mandrel 2.35.0 → 2.36.0

package/.agents/docs/agentrc-reference.json

@@ -340,7 +340,9 @@
         "maxResumes": 3,
         "attachWindowMs": 1200000
       },
-      "autoMerge": "trust-ci"
+      "autoMerge": "trust-ci",
+      "blockOnAdvisoryFailure": true,
+      "advisoryAllowlist": []
     },
     "routing": {
       "roleScopedAgents": true,

package/.agents/docs/configuration.md

@@ -320,6 +320,8 @@ Everything `/deliver` and `single-story-close` consume: execution timeouts, work
 | `ci.watch.maxResumes` | No | `integer` | `3` | How many times the watcher may resume after a transient stall. 0 disables resuming. |
 | `ci.watch.attachWindowMs` | No | `integer` | `1200000` | Story #4890. How long (ms) the watch keeps re-resolving an EMPTY `gh pr checks --required` set before it stops waiting for a required context to attach. A ruleset attaches its contexts asynchronously and the arrival latency is set by the slowest one, so a required context that is an aggregator job gated on every other tier is the last to appear — measured at 16m52s on this repository. Default 1200000 (20 minutes). Raise it for a repository whose contexts arrive later still; exhausting the window is never reported as a red check (the watch exits 2, not-yet-started). |
 | `ci.autoMerge` | No | `"trust-ci"` \| `"strict"` | `"trust-ci"` | Story #4356 (Epic #4355). Merge posture. 'trust-ci' (default) merges once required checks pass; 'strict' additionally requires a clean review gate. |
+| `ci.blockOnAdvisoryFailure` | No | `boolean` | `true` | Story #5096. When true (default), delivery refuses to arm — and disarms — GitHub native auto-merge while a non-required (advisory) check is genuinely red on the PR head and GitHub reports the PR mergeable anyway (mergeStateStatus=UNSTABLE). `--auto` waits on REQUIRED contexts only, so without this a red advisory quality gate merges unattended. Set false to restore the pre-#5096 behaviour verbatim. |
+| `ci.advisoryAllowlist` | No | `array<string>` | `[]` | Story #5096. Check-run names exempt from blockOnAdvisoryFailure — a red run whose name matches exactly never blocks arming. Matching is exact; an unnamed run can never match and always blocks. |
 | `routing` | No | `object` | — | v2 delivery-spawn routing: role-scoped boot contexts and maker-checker sampling. The v1 singleDelivery epic-route kill-switch was removed in Stage 6. |
 | `routing.roleScopedAgents` | No | `boolean` | `true` | Epic #4478 (M7-B). Kill-switch for the role-scoped boot contexts. When true (default), a converted delivery spawn (`story-worker`, `acceptance-critic`) boots on its own `.claude/agents/<role>.md` system prompt instead of re-paying the full CLAUDE.md @-import closure. When false, every converted spawn falls back to `subagent_type: general-purpose` — the instant, code-rollback-free per-consumer revert, and the universal escape for hosts that ignore `.claude/agents/`. The fallback is the full-closure agent that ran before M7-B, so flipping it off never drops a gate. |
 | `routing.freshCriticSampleRate` | No | `number` | `0.2` | Epic #4478 (M7-B, Part 2). Maker-checker sampling floor. Under the standard profile, a change set touching no sensitive path routes its acceptance clusters down the contract-identical inline critic path, but this fraction of them is still forced through a fresh-context critic so a low derived level never means zero independent checking. Clamped to [0, 1]; 0 disables the floor, 1 forces every cluster fresh. Consumed by resolveCeremonyForRisk (lib/orchestration/ceremony-routing.js). |

package/.agents/schemas/agentrc.schema.json

@@ -1913,6 +1913,17 @@
               "enum": ["trust-ci", "strict"],
               "description": "Story #4356 (Epic #4355). Merge posture. 'trust-ci' (default) merges once required checks pass; 'strict' additionally requires a clean review gate.",
               "default": "trust-ci"
+            },
+            "blockOnAdvisoryFailure": {
+              "type": "boolean",
+              "description": "Story #5096. When true (default), delivery refuses to arm — and disarms — GitHub native auto-merge while a non-required (advisory) check is genuinely red on the PR head and GitHub reports the PR mergeable anyway (mergeStateStatus=UNSTABLE). `--auto` waits on REQUIRED contexts only, so without this a red advisory quality gate merges unattended. Set false to restore the pre-#5096 behaviour verbatim.",
+              "default": true
+            },
+            "advisoryAllowlist": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Story #5096. Check-run names exempt from blockOnAdvisoryFailure — a red run whose name matches exactly never blocks arming. Matching is exact; an unnamed run can never match and always blocks.",
+              "default": []
             }
           },
           "additionalProperties": false

