@blamejs/exceptd-skills 0.12.8 → 0.12.10

package/AGENTS.md

@@ -46,7 +46,7 @@ Also read [CONTEXT.md](CONTEXT.md) for a complete orientation to the skill syste
 
     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.
+    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.
 
 ---
 
@@ -97,7 +97,7 @@ Schema reference: `lib/schemas/playbook.schema.json`. Reference playbook (read t
 
 Each playbook's `_meta.feeds_into[]` declares downstream playbooks the host AI should consider chaining into after this run, and the condition that fires the chain. The condition expressions evaluate at `close()` against `analyze` + `validate` + `agentSignals` context. AI assistants surface the suggested next playbook to the operator but never auto-execute; the operator decides.
 
-The current (v0.10.x) matrix:
+The current matrix:
 
 | From | Triggers | To | Why |
 |---|---|---|---|

package/ARCHITECTURE.md

@@ -161,7 +161,7 @@ Schema per entry:
 
 ### `data/global-frameworks.json`
 
-Maps jurisdiction to framework to current coverage and lag assessment. Currently covers 22+ jurisdictions (expanding to 29+ as deferred jurisdiction agents land) including EU member states, UK, AU, SG, IN, JP, CA, and major sectoral regulators (DORA, NIS2, EU AI Act, EU CRA at the EU layer; APRA CPS 234, MAS TRM, CERT-In, SEBI, OSFI B-10 at the national layer). See schema in file.
+Maps jurisdiction to framework to current coverage and lag assessment. Currently covers 35 jurisdictions including EU member states, UK, AU, SG, IN, JP, CA, and major sectoral regulators (DORA, NIS2, EU AI Act, EU CRA at the EU layer; APRA CPS 234, MAS TRM, CERT-In, SEBI, OSFI B-10 at the national layer). See schema in file.
 
 ### `data/zeroday-lessons.json`
 
@@ -173,23 +173,23 @@ Tracks PoC status, weaponization stage, and AI-assist factor per CVE. Updated wh
 
 ### `data/cwe-catalog.json`
 
-30 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.
+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.
 
 `_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`.
 
 ### `data/d3fend-catalog.json`
 
-21 MITRE D3FEND defensive technique entries pinned to **D3FEND v1.0.0**. Each entry records the defensive technique ID (e.g., `D3-EAL` Executable Allowlisting), the tactic / artifact it defends, the offensive ATLAS / ATT&CK TTPs it counters, defense-in-depth layer position, least-privilege scope assumptions, zero-trust posture compatibility, and AI-pipeline applicability per Hard Rule #9. Skills cite D3FEND IDs in `d3fend_refs` to map offensive findings to a defensive countermeasure rather than to abstract control language. The `defensive-countermeasure-mapping` skill is the canonical consumer; any skill shipped on or after 2026-05-11 includes a Defensive Countermeasure Mapping section referencing this catalog.
+28 MITRE D3FEND defensive technique entries pinned to **D3FEND v1.0.0**. Each entry records the defensive technique ID (e.g., `D3-EAL` Executable Allowlisting), the tactic / artifact it defends, the offensive ATLAS / ATT&CK TTPs it counters, defense-in-depth layer position, least-privilege scope assumptions, zero-trust posture compatibility, and AI-pipeline applicability per Hard Rule #9. Skills cite D3FEND IDs in `d3fend_refs` to map offensive findings to a defensive countermeasure rather than to abstract control language. The `defensive-countermeasure-mapping` skill is the canonical consumer; any skill shipped on or after 2026-05-11 includes a Defensive Countermeasure Mapping section referencing this catalog.
 
 `_meta.d3fend_version` pins the version; D3FEND ontology additions are tracked in skill `forward_watch` fields.
 
 ### `data/rfc-references.json`
 
-19 IETF RFC / Internet-Draft references covering authentication and authorization (OAuth 2.0 Security BCP RFC 9700, JWT BCP, FIDO/WebAuthn-related drafts), cryptography (TLS 1.3 RFC 8446, hybrid PQC drafts), disclosure (security.txt RFC 9116), and adjacent IETF standards skills depend on. Each entry tracks: title, status (Proposed Standard / Best Current Practice / Internet-Draft / Historic), errata count, replaces / replaced-by chains, IESG / IRTF stream, and a `last_verified` date. Skills cite RFC IDs in `rfc_refs`. Per Hard Rule #12, RFC references are version-pinned: when an RFC is obsoleted or a draft is published as an RFC, the catalog entry's `replaced_by` field is updated, `last_verified` is refreshed, and affected skills bump `last_threat_review`. Frameworks lag RFCs; RFCs lag attacker innovation — this catalog makes that middle layer auditable.
+31 IETF RFC / Internet-Draft references covering authentication and authorization (OAuth 2.0 Security BCP RFC 9700, JWT BCP, FIDO/WebAuthn-related drafts), cryptography (TLS 1.3 RFC 8446, hybrid PQC drafts), disclosure (security.txt RFC 9116), and adjacent IETF standards skills depend on. Each entry tracks: title, status (Proposed Standard / Best Current Practice / Internet-Draft / Historic), errata count, replaces / replaced-by chains, IESG / IRTF stream, and a `last_verified` date. Skills cite RFC IDs in `rfc_refs`. Per Hard Rule #12, RFC references are version-pinned: when an RFC is obsoleted or a draft is published as an RFC, the catalog entry's `replaced_by` field is updated, `last_verified` is refreshed, and affected skills bump `last_threat_review`. Frameworks lag RFCs; RFCs lag attacker innovation — this catalog makes that middle layer auditable.
 
 ### `data/dlp-controls.json`
 
-21 DLP control entries indexed along five axes: **channel** (where data flows — LLM prompt, RAG retrieval, MCP tool response, email, SaaS API, endpoint), **classifier** (how sensitive data is identified — regex, ML, embedding similarity, watermark), **surface** (where enforcement runs — endpoint, network proxy, API gateway, model gateway), **enforcement** mode (block, redact, warn, log-only), and **evidence** type (the audit artifact each control produces). The `dlp-gap-analysis` skill is the canonical consumer; other DLP-relevant skills cite control IDs in `dlp_refs`. Entries explicitly flag classical DLP controls that are architecturally inadequate for LLM/RAG channels (DR-1 framework-as-truth drift applied to DLP).
+22 DLP control entries indexed along five axes: **channel** (where data flows — LLM prompt, RAG retrieval, MCP tool response, email, SaaS API, endpoint), **classifier** (how sensitive data is identified — regex, ML, embedding similarity, watermark), **surface** (where enforcement runs — endpoint, network proxy, API gateway, model gateway), **enforcement** mode (block, redact, warn, log-only), and **evidence** type (the audit artifact each control produces). The `dlp-gap-analysis` skill is the canonical consumer; other DLP-relevant skills cite control IDs in `dlp_refs`. Entries explicitly flag classical DLP controls that are architecturally inadequate for LLM/RAG channels (DR-1 framework-as-truth drift applied to DLP).
 
 ---
 
@@ -232,6 +232,22 @@ Framework lag scoring and gap report generation.
 - `gapReport(frameworkId, scope)` — Generate gap report for a framework within a scope (e.g., "kernel LPE", "AI attack surface")
 - `theaterCheck(controlId, orgControls)` — Run compliance theater detection for a specific control
 
+### `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`.
+
+### `scripts/check-sbom-currency.js`
+
+Compares `sbom.cdx.json` against the live `manifest.json` skill count and `data/*.json` catalog counts. Fails the predeploy gate when the SBOM drifts from the shipped surface. Refresh with `npm run refresh-sbom`.
+
+### `scripts/verify-shipped-tarball.js`
+
+Packs the project with `npm pack`, extracts the tarball, and runs Ed25519 signature verification against the extracted bytes — the same path a downstream `npm install` exercises. Predeploy gate guaranteeing the shipped tarball verifies, independent of source-tree verification.
+
+### `tests/_helpers/cli.js`
+
+Shared test harness for spawning the CLI under tempdir-isolated state. Tests that exercise verb dispatch should consume this helper rather than spawning subprocesses ad-hoc — the helper enforces the "no mutation outside the tempdir" contract that prevents CI-vs-local state divergence.
+
 ---
 
 ## manifest.json

package/CHANGELOG.md

@@ -1,5 +1,125 @@
 # Changelog
 
+## 0.12.10 — 2026-05-13
+
+**Patch: OSV.dev wired as an upstream source, three new catalog entries, one new library-author indicator.**
+
+### OSV.dev as a new upstream source
+
+`lib/source-osv.js` + `OSV_SOURCE` in `lib/refresh-external.js` add OSV.dev (https://api.osv.dev/) as a recognised upstream pull. Operators run `exceptd refresh --source osv` to import advisories from the OSV-aggregated dataset, which covers the OSSF Malicious Packages namespace (`MAL-*`), Snyk advisories (`SNYK-*`), GitHub Advisory Database (`GHSA-*`), RustSec (`RUSTSEC-*`), Mageia (`MGASA-*`), Go Vuln DB (`GO-*`), Ubuntu USN (`USN-*`), PYSEC, and UVI — one unauthenticated API in place of N per-vendor feeds.
+
+The `--advisory <id>` flag now routes non-CVE / non-GHSA identifiers (`MAL-*`, `SNYK-*`, `RUSTSEC-*`, `USN-*`, `UVI-*`, `GO-*`, `MGASA-*`, `PYSEC-*`) through `source-osv`. CVE-* and GHSA-* continue routing through `source-ghsa` because the GitHub Advisory Database carries richer field coverage for those namespaces. Imported entries land as `_auto_imported: true` / `_draft: true` drafts, the same shape GHSA imports use — editorial fields (framework_control_gaps, full iocs, atlas_refs, attack_refs, rwep_factors) remain null until a human or AI assistant runs the cve-curation skill.
+
+When an OSV record carries a `CVE-*` value in its `aliases`, the catalog key is the CVE form and the OSV identifier moves to an `aliases` array on the entry. When no CVE is assigned (e.g. MAL-* malicious-package compromises), the OSV identifier IS the catalog key. The previous identifier convention (CVE-only keys) is preserved as the default; the new identifier shapes are an extension.
+
+Fixture support: `EXCEPTD_OSV_FIXTURE` env var (path to a JSON file with one or many OSV records) enables offline testing — same convention as the existing `EXCEPTD_GHSA_FIXTURE`.
+
+### Three new catalog entries
+
+- **`MAL-2026-3083`** (OSV-native key for the **elementary-data PyPI worm**, April 2026). 1.1M-monthly-downloads package compromised via a GitHub Actions script-injection sink in the project's own workflow (`update_pylon_issue.yml` interpolated `${{ github.event.comment.body }}` directly into a `run:` shell, escalated via the workflow's `GITHUB_TOKEN` to forge an orphan-commit release). Payload was a single `elementary.pth` file in the wheel (Python auto-exec at install time, not import time); infostealer sweeping dbt warehouse creds, AWS/GCP/Azure credentials, SSH keys, Kubernetes configs, cryptocurrency wallets to `igotnofriendsonlineorirl-imgonnakmslmao.skyhanni.cloud` with second-stage at `litter.catbox.moe/iqesmbhukgd2c7hq.sh`. Cataloged from OSV's OSSF Malicious Packages dataset (which published 2026-04-24, 4 days before the Snyk advisory). Aliases retained: `SNYK-PYTHON-ELEMENTARYDATA-16316110`, `pypi/2026-04-compr-elementary-data/elementary-data`. Full Hard Rule #14 IoC block; precedent-setting first MAL-* entry in the catalog.
+
+- **`CVE-2026-42208`** (BerriAI LiteLLM Proxy Auth SQL Injection). CVSS 9.3, **on CISA KEV** (dateAdded 2026-05-08). Crafted Authorization header to any LLM API route reaches a SQL query through the error-logging pathway with the attacker value concatenated rather than parameterised — read/modify the LiteLLM-managed-credentials database without prior auth. Affected: `litellm >= 1.81.16, < 1.83.7`. Patched: 1.83.7+ (parameterised query). Temporary workaround: `general_settings: disable_error_logs: true`. RWEP 65 (P1 / 72h timeline). Operator IoCs: Authorization header > 100 chars or carrying SQL metacharacters; mass key-mint events in LiteLLM logs without admin-UI sessions.
+
+- **`CVE-2026-39884`** (Flux159 mcp-server-kubernetes Argument Injection). CVSS 8.3. The `port_forward` MCP tool builds a kubectl command string and `.split(' ')`s it instead of using an argv array, so an AI assistant feeding `resourceName: "pod-name --address=0.0.0.0"` (typically via prompt injection upstream) lands attacker flags in kubectl's argv — binds port-forward to all interfaces or redirects to attacker namespace. Affected: `mcp-server-kubernetes <= 3.4.0`. Patched: 3.5.0+ (argv-array refactor). Operator IoCs: MCP audit logs showing port_forward calls with spaces or `--`/`-n` in resourceName; kubectl port-forward processes with `--address=0.0.0.0` on hosts that don't manually port-forward.
+
+Three matching `data/zeroday-lessons.json` entries follow the CVE-2026-45321 lesson shape. Five new control requirements derived from the lessons: NEW-CTRL-011 (GHA script-injection-sink ban), NEW-CTRL-012 (orphan-commit release detection), NEW-CTRL-013 (AI-gateway credential-store isolation), NEW-CTRL-014 (MCP-server argv not shellstring), NEW-CTRL-015 (MCP tool allowlist enforcement).
+
+### One new library-author indicator
+
+`gha-workflow-script-injection-sink` flags any `.github/workflows/*.yml` workflow that interpolates an attacker-controllable `${{ github.event.* }}` field directly into a `run:` shell script — the exact sink the elementary-data attack exploited. Detection grep covers `github.event.comment.body`, `github.event.issue.body`, `github.event.issue.title`, `github.event.pull_request.body`, `github.event.pull_request.title`, `github.event.review.body`, `github.event.head_commit.message`, `github.head_ref`, `github.event.discussion.body`, `github.event.discussion.title`. False-positive demotion path: if the workflow captures the value into an `env:` variable first OR runs only on `pull_request` (sandboxed, not `pull_request_target`) with default-read permissions, the sink isn't exploitable. Cross-referenced to MAL-2026-3083.
+
+### Catalog extensions
+
+- `data/cwe-catalog.json` gains CWE-506 (Embedded Malicious Code) and CWE-88 (Improper Neutralization of Argument Delimiters). Both backed by the new catalog entries.
+- `data/cve-catalog.json` `_meta.id_conventions` documents the MAL-*/SNYK-*/GHSA-*/RUSTSEC-* identifier shapes the catalog now accepts, the alias-retention convention when MITRE issues a CVE later, and the EPSS limitation (FIRST only indexes CVE identifiers).
+
+### Repository
+
+Test count: 441 → 459 (+18: OSV source tests + matching test references for Hard Rule #15 coverage). Predeploy gates: 15/15. Skills: 38/38 signed and verified. No skill bodies changed in this patch.
+
+## 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.**
+
+### Hard Rule #15 — diff-coverage gate is now blocking
+
+`scripts/check-test-coverage.js` flips from `--warn-only` to a blocking gate. The 15th `npm run predeploy` gate and the `Diff coverage` CI job now fail a run if any change to a CLI verb, CLI flag, `module.exports` identifier, playbook indicator, or CVE `iocs` field lands without a covering test reference. Two analyzer bugs that would have made the gate unreliable under blocking are fixed in the same release:
+
+- `coversLibExport` now recognises subprocess-based test invocations (e.g. `spawnSync(... "scripts/check-sbom-currency.js" ...)`) alongside `require(...)`-form coverage.
+- `extractLibExports` strips block and line comments before matching `module.exports = {...}`, eliminating the doc-comment shadow bug where the analyzer's regex captured a JSDoc banner and returned an empty export set.
+
+`tests/playbook-indicators.test.js` lands as a table-driven test referencing all 12 indicator ids added in v0.12.7 (`mcp.json` × 6) and v0.12.8 (`containers.json` × 2, `hardening.json` × 4). The new tests cover the Hard Rule #15 surface the analyzer flagged.
+
+### sbom `matched_cves` now evidence-correlated
+
+`exceptd run sbom` previously surfaced every CVE in the playbook's `domain.cve_refs` under `analyze.matched_cves`, regardless of whether the operator's submitted evidence correlated to any of them. Operators reading the output assumed they were affected by the listed CVEs. The analyze phase now splits into two fields:
+
+- `analyze.matched_cves` — only CVEs correlated to operator evidence (indicator hit whose `attack_ref`/`atlas_ref` intersects the CVE's refs, or an explicit `signals[cveId]` set to `true`/`hit`/`detected`/`affected`). Each entry carries a `correlated_via` reason.
+- `analyze.catalog_baseline_cves` — the playbook's CVE catalog (informational; not an affected-status list). Each entry carries `correlated_via: null` and a note documenting the distinction.
+
+CSAF / SARIF / OpenVEX bundles consume `matched_cves` only — they correctly omit catalog-only CVEs as vulnerabilities. RWEP base now derives from evidence-correlated CVEs rather than the catalog ceiling, so inconclusive runs no longer inherit a misleading high score.
+
+The `run` human renderer shows "No CVEs correlated to your evidence. Playbook catalog (informational): N CVE(s) this playbook scans for." when no evidence correlated.
+
+### CLI surface — ci verdict / exit reconcile, signing-key resolution, fuzzy matches
+
+`ci --scope <type>` with no evidence and all-inconclusive results now emits `verdict: "NO_EVIDENCE"` (was `"PASS"`) so the body and exit code 3 agree. Operators reading either field alone now see the same answer. The verdict computation is hoisted before the result emit so BLOCKED / FAIL / NO_EVIDENCE / PASS are all consistent end-to-end.
+
+`ci` result top-level gains `framework_gap_rollup` aggregating per-playbook `framework_gap_mapping` entries across all scoped playbooks. Each rollup entry lists `{framework, claimed_control, why_insufficient, playbooks[]}` so a CI gate surfaces "what gaps did this run uncover" without the operator having to walk every per-playbook result.
+
+`maybeSignAttestation()` now resolves `.keys/private.pem` cwd-first, package-root fallback — matching how `doctor --signatures` resolves the same key. Pre-v0.12.9, operators running `exceptd run` from a repo with their private key at the cwd-relative `.keys/private.pem` would see `doctor` report the key as present while attestations from the same directory were silently written UNSIGNED. The two surfaces now agree.
+
+`run <typo>` error path adds Levenshtein-distance suggestions for misspelled playbook ids when no substring match fits. `run secrt` now suggests `secrets`; `run cret-stores` suggests `cred-stores`.
+
+`brief --phase <value>` rejects unknown phases with a structured JSON error (accepted set: `govern | direct | look`). Pre-v0.12.9 any string was accepted silently and the full brief was emitted.
+
+`doctor --signatures --shipped-tarball` runs the `verify-shipped-tarball` round-trip alongside the source-tree signature check, surfacing the integrity layer that closed the v0.11.x → v0.12.4 signature regression class. Opt-in; routine `doctor --signatures` stays fast.
+
+`doctor --registry-check` text-mode output now surfaces the registry comparison alongside the other check lines. Pre-v0.12.9 the flag only populated `checks.registry.*` in the JSON output, leaving the text-mode operator with no signal the flag did anything.
+
+`run` precondition renderer no longer prints `[undefined]` for preconditions without an `on_fail` field — the bracket is omitted and the description falls back to `check | description | reason` in order.
+
+### CVE catalog freshness corrections
+
+Five entries reconciled against authoritative public sources as of 2026-05-13:
+
+- **CVE-2026-30615** (Windsurf MCP): CVSS corrected 9.8 → 8.0; vector AV:N → AV:L (the attack is local-vector via adversarial HTML content the Windsurf MCP client processes, not a network-vector zero-interaction RCE). Source: NVD authoritative metric block (`vulnStatus: Deferred`, last_modified 2026-04-27).
+- **CVE-2026-31431** (Copy Fail): KEV `dateAdded` corrected 2026-03-15 → 2026-05-01, `dueDate` 2026-04-05 → 2026-05-15. The catalog was running six weeks ahead of the real KEV listing; downstream framework-SLA computations were anchored on a date that hadn't yet been authoritative. CWE-669 added. Source: CISA KEV JSON feed.
+- **CVE-2026-43284** (Dirty Frag ESP): CVSS authoritative is 8.8 / `Scope:C` (kernel→user-namespace breakout — supports container-escape framing); 7.8 / `Scope:U` preserved as `cvss_score_alternate` for compatibility readers. CWE-123 added.
+- **CVE-2026-43500** (Dirty Frag RxRPC): CWE-787 added.
+- **EPSS values refreshed** for four CVEs (CVE-2026-31431, -43284, -43500, -45321) from live FIRST API values. Catalog previously stored cold-start estimates that overstated newly-published-CVE exposure.
+
+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 claims in the v0.12.8 CHANGELOG were not actually on disk in the squash commit, lost during the v0.12.8 recovery flow:
+
+- `data/playbooks/mcp.json` `domain.cve_refs` now includes CVE-2025-53773 alongside CVE-2026-30615 and CVE-2026-45321. The Hard Rule #4 mismatch (the `copilot-yolo-mode-flag` / `copilot-chat-experimental-flags` indicators detected this CVE without the playbook claiming it) is now genuinely closed.
+- `tests/operator-bugs.test.js` is now refactored to use `tests/_helpers/cli.js` for `makeCli` / `makeSuiteHome` / `tryJson`. The per-suite `EXCEPTD_HOME` tempdir routing applies to all 80+ tests in the file. Pre-v0.12.9 the inline helper continued writing attestations to the maintainer's real `~/.exceptd/attestations/` — 2,819 leaked attestations cleaned up alongside the refactor.
+
+### Two real defects deferred from v0.12.8 fixed
+
+- **Libuv `UV_HANDLE_CLOSING` crash on Windows + Node 25.** `lib/prefetch.js` `main()` called `process.exit(N)` after the summary `console.log` — same v0.11.10 #100 class as the run/ci sites already fixed. Replaced with `process.exitCode = N; return;` so undici / AbortController teardown completes before the event loop ends. Strengthened `#65 refresh --no-network` test asserts exit 0 AND no `Assertion failed` / `UV_HANDLE_CLOSING` lines on stderr.
+- **Two 404'd pin sources.** `d3fend/d3fend-data` and `mitre/cwe` were registered as `SOURCES.pins` GitHub-Releases sources, but neither repository publishes Releases via that path (D3FEND distributes from `d3fend.mitre.org`; CWE from `cwe.mitre.org`). Both sources removed from `lib/prefetch.js` and `lib/refresh-external.js` `pinsDiffFromCache()` `PIN_REPOS`. `prefetch summary` now reports `0 error(s)` on a clean cache. A new regression test asserts every pins source URL matches `^https://api.github.com/repos/<org>/<repo>/releases\?`.
+
+### Skill body second pass
+
+Four priority skills gain a `## Defensive Countermeasure Mapping` body section per Hard Rule #11's post-2026-05-11 grandfathered-skill closeout: `ai-c2-detection`, `ai-attack-surface`, `mcp-agent-trust`, `rag-pipeline-security`. Each maps the skill's offensive findings to 3-7 D3FEND IDs from `data/d3fend-catalog.json` with rationale + ephemeral/serverless-workload alternatives per Hard Rule #9.
+
+Eight meta skills (`researcher`, `threat-model-currency`, `skill-update-loop`, `zeroday-gap-learn`, `policy-exception-gen`, `security-maturity-tiers`, `exploit-scoring`, `compliance-theater`) gain a `## Frontmatter Scope` section documenting why their `atlas_refs` / `attack_refs` / `framework_gaps` lists are intentionally empty.
+
+`rag-pipeline-security` `framework_gaps` token refined `UK-CAF-A1` → `UK-CAF-B2` — the RAG attack class resolves to retrieval-time access-control failure, which is the B2 (Identity and Access Control) surface, not the A1 (Governance) parent concern.
+
+### Repository
+
+- README "13 gates" → "15 gates"; ARCHITECTURE catalog counts refreshed (CWE 30→51, D3FEND 21→28, RFC 19→31, jurisdictions "22+" → "35"); ARCHITECTURE Logic Layer gains entries for `scripts/check-test-coverage.js`, `scripts/check-sbom-currency.js`, `scripts/verify-shipped-tarball.js`, `tests/_helpers/cli.js`.
+- AGENTS.md feeds_into matrix heading drops the residual `(v0.10.x)` tag; Hard Rule #15 wording flips from `--warn-only` rollout language to present-tense blocking.
+- CONTRIBUTING.md adds `npm run diff-coverage` to the pre-push gate list so contributors run the same Hard Rule #15 check CI does.
+- Dependabot grouping for github-actions (already landed in v0.12.8) confirmed intact.
+
+Test count: 418 → 439. Predeploy gates: 15/15 (gate 15 now blocking). Skills: 38/38 signed and verified.
+
 ## 0.12.8 — 2026-05-13
 
 **Patch: comprehensive audit pass — CLI surface fixes, catalog completeness, test infrastructure hardening, AGENTS.md Hard Rule #15.**

package/README.md

@@ -167,7 +167,7 @@ You're adding a skill, updating a catalog, or cutting a release. Clone + bootstr
 git clone https://github.com/blamejs/exceptd-skills
 cd exceptd-skills
 npm run bootstrap          # auto-detects: verify-only / re-sign / first-init
-npm run predeploy          # full 13-gate CI sequence locally
+npm run predeploy          # full 15-gate CI sequence locally
 ```
 
 `bootstrap` auto-detects the right mode based on which keys exist on disk:

package/bin/exceptd.js

@@ -581,7 +581,12 @@ function dispatchPlaybook(cmd, argv) {
     bool:  ["pretty", "air-gap", "force-stale", "all", "flat", "directives",
             "ci", "latest", "diff-from-latest", "explain", "signal-list", "ack",
             "force-overwrite", "no-stream", "block-on-jurisdiction-clock",
-            "json-stdout-only", "fix", "human", "json", "strict-preconditions"],
+            "json-stdout-only", "fix", "human", "json", "strict-preconditions",
+            // v0.12.9: doctor --shipped-tarball runs the verify-shipped-tarball
+            // gate alongside --signatures. doctor --registry-check + --signatures
+            // were already accepted; explicit registration removes the silent
+            // "unknown bool flag" surface in parseArgs.
+            "shipped-tarball", "registry-check", "signatures", "currency", "cves", "rfcs"],
     multi: ["playbook", "format"],
   });
   // v0.11.2 bug #60: flip defaults to human-readable. JSON via explicit --json
@@ -703,17 +708,62 @@ function buildSkillToPlaybookHint(runner, wanted) {
     if (matches.length > 0) {
       return `That is a SKILL (read-only knowledge unit), not a PLAYBOOK (executable). Skill "${wanted}" is loaded by playbook${matches.length === 1 ? "" : "s"}: ${matches.join(", ")}. ` +
              `To execute: \`exceptd run ${matches[0]}\`. To read the skill: \`exceptd skill ${wanted}\`. ` +
-             `Tip: \`exceptd plan\` lists all 13 playbooks; \`exceptd watchlist\` lists skills.`;
+             `Tip: \`exceptd brief --all\` lists all 13 playbooks; \`exceptd watch\` lists skills.`;
     }
     // No matching skill either — provide nearest-playbook suggestions.
-    const near = ids.filter(id => id.includes(wanted) || wanted.includes(id)).slice(0, 3);
+    // v0.12.9 (P3 #9 from production smoke): substring fallback first (cheap),
+    // then edit-distance for typos that don't substring-match (`secrt`,
+    // `kernl`, `cret-stores`). Without the second pass `run secrt` returned
+    // the generic "13 playbooks" message even though `secrets` is one edit
+    // away.
+    const subMatches = ids.filter(id => id.includes(wanted) || wanted.includes(id)).slice(0, 3);
+    const fuzzyMatches = subMatches.length === 0 ? nearestByEditDistance(wanted, ids, 2).slice(0, 3) : [];
+    const near = subMatches.length ? subMatches : fuzzyMatches;
     if (near.length > 0) {
-      return `Did you mean: ${near.join(", ")}? Run \`exceptd plan\` for the full list.`;
+      return `Did you mean: ${near.join(", ")}? Run \`exceptd brief --all\` for the full list.`;
     }
-    return `Run \`exceptd plan\` to list the 13 playbooks.`;
+    return `Run \`exceptd brief --all\` to list the 13 playbooks.`;
   } catch { return null; }
 }
 
