mandrel 2.56.0 → 2.58.0

package/.agents/scripts/lib/orchestration/planning/memory-pool-advisory.js

@@ -13,70 +13,42 @@
  *      verdict nothing read. This emits one advisory the `/mandrel-plan` spine
  *      surfaces at Gate #1, recommending `/memory-consolidate`.
  *
- * It also drops the semantic that made the old scanner unfixable: it renders
- * **no per-entry verdict at all**. A memory citing a closed issue is a
- * delivery retrospective whose subject is that issue — not a stale entry — and
- * only the attended `/memory-consolidate` pass, reading content, can tell the
- * difference. This module counts and stats; it never judges an entry.
+ * It renders **no per-entry verdict at all**. A memory citing a closed issue
+ * is a delivery retrospective whose subject is that issue — not a stale entry
+ * — and only the attended `/memory-consolidate` pass, reading content, can
+ * tell the difference. This module measures one thing; it never judges an
+ * entry.
  *
- * **Growth, never size (Story #5182).** The second arm used to be an absolute
- * ceiling of a hundred entries. A consolidation pass prefers `correct` over
- * `dead` by design, so a pool that crosses a fixed ceiling stays over it
- * forever: the nudge then fired on every plan however fresh the stamp, and a
- * permanent recommendation is one the operator learns to ignore. The arm now
- * measures **entries written since the last pass** — the one quantity a pass
- * actually resets, because Step 6 records the post-rewrite entry count in the
- * stamp as the next run's growth baseline.
- *
- * A stamp carrying a date but no usable `entryCount` (every stamp written
- * before that Story) leaves growth **unmeasured**. That is not
- * "never consolidated" — an operator did review the pool — so the growth arm
- * simply stays silent and only the age arm can speak, until the next pass
- * writes a baseline.
- *
- * **The index byte arm (Story #5285).** Age and growth both measure the
- * *pool*; neither measures the one artifact a session actually loads. The
- * harness reads `MEMORY.md` into every session under a hard byte cap and
- * **truncates** past it, so an index over that cap loses its tail entries
- * silently — the pointers are on disk, indexed, and unreachable. That is a
- * loss in progress, not a hygiene forecast, so this arm is independent of the
- * other two: it fires on a fresh, zero-growth pool whose index has simply
- * outgrown the cap. It measures the index file's size, never the pool's, and
- * a pass that rewrites long index lines short clears it without pruning a
- * single entry.
- *
- * **A future-dated stamp is no stamp.** `lastConsolidatedAt` ahead of `now`
- * cannot describe a pass that happened — it is a clock skew, a hand-edit, or
- * a timezone bug. Scored as-is it yields a negative age that silences the age
- * arm *forever*, which is the loudest possible failure for an advisory whose
- * only job is to speak up. It reads as unstamped instead, so the
- * never-consolidated reason fires and the next real pass overwrites it.
+ * **One arm: the index byte ceiling (Story #5285, sole survivor after Story
+ * #5312).** The harness reads `MEMORY.md` into every session under a hard
+ * byte cap and **truncates** past it, so an index over that cap loses its
+ * tail entries silently — the pointers are on disk, indexed, and unreachable.
+ * That is a loss in progress, not a hygiene forecast, and it is the only
+ * signal that measures the artifact a session actually loads. The stamp-age
+ * and growth-delta arms that used to sit beside it measured the *pool*, fired
+ * on every plan once a pool was mature, and were learned-ignored by exactly
+ * the operators they nagged; Story #5312 deleted them with their
+ * `planning.memoryPool.{staleAfterDays, growthDelta}` knobs. A pass that
+ * rewrites long index lines short clears this arm without pruning a single
+ * entry.
  *
  * Detection is filesystem-only — no child processes, no `gh` probes, no
  * network. Every failure path fails soft to "no pool, no recommendation": the
  * advisory can degrade the nudge, never a plan.
  *
  * Test seams: `cwd`, `env`, `fsImpl` (node:fs-compatible `statSync` /
- * `readdirSync` / `readFileSync`), `now`, and the three thresholds
- * (`staleAfterDays`, `growthDelta`, `indexByteCeiling`).
+ * `readdirSync`), and the `indexByteCeiling` threshold.
  *
  * `buildMemoryPoolAdvisory` is the **only** export: the helpers below have no
  * caller outside this module, and exporting one solely for a test would add a
- * row to the `dead-exports-production` ratchet (the `buildUiSurfaceSignal`
- * precedent). Tests reach every branch through the seams above — do not
- * "fix" the missing exports.
+ * row to the `dead-exports-production` ratchet. Tests reach every branch
+ * through the seams above — do not "fix" the missing exports.
  */
 
 import * as defaultFs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 
-/** Recommend a consolidation pass once the stamp is this old. */
-const STALE_AFTER_DAYS = 30;
-
-/** Recommend a pass once this many entries were written since the last one. */
-const GROWTH_DELTA = 25;
-
 /**
  * Recommend a pass once `MEMORY.md` exceeds this many bytes.
  *
@@ -87,14 +59,9 @@ const GROWTH_DELTA = 25;
  */
 const INDEX_BYTE_CEILING = 24_576;
 
-/** Stamp file written by `/memory-consolidate` after its operator gate. */
-const STAMP_FILENAME = '.consolidation-stamp.json';
-
 /** The index file is not itself a memory entry. */
 const INDEX_FILENAME = 'MEMORY.md';
 
-const MS_PER_DAY = 86_400_000;
-
 /**
  * Slugify an absolute path the way the harness names its per-project
  * directories: every `/` and `.` becomes `-`. Verified against real
@@ -141,10 +108,8 @@ function resolveMemoryPoolDir({ cwd, env = process.env, homedir } = {}) {
  * Run one filesystem probe, falling back on any failure.
  *
  * Every read here is fail-soft by design — the advisory may degrade its nudge
- * but never a plan — so all four probes had the same try/catch shape wrapped
- * around one expression. One helper states the rule once; a new probe cannot
- * forget it, and a `catch` that ever needs to do more than fall back would
- * have to be written out, which is the signal it deserves.
+ * but never a plan — so every probe has the same try/catch shape wrapped
+ * around one expression. One helper states the rule once.
  *
  * @template T
  * @param {() => T} read
@@ -159,61 +124,14 @@ function probe(read, fallback = null) {
   }
 }
 
-/**
- * The growth baseline a stamp records: its entry count, or `null` when it
- * records none. `null` is *unmeasured*, never zero — a zero baseline would
- * score every entry in the pool as newly written.
- *
- * @param {unknown} count
- * @returns {number|null}
- */
-function readBaseline(count) {
-  return Number.isInteger(count) && count >= 0 ? count : null;
-}
-
-/**
- * Read the consolidation stamp.
- *
- * `at` is the ISO timestamp of the last pass, or `null` when there was none:
- * a missing, unreadable, unparseable, date-less or **future-dated** stamp is
- * indistinguishable from "never consolidated" — all five mean the same thing
- * to the advisory. A future date is the one that has to be caught here rather
- * than downstream: it is arithmetically valid, so the age arm would score it
- * as a negative age and stay silent for as long as the clock stays behind it.
- * A stamp whose date is unusable carries no baseline either, so `baseline`
- * follows it to `null` rather than describing a pass that cannot be dated.
- *
- * `baseline` is the entry count that pass left behind — the growth arm's
- * reference point. It is `null` on a stamp that predates Story #5182 (date
- * only) and on a malformed count, which reads as *unmeasured growth*, never
- * as zero growth: a `0` baseline would score the whole pool as new.
- *
- * @param {{ poolDir: string, fsImpl: object, now: Date|string|number }} args
- * @returns {{ at: string|null, baseline: number|null }}
- */
-function readStamp({ poolDir, fsImpl, now }) {
-  const parsed = probe(() =>
-    JSON.parse(fsImpl.readFileSync(path.join(poolDir, STAMP_FILENAME), 'utf8')),
-  );
-  const at = parsed?.lastConsolidatedAt;
-  // `Date.parse` rejects the empty string as NaN, so one test covers both an
-  // absent date and an unusable one; `> now` covers the future-dated stamp.
-  // Equality is not the future, so a stamp written this instant still counts.
-  const at_ms = typeof at === 'string' ? Date.parse(at) : Number.NaN;
-  if (Number.isNaN(at_ms) || at_ms > new Date(now).getTime()) {
-    return { at: null, baseline: null };
-  }
-  return { at, baseline: readBaseline(parsed.entryCount) };
-}
-
 /**
  * The index file's size in bytes.
  *
  * `null` when it cannot be stat'd — an absent or unreadable `MEMORY.md`
- * leaves the byte arm silent rather than guessing a size, on the same
- * fail-soft rule every other probe here follows. Stat'd rather than read:
- * the arm needs the length, never the content, and this module deliberately
- * never reads a memory's text.
+ * leaves the arm silent rather than guessing a size, on the same fail-soft
+ * rule every other probe here follows. Stat'd rather than read: the arm needs
+ * the length, never the content, and this module deliberately never reads a
+ * memory's text.
  *
  * @returns {number|null}
  */
@@ -247,122 +165,40 @@ function countEntries({ poolDir, fsImpl }) {
  *
  * @param {object} fields
  * @returns {{ present: boolean, entryCount: number, indexBytes: number|null,
- *            lastConsolidatedAt: string|null,
- *            entriesSinceConsolidation: number|null, recommend: boolean,
- *            reasons: string[] }}
+ *            recommend: boolean, reasons: string[] }}
  */
 function envelope(fields) {
   return {
     present: false,
     entryCount: 0,
     indexBytes: null,
-    lastConsolidatedAt: null,
-    entriesSinceConsolidation: null,
     recommend: false,
     reasons: [],
     ...fields,
   };
 }
 
-/**
- * Collect the reasons a pool wants a consolidation pass. An empty array is
- * the quiet verdict; the caller turns it into `recommend` and supplies the
- * standing-down sentence, so every arm lives in one place.
- *
- * The three arms are independent and every one that fires is reported.
- *
- * @param {{ stamp: { at: string|null, baseline: number|null },
- *           growth: number|null, indexBytes: number|null,
- *           now: Date|string|number, staleAfterDays: number,
- *           growthDelta: number, indexByteCeiling: number }} args
- * @returns {string[]}
- */
-function collectReasons({
-  stamp,
-  growth,
-  indexBytes,
-  now,
-  staleAfterDays,
-  growthDelta,
-  indexByteCeiling,
-}) {
-  const reasons = [];
-
-  if (stamp.at === null) {
-    reasons.push(
-      'no consolidation stamp — this pool has never been consolidated',
-    );
-  } else {
-    const ageDays =
-      (new Date(now).getTime() - Date.parse(stamp.at)) / MS_PER_DAY;
-    if (ageDays > staleAfterDays) {
-      reasons.push(
-        `last consolidated ${Math.floor(ageDays)} days ago (over the ${staleAfterDays}-day threshold)`,
-      );
-    }
-  }
-
-  // `growth === null` is unmeasured, not zero — a pre-#5182 stamp carries no
-  // baseline, and guessing one would re-invent the ceiling this arm replaced.
-  if (growth !== null && growth >= growthDelta) {
-    reasons.push(
-      `${growth} entries written since the last consolidation (at or over the ${growthDelta}-entry growth delta)`,
-    );
-  }
-
-  // `indexBytes === null` is an unreadable index, not a small one.
-  if (indexBytes !== null && indexBytes > indexByteCeiling) {
-    reasons.push(
-      `${INDEX_FILENAME} is ${indexBytes} bytes, ${indexBytes - indexByteCeiling} over the ${indexByteCeiling}-byte index ceiling — the index is truncated at the cap, so every entry listed after the cut is invisible to every session`,
-    );
-  }
-
-  return reasons;
-}
-
-/**
- * The sentence a quiet pool explains itself with — one per reason it is quiet,
- * so "nothing to do" never reads the same as "nothing measurable".
- *
- * @param {{ growth: number|null, growthDelta: number }} args
- * @returns {string}
- */
-function quietReason({ growth, growthDelta }) {
-  if (growth === null) {
-    return 'memory pool is within the freshness and index-size thresholds; growth is unmeasured until the next /memory-consolidate stamps an entry count';
-  }
-  return `memory pool is within every threshold — ${growth} entries written since the last consolidation (under the ${growthDelta}-entry growth delta)`;
-}
-
 /**
  * Build the `memoryPoolAdvisory` envelope field.
  *
- * Advisory only — it carries **no routing authority**, mirroring
- * `deliverLightSuggestion`. The `/mandrel-plan` spine surfaces `recommend` at Gate #1;
- * nothing auto-runs, and nothing here mutates the operator's memory store.
+ * Advisory only — it carries **no routing authority**. The `/mandrel-plan`
+ * spine surfaces `recommend` at Gate #1 on one advisory line; nothing
+ * auto-runs, and nothing here mutates the operator's memory store.
  *
  * @param {object} [opts]
  * @param {string} [opts.cwd] — defaults to `process.cwd()`
  * @param {Record<string,string|undefined>} [opts.env]
  * @param {object} [opts.fsImpl] — node:fs-compatible seam
  * @param {string} [opts.homedir]
- * @param {Date|string|number} [opts.now]
- * @param {number} [opts.staleAfterDays]
- * @param {number} [opts.growthDelta]
  * @param {number} [opts.indexByteCeiling]
  * @returns {{ present: boolean, entryCount: number, indexBytes: number|null,
- *            lastConsolidatedAt: string|null,
- *            entriesSinceConsolidation: number|null, recommend: boolean,
- *            reasons: string[] }}
+ *            recommend: boolean, reasons: string[] }}
  */
 export function buildMemoryPoolAdvisory({
   cwd = process.cwd(),
   env = process.env,
   fsImpl = defaultFs,
   homedir,
-  now = new Date(),
-  staleAfterDays = STALE_AFTER_DAYS,
-  growthDelta = GROWTH_DELTA,
   indexByteCeiling = INDEX_BYTE_CEILING,
 } = {}) {
   const absent = (reason) => envelope({ reasons: [reason] });
@@ -384,21 +220,10 @@ export function buildMemoryPoolAdvisory({
     return absent(`memory pool at ${poolDir} could not be listed`);
   }
 
-  const stamp = readStamp({ poolDir, fsImpl, now });
-  // Reported raw: a pruning pass can leave this negative, and saying the pool
-  // shrank by 7 is more use to the operator than clamping it to zero.
-  const growth = stamp.baseline === null ? null : entryCount - stamp.baseline;
   const indexBytes = readIndexBytes({ poolDir, fsImpl });
+  const found = { present: true, entryCount, indexBytes };
 
-  const found = {
-    present: true,
-    entryCount,
-    indexBytes,
-    lastConsolidatedAt: stamp.at,
-    entriesSinceConsolidation: growth,
-  };
-
-  // An empty pool has nothing to consolidate, whatever the stamp says.
+  // An empty pool has nothing to consolidate, whatever the index says.
   if (entryCount === 0) {
     return envelope({
       ...found,
@@ -406,20 +231,33 @@ export function buildMemoryPoolAdvisory({
     });
   }
 
-  const reasons = collectReasons({
-    stamp,
-    growth,
-    indexBytes,
-    now,
-    staleAfterDays,
-    growthDelta,
-    indexByteCeiling,
-  });
+  const { recommend, reason } = judgeIndex(indexBytes, indexByteCeiling);
+  return envelope({ ...found, recommend, reasons: [reason] });
+}
 
-  return envelope({
-    ...found,
-    recommend: reasons.length > 0,
-    reasons:
-      reasons.length > 0 ? reasons : [quietReason({ growth, growthDelta })],
-  });
+/**
+ * The index byte arm's verdict. `indexBytes === null` is an unreadable index,
+ * not a small one, so it stays quiet and says why.
+ *
+ * @param {number|null} indexBytes
+ * @param {number} indexByteCeiling
+ * @returns {{ recommend: boolean, reason: string }}
+ */
+function judgeIndex(indexBytes, indexByteCeiling) {
+  if (indexBytes === null) {
+    return {
+      recommend: false,
+      reason: `memory pool present but ${INDEX_FILENAME} could not be measured — the index ceiling is the only arm and it is unmeasured`,
+    };
+  }
+  if (indexBytes > indexByteCeiling) {
+    return {
+      recommend: true,
+      reason: `${INDEX_FILENAME} is ${indexBytes} bytes, ${indexBytes - indexByteCeiling} over the ${indexByteCeiling}-byte index ceiling — the index is truncated at the cap, so every entry listed after the cut is invisible to every session`,
+    };
+  }
+  return {
+    recommend: false,
+    reason: `${INDEX_FILENAME} is ${indexBytes} bytes, within the ${indexByteCeiling}-byte index ceiling`,
+  };
 }

package/.agents/scripts/lib/orchestration/review-base-ref.js

@@ -0,0 +1,138 @@
+/**
+ * lib/orchestration/review-base-ref.js — the base ref a Story-scope review is
+ * allowed to measure against (Story #5325).
+ *
+ * ## The defect this closes
+ *
+ * A close runs base-sync and the Story-scope review against what everyone
+ * called "the base branch" — but the two meant different refs. Base-sync
+ * fetches and merges `origin/<base>`; the review passed the **bare** branch
+ * name, which git resolves to the LOCAL `refs/heads/<base>`, i.e. to whatever
+ * that ref last fast-forwarded to. On a checkout whose local base is behind
+ * its remote, the review's `<base>...<head>` diff therefore contains every
+ * commit the local ref is missing — other people's landed work, scored as if
+ * this Story had written it. Those findings gate the land, and the operator's
+ * only exit is a `review-block-overridden` on blockers that were never real.
+ *
+ * ## Contract
+ *
+ * One resolution, at the review phase boundary, threaded into the change-set
+ * enumeration, the provider review and the local lens pass — so both arms of
+ * the review agree about what changed and neither can inherit local drift.
+ *
+ * Resolution **fails safe rather than falling back**. Base-sync normally
+ * guarantees the remote ref is present, but a `--skip-sync` close or a
+ * remote-less checkout can reach the review with no `origin/<base>` at all.
+ * Reviewing the local ref anyway is the defect, so an unresolvable base
+ * produces a degradation record — carried on the review's existing
+ * `degraded` / `degradations[]` envelope — and no findings whatsoever.
+ */
+
+import { gitSpawn } from '../git-utils.js';
+import { degradationEnvelope } from './review-providers/degraded-gates.js';
+
+/**
+ * The remote-tracking spelling of a base branch — `main` → `origin/main`.
+ * Already-qualified input passes through, so a caller naming `origin/main`
+ * is not double-prefixed.
+ *
+ * @param {unknown} baseBranch
+ * @returns {string|null} the remote-tracking ref, or `null` when unnameable.
+ */
+export function remoteBaseRef(baseBranch) {
+  const base = typeof baseBranch === 'string' ? baseBranch.trim() : '';
+  if (base.length === 0) return null;
+  return base.startsWith('origin/') ? base : `origin/${base}`;
+}
+
+/**
+ * Resolve the base ref base-sync merged from, **verified present** in this
+ * clone. See the module header for why there is no local-ref fallback.
+ *
+ * @param {{
+ *   baseBranch: string,
+ *   cwd?: string,
+ *   gitSpawnFn?: typeof gitSpawn,
+ * }} args
+ * @returns {{ ref: string|null, resolved: boolean, remoteRef: string|null }}
+ *   `ref` is non-null only when `resolved`; `remoteRef` is the ref that was
+ *   probed, for the caller's degradation surface.
+ */
+export function resolveSharedBaseRef({
+  baseBranch,
+  cwd = process.cwd(),
+  gitSpawnFn = gitSpawn,
+} = {}) {
+  const remoteRef = remoteBaseRef(baseBranch);
+  if (remoteRef === null) {
+    return { ref: null, resolved: false, remoteRef: null };
+  }
+  try {
+    const probe = gitSpawnFn(
+      cwd,
+      'rev-parse',
+      '--verify',
+      '--quiet',
+      `${remoteRef}^{commit}`,
+    );
+    if (probe?.status === 0) {
+      return { ref: remoteRef, resolved: true, remoteRef };
+    }
+  } catch {
+    // A spawn failure and a missing ref are the same answer here: the shared
+    // base cannot be vouched for.
+  }
+  return { ref: null, resolved: false, remoteRef };
+}
+
+/**
+ * The review outcome for a close that cannot establish the shared base.
+ *
+ * Shaped as the same envelope a completed review returns — an all-zero
+ * severity tally, nothing posted, and the `degraded` / `degradations[]` pair
+ * the close and the rendered comment already read — so the surfaces reading
+ * it cannot mistake "no findings" for "reviewed and clean". Reported, not
+ * blocking, matching the posture of every other degraded review gate.
+ *
+ * @param {{
+ *   storyId: number|string,
+ *   baseBranch: string,
+ *   remoteRef: string|null,
+ *   progress: (tag: string, msg: string) => void,
+ *   progressTag?: string,
+ * }} args
+ * @returns {object}
+ */
+export function unresolvedBaseReviewOutcome({
+  storyId,
+  baseBranch,
+  remoteRef,
+  progress,
+  progressTag = 'REVIEW',
+}) {
+  const surface = remoteRef ?? `origin/${baseBranch}`;
+  progress(
+    progressTag,
+    `⚠️ Story-scope review for Story #${storyId} did not run: cannot resolve ` +
+      `${surface}, the base ref base-sync merges from. Diffing the local ` +
+      `${baseBranch} instead would score commits this Story never made, so no ` +
+      'findings are raised. Fetch the base ref (or re-run without ' +
+      '--skip-sync) to restore the review.',
+  );
+  return {
+    halted: false,
+    skipped: true,
+    severity: { critical: 0, high: 0, medium: 0, suggestion: 0 },
+    posted: false,
+    postedCommentId: null,
+    ...degradationEnvelope([
+      {
+        tool: 'story-scope-review',
+        gate: 'base-ref-resolution',
+        surface,
+        reason: 'remote-base-ref-unresolved',
+      },
+    ]),
+    crossRefPosted: false,
+  };
+}

package/.agents/scripts/lib/orchestration/single-story-close/phases/close-validation.js

@@ -78,6 +78,7 @@ import { runPreGateSteps as defaultRunPreGateSteps } from './pre-gate-steps.js';
  *   runPreGateSteps?: typeof defaultRunPreGateSteps,
  *   runScopedFormatAutofix?: Function,
  *   runBaselineUpwardWriteback?: Function,
+ *   runContextBudgetWriteback?: Function,
  *   createGateLogSink?: typeof defaultCreateGateLogSink,
  * }} args
  * @returns {Promise<{ gates: Record<string, 'passed'|'skipped'> }>} Per-gate
@@ -98,6 +99,7 @@ export async function runCloseValidationPhase({
   runPreGateSteps = defaultRunPreGateSteps,
   runScopedFormatAutofix,
   runBaselineUpwardWriteback,
+  runContextBudgetWriteback,
   createGateLogSink = defaultCreateGateLogSink,
 }) {
   await runPreGateSteps({
@@ -110,6 +112,7 @@ export async function runCloseValidationPhase({
     progress,
     runScopedFormatAutofix,
     runBaselineUpwardWriteback,
+    runContextBudgetWriteback,
   });
 
   progress(
@@ -124,6 +127,8 @@ export async function runCloseValidationPhase({
     baseBranch,
     cwd: worktreePath || cwd,
     log: gateLog.log,
+    storyId, // Story #5313 — a credited bare `npm test` registers `test`.
+    evidenceCwd: cwd,
   });
   let validation;
   try {

package/.agents/scripts/lib/orchestration/single-story-close/phases/code-review.js

@@ -25,9 +25,21 @@
  * shares a single invocation pattern (Story #3653). Review depth needs no
  * input here: it is derived from this Story's own diff inside `runCodeReview`
  * (Story #4542).
+ *
+ * Story #5325 — this phase boundary is where the base ref is resolved, once.
+ * The resolved ref threads into `runStoryReviewCore`, which hands it to both
+ * the change-set enumeration (and through it the provider review) and the
+ * local lens pass, so one resolution corrects both arms. It resolves to
+ * `origin/<baseBranch>` — the ref base-sync merged from — rather than the bare
+ * branch name git would resolve to the local `refs/heads/<baseBranch>`, whose
+ * drift would otherwise be scored as this Story's own change.
  */
 
 import { parsePrNumberFromUrl } from '../../../github-url.js';
+import {
+  resolveSharedBaseRef,
+  unresolvedBaseReviewOutcome,
+} from '../../review-base-ref.js';
 import { degradationEnvelope } from '../../review-providers/degraded-gates.js';
 import { runStoryReviewCore } from '../../story-close/phases/review-core.js';
 import { postStructuredComment } from '../../ticketing/state.js';
@@ -78,23 +90,25 @@ export function buildStoryReviewCrossRefBody({
 async function invokeStoryReviewCore({
   storyId,
   storyBranch,
-  baseBranch,
+  baseRef,
   prNumber,
   provider,
   runCodeReviewFn,
   runLocalLensReviewFn,
   appendFindingsYieldFn,
+  gitSpawnFn,
   progress,
 }) {
   return runStoryReviewCore({
     storyId,
-    baseRef: baseBranch,
+    baseRef,
     headRef: storyBranch,
     commentTargetId: prNumber,
     provider,
     progress,
     progressTag: 'REVIEW',
     runCodeReviewFn,
+    gitSpawnFn,
     // Forward the seams only when the caller injects them; otherwise
     // `runStoryReviewCore` uses its defaults. `undefined` deep-merges to
     // the default via the destructuring default there.
@@ -153,6 +167,9 @@ async function postStoryReviewCrossRef({
  * Failure modes:
  *   - When `prNumber` is null (couldn't parse), the review is skipped
  *     and the function returns `{ halted: false, skipped: true }`.
+ *   - When `origin/<baseBranch>` cannot be resolved, the review is skipped,
+ *     a `base-ref-resolution` degradation is recorded on the returned
+ *     envelope, and no findings are raised (Story #5325).
  *   - When the runner throws, the close fails non-zero (the throw
  *     propagates) — a Story-scope review failure is not silently
  *     ignored.
@@ -170,6 +187,7 @@ async function postStoryReviewCrossRef({
  *   runCodeReviewFn: Function,
  *   runLocalLensReviewFn?: Function,
  *   appendFindingsYieldFn?: Function,
+ *   gitSpawnFn?: Function,
  *   progress: (tag: string, msg: string) => void,
  * }} args
  * @returns {Promise<{
@@ -185,7 +203,7 @@ async function postStoryReviewCrossRef({
  * }>}
  */
 export async function runStoryScopeReview({
-  cwd: _cwd,
+  cwd,
   storyId,
   storyBranch,
   baseBranch,
@@ -195,6 +213,7 @@ export async function runStoryScopeReview({
   runCodeReviewFn,
   runLocalLensReviewFn,
   appendFindingsYieldFn,
+  gitSpawnFn,
   progress,
 }) {
   if (prNumber == null) {
@@ -205,20 +224,33 @@ export async function runStoryScopeReview({
     return { halted: false, skipped: true };
   }
 
+  // One resolution per close, at the phase boundary: `baseRef` threads from
+  // here into the change set, the provider review and the local lens pass.
+  const base = resolveSharedBaseRef({ baseBranch, cwd, gitSpawnFn });
+  if (!base.resolved) {
+    return unresolvedBaseReviewOutcome({
+      storyId,
+      baseBranch,
+      remoteRef: base.remoteRef,
+      progress,
+    });
+  }
+
   progress(
     'REVIEW',
-    `Running Story-scope code review for Story #${storyId} (${baseBranch}...${storyBranch}) → PR #${prNumber}...`,
+    `Running Story-scope code review for Story #${storyId} (${base.ref}...${storyBranch}) → PR #${prNumber}...`,
   );
 
   const result = await invokeStoryReviewCore({
     storyId,
     storyBranch,
-    baseBranch,
+    baseRef: base.ref,
     prNumber,
     provider,
     runCodeReviewFn,
     runLocalLensReviewFn,
     appendFindingsYieldFn,
+    gitSpawnFn,
     progress,
   });