@1aboveio/skills 1.0.10 → 1.0.12

package/skills/engineering/engineering-runtime/coherence/workflow.json

@@ -11,7 +11,7 @@
     "golden-path",
     "test-quality",
     "better-review",
-    "contributing",
+    "engineering",
     "engineering-runtime"
   ],
   "dependencies": [
@@ -369,7 +369,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "031c4e218b3dfb0121f74b4e48e8f8d4a2dc955d70797d9920aa266d8829a2df",
+      "contentDigest": "e1a3eda72480a554a71b876b0803ffadb6d975f57ce73e9ae84e3a30a75630bc",
       "digestExcludes": []
     },
     {
@@ -382,7 +382,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "a108e254528f4f89c203d4be08073317e11089863750740cae7d31bb0bec9750",
+      "contentDigest": "4976da3d810ab0a712121dfc5acbd62f63f8ae42ec0116431ad7d27d0c52a324",
       "digestExcludes": []
     },
     {
@@ -395,7 +395,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "1969444ee1b22ecd718c42dd75e8da3a7f384dc04060f242ea4d8926eccd1190",
+      "contentDigest": "32204a3fe185c2ea79eb27b0dd4055c321ef7b9f152ffc3a374b714ae8d465fa",
       "digestExcludes": []
     },
     {
@@ -408,7 +408,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "13913c28ec3d6f2cda2cef8df17b0c0229e66da96ec531f723e8050236d782ed",
+      "contentDigest": "6dc6606527c8023eb1f79a188ae73bea4fafe8b339ed391a00fae60340107e0c",
       "digestExcludes": []
     },
     {
@@ -421,7 +421,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "ae65114d4686a3e42fea5ee216f69448e3049e2cf41c686d6af97ffa6a2b48c3",
+      "contentDigest": "0ec4a9d50c9918d1219a2454ea2aad7eb3ffdabe917319c55d7928c6d5e3580e",
       "digestExcludes": []
     },
     {
@@ -434,7 +434,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "9f596a7f17fcdc0287e9a1b9bb420a8047c6c8793629f3aacbbd338a43c57b59",
+      "contentDigest": "388bd68865a9af12e76b1a522f879684546d5d03427649df5639b16d0b0240b9",
       "digestExcludes": []
     },
     {
@@ -447,7 +447,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "320de3be0dc062b20c287cdae31a32198bd290e5d9e83dda890e504bf50d3e8d",
+      "contentDigest": "d7552f7681020f9cd4ed72dbde105adb5b172e40ba4119bcbb0d4685688faf18",
       "digestExcludes": []
     },
     {
@@ -460,7 +460,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "13d7951bed3a526753ccce1f5f400fee30dfaada36ce362d6e9a5a67c83c118d",
+      "contentDigest": "414606c12207509b0d9207b0021dbb29bcb1689ca7d7486496ab2bc6a1dfecfc",
       "digestExcludes": []
     },
     {
@@ -473,7 +473,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "39d02dc25b30f40632b4332d14ebaeaff4397c7252ebb894443df176d7739d10",
+      "contentDigest": "274f5ac6be3224dfdafaa4264cfa0ed223e3b98cf3cbd2c083b6c85314a92791",
       "digestExcludes": []
     },
     {
@@ -486,20 +486,20 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "ea35adb4a3fb7a46a45b4c101cbee4d5c25d7f4e18f7c6000e93000b2b8b4081",
+      "contentDigest": "a6efa258db14db8a4cab8600bcbdc2563c61531a51a486508ed42da70824be86",
       "digestExcludes": []
     },
     {
-      "installName": "contributing",
+      "installName": "engineering",
       "ownership": "owned",
-      "sourcePath": "skills/engineering/contributing",
+      "sourcePath": "skills/engineering/engineering",
       "expectedSource": {
         "id": "first-party",
         "type": "first-party",
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "09b9bac7f5a4ff63cb27e011e919d2c4c29738c134fe0f073319ae8b0e9b6e2d",
+      "contentDigest": "869bf4214b7e80e4968e4488f2f6ad4a944b2393a343ad40157e45f694457814",
       "digestExcludes": []
     },
     {
@@ -512,13 +512,13 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "69a5829eb7e0f1c59bbdf18b907312d9343fa586fe9c55c5cba780d4184b8c08",
+      "contentDigest": "bc78899c2a745aedee9f547a16b8c2be2ffab8a128695b033991802d033db303",
       "digestExcludes": [
         "coherence/workflow.json"
       ]
     }
   ],
