mandrel 2.60.0 → 2.62.0

package/.agents/scripts/lib/findings/provenance-field.js

@@ -1,22 +1,6 @@
 /**
- * lib/findings/provenance-field.js — the per-Story `provenance` field.
- *
- * An audit-seeded plan carries dedup identities forward so the next sweep
- * recognises what it already planned. The optional top-level `provenance`
- * field on a `stories.json` entry says **which of them that Story owns**:
- *
- * ```jsonc
- * { "fingerprints": ["<40-char sha1>"], "semanticKeys": ["architecture␟lib/a.js"] }
- * ```
- *
- * Two callers, deliberately split from
- * [`route-finding.js`](route-finding.js): the ticket validator shape-checks
- * the authored field, and plan-persist's assembly renders the owned identities
- * into the footer source it stamps. Neither is dedup *routing*, which is what
- * `route-finding.js` is for — this module reads its identity vocabulary
- * (`SHA1_RE`, `SEMANTIC_KEY_RE`, and the two footer renderers) from there so
- * there is exactly one definition of what a fingerprint or a semantic key
- * looks like.
+ * lib/findings/provenance-field.js — the optional per-Story `provenance`
+ * field naming the audit identities that Story owns.
  *
  * @module lib/findings/provenance-field
  */
@@ -28,10 +12,8 @@ import {
   semanticKeyFooter,
 } from './route-finding.js';
 
-/** Human-readable rendering of the `provenance` field's two lists. */
 const PROVENANCE_SHAPE = 'fingerprints[] / semanticKeys[]';
 
