@blamejs/exceptd-skills 0.13.18 → 0.13.20

package/sbom.cdx.json

@@ -1,23 +1,23 @@
 {
   "bomFormat": "CycloneDX",
   "specVersion": "1.6",
-  "serialNumber": "urn:uuid:070ec015-b805-4047-838a-451a01d98c27",
+  "serialNumber": "urn:uuid:cdadd1f3-ca1b-4a82-8e4c-ed5bfcb8bc0d",
   "version": 1,
   "metadata": {
-    "timestamp": "2029-10-02T10:53:09.000Z",
+    "timestamp": "2135-05-08T21:32:35.000Z",
     "tools": [
       {
         "vendor": "blamejs",
         "name": "scripts/refresh-sbom.js",
-        "version": "0.13.18"
+        "version": "0.13.20"
       }
     ],
     "component": {
-      "bom-ref": "pkg:npm/@blamejs/exceptd-skills@0.13.18",
+      "bom-ref": "pkg:npm/@blamejs/exceptd-skills@0.13.20",
       "type": "application",
       "name": "@blamejs/exceptd-skills",
-      "version": "0.13.18",
-      "description": "AI security skills grounded in mid-2026 threat reality, not stale framework documentation. 42 skills, 10 catalogs (312 CVEs / 170 CWEs / 711 ATT&CK / 170 ATLAS / 468 D3FEND / 7476 RFCs — every catalog carries context-search fields, not just titles), 34 jurisdictions, pre-computed indexes, Ed25519-signed.",
+      "version": "0.13.20",
+      "description": "AI security skills grounded in mid-2026 threat reality, not stale framework documentation. 42 skills, 10 catalogs (312 CVEs / 171 CWEs / 805 ATT&CK + ICS / 170 ATLAS / 468 D3FEND / 7476 RFCs), 34 jurisdictions, real XML parser + canonical-form diff comparison + content-pattern regression detection, Ed25519-signed.",
       "licenses": [
         {
           "license": {
@@ -25,17 +25,17 @@
           }
         }
       ],
-      "purl": "pkg:npm/%40blamejs/exceptd-skills@0.13.18",
+      "purl": "pkg:npm/%40blamejs/exceptd-skills@0.13.20",
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "f89db04967ff17551e9afc27e3fad7da58ec6bdeedcb3adf8a6addcbccdb2b32"
+          "content": "3aca821664c27f90892a0aaa7602e3813f62e71aca39e0c87eca4a4621584d85"
         }
       ],
       "externalReferences": [
         {
           "type": "distribution",
-          "url": "https://www.npmjs.com/package/@blamejs/exceptd-skills/v/0.13.18"
+          "url": "https://www.npmjs.com/package/@blamejs/exceptd-skills/v/0.13.20"
         },
         {
           "type": "vcs",
@@ -116,11 +116,11 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "6976e60c38d604bdf16448cce86f138e328f90799a782c1bbb115d297bd21c81"
+          "content": "004c3a9617a5290ac345779a48588eed519b6e042102b0a1384881d2a28c23f6"
         },
         {
           "alg": "SHA3-512",
-          "content": "7f43998bfe92dd93528ff1351306a4e9e15f0a4fb0294a31cd12ea05c24f9708771fb27171f2f611b7c4ee375ca53ff10b21b2fc4bf9912c8c2c39a98cb0efee"
+          "content": "5631e188a25811b9b009fdef576e6ea9ad3890ba1206d9a3e7d9b8c606e1c401d21b153ad6e4b3f8110385a6389351172b3a8a10fcf75ed9eebdd750c0a974a3"
         }
       ]
     },
@@ -311,11 +311,11 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "7176cd761e983f3dec8970e297e0bc1805389ae0d678b2d333402c95c0d15ece"
+          "content": "09bd917fe13c23d8a33f6a04978f5c89ea56ee53c8002ad357bd89cfb9ba8981"
         },
         {
           "alg": "SHA3-512",
-          "content": "f3de9bfe7a9feae12f9ce261ab030379dc5efaa7023bb044ef8128a6857e3640e79a8607bb2945e272901cb1751fb15e7f1d25e4e689b3d1d76a87f2aeb34fa4"
+          "content": "6d6ac5427d0f38973e4a1ae04a981f64bb253626ec478709568cae712175207c15f97dfc3c0f5767fc36ce43d6c65c60e1962297ee546437a9cba1ea729381b6"
         }
       ]
     },
