mandrel 2.55.0 → 2.56.0

package/.agents/scripts/file-ci-gap.js

@@ -0,0 +1,306 @@
+#!/usr/bin/env node
+/**
+ * file-ci-gap.js — the CI-remediation Option-2 filing command.
+ *
+ * `rules/ci-remediation.md` sends three verdicts here — `pre-existing`,
+ * `capacity`, `unreproducible-tier` — each meaning "this red check is real,
+ * and fixing it is not this delivery's job". The rule used to say "file a
+ * `meta::framework-gap` issue" and stop, leaving the agent to hand-run
+ * `gh issue create` wherever it was standing. This is the mechanism behind
+ * that sentence: evidence from the CI digest, ownership routing, fingerprint
+ * dedup, the `friction` comment, and the `agent::blocked` flip in one call.
+ *
+ * It files an **intake** issue, never a Story: `/mandrel-plan <id>` graduates
+ * it on the next planning pass. Delivery never blocks on planning — see
+ * `lib/orchestration/ci-gap-intake.js` for why that split is load-bearing.
+ */
+
+import { parseArgs } from 'node:util';
+
+import { runAsCli } from './lib/cli-utils.js';
+import { resolveConfig } from './lib/config-resolver.js';
+import {
+  createFollowUpIssue,
+  ensureIssueLabels,
+  updateFollowUpIssue,
+} from './lib/feedback-loop/graduator-core.js';
+import { issueNumberFromUrl } from './lib/feedback-loop/retro-proposals-graduator.js';
+import {
+  resolveOwnershipRepos,
+  routeOwnership,
+} from './lib/github/framework-repo.js';
+import { Logger } from './lib/Logger.js';
+import {
+  fileCiGapIntake,
+  INTAKE_VERDICTS,
+  REFUSED_VERDICT,
+} from './lib/orchestration/ci-gap-intake.js';
+import { readCiDigest } from './lib/orchestration/ci-rerun-guard.js';
+import {
+  STATE_LABELS,
+  transitionTicketState,
+  upsertStructuredComment,
+} from './lib/orchestration/ticketing.js';
+import { createProvider } from './lib/provider-factory.js';
+
+const USAGE = {
+  invocation:
+    'node .agents/scripts/file-ci-gap.js --story <id> --verdict <verdict> --owner <bucket> [--evidence "<proof reading>"] [--pr <n>] [--block] [--dry-run]',
+  summary:
+    'File (or update) the CI-gap intake issue for an Option-2 verdict in .agents/rules/ci-remediation.md, routed to the repository that owns the fault and deduped by failure signature.',
+  flags: [
+    [
+      '--story <id>',
+      'Story the red check blocked (required — keys the CI digest).',
+    ],
+    [
+      '--verdict <verdict>',
+      `One of ${INTAKE_VERDICTS.join(' | ')}. "${REFUSED_VERDICT}" is refused: it routes to Option 1, fix at source.`,
+    ],
+    [
+      '--owner <bucket>',
+      'Who owns the fault: consumer | framework | platform. Resolves through github.followUpRepos.*.',
+    ],
+    [
+      '--evidence <text>',
+      "The verdict's proof reading (the exhausted-limit log line, the failed attach). Recorded in the body.",
+    ],
+    ['--pr <n>', 'PR number the red check ran on; recorded as an occurrence.'],
+    [
+      '--block',
+      'Also flip the Story to agent::blocked. Without it the friction comment is posted but the Story is left where it is.',
+    ],
+    ['--dry-run', 'Compose the filing and print it; write nothing.'],
+  ],
+  notes: [
+    'Requires a CI digest at temp/story-<id>-ci-digest.json — pr-watch-with-update.js --story <id> writes it on the first red.',
+    'A repeat occurrence of a known signature UPDATES the existing intake issue rather than opening a second one.',
+    'The issue it files is intake, not an executable Story: graduate it with /mandrel-plan <issue number>.',
+  ],
+};
+
+/**
+ * Wire the live GitHub ports the intake filer writes through.
+ *
+ * `gh` is the transport rather than the provider facade because a filing can
+ * target a repository other than the configured one, and `gh issue create
+ * --repo` is the surface that already does that (the graduators file
+ * cross-repo the same way).
+ *
+ * @param {object} opts
+ * @returns {object} ports for `fileCiGapIntake`
+ */
+function liveIntakePorts({ provider, searchRepo, cwd, logger }) {
+  const labelCache = new Map();
+  return {
+    searchIssues: (query) =>
+      provider.searchIssues({
+        query,
+        owner: searchRepo.owner,
+        repo: searchRepo.repo,
+      }),
+    createIssue: async ({ owner, repo, title, body, labels }) => {
+      // `gh issue create --label <absent>` fails outright, so a brand-new
+      // routing label (meta::platform-gap, friction::unreproducible-tier)
+      // has to exist before the create — not after it errors.
+      const ensured = await ensureIssueLabels({
+        owner,
+        repo,
+        labels,
+        labelCache,
+        cwd,
+      });
+      for (const err of ensured.errors) logger?.warn?.(`[file-ci-gap] ${err}`);
+      const created = await createFollowUpIssue({
+        owner,
+        repo,
+        title,
+        body,
+        labels,
+        ghPath: 'gh',
+        cwd,
+      });
+      return {
+        url: created.url,
+        number: created.url ? issueNumberFromUrl(created.url) : null,
+        error: created.error,
+      };
+    },
+    updateIssue: ({ owner, repo, number, body }) =>
+      updateFollowUpIssue({ owner, repo, number, body, ghPath: 'gh', cwd }),
+  };
+}
+
+/**
+ * Render the `friction` comment the Story carries so the blocker is legible
+ * on the ticket itself, not only in the intake issue.
+ *
+ * @param {object} opts
+ * @returns {string}
+ */
+export function renderFrictionComment({ verdict, result, digest }) {
+  const target = result.issue?.url ?? result.issue?.number ?? '(not filed)';
+  const lines = [
+    `### CI gap filed — verdict \`${verdict}\``,
+    '',
+    `- **Failing check:** \`${digest?.failingCheck ?? 'unknown'}\``,
+    `- **Run:** ${digest?.runUrl ?? `run id ${digest?.runId ?? 'unresolved'}`}`,
+    `- **Intake issue:** ${target} (${result.decision})`,
+    `- **Owner:** \`${result.routing.bucket}\` → \`${result.routing.routedRepo.owner}/${result.routing.routedRepo.repo}\``,
+  ];
+  if (!result.routing.routable) {
+    lines.push(
+      `- **Routing:** \`unroutable\` — \`${result.routing.missingKey}\` is unset, so the intake issue was filed locally.`,
+    );
+  }
+  if (result.routing.deferredFrom) {
+    lines.push(
+      `- **Routing:** deferred from \`${result.routing.deferredFrom}\` (${result.routing.deferralReason}) — filed locally instead.`,
+    );
+  }
+  lines.push(
+    '',
+    'This verdict does **not** license a re-run of the failed job. Graduate the',
+    'intake issue with `/mandrel-plan <issue number>` to turn it into a Story.',
+  );
+  return lines.join('\n');
+}
+
+/**
+ * File the CI-gap intake issue for one Story, post the `friction` comment,
+ * and optionally flip the Story to `agent::blocked`.
+ *
+ * Every port is injectable so the unit tests exercise the whole command with
+ * no network and no live tracker.
+ *
+ * @param {object} opts
+ * @returns {Promise<object>} the intake result, plus what the command did.
+ */
+export async function runFileCiGap({
+  storyId,
+  verdict,
+  owner: bucket,
+  evidence = '',
+  prNumber = null,
+  dryRun = false,
+  block = false,
+  config,
+  provider,
+  ports,
+  digest,
+  tempRoot,
+  cwd = process.cwd(),
+  logger = Logger,
+  now,
+} = {}) {
+  const sid = Number(storyId);
+  if (!Number.isInteger(sid) || sid <= 0) {
+    throw new Error('--story <id> is required (a positive issue number).');
+  }
+  const resolved = config ?? resolveConfig();
+  const ciDigest = digest ?? readCiDigest({ storyId: sid, tempRoot, cwd });
+  if (!ciDigest) {
+    throw new Error(
+      `no CI digest for Story #${sid}. The digest is written by \`pr-watch-with-update.js --story ${sid}\` on the first red; without it there is no run link or failure signature to file.`,
+    );
+  }
+
+  const repos = resolveOwnershipRepos(resolved);
+  const currentRepo = repos.consumer ?? { owner: 'unknown', repo: 'unknown' };
+  // Dedup searches the repository the filing will land in — routing is a pure
+  // function, so computing it here and inside the filer cannot disagree.
+  const routed = routeOwnership({ bucket, repos, currentRepo });
+  const searchRepo = routed.routable ? routed.routedRepo : currentRepo;
+
+  const ticketing =
+    provider ?? (dryRun ? null : (createProvider(resolved) ?? null));
+  const livePorts =
+    ports ??
+    liveIntakePorts({
+      provider: ticketing ?? createProvider(resolved),
+      searchRepo,
+      cwd,
+      logger,
+    });
+
+  const result = await fileCiGapIntake({
+    digest: ciDigest,
+    verdict,
+    bucket,
+    evidence,
+    repos,
+    currentRepo,
+    prNumber,
+    dryRun,
+    ports: livePorts,
+    logger,
+    now,
+  });
+
+  const actions = { commented: false, blocked: false };
+  if (!dryRun && ticketing) {
+    const body = renderFrictionComment({ verdict, result, digest: ciDigest });
+    try {
+      await upsertStructuredComment(ticketing, sid, 'friction', body);
+      actions.commented = true;
+    } catch (err) {
+      result.errors.push(`friction comment failed: ${err?.message ?? err}`);
+    }
+    if (block) {
+      try {
+        await transitionTicketState(ticketing, sid, STATE_LABELS.BLOCKED, {});
+        actions.blocked = true;
+      } catch (err) {
+        result.errors.push(
+          `agent::blocked transition failed: ${err?.message ?? err}`,
+        );
+      }
+    }
+  }
+
+  return { storyId: sid, verdict, ...result, actions };
+}
+
+/**
+ * CLI entrypoint.
+ *
+ * @returns {Promise<void>}
+ */
+async function main() {
+  const { values } = parseArgs({
+    args: process.argv.slice(2),
+    options: {
+      story: { type: 'string' },
+      verdict: { type: 'string' },
+      owner: { type: 'string' },
+      evidence: { type: 'string' },
+      pr: { type: 'string' },
+      block: { type: 'boolean', default: false },
+      'dry-run': { type: 'boolean', default: false },
+    },
+  });
+
+  const result = await runFileCiGap({
+    storyId: values.story,
+    verdict: values.verdict,
+    owner: values.owner,
+    evidence: values.evidence ?? '',
+    prNumber: values.pr ? Number(values.pr) : null,
+    dryRun: values['dry-run'],
+    block: values.block,
+  });
+
+  // Single-line JSON per the script-output contract — an orchestrator parses
+  // this, and a pretty dump is noise in a delivery transcript.
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  for (const err of result.errors) {
+    Logger.error(`[file-ci-gap] ${err}`);
+  }
+  if (result.errors.length > 0) process.exitCode = 1;
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'file-ci-gap',
+  errorPrefix: '[file-ci-gap]',
+  usage: USAGE,
+});

