Code Quality & Testing foundations

[rucka]

Epic Information

Epic ID: EP-209
Initiative: Quality — Cost · Security · Delivery #201
Theme: Delivery foundations
Epic Owner: Foomakers Product Team
Status: Planning
Priority: P0
Epic Points: 26 (estimated)
Target Release: Slice ① (sequencing R4.7)

Epic Statement

As a team maintaining code quality with pair
I need measurable foundations: centralized lint/format, tracked tech debt, coverage guardrail, TDD on bug fixes, coupling-aware architecture quality
So that quality practices are enforced consistently and debt is visible and prioritized

Epic Context

Delivery pillar foundations (practices, not classification — D17). Design rules consolidated in existing code-design guidelines (D12: no separate anti-pattern catalog). Extends audit #199: consolidated findings become the initial tech-debt backlog.

Business Value & Objectives

Primary Business Goals

1. Goal 1: Shared lint/format config extended per package type; pre-commit hook + pre-push lint (R7.1). pair's own tools/* becomes the reference pattern in KB.
2. Goal 2: Tech debt tracked and prioritized (R7.2): every new debt → Draft item tagged tech-debt P1/P2/P3; never blocks a PR.
3. Goal 3: Incremental coverage (R7.3): baseline → CI guardrail (no regressions) → gradual targets per type.

Success Metrics (KPIs)

• Coverage regressions merged - Target: 0 (guardrail blocks)
  • Measurement method: CI gate on baseline
  • Current baseline: no baseline tracked
• Debt items from audit Tech-debt resolution ledger (2026-04-17 audit) — resolve findings incrementally #199 - Target: 100% findings converted to tagged Draft items
  • Measurement method: backlog count vs findings list
  • Current baseline: findings only in Tech-debt resolution ledger (2026-04-17 audit) — resolve findings incrementally #199 body

Problem Statement & Market Opportunity

Current State

Lint configs exist in pair's monorepo but not as a KB/setup pattern for projects; debt is flagged but has no persistent backlog; no coverage baseline; TDD on bug fixes is policy (CLAUDE.md) but not verified in review.

Target State

setup-gates provisions shared lint config; assess-debt scans (TODO/FIXME/workarounds + design rules from guidelines) and generates Draft items; coverage baseline + guardrail in CI; review checklist verifies the failing-test-first rule on bug fixes.

Solution Overview

Key Capabilities

1. Lint/format centralized (R7.1) — guideline + setup-gates provisioning, per-type overrides (backend/frontend/shared lib), hooks.
2. Tech-debt backlog (R7.2) — from Tech-debt resolution ledger (2026-04-17 audit) — resolve findings incrementally #199 findings; assess-debt scan extension; tags + P1–P3.
3. Coverage baseline + guardrail (R7.3) — configurable targets per type.
4. TDD on bug fixes (R7.4) — red test before fix, verified in review checklist; no obligation for features; test stack = team choice.
5. Design rules consolidation (R6.7, D12) — do/don't form in code-design guidelines + migration items for existing code.

Epic Breakdown

User Stories (High-Level)

Must-Have Stories (P0)

• US: As a maintainer I want design rules consolidated in code-design guidelines (do/don't) + migration plan so that AI stops generating known bad patterns (R6.7)
• US: As a team I want Tech-debt resolution ledger (2026-04-17 audit) — resolve findings incrementally #199 findings converted to tech-debt Draft items + assess-debt scan extension so that debt is a living backlog
• US: As a project I want the shared lint/format config guideline + setup-gates provisioning so that every pair project starts consistent

Should-Have Stories (P1)

• US: As a team I want coverage baseline + CI guardrail so that coverage never regresses
• US: As a reviewer I want the TDD bug-fix check in the review checklist so that fixes prove they address the bug
• US: As a reviewer I want coupling evaluated on three dimensions (integration strength, distance, volatility) on the PR diff and full-scope as a codebase audit so that architecture quality (R7.5) is measurable (Architecture quality: coupling-balance guideline + assess-coupling (diff/full) in review #263)
• US: As a maintainer I want pair's own gate/tooling scripts (docs-staleness, skills-conformance, code-hygiene, check-broken-links, sync-version, benchmark) consolidated into one tested @pair/dev-tools package (TypeScript, tested where the logic warrants it — see ADL 2026-07-13-gate-tooling-code-in-tested-modules.md) so that pair's own tooling is the reference pattern promised by Goal 1 — PR [#209] refactor: consolidate gate/tooling scripts into @pair/dev-tools #330

Epic Acceptance Criteria

• AC1: Bootstrapped project has shared lint config + hooks
• AC2: New debt found in review generates a tagged Draft item; PR not blocked
• AC3: PR reducing coverage below baseline fails the gate
• AC4: Bug fix without a reproducing test ⇒ CHANGES-REQUESTED
• AC5: PR introducing an unbalanced integration (high strength + high distance) in a volatile area gets an Architecture finding with severity and a rebalancing proposal; the same imbalance in a stable area becomes a tech-debt item without blocking the PR

Timeline & Roadmap

Critical Path Dependencies

• Extends: Tech-debt resolution ledger (2026-04-17 audit) — resolve findings incrementally #199 (audit findings as input)

Success Validation

Launch Criteria

• Functionality: All must-have stories completed and tested
• Documentation: Docs site updated for every feature/artifact of this epic
• CLI: apps/pair-cli updated where install/update/distribution is touched

---

Appendix

Related Documentation

• Requirements R7.1–R7.4, R6.7 · Spec G8 in pair-requirements-triage.md · Decision D12 · Extends Tech-debt resolution ledger (2026-04-17 audit) — resolve findings incrementally #199