@1aboveio/engineering-skills 0.1.10 → 0.1.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (66) hide show
  1. package/README.md +1 -1
  2. package/package.json +2 -2
  3. package/skills/better-review/SKILL.md +37 -37
  4. package/skills/better-review/references/passes.md +35 -41
  5. package/skills/better-review/references/result.md +10 -9
  6. package/skills/e2e-test/SKILL.md +17 -17
  7. package/skills/e2e-test/references/authoring/playwright-config.md +11 -13
  8. package/skills/e2e-test/references/presentation-sweep.md +7 -7
  9. package/skills/e2e-test/references/reviewing.md +9 -11
  10. package/skills/e2e-test/references/route-manifest.md +1 -1
  11. package/skills/engineering/SKILL.md +124 -0
  12. package/skills/engineering/references/engineering-conventions.md +32 -0
  13. package/skills/engineering/references/feature-delivery.md +8 -0
  14. package/skills/engineering/references/init-scope.md +37 -0
  15. package/skills/engineering/scripts/init.mjs +160 -0
  16. package/skills/{contributing → engineering}/scripts/persist-conventions.mjs +1 -1
  17. package/skills/engineering-runtime/SKILL.md +1 -1
  18. package/skills/engineering-runtime/coherence/workflow.json +19 -19
  19. package/skills/engineering-runtime/scripts/workflow-policy.mjs +1 -1
  20. package/skills/ensure-coverage/SKILL.md +22 -109
  21. package/skills/ensure-coverage/references/breadth/coverage-ledger.md +7 -5
  22. package/skills/ensure-coverage/references/breadth/surface-baseline.md +4 -4
  23. package/skills/ensure-coverage/references/breadth/surface-discovery.md +3 -3
  24. package/skills/ensure-coverage/references/depth/characterization.md +4 -65
  25. package/skills/ensure-coverage/references/depth/grading.md +5 -7
  26. package/skills/ensure-coverage/references/depth/mock-policy.md +6 -12
  27. package/skills/ensure-coverage/references/enforcement/ci-contract.md +1 -1
  28. package/skills/ensure-coverage/references/presentation/axis.md +6 -6
  29. package/skills/ensure-coverage/references/process/audit-mode.md +7 -23
  30. package/skills/ensure-coverage/references/process/output-template.md +18 -133
  31. package/skills/ensure-coverage/references/process/test-strategy.md +7 -12
  32. package/skills/ensure-coverage/scripts/README.md +12 -4
  33. package/skills/golden-path/SKILL.md +1 -1
  34. package/skills/harness-runtime/SKILL.md +3 -1
  35. package/skills/harness-runtime/bin/workspaces.mjs +52 -0
  36. package/skills/harness-runtime/native-workspace.mjs +239 -0
  37. package/skills/harness-runtime/references/workspaces.md +78 -0
  38. package/skills/harness-runtime/workspace-lifecycle.mjs +2154 -0
  39. package/skills/resolve-issues/SKILL.md +40 -61
  40. package/skills/resolve-issues/references/ci.md +13 -3
  41. package/skills/resolve-issues/references/delivery-progress.md +4 -3
  42. package/skills/resolve-issues/references/done.md +11 -2
  43. package/skills/resolve-issues/references/expire.md +9 -2
  44. package/skills/resolve-issues/references/implementation.md +33 -17
  45. package/skills/resolve-issues/references/preflight.md +3 -1
  46. package/skills/resolve-issues/references/principles.md +52 -0
  47. package/skills/resolve-issues/references/review.md +25 -15
  48. package/skills/resolve-issues/references/task-plan.md +64 -27
  49. package/skills/resolve-issues/references/workspaces.md +164 -0
  50. package/skills/resolve-issues/scripts/cleanup-runs.mjs +185 -317
  51. package/skills/resolve-issues/scripts/next-actions.mjs +44 -7
  52. package/skills/resolve-issues/scripts/rehydrate.mjs +36 -2
  53. package/skills/resolve-issues/scripts/review-verdict.mjs +9 -8
  54. package/skills/resolve-issues/scripts/workspace-lifecycle.mjs +1 -0
  55. package/skills/resolve-release/SKILL.md +1 -1
  56. package/skills/rush-issues/SKILL.md +7 -5
  57. package/skills/rush-release/SKILL.md +1 -1
  58. package/skills/test-quality/SKILL.md +19 -4
  59. package/skills/test-quality/references/lint.md +1 -1
  60. package/skills/test-quality/references/principles.md +2 -2
  61. package/skills/test-quality/references/testing-conventions.md +1 -1
  62. package/skills/contributing/SKILL.md +0 -70
  63. /package/skills/{contributing → engineering}/LICENSE +0 -0
  64. /package/skills/{contributing → engineering}/references/tracker-conventions.md +0 -0
  65. /package/skills/{contributing → engineering}/release-check.mjs +0 -0
  66. /package/skills/{contributing → engineering}/scripts/persist-conventions-core.mjs +0 -0
@@ -2,128 +2,41 @@
2
2
  name: ensure-coverage
3
3
  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)."
4
4
  disable-model-invocation: true
5
- release-version: 0.44.1
5
+ release-version: 0.45.0
6
6
  ---
7
7
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
8
8
  # Ensure Coverage
9
9
 
10
- 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.
10
+ Define what must be proven for the agreed business outcome and material risks. This skill scopes criteria and grades evidence; it does not implement tests, wire gates, or issue a merge verdict.
11
11
 
12
- - **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)).
13
- - **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)).
12
+ - **Create mode:** agree observable criteria and suitable proof before implementation. Record them in the issue or conversation; create a criteria document only when requested or required by the repository.
13
+ - **Audit mode:** assess evidence against the agreed scope. A feature audit stays scoped to the feature; a whole-repo census is appropriate only for an explicitly requested broad audit. Use the [audit guidance](references/process/audit-mode.md) and [optional output template](references/process/output-template.md).
14
14
 
15
- 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.
15
+ Read the relevant source and governing project guidance. When product behavior or authorization is unclear and blocks the task, ask the owner; do not invent semantics or add planning handoffs for ordinary implementation choices. Keep agreed criteria stable during implementation and proof. A newly discovered concrete defect may need a fix; speculative robustness ideas and test preferences are follow-ups, not new acceptance conditions. Escalate a proposed scope change for agreement.
16
16
 
17
- ## Stance: it ships broken until proven otherwise
17
+ ## Scope and proof
18
18
 
