@1aboveio/skills 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,189 @@
+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',
+  'rush-issues',
+  'resolve-issues',
+  'rush-release',
+  'resolve-release',
+  'golden-path',
+  'test-quality',
+  'better-review',
+  '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_INVOCATION_POLICIES = deepFreeze([
+  { installName: 'tdd', policy: 'manual-only' },
+]);
+
+export const WORKFLOW_TRUSTED_DEPENDENCY_CLOSURES = deepFreeze([
+  {
+    invokedSkill: 'rush-issues',
+    members: [
+      'harness-runtime',
+      'e2e-test',
+      'rush-issues',
+      'resolve-issues',
+      'golden-path',
+      'better-review',
+      'engineering-runtime',
+    ],
+    generatedIdentities: [],
+  },
+
+  {
+    invokedSkill: 'resolve-issues',
+    members: [
+      'harness-runtime',
+      'e2e-test',
+      'resolve-issues',
+      'golden-path',
+      'better-review',
+      'engineering-runtime',
+    ],
+    generatedIdentities: [],
+  },
+
+  {
+    invokedSkill: 'rush-release',
+    members: [
+      'rush-release',
+      'resolve-release',
+      'engineering-runtime',
+    ],
+    generatedIdentities: [],
+  },
+
+  {
+    invokedSkill: 'resolve-release',
+    members: [
+      'resolve-release',
+      'engineering-runtime',
+    ],
+    generatedIdentities: [],
+  },
+
+]);
+
+// First-party content is installed natively from the repository by the Skills CLI (ADR 0005; the
+// @1aboveio/skills npm package is retired, ADR 0010), so its identity is the repository following
+// `main`. External sources keep their immutable reviewed revision.
+export const WORKFLOW_TRUSTED_SOURCES = deepFreeze({
+  firstParty: {
+    id: 'first-party',
+    type: 'first-party',
+    repository: '1aboveio/ai',
+    revision: 'main',
+  },
+  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 invocationPolicyCommand = 'node "$HOME/.agents/skills/engineering-runtime/scripts/invocation-policy.mjs" --skill tdd --policy manual-only --from-selection';
+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 runtimeDependencyInstall = ' && npm --prefix "$(realpath "$HOME/.agents/skills/engineering-runtime/scripts")" ci --ignore-scripts';
+const firstPartyInstallSuffix = `${nativeSkillsTarget} ${firstPartyMembers.join(' ')}${runtimeDependencyInstall}`;
+
+// The native dependency-first install. The first-party step carries no `--yes`: 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: 'private-checkout',
+  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,
+      invocationPolicies: WORKFLOW_TRUSTED_INVOCATION_POLICIES,
+      commands: [{
+        transport: 'https',
+        command: `${externalArchiveLimits} ${nativeSkillsPrefix} https://codeload.github.com/mattpocock/skills/tar.gz/${WORKFLOW_TRUSTED_SOURCES.matt.revision} ${nativeSkillsTarget} ${mattMembersArgument} --yes && ${invocationPolicyCommand}`,
+      }],
+      onFailure: {
+        action: 'stop',
+        message: 'Source matt-pocock fetch failed; stop this recipe before running another source.',
+      },
+    },
+    {
+      sourceId: 'first-party',
+      sourceType: 'first-party',
+      repository: WORKFLOW_TRUSTED_SOURCES.firstParty.repository,
+      revision: WORKFLOW_TRUSTED_SOURCES.firstParty.revision,
+      installPath: null,
+      members: firstPartyMembers,
+      commands: [
+        {
+          transport: 'https',
+          command: `${nativeSkillsPrefix} ${WORKFLOW_TRUSTED_SOURCES.firstParty.repository} ${firstPartyInstallSuffix}`,
+        },
+        {
+          transport: 'ssh',
+          command: `${nativeSkillsPrefix} git@github.com:${WORKFLOW_TRUSTED_SOURCES.firstParty.repository}.git ${firstPartyInstallSuffix}`,
+        },
+      ],
+      onFailure: {
+        action: 'stop',
+        message: 'Source first-party fetch failed; stop this recipe before running another source.',
+      },
+    },
+  ],
+});

