@blamejs/exceptd-skills 0.19.32 → 0.19.34

package/lib/cross-ref-api.js

@@ -1,15 +1,9 @@
 'use strict';
 
 /**
- * Cross-reference API — pure read-only knowledge queries over data/ + data/_indexes/.
- *
- * This is the knowledge layer the host AI calls into during the ANALYZE phase
- * of every directive. No probes, no shellouts, no network. Every function takes
- * an identifier and returns correlated catalog entries from CVE / CWE / ATLAS /
- * ATT&CK / D3FEND / framework-gaps / global-frameworks / RFC / zero-day-lessons,
- * plus pre-computed indexes (xref, chains, recipes, theater-fingerprints).
- *
- * Catalogs are loaded lazily and cached for the lifetime of the process.
+ * Cross-reference API — read-only queries over data/ and data/_indexes/. Every
+ * function takes an identifier and returns the correlated catalog entries.
+ * Catalogs load lazily and are cached for the lifetime of the process.
  */
 
 const fs = require('fs');
@@ -19,35 +13,17 @@ const ROOT = path.join(__dirname, '..');
 const DATA_DIR = process.env.EXCEPTD_DATA_DIR || path.join(ROOT, 'data');
 const INDEX_DIR = path.join(DATA_DIR, '_indexes');
 
-// Cache entries store the parsed payload AND the mtimeMs of the source
-// file at parse-time. Each load call re-stats the file; if mtime matches,
-// the cached value is returned (one syscall, no parse). If mtime changed,
-// re-parse + repopulate. If stat fails (file vanished mid-run, permission
-// glitch), fall back to the cached value. Without mtime-keyed
-// invalidation, long-running `orchestrator watch` processes never see
-// `data/cve-catalog.json` mutations driven by `exceptd refresh --apply`.
+// Each entry stores the parsed payload beside the source file's stat signature,
+// so a long-running process sees a catalog that `refresh --apply` rewrote.
 const _cache = new Map();
 
