@blamejs/exceptd-skills 0.19.33 → 0.19.34

package/lib/cve-curation.js

@@ -1,67 +1,27 @@
 "use strict";
 
 /**
- * lib/cve-curation.js
- *
- * Editorial-enrichment helper for auto-imported CVE catalog drafts. Given
- * a CVE ID that exists in data/cve-catalog.json as a draft (flagged
- * `_auto_imported: true`), this module cross-references the draft against
- * the project's existing catalogs and produces STRUCTURED EDITORIAL
- * QUESTIONS — candidate framework gaps, ATLAS techniques, ATT&CK techniques,
- * CWE refs — that a human reviewer or AI assistant uses to fill in the
- * null editorial fields.
- *
- * Two modes:
- *
- *   curate(id, { apply: false })             → questionnaire (default)
- *   curate(id, { apply: true, answers: {} }) → land answers into the catalog
- *
- * The apply path validates the resulting entry against the strict CVE
- * schema. When every required field is populated, the draft markers
- * (`_auto_imported` + `_draft` + `_draft_reason`) are removed and the
- * entry becomes a full catalog citizen. When required fields are still
- * missing, the draft markers stay and `residual_warnings` enumerates what
- * is still blocking promotion.
- *
- * Writes go through an atomic tmp + rename pattern so a concurrent
- * `--apply` against the same catalog can't half-write the file.
- *
- * Not "AI-assisted" in the LLM sense. The cross-reference logic is
- * deterministic pattern-matching against catalogs already in the install.
+ * Editorial enrichment for auto-imported CVE catalog drafts: cross-references a
+ * draft in data/cve-catalog.json against the installed catalogs and produces
+ * structured editorial questions for a reviewer to answer. The cross-referencing
+ * is deterministic pattern-matching, not an LLM.
  */
 
 const fs = require("fs");
 const path = require("path");
-// v0.12.12 (codex P1 #1, #2): the apply path was an unlocked RMW (lost
-// updates under concurrent --apply) and promoted drafts based only on
-// presence checks (not strict schema validation). Borrow the canonical
-// lockfile-gated atomic-write helper from refresh-external and the schema
-// validator from validate-cve-catalog so the apply path:
-//   1. Serializes against any other catalog mutation (refresh + curate),
-//   2. Re-reads the catalog INSIDE the lock so concurrent applies merge,
-//   3. Validates the post-apply entry against lib/schemas/cve-catalog.schema.json
-//      before deciding promotion.
 const { withCatalogLock } = require("./refresh-external");
-// `validate` is the LOOSE JSON-schema checker; `additionalChecks` is the
-// strict rule set (STRICT_CVSS_PATTERN, isUsableDate on every date field,
-// cisa_kev=true-requires-valid-date, cross-catalog ref resolution, Hard-Rule
-// #14 IoCs). The predeploy gate runs `validate-cve-catalog.js --strict`, which
-// promotes additionalChecks warnings to FATAL errors on NON-draft entries. The
-// apply path must gate promotion on BOTH — otherwise it strips the _draft
-// markers off an entry the very next predeploy run then FATAL-rejects.
+// `validate` is the LOOSE JSON-schema checker; `additionalChecks` is the strict
+// rule set `validate-cve-catalog.js --strict` promotes to FATAL on NON-draft
+// entries. Promotion must gate on BOTH, or the apply path strips the _draft
+// markers off an entry the next predeploy run then FATAL-rejects.
 const {
   validate: validateAgainstSchema,
   additionalChecks,
   STRICT_CVSS_PATTERN,
   isUsableDate,
 } = require("./validate-cve-catalog");
-// derive rwep_score via the canonical scoring helper rather
-// than a blind `Object.values(...).reduce(sum)`. The helper detects shape
-// (boolean inputs → scoreCustom; post-weight numeric inputs → sum + clamp)
-// so the curation apply-path produces a score that matches whatever the
-// catalog scorer or playbook-runner would have produced for the same
-// factors. Direct dependency on scoring.js is intentional — scoring.js is
-// the authoritative formula.
+// deriveRwepFromFactors detects factor shape (boolean inputs → scoreCustom;
+// post-weight numeric inputs → sum + clamp); scoring.js holds the formula.
 const { deriveRwepFromFactors } = require("./scoring");
 
 const ROOT = path.resolve(__dirname, "..");
