mandrel 2.53.0 → 2.55.0

package/.agents/scripts/generate-workflows-doc.js

@@ -22,6 +22,8 @@
  *                current workflow set.
  *   --check    — exits 0 when the on-disk file matches the freshly generated
  *                content, throws (→ exit 1) with a regeneration hint otherwise.
+ *   --root     — read and write under another checkout's `.agents/` tree.
+ *                See {@link resolveTargets} for why this seam exists.
  *
  * Per `.agents/rules/orchestration-error-handling.md`, unrecoverable failures
  * surface via `throw new Error(...)` so `runAsCli` maps the throw to
@@ -39,8 +41,43 @@ import { buildCatalog, buildLoopCatalog } from './lib/mandrel-catalog.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const PROJECT_ROOT = path.resolve(__dirname, '..', '..');
-const WORKFLOWS_DIR = path.join(PROJECT_ROOT, '.agents', 'workflows');
-const DOC_PATH = path.join(PROJECT_ROOT, '.agents', 'docs', 'workflows.md');
+
+/**
+ * Resolve the workflow source directory and the generated doc for one
+ * repository root.
+ *
+ * The `--root` seam this backs exists for the drift gate's own test. That
+ * test used to prove the gate by editing the *real*
+ * `.agents/workflows/mandrel-deliver.md`, running `--check`, and restoring
+ * the file in `afterEach`. The proof was sound; the blast radius was not.
+ * `node --test` runs test files in parallel against one shared checkout, so
+ * for the ~1s the real file sat mutated, every other test file observed a
+ * dirty tree — and `tests/enforcement/workflow-script-help.test.js`, whose
+ * final assertion is a repo-wide `git status --porcelain`, reported it as
+ * "`--help` mutated the working tree" on the Windows Smoke job, where the
+ * wider process-spawn cost stretches that window far enough to collide.
+ *
+ * A generator that can only ever be pointed at its own checkout forces that
+ * choice. Pointing it at a fixture root removes it.
+ *
+ * The `--root` default is applied here rather than at the call site so the
+ * one branch it costs lives with the resolution it belongs to.
+ *
+ * @param {string} [root] Repository root to render against; defaults to this
+ *   checkout. A relative path is resolved against the process cwd.
+ * @returns {{ root: string, workflowsDir: string, docPath: string }}
+ */
+export function resolveTargets(root) {
+  const resolved = root ? path.resolve(root) : PROJECT_ROOT;
+  return {
+    root: resolved,
+    workflowsDir: path.join(resolved, '.agents', 'workflows'),
+    docPath: path.join(resolved, '.agents', 'docs', 'workflows.md'),
+  };
+}
+
+/** This checkout's own targets — the default when `--root` is absent. */
+const { workflowsDir: WORKFLOWS_DIR, docPath: DOC_PATH } = resolveTargets();
 
 /**
  * Collapse a catalog description to a single Markdown table-cell-safe line.
@@ -149,16 +186,24 @@ export function renderWorkflowsDoc(catalog, loopCatalog = []) {
 /**
  * Build the canonical generated content and read the on-disk file (if any).
  *
- * @returns {{ generated: string, original: string | null }}
+ * @param {string} [root] Repository root to render against; see
+ *   {@link resolveTargets}.
+ * @returns {{
+ *   generated: string,
+ *   original: string | null,
+ *   root: string,
+ *   docPath: string,
+ * }}
  */
