@blamejs/exceptd-skills 0.19.33 → 0.19.35

package/scripts/check-test-count.js

@@ -2,41 +2,15 @@
 'use strict';
 
 /**
- * scripts/check-test-count.js — v0.13.2 canonical-test-count predeploy gate.
+ * Canonical-test-count predeploy gate: catches test-set shrinkage the lint and
+ * diff-coverage gates cannot see.
  *
- * Why this exists. The v0.12 audit flagged that nothing in the suite asserts
- * "we expect N tests today." A deleted test file, a removed `test(` call, or a
- * misnamed file glob-excluded would all silently drop tests without anyone
- * noticing. The lint + diff-coverage gates catch source changes; this gate
- * catches test-set shrinkage.
+ * Counts DECLARATIONS statically across `tests/*.test.js` — `test(` and `it(`
+ * with their `.only` / `.skip` variants. `describe(` is NOT counted: a container
+ * is not a test. Blind spot: a test neutered in place still counts as one.
  *
- * Scope + blind spot. This counts test DECLARATIONS, so it detects deleted
- * files / removed `test(`/`it(` calls / glob-exclusions. It does NOT detect a
- * test neutered in place: `test('name', { skip: true }, fn)`, `test.skip(`,
- * and `it.skip(` all still count as one declaration, so flipping a running
- * test to permanently skipped leaves the count unchanged. Guarding against
- * skip-in-place would need runnable-vs-skipped tracking; that is out of scope
- * for this gate.
- *
- * Mechanism: count `test(`/`it(` declarations (including the `.only`/`.skip`
- * variants) across `tests/*.test.js` via static analysis (faster than
- * running). node:test supports both `test()` and the BDD-style `it()`/
- * `describe()` aliases as first-class declarations, and the suite mixes both,
- * so counting only `test(` was blind to every `it(` test. `describe(` is NOT
- * counted — those are containers, not tests, so counting them would inflate
- * the total and conflate removing a grouping block with removing a test.
- * Compare to a baseline pinned in `tests/.test-count-baseline.json`. Fail if
- * the observed count drops MORE than the configured tolerance (default 1)
- * below the baseline. Growth above baseline is fine; if the count grows by
- * more than `update_baseline_when_growth_exceeds`, surface a notice that the
- * baseline file should be refreshed (operator commits the refresh as part
- * of the release that added the tests).
- *
- * Output:
- *   stdout: structured JSON when --json, else a one-line summary
- *   exit 0: observed count is at or above baseline minus tolerance
- *   exit 1: observed count dropped beyond tolerance — fail predeploy
- *   exit 2: baseline file missing or malformed
+ * exit 0 at or above baseline minus tolerance, 1 when it drops further, 2 when
+ * the baseline file is missing or malformed.
  */
 
 const fs = require('fs');
