@blamejs/exceptd-skills 0.12.22 → 0.12.24

package/README.md

@@ -18,7 +18,7 @@
 [![ATLAS](https://img.shields.io/badge/MITRE%20ATLAS-v5.1.0-d946ef)](https://atlas.mitre.org)
 [![ATT&CK](https://img.shields.io/badge/MITRE%20ATT%26CK-v17-d946ef)](https://attack.mitre.org)
 [![Ed25519-signed](https://img.shields.io/badge/skills-Ed25519--signed-2ea043)](AGENTS.md)
-[![Jurisdictions](https://img.shields.io/badge/jurisdictions-34-blue)](data/global-frameworks.json)
+[![Jurisdictions](https://img.shields.io/badge/jurisdictions-35-blue)](data/global-frameworks.json)
 
 </div>
 
@@ -30,13 +30,13 @@ This platform surfaces what is actually happening right now. Every skill explici
 
 ## Status
 
-Pre-1.0. Latest release lives on [GitHub Releases](https://github.com/blamejs/exceptd-skills/releases) and on npm as [`@blamejs/exceptd-skills`](https://www.npmjs.com/package/@blamejs/exceptd-skills) (signed npm provenance attestation). 38 skills across kernel LPE, AI attack surface, MCP trust, RAG security, AI-API C2 detection, PQC migration, framework gap analysis, compliance theater, exploit scoring, threat-model currency, zero-day learning, global GRC, policy exception generation, security maturity tiers, skill update loop, attack-surface pen testing, fuzz testing, DLP gap analysis, supply-chain integrity, defensive-countermeasure mapping, identity assurance, OT/ICS security, coordinated vulnerability disclosure, threat-modeling methodology, child-safety age gates, plus sector packs (federal, financial, healthcare, energy) — and a `researcher` triage dispatcher. 10 data catalogs cover CVE / ATLAS / ATT&CK / CWE / D3FEND / DLP / RFC / framework gaps / global frameworks / zero-day lessons. 34 jurisdictions tracked. AI-consumer ergonomics: `data/_indexes/` ships 17 pre-computed indexes (xref / chains / dispatch / DiD ladders / theater fingerprints / recipes / token budget / currency / activity feed) regenerated by `npm run build-indexes`. External-data refresh is automated nightly via `.github/workflows/refresh.yml` — KEV/EPSS/NVD/RFC drift opens an auto-PR with deltas pre-applied; KEV adds new CVEs and IETF discovery auto-imports new RFCs across 48 project-relevant working groups (`_auto_imported` annotation flags entries for human curation); ATLAS/ATT&CK/CWE/D3FEND version bumps open an issue (audit required per AGENTS.md Hard Rule #12). `exceptd verify` prints dual SHA-256 + SHA3-512 public-key fingerprints for out-of-band key pinning. `exceptd scan` probes 22 PQC algorithms across the full NIST + IETF emerging landscape. `exceptd framework-gap <framework> <scenario>` provides a non-AI programmatic runner for the framework-gap skill.
+Pre-1.0. Latest release lives on [GitHub Releases](https://github.com/blamejs/exceptd-skills/releases) and on npm as [`@blamejs/exceptd-skills`](https://www.npmjs.com/package/@blamejs/exceptd-skills) (signed npm provenance attestation). 38 skills across kernel LPE, AI attack surface, MCP trust, RAG security, AI-API C2 detection, PQC migration, framework gap analysis, compliance theater, exploit scoring, threat-model currency, zero-day learning, global GRC, policy exception generation, security maturity tiers, skill update loop, attack-surface pen testing, fuzz testing, DLP gap analysis, supply-chain integrity, defensive-countermeasure mapping, identity assurance, OT/ICS security, coordinated vulnerability disclosure, threat-modeling methodology, child-safety age gates, plus sector packs (federal, financial, healthcare, energy) — and a `researcher` triage dispatcher. 10 data catalogs cover CVE / ATLAS / ATT&CK / CWE / D3FEND / DLP / RFC / framework gaps / global frameworks / zero-day lessons. 35 jurisdictions tracked. AI-consumer ergonomics: `data/_indexes/` ships 17 pre-computed indexes (xref / chains / dispatch / DiD ladders / theater fingerprints / recipes / token budget / currency / activity feed) regenerated by `npm run build-indexes`. External-data refresh is automated nightly via `.github/workflows/refresh.yml` — KEV/EPSS/NVD/RFC drift opens an auto-PR with deltas pre-applied; KEV adds new CVEs and IETF discovery auto-imports new RFCs across 48 project-relevant working groups (`_auto_imported` annotation flags entries for human curation); ATLAS/ATT&CK/CWE/D3FEND version bumps open an issue (audit required per AGENTS.md Hard Rule #12). `exceptd doctor --signatures` prints dual SHA-256 + SHA3-512 public-key fingerprints for out-of-band key pinning. `exceptd discover` probes 22 PQC algorithms across the full NIST + IETF emerging landscape. `exceptd framework-gap <framework> <scenario>` provides a non-AI programmatic runner for the framework-gap skill.
 
 **v0.10.0 introduced the seven-phase playbook contract** — exceptd ships playbooks under `data/playbooks/*.json` that host AIs (Claude Code, Cursor, Gemini CLI, Codex) execute through seven phases: `govern → direct → look → detect → analyze → validate → close`. exceptd owns govern / direct / analyze / validate / close (knowledge + GRC layer); the host AI owns look / detect (artifact collection + indicator evaluation with its native Bash/Read/Grep/Glob).
 
-**v0.11.0 collapses the 21-verb CLI into 11 canonical verbs** + flips the default output to human-readable. The new surface: `discover` (scan cwd → recommend playbooks), `brief` (unified info doc, replaces plan + govern + direct + look), `run` (phases 4-7, with flat or nested submission shape, auto-detect cwd context), `ai-run` (JSONL streaming variant for AI conversational flow), `attest` (subverbs: list / show / export / verify / diff — replaces reattest + list-attestations), `doctor` (one-shot health check — signatures + currency + cve/rfc validation + signing status), `ci` (one-shot CI gate, exit-2 on detected or rwep ≥ escalate), `ask` (plain-English routing), `lint` (pre-flight submission shape check). Attestation root moved from cwd-relative `.exceptd/` to `~/.exceptd/attestations/<repo-or-host-tag>/`. v0.10.x verbs (`plan`/`govern`/`direct`/`look`/`scan`/`dispatch`/`currency`/`verify`/`validate-cves`/`validate-rfcs`/`watchlist`/`prefetch`/`build-indexes`/`ingest`/`reattest`/`list-attestations`) still work via one-time deprecation banner — removed in v0.12.
+**v0.11.0 collapses the 21-verb CLI into 11 canonical verbs** + flips the default output to human-readable. The new surface: `discover` (scan cwd → recommend playbooks), `brief` (unified info doc, replaces plan + govern + direct + look), `run` (phases 4-7, with flat or nested submission shape, auto-detect cwd context), `ai-run` (JSONL streaming variant for AI conversational flow), `attest` (subverbs: list / show / export / verify / diff — replaces reattest + list-attestations), `doctor` (one-shot health check — signatures + currency + cve/rfc validation + signing status), `ci` (one-shot CI gate, exit-2 on detected or rwep ≥ escalate), `ask` (plain-English routing), `lint` (pre-flight submission shape check). Attestation root moved from cwd-relative `.exceptd/` to `~/.exceptd/attestations/<repo-or-host-tag>/`. v0.10.x verbs (`plan`/`govern`/`direct`/`look`/`scan`/`dispatch`/`currency`/`verify`/`validate-cves`/`validate-rfcs`/`watchlist`/`prefetch`/`build-indexes`/`ingest`/`reattest`/`list-attestations`) still work via one-time deprecation banner — scheduled for removal in v0.13.
 
-**v0.11.1-0.11.7 stability arc** — 30+ operator-reported items fixed across the v0.11.x line: mutex filesystem lockfile, `--vex` filter, `--ci` exit-code gating, `--diff-from-latest`, `--operator`/`--ack` attestation binding, `--format <fmt>` actually transforms output for run + ci, `ask` synonym routing, `lint` shares normalize contract with runner, CSAF/SARIF/OpenVEX bundles include indicator hits + framework gaps (was: empty for posture-only playbooks), CSAF current_release_date populated, SARIF rule definitions for every ruleId, `doctor --fix` for missing private key, `--strict-preconditions` flag, default human output for `attest list`/`lint` on TTY. Permanent regression suite at `tests/operator-bugs.test.js` (35 named test cases) — re-introductions caught at `npm test`, not at user re-report.
+**v0.11 series** — CLI ergonomics and signature-verify hardening: mutex filesystem lockfile, `--vex` filter, `--ci` exit-code gating, `--diff-from-latest`, `--operator`/`--ack` attestation binding, `--format <fmt>` transforms output for `run` and `ci`, `ask` synonym routing, `lint` shares the normalize contract with the runner, CSAF/SARIF/OpenVEX bundles include indicator hits and framework gaps for posture-only playbooks, CSAF `current_release_date` populated, SARIF rule definitions for every ruleId, `doctor --fix` repairs a missing private key, `--strict-preconditions` flag, default human output for `attest list` and `lint` on TTY. Regression coverage at `tests/operator-bugs.test.js` catches re-introductions at `npm test`.
 
 ---
 
@@ -147,6 +147,15 @@ npm install -g @blamejs/exceptd-skills
 exceptd help
 ```
 
+First run — verify the signing chain and pin the public-key fingerprint for out-of-band checks:
+
+```bash
+exceptd doctor --signatures            # verify Ed25519 chains (38/38 expected)
+cat $(exceptd path)/keys/EXPECTED_FINGERPRINT   # pin fingerprint for OOB verify
+```
+
+Verify on npm: `npm view @blamejs/exceptd-skills@<version> dist.signatures` shows the SLSA v1 provenance attestation.
+
 Air-gapped operation: run `exceptd refresh --prefetch` on a connected host, copy the resulting `.cache/upstream/` to the airgap, run `exceptd refresh --from-cache <path> --apply` over there. The vendored upstream snapshots replace every network call.
 
 Fresh-disclosure workflow (v0.12.0): the nightly auto-PR job pulls KEV / NVD / EPSS / IETF / **GHSA** (added in v0.12.0) / **OSV** (added in v0.12.10). KEV typically takes days; NVD ~10 days; GHSA fires within hours of disclosure and covers npm + PyPI + Maven + Go + NuGet + …; OSV aggregates the OSSF Malicious Packages dataset (`MAL-*` keys) + Snyk + RustSec + Mageia + Ubuntu USN + Go Vuln DB + PYSEC + UVI on top of GHSA — useful for malicious-package compromises that don't have CVEs yet (`exceptd refresh --advisory MAL-2026-3083`). New IDs land as drafts (`_auto_imported: true`, `_draft: true`) that the catalog validator treats as warnings, not errors — operators get the fresh entry immediately, editorial review (framework gaps, IoCs, ATLAS/ATT&CK refs) follows via `exceptd refresh --curate <ID>`. For "I want this advisory today, not tomorrow": `exceptd refresh --advisory <CVE-or-GHSA-or-MAL-or-SNYK-or-RUSTSEC-ID> --apply`.
@@ -169,7 +178,7 @@ You're adding a skill, updating a catalog, or cutting a release. Clone + bootstr
 git clone https://github.com/blamejs/exceptd-skills
 cd exceptd-skills
 npm run bootstrap          # auto-detects: verify-only / re-sign / first-init
-npm run predeploy          # full 15-gate CI sequence locally
+npm run predeploy          # full 14-gate CI sequence locally
 ```
 
 `bootstrap` auto-detects the right mode based on which keys exist on disk:
@@ -309,7 +318,7 @@ exceptd help                          This help.
 exceptd <verb> --help                 Per-verb usage with flag descriptions.
 ```
 
-### Legacy v0.10.x verbs (deprecated, removed in v0.12)
+### Legacy v0.10.x verbs (deprecated, scheduled for removal in v0.13)
 
 These still work but emit a one-time deprecation banner per process:
 
@@ -380,15 +389,19 @@ If your tool has a conventional auto-load filename not listed here and you'd lik
 
 Regenerate with `exceptd build-indexes` (full) or `exceptd build-indexes --changed --parallel` (incremental).
 
+## For skill authors — `agents/`
+
+The `agents/` directory ships markdown role cards documenting authoring conventions for contributors writing new skills or playbooks. The cards are reference material for humans and AI assistants editing the repo; the CLI runtime does not load them. Operators consuming `@blamejs/exceptd-skills` can ignore the directory.
+
 ## Data catalogs
 
-All skills pull from `data/`. Cross-validated against canonical upstream sources via `exceptd refresh` / `exceptd validate-cves` / `exceptd validate-rfcs`.
+All skills pull from `data/`. Cross-validated against canonical upstream sources via `exceptd refresh` / `exceptd doctor --cves` / `exceptd doctor --rfcs`.
 
 - `cve-catalog.json` — CVE metadata with RWEP scores, CISA KEV status, PoC availability, live-patch info
 - `atlas-ttps.json` — MITRE ATLAS v5.1.0 TTPs with gap flags and exploitation examples
 - `framework-control-gaps.json` — Per-framework, per-control: what it was designed for vs. what it misses
 - `exploit-availability.json` — PoC locations, weaponization status, AI-assist factor
-- `global-frameworks.json` — All major global compliance frameworks (34 jurisdictions) with control inventories and lag scores
+- `global-frameworks.json` — All major global compliance frameworks (35 jurisdictions) with control inventories and lag scores
 - `zeroday-lessons.json` — Zero-day → control gap → framework gap → new control requirement mappings
 - `cwe-catalog.json` — CWE entries pinned to CWE v4.17 (Top 25 + AI- / supply-chain-relevant additions)
 - `d3fend-catalog.json` — MITRE D3FEND defensive technique entries pinned to D3FEND v1.0.0