@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/engineering/ensure-coverage/references/depth/characterization.md

@@ -0,0 +1,68 @@
+# Depth: Characterization — pin existing behavior before you change it
+
+> Read when: a change **modifies existing behavior** (edits/deletes lines in a non-test source file) rather than adding a brand-new surface. Sibling: [grading.md](grading.md) (how each obligation is graded), [mock-policy.md](mock-policy.md) (the boundary). New-surface work is TDD red→green; *this* is the obligation for touching code that already runs in production.
+
+Michael Feathers' rule: *"Characterization tests document the actual behavior of the code, not the intended behavior."* The common agent failure mode: it refactors or "fixes" a function, the existing tests stay green (they never covered the changed path), and an **observable behavior silently shifts**. A green suite after the change proves nothing if no test pinned the behavior *before* it.
+
+So a modification carries a depth obligation a fresh feature does not: **before you change existing behavior, write a test that captures what the code does today, and make it pass against the unchanged tree.** That test becomes a boundary the change cannot silently cross — the seam ([below](#seams-where-to-pin)) at which you alter behavior deliberately.
+
+## The obligation: when it is owed
+
+A change owes a characterization test when **all** hold:
+
+- It **edits or removes** existing lines of a non-test **source** file (a pure addition into a new file, or appended-only code, is new behavior → TDD path).
+- The touched code has **observable behavior** — return value, durable-state effect, emitted event, HTTP contract, rendered output. (Internal-only renames with no behavioral surface don't.)
+- The surface is **non-trivial** — anything carrying a Surface Baseline floor, or logic a user/caller depends on.
+
+When owed, the test must: **(1) capture actual, not intended, behavior** including quirks/bugs (if current behavior is wrong, characterize it *then* fix it in a separate declared step); **(2) pass on the pre-change tree** (GREEN on `HEAD~`/base before your edit — capture as evidence); **(3) still pass after the change**, unless the change is a declared intended behavior change.
+
+## When it is waived
+
+Mark the waiver explicitly in the PR's evidence, never silently:
+
+- **Already pinned** — an existing behavior test covers the exact changed path and still passes unchanged. Cite it (`file:line`); that test *is* the characterization.
+- **Declared intended behavior change** — deliberately alters observable behavior per an AC/bug brief. The obligation inverts: update/author the test to assert the **new** behavior, and the diff must show the old assertion changing to the new (a behavior change with no test delta is the suspicious case). Cite the AC.
+- **Trivial / generated / non-behavioral** — formatting, comments, type-only edits, generated code with no behavior delta.
+
+## The `@characterizes` convention
+
+Tag a characterization test so the gate can resolve it, parallel to `@covers`:
+
+```js
+// @characterizes <surface-id>   // pins prior behavior of a surface being modified
+// @covers <surface-id>          // (a characterization test usually also @covers it)
+// @level <level>
+```
+
+`@characterizes` is the signal that *this* test exists to hold a modification's behavior boundary. A modifying diff with no `@characterizes` test and no declared waiver is the gap this obligation names.
+
+## Grading
+
+Characterization is a **depth** concern, graded with the [shared vocabulary](grading.md):
+
+- A modifying diff whose changed behavior is pinned by a passing characterization test (or cited pre-existing behavior test) → that surface can reach `Covered` on the normal evidence rules.
+- A modifying diff with **no** characterization test and **no** declared intended-change → `Partial` at best; the reviewer raises the `modifies-existing-behavior` lead (below). Not a hard `Missing` (existing tests may incidentally cover it) — a **lead to adjudicate**, because whether a characterization test is *needed and adequate* is judgment.
+
+## Detection (mechanical) → adjudication (judgment)
+
+The decidable half is mechanical: any non-test source file with **removed/changed** lines emits a `modifies-existing-behavior` **lead** ("look here and verify," never an auto-finding). The reviewer checks for a `@characterizes` test (or a declared change) and adjudicates, citing `file:line`. The reviewer resolves it with a locator, not prose. The split matches the GATE-vs-LEAD line everywhere in this skill: detecting *that behavior changed* is mechanical; deciding *whether the pinning test is adequate* is semantic.
+
+## Seams: where to pin
+
+A characterization test is writable only where you can observe behavior without rewriting the thing you're about to change — a **seam** (*"a place where you can alter behavior without editing the code in that place"*). Pin at the nearest observable seam: the public function's return/throw, the endpoint's HTTP contract, the rendered page's output, the emitted event. If there's no seam, that itself is the finding — introduce one first (extract the call, expose the boundary), pin, *then* change. Do not skip characterization because "it's hard to test as written"; hard-to-pin is the legacy-code smell the obligation exists to surface.
+
+## Fails-first: bug-fix AND feature-AC — prove the test fails when the behavior is broken
+
+The shared property: **a test is evidence for a behavior only if it would go red were that behavior broken.** A green test that passes with *and* without the behavior it claims is **vacuous coverage** — it locks in nothing. Two cases:
+
+**Bug-fix sibling.** A bug fix changes behavior that's *already wrong*, so it owes the inverse of characterization: at least one test demonstrated to **fail on the unfixed code and pass on the fixed code** (RED→GREEN, run in that order), tagged `// @fails-without-fix <surface>`. Reverting the fix must turn the test red. Waive only with a cited reason the failure can't be reproduced in-suite (a tracked `Unverified` manual check, not a silent skip).
+
+**Feature-AC sibling.** The same test applies to a *new feature's* AC, where it's most-missed: a green test cited for an AC clears it only if it would go red were the AC's behavior removed — it exercises the AC's real code path, not a proxy. Recurring vacuous forms:
+- a fixture that **early-returns before the code runs** (a 0-step workflow "proving" a multi-step reset that never executes);
+- a `.fill()`/`setValue` that sets state in one shot and so **masks a re-render/defocus bug** a character-by-character `pressSequentially` would expose;
+- an assertion **pinned to a stand-in value the real producer never emits**;
+- asserting **the mock was called** rather than that the outcome happened.
+
+**Grading the two outcomes** (they differ from [grading.md](grading.md)'s `Unverified`): can't-yet-confirm it would go red → `Unverified` (a warning unless `unverifiedBlocks: true`); confirm it would **still pass** with the behavior gone → `Missing`/`Over-mocked` (a proven-vacuous test is *worse* than unchecked).
+
+The two **decidable** vacuous forms (a swallowed assertion, a fixed timeout) are gated by `lint-tests`; the semantic "would it have been red?" property is verified at review and by running the test against the broken tree. Named incident: the login regression (#237), where a green sweep asserted nothing the bug could trip.

package/skills/engineering/ensure-coverage/references/depth/coverage.config.example.json

@@ -0,0 +1,19 @@
+{
+  "//": "OPTIONAL. The mock-internal-seam lint rule is default-on and zero-tolerance (references/depth/mock-policy.md); a conventional @/-aliased repo needs NO config. Copy this to coverage.config.json at your repo root only to declare non-conventional TOPOLOGY (a monorepo's own package scope, generated dirs to exempt). It cannot disable the gate, and there is no waiver.",
+  "mockPolicy": {
+    "firstPartyAliasPrefixes": [
+      "@/",
+      "~/"
+    ],
+    "firstPartyPackages": [
+      "@your-scope/"
+    ],
+    "externals": [
+      "^@/generated/"
+    ]
+  },
+  "//requirementGlobs": "OPTIONAL. Turns on the acceptance gate: every accepted ADR/PRD under these directories must own a docs/tests/<source>/<id>-*.coverage.yml with `criteria` (or `gapIssue` / `gapDoc` for a tracked gap), unless the document states it has no runtime behavior. Without this key, validate prints 'acceptance gate not enforced'.",
+  "requirementGlobs": {
+    "adr": "docs/adr"
+  }
+}

package/skills/engineering/ensure-coverage/references/depth/grading.md

@@ -0,0 +1,35 @@
+# Depth: Proving Each Obligation
+
+> Read when: grading whether a test actually proves the behavior against real state. Sibling: [mock-policy.md](mock-policy.md) (the boundary principle this grading enforces). Depth grades each `Aligned` row — and each `Orphan surface` carrying a [Surface Baseline Contract](../breadth/surface-baseline.md) floor — by inspecting its actual tests.
+
+The canonical depth failure is **internal interception counted as behavior**: a Playwright `route.fulfill`/`page.route(` faking your own endpoint's response, or any substitute standing in for an internal seam. It makes a surface *look* covered while proving only proxy wiring — the boundary violation the [Mocking Stance](mock-policy.md) forbids. Classify it `Over-mocked`, never `Covered`.
+
+**Separate browser routes from API routes; prove each with its own evidence kind.** Prove an API route (`route.*`) by hitting the endpoint and asserting the HTTP contract, auth, and durable state. Prove a browser route (`page.*`) by driving the rendered page: what it displays, what the user can do, and what happens when they do. Never grade a browser route `Covered` because its backing endpoints are covered (the `/settings/connectors` miss) — a green API test under a page is necessary but never sufficient.
+
+**For any write form, require one test that fills the rendered UI and asserts the mutation end to end** — operator fills the actual form and submits → backend accepts → durable state changes. Keep the render-health watcher attached **through** the submit (compose with `presentation:render-health`, [../presentation/axis.md](../presentation/axis.md)), so an uncaught error / `console.error` / first-party 5xx fired *during* the write fails the test even when the durable-state assertion would pass — the "mutate-health" gap. Do not accept seam tests in its place: a schema endpoint returning fields, a validator rejecting bad input, and an API forwarding a hand-built payload all pass while the rendered form silently drops a backend-required field. This is acute for the **split-contract form**, whose fields come from one source (schema endpoint, config descriptor, generated form spec) and validation from another (the backend contract); only a rendered-form submission proves the form emits a payload the backend accepts.
+
+## Evidence Hierarchy
+
+Do not trust prior coverage documents, audit reports, PR summaries, issue comments, or agent claims as proof of coverage. Treat them only as leads to verify against current code.
+
+Use evidence in this order:
+
+1. Actual test code and assertions.
+2. Test execution evidence: CI logs, local command output, traces, screenshots, or reports.
+3. Runtime/code discovery: routes, endpoints, schemas, public interfaces, and changed code paths.
+4. Prior docs/reports/PR summaries only as context to verify, never as authoritative evidence.
+
+Classify coverage as `Covered` only after inspecting the relevant test file/case and confirming it asserts the required behavior at the required level. CI logs prove execution, not coverage quality. If actual test code cannot be inspected, classify as `BLOCKED` or `Unverified`, never `Covered`.
+
+## Coverage classifications (the shared vocabulary)
+
+A self-declared `@level` is a claim the validator must try to **refute**, and can never alone reach `Covered`. The three terminal states are marked below.
+
+- `Covered` (green, terminal): inspected test code validates the AC at the right level with meaningful assertions and acceptable mock/fake use, **and** the test has been read and marked `verified: true`. A self-declared `@level` alone never reaches it.
+- `Partial`: some behavior is tested, but edge cases, failures, permissions, state, or evidence are incomplete.
+- `Missing`: no meaningful test maps to the AC.
+- `Wrong Level`: test exists but is too shallow for the risk — e.g. unit-only for stateful workflow, API contract, auth, money movement, concurrency, or event behavior.
+- `Over-mocked` (red, terminal): mocks bypass the behavior the AC must prove — a behavior/journey test that intercepts first-party traffic (`page.route`, `route.fulfill`, MSW, first-party fixtures), or a `mutation` journey that never resolves a real durable-state path. Proves only proxy wiring.
+- `Unverified` (yellow, terminal): the level is satisfied statically (or claimed by docs/reports/CI) but nobody has read the test yet. It is a **warning** by default; it blocks only when the user sets `unverifiedBlocks: true`. Marking `verified: true` after reading the test promotes it to `Covered`; no evidence is required unless the user asks for it. The residual variance is over *quality of an existing test*, not *whether a surface exists*.
+- `Excluded`: a human marked the surface out of scope with category + reason and the adapter signals permit it; surfaced in the exclusion census.
+- `BLOCKED`: required source, code, tests, route discovery, environment, or product decision is unavailable.

package/skills/engineering/ensure-coverage/references/depth/mock-policy.md

@@ -0,0 +1,57 @@
+# Mock And Integration Policy (depth)
+
+> Read when: deciding what may be substituted in a test. The boundary principle the [depth grading](grading.md) enforces.
+
+## Mocking Stance
+
+Default to real. The governing principle is **real internals, faked externals, nothing in between**:
+
+- A test substitute is permitted **only at a trust boundary you do not own**: third-party HTTP APIs, payment/KYC providers, email/SMS, the clock, randomness.
+- Everything **inside** your own system runs for real: database, repositories, service layer, internal endpoints, event bus. A substitute for an internal seam is a design smell or coverage gap, not a testing choice.
+- The rule is **two-sided**: don't mock inward, don't reach outward — externals must be replaced by a fake/stub adapter so tests stay deterministic and never call a live third party in CI. "Be pure by calling the real provider" is the opposite failure, also rejected.
+
+The problem we reject is **mock-only coverage of behavior that must be proven against real state** — not the presence of mocks. Fakes/stubs that keep failure-path and edge tests fast and deterministic are good and expected.
+
+## Glossary
+
+- **Dummy**: placeholder passed only to satisfy a signature; never exercised.
+- **Stub**: returns canned data so the test can proceed; no assertions on it.
+- **Spy**: a stub that also records calls, so the test can assert a call happened or did not happen.
+- **Mock**: a pre-programmed object with expectations; the test fails if it is not called exactly as specified (behavior verification of internal call sequences).
+- **Fake**: a real, lightweight working implementation (in-memory DB, fake HTTP adapter) — behaves like the real thing, just not production-grade.
+
+Rule of thumb: prefer **fakes** at external boundaries; use **stub/spy** for failure injection and "was-not-called" assertions; avoid **mocks** that encode internal call sequences — that tests implementation, not behavior.
+
+## Where substitutes are allowed
+
+Use a fake/stub/spy at the external boundary for:
+
+- External provider timeout, decline, malformed response, and rare failure paths (stub/fake the provider adapter).
+- Isolating pure decision logic.
+- Asserting an external provider or side effect was not called after validation failure (spy; there is no real call to observe).
+- Keeping tests deterministic when the external system is not the subject under test.
+
+These are **internal** and are therefore never covered by substitutes alone:
+
+- Database transaction behavior.
+- Idempotency and duplicate delivery.
+- Concurrency/race conditions.
+- Event publishing, outbox, retry, and recovery behavior.
+- Auth, tenant isolation, and permission boundaries.
+- Serialization, schema, and API compatibility.
+- Orchestrator recovery after crash/retry.
+
+Prefer integration tests with real app/service code, real DB or test containers with migrations, queue/pub-sub emulators where practical, fake external provider adapters, and assertions on final durable state, emitted events, and externally visible outcomes.
+
+## Mechanized gate: `mock-internal-seam` (zero-tolerance)
+
+The decidable core of the stance is a hard gate, because over-mock is the failure mode that shipped a production incident behind green tests. The trick that makes it decidable is the **externals-allowlist inversion**: internal seams are unbounded, but the set of things that may legitimately be faked is small and known. So a mock whose target resolves to first-party code is a defect; anything on the declared externals allowlist, a bare npm package, or the stdlib is exempt.
+
+- **Default-on, no waiver, no grandfathering.** Config only declares topology; it cannot turn the gate off. A believed false positive is fixed by declaring the truth in `coverage.config.json`, never by waiving.
+- **Both lanes.** Diff-scoped for new seams, whole-tree for inherited ones; a tree with existing over-mock stays red until it is removed.
+- **Three resolutions, and "keep it" is not one:** replace with a real-boundary test, fake only the external behind it, or **delete** the test. Over-mock is worse than no test: an untested route is an honest gap, an over-mocked one is dishonest green. Deletion reverts the surface to its honest breadth status (`Missing` or `Excluded`).
+- **In audit mode, run it whole-tree from this skill against the target repo** and count every hit as an `Over-mocked` row and a no-ship contributor. A missing `coverage.config.json` means "run on defaults", not "not applicable"; the scripts' absence from the audited repo means nothing.
+
+What stays a review lead: whether a real-boundary sibling exists, shallow assertions, semantically wrong fakes. The gate proves the decidable shell; the reviewer judges the rest. The ledger also reports an over-mock *rate* as a trend signal; the merge bar stays "count is zero".
+
+CLI, rules, and the `coverage.config.json` topology keys: [`scripts/README.md`](../../scripts/README.md).

package/skills/engineering/ensure-coverage/references/depth/test-smells.md

@@ -0,0 +1,39 @@
+# Depth: Test smells — the diagnostic vocabulary and where each is enforced
+
+> Read when: deciding whether a smell belongs in a blocking lint rule or a review lead, or turning a test-quality finding into a coverage grade. Sibling: [grading.md](grading.md) (the coverage classifications), [mock-policy.md](mock-policy.md) (the boundary).
+
+**Judging one test is `test-quality`'s job.** Its seven principles and labels (`Not coverage`, `Weak`, `Redundant`, `Lead`) are the single bar for whether a test catches real bugs; this file does not restate them. It maps each smell to where it is enforced, and each test-quality label to the coverage grade it produces (end of file).
+
+A passing test is not automatically a good test. The classic catalog (Meszaros' *xUnit Test Patterns*, Martin's FIRST) names the ways a green suite still fails its job. Each smell maps to an enforcement point — and to **whether it is mechanically decidable (a gate) or judgment (a lead).** Same dividing line [lint-tests](../../scripts/lint-tests.mjs) draws everywhere: a check blocks only if a legitimate test could never trip it; otherwise it's a lead the reviewer adjudicates.
+
+| Smell | What it is | Decidable? | Enforced as |
+|---|---|---|---|
+| **Erratic** (flaky) | Passes/fails non-deterministically — usually a fixed sleep instead of an explicit wait | **Yes** (the sleep forms) | **Gate**: `lint-tests` `no-fixed-timeout`. Genuine un-sandboxable flake → `@quarantine` lane (runs, non-blocking, graded `Unverified`), never `test.skip` ([test-strategy.md](../process/test-strategy.md)) |
+| **Missing Assertion** | A test that runs but proves nothing | **Partly** | **Gate** for the decidable floors — an **empty body** (`it('x', () => {})`): `lint-tests` `no-empty-test`; and an **assertion whose rejection is swallowed** by a chained `.catch(...)` so it can never fail (`expect(...).not.toBeVisible().catch(() => {})`): `lint-tests` `no-swallowed-assertion`. **Lead** for the rest: a test with statements but no assertion *may still assert through a helper*, so "no `expect`/`assert` token" is not zero-FP — the reviewer reads it (`depth.asserts-something` checklist row) |
+| **Slow** | Violates FIRST's *Fast* — too slow to run every loop | **No** (runtime is environment-sensitive) | **Lead**: a review observation, not a blocking gate — a threshold that fails on a loaded CI runner gets disabled. Flag a test that is slow *for its tier* (a unit test doing real IO, a journey with avoidable waits) and push it down the pyramid or fix the wait |
+| **Fragile** | Breaks on unrelated/implementation changes — couples to structure, not behavior | **No** | **Principle**, not a gate: *test observable behavior, not internal structure* (test-quality principle 1). A test asserting private call-order/shape is the smell; a reviewer judgment |
+| **Obscure** | You can't tell what it tests from reading it — non-DAMP name, hidden setup | **No** | **Lead**: the reviewer checks the test name describes the behavior it asserts (DAMP — Descriptive And Meaningful Phrases), and that a failure message would point at the cause |
+| **Over-mocked** | Mocks bypass the behavior under test (first-party interception) | **Yes/Lead** | **Gate + lead**: ledger `Over-mocked` classification + `lint-tests` `mock-internal-seam` ([grading.md](grading.md), [mock-policy.md](mock-policy.md)) |
+
+## The gate-vs-lead split, stated once
+
+- **Missing Assertion** is the instructive case. Its decidable floor — a literal empty test body — is a gate (`no-empty-test`), because nothing legitimate is an empty-bodied `it(...)`. But the *general* form ("has code, asserts nothing") can't be a zero-FP gate: a test may assert entirely through a helper (`await verifyDashboard(page)`), so flagging "no `expect` on the test's own lines" would false-block it. That residual is a **lead** — the reviewer reads the test and the helper.
+- **Slow** stays a lead for an orthogonal reason — not false positives but **non-determinism of the signal**: the same test's wall-clock varies with the runner. A hard threshold is enforcement built on sand.
+
+## What the reviewer does with the leads
+
+For the `lead` smells above, the reviewer carries them as named checks, each "look here and verify," resolved with a `file:line` + verdict — never prose. A smell that later becomes mechanizable is promoted to a `lint-tests`/ledger rule, the same promotion path every other lead follows.
+
+## From a test-quality label to a coverage grade
+
+A surface's grade comes from the best test that maps to it, after test-quality has judged that test:
+
+| test-quality label on the proving test | Coverage grade for the surface |
+|---|---|
+| clean (no finding) | `Covered` once marked read (`verified: true`), else `Unverified` |
+| `Not coverage` because a first-party fake hides the behavior (principle 3) | `Over-mocked` |
+| `Not coverage` for any other reason (text match, tautology, can never fail) | `Missing` — the test counts as zero proof |
+| `Weak` (proves less than its name, or at too low a level) | `Partial`, or `Wrong Level` when the level is the gap |
+| `Redundant` | no change; the grade comes from the test it duplicates |
+| `Lead` | no change until the lead is confirmed or cleared |
+

package/skills/engineering/ensure-coverage/references/enforcement/ci-contract.md

@@ -0,0 +1,44 @@
+# CI Contract: Golden-Path Smoke Only
+
+> Read when: the user asks what this skill should require, wire, or audit in CI.
+
+Curated golden-path smoke is the **only CI gate supported by this skill**. The coverage ledger, inventory freshness, presentation sweep, broad E2E suite, test lint, over-mock scan, design parity, and quarantine expiry remain local or review-time evidence. Do not propose, require, wire, or audit them as CI gates.
+
+## What smoke proves
+
+Smoke drives a small, human-curated contract (`golden-paths.json`) of do-not-ship journeys against the real running app. It proves those paths are alive through their owned internals:
+
+- start from a real user entry point;
+- use a real browser for browser journeys;
+- do not intercept first-party requests or replace the database or service layer;
+- seed deterministic test state and fake only external providers;
+- pass only on ALIVE: `fail` is DEAD, and `blocked`, `cannot-run`, or `missing` is CANNOT-RUN;
+- keep the contract deliberately small enough to run on every PR.
+
+Smoke is liveness, not comprehensive coverage. A green smoke run does not prove every acceptance criterion, every route's presentation floor, tenant isolation, concurrency, recovery, or the quality of the broader test suite. Those remain obligations graded by the coverage audit.
+
+## Reference command
+
+The `golden-path` skill owns the job. On GitHub Actions it generates the workflow from the repo's `golden-paths.json`; elsewhere a job runs the engine copy it puts in the repo:
+
+```bash
+node scripts/golden-paths/golden-path.mjs run --profile pr-local --boot
+node scripts/golden-paths/golden-path.mjs verdict --profile pr-local
+```
+
+`verdict` exits 0 only on ALIVE; that step is the gate.
+
+## Checking smoke wiring
+
+Run `ci-audit.mjs` only when the user asks to audit CI:
+
+```bash
+node <ensure-coverage>/scripts/ci-audit.mjs \
+  --files .github/workflows/ci.yml,cloudbuild.yaml
+```
+
+It reports the smoke check as `present`, `warn-only`, or `absent`. It does not inspect or recommend any other CI gate. `--adoption` emits a focused issue body for adding or repairing smoke only.
+
+## Production boundary
+
+Do not run mutating smoke against production. Release smoke is read-only against a zero-traffic candidate before traffic shifts. A smoke run after traffic shifts is monitoring, not a release gate.

package/skills/engineering/ensure-coverage/references/examples/coverage-ledger.md

@@ -0,0 +1,110 @@
+# Coverage Ledger: Worked Example
+
+> Read when: setting up or explaining the ledger's three layers and you want a concrete file layout to copy.
+
+A concrete shape for the breadth-axis Coverage Ledger specced in [../breadth/coverage-ledger.md](../breadth/coverage-ledger.md). Paths and command names are illustrative — adapt to the repo. The pattern is what matters: a **generated inventory** from code, a **curated layer authored one file per requirement**, and a **generated aggregation** that dedups by surface and computes status.
+
+## Why it exists
+
+A test-outward audit (mock census → mocked files → gaps) cannot find a surface with no tests — absence produces no signal. The ledger flips direction: enumerate obligations from requirements *and* code, reconcile, let mismatches surface the gaps. The motivating case: a `/settings/models` page with accepted ADRs and a live route, whose only "tests" used Playwright `route.fulfill` to fake the response — proxy wiring counted as coverage. The ledger forces the surface to be owned and discovered; the depth axis then grades it `Over-mocked`.
+
+## Layout
+
+```
+docs/tests/adr/0008-org-model-allowlist.criteria.md      # ACs for the ADR
+docs/tests/adr/0008-org-model-allowlist.coverage.yml     # this ADR's owned surfaces
+docs/tests/prd/<slug>.coverage.yml
+docs/tests/_generated/surface-inventory.json             # discovered from code
+docs/tests/_generated/coverage-index.json                # computed aggregation
+```
+
+## Layer 1 — generated inventory (never hand-edited)
+
+Regenerated from routers/migrations/event registry, one entry per surface. The adapter emits `class` (mechanical) and `reachability`; the baseline floor is computed from `(kind, class)` **before any curated file exists**.
+
+```json
+// docs/tests/_generated/surface-inventory.json
+{ "surfaces": [
+  { "id": "/settings/models", "kind": "route", "class": "mutation", "reachability": "reachable" },
+  { "id": "/internal/debug-panel", "kind": "route", "class": "read", "reachability": "guarded" },
+  { "id": "/api/settings/model-allowlist", "kind": "api", "class": "mutation" },
+  { "id": "model_allowlist", "kind": "table" }
+] }
+```
+
+## Layer 2 — curated coverage, one file per requirement (hand-maintained)
+
+Each file declares only the surfaces that requirement **owns**, their required level, and the criteria link. **No status field** — so multiple owners of a surface can never disagree.
+
+```yaml
+# docs/tests/adr/0008-org-model-allowlist.coverage.yml
+criteria: docs/tests/adr/0008-org-model-allowlist.criteria.md
+surfaces:
+  "/settings/models":
+    requiredLevels: [pg-api, browser-journey, no-secret-assertion]
+  "/api/settings/model-allowlist":
+    requiredLevels: [pg-api]
+```
+
+A second requirement (`0030-model-dispatch.coverage.yml`) can own `/settings/models` too; `aggregate` unions their `requirementRefs` and takes the strictest level.
+
+## Evidence — declared by tests, not hand-listed
+
+Tests say what they prove with a `@covers` annotation (plus optional `@level`), so curated files never carry rot-prone paths. A test that fakes its own endpoint is detected as first-party interception → `Over-mocked`:
+
+```ts
+// apps/web/e2e/models.spec.ts
+// @covers /settings/models
+// @level browser-journey
+test('models page', async ({ page }) => {
+  await page.route('**/api/**', (r) => r.fulfill({ body: '{}' })) // -> Over-mocked
+})
+```
+
+## Layer 3 — generated aggregation (never hand-edited)
+
+Merges every curated file by surface, unions `requirementRefs`, takes the strictest level, diffs against the inventory, maps `@covers` → surface, and **computes** status.
+
+```jsonc
+// docs/tests/_generated/coverage-index.json
+{
+  "/settings/models": {
+    "requirementRefs": ["adr:0008", "adr:0030"],
+    // every route also auto-carries the presentation floor (render-health + spatial + perceivability + reachability + temporal)
+    "requiredLevels": ["pg-api", "browser-journey", "no-secret-assertion", "presentation:render-health", "presentation:spatial", "presentation:perceivability", "presentation:reachability", "presentation:temporal"],
+    "alignment": "Aligned",
+    "depthStatus": "Over-mocked"          // computed: only route.fulfill tests exist
+  },
+  "/internal/debug-panel": {
+    "requirementRefs": [],
+    "requiredLevels": ["browser-journey", "presentation:render-health", "presentation:spatial", "presentation:perceivability", "presentation:reachability", "presentation:temporal"],
+    "alignment": "Orphan surface",         // warn: owned by no curated file
+    "depthStatus": "Missing"               // error: baseline floor unmet
+  }
+}
+```
+
+`/internal/debug-panel` shows the decoupling: `Orphan surface` is only a **warn** (nobody owns it), but its baseline floor is still graded — `Missing` is the failing finding. To exclude it a curated file adds `exclude: { category: internal, reason: "..." }` — honored because it is a `read` route, but **rejected** if it were a `reachable` `mutation`.
+
+## Alignment statuses (computed)
+
+- `Aligned` — requirement ↔ surface present; grade depth next.
+- `Orphan surface` — surface in inventory, owned by no curated file (`inventory − union(curated)`). A **warn**; the baseline floor is still enforced via depth status.
+- `Excluded` — human-declared out of scope (category + reason), permitted by the reachability/class gate; printed in the census.
+- `Unrealized requirement` — a curated surface absent from the inventory.
+- `Stale link` — a curated surface or criteria link points at something gone.
+
+Rows carrying a baseline floor (Aligned or Orphan) are graded by the depth classifications ([../depth/grading.md](../depth/grading.md)). Internal surfaces (`table`/`event`/`job`) instead resolve to `Reached` or `Dead`. `Covered` requires the test to be read and marked `verified: true`; `Unverified` is a warning by default and blocks only with `unverifiedBlocks: true`.
+
+## How this caught `/settings/models`
+
+1. The inventory adapter lists the route and its APIs/tables.
+2. ADR-0008 and ADR-0030 each own it; `aggregate` merges them into one row, strictest level `pg-api + browser-journey` (plus the auto-applied presentation floor).
+3. `validate` resolves status from tests: only a `route.fulfill` test exists → `Over-mocked`; required `pg-api`/`browser-journey` evidence is `Missing`.
+
+And **even with no ADR at all**: the adapter tags `class: mutation`, the Surface Baseline Contract auto-applies a `browser-journey` floor, and the same `route.fulfill`-only test resolves to `Over-mocked` → the gate fails. The organically-added, un-ADR'd route closes by default.
+
+## Presentation (worked shapes)
+
+Every `kind: route` auto-carries the presentation floor on top of `browser-journey`; a real-browser spec tags each level it proves (`// @level presentation:spatial`, etc.) and calls the corresponding assertion (`assertNoHorizontalOverflow`, `assertContrast`, `assertTargetSizes`/`assertFocusVisible`, `assertNoFirstPartyShift`). A DOM-only test tagged with a presentation level grades `Over-mocked`; a `browser-journey` with no such checks leaves the level `Wrong Level`. Full instrument list and failure modes: [../presentation/axis.md](../presentation/axis.md).
+

package/skills/engineering/ensure-coverage/references/examples/refund-flow.md

@@ -0,0 +1,35 @@
+# Refund Flow Test Criteria Example
+
+> Read when: writing a criteria doc for money movement and you want a worked test matrix to pattern on.
+
+A minimal worked criteria doc for a money-movement feature — shows ACs and a risk-classified test matrix. (Template: [../process/output-template.md](../process/output-template.md).)
+
+## Example PRD
+
+Merchant can request a refund for a settled payment. System validates eligibility, creates a refund record, calls the provider, updates payment/refund status, and emits refund events.
+
+## Acceptance Criteria
+
+- AC1: Merchant can refund a settled payment for an amount ≤ remaining refundable amount.
+- AC2: Refund rejected if payment is not settled.
+- AC3: Refund rejected if amount exceeds remaining refundable amount.
+- AC4: Duplicate request with the same idempotency key returns the original refund, creates no second refund.
+- AC5: Provider accepts → status `PROCESSING`, `refund.created` emitted.
+- AC6: Provider rejects → status `FAILED`, normalized provider error stored.
+- AC7: Remaining refundable amount updates only after successful creation.
+- AC8: Unauthorized merchant cannot refund another merchant's payment.
+- AC9: System recovers safely if the provider call succeeds but event publish fails.
+- AC10: Refund APIs return stable error codes, not raw provider/internal errors.
+
+## Test Matrix (representative rows)
+
+| Scenario | ACs | Test Level | Setup/Input | Assertions | Evidence |
+|---|---|---|---|---|---|
+| Valid partial refund | AC1, AC5, AC7 | Integration/API | Settled payment, amount < remaining | Refund row created, `PROCESSING`, provider called once, event emitted, remaining updated | CI integration test |
+| Duplicate request | AC4 | Integration | Same merchant/payment/idempotency key twice | One refund row, one provider call, same response | CI integration test |
+| Unauthorized merchant | AC8 | API/security | Merchant B refunds Merchant A's payment | `403`/`404`, no provider call, no refund row | CI API/security test |
+| Provider hard decline | AC6, AC10 | Integration + fake provider | Provider returns decline | `FAILED`, normalized error stored, no success event | CI integration test |
+| Event publish failure | AC5, AC9 | Integration/recovery | DB commit succeeds, publish fails | Outbox retry emits event, no duplicate refund/provider call | CI recovery test |
+| Concurrent refunds | AC3, AC4, AC7 | Integration/concurrency | Two requests race the same remaining amount | Valid total only, no over-refund | CI concurrency test |
+
+Money/security ACs (AC1, AC4, AC7, AC8) are **never mock-only**, even with approval — they require integration/API/journey evidence against real state ([../process/test-strategy.md](../process/test-strategy.md)). The provider is the one external faked with a fake adapter; the DB, idempotency, concurrency, and outbox run for real.

package/skills/engineering/ensure-coverage/references/presentation/axis.md

@@ -0,0 +1,64 @@
+# Presentation Floor (browser routes)
+
+> Read when: working any `presentation:*` invariant. Sibling: `e2e-test/references/presentation-sweep.md` (the runner and the result shape it emits). This skill *grades* the axis; the `e2e-test` sweep *runs* it.
+
+The **Presentation** axis (third axis) rides the [Surface Baseline Contract](../breadth/surface-baseline.md) machinery as a per-route floor. Every live browser route auto-carries a presentation obligation *on top of* its `browser-journey` floor, checked at the viewport floor `[375, 1280]` (default theme, seeded data).
+
+> **This skill grades the axis; it does not run it.** The tokens below are *graded* by the Coverage Ledger (does a qualifying real-render test exist, is it non-intercepting, is it attested). The *instruments* that open a browser and observe these invariants live in the **`e2e-test` skill's presentation sweep**. ensure-coverage owns the **obligation**; the runner and the per-`(route, level)` result shape the ledger consumes are documented with the runner (`e2e-test/references/presentation-sweep.md`). This mirrors how breadth delegates surface discovery to an inventory adapter ([../breadth/inventory-contract.md](../breadth/inventory-contract.md)).
+
+Invariants, **spine first**:
+
+- **`presentation:render-health`** *(spine)* — the page renders without a **`pageerror` (uncaught exception), a `console.error`, a rendered error boundary, or an HTTP `>= 500`** on the document or any first-party request it issues. The cheapest, most foundational check — an uncaught `TypeError` on mount fails here before any layout question is asked — so every other presentation level sits on it. A green functional journey sails past it when the route's only test intercepts its own API. **Continuous, not load-only**: it must also hold *through* the interactions the other instruments drive — a `presentation:temporal` trigger, a `presentation:perceivability` post-delete mutation, a mutation-form journey's submit — so an error / `console.error` / first-party 5xx fired *during a write* fails too. (This is "mutate-health": render-health composed with the trigger/mutation pattern, not a separate axis — compose with those checks rather than re-driving the form.)
+- **`presentation:spatial`** — laid out without collision: no unintended horizontal overflow **and** no unintended element overlap (bounding-box intersection) at the floor viewports. Intentional z-stacks (carousels, badges, sticky headers) are suppressed only via a **gated allowlist** (`category` + `reason`, surfaced in a census); an overlap occluding a **reachable interactive element can never be allowlisted**.
+- **`presentation:perceivability`** — controls are visible/distinguishable (WCAG contrast), and things that must be *absent* are gone (negative form: a role-gated control not visible to the wrong role; a deleted item does not linger).
+- **`presentation:reachability`** — a user can get to the page and tell its controls are actionable: every manifest route is reachable by crawling the rendered nav (no **navigational orphan**), interactive controls show a visible focus indicator and meet the ≥44px target floor. Negative form: a modal traps focus (no click-through / focus escape); a privilege-gated route is not navigationally reachable for the wrong role.
+- **`presentation:temporal`** — the layout holds still as things inject. **Split by who renders the shift** — *first-party* (lazy images, async data, our dynamic fields) is a **hermetic gate** (real render, no network; before/after geometry gated on a stable condition, never a fixed sleep, or a `PerformanceObserver` CLS score). *Third-party* (Stripe/Adyen payfields) runs against the provider **sandbox iframe** in a **non-blocking PR lane**: a failure posts a visible annotation and the surface stays `Unverified` until the test is read and marked `verified: true`. Top-page CLS is **structurally blind to cross-origin iframes** (WICG excludes descendant frames), so this is a before/after geometry assertion gated on a provider-ready signal, not CLS. The mobile **dynamic-viewport (`dvh`/`100vh`) cell** is gated via Playwright emulation with a tuned tolerance (staging fallback if flake is unmanageable).
+
+"Graded" means the ledger marks a route's floor `Missing` / `Over-mocked` / `Unverified` / `Covered` from the tests that exist — it cannot itself detect a runtime crash, which is why the sweep is a **separate evidence run**, not a side effect of the functional E2E suite. It is not a CI gate; curated golden-path smoke is the sole CI gate ([CI contract](../enforcement/ci-contract.md)).
+
+The floor runs at the screen viewport floor (`[375, 1280]`). The **`media=print` cell is warn-only by default** — a broken print stylesheet is logged in the census, not a blocking gate (lower-frequency, harder to assert deterministically). A surface may escalate it to a gate when print output is a real product surface (e.g. an invoice).
+
+## Feature-derived escalation (the condition matrix grows itself)
+
+The floor above is the fixed minimum; the adapter then *raises* it from deterministic code **signals**, adding cell-qualified obligations (e.g. `presentation:perceivability@dark`) so two agents on the same code compute the same set:
+
+| signal (adapter-derived) | adds |
+|---|---|
+| a dark-mode/theme toggle | `presentation:perceivability@dark` (contrast must also hold in dark theme) |
+| an i18n library | `presentation:spatial@long-locale`, `presentation:spatial@rtl` (layout must survive long locales + RTL) |
+
+A cell-qualified level grades exactly like its base (real render, exact-match, DOM-only → `Over-mocked`). **Adding cells is free; a check can never be made weaker; a cell may be removed only through the gated `excludeCells` path** (`category` + `reason`, surfaced in the census); the base mechanical floor (unqualified levels) can never be removed. This mirrors the Surface Baseline Contract's raise-only + gated-exclusion rule.
+
+> **Navigational vs guard-chain reachability.** `presentation:reachability` is **navigational** ("can a user *click* here from an entry point") — *not* the guard-chain [Route Discovery & Reachability Protocol](../breadth/surface-discovery.md) ("can the URL load past middleware/auth"). A route can be guard-reachable yet navigation-orphaned. Both matter; different checks.
+
+> **Affordance ↔ `impeccable` boundary.** The *deterministic* affordance checks live here (focus-indicator **presence**, target size, nav-orphan). The *aesthetic/holistic* judgment (is the focus style good, is a11y resilient under zoom/AT) stays in `impeccable` (`reference/harden.md`). This axis proves the cue **exists**; impeccable judges whether it's good.
+
+## Proven only against a real rendered page
+
+A presentation level is **exact-match** and proven only against a **real rendered page**:
+
+- A functional `browser-journey` does **not** satisfy a presentation level — a journey clicks the DOM; it never asserts no-overflow or perceivability. Each is required separately; one presentation level does not satisfy another.
+- A DOM-only / JSDOM assertion of a presentation level grades **`Over-mocked`** — the axis's proxy-wiring (it can't see what a human sees). The proving test must drive a real browser.
+- Like any obligation, a statically-satisfied presentation level lands at `Unverified` until the test is read and marked `verified: true`.
+
+**State-aware, abstain-on-doubt.** A check is deterministic only where element state is unambiguous; where it cannot decide it **abstains → `Unverified`**, never a silent pass. Disabled controls are *intended* low-contrast (WCAG exempts them), so the perceivability check derives state (`aria-disabled`/`[disabled]`) and skips them. axe-core's contrast rule **abstains** ("incomplete") on text over a background-image/gradient — the invisible-control case — and that abstain stays `Unverified` until a manual check (`verified: true`) **or** escalation to a stronger instrument. **AI-vision is triage-only**: it may flag for human attestation but never promotes an obligation to `Covered` (run-to-run non-determinism).
+
+Non-browser surfaces (`api`/`table`/`event`/`job`) carry **no** presentation floor.
+
+## `presentation:fidelity` — does it match the design source it came from?
+
+Every level above is **self-referential**: render-health asks whether the page renders, perceivability whether a human can act on it. None of them asks the question a unit built from a prototype, mockup or design doc actually owes: **does this match the thing it was supposed to be derived from?**
+
+That gap is not theoretical. A baseline captured from a wrong implementation is green forever — in the incident below it would have locked in a card plane the design did not have and a flattened type scale, and reported success. Drift detection cannot substitute for fidelity, because it takes the implementation as its own authority.
+
+**When it is owed.** A unit whose source cites a design artifact — a prototype branch/path, a mockup, a design doc that fixes layout — carries `presentation:fidelity` on the surfaces that artifact covers. A unit with no cited design source does not; this is not an auto-floor and inventing one for a CRUD tweak is ceremony.
+
+**The rule that makes it fidelity.** Every expected value is read off the **source**, with it rendered, and cites the source line it came from. A value copied off the page you built is a baseline wearing a fidelity label.
+
+**Why it is not a differ.** Diffing source against implementation only works when both are the same stack; an HTML prototype or a Figma frame against a React deliverable defeats it. So the work splits where it divides: **comparing across technologies is judgment; checking against an extracted spec is mechanical.** A human reads both, rendered, once, and writes the load-bearing properties down in units that survive a stack change (computed pixels, not `sm:text-3xl`). That **parity manifest** is the only step needing eyes; `design-parity.mjs` scaffolds it from a doctrine-fixed catalog, emits the probe that measures the built page, and validates the result ([`scripts/README.md`](../../scripts/README.md)).
+
+**No rewriting the target to match the page.** The cheapest way to green this gate is to edit `expected` instead of fixing the page. Because the source is pinned, a changed `expected` under an unmoved `source.sha` is mechanically detectable and blocks; a genuine mis-read is declared with `rebase: <reason>`. The reviewer treats an undeclared rewrite as a blocker, exactly as it does a silent re-baseline.
+
+**The render is not optional.** A property list catches what someone thought to list. Before the terminal review, render source and deliverable at the floor viewports side by side in the PR.
+
+Two hard rules, from the named incident (fmm-express #521, 2026-08-06: a cited prototype was summarized once into four bullets, nothing downstream re-read or rendered it, and the criteria doc listed visual baselines under non-goals, so a green suite shipped a page that took four rounds of correction): a presentation-only unit **may not** list visual or parity evidence as a non-goal, and a cited design source is **consumed, not summarized**.

package/skills/engineering/ensure-coverage/references/process/audit-mode.md

@@ -0,0 +1,27 @@
+# Audit Mode (process)
+
+> Read when: auditing whether existing code/tests cover a requirement, PR, issue, feature, or bugfix. Audit current sufficiency against the behavior-first criteria; do not only generate ideal future criteria. Coverage classifications used here are defined in [../depth/grading.md](../depth/grading.md).
+
+Audit steps:
+
+1. Derive ACs from the source before inspecting implementation details.
+2. Identify public interfaces, workflows, state transitions, side effects, code paths, and existing tests.
+3. For E2E audit, run the [Route Discovery & Reachability Protocol](../breadth/surface-discovery.md) before judging coverage.
+4. Identify critical journeys with actor/role, start state, trigger, major steps, expected end state, route reachability, and observable side effects.
+5. Map each AC and journey to existing tests only after inspecting the actual test files/cases/assertions; prior docs, PR summaries, or agent reports are leads, not proof.
+6. Reject coverage that only validates private functions, implementation structure, or shallow route render-health checks for business journeys.
+7. Create follow-up items for every gap with required test level, setup/input, assertions, and mock/fake policy.
+8. Reach a production-readiness verdict — an explicit ship / no-ship call, the specific scenarios a real user would hit in the first week, and the evidence that would raise confidence — and **put it at the TOP of the deliverable** (the reader's first question is "what's the call?"; the census and detail justify it below). Do not let mapped ACs alone earn a ship call. Separate **blocking decisions** (product/scope choices that change the verdict and need a human answer) from **follow-up actions** (work to schedule) — see the output template; don't dump both into one vague "open questions" list.
+9. **Do not audit CI wiring** unless the user asks. A repo without coverage gates in CI is not a finding. When the user does ask, run `ci-audit.mjs` against the repo's CI config and report curated golden-path smoke as present / warn-only / absent. Do not turn the other audit checks into CI findings; they contribute directly to the coverage verdict.
+10. **Run the over-mock scan whole-tree** (`lint-tests.mjs --rules mock-internal-seam`, no `--diff`) from this skill against the target repo. Every hit is an `Over-mocked` census row and a no-ship contributor; **count them in the verdict**. A missing `coverage.config.json` means "run on defaults", not "not applicable"; a non-conventional topology earns a "declare topology" follow-up, never a downgrade of the finding ([../depth/mock-policy.md](../depth/mock-policy.md)).
+11. If code, tests, or route discovery cannot be inspected or run, mark the assessment `BLOCKED` and state the missing access or command failure. "The lint script isn't in the audited repo" is not `BLOCKED`: the scripts are part of this skill ([../../scripts/README.md](../../scripts/README.md)).
+
+The coverage classifications (`Covered` / `Partial` / `Missing` / `Wrong Level` / `Over-mocked` / `Unverified` / `Excluded` / `BLOCKED`) are defined in [../depth/grading.md](../depth/grading.md). Use that vocabulary, not a vague "covered."
+
+## Completeness: enumerate every surface, not just the salient gaps
+
+**Gap-finding must be exhaustive, not a highlight reel.** An audit that lists "the top 3 problems" silently leaves the long tail uncovered — where the un-ACed orphan hides. Completeness comes from **closed-world enumeration**:
+
+1. **Start from the full surface inventory** (every route, API, write form, table, event, job — from [surface discovery](../breadth/surface-discovery.md) / the generated inventory), not the list of things you happened to notice.
+2. **Emit a complete surface census**: one row per inventoried surface with its status. `gaps = inventory − {surfaces at Covered}`, so every surface is accounted for *by construction*. The census is the deliverable's backbone (the **Surface Census** table in [output-template.md](output-template.md)); the prose highlights the worst rows, but the table proves nothing was skipped.
+3. **Every non-`Covered`/non-`Excluded` row is a gap** with its own follow-up item. If the inventory cannot be fully enumerated (no adapter, partial access), say so and mark the unenumerated portion `BLOCKED`; do not silently scope to what was easy to see.