19
- 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?**
19
+ - Choose the smallest sufficient proof for the outcome and material risks; reuse existing tests and required CI results when they prove the behavior. Do not automatically require multiple test layers, a ledger, a criteria document, a presentation campaign, or reconciliation of every ADR.
20
+ - Existing required repository checks and adopted coverage floors remain binding unless an approved change alters them. Authentication, money, tenancy, and data-integrity protections remain binding. Read applicable ADRs and project policy for the touched work, not every ADR in the repository.
21
+ - Consider breadth, depth, and presentation where relevant: what behavior is in scope, whether evidence actually exercises it, and whether a user can perceive and use a changed interface. Do not turn every axis or hypothetical state into a separate blocking obligation.
22
+ - The [surface baseline](references/breadth/surface-baseline.md) is guidance for selecting proof, not a universal new floor. The bundled ledger and presentation tools implement stricter mechanical rules; use them only when requested or already required, and report their actual results without claiming their defaults are new policy.
23
+ - Avoid tests that bypass the behavior they claim to prove, especially for security or durable state. Select boundaries and test levels for the risk, following applicable repo rules ([mock policy](references/depth/mock-policy.md), [strategy](references/process/test-strategy.md)). A relevant existing test can suffice; characterization and fails-first runs are useful when warranted, not automatic requirements ([characterization](references/depth/characterization.md)).
24
+ - Do not weaken or disable tests merely to get green. Report a required check that cannot run or fails; do not claim it passed.
25
+ - Do not recommend or wire new CI gates unless asked. Existing required checks still apply ([CI contract](references/enforcement/ci-contract.md)). Integrated release campaigns run at their assigned gate, not automatically for each feature.
20
26
 
21
- - A test you have not read is not coverage. State what each passing test exercises and what it silently skips.
22
- - 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.
23
- - Name the concrete failure ("username dropped, submit returns 400"), not "coverage is partial."
24
- - End with an explicit ship / no-ship call and the counts that drive it. Never round up to `Covered` to be agreeable.
27
+ ## Grade honestly
25
28
 
26
- ## Three axes
29
+ Inspect the relevant test and its assertions before claiming it proves a behavior. A passing execution proves it ran, not that it covered every claim. Use [grading](references/depth/grading.md): `Covered`, `Partial`, `Missing`, `Wrong Level`, `Over-mocked`, `Unverified`, `Excluded`, or `BLOCKED`. Describe what the evidence proves and what remains unverified; never promote a hypothetical state to a blocker merely because it lacks a test. Missing agreed proof, a concrete material defect, or a failed required check can block; distinguish those from follow-ups. Report unavailable evidence or unresolved decisions without a false success.
27
30
 
28
- Each axis is blind to the others' failure; a coverage claim holds only when all three pass.
31
+ ## Workflow and output
29
32
 
30
- - **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.
31
- - **Depth** (test-outward): does each test prove the behavior against real state? Catches false green: over-mocking, proxy wiring, shallow assertions, wrong level.
32
- - **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.
33
+ 1. Identify the agreed outcome, touched behavior, material risks, required repo checks, and applicable guidance. Resolve only decisions needed to proceed.
34
+ 2. Agree observable acceptance criteria and sufficient proof before implementation. Note existing proof and select focused additions only where needed.
35
+ 3. For an audit, inspect relevant tests and results, grade the agreed scope, and report concrete gaps, blockers, and non-blocking follow-ups. Do not expand criteria after the fact. An explicitly requested broad audit may use [surface discovery](references/breadth/surface-discovery.md) and the [coverage ledger](references/breadth/coverage-ledger.md); state any limits on its completeness.
36
+ 4. Record what was verified, what was not, and why. Use the repository's existing format or a concise response; no new document is required by default.
33
37
 
34
- ## The obligations
35
-
36
- **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).
37
-
38
- | kind | class | owes | the test must show |
39
- |---|---|---|---|
40
- | route | read / detail | browser-journey | real rendered data, no first-party mock |
41
- | route | mutation | browser-journey | fill the real form → backend accepts → durable state changes |
42
- | route | +sensitive | + api | + auth / tenant isolation |
43
- | api | read | api | status, shape, auth |
44
- | api | mutation | api + integration | durable state changed |
45
- | api | +sensitive | + auth | mandatory auth / tenant isolation |
46
- | table / event / job | — | none (transitive) | dead-surface warning if nothing reaches it |
47
-
48
- **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)).
49
-
50
- **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)).
51
-
52
- **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)).
53
-
54
- **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)).
55
-
56
- **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)).
57
-
58
- **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.
59
-
60
- **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.
61
-
62
- **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.
63
-
64
- **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.
65
-
66
- ## Classifications
67
-
68
- 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.
69
-
70
- - **`Covered`** — inspected test proves the behavior at the required level, acceptable mocks. The ledger shows it once the test is marked read (`verified: true`).
71
- - **`Partial`** — some behavior tested; edge cases, failures, permissions, state, or evidence incomplete.
72
- - **`Missing`** — no meaningful test maps to the obligation.
73
- - **`Wrong Level`** — a test exists but is too shallow for the risk.
74
- - **`Over-mocked`** — mocks bypass the behavior under test.
75
- - **`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.
76
- - **`Excluded`** — human-declared out of scope with category and reason, permitted by the gate, visible in the census.
77
- - **`BLOCKED`** — source, code, tests, environment, or a product decision is unavailable.
78
-
79
- ## Workflow
80
-
81
- 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.
82
- 2. **Model correctness.** Number the ACs, name the critical journeys, assign each a required level ([levels](references/process/test-strategy.md)).
83
- 3. **Plan coverage.** Test matrix, mock policy, E2E needs.
84
- 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.
85
- 5. **Validate and decide.** Reject implementation-shaped, over-mocked, skipped, or incomplete coverage. Verdict at the top.
86
-
87
- ## Deliverable
88
-
89
- 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)):
90
-
91
- ```markdown
92
- ## Verdict: Ship / No-ship — <one-sentence reason with the driving counts>
93
- ## Source · Scope · Assumptions · Blockers · Design source (or `none`)
94
- ## Acceptance Criteria (numbered, observable, independently testable)
95
- ## Critical Journeys (actor, start state, trigger, end state, side effects)
96
- ## Test Matrix (scenario · AC · level · mock policy · setup · assertions · proving test)
97
- ## Surface Census (audit) — one row per surface, status, proving test or —
98
- ## Gaps and follow-ups (each with level, setup, assertions)
99
- ## Blocking Decisions (product choices that change the verdict)
100
- ```
101
-
102
- ## Common wrong answers
103
-
104
- - Green CI is not coverage. Read the test.
105
- - An API test under a page does not prove the page.
106
- - "Every ADR covered" is not "every surface covered." And an accepted ADR with no coverage file is a gap, not a pass.
107
- - 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.
108
- - Excluding a surface is not fixing it. Exclusion is gated and visible.
109
- - "The script isn't in the audited repo" is not `BLOCKED`. The scripts live in this skill; run them against the repo.
110
- - A top-3 gap list is not an audit. Emit the census.
111
- - "Out of scope" excludes behaviors, never the axis the unit is about.
112
-
113
- ## Mechanization
114
-
115
- 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).
116
-
117
- | script | decides |
118
- |---|---|
119
- | `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 |
120
- | `lint-tests.mjs` | added skips, fixed timeouts, empty tests, swallowed assertions, and mocks of first-party seams (zero-tolerance) |
121
- | `design-parity.mjs` | the built page matches the cited design source |
122
- | `check-quarantine-expiry.mjs` | a dated quarantine exit re-blocks when it expires |
123
- | `ci-audit.mjs` | CI wires curated golden-path smoke as a blocking check |
124
-
125
- In audit mode, always run the over-mock scan whole-tree and count every hit in the verdict.
38
+ The scripts in this skill are optional tools unless the repo already requires them. Set `SKILL_DIR` to this skill's directory and see [scripts/README.md](scripts/README.md) for usage. Their fixed checks and outputs can be broader or stricter than the agreed feature scope; do not silently change or bypass an adopted gate. Escalate conflicts rather than presenting tool defaults as policy.
126
39
 
