mandrel 1.93.0 → 2.0.0

package/.agents/workflows/helpers/worktree-lifecycle.md

@@ -7,16 +7,15 @@ description: >-
 
 # Worktree-per-Story Lifecycle
 
-Parallel epic execution can race when multiple story agents share one working
+Parallel Story delivery can race when multiple agents share one working
 tree: rapid `git checkout` swaps cause `git add` to sweep another agent's WIP
-into the wrong commit. Epic #229 moves each dispatched story into its own
-`git worktree` at `.worktrees/story-<id>/` so branch swaps, staging, and reflog
-activity are isolated per-story. The main checkout stays quiet.
+into the wrong commit. Each Story runs in its own `git worktree` at
+`.worktrees/story-<id>/` so branch swaps, staging, and reflog activity are
+isolated per-Story. The main checkout stays quiet.
 
 This document is the operator and reviewer reference. See
-[`epic-deliver`](deliver-epic.md) and [`story-deliver`](deliver-stories.md)
-for the broader execution flow and the Epic-229 Tech Spec for
-architectural rationale.
+[`/deliver`](../deliver.md) and [`helpers/deliver-story`](deliver-story.md)
+for the broader execution flow.
 
 ## Configuration
 
@@ -24,18 +23,22 @@ All knobs live under `delivery.worktreeIsolation` in `.agentrc.json`:
 
 ```jsonc
 {
-  "orchestration": {
+  "delivery": {
     "worktreeIsolation": {
       "enabled": true, // master switch; false = single-tree (v5.5.1)
       "root": ".worktrees", // relative to repo root; must stay inside it
-      "nodeModulesStrategy": "per-worktree", // per-worktree | symlink | pnpm-store
+      "nodeModulesStrategy": "clone", // clone | per-worktree | symlink | pnpm-store
       "primeFromPath": null, // required when strategy = "symlink"
       "allowSymlinkOnWindows": false, // explicit opt-in for symlink on win32
       "reapOnSuccess": true, // remove worktree after successful story merge
-      "reapOnCancel": true, // remove worktree when story is cancelled
-      "windowsPathLengthWarnThreshold": 240, // pre-flight warning threshold (MAX_PATH=260)
-    },
-  },
+      "bootstrapFiles": [
+        ".env",
+        ".mcp.json",
+        ".agentrc.local.json",
+        ".agents/instructions.local.md"
+      ]
+    }
+  }
 }
 ```
 
@@ -47,20 +50,20 @@ are all rejected at config-load time.
 
 | Phase           | When                                                                          | What happens                                                                                                                                                |
 | --------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Sweep**       | Dispatch-manifest build (`/plan`) and `/deliver` | Stale `*.lock` files under `.git/` (older than 5 min) are removed before GC.                                                                                |
-| **GC**          | Dispatch-manifest build (`/plan`) and `/deliver` | Orphan `.worktrees/story-*` whose stories are closed are reaped if clean.                                                                                   |
-| **Force-drain** | `/plan` boot (`worktree-sweep.js` via `drainPendingCleanupAtBoot`), `story-close` post-merge (`forceDrainPendingCleanup`), `/deliver` Phase 7 | Retries `.worktrees/.pending-cleanup.json` (`git worktree remove` then `fs.rm`); Windows-only escalation enumerates user-mode handle holders and `taskkill`s them before re-trying. |
-| **Ensure**      | `story-init` (entry for `/deliver`)                  | `git worktree add .worktrees/story-<id>/` on the `story-<id>` branch.                                                                                       |
-| **Run**         | During story execution                                                        | Agent runs inside the worktree; HEAD/reflog activity is isolated.                                                                                           |
-| **Reap**        | After successful story merge (in `story-close`)                              | `git worktree remove` — refuses to delete dirty trees or unmerged branches.                                                                                 |
+| **Sweep**       | Operator-driven (`WorktreeManager.sweepStaleLocks`)                           | Stale `*.lock` files under `.git/` (older than 5 min) are removed before GC.                                                                                |
+| **GC**          | Operator-driven (`WorktreeManager.gc`)                                        | Orphan `.worktrees/story-*` whose Stories are closed are reaped if clean.                                                                                   |
+| **Force-drain** | Operator-driven (`drain-pending-cleanup.js`)                                  | Retries `.worktrees/.pending-cleanup.json` (`git worktree remove` then `fs.rm`); Windows-only escalation enumerates user-mode handle holders and `taskkill`s them before re-trying. |
+| **Ensure**      | `single-story-init.js` (entry for `/deliver`)                                 | `git worktree add .worktrees/story-<id>/` on the `story-<id>` branch.                                                                                       |
+| **Run**         | During Story execution                                                        | Agent runs inside the worktree; HEAD/reflog activity is isolated.                                                                                           |
+| **Reap**        | After successful Story merge (in `single-story-close`)                        | `git worktree remove` — refuses to delete dirty trees or unmerged branches.                                                                                 |
 
 The `WorktreeManager` (`.agents/scripts/lib/worktree-manager.js`) is the single
 authority for `ensure`, `reap`, `list`, `isSafeToRemove`, `gc`, `prune`, and
 `sweepStaleLocks`. No other script may call `git worktree` directly.
 
-Managed story worktrees are only eligible for `reap`/`gc` when the caller
-provides the expected Epic branch, so cleanup cannot silently skip the merge
-verification step.
+Managed Story worktrees are only eligible for `reap`/`gc` when the Story is
+merged (or otherwise confirmed closed) so cleanup cannot silently drop an
+unlanded branch.
 
 ### Stale-lock sweep
 
@@ -78,34 +81,28 @@ entry points (see table below).
 
 ### Sweep & GC entry points
 
-Sweep and GC do **not** run at every Epic entry point — in particular,
-`story-init` (the entry for `/deliver`) does not invoke them. The full
-set of callers is:
-
-| Entry point                                                           | Script / caller                                           | Runs sweep? | Runs GC? | Force-drain? | Notes                                                                                               |
-| --------------------------------------------------------------------- | --------------------------------------------------------- | ----------- | -------- | ------------ | --------------------------------------------------------------------------------------------------- |
-| Dispatch manifest build (`/plan` Phase 9)                        | `lib/orchestration/dispatch-pipeline.js::runWorktreeGc`   | ✅ Yes      | ✅ Yes   | ✅ Yes       | Called from `dispatch-engine.js::dispatch()`. Scoped to the epic being dispatched.                  |
-| Spec / decompose CLI boot (`/plan` helpers)                      | `drainPendingCleanupAtBoot` → `worktree-sweep.js`        | ✅ Yes*     | ❌ No    | ✅ Yes       | \*Drains the pending ledger then reaps `git worktree list` entries for done/closed Stories (`--force`). |
-| Story merge (`/deliver` close)                                  | `story-close.js` (`drainPendingCleanupAfterClose`) | ❌ No       | ❌ No    | ✅ Yes       | Runs after the post-merge pipeline when worktree isolation is enabled.                              |
-| Story close                                                           | `epic-deliver runner` (invoked by `story-close.js`)    | ✅ Yes      | ✅ Yes   | ✅ Yes       | Runs before branch deletion so reaping cannot collide with `git branch -D`.                         |
-| Story init (`/deliver <storyId>`)                               | `story-init.js`                                    | ❌ No       | ❌ No    | ❌ No        | Story execution relies on the dispatch/close pair to clean up; it only creates its own worktree.    |
-| Epic deliver wave loop (`/deliver`)                              | `/deliver` slash command + `lib/orchestration/epic-runner/*` | ❌ No       | ❌ No    | ❌ No        | Does not call `sweepStaleLocks` or `gc` directly; cleanup still flows through dispatch + close.     |
-| Drain pending-cleanup (operator-driven)                               | `drain-pending-cleanup.js` (run directly — see below)     | n/a         | n/a      | ✅ Yes       | Manual escape hatch; same drain + Windows escalation as the `/plan` and `/deliver` paths.   |
-
-Operator takeaway: if you need to force a sweep/GC without closing a story,
-the most direct path is re-running `/plan` (or rebuilding the dispatch
-manifest via `dispatcher.js`) against the active epic. Running
-`/deliver <storyId>` on its own does **not** clean up orphan worktrees
-or stale locks.
+Under the v2 single-Story delivery loop, `sweepStaleLocks` and `gc`
+remain `WorktreeManager` methods but have **no automatic caller** — the
+wave-era dispatch/close hooks that invoked them were deleted with the
+epic-runner. The lifecycle surfaces that do run automatically are:
+
+| Entry point                       | Script / caller                                                      | What it cleans                                                                                                          |
+| --------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| Story init (`/deliver <storyId>`) | `single-story-init.js` boot sweep (`sweepMergedStoryBranches`)        | Merged/closed `story-*` branches (local + origin) from prior runs; it then creates only its own worktree.                 |
+| Story close (`/deliver` close)    | `single-story-close.js` worktree-reap phase (`WorktreeManager.reap`)  | The per-Story worktree; on a Windows EBUSY-class lock the entry is deferred into `.worktrees/.pending-cleanup.json`.       |
+| Drain pending-cleanup (operator)  | `drain-pending-cleanup.js` (run directly — see below)                 | The pending-cleanup ledger, with optional Windows handle-holder escalation. This is the only path that drains the ledger. |
+
+Operator takeaway: if worktrees or stale locks accumulate, run
+`node .agents/scripts/drain-pending-cleanup.js` — nothing in the
+`/plan` → `/deliver` loop force-sweeps or GCs on your behalf.
 
 ## Draining the pending-cleanup ledger
 
 `.worktrees/.pending-cleanup.json` accumulates entries when
-`story-close.js` cannot remove a worktree on Windows because of an
-EBUSY-class lock. Plan boot ([`drainPendingCleanupAtBoot`](../../scripts/lib/orchestration/epic-plan-spec/phases/drain.js), run by `plan-persist.js` → [`worktree-sweep.js`](../../scripts/lib/orchestration/plan-runner/worktree-sweep.js))
-retries the entries — but if the holder
-is a long-lived user-mode process (a stranded test runner, a lingering
-biome/tsc, a node REPL), the lock never clears and the entry pins.
+`single-story-close.js` cannot remove a worktree on Windows because of
+an EBUSY-class lock. If the holder is a long-lived user-mode process (a
+stranded test runner, a lingering biome/tsc, a node REPL), the lock
+never clears and the entry pins.
 
 [`drain-pending-cleanup.js`](../../scripts/drain-pending-cleanup.js)
 runs the standard drain *and* enumerates handle holders via
@@ -116,23 +113,10 @@ PowerShell `Get-CimInstance Win32_Process`, terminating them with
 > `/drain-pending-cleanup` slash command — it was demoted to a
 > directly-runnable script (Story #3706, overturning the
 > `docs/decisions.md` matrix row that originally kept it as a command).
-> The three automatic callers — `/deliver` runner Phase 7,
-> `story-close.js`, and `worktree-sweep.js` — invoke
-> `drain-pending-cleanup.js` **directly**, so the demotion does not touch
-> them. The manual path survives unchanged as
+> The wave-era automatic callers were deleted with the epic-runner in
+> the v2 cutover, so the drain is now operator-driven:
 > `node .agents/scripts/drain-pending-cleanup.js`.
 
-### When it runs automatically
-
-| Trigger          | Caller                                                                       |
-| ---------------- | ---------------------------------------------------------------------------- |
-| `/deliver`    | [`Cleaner` lifecycle listener](../../scripts/lib/orchestration/lifecycle/listeners/cleaner.js) at the close-tail cleanup phase (before `wm.gc()`)   |
-| `/plan`     | [`drainPendingCleanupAtBoot`](../../scripts/lib/orchestration/epic-plan-spec/phases/drain.js) (run by `plan-persist.js`) → [`worktree-sweep.js`](../../scripts/lib/orchestration/plan-runner/worktree-sweep.js) |
-| Story merge close | [`story-close.js`](../../scripts/story-close.js) (`drainPendingCleanupAfterClose`) |
-
-All automatic paths call `forceDrainPendingCleanup()` (or are folded into
-`sweepStaleStoryWorktrees`, which calls it first).
-
 ### When to run it manually
 
 - The end-of-epic banner reports `pending-cleanup persistent-lock: story-N, ...`.
@@ -242,9 +226,9 @@ Symlink strategy:
   content-addressable store at `~/.local/share/pnpm/store` (or the platform
   equivalent) — reused packages are hard-linked into the worktree instead of
   re-downloaded and re-extracted. First-run on a cold store is no faster than
-  `per-worktree`, and the plan healthcheck (`epic-plan-healthcheck.js
-  --prime-install`, an opt-in manual run) primes the store in the
-  main checkout to avoid paying that cost in parallel story windows.
+  `per-worktree`. Operators can prime the store once in the main
+  checkout (`pnpm install --frozen-lockfile`) to avoid paying first-run
+  cost in parallel story windows.
 
 ## Windows notes
 

package/.agents/workflows/mandrel-update.md

@@ -32,7 +32,7 @@ generated `.claude/commands/` tree is
 the CLI's sync step.
 
 > **Persona**: `devops-engineer` · **Skills**:
-> `core/ci-cd-and-automation`, `core/documentation-and-adrs`
+> `core/gates-and-baselines`, `core/documentation-and-adrs`
 
 ## Step 0 — Detect the install state and pick the invocation form
 
@@ -167,7 +167,8 @@ the action is `custom-hook-skip` and the helper returns the snippet to
 append by hand), **scripts** (backfill `quality:preview` /
 `quality:watch` only when absent), **config** (seed missing
 `delivery.quality.*` defaults — operator overrides survive). The baselines
-step relocates per-Epic snapshots under `temp/epic/<id>/baselines/`; the
+step migrates legacy per-Epic snapshot layouts into the ephemeral
+`temp/epic/<id>/baselines/` namespace when upgrading from pre-v2 shapes; the
 main-tracked root baselines are never touched. A second run reports
 `no-change` on every path — the idempotence contract this workflow
 requires.

package/.agents/workflows/plan.md

@@ -1,171 +1,138 @@
 ---
 description:
-  Unified planning entry point. Routes a seed idea (via scope triage) or an
-  existing Epic ID to the right planning path — the 3-step Epic path
-  (interrogate → author → persist) or the standalone-Story authoring path —
-  and absorbs every planning flag.
+  Unified planning entry point. Interrogate → author → persist. Emits one
+  Story by default (folded Tech Spec in the Story body); splits into N>1
+  only under the default-single split policy.
 ---
 
-# /plan [Epic ID] | --idea "<seed>" | --from-notes <path>
+# /plan --seed "<text>" | --seed-file <path> | --tickets <ids>
 
 ## Role
 
-Router. `/plan` owns argument parsing and path selection only — all step
-content lives in the two path helpers:
+Single planning path. `/plan` owns the full ceremony — there is no
+Epic/Story router, no scope-triage `epic|story` verdict, and no
+`deliveryShape`. Two operator modes only:
 
-- [`helpers/plan-epic.md`](helpers/plan-epic.md) — the 3-step Epic planning
-  path (interrogate → author → persist; Tech Spec + Acceptance Table folded
-  into the Epic body, then the Story backlog or a single-delivery marker).
-- [`helpers/plan-story.md`](helpers/plan-story.md) — the standalone-Story
-  authoring path (context envelope → host-LLM draft → HITL → issue create).
+1. **Text** — seed from chat or a file.
+2. **Tickets** — analyze existing issue(s) into proper Stories.
 
-The existing **scope-triage skill**
-([`core/scope-triage`](../skills/core/scope-triage/SKILL.md), verdicts
-`epic | story | borderline`) is the router's classifier on the `--idea`
-path; no new classification machinery exists.
+Audit findings become Stories via [`/audit-to-stories`](audit-to-stories.md)
+(separate workflow), which hands off with `--emit-plan-seed` →
+`/plan --seed-file <path>`.
 
 ## Inputs
 
 | Invocation | Behavior |
 | --- | --- |
-| `/plan --idea "<seed>"` | Ideation → **scope triage**. Verdict `epic` → run [`helpers/plan-epic.md`](helpers/plan-epic.md) from its ideation entry. Verdict `story` → run [`helpers/plan-story.md`](helpers/plan-story.md) Phases 1–3. Verdict `borderline` → present both options and let the operator choose. |
-| `/plan <epicId>` | Existing-Epic path — run [`helpers/plan-epic.md`](helpers/plan-epic.md) from its existing-Epic entry. When the helper's story-sized advisory fires (the Epic is really one Story), convert **internally** by switching to [`helpers/plan-story.md`](helpers/plan-story.md) — do not re-triage and do not hop commands. |
-| `/plan --from-notes <path>` | Internal handoff target (e.g. from `/audit-to-stories`). The notes file already encodes the path decision; do **not** re-run scope triage. Route per the notes' declared shape. |
+| `/plan --seed "<text>"` | Ideation from chat text: interrogate → author **one Story by default** → persist. |
+| `/plan --seed-file <path>` | Author from on-disk notes / plan seed (e.g. audit-to-stories handoff). |
+| `/plan --tickets 123[,456…]` | Fetch issue(s), analyze into proper Stories (prefer N=1 rewrite). |
+
+`--body` is **not** a `/plan` entry. Persist always goes through
+`plan-persist.js --stories …`.
 
 ## Flags
 
-`/plan` absorbs every planning flag and forwards it to the active path
-helper:
-
-| Flag | Path | Meaning |
-| --- | --- | --- |
-| `--idea "<seed>"` | both | Seed text; triggers scope triage. |
-| `--from-notes <path>` | both | Pre-triaged handoff notes; skips triage. |
-| `--force` | Epic | Re-plan: overwrite managed sections in place and close + recreate the ticket tree. |
-| `--amend` | Epic | Change-request delta persist: tickets carry `op: add\|modify\|keep\|close`; close ops require `--explicit-delete` after the dry-run diff. |
-| `--force-review` | Epic | Force the gate #2 operator review even when risk routing would skip it. |
-| `--allow-over-budget` | Epic | Permit a decomposition that exceeds the framework `maxTickets` reviewability budget. |
-| `--yes` | both | **Non-interactive / headless mode.** Deterministically auto-proceeds the two `/plan` HITL STOP gates — gate #1 (exit of interrogate) and gate #2 (risk-routed pre-persist review) — without waiting for operator input. Parallel to [`/deliver --yes`](deliver.md). Composes with `--allow-over-budget` and with the risk-routed gate #2 skip (it forces a proceed where those do not apply). Default (flag absent) behavior is unchanged: both gates still STOP for interactive use. |
-| `--steal` | Epic | Forcibly transfer a foreign Epic-lease. |
-| `--resume` | Epic | Continue a partial persist (rate-limit / crash recovery). |
-| `--dry-run` | Story | Author + validate without GitHub writes (`story-plan.js --dry-run`). |
-| `--body <path>` | Story | Pre-authored Story body file; validate (and create, unless `--dry-run`) without re-authoring. |
-| `--persona <name>` | Story | Override the persona label on the drafted Story. |
-| `--refine` / `--no-refine` | Story | Toggle the draft refinement loop. |
-
-**Cross-path flags are no-ops with a warning.** An Epic-only flag passed on
-the story path (or vice versa) is reported once
-(`[plan] --force has no effect on the story path`) and ignored — never an
-error. The historical bidirectional escalation between the two planning
-commands (story-sized Epic ↘ Story; epic-sized Story draft ↗ Epic) is an
-**internal branch switch** inside this router: same skills, same helpers, no
-command hop and no operator re-entry.
-
-### Headless / non-interactive mode (`--yes`)
-
-`--yes` is the headless escape hatch for an unattended driver (CI, a
-benchmark harness, or any `claude -p` run with no human at the keyboard). It
-is the `/plan`-side parallel of [`/deliver --yes`](deliver.md). `/plan` has
-exactly **two** HITL STOP gates, and `--yes` deterministically auto-proceeds
-**both** without waiting for operator input:
-
-1. **Gate #1 — the exit of the interrogate step.** One conceptual gate with
-   a face per entry form, and `--yes` auto-proceeds all of them:
-   - On the `--idea` Epic path, the interrogate step of
-     [`helpers/plan-epic.md`](helpers/plan-epic.md) STOPs to confirm the
-     sharpened one-pager, folding in the scope-triage verdict and the
-     duplicate-candidate review.
-   - On the `--idea` Story path,
-     [`helpers/plan-story.md`](helpers/plan-story.md) Phase 2 STOPs to
-     confirm the drafted Story body.
-   - On the existing-Epic (`/plan <epicId>`) path, the interrogate step
-     STOPs to confirm the folded re-plan / clarity-refinement / advisory
-     outcomes (the Clarity Gate's refined-body diff among them).
-
-   Under `--yes` each resolves as **approved**, and a `story` /
-   `borderline` triage verdict resolves to its **Recommended** branch rather
-   than prompting the three-way choice. **The interrogation itself runs
-   exactly one bounded pass**: no operator questions are asked — facts come
-   from the codebase, and every unresolved unknown lands in the one-pager's
-   **Key Assumptions** section instead of a question, so a headless driver
-   can never hang inside a free-form interrogation. On the `--idea` Epic
-   path this bounded pass IS the seed entry (#4496): `plan-context.js
-   --seed` replaces the idea-refinement prelude, and the one-pager is
-   authored in the same batched write as the spec artifacts. The verdict / clarity
-   scoring is still recorded in chat (one line); only the *wait* is
-   suppressed — the deterministic clarity *scoring* inside the
-   `plan-context.js` envelope always runs.
-2. **Gate #2 — the risk-routed pre-persist review.** When the authored risk
-   verdict routes to review (high risk, or the operator also passed
-   `--force-review`), [`helpers/plan-epic.md`](helpers/plan-epic.md) step 3
-   STOPs for operator approval of the assembled plan (spec, tickets, risk,
-   and `deliveryShape` in one view) before the persist CLI runs. Under
-   `--yes` this review auto-proceeds straight to the persist call, exactly
-   as on the low-risk auto-proceed branch.
-
-**Composition.** `--yes` is orthogonal to the other planning flags and
-composes cleanly:
-
-- With **`--allow-over-budget`**: `--yes` suppresses the gate *waits* while
-  `--allow-over-budget` still governs the `maxTickets` over-budget persist —
-  passing `--yes` alone does **not** waive the budget gate.
-- With the **risk-routed gate #2 skip**: when risk routing already
-  auto-proceeds the review (low-risk, no `--force-review`), `--yes` is a
-  no-op for that gate — it only *forces a proceed where the gate would
-  otherwise STOP*, it never *adds* a stop or relaxes any non-HITL validator.
-
-**`--yes` suppresses only the HITL operator *waits* above.** It does **not**
-relax any deterministic gate — the clarity scoring, the Tech Spec section
-gate, the ticket validator / file-assumption / DAG / budget gates, the
-inline readiness healthcheck, and the `agent::blocked` runtime pause all
-behave exactly as without the flag; it is an operator-input suppressor, not
-a validation override. A `--yes` run that hits one of those still fails
-closed. The smaller operator-input waits folded into the two gates — the
-duplicate-candidate review, the clarity refinement-diff confirm, and the
-advisory critic diffs — auto-proceed for the same headless reason.
+| Flag | Meaning |
+| --- | --- |
+| `--seed "<text>"` | Seed text for ideation. |
+| `--seed-file <path>` | Pre-authored notes / plan-seed path. |
+| `--tickets <ids>` | Comma-separated issue ids to analyze. |
+| `--force-review` | Force gate #2 operator review even when risk routing would skip it. |
+| `--allow-over-budget` | Permit a plan that exceeds `maxTickets` (rare N>1). |
+| `--yes` | Non-interactive: auto-proceed gate #1 and gate #2 HITL waits. |
+| `--dry-run` | Author + validate without GitHub writes. |
+
+## Default-single split policy
+
+Author **one Story** unless:
+
+1. the pieces have **near-zero overlap** (genuinely independent capabilities), or
+2. there is an **architectural seam** (different deployables, migration vs consumer).
+
+Coupled work stays one Story — decompose it inside `## Slicing` as
+intra-session checkpoints, not sibling tickets. When N>1, every acceptance
+criterion must belong to exactly one Story; `plan-persist` runs
+`assertAcceptancePartition` and refuses coupled splits.
+
+**N=1 is the lean path:** one authoring prompt, folded `## Spec` in the
+Story body, light risk/critic profile. Do not run Epic-scale decompose,
+clarity, or reconciler ceremony for a single Story.
 
 ## Procedure
 
-1. **Parse args.** Exactly one of `<epicId>`, `--idea`, `--from-notes`, or
-   `--body` must be present; anything else is a usage error naming the four
-   forms. A `--body` invocation routes to the story path (no triage).
-2. **Triage (idea path only).** Attended: run the
-   [`core/scope-triage`](../skills/core/scope-triage/SKILL.md) skill on the
-   seed. Record the verdict in chat (one line). **Under `--yes`, do not
-   Read the skill**: delegate straight to
-   [`helpers/plan-epic.md`](helpers/plan-epic.md)'s ideation entry — its
-   `plan-context.js --seed` envelope carries the rubric's verdict applied
-   CLI-side (`scopeTriage`), and a `story` / `borderline` verdict resolves
-   to the Recommended handoff from inside the helper (see
-   [`helpers/scope-triage-gate.md`](helpers/scope-triage-gate.md)).
-3. **Delegate.** Read the selected path helper **in full** and execute it
-   from its entry, forwarding the absorbed flags (including `--yes`). The
-   helper's steps, HITL gates, and scripts are the procedure — this router
-   adds no step content. When `--yes` is present, the two HITL STOP gates
-   auto-proceed per [Headless / non-interactive mode](#headless--non-interactive-mode---yes)
-   above; every deterministic gate still runs. **Under `--yes`, when the
-   helper content is already injected or present in context, execute it
-   directly — do not spend a separate read-in-full turn re-reading content
-   you already hold.**
-4. **Internal returns.** When a path helper would historically have handed
-   off to the other planning command, switch helpers in-place and continue;
-   surface the switch to the operator as a one-line note.
+### 1. Interrogate
+
+```bash
+node .agents/scripts/plan-context.js --seed "<seed>"
+# or: --seed-file <path>
+# or: --tickets 123,456
+```
+
+The envelope carries docs context, codebase snapshot, BDD probe, risk
+heuristics, the story-author system prompt, and `duplicates[]` (open
+**Stories** whose title/body overlap the seed — never Epics). Under
+`--yes`, do not ask free-form operator questions — unresolved unknowns
+land in Key Assumptions.
+
+**Gate #1** — STOP to confirm the sharpened plan intent and any
+duplicate-candidate review. Under `--yes`, auto-proceed.
+
+### 2. Author
+
+Write artifacts under `temp/plan-<slug>/`:
+
+- `stories.json` — array of Story tickets (**length 1 by default**). Each
+  body uses the canonical `story-body` shape (`## Goal`, optional
+  `## Slicing`, optional `## Spec`, `## Changes`, `## Acceptance`,
+  `## Verify`, …). The Story is the single executable document: put lean
+  approach prose in `## Spec`, binding criteria in top-level
+  `acceptance[]` / `verify[]` (persist syncs them into the body). Do not
+  restate Goal/Acceptance inside Spec. Over-budget Specs fail closed —
+  split the Story or tighten Spec; never write Specs under `docs/`.
+- `risk-verdict.json` — axes + summary only (**no `deliveryShape`**).
+- optional `techspec.md` — **N===1 only** convenience when Spec was authored
+  outside the Story JSON; persist folds it into that Story's `## Spec`.
+  Forbidden for N>1 (each Story must carry its own Spec).
+- optional `acceptance-manifest.json` — plan-level AC list for partition
+  coverage when N>1.
+
+For N=1, use the envelope `systemPrompts.story` and emit one cohesive
+Story. Split only under the policy above.
+
+### 3. Persist
+
+**Gate #2** — when risk routing requires review (or `--force-review`), STOP
+for operator approval of the assembled plan before persist. Under `--yes`, auto-proceed.
+N=1 low-risk plans typically skip this gate.
+
+```bash
+node .agents/scripts/plan-persist.js \
+  --stories temp/plan-<slug>/stories.json \
+  --risk-verdict temp/plan-<slug>/risk-verdict.json \
+  [--tech-spec temp/plan-<slug>/techspec.md] \
+  [--plan-dir temp/plan-<slug>] \
+  [--dry-run] \
+  [--force-review] \
+  [--allow-over-budget]
+```
+
+Persist creates Story issue(s) with `type::story` + `agent::ready`. When
+N>1 it also applies a shared `plan-run::<id>` label. Ends by naming
+`/deliver <storyId>` (or `/deliver --run <planRunId>` for N>1).
 
 ## Constraints
 
-- The plan→deliver boundary stays a hard stop: `/plan` never starts
-  delivery. It ends by naming the follow-up — `/deliver <epicId>` for a
-  planned Epic, `/deliver <storyId>` for a standalone Story.
-- The router never calls planning scripts directly; the path helpers own
-  every script invocation.
-- Checkout hygiene (branch sweep) and day-0 doc readiness are owned by
-  [`/git-cleanup`](git-cleanup.md) and `mandrel doctor` respectively —
-  `/plan` runs no boot sweep and no first-run preflight.
+- `/plan` never starts delivery.
+- No Epic ticket is opened. No reconciler. No `delivery::single` marker.
+- Duplicate search targets open Stories (`type::story`), not Epics.
+- Deterministic gates (ticket validator, split policy, reachability, budget)
+  still fail closed under `--yes`.
 
 ## See also
 
-- [`/deliver`](deliver.md) — the unified delivery entry point. Accepts a
-  single Epic, one or more standalone Stories, or any mix of ≥1 Epics and
-  standalone Stories — mixed sets compose a sequential segment plan.
-- [`helpers/plan-epic.md`](helpers/plan-epic.md) /
-  [`helpers/plan-story.md`](helpers/plan-story.md) — the path helpers.
+- [`/deliver`](deliver.md) — delivery entry point (`/deliver <storyId>`).
+- [`/audit-to-stories`](audit-to-stories.md) — audit findings → plan seed →
+  `/plan --seed-file`.
+- [`core/scope-triage`](../skills/core/scope-triage/SKILL.md) — optional
+  split-advisory notes only (no routing verdict).

package/.agents/workflows/qa-assist.md

@@ -45,16 +45,14 @@ never reimplements those decisions in prose.**
 > triage-ready finding without breaking stride — then, when the testing pass is
 > done, turned into a plan in one batch.
 >
-> **Persona**: `qa-engineer` · **Skills**: `core/qa-coverage-mapping`
+> **Skills**: `core/qa-coverage-mapping`
 
-## Persona
+## Role framing
 
-Adopt the **`qa-engineer`** persona
-([`.agents/personas/qa-engineer.md`](../personas/qa-engineer.md)) for the whole
-run. You are the quality gatekeeper: you value coverage, hermetic
-environments, deterministic results, and — per that persona's Golden Rule —
-you **never invent the signal**. The human owns what was observed; you enrich
-it. Re-read that persona file as your first action.
+You are the quality gatekeeper for this run: value coverage, hermetic
+environments, and deterministic results. **Never invent the signal** — the
+human owns what was observed; you enrich it. Apply the QA skills; there is
+no separate persona pack.
 
 ## Slash Command
 
@@ -69,7 +67,7 @@ it. Re-read that persona file as your first action.
 | `observation` | no       | `"sync-commands wipes .claude on a reused name"` | An optional first observation, or a brain dump of several. **Usually omitted** — the normal launch is a bare `/qa-assist`, which does Setup and then waits. If supplied, run Setup first, then feed it in as the first intake (splitting it if it carries multiple observations). |
 
 A bare `/qa-assist` is the expected entry point. **Do not** demand an
-observation up front and **do not** synthesize one — the `qa-engineer` Golden
+observation up front and **do not** synthesize one — the QA Golden
 Rule forbids inventing the signal. Set up, announce ready, and wait.
 
 ## Project contract
@@ -140,7 +138,7 @@ ledger is hard-gated.**
 
 Goal: become the operator's QA assistant before any observation arrives.
 
-1. Re-read the `qa-engineer` persona.
+1. Re-read the QA role framing and `core/qa-coverage-mapping` skill.
 2. **Load codebase context.** Read the files in `project.docsContextFiles`
    (architecture, decisions, patterns) and, when the testing touches UI/routing,
    `docs/style-guide.md` / `docs/web-routes.md`. This is the context you will
@@ -321,32 +319,28 @@ its transition is **explicitly operator-gated**.
    import { promoteFindings } from '../scripts/lib/findings/promote-finding.js';
    const { promotions } = await promoteFindings(ledgerItems, {
      searchIssues, // GitHub provider, open + closed
-     createStory, // tight cluster (≤2 surfaces): render seed → /plan --from-notes
-     createEpic, // broad cluster (>2 surfaces): render seed → /plan --idea
+     createStory, // tight cluster (≤2 surfaces): seed → /plan --seed-file
+     createEpic, // broad cluster (>2 surfaces): same /plan --seed-file path (may N>1)
    });
    ```
 
    - **Sizing is delegated, not decided in prose.** `promoteFindings` runs
      `clusterLedgerItems` + `targetForCluster`: a cluster spanning **≤2**
      distinct coverage surfaces routes to `createStory`; **>2** routes to
-     `createEpic`. Do not re-cluster, re-size, or re-dedup in the workflow —
+     `createEpic`. Neither port opens an Epic ticket — both chain
+     `/plan --seed-file`. Do not re-cluster, re-size, or re-dedup in the
+     workflow —
      [`route-finding.js`](../scripts/lib/findings/route-finding.js) /
      [`promote-finding.js`](../scripts/lib/findings/promote-finding.js) are the
      single implementation.
-   - **`createStory` (`/plan --from-notes`)** — render a **redacted**
-     `--from-notes` seed from the cluster (reuse the `/audit-to-stories`
-     Phase 5b notes shape; redaction already ran in Phase 2), **stamp the
+   - **`createStory` / `createEpic` (`/plan --seed-file`)** — render a
+     **redacted** plan seed from the cluster (reuse the `/audit-to-stories`
+     Phase 5a seed shape; redaction already ran in Phase 2), **stamp the
      cluster's `fingerprintFooter(sha)` verbatim into the seed body**, then
-     chain `/plan --from-notes <seed>`. The footer must survive into the issue
-     body the Story create path writes — it round-trips through
-     `story-plan.js --body <file> --dry-run` unchanged (asserted by the
-     deterministic round-trip test under `tests/`) so a later `routeFinding`
-     dedups the same finding instead of re-filing it.
-   - **`createEpic` (`/plan --idea`)** — carry the cluster's
-     `fingerprintFooter(sha)` into the `/plan --idea` seed, then chain
-     `/plan --idea <seed>`. **Known limitation (not solved here):**
-     per-child-Story fingerprint propagation through full Epic decomposition is
-     *not* guaranteed — the fingerprint is carried in the Epic seed only.
+     chain `/plan --seed-file <seed>`. Prefer one Story; split only under
+     the default-single policy. The footer must survive into the issue body
+     so a later `routeFinding` dedups the same finding instead of re-filing
+     it.
    - **A `file` disposition never opens a raw GitHub Issue.** Every `file`
      finding flows through `promoteFindings` → `/plan`; only `defer` (carry
      forward as backlog) and `dismiss` (non-actionable) skip the handoff.
@@ -359,8 +353,8 @@ its transition is **explicitly operator-gated**.
 
 After planning, summarize: the findings recorded, the route/promotion decisions
 (`new`/`update-existing`/`duplicate`/`regression-of-closed`), whether each
-cluster became a Story (`/plan --from-notes`) or Epic (`/plan --idea`), and any
-`defer` backlog a resumed session will pick up.
+cluster became a Story via `/plan --seed-file`, and any `defer` backlog a
+resumed session will pick up.
 
 ---
 
@@ -404,7 +398,7 @@ cluster became a Story (`/plan --from-notes`) or Epic (`/plan --idea`), and any
   are deterministic — never re-derive them in prose.
 - **Promote through `/plan`, never a raw Issue.** A `file`-dispositioned
   finding is promoted via `promoteFindings`, which chains into
-  [`/plan`](plan.md) (`--from-notes` for a tight cluster, `--idea` for a broad
+  [`/plan`](plan.md) (`--seed-file` for a tight cluster, `--seed` for a broad
   one) — mirroring [`/audit-to-stories`](audit-to-stories.md). `/qa-assist`
   never opens a bare GitHub Issue for a `file` finding. The cluster's
   `fingerprintFooter(sha)` is stamped verbatim into the seed so a future
@@ -413,7 +407,7 @@ cluster became a Story (`/plan --from-notes`) or Epic (`/plan --idea`), and any
 ## See also
 
 - [`/plan`](plan.md) — the planning pipeline `/qa-assist` chains into in
-  Phase 4 (`--from-notes` for a Story, `--idea` for an Epic). The plan→deliver
+  Phase 4 (`--seed-file` / `--seed`). The plan→deliver
   hard stop is preserved across the handoff.
 - [`/qa-explore`](qa-explore.md) — the agent-led sibling that drives a named
   surface and triages through the same `/plan` handoff.