docs(coverage): cookbook guide + feature generator scaffolds coverage:

Adds the day-to-day cookbook for the 4-layer coverage architecture
(ADR-020) and threads it into the discovery path:

docs/guides/coverage.md (new):
  - 4 layers at a glance + when each fires
  - Single-source-of-truth pattern (feature.manifest.ts coverage:
    section) and the three readers (vitest, assertFeatureConformance,
    coverage:diff)
  - Daily workflow: pnpm test --coverage -> aggregate -> diff
  - How to read a failure (stderr human + stdout JSON examples)
  - How to fix uncovered slices (TDD walkthrough)
  - The full allowlist (test files, configs, docs, scripts, dev
    tooling, per-feature excludes)
  - Adjusting bands (manifest-first, when to override vitest)
  - CI behavior (two workflows: validate + coverage-snapshot)
  - Reading the committed trend via git log -- coverage/summary.json
  - Mutation testing primer (L3, opt-in, scope, lands in next story)
  - Troubleshooting

CLAUDE.md Read First gets the new guide pinned between audit and
template-tiers, with the L0-L3 layer summary inline so agents see the
shape at a glance.

Feature generator updates (turbo/generators/templates/feature/):
  - feature.manifest.ts.hbs: new `coverage:` block at <gen:coverage>
    anchor scaffolded with the documented defaults + mutationTargets
  - vitest.config.ts.hbs: now uses vitestThresholdsFromBands(
    DEFAULT_COVERAGE_BANDS) instead of the duplicated literal — new
    features ship conformance-compliant by default

Next features generated via `pnpm turbo gen feature` are coverage-
aware from the first commit: bands declared in manifest, vitest
config consumes the helper, no duplication to drift.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-05-13 14:15:01 +02:00
parent 15db9c48cb
commit f4254aae48
4 changed files with 253 additions and 24 deletions

View File

@@ -53,6 +53,7 @@ Turborepo + pnpm monorepo organized by vertical features. Each feature (`auth`,
- `docs/guides/events-and-jobs.md` — publish/consume/schedule cookbook (cross-feature events + background jobs; _requires `gen core-package events`_)
- `docs/guides/realtime.md` — Socket.IO channels, broadcasts, handlers (_requires `gen core-package realtime`_)
- `docs/guides/audit-and-compliance.md` — DPA-compliant audit logging cookbook (_requires `gen core-package audit`_)
- `docs/guides/coverage.md` — 4-layer coverage cookbook (L0 vitest thresholds, L1 `pnpm coverage:diff`, L2 aggregate, L3 mutation; ADR-020)
- `docs/architecture/template-tiers.md` — must-have vs optional packages and how to scaffold the optionals
## Conformance system