mandrel 2.23.0 → 2.24.0

package/.agents/scripts/lib/maintainability-engine.js

@@ -1,25 +1,80 @@
 import fs from 'node:fs';
 import escomplex from 'typhonjs-escomplex';
+import { install as installAstCompat } from './escomplex-ast-compat.js';
 import { transpileIfNeeded } from './transpile.js';
 
 /**
  * Calculates the maintainability score of a JavaScript source file or string.
  * Uses `typhonjs-escomplex` internally, which provides a maintainability index
  * based on the Halstead Volume, Cyclomatic Complexity, and Lines of Code.
+ *
+ * The kernel's code generator predates the Babel AST its own parser emits, so
+ * ordinary modern syntax (`?.`, `await` in a loop head, a regex in a loop
+ * head, object spread in a default parameter) aborts the whole analysis.
+ * `escomplex-ast-compat` repairs that before any scoring runs — see that
+ * module for the defect and the upstream status.
+ */
+installAstCompat();
+
+/**
+ * Sentinel score for a file the kernel cannot analyse.
+ *
+ * A real maintainability index never reaches 0 for runnable code — the
+ * escomplex floor is ~10–20 — so 0 has long been used as an out-of-band
+ * "unscorable" marker. That overload is the bug: consumers drop `mi === 0`
+ * rows, so an unscorable file silently vanishes from the baseline instead of
+ * being reported, and no amount of re-seeding can ever give it a row.
+ *
+ * Deliberately module-private. The numeric return is kept for backwards
+ * compatibility, but the *value* is not something a caller should branch on —
+ * that is the overload this change exists to stop propagating. Callers that
+ * need to tell "unscorable" from "genuinely terrible" read the `unscorable`
+ * flag from {@link scoreSource} / {@link scoreFile}.
+ */
+const UNSCORABLE = 0;
+
+/**
+ * Score a raw string, distinguishing "the kernel could not analyse this" from
+ * "this scored badly".
+ *
+ * @param {string} sourceCode The JavaScript source code.
+ * @returns {{ score: number, unscorable: boolean, reason: string|null }}
+ *   `score` is {@link UNSCORABLE} when `unscorable` is true; `reason` carries
+ *   the kernel's own error message so a consumer can report *why* rather than
+ *   just omitting the file.
+ */
+export function scoreSource(sourceCode) {
+  try {
+    const score = escomplex.analyzeModule(sourceCode)?.maintainability;
+    return Number.isFinite(score)
+      ? { score, unscorable: false, reason: null }
+      : unscorable(`kernel returned a non-finite index (${String(score)})`);
+  } catch (err) {
+    return unscorable(
+      `${err?.constructor?.name ?? 'Error'}: ${err?.message ?? 'unknown kernel failure'}`,
+    );
+  }
+}
+
+/**
+ * @param {string} reason
+ * @returns {{ score: number, unscorable: boolean, reason: string }}
  */
