@1aboveio/skills 0.0.0-stage → 1.0.0

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

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

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

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

package/skills/engineering/ensure-coverage/release-check.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const WEEK_MS = 7 * DAY_MS;
+const here = dirname(fileURLToPath(import.meta.url));
+
+function readJson(path, fallback = {}) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return fallback; }
+}
+
+function frontmatterValue(text, key) {
+  const frontmatter = /^---\n([\s\S]*?)\n---/.exec(text)?.[1] ?? '';
+  const match = new RegExp('^' + key + ':\\s*([^\\n]+)$', 'm').exec(frontmatter);
+  return match?.[1].trim().replace(/^['"]|['"]$/g, '') ?? null;
+}
+
+function repositoryOf(source) {
+  const value = String(source ?? '').trim();
+  const match = /^(?:git@github\.com:|https:\/\/github\.com\/)?([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(value);
+  return match?.[1] ?? null;
+}
+
+function stableVersion(value) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(String(value ?? '').trim());
+  return match ? match.slice(1).map(Number) : null;
+}
+
+function newer(left, right) {
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) return left[index] > right[index];
+  }
+  return false;
+}
+
+function writeCache(path, value) {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(value));
+  } catch { /* A read-only cache must not block skill use. */ }
+}
+
+function main(now = Date.now()) {
+  if (process.env.ONEABOVEIO_NO_UPDATE_CHECK) return;
+  const skill = readFileSync(join(here, 'SKILL.md'), 'utf8');
+  const name = frontmatterValue(skill, 'name');
+  const localVersion = stableVersion(frontmatterValue(skill, 'release-version'));
+  if (!name || !localVersion) return;
+
+  const lock = readJson(join(process.env.HOME || homedir(), '.agents', '.skill-lock.json'));
+  const entry = lock.skills?.[name];
+  const repository = repositoryOf(entry?.sourceUrl || entry?.source);
+  if (!repository) return;
+
+  const cacheRoot = process.env.XDG_CACHE_HOME || join(process.env.HOME || homedir(), '.cache');
+  const cachePath = join(cacheRoot, '1aboveio-skills', 'release-check.json');
+  const all = readJson(cachePath);
+  const cache = all[repository] && typeof all[repository] === 'object' ? all[repository] : {};
+
+  if (!cache.lastCheck || now - cache.lastCheck >= DAY_MS) {
+    const result = spawnSync('gh', ['api', 'repos/' + repository + '/releases/latest', '--jq', '.tag_name'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 1500,
+    });
+    cache.lastCheck = now;
+    if (result.status === 0 && stableVersion(result.stdout)) cache.latestTag = result.stdout.trim();
+    else delete cache.latestTag;
+    all[repository] = cache;
+    writeCache(cachePath, all);
+  }
+
+  const latestVersion = stableVersion(cache.latestTag);
+  if (!latestVersion || !newer(latestVersion, localVersion)) return;
+  if (cache.notifiedTag === cache.latestTag && cache.notifiedAt && now - cache.notifiedAt < WEEK_MS) return;
+
+  cache.notifiedTag = cache.latestTag;
+  cache.notifiedAt = now;
+  all[repository] = cache;
+  writeCache(cachePath, all);
+  const command = `npx skills@1.5.23 add '${repository}#${cache.latestTag}' --global --agent universal claude-code --skill ${name} --yes`;
+  process.stdout.write(
+    `UPDATE_AVAILABLE: A newer 1AboveIO skills release (${cache.latestTag}) is available; this skill is `
+      + `v${localVersion.join('.')}. Ask once whether to refresh ${name}. On approval run \`${command}\`. `
+      + 'The refreshed instructions apply next session. Either way, continue the current task and do not ask again this session.\n',
+  );
+}
+
+try { main(); } catch { /* Update checks are advisory and always fail silent. */ }

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

