@blamejs/exceptd-skills 0.19.32 → 0.19.34

package/lib/cve-regression-watcher.js

@@ -1,62 +1,10 @@
 'use strict';
 
 /**
- * lib/cve-regression-watcher.js — NEW-CTRL-074 detection method.
- *
- * The MiniPlasma class. A researcher republishes a working PoC against a
- * historical CVE (CVE-2020-17103, originally fixed December 2020) and
- * demonstrates the fix has been silently reverted or never landed. The
- * vendor does not issue a new CVE — the original ID is treated as
- * authoritative. NVD / KEV / OSV feeds will never surface this as a
- * current threat. Vendor advisory feeds (RHSA, USN, ZDI) won't either.
- * Vendor security blogs won't unless Microsoft Security Blog elects to
- * post about it (which, for a re-regression of their own fix, is a
- * commercial-incentive misalignment).
- *
- * What this catches: a poller diff (from lib/source-advisories.js) whose
- * extracted CVE-IDs include historical IDs (year <= currentYear - 2) that
- * may be silently regressed against current shipping product. The
- * detection method is signal-correlation, not source-extension:
- *
- *   1. Pull the union of cve_ids extracted from poller diffs in a given run.
- *   2. Filter to historical IDs (CVE-YYYY-NNN where YYYY <= currentYear - 2).
- *   3. For each historical hit, check whether the catalog has a parallel
- *      "*-REREGRESSION-<year>" key whose `aliases[]` references it OR a
- *      `discovery_attribution_note` that names a researcher republishing
- *      the historical PoC.
- *   4. Surface the unmatched historical hits as candidate regressions —
- *      operators triage and decide whether to (a) create a *-REREGRESSION-
- *      catalog entry (the MiniPlasma path) or (b) annotate the existing
- *      historical entry with a re-regression-confirmed flag.
- *
- * Output shape:
- *   {
- *     candidates: [
- *       {
- *         historical_cve: 'CVE-2020-17103',
- *         surfaced_by: ['bleepingcomputer-security', 'thehackernews'],
- *         first_seen_titles: ['MiniPlasma — Windows ...', ...],
- *         existing_regression_key: 'CVE-2020-17103-REREGRESSION-2026' | null,
- *         action: 'annotate' | 'create-regression-entry' | 'already-covered',
- *       }
- *     ],
- *     historical_id_threshold_year: 2024,
- *     evaluated_diffs: N,
- *   }
- *
- * Design notes:
- *
- * - The threshold (year <= currentYear - 2) is deliberately permissive.
- *   A re-regression of a 2024 CVE is still a regression. The threshold
- *   keeps the watcher from firing on every fresh CVE poller diff.
- * - The watcher is REPORT-ONLY. It does not mutate the catalog. Operators
- *   route candidates through `exceptd refresh --advisory <CVE-ID> --apply`
- *   or via manual triage of a new *-REREGRESSION-<year> entry. This
- *   matches ADVISORIES_SOURCE's conservative-by-default contract.
- * - The CVE_RE matcher (lib/source-advisories.js) already handles the
- *   historical-CVE extraction step — the watcher consumes diffs, not raw
- *   feed bodies. This keeps the watcher decoupled from feed-fetch logic
- *   so it works in fixture mode, cache mode, and live mode identically.
+ * NEW-CTRL-074 detection: a historical CVE whose fix has been silently reverted
+ * and whose PoC still works against shipping product. The vendor issues no new
+ * CVE, so NVD, KEV, OSV and vendor advisory feeds never surface it. REPORT-ONLY:
+ * it never mutates the catalog; each candidate is triage input.
  */
 
 const path = require('path');