+function unscorable(reason) {
+  return { score: UNSCORABLE, unscorable: true, reason };
+}
+
 /**
  * Calculate score for a raw string of source code.
+ *
+ * Returns 0 for unscorable input, which is ambiguous by construction — see
+ * {@link UNSCORABLE}. Prefer {@link scoreSource} in new code.
+ *
  * @param {string} sourceCode The JavaScript source code.
  * @returns {number} Score between 0 and 171. Higher is better.
  */
 export function calculateForSource(sourceCode) {
-  try {
-    const result = escomplex.analyzeModule(sourceCode);
-    return result.maintainability;
-  } catch (_err) {
-    // Return 0 if the parser fails (e.g. invalid syntax)
-    return 0;
-  }
+  return scoreSource(sourceCode).score;
 }
 
 /**
@@ -34,17 +89,34 @@ export function calculateForSource(sourceCode) {
  *   be parsed (escomplex parse error or TS transpile failure).
  */
 export function calculateForFile(filePath) {
+  return scoreFile(filePath).score;
+}
+
+/**
+ * Score a file, distinguishing "unscorable" from "scored badly".
+ *
+ * The transpile-failure and kernel-failure cases are reported separately
+ * because they need different fixes: a transpile failure is usually the
+ * consumer's own syntax or `tsconfig`, whereas a kernel failure is the
+ * upstream generator gap described in `escomplex-ast-compat.js`.
+ *
+ * @param {string} filePath Path to the JS/TS source file.
+ * @returns {{ score: number, unscorable: boolean, reason: string|null }}
+ */
+export function scoreFile(filePath) {
+  let sourceCode;
   try {
-    const sourceCode = fs.readFileSync(filePath, 'utf-8');
-    const prepared = transpileIfNeeded(filePath, sourceCode);
-    if (prepared === null) return 0;
-    return calculateForSource(prepared);
+    sourceCode = fs.readFileSync(filePath, 'utf-8');
   } catch (err) {
     if (err.code === 'ENOENT') {
       throw new Error(`File not found: ${filePath}`);
     }
     throw err;
   }
+
+  const prepared = transpileIfNeeded(filePath, sourceCode);
+  if (prepared === null) return unscorable('TypeScript transpile failed');
+  return scoreSource(prepared);
 }
 
 /**

package/.agents/scripts/lib/maintainability-unscorable.js

@@ -0,0 +1,60 @@
+/**
+ * maintainability-unscorable.js — reporting for files the MI kernel cannot
+ * analyse.
+ *
+ * A file the kernel throws on has no maintainability index, so it gets no
+ * baseline row — a phantom `mi: 0` would poison the `min`/p50 rollup and let
+ * real regressions hide behind it. Dropping the row is therefore correct; doing
+ * it *silently* is not. Without a report, an unscorable file is
+ * indistinguishable from a file nobody added yet: the scorer emits nothing, the
+ * scope gate sees an absence it cannot explain, and re-seeding the baseline can
+ * never produce the missing row no matter how many times it runs.
+ *
+ * Kept separate from `maintainability-utils.js` so the scoring path stays about
+ * scoring and this stays about explaining.
+ */
+
+import { Logger } from './Logger.js';
+
+/**
+ * Report every unscorable file, then summarise.
+ *
+ * @param {Array<{ relPath: string, unscorable?: boolean, reason?: string|null }>} perFile
+ * @returns {number} how many files were unscorable, for the caller's own use.
+ */
+export function reportUnscorable(perFile) {
+  const unscorable = (perFile ?? []).filter((entry) => entry?.unscorable);
+  if (unscorable.length === 0) return 0;
+
+  for (const { relPath, reason } of unscorable) {
+    Logger.error(
+      `[Maintainability] UNSCORABLE ${relPath}: ${reason ?? 'unknown kernel failure'}`,
+    );
+  }
+  Logger.error(
+    `[Maintainability] ${unscorable.length} file(s) could not be scored and will have ` +
+      'no baseline row, so the maintainability gate cannot see them. If the cause is a ' +
+      'kernel AST gap, add a handler in lib/escomplex-ast-compat.js rather than an ' +
+      'allowlist entry.',
+  );
+  return unscorable.length;
+}
+
+/**
+ * Whether a per-file entry carries a real maintainability index and so belongs
+ * in the baseline.
+ *
+ * An unscorable entry carries the sentinel score, not an index — letting it
+ * through would write an `mi: 0` phantom and drag the rollup floor down with it
+ * (Story #2467). `score === null` is the separate I/O-failure case.
+ *
+ * Tests for a *number* rather than `score !== null`, because the latter passes
+ * anything absent: `undefined !== null` is true, so a missing entry or one with
+ * no `score` key at all would have been treated as scored.
+ *
+ * @param {{ score?: number|null, unscorable?: boolean }} entry
+ * @returns {boolean}
+ */
+export function isScored(entry) {
+  return typeof entry?.score === 'number' && !entry.unscorable;
+}

package/.agents/scripts/lib/maintainability-utils.js

@@ -4,7 +4,8 @@ import { minimatch } from 'minimatch';
 import { canonicalise as canonicalisePath } from './baselines/path-canon.js';
 import { POOL_SERIAL_THRESHOLD, runOnPool } from './cpu-pool.js';
 import { Logger } from './Logger.js';
