@blamejs/exceptd-skills 0.10.3 → 0.11.1

package/CHANGELOG.md

@@ -1,5 +1,111 @@
 # Changelog
 
+## 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.**
+
+### New canonical surface
+
+| New verb | Replaces |
+|---|---|
+| `brief [playbook]` | plan + govern + direct + look |
+| `run [playbook]` | run + ingest (unchanged but with flat submission shape) |
+| `ai-run <playbook>` | new — JSONL streaming variant for AI conversational flow |
+| `attest <subverb> <sid>` | reattest + list-attestations (now `attest diff` + `attest list`) |
+| `discover` | scan + dispatch (recommends playbooks based on cwd) |
+| `doctor` | currency + verify + validate-cves + validate-rfcs + signing-status |
+| `ci` | new — one-shot CI gate |
+| `ask "<question>"` | new — plain-English routing to playbook(s) |
+| `lint <playbook> <evidence>` | new — pre-flight submission shape check |
+| `verify-attestation <sid>` | alias for `attest verify` |
+| `run-all` | alias for `run --all` |
+
+`exceptd` with no args now prints a welcome with two ways to start (`discover` / `ask`) plus common starting playbooks for code / Linux / AI service contexts.
+
+### Default output flip
+
+Old default was JSON one-line; `--pretty` for humans. Reads weird for the operator audience. v0.11.0 flips:
+
+- **Default: human-readable** (5-10 line summary per phase) for `discover` / `doctor` / `ci` / others.
+- `--json` for machine consumption.
+- `--json --pretty` for indented JSON.
+
+Seven-phase verbs (`brief` / `run`) still emit JSON by default since their consumers are predominantly AI assistants and CI pipelines — switching them would break every existing script.
+
+### Flat submission shape
+
+The runner now accepts a flatter submission shape — one row per observation, indicator inline:
+
+```json
+{
+  "observations": {
+    "env-files":   { "captured": true, "value": "none tracked", "indicator": "env-file-leak", "result": "no_hit" },
+    "repo-context": "ok"
+  },
+  "verdict": { "theater": "actual_security", "classification": "clean", "blast_radius": 0 }
+}
+```
+
+Nested v0.10.x shape (`artifacts` / `signal_overrides` / `signals` / `precondition_checks`) still works — the runner normalizes either shape internally.
+
+### Smart precondition auto-detect
+
+Mechanically-answerable preconditions (`host.platform == 'linux'`, `cwd_readable`, `agent_has_command('uname')`) are now resolved by the runner itself. The AI only declares preconditions that require intent ("operator authorized this scan"). Reduces evidence-JSON friction by ~80% for typical runs.
+
+### Attestation root relocated
+
+Default attestation root moved from cwd-relative `.exceptd/attestations/` to `~/.exceptd/attestations/<repo-or-host-tag>/`. Repo tag is derived from `git config --get remote.origin.url` + branch when in a git repo, else `host:<hostname>`. Means `attest list` works regardless of which directory you happened to run from.
+
+Override via:
+- `--attestation-root <path>` flag
+- `EXCEPTD_HOME` env var (uses `$EXCEPTD_HOME/attestations/`)
+- Legacy cwd-relative `.exceptd/` still scanned by `attest list` / `findSessionDir` so prior data isn't orphaned.
+
+### Bug fixes (operator-reported items 31-46)
+
+- **#31 / #41 session-id collision** — Pre-0.11.0 a `--session-id` collision silently overwrote the prior attestation (data loss + tamper-evidence violation). Now refuses with exit 3 by default; `--force-overwrite` allows replacement and persists `prior_evidence_hash` + `prior_captured_at` so the audit chain survives.
+- **#32 `--mode` validation** — was silently accepting any string. Now validates against `[self_service, authorized_pentest, ir_response, ctf, research, compliance_audit]`.
+- **#33 `--session-key` hex validation** — was silently accepting any string. Now requires hex (0-9, a-f) and a minimum length of 16.
+- **#34 reattest no artifact diff** — `attest diff <sid> --against <other-sid>` (or `reattest` default replay) now emits per-artifact diff: `{added, removed, changed, unchanged_count}` with value previews. Per-signal-override diff also included.
+- **#35 validate-cves crash** — `sources/validators/` was missing from package.json `files` allowlist. Fixed in v0.10.3; still re-tested in v0.11.0.
+- **#36 unsigned attestation warning** — Runs without `.keys/private.pem` now emit one stderr warning per process: "attestation will be written UNSIGNED — enable Ed25519 signing: node lib/sign.js generate-keypair". Suppress with `EXCEPTD_UNSIGNED_WARNED=1`.
+
+### Feature additions (operator items)
+
+- **#38 `lint <playbook> <evidence>`** — Pre-flight check: detects missing required artifacts, unknown signal keys, unsupplied preconditions. Operators iterate on submission JSON before paying the phase-4-7 cost.
+- **#39 `run --format summary`** — 5-line digest emit format for CI workflows (verdict + RWEP + blast + remediation).
+- **#43 reattest cross-session compare** — `attest diff <a-sid> --against <b-sid>` now compares two sessions side-by-side instead of always replaying the same submission.
+- **#46 plan / brief description always present** — Directive entries in plan output now always include a `description` field (falls back through `directive.description` → playbook `direct.threat_context` first sentence → `domain.name`).
+
+### Deprecation
+
+v0.10.x verbs (`plan` / `govern` / `direct` / `look` / `ingest` / `reattest` / `list-attestations` / `scan` / `dispatch` / `currency` / `verify` / `validate-cves` / `validate-rfcs` / `watchlist` / `prefetch` / `build-indexes`) still work but emit a one-time deprecation banner per process pointing at the v0.11.0 replacement. Removed in v0.12.
+
+Suppress the deprecation banner: `EXCEPTD_DEPRECATION_SHOWN=1`.
+
 ## 0.10.3 — 2026-05-12
 
 **Patch: 14 operator-reported items — 5 bugs + 9 features.**

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: