@1aboveio/skills 0.10.0

package/skills/engineering/ensure-coverage/references/enforcement/hooks.md

@@ -0,0 +1,85 @@
+# Hook Contract (in-loop gate enforcement)
+
+The [CI Contract](ci-contract.md) wires the gates at **merge time** — the latest,
+slowest place to discover a problem. This contract adds the *earliest* place: the
+agent's own **edit/stop loop**, run as Claude Code hooks so a violation is caught at
+the keystroke or at the moment the agent tries to finish, not after a CI round-trip.
+
+The point is a **shift left, not a new gate**. Hooks invoke the existing
+`lint-tests.mjs` and `coverage-ledger.mjs`; they add no rules and own no doctrine.
+They convert two `resolve-issues` principles from prose into mechanics the agent
+*cannot* bypass:
+
+- **Principle 1 — never skip/disable/weaken a test.** A `PreToolUse` hook denies an
+  edit that *adds* a banned pattern (`test.skip`/`.only`/`xfail`/`xit`,
+  `waitForTimeout`/numeric `cy.wait`/`time.sleep`) to a test file.
+- **Principle 5 — the loop exits on a fresh green gate, never on a claim.** A `Stop`
+  hook blocks the agent from declaring done while a gate is red against the current
+  HEAD.
+
+The runnable hooks are provided by the **adopting repo** in its own `hooks/` dir
+(`gate-pretooluse.mjs`, `gate-stop.mjs`) — this skill ships the **doctrine**, not the
+scripts. This file specifies which gate belongs at which lifecycle event, and why.
+
+## The enforcement tiers
+
+A gate runs at the **earliest point it can run cheaply and decisively**. Three tiers,
+widening in cost and scope:
+
+| Tier | Lifecycle event | Gate | Why here (and not earlier/later) |
+|---|---|---|---|
+| **Edit-time** | `PreToolUse` (Edit/Write/MultiEdit on a test file) | `lint-tests` skip/timeout, on the *proposed addition* only | Syntactically decidable, ~zero false positives, sub-second. Safe to block at the keystroke. Catching it here saves the agent from building on a test it will have to un-break. |
+| **Stop-time** | `Stop` | `lint-tests --diff` over the net change + `coverage-ledger validate` | Needs the whole `base...HEAD` diff and the surface inventory — not available mid-edit, but cheap enough to run once when the agent tries to finish. This is the mechanical form of "don't stop on a claim." |
+| **CI** | the [CI Contract](ci-contract.md) gates | inventory freshness, accounting, **presentation sweep**, functional/journey suite, `coverage-checklist validate` | Needs a browser, a seeded env, a specific Review-Contract checklist target, or minutes of runtime. Belongs in the PR lane, never the inner loop. |
+
+The dividing line is **decidability and cost**, the same line `lint-tests` draws
+between GATE and LEAD: a check blocks at edit-time only if a legitimate edit could
+never trip it. A heuristic ("is this assertion meaningful?", over-mocking) stays a
+review LEAD — never a blocking hook, because a noisy blocking hook gets turned off,
+taking the real enforcement with it.
+
+### Why these specific placements
+
+- **Skip/timeout lint at edit-time, not just CI** — the one check both fully
+  decidable and instantaneous, guarding the principle most prone to shortcut under
+  pressure ("just skip it to get green").
+- **`coverage-ledger validate` at stop-time, not edit-time** — it reconciles the
+  *whole* changed surface against the inventory; a partial mid-edit tree would
+  produce false failures. Stop is the first coherent point.
+- **`coverage-checklist validate` stays in CI** — it validates a *specific*
+  Review-Contract checklist path a generic stop hook can't know. Runs at the
+  `implement-and-pr` gate step and in CI.
+- **Presentation sweep / full suite stay in CI** — a browser and a seeded env are
+  not inner-loop costs.
+
+## Degradation contract (never trap the agent)
+
+A hook that can't run its gate **must allow**, never block — blocking on a check you
+can't perform is indistinguishable from a false positive, and the first spurious
+fire gets the whole layer disabled:
+
+- **Scripts unresolved** (`ensure-coverage` not vendored / `ENSURE_COVERAGE_SCRIPTS`
+  unset and not at the default path) → allow.
+- **`lint-tests --diff` can't compute a diff** (not a git repo, bad base) → the
+  runner treats unparseable output as `degraded`, not a violation.
+- **`coverage-ledger validate` exits 2** (no surface inventory — gate not wired
+  here) → `degraded`, allow. Only exit **1** (a real reconciliation failure) blocks.
+
+So a repo wiring only part of the pipeline still gets the edit-time skip lint and
+suffers no spurious stop-blocks.
+
+## Escape hatch
+
+`TEST_GATE_OFF=1` disables both hooks for the session — for the legitimate cases (a
+deliberately half-written test mid-edit, or an *inherited* failure the agent is
+fixing), paired with a duty to surface the block to a human. The invariant:
+**disable the gate, never the test.** Using `TEST_GATE_OFF` to land a real
+`test.skip` is the same failure one level up, and it leaves a reviewable trace (the
+env flip) where a silent `test.skip` is what the gate hunts for.
+
+## Relationship to the other enforcement surfaces
+
+Hooks are the **first** line, CI the **last**, review the **judgment** layer
+between — redundant on purpose: the hook catches the skip at the keystroke, CI
+catches it if the hook was off, `review-pr` catches the *semantic* failures neither
+can decide. Doctrine stays here in `ensure-coverage`; the hooks **consume** it.

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