package/.agents/scripts/lib/audit-to-stories/audit-label-taxonomy.js

@@ -26,13 +26,14 @@
  * label spelling — so a rename still lands in one place.
  */
 
+import { auditLabelFooter } from '../findings/route-finding.js';
 import {
   AGENT_LABELS,
   LABEL_COLORS,
   RISK_LABELS,
   TYPE_LABELS,
 } from '../label-constants.js';
-import { AUDIT_LENSES } from './audit-lenses.js';
+import { AUDIT_LENSES, auditLabelsForFindings } from './audit-lenses.js';
 
 /**
  * Per-lens label presentation, keyed by canonical lens name. A lens absent from
@@ -183,3 +184,26 @@ const DEFINED_NAMES = new Set(AUDIT_LABEL_TAXONOMY.map((l) => l.name));
 export function definesAuditLabel(name) {
   return typeof name === 'string' && DEFINED_NAMES.has(name);
 }
+
+/**
+ * Render the `audit-labels` footer for a group of findings.
+ *
+ * The dedup corpus is listed by `audit::*` label, so a Story filed without one
+ * is absent from the pool an indexed run matches against — and with an index in
+ * play the exact lookup is answered locally and never reaches the provider, so
+ * a fingerprint footer alone cannot rescue it. Carrying the labels through the
+ * seed is what lets the chained planning path stamp them without the authoring
+ * agent being asked to notice them (Story #5307).
+ *
+ * Lives here rather than beside {@link auditLabelsForFindings} because it needs
+ * {@link definesAuditLabel}, and the taxonomy already depends on the lens list —
+ * the reverse edge would be a cycle.
+ *
+ * @param {Array<object>} findings
+ * @returns {string} the footer, or '' when no finding resolves to a label.
+ */
+export function auditLabelFooterForFindings(findings) {
+  return auditLabelFooter(
+    auditLabelsForFindings(findings).filter(definesAuditLabel),
+  );
+}

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

