mandrel 2.40.0 → 2.42.0

package/.agents/skills/stack/qa/qa-harness/SKILL.md

@@ -1,13 +1,15 @@
 ---
 name: qa-harness
 description:
-  Conventions for the agent-driven QA harness that drives Gherkin scenarios
-  through a real browser. Use when executing `/qa-run` or instrumenting
-  a live surface — covers navigation-first execution, per-surface console and
-  network capture, design-token visual checks, and the framework-generic
-  heuristic cards for turning signal into findings. The harness procedure lives
-  in `.agents/workflows/qa-run.md`; this skill is the conventions
-  reference it leans on.
+  Conventions for agent-driven QA driving — the one driving-conventions
+  reference behind both `/qa-run` (the known-scenario sweep through a real
+  browser) and `/qa-explore` (agent-led exploratory driving). Use when
+  instrumenting a live surface — covers navigation-first execution,
+  per-surface console and network capture, design-token visual checks, the
+  `F#` finding shape, per-environment resolution, and static driving as the
+  documented interim. The run procedures live in `.agents/workflows/qa-run.md`
+  and `.agents/workflows/qa-explore.md`; this skill is the conventions
+  reference they lean on.
 ---
 
 # Skill: qa-harness
@@ -15,47 +17,110 @@ description:
 ## Policy Capsule
 
 - Driving rules (navigation-first, semantic `Then`, mandatory redaction, sequential-only) live in one prose home — [`qa-run-scenario.md`](../../../../workflows/helpers/qa-run-scenario.md); apply them, do not restate them.
+- Resolve the `qa` contract first and fail loudly when it is absent or malformed; there is no auto-detection fallback and no headless degrade.
+- Resolve the target **environment** before driving (via `resolveQaEnvironment`); each environment keys its own `baseUrl`, `signInSeam`, and `allowWrites`, and its name is recorded on the ledger.
+- Sign in only through the resolved `signInSeam` (`kind: 'url'` dev impersonation or `kind: 'skill'` with a stored `credentialRef`). **Never** type real credentials inline and never fabricate a session.
+- Hold the read-only capture invariant absolutely: no source edits, no product mutations — the only write is appending to the `temp/qa/<sessionId>` ledger.
+- Scrub captured console, network, and headers of tokens, session cookies, and PII before any finding reaches disk or GitHub; findings are posted to GitHub at approval time.
 - Capture console and network per surface; turn each non-allowlisted console error and each failed/error-status request into one structured `F#` finding.
 - Filter console through `qa.consoleAllowlist` via `filterConsoleMessages`; treat the allowlist as a benign-noise filter, never as a security control to silence genuine errors.
 - Spot-check surfaces against `qa.designTokens` when set; flag gross token violations (off-palette colors, off-scale spacing/typography) as findings.
-- Scrub captured console and network of tokens, session cookies, and PII before rendering any finding — findings are posted to GitHub at approval time.
-- Record findings as `QaLedgerItem`s and route them through the shared classify/route/promote core ([`qa-core.md`](../../../../workflows/helpers/qa-core.md)); the harness never files tickets autonomously.
-- Resolve the `qa` contract first and fail loudly when it is absent or malformed; there is no auto-detection fallback and no headless degrade.
-
-Guidance for executing the agent-driven QA harness through a real browser (the
-chrome-devtools MCP surface). The harness **procedure** — argument parsing,
-step ordering, contract resolution sequence — is the SSOT in
-[`.agents/workflows/qa-run.md`](../../../../workflows/qa-run.md);
-this skill shows **how** to apply the instrumentation and inspection
-conventions that procedure depends on. The assertion-tier rules it enforces
-live in [`testing-standards.md`](../../../../rules/testing-standards.md)
+- Choose **static driving** only at Plan time and only where no seam resolves — the documented interim, never a silent fallback — and record the partial coverage.
+- Record findings as `QaLedgerItem`s and route them through the shared classify/route/promote core ([`qa-core.md`](../../../../workflows/helpers/qa-core.md)); the harness never files tickets autonomously, and every phase transition is HITL-gated.
+
+Guidance for driving a live surface through a real browser (the chrome-devtools
+MCP surface). Two workflows lean on this one skill: the **known-scenario
+sweep** ([`qa-run.md`](../../../../workflows/qa-run.md)) walks a resolved
+Gherkin scenario set, and **exploratory driving**
+([`qa-explore.md`](../../../../workflows/qa-explore.md)) walks a named surface
+the agent has no script for. Each **procedure** — argument parsing, phase
+gates, contract resolution sequence — is the SSOT in its own workflow; this
+skill shows **how** to apply the driving and instrumentation conventions both
+depend on. Assertion-tier rules live in
+[`testing-standards.md`](../../../../rules/testing-standards.md)
 (§ Assertion Placement); scenario prose conventions live in
 [`gherkin-authoring`](../gherkin-authoring/SKILL.md); browser-locator
