mandrel 1.61.0 → 1.63.0

package/.agents/scripts/lib/story-body/story-body.js

@@ -355,6 +355,96 @@ function splitSections(markdown) {
   return { sections, footer, preamble };
 }
 
+// ---------------------------------------------------------------------------
+// Parser — per-section sub-parsers
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the minimal {@link ParseResult} returned for a legacy string body —
+ * markdown that carries no recognised structured section. The goal falls
+ * back to the preamble text (or the whole trimmed input), `depends_on` is
+ * still recovered from the footer, and all section arrays are empty.
+ *
+ * @param {string} input - The original markdown string.
+ * @param {string} preamble - Text before the first heading (from splitSections).
+ * @param {string} footer - Footer block text (from splitSections).
+ * @returns {ParseResult}
+ */
+function parseLegacyStringBody(input, preamble, footer) {
+  const warnings = [
+    'legacy-string-body: no structured sections found; returning minimal body from preamble text.',
+    'test-surface-unestimated: estimated_test_files not present.',
+  ];
+  const body = {
+    goal: preamble || input.trim(),
+    changes: [],
+    acceptance: [],
+    verify: [],
+    references: [],
+    wide: null,
+    depends_on: extractBlockedBy(footer),
+    estimated_test_files: null,
+  };
+  return {
+    body,
+    warnings,
+    info: {
+      hasGoalSection: false,
+      hasChangesSection: false,
+      hasAcceptanceSection: false,
+      hasVerifySection: false,
+      hasReferencesSection: false,
+      isLegacyStringBody: true,
+    },
+  };
+}
+
+/**
+ * Parse the `## Goal` section: join its non-empty content lines into a
+ * single one-line goal string.
+ *
+ * @param {string[]} lines - Raw content lines under the heading.
+ * @returns {string}
+ */
+function parseGoalSection(lines) {
+  return lines
+    .map((l) => l.trim())
+    .filter(Boolean)
+    .join(' ');
+}
+
+/**
+ * Parse a `## Changes` / `## References` section into a list of
+ * `PathEntry | string` entries. List markers are stripped, blank entries are
+ * dropped, and each surviving entry is normalized via {@link parsePathEntry}
+ * (which appends `legacy-path-entry` warnings for bare-string bullets).
+ *
+ * @param {string[]} lines - Raw content lines under the heading.
+ * @param {string[]} warnings - Mutable warnings sink.
+ * @returns {Array<PathEntry|string>}
+ */
+function parsePathEntrySection(lines, warnings) {
+  const entries = [];
+  for (const line of lines) {
+    const stripped = stripListMarker(line);
+    if (!stripped) continue;
+    const entry = parsePathEntry(stripped, warnings);
+    if (entry !== null) entries.push(entry);
+  }
+  return entries;
+}
+
+/**
+ * Parse a plain bullet-list section (`## Acceptance` / `## Verify`) into a
+ * list of trimmed strings, dropping blank entries.
+ *
+ * @param {string[]} lines - Raw content lines under the heading.
+ * @returns {string[]}
+ */
+function parseTextListSection(lines) {
+  return lines.map((l) => stripListMarker(l)).filter(Boolean);
+}
+
 // ---------------------------------------------------------------------------
 // Parser
 // ---------------------------------------------------------------------------
