@blamejs/exceptd-skills 0.19.33 → 0.19.34

package/lib/framework-gap.js

@@ -84,38 +84,22 @@ const OPTIMAL = {
 };
 
 /**
- * Score how much a given framework lags behind current threat reality.
- * Returns 0 (no lag) to 100 (complete theater).
- *
- * @param {string} frameworkId - Key in framework-control-gaps.json
- * @param {object} controlGaps - Parsed framework-control-gaps.json
- * @param {object} globalFrameworks - Parsed global-frameworks.json
- * @returns {{ score: number, breakdown: object, label: string }}
+ * How far a framework lags current threat reality, 0 (no lag) to 100 (complete
+ * theater), as { score, label, breakdown }. The catalogs arrive parsed.
  */
 function lagScore(frameworkId, controlGaps, globalFrameworks) {
   const frameworkData = _findFrameworkData(frameworkId, globalFrameworks);
 
-  // global-frameworks uses short KEYS (EU_AI_ACT, NCSC_CAF) while
-  // framework-control-gaps stores human-readable framework strings ("EU
-  // Artificial Intelligence Act (2024/1689)"). A naive
-  // `g.framework.includes(frameworkId)` only accidentally matched the few
-  // frameworks whose key happens to be a substring of the catalog string
-  // (DORA, GDPR, NIS2); every other framework reported
-  // framework_specific_gaps:0. Resolve the framework's display name first,
-  // then match the catalog with the SAME normalized scheme gapReport() and
-  // the orchestrator use, so the two paths converge. g.framework may be a
-  // string or an array — iterate either form.
+  // global-frameworks is keyed by short id (EU_AI_ACT) while
+  // framework-control-gaps stores display strings ("EU Artificial Intelligence
+  // Act (2024/1689)"), so the display name resolves first and matching uses the
+  // SAME normalized scheme as gapReport(). `g.framework` is a string or an array.
   const normalize = (s) => String(s).toLowerCase().replace(/[\s_-]/g, '');
   const idNorm = normalize(frameworkId);
   const nameNorm = frameworkData?.full_name ? normalize(frameworkData.full_name) : null;
-  // Data-driven aliases close the naming divergence between a framework's
-  // global-frameworks full_name and the (often different) labels the control-gap
-  // catalog uses for it — e.g. ASD_ISM's full_name is "Australian Signals
-  // Directorate Information Security Manual" but the catalog labels its 5 gaps
-  // "au-ism" / "ACSC ISM" / "Australian Government Information Security Manual",
-  // so neither nameNorm nor idNorm matched and lagScore reported 0 gaps. Aliases
-  // live in data/global-frameworks.json (catalog_aliases) so this generalizes to
-  // any future framework whose catalog label diverges from its name.
+  // catalog_aliases in data/global-frameworks.json bridges a framework's
+  // full_name and the labels the control-gap catalog uses: ASD_ISM is also
+  // "au-ism" / "ACSC ISM" there, which neither nameNorm nor idNorm matches.
   const aliasNorms = Array.isArray(frameworkData?.catalog_aliases)
     ? frameworkData.catalog_aliases.map((a) => normalize(a)).filter(Boolean)
     : [];
@@ -132,11 +116,8 @@ function lagScore(frameworkId, controlGaps, globalFrameworks) {
     if (normalize(key).startsWith(idNorm)) return true;         // gap-key prefix
     return false;
   });
-  // Observable backstop: a framework that EXISTS in global-frameworks resolving
-  // to zero catalog gaps is almost always a fresh naming divergence (a new
-  // catalog label not yet in catalog_aliases), not a genuinely gap-free
-  // framework. Surface it as a structured flag rather than a silent 0 so a
-  // regression is greppable in the breakdown instead of invisible.
+  // A framework that resolves yet matches zero catalog gaps is almost always a
+  // label missing from catalog_aliases, not a gap-free framework.
   const resolvedButZeroGaps = Boolean(frameworkData && gaps.length === 0);
 
   const universalGaps = Object.values(controlGaps).filter(g =>
@@ -168,25 +149,16 @@ function lagScore(frameworkId, controlGaps, globalFrameworks) {
       pqc_coverage: { coverage: frameworkData?.pqc_coverage ?? 'unknown', score: pqcScore },
       universal_gaps: { count: universalGaps.length, score: universalGapScore },
       framework_specific_gaps: gaps.length,
-      // True only when the framework resolves in global-frameworks yet matched
-      // zero catalog gaps — a likely naming divergence worth investigating.
       framework_resolved_but_zero_gaps: resolvedButZeroGaps
     }
   };
 }
 
 /**
- * Generate a gap report for one or more frameworks vs. a threat scenario.
- *
- * @param {string[]} frameworkIds - Framework identifiers
- * @param {string} threatScenario - Description of the threat or CVE ID
- * @param {object} controlGaps - Parsed framework-control-gaps.json
- * @param {object} cveCatalog - Parsed cve-catalog.json (optional)
- * @param {object} opts - { allFrameworks?: boolean, lessons?: object }
- *        opts.lessons is the parsed zeroday-lessons.json. Optional: callers
- *        that omit it get a report without the new-control section rather than
- *        an error, which keeps the existing call signature working.
- * @returns {{ frameworks: object, universal_gaps: object[], new_control_requirements: object[], theater_risks: object[] }}
+ * Gap report for one or more frameworks against a threat scenario — a CVE id or
+ * free text. Omitting `opts.lessons` (parsed zeroday-lessons.json) yields a
+ * report with no new-control section rather than an error. Returns
+ * { frameworks, universal_gaps, new_control_requirements, theater_risks, summary }.
  */
 function gapReport(frameworkIds, threatScenario, controlGaps, cveCatalog = {}, opts = {}) {
   const scenario = threatScenario.toLowerCase();
@@ -207,14 +179,9 @@ function gapReport(frameworkIds, threatScenario, controlGaps, cveCatalog = {}, o
 
   const frameworkResults = {};
   for (const id of frameworkIds) {
-    // Match a framework filter ID against catalog entries by:
-    //   - exact match against gap.framework (e.g. "NIST SP 800-53 Rev 5")
-    //   - normalized substring match (strip case + spaces + hyphens, e.g. user
-    //     passing "nist-800-53" matches catalog "NIST SP 800-53 Rev 5")
-    //   - normalized prefix match on the gap KEY (e.g. user "nist-800-53"
-    //     matches keys "NIST-800-53-SI-2", "NIST-800-53-SC-8")
-    // This makes the named-framework filter behave the same way `all` does
-    // when extracting per-framework subsets.
+    // A filter id matches three ways: exactly against gap.framework, as a
+    // normalized substring of it ("nist-800-53" → "NIST SP 800-53 Rev 5"), or as
+    // a normalized prefix of the gap KEY ("NIST-800-53-SI-2").
     const normalize = (s) => String(s).toLowerCase().replace(/[\s_-]/g, '');
     const idNorm = normalize(id);
     const frameworkGaps = relevantGaps.filter(([key, g]) => {
@@ -236,13 +203,9 @@ function gapReport(frameworkIds, threatScenario, controlGaps, cveCatalog = {}, o
     };
   }
 
-  // Scope the report to what the operator actually requested. With an explicit
-  // framework filter, only gaps that survived the per-framework filter
-  // (frameworkResults[*].gaps) belong in the report; with `all`, every
-  // scenario-relevant gap does. `seen` is the de-duplicated set of surviving
-  // gap keys (a single gap can match multiple requested frameworks). Both
-  // theater_risks and the matching count derive from it so the per-framework
-  // body, the theater-risk list, and the summary footer all agree.
+  // With an explicit filter only the gaps that survived it belong in the report;
+  // with `all`, every scenario-relevant gap does. theater_risks and the matching
+  // count both derive from this, so body, theater list and footer agree.
   let scopedGaps;
   if (opts.allFrameworks) {
     scopedGaps = relevantGaps;
@@ -254,19 +217,9 @@ function gapReport(frameworkIds, threatScenario, controlGaps, cveCatalog = {}, o
     scopedGaps = relevantGaps.filter(([key]) => seen.has(key));
   }
 
-  // Previously this filtered on `theater_pattern`
-  // (a legacy field) but the v0.12.29 backfill added a structured
-  // `theater_test` block on all 118 entries while leaving most without
-  // `theater_pattern`. Result: the per-entry badge (line 188 above)
-  // showed "⚠ THEATER RISK" for every open gap, but the summary
-  // footer reported "0 theater-risk controls" because nothing matched
-  // the legacy field. Now: an entry is theater-risk if it's open AND
-  // carries EITHER `theater_test` OR `theater_pattern`. Footer + badge
-  // count agree.
-  //
-  // theater_risks is built from scopedGaps (not the full relevantGaps) so a
-  // single-framework request cannot leak or mis-summarize theater controls
-  // from frameworks the operator never asked about.
+  // Theater-risk is open AND EITHER `theater_test` OR `theater_pattern` — most
+  // entries have only the structured test, and filtering on `theater_pattern`
+  // alone puts the badge and the summary footer at odds.
   const theaterRisks = scopedGaps
     .filter(([, g]) => g.status === 'open' && (g.theater_test || g.theater_pattern))
     .map(([key, g]) => ({
@@ -276,39 +229,20 @@ function gapReport(frameworkIds, threatScenario, controlGaps, cveCatalog = {}, o
       theater_test_present: !!g.theater_test,
     }));
 
-  // Summary matching count. With `all` frameworks the summary counts every
-  // scenario-relevant gap across the whole catalog (relevantGaps). With an
-  // explicit framework filter the summary must agree with the per-framework
-  // body the operator actually sees — otherwise `framework-gap nist-800-53
-  // <cve>` shows e.g. "2 matching control gap(s)" per-framework but "Summary:
-  // 8 matching gaps" (every framework's hits, pre-filter).
+  // The summary counts what the operator sees, so the footer cannot overcount.
   const matchingGapCount = scopedGaps.length;
 
-  // Controls the zero-day lesson for this CVE says no framework carries yet.
-  //
-  // `frameworks[].gaps` covers the other half of the same question — existing
-  // controls that are insufficient — so a report that answered only that half
-  // told an operator which controls fall short without ever saying what to put
-  // in their place. The lessons catalog had recorded exactly that for 302 CVEs
-  // and nothing read the field, so the analysis existed and reached no one.
-  //
-  // Keyed by CVE, so a free-text scenario legitimately resolves to none.
+  // Controls the zero-day lesson for this CVE says no framework carries yet —
+  // the other half of what `frameworks[].gaps` answers. Keyed by CVE, so a
+  // free-text scenario legitimately resolves to none.
   const lessons = (opts && opts.lessons) || {};
   const lessonEntry = Object.entries(lessons)
     .find(([id]) => id.toLowerCase() === scenario);
   const newControls = (lessonEntry && Array.isArray(lessonEntry[1].new_control_requirements))
     ? lessonEntry[1].new_control_requirements
-      // Three catalog entries held a bare string where the schema expects a
-      // control object, which rendered as "- undefined undefined:" the moment
-      // this section started being shown. Emitting a malformed record is worse
-      // than omitting it, so drop anything the renderer cannot print.
-      //
-      // Every field the renderer interpolates has to be checked, not just the
-      // identifying one: guarding `id` alone still let `{ id: 'NEW-X' }` reach
-      // the output as "NEW-X undefined:", so the guard would have covered the
-      // bare-string case that prompted it and nothing else. The data itself is
-      // fixed; the catalog test fails on the shape so a malformed record cannot
-      // hide behind this filter.
+      // A record the renderer cannot print is dropped rather than emitted as
+      // "- undefined undefined:". EVERY interpolated field is checked — guarding
+      // `id` alone still lets `{ id: 'NEW-X' }` through as "NEW-X undefined:".
       .filter(c =>
         c && typeof c === 'object' &&
         typeof c.id === 'string' && c.id.trim() !== '' &&
@@ -320,9 +254,7 @@ function gapReport(frameworkIds, threatScenario, controlGaps, cveCatalog = {}, o
         name: c.name,
         requirement: c.description,
         evidence: c.evidence,
-        // Which framework controls this is meant to close. Without it the
-        // control reads as free-floating advice rather than an answer to a
-        // named gap above.
+        // The framework controls this closes; without them it is free-floating advice.
         closes: Array.isArray(c.gap_closes) ? c.gap_closes : [],
       }))
     : [];
@@ -347,11 +279,8 @@ function gapReport(frameworkIds, threatScenario, controlGaps, cveCatalog = {}, o
 }
 
 /**
- * Run all seven theater pattern checks against an organization's control inventory.
- *
- * @param {object} controlGaps - Parsed framework-control-gaps.json
- * @param {object} cveCatalog - Parsed cve-catalog.json
- * @returns {{ findings: object[], theater_score: number, compliant_but_exposed: boolean }}
+ * Runs every THEATER_PATTERNS check against a control inventory, returning
+ * { findings, theater_score, theater_label, compliant_but_exposed, recommendation }.
  */
 function theaterCheck(controlGaps, cveCatalog = {}) {
   const findings = [];
@@ -385,13 +314,7 @@ function theaterCheck(controlGaps, cveCatalog = {}) {
   };
 }
 
-/**
- * Compare multiple frameworks by lag score for a dashboard view.
- *
- * @param {object} controlGaps - Parsed framework-control-gaps.json
- * @param {object} globalFrameworks - Parsed global-frameworks.json
- * @returns {Array} Sorted by lag score descending
- */
+/** Every framework in globalFrameworks with its lag score, sorted descending. */
 function compareFrameworks(controlGaps, globalFrameworks) {
   const results = [];
   const frameworkIds = _extractFrameworkIds(globalFrameworks);
@@ -404,8 +327,6 @@ function compareFrameworks(controlGaps, globalFrameworks) {
   return results.sort((a, b) => b.score - a.score);
 }
 
-// --- private helpers ---
-
 function _findFrameworkData(frameworkId, globalFrameworks) {
   for (const jurisdiction of Object.values(globalFrameworks)) {
     if (!jurisdiction.frameworks) continue;

package/lib/gap-detectors.js

@@ -1,51 +1,11 @@
 "use strict";
 /**
- * lib/gap-detectors.js
- *
- * v0.13.21 — Catalog gap detection beyond the v0.13.19 missing-context /
- * dangling-ref / draft-debt classes. The audit-catalog-gaps detector
- * surfaced field-presence holes; this module adds seven cross-cutting
- * detection classes the prior detector did not cover.
- *
- * Each detector is a pure function: takes the loaded catalogs + options,
- * returns an array of findings. The audit-catalog-gaps CLI composes them
- * into a unified report; the integrity test exercises them against the
- * shipped catalogs; --class filters select between them.
- *
- * Detection classes:
- *
- *   1. content-quality       — fields present but content weak
- *                              (short, placeholder-language, name-as-
- *                              description, KEV-listed but no advisories)
- *
- *   2. temporal-staleness    — last_verified > 180d, last_updated > 365d,
- *                              CISA-KEV due-date passed, EPSS stale
- *
- *   3. logical-consistency   — internal-state contradictions
- *                              (cisa_kev:true + date:null, etc.)
- *
- *   4. cross-ref-completeness — bidirectional references
- *                               (CVE→CWE present but CWE.evidence_cves
- *                               missing the back-ref)
- *
- *   5. schema-evolution      — required-since-version fields missing
- *                              on older entries
- *
- *   6. operator-action-sla   — auto-imported entries older than the
- *                              curation-SLA without operator action
- *
- *   7. unused-orphan         — catalog entries no skill / playbook /
- *                              CVE references — dead-weight content
- *
- * Why pure functions: each detector is independently testable against
- * synthetic catalog inputs, and the integration is just `Array.concat`
- * over the seven results. Composing in audit-catalog-gaps.js stays
- * thin.
+ * Catalog gap detection. Each detector is a pure function over the loaded
+ * catalogs plus options, returning an array of findings; DETECTOR_CLASSES below
+ * names the full set.
  */
 
-// Sentinel strings that indicate placeholder / curation-pending content.
-// Adding new sentinels here makes them findable across every text-heavy
-// field without changing the call sites.
+// Placeholder / curation-pending sentinels, applied to every text-heavy field.
 const PLACEHOLDER_SENTINELS = [
   /pending operator curation/i,
   /refer to vendor advisory for IOC list/i,
@@ -65,11 +25,7 @@ function hasPlaceholderLanguage(str) {
   return false;
 }
 
-// ---------- 1. content-quality ----------
-//
-// Fields present but content weak. Each rule is per-catalog + per-field
-// because the "what's weak" depends on the field's semantic role.
-
+// Fields present but weak; what counts as weak is per catalog and field.
 function contentQualityFindings(loaded) {
   const out = [];
   const cve = loaded["cve-catalog"];
@@ -80,9 +36,7 @@ function contentQualityFindings(loaded) {
     const e = cve[id];
     if (!e) continue;
 
-    // Vector text: < 50 chars or placeholder-language indicates the
-    // operator didn't actually describe the primitive. Hard Rule #1
-    // implicit: every CVE needs a real exploitation-vector description.
+    // A short or placeholder vector means the exploitation primitive is undescribed.
     if (typeof e.vector === "string" && e.vector.length > 0 && e.vector.length < 50) {
       out.push({ class: "content-quality", catalog: "cve-catalog", id,
         field: "vector", reason: `vector is ${e.vector.length} chars (< 50 threshold) — likely a stub` });
@@ -92,24 +46,18 @@ function contentQualityFindings(loaded) {
         field: "vector", reason: "vector contains placeholder-language sentinel" });
     }
 
-    // poc_description with placeholder language while poc_available:true
-    // is a contradiction — the project claims PoC exists but didn't
-    // document where.
+    // poc_available:true with placeholder text claims a PoC without saying where.
     if (e.poc_available === true && hasPlaceholderLanguage(e.poc_description)) {
       out.push({ class: "content-quality", catalog: "cve-catalog", id,
         field: "poc_description", reason: "poc_available:true but description carries placeholder sentinel" });
     }
 
-    // KEV-listed CVEs MUST have vendor_advisories[] non-empty — the
-    // KEV listing implies CISA has linked vendor advisory metadata.
-    // Empty vendor_advisories is an operator-curation gap.
+    // A KEV listing implies CISA linked advisory metadata, so empty is a curation gap.
     if (e.cisa_kev === true && (!Array.isArray(e.vendor_advisories) || e.vendor_advisories.length === 0)) {
       out.push({ class: "content-quality", catalog: "cve-catalog", id,
         field: "vendor_advisories", reason: "cisa_kev:true but vendor_advisories is empty" });
     }
 
-    // Name reused as description (catalog noise — operator didn't
-    // write a real description, just echoed the name).
     if (typeof e.name === "string" && typeof e.description === "string"
         && e.name === e.description && e.name.length > 0) {
       out.push({ class: "content-quality", catalog: "cve-catalog", id,
@@ -119,12 +67,7 @@ function contentQualityFindings(loaded) {
   return out;
 }
 
-// ---------- 2. temporal-staleness ----------
-//
-// Time-based decay. Catalog entries get stale as the threat-intelligence
-// landscape shifts. Surfacing stale entries gives operators a re-verify
-// work-queue.
-
+// Time-based decay: stale entries become an operator re-verify work queue.
 function daysSince(iso, now) {
   if (typeof iso !== "string" || !/^\d{4}-\d{2}-\d{2}/.test(iso)) return null;
   const t = Date.parse(iso);
@@ -157,17 +100,11 @@ function temporalStalenessFindings(loaded, opts = {}) {
         field: "last_updated", reason: `last_updated is ${sinceUpdated}d old (threshold ${STALE_UPDATED_DAYS}d)` });
     }
 
-    // NOTE: a passed CISA KEV due-date is intentionally NOT a temporal-staleness
-    // finding. The due-date is a fixed external date about an OPERATOR's
-    // remediation deadline, not about whether this catalog entry's data is
-    // fresh — every historical KEV entry's due-date passes by calendar and says
-    // nothing about catalog currency. Counting it made the class grow without
-    // bound as the catalog ages and as KEV-import drafts get curated (promotion
-    // would otherwise re-add the finding the draft exemption had removed).
-    // Catalog-data freshness is measured by maintainer-controllable fields:
-    // source_verified, last_updated, and epss_date (below).
-
-    // EPSS score has its own currency clock — FIRST recalculates daily.
+    // A passed CISA KEV due-date is NOT temporal staleness: it is a fixed
+    // external remediation deadline, and every historical entry's passes by
+    // calendar while saying nothing about catalog currency.
+
+    // EPSS has its own currency clock; FIRST recalculates daily.
     if (typeof e.epss_score === "number" && typeof e.epss_date === "string") {
       const sinceEpss = daysSince(e.epss_date, now);
       if (sinceEpss !== null && sinceEpss > STALE_EPSS_DAYS) {
@@ -179,12 +116,7 @@ function temporalStalenessFindings(loaded, opts = {}) {
   return out;
 }
 
-// ---------- 3. logical-consistency ----------
-//
-// Internal-state rules that must hold across multiple fields. These are
-// the bugs that pass schema validation (every required field is present)
-// but the field combinations don't make sense.
-
+// Multi-field rules: combinations that pass schema validation yet contradict.
 function logicalConsistencyFindings(loaded) {
   const out = [];
   const cve = loaded["cve-catalog"];
@@ -195,18 +127,14 @@ function logicalConsistencyFindings(loaded) {
     const e = cve[id];
     if (!e) continue;
 
-    // cisa_kev:true with null cisa_kev_date — KEV listing has a
-    // dateAdded field in CISA's authoritative JSON; null means we
-    // failed to record it at intake time.
+    // CISA's JSON carries dateAdded on every listing, so null means intake lost it.
     if (e.cisa_kev === true && (e.cisa_kev_date == null || e.cisa_kev_date === "")) {
       out.push({ class: "logical-consistency", catalog: "cve-catalog", id,
         rule: "cisa_kev_date_present_when_kev_true",
         reason: "cisa_kev:true requires cisa_kev_date (CISA's dateAdded)" });
     }
 
-    // live_patch_available:true with empty live_patch_tools[] — the
-    // RWEP live_patch_available factor only fires when tools list
-    // names a real live-patch path; the boolean alone is a lie.
+    // The RWEP deduction only holds when the tools list names a real live-patch path.
     if (e.live_patch_available === true
         && (!Array.isArray(e.live_patch_tools) || e.live_patch_tools.length === 0)) {
       out.push({ class: "logical-consistency", catalog: "cve-catalog", id,
@@ -214,9 +142,7 @@ function logicalConsistencyFindings(loaded) {
         reason: "live_patch_available:true but live_patch_tools is empty — RWEP factor would mis-fire" });
     }
 
-    // ai_discovered:true requires named AI tool in attribution_note
-    // (Hard Rule #1 enforcement). The schema-validator catches
-    // discovery_source==unknown but not the attribution-text absence.
+    // The schema validator catches discovery_source==unknown, not a too-short note.
     if (e.ai_discovered === true) {
       const note = e.ai_discovery_notes || e.discovery_attribution_note || "";
       if (typeof note !== "string" || note.length < 30) {
@@ -226,8 +152,6 @@ function logicalConsistencyFindings(loaded) {
       }
     }
 
-    // active_exploitation:"confirmed" with empty verification_sources
-    // is a credibility gap — exploitation claims need sourcing.
     if (e.active_exploitation === "confirmed"
         && (!Array.isArray(e.verification_sources) || e.verification_sources.length < 2)) {
       out.push({ class: "logical-consistency", catalog: "cve-catalog", id,
@@ -235,7 +159,6 @@ function logicalConsistencyFindings(loaded) {
         reason: `active_exploitation:"confirmed" requires >= 2 verification_sources; have ${(e.verification_sources || []).length}` });
     }
 
-    // rwep_score declared but rwep_factors empty — score is unsupported.
     if (typeof e.rwep_score === "number"
         && (!e.rwep_factors || Object.keys(e.rwep_factors).length === 0)) {
       out.push({ class: "logical-consistency", catalog: "cve-catalog", id,
@@ -246,13 +169,8 @@ function logicalConsistencyFindings(loaded) {
   return out;
 }
 
-// ---------- 4. cross-ref-completeness ----------
-//
-// Bidirectional reference checks. Pre-v0.13.21, the dangling-ref class
-// only verified the forward direction (CVE.cwe_refs[] resolves into
-// cwe-catalog). This class verifies the BACK-reference is present too
-// (CWE.evidence_cves[] includes the CVE that cited it).
-
+// The dangling-ref class verifies the forward direction; this one verifies the
+// back-reference: the target entry lists the CVE that cited it.
 function crossRefCompletenessFindings(loaded) {
   const out = [];
   const cve = loaded["cve-catalog"];
@@ -269,8 +187,7 @@ function crossRefCompletenessFindings(loaded) {
     if (cid === "_meta") continue;
     const e = cve[cid];
     if (!e) continue;
-    // Drafts excluded — auto-imported entries don't yet have curated
-    // refs.
+    // Drafts excluded — an auto-imported entry has no curated refs yet.
     if (e._auto_imported) continue;
     for (const c of (e.cwe_refs || [])) {
       if (!cveByCwe.has(c)) cveByCwe.set(c, new Set());
@@ -325,12 +242,7 @@ function crossRefCompletenessFindings(loaded) {
   return out;
 }
 
-// ---------- 5. schema-evolution ----------
-//
-// Required-since-version checks. Fields the schema requires today were
-// optional on entries added in older releases. The audit surfaces those
-// pre-existing entries so operator-curation can backfill.
-
+// Fields the schema requires today that were optional on older entries.
 const REQUIRED_SINCE = {
   "cve-catalog": [
     { field: "ai_discovered", since: "0.12.36", check: (v) => typeof v === "boolean" },
@@ -360,12 +272,7 @@ function schemaEvolutionFindings(loaded) {
   return out;
 }
 
-// ---------- 6. operator-action-sla ----------
-//
-// Auto-imported entries are intake-class events. The catalog allows them
-// to ship un-curated (operators add detail later) but past a threshold
-// the un-curated state IS the problem.
-
+// Past the SLA, an entry's un-curated state is itself the finding.
 function operatorActionSlaFindings(loaded, opts = {}) {
   const now = opts.now || new Date();
   const AUTO_IMPORT_SLA_DAYS = opts.auto_import_sla_days || 60;
@@ -396,35 +303,17 @@ function operatorActionSlaFindings(loaded, opts = {}) {
   return out;
 }
 
-// ---------- 7. unused-orphan ----------
-//
-// Entries that no skill / playbook / CVE references — dead-weight
-// content the operator can either repurpose or remove.
-
-// Build reference sets from skills/*.md frontmatter + body and from
-// data/playbooks/*.json content. Pre-v0.13.21 follow-up (codex P1 PR
-// #61): unusedOrphanFindings defaulted these to empty sets, which
-// flagged D3FEND / CWE / ATT&CK IDs referenced in skill bodies as
-// "unused orphans" — false positive. v0.13.21+ builds the reference
-// sets internally when the caller doesn't supply them.
-//
-// The regex is permissive — any CWE-NNN / T1234[.456] / AML.TNNNN /
-// D3[AF]-XX / RFC-NNN token in a skill body or playbook JSON counts as a
-// reference. We deliberately scan the FULL text, not just structured
-// fields, because skill bodies cite IDs in prose ("see CWE-79") as
-// often as in frontmatter. The D3FEND alternative covers all three
-// namespaces — D3- techniques, D3A- digital artifacts, and D3F-
-// fingerprints — with alphanumeric segments; the prior `D3-[A-Z]+`
-// pattern matched neither the D3A-/D3F- prefixes nor digit-bearing
-// segments, so a D3A-* citation in a skill body went unrecognized and
-// the entry it referenced was mis-flagged as an unused orphan.
+// Entries nothing references — dead weight to repurpose or remove.
+
+// Any id token in a skill body or playbook JSON counts as a reference, and the
+// full text is scanned rather than the structured fields, because skill bodies
+// cite ids in prose. The D3FEND alternative must cover D3-, D3A- and D3F-: a
+// narrower `D3-[A-Z]+` misses a D3A- citation and mis-flags its entry as orphan.
 const REFERENCE_TOKEN_RE = /\b(?:CWE-\d+|T\d{4}(?:\.\d{3})?|AML\.T\d{4}(?:\.\d{3})?|D3[AF]?-[A-Z0-9]+(?:-[A-Z0-9]+)*|RFC-\d+)\b/g;
 
 function buildExternalRefs(rootPath) {
-  // Lazy require — `path` + `fs` are already in scope at module level.
-  // Tolerate the absence of either directory (synthetic-test contexts
-  // may not have a skills/ tree). Returns { skillRefs, playbookRefs }
-  // as Sets of stringified IDs.
+  // Returns { skillRefs, playbookRefs } as Sets of id strings; a missing
+  // skills/ or playbooks/ tree yields an empty set rather than throwing.
   if (!rootPath) {
     const path = require("path");
     rootPath = path.join(__dirname, "..");
@@ -457,9 +346,8 @@ function buildExternalRefs(rootPath) {
 
 function unusedOrphanFindings(loaded, opts = {}) {
   const out = [];
-  // Auto-populate skill/playbook refs when the caller didn't supply
-  // them. The composing runAllDetectors() also auto-populates via
-  // _autoLoadRefs unless tests pin explicit empty sets.
+  // Auto-populate the reference sets when the caller supplies neither; a caller
+  // wanting genuinely empty sets passes _autoLoadRefs:false.
   let skillRefs = opts.skillRefs;
   let playbookRefs = opts.playbookRefs;
   if (!skillRefs && !playbookRefs && opts._autoLoadRefs !== false) {
@@ -482,10 +370,6 @@ function unusedOrphanFindings(loaded, opts = {}) {
   }
   const isReferenced = (id) => skillRefs.has(id) || playbookRefs.has(id) || cveRefIds.has(id);
 
-  // CWE / ATT&CK / ATLAS / D3FEND / framework-gap entries that nothing
-  // references are orphans. Operator-curated entries get a longer
-  // grace period (intentional forward-looking content); auto-imported
-  // entries with no reference are clearer waste.
   for (const catKey of ["cwe-catalog", "attack-techniques", "atlas-ttps", "d3fend-catalog", "framework-control-gaps"]) {
     const cat = loaded[catKey];
     if (!cat) continue;
@@ -503,13 +387,9 @@ function unusedOrphanFindings(loaded, opts = {}) {
   return out;
 }
 
-// ---------- Composite ----------
-
 function runAllDetectors(loaded, opts = {}) {
-  // Pre-populate external reference sets ONCE and thread them through
-  // every detector that needs them. Avoids re-scanning skills/ +
-  // playbooks/ per detector and keeps the same reference set
-  // consistent across the composed run.
+  // Build the external reference sets once and thread them through, so a composed
+  // run does not re-scan per detector or measure against different sets.
   const orphanOpts = { ...opts };
   if (!orphanOpts.skillRefs && !orphanOpts.playbookRefs && opts._autoLoadRefs !== false) {
     const refs = buildExternalRefs(opts._rootPath);
@@ -527,10 +407,8 @@ function runAllDetectors(loaded, opts = {}) {
   ];
 }
 
-// Canonical list of detection classes runAllDetectors can emit. The
-// budget gate asserts class-set equality against this list so a future
-// 8th detector added without a budget entry fails-closed (codex P2
-// PR #61).
+// Every class runAllDetectors can emit. The budget gate asserts class-set equality
+// against this list, so a detector added without a budget entry fails closed.
 const DETECTOR_CLASSES = [
   "content-quality",
   "temporal-staleness",