-discipline is shared with [`playwright`](../playwright/SKILL.md). Read this
-skill before instrumenting a live surface; read the workflow for the run order.
+discipline is shared with [`playwright`](../playwright/SKILL.md); browser
+instrumentation lives in
+[`browser-testing-with-devtools`](../../../core/browser-testing-with-devtools/SKILL.md).
+Read this skill before instrumenting a live surface; read the workflow for the
+run order.
 
 ## 1. Driving Rules Live in One Prose Home
 
-The driving rules the harness depends on — **navigation-first / never URL-jump**,
-**semantic `Then` assertion** against the accessibility snapshot, the Gherkin →
-browser-action mapping, the per-`When` write guard, mandatory evidence
-redaction, and the **sequential-only** browser rule — are stated once in
-[`qa-run-scenario.md`](../../../../workflows/helpers/qa-run-scenario.md), the
-single-scenario driver `/qa-run` delegates to. Apply them from there; this skill
-does not restate them. In short: reach every surface the way a real user would
-(start at a root, click affordances, never deep-link a `Given`), assert `Then`
-semantically (roles, accessible names, visible text — never DOM/CSS/XPath
-selectors, HTTP status, response bodies, or DB rows), and record each scenario's
-result (pass / fail / blocked), the surface it ended on, and a one-line symptom
-for any failure. Assertion-tier rules are in
+The driving rules both modes depend on — **navigation-first / never
+URL-jump**, **semantic `Then`** assertion against the accessibility snapshot,
+the Gherkin → browser-action mapping, the per-`When` write guard, mandatory
+evidence redaction, and the **sequential-only** browser rule — are stated once
+in [`qa-run-scenario.md`](../../../../workflows/helpers/qa-run-scenario.md).
+Apply them from there; this skill does not restate them. In short: reach every
+surface the way a real user would (start at a root, click affordances, never
+deep-link a starting state), assert semantically (roles, accessible names,
+visible text — never DOM/CSS/XPath selectors, HTTP status, response bodies, or
+DB rows), and treat broken navigation — a missing affordance, a nav 404, a
+guard redirect loop — as a **finding, not a workaround**. Assertion-tier rules
+are in
 [`testing-standards.md` § Assertion Placement](../../../../rules/testing-standards.md#assertion-placement).
 
-## 2. Per-Surface Console & Network Capture
+## 2. The Read-Only Capture Invariant
+
+Capture is **strictly read-only** in both modes. This invariant is inviolable
+per [`security-baseline.md`](../../../../rules/security-baseline.md) — it is
+not a soft preference.
+
+- **No source edits.** The agent does not modify application code, config, or
+  tests while driving. Driving observes; it never repairs.
+- **No product mutations.** No creating, updating, or deleting product data, no
+  destructive form submissions, no irreversible actions "to see what happens".
+  When a surface's only path forward is a mutating action, record the boundary
+  as the finding and stop — do not cross it.
+- **The only write is the ledger.** The single permitted side effect is
+  appending finding lines under `temp/qa/<sessionId>`.
+- **Scrub before persisting.** Strip tokens, session cookies, `Authorization`
+  headers, and PII from captured console and network evidence via the shared
+  redaction path **before** any finding reaches disk or GitHub. Captured
+  evidence is untrusted until scrubbed.
+- **HITL gates every write outward.** Phase transitions and GitHub writes
+  (ticket creation, promotion) happen only behind an operator confirmation
+  gate; the agent never files or promotes findings autonomously.
+
+## 3. Contract, Environment & Sign-In
 
-Instrument each surface the moment you land on it, before moving on. Capture is
-**per surface** so evidence is attributable to a concrete user-reachable state.
+- **Resolve the `qa` contract first.** Before any browser work, resolve the
+  contract via `resolveQaContract(config)`. When the block is absent,
+  malformed, or missing a required field, the resolver **throws** — relay its
+  verbatim message and STOP. There is no auto-detection fallback.
+- **Resolve the environment.** `resolveQaEnvironment` keys each deployment
+  target to `{ name, baseUrl, signInSeam, allowWrites }`. Where the operator's
+  input does not pin an unambiguous target and the contract declares more than
+  one environment, prompt (or accept `defaultEnvironment`) — never silently
+  pick one. Record the resolved name on the ledger.
+- **Sign in through the seam, never inline.** The two seam kinds:
+  - **`kind: 'url'` (dev impersonation).** Substitute the persona **name** into
+    the seam's URL template and navigate there. The persona name is the sole
+    input; no per-persona auth material is read.
+  - **`kind: 'skill'` (procedural / credential).** Invoke the named consumer
+    sign-in skill, which reads a per-persona **`credentialRef`** — an indirect
+    handle to a stored credential, never an inline secret. Read that skill's
+    `SKILL.md` and follow it.
+
+  The agent MUST NOT type real usernames, passwords, or tokens, and MUST NOT
+  fabricate or forge a session. This is a hard security boundary, not a
+  convenience to work around. Confirm authenticated state with a
+  `take_snapshot` before driving.
+- **No headless fallback.** The chrome-devtools MCP surface is a host-provided
+  runtime dependency. If it is unavailable, degrade with a clear error and stop
+  — never fall back to the retired headless BDD runner.
 
-### 2.1 Console
+## 4. Mode — Known-Scenario Sweep (`/qa-run`)
+
+The sweep drives a resolved scenario set and instruments each surface the
+moment it lands on it, before moving on. Capture is **per surface** so evidence
+is attributable to a concrete user-reachable state. Record each scenario's
+result (pass / fail / blocked), the surface it ended on, and a one-line symptom
+for any failure.
+
+### 4.1 Console
 
 1. Capture with `list_console_messages` on the current surface.
 2. Filter through the contract's `consoleAllowlist` using
@@ -75,13 +140,13 @@ Allowlist matching is case-sensitive substring matching, so patterns stay
 readable in `.agentrc.json` without regex escaping; a blank pattern is ignored
 rather than matching everything.
 
-### 2.2 Network
+### 4.2 Network
 
 Capture with `list_network_requests` on the surface. Failed requests and
 error-status responses (4xx / 5xx) become findings alongside the
 console-derived set, sharing the same `F#` numbering across the surface.
 
-### 2.3 Design-token visual check
+### 4.3 Design-token visual check
 
 When the contract's `designTokens` pointer is set (it defaults to `null`),
 spot-check the rendered surface against the token source. Flag **gross** token
@@ -98,10 +163,10 @@ A gross violation is one a designer would call a regression on sight; subtle
 sub-pixel differences are not harness findings. When `designTokens` is `null`,
 skip this check entirely — do not invent a token source.
 
-## 3. Findings — the `F#` Shape
+### 4.4 The `F#` finding shape
 
-Every captured problem is normalized into the structured `F#` finding shape so
-the sweep can record it onto the shared ledger (each `F#` finding becomes one
+Every captured problem is normalized into the structured `F#` shape so the
+sweep can record it onto the shared ledger (each `F#` finding becomes one
 `QaLedgerItem` — see [`qa-core.md`](../../../../workflows/helpers/qa-core.md))
 and the schema validates:
 
@@ -111,7 +176,7 @@ and the schema validates:
   "classification": "console-error", // console-error | network-error | visual-token | ...
   "surface": "/invoices",           // the user-reachable surface, not a deep link
   "symptom": "...",                 // one-line user-visible / captured symptom
-  "likelyRootCause": null,          // heuristic card output (§4); null until enriched
+  "likelyRootCause": null,          // null unless the cause is evidenced, not guessed
   "disposition": "follow-up",       // blocker | follow-up
   "acceptance": null,               // AC this folds into, when known
   "evidence": {
@@ -124,77 +189,71 @@ and the schema validates:
 - **Determinism is load-bearing.** Re-running the same selector over the same
   captured console with the same allowlist yields the same findings in the same
   order. Do not reorder or renumber findings between sweeps.
-- **Scrub before rendering.** Before any finding's `evidence` is rendered or
-  drafted, strip tokens, session cookies, Authorization headers, and PII from
-  the captured console and network per
-  [`security-baseline.md`](../../../../rules/security-baseline.md). Findings are
-  posted to GitHub at approval time — captured evidence is untrusted until
-  scrubbed.
-
-## 4. Framework-Generic Heuristic Cards
-
-The harness ships **framework-generic** root-cause heuristics — they reason
-about symptoms, not about any one frontend framework. Use a card to populate
-`likelyRootCause` and to set `disposition`. The cards are guidance, not a
-classifier: when a symptom matches none cleanly, leave `likelyRootCause: null`
-and let the operator triage from the symptom.
-
-| Symptom pattern | Likely root cause | Default disposition |
-| --- | --- | --- |
-| `404` / `Not Found` on a navigation or asset request | Dead route, broken link, or missing build artifact | follow-up (blocker if it breaks the scenario path) |
-| `401` / `403` reaching a surface the persona should see | Missing or over-tight authorization check; guard misconfig | blocker |
-| `500` / `502` / `503` on a user action | Server-side fault behind the action | blocker |
-| Uncaught `TypeError` / `ReferenceError` in console | Null/undefined dereference or missing binding in client code | blocker when it breaks the surface, else follow-up |
-| `Failed to fetch` / `NetworkError` / CORS-rejected request | Misconfigured CORS allowlist, wrong origin, or a downed dependency | follow-up |
-| Hydration / mismatch warning escalated to error | Server/client render divergence | follow-up |
-| Off-palette color, off-scale spacing/typography | Design-token drift — hard-coded value bypassing the token | follow-up |
-| Repeated identical console error across many surfaces | A shared component or global bootstrap fault | record once; the shared route/dedup core collapses duplicates at triage |
-
-Heuristics for working the cards:
-
-- **Record once, let dedup collapse.** When the same error fires on many
-  surfaces, record it once rather than filing N copies; the shared
-  classify/route/dedup core ([`qa-core.md`](../../../../workflows/helpers/qa-core.md))
-  collapses duplicates at triage against the fingerprint footer.
 - **Blocker vs. follow-up.** A finding is a **blocker** when it breaks the
   scenario's user-visible outcome or exposes an authorization gap. Everything
-  else (noise that does not break the journey, cosmetic token drift) is a
+  else — noise that does not break the journey, cosmetic token drift — is a
   **follow-up**.
 - **Symptom over diagnosis.** When unsure of the root cause, record the precise
   symptom and leave `likelyRootCause: null`. A wrong guess is worse than an
   honest "unknown" the operator can triage.
-
-## 5. Record onto the Ledger & Triage (Never File Autonomously)
-
-Record each `F#` finding as a `QaLedgerItem` on the shared session ledger under
+- **Record once, let dedup collapse.** When the same error fires on many
+  surfaces, record it once rather than filing N copies; the shared
+  classify/route/dedup core collapses duplicates at triage against the
+  fingerprint footer.
+
+## 5. Mode — Exploratory Driving (`/qa-explore`)
+
+Exploratory driving walks a named surface with no scenario script, capturing
+what it observes. It is the agent-led half of exploratory QA; its human-led
+sibling is `/qa-assist` (the human drives, the agent scribes). Everything in
+§§ 1–3 applies unchanged; the deltas are the method choice and the per-surface
+boundary.
+
+- **Pick the driving method explicitly at Plan time** — drive (default) vs.
+  static — and record it in the ledger. Do not switch methods mid-surface
+  without a new Plan note.
+- **Drive is the default.** When the resolved environment carries a
+  `signInSeam`, authenticated surfaces — including deployed hosts — are
+  **driven** through that seam, not statically deferred.
+- **Static driving is the documented interim**, chosen **only where no seam
+  resolves** for the target environment. It walks the surface from source,
+  route definitions, and rendered markup rather than a running browser:
+  - **Never a silent fallback.** Static is a deliberate Plan-phase decision
+    recorded with its reason ("environment: preview, method: static, reason: no
+    seam resolves"), not something the agent slips into when the browser MCP
+    hiccups.
+  - **Interim, not equivalent.** Static driving cannot exercise real
+    authorization, routing guards, or runtime console/network signal. Treat its
+    coverage as partial and say so in the ledger; a static pass does not close
+    the same coverage a driven pass would.
+  - **Same read-only invariant** (§ 2) applies identically.
+  - **Promote to driving when a seam lands.** Re-run the surface driven rather
+    than leaving it permanently static.
+- **A surface that could not be driven is itself a signal.** Where the
+  environment resolves no seam, drive the unauthenticated surface or fall back
+  to static and record the gap — never a silent skip.
+- **Observe, do not fabricate.** Never script the runtime to manufacture an
+  outcome the exploration is meant to discover.
+
+## 6. Record onto the Ledger & Triage (Never File Autonomously)
+
+Record each finding as a `QaLedgerItem` on the shared session ledger under
 `temp/qa/`, then route the ledger through the shared classify → route →
 disposition → promote core — both stated once in
 [`qa-core.md`](../../../../workflows/helpers/qa-core.md). The harness **MUST
-NOT** create tickets autonomously: findings are promoted through `/mandrel-plan` only
-after the operator confirms each disposition at the HITL write gate. That gate
-is the safety boundary against spurious filing.
-
-## 6. Sign-In & Contract Discipline
-
-- **Resolve the `qa` contract first.** Before any browser work, resolve the
-  contract via `resolveQaContract(config)`. When the block is absent,
-  malformed, or missing a required field, the resolver **throws** — relay its
-  verbatim message and STOP. There is no auto-detection fallback.
-- **Dev seam only.** Sign in once per persona via the contract's `signInSeam`
-  (`kind: 'url'` dev seam or `kind: 'skill'`). **Never** enter real
-  credentials. Confirm authenticated state with a `take_snapshot` before
-  driving any scenario.
-- **No headless fallback.** The chrome-devtools MCP surface is a host-provided
-  runtime dependency. If it is unavailable, degrade with a clear error and stop
-  — never fall back to the retired headless BDD runner.
+NOT** create tickets autonomously: findings are promoted through
+`/mandrel-plan` only after the operator confirms each disposition at the HITL
+write gate. That gate is the safety boundary against spurious filing.
 
 ## 7. Cross-References
 
-- Run procedure (SSOT): [`qa-run.md`](../../../../workflows/qa-run.md).
+- Sweep procedure (SSOT): [`qa-run.md`](../../../../workflows/qa-run.md).
+- Exploration procedure (SSOT): [`qa-explore.md`](../../../../workflows/qa-explore.md).
 - Driving rules (one prose home): [`qa-run-scenario.md`](../../../../workflows/helpers/qa-run-scenario.md).
 - Shared QA core (contract/session/redaction/ledger/triage/HITL): [`qa-core.md`](../../../../workflows/helpers/qa-core.md).
 - Console filter module: [`console-allowlist.js`](../../../../scripts/lib/qa/console-allowlist.js).
 - Assertion-tier rules: [`testing-standards.md`](../../../../rules/testing-standards.md).
 - Scenario prose: [`gherkin-authoring`](../gherkin-authoring/SKILL.md).
 - Browser-locator discipline: [`playwright`](../playwright/SKILL.md).
-- Evidence scrubbing: [`security-baseline.md`](../../../../rules/security-baseline.md).
+- Browser instrumentation: [`browser-testing-with-devtools`](../../../core/browser-testing-with-devtools/SKILL.md).
+- Evidence scrubbing / read-only boundary: [`security-baseline.md`](../../../../rules/security-baseline.md).

package/.agents/workflows/git-cleanup.md

@@ -17,8 +17,9 @@ Reach for it when the automated hygiene left an unusual state behind.
 > **When to run**: after a session that landed several PRs, or before starting a
 > new Story, to put the local checkout into a known tidy state.
 >
-> **Persona**: `devops-engineer` · **Skills**:
-> `core/git-workflow-and-versioning`
+> **Persona**: `devops-engineer` — git guidance comes from the always-on
+> [`rules/git-conventions.md`](../rules/git-conventions.md), which needs no
+> skill citation.
 
 The enumeration + reap logic lives in
 [`git-cleanup.js`](../scripts/git-cleanup.js) — it computes the candidate list,

package/.agents/workflows/git-deliver.md

@@ -19,8 +19,9 @@ explicitly; the interactive choice prompt fires **only** when the detected
 state is genuinely ambiguous, so the common path stays non-interactive and
 scriptable.
 
-> **Persona**: `devops-engineer` · **Skills**:
-> `core/git-workflow-and-versioning`
+> **Persona**: `devops-engineer` — git guidance comes from the always-on
+> [`rules/git-conventions.md`](../rules/git-conventions.md), which needs no
+> skill citation.
 
 ---
 

package/.agents/workflows/helpers/acceptance-self-eval.md

@@ -113,6 +113,18 @@ mid-delivery, and evaluates the actual work product.
      optional advisory pre-flight — a criterion cannot be scored `met` without
      the supporting `verify[]` evidence where a `verify[]` command is relevant
      to it.
+   - **Reuses the credited full-suite run instead of re-paying for it.**
+     Before spawning a `verify[]` entry, classify it with `resolveVerifyCredit`
+     from
+     [`verify-credit.js`](../../scripts/lib/orchestration/verify-credit.js): an
+     entry that is itself a full-suite command (`npm test`, `pnpm run test`,
+     a bare `node --test`) is consulted against the **same stamp close reads**
+     and, when that stamp is fresh, recorded as `pass` with a `detail` naming
+     the credit — **never respawned**. A stale or absent stamp reports
+     `spawn: true` and the command runs for real, so the credit can never
+     manufacture a pass. The gate warns on any such entry: the intended shape
+     is scoped `verify[]` entries **plus** the one credited run
+     ([`deliver-digest.md`](deliver-digest.md) § 5).
    - **Shares `lint` / `typecheck` evidence with close.** When a
      `verify[]` command is **byte-identical** to a close-validation gate — in
      practice only the cheap, command-identical `lint` and `typecheck` gates

package/.agents/workflows/helpers/deliver-digest.md

@@ -2,9 +2,9 @@
 description: >-
   The deliver path's one bundled framework read. Carries what
   every Story delivery always needs — dispatch decision, engine invariants,
-  the change-set/ceremony incantation, the acceptance-eval gate, and the
-  terminal envelope contract — so the engine reads one file instead of
-  re-reading the helper/schema set each session.
+  the change-set/ceremony incantation, the acceptance-eval gate, the credited
+  full-suite run, and the terminal envelope contract — so the engine reads one
+  file instead of re-reading the helper/schema set each session.
 ---
 
 # Deliver digest (read once per session)
@@ -27,10 +27,8 @@ rule produces it:
    whatever its shape — sub-agent isolation is load-bearing only against a
    *concurrent* sibling racing the same checkout, and a one-Story run has none.
 2. **Every other run is `subagent`.** A multi-Story run dispatches every Story
-   as a sub-agent however trivial its shape — a lite body does not conjure a
-   second session for a sibling, and the wave tick may hand you the whole set
-   on one beat. Shape still sets ceremony; the `route::lite` label is a
-   human-visible hint, never the control signal.
+   as a sub-agent however trivial its shape. Shape still sets ceremony; the
+   `route::lite` label is a human-visible hint, never the control signal.
 
 `inline` removes model-side fan-out only — no `story-worker` boot, no fresh
 acceptance-critic spawn. **`subagent` and `inline` run the same engine**: same
@@ -112,7 +110,30 @@ an unmerged cluster verdict scores a fraction of the criteria and still reports
 not close**: post a `friction` comment and flip `agent::blocked`.
 Per-round mechanics: [`acceptance-self-eval.md`](acceptance-self-eval.md).
 
-## 5. Terminal envelope — the return contract
+## 5. The one creditable full-suite run
+
+**After the self-eval loop's last fix commit, immediately before the push** —
+the credit is keyed on the tree, so any later commit invalidates it. Redraft
+rounds run scoped tests; only this final run needs credit, and a bare
+`npm test` / `pnpm run test` deposits **none**, so close re-runs the identical
+suite. Shape it by the predicate `close-validation/gates.js` uses for its test
+gate:
+
+```bash
+# CRAP gate on (default) + a `test:coverage` script — writes the stamp the
+# close `coverage-capture` gate reads:
+node <main-repo>/.agents/scripts/coverage-capture.js --cwd <workCwd>
+# otherwise — the record the close `test` gate reads. <workCwd> ABSOLUTE,
+# runner exactly `npm test`: both sides hash {cmd, args, cwd}.
+node <main-repo>/.agents/scripts/evidence-gate.js --standalone \
+  --scope-id <storyId> --gate test --worktree <workCwd> -- npm test
+```
+
+`verify[]` is scoped entries **plus** this one run: an entry that is itself a
+full-suite command is reported credited against the same stamp, never
+respawned.
+
+## 6. Terminal envelope — the return contract
 
 `single-story-close.js` emits exactly one envelope on stdout between
 `--- STORY DELIVER TERMINAL ---` markers, schema-validated against
@@ -129,7 +150,7 @@ Relay it verbatim; never hand-compose one, never substitute prose.
 
 Required fields: `kind` (`story-deliver-terminal`), `storyId`, `status`,
 `phase`, `elapsedSeconds`, `nextCommand`. `phase` is one of `init`,
-`wrong-tree-guard`, `close-validation`, `base-sync`, `push`, `pull-request`,
+`wrong-tree-guard`, `base-sync`, `close-validation`, `push`, `pull-request`,
 `code-review`, `auto-merge`, `confirm-merge`, `post-land`, `done`. `gates`
 reports every gate as `passed` / `failed` / `skipped` — a skipped gate is
 reported, never omitted, so a missing gate is never read as a passing one.
@@ -139,7 +160,7 @@ reported, never omitted, so a missing gate is never read as a passing one.
 success; a failed gate replays its tail inline. `AGENT_LOG_LEVEL=verbose`
 restores live streaming.
 
-## 6. When to leave this file
+## 7. When to leave this file
 
 - Unclear state / a re-run refusal → `deliver-recover.js --story <id>` (read-only).
 - Lease, sweep, worktree-scope detail → [`deliver-story-reference.md`](deliver-story-reference.md).

package/.agents/workflows/helpers/deliver-story-reference.md

@@ -233,17 +233,19 @@ runs maker-blind at Story-scope review inside the close subprocess. The
 dispatch step produces `checklistPath` from the Story's predicted footprint
 before it spawns the worker — see [`/mandrel-deliver`](../mandrel-deliver.md).
 
-**Pre-eval full-suite discipline (spine step 1.3).** Repo-invariant guards —
+**Full-suite discipline (spine Step 2.5).** Repo-invariant guards —
 drift-guard and schema tests living outside the Story's scoped greps — are
 the failure class that actually bounces deliveries: close-validation
 discovers them only after the whole close pipeline has run, at several times
-the cost of one pre-eval full-suite run.
+the cost of one full-suite run in the worktree.
 
-**Run it so close can credit it.** Close skips a gate that already passed at
-the current HEAD, but a bare `npm test` deposits no such record — the suite
-then runs twice per delivery, once here and once in the close gate chain.
-Pick the invocation by the same predicate `close-validation/gates.js` uses to
-choose its test gate:
+**Run it once, last, so close can credit it.** The run belongs **after** the
+self-eval loop's last fix commit and immediately **before** the hand-off push,
+so its stamp describes the tree that is pushed; redraft rounds run scoped
+tests. Close skips a gate that already passed at the current HEAD, but a bare
+`npm test` deposits no such record — the suite then runs twice per delivery,
+once here and once in the close gate chain. Pick the invocation by the same
+predicate `close-validation/gates.js` uses to choose its test gate:
 
 ```bash
 # CRAP gate enabled (default) + a `test:coverage` script — writes the stamp
@@ -259,7 +261,15 @@ node <main-repo>/.agents/scripts/evidence-gate.js --standalone \
 The credit expires the moment it stops describing the tree: evidence is keyed
 on HEAD, the capture stamp on a content digest of `crap.targetDirs`. A
 self-eval fix — or any commit — invalidates it and close re-runs the suite for
-real, so this never trades away the gate.
+real, so this never trades away the gate. That keying is exactly why the run
+comes last.
+
+**`verify[]` reuses the same stamp.** A `verify[]` entry that is itself a
+full-suite command is reported **credited** against that stamp rather than
+respawned (`resolveVerifyCredit` in
+[`verify-credit.js`](../../scripts/lib/orchestration/verify-credit.js)), and the
+self-eval gate warns when it sees one: the intended shape is scoped `verify[]`
+entries **plus** the single credited run.
 
 **Conflict with `main` mid-implementation** → resolve as you would any branch
 rebase. There is no `epic/<id>` intermediate, so the rebase base is `main`
@@ -500,22 +510,16 @@ judgment that help text cannot carry.
 
 The `single-story-close.js` script, in order:
 
-1. Runs the close-validation gates against `baseBranch` as the baseline.
-   On any gate failure it throws — the operator fixes and re-runs close.
-   **Gate output is captured, not streamed.** Every gate line
-   goes to `temp/orchestration/close-gates-<storyId>.log`; a clean run reports
-   one digest line naming that artifact, and a **failed** gate replays its
-   captured tail inline so the evidence is in front of you without opening a
-   file. Read the artifact when you need the full text — or re-run under
-   `AGENT_LOG_LEVEL=verbose` for live streaming.
-   1a. **Syncs the Story branch from `origin/<baseBranch>`** before push.
-   Runs `git fetch origin <baseBranch>` followed by
-   `git merge --no-edit origin/<baseBranch>` inside the worktree. This
+1. **Syncs the Story branch from `origin/<baseBranch>`** — before the gates,
+   not after them. Runs `git fetch origin <baseBranch>` followed
+   by `git merge --no-edit origin/<baseBranch>` inside the worktree. This
    defends against the parallel-`/deliver-story` race: when
    multiple sessions run in parallel, the Story that auto-merges first
    bumps `baseBranch`, and without this sync the lagging Stories open
    PRs that are "behind base" and stall against branch-protection's
-   `up-to-date branch` rule. Outcomes:
+   `up-to-date branch` rule. Running it first also means a conflict costs
+   no gate run at all, and — the load-bearing half — the tree the gates
+   validate is the tree the push sends. Outcomes:
    - **No-op / fast-forward / clean merge-commit** → close proceeds to
      push.
    - **Merge conflict** → the merge is aborted, a `friction` structured
@@ -533,12 +537,26 @@ The `single-story-close.js` script, in order:
    closes the PR-open-time race but a residual race remains between PR
    open and auto-merge fire.
 
-2. Pushes `story-<id>` to `origin`.
-3. Probes for an existing open PR with `head = story-<id>`. If none
+2. Runs the close-validation gates against `baseBranch` as the baseline.
+   On any gate failure it throws — the operator fixes and re-runs close.
+   The chain fails cheapest-first: `typecheck`, `lint`, `format` and the
+   coverage-independent half of the baselines gate
+   (`check-baselines-independent`) run in parallel, and only once they are
+   green does the serial walk pay for `coverage-capture` and the
+   coverage-consuming half (`check-baselines-coverage`).
+   **Gate output is captured, not streamed.** Every gate line
+   goes to `temp/orchestration/close-gates-<storyId>.log`; a clean run reports
+   one digest line naming that artifact, and a **failed** gate replays its
+   captured tail inline so the evidence is in front of you without opening a
+   file. Read the artifact when you need the full text — or re-run under
+   `AGENT_LOG_LEVEL=verbose` for live streaming.
+
+3. Pushes `story-<id>` to `origin`.
+4. Probes for an existing open PR with `head = story-<id>`. If none
    exists, opens one via `gh pr create --base <baseBranch>`. The PR
    body carries `Closes #<storyId>` so the GitHub merge auto-closes the
    issue.
-   3a. **Enables GitHub native auto-merge by default** via
+   4a. **Enables GitHub native auto-merge by default** via
    `gh pr merge <prNumber> --auto --squash --delete-branch`. Once CI's
    required checks turn green, GitHub squash-merges the PR and deletes
    the source branch — the operator does not need to babysit the merge
@@ -546,7 +564,7 @@ The `single-story-close.js` script, in order:
    non-fatal: the operator retains the manual merge surface in the
    GitHub UI. Pass `--no-auto-merge` to opt out when the PR needs a
    pre-merge eyeball.
-4. Flips the Story to **`agent::closing`** (NOT `agent::done`) and leaves
+5. Flips the Story to **`agent::closing`** (NOT `agent::done`) and leaves
    the GitHub issue **OPEN**. Auto-merge completes
    asynchronously _after_ this script exits, so closing the issue here
    would strand a CLOSED issue with no merged work if the PR later failed
@@ -557,9 +575,9 @@ The `single-story-close.js` script, in order:
    `--no-wait-merge` run, or the in-close confirm phase on the
    close-and-land default. (Step 5.5 is the Status-column resync.) A Story
    only reaches `agent::done` once its PR to `main` is confirmed merged.
-5. Reaps the worktree when `delivery.worktreeIsolation.reapOnSuccess`
+6. Reaps the worktree when `delivery.worktreeIsolation.reapOnSuccess`
    is enabled.
-6. **Releases the Story lease.** Clears the Story assignment
+7. **Releases the Story lease.** Clears the Story assignment
    that init claimed so the next `/deliver-story` run sees an
    unclaimed ticket. The release is a no-op when the operator no longer
    holds the claim (a later run took over via reclaim/steal), so a late
@@ -572,13 +590,15 @@ The `single-story-close.js` script, in order:
    de-assigning the ticket. The close result carries
    `leaseReleased: <boolean>`.
 
-`--skip-validation` bypasses Step 1 (gates). Use only when re-running
+`--skip-validation` bypasses the gate step. Use only when re-running
 close after a fixed gate failure that's already known to pass.
 
-`--skip-sync` bypasses Step 1a (base-sync). Use only when re-running
-close after a hand-resolved sync, or in tests.
+`--skip-sync` bypasses the base-sync step. Use only when re-running
+close after a hand-resolved sync, or in tests. The two flags are
+independent: either, both or neither may be set, and each elides exactly
+its own phase.
 
-`--no-auto-merge` disables Step 3a. Use when the PR materially changes
+`--no-auto-merge` disables the auto-merge arm (step 4a). Use when the PR materially changes
 behaviour and warrants pre-merge review.
 
 ---