@1aboveio/skills 0.10.0

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

@@ -0,0 +1,166 @@
+const deepFreeze = (value) => {
+  if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+    for (const child of Object.values(value)) deepFreeze(child);
+    Object.freeze(value);
+  }
+  return value;
+};
+
+export const WORKFLOW_OWNED_MEMBERS = deepFreeze([
+  'e2e-test',
+  'ensure-coverage',
+  'implement-and-pr',
+  'resolve-issues',
+  'resolve-release',
+  'review-pr',
+  'smoke',
+  'engineering-runtime',
+]);
+
+export const HARNESS_RUNTIME_DEPENDENCY_MEMBERS = deepFreeze([
+  'harness-runtime',
+]);
+
+export const MATT_DEPENDENCY_MEMBERS = deepFreeze([
+  'batch-grill-me',
+  'code-review',
+  'codebase-design',
+  'diagnosing-bugs',
+  'domain-modeling',
+  'grill-me',
+  'grill-with-docs',
+  'grilling',
+  'handoff',
+  'improve-codebase-architecture',
+  'prototype',
+  'research',
+  'resolving-merge-conflicts',
+  'setup-matt-pocock-skills',
+  'tdd',
+  'to-spec',
+  'to-tickets',
+  'triage',
+  'wayfinder',
+]);
+
+// Per-invoked-skill closure, generated from SKILL.md dependencies plus cross-member
+// runtime imports. Order follows the coherence member census so the same tree always
+// produces the same identity. A generated file remains part of its owner's content
+// digest and is also named explicitly so a scoped verdict reports every identity used.
+export const WORKFLOW_TRUSTED_DEPENDENCY_CLOSURES = deepFreeze([
+  {
+    invokedSkill: 'resolve-issues',
+    members: [
+      'tdd',
+      'harness-runtime',
+      'e2e-test',
+      'ensure-coverage',
+      'implement-and-pr',
+      'resolve-issues',
+      'review-pr',
+      'smoke',
+      'engineering-runtime',
+    ],
+    generatedIdentities: [
+      { member: 'resolve-issues', path: 'generated/workflow-repair-policy.json' },
+    ],
+  },
+  {
+    invokedSkill: 'resolve-release',
+    members: [
+      'harness-runtime',
+      'e2e-test',
+      'ensure-coverage',
+      'resolve-issues',
+      'resolve-release',
+      'review-pr',
+      'smoke',
+      'engineering-runtime',
+    ],
+    generatedIdentities: [
+      { member: 'resolve-issues', path: 'generated/workflow-repair-policy.json' },
+    ],
+  },
+]);
+
+// First-party content is distributed as an exact public npm release, so its identity is the package
+// and version rather than a private repository at a moving branch. The private checkout remains a
+// render target of the same manifest for local development, but it is not what an installed Workflow
+// is verified against: `revision: 'main'` is scoped to that target and never reaches coherence.
+// External sources keep their immutable reviewed revision — the migration is first-party only.
+export const WORKFLOW_TRUSTED_SOURCES = deepFreeze({
+  firstParty: {
+    id: 'first-party',
+    type: 'first-party',
+    package: '@1aboveio/skills',
+    version: '0.10.0',
+  },
+  matt: {
+    id: 'matt-pocock',
+    type: 'external',
+    repository: 'https://github.com/mattpocock/skills',
+    revision: 'ed37663cc5fbef691ddfecd080dff42f7e7e350d',
+    reviewedTree: '04b0fcb78e3de7c58744fcba2528354cc64ab988',
+  },
+});
+
+const nativeSkillsPrefix = 'npx skills@1.5.22 add';
+const nativeSkillsTarget = '--global --agent universal claude-code --skill';
+const externalArchiveLimits = 'SKILLS_DOWNLOAD_MAX_BYTES=33554432 SKILLS_EXTRACT_MAX_FILES=4096 SKILLS_EXTRACT_MAX_BYTES=67108864';
+const mattMembersArgument = MATT_DEPENDENCY_MEMBERS.join(' ');
+const firstPartyMembers = deepFreeze([
+  ...HARNESS_RUNTIME_DEPENDENCY_MEMBERS,
+  ...WORKFLOW_OWNED_MEMBERS,
+]);
+const publicPackageRelease = `${WORKFLOW_TRUSTED_SOURCES.firstParty.package}@${WORKFLOW_TRUSTED_SOURCES.firstParty.version}`;
+
+// The public package/group flow, which expands the same dependency-first recipe the steps below
+// document and delegates every write to the pinned native CLI. `--yes` is deliberately absent: repair
+// runs against an installation that is already missing, modified or mixed, which is exactly when the
+// native overwrite summary and its consent prompt are the point. The generated recipes withhold the
+// flag for the same reason, and repair guidance must not be the one place that pre-approves a
+// destructive overwrite.
+export const WORKFLOW_TRUSTED_REPAIR_RECIPE = deepFreeze({
+  id: 'engineering-workflow-dependency-first',
+  generatedFrom: 'skills/distribution/generated/recipes.json',
+  groupId: 'engineering-workflow',
+  lifecycle: 'install',
+  renderTarget: 'public-npm',
+  stopOnFailure: true,
+  steps: [
+    {
+      sourceId: 'matt-pocock',
+      sourceType: 'external',
+      repository: WORKFLOW_TRUSTED_SOURCES.matt.repository,
+      revision: WORKFLOW_TRUSTED_SOURCES.matt.revision,
+      installPath: null,
+      members: MATT_DEPENDENCY_MEMBERS,
+      commands: [{
+        transport: 'https',
+        command: `${externalArchiveLimits} ${nativeSkillsPrefix} https://codeload.github.com/mattpocock/skills/tar.gz/${WORKFLOW_TRUSTED_SOURCES.matt.revision} ${nativeSkillsTarget} ${mattMembersArgument}`,
+      }],
+      onFailure: {
+        action: 'stop',
+        message: 'Source matt-pocock fetch failed; stop this recipe before running another source.',
+      },
+    },
+    {
+      sourceId: 'first-party',
+      sourceType: 'first-party',
+      package: WORKFLOW_TRUSTED_SOURCES.firstParty.package,
+      version: WORKFLOW_TRUSTED_SOURCES.firstParty.version,
+      installPath: null,
+      members: firstPartyMembers,
+      commands: [
+        {
+          transport: 'npm',
+          command: `npx ${publicPackageRelease} install --group engineering-workflow`,
+        },
+      ],
+      onFailure: {
+        action: 'stop',
+        message: 'Source first-party fetch failed; stop this recipe before running another source.',
+      },
+    },
+  ],
+});

