@blamejs/exceptd-skills 0.11.0 → 0.11.2

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## 0.11.2 — 2026-05-12
+
+**Patch: operator-reported items 58-70 from real CLI use.**
+
+### Bugs
+
+- **#58 `ask` non-functional.** Even literal token "secrets" returned `matched: []`. Root cause: tokenizer required length > 3 (dropped "PQC"/"MCP") and the search index covered only `domain.name + attack_class + first sentence of threat_context`. Rewritten with: (a) length >= 2 token filter, (b) synonym map (`credential` → secret/key/token/...; `supply chain` → sbom/dependency/...; `pqc` → post-quantum/ml-kem/...), (c) richer index covering id + name + attack_class + atlas_refs + attack_refs + cwe_refs + frameworks_in_scope + theater_fingerprints.claim + full threat_context + framework_lag_declaration + skill_chain + collection_scope, (d) ID match scores 3× (so `ask secrets` routes to the secrets playbook). Default output now human-readable; `--json` for machine.
+- **#59 `--format` flag was no-op.** Documented values produced standard JSON unconditionally. Wired through: `--format summary` emits a single-line JSON digest; `--format markdown` emits an operator-readable markdown report; `--format csaf-2.0|sarif|openvex` emits the corresponding bundle from `close.evidence_package.bundles_by_format`. Unknown values rejected with a list of valid options.
+- **#60 Default output flipped (partial).** `emit()` now detects `stdout.isTTY` — interactive use gets indented JSON (massively more readable); piped use stays compact. Override via `--pretty` (always indent) or `EXCEPTD_RAW_JSON=1`. Verbs with dedicated human renderers (`discover`, `doctor`, `ask`) still use them.
+- **#61 doctor summary contradicted its findings.** Output said "all checks green" directly above `[!!] private key MISSING`. Now: signing-check severity is `warn` when key absent; summary distinguishes errors vs warnings (`X fail / Y warn`); icon shows `[!! warn]` instead of `[ok]`. Warnings don't force exit 1 (CI still ok) but the visible state matches.
+- **#62 `watch` verb missing.** The deprecation map said `watchlist → watch` but `watch` returned unknown-command. Added `watch` as orchestrator passthrough aliased to `watchlist` (same function).
+- **#63 `discover` vs `ci --scope code` mismatch.** discover recommended 5 playbooks; ci ran 4 (different sets). ci now includes cross-cutting playbooks (`framework`) regardless of scope, and for `--scope code` on a git repo with a lockfile, also includes `sbom` (system-scope but repo-relevant). Aligns with discover's recommendations.
+- **#65 `refresh --no-network` / `--indexes-only` silently no-op.** v0.11.0 deprecation pointers said `prefetch → refresh --no-network` and `build-indexes → refresh --indexes-only`, but the underlying refresh script ignored those flags. Now: CLI translates them at dispatch time — `refresh --no-network` routes to the `prefetch` script; `refresh --indexes-only` routes to `build-indexes`.
+- **#66 `ai-run` shell-pipe unusable.** `echo '{...}' | exceptd ai-run secrets` failed with "stdin closed without an evidence event" because shell heredocs close stdin before the streaming protocol expects the wrapped `{event:evidence}` frame. Fix: when streaming mode hits EOF without a wrapped event, parse the raw stdin as a bare submission object and run with it. Operators no longer need an interactive harness for the common single-shot case.
+- **#64 verified.** `ok:false` from `on_fail: halt` preconditions correctly exits 1 (kernel-on-Windows reproducer). The user's `exceptd run secrets` cases were `on_fail: warn` preconditions where exit 0 is correct (run completed with warning). No regression in v0.11.x; the user's stale install may have shown different behavior.
+
+### Features
+
+- **#67** `ask` routing index — same fix as #58.
+- **#68** `--format summary` single-line digest — same fix as #59. Returns: `{ok, playbook, session_id, classification, rwep, blast_radius, matched_cves, feeds_into, jurisdiction_clocks, evidence_hash}`. Useful for GH Actions annotation lines.
+- **#69** `doctor --fix` automatically runs `node lib/sign.js generate-keypair` when the private-key check is the only failing warning. Closes the most-common discovered-issue → manual-fix-recipe loop.
+- **#70** `run --format markdown` emits an operator-readable per-run digest (classification, RWEP, matched CVEs, recommended remediation, notification clocks, feeds_into).
+
+### Already shipped (cross-referenced)
+
+- `attest diff <a> --against <b>` (was v0.11.0 #56) — works as documented.
+
+## 0.11.1 — 2026-05-12
+
+**Patch: operator-reported items 47-57.**
+
+### Bugs
+
+- **#48 report self-describing header.** `report executive` / `technical` / `compliance` previously emitted identical `# exceptd Security Assessment Report` headers — only stderr (`[orchestrator] Generating <X> report`) distinguished them, so a piped-to-file report had no internal provenance. Now: `# exceptd Executive Report` / `Technical Report` / `Compliance Report` + an HTML-comment marker (`<!-- exceptd-report:flavor=<x> version=<v> -->`) inside the body. Saved files are self-describing.
+- **#50 mutex cross-process enforcement.** `_meta.mutex` was documented but only enforced intra-process (in-memory `_activeRuns` Set). Two parallel `exceptd run kernel` + `exceptd run hardening` invocations in separate shells would race. Now: runner writes a `.exceptd/locks/<playbook>.lock` JSON file (pid + started_at) for the duration of the run; preflight rejects with `blocked_by: mutex` when a non-stale lock exists. Stale locks (dead pid) are auto-GC'd. Released in `finally`.
+- **#51 deprecation message version-aware.** The banner used to say "Prefer `brief --all` (v0.11.0)" unconditionally; operators on v0.10.x reading it would find no `brief` command in their install. Now: banner shows the installed version explicitly and conditionally emits "available in this install" vs "upgrade to v0.11.0+ first."
+- **#47 / #49 exit-code + skill-not-found shapes.** Verified still correct in v0.11.0 — exit 1 on `ok:false`, JSON shape for `skill <missing>`. No regression; added regression test coverage.
+
+### Features
+
+- **#54 `--json-stdout-only`** — silences ALL stderr emissions (deprecation banners, unsigned-attestation warnings, hook output). Operators piping JSON results through `jq` or scripting exit codes get clean stdout exclusively. Real errors (uncaught exceptions starting with "Error") still pass through.
+- **#55 `report csaf`** — emits a CSAF 2.0 envelope of the full assessment (findings + dispatch plan + skill currency + host context). Pipes directly into VEX downstream tooling.
+- **#57 default-stdin on pipe.** `exceptd run <playbook>` now auto-detects piped stdin (`process.stdin.isTTY === false`) and assumes `--evidence -`. Operators forgetting the flag no longer hit a precondition halt.
+
+### Already-existing surface (cross-referenced in operator report)
+
+- #52 brief lands before deprecating look — already shipped in v0.11.0
+- #53 doctor verb — already shipped in v0.11.0
+- #56 cross-session diff — already exists as `attest diff <a-sid> --against <b-sid>` (v0.11.0)
+
 ## 0.11.0 — 2026-05-12
 
 **Minor: architectural CLI redesign — 21 verbs collapsed to 11. Plus operator-reported items 31-46.**

package/README.md

@@ -32,7 +32,9 @@ This platform surfaces what is actually happening right now. Every skill explici
 
 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.
 
-**v0.10.0 introduces 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). The runner enforces `threat_currency_score` gates, evaluates per-playbook preconditions, honors mutex sets, picks priority-ordered remediation paths, builds CSAF-2.0 evidence bundles (Ed25519-signed by default), computes ISO 8601 notification deadlines from jurisdiction `clock_starts` events, and generates auditor-ready policy-exception language when remediation cannot complete within compliance windows. See `lib/schemas/playbook.schema.json` for the contract and AGENTS.md "Seven-phase playbook contract" for the host-AI invocation guide. Legacy `exceptd scan` remains for non-AI operators with a deprecation banner — to be removed in v1.0.
+**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.
 
 ---
 