@@ -326,11 +326,11 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "c55e90435dd335aec43de0df485294bdb50dcffd97e89c27be3006584c569317"
+          "content": "a09c83af3f9679a7ea73935726a1ff9de2cab94b4ab6321fc017fc147747d7c3"
         },
         {
           "alg": "SHA3-512",
-          "content": "8f76058eb21488f7352798fb22f64c7b3a74fae6d5a3f69b5a629c2af238852453f45f411b6f0db7f8ca4db4f47f401b6635af661dfdc29938bf0628b2ee5c9a"
+          "content": "653f3d3cdac2fe56ba01fdf2bb3b3c6edfdc29b667f0ddb99f7755aec1adf577618135e3a68667126be121f8d130d7848a1001bd41878af10446e959b5db2626"
         }
       ]
     },
@@ -341,11 +341,11 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "7fc28f7347747101ffceccbd679c220375cd06ed67ce1855904dd2a82d03508e"
+          "content": "c56e74b8c9290583b1d6fdd21b54bd65a254c58890c5f683379788ca7b080e9d"
         },
         {
           "alg": "SHA3-512",
-          "content": "26a0434a554c87a112151d897358119cd4cadfdf09895fa516d0381f874e673351a2fce09fbcdce57676d6cb45bc002d74c907a5446f0fa59e798028a7102afb"
+          "content": "24a77d58aa84b7c91c5067dbb28c73ddfa42a0229c6f45b9e36aea58d65ab3bc17a0a759323bdfad7d6a7fad8f21eff8a9ea2efc118f069035a6e5c0373380f6"
         }
       ]
     },
@@ -401,11 +401,11 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "56433a2cf40b4298766e7042789714f93bfd3ac2d96600ba33039e04b1c07192"
+          "content": "b63fe398c3de068093871e8bbca11e16b6567fb15482648d0bbce06939c34104"
         },
         {
           "alg": "SHA3-512",
-          "content": "d3127347ed95498fde382ab4ab2e0ae36a757a160107df769ae76fcbef1fb0e2c0b18ade439bfe3fdc1a5dce0b4c397e4daf6ebbe39e56eda6ec6861cb4eb743"
+          "content": "e64c9e219f6e77fbb235ed875b1775ff6150bffc49fae5903600b15d3799f0d8a27dd553869646e3d0311c5b7fbe456686d9f7bf7e10c0c4cbc71079bcd943ff"
         }
       ]
     },
@@ -776,11 +776,11 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "0e578d3c7585125d71d9d55733477f97447be0a9b9e501d5711fdbeb6672d462"
+          "content": "926ea25892e052fc6a8b9952afc1d8e2bd06c4aec223a1a7aa79ef1dfd7b7bb5"
         },
         {
           "alg": "SHA3-512",
-          "content": "ddf68f4496c9eead89acf7fd75d823f60411365cc8aaf4992a03b7cb3f5fd53430bb3c5e42d9b3f8babe355282443308b2713ccf21bcc5221c5a11402015dd3e"
+          "content": "6632e67313409bf5fdbde7e6ba199e4e61c437edfc00d8276a448e33240d78820927be85bccde6877b5f86c8f16abbe5b037147ed41366b9599963537accff0c"
         }
       ]
     },
@@ -791,11 +791,11 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "147494f4def977dee0b2b7ffda6590df3cc335284795f4fc31b12a0267c96176"
+          "content": "7242a7349ac79a74813bf2b7486b6000c0c877e71cec17e2d68df33bc4007b93"
         },
         {
           "alg": "SHA3-512",
-          "content": "b372d7200bf4167970d0931d33a11fe49126bfd8526e645097cf5a20487cc3186d8b6038101d72dbc2734271312052b6c3e2fd580c924e844f1c49ce98a0caf3"
+          "content": "eaa89dcdafec3f8f3b5bb3f7a34ae6709681dca278a0eacf43fe8c5fb9cc1e533ba64f46df15152316a505572cf891bc20b7682e505474209a0e3e7aa97dea82"
         }
       ]
     },