-// v0.12.14: catalog corruption no longer crashes the runner
-// uncaught. A malformed JSON file in data/ used to produce a SyntaxError
-// at require-time of any consumer (lib/playbook-runner.js), which threw
-// out of the run() entrypoint without honoring AGENTS.md's "non-zero
-// exit + {ok:false, error} to stderr" contract. Now: caught + degraded
-// to an empty catalog with a recorded _loadError that downstream code
-// can inspect.
+// A malformed JSON file degrades to an empty catalog carrying a recorded load
+// error, rather than throwing out of the run() entrypoint.
 const _loadErrors = [];
 
 /**
- * v0.13.0: cache invalidation is keyed on (mtimeMs, size). Pre-v0.13 it
- * was mtime-only, but on filesystems with 1-2s mtime granularity
- * (FAT32, HFS+ pre-APFS, NFSv3, Docker bind-mounts that proxy mtime)
- * a rapid refresh-then-reload within the same second served stale
- * cached data. Adding `size` catches every content change that affects
- * byte count; mtimeMs catches in-place rewrites that preserve byte
- * count. Together they cover every realistic catalog-mutation path
- * without the cost of a per-load SHA computation. SHA-based tier is
- * available via _statContentHash() when callers want full invalidation
- * (e.g. long-running daemons against append-only catalogs).
+ * Keyed on (mtimeMs, size): on a filesystem with 1-2s mtime granularity a
+ * refresh-then-reload inside the same second serves stale data on mtime alone.
  */
 function _statSignature(p) {
   try {
@@ -119,47 +95,34 @@ function entries(catalog) {
   return Object.entries(catalog).filter(([k]) => !k.startsWith('_'));
 }
 
-// Auto-imported drafts carry conservative-default mechanical fields and
-// null analytical fields pending curation. byCve() excludes them by
-// default; every transitive enumeration that walks the same catalog
-// (byCwe / byTtp / bySkill) must apply the identical contract so a draft
-// never surfaces as a curated cross-reference. Keyed on `_auto_imported`
-// to match byCve's exact predicate, so all four entry points agree.
+// Auto-imported drafts carry null analytical fields. byCve, byCwe, byTtp and
+// bySkill all exclude on this one predicate, so a draft never reads as curated.
 function _isDraftEntry(c) {
   return !!c && c._auto_imported === true;
 }
 
-// Single source of truth for the xref sub-maps the skill-correlation
-// queries read. These names MUST stay identical to the keys the index
-// builder emits into data/_indexes/xref.json; reading under a name the
-// builder never writes silently yields empty correlations. The TTP maps
-// are split by id space — ATLAS ids (AML.*) live in atlas_refs, ATT&CK
-// ids (T*) in attack_refs — so a TTP lookup unions both.
+// These names must match the keys the index builder emits into
+// data/_indexes/xref.json — a name it never writes yields empty correlations with
+// no error. ATLAS ids (AML.*) live in atlas_refs, ATT&CK ids in attack_refs.
 const XREF_KEYS = {
   cwe: 'cwe_refs',
   atlas: 'atlas_refs',
   attack: 'attack_refs',
 };
 
-// CWE -> [skill, ...] from the xref index.
 function skillsForCwe(xref, cweId) {
   return (xref[XREF_KEYS.cwe] && xref[XREF_KEYS.cwe][cweId]) || [];
 }
 
-// TTP -> [skill, ...]; ATLAS and ATT&CK ids occupy separate maps, so a
-// single id resolves through whichever map owns its prefix (with a fall
-// back to the other in case a caller passes an unprefixed id).
+// An id resolves through the map owning its prefix, falling back to the other.
 function skillsForTtp(xref, ttpId) {
   const atlas = xref[XREF_KEYS.atlas] || {};
   const attack = xref[XREF_KEYS.attack] || {};
   return (ttpId.startsWith('AML.') ? atlas[ttpId] : attack[ttpId]) || atlas[ttpId] || attack[ttpId] || [];
 }
 
-// No CVE->skill map exists in the index (no skill declares a CVE list, so
-// the builder never emits one). The real linkage runs through the CVE's
-// declared CWEs: each CWE maps to skills via the cwe_refs map. Union the
-// skills across every CWE the CVE references, sorted + de-duplicated so
-// the result is stable regardless of CWE ordering.
+// No CVE->skill map exists, so the linkage runs through the CVE's declared CWEs.
+// The union is sorted so the result does not depend on CWE ordering.
 function skillsForCve(xref, cveEntry) {
   const out = new Set();
   for (const cwe of (cveEntry && cveEntry.cwe_refs) || []) {
@@ -168,21 +131,11 @@ function skillsForCve(xref, cveEntry) {
   return [...out].sort();
 }
 
-// --- public API ---
-
 /**
- * Full correlation for a CVE ID. Returns the catalog entry plus everything
- * that references it across skills, framework gaps, theater fingerprints,
- * recipes, and zero-day lessons.
- *
- * Auto-imported drafts (entries with `_auto_imported === true`) are
- * EXCLUDED by default. Drafts carry conservative-default mechanical fields
- * and null analytical fields pending curation; downstream analyze / bundle
- * emitters that assume `byCve()` returns curated data would treat the
- * draft's placeholders as authoritative. The cve-curation flow (which
- * surfaces the editorial questionnaire) opts in via
- * `byCve(id, { include_drafts: true })`; every other caller stays on the
- * default exclude path.
+ * Full correlation for a CVE id: the catalog entry plus everything referencing
+ * it across skills, framework gaps, theater fingerprints and zero-day lessons.
+ * Auto-imported drafts are excluded unless `opts.include_drafts` is set, since
+ * callers read what this returns as curated.
  */
 function byCve(cveId, opts) {
   const includeDrafts = !!(opts && opts.include_drafts);
@@ -198,27 +151,15 @@ function byCve(cveId, opts) {
   const gaps = loadCatalog('framework-control-gaps.json');
   const lessons = loadCatalog('zeroday-lessons.json');
 
-  // Skills correlate to a CVE transitively through its declared CWEs
-  // (CVE -> cwe_refs -> xref.cwe_refs -> skills); there is no direct
-  // CVE->skill index.
   const skills = skillsForCve(xref, entry);
-  // (Recipes are use-case curated, not CVE-triggered — recipes.json has no
-  // `triggered_by`/CVE keying, so a per-CVE recipe lookup was always empty.
-  // The dead `recipes:[]` field is no longer emitted.)
-  //
-  // Theater fingerprints live under the index's `patterns` container; each
-  // pattern records a single `evidence.cve` (or `evidence.campaign`, which
-  // carries no CVE to match). The distinguishing check is `fast_test`.
+  // Theater fingerprints live under the index's `patterns` container; each records
+  // a single `evidence.cve`, and `fast_test` is the distinguishing check.
   const theater = Object.entries(theaterFp.patterns || {})
     .filter(([, t]) => t && t.evidence && t.evidence.cve === cveId)
     .map(([id, t]) => ({ id, pattern_name: t.pattern_name, distinguisher: t.fast_test }));
-  // Framework-control-gaps link CVEs through `evidence_cves`; the control
-  // identifier field is `control_id`.
   const framework_gaps = entries(gaps).filter(([, g]) =>
     Array.isArray(g.evidence_cves) && g.evidence_cves.includes(cveId)
   ).map(([id, g]) => ({ id, framework: g.framework, control: g.control_id, status: g.status }));
-  // Zero-day lessons are keyed by CVE id, so a referenced lesson is a
-  // direct key hit rather than a back-reference scan.
   const lessons_learned = lessons[cveId] ? [cveId] : [];
 
   return {
@@ -251,11 +192,8 @@ function byCwe(cweId) {
 }
 
 function byTtp(ttpId) {
-  // TTP ids span two disjoint catalogs (ATLAS AML.* vs ATT&CK T*).
-  // Resolve the record from whichever owns the id — namespaces never
-  // collide, so order is irrelevant. Previously only atlas-ttps.json was
-  // consulted, so every ATT&CK technique reported found:false / entry:null
-  // even though skills + related_cves correctly unioned both spaces.
+  // TTP ids span two disjoint catalogs (ATLAS AML.* vs ATT&CK T*); consulting
+  // only one leaves every technique in the other reporting found:false.
   const atlas = loadCatalog('atlas-ttps.json');
   const attack = loadCatalog('attack-techniques.json');
   const xref = loadIndex('xref.json');
@@ -269,10 +207,8 @@ function byTtp(ttpId) {
       )
     )
     .map(([id]) => id);
-  // D3FEND maps countermeasures to the techniques they defeat through the
-  // `counters_attack_techniques` field. The earlier `counters` field is
-  // empty across every catalog entry, so this correlation was structurally
-  // dead (a non-existent field .includes() is always false).
+  // D3FEND maps a countermeasure through `counters_attack_techniques`; the
+  // `counters` field is empty catalog-wide, so filtering on it is dead.
   const d3fend = entries(loadCatalog('d3fend-catalog.json'))
     .filter(([, d]) => Array.isArray(d.counters_attack_techniques) && d.counters_attack_techniques.includes(ttpId))
     .map(([id]) => id);
@@ -283,8 +219,7 @@ function bySkill(skillName) {
   const xref = loadIndex('xref.json');
   const summary = loadIndex('summary-cards.json');
   const card = summary[skillName] || summary.skills?.[skillName] || null;
-  // TTPs invert the atlas_refs + attack_refs maps: any TTP whose skill
-  // list contains this skill is a reference. Both id spaces contribute.
+  // Invert both TTP maps; both id spaces contribute.
   const ttpRefs = Object.entries({
     ...(xref[XREF_KEYS.atlas] || {}),
     ...(xref[XREF_KEYS.attack] || {}),
@@ -292,9 +227,6 @@ function bySkill(skillName) {
     .filter(([, skills]) => Array.isArray(skills) && skills.includes(skillName))
     .map(([ttp]) => ttp)
     .sort();
-  // CVEs link to a skill transitively: a CVE references CWEs, and each CWE
-  // maps to skills via cwe_refs. Collect every CVE whose CWE set resolves
-  // to this skill.
   const cveCatalog = loadCatalog('cve-catalog.json');
   const cveRefs = entries(cveCatalog)
     .filter(([, c]) => !_isDraftEntry(c) && (c.cwe_refs || []).some(cwe => skillsForCwe(xref, cwe).includes(skillName)))
@@ -303,13 +235,9 @@ function bySkill(skillName) {
   return { skill: skillName, summary_card: card, cve_refs: cveRefs, ttp_refs: ttpRefs };
 }
 
-// global-frameworks.json is keyed by REGION (EU/UK/AU/...), each with a nested
-// `frameworks: { SHORTKEY: {full_name, catalog_aliases?, ...} }` map. A flat
-// `global[frameworkId]` lookup therefore ALWAYS returned null — frameworkId is a
-// short key or a catalog display name, never a region — so framework_meta was
-// universally null. Walk the nested structure and match the requested id against
-// the short key, the full_name, or any catalog_alias (normalized), returning the
-// matched framework object annotated with its region + jurisdiction.
+// global-frameworks.json is keyed by region, each region holding a nested
+// `frameworks: { SHORTKEY: {...} }` map, so a flat `global[frameworkId]` lookup
+// never matches. Match the short key, full_name or any catalog_alias, normalized.
 function resolveFrameworkMeta(global, frameworkId) {
   if (!global || frameworkId == null) return null;
   const norm = (s) => String(s == null ? '' : s).toLowerCase().replace(/\([^)]*\)/g, '').replace(/[\s_-]/g, '');
@@ -336,13 +264,8 @@ function byFramework(frameworkId) {
   const gaps = loadCatalog('framework-control-gaps.json');
   const global = loadCatalog('global-frameworks.json');
   const fwMeta = resolveFrameworkMeta(global, frameworkId);
-  // Match gap rows by the framework's full LABEL SET, not just the literal id.
-  // The catalog stores a framework's gaps under labels (au-ism / AU ISM / ACSC
-  // ISM …) that diverge from its short key and full_name, so an exact
-  // `g.framework === frameworkId` match returned a gap set inconsistent with the
-  // (now alias-resolved) framework_meta — non-null metadata but a partial,
-  // sometimes empty, gap list. Resolve the same alias set used for the metadata
-  // and match any gap label (string or array element) against it.
+  // Match gap rows against the framework's whole label set: the catalog files
+  // gaps under labels (au-ism / AU ISM / ACSC ISM) that diverge from the key.
   const norm = (s) => String(s == null ? '' : s).toLowerCase().replace(/\([^)]*\)/g, '').replace(/[\s_-]/g, '');
   const labels = new Set([norm(frameworkId)]);
   if (fwMeta) {
@@ -368,17 +291,13 @@ function byFramework(frameworkId) {
 }
 
 /**
- * Theater-fingerprint lookup — given a finding shape, return the specific test
- * that distinguishes paper compliance from actual security (AGENTS.md Hard
- * Rule #6). Drives the validate phase when emit.theater_check = true.
+ * For a finding shape, the test that distinguishes paper compliance from actual
+ * security. Drives the validate phase when emit.theater_check is true.
  */
 function theaterTestsFor({ cveIds = [], frameworkIds = [], skillIds = [] }) {
   const fp = loadIndex('theater-fingerprints.json');
   const matches = [];
-  // Fingerprints are nested under the index's `patterns` container, not at
-  // the top level. Each pattern records a single `evidence.cve`, a list of
-  // `controls` (each {framework, control_id}), and a `source_skill`. A
-  // framework match accepts either the bare control id ("SI-2") or the
+  // A framework match accepts either the bare control id ("SI-2") or the
   // qualified "framework::control_id" form the by_control index keys on.
   for (const [id, t] of Object.entries(fp.patterns || {})) {
     if (!t) continue;
@@ -395,9 +314,8 @@ function theaterTestsFor({ cveIds = [], frameworkIds = [], skillIds = [] }) {
 }
 
 /**
- * Global-first framework correlation — given a finding's CVE/TTP set, return
- * the relevant gaps across EU (NIS2/DORA/EU AI Act) + UK (CAF) + AU (ISM /
- * Essential 8) + ISO 27001:2022 + NIST. Satisfies AGENTS.md Hard Rule #5.
+ * Given a finding's CVE/TTP set, the relevant gaps across EU (NIS2/DORA/EU AI
+ * Act), UK (CAF), AU (ISM / Essential 8), ISO 27001:2022 and NIST.
  */
 function globalFrameworkContext({ cveIds = [], ttpIds = [] }) {
   const gaps = loadCatalog('framework-control-gaps.json');
@@ -429,8 +347,6 @@ module.exports = {
   // Lower-level access (engine uses these directly)
   _loadCatalog: loadCatalog,
   _loadIndex: loadIndex,
-  // v0.12.14: surface accumulated catalog/index load errors. Returns
-  // [{kind, file, error}, ...] for every catalog/index whose JSON
-  // parse failed. Empty array on a healthy install.
+  // [{kind, file, error}] per catalog or index whose JSON parse failed.
   getLoadErrors,
 };

package/lib/currency-severity.js

@@ -1,33 +1,15 @@
 "use strict";
 
 /**
- * lib/currency-severity.js
+ * Pure function the `exceptd doctor` verb uses to turn a currency report into a
+ * health verdict, on the ladder orchestrator/pipeline.js scores against:
  *
- * Pure function used by the `exceptd doctor` verb to turn a currency report
- * into a health verdict.
+ *   current (>= 90)               → healthy, in neither bucket
+ *   acceptable (70-89, drifting)  → severity:"warn", ok:true, exit 0
+ *   stale / critical_stale (< 70) → ok:false, exit 1
  *
- * The scoring model in orchestrator/pipeline.js grades every skill on four
- * labels — current (score >= 90), acceptable (70-89), stale (50-69),
- * critical_stale (< 50) — and raises `action_required` only below 70. The
- * pre-extraction predicate in the doctor ignored that ladder and failed on
- * `currency_label !== "current"`, which folded the acceptable tier in with
- * genuine staleness.
- *
- * That made the health check a scheduled failure rather than a signal: a
- * skill's score drops from 90 to 80 the day it crosses 90 days since
- * `last_threat_review`, so any skill will turn `doctor` red on a fixed
- * cadence with no code change and nothing actually wrong.
- *
- * The tiers now map to severity the way the model defines them:
- *
- *   current                     → healthy, no entry in either bucket
- *   acceptable (drifting)       → severity:"warn", ok:true, exit 0
- *   stale / critical_stale      → ok:false (error), exit 1
- *
- * `stale_skills` keeps its original meaning — every skill that is not
- * `current` — so an existing consumer reading it still sees the full picture.
- * `drifting_skills` and `action_required_skills` split that list along the
- * boundary the exit code now respects.
+ * Failing on `currency_label !== "current"` instead folds the acceptable tier in
+ * with real staleness and turns doctor red on a fixed cadence with nothing wrong.
  */
 
 /**
@@ -43,8 +25,7 @@ function classifyCurrency(report, actionRequired) {
   const actionable = rows.filter(s => s.action_required);
   const critical = rows.filter(s => s.currency_score !== undefined && s.currency_score < 50);
 
-  // The report-level flag is honored even when no row carries action_required,
-  // so an upstream that raises the flag some other way still fails closed.
+  // The report-level flag is honored even when no row sets it, so this fails closed.
   const ok = actionable.length === 0 && !actionRequired;
 
   return {

package/lib/cve-batch.js

@@ -1,9 +1,8 @@
 'use strict';
 
-// Batch curation: facts + judgments through cve-enrich.assembleEntry, then the
-// catalog, zeroday-lessons.json and one tests/cve-<id>.test.js per CVE. Nothing
-// is written if any entry has an orphaned reference or an assembly error.
-// CLI: `refresh --curate-batch --facts <path> --judgments <path> [--apply]`.
+// Batch curation via `refresh --curate-batch --facts <p> --judgments <p> [--apply]`:
+// facts + judgments through cve-enrich.assembleEntry into the catalog,
+// zeroday-lessons.json and a per-CVE test. Nothing is written unless all assemble.
 
 const fs = require('fs');
 const path = require('path');
@@ -23,19 +22,15 @@ function _metaEnd(text) {
     else if (c === '"') { i++; while (i < text.length && text[i] !== '"') { if (text[i] === '\\') i++; i++; } }
   }
   const comma = text.indexOf(',', i);
-  // Whitespace-only gap to the next comma means _meta has a following member,
-  // so insert after the separator; otherwise _meta is last and the insert
-  // supplies its own leading comma.
+  // A whitespace-only gap to the next comma means _meta has a following member,
+  // so insert after the separator; otherwise the insert supplies its own comma.
   if (comma !== -1 && text.slice(i, comma).trim() === '') return { at: comma + 1, leadingComma: false };
   return { at: i, leadingComma: true };
 }
 
-// Ids already present as top-level catalog members. insertEntries appends and
-// cannot replace, so writing one twice leaves a duplicate JSON key; JSON.parse
-// keeps the last, which is the stale copy, while every count and schema check
-// still passes. Parsed rather than pattern-matched: a CVE id quoted inside
-// another entry's prose is not a member, and building a RegExp from caller ids
-// would be a ReDoS sink in the one function that exists to distrust them.
+// Ids already present as top-level catalog members. Parsed rather than
+// pattern-matched: a CVE id quoted inside another entry's prose is not a member,
+// and a RegExp built from caller ids would be a ReDoS sink.
 function existingIds(catalogText, ids) {
   let parsed;
   try {
@@ -67,9 +62,8 @@ function insertEntries(catalogText, entriesById) {
 
 function recomputeAiMeta(catalogText, aiCount, total) {
   // current_rate is ROUNDED; the floor is enforced against the RAW rate, so the
-  // floor must be the raw rate FLOORED to 3 decimals. Rounding both leaves a
-  // floor the raw rate cannot clear (0.02262 rounds to 0.023). Only ever lower
-  // the floor — raising it fails the corpus it describes.
+  // floor is the raw rate FLOORED (rounding both leaves 0.02262 facing a 0.023
+  // floor it cannot clear). Only ever lower the floor.
   const rawRate = aiCount / total;
   const rate = Math.round(rawRate * 1000) / 1000;
   let out = catalogText.replace(/("current_rate"\s*:\s*)[0-9.]+/, `$1${rate}`);
@@ -175,8 +169,7 @@ async function curateBatch({ factsPath, judgmentsPath, apply, catalogRoot, today
   const lesObj = addLessons(JSON.parse(fs.readFileSync(lesPath, 'utf8')), lessons);
   fs.writeFileSync(lesPath, JSON.stringify(lesObj, null, 2) + '\n');
 
-  // The id already carries its "CVE-" prefix, so lowercasing alone produces the
-  // repo's tests/cve-<year>-<num>.test.js convention.
+  // The id carries its "CVE-" prefix, so lowercasing gives tests/cve-<y>-<n>.test.js.
   for (const id of Object.keys(entries))
     fs.writeFileSync(path.join(catalogRoot, 'tests', `${id.toLowerCase()}.test.js`), renderTest(id));
 
@@ -191,9 +184,8 @@ async function cli(argv) {
     else if (a === '--judgments') opts.judgments = argv[++i];
     else if (a === '--apply') opts.apply = true;
   }
-  // Inputs are checked before curateBatch so a missing path returns the same
-  // {ok:false} envelope every other refresh-curate error path does, rather than
-  // throwing out of the async function.
+  // Checked before curateBatch so a missing path returns the same {ok:false}
+  // envelope as every other error path, rather than throwing out of the async fn.
   if (!opts.facts || !opts.judgments || !fs.existsSync(opts.facts) || !fs.existsSync(opts.judgments)) {
     const missing = [];
     if (!opts.facts) missing.push('--facts <path>');

package/lib/cve-cli.js

@@ -2,11 +2,9 @@
 "use strict";
 
 /**
- * lib/cve-cli.js — `exceptd cve <CVE-ID>` resolver.
- *
- * Catalog -> resolved cache -> one NVD lookup (cached). Tells an agent whether
- * a cited CVE is published / rejected / disputed / fabricated / nonexistent
- * without it researching NVD by hand. Network is opt-out (--air-gap /
+ * `exceptd cve <CVE-ID>` — catalog, then resolved cache, then one cached NVD
+ * lookup. Reports published / rejected / disputed / fabricated / nonexistent so
+ * an agent need not research NVD by hand. Network is opt-out (--air-gap /
  * --no-network / EXCEPTD_AIR_GAP=1).
  */
 
@@ -15,9 +13,8 @@ const { resolveCve } = require("./citation-resolve.js");
 (async () => {
   const argv = process.argv.slice(2);
   const flags = new Set(argv.filter((a) => a.startsWith("--")));
-  // Reject unknown flags rather than silently ignoring them — the same
-  // contract the in-process verbs enforce. A swallowed `--josn` would emit
-  // human text into a pipe that asked for JSON and defeat a CI gate.
+  // A swallowed `--josn` would emit human text into a pipe that asked for
+  // JSON, so an unknown flag is an error, matching the in-process verbs.
   const KNOWN = new Set(["--json", "--pretty", "--air-gap", "--no-network", "--help", "-h"]);
   const unknown = [...flags].filter((f) => !KNOWN.has(f));
   if (unknown.length > 0) {
@@ -28,9 +25,8 @@ const { resolveCve } = require("./citation-resolve.js");
     process.exitCode = 1;
     return;
   }
-  // Trim the positional so a whitespace-only argument (`cve "   "`) is
-  // treated identically to a missing one (`cve ""`) — a usage error, not a
-  // "fabricated" lookup of the literal spaces.
+  // Trimmed so `cve "   "` is a usage error like `cve ""`, not a "fabricated"
+  // lookup of the literal spaces.
   const rawId = argv.find((a) => !a.startsWith("--"));
   const id = rawId == null ? rawId : rawId.trim();
   const pretty = flags.has("--pretty");
@@ -45,10 +41,9 @@ const { resolveCve } = require("./citation-resolve.js");
   }
 
   const r = await resolveCve(id, { airGap: flags.has("--air-gap"), noNetwork: flags.has("--no-network") });
-  // A citation that won't stand up exits non-zero so a CI/script gate trips.
-  // Derive `ok` from the same set of statuses that drive the exit code — a
-  // non-zero exit must carry ok:false, never the inverted ok:true the
-  // envelope previously hardcoded.
+  // A citation that will not stand up exits non-zero so a CI gate trips, and
+  // `ok` derives from the same statuses — a non-zero exit always carries
+  // ok:false.
   const fails = r.status === "rejected" || r.status === "fabricated" || r.status === "nonexistent" || r.status === "withdrawn";
   const body = { verb: "cve", ...r, ok: !fails };
 
@@ -70,11 +65,9 @@ const { resolveCve } = require("./citation-resolve.js");
     process.exitCode = 2;
   }
 })().catch((err) => {
-  // A corrupt/unreadable catalog (or any unexpected throw inside the async
-  // body) becomes a rejected promise. Emit the same single-line
-  // {ok:false,error} envelope the verb promises rather than crashing with a
-  // raw stack trace, and signal failure via exitCode so the event loop drains
-  // stderr before exit.
+  // Any throw inside the async body arrives here as a rejected promise: emit
+  // the same single-line {ok:false,error} envelope the verb promises rather
+  // than a raw stack, and use exitCode so stderr drains before exit.
   process.stderr.write(JSON.stringify({ ok: false, verb: "cve", error: String((err && err.message) || err) }) + "\n");
   process.exitCode = 1;
 });