@1aboveio/skills 1.0.10 → 1.0.12

package/skills/engineering/ensure-coverage/references/depth/mock-policy.md

@@ -4,11 +4,7 @@
 
 ## Mocking Stance
 
-Default to real. The governing principle is **real internals, faked externals, nothing in between**:
-
-- 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.
-- 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.
-- 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.
+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.
 
 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.
 
@@ -43,15 +39,13 @@ These are **internal** and are therefore never covered by substitutes alone:
 
 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.
 
-## Mechanized gate: `mock-internal-seam` (zero-tolerance)
+## Optional scan: `mock-internal-seam`
 
-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.
+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.
 
-- **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.
-- **Both lanes.** Diff-scoped for new seams, whole-tree for inherited ones; a tree with existing over-mock stays red until it is removed.
-- **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`).
-- **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.
+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.
+- **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.
 
-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".
+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.
 
 CLI, rules, and the `coverage.config.json` topology keys: [`scripts/README.md`](../../scripts/README.md).

package/skills/engineering/ensure-coverage/references/enforcement/ci-contract.md

@@ -2,7 +2,7 @@
 
 > Read when: the user asks what this skill should require, wire, or audit in CI.
 
-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.
+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.
 
 ## What smoke proves
 

package/skills/engineering/ensure-coverage/references/presentation/axis.md

@@ -2,7 +2,7 @@
 
 > 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.
 
-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).
+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).
 
 > **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)).
 
@@ -14,7 +14,7 @@ Invariants, **spine first**:
 - **`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.
 - **`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).
 
-"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)).
+"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)).
 
 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).
 
@@ -37,7 +37,7 @@ A cell-qualified level grades exactly like its base (real render, exact-match, D
 
 A presentation level is **exact-match** and proven only against a **real rendered page**:
 
-- 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.
+- 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.
 - 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.
 - Like any obligation, a statically-satisfied presentation level lands at `Unverified` until the test is read and marked `verified: true`.
 
@@ -51,7 +51,7 @@ Every level above is **self-referential**: render-health asks whether the page r
 
 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.
 
-**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.
+**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.
 
 **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.
 
@@ -59,6 +59,6 @@ That gap is not theoretical. A baseline captured from a wrong implementation is
 
 **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.
 
-**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.
+When the parity workflow is agreed or required, rendering source and deliverable side by side can reveal differences that a property list misses.
 
-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**.
+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.

package/skills/engineering/ensure-coverage/references/process/audit-mode.md

@@ -1,27 +1,11 @@
 # Audit Mode (process)
 
-> 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).
+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.
 
-Audit steps:
+1. Establish the source, scope, criteria, and required repository checks. Identify product or architecture questions for their owners.
+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.
+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.
+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.
+5. Audit CI wiring only when asked. A missing optional coverage gate is not a finding. Required repository checks still apply.
 
-1. Derive ACs from the source before inspecting implementation details.
-2. Identify public interfaces, workflows, state transitions, side effects, code paths, and existing tests.
-3. For E2E audit, run the [Route Discovery & Reachability Protocol](../breadth/surface-discovery.md) before judging coverage.
-4. Identify critical journeys with actor/role, start state, trigger, major steps, expected end state, route reachability, and observable side effects.
-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.
-6. Reject coverage that only validates private functions, implementation structure, or shallow route render-health checks for business journeys.
-7. Create follow-up items for every gap with required test level, setup/input, assertions, and mock/fake policy.
-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.
-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.
-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)).
-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)).
-
-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."
-
-## Completeness: enumerate every surface, not just the salient gaps
-
-**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**:
-
-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.
-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.
-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.
+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.

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

@@ -1,139 +1,24 @@
-# Output Template, Writing Rules & Validation (process)
+# Output Template, Writing Rules & Validation
 
-> 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:
+Use the issue or conversation by default. Create a document only when requested or required by the repository. Adapt this optional structure to the agreed scope rather than filling every section for routine work.
 
 ```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`>.
+## Outcome and scope
+- Source, agreed behavior, material risks, assumptions, and out-of-scope work.
+- Product or architecture decisions needing their owners, if any.
+
+## Agreed acceptance criteria and proof
+- Observable criteria agreed before implementation.
+- Existing tests or checks that suffice; focused additional proof if needed.
+- Required repository checks and applicable security or data-integrity protections.
+
+## Assessment (when auditing)
+- Evidence inspected and execution results; what each proves and does not prove.
+- Coverage grades for the agreed scope, with concrete gaps and unavailable evidence.
+- Required fixes or decisions, separate from speculative follow-ups.
+- What was verified and what was not.
 ```
 
