mandrel 1.58.0 → 1.60.0

package/.agents/scripts/lib/orchestration/story-close/baseline-attribution/phases/pre-merge-attribution.js

@@ -55,13 +55,19 @@ export async function runPreMergeGatesWithAttribution({
   projectRegressionsFn = projectRegressionsForGate,
   logger = DefaultLogger,
   maxAttempts = 2,
+  cycleState: cycleStateParam = null,
 } = {}) {
   let attempt = 0;
   const gateCwd = worktreePath || cwd;
   // Story #2205: single mutable cycle state object — `refreshedKinds`
   // gates the idempotency token enforcing AC-9 (one refresh commit per
-  // kind per close cycle).
-  const cycleState = { refreshedKinds: new Set(), lastRefreshSha: null };
+  // kind per close cycle). Story #4017: the caller may thread the close
+  // cycle's shared object so the post-gates auto-refresh sees the kinds
+  // already refreshed by this retry loop and never re-scores them.
+  const cycleState = cycleStateParam ?? {
+    refreshedKinds: new Set(),
+    lastRefreshSha: null,
+  };
   while (attempt < maxAttempts) {
     attempt += 1;
     try {

package/.agents/scripts/lib/orchestration/story-close/baseline-attribution/phases/refresh-commit.js

@@ -261,8 +261,17 @@ export function stageAndCheckBaselineDrift({
  * Story branch — this helper does NOT re-check the branch. story-close.js
  * holds that invariant via `withEpicMergeLock`.
  *
+ * Story #4017 — this helper is the **single refresh→stage→commit funnel**
+ * for story-close. Both call paths route through it: the gate-failure
+ * attribution retry (`gate-failure.js`, no `capCheck`) and the post-gates
+ * bounded auto-refresh (`auto-refresh-runner.js`, which injects a
+ * `capCheck` evaluating the refreshed envelope against the configured
+ * delta caps). When `capCheck` returns `{ canAutoRefresh: false }`, the
+ * staged refresh is rolled back to HEAD and the helper returns
+ * `{ ok: true, refused: true, verdict }` without committing.
+ *
  * @returns {Promise<
- *   | { ok: true, sha: string, skipped?: boolean, reason?: string }
+ *   | { ok: true, sha: string, skipped?: boolean, reason?: string, refused?: boolean, verdict?: object }
  *   | { ok: false, error: string }
  * >}
  */
@@ -274,9 +283,11 @@ export async function runRefreshCommit({
   storyBranch,
   config,
   cycleState = null,
+  capCheck = null,
   refreshBaseline = defaultRefreshBaseline,
   scorerBuilder = buildKindScorer,
   getBaselines: getBaselinesImpl = defaultGetBaselines,
+  getQuality: getQualityImpl = defaultGetQuality,
   fsImpl = fs,
   gitRunner = { gitSpawn: defaultGitSpawn },
   logger = DefaultLogger,
@@ -326,8 +337,9 @@ export async function runRefreshCommit({
     };
   }
 
+  let refreshResult;
   try {
-    await refreshBaseline({
+    refreshResult = await refreshBaseline({
       kind,
       baseRef,
       headRef,
@@ -341,6 +353,7 @@ export async function runRefreshCommit({
       requiredScopeFilePredicate: buildRequiredScopeFilePredicate({
         kind,
         config,
+        getQuality: getQualityImpl,
       }),
     });
   } catch (err) {
@@ -350,6 +363,18 @@ export async function runRefreshCommit({
     };
   }
 
+  // Story #4017 — when the service reports it persisted nothing, skip the
+  // stage/diff round-trip entirely: there is no drift to fold in.
+  if (refreshResult?.wrote === false) {
+    if (cycleState?.refreshedKinds instanceof Set) {
+      cycleState.refreshedKinds.add(kind);
+    }
+    logger?.info?.(
+      `[baseline-attribution-wiring] refresh wrote nothing for kind=${kind} (story-${storyId}); skipping.`,
+    );
+    return { ok: true, sha: '', skipped: true, reason: 'no-baseline-drift' };
+  }
+
   const drift = stageAndCheckBaselineDrift({
     cwd,
     baselineFile: writePath,
@@ -366,6 +391,26 @@ export async function runRefreshCommit({
     return { ok: true, sha: '', skipped: true, reason: 'no-baseline-drift' };
   }
 
+  // Story #4017 — optional bounded-delta cap check (injected by the
+  // post-gates auto-refresh path). A refusal rolls the staged refresh back
+  // to HEAD so the merge consumes the pre-refresh baseline unchanged.
+  if (typeof capCheck === 'function') {
+    const verdict = await capCheck({ kind, writePath });
+    if (verdict && verdict.canAutoRefresh === false) {
+      const rel = path.isAbsolute(writePath)
+        ? path.relative(cwd, writePath)
+        : writePath;
+      const posixRel = rel.split(path.sep).join('/');
+      const res = gitRunner.gitSpawn(cwd, 'checkout', 'HEAD', '--', posixRel);
+      if (res.status !== 0) {
+        logger?.warn?.(
+          `[baseline-attribution-wiring] failed to restore ${rel} after cap refusal: ${res.stderr || res.stdout}`,
+        );
+      }
+      return { ok: true, sha: '', refused: true, verdict };
+    }
+  }
+
   const subject = `chore(baselines): refresh ${kind} for story-${storyId}`;
   const commitRes = gitRunner.gitSpawn(cwd, 'commit', '-m', subject);
   if (commitRes.status !== 0) {

package/.agents/scripts/lib/orchestration/story-close/baseline-attribution/phases/regression-projection.js

@@ -10,14 +10,14 @@
  * Two projectors live here:
  *
  *   - `projectMaintainabilityForGate` — reuses the MI projection from
- *     `close-validation.js` (Story #874).
+ *     `close-validation/projections/maintainability.js` (Story #874).
  *   - `projectCrapForGate` / `projectCrapRegressions` — diff CRAP envelopes
  *     at `origin/<epicBranch>` vs `storyBranch`, optionally scoped to the
  *     Story's touched files (Story #1124).
  */
 
 import { readBaselineAtRef as defaultReadBaselineAtRef } from '../../../../baseline-loader.js';
-import { projectMaintainabilityRegressions as defaultProjectMaintainabilityRegressions } from '../../../../close-validation.js';
+import { projectMaintainabilityRegressions as defaultProjectMaintainabilityRegressions } from '../../../../close-validation/projections/maintainability.js';
 import { getBaselines as defaultGetBaselines } from '../../../../config-resolver.js';
 import {
   computeStoryDiffPaths,

package/.agents/scripts/lib/orchestration/story-close/baseline-friction-body.js

@@ -100,7 +100,7 @@ export function renderBaselineFrictionBody({ rows, epicId, storyId } = {}) {
   const triage = [
     '**Triage:**',
     `1. Open each suspect Story above and run \`npm run maintainability:update\` (or \`npm run crap:update\`) on **its** branch, then commit with a \`baseline-refresh:\` subject and re-close it.`,
-    `2. Re-run \`/story-deliver ${storyId}\` once the suspect Story's refresh has merged into \`epic/${epicId}\`.`,
+    `2. Re-run \`/deliver ${storyId}\` once the suspect Story's refresh has merged into \`epic/${epicId}\`.`,
     `3. If the suspect column reads \`_unknown_\`, the path has no commit on \`epic/${epicId}\` — investigate the baseline file directly before refreshing.`,
   ];
 

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

@@ -1,6 +1,12 @@
 /**
  * format-autofix.js — self-healing biome-format step for story-close.
  *
+ * Story #4017 collapsed the historical three-module split (a whole-tree
+ * fork, a scoped changed-file fork, and a shared plumbing module) into
+ * this single module. The two entry points differ only in file-scope,
+ * commit subject, and log level; the git/formatter plumbing is shared
+ * below.
+ *
  * Background. The pre-merge `biome format` gate is check-only — it fails
  * the close when the working tree has any format drift. In practice
  * upstream waves frequently leave drift in files that lint-staged does
@@ -9,35 +15,31 @@
  * `style:` commit before the close can resume. That manual loop is
  * trivially automatable.
  *
- * This module runs `npx biome format --write .` *before* the pre-merge
- * gate chain. If it rewrites files, we stage and commit them on the
- * Story branch with a `style:` subject so the merge into `epic/<id>`
- * carries the fix forward atomically. The subsequent `biome format`
- * check gate then passes deterministically.
+ * Entry points:
  *
- * The step is a no-op when:
- *   - biome rewrites nothing (clean tree),
- *   - the working tree is dirty for unrelated reasons (we refuse to
- *     opportunistically commit those — operator intent is unclear), or
- *   - `npx biome format --write` exits non-zero (we surface the error
- *     and let the existing format gate report it with the canonical
- *     hint).
+ *   - {@link runFormatAutofix} — whole-tree heal (`biome format --write .`)
+ *     before the pre-merge gate chain, for resume/legacy callers that have
+ *     no Epic→Story diff anchor. Bounded by a wall-clock timeout
+ *     (Story #2165).
+ *   - {@link runScopedFormatAutofix} — Story #2533: scopes the formatter to
+ *     the changed-file set between the Epic branch and the Story branch and
+ *     folds auto-fixed paths into a dedicated `fix(story-close):` commit,
+ *     emitting `Logger.warn` naming the files. Carries the worktree-cwd fix
+ *     and branch assert from Story #3907.
  *
- * Dependencies are injected so unit tests pin behaviour without
- * spawning git or biome.
+ * 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 { resolveFormatWriteCommand } from '../../close-validation/commands.js';
 import { getQuality } from '../../config-resolver.js';
 import { Logger as DefaultLogger } from '../../Logger.js';
-import {
-  commitDirtyPaths,
-  listDirtyPaths,
-  resolveFormatterCmd,
-} from './format-autofix-shared.js';
 
 const TAG = '[format-autofix]';
+const SCOPED_TAG = '[format-autofix-scoped]';
 
 /**
  * Story #2165 — exit code surfaced when the bounded `npx biome format
@@ -49,17 +51,161 @@ const TAG = '[format-autofix]';
  */
 export const FORMAT_AUTOFIX_TIMEOUT_EXIT_CODE = 124;
 
+/**
+ * Run `git status --porcelain` and return the list of changed paths.
+ *
+ * Porcelain lines are `XY <path>` — exactly two status chars, one space,
+ * then the path. Leading whitespace inside the status pair is significant
+ * (e.g. ` M file` for unstaged-modified) so we slice a fixed 3 chars off
+ * the front rather than trimming.
+ *
+ * @param {string} cwd
+ * @param {(args: string[], opts: object) => string} git
+ * @returns {string[]}
+ */
+export function listDirtyPaths(cwd, git) {
+  const out = git(['status', '--porcelain'], {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+  });
+  return out
+    .split('\n')
+    .filter((line) => line.length >= 4)
+    .map((line) => line.slice(3));
+}
+
+/**
+ * Resolve the formatter write command from `project.commands.formatWrite`
+ * (falling back to the historical `npx biome format --write .`) and split
+ * it into an executable + argv pair ready for `execFileSync`.
+ *
+ * The whole-tree entry point runs the command verbatim (keeping the
+ * trailing `.` so biome formats the entire tree). The scoped entry point
+ * appends an explicit changed-file set, so it passes
+ * `dropTrailingDot: true` to strip the `.` before its file list.
+ *
+ * @param {{
+ *   commands?: object,
+ *   dropTrailingDot?: boolean,
+ * }} [opts]
+ * @returns {{ writeCmdString: string, writeCmd: string, writeArgs: string[] }}
+ */
+export function resolveFormatterCmd({
+  commands,
+  dropTrailingDot = false,
+} = {}) {
+  // `resolveFormatWriteCommand` reads `config.project.commands`; wrap the
+  // caller-supplied `commands` map into that canonical shape.
+  const writeCmdString = resolveFormatWriteCommand({ project: { commands } });
+  const parts = writeCmdString.split(/\s+/).filter(Boolean);
+  if (dropTrailingDot && parts[parts.length - 1] === '.') parts.pop();
+  const [writeCmd, ...writeArgs] = parts;
+  return { writeCmdString, writeCmd, writeArgs };
+}
+
+/**
+ * Resolve the branch currently checked out at `cwd` via
+ * `git rev-parse --abbrev-ref HEAD`. Returns the trimmed branch name, or
+ * `null` when the call fails or the tree is in a detached-HEAD state
+ * (`HEAD`). Used as the commit-target guard before
+ * {@link commitDirtyPaths} writes a scoped-autofix commit, so the commit
+ * can never land on the wrong branch (e.g. the main checkout's `main`).
+ *
+ * @param {string} cwd
+ * @param {(args: string[], opts: object) => string} git
+ * @returns {string|null}
+ */
+export function currentBranch(cwd, git) {
+  try {
+    const out = git(['rev-parse', '--abbrev-ref', 'HEAD'], {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const branch = (out ?? '').toString().trim();
+    if (!branch || branch === 'HEAD') return null;
+    return branch;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Stage every modified path (`git add -u`), commit with the caller-supplied
+ * `subject`, and return the short HEAD SHA. Hooks must run; we never pass
+ * `--no-verify` (project policy: never skip git hooks).
+ *
+ * @param {{
+ *   cwd: string,
+ *   git: (args: string[], opts: object) => string,
+ *   subject: string,
+ * }} opts
+ * @returns {string} short HEAD SHA of the new commit
+ */
+export function commitDirtyPaths({ cwd, git, subject }) {
+  git(['add', '-u'], { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+  git(['commit', '-m', subject], {
+    cwd,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  return git(['rev-parse', '--short', 'HEAD'], {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+  }).trim();
+}
+
+/**
+ * Story #2165 — resolve the format-autofix spawn timeout. An explicit
+ * caller-supplied positive integer wins over both
+ * `delivery.quality.formatAutofix.timeoutMs` and the framework default
+ * (60 s). Any resolver failure surfaces as `null`; the caller treats that
+ * as "no timeout" and the spawn runs unbounded — same fail-open contract
+ * coverage-capture uses.
+ */
+function resolveFormatTimeoutMs({ timeoutMs, config }) {
+  if (
+    typeof timeoutMs === 'number' &&
+    Number.isInteger(timeoutMs) &&
+    timeoutMs > 0
+  ) {
+    return timeoutMs;
+  }
+  try {
+    const resolved = getQuality(config)?.formatAutofix?.timeoutMs;
+    if (
+      typeof resolved === 'number' &&
+      Number.isInteger(resolved) &&
+      resolved > 0
+    ) {
+      return resolved;
+    }
+  } catch {
+    // resolver failure → fall through to "no timeout"
+  }
+  return null;
+}
+
 /**
  * Run `npx biome format --write .` then, if anything changed, commit
  * the result on the Story branch with a `style:` subject. Returns a
  * structured envelope so callers can log a single line.
  *
- * Story #2165: the formatter spawn is now bounded by a wall-clock
- * timeout (resolved from `delivery.quality.formatAutofix.timeoutMs`,
- * default 60 s). A SIGKILL fired at the budget boundary is translated
- * to the `timedOut: true` envelope below so the close orchestrator can
- * flip the Story to `agent::blocked` with a friction comment naming the
- * spawn, mirroring the coverage-capture pattern from Story #2142.
+ * Story #2165: the formatter spawn is bounded by a wall-clock timeout
+ * (resolved from `delivery.quality.formatAutofix.timeoutMs`, default
+ * 60 s). A SIGKILL fired at the budget boundary is translated to the
+ * `timedOut: true` envelope below so the close orchestrator can flip the
+ * Story to `agent::blocked` with a friction comment naming the spawn,
+ * mirroring the coverage-capture pattern from Story #2142.
+ *
+ * The step is a no-op when:
+ *   - biome rewrites nothing (clean tree),
+ *   - the working tree is dirty for unrelated reasons (we refuse to
+ *     opportunistically commit those — operator intent is unclear), or
+ *   - `npx biome format --write` exits non-zero (we surface the error
+ *     and let the existing format gate report it with the canonical
+ *     hint).
  *
  * @param {{
  *   cwd: string,
@@ -96,7 +242,7 @@ export function runFormatAutofix({
   // Resolve the formatter command from `project.commands.formatWrite` so
   // Prettier / dprint repos use their own formatter. Falls back to the
   // historical `npx biome format --write .` for repos that haven't opted in.
-  // The whole-tree fork keeps the trailing `.` (formats the entire tree).
+  // The whole-tree entry point keeps the trailing `.` (formats the tree).
   const { writeCmdString, writeCmd, writeArgs } = resolveFormatterCmd({
     commands: config?.project?.commands,
   });
@@ -112,10 +258,7 @@ export function runFormatAutofix({
     return { ran: false, committed: false, dirtyPathsBefore: dirtyBefore };
   }
 
-  // Story #2165 — bounded wall-clock for the formatter spawn. Resolve
-  // through `getQuality` so consumers can tune via
-  // `delivery.quality.formatAutofix.timeoutMs`; an explicit caller-supplied
-  // positive integer wins over both the config and the framework default.
+  // Story #2165 — bounded wall-clock for the formatter spawn.
   // execFileSync's contract: on a SIGKILL trip the thrown error carries
   // `err.signal === 'SIGKILL'` and `err.status === null`, so we branch on
   // that to surface the 124 envelope below — same shape coverage-capture
@@ -185,32 +328,193 @@ export function runFormatAutofix({
 }
 
 /**
- * Story #2165 — resolve the format-autofix spawn timeout. An explicit
- * caller-supplied positive integer wins over both
- * `delivery.quality.formatAutofix.timeoutMs` and the framework default
- * (60 s). Any resolver failure surfaces as `null`; the caller treats that
- * as "no timeout" and the spawn runs unbounded — same fail-open contract
- * coverage-capture uses.
+ * 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 resolveFormatTimeoutMs({ timeoutMs, config }) {
-  if (
-    typeof timeoutMs === 'number' &&
-    Number.isInteger(timeoutMs) &&
-    timeoutMs > 0
-  ) {
-    return timeoutMs;
+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,
+  });
+}
+
+/**
+ * Story #2533 — 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.
+ *
+ * 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 entry point emits
+ * `Logger.warn` naming the auto-fixed files so the signal is visible in
+ * the close transcript and downstream ledger.
+ *
+ * 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?.(
+      `${SCOPED_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?.(
+      `${SCOPED_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 {
-    const resolved = getQuality(config)?.formatAutofix?.timeoutMs;
-    if (
-      typeof resolved === 'number' &&
-      Number.isInteger(resolved) &&
-      resolved > 0
-    ) {
-      return resolved;
-    }
-  } catch {
-    // resolver failure → fall through to "no timeout"
+    spawnSync(writeCmd, [...writeArgs, ...changed], {
+      cwd: workTree,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      encoding: 'utf8',
+    });
+  } catch (err) {
+    logger.warn?.(
+      `${SCOPED_TAG} \`${writeCmdString}\` on ${changed.length} changed file(s) exited non-zero (${err?.status ?? 'unknown'}); falling through to the format check gate.`,
+    );
   }
-  return null;
+
+  const dirtyAfter = listDirtyPaths(workTree, git);
+  if (!dirtyAfter.length) {
+    logger.info?.(
+      `${SCOPED_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?.(
+      `${SCOPED_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?.(
+    `${SCOPED_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 };
 }

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

@@ -20,8 +20,8 @@
  * CC < 12 phase-file budget).
  */
 
-import { PROJECT_ROOT } from '../../../config-resolver.js';
 import { Logger } from '../../../Logger.js';
+import { PROJECT_ROOT } from '../../../project-root.js';
 import { STATE_LABELS } from '../../ticketing.js';
 import { runFinalizeMerge, runResumeMerge } from '../merge-runner.js';
 import { runPostMergeClose } from '../post-merge-close.js';

package/.agents/scripts/lib/orchestration/story-close/phases/gates.js

@@ -30,8 +30,7 @@
 
 import { Logger } from '../../../Logger.js';
 import { runPreMergeGatesWithAttribution } from '../baseline-attribution-wiring.js';
-import { runFormatAutofix } from '../format-autofix.js';
-import { runScopedFormatAutofix } from '../format-autofix-scoped.js';
+import { runFormatAutofix, runScopedFormatAutofix } from '../format-autofix.js';
 import { emitBlockedCloseResult } from '../merge-runner.js';
 import { emitMaintainabilityProjection } from '../pre-merge-validation.js';
 
@@ -223,6 +222,7 @@ export async function runPreMergeValidation({
   phaseTimer,
   provider,
   bus = null,
+  cycleState = null,
 }) {
   // Story #2533: scope-narrowed biome-format auto-apply on the Epic→Story
   // diff. The scoped step folds format drift introduced by Story commits
@@ -273,6 +273,7 @@ export async function runPreMergeValidation({
     config,
     storyId,
     epicId,
+    cycleState,
     useEvidence: !noEvidenceFlag,
     phaseTimer,
     provider,