mandrel 2.63.0 → 2.64.0

package/.agents/scripts/lib/orchestration/ci-red-handling.js

@@ -0,0 +1,73 @@
+// .agents/scripts/lib/orchestration/ci-red-handling.js
+/**
+ * ci-red-handling.js — the first-red half of the no-rerun guard in
+ * `rules/ci-remediation.md` § Verifier, shared by every path that observes a
+ * red required check: the watcher (`pr-watch-with-update.js`) and the
+ * close-and-land merge wait's `checks-failed` fail-fast. The digest itself
+ * lives in `ci-rerun-guard.js`.
+ */
+
+import { Logger } from '../Logger.js';
+import {
+  resolveDigestScope,
+  resolvePrHeadSha,
+  writeCiDigest,
+} from './ci-rerun-guard.js';
+
+/**
+ * The first-red handling every required-check red goes through — the
+ * watcher's red path and the close's `checks-failed` fail-fast alike: disarm
+ * auto-merge FIRST (the race-free moment), then write the digest keyed to the
+ * red head SHA. One implementation, so the guard cannot drift per path.
+ * Never throws: a digest-write failure is returned as `digestError`.
+ *
+ * @param {object} opts
+ * @param {number|string|null} [opts.storyId]
+ * @param {number} opts.prNumber
+ * @param {string} opts.prRef
+ * @param {Array<{name:string, outcome:string}>} opts.failures
+ * @param {string} opts.tempRoot
+ * @param {string} opts.cwd
+ * @param {(args: { prRef: string }) => Promise<{ disarmed: boolean, alreadyUnarmed?: boolean, detail: string }>} opts.disarmFn
+ * @param {string|null} [opts.headSha] Already-observed head SHA; probed when absent.
+ * @param {Function} [opts.headShaFn]
+ * @param {Function} [opts.writeDigestFn]
+ * @param {object} [opts.logger]
+ * @returns {Promise<{ headSha: string|null, disarm: object, digestPaths: { jsonPath: string, mdPath: string }|null, digestError: string|null }>}
+ */
+export async function recordRequiredRed({
+  storyId = null,
+  prNumber,
+  prRef,
+  failures,
+  tempRoot,
+  cwd,
+  disarmFn,
+  headSha = null,
+  headShaFn = resolvePrHeadSha,
+  writeDigestFn = writeCiDigest,
+  logger = Logger,
+}) {
+  const disarm = await disarmFn({ prRef });
+  const scope = resolveDigestScope({ storyId });
+  const redHeadSha = scope ? (headSha ?? headShaFn({ prRef, cwd })) : null;
+  let digestPaths = null;
+  let digestError = null;
+  try {
+    digestPaths = writeDigestFn({
+      storyId,
+      prNumber,
+      headSha: redHeadSha,
+      failures,
+      tempRoot,
+      cwd,
+      prRef,
+    });
+  } catch (err) {
+    digestError = String(err?.message ?? err);
+    logger?.warn?.(
+      `[ci-rerun-guard] failed to write CI digest (non-fatal): ${digestError}`,
+    );
+  }
+  return { headSha: redHeadSha, disarm, digestPaths, digestError };
+}

package/.agents/scripts/lib/orchestration/deliver-recover.js

@@ -13,7 +13,11 @@ import {
 } from '../config/temp-paths.js';
 import { gh as defaultGh } from '../gh-exec.js';
 import { gitSpawn as defaultGitSpawn, getStoryBranch } from '../git-utils.js';
-import { deriveChecksStatus, isPrMerged } from './merge-poll.js';
+import {
+  CHECKS_FAILED_CLASS,
+  deriveChecksStatus,
+  isPrMerged,
+} from './merge-poll.js';
 import { NEXT_COMMANDS } from './story-deliver-terminal.js';
 import { STATE_LABELS } from './ticketing.js';
 
@@ -302,6 +306,56 @@ function decideExecuting({ storyId, branch, pr, closeArtifacts, evidence }) {
   };
 }
 
