mandrel 2.35.0 → 2.37.0

package/.agents/scripts/lib/install-cmd-parser.js

@@ -17,7 +17,7 @@ import { spawnSync as defaultSpawnSync } from 'node:child_process';
  * @param {string} installCmd
  * @returns {{ bin: string, args: string[], shell: boolean }}
  */
-export function parseInstallCmd(installCmd) {
+function parseInstallCmd(installCmd) {
   const tokens = String(installCmd ?? '')
     .trim()
     .split(/\s+/)

package/.agents/scripts/lib/knip-entry-sync.js

@@ -59,6 +59,7 @@ import {
   resolveKnipEntryPatterns,
   __testing as resolverTesting,
 } from './knip-config-resolver.js';
+import { stripJsComments } from './source-text/strip-js-comments.js';
 
 // Only `resolveEntrySync` and `renderEntrySyncReport` are public — they are
 // what `check-knip-entries.js` calls. Everything else is module-private and
@@ -89,63 +90,6 @@ const INVOCATION_SURFACES = Object.freeze([
   { kind: 'dir', at: SCRIPTS_DIR, test: /\.js$/ },
 ]);
 
-/**
- * Strip line and block comments from JavaScript source, preserving string and
- * template literals so a `'https://…'` or a `` `${x}//y` `` is not mangled.
- *
- * Comments are stripped before scanning `.js` surfaces so a JSDoc paragraph
- * that merely *names* a CLI ("superseded by `node .agents/scripts/foo.js`")
- * cannot confer liveness on it. Several such mentions exist today; every one
- * of them is prose about a script's internals, not a call.
- *
- * Replaces comment bodies with equivalent whitespace rather than deleting
- * them, so byte offsets and line numbers survive for any future caller that
- * wants to report a position.
- *
- * @param {string} source
- * @returns {string}
- */
-function stripJsComments(source) {
-  const text = String(source ?? '');
-  let out = '';
-  let i = 0;
-  const blank = (s) => s.replace(/[^\n]/g, ' ');
-  while (i < text.length) {
-    const two = text.slice(i, i + 2);
-    if (two === '//') {
-      const end = text.indexOf('\n', i);
-      const stop = end === -1 ? text.length : end;
-      out += blank(text.slice(i, stop));
-      i = stop;
-    } else if (two === '/*') {
-      const end = text.indexOf('*/', i + 2);
-      const stop = end === -1 ? text.length : end + 2;
-      out += blank(text.slice(i, stop));
-      i = stop;
-    } else {
-      const ch = text[i];
-      if (ch === "'" || ch === '"' || ch === '`') {
-        let j = i + 1;
-        while (j < text.length) {
-          if (text[j] === '\\') {
-            j += 2;
-            continue;
-          }
-          if (text[j] === ch) break;
-          j += 1;
-        }
-        const stop = Math.min(j + 1, text.length);
-        out += text.slice(i, stop);
-        i = stop;
-      } else {
-        out += ch;
-        i += 1;
-      }
-    }
-  }
-  return out;
-}
-
 /**
  * Recursively list files under `dir`, skipping `node_modules` and `.git`.
  *

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

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { minimatch } from 'minimatch';
+import { Minimatch } from 'minimatch';
 import { canonicalise as canonicalisePath } from './baselines/path-canon.js';
 import { POOL_SERIAL_THRESHOLD, runOnPool } from './cpu-pool.js';
 import { Logger } from './Logger.js';
@@ -27,6 +27,57 @@ const IGNORED_DIRS = new Set([
   '.next',
 ]);
 
+/**
+ * Compiled-matcher cache for `isIgnoredByGlobs`, keyed on the pattern list.
+ *
+ * `minimatch(path, glob)` re-parses `glob` into an AST on every call, so the
+ * scan was paying O(files × globs) glob *compilations* to answer O(files ×
+ * globs) glob *matches* — 12–17 ms over the 619-file tree against 0.5 ms
+ * once the patterns are compiled (Story #5109). The number of distinct
+ * pattern lists in a process is tiny (one per gate), and each list is
+ * config-derived and immutable, so an unbounded `Map` keyed on the joined
+ * patterns is bounded in practice.
+ *
+ * Each entry also memoises the per-path verdict. The baseline gates ask the
+ * same question about the same path many times over — `crap.json` carries
+ * thousands of method rows spread over a few hundred files, and the evaluate
+ * phase filters every row — so the second and later asks about a path cost a
+ * `Map` lookup instead of a globstar walk. Both caches are keyed on
+ * config-derived, immutable inputs, and both are bounded by the tree the
+ * process is scanning.
+ *
+ * `\u0000` is the join separator because it cannot occur in a glob, so two
+ * different lists cannot collide onto one key.
+ *
+ * @type {Map<string, {matchers: import('minimatch').Minimatch[], verdicts: Map<string, boolean>}>}
+ */
+const IGNORE_MATCHER_CACHE = new Map();
+
+/**
+ * Compile (once) the `Minimatch` instances for a pattern list, alongside the
+ * per-path verdict memo that shares their lifetime.
+ *
+ * Non-string patterns are dropped rather than compiled — `minimatch()` would
+ * have thrown on them, and the functional call site never fed it any, so
+ * dropping preserves the observable result set.
+ *
+ * @param {string[]} ignoreGlobs
+ * @returns {{matchers: import('minimatch').Minimatch[], verdicts: Map<string, boolean>}}
+ */
+function ignoreMatcherEntry(ignoreGlobs) {
+  const key = ignoreGlobs.join('\u0000');
+  let entry = IGNORE_MATCHER_CACHE.get(key);
+  if (entry) return entry;
+  entry = {
+    matchers: ignoreGlobs
+      .filter((g) => typeof g === 'string')
+      .map((g) => new Minimatch(g, { dot: true })),
+    verdicts: new Map(),
+  };
+  IGNORE_MATCHER_CACHE.set(key, entry);
+  return entry;
+}
+
 /**
  * Test whether an absolute (or repo-relative) file path matches any of the
  * configured `ignoreGlobs`. This is the single source of truth for how the
@@ -39,22 +90,62 @@ const IGNORED_DIRS = new Set([
  *
  * Matching mirrors `scanDirectory`: the path is reduced to a canonicalised,
  * POSIX, repo-relative form and tested against each glob with minimatch's
- * `{ dot: true }` so dot-prefixed roots like `.agents/` match.
+ * `{ dot: true }` so dot-prefixed roots like `.agents/` match. The patterns
+ * are compiled at most once per distinct list (see `IGNORE_MATCHER_CACHE`);
+ * the matched set is identical to the functional `minimatch()` call this
+ * replaced, which is what the `gate-scan-fast-path` test pins over the real
+ * configured `ignoreGlobs`.
  *
  * @param {string} filePath absolute or relative path to the source file
  * @param {string[]} ignoreGlobs minimatch patterns; empty/absent is a no-op
  * @param {string} [cwd] root for repo-relative resolution; defaults to cwd
  * @returns {boolean} true when the file matches at least one ignore glob
  */
-export function isIgnoredByGlobs(filePath, ignoreGlobs = [], cwd) {
-  if (!Array.isArray(ignoreGlobs) || ignoreGlobs.length === 0) return false;
-  const matchCwd = cwd ?? process.cwd();
+/**
+ * Reduce an absolute-or-relative path to the canonicalised, POSIX,
+ * repo-relative form the ignore patterns are written against.
+ *
+ * @param {string} filePath
+ * @param {string} matchCwd
+ * @returns {string}
+ */
+function canonicalRelPath(filePath, matchCwd) {
   const absFilePath = path.isAbsolute(filePath)
     ? filePath
     : path.resolve(matchCwd, filePath);
   const rawRel = path.relative(matchCwd, absFilePath).replace(/\\/g, '/');
-  const relPath = canonicalisePath(rawRel);
-  return ignoreGlobs.some((g) => minimatch(relPath, g, { dot: true }));
+  return canonicalisePath(rawRel);
+}
+
+/**
+ * Answer "does this path match any of the entry's patterns", consulting and
+ * populating the entry's verdict memo.
+ *
+ * Split out of `isIgnoredByGlobs` rather than inlined: the memo's
+ * hit/miss test is a branch, and folding it into the caller pushed that
+ * function from cyclomatic 4 to 5 — over the per-method CRAP contract the
+ * pre-push preview enforces. The lookup belongs beside the cache it reads
+ * anyway, and the hot function keeps a flat shape.
+ *
+ * @param {{matchers: import('minimatch').Minimatch[], verdicts: Map<string, boolean>}} entry
+ * @param {string} relPath Canonicalised, POSIX, repo-relative path.
+ * @returns {boolean}
+ */
+function memoisedIgnoreVerdict(entry, relPath) {
+  const memoised = entry.verdicts.get(relPath);
+  if (memoised !== undefined) return memoised;
+  const verdict = entry.matchers.some((m) => m.match(relPath));
+  entry.verdicts.set(relPath, verdict);
+  return verdict;
+}
+
+export function isIgnoredByGlobs(filePath, ignoreGlobs = [], cwd) {
+  if (!Array.isArray(ignoreGlobs) || ignoreGlobs.length === 0) return false;
+  const matchCwd = cwd ?? process.cwd();
+  return memoisedIgnoreVerdict(
+    ignoreMatcherEntry(ignoreGlobs),
+    canonicalRelPath(filePath, matchCwd),
+  );
 }
 
 /**
@@ -107,7 +198,7 @@ export function scanDirectory(dir, fileList = [], opts = {}) {
  * Calculates maintainability scores for a list of file paths.
  *
  * Each file's transpile-then-analyze unit is dispatched to a
- * worker_threads pool sized to `os.availableParallelism()`. Workers
+ * worker_threads pool whose width `runOnPool` resolves. Workers
  * are recycled across files so TypeScript loads at most once per
  * worker. The pool is bypassed for batches of fewer than
  * `SERIAL_THRESHOLD` files because spawn overhead dominates at small
@@ -129,9 +220,16 @@ export function scanDirectory(dir, fileList = [], opts = {}) {
  * and nothing said so.
  *
  * @param {string[]} paths
+ * @param {{serialThreshold?: number}} [opts] `serialThreshold` overrides the
+ *   pool-vs-serial cutover for this call only. Production callers omit it;
+ *   the parity tests use it to drive the pooled path on a small fixture set
+ *   rather than materialising 256 files to clear the cutover.
  * @returns {Promise<Record<string, number>>}
  */
-export async function calculateAll(paths) {
+export async function calculateAll(paths, opts = {}) {
+  const serialThreshold = Number.isFinite(opts?.serialThreshold)
+    ? opts.serialThreshold
+    : SERIAL_THRESHOLD;
   const cwd = process.cwd();
   const indexed = paths.map((p) => ({
     abs: p,
@@ -139,7 +237,7 @@ export async function calculateAll(paths) {
   }));
 
   let perFile;
-  if (indexed.length < SERIAL_THRESHOLD) {
+  if (indexed.length < serialThreshold) {
     perFile = indexed.map(({ abs, relPath }) => {
       try {
         return { relPath, ...scoreFile(abs) };

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

@@ -94,6 +94,7 @@ const FRAMEWORK_SCRIPT_BASENAMES = Object.freeze([
   'check-cyclomatic.js',
   'check-dead-exports.js',
   'check-doc-links.js',
+  'check-generated-validator.js',
   'check-gherkin-corpus.js',
   'check-knip-entries.js',
   'check-lifecycle-lint.js',
@@ -113,7 +114,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`;
   }