# Implementation Plan: Quality Gates & Code Hygiene

**Branch**: `031-quality-gates-hygiene` | **Date**: 2026-03-11 | **Spec**: [spec.md](./spec.md)
**Input**: Feature specification from `/specs/031-quality-gates-hygiene/spec.md`

**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/plan-template.md` for the execution workflow.

## Summary

Strengthen the project's automated quality gates by: (1) codifying the early-enforcement principle in the constitution and CLAUDE.md, (2) adding Vitest v8 coverage thresholds with auto-ratchet, (3) enabling Biome's cognitive complexity rule and an additional a11y rule, (4) adding dependency auditing to the check script, and (5) cleaning up all blanket biome-ignore comments and reducing a11y suppressions in combatant-row.tsx. All gates enforce at pre-commit via `pnpm check`.

## Technical Context

**Language/Version**: TypeScript 5.8 (strict mode, `verbatimModuleSyntax`)
**Primary Dependencies**: Vitest 3.2.4, Biome 2.0, Lefthook, Knip, jscpd. New: `@vitest/coverage-v8`
**Storage**: N/A (config/documentation changes only)
**Testing**: Vitest with v8 coverage provider (to be added)
**Target Platform**: macOS/Linux dev environments (pre-commit hooks)
**Project Type**: Web application (React 19 + Vite 6)
**Performance Goals**: N/A — tooling config changes
**Constraints**: All changes must pass `pnpm check` at pre-commit
**Scale/Scope**: 10 files modified, 5 functions refactored for complexity

## Constitution Check

*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

| Principle | Status | Notes |
| --------- | ------ | ----- |
| I. Deterministic Domain Core | PASS | No domain logic changes. `set-initiative.ts` fix is a lint-only refactor preserving identical behavior. |
| II. Layered Architecture | PASS | No layer boundary changes. Refactors stay within their existing layers. |
| III. Clarification-First | PASS | All requirements are explicitly specified by the user. No assumptions needed. |
| IV. Escalation Gates | PASS | All items are in the spec. |
| V. MVP Baseline Language | PASS | Constitution amendment uses PATCH clarification language, not permanent bans. |
| VI. No Gameplay Rules | PASS | No gameplay mechanics involved. |
| Dev Workflow: automated checks | PASS | This feature strengthens the check pipeline. |
| Dev Workflow: CLAUDE.md sync | PASS | CLAUDE.md will be updated to reflect the early-enforcement principle. |
| Dev Workflow: README sync | PASS | No user-facing capability changes — README update not required. |

**Post-Phase 1 re-check**: All gates still pass. The constitution itself is being amended (PATCH), which follows the amendment procedure (propose → update → verify → review → commit).

## Project Structure

### Documentation (this feature)

```text
specs/031-quality-gates-hygiene/
├── plan.md              # This file
├── research.md          # Phase 0 output — technical research
├── data-model.md        # Phase 1 output — config artifacts
├── quickstart.md        # Phase 1 output — implementation guide
└── tasks.md             # Phase 2 output (via /speckit.tasks)
```

### Source Code (repository root)

```text
# Files modified by this feature:
.specify/memory/constitution.md    # PATCH amendment (early enforcement)
CLAUDE.md                          # Add early-enforcement operational note
biome.json                         # Add complexity + a11y rules
vitest.config.ts                   # Add v8 coverage with thresholds
package.json                       # Add @vitest/coverage-v8, update check script
.gitignore                         # Add coverage/ directory

# Refactored for cognitive complexity:
apps/web/src/adapters/bestiary-adapter.ts
apps/web/src/persistence/encounter-storage.ts
scripts/check-layer-boundaries.mjs
scripts/generate-bestiary-index.mjs

# Refactored for biome-ignore hygiene:
packages/domain/src/set-initiative.ts
apps/web/src/components/combatant-row.tsx
```

**Structure Decision**: No new directories or structural changes. All modifications target existing files. The only potential new file is a small `StopPropagation` wrapper component if the combatant-row refactor warrants extraction.

## Complexity Tracking

No constitution violations to justify.