@blamejs/exceptd-skills 0.18.8 → 0.18.11

package/scripts/build-indexes.js

@@ -74,9 +74,27 @@ function writeJson(name, obj) {
   // is atomic on POSIX and Windows, so a reader (or the next build's
   // parse-check) only ever sees the complete old or complete new file.
   const abs = path.join(IDX, name);
-  const tmp = `${abs}.tmp-${process.pid}`;
+  // Random suffix (not just pid) so a Promise.all fan-out (--parallel) sharing
+  // a pid can't race the same tmp path, and the in-repo temp name isn't
+  // predictable. Mirrors lib/citation-resolve.js cachePut.
+  const tmp = `${abs}.tmp-${process.pid}.${crypto.randomBytes(4).toString("hex")}`;
   fs.writeFileSync(tmp, JSON.stringify(obj, null, 2) + "\n", "utf8");
-  fs.renameSync(tmp, abs);
+  // rename-over-existing is atomic, but on Windows a sync client / AV / indexer
+  // (e.g. Dropbox holding the target open for a few ms) can make it transiently
+  // EPERM/EACCES/EBUSY. Retry with short backoff so a build doesn't fail on a
+  // lock that clears in milliseconds; on POSIX the first attempt always wins.
+  let lastErr;
+  for (let attempt = 0; attempt < 10; attempt++) {
+    try { fs.renameSync(tmp, abs); return; }
+    catch (e) {
+      lastErr = e;
+      if (e.code !== "EPERM" && e.code !== "EACCES" && e.code !== "EBUSY") break;
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20 * (attempt + 1));
+    }
+  }
+  // Persistent failure: drop the temp sibling so it doesn't orphan, then surface.
+  try { fs.unlinkSync(tmp); } catch { /* best effort */ }
+  throw lastErr;
 }
 
 function readJson(p) {
@@ -795,7 +813,7 @@ async function main() {
     for (const n of wanted) {
       if (!OUTPUTS.find((o) => o.name === n)) {
         console.error(`build-indexes: unknown output "${n}". Valid: ${OUTPUTS.map((o) => o.name).join(", ")}`);
-        process.exit(2);
+        process.exitCode = 2; return;
       }
     }
     chosen = withDependencyClosure(wanted);

package/scripts/builders/section-offsets.js

@@ -68,13 +68,19 @@ function buildOne(absPath, relPath) {
   const totalBytes = buf.length;
   const text = buf.toString("utf8");
   const lines = text.split(/\r?\n/);
-  const lineByteOffsets = [];
-  let cursor = 0;
-  for (const line of lines) {
-    lineByteOffsets.push(cursor);
-    // +1 for the newline. Counts as one byte for LF; CRLF would skew slightly
-    // but the file is written via the project's tooling which is LF-uniform.
-    cursor += Buffer.byteLength(line, "utf8") + 1;
+  // EOL-aware line-start byte offsets: walk the actual terminator bytes off the
+  // decoded text rather than assuming a fixed 1-byte newline. On a pure-LF body
+  // every terminator is 1 byte so the offsets are identical to the old `+ 1`
+  // accumulator; on a stray CRLF body the \r\n terminator is 2 bytes and the
+  // offsets stay correct (the old fixed-constant approach undercounted by 1
+  // byte per line and silently misaligned every token-budget slice). The split
+  // above discards terminator bytes, so the width can only be recovered by
+  // reading the terminators off the raw text — done here.
+  const lineByteOffsets = [0];
+  const eolRe = /\r?\n/g;
+  let m;
+  while ((m = eolRe.exec(text)) !== null) {
+    lineByteOffsets.push(Buffer.byteLength(text.slice(0, m.index + m[0].length), "utf8"));
   }
 
   // Frontmatter: lines between the first "---" and the second "---".
@@ -167,4 +173,7 @@ function buildSectionOffsets({ root, skills }) {
   };
 }
 
-module.exports = { buildSectionOffsets };
+// buildOne is exported for regression testing of the EOL-aware byte offsets
+// (a CRLF body must still produce byte_start values that point at the real
+// "## " byte in the raw file).
+module.exports = { buildSectionOffsets, buildOne };

package/scripts/check-catalog-gap-budget.js

@@ -116,12 +116,12 @@ function main() {
     console.error("Add an explicit budget entry in both:");
     console.error("  scripts/check-catalog-gap-budget.js");
     console.error("  tests/shipped-catalog-integrity.test.js");
-    process.exit(1);
+    process.exitCode = 1; return;
   }
   if (missingBudget.length > 0) {
     console.error("\n[check-catalog-gap-budget] BUDGET missing entries for declared classes:");
     for (const c of missingBudget) console.error(`  ${c}: declared by lib/gap-detectors.js DETECTOR_CLASSES, no BUDGET entry`);
-    process.exit(1);
+    process.exitCode = 1; return;
   }
   if (regressions.length > 0) {
     console.error("\n[check-catalog-gap-budget] REGRESSION beyond budget:");
@@ -131,7 +131,7 @@ function main() {
     console.error("\nClose the gap in this PR (preferred) or update BUDGET in both:");
     console.error("  scripts/check-catalog-gap-budget.js");
     console.error("  tests/shipped-catalog-integrity.test.js");
-    process.exit(1);
+    process.exitCode = 1; return;
   }
   console.log("[check-catalog-gap-budget] all classes within budget; every class is budgeted.");
 }

package/scripts/check-codebase-patterns.js

@@ -148,6 +148,79 @@ function filterMarkers(hits, cls) {
 
 // ---- require.main block ranges -------------------------------------------
 
+// Count `{` / `}` in `line` that are in REAL CODE context, advancing a
+// stateful tokenizer that tracks string / template / comment regions across
+// lines. Braces inside a single/double/template string, a `//` line comment,
+// or a `/* */` block comment do NOT affect depth — otherwise a `{` or `}`
+// typed inside a string literal in the require.main block miscounts the brace
+// balance and the computed block range slides onto an unrelated later function
+// (whose process.exit() is then wrongly treated as a CLI-entry exit and not
+// flagged). `inTemplate` and `inBlockComment` are the cross-line states a
+// per-line stripper cannot model, so the tokenizer state object is threaded
+// line-to-line by the caller.
+//
+// `state` is mutated in place: { inSingle, inDouble, inTemplate, inBlock,
+// templateDepth } — `templateDepth` tracks `${ … }` interpolation nesting so
+// the closing `}` of an interpolation is treated as template punctuation, not
+// a code brace, while braces INSIDE the interpolation expression still count.
+function countCodeBraces(line, state) {
+  let delta = 0;
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    const next = line[i + 1];
+    if (state.inBlock) {
+      if (ch === "*" && next === "/") { state.inBlock = false; i++; }
+      continue;
+    }
+    if (state.inSingle) {
+      if (ch === "\\") { i++; continue; }
+      if (ch === "'") state.inSingle = false;
+      continue;
+    }
+    if (state.inDouble) {
+      if (ch === "\\") { i++; continue; }
+      if (ch === '"') state.inDouble = false;
+      continue;
+    }
+    if (state.inTemplate) {
+      if (ch === "\\") { i++; continue; }
+      if (ch === "`") { state.inTemplate = false; continue; }
+      if (ch === "$" && next === "{") {
+        // Enter an interpolation expression: braces inside ARE code.
+        state.templateExpr.push(0);
+        state.inTemplate = false;
+        i++; // skip the `{`; the `${` opener is template punctuation
+        continue;
+      }
+      continue;
+    }
+    // Code context (possibly inside a template interpolation expression).
+    if (ch === "/" && next === "/") break; // `//` — rest of the line is a comment
+    if (ch === "/" && next === "*") { state.inBlock = true; i++; continue; }
+    if (ch === "'") { state.inSingle = true; continue; }
+    if (ch === '"') { state.inDouble = true; continue; }
+    if (ch === "`") { state.inTemplate = true; continue; }
+    if (ch === "{") {
+      if (state.templateExpr.length) state.templateExpr[state.templateExpr.length - 1]++;
+      delta++;
+    } else if (ch === "}") {
+      if (state.templateExpr.length && state.templateExpr[state.templateExpr.length - 1] === 0) {
+        // Closes the `${ … }` interpolation — back to template body.
+        state.templateExpr.pop();
+        state.inTemplate = true;
+      } else {
+        if (state.templateExpr.length) state.templateExpr[state.templateExpr.length - 1]--;
+        delta--;
+      }
+    }
+  }
+  return delta;
+}
+
+function newBraceState() {
+  return { inSingle: false, inDouble: false, inTemplate: false, inBlock: false, templateExpr: [] };
+}
+
 // Line ranges (1-based, inclusive) of `if (require.main === module) { ... }`
 // blocks — the dual-mode CLI-entry section where synchronous-print-then-exit
 // is correct. process.exit there is owned by tests/safe-exit-grep.test.js and
@@ -156,15 +229,16 @@ function requireMainRanges(lines) {
   const ranges = [];
   for (let i = 0; i < lines.length; i++) {
     if (/\brequire\.main\s*===\s*module\b/.test(lines[i])) {
-      // Find the opening brace (same line or next few), then balance.
+      // Find the opening brace (same line or next few), then balance —
+      // string/comment/template-aware so braces inside literals don't skew the
+      // depth (see countCodeBraces).
       let depth = 0;
       let started = false;
       let j = i;
+      const state = newBraceState();
       for (; j < lines.length; j++) {
-        for (const ch of lines[j]) {
-          if (ch === "{") { depth++; started = true; }
-          else if (ch === "}") { depth--; }
-        }
+        depth += countCodeBraces(lines[j], state);
+        if (depth > 0) started = true;
         if (started && depth <= 0) break;
       }
       if (started) ranges.push([i + 1, j + 1]);
@@ -181,8 +255,14 @@ function inRanges(ranges, lineNo) {
 
 // A line that opens a new function body (so a backward stdout-write scan stops
 // at the enclosing function and doesn't arm an exit from an unrelated earlier
-// function).
-const FUNCTION_START = /(^|[^.\w])function\b|=>\s*\{?\s*$|^\s*(async\s+)?[A-Za-z_$][\w$]*\s*\([^)]*\)\s*\{/;
+// function). The bare-identifier (third) alternative matches a declaration /
+// method-shorthand opener (`foo() {`, `async bar() {`), but it must REFUSE
+// control-flow openers (`for (…) {`, `if (…) {`, `while/switch/catch (…) {`):
+// a control-flow block sitting between a stdout write and a process.exit() is
+// inside the SAME function, so stopping the backward scan there would wrongly
+// leave the exit unflagged. The negative lookahead excludes the control-flow
+// keywords; `function` and arrow alternatives are unchanged.
+const FUNCTION_START = /(^|[^.\w])function\b|=>\s*\{?\s*$|^\s*(async\s+)?(?!(?:if|for|while|switch|catch|do|else|with|finally|return)\b)[A-Za-z_$][\w$]*\s*\([^)]*\)\s*\{/;
 
 function detectProcessExitAfterStdout(files) {
   const hits = [];
@@ -210,6 +290,15 @@ function detectProcessExitAfterStdout(files) {
   return filterMarkers(hits, "process-exit-after-stdout-write");
 }
 
+// The first non-whitespace char of the first arg is `"`, `'`, or `/` => a
+// string/regex literal => static, safe. Anything else (an identifier, a `(`,
+// a backtick template) is operator-derivable and flagged. Backtick is NOT
+// exempt — a template literal can interpolate operator input, so it must be
+// flagged the same as a bare identifier.
+function isStaticRegexFirstChar(ch) {
+  return ch === '"' || ch === "'" || ch === "/";
+}
+
 function detectDynamicRegex(files) {
   const hits = [];
   for (const rel of (files || filesUnder(["lib", "orchestrator", "bin/exceptd.js"]))) {
@@ -217,10 +306,29 @@ function detectDynamicRegex(files) {
     for (let i = 0; i < lines.length; i++) {
       const code = stripLineComment(lines[i]);
       const m = code.match(/\bnew RegExp\s*\(\s*(.)/);
-      if (!m) continue;
-      // Literal first arg => a quote or a `/` regex literal => static, safe.
-      const firstChar = m[1];
-      if (firstChar === '"' || firstChar === "'" || firstChar === "/") continue;
+      if (m) {
+        if (isStaticRegexFirstChar(m[1])) continue;
+        hits.push({ file: rel, line: i + 1, content: lines[i].trim() });
+        continue;
+      }
+      // Multi-line form: `new RegExp(` ends the (comment-stripped) line with the
+      // open paren as the last token, and the pattern arg is on a following
+      // line. The single-line match above can't see the first-arg char, so it
+      // would silently pass a dynamic RegExp whose argument starts next line.
+      // Look ahead, skipping blank and comment-only lines (capped at 5), and
+      // inspect the first code line's first non-whitespace char.
+      if (!/\bnew RegExp\s*\(\s*$/.test(code)) continue;
+      let firstChar = null;
+      for (let k = i + 1; k <= i + 5 && k < lines.length; k++) {
+        const ahead = stripLineComment(lines[k]).replace(/^\s+/, "");
+        if (ahead === "") continue; // blank or comment-only — skip
+        firstChar = ahead[0];
+        break;
+      }
+      // A `new RegExp(` with nothing parseable after it within the cap is
+      // suspicious — flag conservatively. Otherwise apply the SAME literal
+      // exemption as the single-line path.
+      if (firstChar !== null && isStaticRegexFirstChar(firstChar)) continue;
       hits.push({ file: rel, line: i + 1, content: lines[i].trim() });
     }
   }
@@ -453,6 +561,11 @@ module.exports = {
   detectMisalignedMarkedRun,
   scanUnsortedMarkedArray,
   scanMisalignedMarkedRun,
+  requireMainRanges,
+  countCodeBraces,
+  newBraceState,
+  isStaticRegexFirstChar,
+  FUNCTION_START,
   filesUnder,
 };
 

package/scripts/check-sbom-currency.js

@@ -50,6 +50,66 @@ function catalogEntryCount(dataDir, file) {
   return 0;
 }
 
+// Files/prefixes that refresh-sbom's expandAllowlist excludes from the shipped
+// file: component inventory. Kept in sync with scripts/refresh-sbom.js
+// (SELF_EXCLUDED + DERIVABLE_PREFIXES): the SBOM never hashes itself, and the
+// pre-computed index cache under data/_indexes/ is regenerated/test-mutated, so
+// it carries no per-file component. The completeness check below must apply the
+// SAME exclusions or it would demand a component for a file the generator never
+// emits one for.
+const SBOM_SELF_EXCLUDED = new Set(["sbom.cdx.json"]);
+const SBOM_DERIVABLE_PREFIXES = ["data/_indexes/"];
+
+function sbomIsDerivable(rel) {
+  return SBOM_DERIVABLE_PREFIXES.some(
+    (p) => rel === p.replace(/\/$/, "") || rel.startsWith(p)
+  );
+}
+
+// Recursively list every regular file under absDir, returned as absolute paths.
+// Mirrors refresh-sbom's walkFiles (which is root-agnostic — it walks whatever
+// absolute dir it is given).
+function walkFilesAbs(absDir) {
+  const out = [];
+  let entries;
+  try { entries = fs.readdirSync(absDir, { withFileTypes: true }); }
+  catch { return out; }
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    const abs = path.join(absDir, entry.name);
+    if (entry.isDirectory()) out.push(...walkFilesAbs(abs));
+    else if (entry.isFile()) out.push(abs);
+  }
+  return out;
+}
+
+// Root-aware allowlist expansion: the shipped-file set that must each have a
+// file: component, computed against the TARGET tree (`root`), not the running
+// script's source repo. refresh-sbom's exported expandAllowlist is bound to its
+// own REPO_ROOT (it joins/relativizes against __dirname/..), so under a `--root`
+// target the completeness check would otherwise validate the SOURCE repo's file
+// list against the TARGET SBOM — the wrong tree. Replicating the expansion here
+// (same SELF_EXCLUDED + DERIVABLE_PREFIXES exclusions, same dedupe+sort) keeps
+// the gate honest under `--root` without reaching across into the generator's
+// module-level root.
+function expandAllowlistAt(allowlist, root) {
+  const abs = [];
+  for (const entry of allowlist) {
+    const full = path.join(root, entry);
+    let stat;
+    try { stat = fs.statSync(full); }
+    catch { continue; } // tolerate a stale entry; presence checks elsewhere flag
+    if (stat.isDirectory()) abs.push(...walkFilesAbs(full));
+    else if (stat.isFile()) abs.push(full);
+  }
+  const rel = Array.from(
+    new Set(abs.map((a) => path.relative(root, a).split(path.sep).join("/")))
+  )
+    .filter((r) => !SBOM_SELF_EXCLUDED.has(r))
+    .filter((r) => !sbomIsDerivable(r))
+    .sort();
+  return rel;
+}
+
 // The description string embeds per-catalog ENTRY counts as free text, e.g.
 // "11 catalogs (439 CVEs / 177 CWEs / 805 ATT&CK + ICS / 170 ATLAS /
 // 468 D3FEND / 8888 RFCs)". Each token maps to one data/*.json catalog whose
@@ -332,9 +392,15 @@ function checkSbomCurrency(root) {
   // refresh-sbom's exact allowlist expansion + digest so the gate can't drift
   // from the generator.
   try {
-    const { expandAllowlist, bundleDigest } = require("./refresh-sbom");
+    // bundleDigest operates purely on the file: component objects (no tree
+    // walk), so it is root-agnostic and safe to reuse from the generator. The
+    // allowlist expansion, by contrast, MUST run against the target `root`
+    // (expandAllowlistAt below) — refresh-sbom's exported expandAllowlist is
+    // pinned to its own source-repo REPO_ROOT and would validate the wrong tree
+    // under `--root`.
+    const { bundleDigest } = require("./refresh-sbom");
     const pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
-    const expected = expandAllowlist(pkg.files || []);
+    const expected = expandAllowlistAt(pkg.files || [], root);
     const fileComps = components.filter(
       (c) => typeof c["bom-ref"] === "string" && c["bom-ref"].startsWith("file:")
     );
@@ -402,6 +468,6 @@ function main() {
   );
 }
 
-module.exports = { checkSbomCurrency, resolveRoot, DESCRIPTION_ENTRY_TOKENS, catalogEntryCount };
+module.exports = { checkSbomCurrency, resolveRoot, DESCRIPTION_ENTRY_TOKENS, catalogEntryCount, expandAllowlistAt };
 
 if (require.main === module) main();

package/scripts/check-test-count.js

@@ -11,18 +11,24 @@
  * catches test-set shrinkage.
  *
  * Scope + blind spot. This counts test DECLARATIONS, so it detects deleted
- * files / removed `test(` calls / glob-exclusions. It does NOT detect a test
- * neutered in place: `test('name', { skip: true }, fn)` and `test.skip(` both
- * 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.
+ * 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(`, `test.only(`, and `test.skip(` declarations
- * across `tests/*.test.js` via static analysis (faster than running). 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
+ * 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).
  *
@@ -71,7 +77,7 @@ function countTests(filePath) {
     // Drop a trailing line comment too (`test('x'); // disabled`).
     const stripped = noStrings.replace(/\/\/.*$/, '').trim();
     if (!stripped) continue;
-    if (/(?<![A-Za-z0-9_$.])test(?:\.only|\.skip)?\s*\(/.test(stripped)) count++;
+    if (/(?<![A-Za-z0-9_$.])(?:test|it)(?:\.only|\.skip)?\s*\(/.test(stripped)) count++;
   }
   return count;
 }
@@ -165,14 +171,20 @@ function main() {
 
   if (status === 'shrunk_beyond_tolerance') {
     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() invocation was deleted, OR the baseline is stale.');
+    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');
-    process.exit(1);
+    // 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 = 1;
+    return;
   }
   if (status === 'grew_beyond_threshold_consider_bump') {
     console.error(`[check-test-count] NOTICE - test count grew by ${delta} (above the ${updateThreshold} notice threshold). Consider refreshing the baseline: node scripts/check-test-count.js --update-baseline`);
   }
-  process.exit(0);
+  process.exitCode = 0;
 }
 
-main();
+module.exports = { countTests, listTestFiles };
+
+if (require.main === module) main();

package/scripts/check-test-subjects.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * check-test-subjects.js — bidirectional test↔subject gate (and reorg driver).
+ *
+ * Every test file must be named after a real SUBJECT the codebase actually has,
+ * and every subject must have a test. A "subject" is derived dynamically from
+ * the codebase so this list is never hand-maintained:
+ *   - a source MODULE basename (lib/x.js -> x; lib/collectors/x.js -> x and
+ *     collectors-x; orchestrator/index.js -> orchestrator; bin/exceptd.js -> cli)
+ *   - an exported FUNCTION / CLASS name (kebab-cased) — per-function granularity
+ *   - a data PRIMITIVE: a data/*.json catalog FILE, plus each catalog ENTRY that
+ *     is itself a primitive — every CVE/MAL/GHSA id in data/cve-catalog.json and
+ *     every playbook in data/playbooks/ — so one CVE == one test file
+ *   - a .github/workflows/*.yml WORKFLOW (release -> release-workflow, etc.)
+ *   - a CLI verb dispatched by bin/exceptd.js
+ *
+ * FORWARD violation : a tests/<x>.test.js where <x> is not a valid subject.
+ * REVERSE violation : a subject (module / CVE / playbook / workflow) with no
+ *                     tests/<subject>.test.js.
+ *
+ * Run with --worklist for the machine-readable reorg work list (JSON on stdout).
+ * Run with no flag for a human summary; exits non-zero while any violation
+ * remains (so once the suite conforms this becomes a standing predeploy gate).
+ */
+const fs = require("node:fs");
+const path = require("node:path");
+const ROOT = path.resolve(__dirname, "..");
+
+function camelKebab(s) { return s.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/_/g, "-").toLowerCase(); }
+function read(p) { try { return fs.readFileSync(path.join(ROOT, p), "utf8"); } catch { return ""; } }
+function ls(d) { try { return fs.readdirSync(path.join(ROOT, d), { withFileTypes: true }); } catch { return []; } }
+
+function deriveSubjects() {
+  const subjects = new Map(); // name -> kind
+  const add = (s, kind) => { if (s && !subjects.has(s.toLowerCase())) subjects.set(s.toLowerCase(), kind); };
+
+  function walkSrc(d) {
+    for (const e of ls(d)) {
+      if (e.name === "node_modules") continue;
+      const rel = d + "/" + e.name;
+      if (e.isDirectory()) { walkSrc(rel); continue; }
+      if (!e.name.endsWith(".js")) continue;
+      const base = e.name.replace(/\.js$/, "");
+      // index.js is a directory entry point; the directory/canonical subject
+      // covers it, so treat the bare "index" basename as an alias, not a
+      // separately reverse-required module.
+      add(base, (base === "index" ? "alias:" : "module:") + rel);
+      const parent = path.basename(path.dirname(rel));
+      // parent-prefixed name (collectors-x, builders-x, validators-x) is an
+      // ALIAS of the canonical basename subject — a valid test target, but the
+      // canonical <base>.test.js already satisfies coverage, so don't double-
+      // count the alias as its own reverse gap.
+      if (!["lib", "scripts", "orchestrator", "bin"].includes(parent)) add(parent + "-" + base, "alias:" + rel);
+      const txt = read(rel);
+      for (const m of txt.matchAll(/(?:^|\n)\s*(?:async\s+)?(?:function|class)\s+([A-Za-z_$][\w$]*)/g)) add(camelKebab(m[1]), "fn:" + rel);
+      const exp = txt.match(/module\.exports\s*=\s*\{([\s\S]*?)\}/);
+      if (exp) for (const k of exp[1].matchAll(/([A-Za-z_$][\w$]*)\s*[,:}\n]/g)) add(camelKebab(k[1]), "fn:" + rel);
+    }
+  }
+  ["lib", "orchestrator", "scripts", "bin", "sources/validators"].forEach(walkSrc);
+  add("orchestrator", "module:orchestrator/index.js");
+  add("cli", "module:bin/exceptd.js");
+  // Vendored (pinned third-party) modules are valid test SUBJECTS but are not
+  // reverse-required — we don't force a dedicated test per vendored file.
+  (function walkVendor(d) { for (const e of ls(d)) { const rel = d + "/" + e.name; if (e.isDirectory()) walkVendor(rel); else if (e.name.endsWith(".js")) add(e.name.replace(/\.js$/, ""), "vendor:" + rel); } })("vendor");
+
+  // CLI verbs — both the switch-case form and the dispatch-table form
+  //   (verb: () => path.join(...)) that bin/exceptd.js uses for most subcommands.
+  const cliSrc = read("bin/exceptd.js");
+  for (const m of cliSrc.matchAll(/case\s+['"]([a-z][a-z0-9-]+)['"]/g)) { add("cli-" + m[1], "cli-verb"); add(m[1], "cli-verb"); }
+  for (const m of cliSrc.matchAll(/^\s*["']?([a-z][a-z0-9-]+)["']?:\s*\(\)\s*=>/gm)) { add("cli-" + m[1], "cli-verb"); add(m[1], "cli-verb"); }
+
+  // data catalog files
+  for (const e of ls("data")) if (e.isFile() && e.name.endsWith(".json")) add(e.name.replace(/\.json$/, ""), "data");
+  // data ENTRY primitives: every CVE id + every playbook
+  try { const cat = JSON.parse(read("data/cve-catalog.json")); for (const k of Object.keys(cat)) if (k !== "_meta") add(k.toLowerCase(), "cve-primitive"); } catch {}
+  for (const e of ls("data/playbooks")) if (e.isFile() && e.name.endsWith(".json")) { const b = e.name.replace(/\.json$/, ""); add(b, "playbook-primitive"); add("playbook-" + b, "alias:playbook"); }
+  // workflows
+  for (const e of ls(".github/workflows")) if (/\.ya?ml$/.test(e.name)) { const b = e.name.replace(/\.ya?ml$/, ""); add(b, "workflow"); add(b + "-workflow", "workflow"); }
+
+  // Repo-artifact subjects: shipped root config/doc files, the docker build
+  // context, the agents/ directory, and aggregate catalog directories. A test
+  // that pins one of these artifacts (its content, counts, or cross-references)
+  // is named after a durable subject, not a release — so these are valid test
+  // targets. Kind is not module/cve/playbook, so they are NOT reverse-required
+  // (we don't force a dedicated test per doc file).
+  for (const f of ["package.json", "manifest.json", "manifest-snapshot.json", "README.md", "AGENTS.md", "SECURITY.md", "ARCHITECTURE.md", "CONTEXT.md", "CHANGELOG.md", "CONTRIBUTING.md", "CODE_OF_CONDUCT.md", "LICENSE", "NOTICE"]) {
+    add(f.replace(/\.[^.]*$/, "").toLowerCase().replace(/_/g, "-"), "repo:" + f);
+  }
+  add("agents-md", "repo:AGENTS.md");
+  add("docker", "repo:docker/test.Dockerfile");
+  add("agents", "repo:agents/");
+  add("playbooks", "aggregate:data/playbooks");
+  add("workflows", "aggregate:.github/workflows");
+  add("governance", "repo:governance-files"); // LICENSE/NOTICE/FUNDING/CoC/gitignore/gitleaks presence + integrity
+  return subjects;
+}
+
+function run() {
+  const subjects = deriveSubjects();
+  const testFiles = ls("tests").filter((e) => e.isFile() && e.name.endsWith(".test.js")).map((e) => e.name.replace(/\.test\.js$/, ""));
+  const testSet = new Set(testFiles.map((t) => t.toLowerCase()));
+
+  const suggest = (name) => {
+    const toks = name.toLowerCase().split("-");
+    for (let n = toks.length; n >= 1; n--) { const c = toks.slice(0, n).join("-"); if (subjects.has(c)) return c; }
+    return null;
+  };
+  const forward = [];
+  for (const t of testFiles) if (!subjects.has(t.toLowerCase())) forward.push({ file: "tests/" + t + ".test.js", suggested: suggest(t) });
+  const reverse = [];
+  for (const [s, kind] of subjects) if (!testSet.has(s)) reverse.push({ subject: s, kind });
+  return { subjects: subjects.size, forward, reverse };
+}
+
+if (require.main === module) {
+  const r = run();
+  if (process.argv.includes("--worklist")) { process.stdout.write(JSON.stringify(r) + "\n"); process.exitCode = (r.forward.length || r.reverse.length) ? 1 : 0; }
+  else {
+    const revMods = r.reverse.filter((x) => x.kind.startsWith("module:") || x.kind.startsWith("cve-primitive") || x.kind.startsWith("playbook-primitive"));
+    console.log(`[check-test-subjects] valid subjects=${r.subjects} | FORWARD violations=${r.forward.length} | REVERSE (module/cve/playbook) gaps=${revMods.length}`);
+    if (r.forward.length || revMods.length) { console.log("[check-test-subjects] FAIL — run with --worklist for the full list."); process.exitCode = 1; }
+    else console.log("[check-test-subjects] ok — every test maps to a subject and every subject has a test.");
+  }
+}
+module.exports = { deriveSubjects, run };

package/scripts/check-version-tags.js

@@ -90,6 +90,13 @@ const COMMENT_EXEMPT = new Set([
   // literals are load-bearing data, not sprinkled release tags.
   "scripts/check-version-bump.js",
   "tests/version-bump-cadence.test.js",
+  // The version-tag gate's own regression test asserts the trailing-period /
+  // IPv4 / longer-run boundaries and the PHASE_RESIDUE_RES / FILENAME_VERSION_RE
+  // / countLineViolations exports, so it MUST embed literal stamps like
+  // `0.18.9.`, `0.18.99`, `Pre-0.13.22`, and `foo-v0_13_2.test.js` as the inputs
+  // under test — load-bearing data for the detector's boundary cases, not
+  // sprinkled release tags.
+  "tests/check-version-tags.test.js",
 ]);
 
 // Git-ignored files (a contributor's local-only working docs, scratch) are
@@ -115,11 +122,15 @@ function gitIgnoredSet(relPaths) {
 // Pattern: project version like `v0.13.22` or bare `0.13.22`. Matches
 // our pre-1.0 release range. External package versions like ATLAS
 // `v5.6.0` or CycloneDX `1.6` don't match because the major is 0.
-// The dot/digit lookarounds keep an IPv4 octet run (e.g. `127.0.0.1`, whose
-// `0.0.1` tail would otherwise count as a version tag) and any longer
-// dotted-numeric sequence from registering — a release version is never
-// embedded inside a larger digit.digit run.
-const VERSION_TAG_RE = /(?<![\d.])v?0\.\d+\.\d+(?![\d.])/;
+// The trailing lookahead rejects a longer minor/patch digit (so `0.18.99`
+// still matches, but the stamp can't be part of a wider number) and a
+// dot-followed-by-digit (an IPv4 next octet / longer dotted-numeric run, e.g.
+// `127.0.0.1`, whose `0.0.1` tail would otherwise register). A sentence-ending
+// period after the patch (dot followed by non-digit / end-of-line, e.g.
+// `// fixed in 0.18.9.`) is NOT excluded — that is exactly the version residue
+// the gate must catch. The leading `(?<![\d.])` lookbehind keeps the IPv4
+// suppression on the other side.
+const VERSION_TAG_RE = /(?<![\d.])v?0\.\d+\.\d+(?!\d)(?!\.\d)/;
 
 // Phase residue patterns — broader than just version tags.
 const PHASE_RESIDUE_RES = [
@@ -314,5 +325,13 @@ function main() {
   process.exitCode = 1;
 }
 
+module.exports = {
+  VERSION_TAG_RE,
+  PHASE_RESIDUE_RES,
+  FILENAME_VERSION_RE,
+  countLineViolations,
+  scanCurrent,
+};
+
 if (require.main === module) main();
 

package/scripts/predeploy.js

@@ -249,6 +249,19 @@ const GATES = [
     args: [path.join(ROOT, "scripts", "check-codebase-patterns.js")],
     ciJobName: "Data integrity (catalog + manifest snapshot)",
   },
+  {
+    // Test-subject coverage gate. Bidirectional: every tests/<x>.test.js must
+    // be named after a real SUBJECT the codebase has (a module / CLI verb /
+    // CVE id / playbook / data primitive / repo artifact), and every such
+    // subject must have a test. Blocks the naming drift that lets a test be
+    // filed under a version/finding label (where downstream readers can't find
+    // it) and surfaces any module/playbook that ships without a test. Derived
+    // dynamically from the source tree, so the list is never hand-maintained.
+    name: "Test-subject coverage (every test maps to a subject; every subject has a test)",
+    command: process.execPath,
+    args: [path.join(ROOT, "scripts", "check-test-subjects.js")],
+    ciJobName: "Data integrity (catalog + manifest snapshot)",
+  },
   {
     // Release-notes extract + quality gate. Runs the same `## <version>`
     // CHANGELOG extraction the release workflow publishes as the GitHub