mandrel 1.85.0 → 1.87.0

package/.agents/scripts/providers/github/tickets.js

@@ -22,6 +22,7 @@
  */
 
 import { parseBlockedBy, parseBlocks } from '../../lib/dependency-parser.js';
+import { stampFrameworkVersion } from '../../lib/framework-version.js';
 import { Logger } from '../../lib/Logger.js';
 import { TYPE_LABELS } from '../../lib/label-constants.js';
 import { addIssueToBoard } from './board-add.js';
@@ -56,11 +57,20 @@ const SEARCH_PAGE_CAP = 10;
  * arrays on the Story body authored by the decomposer; there is no
  * server-side rendering of a four-section payload at create time.
  *
+ * Story #4382 — this is also where a Story body is stamped, once, with the
+ * running Mandrel framework version and authoring date (hidden `mandrel_version`
+ * / `authored_at` meta field + a visible `> 🏷️ Authored with Mandrel …`
+ * marker) via {@link stampFrameworkVersion}. The stamp is immutable: a body
+ * that already carries a version (e.g. a reconciler re-create) is preserved
+ * verbatim. The `stamp` override exists for deterministic tests; production
+ * callers omit it so the running version and today's date are used.
+ *
  * @param {{
  *   body: string,
  *   parentId: number,
  *   epicId?: number,
  *   dependencies?: number[],
+ *   stamp?: { version?: string, authoredAt?: string } | false,
  * }} opts
  * @returns {string}
  *
@@ -75,8 +85,15 @@ export function composeStoryBody({
   parentId,
   epicId,
   dependencies = [],
+  stamp,
 }) {
-  const head = typeof body === 'string' ? body : '';
+  const rawHead = typeof body === 'string' ? body : '';
+  // `stamp === false` → footer-only recomposition: the caller (the reconciler
+  // UPDATE/diff path) owns stamp preservation itself and must NOT introduce a
+  // fresh authoring stamp, which would churn or bump the version on every
+  // reconcile. Every other call is a create — stamp once (immutably).
+  const head =
+    stamp === false ? rawHead : stampFrameworkVersion(rawHead, stamp ?? {});
   const lines = ['---', `parent: #${parentId}`];
   if (epicId !== undefined && epicId !== null) {
     lines.push(`Epic: #${epicId}`);

package/.agents/scripts/single-story-init.js

@@ -35,7 +35,6 @@
  * @see .agents/workflows/helpers/single-story-deliver.md
  */
 
-import { spawnSync as defaultSpawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { parseSprintArgs } from './lib/cli-args.js';
@@ -67,12 +66,18 @@ import {
   upsertStructuredComment,
 } from './lib/orchestration/ticketing.js';
 import { createProvider } from './lib/provider-factory.js';
+import { buildProtectionCtx } from './lib/single-story-sweep/protection-ctx.js';
 // `sweepMergedStoryBranches` is imported dynamically below — its transitive
 // graph reaches `picomatch` (via `git-cleanup.js`). Loading it statically
 // would crash module resolution before `assertDepsInstalled()` can emit a
 // friendly "run npm install" message.
 import { WorktreeManager } from './lib/worktree-manager.js';
 
+// `makeGhRunner` moved to the shared `single-story-sweep/protection-ctx.js`
+// module (Story #4373) so the three boot callers build an identical
+// protection ctx. Re-exported here to preserve its existing import path.
+export { makeGhRunner } from './lib/single-story-sweep/protection-ctx.js';
+
 /**
  * Fail fast with a clear, actionable message when project deps are missing.
  * Uses only Node builtins so it stays loadable when `node_modules/` is empty.
@@ -97,50 +102,6 @@ function assertDepsInstalled(projectRoot) {
 
 const progress = Logger.createProgress('single-story-init', { stderr: true });
 
-/**
- * Build the synchronous `gh` runner the single-story sweep uses for its
- * candidate-protection checks. Exported for testing.
- *
- * Story #2990: the sweep protection-ctx ghRunner stays on raw
- * `spawnSync('gh', …)` (not the `lib/gh-exec.js` async facade) because
- * `executeCleanup` invokes the protection checks inside a synchronous
- * candidate-filter loop. The runner contract is the legacy
- * `(args, opts) => stdout string` shape; converting it to async would
- * ripple into the single-story-sweep planner, which is intentionally out
- * of scope for the callers-only provider migration.
- *
- * Story #4073: the `spawnImpl` seam injects the `spawnSync` boundary so the
- * runner's success/error handling can be unit-tested without a live `gh`
- * binary. It defaults to `child_process.spawnSync` (mirroring the
- * `spawnImpl` seam in `lib/gh-exec.js` and the `runner` seam in
- * `lib/bootstrap/gh-preflight.js`), so the production CLI path is unchanged.
- * The synchronous `spawnSync` shape is preserved deliberately — the
- * candidate-filter loop in `executeCleanup` is synchronous, so converting
- * this to the async `lib/gh-exec.js` facade would ripple into the
- * single-story-sweep planner.
- *
- * @param {string} cwd Repo root used as the default spawn cwd.
- * @param {typeof defaultSpawnSync} [spawnImpl] Injectable spawn boundary —
- *   defaults to `child_process.spawnSync`. Tests pass a fake to assert the
- *   error/exit-code handling without spawning a real child process.
- * @returns {(args: string[], opts?: { cwd?: string }) => string}
- */
-export function makeGhRunner(cwd, spawnImpl = defaultSpawnSync) {
-  return (args, opts) => {
-    const result = spawnImpl('gh', args, {
-      cwd: opts?.cwd ?? cwd,
-      encoding: 'utf-8',
-      shell: false,
-    });
-    if (result.status !== 0) {
-      throw new Error(
-        `gh ${args.join(' ')} exit ${result.status}: ${result.stderr ?? ''}`,
-      );
-    }
-    return result.stdout ?? '';
-  };
-}
-
 /**
  * Validate that the fetched ticket is a standalone Story this script can
  * deliver. Throws with the canonical operator-facing message otherwise.
@@ -222,12 +183,7 @@ export async function reapMergedStoryBranches({
         info: (m) => progress('CLEANUP', m),
         warn: (m) => progress('CLEANUP', `⚠️ ${m}`),
       },
-      protectionCtx: {
-        repoRoot: cwd,
-        gitSpawn,
-        ghRunner: makeGhRunner(cwd),
-        getTicket: (id) => provider.getTicket(id),
-      },
+      protectionCtx: buildProtectionCtx({ cwd, provider }),
       lockPath,
       lockTimeoutMs,
     });

package/.agents/skills/core/epic-plan-consolidate/SKILL.md

@@ -32,6 +32,11 @@ allowed_tools:
 Senior Project Manager + Orchestrator, acting as a **holistic critic** with
 fresh context — deliberately *separate* from `epic-plan-decompose-author` (the
 generator) so the pass is a fresh-context review, not a same-pass self-critique.
+The `/plan` workflow delivers that fresh context by **dispatching this skill
+inside a genuine sub-agent** (`Agent` tool, `subagent_type: general-purpose`) at
+Phase 8.3, rather than activating it inline in the authoring turn — the
+sub-agent does not inherit the conversation that authored the draft, so the
+critic cannot grade its own homework.
 
 > **Read [`examples.md`](./examples.md) on demand** for the extended rationale:
 > why this critic runs with fresh context, why scope conservation is your
@@ -50,8 +55,8 @@ emit a plan the validator would reject.
 
 ## Inputs
 
-The dispatcher passes the Epic ID as the Skill argument. The Skill itself
-reads:
+The `/plan` workflow dispatches this skill inside a fresh-context sub-agent,
+passing the Epic ID as the Skill argument. The Skill itself reads:
 
 - `temp/epic-<Epic_ID>/tickets.json` — the **draft** Story array the
   `epic-plan-decompose-author` Skill wrote. This is the consolidation input.

package/.agents/skills/core/epic-plan-premortem/SKILL.md

@@ -31,7 +31,12 @@ allowed_tools:
 Senior Engineer + Architect, acting as a **fresh-context pre-mortem critic** —
 deliberately *separate* from `epic-plan-decompose-author` (the generator) and
 `epic-plan-consolidate` (the scope-preserving merge critic) so it is a
-fresh-context, code-reading review, not a same-pass self-critique.
+fresh-context, code-reading review, not a same-pass self-critique. The `/plan`
+workflow delivers that fresh context by **dispatching this skill inside a
+genuine sub-agent** (`Agent` tool, `subagent_type: general-purpose`) at Phase
+8.5, rather than activating it inline in the authoring turn — the sub-agent does
+not inherit the authoring conversation, so its code-reading review is
+independent of the draft it grades.
 
 > **Read [`examples.md`](./examples.md) on demand** for the extended rationale:
 > why this critic opens the actual cited code, why it is additive-recommendation
@@ -52,7 +57,8 @@ surfaces reaches GitHub unreviewed.
 
 ## Inputs
 
-The workflow passes the Epic ID as the Skill argument. The Skill itself reads:
+The `/plan` workflow dispatches this skill inside a fresh-context sub-agent,
+passing the Epic ID as the Skill argument. The Skill itself reads:
 
 - `temp/epic-<Epic_ID>/tickets.json` — the **draft** (or consolidated) Story
   array. This is the pre-mortem subject.

package/.agents/skills/skills.index.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-07-04T23:12:38.376Z",
+  "generatedAt": "2026-07-08T12:24:41.101Z",
   "generator": "generate-skills-index.js@1",
   "skills": [
     {
@@ -377,8 +377,8 @@
       "tier": "stack",
       "category": "architecture",
       "path": ".agents/skills/stack/architecture/subagent-orchestration/SKILL.md",
-      "description": "Coordinates complex tasks via task-isolated subagents. Use when one objective is too large for a single agent or when independent work streams should run concurrently with minimal context bleed. One objective per subagent; summarize before returning to keep the main context window clean.",
-      "policyCapsuleBullets": 7,
+      "description": "Coordinates complex tasks via task-isolated subagents. Use when one objective is too large for a single agent or when independent work streams should run concurrently with minimal context bleed. One objective per subagent; summarize before returning to keep the orchestrator's context window clean. Applies recursively — an orchestrator at any supported nesting depth applies the same policy to its own children.",
+      "policyCapsuleBullets": 8,
       "allowedTools": null,
       "vendor": null
     },

package/.agents/skills/stack/architecture/subagent-orchestration/SKILL.md

@@ -4,11 +4,33 @@ description:
   Coordinates complex tasks via task-isolated subagents. Use when one objective
   is too large for a single agent or when independent work streams should run
   concurrently with minimal context bleed. One objective per subagent;
-  summarize before returning to keep the main context window clean.
+  summarize before returning to keep the orchestrator's context window clean.
+  Applies recursively — an orchestrator at any supported nesting depth applies
+  the same policy to its own children.
 ---
 
 # Skill: Subagent Orchestration
 
+## Recursive orchestration model
+
+This skill describes **recursive orchestration**, not a fixed two-tier
+"main agent vs. subagents" split. An **orchestrator** is any agent that
+dispatches sub-agents; a sub-agent is itself an orchestrator over its own
+children. The Claude Code harness carries the `Agent` tool into sub-agents
+(verified nesting depth 2, announced max depth 5; see
+[#2870](https://github.com/dsj1984/mandrel/issues/2870)), so the same
+one-objective / verify / parallelize policy applies **at every level** —
+substitute "orchestrator" for "main agent" and "child" for "subagent"
+throughout and the rules hold unchanged. Keeping a given dispatch level
+flat remains a legitimate **design choice** (e.g. the `/deliver` wave
+loop), but it is no longer forced by a harness limitation.
+
+The cost caution compounds with depth: every nesting level re-pays the
+full always-loaded context, so an orchestrator MUST weigh the depth it
+opens against its budget (see
+[`instructions.md` § 4](../../../../instructions.md)) and stay within the
+supported depth envelope.
+
 ## Policy Capsule
 
 - Dispatch one objective per subagent; never bundle unrelated goals into a single delegation.
@@ -16,11 +38,13 @@ description:
 - Specify the expected return format explicitly (JSON summary, diff, bullet list) in every handoff.
 - Verify the subagent's output before incorporating it; treat returned artifacts as untrusted until checked.
 - Run non-dependent subagents in parallel; serialize only when one subagent's output is required input for another.
-- Require a concise summary back from each subagent to keep the main context window clean.
+- Require a concise summary back from each subagent to keep the orchestrator's context window clean.
 - Investigate subagent failures rather than retrying blindly with the same prompt.
+- Respect the nesting depth budget; each level opened re-pays the always-loaded context, so orchestrate deeper only when the isolation or parallelism gain justifies the cost.
 
 Internal protocol for managing complex tasks through the creation and
-coordination of subagents.
+coordination of subagents, applied recursively by the orchestrator at any
+supported depth.
 
 ## 1. Core Principles
 
@@ -28,8 +52,11 @@ coordination of subagents.
   with multiple unrelated tasks.
 - **Minimal Context:** Provide only the necessary context (files, docs, specific
   goal) to keep the subagent focused and token-efficient.
-- **Verification:** The main agent must always verify the subagent's output
-  before incorporating it into the final solution.
+- **Verification:** The orchestrator must always verify each child's output
+  before incorporating it into its own result — at every level of the tree.
+- **Depth Awareness:** Orchestration is recursive; before opening a deeper
+  level, confirm the work justifies re-paying the always-loaded context and
+  that the nesting stays within the supported depth envelope.
 
 ## 2. Operation Standards
 
@@ -38,11 +65,12 @@ coordination of subagents.
 - **Error Handling:** If a subagent fails or returns an ambiguous result,
   investigate the failure rather than retrying blindly.
 - **Parallelism:** Use subagents to perform non-dependent tasks concurrently
-  (e.g., auditing three different modules simultaneously).
+  (e.g., auditing three different modules simultaneously). A child that is
+  itself an orchestrator may parallelize its own sub-units the same way.
 
 ## 3. Best Practices
 
-- **State Sync:** Ensure the main agent's mental model remains the source of
+- **State Sync:** Ensure the orchestrator's mental model remains the source of
   truth if multiple subagents modify the codebase.
 - **Summarization:** Require subagents to provide a concise summary of their
-  findings to prevent the main context window from being flooded.
+  findings to prevent the orchestrator's context window from being flooded.

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

@@ -18,11 +18,17 @@ confirmation:
 3. **reap merged local branches** — the existing squash-aware
    `gh pr list --state merged` + `git branch --merged <base>` sweep,
    with attached worktrees removed first. Optionally also deletes the
-   `origin/<branch>` ref when `--remote` is passed. With `--remote`,
-   the planner additionally enumerates `refs/remotes/origin/*` and
-   reaps any **remote-only** merged branches — branches whose local
-   ref is already gone (or never existed) but whose `origin/<branch>`
-   still points at a merged PR.
+   `origin/<branch>` ref when `--remote` is passed. Every default run
+   also **enumerates** `refs/remotes/origin/*` and reports any
+   **remote-only** merged branches — branches whose local ref is
+   already gone (or never existed) but whose `origin/<branch>` still
+   points at a merged PR — even without `--remote`; `--remote` is still
+   required to *delete* them. A third branch, whose content already
+   landed in `<base>` by another route (a squash-merged Epic PR, a
+   cherry-pick, a manual `merge --squash`), is caught by a
+   **content-equivalence probe** (`git merge-tree --write-tree`,
+   git ≥ 2.38) even when it has no merged PR of its own and is not a
+   git ancestor of `<base>`.
 4. **triage `git stash` entries** — list every stash and prompt for
    `drop / keep / quit` per entry (or pass `--drop-stashes <ref>` for
    non-interactive use).
@@ -150,6 +156,10 @@ programmatic consumption:
       "detectedBy": "gh"
     }
   ],
+  "skipped": [
+    { "branch": "story-4200", "reason": "not-merged", "lastCommitAt": "2026-05-01T00:00:00Z" }
+  ],
+  "ghDegraded": false,
   "worktrees": [{ "path": "C:/repo/.worktrees/fix-foo", "ok": true, "dirty": false }],
   "local":  [{ "branch": "fix/foo", "ok": true, "alreadyGone": false }],
   "remote": [{ "branch": "fix/foo", "ok": true, "alreadyGone": true }],
@@ -200,18 +210,51 @@ follow-up prune when `--remote` is set, so passing both is idempotent
 
 ### branches
 
-The merged-branch sweep semantics:
-
-- A branch is a candidate iff it is not `<base>`, not the current
-  HEAD, not in `git config branch.protectedBranches`, and either has a
-  merged PR (`gh pr list --head <branch> --state merged`) or appears in
-  `git branch --merged <base>`.
+The merged-branch sweep recognizes three detection signals, in order:
+
+1. **`detectedBy: 'gh'`** — the branch has a merged PR
+   (`gh pr list --head <branch> --state all`, classified by the
+   **latest** PR's state).
+2. **`detectedBy: 'git-merged'`** — the branch is a git ancestor of
+   `<base>` (`git branch --merged <base>`), or of `origin/<base>` when
+   that remote-tracking ref exists (unioned so a stale local `<base>` —
+   fast-forward phase skipped, or `--branches` run alone — no longer
+   hides a branch already merged on the remote).
+3. **`detectedBy: 'content-merged'`** (Story #4395) — the branch has no
+   reapable PR verdict and is not an ancestor of `<base>` under either
+   anchor, but simulating the merge via
+   `git merge-tree --write-tree <base> <branch>` (git ≥ 2.38) produces a
+   tree identical to `<base>`'s own tree — i.e. applying the branch's
+   changes on top of `<base>` is a content no-op. This catches
+   `story-<id>` branches merged into `epic/<id>` whose Epic PR
+   **squash-merged** to `main` (the story commits are not ancestors of
+   `main` and the story branch usually has no PR of its own), and any
+   other branch whose content landed via a different route (a renamed
+   head, a cherry-pick, a manual `merge --squash`). When git rejects
+   `--write-tree` (git < 2.38) or the simulated merge conflicts, the
+   probe is inconclusive and the branch keeps its existing `not-merged`
+   skip — the signal never guesses. `content-merged` candidates render
+   with a "weaker signal — verify before deleting" annotation in the
+   dry-run list and are called out separately in the confirmation
+   prompt, since — unlike a merged PR or git ancestry — no CI or GitHub
+   merge check ever validated this branch's exact diff.
+
+Other candidate semantics:
+
+- A branch is a candidate iff it is not `<base>`, not the current HEAD,
+  not in `git config branch.protectedBranches`, and matches one of the
+  three signals above.
 - When a candidate has an attached worktree, the worktree is removed
   (force if dirty) **before** `git branch -D`, mirroring the pattern in
   [`worktree-lifecycle.md`](helpers/worktree-lifecycle.md).
 - `--remote` is required on top of `--execute` to touch `origin/`.
+- A throwing `gh` runner (auth failure, rate limit, missing binary) no
+  longer aborts the run: the branches phase logs one warning and
+  continues with the git-only signals (ancestry + content-equivalence).
+  The JSON envelope's `ghDegraded: true` records that this happened for
+  the run, and the dry-run text carries a matching warning line.
 
-The skip taxonomy distinguishes two unreapable cases:
+The skip taxonomy:
 
 - `reason: 'protected'` — the base branch or a name in
   `git config branch.protectedBranches`. Not reapable; ignore.
@@ -219,15 +262,26 @@ The skip taxonomy distinguishes two unreapable cases:
   `git checkout <base>`. The dry-run output surfaces a remediation
   hint so the operator sees the recovery path without having to look
   in the JSON envelope.
-
-The `--remote` flag also opts the planner into a **remote-only
+- `reason: 'tip-diverged-from-merge'` — the latest PR merged, but the
+  branch's tip has since moved past the merged commit (a post-merge
+  force-push). The dry-run line names both SHAs and a remediation hint
+  (delete manually via `git branch -D <branch>`, or push the follow-up
+  commit).
+- `reason: 'not-merged'` — none of the three detection signals matched.
+  Previously silent; the dry-run output now lists every surviving
+  `not-merged` branch as a one-line-per-branch summary with its
+  last-commit age, so the operator can see why a leftover branch isn't
+  reaped instead of hunting for it by hand.
+
+Every default run also opts the planner into a **remote-only
 enumeration pass**: in addition to walking `refs/heads/*`, the planner
 also walks `refs/remotes/origin/*` and emits candidates for any branch
 that exists on `origin` with a merged PR but has no local ref. These
-candidates carry `detectedBy: 'remote-only'` and `localExists: false`,
-and the executor runs only the `git push --delete origin/<branch>`
-path for them (no local `git branch -D` is attempted — there is no
-local branch to delete).
+candidates carry `detectedBy: 'remote-only'` and `localExists: false`
+and are always shown in the dry-run list; **deleting** them (via the
+`git push --delete origin/<branch>` path — no local `git branch -D` is
+attempted, since there is no local branch) still requires `--remote` on
+top of `--execute`, unchanged.
 
 ### stashes
 

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

@@ -70,6 +70,33 @@ it is about to run** before it acts.
 
 ---
 
+## Boot sweep
+
+Before detecting the git setup, run the **protected boot sweep** so
+`/git-deliver` starts from a tidy local checkout — a feature branch this
+command opened and pushed on a prior run, once its PR has merged, is reaped
+here rather than left to accumulate:
+
+```bash
+node .agents/scripts/boot-sweep.js \
+  --include 'feat/*' --include 'fix/*' --include 'chore/*' \
+  --include 'docs/*' --include 'refactor/*' \
+  --current "$(git rev-parse --abbrev-ref HEAD)"
+```
+
+This is the **safe subset** of the `/git-cleanup` phases: it fast-forwards the
+base branch (`main`), prunes stale remote-tracking refs, and reaps every local
+branch whose PR is **merged** and whose HEAD matches the merged `headRefOid`.
+It **never** touches the stash stack, and its `evaluateProtection` partition
+skips (never reaps) any candidate with unpushed work, a dirty worktree, or a
+still-open parent ticket; `--current` always excludes the branch you are on.
+The sweep is **silent on a no-op** — nothing merged, `main` already current →
+one summary line (`[boot-sweep] reaped 0 local + 0 remote; protected 0.`). Its
+exit code is always `0`; a failed sweep is reported in that summary, never
+allowed to fail the delivery run.
+
+---
+
 ## Step 0 — Detect Git Setup & Resolve Level
 
 1. Resolve `[BASE_BRANCH]` from `--base` or `.agentrc.json` →
@@ -248,6 +275,15 @@ Do **not** poll CI. That is the `/deliver` Phase 7 job and is overkill for
 ad-hoc changes. The operator (or GitHub's email notification) is the next
 watcher.
 
+> **Local ref left behind — reaped at the next boot.** At the **pr** level
+> this command leaves a local feature branch behind after the PR merges; it
+> does **not** reap it inline (the merge happens later, out of band). You do
+> not need to run `/git-cleanup` by hand: the next time `/git-deliver` (or
+> `/plan`) runs, its **Boot sweep** step reaps that merged ad-hoc branch and
+> fast-forwards `main` automatically. The delivering flow owns tidying its own
+> refs on the next boot — see
+> [`.agents/rules/git-conventions.md` § Local checkout hygiene](../rules/git-conventions.md).
+
 ---
 
 ## Troubleshooting

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

@@ -35,7 +35,29 @@ per-criterion, mid-delivery, and evaluates the actual work product.
 1. **Eval pass (fresh context, independent of the author).** Run a **separate
    critic pass** — a fresh-context sub-agent (`Agent` tool,
    `subagent_type: general-purpose`), *not* a continuation of your implementing
-   turn — so the evaluator does not grade its own homework. The critic:
+   turn — so the evaluator does not grade its own homework.
+
+   > **Inline-critic fallback (nesting-absent harness).** Dispatching the
+   > critic as a nested `Agent` is the preferred shape — it gives genuine
+   > fresh-context isolation — and works on any harness that carries `Agent`
+   > into sub-agents (Claude Code ≥ 2.1.202; see
+   > [#2870](https://github.com/dsj1984/mandrel/issues/2870)). This eval loop
+   > itself runs inside a Story delivery sub-agent, so the nested critic sits
+   > at nesting depth 2. If the host does **not** support nested `Agent`
+   > dispatch at that depth — the tool is absent, or a spawn attempt returns
+   > an unsupported-capability error — do **not** stall the Story. Fall back
+   > to authoring the verdict **inline**: in a deliberately scoped,
+   > self-critical pass (re-read only the diff, the `acceptance[]` /
+   > `verify[]` arrays, and the `verify[]` command output — treat the
+   > implementation reasoning as untrusted and score against the criteria
+   > afresh), write the same verdict file described below and hand it to the
+   > same `acceptance-eval.js` gate. The fresh-context isolation is weaker in
+   > the inline path, but the gate, the schema, the round cap, and the
+   > proceed / redraft / block decision are identical — a Story is **never**
+   > stranded on a nesting-absent harness. Note in the blocked/friction
+   > comment (if you block) that the inline fallback was used.
+
+   The critic:
    - Inspects the working diff (`git diff origin/<baseBranch>...HEAD`) and the
      Story's inline `acceptance[]` / `verify[]` arrays.
    - **Runs the `verify[]` commands** and consumes their output as **required

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

@@ -509,20 +509,26 @@ node .agents/scripts/lifecycle-emit.js --epic <epicId> \
 
 If Phase 8.5 fell back to the operator-merges-button path (`gh pr
 merge --auto` was declined), the `epic.merge.armed` event never fires
-inside this run and Phase 9 will not run automatically. After the
-operator merges the PR, `epic/<epicId>` and each `story-<id>` ref can
-be reaped manually:
+inside this run and Phase 9 will not run automatically. **Do not** hand-reap
+the refs with a raw `git branch -D` sequence — drive the same
+`BranchCleaner`-backed reap the auto-merge path uses by firing
+`epic.merge.armed` after the operator merges the PR:
 
 ```bash
-git checkout main
-git pull --ff-only origin main
-git branch -D epic/<epicId>
-git branch -D story-<id1> story-<id2> ...
-git remote prune origin
+node .agents/scripts/lifecycle-emit.js --epic <epicId> \
+  --event epic.merge.armed --pr-url <prUrl>
 ```
 
-Note that `git-cleanup.js` alone will not catch `story-<id>` refs in
-this case because the epic PR squash-merges break the `git branch
---merged main` signal and the stories never had their own PRs. Wiring
-a CLI surface that drives the BranchCleaner listener for this
-fallback is tracked as follow-up to Story #2398.
+That single emit reaps `epic/<epicId>` and every `story-<id>` ref from the
+checkpoint, prunes stale tracking refs, and fast-forwards local `main` to
+`origin/main` — the whole Phase 9 reap, not a partial hand-roll. A plain
+`git-cleanup.js` sweep alone will **not** catch the `story-<id>` refs here,
+because the epic PR squash-merge breaks the `git branch --merged main` signal
+and the stories never had their own PRs; the lifecycle-emit surface above is
+the correct driver.
+
+Re-running `/deliver <epicId>` reaches the same outcome without the manual
+emit: the idempotent-resume auto-arm
+(`detectMergedUncleanedEpic` → `armCleanupIfMerged` in
+[`epic-cleanup.js`](../../scripts/lib/orchestration/epic-cleanup.js)) detects
+the merged-but-uncleaned Epic and fires `epic.merge.armed` for you.

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

@@ -89,9 +89,17 @@ Every other runtime modifier is sourced from the Epic's labels or from
 - **Single pause point.** Only `agent::blocked` halts execution. No
   clarifying questions — if stuck, flip to `agent::blocked`, post a
   friction comment, park.
-- **Two-level dispatch.** Host LLM fans out per-Story Agent calls
-  directly with `subagent_type: general-purpose`. Sub-agents do not
-  carry the `Agent` tool, so this stays flat.
+- **Flat Story dispatch by design.** Host LLM fans out per-Story Agent
+  calls directly with `subagent_type: general-purpose`. Keeping Story
+  dispatch flat — the host owns the single fan-out level — is a
+  **design choice**, not a harness constraint: the wave aggregator, idle
+  watchdog, and merge-lock all assume one host-owned dispatch level. As of
+  Claude Code 2.1.202 a level-1 sub-agent **does** carry the `Agent` tool
+  and can nest further (verified depth 2, announced max depth 5; see
+  [#2870](https://github.com/dsj1984/mandrel/issues/2870)), so a Story
+  worker may itself fan out for its own sub-work within that depth budget —
+  the Epic wave loop nonetheless stays flat by choice, not because nesting
+  is unavailable.
 - **Operator-merges-PR exit.** Phase 7 opens the PR; the workflow
   never merges to `main` itself. Phase 8.5 may fire auto-merge when
   every signal is clean.
@@ -481,6 +489,17 @@ therefore auto-runs its mapped lenses (e.g. a `security`-axis Epic runs
 low-risk Epic adds nothing. Findings are persisted as an `audit-results`
 structured comment on the Epic.
 
+The helper walks the selected roster **serially in-context by default**; when
+the roster carries more than one lens it **may delegate the walk to a single
+audit-orchestrator sub-agent** that fans the already-selected lenses out as
+parallel level-2 agents and returns only the aggregated `audit-results` (see
+[`epic-audit.md` § "Optional: delegate the roster walk to an audit-orchestrator
+sub-agent"](epic-audit.md), within the sub-agent depth budget noted under
+"Flat Story dispatch by design" above). The roster stays fixed upstream, every
+per-lens cost gate is preserved, and the seven sequential-only lenses are **not**
+batch-converted — the fan-out parallelizes across lenses only and never changes
+how any single lens runs internally.
+
 - **Any 🔴 Critical Blocker** — STOP. Relay to the operator.
 - **Only 🟠/🟡/🟢** — log as non-blocking and continue.
 - **Selector reports `degraded: true`** — STOP. Propagate the
@@ -734,6 +753,18 @@ On an arming decision the predicate emits `epic.merge.ready`; the downstream
 `epic.merge.blocked` with the disqualifying reasons and exits without merging
 — the operator merges manually.
 
+**Blocked-path output (operator merges the button).** When arming is
+declined, `epic.merge.armed` never fires inside this run, so Phase 9 does not
+reap automatically. Surface the exact one-liner the operator runs **after**
+they merge the PR by hand so local refs are reaped and `main` is
+fast-forwarded (the idempotent-resume path below runs this automatically on
+the next `/deliver <epicId>`):
+
+```bash
+node .agents/scripts/lifecycle-emit.js --epic <epicId> \
+  --event epic.merge.armed --pr-url <prUrl>
+```
+
 Close the phase wrapper by emitting `epic.automerge.end` (records the arm
 outcome on the ledger; `merged: true` once GitHub completes the squash,
 `merged: false` with a reason otherwise):
@@ -784,6 +815,19 @@ via `helpers/epic-deliver-story`'s own checkpointing). The PR from Phase 7 is
 updated in place on subsequent runs. The authoritative live view is
 the `epic-run-progress` structured comment.
 
+**Resume auto-arm for a merged-but-uncleaned Epic.** When `/deliver` resumes
+against an Epic whose PR already merged (operator merged the button in a prior
+session) but whose local `epic/<id>` / `story-<id>` refs still linger, the
+resume path detects the merged-but-uncleaned state
+(`detectMergedUncleanedEpic` in
+[`epic-cleanup.js`](../../scripts/lib/orchestration/epic-cleanup.js)) and fires
+`epic.merge.armed` automatically so Phase 9 reaps — no manual command. The
+detection is idempotent: an already-reaped Epic (no local refs) is a clean
+no-op, and an unmerged Epic never arms. It resolves the merged PR's URL for the
+required `epic.merge.armed` payload and fails closed (does **not** arm) on any
+indeterminate `gh` probe. The one-liner under Phase 8.5 / Phase 9 is the manual
+equivalent for the case where the operator does not re-run `/deliver`.
+
 ---
 
 ## Constraints

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

@@ -318,11 +318,24 @@ Print a final run summary listing every delivered Story in completion order:
 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.
+rests at `agent::closing` with its issue OPEN).
 ```
 
+Then **fast-forward `main` yourself** — do not instruct the operator to run it
+after the last merge. The delivering flow owns bringing the local base branch
+up to whatever has merged so far:
+
+```bash
+node .agents/scripts/git-cleanup.js --fast-forward-main --execute --yes
+```
+
+This runs only the fast-forward-main phase (`git fetch origin main` →
+`git merge --ff-only`); it is idempotent and a no-op when `main` is already
+current, so it is safe to run even while some PRs are still queued in
+auto-merge. Report its one-line result in the summary. Merged Story branches
+themselves are reaped by the boot sweep at the next `/plan` / `/deliver` boot —
+see [`.agents/rules/git-conventions.md` § Local checkout hygiene](../../rules/git-conventions.md).
+
 When some Stories are blocked or failed, list them explicitly with the
 `blockerCommentId` or failure detail so the operator knows where to look.