@blamejs/exceptd-skills 0.19.33 → 0.19.35

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,19 +129,20 @@ 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;
 }
 
-function buildTheaterFingerprints({ root }) {
+// `patternMap` defaults to the curated map; an explicit one lets a test drive
+// the builder with a pattern set of a different size.
+function buildTheaterFingerprints({ root, patternMap = PATTERN_CONTROL_MAP }) {
   const skillPath = path.join(root, "skills/compliance-theater/skill.md");
   const body = fs.readFileSync(skillPath, "utf8");
 
   const out = {};
-  for (const [num, meta] of Object.entries(PATTERN_CONTROL_MAP)) {
+  for (const [num, meta] of Object.entries(patternMap)) {
     const patternBody = extractPatternBodyFromSkill(body, Number(num));
     out[`pattern-${num}`] = {
       pattern_number: Number(num),
@@ -173,9 +161,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) {
@@ -184,11 +171,14 @@ function buildTheaterFingerprints({ root }) {
     }
   }
 
+  const patternCount = Object.keys(out).length;
   return {
     _meta: {
       schema_version: "1.0.0",
-      source: "skills/compliance-theater/skill.md (7 documented patterns)",
-      pattern_count: Object.keys(out).length,
+      // Counted from the built set, not written out, so adding a pattern cannot
+      // leave this prose contradicting pattern_count in the shipped index.
+      source: `skills/compliance-theater/skill.md (${patternCount} documented patterns)`,
+      pattern_count: patternCount,
     },
     patterns: out,
     by_control: byControl,

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");