# 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.