mandrel 2.59.0 → 2.61.0

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

@@ -1,41 +1,7 @@
 /**
- * lib/audit-to-stories/dedupe-against-github.js
- *
- * Idempotency gate: classify each proposed group as either eligible-to-create,
- * already-open (skip), or re-occurring (skip, but flag).
- *
- * This module owns **no** fingerprint or dedup logic. It routes every
- * finding through the shared `lib/findings/route-finding.js` helper — the
- * single dedup/route implementation, shared verbatim with `qa-explore` — and
- * folds the per-finding `routeFinding` decisions up to a group action:
- *
- *   - any finding routes to `update-existing` / `duplicate` → `skip-open`
- *   - else any finding routes to `regression-of-closed`     → `skip-reoccurring`
- *   - else (every finding is `new`)                          → `create`
- *
- * The GitHub lookup is delegated to a `provider` port the caller injects,
- * exposing `findIssuesByFingerprint(sha)` → `{ number, state, body }[]`. The
- * port is adapted into the `searchIssues` shape the shared helper expects.
- * When the caller ALSO injects a `searchCandidates(finding)` port (production
- * wires it to `semantic-issue-search.js`), routing runs the meaning-first
- * Stage-1 pass and opts into location-based semantic-key confirmation so a
- * 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.
- *
- * 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.
+ * Classify each group `create`, `skip-open` (any open match) or
+ * `skip-reoccurring` (any closed match) by folding `route-finding.js`
+ * decisions. No I/O.
  */
 
 import { routeFinding, semanticKeyFor } from '../findings/route-finding.js';
