@blamejs/exceptd-skills 0.9.1

package/scripts/builders/summary-cards.js

@@ -0,0 +1,166 @@
+"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
+ *   }
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+// Walk a body and yield real H2 lines (outside fenced code blocks).
+function findRealH2Indices(lines) {
+  const out = [];
+  let inFence = false;
+  for (let i = 0; i < lines.length; i++) {
+    if (/^```/.test(lines[i])) {
+      inFence = !inFence;
+      continue;
+    }
+    if (!inFence && /^## /.test(lines[i])) out.push(i);
+  }
+  return out;
+}
+
+function locateHeader(lines, headerRegex) {
+  const h2 = findRealH2Indices(lines);
+  for (const idx of h2) {
+    if (headerRegex.test(lines[idx])) return idx;
+  }
+  return -1;
+}
+
+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.
+  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;
+
+  let i = hdrIdx + 1;
+  const isSkippableLeading = (line) => {
+    const t = line.trim();
+    if (t === "") return true;
+    if (t === "---") return true;
+    if (/^#{1,6}\s/.test(t)) return true;
+    if (/^\|/.test(t)) return true;
+    if (/^\*\*[^*]+:\*\*/.test(t)) return true;
+    if (/^[-=]{3,}$/.test(t)) return true;
+    return false;
+  };
+  for (; i < sectionEnd; i++) {
+    if (!isSkippableLeading(lines[i])) break;
+  }
+  if (i >= sectionEnd) return null;
+
+  const para = [];
+  for (; i < sectionEnd; i++) {
+    if (lines[i].trim() === "" && para.length) break;
+    para.push(lines[i]);
+  }
+  const joined = para.join(" ").replace(/\s+/g, " ").trim();
+  if (!joined) return null;
+  if (joined.length <= 600) return joined;
+  const cut = joined.slice(0, 600);
+  const lastSpace = cut.lastIndexOf(" ");
+  return (lastSpace > 400 ? cut.slice(0, lastSpace) : cut) + " ...";
+}
+
+function firstChunkAfterHeader(body, headerRegex, maxChars = 600) {
+  const lines = body.split(/\r?\n/);
+  const hdrIdx = locateHeader(lines, headerRegex);
+  if (hdrIdx < 0) return null;
+  const allH2 = findRealH2Indices(lines);
+  const nextH2 = allH2.find((i) => i > hdrIdx);
+  const sectionEnd = nextH2 != null ? nextH2 : lines.length;
+
+  let i = hdrIdx + 1;
+  while (i < sectionEnd && lines[i].trim() === "") i++;
+  const chunk = lines.slice(i, sectionEnd);
+  const joined = chunk.join("\n").trim();
+  if (!joined) return null;
+  if (joined.length <= maxChars) return joined;
+  return joined.slice(0, maxChars) + " ...";
+}
+
+function handoffTargets(body, allSkillNames, selfName) {
+  // Look in the Hand-Off section; backtick-quoted skill names count as a target.
+  const handoffStart = body.search(/^## Hand-?Off/m);
+  if (handoffStart < 0) return [];
+  const slice = body.slice(handoffStart);
+  const targets = new Set();
+  for (const name of allSkillNames) {
+    if (name === selfName) continue;
+    if (slice.includes("`" + name + "`")) targets.add(name);
+  }
+  return [...targets].sort();
+}
+
+function buildSummaryCards({ root, manifest, skills }) {
+  const cards = {};
+  const allNames = new Set(skills.map((s) => s.name));
+
+  for (const s of skills) {
+    const body = fs.readFileSync(path.join(root, s.path), "utf8");
+
+    const threatCtx = firstParagraphAfterHeader(body, /^## Threat Context/);
+    const produces = firstChunkAfterHeader(body, /^## Output Format/, 600);
+
+    cards[s.name] = {
+      description: s.description || null,
+      threat_context_excerpt: threatCtx,
+      produces: produces,
+      key_xrefs: {
+        cwe_refs: s.cwe_refs || [],
+        d3fend_refs: s.d3fend_refs || [],
+        framework_gaps: s.framework_gaps || [],
+        atlas_refs: s.atlas_refs || [],
+        attack_refs: s.attack_refs || [],
+        rfc_refs: s.rfc_refs || [],
+        dlp_refs: s.dlp_refs || [],
+      },
+      trigger_count: (s.triggers || []).length,
+      atlas_count: (s.atlas_refs || []).length,
+      attack_count: (s.attack_refs || []).length,
+      framework_gap_count: (s.framework_gaps || []).length,
+      cwe_count: (s.cwe_refs || []).length,
+      d3fend_count: (s.d3fend_refs || []).length,
+      rfc_count: (s.rfc_refs || []).length,
+      last_threat_review: s.last_threat_review || null,
+      path: s.path,
+      handoff_targets: handoffTargets(body, allNames, s.name),
+    };
+  }
+
+  return {
+    _meta: {
+      schema_version: "1.0.0",
+      note: "Compact per-skill abstract for researcher dispatch and AI consumer planning. See scripts/builders/summary-cards.js.",
+    },
+    skills: cards,
+  };
+}
+
+module.exports = { buildSummaryCards };

package/scripts/builders/theater-fingerprints.js

@@ -0,0 +1,198 @@
+"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.
+ */
+
+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.
+const PATTERN_CONTROL_MAP = {
+  1: {
+    pattern_name: "Patch Management Theater",
+    primary_attack_class: "patch-cycle vs. KEV-listed instant-root exploits",
+    controls: [
+      { framework: "NIST 800-53", control_id: "SI-2", note: "30-day critical patch SLA designed for slow-weaponization era" },
+      { framework: "ISO 27001:2022", control_id: "A.8.8", note: "'Appropriate timescales' undefined; commonly read as 30 days for High" },
+      { framework: "PCI DSS 4.0", control_id: "6.3.3", note: "One-month critical-patch window" },
+      { framework: "NIS2", control_id: "Art. 21", note: "No specific patching SLA" },
+      { framework: "CIS Controls v8", control_id: "Control 7", note: "Continuous vulnerability management; 'within one month' still too long" },
+    ],
+    evidence: { cve: "CVE-2026-31431", rationale: "Copy Fail: deterministic 732-byte root, CISA KEV, AI-discovered, public PoC" },
+    ttps: ["T1068", "T1203"],
+    fast_test: "Pull last 12 months of patch records. Any CISA KEV patched > 72 hours after KEV listing = THEATER FLAG.",
+  },
+  2: {
+    pattern_name: "Network Segmentation Theater (IPsec)",
+    primary_attack_class: "IPsec subsystem as both control and attack surface",
+    controls: [
+      { framework: "NIST 800-53", control_id: "SC-8", note: "Transmission confidentiality — IPsec common compensating control" },
+      { framework: "NIST 800-53", control_id: "SC-7", note: "Boundary protection — IPsec tunnel as zone separator" },
+      { framework: "PCI DSS 4.0", control_id: "Req 1", note: "Network segmentation between trust zones" },
+    ],
+    evidence: { cve: "CVE-2026-43284", rationale: "Dirty Frag: kernel IPsec subsystem LPE — the control's cryptographic mechanism is the attack surface" },
+    ttps: ["T1190"],
+    fast_test: "Identify hosts using IPsec for segmentation compliance. If kernel patch for CVE-2026-43284 not applied = THEATER FLAG.",
+  },
+  3: {
+    pattern_name: "Access Control Theater (AI Agent)",
+    primary_attack_class: "prompt injection bypasses access control via authorized service account",
+    controls: [
+      { framework: "SOC 2", control_id: "CC6", note: "Logical access — designed for human-controlled accounts" },
+      { framework: "NIST 800-53", control_id: "AC-2", note: "Account management — no concept of AI agent authority delegation" },
+      { framework: "NIST 800-53", control_id: "AC-3", note: "Access enforcement — model judgment is the gate, not a recognized control" },
+      { framework: "ISO 27001:2022", control_id: "A.5.15", note: "Access control policy" },
+    ],
+    evidence: { cve: "CVE-2025-53773", rationale: "Copilot prompt-injection RCE: AI service account executes attacker-chosen actions; no identity boundary crossed" },
+    ttps: ["AML.T0051", "AML.T0054", "T1059"],
+    fast_test: "If AI agents have prod access and (a) prompt content + tool calls aren't logged or (b) no behavioral baseline = THEATER FLAG.",
+  },
+  4: {
+    pattern_name: "Incident Response Theater (AI Pipeline)",
+    primary_attack_class: "IR program with no detection input or procedure for AI-class incidents",
+    controls: [
+      { framework: "SOC 2", control_id: "CC7", note: "System operations / anomaly detection — no baseline for AI-API traffic" },
+      { framework: "NIST 800-53", control_id: "IR-4", note: "Incident handling — phases defined but not AI-class triggers" },
+      { framework: "ISO 27001:2022", control_id: "A.5.24-A.5.28", note: "IR planning/preparation/reporting/response/learning" },
+    ],
+    evidence: { campaign: "SesameOp", rationale: "AML.T0096 LLM Integration Abuse as C2 — no detection triggers exist, so IR procedures have no input" },
+    ttps: ["AML.T0020", "AML.T0096", "AML.T0010"],
+    fast_test: "Search IR playbooks for 'prompt injection', 'model poisoning', 'AI agent', 'LLM', 'MCP server'. Zero matches = THEATER FLAG.",
+  },
+  5: {
+    pattern_name: "Change Management Theater (AI Model)",
+    primary_attack_class: "external model updates bypass operator change control",
+    controls: [
+      { framework: "NIST 800-53", control_id: "CM-3", note: "Configuration change control — drafted for changes the operator controls" },
+      { framework: "ISO 27001:2022", control_id: "A.8.32", note: "Change management" },
+      { framework: "SOC 2", control_id: "CC8", note: "Change management" },
+    ],
+    evidence: { campaign: "Continuous provider model updates", rationale: "Vendor-managed model updates bypass operator change control entirely; safety properties can shift silently" },
+    ttps: ["AML.T0018", "AML.T0020"],
+    fast_test: "List LLM API deps. Does each provider update open a change ticket? Is there a behavioral test suite? Is the model version pinned? Any 'no' = THEATER FLAG.",
+  },
+  6: {
+    pattern_name: "Vendor/Third-Party Risk Theater (AI API + MCP)",
+    primary_attack_class: "vendor program scope excludes LLM APIs and MCP servers",
+    controls: [
+      { framework: "SOC 2", control_id: "CC9", note: "Risk mitigation; vendor management" },
+      { framework: "NIST 800-53", control_id: "SA-12", note: "Supply chain protection" },
+      { framework: "ISO 27001:2022", control_id: "A.5.19", note: "Supplier relationships — drafted for SaaS-style vendors" },
+      { framework: "ISO 27001:2022", control_id: "A.5.20", note: "Information security in supplier agreements" },
+      { framework: "US FedRAMP", control_id: "Rev 5 Moderate", note: "Authorization-as-evidence pattern; ATO does not cover tenant-side MCP" },
+      { framework: "US DoD CMMC", control_id: "2.0 Level 2", note: "Certification-as-evidence; does not cover AI coding-assistant supply chain" },
+    ],
+    evidence: { cve: "CVE-2026-30615", rationale: "Windsurf MCP zero-interaction RCE — vendor management program had no coverage of MCP servers as third-party code" },
+    ttps: ["AML.T0010"],
+    fast_test: "List LLM API providers. Is there a vendor risk assessment + DPA for each? List MCP servers on dev workstations — did each pass vendor review? Either gap = THEATER FLAG.",
+  },
+  7: {
+    pattern_name: "Security Awareness Theater (AI Phishing)",
+    primary_attack_class: "phishing simulation tests resistance to template-era phish, not AI-generated content",
+    controls: [
+      { framework: "NIST 800-53", control_id: "AT-2", note: "Security awareness training — drafted against human-template phishing" },
+      { framework: "ISO 27001:2022", control_id: "A.6.3", note: "Information security awareness, education and training" },
+      { framework: "PCI DSS 4.0", control_id: "12.6", note: "Security awareness program" },
+    ],
+    evidence: { campaign: "AI-generated phishing baseline (82.6% of phish contain AI-generated content)", rationale: "Grammar/style heuristics are no longer reliable detectors; <5% click rate on template phish is non-informative" },
+    ttps: ["T1566", "AML.T0016"],
+    fast_test: "Were any simulation emails AI-generated (not template-based) in the last 3 sims? Is MFA phishing-resistant (hardware keys / passkeys)? Either 'no' = THEATER FLAG.",
+  },
+};
+
+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.
+  const startRe = new RegExp(`^### Pattern ${patternNumber}:`, "m");
+  const startMatch = skillBody.match(startRe);
+  if (!startMatch) return null;
+  const startIdx = startMatch.index;
+  const headerEnd = skillBody.indexOf("\n", startIdx);
+  const afterHeader = headerEnd >= 0 ? headerEnd + 1 : skillBody.length;
+  const tail = skillBody.slice(startIdx);
+  const nextPatternRe = new RegExp(`^### Pattern ${patternNumber + 1}:`, "m");
+  const nextPatternMatch = tail.match(nextPatternRe);
+  const h2Re = /^## /m;
+  const afterHeaderSlice = skillBody.slice(afterHeader);
+  const h2Match = afterHeaderSlice.match(h2Re);
+  const stops = [
+    nextPatternMatch ? nextPatternMatch.index : Infinity,
+    h2Match ? (afterHeader - startIdx) + h2Match.index : Infinity,
+  ];
+  const stopAt = Math.min(...stops);
+  return tail.slice(0, Number.isFinite(stopAt) ? stopAt : tail.length).trim();
+}
+
+function pullField(body, label) {
+  // The patterns use a "**Label:** ..." prose convention. Return the line(s)
+  // after the label until 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 }) {
+  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)) {
+    const patternBody = extractPatternBodyFromSkill(body, Number(num));
+    out[`pattern-${num}`] = {
+      pattern_number: Number(num),
+      pattern_name: meta.pattern_name,
+      primary_attack_class: meta.primary_attack_class,
+      claim: pullField(patternBody || "", "The claim"),
+      audit_evidence: pullField(patternBody || "", "The audit evidence"),
+      reality: pullField(patternBody || "", "The reality"),
+      why_its_theater: pullField(patternBody || "", "Why it's theater"),
+      fast_test: meta.fast_test,
+      controls: meta.controls,
+      evidence: meta.evidence,
+      ttps: meta.ttps,
+      source_skill: "compliance-theater",
+      source_section: `### Pattern ${num}: ${meta.pattern_name}`,
+    };
+  }
+
+  // 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.
+  const byControl = {};
+  for (const [pid, p] of Object.entries(out)) {
+    for (const c of p.controls) {
+      const key = `${c.framework}::${c.control_id}`;
+      (byControl[key] = byControl[key] || []).push(pid);
+    }
+  }
+
+  return {
+    _meta: {
+      schema_version: "1.0.0",
+      source: "skills/compliance-theater/skill.md (7 documented patterns)",
+      pattern_count: Object.keys(out).length,
+    },
+    patterns: out,
+    by_control: byControl,
+  };
+}
+
+module.exports = { buildTheaterFingerprints };

