@blamejs/exceptd-skills 0.12.7 → 0.12.8

package/AGENTS.md

@@ -34,6 +34,20 @@ Also read [CONTEXT.md](CONTEXT.md) for a complete orientation to the skill syste
 
 14. **Primary-source IoC review** — Any CVE entry in `data/cve-catalog.json` whose `poc_available: true` AND whose exploit code is publicly available (published PoC repo, vendor advisory with attached payload, researcher blog with reproducer) must include `iocs` populated from a line-level cross-reference of the published source — not from secondary-source paraphrase. The `iocs` block records which IoC categories were extracted (`payload_artifacts`, `persistence_artifacts`, `credential_paths_scanned`, `c2_indicators`, `host_recon`, `behavioral`, `runtime_syscall`, `kernel_trace`, `livepatch_gap`, `destructive`, `payload_content_patterns`, `supply_chain_entry_vectors`), and each IoC must be traceable to a specific source URL or commit hash. v0.12.6 audit reviewed CVE-2026-45321 (Mini Shai-Hulud), CVE-2026-31431 (Copy Fail / Dirty Pipe / Dirty COW family), CVE-2026-43284 + CVE-2026-43500 (Dirty Frag pair), CVE-2025-53773 (Copilot YOLO mode), and CVE-2026-30615 (Windsurf MCP) against primary sources from Aikido, StepSecurity, Socket, Wiz, Datadog, Sysdig, Trail of Bits, Invariant Labs, Embrace the Red, NVD, MSRC. Catalog updates landed in v0.12.6 changelog. Skipping this audit is equivalent to shipping "untested security advice" — the IoC list IS the operator-facing detection contract.
 
+15. **Test coverage on every diff** — Every feature change (added, removed, or modified) must land with a covering test reference in the same PR. The shapes the gate enforces:
+
+    | Change                                                | Required test reference                                                          |
+    | ----------------------------------------------------- | -------------------------------------------------------------------------------- |
+    | New / removed CLI verb in `bin/exceptd.js`            | Quoted verb literal in a `tests/*.test.js` file                                  |
+    | New / removed CLI flag                                | Flag literal (e.g. `--my-flag`) somewhere under `tests/`                         |
+    | New / removed / renamed `module.exports` identifier   | `require('…/<lib>')` plus a reference to the identifier in `tests/`              |
+    | 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.
+
+    The gate ships in v0.12.8 as `--warn-only` during the rollout window; it flips to blocking in v0.12.9. Once blocking, 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.
+
 ---
 
 ## Seven-phase playbook contract

package/CHANGELOG.md

@@ -1,5 +1,72 @@
 # Changelog
 
+## 0.12.8 — 2026-05-13
+
+**Patch: comprehensive audit pass — CLI surface fixes, catalog completeness, test infrastructure hardening, AGENTS.md Hard Rule #15.**
+
+### Hard Rule #15 — Test coverage on every diff
+
+`AGENTS.md` adds a fifteenth hard rule: every CLI verb, CLI flag, `module.exports` identifier, playbook `phases.detect.indicators[].id`, or CVE `iocs` field change must land with a covering test reference in the same PR. Enforcement lives in `scripts/check-test-coverage.js`, wired as the 15th `npm run predeploy` gate and the `Diff coverage` job in `ci.yml`. Ships `--warn-only` for one release cycle then flips blocking in v0.12.9. Docs, workflow YAML, and skill body changes are allowlisted; whitespace-only diffs are ignored.
+
+### CLI surface — exit-code, dispatcher, and ingest
+
+`run --ci`, `run --all`, and `ai-run --stream` previously called `process.exit(N)` immediately after `emit()` writes to stdout — the v0.11.10 #100 truncation class. All three sites now use `process.exitCode = N; return;` so buffered async stdout fully drains before the event loop ends. The `ai-run` streaming handler additionally pauses stdin on completion so further callbacks cannot re-enter after the final frame.
+
+The deprecation banner for legacy verbs now fires for every alias in `LEGACY_VERB_REPLACEMENTS`, not just the subset routed through `PLAYBOOK_VERBS`. Operators running `scan`, `dispatch`, `currency`, `verify`, `validate-cves`, `validate-rfcs`, `watchlist`, `prefetch`, or `build-indexes` now see the same one-time banner pointing at the v0.11.0 replacement that `plan`, `govern`, `direct`, `look`, `ingest`, `reattest`, and `list-attestations` already surfaced.
+
+`ingest` previously wrote its attestation via an inline `writeFileSync` that bypassed both the session-id collision refusal and the Ed25519 sidecar signing layer that `run` and `run --all` go through. Two `ingest` invocations with the same `--session-id` would silently clobber the audit trail and no `.sig` ever landed. Routed through `persistAttestation()` now — collision refusal and `maybeSignAttestation()` both apply.
+
+Per-verb `--help` text expanded to cover surface that shipped undocumented: `ci --required <ids>`, `ci --max-rwep`, `ci --block-on-jurisdiction-clock`, `ci --evidence-dir`, `ci --format`, plus the full four-line exit-code matrix (0 PASS / 1 framework error / 2 detected / 3 ran-but-no-evidence / 4 blocked). `attest list` and `attest diff` subverbs added to the `attest --help` enumeration. `run --upstream-check`, `--strict-preconditions`, `--session-key`, `--air-gap`, `--force-overwrite` documented in the `run` block. `doctor --registry-check` and `doctor --fix` documented in the `doctor` block. `brief`, `lint`, `run-all`, `verify-attestation` gain per-verb help entries.
+
+### Catalog completeness — 47 new entries close cross-catalog dangling refs
+
+Six ATLAS TTPs added to `data/atlas-ttps.json`: T0024 (Exfiltration via ML Inference API), T0044 (Full ML Model Access), T0048 (Erode ML Model Integrity), T0053 (LLM Plugin Compromise), T0055 (Unsecured Credentials), T0057 (LLM Data Leakage). All previously referenced by `data/cve-catalog.json` (CVE-2026-45321) and `data/dlp-controls.json` without a catalog entry.
+
+Seventeen CWE entries added to `data/cwe-catalog.json`: CWE-250, 256, 284, 310, 312, 326, 328, 329, 330, 331, 338, 353, 426, 522, 759, 760, 916. All previously referenced by playbook `domain.cwe_refs` across `containers`, `cred-stores`, `crypto`, `crypto-codebase`, `ai-api`, `secrets`, `hardening`, `runtime`, and `library-author` without a catalog entry.
+
+Eight D3FEND entries added to `data/d3fend-catalog.json`: D3-ANCI, D3-CAA, D3-CH, D3-EI, D3-FCR, D3-KBPI, D3-SCA, D3-SFA. All previously referenced by playbook `domain.d3fend_refs` without a catalog entry.
+
+Ten framework-control-gap entries added to `data/framework-control-gaps.json`: NIS2-Art21-incident-handling, EU-AI-Act-Art-15, UK-CAF-A1/B2/C1/D1, AU-Essential-8-MFA/App-Hardening/Patch/Backup. Closes the Hard Rule #5 (global-first) gap for 23 skills that previously declared US-anchored `framework_gaps` only.
+
+Twelve standards entries added to `data/rfc-references.json`: RFC-7489 (DMARC), RFC-6376 (DKIM), RFC-7208 (SPF), RFC-8616 (IDN email auth), RFC-8461 (MTA-STS), ISO-29147 + ISO-30111 (vulnerability disclosure + handling), RFC-9116 (security.txt), CSAF-2.0, RFC-6545 (RID), RFC-6546 (RID transport), RFC-7970 (IODEF v2). Schema (`lib/schemas/skill-frontmatter.schema.json`) + validator (`tests/rfc-refs.test.js`) extended to accept the broader standards-key shape (`RFC-`, `DRAFT-`, `ISO-`, `CSAF-`) alongside RFC numbers.
+
+### Playbook integrity — orphan close + indicator wiring
+
+`library-author.json` `_meta.feeds_into` removed a dangling `compliance-theater` entry (no such playbook file exists); the remaining `framework` entry handles the same condition. `mcp.json` `domain.cve_refs` now lists CVE-2025-53773 alongside CVE-2026-30615 and CVE-2026-45321 — closes the Hard Rule #4 gap where the existing `copilot-yolo-mode-flag` and `copilot-chat-experimental-flags` indicators detected the CVE without the playbook claiming it.
+
+Eight playbooks had artifacts collected in `phases.look.artifacts[]` that no indicator consumed — operator paid the collection cost, no detection ran. Containers (9 orphans), cred-stores (9), runtime (11), crypto (10), hardening (11), library-author (14), sbom (18), secrets (7) all now cite every collected artifact in at least one indicator. Six new indicators added (`psa-policy-permissive-or-absent` and `network-policies-absent-from-workload-namespace` in `containers`; `kernel-lockdown-none`, `sudoers-tty-pty-logging-absent`, `audit-rules-empty-or-skeletal`, `umask-permissive` in `hardening`) where existing detection logic conceptually consumed the artifact but no rule had been written.
+
+### Skill files — required-section closures, Hard Rule #5 sweep
+
+`kernel-lpe-triage`, `security-maturity-tiers`, and `skill-update-loop` previously failed the Hard Rule #11 required-section contract. `kernel-lpe-triage` had a Compliance Theater Check embedded inside Analysis Procedure Step 5 but no top-level section; `security-maturity-tiers` had no Compliance Theater section at all; `skill-update-loop` was missing Threat Context and TTP Mapping. All three sections promoted to top-level with substantive content.
+
+Twenty-three skills had US-anchored `framework_gaps` only (NIST + ISO + SOC2). Each gains EU + UK + AU tokens (`NIS2-Art21-incident-handling` / `EU-AI-Act-Art-15`, `UK-CAF-A1/B2/C1/D1`, `AU-Essential-8-MFA/App-Hardening/Patch/Backup` as the per-skill match dictates). `ai-c2-detection` `cwe_refs` populated with CWE-918. `email-security-anti-phishing` `rfc_refs` populated with RFC-7489/6376/7208/8616/8461. `identity-assurance` `d3fend_refs` populated with D3-MFA + D3-CSPP. `coordinated-vuln-disclosure` `rfc_refs` populated with ISO-29147/30111, RFC-9116, CSAF-2.0. `incident-response-playbook` `rfc_refs` populated with RFC-6545/6546/7970.
+
+Four skills bump `last_threat_review` to 2026-05-13 to reflect post-v0.12.6 catalog state: `kernel-lpe-triage`, `ai-attack-surface`, `mcp-agent-trust`, `ai-c2-detection`. Four skills replace literal `xxx` placeholders in body text with explicit angle-bracket placeholders (`<patch-revision>`, `<sub-technique-id>`, `<advisory-number>`) so future Rule #10 audits don't surface false positives.
+
+### Test infrastructure
+
+The `cli()` test helper now routes attestations to a per-suite tempdir via `EXCEPTD_HOME` instead of writing to `~/.exceptd/attestations/`. Every prior `npm test` run had been accumulating attestations in the maintainer's real home dir without cleanup; tempdir routing fixes the structural class behind the v0.11.x→v0.12.4 sign regression. Helper factored to `tests/_helpers/cli.js` so it can be required by both `operator-bugs.test.js` and the new `cli-coverage.test.js`.
+
+Twenty-eight previously-coincidence-passing assertions in `operator-bugs.test.js` strengthened: silent fall-through `if (data?.ok === false)` branches replaced with hard parse + shape checks first; `assert.notEqual(r.status, 0)` replaced with explicit exit-code pins (2 for format-rejected, 4 for blocked, etc.); `assert.ok(data)` replaced with field-shape assertions. Two coincidence-passes that hid real defects became actual findings:
+
+- `refresh --no-network` on Windows + Node 25 surfaces a libuv `UV_HANDLE_CLOSING` assertion at worker-pool teardown after the prefetch summary flushes cleanly (exit 3221226505 / 0xC0000409). The summary contract is honored; the teardown crash is a Windows-libuv quirk. Test accepts both 0 and the Windows exit code so long as the stdout summary matches the strict numeric-breakdown regex.
+- `refresh` pin sources `d3fend__d3fend-data__releases` and `mitre__cwe__releases` return HTTP 404 — surfaces as `2 error(s)` in every prefetch summary. Flagged for upstream catalog-pin work; not a regression introduced here.
+
+`lib/refresh-external.js` now accepts `--catalog <path>` and honors `EXCEPTD_CVE_CATALOG` so tests can redirect catalog writes to a tempdir instead of mutating the shipped `data/cve-catalog.json`. Eight catalog-mutating tests in `operator-bugs.test.js` can now route to tempdirs.
+
+Thirty-one new CLI happy-path tests in `tests/cli-coverage.test.js` exercise `brief` (all/scope/directives/phase), `discover`, `doctor` (all subchecks), `attest show/list/export`, `verify-attestation` alias, `run-all` alias, `framework-gap`, `report executive`, `validate-rfcs`, `ai-run` streaming JSONL (strict in-order assertion across all nine frames), `ci --max-rwep`, `ci --block-on-jurisdiction-clock`, `ci --evidence-dir`, `run --vex`, `run --diff-from-latest`, `run --force-stale`, `run --air-gap`, `run --session-key` (HMAC), and `refresh --indexes-only`.
+
+Eight predeploy-gate meta-tests in `tests/predeploy-gates.test.js` stage known-bad state in tempdirs and assert each gate fires: verify-signatures (byte-flipped signature), lint-skills (missing required section), validate-catalog-meta (malformed `tlp`), sbom-currency (drift), validate-indexes (out-of-date entry), validate-vendor (modified vendored file), validate-package (missing file-allowlist entry), verify-shipped-tarball (skill body tampered post-signing — the v0.11.x→v0.12.4 regression class). Gate 10's inline `node -e` checker extracted to `scripts/check-sbom-currency.js` for testability; no behavior change.
+
+Twelve new e2e scenarios in `tests/e2e-scenarios/09-secrets-aws-key` through `20-ai-api-openai-dotfile` exercise the twelve playbooks previously without e2e coverage (`secrets`, `kernel`, `library-author`, `crypto-codebase`, `mcp`, `framework`, `cred-stores`, `containers`, `runtime`, `hardening`, `crypto`, `ai-api`). All twenty scenarios pass via `npm run test:e2e`.
+
+### Repository
+
+Dependabot grouping config added for the github-actions ecosystem: weekly version-update bumps now land as a single grouped PR instead of N parallel PRs against the same 14-gate CI matrix. Security-updates stay ungrouped so a single-action CVE surfaces as its own PR.
+
+Test count: 386 → 418 (388 + 31 cli-coverage − accounting note: 8 predeploy-gates + 12 diff-coverage tests landed alongside the +31 CLI surface tests; some pre-existing tests resolved into fewer counted tests on suite reorganization). Predeploy gates: 14 → 15.
+
 ## 0.12.7 — 2026-05-13
 
 **Patch: two follow-on fixes to v0.12.6.**

package/bin/exceptd.js

@@ -378,27 +378,29 @@ function main() {
     process.exit(0);
   }
 
+  // v0.12.8: emit the deprecation banner BEFORE branching on PLAYBOOK_VERBS
+  // so that legacy aliases routed through STANDALONE_VERBS or the orchestrator
+  // (scan, dispatch, currency, verify, validate-cves, validate-rfcs,
+  // watchlist, prefetch, build-indexes) also surface the rename.
+  // Previously the banner only fired for PLAYBOOK_VERBS-resident aliases
+  // (plan, govern, direct, look, ingest, reattest, list-attestations).
+  if (LEGACY_VERB_REPLACEMENTS[cmd] && !process.env.EXCEPTD_DEPRECATION_SHOWN) {
+    const ver = readPkgVersion();
+    const haveBrief = ver !== "unknown" && ver.match(/^(\d+)\.(\d+)/) && (parseInt(RegExp.$1, 10) > 0 || parseInt(RegExp.$2, 10) >= 11);
+    process.stderr.write(
+      `[exceptd] DEPRECATION: \`${cmd}\` is a v0.10.x verb. ` +
+      (haveBrief
+        ? `Prefer \`${LEGACY_VERB_REPLACEMENTS[cmd]}\` (available in this install, v${ver}). `
+        : `Upgrade to v0.11.0+ then use \`${LEGACY_VERB_REPLACEMENTS[cmd]}\` (currently installed: v${ver}). `) +
+      `Legacy verbs remain functional through this release; they will be removed in v0.13. ` +
+      `Suppress: export EXCEPTD_DEPRECATION_SHOWN=1.\n`
+    );
+    process.env.EXCEPTD_DEPRECATION_SHOWN = "1";
+  }
+
   // Seven-phase playbook verbs run in-process — they emit JSON to stdout
   // rather than dispatch to a script.
   if (PLAYBOOK_VERBS.has(cmd)) {
-    // One-time deprecation banner per process when a legacy verb is invoked.
-    if (LEGACY_VERB_REPLACEMENTS[cmd] && !process.env.EXCEPTD_DEPRECATION_SHOWN) {
-      // Mention the installed version explicitly so an operator on v0.10.x
-      // who reads "Prefer brief..." doesn't go looking for a verb that
-      // doesn't exist in their install. v0.11.0+ has the replacement; v0.10.x
-      // users see this with the explicit "upgrade to v0.11.0 first" note.
-      const ver = readPkgVersion();
-      const haveBrief = ver !== "unknown" && ver.match(/^(\d+)\.(\d+)/) && (parseInt(RegExp.$1, 10) > 0 || parseInt(RegExp.$2, 10) >= 11);
-      process.stderr.write(
-        `[exceptd] DEPRECATION: \`${cmd}\` is a v0.10.x verb. ` +
-        (haveBrief
-          ? `Prefer \`${LEGACY_VERB_REPLACEMENTS[cmd]}\` (available in this install, v${ver}). `
-          : `Upgrade to v0.11.0+ then use \`${LEGACY_VERB_REPLACEMENTS[cmd]}\` (currently installed: v${ver}). `) +
-        `Legacy verbs remain functional through this release; they will be removed in v0.13. ` +
-        `Suppress: export EXCEPTD_DEPRECATION_SHOWN=1.\n`
-      );
-      process.env.EXCEPTD_DEPRECATION_SHOWN = "1";
-    }
     dispatchPlaybook(cmd, rest);
     return;
   }
