mandrel 1.84.0 → 1.85.0

package/.agents/scripts/lib/orchestration/lifecycle/listeners/automerge-predicate.js

@@ -4,27 +4,41 @@
  * PR is safe to auto-merge after the required-check watch settles.
  * Story #2256 / Task #2260 (Epic #2172); inlined from the now-deleted
  * legacy `automerge-predicate` module in Story #2415 (Epic #2307).
+ * Rewritten in Story #4361 (Epic #4355) so green required CI is the
+ * arming signal, gated by the `delivery.ci.autoMerge` policy.
  *
  * Subscribes to:
  *   - `epic.automerge.start` (production path, Story #3901) → the
  *     `/deliver` Phase 8.5 boundary that the `lifecycle-emit.js`
  *     CLI actually fires. This event carries `prUrl` but NO
- *     `checkOutcomes` (Phase 8's `pr-watch-with-update.js` has already
- *     polled every required check to green before Phase 8.5 runs), so
- *     the CI-freshness gate is skipped and the verdict is decided by
- *     the structured-signal evaluator alone. Before Story #3901 the
- *     listener subscribed ONLY to `epic.watch.end`, which no production
- *     emitter fires — making the entire Phase 8.5 auto-merge gate a
- *     dead wire (epic-lifecycle-review.md §1.1).
+ *     `checkOutcomes`. Before Story #4361 the listener trusted Phase 8
+ *     (`pr-watch-with-update.js`) to have polled every required check to
+ *     green and therefore skipped any CI probe on this path. That left a
+ *     hole (Story #3901): if the Phase 8 watch was interrupted (host
+ *     crash, `/loop` handoff, operator resume) the predicate could arm
+ *     merge with red or pending required checks. Story #4361 closes it —
+ *     the listener now runs a LIVE `gh pr checks --required` probe on
+ *     `epic.automerge.start` and refuses to arm when any required check
+ *     is not green, regardless of what Phase 8 believed.
  *   - `epic.watch.end` (test-only `Watcher` path) → carries an
  *     all-settled `checkOutcomes` map. Any non-passing required check
  *     is a hard block evaluated BEFORE the structured-signal evaluator.
+ *     On this path the pre-supplied `checkOutcomes` map IS the CI truth,
+ *     so no live probe is issued (the map is authoritative).
  *
- * Either trigger evaluates the same verdict: if `evaluateAutoMergePredicate`
- * reports `clean: true` (no manual interventions, every Story done,
- * no story blockers, no critical/high review findings, machine-readable
- * "clean sprint" retro trailer), emit `epic.merge.ready`. Otherwise emit
- * `epic.merge.blocked` with a non-empty reason.
+ * Policy (`delivery.ci.autoMerge`, Story #4356 / #4361):
+ *   - `"trust-ci"` (framework default) — green required CI is the arming
+ *     signal. The ONLY structured conditions that block arming are an
+ *     unresolved 🔴 critical (red) code-review finding or an
+ *     `agent::blocked` state (a story-level blocker recorded in
+ *     run-state, or a missing run-state checkpoint we cannot certify).
+ *     Manual interventions, 🟠 warning-level findings, and a non-clean
+ *     retro are RECORDED for audit (surfaced on the verdict and the
+ *     classification log) but no longer block the merge.
+ *   - `"strict"` — restores the prior clean-sprint predicate EXACTLY:
+ *     zero manual interventions, every Story done, no story blockers,
+ *     no 🔴/🟠 review findings, and a machine-readable `cleanSprint`
+ *     retro trailer. Any dirty signal blocks.
  *
  * Code-review parse-miss policy (Story #4222): a code-review comment that is
  * present but whose severity bullets cannot be parsed is treated as a DISTINCT
@@ -32,22 +46,8 @@
  * rather than blocking. Failing closed on a format miss is indistinguishable,
  * to the operator and to downstream telemetry, from a real disqualifying
  * finding; a parser miss must never masquerade as "the signal said no" inside
- * a generic `epic.merge.blocked`. Genuine critical/high findings still block,
- * because those require the counts to have parsed.
- *
- * Critical contract:
- *   - The verdict for any given input set is byte-identical to the
- *     pre-inlining legacy module's output — this file is its
- *     replacement. The merge-gate-ordering invariant
- *     (`epic.merge.armed` preceded by `epic.merge.ready`) depends on
- *     this listener being the sole emitter of `epic.merge.ready`.
- *
- *   - Required-check outcomes from `epic.watch.end` are a NEW input
- *     not present in the legacy verdict: any check that is not
- *     `'success'`, `'neutral'`, or `'skipped'` flips the verdict to
- *     `blocked` BEFORE the legacy evaluator is even consulted (because
- *     a red CI check is a hard block regardless of the structured
- *     signals).
+ * a generic `epic.merge.blocked`. Genuine critical/high findings still block
+ * (per policy), because those require the counts to have parsed.
  *
  * Idempotency contract (AC-10): per-instance `Set<string>` of
  * `${event}:${seqId}` keys. A repeat `(event, seqId)` short-circuits
@@ -55,15 +55,21 @@
  * on GitHub state, so re-running it is safe; the seqId guard is the
  * defence against double-emit.
  *
- * Side-effect firewall: the listener calls the read-only evaluator and
- * emits on the bus. It does NOT mutate labels, post comments, or call
- * `notify`. Downstream consumers (`AutomergeArmer` on
- * `epic.merge.ready`; LabelTransitioner / StructuredCommentPoster on
- * `epic.merge.blocked`) own those side effects.
+ * Side-effect firewall: the listener calls the read-only evaluator, runs
+ * the read-only `gh pr checks` probe, and emits on the bus. It does NOT
+ * mutate labels, post comments, or call `notify`. Downstream consumers
+ * (`AutomergeArmer` on `epic.merge.ready`; LabelTransitioner /
+ * StructuredCommentPoster on `epic.merge.blocked`) own those side
+ * effects. AutomergeArmer remains the SOLE site that shells `gh pr merge`
+ * (the merge-lockout lint in `check-lifecycle-lint.js` enforces this).
  */
 
+import { spawnSync } from 'node:child_process';
+
+import { getCiDelivery } from '../../../config/ci.js';
 import * as epicRunStateStore from '../../epic-run-state-store.js';
 import { findStructuredComment } from '../../ticketing.js';
+import { normalizeCheckState, RECOGNIZED_CHECK_STATES } from './watcher.js';
 
 /**
  * Outcomes that count as "this required check did not block the merge".
@@ -76,6 +82,41 @@ export const NON_FAILING_CHECK_OUTCOMES = Object.freeze(
   new Set(['success', 'neutral', 'skipped']),
 );
 
+/**
+ * Reason categories emitted by the structured-signal evaluator. The
+ * policy layer (`applyAutoMergePolicy`) decides which categories block
+ * arming under each `delivery.ci.autoMerge` posture. Pure constant —
+ * exported so the taxonomy is reviewable as code.
+ *
+ *   - `criticalReview` — an unresolved 🔴 critical (red) code-review
+ *     finding. Blocks under BOTH policies.
+ *   - `blockedState`   — an `agent::blocked` state (story-level blocker
+ *     recorded in run-state, non-done stories, or a missing run-state
+ *     checkpoint). Blocks under BOTH policies.
+ *   - `warningReview`  — a 🟠 warning-level (high-risk) code-review
+ *     finding. Blocks under `strict` only.
+ *   - `intervention`   — a recorded manual intervention. Blocks under
+ *     `strict` only.
+ *   - `retro`          — a non-clean / missing retro verdict trailer.
+ *     Blocks under `strict` only.
+ */
+export const REASON_CATEGORY = Object.freeze({
+  CRITICAL_REVIEW: 'criticalReview',
+  BLOCKED_STATE: 'blockedState',
+  WARNING_REVIEW: 'warningReview',
+  INTERVENTION: 'intervention',
+  RETRO: 'retro',
+});
+
+/**
+ * Categories that block arming under the default `"trust-ci"` policy.
+ * Everything else is recorded for audit but does not block. Pure —
+ * exported for tests.
+ */
+export const TRUST_CI_BLOCKING_CATEGORIES = Object.freeze(
+  new Set([REASON_CATEGORY.CRITICAL_REVIEW, REASON_CATEGORY.BLOCKED_STATE]),
+);
+
 /**
  * Regex that extracts the machine-readable auto-merge verdict trailer
  * emitted by the retro body composer (`retro/phases/compose-body.js`,
@@ -140,6 +181,111 @@ export function formatCheckFailureReason(failures) {
   return `required checks not green: ${parts.join(', ')}${suffix}`;
 }
 
+/**
+ * Default live `gh pr checks --required` probe. Mirrors the Watcher's
+ * spawn shape (`--json name,state,bucket,workflow`) so the required-set
+ * projection is identical. Pure-spawn helper — exported so tests can
+ * stub the shell-out. Returns the raw spawn envelope; the caller
+ * classifies the payload.
+ *
+ * @param {{ prUrl: string, cwd?: string, spawnFn?: typeof spawnSync }} opts
+ * @returns {{ status: number, stdout: string, stderr: string }}
+ */
+export function probeRequiredChecks({ prUrl, cwd, spawnFn = spawnSync }) {
+  const result = spawnFn(
+    'gh',
+    ['pr', 'checks', prUrl, '--required', '--json', 'name,state,bucket'],
+    { cwd, encoding: 'utf-8', shell: false },
+  );
+  return {
+    status: result.status ?? 1,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? '',
+  };
+}
+
+/**
+ * Classify a live `gh pr checks --required` probe envelope into a
+ * `{ ok, reason, outcomes }` verdict. Pure — exported for tests.
+ *
+ *   - `ok: true`  → every required check is green (non-failing) AND the
+ *     probe returned a parseable, non-empty required-check set.
+ *   - `ok: false` → at least one required check is not green, the probe
+ *     shelled out non-zero, or the payload could not be parsed. A probe
+ *     we cannot read is a hard block: we NEVER arm merge on an
+ *     unreadable CI signal (fail closed on the CI gate specifically —
+ *     the opposite of the code-review parse-miss policy, because CI
+ *     greenness is the whole point of the trust-ci arming signal).
+ *
+ * `gh pr checks --required` exits non-zero (status 8) when a required
+ * check has failed OR is still pending, so a non-zero status is treated
+ * as "not green" only when we cannot otherwise read a clean set from
+ * stdout. We parse stdout first (it is populated even on the non-zero
+ * exit) and classify from the outcomes.
+ *
+ * @param {{ status: number, stdout: string, stderr: string }} probe
+ * @returns {{ ok: boolean, reason: string|null, outcomes: Record<string, string> }}
+ */
+export function classifyRequiredChecksProbe(probe) {
+  const stdout = String(probe?.stdout ?? '').trim();
+  // Empty stdout with a non-zero status → probe genuinely failed (auth,
+  // network, no PR). Fail closed.
+  if (stdout.length === 0) {
+    return {
+      ok: false,
+      reason:
+        `live required-check probe failed (status=${probe?.status ?? 'unknown'})` +
+        (probe?.stderr ? `: ${String(probe.stderr).trim().slice(0, 200)}` : ''),
+      outcomes: {},
+    };
+  }
+  let entries;
+  try {
+    const parsed = JSON.parse(stdout);
+    entries = Array.isArray(parsed) ? parsed : null;
+  } catch {
+    entries = null;
+  }
+  if (!entries) {
+    return {
+      ok: false,
+      reason: 'live required-check probe returned an unparseable payload',
+      outcomes: {},
+    };
+  }
+  const outcomes = {};
+  for (const e of entries) {
+    if (e && typeof e === 'object' && typeof e.name === 'string') {
+      const raw = String(e.state || e.bucket || '')
+        .trim()
+        .toLowerCase();
+      // Fail closed on the arming probe: a token we have not enumerated
+      // could be a genuinely-failing GitHub conclusion. normalizeCheckState
+      // collapses unknowns to 'skipped' (safe for the watch path, unsafe
+      // here), so map an unrecognized token to 'unknown' — which is not in
+      // NON_FAILING_CHECK_OUTCOMES and therefore blocks arming.
+      outcomes[e.name] = RECOGNIZED_CHECK_STATES.has(raw)
+        ? normalizeCheckState(raw)
+        : 'unknown';
+    }
+  }
+  // An empty required set (no required checks configured) is treated as
+  // green — there is nothing to gate on. This matches branch protection
+  // that requires no status checks.
+  const failing = [];
+  for (const [name, outcome] of Object.entries(outcomes)) {
+    // `pending` is NOT in NON_FAILING — a still-running required check
+    // blocks arming (the Phase 8 watch was interrupted before green).
+    if (!NON_FAILING_CHECK_OUTCOMES.has(outcome)) {
+      failing.push({ name, outcome });
+    }
+  }
+  if (failing.length > 0) {
+    return { ok: false, reason: formatCheckFailureReason(failing), outcomes };
+  }
+  return { ok: true, reason: null, outcomes };
+}
+
 /**
  * Regex-parse the rendered severity bullets on the code-review markdown
  * body. Pure. Exported for tests.
@@ -165,16 +311,33 @@ export function parseSeverityCounts(body) {
   };
 }
 
+/**
+ * Push a categorized reason onto the reasons array. Each reason carries
+ * a `category` (from `REASON_CATEGORY`) so the policy layer can decide
+ * whether it blocks under the active posture, plus a human-facing
+ * `message`. Pure helper.
+ */
+function pushReason(reasons, category, message) {
+  reasons.push({ category, message });
+}
+
 function evaluateStateSignals(state, reasons) {
   const interventionCount = Array.isArray(state?.manualInterventions)
     ? state.manualInterventions.length
     : 0;
   if (!state) {
-    reasons.push(
+    // A missing checkpoint means we cannot certify the run at all — this
+    // is a blocked-state condition (we do not know whether a Story is
+    // blocked), so it blocks under BOTH policies.
+    pushReason(
+      reasons,
+      REASON_CATEGORY.BLOCKED_STATE,
       'epic-run-state checkpoint missing — cannot certify clean run',
     );
   } else if (interventionCount > 0) {
-    reasons.push(
+    pushReason(
+      reasons,
+      REASON_CATEGORY.INTERVENTION,
       `manual interventions recorded (${interventionCount}): ${state.manualInterventions
         .map((i) => i.reason)
         .slice(0, 3)
@@ -193,13 +356,20 @@ function evaluateStateSignals(state, reasons) {
   );
   const nonDoneStatuses = storyStatuses.filter((s) => s !== 'done');
   if (nonDoneStatuses.length > 0) {
-    reasons.push(
+    // A story not done is an unfinished / blocked run — blocks under both.
+    pushReason(
+      reasons,
+      REASON_CATEGORY.BLOCKED_STATE,
       `${nonDoneStatuses.length} story(ies) not done (statuses: ${nonDoneStatuses.join(', ')})`,
     );
   }
   const storyBlockers = countStoryBlockers(stories);
   if (storyBlockers > 0) {
-    reasons.push(
+    // A recorded story-level blocker is the `agent::blocked` state — it
+    // blocks under both policies.
+    pushReason(
+      reasons,
+      REASON_CATEGORY.BLOCKED_STATE,
       `${storyBlockers} story-level blocker(s) recorded in run-state`,
     );
   }
@@ -237,7 +407,15 @@ function evaluateCodeReviewSignals(codeReview, reasons) {
     ? parseSeverityCounts(codeReview.body)
     : { critical: null, high: null, medium: null, suggestion: null };
   if (!codeReviewFound) {
-    reasons.push('code-review structured comment not found on Epic');
+    // A missing code-review comment is a soft signal — it does not, on
+    // its own, prove a critical finding. Categorize it as a warning-level
+    // reason so it blocks under `strict` (which demands the clean gate)
+    // but not under `trust-ci` (which only blocks on a PARSED 🔴 count).
+    pushReason(
+      reasons,
+      REASON_CATEGORY.WARNING_REVIEW,
+      'code-review structured comment not found on Epic',
+    );
     return { codeReviewFound, codeReviewUnparseable: false, severity };
   }
   // "Present but unparseable" is a DISTINCT condition from "present and says
@@ -264,10 +442,18 @@ function evaluateCodeReviewSignals(codeReview, reasons) {
     return { codeReviewFound, codeReviewUnparseable, severity };
   }
   if (severity.critical > 0) {
-    reasons.push(`code-review has ${severity.critical} 🔴 Critical Blocker(s)`);
+    pushReason(
+      reasons,
+      REASON_CATEGORY.CRITICAL_REVIEW,
+      `code-review has ${severity.critical} 🔴 Critical Blocker(s)`,
+    );
   }
   if (severity.high > 0) {
-    reasons.push(`code-review has ${severity.high} 🟠 High Risk finding(s)`);
+    pushReason(
+      reasons,
+      REASON_CATEGORY.WARNING_REVIEW,
+      `code-review has ${severity.high} 🟠 High Risk finding(s)`,
+    );
   }
   return { codeReviewFound, codeReviewUnparseable, severity };
 }
@@ -275,23 +461,31 @@ function evaluateCodeReviewSignals(codeReview, reasons) {
 function evaluateRetroSignals(retro, reasons) {
   const retroFound = !!retro && typeof retro.body === 'string';
   if (!retroFound) {
-    reasons.push('retro structured comment not found on Epic');
+    pushReason(
+      reasons,
+      REASON_CATEGORY.RETRO,
+      'retro structured comment not found on Epic',
+    );
     return { retroFound, retroCompact: false };
   }
   // Read the machine-readable verdict trailer instead of string-matching
   // the human-facing "🟢 Clean sprint" prose (Story #3901). A missing or
-  // malformed trailer is a hard disqualifier — we never arm auto-merge on
-  // a retro whose verdict we cannot read.
+  // malformed trailer is a hard disqualifier under `strict` — we never arm
+  // strict-policy auto-merge on a retro whose verdict we cannot read.
   const verdict = parseAutomergeVerdictTrailer(retro.body);
   if (!verdict) {
-    reasons.push(
+    pushReason(
+      reasons,
+      REASON_CATEGORY.RETRO,
       'retro is missing the machine-readable automerge-verdict trailer (cannot certify clean sprint)',
     );
     return { retroFound, retroCompact: false };
   }
   const retroCompact = verdict.cleanSprint === true;
   if (!retroCompact) {
-    reasons.push(
+    pushReason(
+      reasons,
+      REASON_CATEGORY.RETRO,
       'retro automerge-verdict trailer reports cleanSprint=false (full retro indicates friction / parked / interventions)',
     );
   }
@@ -300,7 +494,13 @@ function evaluateRetroSignals(retro, reasons) {
 
 /**
  * Pure verdict-from-signals function. Composes the three signal sources into
- * a single `{ clean, reasons[] }` envelope. Exported for tests.
+ * a single envelope. The `clean` boolean is the strict-policy verdict (true
+ * iff there are zero reasons of any category) — it is preserved so the
+ * `strict` policy restores the prior predicate EXACTLY. `reasons` is the
+ * flat string[] of human-facing messages (byte-identical to the pre-#4361
+ * output for the same inputs); `categorizedReasons` is the same list tagged
+ * with a `REASON_CATEGORY` so the policy filter (`applyAutoMergePolicy`) can
+ * narrow which reasons block per posture. Exported for tests.
  *
  * @param {{
  *   state: object|null,
@@ -310,6 +510,7 @@ function evaluateRetroSignals(retro, reasons) {
  * @returns {{
  *   clean: boolean,
  *   reasons: string[],
+ *   categorizedReasons: Array<{ category: string, message: string }>,
  *   signals: {
  *     manualInterventions: number,
  *     storyStatuses: string[],
@@ -324,14 +525,18 @@ function evaluateRetroSignals(retro, reasons) {
  * }}
  */
 export function deriveAutoMergeVerdict({ state, codeReview, retro }) {
-  const reasons = [];
-  const stateSig = evaluateStateSignals(state, reasons);
-  const reviewSig = evaluateCodeReviewSignals(codeReview, reasons);
-  const retroSig = evaluateRetroSignals(retro, reasons);
+  const categorizedReasons = [];
+  const stateSig = evaluateStateSignals(state, categorizedReasons);
+  const reviewSig = evaluateCodeReviewSignals(codeReview, categorizedReasons);
+  const retroSig = evaluateRetroSignals(retro, categorizedReasons);
 
   return {
-    clean: reasons.length === 0,
-    reasons,
+    // `clean` is the STRICT verdict: no reason of any category. This is the
+    // exact pre-#4361 predicate, preserved so `strict` policy is unchanged.
+    clean: categorizedReasons.length === 0,
+    // Flat string[] — byte-identical to the pre-#4361 reason messages.
+    reasons: categorizedReasons.map((r) => r.message),
+    categorizedReasons,
     signals: {
       manualInterventions: stateSig.interventionCount,
       storyStatuses: stateSig.storyStatuses,
@@ -346,6 +551,67 @@ export function deriveAutoMergeVerdict({ state, codeReview, retro }) {
   };
 }
 
+/**
+ * Apply the `delivery.ci.autoMerge` policy to a categorized verdict.
+ * Returns the EFFECTIVE arming decision plus the split of blocking vs.
+ * recorded-only reasons. Pure — exported for tests.
+ *
+ *   - `"strict"`   → every reason blocks (identical to the pre-#4361
+ *     `clean` verdict). `recordedReasons` is empty.
+ *   - `"trust-ci"` → only `criticalReview` / `blockedState` reasons
+ *     block; the rest (interventions, warnings, retro) land in
+ *     `recordedReasons` for audit and do NOT gate the merge.
+ *
+ * @param {{ clean: boolean, categorizedReasons: Array<{ category: string, message: string }> }} verdict
+ * @param {'trust-ci'|'strict'} policy
+ * @returns {{
+ *   arm: boolean,
+ *   policy: 'trust-ci'|'strict',
+ *   blockingReasons: Array<{ category: string, message: string }>,
+ *   recordedReasons: Array<{ category: string, message: string }>,
+ * }}
+ */
+export function applyAutoMergePolicy(verdict, policy) {
+  const reasons = Array.isArray(verdict?.categorizedReasons)
+    ? verdict.categorizedReasons
+    : [];
+  if (policy === 'strict') {
+    return {
+      arm: reasons.length === 0,
+      policy: 'strict',
+      blockingReasons: reasons,
+      recordedReasons: [],
+    };
+  }
+  // trust-ci (default): only critical-review and blocked-state reasons gate.
+  const blockingReasons = [];
+  const recordedReasons = [];
+  for (const r of reasons) {
+    if (TRUST_CI_BLOCKING_CATEGORIES.has(r.category)) {
+      blockingReasons.push(r);
+    } else {
+      recordedReasons.push(r);
+    }
+  }
+  return {
+    arm: blockingReasons.length === 0,
+    policy: 'trust-ci',
+    blockingReasons,
+    recordedReasons,
+  };
+}
+
+/**
+ * Join a categorized reason list into a single-line `reason` string for
+ * the `epic.merge.blocked` emit / classification log. Pure.
+ */
+function formatReasons(reasons, prefix = '') {
+  const messages = reasons.map((r) => r.message);
+  const head = messages.slice(0, 3).join('; ');
+  const suffix = messages.length > 3 ? `; +${messages.length - 3} more` : '';
+  return `${prefix}${head}${suffix}`;
+}
+
 /**
  * IO-bound entry. Loads all three signal sources from the structured-comment
  * surface on the Epic ticket and hands them to `deriveAutoMergeVerdict`.
@@ -360,7 +626,7 @@ export function deriveAutoMergeVerdict({ state, codeReview, retro }) {
  *   findCommentFn?: typeof findStructuredComment,
  *   readRunStateFn?: typeof epicRunStateStore.read,
  * }} opts
- * @returns {Promise<{ clean: boolean, reasons: string[], signals: object }>}
+ * @returns {Promise<{ clean: boolean, reasons: object[], signals: object }>}
  */
 export async function evaluateAutoMergePredicate({
   provider,
@@ -402,8 +668,15 @@ export class AutomergePredicate {
    * @param {object} opts.provider GitHub provider (passed through to the
    *   evaluator). Required for the read of run-state + structured
    *   comments.
+   * @param {object} [opts.config] Resolved agent config. Read for the
+   *   `delivery.ci.autoMerge` policy via `getCiDelivery`. Defaults to the
+   *   framework default (`trust-ci`) when omitted.
+   * @param {string} [opts.cwd] Working directory for the live
+   *   `gh pr checks --required` probe. Defaults to `process.cwd()`.
    * @param {Function} [opts.evaluatePredicateFn] override of
    *   `evaluateAutoMergePredicate` for tests.
+   * @param {Function} [opts.probeRequiredChecksFn] override of
+   *   `probeRequiredChecks` for tests.
    * @param {{ info?: Function, warn?: Function, debug?: Function }} [opts.logger]
    */
   constructor(opts = {}) {
@@ -425,16 +698,21 @@ export class AutomergePredicate {
     this.bus = opts.bus;
     this.epicId = opts.epicId;
     this.provider = opts.provider;
+    this.cwd = opts.cwd ?? process.cwd();
+    // Resolve the merge posture once at construction. `getCiDelivery`
+    // applies the framework default (`trust-ci`) for any omitted field.
+    this.policy = getCiDelivery(opts.config ?? null).autoMerge;
     this.evaluatePredicateFn =
       opts.evaluatePredicateFn ?? evaluateAutoMergePredicate;
+    this.probeRequiredChecksFn =
+      opts.probeRequiredChecksFn ?? probeRequiredChecks;
     this.logger = opts.logger ?? console;
     /** @type {Set<string>} `${event}:${seqId}` idempotency cache. */
     this._seen = new Set();
     /**
-     * Classification log — every `epic.watch.end` we observe lands here
-     * with the outcome (`ready`, `blocked`, `skipped-duplicate`,
-     * `failed`). Mirrors the Finalizer / Reconciler "no silent skip"
-     * surface.
+     * Classification log — every event we observe lands here with the
+     * outcome (`ready`, `blocked`, `skipped-duplicate`, `failed`).
+     * Mirrors the Finalizer / Reconciler "no silent skip" surface.
      */
     this.classifications = [];
     this.events = Object.freeze(['epic.automerge.start', 'epic.watch.end']);
@@ -472,18 +750,19 @@ export class AutomergePredicate {
       });
       return;
     }
-    // Gate 1 — required-check freshness. Any non-passing required
-    // check is a hard block: short-circuit before consulting the
-    // structured-signal evaluator so the operator sees the CI failure
-    // as the reason, not a downstream signal.
+    // Gate 1 — required-check freshness. Any non-passing required check is
+    // a hard block: short-circuit before consulting the structured-signal
+    // evaluator so the operator sees the CI failure as the reason, not a
+    // downstream signal.
     //
-    // `checkOutcomes` is only present on the `epic.watch.end` payload
-    // (the test-only `Watcher` path). The production `epic.automerge.start`
-    // payload omits it because Phase 8 (`pr-watch-with-update.js`) has
-    // already polled every required check to green before Phase 8.5 fires
-    // (Story #3901). When the map is absent, skip this gate entirely
-    // rather than treating an empty map as "all green by vacuous truth" —
-    // CI greenness is proven upstream, not re-derived here.
+    // Two sources of CI truth:
+    //   (a) `epic.watch.end` (test-only Watcher path) carries a settled
+    //       `checkOutcomes` map — that map is authoritative, so we classify
+    //       it directly and issue NO live probe.
+    //   (b) `epic.automerge.start` (production Phase 8.5) carries no map.
+    //       Story #4361: we run a LIVE `gh pr checks --required` probe here
+    //       so an interrupted Phase 8 watch cannot arm merge on red/pending
+    //       required checks (closes the Story #3901 hole).
     if (payload?.checkOutcomes !== undefined) {
       const failures = listFailingChecks(payload.checkOutcomes);
       if (failures.length > 0) {
@@ -492,14 +771,29 @@ export class AutomergePredicate {
         await this._emitBlocked(prUrl, reason);
         return;
       }
+    } else {
+      // Live probe — production path. Fail closed on any non-green,
+      // pending, or unreadable required-check result.
+      let probeVerdict;
+      try {
+        const probe = this.probeRequiredChecksFn({ prUrl, cwd: this.cwd });
+        probeVerdict = classifyRequiredChecksProbe(probe);
+      } catch (err) {
+        probeVerdict = {
+          ok: false,
+          reason: `live required-check probe threw: ${err?.message ?? err}`,
+          outcomes: {},
+        };
+      }
+      if (!probeVerdict.ok) {
+        const reason = probeVerdict.reason ?? 'required checks not green';
+        this.classifications.push({ event, seqId, outcome: 'blocked', reason });
+        await this._emitBlocked(prUrl, reason);
+        return;
+      }
     }
 
-    // Gate 2 — structured-signal verdict. Wraps
-    // `evaluateAutoMergePredicate` so the verdict for any given input
-    // set is IDENTICAL to what `epic-deliver-automerge.js` would have
-    // produced before Wave 7. The classification surface logs the
-    // first three reasons so operators don't have to dig into the
-    // legacy CLI output to understand a block.
+    // Gate 2 — structured-signal verdict, filtered by the merge policy.
     let verdict;
     try {
       verdict = await this.evaluatePredicateFn({
@@ -518,17 +812,32 @@ export class AutomergePredicate {
       return;
     }
 
-    if (verdict?.clean) {
+    const decision = applyAutoMergePolicy(verdict, this.policy);
+    // Surface recorded-but-non-blocking reasons for audit even when the
+    // trust-ci policy arms anyway (interventions / warnings / non-clean
+    // retro). These never gate the merge but must not be silently dropped.
+    const recorded = decision.recordedReasons ?? [];
+
+    if (decision.arm) {
       this.classifications.push({
         event,
         seqId,
         outcome: 'ready',
+        policy: decision.policy,
         signals: verdict.signals,
+        ...(recorded.length > 0
+          ? { recordedReasons: recorded.map((r) => r.message) }
+          : {}),
       });
+      if (recorded.length > 0) {
+        this.logger.info?.(
+          `[AutomergePredicate] arming under ${decision.policy}; recorded (non-blocking): ${formatReasons(recorded)}`,
+        );
+      }
       try {
         await this.bus.emit('epic.merge.ready', {
           prUrl,
-          reason: 'all required checks green; structured signals clean',
+          reason: `all required checks green; ${decision.policy} policy signals clear`,
         });
       } catch (err) {
         this.logger.warn?.(
@@ -538,20 +847,28 @@ export class AutomergePredicate {
       return;
     }
 
-    const reasons = Array.isArray(verdict?.reasons) ? verdict.reasons : [];
+    const blocking = decision.blockingReasons ?? [];
     const reason =
-      reasons.length > 0
-        ? reasons.slice(0, 3).join('; ') +
-          (reasons.length > 3 ? `; +${reasons.length - 3} more` : '')
+      blocking.length > 0
+        ? formatReasons(blocking)
         : 'predicate dirty (no reasons reported)';
-    this.classifications.push({ event, seqId, outcome: 'blocked', reason });
+    this.classifications.push({
+      event,
+      seqId,
+      outcome: 'blocked',
+      policy: decision.policy,
+      reason,
+      ...(recorded.length > 0
+        ? { recordedReasons: recorded.map((r) => r.message) }
+        : {}),
+    });
     await this._emitBlocked(prUrl, reason);
   }
 
   /**
-   * Emit `epic.merge.blocked`. Helper carved out so the three blocking
-   * paths (CI failure / predicate dirty / evaluator throw) share the
-   * same emit shape.
+   * Emit `epic.merge.blocked`. Helper carved out so the blocking paths
+   * (CI failure / predicate dirty / evaluator throw) share the same emit
+   * shape.
    */
   async _emitBlocked(prUrl, reason) {
     try {