mandrel 2.39.0 → 2.41.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/templates/docs/audit-sweep-runbook.md

@@ -0,0 +1,169 @@
+# Audit sweep runbook
+
+> **Template generated by Mandrel.** Copy it into your own docs tree (e.g.
+> `docs/audit-sweep-runbook.md`), then localise every bracketed placeholder:
+> the cadence, the lens list, who reviews the ledger PR, and the label
+> conventions your repository actually uses. The steps themselves are the
+> contract — the values around them are yours.
+>
+> The workflow this runbook drives is
+> [`/audit-to-stories`](../../workflows/audit-to-stories.md); the CLI it calls
+> is [`audit-to-stories.js`](../../scripts/audit-to-stories.js). Run the CLI
+> with `--help` for the authoritative flag list.
+
+## What this runbook is for
+
+A maintenance **sweep** runs the `audit-*` lenses full-scope, folds their
+findings onto the cross-run ledger, and turns what is genuinely new into
+Stories. It is the unattended sibling of an interactive `/audit-to-stories`
+run: no HITL gates, so every judgement call the interactive path asks a human
+has to be settled here instead.
+
+| Setting | Value for this repository |
+| --- | --- |
+| Cadence | _e.g. weekly, Sunday 02:00_ |
+| Lenses in scope | _e.g. security, clean-code, quality, dependencies_ |
+| Severity floor | _`delivery.auditToStories.severityFloor`, default `high`_ |
+| Ledger reviewer | _e.g. @your-handle_ |
+| Story triage owner | _e.g. the on-call maintainer_ |
+
+## Step 1 — Run the lenses full-scope
+
+Run each `audit-*` workflow with **no** `--paths` and no change-set filter, so
+the whole target-set union is audited rather than whatever a recent branch
+happened to touch. Each lens writes its report to
+`temp/audits/audit-<lens>-results.md`.
+
+A sweep scoped to a change set is not a sweep: it re-reports the same recent
+files every cycle and never reaches the code nobody has touched in a year,
+which is exactly where audit findings accumulate.
+
+## Step 2 — Cross-check the severity tally
+
+Every lens report ends its executive summary with a machine-readable line:
+
+```text
+Severity tally: Critical 0 / High 3 / Medium 7 / Low 2
+```
+
+The CLI re-counts the `### Finding` blocks it actually parsed and compares them
+to that declared tally. A mismatch — or a missing tally line — means the report
+is not trustworthy: a finding was malformed, a severity did not resolve onto the
+canonical scale, or the lens truncated its own output.
+
+`--auto` **fails closed** on any such failure. It exits non-zero having opened
+no Issue and written no ledger, and names the offending report in
+`summary.reportFailures[]`. `--allow-missing-tally` is a `--scan` affordance
+only; `--auto` ignores it by design, because an unattended run has no operator
+to read a warning.
+
+**When the sweep goes red here, re-run the lens.** Do not reach for
+`--allow-missing-tally` and do not hand-edit the report to make the numbers
+agree — the tally is the only signal that the parse saw what the lens wrote.
+
+## Step 3 — Dry-run the first cycles
+
+Start every new sweep in report-only mode, and stay there until the tallies
+stop surprising you:
+
+```bash
+node .agents/scripts/audit-to-stories.js --auto --dry-run
+```
+
+`--dry-run` performs zero GitHub writes and skips the ledger write, printing
+only the run summary. Read `totals.create` before you let the sweep file
+anything: a first full-scope run over an un-audited repository can propose more
+Stories than your team can triage in a quarter. Raise `--severity` (or
+`delivery.auditToStories.severityFloor`) until the create count is a batch you
+would actually take on, then go live.
+
+## Step 4 — Go live, and persist the ledger
+
+```bash
+node .agents/scripts/audit-to-stories.js --auto --ledger-commit
+```
+
+The cross-run ledger (`baselines/audit-ledger.json`) is **consumer state, not
+scratch output**. It is what lets the next sweep tell a re-detection from a
+fresh finding, and a deliberately-rejected finding from an unseen one. A
+scheduled job normally runs on an ephemeral checkout, so unless the ledger is
+committed back it dies with the clone and every later sweep starts amnesiac —
+re-proposing findings already filed and re-surfacing findings a human already
+rejected.
+
+`--ledger-commit` closes that loop. After the run summary has printed, and only
+when the ledger actually changed, it:
+
+1. creates `chore/audit-ledger-<YYYY-MM-DD>` from the current HEAD,
+2. commits **only** the ledger file, subject
+   `chore(audit): reconcile audit ledger <date>`,
+3. pushes the branch, and
+4. opens a PR against your base branch.
+
+**Auto-merge is never requested.** The ledger records machine-derived lifecycle
+state, so a human glance before it lands is the point — nominate that reviewer
+in the table above. Review the PR for entries flipping to `accepted-risk` or
+`regressed`; those two are the ledger telling you something about your backlog,
+not about itself.
+
+Any git or `gh` failure in that sequence is fatal and names the step it broke
+on — but it happens _after_ the summary is printed, so a broken remote never
+costs you the sweep's findings.
+
+Without the flag, a run whose ledger changed on a checkout that cannot persist
+it — no `origin` remote, or HEAD parked off the base branch — sets
+`ledger.unpersisted: true` in the summary and warns on stderr naming the file.
+Treat that warning as a red sweep: the findings are fine, but the memory is
+about to be thrown away.
+
+## Step 5 — Enrich before you deliver
+
+`--emit-stories` renders `{ title, body, labels }` payloads from audit findings.
+Those bodies are **audit prose**, not delivery-ready Specs: they describe a
+symptom and a recommendation, not a scoped change with acceptance criteria a
+worker can verify against.
+
+Do not point `/mandrel-deliver` at a freshly-filed audit Story. Route it through
+`/mandrel-plan` first — the planning pass is where the finding becomes a
+capability slice with a `## Spec`, real `acceptance[]` items and runnable
+`verify[]` lines. Planning is deliberately not automated here: deciding what a
+finding is worth, and how far the fix should reach, is the judgement the sweep
+exists to surface rather than to make.
+
+The wiring pass is the exception — it _is_ mechanical and it is **required**.
+After opening the Issues, replay their numbers through `--wire-edges` so the
+cohort's declared ordering exists as `blocked by #N` footers and native
+`blocked_by` relations. An unwired cohort is genuinely unordered, and
+`/mandrel-deliver` will co-dispatch Stories the edges say must follow one
+another.
+
+## Step 6 — Label convention
+
+Audit-sourced Stories carry a closed label set, so they can be filtered out of
+(or into) ordinary planning at a glance:
+
+| Label | Meaning |
+| --- | --- |
+| `type::story` | Every emitted Story — the sweep never opens Epics or tasks. |
+| `agent::ready` | Filed and available for pickup. |
+| `audit::<lens>` | One per lens represented in the group; a cross-audit merge carries several. |
+| `risk::high` | Added when any finding in the group is Critical. |
+
+The lens labels are a **closed taxonomy**: only the canonical `audit::<lens>`
+names are valid, and the filer refuses to emit a label the repository has never
+created. Create them once with `audit-labels-bootstrap.js` before the first live
+sweep — a generated label that does not exist makes every Issue create fail.
+
+Do not invent per-finding labels. If you need another axis (a team, a
+component), add it in triage on top of this set rather than teaching the sweep
+to mint labels no taxonomy defines.
+
+## Failure triage
+
+| Symptom | Cause | Action |
+| --- | --- | --- |
+| Non-zero exit, `summary.reportFailures[]` populated | A lens report's tally is missing or disagrees with the parse | Re-run that lens; never downgrade with `--allow-missing-tally` |
+| `ledger.unpersisted: true` in the summary | No `origin`, or HEAD off the base branch | Re-run with `--ledger-commit`, or commit the ledger by hand |
+| `--ledger-commit failed at step "..."` | git or `gh` failed at the named step | Fix the remote/auth and re-run; the summary above it is still valid |
+| Same findings re-proposed every cycle | The ledger is not being committed | Adopt Step 4 |
+| `totals.create` far larger than the team can absorb | Severity floor too low for a first full-scope run | Raise `--severity` and re-dry-run |