@blamejs/exceptd-skills 0.19.33 → 0.19.34

package/lib/refresh-external.js

@@ -1,38 +1,7 @@
 "use strict";
 /**
- * lib/refresh-external.js
- *
- * External-data refresh orchestrator. Pulls the latest from the canonical
- * upstream sources and either reports drift (dry-run, default) or applies
- * the drift as an upsert into the local catalog (--apply).
- *
- * Sources (each is independently pluggable):
- *
- *   KEV    — CISA Known Exploited Vulnerabilities (per-CVE upsert of
- *            cisa_kev / cisa_kev_date)
- *   EPSS   — FIRST EPSS (per-CVE upsert of epss_score / epss_percentile /
- *            epss_date)
- *   NVD    — NIST NVD 2.0 (per-CVE upsert of cvss_score / cvss_vector)
- *   RFC    — IETF Datatracker (per-RFC upsert of status)
- *   PINS   — MITRE ATLAS / ATT&CK / D3FEND / CWE upstream releases
- *            (REPORT-ONLY — version bumps need audit per AGENTS.md
- *            Hard Rule #12, so they surface as findings, not auto-applied)
- *
- * Usage:
- *   node lib/refresh-external.js              # dry-run all sources
- *   node lib/refresh-external.js --apply      # apply all sources
- *   node lib/refresh-external.js --source kev # one source, dry-run
- *   node lib/refresh-external.js --apply --source kev,epss
- *   node lib/refresh-external.js --from-fixture <path>   # use frozen fixture
- *                                                          payloads (offline)
- *
- * Exit codes:
- *   0 — dry-run completed (regardless of whether drift was found)
- *   1 — apply mode AND a downstream gate (validate-indexes, lint) failed
- *   2 — unrecoverable runner error
- *
- * The refresh-report.json artifact lives at the repo root and is
- * gitignored. CI uploads it as a workflow artifact.
+ * External-data refresh orchestrator: reports upstream drift (dry-run, the
+ * default) or upserts it into the local catalog (--apply).
  */
 
 const fs = require("fs");
@@ -45,15 +14,8 @@ const ROOT = path.join(__dirname, "..");
 const ABS = (p) => path.join(ROOT, p);
 const TODAY = new Date().toISOString().slice(0, 10);
 
