mandrel 1.59.0 → 1.61.0

package/.agents/workflows/{story-plan.md → helpers/plan-story.md}

@@ -6,46 +6,46 @@ description:
   /single-story-deliver.
 ---
 
-# /story-plan
+# helpers/plan-story — standalone-Story planning path (invoked by /plan)
 
 ## Overview
 
-`/story-plan` is the standalone counterpart to
-[`/epic-plan`](epic-plan.md) for Stories that are **not** attached to an
+`/plan` is the standalone counterpart to
+[`/plan`](plan-epic.md) for Stories that are **not** attached to an
 Epic. It closes the gap between "one-line idea" and "well-formed
-standalone Story body ready for [`/single-story-deliver`](helpers/single-story-deliver.md)"
+standalone Story body ready for [`/single-story-deliver`](single-story-deliver.md)"
 using the same `host LLM authors + Node wrapper persists` split as
-`/epic-plan`.
+`/plan`.
 
 ```text
-/story-plan --idea "<seed>"
+/plan --idea "<seed>"
   → story-plan.js --emit-context               (envelope: seed, template, dup candidates)
   → host LLM authors a draft Story body         (in chat, using the envelope)
   → operator confirms (HITL)
   → story-plan.js --body <file>                 (validate, gh issue create)
-  → "Next: /single-story-deliver <id>"
+  → "Next: /deliver <id>"
 ```
 
-**When to use `/story-plan` vs. `/epic-plan` Phase 8:**
+**The two paths of `/plan` — when each applies:**
 
-| Trait                | `/story-plan`                              | `/epic-plan` Phase 8                         |
+| Trait                | Standalone-Story path (this helper)        | Epic decomposition path (`helpers/plan-epic.md`) |
 | -------------------- | ------------------------------------------ | -------------------------------------------- |
-| Output               | One standalone Story Issue                 | Decomposed Feature/Story/Task hierarchy      |
+| Output               | One standalone Story Issue                 | Epic with child Stories                      |
 | Parent Epic          | None (no `Epic: #N` in body)               | Required                                     |
-| Downstream workflow  | `/single-story-deliver`                    | `/story-deliver` (per Story)                 |
-| Replan surface       | Out of scope (recreate manually if needed) | `/epic-plan --replan` regenerates everything |
-| Inbound route        | Direct, **or** an `/epic-plan` Phase 1.5 scope-triage handoff | Direct (`<epicId>` or `--idea`)         |
-| Outbound route       | Phase 2 may **escalate** an epic-sized draft to `/epic-plan --idea` (scope-triage handoff) | n/a — `/epic-plan` is already the Epic tier |
+| Downstream workflow  | `/deliver <storyId>`                       | `/deliver <epicId>`                          |
+| Replan surface       | Out of scope (recreate manually if needed) | `/plan <epicId> --force` regenerates the backlog |
+| Inbound route        | `--idea` with a `story` triage verdict, `--body`, **or** a scope-triage handoff from the Epic path | Direct (`<epicId>`, or `--idea` with an `epic` verdict) |
+| Outbound route       | Phase 2 may **escalate** an epic-sized draft to the Epic path (internal branch switch) | The story-sized advisory may **convert** a one-Story Epic to this path |
 
-If a Story-under-Epic needs replanning, use `/epic-plan --replan`. If you
+If a Story-under-Epic needs replanning, use `/plan <epicId> --force`. If you
 have a refactor, framework-maintenance idea, or any standalone unit of
 work, use this workflow.
 
-**Inbound from `/epic-plan` scope triage.** `/epic-plan` Phase 1.5 runs the
-[`core/scope-triage`](../skills/core/scope-triage/SKILL.md) rubric over the
+**Inbound from `/plan` scope triage.** `/plan` Phase 1.5 runs the
+[`core/scope-triage`](../../skills/core/scope-triage/SKILL.md) rubric over the
 sharpened one-pager. On a `story` / `borderline` verdict the operator may route
-the work here via `/story-plan --from-notes <path>`. That invocation is a
-**scope-triage handoff** — the triage decision is already made, so `/story-plan`
+the work here via `/plan --from-notes <path>`. That invocation is a
+**scope-triage handoff** — the triage decision is already made, so `/plan`
 MUST NOT re-triage it (the no-re-triage rule in the skill); it proceeds straight
 to authoring the standalone Story body from the handed-off one-pager.
 
@@ -54,20 +54,20 @@ to authoring the standalone Story body from the handed-off one-pager.
 1. `GITHUB_TOKEN` or `gh auth status` clean — `gh issue create` runs at
    persist time.
 2. The `type::story` label and the chosen `persona::*` label exist in the
-   repo. Run [`agents-bootstrap-github.js`](../scripts/agents-bootstrap-github.js)
+   repo. Run [`agents-bootstrap-github.js`](../../scripts/agents-bootstrap-github.js)
    once to provision them.
 
 ## Invocation shapes
 
 ```bash
 # Seed from an inline string:
-/story-plan --idea "rip out the unused TaskBodyMigrator export"
+/plan --idea "rip out the unused TaskBodyMigrator export"
 
 # Seed from a notes file:
-/story-plan --from-notes temp/single-story-2293-notes.md
+/plan --from-notes temp/single-story-2293-notes.md
 
 # Inspect the draft body without creating an Issue:
-/story-plan --dry-run --body temp/single-story-draft.md
+/plan --dry-run --body temp/single-story-draft.md
 ```
 
 ## Phase 1 — Emit Context
@@ -102,8 +102,8 @@ Envelope fields (`kind: "story-plan-context"`, `version: 1`):
 `refine.refine` is `true` when the seed is shorter than 200 characters
 (or empty). Pass `--refine` / `--no-refine` to override. When the
 envelope advises refinement, activate the
-[`core/idea-refinement`](../skills/core/idea-refinement/SKILL.md) skill
-before drafting the body — same skill `/epic-plan` Phase 1 drives.
+[`core/idea-refinement`](../../skills/core/idea-refinement/SKILL.md) skill
+before drafting the body — same skill `/plan` Phase 1 drives.
 
 ## Phase 2 — Host LLM Authors a Draft Body
 
@@ -120,19 +120,19 @@ Using the envelope above, draft a Story body that:
 
 Write the draft to `temp/single-story-draft.md`.
 
-### Scope-triage escalation gate (symmetric counterpart to `/epic-plan` Phase 1.5)
+### Scope-triage escalation gate (symmetric counterpart to `/plan` Phase 1.5)
 
 Once the draft body exists — and **only** then, because the seed alone is not
 an honest basis for a sizing judgment — run the
-[`core/scope-triage`](../skills/core/scope-triage/SKILL.md) rubric over the
+[`core/scope-triage`](../../skills/core/scope-triage/SKILL.md) rubric over the
 **drafted Story body** to catch an Epic-sized scope before it is persisted as a
-standalone Story. This is the outbound mirror of `/epic-plan` Phase 1.5's
+standalone Story. This is the outbound mirror of `/plan` Phase 1.5's
 inbound downgrade gate: the two planning entry points route toward each other
 instead of each silently accepting wrong-sized work.
 
-**Skip the gate entirely when `/story-plan` was entered via a scope-triage
-handoff** — i.e. from `/epic-plan` Phase 1.5 (the inbound route above) or the
-`/epic-plan` Phase 5.5 existing-Epic conversion path. A handoff is a triage
+**Skip the gate entirely when `/plan` was entered via a scope-triage
+handoff** — i.e. from `/plan` Phase 1.5 (the inbound route above) or the
+`/plan` Phase 5.5 existing-Epic conversion path. A handoff is a triage
 decision already made; re-running the rubric here would re-litigate a settled
 call and risk a ping-pong between the two workflows (the skill's no-re-triage
 rule).
