mandrel 2.7.0 → 2.9.0

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

@@ -194,6 +194,61 @@ behaviour and warrants pre-merge review.
 
 ## Step 4 — CI watch + fix recovery
 
+Enter this step **only** when Step 3 returned `blocked` with
+`blockClass: "checks-failed"` (a required check went red), or when a
+`--no-wait-merge` run left the PR for you to shepherd. When a required check is
+red, the agent owns the green-CI outcome, not just the push: local
+close-validation gates pass on the dev host's environment; CI runs on a
+different OS and concurrency, and coverage rounding, platform-conditional
+branches, and timing-sensitive tests routinely drift between the two.
+
+Fix the failure and push a new commit on `story-<storyId>` — auto-merge stays
+armed across retries, so you do not re-arm — then resume the land with the
+envelope's `nextCommand`.
+
+To watch the checks on the red path, drive `pr-watch-with-update.js` — the
+**single CI-watch mechanism** (Story #4358). It polls the required checks to a
+terminal state and auto-recovers from `mergeStateStatus: BEHIND`; do **not**
+fall back to a bare `gh pr checks` watch invocation:
+
+```bash
+node <agentRoot>/scripts/pr-watch-with-update.js --pr <prNumber> --story <storyId>
+```
+
+`--story` is what keys the red-path CI digest
+(`temp/story-<id>-ci-digest.{json,md}` — failing check name, run id, and a
+`gh run view --log-failed` tail). Omit it and a red check writes no digest.
+Poll cadence and caps come from `delivery.ci.watch.*` (`pollIntervalMs`,
+`maxPolls`, `maxResumes`); pass `--poll-interval-ms`, `--max-polls`, or
+`--max-resumes` to override for one run.
+
+When the watch exits, branch on the exit code:
+
+- **Exit 0 (all checks ✓)** — auto-merge will fire (or has already). The Story
+  is still at `agent::closing` with its issue OPEN. **Proceed to merge
+  confirmation (§ Step 5) within the same turn** — green CI is the *start* of
+  the merge-confirm sequence, not a terminal state.
+- **Exit 1 (a check genuinely failed)** — diagnose, fix, and push a new commit
+  on `story-<storyId>`, then re-watch. Auto-merge stays enabled across retries;
+  no need to re-arm it. The Story stays at `agent::closing` throughout, so a
+  failed/abandoned PR never strands a CLOSED issue. If the same failure class
+  recurs, hand convergence off to a self-paced host loop (`/loop`) that re-runs
+  the failing check and applies the smallest fix until it exits green.
+- **Exit 2 (still-running — slow CI, not red)** — the poll cap fired with checks
+  still pending and the watcher exhausted its resume budget with nothing red.
+  This is **never** a failure. Hand the wait off to the host's interval loop
+  rather than ending your turn: `/loop 5m` polling `gh pr checks` until the
+  checks settle.
+
+**Triage authority.** How to classify and remediate a red (or repeatedly slow)
+check — the root-cause-only decision tree for infra/transient and flaky failures
+(reproduce → check `main` → bisect env vs code → fix in-scope or file a
+`meta::framework-gap` issue), the never-rerun / never-quarantine prohibitions,
+and the escalation criteria (three-strikes, the 30-minute wall-clock timebox,
+and the clearly-environmental fast path) — is defined once in
+[`.agents/rules/ci-remediation.md`](../../rules/ci-remediation.md). Read it
+before remediating a red check.
+
 ### The auto-merge wait is an internally-blocking step
 
 This is the single most important contract of this workflow, and the seam
@@ -281,6 +336,20 @@ the watch exits clean.
 
 ## Step 5 — Merge confirmation detail
 
+> On the default path Step 3 already did this. Run it only to resume a
+> `pending` envelope, to finish a `--no-wait-merge` run, or to rescue a
+> merged-but-mislabelled Story.
+
+```bash
+node .agents/scripts/single-story-confirm-merge.js --story <storyId> --cwd <main-repo>
+```
+
+This is the **same** shared land path Step 3 reaches: it flips
+`agent::closing → agent::done` on a confirmed merge (closing the issue) and runs
+the **same** post-land tail — so the two surfaces cannot diverge. It is
+idempotent, emits the same terminal envelope, and is safe to re-run while the PR
+is still open (returns `pending`).
+
 `single-story-confirm-merge.js` re-reads the live PR state (`gh pr view
 --json state,mergedAt`, probing `gh pr list --head story-<id> --state all`
 when `--pr` is omitted) and:
@@ -302,6 +371,18 @@ The issue closes exactly when the work has merged, never at PR-open
 
 ## Step 5.5 — Re-assert Status column detail
 
+> **The land tail already ran this** (Story #4543) — it is `tail.statusResync`
+> in the terminal envelope. Run it by hand only when that step reported
+> `false`, or after a manual merge on a `--no-wait-merge` run.
+
+```bash
+node .agents/scripts/resync-status-column.js --story <storyId>
+```
+
+The helper re-fires the `ColumnSync` mutation and **polls for ~15 s** to win the
+race against the bot's late write (Story #2876). It is idempotent and
+no-op-safe (`no-project` / `not-on-project` exit 0).
+
 The GitHub Projects v2 built-in workflows `Pull request merged` and
 `Pull request linked to issue` are enabled by default on most boards
 and fire ~minutes *after* auto-merge lands. They overwrite the Status
@@ -348,6 +429,30 @@ defense-in-depth against re-enabled or future workflows.
 
 ## Step 6 — Local branch cleanup detail
 
+> **The land tail already ran this** (Story #4543) — it is `tail.refCleanup` and
+> `tail.baseFastForward` in the terminal envelope, done in-process against the
+> same planners this command drives. Run it by hand only when either step
+> reported `false` (a dirty shared checkout is the common, benign cause), or
+> after a manual merge on a `--no-wait-merge` run. To prune the story ref **and**
+> fast-forward local `main` (or `project.baseBranch`):
+
+```bash
+node .agents/scripts/git-cleanup.js \
+  --execute \
+  --remote \
+  --yes \
+  --fast-forward-main \
+  --branches \
+  --include "story-<storyId>"
+```
+
+`--fast-forward-main` brings local `main` current (the next init seeds from it),
+`--branches` + `--include` reap only this Story's ref, and
+`--execute --remote --yes` run the deletes non-interactively. The sweep is
+idempotent and safe to run before `MERGED` confirms. Skip it only when the
+operator opted out via `--no-auto-merge` AND has not yet merged the PR — run the
+cleanup after the manual merge lands.
+
 GitHub deletes the **remote** branch on auto-merge (via the
 `--delete-branch` flag `single-story-close.js` passes to `gh pr merge`).
 The **local** `story-<storyId>` ref, however, lingers in the main
@@ -400,16 +505,10 @@ follows is the *judgement* around it, which a schema cannot express.
 
 ### `pending` is a real status — and it is not a park
 
-Earlier revisions asserted "the auto-merge wait does not produce a fourth
-status", on the reasoning that the wait is internally blocking so a run either
-merges or blocks. That was true only while the wait was unbounded — and it was
-never actually unbounded, because the host kills a tool invocation at ~10
-minutes. So a close-and-land whose CI outlived that ceiling took **no**
-terminal path at all: no event, no label, the Story parked at
-`agent::closing`. The status the model refused to name was the one that kept
-happening.
-
-`pending` names it, with its own exit code (3):
+`pending` is a real terminal status with its own exit code (3) — the honest
+name for a close-and-land whose CI outlived the host's ~10-minute
+tool-invocation ceiling, which would otherwise park the Story at
+`agent::closing` with no event and no label:
 
 - It is **resumable**: no label was mutated, no `merge.unlanded` was emitted,
   and `nextCommand` names the one command that continues it. The cumulative
@@ -419,13 +518,11 @@ happening.
   is the Story #1553 / PR #1554 failure mode wearing a schema. Return it only
   when the bound genuinely expired, or a human owns the merge.
 
-The no-park rule is therefore unchanged in substance: a turn that ends with
-prose ("I'll wait for the watch task…", "the next event will be its
-completion notification…") and an unconfirmed merge is a **contract
-violation** — the parent cannot distinguish "still working" from "done but
-silent". What changed is that there is now an honest, machine-readable way to
-say "not finished, here is exactly how to continue" instead of a choice
-between lying and blocking forever.
+The no-park rule holds: a turn that ends with prose ("I'll wait for the watch
+task…", "the next event will be its completion notification…") and an
+unconfirmed merge is a **contract violation** — the parent cannot distinguish
+"still working" from "done but silent". `pending` is the honest,
+machine-readable alternative: "not finished, here is exactly how to continue."
 
 ### Exit-code compatibility note (`--no-wait-merge`)
 

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

@@ -39,6 +39,16 @@ large — uses the same machinery:
 If the Story still carries an `Epic: #N` reference, **stop** — that is a v1
 Epic-attached ticket; re-plan as a v2 Story or finish it on a pre-v2 checkout.
 
+> **Ceremony-lite Stories still land through this engine unchanged (Story
+> #4683).** A Story that `/plan` routed onto the ceremony-lite path (its
+> `complexityRoute.route === "lite"`) collapses only the *advisory* plan/deliver
+> ceremony — the fresh-critic / Tech-Spec authoring a one-artifact scope does
+> not earn. It does **not** get a cheaper landing: the close-validation gates
+> (lint / test / format / coverage / CRAP / maintainability), the PR to `main`,
+> and the `rules/security-baseline.md` MUSTs all run here exactly as for a
+> full-ceremony Story. The lite route's `preserves` field is the machine-readable
+> record of those non-negotiables; there is no lite-specific gate bypass.
+
 ## Prerequisites
 
 1. A GitHub Issue with the `type::story` label and **no** `Epic: #N`
@@ -131,32 +141,9 @@ Operator/agent responsibilities while in the worktree:
    `checklistPath` (footprint-matched **local**-lens authoring checklists),
    read it before you write and self-check as you author. When absent,
    lens-aware coverage still runs maker-blind at Story-scope review inside
-   the close subprocess.
-
-   **Producing `checklistPath` at dispatch (Story #4627).** The dispatch that
-   spawns this worker threads `checklistPath` the same way it threads
-   `docsDigestPath`. Before the spawn, compute the payload from the Story's
-   predicted footprint (its `changes[]` / `references[]` path entries) with
-   `buildDispatchChecklist` and write it to the run temp dir:
-
-   ```bash
-   node --input-type=module -e '
-     import { buildDispatchChecklist } from "<main-repo>/.agents/scripts/lib/audit-suite/index.js";
-     import { parse } from "<main-repo>/.agents/scripts/lib/story-body/story-body.js";
-     // storyBody is the fetched Story issue body.
-     const { changes, references } = parse(process.env.STORY_BODY);
-     const { checklistPath } = buildDispatchChecklist({
-       storyId: <storyId>, changes, references, runTempDir: "temp/run-<id>",
-     });
-     console.log(checklistPath ?? "");
-   '
-   ```
-
-   A non-empty `checklistPath` is threaded into this worker's prompt; an empty
-   footprint match prints nothing and the worker runs with no write-time
-   checklist (the maker-blind close-scope pass still covers it). The builder is
-   a pure function of the footprint and the on-disk checklists —
-   `buildDispatchChecklist` (`lib/audit-suite/dispatch-checklist.js`).
+   the close subprocess. The dispatch step produces `checklistPath` from the
+   Story's predicted footprint before it spawns this worker (Story #4627) — see
+   [`/deliver`](../deliver.md).
 2. Implement the changes. When the body has a `## Slicing` / Delivery
    Slicing table, walk rows as **intra-session checkpoints** (commit +
    flip each row when done) — never as sibling tickets.
@@ -364,173 +351,36 @@ Flags:
 
 ---
 
-## Step 4 — CI fix loop (**recovery-only**)
+## Steps 4–6 — Recovery router (**recovery-only**)
 
 > **Steps 4, 5, 5.5, and 6 are recovery paths, not routine choreography
 > (Story #4543).** On the default path Step 3 already polled the PR to a
 > confirmed merge, flipped `agent::done`, and ran the whole post-land tail —
 > follow-up capture, status resync, ref cleanup, base fast-forward — in one
 > process. A `landed` envelope means all of it ran; go straight to Step 7.
->
-> Enter this step **only** when Step 3 returned `blocked` with
-> `blockClass: "checks-failed"` (a required check went red), or when a
-> `--no-wait-merge` run left the PR for you to shepherd.
-
-When a required check is red, the agent owns the green-CI outcome, not just
-the push. Local close-validation gates pass on the dev host's environment;
-CI runs on a different OS and concurrency, and coverage rounding,
-platform-conditional branches, and timing-sensitive tests routinely drift
-between the two.
-
-Fix the failure and push a new commit on `story-<storyId>` — auto-merge stays
-armed across retries, so you do not re-arm — then resume the land with the
-envelope's `nextCommand`.
-
-> **A watch is an internally-blocking step, not a reason to end your turn.**
-> `pr-watch-with-update.js` blocks the current turn until CI resolves — that
-> IS how you wait. Ending the turn with prose and an unconfirmed merge is a
-> contract violation (the Story #1553 / PR #1554 failure mode). See
-> [`deliver-story-reference.md` § The auto-merge wait is an internally-blocking step](deliver-story-reference.md#the-auto-merge-wait-is-an-internally-blocking-step).
-
-To watch the checks on the red path, drive
-`pr-watch-with-update.js` — the **single CI-watch mechanism**
-(Story #4358). It polls the required checks to a
-terminal state and auto-recovers from `mergeStateStatus: BEHIND`; do
-**not** fall back to a bare `gh pr checks` watch invocation:
-
-```bash
-node <agentRoot>/scripts/pr-watch-with-update.js --pr <prNumber> --story <storyId>
-```
-
-`--story` is what keys the red-path CI digest
-(`temp/story-<id>-ci-digest.{json,md}` — failing check name, run id, and a
-`gh run view --log-failed` tail). Omit it and a red check writes no digest.
-
-Poll cadence and caps come from `delivery.ci.watch.*`
-(`pollIntervalMs`, `maxPolls`, `maxResumes`); pass `--poll-interval-ms`,
-`--max-polls`, or `--max-resumes` to override for one run.
-
-When the watch exits, branch on the exit code:
-
-- **Exit 0 (all checks ✓)** — auto-merge will fire (or has already). The
-  Story is still at `agent::closing` with its issue OPEN. **Proceed to
-  Step 5 within the same turn** — green CI is the *start* of the
-  merge-confirm sequence, not a terminal state.
-- **Exit 1 (a check genuinely failed)** — diagnose, fix, and push a new
-  commit on `story-<storyId>`, then re-watch. Auto-merge stays enabled
-  across retries; no need to re-arm it. The Story stays at
-  `agent::closing` throughout, so a failed/abandoned PR never strands a
-  CLOSED issue. If the same failure class recurs, hand convergence off to a
-  self-paced host loop (`/loop`) that re-runs the failing check and applies
-  the smallest fix until it exits green.
-- **Exit 2 (still-running — slow CI, not red)** — the poll cap fired with
-  checks still pending and the watcher exhausted its resume budget with
-  nothing red. This is **never** a failure. Hand the wait off to the
-  host's interval loop rather than ending your turn: `/loop 5m` polling
-  `gh pr checks` until the checks settle.
-
-> **Triage authority.** How to classify and remediate a red (or repeatedly
-> slow) check — the root-cause-only decision tree for infra/transient and
-> flaky failures (reproduce → check `main` → bisect env vs code → fix in-scope
-> or file a `meta::framework-gap` issue), the never-rerun / never-quarantine
-> prohibitions, and the escalation criteria (three-strikes, the 30-minute
-> wall-clock timebox, and the clearly-environmental fast path) — is defined
-> once in [`.agents/rules/ci-remediation.md`](../../rules/ci-remediation.md).
-> Read it before remediating a red check above.
->
-> **CI recovery procedures.** For resurrecting the worktree after
-> `reapOnSuccess`, pulling the failing job log, fixing coverage/CRAP
-> baselines without re-running close-validation, and the when-to-stop
-> Anti-Thrashing rules, see
-> [`deliver-story-reference.md` § Step 4 — CI watch + fix recovery](deliver-story-reference.md#step-4--ci-watch--fix-recovery).
-
----
-
-## Step 5 — Merge confirmation + land tail (**recovery-only**)
-
-> On the default path Step 3 already did this. Run it only to resume a
-> `pending` envelope, to finish a `--no-wait-merge` run, or to rescue a
-> merged-but-mislabelled Story.
-
-```bash
-node .agents/scripts/single-story-confirm-merge.js --story <storyId> --cwd <main-repo>
-```
-
-This is the **same** shared land path Step 3 reaches: it flips
-`agent::closing → agent::done` on a confirmed merge (closing the issue) and
-runs the **same** post-land tail — so the two surfaces cannot diverge. It is
-idempotent, emits the same terminal envelope, and is safe to re-run while
-the PR is still open (returns `pending`).
-
-> **Confirmation outcomes.** `single-story-confirm-merge.js` re-reads the
-> live PR state and flips to `agent::done` only on a confirmed `MERGED` PR;
-> it is idempotent and safe to re-run while the PR is still open (returns
-> `pending`). See
-> [`deliver-story-reference.md` § Step 5 — Merge confirmation detail](deliver-story-reference.md#step-5--merge-confirmation-detail).
-
----
-
-## Step 5.5 — Re-assert Status column (**recovery-only**)
-
-> **The land tail already ran this** (Story #4543) — it is `tail.statusResync`
-> in the terminal envelope. Run it by hand only when that step reported
-> `false`, or after a manual merge on a `--no-wait-merge` run.
-
-GitHub Projects v2 built-in workflows fire minutes *after* auto-merge lands
-and clobber the `Done` Status the confirm step set, stranding closed
-Stories at `In Progress` on the board (reproduced on Story #2813).
-Re-assert authority:
-
-```bash
-node .agents/scripts/resync-status-column.js --story <storyId>
-```
-
-The helper re-fires the `ColumnSync` mutation and **polls for ~15 s** to win
-the race against the bot's late write (Story #2876). It is idempotent and
-no-op-safe (`no-project` / `not-on-project` exit 0).
-
-> **Status-column detail + tuning flags + operator fix.** For the poll-loop
-> flags (`--poll-attempts`, `--poll-delay-ms`), the `attempts` / `drifted`
-> envelope semantics, and the canonical
-> `--reap-conflicting-workflows` operator fix, see
-> [`deliver-story-reference.md` § Step 5.5 — Re-assert Status column detail](deliver-story-reference.md#step-55--re-assert-status-column-detail).
-
----
-
-## Step 6 — Local branch cleanup (**recovery-only**)
-
-> **The land tail already ran this** (Story #4543) — it is `tail.refCleanup`
-> and `tail.baseFastForward` in the terminal envelope, done in-process
-> against the same planners this command drives. Run it by hand only when
-> either step reported `false` (a dirty shared checkout is the common,
-> benign cause), or after a manual merge on a `--no-wait-merge` run.
-
-GitHub deletes the **remote** branch on auto-merge, but the **local**
-`story-<storyId>` ref lingers in the main checkout until something prunes
-it. To prune the story ref **and** fast-forward local `main` (or
-`project.baseBranch`):
-
-```bash
-node .agents/scripts/git-cleanup.js \
-  --execute \
-  --remote \
-  --yes \
-  --fast-forward-main \
-  --branches \
-  --include "story-<storyId>"
-```
 
-`--fast-forward-main` brings local `main` current (the next init seeds from
-it), `--branches` + `--include` reap only this Story's ref, and
-`--execute --remote --yes` run the deletes non-interactively. The sweep is
-idempotent and safe to run before `MERGED` confirms. Skip Step 6 only when
-the operator opted out via `--no-auto-merge` AND has not yet merged the PR —
-run the cleanup after the manual merge lands.
-
-> **Why local `main` goes stale + per-flag behaviour.** For the stale-`main`
-> mechanism and the full `--fast-forward-main` / `--branches` / `--include`
-> flag semantics, see
-> [`deliver-story-reference.md` § Step 6 — Local branch cleanup detail](deliver-story-reference.md#step-6--local-branch-cleanup-detail).
+Enter a recovery path **only** when Step 3's terminal envelope tells you to.
+The full procedures — commands, exit-code branches, and the
+internally-blocking-watch contract — live in
+[`deliver-story-reference.md`](deliver-story-reference.md); route by the
+envelope:
+
+- **`blocked` / `blockClass: "checks-failed"`** (a required check went red) →
+  fix and push a new commit on `story-<storyId>` (auto-merge stays armed), then
+  resume with the envelope's `nextCommand`. The watch is an internally-blocking
+  step — never end your turn with prose and an unconfirmed merge (Story #1553).
+  Procedure:
+  [reference § Step 4 — CI watch + fix recovery](deliver-story-reference.md#step-4--ci-watch--fix-recovery)
+  (triage per [`rules/ci-remediation.md`](../../rules/ci-remediation.md)).
+- **`pending`** (bounded merge wait expired, PR healthy; or a `--no-wait-merge`
+  run to shepherd) → run the envelope's `nextCommand`
+  (`single-story-confirm-merge.js`) until it resolves —
+  [reference § Step 5 — Merge confirmation detail](deliver-story-reference.md#step-5--merge-confirmation-detail).
+- **`tail.statusResync: false`** → re-assert the Status column by hand —
+  [reference § Step 5.5](deliver-story-reference.md#step-55--re-assert-status-column-detail).
+- **`tail.refCleanup: false` / `tail.baseFastForward: false`** → prune the local
+  ref and fast-forward `main` by hand —
+  [reference § Step 6](deliver-story-reference.md#step-6--local-branch-cleanup-detail).
 
 ---
 

package/.agents/workflows/helpers/qa-core.md

@@ -0,0 +1,174 @@
+---
+description: >-
+  Helper — not a slash command. The shared core the three QA workflows
+  (/qa-run, /qa-explore, /qa-assist) consume: contract resolution + loud
+  failure, the session & ledger contract, redact-first, the QaLedgerItem shape,
+  the triage procedure (classify → route → disposition → promote), and the HITL
+  write gate. Each workflow states only its mode-specific phases plus a short
+  Constraints delta and points here for everything else.
+caller: qa-run.md, qa-explore.md, qa-assist.md
+---
+
+# helpers/qa-core — shared QA harness core
+
+> **Not a slash command.** This file lives in `helpers/` and is not projected
+> into the plugin command tree. It is consumed by reference from
+> [`/qa-run`](../qa-run.md), [`/qa-explore`](../qa-explore.md), and
+> [`/qa-assist`](../qa-assist.md) — it states each shared block **once** so the
+> three workflows keep only their mode-specific phases and a Constraints delta.
+
+All three QA workflows are **prose workflows**, not Node orchestrators: the
+host LLM executes the procedure; deterministic Node helpers under
+`.agents/scripts/lib/qa/` (contract, session, redaction, coverage, missing-test)
+and `.agents/scripts/lib/findings/` (classification, dedup/route, cluster/size/
+promote) own every decision. The agent never invents those decisions in prose.
+
+## Contract resolution (fail loudly when absent)
+
+Resolve the consumer's `qa` contract block **before any QA work**, through the
+single seam [`resolve-qa-contract.js`](../../scripts/lib/qa/resolve-qa-contract.js):
+
+```js
+import { resolveQaContract } from '../scripts/lib/qa/resolve-qa-contract.js';
+const contract = resolveQaContract(config); // throws loudly if unbound
+```
+
+`resolveQaContract` **throws** — there is no silent fallback to auto-detection
+— when the `qa` block is absent (no `qa` key, or an empty `qa: {}`), malformed
+(wrong-typed or unknown field, e.g. `qa.featureRoot must be a string`), or
+missing a required field (it names the first one). The absent-block message
+reads: _"qa: this project has not bound the QA harness — add a `qa` block to
+.agentrc.json (featureRoot, fixturesManifest, environments, personas) before
+invoking the QA harness."_
+
+When the resolver throws, **STOP immediately**: relay its verbatim message to
+the operator as terminal output and do not proceed. Do not invent a
+`featureRoot`, guess a sign-in seam, or fall back to any retired headless BDD
+runner. The loud failure is the contract — a consumer that has not bound the
+harness has not opted into it.
+
+The normalized contract exposes `featureRoot`, `fixturesManifest`,
+`environments` (each keyed to `{ baseUrl, signInSeam, allowWrites? }`, resolved
+to one target via [`resolveQaEnvironment`](../../scripts/lib/qa/resolve-qa-contract.js)),
+`defaultEnvironment`, `personas` (canonical name-keyed map; a name-only persona
+resolves to an empty record), `consoleAllowlist` (default `[]`), and
+`designTokens` (default `null`).
+
+## Session & ledger (temp/qa/)
+
+Resolve the session and its ledger path **once**, up front, via
+[`qa-session.js`](../../scripts/lib/qa/qa-session.js):
+
+```js
+import { resolveQaSession } from '../scripts/lib/qa/qa-session.js';
+const { sessionId, ledgerPath, reused, untriaged } = resolveQaSession({ config });
+```
+
+- The ledger is always written under **`temp/qa/<sessionId>.ndjson`**
+  (`<tempRoot>/qa/`, from `project.paths.tempRoot`), one `QaLedgerItem` per line
+  validated against [`qa-ledger.schema.json`](../../schemas/qa-ledger.schema.json).
+  **Never** write it anywhere else, and never commit it — `temp/` is gitignored
+  per [`.agents/instructions.md` § 6](../../instructions.md).
+- When `reused` is `true`, a prior session of the same id exists: **append**,
+  never overwrite, and carry the `untriaged` items forward as the rolling
+  backlog. Pass `--session-id <id>` (or `QA_SESSION_ID`) to resume a named
+  session.
+
+## Redact first
+
+Before any evidence string touches disk or GitHub, scrub it through
+[`redact-evidence.js`](../../scripts/lib/qa/redact-evidence.js):
+
+```js
+import { redactEvidence } from '../scripts/lib/qa/redact-evidence.js';
+const evidence = redactEvidence(rawObservation);
+```
+
+This is mandatory per [`security-baseline.md`](../../rules/security-baseline.md)
+(§ Data Leakage & Logging, § Secrets Management) — bearer tokens, session
+cookies, `Authorization` headers, and emails are masked. The pass is
+idempotent, so redact eagerly; captured console and network evidence is
+untrusted until scrubbed. Secrets are never echoed into chat, findings, or the
+ledger.
+
+## The QaLedgerItem shape
+
+Each observation/finding is recorded as one `QaLedgerItem` on the session
+ledger, conforming to [`qa-ledger.schema.json`](../../schemas/qa-ledger.schema.json):
+
+- **`id`** — stable `L1`, `L2`, … in append order (after any carried backlog).
+- **`evidence`** — the **redacted** symptom / observation string.
+- **`coverage`** — the surface label the item points at (or `unknown`).
+- **`class`** — the ledger class (`product-bug`, `environment-setup`,
+  `tooling-dx`, `test-gap`, `enhancement`, …); resolves to the focus/meta label
+  set Triage applies.
+- **`severity`** — the tentative severity.
+- **`missingTest`** — the lowest absent test tier's description, or `null`.
+- **`disposition`** — left **untriaged** at capture; set only in Triage.
+
+**Append** to the ledger, never overwrite; a re-run appends to the same
+session. This is the single findings channel across all three workflows — there
+is no per-workflow finding schema.
+
+## Triage — classify → route → disposition → promote
+
+Route the ledger through the shared classify/route/dedup/promote core. The
+outcome is that **every ledger item carries a class, a route decision, and an
+operator-confirmed disposition**, with each `file` item promoted via
+`promote-finding.js` into `/plan` — verified by the cluster's fingerprint
+footer landing in each seed body. For each untriaged item:
+
+1. **Classify** via
+   [`classify-finding.js`](../../scripts/lib/findings/classify-finding.js). The
+   item's `class` resolves to the focus/meta label set (`tooling-dx` carries
+   `meta::framework-gap`; `enhancement` carries `meta::consumer-improvement`).
+   The helper **throws** on an absent/unknown class — fix the item's class
+   rather than defaulting.
+2. **Dedup / route** against existing GitHub Issues (open **and** closed) via
+   [`route-finding.js`](../../scripts/lib/findings/route-finding.js) — the
+   **single** dedup implementation shared with `audit-to-stories`:
+
+   ```js
+   import { routeFinding, fingerprintFooter } from '../scripts/lib/findings/route-finding.js';
+   const { decision, matchedIssue, fingerprint } =
+     await routeFinding(finding, { searchIssues });
+   ```
+
+   `decision` is one of `new` / `update-existing` / `duplicate` /
+   `regression-of-closed`. Wire `searchIssues` to the GitHub provider and stamp
+   the `fingerprintFooter(sha)` marker into any Issue body so future runs dedup
+   against it.
+3. **Decide the disposition** with the operator (`file` / `defer` / `dismiss`)
+   and record it back onto the ledger item.
+4. **Promote the `file`-dispositioned findings through `/plan`** via
+   [`promote-finding.js`](../../scripts/lib/findings/promote-finding.js) — the
+   same cluster/size/route/file path `audit-to-stories` consumes. Never
+   hand-roll the clustering, sizing, or promotion in prose:
+
+   ```js
+   import { promoteFindings } from '../scripts/lib/findings/promote-finding.js';
+   const { promotions } = await promoteFindings(ledgerItems, {
+     searchIssues, // GitHub provider, open + closed
+     createStory, // tight cluster (≤2 surfaces): seed → /plan --seed-file
+     createPlanSeed, // broad cluster (>2 surfaces): same /plan --seed-file path (may N>1)
+   });
+   ```
+
+   `promoteFindings` runs `clusterLedgerItems` + `targetForCluster`: a cluster
+   spanning **≤2** distinct coverage surfaces routes to `createStory`, **>2** to
+   `createPlanSeed` — neither opens an Epic; both render a **redacted** plan
+   seed (redaction already ran at capture), **stamp the cluster's
+   `fingerprintFooter(sha)` verbatim into the seed body**, and chain
+   `/plan --seed-file <seed>`. Prefer one Story; split only under the
+   default-single policy. A `file` disposition **never** opens a raw GitHub
+   Issue; only `defer` and `dismiss` skip the `/plan` handoff.
+
+## The HITL write gate
+
+Capture stays read-only precisely so every state change lands in Triage,
+deliberately and confirmed. Any ticket-filing, seed write, `/plan` invocation,
+or label mutation is a **write** — present the artifact, confirm each one with
+the operator, and wait before it happens. The agent never files tickets,
+promotes findings, or mutates a label autonomously. The plan→deliver hard stop
+is preserved: each `/plan` chain pauses at its own HITL gates and never
+auto-delivers.

package/.agents/workflows/helpers/qa-run-scenario-reference.md

@@ -0,0 +1,35 @@
+---
+description: >-
+  Reference sibling for helpers/qa-run-scenario.md — the spec-only, not-yet-
+  enabled batched sub-agent dispatch mode. Read only when turning that mode on.
+caller: qa-run-scenario.md
+---
+
+# helpers/qa-run-scenario — reference: batched sub-agent dispatch (spec-only)
+
+> **Not yet enabled.** This section specifies a future execution mode; the
+> current `/qa-run` sweep calls [`qa-run-scenario`](qa-run-scenario.md)
+> **inline**, one scenario at a time, in the orchestrator's own turn. The
+> batched mode below is documented so the contract is stable when it is turned
+> on — do not implement it as live behavior from this spec alone.
+
+In the deferred mode, the orchestrator MAY dispatch scenarios to fresh-context
+sub-agents to keep its own context window focused, under these hard rules:
+
+- **Sequential, never parallel.** Sub-agents run **one at a time**, never
+  concurrently. A live browser surface is a single shared resource; parallel
+  drivers would race on navigation and cross-contaminate evidence. (This
+  sequential-only rule is live today and stated in
+  [`qa-run-scenario.md`](qa-run-scenario.md) — it is not deferred.)
+- **One sub-agent per persona group.** Scenarios are grouped by persona and a
+  single sub-agent drives all of one persona's scenarios, so the persona is
+  signed in once per group rather than per scenario.
+- **Re-verify auth on entry.** Each sub-agent MUST re-verify the
+  authenticated-session precondition (a `take_snapshot` confirming the persona
+  badge) when it starts, because it does not share the orchestrator's live
+  session state.
+- **Same input/output contract.** Each sub-agent consumes the input contract
+  and returns the per-scenario result shape from
+  [`qa-run-scenario.md`](qa-run-scenario.md) for every scenario it drove — the
+  orchestrator aggregates identically whether the helper ran inline or via a
+  batched sub-agent.