-// v0.12.8: the CVE catalog path used by refresh-external is overridable so
-// tests can redirect to a tempdir instead of mutating the real shipped
-// data/cve-catalog.json. Resolution order:
-//   1. opts.catalog (--catalog CLI arg)
-//   2. process.env.EXCEPTD_CVE_CATALOG (env var)
-//   3. ROOT/data/cve-catalog.json (default)
-// All four write-sites in this file route through resolveCatalogPath() so
-// that the redirect is consistent across the advisory-import, GHSA-import,
-// and per-source merge code paths.
+// Every write site in this file resolves the catalog path through here, so a
+// --catalog / EXCEPTD_CVE_CATALOG redirect holds across all of them.
 function resolveCatalogPath(opts) {
   if (opts && opts.catalog) return path.resolve(opts.catalog);
   if (process.env.EXCEPTD_CVE_CATALOG) return path.resolve(process.env.EXCEPTD_CVE_CATALOG);
@@ -67,7 +29,7 @@ function parseArgs(argv) {
     fromFixture: null,   // path to fixture dir
     fromCache: null,     // path to .cache/upstream dir (or default if --from-cache passed bare)
     swarm: false,        // fan-out sources across worker threads
-    advisory: null,      // v0.12.0: single-advisory seed (CVE-* or GHSA-*)
+    advisory: null,      // single-advisory seed (CVE-* or GHSA-*)
     help: false,
     quiet: false,
     json: false,
@@ -81,16 +43,10 @@ function parseArgs(argv) {
     else if (a === "--help" || a === "-h") out.help = true;
     else if (a === "--advisory") { out.advisory = argv[++i]; }
     else if (a.startsWith("--advisory=")) { out.advisory = a.slice("--advisory=".length); }
-    // --check-advisories polls the primary-source advisory feeds (Qualys TRU,
-    // RHSA, USN, ZDI, kernel.org, oss-security, vendor research blogs) and
-    // reports newly-seen CVE IDs ahead of NVD enrichment. Report-only: it
-    // selects the `advisories` source and never applies — operators triage the
-    // diffs[] and seed promising IDs via `refresh --advisory <id> --apply`.
     else if (a === "--check-advisories") { out.source = "advisories"; out.apply = false; out.checkAdvisories = true; }
     else if (a === "--catalog") { out.catalog = argv[++i]; }
     else if (a.startsWith("--catalog=")) { out.catalog = a.slice("--catalog=".length); }
     else if (a === "--from-cache") {
-      // accept either --from-cache <path> or --from-cache (default path)
       const next = argv[i + 1];
       if (next && !next.startsWith("--")) { out.fromCache = next; i++; }
       else out.fromCache = ".cache/upstream";
@@ -102,37 +58,19 @@ function parseArgs(argv) {
     else if (a.startsWith("--from-fixture=")) out.fromFixture = a.slice("--from-fixture=".length);
     else if (a === "--report-out") out.reportOut = argv[++i];
     else if (a.startsWith("--report-out=")) out.reportOut = a.slice("--report-out=".length);
-    // Honour `--air-gap` here so it reaches the GHSA/OSV source modules.
-    // EXCEPTD_AIR_GAP=1 still works as an env-var fallback so existing
-    // automation isn't broken.
     else if (a === "--air-gap") out.airGap = true;
-    // `--force-stale` bypasses cache-freshness + cache-signature refusals.
-    // Required when the operator intentionally wants to consume a cache
-    // older than 7d or one that was prefetched without a signing keypair.
-    // EXCEPTD_FORCE_STALE=1 mirrors for non-interactive automation.
+    // Bypasses the cache freshness and signature refusals.
     else if (a === "--force-stale") out.forceStale = true;
-    // --drift-only reconciles the entries the catalog already holds and skips
-    // auto-discovery of new ones. Discovery imports drafts that still need
-    // curation, so an operator correcting stale fields on shipped entries would
-    // otherwise have to take that work in the same commit or leave the fields
-    // stale.
     else if (a === "--drift-only") out.driftOnly = true;
-    // --prefetch / --no-network are prefetch-cache operations. Capture them so
-    // main() can delegate to lib/prefetch.js (the same routing bin/exceptd.js
-    // performs) when this script is invoked directly — otherwise the help
-    // text's "report-only, no cache write" promise for --no-network is a lie
-    // on the direct path, which would fall through to the live refresh loop.
+    // Cache operations; main() delegates them to lib/prefetch.js.
     else if (a === "--no-network") { out.noNetwork = true; }
     else if (a === "--prefetch") { out.prefetch = true; }
-    // Remaining bin-translated aliases are tolerated as no-ops at this layer
-    // so the unknown-flag guard below doesn't false-reject them.
+    // bin-translated aliases, accepted so the unknown-flag guard below spares them.
     else if (
       a === "--indexes-only" ||
       a === "--network" || a === "--curate" || a === "--force-stale-acked"
     ) { /* accepted, no-op at this layer */ }
-    // Any remaining --flag is an unrecognized typo. Record it; refuse after
-    // the loop rather than silently dropping it into a default full-refresh
-    // (which previously hit the live network on every source).
+    // Any remaining --flag is a typo: recorded here, refused in main().
     else if (typeof a === "string" && a.startsWith("--")) {
       const base = a.indexOf("=") === -1 ? a : a.slice(0, a.indexOf("="));
       (out._unknownFlags || (out._unknownFlags = [])).push(base);
@@ -253,17 +191,12 @@ AGENTS.md Hard Rule #12 and are surfaced as report-only findings.
 `);
 }
 
-// --- Source modules ----------------------------------------------------
-
 /**
- * Each source module exposes:
- *   name: string
- *   fetchDiff(ctx, opts) -> Promise<{ status, diffs, errors, summary }>
- *     status: "ok" | "unreachable" | "partial"
- *     diffs:  array of { id, field, before, after, severity? }
- *     summary: brief string
- *   applyDiff(ctx, diffs) -> Promise<{ updated, errors }>
- *     mutates local catalog and writes it
+ * Every source module exposes:
+ *   fetchDiff(ctx, opts) -> { status: "ok" | "unreachable" | "partial",
+ *                             diffs: [{ id, field, before, after, severity? }],
+ *                             errors, summary }
+ *   applyDiff(ctx, diffs) -> { updated, errors }, having written the catalog
  */
 
 const { discoverNewKev, discoverNewRfcs } = require("./auto-discovery");
@@ -279,14 +212,9 @@ const KEV_SOURCE = {
     const report = await validateAllCves(ctx.cveCatalog, { concurrency: 4 });
     const diffs = [];
     let errors = 0;
-    // Mirror the cache path's implausibly-small-feed guard. The live KEV map is
-    // fetched once per process and its size is surfaced on every reachable
-    // result as fetched.sources.kev.total_entries. A feed that JSON-parses but
-    // is far below a real CISA snapshot (a partial CDN response, a momentarily
-    // near-empty feed) must not be trusted to de-list curated entries. When the
-    // size is known and below the floor we hold ALL de-listings for review,
-    // exactly as kevDiffFromCache does; when the size is unknown (no reachable
-    // KEV result carried it) we fall back to the per-entry curated-signal guard.
+    // A feed that parses but sits far below a real CISA snapshot must not be
+    // trusted to de-list curated entries. With no size available, the per-entry
+    // curated-signal guard is the fallback.
     let liveFeedSize = null;
     for (const r of report.results) {
       const n = r && r.fetched && r.fetched.sources && r.fetched.sources.kev
@@ -297,26 +225,16 @@ const KEV_SOURCE = {
     for (const r of report.results) {
       if (r.status === "unreachable") errors++;
       for (const d of r.discrepancies || []) {
-        // Every KEV field the validator compares, not just the flag and its
-        // date: a filter naming two of the four leaves the deadline and the
-        // ransomware designation reconciling on --from-cache runs alone, which
-        // is not the path most operators take.
         if (KEV_RECONCILED_FIELDS.has(d.field)) {
           const diff = { id: r.cve_id, field: d.field, before: d.local, after: d.fetched, severity: d.severity };
-          // A designation being REMOVED against an implausibly small feed is the
-          // feed failing to tell us something, not upstream telling us it is
-          // gone — held for review exactly as a de-listing is.
+          // A designation REMOVED against an implausibly small feed is the feed
+          // failing to say something, not upstream saying it is gone.
           if (d.field === "known_ransomware_use" && d.local === true && d.fetched === false && !feedComplete) {
             diff.review_only = true;
             diff.note = `Ransomware designation removal held for review: live feed returned only ${liveFeedSize} entries (< ${KEV_FEED_MIN_PLAUSIBLE}), likely incomplete.`;
           }
-          // Symmetric with the --from-cache path: a LIVE KEV de-listing
-          // (true→false) is held for review (applyDiff skips review_only)
-          // instead of auto-downgrading the entry when EITHER the entry carries
-          // strong human-curated exploitation signal OR the live feed is
-          // implausibly small. Without this the live path silently de-listed
-          // confirmed-exploitation CVEs the cache path would have held back, and
-          // a truncated-but-valid feed could de-list every non-curated entry.
+          // A de-listing is review-only — applyDiff skips those — when the entry
+          // carries curated exploitation signal or the feed is implausibly small.
           if (d.field === "cisa_kev" && d.local === true && d.fetched === false &&
               (!feedComplete || hasCuratedExploitSignal(ctx.cveCatalog && ctx.cveCatalog[r.cve_id]))) {
             diff.review_only = true;
@@ -344,8 +262,6 @@ const KEV_SOURCE = {
     await withCatalogLock(catalogPath, (catalog) => {
       for (const d of diffs) {
         if (d.op === "add") {
-          // Auto-discovered new entry. Refuse to overwrite if the entry
-          // somehow exists (race condition / stale fixture); skip silently.
           if (catalog[d.id]) continue;
           catalog[d.id] = d.entry;
           added++;
@@ -355,43 +271,31 @@ const KEV_SOURCE = {
           errors.push(`KEV: no local entry for ${d.id}`);
           continue;
         }
-        // A de-listing flagged for review (a curated entry with strong
-        // exploitation signal that upstream KEV no longer lists) is surfaced
-        // in the report but NOT auto-applied: the curated flag, factor, score
-        // and dates are left intact so a maintainer can confirm a genuine
-        // CISA removal vs a transient / incomplete feed before the entry is
-        // downgraded. Skip the write here.
+        // review_only keeps the flag, factor, score and dates intact until a
+        // maintainer confirms a genuine CISA removal.
         if (d.review_only) continue;
         catalog[d.id][d.field] = d.after;
-        // A cisa_kev flip changes the entry's RWEP: the KEV factor carries
-        // RWEP_WEIGHTS.cisa_kev points, and the catalog invariant requires
-        // rwep_score to equal the factor sum. Writing the flag without the
-        // factor + score left entries failing scoring.validate() (stored 45
-        // vs computed 70 on the first real KEV listing the refresh applied).
+        // The catalog invariant is rwep_score === Σ rwep_factors, so a cisa_kev
+        // flip must rewrite the factor and the score with it.
         if (d.field === "cisa_kev") {
           const entry = catalog[d.id];
           if (entry.rwep_factors && typeof entry.rwep_factors === "object") {
             const scoring = require("./scoring");
-            // Match the stored factor shape: Shape A keeps the boolean,
-            // Shape B (the catalog norm) stores the post-weight contribution.
+            // Match the stored factor shape: a boolean, or the post-weight
+            // contribution the catalog norm holds.
             entry.rwep_factors.cisa_kev =
               typeof entry.rwep_factors.cisa_kev === "boolean"
                 ? !!d.after
                 : (d.after ? scoring.RWEP_WEIGHTS.cisa_kev : 0);
             entry.rwep_score = scoring.deriveRwepFromFactors(entry.rwep_factors);
           }
-          // A de-listing (true→false) leaves the listing date orphaned: the
-          // CVE is no longer KEV-listed, so its dateAdded is stale intel.
-          // The upstream diff producer only emits a cisa_kev_date diff when
-          // upstream has a date, which a de-listed CVE no longer does — so
-          // nothing else clears it. Drop the now-meaningless date fields here.
+          // Nothing else clears the dates: the diff producer emits a
+          // cisa_kev_date diff only when upstream HAS a date.
           if (d.after === false) {
             if ("cisa_kev_date" in entry) entry.cisa_kev_date = null;
             if ("cisa_kev_due_date" in entry) entry.cisa_kev_due_date = null;
-            // The designation restates a KEV record that no longer exists, so
-            // it cannot stand. Null rather than false: false would assert that
-            // CISA records no ransomware use, which is a claim about a record
-            // that is gone, not a fact upstream supplied.
+            // Null, not false: false would assert a claim about a record that
+            // no longer exists.
             if ("known_ransomware_use" in entry) entry.known_ransomware_use = null;
           }
         }
@@ -400,8 +304,7 @@ const KEV_SOURCE = {
       }
       catalog._meta = catalog._meta || {};
       catalog._meta.last_updated = TODAY;
-      // Refresh the in-memory view so later sources in the same process
-      // (sequential or --swarm) see the post-write state.
+      // Refresh the in-memory view so later sources in this process see the write.
       ctx.cveCatalog = catalog;
       return catalog;
     });
@@ -410,9 +313,7 @@ const KEV_SOURCE = {
 };
 
 /**
- * Cache-mode KEV with auto-discovery merged in. Standard drift-check
- * for existing entries plus discoverNewKev() for entries upstream that
- * aren't in the local catalog. Spill count is surfaced in the summary.
+ * Cache-mode KEV drift plus discoverNewKev() for entries the catalog lacks.
  */
 function kevDiffWithDiscoveryFromCache(ctx) {
   const drift = kevDiffFromCache(ctx);
@@ -435,21 +336,9 @@ function kevDiffWithDiscoveryFromCache(ctx) {
 }
 
 /**
- * EPSS publishes score, percentile and date as ONE row, and the percentile is
- * the score's rank within that day's publication. Writing one field without the
- * others leaves a pair drawn from two different days: both numbers in range,
- * both shaped like EPSS values, and nothing downstream able to tell them apart
- * from a coherent pair. That is the corruption scripts/check-epss-consistency.js
- * detects, and a detector cannot repair it — as that gate's own header says, the
- * provenance guarantee has to come from the write side.
- *
- * The bug this replaces applied the drift threshold to score and percentile
- * INDEPENDENTLY: a score that moved past the threshold was written while its
- * percentile, having moved less, was left at yesterday's value. So the rule is
- * now that the threshold decides WHETHER an entry is refreshed, never WHICH of
- * its fields is. Once either number has moved, every field comes from that same
- * row — including the one whose own delta is under the threshold, and including
- * a half of the pair the entry was missing entirely.
+ * EPSS publishes score, percentile and date as ONE row, so a field written
+ * without the others leaves the entry describing two different days. The drift
+ * threshold decides WHETHER an entry is refreshed, never WHICH of its fields.
  *
  * `local` is the catalog entry; `fetched` is {score, percentile, date} read from
  * one EPSS row.
@@ -458,44 +347,22 @@ const EPSS_DRIFT = 0.05;
 
 function epssTripleDiffs(id, local, fetched, drift) {
   const { score, percentile, date } = fetched;
-  // Only a COMPLETE row can produce a coherent triple, so a partial one is
-  // refused before anything else is considered. Guarding this per-branch was
-  // not enough: a row carrying just one number can still cross the drift
-  // threshold on that number, and writing it beside the other half from the
-  // previous publication is precisely the mixed-publication state this function
-  // exists to prevent. At the top, the guard covers a complete local entry and
-  // a half-populated one alike.
-  //
-  // The date is the third member, not decoration. A row with both numbers and
-  // no date would write the new numbers while the entry kept its old
-  // epss_date — and the regenerated note would then state those numbers "as of"
-  // a publication they did not come from, which is the same defect wearing
-  // different clothes.
-  // Finite, not merely present: the callers build these with Number(), which
-  // turns a malformed cached value into NaN rather than null. A NaN would pass
-  // a nullish check, ride the repair path, and land in the catalog serialised
-  // as null — reintroducing the half-populated entry the repair exists to fix.
+  // Only a COMPLETE row produces a coherent triple, the date included — without
+  // it the numbers land under the old epss_date. Finite rather than present: the
+  // callers use Number(), and a NaN passes a nullish check and serialises null.
   if (!Number.isFinite(score) || !Number.isFinite(percentile) || !date) return [];
 
   const scoreMoved = local.epss_score != null && Math.abs(score - local.epss_score) > drift;
   const pctMoved = local.epss_percentile != null && Math.abs(percentile - local.epss_percentile) > drift;
 
-  // An entry holding one half of the pair is already inconsistent, and the
-  // drift threshold cannot reach it: the absent side has nothing to compare
-  // against, so its "moved" test is false by construction, and if the present
-  // side happens to be stable the entry stays half-populated forever while the
-  // consistency gate keeps failing on it. A complete row repairs it regardless
-  // of how far anything moved. An entry carrying NO EPSS at all is left alone —
-  // that is an absent field, not an incoherent pair.
+  // The drift threshold cannot reach a half-populated entry: the absent side has
+  // nothing to compare against, so a stable present side leaves it broken. An
+  // entry carrying NO EPSS is left alone — an absent field is not an incoherent pair.
   const localIncomplete = (local.epss_score == null) !== (local.epss_percentile == null);
   if (!scoreMoved && !pctMoved && !localIncomplete) return [];
 
-  // `coherent` records PROVENANCE: these diffs were derived from a single
-  // complete, validated row, so whatever subset of fields actually differs, the
-  // entry is left describing one publication. The consumer cannot infer that
-  // from the fields alone — a complete row whose percentile rounds to the same
-  // value legitimately emits the score by itself, which is indistinguishable
-  // from a hand-built partial diff set unless the emitter says so.
+  // `coherent` records PROVENANCE: whatever subset differs, these diffs came
+  // from one complete row. A consumer cannot infer that from the fields alone.
   const out = [];
   const emit = (field, before, after, severity) =>
     out.push({ id, field, before, after, severity, coherent: true });
@@ -520,10 +387,8 @@ const EPSS_SOURCE = {
     let errors = 0;
     for (const r of report.results) {
       if (r.status === "unreachable") errors++;
-      // Diff off the FETCHED ROW rather than off r.discrepancies. The
-      // discrepancy list names only the fields that differ enough to report,
-      // which is precisely the input that used to let score and percentile be
-      // written from different publications — see epssTripleDiffs.
+      // Diff off the FETCHED ROW, not r.discrepancies: that list names only the
+      // fields differing enough to report, which mixes publications.
       if (!r.fetched?.epss || !r.local) continue;
       diffs.push(...epssTripleDiffs(r.cve_id, r.local, r.fetched.epss, EPSS_DRIFT));
     }
@@ -548,32 +413,20 @@ const EPSS_SOURCE = {
         catalog[d.id][d.field] = d.after;
         catalog[d.id].last_verified = TODAY;
         // An id is coherent only if EVERY diff applied to it declares that
-        // provenance; one unmarked diff in the set is enough to withhold the
-        // note rewrite.
+        // provenance.
         touchedFields.set(d.id, (touchedFields.get(d.id) !== false) && d.coherent === true);
         updated++;
       }
-      // `epss_note` restates the three fields in prose. It is derived, so a
-      // refresh that moves the numbers and leaves the sentence behind makes the
-      // entry state two different scores as of two different dates — which the
-      // consistency gate reports as a failure on data that was otherwise
-      // refreshed correctly. Rebuild it from the same renderer the gate checks
-      // against, and only for entries that already carry one: adding the note
-      // to an entry that never had it is a content change, not a refresh.
+      // `epss_note` restates the three fields in prose, so moving the numbers
+      // without it leaves the entry stating two scores as of two dates. Rebuilt
+      // only where a note exists — adding one is a content change.
       for (const [id, coherent] of touchedFields) {
         const e = catalog[id];
         if (typeof e.epss_note !== "string") continue;
         if (typeof e.epss_score !== "number" || typeof e.epss_percentile !== "number") continue;
-        // Regenerate only for diffs whose emitter vouched that they came from
-        // one complete publication. applyDiff is exported and is also driven by
-        // fixtures carrying a score and a date without a percentile, so a diff
-        // set can move half the pair on its own; rewriting the note from the
-        // surviving stale percentile would make a mixed-publication entry read
-        // as current and suppress the only signal the consistency gate has for
-        // it. Deciding this from WHICH fields changed does not work — a
-        // complete row whose percentile rounds to the same value emits the
-        // score alone, and skipping it there would strand the note stale
-        // forever, because the next refresh sees no diff left to repair it.
+        // Only diffs whose emitter vouched for one complete publication: this is
+        // exported, and a fixture moving half the pair would rewrite the note
+        // from a stale percentile and make a mixed entry read as current.
         if (!coherent) continue;
         e.epss_note = renderEpssNote(e);
       }
@@ -618,9 +471,7 @@ const NVD_SOURCE = {
     const catalogPath = ctx.cvePath || ABS("data/cve-catalog.json");
     await withCatalogLock(catalogPath, (catalog) => {
       for (const d of diffs) {
-        // A curator-owned CVSS re-score is surfaced in the report but not
-        // applied — the curated value is preserved until a maintainer accepts
-        // the upstream delta (symmetric with the KEV review_only path).
+        // A curator-owned CVSS re-score is reported, not applied.
         if (d.review_only) continue;
         if (!catalog[d.id]) {
           errors.push(`NVD: no local entry for ${d.id}`);
@@ -657,8 +508,7 @@ const RFC_SOURCE = {
       }
       if (r.status === "drift" && r.discrepancies) {
         for (const msg of r.discrepancies) {
-          // The current rfc-validator returns discrepancies as strings. We
-          // attempt to parse a status drift; fall back to the raw message.
+          // The validator returns discrepancies as strings.
           const m = msg.match(/local "([^"]+)" vs Datatracker "([^"]+)"/);
           if (m) {
             diffs.push({ id: r.id, field: "status", before: m[1], after: m[2], severity: "medium" });
@@ -708,11 +558,8 @@ const RFC_SOURCE = {
 };
 
 /**
- * Cache-mode RFC with auto-discovery merged in. Drift-check for
- * existing entries (cache only) plus discoverNewRfcs() which hits
- * Datatracker live for new RFCs in project-relevant working groups.
- * Discovery makes ~30 HTTP calls (one per project WG) per refresh —
- * Datatracker's read budget is generous so this is well within limit.
+ * Cache-mode RFC drift plus discoverNewRfcs(), which hits Datatracker live —
+ * one HTTP call per working group per refresh.
  */
 async function rfcDiffWithDiscoveryFromCache(ctx) {
   const drift = rfcDiffFromCache(ctx);
@@ -776,23 +623,14 @@ const PINS_SOURCE = {
     };
   },
   async applyDiff() {
-    // Version pins are intentionally not auto-applied.
     return { updated: 0, errors: ["pin bumps are report-only — see Hard Rule #12"] };
   },
 };
 
 /**
- * v0.12.0: GHSA (GitHub Advisory Database) source. Covers npm, PyPI,
- * RubyGems, Maven, NuGet, Go, Composer, Swift, Erlang, Pub, Rust — all
- * in one feed, updated within hours of disclosure. Much faster than KEV
- * (variable, often days) or NVD (~10 days).
- *
- * Apply path: new CVE IDs from GHSA land in data/cve-catalog.json as
- * DRAFTS (`_auto_imported: true` + `_draft: true`). The strict catalog
- * validator treats drafts as warnings, not errors, so the nightly
- * auto-PR pipeline can ship them without blocking on editorial review.
- * Framework gaps + IoCs + ATLAS/ATT&CK refs require human or AI-assisted
- * synthesis via `exceptd run cve-curation --advisory <id>`.
+ * GitHub Advisory Database. New CVE IDs land as drafts (`_auto_imported` +
+ * `_draft`), which the strict validator treats as warnings; framework gaps, IoCs
+ * and ATLAS/ATT&CK refs need `exceptd run cve-curation --advisory <id>`.
  */
 const GHSA_SOURCE = {
   name: "ghsa",
@@ -801,11 +639,6 @@ const GHSA_SOURCE = {
   async fetchDiff(ctx) {
     if (ctx.fixtures?.ghsa) return synthesizeFromFixture(ctx, "ghsa");
     if (ctx.cacheDir) {
-      // --from-cache is the offline ingest path: every source reads only
-      // local cache files, never the network. GHSA has no cache layer, so
-      // there is nothing to read offline. Skip it with a structured status
-      // instead of falling through to the live api.github.com fetch, which
-      // would silently egress on a host the operator believes is isolated.
       return {
         status: "unreachable",
         diffs: [],
@@ -817,13 +650,8 @@ const GHSA_SOURCE = {
     return ghsa.buildDiff(ctx);
   },
   async applyDiff(ctx, diffs) {
-    // v0.12.14: the prior shape mutated ctx.cveCatalog in
-    // memory but NEVER persisted to disk. Bulk `--source ghsa --apply`
-    // reported "applied: N updates" while the catalog file gained zero
-    // entries. Worse under `--swarm`: KEV's withCatalogLock would re-read
-    // catalog from disk INSIDE the lock and overwrite the unflushed
-    // in-memory mutations. Route through the same withCatalogLock helper
-    // that KEV/EPSS/NVD/RFC use (v0.12.12 concurrency fix).
+    // A mutation of ctx.cveCatalog alone never reaches disk, and under --swarm
+    // another source's lock re-reads from disk and overwrites it.
     const catalogPath = ctx.cvePath || ABS("data/cve-catalog.json");
     let updated = 0;
     const errors = [];
@@ -847,18 +675,9 @@ const GHSA_SOURCE = {
 };
 
 /**
- * v0.12.10: OSV.dev source. Aggregates OSSF Malicious Packages (MAL-*) +
- * Snyk (SNYK-*) + GitHub Advisory Database + RustSec (RUSTSEC-*) + Mageia
- * + Go Vuln DB + Ubuntu USN into one unauthenticated API. Slot in for the
- * package-compromise class that doesn't have a CVE yet — the MAL-*
- * namespace is the canonical key for those (e.g. MAL-2026-3083, the
- * elementary-data PyPI worm).
- *
- * Apply path mirrors GHSA: new entries land in data/cve-catalog.json as
- * drafts (`_auto_imported: true` + `_draft: true`). Catalog key is either
- * the CVE alias (when present) or the OSV id verbatim — preserving the
- * existing CVE-keyed convention while accepting OSV's broader identifier
- * shapes.
+ * OSV.dev — MAL-*, Snyk, GHSA, RustSec, Mageia, Go Vuln DB and Ubuntu USN behind
+ * one unauthenticated API. Entries land as drafts like GHSA's, keyed by the CVE
+ * alias when there is one and by the OSV id verbatim otherwise.
  */
 const OSV_SOURCE = {
   name: "osv",
@@ -867,10 +686,6 @@ const OSV_SOURCE = {
   async fetchDiff(ctx) {
     if (ctx.fixtures?.osv) return synthesizeFromFixture(ctx, "osv");
     if (ctx.cacheDir) {
-      // --from-cache is the offline ingest path. OSV resolves advisories by
-      // live id lookup (ctx.osv_ids) and has no cache layer, so skip it with
-      // a structured status rather than risk a live osv.dev fetch on a host
-      // the operator believes is isolated.
       return {
         status: "unreachable",
         diffs: [],
@@ -882,9 +697,7 @@ const OSV_SOURCE = {
     return osv.buildDiff(ctx);
   },
   async applyDiff(ctx, diffs) {
-    // v0.12.14: same fix as GHSA — route the read-modify-write
-    // through withCatalogLock so writes actually land on disk and so
-    // concurrent --source osv --apply doesn't lose updates.
+    // Lock-gated like GHSA: a ctx-only mutation never reaches disk.
     const catalogPath = ctx.cvePath || ABS("data/cve-catalog.json");
     let updated = 0;
     const errors = [];
@@ -907,22 +720,12 @@ const OSV_SOURCE = {
   },
 };
 
-// v0.13.1: ADVISORIES_SOURCE polls Qualys TRU + RHSA + USN + ZDI primary
-// feeds and surfaces CVE IDs not yet in the catalog. Report-only — no
-// auto-catalog mutation. Closes the post-mortem gap on CVE-2026-46333
-// (ssh-keysign-pwn) where the existing NVD-based pollers lagged by 3+ days.
+// Primary advisory feeds (Qualys TRU, RHSA, USN, ZDI), report-only.
 const { ADVISORIES_SOURCE } = require('./source-advisories');
 
-// v0.13.17: REGRESSION_WATCHER_SOURCE is NEW-CTRL-074. Implements the
-// detection method that surfaces poller-diff historical-CVE references as
-// candidate silent-regression cases (the MiniPlasma class — a 2026 PoC
-// drop that re-broke CVE-2020-17103 without any new ID being assigned).
-// Report-only; consumes the prior advisories run's output. The main()
-// source loop threads the advisories fetchDiff() result onto
-// ctx.advisoriesObservations (preferred) + ctx.advisoriesDiffs (fallback)
-// after the advisories source resolves and before the watcher runs, so the
-// two must be invoked in that order (advisories first). Under --swarm the
-// watcher runs in a second pass after the parallel batch resolves.
+// NEW-CTRL-074: flags poller-diff historical-CVE references as candidate silent
+// regressions. Report-only, and it consumes the advisories run's output through
+// ctx.advisoriesObservations (or ctx.advisoriesDiffs), so advisories runs first.
 const { REGRESSION_WATCHER_SOURCE } = require('./cve-regression-watcher');
 
 const ALL_SOURCES = {
@@ -937,29 +740,11 @@ const ALL_SOURCES = {
   'cve-regression-watcher': REGRESSION_WATCHER_SOURCE,
 };
 
-// --- Cache-mode helpers ------------------------------------------------
-// When `--from-cache <dir>` is set, the source modules read their inputs
-// from the prefetch cache instead of hitting upstream. The cache layout
-// is fixed by lib/prefetch.js:
-//   <cacheDir>/kev/known_exploited_vulnerabilities.json
-//   <cacheDir>/nvd/<cve>.json
-//   <cacheDir>/epss/<cve>.json
-//   <cacheDir>/rfc/<doc-name>.json
-//   <cacheDir>/pins/<owner__repo__releases>.json
-//
-// readCachedJson returns null on miss; callers report it as "unreachable"
-// for that entry rather than failing the whole source.
-
-// sha256 of on-disk cache entries is recorded in _index.json at fetch time
-// but was never verified on consume. A coordinated tamper that rewrote
-// e.g. `.cache/upstream/kev/known_exploited_vulnerabilities.json` between
-// prefetch and refresh would silently feed false intelligence into the
-// applied catalog. We now recompute the sha256 inside readCachedJson and
-// refuse on mismatch.
-//
-// The sha256 stored at prefetch time is computed over JSON.stringify(payload)
-// — unindented. The on-disk bytes use JSON.stringify(payload, null, 2)+"\n",
-// so we round-trip parse and re-canonicalize to compute the comparable hash.
+// Reads the prefetch cache lib/prefetch.js writes at <cacheDir>/<source>/<id>.json;
+// a miss returns null, so one entry is unreachable rather than the whole source.
+// Each payload's sha256 is recorded in _index.json at fetch time and verified here.
+// The stored hash is over unindented JSON.stringify(payload) while the on-disk
+// bytes are indented, so the parse round-trip re-canonicalizes before comparing.
 function readCachedJson(cacheDir, source, id, opts) {
   const forceStale = !!(opts && opts.forceStale);
   const safe = id.replace(/[^A-Za-z0-9._-]/g, "_");
@@ -968,13 +753,9 @@ function readCachedJson(cacheDir, source, id, opts) {
   let parsed;
   try { parsed = JSON.parse(fs.readFileSync(p, "utf8")); }
   catch { return null; }
-  // Look up the index entry. If the index is absent or doesn't have an
-  // entry for this source/id, we cannot verify integrity — refuse rather
-  // than fail-open. The cache invariant is: every payload on disk has a
-  // signed entry in _index.json. `--force-stale` is the operator escape
-  // hatch for pre-v0.12.24 caches that lack the per-entry sha256 records;
-  // we proceed without integrity checking but emit a warning so the gap
-  // is visible in logs.
+  // Every payload on disk has a signed entry in _index.json, so an absent index
+  // or a missing entry refuses rather than fails open. `--force-stale` proceeds
+  // unverified but warns.
   const indexPath = path.join(cacheDir, "_index.json");
   if (!fs.existsSync(indexPath)) {
     if (forceStale) {
@@ -1025,9 +806,7 @@ function readCachedJson(cacheDir, source, id, opts) {
   const cryptoMod = require("crypto");
   const actual = cryptoMod.createHash("sha256").update(JSON.stringify(parsed)).digest("hex");
   if (expected !== actual) {
-    // sha256 mismatch is a hard tamper signal — `--force-stale` does NOT
-    // bypass it. An operator who knows the cache is stale can re-prefetch;
-    // an operator whose cache has been tampered should not proceed.
+    // A hard tamper signal: `--force-stale` does NOT bypass it.
     const err = new Error(`cache-integrity: sha256 mismatch for ${source}/${id} (expected ${expected.slice(0, 16)}..., got ${actual.slice(0, 16)}...)`);
     err._exceptd_cache_integrity = true;
     err._exceptd_hint = true;
@@ -1037,11 +816,8 @@ function readCachedJson(cacheDir, source, id, opts) {
   return parsed;
 }
 
-// A curated entry carries strong human-curated exploitation signal when its
-// active_exploitation is confirmed/suspected, or it has a non-empty PoC
-// description / verification sources. A de-listing of such an entry is far
-// more likely a transient or incomplete upstream feed than a genuine CISA
-// removal, so it is surfaced for review rather than auto-applied.
+// Strong human-curated exploitation signal. A de-listing of such an entry is far
+// likelier a transient feed than a genuine CISA removal.
 function hasCuratedExploitSignal(entry) {
   if (!entry || typeof entry !== "object") return false;
   const ae = typeof entry.active_exploitation === "string" ? entry.active_exploitation.toLowerCase() : "";
@@ -1051,22 +827,15 @@ function hasCuratedExploitSignal(entry) {
   return false;
 }
 
-// A catalog entry is curator-owned (its CVSS is hand-verified, not an upstream
-// auto-import) unless it carries `_auto_imported: true`. An NVD CVSS re-score on
-// a curator-owned entry is surfaced for review rather than auto-applied — the
-// same principle as the curated-KEV de-listing guard above. The version-
-// downgrade guards already suppress a v3.x→v2 regression; this additionally
-// keeps a *same-version* NVD re-score (e.g. a curated 10.0 the maintainer pinned
-// dropping to NVD's 9.8) from silently overwriting the curated value. Raw
-// auto-imported drafts (`_auto_imported: true`) are not yet curated, so NVD is
-// their source of truth and their CVSS applies normally.
+// An entry is curator-owned — its CVSS hand-verified — unless it carries
+// `_auto_imported: true`. This keeps a same-version NVD re-score from overwriting
+// a curated value, where the version-downgrade guards cannot.
 function isCuratorOwnedCvss(entry) {
   return !!entry && typeof entry === "object" && entry._auto_imported !== true;
 }
 
-// Build an NVD CVSS diff, marking it review-only when the local entry is
-// curator-owned so applyDiff preserves the curated value while the report still
-// surfaces the upstream delta for a maintainer to accept deliberately.
+// Marks the diff review-only when the local entry is curator-owned: applyDiff
+// preserves the curated value while the report still surfaces the delta.
 function cvssDiff(id, field, before, after, severity, local) {
   const d = { id, field, before, after, severity };
   if (isCuratorOwnedCvss(local)) {
@@ -1077,18 +846,13 @@ function cvssDiff(id, field, before, after, severity, local) {
   return d;
 }
 
-// Below this many entries the cached KEV feed is treated as truncated /
-// incomplete rather than a genuine CISA snapshot. CISA KEV has carried well
-// over a thousand entries since 2021 and only grows; a feed this small means
-// a partial download or a tampered cache, and trusting it to de-list curated
-// entries would silently erase confirmed-exploitation intel. De-listings are
-// refused wholesale when the feed is implausibly small.
+// Below this many entries the KEV feed is a partial download or a tampered
+// cache, not a CISA snapshot — the real feed carries thousands. De-listings are
+// refused wholesale there.
 const KEV_FEED_MIN_PLAUSIBLE = 500;
 
-// The KEV fields both refresh paths reconcile. Named once so the live path and
-// the cache path cannot cover different subsets — which is exactly how the
-// deadline and the ransomware designation went unreconciled while the flag and
-// its date tracked upstream.
+// The KEV fields both refresh paths reconcile, named once so the live path and
+// the cache path cannot cover different subsets.
 const KEV_RECONCILED_FIELDS = new Set([
   "cisa_kev", "cisa_kev_date", "cisa_kev_due_date", "known_ransomware_use",
 ]);
@@ -1107,20 +871,16 @@ function kevDiffFromCache(ctx) {
       kevSet.add(v.cveID);
       if (v.dateAdded) kevDates.set(v.cveID, v.dateAdded);
       if (v.dueDate) kevDue.set(v.cveID, v.dueDate);
-      // Recorded ONLY for a value this code understands. An absent or
-      // unrecognised knownRansomwareCampaignUse must not be read as "Unknown":
-      // `String(undefined).toLowerCase() === "known"` is false, which would
-      // propose downgrading a curated true to false on the strength of a field
-      // the feed never carried. Absence is no answer, not a negative answer.
+      // Recorded ONLY for a value this code understands: absence is no answer,
+      // not a negative one, and a coerced miss would propose downgrading a
+      // curated true on a field the feed never carried.
       const r = typeof v.knownRansomwareCampaignUse === "string"
         ? v.knownRansomwareCampaignUse.trim().toLowerCase() : null;
       if (r === "known") kevRansom.set(v.cveID, true);
       else if (r === "unknown") kevRansom.set(v.cveID, false);
     }
   }
-  // An implausibly small feed cannot be trusted to de-list curated entries.
-  // First-listings (false→true) still flow — a small feed never invents new
-  // exploitation; only the de-list direction is suppressed.
+  // Only the de-list direction is suppressed; a small feed never invents a listing.
   const feedComplete = kevSet.size >= KEV_FEED_MIN_PLAUSIBLE;
   const diffs = [];
   for (const [id, entry] of Object.entries(ctx.cveCatalog)) {
@@ -1128,13 +888,8 @@ function kevDiffFromCache(ctx) {
     const upstream = kevSet.has(id);
     if (typeof entry.cisa_kev === "boolean" && entry.cisa_kev !== upstream) {
       const isDelist = entry.cisa_kev === true && upstream === false;
-      // Symmetric with the NVD path's curated-downgrade guard: never silently
-      // regress curated exploitation intel against an upstream that disagrees.
-      // A de-listing of a curated entry with strong exploitation signal, OR
-      // any de-listing when the feed is implausibly small, is re-tagged as a
-      // review-only diff — surfaced in the report so a maintainer confirms a
-      // genuine CISA removal, but NOT auto-applied (applyDiff skips
-      // review_only diffs, leaving cisa_kev / rwep / dates intact).
+      // A de-listing of an entry with strong exploitation signal, or any against
+      // an implausibly small feed, is review-only: applyDiff skips those.
       if (isDelist && (!feedComplete || hasCuratedExploitSignal(entry))) {
         diffs.push({
           id,
@@ -1153,42 +908,29 @@ function kevDiffFromCache(ctx) {
       }
     }
     const upDate = kevDates.get(id) || null;
-    // First listings arrive with a null local date — emit the date diff
-    // whenever upstream has one that the local entry lacks or contradicts,
-    // so the flag flip and its listing date apply together (the strict
-    // catalog validator requires KEV-listed entries to carry the date).
+    // The flag flip and its listing date apply together — the strict validator
+    // requires the date on a KEV-listed entry.
     if (upDate && (entry.cisa_kev_date || null) !== upDate) {
       diffs.push({ id, field: "cisa_kev_date", before: entry.cisa_kev_date ?? null, after: upDate, severity: "low" });
     }
 
-    // CISA edits a listing after publishing it. The remediation deadline and
-    // the ransomware designation both move that way, and neither was compared
-    // here — so an entry curated on the day of listing kept whatever those
-    // fields held then, indefinitely, while every other KEV field tracked the
-    // feed. Only entries upstream still lists are considered; a de-listing
-    // clears both fields through the cisa_kev branch above.
+    // CISA edits a listing after publishing it, moving the deadline and the
+    // ransomware designation. Only entries upstream still lists are considered —
+    // a de-listing clears both fields through the cisa_kev branch above.
     if (upstream) {
       const upDue = kevDue.get(id) || null;
-      // The deadline is rendered into remediation output and regulator drafts,
-      // so a stale one states a date CISA does not require. It is not decoration
-      // and its severity says so.
+      // The deadline is rendered into remediation output and regulator drafts.
       if (upDue && (entry.cisa_kev_due_date || null) !== upDue) {
         diffs.push({ id, field: "cisa_kev_due_date", before: entry.cisa_kev_due_date ?? null, after: upDue, severity: "medium" });
       }
       const upRansom = kevRansom.has(id) ? kevRansom.get(id) : null;
-      // An entry that omits the field is not asserting anything, but every
-      // consumer reads a missing boolean as false — so an omission on an entry
-      // CISA has since designated is read as "no ransomware association", which
-      // is the wrong answer rather than no answer. For a KEV-listed CVE the
-      // value is a restatement of the feed and carries no curator judgment, so
-      // it is filled from upstream in both directions and the field becomes
-      // total across KEV-listed entries instead of sometimes-absent.
+      // Consumers read a missing boolean as false, so an omission reads as "no
+      // ransomware association" — the wrong answer rather than no answer. On a
+      // KEV-listed CVE the value restates the feed, so it fills both directions.
       const localRansom = typeof entry.known_ransomware_use === "boolean" ? entry.known_ransomware_use : null;
       if (upRansom !== null && localRansom !== upRansom) {
-        // Same asymmetry as the de-list guard: a designation being ADDED is
-        // upstream telling us something new, while one being REMOVED against an
-        // implausibly small feed is the feed failing to tell us anything. Hold
-        // the removal for review rather than erasing a curated designation.
+        // An ADDED designation is upstream saying something new; one REMOVED
+        // against an implausibly small feed is the feed saying nothing.
         const removing = localRansom === true && upRansom === false;
         const d = { id, field: "known_ransomware_use", before: localRansom, after: upRansom, severity: "medium" };
         if (removing && !feedComplete) {
@@ -1210,11 +952,9 @@ function epssDiffFromCache(ctx) {
   for (const id of cves) {
     const payload = readCachedJson(ctx.cacheDir, "epss", id, { forceStale: ctx.forceStale });
     if (!payload) { errors++; continue; }
-    // Match the EPSS row by id. The old `|| data[0]` blanket fallback
-    // attributed a DIFFERENT CVE's score to this id whenever the cache entry
-    // keyed under `id` actually held another CVE's payload. Accept the
-    // single-row fallback ONLY when that row carries no cve key (a keyless
-    // legacy payload), never a row naming a different CVE.
+    // Match the row by id: a blanket `|| data[0]` fallback attributes another
+    // CVE's score to this id. The single-row fallback holds only for a keyless
+    // payload, never for a row naming a different CVE.
     let row = (payload.data || []).find((r) => r?.cve === id);
     if (!row && (payload.data || []).length === 1 && (payload.data || [])[0]?.cve == null) row = (payload.data || [])[0];
     if (!row) continue;
@@ -1236,27 +976,20 @@ function nvdDiffFromCache(ctx) {
   for (const id of cves) {
     const payload = readCachedJson(ctx.cacheDir, "nvd", id, { forceStale: ctx.forceStale });
     if (!payload) { errors++; continue; }
-    // Resolve the NVD vuln by id, not by position. vulnerabilities[0] blindly
-    // took the first record, attributing a DIFFERENT CVE's CVSS to this id when
-    // the cache entry keyed under `id` held another CVE's response.
+    // Resolve the NVD vuln by id, not by position: vulnerabilities[0] attributes
+    // another CVE's CVSS to this id.
     const vulnCves = (payload.vulnerabilities || []).map((v) => v?.cve).filter(Boolean);
     let vuln = vulnCves.find((c) => c.id && String(c.id).toUpperCase() === id.toUpperCase());
-    // Keyless single-record fallback: a single vulnerability whose cve carries
-    // no id can't be a mismatch — the id-keyed cache file IS the binding — so
-    // use it. A record whose id names a DIFFERENT cve is still rejected.
+    // A single record whose cve carries no id cannot be a mismatch — the
+    // id-keyed cache file is the binding. One naming a DIFFERENT cve is not.
     if (!vuln && vulnCves.length === 1 && vulnCves[0].id == null) vuln = vulnCves[0];
     if (!vuln) continue;
-    // Prefer the newest CVSS version NVD publishes (Primary within that
-    // version), and normalize a bare v2 vector to its canonical prefix.
     const up = selectNvdCvss(vuln.metrics);
     if (!up) continue;
     const local = ctx.cveCatalog[id];
-    // Never regress a curated higher-version CVSS to an older upstream metric.
-    // NVD keeps many pre-2016 CVEs at v2 only (or tags v2 "Primary" over a
-    // v3.1 "Secondary"); the catalog has been curated to v3.1. When the
-    // selected upstream metric is an older CVSS version than the curated one,
-    // suppress both the score and the vector diff. A same-version drift (a
-    // genuine NVD re-score) still flows through.
+    // Never regress a curated higher-version CVSS to an older upstream metric:
+    // NVD tags v2 "Primary" over a v3.1 "Secondary" on older CVEs. A same-version
+    // drift still flows through.
     const localVersion = cvssVersionOf(local.cvss_vector);
     const isDowngrade =
       up.version != null && localVersion != null && up.version < localVersion;
@@ -1302,14 +1035,9 @@ function rfcDiffFromCache(ctx) {
 }
 
 function pinsDiffFromCache(ctx) {
-  // Cache layout under pins/: <owner>__<repo>__releases.json arrays.
-  // Only repos that publish via GitHub Releases live here — D3FEND and CWE
-  // were removed in the same pass that pruned them from lib/prefetch.js's
-  // SOURCES.pins (neither project tags releases on GitHub; D3FEND ships
-  // the ontology from d3fend/d3fend-ontology without tagged releases,
-  // and CWE distributes XML from cwe.mitre.org). Pin currency for those
-  // two frameworks is monitored via lib/upstream-check.js against their
-  // canonical mitre.org endpoints, not through the prefetch cache.
+  // Cache layout under pins/: <owner>__<repo>__releases.json arrays, so only
+  // repos publishing via GitHub Releases appear. D3FEND and CWE tag none;
+  // lib/upstream-check.js monitors their pin currency against mitre.org instead.
   const PIN_REPOS = {
     atlas_version:  "mitre-atlas__atlas-data__releases",
     attack_version: "mitre-attack__attack-stix-data__releases",
@@ -1346,12 +1074,8 @@ function pinsDiffFromCache(ctx) {
   return { status, diffs, errors, summary: `${diffs.length} pin drifts (from cache); ${errors} missing entries` };
 }
 
-// --- Fixture-mode helper ----------------------------------------------
-
 function synthesizeFromFixture(ctx, sourceName) {
-  // The frozen fixture payloads are JSON files that look like:
-  //   { diffs: [...], errors: 0, summary: "..." }
-  // tests/fixtures/refresh/<sourceName>.json drives this path.
+  // tests/fixtures/refresh/<sourceName>.json holds { diffs, errors, summary }.
   const fp = path.join(ctx.fixtures.dir, `${sourceName}.json`);
   if (!fs.existsSync(fp)) {
     return { status: "ok", diffs: [], errors: 0, summary: `${sourceName}: no fixture` };
@@ -1365,8 +1089,6 @@ function synthesizeFromFixture(ctx, sourceName) {
   };
 }
 
-// --- IO helpers --------------------------------------------------------
-
 function loadCtx(opts) {
   const cvePath = resolveCatalogPath(opts);
   const ctx = {
@@ -1378,28 +1100,17 @@ function loadCtx(opts) {
     d3fendCatalog: JSON.parse(fs.readFileSync(ABS("data/d3fend-catalog.json"), "utf8")),
     fixtures: null,
     cacheDir: null,
-    // Thread --air-gap (or EXCEPTD_AIR_GAP=1) through to ctx.airGap so the
-    // GHSA + OSV source modules (lib/source-ghsa.js, lib/source-osv.js)
-    // branch on it and refuse network egress.
+    // Reaches lib/source-ghsa.js and lib/source-osv.js, which refuse egress on it.
     airGap: !!(opts && opts.airGap) || process.env.EXCEPTD_AIR_GAP === "1",
-    // Thread --force-stale through so readCachedJson can downgrade cache-
-    // integrity refusals to warnings when an operator explicitly opts out.
+    // Lets readCachedJson downgrade cache-integrity refusals to warnings.
     forceStale: !!(opts && opts.forceStale),
-    // `--drift-only` keeps a refresh to the entries the catalog already holds.
-    // Discovery and drift answer different questions — "what is upstream that
-    // we lack" against "what have we got that upstream has since changed" — and
-    // an operator correcting the second does not necessarily want the first,
-    // because a discovered entry arrives as a draft that has to be curated
-    // before it can ship. Bundling them forces a choice between leaving known
-    // fields stale and importing work that is not ready.
+    // Discovery yields drafts that need curation before they can ship, so
+    // drift-only reconciles shipped entries without pulling that work in.
     driftOnly: !!(opts && opts.driftOnly),
   };
   if (opts.fromFixture) {
-    // `--from-fixture` injects frozen test payloads as if they were live
-    // upstream responses. Allowing this on an operator's host would let any
-    // caller forge KEV / NVD / EPSS / pin diffs into the applied catalog.
-    // Gate the flag behind EXCEPTD_TEST_HARNESS=1 so it only activates in
-    // explicit test contexts.
+    // `--from-fixture` injects payloads as if they were live upstream responses,
+    // so outside the harness it would forge diffs into the applied catalog.
     if (process.env.EXCEPTD_TEST_HARNESS !== "1") {
       const err = new Error(
         `refresh: --from-fixture is disabled outside the test harness.\n` +
@@ -1412,14 +1123,7 @@ function loadCtx(opts) {
     }
     const fixtureDir = path.resolve(opts.fromFixture);
     ctx.fixtures = { dir: fixtureDir, kev: true, epss: true, nvd: true, rfc: true, pins: true, ghsa: true, osv: true };
-    // v0.13.7: load tests/fixtures/refresh/advisories.json into
-    // ctx.fixtures.advisories so the advisory poller (Qualys / RHSA / USN /
-    // ZDI / kernel.org / oss-security / JFrog / CISA) uses frozen content
-    // instead of falling through to live RSS. Prior to this load, two
-    // back-to-back fixture-mode runs (e.g. sequential vs `--swarm`) hit
-    // the real-world feeds at different moments and diverged on Pwn2Own /
-    // Trend Micro / ZDI advisories rotated within the window — surfaced as
-    // a CI flake on macOS runners where the test took longer to complete.
+    // Frozen advisories keep the poller off live RSS, which rotates between runs.
     const advFixPath = path.join(fixtureDir, "advisories.json");
     if (fs.existsSync(advFixPath)) {
       try {
@@ -1437,12 +1141,6 @@ function loadCtx(opts) {
     const abs = path.resolve(opts.fromCache);
     ctx.cacheDir = abs;
     if (!fs.existsSync(abs)) {
-      // Operators following the air-gap workflow hit this with an unhelpful
-      // "path does not exist" stack trace. The cache is populated by
-      // `exceptd refresh --prefetch` (which routes to prefetch) — NOT by
-      // `--no-network`, which is the report-only dry run that writes nothing.
-      // Tell them exactly that, and emit a structured JSON error to stderr
-      // instead of a fatal stack trace.
       const err = new Error(
         `refresh: --from-cache path does not exist: ${abs}\n` +
         `Hint: the cache is populated by running \`exceptd refresh --prefetch\` ` +
@@ -1452,12 +1150,8 @@ function loadCtx(opts) {
       err._exceptd_hint = true;
       throw err;
     }
-    // _index.json signature verification. The cache was signed at
-    // prefetch time with the Ed25519 private key. Refuse to consume any
-    // cache whose sidecar signature does not verify against keys/public.pem,
-    // unless the operator explicitly accepts the risk via --force-stale.
-    // A missing sidecar (cache prefetched on a host without the signing
-    // keypair) is treated identically: same refusal, same override.
+    // The cache is Ed25519-signed at prefetch time; a sidecar that does not
+    // verify against keys/public.pem, or is missing, is refused alike.
     try {
       const { verifyIndexSignature } = require("./prefetch.js");
       const sigResult = verifyIndexSignature(abs);
@@ -1474,9 +1168,7 @@ function loadCtx(opts) {
       }
     } catch (e) {
       if (e && e._exceptd_hint) throw e;
-      // Loader error (prefetch.js missing exports, etc.) — treat as a hard
-      // refusal rather than fail-open. Operators on --force-stale still
-      // pass through.
+      // A loader error is a hard refusal, not a fail-open.
       if (!opts.forceStale) {
         const err = new Error(
           `refresh: --from-cache signature verifier unavailable: ${e && e.message}.\n` +
@@ -1488,10 +1180,8 @@ function loadCtx(opts) {
         throw err;
       }
     }
-    // Max-age check. Cache entries whose freshest fetched_at is older
-    // than 7 days are refused outright; intel that stale is more likely
-    // to be misleading than helpful (KEV gains entries weekly; EPSS shifts
-    // daily). --force-stale overrides for genuine air-gap workflows.
+    // A cache whose freshest fetched_at is older than 7 days is refused: KEV
+    // gains entries weekly and EPSS shifts daily.
     try {
       const idxPath = path.join(abs, "_index.json");
       if (fs.existsSync(idxPath)) {
@@ -1521,7 +1211,6 @@ function loadCtx(opts) {
       }
     } catch (e) {
       if (e && e._exceptd_hint) throw e;
-      // Index parse error — bubble up as a hint
       const err = new Error(`refresh: --from-cache _index.json unreadable: ${e && e.message}`);
       err._exceptd_hint = true;
       err._exceptd_exit_code = 4;
@@ -1531,18 +1220,14 @@ function loadCtx(opts) {
   return ctx;
 }
 
-// v0.12.12 C4: every persisted JSON write goes through writeJsonAtomic — a
-// tmp + rename pattern. fs.renameSync is atomic on POSIX and on Windows for
-// same-volume renames (which a `.tmp.<pid>.<rand>` adjacent to the target
-// always satisfies). A concurrent reader either sees the prior file content
-// in full or the new content in full — never a half-written buffer. The
-// tmp name carries pid + random so two writers in the same process (e.g.
-// worker threads) never collide on the same scratch path.
+// Every persisted JSON write goes through here. fs.renameSync is atomic for a
+// `.tmp.<pid>.<rand>` beside the target, so a concurrent reader sees the old
+// file or the new one, never a half-written buffer; the pid + random keeps two
+// writers in one process off the same scratch path.
 function writeJsonAtomic(p, obj) {
   const tmpPath = `${p}.tmp.${process.pid}.${Math.random().toString(36).slice(2, 10)}`;
-  // v0.13.0: fsync the tmp file before rename so a power loss between
-  // write and rename leaves the durable destination intact. See the
-  // matching helper in lib/cve-curation.js for the rationale.
+  // fsync before the rename so a power loss between the two leaves the durable
+  // destination intact. Matching helper in lib/cve-curation.js.
   const fd = fs.openSync(tmpPath, 'w');
   try {
     fs.writeSync(fd, JSON.stringify(obj, null, 2) + "\n", 0, "utf8");
@@ -1558,39 +1243,18 @@ function writeJsonAtomic(p, obj) {
   }
 }
 
-// Back-compat alias — exported callers and historical sites still reference
-// writeJson. Atomic by default; never the unsafe direct-write form.
 function writeJson(p, obj) {
   writeJsonAtomic(p, obj);
 }
 
 /**
- * v0.12.12 C1: lockfile-gated read-modify-write helper for JSON catalogs.
+ * Lockfile-gated read-modify-write for a JSON catalog: a sidecar lockfile
+ * (O_EXCL via `flag: 'wx'`) serializes the triple, so two concurrent
+ * `--advisory <id> --apply` processes cannot drop one another's CVE.
  *
- * Two concurrent `refresh --advisory CVE-A --apply` and
- * `refresh --advisory CVE-B --apply` processes against the same catalog used
- * to race: each read the catalog, mutated its in-memory copy, then wrote —
- * the second write overwrote the first, silently dropping one CVE. The fix
- * is a sidecar lockfile (created with O_EXCL via `flag: 'wx'`) that
- * serializes the read-mutate-write triple. The mutator receives the
- * current-on-disk catalog (re-read inside the lock, NOT a stale in-memory
- * copy from before lock acquisition) and returns it after mutation; the
- * helper then writes atomically via writeJsonAtomic.
- *
- * Stale-lock recovery: if a holder crashes without unlinking, the lockfile
- * persists. After backoff, if the lockfile's mtime is older than 30s we
- * treat it as orphaned and unlink it before retrying. 30s is well past any
- * legitimate single-CVE apply (sub-second on modern disks).
- *
- * On acquisition failure after N retries, we throw — better than silently
- * proceeding without the lock.
- *
- * @param {string} catalogPath  path to the JSON catalog to lock
- * @param {(catalog: object) => object | Promise<object>} mutator
- *        receives current-on-disk catalog, returns mutated catalog. May be
- *        async. The return value is what gets written; if it returns
- *        undefined, the in-place mutation of the passed-in catalog is used.
- * @returns {Promise<{ wrote: boolean, result: any }>}
+ * The mutator, which may be async, receives the catalog as re-read INSIDE the
+ * lock — never a copy from before acquisition — and returns the object to
+ * write; returning undefined writes its in-place mutation instead.
  */
 async function withCatalogLock(catalogPath, mutator) {
   const lockPath = `${catalogPath}.lock`;
@@ -1603,20 +1267,12 @@ async function withCatalogLock(catalogPath, mutator) {
       acquired = true;
       break;
     } catch (e) {
-      // EEXIST is the POSIX signal another process holds the lock. On
-      // Windows the same race surfaces as EPERM (sharing-violation raised
-      // when the holder is mid-unlink). Treat both as "lock held, back off."
+      // EEXIST is the POSIX signal that another process holds the lock; Windows
+      // raises EPERM when the holder is mid-unlink. Both mean held, so back off.
       if (e.code !== "EEXIST" && e.code !== "EPERM") throw e;
-      // PID-liveness check before falling back to mtime. The lockfile
-      // contains String(process.pid) of the holder; parse it and probe with
-      // `process.kill(pid, 0)`. ESRCH means the holder is dead — reclaim
-      // immediately rather than waiting STALE_LOCK_MS for the mtime gate
-      // to expire. EPERM (holder alive, different user) is treated as
-      // "alive, keep waiting." The mtime gate remains as a belt-and-
-      // suspenders for cases where the lockfile content is missing /
-      // malformed / belongs to a recycled PID. Matches the PID pattern in
-      // orchestrator/index.js _acquireWatchLock and
-      // lib/playbook-runner.js pidAlive().
+      // Probe the holder PID before falling back to mtime: ESRCH means dead, so
+      // reclaim now instead of waiting out STALE_LOCK_MS; EPERM means alive under
+      // another user. Same pattern as orchestrator/index.js _acquireWatchLock.
       let reclaimedByPid = false;
       try {
         const raw = fs.readFileSync(lockPath, "utf8").trim();
@@ -1634,8 +1290,7 @@ async function withCatalogLock(catalogPath, mutator) {
         }
       } catch {} // unreadable lockfile — proceed to mtime fallback
       if (reclaimedByPid) continue;
-      // Stale-lock check before sleeping — a long-dead holder shouldn't keep
-      // us waiting MAX_RETRIES * backoff before we recover.
+      // Check for a dead holder before sleeping out MAX_RETRIES * backoff.
       try {
         const stat = fs.statSync(lockPath);
         if (Date.now() - stat.mtimeMs > STALE_LOCK_MS) {
@@ -1661,11 +1316,8 @@ async function withCatalogLock(catalogPath, mutator) {
 }
 
 function chosenSources(opts) {
-  // Flag-absent (opts.source == null) means "all sources" — the default
-  // refresh behavior. Flag-present-but-empty (`--source ""`, or a value that
-  // trims to nothing like `--source ","`) is an operator error, not a
-  // silent run-everything: refuse and list the valid names so the typo is
-  // visible rather than masquerading as a full refresh.
+  // Flag-absent means "all sources"; flag-present-but-empty (`--source ""`,
+  // `--source ","`) is an operator error, not a silent run-everything.
   if (opts.source == null) return Object.values(ALL_SOURCES);
   const names = opts.source.split(",").map((s) => s.trim()).filter(Boolean);
   if (names.length === 0) {
@@ -1676,10 +1328,8 @@ function chosenSources(opts) {
   const out = [];
   for (const n of names) {
     if (!ALL_SOURCES[n]) {
-      // v0.12.12 C3: previously `process.exit(2)` after a console.error.
-      // Stdout writes elsewhere in this run could truncate; throwing lets
-      // main().catch() surface the error through the standard channel and
-      // exit code via process.exitCode + natural event-loop drain.
+      // Throw rather than process.exit(): an exit can truncate a buffered stdout
+      // write, so main().catch() sets process.exitCode and the loop drains.
       const err = new Error(`refresh-external: unknown source "${n}". Valid: ${Object.keys(ALL_SOURCES).join(", ")}`);
       err._exceptd_unknown_source = true;
       throw err;
@@ -1690,21 +1340,12 @@ function chosenSources(opts) {
 }
 
 /**
- * v0.12.0: single-advisory seed. Operator types
- *   exceptd refresh --advisory CVE-2026-45321
- * or
- *   exceptd refresh --advisory GHSA-xxxx-xxxx-xxxx --apply
- *
- * Tool fetches from GHSA (covers npm, PyPI, etc.), normalizes to the
- * exceptd catalog draft shape, and either prints the seed (default) or
- * writes it to data/cve-catalog.json (--apply). Always exits non-zero
- * when a draft is produced, signaling that editorial review is needed.
+ * Seeds one catalog entry from an advisory id via GHSA or OSV, printing the
+ * draft or writing it (--apply). A produced draft exits 3 — review pending.
  */
 async function seedSingleAdvisory(opts) {
   const id = opts.advisory;
-  // v0.12.10: route OSV-native ids (MAL-*, SNYK-*, RUSTSEC-*, USN-*, etc.)
-  // through source-osv. CVE-* and GHSA-* keep routing through GHSA because
-  // GHSA carries richer field coverage for those identifier shapes.
+  // OSV-native ids route through source-osv; CVE-* and GHSA-* go to GHSA.
   const osvMod = require("./source-osv");
   const useOsv = osvMod.isOsvId(id) && !/^GHSA-/i.test(id);
   const ghsa = require("./source-ghsa");
@@ -1712,18 +1353,12 @@ async function seedSingleAdvisory(opts) {
   const sourceName = useOsv ? "osv" : "ghsa";
   const fixtureEnv = useOsv ? "EXCEPTD_OSV_FIXTURE" : "EXCEPTD_GHSA_FIXTURE";
 
-  // Thread the air-gap disposition (the --air-gap flag OR EXCEPTD_AIR_GAP=1)
-  // into the fetch. Previously this passed {} and dropped --air-gap, so
-  // `refresh --advisory <id> --air-gap` egressed to the network — an air-gap
-  // violation. Both source modules refuse (no fixture) when airGap is set.
+  // The air-gap disposition must reach the fetch; dropping it here egresses.
   const airGap = !!opts.airGap || process.env.EXCEPTD_AIR_GAP === "1";
 
   let result = await sourceMod.fetchAdvisoryById(id, { airGap });
-  // F4 (v0.12.11): CVE-* identifiers may have an OSV record before GHSA
-  // publishes one (CNAs and OSV mirrors operate on different cadences).
-  // When GHSA returns 404 specifically, retry through OSV's /v1/vulns/{id}
-  // — OSV indexes CVE ids as primary keys. If both 404, surface a combined
-  // error message so operators know both sources were tried before failing.
+  // A CVE-* id can have an OSV record before GHSA publishes one, so a GHSA 404
+  // retries through OSV's /v1/vulns/{id}. When both 404 the error names both.
   let fallbackSourceUsed = null;
   if (!result.ok && !useOsv && /^CVE-/i.test(id) && /HTTP 404/.test(result.error || "")) {
     const fallback = await osvMod.fetchAdvisoryById(id, { airGap });
@@ -1731,7 +1366,6 @@ async function seedSingleAdvisory(opts) {
       result = fallback;
       fallbackSourceUsed = "osv";
     } else if (/HTTP 404/.test(fallback.error || "") || /not in fixture/.test(fallback.error || "")) {
-      // Both sources tried, both 404 — combine the error message.
       const combined = { ok: false, verb: "refresh", error: `--advisory ${id}: not found in GHSA or OSV (GHSA: ${result.error}; OSV: ${fallback.error})`, source: "offline", routed_to: "ghsa+osv", hint: `Both GHSA and OSV.dev returned 404 for ${id}. Verify the CVE id (CVE-YYYY-NNNN) and that an advisory record exists upstream.` };
       if (opts.json) process.stdout.write(JSON.stringify(combined) + "\n");
       else process.stderr.write(`[refresh --advisory] ${combined.error}\n  hint: ${combined.hint}\n`);
@@ -1746,8 +1380,7 @@ async function seedSingleAdvisory(opts) {
     process.exitCode = 2;
     return;
   }
-  // If the OSV fallback fired, normalize/route through the OSV module from
-  // here on — the advisory shape is OSV's, not GHSA's.
+  // After an OSV fallback the advisory shape is OSV's, so normalize through it.
   const effectiveMod = fallbackSourceUsed === "osv" ? osvMod : sourceMod;
   const effectiveName = fallbackSourceUsed === "osv" ? "osv" : sourceName;
   const advisory = result.advisories[0];
@@ -1769,8 +1402,6 @@ async function seedSingleAdvisory(opts) {
   const cveId = Object.keys(normalized)[0];
 
   if (!opts.apply) {
-    // Print the draft to stdout — operator pipes to jq / inspects /
-    // commits manually. Exit 3 = "draft produced, not applied."
     const output = {
       ok: true,
       verb: "refresh",
@@ -1790,18 +1421,12 @@ async function seedSingleAdvisory(opts) {
     return;
   }
 
-  // Apply: write to cve-catalog.json with the _auto_imported flag.
-  // v0.12.8: honor --catalog / EXCEPTD_CVE_CATALOG so tests can redirect.
-  // v0.12.12 C1: lock-gated RMW. Without this, two concurrent
-  // `refresh --advisory CVE-A --apply` + `--advisory CVE-B --apply`
-  // processes against the same catalog silently dropped one CVE 1-in-20
-  // trials (read-old → mutate → write-overwrites-sibling-mutation).
   const catalogPath = resolveCatalogPath(opts);
   let humanCurated = null;
   await withCatalogLock(catalogPath, (catalog) => {
     if (catalog[cveId] && !catalog[cveId]._auto_imported && !catalog[cveId]._draft) {
-      // Refuse to overwrite a human-curated entry — signal via closure so
-      // we can emit the structured error after the lock releases.
+      // Refuse to overwrite a human-curated entry; signalled through the closure
+      // so the structured error emits after the lock releases.
       humanCurated = { last_updated: catalog[cveId].last_updated };
       return catalog; // unchanged write — idempotent, releases lock
     }
@@ -1831,8 +1456,6 @@ async function seedSingleAdvisory(opts) {
   process.exitCode = 3;
 }
 
-// Known --flag base names refresh accepts (operator-facing surface + the
-// bin-translated aliases). Drives the unknown-flag error message's known list.
 const REFRESH_KNOWN_FLAGS = Object.freeze([
   "--apply", "--quiet", "--swarm", "--json", "--help", "-h", "--advisory",
   "--check-advisories", "--catalog", "--from-cache", "--source", "--from-fixture",
@@ -1844,14 +1467,13 @@ async function main() {
   const opts = parseArgs(process.argv);
   if (opts.help) {
     printHelp();
-    // v0.12.12 C3: exitCode + return so buffered stdout flushes naturally.
+    // exitCode + return, not process.exit() — buffered stdout must flush.
     process.exitCode = 0;
     return;
   }
 
-  // Reject unknown flags BEFORE any network / catalog work. A swallowed typo
-  // (e.g. `--aply`) previously fell through to a default all-sources live
-  // refresh. Exit 2 matches refresh's own scheme (2 = error / unknown source).
+  // Reject unknown flags BEFORE any network or catalog work: a swallowed typo
+  // (`--aply`) otherwise falls through to a default all-sources live refresh.
   if (Array.isArray(opts._unknownFlags) && opts._unknownFlags.length > 0) {
     const uniq = [...new Set(opts._unknownFlags)];
     process.stderr.write(JSON.stringify({
@@ -1865,23 +1487,12 @@ async function main() {
     return;
   }
 
-  // `--prefetch` / `--no-network` are prefetch-cache operations. The operator
-  // path (bin/exceptd.js) routes them to lib/prefetch.js; when this script is
-  // invoked directly, delegate the SAME way so behavior matches the help text:
-  // --prefetch populates the cache, --no-network is a report-only dry run that
-  // writes nothing. Without this, the direct path fell through to the live
-  // refresh loop and could egress + write refresh-report.json despite
-  // --no-network.
+  // Cache operations delegate to lib/prefetch.js exactly as bin/exceptd.js does,
+  // so the direct path cannot egress and write a report despite --no-network.
   if (opts.prefetch || opts.noNetwork) {
-    // Validate --source against the prefetchable (cache-backed) subset BEFORE
-    // delegating to prefetch.js. prefetch.js only knows kev/nvd/epss/rfc/pins;
-    // the refresh-only sources (ghsa, osv, advisories, cve-regression-watcher)
-    // resolve advisories by live id lookup and have no cache layer. Without
-    // this guard, `refresh --prefetch --source osv` reached prefetch.js and
-    // died with `prefetch: fatal: unknown source "osv"` — leaking the internal
-    // verb name (the operator typed `refresh`) and calling a source "unknown"
-    // that the refresh help just listed as valid. Emit a refresh-prefixed,
-    // actionable message instead and forward only the cacheable subset.
+    // prefetch.js knows only kev/nvd/epss/rfc/pins; the refresh-only sources
+    // resolve by live id lookup and would die there as "unknown source", calling
+    // a source unknown that the refresh help lists as valid.
     const PREFETCHABLE = new Set(["kev", "nvd", "epss", "rfc", "pins"]);
     let forwardSource = opts.source;
     if (opts.source) {
@@ -1927,13 +1538,8 @@ async function main() {
     return;
   }
 
-  // v0.12.0: `--advisory <id>` short-circuits the normal source loop and
-  // seeds a single CVE catalog entry from GHSA. Exits non-zero ("draft
-  // written, please review") so CI pipelines surface the needed editorial
-  // step. Operator must run `--apply` for the write to land; without it,
-  // the seed is printed to stdout for review.
-  // An empty --advisory value (`--advisory ""` / `--advisory=`) must error
-  // rather than silently falling through to a full-refresh dry-run.
+  // `--advisory <id>` short-circuits the source loop. An empty value must error
+  // rather than falling through to a full-refresh dry run.
   if (opts.advisory != null && opts.advisory.trim() === "") {
     process.stderr.write(JSON.stringify({
       ok: false,
@@ -1966,17 +1572,11 @@ async function main() {
 
   let hadFailure = false;
 
-  // Source fetches are independently I/O-bound. In normal mode we run them
-  // sequentially so log output is interleaved cleanly. --swarm fans them
-  // out via Promise.all() — each source already has its own per-source
-  // queue with its own rate budget, so parallel sources don't compete
-  // against each other for tokens. The two modes produce the same report
-  // structure; only wall-clock differs.
+  // Sequential keeps log output interleaved cleanly; --swarm fans the sources
+  // out through Promise.all. Both modes produce the same report structure.
   const runOne = async (src) => {
-    // Audit 3 A.1: --air-gap was honored by GHSA/OSV at the source-module
-    // level, but kev/epss/nvd/rfc/pins fell through to their live-network
-    // branches when neither fixtures nor cacheDir was wired up. Refuse
-    // here so the air-gap guarantee holds uniformly across every source.
+    // GHSA and OSV honour --air-gap at the module level, but kev/epss/nvd/rfc/
+    // pins fall through to their live branches without fixtures or a cacheDir.
     if (ctx.airGap && !ctx.fixtures?.[src.name] && !ctx.cacheDir) {
       return {
         src,
@@ -1998,12 +1598,9 @@ async function main() {
     return { src, diff };
   };
 
-  // NEW-CTRL-074 chaining. cve-regression-watcher consumes the advisories
-  // source's per-feed CVE observations (preferred — includes in-catalog
-  // historical IDs the annotate verdict needs) and falls back to its diffs.
-  // The orchestrator otherwise runs every source independently and only
-  // persists outputs into the report, never back onto ctx — so without this
-  // thread the watcher always sees empty input and emits zero candidates.
+  // cve-regression-watcher consumes the advisories source's per-feed CVE
+  // observations — they carry the in-catalog historical IDs the annotate verdict
+  // needs — falling back to its diffs. Nothing else writes source output onto ctx.
   const threadAdvisoriesIntoCtx = (src, diff) => {
     if (src && src.name === "advisories" && diff && !diff.air_gap_blocked) {
       if (Array.isArray(diff.observations)) ctx.advisoriesObservations = diff.observations;
@@ -2013,8 +1610,7 @@ async function main() {
 
   let outcomes;
   if (!opts.swarm) {
-    // Sequential: thread the advisories output onto ctx the instant it
-    // resolves, BEFORE the next source's fetchDiff(ctx) is invoked.
+    // Thread onto ctx as it resolves, BEFORE the next source's fetchDiff(ctx).
     outcomes = [];
     for (const src of sources) {
       const outcome = await runOne(src);
@@ -2022,13 +1618,9 @@ async function main() {
       outcomes.push(outcome);
     }
   } else {
-    // --swarm: advisories and the watcher race when run via the same
-    // Promise.all, so chaining via shared ctx cannot work. Split the
-    // watcher into a second pass: run every other source in parallel,
-    // thread the resolved advisories observations onto ctx, then run the
-    // watcher. If advisories is NOT also selected, the watcher runs in the
-    // first batch like any other source (its empty-input contract is the
-    // operator's choice, not a silent race).
+    // Chaining through shared ctx cannot work inside one Promise.all, so the
+    // watcher runs in a second pass. With advisories unselected it joins the
+    // first batch — empty input is then the operator's choice, not a race.
     const hasAdvisories = sources.some((s) => s.name === "advisories");
     const watcher = hasAdvisories
       ? sources.find((s) => s.name === "cve-regression-watcher")
@@ -2046,12 +1638,9 @@ async function main() {
     }
   }
 
-  // Cache-integrity refusals (sha256 mismatch, missing/partial _index.json,
-  // unindexed payload) are thrown by readCachedJson with _exceptd_exit_code=4
-  // but caught inside runOne and returned as a per-source error — so the
-  // throw never reaches main().catch where the code is otherwise honored.
-  // Carry the marker through here so main() can prefer exit 4 (BLOCKED /
-  // precondition refusal) over the generic per-source-failure exit 1.
+  // runOne catches readCachedJson's cache-integrity refusals as per-source
+  // errors, so _exceptd_exit_code=4 never reaches main().catch. Carry the marker
+  // so exit 4 (precondition refusal) wins over the generic per-source failure 1.
   let cacheIntegrityFailure = false;
   for (const { src, diff, error } of outcomes) {
     if (error) {
@@ -2075,13 +1664,10 @@ async function main() {
       diffs: diff.diffs,
       applies_to: src.applies_to,
       report_only: !!src.report_only,
-      // Audit 3 A.1: thread the central-dispatch air-gap short-circuit
-      // marker through to the persisted report so stdout-parsing consumers
-      // and the regression test can verify the network refusal happened.
+      // Persisted so a stdout-parsing consumer can verify the network refusal.
       ...(diff.air_gap_blocked ? { air_gap_blocked: true } : {}),
-      // NEW-CTRL-074: persist the per-source _meta (the watcher stamps
-      // input_field_used here so the chaining is observable in the report)
-      // and the advisories observations[] the watcher consumes.
+      // The watcher stamps input_field_used onto _meta; persisting it makes the
+      // chaining observable.
       ...(diff._meta ? { _meta: diff._meta } : {}),
       ...(Array.isArray(diff.observations) ? { observations: diff.observations } : {}),
     };
@@ -2094,8 +1680,7 @@ async function main() {
     }
   }
 
-  // Persist report — tests can redirect via --report-out so concurrent
-  // suites don't race on a shared refresh-report.json at the repo root.
+  // --report-out keeps concurrent runs off the shared refresh-report.json.
   const reportPath = opts.reportOut ? path.resolve(opts.reportOut) : ABS("refresh-report.json");
   writeJson(reportPath, report);
   log(`\nWrote ${path.relative(ROOT, reportPath)}`);
@@ -2111,14 +1696,8 @@ async function main() {
     }
   }
 
-  // v0.12.12 C3: same anti-pattern v0.12.9 fixed in prefetch's main(). After
-  // Promise.all(sources.map(runOne)) in --swarm mode, process.exit() could
-  // truncate buffered stdout (refresh-report path log line, summary log
-  // lines piped to a consumer). exitCode + return lets the event loop end
-  // naturally and stdout drains in full.
-  // Prefer the documented BLOCKED (4) code when any source refused on a
-  // cache-integrity precondition; fall back to generic failure (1) for other
-  // per-source errors / downstream gate failures.
+  // exitCode + return, not process.exit(), which can truncate buffered stdout.
+  // 4 (BLOCKED) wins over 1 when a source refused on a cache precondition.
   process.exitCode = cacheIntegrityFailure ? 4 : (hadFailure ? 1 : 0);
 }
 
@@ -2130,25 +1709,18 @@ async function sequential(items, fn) {
 
 if (require.main === module) {
   main().catch((err) => {
-    // v0.11.14 (#129): hinted errors print the hint message + a structured
-    // JSON line on stderr instead of a fatal stack trace.
+    // A hinted error prints its message plus a JSON line, never a stack trace.
     if (err && err._exceptd_hint) {
       console.error(err.message);
       console.error(JSON.stringify({ ok: false, error: err.message.split("\n")[0], hint: err.message.split("\n").slice(1).join(" ").trim(), verb: "refresh" }));
     } else if (err && err._exceptd_unknown_source) {
-      // v0.12.12 C3: surface the source-validation error without leaking a
-      // stack trace; chosenSources throws this for unknown --source values.
+      // chosenSources throws this for an unknown --source; no stack trace.
       console.error(err.message);
     } else {
       console.error(`refresh-external: fatal: ${err && err.stack ? err.stack : err}`);
     }
-    // v0.12.12 C3: exitCode + return rather than process.exit(2) — the
-    // event loop has no further work after main()'s rejection, so this
-    // ends the process with code 2 but lets stderr drain first.
-    // Cache-integrity / cache-stale / from-fixture-disabled refusals carry
-    // an explicit exit code (4) via _exceptd_exit_code; honor that so
-    // downstream automation can distinguish "blocked by precondition"
-    // (exit 4) from "fatal/unhandled" (exit 2).
+    // exitCode rather than process.exit(2), so stderr drains first. A refusal
+    // carrying _exceptd_exit_code=4 reads as "blocked by precondition", not fatal.
     process.exitCode = (err && Number.isInteger(err._exceptd_exit_code)) ? err._exceptd_exit_code : 2;
   });
 }