mandrel 2.54.0 → 2.56.0

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

@@ -36,27 +36,39 @@ 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,
-  parseSeverityTally,
+  readSeverityTally,
 } from './lib/audit-to-stories/parse-audit-md.js';
 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 { SEVERITIES, SEVERITY_RANK } from './lib/findings/severity.js';
+import {
+  normalizeSeverity,
+  SEVERITIES,
+  SEVERITY_RANK,
+} from './lib/findings/severity.js';
 import { Logger } from './lib/Logger.js';
 import { parse as parseStoryBody } from './lib/story-body/story-body.js';
 
@@ -209,6 +221,11 @@ function auditReportFailures({
  *   hand-written report). `allowMissingTally` downgrades ONLY this kind to a
  *   warning, for an interactive `--scan` over legacy reports.
  * - `tally-mismatch` — the report says one thing and the parse says another.
+ * - `duplicate-tally` — the report declares the tally more than once, so there
+ *   is no single number to check against. Adopting whichever line the scan
+ *   reached first would compare the parse against an arbitrary one of two
+ *   declarations, which is a cross-check in name only. `allowMissingTally`
+ *   does NOT downgrade it: the report is contradictory, not merely old.
  * - `unresolved-severity` — a finding parsed with no resolvable severity. It
  *   is a report defect, never an `unknown` group.
  *
@@ -232,7 +249,11 @@ function crossCheckReports({ reports, findings, allowMissingTally }) {
   for (const report of reports) {
     const own = byReport.get(report.sourceReport) ?? [];
     const parsed = comparableTally(own);
-    const reported = parseSeverityTally(report.markdown);
+    const {
+      tally: reported,
+      matches: tallyLines,
+      duplicate,
+    } = readSeverityTally(report.markdown);
     const sourceReport = report.sourceReport;
     const unresolved = own.filter((f) => !f.severity);
     if (unresolved.length > 0) {
@@ -244,6 +265,16 @@ function crossCheckReports({ reports, findings, allowMissingTally }) {
         titles: unresolved.map((f) => f.title),
       });
     }
+    if (duplicate) {
+      failures.push({
+        sourceReport,
+        kind: 'duplicate-tally',
+        reported: null,
+        parsed,
+        tallyLines,
+      });
+      continue;
+    }
     if (!reported) {
       const failure = {
         sourceReport,
@@ -282,7 +313,7 @@ function missingTallyWarning(failure) {
  *
  * Pure: returns the message string so the caller owns the single `Logger.warn`.
  *
- * @param {Array<{ sourceReport: string, kind: string, reported: object|null, parsed: object, titles?: string[] }>} failures
+ * @param {Array<{ sourceReport: string, kind: string, reported: object|null, parsed: object, titles?: string[], tallyLines?: string[] }>} failures
  * @returns {string}
  */
 function reportFailureWarning(failures) {
@@ -290,7 +321,13 @@ function reportFailureWarning(failures) {
     const titles = f.titles?.length
       ? ` findings=${f.titles.map((t) => `"${t}"`).join(', ')}`
       : '';
-    return `  - ${f.sourceReport} [${f.kind}] reported=${formatTally(f.reported)} parsed=${formatTally(f.parsed)}${titles}`;
+    // A duplicate names the competing lines rather than a tally: there is no
+    // single `reported` number to print, and "which two lines" is the whole
+    // remedy.
+    const declared = f.tallyLines?.length
+      ? ` declared=${f.tallyLines.map((t) => `"${t}"`).join(' | ')}`
+      : '';
+    return `  - ${f.sourceReport} [${f.kind}] reported=${formatTally(f.reported)} parsed=${formatTally(f.parsed)}${titles}${declared}`;
   });
   return [
     `audit report cross-check FAILED for ${failures.length} report(s) — the declared severity tally does not match the parsed findings:`,
@@ -338,25 +375,31 @@ 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'`.
+ * Walk the list endpoint once per label and merge the pages into one
+ * deduplicated, normalised issue list.
+ *
+ * `labels` is an OR across the run's lenses, which the REST list endpoint
+ * cannot express in one query (its `labels` parameter is an AND), so one call
+ * per label is the narrowest honest read. Each is a paginated **list**, not a
+ * search — a different, far larger rate-limit budget.
  *
- * @param {object} hit
- * @returns {{ number: number, state: 'open'|'closed', title: string, body: string }}
+ * @param {object} provider
+ * @param {string[]} labels
+ * @returns {Promise<Array<object>>}
  */
-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 ?? '',
-  };
+async function listIssuesForLabels(provider, labels) {
+  const seen = new Map();
+  for (const label of labels) {
+    const issues = await provider.listIssuesByLabel({
+      state: 'all',
+      labels: label,
+    });
+    for (const raw of issues ?? []) {
+      const hit = normaliseIssueHit(raw);
+      if (!seen.has(hit.number)) seen.set(hit.number, hit);
+    }
+  }
+  return [...seen.values()];
 }
 
 /**
@@ -368,7 +411,8 @@ function normaliseIssueHit(hit) {
  *
  * @param {object} provider
  * @param {{ owner: string, repo: string }} coords
- * @returns {{ findIssuesByFingerprint: Function, searchCandidates: Function }}
+ * @returns {{ findIssuesByFingerprint: Function, listAuditIssues: Function,
+ *   searchCandidates: Function }}
  */
 function buildDedupPorts(provider, { owner, repo }) {
   return {
@@ -376,6 +420,21 @@ function buildDedupPorts(provider, { owner, repo }) {
       const hits = await provider.searchIssues({ query: sha, owner, repo });
       return (hits ?? []).map(normaliseIssueHit);
     },
+    /**
+     * List every Issue carrying one of the run's `audit::*` labels, once, off
+     * the REST list endpoint. The dedup module indexes the result and answers
+     * every exact-fingerprint lookup from it, so the rate-limited search API is
+     * spent only on findings it has never seen. A provider without the list
+     * port yields `null`, which returns dedup to the per-finding search path
+     * rather than silently skipping it.
+     *
+     * @param {string[]} labels
+     * @returns {Promise<Array<object>|null>}
+     */
+    async listAuditIssues(labels) {
+      if (typeof provider.listIssuesByLabel !== 'function') return null;
+      return listIssuesForLabels(provider, labels);
+    },
     async searchCandidates(finding) {
       // Wire the shared semantic search onto the provider's full-text
       // issue search (open + closed) so route-finding's Stage-1 pass runs.
@@ -576,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.
@@ -584,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]
@@ -600,6 +791,7 @@ async function buildPlan(
     glob: pattern,
     severity,
     useProvider,
+    issuesFile,
     ledger,
     allowMissingTally,
     failOnReportFailures,
@@ -611,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 {
@@ -651,44 +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,
-      });
-      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
@@ -758,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(
@@ -844,6 +1010,7 @@ async function runAuto({
   severity,
   dryRun,
   useProvider,
+  issuesFile,
   ledgerPath,
   ledgerCommit,
   git,
@@ -856,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.
@@ -893,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 ?? [])
@@ -1002,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();
@@ -1025,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,
@@ -1033,6 +1236,7 @@ async function wireEdges({ plan, issueByGroupKey }, deps = {}) {
     updateBody: (issueNumber, body) =>
       provider.updateTicket(issueNumber, { body }),
   });
+  return { ...wired, ledger };
 }
 
 /**
@@ -1087,6 +1291,8 @@ export const __testing = {
   loadProviderOrNull,
   dedupSkippedWarning,
   dedupDegradedWarning,
+  dedupIndexWarning,
+  dedupIndexDegradedWarning,
   buildAndGateStories,
   runAuto,
   resolveSeverityFloor,
@@ -1117,6 +1323,73 @@ export const __testing = {
  * }} [deps]
  * @returns {Promise<void>}
  */
+/**
+ * The one-line `--ledger-commit` outcome, for stderr.
+ *
+ * Names the branch and the PR on success — the two things an operator needs to
+ * go look at it — and the skip reason otherwise, because "nothing happened" and
+ * "the ledger was already clean" are different facts and only one of them is
+ * fine.
+ *
+ * @param {{ committed?: boolean, reason?: string, branch?: string,
+ *   prUrl?: string|null, resumed?: boolean, ledgerPath?: string }} [result]
+ * @returns {string}
+ */
+function describeLedgerCommit(result) {
+  return result?.committed
+    ? ledgerCommittedLine(result)
+    : ledgerSkippedLine(result);
+}
+
+/**
+ * The success half: the branch, whether it resumed a half-finished one, and
+ * the PR to go look at.
+ * @param {object} result
+ * @returns {string}
+ */
+function ledgerCommittedLine(result) {
+  const resumed = result.resumed ? ' (resumed an unpushed ledger branch)' : '';
+  const pr = result.prUrl ?? '(no URL reported by gh)';
+  return `--ledger-commit: pushed ${result.branch}${resumed} and opened ${pr}.`;
+}
+
+/**
+ * The skip half. It names the ledger file, because the fact that matters is
+ * which state is still only in the working tree.
+ * @param {object} [result]
+ * @returns {string}
+ */
+function ledgerSkippedLine(result) {
+  const reason = result?.reason ?? 'no result';
+  const ledgerPath = result?.ledgerPath ?? 'the ledger';
+  return `--ledger-commit: skipped (${reason}) — ${ledgerPath} was not committed.`;
+}
+
+/**
+ * Validate `--severity` against the canonical scale, failing on a value the
+ * filter would silently ignore.
+ *
+ * `meetsSeverity` reads an unknown threshold as rank `0`, so a typo — the
+ * classic being `--severity Hgh` — quietly widened the run to every finding
+ * instead of narrowing it. On an unattended sweep that is the difference
+ * between filing a batch and filing the backlog, with nothing on stderr to say
+ * so. An absent flag stays absent: the floor then resolves from config.
+ *
+ * @param {string|undefined} raw
+ * @returns {string|undefined} the canonical level.
+ */
+function validateSeverityFlag(raw) {
+  if (raw === undefined || raw === null || raw === '') return undefined;
+  if (String(raw).toLowerCase() === 'all') return 'all';
+  const level = normalizeSeverity(String(raw), null);
+  if (!level) {
+    throw new Error(
+      `[audit-to-stories] --severity "${raw}" is not a severity. Accepted: ${SEVERITIES.join(', ')} (or "all").`,
+    );
+  }
+  return level;
+}
+
 export async function runAuditToStories(
   argv = process.argv.slice(2),
   deps = {},
@@ -1150,12 +1423,15 @@ 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' },
     },
     strict: false,
   });
 
+  values.severity = validateSeverityFlag(values.severity);
+
   const json = (value) => JSON.stringify(value, null, 2);
 
   const runAutoSummary = async () =>
@@ -1165,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'],
       })
@@ -1175,7 +1452,15 @@ export async function runAuditToStories(
   // findings, so the PR attempt is the last thing the run does (Story #5145).
   const commitLedger = async () => {
     if (!values['ledger-commit'] || values['dry-run']) return;
-    await runLedgerCommitImpl({ ledgerPath: values.ledger });
+    // Say what happened. The tail used to run silently, so an operator could
+    // not tell a ledger PR from a skip without going to look for the branch —
+    // and a skip is the outcome that matters, because it means the sweep's
+    // memory is still only in the working tree.
+    Logger.warn(
+      describeLedgerCommit(
+        await runLedgerCommitImpl({ ledgerPath: values.ledger }),
+      ),
+    );
   };
 
   const scanPlan = () =>
@@ -1183,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'],
     });
 
@@ -1208,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
@@ -1284,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>',
@@ -1292,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.',
@@ -1303,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).',