-  "releaseIdentity": "144e6cbba9378e0b509e185b471c53b30dc90b742409004debb068ce4d39ab9d",
+  "releaseIdentity": "fed4e4c161cf525a08eee89fb30ba578ec21962b2d4cb9c9226fc61146fe4225",
   "lifecycleAuthority": "native-skills-cli",
   "repairRecipe": {
     "id": "engineering-workflow-dependency-first",
@@ -589,17 +589,17 @@
           "golden-path",
           "test-quality",
           "better-review",
-          "contributing",
+          "engineering",
           "engineering-runtime"
         ],
         "commands": [
           {
             "transport": "https",
-            "command": "npx skills@1.5.22 add 1aboveio/ai --global --agent universal claude-code --skill harness-runtime e2e-test ensure-coverage rush-issues resolve-issues rush-release resolve-release golden-path test-quality better-review contributing engineering-runtime && npm --prefix \"$(realpath \"$HOME/.agents/skills/engineering-runtime/scripts\")\" ci --ignore-scripts"
+            "command": "npx skills@1.5.22 add 1aboveio/ai --global --agent universal claude-code --skill harness-runtime e2e-test ensure-coverage rush-issues resolve-issues rush-release resolve-release golden-path test-quality better-review engineering engineering-runtime && npm --prefix \"$(realpath \"$HOME/.agents/skills/engineering-runtime/scripts\")\" ci --ignore-scripts"
           },
           {
             "transport": "ssh",
-            "command": "npx skills@1.5.22 add git@github.com:1aboveio/ai.git --global --agent universal claude-code --skill harness-runtime e2e-test ensure-coverage rush-issues resolve-issues rush-release resolve-release golden-path test-quality better-review contributing engineering-runtime && npm --prefix \"$(realpath \"$HOME/.agents/skills/engineering-runtime/scripts\")\" ci --ignore-scripts"
+            "command": "npx skills@1.5.22 add git@github.com:1aboveio/ai.git --global --agent universal claude-code --skill harness-runtime e2e-test ensure-coverage rush-issues resolve-issues rush-release resolve-release golden-path test-quality better-review engineering engineering-runtime && npm --prefix \"$(realpath \"$HOME/.agents/skills/engineering-runtime/scripts\")\" ci --ignore-scripts"
           }
         ],
         "onFailure": {

package/skills/engineering/engineering-runtime/scripts/workflow-policy.mjs

@@ -16,7 +16,7 @@ export const WORKFLOW_OWNED_MEMBERS = deepFreeze([
   'golden-path',
   'test-quality',
   'better-review',
-  'contributing',
+  'engineering',
   'engineering-runtime',
 ]);
 

package/skills/engineering/ensure-coverage/SKILL.md

@@ -2,128 +2,41 @@
 name: ensure-coverage
 description: "Define or audit behavior-first test criteria — ACs, required test levels, mock/integration/E2E policy — across three axes: breadth (Coverage Ledger), depth (over-mocking), presentation (perceivability of browser surfaces). NOT judging whether a single test is any good (test-quality), authoring browser tests (e2e-test), reviewing a PR (better-review), or delivering issues (resolve-issues)."
 disable-model-invocation: true
-release-version: 0.44.1
+release-version: 0.45.1
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Ensure Coverage
 
-Define **what must be proven** before a change is ready. This skill states obligations and grades evidence; it does not run CI, wire gates, author tests, or issue merge verdicts.
+Define what must be proven for the agreed business outcome and material risks. This skill scopes criteria and grades evidence; it does not implement tests, wire gates, or issue a merge verdict.
 
-- **Create mode** — turn an ADR, PRD, spec, issue, or bug brief into `/docs/tests/YYYY-MM-DD-<slug>-criteria.md` ([template](references/process/output-template.md)).
-- **Audit mode** — grade existing code and tests against those criteria into `/docs/tests/YYYY-MM-DD-<slug>-audit.md` ([steps](references/process/audit-mode.md)).
+- **Create mode:** agree observable criteria and suitable proof before implementation. Record them in the issue or conversation; create a criteria document only when requested or required by the repository.
+- **Audit mode:** assess evidence against the agreed scope. A feature audit stays scoped to the feature; a whole-repo census is appropriate only for an explicitly requested broad audit. Use the [audit guidance](references/process/audit-mode.md) and [optional output template](references/process/output-template.md).
 
-No source document? Derive candidate ACs from the issue, repro steps, sibling flows, or the public surface. Mark inferred behavior `Assumption` and undecided product questions `BLOCKED`. Never invent product semantics.
+Read the relevant source and governing project guidance. When product behavior or authorization is unclear and blocks the task, ask the owner; do not invent semantics or add planning handoffs for ordinary implementation choices. Keep agreed criteria stable during implementation and proof. A newly discovered concrete defect may need a fix; speculative robustness ideas and test preferences are follow-ups, not new acceptance conditions. Escalate a proposed scope change for agreement.
 
-## Stance: it ships broken until proven otherwise
+## Scope and proof
 
-Default to "not ready" and make the code earn the verdict. The one question: **if this launched now, how likely is a real user to hit a bug in the first week?**
+- Choose the smallest sufficient proof for the outcome and material risks; reuse existing tests and required CI results when they prove the behavior. Do not automatically require multiple test layers, a ledger, a criteria document, a presentation campaign, or reconciliation of every ADR.
+- Existing required repository checks and adopted coverage floors remain binding unless an approved change alters them. Authentication, money, tenancy, and data-integrity protections remain binding. Read applicable ADRs and project policy for the touched work, not every ADR in the repository.
+- Consider breadth, depth, and presentation where relevant: what behavior is in scope, whether evidence actually exercises it, and whether a user can perceive and use a changed interface. Do not turn every axis or hypothetical state into a separate blocking obligation.
+- The [surface baseline](references/breadth/surface-baseline.md) is guidance for selecting proof, not a universal new floor. The bundled ledger and presentation tools implement stricter mechanical rules; use them only when requested or already required, and report their actual results without claiming their defaults are new policy.
+- Avoid tests that bypass the behavior they claim to prove, especially for security or durable state. Select boundaries and test levels for the risk, following applicable repo rules ([mock policy](references/depth/mock-policy.md), [strategy](references/process/test-strategy.md)). A relevant existing test can suffice; characterization and fails-first runs are useful when warranted, not automatic requirements ([characterization](references/depth/characterization.md)).
+- Do not weaken or disable tests merely to get green. Report a required check that cannot run or fails; do not claim it passed.
+- Do not recommend or wire new CI gates unless asked. Existing required checks still apply ([CI contract](references/enforcement/ci-contract.md)). Integrated release campaigns run at their assigned gate, not automatically for each feature.
 
-- A test you have not read is not coverage. State what each passing test exercises and what it silently skips.
-- Walk what a user does first — open the page, fill the form, submit, hit the error path — and name the test that proves each step.
-- Name the concrete failure ("username dropped, submit returns 400"), not "coverage is partial."
-- End with an explicit ship / no-ship call and the counts that drive it. Never round up to `Covered` to be agreeable.
+## Grade honestly
 
-## Three axes
+Inspect the relevant test and its assertions before claiming it proves a behavior. A passing execution proves it ran, not that it covered every claim. Use [grading](references/depth/grading.md): `Covered`, `Partial`, `Missing`, `Wrong Level`, `Over-mocked`, `Unverified`, `Excluded`, or `BLOCKED`. Describe what the evidence proves and what remains unverified; never promote a hypothetical state to a blocker merely because it lacks a test. Missing agreed proof, a concrete material defect, or a failed required check can block; distinguish those from follow-ups. Report unavailable evidence or unresolved decisions without a false success.
 
-Each axis is blind to the others' failure; a coverage claim holds only when all three pass.
+## Workflow and output
 
-- **Breadth** (requirement-inward): did we enumerate everything that must be proven? Catches surfaces with no test at all. Output is a **complete surface census**, never a top-N list.
-- **Depth** (test-outward): does each test prove the behavior against real state? Catches false green: over-mocking, proxy wiring, shallow assertions, wrong level.
-- **Presentation** (render-outward): can a human *see and act on* the rendered page? Catches the invisible control, the overlapping layout, the route nothing links to.
+1. Identify the agreed outcome, touched behavior, material risks, required repo checks, and applicable guidance. Resolve only decisions needed to proceed.
+2. Agree observable acceptance criteria and sufficient proof before implementation. Note existing proof and select focused additions only where needed.
+3. For an audit, inspect relevant tests and results, grade the agreed scope, and report concrete gaps, blockers, and non-blocking follow-ups. Do not expand criteria after the fact. An explicitly requested broad audit may use [surface discovery](references/breadth/surface-discovery.md) and the [coverage ledger](references/breadth/coverage-ledger.md); state any limits on its completeness.
+4. Record what was verified, what was not, and why. Use the repository's existing format or a concise response; no new document is required by default.
 
-## The obligations
-
-**Every surface owes a floor the moment it exists.** A requirement doc is not a precondition. The floor keys off the surface's kind and class, computed mechanically; humans may raise it or exclude through a gated path, never lower it. A reachable mutation route can never be excluded. Full table, taxonomy keys, exclusion gate: [surface-baseline](references/breadth/surface-baseline.md).
-
-| kind | class | owes | the test must show |
-|---|---|---|---|
-| route | read / detail | browser-journey | real rendered data, no first-party mock |
-| route | mutation | browser-journey | fill the real form → backend accepts → durable state changes |
-| route | +sensitive | + api | + auth / tenant isolation |
-| api | read | api | status, shape, auth |
-| api | mutation | api + integration | durable state changed |
-| api | +sensitive | + auth | mandatory auth / tenant isolation |
-| table / event / job | — | none (transitive) | dead-surface warning if nothing reaches it |
-
-**Every browser route also owes the presentation floor**, proven only against a real rendered page at `[375, 1280]`: `render-health` (no page error, console error, error boundary, or first-party 5xx, held *through* interactions), `spatial` (no overflow or overlap), `perceivability` (visible, contrast-passing controls; absent things are absent), `reachability` (navigable from an entry point, focus visible, ≥44px targets), `temporal` (no first-party layout shift). A functional journey satisfies none of these; a DOM-only assertion is `Over-mocked`. A unit that cites a design source also owes `fidelity`: expected values read off the source, rendered side by side ([axis](references/presentation/axis.md)).
-
-**Real internals, faked externals, nothing in between.** Substitute only at a boundary you do not own (third-party APIs, providers, clock, randomness). Never mock-only: DB transactions, idempotency, concurrency, events/outbox/retry, auth and tenant isolation, schema compatibility, orchestrator recovery. A journey that intercepts first-party traffic proves proxy wiring, not behavior. Over-mocked is worse than untested: fix it or delete it ([policy](references/depth/mock-policy.md)).
-
-**Prove the test would fail.** Modifying existing behavior owes a characterization test that passes on the pre-change tree. A bug fix owes a test red before the fix. A feature test counts only if it would go red were the behavior removed ([characterization](references/depth/characterization.md)).
-
-**No test is skipped, disabled, guarded into a no-op, or weakened to get green.** Missing state is seeded. Un-sandboxable flake goes to a quarantine lane that still runs and reports. Obsolete tests are deleted ([strategy](references/process/test-strategy.md)).
-
-**Every accepted ADR with runtime behavior owns a criteria doc and a coverage file.** An ADR that changes behavior with no proof attached is the un-spec'd route's mirror image: stated intent nobody checked. An ADR with no runtime behavior says so in its text; a known gap names a tracked issue. Mechanized by the ledger's acceptance gate ([ledger](references/breadth/coverage-ledger.md)).
-
-**Every AC maps to a named test at the required level.** Read the test to judge what it proves. A green run of it (exit 0) is the only execution proof needed: do not collect logs, screenshots, traces, or read-backs on top. Prior docs and PR summaries are leads, never proof.
-
-**Assign each obligation to its gate.** Coding acceptance is proven per change, by the tests at the required level, and stops once they pass. Integrated release acceptance (a device or system campaign, all-ABI or signed builds, cross-feature journeys) runs once at the release or campaign gate the spec or repository assigns it. A change's verdict never depends on that campaign and never claims it passed; record it once, as pending, in its owning issue. Define the criteria before execution; never expand them or add evidence obligations while proving them.
-
-**Gates are added by humans only.** Do not recommend, require, wire, or audit for CI gates unless the user explicitly asks. A repo with no coverage gates in CI is not a finding. The gate menu ([ci-contract](references/enforcement/ci-contract.md)) and `ci-audit.mjs` are opt-in tools for when the user asks for gates.
-
-**CI has one supported gate: curated golden-path smoke.** The ledger, inventory freshness, presentation sweep, broad E2E suite, test lint, over-mock scan, design parity, and quarantine expiry are audit and review evidence, not CI gates. When the user asks about CI coverage, propose or audit only the real-app golden-path smoke contract ([ci-contract](references/enforcement/ci-contract.md)); `ci-audit.mjs` checks only that smoke wiring.
-
-## Classifications
-
-Full definitions: [grading](references/depth/grading.md). Whether a single test is any good is `test-quality`'s call; how its labels become these grades, and which smells are lint rules versus reviewer leads: [test-smells](references/depth/test-smells.md). A self-declared level is a claim to refute, never a pass.
-
-- **`Covered`** — inspected test proves the behavior at the required level, acceptable mocks. The ledger shows it once the test is marked read (`verified: true`).
-- **`Partial`** — some behavior tested; edge cases, failures, permissions, state, or evidence incomplete.
-- **`Missing`** — no meaningful test maps to the obligation.
-- **`Wrong Level`** — a test exists but is too shallow for the risk.
-- **`Over-mocked`** — mocks bypass the behavior under test.
-- **`Unverified`** — satisfied statically; nobody has marked the test read yet. A warning, not a block, unless the user turns on `unverifiedBlocks`. No evidence is required unless the user asks for it.
-- **`Excluded`** — human-declared out of scope with category and reason, permitted by the gate, visible in the census.
-- **`BLOCKED`** — source, code, tests, environment, or a product decision is unavailable.
-
-## Workflow
-
-1. **Understand the source.** Read the accepted ADRs (`docs/adr`, status accepted) that govern the touched surfaces; they are a requirement source, not background. Pick the output path; list observable behavior; mark assumptions and blockers.
-2. **Model correctness.** Number the ACs, name the critical journeys, assign each a required level ([levels](references/process/test-strategy.md)).
-3. **Plan coverage.** Test matrix, mock policy, E2E needs.
-4. **Grade all three axes.** Enumerate every surface ([discovery protocol](references/breadth/surface-discovery.md); the adapter's output shape is the [inventory contract](references/breadth/inventory-contract.md)), grade each test by reading it, confirm each browser route's presentation floor. Reconcile every accepted ADR against the census: one with runtime behavior and no coverage file is a finding.
-5. **Validate and decide.** Reject implementation-shaped, over-mocked, skipped, or incomplete coverage. Verdict at the top.
-
-## Deliverable
-
-Verdict first, then the evidence that justifies it ([full template](references/process/output-template.md); worked examples: [refund flow](references/examples/refund-flow.md), [ledger](references/examples/coverage-ledger.md)):
-
-```markdown
-## Verdict: Ship / No-ship — <one-sentence reason with the driving counts>
-## Source · Scope · Assumptions · Blockers · Design source (or `none`)
-## Acceptance Criteria (numbered, observable, independently testable)
-## Critical Journeys (actor, start state, trigger, end state, side effects)
-## Test Matrix (scenario · AC · level · mock policy · setup · assertions · proving test)
-## Surface Census (audit) — one row per surface, status, proving test or —
-## Gaps and follow-ups (each with level, setup, assertions)
-## Blocking Decisions (product choices that change the verdict)
-```
-
-## Common wrong answers
-
-- Green CI is not coverage. Read the test.
-- An API test under a page does not prove the page.
-- "Every ADR covered" is not "every surface covered." And an accepted ADR with no coverage file is a gap, not a pass.
-- A write form covered by a validator or schema test is not covered. Only a rendered-form submission proves the form emits what the backend accepts.
-- Excluding a surface is not fixing it. Exclusion is gated and visible.
-- "The script isn't in the audited repo" is not `BLOCKED`. The scripts live in this skill; run them against the repo.
-- A top-3 gap list is not an audit. Emit the census.
-- "Out of scope" excludes behaviors, never the axis the unit is about.
-
-## Mechanization
-
-The decidable parts of these obligations are decided by scripts, not prose. Every script lives under **this skill's directory** (the path you read this file from). Set `SKILL_DIR` to it and run `node "$SKILL_DIR/scripts/<name>.mjs"`. Never resolve a script against your CWD, and never locate one with `find` over `$HOME`; if `SKILL_DIR` is unknown, stop and ask. Usage and flags: [scripts/README.md](scripts/README.md).
-
-| script | decides |
-|---|---|
-| `coverage-ledger.mjs` | breadth accounting: every surface's floor owned and proven; grades depth and presentation from `@covers`/`@level`; with `requirementGlobs`, every accepted ADR or PRD owns a coverage file with criteria or a tracked gap |
-| `lint-tests.mjs` | added skips, fixed timeouts, empty tests, swallowed assertions, and mocks of first-party seams (zero-tolerance) |
-| `design-parity.mjs` | the built page matches the cited design source |
-| `check-quarantine-expiry.mjs` | a dated quarantine exit re-blocks when it expires |
-| `ci-audit.mjs` | CI wires curated golden-path smoke as a blocking check |
-
-In audit mode, always run the over-mock scan whole-tree and count every hit in the verdict.
+The scripts in this skill are optional tools unless the repo already requires them. Set `SKILL_DIR` to this skill's directory and see [scripts/README.md](scripts/README.md) for usage. Their fixed checks and outputs can be broader or stricter than the agreed feature scope; do not silently change or bypass an adopted gate. Escalate conflicts rather than presenting tool defaults as policy.
 
 ## Downstream
 
-This skill defines what must be proven. `test-quality` judges whether each test is any good (one bar, one skip rule, shared with this skill). `e2e-test` authors browser tests and runs the presentation sweep as review evidence. `golden-path` checks the do-not-ship subset of the critical journeys against a running app and is the sole CI gate ([ci-contract](references/enforcement/ci-contract.md), verified by `ci-audit.mjs`). `resolve-issues` delivers and reviews through `better-review`. Some rules (no skips, fake only externals) are deliberately repeated in `e2e-test` and `golden-path` so each works on its own; this skill is the source when they differ.
+`test-quality` judges individual tests; `e2e-test` authors browser tests; `golden-path` owns curated release-critical journeys; `resolve-issues` delivers and `better-review` provides independent review. Other skills and existing repository policy may still carry stricter requirements: preserve them and surface conflicts to the appropriate owner rather than silently overriding them.

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

@@ -2,6 +2,8 @@
 
 > Read when: building or auditing the breadth axis — reconciling requirement sources against the surface inventory. Holds both the **doctrine** (what the ledger is) and the **mechanics** (how to operate it). Siblings: [surface-baseline.md](surface-baseline.md) (the floor each surface owes), [surface-discovery.md](surface-discovery.md) (how surfaces are found), [inventory-contract.md](inventory-contract.md) (the discovery adapter), [examples/coverage-ledger.md](../examples/coverage-ledger.md) (worked shapes).
 
+This reference describes an optional ledger and its existing mechanical behavior, not a requirement to create a ledger or reconcile all ADRs for routine features. Use it when requested or already required by the repository. Its errors and floors remain binding when an existing required check enforces them; seek approval rather than bypassing or silently changing that policy. A whole-repo census requires an explicitly requested broad audit.
+
 ## Doctrine: the ledger is a reconciliation, not an anchor
 
 Breadth is a reconciliation of independent enumerations, never a single anchor. **No one requirement source is complete** — anchoring only on ADRs misses surfaces nobody wrote an ADR for; anchoring only on code misses intent that was never built.
@@ -22,7 +24,7 @@ Once a row is `Aligned` (or an `Orphan surface` carrying its baseline floor), th
 
 ## Three layers
 
-Separate discovery, curated intent, and the generated aggregation; let CI reconcile them. Status is **computed, never stored**, so per-requirement files for a shared surface cannot diverge — there is no status field to disagree on.
+When using the ledger, separate discovery, curated intent, and the generated aggregation; reconcile them where requested or already required. Status is **computed, never stored**, so per-requirement files for a shared surface cannot diverge — there is no status field to disagree on.
 
 - **Generated inventory** (never hand-edited): surface discovery from code — routes, APIs, tables, events. Regenerated on every change.
 - **Curated coverage** (hand-maintained, one file per requirement at `docs/tests/<adr|prd|design>/<id>-<slug>.coverage.yml`): the surfaces that requirement owns, each with required test level, `uiOnly`, criteria link, optional gap issue. Ownership and intent only — **not** status.
@@ -53,9 +55,9 @@ The aggregation maps `@covers` → surface, checks required levels, flags intern
 
 ## Acceptance gate
 
-Make coverage a precondition of accepting a requirement, not an optional follow-up.
+When the repository has adopted this ledger acceptance gate, follow its configured requirements. Otherwise this is an optional mechanism, not a new acceptance gate.
 
-- Every accepted requirement with runtime behavior must own `docs/tests/<source>/<id>-*.coverage.yml` that links its `criteria` doc, before it can merge; the requirement's own PR adds both.
+- If the adopted gate requires it, an accepted requirement with runtime behavior owns `docs/tests/<source>/<id>-*.coverage.yml` linked to its `criteria` doc.
 - A known gap is declared, not hidden: the coverage file names a `gapIssue` or `gapDoc` in place of `criteria` while the gap is open.
 - A requirement with no runtime behavior (pure architecture, terminology) says "no runtime behavior" in its own text and needs no coverage file.
 - The gate is mechanical: `coverage.config.json` → `requirementGlobs: { adr: "docs/adr" }` (and `prd`, `design`, …); `coverage-ledger.mjs validate` then errors on every accepted document with no coverage file, or a coverage file with neither criteria nor a tracked gap. `acceptedMarker` overrides the default `status: accepted` / `**Status:** accepted` match.
@@ -74,7 +76,7 @@ The breadth axis is enforced by checks that fail (error) or warn:
 - required level is integration/API/journey but only unit/mock evidence resolves;
 - internal interception counted as behavior coverage (`Over-mocked`).
 
-Run reconciliation during the audit regardless of who authored the change. Keep the generated inputs deterministic and report stale inventory rather than repairing it during an audit. This validator is evidence for the coverage verdict, not a CI gate; curated golden-path smoke is the sole CI gate ([CI contract](../enforcement/ci-contract.md)).
+Run reconciliation when requested or required by the repository, within the authorized scope. Keep generated inputs deterministic and report stale inventory rather than repairing it during an audit. Existing required CI checks remain binding; do not add a gate without authorization ([CI contract](../enforcement/ci-contract.md)).
 
 ## Reference validator
 
@@ -87,6 +89,6 @@ node ~/.agents/skills/ensure-coverage/scripts/coverage-ledger.mjs validate [--co
 node ~/.agents/skills/ensure-coverage/scripts/coverage-ledger.mjs report                       # markdown index + ADR matrix view
 ```
 
-**Outputs.** `aggregate` writes the surface-keyed `coverage-index.json` **and** a sibling `coverage-metrics.json` — roll-up counts plus the **over-mock rate** (`overMocked / tested` depth-graded surfaces, split `overMockedBehavior` / `overMockedPresentation`). The metric is a separate file, not a key in the index. `validate` and the `report` header print the rate inline (`N/T tested surfaces over-mocked (X%)`). The over-mock *count* is zero-tolerance in the audit verdict ([../depth/mock-policy.md](../depth/mock-policy.md)); the *rate* lets the reviewer **trend honesty as the suite grows** (a count rises just from more tests, a rate does not).
+**Outputs.** `aggregate` writes the surface-keyed `coverage-index.json` **and** a sibling `coverage-metrics.json` — roll-up counts plus the **over-mock rate** (`overMocked / tested` depth-graded surfaces, split `overMockedBehavior` / `overMockedPresentation`). The metric is a separate file, not a key in the index. `validate` and the `report` header print the rate inline (`N/T tested surfaces over-mocked (X%)`). Treat the over-mock count as a lead to inspect in context ([../depth/mock-policy.md](../depth/mock-policy.md)); the *rate* is a trend signal, not an automatic feature blocker. An adopted required gate retains its configured result.
 
 Surface *discovery* is the one repo-specific piece — supply an inventory adapter per [inventory-contract.md](inventory-contract.md) (a reference Next.js one ships at `scripts/adapters/nextjs-inventory.mjs`). Curated files follow `schemas/coverage-file.schema.json`.

package/skills/engineering/ensure-coverage/references/breadth/surface-baseline.md

@@ -2,7 +2,7 @@
 
 > Read when: computing the minimum required-level floor a surface owes. The breadth axis enumerates surfaces; this is the floor each one carries the instant it's discovered. Sibling refs: [coverage-ledger.md](coverage-ledger.md) (the ledger that holds these obligations), [surface-discovery.md](surface-discovery.md) (how surfaces and their `reachability` are found), [inventory-contract.md](inventory-contract.md) (the adapter that emits the taxonomy).
 
-A requirement source (ADR/PRD/spec) is **not** a precondition for a test obligation. Most production gaps are organically-added routes nobody wrote an ADR for; if coverage waited on someone authoring a requirement, the surface would sit silently uncovered. So **every surface in the inventory carries a minimum required-level floor the instant it is discovered**, graded at depth automatically — safe by default. Orphan detection alone is worthless without a *default obligation* attached; it just relocates the judgment call to whoever notices — the session-variance that produced the gaps.
+Use the table as guidance when selecting proof for the agreed scope and material risks, not as a universal obligation for newly discovered surfaces. Existing repository-adopted floors and required checks remain binding unless changed through approval. A requirement document is not needed to recognize a concrete risk. The rules below describe the bundled ledger's mechanical defaults when it is used, not new policy for every feature.
 
 **The baseline keys off an adapter-emitted taxonomy, never inference at grading time** — inference-per-session is how "covered" came to mean different things. The adapter tags each surface deterministically so two agents on the same code compute the same floor.
 
@@ -27,9 +27,9 @@ Baseline only **entry surfaces** (`route`, `api`). **Internal surfaces** (`table
 | permission | — | `integration` | resolves an auth test |
 | integration (external) | — | fake adapter + contract | — |
 
-Every **live browser route is `browser-journey` at minimum** — `class` changes only *what the journey additionally proves*, not *whether* you drive the page. A genuinely static/content page (marketing, docs) is downgraded via the **`static` exclusion category** to a `render-health` floor — a cheap reachability guarantee, never weakening the floor for real app pages. (`smoke` is accepted as an alias for this level; it is not the curated `smoke` gate, which is a cross-flow liveness check, not a per-route level.) **`render-health` is a browser-level check, not an API ping**: a real browser must load the rendered page and confirm it renders without error (externals may be faked). An HTTP-200 / API-level test does **not** satisfy it. The other exclusion categories (`seed`/`deprecated`/`internal`) drop to manifest-only. `render-health` is the one level a present-but-shallow test can satisfy, precisely because it is definitionally shallow. (Same "page loads/renders" concept as e2e-test's Tier-1 and the `presentation:render-health` spine.)
+In the ledger, every **live browser route is `browser-journey` at minimum** — `class` changes only *what the journey additionally proves*, not *whether* you drive the page. A genuinely static/content page (marketing, docs) is downgraded via the **`static` exclusion category** to a `render-health` floor — a cheap reachability guarantee, never weakening the floor for real app pages. (`smoke` is accepted as an alias for this level; it is not the curated `smoke` gate, which is a cross-flow liveness check, not a per-route level.) **`render-health` is a browser-level check, not an API ping**: a real browser must load the rendered page and confirm it renders without error (externals may be faked). An HTTP-200 / API-level test does **not** satisfy it. The other exclusion categories (`seed`/`deprecated`/`internal`) drop to manifest-only. `render-health` is the one level a present-but-shallow test can satisfy, precisely because it is definitionally shallow. (Same "page loads/renders" concept as e2e-test's Tier-1 and the `presentation:render-health` spine.)
 
-Every live browser route *also* auto-carries the **Presentation floor** on top of the functional floor above — see [../presentation/axis.md](../presentation/axis.md).
+In the ledger, every live browser route *also* auto-carries the **Presentation floor** on top of the functional floor above — see [../presentation/axis.md](../presentation/axis.md).
 
 ## Exclusion is gated, not honored on a reason
 
@@ -41,4 +41,4 @@ An exclusion downgrades a surface to manifest-only — the exact move that re-op
 
 ## The feature card is a deviation record, not a precondition
 
-Because the baseline auto-applies, a surface with no requirement is **not blocked on authoring a file** — it is already graded at its floor. A curated `…coverage.yml` (the "feature card") is required only to **deviate**: raise above baseline, mark `sensitive`, exclude, attest (`verified`), or attach `owner`/`purpose`/`userVisibleContract` ownership. Pure happy-path baseline surfaces need no card. Requirement *ownership* (traceability) is a `warn`; the baseline *test obligation* is the hard gate.
+When using the ledger, because its baseline auto-applies, a surface with no requirement is **not blocked on authoring a file** — it is already graded at its floor. A curated `…coverage.yml` (the "feature card") is required only to **deviate**: raise above baseline, mark `sensitive`, exclude, attest (`verified`), or attach `owner`/`purpose`/`userVisibleContract` ownership. Pure happy-path baseline surfaces need no card. Requirement *ownership* (traceability) is a `warn`; the baseline *test obligation* is the hard gate.

package/skills/engineering/ensure-coverage/references/breadth/surface-discovery.md

@@ -4,13 +4,13 @@
 >
 > **Guard-chain vs navigational reachability.** This protocol determines **guard-chain** reachability — "can the URL load past middleware/auth." That is *different* from `presentation:reachability` ([../presentation/axis.md](../presentation/axis.md)), which is **navigational** — "can a user *click* their way here from an entry point." A route can be guard-reachable yet navigation-orphaned. Both matter; they are different checks.
 
-Use this inline protocol for E2E audits even if `e2e-test` is unavailable. Route discovery is not complete after listing route files; verify whether each route can actually be reached through layouts, middleware, redirects, guards, rewrites, and route groups. For Next.js App Router and similar file-based routers:
+Use this protocol within the agreed audit scope, even if `e2e-test` is unavailable. Enumerate the whole repository only for an explicitly requested broad audit. For scoped work, inspect relevant routes and their reachability as needed; the following describes comprehensive discovery for Next.js App Router and similar file-based routers:
 
 1. Enumerate all `page.*` and `route.*` files, including route groups, dynamic segments, parallel/intercepting routes, and exported HTTP methods for `route.*`. Tag each by kind — **browser route** (`page.*`) or **API route** (`route.*`) — because they carry different depth obligations and proof types ([../depth/grading.md](../depth/grading.md)). Never let one stand in for the other.
 2. For each page route, walk the layout chain root → route group → segment; inspect `layout.*`, `middleware.*`, redirects, `notFound`, auth/session checks, role/tenant guards, feature flags, rewrites.
 3. Classify reachability as `Reachable`, `Redirected`, `Guarded`, `Blocked`, or `Unknown`, with the guard/layout/middleware evidence.
-4. For each `Reachable` page, inventory its user-actionable mutations (forms, submit buttons, write actions) and the backend endpoint each targets. Record one **journey obligation** per mutation (operator completes form → backend accepts → state changes), separate from the page merely rendering. A write form with no journey test is uncovered, even when the route renders.
+4. For relevant `Reachable` pages, identify user-actionable mutations and their backend targets. Distinguish rendering from submission and durable-state evidence; select proof based on agreed criteria and material risks, not an automatic journey obligation per mutation.
 5. Cross-reference discovered routes against PRD/spec claims, route manifests, navigation links, product journeys, and the golden-path candidate list. Discovery may suggest golden-path candidates, but the golden-path contract is curated: a route is not release-blocking merely for being a mutation route or containing an auth/payment-looking word.
-6. Flag routes that are unreachable, misplaced, stale, missing from the manifest, absent from code, or contradicting design docs — and reachable pages whose mutation forms have no journey coverage.
+6. Report relevant concrete gaps and unavailable evidence. Treat missing journey coverage according to agreed criteria and existing required floors, not as an automatic feature blocker.
 
 Do not classify a route as covered, missing, or part of a valid journey solely because a `page.*`/`route.*` file exists — a route file is only a declared route until its guard chain and journey validity are checked.

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

@@ -1,68 +1,7 @@
-# Depth: Characterization — pin existing behavior before you change it
+# Characterization and fails-first evidence
 
-> 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.
+When changing existing behavior, consider whether a relevant existing test already protects the behavior that should stay unchanged. Reuse it if sufficient. Add a characterization test when the risk of unintended change warrants it; it captures actual behavior at an observable boundary, including quirks. Do not require a new test or pre-change run for every source edit, or introduce a seam solely to satisfy a blanket rule.
 
-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.
+For a bug fix, a test that fails before the fix and passes afterward can show that the fix addresses the defect. Use it when practical and useful or when repository policy requires it; otherwise explain the proof and any limitation. A feature test should make meaningful assertions about the agreed outcome, not just a mock call or a fixture that bypasses the real behavior. Inspect it before claiming coverage; a broken-tree run is not automatically required.
 
-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.
+If an existing adopted gate requires annotations, a pre-change run, or other evidence, follow it unless an approved change alters the gate. Grade evidence honestly using [grading](grading.md).

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

@@ -2,11 +2,9 @@
 
 > 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`.
+A depth failure occurs when a substitute bypasses the behavior a test claims to prove. For example, a Playwright interception of an endpoint cannot prove that endpoint's real behavior. Grade that claim `Over-mocked`, not `Covered`; a focused UI test may still prove its own scope. See the [mock policy](mock-policy.md).
 
-**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.
+Distinguish what API and browser evidence actually proves. An API test alone does not prove a rendered form works; a UI test that fakes the backend does not prove durable state. Select the proof needed for the agreed outcome and material risk, reusing existing evidence where sufficient. A rendered end-to-end submission can expose split-contract form failures, but is not an automatic new obligation for every form. Existing adopted floors and required checks remain binding.
 
 ## Evidence Hierarchy
 
@@ -25,11 +23,11 @@ Classify coverage as `Covered` only after inspecting the relevant test file/case
 
 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.
+- `Covered` (green, terminal): inspected test code validates the agreed AC at the appropriate level with meaningful assertions and acceptable mock/fake use. A self-declared `@level` alone never reaches it. The ledger additionally requires its `verified: true` attestation.
+- `Partial`: some agreed behavior or material-risk proof is incomplete. An untested hypothetical state alone is not an automatic blocker.
 - `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.
+- `Over-mocked` (red, terminal): substitutes bypass the behavior the agreed AC must prove. For example, an intercepted endpoint cannot prove its real durable-state path; the test may still prove a narrower UI behavior.
 - `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.