@blamejs/exceptd-skills 0.19.32 → 0.19.34

package/lib/validate-cve-catalog.js

@@ -1,24 +1,10 @@
 #!/usr/bin/env node
 /*
- * lib/validate-cve-catalog.js — exceptd CVE catalog validator.
- *
- * Enforces AGENTS.md rule #6 (zero-day learning is live): every CVE in
- * data/cve-catalog.json must have a matching entry in data/zeroday-lessons.json
- * by the same CVE key. The learning loop runs completely, not partially.
- *
- * Also enforces rule #10 (no placeholder data) by validating each CVE entry
- * against the structural rules expressed in
- * lib/schemas/cve-catalog.schema.json — required fields, types, enums,
- * patterns, range constraints. Implemented as an inline validator (no AJV /
- * external deps; Node 24 stdlib only) covering the schema features that
- * file actually uses.
- *
- * Usage:
- *   node lib/validate-cve-catalog.js          validate the full catalog
- *   node lib/validate-cve-catalog.js --quiet  only print failures + summary
- *
- * Exit code: 0 if every CVE validates and has a matching zeroday lesson,
- *            1 otherwise, 2 on argv error.
+ * CVE catalog validator. Every CVE in data/cve-catalog.json must carry a matching
+ * key in data/zeroday-lessons.json (rule #6) and satisfy
+ * lib/schemas/cve-catalog.schema.json, checked by the inline validator below.
+ * Exits 0 when every CVE validates and pairs with a lesson, 1 otherwise, 2 on an
+ * argv error. --strict promotes the advisory warnings to errors.
  */
 
 'use strict';
@@ -38,16 +24,10 @@ const ATTACK_PATH = path.join(REPO_ROOT, 'data', 'attack-techniques.json');
 const D3FEND_PATH = path.join(REPO_ROOT, 'data', 'd3fend-catalog.json');
 const FRAMEWORK_GAPS_PATH = path.join(REPO_ROOT, 'data', 'framework-control-gaps.json');
 
