mandrel 1.57.0

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

@@ -0,0 +1,317 @@
+---
+description: >-
+  Per-story git worktree isolation model — configuration, lifecycle,
+  node_modules strategies, Windows notes, fallback mode, and human-reviewer
+  guidance.
+---
+
+# Worktree-per-Story Lifecycle
+
+Parallel epic execution can race when multiple story 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.
+
+This document is the operator and reviewer reference. See
+[`epic-deliver`](../epic-deliver.md) and [`story-deliver`](../story-deliver.md)
+for the broader execution flow and the Epic-229 Tech Spec for
+architectural rationale.
+
+## Configuration
+
+All knobs live under `delivery.worktreeIsolation` in `.agentrc.json`:
+
+```jsonc
+{
+  "orchestration": {
+    "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
+      "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)
+    },
+  },
+}
+```
+
+The schema is validated by `config-resolver.js`. Unknown strategies, `root`
+values that escape the repo root, and shell-metacharacter injection in `root`
+are all rejected at config-load time.
+
+## Lifecycle
+
+| 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.                                                                                       |
+| **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.                                                                                 |
+
+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.
+
+### Stale-lock sweep
+
+Even with per-story worktree isolation, the main repo's `.git/` dir is shared
+state — `git worktree add/remove/prune`, `fetch`, auto-gc, and VSCode's git
+extension all touch it. A crashed orchestrator can leave an orphaned
+`.git/index.lock` (or `HEAD.lock`, `packed-refs.lock`, per-worktree
+`index.lock`, etc.) that blocks the next run with a "another git process seems
+to be running" error.
+
+`sweepStaleLocks({ maxAgeMs = 300_000 })` removes well-known lock files whose
+mtime exceeds the age threshold. Fresh locks (belonging to a legitimate
+in-flight op) are skipped. It always runs immediately before `gc`, in the same
+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
+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.                              |
+| 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.   |
+
+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
+manifest via `dispatcher.js`) against the active epic. Running
+`/story-deliver <storyId>` on its own does **not** clean up orphan worktrees
+or stale locks.
+
+## 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/epic-plan-spec.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.
+
+[`drain-pending-cleanup.js`](../../scripts/drain-pending-cleanup.js)
+runs the standard drain *and* enumerates handle holders via
+PowerShell `Get-CimInstance Win32_Process`, terminating them with
+`taskkill /T /F` before re-trying.
+
+> **Not a slash command (decision overturned).** The drain is **not** a
+> `/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,
+> `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
+> `node .agents/scripts/drain-pending-cleanup.js`.
+
+### When it runs automatically
+
+| 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) |
+| 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, ...`.
+- `git worktree list` shows `.worktrees/story-N/` for a closed Story.
+- `npm run lint` fails because of a nested `biome.json` in a half-reaped
+  worktree. The `worktree-residue-biome` self-healing check detects this
+  failure mode.
+
+### Manual usage
+
+```bash
+# Default: drain + escalate (kill holders on Windows)
+node .agents/scripts/drain-pending-cleanup.js
+
+# Passive drain only — retry Stage 1 without killing anything
+node .agents/scripts/drain-pending-cleanup.js --no-escalate
+
+# Inspect what would be killed without acting
+node .agents/scripts/drain-pending-cleanup.js --dry-run
+
+# Override the worktree root (rare)
+node .agents/scripts/drain-pending-cleanup.js --worktree-root /tmp/wt
+```
+
+The script always exits 0 unless the config or runtime is broken; remaining
+entries are reported on stderr and re-enter the next sweep.
+
+### Escalation limitations
+
+Escalation matches process `ExecutablePath` and `CommandLine`. **Kernel-held
+handles are invisible to user-mode enumeration**:
+
+- **Windows Search indexer** (`searchindexer.exe`) — does not record the
+  worktree path in command line. Workaround: exclude `.worktrees/` in
+  Search Options, or wait for the indexer to release after ~5 min idle.
+- **Antivirus** (`MsMpEng.exe`, third-party AV) — same story. Add
+  `.worktrees/` to scan exclusions if this recurs.
+- **VSCode extension host** — files indexed by an open VSCode workspace.
+  Closing the workspace tab releases handles.
+
+When `findHoldersInPath()` returns `[]` for a stuck entry, the script
+emits a `no user-mode holders` warning and leaves the entry for the next
+sweep — by which time the indexer/AV has usually moved on.
+
+### Drain constraints
+
+- **Never** call `git worktree` directly from inside the drain helper —
+  always go through `pending-cleanup.js` / `force-drain.js`. They
+  enforce manifest atomicity and Stage-1/Stage-2/Stage-3 ordering.
+- **Never** widen `findHoldersInPath()` to kill processes outside the
+  worktree path. Match must be rooted at the worktree directory; a
+  loose match risks terminating unrelated user processes.
+- **Always** treat escalation as best-effort: PowerShell or `taskkill`
+  failures must degrade to "leave the entry in the manifest" rather
+  than throw — the next sweep retries.
+- **Always** preserve the `escalate: false` opt-out path so the
+  legacy `drainPendingCleanup` behaviour is reachable when an operator
+  needs to inspect without acting.
+
+### Last-resort manual recipe
+
+When even escalation can't clear an entry, the pre-`ff34fa9` recipe still
+works:
+
+```bash
+cd <main-checkout>
+node -e "require('fs').rmSync('.worktrees/story-<id>', {recursive:true,force:true})"
+git worktree prune
+git branch -D story-<id>
+git push origin --delete story-<id>
+```
+
+(Direct `rm -rf .worktrees/story-<id>` may be blocked by the global
+`Bash(rm -rf *)` deny hook. The Node `fs.rmSync` fallback above avoids
+that shell-pattern denial.)
+
+## `.agents` materialization
+
+`.agents/` is a regular tracked directory in every checkout — the framework
+repo tracks it directly, and npm-installed consumers materialize it via
+`mandrel sync`. Because it is not a git submodule, a per-story worktree
+carries no `.agents` gitlink, so `git worktree add` and `git worktree remove`
+need no special handling for it: the directory is created and reaped like any
+other tracked path.
+
+## node_modules strategies
+
+| Strategy       | Behavior                                                              | When to pick it                                                        |
+| -------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `per-worktree` | Each worktree runs its own `npm/pnpm install`. Default.               | Correct everywhere. Choose for small repos or when disk is cheap.      |
+| `symlink`      | Symlinks `<wt>/node_modules` → `<primeFromPath>/node_modules`.        | Large monorepos where install time dominates. Requires a primed donor. |
+| `pnpm-store`   | Each worktree still runs `pnpm install --frozen-lockfile`; savings come from the shared content-addressable store, not from skipping install. | Repos already on pnpm. Gets most of symlink's speed without fragility. |
+
+Symlink strategy:
+
+- `primeFromPath` (relative to repo root) must exist and contain `node_modules`.
+- On Windows, `allowSymlinkOnWindows: true` is required — symlink semantics vary
+  by Windows version and may demand admin rights.
+- `nodeModulesStrategy: "symlink"` without `primeFromPath` is a config error.
+
+`pnpm-store` strategy — install is **not** eliminated:
+
+- `installDependencies` in `lib/worktree/node-modules-strategy.js` runs
+  `pnpm install --frozen-lockfile` in every new worktree regardless of
+  strategy (symlink is the only strategy that truly skips install).
+- The speed-up vs. `per-worktree` comes from pnpm's global
+  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 `epic-plan-healthcheck.js` primes the store in the
+  main checkout to avoid paying that cost in parallel story windows.
+
+## Windows notes
+
+- **`core.longpaths=true`** is set on each new worktree to lift the 260-char
+  MAX_PATH ceiling. Some older build tools still truncate even with this flag;
+  the pre-flight warning below catches those cases before a build breaks.
+- **Long-path warning**: when `worktreePath.length + 80` exceeds
+  `windowsPathLengthWarnThreshold` (default 240), `WorktreeManager` emits a
+  warning locally and the dispatcher posts an `⚠️` comment on the Epic issue.
+  Relocate `delivery.worktreeIsolation.root` to a shorter prefix (e.g.
+  `C:\w`) if you see this.
+- **`packed-refs` contention**: two worktrees fetching concurrently can collide
+  on `.git/packed-refs.lock`. `gitFetchWithRetry` (`git-utils.js`) retries that
+  specific failure up to 3 times with 250/500/1000 ms backoff. Unrelated fetch
+  failures surface immediately — no retry.
+
+## Fallback: single-tree mode
+
+Set `delivery.worktreeIsolation.enabled: false` (or omit the block) to
+restore v5.5.1 single-tree behavior:
+
+- No `git worktree add` / `remove` calls.
+- `assert-branch.js` and `computeStoryWaves` focus-area serialization remain in
+  place as the primary race guards.
+- All existing v5.5.1 tests pass in this mode.
+
+Pick single-tree mode when:
+
+- The runner lacks disk/space for parallel `node_modules` trees and pnpm is
+  unavailable.
+- Windows path limits are unsolvable via the long-path guard.
+- You need a minimal-risk environment to debug an unrelated dispatcher issue.
+
+## Reviewer guidance
+
+Human reviewers should **keep using the main checkout** — not a worktree:
+
+- The Epic branch accumulates the cumulative diff for code review; that lives on
+  the main checkout, not in any per-story worktree.
+- Opening a worktree in an IDE can mislead: the working directory looks like the
+  main repo but carries a different HEAD. The main checkout is the canonical
+  place to read PRDs, Tech Specs, and run the `helpers/code-review.md`
+  procedure.
+- `git worktree list --porcelain` on the main checkout enumerates any still
+  in-flight story worktrees if you need to inspect one — prefer read-only
+  operations (`git log`, `git show`) when you do.
+
+## Constraint
+
+- **Never** call `git worktree` directly — always go through `WorktreeManager`.
+  It enforces `storyId`/`branch` validation and path-traversal checks.
+- **Only** let `WorktreeManager` pass `--force` after its safety checks have
+  established the Story worktree is removable and the plain Windows lock/cwd
+  retry has exhausted. Dirty unmerged work must still refuse deletion.
+- **Never** commit the `.worktrees/` directory. It must be gitignored.
+- **Always** use the main checkout for code review — not a per-story worktree.
+- **Always** respect `delivery.worktreeIsolation.enabled: false` as a
+  first-class fallback mode, not a degraded one. v5.5.1 single-tree guards
+  (`assert-branch.js`, focus-area serialization) remain the primary defense in
+  that mode.
+
+## Operator escape hatches
+
+- **Force-remove a worktree**: if a worktree is wedged beyond the framework's
+  bounded retry path (e.g. from a crashed agent), operators can manually run
+  `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.
+- **Inspect live worktrees**: `git worktree list --porcelain` on the main
+  checkout. Each block shows `worktree <path>` / `branch refs/heads/story-<id>`.