@@ -844,6 +844,21 @@
         }
       ]
     },
+    {
+      "bom-ref": "file:lib/canonical-eq.js",
+      "type": "file",
+      "name": "lib/canonical-eq.js",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "eb962f83a7b82a4f895553d13191cd933c87d29116591d76c8550c7cb00ebebd"
+        },
+        {
+          "alg": "SHA3-512",
+          "content": "f09e77b2f58aeb0d09c4758738de42d657345a9ef09f28529682f2daa7ebcfb84602eb811a76e85640e45e6ce13274918b994e760099ff457869ccccf740a437"
+        }
+      ]
+    },
     {
       "bom-ref": "file:lib/cross-ref-api.js",
       "type": "file",
@@ -881,11 +896,11 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "3f6f7d0a9487b0b7b89af7c848559381fea053594f5a1cb0b85e7e63e81c2168"
+          "content": "b5278eddccec3e9cf2c68f8bdd8a142de8f95c61d61826570fa5d293e81055f2"
         },
         {
           "alg": "SHA3-512",
-          "content": "68c34e8db139b94951e3b68f8e6dc8945599ea84a4bed028e2145f45d9cfc84f5e8f05cbdfd06ad3ba95c6dbf974b4bc4641b1a0169167a347cf92762418cf1f"
+          "content": "ba4f8de9981e8a3066b014e52984e9917c4e003a7feebc6098f5cd32ed22a0dca82b97dbfcabf31809e3f5de7145e2cb9f30432c6a30564642a4e798c4f796cd"
         }
       ]
     },
@@ -1151,11 +1166,11 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "35b6a6f5a2ae2a833bf0c2ccc21dff47f2f72147f0af7fdd2e484cd0b195334f"
+          "content": "d4da578b2f7d45f3d22eac52c1c9196cd3dbaf23414b5932d1f5c52d713236b8"
         },
         {
           "alg": "SHA3-512",
-          "content": "223e0efb65b0cc18b96ff3267f08170aa1c91c722c5220c6cf26a109eab4c9009330c72507273ad777a8f7ab8de090a9d1d6517797c922cb81a659391777af82"
+          "content": "1f5add189b0d6bfd18cd85b28ff7ce64f1b52fec573098ccfbd71fc9245cbcca624a0cda515315e6881779d46eb0ca27fbefb4eda74cc5ff22c2309a1a97d5de"
         }
       ]
     },
@@ -1339,6 +1354,21 @@
         }
       ]
     },
+    {
+      "bom-ref": "file:lib/version-pins.js",
+      "type": "file",
+      "name": "lib/version-pins.js",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "7cbdc502a689614200f009d74e8d82544bf6b442452dfd970437596742a5e885"
+        },
+        {
+          "alg": "SHA3-512",
+          "content": "eeb9b1cd050195693e425a48967a536f775f016ebe6563c6b6da30b3f90ff436e34e41bd2c860d61f2d343156358193c7c1c7454b4651301e777e37d671039b0"
+        }
+      ]
+    },
     {
       "bom-ref": "file:lib/worker-pool.js",
       "type": "file",
@@ -1354,6 +1384,21 @@
         }
       ]
     },
+    {
+      "bom-ref": "file:lib/xml-tokenizer.js",
+      "type": "file",
+      "name": "lib/xml-tokenizer.js",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "1c2e2a92fe90ce90a7dcb7c95979e1b9c6e18f6bce1cfd160de9ce644fddb889"
+        },
+        {
+          "alg": "SHA3-512",
+          "content": "0bd564faff3173e095ceecff3e9bf70fc6c7ed2a8d4bb8b89b066f33b2a95513488408bc3f5bd6d8571eb1dcfb96710b2b45589b2d22238a04a790be246cb00f"
+        }
+      ]
+    },
     {
       "bom-ref": "file:manifest-snapshot.json",
       "type": "file",
@@ -1391,11 +1436,11 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "e133ca64d1cfbe12cdba5a9c6d8af79eba02456c0ae083b998b44f79084fd1dd"
+          "content": "d9f9002ad675655e952674403fb030798e7ad0c98c65e6ad586960d7d7915af9"
         },
         {
           "alg": "SHA3-512",
-          "content": "af61ad1cf93928f125c3ede8f0acebca62c4e36adb1aac9334d4fccc3c6a29e760a44706f8c9e3b11a60b7b0913b4346d49b6777cbff98743ae158d75a3c5569"
+          "content": "41a61a493083024dd45323b21dd5d243eefdcbf212a1a23948ff180318ebb7644f25e4ea7954b9ff1ecb2650b68ce8050fefae545db14e894cb82e7c1166cedc"
         }
       ]
     },
