@blamejs/exceptd-skills 0.19.32 → 0.19.34

package/lib/collectors/citation-hygiene.js

@@ -1,30 +1,9 @@
 "use strict";
 
 /**
- * lib/collectors/citation-hygiene.js
- *
- * Companion collector for the `citation-hygiene` playbook. Walks the cwd
- * tree (source, comments, docstrings, and security documentation) and
- * extracts every CVE and RFC citation, then cross-references each against
- * the shipped CVE catalog (data/cve-catalog.json) and RFC index
- * (data/rfc-references.json).
- *
- * It flips signal_overrides only for verdicts determinable offline from
- * the catalogs:
- *   - fabricated-cve-id: a citation whose tail is not the canonical
- *     all-numeric CVE form (CVE-2024-XXXX, CVE-2024-zlib). Deterministic.
- *   - rejected-or-disputed-cve: a well-formed citation that resolves to a
- *     catalog entry whose analyst notes mark it rejected / disputed.
- *   - rfc-number-title-mismatch: a citation pairing a number with a title
- *     that conflicts with the index title for that number.
- *
- * Indicators that need an out-of-band lookup or human judgement
- * (cve-citation-needs-external-verification, draft-mislabeled-as-rfc) are
- * surfaced in the artifacts text and left UNFLIPPED so the runner returns
- * inconclusive rather than a forced miss — the catalog is curated, not
- * exhaustive, so absence is never a clean clear or a false fabrication.
- *
- * Interface: see lib/collectors/README.md
+ * Companion collector for the `citation-hygiene` playbook: cross-references CVE
+ * and RFC citations in the cwd tree against data/cve-catalog.json and
+ * data/rfc-references.json. Interface: see lib/collectors/README.md
  */
 
 const fs = require("node:fs");
@@ -34,10 +13,7 @@ const { codeExcludeSet, walkTree, buildEvidenceLocations, lineFromOffset } = req
 
 const COLLECTOR_ID = "citation-hygiene";
 
-// Opt-in resolver (`exceptd collect citation-hygiene --resolve`). Lets the
-// collector resolve the citations the offline catalog can't confirm — once,
-// through the shared cache — instead of parking them as inconclusive for an
-// agent to research. Required lazily so a plain collect() never loads it.
+// Required lazily so a plain collect() never loads the resolver.
 function loadResolver() {
   return require("../citation-resolve.js");
 }