@@ -27,13 +27,21 @@
  * 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.
+ * A caller that already holds the corpus injects it directly as `issues`
+ * instead (Story #5301) — the host fetched it by whatever access path it has,
+ * which is what lets dedup run on a host with no `gh` CLI at all. That source
+ * needs no provider: with an index in play the exact lookup is answered from
+ * memory and `findIssuesByFingerprint` is never called, so the port is required
+ * only on the un-indexed path where it is genuinely used.
+ *
+ * Pure orchestration: this module performs no network I/O itself, and reads no
+ * file — the caller hands over an array, never a path.
  */
 
 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';
+import { prepareDedupRouting } from './issue-corpus.js';
+import { lookupLocally } from './issue-index.js';
 
 /**
  * @typedef {object} GroupClassification
@@ -46,6 +54,11 @@ import { buildIssueIndex, lookupLocally } from './issue-index.js';
 /**
  * Render a short, operator-legible reason from a dedup-lookup failure. Pure —
  * no imports, no I/O — so the module stays pure orchestration (Story #4678).
+ *
+ * Both degrade paths run through here, so the wording an operator reads for a
+ * failed index pre-fetch matches the wording for a failed per-group lookup:
+ * one vocabulary for "the GitHub read did not complete", whichever read it was.
+ *
  * @param {unknown} err
  * @returns {string}
  */
@@ -154,31 +167,6 @@ function portsFor(canonical, sha, { searchIssues, semanticPort, index }) {
   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`.
@@ -191,6 +179,12 @@ async function prefetchIssueIndex({ listAuditIssues, groups }) {
  *   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 {Array<object>} [params.issues]
+ *   Optional pre-fetched corpus the caller already holds, used in preference to
+ *   `listAuditIssues`. Supplying it makes `provider` optional: with an index in
+ *   play no provider read port is ever invoked, which is what lets a host with
+ *   no `gh` CLI dedup at all (Story #5301). An empty array is a valid corpus —
+ *   a first sweep — and is NOT read as "no 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
@@ -204,37 +198,31 @@ export async function classifyGroupsAgainstGitHub({
   searchCandidates,
   onDegraded,
   listAuditIssues,
+  issues,
 }) {
   if (!Array.isArray(groups)) {
     throw new Error('classifyGroupsAgainstGitHub: groups must be an array');
   }
-  if (!provider || typeof provider.findIssuesByFingerprint !== 'function') {
-    throw new Error(
-      'classifyGroupsAgainstGitHub: provider.findIssuesByFingerprint is required',
-    );
-  }
 
-  // Adapt the provider port into the `searchIssues` shape routeFinding wants.
-  // routeFinding hands the port the sha it computed off the canonical
-  // projection, which equals the sha the group already carries (both come
-  // from the same `toCanonicalFinding` projection).
-  const searchIssues = (sha) => provider.findIssuesByFingerprint(sha);
-  const semanticPort =
-    typeof searchCandidates === 'function' ? searchCandidates : undefined;
-  const routing = {
-    searchIssues,
-    semanticPort,
-    routeOptions: { semanticKeyConfirm: Boolean(semanticPort) },
-    index: await prefetchIssueIndex({ listAuditIssues, groups }),
-  };
+  const { routing, summary, error } = await prepareDedupRouting({
+    groups,
+    provider,
+    searchCandidates,
+    listAuditIssues,
+    issues,
+  });
+  if (error) {
+    // Same vocabulary as a per-group failure, but deliberately NOT counted as
+    // a degraded group: the count names groups classified without a check, and
+    // every group still gets one here, off the per-finding search path. Until
+    // Story #5301 this failure was swallowed whole, so the operator saw only
+    // the downstream per-group degradation and could not tell what caused it.
+    const reason = `issue-index pre-fetch failed: ${describeDegradeReason(error)}`;
+    summary.dedupDegraded.indexPrefetch = reason;
+    if (typeof onDegraded === 'function') onDegraded({ group: null, reason });
+  }
 
   const classifications = [];
-  const summary = {
-    create: 0,
-    skipOpen: 0,
-    skipReoccurring: 0,
-    dedupDegraded: { count: 0, groups: [] },
-  };
 
   for (const group of groups) {
     let result;

package/.agents/scripts/lib/audit-to-stories/finding-adapter.js

@@ -62,10 +62,14 @@ export function fingerprintAuditFinding(finding) {
  * shared helper. Stable across a reworded title; used to confirm a dedup
  * match when the fingerprint has drifted (Story #4626).
  *
+ * Module-internal since the ledger moved to the shared findings layer and takes
+ * its projection injected: `renderSemanticKeyFooter` below is the only caller,
+ * and re-exporting it for none would trip `dead-exports:production`.
+ *
  * @param {object} finding
  * @returns {string}
  */
-export function semanticKeyForAuditFinding(finding) {
+function semanticKeyForAuditFinding(finding) {
   return semanticKeyFor(toCanonicalFinding(finding));
 }
 

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

@@ -0,0 +1,162 @@
+/**
+ * lib/audit-to-stories/issue-corpus.js — where the dedup corpus comes from,
+ * and how a corpus that could not be fetched is described to the operator.
+ *
+ * Dedup needs exactly one thing from GitHub: the Issues carrying an `audit::*`
+ * label. Until Story #5301 the only source was the provider's list port, which
+ * spawns `gh`, so a host without a `gh` CLI — a Claude Code cloud sandbox,
+ * where `gh` is absent and direct API access is disabled while the GitHub MCP
+ * tools work fine — could not dedup at all: every group classified `create`
+ * and a scheduled sweep re-filed what it had already filed.
+ *
+ * Sourcing lives here rather than in `dedupe-against-github.js` so that module
+ * stays what its own header claims — pure routing of findings to verdicts —
+ * and so the empty-corpus and failed-fetch cases cannot diverge between call
+ * sites. Nothing here reaches the network or the filesystem: a caller that
+ * already holds the corpus passes the array in.
+ */
+
+import { auditLabelsForFindings } from './audit-lenses.js';
+import { buildIssueIndex } from './issue-index.js';
+
+/**
+ * Resolve the dedup corpus into an index, from whichever source is wired.
+ *
+ * A corpus the caller already holds (`issues`) wins: the host fetched it by
+ * whatever GitHub access path it has, which is what lets dedup run where there
+ * is no `gh` CLI. Otherwise the run's `audit::*` Issues are pre-fetched off the
+ * list port, once.
+ *
+ * Two results deliberately do NOT collapse to "no index", because a null index
+ * silently returns the run to the per-finding search — which on a
+ * provider-less host is no dedup at all, the failure this path exists to kill.
+ * An **empty** injected corpus is a legitimate first sweep and yields a real
+ * zero-row index. A **failed** pre-fetch hands back its `error` so the caller
+ * can say so in its own words: an operator who cannot see that the pre-fetch
+ * failed cannot tell a checked plan from an unchecked one.
+ *
+ * Module-internal: every caller reaches it through `prepareDedupRouting`, so
+ * the empty-corpus and failed-fetch cases cannot diverge between call sites.
+ *
+ * @param {{ listAuditIssues?: Function, groups?: Array<object>,
+ *   issues?: Array<object> }} params
+ * @returns {Promise<{ index: object|null, source: 'injected'|'prefetch'|'none',
+ *   error?: unknown }>}
+ */
+async function resolveIssueCorpus({ listAuditIssues, groups, issues }) {
+  if (Array.isArray(issues)) {
+    return { index: buildIssueIndex(issues), source: 'injected' };
+  }
+  const labels =
+    typeof listAuditIssues === 'function'
+      ? auditLabelsForFindings(
+          (groups ?? []).flatMap((group) => group?.findings ?? []),
+        )
+      : [];
+  if (labels.length === 0) return { index: null, source: 'none' };
+  try {
+    return {
+      index: buildIssueIndex(await listAuditIssues(labels)),
+      source: 'prefetch',
+    };
+  } catch (err) {
+    return { index: null, source: 'none', error: err };
+  }
+}
+
+/**
+ * Attach the index description to a seeded summary, when there is one to make.
+ *
+ * A run with neither an injected corpus nor a list port has no index to
+ * describe, and `{ source: 'none', size: 0 }` says nothing the field's absence
+ * does not — while inviting the reading "an index was consulted and it was
+ * empty", the exact confusion this whole path exists to remove. Omitting it
+ * also leaves the summary a pure per-finding-search run emits byte-identical
+ * to what it has always been.
+ *
+ * A failed pre-fetch is the one `none` that IS described: there the run ended
+ * *without* an index it expected to have, and the operator needs to see that.
+ *
+ * @param {object} summary — the seeded counters.
+ * @param {{ source: string, index: object|null, error?: unknown }} resolution
+ * @returns {object} the same summary, with `dedupIndex` when applicable.
+ */
+function withIndexDescription(summary, { source, index, error }) {
+  if (source === 'none' && !error) return summary;
+  return { ...summary, dedupIndex: { source, size: index?.size ?? 0 } };
+}
+
+/**
+ * Assemble everything routing needs from the caller's ports and corpus: the
+ * read ports, the resolved index, and the two facts the caller must report —
+ * what the corpus was and whether fetching it degraded.
+ *
+ * The provider port is validated here because this is where "is there a usable
+ * dedup source at all" is actually known. It is required only on the
+ * un-indexed path: once an index exists every exact lookup is answered from
+ * memory and `findIssuesByFingerprint` is never called, so demanding it there
+ * would be the one thing standing between a `gh`-less host and a real dedup
+ * run.
+ *
+ * @param {{ groups?: Array<object>, provider?: object,
+ *   searchCandidates?: Function, listAuditIssues?: Function,
+ *   issues?: Array<object> }} params
+ * The seeded `summary` comes back with it: the corpus is the only thing that
+ * knows what the index was, and returning the counters beside it keeps the
+ * caller from reconstructing a shape it does not own.
+ *
+ * @returns {Promise<{ routing: object, summary: object, error?: unknown }>}
+ * @throws {Error} when neither a provider read port nor a corpus is supplied.
+ */
+export async function prepareDedupRouting({
+  groups,
+  provider,
+  searchCandidates,
+  listAuditIssues,
+  issues,
+}) {
+  const hasProviderPort =
+    Boolean(provider) && typeof provider.findIssuesByFingerprint === 'function';
+  if (!hasProviderPort && !Array.isArray(issues)) {
+    throw new Error(
+      'classifyGroupsAgainstGitHub: provider.findIssuesByFingerprint is required ' +
+        'when no `issues` corpus is supplied',
+    );
+  }
+  const { index, source, error } = await resolveIssueCorpus({
+    listAuditIssues,
+    groups,
+    issues,
+  });
+  const semanticPort =
+    typeof searchCandidates === 'function' ? searchCandidates : undefined;
+  return {
+    routing: {
+      // routeFinding hands the port the sha it computed off the canonical
+      // projection, which equals the sha the group already carries.
+      searchIssues: hasProviderPort
+        ? (sha) => provider.findIssuesByFingerprint(sha)
+        : undefined,
+      semanticPort,
+      // An index carries the semantic-key map, so location-based confirmation
+      // costs nothing once one exists. Without this, confirmation would discard
+      // the `bySemanticKey` half of the pool the local lookup just built, and a
+      // provider-less run would be fingerprint-exact only — strictly weaker
+      // than the path it replaces.
+      routeOptions: {
+        semanticKeyConfirm: Boolean(semanticPort) || Boolean(index),
+      },
+      index,
+    },
+    summary: withIndexDescription(
+      {
+        create: 0,
+        skipOpen: 0,
+        skipReoccurring: 0,
+        dedupDegraded: { count: 0, groups: [] },
+      },
+      { source, index, error },
+    ),
+    error,
+  };
+}