+/**
+ * Cheap Levenshtein distance, used to surface "Did you mean X?" suggestions
+ * for misspelled playbook ids in the `run <typo>` error path. Returns ids
+ * whose distance from `wanted` is ≤ `maxDistance`, sorted by closest first.
+ * Bounded by the candidate set size (13 playbooks), so the O(n*m) cost is
+ * negligible.
+ */
+function nearestByEditDistance(wanted, ids, maxDistance) {
+  if (!wanted || !Array.isArray(ids)) return [];
+  const w = String(wanted).toLowerCase();
+  const scored = [];
+  for (const id of ids) {
+    const d = editDistance(w, id.toLowerCase());
+    if (d <= maxDistance) scored.push({ id, d });
+  }
+  scored.sort((a, b) => a.d - b.d);
+  return scored.map(s => s.id);
+}
+
+function editDistance(a, b) {
+  if (a === b) return 0;
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+  const prev = new Array(b.length + 1);
+  for (let j = 0; j <= b.length; j++) prev[j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    let cur = i;
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      const next = Math.min(prev[j] + 1, cur + 1, prev[j - 1] + cost);
+      prev[j - 1] = cur;
+      cur = next;
+    }
+    prev[b.length] = cur;
+  }
+  return prev[b.length];
+}
+
 function printPlaybookVerbHelp(verb) {
   const cmds = {
     plan: `plan — list playbooks + directives, grouped by scope.
@@ -1188,6 +1238,18 @@ function cmdBrief(runner, args, runOpts, pretty) {
   const playbookId = args._[0];
   const onlyPhase = args.phase || null;
 
+  // v0.12.9 (P2 #7 from production smoke): refuse garbage values to --phase.
+  // Pre-v0.12.9 `brief secrets --phase foo` silently accepted any string and
+  // emitted the full brief — operators got no signal the flag was misused.
+  // The legacy-compat surface is exactly the three v0.10.x verb names
+  // (govern | direct | look); anything else is a typo or a misunderstanding.
+  if (onlyPhase != null) {
+    const ACCEPTED_PHASES = ["govern", "direct", "look"];
+    if (!ACCEPTED_PHASES.includes(onlyPhase)) {
+      return emitError(`brief: --phase "${onlyPhase}" not in accepted set ${JSON.stringify(ACCEPTED_PHASES)}.`, { verb: "brief", provided: onlyPhase }, pretty);
+    }
+  }
+
   if (!playbookId || args.all) {
     // Multi-playbook brief (replaces `plan`). Reuses cmdPlan output shape.
     return cmdPlan(runner, args, runOpts, pretty);
@@ -1782,10 +1844,19 @@ function cmdRun(runner, args, runOpts, pretty) {
     const verdictIcon = cls === "detected" ? "[!! DETECTED]" : cls === "inconclusive" ? "[i  INCONCLUSIVE]" : "[ok]";
     lines.push(`\n${verdictIcon}  classification=${cls}  RWEP ${adj}/${top}${adj !== base ? ` (Δ${adj - base} from operator evidence)` : " (catalog baseline)"}  blast_radius=${obj.phases?.analyze?.blast_radius_score ?? "n/a"}/5`);
     const cves = obj.phases?.analyze?.matched_cves || [];
+    const baseline = obj.phases?.analyze?.catalog_baseline_cves || [];
     if (cves.length) {
       lines.push(`\nMatched CVEs (${cves.length}):`);
-      for (const c of cves.slice(0, 6)) lines.push(`  ${c.cve_id}  RWEP ${c.rwep}  KEV=${c.cisa_kev}  ${c.active_exploitation || ""}`);
+      for (const c of cves.slice(0, 6)) {
+        const via = Array.isArray(c.correlated_via) && c.correlated_via.length ? `  via ${c.correlated_via[0]}${c.correlated_via.length > 1 ? ` (+${c.correlated_via.length - 1})` : ""}` : "";
+        lines.push(`  ${c.cve_id}  RWEP ${c.rwep}  KEV=${c.cisa_kev}  ${c.active_exploitation || ""}${via}`);
+      }
       if (cves.length > 6) lines.push(`  … ${cves.length - 6} more`);
+    } else if (baseline.length) {
+      // No evidence correlated to any CVE — clarify rather than implying the
+      // operator is affected by the catalog enumeration. Pre-fix output read
+      // like a hit list; explicit zero + scan-coverage callout fixes that.
+      lines.push(`\nNo CVEs correlated to your evidence. Playbook catalog (informational): ${baseline.length} CVE(s) this playbook scans for.`);
     }
     const indicators = obj.phases?.detect?.indicators || [];
     const hits = indicators.filter(i => i.verdict === "hit");
@@ -1808,7 +1879,16 @@ function cmdRun(runner, args, runOpts, pretty) {
     const issues = obj.preflight_issues || [];
     if (issues.length) {
       lines.push(`\nPreflight warnings (${issues.length}):`);
-      for (const i of issues) lines.push(`  [${i.on_fail}] ${i.id}: ${i.check || ""}`);
+      // v0.12.9 (P3 #12 from production smoke): handle preconditions without
+      // an `on_fail` field (precondition.check was satisfied trivially or the
+      // playbook omits the field). Pre-v0.12.9 these rendered as `[undefined]
+      // <id>:`. Now: omit the bracket when on_fail is absent, and fall back
+      // to the description if `check` is missing too.
+      for (const i of issues) {
+        const tag = i.on_fail ? `[${i.on_fail}] ` : "";
+        const detail = i.check || i.description || i.reason || "(no detail)";
+        lines.push(`  ${tag}${i.id}: ${detail}`);
+      }
     }
     lines.push(`\nFull structured result: --json (or --pretty for indented).`);
     return lines.join("\n");
@@ -2107,6 +2187,15 @@ function persistAttestation(args) {
 function maybeSignAttestation(filePath) {
   const crypto = require("crypto");
   const sigPath = filePath + ".sig";
+  // v0.12.9 (P2 #3 from production smoke + codex P1 PR #4 review): keep the
+  // sign key aligned with the VERIFY key. `attest verify` checks signatures
+  // against PKG_ROOT/keys/public.pem; if we sign with cwd/.keys/private.pem
+  // (e.g. the maintainer's repo-local keypair) the resulting `.sig` will
+  // verify INVALID and report a false tamper signal on every freshly-written
+  // attestation. PKG_ROOT-only resolution is the right answer; the original
+  // smoke report's "doctor finds key, run does not" gap is fixed in `doctor`
+  // (reporting only PKG_ROOT now), not by making `run` follow a cwd key the
+  // verifier doesn't trust.
   const privKeyPath = path.join(PKG_ROOT, ".keys", "private.pem");
   const content = fs.readFileSync(filePath, "utf8");
   // One-time-per-process unsigned warning so cron jobs don't spam stderr.
@@ -2840,6 +2929,46 @@ function cmdDoctor(runner, args, runOpts, pretty) {
         ...(ok ? {} : { exit_code: res.status, raw: text.slice(0, 500) }),
       };
       if (!ok) issues.push("signatures");
+
+      // v0.12.9 (P3 #10 from production smoke): also run the shipped-tarball
+      // round-trip gate (sign + pack + extract + verify) when the operator
+      // opts in via --shipped-tarball. This is the v0.12.3 verify-as-shipped
+      // gate that closed the v0.11.x → v0.12.4 signature regression class
+      // (source-tree verify passed; shipped-tarball verify failed). It's
+      // opt-in because npm pack adds ~5-10s and creates tempdir churn —
+      // routine `doctor --signatures` stays fast.
+      if (args["shipped-tarball"]) {
+        try {
+          const tarballScript = path.join(PKG_ROOT, "scripts", "verify-shipped-tarball.js");
+          if (fs.existsSync(tarballScript)) {
+            const tRes = spawnSync(process.execPath, [tarballScript], {
+              encoding: "utf8",
+              cwd: PKG_ROOT,
+              timeout: 120000,
+            });
+            const tText = (tRes.stdout || "") + (tRes.stderr || "");
+            const tOk = tRes.status === 0;
+            const tMatch = tText.match(/(\d+)\/(\d+)\s+pass,\s+(\d+)\s+fail/i);
+            checks.signatures.shipped_tarball = {
+              ok: tOk,
+              skills_passed: tMatch ? Number(tMatch[1]) : null,
+              skills_total: tMatch ? Number(tMatch[2]) : null,
+              skills_failed: tMatch ? Number(tMatch[3]) : null,
+              ...(tOk ? {} : { exit_code: tRes.status, raw: tText.slice(-500) }),
+            };
+            if (!tOk) issues.push("signatures.shipped_tarball");
+          } else {
+            checks.signatures.shipped_tarball = {
+              ok: null,
+              skipped: true,
+              reason: "scripts/verify-shipped-tarball.js not present (likely an installed package, not a source checkout). The tarball-verify gate runs at release time; routine integrity is covered by `--signatures`.",
+            };
+          }
+        } catch (e) {
+          checks.signatures.shipped_tarball = { ok: false, error: e.message };
+          issues.push("signatures.shipped_tarball");
+        }
+      }
     } catch (e) {
       checks.signatures = { ok: false, error: e.message };
       issues.push("signatures");
@@ -2941,9 +3070,14 @@ function cmdDoctor(runner, args, runOpts, pretty) {
 
   if (runSigning) {
     try {
-      const keyPath = path.join(process.cwd(), ".keys", "private.pem");
-      const fallback = path.join(PKG_ROOT, ".keys", "private.pem");
-      const present = fs.existsSync(keyPath) || fs.existsSync(fallback);
+      // v0.12.9 codex P1 (PR #4): report only PKG_ROOT — that's the path
+      // maybeSignAttestation() and `attest verify` actually use. Pre-v0.12.9
+      // doctor also reported cwd-resident keys as present, which gave a
+      // false-positive "signing enabled" signal when the operator's cwd
+      // key was misaligned with the PKG_ROOT-resident public key used at
+      // verify time.
+      const keyPath = path.join(PKG_ROOT, ".keys", "private.pem");
+      const present = fs.existsSync(keyPath);
       // Bug #61 (v0.11.2): signing-status missing key is a real WARNING. The
       // attestation pipeline writes unsigned files when this is absent, which
       // operators reading the attestation later cannot verify for authenticity.
@@ -3028,10 +3162,9 @@ function cmdDoctor(runner, args, runOpts, pretty) {
     });
     if (r.status === 0) {
       // Re-verify the private key is now present so the JSON output reflects
-      // the fix.
-      const keyPath = path.join(process.cwd(), ".keys", "private.pem");
-      const fallback = path.join(PKG_ROOT, ".keys", "private.pem");
-      const present = fs.existsSync(keyPath) || fs.existsSync(fallback);
+      // the fix. v0.12.9 codex P1: PKG_ROOT-only (sign + verify use this path).
+      const keyPath = path.join(PKG_ROOT, ".keys", "private.pem");
+      const present = fs.existsSync(keyPath);
       checks.signing = { ok: present, severity: present ? "info" : "warn", private_key_present: present, can_sign_attestations: present };
       out.checks = checks;
       out.summary.fix_applied = "ed25519_keypair_generated";
@@ -3080,6 +3213,35 @@ function cmdDoctor(runner, args, runOpts, pretty) {
       ? `RFC catalog: ${c.total ?? "?"} entries, drift ${c.drift ?? 0}`
       : `RFC catalog FAILED (exit=${c.exit_code ?? "?"})`
   );
+  // v0.12.9 (P3 #11 from production smoke): render registry-check in text mode.
+  // Pre-v0.12.9 --registry-check populated checks.registry only in the JSON
+  // output; operators in text mode had to add --json to see if the flag did
+  // anything. Now the line surfaces in the human checklist.
+  mark(checks.registry, c => {
+    if (c.skipped) return `npm registry check: skipped (${c.reason || "unknown reason"})`;
+    if (!c.ok && !c.same && c.behind) {
+      const days = c.days_since_latest_publish != null ? `${c.days_since_latest_publish}d` : "?";
+      return `npm registry: local v${c.local_version ?? "?"} BEHIND published v${c.published_version ?? "?"} (${days})`;
+    }
+    if (c.same) {
+      return `npm registry: local v${c.local_version ?? "?"} == published v${c.published_version ?? "?"} (current)`;
+    }
+    if (c.ahead) {
+      return `npm registry: local v${c.local_version ?? "?"} AHEAD of published v${c.published_version ?? "?"} (unreleased / dev install)`;
+    }
+    return `npm registry: check returned no comparison (raw exit=${c.exit_code ?? "?"})`;
+  });
+  // v0.12.9 (P3 #10): surface shipped_tarball sub-check when --shipped-tarball was used.
+  if (checks.signatures?.shipped_tarball) {
+    const st = checks.signatures.shipped_tarball;
+    if (st.skipped) {
+      lines.push(`  [info] shipped tarball verify: skipped (${st.reason})`);
+    } else if (st.ok) {
+      lines.push(`  [ok] shipped tarball verify: ${st.skills_passed ?? "?"}/${st.skills_total ?? "?"} skills pass on extracted tarball`);
+    } else {
+      lines.push(`  [!!] shipped tarball verify FAILED: ${st.skills_failed ?? "?"}/${st.skills_total ?? "?"} skills fail (exit=${st.exit_code ?? "?"})`);
+    }
+  }
   if (checks.signing) {
     if (checks.signing.private_key_present) {
       lines.push(`  [ok] attestation signing: private key present (.keys/private.pem)`);
@@ -3711,17 +3873,65 @@ function cmdCi(runner, args, runOpts, pretty) {
   const rwepValues = results.map(r => r.phases?.analyze?.rwep?.adjusted ?? 0);
   const maxRwepObserved = rwepValues.length ? Math.max(...rwepValues) : 0;
 
+  // v0.12.9 (P1 #2 from production smoke): reconcile verdict with exit code.
+  // Pre-v0.12.9 the no-evidence-all-inconclusive path emitted verdict="PASS"
+  // but the process exited 3 ("ran but no evidence"). CI consumers reading
+  // exit code only failed a PASS run; consumers reading verdict only passed
+  // a no-data run. Now compute the verdict up-front to match the exit-code
+  // matrix (BLOCKED > FAIL > NO_EVIDENCE > PASS) so both surfaces agree.
+  const suppliedEvidenceForVerdict = args.evidence || args["evidence-dir"];
+  const blockedCount = results.filter(r => r && r.ok === false).length;
+  const inconclusiveCount = results.filter(r => r.phases?.detect?.classification === "inconclusive").length;
+  const totalForVerdict = results.length;
+  const noEvidenceAllInconclusive = !suppliedEvidenceForVerdict && totalForVerdict > 0 && inconclusiveCount === totalForVerdict;
+  const computedVerdict = blockedCount > 0
+    ? "BLOCKED"
+    : fail
+      ? "FAIL"
+      : noEvidenceAllInconclusive
+        ? "NO_EVIDENCE"
+        : "PASS";
+
+  // v0.12.9 (P2 #8 from production smoke): roll up per-playbook framework_gap
+  // mappings to the ci top-level. Phase 7 of the seven-phase contract surfaces
+  // framework_gap_mapping per result; pre-v0.12.9 ci never aggregated them,
+  // so operators got individual-playbook results only. Now: top-level
+  // framework_gap_rollup lists each {framework, claimed_control} once with
+  // the set of playbooks that flagged it — single-glance "what gaps did this
+  // gate uncover across the scoped playbooks."
+  const gapRollupMap = new Map();
+  for (const r of results) {
+    const gaps = r.phases?.analyze?.framework_gap_mapping || [];
+    for (const g of gaps) {
+      const key = `${g.framework || "unknown"}::${g.claimed_control || "unspecified"}`;
+      const existing = gapRollupMap.get(key);
+      if (existing) {
+        if (!existing.playbooks.includes(r.playbook_id)) existing.playbooks.push(r.playbook_id);
+      } else {
+        gapRollupMap.set(key, {
+          framework: g.framework || null,
+          claimed_control: g.claimed_control || null,
+          why_insufficient: g.why_insufficient || null,
+          playbooks: [r.playbook_id],
+        });
+      }
+    }
+  }
+  const frameworkGapRollup = [...gapRollupMap.values()];
+
   const summary = {
     total: results.length,
     detected: results.filter(r => r.phases?.detect?.classification === "detected").length,
-    inconclusive: results.filter(r => r.phases?.detect?.classification === "inconclusive").length,
+    inconclusive: inconclusiveCount,
     not_detected: results.filter(r => ["not_detected", "clean"].includes(r.phases?.detect?.classification)).length,
-    blocked: results.filter(r => r && r.ok === false).length,
+    blocked: blockedCount,
     max_rwep_observed: maxRwepObserved,
     jurisdiction_clocks_started: results
       .flatMap(r => r.phases?.close?.notification_actions || [])
       .filter(n => n && n.clock_started_at != null).length,
-    verdict: fail ? "FAIL" : "PASS",
+    framework_gap_rollup: frameworkGapRollup,
+    framework_gap_count: frameworkGapRollup.length,
+    verdict: computedVerdict,
     fail_reasons: failReasons,
   };