@@ -0,0 +1,109 @@
+# Coverage Ledger: Worked Example
+
+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 reviewer attestation (`verified: true`); `Unverified` blocks the gate by default.
+
+## 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 & visual (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).
+
+`presentation:visual` is **not** auto-floored — a surface earns a committed pixel baseline only by declaring it in its curated file (with gated, reasoned `mask:` regions), because every intended UI change re-baselines. It grades `Missing` with no committed baseline, and a diff counts as coverage only when tied to a declared intended UI change. Mechanics: [../presentation/runner-contract.md](../presentation/runner-contract.md), [../enforcement/ci-contract.md](../enforcement/ci-contract.md).

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

@@ -0,0 +1,33 @@
+# Refund Flow Test Criteria Example
+
+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,78 @@
+# Presentation Floor (browser routes)
+
+> Read when: working any `presentation:*` invariant. Sibling: [runner-contract.md](runner-contract.md) (the interface the `e2e-test` sweep must satisfy to *run* these). 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 **contract** — [runner-contract.md](runner-contract.md) (the interface a repo's sweep must satisfy and the per-`(route, level)` result shape the ledger consumes) — not the runner. 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 a reviewer attests. 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, mandatory CI job** ([../enforcement/ci-contract.md](../enforcement/ci-contract.md)), not a side effect of the functional E2E suite.
+
+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 blocking `Unverified` until reviewer-attested.
+
+**State-aware, abstain-on-doubt.** A check is deterministic only where element state is unambiguous; where it cannot decide it **abstains → blocking `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 blocks until reviewer attestation (`verified: true`, after manual check) **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:visual` — opt-in pixel-baseline regression
+
+The floor invariants above are *structural* and auto-applied: they prove a page renders, doesn't overflow, and is perceivable, but not that it *looks* right. `presentation:visual` is the **opt-in** level that pins the rendered appearance against a committed pixel baseline and fails on drift — catching the restyle/wrong-content/visually-broken-but-not-erroring class the other levels miss.
+
+It is **not** part of the auto-floor. A surface earns it only by declaring `presentation:visual` in its curated `*.coverage.yml` (the raise-only path of the [Surface Baseline Contract](../breadth/surface-baseline.md)) — a baseline is a maintenance liability, so which routes deserve it is a per-surface breadth decision. Once declared it grades like its siblings: **exact-match, real-render** (a DOM/JSDOM snapshot can't see pixels → `Over-mocked`), statically-satisfied lands at blocking `Unverified` until attested. Distinctive grading hooks:
+
+- The proving evidence is the **committed baseline PNG(s)** at the floor viewports — a cell with no committed baseline is `Missing`.
+- A **baseline diff** grades as coverage only when tied to a *declared* intended UI change (`review-pr` blocks a silent `--update-snapshots` to green — the visual analogue of no-skip-to-green).
+- It is **CI-only**, in a pinned container; run mechanics, determinism rules (mask/freeze/threshold), and the two CI jobs live in [runner-contract.md](runner-contract.md) and [../enforcement/ci-contract.md](../enforcement/ci-contract.md). AI-vision stays triage-only — a pixel baseline is the deterministic instrument; vision can flag, never promote.
+
+## `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, and `presentation:visual` whether it drifted from *its own* committed baseline. 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.** The obvious instrument diffs source against implementation, and it only works when both are the same stack. An HTML prototype, a v0 export or a Figma frame against a React deliverable defeats it immediately. So the work splits where it actually 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 interchange format and the only step needing eyes. Everything after it mechanizes:
+
+- `scripts/design-parity.mjs scaffold` emits the manifest skeleton from a **doctrine-fixed catalog** — page measure, container plane (three properties: a card returns through whichever one you left unpinned), primary/secondary type scale **per floor viewport**, box padding, coupled-element rhythm, and one relational row (`primary.font-size > secondary.font-size`) that survives both a stack change and a token change. The catalog is the anti-omission device: the rows you would have forgotten are already in the file, and a row may be **rejected with a written reason but never silently omitted**.
+- `design-parity.mjs probe <manifest> --viewport <px>` emits the JS that measures the built page; its output is the results file. `e2e-test` or `agent-browser` drives it — this skill owns what must be proven, not the runner.
+- `design-parity.mjs validate <manifest> --observed <results.json>` is the gate. Without `--observed` it announces itself as the **reduced form**: it checks the manifest is complete and its citations resolve, never that the page conforms.
+
+**No rewriting the target to match the page.** The cheapest way to green this gate is to stop fixing the page and edit `expected` instead — the same move as a bare `--update-snapshots`, except easier, because it is one character of YAML rather than a regenerated PNG and leaves no image in the diff to notice. It is also mechanically detectable, thanks to the property that makes this fidelity: **the source is pinned and therefore immutable**. If `source.sha` has not moved and the row's `from:` line has not moved, the value read off that line cannot have changed. So `design-parity.mjs validate --diff <base>` blocks a changed `expected` under an unmoved source, and a genuine mis-read clears it by saying so — `rebase: <reason>` on the row, the same declared-intended-change shape the visual baseline already uses. When the source itself is re-pinned, expectations are *supposed* to move: that warns rather than blocks. `review-pr` 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 `[375, 1280]` and put them **side by side** in the PR. This is the check that fails when the manifest itself is incomplete, and it is the cheapest one here.
+
+**Named incident (fmm-express #521, 2026-08-06).** A settled prototype was cited by exact branch and path in the issue, summarized **once** into four prose bullets, and every downstream artifact — issue, criteria doc, tests, code — descended from the summary rather than the source. What the summary dropped (page measure, card plane, the primary input's responsive type steps, the secondary field's scale) was then unfindable: nothing re-read the source and nothing rendered it — one image in a 3,040-message session, pasted by the user. The criteria doc listed "visual screenshot baselines" under **Non-goals** on a unit whose entire content was visual, so a fully green suite shipped a page that took four rounds of user correction. Hence two hard rules: a presentation-only unit **may not** list visual/parity evidence as a non-goal, and a cited design source is **consumed, not summarized**.

package/skills/engineering/ensure-coverage/references/presentation/runner-contract.md

@@ -0,0 +1,74 @@
+# Presentation Runner Contract
+
+The presentation axis is **graded** by the Coverage Ledger but **run** by a real browser the ledger never launches. This file is the interface between the two: what a repo's presentation sweep must do, and the per-`(route, level)` result shape the ledger consumes. It is the presentation-axis sibling of [../breadth/inventory-contract.md](../breadth/inventory-contract.md) (which is the breadth-axis discovery contract).
+
+The reference implementation of this contract ships in the **`e2e-test` skill** (`scripts/presentation-render-health.mjs`, `presentation-checks.mjs`, `presentation-sweep.mjs`, …). ensure-coverage owns the contract; `e2e-test` owns the runner. A repo may use the reference runner as-is or supply its own as long as it satisfies this contract.
+
+## Why a runner is needed at all
+
+`coverage-ledger.mjs` is a static analyzer: it proves *a qualifying test was authored* (real-browser, non-intercepting, `@covers <route>` at `@level presentation:*`, attested) and can mark a route's floor `Missing` / `Over-mocked` / `Unverified` / `Covered`. It **cannot** observe a `pageerror`, an overflow, or a layout shift — only a browser opening the real page can. So the gate has two halves: **accounting** (`coverage-ledger.mjs validate` — is the obligation owned and proven by a clean test?) and **rendering** (this sweep — does the page pass the invariant when opened for real?). A repo that wires only accounting ships crashing routes with a green board.
+
+## What the sweep must do
+
+Given the generated route manifest (the same `kind: "route"` surfaces emitted per [../breadth/inventory-contract.md](../breadth/inventory-contract.md)):
+
+1. **Open every manifest route in a real browser** (Chromium) at the viewport floor `[375, 1280]` — `PRESENTATION_VIEWPORT_FLOOR`, the ledger constant. Do **not** sample or top-N silently; if you bound coverage, `log` what was dropped.
+2. **Drive the real render path — no first-party interception.** `page.route('**/api/**')`, `route.fulfill`, MSW for owned paths, or first-party fixtures **disqualify** the run for that route (a sweep faking its own backend proves proxy wiring). Externals (Stripe, third-party APIs) may be faked. Mirrors the ledger's `INTERCEPT_RE` rule — a route proven only behind an interception is `Over-mocked`.
+3. **Assert the floor invariants, spine first**, recording a result per `(route, level, viewport)`:
+   - `presentation:render-health` *(spine)* — no `pageerror`, no `console.error`, no rendered error boundary / framework overlay, no HTTP `>= 500` on the document or any first-party request. **Continuous, not load-only**: the sweep asserts it at load, and authored journeys keep the watcher attached *through* their interactions (the `temporal` trigger, the `perceivability` post-delete mutation, the mutation-form submit) so an error fired *during a write* fails too ("mutate-health"). The sweep itself proves only the load path — write paths are destructive and need authored journeys.
+   - `presentation:spatial` — no unintended horizontal overflow, no unintended element overlap.
+   - `presentation:perceivability` — contrast / no invisible-but-present controls (+ negative forms).
+   - `presentation:reachability` — navigational reachability + affordance cues (focus indicator present, ≥44px target).
+   - `presentation:temporal` — first-party shift is a hermetic gate; third-party shift runs against the provider sandbox in a non-blocking lane.
+4. **Abstain, never silently pass.** Where state is ambiguous (contrast over a gradient/image, a route unreachable because seeding failed), emit `unverified` — it blocks until attested or escalated. Where the environment cannot render at all (no `DATABASE_URL`, auth unavailable), emit `blocked`, **not** `pass`. "Could not check" is never "checked and fine."
+
+## Visual regression — the opt-in `presentation:visual` level
+
+The floor invariants are auto-applied and assert *structural* facts; none catches a surface that renders cleanly, passes contrast, and is laid out without collision yet *looks wrong* (wrong content, a restyled component). `presentation:visual` closes that gap: it captures the rendered page and **fails when it drifts from a committed reference image**.
+
+Unlike the floor levels, **`presentation:visual` is opt-in, never auto-floored** — a surface carries it only when its curated `*.coverage.yml` declares it (the raise-the-level path of the [Surface Baseline Contract](../breadth/surface-baseline.md)). A pixel baseline is a maintenance liability (every intended UI change re-baselines), so which routes deserve it is a per-surface breadth decision. The reference runner uses **Playwright's built-in `toHaveScreenshot()`** — baselines, 3-up diff, `mask:` regions, and the `maxDiffPixelRatio` threshold are all native.
+
+**CI-only, in a pinned container — non-negotiable.** A baseline generated on one OS and gated on another fails on every glyph's anti-aliasing, and a visual gate that reds on every PR gets disabled. So **both** baseline generation and the gate run only in CI inside a pinned Playwright image (`mcr.microsoft.com/playwright:vX.Y`). Two CI jobs realize this ([../enforcement/ci-contract.md](../enforcement/ci-contract.md)): a blocking **`visual-gate`** and an on-demand **`visual-baseline-regen`** (label/dispatch-triggered `--update-snapshots`, commits the PNGs back). The in-loop hooks never run it ([../enforcement/hooks.md](../enforcement/hooks.md)).
+
+**Determinism is the surface's obligation.** Before the snapshot: animations/transitions disabled, clock frozen, data seeded, and every known-dynamic region (timestamps, avatars, live counts) covered by a `mask:` locator — a *gated concession* declared with a `reason`, surfaced in the census, so masking can't silently grow to hide a regression. The threshold is a **tight** `maxDiffPixelRatio` for sub-pixel AA noise, never loose enough to swallow a real change.
+
+**A baseline change is reviewable evidence.** The committed PNGs are the durable record; a diff to them must be tied to a *declared* intended UI change in the Review Contract, never a silent `--update-snapshots` to green (`review-pr` enforces this). After regen, the durable baseline link (at the SHA) plus the ephemeral diff-preview URL are posted back to the work item and **returned as a value** (`--evidence-out`, plus stdout) for the `resolve-issues` orchestrator to record on the unit — the evidence-posting step in [../enforcement/ci-contract.md](../enforcement/ci-contract.md). The regen job does **not** write the run manifest itself; the orchestrator is its only writer (ADR 0001 decision 5 (`docs/adr/0001-interference-is-the-scheduling-primitive.md`)).
+
+## Fixtures the sweep needs (repo-supplied)
+
+These are repo-specific, like inventory discovery. The reference runner parameterizes them:
+
+- **Auth** — a deterministic bypass/seeded session so guarded routes render as a real user (e.g. an `E2E_AUTH_BYPASS` cookie). A login wall is not a render pass.
+- **Seed** — deterministic data so `read`/`detail` routes render real content and `mutation` routes have something to act on. An empty-state-only render does not prove the populated page.
+- **Param substitution** — dynamic segments (`/tasks/[id]`) need a concrete seeded id per route. A route whose param cannot be resolved is `blocked`, not skipped.
+- **Allowlist** — intentional overlap/z-stack suppression is a *gated* allowlist (`category` + `reason`, surfaced in a census); an overlap occluding a reachable interactive control can never be allowlisted.
+
+## Result shape the ledger consumes
+
+Emit JSON to `docs/tests/_generated/presentation-results.json`:
+
+```json
+{
+  "viewportFloor": [375, 1280],
+  "results": [
+    { "route": "/tasks", "level": "presentation:render-health", "status": "fail",
+      "evidence": "pageerror: Cannot read properties of undefined (reading 'id') at TasksToolbar" },
+    { "route": "/tasks", "level": "presentation:spatial", "status": "blocked",
+      "evidence": "render-health failed; layout not assessable" },
+    { "route": "/dashboard", "level": "presentation:render-health", "status": "pass" },
+    { "route": "/dashboard", "level": "presentation:visual", "status": "fail", "viewport": 1280,
+      "evidence": "12.4% pixels differ from baseline (maxDiffPixelRatio 0.001)",
+      "baseline": "e2e/dashboard.spec.ts-snapshots/dashboard-1280-chromium-linux.png",
+      "diffArtifact": "https://…/artifacts/visual-diff (expires 2026-09-13)" }
+  ]
+}
+```
+
+- `status` — `pass | fail | unverified | blocked`. `fail` and `blocked` exit the sweep non-zero (gate fails). `unverified` blocks the ledger until attested.
+- `evidence` — the concrete observation (the actual `pageerror` text, offending selector + overflow px, the unreachable param, the percent-pixels-differ for `presentation:visual`). Name the failure, not "presentation partial."
+- For `presentation:visual` only: `viewport` (which floor viewport this cell covers — visual is captured per viewport), `baseline` (the committed reference PNG the gate compared against — the durable evidence), and `diffArtifact` (the ephemeral 3-up diff URL on failure, with its expiry). These flow into the evidence-posting step.
+- The ledger reconciles these against each route's required presentation levels: a `fail`/`blocked`/missing result on a required level is a finding; a `pass` is a *lead* that still needs a clean authored test + attestation to reach `Covered` (a sweep run is execution evidence, not authored coverage).
+
+## Relationship to the functional E2E suite
+
+The sweep is a **separate gate** from the functional/journey E2E suite, though both use Playwright: the functional suite clicks the DOM and may legitimately intercept externals; the sweep opens the real render path and asserts perceivability. A green functional suite satisfies **no** presentation level ([axis.md](axis.md)). CI placement: [../enforcement/ci-contract.md](../enforcement/ci-contract.md).

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

@@ -0,0 +1,33 @@
+# 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, mock/fake policy, and evidence.
+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. Audit the **enforcement wiring** against [../enforcement/ci-contract.md](../enforcement/ci-contract.md), not just the tests: does the repo run the accounting gate *and* a separate render sweep over the manifest? A repo can have clean doctrine and still ship a crashing route because the sweep gate is absent, in warn-only/phase-in mode, or the route is missing from the inventory. Run the meta-gate — `scripts/ci-audit.mjs --files <ci configs>` — which reports each required gate as present / warn-only / absent; a missing or weakened render-sweep gate is itself a finding, independent of any single test.
+10. **Run the over-mock scan WHOLE-TREE as part of the depth audit** — it mechanically finds `Over-mocked` (a test that fakes the first-party seam it claims to exercise), **zero-tolerance** ([../depth/mock-policy.md](../depth/mock-policy.md)). Run it **from this skill against the target repo** (the scripts live here, not in the audited repo — their absence there is expected, not a reason to skip):
+    ```
+    node <path-to-this-skill>/scripts/lint-tests.mjs --rules mock-internal-seam   # whole-tree: every test file, not just the diff
+    ```
+    - **Always run it, even with no `coverage.config.json`** — default-on, config-independent (config only declares topology); a missing config means "run on defaults" (conventional `@/`/`~/`-aliased repo), not "not applicable." Whole-tree (no `--diff`): inherited mocks aren't grandfathered.
+    - **Each hit is an `Over-mocked` census row and an automatic no-ship contributor.** **Quantify the count in the verdict** — never compress to "advisory mock debt." Resolution: replace with a real-boundary test, fake only the external, or **delete** (over-mock is worse than no test); no `@mock-ok` waiver. Deleting reverts the route to its honest breadth status (`Missing`/`Excluded`).
+    - A **non-conventional topology** (e.g. a monorepo `@acme/` scope, generated dirs) earns a "declare topology in `coverage.config.json`" follow-up — never "gate not available," never a reason to downgrade the finding.
+11. If code/tests or route discovery cannot be inspected/run, mark assessment `BLOCKED` and state the missing access, files, or command failure. ("The lint script isn't in the audited repo" is *not* BLOCKED — the script is part of this skill; run it from here.)
+
+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.

package/skills/engineering/ensure-coverage/references/process/output-template.md

@@ -0,0 +1,139 @@
+# Output Template, Writing Rules & Validation (process)
+
+> Read when: producing the criteria/audit document (create mode), or running the final self-check before saving.
+
+## Lead with the verdict
+
+An **audit deliverable opens with the verdict**, not buries it under tables. Put a one-line `## Verdict: Ship / No-ship` (with the one-sentence reason) as the **first section**, before the Surface Census and the detailed assessment, which then *justify* it below. (Create-mode criteria docs lead with Source/Scope — there's no verdict yet.)
+
+**Quantify the debt that drives the verdict — a no-ship is a number, not a vibe.** A `No-ship` carries the **magnitudes** that make it no-ship, in the verdict itself: counts of uncovered surfaces, orphan surfaces, ledger warnings, skipped tests, and **over-mock findings** (the `mock-internal-seam` count is a zero-tolerance, automatic no-ship contributor — [../depth/mock-policy.md](../depth/mock-policy.md)). "Coverage is still partial" drops the evidence the reader needs to size the work. **If a finding has a count, the count goes in the summary** — "it doesn't block CI yet" is never a license to omit it.
+
+## Writing Rules
+
+- Make each AC independently testable.
+- Prefer observable outcomes over internal implementation details.
+- Include negative cases and misuse paths, not only happy paths.
+- For async/pub-sub/orchestrator systems, require correlation IDs and final durable state assertions.
+- For idempotent APIs, require duplicate request tests and concurrent request tests when money/state transitions are involved.
+- For security-sensitive flows, require authorization tests for cross-tenant/cross-merchant access.
+- For provider integrations, use fake adapters in integration tests and real providers only in staging smoke tests.
+- Avoid vague criteria like “works correctly,” “fast,” or “secure”; replace them with measurable expectations.
+
+## Output Template
+
+Use this structure unless the user asks for another format:
+
+```markdown
+# Test Criteria: <feature/task name>
+
+## Source
+- Input: <PRD/design document/spec/bug brief/GitHub issue/code audit source name or link>
+- Version/date: <if available>
+- Author/owner: <if available>
+
+## Scope
+- In scope: <behaviors covered>
+- Out of scope: <behaviors intentionally excluded>
+- Assumptions: <behavior inferred from issue/context/sibling flows because source is incomplete>
+- Blockers: <product/access/env decisions that prevent precise criteria>
+- Design source: <the prototype ref:path / mockup / layout-fixing doc this unit is built from, pinned at a commit — or `none`>
+
+> **"Out of scope" cannot exclude the axis the unit is about.** Scope excludes *behaviors*; it is not a place to retire an axis of proof. The named incident (fmm-express #521) is one line in this section: a charge-screen unit whose entire content was visual listed *"Non-goals: visual screenshot baselines"*, and a fully green suite then shipped a page that took four rounds of user correction. If the unit cites a **Design source** above, its criteria owe `presentation:fidelity` — a parity manifest and the side-by-side render ([../presentation/axis.md](../presentation/axis.md)) — and writing that evidence off here is declaring the point of the work out of scope. The reverse is fine and common: a unit with no design source simply says `none`.
+
+## Acceptance Criteria
+- AC1: <actor/system does ... under condition ... with expected observable result>
+- AC2: <...>
+
+## Critical User/System Journeys
+- J1: <actor/role starts from ... does ... and reaches ... with expected side effects>
+- J2: <...>
+
+## Test Matrix
+| Scenario | AC/Journey | Test Level | Mock/Fake Policy | Setup/Input | Assertions | Required Evidence |
+|---|---|---|---|---|---|---|
+| Happy path | AC1 / J1 | Integration/API | Real DB + fake external provider | ... | ... | CI test name/log |
+| Invalid input | AC2 | Unit + API | Mock provider only to assert it is not called | ... | ... | CI test name/log |
+
+## Mock And Integration Policy
+- Mock acceptable: <pure decision logic, provider failures, asserting side effect is not called>
+- Integration required: <DB transactions, idempotency, concurrency, event/outbox, auth/tenant isolation, schema compatibility>
+- External dependency strategy: <fake provider adapter, emulator, test container, staging smoke test>
+- Mock-only exceptions: <AC/scenario + explicit justification + reviewer approval — applies ONLY to the non-seam mock-only judgment; mocking a first-party internal seam is gate 5 (`mock-internal-seam`), zero-tolerance, NOT an approvable exception — see [../depth/mock-policy.md](../depth/mock-policy.md)>
+
+## Required Automated Tests
+- Unit: <specific logic and edge cases>
+- Integration: <DB/broker/provider fakes/state transitions>
+- Contract/API: <request/response/schema guarantees>
+- API E2E: <endpoint behavior with state/side-effect assertions, if needed>
+- UI E2E: <page route render-health/functional browser behavior, if needed>
+- Journey E2E: <cross-page/core business flow with real APIs where practical, if needed>
+
+## Coverage Mapping
+| Requirement/Journey | ACs | Test Case/File | Status |
+|---|---|---|---|
+| <REQ-1 / J1> | AC1, AC2 | <path::test_name> | Required |
+
+## Surface Census (Audit Mode Only — every surface, not just the gaps)
+One row per inventoried surface so completeness is provable by construction: gaps = every row not `Covered`/`Excluded`. If the inventory can't be fully enumerated, say so and mark the rest `BLOCKED` — do not quietly scope to what was easy to see.
+| Surface | kind/class | Required level | Status | Proving test (or — ) |
+|---|---|---|---|---|
+| /settings/team | route/mutation | browser-journey + presentation | Over-mocked | e2e/team.spec.ts (intercepts own API) |
+| /settings/team/members | route/mutation | browser-journey + presentation | Missing | — (orphan, no test) |
+| /api/team/invite | api/mutation | api + integration | Partial | tests/api/invite.test.ts |
+| ... (every remaining surface) | ... | ... | ... | ... |
+
+## Existing Coverage Assessment (Audit Mode Only)
+- Production-readiness verdict: <Ship / No-ship>, with the specific user scenarios likely to generate bug reports in the first week and the evidence that would raise confidence. **State the driving counts** (uncovered/orphan surfaces, ledger warnings, skips, over-mock findings) — a no-ship names its numbers, including advisory-scan counts; it does not hide them behind "partial."
+- Current coverage status: <Covered / Partial / Missing / Wrong Level / Over-mocked / Unverified / BLOCKED>
+- Existing tests reviewed: <actual paths/test names/cases/assertions inspected; do not list docs-only claims as reviewed tests>
+- Code paths reviewed: <paths/modules>
+- Route/endpoint discovery: <method/command/source used, discovered count, manifest count, missing/stale/uncovered entries>
+- Route reachability: <Reachable / Redirected / Guarded / Blocked / Unknown per relevant route, with layout/middleware/guard evidence>
+- E2E journeys identified: <journey list or Not applicable>
+- E2E journey coverage: <journey -> API/UI/Journey E2E evidence/status>
+- Prior coverage docs/reports checked: <None or list; state which claims were verified against test code>
+- Coverage gaps: <missing scenarios, weak assertions, over-mocking, wrong level, uncovered journeys, unverified claims, or None>
+- Follow-up test criteria items: <specific tests to add/update, with AC/journey mapping>
+
+## Test Skipping
+- Skipped tests: <None or list with allowed category, evidence/blocker link, and replacement verification>
+
+## Behavior-First Validation
+- ACs describe externally observable behavior, not private functions.
+- Test matrix scenarios validate outcomes, durable state, contracts, side effects, permissions, and failure behavior.
+- Unit tests are scoped to public behavior, pure decision logic, or stable public contracts.
+- Mock-only coverage does not bypass the core behavior under test.
+- Existing coverage claims were verified against actual test code, not trusted from prior docs/reports.
+- Route discovery and reachability analysis were performed before E2E audit, if applicable.
+- Production-readiness verdict is stated as an explicit ship/no-ship call with named first-week bug-report scenarios, not a vibe.
+- Status: PASS / FAIL / BLOCKED
+- Required revisions before approval: <None or list>
+
+## Reviewer Checklist
+- Obligation impact stated: which obligations/surfaces this change touches, their `requirementRefs`, and the evidence that proves each.
+- No `Orphan surface` introduced: every changed/new surface is referenced by at least one requirement and has a Coverage Ledger row.
+- Every changed/new page with a write form has a mutation-form journey test that fills the real UI and asserts the backend accepts the submission; split-contract forms (fields and validator from different sources) are not signed off on seam tests alone.
+- Every AC maps to an automated test or approved exception.
+- Tests assert behavior/state, not implementation details only.
+- No tests skipped/weakened to make CI pass; every (inherited) skip has an allowed category, evidence/blocker link, and replacement verification.
+- Substitutes appear only at external trust boundaries; no internal seam (DB, service layer, internal endpoint, event bus) is mocked. Fakes/stubs keep failure-path/edge cases fast and deterministic and never call a live third party in CI; mocks/fakes don't bypass the core behavior.
+- Mock-only coverage is rejected for stateful workflow, money movement, auth, idempotency, concurrency, event/outbox, or orchestrator recovery unless explicitly approved; money movement, auth, and idempotency can never be mock-only even with approval. (This approval path is the broader mock-only *judgment* only — mocking a first-party internal seam is the zero-tolerance `mock-internal-seam` gate 5, never approvable — resolve it by making the test real, faking only the external, or deleting it; see [the mock policy](../depth/mock-policy.md).)
+- Failure, retry, duplicate, permission, and concurrency cases are covered where relevant.
+- Test evidence is attached: CI link, command output, logs, screenshots, or traces.
+
+## Blocking Decisions (need a human answer to finalize the criteria)
+Each entry is a product/scope decision you could NOT make yourself — phrase it so the reader knows exactly what to decide and why it matters. These are distinct from follow-up actions (which are just work to schedule); a blocking decision changes the criteria/verdict depending on the answer.
+- Decision: <the choice to make> · Why it blocks: <which AC/scope/verdict is undetermined until this is answered> · If A → <consequence for the criteria/tests> · If B → <consequence>. Default if no answer: <the assumption you'll proceed on, marked `Assumption`>.
+```
+
+## Behavior-First Validation (the gate before saving)
+
+After drafting, validate and revise before saving. Mark `BLOCKED` only when the source lacks enough information/access to define observable behavior. Reject criteria or audit claims that rely on:
+
+- ACs phrased as calls to specific internal functions, or test matrices organized around implementation modules instead of user/system scenarios.
+- Mock-heavy plans that never exercise state changes, API contracts, permissions, events, or side effects; or substitutes standing in for internal seams (DB, service layer, internal endpoints, event bus) instead of external trust boundaries.
+- Requirement coverage mapped only to private-method/unit tests when integration, contract, or E2E is required.
+- Coverage classified `Covered` from prior docs/PR summaries/audit reports/issue comments/CI/agent claims without inspecting actual test code/assertions.
+- E2E audits that skipped deterministic route/endpoint discovery or reachability analysis.
+- Audits driven only test-outward (mock census, existing-test mapping) without requirement-inward reconciliation, so `Orphan surface` gaps stay invisible.
+- Reachable pages with write forms treated as covered by route/API/validator tests, without a mutation-form journey that fills the rendered UI and asserts the backend accepts the submission (split-contract form gap).