@@ -1504,6 +1549,21 @@
         }
       ]
     },
+    {
+      "bom-ref": "file:scripts/audit-catalog-gaps.js",
+      "type": "file",
+      "name": "scripts/audit-catalog-gaps.js",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "ab99b9dc0a40f6a1914f40678c0b9b15880895515ddbb27526703f4d11400370"
+        },
+        {
+          "alg": "SHA3-512",
+          "content": "d7f2b1d775d45c12e651d4da2cfd1f1e118eeb3bd9bd72f562417b06429f8868ddaa2c34aa66bcbe19214f44a673770d2cfc24fcfaf2be66510d6b42889f56d9"
+        }
+      ]
+    },
     {
       "bom-ref": "file:scripts/audit-cross-skill.js",
       "type": "file",
@@ -1841,11 +1901,11 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "2114e1afc6b0e033c357aaffe3b885b8198820c134583833c665264befd632e7"
+          "content": "d126c48bee7da18f03cefba681dcae5b931a0472658e4d7e0227ce3e29461026"
         },
         {
           "alg": "SHA3-512",
-          "content": "e420ed39530f9285c1524fdd3e8bbe3276e7ec068dc57b059731916f3bd70090c18de14e07d133f3b996867f85798662612fafd2eddafdd22c40b2d64ece3a54"
+          "content": "1ba4ffa94b0bf0bdb7e0bd0b537d016424da070d7c6991b90446dc8991dc005d13d5d306cc69d10ad73f765154eb09716b68cad38ab609069f105974006f4d3e"
         }
       ]
     },
@@ -1939,6 +1999,21 @@
         }
       ]
     },
+    {
+      "bom-ref": "file:scripts/refresh-mitre-ics-attack.js",
+      "type": "file",
+      "name": "scripts/refresh-mitre-ics-attack.js",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "014fd472f805193662698020c53d8ed08532ea2d8cbd2c9d8f33f162728d0ad2"
+        },
+        {
+          "alg": "SHA3-512",
+          "content": "8437f443eff9e5caca4414c2e7e7454c18b7dfcb8acfc690ac9565aef775d6c562c174f4cbe87a577b9616ebea189008bc62d04df5a8bfef791e5b9b81feaa53"
+        }
+      ]
+    },
     {
       "bom-ref": "file:scripts/refresh-reverse-refs.js",
       "type": "file",
@@ -1991,11 +2066,11 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "4eebbff0625bca22f6fbf8f64742756f266c45817ded063f2fff01a7cd3a026d"
+          "content": "4c2d6ba4c75dea4c92409908db8ffcd357b7208f765c532a3ac976a8cf785acf"
         },
         {
           "alg": "SHA3-512",
-          "content": "c8f1d98095840427929fda55313b210cb977d41cbf01121998286b5340f486369a6e83927ce976f3457067799c2d3441c87ade5b420593a8fab7ffeb6185779c"
+          "content": "29d02c2280fde260d95d215ef68ca4f668906c31d240a174195141b7568bd17a203af50c25d8f0a861d76247ee13984d0843ccab5b5e75f52b6ad77e69f06521"
         }
       ]
     },

package/scripts/audit-catalog-gaps.js

