mandrel 1.94.0 → 2.1.0

package/.agents/scripts/lib/orchestration/spec-freshness.js

@@ -1,29 +1,12 @@
 /**
- * spec-freshness.js — Tech Spec post-author cross-validation against the
- * current codebase.
+ * spec-freshness.js — path-reference helpers for plan authoring.
  *
- * `/plan` Phase 7 authors the Tech Spec from documentation alone.
- * When `project.docsContextFiles` (architecture.md, etc.) drift from
- * the real source tree, the Architect persona happily cites modules and
- * paths that no longer exist. The mismatch only surfaces at delivery time,
- * after Phase 8 has already decomposed the stale spec into Tasks.
- *
- * `validateSpecFreshness` scans a Tech Spec body for path-shaped references,
- * probes each against `baseBranchRef` (via `git cat-file -e`), and returns a
- * `{ stale, fresh, ambiguous }` envelope. The caller (plan-persist.js)
- * uses the result to write a JSON report and post an advisory structured
- * comment on the Epic. The check is intentionally non-blocking —
- * planning continues even when stale references are present, because the
- * operator may legitimately be planning to create the path the Tech Spec
- * cites.
- *
- * Sibling to {@link ./ticket-validator.js#validateAcFreshness}, which runs at
- * Phase 8 (decompose) time against Task bodies. This module operates one
- * phase earlier, on the spec body that feeds the decomposer.
+ * Stage 5 retired the epic-era `validateSpecFreshness` / structured-comment
+ * reporter (no production callers remained after the planning collapse).
+ * Survivors: path-cue extraction used by `planning/authoring-context.js`
+ * and the plan-authoring grounding tests.
  */
 
