mandrel 1.58.0 → 1.60.0

package/.agents/scripts/lib/maintainability-utils.js

@@ -1,119 +1,24 @@
 import fs from 'node:fs';
-import { createRequire } from 'node:module';
 import path from 'node:path';
 import { minimatch } from 'minimatch';
 import { canonicalise as canonicalisePath } from './baselines/path-canon.js';
-import {
-  write as writeBaselineEnvelope,
-  writeFile as writeBaselineFile,
-} from './baselines/writer.js';
-import { runOnPool } from './cpu-pool.js';
+import { POOL_SERIAL_THRESHOLD, runOnPool } from './cpu-pool.js';
 import { Logger } from './Logger.js';
 import { calculateForFile } from './maintainability-engine.js';
 
-const require = createRequire(import.meta.url);
-
 const MAINTAINABILITY_WORKER_URL = new URL(
   './workers/maintainability-worker.js',
   import.meta.url,
 );
 
-// Below this batch size the pool's spawn overhead dominates — fall back
-// to in-process serial scoring for `--changed-since` runs that touch
-// only a handful of files. Tuned against the test suite's tmpdir
-// fixtures (n=2 stays serial; the full repo n≈470 takes the pool path).
-const SERIAL_THRESHOLD = 8;
+// Pool-vs-serial cutover — single-sourced in cpu-pool.js (see the
+// POOL_SERIAL_THRESHOLD docstring for the tuning rationale).
+const SERIAL_THRESHOLD = POOL_SERIAL_THRESHOLD;
 
 const JS_EXTS = new Set(['.js', '.mjs', '.cjs']);
 const TS_EXTS = new Set(['.ts', '.tsx', '.mts', '.cts']);
 const SUPPORTED_EXTS = new Set([...JS_EXTS, ...TS_EXTS]);
 
-let _ts = null;
-let _tsLoadFailed = false;
-
-function loadTypeScript() {
-  if (_ts) return _ts;
-  if (_tsLoadFailed) return null;
-  try {
-    _ts = require('typescript');
-    return _ts;
-  } catch {
-    _tsLoadFailed = true;
-    return null;
-  }
-}
-
-/**
- * Resolve the `typescript` package version, used to stamp baselines so
- * consumers can detect transpiler drift. Returns `'0.0.0'` when the
- * dependency is unresolvable — callers treat that sentinel as "unknown
- * environment" and may refuse to persist a baseline that includes TS rows.
- *
- * @returns {string}
- */
-export function resolveTsTranspilerVersion() {
-  const ts = loadTypeScript();
-  if (ts && typeof ts.version === 'string') return ts.version;
-  return '0.0.0';
-}
-
-function isTypeScriptPath(filePath) {
-  return TS_EXTS.has(path.extname(String(filePath)).toLowerCase());
-}
-
-/**
- * Pre-transpile TypeScript or TSX sources to JavaScript that the
- * Esprima-based escomplex kernel can parse. Returns the input unchanged
- * for `.js` / `.mjs` / `.cjs` paths.
- *
- * Type annotations introduce no control flow, so the transpiled output
- * scores identically to the original TS for cyclomatic complexity,
- * Halstead volume, and the maintainability index. `.tsx` uses the
- * `react-jsx` emit so JSX expressions become function calls escomplex
- * can read; `.preserve` would leave JSX in the output and Esprima would
- * choke on it.
- *
- * On transpile failure the helper returns `null` — callers treat that
- * as "skip this file" rather than crashing the scan.
- *
- * @param {string} filePath
- * @param {string} source
- * @returns {string|null}
- */
-export function transpileIfNeeded(filePath, source) {
-  if (!isTypeScriptPath(filePath)) return source;
-  const ts = loadTypeScript();
-  if (!ts) {
-    Logger.warn(
-      `[Maintainability] ⚠ typescript package not resolvable; cannot score ${filePath}. ` +
-        "Install with 'npm install --save-dev typescript' (peer dep, >=5.0.0).",
-    );
-    return null;
-  }
-  try {
-    const result = ts.transpileModule(source, {
-      compilerOptions: {
-        target: ts.ScriptTarget.ESNext,
-        module: ts.ModuleKind.ESNext,
-        isolatedModules: true,
-        noEmitHelpers: true,
-        importHelpers: false,
-        removeComments: false,
-        jsx: ts.JsxEmit.ReactJSX,
-        sourceMap: false,
-      },
-      fileName: path.basename(filePath),
-      reportDiagnostics: false,
-    });
-    return result.outputText;
-  } catch (err) {
-    Logger.warn(
-      `[Maintainability] ⚠ TS transpile failed for ${filePath}: ${err?.message ?? err}; skipping.`,
-    );
-    return null;
-  }
-}
-
 /**
  * @returns {boolean} True when the path's extension is one the engines score.
  */
