mandrel 1.57.0

package/.agents/scripts/lib/orchestration/story-close/cd-out-guard.js

@@ -0,0 +1,86 @@
+/**
+ * cd-out-guard.js — pre-flight check that refuses to close while the
+ * operator's shell is still cd'd into the per-story worktree being reaped.
+ *
+ * Extracted from story-close.js (Story #956, Theme A finishing touch) so the
+ * close orchestrator becomes a thin CLI shell.
+ *
+ * On Windows this surfaces as `EBUSY: resource busy or locked, rmdir`
+ * during reap; cross-platform it makes `--cwd` semantics impossible to
+ * honour because git operations target the main repo while the filesystem
+ * mutation targets the worktree the caller is sitting inside.
+ *
+ * Fires only when `--cwd` is set explicitly. Single-tree closures resolve
+ * `workCwd` to the main repo, so the equality check is a tautology there
+ * and we don't reject those.
+ *
+ * Both operands are canonicalized through `fs.realpathSync` before the
+ * equality check (Story #3672). `path.resolve` normalizes `.`/`..` and makes
+ * a path absolute but does NOT resolve symlinks, while `process.cwd()` is
+ * returned fully canonicalized by the OS. On hosts where the working path
+ * contains a symlinked component — most notably macOS, where `/tmp` →
+ * `/private/tmp` and `/var` → `/private/var` — the two strings would never
+ * match, so the guard silently no-opped and failed to fire. Realpath'ing
+ * both sides closes that false-negative.
+ *
+ * Pure: takes inputs, returns a verdict. Exported so the rejection path is
+ * unit-testable without spawning the script. The `realpath` seam is injected
+ * (default `fs.realpathSync`) so tests can drive the symlinked and
+ * non-symlinked cases without touching the filesystem.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Canonicalize a path: resolve symlinks via `realpath`, falling back to
+ * `path.resolve` when the path does not exist yet (`realpathSync` throws on
+ * missing paths). The fallback keeps the comparison correct for
+ * not-yet-created worktree directories.
+ *
+ * @param {string} p
+ * @param {(p: string) => string} realpath
+ * @returns {string}
+ */
+function canonical(p, realpath) {
+  try {
+    return realpath(p);
+  } catch {
+    return path.resolve(p);
+  }
+}
+
+/**
+ * @param {object} opts
+ * @param {boolean} opts.cwdExplicit       True when `--cwd` (or AGENT_WORKTREE_ROOT) was set.
+ * @param {string} opts.mainCwd            Resolved main repo path.
+ * @param {number|string} opts.storyId
+ * @param {string} [opts.worktreeRoot]     `delivery.worktreeIsolation.root` (defaults to `.worktrees`).
+ * @param {string} [opts.currentCwd]       Defaults to `process.cwd()`.
+ * @param {(p: string) => string} [opts.realpath]  Symlink-resolution seam (defaults to `fs.realpathSync`).
+ * @returns {{ ok: true } | { ok: false, message: string }}
+ */
+export function checkCdOutGuard({
+  cwdExplicit,
+  mainCwd,
+  storyId,
+  worktreeRoot = '.worktrees',
+  currentCwd = process.cwd(),
+  realpath = fs.realpathSync,
+}) {
+  if (!cwdExplicit) return { ok: true };
+  const workCwd = canonical(
+    path.resolve(mainCwd, worktreeRoot, `story-${storyId}`),
+    realpath,
+  );
+  const cwd = canonical(currentCwd, realpath);
+  if (cwd !== workCwd) return { ok: true };
+  return {
+    ok: false,
+    message:
+      `Refusing to close while CWD is the worktree being reaped.\n` +
+      `   Current cwd:  ${cwd}\n` +
+      `   Main repo:    ${mainCwd}\n` +
+      `   Run instead:  cd "${mainCwd}" && node .agents/scripts/story-close.js --story ${storyId}`,
+  };
+}

package/.agents/scripts/lib/orchestration/story-close/cleanup-reconciler.js