package/skills/engineering/ensure-coverage/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2026 1AboveIO

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

@@ -0,0 +1,136 @@
+---
+name: ensure-coverage
+description: "Define or audit behavior-first test criteria — ACs, required test levels, evidence expectations, mock/integration/E2E policy — across three axes: breadth (Coverage Ledger), depth (over-mocking), presentation (perceivability of browser surfaces). NOT the merge verdict on a PR (review-pr), authoring browser tests (e2e-test), or driving issues to PRs (resolve-issues)."
+---
+
+# Ensure Coverage
+
+Use this skill to define what must be proven before implementation is ready. Convert a PRD, design doc, feature spec, bug brief, GitHub issue, or equivalent into a behavior-first test criteria document under `/docs/tests/`. Use audit mode to compare existing code/tests against those criteria and produce concrete coverage gaps.
+
+This file is the **spine** — the mental model, the workflow, and a map to the detail. The mechanics (tables, templates, protocols, contracts) live in `references/`, grouped by axis; load a reference only when the step needs it (see [Reference Map](#reference-map)). The spine alone is enough for the common path.
+
+## Modes
+
+- **Create mode** — before or during implementation, when the user needs test criteria, acceptance criteria, or a test matrix.
+- **Audit mode** — when reviewing whether current code/tests sufficiently cover a requirement, PR, issue, feature, or bugfix. Steps: [process/audit-mode.md](references/process/audit-mode.md).
+
+## Inputs And Outputs
+
+Required input:
+
+- A PRD, design document, feature spec, bug brief, GitHub issue, or equivalent source-of-truth requirement.
+- For audit mode: relevant code paths and existing tests, or enough repo access to inspect them.
+- If no source document exists, derive candidate ACs from the best available source: issue brief, repro steps, screenshots, sibling flows, public API/code surface, existing behavior, or explicit design decisions.
+
+Required output:
+
+- Create mode: `/docs/tests/YYYY-MM-DD-<feature-slug>-criteria.md` (template: [process/output-template.md](references/process/output-template.md)).
+- Audit mode: `/docs/tests/YYYY-MM-DD-<feature-slug>-audit.md`.
+- Mark inferred behavior `Assumption` and unclear product decisions `BLOCKED`; do not invent product semantics.
+
+## Stance: Assume It Ships Broken Until Proven Otherwise
+
+Audit adversarially. Default to "not ready" and make the code earn the verdict. Run every audit against one question: **if we launch to production right now, how likely is a real user to hit a bug, and how confident are you that no bug report lands in the first week?** A green suite is a claim to be attacked, not an answer.
+
+- Treat each passing test as a suspect: state what it actually exercises and what it silently skips. A test you have not read does not count as coverage.
+- Walk the first things a real user does — open the page, fill the form, submit, take the error path — and name the test that proves each. If you cannot, that is a predicted bug report.
+- Name the concrete failure: "username field is dropped, submit returns 400" beats "form coverage is partial."
+- End with a verdict, not a vibe: an explicit ship / no-ship call, the scenarios that would generate bug reports, and the evidence that would raise confidence.
+- When behavior is unproven, say not ready. Do not round up to `Covered` to be agreeable.
+
+## Coverage Has Three Axes: Breadth, Depth, And Presentation
+
+Coverage is three orthogonal questions audited in different directions. Drive all three; each is blind to the others' failure.
+
+- **Breadth (completeness), requirement-inward**: did we identify everything that must be proven? Enumerate obligations from sources of truth and reconcile against what the system exposes. Catches *invisible gaps* — surfaces nobody audited, obligations with no test at all. A closed-world enumeration problem, so an audit emits a **complete surface census** (every surface with a status; gaps = non-`Covered`/`Excluded` rows), never a "top gaps" highlight reel. → `references/breadth/`, completeness rules in [process/audit-mode.md](references/process/audit-mode.md)
+- **Depth (fidelity), test-outward**: does each test actually prove the behavior against real state? Catches *false green* — over-mocking, proxy wiring, shallow assertions, wrong level, stale/unverified evidence. → `references/depth/`
+- **Presentation (perceivability), render-outward**: for a browser surface, can a human *see and act on* the rendered page, not just does the DOM exist? Catches what a green functional journey sails past — an invisible control, overlapping/overflowing layout, layout shift, a route nothing links to. → `references/presentation/`
+
+Depth without breadth is honest tests of an incomplete set. Breadth without depth is a complete-looking ledger full of proxy-wiring green. Both can pass while a control sits invisible on the page — that is the Presentation axis's job. **A coverage claim is trustworthy only when all three axes pass.** Absence produces no signal from the test side, so only requirement-inward enumeration finds a surface with no tests; and neither functional axis can tell that a present, clicked-by-tests control is unperceivable to a user.
+
+## Coverage Classifications (the shared vocabulary)
+
+Every axis grades obligations with the same eight terms. A self-declared `@level` is a claim the validator must try to **refute** — it never alone reaches `Covered`. Full definitions: [depth/grading.md](references/depth/grading.md).
+
+- **`Covered`** (green) — inspected test proves the behavior at the required level with acceptable mocks, **and** is reviewer-attested.
+- **`Partial`** — some behavior tested; edge cases, failures, permissions, state, or evidence incomplete.
+- **`Missing`** — no meaningful test maps to the obligation ("required and built but untested" is this, not a breadth gap).
+- **`Wrong Level`** — a test exists but is too shallow for the risk (e.g. unit-only for a stateful workflow).
+- **`Over-mocked`** (red) — mocks bypass the behavior under test: a journey intercepting first-party traffic (`page.route`/`route.fulfill`/MSW), or a mutation journey that never resolves a real durable-state path.
+- **`Unverified`** (blocking yellow) — satisfied statically but assertion/execution quality unconfirmed; **blocks** the gate until a reviewer attests `verified: true`.
+- **`Excluded`** — human marked out of scope with category + reason, adapter signals permitting; surfaced in the exclusion census.
+- **`BLOCKED`** — required source, code, tests, route discovery, environment, or product decision unavailable.
+
+## The Surface Baseline (the floor every surface owes)
+
+A requirement (ADR/PRD/spec) is **not** a precondition for a test obligation. **Every surface in the inventory carries a minimum required-level floor the instant it is discovered**, graded automatically — safe by default, not safe-if-someone-remembers. The floor keys off an **adapter-emitted taxonomy** (`class`, `reachability`), never per-session inference, so two agents on the same code compute the same floor. Humans may only **raise** the floor (`sensitive`) or **exclude** through a gated path — never weaken the mechanical floor; a `reachable` `mutation` route can never be excluded. A curated `…coverage.yml` ("feature card") is needed only to *deviate*, not to enable coverage.
+
+The floor table, the taxonomy keys, the exclusion gate, and the feature card: [breadth/surface-baseline.md](references/breadth/surface-baseline.md). Every live browser route *also* auto-carries the **Presentation floor** (spine: `presentation:render-health`) on top: [presentation/axis.md](references/presentation/axis.md).
+
+## Core Principles
+
+Separate test design from implementation, and test observable behavior, not internal structure.
+
+- Planner defines ACs/matrix/evidence/gates before coding; coding agent implements tests mapped to the approved criteria; reviewer rejects shallow/over-mocked/implementation-shaped tests; human approves risk decisions, mock-only exceptions, and unautomated ACs.
+- Tests prove externally visible outcomes: user/system behavior, durable state, contracts, permissions, side effects, events, failure handling — not private functions, unless that unit *is* the public contract.
+- **Mock boundary:** real internals, faked externals, nothing in between. A substitute for an internal seam (DB, service layer, internal endpoint, event bus) is a gap, not a choice. Full policy: [depth/mock-policy.md](references/depth/mock-policy.md).
+- **Characterize before you change.** Adding a new surface is TDD red→green; *modifying* existing behavior owes the inverse — a **characterization test that pins the current behavior and passes on the pre-change tree** before you edit it, so the diff is proven not to shift observable behavior by accident (tag `// @characterizes <surface>`; waive only with a cited pre-existing test or a declared intended change). Full policy: [depth/characterization.md](references/depth/characterization.md).
+- **Prove it fails first — a test is evidence only if it would go red when the behavior is broken.** One rule, two cases: a **bug-fix** test must be red on the pre-fix tree (tag `// @fails-without-fix <surface>`), and a **feature-AC** test must go red were the AC's behavior removed — exercise the AC's real code path, not a proxy. Grading splits: can't-yet-confirm-it-would-fail is `Unverified` (blocking); confirmed-it-would-still-pass is `Missing`/`Over-mocked` (worse than unchecked). The decidable vacuous forms ride `lint-tests` (`no-swallowed-assertion`, `no-fixed-timeout`); the "would it have been red?" property is verified at review. Full doctrine and waiver rules: [depth/characterization.md](references/depth/characterization.md) → "Fails-first".
+- **Evidence order:** test code first, then execution evidence, then code discovery; prior docs/PR summaries/CI logs are leads, never proof of coverage *quality*. Full hierarchy: [depth/grading.md](references/depth/grading.md).
+- **Obligation ≠ placement.** A surface's coverage *obligation* — what must be proven, at what level, honestly (no skip / over-mock / vacuous assertion) — is fixed by risk and **non-negotiable**. *Where and when* the proof runs (per-PR lane, integration-branch gate, nightly, release lane) is a separate cost/latency decision owned by CI config and the orchestrators (`resolve-issues`, `cloud-build`, `cloud-deploy`), not this skill. Demoting the broad functional+journey suite to the integration lane is legitimate tuning; using "placement" as cover to drop, skip, or weaken it is not. The **per-PR floor** every PR pays never negotiates down: the `presentation:render-health` sweep and a curated E2E `smoke` gate. Each honest-proof property is enforced **as early as it is decidable** (static checks ride the edit-time hook / per-PR `lint-tests`; smoke rides the implementer's local run). Full lane model: [enforcement/ci-contract.md](references/enforcement/ci-contract.md) → "Three lanes".
+
+## Workflow
+
+1. **Understand the source** — choose the dated output path, identify observable behavior, mark assumptions/blockers/product decisions needing confirmation.
+2. **Model correctness** — write numbered ACs, identify critical journeys, classify each by required test level ([process/test-strategy.md](references/process/test-strategy.md)).
+3. **Plan coverage** — build the test matrix, mock/integration policy, E2E needs, required evidence ([process/output-template.md](references/process/output-template.md)).
+4. **Audit or gate — drive all three axes:**
+   - *Breadth* — reconcile requirement sources against the surface inventory into the Coverage Ledger; flag `Orphan surface` / `Unrealized requirement` / `Stale link` before judging any test ([breadth/coverage-ledger.md](references/breadth/coverage-ledger.md)). Run route/surface discovery first ([breadth/surface-discovery.md](references/breadth/surface-discovery.md)).
+   - *Depth* — verify actual test code before trusting prior claims; classify each obligation; name concrete gaps ([depth/grading.md](references/depth/grading.md)).
+   - *Presentation* — for each browser route, confirm its `presentation:*` floor is proven against a real rendered page (a functional journey does not satisfy it; DOM-only is `Over-mocked`). **If the unit's source cites a design artifact** (prototype branch/path, mockup, layout-fixing design doc), it also owes `presentation:fidelity` — every other level is self-referential and cannot ask whether the page matches the thing it was derived from ([presentation/axis.md](references/presentation/axis.md)).
+   - *Enforcement* — audit that CI actually wires the gates ([enforcement/ci-contract.md](references/enforcement/ci-contract.md)).
+5. **Validate** — reject implementation-shaped, over-mocked, skipped, or incomplete coverage; revise until the Behavior-First Validation checklist passes or mark explicit blockers ([process/output-template.md](references/process/output-template.md)).
+
+## Reference Map
+
+Load the reference for the step you're on — not all of them.
+
+| When you need to… | Read |
+|---|---|
+| build/aggregate the Coverage Ledger, `@covers` convention, the validator | [breadth/coverage-ledger.md](references/breadth/coverage-ledger.md) |
+| compute a surface's baseline floor (table, taxonomy keys, exclusion gate, feature card) | [breadth/surface-baseline.md](references/breadth/surface-baseline.md) |
+| enumerate surfaces / classify guard-chain route reachability | [breadth/surface-discovery.md](references/breadth/surface-discovery.md) |
+| supply the repo's surface-inventory adapter | [breadth/inventory-contract.md](references/breadth/inventory-contract.md) |
+| grade test depth (classifications, split-contract trap, evidence hierarchy, terminal states) | [depth/grading.md](references/depth/grading.md) |
+| characterize existing behavior before modifying it (the obligation, `@characterizes`, owed/waived, grading) | [depth/characterization.md](references/depth/characterization.md) |
+| diagnose a test smell + decide gate vs. lead (Erratic/Missing-Assertion/Slow/Fragile/Obscure/Over-mocked) | [depth/test-smells.md](references/depth/test-smells.md) |
+| decide what may be mocked | [depth/mock-policy.md](references/depth/mock-policy.md) |
+| work a presentation invariant (render-health spine, spatial, perceivability, navigational reachability, temporal, mutate-health) **or the opt-in `presentation:visual` pixel baseline** | [presentation/axis.md](references/presentation/axis.md) |
+| build against a cited design source — prototype, mockup, design doc — and prove the deliverable matches it (`presentation:fidelity`, the parity manifest) | [presentation/axis.md](references/presentation/axis.md) → `presentation:fidelity` |
+| the presentation sweep runner interface (what the `e2e-test` sweep must satisfy) | [presentation/runner-contract.md](references/presentation/runner-contract.md) |
+| wire or audit CI gates (incl. the `ci-audit.mjs` meta-gate + lifecycle gates) | [enforcement/ci-contract.md](references/enforcement/ci-contract.md) |
+| wire the in-loop gate hooks (edit-time skip lint, stop-time coverage gate, tiering, escape hatch) | [enforcement/hooks.md](references/enforcement/hooks.md) |
+| write the criteria/audit doc (template, writing rules, behavior-first validation) | [process/output-template.md](references/process/output-template.md) |
+| choose test levels / E2E type / skipping policy | [process/test-strategy.md](references/process/test-strategy.md) |
+| run an audit end to end | [process/audit-mode.md](references/process/audit-mode.md) |
+| the canonical Review Contract schema (used by implement-and-pr + review-pr) | [process/review-contract-template.md](references/process/review-contract-template.md) |
+| decide whether the coverage artifacts apply at all to a config-only/docs-only unit (the `no-surface` scope class, its pattern→oracle table, what it never drops) | [process/scope-class.md](references/process/scope-class.md) |
+| worked examples | [examples/refund-flow.md](references/examples/refund-flow.md) · [examples/coverage-ledger.md](references/examples/coverage-ledger.md) |
+
+## Scripts
+
+**Resolving these scripts.** Every `scripts/<name>.mjs` below is under **this skill's own directory** — the absolute path you read this `SKILL.md` from — **not your working directory** (a spawned agent's CWD is the target repo, where `scripts/…` does not resolve). Set `SKILL_DIR` to that directory and invoke `node "$SKILL_DIR/scripts/<name>.mjs"`. Never resolve a script against your CWD, and **never locate one with `find` over `$HOME` / `/Users`**; if `SKILL_DIR` is unknown, stop and ask.
+
+- `scripts/coverage-ledger.mjs aggregate|validate|report` — the breadth accounting gate (also grades depth + presentation from `@covers`/`@level` annotations).
+- `scripts/ci-audit.mjs --files <ci configs>` — the meta-gate: verifies CI wires the required gates and keeps them blocking. `--adoption` turns an unwired/pre-existing CI into a ready-to-file wiring issue (gap-scoped checklist + matching template + bootstrap step); pipe into `to-issues` so the contract installs itself through the normal loop.
+- `scripts/coverage-checklist.mjs generate|validate` — the method-tagged **Coverage Checklist** for the [Review Contract](references/process/review-contract-template.md), spanning all three axes. `generate` auto-fills the **gate-lint** rows from the tools (lint-tests, ledger, ci-audit, presentation sweep, and runtime smoke via `--smoke <results.json>`) and leaves **lead/judgment** rows as a skeleton; `validate` is the anti-ritual guard — every PASS/FAIL row must carry a checkable locator (`file:line` / `` `command` `` / #issue), no gate row left `TODO`. The method per row is doctrine-fixed in the script's catalog (never chosen per-PR); a judgment row whose evidence becomes mechanizable is promoted to a gate-lint rule.
+- `scripts/evidence-block.mjs collect|validate|render` — generates the **volatile half** of the [Review Contract](references/process/review-contract-template.md) instead of letting an author retype it: scan channels (via `review-pr/scripts/scan-diff.mjs`), the exact-head CI job table, SHAs, and the production-diff-emptiness proof, all stamped with the HEAD they describe. `validate` fails when the stamp is not current HEAD, so staleness is a command's verdict rather than a reviewer's catch. Repo-specific suite results come in via `--ingest` and carry the same stamp; reuse of an earlier probe must be `reused: true` with a note and cannot be `Pass`, and a skipped CI job is reported skipped, never folded into passed. Durable claims — what the PR proves, which rows are `Partial/Unverified` and why — stay hand-written; only the machine-derivable numbers move here. Wired as the `evidence-block` job in `e2e-test/assets/ci-gates.*`, because the producer running it is an instruction to do something last and a later commit re-stales it silently.
+- `scripts/lint-tests.mjs --diff <base>` — static **test-lint gate engine**: deterministic, ~zero-false-positive checks blocking on what a diff **adds** (`--rules a,b` for a subset). Always-on authoring rules `no-skip`, `no-fixed-timeout`, `no-empty-test`, `no-swallowed-assertion`, plus the default-on zero-tolerance depth rule `mock-internal-seam` (a `vi.mock`/`jest.mock` of a first-party seam — no waiver, no grandfathering; fix by correcting topology in `coverage.config.json`, never disable). Decidable shell only; the judgment remainder stays a review lead (`review-pr` → `scripts/scan-diff.mjs`). Full catalog + `RULES` registry: [enforcement/ci-contract.md](references/enforcement/ci-contract.md) → "Static lint gates" · [depth/mock-policy.md](references/depth/mock-policy.md). Wired as the `lint-tests` job in `e2e-test/assets/ci-gates.*`.
+- `scripts/design-parity.mjs scaffold|probe|validate` — the **fidelity gate** for a unit built from a cited design source. `scaffold` emits a parity-manifest skeleton from a doctrine-fixed catalog (page measure, container plane, per-viewport type scale, box, coupled rhythm, plus a relational primary>secondary row) so the properties a hand-written list forgets are already in the file; `probe` emits the JS that measures the built page; `validate --observed <results.json>` blocks on a TODO row, a rejection with no real reason, a `from:` citation that does not resolve in the source blob, a catalog row missing for a declared role, or any measured divergence. **Not a differ** — comparing across stacks (HTML/Figma source vs React deliverable) is judgment, so only the check against the extracted manifest is mechanized. **Not `presentation:visual`** — every `expected` is read off the *source*, where a pixel baseline is captured from the implementation and so ratifies whatever shipped. Reduced form (no `--observed`) announces itself on stderr. Doctrine + the named incident: [presentation/axis.md](references/presentation/axis.md) → `presentation:fidelity`.
+- `scripts/check-quarantine-expiry.mjs` — the **auto-resurface gate**: a `@quarantine(until=…)` exit sits non-blocking until its date, then **expires and re-blocks** so the quarantine lane can't decay into a silent permanent skip. Run in the blocking lane ([enforcement/ci-contract.md](references/enforcement/ci-contract.md)).
+- `scripts/scope-class.mjs classify|table` — infers a unit's **scope class** from its net `merge-base...HEAD` diff, **deny-by-default**: `no-surface` only when *every* path matches a configured non-runtime pattern, one unmatched path ⇒ `surface-bearing` and full gates. Orthogonal to `highRisk` — it decides which coverage/evidence *artifacts* apply, never how deep the review goes (`SCOPE_KEPT_OBLIGATIONS` names what no class ever drops: scan-diff's findings channel, CI on the exact head, the independent review, delivery recording). One repo-config table (`coverage.config.json` → `scopeClass`) drives both the classification and the **oracle requirement**: a matched class with no declared oracle is a blocking finding, not a waiver. Also derives the smoke `not-applicable` reason and the Review Contract's inapplicable rows. Doctrine + the built-in default table: [process/scope-class.md](references/process/scope-class.md).
+- `scripts/mock-policy-config.mjs` — resolves the project's first-party/external **topology** (`coverage.config.json` → `mockPolicy`) that `mock-internal-seam` reads, so "real internals, faked externals" is decidable from declared config, not a baked-in path regex ([depth/mock-policy.md](references/depth/mock-policy.md)).
+
+## Downstream
+
+ensure-coverage defines *what must be proven*; `implement-and-pr` proves it; `review-pr` runs the audit/breadth gate last; CI enforces the [gate contract](references/enforcement/ci-contract.md), and the repo's `hooks/` run the fast/decidable subset *in the agent's loop* per the [hook contract](references/enforcement/hooks.md). `e2e-test` owns the presentation sweep runner satisfying [presentation/runner-contract.md](references/presentation/runner-contract.md). `resolve-issues` sequences these steps (implement → e2e → review → CI → fix) and runs this skill's gates between them. This skill is the source of truth for doctrine; downstream skills consume it rather than restating it.