-import { calculateForFile } from './maintainability-engine.js';
+import { scoreFile } from './maintainability-engine.js';
+import { isScored, reportUnscorable } from './maintainability-unscorable.js';
 
 const MAINTAINABILITY_WORKER_URL = new URL(
   './workers/maintainability-worker.js',
@@ -128,6 +129,13 @@ export function scanDirectory(dir, fileList = [], opts = {}) {
  * worker-side per-item failures surface as a `null` score that is
  * filtered out before assembly.
  *
+ * A file the kernel cannot analyse is also dropped — a phantom `mi: 0` row
+ * poisons the rollup — but it is **reported** on the way out, with the
+ * kernel's own error text, and the count is summarised at the end of the run.
+ * Silently omitting these is what let a file sit unmeasured indefinitely: the
+ * scorer emitted no row, so no amount of re-seeding could ever produce one,
+ * and nothing said so.
+ *
  * @param {string[]} paths
  * @returns {Promise<Record<string, number>>}
  */
@@ -142,7 +150,7 @@ export async function calculateAll(paths) {
   if (indexed.length < SERIAL_THRESHOLD) {
     perFile = indexed.map(({ abs, relPath }) => {
       try {
-        return { relPath, score: calculateForFile(abs) };
+        return { relPath, ...scoreFile(abs) };
       } catch (err) {
         Logger.error(
           `[Maintainability] Failed to process ${abs}: ${err.message}`,
@@ -166,7 +174,7 @@ export async function calculateAll(paths) {
       if (r.score === null && r.error) {
         Logger.error(`[Maintainability] Failed to process ${abs}: ${r.error}`);
       }
-      return { relPath, score: r.score };
+      return { relPath, ...r };
     });
   }
 
@@ -174,9 +182,10 @@ export async function calculateAll(paths) {
     a.relPath < b.relPath ? -1 : a.relPath > b.relPath ? 1 : 0,
   );
 
+  reportUnscorable(perFile);
+
   const scores = {};
-  for (const { relPath, score } of perFile) {
-    if (score === null) continue;
+  for (const { relPath, score } of perFile.filter(isScored)) {
     scores[relPath] = score;
   }
   return scores;

package/.agents/scripts/lib/observability/runtime-friction.js

@@ -75,6 +75,14 @@ export const RUNTIME_FRICTION_CATEGORIES = Object.freeze({
    * reflect code findings only.
    */
   TOOL_DEGRADED: 'tool-degraded',
+  /**
+   * The light delivery path refused a scope — a suitability-gate `ask-operator`
+   * or a blocked diff backstop. Story #4856 added it because neither rejection
+   * emitted anything, so an over-tight ceiling could only reach the framework
+   * as anecdote; the roll-up aggregating these by category is what makes the
+   * ceilings recalibratable from recorded evidence.
+   */
+  LIGHT_SCOPE_REJECTED: 'light-scope-rejected',
 });
 
 /** Cap on free-form reason text copied into a signal's `details`. */

package/.agents/scripts/lib/orchestration/diff-magnitude.js

@@ -0,0 +1,283 @@
+/**
+ * lib/orchestration/diff-magnitude.js — the changed-line magnitude of a diff,
+ * split into implementation and mandated-companion halves (Story #4856).
+ *
+ * ## Why magnitude, and why the split
+ *
+ * The light path's diff backstop used to bound scope with a single
+ * `maxFiles: 4` ceiling. Measured against this repository's own history that
+ * ceiling was wrong in both directions:
+ *
+ *   - **Too tight.** Of 33 real-work squash merges on `main` (excluding
+ *     release-please and `chore(baselines)` automation) only 7 — 21% — touch
+ *     four files or fewer; the median is 8. The framework's *own* narrow-diff
+ *     scale, `DEFAULT_DIFF_WIDTH.softFiles` in `review-depth.js`, is 15.
+ *   - **Blind.** A three-file, 323-line rewrite passed while a 190-file change
+ *     was rejected 47× over — even though 186 of those files were tests and its
+ *     implementation was 7 files.
+ *
+ * So the axis is **changed lines over implementation files**, and the companion
+ * classes the framework itself mandates are exempt from the count: obeying
+ * `rules/testing-standards.md` (test-first), the `delivery.docsFreshness` gate,
+ * and the baseline ratchets must not inflate the number that then rejects the
+ * change. Re-counting those same 33 merges on implementation files alone moves
+ * the four-file pass rate from 21% to 58%.
+ *
+ * ## Three contracts worth not rediscovering
+ *
+ *   1. **Additions plus deletions, never net.** A modified line counts twice
+ *      (one `+`, one `-`), which is the intended weighting. Net is actively
+ *      broken as a size signal: the merge retiring the planner snapshot is
+ *      1119 add+del but **−803** net, so a large deletion would measure as
+ *      trivial.
+ *   2. **A pure rename is free.** `git diff --numstat` reports `0\t0` for one,
+ *      and its path arrives in `old => new` form — normalized here to the
+ *      destination so the file still counts toward the implementation tally.
+ *   3. **Exemption is from *counting*, never from *risk*.** Nothing here
+ *      touches sensitive-path derivation, which every caller runs over the
+ *      full changed set including companions.
+ *
+ * Companion matching runs through the audit suite's picomatch seam as a
+ * **positive** glob list negated by the caller. A `!`-prefixed picomatch
+ * pattern widens a match rather than narrowing it, so expressing the
+ * behavior-bearing exceptions as negations would silently exempt more than
+ * intended.
+ *
+ * Every export is total: no throws. {@link readNumstatRows} owns the one git
+ * read; everything else is pure.
+ *
+ * The public surface is deliberately just those two functions. The numstat
+ * parse, the rename normalization, and the companion classifier are internal:
+ * each is fully observable through them (a stubbed `gitSpawnFn` drives the
+ * parse, an `isCompanionFn` seam drives the classification), so exporting them
+ * would widen the module's contract for no caller.
+ *
+ * @module lib/orchestration/diff-magnitude
+ */
+
+import { matchesAnyFilePattern } from '../audit-suite/selector.js';
+import { gitSpawn } from '../git-utils.js';
+
+/**
+ * Paths whose churn is a **mandated companion** of a change rather than the
+ * change itself, exempt from the implementation line and file counts.
+ *
+ * Deliberately absent, and load-bearing in their absence: `.agentrc.json`,
+ * `.agents/schemas/**`, `.github/workflows/**`, and `package.json`. Those are
+ * "config" by file type but behavior by effect, and `.agents/schemas/audit-rules.json`
+ * is the sensitive-path SSOT — exempting it would let a change widen the very
+ * allowlist that decides whether it is risky.
+ *
+ * Note the anchoring: `baselines/**` is the generated baseline **data** at the
+ * repository root. The baseline *schemas* under `.agents/schemas/baselines/`
+ * are unanchored by this pattern and therefore still count as implementation.
+ *
+ * Markdown is exempt wholesale, which includes `.agents/workflows/**` and
+ * `.agents/rules/**`. That is intended: rewriting a workflow contract is not
+ * *effort* the way a module rewrite is, and its real guards are the close-time
+ * context-budget, doc-link, and docs-reference-sync gates — none of which this
+ * ceiling replaces.
+ */
+const COMPANION_PATH_GLOBS = Object.freeze([
+  // Tests — mandated by rules/testing-standards.md's test-first discipline.
+  '**/__tests__/**',
+  '**/*.test.js',
+  '**/*.test.mjs',
+  '**/*.test.cjs',
+  '**/*.test.ts',
+  '**/*.test.tsx',
+  'tests/**',
+  'features/**',
+  // Documentation — mandated by the delivery.docsFreshness gate.
+  'docs/**',
+  '**/*.md',
+  // Generated baseline data — written by the ratchets, not hand-authored.
+  'baselines/**',
+  // Lockfiles — regenerated wholesale; their line count means nothing.
+  'package-lock.json',
+  'pnpm-lock.yaml',
+  'yarn.lock',
+]);
+
+/**
+ * Normalize a `git diff --numstat` path field to the single file it names.
+ * Rename rows arrive as `old => new` or with a braced infix
+ * (`dir/{old => new}/file.js`); both resolve to the destination, so a renamed
+ * implementation file still counts as one implementation file.
+ *
+ * Pure and total.
+ *
+ * @param {string} raw
+ * @returns {string}
+ */
+function normalizeNumstatPath(raw) {
+  const value = typeof raw === 'string' ? raw.trim() : '';
+  if (value === '') return '';
+  const braced = /^(.*)\{(.*) => (.*)\}(.*)$/.exec(value);
+  if (braced) {
+    const [, prefix, , to, suffix] = braced;
+    return `${prefix}${to}${suffix}`.replace(/\/{2,}/g, '/');
+  }
+  const arrow = value.split(' => ');
+  return (arrow.length > 1 ? arrow[arrow.length - 1] : value).trim();
+}
+
+/**
+ * Parse `git diff --numstat` output into per-file rows.
+ *
+ * Binary rows (`-\t-\tpath`) contribute zero text lines without poisoning the
+ * parse. Any line that does not match the numstat shape makes the whole result
+ * untrustworthy, so the function returns `null` — the "magnitude unknown"
+ * signal every caller fails closed (or fails open) on deliberately.
+ *
+ * Pure and total.
+ *
+ * @param {unknown} stdout
+ * @returns {Array<{ additions: number, deletions: number, path: string }>|null}
+ */
+function parseNumstatRows(stdout) {
+  if (typeof stdout !== 'string') return null;
+  const rows = [];
+  for (const line of stdout.split('\n')) {
+    const trimmedEnd = line.replace(/\s+$/, '');
+    if (trimmedEnd.length === 0) continue;
+    const match = /^(\d+|-)\t(\d+|-)\t(.+)$/.exec(trimmedEnd);
+    if (!match) return null;
+    rows.push({
+      additions: match[1] === '-' ? 0 : Number(match[1]),
+      deletions: match[2] === '-' ? 0 : Number(match[2]),
+      path: normalizeNumstatPath(match[3]),
+    });
+  }
+  return rows;
+}
+
+/**
+ * True when `file` is a mandated companion rather than implementation.
+ *
+ * Pure and total — a throwing matcher resolves to `false`, which counts the
+ * file as implementation. That is the conservative direction: a
+ * classification failure must never shrink the measured magnitude.
+ *
+ * @param {unknown} file
+ * @param {{ matchFn?: typeof matchesAnyFilePattern }} [deps]
+ * @returns {boolean}
+ */
+function isCompanionPath(file, { matchFn = matchesAnyFilePattern } = {}) {
+  if (typeof file !== 'string' || file.trim() === '') return false;
+  try {
+    return matchFn(COMPANION_PATH_GLOBS, [file.trim()]) === true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Read the per-file numstat rows for the `baseRef...headRef` diff. The one
+ * side-effecting function in this module.
+ *
+ * Total — never throws; returns `null` on any git failure or unparseable
+ * output.
+ *
+ * @param {{
+ *   baseRef?: string,
+ *   headRef?: string,
+ *   cwd?: string,
+ *   gitSpawnFn?: typeof gitSpawn,
+ * }} [args]
+ * @returns {Array<{ additions: number, deletions: number, path: string }>|null}
+ */
+export function readNumstatRows({
+  baseRef,
+  headRef,
+  cwd = process.cwd(),
+  gitSpawnFn = gitSpawn,
+} = {}) {
+  if (typeof baseRef !== 'string' || baseRef.length === 0) return null;
+  if (typeof headRef !== 'string' || headRef.length === 0) return null;
+  try {
+    const result = gitSpawnFn(
+      cwd,
+      'diff',
+      '--numstat',
+      `${baseRef}...${headRef}`,
+    );
+    if (!result || result.status !== 0) return null;
+    return parseNumstatRows(result.stdout);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Summarize a diff's magnitude, splitting implementation from mandated
+ * companions.
+ *
+ * `implFiles` is counted from `changedFiles` — the canonical
+ * `git diff --name-only` enumeration produced by `change-set.js` — rather than
+ * from the numstat rows, so file counting uses clean paths from the one
+ * enumerator every other consumer reads. `implLines` comes from the numstat
+ * rows, which is the only surface carrying line counts.
+ *
+ * Returns `null` when either input is unusable: the magnitude is then *unknown*,
+ * which is deliberately distinct from *zero* so a caller can fail closed on the
+ * absence of evidence.
+ *
+ * Pure and total.
+ *
+ * @param {{
+ *   changedFiles?: unknown,
+ *   rows?: unknown,
+ *   isCompanionFn?: typeof isCompanionPath,
+ * }} [args]
+ * @returns {{
+ *   implFiles: number,
+ *   implLines: number,
+ *   companionFiles: number,
+ *   companionLines: number,
+ *   totalFiles: number,
+ * }|null}
+ */
+export function summarizeDiffMagnitude({
+  changedFiles,
+  rows,
+  isCompanionFn = isCompanionPath,
+} = {}) {
+  if (!Array.isArray(changedFiles) || !Array.isArray(rows)) return null;
+  const files = changedFiles.filter(
+    (f) => typeof f === 'string' && f.trim() !== '',
+  );
+
+  // A classification failure resolves to "implementation" — the conservative
+  // direction, since counting a companion as implementation can only ever make
+  // the measured magnitude larger. Guarded here as well as inside the default
+  // classifier so an injected one cannot break this function's totality.
+  const isCompanion = (file) => {
+    try {
+      return isCompanionFn(file) === true;
+    } catch {
+      return false;
+    }
+  };
+
+  let implFiles = 0;
+  for (const file of files) {
+    if (!isCompanion(file)) implFiles += 1;
+  }
+
+  let implLines = 0;
+  let companionLines = 0;
+  for (const row of rows) {
+    const lines = (row?.additions ?? 0) + (row?.deletions ?? 0);
+    if (isCompanion(row?.path)) companionLines += lines;
+    else implLines += lines;
+  }
+
+  return {
+    implFiles,
+    implLines,
+    companionFiles: files.length - implFiles,
+    companionLines,
+    totalFiles: files.length,
+  };
+}

package/.agents/scripts/lib/orchestration/light-backstop.js

@@ -0,0 +1,107 @@
+/**
+ * lib/orchestration/light-backstop.js — the light path's diff-backstop pass
+ * (Story #4856).
+ *
+ * The backstop is invariant 3 of the light path: after implementation the
+ * **actual** change set is re-checked, because the diff — not the prompt — is
+ * the real scope signal. This module owns that pass end to end so
+ * `deliver-light.js` stays the thin CLI shell it claims to be: it reads the two
+ * git surfaces, applies
+ * {@link module:lib/orchestration/light-suitability.checkLightDiffBackstop},
+ * and resolves what a refusal means.
+ *
+ * ## Two git surfaces, each used for what it reports reliably
+ *
+ *   - `--name-only`, via the one canonical `computeChangeSet` enumerator, gives
+ *     the clean full file list. Sensitive-path derivation and
+ *     implementation-file counting both read it, so the backstop and every
+ *     other consumer are looking at the same change set.
+ *   - `--numstat` gives per-file line counts, the only surface carrying them.
+ *
+ * @module lib/orchestration/light-backstop
+ */
+
+import { computeChangeSet } from './change-set.js';
+import { readNumstatRows, summarizeDiffMagnitude } from './diff-magnitude.js';
+import { handleBlockedBackstop } from './light-escalation.js';
+import { checkLightDiffBackstop } from './light-suitability.js';
+
+/** Exit code when the diff backstop blocked the land. */
+const EXIT_BACKSTOP_BLOCKED = 3;
+
+/**
+ * Run the diff backstop against a Story branch's actual change set.
+ *
+ * @param {{
+ *   storyId: number,
+ *   baseRef?: string,
+ *   cwd?: string,
+ *   computeFn?: typeof computeChangeSet,
+ *   readRowsFn?: typeof readNumstatRows,
+ *   injectedRules?: object,
+ * }} args
+ * @returns {ReturnType<typeof checkLightDiffBackstop>}
+ */
+function runDiffBackstop({
+  storyId,
+  baseRef = 'main',
+  cwd = process.cwd(),
+  computeFn = computeChangeSet,
+  readRowsFn = readNumstatRows,
+  injectedRules,
+} = {}) {
+  const headRef = `story-${storyId}`;
+  const { files } = computeFn({ baseRef, headRef, cwd });
+  const rows = readRowsFn({ baseRef, headRef, cwd });
+  const magnitude = summarizeDiffMagnitude({ changedFiles: files, rows });
+  return checkLightDiffBackstop({
+    changedFiles: files,
+    magnitude,
+    injectedRules,
+  });
+}
+
+/**
+ * Resolve the backstop pass into everything the CLI needs to print and exit
+ * with: the verdict, the recycle command on a refusal (`null` when clean), the
+ * exit code, and the log line.
+ *
+ * @param {{
+ *   storyId: number,
+ *   runFn?: typeof runDiffBackstop,
+ *   handleBlockedFn?: typeof handleBlockedBackstop,
+ * }} args Any further keys (`baseRef`, `cwd`, `computeFn`, `readRowsFn`,
+ *   `injectedRules`) forward to the backstop run, so the git-surface join is
+ *   drivable through this one entry point.
+ * @returns {Promise<{
+ *   result: ReturnType<typeof checkLightDiffBackstop>,
+ *   nextCommand: string|null,
+ *   exitCode: number,
+ *   message: string,
+ * }>}
+ */
+export async function resolveBackstopOutcome({
+  storyId,
+  runFn = runDiffBackstop,
+  handleBlockedFn = handleBlockedBackstop,
+  ...seams
+} = {}) {
+  const result = runFn({ storyId, ...seams });
+  if (!result.blocked) {
+    return {
+      result,
+      nextCommand: null,
+      exitCode: 0,
+      message: `[deliver-light] diff backstop clean for Story #${storyId}.`,
+    };
+  }
+  const nextCommand = await handleBlockedFn({ storyId, result });
+  return {
+    result,
+    nextCommand,
+    exitCode: EXIT_BACKSTOP_BLOCKED,
+    message:
+      `[deliver-light] diff backstop BLOCKED Story #${storyId}: ` +
+      `${result.reasons.join('; ')} — recycle the receipt with "${nextCommand}"`,
+  };
+}