@@ -174,71 +176,141 @@ Direct invocations also available: `npm run verify`, `node lib/sign.js sign-all`
 
 Every command works the same via `npx @blamejs/exceptd-skills`, a global install (`exceptd`), or a local `node bin/exceptd.js`.
 
-```
-exceptd path                          Print absolute path to the installed package.
-
-exceptd prefetch [args]               Warm local cache of upstream artifacts.
-  --max-age 24h                       Skip entries fresher than this.
-  --source kev,nvd                    Comma-separated source filter.
-  --force                             Ignore freshness; refetch everything.
-  --no-network                        Dry-run plan; do not actually fetch.
-
-exceptd refresh [args]                Refresh upstream data; optionally apply upserts.
-  --apply                             Write diffs back to data/*.json and rebuild indexes.
-  --from-cache [<dir>]                Read from prefetch cache instead of upstream.
-  --swarm                             Fan-out across worker threads.
-  --source kev,epss,nvd,rfc,pins      Scope by source.
-  --from-fixture <dir>                Test mode — read frozen fixtures.
-  --report-out <path>                 Redirect refresh-report.json output.
-
-exceptd build-indexes [args]          Rebuild data/_indexes/*.json (17 outputs).
-  --only <names>                      Comma-separated subset (auto-pulls in dependencies).
-  --changed                           Rebuild only outputs whose deps changed.
-  --parallel                          Run independent outputs concurrently.
-
-exceptd verify                        Verify Ed25519 signature on every skill.
-                                      Prints dual SHA-256 + SHA3-512 fingerprint
-                                      of keys/public.pem so operators can pin
-                                      the key out-of-band.
-exceptd scan                          Scan environment for findings — includes
-                                      a 22-algorithm PQC probe (NIST finalized
-                                      ML-KEM/ML-DSA/SLH-DSA, draft FN-DSA + HQC,
-                                      Round-4 alternates Frodo/NTRU/McEliece/BIKE,
-                                      signature on-ramp Hawk/Mayo/SQIsign/CROSS/
-                                      UOV/SDitH/Mirath/FAEST/Perk, stateful
-                                      LMS/XMSS/HSS, IETF composite sigs + KEMs).
-exceptd dispatch                      Scan then route findings to skills. Plan
-                                      entries surface per-CVE evidence (IDs +
-                                      RWEP scores), not aggregate counts.
-exceptd skill <name>                  Show context for a specific skill.
-exceptd currency                      Skill currency report. Score is age-only
-                                      (forward_watch count does NOT reduce score
-                                      — it's a maintenance signal).
-exceptd report [executive|technical|compliance]   Generate report. Executive
-                                      summary splits currency into named tiers
-                                      (critical-stale <50%, stale 50-69%).
-exceptd framework-gap <FW> <SCENARIO> [--json]
-                                      Programmatic runner for the framework-gap
-                                      skill. Lists matching control gaps,
-                                      universal gaps, and theater-risk controls.
-                                      Examples:
-                                        exceptd framework-gap NIST-800-53 CVE-2026-31431
-                                        exceptd framework-gap PCI-DSS-4.0 "prompt injection"
-                                        exceptd framework-gap all CVE-2025-53773 --json
-exceptd validate-cves [args]          Cross-check CVE catalog vs NVD/KEV/EPSS.
-  --offline                           Local view only; no network.
-  --from-cache [<dir>]                Cache-first lookups with live fallback.
-  --no-fail                           Report drift without failing exit code.
-exceptd validate-rfcs [args]          Cross-check RFC catalog vs IETF Datatracker.
-  --offline                           Local view only; no network.
-  --from-cache [<dir>]                Cache-first lookups with live fallback.
-  --no-fail                           Report drift without failing exit code.
-exceptd watchlist [--by-skill]        Forward-watch aggregator across skills.
+### v0.11.0 canonical verbs
 
+```
+exceptd                               First-run welcome — two ways to start
+                                      (discover / ask) plus common starting
+                                      playbooks for code / Linux / service contexts.
+
+exceptd discover                      Scan cwd → recommend playbooks based on
+                                      detected files (.git, package.json,
+                                      Dockerfile, requirements.txt, etc) + host
+                                      platform. Replaces scan + dispatch.
+  --scan-only                         Also include legacy host scan findings.
+  --json | --pretty                   Machine output (default is human checklist).
+
+exceptd brief [playbook]              Unified info doc — jurisdictions + threat
+                                      context + RWEP thresholds + preconditions
+                                      + artifacts + indicators. Replaces plan +
+                                      govern + direct + look.
+  --all                               Every playbook (replaces `plan`).
+  --scope <type>                      system | code | service | cross-cutting.
+  --directives                        Expand directive metadata per playbook.
+  --phase <name>                      Emit only one phase (legacy compat).
+
+exceptd run [playbook]                Phases 4-7. Auto-detects cwd context when
+                                      no playbook positional.
+  --evidence <file|->                 Submission JSON (flat or nested shape).
+  --evidence-dir <dir>                Per-playbook submission files (cron-friendly).
+  --scope <type> | --all              Multi-playbook run.
+  --vex <file>                        CycloneDX / OpenVEX filter (drop not_affected).
+  --format <fmt> ...                  csaf-2.0 | sarif | openvex | markdown | summary.
+                                      Repeatable. CSAF is primary; extras go to
+                                      close.evidence_package.bundles_by_format.
+  --diff-from-latest                  Drift vs prior attestation for same playbook.
+  --ci                                Exit-code gate (use `exceptd ci` instead).
+  --operator <name>                   Bind attestation to identity.
+  --ack                               Explicit jurisdiction-obligation consent.
+  --session-id <id>                   Reuse session id (collision refused).
+  --force-overwrite                   Override session collision refusal.
+  --session-key <hex>                 HMAC sign evidence_package (≥ 16 hex chars).
+  --attestation-root <path>           Override ~/.exceptd/attestations/ root.
+  --explain                           Dry-run: preconditions + artifacts +
+                                      signal keys + submission skeleton.
+  --signal-list                       Lighter than --explain; enumerate signal
+                                      keys only.
+  --force-stale                       Override threat_currency_score < 50 gate.
+  --air-gap                           Honor air_gap_alternative paths.
+
+exceptd ai-run <playbook>             JSONL streaming variant of run. AI emits
+                                      evidence events on stdin; runner streams
+                                      phase events on stdout. One pipe, no
+                                      file handoff.
+  --no-stream                         Single-shot mode (emit one combined JSON).
+
+exceptd attest <subverb> [<sid>]      Auditor-facing operations.
+  attest list                         Inventory all sessions across both
+                                      ~/.exceptd and cwd-legacy roots.
+  attest show <sid>                   Full (unredacted) attestation.
+  attest export <sid>                 Redacted bundle for audit submission.
+                                      Strips raw artifact values; preserves
+                                      evidence_hash + signature + verdict.
+                                      --format csaf wraps in CSAF envelope.
+  attest verify <sid>                 Ed25519 .sig sidecar verification.
+  attest diff <sid>                   Drift replay (= reattest default).
+                                      --against <other-sid> compares two
+                                      sessions side-by-side with per-artifact
+                                      diff (added / removed / changed).
+  --playbook <id>                     Filter (list / diff).
+  --since <ISO>                       Filter list / diff to entries after date.
+
+exceptd discover / doctor / ci        See above for doctor and ci.
+
+exceptd doctor                        One-shot health check.
+  --signatures                        Only Ed25519 skill verification.
+  --currency                          Only skill currency report.
+  --cves                              Only CVE catalog drift check.
+  --rfcs                              Only RFC catalog drift check.
+
+exceptd ci                            One-shot CI gate. Exits 2 on detected or
+                                      rwep ≥ rwep_threshold.escalate.
+  --all | --scope <type>              Pick playbooks; auto-detect if neither.
+  --max-rwep <n>                      Cap below playbook default.
+  --block-on-jurisdiction-clock       Fail when notification clock fires.
+  --evidence / --evidence-dir         Per-playbook submission files.
+
+exceptd ask "<question>"              Plain-English routing to playbook(s).
+                                      Returns ranked playbook IDs based on
+                                      keyword overlap with each playbook's
+                                      domain.name + attack_class + threat_context.
+
+exceptd lint <pb> <evidence>          Pre-flight check submission shape vs
+                                      playbook (preconditions / artifacts /
+                                      indicators) without executing phases 4-7.
+
+exceptd refresh                       Refresh upstream catalogs + indexes.
+                                      Replaces prefetch + refresh + build-indexes.
+  --apply                             Write diffs back + rebuild indexes.
+  --from-cache [<dir>]                Read from prefetch cache.
+  --no-network                        Dry-run.
+  --indexes-only                      Rebuild data/_indexes/*.json only.
+
+exceptd skill <name>                  Show context for one skill.
+exceptd framework-gap <FW> <ref>      One framework + one CVE/scenario, JSON
+                                      or human. (Operates outside the seven-
+                                      phase contract for ad-hoc gap analysis.)
+exceptd path                          Absolute path to the installed package.
 exceptd version                       Package version.
 exceptd help                          This help.
+exceptd <verb> --help                 Per-verb usage with flag descriptions.
 ```
 
+### Legacy v0.10.x verbs (deprecated, removed in v0.12)
+
+These still work but emit a one-time deprecation banner per process:
+
+| Legacy verb | v0.11.0 replacement |
+|---|---|
+| `plan` | `brief --all` |
+| `govern <pb>` | `brief <pb> --phase govern` |
+| `direct <pb>` | `brief <pb> --phase direct` |
+| `look <pb>` | `brief <pb> --phase look` |
+| `scan` | `discover --scan-only` |
+| `dispatch` | `discover` |
+| `currency` | `doctor --currency` |
+| `verify` | `doctor --signatures` |
+| `validate-cves` | `doctor --cves` |
+| `validate-rfcs` | `doctor --rfcs` |
+| `ingest` | `run` |
+| `reattest <sid>` | `attest diff <sid>` |
+| `list-attestations` | `attest list` |
+| `watchlist` | (no replacement yet — kept) |
+| `prefetch` | `refresh --no-network` |
+| `build-indexes` | `refresh --indexes-only` |
+
+Suppress the deprecation banner: `EXCEPTD_DEPRECATION_SHOWN=1`.
+
 ## Invoking a skill from your AI assistant
 
 Once your assistant has loaded `AGENTS.md`, type a trigger phrase or skill name: