mandrel 1.57.0 → 1.59.0

package/.agents/scripts/lib/orchestration/cascade-grouping.js

@@ -1,275 +0,0 @@
-/**
- * lib/orchestration/cascade-grouping.js — Cascade dispatch helpers.
- *
- * Pure helpers used by `cascadeCompletion` (see `./ticketing.js`) to
- * partition a list of parent tickets into disjoint shared-ancestor groups
- * and to buffer per-parent log output so parallel dispatch produces a
- * byte-identical log stream to the serial baseline.
- *
- * Pulled out of `ticketing.js` so the cascade orchestrator stays under the
- * project's per-file maintainability ceiling. No state is held at module
- * scope — every helper takes its dependencies as arguments.
- */
-
-/**
- * Walks `parent: #N` references upward from the given ticket id until no new
- * ancestors are discovered. Returns the set of every ticket id reachable
- * along the chain, including the starting id. Cycle-safe by construction —
- * the visited set acts as the seen guard, so a cyclic `parent: #N` graph
- * terminates in finite steps without revisiting nodes.
- *
- * Pure of side effects beyond the provider reads it issues. Provider
- * failures on a single hop fall back to "no further ancestors discovered"
- * for that branch (the chain truncates rather than throwing); this matches
- * `cascadeCompletion`'s tolerant posture toward transient reads.
- *
- * @param {import('../ITicketingProvider.js').ITicketingProvider} provider
- * @param {number} startId
- * @param {Map<number, Set<number>>} [cache] - Optional per-call cache of
- *   already-walked chains keyed by intermediate id. Reused across parents
- *   in {@link groupByAncestor} to amortise repeat walks.
- * @returns {Promise<Set<number>>} ancestor set including `startId`.
- */
-export async function walkAncestorChain(provider, startId, cache) {
-  // Inner DFS with memoisation. `inProgress` guards cycles so a cyclic
-  // `parent: #N` graph terminates without recursion depth issues. Each
-  // visited node gets its own cache entry holding the set of ids reachable
-  // from it (inclusive), so a sibling walk that re-enters this subgraph
-  // can splice the cached set wholesale instead of re-reading the provider.
-  async function visit(id, inProgress) {
-    if (cache?.has(id)) return cache.get(id);
-    if (inProgress.has(id)) {
-      // Cycle: return a singleton so the caller still includes `id` in its
-      // ancestor set without recursing further through this loop. Do NOT
-      // memoise — the partial result is incomplete for `id`'s true chain.
-      return new Set([id]);
-    }
-    inProgress.add(id);
-
-    const set = new Set([id]);
-    let ticket = null;
-    try {
-      ticket = await provider.getTicket(id);
-    } catch {
-      // Provider read failure: truncate the chain branch. Memoise as the
-      // singleton so subsequent walks don't retry an already-failed read.
-      inProgress.delete(id);
-      cache?.set(id, set);
-      return set;
-    }
-
-    if (ticket?.body) {
-      const matches = [...ticket.body.matchAll(/parent:\s*#(\d+)/gi)];
-      for (const m of matches) {
-        const next = Number.parseInt(m[1], 10);
-        if (!Number.isFinite(next)) continue;
-        const subset = await visit(next, inProgress);
-        for (const v of subset) set.add(v);
-      }
-    }
-
-    inProgress.delete(id);
-    cache?.set(id, set);
-    return set;
-  }
-
-  return visit(startId, new Set());
-}
-
-/**
- * Partitions a list of parent ids into disjoint groups whose members share
- * at least one ancestor (transitively, via `parent: #N` references walked
- * to fixpoint).
- *
- * Two parents end up in the same group if and only if their ancestor sets
- * overlap on at least one ticket id. Parents with no shared ancestors end
- * up in singleton groups. The union of the returned groups equals the
- * input set; the order of `parents[]` is preserved within each group, and
- * groups are returned in the order their first member appears in the
- * input.
- *
- * Pure of side effects beyond the provider reads needed to walk chains.
- * Walked ancestor sets are cached per call so a parent that contributes
- * to multiple groups is not re-walked. Cycle-safe — see
- * {@link walkAncestorChain}.
- *
- * Used by `cascadeCompletion` to dispatch disjoint groups in parallel
- * while keeping shared-ancestor groups strictly sequential (concurrent
- * transitions on the same ancestor would race the "all children done?"
- * check).
- *
- * @param {Array<number>} parents
- * @param {import('../ITicketingProvider.js').ITicketingProvider} provider
- * @returns {Promise<Array<Array<number>>>} disjoint groups of parent ids.
- */
-export async function groupByAncestor(parents, provider) {
-  if (!Array.isArray(parents) || parents.length === 0) return [];
-
-  // Walk each parent's ancestor chain once, sharing a cache so a parent
-  // that re-enters an already-walked subgraph reuses the cached set.
-  const cache = new Map();
-  const ancestorsByParent = new Map();
-  for (const parentId of parents) {
-    const chain = await walkAncestorChain(provider, parentId, cache);
-    ancestorsByParent.set(parentId, chain);
-  }
-
-  return unionFindByAncestor(parents, ancestorsByParent);
-}
-
-/**
- * Union-Find over `parents`, joined whenever any two parents' ancestor
- * chains overlap on at least one id. Returns the parents bucketed by
- * representative, in input order both for the groups themselves and for
- * members within each group.
- *
- * Pulled out of {@link groupByAncestor} to keep that function's CRAP
- * under the v6 ceiling.
- *
- * @param {Array<number>} parents
- * @param {Map<number, Set<number>>} ancestorsByParent
- * @returns {Array<Array<number>>}
- */
-function unionFindByAncestor(parents, ancestorsByParent) {
-  const parentIndex = new Map();
-  parents.forEach((p, i) => {
-    parentIndex.set(p, i);
-  });
-  const uf = parents.map((_, i) => i);
-  const find = (i) => {
-    while (uf[i] !== i) {
-      uf[i] = uf[uf[i]];
-      i = uf[i];
-    }
-    return i;
-  };
-  const union = (a, b) => {
-    const ra = find(a);
-    const rb = find(b);
-    if (ra !== rb) uf[ra] = rb;
-  };
-
-  // For each ancestor id, collect parents whose chain hits it; union them.
-  const ancestorToParents = new Map();
-  for (const [parentId, chain] of ancestorsByParent) {
-    for (const ancestorId of chain) {
-      if (!ancestorToParents.has(ancestorId)) {
-        ancestorToParents.set(ancestorId, []);
-      }
-      ancestorToParents.get(ancestorId).push(parentId);
-    }
-  }
-  for (const sharing of ancestorToParents.values()) {
-    if (sharing.length < 2) continue;
-    const first = parentIndex.get(sharing[0]);
-    for (let i = 1; i < sharing.length; i++) {
-      union(first, parentIndex.get(sharing[i]));
-    }
-  }
-
-  // Bucket parents by representative, preserving first-seen order for
-  // both groups and within-group ordering.
-  const repToGroup = new Map();
-  const groupOrder = [];
-  for (const parentId of parents) {
-    const rep = find(parentIndex.get(parentId));
-    if (!repToGroup.has(rep)) {
-      repToGroup.set(rep, []);
-      groupOrder.push(rep);
-    }
-    repToGroup.get(rep).push(parentId);
-  }
-
-  return groupOrder.map((rep) => repToGroup.get(rep));
-}
-
-/**
- * Dispatches cascade work across disjoint shared-ancestor groups in
- * parallel while running each within-group parent sequentially in input
- * order. Per-parent output is captured into a buffered logger so the
- * visible log stream is byte-identical to a serial baseline; the buffer
- * is flushed to `flushLogger` in the original `parsedParents` order
- * after every group resolves.
- *
- * The actual per-parent work is supplied by `processParent` so this
- * helper stays free of cascade-specific dependencies — its only job is
- * the parallel-dispatch + ordered-flush scaffolding.
- *
- * @template R
- * @param {Object} args
- * @param {Array<number>} args.parsedParents - Parent ids in their
- *   original input order. Drives both the group-membership lookup and
- *   the post-dispatch log flush order.
- * @param {Array<Array<number>>} args.groups - Disjoint groups returned
- *   by {@link groupByAncestor}.
- * @param {(parentId: number, bufferedLogger: object) => Promise<R>} args.processParent
- *   Per-parent worker. Receives the parent id and a buffered logger.
- *   Its resolved value is collected into `args.parsedParents`-ordered
- *   results.
- * @param {{ debug: Function, info: Function, warn: Function, error: Function }} args.flushLogger
- *   Real logger that receives the buffered output after dispatch.
- * @returns {Promise<Array<R>>} per-parent results in `parsedParents`
- *   order.
- */
-export async function dispatchCascadeGroups({
-  parsedParents,
-  groups,
-  processParent,
-  flushLogger,
-}) {
-  const parentLoggers = new Map();
-  const parentResults = new Map();
-  for (const parentId of parsedParents) {
-    parentLoggers.set(parentId, createBufferedLogger());
-  }
-
-  await Promise.all(
-    groups.map(async (group) => {
-      for (const parentId of group) {
-        const logger = parentLoggers.get(parentId);
-        const result = await processParent(parentId, logger);
-        parentResults.set(parentId, result);
-      }
-    }),
-  );
-
-  const results = [];
-  for (const parentId of parsedParents) {
-    const lg = parentLoggers.get(parentId);
-    if (lg) {
-      for (const entry of lg.buffer) {
-        flushLogger[entry.level](entry.message);
-      }
-    }
-    const result = parentResults.get(parentId);
-    if (result !== undefined) results.push(result);
-  }
-  return results;
-}
-
-/**
- * Buffered logger shaped like the public `Logger` surface. Stores every
- * emitted line in `buffer[]` instead of writing to the console. Callers
- * flush the buffer to a real logger after the buffered region completes
- * so the visible log output is byte-identical to a serial run.
- *
- * @returns {{ buffer: Array<{ level: 'debug'|'info'|'warn'|'error', message: string }>, debug: Function, info: Function, warn: Function, error: Function }}
- */
-export function createBufferedLogger() {
-  const buffer = [];
-  return {
-    buffer,
-    debug(message) {
-      buffer.push({ level: 'debug', message });
-    },
-    info(message) {
-      buffer.push({ level: 'info', message });
-    },
-    warn(message) {
-      buffer.push({ level: 'warn', message });
-    },
-    error(message) {
-      buffer.push({ level: 'error', message });
-    },
-  };
-}

package/.agents/scripts/lib/orchestration/epic-runner/progress-reporter.js

@@ -1,69 +0,0 @@
-/**
- * progress-reporter.js — facade module for the /epic-deliver progress
- * narrative. Story #1847 split the original 1158-LOC monolith into three
- * sibling sub-modules under `progress-reporter/`:
- *
- *   - `composition.js` — structured-comment body builders and the pure
- *     rendering helpers (the legacy ProgressReporter class used these).
- *   - `transport.js` — the curated webhook emit surface (epic-started,
- *     epic-progress, epic-blocked, epic-unblocked).
- *   - `signals.js` — pure parse/aggregate over `story-run-progress` and
- *     `phase-timings` structured comments + the shared state lookup
- *     tables (PHASE_TO_STATE, PHASE_ORDER, STATE_EMOJI).
- *
- * Epic #2646 Story C (Task #2699) — the tick-based polling
- * `ProgressReporter` class that used to live here was deleted in favour
- * of the bus-driven `lifecycle/listeners/progress-reporter.js` which
- * already consumes `story.dispatch.end` + `wave.end` to compose the
- * `epic-run-progress` body. The webhook helpers and parse/aggregate
- * exports remain at this path so existing importers
- * (`epic-execute-record-wave.js`, `wave-record-notifications.js`,
- * `crap-remediation-1641.test.js`) keep resolving — only the periodic
- * emission shell went away.
- */
-
-import {
-  deriveState as deriveStateFromComposition,
-  renderProgressBody as renderProgressBodyFromComposition,
-  truncate as truncateFromComposition,
-  upsertEpicRunProgress as upsertEpicRunProgressFromComposition,
-} from './progress-reporter/composition.js';
-import {
-  aggregatePhaseTimings as aggregatePhaseTimingsFromSignals,
-  EPIC_RUN_PROGRESS_TYPE as EPIC_RUN_PROGRESS_TYPE_FROM_SIGNALS,
-  PHASE_TIMINGS_TYPE as PHASE_TIMINGS_TYPE_FROM_SIGNALS,
-  parsePhaseTimingsComment as parsePhaseTimingsCommentFromSignals,
-  parseStoryRunProgressComment as parseStoryRunProgressCommentFromSignals,
-  phaseToState as phaseToStateFromSignals,
-  renderPhaseTimingsSection as renderPhaseTimingsSectionFromSignals,
-  STORY_RUN_PROGRESS_TYPE as STORY_RUN_PROGRESS_TYPE_FROM_SIGNALS,
-} from './progress-reporter/signals.js';
-import {
-  EPIC_PROGRESS_EVENT as EPIC_PROGRESS_EVENT_FROM_TRANSPORT,
-  emitEpicBlocked as emitEpicBlockedFromTransport,
-  emitEpicProgress as emitEpicProgressFromTransport,
-  emitEpicStarted as emitEpicStartedFromTransport,
-  emitEpicUnblocked as emitEpicUnblockedFromTransport,
-} from './progress-reporter/transport.js';
-
-// Re-exports — sub-module surfaces are aliased back to the parent path so
-// existing imports (epic-execute-record-wave.js,
-// wave-record-notifications.js) keep resolving.
-export const EPIC_RUN_PROGRESS_TYPE = EPIC_RUN_PROGRESS_TYPE_FROM_SIGNALS;
-export const PHASE_TIMINGS_TYPE = PHASE_TIMINGS_TYPE_FROM_SIGNALS;
-export const STORY_RUN_PROGRESS_TYPE = STORY_RUN_PROGRESS_TYPE_FROM_SIGNALS;
-export const EPIC_PROGRESS_EVENT = EPIC_PROGRESS_EVENT_FROM_TRANSPORT;
-export const emitEpicProgress = emitEpicProgressFromTransport;
-export const emitEpicStarted = emitEpicStartedFromTransport;
-export const emitEpicBlocked = emitEpicBlockedFromTransport;
-export const emitEpicUnblocked = emitEpicUnblockedFromTransport;
-export const parseStoryRunProgressComment =
-  parseStoryRunProgressCommentFromSignals;
-export const parsePhaseTimingsComment = parsePhaseTimingsCommentFromSignals;
-export const aggregatePhaseTimings = aggregatePhaseTimingsFromSignals;
-export const renderPhaseTimingsSection = renderPhaseTimingsSectionFromSignals;
-export const phaseToState = phaseToStateFromSignals;
-export const upsertEpicRunProgress = upsertEpicRunProgressFromComposition;
-export const deriveState = deriveStateFromComposition;
-export const renderProgressBody = renderProgressBodyFromComposition;
-export const truncate = truncateFromComposition;

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

@@ -1,221 +0,0 @@
-/**
- * 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 };
-}

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

@@ -1,123 +0,0 @@
-/**
- * format-autofix-shared.js — Story #3332 (Epic #3316): single-source the
- * git/formatter plumbing shared by the two format-autofix forks.
- *
- * `format-autofix.js` (whole-tree heal) and `format-autofix-scoped.js`
- * (Epic→Story changed-file heal) historically each carried their own copy
- * of the porcelain-status parse, the formatter-command resolution, and the
- * stage→commit→rev-parse sequence. The three forked helpers are
- * byte-for-byte equivalent apart from cosmetics, so a fix to (say) the
- * porcelain-line slice had to land twice. This module is the single home
- * for all three; the two forks now differ only in file-scope, commit
- * subject, and log level.
- *
- * Every helper takes an injected `git` runner (`(args, opts) => string`) so
- * unit tests pin behaviour without spawning git.
- */
-
-import { resolveFormatWriteCommand } from '../../close-validation.js';
-
-/**
- * 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 fork runs the command verbatim (keeping the trailing `.`
- * so biome formats the entire tree). The scoped fork 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();
-}