-/** What each `provenance` list accepts, and how to say so when it does not. */
 const PROVENANCE_FIELDS = Object.freeze({
   fingerprints: { pattern: SHA1_RE, expected: 'a 40-char sha1 hex string' },
   semanticKeys: {
@@ -41,8 +23,6 @@ const PROVENANCE_FIELDS = Object.freeze({
 });
 
 /**
- * Validate one authored `provenance` list into its normalized form.
- *
  * @param {unknown} list
  * @param {{ where: string, field: string, pattern: RegExp, expected: string }} spec
  * @returns {string[]} Trimmed, de-duplicated, first-seen order.
@@ -66,25 +46,13 @@ function normalizeList(list, { where, field, pattern, expected }) {
 }
 
 /**
- * Normalize the optional per-Story `provenance` field a plan may author —
- * the identities of the findings **that Story owns**.
- *
- * Absence is meaningful and must stay cheap: `undefined` / `null` returns
- * `null`, which is the caller's signal to fall back to the whole-seed union
- * carry. That fallback is not vestigial — leaving the authoring agent to
- * hand-carry provenance out of the seed's HTML comments was measured to fail,
- * and the mechanical union is what closed it. Attribution is **additive**: a
- * plan that attributes gets exact stamping, a plan that does not keeps recall.
- *
- * An empty object is therefore *not* the same as an absent field: it means
- * "this Story owns nothing", and stamps nothing.
- *
- * Present-but-malformed is a hard error rather than a silent drop, because a
- * dropped identity is invisible until the next sweep re-files work that was
- * already planned.
+ * Absent → `null`: the caller falls back to carrying the whole seed's union
+ * (hand-carrying was measured to fail). An empty object means "owns nothing"
+ * and stamps nothing. Malformed throws — a dropped identity is invisible until
+ * the next sweep re-files planned work.
  *
  * @param {unknown} raw
- * @param {string} [label] Identifier for the error message (a Story slug).
+ * @param {string} [label]
  * @returns {{ fingerprints: string[], semanticKeys: string[] }|null}
  * @throws {Error} On any shape the stamper cannot honour exactly.
  */
@@ -108,19 +76,10 @@ export function normalizeOwnedProvenance(raw, label = 'story') {
 }
 
 /**
- * Render the provenance **source document** for a set of owned identities, in
- * the same footer vocabulary `carryProvenanceFooters` harvests from an audit
- * seed. That reuse is the point: attribution changes *which* identities reach
- * a Story body, never how they are stamped, so the carry stays additive,
- * union-preserving and idempotent for an attributed plan exactly as it is for
- * an un-attributed one.
- *
- * An empty (or absent) set renders the empty string, which the carry treats as
- * nothing-to-do — so a Story that owns no findings is stamped with none rather
- * than inheriting its siblings'.
- *
- * Expects the normalized shape {@link normalizeOwnedProvenance} returns; the
- * validator runs first on every production path.
+ * Render owned identities in the same footer vocabulary
+ * `carryProvenanceFooters` harvests, so attribution changes which identities
+ * are stamped, never how. An empty set renders `''` (nothing inherited from
+ * siblings). Expects {@link normalizeOwnedProvenance}'s shape.
  *
  * @param {{ fingerprints?: string[], semanticKeys?: string[] }|null} [provenance]
  * @returns {string}

package/.agents/scripts/lib/findings/route-finding.js

@@ -1,32 +1,6 @@
 /**
- * lib/findings/route-finding.js — Shared dedup/route helper for findings.
- *
- * This module is the single dedup/route implementation that both
- * `audit-to-stories` and `qa-explore` consume. It does three things:
- *
- *   1. `fingerprintFinding(finding)` — a stable sha1 over the finding's
- *      identity fields (`title`, `area`, `primaryFile`, `severity`,
- *      `labels`). Two runs over the same finding MUST produce the same
- *      sha, and unrelated prose drift MUST NOT change it.
- *   2. `fingerprintFooter(sha)` / `parseFingerprintFooter(body)` — round-trip
- *      the machine-readable `<!-- audit-fingerprints: sha,sha,... -->` marker
- *      stamped into Issue bodies.
- *   3. `routeFinding(finding, { searchIssues, searchCandidates })` — classify a
- *      finding against existing Issues into one of `new | update-existing |
- *      duplicate | regression-of-closed`. Routing gathers a candidate pool,
- *      then confirms identity against it. **Every wired port runs, and their
- *      results union** (Story #5079): the exact `searchIssues(sha)` lookup is
- *      what reliably retrieves an Issue by its footer sha, while the
- *      meaning-first `searchCandidates` pass (wired to
- *      `semantic-issue-search.js`) widens that pool to catch a reworded
- *      finding whose sha has drifted. The semantic pass **adds** to the
- *      fingerprint lookup; it never replaces it. Whichever ports are wired
- *      query BOTH open and closed issues; a closed fingerprint match yields
- *      `regression-of-closed`.
- *
- * Pure orchestration: no network I/O lives here. The `searchIssues` /
- * `searchCandidates` ports are injected by the caller (production wires them
- * to the GitHub provider; tests pass an in-memory stub).
+ * lib/findings/route-finding.js — the one dedup/route implementation: finding
+ * fingerprints, Issue-body footers, and `routeFinding`. Ports are injected.
  */
 
 import crypto from 'node:crypto';
@@ -38,13 +12,10 @@ const MARKER = 'audit-fingerprints:';
 const SEMANTIC_MARKER = 'audit-semantic-keys:';
 const LABEL_MARKER = 'audit-labels:';
 export const SHA1_RE = /^[0-9a-f]{40}$/;
-// A semantic key round-trips through a comma-joined footer, so it must not
-// carry a comma or a `>` (which would truncate the HTML comment). Both are
-// stripped when the key is built, so this guard is defence-in-depth.
+// No `,` or `>`: keys round-trip through a comma-joined HTML-comment footer.
 export const SEMANTIC_KEY_RE = /^[^,>]+$/;
 
 /**
- * Normalise a single scalar identity field to a stable string.
  * @param {unknown} value
  * @returns {string}
  */
@@ -54,7 +25,6 @@ function normaliseField(value) {
 }
 
 /**
- * Normalise the `labels` array into a stable, order-independent string.
  * @param {unknown} labels
  * @returns {string}
  */
@@ -68,20 +38,8 @@ function normaliseLabels(labels) {
 }
 
 /**
- * Compute the stable identity payload for a finding.
- *
- * **Severity is projected, not raw (Story #4877).** The severity vocabulary was
- * normalised onto the canonical five-level scale in the same change that wrote
- * this comment, and severity is an identity field — so a naive
- * `normaliseField(finding.severity)` here would have re-minted the fingerprint
- * of every finding whose spelling the normalisation touched, silently breaking
- * dedup against every Issue already filed. {@link fingerprintSeverity} is the
- * projection that makes the hash **invariant** under that normalisation: it
- * resolves aliases onto their canonical level, keeps an absent severity as the
- * empty string (what the raw call produced), and passes an unrecognised value
- * through verbatim. Labels are deliberately left on the raw
- * lower-case/trim/sort path for the same reason — order- and case-insensitive
- * already, and any further folding would move existing shas.
+ * Any change to this folding moves existing shas and breaks dedup against
+ * filed Issues.
  *
  * @param {object} finding
  * @returns {{ title: string, area: string, primaryFile: string, severity: string, labels: string }}
@@ -97,8 +55,6 @@ function fingerprintComponents(finding) {
 }
 
 /**
- * Stable per-finding fingerprint over {title, area, primaryFile, severity, labels}.
- *
  * @param {object} finding
  * @returns {{ short: string, full: string, components: object }}
  */
@@ -116,20 +72,10 @@ export function fingerprintFinding(finding) {
 }
 
 /**
- * Compute the **location-based semantic key** for a finding. Unlike the
- * fingerprint (which folds in the title, so any prose rewording mints a fresh
- * sha), the semantic key is stable across a reworded title and a re-severitied
- * finding: it is derived solely from the finding's identity *location* —
- * `area` (the audit dimension) plus `primaryFile`. Two scans that describe the
- * same problem at the same location produce the same semantic key even when
- * their titles diverge, so a reworded finding still confirms against the Issue
- * that already tracks that location.
+ * Location key (`area` + `primaryFile`), stable across rewording. Empty when
+ * the location is unknown; an empty key never confirms a match.
  *
- * Returns the empty string when the location is unknown (no `area` and no
- * `primaryFile`) — an empty key never confirms a match, exactly as an absent
- * fingerprint footer never does.
- *
- * @param {object} finding — canonical finding ({ area, primaryFile, ... }).
+ * @param {object} finding
  * @returns {string}
  */
 export function semanticKeyFor(finding) {
@@ -141,13 +87,7 @@ export function semanticKeyFor(finding) {
 }
 
 /**
- * Render the machine-readable semantic-key footer for one or more keys
- * (`<!-- audit-semantic-keys: key,key,... -->`). Stamped alongside the
- * fingerprint footer by the audit filers so a later reworded finding can
- * confirm identity by location when its fingerprint has drifted. Round-trips
- * through {@link parseSemanticKeyFooter}. Empty keys are dropped.
- *
- * @param {string | string[]} keys — one semantic key or an array of them.
+ * @param {string | string[]} keys
  * @returns {string}
  */
 export function semanticKeyFooter(keys) {
@@ -159,12 +99,6 @@ export function semanticKeyFooter(keys) {
 }
 
 /**
- * Extract semantic keys from an Issue body carrying the semantic-key footer.
- * The audit filers stamp the footer via {@link semanticKeyFooter}; the
- * confirmation path here, {@link carryProvenanceFooters} and the audit dedup's
- * local issue index read it back. Exported alongside its writer so an indexer
- * cannot drift into a second parse of the same footer.
- *
  * @param {string} body
  * @returns {string[]}
  */
@@ -177,15 +111,8 @@ export function parseSemanticKeyFooter(body) {
 }
 
 /**
- * Render the machine-readable audit-label footer
- * (`<!-- audit-labels: audit::x,audit::y -->`).
- *
- * The dedup corpus is listed by `audit::*` label, so a Story carrying none 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 planning path stamp them without the authoring agent
- * being asked to notice them (Story #5307).
+ * The dedup corpus is listed by `audit::*` label; this footer lets planning
+ * stamp them so the Story stays visible to indexed dedup.
  *
  * @param {string | string[]} labels
  * @returns {string}
@@ -200,8 +127,6 @@ export function auditLabelFooter(labels) {
 }
 
 /**
- * Read every `audit-labels` footer out of a body, de-duplicated.
- *
  * @param {string} body
  * @returns {string[]}
  */
@@ -214,16 +139,7 @@ export function parseAuditLabelFooter(body) {
 }
 
 /**
- * Render the machine-readable fingerprint footer for one or more shas.
- *
- * Accepts either a single 40-char sha1 or an array of them, so a footer
- * can carry every finding sha that a grouped Issue tracks
- * (`<!-- audit-fingerprints: sha,sha,... -->`). The comma-joined form
- * round-trips through {@link parseFingerprintFooter}. This is the single
- * footer renderer shared by `audit-to-stories` and `qa-explore`; neither
- * consumer defines its own marker.
- *
- * @param {string | string[]} shas — full 40-char sha1, or an array of them.
+ * @param {string | string[]} shas
  * @returns {string}
  */
 export function fingerprintFooter(shas) {
@@ -239,8 +155,6 @@ export function fingerprintFooter(shas) {
 }
 
 /**
- * Extract fingerprint sha1s from an Issue body carrying the footer marker.
- *
  * @param {string} body
  * @returns {string[]}
  */
@@ -253,20 +167,11 @@ export function parseFingerprintFooter(body) {
 }
 
 /**
- * Collect the comma-separated values out of **every** occurrence of a footer
- * marker in `text`, de-duplicated, in first-seen order.
- *
- * Scanning every occurrence rather than only the first matters for the
- * provenance carry (Story #4877): the audit Single-plan seed stamps one footer
- * pair per MVP Scope bullet, so a multi-group seed carries several. A
- * first-match-only parse silently dropped every group but the first, which
- * would have made the carry look wired while leaking most of the provenance.
- * Reading all footers is also strictly more correct for issue-body confirmation
- * — a body that accumulated two footer lines confirms against either.
+ * Values from every occurrence of a footer (a multi-group seed carries
+ * several), de-duplicated.
  *
  * @param {unknown} text
- * @param {RegExp} pattern — a global regex whose first capture group is the
- *   comma-separated value list.
+ * @param {RegExp} pattern — global; capture group 1 is the value list.
  * @param {(value: string) => boolean} isValid
  * @returns {string[]}
  */
@@ -286,34 +191,12 @@ function parseAllFooterValues(text, pattern, isValid) {
 }
 
 /**
- * Carry audit dedup provenance from a source document into a target body
- * (Story #4877).
- *
- * The audit sweep's Single-plan path emits a `/mandrel-plan` seed whose MVP Scope
- * bullets already carry the `audit-fingerprints` / `audit-semantic-keys`
- * footers (Story #4626). Nothing then copied them into the Story `/mandrel-plan`
- * actually persisted, so the recommended path filed Stories that the next
- * sweep could not recognise and re-filed as new. It was left to the authoring
- * agent to notice HTML comments in a one-pager and hand-carry them — a
- * remembered step, which is to say no step at all.
- *
- * This is that carry, as a function: harvest both footers out of `from`, and
- * append whichever provenance `into` is missing. It is deliberately:
+ * Append the seed's provenance footers missing from `into`, so the next
+ * sweep recognises the Story. Additive and idempotent.
  *
- * - **Additive.** Shas and keys already present in `into` are never duplicated,
- *   and a footer `into` already carries is left exactly as authored.
- * - **Union-preserving.** When both sides carry footers the result carries the
- *   union, so a hand-authored fingerprint is not dropped in favour of the seed's.
- * - **Idempotent.** Re-running over its own output is a no-op, so a resumed
- *   persist cannot stack footers.
- * - **Silent on nothing-to-do.** No provenance in `from` returns `into`
- *   unchanged with `carried: false`, so a non-audit plan run is untouched.
- *
- * @param {{ from?: string, into?: string }} args — `from` is the provenance
- *   source (the seed markdown); `into` is the body being persisted.
+ * @param {{ from?: string, into?: string }} args
  * @returns {{ body: string, carried: boolean, fingerprints: string[], semanticKeys: string[] }}
- *   `body` is the augmented text; `fingerprints` / `semanticKeys` are the values
- *   newly carried (empty when there was nothing to carry).
+ *   The arrays hold only newly carried values.
  */
 export function carryProvenanceFooters({ from = '', into = '' } = {}) {
   const body = typeof into === 'string' ? into : '';
@@ -346,9 +229,8 @@ export function carryProvenanceFooters({ from = '', into = '' } = {}) {
 }
 
 /**
- * Confirm an issue body's footer actually carries the target sha. Guards
- * against a false-positive search hit (e.g. a body that mentions the sha in
- * prose rather than in the fingerprint footer).
+ * Rejects a hit that mentions the sha only in prose; a body-less issue is
+ * trusted.
  *
  * @param {{ body?: string }} issue
  * @param {string} sha
@@ -360,10 +242,7 @@ function issueCarriesFingerprint(issue, sha) {
 }
 
 /**
- * Confirm an issue body's footer carries the target semantic key. Unlike
- * {@link issueCarriesFingerprint}, this is strict on a missing body — a
- * location match is only meaningful when the issue actually carries a
- * semantic-key footer to compare against.
+ * Strict on a missing body: a location match needs a footer to compare.
  *
  * @param {{ body?: string }} issue
  * @param {string} key
@@ -375,7 +254,6 @@ function issueCarriesSemanticKey(issue, key) {
 }
 
 /**
- * Decide the route decision from a confirmed matched issue's state.
  * @param {{ state?: string }} issue
  * @returns {'update-existing'|'regression-of-closed'}
  */
@@ -385,23 +263,8 @@ function decisionForIssue(issue) {
 }
 
 /**
- * Resolve the pool that **attributes** a finding, out of everything that
- * confirmed it (Story #5045).
- *
- * Confirmation admits two different strengths of claim, and collapsing them
- * was the source of two wrong routes:
- *
- * - An issue carrying the finding's exact **fingerprint** owns it. That is
- *   identity: this issue tracks *this* finding.
- * - An issue matching only on the location-based **semantic key** is merely
- *   adjacent: it tracks *a* finding at the same `area␟primaryFile`.
- *
- * Owners win outright when any exist. Location-only matches are not discarded
- * — they are the whole point of the semantic key and remain the pool when
- * nothing carries the fingerprint (a reworded finding at an unchanged
- * location). The pool is sorted by issue number so a genuine tie resolves to
- * the earliest-filed issue rather than to whatever order the search port
- * happened to return.
+ * Fingerprint owners win outright over location-only neighbours. Sorted so a
+ * tie resolves to the earliest-filed issue, not search order.
  *
  * @param {Array<{ number: number, state: string, body?: string }>} confirmed
  * @param {string} sha
@@ -415,28 +278,8 @@ function attributedPool(confirmed, sha) {
 }
 
 /**
- * Decide the final route from a confirmed-match pool (issues that both
- * surfaced in the candidate/search pass AND carry a confirming footer).
- * Shared by both the semantic-first and fingerprint-only code paths so the
- * decision enum is identical regardless of how candidates were gathered.
- *
- * **Attribution decides, not array order (Story #5045).** The pool used to be
- * read flat, which produced two wrong answers whenever more than one issue
- * confirmed:
- *
- *   1. Two open matches routed `duplicate` pinned to `open[0]` — whichever
- *    issue the search port happened to return first. With per-Story
- *    provenance that pick is answerable rather than arbitrary: the issue
- *    carrying the finding's own fingerprint owns it, and a sibling matching
- *    only by location does not.
- *   2. Any open match at all masked a closed one, so a finding whose
- *    fingerprint is owned by a **closed** Story routed `update-existing`
- *    against an open neighbour — a genuine regression filed as a
- *    business-as-usual update. Attribution restores it: state is read off the
- *    owning issue, not off whatever else shares its location.
- *
- * {@link attributedPool} owns that selection; the decision below reads only
- * the pool it returns.
+ * State is read off the attributed issue, so an open neighbour cannot mask a
+ * regression of the closed owner.
  *
  * @param {Array<{ number: number, state: string }>} confirmed
  * @param {string} sha
@@ -469,15 +312,8 @@ function decideFromConfirmed(confirmed, sha) {
 }
 
 /**
- * Keep only the issue records that have the right wire shape AND carry a
- * confirming footer. Confirmation is by the exact **fingerprint** footer and,
- * when a `semanticKey` is supplied (audit dedup opts in via
- * `options.semanticKeyConfirm`), ALSO by the location-based **semantic-key**
- * footer. A semantic candidate that merely *looks* similar but carries neither
- * footer is dropped here — semantic similarity widens the net; a deterministic
- * footer (fingerprint or semantic key) is what confirms identity. The semantic
- * key catches a reworded finding whose fingerprint has drifted but whose
- * location is unchanged.
+ * Only a deterministic footer (fingerprint, or semantic key when supplied)
+ * confirms identity.
  *
  * @param {Array<unknown>} hits
  * @param {{ sha: string, semanticKey?: string }} identity
@@ -496,13 +332,7 @@ function confirmCandidates(hits, { sha, semanticKey = '' }) {
 }
 
 /**
- * Union candidate pools into one flat pool, keeping first-seen order and
- * dropping an issue number an earlier pool already contributed.
- *
- * The fingerprint pool is passed first, so when both ports return the same
- * Issue it is that pool's record — the one retrieved by exact identity — that
- * survives into confirmation. Records without a usable number are left for
- * {@link confirmCandidates} to reject, exactly as a single port's would be.
+ * First-seen wins, so the fingerprint pool's record survives a tie.
  *
  * @param {Array<unknown>} pools
  * @returns {Array<object>}
@@ -519,18 +349,10 @@ function unionCandidatePools(pools) {
 }
 
 /**
- * Gather the candidate pool for a finding from every wired port.
- *
- * A run with a single wired port returns that port's result **verbatim**, so
- * the fingerprint-only wiring (`qa-explore`, and every caller that injects no
- * semantic port) keeps its behaviour exactly — including how a non-array
- * return is handled downstream by {@link confirmCandidates}.
- *
- * Both ports are awaited together; a rejection from either propagates rather
- * than degrading silently to a partial pool.
+ * A single port's result is returned verbatim; a rejection propagates.
  *
  * @param {object} finding
- * @param {string} sha — the finding's full fingerprint.
+ * @param {string} sha
  * @param {{ searchIssues?: Function, searchCandidates?: Function }} ports
  * @returns {Promise<Array<object>|unknown>}
  */
@@ -544,55 +366,18 @@ async function gatherCandidates(finding, sha, ports) {
 }
 
 /**
- * Route a finding against existing Issues: gather candidates, then confirm.
- *
- * **Gather — every wired port runs, and their pools union (Story #5079).** The
- * two ports answer different questions and neither subsumes the other:
- *
- * - `searchIssues(sha)` is the **exact** lookup. A fingerprint sha is one
- *   high-signal term, so it retrieves the Issue whose footer carries it.
- * - `searchCandidates(finding)` is the **meaning-first** pass. It widens the
- *   pool to Issues describing the same problem under a different title, so a
- *   reworded finding or a moved file still confirms by semantic key.
- *
- * This was a ternary until Story #5079: an injected semantic port *replaced*
- * the fingerprint lookup instead of widening it. Production always injects
- * one, so `searchIssues` was dead code on the live path and dedup rested
- * entirely on a ~20-token bag-of-words query that does not reliably retrieve
- * the Issue. The audit loop consequently re-filed Stories it had already
- * filed, against the workflow's "Never open a duplicate Issue" constraint.
- * Running both ports and unioning their pools is what closes that loop.
- *
- * A port that rejects **propagates**. A pool gathered from only some of its
- * sources is not a smaller pool, it is an unknown one, so the caller
- * (`classifyGroupsAgainstGitHub`) must record a degraded lookup rather than
- * report a confident `new`.
- *
- * **Confirm.** The pooled candidates are filtered down to those that actually
- * carry the finding's fingerprint footer — or, when `semanticKeyConfirm` is
- * on, its location-based semantic-key footer — then resolved:
- *   - An open match → `update-existing` (or `duplicate` when more than one
- *     open issue carries the fingerprint).
- *   - A closed match (no open match) → `regression-of-closed`.
- *   - No confirmed match → `new`.
- *
- * The decision enum is identical however the candidates were gathered.
+ * Route a finding against existing Issues. Every wired port runs and pools
+ * union: the semantic search must widen, never replace, the exact sha lookup
+ * (a bag-of-words query alone re-files duplicates). A rejecting port
+ * propagates — a partial pool is unknown, not a confident `new`.
  *
  * @param {object} finding
  * @param {object} ports
  * @param {(sha: string) => Promise<Array<{ number: number, state: string, body?: string }>>} [ports.searchIssues]
- *   Fingerprint-keyed lookup over open+closed issues. Runs whenever it is
- *   supplied. Required when `searchCandidates` is not.
  * @param {(finding: object) => Promise<Array<{ number: number, state: string, title?: string, body?: string }>>} [ports.searchCandidates]
- *   Meaning-first candidate search over open+closed issues (and Epic
- *   sub-issues). Runs whenever it is supplied, alongside `searchIssues` rather
- *   than instead of it; the union is then confirmed by footer.
  * @param {object} [options]
- * @param {boolean} [options.semanticKeyConfirm=false] — also confirm a
- *   candidate by the location-based semantic-key footer, not the fingerprint
- *   alone. Opt-in so the audit dedup path catches a reworded finding at an
- *   unchanged location while the qa-explore path (which does not stamp
- *   semantic-key footers) stays fingerprint-exact and byte-identical.
+ * @param {boolean} [options.semanticKeyConfirm=false] — opt-in; qa-explore
+ *   stamps no semantic keys.
  * @returns {Promise<{ decision: 'new'|'update-existing'|'duplicate'|'regression-of-closed', matchedIssue: object|null, fingerprint: string }>}
  */
 export async function routeFinding(
@@ -612,14 +397,11 @@ export async function routeFinding(
   const { full: sha } = fingerprintFinding(finding);
   const semanticKey = options.semanticKeyConfirm ? semanticKeyFor(finding) : '';
 
-  // Gather: every wired port runs, and their pools union (Story #5079).
   const hits = await gatherCandidates(finding, sha, {
     searchIssues,
     searchCandidates,
   });
 
-  // Confirm identity by fingerprint footer (and, when opted in, the
-  // location-based semantic-key footer) over the pooled candidates.
   const confirmed = confirmCandidates(hits, { sha, semanticKey });
 
   return decideFromConfirmed(confirmed, sha);