package/skills/engineering/engineering-runtime/scripts/yaml-mapping.mjs

@@ -0,0 +1,18 @@
+import { DEFAULT_SCHEMA, dump, load } from "js-yaml"
+
+// Parses a YAML document whose root must be a mapping. Lives here because js-yaml is resolved
+// from this directory's node_modules; a skill script elsewhere cannot import it by bare name.
+export function parseYamlMapping(yaml, label = "YAML") {
+  let value
+  try {
+    value = load(String(yaml || ""), { schema: DEFAULT_SCHEMA, json: false })
+  } catch (error) {
+    throw new Error(`${label} parse failed closed: ${String(error.message || error).trim()}`)
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} root must be a mapping`)
+  return value
+}
+
+export function dumpYamlMapping(value) {
+  return dump(value, { lineWidth: -1, noRefs: true, sortKeys: false })
+}

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,129 @@
+---
+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.36.0
+---
+**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.
+
+- **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)).
+
+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.
+
+## Stance: it ships broken until proven otherwise
+
+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?**
+
+- 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.
+
+## Three axes
+
+Each axis is blind to the others' failure; a coverage claim holds only when all three pass.
+
+- **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.
+
+## 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.
+
+## 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.

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

@@ -0,0 +1,92 @@
+# 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` is a **warning by default** (`unverifiedBlocks: false`) until a curated `verified: true` promotes it; set `unverifiedBlocks: true` only when the user asks for it to block.
+
+## 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 own `docs/tests/<source>/<id>-*.coverage.yml` that links its `criteria` doc, before it can merge; the requirement's own PR adds both.
+- 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.
+
+## Reconciliation checks
+
+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` (warning by default; error when `unverifiedBlocks: true`);
+- 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`).
+
+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)).
+
+## 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 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).
+
+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/inventory-contract.md