package/skills/engineering/ensure-coverage/evals/evals.json

@@ -0,0 +1,125 @@
+{
+  "skill_name": "ensure-coverage",
+  "evals": [
+    {
+      "id": 1,
+      "name": "unmapped-mutation-route-baseline",
+      "prompt": "Someone on my team shipped a /settings/integrations page last sprint with a 'Connect account' form on it. There's no ADR and no PRD for it \u2014 it just got added. There is one Playwright test for the page and it passes. Our coverage audit reports we're green because every ADR in docs/adr is covered. Are we actually covered here? And more generally, how should features like this \u2014 added without any spec written ahead of time \u2014 be handled by our coverage system so they don't slip through?",
+      "expected_output": "Explains that no ADR/PRD does NOT mean no test obligation: every surface gets a baseline floor from its (kind, class). Identifies /settings/integrations as a reachable mutation/write-form route needing a browser-journey (fill form -> backend accepts -> durable state). Treats the single passing Playwright test as a suspect to inspect (likely over-mocked via page.route/route.fulfill). Describes a default baseline contract by surface type rather than waiting on a spec, and that orphan/ownership is a warn while the test obligation is the hard gate.",
+      "files": [],
+      "assertions": [
+        {
+          "text": "States that the absence of an ADR/PRD does not remove the test obligation (surfaces carry a baseline regardless of ownership)"
+        },
+        {
+          "text": "Identifies the page as a reachable mutation/write-form surface requiring a browser-level journey (fill the real form, backend accepts, durable state changes)"
+        },
+        {
+          "text": "Treats the single passing Playwright test as a suspect and asks to inspect it for first-party interception (page.route/route.fulfill) -> Over-mocked, not Covered"
+        },
+        {
+          "text": "Proposes a default baseline keyed on surface type (read/detail/mutation), applied automatically rather than waiting on someone to author a spec"
+        },
+        {
+          "text": "Notes that 'every ADR covered' is not the same as 'every surface covered' (requirement-inward breadth misses un-ADR'd surfaces)"
+        }
+      ]
+    },
+    {
+      "id": 2,
+      "name": "exclusion-governance-and-smoke",
+      "prompt": "Our route coverage tool is complaining about a pile of pages and endpoints with no journey tests: a /pricing marketing page, a /signup form, and an /api/_seed endpoint that's only used by CI to seed test data. The team's plan is to just exclude all of them from the coverage tool so the build goes green. Is that acceptable? What's the right policy for each one?",
+      "expected_output": "Distinguishes legitimately excludable surfaces (static /pricing, internal /api/_seed) from ones that must keep coverage (/signup is a reachable write form -> cannot be excluded). Static content page keeps a render-health (browser-level reachability) floor — the level formerly named smoke — not zero test. render-health must be a real browser load, not an HTTP-200/API ping. Exclusions require a category + reason and are surfaced in a visible census, never silent. A reachable mutation surface can never be excluded to dodge a journey.",
+      "files": [],
+      "assertions": [
+        {
+          "text": "Refuses a blanket exclusion; evaluates each surface separately by reachability and class"
+        },
+        {
+          "text": "Says /signup (a reachable write form) cannot be excluded and still needs a mutation-form journey"
+        },
+        {
+          "text": "Allows excluding /pricing but keeps a render-health floor (does not let a content page ship with zero test)"
+        },
+        {
+          "text": "Specifies render-health is browser-level (page loads and renders), not an API/HTTP-200 check"
+        },
+        {
+          "text": "Requires each exclusion to carry a category + reason and be visible (census), not silently dropped"
+        }
+      ]
+    },
+    {
+      "id": 3,
+      "name": "settings-models-coverage-audit",
+      "prompt": "We have a /settings/models page and its APIs governed by a couple of ADRs, and some Playwright tests that pass. I have a nagging feeling the coverage isn't real. How would you audit whether this is actually covered?",
+      "expected_output": "Regression check carried from iteration-1: refuses green CI as proof, inspects actual test code, flags route.fulfill/page.route interception as Over-mocked, runs requirement-inward breadth, names load-bearing behaviors, recommends real-DB integration + journey tests.",
+      "files": [],
+      "assertions": [
+        {
+          "text": "Refuses to treat green CI as proof; inspects actual test code (Evidence Hierarchy)"
+        },
+        {
+          "text": "Flags route.fulfill/page.route interception as the likely cause (Over-mocked)"
+        },
+        {
+          "text": "Runs requirement-inward breadth (surface inventory, Orphan/Unrealized/Stale)"
+        },
+        {
+          "text": "Names load-bearing behaviors (per-org persistence, permission/tenant, no-secret)"
+        },
+        {
+          "text": "Recommends replacing mocked specs with real-DB integration + journey tests"
+        }
+      ]
+    },
+    {
+      "id": 4,
+      "name": "presentation-invisible-button-and-overflow",
+      "prompt": "We have a React dashboard at /dashboard. Last release a 'Save' button shipped that is technically present and clickable \u2014 our Playwright journey does getByRole('button',{name:'Save'}).click() and the test is green \u2014 but the button is nearly the same light-grey as the page background, so users literally can't see it. We also got a report that on mobile a data table runs off the right edge of the screen. Our coverage dashboard is all green. How is that possible, and what should our test criteria require so this whole class of bug can't pass green again?",
+      "expected_output": "Explains that a DOM-driven journey passes whether or not the control is visually perceivable, so functional coverage is structurally blind to invisible/overflowing UI. Introduces presentation obligations proven against the REAL rendered page: perceivability (WCAG contrast, e.g. axe-core) and spatial (no horizontal overflow at mobile+desktop viewports). Notes a DOM-only/JSDOM assertion does not count (Over-mocked); disabled controls are state-aware-exempt; ambiguous contrast (text over image/gradient) abstains to a blocking Unverified. Crucially, the answer should invoke the SKILL-SPECIFIC semantics (real-render-or-Over-mocked, exact-match levels, abstain->Unverified for gradient contrast, state-exempt disabled controls, gated allowlist for intentional overflow) \u2014 not just the general idea of 'add contrast and overflow checks', which a capable model proposes unaided.",
+      "files": [],
+      "assertions": [
+        {
+          "text": "Diagnoses both bugs as a distinct Presentation-axis concern that the functional DOM journey is structurally blind to (the green journey is necessary but not sufficient)"
+        },
+        {
+          "text": "Requires the perceivability/spatial checks be proven against a REAL rendered page and states a DOM-only/JSDOM assertion is graded Over-mocked, not Covered"
+        },
+        {
+          "text": "States a functional browser-journey does NOT satisfy the presentation obligation \u2014 presentation:spatial / presentation:perceivability is a separate, exact-match required level"
+        },
+        {
+          "text": "Handles ambiguity/intent correctly: contrast on text over an image/gradient abstains to a blocking Unverified (not a silent pass), and disabled controls are state-exempt from the contrast check"
+        },
+        {
+          "text": "Treats intentional horizontal scroll (e.g. a carousel) as suppressible only via a gated allowlist (category + reason, surfaced in a census), never silently ignored"
+        }
+      ]
+    },
+    {
+      "id": 5,
+      "name": "presentation-navorphan-and-payfields-shift",
+      "prompt": "Two things are bugging me. (1) We built a /reports/export page; it loads fine and is behind auth guards, but QA says no menu or link anywhere points to it, so real users can't find it. Our route coverage tool lists it as 'reachable' and green. (2) On checkout, the Stripe embedded card fields load a moment late and shove the rest of the layout downward when they appear. What's wrong with calling /reports/export 'covered', and what should our coverage actually require for both of these?",
+      "expected_output": "Distinguishes guard-chain reachability (URL loads past auth) from navigational reachability (a user can click their way to it) \u2014 guard-reachable is not the same as navigationally reachable; /reports/export is a navigational orphan. Requires a nav-orphan check (route-manifest minus the crawl-reachable set). For Stripe: a temporal/layout-shift obligation; notes the cross-origin iframe specifics (top-page CLS is blind to it; use before/after geometry gated on a provider-ready signal against the provider sandbox) and that this runs in a non-blocking lane that is tracked (Unverified), not silently ignored.",
+      "files": [],
+      "assertions": [
+        {
+          "text": "Distinguishes guard-chain reachability (loads past auth) from navigational reachability (a user can click to it); the route is a navigational orphan despite being guard-reachable"
+        },
+        {
+          "text": "Requires a nav-orphan check: route-manifest set minus the set reachable by crawling the rendered navigation"
+        },
+        {
+          "text": "Identifies the Stripe issue as a layout-shift/temporal obligation"
+        },
+        {
+          "text": "Notes the cross-origin iframe nuance (top-page CLS cannot see inside it; use before/after geometry gated on a provider-ready signal, against the provider sandbox)"
+        },
+        {
+          "text": "Notes the third-party/payfields check is tracked (non-blocking lane + Unverified), not silently passed or silently dropped"
+        }
+      ]
+    }
+  ]
+}

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