@@ -121,94 +26,6 @@ function isSupportedSourceFile(filePath) {
   return SUPPORTED_EXTS.has(path.extname(String(filePath)).toLowerCase());
 }
 
-/**
- * Loads the current maintainability baseline from disk. The on-disk path is
- * resolved by the caller via {@link getBaselines}; passing it explicitly
- * removes the silent-default behaviour the framework dropped in Epic #730
- * Story 5.5.
- *
- * @param {string} baselinePath  Repo-relative or absolute path to the baseline
- *   JSON. Required.
- * @returns {Record<string, number>}
- */
-/**
- * Story #1895: project the canonical maintainability envelope back to the
- * legacy flat `{ path: mi }` map so existing gate consumers keep working
- * without churn — Story #1912 will replace this shim with the shared
- * reader. Returns the parsed input unchanged when it doesn't look like an
- * envelope (legacy flat shape stays flat).
- */
-function projectMaintainabilityEnvelopeToFlat(parsed) {
-  if (
-    !parsed ||
-    typeof parsed !== 'object' ||
-    Array.isArray(parsed) ||
-    !Array.isArray(parsed.rows) ||
-    typeof parsed.$schema !== 'string'
-  ) {
-    return parsed;
-  }
-  const flat = {};
-  for (const row of parsed.rows) {
-    if (row && typeof row.path === 'string' && typeof row.mi === 'number') {
-      flat[row.path] = row.mi;
-    }
-  }
-  return flat;
-}
-
-export function getBaseline(baselinePath) {
-  if (typeof baselinePath !== 'string' || baselinePath.length === 0) {
-    throw new TypeError(
-      'maintainability-utils.getBaseline: baselinePath is required (Epic #730 ' +
-        'Story 5.5 — callers resolve the path via getBaselines(config).maintainability.path).',
-    );
-  }
-  const abs = path.isAbsolute(baselinePath)
-    ? baselinePath
-    : path.resolve(process.cwd(), baselinePath);
-  if (!fs.existsSync(abs)) return {};
-  try {
-    const parsed = JSON.parse(fs.readFileSync(abs, 'utf-8'));
-    return projectMaintainabilityEnvelopeToFlat(parsed);
-  } catch (err) {
-    Logger.warn(`[Maintainability] Failed to parse baseline: ${err.message}`);
-    return {};
-  }
-}
-
-/**
- * Saves a new maintainability baseline to disk at `baselinePath`.
- *
- * Accepts the legacy flat `{ path: mi }` shape for backwards compatibility
- * with existing callers (`regenerateMainFromTree`, refresh helpers). The
- * map is transformed into the canonical envelope shape (`$schema`,
- * `kernelVersion`, `generatedAt`, `rollup`, `rows`) via the shared
- * `lib/baselines/writer.js` pipeline before being persisted, so every
- * write produces a file that round-trips through `lib/baselines/reader.js`
- * without schema errors.
- *
- * @param {Record<string, number>} baseline  path→MI flat map.
- * @param {string} baselinePath  Required — caller supplies via getBaselines().
- */
-export function saveBaseline(baseline, baselinePath) {
-  if (typeof baselinePath !== 'string' || baselinePath.length === 0) {
-    throw new TypeError(
-      'maintainability-utils.saveBaseline: baselinePath is required.',
-    );
-  }
-  const abs = path.isAbsolute(baselinePath)
-    ? baselinePath
-    : path.resolve(process.cwd(), baselinePath);
-
-  const rows = Object.entries(baseline ?? {}).map(([p, mi]) => ({
-    path: p,
-    mi,
-  }));
-  const envelope = writeBaselineEnvelope({ kind: 'maintainability', rows });
-  writeBaselineFile(abs, envelope);
-}
-
 const IGNORED_DIRS = new Set([
   'node_modules',
   '.git',

package/.agents/scripts/lib/observability/perf-report-readers.js

@@ -16,6 +16,7 @@ import { storyArtifactPath } from '../config/temp-paths.js';
 import { gitSpawn } from '../git-utils.js';
 import { Logger } from '../Logger.js';
 import { read as readSignals } from '../signals/read.js';
+import { concurrentMap } from '../util/concurrent-map.js';
 import { extractStoryPerfSummaryFromComment } from './perf-report-render.js';
 import { forEachLine } from './signals-writer.js';
 
@@ -154,30 +155,38 @@ export async function collectStorySummaries(provider, epicId, logger) {
       ),
   );
 
-  const summaries = [];
-  for (const ticket of storyTickets) {
-    const id = Number(ticket.id ?? ticket.number);
-    if (!Number.isInteger(id) || id < 1) continue;
-    let comments;
-    try {
-      comments = (await provider.getTicketComments(id)) ?? [];
-    } catch (err) {
-      logger.warn?.(
-        `[analyze-execution] getTicketComments(${id}) failed: ${
-          err instanceof Error ? err.message : String(err)
-        }`,
-      );
-      continue;
-    }
-    for (const c of comments) {
-      const parsed = extractStoryPerfSummaryFromComment(c?.body);
-      if (parsed) {
-        summaries.push(parsed);
-        break;
+  // Bounded-parallel comment fetch (Story #3990). Each Story's comment
+  // thread is an independent paginated REST read through a fresh `gh`
+  // spawn, so a serial loop pays N sequential round-trips. concurrentMap
+  // preserves input→output index, keeping summaries in Story order; the
+  // per-Story try/catch stays inside the mapper so one failed fetch
+  // degrades to warn-and-skip without aborting the batch (mirrors
+  // verifySingleResult in lib/orchestration/wave-record-io.js, #3024).
+  const perStory = await concurrentMap(
+    storyTickets,
+    async (ticket) => {
+      const id = Number(ticket.id ?? ticket.number);
+      if (!Number.isInteger(id) || id < 1) return null;
+      let comments;
+      try {
+        comments = (await provider.getTicketComments(id)) ?? [];
+      } catch (err) {
+        logger.warn?.(
+          `[analyze-execution] getTicketComments(${id}) failed: ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+        );
+        return null;
       }
-    }
-  }
-  return summaries;
+      for (const c of comments) {
+        const parsed = extractStoryPerfSummaryFromComment(c?.body);
+        if (parsed) return parsed;
+      }
+      return null;
+    },
+    { concurrency: 4 },
+  );
+  return perStory.filter((s) => s !== null);
 }
 
 /**

package/.agents/scripts/lib/orchestration/acceptance-eval-decision.js

@@ -1,12 +1,22 @@
 /**
  * Acceptance self-eval decision core (Story #3819).
  *
- * Pure, I/O-free reducer that turns one round's critic verdict plus the
- * resolved round cap into the loop's next action. The CLI wrapper
+ * Pure reducer that turns one round's critic verdict plus the resolved
+ * round cap into the loop's next action. The CLI wrapper
  * (`acceptance-eval.js`) owns the file reads, schema validation, signal
  * emission, and ticket transitions; this module owns the *decision* so it
  * can be unit-tested in isolation.
  *
+ * ## Round derivation (Story #4019)
+ *
+ * The round number is **derived from the signals ledger**, not from the
+ * critic's self-reported `verdict.round`: every prior round appended one
+ * `acceptance-eval` signal to the Story's `signals.ndjson`, so the
+ * current round is `count(prior signals) + 1`. This survives a subagent
+ * restart (the ledger is on disk) and removes the critic's scratch value
+ * from the cap enforcement path — a critic that always reports `round: 1`
+ * can no longer defeat the bounded-loop guarantee.
+ *
  * ## The three terminal actions
  *
  *   - `proceed`  — every criterion is `met`. The Story may flip to
@@ -29,6 +39,10 @@
  * possible action is `block`.
  */
 
+import { readFileSync } from 'node:fs';
+
+import { signalsFile } from '../config/temp-paths.js';
+
 /**
  * Verdicts that clear a criterion. Anything else (`partial`, `unmet`, or
  * an unrecognised value) is treated as not-yet-met and triggers rework.
@@ -87,11 +101,16 @@ function partitionCriteria(criteria) {
  * Decide the next loop action from a single round's verdict.
  *
  * @param {object} args
- * @param {{ round?: number, criteria?: Array<object> }} args.verdict
+ * @param {{ criteria?: Array<object> }} args.verdict
  *   A verdict already validated against the acceptance-eval-verdict schema.
+ *   Its `round` field, when present, is ignored — the round is supplied by
+ *   the caller (derived from the signals ledger; Story #4019).
  * @param {number} args.maxRounds
  *   The resolved (already-clamped) redraft ceiling from
  *   `getAcceptanceEval(config).maxRounds`.
+ * @param {number} [args.round]
+ *   The current round number, derived via `deriveAcceptanceEvalRound`.
+ *   Defaults to 1 when absent or invalid.
  * @returns {{
  *   decision: 'proceed' | 'redraft' | 'block',
  *   round: number,
@@ -102,10 +121,9 @@ function partitionCriteria(criteria) {
  *   capReached: boolean,
  * }}
  */
-export function decideAcceptanceEval({ verdict, maxRounds }) {
+export function decideAcceptanceEval({ verdict, maxRounds, round: roundIn }) {
   const cap = effectiveCap(maxRounds);
-  const round =
-    Number.isInteger(verdict?.round) && verdict.round >= 1 ? verdict.round : 1;
+  const round = Number.isInteger(roundIn) && roundIn >= 1 ? roundIn : 1;
   const { metCount, notMet } = partitionCriteria(verdict?.criteria);
   const totalCriteria = metCount + notMet.length;
   const allMet = notMet.length === 0;
@@ -134,7 +152,7 @@ export function decideAcceptanceEval({ verdict, maxRounds }) {
 /**
  * Build the per-criterion acceptance-eval signal payload for the retro /
  * feedback substrate. Carries which acceptance items needed rework and the
- * round count so `/epic-plan` Phase 0 feedback fetch and the retro can
+ * round count so `/plan` Phase 0 feedback fetch and the retro can
  * surface acceptance churn. PII-free by construction — it carries only
  * acceptance-item indices, verdicts, and the terminal decision.
  *
@@ -171,3 +189,59 @@ export function buildAcceptanceEvalSignal({
     },
   };
 }
+
+/**
+ * Derive the current acceptance-eval round for a Story by counting the
+ * `acceptance-eval` signals already appended to the Story's
+ * `signals.ndjson` (Story #4019). Round = prior-signal count + 1, so the
+ * first run reports round 1 and each completed round (which appends one
+ * signal via `acceptance-eval.js`) advances the derived round by one.
+ *
+ * The derivation is restart-safe: the ledger lives on disk, so a subagent
+ * that dies mid-loop and restarts still observes every prior round. A
+ * missing or malformed ledger degrades to round 1 (no prior rounds), and
+ * malformed lines are skipped — observability corruption never wedges the
+ * gate.
+ *
+ * @param {object} args
+ * @param {number|null} args.epicId   Parent Epic ID, or `null` for a
+ *   standalone Story (routes to `<tempRoot>/standalone/stories/...`).
+ * @param {number} args.storyId
+ * @param {object} [args.config]      Resolved config (tempRoot resolution).
+ * @param {(p: string) => string} [args.readFile]  Injectable reader (tests).
+ * @param {(eid: number|null, sid: number, config?: object) => string} [args.signalsPathResolver]
+ *   Injectable path resolver (tests). Defaults to `signalsFile`.
+ * @returns {number} The 1-based current round.
+ */
+export function deriveAcceptanceEvalRound({
+  epicId,
+  storyId,
+  config,
+  readFile = (p) => readFileSync(p, 'utf8'),
+  signalsPathResolver = signalsFile,
+}) {
+  let text;
+  try {
+    text = readFile(signalsPathResolver(epicId ?? null, storyId, config));
+  } catch (_err) {
+    // No ledger yet → no prior rounds.
+    return 1;
+  }
+
+  let priorRounds = 0;
+  for (const line of String(text).split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed === '') continue;
+    let record;
+    try {
+      record = JSON.parse(trimmed);
+    } catch (_err) {
+      continue; // Malformed line — skip, never throw.
+    }
+    if (!record || typeof record !== 'object') continue;
+    if (record.kind !== 'acceptance-eval') continue;
+    if (record.storyId !== storyId) continue;
+    priorRounds += 1;
+  }
+  return priorRounds + 1;
+}

package/.agents/scripts/lib/orchestration/code-review.js

@@ -3,7 +3,7 @@
  *
  * Story #1155 (Epic #1142, 5.40.0) — extracted the helper-driven
  * `epic-code-review` invocation into a callable module so the
- * `/epic-deliver` runner can run Phase D without spawning a child
+ * `/deliver` runner can run Phase D without spawning a child
  * process or routing through an LLM-driven helper.
  *
  * Story #2831 (Epic #2815, Pluggable Code Review) — refactored to load
@@ -16,7 +16,7 @@
  * chain are unchanged.
  *
  * Public API:
- *   - `runCodeReview({ epicId, provider, logger, bus, ... })` →
+ *   - `runCodeReview({ scope, ticketId, provider, logger, bus, ... })` →
  *       `{ status, severity, posted, report, halted, blockerReason }`.
  *
  * Behaviour:
@@ -25,11 +25,11 @@
  *   - Always posts the structured `code-review` comment on the Epic
  *     issue (the adapter never posts; the orchestrator owns persistence).
  *   - Treats severity.critical > 0 as a halting blocker — the merged
- *     `/epic-deliver` runner consults `halted` and refuses to advance
+ *     `/deliver` runner consults `halted` and refuses to advance
  *     to Phase E (retro) when set.
  *
  * Halting on critical findings is the in-process replacement for the
- * helper's "operator must remediate before /epic-deliver" gate.
+ * helper's "operator must remediate before /deliver" gate.
  */
 
 import { resolveConfig } from '../config-resolver.js';
@@ -116,7 +116,7 @@ function resolveTaskSizing(config) {
  *
  * Best-effort and total: a missing/unparseable checkpoint, an absent
  * `planningRisk` field, a read failure, or a malformed `overallLevel` all
- * degrade to `standard` (never throws). So an Epic that skipped `/epic-plan`
+ * degrade to `standard` (never throws). So an Epic that skipped `/plan`
  * (no checkpoint) still gets a passing `standard` review with no new failure
  * mode. The producer resolves depth from the judged risk alone (the diff is
  * not yet enumerated at this point); the full risk + diff-width combination is
@@ -302,90 +302,106 @@ function buildCodeReviewEndPayload({ epicId, result, durationMs }) {
 }
 
 /**
- * Resolve the scope envelope from the (legacy `epicId` + optional
- * `baseBranch`) shape OR the (new `scope`/`ticketId`/`headRef`/
- * `commentTargetId`) shape into a single normalized record. Extracted to
- * keep `runCodeReview` body below the CRAP-cyclomatic ceiling.
+ * Resolve the project base branch fallback used when a caller omits
+ * `baseRef`.
+ */
+function resolveConfigBase(config) {
+  return (
+    config?.project?.baseBranch ?? config?.agentSettings?.baseBranch ?? 'main'
+  );
+}
+
+/** Positive-integer override, else the supplied default. */
+function resolveCommentTargetId(commentTargetId, fallback) {
+  return Number.isInteger(commentTargetId) && commentTargetId > 0
+    ? commentTargetId
+    : fallback;
+}
+
+/**
+ * Resolve the Story-scope envelope from the parameterized
+ * `{ scope: 'story', ticketId, baseRef, headRef, commentTargetId }` shape.
  *
- * @param {{
- *   epicId?: number,
- *   scope?: 'epic'|'story',
- *   ticketId?: number,
- *   baseBranch?: string|null,
- *   baseRef?: string|null,
- *   headRef?: string|null,
- *   commentTargetId?: number|null,
- * }} opts
- * @param {object} config
  * @returns {{
- *   scope: 'epic'|'story',
+ *   scope: 'story',
  *   ticketId: number,
  *   baseRef: string,
  *   headRef: string,
  *   commentTargetId: number,
- *   epicIdForLedger: number|null,
+ *   epicIdForLedger: null,
  * }}
  */
-function resolveScopeEnvelope(opts, config) {
-  const explicitScope = opts.scope;
-  const epicIdLegacy = opts.epicId;
-  const configBase =
-    config?.project?.baseBranch ?? config?.agentSettings?.baseBranch ?? 'main';
-
-  if (explicitScope === 'story') {
-    if (!Number.isInteger(opts.ticketId) || opts.ticketId <= 0) {
-      throw new TypeError(
-        'runCodeReview: ticketId is required (positive integer) when scope="story".',
-      );
-    }
-    if (typeof opts.headRef !== 'string' || opts.headRef.length === 0) {
-      throw new TypeError(
-        'runCodeReview: headRef is required (non-empty string) when scope="story".',
-      );
-    }
-    const baseRef = opts.baseRef ?? opts.baseBranch ?? configBase;
-    const commentTargetId =
-      Number.isInteger(opts.commentTargetId) && opts.commentTargetId > 0
-        ? opts.commentTargetId
-        : opts.ticketId;
-    return {
-      scope: 'story',
-      ticketId: opts.ticketId,
-      baseRef,
-      headRef: opts.headRef,
-      commentTargetId,
-      epicIdForLedger: null,
-    };
+function resolveStoryScope(opts, config) {
+  if (!Number.isInteger(opts.ticketId) || opts.ticketId <= 0) {
+    throw new TypeError(
+      'runCodeReview: ticketId is required (positive integer) when scope="story".',
+    );
+  }
+  if (typeof opts.headRef !== 'string' || opts.headRef.length === 0) {
+    throw new TypeError(
+      'runCodeReview: headRef is required (non-empty string) when scope="story".',
+    );
   }
+  return {
+    scope: 'story',
+    ticketId: opts.ticketId,
+    baseRef: opts.baseRef ?? resolveConfigBase(config),
+    headRef: opts.headRef,
+    commentTargetId: resolveCommentTargetId(
+      opts.commentTargetId,
+      opts.ticketId,
+    ),
+    epicIdForLedger: null,
+  };
+}
 
-  // Epic scope (default + legacy `epicId` callers).
-  const effectiveEpicId =
-    Number.isInteger(opts.ticketId) && opts.ticketId > 0
-      ? opts.ticketId
-      : epicIdLegacy;
-  if (!Number.isInteger(effectiveEpicId) || effectiveEpicId <= 0) {
+/**
+ * Resolve the Epic-scope envelope from the parameterized
+ * `{ scope: 'epic', ticketId, baseRef, headRef, commentTargetId }` shape.
+ * `headRef` defaults to `epic/<ticketId>` and `baseRef` to the project
+ * base branch.
+ *
+ * @returns {{
+ *   scope: 'epic',
+ *   ticketId: number,
+ *   baseRef: string,
+ *   headRef: string,
+ *   commentTargetId: number,
+ *   epicIdForLedger: number,
+ * }}
+ */
+function resolveEpicScope(opts, config) {
+  if (!Number.isInteger(opts.ticketId) || opts.ticketId <= 0) {
     throw new TypeError(
-      'runCodeReview: epicId is required (positive integer).',
+      'runCodeReview: ticketId is required (positive integer) when scope="epic".',
     );
   }
-  const baseRef = opts.baseRef ?? opts.baseBranch ?? configBase;
-  const headRef = opts.headRef ?? `epic/${effectiveEpicId}`;
-  const commentTargetId =
-    Number.isInteger(opts.commentTargetId) && opts.commentTargetId > 0
-      ? opts.commentTargetId
-      : effectiveEpicId;
   return {
     scope: 'epic',
-    ticketId: effectiveEpicId,
-    baseRef,
-    headRef,
-    commentTargetId,
-    epicIdForLedger: effectiveEpicId,
+    ticketId: opts.ticketId,
+    baseRef: opts.baseRef ?? resolveConfigBase(config),
+    headRef: opts.headRef ?? `epic/${opts.ticketId}`,
+    commentTargetId: resolveCommentTargetId(
+      opts.commentTargetId,
+      opts.ticketId,
+    ),
+    epicIdForLedger: opts.ticketId,
   };
 }
 
 /**
- * In-process wrapper that the `/epic-deliver` runner and the
+ * Dispatch the parameterized scope envelope
+ * (`{ scope, ticketId, baseRef, headRef, commentTargetId }`) to the
+ * matching pure resolver. `scope` defaults to `'epic'`.
+ */
+function resolveScopeEnvelope(opts, config) {
+  return opts.scope === 'story'
+    ? resolveStoryScope(opts, config)
+    : resolveEpicScope(opts, config);
+}
+
+/**
+ * In-process wrapper that the `/deliver` runner and the
  * `/single-story-deliver` close path consume.
  *
  * Story #2252 — emits `code-review.start` immediately on entry and
@@ -407,26 +423,23 @@ function resolveScopeEnvelope(opts, config) {
  * `scope: 'epic'` because the `code-review.end` schema requires
  * `epicId` and the ledger only spans Epic lifecycles.
  *
- * Argument shapes:
- *   - Legacy (Epic):
- *       `{ epicId, provider, bus, [baseBranch] }`
- *   - Parameterized (Epic or Story):
- *       `{ scope, ticketId, baseRef, headRef, [commentTargetId],
- *          provider, bus }`
- *     For `scope === 'story'`, `commentTargetId` overrides the post
- *     target (e.g. PR number) while `ticketId` continues to label the
- *     rendered header ("Story #N").
+ * Argument shape (parameterized, Epic or Story):
+ *   `{ scope, ticketId, baseRef, headRef, [commentTargetId],
+ *      provider, bus }`
+ *   `scope` defaults to `'epic'`; `baseRef` defaults to the project base
+ *   branch and (Epic scope only) `headRef` defaults to `epic/<ticketId>`.
+ *   For `scope === 'story'`, `commentTargetId` overrides the post
+ *   target (e.g. PR number) while `ticketId` continues to label the
+ *   rendered header ("Story #N").
  *
  * @param {{
- *   epicId?: number,
  *   scope?: 'epic'|'story',
- *   ticketId?: number,
+ *   ticketId: number,
  *   baseRef?: string|null,
  *   headRef?: string|null,
  *   commentTargetId?: number|null,
  *   provider: object,
  *   logger?: { info?: Function, warn?: Function, error?: Function, fatal?: Function, createProgress?: Function },
- *   baseBranch?: string|null,
  *   planningRisk?: { overallLevel?: ('low'|'medium'|'high'), axes?: Array<{ axis?: string, level?: string }> }|null,
  *   changedFileCount?: number|null,
  *   storyId?: number|null,