mandrel 1.57.0

package/.agents/workflows/qa-run-harness.md

@@ -0,0 +1,288 @@
+---
+description: Drive Gherkin scenarios through a real browser as an agent-driven QA sweep
+---
+
+# /qa-run-harness
+
+Execute a consumer's Gherkin `.feature` scenarios through a **real browser**
+(the chrome-devtools MCP surface), with the agent acting as the step executor
+and a human observing. The harness resolves the consumer's `qa` contract,
+selects a concrete scenario set, signs in via the configured seam, navigates
+**from a root** to drive each `Given/When/Then`, and asserts `Then` outcomes
+**semantically** against the accessibility snapshot. Per-surface console and
+network are instrumented into structured findings; findings are bundled into a
+follow-up **draft** for operator sign-off — the harness never files tickets
+autonomously.
+
+This workflow is the agent-driven successor to the framework's earlier
+headless BDD runner. It is a **prose workflow**, not a Node orchestrator: the host LLM
+executes the procedure; deterministic Node helpers under
+`.agents/scripts/lib/qa/` do only contract resolution, scenario selection, and
+console filtering.
+
+> **When to run**: During sprint testing to exercise a targeted slice of the
+> acceptance suite (a feature, a tag expression, or a domain), for regression
+> passes before `/epic-deliver`, or on demand while debugging a Story's
+> user-visible behavior in a live browser.
+>
+> **Persona**: `qa-engineer` · **Skills**: `stack/qa/gherkin-authoring`,
+> `stack/qa/playwright-bdd` (authoring reference; this harness owns execution)
+
+## Slash Command
+
+```text
+/qa-run-harness <selector>
+```
+
+### Arguments
+
+| Name       | Required | Shape / Example                              | Notes                                                                                              |
+| ---------- | -------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `selector` | yes      | `feature:login`, `tag:@smoke and not @wip`, `domain:billing` | Scopes the sweep to a concrete scenario set. One of three kinds — see below. |
+
+The selector is resolved by
+[`resolve-selection.js`](../scripts/lib/qa/resolve-selection.js) into a
+deterministic, `(file, line)`-sorted scenario set under the contract's
+`featureRoot`. The three kinds map to that resolver's selector shapes:
+
+- **`feature:<id>`** → `{ kind: 'feature', id }` — the single `.feature` file
+  whose `featureRoot`-relative path stem (or basename) equals the id
+  (case-insensitive). Ambiguous ids throw; qualify with a relative path.
+- **`tag:<expression>`** → `{ kind: 'tag', expression }` — the scenario set
+  whose tags satisfy the cucumber boolean expression (`@tag` atoms with
+  `and` / `or` / `not` and parentheses). Quote expressions that contain
+  spaces.
+- **`domain:<name>`** → `{ kind: 'domain', name }` — every scenario under the
+  `featureRoot`-relative subdirectory `name`.
+
+### Examples
+
+```text
+/qa-run-harness feature:login
+/qa-run-harness "tag:@smoke and not @wip"
+/qa-run-harness domain:billing
+```
+
+The canonical tag taxonomy — `@smoke`, `@risk-high`, `@platform-web`,
+`@platform-mobile`, `@domain-*`, and the allowed extension syntax — is defined
+in `.agents/rules/gherkin-standards.md`. Do not invent tags inside a feature
+file; add new tags to the rule first.
+
+## Step 0 — Resolve the `qa` contract (fail loudly when absent)
+
+The harness is meaningless without the consumer's `qa` contract block in
+`.agentrc.json`. Resolve it through the single seam
+[`resolve-qa-contract.js`](../scripts/lib/qa/resolve-qa-contract.js) **before
+any browser work**:
+
+```bash
+node -e "import('./.agents/scripts/lib/qa/resolve-qa-contract.js').then(async (m) => { const { resolveConfig } = await import('./.agents/scripts/config-resolver.js'); const cfg = await resolveConfig(); console.log(JSON.stringify(m.resolveQaContract(cfg), null, 2)); })"
+```
+
+(Use whatever config-resolution entry point the host exposes; the contract
+seam is `resolveQaContract(config)`.) The resolver returns the normalized
+contract:
+
+| Field              | Use                                                                       |
+| ------------------ | ------------------------------------------------------------------------- |
+| `featureRoot`      | Root passed to `resolve-selection.js` for scenario discovery.             |
+| `fixturesManifest` | Persona → seed binding loaded before sign-in.                             |
+| `signInSeam`       | `{ kind: 'url', template }` **or** `{ kind: 'skill', skill }` — see Step 2. |
+| `personas`         | Canonical object map keyed by persona name (`personaNames` lists the names). Authored as a plain name array under a `urlTemplate` seam, or as a per-persona credential/skill map under a `skill` (or credential) seam — see Step 2. |
+| `consoleAllowlist` | Inline benign-console patterns (default `[]`) — see Step 4.               |
+| `designTokens`     | Pointer to the token/style source for visual inspection (default `null`). |
+
+### Loud-failure path (no `qa` block)
+
+`resolveQaContract` **throws** — there is no silent fallback to
+auto-detection — in three cases:
+
+- **Block absent** (no `qa` key, or an empty `qa: {}` with no harness-required
+  fields): the error reads
+  _"qa: this project has not bound the QA harness — add a `qa` block to
+  .agentrc.json (featureRoot, fixturesManifest, signInSeam, personas) before
+  invoking the QA harness."_
+- **Malformed shape** (wrong-typed field, unknown field): the error names the
+  offending field, e.g. `qa.featureRoot must be a string`.
+- **Missing required field**: the error names the first missing field.
+
+When you hit any of these, **STOP immediately**. Relay the resolver's
+verbatim message to the operator as the harness's terminal output and do not
+proceed to browser execution. Do not invent a `featureRoot`, do not guess a
+sign-in seam, and do not 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.
+
+### MCP availability check
+
+The chrome-devtools MCP surface (`navigate_page`, `take_snapshot`, `click`,
+`fill_form`, `evaluate_script`, `wait_for`, `list_console_messages`,
+`list_network_requests`) is **host-provided** — it is an external runtime
+dependency, not in-repo code. If the host does not expose it, degrade with a
+clear error ("the chrome-devtools MCP server is unavailable; the QA harness
+requires a live browser surface") and stop. Do not attempt a headless
+fallback.
+
+## Step 1 — Select the scenario set
+
+Pass the parsed `selector` and the contract's `featureRoot` to
+[`resolveSelection`](../scripts/lib/qa/resolve-selection.js). It returns
+`{ kind, featureRoot, files, scenarios }` where `scenarios` is the
+`(file, line)`-sorted set the sweep will execute. Determinism is load-bearing:
+re-running the same selector across sweeps scopes the identical set, so the
+evidence stays diffable.
+
+Load the `fixturesManifest` to resolve each persona's seed data before
+sign-in. If the selection is empty, report "no scenarios matched
+`<selector>`" and stop — an empty selection is operator error (a typo'd
+feature id or domain), not a passing sweep.
+
+## Step 2 — Sign in via the `signInSeam`
+
+Sign in **once per persona** before driving that persona's scenarios, using
+the contract's discriminated-union seam:
+
+- **`kind: 'url'`** — substitute `{persona}` into `template` (e.g.
+  `/dev/sign-in-as/{persona}` → `/dev/sign-in-as/admin`) and `navigate_page`
+  to the resulting dev seam URL. This is a dev-only seam; **no real
+  credentials** are ever entered. The persona **name** (a `personaNames`
+  entry) is the **sole input** the seam consumes — per-persona auth material
+  is neither needed nor read here, so under a `urlTemplate` seam the contract
+  is authored as a plain name array (`personas: ["athlete", "coach"]`).
+- **`kind: 'skill'`** — invoke the named consumer skill for procedural
+  (multi-step or non-URL) sign-in. Read the skill's `SKILL.md` and follow it.
+
+### Which seam kinds consult per-persona material
+
+Per-persona auth material (`credentialRef` / `signInSkill`, authored via the
+object-map `personas` shape) is consulted **only** under a `skill` or
+credential seam, where the sign-in procedure needs a stored credential
+reference or a per-persona sign-in skill. Under a `urlTemplate`
+dev-impersonation seam the persona name is the only input, so the material is
+never read — author name-only personas there rather than fabricating
+`credentialRef`/`signInSkill` values the harness ignores. The resolver
+normalizes both authored shapes to one canonical object map keyed by persona
+name; a name-only persona resolves to an empty record (no auth material).
+
+After sign-in, confirm the authenticated state with a `take_snapshot`
+(e.g. the user menu or persona badge is present) before driving any scenario.
+
+## Step 3 — Drive each scenario (navigation-first, semantic Then)
+
+For each scenario in selection order, drive its `Given/When/Then` steps
+through the browser. Two rules are **non-negotiable**:
+
+### Navigation-first — never URL-jump
+
+Start every scenario at a **root** (the app's home/dashboard after sign-in)
+and reach the surface under test **only by navigating UI affordances** — click
+nav links, menu items, buttons, and follow the same paths a real user would.
+**Never** `navigate_page` directly to a deep link to set up a `Given`. URL-
+jumping bypasses the app's real authorization and routing flows, which both
+masks access-control gaps and produces findings that do not reflect a user-
+reachable state. Driving via affordances keeps the agent inside the app's
+genuine flows and surfaces broken navigation, guard redirects, and dead links
+as findings rather than hiding them.
+
+Map the Gherkin steps to browser actions:
+
+- **`Given`** — establish state by navigating from the root via affordances
+  (sign in as the persona, navigate to the starting surface, seed via UI where
+  the manifest does not pre-seed).
+- **`When`** — perform the user action: `click`, `fill_form`,
+  `evaluate_script` (only for app-provided hooks, never to fabricate the
+  outcome), then `wait_for` the resulting transition.
+- **`Then`** — assert the outcome semantically (below).
+
+### Semantic Then assertion against the accessibility snapshot
+
+Assert every `Then` **semantically** against the accessibility snapshot from
+`take_snapshot` — match on roles, accessible names, labels, and visible text
+that express the user-visible outcome ("a banner with text _Invoice sent_ is
+visible", "a row for _ACME Corp_ appears in the invoices table"). **Do not**
+assert against brittle DOM/CSS/XPath selectors, and **do not** assert on HTTP
+status codes, response bodies, or DB rows — those are contract-tier concerns
+that belong in contract tests, not in a user-journey sweep (see
+`.agents/rules/testing-standards.md` § Assertion Placement). A `Then` that can
+only be expressed as a wire-shape or DB check is a signal the scenario is
+mis-tiered, not a reason to break the semantic rule.
+
+Before driving each scenario, state its **business intent** in one
+plain-English line, derived from the `Scenario:` name and its
+`Given/When/Then` (what the user is trying to do and the outcome that proves
+it) — e.g. "a signed-in coach reaches their own team-management surface".
+Then record the scenario's result (pass / fail / blocked) with the surface it
+ended on and a one-line user-visible symptom for any failure. State the
+intent for **every** scenario, not only failures. Keep it to one line sourced
+from the `Scenario:` name and steps — the `.feature` file is the source of
+truth; do not paraphrase every step or leak implementation detail.
+
+## Step 4 — Instrument & inspect (findings)
+
+Per surface visited, capture console and network and turn genuine problems
+into structured findings:
+
+1. **Console** — `list_console_messages`, then filter through the contract's
+   `consoleAllowlist` via
+   [`filterConsoleMessages`](../scripts/lib/qa/console-allowlist.js). Each
+   non-allowlisted console **error** (level `error` / `severe`) becomes one
+   `F#` finding; allowlisted patterns and non-error levels are suppressed. The
+   allowlist is a **noise filter, not a security control** — never expand it to
+   silence a genuine error signal.
+2. **Network** — `list_network_requests`; failed or error-status requests on
+   the surface become findings alongside the console-derived set.
+3. **Visual / style** — when `designTokens` is set, spot-check the surface
+   against the token source; gross token violations become findings.
+
+Findings use the structured `F#` shape: `{ id, classification, surface,
+symptom, likelyRootCause, disposition (blocker | follow-up), acceptance,
+foldsInto?, evidence: { console[], network[] } }`, validated against
+[`qa-finding.schema.json`](../schemas/qa-finding.schema.json). Before
+rendering any finding evidence, **scrub captured console/network of tokens,
+session cookies, and PII** per `.agents/rules/security-baseline.md` — findings
+are posted to GitHub at approval time.
+
+## Step 5 — Draft follow-ups (operator sign-off required)
+
+Validate each finding against
+[`qa-finding.schema.json`](../schemas/qa-finding.schema.json) first, then
+bundle findings **by likely root cause** into proposed follow-up tickets with
+`Depends-on` / `Blocks` relationships, and present the draft to the operator
+for approval. The harness **MUST NOT** create tickets autonomously — it stops
+at a draft. The operator-approval gate is the safety boundary against spurious
+filing. If the run was triggered from an Epic-testing context, hand the
+approved findings to the Epic-testing helper for attachment to the Epic's QA
+evidence ticket.
+
+## Step 6 — Report
+
+Summarize the sweep in chat with:
+
+- Selector applied and the resolved scenario count.
+- Scenario totals: passed / failed / blocked.
+- Findings totals by classification and disposition (blocker vs follow-up).
+- A per-scenario line pairing each scenario's plain-English intent with its
+  verdict (pass / fail / blocked), grouped by feature file or domain — so the
+  digest reads as "what was checked → what happened", not a tag list.
+- For each failure, the scenario name, file path, the surface it ended on, and
+  a one-line user-visible symptom.
+- A pointer to the drafted follow-up bundle awaiting sign-off (if any).
+
+## Constraints
+
+- **Always** resolve the `qa` contract first and **fail loudly** when it is
+  absent or malformed. There is no auto-detection fallback.
+- **Always** navigate from a root via UI affordances. **Never** URL-jump to a
+  deep link to set up a scenario.
+- **Always** assert `Then` outcomes semantically against the accessibility
+  snapshot. **Never** assert via DOM/CSS/XPath selectors, HTTP status codes,
+  response bodies, or DB rows inside a scenario — push those to the contract
+  tier per `.agents/rules/testing-standards.md`.
+- **Never** enter real credentials; sign-in uses the consumer's dev seam only.
+- **Never** file follow-up tickets autonomously; stop at a draft for operator
+  sign-off.
+- **Never** expand `consoleAllowlist` to suppress genuine error signal — it is
+  a benign-noise filter, not a security control.
+- **Always** scrub captured evidence of secrets and PII before rendering a
+  finding.
+- **Never** fall back to a retired headless BDD-runner workflow.

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

@@ -0,0 +1,327 @@
+---
+description: >-
+  Deliver one or more standalone Stories end-to-end. Accepts 1+ Story IDs,
+  computes a dependency-aware wave plan via `stories-wave-tick.js`, asks the
+  operator to confirm the plan, then fans out parallel Agent calls per wave
+  — each delegating to `helpers/single-story-deliver`. Stories without an
+  `Epic: #N` reference only; Epic-attached Stories use `/epic-deliver`.
+---
+
+# /story-deliver [Story IDs...]
+
+## Overview
+
+`/story-deliver` is the **operator-facing multi-Story delivery command**. It
+takes one or more Story IDs, builds a dependency-aware wave plan, optionally
+confirms it with the operator, and fans out one Agent call per Story per wave
+— parallel within each wave, serialised across waves.
+
+```text
+/story-deliver 101 102 103
+  → Phase 0 — Validate input & build DAG
+  → Phase 1 — stories-wave-tick.js → wave plan + operator confirmation
+  → Phase 2 — for each wave:
+        Agent tool × min(wave.stories.length, plan.concurrencyCap) parallel calls
+          helpers/single-story-deliver <storyId>
+  → Phase 3 — Summary
+```
+
+**When to use `/story-deliver` vs. other commands:**
+
+| Scenario | Command |
+| --- | --- |
+| 1+ standalone Stories (no `Epic: #N` in body) | `/story-deliver <id> [<id>...]` |
+| Exactly one standalone Story (lighter path) | `/single-story-deliver <id>` |
+| Epic-attached Stories (have `Epic: #N`) | `/epic-deliver <epicId>` |
+
+`/story-deliver` **refuses** Stories that carry an `Epic: #N` reference in
+their body. Those Stories belong to an Epic's dispatch manifest and must flow
+through `/epic-deliver`. Use `/single-story-deliver` for a single Epic-free
+Story when you want the leaner one-story path without wave machinery.
+
+> **Concurrency cap.** The cap is resolved **deterministically in code** by
+> `stories-wave-tick.js` (Phase 1a) — the same `resolveConfig` + `getRunners`
+> seam `/epic-deliver` uses — and emitted as the `concurrencyCap` field on the
+> `stories-wave-plan` envelope. The default is 3; override persistently via
+> `delivery.deliverRunner.concurrencyCap` in `.agentrc.json` (a
+> `.agentrc.local.json` override is honored) or per-run via the `--concurrency`
+> flag below. Phase 2 dispatches `min(wave.stories.length, plan.concurrencyCap)`
+> straight from the emitted field — do **not** re-read or merge config yourself.
+
+---
+
+## Arguments
+
+```text
+/story-deliver <storyId> [<storyId> ...] [--dep <fromId>:<toId> ...] [--yes] [--concurrency <n>]
+```
+
+- `storyId` — One or more GitHub issue numbers carrying `type::story` and
+  **no** `Epic: #N` reference. At least one is required.
+- `--dep <fromId>:<toId>` — Declare an explicit dependency edge: `<fromId>`
+  must complete before `<toId>` runs. Repeat for each edge. When omitted,
+  all Stories are treated as independent (wave 0 catches everything) unless
+  `blocked by #N` references between the supplied IDs are detected
+  automatically.
+- `--yes` — Skip the operator confirmation in Phase 1 and proceed
+  immediately. Safe for scripted / sub-agent invocations.
+- `--concurrency <n>` — Override the per-wave concurrency cap for this run
+  only. Passed through to `stories-wave-tick.js` in Phase 1a, which validates
+  it (must be a positive integer) and reflects it in the emitted
+  `concurrencyCap` field. When omitted, the cap is resolved from
+  `delivery.deliverRunner.concurrencyCap` (default 3).
+
+---
+
+## Phase 0 — Validate input and build DAG
+
+For each supplied Story ID:
+
+1. Confirm the issue exists and carries the `type::story` label.
+2. Confirm the issue body does **not** contain an `Epic: #N` reference. If
+   it does, STOP and tell the operator to use `/epic-deliver <epicId>`
+   instead.
+3. Collect `blocked by #N` references between the supplied Story IDs.
+   References to Story IDs outside the supplied set are advisory warnings
+   only — they do not block delivery.
+
+Construct the DAG input array:
+
+```json
+[
+  { "id": 101, "dependsOn": [] },
+  { "id": 102, "dependsOn": [101] },
+  { "id": 103, "dependsOn": [] }
+]
+```
+
+`dependsOn` is the union of:
+
+- `blocked by #N` edges where `N` is in the supplied set.
+- Explicit `--dep` edges.
+
+---
+
+## Phase 1 — Wave planning and operator confirmation
+
+### 1a. Compute the wave plan
+
+```bash
+node .agents/scripts/stories-wave-tick.js --dag '<dag-json>'
+# with a per-run cap override:
+node .agents/scripts/stories-wave-tick.js --dag '<dag-json>' --concurrency <n>
+```
+
+When the operator passed `--concurrency <n>` to `/story-deliver`, forward it
+verbatim to `stories-wave-tick.js`. The script resolves the cap from config
+(`delivery.deliverRunner.concurrencyCap`, default 3) and the override wins for
+that run.
+
+Stdout is one JSON envelope:
+
+```json
+{
+  "kind": "stories-wave-plan",
+  "waves": [
+    { "waveIndex": 0, "stories": [101, 103] },
+    { "waveIndex": 1, "stories": [102] }
+  ],
+  "totalStories": 3,
+  "concurrencyCap": 3,
+  "cycleError": null
+}
+```
+
+- **`cycleError` non-null** → STOP. Report the cycle to the operator and
+  exit. The Story set cannot be delivered until the circular dependency is
+  resolved.
+- **`waves` empty** → STOP. Zero Stories resolved — report and exit.
+- **`concurrencyCap`** is the resolved per-wave cap. Phase 2 dispatches
+  `min(wave.stories.length, plan.concurrencyCap)` from this field — the
+  workflow never re-reads or merges config to recover the cap.
+- An invalid `--concurrency` value (non-positive / non-integer) makes the
+  script exit non-zero with an `inputError` → STOP and surface the message.
+
+### 1b. Operator confirmation (skipped with `--yes` or for single-story plans)
+
+**Auto-skip rule (Story #3302):** When `waves.length === 1` and
+`waves[0].stories.length === 1`, skip the confirmation prompt
+automatically and proceed. A single-Story plan has no ordering ambiguity
+and no meaningful operator decision to make — the plan *is* "deliver this
+one Story". Prompting for confirmation would just be friction.
+
+Otherwise, present the wave plan to the operator in a readable table:
+
+```text
+Wave plan — 3 Stories across 2 waves
+  Wave 0 (parallel): #101 "<title>", #103 "<title>"
+  Wave 1 (after wave 0): #102 "<title>"
+
+Proceed? [Y/n]
+```
+
+Wait for the operator to confirm before dispatching. When the operator
+types `n` or `N`, abort cleanly with a summary of the plan that was
+declined. When `--yes` was passed, skip this step and proceed regardless
+of wave count.
+
+---
+
+## Phase 2 — Wave dispatch loop
+
+For each wave in `waves` (in `waveIndex` order):
+
+### 2a. Fan out per-Story Agent calls
+
+Emit **one `Agent` tool call per Story** in the wave, capped at
+`plan.concurrencyCap` from the Phase 1a `stories-wave-plan` envelope. When
+the wave contains more Stories than `plan.concurrencyCap`, dispatch the first
+`plan.concurrencyCap` in one turn with `run_in_background: true` and refill
+as each child returns — never exceed the cap, never wait for the whole
+batch before refilling. Do **not** re-derive the cap from config here; the
+envelope field is the single deterministic source.
+
+Each Agent call:
+
+1. Names the Story ID and instructs the child to invoke
+   [`helpers/single-story-deliver`](helpers/single-story-deliver.md)
+   for that Story.
+2. States the **return contract** (see § 2c).
+3. Reminds the child of the **non-interactive contract**: no clarifying
+   questions — if stuck, transition to `agent::blocked`, post a
+   `friction` comment, and exit non-zero.
+4. Requests the child suppress per-phase chat relay and include its
+   **terminal** `renderedBody` in the JSON return.
+
+Use `subagent_type: general-purpose`.
+
+### 2b. Collect results
+
+Wait for all dispatched Stories in the current wave to return before
+advancing to the next wave. A wave is complete when every dispatched
+Agent call has returned a result (success, blocked, or failed).
+
+### 2c. Per-Story return contract
+
+Each child returns:
+
+```json
+{
+  "storyId": <number>,
+  "status": "done" | "blocked" | "failed",
+  "phase": "init|implementing|closing|blocked|done",
+  "branchDeleted": <boolean>,
+  "blockerCommentId": <string|null>,
+  "detail": "<one-liner>",
+  "renderedBody": "<terminal story body>"
+}
+```
+
+### 2d. Wave outcome handling
+
+After every Story in a wave returns:
+
+- **All `status === 'done'`** → Advance to the next wave (or Phase 3 if
+  this was the last wave). Print a one-line wave-complete summary.
+- **Any `status === 'blocked'`** → STOP the wave loop. Post a summary
+  of blocked Stories and their `blockerCommentId` references. Do not
+  dispatch the next wave. Wait for the operator to resolve each blocker
+  and re-run `/story-deliver` with the same set (already-done Stories
+  will short-circuit because `single-story-close.js` is idempotent).
+- **Any `status === 'failed'`** → STOP the wave loop. Report the
+  failures. The operator must fix the failing Stories before re-running.
+
+---
+
+## Phase 3 — Summary
+
+Print a final run summary:
+
+```text
+/story-deliver — 3 Stories delivered in 2 waves
+
+  Wave 0: #101 ✅ done, #103 ✅ done
+  Wave 1: #102 ✅ done
+
+All Stories delivered. PRs opened, auto-merge armed. CI will merge each
+PR when checks pass; each child then confirms the merge and flips its
+Story to `agent::done` (Story #3385 — until the merge confirms, a Story
+rests at `agent::closing` with its issue OPEN). Run
+`git-cleanup --fast-forward-main` after the last merge to bring local
+main up to date.
+```
+
+When some Stories are blocked or failed, list them explicitly with the
+`blockerCommentId` or failure detail so the operator knows where to look.
+
+---
+
+## Opt-in post-green refactor stage (`delivery.refactorStage`)
+
+When `delivery.refactorStage.enabled` is `true` in `.agentrc.json`, each
+per-Story worker runs an **advisory** post-green refactor pass after the
+Story's suite is green and the close-validation gates already pass — and
+**before** close. The stage is **strictly opt-in and default-OFF**: when the
+key is unset or `false`, story-deliver behaves exactly as documented above
+and this stage is skipped entirely.
+
+The stage adopts the [`refactorer`](../personas/refactorer.md) persona and the
+[`core/refactoring-discipline`](../skills/core/refactoring-discipline/SKILL.md)
+skill to drive a behaviour-preserving pass that lowers CRAP and removes
+duplication on the files the Story already touched:
+
+- **Post-green only.** It runs after the suite is green and the gates pass —
+  never from red, and never to make a failing test pass.
+- **Behaviour-preserving.** Existing tests MUST keep passing without
+  modification; if a test had to change, the change was a behaviour change and
+  must be reverted.
+- **Advisory, not a gate.** This stage does **not** introduce a new
+  close-validation gate and does **not** change the semantics of the existing
+  [close-validation](../scripts/lib/close-validation.js) chain (typecheck,
+  lint, test, format, maintainability, coverage, crap). The canonical gates
+  remain the single source of pass/fail at close; the refactor stage only adds
+  an extra behaviour-preserving cleanup commit when enabled.
+
+> **Default-OFF guarantee.** Consumers who do not set
+> `delivery.refactorStage.enabled` (or set it to `false`) see no change in
+> delivery behaviour — no extra stage, no new gate, identical close semantics.
+
+---
+
+## Idempotence
+
+`/single-story-deliver` is idempotent at every phase:
+`single-story-init.js` reuses an existing worktree and
+`single-story-close.js` short-circuits when the Story is already closed.
+Re-running `/story-deliver` with the same Story set after a partial
+failure is safe — already-done Stories produce no-op outcomes; only the
+blocked or unstarted Stories execute.
+
+---
+
+## Constraints
+
+- **Never** pass Epic-attached Stories to this command. Detect `Epic: #N`
+  in Phase 0 and STOP.
+- **Never** advance to the next wave while any Story in the current wave
+  is `blocked` or `failed`.
+- **Never** exceed `plan.concurrencyCap` (the resolved cap emitted by
+  `stories-wave-tick.js`) parallel Agent calls at any moment.
+- **Always** confirm the wave plan with the operator before dispatching,
+  unless `--yes` was passed.
+- **Label transitions**: drive every `agent::*` state change through
+  `node .agents/scripts/update-ticket-state.js --ticket <id> --state <state>`.
+  This CLI is the authoritative mechanism — there is no separate
+  state-mutation MCP server to degrade from (see
+  [`.agents/instructions.md` § 1.D](../instructions.md)).
+
+---
+
+## See also
+
+- [`helpers/single-story-deliver`](helpers/single-story-deliver.md) — the
+  per-Story worker this command delegates to.
+- [`/epic-deliver`](epic-deliver.md) — full Epic wave loop for
+  Epic-attached Stories.
+- [`helpers/epic-deliver-story`](helpers/epic-deliver-story.md) — the
+  per-Story worker `/epic-deliver` uses internally.