-import { gitSpawn } from '../git-utils.js';
-
 /**
  * Path-shape regexes. Three forms the Architect persona emits today:
  *
@@ -68,11 +51,7 @@ const BARE_PATH_RE = new RegExp(
  * Words in surrounding prose that signal a reference is intentionally
  * net-new — the planner is *proposing* the path, not asserting it exists.
  * When any of these appear within `AMBIGUITY_WINDOW` characters of the
- * match, we mark the reference `ambiguous` rather than `stale`.
- *
- * Conservative on purpose: false-positives here downgrade real staleness
- * to ambiguity, but the operator-visible comment still lists the path so
- * nothing is hidden — just demoted in the report's headline count.
+ * match, we treat the citation as intentional rather than drift.
  */
 const NEW_FILE_CUES = [
   'introduce',
@@ -97,40 +76,6 @@ const NEW_FILE_CUES = [
 
 const AMBIGUITY_WINDOW = 80;
 
-/**
- * Default git probe: returns true when `path` exists at `baseBranchRef`.
- * Mirrors the probe in ticket-validator.js so the two freshness gates
- * share semantics. Callers may inject a `(opts) => boolean` runner with
- * the same shape for unit tests.
- *
- * @param {{ baseBranchRef: string, path: string, cwd?: string }} opts
- * @returns {boolean}
- */
-function defaultGitRunner({ baseBranchRef, path, cwd }) {
-  const result = gitSpawn(
-    cwd ?? process.cwd(),
-    'cat-file',
-    '-e',
-    `${baseBranchRef}:${path}`,
-  );
-  return result.status === 0;
-}
-
-/**
- * Find the 1-based line number for a string index into `body`.
- *
- * @param {string} body
- * @param {number} index
- * @returns {number}
- */
-function lineNumberFor(body, index) {
-  let line = 1;
-  for (let i = 0; i < index && i < body.length; i += 1) {
-    if (body.charCodeAt(i) === 10) line += 1;
-  }
-  return line;
-}
-
 /**
  * Check whether the prose surrounding `index` carries one of the
  * net-new cue phrases. Looks both before and after the match within
@@ -138,8 +83,12 @@ function lineNumberFor(body, index) {
  * way: "introduce src/x.ts" *or* "src/x.ts (new helper)".
  *
  * Case-insensitive substring match — deliberately not regex/word-boundary
- * so future cue variants don't silently slip the gate. False positives
- * downgrade staleness to ambiguity, which is the safe direction.
+ * so future cue variants don't silently slip the gate.
+ *
+ * @param {string} body
+ * @param {number} index
+ * @param {number} matchLength
+ * @returns {boolean}
  */
 export function hasNewFileCue(body, index, matchLength) {
   const start = Math.max(0, index - AMBIGUITY_WINDOW);
@@ -154,8 +103,8 @@ export function hasNewFileCue(body, index, matchLength) {
 /**
  * Collect every `(path, index, matchLength)` triple from `body` using the
  * three path-shape regexes. The same path can surface at multiple indices —
- * each callsite is preserved so the report can cite every line and the
- * ambiguity check runs against the cue at *that* index, not a different one.
+ * each callsite is preserved so the ambiguity check runs against the cue at
+ * *that* index, not a different one.
  *
  * @param {string} body
  * @returns {Array<{ path: string, index: number, matchLength: number }>}
@@ -178,143 +127,3 @@ export function collectReferences(body) {
   }
   return refs;
 }
-
-/**
- * Validate every code-asset path the Tech Spec body references against
- * `baseBranchRef`. Returns a `{ stale, fresh, ambiguous }` envelope.
- *
- * Each result element has the shape `{ path, line }` — `line` is the
- * 1-based line number of the *first* citation of `path` in `body`. When
- * the same path appears multiple times, the result is deduped by path
- * but `citations` carries every `{ line }` for downstream rendering.
- *
- * Buckets:
- *   - `stale`     — path is absent from `baseBranchRef` and prose has no
- *                   new-file cue nearby. Real likely-hallucinated reference.
- *   - `fresh`     — path exists at `baseBranchRef`. No action needed.
- *   - `ambiguous` — path is absent from `baseBranchRef` but surrounding
- *                   prose carries a new-file cue. Probably intentional;
- *                   surfaced for operator review without alarming the
- *                   headline count.
- *
- * The function never throws on a missing git ref — the runner is
- * expected to return `false` for any unreadable probe and the path lands
- * in `stale` (or `ambiguous`). Non-blocking by design.
- *
- * @param {string} specBody
- * @param {{ baseBranchRef: string, gitRunner?: Function, cwd?: string }} opts
- * @returns {{ stale: Array, fresh: Array, ambiguous: Array }}
- */
-export function validateSpecFreshness(specBody, opts = {}) {
-  if (typeof specBody !== 'string') {
-    throw new TypeError('validateSpecFreshness: specBody must be a string.');
-  }
-  const { baseBranchRef, gitRunner = defaultGitRunner, cwd } = opts;
-  if (!baseBranchRef || typeof baseBranchRef !== 'string') {
-    throw new Error(
-      'validateSpecFreshness: baseBranchRef is required and must be a string.',
-    );
-  }
-
-  const refs = collectReferences(specBody);
-  const probeCache = new Map();
-  const buckets = { stale: [], fresh: [], ambiguous: [] };
-  const seen = new Map(); // path → bucket entry
-
-  for (const { path, index, matchLength } of refs) {
-    const line = lineNumberFor(specBody, index);
-    let exists = probeCache.get(path);
-    if (exists === undefined) {
-      exists = gitRunner({ baseBranchRef, path, cwd });
-      probeCache.set(path, exists);
-    }
-    let bucket;
-    if (exists) {
-      bucket = 'fresh';
-    } else if (hasNewFileCue(specBody, index, matchLength)) {
-      bucket = 'ambiguous';
-    } else {
-      bucket = 'stale';
-    }
-    const existing = seen.get(path);
-    if (existing) {
-      // Same path cited multiple times. Append the citation and, if any
-      // citation lacks a new-file cue, downgrade to stale — the most
-      // serious bucket wins so the operator sees the strongest signal.
-      existing.citations.push({ line });
-      if (existing.bucket === 'ambiguous' && bucket === 'stale') {
-        // Move entry from ambiguous → stale.
-        const idx = buckets.ambiguous.indexOf(existing);
-        if (idx >= 0) buckets.ambiguous.splice(idx, 1);
-        existing.bucket = 'stale';
-        buckets.stale.push(existing);
-      }
-      continue;
-    }
-    const entry = { path, line, citations: [{ line }], bucket };
-    seen.set(path, entry);
-    buckets[bucket].push(entry);
-  }
-
-  // Strip the internal `bucket` field from the returned envelope — it's a
-  // scratch marker only the dedupe pass cares about.
-  const strip = (arr) =>
-    arr.map(({ path, line, citations }) => ({ path, line, citations }));
-  return {
-    stale: strip(buckets.stale),
-    fresh: strip(buckets.fresh),
-    ambiguous: strip(buckets.ambiguous),
-  };
-}
-
-/**
- * Render the Markdown body for the `spec-freshness` structured comment.
- * Kept in this module so the comment shape and the validator stay in
- * lock-step — a reviewer reading the report knows where to find the
- * exact rendering contract.
- *
- * @param {{ stale: Array, ambiguous: Array, fresh: Array }} report
- * @param {{ baseBranchRef: string, epicId?: number }} ctx
- * @returns {string}
- */
-export function renderSpecFreshnessComment(report, ctx) {
-  const { baseBranchRef, epicId } = ctx;
-  const staleCount = report.stale.length;
-  const ambiguousCount = report.ambiguous.length;
-  const freshCount = report.fresh.length;
-  const header = epicId
-    ? `## Tech Spec freshness check (Epic #${epicId})`
-    : '## Tech Spec freshness check';
-  const summary = `${staleCount} stale · ${ambiguousCount} ambiguous · ${freshCount} fresh against \`${baseBranchRef}\`.`;
-  const sections = [header, '', summary, ''];
-  if (staleCount > 0) {
-    sections.push('### Stale references');
-    sections.push('');
-    sections.push(
-      'These paths do not exist at the base branch and the surrounding prose does not signal them as net-new. Either correct the citation or rephrase the spec to mark the path as net-new.',
-    );
-    sections.push('');
-    for (const entry of report.stale) {
-      const lines = entry.citations.map((c) => `L${c.line}`).join(', ');
-      sections.push(`- \`${entry.path}\` (${lines})`);
-    }
-    sections.push('');
-  }
-  if (ambiguousCount > 0) {
-    sections.push('### Ambiguous references');
-    sections.push('');
-    sections.push(
-      'These paths do not exist at the base branch but the surrounding prose suggests they are net-new. Confirm or correct.',
-    );
-    sections.push('');
-    for (const entry of report.ambiguous) {
-      const lines = entry.citations.map((c) => `L${c.line}`).join(', ');
-      sections.push(`- \`${entry.path}\` (${lines})`);
-    }
-    sections.push('');
-  }
-  sections.push(
-    '_This is an advisory check; planning continues regardless. Sourced from `spec-freshness.js` after Phase 7 spec authoring._',
-  );
-  return sections.join('\n');
-}

package/.agents/scripts/lib/orchestration/spec-section-validator.js

@@ -22,10 +22,9 @@
  * retired; `runSpecPhase` (`phases/run-spec-phase.js`) now calls
  * `validateSpecSections` directly against the in-memory authored content as
  * part of its input validation, before any GitHub mutation. This is the
- * Phase 8-side counterpart to the Phase 6 Epic Clarity Gate
- * ({@link ../epic-plan-clarity.js#scoreEpicBody}) — same detect-then-prompt
- * pattern, one phase later, but a hard gate (fail closed) rather than an
- * advisory rubric.
+ * Phase 8-side counterpart to the retired Phase 6 Epic Clarity Gate —
+ * same detect-then-prompt pattern, one phase later, but a hard gate
+ * (fail closed) rather than an advisory rubric.
  *
  * `validateSpecSections` and `formatMissingSectionMessage` are pure, I/O-free
  * helpers. `validateSpecFile` is a thin disk-reading convenience for callers
@@ -33,7 +32,7 @@
  */
 
 import { readFile } from 'node:fs/promises';
-import { DELIVERY_SLICING_RE } from '../epic-body-sections.js';
+import { DELIVERY_SLICING_RE } from '../ticket-body-sections.js';
 
 /**
  * The single required Tech Spec section, with the heading variants the

package/.agents/scripts/lib/orchestration/spec-spill.js

@@ -0,0 +1,60 @@
+/**
+ * v2 Story `## Spec` budget gate.
+ *
+ * The Story body is the single executable document: Tech Spec prose stays
+ * inline under `## Spec`. There is no spill-to-`docs/` path — an over-budget
+ * Spec is treated as a sizing smell (the Story should be split or the Spec
+ * tightened), not as a reason to write temporary product docs.
+ *
+ * The budget reuses the §2 FinOps estimator ({@link estimateTokens}, ~4
+ * chars/token) so the threshold speaks the same units as hydration budgets.
+ *
+ * @module lib/orchestration/spec-spill
+ */
+
+import { estimateTokens } from './context-envelope.js';
+
+/**
+ * Soft budget (estimated tokens) for an inline `## Spec`. ~1500 tokens ≈ 6KB —
+ * enough for a real approach section, well under issue-body bloat.
+ */
+export const DEFAULT_SPEC_BODY_TOKEN_BUDGET = 1500;
+
+/**
+ * @typedef {object} SpecBudgetResult
+ * @property {number} estimatedTokens
+ * @property {string} content
+ */
+
+/**
+ * Keep Spec inline when it fits; throw when it exceeds the budget so the
+ * planner splits or tightens instead of writing docs/.
+ *
+ * @param {object} args
+ * @param {string} args.storyId  Story slug/id for error context.
+ * @param {string} args.spec     Folded Tech Spec markdown.
+ * @param {object} [opts]
+ * @param {number} [opts.tokenBudget=DEFAULT_SPEC_BODY_TOKEN_BUDGET]
+ * @returns {SpecBudgetResult}
+ */
+export function assertSpecWithinBudget({ storyId, spec }, opts = {}) {
+  const { tokenBudget = DEFAULT_SPEC_BODY_TOKEN_BUDGET } = opts;
+  const content = typeof spec === 'string' ? spec : '';
+  const estimatedTokens = estimateTokens(content);
+
+  if (estimatedTokens <= tokenBudget) {
+    return { estimatedTokens, content };
+  }
+
+  const label =
+    typeof storyId === 'string' && storyId.trim() !== ''
+      ? storyId.trim()
+      : 'unknown';
+
+  throw new Error(
+    `[plan-persist] Story "${label}" ## Spec is ~${estimatedTokens} tokens ` +
+      `(budget ${tokenBudget}). An over-budget Spec usually means the Story ` +
+      `is too large — split it, or tighten ## Spec so the Story body stays ` +
+      `the single executable document. Specs are never written to docs/.`,
+  );
+}

package/.agents/scripts/lib/orchestration/split-policy-validator.js

@@ -0,0 +1,188 @@
+/**
+ * v2 split-policy validator — the plan-time "one-owner-AC" split rejector.
+ *
+ * Under the v2 default-single split policy (`docs/roadmap.md` § v2.0.0), a
+ * plan authors **one Story by default**; it splits into N>1 Stories only when
+ * the pieces have near-zero overlap or sit across an architectural seam. This
+ * validator is the deterministic guardrail on that policy: **every acceptance
+ * criterion must belong to exactly one Story.** An identical AC appearing in
+ * two Stories is evidence the split coupled what should have stayed one Story,
+ * so the plan is refused rather than reconciled at delivery time (there is no
+ * epic-level acceptance reconcile in v2).
+ *
+ * Scope of the deterministic check:
+ *   - **Cross-Story duplication** (always): the same normalized AC text must
+ *     not appear in more than one Story.
+ *   - **Full coverage** (optional, when a plan-level `acceptance` manifest is
+ *     supplied): every manifest AC is claimed by exactly one Story, and no
+ *     Story claims an AC absent from the manifest.
+ *
+ * Semantic overlap between differently-worded ACs is **not** caught here — it
+ * is a gate-#2 review call. This validator only sees identical (normalized)
+ * text, keeping it deterministic and false-positive-free.
+ *
+ * Normalization for comparison: trim, collapse internal whitespace, and
+ * lower-case. Reporting always uses the first-seen original text.
+ */
+
+/**
+ * Normalize an acceptance string for equality comparison. Trims, collapses
+ * runs of whitespace to a single space, and lower-cases. Non-strings and
+ * empty/whitespace-only strings normalize to `null` (ignored).
+ *
+ * @param {unknown} ac
+ * @returns {string | null}
+ */
+export function normalizeAcceptance(ac) {
+  if (typeof ac !== 'string') return null;
+  const norm = ac.trim().replace(/\s+/g, ' ').toLowerCase();
+  return norm === '' ? null : norm;
+}
+
+/**
+ * @typedef {object} StorySlice
+ * @property {string} [id]        Story identifier for reporting (slug or #id).
+ * @property {string} [slug]      Alternate identifier (used when `id` absent).
+ * @property {string[]} acceptance Acceptance criteria this Story claims.
+ */
+
+/**
+ * @typedef {object} SplitPolicyViolation
+ * @property {'cross-story-duplicate'|'orphan-ac'|'unclaimed-manifest-ac'} kind
+ * @property {string} acceptance The original (first-seen) AC text.
+ * @property {string[]} [stories] Story ids sharing a duplicated AC (`cross-story-duplicate`).
+ * @property {string}   [story]   Story id owning an AC absent from the manifest (`orphan-ac`).
+ */
+
+/**
+ * Resolve a Story's reporting id.
+ *
+ * @param {StorySlice} story
+ * @param {number} index
+ * @returns {string}
+ */
+function storyId(story, index) {
+  if (story && typeof story.id === 'string' && story.id.trim() !== '') {
+    return story.id;
+  }
+  if (story && typeof story.slug === 'string' && story.slug.trim() !== '') {
+    return story.slug;
+  }
+  return `story[${index}]`;
+}
+
+/**
+ * Validate that acceptance criteria partition cleanly across Stories.
+ *
+ * @param {StorySlice[]} stories The plan's Stories, each with `acceptance[]`.
+ * @param {object} [opts]
+ * @param {string[]} [opts.planAcceptance] Optional plan-level acceptance
+ *   manifest. When supplied, coverage is enforced (every manifest AC claimed
+ *   exactly once; no Story claims an off-manifest AC).
+ * @returns {{ ok: boolean, violations: SplitPolicyViolation[] }}
+ */
+export function validateAcceptancePartition(stories, opts = {}) {
+  const violations = [];
+  const list = Array.isArray(stories) ? stories : [];
+
+  // normalized AC → { original, owners: Set<storyId> }
+  const owners = new Map();
+  list.forEach((story, index) => {
+    const id = storyId(story, index);
+    const acceptance = Array.isArray(story?.acceptance) ? story.acceptance : [];
+    for (const ac of acceptance) {
+      const norm = normalizeAcceptance(ac);
+      if (norm === null) continue;
+      const existing = owners.get(norm);
+      if (existing) {
+        existing.owners.add(id);
+      } else {
+        owners.set(norm, { original: ac.trim(), owners: new Set([id]) });
+      }
+    }
+  });
+
+  // Cross-Story duplication: any AC owned by more than one Story.
+  for (const { original, owners: set } of owners.values()) {
+    if (set.size > 1) {
+      violations.push({
+        kind: 'cross-story-duplicate',
+        acceptance: original,
+        stories: [...set],
+      });
+    }
+  }
+
+  // Optional coverage check against a plan-level manifest.
+  const manifest = Array.isArray(opts.planAcceptance)
+    ? opts.planAcceptance
+    : null;
+  if (manifest !== null) {
+    const manifestNorms = new Map();
+    for (const ac of manifest) {
+      const norm = normalizeAcceptance(ac);
+      if (norm !== null && !manifestNorms.has(norm)) {
+        manifestNorms.set(norm, ac.trim());
+      }
+    }
+    // Every manifest AC must be claimed by exactly one Story.
+    for (const [norm, original] of manifestNorms) {
+      if (!owners.has(norm)) {
+        violations.push({
+          kind: 'unclaimed-manifest-ac',
+          acceptance: original,
+        });
+      }
+    }
+    // No Story may claim an AC absent from the manifest.
+    for (const [norm, { original, owners: set }] of owners) {
+      if (!manifestNorms.has(norm)) {
+        violations.push({
+          kind: 'orphan-ac',
+          acceptance: original,
+          story: [...set][0],
+        });
+      }
+    }
+  }
+
+  return { ok: violations.length === 0, violations };
+}
+
+/**
+ * Render a single violation as a human-readable line.
+ *
+ * @param {SplitPolicyViolation} v
+ * @returns {string}
+ */
+function formatViolation(v) {
+  switch (v.kind) {
+    case 'cross-story-duplicate':
+      return `acceptance criterion appears in ${v.stories.length} Stories (${v.stories.join(', ')}) — a coupled split; keep it one Story: "${v.acceptance}"`;
+    case 'unclaimed-manifest-ac':
+      return `plan acceptance criterion is claimed by no Story: "${v.acceptance}"`;
+    case 'orphan-ac':
+      return `Story ${v.story} claims an acceptance criterion absent from the plan manifest: "${v.acceptance}"`;
+    default:
+      return `unknown split-policy violation: "${v.acceptance}"`;
+  }
+}
+
+/**
+ * Throwing wrapper for the persist path: throws a single batched error when
+ * the acceptance criteria do not partition cleanly, otherwise returns
+ * `stories` unchanged. Wired into `plan-persist` in Stage 3.
+ *
+ * @param {StorySlice[]} stories
+ * @param {object} [opts] See {@link validateAcceptancePartition}.
+ * @returns {StorySlice[]}
+ */
+export function assertAcceptancePartition(stories, opts = {}) {
+  const { ok, violations } = validateAcceptancePartition(stories, opts);
+  if (ok) return stories;
+  throw new Error(
+    `[split-policy] ${violations.length} acceptance-partition violation(s) — the plan splits coupled work; refuse:\n${violations
+      .map((v) => `  - ${formatViolation(v)}`)
+      .join('\n')}`,
+  );
+}

package/.agents/scripts/lib/orchestration/story-close/emit-blocked.js

@@ -0,0 +1,49 @@
+/**
+ * Best-effort blocked-close result helper shared by Story-scope review.
+ *
+ * @module lib/orchestration/story-close/emit-blocked
+ */
+
+import { Logger } from '../../Logger.js';
+
+/**
+ * Best-effort `story.blocked` lifecycle emit. The bus is optional and emit
+ * failures are swallowed so the blocked result remains the caller-visible
+ * outcome.
+ */
+async function emitStoryBlockedSafe({ bus, storyId, reason, logger }) {
+  if (!bus) return;
+  try {
+    await bus.emit('story.blocked', {
+      storyId: Number(storyId),
+      reason: String(reason),
+    });
+  } catch (err) {
+    logger?.warn?.(
+      `[story-close] story.blocked emit failed for #${storyId} (swallowed): ${err?.message ?? err}`,
+    );
+  }
+}
+
+/**
+ * @param {object} args
+ * @returns {Promise<object>}
+ */
+export async function emitBlockedCloseResult({
+  storyId,
+  phase,
+  reason,
+  extra = {},
+  bus = null,
+  progress,
+  blockedMessage,
+  logger = Logger,
+}) {
+  const result = { success: false, status: 'blocked', phase, reason, ...extra };
+  await emitStoryBlockedSafe({ bus, storyId, reason, logger });
+  logger.info?.(
+    `\n--- STORY CLOSE RESULT ---\n${JSON.stringify(result, null, 2)}\n--- END RESULT ---\n`,
+  );
+  progress('BLOCKED', blockedMessage);
+  return result;
+}

package/.agents/scripts/lib/orchestration/story-close/format-autofix.js

@@ -328,7 +328,7 @@ export function runFormatAutofix({
 }
 
 /**
- * List the files changed between `epicBranch` and `storyBranch` using the
+ * List the files changed between `baseBranch` and `storyBranch` using the
  * three-dot merge-base diff. Delegates parsing to `diffNameOnly` from
  * `changed-files.js` so the stdout → path-list conversion lives in one place.
  *
@@ -336,10 +336,10 @@ export function runFormatAutofix({
  * `(args: string[], opts: object) => string`. A bridge adapter wraps it into
  * the `gitSpawn(cwd, ...args)` shape that `diffNameOnly` expects.
  *
- * @param {{ cwd: string, epicBranch: string, storyBranch: string, git: Function }} opts
+ * @param {{ cwd: string, baseBranch: string, storyBranch: string, git: Function }} opts
  * @returns {string[]}
  */
-function listChangedFiles({ cwd, epicBranch, storyBranch, git }) {
+function listChangedFiles({ cwd, baseBranch, storyBranch, git }) {
   // Bridge the (args, opts) → string interface into gitSpawn(cwd, ...args).
   const gitSpawn = (_cwd, ...args) => {
     try {
@@ -358,7 +358,7 @@ function listChangedFiles({ cwd, epicBranch, storyBranch, git }) {
     }
   };
   return diffNameOnly({
-    range: `${epicBranch}...${storyBranch}`,
+    range: `${baseBranch}...${storyBranch}`,
     cwd,
     gitSpawn,
   });
@@ -401,7 +401,7 @@ function listChangedFiles({ cwd, epicBranch, storyBranch, git }) {
  *   cwd: string,
  *   worktreePath?: string,
  *   storyId: number|string,
- *   epicBranch: string,
+ *   baseBranch: string,
  *   storyBranch: string,
  *   config?: object,
  *   logger?: object,
@@ -420,7 +420,7 @@ export function runScopedFormatAutofix({
   cwd,
   worktreePath,
   storyId,
-  epicBranch,
+  baseBranch,
   storyBranch,
   config,
   logger = DefaultLogger,
@@ -428,8 +428,8 @@ export function runScopedFormatAutofix({
   gitSync,
 } = {}) {
   if (!cwd) throw new Error('runScopedFormatAutofix: cwd is required');
-  if (!epicBranch)
-    throw new Error('runScopedFormatAutofix: epicBranch is required');
+  if (!baseBranch)
+    throw new Error('runScopedFormatAutofix: baseBranch is required');
   if (!storyBranch)
     throw new Error('runScopedFormatAutofix: storyBranch is required');
 
@@ -449,13 +449,13 @@ export function runScopedFormatAutofix({
 
   const changed = listChangedFiles({
     cwd: workTree,
-    epicBranch,
+    baseBranch,
     storyBranch,
     git,
   });
   if (changed.length === 0) {
     logger.info?.(
-      `${SCOPED_TAG} skipped — no changed files between ${epicBranch} and ${storyBranch}.`,
+      `${SCOPED_TAG} skipped — no changed files between ${baseBranch} and ${storyBranch}.`,
     );
     return { ran: false, committed: false, reason: 'no-changed-files' };
   }