@@ -0,0 +1,91 @@
+# Coverage Ledger (breadth)
+
+> 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).
+
+## 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.
+
+1. **Requirement sources (intent)**: ADRs, PRDs, specs, issues, security/compliance rules, explicit design decisions. Triangulate across them; do not trust one.
+2. **Surface inventory (implementation)**: routes, API endpoints, **interactive write surfaces (mutation forms and write actions on pages)**, DB tables/migrations, events/topics, jobs, permission boundaries, external integrations. Discover deterministically from code — extend the [Route Discovery And Reachability Protocol](surface-discovery.md) to every surface type. For each reachable page carrying a write action, inventory one **mutation-form journey** per write action as its own obligation; do not fold it into the route entry or its backend endpoint. Treat a page with a write form and `specs: []` (or any empty coverage entry) as an uncovered journey, not a covered route.
+3. **Reconcile** the two into a **Coverage Ledger**, authored **one file per requirement document** (`docs/tests/adr/<id>-<slug>.coverage.yml`, likewise under `prd/` and `design/`), colocated with and gated by that requirement. Each file declares only the surfaces that requirement owns plus their required level and criteria link; it stores **no** coverage status. A generated aggregation (`coverage-index`) merges duplicate surfaces across files into one row, unions their `requirementRefs: [adr:…, prd:…, issue:…]`, takes the strictest required level, and computes status from the actual tests. The surface stays the unit of truth; the requirement document is just the storage/ownership unit. The ADR Coverage Matrix is a *view* of the aggregation filtered to `adr:` refs — not the source of truth.
+
+## Alignment statuses (the breadth classification)
+
+- `Aligned` — requirement ↔ surface ↔ evidence all present and linked. Hand off to depth grading.
+- `Orphan surface` — a surface exists but **no requirement references it** (empty `requirementRefs`) = `inventory − union(curated files)`. The traceability gap a single-anchor audit cannot see. **A warning, not a hard error** — ownership is decoupled from the test obligation: the surface still carries its [Surface Baseline Contract](surface-baseline.md) floor and is graded at depth like any aligned row.
+- `Unrealized requirement` — a curated surface absent from the inventory (drift, dead ADR, unbuilt spec).
+- `Stale link` — the row references a surface or evidence file that no longer exists (rot).
+- `Excluded` — a human marked the surface out of scope with a category + reason and the adapter signals permit it (see the baseline contract's exclusion gate). Surfaced in a visible census, never silent.
+
+Once a row is `Aligned` (or an `Orphan surface` carrying its baseline floor), the quality of its evidence is a *depth* question, graded by the [depth classifications](../depth/grading.md). "Required and built but untested" is not a breadth gap — it is a row at depth status `Missing`.
+
+## 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.
+
+- **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.
+- **Generated aggregation** (`coverage-index`, never hand-edited): merges all curated files, dedups by surface, unions `requirementRefs`, takes the strictest required level (`strictest(baseline, curated, sensitive)`), and **computes** alignment + coverage status.
+
+## Baseline floor (no requirement needed)
+
+Every entry surface (`route`, `api`) carries a minimum required-level floor computed from its `(kind, class)` — see [surface-baseline.md](surface-baseline.md). It applies **whether or not a requirement owns the surface**, so an organically-added route is graded the instant it appears. Consequences: `Orphan surface` is a **warn** but is still graded at its baseline floor (an unmet floor gives the failing depth status); internal surfaces (`table`/`event`/`job`) carry no floor (`Dead`-warned when unreached, else `Reached`); a curated entry can only **raise** (`requiredLevels`, `sensitive`) or **exclude** (gated), never lower the mechanical floor.
+
+## Exclusion gate + census
+
+A curated `exclude: { category, reason, gapIssue? }` is honored only when the adapter signals agree the surface cannot hurt a user (`exclusionAllowed`) — full gate in [surface-baseline.md](surface-baseline.md). Every honored exclusion prints a `warn`-level census line; no silent caps.
+
+## Terminal depth states (the ledger's config)
+
+`@level` is self-declared and never alone reaches `Covered` (the terminal states — `Over-mocked` / `Unverified` / `Covered` — are defined in [../depth/grading.md](../depth/grading.md)). The ledger flag: `Unverified` **blocks the gate by default** (`unverifiedBlocks: true`) until a curated `verified: true` attestation promotes it; set `unverifiedBlocks: false` to phase it down to a warning during rollout.
+
+## Evidence via `@covers` annotations
+
+Curated files must not hand-list test paths that rot. Each test declares the surfaces it proves:
+
+```ts
+// @covers /settings/models
+// @level browser-journey
+```
+
+The aggregation maps `@covers` → surface, checks required levels, flags internal interception (`route.fulfill`/`page.route(`), and computes depth status per the Evidence Hierarchy.
+
+## Acceptance gate
+
+Make coverage a precondition of accepting a requirement, not an optional follow-up.
+
+- Every accepted requirement with runtime behavior must have its own `…criteria.md` and `…coverage.yml` before it can merge; the requirement's own PR adds both.
+- A requirement with no runtime behavior (pure architecture/terminology) satisfies the gate with a criteria doc stating "no runtime behavior" and why, plus an empty coverage file.
+- When a requirement's status becomes accepted, CI checks for its matching criteria doc and coverage file.
+
+## Reconciliation checks (CI)
+
+The breadth axis is enforced by checks that fail (error) or warn:
+
+- an accepted requirement with runtime behavior has no criteria doc or coverage file (error);
+- the generated inventory is stale (surfaces changed but inventory not regenerated);
+- an entry surface's **baseline floor is unmet** — `Missing`/`Over-mocked`/`Wrong Level` (error), or `Unverified` (error by default, see `unverifiedBlocks`);
+- a surface owned by no curated file (`Orphan surface`, **warn** — baseline still enforced);
+- an internal surface reached by no evidence (`Dead surface`, warn);
+- an exclusion rejected by the reachability/class gate, or missing `category`/`reason` (error); honored exclusions print a census line (warn);
+- a `Stale link` / `Unrealized requirement`;
+- required level is integration/API/journey but only unit/mock evidence resolves;
+- internal interception counted as behavior coverage (`Over-mocked`).
+
+Wire this as a CI job on every PR (the illustrative job is in [../enforcement/ci-contract.md](../enforcement/ci-contract.md) → Reference wiring) regardless of who authored the change, and pair it with a PR template requiring the **Obligation Impact** block (touched surfaces, levels, proving tests, gate result). Skill prose makes the *agent* produce good inputs but cannot guarantee it — the CI job is the guarantee.
+
+## Reference validator
+
+A framework-agnostic tool ships at `scripts/coverage-ledger.mjs` (Node, `js-yaml` only; curated files may be `.json` for zero-dep):
+
+```
+node ~/.agents/skills/ensure-coverage/scripts/adapters/nextjs-inventory.mjs <appDir> --check   # repo-specific discovery; fail if inventory stale
+node ~/.agents/skills/ensure-coverage/scripts/coverage-ledger.mjs aggregate                    # build coverage-index from inventory + curated files + @covers tests
+node ~/.agents/skills/ensure-coverage/scripts/coverage-ledger.mjs validate [--config f] [--strict] [--warn-only]   # checks above; exit 1 on errors
+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 the zero-tolerance gate ([../depth/mock-policy.md](../depth/mock-policy.md)); the *rate* lets CI / `review-pr` **trend honesty as the suite grows** (a count rises just from more tests, a rate does not).
+
+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`.