@@ -0,0 +1,85 @@
+# Surface Inventory Contract
+
+> Read when: writing or checking a repo's surface-inventory adapter, or the ledger reports an orphan or dead surface you cannot explain.
+
+Surface **discovery** is the one repo-specific part of the Coverage Ledger: enumerating routes/APIs/tables/events depends entirely on the stack. The reference tool (`scripts/coverage-ledger.mjs`) does **not** discover surfaces — your repo supplies them by emitting an inventory file that satisfies this contract. Everything downstream (aggregation, orphan detection, status) is generic and handled by the tool.
+
+## Output
+
+Write JSON to `docs/tests/_generated/surface-inventory.json` (or wherever `--inventory` points). This file is **generated, never hand-edited**, and regenerated on every change so staleness is detectable.
+
+### Canonical form
+
+```json
+{
+  "surfaces": [
+    { "id": "/settings/models", "kind": "route", "class": "mutation", "reachability": "reachable" },
+    { "id": "/about", "kind": "route", "class": "read", "reachability": "reachable" },
+    { "id": "/api/settings/model-allowlist", "kind": "api", "class": "mutation" },
+    { "id": "model_allowlist", "kind": "table" },
+    { "id": "model.allowlist.updated", "kind": "event" }
+  ]
+}
+```
+
+- `id` — the surface identifier. It must match exactly how the curated `*.coverage.yml` files and the test `@covers` annotations name the surface.
+- `kind` — one of `route`, `api`, `table`, `event`, `job`, `permission`, `integration` (extend as needed; used only for reporting).
+- `class` — the **mechanical taxonomy** that drives the Surface Baseline Contract floor. The adapter derives it deterministically from code, never from a session judgment:
+  - `route`: `read` (no write form) · `detail` (dynamic segment, renders one entity) · `mutation` (contains a write form / submit action).
+  - `api`: `read` (GET only) · `mutation` (exports POST/PUT/PATCH/DELETE).
+  - Omit for internal kinds (`table`/`event`/`job`) — they carry no baseline.
+  - The adapter emits **only** the mechanical class. `sensitive` (credential/admin escalation) and exclusion are human-declared in the curated `*.coverage.yml`, never guessed here — a path heuristic that under-classifies an admin route would silently hand it the weak floor.
+- `reachability` — `reachable | guarded | blocked | unreachable | unknown`, from walking the guard/layout/middleware chain (see the Route Reachability Protocol). Drives the **exclusion gate**: a `reachable` `mutation` route can never be excluded below its journey floor. Omit for non-route kinds.
+
+The baseline floor is computed from `(kind, class)`; the grouped lenient form below omits `class`/`reachability`, so entry surfaces fall back to the kind's `_default` floor (still enforced, just not class-refined). Prefer the canonical form so the floor is precise.
+
+### Golden-path candidate discovery
+
+The same generated inventory can seed the golden-path contract: `golden-path suggest --inventory docs/tests/_generated/surface-inventory.json` ranks likely golden-path candidates from deterministic signals (route/API kind, `class: mutation`, reachability, auth/payment/liveness-looking names). The output is a `candidates` list, **not** a runnable `golden-paths.json` — product/release judgment decides which candidates are truly do-not-ship flows and writes the concrete observables.
+
+### Presentation axis (browser routes)
+
+Every surface with `kind: "route"` auto-carries the **Presentation** floor on top of its functional floor (the five `presentation:*` levels — [../presentation/axis.md](../presentation/axis.md)). The adapter emits **no extra field**: `kind: "route"` *is* the browser-route fact the floor keys on. These floors are *graded* by the ledger and *run* by the `e2e-test` presentation sweep (`e2e-test/references/presentation-sweep.md`). The condition-matrix floor — viewports `[375, 1280]`, default theme, seeded data — is a ledger constant (`PRESENTATION_VIEWPORT_FLOOR` in `coverage-ledger.mjs`), not per-surface data.
+
+### Feature-derived escalation signals (optional)
+
+A route surface may carry an optional `signals` object that the adapter derives **deterministically** from code. Each signal *raises* the presentation floor by adding a cell-qualified obligation (Dimension B of the condition matrix). Optional and additive — absent signals just leave the surface at the fixed floor.
+
+```json
+{ "id": "/app", "kind": "route", "class": "read", "reachability": "reachable",
+  "signals": { "themeToggle": true, "i18n": true } }
+```
+
+| signal | derived from | adds required level(s) |
+|---|---|---|
+| `themeToggle` | a `next-themes` dep, or `useTheme`/`<ThemeProvider>`/`data-theme` in source | `presentation:perceivability@dark` |
+| `i18n` | a known i18n dependency (next-intl, react-i18next, i18next, …) | `presentation:spatial@long-locale`, `presentation:spatial@rtl` |
+
+Signals must be **deterministic** (same code → same signals) so two agents compute identical obligations. The reference Next.js adapter detects them at the app level and attaches to every route; a stack may refine to per-route detection. An escalated (`@`-qualified) cell can be dropped only via a gated `excludeCells` entry (category + reason, surfaced in the census); the base mechanical floor can never be removed.
+
+### Lenient grouped form (also accepted)
+
+```json
+{
+  "routes": ["/settings/models"],
+  "apis": ["/api/settings/model-allowlist"],
+  "tables": ["model_allowlist"],
+  "events": ["model.allowlist.updated"]
+}
+```
+
+The tool flattens this, deriving `kind` from the group name (`routes` → `route`).
+
+## Adapter expectations
+
+- **Deterministic**: same code → same inventory. No timestamps or ordering noise (the tool sorts).
+- **Complete for the kinds it claims**: if it emits `route`s, it must emit *all* reachable routes, or orphan detection becomes unsound.
+- **CI staleness check**: run the adapter with a `--check` mode (or `git diff --exit-code` on the output) so a PR that changes surfaces but not the inventory fails.
+
+A reference Next.js App Router adapter ships at `scripts/adapters/nextjs-inventory.mjs` — copy and adapt it, or write your own per framework.
+
+## How the tool consumes it
+
+`coverage-ledger.mjs aggregate` reads this inventory, the curated files, and `@covers` tests to build the index; `validate` runs the reconciliation checks. Commands and checks are documented in [coverage-ledger.md](coverage-ledger.md).
+
+`Orphan surface` = a surface in this inventory owned by no curated file. It is a `warn` (a traceability gap), but the surface still carries — and is graded against — its Surface Baseline Contract floor, so an unowned route is not silently uncovered. The inventory's completeness is therefore what makes all three axes sound: an adapter that under-reports surfaces, or under-classifies an entry surface's `class`/`reachability`, hides exactly the gaps the ledger exists to catch — including the per-route presentation floor, which keys off `kind: route`.

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