-export function buildExpected() {
-  const catalog = buildCatalog(WORKFLOWS_DIR);
-  const loopCatalog = buildLoopCatalog(WORKFLOWS_DIR);
+export function buildExpected(root) {
+  const { root: resolvedRoot, workflowsDir, docPath } = resolveTargets(root);
+  const catalog = buildCatalog(workflowsDir);
+  const loopCatalog = buildLoopCatalog(workflowsDir);
   const generated = renderWorkflowsDoc(catalog, loopCatalog);
-  const original = fs.existsSync(DOC_PATH)
-    ? fs.readFileSync(DOC_PATH, 'utf8')
+  const original = fs.existsSync(docPath)
+    ? fs.readFileSync(docPath, 'utf8')
     : null;
-  return { generated, original };
+  return { generated, original, root: resolvedRoot, docPath };
 }
 
 /**
@@ -169,12 +214,13 @@ async function main(argv = process.argv.slice(2)) {
     args: argv,
     options: {
       check: { type: 'boolean', default: false },
+      root: { type: 'string' },
     },
     allowPositionals: false,
   });
 
-  const { generated, original } = buildExpected();
-  const rel = path.relative(PROJECT_ROOT, DOC_PATH).split(path.sep).join('/');
+  const { generated, original, root, docPath } = buildExpected(values.root);
+  const rel = path.relative(root, docPath).split(path.sep).join('/');
 
   if (values.check) {
     if (original === generated) {
@@ -191,8 +237,8 @@ async function main(argv = process.argv.slice(2)) {
     Logger.info(`generate-workflows-doc: ${rel} already current — no write.`);
     return;
   }
-  fs.mkdirSync(path.dirname(DOC_PATH), { recursive: true });
-  fs.writeFileSync(DOC_PATH, generated, 'utf8');
+  fs.mkdirSync(path.dirname(docPath), { recursive: true });
+  fs.writeFileSync(docPath, generated, 'utf8');
   Logger.info(`generate-workflows-doc: wrote ${rel}.`);
 }
 
@@ -201,7 +247,8 @@ export { DOC_PATH, WORKFLOWS_DIR };
 runAsCli(import.meta.url, main, {
   source: 'generate-workflows-doc',
   usage: {
-    invocation: 'node .agents/scripts/generate-workflows-doc.js [--check]',
+    invocation:
+      'node .agents/scripts/generate-workflows-doc.js [--check] [--root <dir>]',
     summary:
       'Regenerate the workflow catalog from .agents/workflows/. Writes only when the generated content differs.',
     flags: [
@@ -209,6 +256,10 @@ runAsCli(import.meta.url, main, {
         '--check',
         'Verify the doc is current and fail if stale; write nothing.',
       ],
+      [
+        '--root <dir>',
+        "Render against another checkout's .agents/ tree instead of this one (test seam).",
+      ],
     ],
   },
 });

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

@@ -157,6 +157,10 @@ runAsCli(import.meta.url, main, {
         'Never consider branches matching the glob (repeatable).',
       ],
       ['--drop-stashes <ref>', 'Stash ref approved for dropping (repeatable).'],
+      [
+        '--include-content-merged',
+        'Under --yes, also delete remote refs detected only by content-equivalence.',
+      ],
       ['--base <branch>', 'Base branch (default: project.baseBranch).'],
       ['--cwd <path>', 'Repository root (default: process cwd).'],
     ],

package/.agents/scripts/lib/ITicketingProvider.js

@@ -98,6 +98,84 @@ export class ITicketingProvider {
     // Intentional no-op. Concrete providers that maintain a cache override.
   }
 
+  /**
+   * List every ticket carrying `labels`, in the **mapped** ticket shape.
+   *
+   * This is the declared read for a label scan, and the only one callers
+   * should reach for. Implementations MUST map every issue the way every
+   * other read on this interface does — in particular `id` is the **issue
+   * number**, not the backend's internal database id.
+   *
+   * That single rule is the whole reason the method exists. The raw REST
+   * payload names the issue number `number` and the database id `id`, so a
+   * consumer handed either shape wrote `number ?? id` and appeared to cope —
+   * while silently addressing issues by database id on the mapped shape,
+   * because there `id` is already the number and the fallback never fires.
+   * A declared shape removes the choice rather than documenting it.
+   *
+   * `state` selects `open` (default), `closed` or `all`. Implementations MUST
+   * honour it: a caller asking for `all` is asking a question — "did this
+   * child reopen?" — that an open-only listing answers wrongly rather than
+   * partially.
+   *
+   * @param {{ state?: 'open'|'closed'|'all', labels?: string }} [_opts]
+   * @returns {Promise<Array<{
+   *   id: number,
+   *   title: string,
+   *   body: string,
+   *   labels: string[],
+   *   assignees: string[],
+   *   state: string,
+   *   url?: string|null,
+   * }>>}
+   */
+  async listTicketsByLabel(_opts = {}) {
+    throw new Error('Not implemented: listTicketsByLabel');
+  }
+
+  /**
+   * Read a parent's native sub-issue children as issue numbers.
+   *
+   * Takes **both** identifiers because they address different things: the
+   * backend's child edge is keyed by the parent's opaque node id, while
+   * `number` exists only so a degraded read can name the parent it failed on.
+   * Passing the number where the node id belongs is not a type error — it is
+   * a successful call about the wrong issue — which is why the parameter
+   * order is fixed here rather than left to each call site.
+   *
+   * Implementations MUST return `[]` rather than throw when the sub-issue
+   * feature is unavailable on the backend: absence of the feature is not a
+   * failed read, and callers union this with a body checklist that still
+   * answers the question.
+   *
+   * @param {string} _nodeId Opaque node id of the parent.
+   * @param {number} _number Parent's issue number, for diagnostics only.
+   * @returns {Promise<number[]>}
+   */
+  async getNativeSubIssues(_nodeId, _number) {
+    throw new Error('Not implemented: getNativeSubIssues');
+  }
+
+  /**
+   * Resolve a ticket's container parent in **one** call.
+   *
+   * Exists so a child→parent lookup is a read, not a search. Without it the
+   * only way to find a container was to list every candidate parent and read
+   * each one's children — O(containers) requests to answer what the backend
+   * knows directly.
+   *
+   * Returns `null` when the ticket has no parent, and `null` rather than
+   * throwing when the backend cannot answer. Callers treat a null as "no
+   * parent resolved *here*" and may fall back to a body-declared link; an
+   * exception would turn a degraded lookup into a failed lifecycle edge.
+   *
+   * @param {number} _number Issue number whose parent to resolve.
+   * @returns {Promise<object|null>} Mapped parent ticket, or null.
+   */
+  async getParentIssue(_number) {
+    throw new Error('Not implemented: getParentIssue');
+  }
+
   /**
    * Return the dependency graph edges for a ticket.
    * Parses `blocked by #NNN` patterns from the ticket body.

package/.agents/scripts/lib/audit-advisories.js

@@ -0,0 +1,195 @@
+/**
+ * audit-advisories.js — run `npm audit --json` and diff advisories across refs.
+ *
+ * The measuring half of `audit-attribution.js` next door. That module owns the
+ * verdict vocabulary and how a verdict is worded; this one owns what a verdict
+ * is computed FROM.
+ *
+ * The comparison is **per advisory**, not per exit code. Reading only "did the
+ * base audit fail too" collapses the case a busy repository meets most: a base
+ * that is already red for advisory A, and a diff that adds advisory B. That
+ * answered `pre-existing` — a true statement about A, and a misleading one
+ * about the branch, because the author was told their diff was innocent while
+ * it was carrying B. Diffing advisory ids at or above `high` reports both facts
+ * separately: B introduced, A pre-existing.
+ *
+ * The npm spawn is injectable (`.agents/rules/test-seams.md`), so the whole
+ * projection is reachable without a registry round-trip.
+ */
+
+import { spawnCapture } from './child-exec.js';
+
+/** The levels the required SCA step fails on, so the levels attribution reads. */
+const BLOCKING_SEVERITIES = new Set(['critical', 'high']);
+
+/**
+ * The stable identity of one advisory in an `npm audit --json` report.
+ *
+ * `source` is the advisory's own numeric id and is what makes two runs
+ * comparable; the URL and title are fallbacks for a registry that omits it. A
+ * `via` entry that is a bare string names another package rather than an
+ * advisory and is handled by the package-level fallback in
+ * {@link extractBlockingAdvisories}.
+ *
+ * @param {object} via
+ * @returns {string|null}
+ */
+function advisoryIdOf(via) {
+  if (via?.source !== undefined && via.source !== null) {
+    return `advisory:${via.source}`;
+  }
+  if (typeof via?.url === 'string' && via.url.length > 0) return via.url;
+  if (typeof via?.title === 'string' && via.title.length > 0) {
+    return `title:${via.title}`;
+  }
+  return null;
+}
+
+/**
+ * Project an `npm audit --json` report onto the set of advisories at or above
+ * `high`, as `{ id, severity, title }` records sorted by id.
+ *
+ * A vulnerable package whose `via` list carries no advisory object at all — the
+ * transitive case, where `via` is a list of package names — still contributes a
+ * `package:<name>` entry. Dropping it would let a real blocking advisory go
+ * uncounted, and an attribution that under-counts the head is one that reports
+ * a genuine regression as `pre-existing`.
+ *
+ * @param {object|null} report — parsed `npm audit --json` output.
+ * @returns {Array<{ id: string, severity: string, title: string }>}
+ */
+export function extractBlockingAdvisories(report) {
+  const packages = report?.vulnerabilities;
+  if (!packages || typeof packages !== 'object') return [];
+  const found = new Map();
+  for (const [name, entry] of Object.entries(packages)) {
+    if (BLOCKING_SEVERITIES.has(String(entry?.severity ?? '').toLowerCase())) {
+      collectPackageAdvisories(name, entry, found);
+    }
+  }
+  return [...found.values()].sort((a, b) => a.id.localeCompare(b.id));
+}
+
+/**
+ * Add one vulnerable package's blocking advisories to `found`, falling back to
+ * a `package:<name>` entry when its `via` list names packages rather than
+ * advisories.
+ *
+ * @param {string} name
+ * @param {object} entry
+ * @param {Map<string, object>} found
+ */
+function collectPackageAdvisories(name, entry, found) {
+  const before = found.size;
+  for (const via of Array.isArray(entry?.via) ? entry.via : []) {
+    const severity = String(via?.severity ?? entry.severity).toLowerCase();
+    const id = BLOCKING_SEVERITIES.has(severity) ? advisoryIdOf(via) : null;
+    if (id && !found.has(id)) {
+      found.set(id, { id, severity, title: via?.title ?? name });
+    }
+  }
+  if (found.size === before) {
+    found.set(`package:${name}`, {
+      id: `package:${name}`,
+      severity: entry.severity,
+      title: name,
+    });
+  }
+}
+
+/**
+ * Split the head's blocking advisories into the ones this diff **introduced**
+ * (head minus base) and the ones the merge base already carried
+ * (the intersection).
+ *
+ * A `null` base is the degraded read: nothing can be attributed, so neither
+ * list is populated and the caller reports `unknown` rather than guessing.
+ *
+ * @param {{ head?: Array<object>, base?: Array<object>|null }} params
+ * @returns {{ introduced: Array<object>, preExisting: Array<object> }}
+ */
+export function diffAdvisories({ head = [], base = null }) {
+  if (!Array.isArray(base)) return { introduced: [], preExisting: [] };
+  const baseIds = new Set(base.map((a) => a.id));
+  return {
+    introduced: head.filter((a) => !baseIds.has(a.id)),
+    preExisting: head.filter((a) => baseIds.has(a.id)),
+  };
+}
+
+/**
+ * Run `npm audit --json` over a dependency manifest pair and project it.
+ *
+ * `--package-lock-only` audits the committed lockfile without installing, so
+ * the probe never touches the job's own `node_modules`: an attribution
+ * mechanism that could disturb the tree it is reporting on would be a worse
+ * defect than the one it explains. `--json` is what makes the two runs
+ * comparable at all — the human report says which advisories exist, but only
+ * as prose.
+ *
+ * @param {string} dir — directory holding package.json + package-lock.json.
+ * @param {{ spawn?: Function }} [deps]
+ * @returns {{ failed: boolean, advisories: Array<object> }}
+ * @throws {Error} when npm could not evaluate the tree at all.
+ */
+export function auditAdvisories(dir, { spawn = spawnCapture } = {}) {
+  const result = spawn(
+    'npm',
+    ['audit', '--json', '--audit-level=high', '--package-lock-only'],
+    { cwd: dir },
+  );
+  const report = parseAuditJson(result?.stdout);
+  // npm exits non-zero for "advisories found" and for "could not audit" alike.
+  // Only a real audit verdict carries a `vulnerabilities` map; anything else is
+  // a probe failure the caller must read as `unknown`.
+  if (!report) {
+    throw new Error(
+      `npm audit could not evaluate the tree: ${String(result?.stderr ?? '').slice(0, 200)}`,
+    );
+  }
+  const advisories = extractBlockingAdvisories(report);
+  return { failed: advisories.length > 0, advisories };
+}
+
+/**
+ * Parse `npm audit --json` stdout, returning `null` for anything that is not a
+ * real audit report. Never throws: a probe that crashed on its own output would
+ * be the second failure mode this module exists to avoid.
+ *
+ * @param {unknown} stdout
+ * @returns {object|null}
+ */
+function parseAuditJson(stdout) {
+  try {
+    const parsed = JSON.parse(String(stdout ?? ''));
+    return parsed?.vulnerabilities ? parsed : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Render the per-advisory detail lines that follow the verdict.
+ *
+ * Named lists, not counts: "3 introduced" sends the reader back to the raw
+ * audit output, which is the trip attribution exists to save.
+ *
+ * @param {{ introduced?: Array<object>, preExisting?: Array<object> }} input
+ * @returns {string[]}
+ */
+export function renderAdvisoryDetail({ introduced = [], preExisting = [] }) {
+  const list = (advisories) =>
+    advisories.map((a) => `${a.id} (${a.severity})`).join(', ');
+  const lines = [];
+  if (introduced.length > 0) {
+    lines.push(
+      `Introduced by this diff (${introduced.length}): ${list(introduced)}.`,
+    );
+  }
+  if (preExisting.length > 0) {
+    lines.push(
+      `Already on the merge base (${preExisting.length}): ${list(preExisting)}. Those are not this branch's to fix.`,
+    );
+  }
+  return lines;
+}

package/.agents/scripts/lib/audit-attribution.js

@@ -16,8 +16,25 @@
  * the same audit, evaluated against the pull request's merge base.
  *
  * It buys legibility, never permission — see `attributionExitCode`.
+ *
+ * The comparison is **per advisory**, not per exit code. Reading only "did the
+ * base audit fail too" collapses the case a busy repository meets most: a base
+ * that is already red for advisory A, and a diff that adds advisory B. That
+ * answered `pre-existing` — a true statement about A, and a misleading one
+ * about the branch, because the author was told their diff was innocent while
+ * it was carrying B. Diffing advisory ids at or above `high` reports both
+ * facts separately: B introduced, A pre-existing.
  */
 
+// The per-advisory machinery lives next door and is re-exported here, so this
+// module stays the one import an attribution consumer needs while the audit
+// runner, the projection and the diff keep their own file.
+export {
+  auditAdvisories,
+  diffAdvisories,
+  renderAdvisoryDetail,
+} from './audit-advisories.js';
+
 // The verdict vocabulary. Only `UNKNOWN` is exported: the CLI branches on it
 // to decide whether to audit the base at all, while the other two are read by
 // callers out of the rendered report rather than compared as symbols. Their
@@ -39,6 +56,11 @@ export const UNKNOWN = 'unknown';
  * attribution mechanism must never guess, because the guess it would make
  * (`introduced-by-this-diff`) is an accusation against the author reading it.
  *
+ * `baseAudit.failed` is asked **per advisory** by the CLI: it passes
+ * `{ failed: <the base already carries every advisory the head has> }`, so a
+ * base that is red for its own advisory does not absolve a diff that added a
+ * different one.
+ *
  * @param {{ headFailed: boolean, baseAudit: { failed: boolean } | null }} input
  * @returns {string} one of INTRODUCED / PRE_EXISTING / UNKNOWN
  */

package/.agents/scripts/lib/audit-to-stories/dedupe-against-github.js

@@ -22,11 +22,18 @@
  * reworded finding at an unchanged location still dedupes against its Issue
  * (Story #4626).
  *
+ * When the caller injects a `listAuditIssues(labels)` port, the whole dedup
+ * corpus is pre-fetched **once per run** off the list endpoint and indexed by
+ * both provenance footers, so `findIssuesByFingerprint` is answered locally and
+ * the rate-limited search API is spent only on findings with no exact hit.
+ *
  * Pure orchestration: this module performs no network I/O itself.
  */
 
-import { routeFinding } from '../findings/route-finding.js';
+import { routeFinding, semanticKeyFor } from '../findings/route-finding.js';
+import { auditLabelsForFindings } from './audit-lenses.js';
 import { toCanonicalFinding } from './finding-adapter.js';
+import { buildIssueIndex, lookupLocally } from './issue-index.js';
 
 /**
  * @typedef {object} GroupClassification
@@ -76,7 +83,7 @@ function groupLabel(group) {
  */
 async function classifyOneGroup(
   group,
-  { searchIssues, semanticPort, routeOptions },
+  { searchIssues, semanticPort, routeOptions, index },
 ) {
   const findings = group.findings ?? [];
   const matchedIssues = [];
@@ -91,9 +98,7 @@ async function classifyOneGroup(
     const canonical = toCanonicalFinding(finding);
     const { decision, matchedIssue, fingerprint } = await routeFinding(
       canonical,
-      semanticPort
-        ? { searchIssues, searchCandidates: () => semanticPort(canonical) }
-        : { searchIssues },
+      portsFor(canonical, sha, { searchIssues, semanticPort, index }),
       routeOptions,
     );
 
@@ -122,6 +127,58 @@ async function classifyOneGroup(
   return { action, matchedIssues, matchedFingerprints };
 }
 
+/**
+ * The read ports one finding is routed through.
+ *
+ * With no local index this is the historical wiring: the provider answers the
+ * exact lookup and the semantic port always runs. With an index, the exact
+ * lookup is answered from memory, and the semantic port — the only remaining
+ * network call — runs **only** when the index holds no exact fingerprint hit.
+ * That is the whole saving: a finding the sweep has already filed costs zero
+ * requests, and only a genuinely-unrecognised one is worth a search.
+ *
+ * @param {object} canonical — the canonical finding projection.
+ * @param {string} sha — its full fingerprint.
+ * @param {{ searchIssues: Function, semanticPort?: Function, index?: object }} routing
+ * @returns {{ searchIssues: Function, searchCandidates?: Function }}
+ */
+function portsFor(canonical, sha, { searchIssues, semanticPort, index }) {
+  const withSemantic = (ports) =>
+    semanticPort
+      ? { ...ports, searchCandidates: () => semanticPort(canonical) }
+      : ports;
+  if (!index) return withSemantic({ searchIssues });
+
+  const { exact, pool } = lookupLocally(index, sha, semanticKeyFor(canonical));
+  const local = { searchIssues: () => pool };
+  return exact.length > 0 ? local : withSemantic(local);
+}
+
+/**
+ * Pre-fetch and index every Issue carrying one of the run's `audit::*` labels.
+ *
+ * Returns `null` — the un-indexed, per-finding-search path — when no list port
+ * is wired, when the run's findings resolve to no canonical lens label, or when
+ * the list itself fails. A degraded pre-fetch must cost the run its saving, not
+ * its dedup.
+ *
+ * @param {{ listAuditIssues?: Function, groups: Array<object>,
+ *   onDegraded?: Function }} params
+ * @returns {Promise<object|null>}
+ */
+async function prefetchIssueIndex({ listAuditIssues, groups }) {
+  if (typeof listAuditIssues !== 'function') return null;
+  const labels = auditLabelsForFindings(
+    groups.flatMap((group) => group?.findings ?? []),
+  );
+  if (labels.length === 0) return null;
+  try {
+    return buildIssueIndex(await listAuditIssues(labels));
+  } catch (_) {
+    return null;
+  }
+}
+
 /**
  * @param {object} params
  * @param {Array<object>} params.groups — output of `groupFindings`.
@@ -130,6 +187,10 @@ async function classifyOneGroup(
  *   Optional meaning-first candidate search (production: `semantic-issue-search.js`).
  *   When supplied, routing runs the Stage-1 semantic pass and opts into
  *   location-based semantic-key confirmation.
+ * @param {(labels: string[]) => Promise<Array<object>>} [params.listAuditIssues]
+ *   Optional list port over the run's `audit::*` labels. When wired, its result
+ *   is fetched once and indexed, and `provider.findIssuesByFingerprint` is not
+ *   called at all — the exact lookup is answered from that index.
  * @param {(entry: { group: object, reason: string }) => void} [params.onDegraded]
  *   Optional sink notified once per group whose dedup lookup could not complete
  *   (Story #4678). The group is then classified `create` — a soft-fail, never
@@ -142,6 +203,7 @@ export async function classifyGroupsAgainstGitHub({
   provider,
   searchCandidates,
   onDegraded,
+  listAuditIssues,
 }) {
   if (!Array.isArray(groups)) {
     throw new Error('classifyGroupsAgainstGitHub: groups must be an array');
@@ -163,6 +225,7 @@ export async function classifyGroupsAgainstGitHub({
     searchIssues,
     semanticPort,
     routeOptions: { semanticKeyConfirm: Boolean(semanticPort) },
+    index: await prefetchIssueIndex({ listAuditIssues, groups }),
   };
 
   const classifications = [];

package/.agents/scripts/lib/audit-to-stories/issue-index.js

@@ -0,0 +1,83 @@
+/**
+ * lib/audit-to-stories/issue-index.js — a local index of the audit Issues a
+ * sweep must dedupe against.
+ *
+ * Dedup used to answer every finding with a **search** round-trip: one
+ * `findIssuesByFingerprint(sha)` per finding, plus a meaning-first semantic
+ * search on top. GitHub's search endpoint is rate-limited an order of magnitude
+ * harder than the list endpoint, so a full-scope sweep — hundreds of findings —
+ * spent its whole budget re-discovering the same few dozen Issues, and then
+ * degraded the rest of the run to `create`, which is how a sweep opens
+ * duplicates of Issues it already filed.
+ *
+ * The Issues that can possibly match are exactly those carrying an `audit::*`
+ * label, and there are tens of them, not hundreds. Listing them **once per run**
+ * and indexing their provenance footers answers every exact-fingerprint lookup
+ * locally, for free. The search API is then spent only where it is the only
+ * thing that can help: a finding with no exact hit, whose fingerprint may have
+ * drifted under a rewording.
+ *
+ * Pure: the caller injects the list port and this module performs no I/O.
+ */
+
+import {
+  parseFingerprintFooter,
+  parseSemanticKeyFooter,
+} from '../findings/route-finding.js';
+
+/**
+ * Add `record` to the list `map` keys under `key`.
+ *
+ * @param {Map<string, object[]>} map
+ * @param {string} key
+ * @param {object} record
+ */
+function push(map, key, record) {
+  const bucket = map.get(key);
+  if (bucket) bucket.push(record);
+  else map.set(key, [record]);
+}
+
+/**
+ * Index issues by both provenance footers the audit filers stamp.
+ *
+ * An issue carrying neither footer is indexed under nothing — it can never
+ * confirm a match, exactly as it could not when it came back from a search.
+ *
+ * @param {Array<{ number: number, state: string, body?: string }>} issues
+ * @returns {{ byFingerprint: Map<string, object[]>, bySemanticKey: Map<string, object[]>, size: number }}
+ */
+export function buildIssueIndex(issues) {
+  const byFingerprint = new Map();
+  const bySemanticKey = new Map();
+  const records = (issues ?? []).filter(
+    (issue) => typeof issue?.number === 'number',
+  );
+  for (const issue of records) {
+    for (const sha of parseFingerprintFooter(issue.body)) {
+      push(byFingerprint, sha, issue);
+    }
+    for (const key of parseSemanticKeyFooter(issue.body)) {
+      push(bySemanticKey, key, issue);
+    }
+  }
+  return { byFingerprint, bySemanticKey, size: records.length };
+}
+
+/**
+ * The union of the two local lookups for one finding, fingerprint hits first.
+ *
+ * Order matters downstream: `routeFinding` keeps the first record contributed
+ * for an issue number, and the record retrieved by exact identity is the one
+ * that should survive into confirmation.
+ *
+ * @param {{ byFingerprint: Map, bySemanticKey: Map }} index
+ * @param {string} sha
+ * @param {string} semanticKey
+ * @returns {{ exact: object[], pool: object[] }}
+ */
+export function lookupLocally(index, sha, semanticKey) {
+  const exact = index.byFingerprint.get(sha) ?? [];
+  const byKey = semanticKey ? (index.bySemanticKey.get(semanticKey) ?? []) : [];
+  return { exact, pool: [...exact, ...byKey] };
+}