mandrel 1.58.0 → 1.60.0

package/.agents/scripts/check-arch-cycles.js

@@ -0,0 +1,360 @@
+/**
+ * CLI: ratchet-down architecture gate for import cycles (Story #3991).
+ *
+ * Walks every `.js` file under `.agents/scripts/` (excluding
+ * `node_modules`), parses relative static-import edges
+ * (`from './…/x.js'`), detects directed cycles via DFS, and compares
+ * them against the committed allowlist at `baselines/arch-cycles.json`.
+ *
+ * Ratchet semantics mirror `check-dead-exports.js`:
+ *   - Any detected cycle NOT in the allowlist → exit 1, cycle path printed.
+ *   - Allowlisted cycle no longer detected → printed as `-` (removal),
+ *     warning that the allowlist can shrink. Removals-only exits 0.
+ *   - Clean diff → exit 0.
+ *
+ * Cycles are normalized by rotating to the lexicographically-smallest
+ * member so the same cycle always serializes identically regardless of
+ * the DFS entry point.
+ *
+ * Flags:
+ *   --baseline <path>  override the allowlist path (default
+ *                      `baselines/arch-cycles.json`, resolved from cwd)
+ *   --root <path>      override the scanned root (default
+ *                      `.agents/scripts`, resolved from cwd)
+ *   --json             write the structured envelope to stdout
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { runAsCli } from './lib/cli-utils.js';
+
+/**
+ * Parse argv for `--baseline <path>`, `--root <path>`, and `--json`.
+ * Exported so unit tests can pin the parser.
+ *
+ * @param {string[]} argv
+ * @returns {{ baselinePath: string | null, rootPath: string | null, json: boolean }}
+ */
+export function parseArgv(argv = []) {
+  let baselinePath = null;
+  let rootPath = null;
+  let json = false;
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--baseline') {
+      const next = argv[i + 1];
+      if (next && !next.startsWith('--')) {
+        baselinePath = next;
+        i += 1;
+      }
+    } else if (a === '--root') {
+      const next = argv[i + 1];
+      if (next && !next.startsWith('--')) {
+        rootPath = next;
+        i += 1;
+      }
+    } else if (a === '--json') {
+      json = true;
+    }
+  }
+  return { baselinePath, rootPath, json };
+}
+
+/**
+ * Recursively collect `.js` files under `rootDir`, skipping
+ * `node_modules`. Returns absolute paths, sorted for determinism.
+ *
+ * @param {string} rootDir
+ * @returns {string[]}
+ */
+export function collectJsFiles(rootDir) {
+  const out = [];
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name === 'node_modules') continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+      } else if (entry.isFile() && entry.name.endsWith('.js')) {
+        out.push(full);
+      }
+    }
+  };
+  walk(rootDir);
+  return out.sort();
+}
+
+const IMPORT_RE = /from\s+['"](\.\.?\/[^'"]+\.js)['"]/g;
+
+/**
+ * Pure helper: extract relative static-import specifiers from source text.
+ *
+ * @param {string} source
+ * @returns {string[]}
+ */
+export function parseRelativeImports(source) {
+  const specs = [];
+  for (const m of source.matchAll(IMPORT_RE)) {
+    specs.push(m[1]);
+  }
+  return specs;
+}
+
+/**
+ * Build a directed import graph over the given files. Node identity is the
+ * file path relative to `rootDir`, posix-separated, so the graph (and any
+ * cycles found in it) serializes identically across platforms. Edges that
+ * resolve outside the scanned file set are dropped.
+ *
+ * @param {string[]} files absolute paths
+ * @param {string} rootDir
+ * @param {{ readFile?: (p: string) => string }} [opts]
+ * @returns {Map<string, string[]>}
+ */
+export function buildGraph(files, rootDir, { readFile } = {}) {
+  const read = readFile ?? ((p) => fs.readFileSync(p, 'utf-8'));
+  const toId = (abs) => path.relative(rootDir, abs).split(path.sep).join('/');
+  const idSet = new Set(files.map(toId));
+  const graph = new Map();
+  for (const file of files) {
+    const id = toId(file);
+    let source;
+    try {
+      source = read(file);
+    } catch {
+      graph.set(id, []);
+      continue;
+    }
+    const edges = [];
+    for (const spec of parseRelativeImports(source)) {
+      const target = path
+        .relative(rootDir, path.resolve(path.dirname(file), spec))
+        .split(path.sep)
+        .join('/');
+      if (idSet.has(target) && target !== id) edges.push(target);
+    }
+    graph.set(id, [...new Set(edges)].sort());
+  }
+  return graph;
+}
+
+/**
+ * Pure helper: rotate a cycle (array of module ids, no repeated terminal
+ * element) so it starts at its lexicographically-smallest member. The same
+ * cycle therefore always serializes identically regardless of where the
+ * DFS entered it.
+ *
+ * @param {string[]} cycle
+ * @returns {string[]}
+ */
+export function normalizeCycle(cycle) {
+  if (cycle.length === 0) return [];
+  let minIdx = 0;
+  for (let i = 1; i < cycle.length; i += 1) {
+    if (cycle[i] < cycle[minIdx]) minIdx = i;
+  }
+  return [...cycle.slice(minIdx), ...cycle.slice(0, minIdx)];
+}
+
+/**
+ * Detect directed cycles in the graph via iterative-stack DFS (white /
+ * gray / black coloring). Each back edge to a gray node yields the cycle
+ * slice currently on the DFS path. Cycles are normalized and deduplicated
+ * by their serialized form, then sorted for stable output.
+ *
+ * @param {Map<string, string[]>} graph
+ * @returns {string[][]} normalized cycles
+ */
+export function findCycles(graph) {
+  const WHITE = 0;
+  const GRAY = 1;
+  const BLACK = 2;
+  const color = new Map();
+  for (const node of graph.keys()) color.set(node, WHITE);
+  const seen = new Map();
+
+  const pathStack = [];
+  const onPath = new Map(); // node -> index in pathStack
+
+  const visit = (start) => {
+    // Iterative DFS frame stack: [node, edge cursor].
+    const frames = [[start, 0]];
+    color.set(start, GRAY);
+    onPath.set(start, pathStack.length);
+    pathStack.push(start);
+    while (frames.length > 0) {
+      const frame = frames[frames.length - 1];
+      const [node] = frame;
+      const edges = graph.get(node) ?? [];
+      if (frame[1] < edges.length) {
+        const next = edges[frame[1]];
+        frame[1] += 1;
+        const c = color.get(next);
+        if (c === GRAY) {
+          const cycle = normalizeCycle(pathStack.slice(onPath.get(next)));
+          seen.set(cycle.join(' -> '), cycle);
+        } else if (c === WHITE) {
+          color.set(next, GRAY);
+          onPath.set(next, pathStack.length);
+          pathStack.push(next);
+          frames.push([next, 0]);
+        }
+      } else {
+        color.set(node, BLACK);
+        onPath.delete(node);
+        pathStack.pop();
+        frames.pop();
+      }
+    }
+  };
+
+  for (const node of [...graph.keys()].sort()) {
+    if (color.get(node) === WHITE) visit(node);
+  }
+  return [...seen.values()].sort((a, b) =>
+    a.join(' -> ').localeCompare(b.join(' -> ')),
+  );
+}
+
+/**
+ * Pure helper: read the allowlist envelope from disk. Returns the parsed
+ * object or `null` when the file is missing or unparseable.
+ *
+ * @param {string} baselinePath
+ * @returns {{ cycles?: string[][] } | null}
+ */
+export function loadBaseline(baselinePath) {
+  try {
+    if (!fs.existsSync(baselinePath)) return null;
+    const parsed = JSON.parse(fs.readFileSync(baselinePath, 'utf-8'));
+    if (!parsed || typeof parsed !== 'object') return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Pure helper: diff detected cycles against the allowlist. Both sides are
+ * normalized before comparison so rotation differences never count as
+ * drift. Identity is the ` -> `-joined normalized cycle.
+ *
+ * @param {string[][]} allowlisted
+ * @param {string[][]} detected
+ * @returns {{ added: string[][], removed: string[][] }}
+ */
+export function diffCycles(allowlisted, detected) {
+  const key = (c) => normalizeCycle(c).join(' -> ');
+  const baseSet = new Set((allowlisted ?? []).map(key));
+  const currentSet = new Set((detected ?? []).map(key));
+  const added = (detected ?? []).filter((c) => !baseSet.has(key(c)));
+  const removed = (allowlisted ?? []).filter((c) => !currentSet.has(key(c)));
+  const sortFn = (a, b) => key(a).localeCompare(key(b));
+  return { added: added.sort(sortFn), removed: removed.sort(sortFn) };
+}
+
+/**
+ * Pure helper: render the human-readable diff. `+` lines are new cycles
+ * (gate fail), `-` lines are fixed cycles whose allowlist entry can be
+ * removed. A one-line summary always follows.
+ *
+ * @param {{ added: string[][], removed: string[][] }} diff
+ * @returns {string}
+ */
+export function renderDiff(diff) {
+  const lines = [];
+  const fmt = (c) => `${c.join(' -> ')} -> ${c[0]}`;
+  for (const c of diff.added) lines.push(`+ ${fmt(c)}`);
+  for (const c of diff.removed) lines.push(`- ${fmt(c)}`);
+  if (diff.removed.length > 0) {
+    lines.push(
+      `[arch-cycles] ⚠ ${diff.removed.length} allowlisted cycle(s) no longer detected — shrink baselines/arch-cycles.json`,
+    );
+  }
+  const tag = diff.added.length > 0 ? '(gate fail)' : '(ok)';
+  lines.push(
+    `[arch-cycles] added=${diff.added.length} removed=${diff.removed.length} ${tag}`,
+  );
+  return lines.join('\n');
+}
+
+/**
+ * Top-level CLI entry. Exported so tests can drive the full pipeline
+ * against a tmpdir fixture graph.
+ *
+ * @param {{
+ *   argv?: string[],
+ *   cwd?: string,
+ *   stdout?: { write: (s: string) => void },
+ *   stderr?: { write: (s: string) => void },
+ * }} [opts]
+ * @returns {Promise<number>} 0 = clean or removals-only; 1 = new cycle detected
+ */
+export async function runCli({
+  argv = process.argv.slice(2),
+  cwd = process.cwd(),
+  stdout = process.stdout,
+  stderr = process.stderr,
+} = {}) {
+  const { baselinePath, rootPath, json } = parseArgv(argv);
+  const resolvedRoot = path.resolve(
+    cwd,
+    rootPath ?? path.join('.agents', 'scripts'),
+  );
+  const resolvedBaselinePath = path.resolve(
+    cwd,
+    baselinePath ?? path.join('baselines', 'arch-cycles.json'),
+  );
+  if (!fs.existsSync(resolvedRoot)) {
+    throw new Error(`[arch-cycles] scan root not found: ${resolvedRoot}`);
+  }
+  const baseline = loadBaseline(resolvedBaselinePath);
+  const allowlisted = Array.isArray(baseline?.cycles) ? baseline.cycles : [];
+
+  const files = collectJsFiles(resolvedRoot);
+  const graph = buildGraph(files, resolvedRoot);
+  const detected = findCycles(graph);
+  const diff = diffCycles(allowlisted, detected);
+  const exitCode = diff.added.length > 0 ? 1 : 0;
+
+  if (json) {
+    const envelope = {
+      kind: 'arch-cycles-report',
+      root: resolvedRoot,
+      baselinePath: resolvedBaselinePath,
+      allowlisted: allowlisted.map(normalizeCycle),
+      detected,
+      added: diff.added,
+      removed: diff.removed,
+      exitCode,
+    };
+    stdout.write(`${JSON.stringify(envelope, null, 2)}\n`);
+  } else {
+    if (!baseline) {
+      stderr.write(
+        `[arch-cycles] ⚠ allowlist not found at ${resolvedBaselinePath} — treating as empty\n`,
+      );
+    }
+    stdout.write(`\n--- arch-cycles preview ---\n`);
+    stdout.write(`${renderDiff(diff)}\n`);
+  }
+
+  return exitCode;
+}
+
+async function main() {
+  return runCli();
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'arch-cycles',
+  propagateExitCode: true,
+  errorPrefix: '[arch-cycles] ❌ Fatal error',
+});

package/.agents/scripts/check-doc-links.js

@@ -5,7 +5,7 @@
 // Story #2662 — Internal-link and slash-command resolver for active docs.
 //
 // Scans every `*.md` under `docs/` and `.agents/` (excluding
-// `docs/CHANGELOG.md` and anything under `docs/archive/**`) and validates:
+// `docs/CHANGELOG.md`) and validates:
 //
 //   1. Every Markdown relative-path link `[text](relative/path[#anchor])`
 //      resolves to a real file on disk (anchors are not validated, only
@@ -19,7 +19,7 @@
 //
 //   3. No active doc mentions any retired slash command. The retired-command
 //      blocklist is seeded with `agents-bootstrap-github`,
-//      `single-story-plan` (renamed to `/story-plan`), and `mandrel`
+//      `single-story-plan` (renamed to `/plan`), and `mandrel`
 //      (retired in favor of the generated `.agents/docs/workflows.md`
 //      catalog) and takes precedence over the workflow-resolution check —
 //      a retired token is always a non-zero exit even if a stale workflow
@@ -125,7 +125,6 @@ export const SLASH_ALLOWLIST = new Set([
 
 function isExcludedRelPath(relPath) {
   if (relPath === 'docs/CHANGELOG.md') return true;
-  if (relPath.startsWith('docs/archive/')) return true;
   return false;
 }
 

package/.agents/scripts/coverage-capture.js

@@ -9,9 +9,11 @@
  *   2. With `--skip-when-no-crap-files`: read `git diff --name-only <ref>...HEAD`
  *      (default ref `main`) and exit 0 if no changed file lives under
  *      `crap.targetDirs`.
- *   3. Compare the coverage artifact mtime against the newest mtime in
- *      `crap.targetDirs`. Exit 0 when fresh.
- *   4. Otherwise spawn `npm run test:coverage` and propagate its exit code.
+ *   3. Test freshness: content digest of `crap.targetDirs` vs. the persisted
+ *      capture stamp (`coverage/.capture-stamp.json`), falling back to the
+ *      artifact-mtime heuristic when no stamp exists. Exit 0 when fresh.
+ *   4. Otherwise spawn `npm run test:coverage`, write a fresh capture stamp
+ *      on success, and propagate the exit code.
  *
  * Exit codes:
  *   0 — coverage is fresh (or capture skipped/succeeded).
@@ -24,8 +26,10 @@ import { getChangedFiles } from './lib/changed-files.js';
 import { getQuality, resolveConfig } from './lib/config-resolver.js';
 import {
   anyChangedUnderTargets,
+  computeContentDigest,
   isCoverageFresh,
   runCapture,
+  writeCaptureStamp,
 } from './lib/coverage-capture.js';
 
 import { Logger } from './lib/Logger.js';
@@ -99,6 +103,23 @@ function main() {
     Logger.error(
       `[coverage-capture] ✖ npm run test:coverage exited ${code}. Fix failing tests or coverage-threshold breaches before re-running the CRAP gate.`,
     );
+    return code;
+  }
+
+  // Persist the content digest next to the fresh artifact so subsequent
+  // freshness checks are content-aware (mtime churn from branch switches no
+  // longer invalidates). Best-effort — a missing stamp just means the next
+  // check falls back to the mtime heuristic.
+  const digest = computeContentDigest(args.cwd, crap.targetDirs);
+  if (
+    digest &&
+    writeCaptureStamp({
+      cwd: args.cwd,
+      coveragePath: crap.coveragePath,
+      digest,
+    })
+  ) {
+    Logger.info('[coverage-capture] Wrote content-digest capture stamp.');
   }
   return code;
 }

package/.agents/scripts/diagnose-friction.js

@@ -134,7 +134,7 @@ function buildFrictionSignal({
     timestamp: new Date().toISOString(),
     epicId: epicId ?? null,
     storyId: storyId ?? null,
-    // 3-tier hierarchy (Epic #3163): no Task tier, so friction signals
+    // 2-tier hierarchy (Epic #3163): no Task tier, so friction signals
     // carry no Task id. The field is retained for schema compatibility
     // and always null.
     taskId: null,

package/.agents/scripts/dispatcher.js

@@ -72,12 +72,12 @@ import { loadSpec, loadState } from './lib/spec/index.js';
  * loaded state mapping. The spec-aware renderer (`buildManifestFromSpec`)
  * looks up each Story's status via `state.mapping[slug].lastObservedAgentState`;
  * that field is only refreshed by the structural reconciler, so during
- * `/epic-deliver` execution it stays `null` and every Story renders as ⬜
+ * `/deliver` execution it stays `null` and every Story renders as ⬜
  * pending even after the Story merges. The wave-runner replaced the
  * dispatcher-per-wave refresh loop and the local state.json never sees
  * the progress signal.
  *
- * Under the 3-tier hierarchy (Epic #3163) the runtime manifest's wave
+ * Under the 2-tier hierarchy (Epic #3163) the runtime manifest's wave
  * records carry `stories[]` (each with the live `storyId` + `status` from
  * `fetchEpicContext`'s GH query), not the retired `tasks[]` shape. The
  * overlay walks `manifest.waves[].stories[]` and copies each Story's

package/.agents/scripts/drain-pending-cleanup.js

@@ -8,7 +8,7 @@
  * any still-stuck entries by enumerating the processes holding handles
  * inside the worktree path and terminating them.
  *
- * Invoked by `/epic-deliver`, `/epic-plan-spec` / `/epic-plan-decompose`
+ * Invoked by `/deliver`, `/epic-plan-spec` / `/epic-plan-decompose`
  * (via `drainPendingCleanupAtBoot` → `worktree-sweep.js`), and
  * `story-close` so the pending-cleanup ledger drains automatically
  * across the sprint lifecycle. Operators can also run it standalone:

package/.agents/scripts/epic-audit-prepare.js

@@ -2,7 +2,7 @@
 /* node:coverage ignore file */
 
 /**
- * epic-audit-prepare.js — Phase 4 prepare CLI for `/epic-deliver`.
+ * epic-audit-prepare.js — Phase 4 prepare CLI for `/deliver`.
  *
  * Thin glue around the audit-suite `selectAudits` SDK. Reads the Epic
  * ticket, runs the change-set selector against the Epic branch diff
@@ -193,7 +193,7 @@ function resolveTaskSizing(config) {
  * Best-effort and total, mirroring `resolveRiskRoutedLenses`: a
  * missing/unparseable checkpoint, an absent `planningRisk` field, or a
  * provider read failure all degrade to `standard` — the neutral default that
- * preserves today's behavior — so an Epic that skipped `/epic-plan` (no
+ * preserves today's behavior — so an Epic that skipped `/plan` (no
  * checkpoint) still gets a passing `standard` pass with no new failure mode.
  * The changed-file count can only escalate a low-risk Epic to `deep` (a wide
  * diff) and never downgrades a high-risk one; an unknown/absent count is the
@@ -295,7 +295,7 @@ export async function runEpicAuditPrepare(values, deps = {}) {
   const runner = deps.selectAudits ?? selectAudits;
 
   // Pin the change set to the requested Epic's own branch rather than the
-  // shared checkout's HEAD (Story #3362). Under two concurrent /epic-deliver
+  // shared checkout's HEAD (Story #3362). Under two concurrent /deliver
   // runs sharing one working copy, a HEAD-relative diff silently reports the
   // *other* Epic's change set; `refs/heads/epic/<id>` is unambiguous.
   const epicBranch = `epic/${epicId}`;

package/.agents/scripts/epic-deliver-note-intervention.js

@@ -3,9 +3,9 @@
 
 /**
  * epic-deliver-note-intervention.js — record a manual-intervention event
- * against the active `/epic-deliver` run-state checkpoint.
+ * against the active `/deliver` run-state checkpoint.
  *
- * The host LLM driving `/epic-deliver` invokes this CLI whenever it does
+ * The host LLM driving `/deliver` invokes this CLI whenever it does
  * something out-of-band that disqualifies the Epic from auto-merge:
  *
  *   - `AskUserQuestion` to the operator mid-run

package/.agents/scripts/epic-deliver-preflight.js

@@ -4,7 +4,7 @@
 /**
  * epic-deliver-preflight.js — Story #2899 (Epic #2880, F13).
  *
- * Estimates the cost of an upcoming `/epic-deliver` run *before* Story
+ * Estimates the cost of an upcoming `/deliver` run *before* Story
  * fan-out and surfaces the result to the operator on two channels:
  *
  *   1. A JSON envelope on stdout (always) with the keys
@@ -19,7 +19,7 @@
  *
  * The CLI is intentionally side-effect-light when `--dry-run` is set: no
  * comment write, no lifecycle emit. The slash-command workflow
- * (`/epic-deliver` Phase 1) calls the CLI without `--dry-run` so the
+ * (`/deliver` Phase 1) calls the CLI without `--dry-run` so the
  * comment is upserted; if any threshold is breached, the workflow flips
  * the Epic to `agent::blocked` and surfaces the envelope in chat for
  * operator review. The CLI itself does NOT flip labels — the workflow
@@ -70,7 +70,7 @@ const HELP = `Usage: node .agents/scripts/epic-deliver-preflight.js \\
   [--per-story-claude-tokens <n>]
 
 Estimates Story count, install cost, wave count, GitHub API request volume,
-and Claude Max quota burn for an Epic *before* /epic-deliver fan-out.
+and Claude Max quota burn for an Epic *before* /deliver fan-out.
 
 Flags:
   --dry-run                        Compute the estimate and print the JSON
@@ -103,7 +103,7 @@ const DEFAULTS = Object.freeze({
   perStoryApiRequests: 25,
   perStoryClaudeTokens: 200_000,
   // Base GH API budget: snapshot getTicket + getSubTickets + plan/manifest
-  // reads/writes that happen once per /epic-deliver run regardless of
+  // reads/writes that happen once per /deliver run regardless of
   // Story count. Empirical observation from a 5-Story Epic shows ~30
   // requests for the non-per-Story floor.
   baseApiRequests: 30,
@@ -240,7 +240,7 @@ export function renderPreflightBody({
     );
   } else {
     lines.push(
-      '⛔ **Threshold breaches** — `/epic-deliver` will flip the Epic to `agent::blocked` for operator review:',
+      '⛔ **Threshold breaches** — `/deliver` will flip the Epic to `agent::blocked` for operator review:',
     );
     for (const b of breaches) {
       lines.push(`- \`${b.key}\` = ${b.observed} (max ${b.max})`);
@@ -284,7 +284,7 @@ export async function runPreflight({
   const provider = injectedProvider ?? createProvider(config);
   const thresholds = getPreflight(config);
 
-  // Compose the same two phases /epic-deliver Phase 1 runs so the
+  // Compose the same two phases /deliver Phase 1 runs so the
   // preflight numbers match the actual dispatch plan.
   const ctx = { epicId, provider };
   let state = {};
@@ -297,9 +297,11 @@ export async function runPreflight({
   // Persist the snapshot/DAG envelope so `epic-deliver-prepare.js` can
   // reuse it instead of re-walking the hierarchy. The cache key is a
   // deterministic fingerprint of the Epic ticket returned by the same
-  // `getTicket(epicId)` call that drove `runSnapshotPhase`, so any drift
-  // (label, body, updatedAt) forces a cache miss in prepare.
-  const baseSha = computeBaseSha(state.epic);
+  // `getTicket(epicId)` call that drove `runSnapshotPhase` **plus** the
+  // Story snapshots that drove the wave DAG (Story #4019), so any drift —
+  // Epic label/body/updatedAt or a Story-dependency edit — forces a cache
+  // miss in prepare.
+  const baseSha = computeBaseSha(state.epic, state.stories);
   let cacheWritten = false;
   if (!dryRun) {
     await writePreflightCache({

package/.agents/scripts/epic-deliver-prepare.js

@@ -2,7 +2,7 @@
 /* node:coverage ignore file */
 
 /**
- * epic-deliver-prepare.js — Step 0/1 of the operator-driven `/epic-deliver`.
+ * epic-deliver-prepare.js — Step 0/1 of the operator-driven `/deliver`.
  *
  * Composes the existing engine phases that the in-process epic-runner used to
  * call sequentially, but does NOT dispatch any waves. The CLI is the single
@@ -226,16 +226,24 @@ export async function runEpicDeliverPrepare({
 
   // Story #3027: try the preflight cache first so we don't re-walk Epic
   // → Feature → Story when `epic-deliver-preflight.js` already did. The
-  // cache key is a deterministic fingerprint of the Epic ticket; a
-  // single getTicket(epicId) round-trip confirms the cache is still
-  // valid. Cache miss or baseSha mismatch → fall back to a fresh pass.
+  // cache key is a deterministic fingerprint of the Epic ticket plus the
+  // cached Story snapshots (Story #4019): the Epic re-fetch plus one
+  // getTicket per cached Story is still far cheaper than the full
+  // hierarchy BFS, and a Story-dependency edit now invalidates the cache.
+  // Cache miss or baseSha mismatch → fall back to a fresh pass.
   const ctx = { epicId, provider };
   let state = {};
   let cacheStatus = 'miss';
   const cached = await readPreflightCache({ epicId, cwd });
   if (cached) {
     const freshEpic = await provider.getTicket(epicId);
-    const freshBaseSha = computeBaseSha(freshEpic);
+    const cachedStoryIds = cached.stories
+      .map((s) => Number(s?.id ?? s?.number))
+      .filter((id) => Number.isInteger(id) && id > 0);
+    const freshStories = await Promise.all(
+      cachedStoryIds.map((id) => provider.getTicket(id)),
+    );
+    const freshBaseSha = computeBaseSha(freshEpic, freshStories);
     if (freshBaseSha === cached.baseSha) {
       state = {
         epic: cached.epic,

package/.agents/scripts/epic-execute-record-wave.js

@@ -6,7 +6,7 @@
  * advance the `epic-run-state` checkpoint, and re-render the unified
  * `epic-run-progress` rollup on the Epic.
  *
- * The slash-command (`/epic-deliver`) calls this CLI once per wave, after
+ * The slash-command (`/deliver`) calls this CLI once per wave, after
  * its host-level Agent-tool fan-out drains. It is the only writer of the
  * `epic-run-progress` structured comment for the wave-completion path —
  * there is no separate `/wave-execute` skill, no `wave-run-progress`
@@ -42,7 +42,7 @@ import { getRunners } from './lib/config/runners.js';
 import { resolveConfig } from './lib/config-resolver.js';
 import { Logger } from './lib/Logger.js';
 import * as epicRunStateStore from './lib/orchestration/epic-run-state-store.js';
-import { upsertEpicRunProgress } from './lib/orchestration/epic-runner/progress-reporter.js';
+import { upsertEpicRunProgress } from './lib/orchestration/epic-runner/progress-reporter/composition.js';
 import {
   emitStoryDispatchEnd,
   storyStatusToDispatchOutcome,
@@ -95,7 +95,7 @@ const HELP = `Usage: node .agents/scripts/epic-execute-record-wave.js \\
 
 Records the wave's per-Story outcomes, advances the epic-run-state
 checkpoint, and upserts the unified epic-run-progress rollup on the Epic.
-Prints the next action for the /epic-deliver slash command.
+Prints the next action for the /deliver slash command.
 `;
 
 /**
@@ -237,7 +237,7 @@ export async function runEpicExecuteRecordWave({
   //     Closes the start/end pairing the wave-tick reconciler and the
   //     `--check-idle` watchdog use to derive in-flight Stories. Before this
   //     the only producer was `wave-session.js`, which the host-LLM driven
-  //     /epic-deliver path never imports — so every dispatched Story stayed
+  //     /deliver path never imports — so every dispatched Story stayed
   //     "in-flight" forever and completed Stories tripped the watchdog.
   //     Best-effort: a failed append must not block the wave loop.
   emitWaveDispatchEnds({ epicId, verified, config });
@@ -257,7 +257,7 @@ export async function runEpicExecuteRecordWave({
 
   // 7. Fire the curated webhook events for this wave boundary. Mirrors the
   //    wave-loop emits in `lib/orchestration/epic-runner/phases/iterate-waves.js`
-  //    for the host-LLM driven /epic-deliver path (which does not pass
+  //    for the host-LLM driven /deliver path (which does not pass
   //    through `runEpic`). Each helper is fire-and-forget — webhook
   //    misconfig or a transient Slack outage must not block the wave loop.
   await emitWaveBoundaryNotifications({