127
40
  ## Downstream
128
41
 
129
- 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.
42
+ `test-quality` judges individual tests; `e2e-test` authors browser tests; `golden-path` owns curated release-critical journeys; `resolve-issues` delivers and `better-review` provides independent review. Other skills and existing repository policy may still carry stricter requirements: preserve them and surface conflicts to the appropriate owner rather than silently overriding them.
@@ -2,6 +2,8 @@
2
2
 
3
3
  > 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).
4
4
 
5
+ This reference describes an optional ledger and its existing mechanical behavior, not a requirement to create a ledger or reconcile all ADRs for routine features. Use it when requested or already required by the repository. Its errors and floors remain binding when an existing required check enforces them; seek approval rather than bypassing or silently changing that policy. A whole-repo census requires an explicitly requested broad audit.
6
+
5
7
  ## Doctrine: the ledger is a reconciliation, not an anchor
6
8
 
7
9
  Breadth is a reconciliation of independent enumerations, never a single anchor. **No one requirement source is complete** — anchoring only on ADRs misses surfaces nobody wrote an ADR for; anchoring only on code misses intent that was never built.
@@ -22,7 +24,7 @@ Once a row is `Aligned` (or an `Orphan surface` carrying its baseline floor), th
22
24
 
23
25
  ## Three layers
24
26
 
25
- 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.
27
+ When using the ledger, separate discovery, curated intent, and the generated aggregation; reconcile them where requested or already required. Status is **computed, never stored**, so per-requirement files for a shared surface cannot diverge — there is no status field to disagree on.
26
28
 
27
29
  - **Generated inventory** (never hand-edited): surface discovery from code — routes, APIs, tables, events. Regenerated on every change.
28
30
  - **Curated coverage** (hand-maintained, one file per requirement at `docs/tests/<adr|prd|design>/<id>-<slug>.coverage.yml`): the surfaces that requirement owns, each with required test level, `uiOnly`, criteria link, optional gap issue. Ownership and intent only — **not** status.
@@ -53,9 +55,9 @@ The aggregation maps `@covers` → surface, checks required levels, flags intern
53
55
 
54
56
  ## Acceptance gate
55
57
 
56
- Make coverage a precondition of accepting a requirement, not an optional follow-up.
58
+ When the repository has adopted this ledger acceptance gate, follow its configured requirements. Otherwise this is an optional mechanism, not a new acceptance gate.
57
59
 
58
- - 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.
60
+ - If the adopted gate requires it, an accepted requirement with runtime behavior owns `docs/tests/<source>/<id>-*.coverage.yml` linked to its `criteria` doc.
59
61
  - A known gap is declared, not hidden: the coverage file names a `gapIssue` or `gapDoc` in place of `criteria` while the gap is open.
60
62
  - A requirement with no runtime behavior (pure architecture, terminology) says "no runtime behavior" in its own text and needs no coverage file.
61
63
  - The gate is mechanical: `coverage.config.json` → `requirementGlobs: { adr: "docs/adr" }` (and `prd`, `design`, …); `coverage-ledger.mjs validate` then errors on every accepted document with no coverage file, or a coverage file with neither criteria nor a tracked gap. `acceptedMarker` overrides the default `status: accepted` / `**Status:** accepted` match.
@@ -74,7 +76,7 @@ The breadth axis is enforced by checks that fail (error) or warn:
74
76
  - required level is integration/API/journey but only unit/mock evidence resolves;
75
77
  - internal interception counted as behavior coverage (`Over-mocked`).
76
78
 
77
- 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)).
79
+ Run reconciliation when requested or required by the repository, within the authorized scope. Keep generated inputs deterministic and report stale inventory rather than repairing it during an audit. Existing required CI checks remain binding; do not add a gate without authorization ([CI contract](../enforcement/ci-contract.md)).
78
80
 
79
81
  ## Reference validator
80
82
 
@@ -87,6 +89,6 @@ node ~/.agents/skills/ensure-coverage/scripts/coverage-ledger.mjs validate [--co
87
89
  node ~/.agents/skills/ensure-coverage/scripts/coverage-ledger.mjs report # markdown index + ADR matrix view
88
90
  ```
89
91
 
90
- **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).
92
+ **Outputs.** `aggregate` writes the surface-keyed `coverage-index.json` **and** a sibling `coverage-metrics.json` — roll-up counts plus the **over-mock rate** (`overMocked / tested` depth-graded surfaces, split `overMockedBehavior` / `overMockedPresentation`). The metric is a separate file, not a key in the index. `validate` and the `report` header print the rate inline (`N/T tested surfaces over-mocked (X%)`). Treat the over-mock count as a lead to inspect in context ([../depth/mock-policy.md](../depth/mock-policy.md)); the *rate* is a trend signal, not an automatic feature blocker. An adopted required gate retains its configured result.
91
93
 
92
94
  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`.
@@ -2,7 +2,7 @@
2
2
 
3
3
  > 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).
4
4
 
5
- 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.
5
+ Use the table as guidance when selecting proof for the agreed scope and material risks, not as a universal obligation for newly discovered surfaces. Existing repository-adopted floors and required checks remain binding unless changed through approval. A requirement document is not needed to recognize a concrete risk. The rules below describe the bundled ledger's mechanical defaults when it is used, not new policy for every feature.
6
6
 
7
7
  **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.
8
8
 
