@blamejs/exceptd-skills 0.18.9 → 0.18.12

package/scripts/check-test-subjects.js

@@ -0,0 +1,148 @@
+#!/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);
+      // Capture the FULL module.exports object via a brace-balanced scan. A
+      // non-greedy /\{([\s\S]*?)\}/ stops at the first nested `}` and drops
+      // every export name after it (the brace-truncation class), under-deriving
+      // subjects so a real export silently has no required test.
+      const expAt = txt.search(/module\.exports\s*=\s*\{/);
+      if (expAt >= 0) {
+        const open = txt.indexOf("{", expAt);
+        let depth = 0, end = -1;
+        for (let k = open; k < txt.length; k++) { const ch = txt[k]; if (ch === "{") depth++; else if (ch === "}" && --depth === 0) { end = k; break; } }
+        if (end > open) for (const m of txt.slice(open + 1, end).matchAll(/([A-Za-z_$][\w$]*)\s*[,:}\n]/g)) add(camelKebab(m[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
+  // CVE-primitive subjects. An unreadable / malformed / empty catalog must NOT
+  // silently derive zero CVE subjects — that would let the reverse-coverage gate
+  // PASS with no CVE coverage at all (the absent-input false-pass class). Fail
+  // loud instead.
+  let cveDerived = 0;
+  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"); cveDerived++; } }
+  catch (e) { throw new Error("check-test-subjects: cannot read/parse data/cve-catalog.json — refusing to derive subjects (reverse coverage would falsely pass with no CVE coverage): " + e.message); }
+  if (cveDerived === 0) throw new Error("check-test-subjects: data/cve-catalog.json yielded zero CVE entries — refusing to let reverse coverage pass with no CVE coverage.");
+  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 });
+  // Reverse-REQUIRED subset: only module / cve / playbook subjects must have a
+  // test (aliases, data files, cli verbs, repo artifacts are valid targets but
+  // not reverse-required). The exit-code logic gates on THIS, consistently
+  // across --worklist and the human/predeploy paths.
+  const reverseRequired = reverse.filter((x) => x.kind.startsWith("module:") || x.kind.startsWith("cve-primitive") || x.kind.startsWith("playbook-primitive"));
+  return { subjects: subjects.size, forward, reverse, reverseRequired };
+}
+
+if (require.main === module) {
+  const r = run();
+  const revMods = r.reverseRequired;
+  if (process.argv.includes("--worklist")) { process.stdout.write(JSON.stringify(r) + "\n"); process.exitCode = (r.forward.length || revMods.length) ? 1 : 0; }
+  else {
+    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
@@ -322,16 +335,27 @@ function runGate(gate) {
     const ceil = typeof gate.informationalMaxExitCode === "number"
       ? gate.informationalMaxExitCode
       : Infinity;
-    // A signal kill (spawnSync returns status:null with r.signal set — e.g. a
-    // 137 OOM kill) is a crash, not an informational soft-signal. Without this,
-    // an OOM-killed informational gate fell through to "informational" and the
-    // release proceeded as if the gate had merely produced advisory output.
-    if (r.signal || (r.status !== null && r.status > ceil)) {
+    // A spawn failure (spawnSync returns r.error set, status:null, signal:null —
+    // e.g. the gate command is missing / ENOENT / EACCES) is a crash, not an
+    // informational soft-signal. So is a signal kill (status:null with r.signal
+    // set — e.g. a 137 OOM kill) and a status that exceeds the soft-signal
+    // ceiling. Without surfacing the spawn-error case, an informational gate
+    // that never even ran fell through to "informational" and the release
+    // proceeded as if the gate had merely produced advisory output. The
+    // status===null && !signal case (no error object, but the process never
+    // produced an exit code) is treated the same way — a gate that did not
+    // exit cleanly cannot be classified as a soft signal.
+    const spawnFailed = !!r.error || (r.status === null && !r.signal);
+    if (r.error || r.signal || spawnFailed || (r.status !== null && r.status > ceil)) {
       return {
         status: "failed",
-        exitCode: r.status,
-        message: r.signal
+        exitCode: r.status ?? null,
+        message: r.error
+          ? `informational gate failed to spawn (treated as a crash): ${r.error.message}`
+          : r.signal
           ? `informational gate killed by signal ${r.signal} (treated as a crash)`
+          : r.status === null
+          ? `informational gate did not exit cleanly (no exit code, no signal) — treated as a crash`
           : `informational gate crashed (exit ${r.status} > informationalMaxExitCode=${ceil})`,
         durationMs,
         warnCount,
@@ -425,7 +449,7 @@ function main() {
   process.exit(failures.length > 0 ? 1 : 0); // allow:process-exit-after-stdout-write — local-only gate runner; output is the human/CI summary written synchronously above, never a piped --json result channel
 }
 
-module.exports = { GATES };
+module.exports = { GATES, runGate };
 
 if (require.main === module) {
   try {

package/scripts/refresh-upstream-catalogs.js

@@ -55,10 +55,39 @@ function specRequiredFields(catalogKey) {
   return spec.required_context.map((r) => r.field);
 }
 
-function fetchUrl(url) {
+const MAX_REDIRECTS = 5;
+
+// Hardened fetch helper. Three properties the hand-rolled follower lacked:
+//   1. Redirect-depth cap + base-URL resolution + response drain, so a
+//      redirect loop rejects within the cap (rather than recursing/hanging
+//      unbounded) and a relative Location resolves against the current URL.
+//   2. 4xx/5xx (and a missing statusCode edge) reject instead of resolving an
+//      error body as a "successful" empty result — every consumer fails
+//      closed on an HTTP error rather than stamping _meta on a non-fetch.
+//   3. A 3xx with no Location header rejects with a clear message rather than
+//      throwing an opaque ERR_INVALID_URL on `new URL(undefined, url)`.
+function fetchUrl(url, depth = 0) {
   return new Promise((resolve, reject) => {
     https.get(url, { headers: { "User-Agent": "exceptd-refresh-upstream-catalogs" } }, (r) => {
-      if (r.statusCode >= 300 && r.statusCode < 400) return fetchUrl(r.headers.location).then(resolve, reject);
+      const code = r.statusCode;
+      if (code == null) {
+        r.resume();
+        return reject(new Error(`no HTTP status code for ${url}`));
+      }
+      if (code >= 300 && code < 400) {
+        r.resume(); // drain the redirect response so the socket is freed/reused
+        const loc = r.headers.location;
+        if (!loc) return reject(new Error(`redirect ${code} from ${url} with no Location header`));
+        if (depth >= MAX_REDIRECTS) return reject(new Error(`too many redirects (>${MAX_REDIRECTS}) fetching ${url}`));
+        let next;
+        try { next = new URL(loc, url).toString(); } // resolves relative AND absolute Location
+        catch (e) { return reject(new Error(`invalid redirect target "${loc}" from ${url}: ${e.message}`)); }
+        return fetchUrl(next, depth + 1).then(resolve, reject);
+      }
+      if (code >= 400) {
+        r.resume(); // drain so the socket is freed
+        return reject(new Error("HTTP " + code + " for " + url));
+      }
       let b = "";
       r.on("data", (c) => (b += c));
       r.on("end", () => resolve(b));
@@ -70,8 +99,16 @@ function loadCatalog(rel) {
   return JSON.parse(fs.readFileSync(path.join(ROOT, "data", rel), "utf8"));
 }
 
+// Atomic write: a crash / disk-full / SIGKILL mid-write would otherwise leave a
+// truncated JSON catalog on disk. Write to a temp sibling and rename — rename is
+// atomic on POSIX and on same-volume Windows renames (the .tmp sibling is
+// adjacent to the target, same volume), so a reader / the next run only ever
+// sees the complete old or complete new file. Mirrors build-indexes#writeJson.
 function writeCatalog(rel, obj) {
-  fs.writeFileSync(path.join(ROOT, "data", rel), JSON.stringify(obj, null, 2) + "\n");
+  const abs = path.join(ROOT, "data", rel);
+  const tmp = `${abs}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, JSON.stringify(obj, null, 2) + "\n");
+  fs.renameSync(tmp, abs);
 }
 
 function getTag(blk, tag) {
@@ -198,9 +235,12 @@ function parseRfcEntry(blk) {
   };
 }
 
-async function refreshRfc({ dry = false } = {}) {
+async function refreshRfc({ dry = false, _deps = {} } = {}) {
+  const _fetchUrl = _deps.fetchUrl || fetchUrl;
+  const _loadCatalog = _deps.loadCatalog || loadCatalog;
+  const _writeCatalog = _deps.writeCatalog || writeCatalog;
   console.log("[refresh-upstream:rfc] fetching IETF RFC index...");
-  const body = await fetchUrl(RFC_SRC);
+  const body = await _fetchUrl(RFC_SRC);
   console.log(`[refresh-upstream:rfc] index size: ${(body.length / 1e6).toFixed(2)} MB`);
   const re = /<rfc-entry>([\s\S]*?)<\/rfc-entry>/g;
   const entries = [];           // current — eligible for new-add
@@ -213,8 +253,17 @@ async function refreshRfc({ dry = false } = {}) {
     if (e.obsoleted || e.status === "HISTORIC" || e.status === "UNKNOWN") continue;
     entries.push(e);
   }
+  // Sanity floor: the IETF index has ~9000+ RFCs, so a successful fetch can
+  // never parse to zero entries. A zero count means the fetch returned an
+  // error/empty/soft-error body (a 200 with a CDN error page, a captive portal,
+  // or a truncated body the HTTP-status guard can't see) — refuse to stamp
+  // _meta or write rfc-references.json, matching the JSON-parse failures the
+  // STIX sources surface for free (an empty index is never a legitimate result).
+  if (backfillable.length === 0) {
+    throw new Error("RFC index parsed 0 entries (fetch likely returned an error/empty body) — refusing to stamp _meta or write rfc-references.json");
+  }
   console.log(`[refresh-upstream:rfc] current entries: ${entries.length} (+ ${backfillable.length - entries.length} obsoleted/historic available for backfill on existing rows)`);
-  const cat = loadCatalog("rfc-references.json");
+  const cat = _loadCatalog("rfc-references.json");
   const existing = new Set(Object.keys(cat).filter((k) => k !== "_meta"));
   let added = 0, statusBumped = 0, backfilledCount = 0;
   // First pass: backfill ALL existing rows from the broader entry set
@@ -226,8 +275,13 @@ async function refreshRfc({ dry = false } = {}) {
     const cur = cat[id];
     if (!cur) continue;
     let touched = false;
-    if (cur._auto_imported && cur.status !== RFC_STATUS_MAP[e.status]) {
-      cur.status = RFC_STATUS_MAP[e.status];
+    // Mirror the new-add path's `|| e.status` fallback: an upstream status
+    // outside RFC_STATUS_MAP must NOT write `undefined` (which would drop the
+    // status field on an existing curated row). Fall back to the raw upstream
+    // status, and only bump when the mapped value actually differs.
+    const mapped = RFC_STATUS_MAP[e.status] || e.status;
+    if (cur._auto_imported && mapped && cur.status !== mapped) {
+      cur.status = mapped;
       touched = true;
       statusBumped++;
     }
@@ -293,16 +347,25 @@ async function refreshRfc({ dry = false } = {}) {
     existing.add(id);
     added++;
   }
-  if (cat._meta) {
-    cat._meta.last_updated = TODAY;
-    cat._meta.last_threat_review = TODAY;
-  }
+  // Only restamp _meta + write when something actually changed. A genuine
+  // no-op leaves the file byte-identical so the daily refresh doesn't emit a
+  // spurious _meta-only diff (and so the freshness gates stay honest — a
+  // wall-clock restamp on an unchanged catalog masks real staleness).
+  const changed = added > 0 || backfilledCount > 0 || statusBumped > 0;
   if (dry) {
     console.log(`[refresh-upstream:rfc] DRY-RUN: +${added} new, ${backfilledCount} backfilled, ${statusBumped} status bumps.`);
     return { added, statusBumped, backfilled: backfilledCount };
   }
-  writeCatalog("rfc-references.json", cat);
-  console.log(`[ok] rfc-references.json: +${added} entries, ${backfilledCount} backfilled, ${statusBumped} status bumps (now ${existing.size} total)`);
+  if (changed) {
+    if (cat._meta) {
+      cat._meta.last_updated = TODAY;
+      cat._meta.last_threat_review = TODAY;
+    }
+    _writeCatalog("rfc-references.json", cat);
+    console.log(`[ok] rfc-references.json: +${added} entries, ${backfilledCount} backfilled, ${statusBumped} status bumps (now ${existing.size} total)`);
+  } else {
+    console.log("[ok] rfc-references.json: no upstream changes — file unchanged");
+  }
   return { added, statusBumped, backfilled: backfilledCount };
 }
 
@@ -392,9 +455,12 @@ function backfillAttack(cur, fresh) {
   return touched;
 }
 
-async function refreshAttack({ dry = false, cap = Infinity } = {}) {
+async function refreshAttack({ dry = false, cap = Infinity, _deps = {} } = {}) {
+  const _fetchUrl = _deps.fetchUrl || fetchUrl;
+  const _loadCatalog = _deps.loadCatalog || loadCatalog;
+  const _writeCatalog = _deps.writeCatalog || writeCatalog;
   console.log("[refresh-upstream:attack] fetching MITRE ATT&CK STIX...");
-  const body = await fetchUrl(ATTACK_SRC);
+  const body = await _fetchUrl(ATTACK_SRC);
   const stix = JSON.parse(body);
   // For NEW adds: live techniques only (skip revoked / deprecated).
   // For BACKFILL on existing rows: include revoked too — an operator-
@@ -410,7 +476,7 @@ async function refreshAttack({ dry = false, cap = Infinity } = {}) {
   );
   console.log(`[refresh-upstream:attack] STIX live techniques: ${liveTechs.length} (+ ${backfillTechs.length - liveTechs.length} revoked/deprecated available for backfill on existing rows)`);
   const techs = liveTechs;
-  const local = loadCatalog("attack-techniques.json");
+  const local = _loadCatalog("attack-techniques.json");
   const existing = new Set(Object.keys(local).filter((k) => k !== "_meta"));
   techs.sort((a, b) => {
     const aSub = a.x_mitre_is_subtechnique ? 1 : 0;
@@ -448,9 +514,14 @@ async function refreshAttack({ dry = false, cap = Infinity } = {}) {
     added++;
   }
   if (dry) { console.log(`[refresh-upstream:attack] DRY-RUN: +${added} new, ${backfilled} context backfills`); return { added, backfilled }; }
-  if (local._meta) { local._meta.last_updated = TODAY; local._meta.last_threat_review = TODAY; }
-  writeCatalog("attack-techniques.json", local);
-  console.log(`[ok] attack-techniques.json: +${added} entries, ${backfilled} context backfills (now ${existing.size} total)`);
+  const changed = added > 0 || backfilled > 0;
+  if (changed) {
+    if (local._meta) { local._meta.last_updated = TODAY; local._meta.last_threat_review = TODAY; }
+    _writeCatalog("attack-techniques.json", local);
+    console.log(`[ok] attack-techniques.json: +${added} entries, ${backfilled} context backfills (now ${existing.size} total)`);
+  } else {
+    console.log("[ok] attack-techniques.json: no upstream changes — file unchanged");
+  }
   return { added, backfilled };
 }
 
@@ -472,15 +543,18 @@ const ICS_TACTIC_NAME = {
   "impact": "Impact (ICS)"
 };
 
-async function refreshIcsAttack({ dry = false, cap = Infinity } = {}) {
+async function refreshIcsAttack({ dry = false, cap = Infinity, _deps = {} } = {}) {
+  const _fetchUrl = _deps.fetchUrl || fetchUrl;
+  const _loadCatalog = _deps.loadCatalog || loadCatalog;
+  const _writeCatalog = _deps.writeCatalog || writeCatalog;
   console.log("[refresh-upstream:ics-attack] fetching MITRE ICS-attack STIX...");
-  const body = await fetchUrl(ICS_ATTACK_SRC);
+  const body = await _fetchUrl(ICS_ATTACK_SRC);
   const stix = JSON.parse(body);
   const techs = (stix.objects || []).filter(
     (o) => o.type === "attack-pattern" && !o.revoked && !o.x_mitre_deprecated
   );
   console.log(`[refresh-upstream:ics-attack] STIX live ICS techniques: ${techs.length}`);
-  const local = loadCatalog("attack-techniques.json");
+  const local = _loadCatalog("attack-techniques.json");
   const existing = new Set(Object.keys(local).filter((k) => k !== "_meta"));
   let added = 0, backfilled = 0;
   for (const t of techs) {
@@ -519,9 +593,14 @@ async function refreshIcsAttack({ dry = false, cap = Infinity } = {}) {
     added++;
   }
   if (dry) { console.log(`[refresh-upstream:ics-attack] DRY-RUN: +${added} new, ${backfilled} backfills`); return { added, backfilled }; }
-  if (local._meta) { local._meta.last_updated = TODAY; local._meta.last_threat_review = TODAY; }
-  writeCatalog("attack-techniques.json", local);
-  console.log(`[ok] attack-techniques.json: +${added} ICS entries, ${backfilled} backfills (now ${existing.size} total)`);
+  const changed = added > 0 || backfilled > 0;
+  if (changed) {
+    if (local._meta) { local._meta.last_updated = TODAY; local._meta.last_threat_review = TODAY; }
+    _writeCatalog("attack-techniques.json", local);
+    console.log(`[ok] attack-techniques.json: +${added} ICS entries, ${backfilled} backfills (now ${existing.size} total)`);
+  } else {
+    console.log("[ok] attack-techniques.json: no upstream ICS changes — file unchanged");
+  }
   return { added, backfilled };
 }
 
@@ -580,6 +659,15 @@ function backfillAtlas(cur, fresh) {
       if (!cur[key] && val) { cur[key] = val; touched = true; }
     }
   };
+  // Parity with backfillAttack: include the short description + tactic in the
+  // backfill set. Existing curated ATLAS rows often carry only {name} and need
+  // the short description + tactic too, not just description_full/platforms/etc.
+  fillIfEmpty("description", fresh.description);
+  // tactic: atlasEntryFromStix() emits a STRING for a single-tactic technique
+  // and an array for multi-tactic, so backfill both forms. fillIfEmpty only
+  // writes when cur is empty, so an existing (string OR array) tactic is never
+  // overwritten — the common single-tactic case is no longer left unhydrated.
+  fillIfEmpty("tactic", fresh.tactic);
   fillIfEmpty("description_full", fresh.description_full);
   fillIfEmpty("platforms", fresh.platforms);
   fillIfEmpty("detection", fresh.detection);
@@ -591,9 +679,12 @@ function backfillAtlas(cur, fresh) {
   return touched;
 }
 
-async function refreshAtlas({ dry = false } = {}) {
+async function refreshAtlas({ dry = false, _deps = {} } = {}) {
+  const _fetchUrl = _deps.fetchUrl || fetchUrl;
+  const _loadCatalog = _deps.loadCatalog || loadCatalog;
+  const _writeCatalog = _deps.writeCatalog || writeCatalog;
   console.log("[refresh-upstream:atlas] fetching MITRE ATLAS STIX...");
-  const body = await fetchUrl(ATLAS_SRC);
+  const body = await _fetchUrl(ATLAS_SRC);
   const stix = JSON.parse(body);
   const techs = (stix.objects || []).filter(
     (o) => o.type === "attack-pattern" && !o.revoked && !o.x_mitre_deprecated
@@ -609,7 +700,7 @@ async function refreshAtlas({ dry = false } = {}) {
       atlasVersion = o.x_mitre_version; break;
     }
   }
-  const local = loadCatalog("atlas-ttps.json");
+  const local = _loadCatalog("atlas-ttps.json");
   const existing = new Set(Object.keys(local).filter((k) => k !== "_meta"));
   aml.sort((a, b) => {
     const aSub = a.x_mitre_is_subtechnique ? 1 : 0;
@@ -635,13 +726,22 @@ async function refreshAtlas({ dry = false } = {}) {
     added++;
   }
   if (dry) { console.log(`[refresh-upstream:atlas] DRY-RUN: +${added} new, ${backfilled} backfills${atlasVersion ? `, v${atlasVersion}` : ""}`); return { added, backfilled, atlasVersion }; }
-  if (local._meta) {
-    if (atlasVersion) local._meta.atlas_version = atlasVersion;
-    local._meta.last_updated = TODAY;
-    local._meta.last_threat_review = TODAY;
+  // A newly-detected ATLAS matrix version that differs from the recorded one
+  // is itself a change (the catalog should bump atlas_version + last_updated
+  // together), independent of any added/backfilled rows.
+  const versionChanged = !!(atlasVersion && local._meta && local._meta.atlas_version !== atlasVersion);
+  const changed = added > 0 || backfilled > 0 || versionChanged;
+  if (changed) {
+    if (local._meta) {
+      if (atlasVersion) local._meta.atlas_version = atlasVersion;
+      local._meta.last_updated = TODAY;
+      local._meta.last_threat_review = TODAY;
+    }
+    _writeCatalog("atlas-ttps.json", local);
+    console.log(`[ok] atlas-ttps.json: +${added} entries, ${backfilled} backfills (now ${existing.size} total${atlasVersion ? `, ATLAS v${atlasVersion}` : ""})`);
+  } else {
+    console.log("[ok] atlas-ttps.json: no upstream changes — file unchanged");
   }
-  writeCatalog("atlas-ttps.json", local);
-  console.log(`[ok] atlas-ttps.json: +${added} entries, ${backfilled} backfills (now ${existing.size} total${atlasVersion ? `, ATLAS v${atlasVersion}` : ""})`);
   return { added, backfilled, atlasVersion };
 }
 
@@ -672,8 +772,18 @@ function d3fendIdList(t, field) {
   return arr.map((x) => (x && x["@id"]) ? String(x["@id"]).replace(/^d3f:/, "") : null).filter(Boolean);
 }
 
+// Strip a trailing period from an OWL d3fend-id: a few upstream artifact ids
+// (e.g. "D3A-C4.") carry a spurious terminal dot that no id token regex can
+// round-trip, leaving the entry unmatchable by the orphan/cross-ref scanners.
+// No legitimate d3fend technique id ends in a period. The SAME normalization
+// must key the catalog (existing.has / local[id]) as well as the entry payload,
+// or a refresh re-adds the period-keyed row every run (duplicate / churn).
+function normD3fendId(rawId) {
+  return typeof rawId === "string" ? rawId.replace(/\.$/, "") : rawId;
+}
+
 function d3fendEntryFromOwl(t) {
-  const id = t["d3f:d3fend-id"];
+  const id = normD3fendId(t["d3f:d3fend-id"]);
   const labelRaw = t["rdfs:label"];
   const name = Array.isArray(labelRaw)
     ? (typeof labelRaw[0] === "object" ? labelRaw[0]["@value"] : labelRaw[0])
@@ -736,19 +846,22 @@ function backfillD3fend(cur, fresh) {
   return touched;
 }
 
-async function refreshD3fend({ dry = false, cap = Infinity } = {}) {
+async function refreshD3fend({ dry = false, cap = Infinity, _deps = {} } = {}) {
+  const _fetchUrl = _deps.fetchUrl || fetchUrl;
+  const _loadCatalog = _deps.loadCatalog || loadCatalog;
+  const _writeCatalog = _deps.writeCatalog || writeCatalog;
   console.log("[refresh-upstream:d3fend] fetching MITRE D3FEND ontology...");
-  const body = await fetchUrl(D3FEND_SRC);
+  const body = await _fetchUrl(D3FEND_SRC);
   const j = JSON.parse(body);
   const graph = j["@graph"] || [];
   const techs = graph.filter((o) => o["@id"] && o["d3f:d3fend-id"] && o["rdfs:label"]);
   console.log(`[refresh-upstream:d3fend] ontology techniques: ${techs.length}`);
-  const local = loadCatalog("d3fend-catalog.json");
+  const local = _loadCatalog("d3fend-catalog.json");
   const existing = new Set(Object.keys(local).filter((k) => k !== "_meta"));
   techs.sort((a, b) => String(a["d3f:d3fend-id"]).localeCompare(String(b["d3f:d3fend-id"])));
   let added = 0, backfilled = 0;
   for (const t of techs) {
-    const id = t["d3f:d3fend-id"];
+    const id = normD3fendId(t["d3f:d3fend-id"]);
     if (existing.has(id)) {
       const fresh = d3fendEntryFromOwl(t);
       const cur = local[id];
@@ -761,9 +874,14 @@ async function refreshD3fend({ dry = false, cap = Infinity } = {}) {
     added++;
   }
   if (dry) { console.log(`[refresh-upstream:d3fend] DRY-RUN: +${added} new, ${backfilled} backfills`); return { added, backfilled }; }
-  if (local._meta) { local._meta.last_updated = TODAY; local._meta.last_threat_review = TODAY; }
-  writeCatalog("d3fend-catalog.json", local);
-  console.log(`[ok] d3fend-catalog.json: +${added} entries, ${backfilled} backfills (now ${existing.size} total)`);
+  const changed = added > 0 || backfilled > 0;
+  if (changed) {
+    if (local._meta) { local._meta.last_updated = TODAY; local._meta.last_threat_review = TODAY; }
+    _writeCatalog("d3fend-catalog.json", local);
+    console.log(`[ok] d3fend-catalog.json: +${added} entries, ${backfilled} backfills (now ${existing.size} total)`);
+  } else {
+    console.log("[ok] d3fend-catalog.json: no upstream changes — file unchanged");
+  }
   return { added, backfilled };
 }
 
@@ -820,5 +938,12 @@ module.exports = {
   refreshAtlas,
   refreshD3fend,
   SOURCES,
-  runCli
+  runCli,
+  // Exported for regression tests: fetchUrl's status/redirect handling and
+  // writeCatalog's atomicity are load-bearing fail-closed properties.
+  fetchUrl,
+  writeCatalog,
+  // Exported for regression tests: backfillAtlas must mirror backfillAttack's
+  // description + array-tactic backfill on curated rows.
+  backfillAtlas
 };