mandrel 2.23.0 → 2.25.0

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/lifecycle/listeners/watcher.js

@@ -132,6 +132,29 @@ export function normalizeCheckState(raw) {
  */
 export const extractPrNumber = parsePrNumberFromUrl;
 
+/**
+ * The `gh --repo` flag pair for an optional `owner/repo` target, or an empty
+ * argv fragment when the repository is inferred from the cwd's remote.
+ *
+ * `gh` resolves a *cross-repository* PR reference only through this flag — it
+ * has no `<owner/repo>#<number>` argument form, and a caller that builds one
+ * gets it parsed as a **branch name** instead (every `--repo` invocation of the
+ * watch CLI failed on that, reported as a misleading `gh-checks-failed`). Pure
+ * — one place builds the fragment so no port can forget it.
+ *
+ * Module-private on purpose: the three ports below are the only callers, and
+ * the flag is asserted through them (a real-spawn argv probe), never by
+ * importing this helper — an export existing solely for a test is dead in the
+ * `--production` reachability ratchet.
+ *
+ * @param {string|null|undefined} repo `owner/repo`, or nullish to infer.
+ * @returns {string[]}
+ */
+function ghRepoFlag(repo) {
+  const trimmed = String(repo ?? '').trim();
+  return trimmed.length > 0 ? ['--repo', trimmed] : [];
+}
+
 /**
  * Default `gh pr checks` spawn. Always invokes with `--required` so the
  * returned set is authoritative for branch-protection gating. The
@@ -139,7 +162,7 @@ export const extractPrNumber = parsePrNumberFromUrl;
  *
  * Exported so tests can stub.
  */
-function ghPrChecks({ prUrl, cwd, spawnFn = spawnSync }) {
+function ghPrChecks({ prUrl, cwd, repo, spawnFn = spawnSync }) {
   const result = spawnFn(
     'gh',
     [
@@ -149,6 +172,7 @@ function ghPrChecks({ prUrl, cwd, spawnFn = spawnSync }) {
       '--required',
       '--json',
       'name,state,bucket,workflow',
+      ...ghRepoFlag(repo),
     ],
     { cwd, encoding: 'utf-8', shell: false },
   );
@@ -164,10 +188,10 @@ function ghPrChecks({ prUrl, cwd, spawnFn = spawnSync }) {
  * can detect the BEHIND condition (PR head is behind its base branch)
  * AFTER every required check is green. Exported so tests can stub.
  */
-function ghPrView({ prUrl, cwd, spawnFn = spawnSync }) {
+function ghPrView({ prUrl, cwd, repo, spawnFn = spawnSync }) {
   const result = spawnFn(
     'gh',
-    ['pr', 'view', prUrl, '--json', 'mergeStateStatus'],
+    ['pr', 'view', prUrl, '--json', 'mergeStateStatus', ...ghRepoFlag(repo)],
     { cwd, encoding: 'utf-8', shell: false },
   );
   return {
@@ -202,12 +226,16 @@ function parseMergeStateStatus(stdout) {
  * loop to fast-forward the PR head with its base branch. Exported so
  * tests can stub and assert call counts.
  */
-function ghPrUpdateBranch({ prUrl, cwd, spawnFn = spawnSync }) {
-  const result = spawnFn('gh', ['pr', 'update-branch', prUrl], {
-    cwd,
-    encoding: 'utf-8',
-    shell: false,
-  });
+function ghPrUpdateBranch({ prUrl, cwd, repo, spawnFn = spawnSync }) {
+  const result = spawnFn(
+    'gh',
+    ['pr', 'update-branch', prUrl, ...ghRepoFlag(repo)],
+    {
+      cwd,
+      encoding: 'utf-8',
+      shell: false,
+    },
+  );
   return {
     status: result.status ?? 1,
     stdout: result.stdout ?? '',
@@ -355,6 +383,7 @@ function defaultSleep(ms) {
  * @param {object} opts
  * @param {string} opts.prUrl
  * @param {string} opts.cwd
+ * @param {string|null} [opts.repo] `owner/repo` passed to `gh` as `--repo`.
  * @param {object} opts.outcomes  Initial `{ checkName: outcome }` map.
  * @param {number} opts.polls     Current poll counter (mutated in-place by caller).
  * @param {number} opts.maxPolls  Hard cap on total poll iterations.
@@ -367,6 +396,7 @@ function defaultSleep(ms) {
 export async function pollUntilTerminal({
   prUrl,
   cwd,
+  repo = null,
   outcomes,
   polls,
   maxPolls,
@@ -380,7 +410,7 @@ export async function pollUntilTerminal({
   while (!allTerminal(currentOutcomes) && currentPolls < maxPolls) {
     await sleepFn(pollIntervalMs);
     currentPolls += 1;
-    const probe = ghPrChecksFn({ prUrl, cwd });
+    const probe = ghPrChecksFn({ prUrl, cwd, repo });
     const entries = parseGhPrChecks(probe.stdout);
     if (entries.length === 0 && probe.status !== 0 && probe.status !== 8) {
       // Transient `gh` failure — log and continue. The outer
@@ -411,6 +441,9 @@ export async function pollUntilTerminal({
  * @param {object} opts
  * @param {string} opts.prUrl              PR URL or number (passed to `gh` verbatim).
  * @param {string} opts.cwd
+ * @param {string|null} [opts.repo]        `owner/repo` target, threaded to every
+ *   `gh` port as a real `--repo` flag (Story #4890). Nullish infers the
+ *   repository from the cwd's remote — the behaviour every in-repo caller wants.
  * @param {number} opts.maxPolls           Hard cap on total poll iterations per arm.
  * @param {number} opts.maxUpdates         Cap on `gh pr update-branch` recovery calls.
  * @param {number} [opts.maxResumes]       Story #4358: after the poll cap fires with
@@ -444,17 +477,19 @@ export async function pollUntilTerminal({
  *   terminal: boolean,
  *   green: boolean,
  *   stillRunning: boolean,
+ *   requiredChecksEmpty?: boolean,
  *   error?: string,
  * }>}
  *   `outcomes` is schema-valid (no `'pending'` — leftover pending is
  *   promoted to `'still-running'` when the cap and resume budget are both
  *   exhausted with no failed check). `stillRunning` is true in exactly
- *   that case (slow CI, not red). `error` is set only when the first
- *   probe could not resolve the required-check set.
+ *   that case (slow CI, not red). `requiredChecksEmpty` / `error` are set
+ *   only when the first probe resolved NO required-check names.
  */
 export async function watchPrToTerminal({
   prUrl,
   cwd,
+  repo = null,
   maxPolls,
   maxUpdates,
   maxResumes = 0,
@@ -469,15 +504,25 @@ export async function watchPrToTerminal({
   // First probe: resolve the required-check name set at runtime. Reuse a
   // caller-supplied probe (the listener already issued one to resolve the
   // required check names) so we never double-spend the first `gh` call.
-  const first = firstProbe ?? ghPrChecksFn({ prUrl, cwd });
+  const first = firstProbe ?? ghPrChecksFn({ prUrl, cwd, repo });
   // `gh` exits 8 when checks are still pending; this is expected and
   // does not indicate failure. Any other non-zero status with no
   // parseable JSON body is a genuine failure.
   const firstEntries = parseGhPrChecks(first.stdout);
-  if (firstEntries.length === 0 && first.status !== 0 && first.status !== 8) {
-    logger.warn?.(
-      `[Watcher] gh pr checks failed (status=${first.status}): ${first.stderr}`,
-    );
+  if (firstEntries.length === 0) {
+    // NO required-check name resolved. Never enter the poll loop on that:
+    // `allTerminal({})` is vacuously true, so the loop would exit on its
+    // first evaluation and report a terminal-but-not-green arm — a red
+    // verdict with no failing check in it (Story #4890). The name set is
+    // resolved exactly once per call, so converging on a context that
+    // attaches later means calling this function again; return the
+    // empty-set signal and let the caller's attach window re-resolve it.
+    const ghFaulted = first.status !== 0 && first.status !== 8;
+    if (ghFaulted) {
+      logger.warn?.(
+        `[Watcher] gh pr checks failed (status=${first.status}): ${first.stderr}`,
+      );
+    }
     return {
       outcomes: {},
       requiredChecks: [],
@@ -487,7 +532,12 @@ export async function watchPrToTerminal({
       terminal: false,
       green: false,
       stillRunning: false,
-      error: `gh-checks-failed:status=${first.status}`,
+      requiredChecksEmpty: true,
+      // `gh` overloads a non-zero exit for "no required check is attached
+      // right now" AND for a genuine fault, and its stderr prose is not a
+      // contract — so the status is reported and the *classification* is the
+      // caller's, made against a structural probe of the PR itself.
+      error: `gh-checks-${ghFaulted ? 'failed' : 'empty'}:status=${first.status}`,
     };
   }
 
@@ -512,6 +562,7 @@ export async function watchPrToTerminal({
       ({ outcomes, polls } = await pollUntilTerminal({
         prUrl,
         cwd,
+        repo,
         outcomes,
         polls,
         maxPolls,
@@ -529,7 +580,7 @@ export async function watchPrToTerminal({
       // indefinitely.
       if (!allTerminal(outcomes) || !allGreen(outcomes)) break;
       if (updatesApplied >= maxUpdates) break;
-      const view = ghPrViewFn({ prUrl, cwd });
+      const view = ghPrViewFn({ prUrl, cwd, repo });
       if (view.status !== 0) {
         logger.warn?.(
           `[Watcher] gh pr view failed (status=${view.status}): ${view.stderr}`,
@@ -538,7 +589,7 @@ export async function watchPrToTerminal({
       }
       const mergeStateStatus = parseMergeStateStatus(view.stdout);
       if (mergeStateStatus !== 'BEHIND') break;
-      const update = ghPrUpdateBranchFn({ prUrl, cwd });
+      const update = ghPrUpdateBranchFn({ prUrl, cwd, repo });
       if (update.status !== 0) {
         logger.warn?.(
           `[Watcher] gh pr update-branch failed (status=${update.status}): ${update.stderr}`,

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

@@ -0,0 +1,124 @@
+/**
+ * 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,
+  preserveRefusedWork,
+} 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.
+ *
+ * A refusal also **preserves** the work before it reports (Story #4875): the
+ * implementation is finished and the recycle command hands the receipt to
+ * `/plan`, so leaving it on an untracked local branch that routine cleanup may
+ * reap is not an acceptable end state. Preservation is best-effort and its
+ * outcome is reported either way — a failed push degrades the message, never
+ * the verdict or the exit code.
+ *
+ * @param {{
+ *   storyId: number,
+ *   runFn?: typeof runDiffBackstop,
+ *   handleBlockedFn?: typeof handleBlockedBackstop,
+ *   preserveFn?: typeof preserveRefusedWork,
+ * }} 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,
+ *   preservation: ReturnType<typeof preserveRefusedWork>|null,
+ *   exitCode: number,
+ *   message: string,
+ * }>}
+ */
+export async function resolveBackstopOutcome({
+  storyId,
+  runFn = runDiffBackstop,
+  handleBlockedFn = handleBlockedBackstop,
+  preserveFn = preserveRefusedWork,
+  ...seams
+} = {}) {
+  const result = runFn({ storyId, ...seams });
+  if (!result.blocked) {
+    return {
+      result,
+      nextCommand: null,
+      preservation: null,
+      exitCode: 0,
+      message: `[deliver-light] diff backstop clean for Story #${storyId}.`,
+    };
+  }
+  const preservation = preserveFn({ storyId, cwd: seams.cwd });
+  const nextCommand = await handleBlockedFn({ storyId, result, preservation });
+  return {
+    result,
+    nextCommand,
+    preservation,
+    exitCode: EXIT_BACKSTOP_BLOCKED,
+    message:
+      `[deliver-light] diff backstop BLOCKED Story #${storyId}: ` +
+      `${result.reasons.join('; ')} — ${preservation.detail}; ` +
+      `recycle the receipt with "${nextCommand}"`,
+  };
+}