@1aboveio/skills 0.10.0

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

@@ -0,0 +1,119 @@
+# Review Contract Template (canonical)
+
+The single source of truth for the Review Contract — the PR-handoff artifact. `implement-and-pr` produces it; `review-pr` verifies against it. Keep this file canonical; both skills point here so the schema cannot drift. Producer-only fields (TDD Mode, RED/GREEN, Local Commands) are optional for non-TDD work; a reviewer treats them as evidence, not required structure.
+
+```markdown
+## Review Contract
+
+Source Work Item: <GitHub issue / PRD / design doc / spec / bug brief ID or link>
+Test Criteria: </docs/tests/YYYY-MM-DD-... link OR "Not required" + reason>
+TDD Mode: <Applied / Not applied + reason>
+Scope Class: <surface-bearing | no-surface + the matched classes — from `scope-class.mjs classify`, NOT self-declared. On `no-surface`, list each matched class's declared ORACLE and its result (or the declared unproven reason); a matched class with no oracle is a blocking finding, not a waiver. See scope-class.md.>
+Implementation Model: <model id the diff was actually written on (spawn read-back), + harness when ambiguous — e.g. "gpt-5.6-terra (codex)" / "sonnet-5 (claude code)". The durable record that makes cross-run model/harness comparison possible; under resolve-issues a contract missing it bounces at the pre-spawn check.>
+
+Invariant Class Closed (every fix round; omit on a first-round PR):
+- <per finding: the rule closed — not the cited line — plus the adjacent members (paths / fields / states / interleavings under that same rule) checked, with locators. One line each; "class = this call site, no siblings exist" is a complete answer where the rule genuinely covers one instance. The re-review reconciles against this and marks an instance-only repair `Partially resolved`.>
+
+Fix-Round Contract (high-risk state-machine/concurrency fix rounds only — resolve-issues/references/high-risk.md; omit the section otherwise):
+- Finding theme: <stable theme.id + kind + general violated contract>
+- State-machine/concurrency matrix: <every declared state × child/task-kind cell → test locator + execution-evidence locator>
+- Adjacent-state self-review: <one `{ state, evidenceLocator }` entry for every declared state>
+- Durable run record: <the matrix returned to the orchestrator under `fixRound`, and where it banked it — optional mechanization, when the run opted into the deep-audit layer. The producer returns it; it never writes the manifest itself.>
+
+Round-1 Depth Obligations (high-risk units only — resolve-issues/references/high-risk.md; omit the section otherwise):
+- Live endpoint probing: <completed + command/result evidence, or not-applicable + specific reason/evidence; never deferred>
+- Shared-consumer impact: <completed + consumer/evidence locators, or not-applicable + specific reason/evidence; never deferred>
+
+Acceptance Criteria Covered:
+- AC1: <summary> → <test file/test name/evidence>
+- AC2: <summary> → <test file/test name/evidence>
+
+Test Evidence:
+- CI: <workflow/link/result, pending, or blocker>
+- Tests Added/Updated: <files/test names>
+- Local Commands: <command + pass/fail summary>
+- RED/GREEN Evidence: <for TDD mode: failing test command/result then passing command/result per slice, or summary with logs; otherwise Not applicable>
+- Manual Evidence: <screenshots/logs/traces, if applicable>
+
+Obligation Impact (per ensure-coverage; omit only if no surfaces changed):
+- Surfaces added/changed: <surface id + kind/class>
+- Baseline/required level + proving test: <surface → @covers test file::name @level>
+- Coverage gate: <coverage-ledger.mjs validate result, or repo wrapper>
+- Presentation sweep: <e2e-test presentation-sweep result for changed browser routes, or N/A>
+- Exclusions/mock exceptions: <None / category+reason, gated>
+
+Mock/Fake Policy:
+- <where mocks/fakes are used and why they are sufficient>
+- <where integration coverage is used and what real components are exercised>
+
+Known Gaps:
+- None / <gap + explicit approval reference>
+
+Reviewer Focus:
+- <specific risks, edge cases, integration points, or ACs that need attention>
+```
+
+## A `no-surface` unit's inapplicable rows
+
+When `scope-class.mjs classify` returns `no-surface`, the rows below are recorded
+`Not applicable` **with the reason the classifier derived** — never generated first and
+marked N/A afterwards. Take them verbatim from `inapplicableArtifacts()` (the CLI's
+`inapplicable` field) so the reason names the matched classes rather than being retyped:
+
+- `coverage-checklist.mjs generate` / `validate` — no surface rows to fill
+- `coverage-ledger.mjs validate` — nothing enters the surface inventory
+- e2e route manifest + presentation sweep
+- TDD mode + the create-mode test-criteria gate
+
+What stays, on every class, and is never routed through the scope class: `scan-diff`'s
+findings channel (zero-tolerance), CI green on the exact head, the independent review on
+a different model (same spawn, same diversity rule, same verdict bar), and delivery
+recording. **`no-surface` ≠ low-risk** — merge/CI/deploy/IAM paths are config-only *and*
+set `highRisk: true`. Doctrine: [scope-class.md](scope-class.md).
+
+## What counts as valid AC evidence
+
+An `AC → test` line attests that the test **runs and asserts the behavior**. It is *not* PASS when backed by:
+
+- a **skipped** proving test (`test.skip(...)`), or one **guarded** into a no-op (`if (!data) test.skip()` / `if (!x) return`);
+- an assertion that passes on a **degraded page** (404 / not-found / empty / error) when the AC promises a real rendered result;
+- **CI being green** where that green came from skipping, guarding, or weakening assertions rather than fixing the cause.
+
+Tests are **never skipped** to clear an AC ([test-strategy.md](test-strategy.md); `e2e-test` → `references/authoring/test-skipping.md`). A missing precondition (no `payment_live` merchant, no session, an unapplied migration, an off flag) is **seedable** — seed it and let the test run; an un-sandboxable/flaky case goes to the quarantine lane (runs, non-blocking, `Unverified`). A disabled-test AC is `Missing`/`Unverified`, never PASS, and a `TODO`/issue link does not upgrade it.
+
+## Coverage Checklist (method-tagged; every row = decision + evidence)
+
+The AC table proves *the specified* behaviour. This checklist proves the **three coverage axes** (breadth / depth / presentation) — including surfaces no AC mentions. One rule for machine and model alike: **no row resolves without a decision (PASS / FAIL / N/A) backed by a checkable evidence locator** — a `file:line`, a rerunnable `` `command` ``, or a #issue. Prose ("looks fine") is not evidence. This stops both failure modes: an implementer can't bank "CI is green" for the judgment rows, and a reviewer can't wave a row through.
+
+Each row carries a **Method**, fixed by doctrine (the catalog in `ensure-coverage/scripts/coverage-checklist.mjs`), **not chosen per-PR**:
+
+- **gate-lint** — a tool decides and blocks; evidence = its command/output. **Auto-filled.**
+- **lead** — a tool surfaces candidates; you adjudicate each; evidence = the lead + verdict + `file:line`.
+- **judgment** — you reason from code; evidence = `file:line` + argument.
+
+**Produce it** with the assembler (gate rows come back filled with decision + evidence; lead/judgment rows come back as a skeleton to complete):
+
+```bash
+node <ensure-coverage>/scripts/coverage-checklist.mjs generate \
+  --diff <base> --ci <ci files> --ledger \
+  --sweep <presentation-results.json> --smoke <runtime-smoke-results.json>   # paste output below
+```
+
+Then complete every lead/judgment row with its locator. **Verify** before handoff and in review — the anti-ritual guard fails any PASS/FAIL row with no locator, any gate row left `TODO`, any cited `file:line` that does not **resolve** in the tree, and any gate row citing its command without the gate's result:
+
+```bash
+node <ensure-coverage>/scripts/coverage-checklist.mjs validate <this-checklist>.md --diff <merge-base>
+```
+
+**Pass `--diff`.** It is what makes a *missing* file decidable: paths this PR deletes are exempt (citing the over-mocked test you removed is true evidence that resolves to nothing on purpose), and without the diff the guard cannot tell that from a stale locator, so it warns instead of blocking. Locators sitting entirely outside the net diff are warned as possible pre-rebase leftovers. A line past the end of an existing file blocks either way — no deletion explains that. `--no-resolve` turns resolution off entirely, for a caller with no tree to resolve against.
+
+The rows and their methods are the single source of truth in the script; don't restate the full catalog here (it would drift). Paste the generated table; a completed row looks like:
+
+```markdown
+### Depth
+| Check | Method | Decision | Evidence |
+|---|---|---|---|
+| No test skipped/focused/xfail added | gate-lint | PASS | `lint-tests.mjs --rules no-skip --diff dev` → 0 findings |
+| Assertions are behavior-first; none pass on a 404/empty/error page | judgment | PASS | real checkout form asserted at `e2e/checkout.spec.ts:88` |
+| First-party interception is justified, not counted as coverage | lead | FAIL | intercepts `**/api/**` at `e2e/journeys/checkout.spec.ts:30` — re-point at seeded path |
+```

package/skills/engineering/ensure-coverage/references/process/scope-class.md

@@ -0,0 +1,178 @@
+# Scope class — which evidence artifacts apply to this unit
+
+Read this when a unit's whole diff is CI/policy config, docs, lockfiles or generated
+files, and the coverage artifacts have nothing to say about it. The mechanism is
+`scripts/scope-class.mjs`; this file is the doctrine it enforces.
+
+## The axis, and the axis it is NOT
+
+| axis | decides |
+|---|---|
+| `highRisk` (existing) | how deep the **review** goes |
+| `scopeClass` (this) | which coverage/evidence **artifacts** apply |
+
+They are orthogonal, and keeping them apart is the whole point. `.mergify.yml`, CI
+workflows, Dockerfile base images, IAM bindings and feature-flag defaults are all
+config-only *and* commonly high-risk. **`no-surface` ≠ low-risk.**
+
+Diff size is not blast radius. The incident this exists for
+(a consumer product repo, PR #1065) was a 12-line diff that removed
+`merge_protections_settings.auto_merge_conditions` — it changed who may merge to
+`main`. A rule of the form "config-only ⇒ lighter review" fires hardest exactly where
+it is most wrong. So the cut is never on review depth; it is on *which evidence
+artifacts are applicable*, which is a different question.
+
+The reviewer's own line from that PR, and the only artifact in the run that cost work
+and said nothing:
+
+> The generic coverage checklist was generated for the policy-only diff but is not
+> fully applicable without a dedicated checklist artifact.
+
+Everything else in that run was load-bearing: `mergify config validate`,
+`config simulate` against a live PR, the focused policy suite, `scan-diff` = 0 leads /
+0 findings.
+
+## Inferred from the diff, deny-by-default
+
+Not human-declared, and not at intake — there is no diff at intake. Classification
+runs at **producer close-out**, which already computes `merge-base...HEAD` for the
+evidence block.
+
+A unit is `no-surface` only if **every** path in the net diff matches an explicit
+non-runtime pattern. **One unmatched path ⇒ `surface-bearing`, full gates.** This
+fails in the cheap direction on purpose: misclassifying config as surface-bearing
+costs one useless checklist; misclassifying source as `no-surface` silently drops the
+breadth and depth gates. Everything ambiguous fails toward `surface-bearing` — an
+empty diff, a non-list input, a malformed config.
+
+**The corollary deny-by-default depends on: no changed path may reach the classifier
+in a form that hides what it is.** Every side of every change is a changed path, and
+anything the parser cannot take at face value fails toward `surface-bearing`.
+Deny-by-default is only as strong as the path list it is handed — a path the list never
+contains cannot be denied, and the classification then reads as clean. The instance
+that earned the rule: `git mv src/lib/auth.ts docs/auth-notes.md` classified
+`no-surface`, because only the post-image survived, so a diff that **deleted a runtime
+source file** looked like a docs edit. So the classifier emits **both sides** of every
+diff entry (rename and copy pre-images included), runs `git diff --name-only` with
+`--no-renames` so detection cannot collapse the pair one layer up, and refuses to glob
+a path it cannot read literally — a `..` segment (`docs/../src/app.ts` matches `docs/**`
+as a string and means `src/app.ts` as a file) or an unsplittable `diff --git` header
+lands in `unmatched` rather than being dropped or matched. Hazard row:
+`rename-preimage-escapes-path-classifiers`.
+
+**Test files do not break the classification.** PR #1065 touched
+`mergify-policy.test.ts` and must still classify `no-surface`. The guard against
+"weakened the test so the config passes" is not this table — it is `scan-diff`'s
+findings channel, which stays zero-tolerance for **every** class.
+
+The result lands on the run manifest as `units[].scopeClass` so `resolve-issues` step 2's
+pre-spawn check knows an absent checklist is legitimate rather than missing. **The
+producer does not write it** — it **returns** the classifier's JSON payload in its
+result and the orchestrator records it, because the orchestrator is the manifest's only
+writer (ADR 0001 decision 5 (`docs/adr/0001-interference-is-the-scheduling-primitive.md`)).
+**The manifest is the authority, never the producer's say-so** — without the recorded
+field, a `no-surface` unit would bounce to step 3 forever, waiting on a checklist that
+will never be generated.
+
+## One config table, two jobs
+
+The patterns and their oracles live together, because both are repo-specific and they
+answer one question: *this artifact is inapplicable — so what proves the change
+instead?*
+
+Built-in default set (print the resolved table with `scope-class.mjs table`):
+
+| class | patterns (abridged) | oracle | high-risk |
+|---|---|---|---|
+| `merge-policy` | `.mergify.yml`, `CODEOWNERS`, branch-protection config | `mergify config validate` + `config simulate` against a live PR | yes |
+| `ci-workflows` | `.github/workflows/**`, `.github/actions/**` | `actionlint` | yes |
+| `deploy-config` | `cloudbuild*.yaml`, `skaffold*.yaml`, `k8s/**`, `Dockerfile` | render/build without deploying (`skaffold render`, `kustomize build`, `docker build --check`) | yes |
+| `iam-policy` | `iam/**`, `*.iam.yaml`, `*.rego` | policy evaluation against the intended principals (`opa test`, `gcloud policy-troubleshoot`) | yes |
+| `docs` | `docs/**`, `*.md`, `*.mdx` | **none — declared**, so the reviewer knows it is unproven by design | no |
+| `lockfiles` | `package-lock.json`, `uv.lock`, `Cargo.lock`, … | install determinism: re-run the installer, then `git diff --exit-code` | no |
+| `generated` | `**/generated/**`, `*.generated.*`, `*.snap` | regen determinism: re-run the generator, then `git diff --exit-code` | no |
+| `tests` | `*.test.*`, `*.spec.*`, `tests/**`, `e2e/**` | run the changed test suite and paste its output | no |
+
+Tune it per repo in `coverage.config.json` → `scopeClass`:
+
+```json
+{
+  "scopeClass": {
+    "extraClasses": [
+      { "id": "terraform", "patterns": ["infra/**/*.tf"], "oracle": "`terraform plan` against the target workspace", "highRisk": true }
+    ]
+  }
+}
+```
+
+- `extraClasses` is **additive and checked first**, so a repo's own declaration wins
+  over an overlapping built-in guess.
+- `classes` **replaces** the table wholesale, for a repo that wants full control.
+- A malformed config falls back to the built-in defaults — a broken config must never
+  *widen* `no-surface`.
+
+### The oracle is a requirement, not a waiver
+
+**A matched class with no declared oracle is not a pass — it is the finding**
+(`oracle-undeclared`, blocking; the CLI exits 1). Write an oracle, or declare the
+class unproven-by-design (`"oracle": null` plus an `unprovenReason`), which forces the
+Review Contract to *say* the change is unproven rather than implying a gate covered
+it. An empty-string oracle is undeclared; a blank waiver is not a declaration.
+
+The oracle requirement is scoped to the `no-surface` lane. A surface-bearing unit
+already owes the full breadth/depth gates, so raising an oracle finding there would
+bill twice for the same obligation.
+
+## What `no-surface` drops
+
+Recorded `Not applicable` **with a reason derived from the scope class**, never
+generated-then-marked-N/A. `inapplicableArtifacts()` returns exactly these rows:
+
+- `coverage-checklist.mjs generate` / `validate` — no surface rows to fill
+- `coverage-ledger.mjs validate` — nothing enters the surface inventory
+- e2e route manifest + presentation sweep
+- TDD mode + the create-mode test-criteria gate
+
+**Smoke keeps the existing path**, it is not skipped: `gates.smoke = 'not-applicable'`
+plus a `smokeNotApplicableReason` (a reasoned N/A reaches ALIVE, an unreasoned one
+stays DEAD — `resolve-issues/scripts/combine-and-verify.mjs`). The only change is that
+the reason string is **derived** from the scope class (`scopeSmokeReason()`), not
+written per run. Less machinery than a skip, and no per-run prose.
+
+## What `no-surface` keeps — all of it
+
+`SCOPE_KEPT_OBLIGATIONS` in the script, identical for every class and asserted
+identical by its tests. If someone later tries to route a review obligation through
+this classifier, that constant is where it has to be added, in the open.
+
+- `scan-diff`'s findings channel — zero-tolerance for every scope class
+- CI green on the exact head
+- the independent review on a different model — **same reviewer spawn, same
+  model-diversity rule, same verdict bar**; an inferred scope class never lightens the
+  review
+- delivery recording with ancestry proof
+
+## Risk auto-flag (raise-only)
+
+Paths governing merge authority, CI, deploy and IAM set `highRisk: true` **while**
+setting `scopeClass: no-surface`. PR #1064 would have qualified and did not.
+
+The flag only ever moves **up**. The orchestrator's recording step ORs it in and can
+never write `false` over a set flag — otherwise a `no-surface` docs diff would clear
+the high-risk tier of a unit intake had already flagged, on the very round its scope
+was classified.
+
+## Usage
+
+```bash
+# at close-out, from the net diff the evidence block already computes
+git diff $(git merge-base origin/<target> HEAD)...HEAD \
+  | node <ensure-coverage>/scripts/scope-class.mjs classify --stdin --json > scope.json
+
+# then RETURN scope.json's contents in the spawn's result, under `scopeClass`.
+# The orchestrator records it on the unit — the manifest, not the producer, is the
+# authority, and the orchestrator is its only writer (ADR 0001 decision 5).
+```
+
+Exit codes: `0` classified (either class), `1` a blocking oracle finding, `2` usage
+error. `surface-bearing` is exit 0 — a normal, safe outcome, not a failure.

package/skills/engineering/ensure-coverage/references/process/test-strategy.md

@@ -0,0 +1,55 @@
+# Test Strategy (process)
+
+> Read when: choosing the required test level for an AC, classifying E2E type, or deciding whether a skip is allowed.
+
+## Test Level Selection
+
+Classify each AC before writing the matrix:
+
+- Logic AC: unit test is acceptable for pure decision logic or stable public contracts.
+- Boundary AC: contract/API test is required for request/response, validation, schema, compatibility, and error contracts.
+- Stateful workflow AC: integration test is required for DB writes, transactions, state transitions, idempotency, and recovery.
+- Async/pub-sub/orchestrator AC: integration test is required with real state store plus broker emulator or fake event adapter; assert final durable state and emitted events.
+- Critical money/security AC: integration, API E2E, or Journey E2E is required; mock-only coverage is never acceptable here, even with approval.
+- Browser/UI AC: UI E2E is required for page behavior, navigation, user-visible errors, forms, and role-dependent visibility.
+- Cross-page/core business journey: Journey E2E is required with real APIs where practical; do not mock internal endpoints unless explicitly approved.
+
+## E2E Coverage Rules
+
+When E2E is required, classify it explicitly and apply the `e2e-test` skill:
+
+- API E2E: endpoint behavior with real app; assert HTTP contract, auth/permissions, durable state, and side effects.
+- UI E2E: page/route behavior; assert loading, navigation, forms, user-visible behavior, auth, and error states.
+- Journey E2E: cross-page or core business flow; assert final outcome and side effects through real APIs where practical.
+
+## Golden-path smoke selection
+
+Smoke is not a separate browser-test level. A browser smoke path is a **curated E2E smoke journey**: it uses the same real-app/Playwright discipline as E2E, but only for the handful of journeys whose failure alone means "do not ship." Keep the classification separate:
+
+- **E2E obligation** — required by risk and surface behavior; broad functional/journey coverage belongs to the integration lane.
+- **Smoke membership** — release-critical selection from those obligations; small enough to run per-PR and reduced to ALIVE/DEAD by the `smoke` skill.
+
+You can use the generated surface inventory to suggest candidates (mutation routes, auth/payments-looking routes, health endpoints), but do not let code discovery decide the golden-path manifest. Product/release judgment must promote candidates into `smoke.manifest.json` and write concrete observables.
+
+For audit mode:
+
+- Run deterministic route/endpoint discovery before coverage judgment.
+- Include discovery method, discovered count, manifest count, missing/stale/uncovered entries, and changed-route coverage status.
+- Build the user journey inventory before mapping tests; route render-health tests do not prove a business journey unless they exercise the full flow and assert final outcomes.
+- Decompose every reachable dashboard/settings page into its mutation-form journeys (e.g. "operator creates a GitHub connector account"). For each, require UI/Journey E2E proof that the form renders every backend-required field and that submitting it produces a payload the backend accepts plus the expected durable state change. Reject backend-validator, schema-source, and API-forwarding tests as a substitute — they are proxy wiring for a split-contract form.
+
+## Test Skipping Policy (no-skip)
+
+The committed suite contains **only tests that run and assert**. A test is never disabled to get past a missing precondition or a failure — no `test.skip()` / `xit` / `describe.skip`, no conditional skip, no *disguised* skip (`if (!data) return` or any guard that no-ops the body while reporting **passed**). **The agent has no discretion to skip**: there is a non-skip answer for every case, and a disabled/guarded test doesn't even clear the gate — the ledger grades it not-covered and the render sweep reports `blocked`, never `pass`.
+
+There is **no allow-list** — "skip when it's outside your control" is the exact rationalization that ships false coverage. Map each case to a mechanism that keeps the **signal** or an honest **`Unverified`**:
+
+- **Missing state** (data, session, migration, flag, a specific entity status) → **seed it**; constructing it is the test's *arrange* step, not a blocker. The line is "can the agent create this state?", not "is it present now?"
+- **Third-party dependency** → **sandbox at the boundary** (sandbox + test keys; fake only the external adapter).
+- **Un-sandboxable external or a genuine flake** → **quarantine lane**: a non-blocking job that still *runs and reports* the test, surface graded blocking-but-attestable `Unverified`, with a dated exit. Run + report + don't-block ≠ stop running.
+- **Only valid on a specific platform/capability** → **route it** (matrix/tag); selection ≠ skip.
+- **Behavior not built yet** → land the test *with* the behavior (TDD red→green) or don't merge it yet.
+- **Obsolete / wrong test** → **delete it**, don't skip.
+- **Cannot run in any environment we control** → it isn't an automated test → a documented **manual-check**, tracked.
+
+**Annotation is not authorization:** a `TODO`/issue link doesn't make a skip acceptable — it's a confession the work was deferred (`TODO: re-enable when we seed …` means it was seedable). **Inherited** skips are pre-existing (a note, not a blocker per `review-pr` diff-discipline), but no PR may *add* one. E2E specifics + the full solutions map: `e2e-test` → `references/authoring/test-skipping.md`.

package/skills/engineering/ensure-coverage/schemas/coverage-config.schema.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "coverage-config.schema.json",
+  "title": "coverage.config.json",
+  "description": "Per-project config for ensure-coverage tooling, placed at the repo root. The mockPolicy block declares TOPOLOGY for the default-on, zero-tolerance mock-internal-seam lint rule (references/depth/mock-policy.md) — it tunes what counts as first-party; it does not enable/disable the gate.",
+  "type": "object",
+  "additionalProperties": true,
+  "properties": {
+    "mockPolicy": {
+      "type": "object",
+      "description": "Declares topology for lint-tests' mock-internal-seam rule via the externals-allowlist inversion: flag a mock of first-party code, exempt declared externals. The rule is default-on and cannot be disabled here.",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": true,
+          "description": "Inert / retained for compatibility. The mock-internal-seam gate is ZERO-TOLERANCE and default-on; setting this false does NOT disable it. Config declares topology, not on/off."
+        },
+        "firstPartyAliasPrefixes": {
+          "type": "array",
+          "items": { "type": "string" },
+          "default": ["@/", "~/"],
+          "description": "Import-specifier prefixes denoting first-party app source; a mock of one of these is treated as an internal seam."
+        },
+        "firstPartyPackages": {
+          "type": "array",
+          "items": { "type": "string" },
+          "default": [],
+          "description": "Bare package names — exact or scope prefix (e.g. \"@acme/\") — that are actually first-party workspace packages, so mocking them is an internal seam."
+        },
+        "externals": {
+          "type": "array",
+          "items": { "type": "string" },
+          "default": [],
+          "description": "Regex sources for specifiers that are legitimately external and therefore exempt (overrides first-party detection). Bare npm packages and node: builtins are already external by default; use this only for a first-party-looking specifier that is actually external/generated."
+        },
+        "testUtilHints": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Path segments that mark a relative import as a test util / fixture / mock rather than a production seam (e.g. __mocks__, fixtures, helpers)."
+        }
+      }
+    }
+  }
+}

package/skills/engineering/ensure-coverage/schemas/coverage-file.schema.json

@@ -0,0 +1,93 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://example.com/ensure-coverage/coverage-file.schema.json",
+  "title": "Per-requirement coverage file",
+  "description": "Curated, hand-authored, one per requirement document at docs/tests/<source>/<id>-<slug>.coverage.(yml|json). Declares ownership and intent only. It MUST NOT carry coverage status — status is computed by the aggregator so files for a shared surface cannot diverge.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["surfaces"],
+  "properties": {
+    "criteria": {
+      "type": "string",
+      "description": "Path to this requirement's test criteria doc, e.g. docs/tests/adr/0008-org-model-allowlist.criteria.md"
+    },
+    "surfaces": {
+      "type": "object",
+      "description": "Map of surface id (route/api/table/event id, matching the inventory) to its required coverage. May be empty for an accepted requirement with no runtime behavior.",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "description": "Deviation/ownership record for one surface. A surface needs NO entry here to be enforced — the Surface Baseline Contract auto-applies a floor from the inventory's (kind, class). An entry exists only to RAISE the floor, mark sensitive, exclude, attest, or attach ownership.",
+        "properties": {
+          "requiredLevels": {
+            "type": "array",
+            "description": "Raise the floor above baseline. Strictest required test levels for this surface (unioned with the auto-computed baseline; cannot lower it). Functional tokens: render-health, unit, integration, api, pg-api, browser-journey, journey, ui-e2e, e2e, no-secret-assertion. (`render-health` is a minimal browser reachability/render floor, used as the residual for the `static` exclusion category; it is the breadth-floor sibling of the presentation spine `presentation:render-health` and of e2e-test's Tier-1. The old token `smoke` is kept as a back-compat alias for `render-health`.) Presentation-axis tokens (proven against a real rendered page, never DOM-only): presentation:render-health (the spine — page renders without pageerror/console.error/error boundary/5xx), presentation:spatial, presentation:perceivability, presentation:reachability, presentation:temporal. Every browser route auto-carries the full presentation floor via the Surface Baseline Contract. These tokens are GRADED by the ledger; the e2e-test presentation sweep is the runner that emits per-(route,level) results (see ensure-coverage references/presentation/runner-contract.md).",
+            "items": { "type": "string" }
+          },
+          "sensitive": {
+            "type": "boolean",
+            "description": "Human-declared escalation for credential/admin/settings surfaces. Adds a contract + auth/tenant-isolation obligation on top of the mechanical floor. May only raise the bar, never lower it."
+          },
+          "verified": {
+            "type": "boolean",
+            "description": "Reviewer attestation that the resolved tests genuinely prove the behavior (assertions inspected, evidence confirmed). Promotes a statically-adequate surface from the blocking `Unverified` state to `Covered`. A self-declared @level alone never reaches `Covered`."
+          },
+          "excludeCells": {
+            "type": "object",
+            "description": "Gated removal of feature-derived escalation CELLS (e.g. `presentation:perceivability@dark`). Map of cell-qualified level -> { category, reason }. Only `@`-qualified cells may be excluded; the base mechanical floor can never be removed. Each removal is surfaced in the census.",
+            "additionalProperties": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["category", "reason"],
+              "properties": {
+                "category": { "type": "string", "description": "Why this cell is out of scope (e.g. deprecated, seed)." },
+                "reason": { "type": "string", "description": "Human-readable justification (printed in the census)." }
+              }
+            }
+          },
+          "exclude": {
+            "type": ["object", "null"],
+            "additionalProperties": false,
+            "description": "Mark the surface out of scope. PERMITTED ONLY when the adapter's reachability/class signals agree it cannot hurt a user — a reachable mutation route or a mutation API can never be excluded. Surfaced in a visible exclusion census.",
+            "required": ["category", "reason"],
+            "properties": {
+              "category": {
+                "type": "string",
+                "enum": ["seed", "static", "deprecated", "internal"],
+                "description": "Why this surface is out of scope."
+              },
+              "reason": {
+                "type": "string",
+                "description": "Human-readable justification (printed in the census)."
+              },
+              "gapIssue": {
+                "type": ["string", "null"],
+                "description": "Optional tracker link for the exclusion or a follow-up."
+              }
+            }
+          },
+          "uiOnly": {
+            "type": "boolean",
+            "description": "True if this surface is only reachable/asserted via UI."
+          },
+          "owner": {
+            "type": ["string", "null"],
+            "description": "Optional feature-card ownership: team or person responsible for this surface."
+          },
+          "purpose": {
+            "type": ["string", "null"],
+            "description": "Optional feature-card field: what this surface is for."
+          },
+          "userVisibleContract": {
+            "type": ["string", "null"],
+            "description": "Optional feature-card field: the user-visible contract this surface must uphold."
+          },
+          "gapIssue": {
+            "type": ["string", "null"],
+            "description": "Optional tracker link for a known, accepted coverage gap."
+          }
+        }
+      }
+    }
+  }
+}