mandrel 1.57.0

package/.agents/workflows/helpers/epic-audit.md

@@ -0,0 +1,295 @@
+---
+description: >-
+  Run smart change-set audits at Epic finalize. Consumes the epic-audit-prepare
+  envelope, dispatches each selected lens inline via runAuditSuite, and posts
+  an audit-results structured comment back onto the Epic ticket.
+---
+
+# Epic Audit (helper)
+
+> **Helper module.** Not a slash command. Invoked automatically from
+> `/epic-deliver` Phase 4 once the wave loop completes (all Stories at
+> `agent::done`). To run an audit directly, use `/epic-deliver [Epic_ID]` — it
+> delegates here (or pass `--skip-epic-audit` to bypass).
+
+This helper runs the **change-set-aware audit pass** on an Epic branch
+before the code-review helper opens its review. Unlike code-review (which
+walks the full diff against `main` through six fixed pillars), epic-audit
+asks the [`selectAudits`](../../scripts/lib/audit-suite/index.js) SDK which
+lenses are actually relevant to **this** Epic's change set, then dispatches
+only the matching audit workflows. Docs-only Epics select zero lenses and
+exit cleanly.
+
+In addition to the change-set selection, `epic-audit-prepare.js` unions in
+the **risk-routed lenses** (Story #3889): it reads the Epic's model-judged
+`planningRisk` envelope off the `epic-plan-state` checkpoint and routes each
+high-risk axis to its mapped lens via
+[`resolveAuditLenses`](../../scripts/lib/orchestration/code-review.js)
+(`security` → `audit-security`, `public-api` → `audit-architecture`). A
+high-risk Epic therefore auto-runs its mapped lenses even when the change
+set alone did not select them; a low-risk Epic adds nothing beyond the
+change-set selection. Both lens sources fire through the **same**
+`runAuditSuite` dispatch below — no new audit machinery.
+
+> **When to run**: After Phase 3 close-validation passes and before Phase 5
+> code-review. `/epic-deliver` invokes this automatically once the wave loop
+> completes and all Stories reach `agent::done`.
+>
+> **Persona**: `architect` · **Skills**: `core/code-review-and-quality`,
+> `core/security-and-hardening`
+
+## Step 0 — Resolve Context
+
+1. Resolve `[EPIC_ID]` — the GitHub Issue number of the Epic under audit.
+2. Resolve `[EPIC_BRANCH]` — `epic/<epicId>`.
+3. Resolve `[BASE_BRANCH]` from `baseBranch` in `.agentrc.json` (default:
+   `main`).
+4. Fetch the Epic ticket and identify linked context tickets:
+   - **PRD** — the `context::prd` ticket linked in the Epic body.
+   - **Tech Spec** — the `context::tech-spec` ticket linked in the Epic
+     body.
+5. Read both the PRD and Tech Spec fully to understand the intended scope,
+   selected lenses, and acceptance criteria.
+
+## Step 1 — Prepare (`epic-audit-prepare.js`)
+
+Run the prepare CLI to compute the change-set, ask `selectAudits` which
+lenses fire at `gate3` (the Epic close gate), and emit the helper-consumable
+JSON envelope on stdout:
+
+```bash
+node .agents/scripts/epic-audit-prepare.js \
+  --epic [EPIC_ID] --base-branch [BASE_BRANCH] --gate gate3
+```
+
+The CLI is thin glue around the audit-suite SDK and is fully described in
+[`epic-audit-prepare.js`](../../scripts/epic-audit-prepare.js). Capture the
+envelope:
+
+```json
+{
+  "epicId": 2586,
+  "epicBranch": "epic/2586",
+  "depth": "deep",
+  "selectedAudits": ["audit-security", "audit-privacy"],
+  "changeSetAudits": ["audit-privacy"],
+  "riskRoutedAudits": ["audit-security"],
+  "changedFiles": ["src/api/admin/users.ts", "..."],
+  "changedFilesCount": 47,
+  "substitutionsPayload": "src/api/admin/users.ts\n..."
+}
+```
+
+`selectedAudits` is the de-duplicated **union** of `changeSetAudits` (the
+change-set selection) and `riskRoutedAudits` (the model-judged risk-routed
+lenses). The two source arrays are surfaced for observability so the
+operator can see why each lens fired. Dispatch the `selectedAudits` union
+in Step 2.
+
+### The `depth` field (Story #3939)
+
+`depth` is `light`, `standard`, or `deep` — an **orthogonal** signal that
+tells you how thorough each **selected** lens should be on this Epic. It is
+resolved by the shared `resolveDepth` resolver from the Epic's model-judged
+risk envelope (`overallLevel` off the `epic-plan-state` checkpoint) folded
+with `changedFilesCount`: a high-risk **or** wide-footprint Epic resolves to
+`deep`, a low-risk small one to `light`, and everything else — including an
+Epic that skipped `/epic-plan` and has no checkpoint — to `standard`.
+
+Depth changes **how deeply** each lens runs, never **which** lenses fire:
+
+- **`light`** — run each selected lens against the **changed surface only**
+  and report **only Critical/High** findings. Skip the Medium/Suggestion
+  sweep. Light **never skips a selected lens** — including the alwaysRun
+  floor (`audit-clean-code`, `audit-architecture`) — it only **shrinks the
+  selected lens's sweep**. An easy, low-risk Epic still runs its audits;
+  they just run lighter.
+- **`standard`** — today's behavior: walk each selected lens's full
+  procedure over the changed surface at every severity.
+- **`deep`** — run the full lens procedure over the changed surface **plus
+  the modules it directly touches**, at every severity.
+
+Depth never changes the severity taxonomy, the findings-report shape, or the
+Phase 4 halting rule below (a 🔴 Critical Blocker halts at every depth;
+everything else logs). Thread the resolved `depth` into each lens walk in
+Step 2 — it scopes the sweep, it does not gate the roster.
+
+### Outcomes
+
+- **`selectedAudits` is non-empty** — continue to Step 2.
+- **`selectedAudits` is empty** (docs-only or no-lens change set, and no
+  high-risk axis routed a lens) — skip Step 2 and write the docs-only
+  marker described in Step 4.
+- **`degraded: true`** — the selector aborted. Possible `reason` codes:
+  `GIT_DIFF_TIMEOUT` (git-diff timed out), `HEAD_REF_UNRESOLVED` (the
+  Epic's branch `refs/heads/epic/<id>` is not present in this checkout),
+  or `EPIC_REF_MISMATCH` (the selector diffed a ref other than the
+  requested Epic's branch — the cross-epic-leak guard from Story #3362).
+  Surface the `reason`/`detail` fields to the operator, post a friction
+  comment on the Epic, and STOP. Do not fall back to running the full lens
+  roster — that defeats the change-set scoping, and an unresolved/mismatched
+  ref means the change set would belong to the wrong Epic.
+
+## Step 2 — Walk Selected Lenses (`runAuditSuite`)
+
+> **Execution model — the host LLM is the executor, not the CLI.**
+> `run-audit-suite.js` is a **prompt-assembly runner**, not a findings
+> generator. It resolves each lens to its workflow markdown, applies
+> the `{{ticketId}}` / `{{baseBranch}}` / `{{changedFiles}}` (and any
+> per-audit) substitutions, and returns one *workflow descriptor* per
+> lens. Its return envelope intentionally carries `findings: []` and
+> `summary: { critical:0, high:0, medium:0, low:0 }` because no lens
+> has been *executed* yet — the host LLM walks each workflow's
+> procedure inline against the substitution payload, severity-rates
+> what it finds, and assembles the aggregate report in Step 4. If you
+> expected `findings[]` to be populated by the CLI, the rest of this
+> helper will surprise you; stop and re-read this paragraph.
+
+For each lens name in `selectedAudits`, invoke
+[`runAuditSuite`](../../scripts/lib/audit-suite/index.js) (or its CLI
+wrapper) with the prepare envelope as the substitution source. The
+runner loads the matching `.agents/workflows/audit-<lens>.md` file,
+applies the substitutions, and — when `--run-id` is supplied — writes
+the substituted body to a per-lens artifact at
+`<auditOutputDir>/audit-<run-id>-<lens>.md` (default `auditOutputDir`
+is `temp/audits/`):
+
+```bash
+node .agents/scripts/run-audit-suite.js \
+  --audits audit-security,audit-privacy \
+  --ticket [EPIC_ID] \
+  --base-branch [BASE_BRANCH] \
+  --substitution changedFiles="[substitutionsPayload]" \
+  --run-id epic-[EPIC_ID]
+```
+
+CLI shape notes:
+
+- `--audits` is **comma-separated**, not space-separated. Passing each
+  lens as a separate positional arg only captures the first one.
+- `--substitution` is **repeatable** (`key=value` per occurrence); the
+  legacy `--substitutions '<json>'` flag is not supported.
+- `--run-id` is the per-lens artifact prefix (the legacy
+  `--artifact-prefix` flag is not supported). When omitted, no
+  artifact is written and the host LLM must walk the workflow body in
+  memory.
+
+After the runner returns:
+
+1. **Read the descriptor stream** — confirm every requested lens
+   appears in `metadata.auditsRun`, then walk each entry in
+   `workflows[]` (or each on-disk artifact when `--run-id` was set).
+2. **Execute the lens inline at the run's `depth`.** Open the lens
+   workflow at `path` (or the per-lens artifact file when `--run-id`
+   produced one) and follow its procedure verbatim against the
+   substituted change set, scoping the sweep to the envelope's `depth`
+   (see "The `depth` field" above): `light` walks the changed surface and
+   reports only 🔴/🟠 findings, `standard` walks the full procedure at
+   every severity, and `deep` extends the sweep to the directly-touched
+   modules. Depth scopes the sweep only — never skip a selected lens.
+   Each lens declares its own pillars, severity rubric, and remediation
+   prose; treat its body as the canonical execution contract for that
+   pass.
+3. **Aggregate** by severity (🔴 Critical Blocker / 🟠 High /
+   🟡 Medium / 🟢 Suggestion). Hold the aggregate for Step 3
+   (auto-fix) and Step 4 (the `audit-results` structured comment).
+
+If a future Story lifts per-lens execution out of the host-LLM walk
+into the CLI itself, the runner will populate `findings[]` and this
+section will collapse to a "read the structured findings off the
+envelope" bullet. Until then, the host LLM is the gate.
+
+## Step 3 — Remediation Routing (host LLM, no automated loop)
+
+There is **no runtime auto-fix function** at this phase. The host LLM is
+the executor: it inspects the aggregated 🔴 / 🟠 findings from Step 2 and
+either applies a focused fix on the Epic branch or escalates the finding
+to the operator via the `audit-results` comment in Step 4.
+
+For each 🔴 / 🟠 finding, the host LLM MUST decide between two paths:
+
+1. **Apply a focused fix on `[EPIC_BRANCH]`.** Permitted only when the
+   finding is unambiguously *fixable* (clean remediation, no scope creep,
+   no spec deviation, no secret exposure):
+   - Call [`assert-branch.js`](../../scripts/assert-branch.js) with
+     `--expected [EPIC_BRANCH]` before touching the working tree.
+   - Stage explicit paths only (never `git add .`).
+   - Make one focused conventional commit per finding
+     (`fix(<scope>): <description> (audit finding)`).
+   - Re-run the owning lens (re-invoke `run-audit-suite.js` for that
+     single lens) and confirm the finding is gone before moving on.
+   - Run the lens-appropriate validation subset (`npm run lint` plus the
+     relevant `npm test` slice) to confirm the fix did not regress
+     anything.
+   - If the rescan still surfaces the same finding, or validation
+     regresses, **stop fixing** — route the finding to escalation
+     (path 2) and record the attempt context in Step 4.
+2. **Escalate to the operator via Step 4.** Required when the finding
+   falls into any of the following classes:
+   - `spec-deviation` — the change diverges from the PRD/Tech Spec.
+   - `secrets` — credentials, tokens, or PII surfaced in the diff.
+   - `test-deletion` — coverage was removed without an explicit
+     decision in the spec.
+   - `scope-exceeded` — the remediation would touch more files than the
+     change set warrants.
+   - Any finding the host LLM cannot remediate after one focused
+     attempt (the equivalent of the prior loop's
+     `validation-regression` / `thrash-detected` exits).
+
+Do not invent a programmatic retry budget. The host LLM applies *at most
+one* focused-fix attempt per finding before escalating; any further
+remediation is the operator's call after reading the `audit-results`
+comment.
+
+Escalated findings flow through to Step 4 unchanged with their
+escalation reason recorded — the audit pass does not delete them, it
+just stops trying to fix them automatically. Surface the escalation
+reason for each in the `audit-results` comment so the operator sees
+exactly why the finding was not auto-remediated.
+
+## Step 4 — Post `audit-results` Structured Comment
+
+Persist the findings as an `audit-results` structured comment on the Epic
+issue. The comment is idempotent — re-runs replace the prior one. Build the
+body in a temp file under `[TEMP_ROOT]/epic-[EPIC_ID]/audit-results.md`,
+then upsert via [`post-structured-comment.js`](../../scripts/post-structured-comment.js):
+
+```bash
+node .agents/scripts/post-structured-comment.js \
+  --ticket [EPIC_ID] \
+  --marker audit-results \
+  --body-file [TEMP_ROOT]/epic-[EPIC_ID]/audit-results.md
+```
+
+The body MUST include:
+
+- the `selectedAudits` roster (or `Lenses applied: none (docs-only)` when
+  the prepare envelope returned an empty list),
+- the per-severity counts (🔴 critical / 🟠 high / 🟡 medium / 🟢 suggestion),
+- the per-lens findings grouped under the lens name, each carrying file
+  path + line range + pillar + recommended fix,
+- a link to the per-lens artifact files under `<auditOutputDir>` so the
+  operator (and downstream retro) can re-read the full prompt body.
+
+### Severity gating
+
+- **Any 🔴 Critical Blocker** → STOP. Relay to the operator and let
+  `/epic-deliver` Phase 4 record a manual intervention.
+- **Only 🟠/🟡/🟢** → log as non-blocking and return to `/epic-deliver`
+  Phase 5 (code-review).
+
+## Constraints
+
+- **Always** diff against `[BASE_BRANCH]`, not against individual Story
+  branches. The audit examines the cumulative effect of the entire Epic.
+- **Always** read the PRD and Tech Spec before walking lenses. Findings
+  without spec context are noise.
+- **Always** cap focused fixes at one attempt per finding (Step 3). The
+  host LLM is the executor; there is no shared retry/anti-thrash module
+  to call. Any finding that does not resolve cleanly on the first attempt
+  routes to escalation in Step 4.
+- **Never** widen the lens roster past `selectedAudits`. The whole point of
+  the change-set selector is to avoid running irrelevant audits on a
+  scoped Epic — running extras defeats the gate.
+- **Always** propagate `degraded` envelopes verbatim. Do not paper over a
+  selector failure with a full-roster fallback.

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

@@ -0,0 +1,370 @@
+---
+description: >-
+  Helper — not a slash command. Execute one Epic-attached Story end-to-end on
+  behalf of `/epic-deliver`. Calls `story-init.js`, `cd`s into the worktree,
+  runs the Story-implementation phase against the inline acceptance[] /
+  verify[] arrays, writes a `story-run-progress` snapshot per transition, and
+  finally calls `story-close.js` to merge into the Epic branch and reap the
+  worktree.
+caller: epic-deliver.md
+---
+
+# helpers/epic-deliver-story — Epic-attached Story worker
+
+> **Not a slash command.** This file lives in `helpers/` and is not projected
+> into the mandrel plugin command tree. It is invoked exclusively by the
+> [`/epic-deliver`](../epic-deliver.md) per-wave fan-out via an `Agent` tool
+> call (`subagent_type: general-purpose`). Run `/epic-deliver <epicId>` from
+> the operator surface, not this helper directly.
+
+## Overview
+
+`epic-deliver-story` is the **single-Story worker** for Epic-attached Stories.
+It sits below [`/epic-deliver`](../epic-deliver.md) (which fans out one Story
+sub-agent per slot, per wave) and runs one Story from init to close in one
+invocation.
+
+```text
+/epic-deliver <epicId>
+  → for each wave N:
+      Agent tool × concurrencyCap parallel calls (one assistant turn):
+        helpers/epic-deliver-story <storyId>
+          → story-init.js
+          → single Story-implementation phase using inline
+            acceptance[] / verify[] from the Story body
+          → story-close.js
+```
+
+The argument is always a **Story ID** (`type::story`). Epic IDs go through
+[`/epic-deliver`](../epic-deliver.md).
+
+**Standalone Stories** (no `Epic: #N` in body) use
+[`/story-deliver`](../story-deliver.md) instead — that workflow's helper
+branches from `main`, opens its PR directly to `main`, and skips the
+Epic-scoped machinery (cascade, dispatch manifest, dashboard regen). This
+helper requires a parent Epic and will refuse to initialize a Story that lacks
+the `Epic: #N` reference.
+
+> **Worktree isolation.** When `delivery.worktreeIsolation.enabled` is
+> `true`, Step 0 creates a worktree at `.worktrees/story-<id>/` and prints
+> its absolute path as `workCwd`. You **must** `cd` into that path before
+> Step 1. The main checkout's HEAD is never moved. See
+> [`worktree-lifecycle.md`](worktree-lifecycle.md) for node_modules
+> strategies, Windows notes, and escape hatches.
+
+---
+
+## Non-interactive execution contract
+
+`epic-deliver-story` runs as a sub-agent of `/epic-deliver`'s per-wave fan-out
+(common case) or interactively for a single Story. Sub-agent runs share
+the parent's permissions but have **no input channel** mid-run.
+
+- **Never** ask clarifying questions as a sub-agent. Pick the narrowest
+  reasonable interpretation that satisfies the Story's AC. If you cannot
+  proceed, transition to `agent::blocked`, post a `friction` comment with
+  the decision needed and the default assumption, and exit non-zero.
+- **Never** assume tool-permission prompts will be auto-approved. Treat a
+  blocking prompt as a harness condition and transition to `agent::blocked`.
+- **Always** write `story-run-progress` snapshots at every phase
+  transition so the parent aggregator never falls back to label
+  re-derivation.
+
+---
+
+## Step 0 — Initialize (`story-init.js`)
+
+Run from the **main checkout** (the worktree does not exist yet):
+
+```bash
+node .agents/scripts/story-init.js --story <storyId>
+```
+
+> **Execution mode (sub-agents must read).** This command typically takes
+> 3–6 minutes when the worktree's per-tree install runs. Invoke it
+> **synchronously** with the Bash tool's maximum timeout
+> (`Bash(timeout: 600000)`). Do **not** use `run_in_background` + `Monitor`
+> here: `Monitor`'s return is not equivalent to script exit, and a sub-agent
+> that exits during a `Monitor` wait kills `story-init.js` mid-batch — the
+> worktree is left half-initialized (no `story-init` comment, no Story-level
+> `agent::*` label flip) and the parent
+> wave aggregator records the Story as failed. The script is idempotent on
+> partial state, so the recovery is to re-run it synchronously, but
+> prevention is cheaper: just give Bash the 10-minute timeout and block.
+
+The script validates `type::story`, checks blockers, traces the
+Feature → Epic → PRD/Tech-Spec hierarchy, seeds `story-<id>` from the
+Epic branch, and (when worktree isolation is on) runs `git worktree add`
+at `.worktrees/story-<id>/`. The Story flips to `agent::executing`. A
+`story-init` structured comment is upserted with the Story's inline
+`acceptance[]` and `verify[]` arrays from the body.
+
+Capture `workCwd`, `dependenciesInstalled` (tri-state), and
+`context.{prdId,techSpecId,acceptance,verify}`. Add `--dry-run` to check
+status without git or ticket changes.
+
+### Step 0.5 — `cd` into the workCwd
+
+```bash
+cd "<workCwd from Step 0 result>"
+```
+
+All subsequent commands run from this directory. The `dependenciesInstalled`
+tri-state carries one of three values:
+
+| Value     | Meaning                                                                            | Action                                              |
+| --------- | ---------------------------------------------------------------------------------- | --------------------------------------------------- |
+| `true`    | Per-worktree install ran and succeeded.                                            | Proceed.                                            |
+| `false`   | Install was attempted and failed.                                                  | The next CLI runs the install before proceeding.    |
+| `skipped` | No per-worktree install (single-tree, reused worktree, `symlink`, `pnpm-store`).   | Trust the strategy.                                 |
+
+### Step 0.6 — Initial `story-run-progress` snapshot
+
+Re-read the `story-init` comment, apply the install tri-state, and upsert
+the initial snapshot (`phase: "init"`):
+
+```bash
+node .agents/scripts/story-deliver-prepare.js --story <storyId> --cwd .
+```
+
+The CLI runs the install command when `dependenciesInstalled === 'false'`
+(default `npm ci`; override with `--install-cmd "<cmd>"`).
+
+The CLI's stdout JSON envelope carries a `renderedBody` field — the markdown
+body that was upserted onto the Story ticket. **Relay it verbatim to chat**
+so operators see the initial progress block before the first commit lands.
+Do the same after every transition in Step 1 / Step 3 (the body is the
+Story-level rollup the parent `/epic-deliver` aggregator reads).
+
+---
+
+## Step 1 — Story implementation
+
+Run a single Story-implementation phase against the inline `acceptance[]`
+/ `verify[]` arrays on the Story body.
+
+1. Flip the snapshot to the `implementing` phase:
+
+   ```bash
+   node .agents/scripts/story-phase.js \
+     --story <storyId> --phase implementing
+   ```
+
+2. Read the Story body's inline `acceptance[]` and `verify[]` arrays
+   from the `story-init` structured comment (`context.acceptance`,
+   `context.verify`). Treat the acceptance items as the contract and
+   the verify items as the canonical at-keyboard checks.
+
+3. Implement the work as one or more commits on `story-<storyId>`.
+   Author commits directly with the project's editor / `git commit`,
+   following
+   [`.agents/rules/git-conventions.md`](../../rules/git-conventions.md):
+   - Conventional Commit subject (`feat:`, `fix:`, …).
+   - Reference the parent Story via `(refs #<storyId>)` in the subject
+     or body.
+   - The `commit-msg` Husky hook enforces commitlint locally.
+
+4. After the final commit lands, run the **bounded acceptance self-eval
+   loop** (Step 1a below) **before** flipping to `closing`. The
+   `verify[]` commands are consumed inside that loop as **required
+   evidence** — they are no longer optional advisory pre-flight.
+
+5. Once the eval loop returns `proceed`, flip the snapshot to `closing`
+   and proceed to Step 3:
+
+   ```bash
+   node .agents/scripts/story-phase.js \
+     --story <storyId> --phase closing
+   ```
+
+6. If blocked (including by the eval loop reaching its round cap with
+   criteria still unmet — Step 1a), flip the snapshot to `blocked`,
+   transition the Story to `agent::blocked`, post a `friction` comment,
+   and exit non-zero:
+
+   ```bash
+   node .agents/scripts/story-phase.js \
+     --story <storyId> --phase blocked
+   ```
+
+### Step 1a — Bounded acceptance self-eval loop (**required, not optional**)
+
+After the implementation commits land and **before** the snapshot flips to
+`closing`, run the bounded acceptance self-eval loop. The per-round critic
+mechanic (fresh-context critic, `verify[]`-as-evidence, the verdict schema, and
+the proceed / redraft / block decision) is the single-homed include
+[`acceptance-self-eval.md`](acceptance-self-eval.md) — read it and follow it.
+The critic reads the Story's inline `acceptance[]` / `verify[]` arrays from the
+`story-init` comment (`context.acceptance` / `context.verify`).
+
+Epic-attached specifics for this path:
+
+- **Gate invocation** (pass `--epic <epicId>` so the per-criterion signal lands
+  on the Epic-scoped stream):
+
+  ```bash
+  node .agents/scripts/acceptance-eval.js \
+    --story <storyId> --epic <epicId> --verdict <verdict-path>
+  ```
+
+- **On `decision: "proceed"`** → flip the snapshot to `closing` (item 5 above).
+- **On `decision: "block"`** → take the blocked path (item 6 above): post a
+  `friction` comment naming the unmet criteria and their evidence, flip the
+  snapshot to `blocked`, and exit non-zero. Never silently proceed to close.
+
+The resume guard is expressed at the Story level: re-entering a
+partially-implemented Story picks up from whatever commits are already
+on `story-<storyId>`; the agent inspects `git log` to decide what work
+remains.
+
+After each `story-phase.js` call, **relay the envelope's
+`renderedBody` to chat** as the Story's progress update. Skip chat
+relay only when running in a non-interactive sub-agent context where
+the parent will aggregate.
+
+> Rebase pauses on conflicts → follow
+> [`_merge-conflict-template.md`](_merge-conflict-template.md).
+
+---
+
+## Step 2 — Validate (deferred to close)
+
+`story-close.js` runs the canonical close-validation chain (typecheck,
+lint, test, format, maintainability, coverage, crap) before it merges —
+**do not** pre-run those gates here unless interactively iterating on a
+fix. (Interactively, `npm run typecheck && npm run lint && npm test` is
+fine as advisory pre-flight.)
+
+---
+
+## Step 3 — Close (`story-close.js`)
+
+Flip the snapshot to the closing phase, then invoke close. Pass the
+main-checkout path via `--cwd` so the merge and branch deletion run
+against the main repo (branches checked out in a worktree cannot be
+deleted from themselves):
+
+```bash
+node .agents/scripts/story-phase.js \
+  --story <storyId> --phase closing
+
+node <main-repo>/.agents/scripts/story-close.js --story <storyId> --cwd <main-repo>
+```
+
+In single-tree mode, `--cwd` defaults to `PROJECT_ROOT`. The script merges
+into `epic/<epicId>` (`--no-ff`), pushes the Epic branch, deletes the
+Story branch, reaps the worktree via `WorktreeManager.reap`, closes the
+Story to `agent::done`, runs `cascadeCompletion()`, and regenerates the
+Epic dispatch manifest (`--skip-dashboard` to suppress). Output is JSON
+with `ticketsClosed[]`, `cascadedTo[]`, and reap status.
+
+> **Why not GitHub auto-close?** `Closes #N` only fires on default-branch
+> merges; close fires the state writer explicitly.
+
+After close, upsert a terminal snapshot:
+
+```bash
+node .agents/scripts/story-phase.js \
+  --story <storyId> --phase done
+```
+
+---
+
+## Step 4 — Return contract (sub-agent path)
+
+When run as a sub-agent, return one JSON object:
+
+```json
+{
+  "storyId": <number>,
+  "status": "done" | "blocked" | "failed",
+  "phase": "init|implementing|closing|blocked|done",
+  "branchDeleted": <boolean>,
+  "blockerCommentId": <string|null>,
+  "detail": <string|undefined>,
+  "renderedBody": <string|undefined>
+}
+```
+
+`status === 'done'` requires the Story closed and
+`branchDeleted: true`.
+
+> **Handoff discipline — report state, not process.** Populate the return
+> object with essential terminal state only: the Story branch, the closing
+> commit SHA, what changed, and what was verified (this maps onto the
+> existing `storyId` / `branchDeleted` / `phase` / `detail` /
+> `renderedBody` fields — do **not** add new envelope fields). Do not
+> narrate the steps you took to get there, and do not prescribe how
+> `/epic-deliver`'s aggregator should do its job downstream. The parent
+> reads structured state from this envelope and the `story-run-progress`
+> snapshot; prose process commentary only bloats the hydrated prompt
+> (`delivery.maxTokenBudget` elision).
+
+`branchDeleted` is sourced from the `branchDeleted` field of the
+`story-close.js` result envelope, which is `branchCleanup.localDeleted &&
+branchCleanup.remoteDeleted`. It is **independent** of `worktreeReap.status`.
+Specifically, when `worktreeReap.status === 'stale-registry-entry'` — a
+Windows-only outcome where the worktree directory was removed and the local
+branch was deleted but `git worktree list` still shows the entry — the
+close still reports `branchDeleted: true` because the branch was honestly
+deleted; a pending-cleanup entry is recorded so the next post-close drain
+(or the next plan-time sweep) clears the stale `.git/worktrees/<name>/`
+registry entry. Treat `stale-registry-entry` as operationally complete
+when computing your return contract: `status: 'done'` is appropriate when
+all Tasks are closed and `branchDeleted: true`, regardless of whether
+`worktreeReap.status` is `'removed'`, `'removed-after-drain'`, or
+`'stale-registry-entry'`.
+
+`renderedBody` is the **most recent** `renderedBody` returned by
+`story-phase.js` (typically the `phase: 'done'` snapshot at close,
+or the `phase: 'blocked'` snapshot on a blocker). The parent
+`/epic-deliver` may inline a digest of this in its wave-level Notable
+section. When run interactively (no parent), omit it — the chat already
+has the latest body relayed during Step 1 / Step 3.
+
+---
+
+## Idempotence
+
+`story-init.js` re-prints the same `workCwd` without recreating the
+worktree. `story-run-progress` is upserted in place. `story-close.js`
+short-circuits when the Story branch is already merged and deleted. Re-
+running this helper against an already-closed Story is safe.
+
+---
+
+## Constraints
+
+- **MUST merge into `epic/<epicId>`, never `main`.** The Story branch's
+  only integration target is the parent Epic's integration branch. If
+  `story-close.js` short-circuits, no-ops, or otherwise fails to merge,
+  **do NOT** fall back to `gh pr create --base main`, **do NOT** invoke
+  `/story-deliver` on the same Story, and **do NOT** open a PR by
+  hand against `main`. Such a PR orphans the change on `main` and forces
+  a manual `git merge origin/main` back into `epic/<id>` to recover (the
+  Epic #2880 wave-5 / Story #2960 friction note). The framework refuses
+  these PRs via the `pr-base-guard` helper wired into every
+  `createPullRequest` surface; a raw shell `gh pr create` is the only
+  way to bypass it, and you must not. Diagnose the no-op (was the
+  branch already merged? is the ticket already closed? is the worktree
+  on the wrong HEAD?) and re-run close, or transition the Story to
+  `agent::blocked` with a `friction` comment so the operator can
+  resolve it.
+- **Never** push the Story branch directly to `main`. `story-close.js` is
+  the only writer that integrates upstream, and only into `epic/<epicId>`.
+- **Never** merge across Story branches; cross-Story dependencies are
+  resolved by wave ordering via `blocked by`.
+- **Always** `cd` into the `workCwd` returned by Step 0 before editing, and
+  prefix every path-based Edit/Write/Read with that absolute `workCwd` root —
+  the Edit tools ignore the shell cwd. The worktree pins the branch to
+  `story-<storyId>`, so there is no need to re-check `git branch` before each
+  commit.
+- **Always** upsert a `story-run-progress` snapshot at every phase
+  transition. The wave aggregator depends on this comment, not labels.
+- **Always** pass `--cwd <main-repo>` to `story-close.js` when invoking
+  from inside a worktree.
+- **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)).