-## 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:
+Use a surface census only for an explicitly requested broad audit; state its boundaries and any incomplete inventory. Do not invent a ship/no-ship verdict where the evidence or an owner decision is missing. If a verdict is requested, explain its concrete basis; do not make an untested hypothetical state an automatic blocker. A newly found concrete defect may require a fix without silently changing the agreed criteria.
 
-- 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).
+Prefer observable behavior to implementation-shaped assertions. Choose relevant failure, authorization, tenant-isolation, money, or durable-state cases based on material risk and existing policy. Preserve required repository checks and adopted floors. For design work, compare against the agreed design where needed; a cited source does not automatically require a separate presentation campaign. Inspect tests before saying they prove a behavior, and do not claim that an unavailable or failed check passed.

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

@@ -4,15 +4,15 @@
 
 ## Test Level Selection
 
-Classify each AC before writing the matrix:
+Choose sufficient proof for each agreed AC and material risk, reusing existing evidence. The examples below are options, not automatic extra layers; existing required checks and adopted floors remain binding:
 
 - 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.
+- Boundary AC: consider a contract/API test for request/response, validation, schema, compatibility, and error contracts.
+- Stateful workflow AC: consider an integration test for DB writes, transactions, state transitions, idempotency, and recovery.
+- Async/pub-sub/orchestrator AC: consider an integration test 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.
+- Browser/UI AC: consider UI E2E for page behavior, navigation, user-visible errors, forms, and role-dependent visibility.
+- Cross-page/core business journey: consider Journey E2E with real APIs where practical; do not mock internal endpoints unless explicitly approved.
 
 ## E2E Coverage Rules
 
@@ -31,12 +31,7 @@ Smoke is not a separate browser-test level. A browser smoke path is a **curated
 
 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.
+For audit mode, inspect the routes and journeys relevant to the agreed scope. A render-health test does not by itself prove a business journey; a backend test alone does not prove a form submits correctly. Use broader discovery only for an explicitly requested broad audit, and do not require a separate browser journey for every form by default.
 
 ## Test Skipping Policy (no-skip)
 

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

@@ -1,8 +1,9 @@
 # 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.
+This is the CLI reference for optional coverage tools. `SKILL.md` and `references/`
+define when a tool is relevant; the checks below describe its unchanged mechanics,
+not new acceptance conditions. Run a tool when requested or required by the repository.
+Preserve adopted gates, but do not turn an optional scan into a feature blocker.
 
 **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
@@ -45,7 +46,14 @@ Static test-lint gate engine. Deterministic, near-zero false positives, blocks o
 | `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:
+The scanner mechanically treats `mock-internal-seam` as default-on and zero-tolerance:
+`@mock-ok` and inherited code do not suppress its exit status. Whole-tree scanning
+belongs to an explicitly requested broad audit or an existing repo requirement;
+a scoped task uses scoped checks when needed. Assess optional hits against the
+behavior claimed; the classifier alone cannot determine test adequacy. Do not
+require remediation merely because an optional scan flags a useful isolated unit
+test. An adopted required gate remains binding. Correct topology declarations
+when the scanner misclassifies an external boundary:
 
 ```json
 // coverage.config.json at the repo root — declares what counts as first-party

package/skills/engineering/golden-path/SKILL.md

@@ -3,7 +3,7 @@ name: golden-path
 description: "Golden-path E2E: the short list of user journeys whose failure blocks a release, kept in a repo as one contract (golden-paths.json) with a generated GOLDEN_PATHS.md and a generated GitHub Actions workflow, and run against a local build or a deployed URL for an ALIVE/DEAD verdict. Use to set golden paths up in a repo ('init golden paths', 'add golden-path CI'), to migrate an older smoke.manifest.json or a hand-built smoke setup ('audit', 'migrate smoke'), to add, change, or remove a golden path, to ask 'is the build alive?' or run them before a PR or release, or when a change touches a flow listed in GOLDEN_PATHS.md. NOT for writing the Playwright specs themselves (e2e-test), deciding what a change must prove (ensure-coverage), or general workflow YAML (github-actions)."
 dependencies:
   - e2e-test