package/.agents/workflows/onboard.md

@@ -0,0 +1,207 @@
+---
+description: >-
+  Guided first-run onboarding for a freshly installed Mandrel. Detects the
+  consumer stack, offers to scaffold any missing docsContextFiles, runs
+  `mandrel doctor` as a readiness gate, and hands off to a started /epic-plan.
+  The whole path is designed to take about 15 minutes from a clean checkout to
+  a planned Epic.
+---
+
+# /onboard
+
+## Role
+
+Onboarding guide. You walk a first-time operator from a freshly installed
+Mandrel to their first planned Epic, composing the building blocks shipped by
+the guided-onboard Feature (#3514): stack detection, docs scaffolding, the
+`mandrel doctor` readiness check, and a started `/epic-plan` handoff.
+
+## Overview
+
+`/onboard` is the **guided first-successful-run path**. It sequences four
+phases that each lean on an already-shipped, independently tested building
+block, then hands the operator off to planning:
+
+```text
+/onboard
+  → Phase 1 — Detect stack          (lib/onboard/detect-stack.js#detectStack)
+  → Phase 2 — Offer docs scaffolding (lib/onboard/scaffold-docs.js#scaffoldDocs)
+  → Phase 3 — Readiness gate         (mandrel doctor → lib/cli/doctor.js)
+  → Phase 4 — Handoff to /epic-plan  (started, not auto-run)
+```
+
+Each phase is **advisory and resumable**: re-running `/onboard` on an
+already-onboarded project re-detects, re-checks, and offers the same handoff
+without duplicating any scaffolding (the scaffolder only writes files that are
+genuinely missing, and `mandrel doctor` is read-only).
+
+### When to use `/onboard`
+
+| Scenario | Command |
+| --- | --- |
+| First run after installing Mandrel into a project | `/onboard` |
+| Plan a new Epic once onboarded | `/epic-plan <epicId>` or `/epic-plan --idea "<seed>"` |
+| Deliver Epic-attached Stories | `/epic-deliver <epicId>` |
+
+## Prerequisites
+
+1. Mandrel installed and bootstrapped into the project. The zero-to-installed
+   path is `npx create-mandrel`, which installs the `mandrel`
+   package, runs `mandrel sync` to materialize the `.agents/` bundle, and then
+   execs `.agents/scripts/bootstrap.js` to provision the project (labels,
+   board, `.agentrc.json` seed). `/onboard` runs **after** that bootstrap
+   completes — it does not invoke `bootstrap.js` itself, so the coupling is
+   indirect: bootstrap owns first-time provisioning, `/onboard` owns the
+   guided first-successful-run. By the time you reach `/onboard`, the
+   `.agents/` bundle is present and `mandrel` resolves on the `PATH`.
+2. `GITHUB_TOKEN` available in the project's `.env` (Phase 3 checks this; the
+   token value is never echoed).
+
+## The ~15-minute first-successful-run path
+
+`/onboard` is tuned so a brand-new operator can go from a clean checkout to a
+planned Epic in roughly **15 minutes**. The budget breaks down as:
+
+| Step | Phase | Rough budget |
+| --- | --- | --- |
+| Detect the stack and confirm the report | Phase 1 | ~1 min |
+| Review the missing-docs offer and accept the scaffold | Phase 2 | ~3 min |
+| Run `mandrel doctor` and clear any ✘ checks | Phase 3 | ~5 min |
+| Start `/epic-plan` and describe the first Epic idea | Phase 4 | ~6 min |
+
+If any single phase blows its budget — most often a Phase 3 remedy such as
+authenticating `gh` or installing runtime deps — clear that one check and
+re-run `/onboard`; the earlier phases are cheap and idempotent, so re-running
+costs seconds.
+
+### Sample-repo pointer
+
+If you do not have a project to onboard yet and just want to see the path
+end-to-end, point `/onboard` at the **stack-detection sample-repo fixture**
+that ships with the framework. `detectStack` is fixture-driven by design (its
+filesystem facade reads a real directory), and the unit suite exercises it
+against an on-disk sample repo — see
+[`tests/onboard/detect-stack.test.js`](../../tests/onboard/detect-stack.test.js),
+which builds a sample repo with a lockfile, a `package.json`, and source files
+and asserts the detected package manager, test runner, and primary language.
+Use that fixture (or any small throwaway repo with a `package.json` and a few
+source files) as the target for a dry first run before onboarding a real
+project.
+
+## Phase 1 — Detect the stack
+
+Inspect the consumer repository root and report what Mandrel inferred before
+touching anything. Use the detection helper shipped by Story #3520:
+
+```bash
+node -e "import('./.agents/scripts/lib/onboard/detect-stack.js').then(m => console.log(JSON.stringify(m.detectStack(process.cwd()), null, 2)))"
+```
+
+`detectStack(root)` returns `{ packageManager, testRunner, primaryLanguage }`,
+each inferred from on-disk signals (lockfiles, `package.json`, source-file
+extensions) and `null` when no signal is found. Relay the report to the
+operator so they can confirm Mandrel understood the project. Detection is
+**read-only** — it never writes to disk — so a wrong guess is harmless and the
+operator can simply correct course in their `.agentrc.json` later.
+
+## Phase 2 — Offer to scaffold missing `docsContextFiles`
+
+Mandrel agents perform a **mandatory read** of every file listed in
+`project.docsContextFiles` before each task; a missing entry degrades every
+downstream run. Detect which are absent and offer to scaffold stubs, using the
+helper shipped by Story #3519:
+
+1. **Preview (no writes).** Detect the missing set first:
+
+   ```bash
+   node -e "import('./.agents/scripts/lib/onboard/scaffold-docs.js').then(m => console.log(JSON.stringify(m.scaffoldDocs({ write: false }), null, 2)))"
+   ```
+
+   `scaffoldDocs({ write: false })` returns `{ docsRoot, docsContextFiles,
+   missing, present, created }` without creating any files.
+
+2. **Offer.** Show the operator the `missing` list and ask whether to scaffold
+   stubs. If the list is empty, report "all docsContextFiles present" and skip
+   to Phase 3.
+
+3. **Scaffold (on acceptance).** When the operator accepts, write the stubs:
+
+   ```bash
+   node -e "import('./.agents/scripts/lib/onboard/scaffold-docs.js').then(m => console.log(JSON.stringify(m.scaffoldDocs({ write: true }), null, 2)))"
+   ```
+
+   Each missing file is seeded from a dedicated template under
+   `.agents/templates/docs/<name>` when one ships, otherwise from a generic
+   placeholder stub. The operator replaces the stub content with real docs
+   later; the point of the scaffold is that the mandatory-read never resolves
+   to a missing file.
+
+This phase is **idempotent**: the scaffolder only writes files that are
+actually absent, so re-running `/onboard` after a partial scaffold creates
+only the still-missing stubs.
+
+## Phase 3 — Readiness gate (`mandrel doctor`)
+
+Run the doctor as a **readiness gate** before handing off to planning:
+
+```bash
+mandrel doctor
+```
+
+`mandrel doctor` (see [`lib/cli/doctor.js`](../../lib/cli/doctor.js)) runs
+every check in the registry in order — `node-version`, `git-available`,
+`gh-available`, `github-token`, `gh-auth`, `commands-in-sync`, `runtime-deps`,
+`agents-materialized`, `agents-drift`, `version-current` — and prints a
+`✔`/`✘` line per check. Every failing check prints a `→ <remedy>` line, and
+the command exits:
+
+- **0** with `✅  Ready (N/N checks passed)` — proceed to Phase 4.
+- **non-zero** with `❌  Not ready (M/N checks failed)` — **stop**. Work
+  through the `→` remedies (e.g. authenticate `gh`, set `GITHUB_TOKEN`,
+  install runtime deps), then re-run `mandrel doctor` until it is green.
+
+Do **not** hand off to `/epic-plan` while the doctor is red — planning needs a
+working `gh` / `GITHUB_TOKEN` and a materialized `.agents/` bundle, exactly
+what the gate verifies. The `github-token` check never echoes the token value
+(security baseline § Secrets Management).
+
+## Phase 4 — Handoff to a started `/epic-plan`
+
+With a green readiness gate, hand the operator off to planning. `/onboard`
+**starts** the handoff — it surfaces the entry point and the idea-refinement
+path — but does **not** auto-run `/epic-plan`, because Epic planning authors
+GitHub artifacts and must stay under explicit operator control.
+
+Present the operator with the two `/epic-plan` entry shapes:
+
+- **From an idea** (no Epic exists yet):
+
+  ```text
+  /epic-plan --idea "<one-line description of the first thing to build>"
+  ```
+
+  This enters [`/epic-plan`](epic-plan.md) at Phase 1 (Idea Refinement),
+  which refines the seed into a PRD, Tech Spec, and a decomposed
+  Epic → Feature → Story backlog.
+
+- **From an existing Epic** (a `type::epic` issue already exists):
+
+  ```text
+  /epic-plan <epicId>
+  ```
+
+Stop here and let the operator invoke `/epic-plan` themselves. Once they have
+a planned Epic, the natural next step is `/epic-deliver <epicId>` to execute
+it — but that is beyond the onboarding path.
+
+## Constraints
+
+- **Read-before-write.** Phases 1 and 3 are read-only; Phase 2 writes only
+  files that are genuinely missing and only on explicit operator acceptance.
+- **Do not auto-run `/epic-plan`.** Phase 4 starts the handoff; the operator
+  invokes planning. Planning authors GitHub artifacts and stays under human
+  control.
+- **Never echo secrets.** The `github-token` check and any token-related
+  remedy must not print the token value.
+- **Stop on a red doctor.** A non-zero `mandrel doctor` exit blocks the
+  handoff until the operator clears the failing checks.