fraqtal/agentic-dev
Template
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(coverage): sync docs to shipped state + wire sandcastle prompts

Browse Source 
Closes the staleness gap after the 10-commit coverage epic shipped.

Doc sync (item 1 from the user's choice):
  - CLAUDE.md Quick Start: adds pnpm coverage:aggregate / coverage:diff
    / mutate to the command listing
  - CLAUDE.md: new "Sibling architecture: coverage (ADR-020)" section
    after the conformance gate table — captures the 4-layer table +
    points at docs/guides/coverage.md + ADR-020 + says agents must run
    coverage:diff before reporting complete
  - AGENTS.md preamble: now lists coverage as a parallel multi-latency
    quality system alongside conformance, with the same gate / latency
    framing
  - PRD frontmatter: status draft -> shipped + shipped date +
    shipping-commits list (all 10 SHAs anchoring the trace)
  - PRD findings table: each row gets a Resolution column citing the
    commit that closed it; conclusion text updated to past tense
  - ADR-020 implementation phasing: rewritten as a status table with
    each step linked to the commit that shipped it + Boot-time
    assertFeatureConformance explicitly marked Deferred with rationale
  - docs/guides/coverage.md: removed "Boot wiring lands in the next
    story" line; replaced with the deferral rationale + clarified
    that two readers (vitest, coverage:diff) consume the manifest

Sandcastle prompts (item 2 from the user's choice):
  - .sandcastle/implementer.prompt.md: new "Coverage gates" section
    after the conformance-gates list, requiring `pnpm test --coverage`,
    `pnpm coverage:aggregate`, and `pnpm coverage:diff` to all pass
    before reporting `complete`. Machine-readable JSON shape of
    coverage:diff documented (status / uncovered[] / kind enum), with
    explicit instructions on how to interpret each kind. Allowlist
    expansion requires justification + test.
  - .sandcastle/reviewer.prompt.md: AC coverage relabeled to "AC
    coverage (acceptance criteria, not test coverage)" to disambiguate;
    new check #7 "Coverage gates (ADR-020)" requiring CI's
    Coverage — diff (L1) step green + per-layer thresholds met +
    no silent allowlist expansion + manifest band drift detection.

Effect: future agent runs through sandcastle now treat coverage as a
first-class blocking gate, parallel to conformance. PRs no longer
discover coverage failures only via CI; the implementer is required
to check before reporting done, and the reviewer is required to
verify.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Danijel Martinek
2026-05-13 16:47:16 +02:00
parent bf0b049583
commit fc27eef6eb
8 changed files with 82 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
CLAUDE.md
View File

@@ -12,6 +12,9 @@ pnpm lint # ESLint (incl. 8 conformance/* rules)
pnpm conformance # Cross-feature event closure
pnpm fallow # Whole-codebase: dead exports, dupes, complexity
pnpm fallow:audit # AI-change audit (run before commits)
pnpm coverage:aggregate # Merge per-package lcovs -> coverage/lcov.info + summary.json (L2)
pnpm coverage:diff # Cover-the-diff gate; JSON to stdout (L1, ADR-020)
pnpm mutate # Stryker mutation testing on entities + use-cases (L3, on-demand)
pnpm turbo boundaries # Workspace dependency graph
pnpm work status # docs/work/ epic + story state
pnpm work next # Next ready story
@@ -72,6 +75,19 @@ The five conformance ESLint rules: `feature-must-have-manifest` (error), `usecas
See `docs/architecture/agent-first-workflow-and-conformance.md` for the full design and `docs/guides/conformance-quickref.md` for the day-to-day reference.
### Sibling architecture: coverage (ADR-020)
Coverage runs in parallel to the 5-gate conformance system above — same multi-latency philosophy, different signal. Each feature's `feature.manifest.ts` declares a `coverage.bands` section that vitest (test-time), `pnpm coverage:diff` (CI/agent-loop), and `pnpm mutate` (nightly) all read from. Four layers:
| Layer | Catches | Surface |
| ---------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------- |
| **L0** Per-layer vitest thresholds | Drift below declared bands (entities/use-cases/controllers at 100%) | `pnpm test -- --coverage` |
| **L1** Diff coverage | Changed line not exercised by tests | `pnpm coverage:diff` — CI-gated on PRs + dispatch post-task |
| **L2** Aggregate trend | Codebase coverage drifted over time | `pnpm coverage:aggregate` → committed `coverage/summary.json` |
| **L3** Mutation testing | Tests that exist + execute the code but assert nothing | `pnpm mutate` — on-demand + nightly GH Action |
See `docs/guides/coverage.md` for the cookbook and ADR-020 for the full rationale. Agents running in sandcastle: run `pnpm coverage:diff` before reporting `complete` — the implementer and reviewer prompts enforce this.
## Key Conventions
- **Relative imports in `src/`** — Source files use relative paths (`../repositories/...`), not `@/` alias