mandrel 1.60.0 → 1.62.0

package/.agents/workflows/deliver.md

@@ -1,17 +1,19 @@
 ---
 description:
   Unified delivery entry point. Inspects the ticket type(s) and
-  Epic-reference state of the supplied IDs, then routes to the Epic wave
-  loop or the standalone multi-Story fan-out — preserving every flag and
-  the parallel-delivery contract of the retired commands.
+  Epic-reference state of the supplied IDs, composes a sequential segment
+  plan over any mix of Epics and standalone Stories, then delegates each
+  segment to the Epic wave loop or the standalone multi-Story fan-out —
+  preserving every flag and the parallel-delivery contract of the retired
+  commands.
 ---
 
-# /deliver [Epic ID] | [Story IDs...]
+# /deliver [Epic IDs...] | [Story IDs...]
 
 ## Role
 
-Router. `/deliver` owns input classification and path selection only — all
-phase content lives in the two path helpers:
+Router. `/deliver` owns input classification, segment-plan composition, and
+path selection only — all phase content lives in the two path helpers:
 
 - [`helpers/deliver-epic.md`](helpers/deliver-epic.md) — the full Epic
   delivery loop (preflight, wave loop fanning out
@@ -30,20 +32,67 @@ reference) before routing:
 
 | Input | Route |
 | --- | --- |
-| Exactly one `type::epic` ID | **Epic path** — run [`helpers/deliver-epic.md`](helpers/deliver-epic.md) Phases 1–9 unchanged. |
-| One or more `type::story` IDs, none carrying an `Epic: #N` reference | **Standalone path** — run [`helpers/deliver-stories.md`](helpers/deliver-stories.md) Phases 0–3. |
-| Any Story carrying an `Epic: #N` reference | **Error**, naming the fix: `Story #<id> belongs to Epic #<n> — run /deliver <n>`. |
-| Mixed Epic + Story IDs, or more than one Epic | **Error**: separate invocations — one `/deliver <epicId>` per Epic, one `/deliver <id> [<id>...]` for the standalone set. |
-
-## Flags (forwarded per path)
+| Exactly one `type::epic` ID | **Epic path** — run [`helpers/deliver-epic.md`](helpers/deliver-epic.md) Phases 1–9 unchanged (single-segment plan; no confirmation prompt). |
+| One or more `type::story` IDs, none carrying an `Epic: #N` reference | **Standalone path** — run [`helpers/deliver-stories.md`](helpers/deliver-stories.md) Phases 0–3 (single-segment plan; no confirmation prompt). |
+| Any combination of ≥1 `type::epic` IDs and ≥0 standalone `type::story` IDs | **Segment plan** — compose and execute the sequential segment plan below. |
+| Any Story carrying an `Epic: #N` reference (alone or mixed into an otherwise-valid set) | **Error**, naming every affected ID and the fix: `Story #<id> belongs to Epic #<n> — run /deliver <n>`. |
+
+Per-ID classification is unchanged: fetch the `type::*` label and probe the
+body for an `Epic: #N` reference before routing. Never guess a route.
+
+## Segment plan (mixed / multi-Epic input)
+
+When the supplied IDs span more than one Epic, or mix Epics with standalone
+Stories, the router composes a **segment plan** and executes the segments
+**strictly sequentially**:
+
+1. **Standalone segment first** (when any standalone Story IDs are
+   present): the full standalone-Story set forms **one** segment,
+   delivered via [`helpers/deliver-stories.md`](helpers/deliver-stories.md)
+   Phases 0–3 unchanged. It runs first because it is fast, each Story
+   merges to `main` independently, and each subsequent Epic segment's
+   Phase 7.0 base-sync then integrates those merges naturally instead of
+   the Epic PR opening behind base.
+2. **Epic segments in input order**: each `type::epic` ID forms its own
+   segment, delivered via
+   [`helpers/deliver-epic.md`](helpers/deliver-epic.md) Phases 1–9
+   unchanged.
+
+Sequential execution is a deliberate design decision: the Epic path assumes
+a single main checkout (prepare's checkout guard, Phase 7.0
+`git checkout epic/<id>`), holds a per-Epic lease, serializes same-machine
+sessions via `epic-merge-lock.js`, and constrains dispatch to one wave at a
+time. Segments are never interleaved or parallelized; running them one at a
+time keeps both helpers' machinery untouched.
+
+**Confirmation gate.** When the composed plan has more than one segment,
+present it to the operator before dispatching — the segments, the IDs in
+each, and the execution order — and wait for confirmation. `--yes`
+suppresses this prompt. Single-segment plans route directly with today's
+behavior (no new prompt; the standalone path's own Phase 1 confirmation
+still applies as before).
+
+**Failure policy.** A segment that ends non-complete (blocked, failed, or
+halted at a gate) **stops the run** — no subsequent segment dispatches.
+Report the terminal state: which segments completed, which segment halted
+(and why), and which segments never started. Name the resume command:
+re-running `/deliver` with the same IDs — both path helpers short-circuit
+already-done work (the Epic path resumes idempotently from its checkpoint;
+merged standalone Stories no-op).
+
+## Flags (scoped per segment)
 
 | Path | Flags |
 | --- | --- |
 | Epic | `--skip-epic-audit`, `--skip-code-review`, `--skip-retro`, `--full-retro`, `--steal`, `--as <handle>` |
 | Story | `--dep <from>:<to>`, `--yes`, `--concurrency <n>` |
 