@@ -70,16 +30,8 @@ let _cveSchemaCache = null;
 function loadCveEntrySchema() {
   if (_cveSchemaCache) return _cveSchemaCache;
   try {
-    // v0.12.15 (A): the prior version of this function looked for
-    // either `root.patternProperties["^CVE-\\d{4}-\\d+$"]` or an object
-    // `root.additionalProperties`. The actual schema at lib/schemas/cve-
-    // catalog.schema.json has NEITHER — its top level IS the entry shape
-    // (`{type:'object', required:[...], properties: {...}}`) because
-    // validate-cve-catalog.js iterates each CVE id key manually and runs
-    // the schema validator over each value. Result: loadCveEntrySchema()
-    // always returned null, the v0.12.12 codex P1 #1 fix (strict-schema
-    // gating of promotion) was silently disabled, and schema-violating
-    // entries promoted anyway. Use the root schema directly.
+    // The schema's top level IS the entry shape — no patternProperties wrapper
+    // to unwrap; validate-cve-catalog.js iterates the CVE id keys itself.
     const root = JSON.parse(fs.readFileSync(CVE_SCHEMA_PATH, "utf8"));
     _cveSchemaCache = root || null;
     return _cveSchemaCache;
@@ -88,10 +40,7 @@ function loadCveEntrySchema() {
   }
 }
 
-// Lazy-loaded module-level catalog cache. The ATLAS / ATT&CK / CWE /
-// framework-control-gaps catalogs don't change inside a single CLI process,
-// so re-reading them per `curate()` call is wasted I/O. Cache once per
-// process; batch-curate paths (future) get the speedup for free.
+// These catalogs cannot change inside a CLI process; read once per process.
 const catalogsCache = {};
 
 function loadJsonRaw(absPath) {
@@ -99,9 +48,8 @@ function loadJsonRaw(absPath) {
   catch { return null; }
 }
 
-// Resolve a catalog path that may be absolute (operator passed
-// `--catalog C:\tmp\cat.json` or `/tmp/cat.json`) or repo-relative. Plain
-// `path.join(ROOT, abs)` mishandles absolute paths on Windows.
+// A `--catalog` path may be absolute or repo-relative, and a plain
+// `path.join(ROOT, abs)` mishandles an absolute path on Windows.
 function resolveCatalogPath(p) {
   if (!p) return path.join(ROOT, "data", "cve-catalog.json");
   if (path.isAbsolute(p)) return p;
@@ -109,9 +57,8 @@ function resolveCatalogPath(p) {
 }
 
 function loadJson(relOrAbs) {
-  // Repo-relative reads (atlas-ttps.json, attack-ttps.json, etc.) cache
-  // by relative key. Absolute paths bypass the cache — they're operator-
-  // supplied and may legitimately change between invocations.
+  // Repo-relative reads cache by relative key. Absolute paths bypass the cache:
+  // they are operator-supplied and may change between invocations.
   if (path.isAbsolute(relOrAbs)) return loadJsonRaw(relOrAbs);
   if (catalogsCache[relOrAbs] !== undefined) return catalogsCache[relOrAbs];
   const v = loadJsonRaw(path.join(ROOT, relOrAbs));
@@ -119,11 +66,8 @@ function loadJson(relOrAbs) {
   return v;
 }
 
-// Build the cross-reference context additionalChecks() consumes — the same
-// id Sets lib/validate-cve-catalog.js#main() assembles. Cached per process
-// (the underlying catalogs are immutable inside one CLI run). A `null` Set
-// (catalog absent) makes additionalChecks() skip that ref family, matching
-// the validator's defense-in-depth behaviour.
+// The cross-reference context additionalChecks() consumes — the same id Sets
+// lib/validate-cve-catalog.js#main() assembles. A `null` Set skips that family.
 let _strictCtxCache = null;
 function strictCheckCtx() {
   if (_strictCtxCache) return _strictCtxCache;
@@ -143,10 +87,7 @@ function strictCheckCtx() {
   return _strictCtxCache;
 }
 
-/**
- * Score a candidate by counting keyword overlap with the draft entry.
- * Returns 0..100. Pure heuristic — reviewer makes the final call.
- */
+// Keyword overlap between a candidate and the draft, 0..100; a ranking heuristic.
 function keywordOverlapScore(draftText, candidateText) {
   if (!draftText || !candidateText) return 0;
   const draftWords = new Set(
@@ -177,10 +118,8 @@ function pickCandidates(draftDigest, catalog, idField, descriptionField) {
   return candidates.slice(0, 5);
 }
 
-// Report the actual upstream source on a draft. A check that only knows
-// about `_source_ghsa_id` would tag every OSV-imported draft (MAL-*,
-// SNYK-*, RUSTSEC-*, etc. that land via lib/source-osv.js) as "unknown".
-// The registry makes future sources a one-line addition.
+// A registry rather than a `_source_ghsa_id` check, which would report every
+// OSV-imported draft (MAL-*, SNYK-*, RUSTSEC-*) as "unknown".
 const SOURCE_FIELDS = [
   { field: "_source_ghsa_id", label: "GHSA" },
   { field: "_source_osv_id", label: "OSV" },
@@ -196,10 +135,7 @@ function autoImportedFrom(draft) {
   return "unknown";
 }
 
-// Severity word. cvss_score: null returns "unrated" — collapsing it to
-// "low" would be wrong + misleading on a draft that has not been scored
-// yet. "unrated" lets operators grep for unscored drafts and the curate
-// summary reflects the actual state.
+// An unscored draft is "unrated", never "low": no score is not a low score.
 function severityWord(score) {
   if (typeof score !== "number" || Number.isNaN(score)) return "unrated";
   if (score >= 9) return "critical";
@@ -208,9 +144,7 @@ function severityWord(score) {
   return "low";
 }
 
-// The fields the strict CVE schema requires. Used to (a) extend the
-// questionnaire so the operator is prompted for every blocking gap, and
-// (b) compute `residual_warnings` after an apply.
+// The fields the strict CVE schema requires; drives `residual_warnings`.
 const REQUIRED_SCHEMA_FIELDS = [
   "name", "type", "cvss_score", "cvss_vector", "cisa_kev",
   "poc_available", "ai_discovered", "ai_assisted_weaponization", "active_exploitation",
@@ -253,17 +187,14 @@ function residualWarnings(entry) {
 }
 
 /**
- * Build the curation report — questionnaire or apply.
- *
- * curate(cveId, { catalogPath, apply, answers })
+ * The curation report for one CVE.
  *
- *   apply: false (default) → return { ok, editorial_questions, ... }
- *   apply: true            → consume answers, write the catalog, return
- *                             { ok, applied_fields, residual_warnings, ... }
+ *   apply: false (default) → { ok, editorial_questions, ... }
+ *   apply: true            → consumes answers, writes the catalog, and returns
+ *                            { ok, applied_fields, residual_warnings, ... }
  */
 async function curate(cveId, opts = {}) {
-  // Back-compat: earlier signature was `curate(id, { catalogPath, opts })`
-  // — accept either shape so the CLI wiring stays stable.
+  // The nested `{ opts: { catalogPath } }` shape is accepted as well.
   if (opts && opts.opts && !opts.catalogPath && opts.opts.catalogPath) {
     opts = { ...opts, catalogPath: opts.opts.catalogPath };
   }
@@ -279,9 +210,7 @@ async function curate(cveId, opts = {}) {
   }
   const draft = catalog[cveId];
 
-  // Only curate drafts. Editing a human-curated entry is intentional and
-  // happens via direct file edit — refusing here prevents accidental
-  // suggestion-storms on entries that have already been reviewed.
+  // Drafts only: a reviewed entry is edited directly.
   if (!draft._auto_imported && !draft._draft) {
     return {
       ok: false,
@@ -292,17 +221,14 @@ async function curate(cveId, opts = {}) {
     };
   }
 
-  // ----- APPLY PATH (J1) -------------------------------------------------
   if (opts.apply && opts.answers) {
     return applyAnswers(cveId, draft, catalog, catalogPath, opts.answers);
   }
 
-  // ----- QUESTIONNAIRE PATH ---------------------------------------------
   return buildQuestionnaire(cveId, draft);
 }
 
 function buildQuestionnaire(cveId, draft) {
-  // Digest of the draft — feed into keyword-overlap scoring.
   const draftDigest = [
     draft.name || "",
     draft.affected || "",
@@ -311,15 +237,9 @@ function buildQuestionnaire(cveId, draft) {
     draft.type || "",
   ].filter(Boolean).join(" ");
 
-  // Pull candidate catalogs. Each is optional — missing catalogs are skipped
-  // gracefully. J7 makes these one-shot loads per process.
+  // Each candidate catalog is optional; an absent one loads as null and is
+  // skipped. A misnamed path reads the same way — as zero proposals.
   const atlas = loadJson("data/atlas-ttps.json");
-  // v0.12.15 (E): the catalog ships as data/attack-techniques.json
-  // (renamed from data/attack-ttps.json before the v0.12.12 release; the
-  // canonical file path is also what lib/validate-cve-catalog.js consumes).
-  // The prior `data/attack-ttps.json` lookup silently fell back to an empty
-  // object via loadJsonRaw's ENOENT handling, so the ATT&CK candidate
-  // questionnaire branch always returned zero proposals.
   const attack = loadJson("data/attack-techniques.json");
   const frameworkGaps = loadJson("data/framework-control-gaps.json");
 
@@ -328,15 +248,10 @@ function buildQuestionnaire(cveId, draft) {
   // CWE candidates surface as part of the vector question — not its own field.
   const frameworkCandidates = pickCandidates(draftDigest, frameworkGaps, "control_id", "description");
 
-  // Build the editorial-questions list. Each entry names the catalog field,
-  // its current value (likely null on a draft), ranked candidates, and a
-  // specific ASK to surface what the reviewer needs to decide.
   const questions = [];
 
-  // Pre-filled empty containers (`iocs: {}`, `atlas_refs: []`) must NOT
-  // be treated as "answered". `if (!draft.iocs)` is truthy for {}, which
-  // would skip the prompt. Use explicit emptiness checks so drafts
-  // seeded with empty objects / arrays still get the prompt.
+  // A pre-filled empty container (`iocs: {}`, `atlas_refs: []`) is not an
+  // answer, and `!draft.iocs` is false for `{}` — so emptiness is explicit.
   const arrEmpty = (a) => !Array.isArray(a) || a.length === 0;
   const objEmpty = (o) => !o || typeof o !== "object" || Object.keys(o).length === 0;
 
@@ -413,10 +328,7 @@ function buildQuestionnaire(cveId, draft) {
     });
   }
 
-  // Schema-required field prompts. Without these populated, the apply
-  // path cannot produce a schema-passing entry — the entry stays a draft
-  // even after curate --apply. Prompt for them explicitly so the
-  // operator sees what's actually blocking promotion.
+  // Schema-required: unpopulated, `--apply` leaves the entry a draft.
   if (draft.cvss_score === null || draft.cvss_score === undefined
       || draft.cvss_vector === null || draft.cvss_vector === undefined
       || draft.cvss_vector === "") {
@@ -454,9 +366,7 @@ function buildQuestionnaire(cveId, draft) {
     });
   }
 
-  // KEV is always-ask: the operator might know KEV applies (and even has
-  // a date) even when the upstream KEV feed hasn't caught up yet. False
-  // is a valid answer.
+  // Always asked: the operator may know a listing the KEV feed has not caught up.
   if (draft.cisa_kev === null || draft.cisa_kev === undefined) {
     questions.push({
       field: "cisa_kev + cisa_kev_date",
@@ -466,9 +376,8 @@ function buildQuestionnaire(cveId, draft) {
     });
   }
 
-  // The KEV block above only fires while cisa_kev is still unanswered, so a
-  // draft that already knows it is listed needs its own checks for the two
-  // fields that come from the same record and are easy to leave behind.
+  // The block above fires only while cisa_kev is unanswered, so a draft that
+  // already knows it is listed needs its own check for the sibling fields.
   if (draft.cisa_kev === true && !draft.cisa_kev_due_date) {
     questions.push({
       field: "cisa_kev_due_date",
@@ -478,9 +387,8 @@ function buildQuestionnaire(cveId, draft) {
     });
   }
 
-  // A KEV-listed entry has to carry the designation as a boolean: an absent
-  // field reads as false to every consumer, which asserts something CISA's
-  // record may not say.
+  // A KEV-listed entry carries the designation as a boolean: an absent field
+  // reads as false to every consumer, asserting something CISA may not say.
   if (draft.cisa_kev === true && typeof draft.known_ransomware_use !== "boolean") {
     questions.push({
       field: "known_ransomware_use",
@@ -517,43 +425,13 @@ function buildQuestionnaire(cveId, draft) {
 }
 
 /**
- * Apply operator-supplied answers to a draft and write back atomically.
- *
- * Answers shape (each key optional; missing keys leave the draft unchanged
- * for that field):
- *
- *   {
- *     framework_control_gaps: { "NIST-800-53-SI-2": "...", ... },
- *     iocs: { payload_artifacts: [...], behavioral: [...], ... },
- *     atlas_refs: ["AML.T0010", ...],
- *     attack_refs: ["T1195.002", ...],
- *     rwep_factors: { cisa_kev: 25, blast_radius: 30, ... },
- *     rwep_score: 80,                       // optional; derived from sum if absent
- *     cvss_score: 9.8,
- *     cvss_vector: "CVSS:3.1/AV:N/...",
- *     cisa_kev: true,                       // or false
- *     cisa_kev_date: "2026-05-13",
- *     poc_available: true,
- *     poc_description: "...",
- *     ai_discovered: false,
- *     ai_assisted_weaponization: false,
- *     active_exploitation: "confirmed" | "suspected" | "theoretical" | "none" | "unknown",
- *     vector: "...",
- *     complexity: "...",
- *     patch_available: true,
- *     patch_required_reboot: false,
- *     live_patch_available: true,
- *     live_patch_tools: ["kpatch", "kgraft"],
- *     affected_versions: ["...", "..."],
- *     verification_sources: ["https://...", ...]
- *   }
+ * Applies operator-supplied answers to a draft and writes back atomically. Every
+ * answer key is optional; the ALLOWED table below is the authoritative list of
+ * keys and their shapes. rwep_score derives from rwep_factors when it is absent.
  */
 async function applyAnswers(cveId, _draftSnapshot, _catalogSnapshot, catalogPath, answers) {
-  // v0.12.12 (codex P1 #2): wrap the entire read-modify-write under
-  // withCatalogLock. Two concurrent --apply runs against the same catalog
-  // previously read the same base, each mutated a different CVE, and the
-  // later writer overwrote the earlier writer's changes. The lock + re-read
-  // inside the critical section ensures sibling applies merge cleanly.
+  // The whole read-modify-write runs under withCatalogLock, re-reading the
+  // catalog inside the critical section so sibling applies merge.
   let outcome = null;
   await withCatalogLock(catalogPath, (catalog) => {
     if (!catalog || !catalog[cveId]) {
@@ -575,24 +453,14 @@ function applyAnswersUnderLock(cveId, catalog, catalogPath, answers) {
   const entry = catalog[cveId];
   const appliedFields = [];
 
-  // Whitelist of fields the operator may supply. Anything not in this map
-  // is ignored (so a typo'd key in answers.json doesn't pollute the entry).
-  // Each entry: [field, validator(value) -> bool, transformer(value) -> stored].
+  // The fields an operator may supply, as [field, validator, transformer]. A key
+  // absent from the table is ignored, so a typo cannot pollute the entry.
   const id = (x) => x;
 
-  // rwep_factors must arrive as the post-weight (Shape B) block the schema
-  // mandates: a non-array object whose EVERY value is a finite number. A
-  // permissive "any object" check let a mixed-shape bag through — post-weight
-  // integers carrying a string active_exploitation, or an all-numeric block
-  // plus a rogue extra key holding a ladder string ('confirmed'). Either
-  // shape flips deriveRwepFromFactors() onto its Shape-A (scoreCustom) route,
-  // which reads the post-weight integers as booleans and DROPS the unmapped
-  // ai_factor weight — deriving a silently wrong rwep_score (e.g. 55/75 for a
-  // bag the operator intended as 90) and writing it to the catalog. Rejecting
-  // any non-numeric value here turns that silent mis-score into a surfaced
-  // rejected_fields entry at apply time, instead of relying on the downstream
-  // scoring.validate() divergence gate (which runs only at predeploy, after
-  // the wrong score is already on disk).
+  // rwep_factors must arrive as the post-weight block the schema mandates: a
+  // non-array object whose EVERY value is a finite number. A mixed bag flips
+  // deriveRwepFromFactors() onto its scoreCustom route, which reads the integers
+  // as booleans and writes a silently wrong rwep_score.
   const isPostWeightFactors = (v) =>
     v && typeof v === "object" && !Array.isArray(v) &&
     Object.values(v).every((x) => typeof x === "number" && Number.isFinite(x));
@@ -606,11 +474,8 @@ function applyAnswersUnderLock(cveId, catalog, catalogPath, answers) {
     ["rwep_score",             (v) => typeof v === "number", id],
     ["rwep_notes",             (v) => typeof v === "string", id],
     ["cvss_score",             (v) => typeof v === "number", id],
-    // Match the predeploy strict gate at apply time: a non-existent CVSS
-    // version (`CVSS:9/...`) and a malformed/impossible KEV date previously
-    // survived the per-field check, landed on the entry, then blocked
-    // promotion downstream. Rejecting them here surfaces the exact field as a
-    // rejected_fields entry instead of a silent block.
+    // These match the predeploy strict gate at apply time: a `CVSS:9/...` vector
+    // or a malformed KEV date otherwise blocks promotion with no field named.
     ["cvss_vector",            (v) => typeof v === "string" && STRICT_CVSS_PATTERN.test(v), id],
     ["cisa_kev",               (v) => typeof v === "boolean", id],
     ["cisa_kev_date",          (v) => v === null || (typeof v === "string" && isUsableDate(v).ok), id],
@@ -653,27 +518,18 @@ function applyAnswersUnderLock(cveId, catalog, catalogPath, answers) {
     appliedFields.push(field);
   }
 
-  // derive rwep_score via the canonical scoring helper rather
-  // than a blind sum. deriveRwepFromFactors detects shape (boolean inputs
-  // → scoreCustom; post-weight numeric inputs → sum + clamp) and routes
-  // accordingly, so the apply-path produces a score that agrees with
-  // scoring.validate() instead of diverging from it.
+  // Derived through the canonical helper, not a blind sum, so the score agrees
+  // with scoring.validate() rather than diverging from it.
   if ("rwep_factors" in answers && !("rwep_score" in answers)
       && entry.rwep_factors && typeof entry.rwep_factors === "object") {
     entry.rwep_score = deriveRwepFromFactors(entry.rwep_factors);
     appliedFields.push("rwep_score (derived from rwep_factors via scoring.deriveRwepFromFactors)");
   }
 
-  // last_updated reflects the apply moment.
   entry.last_updated = new Date().toISOString().slice(0, 10);
 
-  // v0.12.12 (codex P1 #1): validate the post-apply entry against the
-  // strict CVE schema BEFORE deciding whether to promote. Promotion was
-  // previously gated on residualWarnings() alone — a presence check — so
-  // an input like `"ai_discovered": "false"` (string) passed presence but
-  // would have failed lib/validate-cve-catalog.js on type mismatch,
-  // creating a "promoted but invalid" entry. Now: presence + strict schema
-  // BOTH must hold for promotion.
+  // Promotion needs presence AND the strict schema: a presence check alone
+  // accepts `"ai_discovered": "false"`, leaving a promoted-but-invalid entry.
   const warnings = residualWarnings(entry);
   const schemaErrors = [];
   const entrySchema = loadCveEntrySchema();
@@ -681,17 +537,9 @@ function applyAnswersUnderLock(cveId, catalog, catalogPath, answers) {
     const errs = validateAgainstSchema(entry, entrySchema, "cve-entry", `${cveId}`);
     if (Array.isArray(errs) && errs.length > 0) schemaErrors.push(...errs);
   }
-  // The loose schema accepts values the predeploy `validate-cve-catalog.js
-  // --strict` gate FATAL-rejects on a non-draft entry: a cvss_vector for a
-  // non-existent CVSS version (`CVSS:9/...` passes the schema's
-  // `^CVSS:[0-9]+(\.[0-9]+)?/` but fails STRICT_CVSS_PATTERN), a cisa_kev=true
-  // with a malformed/impossible cisa_kev_date, an atlas/attack/cwe/d3fend/
-  // framework ref that resolves to no catalog entry, or a poc+public-exploit
-  // source with no iocs. Run the SAME additionalChecks() the validator runs
-  // and fold its findings into the promotion gate, so the apply path never
-  // strips _draft off an entry the next predeploy run then rejects. Surfaced
-  // under a dedicated `strict_warnings` key so the operator sees exactly which
-  // strict rule blocked promotion.
+  // The loose schema accepts values `validate-cve-catalog.js --strict`
+  // FATAL-rejects on a non-draft entry, so the validator's own additionalChecks()
+  // runs here too; `strict_warnings` names the rule.
   const strictWarnings = additionalChecks(cveId, entry, strictCheckCtx());
   let promoted = false;
   if (warnings.length === 0 && schemaErrors.length === 0 && strictWarnings.length === 0) {
@@ -701,9 +549,7 @@ function applyAnswersUnderLock(cveId, catalog, catalogPath, answers) {
     promoted = true;
   }
 
-  // catalog has been mutated in-place under the lock; the locker writes it
-  // atomically when this function returns. Concurrent applies are
-  // serialized + see the post-merge state.
+  // Mutated in place under the lock; the locker writes it atomically on return.
   catalog[cveId] = entry;
 
   return {
@@ -738,11 +584,8 @@ function applyAnswersUnderLock(cveId, catalog, catalogPath, answers) {
 
 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. Without
-  // fsync the data sits in the OS page cache and the rename succeeds
-  // atomically, but the renamed file may be zero-length / partial on
-  // crash. Open + write + fsync + close + rename is the durable idiom.
+  // fsync before the rename: without it the rename is still atomic, but the
+  // renamed file can be zero-length or partial after a crash.
   const fd = fs.openSync(tmpPath, 'w');
   try {
     fs.writeSync(fd, JSON.stringify(obj, null, 2) + "\n", 0, "utf8");
@@ -758,14 +601,10 @@ function writeJsonAtomic(p, obj) {
   }
 }
 
-/**
- * CLI entry — wired from bin/exceptd.js via `refresh --curate <id>` and
- * `refresh --curate <id> --answers <path> [--apply]`.
- */
+// CLI entry, wired from bin/exceptd.js as `refresh --curate <id>` and
+// `refresh --curate <id> --answers <path> [--apply]`.
 async function cli(argv) {
-  // Batch curation (facts file + judgments file → gate-passing catalog
-  // entries) is a distinct workflow from the single-CVE questionnaire
-  // below; delegate before the --curate opts loop touches argv.
+  // A distinct workflow, delegated before the opts loop below consumes argv.
   if (argv.includes("--curate-batch")) return require("./cve-batch.js").cli(argv);
   const opts = { advisory: null, json: false, catalogPath: null, answersPath: null, apply: false };
   for (let i = 0; i < argv.length; i++) {
@@ -788,10 +627,8 @@ async function cli(argv) {
     return;
   }
 
-  // Operator passing --answers <path> means apply. --apply on its own is
-  // also accepted (for parity with --advisory --apply), but it's a no-op
-  // without --answers — fail loudly so a forgetful operator doesn't think
-  // a write succeeded when in fact the questionnaire was returned.
+  // `--answers <path>` implies apply. `--apply` alone is a no-op that would
+  // return the questionnaire, so it fails loudly rather than read as a write.
   let answers = null;
   if (opts.answersPath) {
     try {
@@ -805,8 +642,6 @@ async function cli(argv) {
       return;
     }
   }
-  // --answers alone implies apply; --apply alone without --answers is a
-  // user error.
   const doApply = !!answers || opts.apply;
   if (opts.apply && !answers) {
     const err = { ok: false, verb: "refresh", mode: "cve-curation", error: "--apply requires --answers <path-to-answers.json>" };
@@ -839,8 +674,8 @@ async function cli(argv) {
     }
     process.stdout.write(`\n  Run with --json for the full structured output.\n`);
   }
-  // Questionnaire path: exit 3 ("editorial review pending"). Apply path:
-  // exit 0 when promoted, 3 when residual_warnings remain (still draft).
+  // Exit 2 on error, 3 for "editorial review pending" — the questionnaire, or
+  // an apply that left the entry a draft — and 0 only on promotion.
   if (!result.ok) process.exitCode = 2;
   else if (result.mode === "cve-curation-apply") process.exitCode = result.promoted ? 0 : 3;
   else process.exitCode = 3;
@@ -848,10 +683,8 @@ async function cli(argv) {
 
 if (require.main === module) {
   cli(process.argv.slice(2)).catch((err) => {
-    // An apply-path write failure (disk full / read-only FS / permission
-    // denied) throws out of cli(). Emit the same {ok:false,verb,mode,error}
-    // envelope every other error path in cli() produces instead of crashing
-    // with a raw stack trace, and set exitCode so stderr drains before exit.
+    // A throw out of cli() emits the same {ok:false,verb,mode,error} envelope as
+    // every other error path, and `process.exitCode`, so stderr drains first.
     process.stderr.write(JSON.stringify({ ok: false, verb: "refresh", mode: "cve-curation", error: String((err && err.message) || err) }) + "\n");
     process.exitCode = 2;
   });