package/scripts/builders/token-budget.js

@@ -0,0 +1,96 @@
+"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 }
+ *     }
+ *   }
+ *
+ * Plus a totals block:
+ *   {
+ *     total_chars, total_approx_tokens,
+ *     by_recipe: { … } — placeholder consumers can use to estimate bundles
+ *   }
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+function approxTokens(chars) {
+  return Math.round(chars / 4);
+}
+
+function buildTokenBudget({ root, skills, sectionOffsets }) {
+  const skillBudgets = {};
+  let totalChars = 0;
+  let totalApprox = 0;
+
+  for (const s of skills) {
+    const abs = path.join(root, s.path);
+    const buf = fs.readFileSync(abs);
+    const text = buf.toString("utf8");
+    const chars = text.length;
+    const tokens = approxTokens(chars);
+    totalChars += chars;
+    totalApprox += tokens;
+
+    const sectionMap = {};
+    const sectionEntry = sectionOffsets.skills?.[s.name];
+    if (sectionEntry && Array.isArray(sectionEntry.sections)) {
+      for (const sec of sectionEntry.sections) {
+        const sliceText = buf
+          .slice(sec.byte_start, sec.byte_end)
+          .toString("utf8");
+        sectionMap[sec.normalized_name] = {
+          bytes: sec.bytes,
+          chars: sliceText.length,
+          approx_tokens: approxTokens(sliceText.length),
+        };
+      }
+    }
+
+    skillBudgets[s.name] = {
+      path: s.path,
+      bytes: buf.length,
+      chars,
+      lines: text.split(/\r?\n/).length,
+      approx_tokens: tokens,
+      approx_chars_per_token: 4,
+      sections: sectionMap,
+    };
+  }
+
+  return {
+    _meta: {
+      schema_version: "1.0.0",
+      tokenizer_note: "Character-density approximation: 1 token ≈ 4 chars. This is the canonical rule-of-thumb for OpenAI tokenizers on English+technical text. Claude's tokenizer is typically more efficient on prose; treat this as an upper-bound budget for both. Consumers with stricter precision needs should re-tokenize with their own tokenizer.",
+      approx_chars_per_token: 4,
+      total_chars: totalChars,
+      total_approx_tokens: totalApprox,
+      skill_count: skills.length,
+    },
+    skills: skillBudgets,
+  };
+}
+
+module.exports = { buildTokenBudget };

package/scripts/check-manifest-snapshot.js

@@ -0,0 +1,217 @@
+"use strict";
+/**
+ * scripts/check-manifest-snapshot.js
+ *
+ * CI gate. Captures the current public skill surface (skill name +
+ * version + triggers + data_deps + atlas_refs + attack_refs +
+ * framework_gaps) from manifest.json and compares it to the committed
+ * manifest-snapshot.json baseline.
+ *
+ * The skill surface is the public contract this repo offers downstream
+ * AI assistants: skill names that downstream prompts may reference,
+ * trigger keywords that downstream skill-matchers index on, and the
+ * data files that skills rely on. Removing a skill or trigger keyword
+ * silently breaks every consumer that pinned that surface.
+ *
+ * Exit codes:
+ *   0  — no breaking changes (additive changes printed but not failing)
+ *   1  — breaking changes detected
+ *   2  — script-level error (missing baseline, IO failure, etc.)
+ *
+ * Operators see this gate in SECURITY.md / CONTRIBUTING.md as a CI
+ * promise: "removed skills, removed triggers, or removed data deps fail
+ * the build before they reach main."
+ *
+ * Usage:
+ *   node scripts/check-manifest-snapshot.js
+ *
+ * Regenerate the baseline after an intentional removal:
+ *   node scripts/refresh-manifest-snapshot.js
+ *   git add manifest-snapshot.json && git commit
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const ROOT = path.join(__dirname, "..");
+const MANIFEST_PATH = path.join(ROOT, "manifest.json");
+const SNAPSHOT_PATH = path.join(ROOT, "manifest-snapshot.json");
+
+function captureSurface(manifest) {
+  // Public surface = the set of facts downstream consumers may have
+  // pinned against. NOT included: sha256 / signature / signed_at —
+  // those change every commit and are not a public contract.
+  const skills = (manifest.skills || []).map(s => ({
+    name: s.name,
+    version: s.version || null,
+    triggers: [...(s.triggers || [])].sort(),
+    data_deps: [...(s.data_deps || [])].sort(),
+    atlas_refs: [...(s.atlas_refs || [])].sort(),
+    attack_refs: [...(s.attack_refs || [])].sort(),
+    framework_gaps: [...(s.framework_gaps || [])].sort(),
+    rfc_refs: [...(s.rfc_refs || [])].sort(),
+    cwe_refs: [...(s.cwe_refs || [])].sort(),
+    d3fend_refs: [...(s.d3fend_refs || [])].sort(),
+    dlp_refs: [...(s.dlp_refs || [])].sort(),
+  })).sort((a, b) => a.name.localeCompare(b.name));
+
+  return {
+    atlas_version: manifest.atlas_version || null,
+    skill_count: skills.length,
+    skills,
+  };
+}
+
+function diff(baseline, current) {
+  const breaking = [];
+  const additive = [];
+
+  const bSkills = new Map(baseline.skills.map(s => [s.name, s]));
+  const cSkills = new Map(current.skills.map(s => [s.name, s]));
+
+  // Removed skills are breaking.
+  for (const name of bSkills.keys()) {
+    if (!cSkills.has(name)) {
+      breaking.push(`removed skill: ${name}`);
+    }
+  }
+
+  // Added skills are additive.
+  for (const name of cSkills.keys()) {
+    if (!bSkills.has(name)) {
+      additive.push(`added skill: ${name}`);
+    }
+  }
+
+  // For each skill present in both, diff the pinned facts.
+  for (const [name, b] of bSkills) {
+    const c = cSkills.get(name);
+    if (!c) continue;
+
+    // version downgrades are breaking; bumps are additive.
+    if (b.version && c.version && b.version !== c.version) {
+      // Use a simple lexicographic compare — semver isn't enforced
+      // upstream and the manifest version field is informational. The
+      // operator should bump, not unbump.
+      if (c.version < b.version) {
+        breaking.push(`${name}: version downgraded ${b.version} -> ${c.version}`);
+      } else {
+        additive.push(`${name}: version bumped ${b.version} -> ${c.version}`);
+      }
+    }
+
+    // Removed trigger keywords break downstream skill matchers.
+    const removedTriggers = b.triggers.filter(t => !c.triggers.includes(t));
+    if (removedTriggers.length > 0) {
+      breaking.push(`${name}: removed trigger keywords: ${removedTriggers.join(", ")}`);
+    }
+    const addedTriggers = c.triggers.filter(t => !b.triggers.includes(t));
+    if (addedTriggers.length > 0) {
+      additive.push(`${name}: added trigger keywords: ${addedTriggers.join(", ")}`);
+    }
+
+    // Removed data deps break the skill at load time. Additions are fine.
+    const removedDeps = b.data_deps.filter(d => !c.data_deps.includes(d));
+    if (removedDeps.length > 0) {
+      breaking.push(`${name}: removed data deps: ${removedDeps.join(", ")}`);
+    }
+    const addedDeps = c.data_deps.filter(d => !b.data_deps.includes(d));
+    if (addedDeps.length > 0) {
+      additive.push(`${name}: added data deps: ${addedDeps.join(", ")}`);
+    }
+
+    // Removed ATLAS/ATT&CK/framework refs are surface narrowing.
+    // Per AGENTS.md rule #4 (no orphaned controls) and #12 (external
+    // data version pinning), narrowing the cited surface is a
+    // deliberate decision worth surfacing in CI. Treat as breaking;
+    // the operator can refresh the baseline alongside the intent.
+    for (const field of ["atlas_refs", "attack_refs", "framework_gaps", "rfc_refs", "cwe_refs", "d3fend_refs", "dlp_refs"]) {
+      const removed = b[field].filter(r => !c[field].includes(r));
+      if (removed.length > 0) {
+        breaking.push(`${name}: removed ${field}: ${removed.join(", ")}`);
+      }
+      const added = c[field].filter(r => !b[field].includes(r));
+      if (added.length > 0) {
+        additive.push(`${name}: added ${field}: ${added.join(", ")}`);
+      }
+    }
+  }
+
+  // ATLAS pinned-version change is breaking per AGENTS.md rule #12
+  // (never silently inherit version changes). The operator must update
+  // the baseline alongside the audit of TTP ID changes.
+  if (baseline.atlas_version && current.atlas_version &&
+      baseline.atlas_version !== current.atlas_version) {
+    breaking.push(
+      `atlas_version changed ${baseline.atlas_version} -> ${current.atlas_version} ` +
+      `(per AGENTS.md rule #12, audit TTP IDs and refresh baseline together)`
+    );
+  }
+
+  return { breaking, additive };
+}
+
+function formatDiff(result) {
+  const lines = [];
+  if (result.breaking.length === 0 && result.additive.length === 0) {
+    lines.push("[check-manifest-snapshot] surface unchanged.");
+    return lines.join("\n");
+  }
+
+  if (result.breaking.length > 0) {
+    lines.push(`[check-manifest-snapshot] ${result.breaking.length} breaking change(s):`);
+    for (const b of result.breaking) lines.push(`  ! ${b}`);
+  }
+  if (result.additive.length > 0) {
+    lines.push(`[check-manifest-snapshot] ${result.additive.length} additive change(s):`);
+    for (const a of result.additive) lines.push(`  + ${a}`);
+  }
+  return lines.join("\n");
+}
+
+module.exports = { captureSurface, diff, formatDiff };
+
+if (require.main === module) {
+  try {
+    let baseline;
+    try {
+      baseline = JSON.parse(fs.readFileSync(SNAPSHOT_PATH, "utf8"));
+    } catch (e) {
+      console.error(
+        "[check-manifest-snapshot] baseline missing or unreadable: " +
+        ((e && e.message) || String(e))
+      );
+      console.error(
+        "[check-manifest-snapshot] generate one with " +
+        "`node scripts/refresh-manifest-snapshot.js` and commit it."
+      );
+      process.exit(2);
+    }
+
+    const manifest = JSON.parse(fs.readFileSync(MANIFEST_PATH, "utf8"));
+    const current = captureSurface(manifest);
+    const result = diff(baseline, current);
+
+    console.log(formatDiff(result));
+
+    if (result.breaking.length > 0) {
+      console.error(
+        "[check-manifest-snapshot] BREAKING changes detected. If intentional, " +
+        "regenerate the baseline with `node scripts/refresh-manifest-snapshot.js` " +
+        "and commit it alongside the change."
+      );
+      process.exit(1);
+    }
+
+    if (result.additive.length > 0) {
+      console.log(
+        "[check-manifest-snapshot] additive changes only — refresh the baseline " +
+        "(`node scripts/refresh-manifest-snapshot.js`) so the new surface is tracked."
+      );
+    }
+    process.exit(0);
+  } catch (e) {
+    console.error("[check-manifest-snapshot] error: " + ((e && e.stack) || e));
+    process.exit(2);
+  }
+}