@@ -141,7 +141,7 @@ Otherwise, activate the skill **by reference** — read its `SKILL.md` via the
 `Read` tool and apply its rubric; do **not** restate its sizing thresholds or
 copy its verdict prose here. The skill anchors its sizing judgment to
 `DELIVERABLE_GRANULARITY_GUIDANCE` / `DEFAULT_TASK_SIZING` in
-[`ticket-validator-sizing.js`](../scripts/lib/orchestration/ticket-validator-sizing.js)
+[`ticket-validator-sizing.js`](../../scripts/lib/orchestration/ticket-validator-sizing.js)
 and emits one verdict — `epic` | `story` | `borderline`. The verdict is
 host-LLM judgment: there is **no `--flag`**, no scorer, no schema, and no label
 transition behind it. (The `refine` heuristic in `story-plan.js` is unchanged —
@@ -153,7 +153,7 @@ add a second stop.
 
 Display the draft to the operator and **STOP**. Do not call the persist phase
 until the operator explicitly confirms the draft. This mirrors the HITL gate
-`/epic-plan` Phase 3 enforces before opening the Epic Issue. The scope-triage
+`/plan` Phase 3 enforces before opening the Epic Issue. The scope-triage
 verdict folds into this same stop:
 
 - **`story` verdict (or gate skipped via handoff)** → no extra prompt. The
@@ -162,12 +162,12 @@ verdict folds into this same stop:
 - **`epic` verdict** (multiple independent capabilities, a plausible
   sizing-ceiling breach, or a real dependency structure) → the confirmation
   prompt presents a **three-way operator choice**:
-  - **Recommended: escalate to `/epic-plan --idea`** (with the triage
+  - **Recommended: escalate to `/plan --idea`** (with the triage
     rationale) — persist the notes/draft to a notes file and hand off to
-    `/epic-plan --idea` (or `--from-notes <path>`), identifying the invocation
-    as a **scope-triage handoff** so `/epic-plan` skips its own Phase 1.5 gate
+    `/plan --idea` (or `--from-notes <path>`), identifying the invocation
+    as a **scope-triage handoff** so `/plan` skips its own Phase 1.5 gate
     (the skill's no-re-triage rule). Then **abandon the draft and exit
-    `/story-plan`** — no standalone Story is created.
+    `/plan`** — no standalone Story is created.
   - **Persist as a standalone Story anyway** — ignore the recommendation and
     proceed to Phase 3 with the draft unchanged. Being wrong in the `epic`
     direction is cheap to tolerate: if the operator persists an oversized Story,
@@ -212,22 +212,22 @@ exact `gh issue create` shape that would run.
 
 - **No `Epic: #N` references.** This is the standalone contract; persist
   fails fast if one is present. To attach a Story to an Epic, use
-  `/epic-plan` Phase 8 instead.
+  `/plan` Phase 8 instead.
 - **No external LLM APIs.** Mirrors the v5.6 contract: the host LLM does
   the authoring; the Node wrapper does the I/O.
 - **Idempotent.** Re-running `--emit-context` is safe. Re-running
   `--body` opens a new Issue (it is not aware of prior runs); use
   `--dry-run` first when iterating on the draft.
-- **Atomic by contract.** A Story is the leaf of the 3-tier hierarchy — it
+- **Atomic by contract.** A Story is the leaf of the 2-tier hierarchy — it
   has no child tickets. Its acceptance criteria and verification steps live
   inline on the Story body
-  ([`single-story-deliver.md`](helpers/single-story-deliver.md)).
+  ([`single-story-deliver.md`](single-story-deliver.md)).
 
 ## See also
 
-- [`/single-story-deliver`](helpers/single-story-deliver.md) — the consumer
+- [`/single-story-deliver`](single-story-deliver.md) — the consumer
   workflow that picks the Story up after this one creates it.
-- [`/epic-plan`](epic-plan.md) — the Epic-tier equivalent. Phases 1–4
+- [`/plan`](plan-epic.md) — the Epic-tier equivalent. Phases 1–4
   inspired the seed-capture + envelope-emit pattern used here.
-- [`core/idea-refinement`](../skills/core/idea-refinement/SKILL.md) —
+- [`core/idea-refinement`](../../skills/core/idea-refinement/SKILL.md) —
   optional pre-authoring skill activated when the seed is short.

package/.agents/workflows/helpers/signals.md

@@ -12,7 +12,7 @@ description: >-
 > **Helper, not a slash command.** Files under `workflows/helpers/` are not
 > projected into the mandrel plugin command tree. The signals subsystem itself
 > (`lib/signals/`, writer, schema, detectors, NDJSON listeners) runs as
-> part of the normal `/epic-deliver` machinery — this viewer is for
+> part of the normal `/deliver` machinery — this viewer is for
 > ad-hoc debugging when you need to inspect the span-tree directly.
 > Invoke the backing script: `node .agents/scripts/signals-view.js <epic-id> [--story <id>]`.
 

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

@@ -10,7 +10,7 @@ description:
 ## Overview
 
 `/single-story-deliver` is the standalone counterpart to
-[`/story-deliver`](../story-deliver.md). Use it for a Story that is **not**
+[`/deliver`](deliver-stories.md). Use it for a Story that is **not**
 attached to an Epic — refactors carved out of closed Epics, framework
 maintenance, or any work small enough that the Epic-Centric ceremony
 (PRD + Tech Spec + decomposition + dispatch manifest + cascade) would be
@@ -25,19 +25,19 @@ overhead rather than help.
   → single-story-confirm-merge.js  (PR merged → agent::done, issue closes)
 ```
 
-**When to use `/single-story-deliver` vs. `/epic-deliver`:**
+**When to use `/single-story-deliver` vs. `/deliver`:**
 
-| Trait                         | `/single-story-deliver`                              | `/epic-deliver`                                         |
+| Trait                         | `/single-story-deliver`                              | `/deliver`                                         |
 | ----------------------------- | ---------------------------------------------------- | ------------------------------------------------------- |
 | Parent Epic                   | None (no `Epic: #N` in body)                         | Required (`Epic: #N` in body)                           |
 | Branch base                   | `project.baseBranch` (default `main`)          | `epic/<epicId>`                                         |
 | Merge target                  | `main` via PR                                        | `epic/<epicId>` via `--no-ff` merge                     |
-| Cascade up to Feature/Epic    | No                                                   | Yes                                                     |
+| Epic-branch integration       | No                                                   | Yes — merged into `epic/<epicId>` at close              |
 | Dispatch manifest interaction | None                                                 | Read at init, regenerated at close                      |
 | Story scope                   | Inline `acceptance[]` / `verify[]` on the Story body | Inline `acceptance[]` / `verify[]` on the Story body    |
 
-If the Story has an `Epic: #N` reference, use `/epic-deliver`. If it
-doesn't, use this workflow (or `/story-deliver` for several standalone
+If the Story has an `Epic: #N` reference, use `/deliver`. If it
+doesn't, use this workflow (or `/deliver` for several standalone
 Stories at once).
 
 ## Prerequisites
@@ -82,7 +82,7 @@ the Story to `agent::executing`.
 > is the only guard against a concurrent `single-story-init` clobbering an
 > in-flight run.
 >
-> **Fail-closed (audit #3513).** Unlike `/epic-deliver`, the standalone path
+> **Fail-closed (audit #3513).** Unlike `/deliver`, the standalone path
 > has **no Epic-scoped lifecycle ledger** to read a per-owner
 > `story.heartbeat` from, so there is no live-heartbeat source to decide
 > whether a foreign claim is stale. Rather than silently reclaim every
@@ -290,7 +290,7 @@ The script:
    `gh pr merge <prNumber> --auto --squash --delete-branch`. Once CI's
    required checks turn green, GitHub squash-merges the PR and deletes
    the source branch — the operator does not need to babysit the merge
-   button. Mirrors the `/epic-deliver` finalize path. Failure is
+   button. Mirrors the `/deliver` finalize path. Failure is
    non-fatal: the operator retains the manual merge surface in the
    GitHub UI. Pass `--no-auto-merge` to opt out when the PR needs a
    pre-merge eyeball.
@@ -614,7 +614,7 @@ safe.
   invoking from inside a worktree (worktree-local branch deletion fails
   when run from inside the worktree).
 - **Handoff discipline — report state, not process.** When you hand back to
-  your caller (the `/story-deliver` aggregator or the interactive operator),
+  your caller (the `/deliver` aggregator or the interactive operator),
   report essential terminal state only: the Story branch, the closing commit
   SHA, what changed, and what was verified. Mirror the fields the close
   pipeline already emits (`single-story-close.js` / `story-phase.js`
@@ -632,6 +632,6 @@ safe.
 
 ## See also
 
-- [`/story-deliver`](../story-deliver.md) — several standalone Stories at
+- [`/deliver`](deliver-stories.md) — several standalone Stories at
   once (dependency-aware waves).
-- [`/epic-deliver`](../epic-deliver.md) — full Epic wave loop.
+- [`/deliver`](deliver-epic.md) — full Epic wave loop.

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

@@ -14,7 +14,7 @@ into the wrong commit. Epic #229 moves each dispatched story into its own
 activity are isolated per-story. The main checkout stays quiet.
 
 This document is the operator and reviewer reference. See
-[`epic-deliver`](../epic-deliver.md) and [`story-deliver`](../story-deliver.md)
+[`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.
 
@@ -47,10 +47,10 @@ are all rejected at config-load time.
 
 | Phase           | When                                                                          | What happens                                                                                                                                                |
 | --------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Sweep**       | Dispatch-manifest build (`/epic-plan`) and `/epic-deliver` | Stale `*.lock` files under `.git/` (older than 5 min) are removed before GC.                                                                                |
-| **GC**          | Dispatch-manifest build (`/epic-plan`) and `/epic-deliver` | Orphan `.worktrees/story-*` whose stories are closed are reaped if clean.                                                                                   |
-| **Force-drain** | `/epic-plan` boot (`worktree-sweep.js` via `drainPendingCleanupAtBoot`), `story-close` post-merge (`forceDrainPendingCleanup`), `/epic-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 `/story-deliver`)                  | `git worktree add .worktrees/story-<id>/` on the `story-<id>` branch.                                                                                       |
+| **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.                                                                                 |
 
@@ -79,23 +79,23 @@ 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 `/story-deliver`) does not invoke them. The full
+`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 (`/epic-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 (`/epic-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 (`/story-deliver` close)                                  | `story-close.js` (`drainPendingCleanupAfterClose`) | ❌ No       | ❌ No    | ✅ Yes       | Runs after the post-merge pipeline when worktree isolation is enabled.                              |
+| 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 (`/story-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 (`/epic-deliver`)                              | `/epic-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 `/epic-plan` and `/epic-deliver` paths.   |
+| 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 `/epic-plan` (or rebuilding the dispatch
+the most direct path is re-running `/plan` (or rebuilding the dispatch
 manifest via `dispatcher.js`) against the active epic. Running
-`/story-deliver <storyId>` on its own does **not** clean up orphan worktrees
+`/deliver <storyId>` on its own does **not** clean up orphan worktrees
 or stale locks.
 
 ## Draining the pending-cleanup ledger
@@ -116,7 +116,7 @@ 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 — `/epic-deliver` runner Phase 7,
+> 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
@@ -126,8 +126,8 @@ PowerShell `Get-CimInstance Win32_Process`, terminating them with
 
 | Trigger          | Caller                                                                       |
 | ---------------- | ---------------------------------------------------------------------------- |
-| `/epic-deliver`    | [`Cleaner` lifecycle listener](../../scripts/lib/orchestration/lifecycle/listeners/cleaner.js) at the close-tail cleanup phase (before `wm.gc()`)   |
-| `/epic-plan`     | [`drainPendingCleanupAtBoot`](../../scripts/epic-plan-spec.js) → [`worktree-sweep.js`](../../scripts/lib/orchestration/plan-runner/worktree-sweep.js) |
+| `/deliver`    | [`Cleaner` lifecycle listener](../../scripts/lib/orchestration/lifecycle/listeners/cleaner.js) at the close-tail cleanup phase (before `wm.gc()`)   |
+| `/plan`     | [`drainPendingCleanupAtBoot`](../../scripts/epic-plan-spec.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
@@ -312,6 +312,6 @@ Human reviewers should **keep using the main checkout** — not a worktree:
   `git worktree remove --force <path>`. Confirm there is no uncommitted work
   first.
 - **Disable temporarily**: flip `enabled: false` in `.agentrc.json`. The next
-  `/story-deliver` skips worktree creation entirely.
+  `/deliver` skips worktree creation entirely.
 - **Inspect live worktrees**: `git worktree list --porcelain` on the main
   checkout. Each block shows `worktree <path>` / `branch refs/heads/story-<id>`.

package/.agents/workflows/plan.md

@@ -0,0 +1,131 @@
+---
+description:
+  Unified planning entry point. Routes a seed idea (via scope triage) or an
+  existing Epic ID to the right planning path — the full Epic pipeline
+  (PRD, Tech Spec, Acceptance Spec, decomposition) or the standalone-Story
+  authoring path — and absorbs every planning flag.
+---
+
+# /plan [Epic ID] | --idea "<seed>" | --from-notes <path>
+
+## Role
+
+Router. `/plan` owns argument parsing and path selection only — all phase
+content lives in the two path helpers:
+
+- [`helpers/plan-epic.md`](helpers/plan-epic.md) — the full Epic planning
+  pipeline (PRD, Tech Spec, Acceptance Spec, work breakdown, healthcheck,
+  handoff).
+- [`helpers/plan-story.md`](helpers/plan-story.md) — the standalone-Story
+  authoring path (context envelope → host-LLM draft → HITL → issue create).
+
+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.
+
+## Inputs
+
+| Invocation | Behavior |
+| --- | --- |
+| `/plan --idea "<seed>"` | Ideation → **scope triage**. Verdict `epic` → run [`helpers/plan-epic.md`](helpers/plan-epic.md) from Phase 1 (Idea Refinement). 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 Phase 5. 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. |
+
+## Flags
+
+`/plan` absorbs every flag the two retired planning commands accepted and
+forwards them 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 | Close + recreate an existing ticket tree on re-plan. |
+| `--force-review` | Epic | Force the operator review gate even when risk routing would skip it. |
+| `--allow-over-budget` | Epic | Permit a decomposition that exceeds `planning.maxTickets`. |
+| `--steal` | Epic | Forcibly transfer a foreign Epic-lease. |
+| `--dry-run` | both | Author + validate without GitHub writes. |
+| `--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 now
+an **internal branch switch** inside this router: same skills, same
+helpers, no command hop and no operator re-entry.
+
+## First-run preflight
+
+Before routing to a path helper, run a **first-run preflight** to catch
+common day-0 issues that would silently degrade every downstream task.
+
+### When the preflight fires
+
+The preflight runs when **any** of these is true:
+
+1. One or more `project.docsContextFiles` entries are absent under the
+   configured `docsRoot`.
+2. One or more present `docsContextFiles` still carry the
+   `<!-- MANDREL:STUB -->` marker (i.e. they are un-edited scaffolded stubs).
+3. The last `mandrel doctor` verdict cached in `temp/doctor-result.json`
+   records `"verdict": "unready"`. An **absent** cache file is no signal —
+   doctor may simply never have run; only an explicit recorded unready
+   verdict fires this signal.
+
+### Preflight procedure
+
+1. **Detect the condition.** Check the three signals above. When none is
+   true, skip the preflight entirely — no operator interaction, no delay.
+2. **Offer to flesh out docs.** Summarize the found condition to the
+   operator (e.g. "3 docsContextFiles are missing" or "architecture.md
+   still carries the stub marker") and ask:
+   > *Do you want to flesh out these docs from the codebase before planning?
+   > [y/N]*
+3. **On acceptance.** Walk through each affected file, read relevant
+   codebase artifacts (source files, README, existing docs), and write real
+   content to replace the stub. Then re-run `mandrel doctor` to confirm
+   readiness. If doctor passes, proceed to routing.
+4. **On decline.** Log one line:
+   > *[plan] Proceeding with degraded doc context — planning quality may be
+   > reduced.*
+   Then continue to the normal routing procedure below.
+
+The preflight is **never a hard stop** — declining continues planning with a
+noted degradation. It only fires when there is a genuine signal (missing or
+stubbed docs, or an unready doctor verdict).
+
+## 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. **First-run preflight.** Run the preflight above. Skip when all signals
+   are clear (healthy project).
+3. **Triage (idea path only).** Run the
+   [`core/scope-triage`](../skills/core/scope-triage/SKILL.md) skill on the
+   seed. Record the verdict in chat (one line).
+4. **Delegate.** Read the selected path helper **in full** and execute it
+   from its entry phase, forwarding the absorbed flags. The helper's phase
+   numbering, HITL gates, and scripts are unchanged — this router adds no
+   phase content.
+5. **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.
+
+## 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.
+
+## See also
+
+- [`/deliver`](deliver.md) — the unified delivery entry point.
+- [`helpers/plan-epic.md`](helpers/plan-epic.md) /
+  [`helpers/plan-story.md`](helpers/plan-story.md) — the path helpers.

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

@@ -33,7 +33,7 @@ resolution, redaction, coverage verdict, missing-test proposal, classification,
 and dedup/route decisions. The agent never invents those decisions in prose.
 
 > **When to run**: ad-hoc agent-driven exploration of a freshly delivered Story
-> or Feature, a regression sweep over a risky surface before `/epic-deliver`, or
+> or Feature, a regression sweep over a risky surface before `/deliver`, or
 > a structured agent-driven bug-hunt the operator wants captured into a
 > triageable ledger.
 >

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

@@ -22,7 +22,7 @@ console filtering.
 
 > **When to run**: During sprint testing to exercise a targeted slice of the
 > acceptance suite (a feature, a tag expression, or a domain), for regression
-> passes before `/epic-deliver`, or on demand while debugging a Story's
+> passes before `/deliver`, or on demand while debugging a Story's
 > user-visible behavior in a live browser.
 >
 > **Persona**: `qa-engineer` · **Skills**: `stack/qa/gherkin-authoring`,

package/README.md

@@ -25,37 +25,31 @@ provisions both as part of a cold start (`git init` → `gh repo create --push`
   provisioning, grant the scope with `gh auth refresh -s project` (re-auth
   in the browser when prompted) before running `bootstrap.js`.
 
-See the [Compatibility matrix](docs/upgrade-major.md#compatibility-matrix)
-section of `docs/upgrade-major.md` for the supported OS / Node /
-package-manager combinations.
-
 ## Quickstart
 
-The canonical cold-start path is one command, then two slash
-commands inside Claude Code:
+The canonical cold-start path is one command, then one slash command:
 
 ```bash
-npx mandrel init        # install mandrel → sync → prompt → bootstrap
+npx mandrel init        # install mandrel → sync → prompt → bootstrap → onboarding tail → /plan handoff
 ```
 
 ```text
 # then, inside Claude Code (commands load from .claude/commands/):
-/onboard            # guided first run: stack detect → docs → doctor → /epic-plan
-/epic-plan          # ideation -> PRD/Tech Spec -> Epic/Feature/Story hierarchy
+/plan          # ideation -> PRD/Tech Spec -> Epic with child Stories
 ```
 
 `npx mandrel init` installs `mandrel` (when `./.agents/` is absent),
 materializes it via `mandrel sync`, then asks whether to **configure now**
-(option 1 → runs `node .agents/scripts/bootstrap.js`, forwarding any flags you
-pass) or stop at **just the files** (option 2 → re-run `mandrel init` any time
-to configure). Pass `--assume-yes` for a non-interactive run that proceeds
-straight to configure (and forwards the flag to bootstrap). When `./.agents/`
-is already present (you ran `npm install mandrel` first), `init` skips the
-install/sync and goes straight to the prompt. `/onboard` then walks you from a
-clean checkout to a planned Epic (stack detection, docs scaffolding, a
-`mandrel doctor` readiness gate, and a started `/epic-plan`). Once you have a
-planned Epic, deliver it with `/epic-deliver <id>` (wave loop → validation →
-review → retro → open PR).
+(option 1 → runs `bootstrap.js`, then the onboarding tail: stack detection,
+docs scaffolding offer, `mandrel doctor` readiness gate, and a `/plan`
+handoff) or stop at **just the files** (option 2 → re-run `mandrel init`
+any time to configure). Pass `--assume-yes` for a non-interactive run that
+proceeds straight to configure (and forwards the flag to bootstrap). When
+`./.agents/` is already present (you ran `npm install mandrel` first), `init`
+skips the install/sync and goes straight to the prompt. Once `mandrel init`
+completes, you land at the `/plan` handoff — run `/plan --idea "<seed>"` to
+start planning your first Epic, then deliver it with `/deliver <id>` (wave
+loop → validation → review → retro → open PR).
 
 ### Manual equivalent
 
@@ -108,29 +102,23 @@ npx mandrel update
 
 1. **Resolve** the newest published version (a `npm view mandrel
    version` registry probe) and the currently installed version.
-2. **Major gate** — if the newest version crosses a major boundary
-   (e.g. `1.x → 2.0`), the command declines, prints a pointer to
-   [`docs/upgrade-major.md`](docs/upgrade-major.md), and exits non-zero
-   without touching anything. Re-run with `--major` to apply it.
-3. **No-op short-circuit** — already on the newest version ⇒ nothing to do.
-4. **Install** the target version with the project's package manager —
+2. **No-op short-circuit** — already on the newest version ⇒ nothing to do.
+3. **Install** the target version with the project's package manager —
    auto-detected from the lockfile (`pnpm-lock.yaml` ⇒ pnpm, `yarn.lock` ⇒
    yarn, otherwise npm) so the bump lands in your real lockfile. The
    dependency bump is left **staged** on disk — `mandrel update` performs no
    `git add` / `git commit`, so you review and commit the lockfile change
    yourself.
-5. **Sync** — re-materialize `./.agents/` from the freshly installed payload.
-6. **Migrate** — apply version-keyed migration steps for the crossed range.
-7. **Doctor** — run the check registry to verify the resulting install.
-8. **Surface** the target changelog section.
+4. **Sync** — re-materialize `./.agents/` from the freshly installed payload.
+5. **Migrate** — apply version-keyed migration steps for the crossed range.
+6. **Doctor** — run the check registry to verify the resulting install.
+7. **Surface** the target changelog section.
 
 ### Flags
 
 - `--dry-run` — print the resolved target version and the ordered step
   plan, then exit. No dependency is bumped, no file is written, no seam
   runs.
-- `--major` — apply a major-version crossing that the gate would otherwise
-  refuse. Review [`docs/upgrade-major.md`](docs/upgrade-major.md) first.
 - `--install-cmd "<cmd>"` — override the auto-detected install command. The
   package manager is normally detected from your lockfile
   (`pnpm-lock.yaml` ⇒ `pnpm add -D …`, `yarn.lock` ⇒ `yarn add -D …`,
@@ -150,14 +138,6 @@ npx mandrel sync                        # re-materialize ./.agents/
 npx mandrel doctor                      # verify the install
 ```
 
-### Migrating from `@mandrelai/agents`
-
-The framework package was renamed from the scoped `@mandrelai/agents` to the
-unscoped `mandrel`. Already on the old name? `mandrel update` does **not**
-auto-migrate (it resolves the package by name), so make the one-time manual
-hop documented in
-[`docs/migrate-mandrelai-to-mandrel.md`](docs/migrate-mandrelai-to-mandrel.md).
-
 ## Contributors
 
 Only `.agents/` is distributed to consumers — it ships inside the