-release-version: 0.44.1
+release-version: 0.45.1
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Golden path

package/skills/engineering/harness-runtime/SKILL.md

@@ -3,7 +3,7 @@ name: harness-runtime
 description: Internal import-only library shared by first-party engineering packages. Not a workflow skill; never select or invoke it as a user capability.
 disable-model-invocation: true
 user-invocable: false
-release-version: 0.44.1
+release-version: 0.45.1
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Harness Runtime
@@ -17,3 +17,5 @@ This support-only runtime package exposes shared programmatic contracts plus can
 - `index.mjs` exports neutral constructors plus pure question planning and response normalization.
 - `discover-models.mjs` enumerates model evidence; `model-catalog.mjs` manages per-harness classifications.
 - `references/model-catalog.md` documents catalog policy; `bin/` contains the installed command wrappers.
+- `workspace-lifecycle.mjs` and `bin/workspaces.mjs` own workspace preparation and reclamation;
+  read [references/workspaces.md](references/workspaces.md) for standalone native setup.

package/skills/engineering/harness-runtime/bin/workspaces.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+import { execFileSync } from 'node:child_process'
+import { prepare, cleanup, recover, inventory } from '../workspace-lifecycle.mjs'
+import { nativeStart, nativeFinish } from '../native-workspace.mjs'
+
+const allowed = {
+  prepare: ['run', 'unit', 'revision', 'apply', 'json'],
+  cleanup: ['run', 'unit', 'revision', 'apply', 'json'],
+  recover: ['repo', 'json'],
+  inventory: ['repo', 'root', 'max-entries', 'max-depth', 'json'],
+  'native-start': ['repo', 'run-id', 'base', 'branch', 'target', 'platform', 'kind', 'native-dir', 'disposable', 'json'],
+  'native-finish': ['run', 'json'],
+}
+
+function options(command, args) {
+  if (!Object.hasOwn(allowed, command)) throw new Error('expected prepare, cleanup, recover, inventory, native-start or native-finish')
+  const out = {}
+  for (let index = 0; index < args.length; index++) {
+    const name = args[index].replace(/^--/, '')
+    if (!args[index].startsWith('--') || !allowed[command].includes(name)) throw new Error(`invalid ${command} option: ${args[index]}`)
+    const key = name.replace(/-([a-z])/g, (_, value) => value.toUpperCase())
+    if (Object.hasOwn(out, key) && name !== 'disposable') throw new Error(`duplicate option: --${name}`)
+    if (name === 'apply' || name === 'json') { out[key] = true; continue }
+    const value = args[++index]
+    if (value === undefined || value.startsWith('--')) throw new Error(`--${name} needs a value`)
+    if (name === 'disposable') (out[key] ??= []).push(value)
+    else out[key] = value
+  }
+  for (const key of ['revision', 'maxEntries', 'maxDepth']) {
+    if (out[key] === undefined) continue
+    if (!/^\d+$/.test(out[key]) || !Number.isSafeInteger(Number(out[key]))) throw new Error(`invalid ${key}`)
+    out[key] = Number(out[key])
+  }
+  return out
+}
+
+try {
+  const [command, ...args] = process.argv.slice(2)
+  const opts = options(command, args)
+  let result
+  if (command === 'native-start') result = nativeStart(opts)
+  else if (command === 'native-finish') result = nativeFinish(opts)
+  else if (command === 'prepare') result = prepare(opts)
+  else if (command === 'cleanup') result = cleanup({ ...opts, runGh: (argv) => execFileSync('gh', argv, { encoding: 'utf8', timeout: 30_000, maxBuffer: 4 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'] }) })
+  else if (command === 'recover') result = recover(opts)
+  else result = inventory(opts)
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`)
+  process.exitCode = result.ok === false ? 1 : 0
+} catch (error) {
+  process.stderr.write(`${error.message}\n`)
+  process.exitCode = 2
+}