@@ -52,12 +18,7 @@ import { 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.
+ * One vocabulary for both degrade paths (index pre-fetch and per-group lookup).
  *
  * @param {unknown} err
  * @returns {string}
@@ -75,7 +36,6 @@ function describeDegradeReason(err) {
 }
 
 /**
- * Stable operator-facing label for a group in a degrade report.
  * @param {object} group
  * @returns {string}
  */
@@ -84,11 +44,7 @@ function groupLabel(group) {
 }
 
 /**
- * Route every finding in one group and fold the per-finding decisions up to a
- * group action. Extracted so the top-level loop can wrap it in one try/catch:
- * a search failure that survives the endpoint budget (an HTTP 422, or a rate
- * limit still exhausted after the cooldown) throws out of here and is caught
- * once per group rather than aborting the whole scan (Story #4678).
+ * Throws on lookup failure; caught per group by the caller.
  *
  * @param {object} group
  * @param {object} routing — `{ searchIssues, semanticPort, routeOptions }`.
@@ -141,14 +97,8 @@ async function classifyOneGroup(
 }
 
 /**
- * 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.
+ * With an index, the exact lookup is answered from memory and the semantic
+ * search (the only network call left) runs only when there is no exact hit.
  *
  * @param {object} canonical — the canonical finding projection.
  * @param {string} sha — its full fingerprint.
@@ -171,25 +121,15 @@ function portsFor(canonical, sha, { searchIssues, semanticPort, index }) {
  * @param {object} params
  * @param {Array<object>} params.groups — output of `groupFindings`.
  * @param {{ findIssuesByFingerprint: (sha: string) => Promise<Array<{ number: number, state: string, body?: string }>> }} params.provider
+ *   Only read on the un-indexed path.
  * @param {(finding: object) => Promise<Array<{ number: number, state: string, title?: string, body?: string }>>} [params.searchCandidates]
- *   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.
+ *   Enables the semantic pass and 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 {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".
+ *   Fetched once and indexed.
+ * @param {Array<object>} [params.issues] Pre-fetched corpus, preferred over
+ *   `listAuditIssues`; lets a host with no `gh` dedup. `[]` is a valid corpus.
  * @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
- *   fatal. Pure orchestration: this module performs no network I/O and swallows
- *   no failure silently.
+ *   Notified per group whose lookup failed; that group soft-fails to `create`.
  * @returns {Promise<{ classifications: GroupClassification[], summary: { create: number, skipOpen: number, skipReoccurring: number, dedupDegraded: { count: number, groups: Array<{ group: string, reason: string }> } } }>}
  */
 export async function classifyGroupsAgainstGitHub({
@@ -212,11 +152,7 @@ export async function classifyGroupsAgainstGitHub({
     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.
+    // Not counted as a degraded group: per-finding search still checks each.
     const reason = `issue-index pre-fetch failed: ${describeDegradeReason(error)}`;
     summary.dedupDegraded.indexPrefetch = reason;
     if (typeof onDegraded === 'function') onDegraded({ group: null, reason });
@@ -229,8 +165,6 @@ export async function classifyGroupsAgainstGitHub({
     try {
       result = await classifyOneGroup(group, routing);
     } catch (err) {
-      // A dedup lookup that cannot complete degrades this group to `create`
-      // with a recorded reason — never aborts the whole scan.
       const reason = describeDegradeReason(err);
       const entry = { group: groupLabel(group), reason };
       summary.dedupDegraded.count += 1;

package/.agents/scripts/lib/audit-to-stories/epic-grouping-directive.js

@@ -1,20 +1,8 @@
 /**
- * epic-grouping-directive.js — the container-Epic directive an audit sweep
- * emits (Story #5139).
- *
- * Lives on its own because **both** `/audit-to-stories` output paths carry it:
- * the `/mandrel-plan` seed one-pager (`seed-from-findings.js`) and the
- * standalone Story-draft transcript (`audit-to-stories.js`). A sweep is the
- * clearest case for a container — every Story shares a provenance and the
- * operator almost always wants them delivered together — so the Epic is the
- * **default** here, unlike the offer `/mandrel-plan` makes on an ad-hoc plan.
- *
- * It stays a directive in the text rather than an automatic write: the
- * workflow's Phase 4 HITL stop is where an operator declines it.
- *
- * Since Story #5155 the directive names adoption first: a repeat sweep over the
- * same area is the case most likely to already have a container, and opening a
- * second one beside it is the failure this ordering exists to prevent.
+ * The container-Epic directive both `/audit-to-stories` output paths carry.
+ * For a sweep the Epic is the default (shared provenance), declinable at the
+ * HITL stop; adoption of an existing Epic is named first so a repeat sweep
+ * does not open a second container.
  *
  * @module lib/audit-to-stories/epic-grouping-directive
  */
@@ -22,8 +10,6 @@
 import { EPIC_SUGGESTION_THRESHOLD } from '../orchestration/plan-persist/epic-ops.js';
 
 /**
- * Render the grouping directive for a proposed Story set.
- *
  * @param {unknown[]} groups The proposed Stories (only the count is read).
  * @returns {string} Markdown paragraph(s).
  */

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

@@ -1,16 +1,6 @@
 /**
- * lib/audit-to-stories/finding-adapter.js — Project audit findings onto the
- * shared findings identity.
- *
- * `/audit-to-stories` parses `audit-*-results.md` into findings shaped as
- * `{ dimension, severity, title, normalisedTitle, files, ... }`. The shared
- * dedup/route helper (`lib/findings/route-finding.js`) fingerprints over the
- * canonical identity `{ title, area, primaryFile, severity, labels }`. This
- * module is the thin, audit-specific adapter that maps the former onto the
- * latter and reuses the shared helper's primitives — it contains **no**
- * fingerprint or dedup logic of its own. The single dedup/route
- * implementation lives in `lib/findings/route-finding.js`, shared verbatim
- * with `qa-explore`.
+ * Project parsed audit findings onto the shared findings identity. No
+ * fingerprint or dedup logic of its own — that lives in `route-finding.js`.
  */
 
 import {
@@ -21,13 +11,8 @@ import {
 } from '../findings/route-finding.js';
 
 /**
- * Map an audit finding onto the canonical identity the shared helper
- * fingerprints over. The audit pipeline already lower-cases `dimension` and
- * normalises the title; `files[0]` is the primary file the parser pulled
- * from the finding body. `dimension` is the identity axis (carried as
- * `area`) and also the sole label so two findings in the same dimension that
- * are otherwise identical collide exactly as the legacy
- * `(dimension, normalisedTitle, primaryFile)` key did.
+ * `dimension` is both `area` and the sole label, so identity stays
+ * `(dimension, normalisedTitle, primaryFile)`; severity is excluded.
  *
  * @param {{ dimension?: string, normalisedTitle?: string, files?: string[] }} finding
  * @returns {{ title: string, area: string, primaryFile: string, severity: string, labels: string[] }}
@@ -48,8 +33,6 @@ export function toCanonicalFinding(finding) {
 }
 
 /**
- * Compute the shared-helper fingerprint for a single audit finding.
- *
  * @param {object} finding
  * @returns {{ short: string, full: string, components: object }}
  */
@@ -58,13 +41,7 @@ export function fingerprintAuditFinding(finding) {
 }
 
 /**
- * Compute the location-based semantic key for a single audit finding via the
- * 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`.
+ * Location-based key, stable across a reworded title.
  *
  * @param {object} finding
  * @returns {string}
@@ -74,10 +51,6 @@ function semanticKeyForAuditFinding(finding) {
 }
 
 /**
- * Stamp every audit finding with its shared-helper fingerprint and return a
- * new array. Mirrors the legacy `withFingerprints` contract so downstream
- * grouping / story-body / dedupe consumers keep reading `finding.fingerprint`.
- *
  * @template T
  * @param {Array<T>} findings
  * @returns {Array<T & { fingerprint: { short: string, full: string } }>}
@@ -93,9 +66,7 @@ export function withFingerprints(findings) {
 }
 
 /**
- * Render the machine-readable fingerprint footer for a group of findings,
- * via the shared helper's single footer renderer. Findings must already
- * carry `fingerprint.full` (set by {@link withFingerprints}).
+ * Findings must already carry `fingerprint.full` ({@link withFingerprints}).
  *
  * @param {Array<{ fingerprint?: { full?: string } }>} findings
  * @returns {string}
@@ -111,11 +82,7 @@ export function renderFingerprintFooter(findings) {
 }
 
 /**
- * Render the location-based semantic-key footer for a group of findings, via
- * the shared helper's single footer renderer. Stamped alongside the
- * fingerprint footer so a later reworded finding at the same location still
- * confirms a dedup match (Story #4626). Findings do not need a precomputed
- * key — it is derived from each finding's canonical projection here.
+ * Lets a reworded finding at the same location still confirm a dedup match.
  *
  * @param {Array<object>} findings
  * @returns {string}

package/.agents/scripts/lib/audit-to-stories/group-findings.js

@@ -1,24 +1,8 @@
 /**
- * lib/audit-to-stories/group-findings.js — Cluster findings into Stories.
- *
- * Grouping signals, in priority order (Story #2583):
- *   1. **Same primary file** — two findings on the same file merge.
- *   2. **Adjacent files in the same module directory** — when the
- *      directory hash matches and there is no stronger signal.
- *   3. **Root-cause keyword overlap** — shared topical n-gram across
- *      Current State / Title.
- *
- * Cross-audit grouping is enabled by default: a `security` finding and a
- * `clean-code` finding on the same file produce a single group with both
- * dimensions captured (`group.dimensions` is an array — callers map this
- * to multiple `audit::<dim>` labels).
- *
- * Dependency edges (Recommendation of A references the file Current
- * State of B flags) are emitted as a separate `edges` array — they do
- * NOT merge the groups. The CLI surfaces them in the preview so the
- * operator can decide if a sequencing constraint is worth flagging.
- *
- * Pure: no I/O.
+ * Cluster findings (across lenses) into Stories by: same primary file, then
+ * same directory with root-cause keyword overlap, then keyword overlap alone.
+ * Dependency edges (A's recommendation names B's file) are reported
+ * separately and never merge groups. Pure.
  */
 
 import { highestSeverity as highestSeverityOf } from '../findings/severity.js';
@@ -38,16 +22,8 @@ function pickPrimaryFile(finding) {
 }
 
 /**
- * The highest severity across a group's findings, ranked by the severity SSOT
- * ({@link highestSeverityOf}) rather than a local copy of the scale.
- *
- * The rank map this replaces knew four levels and not `info`, so an Info
- * finding tied with a finding carrying no severity at all — the same partial
- * vocabulary this Story removes everywhere else.
- *
- * A group whose findings all lack a usable severity still reports `null`, not
- * the SSOT's `info` floor: absent is not the same claim as "graded lowest",
- * and the callers that tally and threshold on this value distinguish them.
+ * `null` (not `info`) when no finding states a severity: absent is not
+ * "graded lowest", and callers distinguish them.
  *
  * @param {Array<{ severity?: string }>} findings
  * @returns {string|null} a canonical severity, or null when none is stated.
@@ -88,7 +64,6 @@ function tokenisePhrase(text) {
 }
 
 function rootCauseSignature(finding) {
-  // Topical tokens drawn from title + current-state.
   const title = tokenisePhrase(finding.normalisedTitle ?? finding.title ?? '');
   const state = tokenisePhrase(finding.currentState ?? '');
   return new Set([...title, ...state]);
@@ -143,8 +118,7 @@ function synthesizeTitle(group) {
 }
 
 function detectDependencyEdges(groups) {
-  // A dependency edge fires when group B's primary file is mentioned in
-  // group A's Recommendation text (i.e. fixing A requires B to land).
+  // A → B when A's recommendation mentions a file B owns.
   const fileToGroup = new Map();
   for (const g of groups) {
     const filesIter = Array.isArray(g.files) ? g.files : [...g.files];
@@ -176,8 +150,6 @@ function detectDependencyEdges(groups) {
 }
 
 /**
- * Cluster findings into Stories.
- *
  * @param {Array<{
  *   dimension: string,
  *   severity: string|null,
@@ -204,7 +176,6 @@ export function groupFindings(findings) {
     if (primary) {
       key = `file:${primary}`;
     } else {
-      // No file → try signature-based merge with an existing group.
       const { key: matchKey, sig } = bestSignatureGroupKey(finding, sigBuckets);
       if (matchKey) {
         key = matchKey;
@@ -227,9 +198,8 @@ export function groupFindings(findings) {
     attachFindingToGroup(groups.get(key), finding);
   }
 
-  // Second pass: merge any single-finding groups whose primary directory
-  // matches another group's directory AND whose root-cause signatures
-  // overlap by ≥ 3 tokens. This implements signal #2.
+  // Merge single-finding groups into a same-directory group sharing ≥ 3
+  // signature tokens.
   const groupArray = [...groups.values()];
   const merged = new Set();
   for (let i = 0; i < groupArray.length; i += 1) {

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

@@ -1,42 +1,13 @@
-/**
- * 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.
- */
+/** Source and describe the dedup corpus. No I/O. */
 
 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.
+ * An injected `issues` corpus wins; else pre-fetch once off the list port.
+ * An empty corpus is a real zero-row index, and a failed pre-fetch returns its
+ * `error`: neither may collapse to a null index, which silently means no dedup
+ * on a provider-less host.
  *
  * @param {{ listAuditIssues?: Function, groups?: Array<object>,
  *   issues?: Array<object> }} params
@@ -65,17 +36,7 @@ async function resolveIssueCorpus({ listAuditIssues, groups, issues }) {
 }
 
 /**
- * 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.
+ * Omits `dedupIndex` when no index was expected; describes a failed prefetch.
  *
  * @param {object} summary — the seeded counters.
  * @param {{ source: string, index: object|null, error?: unknown }} resolution
@@ -87,24 +48,12 @@ function withIndexDescription(summary, { source, index, error }) {
 }
 
 /**
- * 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.
+ * Routing ports, resolved index and seeded summary. The provider port is
+ * required only without a corpus: with an index, exact lookups never call it.
  *
  * @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.
  */
@@ -132,17 +81,12 @@ export async function prepareDedupRouting({
     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.
+      // An index carries the semantic-key map, so confirmation is free; without
+      // it a provider-less run would be fingerprint-exact only.
       routeOptions: {
         semanticKeyConfirm: Boolean(semanticPort) || Boolean(index),
       },

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

@@ -1,23 +1,7 @@
 /**
- * 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.
+ * Local index of `audit::*` Issues by provenance footer, listed once per run.
+ * Search is far more rate-limited than list, so exact-fingerprint lookups are
+ * answered here and search is spent only on findings with no exact hit. Pure.
  */
 
 import {
@@ -26,8 +10,6 @@ import {
 } 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
@@ -39,10 +21,7 @@ function push(map, 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.
+ * An issue with neither footer is indexed under nothing.
  *
  * @param {Array<{ number: number, state: string, body?: string }>} issues
  * @returns {{ byFingerprint: Map<string, object[]>, bySemanticKey: Map<string, object[]>, size: number }}
@@ -65,11 +44,8 @@ export function buildIssueIndex(issues) {
 }
 
 /**
- * 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.
+ * Fingerprint hits first: `routeFinding` keeps the first record per issue
+ * number, and the exact-identity one should survive into confirmation.
  *
  * @param {{ byFingerprint: Map, bySemanticKey: Map }} index
  * @param {string} sha

package/.agents/scripts/lib/audit-to-stories/issues-file.js

@@ -1,34 +1,14 @@
 /**
- * lib/audit-to-stories/issues-file.js — the issue corpus dedup checks against,
- * and the one normaliser every source of it goes through.
- *
- * Dedup needs exactly one thing from GitHub: the list of Issues carrying an
- * `audit::*` label. Until Story #5301 the only way to get it was the provider,
- * 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 but the
- * GitHub MCP tools work fine — could not dedup at all. Every group classified
- * `create` and a scheduled sweep re-filed findings it had already filed.
- *
- * `--issues-file <path>` breaks that coupling: the host fetches the list by
- * whatever access path it has and hands over a JSON array. Nothing here knows
- * how it was fetched, so MCP, REST, and a cached dump are all equally valid.
- *
- * A file that cannot be read as an issue array is a **hard error**, never a
- * degrade. Falling back would mean "dedup did not run" on precisely the
- * invocation whose whole purpose is that it does — and a create-only plan the
- * operator reads as checked is how the duplicate-filing loop starts.
+ * `--issues-file`: a host-fetched `audit::*` issue corpus (MCP, REST, a dump),
+ * so dedup runs without `gh`. An unreadable file is a hard error, never a
+ * degrade — a silently create-only plan starts the duplicate-filing loop.
  */
 
 import fs from 'node:fs';
 
 /**
- * Flatten one raw issue onto the `{ number, state, title, body }` shape the
- * dedupe module reads, collapsing every closed-ish state spelling (`CLOSED`,
- * `state_reason: not_planned`, …) onto `'closed'`.
- *
- * Shared by both corpus sources — the provider's `searchIssues` hits and the
- * `--issues-file` array — so a host can hand over a raw `list_issues` result
- * verbatim without knowing which spelling this repo's dedup expects.
+ * The one normaliser for every corpus source; any closed-ish `state` or
+ * `state_reason` spelling becomes `'closed'`.
  *
  * @param {object} hit
  * @returns {{ number: number, state: 'open'|'closed', title: string, body: string }}
@@ -48,13 +28,6 @@ export function normaliseIssueHit(hit) {
 }
 
 /**
- * Read and normalise a host-supplied issue corpus.
- *
- * `state` is read from either `state` or `state_reason`, so a closed-as-
- * not-planned issue is recognised however the host's API spelled it. Only
- * `number` and `body` are load-bearing: the number identifies the match and
- * the body carries the provenance footers dedup confirms identity against.
- *
  * @param {string} filePath — path to a JSON array of issues.
  * @param {{ readFileSyncImpl?: typeof fs.readFileSync }} [seams]
  * @returns {Array<{ number: number, state: string, title: string, body: string }>}
@@ -94,9 +67,7 @@ export function loadIssuesFile(
 }
 
 /**
- * Whether one array entry can possibly identify an issue. An entry without a
- * numeric `number` can never confirm a match — exactly as it could not when it
- * came back from a search — so it is dropped rather than indexed under nothing.
+ * Without a numeric `number` an entry can never confirm a match, so it drops.
  *
  * @param {unknown} entry
  * @returns {boolean}
@@ -110,7 +81,6 @@ function isIssueLike(entry) {
 }
 
 /**
- * Name what a non-array payload actually was, so the error points at the fix.
  * @param {unknown} value
  * @returns {string}
  */