-A flag passed to the wrong path is reported once as a no-op warning and
-ignored — never an error.
+In a segment plan, Epic-path flags apply to **every** Epic segment;
+Story-path flags apply to the standalone segment. `--yes` additionally
+suppresses the router's segment-plan confirmation gate above. A flag with
+no applicable segment in the plan is reported once as a no-op warning and
+ignored — never an error (the existing convention, restated for segment
+plans).
 
 **Multi-Story parallel contract (preserved verbatim).**
 
@@ -55,31 +104,43 @@ behaves exactly as the retired multi-Story command did: the same
 `stories-wave-tick.js` wave plan, the same operator confirmation gate
 (suppressed by `--yes`), and the same parallel fan-out — one Agent call per
 Story per wave, capped by the resolved `concurrencyCap` — to
-[`helpers/single-story-deliver`](helpers/single-story-deliver.md).
+[`helpers/single-story-deliver`](helpers/single-story-deliver.md). The
+parallelism lives **inside** the standalone segment; segments themselves
+remain strictly sequential.
 
 ## Procedure
 
 1. **Parse args.** At least one positive-integer ID is required.
 2. **Classify.** Fetch each ticket's labels + body and apply the input
-   matrix above. Refuse ambiguous input with the matrix's error messages —
-   never guess a route.
-3. **Delegate.** Read the selected path helper **in full** and execute it
-   from its entry phase, forwarding the absorbed flags. The helper's phase
-   numbering, watchdogs, gates, and scripts are unchanged — this router
-   adds no phase content.
+   matrix above. Any Epic-attached Story ID is a hard error naming the
+   affected IDs and the fix — never guess a route.
+3. **Compose the segment plan.** Standalone-Story set (when present) as
+   one segment, then one segment per Epic ID in input order. For a
+   multi-segment plan, present it and wait for operator confirmation
+   (`--yes` suppresses).
+4. **Execute segments sequentially.** For each segment in order, read the
+   selected path helper **in full** and execute it from its entry phase,
+   forwarding the segment's scoped flags. The helper's phase numbering,
+   watchdogs, gates, and scripts are unchanged — this router adds no phase
+   content. Stop on the first non-complete segment per the failure policy.
+5. **Report.** On completion (or halt), summarize per-segment outcomes and,
+   when halted, the resume command.
 
 ## Constraints
 
