mandrel 1.61.0 → 1.63.0

package/.agents/scripts/epic-deliver-prepare.js

@@ -139,101 +139,82 @@ function resolveGitUserEmail(cwd) {
  *   checkpointInitializedAt: string,
  * }>}
  */
-export async function runEpicDeliverPrepare({
+/**
+ * Run the fail-closed preflight guards (Story #3482): refuse on a
+ * dirty/foreign-branch checkout and on a live foreign Epic lease, BEFORE any
+ * snapshot or git mutation. No-op when guards are suppressed. The guards are
+ * skipped when `skipPreflightGuards` is set, OR — implicitly — when a caller
+ * injects a provider but no git seam (the signature of the prepare-runner
+ * unit tests that drive an in-memory provider and never stand up a tree). The
+ * real CLI path injects neither, so the guards always run for an
+ * operator-driven invocation. Story #4075 — extracted from
+ * `runEpicDeliverPrepare`.
+ */
+async function runPreflightGuardsForPrepare({
   epicId,
   cwd,
+  config,
+  provider,
   injectedProvider,
-  injectedConfig,
-  injectedFindings,
-  ignoreConcurrencyHazards = false,
-  steal = false,
-  asOperator,
   injectedGit,
+  asOperator,
+  steal,
   leaseHeartbeatAt,
   leaseNow,
-  skipPreflightGuards = false,
-} = {}) {
-  if (!Number.isInteger(epicId) || epicId <= 0) {
-    throw new TypeError(
-      'runEpicDeliverPrepare: --epic must be a positive integer',
-    );
-  }
-
-  const config = injectedConfig ?? resolveConfig({ cwd });
-  if (!config.github) {
-    throw new Error('runEpicDeliverPrepare: no github block in .agentrc.json');
-  }
-  const provider = injectedProvider ?? createProvider(config);
-  const { deliverRunner } = getRunners(config);
-  const concurrencyCap = deliverRunner.concurrencyCap;
-
-  // Preflight guards (Story #3482): fail closed on a dirty/foreign-branch
-  // checkout and on a live foreign Epic lease, BEFORE any snapshot or git
-  // mutation runs. The guards are injectable so the unit suite exercises them
-  // without a real repo. They are skipped when an explicit `skipPreflightGuards`
-  // is set, OR — implicitly — when a caller injects a provider but no git seam:
-  // that combination is the signature of the pre-existing prepare-runner unit
-  // tests that assert the DAG/checkpoint behaviour against an in-memory
-  // provider and never stand up a working tree. The real CLI path passes
-  // neither `injectedProvider` nor `injectedGit`, so the guards always run for
-  // an operator-driven invocation.
+  skipPreflightGuards,
+}) {
   const guardsSuppressed =
     skipPreflightGuards || (Boolean(injectedProvider) && !injectedGit);
-  if (!guardsSuppressed) {
-    const guardCwd = cwd ?? process.cwd();
-    const git = injectedGit ?? createGitShim(guardCwd);
-    const baseBranch = config.project?.baseBranch ?? 'main';
-    const expectedBranch = [getEpicBranch(epicId), baseBranch];
-    const operator =
-      resolveOperator({
-        asFlag: asOperator,
-        config,
-        gitUserEmail: injectedGit ? undefined : resolveGitUserEmail(guardCwd),
-      }) ?? null;
-
-    // Liveness seam: a foreign claim is only "live" (and so refuses) when the
-    // claim *owner* has a recent `story.heartbeat`. Without this the lease
-    // guard is inert — `heartbeatAt` defaults to null, `isClaimLive(null)` is
-    // false, and every foreign claim looks stale and gets silently reclaimed
-    // (audit #3513). Read the Epic's current assignee (the claim owner) and
-    // resolve that owner's latest heartbeat from the Epic lifecycle ledger
-    // (`temp/epic-<id>/lifecycle.ndjson`) via the shared resolver, so a LIVE
-    // foreign claim actually refuses and only a genuinely stale/absent one is
-    // reclaimed. Tests may inject `leaseHeartbeatAt` directly (any value,
-    // including null) to bypass the ledger read; the CLI passes nothing.
-    let heartbeatAt = leaseHeartbeatAt;
-    if (heartbeatAt === undefined) {
-      const epicTicket = await provider.getTicket(epicId);
-      const claimOwner = leaseCurrentOwner(epicTicket?.assignees);
-      heartbeatAt = claimOwner
-        ? latestHeartbeatForOwner({ epicId, owner: claimOwner, config })
-        : null;
-    }
+  if (guardsSuppressed) return;
 
-    await runPrepareGuards({
-      epicId,
-      expectedBranch,
-      git,
-      provider,
-      operator,
-      heartbeatAt,
-      steal,
+  const guardCwd = cwd ?? process.cwd();
+  const git = injectedGit ?? createGitShim(guardCwd);
+  const baseBranch = config.project?.baseBranch ?? 'main';
+  const expectedBranch = [getEpicBranch(epicId), baseBranch];
+  const operator =
+    resolveOperator({
+      asFlag: asOperator,
       config,
-      now: leaseNow,
-      logger: Logger,
-    });
+      gitUserEmail: injectedGit ? undefined : resolveGitUserEmail(guardCwd),
+    }) ?? null;
+
+  // Liveness seam: a foreign claim is only "live" (and so refuses) when the
+  // claim *owner* has a recent `story.heartbeat`. Without this the lease
+  // guard is inert — every foreign claim looks stale and gets silently
+  // reclaimed (audit #3513). Read the Epic's current assignee (the claim
+  // owner) and resolve that owner's latest heartbeat from the Epic lifecycle
+  // ledger via the shared resolver. Tests may inject `leaseHeartbeatAt`
+  // directly (any value, including null) to bypass the ledger read.
+  let heartbeatAt = leaseHeartbeatAt;
+  if (heartbeatAt === undefined) {
+    const epicTicket = await provider.getTicket(epicId);
+    const claimOwner = leaseCurrentOwner(epicTicket?.assignees);
+    heartbeatAt = claimOwner
+      ? latestHeartbeatForOwner({ epicId, owner: claimOwner, config })
+      : null;
   }
 
-  // Story #3027: try the preflight cache first so we don't re-walk Epic
-  // → Feature → Story when `epic-deliver-preflight.js` already did. The
-  // cache key is a deterministic fingerprint of the Epic ticket plus the
-  // cached Story snapshots (Story #4019): the Epic re-fetch plus one
-  // getTicket per cached Story is still far cheaper than the full
-  // hierarchy BFS, and a Story-dependency edit now invalidates the cache.
-  // Cache miss or baseSha mismatch → fall back to a fresh pass.
-  const ctx = { epicId, provider };
-  let state = {};
-  let cacheStatus = 'miss';
+  await runPrepareGuards({
+    epicId,
+    expectedBranch,
+    git,
+    provider,
+    operator,
+    heartbeatAt,
+    steal,
+    config,
+    now: leaseNow,
+    logger: Logger,
+  });
+}
+
+/**
+ * Resolve the Epic state, preferring the preflight cache (Story #3027) and
+ * falling back to a fresh snapshot + wave-DAG pass on miss or baseSha
+ * mismatch. Returns `{ state, cacheStatus }`. Story #4075 — extracted from
+ * `runEpicDeliverPrepare`.
+ */
+async function resolvePrepareState({ epicId, cwd, provider }) {
   const cached = await readPreflightCache({ epicId, cwd });
   if (cached) {
     const freshEpic = await provider.getTicket(epicId);
@@ -245,35 +226,42 @@ export async function runEpicDeliverPrepare({
     );
     const freshBaseSha = computeBaseSha(freshEpic, freshStories);
     if (freshBaseSha === cached.baseSha) {
-      state = {
-        epic: cached.epic,
-        stories: cached.stories,
-        waves: cached.waves,
+      return {
+        state: {
+          epic: cached.epic,
+          stories: cached.stories,
+          waves: cached.waves,
+        },
+        cacheStatus: 'hit',
       };
-      cacheStatus = 'hit';
-    } else {
-      cacheStatus = 'stale';
     }
   }
-  if (cacheStatus !== 'hit') {
-    state = await runSnapshotPhase(ctx, {}, state);
-    state = await runBuildWaveDagPhase(ctx, {}, state);
-  }
+  const ctx = { epicId, provider };
+  let state = await runSnapshotPhase(ctx, {}, {});
+  state = await runBuildWaveDagPhase(ctx, {}, state);
+  return { state, cacheStatus: cached ? 'stale' : 'miss' };
+}
 
-  // Cross-Story concurrency-hazard gate (Story #2297). Findings come in
-  // via DI; no default loader is wired yet — production callers will
-  // either pass findings derived from the persisted manifest or rely on
-  // the empty default (gate trivially passes).
+/**
+ * Evaluate the cross-Story concurrency-hazard gate (Story #2297). Throws on a
+ * tripped, non-bypassed gate; warns (and returns `gate`) on a bypassed trip.
+ * Story #4075 — extracted from `runEpicDeliverPrepare`.
+ */
+function evaluatePrepareConcurrencyGate({
+  config,
+  waves,
+  injectedFindings,
+  ignoreConcurrencyHazards,
+}) {
   const findings = Array.isArray(injectedFindings) ? injectedFindings : [];
-  const pendingKeys = collectPendingStoryKeys(state.waves);
+  const pendingKeys = collectPendingStoryKeys(waves);
   const pendingFindings = filterFindingsToPending(findings, pendingKeys);
-  const concurrencyPolicy = {
-    failOnConcurrencyHazards:
-      config?.delivery?.failOnConcurrencyHazards === true,
-  };
   const gate = evaluateConcurrencyGate({
     findings: pendingFindings,
-    policy: concurrencyPolicy,
+    policy: {
+      failOnConcurrencyHazards:
+        config?.delivery?.failOnConcurrencyHazards === true,
+    },
     ignore: ignoreConcurrencyHazards === true,
   });
   if (gate.tripped && !gate.bypassed) {
@@ -288,6 +276,63 @@ export async function runEpicDeliverPrepare({
       `[epic-deliver-prepare] ⚠️  Concurrency-hazard gate bypassed via --ignore-concurrency-hazards (reason=${gate.reason}, count=${gate.findings.length}).`,
     );
   }
+  return gate;
+}
+
+export async function runEpicDeliverPrepare({
+  epicId,
+  cwd,
+  injectedProvider,
+  injectedConfig,
+  injectedFindings,
+  ignoreConcurrencyHazards = false,
+  steal = false,
+  asOperator,
+  injectedGit,
+  leaseHeartbeatAt,
+  leaseNow,
+  skipPreflightGuards = false,
+} = {}) {
+  if (!Number.isInteger(epicId) || epicId <= 0) {
+    throw new TypeError(
+      'runEpicDeliverPrepare: --epic must be a positive integer',
+    );
+  }
+
+  const config = injectedConfig ?? resolveConfig({ cwd });
+  if (!config.github) {
+    throw new Error('runEpicDeliverPrepare: no github block in .agentrc.json');
+  }
+  const provider = injectedProvider ?? createProvider(config);
+  const { deliverRunner } = getRunners(config);
+  const concurrencyCap = deliverRunner.concurrencyCap;
+
+  await runPreflightGuardsForPrepare({
+    epicId,
+    cwd,
+    config,
+    provider,
+    injectedProvider,
+    injectedGit,
+    asOperator,
+    steal,
+    leaseHeartbeatAt,
+    leaseNow,
+    skipPreflightGuards,
+  });
+
+  const { state, cacheStatus } = await resolvePrepareState({
+    epicId,
+    cwd,
+    provider,
+  });
+
+  const gate = evaluatePrepareConcurrencyGate({
+    config,
+    waves: state.waves,
+    injectedFindings,
+    ignoreConcurrencyHazards,
+  });
 
   const totalWaves = state.waves.length;
   const checkpointState = await initializeEpicRunState({

package/.agents/scripts/lib/baseline-snapshot.js

@@ -452,6 +452,219 @@ export function commitSnapshotsToEpicBranch({
  *   files: Array<{ kind: 'maintainability'|'crap', path: string, didChange: boolean, reason?: 'no-coverage'|'unchanged'|'updated' }>,
  * }>}
  */
+/**
+ * Build the `files[]` entry for a baseline write, choosing between the
+ * structural-equality short-circuit (no write, `reason: 'unchanged'`) and
+ * the stamp-and-write path (`reason: 'updated'`). Story #4075 — collapses
+ * the duplicated short-circuit branch shared by the MI and CRAP passes.
+ *
+ * @returns {{ entry: object, wrote: boolean }}
+ */
+function commitBaselineEnvelope({
+  kind,
+  abs,
+  envelope,
+  priorEnvelope,
+  writeFileFn,
+  fsImpl,
+}) {
+  if (priorEnvelope && envelope === priorEnvelope) {
+    return {
+      entry: { kind, path: abs, didChange: false, reason: 'unchanged' },
+      wrote: false,
+    };
+  }
+  writeFileFn(abs, envelope, { fsImpl });
+  return {
+    entry: { kind, path: abs, didChange: true, reason: 'updated' },
+    wrote: true,
+  };
+}
+
+/**
+ * Regenerate the maintainability baseline from a fresh tree scan. Returns
+ * `null` when no maintainability baseline path is configured. The scanned
+ * source list is returned so the CRAP pass can reuse it when the two passes
+ * target the same dirs (Story #3663). Story #4075 — extracted from
+ * `regenerateMainFromTree`.
+ */
+async function regenerateMaintainability({
+  cwd,
+  baselines,
+  quality,
+  scanDirectoryFn,
+  calculateAllFn,
+  writeFn,
+  writeFileFn,
+  loadPriorFn,
+  fsImpl,
+}) {
+  const miPath = baselines?.maintainability?.path;
+  if (typeof miPath !== 'string' || miPath.length === 0) return null;
+
+  const miTargetDirs = quality?.maintainability?.targetDirs ?? [];
+  const miIgnoreGlobs = quality?.maintainability?.ignoreGlobs ?? [];
+  const miAbs = path.isAbsolute(miPath) ? miPath : path.resolve(cwd, miPath);
+  const miSourceList = [];
+  for (const dir of miTargetDirs) {
+    const abs = path.isAbsolute(dir) ? dir : path.resolve(cwd, dir);
+    scanDirectoryFn(abs, miSourceList, { cwd, ignoreGlobs: miIgnoreGlobs });
+  }
+  const scores = await calculateAllFn(miSourceList);
+
+  // Project the scoring helper's `{path: mi}` map onto the writer's
+  // canonical row shape. Story #2079 path-canon defence stays in place —
+  // the writer would canonicalise again, but doing it here keeps any
+  // pre-canonicalised comparison inside the function meaningful.
+  const miRows = filterExcludedRows(
+    Object.entries(scores).map(([key, mi]) => {
+      const rel = path.isAbsolute(key) ? path.relative(cwd, key) : key;
+      const posixRel = rel.split(path.sep).join('/');
+      return { path: canonicalisePath(posixRel), mi };
+    }),
+  );
+
+  const priorMi = loadPriorFn(miAbs, 'maintainability');
+  const envelope = writeFn({
+    kind: 'maintainability',
+    rows: miRows,
+    priorEnvelope: priorMi,
+  });
+  const { entry, wrote } = commitBaselineEnvelope({
+    kind: 'maintainability',
+    abs: miAbs,
+    envelope,
+    priorEnvelope: priorMi,
+    writeFileFn,
+    fsImpl,
+  });
+  return { entry, wrote, miSourceList, miTargetDirs, miIgnoreGlobs };
+}
+
+/**
+ * Decide whether the CRAP pass can reuse the MI scan's file list — true only
+ * when both passes target the same dirs with the same ignore globs
+ * (Story #3663).
+ */
+function crapDirsMatchMi({
+  miSourceList,
+  crapTargetDirs,
+  crapIgnoreGlobs,
+  miTargetDirs,
+  miIgnoreGlobs,
+}) {
+  return (
+    miSourceList !== null &&
+    crapTargetDirs.length === miTargetDirs.length &&
+    crapTargetDirs.every((d, i) => d === miTargetDirs[i]) &&
+    crapIgnoreGlobs.length === miIgnoreGlobs.length &&
+    crapIgnoreGlobs.every((g, i) => g === miIgnoreGlobs[i])
+  );
+}
+
+/**
+ * Regenerate the CRAP baseline from a fresh tree scan + coverage map.
+ * Returns `null` when no CRAP baseline path is configured. Story #4075 —
+ * extracted from `regenerateMainFromTree`.
+ */
+async function regenerateCrap({
+  cwd,
+  baselines,
+  quality,
+  logger,
+  miScan,
+  scanAndScoreFn,
+  loadCoverageFn,
+  resolveEscomplexVersionFn,
+  resolveTsTranspilerVersionFn,
+  writeFn,
+  writeFileFn,
+  loadPriorFn,
+  fsImpl,
+}) {
+  const crapPath = baselines?.crap?.path;
+  if (typeof crapPath !== 'string' || crapPath.length === 0) return null;
+
+  const crapCfg = quality?.crap ?? {};
+  const crapTargetDirs = Array.isArray(crapCfg.targetDirs)
+    ? crapCfg.targetDirs
+    : [];
+  const crapIgnoreGlobs = Array.isArray(crapCfg.ignoreGlobs)
+    ? crapCfg.ignoreGlobs
+    : [];
+  const requireCoverage = crapCfg.requireCoverage !== false;
+  const coveragePath = crapCfg.coveragePath ?? 'coverage/coverage-final.json';
+  const crapAbs = path.isAbsolute(crapPath)
+    ? crapPath
+    : path.resolve(cwd, crapPath);
+  const coverageAbs = path.isAbsolute(coveragePath)
+    ? coveragePath
+    : path.resolve(cwd, coveragePath);
+  const coverage = loadCoverageFn(coverageAbs);
+
+  if (!coverage && requireCoverage) {
+    logger.warn?.(
+      `[baseline-snapshot] ⚠ no coverage at ${coveragePath} — skipping crap regeneration (refresh stays clean for this file).`,
+    );
+    return {
+      entry: {
+        kind: 'crap',
+        path: crapAbs,
+        didChange: false,
+        reason: 'no-coverage',
+      },
+      wrote: false,
+    };
+  }
+
+  const reusePreScan = crapDirsMatchMi({
+    miSourceList: miScan?.miSourceList ?? null,
+    crapTargetDirs,
+    crapIgnoreGlobs,
+    miTargetDirs: miScan?.miTargetDirs ?? [],
+    miIgnoreGlobs: miScan?.miIgnoreGlobs ?? [],
+  });
+  const { rows } = await scanAndScoreFn({
+    targetDirs: crapTargetDirs,
+    coverage,
+    requireCoverage,
+    cwd,
+    ignoreGlobs: crapIgnoreGlobs,
+    ...(reusePreScan && { preScannedFiles: miScan.miSourceList }),
+  });
+  // scanAndScore yields rows keyed by `file:`; the per-kind crap module's
+  // `projectRow` handles `path ?? file`, so the writer takes either.
+  // Filter to actually-scored rows here (crap is nullable for trivial
+  // methods); the writer's `assertEnvelope` would reject otherwise.
+  const crapRows = (rows ?? []).filter(
+    (r) => typeof r?.crap === 'number' && Number.isFinite(r.crap),
+  );
+
+  // CRAP gates need the running scorer's versions present on the
+  // envelope-adjacent shape; the V2 envelope itself only carries
+  // `kernelVersion`, so we stamp escomplex/tsTranspiler via the writer's
+  // `kernelVersion` override and let the existing per-kind module resolve
+  // the rest. We also resolve them eagerly so a test stub can pin them
+  // deterministically.
+  resolveEscomplexVersionFn(cwd);
+  resolveTsTranspilerVersionFn();
+
+  const priorCrap = loadPriorFn(crapAbs, 'crap');
+  const envelope = writeFn({
+    kind: 'crap',
+    rows: crapRows,
+    priorEnvelope: priorCrap,
+  });
+  return commitBaselineEnvelope({
+    kind: 'crap',
+    abs: crapAbs,
+    envelope,
+    priorEnvelope: priorCrap,
+    writeFileFn,
+    fsImpl,
+  });
+}
+
 export async function regenerateMainFromTree({
   cwd = process.cwd(),
   resolveConfig = defaultResolveConfig,
@@ -476,149 +689,40 @@ export async function regenerateMainFromTree({
   const files = [];
   let didChange = false;
 
-  // ── maintainability ──────────────────────────────────────────────────────
-  const miPath = baselines?.maintainability?.path;
-  const miTargetDirs = quality?.maintainability?.targetDirs ?? [];
-  const miIgnoreGlobs = quality?.maintainability?.ignoreGlobs ?? [];
-  // Hoisted so the CRAP pass can reuse it when targetDirs match — avoids a
-  // second full-tree walk over the same directories (Story #3663).
-  let miSourceList = null;
-  if (typeof miPath === 'string' && miPath.length > 0) {
-    const miAbs = path.isAbsolute(miPath) ? miPath : path.resolve(cwd, miPath);
-    miSourceList = [];
-    for (const dir of miTargetDirs) {
-      const abs = path.isAbsolute(dir) ? dir : path.resolve(cwd, dir);
-      scanDirectoryFn(abs, miSourceList, { cwd, ignoreGlobs: miIgnoreGlobs });
-    }
-    const scores = await calculateAllFn(miSourceList);
-
-    // Project the scoring helper's `{path: mi}` map onto the writer's
-    // canonical row shape. Story #2079 path-canon defence stays in place —
-    // the writer would canonicalise again, but doing it here keeps any
-    // pre-canonicalised comparison inside the function meaningful.
-    const miRows = filterExcludedRows(
-      Object.entries(scores).map(([key, mi]) => {
-        const rel = path.isAbsolute(key) ? path.relative(cwd, key) : key;
-        const posixRel = rel.split(path.sep).join('/');
-        return { path: canonicalisePath(posixRel), mi };
-      }),
-    );
-
-    const priorMi = loadPriorFn(miAbs, 'maintainability');
-    const envelope = writeFn({
-      kind: 'maintainability',
-      rows: miRows,
-      priorEnvelope: priorMi,
-    });
-    if (priorMi && envelope === priorMi) {
-      // Structural-equality short-circuit fired — on-disk bytes are
-      // guaranteed identical, no writeFile invocation needed.
-      files.push({
-        kind: 'maintainability',
-        path: miAbs,
-        didChange: false,
-        reason: 'unchanged',
-      });
-    } else {
-      writeFileFn(miAbs, envelope, { fsImpl });
-      didChange = true;
-      files.push({
-        kind: 'maintainability',
-        path: miAbs,
-        didChange: true,
-        reason: 'updated',
-      });
-    }
+  const miScan = await regenerateMaintainability({
+    cwd,
+    baselines,
+    quality,
+    scanDirectoryFn,
+    calculateAllFn,
+    writeFn,
+    writeFileFn,
+    loadPriorFn,
+    fsImpl,
+  });
+  if (miScan) {
+    files.push(miScan.entry);
+    didChange = didChange || miScan.wrote;
   }
 
-  // ── crap ─────────────────────────────────────────────────────────────────
-  const crapPath = baselines?.crap?.path;
-  const crapCfg = quality?.crap ?? {};
-  const crapTargetDirs = Array.isArray(crapCfg.targetDirs)
-    ? crapCfg.targetDirs
-    : [];
-  const crapIgnoreGlobs = Array.isArray(crapCfg.ignoreGlobs)
-    ? crapCfg.ignoreGlobs
-    : [];
-  const requireCoverage = crapCfg.requireCoverage !== false;
-  const coveragePath = crapCfg.coveragePath ?? 'coverage/coverage-final.json';
-  if (typeof crapPath === 'string' && crapPath.length > 0) {
-    const crapAbs = path.isAbsolute(crapPath)
-      ? crapPath
-      : path.resolve(cwd, crapPath);
-    const coverageAbs = path.isAbsolute(coveragePath)
-      ? coveragePath
-      : path.resolve(cwd, coveragePath);
-    const coverage = loadCoverageFn(coverageAbs);
-    if (!coverage && requireCoverage) {
-      logger.warn?.(
-        `[baseline-snapshot] ⚠ no coverage at ${coveragePath} — skipping crap regeneration (refresh stays clean for this file).`,
-      );
-      files.push({
-        kind: 'crap',
-        path: crapAbs,
-        didChange: false,
-        reason: 'no-coverage',
-      });
-    } else {
-      // Reuse the MI scan's file list when CRAP and MI target the same
-      // directories with the same ignore globs — avoids a second full-tree
-      // walk over identical source trees (Story #3663).
-      const crapDirsMatchMi =
-        miSourceList !== null &&
-        crapTargetDirs.length === miTargetDirs.length &&
-        crapTargetDirs.every((d, i) => d === miTargetDirs[i]) &&
-        crapIgnoreGlobs.length === miIgnoreGlobs.length &&
-        crapIgnoreGlobs.every((g, i) => g === miIgnoreGlobs[i]);
-      const { rows } = await scanAndScoreFn({
-        targetDirs: crapTargetDirs,
-        coverage,
-        requireCoverage,
-        cwd,
-        ignoreGlobs: crapIgnoreGlobs,
-        ...(crapDirsMatchMi && { preScannedFiles: miSourceList }),
-      });
-      // scanAndScore yields rows keyed by `file:`; the per-kind crap module's
-      // `projectRow` handles `path ?? file`, so the writer takes either.
-      // Filter to actually-scored rows here (crap is nullable for trivial
-      // methods); the writer's `assertEnvelope` would reject otherwise.
-      const crapRows = (rows ?? []).filter(
-        (r) => typeof r?.crap === 'number' && Number.isFinite(r.crap),
-      );
-
-      // CRAP gates need the running scorer's versions present on the
-      // envelope-adjacent shape; the V2 envelope itself only carries
-      // `kernelVersion`, so we stamp escomplex/tsTranspiler via the writer's
-      // `kernelVersion` override and let the existing per-kind module
-      // resolve the rest. We also resolve them eagerly so a test stub can
-      // pin them deterministically.
-      resolveEscomplexVersionFn(cwd);
-      resolveTsTranspilerVersionFn();
-
-      const priorCrap = loadPriorFn(crapAbs, 'crap');
-      const envelope = writeFn({
-        kind: 'crap',
-        rows: crapRows,
-        priorEnvelope: priorCrap,
-      });
-      if (priorCrap && envelope === priorCrap) {
-        files.push({
-          kind: 'crap',
-          path: crapAbs,
-          didChange: false,
-          reason: 'unchanged',
-        });
-      } else {
-        writeFileFn(crapAbs, envelope, { fsImpl });
-        didChange = true;
-        files.push({
-          kind: 'crap',
-          path: crapAbs,
-          didChange: true,
-          reason: 'updated',
-        });
-      }
-    }
+  const crapResult = await regenerateCrap({
+    cwd,
+    baselines,
+    quality,
+    logger,
+    miScan,
+    scanAndScoreFn,
+    loadCoverageFn,
+    resolveEscomplexVersionFn,
+    resolveTsTranspilerVersionFn,
+    writeFn,
+    writeFileFn,
+    loadPriorFn,
+    fsImpl,
+  });
+  if (crapResult) {
+    files.push(crapResult.entry);
+    didChange = didChange || crapResult.wrote;
   }
 
   return { didChange, files };