package/.agents/schemas/lifecycle/merge.unlanded.schema.json

@@ -29,7 +29,8 @@
         "branch-protection-human-required",
         "arm-failure",
         "api-race-other",
-        "predicate-refused"
+        "predicate-refused",
+        "advisory-gate-red"
       ]
     },
     "reason": { "type": "string", "minLength": 1 },

package/.agents/schemas/story-deliver-terminal.schema.json

@@ -125,6 +125,7 @@
             "arm-failure",
             "api-race-other",
             "predicate-refused",
+            "advisory-gate-red",
             "merged-flip-failed"
           ]
         },

package/.agents/scripts/check-doc-links.js

@@ -325,6 +325,22 @@ function stripAnchorAndQuery(target) {
   return t;
 }
 
+// Percent-decode a link target's path portion (Story #5090). A correctly
+// encoded Markdown destination escapes URL-reserved characters — a
+// file-based router's `[token]` segment is written `%5Btoken%5D`, the form
+// CommonMark renderers require — but the filesystem knows only the decoded
+// name. The decode is one-way and total: a malformed escape (`%zz`) degrades
+// to the raw string instead of throwing `URIError`, so an undecodable target
+// is resolved exactly as it was before.
+function decodeLinkPath(pathOnly) {
+  if (!pathOnly.includes('%')) return pathOnly;
+  try {
+    return decodeURIComponent(pathOnly);
+  } catch {
+    return pathOnly;
+  }
+}
+
 // --- Slash-token extraction ------------------------------------------------
 
 // Tokens look like `/<lowercase-alphanum-with-hyphens>`. We exclude tokens
