mandrel 2.34.0 → 2.36.0

package/.agents/scripts/lib/findings/route-finding.js

@@ -13,14 +13,15 @@
  *      stamped into Issue bodies.
  *   3. `routeFinding(finding, { searchIssues, searchCandidates })` — classify a
  *      finding against existing Issues into one of `new | update-existing |
- *      duplicate | regression-of-closed`. Routing is a two-stage pass: a
- *      meaning-first **semantic candidate** pass runs FIRST (when a
- *      `searchCandidates` port is injected, e.g. wired to
- *      `semantic-issue-search.js`), then the exact **fingerprint
- *      confirmation** pass runs SECOND over that candidate pool. When no
- *      semantic port is injected the helper falls back to a fingerprint-only
- *      lookup via the `searchIssues` port. Either way the ports query BOTH
- *      open and closed issues; a closed fingerprint match yields
+ *      duplicate | regression-of-closed`. Routing gathers a candidate pool,
+ *      then confirms identity against it. **Every wired port runs, and their
+ *      results union** (Story #5079): the exact `searchIssues(sha)` lookup is
+ *      what reliably retrieves an Issue by its footer sha, while the
+ *      meaning-first `searchCandidates` pass (wired to
+ *      `semantic-issue-search.js`) widens that pool to catch a reworded
+ *      finding whose sha has drifted. The semantic pass **adds** to the
+ *      fingerprint lookup; it never replaces it. Whichever ports are wired
+ *      query BOTH open and closed issues; a closed fingerprint match yields
  *      `regression-of-closed`.
  *
  * Pure orchestration: no network I/O lives here. The `searchIssues` /
@@ -455,36 +456,97 @@ function confirmCandidates(hits, { sha, semanticKey = '' }) {
 }
 
 /**
- * Route a finding against existing Issues with a two-stage pass.
- *
- * **Stage 1 — semantic candidate search (first).** When a `searchCandidates`
- * port is injected, it runs first to surface issues that *describe the same
- * problem by meaning* across BOTH open and closed issues (and, when the
- * caller wires it, an Epic's sub-issues). This widens the net beyond an exact
- * fingerprint so a reworded title or a moved file does not hide a real
- * duplicate. When no `searchCandidates` port is supplied the helper skips
- * straight to Stage 2 over the `searchIssues` lookup — the legacy
- * fingerprint-only behaviour, preserved verbatim.
- *
- * **Stage 2 — fingerprint confirmation (second).** Whatever candidates Stage 1
- * produced are filtered down to those that actually carry the finding's
- * fingerprint footer, then resolved:
+ * Union candidate pools into one flat pool, keeping first-seen order and
+ * dropping an issue number an earlier pool already contributed.
+ *
+ * The fingerprint pool is passed first, so when both ports return the same
+ * Issue it is that pool's record — the one retrieved by exact identity — that
+ * survives into confirmation. Records without a usable number are left for
+ * {@link confirmCandidates} to reject, exactly as a single port's would be.
+ *
+ * @param {Array<unknown>} pools
+ * @returns {Array<object>}
+ */
+function unionCandidatePools(pools) {
+  const seen = new Set();
+  return pools.flat().filter((issue) => {
+    const number = issue?.number;
+    if (typeof number !== 'number') return true;
+    const fresh = !seen.has(number);
+    seen.add(number);
+    return fresh;
+  });
+}
+
+/**
+ * Gather the candidate pool for a finding from every wired port.
+ *
+ * A run with a single wired port returns that port's result **verbatim**, so
+ * the fingerprint-only wiring (`qa-explore`, and every caller that injects no
+ * semantic port) keeps its behaviour exactly — including how a non-array
+ * return is handled downstream by {@link confirmCandidates}.
+ *
+ * Both ports are awaited together; a rejection from either propagates rather
+ * than degrading silently to a partial pool.
+ *
+ * @param {object} finding
+ * @param {string} sha — the finding's full fingerprint.
+ * @param {{ searchIssues?: Function, searchCandidates?: Function }} ports
+ * @returns {Promise<Array<object>|unknown>}
+ */
+async function gatherCandidates(finding, sha, ports) {
+  const call = (port, arg) => (typeof port === 'function' ? [port(arg)] : []);
+  const pools = await Promise.all([
+    ...call(ports.searchIssues, sha),
+    ...call(ports.searchCandidates, finding),
+  ]);
+  return pools.length === 1 ? pools[0] : unionCandidatePools(pools);
+}
+
+/**
+ * Route a finding against existing Issues: gather candidates, then confirm.
+ *
+ * **Gather — every wired port runs, and their pools union (Story #5079).** The
+ * two ports answer different questions and neither subsumes the other:
+ *
+ * - `searchIssues(sha)` is the **exact** lookup. A fingerprint sha is one
+ *   high-signal term, so it retrieves the Issue whose footer carries it.
+ * - `searchCandidates(finding)` is the **meaning-first** pass. It widens the
+ *   pool to Issues describing the same problem under a different title, so a
+ *   reworded finding or a moved file still confirms by semantic key.
+ *
+ * This was a ternary until Story #5079: an injected semantic port *replaced*
+ * the fingerprint lookup instead of widening it. Production always injects
+ * one, so `searchIssues` was dead code on the live path and dedup rested
+ * entirely on a ~20-token bag-of-words query that does not reliably retrieve
+ * the Issue. The audit loop consequently re-filed Stories it had already
+ * filed, against the workflow's "Never open a duplicate Issue" constraint.
+ * Running both ports and unioning their pools is what closes that loop.
+ *
+ * A port that rejects **propagates**. A pool gathered from only some of its
+ * sources is not a smaller pool, it is an unknown one, so the caller
+ * (`classifyGroupsAgainstGitHub`) must record a degraded lookup rather than
+ * report a confident `new`.
+ *
+ * **Confirm.** The pooled candidates are filtered down to those that actually
+ * carry the finding's fingerprint footer — or, when `semanticKeyConfirm` is
+ * on, its location-based semantic-key footer — then resolved:
  *   - An open match → `update-existing` (or `duplicate` when more than one
  *     open issue carries the fingerprint).
  *   - A closed match (no open match) → `regression-of-closed`.
  *   - No confirmed match → `new`.
  *
- * The decision enum is identical on both paths.
+ * The decision enum is identical however the candidates were gathered.
  *
  * @param {object} finding
  * @param {object} ports
  * @param {(sha: string) => Promise<Array<{ number: number, state: string, body?: string }>>} [ports.searchIssues]
- *   Fingerprint-keyed lookup over open+closed issues. Required when
- *   `searchCandidates` is not supplied.
+ *   Fingerprint-keyed lookup over open+closed issues. Runs whenever it is
+ *   supplied. Required when `searchCandidates` is not.
  * @param {(finding: object) => Promise<Array<{ number: number, state: string, title?: string, body?: string }>>} [ports.searchCandidates]
  *   Meaning-first candidate search over open+closed issues (and Epic
- *   sub-issues). When supplied, runs FIRST; its candidates are then
- *   fingerprint-confirmed.
+ *   sub-issues). Runs whenever it is supplied, alongside `searchIssues` rather
+ *   than instead of it; the union is then confirmed by footer.
  * @param {object} [options]
  * @param {boolean} [options.semanticKeyConfirm=false] — also confirm a
  *   candidate by the location-based semantic-key footer, not the fingerprint
@@ -510,15 +572,14 @@ export async function routeFinding(
   const { full: sha } = fingerprintFinding(finding);
   const semanticKey = options.semanticKeyConfirm ? semanticKeyFor(finding) : '';
 
-  // Stage 1: semantic candidate pass first (when wired); else fingerprint
-  // lookup. Both yield a candidate pool drawn from open AND closed issues.
-  const hits =
-    typeof searchCandidates === 'function'
-      ? await searchCandidates(finding)
-      : await searchIssues(sha);
+  // Gather: every wired port runs, and their pools union (Story #5079).
+  const hits = await gatherCandidates(finding, sha, {
+    searchIssues,
+    searchCandidates,
+  });
 
-  // Stage 2: confirm identity by fingerprint footer (and, when opted in, the
-  // location-based semantic-key footer) over the candidate pool.
+  // Confirm identity by fingerprint footer (and, when opted in, the
+  // location-based semantic-key footer) over the pooled candidates.
   const confirmed = confirmCandidates(hits, { sha, semanticKey });
 
   return decideFromConfirmed(confirmed, sha);
@@ -526,6 +587,8 @@ export async function routeFinding(
 
 export const __testing = {
   MARKER,
+  gatherCandidates,
+  unionCandidatePools,
   SEMANTIC_MARKER,
   SEP,
   confirmCandidates,

package/.agents/scripts/lib/maintainability-utils.js

@@ -6,6 +6,7 @@ import { POOL_SERIAL_THRESHOLD, runOnPool } from './cpu-pool.js';
 import { Logger } from './Logger.js';
 import { scoreFile } from './maintainability-engine.js';
 import { isScored, reportUnscorable } from './maintainability-unscorable.js';
+import { isScorableSourceFile } from './source-extensions.js';
 
 const MAINTAINABILITY_WORKER_URL = new URL(
   './workers/maintainability-worker.js',
@@ -16,17 +17,6 @@ const MAINTAINABILITY_WORKER_URL = new URL(
 // POOL_SERIAL_THRESHOLD docstring for the tuning rationale).
 const SERIAL_THRESHOLD = POOL_SERIAL_THRESHOLD;
 
-const JS_EXTS = new Set(['.js', '.mjs', '.cjs']);
-const TS_EXTS = new Set(['.ts', '.tsx', '.mts', '.cts']);
-const SUPPORTED_EXTS = new Set([...JS_EXTS, ...TS_EXTS]);
-
-/**
- * @returns {boolean} True when the path's extension is one the engines score.
- */
-function isSupportedSourceFile(filePath) {
-  return SUPPORTED_EXTS.has(path.extname(String(filePath)).toLowerCase());
-}
-
 const IGNORED_DIRS = new Set([
   'node_modules',
   '.git',
@@ -68,8 +58,10 @@ export function isIgnoredByGlobs(filePath, ignoreGlobs = [], cwd) {
 }
 
 /**
- * Recursively scans a directory for JS/TS source files. Accepts `.js`,
- * `.mjs`, `.cjs`, `.ts`, `.tsx`, `.mts`, and `.cts`. Directories listed
+ * Recursively scans a directory for JS/TS source files, selecting them by
+ * the shared `SCORABLE_SOURCE_EXTENSIONS` set (`source-extensions.js`) so the
+ * walk, the coverage-freshness check and the close-validation CRAP projection
+ * cannot drift apart. Directories listed
  * in `IGNORED_DIRS` (including `coverage` and `.next`, added in 5.29.0
  * to skip vitest's istanbul HTML scaffolding and Next.js build output)
  * are skipped.
@@ -101,7 +93,7 @@ export function scanDirectory(dir, fileList = [], opts = {}) {
       if (!IGNORED_DIRS.has(entry.name)) {
         scanDirectory(filePath, fileList, opts);
       }
-    } else if (entry.isFile() && isSupportedSourceFile(entry.name)) {
+    } else if (entry.isFile() && isScorableSourceFile(entry.name)) {
       if (isIgnoredByGlobs(filePath, ignoreGlobs, matchCwd)) {
         continue;
       }

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`;
   }