mandrel 2.66.0 → 2.68.0

package/.agents/scripts/quality-preview.js

@@ -18,7 +18,7 @@ import { CODING_GUARDRAILS } from './lib/config/quality.js';
 
 const USAGE = {
   invocation:
-    'node .agents/scripts/quality-preview.js [--staged | --changed-since <ref>] [--json]',
+    'node .agents/scripts/quality-preview.js [--staged | --changed-since <ref>] [--only mi|crap] [--json]',
   summary:
     'Preview the per-file maintainability and CRAP deltas for the change set, and exit non-zero on any threshold violation.',
   flags: [
@@ -30,6 +30,10 @@ const USAGE = {
       '--changed-since <ref>',
       'Score the diff against <ref> (default: HEAD). Last occurrence wins.',
     ],
+    [
+      '--only mi|crap',
+      'Run one half only — maintainability (`mi`) or CRAP (`crap`); the other half is reported as not run. Default: both, serially.',
+    ],
     ['--json', 'Emit both gate envelopes plus the merged table as JSON.'],
   ],
 };
@@ -73,6 +77,96 @@ export function parseStagedFlag(argv) {
   return argv.includes('--staged');
 }
 
+/** The halves `--only` can select. */
+const PREVIEW_HALVES = new Set(['mi', 'crap']);
+
+/**
+ * `--only <half>` (last occurrence wins); `null` runs both halves. A value
+ * outside {@link PREVIEW_HALVES} is returned as-is for the caller to refuse.
+ *
+ * @param {string[]} argv
+ * @returns {string | null}
+ */
+function parseOnlyArg(argv) {
+  const at = argv.lastIndexOf('--only');
+  return at === -1 ? null : (argv[at + 1] ?? '');
+}
+
+/**
+ * @param {string|null} only
+ * @returns {boolean}
+ */
+function isUnknownHalf(only) {
+  return only !== null && !PREVIEW_HALVES.has(only);
+}
+
+/**
+ * Run `half` unless `--only` selected the other one.
+ *
+ * @param {{ only: string|null, half: 'mi'|'crap', run: () => Promise<{exitCode: number, envelope: object|null}> }} opts
+ * @returns {Promise<{exitCode: number, envelope: object|null}>}
+ */
+function runHalf({ only, half, run }) {
+  return only === null || only === half ? run() : Promise.resolve(NOT_RUN);
+}
+
+/**
+ * The `--json` field naming the selected half; empty for the default run so
+ * its envelope stays byte-identical.
+ *
+ * @param {string|null} only
+ * @returns {{ only?: string }}
+ */
+function onlyField(only) {
+  return only ? { only } : {};
+}
+
+/**
+ * The report line naming the selected half; empty for the default run.
+ *
+ * @param {string|null} only
+ * @returns {string}
+ */
+function halfLine(only) {
+  return only ? `half=${only} only — the other half was not run\n` : '';
+}
+
+/**
+ * `--staged` wins; otherwise `--changed-since` (absent → `HEAD`).
+ *
+ * @param {string[]} argv
+ * @param {boolean} staged
+ * @returns {string|null}
+ */
+function resolveRef(argv, staged) {
+  return staged ? null : (parseChangedSinceArg(argv) ?? 'HEAD');
+}
+
+/** A half `--only` left out: clean, with no envelope to merge. */
+const NOT_RUN = Object.freeze({ exitCode: 0, envelope: null });
+
+/**
+ * Run the selected halves serially, not via Promise.all: each runner sizes its
+ * own pool to availableParallelism, so overlapping them oversubscribes 2x and
+ * stacks two escomplex heaps (>1 GB RSS).
+ *
+ * @param {{ only: string|null, args: object, runMi: Function, runCrap: Function, stderr: { write: (s: string) => void } }} opts
+ * @returns {Promise<{ miResult: {exitCode: number, envelope: object|null}, crapResult: {exitCode: number, envelope: object|null} }>}
+ */
+async function runHalves({ only, args, runMi, runCrap, stderr }) {
+  const miResult = await runHalf({
+    only,
+    half: 'mi',
+    run: () => runGateSafely(runMi, args, 'MI', stderr),
+  });
+  const crapResult = await runHalf({
+    only,
+    half: 'crap',
+    run: () => runGateSafely(runCrap, args, 'CRAP', stderr),
+  });
+  return { miResult, crapResult };
+}
+
 /**
  * @param {unknown} value
  * @returns {number}
@@ -325,6 +419,7 @@ function stagedScopeLine({ staged, ref, cwd }) {
  *
  * @param {{
  *   json: boolean,
+ *   only: string|null,
  *   staged: boolean,
  *   ref: string|null,
  *   cwd: string,
@@ -338,6 +433,7 @@ function stagedScopeLine({ staged, ref, cwd }) {
  */
 function emitReport({
   json,
+  only,
   staged,
   ref,
   cwd,
@@ -355,6 +451,7 @@ function emitReport({
         {
           ref: staged ? null : ref,
           staged,
+          ...onlyField(only),
           mi: { exit: miExit, envelope: miResult.envelope },
           crap: { exit: crapExit, envelope: crapResult.envelope },
           merged,
@@ -366,6 +463,7 @@ function emitReport({
     return;
   }
   stdout.write('\n--- quality:preview ---\n');
+  stdout.write(halfLine(only));
   stdout.write(stagedScopeLine({ staged, ref, cwd }));
   stdout.write(`${renderTable(merged)}\n`);
   writeAdvisories(merged.advisories, stdout);
@@ -399,23 +497,22 @@ export async function runCli({
 } = {}) {
   const json = parseJsonFlag(argv);
   const staged = parseStagedFlag(argv);
-  const ref = staged ? null : (parseChangedSinceArg(argv) ?? 'HEAD');
+  const ref = resolveRef(argv, staged);
+  const only = parseOnlyArg(argv);
+  if (isUnknownHalf(only)) {
+    stderr.write(
+      `[quality:preview] --only takes mi or crap (got "${only}").\n`,
+    );
+    return { exitCode: 2, merged: mergeEnvelopes(null, null) };
+  }
 
-  // Serial, not Promise.all: each runner sizes its own pool to
-  // availableParallelism, so overlapping them oversubscribes 2x and stacks
-  // two escomplex heaps (>1 GB RSS).
-  const miResult = await runGateSafely(
+  const { miResult, crapResult } = await runHalves({
+    only,
+    args: { cwd, staged, changedSinceRef: ref },
     runMi,
-    { cwd, staged, changedSinceRef: ref },
-    'MI',
-    stderr,
-  );
-  const crapResult = await runGateSafely(
     runCrap,
-    { cwd, staged, changedSinceRef: ref },
-    'CRAP',
     stderr,
-  );
+  });
 
   const merged = mergeEnvelopes(miResult.envelope, crapResult.envelope, {
     cyclomaticFlag: DEFAULT_CYCLOMATIC_FLAG,
@@ -423,6 +520,7 @@ export async function runCli({
 
   emitReport({
     json,
+    only,
     staged,
     ref,
     cwd,

package/.agents/scripts/single-story-init.js

@@ -229,10 +229,60 @@ export function decideStoryBranchSeed({ localHas, remoteHas }) {
 }
 
 /**
- * Reap merged `story-*` branches (excluding the current one). Never blocks
- * init. Protected candidates (unpushed work, dirty worktree, open Story) are
- * skipped; the lockfile is shared with `boot-sweep.js` via
- * `resolveSweepLockPath` so concurrent reaps cannot race.
+ * Remove closed-Story `.worktrees/story-<id>` trees through the boot sweep's
+ * own seam (`runWorktreeSweep`: same lock, same invariants). The Story being
+ * initialized is always kept, whatever its ticket state. Never throws: a
+ * failure lands in the returned outcome, which rides the init envelope.
+ *
+ * @returns {Promise<object>} `{ ok, reaped, skipped, reason?, error? }`.
+ */
+export async function reapClosedStoryWorktrees({
+  cwd,
+  storyBranch,
+  provider,
+  lockPath,
+  lockTimeoutMs,
+  worktreeSweepFn,
+  acquireLockFn,
+}) {
+  const logger = {
+    info: (m) => progress('CLEANUP', m),
+    warn: (m) => progress('CLEANUP', `⚠️ ${m}`),
+  };
+  try {
+    const { runWorktreeSweep } = await import('./boot-sweep.js');
+    const outcome = await runWorktreeSweep({
+      root: cwd,
+      provider,
+      lockPath,
+      lockTimeoutMs,
+      ...(worktreeSweepFn ? { sweepFn: worktreeSweepFn } : {}),
+      ...(acquireLockFn ? { acquireLockFn } : {}),
+      logger,
+      logTag: '[worktree-sweep]',
+      keepPaths: [path.join(cwd, '.worktrees', storyBranch)],
+    });
+    if (outcome.reaped?.length > 0) {
+      progress(
+        'CLEANUP',
+        `🧹 removed ${outcome.reaped.length} closed-Story worktree(s).`,
+      );
+    }
+    return outcome;
+  } catch (err) {
+    const msg = err?.message ?? String(err);
+    logger.warn(`worktree sweep threw (init continues): ${msg}`);
+    return { ok: false, error: msg, reaped: [], skipped: [] };
+  }
+}
+
+/**
+ * Reap merged `story-*` branches (excluding the current one), then the
+ * closed-Story worktrees. Never blocks init. Protected candidates (unpushed
+ * work, dirty worktree, open Story) are skipped; the lockfile is shared with
+ * `boot-sweep.js` via `resolveSweepLockPath` so concurrent reaps cannot race.
+ *
+ * @returns {Promise<{ worktreeSweep: object }>}
  */
 export async function reapMergedStoryBranches({
   cwd,
@@ -241,6 +291,8 @@ export async function reapMergedStoryBranches({
   config,
   provider,
   injectedSweep,
+  worktreeSweepFn,
+  acquireLockFn,
 }) {
   const sweepFn =
     injectedSweep ??
@@ -248,7 +300,37 @@ export async function reapMergedStoryBranches({
   const tempRoot = config?.project?.paths?.tempRoot ?? 'temp';
   const lockPath = resolveSweepLockPath({ cwd, tempRoot });
   const lockTimeoutMs =
-    config.delivery?.worktreeIsolation?.sweepLockMs ?? 60_000;
+    config?.delivery?.worktreeIsolation?.sweepLockMs ?? 60_000;
+  await reapMergedBranches({
+    cwd,
+    baseBranch,
+    storyBranch,
+    provider,
+    sweepFn,
+    lockPath,
+    lockTimeoutMs,
+  });
+  const worktreeSweep = await reapClosedStoryWorktrees({
+    cwd,
+    storyBranch,
+    provider,
+    lockPath,
+    lockTimeoutMs,
+    worktreeSweepFn,
+    acquireLockFn,
+  });
+  return { worktreeSweep };
+}
+
+async function reapMergedBranches({
+  cwd,
+  baseBranch,
+  storyBranch,
+  provider,
+  sweepFn,
+  lockPath,
+  lockTimeoutMs,
+}) {
   try {
     const sweep = await sweepFn({
       cwd,
@@ -300,9 +382,12 @@ export async function reapMergedStoryBranches({
  * @param {object} opts.config
  * @param {object} opts.provider
  * @param {Function|undefined} opts.injectedSweep
+ * @param {Function} [opts.worktreeSweepFn] Test override for the
+ *   closed-Story worktree sweep.
  * @param {Function} opts.progress
  * @param {import('./lib/git/cached-fetch.js').FetchCache} [opts.fetchCache]
  *   Test override; production shares the module singleton.
+ * @returns {Promise<{ worktreeSweep: object }>}
  */
 export async function materializeBaseBranch({
   cwd,
@@ -311,6 +396,7 @@ export async function materializeBaseBranch({
   config,
   provider,
   injectedSweep,
+  worktreeSweepFn,
   progress,
   fetchCache,
 }) {
@@ -326,13 +412,14 @@ export async function materializeBaseBranch({
     );
   }
 
-  await reapMergedStoryBranches({
+  const { worktreeSweep } = await reapMergedStoryBranches({
     cwd,
     baseBranch,
     storyBranch,
     config,
     provider,
     injectedSweep,
+    worktreeSweepFn,
   });
 
   if (!branchExistsLocally(baseBranch, cwd)) {
@@ -342,10 +429,19 @@ export async function materializeBaseBranch({
         `Failed to fetch base branch ${baseBranch}: ${r.stderr || '(no stderr)'}`,
       );
     }
-    return;
+    return { worktreeSweep };
   }
 
-  // `git fetch` leaves local base at the old tip until fast-forwarded.
+  fastForwardBase({ cwd, baseBranch, progress });
+  return { worktreeSweep };
+}
+
+/**
+ * `git fetch` leaves local base at the old tip until fast-forwarded.
+ *
+ * @param {{ cwd: string, baseBranch: string, progress: Function }} opts
+ */
+function fastForwardBase({ cwd, baseBranch, progress }) {
   const ffPlan = planFastForward({ cwd, baseBranch });
   const ff = executeFastForward({
     cwd,
@@ -461,6 +557,7 @@ export async function runSingleStoryInit({
   injectedProvider,
   injectedConfig,
   injectedSweep,
+  injectedWorktreeSweep,
   injectedAcquireLease,
   steal = false,
   injectedVerifyRemote,
@@ -533,6 +630,7 @@ export async function runSingleStoryInit({
   let workCwd = cwd;
   let worktreeCreated = false;
   let installStatus = { status: 'skipped', reason: 'dry-run' };
+  let worktreeSweep = null;
 
   if (!dryRun) {
     const acquire = injectedAcquireLease ?? acquireStoryLease;
@@ -563,15 +661,17 @@ export async function runSingleStoryInit({
     await rollUpContainerEpic(provider, storyId, config);
 
     try {
-      await injectedMaterialize({
-        cwd,
-        baseBranch,
-        storyBranch,
-        config,
-        provider,
-        injectedSweep,
-        progress,
-      });
+      ({ worktreeSweep } =
+        (await injectedMaterialize({
+          cwd,
+          baseBranch,
+          storyBranch,
+          config,
+          provider,
+          injectedSweep,
+          worktreeSweepFn: injectedWorktreeSweep,
+          progress,
+        })) ?? {});
       injectedSeedBranch({ cwd, storyBranch, baseBranch, progress });
       ({ workCwd, worktreeCreated, installStatus } =
         await injectedProvisionWorktree({
@@ -610,6 +710,9 @@ export async function runSingleStoryInit({
     installStatus,
     dependenciesInstalled,
     installFailed: installStatus.status === 'failed',
+    // Closed-Story worktree sweep outcome; a failure degrades here, never
+    // into an init failure. `null` under --dry-run.
+    worktreeSweep: worktreeSweep ?? null,
     dryRun,
     remoteVerified: remote.remoteVerified,
     remoteProbe: { remoteUrl: remote.remoteUrl, detail: remote.detail },

package/.agents/scripts/stories-wave-tick.js

@@ -183,6 +183,15 @@ delivery.deliverRunner.footprintGuard: under "advisory" the collisions are
 detected and listed in "advisory" but never withhold, and dispatch follows the
 declared depends_on edges alone.
 
+crossRunOverlaps (probe mode only) is ADVISORY: each probed Story that is
+ready or in flight and shares a concrete path with an open Story in flight in
+ANOTHER session (outside --stories) — { id, otherId, holder, paths } — plus one
+stderr warning line per pair. It never withholds, reorders or delays dispatch
+and never changes the exit code; it uses the same concrete-path rule as
+inFlightReservation. When the outside query fails the envelope carries
+crossRunOverlapProbe: "unavailable" and crossRunOverlapProbeReason instead of
+the list, so "no overlap" is never inferred from a failed read.
+
 Exit codes:
   0 - Success, ready set emitted
   1 - Invalid input (missing/malformed DAG, invalid --concurrency/--in-flight/--done)
@@ -890,6 +899,7 @@ export function runStoriesWaveTick({
  * @param {NodeJS.ProcessEnv} [args.env]
  * @param {Function} [args.probe]   Test seam.
  * @param {Function} [args.context] Test seam.
+ * @param {Function} [args.warn]  Test seam.
  * @returns {Promise<{ envelope: object, exitCode: number, records: object[] }>}
  *   `records` are the probed nodes, kept off stdout.
  */
@@ -902,6 +912,7 @@ export async function runProbedStoriesWaveTick({
   env,
   probe = probeLiveState,
   context = createProbeContext,
+  warn = Logger.warn,
 } = {}) {
   const { value: override, error: concurrencyError } =
     parseConcurrencyOverride(concurrency);
@@ -956,6 +967,8 @@ export async function runProbedStoriesWaveTick({
     foreignHeld = [],
     inFlightRecords = [],
   } = probed;
+  const crossRun = crossRunFields(probed);
+  for (const line of crossRunWarnings(crossRun.crossRunOverlaps)) warn(line);
   const { envelope, exitCode } = buildReadySetEnvelope(nodes, {
     concurrencyCap,
     capPrecedence,
@@ -979,6 +992,7 @@ export async function runProbedStoriesWaveTick({
       stalledDispatch,
       foreignHeld,
       foreignHeldReason: foreignHeldReasonFor(foreignHeld),
+      ...crossRun,
     },
     records: nodes,
     // Blocked outranks a wedge (its blockers are moot while a human owes a
@@ -990,6 +1004,39 @@ export async function runProbedStoriesWaveTick({
   };
 }
 
+/**
+ * Exactly one advisory shape passes through; a failed read never becomes [].
+ *
+ * @param {object} probed
+ * @returns {object}
+ */
+function crossRunFields(probed) {
+  if (Array.isArray(probed.crossRunOverlaps)) {
+    return { crossRunOverlaps: probed.crossRunOverlaps };
+  }
+  if (probed.crossRunOverlapProbe === 'unavailable') {
+    return {
+      crossRunOverlapProbe: 'unavailable',
+      crossRunOverlapProbeReason: probed.crossRunOverlapProbeReason ?? null,
+    };
+  }
+  return {};
+}
+
+/**
+ * @param {object[]} [overlaps]
+ * @returns {string[]}
+ */
+function crossRunWarnings(overlaps = []) {
+  return overlaps.map(({ id, otherId, holder, paths }) => {
+    const who = holder ? `held by @${holder}` : 'holder unknown';
+    return (
+      `stories-wave-tick: #${id} overlaps #${otherId} (in flight in another session, ${who}) ` +
+      `on ${paths.join(', ')} — expect a rebase conflict at close. Advisory only; dispatch is unchanged.`
+    );
+  });
+}
+
 /**
  * @param {number[]} blockedIds
  * @returns {string|null}

package/.agents/scripts/story-review-compute.js

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+
+/**
+ * story-review-compute.js — compute the Story-scope review on the worker, at
+ * push time, and deposit it for close to adopt.
+ *
+ * Runs close's compute step (`computeStoryScopeReview` over the configured
+ * provider chain, posting nothing) against `origin/<base>...story-<id>` and
+ * writes one held-review JSON beside the terminal envelope, keyed on the diff
+ * digest. Close adopts it when the digest still matches, so the serialized
+ * close tail only posts; a CRITICAL surfaces here, where the worker can fix
+ * and re-push inside its own parallel loop.
+ *
+ * Posts nothing to GitHub and takes no full-suite lock. Exit 0 whatever the
+ * findings; 1 only on a usage error or a provider throw.
+ */
+
+import { parseArgs } from 'node:util';
+
+import { runAsCli } from './lib/cli-utils.js';
+import { resolveConfig } from './lib/config-resolver.js';
+import { getStoryBranch, gitSpawn } from './lib/git-utils.js';
+import { runCodeReview } from './lib/orchestration/code-review.js';
+import { resolveSharedBaseRef } from './lib/orchestration/review-base-ref.js';
+import {
+  buildReviewDeposit,
+  computeReviewDiffDigest,
+  resolveRefSha,
+  writeReviewDeposit,
+} from './lib/orchestration/review-deposit.js';
+import { computeStoryScopeReview } from './lib/orchestration/single-story-close/phases/code-review.js';
+
+const USAGE = {
+  invocation:
+    'node .agents/scripts/story-review-compute.js --story <id> [--cwd <workCwd>]',
+  summary:
+    'Compute the Story-scope code review of origin/<base>...story-<id> without posting it, and write the held result (keyed on the diff digest) for close to adopt. Exits 0 whatever the findings.',
+  flags: [
+    ['--story <id>', 'Story issue number; the head ref is story-<id>.'],
+    [
+      '--cwd <path>',
+      'Checkout to resolve the branch and diff in (default: the current directory).',
+    ],
+  ],
+};
+
+/**
+ * @param {string[]} argv
+ * @returns {{ storyId: number|null, cwd: string|null }}
+ */
+export function parseArgv(argv) {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      story: { type: 'string' },
+      cwd: { type: 'string' },
+    },
+    strict: false,
+  });
+  const storyId = Number.parseInt(values.story ?? '', 10);
+  return {
+    storyId: Number.isInteger(storyId) && storyId > 0 ? storyId : null,
+    cwd: values.cwd ?? null,
+  };
+}
+
+/**
+ * @param {object} severity
+ * @returns {string}
+ */
+function formatTally(severity) {
+  const s = severity ?? {};
+  return `critical=${s.critical ?? 0} high=${s.high ?? 0} medium=${s.medium ?? 0} suggestion=${s.suggestion ?? 0}`;
+}
+
+/**
+ * @param {{ storyId: number, cwd: string, config: object }} input
+ * @param {{
+ *   gitSpawnFn?: typeof gitSpawn,
+ *   runCodeReviewFn?: typeof runCodeReview,
+ *   writeDepositFn?: typeof writeReviewDeposit,
+ *   progress?: (tag: string, msg: string) => void,
+ *   nowIso?: () => string,
+ * }} [deps]
+ * @returns {Promise<{ written: boolean, path?: string, reason?: string,
+ *   deposit?: object }>}
+ */
+export async function computeStoryReviewDeposit(
+  { storyId, cwd, config },
+  deps = {},
+) {
+  const {
+    gitSpawnFn = gitSpawn,
+    runCodeReviewFn = runCodeReview,
+    writeDepositFn = writeReviewDeposit,
+    progress = () => {},
+    nowIso = () => new Date().toISOString(),
+  } = deps;
+  const storyBranch = getStoryBranch(storyId);
+  const baseBranch = config?.project?.baseBranch ?? 'main';
+  const headSha = resolveRefSha({ cwd, ref: storyBranch, gitSpawnFn });
+  if (!headSha) {
+    return { written: false, reason: `could not resolve ${storyBranch}` };
+  }
+  const base = resolveSharedBaseRef({ baseBranch, cwd, gitSpawnFn });
+  const diffDigest = computeReviewDiffDigest({
+    cwd,
+    baseRef: base.resolved ? base.ref : null,
+    headRef: headSha,
+    gitSpawnFn,
+  });
+  if (!diffDigest) {
+    return {
+      written: false,
+      reason: `could not read the ${base.remoteRef ?? baseBranch}...${storyBranch} diff`,
+    };
+  }
+  const computed = await computeStoryScopeReview({
+    cwd,
+    storyId,
+    headRef: headSha,
+    baseBranch,
+    deferPost: true,
+    provider: null,
+    runCodeReviewFn,
+    gitSpawnFn,
+    progress,
+  });
+  if (!computed.result) {
+    return { written: false, reason: 'the review base is unresolvable' };
+  }
+  const deposit = buildReviewDeposit({
+    storyId,
+    headSha,
+    baseRef: base.ref,
+    diffDigest,
+    result: computed.result,
+    createdAt: nowIso(),
+  });
+  const path = writeDepositFn(deposit, { config });
+  return { written: true, path, deposit };
+}
+
+/**
+ * @param {string[]} [argv]
+ * @param {{
+ *   resolveConfigImpl?: typeof resolveConfig,
+ *   stdout?: { write: (s: string) => void },
+ *   cwd?: string,
+ * } & Parameters<typeof computeStoryReviewDeposit>[1]} [deps]
+ * @returns {Promise<object>} the outcome
+ */
+export async function runStoryReviewComputeCli(
+  argv = process.argv.slice(2),
+  deps = {},
+) {
+  const {
+    resolveConfigImpl = resolveConfig,
+    stdout = process.stdout,
+    cwd: defaultCwd = process.cwd(),
+    ...computeDeps
+  } = deps;
+  const { storyId, cwd } = parseArgv(argv);
+  if (!storyId) {
+    throw new Error(
+      'story-review-compute: --story <id> is required (a positive integer).',
+    );
+  }
+  const workCwd = cwd ?? defaultCwd;
+  const config = resolveConfigImpl({ cwd: workCwd });
+  const progress =
+    computeDeps.progress ??
+    ((tag, msg) => stdout.write(`[story-review-compute] [${tag}] ${msg}\n`));
+  const outcome = await computeStoryReviewDeposit(
+    { storyId, cwd: workCwd, config },
+    { ...computeDeps, progress },
+  );
+  if (!outcome.written) {
+    stdout.write(
+      `[story-review-compute] ⏭ No held review written: ${outcome.reason}. Close computes the review itself.\n`,
+    );
+    return outcome;
+  }
+  const { deposit } = outcome;
+  stdout.write(
+    `[story-review-compute] ✅ Held review for Story #${storyId} written → ${outcome.path}\n` +
+      `[story-review-compute] diff ${deposit.diffDigest.slice(0, 12)} @ ${deposit.headSha.slice(0, 12)} · ${formatTally(deposit.severity)}\n`,
+  );
+  if (deposit.halted) {
+    stdout.write(
+      `[story-review-compute] ❌ CRITICAL: fix, commit and re-push before hand-off. Report:\n${deposit.report}\n`,
+    );
+  }
+  return outcome;
+}
+
+async function main() {
+  await runStoryReviewComputeCli();
+  return 0;
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'story-review-compute',
+  propagateExitCode: true,
+  errorPrefix: '[story-review-compute] ❌ Fatal error',
+  usage: USAGE,
+});