@@ -45,9 +21,7 @@ function loadResolver() {
 const DEFAULT_MAX_DEPTH = 8;
 const EXCLUDES = codeExcludeSet();
 
-// File extensions whose contents are worth scanning for citations: source,
-// markup/docs, config that carries security prose. Citations live in
-// comments and docstrings (source) and in docs (md / rst / txt / adoc).
+// Citations live in source comments, and in docs and config prose.
 const SCAN_EXTS = new Set([
   ".js", ".mjs", ".cjs", ".jsx", ".ts", ".tsx", ".mts", ".cts",
   ".py", ".pyi",
@@ -66,16 +40,13 @@ const SCAN_EXTS = new Set([
 
 const MAX_FILE_BYTES = 2 * 1024 * 1024;
 
-// Paths whose citations are illustrative (templates / fixtures / the
-// scanner's own pattern catalogue), not real self-citations.
+// Paths whose citations are illustrative, not real self-citations.
 const ILLUSTRATIVE_PATH_SEGMENTS = [
   "/test/", "/tests/", "/spec/", "/specs/", "/__tests__/",
   "/fixtures/", "/fixture/",
   "/.github/issue_template/", "/.github/pull_request_template/",
   "/issue_template/", "/pull_request_template/",
-  // The collectors and the playbooks directory literally contain CVE /
-  // RFC patterns and example citations; scanning them would flag the
-  // scanner itself. The playbook's intent is the consumer's source.
+  // These directories hold the patterns themselves; scanning them flags the scanner.
   "/lib/collectors/", "/data/playbooks/", "/lib/schemas/",
 ];
 
@@ -91,60 +62,37 @@ function isIllustrativePath(rel) {
 
 function readSafe(full) {
   try {
-    // Read raw bytes, enforce the 2 MB cap on the buffer length, then decode.
-    // Replaces a statSync-before-read with a single read; the cap is
-    // byte-based, so Buffer.length is the correct measure and an oversized
-    // file is rejected before any UTF-8 decode.
+    // The cap is byte-based: enforced on the buffer, before any UTF-8 decode.
     const raw = fs.readFileSync(full);
     if (raw.length > MAX_FILE_BYTES) return null;
     return raw.toString("utf8");
   } catch { return null; }
 }
 
-// Permissive CVE matcher: 4-digit year, then a tail of digits OR letters
-// (so malformed citations like CVE-2024-XXXX / CVE-2024-zlib are captured,
-// not silently skipped). The canonical-form test is applied afterwards.
+// Permissive: a letter tail is captured, not skipped, so the canonical-form test
+// below can flag it.
 const CVE_CITATION_RE = /CVE-(\d{4})-([0-9A-Za-z]+)/g;
 const CVE_CANONICAL_RE = /^CVE-\d{4}-\d{4,}$/;
 
-// RFC citation: `RFC 9404`, `RFC9404`, `RFC-9404`. Capture the number.
 const RFC_CITATION_RE = /RFC[\s-]?(\d{1,5})\b/gi;
 
-// A catalog note records a rejected/disputed RECORD for THIS CVE only when a
-// reject/dispute/withdraw word refers to the citation's own record — not to a
-// CVSS *scoring* disagreement, a disclosure-coordination dispute, or a
-// DIFFERENT CVE the note merely mentions. A bare word-anywhere scan matched all
-// three, producing a false "citation to a rejected record" hit AND a false
-// __fp_checks[1] attestation (telling the runner not to downgrade), so a valid,
-// often actively-exploited CVE surfaced as a confirmed rejected/disputed
-// citation. `selfId` is the citation's own CVE id.
+// True only when a reject/dispute/withdraw word refers to THIS citation's own
+// record — not a CVSS disagreement, a coordination dispute, or another CVE the
+// note mentions. `selfId` is the citation's own CVE id.
 function recordRejectedOrDisputed(note, selfId) {
   if (!note) return false;
   const self = String(selfId || "").toUpperCase();
   const re = /\b(reject(?:ed|s|ion)?|disputed?|withdrawn)\b/gi;
-  // Qualifier nouns that make a "dispute" a disagreement about something OTHER
-  // than the record's validity (the score, the severity, the disclosure
-  // process, …). 'rejected'/'withdrawn' are record-level words and bypass this.
+  // Qualifier nouns that make a "dispute" a disagreement about something other
+  // than the record's validity; 'rejected' / 'withdrawn' bypass this.
   const QUALIFIER = /\b(cvss|scoring|score|severity|coordination|disclosure|methodolog\w*|attribution|naming|assignment|priorit\w*)\b/i;
-  // A "duplicate of / superseded by / replaced by / merged into / in favour of"
-  // construction names the REPLACEMENT cve — THIS record is still the rejected
-  // one, so a different cve appearing as that replacement must NOT suppress the
-  // flag (e.g. "this record was rejected as a duplicate of CVE-Y").
+  // A "duplicate of / superseded by / in favour of" construction names the
+  // REPLACEMENT cve, so that other id must not suppress the flag.
   const REPLACEMENT_OF = /\b(?:duplicate|dup)\b[\s\w-]*\bof\b|\b(?:supersed\w+|replaced|merged)\b[\s\w-]*\b(?:by|into)\b|\bin\s+favou?r\s+of\b/i;
-  // "Reject" is also an ordinary verb for what code does to input, and a vector
-  // description is full of it: a parser rejects an invalid DTD, a validator
-  // rejects a traversal sequence. Nothing about the CVE record is being claimed
-  // there. The record sense always names what was rejected — a record, an
-  // entry, an identifier — or who rejected it (MITRE, NVD, the CNA), so require
-  // one of those nearby before treating a reject-word as record-level. The
-  // alternative is rewording accurate mechanism prose to dodge a regex, which
-  // costs the catalog more than the false positive does.
-  // Deliberately excludes bare "entry" and "advisory". Both are ordinary words
-  // in mechanism prose — "rejection log entry", "cache entry", "registry entry" —
-  // and including them let an Exim entry describing SMTP message rejection read
-  // as a claim that the CVE record itself was rejected. The surviving tokens all
-  // name the record or the body that maintains it, so they cannot be satisfied
-  // by a sentence about software rejecting input.
+  // "Reject" is also the ordinary verb for what code does to input, so the record
+  // sense must name what was rejected or who rejected it. Bare "entry" and
+  // "advisory" stay out: they are ordinary words in mechanism prose, and admitting
+  // them reads SMTP message rejection as a rejected CVE record.
   const RECORD_CONTEXT = /\b(CVE record|catalog(?:ue)? entry|record status|identifier|assignment|CVE|MITRE|NVD|CNA)\b/i;
   const otherCve = (s) => (s.match(/CVE-\d{4}-\d{4,}/gi) || []).some((c) => c.toUpperCase() !== self);
   let m;
@@ -152,21 +100,16 @@ function recordRejectedOrDisputed(note, selfId) {
     const word = m[1].toLowerCase();
     const before = note.slice(Math.max(0, m.index - 60), m.index);
     const after = note.slice(re.lastIndex, re.lastIndex + 60);
-    // (a) A different cve BEFORE the word is the subject ("CVE-Y was rejected")
-    //     — the status is about that record, not this citation.
+    // A different cve BEFORE the word is the subject: that record's status.
     if (otherCve(before)) continue;
-    // (b) A different cve AFTER the word suppresses too, UNLESS it is the
-    //     replacement target of a duplicate-of/superseded-by construction, in
-    //     which case THIS record is the rejected one — keep it flagged.
+    // A cve AFTER suppresses too, unless it is a duplicate-of replacement target.
     if (otherCve(after) && !REPLACEMENT_OF.test(after)) continue;
-    // (c) A 'dispute(d)' qualified by a non-record noun is a disagreement about
-    //     that noun, not a record rejection.
+    // A 'dispute' qualified by a non-record noun is about that noun.
     if (word.startsWith("disput")) {
       const lastTokens = before.trim().split(/[\s-]+/).slice(-3).join(" ");
       if (QUALIFIER.test(lastTokens)) continue;
     }
-    // (d) A 'reject' with nothing record-shaped around it is the ordinary verb
-    //     — code rejecting input — not a statement about this CVE's record.
+    // A 'reject' with nothing record-shaped around it is the ordinary verb.
     if (word.startsWith("reject") && !RECORD_CONTEXT.test(before + " " + after)) continue;
     return true;
   }
@@ -177,10 +120,9 @@ function recordRejectedOrDisputed(note, selfId) {
 const DRAFT_LANGUAGE_RE = /\b(draft-[a-z0-9-]+|internet[- ]draft|work[- ]in[- ]progress|i-d\b)\b/i;
 
 /**
- * Load the shipped CVE catalog and RFC index. The catalogs ship in the
- * package tarball under data/; resolve relative to this module so the
- * collector works whether run from the source tree or a node_modules
- * install. Returns { cveKeys:Set, cveNotes:Map<id,string>, rfcTitles:Map<number,string>, errors:[] }.
+ * Load the shipped CVE catalog and RFC index, resolved relative to this module so
+ * the collector works from a source tree or a node_modules install. Returns
+ * { cveKeys:Set, cveNotes:Map<id,string>, rfcTitles:Map<number,string>, errors:[] }.
  */
 function loadCatalogs() {
   const errors = [];
@@ -195,9 +137,8 @@ function loadCatalogs() {
       if (k.startsWith("_")) continue;
       cveKeys.add(k);
       if (v && typeof v === "object") {
-        // Concatenate the analyst-note fields that carry rejected /
-        // disputed status. Matching the cited key's OWN notes (not a
-        // neighbour's) is enforced by per-entry concatenation.
+        // Analyst-note fields carrying rejected / disputed status, concatenated
+        // per entry so a citation matches its own notes and never a neighbour's.
         const noteParts = [
           v.cvss_note, v.active_exploitation_notes, v.vector,
           v.discovery_attribution_note, v.ai_discovery_notes,
@@ -225,8 +166,6 @@ function loadCatalogs() {
   return { cveKeys, cveNotes, rfcTitles, errors };
 }
 
-// Normalise a title for comparison: lowercase, drop punctuation, collapse
-// whitespace, and strip a leading "the".
 function normalizeTitle(s) {
   return s
     .toLowerCase()
@@ -247,42 +186,24 @@ function titleTokens(s) {
   );
 }
 
-// Ordered list of meaningful (post-stopword, non-numeric) tokens in a
-// title — used both for overlap and for acronym construction.
 function orderedTitleTokens(s) {
   return normalizeTitle(s)
     .split(" ")
     .filter((t) => t.length >= 3 && !/^\d+$/.test(t) && !TITLE_STOPWORDS.has(t));
 }
 
-// Build the lowercase acronym from the title's meaningful words
-// (Transport Layer Security Protocol -> "tls", since protocol/version are
-// stopwords). Lets a nickname / abbreviation in the adjacent text be
-// recognised as the same document, not a wrong title.
+// Lowercase acronym from the title's meaningful words: "Transport Layer Security
+// Protocol" gives "tls". Lets a nickname be recognised as the same document.
 function titleAcronym(realTitle) {
   return orderedTitleTokens(realTitle).map((w) => w[0]).join("");
 }
 
 /**
- * Decide whether an EXPLICITLY STATED title conflicts with the real index
- * title. The stated title is extracted by the caller (see statedTitleAfter):
- * only a title introduced immediately after the RFC number by a delimiter —
- * `RFC N: The Title`, `RFC N "The Title"`, `RFC N (The Title)` — counts.
- *
- * This is deliberately strict because the dominant real-world pattern is a
- * mechanism citation — "CRLF line endings per RFC 5322", "renders values per
- * RFC 8785", "ETag repeated per RFC 7232 §4.1" — where the prose describes
- * what the code does *per* the RFC using vocabulary that never overlaps the
- * RFC's formal title. Comparing that prose against the title produced a
- * false "mismatch" on correct citations. Such references state no title and
- * are filtered out before this function is reached.
- *
- *   - at least TWO meaningful tokens in the stated title (a bare acronym /
- *     nickname is not a title),
- *   - the title's acronym appearing in the stated title is the same document
- *     (TLS for Transport Layer Security); not a mismatch,
- *   - only ZERO overlap between stated-title tokens and real-title tokens
- *     flags a mismatch; any shared content word is a paraphrase — demote.
+ * Decide whether an EXPLICITLY STATED title conflicts with the real index title.
+ * Only a title introduced immediately after the RFC number counts (see
+ * statedTitleAfter): a mechanism citation states no title, and comparing that
+ * prose against a formal title reports a mismatch on a correct citation. Only
+ * ZERO token overlap is a mismatch — any shared content word is a paraphrase.
  * Returns "mismatch" | "match" | "no-title-claim".
  */
 function classifyRfcTitle(statedTitle, realTitle) {
@@ -290,30 +211,21 @@ function classifyRfcTitle(statedTitle, realTitle) {
   if (adjTokens.size < 2) return "no-title-claim";
   const realTokens = titleTokens(realTitle);
   if (realTokens.size === 0) return "no-title-claim";
-  // Acronym recognition: "tls" in the stated title matches "Transport
-  // Layer Security". Same document, not a wrong title.
   const acronym = titleAcronym(realTitle);
   if (acronym.length >= 2 && adjTokens.has(acronym)) return "match";
   let overlap = 0;
   for (const t of adjTokens) {
     if (realTokens.has(t)) { overlap++; continue; }
-    // Nickname / short-name recognition: a stated token that contains (or is
-    // contained by) a real-title token of length >= 4 is the same document
-    // under a common name — "IMAP4rev2" carries the real token "imap"
-    // ("...Access Protocol (IMAP)..."). Avoids false mismatches on the way
-    // developers actually cite RFCs by their well-known short names.
+    // Nickname recognition: a stated token containing (or contained by) a real
+    // token of length >= 4 is the same document — "IMAP4rev2" carries "imap".
     for (const rt of realTokens) {
       if (rt.length >= 4 && (t.includes(rt) || rt.includes(t))) { overlap++; break; }
     }
   }
-  // Any shared content word -> the author is describing the right
-  // document. Only a stated title with ZERO overlap is a conflicting
-  // claim. This trades recall for precision intentionally.
   return overlap === 0 ? "mismatch" : "match";
 }
 
-// Pull the text on the same line as the match, used as the "adjacent text"
-// for the RFC title comparison.
+// The whole line containing `index`, as adjacent text for the title comparison.
 function lineAround(content, index) {
   const start = content.lastIndexOf("\n", index) + 1;
   let end = content.indexOf("\n", index);
@@ -321,24 +233,12 @@ function lineAround(content, index) {
   return content.slice(start, end);
 }
 
-// Extract a title EXPLICITLY QUOTED immediately after the RFC number on the
-// same line:
-//   RFC N "The Title"      RFC N: "The Title"      RFC N ("The Title")
-// A quoted string is the only unambiguous title claim. Everything else states
-// no title and returns null:
-//   - free prose ("RFC 6455 wire layer"), a section pointer ("RFC 5322 §2.3"),
-//     and "X per RFC N" mechanism attributions describe usage, not the title;
-//   - bare nicknames ("RFC 9051 (IMAP4rev2)") are common short names;
-//   - and crucially, an RFC-number-shaped token inside CODE (`envelope.rfc822`
-//     matches "RFC 822"; `RFC 3339:` ahead of an object literal) is followed
-//     by code punctuation, never a quoted title — so comparing a code fragment
-//     against a formal title can no longer produce a phantom mismatch.
-// The opening quote must be SEPARATED from the number by whitespace or a
-// `:` / `(` introducer. A quote touching the last digit (`"…RFC 3339"`) is the
-// CLOSING quote of a string that happens to end with the citation, not the
-// opening quote of a title — without this guard the following code was
-// captured as a phantom "title". The closing quote bounds the title; straight
-// and typographic quotes are accepted.
+// Extract a title EXPLICITLY QUOTED immediately after the RFC number on the same
+// line — `RFC N "The Title"`, `RFC N: "The Title"`, `RFC N ("The Title")`. Prose,
+// section pointers, bare nicknames and `envelope.rfc822` state no title. The
+// opening quote must be SEPARATED from the number by whitespace or a `:` / `(`
+// introducer: one touching the last digit is the CLOSING quote of a string ending
+// with the citation, and the code after it is then captured as a phantom title.
 function statedTitleAfter(after) {
   const m = after.match(/^(?:\s*[:(]\s*|\s+)["“]([^"”\n]{3,100})["”]/);
   return m ? m[1].trim() : null;
@@ -370,16 +270,13 @@ function collect({ cwd = process.cwd() } = {}) {
 
   const scanFiles = files.filter((f) => SCAN_EXTS.has(path.extname(f.name).toLowerCase()));
 
-  // Hit collectors. Each entry keeps the file + the citation text so the
-  // artifact summary is auditable. CVE / RFC literals are references, not
-  // secrets, so they are safe to retain in the value text.
+  // Each entry keeps file and citation text so the artifact summary is auditable.
   const hits = {
     "fabricated-cve-id": [],
     "rejected-or-disputed-cve": [],
     "rfc-number-title-mismatch": [],
   };
-  // Inconclusive / needs-verification buckets — surfaced in artifacts,
-  // never flipped to a deterministic verdict.
+  // Needs-verification buckets: surfaced in artifacts, never flipped to a verdict.
   const needsVerify = {
     cve_not_in_catalog: [],
     rfc_not_in_index: [],
@@ -397,36 +294,29 @@ function collect({ cwd = process.cwd() } = {}) {
     }
     const illustrative = isIllustrativePath(f.rel);
 
-    // ---- CVE citations ----
     for (const m of content.matchAll(CVE_CITATION_RE)) {
       const full = m[0];
       totalCveCitations++;
-      // 1-based line of the citation so the evidence location carries a SARIF
-      // startLine region. Does not change any hit/miss verdict.
+      // 1-based, so the evidence location carries a SARIF startLine region.
       const cveLine = lineFromOffset(content, m.index);
       const canonical = CVE_CANONICAL_RE.test(full);
       if (!canonical) {
-        // Fabricated / malformed. Illustrative surfaces (templates,
-        // fixtures, the format-explaining docs) are demoted.
         if (!illustrative) {
           hits["fabricated-cve-id"].push({ file: f.rel, citation: full, line: cveLine });
         }
         continue;
       }
-      // Well-formed. Cross-reference the catalog.
       if (cveKeys.has(full)) {
         const note = cveNotes.get(full) || "";
         if (recordRejectedOrDisputed(note, full) && !illustrative) {
           hits["rejected-or-disputed-cve"].push({ file: f.rel, citation: full, line: cveLine });
         }
       } else if (catalogsLoaded && !illustrative) {
-        // Absent from the curated catalog: needs an external lookup.
-        // NOT a fabrication — inconclusive by design.
+        // Absent from the curated catalog is inconclusive, not a fabrication.
         needsVerify.cve_not_in_catalog.push({ file: f.rel, citation: full });
       }
     }
 
-    // ---- RFC citations ----
     for (const m of content.matchAll(RFC_CITATION_RE)) {
       totalRfcCitations++;
       const num = Number(m[1]);
@@ -447,9 +337,7 @@ function collect({ cwd = process.cwd() } = {}) {
           });
         }
       } else if (catalogsLoaded && !illustrative) {
-        // Number not in the published index. Needs verification; if draft
-        // language is adjacent, record it as a draft-as-RFC candidate
-        // (still inconclusive — left unflipped).
+        // Adjacent draft language makes it a draft-as-RFC candidate, still unflipped.
         needsVerify.rfc_not_in_index.push({ file: f.rel, citation: `RFC ${num}` });
         if (DRAFT_LANGUAGE_RE.test(line)) {
           needsVerify.draft_as_rfc_candidates.push({ file: f.rel, citation: `RFC ${num}` });
@@ -458,53 +346,39 @@ function collect({ cwd = process.cwd() } = {}) {
     }
   }
 
-  // signal_overrides: only the deterministically-decidable indicators are
-  // flipped. The needs-verification indicators stay absent so the runner
-  // returns inconclusive for them.
+  // Only deterministically-decidable indicators flip; the rest stay absent so the
+  // runner returns inconclusive for them.
   const signal_overrides = {
     "fabricated-cve-id": hits["fabricated-cve-id"].length > 0 ? "hit" : "miss",
     "rfc-number-title-mismatch": hits["rfc-number-title-mismatch"].length > 0 ? "hit" : "miss",
   };
-  // rejected-or-disputed-cve is high-confidence (not deterministic) — flip
-  // on a catalog-backed match, otherwise miss. Only assert a verdict when
-  // the catalog actually loaded; without it the check could not run.
+  // Only assert a verdict when the catalog loaded; without it the check cannot run.
   if (cveKeys.size > 0) {
     signal_overrides["rejected-or-disputed-cve"] =
       hits["rejected-or-disputed-cve"].length > 0 ? "hit" : "miss";
   } else {
     signal_overrides["rejected-or-disputed-cve"] = "inconclusive";
   }
-  // The needs-verification CVE indicator: hit means "found citations the
-  // offline catalog cannot confirm" — itself an inconclusive state, so it
-  // maps to inconclusive (not a clean miss) when such citations exist.
+  // Citations the offline catalog cannot confirm are inconclusive, not a miss.
   if (needsVerify.cve_not_in_catalog.length > 0) {
     signal_overrides["cve-citation-needs-external-verification"] = "inconclusive";
   }
 
-  // __fp_checks attestation for the FP-gated indicators the collector decides
-  // deterministically. Each hit already excludes illustrative (template /
-  // fixture / doc-snippet) paths and is keyed off the shipped catalogs, so the
-  // path / catalog-cross-reference / same-citation checks the collector ran
-  // are attested; surrounding-text-acknowledgement remains operator judgement.
-  // Without this the runner downgrades a real bad citation to inconclusive.
+  // __fp_checks attest the FP checks this collector ran; without the attestation
+  // the runner downgrades a real bad citation to inconclusive.
   if (signal_overrides["fabricated-cve-id"] === "hit") {
-    // [0] not under a fixture / regex-example / doc-snippet path (illustrative
-    //     paths are excluded before the hit). [1] placeholder forms (CVE-TBD /
-    //     pending) never match the numeric citation regex, so a fired hit is
-    //     not a placeholder.
+    // [0] illustrative paths are excluded before the hit; [1] placeholder forms
+    //     never match the numeric citation regex.
     signal_overrides["fabricated-cve-id__fp_checks"] = { "0": true, "1": true };
   }
   if (signal_overrides["rejected-or-disputed-cve"] === "hit") {
-    // [1] the catalog note marks THIS exact identifier rejected/disputed.
-    // [2] the identifier is present in the catalog (absence does not fire).
-    // [0] inline dispute-acknowledgement in surrounding prose is operator
-    //     judgement — left unattested.
+    // [1] the catalog note marks THIS identifier; [2] it is in the catalog.
+    //     [0] inline dispute acknowledgement in prose is left unattested.
     signal_overrides["rejected-or-disputed-cve__fp_checks"] = { "1": true, "2": true };
   }
   if (signal_overrides["rfc-number-title-mismatch"] === "hit") {
-    // [0] a paraphrase / nickname (no title claim) does not fire. [1] numbers
-    // absent from the shipped RFC index do not fire. [2] the stated title is
-    // extracted from the SAME citation line.
+    // [0] a paraphrase / nickname does not fire; [1] numbers absent from the
+    //     index do not fire; [2] the stated title comes from the same line.
     signal_overrides["rfc-number-title-mismatch__fp_checks"] = { "0": true, "1": true, "2": true };
   }
 
@@ -549,10 +423,7 @@ function collect({ cwd = process.cwd() } = {}) {
     },
   };
 
-  // Per-indicator file locations for the indicators flipped to "hit",
-  // so SARIF results point at the source file that carries the bad
-  // citation. The hits record a 1-based `line` (from the match offset),
-  // so locations include a startLine region.
+  // Locations for flipped indicators, so SARIF results point at the source line.
   const evidence_locations = {};
   for (const id of Object.keys(hits)) {
     if (signal_overrides[id] === "hit") {
@@ -568,9 +439,7 @@ function collect({ cwd = process.cwd() } = {}) {
     artifacts,
     signal_overrides,
     ...(Object.keys(evidence_locations).length ? { evidence_locations } : {}),
-    // The citations the offline catalog could not confirm. `applyResolution`
-    // (opt-in --resolve) consumes this to resolve + flip them; on a plain
-    // collect it documents what still needs verification.
+    // Consumed by applyResolution (--resolve) to resolve and flip these.
     needs_verification: needsVerify,
     collector_meta: {
       collector_id: COLLECTOR_ID,
@@ -590,14 +459,11 @@ function collect({ cwd = process.cwd() } = {}) {
 }
 
 /**
- * Resolve the citations a plain collect() left as needs-verification, flipping
- * the parked signals from inconclusive to a real verdict. Opt-in: only invoked
- * for `exceptd collect citation-hygiene --resolve`. Each uncatalogued CVE goes
- * through the shared resolver (catalog -> cache -> one NVD lookup, cached), so a
- * fan-out resolves each id once. Honors air-gap (resolver returns unknown).
- *
- * Mutates a shallow copy of the submission's signal_overrides and records a
- * resolution summary artifact. Returns the updated submission.
+ * Resolve the citations collect() left as needs-verification, flipping the parked
+ * signals from inconclusive to a real verdict. Each uncatalogued CVE goes through
+ * the shared resolver (catalog -> cache -> one NVD lookup, cached), so a fan-out
+ * resolves each id once. Returns a shallow copy carrying a resolution summary
+ * artifact; `submission` itself is not mutated.
  *
  * @param {object} submission  the object returned by collect()
  * @param {object} [opts]      { airGap?: boolean, _resolveCve?, _resolveRfc? }
@@ -630,9 +496,7 @@ async function applyResolution(submission, opts = {}) {
   }
   if (rejectedHit) signals["rejected-or-disputed-cve"] = "hit";
   if (fabricatedHit) signals["fabricated-cve-id"] = "hit";
-  // The needs-verification signal: a clean miss once every parked CVE was
-  // classified, inconclusive while any remain unresolvable (NVD unreachable /
-  // air-gap), and absent when there was nothing to verify.
+  // A miss once every parked CVE is classified; inconclusive while any stay unknown.
   if (cveList.length > 0) {
     signals["cve-citation-needs-external-verification"] = cveUnknown > 0 ? "inconclusive" : "miss";
   }
@@ -643,9 +507,7 @@ async function applyResolution(submission, opts = {}) {
     const num = (cite.match(/(\d+)/) || [])[1];
     const r = await resolver.resolveRfc(num || cite, { airGap });
     resolved.rfc.push({ citation: cite, file: item.file, status: r.status, found: r.found, from: r.from, title: r.title || null });
-    // A cited RFC number that resolves to nothing is a bad citation, same class
-    // as a fabricated CVE — surface it instead of discarding the verdict. (An
-    // obsoleted/historic RFC that resolves IS a real RFC, so it isn't flagged.)
+    // A number resolving to nothing is a bad citation; an obsoleted RFC still resolves.
     if (r.status === "nonexistent") rfcNonexistentHit = true;
   }
   if (rfcNonexistentHit) signals["rfc-number-title-mismatch"] = "hit";