-// v0.12.12 — patterns that mark a verification_sources URL as a public exploit
-// or PoC location. When poc_available: true AND a verification source matches
-// one of these, the entry must carry an `iocs` block per AGENTS.md Hard Rule
-// #14. Surfaced as a warning by default so drafts and pre-IoC entries don't
-// break patch-class compatibility; promoted to an error under --strict.
-// The host-based entries anchor on scheme + host so a lookalike that merely
-// embeds the host as a label (`exploit-db.com.attacker.example`,
-// `not-exploit-db.com`, `evil.com/?ref=packetstormsecurity.com`) is no longer
-// misclassified as a public-exploit source. Verified zero classification
-// change across the live catalog's verification URLs.
+// A verification_sources URL matching one of these marks a public exploit or PoC
+// location; with poc_available true the entry must then carry an `iocs` block
+// (Hard Rule #14). The host patterns anchor on scheme + host, so a lookalike
+// embedding the host as a label does not match.
 const PUBLIC_EXPLOIT_URL_PATTERNS = [
   /^https?:\/\/(?:[\w-]+\.)*github\.com\/.+\/(?:exploits?|pocs?)\b/i,
   /^https?:\/\/(?:[\w-]+\.)*exploit-?db\.com(?:[/:?#]|$)/i,
@@ -57,14 +37,11 @@ const PUBLIC_EXPLOIT_URL_PATTERNS = [
   /-poc\b/i,
 ];
 
-// v0.12.12 — Tightened CVSS-vector prefix. Schema's existing pattern accepts
-// any "CVSS:<digits>/"; the strict pattern below admits only known CVSS
-// versions (2.0 / 3.0 / 3.1 / 4.0). Emitted as a warning by default;
-// promoted to an error under --strict.
+// The schema's own pattern accepts any "CVSS:<digits>/"; this admits only known
+// CVSS versions. A warning by default, an error under --strict.
 const STRICT_CVSS_PATTERN = /^CVSS:(2\.0|3\.[01]|4\.0)\//;
 
-// v0.12.12 — Impossible-date guard. Reject obviously bogus year ranges
-// (typos like 1014 or 20262) without rejecting legitimate ISO dates.
+// Wide enough for any legitimate ISO date, narrow enough to reject a year typo.
 const MIN_VALID_YEAR = 1990;
 const MAX_VALID_YEAR = 2100;
 const DATE_FIELDS = [
@@ -116,10 +93,9 @@ function typeMatches(value, expected) {
   return actual === expected;
 }
 
-/* Validate a value against a (subset of) JSON Schema. The subset we need is
- * what lib/schemas/cve-catalog.schema.json uses: type, required, properties,
- * additionalProperties, items, pattern, minLength, minimum, maximum, minItems,
- * minProperties, enum, format=uri (loose check). */
+/* Handles the JSON Schema subset cve-catalog.schema.json uses: type, required,
+ * properties, additionalProperties, items, pattern, minLength, minimum, maximum,
+ * minItems, minProperties, enum, format=uri. Any other keyword is ignored. */
 function validate(value, schema, schemaName, pathStr) {
   const errors = [];
   const here = pathStr || schemaName;
@@ -220,11 +196,8 @@ function isUsableDate(value) {
   }
   const d = new Date(value + 'T00:00:00Z');
   if (Number.isNaN(d.getTime())) return { ok: false, reason: 'unparseable' };
-  // Reject impossible calendar dates (Feb 30, Apr 31, Feb 29 in a non-leap
-  // year). `new Date('2026-02-30T00:00:00Z')` does NOT throw — it silently
-  // rolls over to March 2 and reports a valid getTime() — so a malformed KEV
-  // deadline would pass this, the only date-validity guard. Require the parsed
-  // Y-M-D to round-trip back to the input components.
+  // `new Date('2026-02-30T00:00:00Z')` does not throw — it rolls over to March 2 —
+  // so a malformed KEV deadline would pass the only date-validity guard.
   const [yStr, mStr, dStr] = value.split('-');
   if (d.getUTCFullYear() !== Number(yStr) ||
       d.getUTCMonth() + 1 !== Number(mStr) ||
@@ -244,17 +217,13 @@ function isUsableDate(value) {
 function additionalChecks(key, entry, ctx) {
   const warnings = [];
 
-  // A non-object entry has no checkable sub-fields, and validate() already
-  // emits the top-level type error for it (lines 127-133). Guarding here turns
-  // the uncaught `entry.poc_available` TypeError on a null/array entry into a
-  // clean no-op so main() still prints that FAIL and continues to later
-  // entries instead of aborting the whole gate. The FAIL is preserved — it
-  // originates in validate(), not here.
+  // validate() already emits the type error, so the FAIL survives this no-op;
+  // without it, entry.* throws and aborts the gate.
   if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
     return [];
   }
 
-  // V1 — Hard Rule #14 conditional: poc + public-exploit URL → iocs required.
+  // Hard Rule #14: poc_available plus a public-exploit URL requires iocs.
   if (entry.poc_available === true) {
     const sources = Array.isArray(entry.verification_sources)
       ? entry.verification_sources
@@ -272,10 +241,7 @@ function additionalChecks(key, entry, ctx) {
     }
   }
 
-  // V2 — Cross-catalog reference resolution. Unresolved refs are warnings
-  // by default; promoted to hard failures under --strict. V2 expansion
-  // extends the walk from cwe_refs only to attack_refs, atlas_refs,
-  // d3fend_refs, AND framework_control_gaps.
+  // Cross-catalog refs: an unresolved id is a warning, an error under --strict.
   const REF_FIELDS = [
     { field: 'atlas_refs', set: ctx.atlasKeys, file: 'data/atlas-ttps.json' },
     { field: 'cwe_refs', set: ctx.cweKeys, file: 'data/cwe-catalog.json' },
@@ -289,22 +255,16 @@ function additionalChecks(key, entry, ctx) {
   ];
   for (const { field, set, file } of REF_FIELDS) {
     if (!set) {
-      // A reference catalog is part of a valid tree, so its absence is not a
-      // "defense-in-depth skip" — it means the ref family CANNOT be validated,
-      // and an orphaned id would ship unchecked. Surface it (promoted to a hard
-      // error under --strict, like an unresolved ref) for any entry that
-      // actually carries the field, rather than passing silently.
+      // An absent catalog means the family cannot be validated, not that it
+      // passed: surface it so an orphaned id cannot ship unchecked.
       if (entry[field] && (Array.isArray(entry[field]) ? entry[field].length > 0 : typeof entry[field] === 'object' && Object.keys(entry[field]).length > 0)) {
         warnings.push(`${key}: cannot validate ${field} — ${file} catalog is absent, so its ids go unchecked (an error under --strict).`);
       }
       continue;
     }
     const refs = entry[field];
-    // Most ref fields are arrays of id strings (atlas_refs, cwe_refs, ...),
-    // but framework_control_gaps is a map keyed BY control id. An
-    // Array.isArray-only guard skipped the map form entirely, so orphaned
-    // control ids never surfaced. Derive the candidate ids from whichever
-    // shape the field uses: array elements, or the keys of a plain object.
+    // Most ref fields are arrays of ids, but framework_control_gaps is a map keyed
+    // BY control id — an Array.isArray-only guard lets orphaned ids through.
     let ids;
     if (Array.isArray(refs)) {
       ids = refs;
@@ -323,11 +283,8 @@ function additionalChecks(key, entry, ctx) {
     }
   }
 
-  // V5 — KEV status must carry its date (AGENTS.md Hard Rule #1: a KEV flag
-  // without a date is an incomplete threat-intel claim; RWEP scoring and the
-  // jurisdiction-clock SLAs key off the KEV listing date). cisa_kev=true with a
-  // null/missing/invalid cisa_kev_date is flagged; promoted to a hard error
-  // under --strict (predeploy). 0 violations in the shipped catalog today.
+  // Hard Rule #1: RWEP scoring and the jurisdiction-clock SLAs key off the KEV
+  // listing date, so a KEV flag without one is an incomplete claim.
   if (entry.cisa_kev === true) {
     const d = entry.cisa_kev_date;
     const dateOk = typeof d === 'string' && isUsableDate(d).ok;
@@ -336,12 +293,9 @@ function additionalChecks(key, entry, ctx) {
         `${key}: cisa_kev=true but cisa_kev_date is ${JSON.stringify(d)} (KEV status must carry a valid listing date — Hard Rule #1)`,
       );
     }
-    // The ransomware designation is part of the same KEV record and drives
-    // operator prioritisation, but an omitted boolean reads to every consumer
-    // as false — so an entry CISA has designated and that simply never wrote
-    // the field is indistinguishable from one CISA has not. Both readings are
-    // available only while the field can be absent, so on a KEV-listed entry it
-    // may not be.
+    // An omitted boolean reads to every consumer as false, so a designation CISA
+    // made is indistinguishable from one it did not make. On a KEV entry the
+    // field may not be absent.
     if (typeof entry.known_ransomware_use !== 'boolean') {
       warnings.push(
         `${key}: cisa_kev=true but known_ransomware_use is ${JSON.stringify(entry.known_ransomware_use)} (an absent boolean is read as false, which asserts a designation CISA may not agree with)`,
@@ -349,7 +303,6 @@ function additionalChecks(key, entry, ctx) {
     }
   }
 
-  // V4 — Impossible-date guard.
   for (const f of DATE_FIELDS) {
     const v = entry[f];
     if (v === undefined || v === null) continue;
@@ -359,8 +312,6 @@ function additionalChecks(key, entry, ctx) {
     }
   }
 
-  // Sch1 — strict CVSS-vector prefix (warning-only for v0.12.12). The schema
-  // pattern stays loose; this admits only known CVSS versions.
   if (typeof entry.cvss_vector === 'string' && entry.cvss_vector.length > 0) {
     if (!STRICT_CVSS_PATTERN.test(entry.cvss_vector)) {
       warnings.push(
@@ -372,10 +323,8 @@ function additionalChecks(key, entry, ctx) {
   return warnings;
 }
 
-// Return the list of catalogs whose hand-maintained _meta.entry_count disagrees
-// with the live count of non-metadata top-level keys. Catalogs without a numeric
-// _meta.entry_count (or absent/null catalogs) are skipped, so any loaded catalog
-// that adopts the field is covered without editing this function.
+// Catalogs without a numeric _meta.entry_count, and absent ones, are skipped, so
+// one that adopts the field is covered without editing here.
 function entryCountMismatches(catalogs) {
   const failures = [];
   for (const { name, catalog: cat } of catalogs) {
@@ -395,14 +344,8 @@ function main() {
   const schema = readJson(SCHEMA_PATH);
   const catalog = readJson(CATALOG_PATH);
   const lessons = readJson(LESSONS_PATH);
-  // All five reference catalogs default to null when absent so the
-  // "cannot validate — catalog absent" branch in additionalChecks fires
-  // uniformly for every ref family. atlas/cwe previously defaulted to {},
-  // which built an EMPTY Set (never null) — so an absent atlas/cwe catalog
-  // silently FLAGGED every ref as unresolved (false positive) instead of
-  // surfacing the catalog-absent warning, the asymmetric opposite of how
-  // attack/d3fend/framework behaved. Uniform null makes the absence
-  // observable rather than misclassified.
+  // null when absent, never {}: an empty object builds an empty Set that is never
+  // null, so every ref would flag unresolved instead of firing the absent branch.
   const atlas = fs.existsSync(ATLAS_PATH) ? readJson(ATLAS_PATH) : null;
   const cwe = fs.existsSync(CWE_PATH) ? readJson(CWE_PATH) : null;
   const attack = fs.existsSync(ATTACK_PATH) ? readJson(ATTACK_PATH) : null;
@@ -432,13 +375,8 @@ function main() {
   const cveKeys = Object.keys(catalog).filter((k) => !k.startsWith('_'));
   const lessonKeys = new Set(Object.keys(lessons).filter((k) => !k.startsWith('_')));
 
-  // v0.13.5: cross-check that the schema's active_exploitation enum
-  // matches catalog._meta.active_exploitation_vocabulary.values. Pre-fix
-  // the two could drift independently (the v0.12.41 _meta block had 5
-  // values, the schema enum had 4 — operators reading the _meta vocab
-  // got a list that the validator wouldn't accept). v0.13.5 reconciled
-  // by adding "theoretical" to the schema; this cross-check refuses any
-  // future drift.
+  // The schema's active_exploitation enum and _meta.active_exploitation_vocabulary
+  // must agree exactly, or operators read a vocabulary the validator rejects.
   const schemaEnum = ((schema.properties || {}).active_exploitation || {}).enum;
   const metaVocab = (catalog._meta && catalog._meta.active_exploitation_vocabulary && catalog._meta.active_exploitation_vocabulary.values) || null;
   if (Array.isArray(schemaEnum) && Array.isArray(metaVocab)) {
@@ -459,13 +397,7 @@ function main() {
     }
   }
 
-  // Guard hand-maintained _meta.entry_count fields against silent drift. The
-  // framework-control-gaps counter once declared 184 while the file held 192
-  // and nothing caught it; the zeroday-lessons counter drifted to 68 while the
-  // file held 422 because only framework-control-gaps was gated. This checks
-  // EVERY loaded catalog that declares a numeric _meta.entry_count, so a new
-  // catalog with the field is covered automatically. The covered set is derived
-  // from the catalogs main() already loaded, not a fixed allowlist.
+  // Guards the hand-maintained _meta.entry_count fields against silent drift.
   const ENTRY_COUNT_CATALOGS = [
     { name: 'cve-catalog', catalog },
     { name: 'zeroday-lessons', catalog: lessons },
@@ -490,7 +422,6 @@ function main() {
   let drafts = 0;
   let warned = 0;
 
-  // V3 — Duplicate-name detection across all non-_meta entries.
   const nameToKeys = new Map();
   for (const k of cveKeys) {
     const n = catalog[k] && catalog[k].name;
@@ -510,11 +441,8 @@ function main() {
 
   for (const key of cveKeys) {
     const entry = catalog[key];
-    // v0.12.0: GHSA-imported drafts are flagged `_auto_imported: true` +
-    // `_draft: true`. They pass validation as WARNINGS (printed but not
-    // exit-failing) so the nightly auto-PR pipeline can ship them while
-    // editorial fields await human or AI-assisted enrichment via
-    // `exceptd run cve-curation --advisory <id>`.
+    // Drafts validate as warnings, never failures, so the nightly auto-PR ships
+    // them while their editorial fields await enrichment.
     const isDraft = entry && (entry._auto_imported === true || entry._draft === true);
     const errors = validate(entry, schema, 'cve', key);
     let warnings = additionalChecks(key, entry, ctx);
@@ -523,8 +451,7 @@ function main() {
         `${key}: missing matching entry in data/zeroday-lessons.json (rule #6: zero-day learning is live)`,
       );
     }
-    // F20 — --strict promotes per-CVE warnings to errors. Drafts are
-    // exempt (drafts already exit non-fail).
+    // --strict promotes per-CVE warnings to errors; drafts stay exempt.
     if (opts.strict && !isDraft) {
       errors.push(...warnings);
       warnings = [];
@@ -536,7 +463,6 @@ function main() {
         for (const e of errors) console.log(`        - [warn] ${e}`);
         for (const w of warnings) console.log(`        - [warn] ${w}`);
       }
-      // Drafts don't increment `failed` — they're warnings, not errors.
       continue;
     }
     if (errors.length === 0 && warnings.length === 0) {
@@ -553,9 +479,8 @@ function main() {
     }
   }
 
-  /* Reverse check: every zeroday lesson should map to a real CVE. Not strictly
-   * required by AGENTS.md but a stale lesson with no catalog entry is exactly
-   * the placeholder propagation rule #6 wants to catch. */
+  /* The other direction: a lesson with no catalog entry is the placeholder
+   * propagation rule #6 exists to catch. */
   for (const lessonKey of lessonKeys) {
     if (!cveKeys.includes(lessonKey)) {
       failed++;
@@ -566,7 +491,6 @@ function main() {
     }
   }
 
-  // V3 — emit duplicate-name warnings as a catalog-wide tail block.
   for (const w of dupNameWarnings) {
     console.log(`WARN  catalog`);
     console.log(`        - [warn] ${w}`);
@@ -579,7 +503,7 @@ function main() {
     (warned ? `, ${warned} with warnings` : '') +
     (failed ? `, ${failed} failed` : '') + '.';
   console.log(summary);
-  // process.exitCode + return so buffered output drains.
+  // process.exitCode, not process.exit() — the exit can truncate a piped write.
   process.exitCode = failed === 0 ? 0 : 1;
 }
 

package/lib/validate-indexes.js

@@ -1,26 +1,8 @@
 "use strict";
 /**
- * lib/validate-indexes.js
- *
- * Predeploy gate. Confirms that `data/_indexes/*.json` is current
- * against the canonical sources (manifest.json + every data/*.json
- * minus _indexes/* + every skill body).
- *
- * Strategy:
- *   1. Load `data/_indexes/_meta.json` for the source SHA-256 table.
- *   2. Re-hash every listed source file.
- *   3. Fail if any hash diverges (the indexes are stale).
- *   4. Fail if a new source file exists that's not in the index (the
- *      index doesn't reflect current state).
- *   5. Fail if source_hashes is empty (build-indexes never ran).
- *   6. Fail if any data/*.json or listed source is a symlink.
- *
- * Exit 0 on success, 1 on staleness.
- *
- * Run as: node lib/validate-indexes.js
- * Or as predeploy gate via scripts/predeploy.js.
- *
- * Re-build with: npm run build-indexes
+ * Predeploy gate. Confirms `data/_indexes/*.json` is current against the
+ * canonical sources by re-hashing each against the SHA-256 table in
+ * data/_indexes/_meta.json. Exit 0 when current, 1 when stale.
  */
 
 const fs = require("fs");
@@ -37,17 +19,14 @@ function sha256(buf) {
 }
 
 /**
- * Confirm every derived index OUTPUT exists, is a real file, and parses as
- * JSON. Returns an array of human-readable issue strings (empty = all good).
- * Source-hash drift alone does NOT catch a deleted/truncated/corrupted output,
- * so this runs in addition to the source-hash comparison.
+ * Confirm every derived index OUTPUT exists, is a real file, and parses as JSON.
+ * Returns human-readable issue strings (empty = all good).
  */
 function verifyOutputs(idxDir, outputs) {
   const issues = [];
-  // O_NOFOLLOW + a single descriptor: the open atomically refuses a symlinked
-  // index path (ELOOP) and every subsequent stat/read rides the same fd, so
-  // there is no existsSync->lstat->readFileSync TOCTOU on the path. Where
-  // O_NOFOLLOW is unavailable the flag degrades to 0 (plain open).
+  // O_NOFOLLOW plus a single descriptor: the open atomically refuses a symlinked
+  // index path (ELOOP) and every read rides the same fd, so there is no
+  // existsSync->lstat->readFileSync TOCTOU. Where unavailable the flag is 0.
   const O_NOFOLLOW = fs.constants.O_NOFOLLOW || 0;
   for (const file of outputs) {
     const abs = path.join(idxDir, file);
@@ -65,10 +44,8 @@ function verifyOutputs(idxDir, outputs) {
       continue;
     }
     try {
-      // readFileSync(fd) loops read() to EOF — a single readSync may return
-      // fewer than st.size bytes (short read on a network/FUSE-backed fd),
-      // leaving the tail NUL-filled and truncating the JSON. Reading via the
-      // open fd keeps the open→fstat ordering TOCTOU-free.
+      // readFileSync(fd) loops read() to EOF — a single readSync can return fewer
+      // than st.size bytes on a network fd, NUL-filling the tail.
       JSON.parse(fs.readFileSync(fd, "utf8"));
     } catch (e) {
       issues.push(`derived index file does not parse: data/_indexes/${file} (${e.message})`);
@@ -80,14 +57,8 @@ function verifyOutputs(idxDir, outputs) {
 }
 
 /**
- * Compare a live source set against the recorded source_hashes table and return
- * { drift, missing } message arrays. Pure (no I/O of its own beyond the injected
- * absFn + fs reads of the named sources) so it is unit-testable for the
- * fail-closed edge cases:
- *   - a source that vanished between discovery and hashing (TOCTOU) is REPORTED
- *     missing, never an unhandled ENOENT crash;
- *   - a non-string recorded hash (corrupted _meta.json) is REPORTED as drift,
- *     never a TypeError from .slice() of a non-string.
+ * Compare a live source set against the recorded source_hashes table. Fail-closed:
+ * a vanished source and a non-string recorded hash are both REPORTED, never thrown.
  *
  * @param {Set<string>|string[]} liveSources  source paths discovered live
  * @param {Record<string,string>} recorded    the _meta.json source_hashes table
@@ -104,15 +75,9 @@ function checkSourceHashes(liveSources, recorded, absFn) {
       continue;
     }
     const abs = absFn(p);
-    // F16 — also check listed-but-symlinked sources. A source can disappear or
-    // be swapped between discovery and hashing (TOCTOU); resolve its type and
-    // read it defensively so a vanished or newly-symlinked file is REPORTED as
-    // missing, never an unhandled ENOENT that crashes the whole validation.
     // Open through a single O_NOFOLLOW descriptor and hash the bytes from THAT
-    // descriptor — no path stat-then-read, so there is no check-then-use window.
-    // O_NOFOLLOW refuses a symlinked leaf at open (ELOOP) on POSIX; an absent
-    // file (ENOENT) is reported missing instead of crashing; the fstat type
-    // check refuses a dir/junction/fifo on every platform.
+    // descriptor: no path stat-then-read, so no check-then-use window. The fstat
+    // type check refuses a dir / junction / fifo on every platform.
     let live;
     {
       let fd;
@@ -136,9 +101,6 @@ function checkSourceHashes(liveSources, recorded, absFn) {
     }
     const recordedHash = recorded[p];
     if (typeof recordedHash !== 'string') {
-      // A null/non-string recorded hash means a corrupted _meta.json
-      // source_hashes map — report it as drift rather than crashing on
-      // .slice() of a non-string (fail-closed, not fail-open).
       drift.push(`hash drift: ${p} (recorded entry is not a string: ${JSON.stringify(recordedHash)}, live ${live.slice(0, 12)}…)`);
     } else if (live !== recordedHash) {
       drift.push(`hash drift: ${p} (recorded ${recordedHash.slice(0, 12)}…, live ${live.slice(0, 12)}…)`);
@@ -155,7 +117,8 @@ function checkSourceHashes(liveSources, recorded, absFn) {
 function main() {
   if (!fs.existsSync(META)) {
     console.error("[validate-indexes] data/_indexes/_meta.json missing — run `npm run build-indexes`.");
-    // v0.11.13 pattern: exitCode + return so async stdout/stderr writes drain.
+    // `process.exitCode` + return, never process.exit(): a piped stderr write
+    // can be truncated by the exit. Same for every other exit path below.
     process.exitCode = 1;
     return;
   }
@@ -163,12 +126,8 @@ function main() {
   const meta = JSON.parse(fs.readFileSync(META, "utf8"));
   const recorded = meta.source_hashes || {};
 
-  // reject an empty source_hashes table outright. The previous
-  // gate would silently pass when source_hashes was {} (or missing entirely)
-  // because the for-loop body never executed; the resulting "0 sources" pass
-  // banner falsely advertised the indexes as current. An empty source-hash
-  // table means build-indexes was never run, or was run against an empty
-  // repo, and the index files themselves are not trustworthy.
+  // An empty source_hashes table is a hard fail, not a "0 sources" pass: the
+  // comparison loop never runs, so an empty table would advertise them current.
   if (Object.keys(recorded).length === 0) {
     console.error(
       "[validate-indexes] data/_indexes/_meta.json source_hashes is empty — " +
@@ -179,19 +138,14 @@ function main() {
     return;
   }
 
-  // Discover the current canonical source set.
   const manifest = JSON.parse(fs.readFileSync(ABS("manifest.json"), "utf8"));
   const liveSources = new Set();
   liveSources.add("manifest.json");
-  // README.md is consumed by the stale-content index builder (badge-count
-  // drift), so build-indexes hashes it as a source. Keep this validator's
-  // source set in sync — otherwise the hashed README looks like a removed
-  // file here. (Mirrors liveSourceSet() in scripts/build-indexes.js.)
+  // This set mirrors liveSourceSet() in scripts/build-indexes.js, which hashes
+  // README.md for the stale-content index; out of sync, README reads as removed.
   if (fs.existsSync(ABS("README.md"))) liveSources.add("README.md");
-  // use lstat to detect symlinks. A symlinked .json under data/
-  // would be hashed via the followed target, allowing a malicious checkout
-  // (or a misconfigured filesystem) to swap data origin without tripping the
-  // gate. Reject symlinks outright.
+  // lstat, not stat: a symlinked .json under data/ would be hashed through its
+  // target, letting a checkout swap the data origin without tripping the gate.
   for (const f of fs.readdirSync(ABS("data"))) {
     if (!f.endsWith(".json")) continue;
     const abs = ABS("data/" + f);
@@ -210,14 +164,9 @@ function main() {
 
   const { drift, missing } = checkSourceHashes(liveSources, recorded, ABS);
 
-  // Verify the derived index OUTPUTS themselves exist and parse. Source-hash
-  // drift alone does not catch a deleted/truncated/corrupted OUTPUT: a clean
-  // source tree with a missing index file would otherwise pass as "current".
-  // _meta.outputs is the canonical list build-indexes records; an absent list
-  // FAILS (rather than silently skipping the check) so an old _meta can't pass.
-  // Absent `outputs` list (an older build that predates this field) is itself a
-  // staleness condition — fold it into the unified STALE report rather than
-  // early-returning, so a concurrent source-hash drift still surfaces too.
+  // Source-hash drift alone does not catch a deleted or corrupted OUTPUT.
+  // _meta.outputs is the canonical list build-indexes records; an absent list is
+  // itself staleness, folded into the STALE report so hash drift still surfaces.
   const outputs = Array.isArray(meta.outputs) ? meta.outputs : null;
   if (!outputs || outputs.length === 0) {
     missing.push(