-- `/deliver` requires a planned ticket: an Epic at `agent::ready` (the
-  Epic helper's preflight enforces this) or well-formed standalone Stories.
-  Planning happens in [`/plan`](plan.md); the plan-review gate between the
-  two commands is a hard boundary.
+- `/deliver` requires planned tickets: Epics at `agent::ready` (the
+  Epic helper's preflight enforces this, per segment) or well-formed
+  standalone Stories. Planning happens in [`/plan`](plan.md); the
+  plan-review gate between the two commands is a hard boundary.
 - The router performs no git or label mutations itself; the path helpers
   own every script invocation.
+- Segments execute strictly sequentially — never interleave a standalone
+  Story fan-out with an Epic wave loop, and never run two Epic segments
+  concurrently.
 
 ## See also
 
 - [`/plan`](plan.md) — the unified planning entry point.
 - [`helpers/deliver-epic.md`](helpers/deliver-epic.md) /
   [`helpers/deliver-stories.md`](helpers/deliver-stories.md) — the path
-  helpers.
+  helpers, delegated to per segment.

package/.agents/workflows/helpers/agents-sync-config.md

@@ -68,8 +68,9 @@ node .agents/scripts/sync-agentrc.js
 The script:
 
 1. Reads `.agentrc.json` from the working directory (`--cwd <path>` to
-   override). When the file is missing, prints a pointer to
-   `/agents-bootstrap-project` and exits 1.
+   override). When the file is missing, prints an error asking the
+   operator to run `mandrel init` (new project) or
+   `node .agents/scripts/bootstrap.js` (existing project) and exits 1.
 2. Validates the parsed config against the framework AJV schema
    (`getAgentrcValidator()`). On any failure, prints a single-line error
    list and exits 1 — the operator must fix the typo / missing required

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

@@ -14,9 +14,14 @@ description: >-
 
 ## Overview
 
-`/deliver` is the **single SDL execution command** in the 5.40 surface.
-It opens a PR against `main` and auto-merges when every signal certifies a
-clean run; otherwise it falls back to the operator-merges-button path.
+This helper is the **Epic delivery path** behind `/deliver` — the router
+delegates to it once per Epic ID, either as the sole route (single-Epic
+input) or as one **Epic segment** of the sequential segment plan `/deliver`
+composes over mixed Epic / standalone-Story input (Epic segments run in
+input order, after the standalone segment; see
+[`deliver.md`](../deliver.md)). Each invocation opens a PR against `main`
+and auto-merges when every signal certifies a clean run; otherwise it falls
+back to the operator-merges-button path.
 
 ```text
 /deliver <epicId>
@@ -32,8 +37,10 @@ clean run; otherwise it falls back to the operator-merges-button path.
   → Phase 9 — cleanup              (BranchCleaner + Cleaner lifecycle listeners on epic.cleanup.start / epic.merge.armed; fire via lifecycle-emit → epic.merge.armed)
 ```
 
-The argument is always an Epic ID (`type::epic`). Story IDs go to
-[`/deliver`](deliver-stories.md) (standalone) or the
+The argument is always a single Epic ID (`type::epic`) — multi-Epic or
+mixed input is segmented by the `/deliver` router before this helper runs.
+Story IDs go to
+[`helpers/deliver-stories`](deliver-stories.md) (standalone) or the
 [`helpers/epic-deliver-story`](epic-deliver-story.md) helper
 (Epic-attached, invoked by this workflow's fan-out); Tasks are not directly
 executable.

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

@@ -11,10 +11,14 @@ description: >-
 
 ## Overview
 
-`/deliver` is the **operator-facing multi-Story delivery command**. It
-takes one or more Story IDs, builds a dependency-aware wave plan, optionally
-confirms it with the operator, and fans out one Agent call per Story per wave
-— parallel within each wave, serialised across waves.
+This helper is the **standalone multi-Story delivery path** behind
+`/deliver`. The router delegates to it whenever the supplied IDs include
+standalone Stories — either as the sole route (Story-only input) or as the
+**standalone segment** of a mixed segment plan (run first, before any Epic
+segments; see [`deliver.md`](../deliver.md)). It takes one or more Story
+IDs, builds a dependency-aware wave plan, optionally confirms it with the
+operator, and fans out one Agent call per Story per wave — parallel within
+each wave, serialised across waves.
 
 ```text
 /deliver 101 102 103
@@ -33,11 +37,13 @@ confirms it with the operator, and fans out one Agent call per Story per wave
 | 1+ standalone Stories (no `Epic: #N` in body) | `/deliver <id> [<id>...]` |
 | Exactly one standalone Story (lighter path) | `/single-story-deliver <id>` |
 | Epic-attached Stories (have `Epic: #N`) | `/deliver <epicId>` |
+| Mixed Epics + standalone Stories | `/deliver <ids...>` — the router composes a sequential segment plan; this helper delivers the standalone segment first |
 
-`/deliver` **refuses** Stories that carry an `Epic: #N` reference in
+This helper **refuses** Stories that carry an `Epic: #N` reference in
 their body. Those Stories belong to an Epic's dispatch manifest and must flow
-through `/deliver`. Use `/single-story-deliver` for a single Epic-free
-Story when you want the leaner one-story path without wave machinery.
+through `/deliver <epicId>`. Use `/single-story-deliver` for a single
+Epic-free Story when you want the leaner one-story path without wave
+machinery.
 
 > **Concurrency cap.** The cap is resolved **deterministically in code** by
 > `stories-wave-tick.js` (Phase 1a) — the same `resolveConfig` + `getRunners`

package/.agents/workflows/plan.md

@@ -58,19 +58,61 @@ 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. **Triage (idea path only).** Run the
+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).
-3. **Delegate.** Read the selected path helper **in full** and execute it
+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.
-4. **Internal returns.** When a path helper would historically have handed
+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.
 
@@ -84,6 +126,8 @@ helpers, no command hop and no operator re-entry.
 
 ## See also
 
-- [`/deliver`](deliver.md) — the unified delivery entry point.
+- [`/deliver`](deliver.md) — the unified delivery entry point. Accepts a
+  single Epic, one or more standalone Stories, or any mix of ≥1 Epics and
+  standalone Stories — mixed sets compose a sequential segment plan.
 - [`helpers/plan-epic.md`](helpers/plan-epic.md) /
   [`helpers/plan-story.md`](helpers/plan-story.md) — the path helpers.

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 → /plan
 /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 `/plan`). Once you have a
-planned Epic, deliver it with `/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 …`,