@@ -63,16 +37,13 @@ function listTestFiles(dir) {
 
 function countTests(filePath) {
   let text = fs.readFileSync(filePath, 'utf8');
-  // Strip block comments first so a `/* test('x'); */`-disabled test is not
-  // counted — the most common "temporarily disable" action, which previously
-  // defeated this gate's entire purpose (it only stripped whole-line `//`).
+  // Strip block comments first: commenting a test out is the usual way to
+  // disable one, and counting it anyway defeats the gate.
   text = text.replace(/\/\*[\s\S]*?\*\//g, '');
   let count = 0;
   for (const rawLine of text.split('\n')) {
-    // Blank out single-line string/template literal BODIES first so a `test(`
-    // mentioned inside a string (e.g. an assertion on output text, or this very
-    // file's docstring examples) is not miscounted as a declaration — that
-    // phantom inflated the baseline and could mask a real test deletion.
+    // Blank string and template bodies first, so a `test(` inside a string
+    // literal is not read as a declaration — a phantom inflates the baseline.
     const noStrings = rawLine.replace(/'(?:[^'\\]|\\.)*'|"(?:[^"\\]|\\.)*"|`(?:[^`\\]|\\.)*`/g, "''");
     // Drop a trailing line comment too (`test('x'); // disabled`).
     const stripped = noStrings.replace(/\/\/.*$/, '').trim();
@@ -86,11 +57,8 @@ function main() {
   const wantJson = process.argv.includes('--json');
   const wantUpdate = process.argv.includes('--update-baseline');
 
-  // Read the baseline once and branch on the read RESULT, not on a prior
-  // existsSync probe. A separate existsSync(BASELINE_PATH)-then-read opens a
-  // check-then-use window (CodeQL js/file-system-race) where the file the
-  // gate decides about is not the file it later reads. ENOENT from the single
-  // read IS the "missing" signal — no second path access needed.
+  // Branch on the read RESULT, never on a prior existsSync probe: ENOENT from
+  // this single read IS the "missing" signal.
   let baselineRaw = null;
   try {
     baselineRaw = fs.readFileSync(BASELINE_PATH, 'utf8');
@@ -99,13 +67,10 @@ function main() {
       console.error(`[check-test-count] cannot read baseline: ${e.message}`);
       process.exit(2);
     }
-    // ENOENT — baseline absent.
     if (wantUpdate) {
       const files = listTestFiles(TESTS_DIR);
       const observed = files.reduce((n, f) => n + countTests(f), 0);
-      // Exclusive create ('wx'): fails with EEXIST if the file appeared
-      // between the read above and this write, so we never clobber a baseline
-      // a concurrent run just produced — atomic, no check-then-write window.
+      // Exclusive create: EEXIST rather than clobbering a concurrent run's baseline.
       fs.writeFileSync(BASELINE_PATH, JSON.stringify({
         baseline: observed,
         tolerance: 1,
@@ -173,9 +138,7 @@ function main() {
     console.error(`[check-test-count] FAIL - test count dropped from ${baseline} to ${observed} (delta ${delta}, tolerance -${tolerance}).`);
     console.error('[check-test-count] Either a test file was accidentally removed, a test()/it() invocation was deleted, OR the baseline is stale.');
     console.error('[check-test-count] If the drop is intentional, run: node scripts/check-test-count.js --update-baseline');
-    // exitCode + return (not process.exit) so the buffered stdout write above
-    // (the --json result / one-line summary) drains before the event loop ends
-    // — process.exit() can truncate piped output.
+    // `process.exitCode`, not `process.exit()`: the buffered stdout write must drain.
     process.exitCode = 1;
     return;
   }

package/scripts/check-test-coverage.js

@@ -1,38 +1,17 @@
 #!/usr/bin/env node
 "use strict";
 /**
- * scripts/check-test-coverage.js
+ * Diff-aware test-coverage gate. Compares the changed surface in the working
+ * tree (or a staged set, or any --base..HEAD range) against the tests/ tree
+ * and reports any surface change that lacks a covering test.
  *
- * Diff-aware test-coverage gate. Compares the changed surface in the
- * working tree (or a staged set, or any --base..HEAD range) against the
- * tests/ tree and reports any surface change that lacks a covering test.
+ * Surfaces: CLI verbs and flags in bin/exceptd.js, exported functions in
+ * lib / orchestrator / scripts, playbook detect-indicator and look-artifact
+ * ids, and CVE entries whose iocs changed. Docs, tooling dotfiles, tests/
+ * itself and derived indexes are allowlisted; workflows, manifests, schemas,
+ * SBOM and unclassified files are surfaced as manual-review, never auto-green.
  *
- * Surfaces detected:
- *   - bin/exceptd.js                CLI verbs / flags (COMMANDS / PLAYBOOK_VERBS)
- *   - lib/*.js, orchestrator/*.js,
- *     scripts/*.js                  exported functions (module.exports = {...})
- *   - data/playbooks/*.json         detect.indicators[].id + look.artifacts[].id
- *   - data/cve-catalog.json         CVE entries whose iocs field changed
- *
- * Categorization (no test required):
- *   - *.md outside data/, .gitignore, .npmrc, .editorconfig
- *   - CHANGELOG.md / README.md / CONTRIBUTING.md / SECURITY.md
- *   - whitespace-only diffs (re-run with --ignore-all-space)
- *   - tests/** changes (no recursion)
- *   - .github/workflows/*.yml      surfaced as manual-review-required
- *   - skills/<name>/skill.md       satisfied by Ed25519 verify gate
- *
- * Exit codes:
- *   0  no uncovered surface (or --warn-only)
- *   1  uncovered surface detected
- *   2  runner error (bad flag, git failure, etc.)
- *
- * Flags:
- *   --base <ref>     compare HEAD against <ref> (default: origin/main)
- *   --staged         use the staged index against HEAD
- *   --json           emit machine-readable report on stdout
- *   --warn-only      print but never exit non-zero
- *   --help, -h       this help
+ * Exit codes: 0 clean or --warn-only, 1 uncovered surface, 2 runner error.
  */
 
 const fs = require("fs");
@@ -41,8 +20,6 @@ const childProc = require("child_process");
 
 const ROOT = path.resolve(__dirname, "..");
 
-// --- Flag parsing -----------------------------------------------------------
-
 function parseArgs(argv) {
   const out = { base: "origin/main", staged: false, json: false, warnOnly: false };
   for (let i = 0; i < argv.length; i++) {
@@ -60,15 +37,29 @@ function parseArgs(argv) {
 
 function printHelp() {
   const banner =
+    "check-test-coverage — report changed surface that no test covers.\n" +
+    "\n" +
     "Usage: node scripts/check-test-coverage.js [--base <ref>] [--staged]\n" +
     "                                          [--json] [--warn-only]\n" +
     "\n" +
-    "See file header for full surface + categorization rules.\n";
+    "Flags:\n" +
+    "  --base <ref>   compare against <ref>..HEAD (default: origin/main)\n" +
+    "  --staged       compare the staged set instead of a ref range\n" +
+    "  --json         emit the result as JSON instead of a text report\n" +
+    "  --warn-only    report findings but always exit 0\n" +
+    "\n" +
+    "Surfaces checked: CLI verbs and flags in bin/exceptd.js, exported functions\n" +
+    "in lib / orchestrator / scripts, playbook detect-indicator and look-artifact\n" +
+    "ids, and CVE entries whose iocs changed.\n" +
+    "\n" +
+    "Categorization: docs, tooling dotfiles, tests/ itself and derived indexes are\n" +
+    "allowlisted; workflows, manifests, schemas, SBOM and unclassified files are\n" +
+    "surfaced as manual-review, never auto-green.\n" +
+    "\n" +
+    "Exit codes: 0 clean or --warn-only, 1 uncovered surface, 2 runner error.\n";
   process.stdout.write(banner);
 }
 
-// --- Git plumbing -----------------------------------------------------------
-
 function git(args, cwd) {
   const r = childProc.spawnSync("git", args, { cwd, encoding: "utf8" });
   if (r.status !== 0) {
@@ -79,29 +70,14 @@ function git(args, cwd) {
   return r.stdout;
 }
 
-// v0.12.8: resolve the diff anchor ONCE up front and thread the resolved SHA
-// through every per-file computation. Pre-fix, listChangedFiles() resolved
-// `opts.base` to a merge-base but fileDiff()/fileBefore() still used the raw
-// `opts.base` ref — so if origin/main advanced past the merge-base between
-// the file-list call and the per-file diff calls, the analyzer compared
-// per-file content against a newer upstream tree than the file list itself
-// was derived from. Result: false "added/removed" surface findings or real
-// findings masked. Codex P1 flag on PR #2 of v0.12.8.
+// The diff anchor resolves ONCE and the resolved SHA threads through every
+// per-file call: passing the raw ref lets origin/main advance mid-run, comparing
+// content against a newer tree than the file list came from.
 function resolveBaseRef(opts, cwd) {
   if (opts.staged) return null; // staged mode uses --cached / HEAD throughout
-  // F14 — fall back gracefully when origin/main is unreachable. The
-  // original implementation tried `merge-base HEAD <opts.base>` and, on
-  // failure, returned opts.base verbatim — which then failed every
-  // subsequent git invocation, surfacing as a runner-level error. In CI
-  // (full clones) the original ref usually resolves; on a developer
-  // laptop without `origin/main` configured (fresh clone, detached
-  // worktree, alternative remote name) the gate would fail entirely.
-  //
-  // Order of preference:
-  //   1. merge-base against the requested base
-  //   2. requested base verbatim, if `git rev-parse --verify` resolves it
-  //   3. local `main` HEAD if it exists
-  //   4. HEAD~1 as a last resort (single-commit diff)
+  // origin/main is not always reachable — fresh clone, detached worktree, remote
+  // under another name — and an unresolvable ref fails every later git call as a
+  // runner error rather than a coverage result.
   const tryResolve = (ref) => {
     try {
       git(["merge-base", "HEAD", ref], cwd).trim();
@@ -160,12 +136,9 @@ function fileDiff(opts, file, cwd, ignoreWs, resolvedBase) {
 }
 
 function fileAtRef(file, ref, cwd) {
-  // v0.13.18: bumped maxBuffer from the Node default (1 MiB on Windows)
-  // to 64 MiB so large catalog files (data/rfc-references.json is ~3 MiB;
-  // data/cve-catalog.json is ~600 KiB) don't ENOBUFS-truncate. A null
-  // return is the documented "missing" sentinel — silent truncation
-  // would make every entry in the live file appear as a fresh add and
-  // generate hundreds of bogus diff-coverage findings.
+  // maxBuffer far above Node's 1 MiB default: an ENOBUFS-truncated read of a
+  // multi-MiB catalog makes every entry in the live file look freshly added.
+  // Null is the "missing" sentinel, so a failure never returns partial content.
   const r = childProc.spawnSync("git", ["show", ref + ":" + file], {
     cwd, encoding: "utf8", maxBuffer: 64 * 1024 * 1024
   });
@@ -190,23 +163,14 @@ function readMaybe(p) {
   try { return fs.readFileSync(p, "utf8"); } catch { return null; }
 }
 
-// --- Categorization ---------------------------------------------------------
-
-// Mechanical / contributor-only docs the gate auto-allows: their content
-// has no operator-facing semantic surface (CONTRIBUTING is for PRs;
-// LICENSE / NOTICE / CODE_OF_CONDUCT are boilerplate; .gitignore / .npmrc
-// / .editorconfig are tooling). Edits here never need a regression test.
+// Contributor-only docs and tooling dotfiles: no semantic surface to test.
 const DOCS_ALWAYS_GREEN = new Set([
   "CONTRIBUTING.md", "LICENSE", "NOTICE", "CODE_OF_CONDUCT.md",
   "SUPPORT.md", ".gitignore", ".npmrc", ".editorconfig",
 ]);
 
-// Operator-facing docs (release notes, install instructions, security
-// disclosure policy, migration guides, AI-assistant ground truth) must not
-// auto-green — a PR could otherwise land deceptive copy here without any
-// reviewer signal. Downgrade to manual-review so the diff surfaces in the
-// gate output — a human (or the maintainer reviewing the bot summary) at
-// least sees the change exists.
+// Operator-facing docs must not auto-green — a PR could otherwise land
+// deceptive copy with no reviewer signal — so they downgrade to manual-review.
 const DOCS_MANUAL_REVIEW = new Set([
   "CHANGELOG.md", "README.md", "SECURITY.md", "MIGRATING.md", "AGENTS.md",
 ]);
@@ -226,20 +190,14 @@ function categorize(file) {
   if (norm.startsWith("scripts/") && norm.endsWith(".js")) return "lib";
   if (norm.startsWith("data/playbooks/") && norm.endsWith(".json")) return "playbook";
   if (norm === "data/cve-catalog.json") return "cve-catalog";
-  // F11 — files matching catalog/schema/SBOM shapes are surfaced for manual
-  // review rather than silent allowlist. These changes (manifest.json,
-  // schemas/*, data/*.json, sbom.cdx.json, manifest-snapshot.*) can carry
-  // semantic surface but the analyzer has no syntactic surface extractor
-  // for them — humans should look.
+  // Shapes carrying semantic surface the analyzer has no extractor for: a human
+  // looks, instead of an allowlist.
   if (norm === "manifest.json") return "manual-review";
   if (norm === "manifest-snapshot.json") return "manual-review";
   if (norm === "manifest-snapshot.sha256") return "manual-review";
   if (norm === "sbom.cdx.json") return "manual-review";
   if (norm.startsWith("lib/schemas/")) return "manual-review";
-  // v0.12.14: data/_indexes/ is auto-regenerated from data/ + manifest by
-  // `npm run build-indexes`; the source-of-truth diff is in the data/
-  // files themselves. Allowlist the derived index files so they don't
-  // perpetually surface as manual-review on every release commit.
+  // data/_indexes/ is regenerated; the reviewable diff is in the data/ sources.
   if (norm.startsWith("data/_indexes/")) return "allowlist-derived";
   if (norm.startsWith("data/") && norm.endsWith(".json")) return "manual-review";
   if (norm === "package.json") return "manual-review";
@@ -252,14 +210,11 @@ function isWhitespaceOnly(opts, file, cwd, resolvedBase) {
     .filter(l => !l.startsWith("+++") && !l.startsWith("---")).length === 0;
 }
 
-// --- Surface extraction -----------------------------------------------------
-
 function extractCliSurface(content) {
   if (!content) return { verbs: new Set(), flags: new Set() };
   const verbs = new Set();
   const flags = new Set();
-  // Only scan the COMMANDS = {...} block and PLAYBOOK_VERBS Set to avoid
-  // picking up arbitrary keys from elsewhere.
+  // Only the COMMANDS block and PLAYBOOK_VERBS Set, not arbitrary keys elsewhere.
   const cmdBlock = content.match(/const COMMANDS = \{([\s\S]*?)\n\};/);
   if (cmdBlock) {
     const re = /^\s*"?([a-zA-Z][\w-]+)"?\s*:/gm;
@@ -272,18 +227,22 @@ function extractCliSurface(content) {
     let m;
     while ((m = re.exec(playbookBlock[1])) !== null) verbs.add(m[1]);
   }
-  // REMOVED_VERBS keys are still part of the CLI surface: invoking one returns
-  // a structured refusal envelope (a real, test-covered contract). Counting
-  // them keeps a verb in the surface set when its vestigial COMMANDS entry is
-  // dropped — otherwise removing dead COMMANDS table rows for already-retired
-  // verbs reads as a fresh "removed-but-test-remains" against the refusal test.
+  // REMOVED_VERBS keys are still CLI surface: invoking one returns a structured
+  // refusal that tests cover. Counting them stops a dropped COMMANDS row reading
+  // as a fresh "removed-but-test-remains" against the refusal test.
   const removedBlock = content.match(/const REMOVED_VERBS = \{([\s\S]*?)\n\};/);
   if (removedBlock) {
     for (const m of removedBlock[1].matchAll(/^\s*"?([a-zA-Z][\w-]+)"?\s*:/gm)) verbs.add(m[1]);
   }
+  // Scans the whole file, prose included, so a flag named in a comment counts as
+  // surface. A trailing hyphen means the match stopped at a line break mid-name
+  // (`--attest-` wrapping to `ownership`), which is never a flag — admitting one
+  // makes deleting that comment read as a removed flag.
   const flagRe = /(--[a-zA-Z][\w-]+)/g;
   let m;
-  while ((m = flagRe.exec(content)) !== null) flags.add(m[1]);
+  while ((m = flagRe.exec(content)) !== null) {
+    if (!m[1].endsWith("-")) flags.add(m[1]);
+  }
   for (const f of ["--help", "--version"]) flags.delete(f);
   return { verbs, flags };
 }
@@ -299,27 +258,18 @@ function diffSets(before, after) {
 function extractLibExports(content) {
   if (!content) return new Set();
   const out = new Set();
-  // v0.12.9: strip block + line comments before matching `module.exports`
-  // so a doc-comment example like `module.exports = {...}` inside a /** */
-  // block does not shadow the real exports lower in the file. Pre-fix, the
-  // analyzer's own file matched a 3-char doc-comment fragment first and
-  // returned an empty export set — any source that mentions `module.exports`
-  // in a JSDoc/banner block hit the same bug. After stripping comments,
-  // the `module.exports = {...}` match runs against real code only.
+  // Strip comments first: a `module.exports = {...}` inside a doc comment
+  // otherwise shadows the real exports and the export set comes back empty.
   const stripped = content
     .replace(/\/\*[\s\S]*?\*\//g, "")
     .replace(/^\s*\/\/.*$/gm, "");
-  // Capture the `module.exports = { ... }` body with brace-balancing so a
-  // nested object/array member (e.g. `{ CONFIG: { a: 1 }, x, y }`) does not
-  // truncate the export list at the first inner `}` and hide later exports —
-  // which would let an uncovered new export ship green (the gate's blind spot).
+  // Brace-balanced so a nested member (`{ CONFIG: { a: 1 }, x, y }`) does not
+  // truncate the list at the first inner `}` and hide later exports.
   const objStart = stripped.search(/module\.exports\s*=\s*\{/);
   if (objStart !== -1) {
     const openIdx = stripped.indexOf("{", objStart);
-    // String-aware brace balance: a `}` inside a string/template value (e.g.
-    // `{ PATTERN: "a}b", realExport }`) must NOT close the object early and
-    // hide the exports that follow — that blind spot let an uncovered export
-    // ship green.
+    // String-aware: a `}` inside a value (`{ PATTERN: "a}b", realExport }`)
+    // must not close the object early and hide the exports that follow.
     let depth = 0, end = -1, inStr = null;
     for (let i = openIdx; i < stripped.length; i++) {
       const ch = stripped[i];
@@ -334,8 +284,7 @@ function extractLibExports(content) {
     }
     if (end !== -1) {
       const body = stripped.slice(openIdx + 1, end);
-      // String-aware member split: a `,` or bracket inside a string value must
-      // not split a member or skew the bracket depth.
+      // String-aware split: a `,` or bracket inside a string must not split a member.
       let d = 0, cur = "", sInStr = null;
       const members = [];
       for (let i = 0; i < body.length; i++) {
@@ -356,12 +305,9 @@ function extractLibExports(content) {
       for (const tok of members) {
         const id = tok.split(":")[0].trim();
         if (/^[a-zA-Z_$][\w$]*$/.test(id)) { out.add(id); continue; }
-        // Method-shorthand member (`fn(a){...}`, `async load(){}`, `get x(){}`,
-        // `*gen(){}`): the colon-split above fails the id test because the token
-        // is `name(...)...`, so the export name would be silently dropped and a
-        // new exported method would ship with no diff-coverage requirement.
-        // Recover the name as the identifier immediately before the first `(`,
-        // after any leading modifier keyword (async/get/set) or generator `*`.
+        // Method-shorthand member (`fn(a){}`, `async load(){}`, `*gen(){}`): the
+        // colon split leaves `name(...)`, so recover the name before the first
+        // `(`, past any modifier keyword or generator `*`.
         const beforeParen = tok.split("(")[0].trim();
         const parts = beforeParen.split(/\s+/);
         const cand = parts[parts.length - 1].replace(/^\*/, "").trim();
@@ -369,12 +315,8 @@ function extractLibExports(content) {
       }
     }
   }
-  // Single-identifier whole-module export (`module.exports = mainFn;`): the
-  // entire public surface of a lib file is one assigned function. The object
-  // extractor above matches nothing, so without this the file's only export is
-  // invisible to the gate and a change to it requires no test. Capture the bare
-  // identifier on the RHS of `module.exports =` when it is not an object/array/
-  // function-expression/arrow (those are handled elsewhere or have no name).
+  // Whole-module export (`module.exports = mainFn;`): the object extractor above
+  // matches nothing, so without this the file's only export is invisible.
   const singleIdent = stripped.match(/module\.exports\s*=\s*([a-zA-Z_$][\w$]*)\s*;/);
   if (singleIdent && !/^(function|async|class)$/.test(singleIdent[1])) {
     out.add(singleIdent[1]);
@@ -401,13 +343,8 @@ function extractPlaybookIds(content) {
   return { indicators: ind, artifacts: arts };
 }
 
-// Canonical-form recursive equality replaces JSON.stringify comparison.
-// Pre-v0.13.20 the comparator was JSON.stringify(before.iocs) !==
-// JSON.stringify(after.iocs) — non-canonical: key order, trailing
-// whitespace, and numeric format differences all flagged as "changed"
-// when the operator made no semantic change. Symptoms were patched
-// twice with skip rules (_auto_imported, _iocs_stub) instead of fixing
-// the comparator. v0.13.20 fixes the root cause.
+// Canonical equality, not JSON.stringify: key order, whitespace and numeric
+// formatting are not semantic changes to an iocs block.
 const { canonicalEqual } = require("../lib/canonical-eq");
 
 function extractCveIocChanges(beforeStr, afterStr) {
@@ -417,10 +354,8 @@ function extractCveIocChanges(beforeStr, afterStr) {
   const ids = new Set([...Object.keys(before), ...Object.keys(after)]);
   for (const id of ids) {
     if (!/^CVE-\d{4}-\d+/.test(id)) continue;
-    // v0.13.18 retained skip rule: bulk-imported rows whose IoCs are
-    // stub-by-design on both sides — pure intake-class events, not
-    // operator curation. Removing this would surface every fresh KEV
-    // bulk-import as a per-CVE iocs-modified finding.
+    // Rows auto-imported on BOTH sides hold stub IoCs by design; without the
+    // skip, every fresh KEV bulk-import surfaces as a per-CVE finding.
     const beforeAuto = !!(before[id] && before[id]._auto_imported);
     const afterAuto  = !!(after[id]  && after[id]._auto_imported);
     if (beforeAuto && afterAuto) continue;
@@ -433,8 +368,6 @@ function extractCveIocChanges(beforeStr, afterStr) {
 
 function safeParse(s) { try { return s ? JSON.parse(s) : null; } catch { return null; } }
 
-// --- Test corpus + coverage probes ------------------------------------------
-
 function loadTestCorpus(cwd) {
   const root = path.join(cwd, "tests");
   if (!fs.existsSync(root)) return { joined: "", files: [] };
@@ -473,32 +406,21 @@ function coversCliFlag(corpus, flag) {
   return corpus.includes(flag);
 }
 
-// F10 — same-file context check. A test corpus is no longer treated as
-// one giant string for lib-export coverage: the identifier must appear
-// inside a real test block (`test(`, `it(`, `describe(`, or an `assert(`
-// argument) within the SAME file that issues the matching require().
-// Pre-fix: an `assert.equal(...)` mention in one test file plus a stray
-// `require('../lib/x')` in a completely different test file counted as
-// coverage. That's not coverage — it's textual coincidence.
-//
-// `corpus` may be either a string (legacy joined corpus, used by
-// CLI/playbook/CVE coverage probes) or the structured shape
-// `{ joined, files }` produced by loadTestCorpus().
+// Coverage needs same-file context: the identifier must appear inside a real
+// test block in the SAME file that requires the module, or a stray require() in
+// one file plus a mention in another reads as coverage. `corpus` is either the
+// structured `{ joined, files }` from loadTestCorpus or a legacy joined string.
 function coversLibExport(corpus, libRel, ident) {
   const baseName = path.basename(libRel).replace(/\.js$/, "");
-  const baseFile = path.basename(libRel); // e.g. "check-sbom-currency.js"
+  const baseFile = path.basename(libRel);
   const identRe = new RegExp("\\b" + escapeRe(ident) + "\\b");
   const requireRe = new RegExp("require\\([^)]*" + escapeRe(baseName) + "[^)]*\\)");
-  // Accept the structured shape (preferred). Walk files individually.
   if (corpus && Array.isArray(corpus.files)) {
     for (const f of corpus.files) {
       const hasRequire = requireRe.test(f.content);
       const mentionsSpawnPath = f.content.includes(baseFile);
       if (!hasRequire && !mentionsSpawnPath) continue;
       if (!identRe.test(f.content)) continue;
-      // F10 — require the identifier appears inside a test block in this
-      // file. Recognise `test(`, `it(`, `describe(`, or `assert(` (or any
-      // `assert.<member>(`) bracketed argument that mentions the ident.
       if (mentionsIdentInTestContext(f.content, ident)) return true;
     }
     return false;
@@ -510,16 +432,11 @@ function coversLibExport(corpus, libRel, ident) {
   return false;
 }
 
-// Returns true when `ident` appears as a token inside the body of any
-// `test( ... )`, `it( ... )`, `describe( ... )`, `assert( ... )` or
-// `assert.<member>( ... )` call in the file. We approximate "the body of
-// the call" by finding the opening paren after the keyword, then walking
-// matched parens until the call closes. This is a syntactic-enough check
-// for vanilla JavaScript tests; the goal is to refuse "ident only appears
-// in a top-level comment" while still accepting `assert.deepEqual(foo, ...)`.
+// True when `ident` appears as a token inside the parenthesised body of a
+// `test(`, `it(`, `describe(`, `assert(` or `assert.<member>(` call. The paren
+// walk is approximate by design.
 function mentionsIdentInTestContext(content, ident) {
   const tokenRe = new RegExp("\\b" + escapeRe(ident) + "\\b");
-  // Quick reject: file does not mention the identifier at all.
   if (!tokenRe.test(content)) return false;
   const callRe = /\b(test|it|describe|assert(?:\.[A-Za-z_$][\w$]*)?)\s*\(/g;
   let m;
@@ -556,33 +473,15 @@ function coversCveIoc(corpus, cveId) {
   return /\biocs\b/i.test(corpus);
 }
 
-// --- Main analyzer ----------------------------------------------------------
-
-// --- Class-level lint: ban coincidence-passing notEqual(r.status, 0) --------
-//
-// Anti-coincidence rule: every exit-code assertion must pin the
-// EXACT code. `assert.notEqual(r.status, 0)` silently passes when an
-// unrelated failure produces ANY non-zero exit, hiding the regression the
-// test was meant to catch. This lint walks tests/*.test.js and rejects the
-// pattern outright. The `// allow-notEqual: <reason>` opt-out on the same
-// line is the escape hatch for genuine refusal-pins (asserting NOT a
-// specific code) — those must justify themselves inline.
-//
-// Pattern hits any of:
-//   assert.notEqual(r.status, 0)
-//   assert.notEqual(result.status, 0, '...')
-//   assert.notEqual(foo.status, 2, 'must not be unknown-cmd')   ← also refused
-// unless the same line ends with `// allow-notEqual: <reason>`.
-//
-// Structural lint replaces a per-instance hunt across 25+ test sites — keeps
-// new tests / new ports from regressing into coincidence-passing assertions.
-// Fix the class, not the instance.
+// Every exit-code assertion must pin the EXACT code: `assert.notEqual(r.status,
+// 0)` passes on any non-zero exit, hiding the regression the test was written
+// for. The only opt-out is `// allow-notEqual: <reason>` on the same line, for a
+// genuine refusal-pin that asserts NOT a specific code.
 function scanForCoincidenceAsserts(cwd) {
   const out = [];
   const testsDir = path.join(cwd, "tests");
   if (!fs.existsSync(testsDir)) return out;
-  // Match `assert.notEqual( <ident>.status` — the receiver name varies
-  // (r, r1, result, child, etc.) but the .status access is the signal.
+  // The receiver name varies (r, r1, result, child); the `.status` access is the signal.
   const banRe = /assert\.notEqual\s*\(\s*[A-Za-z_$][\w$]*\.status\b/;
   const allowRe = /\/\/\s*allow-notEqual\s*:/;
   const skipPrefix = "_helpers"; // helpers may legitimately reference the pattern
@@ -611,10 +510,6 @@ function scanForCoincidenceAsserts(cwd) {
 
 function analyze(opts) {
   const cwd = opts.repo || ROOT;
-  // v0.12.8: resolve the diff anchor ONCE and thread it through every
-  // per-file call so listChangedFiles + fileDiff + fileBefore all agree on
-  // the same SHA. Otherwise origin/main advancing past the merge-base
-  // between calls produces false add/remove findings.
   const resolvedBase = resolveBaseRef(opts, cwd);
   const changed = listChangedFiles(opts, cwd, resolvedBase);
   const corpusObj = loadTestCorpus(cwd);
@@ -632,10 +527,7 @@ function analyze(opts) {
     }
     if (cat === "skill") { allowlisted.push({ file: ch.file, reason: "skill-signed" }); continue; }
     if (cat === "workflow") { manualReview.push({ file: ch.file, reason: "workflow" }); continue; }
-    // F11 — data catalogs, schemas, manifests, SBOM go to manual review
-    // instead of being silently allowlisted. They show up in CI output.
     if (cat === "manual-review") { manualReview.push({ file: ch.file, reason: "manual-review" }); continue; }
-    // v0.12.14: derived index files allowlist (auto-regenerated artifacts).
     if (cat === "allowlist-derived") { allowlisted.push({ file: ch.file, reason: "derived-artifact" }); continue; }
     if (cat === "other") { manualReview.push({ file: ch.file, reason: "unclassified" }); continue; }
     if (ch.status !== "D" && isWhitespaceOnly(opts, ch.file, cwd, resolvedBase)) {
@@ -663,8 +555,6 @@ function analyze(opts) {
       const b = extractLibExports(before);
       const a = extractLibExports(after);
       const d = diffSets(b, a);
-      // F10 — pass the structured corpus so coversLibExport can enforce
-      // same-file require()+identifier-in-test-context coverage.
       for (const id of d.added) if (!coversLibExport(corpusObj, ch.file, id))
         findings.push({ file: ch.file, kind: "lib-export", surface: id, change: "added" });
       for (const id of d.removed) if (coversLibExport(corpusObj, ch.file, id))
@@ -687,11 +577,8 @@ function analyze(opts) {
     }
   }
 
-  // Class-level lint: ban `notEqual(<ident>.status, N)` outside of
-  // refusal-pin allowlist comments. Runs irrespective of the diff —
-  // a coincidence-passing assert that lands via a non-test-coverage
-  // path (someone hand-edits a tests/ file in a docs-only commit) is
-  // still a regression vector the gate must catch.
+  // Runs irrespective of the diff: a coincidence-passing assert can land by a
+  // path this analyzer never inspects.
   const coincidenceFindings = scanForCoincidenceAsserts(cwd);
   for (const f of coincidenceFindings) {
     findings.push({
@@ -705,8 +592,6 @@ function analyze(opts) {
   return { findings, allowlisted, manualReview, totalChanged: changed.length };
 }
 
-// --- Output -----------------------------------------------------------------
-
 function emitHuman(report) {
   const out = [];
   out.push("Diff coverage analyzer — " + report.totalChanged + " changed file(s)");