mandrel 1.94.0 → 2.1.0

package/.agents/workflows/helpers/parallel-tooling.md

@@ -20,8 +20,8 @@ them in one assistant turn rather than serially. The host runtime executes
 the batch in parallel; serial calls cost N round-trips for no gain.
 
 - **Tool primitives:** `Read`, `Grep`, `Glob`, MCP `list_*` / `get_*` calls.
-- **When:** reading the Epic body (with its folded Tech Spec sections)
-  and Story body up front; grepping
+- **When:** reading the Story body (with its inline `## Spec`)
+  up front; grepping
   for multiple unrelated patterns; globbing several directory trees;
   fetching independent GitHub tickets.
 - **Anti-pattern:** sequential `Read` → wait → `Read` → wait → `Grep` chains
@@ -42,7 +42,7 @@ the full duration and blocks every other parallel opportunity.
   fetches, anything you would have prefixed with `nohup` in a terminal.
 - **Anti-pattern:** synchronous `Bash` with a 600 000 ms timeout used as a
   blocker — that pattern is reserved for scripts whose exit is the
-  signal-to-proceed (e.g., `story-init.js`'s per-tree install, which the
+  signal-to-proceed (e.g., `single-story-init.js`'s per-tree install, which the
   parent skill calls out explicitly).
 - **Don't poll with `sleep`:** `Monitor` returns on each stdout line. Loop
   on `until <condition>; do sleep 2; done` only when no event stream is

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

@@ -1,7 +1,7 @@
 ---
 description: >-
   Helper doc for the signals-view.js debug viewer. Renders the signals
-  span-tree for an Epic (and optionally a single Story) to the terminal.
+  span-tree for a run (and optionally a single Story) to the terminal.
   Read-only over `lib/signals/` — no remote writes, no state mutation, no
   auto-fixes. Dumb-terminal-safe (`console.log` only). Not a slash command —
   invoke the script directly when needed.
@@ -14,27 +14,27 @@ description: >-
 > (`lib/signals/`, writer, schema, detectors, NDJSON listeners) runs as
 > 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>]`.
+> Invoke the backing script: `node .agents/scripts/signals-view.js <run-id> [--story <id>]`.
 
 ## Overview
 
 `signals-view.js` is the operator-facing viewer for the consolidated
-signals stream. It reads `temp/epic-<eid>/stories/story-<sid>/signals.ndjson` via
+signals stream. It reads `temp/run-<id>/stories/story-<sid>/signals.ndjson` via
 [`lib/signals/read`](../../scripts/lib/signals/read.js), builds an
 in-memory span-tree via
 [`lib/signals/buildSpanTree`](../../scripts/lib/signals/span-tree.js), and
-prints an Epic → Story → Task → events tree to stdout.
+prints a run → Story → events tree to stdout.
 
-It is distinct from `diagnose-friction.js` (per-Task signal capture that
+It is distinct from `diagnose-friction.js` (per-Story signal capture that
 wraps a shell command) and from `diagnose.js` (read of the checks
 registry). This viewer is purely a formatter over an iterator — no
 GitHub I/O, no commit creation, no label transitions.
 
 ```text
-node .agents/scripts/signals-view.js <epic-id> [--story <id>]
-  → signals.read({ epic, story? })
+node .agents/scripts/signals-view.js <run-id> [--story <id>]
+  → signals.read({ run, story? })
   → buildSpanTree(asyncIterator)
