initiative/specs/031-quality-gates-hygiene/spec.md

Feature Specification: Quality Gates & Code Hygiene

Feature Branch: 031-quality-gates-hygiene Created: 2026-03-10 Status: Draft Input: User description: "Refine constitution early enforcement principle, add Vitest coverage thresholds, Biome cognitive complexity rule, pnpm audit in check script, fix biome-ignore hygiene, review Biome a11y rules"

User Scenarios & Testing (mandatory)

User Story 1 - Constitution codifies early enforcement (Priority: P1)

A contributor reads the constitution and CLAUDE.md and understands that every automated quality gate MUST run at the earliest feasible enforcement point — currently pre-commit via Lefthook's pnpm check. No gate may exist only as a CI step or manual process.

Why this priority: This principle governs all other items in the feature; without it, the remaining gates lack authoritative backing.

Independent Test: Can be verified by reading the updated constitution and CLAUDE.md and confirming the early-enforcement language is present.

Acceptance Scenarios:

1. Given the constitution's Development Workflow section, When a reader reviews it, Then there is an explicit rule stating all automated quality gates MUST run at the earliest feasible enforcement point (currently pre-commit).
2. Given CLAUDE.md, When a reader reviews it, Then the early-enforcement principle is reflected operationally in the Commands or Conventions section.

---

User Story 2 - Test coverage thresholds prevent regressions (Priority: P1)

A contributor runs pnpm check and coverage is measured automatically. If coverage drops below the configured thresholds (initial: lines 70%, branches 60%), the check fails. Thresholds ratchet upward automatically as coverage improves.

Why this priority: Coverage thresholds are the most impactful new gate — they catch untested code before it reaches the repository.

Independent Test: Can be tested by running pnpm check and verifying coverage is reported and thresholds are enforced.

Acceptance Scenarios:

1. Given the project with current test suite, When a contributor runs pnpm check, Then test coverage is measured using the v8 provider and reported.
2. Given coverage thresholds configured at lines: 70, branches: 60, When a change drops coverage below either threshold, Then pnpm check fails.
3. Given thresholds.autoUpdate: true, When coverage exceeds the configured thresholds, Then the thresholds are automatically ratcheted upward in the config file.

---

User Story 3 - Cognitive complexity catches overly complex functions (Priority: P2)

A contributor writes a function with cognitive complexity exceeding 15. Biome flags it during pnpm check, prompting the contributor to refactor.

Why this priority: Directly supports the Deterministic Domain Core principle by keeping pure functions small and understandable, but is less impactful than coverage gates.

Independent Test: Can be tested by writing a function with complexity > 15 and verifying Biome reports an error.

Acceptance Scenarios:

1. Given Biome configured with noExcessiveCognitiveComplexity at threshold 15, When pnpm check runs against a function exceeding that threshold, Then Biome reports a lint error.
2. Given all existing code in the repository, When the rule is enabled, Then no existing code violates the threshold (or violations are addressed).

---

User Story 4 - Dependency audit catches known CVEs (Priority: P2)

A contributor runs pnpm check and known high-severity dependency vulnerabilities are flagged before commit.

Why this priority: Security hygiene is important but the blast radius is smaller than coverage or complexity — it catches external dependency issues rather than code quality.

Independent Test: Can be tested by running pnpm check and verifying audit runs with --audit-level=high.

Acceptance Scenarios:

1. Given pnpm audit --audit-level=high is wired into pnpm check, When a contributor runs pnpm check, Then the audit step executes.
2. Given no high-severity advisories exist in the current dependency tree, When pnpm check runs, Then the audit step passes.
3. Given a high-severity advisory exists, When pnpm check runs, Then the check fails and the advisory is reported.

---

User Story 5 - Biome-ignore comments are hygienic (Priority: P2)

All biome-ignore comments in the codebase specify the exact rule being suppressed. Blanket biome-ignore lint: comments are eliminated. The number of total ignores is reduced where possible.

Why this priority: Code hygiene — blanket ignores silently suppress future rules and mask technical debt.

Independent Test: Can be tested by searching the codebase for biome-ignore comments and verifying none use blanket lint: form.

Acceptance Scenarios:

1. Given packages/domain/src/set-initiative.ts line 65, When the blanket biome-ignore lint: is removed, Then the code is refactored so no ignore is needed (e.g., inline undefined checks or narrowing).
2. Given apps/web/src/components/combatant-row.tsx with 8 a11y ignores (4 pairs of useKeyWithClickEvents + noStaticElementInteractions), When the clickable wrapper divs are refactored, Then the number of biome-ignore comments is reduced (ideally eliminated) by using semantic elements or a shared wrapper component.
3. Given the full codebase, When searched for biome-ignore lint: (blanket form without a specific rule), Then zero results are found.

---

User Story 6 - Biome a11y rules are comprehensive (Priority: P3)

The Biome configuration explicitly enables relevant non-recommended a11y rules that benefit this React UI app, beyond what recommended: true provides by default.

Why this priority: Incremental improvement — the app already has recommended: true covering stable a11y rules. Non-recommended rules add coverage but are lower urgency.

Independent Test: Can be tested by reviewing biome.json and verifying a11y nursery rules are explicitly listed.

Acceptance Scenarios:

1. Given Biome 2.0 with recommended: true, When a developer reviews biome.json, Then relevant non-recommended a11y rules are explicitly enabled.
2. Given the newly enabled rules, When pnpm check runs against the existing codebase, Then no new violations are introduced (or all violations are fixed).

---

Edge Cases

• What happens when pnpm audit finds a vulnerability in a dev-only dependency? The --audit-level=high flag filters by severity, not dependency type — dev-only high-severity CVEs still fail the check.
• What happens when thresholds.autoUpdate writes to the config file? The updated thresholds file should be committed by the contributor as part of their change.
• What happens if Biome nursery rules produce false positives? Individual false positives can be suppressed with rule-specific biome-ignore comments (never blanket ignores).
• What happens if pnpm audit is slow or unavailable offline? The audit command may fail if the registry is unreachable; contributors working offline may need to skip the check temporarily (acceptable trade-off for pre-commit enforcement).

Requirements (mandatory)

Functional Requirements

• FR-001: The constitution's Development Workflow section MUST include an explicit early-enforcement principle stating all automated quality gates run at the earliest feasible enforcement point.
• FR-002: CLAUDE.md MUST reflect the early-enforcement principle operationally.
• FR-003: Vitest MUST be configured with the v8 coverage provider and initial thresholds of lines: 70, branches: 60.
• FR-004: Vitest coverage MUST have thresholds.autoUpdate: true enabled so thresholds ratchet upward.
• FR-005: Coverage enforcement MUST be wired into pnpm check.
• FR-006: Biome MUST have noExcessiveCognitiveComplexity enabled with the default threshold (15).
• FR-007: pnpm audit --audit-level=high MUST be added to the pnpm check script.
• FR-008: The blanket biome-ignore lint: in set-initiative.ts MUST be replaced with either a rule-specific ignore or (preferably) a code fix that eliminates the need for any ignore.
• FR-009: The 8 a11y ignores in combatant-row.tsx MUST be reduced by refactoring clickable wrapper divs to use semantic elements or a shared wrapper component.
• FR-010: No biome-ignore lint: (blanket form) may exist anywhere in the codebase after implementation.
• FR-011: Relevant non-recommended Biome a11y rules MUST be explicitly enabled in biome.json.
• FR-012: All changes MUST pass pnpm check after implementation.

Assumptions

• The v8 coverage provider is compatible with the existing Vitest setup (Vitest 3.x supports v8 natively).
• Initial coverage thresholds (lines: 70, branches: 60) are conservative enough that the current test suite passes without needing to add tests.
• Biome 2.0's noExcessiveCognitiveComplexity default threshold of 15 is reasonable for existing code — no existing functions exceed it.
• The project's current dependencies have no high-severity advisories (pnpm audit passes cleanly).
• Non-recommended Biome a11y rules are stable enough for pre-commit enforcement and won't produce excessive false positives.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: pnpm check enforces all six gate types: unused code (knip), formatting/linting (biome), type checking (tsc), tests with coverage (vitest), copy-paste detection (jscpd), and dependency audit (pnpm audit).
• SC-002: Test coverage thresholds are enforced and automatically ratchet upward — no manual maintenance needed.
• SC-003: Zero blanket biome-ignore lint: comments remain in the codebase.
• SC-004: The total number of biome-ignore comments in combatant-row.tsx is reduced from 8 to 4 or fewer.
• SC-005: The constitution and CLAUDE.md explicitly document the early-enforcement principle.
• SC-006: All existing code passes pnpm check with the new gates enabled — no regressions.