@blamejs/exceptd-skills 0.19.33 → 0.19.34

package/scripts/builders/did-ladders.js

@@ -1,18 +1,11 @@
 "use strict";
 /**
- * scripts/builders/did-ladders.js
- *
- * Builds `data/_indexes/did-ladders.json` — canonical defense-in-depth
- * ladders per high-frequency attack class. Each ladder is a layered
- * sequence of controls (perimeter → identity → workload → data →
- * detection) with a cross-reference to the source skill(s) that
- * operationalize each layer and the D3FEND countermeasures backing each
- * layer.
- *
- * Curated content, validated against the manifest: every referenced skill
- * and D3FEND id must exist in their respective catalogs or the build
- * fails. This is the only place where the project's DiD knowledge is
- * laid out flat across attack classes.
+ * Builds `data/_indexes/did-ladders.json`: one defense-in-depth ladder per
+ * high-frequency attack class, each layer naming the skill that operationalizes
+ * it and the D3FEND countermeasures behind it. The ladders are curated here —
+ * the only place the project's DiD knowledge is laid out flat across attack
+ * classes — and a referenced skill or D3FEND id absent from its catalog fails
+ * the build.
  */
 
 const LADDERS = [

package/scripts/builders/frequency.js

@@ -1,21 +1,8 @@
 "use strict";
 /**
- * scripts/builders/frequency.js
- *
- * Builds `data/_indexes/frequency.json` — citation-count tables. For each
- * catalog (CWE, ATLAS, ATT&CK, D3FEND, framework gaps, RFC, DLP), counts
- * how many skills cite each entry. Surfaces which entries are load-bearing
- * (cited by many) vs. orphan-adjacent (cited by ≤1).
- *
- * Per-field shape:
- *   {
- *     <entry_id>: { count, skills: [name, ...] }
- *   }
- *
- * Plus rollups:
- *   - top_cited: top 10 entries per field
- *   - orphan_adjacent: entries cited by exactly one skill
- *   - uncited: catalog entries with zero skill citations (flagged for review)
+ * Builds `data/_indexes/frequency.json`: how many skills cite each entry of
+ * each catalog, with rollups that separate the load-bearing entries from the
+ * ones a single skill cites and the ones nothing cites at all.
  */
 
 function buildFrequency({ skills, catalogs }) {
@@ -51,7 +38,6 @@ function buildFrequency({ skills, catalogs }) {
       .sort();
   }
 
-  // Uncited: catalog has an entry but zero skill cites it.
   const uncited = {};
   const catalogFieldMap = {
     cwe_refs: catalogs.cwe,
@@ -67,8 +53,8 @@ function buildFrequency({ skills, catalogs }) {
     uncited[field] = inCatalog.filter((id) => !counts[field][id]).sort();
   }
 
-  // attack_refs has no catalog file (uses MITRE upstream directly), so no
-  // uncited table for it — only counts.
+  // attack_refs is absent from catalogFieldMap: it has no catalog file of its
+  // own, so it gets counts but no uncited table.
 
   const topCited = {};
   for (const f of fields) topCited[f] = topN(f);

package/scripts/builders/jurisdiction-clocks.js

@@ -2,31 +2,12 @@
 /**
  * scripts/builders/jurisdiction-clocks.js
  *
- * Builds `data/_indexes/jurisdiction-clocks.json` — the normalized
- * jurisdiction × obligation × clock matrix. Today consumers asking
- * "what's the breach-notification clock in jurisdiction X?" have to
- * scan `data/global-frameworks.json` and pull `notification_sla` off
- * specific framework entries. This index flattens the dimension.
- *
- * Obligation types covered:
- *   - breach_notification (hours from awareness)
- *   - patch_sla            (hours from disclosure for Critical/High)
- *   - incident_reporting   (regulator + clock + trigger)
- *
- * Per-jurisdiction shape:
- *   {
- *     jurisdiction_name:
- *     frameworks: {
- *       <fwName>: {
- *         authority,
- *         breach_notification: { hours, trigger, stages?, source }
- *         patch_sla: { hours, note?, source }
- *         incident_reporting: { hours, trigger, source }
- *       }
- *     }
- *     fastest_breach_notification: { hours, framework }   // null when none specified
- *     fastest_patch_sla:           { hours, framework }
- *   }
+ * Builds `data/_indexes/jurisdiction-clocks.json` — the normalized jurisdiction
+ * × obligation × clock matrix, so a consumer asking "what is the breach-
+ * notification clock in jurisdiction X?" need not scan
+ * `data/global-frameworks.json` for `notification_sla` on each framework entry.
+ * All times are in hours; a `fastest_*` slot is null when no framework in the
+ * jurisdiction specifies that clock.
  */
 
 function buildJurisdictionClocks({ globalFrameworks }) {

package/scripts/builders/recipes.js

@@ -1,16 +1,9 @@
 "use strict";
 /**
- * scripts/builders/recipes.js
- *
- * Builds `data/_indexes/recipes.json` — curated skill sequences for the
- * most common operator use cases. Each recipe is a vetted chain of skills
- * to invoke, in order, with a brief rationale per step. Saves the
- * researcher skill from re-deriving these on every request.
- *
- * Recipes are content (not derived), so this builder is mostly a
- * declarative table. The build step validates that every referenced
- * skill exists in the manifest, so a renamed/deleted skill surfaces as a
- * build error.
+ * Builds `data/_indexes/recipes.json` — curated skill chains for the common
+ * operator cases, so the researcher skill does not re-derive them per request.
+ * The table below is content, not derived; the build validates every referenced
+ * skill against the manifest, so a rename or deletion fails the build.
  */
 
 const RECIPES = [
@@ -138,9 +131,8 @@ function buildRecipes({ skills }) {
     throw new Error("recipes.js: " + errors.join("; "));
   }
 
-  // Add token-budget hints once we have them — token-budget builder may run
-  // after this one, so we just emit the per-step list and let consumers
-  // join to token-budget.json. The skill_count is cheap to include here.
+  // No token-budget hints here: that builder may run after this one, so
+  // consumers join to token-budget.json themselves.
   const out = {
     _meta: {
       schema_version: "1.0.0",

package/scripts/builders/section-offsets.js

@@ -1,42 +1,14 @@
 "use strict";
 /**
- * scripts/builders/section-offsets.js
- *
- * Builds `data/_indexes/section-offsets.json` — for each skill, the byte
- * + line offsets of every H2 section header in the body. AI consumers can
- * slice a single section (e.g. "Compliance Theater Check") from disk
- * without parsing the full skill file.
- *
- * Per-skill shape:
- *   {
- *     path:           "skills/<name>/skill.md",
- *     total_bytes:    n,
- *     total_lines:    n,
- *     frontmatter:    { byte_start, byte_end, line_start, line_end },
- *     sections: [
- *       {
- *         name:            raw H2 text (e.g. "Threat Context (mid-2026)")
- *         normalized_name: collapsed for lookup ("threat-context")
- *         line:            1-based line number of the "## …" header
- *         byte_start:      byte offset of the "## " character
- *         byte_end:        byte offset where the next H2 begins (or EOF)
- *         bytes:           byte_end - byte_start
- *         h3_count:        number of "### " headers contained
- *       },
- *       ...
- *     ]
- *   }
- *
- * The normalized_name strips parenthetical qualifiers and common phrasings
- * so consumers can request a canonical section name without caring about
- * formatting drift.
+ * Builds `data/_indexes/section-offsets.json`: per skill, the byte and line
+ * offsets of every H2 section in the body, so a consumer can slice one section
+ * off disk without parsing the whole file. normalized_name collapses
+ * parenthetical qualifiers and phrasing variants onto a canonical name.
  */
 
 const fs = require("fs");
 const path = require("path");
 
-// Recognized canonical section anchors. Multiple raw H2 phrasings map to one
-// normalized name — see grep survey of skills/* for the variant phrasings.
 const NORMALIZERS = [
   [/threat\s*context/i,                     "threat-context"],
   [/framework\s*lag\s*declaration/i,        "framework-lag-declaration"],
@@ -56,7 +28,6 @@ function normalize(headerText) {
   for (const [re, canonical] of NORMALIZERS) {
     if (re.test(stripped)) return canonical;
   }
-  // Fall back: slug.
   return stripped
     .toLowerCase()
     .replace(/[^a-z0-9]+/g, "-")
@@ -68,14 +39,10 @@ function buildOne(absPath, relPath) {
   const totalBytes = buf.length;
   const text = buf.toString("utf8");
   const lines = text.split(/\r?\n/);
-  // EOL-aware line-start byte offsets: walk the actual terminator bytes off the
-  // decoded text rather than assuming a fixed 1-byte newline. On a pure-LF body
-  // every terminator is 1 byte so the offsets are identical to the old `+ 1`
-  // accumulator; on a stray CRLF body the \r\n terminator is 2 bytes and the
-  // offsets stay correct (the old fixed-constant approach undercounted by 1
-  // byte per line and silently misaligned every token-budget slice). The split
-  // above discards terminator bytes, so the width can only be recovered by
-  // reading the terminators off the raw text — done here.
+  // Line-start byte offsets are measured off the real terminator bytes: a CRLF
+  // terminator is 2 bytes, and assuming a fixed 1-byte newline misaligns every
+  // offset in a CRLF body. The split above discards the terminators, so their
+  // width can only be recovered from the raw text.
   const lineByteOffsets = [0];
   const eolRe = /\r?\n/g;
   let m;
@@ -103,9 +70,8 @@ function buildOne(absPath, relPath) {
       }
     : null;
 
-  // H2 headers — only those outside fenced code blocks. Skill bodies often
-  // contain "## Foo" lines inside ```...``` blocks as output templates; those
-  // are not real sections.
+  // H2 headers outside fenced code blocks only — skill bodies carry "## Foo"
+  // lines inside ```...``` blocks as output templates, which are not sections.
   const h2 = [];
   let inFence = false;
   for (let i = 0; i < lines.length; i++) {
@@ -124,10 +90,8 @@ function buildOne(absPath, relPath) {
     const next = h2[j + 1];
     const startByte = lineByteOffsets[cur.idx];
     const endByte = next ? lineByteOffsets[next.idx] : totalBytes;
-    // Count H3 within this section — fence-aware, the same way the H2 loop
-    // above is. A section starts and ends on an H2 header, both of which are
-    // outside any fence, so fence state always begins false here. "### Foo"
-    // lines inside ```...``` output templates are not real sub-sections.
+    // Fence-aware like the H2 loop: a section starts and ends on an H2, both
+    // outside any fence, so fence state always begins false here.
     const endIdx = next ? next.idx : lines.length;
     let h3Count = 0;
     let h3InFence = false;
@@ -173,7 +137,5 @@ function buildSectionOffsets({ root, skills }) {
   };
 }
 
-// buildOne is exported for regression testing of the EOL-aware byte offsets
-// (a CRLF body must still produce byte_start values that point at the real
-// "## " byte in the raw file).
+// buildOne is exported for the CRLF byte-offset regression test.
 module.exports = { buildSectionOffsets, buildOne };

package/scripts/builders/stale-content.js

@@ -1,24 +1,9 @@
 "use strict";
 /**
- * scripts/builders/stale-content.js
- *
- * Builds `data/_indexes/stale-content.json` — surfaces stale or
- * drifted references the audit-cross-skill script catches at run time,
- * persisted as a JSON artifact so CI / dashboards / downstream tools can
- * read the same view without invoking the script.
- *
- * Checks performed here (subset of audit-cross-skill that's relevant to
- * the index layer, deterministic across reruns):
- *
- *   - Skill bodies referencing renamed-skill tokens (e.g. age-gates-minor-*)
- *   - README badge counts vs. live counts
- *   - "Researcher routes to N skills" claim vs. live count
- *   - Skills with last_threat_review older than 180 days from
- *     manifest.threat_review_date (gives a stale-content snapshot)
- *   - Catalog _meta.last_verified entries older than freshness_policy.stale_after_days
- *   - Forward_watch items mentioning dates that have already passed
- *
- * Each finding is { severity, category, artifact, detail }.
+ * Builds `data/_indexes/stale-content.json` — the subset of the
+ * audit-cross-skill checks that is deterministic across reruns, persisted so CI
+ * and downstream tools read the same view without invoking that script. Each
+ * finding is { severity, category, artifact, detail }.
  */
 
 const fs = require("fs");
@@ -45,7 +30,6 @@ function buildStaleContent({ root, manifest, skills, catalogFiles }) {
   const findings = [];
   const refDate = new Date((manifest.threat_review_date || "2026-05-01") + "T00:00:00Z");
 
-  // 1. Stale-renamed-skill tokens
   for (const s of skills) {
     const body = fs.readFileSync(path.join(root, s.path), "utf8");
     for (const tok of RENAMED_SKILL_TOKENS) {
@@ -62,7 +46,6 @@ function buildStaleContent({ root, manifest, skills, catalogFiles }) {
     }
   }
 
-  // 2. README badge counts vs. live counts
   const readmePath = path.join(root, "README.md");
   if (fs.existsSync(readmePath)) {
     const readme = fs.readFileSync(readmePath, "utf8");
@@ -71,10 +54,9 @@ function buildStaleContent({ root, manifest, skills, catalogFiles }) {
     const liveJurisdictions = (() => {
       try {
         const gf = JSON.parse(fs.readFileSync(path.join(root, "data/global-frameworks.json"), "utf8"));
-        // Count non-underscore keys (GLOBAL included) — the canonical
-        // jurisdiction count used by the README badge and catalog-summaries.
-        // Excluding GLOBAL here uniquely produced 34 and emitted a false
-        // badge_drift finding against the README's (correct) 35.
+        // Non-underscore keys, GLOBAL INCLUDED — the canonical jurisdiction
+        // count the README badge and catalog-summaries use. Excluding GLOBAL
+        // undercounts by one and emits a false badge_drift.
         return Object.keys(gf).filter((k) => !k.startsWith("_")).length;
       } catch {
         return null;
@@ -98,7 +80,6 @@ function buildStaleContent({ root, manifest, skills, catalogFiles }) {
     }
   }
 
-  // 3. Researcher dispatch count claim
   const researcherPath = path.join(root, "skills/researcher/skill.md");
   if (fs.existsSync(researcherPath)) {
     const r = fs.readFileSync(researcherPath, "utf8");
@@ -117,7 +98,6 @@ function buildStaleContent({ root, manifest, skills, catalogFiles }) {
     }
   }
 
-  // 4. Skills with > 180 days since review (against reference date)
   for (const s of skills) {
     if (!s.last_threat_review) continue;
     const ageDays = Math.floor(
@@ -133,7 +113,6 @@ function buildStaleContent({ root, manifest, skills, catalogFiles }) {
     }
   }
 
-  // 5. Catalog last_verified entries older than freshness_policy.stale_after_days
   for (const rel of catalogFiles) {
     const abs = path.join(root, rel);
     try {

package/scripts/builders/summary-cards.js

@@ -1,24 +1,8 @@
 "use strict";
 /**
- * scripts/builders/summary-cards.js
- *
- * Builds `data/_indexes/summary-cards.json` — for each skill, a compact
- * abstract that downstream AI consumers (researcher dispatch in particular)
- * can render without loading the full skill body.
- *
- * Card shape per skill:
- *   {
- *     description:           manifest description
- *     threat_context_excerpt: first paragraph of Threat Context section
- *     produces:               first paragraph of Output Format section (if present)
- *     key_xrefs: {
- *       cwe_refs, d3fend_refs, framework_gaps, atlas_refs,
- *       attack_refs, rfc_refs, dlp_refs
- *     }
- *     trigger_count, atlas_count, attack_count, framework_gap_count,
- *     last_threat_review, path,
- *     handoff_targets: skills referenced from this skill's Hand-Off section
- *   }
+ * Builds `data/_indexes/summary-cards.json`: a compact per-skill abstract that
+ * downstream AI consumers — researcher dispatch in particular — render without
+ * loading the full skill body.
  */
 
 const fs = require("fs");
@@ -47,14 +31,11 @@ function locateHeader(lines, headerRegex) {
 }
 
 function firstParagraphAfterHeader(body, headerRegex) {
-  // Locate the first real H2 matching the regex, then find the first prose
-  // paragraph beneath it — skip any H3 / H4 / bold-prefix metadata lines /
-  // horizontal rules / table separators that often sit at the top of a
-  // section. Real H2 means outside of fenced code blocks.
+  // The first prose paragraph beneath the matching H2, skipping the H3/H4,
+  // bold-prefix metadata, rules and table separators that often lead a section.
   const lines = body.split(/\r?\n/);
   const hdrIdx = locateHeader(lines, headerRegex);
   if (hdrIdx < 0) return null;
-  // Find the next real H2 as the section boundary.
   const allH2 = findRealH2Indices(lines);
   const nextH2 = allH2.find((i) => i > hdrIdx);
   const sectionEnd = nextH2 != null ? nextH2 : lines.length;
@@ -106,11 +87,9 @@ function firstChunkAfterHeader(body, headerRegex, maxChars = 600) {
 }
 
 function handoffTargets(body, allSkillNames, selfName) {
-  // Look ONLY in the Hand-Off section; backtick-quoted skill names count as a
-  // target. Bound the scan to [Hand-Off header, next real H2) so unrelated
-  // later sections are not mis-attributed as hand-off targets. Header
-  // detection and the section boundary are both fence-aware (a `## ` line
-  // inside a ```...``` block is not a real H2).
+  // Only the Hand-Off section counts, and a backtick-quoted skill name is a
+  // target. The scan is bounded to [header, next real H2) so a later section is
+  // not mis-attributed, and both bounds are fence-aware.
   const lines = body.split(/\r?\n/);
   const h2 = findRealH2Indices(lines);
   const handoffIdx = h2.find((i) => /^## Hand-?Off/.test(lines[i]));

package/scripts/builders/theater-fingerprints.js

@@ -1,28 +1,16 @@
 "use strict";
 /**
- * scripts/builders/theater-fingerprints.js
- *
- * Builds `data/_indexes/theater-fingerprints.json` — for each Compliance
- * Theater pattern in the `compliance-theater` skill, a structured record:
- *   - the claim (what auditors hear)
- *   - the audit evidence (what passes the audit)
- *   - the reality (why it's theater)
- *   - the detection test (operational steps)
- *   - the controls it spans (NIST 800-53 / ISO 27001 / PCI / SOC 2)
- *   - the evidence CVE / campaign tying the pattern to the real world
- *
- * Extracted from `skills/compliance-theater/skill.md`. The compliance-theater
- * skill is the source-of-truth — this index just structures the pattern
- * library so downstream consumers (audit defense, framework-gap-analysis)
- * can join on control IDs without re-parsing the markdown.
+ * Builds `data/_indexes/theater-fingerprints.json` from
+ * `skills/compliance-theater/skill.md`, which stays the source of truth — the
+ * index only structures the pattern library so consumers can join on control
+ * IDs without re-parsing the markdown.
  */
 
 const fs = require("fs");
 const path = require("path");
 
-// Stable mapping of each Pattern → the controls it spans. Manually curated
-// from the skill's Framework Lag Declaration table — keep this in lockstep
-// with skills/compliance-theater/skill.md.
+// Each pattern → the controls it spans, hand-curated from the skill's Framework
+// Lag Declaration table; keep in lockstep with that table.
 const PATTERN_CONTROL_MAP = {
   1: {
     pattern_name: "Patch Management Theater",
@@ -117,10 +105,9 @@ const PATTERN_CONTROL_MAP = {
 };
 
 function extractPatternBodyFromSkill(skillBody, patternNumber) {
-  // Find "### Pattern N:" and capture until the next "### Pattern N+1:" OR
-  // the next ## H2 after the header line itself. We skip the header's own
-  // line before scanning for an H2 boundary — otherwise the `### Pattern N:`
-  // line would match the `## ` prefix regex once its leading `#` is sliced.
+  // Captures from "### Pattern N:" to the next "### Pattern N+1:" or the next
+  // H2. The H2 scan starts past the header line: `### Pattern N:` itself
+  // matches the `^## ` prefix once its leading `#` is sliced off.
   const startRe = new RegExp(`^### Pattern ${patternNumber}:`, "m");
   const startMatch = skillBody.match(startRe);
   if (!startMatch) return null;
@@ -142,8 +129,7 @@ function extractPatternBodyFromSkill(skillBody, patternNumber) {
 }
 
 function pullField(body, label) {
-  // The patterns use a "**Label:** ..." prose convention. Return the line(s)
-  // after the label until the next "**" or blank line.
+  // Patterns write fields as "**Label:** ..."; capture to the next "**" or blank line.
   const re = new RegExp(`\\*\\*${label.replace(/[-/\\^$*+?.()|[\\]{}]/g, "\\$&")}:?\\*\\*\\s*([\\s\\S]*?)(?=\\n\\n|\\n\\*\\*|$)`);
   const m = body.match(re);
   return m ? m[1].trim() : null;
@@ -173,9 +159,8 @@ function buildTheaterFingerprints({ root }) {
     };
   }
 
-  // Inverted index: control_id → pattern(s) it spans, so a consumer can ask
-  // "is this control implicated in a theater pattern?" without scanning all
-  // seven patterns.
+  // Inverted index, framework::control_id → patterns, so a consumer can ask
+  // whether a control is implicated without scanning every pattern.
   const byControl = {};
   for (const [pid, p] of Object.entries(out)) {
     for (const c of p.controls) {

package/scripts/builders/token-budget.js

@@ -1,36 +1,9 @@
 "use strict";
 /**
- * scripts/builders/token-budget.js
- *
- * Builds `data/_indexes/token-budget.json` — per-skill approximate token
- * counts using a character-density heuristic. Zero-dep (no tiktoken). The
- * approximation is documented as such so consumers know to recompute with
- * their own tokenizer if precision matters.
- *
- * Heuristic: 1 token ≈ 4 characters for English prose mixed with technical
- * tokens (matches the well-known OpenAI rule-of-thumb). This is an upper
- * bound for Claude (Anthropic's tokenizer is more efficient on common
- * prose) but is good enough for context-budget planning where consumers
- * just need to know "is this load 5K or 50K tokens".
- *
- * Per-skill shape:
- *   {
- *     path:                 skill file path
- *     bytes:                total file bytes
- *     chars:                total character count
- *     lines:                line count
- *     approx_tokens:        chars / 4 (integer)
- *     approx_chars_per_token: 4
- *     sections: {
- *       <normalized_section_name>: { bytes, approx_tokens }
- *     }
- *   }
- *
- * Corpus totals live under the top-level `_meta` block:
- *   {
- *     schema_version, tokenizer_note, approx_chars_per_token,
- *     total_chars, total_approx_tokens, skill_count
- *   }
+ * Builds `data/_indexes/token-budget.json`: per-skill token counts from a
+ * 1-token ≈ 4-characters density heuristic, with no tokenizer dependency. The
+ * result is an upper bound for context-budget planning, never a precise count —
+ * the caveat travels with the data in `_meta.tokenizer_note`.
  */
 
 const fs = require("fs");

package/scripts/check-agents-md-collectors.js

@@ -2,24 +2,9 @@
 "use strict";
 
 /**
- * scripts/check-agents-md-collectors.js
- *
- * Predeploy gate. Verifies that AGENTS.md's "<N> reference collectors
- * ship today" paragraph stays in sync with the actual contents of
- * lib/collectors/. Drift is silent today - AGENTS.md gets bumped by
- * hand each release; a missed bump produces inaccurate count + stale
- * enumeration that downstream AI consumers parse.
- *
- * Checks:
- *   1. The numeric count word in the paragraph (Eleven / Twelve /
- *      Thirteen / ...) matches the actual count of
- *      lib/collectors/*.js modules.
- *   2. Every collector named in the parenthesized list exists at
- *      lib/collectors/<name>.js.
- *   3. Every lib/collectors/<name>.js module appears in the
- *      parenthesized list.
- *
- * Exit codes: 0 ok, 1 drift, 2 parse error.
+ * Predeploy gate: AGENTS.md's "<N> reference collectors ship today" paragraph
+ * must agree with lib/collectors/ — the count word and the enumeration, both
+ * directions. Exit codes: 0 ok, 1 drift, 2 parse error.
  */
 
 const fs = require("node:fs");
@@ -28,31 +13,20 @@ const path = require("node:path");
 const ROOT = path.join(__dirname, "..");
 const AGENTS = path.join(ROOT, "AGENTS.md");
 const REAL_COLLECTOR_DIR = path.join(ROOT, "lib", "collectors");
-// EXCEPTD_COLLECTOR_DIR lets the test suite drive the gate against a throwaway
-// tempdir (so the require-throw / leaked-fixture behaviours are exercised
-// without writing into the real lib/collectors/). It is honored ONLY when the
-// explicit test-only switch EXCEPTD_COLLECTOR_DIR_TESTONLY=1 is also set, so a
-// stray env var in CI or a developer shell can never point the release gate at
-// an alternate directory and let missing/broken real collectors pass.
+// EXCEPTD_COLLECTOR_DIR is honored ONLY alongside EXCEPTD_COLLECTOR_DIR_TESTONLY=1,
+// so a stray env var cannot aim the release gate at another directory.
 const COLLECTOR_DIR =
   process.env.EXCEPTD_COLLECTOR_DIR_TESTONLY === "1" && process.env.EXCEPTD_COLLECTOR_DIR
     ? path.resolve(process.env.EXCEPTD_COLLECTOR_DIR)
     : REAL_COLLECTOR_DIR;
 
-// A real shipped collector is named [a-z0-9-]+.js — the AGENTS.md enumeration
-// regex (`lib/collectors/([a-z0-9-]+\.js)`) cannot even reference an
-// underscore-prefixed file. So a `__`-prefixed file is never a collector:
-// it is test scaffolding or a stray artifact. classifyCollectors SKIPS it so a
-// leaked fixture cannot poison the count/enumeration/load-error scan; the gate
-// separately FORBIDS it (see findReservedFixtures) so a leaked fixture cannot
-// silently ship in the wholesale-published lib/ tree either.
+// A shipped collector is named [a-z0-9-]+.js, so a `__`-prefixed file is test
+// scaffolding: classifyCollectors skips it, findReservedFixtures forbids it in lib/.
 function isReservedFixture(f) {
   return f.startsWith("__");
 }
 
-// Reserved-prefix .js files present in `dir`. These are test scaffolding and
-// must never ship; the gate fails hard if any are found in the directory it
-// validates.
+// Reserved-prefix .js files present in `dir`; an unreadable dir yields [].
 function findReservedFixtures(dir) {
   try {
     return fs.readdirSync(dir).filter((f) => f.endsWith(".js") && isReservedFixture(f));
@@ -61,10 +35,8 @@ function findReservedFixtures(dir) {
   }
 }
 
-// Classify every <dir>/*.js into collectors (require succeeds + exports
-// collect()), helpers (require succeeds, no collect() — silently excluded),
-// and load-errors (require throws — surfaced, never silently dropped).
-// Exported so the test suite can drive it against a tempdir.
+// Classify every <dir>/*.js: a collector requires cleanly and exports collect();
+// a require that throws becomes a load error rather than a silent omission.
 function classifyCollectors(dir) {
   const jsFiles = fs.readdirSync(dir)
     .filter((f) => f.endsWith(".js") && !isReservedFixture(f))
@@ -104,10 +76,7 @@ function ok(msg) {
 }
 
 function main() {
-  // Leak-guard (P2: forbid leaked reserved fixtures before packing). A
-  // `__`-prefixed file in the collectors dir is stray test scaffolding;
-  // because lib/ is published wholesale, a leaked one would otherwise ship.
-  // Fail hard, naming the file, so the release path deletes it.
+  // lib/ is published wholesale, so a stray fixture would ship.
   const stray = findReservedFixtures(COLLECTOR_DIR);
   if (stray.length > 0) {
     console.error(
@@ -126,18 +95,6 @@ function main() {
     return;
   }
 
-  // Classify every lib/collectors/*.js into exactly one of three buckets:
-  //   - collector:  require() succeeds AND exports a collect() function
-  //                 (counted; must appear in the AGENTS.md enumeration).
-  //   - helper:     require() succeeds but exports no collect() function
-  //                 (e.g. scan-excludes.js, the directory-walk exclusion
-  //                 policy) — legitimately excluded from the count.
-  //   - load-error: require() THROWS (syntax error, bad top-level require,
-  //                 init-time exception). A broken collector must NOT be
-  //                 silently dropped: doing so excludes it from BOTH the
-  //                 count and the enumeration cross-check, so a file that
-  //                 still ships in the tarball passes the gate undetected.
-  //                 Surface it as a parse error (exit 2) naming the file.
   let collectorFiles, loadErrors;
   try {
     ({ collectorFiles, loadErrors } = classifyCollectors(COLLECTOR_DIR));