@@ -0,0 +1,147 @@
+/**
+ * cleanup-reconciler.js — post-merge worktree-cleanup drain + reconciliation.
+ *
+ * Extracted from story-close.js (Story #955, Theme A part 2) so the close
+ * orchestrator becomes a thin CLI shell. This module owns the three
+ * worktree-cleanup helpers that previously lived inline in `runStoryClose`:
+ *
+ *   - drainPendingCleanupAfterClose — drives the `forceDrainPendingCleanup`
+ *     pass that runs after the post-merge pipeline reaps the per-story
+ *     worktree. Logs the drain summary via the supplied progress sink.
+ *   - reconcileCleanupState         — pure helper that folds the drain
+ *     outcome back into the pipeline's `worktreeReap` + `branchCleanup`
+ *     state, lifting `localDeleted` / `remoteDeleted` flags and the
+ *     `closeDrainStatus` enum.
+ *   - getCloseDrainStatus           — names the three deferred-to-sweep
+ *     outcomes (persistent / still-pending / not-found) so callers don't
+ *     have to read a nested ternary.
+ *
+ * No close-time control flow lives here — the helpers are pure functions
+ * (or thin wrappers around an injected `drainFn`) and exercise nothing
+ * outside the worktree-isolation surface.
+ */
+
+import path from 'node:path';
+import { gitSpawn } from '../../git-utils.js';
+import { Logger } from '../../Logger.js';
+import { forceDrainPendingCleanup } from '../../worktree/lifecycle/force-drain.js';
+
+function resolveWorktreeRoot(repoRoot, delivery) {
+  const configuredRoot = delivery?.worktreeIsolation?.root ?? '.worktrees';
+  return path.join(repoRoot, configuredRoot);
+}
+
+export async function drainPendingCleanupAfterClose({
+  repoRoot,
+  delivery,
+  progress: progressFn,
+  logger = Logger,
+  git = { gitSpawn },
+  drainFn = forceDrainPendingCleanup,
+} = {}) {
+  const wtConfig = delivery?.worktreeIsolation;
+  if (!wtConfig?.enabled) return null;
+  const worktreeRoot = resolveWorktreeRoot(repoRoot, delivery);
+  const result = await drainFn({
+    repoRoot,
+    worktreeRoot,
+    git,
+    logger,
+  });
+  const totalResolved =
+    (result.drained?.length ?? 0) +
+    (result.persistent?.length ?? 0) +
+    (result.stillPending?.length ?? 0);
+  if (totalResolved > 0 && typeof progressFn === 'function') {
+    progressFn(
+      'WORKTREE',
+      `Pending cleanup drain: drained=${result.drained.length}, persistent=${result.persistent.length}, stillPending=${result.stillPending.length}`,
+    );
+  }
+  return { worktreeRoot, ...result };
+}
+
+const REAP_STATUSES_DRAIN_FLIPS = new Set([
+  'deferred-to-sweep',
+  'stale-registry-entry',
+]);
+
+function applyDrainedEntry(nextWorktreeReap, nextBranchCleanup, drainedEntry) {
+  if (drainedEntry.localBranchDeleted !== null) {
+    nextBranchCleanup.localDeleted =
+      nextBranchCleanup.localDeleted || !!drainedEntry.localBranchDeleted;
+  }
+  if (drainedEntry.remoteBranchDeleted !== null) {
+    nextBranchCleanup.remoteDeleted =
+      nextBranchCleanup.remoteDeleted || !!drainedEntry.remoteBranchDeleted;
+  }
+  if (REAP_STATUSES_DRAIN_FLIPS.has(nextWorktreeReap.status)) {
+    nextWorktreeReap.status = 'removed-after-drain';
+  }
+  nextWorktreeReap.pendingCleanup = null;
+  nextWorktreeReap.closeDrainStatus = 'drained';
+}
+
+export function reconcileCleanupState({
+  storyId,
+  worktreeReap,
+  branchCleanup,
+  pendingCleanupDrain,
+}) {
+  const normalizedStoryId = Number(storyId);
+  const nextWorktreeReap = worktreeReap ? { ...worktreeReap } : null;
+  const nextBranchCleanup = branchCleanup ? { ...branchCleanup } : null;
+  if (!pendingCleanupDrain || !nextWorktreeReap || !nextBranchCleanup) {
+    return { worktreeReap: nextWorktreeReap, branchCleanup: nextBranchCleanup };
+  }
+
+  const drainedEntry =
+    pendingCleanupDrain.drainedDetails?.find(
+      (entry) => Number(entry.storyId) === normalizedStoryId,
+    ) ?? null;
+
+  if (drainedEntry) {
+    applyDrainedEntry(nextWorktreeReap, nextBranchCleanup, drainedEntry);
+    return { worktreeReap: nextWorktreeReap, branchCleanup: nextBranchCleanup };
+  }
+
+  if (REAP_STATUSES_DRAIN_FLIPS.has(nextWorktreeReap.status)) {
+    nextWorktreeReap.closeDrainStatus = getCloseDrainStatus({
+      isPersistent:
+        pendingCleanupDrain.persistent?.includes(normalizedStoryId) ?? false,
+      isStillPending:
+        pendingCleanupDrain.stillPending?.includes(normalizedStoryId) ?? false,
+    });
+  }
+
+  return { worktreeReap: nextWorktreeReap, branchCleanup: nextBranchCleanup };
+}
+
+/**
+ * Resolve the deferred-to-sweep close-drain status when the current Story's
+ * pending-cleanup entry was *not* drained on this close. Three outcomes:
+ *
+ *   - `'persistent'`   — the entry has hit the persistent-lock threshold
+ *                        (`MAX_SWEEP_ATTEMPTS` reached). `isPersistent` wins
+ *                        regardless of whether the entry is also still in
+ *                        the live pending list, because operator-action is
+ *                        the authoritative outcome.
+ *   - `'still-pending'`— the entry is in the pending list but has not yet
+ *                        crossed the persistent threshold. The next sweep
+ *                        run will retry.
+ *   - `'not-found'`    — the entry is in neither list. Either the drain
+ *                        cleared it before this reconcile saw it, or this
+ *                        Story never had a pending entry. Treated as a
+ *                        clean state for downstream callers.
+ *
+ * Extracted from a nested ternary so the truth table is greppable and each
+ * branch carries an explicit name.
+ *
+ * @param {{ isPersistent: boolean, isStillPending: boolean }} flags
+ * @returns {'persistent' | 'still-pending' | 'not-found'}
+ */
+export function getCloseDrainStatus({ isPersistent, isStillPending }) {
+  if (isPersistent) return 'persistent';
+  if (isStillPending) return 'still-pending';
+  return 'not-found';
+}

