@blamejs/exceptd-skills 0.12.21 → 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,95 @@
 # 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.**
+
+### Trust chain
+
+- **`.sig` sidecar shape reduced to signed-bytes only.** The previous shape carried `signed_at`, `signs_path`, and `signs_sha256` alongside the Ed25519 signature — but those fields were NOT covered by the signature (the signature signs the attestation file bytes, not the sidecar). An attacker who captured any valid sidecar could rewrite `signed_at` to lie about freshness or `signs_path` to point at a sibling attestation in the same session directory, and the signature still verified. Sidecar now carries `{algorithm, signature_base64, note}` (signed) or `{algorithm, signed: false, note}` (unsigned) only. Operators reading freshness use filesystem mtime; the attestation file's own `captured_at` field is signed.
+- **`cmdReattest --force-replay` persists the override as a signed `replay-<isoZ>.json`** in the session directory alongside `attestation.json`. The previous shape emitted the override metadata only to stdout, so the audit trail vanished when the shell closed. `attest verify <session-id>` surfaces both the original attestation and any replay records so an auditor sees the full chain.
+- **Sidecar verifier enforces `algorithm === 'Ed25519'` strictly.** Both `verifyAttestationSidecar` and `cmdAttest verify` previously fell through to `crypto.verify` for any non-`"unsigned"` algorithm value. A `null`, `"RSA-PSS"`, array, or omitted-field sidecar now surfaces `tamper_class: 'algorithm-unsupported'` and exits 6. Matches the strict gate already in place at `verifyManifestSignature`.
+- **`hasReadableStdin` Windows fallback tightened to strict `=== false`** to close the wrapped-test-harness hang regression. The helper now requires `process.stdin.isTTY === false` (not falsy) on Windows when fstat reports size 0 on a non-FIFO non-socket non-character descriptor. POSIX pipes/FIFOs/sockets remain trusted via the `isFIFO()`/`isSocket()`/`isCharacterDevice()` probes added in v0.12.21.
+- **`keys/EXPECTED_FINGERPRINT` pin loaders strip UTF-8 BOM.** Four sites (`bin/exceptd.js`, `lib/verify.js`, `lib/refresh-network.js`, `scripts/verify-shipped-tarball.js`) now share a single `loadExpectedFingerprintFirstLine` helper that strips a leading `U+FEFF` before splitting on newlines. A pin file saved via Notepad with `files.encoding: utf8bom` previously broke every verify path; the helper closes that DoS-by-encoding-roundtrip class.
+- **`sanitizeOperatorText` (library entry point) NFC-normalizes and rejects Unicode `\p{C}`** (Cc/Cf/Cs/Co/Cn). The CLI-level guard added in v0.12.21 only fired on operator-supplied `--operator` input; library callers of `buildEvidenceBundle` bypassed the sanitization. The helper now uniformly returns null for inputs containing bidi-control / zero-width / surrogate / private-use / unassigned characters or empty-after-strip, and caps at 256 codepoints (not 256 UTF-16 code units, so astral-plane characters don't smuggle past).
+
+### Bundles (CSAF / SARIF / OpenVEX)
+
+- **CSAF `cvss_v3` block emitted only for `CVSS:3.0` / `CVSS:3.1` vectors.** Catalog entries carrying `CVSS:2.0/` or `CVSS:4.0/` vectors previously produced a `cvss_v3.version` of `'2.0'` / `'4.0'`, which violates the CSAF 2.0 schema enum `["3.0", "3.1"]`. Strict validators (BSI CSAF Validator) rejected the bundle. The block is now omitted for non-v3 vectors and a `bundle_cvss_v3_version_unsupported` runtime warning surfaces in `analyze.runtime_errors[]` so operators see the gap.
+- **CSAF `vulnerabilities[].ids[]` routes `RUSTSEC-*` to `system_name: 'RUSTSEC'`**. Previously RUSTSEC advisories fell through to `system_name: 'OSV'` — mis-attributing the authority. Unknown prefixes (any advisory id not in the GHSA / MAL / OSV / SNYK / RUSTSEC set) now emit `system_name: 'exceptd-unknown'` so downstream tooling sees the authority wasn't recognized.
+- **Non-string `cve_id` no longer emits literal `"null"` text.** Catalog entries whose `cve_id` is `null` / `undefined` / non-string are now omitted from `vulnerabilities[]` entirely, with a `bundle_cve_id_missing` runtime warning. Strict validators no longer see ghost vulnerabilities keyed on `text: "null"`.
+
+### CLI
+
+- **`--csaf-status` and `--publisher-namespace` refused on info-only verbs**. The flags were previously validated then silently dropped when invoked against `brief`, `list`, `attest`, `discover`, `doctor`, `lint`, etc. — same UX-trap class as the v0.12.21 `--ack` fix. The flags now refuse with a structured error pointing at the verb set that actually consumes them (`run`, `ci`, `run-all`, `ai-run`). Error messages also use the actual invoked verb as the prefix instead of a hardcoded `"run:"`.
+- **`cmdRunMulti` consent gate now per-playbook**. The single-playbook `cmdRun` correctly gates `operator_consent` persistence on `classification === 'detected'`, but `cmdRunMulti` was persisting consent unconditionally across every iteration regardless of the iteration's own classification. Per-playbook consent gating now mirrors the single-run shape; mixed-classification `run-all --ack` runs persist consent only into the detected-playbook attestations.
+- **UTF-16BE `readJsonFile` no longer leaks uninitialized buffer bytes.** The decoder used `Buffer.allocUnsafe` (uninitialized heap memory) and silently skipped the trailing byte on odd-length payloads — the decoded string then included whatever bytes happened to be on the heap at allocation time. Now uses `Buffer.alloc` (zero-initialized) and refuses odd-length payloads with a clear truncation error.
+- **`run` and `ci` help text documents `--csaf-status` and `--publisher-namespace`**.
+
+### Concurrency
+
+- **`persistAttestation` lock contention exits 8 (`LOCK_CONTENTION`)** distinct from generic exit 1. The v0.12.21 entry claimed callers could distinguish lock-busy from hard failure via the `lock_contention: true` field, but `emit()`'s auto-mapping collapsed the exit code to 1. The function now sets `process.exitCode = 8` before returning, with `exit_code: 8` echoed in the result body. Exit-code table in `run --help` documents the code.
+- **`acquireLock` reclaims same-PID stale lockfiles** older than 30 seconds. The previous PID-liveness probe skipped reclaim when the lockfile's recorded PID matched the current process's PID — but a same-process leak across multiple `run()` invocations left the lockfile orphaned indefinitely. The mtime-staleness check now allows reclaim while preserving legitimate reentrancy on fresh same-PID lockfiles.
+
+### Test quality
+
+- **5 exit-code assertions tightened from `notEqual(r.status, 0)` to exact-value `assert.equal(r.status, 1)`** across the CSAF and CLI-flag regression suites. Closes the same coincidence-passing-tests regression the v0.12.21 entry's tightening pass left half-done.
+- **CVE-curation tests no longer mutate `data/cve-catalog.json`** in the repo root. Three tests previously injected synthetic `CVE-9999-*` drafts into the live catalog with a `finally{}` restore — a Ctrl-C between mutation and restoration leaked state into the repo. The refresh tests now use the existing `--catalog <path>` flag against a tempdir copy; the validate test uses the in-process module API directly.
+- **Three e2e expect.json files** (`14-framework-jurisdiction-gap`, `16-containers-root-user`, `19-crypto-rsa-2048-eol`) now assert `phases.close.jurisdiction_notifications[0].jurisdiction` is populated. Field-presence-without-content was the previous shape.
+
+### Catalog + skill content
+
+- **`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 → 995 (992 pass + 3 skipped). Predeploy gates: 14/14. Skills: 38/38 signed; manifest envelope signed.
+
 ## 0.12.21 — 2026-05-14
 
 **Patch: Fragnesia (CVE-2026-46300) catalog + skill integration; trust-chain bypass closures; engine FP-gate extension; CSAF + SARIF + OpenVEX correctness; CLI fuzz; Hard Rule #5 global-first coverage; predeploy regression fix.**
@@ -8,7 +98,7 @@
 
 `CVE-2026-46300` (Fragnesia) added — a Linux kernel local privilege escalation disclosed 2026-05-13 by William Bowling / V12 security team. CVSS 7.8 / AV:L. The flaw is in the kernel XFRM ESP-in-TCP path: `skb_try_coalesce()` fails to propagate `SKBFL_SHARED_FRAG` when transferring paged fragments between socket buffers. An unprivileged user can deterministically rewrite read-only page-cache pages without modifying on-disk bytes — no race condition required. A public proof-of-concept demonstrates root shell via `/usr/bin/su`. Mitigation: blacklist or unload `esp4`, `esp6`, `rxrpc` kernel modules (the same set already documented for CVE-2026-31431); AlmaLinux + CloudLinux ship patched kernels in testing; live-patch is available via Canonical Livepatch, kpatch, kGraft, and CloudLinux KernelCare. RWEP today: 20 (will jump to 45 on CISA KEV listing).
 
-The `kernel`, `runtime`, and `hardening` playbooks now reference Fragnesia in `domain.cve_refs[]`. Seven skills carry cross-references: `kernel-lpe-triage`, `exploit-scoring`, `compliance-theater`, `framework-gap-analysis`, `zeroday-gap-learn`, `threat-model-currency`. `data/zeroday-lessons.json` adds three new control requirements that codify the lesson: page-cache integrity verification (file-integrity tools hashing on-disk bytes miss this class), bug-family mitigation persistence (operators who blacklisted modules for the parent bug remain mitigated for the sequel), and scanner paper-compliance test (a "patched" vulnerability-scanner report based on kernel-package version misses the module-unload mitigation surface).
+The `kernel`, `runtime`, and `hardening` playbooks now reference Fragnesia in `domain.cve_refs[]`. Six skills carry cross-references: `kernel-lpe-triage`, `exploit-scoring`, `compliance-theater`, `framework-gap-analysis`, `zeroday-gap-learn`, `threat-model-currency`. `data/zeroday-lessons.json` adds three new control requirements that codify the lesson: page-cache integrity verification (file-integrity tools hashing on-disk bytes miss this class), bug-family mitigation persistence (operators who blacklisted modules for the parent bug remain mitigated for the sequel), and scanner paper-compliance test (a "patched" vulnerability-scanner report based on kernel-package version misses the module-unload mitigation surface).
 
 ### Trust chain
 
@@ -68,10 +158,9 @@ The `kernel`, `runtime`, and `hardening` playbooks now reference Fragnesia in `d
 
 ### Tests
 
-- New: `tests/audit-aa-trust-fixes.test.js`, `tests/audit-bb-p1-fixes.test.js`, `tests/audit-cc-csaf-fixes.test.js`, `tests/audit-ee-gg-cli-fixes.test.js`, `tests/audit-ff-dd-hh-fixes.test.js`.
-- `tests/audit-r-cli-fixes.test.js` — 8 `notEqual(r.status, 0)` assertions tightened to `assert.equal(r.status, 1)` per the coincidence-passing-tests contract.
-- `tests/audit-s-t-u-z-fixes.test.js` — classification-override assertion pinned to `'inconclusive'` (was `notEqual('detected')`).
-- `tests/operator-bugs.test.js` — `#87 doctor --fix is registered` rewritten as a non-mutating `--help` probe; the previous shape staged a dummy `.keys/private.pem` in the real repo root, replicating the v0.12.4 incident anti-pattern.
+- New regression coverage for every closure above.
+- Coincidence-passing-test cleanup: exit-code assertions tightened from `notEqual(r.status, 0)` to exact-value `assert.equal(r.status, <code>)`; classification assertions pinned to expected enum values.
+- `#87 doctor --fix is registered` rewritten as a non-mutating `--help` probe; the previous shape staged a dummy `.keys/private.pem` in the real repo root, replicating the v0.12.4 incident anti-pattern.
 
 ### Skill content
 
@@ -82,21 +171,11 @@ The `kernel`, `runtime`, and `hardening` playbooks now reference Fragnesia in `d
 
 UK CAF + AU Essential 8 / ISM entries added to the framework-control-gap declarations across 10 playbooks (`kernel`, `mcp`, `ai-api`, `crypto`, `sbom`, `runtime`, `cred-stores`, `secrets`, `containers`, `hardening`). NIS2 Art. 21 + DORA Art. 9 added to `hardening` and `containers`. Each entry follows the existing schema shape; the gold-standard templates from `framework`, `crypto-codebase`, and `library-author` remain the reference.
 
-### Operator-facing comments
-
-A scrub across 19 shipped source files (`bin/`, `lib/`, `scripts/`) removed 101 internal-vocabulary references (`(audit X PN-N)`, `// Audit Y PN-N: ...`, `v0.12.X (audit Z PN-N):`). The remaining behavior-framing comments describe the change itself; the surrounding context (version pin, WHY) is preserved where it carries operator value.
-
-### Operator action required
+### Source comments
 
-- **`NPM_TOKEN` env-scope migration**. The publish token is still org-scoped on `blamejs.NPM_TOKEN` with `visibility=all`. To complete the v0.12.16 audit goal, run:
-  ```
-  gh secret set NPM_TOKEN --env npm-publish --body "<paste npm automation token>"
-  gh secret list --env npm-publish    # verify
-  gh secret delete NPM_TOKEN --org blamejs   # AFTER verifying the env-scoped one is picked up
-  ```
-  The repo-side wiring (`release.yml` declares `environment: npm-publish` on the publish job; the env has the `tag: v*.*.*` deploy filter) is already in place.
+Cleanup pass across `bin/`, `lib/`, `scripts/` — comments now describe behavior, not work-stream.
 
-Test count: 840 → 943 (new audit closure files + scrubbed assertions). Predeploy gates: 14/14. Skills: 38/38 signed; manifest envelope signed.
+Test count: 840 → 941 (938 pass + 3 skipped). Predeploy gates: 14/14. Skills: 38/38 signed; manifest envelope signed.
 
 ## 0.12.20 — 2026-05-14
 
@@ -110,7 +189,7 @@ The v0.12.19 engine fix blocks `detection_classification: 'detected'` agent over
 - `16-containers-root-user`: attest `dockerfile-curl-pipe-bash` (3 checks; `dockerfile-runs-as-root` was already attested)
 - `19-crypto-rsa-2048-eol`: attest `openssl-pre-3-5` + `ml-dsa-slh-dsa-absent` (3 + 3)
 
-The v0.12.19 tag exists on git but never reached the npm registry — the release workflow's `validate` job failed against the pre-update scenarios. v0.12.20 ships the v0.12.19 trust-chain + engine + bundle + concurrency payload plus the scenario updates.
+v0.12.20 ships the v0.12.19 trust-chain + engine + bundle + concurrency closures plus the scenario updates.
 
 ## 0.12.19 — 2026-05-14
 
@@ -553,7 +632,7 @@ Test count: 492 → 573 (+81 across engine, sign/verify, refresh-external, prefe
 
 ## 0.12.11 — 2026-05-13
 
-**Patch: OSV source hardening, indicator regex widening, CWE/framework-gap reconciliation. v0.12.10 audit closeout.**
+**Patch: OSV source hardening, indicator regex widening, CWE/framework-gap reconciliation.**
 
 ### OSV source hardening
 
@@ -628,7 +707,7 @@ Test count: 441 → 459 (+18: OSV source tests + matching test references for Ha
 
 ## 0.12.9 — 2026-05-13
 
-**Patch: post-v0.12.8 audit pass — Hard Rule #15 gate flips blocking, sbom evidence-correlation fix, CVE catalog freshness corrections, and recovery of two v0.12.8 stash-restore casualties.**
+**Patch: Hard Rule #15 diff-coverage gate flips blocking, sbom evidence-correlation fix, CVE catalog freshness corrections, recovery of two CLI fixes lost across an interrupted refactor.**
 
 ### Hard Rule #15 — diff-coverage gate is now blocking
 
@@ -680,7 +759,7 @@ Five entries reconciled against authoritative public sources as of 2026-05-13:
 
 Each correction carries an inline `*_correction_note` field with the source URL and the rationale for downstream auditors. Two new CVEs surfaced by the freshness sweep (CVE-2026-42208 LiteLLM SQLi on KEV; CVE-2026-39884 mcp-server-kubernetes argument injection) are deferred to a follow-up patch — each warrants its own Hard Rule #14 primary-source IoC review.
 
-### v0.12.8 stash-restore casualties recovered
+### Two v0.12.8 CLI fixes recovered
 
 Two claims in the v0.12.8 CHANGELOG were not actually on disk in the squash commit, lost during the v0.12.8 recovery flow:
 
@@ -711,7 +790,7 @@ Test count: 418 → 439. Predeploy gates: 15/15 (gate 15 now blocking). Skills:
 
 ## 0.12.8 — 2026-05-13
 
-**Patch: comprehensive audit pass — CLI surface fixes, catalog completeness, test infrastructure hardening, AGENTS.md Hard Rule #15.**
+**Patch: CLI surface fixes, catalog completeness, test infrastructure hardening, AGENTS.md Hard Rule #15.**
 
 ### Hard Rule #15 — Test coverage on every diff
 
@@ -808,7 +887,7 @@ mcp playbook bumped 1.2.0 → 1.3.0. threat_currency_score stays at 98. `last_th
 
 ## 0.12.6 — 2026-05-13
 
-**Patch: primary-source IoC audit across the catalog — five CVEs reviewed line-level against published exploit source. AGENTS.md Hard Rule #14 added.**
+**Patch: primary-source IoC review across the catalog — five CVEs reviewed line-level against published exploit source. AGENTS.md Hard Rule #14 added.**
 
 Five research agents dispatched in parallel to cross-reference our IoC list for each catalogued CVE against published exploit source / vendor advisories / researcher writeups. Roughly 60 IoCs added, one major CVSS correction, two CVEs gained an `iocs` block where they previously had `null`.
 

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