@@ -394,8 +410,13 @@ export function checkFile(absPath, repoRoot) {
   // 2. Relative-link resolution.
   for (const { target, line } of extractLinks(masked)) {
     if (isExternalOrInternalAnchor(target)) continue;
-    const pathOnly = stripAnchorAndQuery(target);
-    if (!pathOnly) continue; // pure anchor that survived earlier check
+    const rawPathOnly = stripAnchorAndQuery(target);
+    if (!rawPathOnly) continue; // pure anchor that survived earlier check
+    // Decode AFTER anchor/query stripping — so an escaped `%23` cannot
+    // collapse into an anchor delimiter and truncate the target — and BEFORE
+    // resolution, so the payload-boundary branch below reports the decoded
+    // path rather than the escaped one.
+    const pathOnly = decodeLinkPath(rawPathOnly);
     let resolved;
     if (pathOnly.startsWith('/')) {
       // Treat root-absolute paths as repo-root relative.

package/.agents/scripts/git-cleanup.js

@@ -64,6 +64,7 @@ import {
   probeMergedPr,
   refExists,
 } from './lib/orchestration/git-cleanup/phases/git-probes.js';
+import { probeAncestry } from './lib/orchestration/git-cleanup/phases/merged-tip.js';
 import { parseCleanupArgs } from './lib/orchestration/git-cleanup/phases/parse-args.js';
 import {
   executePrune,
@@ -110,6 +111,7 @@ export {
   planFastForward,
   planStashes,
   probeAllPrs,
+  probeAncestry,
   probeContentEquivalent,
   probeLatestPr,
   probeMergedPr,

package/.agents/scripts/lib/config/ci.js

@@ -5,6 +5,13 @@
  * (default `"trust-ci"`) selects the merge posture — `"trust-ci"` merges once
  * required checks pass, `"strict"` additionally requires a clean review gate.
  *
+ * Story #5096 added `blockOnAdvisoryFailure` (default `true`) and
+ * `advisoryAllowlist` (default `[]`). GitHub native auto-merge waits on
+ * REQUIRED contexts only, so a red ADVISORY gate would otherwise be merged
+ * straight past; these knobs own mandrel's side of that decision. Set
+ * `blockOnAdvisoryFailure: false` to restore the pre-#5096 behaviour verbatim,
+ * or list a job name in `advisoryAllowlist` to exempt just that one.
+ *
  * Retired (no production readers on v2 Story-only delivery): `earlyPr`
  * (Epic early-PR warmup) and `requireChecks` (AutomergePredicate escape hatch
  * whose listener was never landed).
@@ -12,6 +19,8 @@
 
 export const CI_DELIVERY_DEFAULTS = Object.freeze({
   autoMerge: 'trust-ci',
+  blockOnAdvisoryFailure: true,
+  advisoryAllowlist: Object.freeze([]),
 });
 
 /**
@@ -31,6 +40,15 @@ export function getCiDelivery(config) {
       ci.autoMerge === 'trust-ci' || ci.autoMerge === 'strict'
         ? ci.autoMerge
         : CI_DELIVERY_DEFAULTS.autoMerge,
+    blockOnAdvisoryFailure:
+      typeof ci.blockOnAdvisoryFailure === 'boolean'
+        ? ci.blockOnAdvisoryFailure
+        : CI_DELIVERY_DEFAULTS.blockOnAdvisoryFailure,
+    advisoryAllowlist: Array.isArray(ci.advisoryAllowlist)
+      ? ci.advisoryAllowlist.filter(
+          (entry) => typeof entry === 'string' && entry,
+        )
+      : [...CI_DELIVERY_DEFAULTS.advisoryAllowlist],
     watch:
       ci.watch && typeof ci.watch === 'object' ? { ...ci.watch } : undefined,
   };

package/.agents/scripts/lib/config-settings-schema-delivery.js

@@ -389,6 +389,19 @@ const CI_DELIVERY_SCHEMA = {
         "Story #4356 (Epic #4355). Merge posture. 'trust-ci' (default) merges once required checks pass; 'strict' additionally requires a clean review gate.",
       default: CI_DELIVERY_DEFAULTS.autoMerge,
     },
+    blockOnAdvisoryFailure: {
+      type: 'boolean',
+      description:
+        'Story #5096. When true (default), delivery refuses to arm — and disarms — GitHub native auto-merge while a non-required (advisory) check is genuinely red on the PR head and GitHub reports the PR mergeable anyway (mergeStateStatus=UNSTABLE). `--auto` waits on REQUIRED contexts only, so without this a red advisory quality gate merges unattended. Set false to restore the pre-#5096 behaviour verbatim.',
+      default: CI_DELIVERY_DEFAULTS.blockOnAdvisoryFailure,
+    },
+    advisoryAllowlist: {
+      type: 'array',
+      items: { type: 'string' },
+      description:
+        'Story #5096. Check-run names exempt from blockOnAdvisoryFailure — a red run whose name matches exactly never blocks arming. Matching is exact; an unnamed run can never match and always blocks.',
+      default: [...CI_DELIVERY_DEFAULTS.advisoryAllowlist],
+    },
   },
   additionalProperties: false,
 };

package/.agents/scripts/lib/observability/source-classifier.js

@@ -113,7 +113,6 @@ const FRAMEWORK_SCRIPT_BASENAMES = Object.freeze([
   'evidence-gate.js',
   'generate-config-docs.js',
   'generate-lens-checklists.js',
-  'generate-lifecycle-docs.js',
   'generate-skills-index.js',
   'generate-workflows-doc.js',
   'git-cleanup.js',

package/.agents/scripts/lib/orchestration/git-cleanup/phases/branches.js

@@ -37,15 +37,19 @@ import {
   removeWorktree,
   worktreesByBranch,
 } from './git-probes.js';
+import { probeAncestry } from './merged-tip.js';
 import { parsePrunedRefs } from './prune.js';
 
 const TAG = '[git-cleanup]';
 
+/** Fields a planner verdict forwards onto its `skipped[]` entry. */
+const SKIP_DETAIL_FIELDS = ['prNumber', 'tipSha', 'mergedSha', 'detail'];
+
 function skipEntryFromVerdict(branch, verdict) {
   const entry = { branch, reason: verdict.reason };
-  if (verdict.prNumber != null) entry.prNumber = verdict.prNumber;
-  if (verdict.tipSha) entry.tipSha = verdict.tipSha;
-  if (verdict.mergedSha) entry.mergedSha = verdict.mergedSha;
+  for (const field of SKIP_DETAIL_FIELDS) {
+    if (verdict[field] != null) entry[field] = verdict[field];
+  }
   return entry;
 }
 
@@ -88,6 +92,7 @@ function evaluateLocalBranch({
   wtMap,
   remoteName,
   branchTipShaFn,
+  ancestryFn,
   contentEquivalentFn,
   branchLastCommitFn,
 }) {
@@ -102,6 +107,7 @@ function evaluateLocalBranch({
     remoteName,
     localExists: true,
     branchTipShaFn,
+    ancestryFn,
   });
   if (verdict.kind === 'skip') {
     return { skip: skipEntryFromVerdict(branch, verdict) };
@@ -134,6 +140,7 @@ function evaluateLocalBranch({
       worktreePath: wt?.path ?? null,
       detectedBy,
       localExists: true,
+      behindMerge: verdict.reason === 'tip-behind-merge',
     },
   };
 }
@@ -147,6 +154,7 @@ function collectRemoteOnlyCandidates({
   filter,
   prProbe,
   branchTipShaFn,
+  ancestryFn,
   skipped,
 }) {
   const out = [];
@@ -162,6 +170,7 @@ function collectRemoteOnlyCandidates({
       remoteName,
       localExists: false,
       branchTipShaFn,
+      ancestryFn,
     });
     if (verdict.kind === 'no-pr') continue;
     if (verdict.kind === 'skip') {
@@ -176,6 +185,7 @@ function collectRemoteOnlyCandidates({
       worktreePath: null,
       detectedBy: 'remote-only',
       localExists: false,
+      behindMerge: verdict.reason === 'tip-behind-merge',
     });
   }
   return out;
@@ -187,10 +197,12 @@ function collectRemoteOnlyCandidates({
  * The PR probe classifies each candidate by the **latest** PR on the head
  * ref rather than any historical merge. Branches whose latest PR is OPEN
  * or CLOSED-not-merged are skipped with `reason: 'latest-pr-open'` /
- * `reason: 'latest-pr-closed-not-merged'`. When the latest PR is MERGED
- * but the branch tip has diverged from the PR's `headRefOid` (post-merge
- * force-push), the branch is skipped with
- * `reason: 'tip-diverged-from-merge'`.
+ * `reason: 'latest-pr-closed-not-merged'`. A MERGED PR whose `headRefOid`
+ * differs from the branch tip is resolved by ancestry in
+ * `merged-tip.js` — a tip *behind* the merged head becomes a candidate
+ * carrying `behindMerge: true`, a tip *ahead* of it keeps the
+ * `tip-diverged-from-merge` force-push skip, and an unresolvable rev
+ * skips as `unverifiable`.
  *
  * Performance (Story #3333): when the caller does not inject its own
  * `prProbe`, the planner fires **one** bulk `gh pr list --state all`
@@ -250,6 +262,7 @@ export function planCleanup(ctx) {
     prIndexFn = probeAllPrs,
     prFallback = probeLatestPr,
     branchTipShaFn = branchTipSha,
+    ancestryFn = probeAncestry,
     contentEquivalentFn = probeContentEquivalent,
     branchLastCommitFn = branchLastCommitAt,
     refExistsFn = refExists,
@@ -301,6 +314,7 @@ export function planCleanup(ctx) {
       wtMap,
       remoteName,
       branchTipShaFn,
+      ancestryFn,
       contentEquivalentFn,
       branchLastCommitFn,
     });
@@ -318,6 +332,7 @@ export function planCleanup(ctx) {
         filter,
         prProbe,
         branchTipShaFn,
+        ancestryFn,
         skipped,
       }),
     );

package/.agents/scripts/lib/orchestration/git-cleanup/phases/git-probes.js

@@ -17,6 +17,7 @@ import { execFileSync } from 'node:child_process';
 
 import { gitSpawn } from '../../../git-utils.js';
 import { parseWorktreePorcelain } from '../../../worktree-manager.js';
+import { resolveMergedTip } from './merged-tip.js';
 
 export {
   canFastForward,
@@ -452,6 +453,12 @@ export const __testing = { validSha, firstLsRemoteSha, firstStdoutLine };
  *     into `skipped[]` and continues.
  *   - `{ kind: 'no-pr' }` — caller continues without skipping.
  *
+ * A MERGED PR whose `headRefOid` differs from the branch tip is handed
+ * to {@link resolveMergedTip}, which resolves it by ancestry — see that
+ * module for the `tip-behind-merge` / `tip-diverged-from-merge` /
+ * `unverifiable` taxonomy and why a bare SHA inequality could not
+ * express it.
+ *
  * @param {{
  *   prInfo: { number?: number, state?: string, mergedAt?: string|null, headRefOid?: string|null } | null,
  *   branch: string,
@@ -459,8 +466,10 @@ export const __testing = { validSha, firstLsRemoteSha, firstStdoutLine };
  *   remoteName: string,
  *   localExists: boolean,
  *   branchTipShaFn: (args: { cwd: string, branch: string, remoteName: string, localExists: boolean }) => string | null,
+ *   ancestryFn?: Function,
+ *   mergedTipFn?: typeof resolveMergedTip,
  * }} args
- * @returns {{ kind: 'candidate', prInfo: object } | { kind: 'skip', reason: string, prNumber?: number, tipSha?: string|null, mergedSha?: string|null } | { kind: 'no-pr' }}
+ * @returns {{ kind: 'candidate', prInfo: object, reason?: string, tipSha?: string, mergedSha?: string } | { kind: 'skip', reason: string, prNumber?: number, tipSha?: string|null, mergedSha?: string|null, detail?: string } | { kind: 'no-pr' }}
  */
 export function classifyLatestPr({
   prInfo,
@@ -469,6 +478,8 @@ export function classifyLatestPr({
   remoteName,
   localExists,
   branchTipShaFn,
+  ancestryFn,
+  mergedTipFn = resolveMergedTip,
 }) {
   if (!prInfo) return { kind: 'no-pr' };
   const state =
@@ -494,17 +505,14 @@ export function classifyLatestPr({
       prNumber: prInfo.number ?? null,
     };
   }
-  if (prInfo.headRefOid) {
-    const tipSha = branchTipShaFn({ cwd, branch, remoteName, localExists });
-    if (tipSha && tipSha !== prInfo.headRefOid) {
-      return {
-        kind: 'skip',
-        reason: 'tip-diverged-from-merge',
-        prNumber: prInfo.number ?? null,
-        tipSha,
-        mergedSha: prInfo.headRefOid,
-      };
-    }
-  }
-  return { kind: 'candidate', prInfo };
+  const tipVerdict = mergedTipFn({
+    prInfo,
+    branch,
+    cwd,
+    remoteName,
+    localExists,
+    branchTipShaFn,
+    ancestryFn,
+  });
+  return tipVerdict ?? { kind: 'candidate', prInfo };
 }

package/.agents/scripts/lib/orchestration/git-cleanup/phases/merged-tip.js

@@ -0,0 +1,132 @@
+/**
+ * merged-tip.js — resolve a MERGED PR's head against the branch tip
+ * (Story #5086).
+ *
+ * Owns the ancestry probe and the taxonomy the branches-phase classifier
+ * applies when a merged PR's `headRefOid` and the branch tip disagree.
+ * Split out of `git-probes.js` so the classifier reads as one call and
+ * the taxonomy's own documentation sits next to the code it governs.
+ *
+ * @module lib/orchestration/git-cleanup/phases/merged-tip
+ */
+
+import { gitSpawn } from '../../../git-utils.js';
+
+/**
+ * Tri-state ancestry probe: is `ancestorSha` reachable from
+ * `descendantSha`?
+ *
+ * Mirrors the contract `checkHeadAncestor` in
+ * `lib/worktree/lifecycle/merge-reachability.js` proved out for the
+ * worktree-reap gate — the two cannot share an implementation because
+ * that one takes a `ctx.git.gitSpawn` / `ctx.repoRoot` bag while
+ * git-cleanup's probes take a bare `cwd`.
+ *
+ * `git merge-base --is-ancestor` exits **0** (ancestor), **1** (not an
+ * ancestor) or **128** (a rev it cannot resolve). Folding 128 into
+ * "not an ancestor" is the bug this probe exists to prevent: a merged
+ * head absent from the local object DB would silently read as a
+ * divergence and re-emit the wrong post-merge-force-push diagnosis. Both
+ * revs are therefore resolved with `git rev-parse -q --verify` first, and
+ * any failure fails closed to the `error` arm — so `merge-base` never
+ * runs against a rev git cannot resolve.
+ *
+ * @param {{ cwd: string, ancestorSha: string, descendantSha: string, spawn?: typeof gitSpawn }} args
+ * @returns {{ outcome: 'ancestor' } | { outcome: 'not-ancestor' } | { outcome: 'error', reason: string }}
+ */
+export function probeAncestry({
+  cwd,
+  ancestorSha,
+  descendantSha,
+  spawn = gitSpawn,
+}) {
+  for (const rev of [ancestorSha, descendantSha]) {
+    const res = spawn(
+      cwd,
+      'rev-parse',
+      '--quiet',
+      '--verify',
+      `${rev}^{commit}`,
+    );
+    if (res.status !== 0) {
+      return { outcome: 'error', reason: `unresolvable rev ${rev}` };
+    }
+  }
+  const res = spawn(
+    cwd,
+    'merge-base',
+    '--is-ancestor',
+    ancestorSha,
+    descendantSha,
+  );
+  if (res.status === 0) return { outcome: 'ancestor' };
+  if (res.status === 1) return { outcome: 'not-ancestor' };
+  return {
+    outcome: 'error',
+    reason: (res.stderr || res.stdout || 'unknown').trim(),
+  };
+}
+
+/**
+ * Resolve a MERGED PR's `headRefOid` against the branch's current tip.
+ *
+ * Returns `null` when there is nothing to resolve — the PR row carries no
+ * `headRefOid`, the tip cannot be read, or the tip already matches the
+ * merged head — leaving the caller's plain-candidate path untouched.
+ *
+ * Otherwise the tip is classified by **ancestry**, never by the bare SHA
+ * inequality this replaced. That inequality could not tell a branch that
+ * is *behind* the merged head from one force-pushed *past* it, and
+ * reported both as the latter — advising the operator to push a follow-up
+ * commit that, for a stale pre-merge snapshot, does not exist. The three
+ * arms:
+ *
+ *   - **ancestor** — 0 commits ahead, every commit landed with the PR:
+ *     a reap candidate tagged `reason: 'tip-behind-merge'`.
+ *   - **not-ancestor** — equivalently "≥1 commit ahead", which is why one
+ *     probe settles the whole taxonomy and no `rev-list` count is needed:
+ *     the unchanged `tip-diverged-from-merge` force-push skip.
+ *   - **error** — a rev the local object DB cannot resolve:
+ *     `reason: 'unverifiable'` carrying the probe's `detail`. Never a
+ *     silent pass, and never a force-push label.
+ *
+ * @param {object} args
+ * @returns {{ kind: 'candidate', prInfo: object, reason: string, tipSha: string, mergedSha: string } | { kind: 'skip', reason: string, prNumber: number|null, tipSha: string, mergedSha: string, detail?: string } | null}
+ */
+export function resolveMergedTip({
+  prInfo,
+  branch,
+  cwd,
+  remoteName,
+  localExists,
+  branchTipShaFn,
+  ancestryFn = probeAncestry,
+}) {
+  const mergedSha = prInfo.headRefOid;
+  if (!mergedSha) return null;
+  const tipSha = branchTipShaFn({ cwd, branch, remoteName, localExists });
+  if (!tipSha || tipSha === mergedSha) return null;
+  const ancestry = ancestryFn({
+    cwd,
+    ancestorSha: tipSha,
+    descendantSha: mergedSha,
+  });
+  if (ancestry.outcome === 'ancestor') {
+    return {
+      kind: 'candidate',
+      prInfo,
+      reason: 'tip-behind-merge',
+      tipSha,
+      mergedSha,
+    };
+  }
+  const errored = ancestry.outcome === 'error';
+  return {
+    kind: 'skip',
+    reason: errored ? 'unverifiable' : 'tip-diverged-from-merge',
+    prNumber: prInfo.number ?? null,
+    tipSha,
+    mergedSha,
+    ...(errored ? { detail: ancestry.reason } : {}),
+  };
+}

package/.agents/scripts/lib/orchestration/git-cleanup/phases/render.js

@@ -61,6 +61,41 @@ function contentMergedNote(candidate) {
     : '';
 }
 
+/**
+ * Pure: render a single behind-the-merged-head candidate annotation.
+ *
+ * A branch whose tip is a strict ancestor of its merged PR head is a
+ * stale pre-merge snapshot — reapable, because every commit on it landed
+ * with the PR, but reapable for a different reason than a branch whose
+ * tip *matches* the merged head. It used to be skipped outright as a
+ * post-merge force-push; the note keeps the two visibly distinct in the
+ * dry-run list and the confirmation prompt so the operator can see why a
+ * branch that is not at the merged head is nonetheless offered.
+ */
+function behindMergeNote(candidate) {
+  return candidate.behindMerge
+    ? ' (tip behind the merged head — content already landed)'
+    : '';
+}
+
+/** Pure: every provenance annotation a candidate row carries, in order. */
+function candidateNotes(candidate) {
+  return `${contentMergedNote(candidate)}${behindMergeNote(candidate)}`;
+}
+
+/**
+ * Pure: one candidate row — its detection provenance, worktree, locality
+ * and annotations. Split out of {@link renderDryRun} so that renderer
+ * stays a loop over rows rather than growing a fourth inline ternary
+ * every time a candidate gains a new dimension.
+ */
+function renderCandidateRow(c) {
+  const pr = c.prNumber ? `PR #${c.prNumber}` : c.detectedBy;
+  const wt = c.hasWorktree ? ` (worktree: ${c.worktreePath})` : '';
+  const remoteOnly = c.localExists === false ? ' (remote-only)' : '';
+  return `  • ${c.branch} — ${pr}${wt}${remoteOnly}${candidateNotes(c)}`;
+}
+
 /**
  * Pure: render the branch-phase candidate list as the operator-facing text
  * block.
@@ -87,14 +122,7 @@ export function renderDryRun(plan, opts = {}) {
   if (plan.candidates.length === 0) {
     lines.push('  (no merged branches to clean up)');
   } else {
-    for (const c of plan.candidates) {
-      const pr = c.prNumber ? `PR #${c.prNumber}` : c.detectedBy;
-      const wt = c.hasWorktree ? ` (worktree: ${c.worktreePath})` : '';
-      const remoteOnly = c.localExists === false ? ' (remote-only)' : '';
-      lines.push(
-        `  • ${c.branch} — ${pr}${wt}${remoteOnly}${contentMergedNote(c)}`,
-      );
-    }
+    for (const c of plan.candidates) lines.push(renderCandidateRow(c));
   }
   const skipped = plan.skipped ?? [];
   const currentHeadSkip = skipped.find((s) => s.reason === 'current-head');
@@ -141,6 +169,17 @@ export function renderCandidateList({ plan, opts = {}, baseBranch = null }) {
   return renderDryRun(plan, { baseBranch, execute: !opts.dryRun });
 }
 
+/**
+ * Pure: the tip / merged short-SHA pair both merged-tip skip lines quote,
+ * with a placeholder for either side the planner could not resolve.
+ */
+function shortShaPair(skip) {
+  return {
+    tip: skip.tipSha ? skip.tipSha.slice(0, 7) : '<unknown>',
+    merged: skip.mergedSha ? skip.mergedSha.slice(0, 7) : '<unknown>',
+  };
+}
+
 /**
  * Pure: render a single latest-PR-state skip line. Returns null when the
  * skip reason is not one of the latest-PR family — `renderDryRun` filters
@@ -148,7 +187,7 @@ export function renderCandidateList({ plan, opts = {}, baseBranch = null }) {
  * `current-head`, `filtered`) stay quiet here. `not-merged` gets its own
  * renderer ({@link renderNotMergedSkipLine}).
  *
- * @param {{ branch: string, reason: string, prNumber?: number, tipSha?: string, mergedSha?: string }} skip
+ * @param {{ branch: string, reason: string, prNumber?: number, tipSha?: string, mergedSha?: string, detail?: string }} skip
  * @returns {string | null}
  */
 export function renderLatestPrSkipLine(skip) {
@@ -161,13 +200,19 @@ export function renderLatestPrSkipLine(skip) {
     return `${TAG} ⏭️  ${skip.branch} skipped — ${prRef} is still open`;
   }
   if (skip.reason === 'tip-diverged-from-merge') {
-    const tip = skip.tipSha ? skip.tipSha.slice(0, 7) : '<unknown>';
-    const merged = skip.mergedSha ? skip.mergedSha.slice(0, 7) : '<unknown>';
+    const { tip, merged } = shortShaPair(skip);
     return (
       `${TAG} ⏭️  ${skip.branch} skipped — tip ${tip} diverges from ${prRef}'s merged ${merged} (post-merge force-push); ` +
       `resolve by deleting manually (\`git branch -D ${skip.branch}\`) or pushing the follow-up commit`
     );
   }
+  if (skip.reason === 'unverifiable') {
+    const { tip, merged } = shortShaPair(skip);
+    return (
+      `${TAG} ⏭️  ${skip.branch} skipped — cannot verify tip ${tip} against ${prRef}'s merged ${merged}${skip.detail ? `: ${skip.detail}` : ''}; ` +
+      `fetch the missing commit or inspect the branch by hand before deleting it`
+    );
+  }
   if (skip.reason === 'latest-pr-unknown-state') {
     return `${TAG} ⏭️  ${skip.branch} skipped — ${prRef} has an unrecognized state`;
   }

package/.agents/scripts/lib/orchestration/merge-block-class.js

@@ -96,7 +96,15 @@ export const BLOCK_CLASSES = Object.freeze([
  * This is the classifier's four outputs PLUS `predicate-refused` (#4472),
  * emitted DIRECTLY for a headless refusal that never reached the
  * poll-exhaustion classifier — so it is a valid attribution value even though
- * `classifyMergeBlock` never produces it. (The Epic-era listeners that used to
+ * `classifyMergeBlock` never produces it. Story #5096 added
+ * `advisory-gate-red` on the same footing: a genuinely red NON-required check
+ * observed while GitHub reports the PR mergeable anyway
+ * (`mergeStateStatus: UNSTABLE`), which native auto-merge would land straight
+ * past. It is emitted directly by the arm and merge-wait phases — the
+ * classifier cannot produce it, because by construction GitHub is NOT blocking
+ * the merge, which is the entire problem it names. It is deliberately NOT in
+ * `BLOCK_CLASSES`, whose reachability invariant covers only what
+ * `classifyMergeBlock` returns. (The Epic-era listeners that used to
  * emit it, AutomergePredicate and AutomergeArmer, are gone; the value stays
  * because archived `merge.unlanded` records carry it and the schema enum
  * must keep validating them.) `isValidBlockClass` (and the `merge.unlanded` schema enum)
@@ -106,6 +114,7 @@ export const BLOCK_CLASSES = Object.freeze([
 export const MERGE_UNLANDED_BLOCK_CLASSES = Object.freeze([
   ...BLOCK_CLASSES,
   'predicate-refused',
+  'advisory-gate-red',
 ]);
 
 const BLOCK_CLASS_SET = new Set(MERGE_UNLANDED_BLOCK_CLASSES);