@blamejs/exceptd-skills 0.19.32 → 0.19.34

package/lib/rfc-cli.js

@@ -2,21 +2,14 @@
 "use strict";
 
 /**
- * lib/rfc-cli.js — `exceptd rfc <number>` resolver.
- *
- * Local index (whole current RFC series, offline) -> resolved cache -> one
- * datatracker lookup to disambiguate obsoleted-vs-nonexistent. Resolves an RFC
- * number to its title + status so an agent can confirm a citation (e.g. "is
- * RFC 9404 the Sieve spec?") without the datatracker. Optional --check
- * "<claimed title>" reports whether the claimed title matches.
+ * `exceptd rfc <number>` — resolves an RFC number to its title and status:
+ * local index, then resolved cache, then one datatracker lookup to separate
+ * obsoleted from nonexistent.
  */
 
 const { resolveRfc } = require("./citation-resolve.js");
 
-// Stopwords that don't disambiguate one RFC title from another. A claimed title
-// run preceded by one of these in the index title is still a clean match; a run
-// preceded by a CONTENT word (e.g. "datagram" before "transport layer security")
-// is the tail of a more-specific title and must NOT be accepted as a match.
+// Stopwords don't disambiguate one RFC title from another.
 const TITLE_STOPWORDS = new Set(["the", "a", "an", "of", "for", "to", "in", "on", "and", "or"]);
 
 function normTitle(s) {
@@ -24,37 +17,19 @@ function normTitle(s) {
 }
 
 /**
- * Decide whether a claimed RFC title matches the authoritative index title.
- *
- * Replaces the old lenient bidirectional substring test (`a.includes(b) ||
- * b.includes(a)`), which let "TLS" match the DTLS title (substring of "dtls")
- * and let "Transport Layer Security" match the DTLS title (tail-of-phrase).
- * The comparison is now whole-word and phrase-aware:
- *
- *   1. Every claimed token must appear as a WHOLE word in the index title
- *      (so "tls" never matches inside "dtls").
- *   2. The claimed token sequence must appear as a CONTIGUOUS run in the index
- *      title, OR the claim must cover enough of the index title (containment
- *      ratio floor) to be unambiguous.
- *   3. A contiguous run that is immediately preceded by a distinguishing
- *      CONTENT word in the index title is rejected — it is the tail of a
- *      more-specific title (the "datagram transport layer security" trap).
- *
- * Returns true / false. Only called when both a claim and an index title exist.
+ * Whole-word, phrase-aware comparison of a claimed RFC title against the
+ * authoritative index title. Called only when both exist.
  */
 function titleMatches(claimed, indexTitle) {
   const claimTokens = normTitle(claimed).split(" ").filter(Boolean);
   const titleTokens = normTitle(indexTitle).split(" ").filter(Boolean);
   if (claimTokens.length === 0 || titleTokens.length === 0) return false;
 
-  // (1) Whole-word containment: every claimed token must be a standalone token
-  //     in the index title. Kills the tls-inside-dtls substring false positive.
   const titleSet = new Set(titleTokens);
   for (const t of claimTokens) {
     if (!titleSet.has(t)) return false;
   }
 
-  // Find every contiguous run of the claim inside the index title.
   const runStarts = [];
   for (let i = 0; i + claimTokens.length <= titleTokens.length; i++) {
     let hit = true;
@@ -65,16 +40,12 @@ function titleMatches(claimed, indexTitle) {
   }
 
   if (runStarts.length > 0) {
-    // A single-token claim that is a whole word in the title is unambiguous on
-    // its own — the whole-word check above already excluded the substring trap
-    // (e.g. "tls" is NOT a token inside "dtls"), so "TLS" correctly matches the
-    // 8446 title (standalone "tls" token) but not the 9147 DTLS title.
+    // A single-token claim that survived the whole-word check is unambiguous on
+    // its own — "tls" is not a token inside "dtls".
     if (claimTokens.length === 1) return true;
-    // (3) For a MULTI-token run, accept only if at least one occurrence is NOT
-    //     preceded by a distinguishing content word — i.e. it begins the title
-    //     or is preceded only by a stopword. A run preceded solely by a content
-    //     qualifier (e.g. "datagram" before "transport layer security") is the
-    //     tail of a more-specific title and must not be accepted as a match.
+    // A multi-token run counts only where some occurrence begins the title or
+    // is preceded by a stopword. Preceded by a content qualifier ("datagram"
+    // before "transport layer security") it is the tail of a different title.
     for (const start of runStarts) {
       if (start === 0) return true;
       const prev = titleTokens[start - 1];
@@ -83,13 +54,9 @@ function titleMatches(claimed, indexTitle) {
     return false;
   }
 
-  // No contiguous run, but all tokens present out of order. Accept only when the
-  // claim covers a strong majority of the index title's tokens (containment
-  // ratio floor) — a few scattered tokens against a long title is ambiguous,
-  // not a match. Count DISTINCT claim tokens that appear in the title: counting
-  // non-distinct tokens lets a repeated-token claim (e.g. "security security
-  // security security") inflate the ratio past the floor and falsely match an
-  // unrelated title.
+  // No contiguous run, all tokens present out of order: accept only when the
+  // claim covers a strong majority of the title's tokens. DISTINCT claim tokens
+  // are counted, or a repeated-token claim inflates the ratio past the floor.
   const distinct = new Set(claimTokens);
   const present = [...distinct].filter((t) => titleSet.has(t)).length;
   const ratio = present / titleTokens.length;
@@ -99,9 +66,8 @@ function titleMatches(claimed, indexTitle) {
 async function main() {
   const argv = process.argv.slice(2);
   const flags = new Set(argv.filter((a) => a.startsWith("--")));
-  // Reject unknown flags (same contract as the in-process verbs). `--check`
-  // consumes the following token as its value; that value is a positional, not
-  // a flag, so it isn't checked here.
+  // Unknown flags are rejected, as in the in-process verbs. `--check` consumes
+  // the following token, which is a positional and so isn't checked here.
   const KNOWN = new Set(["--json", "--pretty", "--air-gap", "--no-network", "--check", "--help", "-h"]);
   const unknown = [...flags].filter((f) => !KNOWN.has(f));
   if (unknown.length > 0) {
@@ -112,10 +78,8 @@ async function main() {
     process.exitCode = 1;
     return;
   }
-  // --check "<claimed title>" consumes the FOLLOWING token as its value. Exclude
-  // that value token by INDEX from the positional pool before selecting id, so
-  // the RFC number resolves correctly regardless of flag order
-  // (`rfc --check "Some Title" 9404` reads id=9404, not id="Some Title").
+  // The `--check` value token is excluded from the positional pool by INDEX, so
+  // `rfc --check "Some Title" 9404` reads id=9404, not id="Some Title".
   const checkIdx = argv.indexOf("--check");
   const checkValueIdx = (checkIdx !== -1 && argv[checkIdx + 1] && !argv[checkIdx + 1].startsWith("--")) ? checkIdx + 1 : -1;
   const positionals = argv.filter((a, i) => !a.startsWith("--") && i !== checkValueIdx);
@@ -123,9 +87,7 @@ async function main() {
   const pretty = flags.has("--pretty");
   const json = flags.has("--json") || pretty;
 
-  // The claimed title is exactly the excluded value token (kept in lockstep with
-  // checkValueIdx so the two never diverge); a trailing `--check` with no value
-  // leaves it null.
+  // Exactly the excluded value token; a trailing `--check` with no value is null.
   let claimedTitle = null;
   if (checkValueIdx !== -1) claimedTitle = argv[checkValueIdx];
 
@@ -143,10 +105,7 @@ async function main() {
   if (claimedTitle && r.title) {
     titleMatch = titleMatches(claimedTitle, r.title);
   }
-  // Derive `ok` from the resolved status + title-check the same way the exit
-  // code is derived below — a non-zero exit (status nonexistent OR an explicit
-  // title mismatch) must carry ok:false, not the inverted ok:true the envelope
-  // previously hardcoded.
+  // `ok` derives from the same condition as the exit code below.
   const fails = r.status === "nonexistent" || titleMatch === false;
   const body = { verb: "rfc", ...r, ...(claimedTitle ? { claimed_title: claimedTitle, title_match: titleMatch } : {}), ok: !fails };
 
@@ -171,15 +130,11 @@ async function main() {
   if (fails) process.exitCode = 2;
 }
 
-// Only run the CLI when invoked directly (`exceptd rfc ...`). When required by a
-// test the IIFE must not fire — it would read process.argv and write to stdout —
-// so the pure title-match helper can be exercised in-process.
+// Under require it would read process.argv and write stdout; keep it testable.
 if (require.main === module) {
   main().catch((err) => {
-    // A corrupt/unreadable RFC index (or any unexpected throw inside the async
-    // body) becomes a rejected promise. Emit the documented {ok:false,error}
-    // envelope rather than crashing with a raw stack trace, and signal failure
-    // via exitCode so the event loop drains stderr before exit.
+    // Any unexpected throw becomes the {ok:false,error} envelope, not a raw
+    // stack; `process.exitCode`, not `process.exit()`, so stderr drains.
     process.stderr.write(JSON.stringify({ ok: false, verb: "rfc", error: String((err && err.message) || err) }) + "\n");
     process.exitCode = 1;
   });

package/lib/scoring.js

@@ -4,17 +4,13 @@
  * RWEP — Real-World Exploit Priority scoring engine. Supplements CVSS with
  * exploit availability, active exploitation and operational constraints.
  *
- * `rwep_factors` carries two shapes at once. Every factor stores its POST-WEIGHT
- * contribution except `blast_radius`, which stores its RAW 0..30 magnitude —
- * summing the object still yields `rwep_score` only because the blast weight is
- * also 30. Do not feed booleans in here; `scoreCustom()` takes those, plus a
- * numeric blast_radius and a ladder string. `deriveRwepFromFactors()` detects
- * which shape it was given and routes accordingly.
+ * In a stored `rwep_factors` block every factor is its POST-WEIGHT contribution
+ * except `blast_radius`, a RAW 0..30 magnitude; the object sums to `rwep_score`
+ * only because the blast weight is also 30.
  */
 
 // Loaded from the schema so the two cannot drift. live_patch_tools is
-// deliberately absent: it is schema-optional, and the
-// live_patch_available => live_patch_tools implication is enforced below.
+// schema-optional — validate() enforces live_patch_available => live_patch_tools.
 const CVE_SCHEMA_REQUIRED = require('./schemas/cve-catalog.schema.json').required;
 
 // reboot_required applies even when a live patch exists, because a live patch
@@ -30,12 +26,9 @@ const RWEP_WEIGHTS = {
   reboot_required:       5
 };
 
-// Must stay aligned with playbook-runner's _activeExploitationLadder so the
-// catalog scorer and the runtime evaluator agree on the same string. 'unknown'
-// scores a quarter rather than zero: an untriaged CVE is not a clean one.
-// 'theoretical' is mapped explicitly at 0 — a published PoC carries its weight
-// through poc_available, and an incidental `?? 0` fall-through here would be
-// indistinguishable from an unrecognised value.
+// Must stay aligned with playbook-runner's _activeExploitationLadder. 'unknown'
+// scores a quarter — an untriaged CVE is not a clean one; 'theoretical' is
+// mapped explicitly so it stays distinguishable from an unrecognised value.
 const ACTIVE_EXPLOITATION_LADDER = {
   confirmed:   1.0,
   suspected:   0.5,
@@ -45,15 +38,10 @@ const ACTIVE_EXPLOITATION_LADDER = {
 };
 
 /**
- * Ladder multiplier for an active_exploitation value, as
- * { multiplier, recognised, normalised }.
- *
- * Case- and whitespace-normalised, so 'Confirmed' resolves rather than zeroing.
- * null and undefined are the documented 'none' default and count as recognised.
- * Anything else returns multiplier 0 AND emits a process warning: an
- * out-of-vocabulary string would otherwise drop 20 points silently, and the
- * no-match path has to be observable. validateFactors() carries the structured
- * diagnostic for callers that collect warnings.
+ * Ladder multiplier as { multiplier, recognised, normalised }. Case- and
+ * whitespace-normalised; null and undefined are the 'none' default and count as
+ * recognised. Anything else returns multiplier 0 with recognised false, so an
+ * out-of-vocabulary string cannot drop 20 points silently.
  */
 function resolveActiveExploitation(active_exploitation) {
   if (active_exploitation === undefined || active_exploitation === null) {
@@ -72,11 +60,8 @@ function resolveActiveExploitation(active_exploitation) {
 function activeExploitationMultiplier(active_exploitation) {
   const r = resolveActiveExploitation(active_exploitation);
   if (!r.recognised) {
-    // Observable diagnostic for the bare-number call path (scoreCustom without
-    // collectWarnings, which the production write-paths use). Routed through
-    // process.emitWarning so it lands on the standard Node diagnostic channel
-    // without changing the function's number return contract; deduped per
-    // distinct offending value so a batch curation run doesn't flood stderr.
+    // Routed through process.emitWarning so the bare-number return contract is
+    // unchanged; validateFactors() carries the structured form.
     const detail = active_exploitation === undefined || active_exploitation === null
       ? String(active_exploitation)
       : (typeof active_exploitation === 'string' ? JSON.stringify(active_exploitation) : `${typeof active_exploitation} ${JSON.stringify(active_exploitation)}`);
@@ -89,8 +74,7 @@ function activeExploitationMultiplier(active_exploitation) {
 }
 
 // Boolean-input (Shape-A) keys scoreCustom recognises; validateFactors flags
-// anything else. The last two are the catalog's own field names, accepted as
-// aliases so a factor bag built straight from an entry validates.
+// anything else. The last two are catalog field names accepted as aliases.
 const RECOGNISED_FACTOR_KEYS = new Set([
   'cisa_kev', 'poc_available', 'ai_assisted_weapon', 'ai_discovered',
   'active_exploitation', 'blast_radius', 'patch_available',
@@ -99,11 +83,9 @@ const RECOGNISED_FACTOR_KEYS = new Set([
   'patch_required_reboot',
 ]);
 
-// Post-weight (Shape-B) keys deriveRwepFromFactors may sum. `ai_factor` has to
-// be added back: it is the +15 weight every Shape-B entry stores, and it is
-// absent from the Shape-A set above, so filtering on that set alone would drop
-// it from every derivation. A key outside this set is excluded from the sum and
-// surfaced, so a typo cannot quietly change a score.
+// Post-weight (Shape-B) keys deriveRwepFromFactors may sum. `ai_factor` is added
+// back because it is absent from the Shape-A set above. A key outside this set is
+// excluded from the sum and surfaced, so a typo cannot quietly change a score.
 const RECOGNISED_POST_WEIGHT_KEYS = new Set([...RECOGNISED_FACTOR_KEYS, 'ai_factor']);
 
 function score(cveId, catalog) {
@@ -115,9 +97,7 @@ function score(cveId, catalog) {
 /**
  * Warnings for a factor bag: missing-but-defaultable fields and out-of-range
  * values. Never throws — a caller wanting enforcement treats a non-empty return
- * as a failure. Booleans may be null (false, with a warning);
- * active_exploitation must be a ladder value; blast_radius is an integer in
- * [0, 30], flagged out of range because that usually means a unit error.
+ * as a failure.
  */
 function validateFactors(factors) {
   const warnings = [];
@@ -127,8 +107,8 @@ function validateFactors(factors) {
   const boolFields = ['cisa_kev', 'poc_available', 'ai_assisted_weapon', 'ai_discovered',
                       'patch_available', 'live_patch_available', 'reboot_required'];
   for (const f of boolFields) {
-    // Honours the same aliasing as scoreCustom, so a bag supplying only the
-    // catalog field name is not flagged missing.
+    // Same aliasing as scoreCustom, so a bag supplying only the catalog field
+    // name is not flagged missing.
     const present = (f === 'ai_assisted_weapon')
       ? (factors.ai_assisted_weapon ?? factors.ai_assisted_weaponization)
       : (f === 'reboot_required')
@@ -146,20 +126,18 @@ function validateFactors(factors) {
     warnings.push("active_exploitation: missing (treated as 'none')");
   } else {
     // Normalised before the vocabulary check so this accepts exactly what the
-    // scorer accepts; otherwise 'Confirmed' is flagged here and consumed there.
+    // scorer accepts — otherwise 'Confirmed' is flagged here and taken there.
     const aeNorm = typeof aeRaw === 'string' ? aeRaw.trim().toLowerCase() : aeRaw;
     if (!aeAllowed.includes(aeNorm)) {
       warnings.push(`active_exploitation: expected one of ${aeAllowed.join(', ')}, got ${JSON.stringify(aeRaw)}`);
     }
   }
-  // Number.isFinite rather than a typeof check: `typeof NaN === 'number'` and
-  // `JSON.stringify(NaN) === 'null'`, which together produce the useless
-  // "expected number, got number (null)".
+  // Number.isFinite rather than typeof: `typeof NaN === 'number'` and
+  // `JSON.stringify(NaN) === 'null'` produce "expected number, got number (null)".
   if (factors.blast_radius === undefined || factors.blast_radius === null) {
     warnings.push('blast_radius: missing (treated as 0)');
   } else if (typeof factors.blast_radius !== 'number') {
-    // scoreCustom coerces a numeric string via Number(), so a finite one is
-    // noted rather than rejected — the scorer will use it either way.
+    // scoreCustom coerces a numeric string, so a finite one is noted, not rejected.
     if (typeof factors.blast_radius === 'string' && Number.isFinite(Number(factors.blast_radius)) && factors.blast_radius.trim() !== '') {
       warnings.push(`blast_radius: numeric string "${factors.blast_radius}" accepted (coerced to ${Number(factors.blast_radius)}); prefer a JSON number`);
     } else {
@@ -172,8 +150,8 @@ function validateFactors(factors) {
   } else if (factors.blast_radius < 0 || factors.blast_radius > 30) {
     warnings.push(`blast_radius: ${factors.blast_radius} out of expected range [0, 30] (clamped to weight ceiling, but the value usually indicates a unit-of-measure mistake)`);
   }
-  // An unknown key is surfaced rather than ignored: `patch_avilable` would
-  // otherwise default to false with no diagnostic.
+  // An unknown key is surfaced, not ignored: `patch_avilable` would otherwise
+  // default to false with no diagnostic.
   for (const k of Object.keys(factors)) {
     if (!RECOGNISED_FACTOR_KEYS.has(k)) {
       warnings.push(`unknown factor: ${k} (ignored — not in the recognised key set)`);
@@ -183,19 +161,16 @@ function validateFactors(factors) {
 }
 
 /**
- * RWEP for a factor bag, clamped to [0, 100].
- *
- * Returns a bare number, which callers depend on. With
- * `opts.collectWarnings` it returns `{ score, _scoring_warnings }` instead;
- * for validation without a score, call `validateFactors()` directly.
+ * RWEP for a factor bag, clamped to [0, 100]. Returns a bare number, which
+ * callers depend on; with `opts.collectWarnings` it returns
+ * `{ score, _scoring_warnings }` instead.
  */
 function scoreCustom(factors, opts) {
   const {
     cisa_kev = false,
     poc_available = false,
     ai_assisted_weapon = false,
-    // Catalog field name, accepted as an alias so an entry-derived bag still
-    // counts the +15 AI factor.
+    // Catalog field name, aliased so an entry-derived bag still counts the +15.
     ai_assisted_weaponization = false,
     ai_discovered = false,
     active_exploitation = 'none',
@@ -203,8 +178,7 @@ function scoreCustom(factors, opts) {
     patch_available = false,
     live_patch_available = false,
     reboot_required = false,
-    // Likewise: the catalog spells this `patch_required_reboot`, so both
-    // spellings are accepted and a direct caller cannot lose the factor.
+    // Likewise the catalog spelling; both are accepted so no caller loses it.
     patch_required_reboot,
   } = factors || {};
   const rebootFactor = (reboot_required === true) || (patch_required_reboot === true);
@@ -217,11 +191,8 @@ function scoreCustom(factors, opts) {
   // odd number would truncate under a `Math.floor(weight/2)` split.
   const aeMultiplier = activeExploitationMultiplier(active_exploitation);
   score += RWEP_WEIGHTS.active_exploitation * aeMultiplier;
-  // Accepts only a finite number or a trimmed non-empty numeric string, which
-  // is validateFactors' contract exactly. Bare Number() would turn `true` into
-  // 1 and `[7]` into 7 — values the validator rejects — so the scorer would add
-  // a contribution the validator calls invalid. NaN also has
-  // `typeof === 'number'` and propagates through the final clamp.
+  // Only a finite number or a trimmed non-empty numeric string, matching
+  // validateFactors. Bare Number() turns `true` into 1 and `[7]` into 7.
   let brRaw = 0;
   if (typeof blast_radius === 'number' && Number.isFinite(blast_radius)) {
     brRaw = blast_radius;
@@ -254,23 +225,17 @@ function scoreCustom(factors, opts) {
 }
 
 /**
- * RWEP from a `rwep_factors` object of either shape, so the curation
- * apply-path and the auto-discovery builder share one derivation.
- *
- * Shape A (booleans, a ladder string, a numeric blast_radius) routes through
- * scoreCustom. Shape B (post-weight contributions, how the catalog stores them)
- * is summed and clamped to [0, 100].
+ * RWEP from a `rwep_factors` object of either shape. Shape A (booleans, a ladder
+ * string, a numeric blast_radius) routes through scoreCustom; Shape B
+ * (post-weight contributions, how the catalog stores them) is summed and clamped.
  */
 function deriveRwepFromFactors(factors) {
   if (!factors || typeof factors !== 'object') return 0;
   const entries = Object.entries(factors);
   if (entries.length === 0) return 0;
-  // A boolean, or a ladder string, is Shape-A evidence. The ladder string
-  // legitimately appears in BOTH shapes — Shape B may carry it as a readable
-  // status beside its integers — so hasPostWeightInt below is what
-  // disambiguates, not excluding active_exploitation from this check. Excluding
-  // it here under-scores a ladder-only bag, which falls through to the sum and
-  // skips the string entirely.
+  // A boolean or a ladder string is Shape-A evidence. The ladder string is legal
+  // in both shapes, so hasPostWeightInt below disambiguates; excluding it here
+  // sends a ladder-only bag to the sum, which skips the string entirely.
   const aeAllowed = new Set(['none', 'unknown', 'suspected', 'theoretical', 'confirmed']);
   const hasBooleanOrLadder = entries.some(
     ([, v]) => (typeof v === 'boolean' || (typeof v === 'string' && aeAllowed.has(v.trim().toLowerCase()))),
@@ -283,18 +248,14 @@ function deriveRwepFromFactors(factors) {
   if (hasBooleanOrLadder && !hasPostWeightInt) {
     return scoreCustom(factors);
   }
-  // Shape B: sum and clamp. blast_radius is the one field needing a per-factor
-  // clamp first — it is a raw 0..30 magnitude, not a post-weight contribution,
-  // so a unit error like 300 would otherwise reach only the aggregate clamp and
-  // make the two scorers disagree, which would show up as a false divergence in
-  // validate()'s recompute-vs-stored gate.
+  // Shape B: sum and clamp. blast_radius needs a per-factor clamp first — a unit
+  // error like 300 would otherwise reach only the aggregate clamp and make the
+  // two scorers disagree in validate()'s recompute-vs-stored gate.
   let sum = 0;
   for (const [k, v] of Object.entries(factors)) {
     if (typeof v !== 'number' || !Number.isFinite(v)) continue;
-    // An unrecognised key is excluded AND surfaced, matching what scoreCustom
-    // and validateFactors do, so the three scoring surfaces agree on what a
-    // typo means. Summing it blindly let a sub-5 typo inflate the breakdown
-    // with no diagnostic.
+    // Excluded AND surfaced, as in validateFactors, so a sub-5 typo cannot
+    // inflate the sum with no diagnostic.
     if (!RECOGNISED_POST_WEIGHT_KEYS.has(k)) {
       process.emitWarning(
         `rwep_factors carries unrecognised key '${k}'; excluded from the derived sum`,
@@ -314,9 +275,8 @@ function deriveRwepFromFactors(factors) {
   return Math.max(0, Math.min(100, sum));
 }
 
-// Post-weight (Shape-B) factor object required by cve-catalog.schema.json.
-// Canonical home for the math auto-discovery.js/cve-enrich.js both consume,
-// so Σ Object.values(...) === scoreCustom(inputs) (pre-clamp) by construction.
+// Post-weight (Shape-B) factor object required by cve-catalog.schema.json:
+// Σ Object.values(...) === scoreCustom(inputs) pre-clamp, by construction.
 function postWeightFactors(inputs) {
   const i = inputs || {};
   const aeMultiplier = activeExploitationMultiplier(i.active_exploitation);
@@ -351,8 +311,7 @@ function compare(cveId, catalog, opts) {
   if (!entry) throw new Error(`CVE not in catalog: ${cveId}`);
 
   // `recompute` ignores the stored score and re-derives from rwep_factors,
-  // which is how catalog drift against current weights is caught. Routed
-  // through the shape detector so hand-edited factors in either shape work.
+  // which is how catalog drift against the current weights is caught.
   const recompute = !!(opts && opts.recompute);
   let rwep;
   if (recompute) {
@@ -362,8 +321,7 @@ function compare(cveId, catalog, opts) {
     rwep = entry.rwep_score;
   }
   // Absent or non-finite CVSS must not reach `cvss * 10`: NaN fails every band
-  // below and falls through to "broadly aligned", asserting an alignment never
-  // computed. Absent CVSS is not-comparable, not zero.
+  // and falls through to "broadly aligned". Absent CVSS is not-comparable, not zero.
   const cvss = (typeof entry.cvss_score === 'number' && Number.isFinite(entry.cvss_score))
     ? entry.cvss_score
     : null;
@@ -375,9 +333,7 @@ function compare(cveId, catalog, opts) {
   const delta = (cvssAbsent || !rwepValid) ? null : rwep - cvssEquivalent;
 
   // The "broadly aligned" band is ±10, the tightest that still reads ordinary
-  // CVSS rounding as alignment. A ±20 band swallows a delta of 12, which is
-  // exactly the case where the CVSS-calibrated SLA is the thing at issue.
-  // A zero-vs-zero entry reports no scoring signal rather than alignment.
+  // CVSS rounding as alignment; ±20 swallows a delta of 12.
   let explanation = '';
   if (!rwepValid) {
     explanation = 'RWEP score absent or non-numeric for this CVE — no usable RWEP signal to compare. Backfill rwep_score / rwep_factors in the catalog.';
@@ -387,29 +343,23 @@ function compare(cveId, catalog, opts) {
     explanation = 'CVSS absent — RWEP is the only usable score for this CVE; no CVSS comparison is possible. Backfill cvss_score in the catalog to enable the comparison.';
   } else if (delta > 10) {
     explanation = `RWEP significantly higher than CVSS equivalent. Factors driving delta: `;
-    // Lists every factor scoreCustom counts, through the same aliases and
-    // normalization — otherwise an entry driven by ai_assisted_weaponization, a
-    // stray-cased 'Confirmed' or the patch_required_reboot alias shows a raised
-    // RWEP with no stated reason.
+    // Every factor scoreCustom counts, through the same aliases and
+    // normalization, or a raised RWEP is shown with no stated reason.
     const driving = [];
     if (entry.cisa_kev) driving.push('CISA KEV (+25)');
     if (entry.poc_available) driving.push('public PoC (+20)');
     if (entry.ai_discovered || entry.ai_assisted_weaponization) driving.push('AI-discovered (+15 weaponization)');
-    // Through the same ladder, so suspected (+10) and unknown (+5) are listed
-    // with their real contribution. A confirmed-only test leaves the enumerated
-    // factors summing to less than the delta, or to nothing at all.
+    // Through the same ladder, so suspected (+10) and unknown (+5) are listed too.
     const ae = resolveActiveExploitation(entry.active_exploitation);
     if (ae.multiplier > 0) {
       driving.push(`${ae.normalised} exploitation (+${Math.round(RWEP_WEIGHTS.active_exploitation * ae.multiplier)})`);
     }
-    // blast_radius contributes its raw 0..30 value, so a blast-driven delta
-    // needs it listed or the raised RWEP has no stated cause.
+    // blast_radius contributes its raw 0..30 value, so a blast-driven delta needs it.
     const blastRaw = Number((entry.rwep_factors || {}).blast_radius);
     const blast = Number.isFinite(blastRaw) ? Math.max(0, Math.min(RWEP_WEIGHTS.blast_radius, blastRaw)) : 0;
     if (blast > 0) driving.push(`blast radius (+${Math.round(blast)})`);
-    // Ungated by live_patch_available, mirroring scoreCustom's rebootFactor.
-    // Gating it here hides a driver the score counted on any entry that both
-    // needs a reboot and has a live patch.
+    // Ungated by live_patch_available, mirroring scoreCustom's rebootFactor:
+    // gating here hides a driver the score counted.
     if (entry.reboot_required || entry.patch_required_reboot) driving.push('reboot required (+5)');
     // Names the structural cause rather than trailing off after "driving delta:".
     explanation += driving.length ? driving.join(', ') : 'blast magnitude / structural RWEP factors';
@@ -443,17 +393,14 @@ function compare(cveId, catalog, opts) {
 }
 
 /**
- * Which shape an `rwep_factors` block uses: 'A' raw, 'B' post-weight,
- * 'unknown' for empty or ambiguous blocks, 'mixed' for the violating case.
- *
- * Mixing them inside one entry breaks the sum invariant silently:
- * `{ cisa_kev: true, blast_radius: 30 }` sums to 30 when the intended score is
- * 55, because a raw boolean contributes nothing to a post-weight sum.
+ * Which shape an `rwep_factors` block uses: 'A' raw, 'B' post-weight, 'unknown'
+ * for empty or ambiguous blocks, 'mixed' for the violating case. Mixing them
+ * breaks the sum invariant silently: `{ cisa_kev: true, blast_radius: 30 }` sums
+ * to 30 where the intended score is 55.
  */
 function detectFactorShape(factors) {
   if (!factors || typeof factors !== 'object') return 'unknown';
-  // Both spellings per factor, so a post-weight integer on either canonical key
-  // registers as Shape-B evidence rather than slipping past the detector.
+  // Both spellings per factor, so a post-weight integer on either registers as Shape-B.
   const boolFields = ['cisa_kev', 'poc_available', 'ai_assisted_weaponization', 'ai_discovered', 'ai_factor', 'active_exploitation', 'patch_available', 'live_patch_available', 'patch_required_reboot', 'reboot_required'];
   let sawBool = false;
   let sawWeightedInt = false;
@@ -461,8 +408,7 @@ function detectFactorShape(factors) {
     if (k === 'blast_radius') continue; // always integer in both shapes
     if (k === 'active_exploitation' && typeof v === 'string') {
       // Valid in both shapes, so it is not Shape-A evidence: counting it would
-      // return 'mixed' on a clean Shape-B block. Its weight is resolved in the
-      // post-weight path, not here.
+      // return 'mixed' on a clean Shape-B block.
       continue;
     }
     if (typeof v === 'boolean' || v === null) {
@@ -486,10 +432,8 @@ function validate(catalog) {
   for (const [cveId, entry] of Object.entries(catalog)) {
     if (cveId.startsWith('_')) continue;
     // Drafts carry a conservative-default rwep_score beside null-until-curated
-    // factor fields, so the divergence check below would fire on every one of
-    // them. They are reviewed through `_auto_imported_meta.curation_needed` and
-    // the validator's draft tier instead; clearing `_auto_imported` at curation
-    // restores full validation.
+    // factor fields, so the divergence check below fires on every one. They are
+    // reviewed through `_auto_imported_meta.curation_needed` instead.
     if (entry && entry._auto_imported === true) continue;
     for (const field of CVE_SCHEMA_REQUIRED) {
       if (!(field in entry)) {
@@ -506,10 +450,9 @@ function validate(catalog) {
     if (shape === 'mixed') {
       errors.push(`${cveId}: rwep_factors mixes Shape A (booleans) with Shape B (post-weight integers) — sum invariant cannot hold. Convert factors to a single shape.`);
     }
-    // Per-factor coherence: every Shape-B contribution must equal the weight
-    // its source field implies, because two compensating errors cancel inside
-    // the ±5 aggregate tolerance below. blast_radius is exempt — it is the one
-    // judgment-set factor with no deriving field.
+    // Per-factor coherence: every Shape-B contribution must equal the weight its
+    // source field implies, because two compensating errors cancel inside the ±5
+    // aggregate tolerance below. blast_radius is exempt — no deriving field.
     if (shape === 'B') {
       const f = entry.rwep_factors;
       const aeMultiplier = resolveActiveExploitation(entry.active_exploitation).multiplier;
@@ -526,8 +469,8 @@ function validate(catalog) {
           errors.push(`${cveId}: rwep_factors.${k} is ${f[k]} but the entry's source fields imply ${want}`);
         }
       }
-      // One implied weight, two accepted spellings. Both are checked, or a
-      // contradictory value stored under the alias passes the coherence gate.
+      // One implied weight, two accepted spellings: both are checked, or a
+      // contradictory value under the alias passes the coherence gate.
       const rebootWant = entry.patch_required_reboot === true ? RWEP_WEIGHTS.reboot_required : 0;
       for (const rebootKey of ['reboot_required', 'patch_required_reboot']) {
         if (rebootKey in f && typeof f[rebootKey] === 'number' && f[rebootKey] !== rebootWant) {
@@ -544,8 +487,7 @@ function validate(catalog) {
       blast_radius: entry.rwep_factors ? entry.rwep_factors.blast_radius : 0,
       patch_available: entry.patch_available,
       live_patch_available: entry.live_patch_available,
-      // Both spellings, mirroring scoreCustom: passing only one drops the other
-      // and computes a divergent expected score.
+      // Both spellings, mirroring scoreCustom; passing one computes a divergent score.
       reboot_required: entry.reboot_required || entry.patch_required_reboot
     });
     if (Math.abs(calculatedRwep - entry.rwep_score) > 5) {
@@ -556,15 +498,10 @@ function validate(catalog) {
 }
 
 /**
- * Strict CVSS 3.x vector parse, as `{ ok, version, reason? }`.
- *
- * Strict CSAF validators reject a document whose cvss_v3 block is keyed off a
- * malformed vector, so a permissive parse here fails downstream rather than
- * here. Mandatory metrics in order are AV/AC/PR/UI/S/C/I/A; E/RL/RC and the
- * CR..MA environmental set are optional.
- *
- * 3.0 and 3.1 share one grammar and differ only in the prefix, and CSAF 2.0
- * accepts both, so the version is recorded rather than rejected.
+ * Strict CVSS 3.x vector parse, as `{ ok, version, reason? }`. A permissive parse
+ * here fails downstream instead: strict CSAF validators reject a document whose
+ * cvss_v3 block is keyed off a malformed vector. CSAF 2.0 accepts 3.0 and 3.1
+ * alike, so the version is recorded rather than rejected.
  */
 const CVSS_3X_RE = /^CVSS:3\.[01]\/AV:[NALP]\/AC:[LH]\/PR:[NLH]\/UI:[NR]\/S:[UC]\/C:[NLH]\/I:[NLH]\/A:[NLH](\/E:[XUPFH])?(\/RL:[XOTWU])?(\/RC:[XURC])?(\/CR:[XLMH])?(\/IR:[XLMH])?(\/AR:[XLMH])?(\/MAV:[XNALP])?(\/MAC:[XLH])?(\/MPR:[XNLH])?(\/MUI:[XNR])?(\/MS:[XUC])?(\/MC:[XNLH])?(\/MI:[XNLH])?(\/MA:[XNLH])?$/;
 
@@ -588,16 +525,11 @@ function parseCvss31Vector(v) {
 
 /**
  * Package-Confidence Score: a supplementary 0-100 supply-chain trust signal
- * shown alongside RWEP, never instead of it. Returns null with no usable input.
- *
- * Its polarity is the INVERSE of RWEP — high means trustworthy provenance, low
- * means it behaves like malware — so the two must never be summed or compared.
- * It is deliberately outside the RWEP factor key set and is never called from
- * validate(), scoreCustom() or deriveRwepFromFactors(), so it cannot perturb a
- * stored rwep_score or trip the divergence gate.
+ * shown alongside RWEP, never instead of it. Null with no usable input.
  *
- * Equal-weight mean of whichever sub-signals are present; an absent dimension is
- * skipped rather than scored 0, so a partly-curated entry is not punished.
+ * Its polarity is the INVERSE of RWEP — high means trustworthy provenance — so
+ * the two are never summed or compared. Equal-weight mean of whichever
+ * sub-signals are present; an absent dimension is skipped rather than scored 0.
  */
 function packageConfidence(inputs) {
   if (!inputs || typeof inputs !== 'object') return null;