-  → console.log lines (Epic → Story → Task → events)
+  → console.log lines (run → Story → events)
   → exit 0 (always; missing-file path prints a friendly message)
 ```
 
@@ -42,8 +42,8 @@ node .agents/scripts/signals-view.js <epic-id> [--story <id>]
 
 | Argument         | Required | Description                                                                                                                            |
 | ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
-| `<epic-id>`      | yes      | Positive integer Epic ID. The viewer resolves `temp/epic-<id>/` under the configured `project.paths.tempRoot`.                  |
-| `--story <id>`   | no       | Positive integer Story ID. When set, the printed tree is narrowed to a single Story subtree under the Epic.                            |
+| `<run-id>`       | yes      | Positive integer run ID. The viewer resolves `temp/run-<id>/` under the configured `project.paths.tempRoot`.                         |
+| `--story <id>`   | no       | Positive integer Story ID. When set, the printed tree is narrowed to a single Story subtree under the run.                            |
 
 ## Flags (test-only)
 
@@ -55,13 +55,13 @@ node .agents/scripts/signals-view.js <epic-id> [--story <id>]
 
 | Code | Meaning                                                                                       |
 | ---- | --------------------------------------------------------------------------------------------- |
-| `0`  | Happy path **or** missing signals file. The missing-file path prints a friendly message ("No signals found for Epic #N"), never a stack trace. |
-| `1`  | Bad arguments (non-integer `<epic-id>`, missing positional, malformed `--story`).             |
+| `0`  | Happy path **or** missing signals file. The missing-file path prints a friendly message ("No signals found for run #N"), never a stack trace. |
+| `1`  | Bad arguments (non-integer `<run-id>`, missing positional, malformed `--story`).              |
 
 ## Examples
 
 ```bash
-# Render every Story under Epic #1181.
+# Render every Story under run #1181.
 node .agents/scripts/signals-view.js 1181
 
 # Narrow to a single Story subtree.
@@ -69,15 +69,15 @@ node .agents/scripts/signals-view.js 1181 --story 1438
 
 # No signals yet — friendly message, exit 0.
 node .agents/scripts/signals-view.js 9999
-# → No signals found for Epic #9999.
+# → No signals found for run #9999.
 ```
 
 ## Phase steps
 
-1. Parse `<epic-id>` and optional `--story <id>` from the slash-command
+1. Parse `<run-id>` and optional `--story <id>` from the CLI
    arguments. Reject non-integer or non-positive inputs with exit 1 and
    the canonical usage line.
-2. Invoke `node .agents/scripts/signals-view.js <epic-id> [--story <id>]`
+2. Invoke `node .agents/scripts/signals-view.js <run-id> [--story <id>]`
    from the operator's working directory. The script resolves
    `tempRoot` from the project's `.agentrc.json` (or the framework
    default `'temp'`).

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

@@ -7,60 +7,60 @@ 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
 
-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.
+All knobs live under `delivery.worktreeIsolation` in `.agentrc.json`. The
+**key list, types, and accepted enum values are not restated here** — the
+runtime schema in `config-resolver.js` validates them and
+[`.agents/docs/configuration.md`](../../docs/configuration.md) is generated
+from it, so a copy in this file could only drift out of agreement with the
+thing that actually enforces it. Read the generated table for the shape.
+
+What that table cannot tell you is which knob to reach for, so this document
+covers the judgement instead, each in its own section below:
+
+- `enabled` — the master switch; see [Fallback: single-tree mode](#fallback-single-tree-mode).
+- `nodeModulesStrategy`, `primeFromPath`, `allowSymlinkOnWindows` — see
+  [node_modules strategies](#node_modules-strategies).
+- `root` — where worktrees materialize; see [Windows notes](#windows-notes)
+  for the long-path constraint on it.
+- `reapOnSuccess` — drives the **Reap** phase in the lifecycle table below.
+- `bootstrapFiles` — untracked, per-developer files (local env, MCP, and
+  `.agentrc.local.json` / `instructions.local.md` overrides) copied into each
+  new worktree, because a worktree checkout carries only tracked content and
+  would otherwise boot without the operator's local configuration.
+
+Config-load rejects unknown strategies, `root` values that escape the repo
+root, and shell-metacharacter injection in `root`.
 
 ## Lifecycle
 
 | 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 +78,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,26 +110,13 @@ 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, ...`.
+- The close output 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
@@ -242,9 +223,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
 
@@ -253,7 +234,7 @@ Symlink strategy:
   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.
+  warning locally.
   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
@@ -351,12 +332,11 @@ Pick single-tree mode when:
 
 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.
+- Each Story's diff is reviewed on its PR on GitHub (`story-<id>` → `main`);
+  no local branch accumulates a cumulative diff for review.
 - 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 Epic planning bodies and run the `helpers/code-review.md`
-  procedure.
+  place to 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.

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

@@ -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.