mandrel 2.9.0 → 2.11.0

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

@@ -36,6 +36,24 @@
  * Backgrounding is not a workaround here and does not need to be: an
  * interrupted poll is stateless and re-entrant by construction.
  *
+ * ## Async mode (Story #4698 — a designed short probe window, not an accident)
+ *
+ * `maxWaitSeconds` (default 300s) still routinely EXPIRES on a slow-CI
+ * consumer: the median PR-create→merge time can be minutes, so nearly every
+ * close burns its whole foreground slot polling and then returns `pending`
+ * anyway. `delivery.mergeWatch.mode: "async"` makes that async confirm a
+ * designed mode rather than an expiry accident. It caps the per-invocation
+ * wait to a short probe window (`ASYNC_PROBE_WINDOW_SECONDS`, ~60s) — long
+ * enough for the loop's existing checks to catch an instant merge and, via the
+ * imported {@link decideMergeWaitFailFast} decision (Story #4695/#4710), an
+ * instantly-red required check — then returns the SAME resumable `pending`
+ * terminal, whose `nextCommand` the worker launches in the background. Nothing
+ * else changes: the cumulative `maxBudgetSeconds` anchor is untouched, and
+ * `sync` mode (the default) is byte-compatible. An explicit `--max-wait-seconds`
+ * override wins over the async cap so a headless caller can still land in one
+ * block. The clamp lives entirely in `resolveMergeWaitConfig`; the poll loop is
+ * mode-agnostic.
+ *
  * ## The wait is not weaker than the watch it displaced
  *
  * The pre-#4543 poll read only `state` / `mergedAt`. A check that went red
@@ -72,7 +90,7 @@
  *     confirm.
  */
 
-import { gh as defaultGh } from '../../../gh-exec.js';
+import { createGh } from '../../../gh-exec.js';
 import {
   confirmStoryMerged as defaultConfirmStoryMerged,
   readPrMergeState as defaultReadPrMergeState,
@@ -86,8 +104,10 @@ import { classifyMergeBlock as defaultClassifyMergeBlock } from '../../merge-blo
 import {
   DEFAULT_INTERVAL_SECONDS,
   DEFAULT_MAX_BUDGET_SECONDS,
+  decideMergeWaitFailFast,
   deriveChecksStatus,
-  failingChecksBlockMerge,
+  deriveRequiredRunEvidence,
+  MERGE_WAIT_GH_TIMEOUT_MS,
 } from '../../merge-poll.js';
 import { NEXT_COMMANDS } from '../../story-deliver-terminal.js';
 import {
@@ -105,6 +125,17 @@ import { runPostLandTail as defaultRunPostLandTail } from './post-land.js';
  */
 export const DEFAULT_MAX_WAIT_SECONDS = 300;
 
+/**
+ * Async-mode per-invocation probe window (Story #4698). When
+ * `delivery.mergeWatch.mode` is `"async"`, `resolveMergeWaitConfig` caps the
+ * per-invocation wait to this many seconds so close returns the resumable
+ * `pending` terminal fast instead of burning the foreground host slot. Sized
+ * to catch an instant merge and — via the head-anchored required-check
+ * predicate — an instantly-red required check, while staying far inside the
+ * cumulative `maxBudgetSeconds` give-up bound.
+ */
+export const ASYNC_PROBE_WINDOW_SECONDS = 60;
+
 /** Bounded `gh pr update-branch` attempts for a BEHIND PR. */
 export const DEFAULT_UPDATE_ATTEMPTS = 3;
 
@@ -129,6 +160,49 @@ function defaultSleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+/**
+ * The wait's default `gh` facade, bound to a spawn-level timeout (Story
+ * #4710): every subprocess the wait launches through it carries
+ * `MERGE_WAIT_GH_TIMEOUT_MS`, so a wedged `gh` child is killed rather than
+ * stranding an unattended async-mode wait forever. Callers that inject their
+ * own `gh` (tests, the resume CLI) are bounded by {@link withGhTimeout} at
+ * the call sites instead.
+ */
+const defaultGh = createGh(undefined, { timeoutMs: MERGE_WAIT_GH_TIMEOUT_MS });
+
+/**
+ * Bound an arbitrary `gh` call with a wall-clock timeout (Story #4710). The
+ * spawn-level `timeoutMs` on {@link defaultGh} already kills a wedged real
+ * subprocess, but an injected `gh` implementation (a test stub, a facade
+ * built without defaults) can still return a promise that never settles —
+ * and the merge wait must never hang on any of them. Rejection maps to the
+ * caller's existing error handling: the probe degrades to its conservative
+ * pending shape, the update-branch attempt logs and continues.
+ *
+ * A late settlement of the losing promise is explicitly absorbed so a
+ * post-timeout rejection cannot surface as an unhandled rejection.
+ *
+ * The timeout timer is deliberately NOT `unref`'d: when the awaited call is a
+ * promise that never settles (a hung stub, or a real gh child whose I/O has
+ * gone quiet), the timer is the ONLY handle keeping the event loop alive, so
+ * unref'ing it would let the process/test exit before the timeout ever fires —
+ * exactly the hang this guard exists to prevent. It is short-lived and always
+ * cleared in `finally`, so keeping it referenced costs nothing.
+ */
+function withGhTimeout(promise, timeoutMs, label) {
+  let timer;
+  const bounded = new Promise((resolve, reject) => {
+    timer = setTimeout(() => {
+      reject(
+        new Error(`${label} did not return within ${timeoutMs}ms (timeout)`),
+      );
+    }, timeoutMs);
+    promise.then(resolve, reject);
+  }).finally(() => clearTimeout(timer));
+  promise.catch(() => {});
+  return bounded;
+}
+
 /**
  * One probe per poll iteration, carrying every field the loop and the
  * terminal classifier need: merge state, the checks rollup, the merge-state
@@ -137,20 +211,31 @@ function defaultSleep(ms) {
  *
  * Returns a degraded `{ checksStatus: 'pending', error }` probe when the read
  * itself fails, preserving the conservative classification on probe errors —
- * a flaky API read must not be mistaken for a definitive verdict.
+ * a flaky API read must not be mistaken for a definitive verdict. A probe
+ * that exceeds `ghTimeoutMs` (Story #4710) takes the SAME degraded path: a
+ * hung subprocess must surface as a probe error within the bound, never
+ * strand the wait.
  *
  * @returns {Promise<object>}
  */
-export async function readPrWaitProbe({ prNumber, gh = defaultGh }) {
+export async function readPrWaitProbe({
+  prNumber,
+  gh = defaultGh,
+  ghTimeoutMs = MERGE_WAIT_GH_TIMEOUT_MS,
+}) {
   try {
-    const view = await gh.pr.view(prNumber, [
-      'state',
-      'mergedAt',
-      'createdAt',
-      'mergeStateStatus',
-      'reviewDecision',
-      'statusCheckRollup',
-    ]);
+    const view = await withGhTimeout(
+      gh.pr.view(prNumber, [
+        'state',
+        'mergedAt',
+        'createdAt',
+        'mergeStateStatus',
+        'reviewDecision',
+        'statusCheckRollup',
+      ]),
+      ghTimeoutMs,
+      `gh pr view ${prNumber}`,
+    );
     return {
       state: typeof view?.state === 'string' ? view.state : null,
       mergedAt: typeof view?.mergedAt === 'string' ? view.mergedAt : null,
@@ -164,6 +249,11 @@ export async function readPrWaitProbe({ prNumber, gh = defaultGh }) {
           ? view.reviewDecision
           : undefined,
       checksStatus: deriveChecksStatus(view?.statusCheckRollup),
+      // Head-anchored per-run evidence (Story #4695): distinguishes a
+      // genuinely red required run from the superseded / still-pending noise
+      // the aggregate `checksStatus` folds together. `null` when the rollup is
+      // absent/empty — the loop's consecutive-probe fallback owns that path.
+      requiredRunEvidence: deriveRequiredRunEvidence(view?.statusCheckRollup),
     };
   } catch (err) {
     return {
@@ -185,18 +275,36 @@ export async function readPrWaitProbe({ prNumber, gh = defaultGh }) {
  * raises the per-invocation bound to keep single-block semantics without
  * editing the consumer's config.
  *
+ * `mode` (Story #4698) selects the close-time merge posture. `async` caps the
+ * per-invocation wait to `ASYNC_PROBE_WINDOW_SECONDS` so close returns the
+ * resumable `pending` terminal fast; `sync` (the default) is unchanged. An
+ * explicit `maxWaitSecondsOverride` still wins over the async cap — a headless
+ * caller with no host ceiling opts back into single-block waiting.
+ *
  * @param {object} [config]
  * @param {number} [maxWaitSecondsOverride]
- * @returns {{ intervalSeconds: number, maxWaitSeconds: number, maxBudgetSeconds: number, updateAttempts: number }}
+ * @returns {{ mode: 'sync'|'async', intervalSeconds: number, maxWaitSeconds: number, maxBudgetSeconds: number, updateAttempts: number }}
  */
 export function resolveMergeWaitConfig(config, maxWaitSecondsOverride) {
   const mergeWatch = config?.delivery?.mergeWatch ?? {};
   const int = (value, fallback, min = 1) =>
     Number.isInteger(value) && value >= min ? value : fallback;
-  const maxWaitSeconds = int(
+  const mode = mergeWatch.mode === 'async' ? 'async' : 'sync';
+  const configuredMaxWait = int(
     maxWaitSecondsOverride,
     int(mergeWatch.maxWaitSeconds, DEFAULT_MAX_WAIT_SECONDS),
   );
+  // Async mode caps the per-invocation wait to a short probe window so close
+  // returns `pending` fast instead of burning the foreground host slot on a
+  // merge that lands after the wait would have expired anyway. The window is
+  // long enough for the loop's existing checks to catch an instant merge and —
+  // via the imported `decideMergeWaitFailFast` decision — an instantly
+  // red required check. An explicit `--max-wait-seconds` override still wins so
+  // a headless caller with no host ceiling opts back into single-block waiting.
+  const maxWaitSeconds =
+    mode === 'async' && maxWaitSecondsOverride == null
+      ? Math.min(configuredMaxWait, ASYNC_PROBE_WINDOW_SECONDS)
+      : configuredMaxWait;
   // A poll interval longer than the wait bound is incoherent, and silently
   // harmful: the pending check would fire on poll 1 every time, so the wait
   // could never sleep, `polls` could never reach
@@ -210,6 +318,7 @@ export function resolveMergeWaitConfig(config, maxWaitSecondsOverride) {
     maxWaitSeconds,
   );
   return {
+    mode,
     intervalSeconds,
     maxWaitSeconds,
     maxBudgetSeconds: int(
@@ -429,6 +538,12 @@ async function blockOnUnlanded({
     budget,
   });
   const elapsedSeconds = budget?.elapsedSeconds ?? 0;
+  // Which evidence path produced a `checks-failed` verdict (Story #4695):
+  // `per-run` (head-anchored required-run evidence) or `consecutive-probe`
+  // (the evidence-unavailable fallback). Named on the emitted record so the
+  // `merge.unlanded` telemetry attributes the fail-fast to the path that
+  // fired it. Absent for every other block class.
+  const evidencePath = prProbe?.evidencePath;
 
   if (Number.isInteger(prNumber) && prNumber > 0) {
     try {
@@ -439,6 +554,7 @@ async function blockOnUnlanded({
         blockClass,
         reason,
         elapsedSeconds,
+        ...(evidencePath ? { evidencePath } : {}),
       });
     } catch (err) {
       progress?.(
@@ -509,6 +625,7 @@ async function maybeUpdateBehindPr({
   updatesUsed,
   updateAttempts,
   gh,
+  ghTimeoutMs = MERGE_WAIT_GH_TIMEOUT_MS,
   progress,
 }) {
   if (probe.mergeStateStatus !== 'BEHIND') return false;
@@ -520,7 +637,11 @@ async function maybeUpdateBehindPr({
     return false;
   }
   try {
-    await (gh ?? defaultGh).pr.updateBranch(prNumber);
+    await withGhTimeout(
+      (gh ?? defaultGh).pr.updateBranch(prNumber),
+      ghTimeoutMs,
+      `gh pr update-branch ${prNumber}`,
+    );
     progress?.(
       'CONFIRM',
       `⏫ PR #${prNumber} was BEHIND its base — updated (attempt ${updatesUsed + 1}/${updateAttempts}).`,
@@ -650,6 +771,10 @@ async function onMergeObserved({
  * @param {(ms: number) => Promise<void>} [args.sleepFn] Test seam so the
  *   suite does not actually wait.
  * @param {() => number} [args.nowMsFn] Test seam; returns epoch ms.
+ * @param {number} [args.ghTimeoutMs] Wall-clock bound for each `gh` call the
+ *   wait makes (Story #4710). A framework constant
+ *   (`MERGE_WAIT_GH_TIMEOUT_MS`), overridable only as a test seam — not
+ *   config.
  * @returns {Promise<object>}
  */
 export async function runConfirmMergePhase({
@@ -676,6 +801,7 @@ export async function runConfirmMergePhase({
   runPostLandTailFn = defaultRunPostLandTail,
   sleepFn = defaultSleep,
   nowMsFn = Date.now,
+  ghTimeoutMs = MERGE_WAIT_GH_TIMEOUT_MS,
 }) {
   // The arm itself never succeeded (gh failure, unparseable PR number, or a
   // deliberate disablement) — there is no "armed but unconfirmed" PR to
@@ -699,22 +825,38 @@ export async function runConfirmMergePhase({
     });
   }
 
-  const { intervalSeconds, maxWaitSeconds, maxBudgetSeconds, updateAttempts } =
-    resolveMergeWaitConfig(config, maxWaitSecondsOverride);
+  const {
+    mode,
+    intervalSeconds,
+    maxWaitSeconds,
+    maxBudgetSeconds,
+    updateAttempts,
+  } = resolveMergeWaitConfig(config, maxWaitSecondsOverride);
   const intervalMs = intervalSeconds * 1000;
   const startedAtMs = nowMsFn();
   let anchorMs = startedAtMs;
   let updatesUsed = 0;
   let polls = 0;
+  // Consecutive failing check probes observed WITHOUT per-run evidence
+  // (Story #4695). The evidence-unavailable fallback: a single failing rollup
+  // snapshot never fail-fasts — two consecutive failing probes at least one
+  // poll interval apart are required. Reset on any non-failing (or genuinely
+  // evidenced) probe.
+  let consecutiveRequiredFailSnapshots = 0;
 
   progress?.(
     'CONFIRM',
     `⏳ Close-and-land: polling PR #${prNumber} for merge confirmation ` +
-      `(wait=${maxWaitSeconds}s this invocation, cumulative budget=${maxBudgetSeconds}s)...`,
+      `(mode=${mode}, wait=${maxWaitSeconds}s this invocation, ` +
+      `cumulative budget=${maxBudgetSeconds}s)...`,
   );
 
   while (true) {
-    const probe = await readPrWaitProbeFn({ prNumber, gh: injectedGh });
+    const probe = await readPrWaitProbeFn({
+      prNumber,
+      gh: injectedGh,
+      ghTimeoutMs,
+    });
     polls += 1;
 
     // Anchor the cumulative budget at the PR's creation the first time we
@@ -755,6 +897,12 @@ export async function runConfirmMergePhase({
       });
     }
 
+    // Everything below funnels into ONE terminal exit (Story #4710): each
+    // definitive condition fills `unlanded` and the single call site at the
+    // bottom classifies, emits, and blocks — the fail-fast tree used to
+    // duplicate that block twice inline.
+    let unlanded = null;
+
     if (probe.state === 'CLOSED') {
       // Closed without merging — a definitive terminal, not a "still
       // pending" condition the budget should keep waiting on. checksStatus
@@ -763,10 +911,7 @@ export async function runConfirmMergePhase({
       // pending", which would misclassify this definitive case as
       // checks-pending-timeout instead of reaching the api-race-other
       // reason built from prProbe.error.
-      return blockOnUnlanded({
-        storyId,
-        prNumber,
-        prUrl,
+      unlanded = {
         prProbe: {
           checksStatus: 'closed',
           error: 'PR closed without merging (state=CLOSED)',
@@ -775,72 +920,78 @@ export async function runConfirmMergePhase({
           exhausted: true,
           elapsedSeconds: Math.round(waitedMs / 1000),
         },
-        provider,
-        progress,
-        classifyMergeBlockFn,
-        emitMergeUnlandedFn,
+      };
+    } else {
+      // Fail fast on a GENUINELY red REQUIRED check — head-anchored (Story
+      // #4695), decided by the extracted `decideMergeWaitFailFast` (Story
+      // #4710): per-run evidence decides on a single probe; without evidence
+      // two consecutive failing probes are required. No remaining budget
+      // turns a failed check green, and waiting it out is what made the
+      // pre-#4543 wait report the operator's red test run as a
+      // branch-protection block.
+      const decision = decideMergeWaitFailFast({
+        probe,
+        consecutiveRequiredFailSnapshots,
       });
+      consecutiveRequiredFailSnapshots =
+        decision.consecutiveRequiredFailSnapshots;
+      if (decision.failFast) {
+        progress?.(
+          'CONFIRM',
+          decision.evidencePath === 'per-run'
+            ? `🛑 PR #${prNumber}: a required check concluded failure with none in flight — failing fast (evidence=per-run).`
+            : `🛑 PR #${prNumber}: two consecutive failing check probes without per-run evidence — failing fast (evidence=consecutive-probe).`,
+        );
+        unlanded = {
+          prProbe: decision.prProbe,
+          budget: {
+            exhausted: false,
+            elapsedSeconds: Math.round(waitedMs / 1000),
+          },
+        };
+      }
     }
 
-    // Fail fast on a red REQUIRED check. No remaining budget turns a failed
-    // check green, and waiting it out is what made the pre-#4543 wait report
-    // the operator's red test run as a branch-protection block.
-    //
-    // Gated on `failingChecksBlockMerge`, not on the raw rollup: a red
-    // OPTIONAL check does not stop native auto-merge, so failing fast on it
-    // would block the Story while the PR lands anyway.
-    if (failingChecksBlockMerge(probe)) {
-      progress?.(
-        'CONFIRM',
-        `🛑 PR #${prNumber}: a required check went red — failing fast rather than burning the budget.`,
-      );
-      return blockOnUnlanded({
-        storyId,
-        prNumber,
-        prUrl,
-        prProbe: probe,
-        budget: {
-          exhausted: false,
-          elapsedSeconds: Math.round(waitedMs / 1000),
-        },
-        provider,
-        progress,
-        classifyMergeBlockFn,
-        emitMergeUnlandedFn,
-      });
-    }
+    if (!unlanded) {
+      if (
+        await maybeUpdateBehindPr({
+          probe,
+          prNumber,
+          updatesUsed,
+          updateAttempts,
+          gh: injectedGh,
+          ghTimeoutMs,
+          progress,
+        })
+      ) {
+        updatesUsed += 1;
+      }
 
-    if (
-      await maybeUpdateBehindPr({
-        probe,
-        prNumber,
-        updatesUsed,
-        updateAttempts,
-        gh: injectedGh,
-        progress,
-      })
-    ) {
-      updatesUsed += 1;
+      // Cumulative budget exhausted → the genuine give-up. Classify from the
+      // probe we already hold. Gated behind the poll floor so an
+      // already-over-budget PR (anchored at a createdAt older than the budget
+      // — a resume the next day, or a long-open PR) still gets a real poll
+      // cycle instead of being blocked before this invocation waited at all.
+      if (
+        polls >= MIN_POLLS_BEFORE_BUDGET_BLOCK &&
+        cumulativeMs + intervalMs > maxBudgetSeconds * 1000
+      ) {
+        unlanded = {
+          prProbe: probe,
+          budget: {
+            exhausted: true,
+            elapsedSeconds: Math.round(cumulativeMs / 1000),
+          },
+        };
+      }
     }
 
-    // Cumulative budget exhausted → the genuine give-up. Classify from the
-    // probe we already hold. Gated behind the poll floor so an
-    // already-over-budget PR (anchored at a createdAt older than the budget —
-    // a resume the next day, or a long-open PR) still gets a real poll cycle
-    // instead of being blocked before this invocation waited at all.
-    if (
-      polls >= MIN_POLLS_BEFORE_BUDGET_BLOCK &&
-      cumulativeMs + intervalMs > maxBudgetSeconds * 1000
-    ) {
+    if (unlanded) {
       return blockOnUnlanded({
         storyId,
         prNumber,
         prUrl,
-        prProbe: probe,
-        budget: {
-          exhausted: true,
-          elapsedSeconds: Math.round(cumulativeMs / 1000),
-        },
+        ...unlanded,
         provider,
         progress,
         classifyMergeBlockFn,

package/.agents/scripts/lib/orchestration/spec-budget.js

@@ -0,0 +1,78 @@
+/**
+ * lib/orchestration/spec-budget.js — the soft `## Spec` word-budget pass
+ * (Story #4723), extracted from `ticket-validator.js` so the advisory
+ * length nudge lives beside neither the hard validators nor their error
+ * channel: everything here is `'soft'` by construction and can never fail
+ * a persist.
+ */
+
+import { parse as parseStoryBody } from '../story-body/story-body.js';
+
+/**
+ * Soft advisory word budget for a Story's inline `## Spec` (Story #4723).
+ * ~250 words is the #4707 contract-level-prose target: interfaces,
+ * invariants, and load-bearing constraints — not route-by-route behavior
+ * narration. Distinct from the hard ~1500-token fail-closed ceiling in
+ * `spec-spill.js`: this budget only warns; it never fails the persist.
+ */
+export const SPEC_SOFT_WORD_BUDGET = 250;
+
+/**
+ * Resolve a Story's Spec prose across both authoring shapes: the canonical
+ * serialized string body (parsed; `## Spec` text block) and the
+ * pre-serialize structured object body (`body.spec`). Returns `''` when
+ * absent — or when a string body does not parse: this pass is advisory, so
+ * an unreadable body contributes no finding here and is left to the hard
+ * parse gate (`assertStoryBodiesParse`) to reject.
+ *
+ * @param {object} story
+ * @returns {string}
+ */
+function resolveSpecText(story) {
+  const body = story?.body;
+  if (typeof body === 'string' && body.trim().length > 0) {
+    let spec;
+    try {
+      spec = parseStoryBody(body).body.spec;
+    } catch {
+      return '';
+    }
+    return typeof spec === 'string' ? spec : '';
+  }
+  if (body !== null && typeof body === 'object') {
+    return typeof body?.spec === 'string' ? body.spec : '';
+  }
+  return '';
+}
+
+/**
+ * Advisory `## Spec` length pass (Story #4723). Emits one `'soft'` finding
+ * per Story whose Spec prose exceeds {@link SPEC_SOFT_WORD_BUDGET} words,
+ * nudging the author toward contract-level prose (#4707). Soft only — the
+ * findings never reach the validator's `errors[]` channel, so an
+ * over-budget Spec never fails the persist.
+ *
+ * @param {{ stories: object[] }} opts
+ * @returns {object[]} Zero or more `spec-word-budget` findings.
+ */
+export function computeSpecBudgetFindings({ stories }) {
+  const findings = [];
+  for (const story of stories ?? []) {
+    const words = resolveSpecText(story).split(/\s+/).filter(Boolean).length;
+    if (words <= SPEC_SOFT_WORD_BUDGET) continue;
+    findings.push({
+      kind: 'spec-word-budget',
+      severity: 'soft',
+      ticketSlug: story.slug ?? '<unknown>',
+      words,
+      budget: SPEC_SOFT_WORD_BUDGET,
+      message:
+        `Story "${story.slug ?? '<unknown>'}" ## Spec is ~${words} words ` +
+        `(soft budget ${SPEC_SOFT_WORD_BUDGET}). Prefer contract-level prose ` +
+        '(interfaces, invariants, load-bearing constraints with their why) ' +
+        'over per-file behavior narration — advisory only; the persist ' +
+        'proceeds.',
+    });
+  }
+  return findings;
+}

package/.agents/scripts/lib/orchestration/story-body-gate.js

@@ -0,0 +1,72 @@
+/**
+ * lib/orchestration/story-body-gate.js — the Story-body parse gate
+ * (Story #4541), extracted from `ticket-validator.js`: the one place a
+ * serialized Story body is parsed with parse failures translated into the
+ * validator's operator-legible `ValidationError` shape. Both the gate that
+ * refuses a plan up front (`assertStoryBodiesParse`) and the per-call
+ * translating parser (`parseStoryBodyOrThrow`) the downstream validators
+ * lean on live here.
+ */
+
+import { ValidationError } from '../errors/index.js';
+import {
+  parse as parseStoryBody,
+  StoryBodyParseError,
+} from '../story-body/story-body.js';
+
+/**
+ * Parse a Story's serialized markdown body, translating a
+ * `StoryBodyParseError` into a `ValidationError` that names the offending
+ * **section** and **entry** (Story #4541).
+ *
+ * `StoryBodyParseError` already carries `field` (the section the parser was
+ * reading) and `raw` (the entry text that failed); this lifts both into an
+ * operator-legible message and a structured `violation` payload so an
+ * authoring loop can point at the exact bullet instead of re-deriving it
+ * from a downstream freshness miss.
+ *
+ * @param {object} story Story whose `body` is a non-empty markdown string.
+ * @returns {object} The structured body.
+ * @throws {ValidationError} `code: 'story-body-unparseable'`.
+ */
+export function parseStoryBodyOrThrow(story) {
+  try {
+    return parseStoryBody(story.body).body;
+  } catch (err) {
+    if (!(err instanceof StoryBodyParseError)) throw err;
+    const slug = story.slug ?? '<unknown>';
+    const section = err.field ?? 'body';
+    const entry = err.raw ?? null;
+    const entryLine = entry === null ? '' : `\n      entry: ${entry}`;
+    const violation = { slug, section, entry, reason: err.message };
+    const error = new ValidationError(
+      `Cross-Validation Failed: Story "${slug}" has an unparseable body — ` +
+        `the ## ${section} section could not be read: ${err.message}` +
+        `${entryLine}\n\nFix the offending entry; this is a malformed body, ` +
+        'not a stale path reference.',
+      { violations: [violation] },
+    );
+    error.code = 'story-body-unparseable';
+    error.violations = [violation];
+    throw error;
+  }
+}
+
+/**
+ * Refuse the plan when any Story's serialized body cannot be parsed, before
+ * either git-probe gate runs (Story #4541). Ordering matters: the freshness
+ * gate consults `body.changes` for its net-new whitelist, so an unparseable
+ * body used to reach the operator as a freshness miss naming declared paths.
+ *
+ * @param {{ tickets: object[] }} opts
+ * @throws {ValidationError} `code: 'story-body-unparseable'` on the first
+ *   offending Story.
+ */
+export function assertStoryBodiesParse({ tickets }) {
+  for (const story of (tickets ?? []).filter((t) => t.type === 'story')) {
+    if (typeof story.body !== 'string' || story.body.trim().length === 0) {
+      continue;
+    }
+    parseStoryBodyOrThrow(story);
+  }
+}