@@ -27,9 +27,9 @@ Baseline only **entry surfaces** (`route`, `api`). **Internal surfaces** (`table
27
27
  | permission | — | `integration` | resolves an auth test |
28
28
  | integration (external) | — | fake adapter + contract | — |
29
29
 
30
- 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.)
30
+ In the ledger, every **live browser route is `browser-journey` at minimum** — `class` changes only *what the journey additionally proves*, not *whether* you drive the page. A genuinely static/content page (marketing, docs) is downgraded via the **`static` exclusion category** to a `render-health` floor — a cheap reachability guarantee, never weakening the floor for real app pages. (`smoke` is accepted as an alias for this level; it is not the curated `smoke` gate, which is a cross-flow liveness check, not a per-route level.) **`render-health` is a browser-level check, not an API ping**: a real browser must load the rendered page and confirm it renders without error (externals may be faked). An HTTP-200 / API-level test does **not** satisfy it. The other exclusion categories (`seed`/`deprecated`/`internal`) drop to manifest-only. `render-health` is the one level a present-but-shallow test can satisfy, precisely because it is definitionally shallow. (Same "page loads/renders" concept as e2e-test's Tier-1 and the `presentation:render-health` spine.)
31
31
 
32
- Every live browser route *also* auto-carries the **Presentation floor** on top of the functional floor above — see [../presentation/axis.md](../presentation/axis.md).
32
+ In the ledger, every live browser route *also* auto-carries the **Presentation floor** on top of the functional floor above — see [../presentation/axis.md](../presentation/axis.md).
33
33
 
34
34
  ## Exclusion is gated, not honored on a reason
35
35
 
@@ -41,4 +41,4 @@ An exclusion downgrades a surface to manifest-only — the exact move that re-op
41
41
 
42
42
  ## The feature card is a deviation record, not a precondition
43
43
 
44
- 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.
44
+ When using the ledger, because its baseline auto-applies, a surface with no requirement is **not blocked on authoring a file** — it is already graded at its floor. A curated `…coverage.yml` (the "feature card") is required only to **deviate**: raise above baseline, mark `sensitive`, exclude, attest (`verified`), or attach `owner`/`purpose`/`userVisibleContract` ownership. Pure happy-path baseline surfaces need no card. Requirement *ownership* (traceability) is a `warn`; the baseline *test obligation* is the hard gate.
@@ -4,13 +4,13 @@
4
4
  >
5
5
  > **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.
6
6
 
7
- 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:
7
+ Use this protocol within the agreed audit scope, even if `e2e-test` is unavailable. Enumerate the whole repository only for an explicitly requested broad audit. For scoped work, inspect relevant routes and their reachability as needed; the following describes comprehensive discovery for Next.js App Router and similar file-based routers:
8
8
 
9
9
  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.
10
10
  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.
11
11
  3. Classify reachability as `Reachable`, `Redirected`, `Guarded`, `Blocked`, or `Unknown`, with the guard/layout/middleware evidence.
12
- 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.
12
+ 4. For relevant `Reachable` pages, identify user-actionable mutations and their backend targets. Distinguish rendering from submission and durable-state evidence; select proof based on agreed criteria and material risks, not an automatic journey obligation per mutation.
13
13
  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.
14
- 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.
14
+ 6. Report relevant concrete gaps and unavailable evidence. Treat missing journey coverage according to agreed criteria and existing required floors, not as an automatic feature blocker.
15
15
 
16
16
  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.
@@ -1,68 +1,7 @@
1
- # Depth: Characterization — pin existing behavior before you change it
1
+ # Characterization and fails-first evidence
2
2
 
3
- > Read when: a change **modifies existing behavior** (edits/deletes lines in a non-test source file) rather than adding a brand-new surface. Sibling: [grading.md](grading.md) (how each obligation is graded), [mock-policy.md](mock-policy.md) (the boundary). New-surface work is TDD red→green; *this* is the obligation for touching code that already runs in production.
3
+ When changing existing behavior, consider whether a relevant existing test already protects the behavior that should stay unchanged. Reuse it if sufficient. Add a characterization test when the risk of unintended change warrants it; it captures actual behavior at an observable boundary, including quirks. Do not require a new test or pre-change run for every source edit, or introduce a seam solely to satisfy a blanket rule.
4
4
 
5
- Michael Feathers' rule: *"Characterization tests document the actual behavior of the code, not the intended behavior."* The common agent failure mode: it refactors or "fixes" a function, the existing tests stay green (they never covered the changed path), and an **observable behavior silently shifts**. A green suite after the change proves nothing if no test pinned the behavior *before* it.
5
+ For a bug fix, a test that fails before the fix and passes afterward can show that the fix addresses the defect. Use it when practical and useful or when repository policy requires it; otherwise explain the proof and any limitation. A feature test should make meaningful assertions about the agreed outcome, not just a mock call or a fixture that bypasses the real behavior. Inspect it before claiming coverage; a broken-tree run is not automatically required.
6
6
 
7
- So a modification carries a depth obligation a fresh feature does not: **before you change existing behavior, write a test that captures what the code does today, and make it pass against the unchanged tree.** That test becomes a boundary the change cannot silently cross — the seam ([below](#seams-where-to-pin)) at which you alter behavior deliberately.
8
-
9
- ## The obligation: when it is owed
10
-
11
- A change owes a characterization test when **all** hold:
12
-
13
- - It **edits or removes** existing lines of a non-test **source** file (a pure addition into a new file, or appended-only code, is new behavior → TDD path).
14
- - The touched code has **observable behavior** — return value, durable-state effect, emitted event, HTTP contract, rendered output. (Internal-only renames with no behavioral surface don't.)
15
- - The surface is **non-trivial** — anything carrying a Surface Baseline floor, or logic a user/caller depends on.
16
-
17
- When owed, the test must: **(1) capture actual, not intended, behavior** including quirks/bugs (if current behavior is wrong, characterize it *then* fix it in a separate declared step); **(2) pass on the pre-change tree** (GREEN on `HEAD~`/base before your edit — capture as evidence); **(3) still pass after the change**, unless the change is a declared intended behavior change.
18
-
19
- ## When it is waived
20
-
21
- Mark the waiver explicitly in the PR's evidence, never silently:
22
-
23
- - **Already pinned** — an existing behavior test covers the exact changed path and still passes unchanged. Cite it (`file:line`); that test *is* the characterization.
24
- - **Declared intended behavior change** — deliberately alters observable behavior per an AC/bug brief. The obligation inverts: update/author the test to assert the **new** behavior, and the diff must show the old assertion changing to the new (a behavior change with no test delta is the suspicious case). Cite the AC.
25
- - **Trivial / generated / non-behavioral** — formatting, comments, type-only edits, generated code with no behavior delta.
26
-
27
- ## The `@characterizes` convention
28
-
29
- Tag a characterization test so the gate can resolve it, parallel to `@covers`:
30
-
31
- ```js
32
- // @characterizes <surface-id> // pins prior behavior of a surface being modified
33
- // @covers <surface-id> // (a characterization test usually also @covers it)
34
- // @level <level>
35
- ```
36
-
37
- `@characterizes` is the signal that *this* test exists to hold a modification's behavior boundary. A modifying diff with no `@characterizes` test and no declared waiver is the gap this obligation names.
38
-
39
- ## Grading
40
-
41
- Characterization is a **depth** concern, graded with the [shared vocabulary](grading.md):
42
-
43
- - A modifying diff whose changed behavior is pinned by a passing characterization test (or cited pre-existing behavior test) → that surface can reach `Covered` on the normal evidence rules.
44
- - A modifying diff with **no** characterization test and **no** declared intended-change → `Partial` at best; the reviewer raises the `modifies-existing-behavior` lead (below). Not a hard `Missing` (existing tests may incidentally cover it) — a **lead to adjudicate**, because whether a characterization test is *needed and adequate* is judgment.
45
-
46
- ## Detection (mechanical) → adjudication (judgment)
47
-
48
- The decidable half is mechanical: any non-test source file with **removed/changed** lines emits a `modifies-existing-behavior` **lead** ("look here and verify," never an auto-finding). The reviewer checks for a `@characterizes` test (or a declared change) and adjudicates, citing `file:line`. The reviewer resolves it with a locator, not prose. The split matches the GATE-vs-LEAD line everywhere in this skill: detecting *that behavior changed* is mechanical; deciding *whether the pinning test is adequate* is semantic.
49
-
50
- ## Seams: where to pin
51
-
52
- A characterization test is writable only where you can observe behavior without rewriting the thing you're about to change — a **seam** (*"a place where you can alter behavior without editing the code in that place"*). Pin at the nearest observable seam: the public function's return/throw, the endpoint's HTTP contract, the rendered page's output, the emitted event. If there's no seam, that itself is the finding — introduce one first (extract the call, expose the boundary), pin, *then* change. Do not skip characterization because "it's hard to test as written"; hard-to-pin is the legacy-code smell the obligation exists to surface.
53
-
54
- ## Fails-first: bug-fix AND feature-AC — prove the test fails when the behavior is broken
55
-
56
- The shared property: **a test is evidence for a behavior only if it would go red were that behavior broken.** A green test that passes with *and* without the behavior it claims is **vacuous coverage** — it locks in nothing. Two cases:
57
-
58
- **Bug-fix sibling.** A bug fix changes behavior that's *already wrong*, so it owes the inverse of characterization: at least one test demonstrated to **fail on the unfixed code and pass on the fixed code** (RED→GREEN, run in that order), tagged `// @fails-without-fix <surface>`. Reverting the fix must turn the test red. Waive only with a cited reason the failure can't be reproduced in-suite (a tracked `Unverified` manual check, not a silent skip).
59
-
60
- **Feature-AC sibling.** The same test applies to a *new feature's* AC, where it's most-missed: a green test cited for an AC clears it only if it would go red were the AC's behavior removed — it exercises the AC's real code path, not a proxy. Recurring vacuous forms:
61
- - a fixture that **early-returns before the code runs** (a 0-step workflow "proving" a multi-step reset that never executes);
62
- - a `.fill()`/`setValue` that sets state in one shot and so **masks a re-render/defocus bug** a character-by-character `pressSequentially` would expose;
63
- - an assertion **pinned to a stand-in value the real producer never emits**;
64
- - asserting **the mock was called** rather than that the outcome happened.
65
-
66
- **Grading the two outcomes** (they differ from [grading.md](grading.md)'s `Unverified`): can't-yet-confirm it would go red → `Unverified` (a warning unless `unverifiedBlocks: true`); confirm it would **still pass** with the behavior gone → `Missing`/`Over-mocked` (a proven-vacuous test is *worse* than unchecked).
67
-
68
- The two **decidable** vacuous forms (a swallowed assertion, a fixed timeout) are gated by `lint-tests`; the semantic "would it have been red?" property is verified at review and by running the test against the broken tree. Named incident: the login regression (#237), where a green sweep asserted nothing the bug could trip.
7
+ If an existing adopted gate requires annotations, a pre-change run, or other evidence, follow it unless an approved change alters the gate. Grade evidence honestly using [grading](grading.md).
@@ -2,11 +2,9 @@
2
2
 
3
3
  > Read when: grading whether a test actually proves the behavior against real state. Sibling: [mock-policy.md](mock-policy.md) (the boundary principle this grading enforces). Depth grades each `Aligned` row — and each `Orphan surface` carrying a [Surface Baseline Contract](../breadth/surface-baseline.md) floor — by inspecting its actual tests.
4
4
 
5
- The canonical depth failure is **internal interception counted as behavior**: a Playwright `route.fulfill`/`page.route(` faking your own endpoint's response, or any substitute standing in for an internal seam. It makes a surface *look* covered while proving only proxy wiring — the boundary violation the [Mocking Stance](mock-policy.md) forbids. Classify it `Over-mocked`, never `Covered`.
5
+ A depth failure occurs when a substitute bypasses the behavior a test claims to prove. For example, a Playwright interception of an endpoint cannot prove that endpoint's real behavior. Grade that claim `Over-mocked`, not `Covered`; a focused UI test may still prove its own scope. See the [mock policy](mock-policy.md).
6
6
 
7
- **Separate browser routes from API routes; prove each with its own evidence kind.** Prove an API route (`route.*`) by hitting the endpoint and asserting the HTTP contract, auth, and durable state. Prove a browser route (`page.*`) by driving the rendered page: what it displays, what the user can do, and what happens when they do. Never grade a browser route `Covered` because its backing endpoints are covered (the `/settings/connectors` miss) — a green API test under a page is necessary but never sufficient.
8
-
9
- **For any write form, require one test that fills the rendered UI and asserts the mutation end to end** — operator fills the actual form and submits → backend accepts → durable state changes. Keep the render-health watcher attached **through** the submit (compose with `presentation:render-health`, [../presentation/axis.md](../presentation/axis.md)), so an uncaught error / `console.error` / first-party 5xx fired *during* the write fails the test even when the durable-state assertion would pass — the "mutate-health" gap. Do not accept seam tests in its place: a schema endpoint returning fields, a validator rejecting bad input, and an API forwarding a hand-built payload all pass while the rendered form silently drops a backend-required field. This is acute for the **split-contract form**, whose fields come from one source (schema endpoint, config descriptor, generated form spec) and validation from another (the backend contract); only a rendered-form submission proves the form emits a payload the backend accepts.
7
+ Distinguish what API and browser evidence actually proves. An API test alone does not prove a rendered form works; a UI test that fakes the backend does not prove durable state. Select the proof needed for the agreed outcome and material risk, reusing existing evidence where sufficient. A rendered end-to-end submission can expose split-contract form failures, but is not an automatic new obligation for every form. Existing adopted floors and required checks remain binding.
10
8
 
11
9
  ## Evidence Hierarchy
12
10
 
@@ -25,11 +23,11 @@ Classify coverage as `Covered` only after inspecting the relevant test file/case
25
23
 
26
24
  A self-declared `@level` is a claim the validator must try to **refute**, and can never alone reach `Covered`. The three terminal states are marked below.
27
25
 
28
- - `Covered` (green, terminal): inspected test code validates the AC at the right level with meaningful assertions and acceptable mock/fake use, **and** the test has been read and marked `verified: true`. A self-declared `@level` alone never reaches it.
29
- - `Partial`: some behavior is tested, but edge cases, failures, permissions, state, or evidence are incomplete.
26
+ - `Covered` (green, terminal): inspected test code validates the agreed AC at the appropriate level with meaningful assertions and acceptable mock/fake use. A self-declared `@level` alone never reaches it. The ledger additionally requires its `verified: true` attestation.
27
+ - `Partial`: some agreed behavior or material-risk proof is incomplete. An untested hypothetical state alone is not an automatic blocker.
30
28
  - `Missing`: no meaningful test maps to the AC.
31
29
  - `Wrong Level`: test exists but is too shallow for the risk — e.g. unit-only for stateful workflow, API contract, auth, money movement, concurrency, or event behavior.
32
- - `Over-mocked` (red, terminal): mocks bypass the behavior the AC must prove — a behavior/journey test that intercepts first-party traffic (`page.route`, `route.fulfill`, MSW, first-party fixtures), or a `mutation` journey that never resolves a real durable-state path. Proves only proxy wiring.
30
+ - `Over-mocked` (red, terminal): substitutes bypass the behavior the agreed AC must prove. For example, an intercepted endpoint cannot prove its real durable-state path; the test may still prove a narrower UI behavior.
33
31
  - `Unverified` (yellow, terminal): the level is satisfied statically (or claimed by docs/reports/CI) but nobody has read the test yet. It is a **warning** by default; it blocks only when the user sets `unverifiedBlocks: true`. Marking `verified: true` after reading the test promotes it to `Covered`; no evidence is required unless the user asks for it. The residual variance is over *quality of an existing test*, not *whether a surface exists*.
34
32
  - `Excluded`: a human marked the surface out of scope with category + reason and the adapter signals permit it; surfaced in the exclusion census.
35
33
  - `BLOCKED`: required source, code, tests, route discovery, environment, or product decision is unavailable.
@@ -4,11 +4,7 @@
4
4
 
5
5
  ## Mocking Stance
6
6
 
7
- Default to real. The governing principle is **real internals, faked externals, nothing in between**:
8
-
9
- - A test substitute is permitted **only at a trust boundary you do not own**: third-party HTTP APIs, payment/KYC providers, email/SMS, the clock, randomness.
10
- - Everything **inside** your own system runs for real: database, repositories, service layer, internal endpoints, event bus. A substitute for an internal seam is a design smell or coverage gap, not a testing choice.
11
- - The rule is **two-sided**: don't mock inward, don't reach outward — externals must be replaced by a fake/stub adapter so tests stay deterministic and never call a live third party in CI. "Be pure by calling the real provider" is the opposite failure, also rejected.
7
+ Choose substitutes based on what the test must prove and the material risk. Unit tests may isolate internal collaborators, but a substitute cannot prove the behavior it replaces. Use real boundaries where needed to prove security, tenancy, money, or durable-state behavior, subject to existing repository policy. Fake external providers when necessary for safe, deterministic tests; follow the repository's rules for live services.
12
8
 
13
9
  The problem we reject is **mock-only coverage of behavior that must be proven against real state** — not the presence of mocks. Fakes/stubs that keep failure-path and edge tests fast and deterministic are good and expected.
14
10
 
@@ -43,15 +39,13 @@ These are **internal** and are therefore never covered by substitutes alone:
43
39
 
44
40
  Prefer integration tests with real app/service code, real DB or test containers with migrations, queue/pub-sub emulators where practical, fake external provider adapters, and assertions on final durable state, emitted events, and externally visible outcomes.
45
41
 
46
- ## Mechanized gate: `mock-internal-seam` (zero-tolerance)
42
+ ## Optional scan: `mock-internal-seam`
47
43
 
48
- The decidable core of the stance is a hard gate, because over-mock is the failure mode that shipped a production incident behind green tests. The trick that makes it decidable is the **externals-allowlist inversion**: internal seams are unbounded, but the set of things that may legitimately be faked is small and known. So a mock whose target resolves to first-party code is a defect; anything on the declared externals allowlist, a bare npm package, or the stdlib is exempt.
44
+ The following describes the scanner's strict mechanics, not a universal ban on internal test doubles. Run it when requested or required by the repository; a whole-tree scan belongs to an explicitly requested broad audit. Assess hits against the behavior and risk rather than counting them as automatic feature blockers. Existing required gates remain binding.
49
45
 
50
- - **Default-on, no waiver, no grandfathering.** Config only declares topology; it cannot turn the gate off. A believed false positive is fixed by declaring the truth in `coverage.config.json`, never by waiving.
51
- - **Both lanes.** Diff-scoped for new seams, whole-tree for inherited ones; a tree with existing over-mock stays red until it is removed.
52
- - **Three resolutions, and "keep it" is not one:** replace with a real-boundary test, fake only the external behind it, or **delete** the test. Over-mock is worse than no test: an untested route is an honest gap, an over-mocked one is dishonest green. Deletion reverts the surface to its honest breadth status (`Missing` or `Excluded`).
53
- - **In audit mode, run it whole-tree from this skill against the target repo** and count every hit as an `Over-mocked` row and a no-ship contributor. A missing `coverage.config.json` means "run on defaults", not "not applicable"; the scripts' absence from the audited repo means nothing.
46
+ The scanner uses an **externals-allowlist inversion**: it flags mocks resolving to first-party code and exempts declared externals, bare npm packages, and the standard library. Its default configuration is strict; a flag does not itself establish that a test is inadequate. Where an adopted required gate fails, report the failure and seek the appropriate approved resolution rather than bypassing it. Do not delete a useful test merely to silence an optional scan.
47
+ - **When run**, a missing `coverage.config.json` uses defaults. The scripts live in this skill, not the audited repo. A hit is a lead; determine whether the test actually bypasses the behavior it claims to prove.
54
48
 
55
- What stays a review lead: whether a real-boundary sibling exists, shallow assertions, semantically wrong fakes. The gate proves the decidable shell; the reviewer judges the rest. The ledger also reports an over-mock *rate* as a trend signal; the merge bar stays "count is zero".
49
+ Whether a real-boundary sibling exists, assertions are shallow, or fakes are wrong requires judgment. The scanner detects patterns, not their full meaning. The ledger's over-mock rate is a trend signal; do not invent a zero-count merge bar.
56
50
 
57
51
  CLI, rules, and the `coverage.config.json` topology keys: [`scripts/README.md`](../../scripts/README.md).
@@ -2,7 +2,7 @@
2
2
 
3
3
  > Read when: the user asks what this skill should require, wire, or audit in CI.
4
4
 
5
- Curated golden-path smoke is the **only CI gate supported by this skill**. The coverage ledger, inventory freshness, presentation sweep, broad E2E suite, test lint, over-mock scan, design parity, and quarantine expiry remain local or review-time evidence. Do not propose, require, wire, or audit them as CI gates.
5
+ When asked to propose a CI gate, this skill supports curated golden-path smoke. Do not propose, require, wire, or audit additional gates without an explicit request. Existing repository-required checks, including checks outside this menu, remain binding; do not bypass or remove them.
6
6
 
7
7
  ## What smoke proves
8
8
 
@@ -2,7 +2,7 @@
2
2
 
3
3
  > Read when: working any `presentation:*` invariant. Sibling: `e2e-test/references/presentation-sweep.md` (the runner and the result shape it emits). This skill *grades* the axis; the `e2e-test` sweep *runs* it.
4
4
 
5
- The **Presentation** axis (third axis) rides the [Surface Baseline Contract](../breadth/surface-baseline.md) machinery as a per-route floor. Every live browser route auto-carries a presentation obligation *on top of* its `browser-journey` floor, checked at the viewport floor `[375, 1280]` (default theme, seeded data).
5
+ Consider presentation evidence when it matters to the agreed outcome or material risks. The following describes the bundled ledger and sweep's per-route mechanics, not a new universal requirement or an automatic presentation campaign. Existing repository-adopted floors and required checks remain binding unless changed through approval. In the ledger, every live browser route carries a presentation floor at `[375, 1280]` (default theme, seeded data).
6
6
 
7
7
  > **This skill grades the axis; it does not run it.** The tokens below are *graded* by the Coverage Ledger (does a qualifying real-render test exist, is it non-intercepting, is it attested). The *instruments* that open a browser and observe these invariants live in the **`e2e-test` skill's presentation sweep**. ensure-coverage owns the **obligation**; the runner and the per-`(route, level)` result shape the ledger consumes are documented with the runner (`e2e-test/references/presentation-sweep.md`). This mirrors how breadth delegates surface discovery to an inventory adapter ([../breadth/inventory-contract.md](../breadth/inventory-contract.md)).
8
8
 
@@ -14,7 +14,7 @@ Invariants, **spine first**:
14
14
  - **`presentation:reachability`** — a user can get to the page and tell its controls are actionable: every manifest route is reachable by crawling the rendered nav (no **navigational orphan**), interactive controls show a visible focus indicator and meet the ≥44px target floor. Negative form: a modal traps focus (no click-through / focus escape); a privilege-gated route is not navigationally reachable for the wrong role.
15
15
  - **`presentation:temporal`** — the layout holds still as things inject. **Split by who renders the shift** — *first-party* (lazy images, async data, our dynamic fields) is a **hermetic gate** (real render, no network; before/after geometry gated on a stable condition, never a fixed sleep, or a `PerformanceObserver` CLS score). *Third-party* (Stripe/Adyen payfields) runs against the provider **sandbox iframe** in a **non-blocking PR lane**: a failure posts a visible annotation and the surface stays `Unverified` until the test is read and marked `verified: true`. Top-page CLS is **structurally blind to cross-origin iframes** (WICG excludes descendant frames), so this is a before/after geometry assertion gated on a provider-ready signal, not CLS. The mobile **dynamic-viewport (`dvh`/`100vh`) cell** is gated via Playwright emulation with a tuned tolerance (staging fallback if flake is unmanageable).
16
16
 
17
- "Graded" means the ledger marks a route's floor `Missing` / `Over-mocked` / `Unverified` / `Covered` from the tests that exist — it cannot itself detect a runtime crash, which is why the sweep is a **separate evidence run**, not a side effect of the functional E2E suite. It is not a CI gate; curated golden-path smoke is the sole CI gate ([CI contract](../enforcement/ci-contract.md)).
17
+ "Graded" means the ledger marks a route's floor `Missing` / `Over-mocked` / `Unverified` / `Covered` from the tests that exist — it cannot itself detect a runtime crash, which is why the sweep is a **separate evidence run**, not a side effect of the functional E2E suite. It is not a new CI gate; existing repository-required checks remain binding ([CI contract](../enforcement/ci-contract.md)).
18
18
 
19
19
  The floor runs at the screen viewport floor (`[375, 1280]`). The **`media=print` cell is warn-only by default** — a broken print stylesheet is logged in the census, not a blocking gate (lower-frequency, harder to assert deterministically). A surface may escalate it to a gate when print output is a real product surface (e.g. an invoice).
20
20
 
@@ -37,7 +37,7 @@ A cell-qualified level grades exactly like its base (real render, exact-match, D
37
37
 
38
38
  A presentation level is **exact-match** and proven only against a **real rendered page**:
39
39
 
40
- - A functional `browser-journey` does **not** satisfy a presentation level — a journey clicks the DOM; it never asserts no-overflow or perceivability. Each is required separately; one presentation level does not satisfy another.
40
+ - In the ledger, a functional `browser-journey` does not automatically satisfy a separate presentation level. For scoped proof, a single test can demonstrate multiple outcomes if its assertions actually cover them.
41
41
  - A DOM-only / JSDOM assertion of a presentation level grades **`Over-mocked`** — the axis's proxy-wiring (it can't see what a human sees). The proving test must drive a real browser.
42
42
  - Like any obligation, a statically-satisfied presentation level lands at `Unverified` until the test is read and marked `verified: true`.
43
43
 
@@ -51,7 +51,7 @@ Every level above is **self-referential**: render-health asks whether the page r
51
51
 
52
52
  That gap is not theoretical. A baseline captured from a wrong implementation is green forever — in the incident below it would have locked in a card plane the design did not have and a flattened type scale, and reported success. Drift detection cannot substitute for fidelity, because it takes the implementation as its own authority.
53
53
 
54
- **When it is owed.** A unit whose source cites a design artifact — a prototype branch/path, a mockup, a design doc that fixes layout — carries `presentation:fidelity` on the surfaces that artifact covers. A unit with no cited design source does not; this is not an auto-floor and inventing one for a CRUD tweak is ceremony.
54
+ **When it is relevant.** Compare the implementation with a cited design where the agreed outcome calls for fidelity. Use the parity workflow when requested or required by the repository; citing a design alone does not automatically mandate a campaign.
55
55
 
56
56
  **The rule that makes it fidelity.** Every expected value is read off the **source**, with it rendered, and cites the source line it came from. A value copied off the page you built is a baseline wearing a fidelity label.
57
57
 
@@ -59,6 +59,6 @@ That gap is not theoretical. A baseline captured from a wrong implementation is
59
59
 
60
60
  **No rewriting the target to match the page.** The cheapest way to green this gate is to edit `expected` instead of fixing the page. Because the source is pinned, a changed `expected` under an unmoved `source.sha` is mechanically detectable and blocks; a genuine mis-read is declared with `rebase: <reason>`. The reviewer treats an undeclared rewrite as a blocker, exactly as it does a silent re-baseline.
61
61
 
62
- **The render is not optional.** A property list catches what someone thought to list. Before the terminal review, render source and deliverable at the floor viewports side by side in the PR.
62
+ When the parity workflow is agreed or required, rendering source and deliverable side by side can reveal differences that a property list misses.
63
63
 
64
- Two hard rules, from the named incident (fmm-express #521, 2026-08-06: a cited prototype was summarized once into four bullets, nothing downstream re-read or rendered it, and the criteria doc listed visual baselines under non-goals, so a green suite shipped a page that took four rounds of correction): a presentation-only unit **may not** list visual or parity evidence as a non-goal, and a cited design source is **consumed, not summarized**.
64
+ The fmm-express #521 incident shows why a presentation-focused change may need direct comparison with its design source. Agree that proof before implementation; do not impose the full parity workflow on unrelated features.
@@ -1,27 +1,11 @@
1
1
  # Audit Mode (process)
2
2
 
3
- > Read when: auditing whether existing code/tests cover a requirement, PR, issue, feature, or bugfix. Audit current sufficiency against the behavior-first criteria; do not only generate ideal future criteria. Coverage classifications used here are defined in [../depth/grading.md](../depth/grading.md).
3
+ Audit the agreed feature scope against its observable criteria and material risks. A whole-repo census is only for an explicitly requested broad audit. Existing required checks and adopted floors remain binding.
4
4
 
5
- Audit steps:
5
+ 1. Establish the source, scope, criteria, and required repository checks. Identify product or architecture questions for their owners.
6
+ 2. Inspect relevant behavior and existing tests; map evidence to the agreed criteria. A prior report is a lead, not proof of test content. Reuse sufficient proof rather than requiring redundant layers.
7
+ 3. Grade honestly using [grading](../depth/grading.md). Describe concrete material gaps and any unavailable evidence. A hypothetical untested state alone is not a feature blocker.
8
+ 4. Report what was verified, failed or unavailable, distinguishing required fixes and decisions from speculative follow-ups. A newly discovered concrete defect may need a fix; do not silently add criteria after implementation starts.
9
+ 5. Audit CI wiring only when asked. A missing optional coverage gate is not a finding. Required repository checks still apply.
6
10
 
7
- 1. Derive ACs from the source before inspecting implementation details.
8
- 2. Identify public interfaces, workflows, state transitions, side effects, code paths, and existing tests.
9
- 3. For E2E audit, run the [Route Discovery & Reachability Protocol](../breadth/surface-discovery.md) before judging coverage.
10
- 4. Identify critical journeys with actor/role, start state, trigger, major steps, expected end state, route reachability, and observable side effects.
11
- 5. Map each AC and journey to existing tests only after inspecting the actual test files/cases/assertions; prior docs, PR summaries, or agent reports are leads, not proof.
12
- 6. Reject coverage that only validates private functions, implementation structure, or shallow route render-health checks for business journeys.
13
- 7. Create follow-up items for every gap with required test level, setup/input, assertions, and mock/fake policy.
14
- 8. Reach a production-readiness verdict — an explicit ship / no-ship call, the specific scenarios a real user would hit in the first week, and the evidence that would raise confidence — and **put it at the TOP of the deliverable** (the reader's first question is "what's the call?"; the census and detail justify it below). Do not let mapped ACs alone earn a ship call. Separate **blocking decisions** (product/scope choices that change the verdict and need a human answer) from **follow-up actions** (work to schedule) — see the output template; don't dump both into one vague "open questions" list.
15
- 9. **Do not audit CI wiring** unless the user asks. A repo without coverage gates in CI is not a finding. When the user does ask, run `ci-audit.mjs` against the repo's CI config and report curated golden-path smoke as present / warn-only / absent. Do not turn the other audit checks into CI findings; they contribute directly to the coverage verdict.
16
- 10. **Run the over-mock scan whole-tree** (`lint-tests.mjs --rules mock-internal-seam`, no `--diff`) from this skill against the target repo. Every hit is an `Over-mocked` census row and a no-ship contributor; **count them in the verdict**. A missing `coverage.config.json` means "run on defaults", not "not applicable"; a non-conventional topology earns a "declare topology" follow-up, never a downgrade of the finding ([../depth/mock-policy.md](../depth/mock-policy.md)).
17
- 11. If code, tests, or route discovery cannot be inspected or run, mark the assessment `BLOCKED` and state the missing access or command failure. "The lint script isn't in the audited repo" is not `BLOCKED`: the scripts are part of this skill ([../../scripts/README.md](../../scripts/README.md)).
18
-
19
- The coverage classifications (`Covered` / `Partial` / `Missing` / `Wrong Level` / `Over-mocked` / `Unverified` / `Excluded` / `BLOCKED`) are defined in [../depth/grading.md](../depth/grading.md). Use that vocabulary, not a vague "covered."
20
-
21
- ## Completeness: enumerate every surface, not just the salient gaps
22
-
23
- **Gap-finding must be exhaustive, not a highlight reel.** An audit that lists "the top 3 problems" silently leaves the long tail uncovered — where the un-ACed orphan hides. Completeness comes from **closed-world enumeration**:
24
-
25
- 1. **Start from the full surface inventory** (every route, API, write form, table, event, job — from [surface discovery](../breadth/surface-discovery.md) / the generated inventory), not the list of things you happened to notice.
26
- 2. **Emit a complete surface census**: one row per inventoried surface with its status. `gaps = inventory − {surfaces at Covered}`, so every surface is accounted for *by construction*. The census is the deliverable's backbone (the **Surface Census** table in [output-template.md](output-template.md)); the prose highlights the worst rows, but the table proves nothing was skipped.
27
- 3. **Every non-`Covered`/non-`Excluded` row is a gap** with its own follow-up item. If the inventory cannot be fully enumerated (no adapter, partial access), say so and mark the unenumerated portion `BLOCKED`; do not silently scope to what was easy to see.
11
+ For an explicitly requested broad audit, define its boundaries and use [discovery](../breadth/surface-discovery.md) or a census when useful. Report incomplete access or inventory rather than claiming completeness. The optional whole-tree over-mock scan produces leads to assess in context, not automatic feature no-ship findings; an existing required gate retains its own result.