@@ -0,0 +1,67 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "coverage-config.schema.json",
+  "title": "coverage.config.json",
+  "description": "Per-project config for ensure-coverage tooling, placed at the repo root. The mockPolicy block declares TOPOLOGY for the default-on, zero-tolerance mock-internal-seam lint rule (references/depth/mock-policy.md) \u2014 it tunes what counts as first-party; it does not enable/disable the gate.",
+  "type": "object",
+  "additionalProperties": true,
+  "properties": {
+    "mockPolicy": {
+      "type": "object",
+      "description": "Declares topology for lint-tests' mock-internal-seam rule via the externals-allowlist inversion: flag a mock of first-party code, exempt declared externals. The rule is default-on and cannot be disabled here.",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": true,
+          "description": "Inert / retained for compatibility. The mock-internal-seam gate is ZERO-TOLERANCE and default-on; setting this false does NOT disable it. Config declares topology, not on/off."
+        },
+        "firstPartyAliasPrefixes": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "default": [
+            "@/",
+            "~/"
+          ],
+          "description": "Import-specifier prefixes denoting first-party app source; a mock of one of these is treated as an internal seam."
+        },
+        "firstPartyPackages": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "default": [],
+          "description": "Bare package names \u2014 exact or scope prefix (e.g. \"@acme/\") \u2014 that are actually first-party workspace packages, so mocking them is an internal seam."
+        },
+        "externals": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "default": [],
+          "description": "Regex sources for specifiers that are legitimately external and therefore exempt (overrides first-party detection). Bare npm packages and node: builtins are already external by default; use this only for a first-party-looking specifier that is actually external/generated."
+        },
+        "testUtilHints": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Path segments that mark a relative import as a test util / fixture / mock rather than a production seam (e.g. __mocks__, fixtures, helpers)."
+        }
+      }
+    },
+    "requirementGlobs": {
+      "type": "object",
+      "description": "Enables the acceptance gate. Maps a requirement source name to the directory holding its documents, e.g. {\"adr\": \"docs/adr\", \"prd\": \"docs/prd\"}. Every document there whose text matches acceptedMarker must own <coverageDir>/<source>/<id>-*.coverage.{yml,json} with `criteria` or a tracked gap, unless the document says \"no runtime behavior\". Unset means the gate is skipped and validate says so.",
+      "additionalProperties": {
+        "type": "string"
+      }
+    },
+    "acceptedMarker": {
+      "type": "string",
+      "description": "Case-insensitive regex that marks a requirement document as accepted. Default matches `status: accepted` and `**Status:** accepted`."
+    }
+  }
+}

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

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

package/skills/engineering/ensure-coverage/scripts/README.md

