mandrel 2.40.0 → 2.42.0

package/.agents/scripts/lib/orchestration/check-baselines/phases/evaluate.js

@@ -7,22 +7,16 @@
  * @module lib/orchestration/check-baselines/phases/evaluate
  */
 
-import { resolveKindRefreshOverrides } from '../../../baselines/env-overrides.js';
-import { readRangeSubjectsTouchingFile } from '../../../baselines/git-base.js';
 import {
   checkBaselineSemantics,
   checkKernelVersion,
   getKindModule,
 } from '../../../baselines/kernel.js';
 import * as reader from '../../../baselines/reader.js';
-import { Logger } from '../../../Logger.js';
 import { isIgnoredByGlobs } from '../../../maintainability-utils.js';
 import { applyTolerance, evaluateCompare, runCompareStage } from './compare.js';
 import { applyFloors, flattenBreaches } from './floors.js';
-import { DEFAULT_BASELINE_PATHS } from './parse-args.js';
-
-/** Default refresh-tag substring when the gate omits `refreshTag`. */
-const DEFAULT_REFRESH_TAG = 'baseline-refresh:';
+import { applyRefreshAcknowledgment } from './refresh-ack.js';
 
 /**
  * Defense-in-depth against an `ignoreGlobs`-poisoned baseline (Epic #4326
@@ -87,97 +81,6 @@ function loadHeadBaseline(kind, cwd, configPath) {
   }
 }
 
-/**
- * Resolve the one-shot refresh trigger for any ratcheted kind (Story #4802,
- * generalizing Story #151's bundle-size env flag and Story #4731's
- * maintainability env-or-commit-tag pair). Two paths, either of which
- * acknowledges:
- *
- *   1. Env parity: `<KIND>_REFRESH=1` (the manual override) — upper-snaked,
- *      so the two pre-existing names (`BUNDLE_SIZE_REFRESH`,
- *      `MAINTAINABILITY_REFRESH`) keep working unchanged.
- *   2. Commit tag: a commit in the compared range `<baseRef>..HEAD` whose
- *      subject contains the configured `refreshTag` AND whose diff touches
- *      that kind's baseline file. One-shot by construction — once merged, the
- *      refreshed baseline becomes the base and the tag leaves the range.
- *
- * The tag is matched as a plain substring of a conventional commit subject, so
- * commitlint stays satisfied (e.g. `chore(baselines): baseline-refresh: …`).
- *
- * Fails closed: a kind whose baseline path is neither configured nor present
- * in `DEFAULT_BASELINE_PATHS` simply skips the commit-tag path rather than
- * throwing, leaving the run un-acknowledged.
- *
- * @returns {{ triggered: boolean, reasons: string[] }}
- */
-function resolveRefreshTrigger({ kind, gateBlock, cmp, cwd, env }) {
-  const reasons = [];
-  const { acknowledged: envAck, overrides } = resolveKindRefreshOverrides(
-    kind,
-    env,
-  );
-  if (envAck) reasons.push(...overrides);
-
-  const baseRef = cmp?.baseRef ?? null;
-  if (baseRef) {
-    const refreshTag =
-      typeof gateBlock?.refreshTag === 'string' && gateBlock.refreshTag.length
-        ? gateBlock.refreshTag
-        : DEFAULT_REFRESH_TAG;
-    const baselinePath =
-      typeof gateBlock?.baselinePath === 'string' &&
-      gateBlock.baselinePath.length
-        ? gateBlock.baselinePath
-        : DEFAULT_BASELINE_PATHS[kind];
-    if (typeof baselinePath === 'string' && baselinePath.length) {
-      const subjects = readRangeSubjectsTouchingFile(baseRef, baselinePath, {
-        cwd,
-      });
-      const match = subjects.find((s) => s.includes(refreshTag));
-      if (match) {
-        reasons.push(
-          `refresh commit "${match}" (subject contains ${JSON.stringify(refreshTag)}, touches ${baselinePath})`,
-        );
-      }
-    }
-  }
-
-  return { triggered: reasons.length > 0, reasons };
-}
-
-/**
- * One-shot baseline refresh/acknowledge for any ratcheted kind (Story #4802).
- * When triggered (env flag OR a `baseline-refresh:`-tagged range commit
- * touching that kind's baseline), demote every head-vs-base regression to
- * `unchanged` for this run only — floors still apply, so a row below its floor
- * still breaches. The trigger is read fresh every run and never persisted:
- * post-merge the refreshed baseline is the new base and the tag leaves the
- * range, so the ratchet returns to full strength automatically.
- *
- * A no-op absent a trigger, so an unacknowledged run of any kind reports its
- * regressions exactly as before.
- */
-function applyRefreshAcknowledgment(kind, compareOutput, ctx) {
-  const { triggered, reasons } = resolveRefreshTrigger({ ...ctx, kind });
-  if (!triggered || compareOutput.regressions.length === 0) {
-    return { compareOutput, acknowledged: false };
-  }
-  Logger.warn(
-    `[${kind}] ⚠ ${reasons.join('; ')} — ` +
-      `${compareOutput.regressions.length} regression(s) acknowledged for this run only; ` +
-      'floors still enforced. This does not persist: once the refresh is the ' +
-      'new base the ratchet re-enforces at full strength.',
-  );
-  return {
-    acknowledged: true,
-    compareOutput: {
-      ...compareOutput,
-      regressions: [],
-      unchanged: [...compareOutput.unchanged, ...compareOutput.regressions],
-    },
-  };
-}
-
 function buildGateReport({
   kind,
   gateBlock,
@@ -186,7 +89,7 @@ function buildGateReport({
   breaches,
   compareOutput,
   cmp,
-  acknowledged,
+  ack,
 }) {
   const kernel = checkKernelVersion(kind, baseline.kernelVersion);
   return {
@@ -212,7 +115,12 @@ function buildGateReport({
     // the JSON report alone.
     baseRead: cmp.baseRead === true,
     generatedAt: baseline.generatedAt,
-    acknowledged,
+    acknowledged: ack.acknowledged,
+    // Story #5179 — `acknowledged` is now a PARTIAL statement: a refresh commit
+    // clears only the rows it actually refreshed, so a run can acknowledge some
+    // regressions and still fail on others. Naming the acknowledged keys makes
+    // which-half-was-which readable from the JSON report without re-walking git.
+    acknowledgedKeys: ack.acknowledgedKeys,
   };
 }
 
@@ -258,17 +166,16 @@ export async function evaluateKind({
     cmp,
     cwd,
     env,
+    headBaseline: baseline,
   });
-  const compareOutput = ack.compareOutput;
-  const acknowledged = ack.acknowledged;
   return buildGateReport({
     kind,
     gateBlock,
     baseline,
     findings,
     breaches,
-    compareOutput,
+    compareOutput: ack.compareOutput,
     cmp,
-    acknowledged,
+    ack,
   });
 }

package/.agents/scripts/lib/orchestration/check-baselines/phases/refresh-ack.js

@@ -0,0 +1,320 @@
+/**
+ * refresh-ack.js — the one-shot baseline refresh acknowledgment (Story #5179).
+ *
+ * Extracted from `evaluate.js`, where it grew from a bundle-size env flag
+ * (Story #151) through a maintainability env-or-commit-tag pair (Story #4731)
+ * into the kind-generic trigger (Story #4802). Story #5179 narrowed the
+ * commit-tag arm from a whole-run blanket to the rows the tagged commit
+ * actually refreshed, which is enough logic to own its own module.
+ *
+ * @module lib/orchestration/check-baselines/phases/refresh-ack
+ */
+
+import { resolveKindRefreshOverrides } from '../../../baselines/env-overrides.js';
+import {
+  readBaseFromGit,
+  readRangeCommitsTouchingFile,
+} from '../../../baselines/git-base.js';
+import { getKindModule } from '../../../baselines/kernel.js';
+import { Logger } from '../../../Logger.js';
+import { applyTolerance } from './compare.js';
+import { DEFAULT_BASELINE_PATHS } from './parse-args.js';
+
+/** Default refresh-tag substring when the gate omits `refreshTag`. */
+const DEFAULT_REFRESH_TAG = 'baseline-refresh:';
+
+function resolveBaselinePath(kind, gateBlock) {
+  const configured =
+    typeof gateBlock?.baselinePath === 'string' && gateBlock.baselinePath.length
+      ? gateBlock.baselinePath
+      : null;
+  return configured ?? DEFAULT_BASELINE_PATHS[kind] ?? null;
+}
+
+function resolveRefreshTag(gateBlock) {
+  return typeof gateBlock?.refreshTag === 'string' &&
+    gateBlock.refreshTag.length
+    ? gateBlock.refreshTag
+    : DEFAULT_REFRESH_TAG;
+}
+
+/**
+ * Resolve the one-shot refresh trigger for any ratcheted kind. Two paths, either
+ * of which acknowledges:
+ *
+ *   1. Env parity: `<KIND>_REFRESH=1` (the manual override) — upper-snaked, so
+ *      the two pre-existing names (`BUNDLE_SIZE_REFRESH`,
+ *      `MAINTAINABILITY_REFRESH`) keep working unchanged.
+ *   2. Commit tag: a commit in the compared range `<baseRef>..HEAD` whose
+ *      subject contains the configured `refreshTag` AND whose diff touches that
+ *      kind's baseline file. One-shot by construction — once merged, the
+ *      refreshed baseline becomes the base and the tag leaves the range.
+ *
+ * The tag is matched as a plain substring of a conventional commit subject, so
+ * commitlint stays satisfied (e.g. `chore(baselines): baseline-refresh: …`).
+ *
+ * The two arms are reported separately because Story #5179 scopes them
+ * differently: see `applyRefreshAcknowledgment`.
+ *
+ * Fails closed: a kind whose baseline path is neither configured nor present in
+ * `DEFAULT_BASELINE_PATHS` simply skips the commit-tag path rather than
+ * throwing, leaving that arm un-acknowledged.
+ *
+ * @returns {{ triggered: boolean, reasons: string[], envAcknowledged: boolean,
+ *   refreshCommits: { sha: string, subject: string }[], baselinePath: string | null }}
+ */
+function resolveRefreshTrigger({ kind, gateBlock, cmp, cwd, env }) {
+  const reasons = [];
+  const { acknowledged: envAcknowledged, overrides } =
+    resolveKindRefreshOverrides(kind, env);
+  if (envAcknowledged) reasons.push(...overrides);
+
+  const baselinePath = resolveBaselinePath(kind, gateBlock);
+  const refreshCommits = [];
+  const baseRef = cmp?.baseRef ?? null;
+  if (baseRef && typeof baselinePath === 'string' && baselinePath.length) {
+    const refreshTag = resolveRefreshTag(gateBlock);
+    const commits = readRangeCommitsTouchingFile(baseRef, baselinePath, {
+      cwd,
+    });
+    for (const commit of commits) {
+      if (!commit.subject.includes(refreshTag)) continue;
+      refreshCommits.push(commit);
+      reasons.push(
+        `refresh commit "${commit.subject}" (subject contains ${JSON.stringify(refreshTag)}, touches ${baselinePath})`,
+      );
+    }
+  }
+
+  return {
+    triggered: reasons.length > 0,
+    reasons,
+    envAcknowledged,
+    refreshCommits,
+    baselinePath,
+  };
+}
+
+/**
+ * Read the baseline rows as of one refresh commit. Returns `null` — never
+ * throws and never a partial row set — when the blob is absent, unreadable or
+ * unparseable at that SHA. The caller treats `null` as "this commit
+ * acknowledges nothing", which keeps the ratchet at full strength rather than
+ * acknowledging on a guess.
+ */
+function readRowsAtCommit(sha, baselinePath, cwd) {
+  let raw;
+  try {
+    raw = readBaseFromGit(sha, baselinePath, { cwd });
+  } catch {
+    return null;
+  }
+  if (raw === null) return null;
+  try {
+    const payload = JSON.parse(raw);
+    return Array.isArray(payload?.rows) ? payload.rows : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Classify the head rows against one refresh commit's rows, using the kind's
+ * own classifier and the gate's own tolerance.
+ *
+ * Row identity is deliberately never derived here. A kind's `keyField` names
+ * the row property the kind is *about*, which is not always its compare key:
+ * CRAP declares `keyField: 'path'` but keys rows as `path::method@startLine`,
+ * because one file holds many methods. Reading `row[keyField]` would produce a
+ * key matching no regression, silently acknowledging nothing for that kind.
+ * `compare()` is the one thing that knows a kind's key, so every key here comes
+ * back out of it — the same reason direction and tolerance are delegated rather
+ * than reimplemented.
+ *
+ * That also collapses both tests into one classification:
+ *
+ *   - `regressions` — present in both, worse at head: post-refresh drift.
+ *   - `improvements` / `unchanged` — present in both, no worse: the rows this
+ *     commit vouches for.
+ *   - `additions` — present at head but absent from the refresh blob, i.e.
+ *     never refreshed by this commit, so deliberately in neither set.
+ *
+ * @returns {{ ok: string[], drifted: string[] } | null} null when the
+ *   classifier is unusable, which acknowledges nothing.
+ */
+function classifyAgainstRefresh({ mod, headRows, refreshRows, tolerance }) {
+  try {
+    const result = mod.compare({ rows: headRows }, { rows: refreshRows });
+    const tolerated = applyTolerance(
+      {
+        regressions: result?.regressions ?? [],
+        improvements: result?.improvements ?? [],
+        unchanged: result?.unchanged ?? [],
+        additions: result?.additions ?? [],
+      },
+      tolerance ?? null,
+    );
+    return {
+      ok: [...tolerated.improvements, ...tolerated.unchanged].map((r) => r.key),
+      drifted: tolerated.regressions.map((r) => r.key),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Which regression keys are acknowledgeable by the tagged commits (Story #5179)?
+ *
+ * The acknowledgment is a statement about what a refresh commit re-scored, so a
+ * key is acknowledgeable only when the commit both covered it and recorded a
+ * value the head has not since fallen below. Both tests come out of
+ * `classifyAgainstRefresh` above:
+ *
+ *   1. **Row membership** — a key absent from the refresh blob lands in
+ *      `additions`, never in `ok`. This was the larger half of the leak: a
+ *      single tagged commit cleared regressions on rows in directories it never
+ *      touched.
+ *   2. **No post-refresh drift** — a key worse at head than the commit recorded
+ *      lands in `drifted`. Drift from commits landing AFTER the refresh is what
+ *      "the baseline commit must be the branch's last score-moving commit" asks
+ *      for by convention and nothing enforced.
+ *
+ * Fails closed at every step: an unreadable blob, a missing `compare`, or a
+ * classifier that throws contributes nothing, so those regressions stand.
+ *
+ * @returns {Set<string>}
+ */
+function acknowledgeableKeys({
+  kind,
+  headBaseline,
+  refreshCommits,
+  baselinePath,
+  cwd,
+  tolerance,
+}) {
+  const acknowledgeable = new Set();
+  if (refreshCommits.length === 0) return acknowledgeable;
+  if (typeof baselinePath !== 'string' || baselinePath.length === 0)
+    return acknowledgeable;
+
+  let mod;
+  try {
+    mod = getKindModule(kind);
+  } catch {
+    return acknowledgeable;
+  }
+  if (typeof mod?.compare !== 'function') return acknowledgeable;
+
+  const headRows = Array.isArray(headBaseline?.rows) ? headBaseline.rows : [];
+  // `readRangeCommitsTouchingFile` returns newest-first, and a key the newest
+  // refresh already ruled on is not reopened by an older one: the newest is the
+  // state the branch is asking to be held to.
+  const decided = new Set();
+  for (const { sha } of refreshCommits) {
+    const refreshRows = readRowsAtCommit(sha, baselinePath, cwd);
+    if (refreshRows === null) continue;
+    const verdict = classifyAgainstRefresh({
+      mod,
+      headRows,
+      refreshRows,
+      tolerance,
+    });
+    if (verdict === null) continue;
+    for (const key of verdict.ok) {
+      if (decided.has(key)) continue;
+      decided.add(key);
+      acknowledgeable.add(key);
+    }
+    for (const key of verdict.drifted) decided.add(key);
+  }
+  return acknowledgeable;
+}
+
+function partitionRegressions(regressions, isAcknowledgeable) {
+  const acknowledged = [];
+  const kept = [];
+  for (const reg of regressions) {
+    if (isAcknowledgeable(reg)) acknowledged.push(reg);
+    else kept.push(reg);
+  }
+  return { acknowledged, kept };
+}
+
+function logAcknowledgment({ kind, reasons, acknowledged, kept }) {
+  const held =
+    kept.length > 0
+      ? `${kept.length} regression(s) NOT acknowledged (outside the refreshed rows, or drifted further after the refresh) and still fail the gate; `
+      : '';
+  Logger.warn(
+    `[${kind}] ⚠ ${reasons.join('; ')} — ` +
+      `${acknowledged.length} regression(s) acknowledged for this run only; ` +
+      `${held}floors still enforced. This does not persist: once the refresh is ` +
+      'the new base the ratchet re-enforces at full strength.',
+  );
+}
+
+/**
+ * One-shot baseline refresh/acknowledge for any ratcheted kind. When triggered,
+ * demote acknowledged head-vs-base regressions to `unchanged` for this run only
+ * — floors still apply, so a row below its floor still breaches. The trigger is
+ * read fresh every run and never persisted: post-merge the refreshed baseline is
+ * the new base and the tag leaves the range, so the ratchet returns to full
+ * strength automatically.
+ *
+ * The two trigger arms are scoped differently, deliberately:
+ *
+ * - **Commit tag** — scoped to the rows the tagged commits actually refreshed,
+ *   per `acknowledgeableKeys`. Before Story #5179 this cleared every regression
+ *   in the range, so a branch merged carrying a stale row and the ratchet ran
+ *   loose on that file; the failure recurred six times.
+ * - **Env parity** (`<KIND>_REFRESH=1`) — stays whole-run. There is no commit to
+ *   anchor row-scoping to, and setting the variable is an explicit, deliberate
+ *   operator act rather than a signal inferred from history.
+ *
+ * A no-op absent a trigger, so an unacknowledged run of any kind reports its
+ * regressions exactly as before.
+ *
+ * @returns {{ compareOutput: object, acknowledged: boolean, acknowledgedKeys: string[] }}
+ */
+export function applyRefreshAcknowledgment(kind, compareOutput, ctx) {
+  const trigger = resolveRefreshTrigger({ ...ctx, kind });
+  if (!trigger.triggered || compareOutput.regressions.length === 0) {
+    return { compareOutput, acknowledged: false, acknowledgedKeys: [] };
+  }
+
+  let isAcknowledgeable;
+  if (trigger.envAcknowledged) {
+    isAcknowledgeable = () => true;
+  } else {
+    const keys = acknowledgeableKeys({
+      kind,
+      headBaseline: ctx.headBaseline,
+      refreshCommits: trigger.refreshCommits,
+      baselinePath: trigger.baselinePath,
+      cwd: ctx.cwd,
+      tolerance: ctx.gateBlock?.tolerance ?? null,
+    });
+    isAcknowledgeable = (reg) => keys.has(reg.key);
+  }
+
+  const { acknowledged, kept } = partitionRegressions(
+    compareOutput.regressions,
+    isAcknowledgeable,
+  );
+  if (acknowledged.length === 0) {
+    return { compareOutput, acknowledged: false, acknowledgedKeys: [] };
+  }
+
+  logAcknowledgment({ kind, reasons: trigger.reasons, acknowledged, kept });
+
+  return {
+    acknowledged: true,
+    acknowledgedKeys: acknowledged.map((reg) => reg.key),
+    compareOutput: {
+      ...compareOutput,
+      regressions: kept,
+      unchanged: [...compareOutput.unchanged, ...acknowledged],
+    },
+  };
+}

package/.agents/scripts/lib/orchestration/check-baselines/phases/report.js

@@ -34,7 +34,14 @@ function formatGateLine(g) {
     g.baseRef && g.baseRead === false
       ? ' [baseRead=false — compare skipped]'
       : '';
-  const ack = g.acknowledged ? ' [ACKNOWLEDGED — this run only]' : '';
+  // Story #5179 — a refresh commit acknowledges only the rows it refreshed, so
+  // the count says how much was cleared and the status ahead of it still shows
+  // FAIL when regressions outside those rows survived. `buildGateReport` always
+  // sets `acknowledgedKeys` alongside `acknowledged` from the same result
+  // object, so the array needs no guard of its own here.
+  const ack = g.acknowledged
+    ? ` [ACKNOWLEDGED ${g.acknowledgedKeys.length} row(s) — this run only]`
+    : '';
   return `  - ${g.kind}: ${status}${drift}${baseRef}${baseRead}${ack}`;
 }
 

package/.agents/scripts/lib/orchestration/dependency-candidates.js

@@ -0,0 +1,139 @@
+/**
+ * dependency-candidates.js — open Stories a newly planned Story may need to
+ * wait for.
+ *
+ * Story #5155. `depends_on[]` has always ordered *siblings within one plan*.
+ * Nothing surfaced the other ordering that actually bites: a Story authored
+ * today that edits a file an already-open Story from an earlier plan is going
+ * to rewrite. Delivered concurrently, the second lands on a base the first
+ * just changed — and the planner had no way to see it coming, because the
+ * duplicate search asks "is this the same Story?" (title/body similarity),
+ * never "does this Story touch what I am about to touch?".
+ *
+ * Overlap here is therefore computed on **declared footprints**, not prose:
+ * the seed's `predictedPaths` against each open Story's parsed `changes[]`,
+ * via the same `storyFootprint` the wave runner uses to withhold colliding
+ * Stories at dispatch. That is deliberate — the planner sees the collision the
+ * runtime would later enforce, one layer earlier and while it is still cheap
+ * to order around.
+ *
+ * The result is **advisory**: an overlap is a prompt to consider an edge, not
+ * proof one is needed. Two Stories can touch a shared barrel file with no real
+ * ordering between them; only the operator knows.
+ *
+ * @module lib/orchestration/dependency-candidates
+ * @see Story #5155
+ */
+
+import { Logger } from '../Logger.js';
+import { TYPE_LABELS } from '../label-constants.js';
+import { parse as parseStoryBody } from '../story-body/story-body.js';
+import { storyFootprint } from '../wave-runner/footprint.js';
+
+/**
+ * Build an issue URL for a Story the provider returned without one.
+ *
+ * @param {number} id
+ * @param {{ owner?: string, repo?: string }} [opts]
+ * @returns {string}
+ */
+function buildStoryUrl(id, { owner, repo } = {}) {
+  if (owner && repo) return `https://github.com/${owner}/${repo}/issues/${id}`;
+  return `#${id}`;
+}
+
+/**
+ * Read one open Story's declared footprint.
+ *
+ * Total by construction: an unparseable body yields an empty footprint, which
+ * intersects with nothing and drops the Story from the candidate list. A
+ * hand-written Story with no `## Changes` section is exactly that case, and it
+ * is the right outcome — there is no declared footprint to collide with.
+ *
+ * @param {object} issue
+ * @returns {Set<string>}
+ */
+function footprintOf(issue) {
+  const body = typeof issue?.body === 'string' ? issue.body : '';
+  if (body === '') return new Set();
+  try {
+    return storyFootprint(parseStoryBody(body).body);
+  } catch {
+    return new Set();
+  }
+}
+
+/**
+ * Find open Stories whose declared footprint intersects the seed's predicted
+ * paths.
+ *
+ * Returns `[]` **without contacting the provider** when the seed named no
+ * paths: with nothing to intersect, every candidate would score empty, and the
+ * round-trip would buy nothing. That short-circuit is load-bearing for the
+ * common one-line seed, which mentions no file at all.
+ *
+ * @param {{
+ *   predictedPaths: string[],
+ *   provider: object,
+ *   owner?: string,
+ *   repo?: string,
+ *   excludeIds?: Iterable<number|string>,
+ * }} args
+ * @returns {Promise<Array<{ id: number, title: string, url: string, state: string, overlappingPaths: string[] }>>}
+ */
+export async function findDependencyCandidates({
+  predictedPaths,
+  provider,
+  owner,
+  repo,
+  excludeIds = [],
+}) {
+  const wanted = (Array.isArray(predictedPaths) ? predictedPaths : []).filter(
+    (p) => typeof p === 'string' && p.trim() !== '',
+  );
+  if (wanted.length === 0) return [];
+  if (typeof provider?.listIssuesByLabel !== 'function') return [];
+
+  const excluded = new Set(
+    [...excludeIds].map((id) => Number(id)).filter((n) => Number.isFinite(n)),
+  );
+
+  let issues;
+  try {
+    issues = await provider.listIssuesByLabel({
+      state: 'open',
+      labels: TYPE_LABELS.STORY,
+    });
+  } catch (err) {
+    Logger.warn(
+      `[dependency-candidates] open-Story listing degraded to no candidates: ${err?.message ?? err}`,
+    );
+    return [];
+  }
+
+  const out = [];
+  for (const issue of Array.isArray(issues) ? issues : []) {
+    const id = Number(issue?.number ?? issue?.id);
+    if (!Number.isInteger(id) || id <= 0 || excluded.has(id)) continue;
+
+    const footprint = footprintOf(issue);
+    if (footprint.size === 0) continue;
+
+    const overlappingPaths = wanted.filter((p) => footprint.has(p));
+    if (overlappingPaths.length === 0) continue;
+
+    out.push({
+      id,
+      title: typeof issue?.title === 'string' ? issue.title : '',
+      url: issue?.html_url ?? issue?.url ?? buildStoryUrl(id, { owner, repo }),
+      state: typeof issue?.state === 'string' ? issue.state : 'open',
+      overlappingPaths,
+    });
+  }
+
+  // Most-entangled first, then ascending id for a stable render.
+  return out.sort(
+    (a, b) =>
+      b.overlappingPaths.length - a.overlappingPaths.length || a.id - b.id,
+  );
+}