package/.agents/scripts/lib/orchestration/story-close/close-inputs.js

@@ -0,0 +1,142 @@
+/**
+ * close-inputs.js — argument parsing + cwd / epic / branch resolution for
+ * the story-close CLI. Extracted from story-close.js (Story #956, Theme A
+ * finishing touch) so the close orchestrator becomes a thin CLI shell.
+ *
+ * `resolveCloseInputs` folds the three pre-merge resolutions that
+ * `runStoryClose` does up-front into a single helper:
+ *
+ *   - parse the CLI argv (or normalize the parameter object passed to
+ *     `runStoryClose(...)` from a test/programmatic caller),
+ *   - resolve the main-repo cwd (explicit param > --cwd flag > env >
+ *     PROJECT_ROOT),
+ *   - run the cd-out guard before any git/filesystem mutation,
+ *   - fetch the Story ticket and resolve `epicId` from the body when not
+ *     passed via --epic,
+ *   - derive `epicBranch` + `storyBranch` from the canonical helpers.
+ *
+ * The helper does NOT touch the merge lock, the post-merge pipeline, or
+ * the phase timer — those stay in the orchestrator.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseSprintArgs } from '../../cli-args.js';
+import { PROJECT_ROOT, resolveConfig } from '../../config-resolver.js';
+import { getEpicBranch, getStoryBranch } from '../../git-utils.js';
+import { createProvider as defaultCreateProvider } from '../../provider-factory.js';
+import { resolveStoryHierarchy } from '../../story-lifecycle.js';
+import { checkCdOutGuard } from './cd-out-guard.js';
+
+/**
+ * Resolve the path of the Story's worktree given the resolved main `cwd` and
+ * `storyId`. Returns the absolute worktree path when `<cwd>/<root>/story-<id>`
+ * exists on disk; returns `null` otherwise (single-tree mode, or the worktree
+ * was reaped earlier in the close flow). Used by `runStoryClose` to thread
+ * the worktree directory into pre-merge gate spawns so close-validation runs
+ * against the Story branch's post-rebase tree (Story #1120).
+ *
+ * Pure-ish (modulo `fs.existsSync`) — exported so tests can pin the
+ * "what counts as a usable worktree" contract without mocking filesystem
+ * state.
+ */
+export function resolveWorktreePath({ cwd, storyId, worktreeRoot }) {
+  if (!cwd || !storyId) return null;
+  const root = worktreeRoot ?? '.worktrees';
+  const candidate = path.resolve(cwd, root, `story-${storyId}`);
+  try {
+    return fs.existsSync(candidate) ? candidate : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {{
+ *   storyIdParam?: number|string,
+ *   epicIdParam?: number|string,
+ *   skipDashboardParam?: boolean,
+ *   skipValidationParam?: boolean,
+ *   cwdParam?: string|null,
+ *   resumeParam?: boolean,
+ *   restartParam?: boolean,
+ *   injectedProvider?: object,
+ *   createProvider?: typeof defaultCreateProvider,
+ * }} args
+ */
+export async function resolveCloseInputs({
+  storyIdParam,
+  epicIdParam,
+  skipDashboardParam,
+  skipValidationParam,
+  cwdParam,
+  resumeParam,
+  restartParam,
+  injectedProvider,
+  createProvider = defaultCreateProvider,
+}) {
+  const parsed =
+    storyIdParam !== undefined
+      ? {
+          storyId: storyIdParam,
+          epicId: epicIdParam,
+          skipDashboard: !!skipDashboardParam,
+          skipValidation: !!skipValidationParam,
+          cwd: cwdParam ?? null,
+          resume: !!resumeParam,
+          restart: !!restartParam,
+        }
+      : parseSprintArgs();
+  const cwd = path.resolve(cwdParam ?? parsed.cwd ?? PROJECT_ROOT);
+
+  if (!parsed.storyId) {
+    throw new Error(
+      'Usage: node story-close.js --story <STORY_ID> [--epic <EPIC_ID>]',
+    );
+  }
+
+  const config = resolveConfig({ cwd });
+  const worktreeRoot = config.delivery?.worktreeIsolation?.root;
+
+  const guard = checkCdOutGuard({
+    cwdExplicit: parsed.cwd != null,
+    mainCwd: cwd,
+    storyId: parsed.storyId,
+    worktreeRoot,
+  });
+  if (!guard.ok) throw new Error(guard.message);
+
+  const provider = injectedProvider || createProvider(config);
+  const story = await provider.getTicket(parsed.storyId);
+  let epicId = parsed.epicId;
+  if (!epicId) {
+    const resolved = resolveStoryHierarchy(story.body);
+    if (!resolved.epicId) {
+      throw new Error(
+        `Story #${parsed.storyId} has no "Epic: #N" reference. Pass --epic <id> explicitly.`,
+      );
+    }
+    epicId = resolved.epicId;
+  }
+
+  return {
+    storyId: parsed.storyId,
+    epicId,
+    cwd,
+    worktreePath: resolveWorktreePath({
+      cwd,
+      storyId: parsed.storyId,
+      worktreeRoot,
+    }),
+    skipDashboard: parsed.skipDashboard,
+    skipValidation: !!parsed.skipValidation,
+    resumeFlag: parsed.resume,
+    restartFlag: parsed.restart,
+    noEvidenceFlag: parsed.noEvidence,
+    config,
+    provider,
+    story,
+    epicBranch: getEpicBranch(epicId),
+    storyBranch: getStoryBranch(epicId, parsed.storyId),
+  };
+}

package/.agents/scripts/lib/orchestration/story-close/comment-bodies.js

@@ -0,0 +1,62 @@
+import { buildMergeMessageWithCap } from './merge-subject.js';
+
+/**
+ * comment-bodies.js — pure renderers for story-close GitHub comment payloads
+ * and operator-facing fatal-message envelopes.
+ *
+ * Extracted from story-close.js (Story #955, Theme A part 3) so the close
+ * orchestrator becomes a thin CLI shell. These helpers are stateless and
+ * format-only:
+ *
+ *   - buildResumeMergeCommitMsg     — the conventional-commit subject the
+ *     `--resume` partial-merge path uses to finalize the in-progress merge.
+ *   - describeResumePushFailure     — classifies a `pushEpicWithRetry`
+ *     outcome into the operator-facing fatal-error string (or returns null
+ *     when the push was ok).
+ *
+ * Epic #1030 Story #1046 — `renderPhaseTimingsCommentBody` was removed; the
+ * legacy `<!-- structured:phase-timings -->` post is now produced by
+ * `analyze-execution.js` as the unified `<!-- structured:story-perf-summary -->`
+ * comment. The `perf-summary` phase in post-merge-pipeline.js is the call
+ * site.
+ *
+ * No I/O, no logging, no hidden globals. Tests import the same symbols and
+ * pin behaviour without spawning the close script.
+ */
+
+/**
+ * Pure: build the conventional-commit subject the resume path uses to
+ * finalize a partial-merge commit. When `headerMaxLength` is provided
+ * and the assembled subject would exceed it, the title is truncated on
+ * a word boundary (Conventional-Commits prefix and `(resolves #N)` suffix
+ * preserved verbatim) and a `truncated-from: <original>` body trailer is
+ * appended. Exported for tests.
+ *
+ * @param {string} storyTitle
+ * @param {number|string} storyId
+ * @param {{ headerMaxLength?: number, logger?: { warn?: Function } }} [opts]
+ */
+export function buildResumeMergeCommitMsg(storyTitle, storyId, opts = {}) {
+  return buildMergeMessageWithCap({
+    type: 'feat',
+    title: storyTitle,
+    storyId,
+    headerMaxLength: opts.headerMaxLength,
+    logger: opts.logger,
+  }).message;
+}
+
+/**
+ * Pure: classify a `pushEpicWithRetry` outcome into the operator-facing
+ * fatal-error message. Returns `null` when the push was ok.
+ */
+export function describeResumePushFailure(pushOutcome) {
+  if (pushOutcome.ok) return null;
+  const reasonLabel =
+    pushOutcome.reason === 'retry-exhausted'
+      ? `retries exhausted after ${pushOutcome.attempts} attempt(s)`
+      : pushOutcome.reason;
+  const detail =
+    pushOutcome.result?.stderr || pushOutcome.result?.stdout || 'unknown';
+  return `Push failed (${reasonLabel}): ${detail}`;
+}

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

@@ -0,0 +1,221 @@
+/**
+ * format-autofix-scoped.js — Story #2533: scoped biome-format auto-apply
+ * inside story-close's pre-merge gate chain.
+ *
+ * Background. The whole-tree `runFormatAutofix` (sibling module) heals
+ * drift across `.` before the gate chain runs. That step is intentionally
+ * broad because it covers files (JSON / YAML / config) that lint-staged
+ * does not glob. This module is the narrower companion: it scopes
+ * `biome format --write` to the **changed-file set** between the Epic
+ * branch and the Story branch and folds any auto-fixed paths into a
+ * dedicated commit on the Story branch *before* `biome ci` runs in the
+ * gate chain.
+ *
+ * Why scoped + warn-level. The Tech Spec (Epic #2527, Story 5) calls out
+ * that format diffs introduced by Story commits should never surface to
+ * Phase 3 close-validation. The whole-tree autofix already covers that,
+ * but emits `info` so operators routinely miss it. This module emits
+ * `Logger.warn` naming the auto-fixed files so the signal is visible in
+ * the close transcript and downstream ledger.
+ *
+ * Dependencies are injected so unit tests pin behaviour without spawning
+ * git or biome.
+ */
+
+import { execFileSync } from 'node:child_process';
+
+import { diffNameOnly } from '../../changed-files.js';
+import { Logger as DefaultLogger } from '../../Logger.js';
+import {
+  commitDirtyPaths,
+  currentBranch,
+  listDirtyPaths,
+  resolveFormatterCmd,
+} from './format-autofix-shared.js';
+
+const TAG = '[format-autofix-scoped]';
+
+/**
+ * List the files changed between `epicBranch` 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.
+ *
+ * The `git` parameter uses the caller's local interface:
+ * `(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
+ * @returns {string[]}
+ */
+function listChangedFiles({ cwd, epicBranch, storyBranch, git }) {
+  // Bridge the (args, opts) → string interface into gitSpawn(cwd, ...args).
+  const gitSpawn = (_cwd, ...args) => {
+    try {
+      const stdout = git(args, {
+        cwd: _cwd,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+      });
+      return { status: 0, stdout: stdout ?? '', stderr: '' };
+    } catch (err) {
+      return {
+        status: err.status ?? 1,
+        stdout: err.stdout ?? '',
+        stderr: err.stderr ?? err.message,
+      };
+    }
+  };
+  return diffNameOnly({
+    range: `${epicBranch}...${storyBranch}`,
+    cwd,
+    gitSpawn,
+  });
+}
+
+/**
+ * Run `biome format --write <changedFiles>` on the Epic→Story diff. If
+ * any file is modified, stage and commit the changes on the Story branch
+ * with a conventional `fix(story-close):` subject and emit a
+ * `Logger.warn` naming the auto-fixed files. Returns a structured
+ * envelope so callers can log a single line.
+ *
+ * No-op envelopes:
+ *   - `{ ran: false, reason: 'no-changed-files' }`        — empty diff.
+ *   - `{ ran: false, reason: 'dirty-tree' }`              — refused to
+ *     absorb pre-existing edits.
+ *   - `{ ran: true, committed: false }`                   — formatter
+ *     was clean.
+ *
+ * **Worktree scope (Story #3907).** All git + formatter operations run in
+ * `worktreePath` (the Story worktree where `story-<id>` is checked out), not
+ * `cwd` (the main checkout). The earlier implementation ran every step
+ * against `cwd`, so the `git add -u` + `git commit` could land an unreviewed
+ * `fix(story-close):` commit on whatever branch the main checkout happened to
+ * have out — including `main`. Before committing, the worktree's checked-out
+ * branch is asserted to equal `storyBranch`; a mismatch refuses to commit and
+ * returns `{ ran: true, committed: false, reason: 'wrong-branch' }` so a
+ * stale-state checkout can never absorb the autofix into the wrong history.
+ * `worktreePath` defaults to `cwd` for the resume/legacy callers that have no
+ * separate worktree.
+ *
+ * @param {{
+ *   cwd: string,
+ *   worktreePath?: string,
+ *   storyId: number|string,
+ *   epicBranch: string,
+ *   storyBranch: string,
+ *   config?: object,
+ *   logger?: object,
+ *   spawnSync?: typeof execFileSync,
+ *   gitSync?: (args: string[], opts: object) => string,
+ * }} opts
+ * @returns {{
+ *   ran: boolean,
+ *   committed: boolean,
+ *   sha?: string,
+ *   modifiedPaths?: string[],
+ *   reason?: string,
+ * }}
+ */
+export function runScopedFormatAutofix({
+  cwd,
+  worktreePath,
+  storyId,
+  epicBranch,
+  storyBranch,
+  config,
+  logger = DefaultLogger,
+  spawnSync = execFileSync,
+  gitSync,
+} = {}) {
+  if (!cwd) throw new Error('runScopedFormatAutofix: cwd is required');
+  if (!epicBranch)
+    throw new Error('runScopedFormatAutofix: epicBranch is required');
+  if (!storyBranch)
+    throw new Error('runScopedFormatAutofix: storyBranch is required');
+
+  // Story #3907 — the formatter writes + the commit must land in the Story
+  // worktree, never the main checkout. Fall back to `cwd` only for callers
+  // that do not run under worktree isolation.
+  const workTree = worktreePath || cwd;
+
+  const git = gitSync ?? ((args, opts) => spawnSync('git', args, opts));
+
+  // Resolve the formatter base command (e.g. `npx biome format --write`).
+  // We drop a trailing `.` so we can append the changed-file set explicitly.
+  const { writeCmdString, writeCmd, writeArgs } = resolveFormatterCmd({
+    commands: config?.project?.commands,
+    dropTrailingDot: true,
+  });
+
+  const changed = listChangedFiles({
+    cwd: workTree,
+    epicBranch,
+    storyBranch,
+    git,
+  });
+  if (changed.length === 0) {
+    logger.info?.(
+      `${TAG} skipped — no changed files between ${epicBranch} and ${storyBranch}.`,
+    );
+    return { ran: false, committed: false, reason: 'no-changed-files' };
+  }
+
+  const dirtyBefore = listDirtyPaths(workTree, git);
+  if (dirtyBefore.length) {
+    logger.info?.(
+      `${TAG} skipped — working tree dirty before scoped autofix (${dirtyBefore.length} paths).`,
+    );
+    return { ran: false, committed: false, reason: 'dirty-tree' };
+  }
+
+  // Run the formatter against the changed-file set. We tolerate non-zero
+  // exit because the downstream check gate is the source of truth for
+  // "did formatting succeed".
+  try {
+    spawnSync(writeCmd, [...writeArgs, ...changed], {
+      cwd: workTree,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      encoding: 'utf8',
+    });
+  } catch (err) {
+    logger.warn?.(
+      `${TAG} \`${writeCmdString}\` on ${changed.length} changed file(s) exited non-zero (${err?.status ?? 'unknown'}); falling through to the format check gate.`,
+    );
+  }
+
+  const dirtyAfter = listDirtyPaths(workTree, git);
+  if (!dirtyAfter.length) {
+    logger.info?.(
+      `${TAG} no format drift on ${changed.length} changed file(s).`,
+    );
+    return { ran: true, committed: false };
+  }
+
+  // Story #3907 — assert the worktree is actually on `storyBranch` before we
+  // stage + commit. Without this guard a stale-state checkout (or a
+  // mis-wired `cwd`) could absorb the autofix onto the wrong branch (incl.
+  // `main`). A mismatch refuses to commit and leaves the format drift for the
+  // downstream check gate to surface.
+  const onBranch = currentBranch(workTree, git);
+  if (onBranch !== storyBranch) {
+    logger.warn?.(
+      `${TAG} refusing to commit — worktree ${workTree} is on "${onBranch ?? 'unknown'}", expected "${storyBranch}". ` +
+        `${dirtyAfter.length} format-drift path(s) left for the check gate.`,
+    );
+    return { ran: true, committed: false, reason: 'wrong-branch' };
+  }
+
+  // Stage every modified path and commit. Hooks must run; do not pass
+  // --no-verify (project policy: never skip git hooks).
+  const subject = `fix(story-close): auto-apply biome format in scoped lint (story #${storyId})`;
+  const sha = commitDirtyPaths({ cwd: workTree, git, subject });
+
+  // The warn-level emission is the Tech Spec contract — operators read
+  // this line in the close transcript to know auto-fix landed in the
+  // close commit, and downstream ledger inspectors filter on it.
+  logger.warn?.(
+    `${TAG} auto-applied biome format to ${dirtyAfter.length} path(s) on story #${storyId}: ${dirtyAfter.join(', ')}; committed as ${sha}.`,
+  );
+  return { ran: true, committed: true, sha, modifiedPaths: dirtyAfter };
+}