@@ -0,0 +1,99 @@
+# ensure-coverage scripts
+
+The mechanized half of the skill: each script decides one thing the doctrine in
+[`../SKILL.md`](../SKILL.md) says must be proven. This file is the CLI reference. The
+*what* lives in `SKILL.md` and `references/`; the *why* of each rule is cited there.
+
+**Resolution.** Every script is under this skill's own directory, not the target
+repo. Set `SKILL_DIR` to the directory you read `SKILL.md` from and run
+`node "$SKILL_DIR/scripts/<name>.mjs"`. Never resolve against your CWD, and never
+locate a script with `find` over `$HOME`; if `SKILL_DIR` is unknown, stop and ask.
+Consumers write the path as `<ensure-coverage>/scripts/<name>.mjs`.
+
+Every script has a `*.test.mjs` sibling; `ci.yml` runs them all.
+
+## `coverage-ledger.mjs aggregate|validate|report`
+
+The breadth accounting gate. Reconciles the generated surface inventory
+(`docs/tests/_generated/surface-inventory.json`, per
+[`inventory-contract.md`](../references/breadth/inventory-contract.md)) against the
+curated `*.coverage.yml` files and the `@covers` / `@level` annotations in tests, and
+computes every surface's status. Full mechanics:
+[`coverage-ledger.md`](../references/breadth/coverage-ledger.md).
+
+```bash
+node "$SKILL_DIR/scripts/coverage-ledger.mjs" aggregate                 # build coverage-index.json + coverage-metrics.json
+node "$SKILL_DIR/scripts/coverage-ledger.mjs" validate [--config f] [--strict] [--warn-only]   # exit 1 on errors
+node "$SKILL_DIR/scripts/coverage-ledger.mjs" report                    # markdown index + ADR matrix view
+```
+
+- `validate` fails on an unmet baseline floor (`Missing` / `Over-mocked` / `Wrong Level`), an `Unverified` only when `unverifiedBlocks: true` (default `false`: a warning), a rejected exclusion, a `Stale link`, or an `Unrealized requirement`. `Orphan surface` and `Dead surface` warn.
+- `aggregate` also writes `coverage-metrics.json` with the **over-mock rate** (`overMocked / tested`, split behavior vs presentation). The *count* is the zero-tolerance gate; the *rate* is a trend signal for reviewers and dashboards, never a second gate.
+- **Acceptance gate.** Set `requirementGlobs` in `coverage.config.json` (e.g. `{ "adr": "docs/adr" }`) and `validate` also checks every accepted requirement document there: it must own `<coverageDir>/<source>/<id>-*.coverage.{yml,json}` that links a `criteria` doc or names a tracked gap (`gapIssue` / `gapDoc`), unless the document says it has "no runtime behavior". `acceptedMarker` overrides the default accepted-status regex. Unset, the gate is skipped and the output says so.
+- Exit 2 means no surface inventory was found (gate not wired here); hooks treat that as degraded, not failed.
+- Surface discovery is repo-specific. A reference Next.js App Router adapter ships at `scripts/adapters/nextjs-inventory.mjs <appDir> --check` (`--check` fails when the committed inventory is stale).
+
+## `lint-tests.mjs --diff <base> [--rules a,b]`
+
+Static test-lint gate engine. Deterministic, near-zero false positives, blocks on what a diff **adds**. Without `--diff` it scans the whole tree.
+
+| rule | blocks on |
+|---|---|
+| `no-skip` | an added declared `test.skip('name', …)` / `.only` / `xit` / `.todo` / `describe.skip` (conditional skips and `xfail` are test-quality's `conditional-skip` lead) |
+| `no-fixed-timeout` | an added `waitForTimeout` / numeric `cy.wait` / `sleep` |
+| `no-empty-test` | an empty test body |
+| `no-swallowed-assertion` | an assertion whose rejection is eaten by a chained `.catch(...)` |
+| `mock-internal-seam` | a `vi.mock` / `jest.mock` / `vitest.mock` whose target is first-party code |
+
+`mock-internal-seam` is default-on and zero-tolerance: no `@mock-ok` waiver, no grandfathering. In audit mode run it **whole-tree** (`--rules mock-internal-seam`, no `--diff`) and count every hit in the verdict. A believed false positive is fixed by declaring the repo's topology, never by waiving:
+
+```json
+// coverage.config.json at the repo root — declares what counts as first-party
+{ "mockPolicy": {
+    "firstPartyAliasPrefixes": ["@/", "~/"],
+    "firstPartyPackages": ["@acme/"],
+    "externals": ["^@/generated/"] } }
+```
+
+A conventional `@/`-aliased repo needs no config. `mock-policy-config.mjs` is the resolver `lint-tests` uses; the field reference is `schemas/coverage-config.schema.json` and a ready-to-copy example is `references/depth/coverage.config.example.json`. Only the front end (finding a mock call and its target) is language-specific; a new stack is a one-function adapter feeding the same classifier, and until one exists the rule degrades to a review lead, not a false block.
+
+The judgment remainder (does a real-boundary sibling exist, is the assertion meaningful) stays a reviewer judgment.
+
+## `design-parity.mjs scaffold|probe|validate`
+
+The `presentation:fidelity` gate for a unit built from a cited design source
+([`axis.md`](../references/presentation/axis.md) → `presentation:fidelity`).
+
+```bash
+node "$SKILL_DIR/scripts/design-parity.mjs" scaffold                           # manifest skeleton from the doctrine-fixed catalog
+node "$SKILL_DIR/scripts/design-parity.mjs" probe <manifest> --viewport <px>   # emits the JS that measures the built page
+node "$SKILL_DIR/scripts/design-parity.mjs" validate <manifest> --observed <results.json> [--diff <base>]
+```
+
+- `scaffold` pre-fills the rows a hand-written list forgets: page measure, container plane, per-viewport type scale, box, coupled rhythm, and a relational `primary > secondary` row. A row may be rejected with a written reason, never silently omitted.
+- `validate` blocks on a `TODO` row, a rejection with no reason, a `from:` citation that does not resolve in the pinned source, a missing catalog row for a declared role, or any measured divergence. With `--diff` it also blocks a changed `expected` under an unmoved `source.sha` (rewriting the target to match the page); declare a genuine re-read with `rebase: <reason>`.
+- Without `--observed` it announces the **reduced form** on stderr: manifest complete and citations resolve, nothing about conformance.
+- Not a differ (cross-stack comparison is judgment) and not a pixel baseline (every `expected` is read off the *source*, not captured from the implementation).
+
+## `check-quarantine-expiry.mjs`
+
+The auto-resurface gate. A `@quarantine(until=…)` exit is non-blocking until its date, then expires and re-blocks, so the quarantine lane cannot decay into a permanent skip.
+
+## `ci-audit.mjs --files <ci configs> [--adoption] [--json] [--allow-warn]`
+
+Opt-in: run only when the user asks to audit CI. It checks the skill's sole supported CI gate, curated golden-path smoke, and reports `present` / `warn-only` / `absent`. It deliberately ignores ledger validation, inventory freshness, presentation sweeps, broad E2E, test lint, over-mock scans, design parity, and quarantine expiry. Contract: [`ci-contract.md`](../references/enforcement/ci-contract.md).
+
+```bash
+node "$SKILL_DIR/scripts/ci-audit.mjs" --files .github/workflows/ci.yml,cloudbuild.gates.yaml
+node "$SKILL_DIR/scripts/ci-audit.mjs" --adoption --files <ci files>          # issue body on stdout; exit 1 when wiring is needed
+```
+
+`--adoption` turns missing or weakened smoke wiring into a focused issue body.
+
+## `mock-policy-config.mjs`
+
+Library, not a CLI: resolves `coverage.config.json` → `mockPolicy` into the first-party/external topology `mock-internal-seam` classifies against. Defaults in `DEFAULT_MOCK_POLICY`.
+
+## CI boundary
+
+The analyzers above support audits and review; this skill does not recommend them as CI gates. Curated golden-path smoke is the only CI gate in [`ci-contract.md`](../references/enforcement/ci-contract.md).