@@ -414,84 +504,20 @@ export function parse(input) {
     !hasVerifySection;
 
   if (isLegacyStringBody) {
-    // Extract depends_on from footer even for legacy bodies.
-    const dependsOn = extractBlockedBy(footer);
-    warnings.push(
-      'legacy-string-body: no structured sections found; returning minimal body from preamble text.',
-    );
-    warnings.push(
-      'test-surface-unestimated: estimated_test_files not present.',
-    );
-    const body = {
-      goal: preamble || input.trim(),
-      changes: [],
-      acceptance: [],
-      verify: [],
-      references: [],
-      wide: null,
-      depends_on: dependsOn,
-      estimated_test_files: null,
-    };
-    return {
-      body,
-      warnings,
-      info: {
-        hasGoalSection: false,
-        hasChangesSection: false,
-        hasAcceptanceSection: false,
-        hasVerifySection: false,
-        hasReferencesSection: false,
-        isLegacyStringBody: true,
-      },
-    };
+    return parseLegacyStringBody(input, preamble, footer);
   }
 
-  // --- Parse goal ---
-  const goalLines = sections.get('goal') ?? [];
-  const goal = goalLines
-    .map((l) => l.trim())
-    .filter(Boolean)
-    .join(' ');
-
-  // --- Parse changes ---
-  const changeLines = sections.get('changes') ?? [];
-  const changes = [];
-  for (const line of changeLines) {
-    const stripped = stripListMarker(line);
-    if (!stripped) continue;
-    const entry = parsePathEntry(stripped, warnings);
-    if (entry !== null) changes.push(entry);
-  }
-
-  // --- Parse acceptance ---
-  const acceptanceLines = sections.get('acceptance') ?? [];
-  const acceptance = acceptanceLines
-    .map((l) => stripListMarker(l))
-    .filter(Boolean);
-
-  // --- Parse verify ---
-  const verifyLines = sections.get('verify') ?? [];
-  const verify = verifyLines.map((l) => stripListMarker(l)).filter(Boolean);
-
-  // --- Parse references (optional) ---
-  const referenceLines = sections.get('references') ?? [];
-  const references = [];
-  for (const line of referenceLines) {
-    const stripped = stripListMarker(line);
-    if (!stripped) continue;
-    const entry = parsePathEntry(stripped, warnings);
-    if (entry !== null) {
-      // References MUST be object form (canonical).
-      if (typeof entry === 'string') {
-        // Already warned as legacy-path-entry; keep as string for now.
-        references.push(entry);
-      } else {
-        references.push(entry);
-      }
-    }
-  }
-
-  // --- Parse footer ---
+  const goal = parseGoalSection(sections.get('goal') ?? []);
+  const changes = parsePathEntrySection(
+    sections.get('changes') ?? [],
+    warnings,
+  );
+  const acceptance = parseTextListSection(sections.get('acceptance') ?? []);
+  const verify = parseTextListSection(sections.get('verify') ?? []);
+  const references = parsePathEntrySection(
+    sections.get('references') ?? [],
+    warnings,
+  );
   const dependsOn = extractBlockedBy(footer);
 
   // --- Recover wide / estimated_test_files from the meta block ---

package/.agents/scripts/providers/github/blocked-by-add.js

@@ -0,0 +1,252 @@
+/**
+ * GitHub Provider — shared "set native blocked-by dependency" helper.
+ *
+ * Story #4067 — after issue creation during Phase 8 decomposition, each
+ * Story's `depends_on` graph is known as a set of sibling slugs. This
+ * helper translates those slug-to-issueNumber pairs into native GitHub
+ * "blocked by" dependency edges so maintainers can see blocking
+ * relationships directly in the GitHub UI.
+ *
+ * API surface used:
+ *   Read:  GET  /repos/{owner}/{repo}/issues/{issue_number}/dependencies/blocked_by
+ *   Write: POST /repos/{owner}/{repo}/issues/{issue_number}/dependencies/blocked_by
+ *          body: { "issue_id": <integer db id of the blocking issue> }
+ *
+ * Contract:
+ *   - **Idempotent** — reads existing edges first; only POSTs missing ones.
+ *   - **Non-fatal** — catches all errors per edge, warns, and continues.
+ *     The overall function never throws; errors are returned in a summary.
+ *   - **No-op on empty input** — returns immediately when no depends_on
+ *     edges are present or the slug→issueNumber map is empty.
+ */
+
+import { Logger } from '../../lib/Logger.js';
+import { concurrentMap } from '../../lib/util/concurrent-map.js';
+import { parseApiJson } from './request-helpers.js';
+
+/**
+ * Bounded concurrency for the GitHub dependency-edge round-trips. Kept modest
+ * to respect GitHub's secondary rate limits while still collapsing the wall-
+ * clock latency from `sum(round-trips)` toward `sum(round-trips) / concurrency`.
+ */
+const EDGE_CONCURRENCY = 5;
+
+/**
+ * Fetch the existing blocked-by issue numbers for a given issue.
+ *
+ * Returns `[]` on any error so the caller falls back to posting the full
+ * set of missing edges (worst case: a duplicate POST, which GitHub
+ * handles idempotently).
+ *
+ * @param {{ gh: object, owner: string, repo: string, issueNumber: number }} opts
+ * @returns {Promise<number[]>} Database ids of the issues that currently block `issueNumber`.
+ */
+async function fetchExistingBlockedBy({ gh, owner, repo, issueNumber }) {
+  try {
+    const result = await gh.api({
+      method: 'GET',
+      endpoint: `/repos/${owner}/${repo}/issues/${issueNumber}/dependencies/blocked_by`,
+    });
+    const data = parseApiJson(result);
+    if (!Array.isArray(data)) return [];
+    return data.map((item) => item?.id).filter((id) => typeof id === 'number');
+  } catch (err) {
+    Logger.warn(
+      `[blocked-by-add] Could not fetch existing blocked-by for #${issueNumber}: ${err.message}`,
+    );
+    return [];
+  }
+}
+
+/**
+ * Set native GitHub "blocked by" dependency edges for a single issue.
+ *
+ * For each entry in `blockerInternalIds`, checks whether the edge already
+ * exists and POSTs only the missing ones. Every individual POST failure is
+ * caught, logged as a warning, and counted — the function never throws.
+ *
+ * @param {{
+ *   gh: object,
+ *   owner: string,
+ *   repo: string,
+ *   issueNumber: number,
+ *   blockerInternalIds: number[],
+ * }} opts
+ * @returns {Promise<{ added: number, skipped: number, failed: number }>}
+ */
+async function addBlockedByEdges({
+  gh,
+  owner,
+  repo,
+  issueNumber,
+  blockerInternalIds,
+}) {
+  if (blockerInternalIds.length === 0) {
+    return { added: 0, skipped: 0, failed: 0 };
+  }
+
+  const existing = await fetchExistingBlockedBy({
+    gh,
+    owner,
+    repo,
+    issueNumber,
+  });
+  const existingSet = new Set(existing);
+
+  // Partition up front so the skip count is deterministic regardless of the
+  // concurrent POST dispatch order, then POST only the missing edges in
+  // parallel under a modest cap.
+  const missing = blockerInternalIds.filter((id) => !existingSet.has(id));
+  const skipped = blockerInternalIds.length - missing.length;
+
+  const perEdge = await concurrentMap(
+    missing,
+    async (blockerId) => {
+      try {
+        await gh.api({
+          method: 'POST',
+          endpoint: `/repos/${owner}/${repo}/issues/${issueNumber}/dependencies/blocked_by`,
+          body: { issue_id: blockerId },
+        });
+        return { added: 1, failed: 0 };
+      } catch (err) {
+        Logger.warn(
+          `[blocked-by-add] Failed to add blocked-by edge #${issueNumber} ← blocker(id=${blockerId}): ${err.message}`,
+        );
+        return { added: 0, failed: 1 };
+      }
+    },
+    { concurrency: EDGE_CONCURRENCY },
+  );
+
+  let added = 0;
+  let failed = 0;
+  for (const r of perEdge) {
+    added += r.added;
+    failed += r.failed;
+  }
+
+  return { added, skipped, failed };
+}
+
+/**
+ * Translate a Story's `depends_on` slug list into native GitHub "blocked
+ * by" dependency edges, given the slug→issueNumber map from the reconciler
+ * state and a `getTicket` hook to resolve database ids.
+ *
+ * Iterates every Story that has a non-empty `dependsOn` array; for each
+ * depended-on slug, resolves the blocker's issue number (via the slug map),
+ * then resolves the blocker's database id via `getTicket`, and calls
+ * `addBlockedByEdges`. Any failure at any step is caught, logged as a
+ * warning, and reflected in the returned summary — the function never
+ * throws.
+ *
+ * @param {{
+ *   stories: Array<{ slug: string, dependsOn?: string[] }>,
+ *   slugToIssueNumber: Record<string, number>,
+ *   getTicket: (issueNumber: number) => Promise<{ internalId: number }>,
+ *   owner: string,
+ *   repo: string,
+ *   gh: object,
+ * }} opts
+ * @returns {Promise<{
+ *   edgesAdded: number,
+ *   edgesSkipped: number,
+ *   edgesFailed: number,
+ *   storiesProcessed: number,
+ * }>}
+ */
+export async function applyBlockedByDependencies({
+  stories,
+  slugToIssueNumber,
+  getTicket,
+  owner,
+  repo,
+  gh,
+}) {
+  let edgesAdded = 0;
+  let edgesSkipped = 0;
+  let edgesFailed = 0;
+  let storiesProcessed = 0;
+
+  // Process each story's GET + its POST batch under one bounded concurrentMap
+  // so the per-story round-trips overlap. Each mapper returns its own counter
+  // contribution; we sum them after the pass. The bodies swallow their own
+  // errors (per-edge try/catch + the non-fatal contract), so concurrentMap
+  // never sees a rejection and the no-throw guarantee is preserved.
+  const perStory = await concurrentMap(
+    stories,
+    async (story) => {
+      const deps = Array.isArray(story.dependsOn) ? story.dependsOn : [];
+      if (deps.length === 0) {
+        return { added: 0, skipped: 0, failed: 0, processed: 0 };
+      }
+
+      const storyIssueNumber = slugToIssueNumber[story.slug];
+      if (typeof storyIssueNumber !== 'number') {
+        Logger.warn(
+          `[blocked-by-add] No issue number for story slug "${story.slug}"; skipping depends_on edges.`,
+        );
+        return { added: 0, skipped: 0, failed: 0, processed: 0 };
+      }
+
+      let failed = 0;
+      const blockerInternalIds = [];
+
+      for (const depSlug of deps) {
+        const blockerIssueNumber = slugToIssueNumber[depSlug];
+        if (typeof blockerIssueNumber !== 'number') {
+          Logger.warn(
+            `[blocked-by-add] depends_on slug "${depSlug}" (from "${story.slug}") has no mapped issue number; skipping edge.`,
+          );
+          failed++;
+          continue;
+        }
+        try {
+          const blocker = await getTicket(blockerIssueNumber);
+          if (typeof blocker?.internalId !== 'number') {
+            Logger.warn(
+              `[blocked-by-add] Blocker #${blockerIssueNumber} ("${depSlug}") has no internalId; skipping edge.`,
+            );
+            failed++;
+            continue;
+          }
+          blockerInternalIds.push(blocker.internalId);
+        } catch (err) {
+          Logger.warn(
+            `[blocked-by-add] Could not resolve blocker "${depSlug}" (#${blockerIssueNumber}): ${err.message}`,
+          );
+          failed++;
+        }
+      }
+
+      if (blockerInternalIds.length === 0) {
+        return { added: 0, skipped: 0, failed, processed: 1 };
+      }
+
+      const result = await addBlockedByEdges({
+        gh,
+        owner,
+        repo,
+        issueNumber: storyIssueNumber,
+        blockerInternalIds,
+      });
+      return {
+        added: result.added,
+        skipped: result.skipped,
+        failed: failed + result.failed,
+        processed: 1,
+      };
+    },
+    { concurrency: EDGE_CONCURRENCY },
+  );
+
+  for (const r of perStory) {
+    edgesAdded += r.added;
+    edgesSkipped += r.skipped;
+    edgesFailed += r.failed;
+    storiesProcessed += r.processed;
+  }
+
+  return { edgesAdded, edgesSkipped, edgesFailed, storiesProcessed };
+}

package/.agents/scripts/single-story-init.js

@@ -36,7 +36,7 @@
  * @see .agents/workflows/helpers/single-story-deliver.md
  */
 
-import { spawnSync } from 'node:child_process';
+import { spawnSync as defaultSpawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { parseSprintArgs } from './lib/cli-args.js';
@@ -109,12 +109,25 @@ const progress = Logger.createProgress('single-story-init', { stderr: true });
  * ripple into the single-story-sweep planner, which is intentionally out
  * of scope for the callers-only provider migration.
  *
+ * Story #4073: the `spawnImpl` seam injects the `spawnSync` boundary so the
+ * runner's success/error handling can be unit-tested without a live `gh`
+ * binary. It defaults to `child_process.spawnSync` (mirroring the
+ * `spawnImpl` seam in `lib/gh-exec.js` and the `runner` seam in
+ * `lib/bootstrap/gh-preflight.js`), so the production CLI path is unchanged.
+ * The synchronous `spawnSync` shape is preserved deliberately — the
+ * candidate-filter loop in `executeCleanup` is synchronous, so converting
+ * this to the async `lib/gh-exec.js` facade would ripple into the
+ * single-story-sweep planner.
+ *
  * @param {string} cwd Repo root used as the default spawn cwd.
+ * @param {typeof defaultSpawnSync} [spawnImpl] Injectable spawn boundary —
+ *   defaults to `child_process.spawnSync`. Tests pass a fake to assert the
+ *   error/exit-code handling without spawning a real child process.
  * @returns {(args: string[], opts?: { cwd?: string }) => string}
  */
-export function makeGhRunner(cwd) {
+export function makeGhRunner(cwd, spawnImpl = defaultSpawnSync) {
   return (args, opts) => {
-    const result = spawnSync('gh', args, {
+    const result = spawnImpl('gh', args, {
       cwd: opts?.cwd ?? cwd,
       encoding: 'utf-8',
       shell: false,

package/.agents/workflows/audit-architecture.md

@@ -129,6 +129,14 @@ legitimately have no layered architecture to guard.
 
 ## Step 2: Analysis Dimensions
 
+For every finding you surface, grade **Impact** on a High / Medium / Low axis
+reflecting the severity of the architectural risk (how much correctness,
+maintainability, or testability the gap erodes), independent of the
+**Category** effort axis — a Quick Win can still be High Impact, and a
+Structural Change can be Medium. As a loose default, Quick Wins typically land
+High (cheap to fix, real payoff) and Structural Changes Medium/High, but grade
+Impact on the risk itself rather than deriving it mechanically from Category.
+
 Evaluate the gathered context against the following clean code dimensions:
 
 1. **Over-Engineering & Abstractions:** Identify "dry-run" complexity, premature
@@ -294,6 +302,7 @@ marked `n/a`.]
 
 ### [Short Title of the Issue]
 
+- **Impact:** [High | Medium | Low]
 - **Category:** [Quick Win | Structural Change]
 - **Dimension:** [e.g., Cognitive Load & Nesting | Testable Surface (Humble-Object Boundary) | Automated Architecture Guardrails]
 - **Current State:** [The specific file/function and why it is problematic]

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.