mandrel 2.63.0 → 2.65.0

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

@@ -282,11 +282,61 @@ async function stepPlanRunLabelReap({
 }
 
 /**
- * Run the post-land tail, sequentially. The ref reap and fast-forward (the
- * local-checkout mutations, reap first) run under a cross-process lock on the
- * main checkout, since concurrent closes race on the base ref and worktree
- * registry; GitHub steps stay outside it. The lock is best-effort: on
- * timeout the mutations run anyway.
+ * The local-checkout mutations (ref reap first, then fast-forward) under a
+ * cross-process lock on the main checkout, since concurrent closes race on
+ * the base ref and worktree registry. Best-effort: on timeout they run anyway.
+ */
+async function runLockedLocalSteps({
+  storyId,
+  storyBranch,
+  baseBranch,
+  cwd,
+  config,
+  progress,
+  gitSpawnFn,
+  planFastForwardFn,
+  executeFastForwardFn,
+  acquireLockWithWaitFn,
+}) {
+  const lockCfg = config?.delivery?.postLandLock ?? {};
+  const lock = await acquireLockWithWaitFn({
+    lockPath: postLandLockPath(cwd),
+    waitMs: lockCfg.waitMs,
+    pollMs: lockCfg.pollMs,
+    timeoutMs: lockCfg.timeoutMs,
+    ownerId: `post-land-${storyId}`,
+  });
+  if (!lock.acquired) {
+    progress?.(
+      'POST-LAND',
+      `⚠️ post-land lock not acquired (${lock.reason}); proceeding unserialized.`,
+    );
+  }
+  try {
+    const refCleanup = await step(
+      () => stepRefCleanup({ cwd, storyBranch, progress, gitSpawnFn }),
+      { name: 'local ref cleanup', progress },
+    );
+    const baseFastForward = await step(
+      () =>
+        stepBaseFastForward({
+          cwd,
+          baseBranch,
+          progress,
+          planFastForwardFn,
+          executeFastForwardFn,
+        }),
+      { name: 'base fast-forward', progress },
+    );
+    return { refCleanup, baseFastForward };
+  } finally {
+    if (lock.acquired) lock.release();
+  }
+}
+
+/**
+ * Run the post-land tail: friction markers, then the GitHub steps and the
+ * locked local steps concurrently, then temp purge, then lease release.
  *
  * @param {object} args
  * @param {number} args.storyId
@@ -348,87 +398,67 @@ export async function runPostLandTail({
     config,
   });
 
-  const followUps = await step(
-    () =>
-      stepFollowUps({
-        storyId,
-        provider,
-        config,
-        cwd,
-        progress,
-        captureStoryFollowUpsFn,
-      }),
-    { name: 'follow-up capture', progress },
-  );
-  const statusResync = await step(
-    () =>
-      stepStatusResync({
-        storyId,
-        provider,
-        config,
-        progress,
-        reassertStatusColumnFn,
-      }),
-    { name: 'status-column resync', progress },
-  );
-  await step(
-    () =>
-      stepPlanRunLabelReap({
-        storyId,
-        provider,
-        progress,
-        reapPlanRunLabelsForStoryFn,
-      }),
-    { name: 'plan-run label reap', progress },
-  );
-
-  const epicRollup = await step(
-    () =>
-      stepEpicRollup({
-        storyId,
-        provider,
-        config,
-        progress,
-        rollUpEpicForStoryFn,
-      }),
-    { name: 'epic rollup', progress },
-  );
-
-  const lockCfg = config?.delivery?.postLandLock ?? {};
-  const lock = await acquireLockWithWaitFn({
-    lockPath: postLandLockPath(cwd),
-    waitMs: lockCfg.waitMs,
-    pollMs: lockCfg.pollMs,
-    timeoutMs: lockCfg.timeoutMs,
-    ownerId: `post-land-${storyId}`,
-  });
-  if (!lock.acquired) {
-    progress?.(
-      'POST-LAND',
-      `⚠️ post-land lock not acquired (${lock.reason}); proceeding unserialized.`,
-    );
-  }
-  let refCleanup;
-  let baseFastForward;
-  try {
-    refCleanup = await step(
-      () => stepRefCleanup({ cwd, storyBranch, progress, gitSpawnFn }),
-      { name: 'local ref cleanup', progress },
-    );
-    baseFastForward = await step(
+  // The GitHub steps are independent of each other and of the local
+  // lock-held mutations, so all of them run concurrently.
+  const [followUps, statusResync, , epicRollup, local] = await Promise.all([
+    step(
       () =>
-        stepBaseFastForward({
+        stepFollowUps({
+          storyId,
+          provider,
+          config,
           cwd,
-          baseBranch,
           progress,
-          planFastForwardFn,
-          executeFastForwardFn,
+          captureStoryFollowUpsFn,
         }),
-      { name: 'base fast-forward', progress },
-    );
-  } finally {
-    if (lock.acquired) lock.release();
-  }
+      { name: 'follow-up capture', progress },
+    ),
+    step(
+      () =>
+        stepStatusResync({
+          storyId,
+          provider,
+          config,
+          progress,
+          reassertStatusColumnFn,
+        }),
+      { name: 'status-column resync', progress },
+    ),
+    step(
+      () =>
+        stepPlanRunLabelReap({
+          storyId,
+          provider,
+          progress,
+          reapPlanRunLabelsForStoryFn,
+        }),
+      { name: 'plan-run label reap', progress },
+    ),
+    step(
+      () =>
+        stepEpicRollup({
+          storyId,
+          provider,
+          config,
+          progress,
+          rollUpEpicForStoryFn,
+        }),
+      { name: 'epic rollup', progress },
+    ),
+    runLockedLocalSteps({
+      storyId,
+      storyBranch,
+      baseBranch,
+      cwd,
+      config,
+      progress,
+      gitSpawnFn,
+      planFastForwardFn,
+      executeFastForwardFn,
+      acquireLockWithWaitFn,
+    }),
+  ]);
+  const { refCleanup, baseFastForward } = local;
 
   // After every step that reads the temp artifacts; `signals.ndjson` survives.
   const tempPurge = await step(

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

@@ -33,6 +33,7 @@ import { runConfirmMergePhase } from './phases/confirm-merge.js';
 import { runGraphqlPreflight } from './phases/graphql-preflight.js';
 import { lockWaitPending } from './phases/lock-wait-pending.js';
 import { parseCloseOptions, resolveWaitForMerge } from './phases/options.js';
+import { runPostLandTail } from './phases/post-land.js';
 import { ensurePullRequestWith } from './phases/pull-request.js';
 import { pushStoryBranch } from './phases/push.js';
 import { handleCriticalReviewBlock } from './phases/review-block.js';
@@ -42,12 +43,54 @@ import { runWrongTreeGuardPhase } from './phases/wrong-tree-guard.js';
 
 const progress = Logger.createProgress('single-story-close', { stderr: true });
 
+/**
+ * Wall-clock seconds per named phase; each transition logs the phase it ends.
+ *
+ * @param {() => number} [nowMs]
+ */
+function createPhaseTimer(nowMs = Date.now) {
+  const durations = {};
+  let current = null;
+  let since = 0;
+  const end = () => {
+    if (current === null) return;
+    const seconds = Math.round((nowMs() - since) / 100) / 10;
+    durations[current] = (durations[current] ?? 0) + seconds;
+    progress('TIMING', `⏱  ${current}: ${seconds}s`);
+    current = null;
+  };
+  return {
+    enter(phase) {
+      end();
+      if (phase === 'init') return;
+      current = phase;
+      since = nowMs();
+    },
+    finish() {
+      end();
+      return Object.keys(durations).length > 0 ? { ...durations } : null;
+    },
+    stamp(terminal) {
+      const phaseDurations = this.finish();
+      if (phaseDurations) terminal.phaseDurations = phaseDurations;
+    },
+  };
+}
+
+const UNTIMED = Object.freeze({ stamp() {} });
+
 /**
  * The single terminal writer: the result summary, the envelope callers parse,
  * and terminal friction — so no ending can forget one. Must be awaited: the
  * CLI `process.exit`s as soon as `main` resolves.
  */
-async function emitTerminal({ terminal, result, config }) {
+async function emitTerminal({
+  terminal,
+  result,
+  config,
+  phaseTimer = UNTIMED,
+}) {
+  phaseTimer.stamp(terminal);
   if (result) {
     emitTerseResult({
       label: 'STORY CLOSE RESULT',
@@ -516,8 +559,10 @@ export async function runSingleStoryClose({
   // builds the `failed` envelope from those tags.
   let phase = 'init';
   let observedGates = null;
+  const phaseTimer = createPhaseTimer();
   const setPhase = (next) => {
     phase = next;
+    phaseTimer.enter(next);
   };
   const setObservedGates = (gates) => {
     observedGates = gates;
@@ -527,6 +572,7 @@ export async function runSingleStoryClose({
       options,
       setPhase,
       setObservedGates,
+      phaseTimer,
       injectedProvider,
       injectedConfig,
       injectedNotify,
@@ -539,6 +585,7 @@ export async function runSingleStoryClose({
     });
   } catch (err) {
     if (err && typeof err === 'object') {
+      err.closePhaseDurations = phaseTimer.finish();
       if (!err.closePhase) err.closePhase = phase;
       if (!err.closeGates && observedGates) err.closeGates = observedGates;
     }
@@ -617,6 +664,10 @@ async function finishWithMergeWait(prCtx, deps) {
     progress,
     injectedGh: deps.injectedGh,
     injectedNotify: deps.injectedNotify,
+    runPostLandTailFn: (args) => {
+      deps.setPhase('post-land');
+      return runPostLandTail(args);
+    },
   });
   const terminal = terminalFromWaitOutcome({
     waitOutcome,
@@ -650,7 +701,12 @@ async function finishWithMergeWait(prCtx, deps) {
     }),
     landCompleted: waitOutcome.confirmed === true,
   });
-  await emitTerminal({ terminal, result, config: prCtx.config });
+  await emitTerminal({
+    terminal,
+    result,
+    config: prCtx.config,
+    phaseTimer: prCtx.phaseTimer,
+  });
   reportWaitTerminal(terminal, { storyId: prCtx.storyId, prUrl: prCtx.prUrl });
   return { success: terminal.status === 'landed', result, terminal };
 }
@@ -698,7 +754,12 @@ async function finishWithoutMergeWait(prCtx, waitForMergeReason) {
     nextCommand: NEXT_COMMANDS.confirmMerge(prCtx.storyId),
     elapsedSeconds: elapsedSecondsSince(prCtx.startedAtMs),
   });
-  await emitTerminal({ terminal, result, config: prCtx.config });
+  await emitTerminal({
+    terminal,
+    result,
+    config: prCtx.config,
+    phaseTimer: prCtx.phaseTimer,
+  });
   progress(
     'DONE',
     `✅ Story #${prCtx.storyId}: PR ready → ${prCtx.prUrl} (${waitForMergeReason})`,
@@ -714,13 +775,16 @@ async function finishWithoutMergeWait(prCtx, waitForMergeReason) {
  *   config: object, startedAtMs: number }} ctx
  * @returns {Promise<{ success: false, result: object, terminal: object }>}
  */
-async function finishDeferred(lockWait, { config, startedAtMs, ...ids }) {
+async function finishDeferred(
+  lockWait,
+  { config, startedAtMs, phaseTimer, ...ids },
+) {
   const { result, terminal, note } = lockWaitPending({
     ...ids,
     lockWait,
     elapsedSeconds: elapsedSecondsSince(startedAtMs),
   });
-  await emitTerminal({ terminal, result, config });
+  await emitTerminal({ terminal, result, config, phaseTimer });
   progress('PENDING', note);
   return { success: false, result, terminal };
 }
@@ -759,6 +823,7 @@ async function runClosePipeline({
   options,
   setPhase,
   setObservedGates,
+  phaseTimer,
   injectedProvider,
   injectedConfig,
   injectedNotify,
@@ -848,6 +913,7 @@ async function runClosePipeline({
       baseBranch,
       config,
       startedAtMs,
+      phaseTimer,
     });
   }
 
@@ -943,6 +1009,7 @@ async function runClosePipeline({
     directMerged,
     config,
     startedAtMs,
+    phaseTimer,
     lockWait: prePush.lockWait,
     gates: closeEnvelopeGates(options, prePush.validationGates, reviewOverride),
   };

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

@@ -3,23 +3,20 @@
  * maker-blind `runCodeReview` invocation out of any phase file.
  */
 
-import { countChangedLines } from '../../../audit-suite/index.js';
 import { gitSpawn } from '../../../git-utils.js';
-import { appendFindingsYield } from '../../../observability/metrics-ledger.js';
 import { computeChangeSet } from '../../change-set.js';
 import { runCodeReview } from '../../code-review.js';
-import { runLocalLensReview } from './local-lens-review.js';
 
 /**
- * Run the local-lens pass and `runCodeReview` over one change set and return
- * the review result. Throws propagate; the caller picks the advisory posture.
- * Review depth is derived by `runCodeReview` from the changed files and is
- * input-only — it never alters the output envelope.
+ * Run `runCodeReview` over one change set and return the review result.
+ * Throws propagate; the caller picks the advisory posture. Review depth is
+ * derived by `runCodeReview` from the changed files and is input-only — it
+ * never alters the output envelope.
  *
- * The diff is enumerated exactly once here and injected into both consumers,
- * so lens roster and review depth agree on what changed even if a commit
- * lands in between. An unenumerable diff injects `null` ("already tried"),
- * which both consumers honour without re-spawning git.
+ * The diff is enumerated exactly once here and injected into the review, so
+ * review depth scores the same file set the change set names even if a
+ * commit lands in between. An unenumerable diff injects `null` ("already
+ * tried"), which the review honours without re-spawning git.
  *
  * @param {{
  *   storyId: number|string,
@@ -32,12 +29,9 @@ import { runLocalLensReview } from './local-lens-review.js';
  *   gitSpawnFn?: import('../../change-set.js').GitSpawnFn,
  *   computeChangeSetFn?: typeof computeChangeSet,
  *   runCodeReviewFn?: typeof runCodeReview,
- *   runLocalLensReviewFn?: typeof runLocalLensReview,
- *   countChangedLinesFn?: typeof countChangedLines,
- *   appendFindingsYieldFn?: typeof appendFindingsYield,
  * }} args
- * @returns {Promise<object>} The `runCodeReview` result plus
- *   `localLensReview` and the computed `changeSet`.
+ * @returns {Promise<object>} The `runCodeReview` result plus the computed
+ *   `changeSet`.
  */
 export async function runStoryReviewCore({
   storyId,
@@ -50,24 +44,12 @@ export async function runStoryReviewCore({
   gitSpawnFn = gitSpawn,
   computeChangeSetFn = computeChangeSet,
   runCodeReviewFn = runCodeReview,
-  runLocalLensReviewFn = runLocalLensReview,
-  countChangedLinesFn = countChangedLines,
-  appendFindingsYieldFn = appendFindingsYield,
 }) {
-  const storyIdNum = Number(storyId);
-
   const changeSet = computeChangeSetFn({ baseRef, headRef, gitSpawnFn });
 
-  // Line count for the lens diff-floor, probed only for a non-empty file set;
-  // `null` = unknown, and the floor fails open.
-  const changedLineCount =
-    Array.isArray(changeSet.files) && changeSet.files.length > 0
-      ? countChangedLinesFn({ baseRef, headRef, gitSpawnFn })
-      : null;
-
   const opts = {
     scope: 'story',
-    ticketId: storyIdNum,
+    ticketId: Number(storyId),
     baseRef,
     headRef,
     provider,
@@ -82,63 +64,6 @@ export async function runStoryReviewCore({
     opts.commentTargetId = commentTargetId;
   }
 
-  const localLensReview = await runLocalLensReviewFn({
-    baseRef,
-    headRef,
-    changedFiles: changeSet.files,
-    changedLineCount,
-    storyId: storyIdNum,
-    progress,
-    progressTag,
-    gitSpawnFn,
-  });
-
   const result = await runCodeReviewFn(opts);
-
-  // Best-effort findings-yield ledger, for tuning the roster on measurement.
-  try {
-    const yieldEntries = buildLensYieldEntries(localLensReview);
-    if (yieldEntries !== null) {
-      await appendFindingsYieldFn({
-        storyId: storyIdNum,
-        cli: 'story-close-review',
-        lenses: yieldEntries,
-        diffFloor: localLensReview?.floorSkip ?? null,
-      });
-    }
-  } catch (err) {
-    progress(
-      progressTag,
-      `⚠️ findings-yield ledger append failed (continuing): ${err?.message ?? err}`,
-    );
-  }
-
-  return { ...result, localLensReview, changeSet };
-}
-
-/**
- * One findings-yield entry per matched lens; `null` for an empty roster.
- *
- * @param {object|null|undefined} localLensReview
- * @returns {Array<{ lens: string, findings: number, skippedByFloor: boolean }>|null}
- */
-function buildLensYieldEntries(localLensReview) {
-  const lenses = Array.isArray(localLensReview?.lenses)
-    ? localLensReview.lenses.filter((l) => typeof l === 'string' && l.length)
-    : [];
-  if (lenses.length === 0) return null;
-  const skippedByFloor = localLensReview?.floorSkip?.skip === true;
-  const findingsByLens = new Map();
-  for (const finding of localLensReview?.materialized?.findings ?? []) {
-    if (typeof finding?.audit !== 'string') continue;
-    findingsByLens.set(
-      finding.audit,
-      (findingsByLens.get(finding.audit) ?? 0) + 1,
-    );
-  }
-  return lenses.map((lens) => ({
-    lens,
-    findings: skippedByFloor ? 0 : (findingsByLens.get(lens) ?? 0),
-    skippedByFloor,
-  }));
+  return { ...result, changeSet };
 }

package/.agents/scripts/lib/orchestration/story-deliver-terminal.js

@@ -116,6 +116,7 @@ function compact(obj) {
  * @param {object|null} [args.waitBudget]
  * @param {{ waitedSeconds: number, expired: boolean }|null} [args.lockWait]
  *   Full-suite lock wait; `waitBudget` is merge-wait only.
+ * @param {Record<string, number>|null} [args.phaseDurations] Seconds per phase.
  * @param {string} [args.timestamp]
  * @param {{ schema: object|null, error: string|null }} [args.schemaSource]
  *   Test seam.
@@ -137,6 +138,7 @@ export function buildTerminalEnvelope({
   elapsedSeconds = 0,
   waitBudget,
   lockWait,
+  phaseDurations,
   timestamp = new Date().toISOString(),
   schemaSource,
 }) {
@@ -158,6 +160,7 @@ export function buildTerminalEnvelope({
     elapsedSeconds: Math.max(0, Number(elapsedSeconds) || 0),
     waitBudget: waitBudget ?? null,
     lockWait: lockWait ?? null,
+    phaseDurations,
     timestamp,
   });
 

package/.agents/scripts/lib/templates/decomposer-prompts.js

@@ -31,13 +31,11 @@ export function renderStoryAuthorCore() {
     (lint) =>
       `- **${lint.id}** — ${lint.summary} Example: \`${lint.goodExample}\``,
   ).join('\n');
-  return `You are an expert Senior Project Manager and Orchestrator.
-Your job is to turn a plan seed / Tech Spec into a Story ticket array for an AI Agent to execute.
+  return `Turn a plan seed / Tech Spec into Story tickets for an AI agent to execute. The emitted stories template (see STORY BODY SCHEMA) is the ticket shape.
 
 ### HIERARCHY RULES (v2 default-single):
 1. **Emit exactly one Story by default.** Split into N>1 only when pieces have near-zero overlap or sit across an architectural seam. Coupled work stays one Story — put intra-session checkpoints in \`## Slicing\` and fold the Tech Spec into \`## Spec\`.
 2. **Stories**: Specific user-facing or architectural capabilities (e.g., "Implement JWT Token Exchange").
-   - There is NO Epic parent ticket, NO Feature tier, and NO Task layer.
    - **Story-Level Execution**: Each Story is executed end-to-end on a single branch by a single agent. Acceptance criteria and verification commands live as top-level \`acceptance[]\` / \`verify[]\` arrays on the Story ticket (see STORY BODY SCHEMA below).
    - Thematic grouping is prose in the Story's folded \`## Spec\` / \`## Slicing\`, never sibling tickets for coupled work.
 
@@ -46,27 +44,10 @@ Your job is to turn a plan seed / Tech Spec into a Story ticket array for an AI
 - \`labels[]\` is **optional**. Emit it only to request an *additional* label; persist sanitizes the list before applying it.
 - Do **not** emit \`agent::*\` labels — lifecycle state is runtime-owned, and persist applies \`agent::ready\` itself once every checkpoint is on the ticket.
 
-### OUTPUT FORMAT:
-You MUST respond ONLY with a valid JSON array of objects. No prose, no markdown blocks.
-
-### JSON SCHEMA:
-[
-  {
-    "slug": "hyphen-case-id",
-    "type": "story",
-    "title": "Short descriptive title",
-    "body": <string — see STORY BODY SCHEMA below>,
-    "acceptance": ["<outcome a PR reviewer can confirm>", ...],
-    "verify": ["<exact command or test path>", ...],
-    "labels": ["<extra-label>"] (optional — type::story is applied automatically; omit this field unless you need an additional label),
-    "depends_on": ["slug-of-blocking-dependency"] (optional array of Story slugs that block execution)
-  }
-]
-
 **Slug format**: \`^[a-z0-9][a-z0-9-]*$\` — hyphen-case only. Underscores are rejected by the validator.
 
 ### STORY BODY SCHEMA (REQUIRED FOR EVERY STORY):
-\`body\` is either the serialized markdown **string** (the section format below) or a **structured object** carrying the same fields (\`goal\`, optional \`slicing\` / \`spec\`, \`changes\`, optional \`non_goals\`) — persist parses either shape and serializes the canonical markdown itself, so you never need to read \`story-body.js\` or hand-assemble the markdown (the \`stories.template.json\` file emitted next to the plan-context envelope is a ready-to-fill structured-object skeleton). Stories are consumed by non-interactive sub-agents that must self-verify from the Story ticket alone — so the ticket must carry everything an agent needs to execute and self-verify.
+\`body\` is either the serialized markdown **string** (the section format below) or a **structured object** carrying the same fields (\`goal\`, optional \`slicing\` / \`spec\`, \`changes\`, optional \`non_goals\`) — persist parses either shape and serializes the canonical markdown itself, so you never need to read \`story-body.js\` or hand-assemble the markdown (the \`stories.template.json\` file emitted next to the plan-context envelope is a ready-to-fill structured-object skeleton). The executing sub-agent is non-interactive and self-verifies from the ticket alone, so the ticket carries everything it needs.
 
 The \`acceptance[]\` and \`verify[]\` arrays live at the **top level** of the Story ticket object — that is the machine contract the validator reads. Author each list **once, at top level**, and **omit** the \`## Acceptance\` / \`## Verify\` sections from the authored \`body\` string: persist syncs the top-level arrays into those sections so the GitHub issue stays a complete executable document. The validator resolves both fields from the top level, so an omitted section is the expected shape, not a violation.
 
@@ -153,9 +134,9 @@ ${envelopeFloor}
 - A Story touching UI (\`*.tsx\`, \`*.astro\`, \`*.svelte\`, \`*.vue\`, a components folder) states the \`data-testid\` contract in \`acceptance[]\` per the testid contract in \`.agents/skills/stack/qa/playwright/SKILL.md\`.
 - A Story touching user-visible copy, brand assets or visual style cites the relevant section of \`docs/style-guide.md\` in \`acceptance[]\` when that file exists.
 
-CRITICAL: Dependencies should follow execution blockers. There is no parent ticket — never emit a 'parent_slug' field.
-IMPORTANT DEPENDENCY RULE: Story-to-Story dependencies are expressed via \`depends_on\` (one Story depends_on another Story's slug). Use this to express execution ordering across the plan.
-**Never stop mid-array.** Always emit complete JSON — partial arrays are rejected by the validator.`;
+#### ORDERING:
+
+Express execution ordering between Stories with \`depends_on\` — the slugs of the Stories that must land first. Never emit a parent field.`;
 }
 
 /**

package/.agents/scripts/pr-watch-with-update.js

@@ -20,6 +20,7 @@ import { runAsCli } from './lib/cli-utils.js';
 import { resolveConfig } from './lib/config-resolver.js';
 import { gh as defaultGh } from './lib/gh-exec.js';
 import { Logger } from './lib/Logger.js';
+import { recordRequiredRed } from './lib/orchestration/ci-red-handling.js';
 import {
   blockStoryDelivery,
   classifyFailure,
@@ -229,25 +230,18 @@ async function handleRedWatch({
   blockFn,
   logger,
 }) {
-  const disarm = await disarmFn({ prRef });
-  const scope = resolveDigestScope({ storyId });
-  const headSha = scope ? headShaFn({ prRef, cwd }) : null;
-  let digestPaths = null;
-  try {
-    digestPaths = writeDigestFn({
-      storyId,
-      prNumber,
-      headSha,
-      failures,
-      tempRoot,
-      cwd,
-      prRef,
-    });
-  } catch (err) {
-    logger.warn?.(
-      `[pr-watch] failed to write CI digest (non-fatal): ${err?.message ?? err}`,
-    );
-  }
+  const { headSha, disarm, digestPaths } = await recordRequiredRed({
+    storyId,
+    prNumber,
+    prRef,
+    failures,
+    tempRoot,
+    cwd,
+    disarmFn,
+    headShaFn,
+    writeDigestFn,
+    logger,
+  });
   let blocked = false;
   if (!disarm.disarmed) {
     logger.error?.(