@@ -65,8 +13,7 @@ const fs = require('fs');
 const CVE_ID_RE = /^CVE-((?:19|20)\d{2})-\d{4,7}$/;
 
 /**
- * Extract the year from a CVE-YYYY-NNN identifier. Returns null for non-CVE
- * IDs (e.g. MAL-*, GHSA-*, the HANDLE:* shape from the github-events parser).
+ * Year from a CVE-YYYY-NNN identifier; null for other shapes (MAL-*, GHSA-*, HANDLE:*).
  */
 function cveYear(id) {
   if (typeof id !== 'string') return null;
@@ -75,10 +22,8 @@ function cveYear(id) {
 }
 
 /**
- * Find any catalog entry whose `aliases[]` includes the historical CVE-ID
- * OR whose key derives from it via the *-REREGRESSION-<year> convention.
- *
- * Returns the key (e.g. 'CVE-2020-17103-REREGRESSION-2026') or null.
+ * The catalog key covering `historicalId` — itself, a `<id>-REREGRESSION-<year>`
+ * key, or an entry listing it in `aliases[]`. Null when nothing covers it.
  */
 function findRegressionEntry(catalog, historicalId) {
   for (const key of Object.keys(catalog)) {
@@ -94,26 +39,13 @@ function findRegressionEntry(catalog, historicalId) {
 }
 
 /**
- * Walk a list of poller diffs (the shape lib/source-advisories.js produces)
- * and surface historical-CVE-ID references that are NOT yet covered by a
- * regression entry in the catalog.
- *
- * @param {Array<{id: string, source?: string, title?: string, sources?: string[]}>} diffs
- * @param {Object} catalog — data/cve-catalog.json shape, _meta key tolerated
- * @param {Object} opts — { now?: Date, threshold_years_ago?: number }
- * @returns {Object} report — { candidates, historical_id_threshold_year, evaluated_diffs }
+ * Surfaces historical-CVE references from poller diffs the catalog does not cover.
+ * @param {Object} catalog — data/cve-catalog.json shape, `_meta` key tolerated
+ * @param {Object} opts — { now?: Date, threshold_years_ago?: number } (default 2)
  */
-// v0.13.20 — content-pattern signals layered on top of the CVE-ID match.
-// The audit-class-2.4 problem: pre-v0.13.20, the watcher detected only
-// when a poller diff carried an extracted CVE-YYYY-NNN identifier. If a
-// researcher's writeup announces "the 2020 Forshaw fix is silently
-// reverted" without typing the CVE ID, the watcher missed the class
-// entirely. v0.13.20 adds content-pattern signals so the watcher can
-// flag candidates from prose alone.
 
-// Historical-regression language. Phrases that indicate a researcher is
-// claiming a fix was silently reverted, downgrade-rolled-back, or
-// otherwise re-broken.
+// Content patterns layer on top of the CVE-id match: a writeup claiming the fix
+// was silently reverted without typing the id is otherwise invisible.
 const HISTORICAL_REGRESSION_PHRASES = [
   /silently (re-?broken|reverted|regressed|rolled back)/i,
   /(fix|patch|mitigation) (was|is)? ?(silently )?(reverted|undone|removed|missing)/i,
@@ -125,11 +57,8 @@ const HISTORICAL_REGRESSION_PHRASES = [
   /vendor (declined|refused|never issued) (a )?new CVE/i,
 ];
 
-// Named-researcher patterns. Operator-curated names that have a prior
-// catalog-grade drop are tracked elsewhere (NEW-CTRL-073 handle tracker),
-// but the regression-watcher also looks for the names in poller-diff
-// content as an additional signal — a familiar handle re-disclosing an
-// old CVE is a higher-confidence regression candidate.
+// A familiar handle re-disclosing an old CVE raises confidence; handles proper
+// are tracked by NEW-CTRL-073, these names are only an extra signal.
 const RESEARCHER_NAME_PATTERNS = [
   /Nightmare-Eclipse/i,
   /Chaotic Eclipse/i,
@@ -140,8 +69,7 @@ const RESEARCHER_NAME_PATTERNS = [
   /Jann Horn/i,
 ];
 
-// Component-string detection — when a poller diff text mentions one of
-// these in conjunction with a regression phrase, flag as candidate.
+// A candidate needs one of these alongside a regression phrase.
 const TRACKED_COMPONENT_TOKENS = [
   /cldflt\.sys/i,
   /\bldfltrl\.sys/i,
@@ -158,17 +86,14 @@ const TRACKED_COMPONENT_TOKENS = [
 function scanContentSignals(text) {
   if (typeof text !== "string" || !text) return {};
   const signals = {};
-  // Historical-regression language hit.
   for (const re of HISTORICAL_REGRESSION_PHRASES) {
     const m = text.match(re);
     if (m) { signals.regression_language = m[0]; break; }
   }
-  // Researcher-name hit.
   for (const re of RESEARCHER_NAME_PATTERNS) {
     const m = text.match(re);
     if (m) { signals.researcher = m[0]; break; }
   }
-  // Component-token hit.
   const components = [];
   for (const re of TRACKED_COMPONENT_TOKENS) {
     const m = text.match(re);
@@ -186,24 +111,14 @@ function findRegressionCandidates(diffs, catalog, opts) {
 
   // Group historical-CVE refs by id so multi-feed surfacing collapses.
   const byHistoricalId = new Map();
-  // Content-only candidates — surfaced by language/component pattern
-  // matching even when no CVE ID was extracted from the diff text. Grouped
-  // by a stable key (the diff id when present, else a composite of the
-  // matched signal) so N duplicate rows for the same regression claim
-  // across feeds collapse to one candidate with a merged surfaced_by — the
-  // same group-by-merge-sources pattern the historical-CVE branch uses.
+  // Content-only candidates: keyed on the diff id when there is one, else on the
+  // matched signal, so duplicate rows for one claim collapse with merged surfaced_by.
   const byContentKey = new Map();
   for (const d of (diffs || [])) {
     if (!d || typeof d.id !== 'string') continue;
-    // Title field name depends on input shape:
-    //   - ADVISORIES_SOURCE diffs[] carry `title` (post-dedupe string).
-    //   - ADVISORIES_SOURCE observations[] carry `first_title` (also a
-    //     string — the first occurrence across feeds). Pre-v0.13.20
-    //     fix (codex P1 PR #60): the watcher only read `title`, which
-    //     is undefined on observations[], so the content-pattern layer
-    //     never fired in the primary production path.
-    // Advisory URL is `advisory_url` (string) on raw per-feed diffs and
-    // `advisory_urls` (array) after dedupe in both shapes.
+    // The title is `title` on diffs[] and `first_title` on observations[] — the
+    // production path passes observations, so reading only `title` kills the content
+    // layer. URLs are `advisory_url` per feed, `advisory_urls` after dedupe.
     const titleField = d.title || d.first_title || '';
     const urls = Array.isArray(d.advisory_urls)
       ? d.advisory_urls.join(' ')
@@ -214,7 +129,6 @@ function findRegressionCandidates(diffs, catalog, opts) {
       (signals.researcher && signals.components));
     const year = cveYear(d.id);
     if (year !== null && year <= thresholdYear) {
-      // CVE-ID-bearing historical reference (the original v0.13.17 path).
       if (!byHistoricalId.has(d.id)) byHistoricalId.set(d.id, { sources: new Set(), titles: [], signals: {} });
       const slot = byHistoricalId.get(d.id);
       if (Array.isArray(d.sources)) {
@@ -222,28 +136,15 @@ function findRegressionCandidates(diffs, catalog, opts) {
       } else if (typeof d.source === 'string') {
         slot.sources.add(d.source);
       }
-      // Title may be carried as `title` (diffs[]) or `first_title`
-      // (observations[]) — accept either to keep the historical-
-      // candidate title list populated under both input shapes.
       const titleStr = (typeof d.title === 'string' && d.title) ? d.title
         : (typeof d.first_title === 'string' && d.first_title) ? d.first_title
         : '';
-      // Dedupe titles before pushing — mirrors the content-only branch.
-      // Without this, duplicate titles across feeds (a common multi-feed
-      // surfacing pattern) consume distinct slots and evict genuinely
-      // distinct titles from the 5-cap below.
+      // Dedupe before pushing, or repeated titles evict distinct ones from the 5-cap.
       if (titleStr && !slot.titles.includes(titleStr)) slot.titles.push(titleStr);
-      // Merge content signals — the strongest signal wins.
       Object.assign(slot.signals, signals);
       continue;
     }
-    // No historical CVE-ID in this diff. If content signals fire, still
-    // surface as a content-only candidate so an operator can triage.
-    // Group by a stable key so duplicate rows for the same claim across
-    // multiple feeds merge their surfaced_by — mirrors byHistoricalId.
-    // The diff id (a current-year / non-historical CVE id) is the cleanest
-    // key when present; ID-less prose rows key off the matched signal
-    // (regression phrase + researcher + sorted component tokens).
+    // No historical CVE id: a content signal is the only way the claim reaches triage.
     if (hasRegressionSignal) {
       const key = (typeof d.id === 'string' && d.id)
         ? `id:${d.id}`
@@ -266,9 +167,7 @@ function findRegressionCandidates(diffs, catalog, opts) {
     const existing = findRegressionEntry(catalog, id);
     let action;
     if (existing) {
-      // The historical CVE is the catalog key itself — annotate it.
       if (existing === id) action = 'annotate';
-      // Already covered by a *-REREGRESSION-<year> entry — nothing to do.
       else action = 'already-covered';
     } else {
       action = 'create-regression-entry';
@@ -284,9 +183,6 @@ function findRegressionCandidates(diffs, catalog, opts) {
   }
 
   candidates.sort((a, b) => a.historical_cve.localeCompare(b.historical_cve));
-  // Emit one content-only candidate per grouped key, with surfaced_by as
-  // the sorted union of every feed that surfaced the same regression claim
-  // and the title list capped at 5 (matching the historical branch).
   const contentCandidates = [];
   for (const slot of byContentKey.values()) {
     contentCandidates.push({
@@ -304,43 +200,25 @@ function findRegressionCandidates(diffs, catalog, opts) {
     candidates,
     historical_id_threshold_year: thresholdYear,
     evaluated_diffs: evaluated,
-    // Stamp from the same clock that derives the threshold year, so both
-    // date-derived report fields share one instant. Falls back to call-time
-    // `new Date()` (via the `now` default) when no clock is injected — never
-    // a module-load constant, which would go stale in a long-lived process.
+    // The same clock that derives the threshold year; a module-load constant would
+    // go stale in a long-lived process.
     generated_at: now.toISOString().slice(0, 10),
     control_ref: 'NEW-CTRL-074',
   };
 }
 
 /**
- * Source-style wrapper so the watcher plugs into the refresh pipeline as a
- * peer of ADVISORIES_SOURCE. fetchDiff() consumes the prior
- * ADVISORIES_SOURCE.fetchDiff() result via ctx.advisoriesObservations
- * (preferred — the full extracted-CVE list including IDs already in
- * catalog, so the annotate verdict can fire on the MiniPlasma class) and
- * falls back to ctx.advisoriesDiffs when the advisories source ran on a
- * pre-v0.13.17 build that did not emit observations.
- *
- * Chaining is explicit — the watcher does not poll feeds itself. The
- * refresh orchestrator's sequential runner (lib/refresh-external.js#main)
- * threads the resolved advisories fetchDiff() result onto
- * ctx.advisoriesObservations + ctx.advisoriesDiffs immediately after the
- * advisories source resolves and BEFORE the next source's fetchDiff is
- * invoked, so order matters: advisories must run before
- * cve-regression-watcher in a multi-source invocation. Under --swarm
- * (Promise.all) the two sources cannot share ctx mid-flight, so the
- * orchestrator runs the watcher in a second pass after the parallel batch
- * resolves, reading observations from the resolved advisories outcome.
+ * Source-style wrapper so the watcher plugs into the refresh pipeline, reading
+ * ADVISORIES_SOURCE's result off `ctx.advisoriesObservations` or
+ * `ctx.advisoriesDiffs`. Ordering is load-bearing: advisories must run BEFORE
+ * this, and under --swarm the orchestrator runs it in a second pass.
  */
 const REGRESSION_WATCHER_SOURCE = {
   name: 'cve-regression-watcher',
   description: 'NEW-CTRL-074 detection method — surfaces poller-diff historical-CVE references that may indicate silent vendor regression (the MiniPlasma class). Report-only; depends on ADVISORIES_SOURCE observations as input.',
   applies_to: 'data/cve-catalog.json',
   async fetchDiff(ctx) {
-    // Prefer observations (v0.13.17+ ADVISORIES_SOURCE return shape) over
-    // diffs[] (pre-v0.13.17). observations[] preserves in-catalog CVE
-    // refs which the annotate verdict requires.
+    // Observations preserve the in-catalog CVE refs the annotate verdict needs.
     const input = (ctx && ctx.advisoriesObservations) || (ctx && ctx.advisoriesDiffs) || [];
     const catalog = (ctx && ctx.cveCatalog) || {};
     const report = findRegressionCandidates(input, catalog, {});
@@ -357,7 +235,6 @@ const REGRESSION_WATCHER_SOURCE = {
       },
     };
   },
-  // Report-only.
   applyDiff(_ctx, _diffs) {
     return {
       updated: 0,

package/lib/cvss.js

@@ -1,51 +1,21 @@
 "use strict";
 /**
- * lib/cvss.js
- *
- * Shared CVSS metric-selection and vector-normalization helpers for every
- * site that ingests NIST NVD scoring (the cache-backed refresh diff, the
- * live per-CVE validator, and the KEV auto-discovery importer).
- *
- * Two properties of NVD's data make naive ingestion lossy:
- *
- *   1. NVD tags the legacy CVSS v2 metric as `type: "Primary"` on pre-v3
- *      CVEs, while a modern v3.1 re-score (often supplied by a CNA) rides as
- *      `type: "Secondary"`. Selecting a metric by `type === "Primary"` alone
- *      therefore picks the *older* v2 score over a newer v3.1 one — silently
- *      downgrading a curated v3.1 entry to v2 on every refresh.
- *
- *   2. NVD's `cvssMetricV2` entries carry a bare base vector
- *      ("AV:N/AC:L/Au:N/C:C/I:C/A:C") with no "CVSS:2.0/" prefix, whereas
- *      v3.x/v4.0 carry the prefix. The catalog schema (and
- *      validate-cve-catalog --strict) require the canonical "CVSS:<x.y>/"
- *      prefix, so writing a bare v2 vector produces an invalid entry.
- *
- * `selectNvdCvss` resolves (1) by preferring the newest CVSS version present
- * and choosing Primary only *within* that version; it resolves (2) by
- * normalizing the returned vector. Callers additionally guard against
- * cross-version downgrades using `cvssVersionOf` on the locally-curated
- * vector.
- *
- * Zero npm deps. Node stdlib only.
+ * CVSS metric selection and vector normalization for NVD ingestion. NVD tags
+ * its legacy v2 metric `type: "Primary"` on pre-v3 CVEs while a newer v3.1
+ * re-score rides as "Secondary", so selecting on `type` alone downgrades a
+ * curated entry to v2. `cvssMetricV2` also omits the "CVSS:2.0/" prefix the
+ * catalog schema requires.
  */
 
-// A bare (unprefixed) CVSS v2 base vector. v2 is the only version NVD emits
-// without a "CVSS:x/" prefix, and its grammar carries the Au: (Authentication)
-// metric that v3/v4 dropped — the unambiguous discriminator for a bare v2.
+// A bare (unprefixed) CVSS v2 base vector; Au: is the metric v3/v4 dropped.
 const BARE_V2_RE = /^AV:[NAL]\/AC:[HML]\/Au:[MSN]\//;
 
-// The four canonical version prefixes the catalog accepts (mirrors
-// validate-cve-catalog.js STRICT_CVSS_PATTERN).
+// Version prefixes the catalog accepts; mirrors STRICT_CVSS_PATTERN in validate-cve-catalog.js.
 const PREFIXED_RE = /^CVSS:(2\.0|3\.0|3\.1|4\.0)\//;
 
 /**
- * The CVSS version a vector declares, as a comparable number (2.0 < 3.0 < 3.1
- * < 4.0). Recognizes the four canonical "CVSS:x.y/" prefixes plus NVD's bare
- * v2 base vector. Returns null for anything unrecognized so callers can treat
- * an unknown version as "do not block" rather than mis-suppressing a diff.
- *
- * @param {string} vector
- * @returns {number|null}
+ * The CVSS version a vector declares, as a comparable number. Null when
+ * unrecognized, so callers treat an unknown version as "do not block".
  */
 function cvssVersionOf(vector) {
   if (typeof vector !== "string" || vector.length === 0) return null;
@@ -56,13 +26,8 @@ function cvssVersionOf(vector) {
 }
 
 /**
- * Ensure a vector carries a canonical "CVSS:x.y/" prefix. A bare v2 base
- * vector is prefixed with "CVSS:2.0/"; already-prefixed vectors (and anything
- * unrecognized) pass through unchanged. The output of a recognized vector
- * always satisfies validate-cve-catalog --strict.
- *
- * @param {string} vector
- * @returns {string}
+ * Prefixes a bare v2 base vector with "CVSS:2.0/"; already-prefixed and
+ * unrecognized vectors pass through unchanged.
  */
 function normalizeCvssVector(vector) {
   if (typeof vector !== "string" || vector.length === 0) return vector;
@@ -72,14 +37,8 @@ function normalizeCvssVector(vector) {
 }
 
 /**
- * Select the most authoritative CVSS metric from an NVD `metrics` object.
- * Prefers the newest CVSS version present (4.0 > 3.1 > 3.0 > 2.0); within the
- * chosen version prefers NVD's "Primary" analyst score over a "Secondary"
- * (CNA) one, falling back to the first entry when no Primary exists in that
- * version. The returned vector is normalized to the canonical prefix form.
- *
- * @param {object} metrics  The `vulnerabilities[0].cve.metrics` object.
- * @returns {{version:number|null, baseScore:number|null, vector:string|null, source:string|null}|null}
+ * The most authoritative metric from an NVD `metrics` object: newest version
+ * wins, "Primary" beats "Secondary". Null when no CVSS metric is present.
  */
 function selectNvdCvss(metrics) {
   const m = metrics || {};

package/lib/doctor-bucketing.js

@@ -1,20 +1,10 @@
 "use strict";
 
 /**
- * lib/doctor-bucketing.js
+ * Buckets `exceptd doctor` per-check results into warning and error lists.
  *
- * Pure function used by the `exceptd doctor` verb to bucket per-check
- * results into "errors" vs "warnings" lists.
- *
- * v0.13.11 — extracted from bin/exceptd.js so the bucketing rule is
- * testable in isolation. The bug it fixes: severity governs bucketing,
- * not the `ok` field alone. A check that sets `ok: false` with
- * `severity: "warn"` (the signing-status check on a non-contributor
- * install — a nudge that the operator can enable signing if they want,
- * not a release-blocker) was previously routed to `failed_checks` and
- * tripped `all_green: false` with `issues_count: 1`, contradicting the
- * `[!! warn]` icon shown in the human-readable text mode. The fix:
- * `severity === "warn"` always wins, regardless of `ok`.
+ * Severity decides the bucket, not `ok`: `severity: "warn"` routes to warnings
+ * and `severity: "info"` routes to neither list, whatever `ok` says.
  */
 
 function bucketChecks(checks) {
@@ -22,12 +12,6 @@ function bucketChecks(checks) {
   const errorList = [];
   for (const [k, v] of Object.entries(checks || {})) {
     if (!v || typeof v !== "object") continue;
-    // v0.13.13: severity:info is informational only — never routes to
-    // either bucket regardless of `ok`. Lets a check report ok:false +
-    // severity:info to mean "this surface is intentionally not enabled
-    // here, not a problem" (consumer install with no private key, an
-    // air-gap probe deliberately skipped, etc.) without polluting
-    // warning or failure counts.
     if (v.severity === "info") continue;
     if (v.severity === "warn") {
       warnList.push(k);

package/lib/exit-codes.js

@@ -1,18 +1,9 @@
 'use strict';
 
 /**
- * Canonical exit-code constants for every CLI verb.
- *
- * Every `process.exitCode = N` / `process.exit(N)` site in `bin/exceptd.js`
- * (and any library that wants to set an exit code via emit() ok:false bodies)
- * should reference one of these constants rather than a bare number literal.
- * The map is the source of truth for help text — `exceptd doctor --exit-codes`
- * dumps it as JSON so operator-facing docs cannot drift from runtime.
- *
- * History: prior to v0.12.24 codes were bare magic numbers scattered across
- * ~30 sites. Code 3 in particular meant both "session-id collision" (cmdRun)
- * and "ran-but-no-evidence" (cmdCi) — two semantics, one code, no doc surface.
- * v0.12.24 splits them and centralises so a new verb cannot regress by typo.
+ * Canonical exit-code constants for every CLI verb. Exit sites reference a
+ * constant, not a literal; `exceptd doctor --exit-codes` dumps this map as
+ * JSON, so help text cannot drift from runtime.
  */
 
 const EXIT_CODES = Object.freeze({
@@ -30,10 +21,6 @@ const EXIT_CODES = Object.freeze({
   WATCH_LOCK_CONTENTION: 75,
 });
 
-/**
- * Human-readable + machine-stable description per code. Source for the
- * `exceptd doctor --exit-codes` dump and for help-text rendering.
- */
 const EXIT_CODE_DESCRIPTIONS = Object.freeze({
   0: { name: 'SUCCESS', summary: 'Verb completed successfully.' },
   1: { name: 'GENERIC_FAILURE', summary: 'Unhandled error or validation failure.' },
@@ -49,17 +36,11 @@ const EXIT_CODE_DESCRIPTIONS = Object.freeze({
   75: { name: 'WATCH_LOCK_CONTENTION', summary: 'Watch daemon lock is held by a live process; retry after it exits (sysexits EX_TEMPFAIL). Distinct from LOCK_CONTENTION (8), the per-playbook attestation lock.' },
 });
 
-/**
- * Return the human-readable name for a numeric exit code.
- */
 function exitCodeName(code) {
   const e = EXIT_CODE_DESCRIPTIONS[code];
   return e ? e.name : 'UNKNOWN';
 }
 
-/**
- * Return all exit codes as a stable-shape array suitable for JSON dump.
- */
 function listExitCodes() {
   return Object.entries(EXIT_CODE_DESCRIPTIONS).map(([code, info]) => ({
     code: Number(code),
@@ -69,28 +50,15 @@ function listExitCodes() {
 }
 
 /**
- * Set the process exit code WITHOUT calling process.exit(). Returns to the
- * caller so any pending stdout/stderr writes drain on natural event-loop
- * shutdown.
- *
- * `process.exit(N)` terminates the process synchronously, which truncates
- * buffered async stdout when stdout is piped (CI, test harnesses, --json
- * consumers). The v0.11.10 CI #100 fix established the exitCode-then-return
- * idiom for that reason; every subsequent regression that re-introduced
- * bare process.exit() in the dispatch surface was the same class of bug.
- *
- * Callers SHOULD prefer this helper for any exit-after-stdout-write path.
- * Long-running daemons / tests that need synchronous termination can still
- * use process.exit() directly — that's intentional and not what this guards.
- *
- * @param {number} code Exit code (use the EXIT_CODES constants)
- * @returns {void}
+ * Set the process exit code WITHOUT calling process.exit(), so buffered
+ * stdout drains on natural event-loop shutdown; process.exit() terminates
+ * synchronously and truncates a piped stdout write. Use on any
+ * exit-after-stdout-write path — daemons and tests that need synchronous
+ * termination still call process.exit() directly.
  */
 function safeExit(code) {
-  // Only override exitCode when it isn't already set to a non-zero value —
-  // matches the emit() ok:false fallback contract so a caller that already
-  // set BLOCKED (4) before emit() doesn't get overwritten by a later
-  // GENERIC_FAILURE (1).
+  // A non-zero code already set wins: emit()'s ok:false fallback must not
+  // overwrite a caller's BLOCKED (4) with GENERIC_FAILURE (1).
   if (!process.exitCode || process.exitCode === 0) {
     process.exitCode = code;
   }

package/lib/flag-suggest.js

@@ -1,19 +1,11 @@
 'use strict';
 
 /**
- * Levenshtein-distance flag-typo suggestions.
+ * Levenshtein-distance flag-typo suggestions against a verb-scoped allowlist.
  *
- * Operator typos `--evidnce` / `--csaf-stats` / `--bundle-epohc` were silently
- * absorbed by the argv parser, falling through as boolean true flags with no
- * value, then producing cryptic downstream errors. This helper compares an
- * unknown flag to a verb-scoped allowlist and returns the closest match at
- * distance ≤ 2 AND ≤ floor(flag.length / 2).
- *
- * Per-verb allowlists are the canonical CLI surface. Adding a new flag to a
- * verb means appending to the allowlist here AND updating the
- * printPlaybookVerbHelp block; keep the two in sync. doctor maintains its own
- * KNOWN_DOCTOR_FLAGS set in bin/exceptd.js — keep VERB_FLAG_ALLOWLIST.doctor
- * aligned with it (tests/lib-flag-suggest.test.js pins the shared flags).
+ * The allowlists are the canonical CLI surface: a new flag must be appended
+ * here AND to the printPlaybookVerbHelp block, and VERB_FLAG_ALLOWLIST.doctor
+ * must stay aligned with KNOWN_DOCTOR_FLAGS in bin/exceptd.js.
  */
 
 function editDistance(a, b) {
@@ -39,11 +31,8 @@ function editDistance(a, b) {
 }
 
 /**
- * Suggest the closest allowlisted flag to a given unknown flag.
- *
- * @param {string} flag - operator-supplied flag name without leading --
- * @param {string[]} allowlist - known flag names for the active verb
- * @returns {string|null} the suggested flag name or null when no close match
+ * The closest allowlisted flag, or null when none is close. `flag` is the
+ * operator-supplied name WITHOUT the leading `--`.
  */
 function suggestFlag(flag, allowlist) {
   if (typeof flag !== 'string' || flag.length === 0) return null;
@@ -62,11 +51,7 @@ function suggestFlag(flag, allowlist) {
   return best;
 }
 
-/**
- * Per-verb known-flag allowlist. Every operator-facing flag should appear
- * exactly once per verb where it is consumed. Flags consumed by every verb
- * (e.g. `pretty`, `json`, `help`) live under '_global'.
- */
+/** Flags accepted by every verb live under '_global'. */
 const VERB_FLAG_ALLOWLIST = Object.freeze({
   _global: ['help', 'pretty', 'json', 'verbose', 'quiet'],
   run: [
@@ -118,9 +103,6 @@ const VERB_FLAG_ALLOWLIST = Object.freeze({
   prefetch: ['source', 'cache-dir', 'max-age', 'force', 'no-network'],
 });
 
-/**
- * Return the allowlist for a verb (global flags always included).
- */
 function flagsFor(verb) {
   const verbFlags = VERB_FLAG_ALLOWLIST[verb] || [];
   return [...VERB_FLAG_ALLOWLIST._global, ...verbFlags];