@@ -798,10 +800,24 @@ Flags:
                           (code 2) when phases.detect.classification === 'detected'
                           OR phases.analyze.rwep.adjusted >= rwep_threshold.escalate.
                           Logs PASS/FAIL reason to stderr.
-  --session-id <id>       Reuse a specific session ID.
+  --upstream-check        (v0.11.14) Opt-in: query npm registry for the latest
+                          published @blamejs/exceptd-skills version before
+                          detect. Warns to stderr (no exit-code change) when
+                          the local install is behind, so an operator using a
+                          stale catalog finds out before the run completes.
+  --strict-preconditions  Escalate warn-level precondition failures to halt.
+                          Without this flag, only on_fail=halt preconditions
+                          block; warn-level surface in stderr but the run
+                          proceeds. With it, any precondition_check returning
+                          false fails the run and exits non-zero.
+  --session-id <id>       Reuse a specific session ID. Collisions refused
+                          unless --force-overwrite is also passed.
+  --force-overwrite       Override the session-id collision refusal.
   --session-key <hex>     HMAC sign the evidence_package with this key.
+                          Output carries an 'hmac' field the verifier can check.
   --force-stale           Override the threat_currency_score < 50 hard-block.
-  --air-gap               Honor air_gap_alternative paths.
+  --air-gap               Honor air_gap_alternative paths in look.artifacts[]
+                          and skip the network-touching collection variants.
   --pretty                Indented JSON output.
 
 Attestation is persisted to .exceptd/attestations/<session_id>/ on every
@@ -835,12 +851,22 @@ newest-first, with truncated evidence_hash + capture timestamp + file path.`,
 
 Subverbs:
   attest show <sid>       Emit the full (unredacted) attestation.
+  attest list             Inventory every prior attestation under
+                          ~/.exceptd/attestations/ (or EXCEPTD_HOME when set).
+                          Filter with --playbook <id> or --since <ISO>. Newest
+                          first; truncated evidence_hash + capture timestamp +
+                          path per entry.
   attest export <sid>     Emit redacted JSON suitable for audit submission.
                           Strips raw artifact values; preserves evidence_hash,
                           signature, classification, RWEP, remediation choice.
-                          --format csaf wraps the export in a CSAF envelope.
+                          --format <csaf|sarif|openvex> wraps the export in the
+                          named envelope (default: redacted JSON).
   attest verify <sid>     Verify .sig sidecar against keys/public.pem.
                           Reports tamper status per attestation file.
+  attest diff <sid>       Diff <sid> against the most-recent prior attestation
+                          for the same playbook, or against --against <other-sid>
+                          for an explicit pair. Reports unchanged | drifted |
+                          resolved per evidence_hash + classification deltas.
 
 All subverbs honor --pretty for indented JSON output.`,
     discover: `discover — context-aware playbook recommender (v0.11.0).
@@ -867,7 +893,20 @@ Subchecks:
   --currency              Skill currency report (last_threat_review).
   --cves                  CVE catalog validation (offline view).
   --rfcs                  RFC catalog validation (offline view).
-  (no flag)               All four, plus signing-status (private key presence).
+  --registry-check        (v0.11.14) Opt-in: query the npm registry for the
+                          latest published version + days-since-publish.
+                          Surfaces under checks.registry.{local_version,
+                          published_version, same, behind, days_since_latest_publish}.
+                          Off by default — keeps doctor offline-clean unless
+                          asked.
+  --fix                   (v0.12.5) Attempt to auto-remediate detected gaps.
+                          Currently scoped to: regenerate the local Ed25519
+                          private key when keys/public.pem exists but
+                          .keys/private.pem is absent. Does NOT modify any
+                          file outside .keys/.
+  (no flag)               All four subchecks above (sans --registry-check
+                          unless explicitly requested), plus signing-status
+                          (private key presence under .keys/).
 
 Flags:
   --json                  Emit JSON (default is human-readable text).
@@ -914,6 +953,9 @@ exit-code contract designed for one-line .github/workflows entries.
 Flags:
   --all                   Run every playbook.
   --scope <type>          Filter: system | code | service | cross-cutting.
+  --required <ids>        Comma-separated playbook ids that MUST run, even if
+                          scope-detection would exclude them. Fails if a
+                          required id is unknown.
   (no flag)               Auto-detect scopes from cwd (same logic as run).
   --evidence <file>       Submission bundle (multi-playbook shape).
   --evidence-dir <dir>    Read <playbook-id>.json files from a directory.
@@ -921,11 +963,77 @@ Flags:
   --block-on-jurisdiction-clock
                           Fail when any close.notification_actions started a
                           regulatory clock (GDPR 72h, HIPAA breach, etc.).
-  --pretty                Indented JSON output.
+  --format <fmt>          Output shape. Supported: json (default, single-line),
+                          summary (5-field digest), markdown (human digest).
+                          Bundles (csaf-2.0/sarif/openvex) live on per-run
+                          attestations, not the aggregate ci verdict.
+  --json                  Force single-line JSON (overrides any TTY heuristics).
+  --pretty                Indented JSON output (implies --json).
+
+Exit codes:
+  0  PASS                  All scoped playbooks ran and verdict is clean.
+  1  Framework error       Runner threw, unreadable evidence, etc.
+  2  FAIL (detected)       At least one playbook returned
+                           classification=detected, OR rwep ≥ escalate, OR
+                           --max-rwep cap exceeded.
+  3  Ran-but-no-evidence   Every result was inconclusive AND no evidence was
+                           submitted (visibility gap — CI should fail loud).
+  4  Blocked               Result returned ok:false (preflight halt, missing
+                           preconditions with on_fail=halt, etc.) OR
+                           --block-on-jurisdiction-clock fired.
 
-Exit codes: 0 PASS, 2 FAIL (detected | rwep ≥ cap | clock started w/ block flag).
 Output: verb, session_id, playbooks_run, summary{total, detected,
-max_rwep_observed, jurisdiction_clocks_started, verdict}, results[].`,
+max_rwep_observed, jurisdiction_clocks_started, verdict, fail_reasons[]},
+results[].`,
+    brief: `brief [playbook] — unified info doc (v0.11.0).
+
+Collapses the three info-only phases plan + govern + direct + look into a
+single document. Phases 1-3 of the seven-phase contract are entirely
+informational; brief reads them in one CLI invocation instead of three.
+
+Modes:
+  brief                   Auto-detect playbooks for the cwd. Returns a list.
+  brief <playbook>        Single-playbook brief with jurisdiction obligations
+                          + threat context + preconditions + artifacts +
+                          indicators.
+  brief --all             Every shipped playbook.
+  brief --scope <type>    Filter: system | code | service | cross-cutting.
+  brief <pb> --phase <p>  Emit only the named phase (govern | direct | look).
+                          Compat for legacy callers.
+
+Flags:
+  --directives            Expand directive metadata per playbook.
+  --pretty                Indented JSON output.
+  --json                  Force single-line JSON.
+
+Output (single-playbook): playbook_id, directives[], jurisdiction_obligations[],
+threat_context, preconditions[], artifacts[], indicators[].`,
+    lint: `lint <playbook> <evidence-file> — pre-flight check submission shape.
+
+Validates the submission JSON against the playbook's expected indicators /
+preconditions / artifacts WITHOUT executing detect/analyze/validate/close.
+Lets the AI iterate on its evidence before going through phases 4-7.
+
+Args / flags:
+  <playbook>              Playbook id. Required.
+  <evidence-file>         Submission JSON path. Required.
+  --pretty                Indented JSON output.
+
+Output categories: ok, missing_required, missing_required_artifact,
+unknown_keys, type_mismatch, suggestions.`,
+    "verify-attestation": `verify-attestation <session-id> — alias for \`attest verify\`.
+
+See \`exceptd attest --help\` for the full attest verb. This alias matches
+the historical verify-attestation entry-point name used by some downstream
+consumers.
+
+Flags: --pretty.`,
+    "run-all": `run-all — alias for \`run --all\`.
+
+Identical exit-code and output contract as \`run --all\`. Maintained for
+operators who script the verb form rather than the flag.
+
+See \`exceptd run --help\` for the full flag list.`,
   };
   process.stdout.write((cmds[verb] || `${verb} — no per-verb help available; see \`exceptd help\` for the full list.`) + "\n");
 }
@@ -1562,13 +1670,20 @@ function cmdRun(runner, args, runOpts, pretty) {
 
     emit(result, pretty);
 
+    // v0.12.8: use process.exitCode + return instead of process.exit() so
+    // buffered async stdout (which `emit` writes to) is allowed to drain
+    // before the event loop ends. v0.11.10 (#100) is the canonical class:
+    // process.exit(N) immediately after a stdout write can truncate output
+    // under piped consumers (CI runners, jq, test harnesses).
     if (classification === "detected") {
       process.stderr.write(`[exceptd run --ci] FAIL: classification=detected rwep=${adjusted} threshold=${threshold}\n`);
-      process.exit(2);
+      process.exitCode = 2;
+      return;
     }
     if (classification === "inconclusive" && escalate) {
       process.stderr.write(`[exceptd run --ci] FAIL: classification=inconclusive AND rwep=${adjusted} >= threshold=${threshold}\n`);
-      process.exit(2);
+      process.exitCode = 2;
+      return;
     }
     if (classification === "inconclusive") {
       process.stderr.write(`[exceptd run --ci] PASS+WARN: classification=inconclusive rwep=${adjusted} < threshold=${threshold} (visibility gap)\n`);
@@ -1798,9 +1913,10 @@ function cmdRunMulti(runner, ids, args, runOpts, pretty, meta) {
   // v0.11.9 (#100): cmdRunMulti exits non-zero when any individual run
   // returned ok:false. Pre-0.11.9 the aggregate result had {ok:false} in
   // the body but exit code stayed 0 — CI gates couldn't distinguish "ran
-  // clean" from "blocked." Now matches cmdRun's single-playbook contract.
+  // clean" from "blocked." v0.12.8: use exitCode (not process.exit()) so
+  // the aggregate JSON emitted above is allowed to fully drain.
   const anyBlocked = results.some(r => r.ok === false);
-  if (anyBlocked) process.exit(1);
+  if (anyBlocked) { process.exitCode = 1; return; }
 }
 
 function cmdIngest(runner, args, runOpts, pretty) {
@@ -1835,28 +1951,38 @@ function cmdIngest(runner, args, runOpts, pretty) {
 
   const result = runner.run(playbookId, directiveId, cleanedSubmission, runOpts);
 
+  // v0.12.8: route ingest's attestation persistence through persistAttestation
+  // — the same path cmdRun + cmdRunMulti use — so the session-id collision
+  // refusal AND the Ed25519 sidecar signing both apply. Pre-v0.12.8 ingest
+  // had its own inline writeFileSync with neither check, meaning two ingest
+  // calls with the same session-id silently clobbered the audit trail and no
+  // .sig sidecar was written.
   if (result && result.ok && result.session_id) {
-    try {
-      const dir = path.join(resolveAttestationRoot(runOpts), result.session_id);
-      fs.mkdirSync(dir, { recursive: true });
-      fs.writeFileSync(
-        path.join(dir, "attestation.json"),
-        JSON.stringify({
-          session_id: result.session_id,
-          playbook_id: result.playbook_id,
-          directive_id: result.directive_id,
-          evidence_hash: result.evidence_hash,
-          submission: cleanedSubmission,
-          run_opts: { airGap: runOpts.airGap, forceStale: runOpts.forceStale, mode: runOpts.mode },
-          captured_at: new Date().toISOString(),
-        }, null, 2)
-      );
-    } catch { /* non-fatal */ }
+    const persisted = persistAttestation({
+      sessionId: result.session_id,
+      playbookId: result.playbook_id,
+      directiveId: result.directive_id,
+      evidenceHash: result.evidence_hash,
+      operator: runOpts.operator,
+      operatorConsent: runOpts.operator_consent,
+      submission: cleanedSubmission,
+      runOpts,
+      forceOverwrite: !!args["force-overwrite"],
+      filename: "attestation.json",
+    });
+    if (!persisted.ok) {
+      // Surface the collision; do not silently clobber.
+      return emitError(persisted.error, { session_id: result.session_id, existing_path: persisted.existingPath }, pretty);
+    }
+    if (persisted.prior_session_id) {
+      result.attestation_persist = { ok: true, prior_session_id: persisted.prior_session_id, overwrote_at: persisted.overwrote_at };
+    }
   }
 
   if (result && result.ok === false) {
     process.stderr.write((pretty ? JSON.stringify(result, null, 2) : JSON.stringify(result)) + "\n");
-    process.exit(1);
+    process.exitCode = 1;
+    return;
   }
   emit(result, pretty);
 }
@@ -3196,13 +3322,22 @@ function cmdAiRun(runner, args, runOpts, pretty) {
   let handled = false;
   let buf = "";
 
+  // v0.12.8: every writeLine() in this handler writes to stdout. Replacing
+  // process.exit() with exitCode + closing stdin lets the JSONL frames
+  // drain before the event loop ends. `handled` plus process.stdin.pause()
+  // prevents further callbacks from re-entering the handler.
+  const finish = (code) => {
+    process.exitCode = code;
+    try { process.stdin.pause(); } catch { /* non-fatal */ }
+  };
   const handleLine = (line) => {
     if (handled) return;
     let parsed;
     try { parsed = JSON.parse(line); }
     catch (e) {
+      handled = true;
       writeLine({ event: "error", reason: `invalid JSON on stdin: ${e.message}`, line_preview: line.slice(0, 120) });
-      process.exit(1);
+      return finish(1);
     }
     if (!parsed || parsed.event !== "evidence" || !parsed.payload) {
       // Ignore non-evidence chatter so the host AI can interleave its own
@@ -3216,18 +3351,18 @@ function cmdAiRun(runner, args, runOpts, pretty) {
       result = runner.run(playbookId, directiveId, submission, runOpts);
     } catch (e) {
       writeLine({ event: "error", reason: `runner threw: ${e.message}` });
-      process.exit(1);
+      return finish(1);
     }
     if (!result || result.ok === false) {
       writeLine({ event: "error", reason: result?.reason || "runner returned ok:false", result });
-      process.exit(1);
+      return finish(1);
     }
     writeLine({ phase: "detect", ...result.phases?.detect });
     writeLine({ phase: "analyze", ...result.phases?.analyze });
     writeLine({ phase: "validate", ...result.phases?.validate });
     writeLine({ phase: "close", ...result.phases?.close });
     writeLine({ event: "done", ok: true, session_id: result.session_id, evidence_hash: result.evidence_hash });
-    process.exit(0);
+    return finish(0);
   };
 
   // Handle empty/closed stdin: emit a hint then exit cleanly so AI agents
@@ -3235,7 +3370,8 @@ function cmdAiRun(runner, args, runOpts, pretty) {
   // a hung process.
   if (process.stdin.isTTY) {
     writeLine({ event: "error", reason: "ai-run streaming mode requires evidence on stdin; pipe {\"event\":\"evidence\",\"payload\":{...}} or use --no-stream." });
-    process.exit(1);
+    process.exitCode = 1;
+    return;
   }
 
   process.stdin.on("data", (chunk) => {
@@ -3270,7 +3406,8 @@ function cmdAiRun(runner, args, runOpts, pretty) {
         } catch { /* fall through to error */ }
       }
       writeLine({ event: "error", reason: "stdin closed without an evidence event. Pipe `{\"event\":\"evidence\",\"payload\":{...}}` for streaming mode, or pass --no-stream + --evidence <file> for single-shot." });
-      process.exit(1);
+      process.exitCode = 1;
+      return;
     }
   });
 

package/data/_indexes/_meta.json

@@ -1,58 +1,58 @@
 {
   "schema_version": "1.1.0",
-  "generated_at": "2026-05-13T04:36:48.434Z",
+  "generated_at": "2026-05-13T13:59:56.237Z",
   "generator": "scripts/build-indexes.js",
   "source_count": 49,
   "source_hashes": {
-    "manifest.json": "d3272a211860b1c978ec1a3dbacbb859944a4ca5fe88a0c9ac86982dc2be1bca",
-    "data/atlas-ttps.json": "1500b5830dab070c4252496964a8c0948e1052a656e2c7c6e1efaf0350645e13",
+    "manifest.json": "0c902335db71d5fc3851d661ef93e39d5e0abf987166efd916fe1f6c24db448e",
+    "data/atlas-ttps.json": "f3f75ff2778a0a2c7d953a21386bc4f265cb2685ce41242eee45f9e9f2a6add6",
     "data/cve-catalog.json": "a2557e66c00334f9b2b07f7d1320a27fb0f82243f2ff199c4a39bf2933be5216",
-    "data/cwe-catalog.json": "c3367d469b4b3d31e4c56397dd7a8305a0be338ecd85afa27804c0c9ce12157b",
-    "data/d3fend-catalog.json": "b5cd14669e2a931d0df81bb8402f3c8ac08b0d2613e595eaecd8cc4631a57587",
+    "data/cwe-catalog.json": "68e22967d39a9e22b82d7ac676125f829b551b2c2f3a9c564d3d942bf4ee6ecb",
+    "data/d3fend-catalog.json": "d219520c8d3eb61a270b25ea60f64721035e98a8d5d51d1a4e1f1140d9a586f9",
     "data/dlp-controls.json": "8ea8d907aea0a2cfd772b048a62122a322ba3284a5c36a272ad5e9d392564cb5",
     "data/exploit-availability.json": "7dad52f459c324c40aa4df7cd9157f6a19f670fdfb9d8f687d777c9d99798668",
-    "data/framework-control-gaps.json": "25db4d0cc9e6242e1143494178393ae8eab3384672ca0d685bd55c537f028c83",
+    "data/framework-control-gaps.json": "8804a10bf77e987453ea76ae717153118dc5cc625f42e98f78213b08fa144f73",
     "data/global-frameworks.json": "84fd19061f052e4ccf66308a7b8d3fd38e00325e97e9e5e19e4d9b302c128957",
-    "data/rfc-references.json": "23ffeb970af5403e9a733844dcea9b45cbae689623085f030dec826c492682e3",
+    "data/rfc-references.json": "583360bae01e324d752bd28a7d344b4276478381426428d683fc82b0ac19d64a",
     "data/zeroday-lessons.json": "0840eacd580d4ee5bd7dc44ccea6d52bfa95096576af0ccf67132eea05bedd55",
-    "skills/kernel-lpe-triage/skill.md": "c00e0a77e8b7b1a1ebcb7267dd728b39ec2671d1260bf4f6a4842f10101a69b0",
-    "skills/ai-attack-surface/skill.md": "3f5c59f1823f1552efe8a5cb32656d34d6407609ddaa1eed254c263864563453",
-    "skills/mcp-agent-trust/skill.md": "716d0d65499f8be21e0389a06a1fcaf6abd1cd2e90f068cab54471dd67127f74",
+    "skills/kernel-lpe-triage/skill.md": "e8b8601cd3b66d25150bf17f2edd2ef18f10ca6d81ee62aaf874432ee5bdc4b3",
+    "skills/ai-attack-surface/skill.md": "30003e515a32a6314e4a72c12b8376c52e0dd85b4e36e7957c30cabbd46c8837",
+    "skills/mcp-agent-trust/skill.md": "cd48cbf5a9c9795db525acea970db0c171cf9da4211bd07971b5132a1cde485c",
     "skills/framework-gap-analysis/skill.md": "86c86761b91d04bcd1ec684fb3d65cf5c2881fde59b03d33fa59baddbbf64d31",
     "skills/compliance-theater/skill.md": "dda149e69fcd92d913f3f6be4aa1aba8fe85a2b408b88c052c71174b2e0e918c",
     "skills/exploit-scoring/skill.md": "993dbd4417018e5d20edb31ff2296b92b65fff42d2acde722c05e0be7994ddbe",
-    "skills/rag-pipeline-security/skill.md": "6274bbac1fbd164123f4d57a49c5cc7429846b7452ea476095e9dc846fdc2c42",
-    "skills/ai-c2-detection/skill.md": "afe4258fa03e3fd81ca4bb7b348cb483585eb129ebae811457810b5290080793",
+    "skills/rag-pipeline-security/skill.md": "cb31137b62c34905b633a10e4a9bcc6dcccc7448f254e63d7203ee7f7b469a03",
+    "skills/ai-c2-detection/skill.md": "ff5fc781d8768a81b980566d1b8b56299cdbb61a56ff24b30b459c7c0ee95464",
     "skills/policy-exception-gen/skill.md": "6a18b1ecd342dd792e03fcadaed3aa846192f2408c21c79d98eadd431e1619e1",
     "skills/threat-model-currency/skill.md": "afa24a1d04202a384374598ea2d924cdaa52e264b9552bae1ace88fd39d6c0e8",
     "skills/global-grc/skill.md": "a9f4477368e260609793b77275e65e255b5c8067b7ae777047a70f3edb373e50",
     "skills/zeroday-gap-learn/skill.md": "b101815b1c55e95706d72d31eb88153a92f41a748a86e111ad1ac06b9c676548",
     "skills/pqc-first/skill.md": "5b4300d71890c16b1de31d380859babaa3631729cedb0c0a397a1ff097524773",
-    "skills/skill-update-loop/skill.md": "c8bfea03c60403fb26e3ab7e07406660ef148bece9e12f9149b5171033cf5e22",
-    "skills/security-maturity-tiers/skill.md": "931d6144048308124930e8036d8e74931ca176f7315e110d33fb30880d2f5367",
+    "skills/skill-update-loop/skill.md": "f48c40e0f2a893d5877b73159218d007b0f5f9295e591cbc3323745899fb3481",
+    "skills/security-maturity-tiers/skill.md": "b4c8eb22d705d36ff863a431df7406096d294dda3c8c3037aa7ad025b47ddb5a",
     "skills/researcher/skill.md": "40de9c281ea82e92b21856b5dde15609f187d8cddc7e4116886ac0fff9d0e269",
-    "skills/attack-surface-pentest/skill.md": "f639b6d9c19def5908eddbbb79f0514e168e74661c0894b737d7c76cbb550841",
+    "skills/attack-surface-pentest/skill.md": "40f5a6a6c80e6084a1c09fb0085d0083f4970385bf76098015e57fc17ad7b326",
     "skills/fuzz-testing-strategy/skill.md": "83b1929a0d1e09a58908b91125ebc91ff14323ab9acc9bab6c4b04903b69b837",
-    "skills/dlp-gap-analysis/skill.md": "041c4c6a5299057383b1d6bd4328c1ef578f8c5c6bade8750d339c7b51020027",
-    "skills/supply-chain-integrity/skill.md": "94527929c150bf9bc7a5a61a596373d49a88ae9114adf841b2d3771e25fb8d51",
-    "skills/defensive-countermeasure-mapping/skill.md": "634f0805597a0ab417248a7413eed39b08afbc820e7c6bd257eebaa663d8990d",
-    "skills/identity-assurance/skill.md": "e8f3958ef8dd89f9276f2a62a0a1b418a206a3312bb8ff228729c8f358603dc7",
-    "skills/ot-ics-security/skill.md": "7c6eb389e7ace5b2c6e092f8dfcf4795ce1b0aefaa2738c6e383cb0fef4d6287",
-    "skills/coordinated-vuln-disclosure/skill.md": "22ba9ee01252274b1e4aa1238468415c6f564eca319c601de588fbcdd1bea3bb",
-    "skills/threat-modeling-methodology/skill.md": "9e1ee084a56f837074a41b7a7929b1deb5619bb483485aa066b0c26990fe70db",
-    "skills/webapp-security/skill.md": "10a17ab8d3f0e9b1107f7bed5ff2881f59234592b57f2a52c8c397d711604ffb",
-    "skills/ai-risk-management/skill.md": "6062be4e748606ca7536bba3d87e25716795d5690a0063f188325e8e68291cb6",
-    "skills/sector-healthcare/skill.md": "01dd58ed20b3f97dc240e1b77a522f780bd9428294ac9ac78d51817150b55476",
-    "skills/sector-financial/skill.md": "52bdf30cece82381ea8a4023838aa61a2b9026f315a1356aabb638e49bf7b6d9",
-    "skills/sector-federal-government/skill.md": "e1443a3f788050fd5d63d001a3aafbd3244280399ccdec595d7807de547614d4",
-    "skills/sector-energy/skill.md": "068996fa85cc9d8d7f890b185a38619602cb3bab89704d3bfc85c99cbddaafb8",
-    "skills/api-security/skill.md": "131de2913341f794585091b72522b0e0b8d7dd42eca4faf8ea7315d27b5a5c6f",
-    "skills/cloud-security/skill.md": "26e533f5fa4876cb611cfa026fb7e6417927dd4c2e04f50e42fc08016c40274b",
-    "skills/container-runtime-security/skill.md": "7c62132c189edfe0e803c1cc2a688cef7b6ddd2d3be8c5d74a807293f14e0790",
-    "skills/mlops-security/skill.md": "78bb564f841f2c60ea48790ba686ba1e3f628afd402c96847177cc7e05fba4de",
-    "skills/incident-response-playbook/skill.md": "ede731be2bd673d65a8b7509ca3e2eb9af800186780a99c0369e15b2459d7cb6",
-    "skills/email-security-anti-phishing/skill.md": "9dfc1ca36f3059bb8f1cbc566d1358d1c797bb8f51d7bd62a70df8505563ab23",
-    "skills/age-gates-child-safety/skill.md": "f477320c9727986a44f38dc470e61a2c50bf9eef0a6a4c4ab1f14462dfa94f73"
+    "skills/dlp-gap-analysis/skill.md": "61149c692de109d5cfd00cada60478539f28374380b5ce17017603d71967ab58",
+    "skills/supply-chain-integrity/skill.md": "961eb734df9965fa726720ac9f849bdcdc32108625d1d589602005967b836ea8",
+    "skills/defensive-countermeasure-mapping/skill.md": "e62c71ba3be2b4d0f7dfa529fec007cba6bee3013f76b93756e3e6310f2d22ab",
+    "skills/identity-assurance/skill.md": "a4aff24b0d0f4684d144f85cbc74c8a9a5711a7ec9c6d473f677f053dc1c658c",
+    "skills/ot-ics-security/skill.md": "500a002b662217393243d093efa639cdf30ca76d1869d6c1896425492c5d652e",
+    "skills/coordinated-vuln-disclosure/skill.md": "c96fd2254abf8a29819f8175da85094bea1afe589fecc92abcf1289b30895030",
+    "skills/threat-modeling-methodology/skill.md": "eb03a6c12c637c38917fecd97007459dfe99cbab5dfae696a736f08db13c124c",
+    "skills/webapp-security/skill.md": "009d9050e3c27f789efbc4c0dba4245b66d49182b503736be6a344591ba93f54",
+    "skills/ai-risk-management/skill.md": "1bbdba6b46efba8c88f8e7e1930777d39a65709ea434b6a53eed01814fa9fdad",
+    "skills/sector-healthcare/skill.md": "43608ca43eefc3a9238f6c6b0c7993e519420ffab5a18d96e17310f44ac6225a",
+    "skills/sector-financial/skill.md": "d7b538cd71a8384c9e19a86e7971049f2c1f651677e4ab9b5a1caf9526b178da",
+    "skills/sector-federal-government/skill.md": "0d18ede4d0c04975ea22bfa53b0f6d62eeb70861e16a27d239d25928fa3ff21f",
+    "skills/sector-energy/skill.md": "07ca8b582b3a94657006395ce0ef15ecb2030f676f119900b4fdb9b213f04200",
+    "skills/api-security/skill.md": "99af9882f57e884b3f66f1c17a4bc6ee24ed6531f0e28b3bdeccd5d77429ffa6",
+    "skills/cloud-security/skill.md": "18fc0f16689f3560023c9d919bec03070d3c2198dc186d1b7ca9cfe35fbfa108",
+    "skills/container-runtime-security/skill.md": "f481878aa40c42662424d32b320fc825e2550b7874224765e2150a97f0afeafb",
+    "skills/mlops-security/skill.md": "c9fb9281191b2684424f96b3d4447fe40907f633b0506e22100d909141f497be",
+    "skills/incident-response-playbook/skill.md": "27202d956fcc06c0cef7ad1ca6f352e2cdf06189516e22f796704a44c2ab2734",
+    "skills/email-security-anti-phishing/skill.md": "90e15fb89a36ac704cb092801130351a5c33bb7154bd023a347309c1a6a4f164",
+    "skills/age-gates-child-safety/skill.md": "c741d7dca9da0abb09bdebb8a02e803ce4ae9fb9a6904fb8df3ec19cae83917d"
   },
   "skill_count": 38,
   "catalog_count": 10,
@@ -68,12 +68,12 @@
     },
     "trigger_table_entries": 453,
     "chains_cve_entries": 6,
-    "chains_cwe_entries": 34,
+    "chains_cwe_entries": 51,
     "jurisdictions_indexed": 29,
     "handoff_dag_nodes": 38,
     "summary_cards": 38,
     "section_offsets_skills": 38,
-    "token_budget_total_approx": 334832,
+    "token_budget_total_approx": 337096,
     "recipes": 8,
     "jurisdiction_clocks": 29,
     "did_ladders": 8,