@@ -0,0 +1,347 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * scripts/audit-catalog-gaps.js
+ *
+ * Walks every data/*.json catalog and surfaces three classes of gap:
+ *
+ *   1. missing-context     entries that exist but lack one of the
+ *                          documented context-search fields (e.g. RFC
+ *                          without abstract; ATT&CK technique without
+ *                          platforms; CVE without iocs)
+ *
+ *   2. dangling-ref        forward references from one catalog into
+ *                          another that do not resolve (e.g. CVE
+ *                          entry's cwe_refs cites CWE-XXX but the
+ *                          local cwe-catalog does not carry that ID)
+ *
+ *   3. draft-debt          per-catalog count of _auto_imported rows
+ *                          relative to operator-curated rows. High
+ *                          draft-debt = bulk-imported surface that has
+ *                          not been refined yet.
+ *
+ * Output: structured JSON to stdout (default) or human-readable summary
+ * with `--pretty`. Returns exit 0 in --warn-only mode (default); exit
+ * 1 in --strict mode if any class triggers.
+ *
+ * Usage:
+ *   node scripts/audit-catalog-gaps.js                    # JSON
+ *   node scripts/audit-catalog-gaps.js --pretty           # human
+ *   node scripts/audit-catalog-gaps.js --strict           # exit 1 on gap
+ *   node scripts/audit-catalog-gaps.js --catalog cve      # one catalog
+ *   node scripts/audit-catalog-gaps.js --class missing-context
+ *
+ * npm: `npm run audit-catalog-gaps`
+ *
+ * Design note: the gap analyzer is a separate detection plane from
+ * lib/validate-cve-catalog.js (schema validation, predeploy gate) and
+ * scripts/refresh-reverse-refs.js (forward/reverse-ref currency). The
+ * validator polices what's strictly required by the schema; the gap
+ * analyzer polices the recommended-but-not-required context envelope
+ * that lets an AI consumer find an entry by topic instead of by ID.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const ROOT = path.join(__dirname, "..");
+const DATA = path.join(ROOT, "data");
+const TODAY = new Date().toISOString().slice(0, 10);
+
+// Per-catalog required context fields. Each entry in the array is a
+// field path (dot-separated for nested) and a non-emptiness predicate.
+// Pillar / Class / Pillar-abstraction CWEs and similar can opt out via
+// the suppression key on the entry (_gap_skip: { fields: [...] }).
+const SPEC = {
+  "cve-catalog": {
+    file: "cve-catalog.json",
+    idShape: /^(CVE-|MAL-|BUG-|GHSA-|SNYK-)/,
+    required_context: [
+      { field: "iocs", check: (v) => v && (
+        (Array.isArray(v.payload_artifacts) && v.payload_artifacts.length) ||
+        (Array.isArray(v.behavioral) && v.behavioral.length)
+      ), label: "iocs.payload_artifacts or iocs.behavioral" },
+      { field: "framework_control_gaps", check: (v) => v && Object.keys(v).length > 0, label: "framework_control_gaps" },
+      { field: "attack_refs", check: (v) => Array.isArray(v) && v.length > 0, label: "attack_refs" },
+      { field: "cwe_refs", check: (v) => Array.isArray(v) && v.length > 0, label: "cwe_refs" },
+      { field: "verification_sources", check: (v) => Array.isArray(v) && v.length > 0, label: "verification_sources" }
+    ],
+    refs: [
+      { field: "cwe_refs", target: "cwe-catalog.json", item: true },
+      { field: "attack_refs", target: "attack-techniques.json", item: true },
+      { field: "atlas_refs", target: "atlas-ttps.json", item: true },
+      { field: "framework_control_gaps", target: "framework-control-gaps.json", keys: true }
+    ]
+  },
+  "cwe-catalog": {
+    file: "cwe-catalog.json",
+    idShape: /^CWE-\d+$/,
+    required_context: [
+      { field: "name", check: (v) => typeof v === "string" && v.length > 0, label: "name" },
+      { field: "abstraction", check: (v) => typeof v === "string" && v.length > 0, label: "abstraction" },
+      { field: "description", check: (v) => typeof v === "string" && v.length > 20, label: "description (>20 chars)" }
+    ],
+    refs: []
+  },
+  "attack-techniques": {
+    file: "attack-techniques.json",
+    idShape: /^T\d{4}(\.\d{3})?$/,
+    required_context: [
+      { field: "name", check: (v) => typeof v === "string" && v.length > 0, label: "name" },
+      { field: "tactic", check: (v) => (Array.isArray(v) ? v.length > 0 : typeof v === "string" && v.length > 0), label: "tactic" },
+      { field: "description", check: (v) => typeof v === "string" && v.length > 0, label: "description (short)" },
+      { field: "platforms", check: (v) => Array.isArray(v) && v.length > 0, label: "platforms" }
+    ],
+    refs: []
+  },
+  "atlas-ttps": {
+    file: "atlas-ttps.json",
+    idShape: /^AML\.T\d{4}(\.\d{3})?$/,
+    required_context: [
+      { field: "name", check: (v) => typeof v === "string" && v.length > 0, label: "name" },
+      { field: "tactic", check: (v) => (Array.isArray(v) ? v.length > 0 : typeof v === "string" && v.length > 0), label: "tactic" },
+      { field: "description", check: (v) => typeof v === "string" && v.length > 0, label: "description" }
+    ],
+    refs: []
+  },
+  "d3fend-catalog": {
+    file: "d3fend-catalog.json",
+    idShape: /^D3-/,
+    required_context: [
+      { field: "name", check: (v) => typeof v === "string" && v.length > 0, label: "name" },
+      { field: "tactic", check: (v) => typeof v === "string" && v.length > 0, label: "tactic" },
+      { field: "description", check: (v) => typeof v === "string" && v.length > 0, label: "description" }
+    ],
+    refs: []
+  },
+  "rfc-references": {
+    file: "rfc-references.json",
+    idShape: /^(RFC-\d+|DRAFT-|ISO-|CSAF-)/,
+    required_context: [
+      { field: "title", check: (v) => typeof v === "string" && v.length > 0, label: "title" },
+      { field: "status", check: (v) => typeof v === "string" && v.length > 0, label: "status" },
+      { field: "abstract", check: (v) => typeof v === "string" && v.length > 20, label: "abstract (>20 chars)" }
+    ],
+    refs: []
+  },
+  "framework-control-gaps": {
+    file: "framework-control-gaps.json",
+    idShape: /^[A-Z]/,
+    required_context: [
+      { field: "framework", check: (v) => typeof v === "string" && v.length > 0, label: "framework" },
+      { field: "control_id", check: (v) => typeof v === "string" && v.length > 0, label: "control_id" },
+      { field: "control_name", check: (v) => typeof v === "string" && v.length > 0, label: "control_name" },
+      { field: "real_requirement", check: (v) => typeof v === "string" && v.length > 20, label: "real_requirement (>20 chars)" },
+      { field: "theater_test", check: (v) => v && typeof v.claim === "string" && typeof v.test === "string", label: "theater_test{claim,test}" },
+      // evidence_cves is required UNLESS the entry declares forward_looking:true.
+      // v0.13.19 used per-entry _gap_skip annotations on 84 framework gaps;
+      // v0.13.20 replaces that with a first-class schema field operators can
+      // see in the JSON. The check honors forward_looking via the entry
+      // parameter — see the SCHEMA_FORWARD_LOOKING block in inspect().
+      { field: "evidence_cves", check: (v, entry) => (entry && entry.forward_looking === true) || (Array.isArray(v) && v.length > 0), label: "evidence_cves (or forward_looking:true)" }
+    ],
+    refs: []
+  },
+  "zeroday-lessons": {
+    file: "zeroday-lessons.json",
+    idShape: /^(CVE-|MAL-|BUG-)/,
+    required_context: [
+      { field: "attack_vector", check: (v) => v && typeof v.description === "string" && v.description.length > 20, label: "attack_vector.description" },
+      { field: "framework_coverage", check: (v) => v && Object.keys(v).length > 0, label: "framework_coverage" },
+      { field: "new_control_requirements", check: (v) => Array.isArray(v) && v.length > 0, label: "new_control_requirements" }
+    ],
+    refs: []
+  }
+};
+
+function loadCatalog(name) {
+  return JSON.parse(fs.readFileSync(path.join(DATA, name), "utf8"));
+}
+
+function inspect(catalogKey) {
+  const spec = SPEC[catalogKey];
+  if (!spec) throw new Error(`unknown catalog: ${catalogKey}`);
+  const cat = loadCatalog(spec.file);
+  const ids = Object.keys(cat).filter((k) => k !== "_meta");
+  const report = {
+    catalog: catalogKey,
+    entries: ids.length,
+    auto_imported: 0,
+    operator_curated: 0,
+    missing_context: [],
+    dangling_refs: []
+  };
+  for (const id of ids) {
+    if (!spec.idShape.test(id)) continue;
+    const e = cat[id];
+    if (!e) continue;
+    if (e._auto_imported) report.auto_imported++;
+    else report.operator_curated++;
+    const skip = e._gap_skip && Array.isArray(e._gap_skip.fields) ? new Set(e._gap_skip.fields) : new Set();
+    for (const r of spec.required_context) {
+      if (skip.has(r.field)) continue;
+      // Pass the entry as the second argument so per-field checks can
+      // inspect class-level schema flags (forward_looking, etc.). The
+      // legacy check-functions only consumed the value; new ones can
+      // opt into entry-aware evaluation.
+      if (!r.check(e[r.field], e)) {
+        report.missing_context.push({ id, field: r.field, label: r.label });
+      }
+    }
+  }
+  return report;
+}
+
+function inspectRefs(allCatalogs) {
+  const findings = [];
+  const cveCat = allCatalogs["cve-catalog"];
+  const cweCat = allCatalogs["cwe-catalog"];
+  const attCat = allCatalogs["attack-techniques"];
+  const atlCat = allCatalogs["atlas-ttps"];
+  const fwCat = allCatalogs["framework-control-gaps"];
+  // Build presence sets keyed by id (sans _meta).
+  const cweSet = new Set(Object.keys(cweCat).filter((k) => k !== "_meta"));
+  const attSet = new Set(Object.keys(attCat).filter((k) => k !== "_meta"));
+  const atlSet = new Set(Object.keys(atlCat).filter((k) => k !== "_meta"));
+  const fwSet = new Set(Object.keys(fwCat).filter((k) => k !== "_meta"));
+  for (const id of Object.keys(cveCat)) {
+    if (id === "_meta") continue;
+    const e = cveCat[id];
+    if (!e) continue;
+    for (const ref of (e.cwe_refs || [])) {
+      if (!cweSet.has(ref)) findings.push({ kind: "dangling-ref", source_catalog: "cve-catalog", source_id: id, target_catalog: "cwe-catalog", missing: ref });
+    }
+    for (const ref of (e.attack_refs || [])) {
+      if (!attSet.has(ref)) findings.push({ kind: "dangling-ref", source_catalog: "cve-catalog", source_id: id, target_catalog: "attack-techniques", missing: ref });
+    }
+    for (const ref of (e.atlas_refs || [])) {
+      if (!atlSet.has(ref)) findings.push({ kind: "dangling-ref", source_catalog: "cve-catalog", source_id: id, target_catalog: "atlas-ttps", missing: ref });
+    }
+    const fcg = e.framework_control_gaps || {};
+    for (const key of Object.keys(fcg)) {
+      if (!fwSet.has(key)) findings.push({ kind: "dangling-ref", source_catalog: "cve-catalog", source_id: id, target_catalog: "framework-control-gaps", missing: key });
+    }
+  }
+  return findings;
+}
+
+function parseArgs(argv) {
+  const out = { pretty: false, strict: false, catalog: null, klass: null };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--pretty") out.pretty = true;
+    else if (a === "--strict") out.strict = true;
+    else if (a === "--catalog") out.catalog = argv[++i];
+    else if (a === "--class") out.klass = argv[++i];
+  }
+  return out;
+}
+
+function emitPretty(report) {
+  const lines = [];
+  lines.push("Catalog gap audit");
+  lines.push("=================");
+  for (const r of report.per_catalog) {
+    lines.push(`\n[${r.catalog}]  entries=${r.entries}  auto-imported=${r.auto_imported}  operator-curated=${r.operator_curated}`);
+    if (r.missing_context.length === 0) {
+      lines.push("  ✓ context complete on every entry");
+    } else {
+      // Group by field for tidier output.
+      const byField = new Map();
+      for (const m of r.missing_context) {
+        if (!byField.has(m.field)) byField.set(m.field, []);
+        byField.get(m.field).push(m.id);
+      }
+      for (const [field, ids] of byField) {
+        lines.push(`  missing ${field} on ${ids.length} entries: ${ids.slice(0, 5).join(", ")}${ids.length > 5 ? `  ... +${ids.length - 5}` : ""}`);
+      }
+    }
+  }
+  lines.push("\nCross-catalog dangling refs:");
+  if (report.dangling_refs.length === 0) {
+    lines.push("  ✓ every cross-ref resolves");
+  } else {
+    const byTarget = new Map();
+    for (const f of report.dangling_refs) {
+      const key = `${f.source_catalog}.${f.target_catalog}`;
+      if (!byTarget.has(key)) byTarget.set(key, []);
+      byTarget.get(key).push(`${f.source_id} → ${f.missing}`);
+    }
+    for (const [k, list] of byTarget) {
+      lines.push(`  ${k}: ${list.length} dangling`);
+      for (const l of list.slice(0, 5)) lines.push(`    ${l}`);
+      if (list.length > 5) lines.push(`    ... +${list.length - 5}`);
+    }
+  }
+  lines.push("\nDraft debt (auto-imported / total):");
+  for (const r of report.per_catalog) {
+    const pct = r.entries === 0 ? 0 : ((r.auto_imported / r.entries) * 100).toFixed(1);
+    lines.push(`  ${r.catalog.padEnd(28)} ${r.auto_imported} / ${r.entries}  (${pct}%)`);
+  }
+  return lines.join("\n");
+}
+
+// Valid finding-class names for the `--class` filter. The pretty + JSON
+// emitters always include every section, but counts and strict-exit
+// gating respect the active filter.
+const VALID_CLASSES = new Set(["missing-context", "dangling-ref", "draft-debt"]);
+
+function main() {
+  const opts = parseArgs(process.argv);
+  if (opts.klass && !VALID_CLASSES.has(opts.klass)) {
+    console.error(`unknown class: ${opts.klass}  valid: ${[...VALID_CLASSES].join(", ")}`);
+    process.exitCode = 2;
+    return;
+  }
+  const catalogKeys = opts.catalog ? [opts.catalog] : Object.keys(SPEC);
+  const perCatalog = [];
+  const allLoaded = {};
+  for (const k of catalogKeys) {
+    if (!SPEC[k]) {
+      console.error(`unknown catalog: ${k}  valid: ${Object.keys(SPEC).join(", ")}`);
+      process.exitCode = 2;
+      return;
+    }
+    perCatalog.push(inspect(k));
+    allLoaded[k] = loadCatalog(SPEC[k].file);
+  }
+  // Load all needed catalogs for cross-ref pass even when --catalog scoped.
+  for (const k of Object.keys(SPEC)) if (!allLoaded[k]) allLoaded[k] = loadCatalog(SPEC[k].file);
+  const dangling = opts.catalog && opts.catalog !== "cve-catalog" ? [] : inspectRefs(allLoaded);
+
+  // Apply the --class filter before counts + strict-exit gating.
+  // Missing-context findings on per_catalog and dangling_refs are the
+  // two policed classes; draft-debt is informational-only (the audit
+  // surfaces draft-debt but it does not fail strict mode by design).
+  const filteredPerCatalog = opts.klass === "dangling-ref" || opts.klass === "draft-debt"
+    ? perCatalog.map((r) => ({ ...r, missing_context: [] }))
+    : perCatalog;
+  const filteredDangling = opts.klass === "missing-context" || opts.klass === "draft-debt"
+    ? []
+    : dangling;
+
+  const report = {
+    generated_at: TODAY,
+    class_filter: opts.klass || null,
+    per_catalog: filteredPerCatalog,
+    dangling_refs: filteredDangling,
+    totals: {
+      catalogs: filteredPerCatalog.length,
+      entries: filteredPerCatalog.reduce((n, r) => n + r.entries, 0),
+      missing_context: filteredPerCatalog.reduce((n, r) => n + r.missing_context.length, 0),
+      dangling_refs: filteredDangling.length
+    }
+  };
+  if (opts.pretty) {
+    process.stdout.write(emitPretty(report) + "\n");
+  } else {
+    process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+  }
+  if (opts.strict && (report.totals.missing_context > 0 || report.totals.dangling_refs > 0)) {
+    process.exitCode = 1;
+  }
+}
+
+if (require.main === module) main();
+
+module.exports = { SPEC, inspect, inspectRefs };