mandrel 2.55.0 → 2.56.0

package/.agents/docs/agentrc-reference.json

@@ -28,6 +28,10 @@
     "projectOwner": null,
     "operatorHandle": "@[USERNAME]",
     "defaultTimeoutMs": 60000,
+    "followUpRepos": {
+      "framework": "dsj1984/mandrel",
+      "platform": null
+    },
     "branchProtection": {
       "enforce": true,
       "requiredChecks": [

package/.agents/docs/configuration.md

@@ -103,6 +103,9 @@ GitHub provider identity plus the remote stance the bootstrap enforces. `owner`,
 | `projectOwner` | No | `string` \| `null` | `null` | Owner of the Projects V2 board when it lives outside `owner` (an org board fed by a user repo). `null` means the board shares `owner`. |
 | `operatorHandle` | Yes | `string` | `"@[USERNAME]"` | The human the framework escalates to, `@`-prefixed. Used for HITL @-mentions on `agent::blocked`. |
 | `defaultTimeoutMs` | No | `integer` | `60000` | Default `timeoutMs` applied to every `gh` subprocess the provider facade spawns, so a stalled socket or long-poll cannot hang an orchestration indefinitely. A `GhExecTimeoutError` from a hit ceiling is classified `transient` and retried by `withTransientRetry`. Story #2860. |
+| `followUpRepos` | No | `object` | — | Repository slugs for the non-consumer follow-up ownership buckets, used when a CI gap, retro proposal, or audit finding belongs to someone other than the repo that surfaced it. |
+| `followUpRepos.framework` | No | `string` | `"dsj1984/mandrel"` | `<owner>/<repo>` that owns framework-level defects. Defaults to the Mandrel mirror — the one bucket with a knowable default. |
+| `followUpRepos.platform` | No | `string` \| `null` | `null` | `<owner>/<repo>` for a shared platform or infrastructure tracker (a shared base config, a runner fleet, a cross-repo toolchain). No default — nothing can guess a shared repo. Left unset, platform-owned findings file locally and say so. |
 | `branchProtection` | No | `object` | — | Branch-protection stance applied to `project.baseBranch` by the GitHub bootstrap, and reproduced locally before every push. |
 | `branchProtection.enforce` | No | `boolean` | `true` | When true, the GitHub bootstrap writes the required-check ruleset. False leaves the remote stance alone. |
 | `branchProtection.requiredChecks[]` | No | `array<object>` | `[{"name":"lint","cmd":["npm","run","lint"]},{"name":"test","cmd":["npm","test"]},{"name":"baselines","cmd":["node",".agents/scripts/check-baselines.js"]}]` | Checks that must pass before a Story PR merges. Each entry carries both the remote context name and the local argv. Each item has: name, cmd. |

package/.agents/rules/ci-remediation.md

@@ -27,13 +27,29 @@ exactly one of two ways, and no others:
    through the fix table in
    [`deliver-story-reference.md` § Step 4](../workflows/helpers/deliver-story-reference.md#step-4--ci-watch--fix-recovery);
    refresh a baseline only when the diff demonstrably can't be covered.
-2. **File a `meta::framework-gap` issue** when the root cause is outside this
+2. **File the CI-gap intake issue** when the root cause is outside this
    delivery's scope — a pre-existing flaky test, a runner/infra weakness, a
-   framework-level environment gap. Open the issue with the `meta::framework-gap`
-   label (see [`git-conventions.md`](git-conventions.md)) carrying **the run
-   link and the failure signature** so a later `/mandrel-plan` Phase 0 sweep can act on
-   it. Remediate this delivery only if the pre-existing defect is genuinely
-   blocking it.
+   framework-level environment gap. One command does it, and it is the only
+   sanctioned filing surface:
+
+   ```bash
+   node .agents/scripts/file-ci-gap.js --story <id> --verdict <verdict> \
+     --owner <consumer|framework|platform> --evidence "<proof reading>" [--block]
+   ```
+
+   It reads the digest for the run link and failure signature, routes the
+   filing to the repository that **owns** the fault, dedups by signature so
+   the Nth occurrence updates the existing ticket, posts the `friction`
+   comment, and (with `--block`) flips the Story. Hand-running `gh issue
+   create` is not the fallback: it files an issue no `/mandrel-plan` pass can
+   graduate, in whichever repo you happen to be standing in. Remediate this
+   delivery only if the pre-existing defect is genuinely blocking it.
+
+   **`--owner` is the judgement call**, and it is yours to make from the
+   evidence: `consumer` for this repository's own code, `framework` for a
+   Mandrel defect, `platform` for a shared base config, runner fleet, or
+   cross-repo toolchain that neither owns. An unconfigured bucket files
+   locally and says so in the issue body — it never pretends to be routed.
 
 Infra, transient, and flaky failures are root-cause defects too — a flaky test
 that passes on a rerun is still a bug that will fail a future run. They route
@@ -49,9 +65,9 @@ the two options above. Name the verdict you reached in the `friction` comment.
 | Verdict | Evidence | Routes to |
 | --- | --- | --- |
 | **defect-in-diff** | The failure reproduces on the branch and not on an unmodified `main` | Option 1 — fix at source |
-| **pre-existing** | The same check fails on an unmodified `main` too | Option 2 — file `meta::framework-gap`; remediate here only if it blocks this delivery |
-| **capacity** | Proven exhaustion of a runner resource, not a property of the diff (see below) | Option 2 — file `meta::framework-gap` **and** escalate to the operator |
-| **unreproducible-tier** | The tier cannot be exercised in this sandbox at all, proven by an attempted attach (see below) | Option 2 — file `meta::framework-gap` **and** escalate on first encounter |
+| **pre-existing** | The same check fails on an unmodified `main` too | Option 2 — `file-ci-gap.js --verdict pre-existing`; remediate here only if it blocks this delivery |
+| **capacity** | Proven exhaustion of a runner resource, not a property of the diff (see below) | Option 2 — `file-ci-gap.js --verdict capacity` (`meta::framework-gap` unless `--owner` routes it elsewhere) **and** escalate to the operator |
+| **unreproducible-tier** | The tier cannot be exercised in this sandbox at all, proven by an attempted attach (see below) | Option 2 — `file-ci-gap.js --verdict unreproducible-tier` (`meta::framework-gap` unless `--owner` routes it elsewhere) **and** escalate on first encounter |
 
 Why the verdict set carries these last two is recorded in
 [`docs/decisions.md` ADR 20260906-5160a](../../docs/decisions.md).
@@ -72,10 +88,12 @@ line naming the exhausted limit (an OOM kill, `ENOSPC`, `EMFILE`,
 timeout), plus the fact that the failure is not specific to this diff. Absent
 that reading the verdict is **flaky, not capacity**, and it routes to Option 1.
 
-On a `capacity` verdict: file the `meta::framework-gap` issue with the run link,
-the failure signature, and the resource reading; flip the Story to
-`agent::blocked` with a `friction` comment naming the verdict; and hand back to
-the operator, who owns the runner pool. Do not sit in a retry loop waiting for
+On a `capacity` verdict: run `file-ci-gap.js --verdict capacity --block`, passing
+the resource reading as `--evidence` (the run link and failure signature come
+from the digest). That files the intake issue — `meta::framework-gap`, or
+`meta::platform-gap` when `--owner platform` names a shared runner fleet — posts
+the `friction` comment and flips the Story in one call; then hand back to the
+operator, who owns the runner pool. Do not sit in a retry loop waiting for
 capacity to return.
 
 **Rerunning a failed job to reach green stays forbidden under every verdict,
@@ -106,10 +124,9 @@ both:
   failure in the app under test.
 
 Absent both readings the verdict is unavailable and the failure routes as it did
-before. On the verdict: file the `meta::framework-gap` issue with the run link,
-the failure signature, and the attach attempt; flip the Story to
-`agent::blocked` with a `friction` comment naming the verdict; and hand back to
-the operator, who owns the sandbox. Do not author a fix for a tier you could not
+before. On the verdict: run
+`file-ci-gap.js --verdict unreproducible-tier --block`, passing the failed attach
+as `--evidence`; then hand back to the operator, who owns the sandbox. Do not author a fix for a tier you could not
 run — a blind fix to a suite nobody exercised is how the gap compounds.
 
 ## Verifier
@@ -131,8 +148,9 @@ alongside the failing check-run identity. On green it adjudicates:
 
 - **Same head SHA** → the green came from re-running the failed job. The
   watcher exits non-zero, flips the Story to `agent::blocked` with a
-  `friction` comment, and requires the `meta::framework-gap` issue (run link +
-  failure signature, both already in the digest) before the delivery proceeds.
+  `friction` comment, and requires the CI-gap intake issue
+  (`file-ci-gap.js` — run link and failure signature are already in the
+  digest) before the delivery proceeds.
 - **New head SHA** → fix at source. The digest is retired, auto-merge is
   re-armed, and the delivery continues unobstructed.
 
@@ -153,8 +171,8 @@ operator under **any** of:
 - **Clearly-environmental → escalate immediately.** An unambiguously
   environmental failure outside your control (runner provisioning, a persistent
   registry/network outage, a branch-protection or CI misconfiguration, an
-  expired credential) — file the `meta::framework-gap` issue (with run link +
-  signature) and escalate on the first encounter rather than burning iterations
+  expired credential) — run `file-ci-gap.js --block` and escalate on the
+  first encounter rather than burning iterations
   trying to code around it. A proven-capacity failure is this case: reach the
   `capacity` verdict above and escalate on the first encounter.
 - **Unrunnable tier → escalate immediately.** A tier the sandbox cannot host at

package/.agents/schemas/agentrc.schema.json

@@ -169,6 +169,25 @@
           "description": "Default `timeoutMs` applied to every `gh` subprocess the provider facade spawns, so a stalled socket or long-poll cannot hang an orchestration indefinitely. A `GhExecTimeoutError` from a hit ceiling is classified `transient` and retried by `withTransientRetry`. Story #2860.",
           "default": 60000
         },
+        "followUpRepos": {
+          "type": "object",
+          "description": "Repository slugs for the non-consumer follow-up ownership buckets, used when a CI gap, retro proposal, or audit finding belongs to someone other than the repo that surfaced it.",
+          "properties": {
+            "framework": {
+              "type": "string",
+              "pattern": "^[^/\\s]+/[^/\\s]+$",
+              "description": "`<owner>/<repo>` that owns framework-level defects. Defaults to the Mandrel mirror — the one bucket with a knowable default.",
+              "default": "dsj1984/mandrel"
+            },
+            "platform": {
+              "type": ["string", "null"],
+              "pattern": "^[^/\\s]+/[^/\\s]+$",
+              "description": "`<owner>/<repo>` for a shared platform or infrastructure tracker (a shared base config, a runner fleet, a cross-repo toolchain). No default — nothing can guess a shared repo. Left unset, platform-owned findings file locally and say so.",
+              "default": null
+            }
+          },
+          "additionalProperties": false
+        },
         "branchProtection": {
           "type": "object",
           "description": "Branch-protection stance applied to `project.baseBranch` by the GitHub bootstrap, and reproduced locally before every push.",

package/.agents/scripts/audit-to-stories.js

@@ -36,18 +36,20 @@ import { parseArgs } from 'node:util';
 import { buildStoryBody } from './lib/audit-to-stories/build-story-body.js';
 import { classifyGroupsAgainstGitHub } from './lib/audit-to-stories/dedupe-against-github.js';
 import { formatEpicGrouping } from './lib/audit-to-stories/epic-grouping-directive.js';
-import { withFingerprints } from './lib/audit-to-stories/finding-adapter.js';
+import {
+  toCanonicalFinding,
+  withFingerprints,
+} from './lib/audit-to-stories/finding-adapter.js';
 import { groupFindings } from './lib/audit-to-stories/group-findings.js';
 import {
-  DEFAULT_LEDGER_PATH,
-  readLedger,
-  reconcileLedger,
-  writeLedger,
-} from './lib/audit-to-stories/ledger.js';
+  loadIssuesFile,
+  normaliseIssueHit,
+} from './lib/audit-to-stories/issues-file.js';
 import {
   resolveLedgerSummary,
   runLedgerCommit,
 } from './lib/audit-to-stories/ledger-commit.js';
+import { recordFiledIssues } from './lib/audit-to-stories/ledger-record.js';
 import {
   parseAuditReports,
   readSeverityTally,
@@ -55,6 +57,12 @@ import {
 import { buildPlanSeedMarkdown } from './lib/audit-to-stories/seed-from-findings.js';
 import { wireAuditStoryEdges } from './lib/audit-to-stories/wire-dependencies.js';
 import { runAsCli } from './lib/cli-utils.js';
+import {
+  DEFAULT_LEDGER_PATH,
+  readLedger,
+  reconcileLedger,
+  writeLedger,
+} from './lib/findings/audit-ledger.js';
 import { searchSemanticCandidates } from './lib/findings/semantic-issue-search.js';
 import {
   normalizeSeverity,
@@ -366,28 +374,6 @@ class ProviderUnavailableError extends Error {
   }
 }
 
-/**
- * Flatten one raw `searchIssues` hit onto the `{ number, state, title, body }`
- * shape the dedupe module reads, collapsing every closed-ish state spelling
- * (`CLOSED`, `state_reason: not_planned`, …) onto `'closed'`.
- *
- * @param {object} hit
- * @returns {{ number: number, state: 'open'|'closed', title: string, body: string }}
- */
-function normaliseIssueHit(hit) {
-  return {
-    number: hit.number,
-    state: (hit.state ?? hit.state_reason ?? 'open')
-      .toString()
-      .toLowerCase()
-      .includes('closed')
-      ? 'closed'
-      : 'open',
-    title: hit.title ?? '',
-    body: hit.body ?? '',
-  };
-}
-
 /**
  * Walk the list endpoint once per label and merge the pages into one
  * deduplicated, normalised issue list.
@@ -649,6 +635,136 @@ function dedupDegradedWarning(entries) {
   );
 }
 
+/**
+ * Render the operator-visible line naming a host-supplied index and its size.
+ *
+ * Always emitted for a `--issues-file` run, because "how many issues did you
+ * actually check against" is the one number that separates a real dedup from a
+ * plan that merely looks checked. At zero it is the load-bearing case: an empty
+ * corpus is a legitimate first sweep AND exactly what a broken fetch writes, so
+ * the operator — not the run — decides which this was. Deliberately distinct in
+ * wording from both `dedupSkippedWarning` and `dedupDegradedWarning` so the
+ * three are never confused in a scrollback.
+ *
+ * @param {{ source?: string, size?: number }} dedupIndex
+ * @returns {string}
+ */
+function dedupIndexWarning({ size = 0 } = {}) {
+  if (size === 0) {
+    return (
+      'dedup index: 0 issues supplied via --issues-file. Dedup DID run and ' +
+      'every group is correctly "create" — but that is also what a fetch that ' +
+      'returned nothing looks like. If audit issues already exist, the fetch ' +
+      'that wrote this file is broken and this run will re-file them.'
+    );
+  }
+  return `dedup index: ${size} issue(s) supplied via --issues-file; every exact-fingerprint lookup was answered from it.`;
+}
+
+/**
+ * Render the warning for a pre-fetch of the issue index that could not
+ * complete. The run still dedups — it falls back to a per-finding search — but
+ * it loses the one-list saving, and until Story #5301 this failure was
+ * swallowed whole: the operator saw only the downstream per-group degradation
+ * and could not tell that the pre-fetch itself was the cause.
+ *
+ * @param {string} reason
+ * @returns {string}
+ */
+function dedupIndexDegradedWarning(reason) {
+  return (
+    `dedup index unavailable: ${reason}. Dedup fell back to a per-finding ` +
+    'search, which is slower and rate-limited — if those searches also fail, ' +
+    'every affected group is classified "create" WITHOUT a dedup check.'
+  );
+}
+
+/**
+ * Phase 6: classify every group against GitHub, and say loudly whichever way
+ * it went.
+ *
+ * Extracted from `buildPlan` because the gate has three outcomes, not two, and
+ * inlining them pushed the caller past its complexity ceiling. The three:
+ *
+ *   - **deduped** — a provider resolved, or the host supplied a corpus, or
+ *     both. A host-supplied corpus is a dedup source in its own right, which is
+ *     the whole point: the gate asks "can we dedup at all", not "did a provider
+ *     resolve". While it asked the latter, `--no-provider --issues-file` — the
+ *     one invocation a `gh`-less host can run — short-circuited to the seeded
+ *     all-`create` classifications however well the dedupe module worked.
+ *   - **skipped, no port** — a provider was wanted but could not be adapted.
+ *   - **skipped, disabled** — `--no-provider` with no corpus to fall back on.
+ *
+ * Every outcome warns on stderr, so the `--scan` JSON on stdout stays clean and
+ * a create-only plan is never read as "checked, found nothing".
+ *
+ * @param {{ groups: Array<object>, useProvider?: boolean,
+ *   issues?: Array<object>|null }} params
+ * @param {{ loadProviderImpl: Function, classifyGroupsImpl: Function,
+ *   logger: { warn: Function } }} deps
+ * @returns {Promise<{ classifications: Array<object>, summary: object,
+ *   dedupApplied: boolean }>}
+ */
+async function runDedupPhase(
+  { groups, useProvider, issues },
+  { loadProviderImpl, classifyGroupsImpl, logger },
+) {
+  const provider = useProvider ? await loadProviderImpl() : null;
+  if (!provider && !issues) {
+    logger.warn(
+      dedupSkippedWarning(useProvider ? 'no-provider-port' : 'disabled'),
+    );
+    return {
+      classifications: groups.map((group) => ({
+        group,
+        action: 'create',
+        matchedIssues: [],
+        matchedFingerprints: [],
+      })),
+      summary: { create: groups.length, skipOpen: 0, skipReoccurring: 0 },
+      dedupApplied: false,
+    };
+  }
+
+  const { classifications, summary } = await classifyGroupsImpl({
+    groups,
+    provider,
+    searchCandidates: provider?.searchCandidates,
+    listAuditIssues: provider?.listAuditIssues,
+    issues,
+  });
+  for (const warning of dedupPhaseWarnings({ issues, summary })) {
+    logger.warn(warning);
+  }
+  return { classifications, summary, dedupApplied: true };
+}
+
+/**
+ * Every warning a completed dedup pass owes the operator, in order. Pure, so
+ * the wording stays unit-testable and `runDedupPhase` keeps one write site.
+ *
+ * @param {{ issues?: Array<object>|null, summary: object }} params
+ * @returns {string[]}
+ */
+function dedupPhaseWarnings({ issues, summary }) {
+  const warnings = [];
+  if (issues) warnings.push(dedupIndexWarning(summary.dedupIndex));
+  // The pre-fetch failing is a distinct fact from any group's lookup failing,
+  // and used to be invisible: the operator saw only the downstream per-group
+  // degradation and could not tell what had caused it.
+  if (summary.dedupDegraded?.indexPrefetch) {
+    warnings.push(
+      dedupIndexDegradedWarning(summary.dedupDegraded.indexPrefetch),
+    );
+  }
+  // A partially-checked plan is a useful result — name the groups that degraded
+  // to create because their lookup could not complete (Story #4678).
+  if (summary.dedupDegraded?.count > 0) {
+    warnings.push(dedupDegradedWarning(summary.dedupDegraded.groups));
+  }
+  return warnings;
+}
+
 /**
  * Scan → group → dedup → (optionally) reconcile the cross-run ledger, and
  * return the plan envelope.
@@ -657,12 +773,14 @@ function dedupDegradedWarning(entries) {
  * implementation (`.agents/rules/test-seams.md` rules 1-2, 4), so `main`,
  * `runAuto`, and every production caller are unchanged.
  *
- * @param {{ glob?: string, severity?: string, useProvider?: boolean, ledger?: object }} params
+ * @param {{ glob?: string, severity?: string, useProvider?: boolean,
+ *   issuesFile?: string, ledger?: object }} params
  * @param {{
  *   collectReportPathsImpl?: typeof collectReportPaths,
  *   readReportsImpl?: typeof readReports,
  *   loadProviderImpl?: typeof loadProviderOrNull,
  *   classifyGroupsImpl?: typeof classifyGroupsAgainstGitHub,
+ *   loadIssuesFileImpl?: typeof loadIssuesFile,
  *   reconcileScanLedgerImpl?: typeof reconcileScanLedger,
  *   logger?: { warn: Function },
  * }} [deps]
@@ -673,6 +791,7 @@ async function buildPlan(
     glob: pattern,
     severity,
     useProvider,
+    issuesFile,
     ledger,
     allowMissingTally,
     failOnReportFailures,
@@ -684,9 +803,14 @@ async function buildPlan(
     readReportsImpl = readReports,
     loadProviderImpl = loadProviderOrNull,
     classifyGroupsImpl = classifyGroupsAgainstGitHub,
+    loadIssuesFileImpl = loadIssuesFile,
     reconcileScanLedgerImpl = reconcileScanLedger,
     logger = Logger,
   } = deps;
+  // Deliberately BEFORE the reports are read: an unusable corpus is a usage
+  // error, and failing fast costs the operator nothing, where failing late
+  // would tempt a fallback that silently dedups nothing.
+  const issues = issuesFile ? loadIssuesFileImpl(issuesFile) : null;
   const reportPaths = await collectReportPathsImpl(pattern ?? DEFAULT_GLOB);
   if (reportPaths.length === 0) {
     return {
@@ -724,45 +848,10 @@ async function buildPlan(
   const stamped = withFingerprints(filtered.filter((f) => Boolean(f.severity)));
   const { groups, edges } = groupFindings(stamped);
 
-  let classifications = groups.map((g) => ({
-    group: g,
-    action: 'create',
-    matchedIssues: [],
-    matchedFingerprints: [],
-  }));
-  let summary = { create: groups.length, skipOpen: 0, skipReoccurring: 0 };
-  let dedupApplied = false;
-
-  if (useProvider) {
-    const provider = await loadProviderImpl();
-    if (provider) {
-      const result = await classifyGroupsImpl({
-        groups,
-        provider,
-        searchCandidates: provider.searchCandidates,
-        listAuditIssues: provider.listAuditIssues,
-      });
-      classifications = result.classifications;
-      summary = result.summary;
-      dedupApplied = true;
-      // A partially-checked plan is a useful result — warn loudly (stderr, so
-      // the --scan JSON on stdout stays clean) naming the groups that degraded
-      // to create because their lookup could not complete (Story #4678).
-      if (summary.dedupDegraded?.count > 0) {
-        logger.warn(dedupDegradedWarning(summary.dedupDegraded.groups));
-      }
-    } else {
-      // The provider could not resolve a searchIssues port — the dedup gate
-      // is silently a no-op without this. Surface it loudly (stderr, so the
-      // --scan JSON on stdout stays clean) so the operator does not read a
-      // create-only plan as "no duplicates found".
-      logger.warn(dedupSkippedWarning('no-provider-port'));
-    }
-  } else {
-    // Operator explicitly opted out via --no-provider. Still warn so a
-    // duplicate-opening re-run is never a surprise.
-    logger.warn(dedupSkippedWarning('disabled'));
-  }
+  const { classifications, summary, dedupApplied } = await runDedupPhase(
+    { groups, useProvider, issues },
+    { loadProviderImpl, classifyGroupsImpl, logger },
+  );
 
   // Cross-run ledger (Story #4626): fold this scan onto the committed memory,
   // suppress findings a prior run recorded as accepted-risk, and (unless the
@@ -832,6 +921,9 @@ function reconcileScanLedger({ ledgerPath, findings, classifications, write }) {
     ledger: prior,
     findings,
     issueStates,
+    // The ledger lives in the shared findings layer and cannot import the
+    // audit adapter without closing a cycle, so the projection is ours to pass.
+    toCanonical: toCanonicalFinding,
   });
   if (write !== false) writeLedger(ledgerPath, next);
   return new Set(
@@ -918,6 +1010,7 @@ async function runAuto({
   severity,
   dryRun,
   useProvider,
+  issuesFile,
   ledgerPath,
   ledgerCommit,
   git,
@@ -930,6 +1023,7 @@ async function runAuto({
     glob,
     severity: floor,
     useProvider,
+    issuesFile,
     ledger: { path: resolvedLedgerPath, write: !dryRun },
     // `--auto` never accepts `--allow-missing-tally`: an unattended sweep has
     // no operator to read a warning, so every report failure is fatal here.
@@ -967,6 +1061,11 @@ async function runAuto({
       skipReoccurring: byAction.skipReoccurring.length,
       suppressedByLedger: byAction.suppressed.length,
     },
+    // `--auto` opens no Issues itself — the caller does, from the `--emit-stories`
+    // drafts — so these keys are the only thing standing between its summary and
+    // the `--wire-edges --ids` map. Without them an unattended sweep cannot
+    // record what it filed, and the ledger stays empty however well it works.
+    createGroupKeys: eligible.map((g) => g?.groupKey).filter(Boolean),
     // Re-detected open Issues the operator may want a "re-detected" comment on.
     reDetected: byAction.skipOpen
       .flatMap((c) => c.matchedIssues ?? [])
@@ -1076,20 +1175,50 @@ function wireEdgesPreconditionError(reason, detail) {
  * re-rendered with a canonical `blocked by #N` footer and the same edges are
  * mirrored as native `blocked_by` relations.
  *
+ * The same map is what the cross-run ledger needs to record what this run
+ * filed, so the record rides along here rather than arriving as a second
+ * command an operator must remember (Story #5305).
+ *
  * @param {object} params
  * @param {object} params.plan   A `--scan` plan envelope.
  * @param {Record<string, number>} params.issueByGroupKey
+ * @param {string} [params.ledgerPath] — ledger to record into; defaults to
+ *   `DEFAULT_LEDGER_PATH` inside the record.
+ * @param {boolean} [params.write] — `false` computes the record without
+ *   persisting it (what `--dry-run` passes).
  * @param {object} [deps]
  * @param {Function} [deps.loadProviderImpl]
  * @param {Function} [deps.wireImpl]
- * @returns {Promise<object>} the wiring summary.
+ * @param {Function} [deps.recordFiledIssuesImpl]
+ * @returns {Promise<object>} the wiring summary, with the ledger record on
+ *   `ledger`.
  */
-async function wireEdges({ plan, issueByGroupKey }, deps = {}) {
-  const { loadProviderImpl = loadProvider, wireImpl = wireAuditStoryEdges } =
-    deps;
+async function wireEdges(
+  { plan, issueByGroupKey, ledgerPath, write },
+  deps = {},
+) {
+  const {
+    loadProviderImpl = loadProvider,
+    wireImpl = wireAuditStoryEdges,
+    recordFiledIssuesImpl = recordFiledIssues,
+  } = deps;
   const groups = (plan.classifications ?? [])
     .filter((c) => c.action === 'create')
     .map((c) => c.group);
+
+  // Record BEFORE the provider is loaded. The record is pure local filesystem
+  // work, while the wiring below needs a provider exposing `updateTicket` — and
+  // the host most likely to lack one is the `gh`-less host where the ledger is
+  // the only duplicate protection there is. Recording first means such a run
+  // still remembers what it filed, and the precondition error below still
+  // surfaces unchanged afterwards.
+  const ledger = recordFiledIssuesImpl({
+    ledgerPath,
+    groups,
+    issueByGroupKey,
+    write,
+  });
+
   let provider;
   try {
     provider = await loadProviderImpl();
@@ -1099,7 +1228,7 @@ async function wireEdges({ plan, issueByGroupKey }, deps = {}) {
   if (typeof provider?.updateTicket !== 'function') {
     throw wireEdgesPreconditionError('fixture-no-write-port');
   }
-  return wireImpl({
+  const wired = await wireImpl({
     groups,
     edges: plan.edges ?? [],
     issueByGroupKey,
@@ -1107,6 +1236,7 @@ async function wireEdges({ plan, issueByGroupKey }, deps = {}) {
     updateBody: (issueNumber, body) =>
       provider.updateTicket(issueNumber, { body }),
   });
+  return { ...wired, ledger };
 }
 
 /**
@@ -1161,6 +1291,8 @@ export const __testing = {
   loadProviderOrNull,
   dedupSkippedWarning,
   dedupDegradedWarning,
+  dedupIndexWarning,
+  dedupIndexDegradedWarning,
   buildAndGateStories,
   runAuto,
   resolveSeverityFloor,
@@ -1291,6 +1423,7 @@ export async function runAuditToStories(
       plan: { type: 'string' },
       out: { type: 'string' },
       'no-provider': { type: 'boolean' },
+      'issues-file': { type: 'string' },
       'allow-missing-tally': { type: 'boolean' },
       json: { type: 'boolean' },
     },
@@ -1308,6 +1441,7 @@ export async function runAuditToStories(
         severity: values.severity,
         dryRun: values['dry-run'],
         useProvider: !values['no-provider'],
+        issuesFile: values['issues-file'],
         ledgerPath: values.ledger,
         ledgerCommit: values['ledger-commit'],
       })
@@ -1334,6 +1468,7 @@ export async function runAuditToStories(
       glob: values.glob,
       severity: values.severity,
       useProvider: !values['no-provider'],
+      issuesFile: values['issues-file'],
       allowMissingTally: values['allow-missing-tally'],
     });
 
@@ -1359,6 +1494,11 @@ export async function runAuditToStories(
     wireEdgesImpl({
       plan: loadPlanImpl(values.plan),
       issueByGroupKey: parseIssueMapImpl(values.ids),
+      ledgerPath: values.ledger,
+      // `--scan` still never writes the ledger; `--wire-edges` runs only after
+      // the Issues were really opened, where recording is never wrong — so the
+      // record is on by default here and `--dry-run` is what suppresses it.
+      write: !values['dry-run'],
     });
 
   // One table, not a chain of `if (values.X) { …; return; }`. Each entry
@@ -1435,7 +1575,7 @@ runAsCli(import.meta.url, main, {
       ['--emit-stories', 'Emit the Story drafts as JSON.'],
       [
         '--wire-edges',
-        'Second pass: resolve the detected group edges to blocked by #N footers plus native blocked_by relations. Needs --plan and --ids.',
+        'Second pass: resolve the detected group edges to blocked by #N footers plus native blocked_by relations, and record the mapped issues in the cross-run ledger as filed. Needs --plan and --ids; --dry-run suppresses the ledger write.',
       ],
       [
         '--ids <json|path>',
@@ -1443,7 +1583,10 @@ runAsCli(import.meta.url, main, {
       ],
       ['--glob <pattern>', 'Override the audit-results glob.'],
       ['--severity <level>', 'Lowest severity to include (high|medium|low).'],
-      ['--ledger <path>', 'Path to the dedup ledger.'],
+      [
+        '--ledger <path>',
+        `Path to the cross-run dedup ledger (default ${DEFAULT_LEDGER_PATH}).`,
+      ],
       [
         '--ledger-commit',
         'After the --auto summary prints, commit a changed ledger onto chore/audit-ledger-<date>, push it, and open a PR against the base branch (never auto-merged). Ignored under --dry-run.',
@@ -1454,6 +1597,10 @@ runAsCli(import.meta.url, main, {
       ],
       ['--out <path>', 'Write output to a file instead of stdout.'],
       ['--no-provider', 'Skip live GitHub dedup lookups (offline).'],
+      [
+        '--issues-file <path>',
+        'Dedup against a JSON array of issues the host already fetched (every issue labelled audit::*, state all) instead of listing them through the provider. Lets dedup run where there is no gh CLI; composes with --no-provider.',
+      ],
       [
         '--allow-missing-tally',
         'Downgrade a missing "Severity tally:" line to a warning (--scan only; --auto ignores it).',