@@ -0,0 +1,44 @@
+# Surface Baseline Contract (breadth)
+
+> 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.
+
+**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.
+
+- **`class` (mechanical, adapter-owned)**: `read | detail | mutation` for routes (does the page contain a write form / does `route.*` export a write method); derived from code with no human input.
+- **`reachability` (adapter-owned)**: `reachable | guarded | blocked | unreachable | unknown` from the guard/layout/middleware chain (see [surface-discovery.md](surface-discovery.md)).
+- **`sensitive` / exclusion (human-declared)**: credential/admin judgment and out-of-scope intent are *not* reliably derivable from syntax. Humans may only **raise** the floor (`sensitive`) or **exclude** (gated below) — never weaken the mechanical floor. `effectiveLevels = strictest(baseline, curated requiredLevels, sensitive escalation)`.
+
+## Baseline table
+
+Baseline only **entry surfaces** (`route`, `api`). **Internal surfaces** (`table`, `event`, `job`) carry no independent obligation — they are proven transitively by the entry surface that writes/emits them, and only **dead-surface-warned** when no evidence reaches them (a table nothing writes is likely dead code, not a coverage gap).
+
+| kind | class | baseline `requiredLevels` | the journey must additionally assert |
+|---|---|---|---|
+| route | read | `browser-journey` | page renders real data (drive the rendered page, no first-party mock) |
+| route | detail | `browser-journey` | seeded real entity renders |
+| route | mutation | `browser-journey` | fill real form → backend accepts → **durable state changes** |
+| route | +sensitive | `browser-journey` + `api` | + auth / tenant-isolation assertion |
+| api | read (GET) | `api` | status, shape, auth |
+| api | mutation (write) | `api` + `integration` | durable state changed |
+| api | +sensitive | + auth | mandatory auth / tenant isolation |
+| table / event / job | — | none (transitive) | dead-surface-warned if unreached |
+| 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.)
+
+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
+
+An exclusion downgrades a surface to manifest-only — the exact move that re-opens the gap if trusted on a prose reason. So exclusion is **permitted only when the adapter's deterministic signals agree the surface cannot hurt a user**:
+
+- A `Reachable` `mutation` route can **never** be excluded below its journey floor, regardless of any human "internal" claim — a reachable write form is a first-week bug surface.
+- Manifest-only is permitted only when reachability is `blocked`/`unreachable`, or the surface is a read-only page (static/content), or a non-mutation API. The `static` category is the exception that downgrades to a `render-health` floor rather than manifest-only, so a content page still proves it loads.
+- Every exclusion requires `category` (seed/static/deprecated/internal) + `reason` + optional `gapIssue`, and the validator prints a **visible exclusion census** every run. No silent caps.
+
+## 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.

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

@@ -0,0 +1,16 @@
+# Route Discovery & Reachability Protocol (breadth)
+
+> Read when: enumerating the surfaces that must be proven, and classifying whether each route is actually reachable. This is the *requirement-inward enumeration* that builds the surface inventory — a breadth activity. Its `reachability` output feeds the baseline floor and the exclusion gate ([surface-baseline.md](surface-baseline.md)).
+>
+> **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:
+
+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.
+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.
+
+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.