@blamejs/exceptd-skills 0.12.22 → 0.12.23

package/AGENTS.md

@@ -44,7 +44,7 @@ Also read [CONTEXT.md](CONTEXT.md) for a complete orientation to the skill syste
     | New `phases.detect.indicators[].id` in a playbook     | Quoted indicator id literal in `tests/e2e-scenarios/*/expect.json` or `tests/*.test.js` |
     | New / changed `iocs` field on a CVE entry             | CVE id and the word `iocs` in the same test file                                 |
 
-    Mechanical enforcement lives in `scripts/check-test-coverage.js` and runs as the 15th gate of `npm run predeploy` (also the `Diff coverage` job in `ci.yml`). Docs (`*.md`), workflow YAML, and skill body changes are allowlisted — skill bodies are covered by the Ed25519 signature gate (Hard Rule #13), workflows surface a manual-review flag rather than a hard finding. Whitespace-only diffs are ignored.
+    Mechanical enforcement lives in `scripts/check-test-coverage.js` and runs as the 13th gate of `npm run predeploy` (also the `Diff coverage` job in `ci.yml`). Docs (`*.md`), workflow YAML, and skill body changes are allowlisted — skill bodies are covered by the Ed25519 signature gate (Hard Rule #13), workflows surface a manual-review flag rather than a hard finding. Whitespace-only diffs are ignored.
 
     The gate is blocking: a covered surface change without a covering test reference fails the predeploy run and the `Diff coverage` CI job. Never bypass with `--no-verify` or `--warn-only` — add the covering test first. This rule is additive to Hard Rule #11 (no-MVP ban): a new playbook indicator or CLI surface that ships without a regression test is the same shape of incomplete-feature ship that #11 forbids, applied to the test layer.
 
@@ -52,7 +52,7 @@ Also read [CONTEXT.md](CONTEXT.md) for a complete orientation to the skill syste
 
 ## Seven-phase playbook contract
 
-exceptd ships investigation playbooks under `data/playbooks/*.json` (schema: `lib/schemas/playbook.schema.json`; reference playbook: `data/playbooks/kernel.json`). Each playbook defines a **seven-phase** investigation that splits cleanly between exceptd (knowledge + GRC layer) and the host AI assistant (artifact collection + indicator evaluation). The host AI invokes the runner via `node lib/playbook-runner.js` today; direct CLI verbs (`exceptd plan`, `exceptd govern`, `exceptd direct`, `exceptd run`) are landing in a follow-up task. exceptd owns **govern, direct, analyze, validate, close**; the AI owns **look, detect**. Phases run strictly in order — never reorder, never skip.
+exceptd ships investigation playbooks under `data/playbooks/*.json` (schema: `lib/schemas/playbook.schema.json`; reference playbook: `data/playbooks/kernel.json`). Each playbook defines a **seven-phase** investigation that splits cleanly between exceptd (knowledge + GRC layer) and the host AI assistant (artifact collection + indicator evaluation). The host AI invokes the runner via the `exceptd brief` / `exceptd run` / `exceptd ai-run` verbs or, for in-process callers, `require('@blamejs/exceptd-skills/lib/playbook-runner.js')`. exceptd owns **govern, direct, analyze, validate, close**; the AI owns **look, detect**. Phases run strictly in order — never reorder, never skip.
 
 ### The seven phases
 
@@ -88,8 +88,8 @@ Operator asks: "is this host vulnerable to Copy Fail?" AI invokes `node lib/play
 
 ### CLI invocation
 
-- **Today:** `node lib/playbook-runner.js <path-to-playbook.json>` — current Node module entry point.
-- **Coming:** `exceptd plan`, `exceptd govern`, `exceptd direct`, `exceptd run` — direct CLI verbs land in a follow-up task and will wrap the same runner. AI assistants should prefer the named verbs once they ship; the Node module entry point remains stable as the underlying implementation.
+- **CLI verb:** `exceptd run <playbook> --evidence <file>` walks the full seven phases against operator-supplied evidence. `exceptd brief <playbook>` returns Phase 2 threat context for prep; `exceptd ai-run` is the streaming variant for AI agents. `exceptd ci` is the gate-only variant for CI pipelines (exit 8 on lock contention, 6 on tampered attestations).
+- **Library entry point:** `require('@blamejs/exceptd-skills/lib/playbook-runner.js')` exposes the same engine for in-process callers — schema reference at `lib/schemas/playbook.schema.json`.
 
 Schema reference: `lib/schemas/playbook.schema.json`. Reference playbook (read this before authoring a new one): `data/playbooks/kernel.json`.
 
@@ -133,14 +133,20 @@ Cross-cutting playbook `framework` is the natural correlation layer — many pla
 
 | Verb | What it does |
 |---|---|
-| `exceptd plan` | Default: grouped-by-scope summary of all 13 playbooks. `--scope <type>` filters. `--directives` expands directive IDs/titles per playbook. `--flat` for non-grouped. |
-| `exceptd govern <pb>` | Phase 1 — jurisdiction obligations, theater fingerprints, framework gaps, skills to preload. |
-| `exceptd direct <pb>` | Phase 2 — threat context, RWEP thresholds, skill chain, token budget. |
-| `exceptd look <pb>` | Phase 3 — typed artifact-collection spec + `preconditions` array + submission-shape hint. |
-| `exceptd run <pb>` | Phases 4-7 from agent evidence. Auto-detect cwd when no playbook positional. `--scope <type>` or `--all` for multi-playbook. `--vex <file>` to drop CycloneDX/OpenVEX `not_affected` CVEs. `--ci` for exit-code gating. `--diff-from-latest` for drift mode. `--force-stale` to override currency hard-block. |
-| `exceptd ingest` | Alias for `run`; submission JSON may carry `playbook_id` + `directive_id`. |
-| `exceptd reattest [<sid> \| --latest]` | Replay prior session, diff evidence_hash. `--latest [--playbook <id>] [--since <ISO>]` finds the most recent attestation automatically. |
-| `exceptd list-attestations` | Inventory `.exceptd/attestations/<sid>/` — every prior session, newest first. `--playbook <id>` filters. |
+| `exceptd brief --all` | Grouped-by-scope summary of all 13 playbooks. `--scope <type>` filters. `--directives` expands directive IDs/titles per playbook. `--flat` for non-grouped. Legacy alias: `exceptd plan` (deprecated, scheduled for removal in v0.13). |
+| `exceptd brief <pb>` | Phase 2 threat-context briefing — threat context, RWEP thresholds, skill chain, token budget, jurisdiction obligations. |
+| `exceptd run <pb> --evidence <file>` | Phases 5-7 (analyze + validate + close) from agent evidence. Auto-detect cwd when no playbook positional. `--vex <file>` drops CycloneDX/OpenVEX `not_affected` CVEs. `--diff-from-latest` for drift mode. `--force-stale` overrides currency hard-block. |
+| `exceptd ai-run <pb>` | Streaming variant of `run` for AI agents; emits phase-by-phase NDJSON. |
+| `exceptd run-all` | Multi-playbook batch run. `--scope <type>` filters. |
+| `exceptd ci` | Top-level CI gate for a single playbook with exit-code semantics. Preferred over `run --ci`. |
+| `exceptd discover` | Repo discovery — scans cwd and surfaces matching playbooks + collection hints. |
+| `exceptd ask <pb> <question>` | Read-only Q&A against a playbook's directives, indicators, and threat context. |
+| `exceptd attest diff <sid>` | Replay analyze against a stored evidence bundle for drift detection. `--against <other-sid>` compares two sessions. `--playbook <id>` + `--since <ISO>` accepted with `--latest`. Legacy alias: `exceptd reattest` (deprecated, scheduled for removal in v0.13). |
+| `exceptd attest verify <sid>` | Verify a persisted attestation's signature + evidence hash. |
+| `exceptd attest list` | Inventory `.exceptd/attestations/` — newest first. `--playbook <id>` filters. |
+| `exceptd attest show <sid>` | Print the attestation body. |
+| `exceptd doctor` | Health checks. `--signatures` verifies Ed25519 chains; `--cves` / `--rfcs` check catalog currency; `--fix` repairs recoverable state. |
+| `exceptd lint` | Skill format lint — frontmatter completeness, required body sections, signature presence. |
 
 All verbs support `--help` for per-verb usage. JSON output by default; `--pretty` for indented.
 

package/ARCHITECTURE.md

@@ -173,7 +173,7 @@ Tracks PoC status, weaponization stage, and AI-assist factor per CVE. Updated wh
 
 ### `data/cwe-catalog.json`
 
-51 CWE entries pinned to **CWE v4.17**. Covers the Top 25 Most Dangerous Software Weaknesses (2024 release) plus AI- and supply-chain-relevant weakness classes (prompt-injection-as-trust-boundary failure, training data integrity, dependency confusion, untrusted artifact ingestion). Each entry records root-cause description, common consequences, mitigation patterns, and the CVEs in `cve-catalog.json` that instantiate the weakness. Skills cite CWE IDs in `cwe_refs` to anchor a finding to a stable weakness taxonomy rather than to a single CVE; the CWE provides the durable root-cause lens that survives across exploit generations.
+55 CWE entries pinned to **CWE v4.17**. Covers the Top 25 Most Dangerous Software Weaknesses (2024 release) plus AI- and supply-chain-relevant weakness classes (prompt-injection-as-trust-boundary failure, training data integrity, dependency confusion, untrusted artifact ingestion). Each entry records root-cause description, common consequences, mitigation patterns, and the CVEs in `cve-catalog.json` that instantiate the weakness. Skills cite CWE IDs in `cwe_refs` to anchor a finding to a stable weakness taxonomy rather than to a single CVE; the CWE provides the durable root-cause lens that survives across exploit generations.
 
 `_meta.cwe_version` pins the version; on a CWE release, audit IDs for renames or deprecations, bump `last_threat_review` on affected skills, and update `_meta`.
 
@@ -234,7 +234,7 @@ Framework lag scoring and gap report generation.
 
 ### `scripts/check-test-coverage.js`
 
-Diff-coverage analyzer. Walks the staged/working-tree diff for the changed-surface shapes Hard Rule #15 enforces (CLI verbs, CLI flags, `module.exports` identifiers, new playbook indicator IDs, CVE `iocs` fields) and asserts that each change has a covering test reference somewhere under `tests/`. Skill bodies, docs, and workflow YAML are allowlisted. Runs as the 15th gate of `npm run predeploy` (and the `Diff coverage` job in `ci.yml`). Direct invocation: `npm run diff-coverage`.
+Diff-coverage analyzer. Walks the staged/working-tree diff for the changed-surface shapes Hard Rule #15 enforces (CLI verbs, CLI flags, `module.exports` identifiers, new playbook indicator IDs, CVE `iocs` fields) and asserts that each change has a covering test reference somewhere under `tests/`. Skill bodies, docs, and workflow YAML are allowlisted. Runs as the 13th gate of `npm run predeploy` (and the `Diff coverage` job in `ci.yml`). Direct invocation: `npm run diff-coverage`.
 
 ### `scripts/check-sbom-currency.js`
 

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## 0.12.23 — 2026-05-15
+
+**Patch: doc-vs-code reconciliation, trust-chain pin loader hardening, attest list/show replay isolation, global-first framework coverage backfill.**
+
+### Trust chain
+
+- **`loadExpectedFingerprintFirstLine` refuses UTF-16LE / UTF-16BE pin files.** Saving `keys/EXPECTED_FINGERPRINT` via PowerShell `Set-Content -Encoding UTF16LE` (or any tool emitting a UTF-16 BOM) previously caused every consumer (verify, refresh-network, verify-shipped-tarball, attest pin) to decode the file as UTF-8 mojibake; the first line never matched a live fingerprint and operators saw no signal that the encoding was wrong. The loader now detects the FF FE / FE FF byte signatures, returns null, and routes through the existing "no-pin" warn-and-continue path so the error is surfaced without bricking the gate. UTF-8 and UTF-8-with-BOM remain supported.
+- **`KEYS_ROTATED=1` override now emits a `process.emitWarning('EXCEPTD_KEYS_ROTATED_OVERRIDE', ...)`** at every site that accepts the bypass (`bin/exceptd.js` attestation pin, `lib/refresh-network.js` refresh-network swap gate). Previously the env var was a silent skip; operators who set it once for a legitimate rotation and forgot to commit the new pin had no surface signal on subsequent runs. The mismatch values are echoed in the warning so log scrapers can confirm intended rotation. `lib/verify.js` and `scripts/verify-shipped-tarball.js` already emitted warnings at this gate and are unchanged.
+
+### Engine + CLI
+
+- **`attest list` and `attest show` filter `kind: 'replay'` records out of the session attestations array.** v0.12.22 added signed `replay-<iso>.json` audit records under `.exceptd/attestations/<sid>/`, which the listing/show loops were treating as additional sessions (or duplicate attestation entries) with `evidence_hash: null` and `captured_at: null`. Records are now partitioned by parsed `kind` field — replay records appear under a new `attestation_replays[]` array on `attest show` output and are omitted entirely from `attest list`. Gating on the parsed `kind` field (not filename prefix) closes the rename-smuggle vector.
+- **`--session-id .` / `..` / all-dots refused after regex pass.** The `/^[A-Za-z0-9._-]{1,64}$/` validator accepted any string of dots, which resolved into or above the attestation root. The CLI now explicitly refuses all-dots session ids with a structured error.
+
+### Help text and exit-code surface
+
+- **`ingest`, `ai-run`, and `run-all` help blocks document `--csaf-status` and `--publisher-namespace`.** v0.12.22's `BUNDLE_FLAG_RELEVANT_VERBS` set wired the flags into all five bundle-emitting verbs but only the `run` and `ci` help blocks listed them; operators on the other three verbs had to read the source to find them.
+- **Exit-code tables completed across the help surface.** Top-level `exceptd help` for `ci` now lists 0/1/2/3/4/5/6/8 instead of 0/2/3/4/5/1. Per-verb tables for `ci`, `attest verify`, and `reattest` now document `6 — TAMPERED` and `8 — LOCK_CONTENTION` where applicable. `run --help` adds a `6-7 — reserved` line so the gap doesn't read as accidental.
+
+### Hard Rule #5 — global-first coverage
+
+- **Eleven playbooks backfilled with UK CAF + AU Essential 8 / ACSC / ISM clauses** in `phases.direct.framework_lag_declaration` (`secrets`, `ai-api`, `containers`, `cred-stores`, `crypto`, `kernel`, `mcp`, `runtime`, `sbom` — both CAF and E8 added; `crypto-codebase` — E8 added on top of existing CAF; `hardening` — CAF added on top of existing E8). The v0.12.21 entry claimed this coverage was already in place; only `framework.json` and `library-author.json` actually had it. All 13 playbooks now declare CAF + E8 framework-lag posture alongside NIST and ISO.
+
+### Operator-facing docs
+
+- **README, AGENTS.md, ARCHITECTURE.md, and CONTEXT.md reconciled with the v0.11+ canonical CLI surface.** The deprecation banner heading on legacy v0.10.x verbs now states "scheduled for removal in v0.13" (not "removed in v0.12" — the verbs remain registered with deprecation warnings). README body examples replace `exceptd verify` / `exceptd scan` / `validate-cves` / `validate-rfcs` with `exceptd doctor --signatures` / `exceptd discover` / `doctor --cves` / `doctor --rfcs`. AGENTS.md CLI reference table replaces the stale v0.10.x verb set (`plan`/`govern`/`direct`/`look`/`ingest`/`reattest`/`list-attestations`) with the v0.11+ canonical surface (`brief`/`run`/`ai-run`/`run-all`/`ci`/`discover`/`ask`/`reattest <sid>`/`attest verify|list|show`/`doctor`/`lint`). CONTEXT.md catalog inventory aligned with actual catalog state (10 CVE, 62 framework-control-gap, 35 jurisdictions, 55 CWE, 28 D3FEND, 31 RFC, 22 DLP entries) and a new "Playbooks and the Seven-Phase Contract" section enumerates the 13 playbooks and the govern → direct → look → detect → analyze → validate → close contract.
+- **Predeploy gate count corrected from "15" to "14"** across AGENTS.md, ARCHITECTURE.md, and README. The predeploy gate set ships 14 gates per `scripts/predeploy.js`; the "15th" framing was an off-by-one carryover from an earlier draft of the diff-coverage gate that landed as the 13th rather than appended. The diff-coverage gate position is also corrected from "14th" to "13th" in AGENTS.md Hard Rule #15 and ARCHITECTURE.md (the validate-playbooks gate sits at position 14).
+- **AGENTS.md CLI reference table now lists `brief --all` and `attest diff <sid>`** as canonical, with `plan` and `reattest` marked as deprecated aliases scheduled for removal in v0.13 (consistent with how the v0.10.x `govern`/`direct`/`look` verbs are surfaced).
+- **AGENTS.md "Seven-phase playbook contract" intro** drops the "direct CLI verbs are landing in a follow-up task" prose — the verbs landed in v0.11.0. Points readers at `exceptd brief` / `exceptd run` / `exceptd ai-run` plus the library entry point at `lib/playbook-runner.js`.
+- **CONTEXT.md phase-contract table** now references `exceptd brief <playbook> --phase {govern,direct,look}` for phases 1-3 (was `exceptd govern|direct|look`); the "How to Walk a Playbook" onboarding section is rewritten against the same canonical surface.
+- **ARCHITECTURE.md CWE entry count** corrected from 51 to 55 (matches `data/cwe-catalog.json` and CONTEXT.md).
+- **Jurisdiction count corrected from "37" / "34" to "35"** in the README badge, status copy, and catalog footnote. `data/global-frameworks.json` has 38 top-level keys but three are `_meta` / `_notification_summary` / `_patch_sla_summary` aggregates; the actual jurisdiction count is 35.
+
+### Operations
+
+- **`.github/workflows/atlas-currency.yml` declares `permissions:` at the job level** instead of the workflow root. Matches the project's OpenSSF Scorecard `TokenPermissionsID` posture (job-scoped least-privilege); top-level permission grants were the only remaining outlier across the repo's workflow set.
+
+### Internal
+
+- **Source-comment slot-token scrub broadened** to cover bare audit slot-tokens (`KK P1-N`, `R-F8`, `S P1-A`, etc.) without the leading `audit` prefix. Previous scrubs only matched `(audit|Audit)\s+[A-Z]+`; the new sweep covers comment-only references across `bin/`, `lib/`, `scripts/`, and `tests/`. Test logic and code logic untouched.
+- **`tests/audit-mm-nn-fixes.test.js` tightened** — the UTF-16BE odd-length-payload refusal test was asserting `notEqual(r.status, 0)`, the exact coincidence-passing-tests anti-pattern the project rule explicitly forbids. Changed to `assert.equal(r.status, 1)`.
+
+Test count and predeploy gates land alongside this entry; see the predeploy log on the release commit.
+
+## 0.12.22 — 2026-05-15
+
 ## 0.12.22 — 2026-05-15
 
 **Patch: trust-chain attestation sidecar redesign, CSAF spec-compliance fixes, CLI flag scoping, concurrency exit-code surface.**
@@ -42,7 +88,7 @@
 - **`data/playbooks/runtime.json domain.cve_refs[]`** completes the Dirty-Frag family by adding `CVE-2026-43284` and `CVE-2026-43500` (already referenced by `kernel.json` and `hardening.json`).
 - **`skills/threat-model-currency/skill.md`** inline `last_threat_review` date aligned to frontmatter (`2026-05-14`).
 
-Test count: 941 → 992 (989 pass + 3 skipped). Predeploy gates: 14/14. Skills: 38/38 signed; manifest envelope signed.
+Test count: 941 → 995 (992 pass + 3 skipped). Predeploy gates: 14/14. Skills: 38/38 signed; manifest envelope signed.
 
 ## 0.12.21 — 2026-05-14
 

package/CONTEXT.md

@@ -1,14 +1,17 @@
 # exceptd Security — AI Context
 
-This file gives any AI assistant the context it needs to use this skill repository effectively. It is AI-system-agnostic and does not assume any particular assistant runtime.
+This file gives any AI assistant the context it needs to use this repository effectively. It is AI-system-agnostic and does not assume any particular assistant runtime.
 
 ---
 
 ## What This Repository Is
 
-exceptd Security is a library of AI security skills grounded in mid-2026 threat reality. Each skill is a structured instruction file that tells an AI assistant how to perform a specific security analysis — what questions to ask, what data to query, how to score risk, and what output to produce.
+exceptd Security ships two interlocking surfaces grounded in mid-2026 threat reality:
 
-**The core insight:** Every major compliance framework (NIST 800-53, ISO 27001, SOC 2, PCI-DSS) was written for environments that no longer describe how attacks happen. These skills explicitly map where framework coverage ends and real attacker capability begins.
+1. **Skills** — Markdown instruction files telling an AI assistant how to perform a specific security analysis (what questions to ask, what data to query, how to score risk, what output to produce).
+2. **Playbooks** — JSON specifications of attack-class investigations executed by the CLI engine through a seven-phase contract (govern → direct → look → detect → analyze → validate → close).
+
+**The core insight:** Every major compliance framework (NIST 800-53, ISO 27001, SOC 2, PCI-DSS) was written for environments that no longer describe how attacks happen. Both skills and playbooks explicitly map where framework coverage ends and real attacker capability begins.
 
 ---
 
@@ -33,42 +36,96 @@ attack_refs:              # MITRE ATT&CK TTP IDs referenced
   - T1068
 framework_gaps:           # Framework controls this skill exposes as insufficient
   - NIST-800-53-SI-2
-forward_watch:            # Upcoming changes to watch for skill updates
+rfc_refs:                 # IETF RFC / Internet-Draft references
+  - RFC-8446
+cwe_refs:                 # Root-cause weakness classes
+  - CWE-787
+d3fend_refs:              # MITRE D3FEND defensive techniques
+  - D3-EAL
+dlp_refs:                 # DLP control IDs (DLP-relevant skills only)
+  - DLP-CHAN-LLM-PROMPT
+forward_watch:            # Upcoming changes to monitor for skill updates
   - FIPS 206 finalization
-last_threat_review:       # Date of last threat currency review
-  "2026-05-01"
+last_threat_review: "2026-05-01"
 ```
 
 ### Skill Body Structure
 
-Every skill has these sections:
+Required sections (every shipped skill):
 
-1. **Threat Context** — Current exploitation reality, not theoretical risk
-2. **Framework Lag Declaration** — Per-framework gap statements with specific control IDs
+1. **Threat Context** — current exploitation reality, not theoretical risk
+2. **Framework Lag Declaration** — per-framework gap statements with specific control IDs
 3. **TTP Mapping** — ATLAS/ATT&CK IDs with framework coverage gap flags
-4. **Exploit Availability Matrix** — PoC status, KEV listing, AI-acceleration factor
-5. **Analysis Procedure** — Step-by-step instructions for performing the analysis
-6. **Output Format** — Exact structure the analysis should produce
-7. **Compliance Theater Check** — Specific test distinguishing paper compliance from real posture
+4. **Exploit Availability Matrix** — PoC status, KEV listing, AI-acceleration factor, live-patchability
+5. **Analysis Procedure** — step-by-step instructions, threading defense-in-depth, least privilege, and zero trust as foundational design principles (not optional considerations)
+6. **Output Format** — exact structure the analysis should produce
+7. **Compliance Theater Check** — specific test distinguishing paper compliance from real posture
+
+Required 8th section for skills shipped on or after 2026-05-11 (pre-existing skills exempt until next minor bump):
+
+8. **Defensive Countermeasure Mapping** — maps offensive findings to MITRE D3FEND IDs with explicit defense-in-depth layer position, least-privilege scope, zero-trust posture, and AI-pipeline applicability.
+
+---
+
+## Playbooks and the Seven-Phase Contract
+
+Playbooks live at `data/playbooks/<id>.json` and are executed by the CLI engine. Each playbook is an attack-class investigation that walks a govern → direct → look → detect → analyze → validate → close loop.
+
+Thirteen playbooks ship today:
+
+| Playbook | Attack class |
+|---|---|
+| `ai-api` | AI API as covert C2 |
+| `containers` | Container escape |
+| `cred-stores` | Credential-store abuse |
+| `crypto` | PQC exposure / HNDL |
+| `crypto-codebase` | Crypto misuse in source |
+| `framework` | Compliance theater (pure-analyze; correlates other playbooks' findings) |
+| `hardening` | Kernel / OS hardening posture |
+| `kernel` | Kernel LPE |
+| `library-author` | Upstream library supply-chain posture |
+| `mcp` | MCP supply chain |
+| `runtime` | Runtime tamper |
+| `sbom` | SBOM / dependency supply chain |
+| `secrets` | DLP exfiltration |
+
+Phase contract:
+
+| Phase | Purpose | CLI surface |
+|---|---|---|
+| 1 govern | Operator consent + jurisdiction clocks (NIS2 24h, DORA 4h, GDPR 72h, etc.) | `exceptd brief <playbook> --phase govern` |
+| 2 direct | Threat-context briefing + skill chain + RWEP threshold | `exceptd brief <playbook> --phase direct` |
+| 3 look | Artifacts and indicators to gather; air-gap alternates | `exceptd brief <playbook> --phase look` |
+| 4 detect | AI applies indicators to captured evidence; runs every required false-positive check | walked inline by the assistant |
+| 5 analyze | Correlate hits → findings | `exceptd run <playbook> --evidence -` |
+| 6 validate | Priority-sorted remediation paths + validation tests + residual-risk statement | (part of `run`) |
+| 7 close | CSAF-2.0 bundle + jurisdiction notification drafts + auditor-ready exception language + `feeds_into` chaining | (part of `run`) |
+
+Preconditions encode hard refuse-to-run conditions: `threat_currency_score < 50` hard-blocks unless `--force-stale`; `_meta.mutex` refuses concurrent conflicting playbooks; `--air-gap` substitutes `air_gap_alternative` source paths.
+
+Attestations persist at `.exceptd/attestations/<session_id>/attestation.json` and can be replayed against the stored evidence with `exceptd reattest <session-id>` (drift verdict) or inspected with `exceptd attest verify|show|list|diff`.
 
 ---
 
 ## Data Files
 
-Skills read from `data/`. These are the authoritative data sources:
-
-| File | Purpose |
-|------|---------|
-| `cve-catalog.json` | 5 CVEs with CVSS, RWEP score, EPSS estimates, CISA KEV flags, PoC and live-patch availability |
-| `atlas-ttps.json` | MITRE ATLAS v5.1.0 (November 2025) techniques and mappings with framework gap flags |
-| `framework-control-gaps.json` | 49 framework control gap entries: designed-for vs. what each control misses |
-| `exploit-availability.json` | Per-CVE PoC locations, weaponization stage, AI-acceleration factor, live-patch status |
-| `global-frameworks.json` | 22+ jurisdictions (expanding to 29+) — framework registry with patch SLAs and notification windows |
-| `zeroday-lessons.json` | Learning-loop entries: zero-day → attack vector → control gap → framework gap → new control requirement |
-| `cwe-catalog.json` | 30 CWE entries pinned to CWE v4.17 (Top 25 2024 plus AI- and supply-chain-relevant weaknesses) for root-cause classification |
-| `d3fend-catalog.json` | 21 MITRE D3FEND defensive techniques pinned to D3FEND v1.0.0; used to map offensive findings to specific defensive countermeasures |
-| `rfc-references.json` | 19 IETF RFC / Internet-Draft references with status, errata count, replaces / replaced-by, and `last_verified` dates |
-| `dlp-controls.json` | 21 DLP control entries indexed by channel, classifier, surface, enforcement mode, and evidence type for DLP-relevant skills |
+Skills and playbooks read from `data/`. Authoritative catalog inventory:
+
+| File | Entries | Purpose |
+|------|---------|---------|
+| `cve-catalog.json` | 10 | CVEs with CVSS, RWEP score, EPSS estimates, CISA KEV flags, PoC and live-patch availability |
+| `atlas-ttps.json` | 15 | MITRE ATLAS v5.1.0 (November 2025) techniques with framework gap flags |
+| `attack-techniques.json` | 79 | MITRE ATT&CK techniques with framework coverage mappings |
+| `framework-control-gaps.json` | 62 | Framework control gap entries: designed-for vs. what each control misses |
+| `exploit-availability.json` | 10 | Per-CVE PoC locations, weaponization stage, AI-acceleration factor, live-patch status |
+| `global-frameworks.json` | 35 jurisdictions | Patch SLAs and notification windows across global regulatory regimes |
+| `zeroday-lessons.json` | 10 | Learning-loop entries: zero-day → attack vector → control gap → framework gap → new control |
+| `cwe-catalog.json` | 55 | CWE v4.17 entries (Top 25 2024 plus AI- and supply-chain-relevant weaknesses) |
+| `d3fend-catalog.json` | 28 | MITRE D3FEND v1.0.0 defensive techniques for offensive → defensive mapping |
+| `rfc-references.json` | 31 | IETF RFC / Internet-Draft references with status, errata count, replaces / replaced-by, `last_verified` dates |
+| `dlp-controls.json` | 22 | DLP control entries indexed by channel, classifier, surface, enforcement mode, evidence type |
+| `playbooks/` | 13 | Playbook specifications (see above) |
+| `_indexes/` | 17 derived files | Pre-computed indexes built by `npm run build-indexes` |
 
 ---
 
@@ -77,15 +134,16 @@ Skills read from `data/`. These are the authoritative data sources:
 To use a skill, match its trigger phrases and follow its Analysis Procedure. Example invocations:
 
 ```
-kernel-lpe-triage           — Assess Linux kernel LPE exposure
+kernel-lpe-triage           — Linux kernel LPE exposure
 ai-attack-surface           — AI/ML attack surface assessment
-framework-gap-analysis      — Feed a control ID + threat → get the gap
-compliance-theater          — Detect where audit compliance ≠ real security
-global-grc NIS2             — Map a threat to NIS2 + companion jurisdictions
+framework-gap-analysis      — control ID + threat → gap statement
+compliance-theater          — detect audit-passing ≠ real-secure
+global-grc NIS2             — map a threat to NIS2 + companion jurisdictions
 exploit-scoring CVE-2026-31431  — RWEP score with full factor breakdown
-security-maturity-tiers     — MVP / Practical / Overkill roadmap for any domain
-zeroday-gap-learn CVE-...   — Run the zero-day learning loop on a new CVE
-pqc-first                   — Post-quantum cryptography readiness assessment
+security-maturity-tiers     — MVP / Practical / Overkill roadmap
+zeroday-gap-learn CVE-...   — zero-day learning loop on a new CVE
+pqc-first                   — post-quantum cryptography readiness
+researcher                  — front-door dispatcher for raw threat intel
 ```
 
 ---
@@ -119,39 +177,26 @@ This repository uses the term "compliance theater" for a specific, measurable co
 
 Seven documented patterns:
 1. **Patch Management Theater** — meets framework SLA, still exposed to active exploitation
-2. **AI Access Control Theater** — service account is compliant; prompt injection bypasses it entirely
-3. **Vendor Management Theater** — vendor controls pass audit; AI tool plugins (MCP servers) are out of scope
-4. **Malware Protection Theater** — signatures are current; AI-generated novel code evades all signatures
-5. **Supply Chain Theater** — software supply chain passes review; developer-installed AI plugins are excluded
-6. **Encryption Theater** — classical encryption is compliant; HNDL exposure is unaddressed
-7. **Detection Theater** — monitoring is compliant; AI C2 channels and AI-querying malware are not detected
+2. **AI Access Control Theater** — service account compliant; prompt injection bypasses it entirely
+3. **Vendor Management Theater** — vendor controls pass audit; MCP plugins are out of scope
+4. **Malware Protection Theater** — signatures current; AI-generated novel code evades all signatures
+5. **Supply Chain Theater** — software supply chain passes review; developer-installed AI plugins excluded
+6. **Encryption Theater** — classical encryption compliant; HNDL exposure unaddressed
+7. **Detection Theater** — monitoring compliant; AI C2 channels and AI-querying malware not detected
 
-Run `lib/framework-gap.js` → `theaterCheck()` to detect these patterns programmatically.
+Run `lib/framework-gap.js` → `theaterCheck()` for programmatic detection. The `framework` playbook surfaces these patterns across an entire estate by correlating findings from other playbooks.
 
 ---
 
-## Orchestration Layer
-
-The `orchestrator/` directory provides:
-- **Scanner** — discovers kernel versions, MCP configs, crypto posture, framework claims
-- **Dispatcher** — routes scanner findings to relevant skills via manifest triggers
-- **Pipeline** — coordinates `threat-researcher` → `source-validator` → `skill-updater` → `report-generator`
-- **Event bus** — triggers skill updates on CISA KEV additions, ATLAS releases, framework amendments
-- **Scheduler** — runs weekly currency checks and annual full audits
-
-Entry point: `node orchestrator/index.js`
+## Agents vs. Skills vs. Playbooks
 
-### Agents vs. Skills
+Three distinct artifact types:
 
-The four orchestration components above (`threat-researcher`, `source-validator`, `skill-updater`, `report-generator`) are **agent definitions** living under `agents/`. They are pipeline workers that run inside the orchestrator — not user-invokable skills.
+- **`skills/<name>/skill.md`** — user-invoked, matched by trigger phrases, interactive front door.
+- **`data/playbooks/<id>.json`** — engine-executed attack-class investigations, structured seven-phase output.
+- **`agents/<name>/`** — pipeline workers (`threat-researcher`, `source-validator`, `skill-updater`, `report-generator`) that run autonomously inside the orchestrator. Not user-invokable.
 
-Skills live under `skills/<name>/skill.md` and are matched by trigger phrases. The `researcher` **skill** (separate from the `threat-researcher` **agent**) is the user-facing entry-point dispatcher: when an operator drops in raw threat intel without knowing which specialized skill to call, the `researcher` skill cross-joins the data catalogs, produces an RWEP-anchored dispatch report, and routes to the right specialized skill(s).
-
-Naming convention to keep straight:
-- `agents/threat-researcher/` — orchestrator pipeline worker (autonomous, background)
-- `skills/researcher/skill.md` — user-invoked triage dispatcher (interactive, front door)
-
-They share a thematic name but are different artifacts with different runtimes.
+The `researcher` **skill** (front-door dispatcher) and `threat-researcher` **agent** (background pipeline worker) share a thematic name but are different artifacts with different runtimes. When in doubt, the path tells you which: `skills/researcher/` vs `agents/threat-researcher/`.
 
 ---
 
@@ -159,28 +204,38 @@ They share a thematic name but are different artifacts with different runtimes.
 
 ### How to Load Skills
 
-1. Read `manifest.json` to get the full skill registry
+1. Read `manifest.json` for the full skill registry
 2. Match user intent against `triggers` arrays
 3. Load the matched `skill.md` into context
 4. Follow the skill's **Analysis Procedure** step by step
-5. Pull data from the referenced `data_deps` files as needed
+5. Pull data from referenced `data_deps` files as needed
 6. Produce output matching the skill's **Output Format**
 
+### How to Walk a Playbook
+
+1. `exceptd brief` (no args) lists available playbooks; `exceptd brief <id>` returns the full Phase 1+2+3 briefing in one document
+2. Surface the Phase-1 jurisdiction obligations to the operator and wait for ack (use `exceptd brief <id> --phase govern` for just that slice)
+3. `exceptd brief <id> --phase direct` and `--phase look` pull the threat context and indicator set
+4. Walk Phase 4 (detect) inline using local tools; run every required false-positive check
+5. Pipe evidence to `exceptd run <id> --evidence -` for Phases 5–7 (use `exceptd ci` for the gate-only variant in CI pipelines)
+6. Offer to persist the attestation and draft any notification messages
+
 ### Context Budget Guidance
 
-- `manifest.json` — load first, always (small, high-value index)
-- `data/cve-catalog.json` — load on demand for any CVE-specific analysis
+- `manifest.json` — load first (small, high-value index)
+- `data/cve-catalog.json` — load on demand for CVE-specific analysis
 - `data/framework-control-gaps.json` — load for gap analysis and theater detection
 - `data/global-frameworks.json` — load for multi-jurisdiction questions
-- `data/atlas-ttps.json` — load for AI attack surface and C2 detection work
-- Individual skill files — 15–40KB each; load on match, not preemptively
+- `data/atlas-ttps.json`, `data/attack-techniques.json` — load for TTP-driven work
+- Individual skill files — 15–40 KB each; load on match, not preemptively
+- Playbook JSON — load on demand via `exceptd direct/look`; the engine handles phase orchestration
 
 ### What This Repo Does Not Contain
 
 - No code that executes automatically in your environment
-- No network calls — all data is local and static
+- No outbound network calls; all data is local and static (the watchlist surface is read-only)
 - No credentials or keys
-- Skills are instruction text — the AI implements them, not the files themselves
+- Skills are instruction text — the AI implements them; playbook execution is governed by the CLI engine
 
 ---
 
@@ -193,9 +248,11 @@ They share a thematic name but are different artifacts with different runtimes.
 | ATLAS | MITRE ATLAS v5.1.0 — AI threat framework |
 | MCP | Model Context Protocol — AI tool integration standard |
 | HNDL | Harvest-Now-Decrypt-Later — quantum threat to current crypto |
-| Framework lag | The gap between what a framework requires and what current TTPs demand |
+| Framework lag | Gap between what a framework requires and what current TTPs demand |
 | Theater | Audit-passing compliance that doesn't close the real attack path |
 | RWEP 90+ | Priority 1: live-patch or isolate same-day |
+| Seven-phase | govern → direct → look → detect → analyze → validate → close |
+| CSAF-2.0 | Common Security Advisory Framework — Phase-7 output bundle format |
 | Copy Fail | CVE-2026-31431 — RWEP 90, CISA KEV, 732-byte deterministic root |
 | Dirty Frag | CVE-2026-43284/43500 — IPsec subsystem LPE chain |
 | SesameOp | AI API as covert C2 channel (ATLAS AML.T0096) |

package/README.md

@@ -18,7 +18,7 @@
 [![ATLAS](https://img.shields.io/badge/MITRE%20ATLAS-v5.1.0-d946ef)](https://atlas.mitre.org)
 [![ATT&CK](https://img.shields.io/badge/MITRE%20ATT%26CK-v17-d946ef)](https://attack.mitre.org)
 [![Ed25519-signed](https://img.shields.io/badge/skills-Ed25519--signed-2ea043)](AGENTS.md)
-[![Jurisdictions](https://img.shields.io/badge/jurisdictions-34-blue)](data/global-frameworks.json)
+[![Jurisdictions](https://img.shields.io/badge/jurisdictions-35-blue)](data/global-frameworks.json)
 
 </div>
 
@@ -30,11 +30,11 @@ This platform surfaces what is actually happening right now. Every skill explici
 
 ## Status
 
-Pre-1.0. Latest release lives on [GitHub Releases](https://github.com/blamejs/exceptd-skills/releases) and on npm as [`@blamejs/exceptd-skills`](https://www.npmjs.com/package/@blamejs/exceptd-skills) (signed npm provenance attestation). 38 skills across kernel LPE, AI attack surface, MCP trust, RAG security, AI-API C2 detection, PQC migration, framework gap analysis, compliance theater, exploit scoring, threat-model currency, zero-day learning, global GRC, policy exception generation, security maturity tiers, skill update loop, attack-surface pen testing, fuzz testing, DLP gap analysis, supply-chain integrity, defensive-countermeasure mapping, identity assurance, OT/ICS security, coordinated vulnerability disclosure, threat-modeling methodology, child-safety age gates, plus sector packs (federal, financial, healthcare, energy) — and a `researcher` triage dispatcher. 10 data catalogs cover CVE / ATLAS / ATT&CK / CWE / D3FEND / DLP / RFC / framework gaps / global frameworks / zero-day lessons. 34 jurisdictions tracked. AI-consumer ergonomics: `data/_indexes/` ships 17 pre-computed indexes (xref / chains / dispatch / DiD ladders / theater fingerprints / recipes / token budget / currency / activity feed) regenerated by `npm run build-indexes`. External-data refresh is automated nightly via `.github/workflows/refresh.yml` — KEV/EPSS/NVD/RFC drift opens an auto-PR with deltas pre-applied; KEV adds new CVEs and IETF discovery auto-imports new RFCs across 48 project-relevant working groups (`_auto_imported` annotation flags entries for human curation); ATLAS/ATT&CK/CWE/D3FEND version bumps open an issue (audit required per AGENTS.md Hard Rule #12). `exceptd verify` prints dual SHA-256 + SHA3-512 public-key fingerprints for out-of-band key pinning. `exceptd scan` probes 22 PQC algorithms across the full NIST + IETF emerging landscape. `exceptd framework-gap <framework> <scenario>` provides a non-AI programmatic runner for the framework-gap skill.
+Pre-1.0. Latest release lives on [GitHub Releases](https://github.com/blamejs/exceptd-skills/releases) and on npm as [`@blamejs/exceptd-skills`](https://www.npmjs.com/package/@blamejs/exceptd-skills) (signed npm provenance attestation). 38 skills across kernel LPE, AI attack surface, MCP trust, RAG security, AI-API C2 detection, PQC migration, framework gap analysis, compliance theater, exploit scoring, threat-model currency, zero-day learning, global GRC, policy exception generation, security maturity tiers, skill update loop, attack-surface pen testing, fuzz testing, DLP gap analysis, supply-chain integrity, defensive-countermeasure mapping, identity assurance, OT/ICS security, coordinated vulnerability disclosure, threat-modeling methodology, child-safety age gates, plus sector packs (federal, financial, healthcare, energy) — and a `researcher` triage dispatcher. 10 data catalogs cover CVE / ATLAS / ATT&CK / CWE / D3FEND / DLP / RFC / framework gaps / global frameworks / zero-day lessons. 35 jurisdictions tracked. AI-consumer ergonomics: `data/_indexes/` ships 17 pre-computed indexes (xref / chains / dispatch / DiD ladders / theater fingerprints / recipes / token budget / currency / activity feed) regenerated by `npm run build-indexes`. External-data refresh is automated nightly via `.github/workflows/refresh.yml` — KEV/EPSS/NVD/RFC drift opens an auto-PR with deltas pre-applied; KEV adds new CVEs and IETF discovery auto-imports new RFCs across 48 project-relevant working groups (`_auto_imported` annotation flags entries for human curation); ATLAS/ATT&CK/CWE/D3FEND version bumps open an issue (audit required per AGENTS.md Hard Rule #12). `exceptd doctor --signatures` prints dual SHA-256 + SHA3-512 public-key fingerprints for out-of-band key pinning. `exceptd discover` probes 22 PQC algorithms across the full NIST + IETF emerging landscape. `exceptd framework-gap <framework> <scenario>` provides a non-AI programmatic runner for the framework-gap skill.
 
 **v0.10.0 introduced the seven-phase playbook contract** — exceptd ships playbooks under `data/playbooks/*.json` that host AIs (Claude Code, Cursor, Gemini CLI, Codex) execute through seven phases: `govern → direct → look → detect → analyze → validate → close`. exceptd owns govern / direct / analyze / validate / close (knowledge + GRC layer); the host AI owns look / detect (artifact collection + indicator evaluation with its native Bash/Read/Grep/Glob).
 
-**v0.11.0 collapses the 21-verb CLI into 11 canonical verbs** + flips the default output to human-readable. The new surface: `discover` (scan cwd → recommend playbooks), `brief` (unified info doc, replaces plan + govern + direct + look), `run` (phases 4-7, with flat or nested submission shape, auto-detect cwd context), `ai-run` (JSONL streaming variant for AI conversational flow), `attest` (subverbs: list / show / export / verify / diff — replaces reattest + list-attestations), `doctor` (one-shot health check — signatures + currency + cve/rfc validation + signing status), `ci` (one-shot CI gate, exit-2 on detected or rwep ≥ escalate), `ask` (plain-English routing), `lint` (pre-flight submission shape check). Attestation root moved from cwd-relative `.exceptd/` to `~/.exceptd/attestations/<repo-or-host-tag>/`. v0.10.x verbs (`plan`/`govern`/`direct`/`look`/`scan`/`dispatch`/`currency`/`verify`/`validate-cves`/`validate-rfcs`/`watchlist`/`prefetch`/`build-indexes`/`ingest`/`reattest`/`list-attestations`) still work via one-time deprecation banner — removed in v0.12.
+**v0.11.0 collapses the 21-verb CLI into 11 canonical verbs** + flips the default output to human-readable. The new surface: `discover` (scan cwd → recommend playbooks), `brief` (unified info doc, replaces plan + govern + direct + look), `run` (phases 4-7, with flat or nested submission shape, auto-detect cwd context), `ai-run` (JSONL streaming variant for AI conversational flow), `attest` (subverbs: list / show / export / verify / diff — replaces reattest + list-attestations), `doctor` (one-shot health check — signatures + currency + cve/rfc validation + signing status), `ci` (one-shot CI gate, exit-2 on detected or rwep ≥ escalate), `ask` (plain-English routing), `lint` (pre-flight submission shape check). Attestation root moved from cwd-relative `.exceptd/` to `~/.exceptd/attestations/<repo-or-host-tag>/`. v0.10.x verbs (`plan`/`govern`/`direct`/`look`/`scan`/`dispatch`/`currency`/`verify`/`validate-cves`/`validate-rfcs`/`watchlist`/`prefetch`/`build-indexes`/`ingest`/`reattest`/`list-attestations`) still work via one-time deprecation banner — scheduled for removal in v0.13.
 
 **v0.11.1-0.11.7 stability arc** — 30+ operator-reported items fixed across the v0.11.x line: mutex filesystem lockfile, `--vex` filter, `--ci` exit-code gating, `--diff-from-latest`, `--operator`/`--ack` attestation binding, `--format <fmt>` actually transforms output for run + ci, `ask` synonym routing, `lint` shares normalize contract with runner, CSAF/SARIF/OpenVEX bundles include indicator hits + framework gaps (was: empty for posture-only playbooks), CSAF current_release_date populated, SARIF rule definitions for every ruleId, `doctor --fix` for missing private key, `--strict-preconditions` flag, default human output for `attest list`/`lint` on TTY. Permanent regression suite at `tests/operator-bugs.test.js` (35 named test cases) — re-introductions caught at `npm test`, not at user re-report.
 
@@ -169,7 +169,7 @@ You're adding a skill, updating a catalog, or cutting a release. Clone + bootstr
 git clone https://github.com/blamejs/exceptd-skills
 cd exceptd-skills
 npm run bootstrap          # auto-detects: verify-only / re-sign / first-init
-npm run predeploy          # full 15-gate CI sequence locally
+npm run predeploy          # full 14-gate CI sequence locally
 ```
 
 `bootstrap` auto-detects the right mode based on which keys exist on disk:
@@ -309,7 +309,7 @@ exceptd help                          This help.
 exceptd <verb> --help                 Per-verb usage with flag descriptions.
 ```
 
-### Legacy v0.10.x verbs (deprecated, removed in v0.12)
+### Legacy v0.10.x verbs (deprecated, scheduled for removal in v0.13)
 
 These still work but emit a one-time deprecation banner per process:
 
@@ -382,13 +382,13 @@ Regenerate with `exceptd build-indexes` (full) or `exceptd build-indexes --chang
 
 ## Data catalogs
 
-All skills pull from `data/`. Cross-validated against canonical upstream sources via `exceptd refresh` / `exceptd validate-cves` / `exceptd validate-rfcs`.
+All skills pull from `data/`. Cross-validated against canonical upstream sources via `exceptd refresh` / `exceptd doctor --cves` / `exceptd doctor --rfcs`.
 
 - `cve-catalog.json` — CVE metadata with RWEP scores, CISA KEV status, PoC availability, live-patch info
 - `atlas-ttps.json` — MITRE ATLAS v5.1.0 TTPs with gap flags and exploitation examples
 - `framework-control-gaps.json` — Per-framework, per-control: what it was designed for vs. what it misses
 - `exploit-availability.json` — PoC locations, weaponization status, AI-assist factor
-- `global-frameworks.json` — All major global compliance frameworks (34 jurisdictions) with control inventories and lag scores
+- `global-frameworks.json` — All major global compliance frameworks (35 jurisdictions) with control inventories and lag scores
 - `zeroday-lessons.json` — Zero-day → control gap → framework gap → new control requirement mappings
 - `cwe-catalog.json` — CWE entries pinned to CWE v4.17 (Top 25 + AI- / supply-chain-relevant additions)
 - `d3fend-catalog.json` — MITRE D3FEND defensive technique entries pinned to D3FEND v1.0.0