+/**
+ * A close that blocked on a red required check disarmed auto-merge and wrote
+ * the CI digest, so the next step is the ci-remediation loop — never this
+ * probe again. `null` for every other blocked class (or with no PR to watch).
+ *
+ * @returns {{ shape: string, nextCommand: string, detail: string, evidence: string[] } | null}
+ */
+function decideBlockedChecksFailed({ storyId, pr, closeArtifacts, evidence }) {
+  const envelope = closeArtifacts?.envelope;
+  if (envelope?.blocked?.blockClass !== CHECKS_FAILED_CLASS) return null;
+  const prNumber = pr?.number ?? envelope?.pr?.number ?? null;
+  if (!prNumber) return null;
+  return {
+    shape: 'blocked-checks-failed',
+    nextCommand: NEXT_COMMANDS.watchCi(storyId, prNumber),
+    detail:
+      `Story is \`agent::blocked\` because a required check on PR #${prNumber} went red. ` +
+      `The close disarmed auto-merge and wrote the CI digest ` +
+      `(\`story-${storyId}-ci-digest.json\` under the configured tempRoot). Per ` +
+      `\`.agents/rules/ci-remediation.md\`, either fix the failure at source and push a new ` +
+      `commit on \`story-${storyId}\`, or — when the root cause is outside this delivery — run ` +
+      `\`node .agents/scripts/file-ci-gap.js --story ${storyId} --pr ${prNumber} --verdict <verdict> ` +
+      `--owner <consumer|framework|platform> --evidence "<proof reading>"\`. Then run the watcher: ` +
+      `a green on a new head SHA, or the one rerun a filed capacity / unreproducible-tier verdict ` +
+      `admits, re-arms auto-merge.`,
+    evidence,
+  };
+}
+
+/**
+ * A blocked Story: the checks-failed route when it applies, else the
+ * class-specific remediation the friction comment already carries.
+ *
+ * @returns {{ shape: string, nextCommand: string, detail: string, evidence: string[] }}
+ */
+function decideBlocked({ storyId, pr, closeArtifacts, evidence }) {
+  return (
+    decideBlockedChecksFailed({ storyId, pr, closeArtifacts, evidence }) ?? {
+      shape: 'blocked',
+      nextCommand: NEXT_COMMANDS.recover(storyId),
+      detail:
+        `Story is at \`agent::blocked\`. The block was already classified when it was ` +
+        `filed — read the \`friction\` comment on #${storyId} for the class-specific ` +
+        `remediation, resolve it, then transition back to \`agent::executing\`. ` +
+        `Re-run this probe afterwards to confirm the strand cleared.`,
+      evidence,
+    }
+  );
+}
+
 /**
  * The pure decision table: exactly one verdict, never a list.
  *
@@ -357,16 +411,7 @@ export function decideRecovery({
   }
 
   if (label === STATE_LABELS.BLOCKED) {
-    return {
-      shape: 'blocked',
-      nextCommand: NEXT_COMMANDS.recover(storyId),
-      detail:
-        `Story is at \`agent::blocked\`. The block was already classified when it was ` +
-        `filed — read the \`friction\` comment on #${storyId} for the class-specific ` +
-        `remediation, resolve it, then transition back to \`agent::executing\`. ` +
-        `Re-run this probe afterwards to confirm the strand cleared.`,
-      evidence,
-    };
+    return decideBlocked({ storyId, pr, closeArtifacts, evidence });
   }
 
   if (label === STATE_LABELS.DONE) {

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

@@ -27,6 +27,7 @@ import {
 import { pollUntil } from '../../../util/poll-loop.js';
 import { applyBehindUpdate } from '../../behind-recovery.js';
 import { isRerunPermitted } from '../../check-state.js';
+import { recordRequiredRed as defaultRecordRequiredRed } from '../../ci-red-handling.js';
 import {
   emitMergeFlipFailed as defaultEmitMergeFlipFailed,
   MERGED_FLIP_FAILED_BLOCK_CLASS,
@@ -36,6 +37,7 @@ import { classifyMergeBlock as defaultClassifyMergeBlock } from '../../merge-blo
 import {
   ADVISORY_GATE_INCONCLUSIVE_CLASS,
   ADVISORY_GATE_RED_CLASS,
+  CHECKS_FAILED_CLASS,
   DEFAULT_INTERVAL_SECONDS,
   DEFAULT_MAX_BUDGET_SECONDS,
   decideAdvisoryGateBlock,
@@ -297,14 +299,9 @@ function advisoryGateRemedy({ storyId, blockClass }) {
  * @param {{ storyId: number, prNumber: number|null, blockClass: string }} args
  * @returns {string}
  */
-function unlandedRemedy({ storyId, prNumber, blockClass }) {
-  if (blockClass === 'checks-failed') {
-    return (
-      `A required check is **red**. Fix the failure and push a new commit on \`story-${storyId}\`; ` +
-      `the red disarms auto-merge, and only a green on a new head SHA re-arms it — ` +
-      `re-running the failed job is forbidden. Watch the checks with:\n\n` +
-      `\`\`\`bash\n${NEXT_COMMANDS.watchCi(storyId, prNumber)}\n\`\`\``
-    );
+function unlandedRemedy({ storyId, prNumber, blockClass, redRecord }) {
+  if (blockClass === CHECKS_FAILED_CLASS) {
+    return checksFailedRemedy({ storyId, prNumber, redRecord });
   }
   if (
     blockClass === ADVISORY_GATE_INCONCLUSIVE_CLASS ||
@@ -319,6 +316,35 @@ function unlandedRemedy({ storyId, prNumber, blockClass }) {
   );
 }
 
+/**
+ * States what the red handling actually did — never claims a disarm or a
+ * digest that did not happen — then names both ci-remediation routes.
+ *
+ * @param {{ storyId: number, prNumber: number|null, redRecord?: object }} args
+ * @returns {string}
+ */
+function checksFailedRemedy({ storyId, prNumber, redRecord }) {
+  const disarm = redRecord?.disarm;
+  const armLine = disarm?.disarmed
+    ? disarm.alreadyUnarmed
+      ? 'Auto-merge was already un-armed.'
+      : 'Auto-merge was **disarmed**; only a green on a new head SHA, or the one rerun a filed `capacity` / `unreproducible-tier` verdict admits, re-arms it.'
+    : `⚠️ Auto-merge could **not** be disarmed (${disarm?.detail ?? 'the red handling did not run'}) — GitHub may still land the PR when the checks read green. Disarm it by hand.`;
+  const watch = NEXT_COMMANDS.watchCi(storyId, prNumber);
+  const digestLine = redRecord?.digestPaths
+    ? `CI digest (run link + failure signature): \`${redRecord.digestPaths.jsonPath}\`.`
+    : `⚠️ No CI digest was written (${redRecord?.digestError ?? 'no Story scope'}); \`${watch}\` rewrites it.`;
+  return (
+    `A required check is **red**. ${armLine}\n\n${digestLine}\n\n` +
+    `Per \`.agents/rules/ci-remediation.md\`, either fix the failure and push a new commit on ` +
+    `\`story-${storyId}\` (re-running the failed job is forbidden), or — when the root cause is ` +
+    `outside this delivery — file it:\n\n` +
+    `\`\`\`bash\nnode .agents/scripts/file-ci-gap.js --story ${storyId} --pr ${prNumber} ` +
+    `--verdict <verdict> --owner <consumer|framework|platform> --evidence "<proof reading>"\n\`\`\`\n\n` +
+    `Then watch the checks with:\n\n\`\`\`bash\n${watch}\n\`\`\``
+  );
+}
+
 function formatUnlandedFriction({
   storyId,
   prNumber,
@@ -326,12 +352,13 @@ function formatUnlandedFriction({
   blockClass,
   reason,
   elapsedSeconds,
+  redRecord,
 }) {
   const prLabel =
     Number.isInteger(prNumber) && prNumber > 0
       ? `PR #${prNumber}${prUrl ? ` (${prUrl})` : ''}`
       : (prUrl ?? 'the PR');
-  const remedy = unlandedRemedy({ storyId, prNumber, blockClass });
+  const remedy = unlandedRemedy({ storyId, prNumber, blockClass, redRecord });
   return (
     `### close-and-land: merge did not land\n\n` +
     `Story #${storyId}: the close polled ${prLabel} for merge confirmation and ` +
@@ -691,6 +718,61 @@ function queuedExhaustionVerdict(probe, cumulativeMs) {
   };
 }
 
+/**
+ * A `checks-failed` fail-fast is a required-check red, so it gets the same
+ * first-red handling as the watcher: disarm, then write the CI digest
+ * `file-ci-gap.js` reads. Never throws — the block stands regardless.
+ *
+ * @returns {Promise<object>} the `recordRequiredRed` outcome.
+ */
+async function recordChecksFailedRed({
+  storyId,
+  prNumber,
+  probe,
+  cwd,
+  config,
+  gh,
+  progress,
+  disarmAutoMergeFn,
+  recordRequiredRedFn,
+}) {
+  const failures = (probe?.redHeadRuns ?? []).map((run) => ({
+    name: run.name ?? 'unknown',
+    outcome: String(run.conclusion ?? 'failure').toLowerCase(),
+  }));
+  try {
+    const record = await recordRequiredRedFn({
+      storyId,
+      prNumber,
+      prRef: String(prNumber),
+      failures,
+      tempRoot: config?.project?.paths?.tempRoot ?? 'temp',
+      cwd,
+      headSha: probe?.headSha ?? null,
+      disarmFn: () => disarmAutoMergeFn({ prNumber, gh, progress }),
+    });
+    if (record.digestPaths) {
+      progress?.(
+        'CONFIRM',
+        `🧾 CI failure digest → ${record.digestPaths.jsonPath}`,
+      );
+    }
+    return record;
+  } catch (err) {
+    const detail = String(err?.message ?? err);
+    progress?.(
+      'CONFIRM',
+      `⚠️ Red-check handling failed (continuing to block): ${detail}`,
+    );
+    return {
+      headSha: probe?.headSha ?? null,
+      disarm: { disarmed: false, alreadyUnarmed: false, detail },
+      digestPaths: null,
+      digestError: detail,
+    };
+  }
+}
+
 /** Classify, emit `merge.unlanded`, post friction, block — all best-effort. */
 async function blockOnUnlanded({
   storyId,
@@ -705,6 +787,7 @@ async function blockOnUnlanded({
   emitMergeUnlandedFn,
   blockClassOverride,
   reasonOverride,
+  redRecord,
 }) {
   // A verdict decided at detection is emitted as-is, never re-derived (the
   // classifier reads an advisory-gate PR as healthy); the classifier runs
@@ -757,6 +840,7 @@ async function blockOnUnlanded({
       blockClass,
       reason,
       elapsedSeconds,
+      redRecord,
     }),
     progress,
   });
@@ -781,6 +865,7 @@ async function blockOnUnlanded({
     reason,
     frictionCommentId,
     elapsedSeconds,
+    ...(redRecord ? { redRecord } : {}),
     // The envelope's `pr.state` / `pr.checksStatus` come from here.
     prProbe,
   };
@@ -933,6 +1018,8 @@ async function onMergeObserved({
  * @param {Function} [args.classifyMergeBlockFn]
  * @param {Function} [args.emitMergeUnlandedFn]
  * @param {Function} [args.runPostLandTailFn]
+ * @param {Function} [args.disarmAutoMergeFn]
+ * @param {Function} [args.recordRequiredRedFn] The shared first-red handling (disarm + CI digest).
  * @param {(ms: number) => Promise<void>} [args.sleepFn]
  * @param {() => number} [args.nowMsFn]
  * @param {number} [args.ghTimeoutMs] Test seam only, not config.
@@ -964,6 +1051,7 @@ export async function runConfirmMergePhase({
   emitMergeFlipFailedFn = defaultEmitMergeFlipFailed,
   runPostLandTailFn = defaultRunPostLandTail,
   disarmAutoMergeFn = disarmAutoMerge,
+  recordRequiredRedFn = defaultRecordRequiredRed,
   sleepFn = defaultSleep,
   nowMsFn = Date.now,
   ghTimeoutMs = MERGE_WAIT_GH_TIMEOUT_MS,
@@ -1127,6 +1215,17 @@ export async function runConfirmMergePhase({
           },
           blockClassOverride: decision.blockClass,
           reasonOverride: decision.reason,
+          redRecord: await recordChecksFailedRed({
+            storyId,
+            prNumber,
+            probe,
+            cwd,
+            config,
+            gh: injectedGh,
+            progress,
+            disarmAutoMergeFn,
+            recordRequiredRedFn,
+          }),
         };
       }
 

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?.(

package/docs/CHANGELOG.md

@@ -15,6 +15,13 @@ All notable changes to this project will be documented in this file.
 -->
 <!-- markdownlint-disable-file MD004 MD012 MD037 -->
 
+## [2.64.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.63.0...mandrel-v2.64.0) (2026-09-19)
+
+
+### Fixed
+
+* close-and-land: a checks-failed stop disarms auto-merge and writes the CI digest ([#5405](https://github.com/dsj1984/mandrel/issues/5405)) ([#5406](https://github.com/dsj1984/mandrel/issues/5406)) ([5819d52](https://github.com/dsj1984/mandrel/commit/5819d52a834a6973b3e138961d9735e477f6cb48))
+
 ## [2.63.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.62.0...mandrel-v2.63.0) (2026-09-18)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.63.0",
+  "version": "2.64.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",