@blamejs/exceptd-skills 0.13.126 → 0.14.1

package/AGENTS.md

@@ -8,7 +8,7 @@ Also read [CONTEXT.md](CONTEXT.md) for a complete orientation to the skill syste
 
 Each rule below carries a **Forcing function** annotation declaring whether it is mechanically enforced by a script in the predeploy / CI gate sequence, or whether it is policy-only (reviewer trust). Policy-only rules are not weaker — they are auditable through reviewer judgment, not via a script — but operators should know which class a given rule sits in.
 
-1. **No stale threat intel** — Every CVE reference must include: CVSS score, KEV status, PoC availability, AI-discovery flag, active exploitation status, and patch/live-patch availability. No theoretical vulnerabilities without real-world grounding.
+1. **No stale threat intel** — Every CVE reference must include: CVSS score, KEV status, PoC availability, AI-discovery flag, active exploitation status, and patch/live-patch availability. No theoretical vulnerabilities without real-world grounding. When validating a CVE or RFC citation during security work, the canonical move is `exceptd cve <CVE-ID>` / `exceptd rfc <number>` — it resolves the citation and caches the result, so a multi-agent fan-out resolves each id once rather than re-researching it independently against NVD/the datatracker.
    *Forcing function:* enforced by `lib/validate-cve-catalog.js` (predeploy gate).
 
 2. **Framework lag is a first-class concept** — Every skill must explicitly declare which framework controls are insufficient for the threats it covers. Never imply a framework control is adequate when current TTPs bypass it.
@@ -156,7 +156,7 @@ Cross-cutting playbook `framework` is the natural correlation layer — many pla
 
 | Verb | What it does |
 |---|---|
-| `exceptd brief --all` | Grouped-by-scope summary of all 23 playbooks. `--scope <type>` filters. `--directives` expands directive IDs/titles per playbook. `--flat` for non-grouped. `exceptd plan` was removed in v0.13.0; invoking it returns a structured `ok:false` refusal pointing at this command. |
+| `exceptd brief --all` | Grouped-by-scope summary of all 24 playbooks. `--scope <type>` filters. `--directives` expands directive IDs/titles per playbook. `--flat` for non-grouped. `exceptd plan` was removed in v0.13.0; invoking it returns a structured `ok:false` refusal pointing at this command. |
 | `exceptd brief <pb>` | Phase 2 threat-context briefing — threat context, RWEP thresholds, skill chain, token budget, jurisdiction obligations. |
 | `exceptd run <pb> --evidence <file>` | Phases 5-7 (analyze + validate + close) from agent evidence. Auto-detect cwd when no playbook positional. `--vex <file>` drops CycloneDX/OpenVEX `not_affected` CVEs. `--diff-from-latest` for drift mode. `--force-stale` overrides currency hard-block. |
 | `exceptd ai-run <pb>` | Streaming variant of `run` for AI agents; emits phase-by-phase NDJSON. |
@@ -169,6 +169,8 @@ Cross-cutting playbook `framework` is the natural correlation layer — many pla
 | `exceptd attest list` | Inventory `.exceptd/attestations/` — newest first. `--playbook <id>` filters. |
 | `exceptd attest show <sid>` | Print the attestation body. |
 | `exceptd doctor` | Health checks. `--signatures` verifies Ed25519 chains; `--cves` / `--rfcs` check catalog currency; `--fix` repairs recoverable state; `--ai-config` audits AI-assistant config-file permissions (`~/.claude`, `~/.cursor`, `~/.codeium`, `~/.aider`, `~/.continue`) and flags sensitive files not at mode `0o600` on POSIX (NEW-CTRL-050). |
+| `exceptd cve <CVE-ID>` | Resolve a single CVE citation — returns status (`published`/`rejected`/`disputed`/`fabricated`/`nonexistent`/`unknown`) plus cvss/kev/product. Resolution order: curated catalog (offline) → resolved cache (`.cache/upstream/resolved/`, 7-day TTL) → one NVD lookup, then cached. `--air-gap`/`--no-network`/`EXCEPTD_AIR_GAP=1` force offline-only (returns `unknown` with a reason). Exit 2 when the citation won't stand up (rejected/fabricated/nonexistent/withdrawn). |
+| `exceptd rfc <number>` | Resolve an RFC number → title + status from the local index (whole current series, offline). `--check "<title>"` reports `title_match` true/false, exit 2 on mismatch (catches e.g. RFC 9404 cited as the Sieve spec — it's JMAP Blob Management). Not-found numbers are likely obsoleted/historic or nonexistent; with network it disambiguates via the datatracker. |
 | `exceptd lint` | Skill format lint — frontmatter completeness, required body sections, signature presence. |
 | `exceptd refresh --check-advisories` | Poll 15 primary-source advisory feeds — 8 advisory/coordinated-disclosure venues (Qualys TRU, Red Hat RHSA, Ubuntu USN, ZDI, kernel.org commits, oss-security mailing list, JFrog SecOps, CISA current advisories), 4 vendor security research blogs (Microsoft Security Blog, Sysdig, Trail of Bits, Embrace the Red — added in v0.13.14 after DirtyDecrypt fell through the advisory-only set), and 3 sources added in v0.13.17 (BleepingComputer security, The Hacker News, Nightmare-Eclipse GitLab activity-feed tracker, migrated from GitHub after the account was removed — closes the researcher-drop class anchored by MiniPlasma / YellowKey / GreenPlasma / UnDefend, NEW-CTRL-073). Pairs with `lib/cve-regression-watcher.js` (NEW-CTRL-074) which cross-checks poller diffs for historical-CVE references that may indicate silent vendor regression — the class anchored by MiniPlasma re-breaking CVE-2020-17103. Report-only; emits structured `diffs[]` without mutating the catalog. Route promising IDs through `refresh --advisory <CVE-ID> --apply` to enrich. |
 | `exceptd watchlist` | Default: aggregate every skill's `forward_watch` entries. `--by-skill` inverts grouping. `--alerts` switches to CVE-catalog pattern alerts (5 patterns: `kernel_lpe_with_poc`, `supply_chain_family`, `ai_discovered_kev`, `active_exploitation_unpatched`, `recent_poc_no_kev_yet`); sorts critical-first, then by RWEP. `--org-scan --org <login>` probes GitHub Search for repos matching threat-actor naming patterns ("A Gift From TeamPCP", "Shai-Hulud", "TeamPCP"); custom patterns via repeatable `--pattern <s>`; set `GITHUB_TOKEN` for private-repo + rate-limit headroom (NEW-CTRL-052). |
@@ -372,7 +374,7 @@ This split costs every consumer the same translation work on every invocation. C
 exceptd collect secrets | exceptd run secrets --evidence -
 ```
 
-The collector library is small and grows as playbooks are touched. Thirteen reference collectors ship today (`lib/collectors/secrets.js`, `lib/collectors/kernel.js`, `lib/collectors/sbom.js`, `lib/collectors/containers.js`, `lib/collectors/library-author.js`, `lib/collectors/crypto-codebase.js`, `lib/collectors/cred-stores.js`, `lib/collectors/hardening.js`, `lib/collectors/runtime.js`, `lib/collectors/ai-api.js`, `lib/collectors/mcp.js`, `lib/collectors/crypto.js`, `lib/collectors/cicd-pipeline-compromise.js`); the rest are written when each playbook needs them. Until a playbook has a collector, the AI/operator owns evidence collection as before.
+The collector library is small and grows as playbooks are touched. Fourteen reference collectors ship today (`lib/collectors/secrets.js`, `lib/collectors/kernel.js`, `lib/collectors/sbom.js`, `lib/collectors/containers.js`, `lib/collectors/library-author.js`, `lib/collectors/crypto-codebase.js`, `lib/collectors/cred-stores.js`, `lib/collectors/hardening.js`, `lib/collectors/runtime.js`, `lib/collectors/ai-api.js`, `lib/collectors/mcp.js`, `lib/collectors/crypto.js`, `lib/collectors/cicd-pipeline-compromise.js`, `lib/collectors/citation-hygiene.js`); the rest are written when each playbook needs them. Code-scope collectors share `lib/collectors/scan-excludes.js`, which skips dependency/build caches, agent scratch (`.claude`), and linked git worktrees so a tree holding detached worktree copies isn't scanned N times. Until a playbook has a collector, the AI/operator owns evidence collection as before.
 
 ### Precision target for new `look.artifacts[].source` strings
 

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 0.14.1 — 2026-05-27
+
+Two citation resolvers — `exceptd cve <id>` and `exceptd rfc <number>` — answer "is this CVE/RFC citation valid?" so an agent gets the answer from exceptd instead of researching each identifier against NVD or the IETF datatracker by hand. A fan-out of agents auditing a codebase previously re-researched the same citations independently; these resolvers do it once and cache the result for the rest.
+
+`exceptd cve <id>` returns a structured status — published, rejected, disputed, fabricated, nonexistent, or unknown — alongside CVSS / KEV / product. It resolves offline-first: the curated catalog, then a resolved cache, then a single NVD lookup whose result is cached under `.cache/upstream/resolved/` (7-day TTL). The first lookup of an uncatalogued identifier serves every later agent and every offline run. NVD's authoritative `vulnStatus` and `cveTags` are now read — they were previously fetched and discarded — so a rejected or disputed CVE is flagged rather than treated as valid (the class that lets a withdrawn identifier sit cited in a codebase unnoticed). A non-canonical identifier such as `CVE-2024-XXXX` is caught as fabricated with no network call. Network is opt-out: `--air-gap`, `--no-network`, or `EXCEPTD_AIR_GAP=1` keep resolution offline-only and return `unknown` with a reason. Exit code 2 when a citation will not stand up.
+
+`exceptd rfc <number>` resolves an RFC number to its title and status from the local index — the whole current RFC series, fully offline. `--check "<claimed title>"` reports whether a claimed title matches the real one (exit code 2 on mismatch), catching an RFC number cited under the wrong specification.
+
+Catalog entries may now carry a structured `status` field (`published` / `rejected` / `disputed` / `withdrawn` / `reserved`), sourced from NVD `vulnStatus` / `cveTags` or OSV / GHSA `withdrawn`, replacing the prior free-text heuristic. The `citation-hygiene` playbook now routes its "needs external verification" guidance through `exceptd cve` / `exceptd rfc`.
+
+## 0.14.0 — 2026-05-26
+
+New playbook — `citation-hygiene`. Validates a codebase's own cited security references: it scans source, comments, and docs for CVE and RFC citations and flags fabricated CVE IDs (the non-numeric `CVE-2024-XXXX` form), catalog-rejected/disputed CVEs, and RFC number-vs-title mismatches. Well-formed CVE IDs absent from the curated catalog are routed to an inconclusive "needs external verification" result rather than a false clear or a false fabrication flag. Ships with a companion collector — `exceptd collect citation-hygiene | exceptd run citation-hygiene --evidence -`. The catalog now holds 24 playbooks.
+
+Unknown flags are refused on every verb. Previously only `doctor` rejected an unrecognized flag; every other verb silently ignored it, so a typo like `--max-rweap 70` or `--fromat sarif` looked like it applied a cap or a format when it did nothing. Each verb now exits 1 with the accepted-flag list and a did-you-mean suggestion. A flag that is valid on another verb (e.g. `--csaf-status` on `brief`) still gets its tailored "that flag belongs on a run-class verb" guidance instead of a blanket refusal.
+
+`exceptd run --format json` now emits the full run result. It previously discarded the result and printed a short "unknown format" stub with a success exit code. SARIF, CSAF, and OpenVEX bundles are now emitted as spec-conformant documents — the internal `ok` envelope key is no longer prepended, so strict validators (GitHub code-scanning SARIF upload, CSAF trusted-provider checks) accept the output. Passing several `--format` values prints a note to stderr pointing at `bundles_by_format` rather than silently dropping all but the first.
+
+`exceptd collect <pb> | exceptd run <pb> --evidence -` works again. `collect` now emits JSON when its stdout is a pipe (the human summary is reserved for an interactive terminal), so the documented one-liner no longer feeds a prose summary into `run`.
+
+`exceptd refresh --check-advisories` polls the primary-source advisory feeds as documented (report-only; emits `diffs[]`) instead of being silently ignored.
+
+`skill --help` and `framework-gap --help` print usage instead of erroring.
+
+`exceptd attest list --limit <n>` caps the inventory; the JSON envelope reports the unfiltered total alongside the shown count.
+
+Code-scope collectors skip agent scratch (`.claude`) and linked git worktrees. A working tree holding detached worktree copies was scanned once per copy, inflating hash and secret counts with duplicates of the same files. The `library-author` collector now recognizes release-time SBOM generation, npm provenance, and sigstore/cosign signing, and `id-token: write` declared at job scope — so a well-run publisher no longer gets false "SBOM absent" or "no OIDC" findings from artifacts that are produced at release time.
+
+Documentation: the `ci` exit-code contract (0–5), the `osv` refresh source, and the full `--format` vocabulary are corrected in `--help` and README; the deprecated-alias help no longer claims a one-time banner it does not emit, and `reattest` / `list-attestations` are documented as canonical short forms rather than deprecated aliases.
+
 ## 0.13.126 — 2026-05-26
 
 CVE catalog — n8n Git-node RCE. Adds **CVE-2026-21877**, completing the n8n critical cluster. In versions ≥ 0.123.0 and < 1.121.3, an authenticated user abuses the Git node to write a file of a dangerous type to an arbitrary path, which is then executed — yielding remote code execution and full compromise of both self-hosted and Cloud instances (CWE-434 unrestricted upload chained to CWE-94; GitHub CNA CVSS v3.1 9.9). Fixed in 1.121.3. Reuses the AI-app-builder execution-endpoint auth-and-sandbox control (NEW-CTRL-103), which now also covers file-writing workflow nodes as code-execution sinks. CVE count 419 → 420.

package/README.md

@@ -30,7 +30,7 @@ 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) with signed npm provenance attestation and Ed25519-signed skill bodies. The package ships 42 skills across kernel LPE, MCP supply chain, AI-as-C2, prompt injection, post-quantum crypto, SBOM integrity, identity-incident response, and 35 other AI/security domains, plus 10 intelligence catalogs (CVE / ATLAS / ATT&CK / CWE / D3FEND / DLP / RFC / framework gaps / global frameworks / zero-day lessons) covering 35 jurisdictions — the CVE catalog has grown past 400 entries, its size anchored by a v0.13.17 CISA KEV bulk-intake of `dateAdded >= 2024-01-01` actively-exploited vulnerabilities that took it from 68 to 312 in a single pass. 23 investigation playbooks (kernel, MCP, AI-API, framework, SBOM, runtime, hardening, secrets, cred-stores, containers, crypto, plus `webhook-callback-abuse`, `cicd-pipeline-compromise`, `identity-sso-compromise`, `llm-tool-use-exfil`, `post-quantum-migration`, `ai-discovered-cve-triage`, `supply-chain-recovery`, and more), a CLI for discovery and seven-phase investigation runs (`govern → direct → look → detect → analyze → validate → close`), and a nightly auto-refresh job that pulls KEV / NVD / EPSS / GHSA / OSV / IETF deltas plus 15 primary-source advisory + research-blog + tech-press feeds (Qualys TRU, Red Hat RHSA, Ubuntu USN, ZDI, kernel.org, oss-security, JFrog, CISA, Microsoft Security Blog, Sysdig, Trail of Bits, Embrace the Red, BleepingComputer security, The Hacker News, and a GitLab activity-feed tracker for the Nightmare-Eclipse researcher handle that anchors NEW-CTRL-073) into auto-PRs for editorial review. v0.13.17 also ships `lib/cve-regression-watcher.js` (NEW-CTRL-074) — a complementary detection method that surfaces poller-diff historical-CVE references as candidate silent-regression cases, the class anchored by MiniPlasma (a 2026 PoC drop that re-broke CVE-2020-17103 without any new ID being assigned).
+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) with signed npm provenance attestation and Ed25519-signed skill bodies. The package ships 42 skills across kernel LPE, MCP supply chain, AI-as-C2, prompt injection, post-quantum crypto, SBOM integrity, identity-incident response, and 35 other AI/security domains, plus 10 intelligence catalogs (CVE / ATLAS / ATT&CK / CWE / D3FEND / DLP / RFC / framework gaps / global frameworks / zero-day lessons) covering 35 jurisdictions — the CVE catalog has grown past 400 entries, its size anchored by a v0.13.17 CISA KEV bulk-intake of `dateAdded >= 2024-01-01` actively-exploited vulnerabilities that took it from 68 to 312 in a single pass. 24 investigation playbooks (kernel, MCP, AI-API, framework, SBOM, runtime, hardening, secrets, cred-stores, containers, crypto, plus `webhook-callback-abuse`, `cicd-pipeline-compromise`, `identity-sso-compromise`, `llm-tool-use-exfil`, `post-quantum-migration`, `ai-discovered-cve-triage`, `supply-chain-recovery`, `citation-hygiene`, and more), a CLI for discovery and seven-phase investigation runs (`govern → direct → look → detect → analyze → validate → close`), and a nightly auto-refresh job that pulls KEV / NVD / EPSS / GHSA / OSV / IETF deltas plus 15 primary-source advisory + research-blog + tech-press feeds (Qualys TRU, Red Hat RHSA, Ubuntu USN, ZDI, kernel.org, oss-security, JFrog, CISA, Microsoft Security Blog, Sysdig, Trail of Bits, Embrace the Red, BleepingComputer security, The Hacker News, and a GitLab activity-feed tracker for the Nightmare-Eclipse researcher handle that anchors NEW-CTRL-073) into auto-PRs for editorial review. v0.13.17 also ships `lib/cve-regression-watcher.js` (NEW-CTRL-074) — a complementary detection method that surfaces poller-diff historical-CVE references as candidate silent-regression cases, the class anchored by MiniPlasma (a 2026 PoC drop that re-broke CVE-2020-17103 without any new ID being assigned).
 
 ---
 
@@ -156,13 +156,13 @@ Fresh-disclosure workflow (v0.12.0): the nightly auto-PR job pulls KEV / NVD / E
 
 Primary-source advisory polling: `exceptd refresh --check-advisories` polls 15 vendor and coordinated-disclosure feeds — 8 advisory/coordinated-disclosure venues (Qualys TRU, Red Hat RHSA, Ubuntu USN, Zero Day Initiative, kernel.org commits, oss-security mailing list, JFrog SecOps, CISA current advisories), 4 vendor security research blogs added in v0.13.14 (Microsoft Security Blog, Sysdig, Trail of Bits, Embrace the Red), and 3 additions in v0.13.17 (BleepingComputer security, The Hacker News, and a GitLab activity-feed tracker for the Nightmare-Eclipse researcher handle that anchors NEW-CTRL-073). Combined coverage publishes CVE IDs at T+0 to T+1 — typically 3–14 days ahead of NVD enrichment. The command is report-only: it returns a structured `diffs[]` listing each newly-seen CVE ID with its source attributions and advisory URLs, but does not mutate the catalog. v0.13.17 also adds a complementary detection method (NEW-CTRL-074 / `lib/cve-regression-watcher.js`): the watcher cross-checks poller diffs for historical-CVE references (year ≤ currentYear − 2) and surfaces candidate silent-regression cases — the class anchored by MiniPlasma (a 2026 PoC drop that re-broke CVE-2020-17103 without any new ID being assigned). Operators triage the output and route promising IDs through `exceptd refresh --advisory <CVE-ID> --apply`. Pairs naturally with the daily scheduled remote agent below.
 
-CVE-class alert surfacing: `exceptd watchlist --alerts` matches the live `cve-catalog.json` against five operational patterns (`kernel_lpe_with_poc`, `supply_chain_family`, `ai_discovered_kev`, `active_exploitation_unpatched`, `recent_poc_no_kev_yet`) and returns the matches sorted critical-severity-first, then by RWEP. Use as a fast operational triage on a refreshed catalog without scanning every entry by hand.
+CVE-class alert surfacing: `exceptd watch --alerts` matches the live `cve-catalog.json` against five operational patterns (`kernel_lpe_with_poc`, `supply_chain_family`, `ai_discovered_kev`, `active_exploitation_unpatched`, `recent_poc_no_kev_yet`) and returns the matches sorted critical-severity-first, then by RWEP. Use as a fast operational triage on a refreshed catalog without scanning every entry by hand.
 
-GitHub repo-pattern monitoring: `exceptd watchlist --org-scan --org <login>` probes GitHub Search for repositories matching known threat-actor naming patterns ("A Gift From TeamPCP", "Shai-Hulud", "TeamPCP") scoped to one org. Custom patterns via repeatable `--pattern <s>`. Implements the canonical detection for the Shai-Hulud / TeamPCP supply-chain framework class — the attacker uses GitHub itself as the exfil channel. Set `GITHUB_TOKEN` for private-repo coverage and rate-limit headroom; public-repo search works without auth.
+GitHub repo-pattern monitoring: `exceptd watch --org-scan --org <login>` probes GitHub Search for repositories matching known threat-actor naming patterns ("A Gift From TeamPCP", "Shai-Hulud", "TeamPCP") scoped to one org. Custom patterns via repeatable `--pattern <s>`. Implements the canonical detection for the Shai-Hulud / TeamPCP supply-chain framework class — the attacker uses GitHub itself as the exfil channel. Set `GITHUB_TOKEN` for private-repo coverage and rate-limit headroom; public-repo search works without auth.
 
 AI-assistant config-file audit: `exceptd doctor --ai-config` walks `~/.claude`, `~/.cursor`, `~/.codeium`, `~/.aider`, and `~/.continue`, flagging sensitive files (`settings.json`, `mcp.json`, `*.mcp_config.json`, `api_key*`, `*.token`, `*.credentials`) not at mode 0600 on POSIX. On Windows the mode bits aren't load-bearing; each finding is surfaced with an info-level "manual ACL review" note. Catches the AI-config-credential-exfil class that the Shai-Hulud framework targets. Opt-in — does not run as part of the default no-flag `doctor` pass.
 
-Evidence-collection layer: `exceptd collect <playbook>` invokes a companion script under `lib/collectors/<playbook>.js` that walks cwd, applies the catalogued regex set, stats permissions, and emits the submission JSON in the same shape `exceptd run --evidence -` accepts. 13 of 23 playbooks have collectors today (`ai-api`, `cicd-pipeline-compromise`, `containers`, `cred-stores`, `crypto`, `crypto-codebase`, `hardening`, `kernel`, `library-author`, `mcp`, `runtime`, `sbom`, `secrets`); the remaining 10 are policy-skipped per AGENTS.md (judgement-shaped incident / governance / pure-analyze playbooks where AI-driven evidence collection is the design). Canonical operator pipe: `exceptd collect <pb> | exceptd run <pb> --evidence -`. `exceptd doctor --collectors` enumerates the layer; `exceptd discover` tags applicable playbooks with `[collector]` when one ships. `cicd-pipeline-compromise` requires `--attest-ownership` on the collect call (the playbook's `operator-owns-ci-fleet` precondition is opt-in to prevent unauthorized CI assessments).
+Evidence-collection layer: `exceptd collect <playbook>` invokes a companion script under `lib/collectors/<playbook>.js` that walks cwd, applies the catalogued regex set, stats permissions, and emits the submission JSON in the same shape `exceptd run --evidence -` accepts. 14 of 24 playbooks have collectors today (`ai-api`, `cicd-pipeline-compromise`, `citation-hygiene`, `containers`, `cred-stores`, `crypto`, `crypto-codebase`, `hardening`, `kernel`, `library-author`, `mcp`, `runtime`, `sbom`, `secrets`); the remaining 10 are policy-skipped per AGENTS.md (judgement-shaped incident / governance / pure-analyze playbooks where AI-driven evidence collection is the design). Canonical operator pipe: `exceptd collect <pb> | exceptd run <pb> --evidence -`. `exceptd doctor --collectors` enumerates the layer; `exceptd discover` tags applicable playbooks with `[collector]` when one ships. `cicd-pipeline-compromise` requires `--attest-ownership` on the collect call (the playbook's `operator-owns-ci-fleet` precondition is opt-in to prevent unauthorized CI assessments).
 
 Daily scheduled threat intake: a `routine: exceptd-threat-intake` (claude.ai remote agent) runs daily at 14:00 UTC. Sequence: `npm install` → `refresh --check-advisories` → `watchlist --alerts` → `refresh --apply` → `refresh --advisory <CVE-ID>` for up to 5 new CVE IDs from the primary-source feeds → re-sign + rebuild-indexes if the catalog mutated → commit on `intake/<YYYY-MM-DD>` branch with the full diff in the report. Closes the cadence gap that previously left fresh disclosures dependent on operator-triggered intake. Operator-managed at <https://claude.ai/code/routines>.
 
@@ -281,7 +281,7 @@ exceptd collect <playbook>            Walk cwd + invoke the companion collector
                                       under lib/collectors/<playbook>.js. Emits
                                       a submission JSON ready to pipe into
                                       `exceptd run <playbook> --evidence -`.
-                                      13/23 playbooks have collectors; the rest
+                                      14/24 playbooks have collectors; the rest
                                       are AI-driven by design (incident /
                                       governance / pure-analyze — see
                                       AGENTS.md).
@@ -330,8 +330,11 @@ exceptd doctor                        One-shot health check.
                                       Opt-in; not part of the default doctor
                                       pass.
 
-exceptd ci                            One-shot CI gate. Exits 2 on detected or
-                                      rwep ≥ rwep_threshold.escalate.
+exceptd ci                            One-shot CI gate. Exit codes: 0 PASS,
+                                      1 framework error, 2 detected/escalate
+                                      (or rwep ≥ rwep_threshold.escalate),
+                                      3 ran-but-no-evidence, 4 blocked
+                                      (ok:false), 5 jurisdiction clock started.
   --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.
@@ -346,6 +349,35 @@ exceptd lint <pb> <evidence>          Pre-flight check submission shape vs
                                       playbook (preconditions / artifacts /
                                       indicators) without executing phases 4-7.
 
+exceptd cve <CVE-ID>                  Resolve one CVE citation → status
+                                      (published / rejected / disputed /
+                                      fabricated / nonexistent / unknown) plus
+                                      cvss / kev / product. Order: curated
+                                      catalog (offline) → resolved cache
+                                      (7-day TTL, warmed by a prior lookup) →
+                                      one NVD lookup, then cached. Lets a
+                                      fan-out of agents share one answer
+                                      instead of each researching the same id.
+  --air-gap | --no-network            Offline-only (also EXCEPTD_AIR_GAP=1).
+                                      Returns unknown + a reason when the id
+                                      isn't in catalog/cache.
+  --json | --pretty                   Machine output.
+                                      Exit 2 when the citation won't stand up
+                                      (rejected / fabricated / nonexistent /
+                                      withdrawn).
+
+exceptd rfc <number>                  Resolve an RFC number → title + status
+                                      from the local index (whole current
+                                      series, fully offline).
+  --check "<title>"                   Report title_match true/false; exit 2 on
+                                      mismatch (e.g. RFC 9404 cited as the
+                                      Sieve spec — it's JMAP Blob Management).
+  --air-gap                           Offline-only. Not-found numbers are
+                                      likely obsoleted/historic or nonexistent;
+                                      with network it disambiguates via the
+                                      datatracker.
+  --json | --pretty                   Machine output.
+
 exceptd refresh                       Refresh upstream catalogs + indexes.
                                       Replaces prefetch + refresh + build-indexes.
   --apply                             Write diffs back + rebuild indexes.
@@ -385,7 +417,7 @@ Packages dataset (`MAL-*` keys). New IDs land as drafts that the catalog
 validator treats as warnings, not errors — editorial review (framework
 gaps, IoCs, ATLAS/ATT&CK refs) is still required.
 
-exceptd watchlist                     Default mode: aggregate every skill's
+exceptd watch                         Default mode: aggregate every skill's
                                       forward_watch entries (upcoming standards,
                                       RFC publications, new TTPs to monitor).
                                       `--by-skill` inverts the grouping.
@@ -536,7 +568,7 @@ If your tool has a conventional auto-load filename not listed here and you'd lik
 - **`theater-fingerprints.json`** — structured records for the 7 compliance theater patterns: claim, audit evidence, reality, fast detection test, controls implicated.
 - **`_meta.json`** — sha256 of every source file. The `validate-indexes` predeploy gate fails if any source changed after the last build; `build-indexes --changed` reads this to know what to rebuild.
 
-Regenerate with `exceptd build-indexes` (full) or `exceptd build-indexes --changed --parallel` (incremental).
+Regenerate with `exceptd refresh --indexes-only`.
 
 ## For skill authors — `agents/`
 
@@ -546,6 +578,8 @@ The `agents/` directory ships markdown role cards documenting authoring conventi
 
 All skills pull from `data/`. Cross-validated against canonical upstream sources via `exceptd refresh` / `exceptd doctor --cves` / `exceptd doctor --rfcs`.
 
+To resolve a single citation rather than refresh the whole catalog, `exceptd cve <CVE-ID>` and `exceptd rfc <number>` return a status verdict for one id (catalog → resolved cache → one NVD / datatracker lookup, offline-capable). The lookup caches, so a fan-out of agents shares the answer instead of each independently re-researching the same citation.
+
 - `cve-catalog.json` — CVE metadata with RWEP scores, CISA KEV status, PoC availability, live-patch info
 - `atlas-ttps.json` — MITRE ATLAS v5.6.0 TTPs with gap flags and exploitation examples. Each TTP now carries a `cve_refs[]` back-edge — operators reading an ATLAS entry see the catalogued CVEs that cite it without grepping `cve-catalog.json`. The same back-edge is populated on `attack-techniques.json`, and each playbook carries a `_meta.fed_by[]` reverse field naming the upstream playbooks that chain into it.
 - `framework-control-gaps.json` — Per-framework, per-control: what it was designed for vs. what it misses

package/bin/exceptd.js

@@ -65,7 +65,17 @@ const PKG_ROOT = path.resolve(__dirname, "..");
 // behavior share the same source of truth.
 const { EXIT_CODES, listExitCodes } = require(path.join(PKG_ROOT, "lib", "exit-codes.js"));
 const { validateIdComponent } = require(path.join(PKG_ROOT, "lib", "id-validation.js"));
-const { suggestFlag, flagsFor } = require(path.join(PKG_ROOT, "lib", "flag-suggest.js"));
+const { suggestFlag, flagsFor, VERB_FLAG_ALLOWLIST } = require(path.join(PKG_ROOT, "lib", "flag-suggest.js"));
+
+// Union of every flag known to ANY verb. A flag that is valid somewhere but
+// not on the active verb (e.g. `--csaf-status` on `brief`) is cross-verb
+// misuse, not a typo — it falls through to the verb handler, which emits a
+// tailored "that flag belongs on a run-class verb" message. Only a flag that
+// is unknown EVERYWHERE is refused outright as a typo/garbage at the
+// dispatcher. Kept module-scope so it is computed once.
+const ALL_KNOWN_FLAGS = new Set(
+  Object.values(VERB_FLAG_ALLOWLIST).flat()
+);
 
 /**
  * Factor the EXPECTED_FINGERPRINT pin check used by
@@ -144,6 +154,10 @@ const COMMANDS = {
   watch:           () => path.join(PKG_ROOT, "orchestrator", "index.js"),
   "framework-gap": () => path.join(PKG_ROOT, "orchestrator", "index.js"),
   "framework-gap-analysis": () => path.join(PKG_ROOT, "orchestrator", "index.js"),
+  // Citation resolvers — answer "is this CVE/RFC citation valid?" offline-first
+  // (catalog/index -> resolved cache -> opt-in single network lookup, cached).
+  cve:             () => path.join(PKG_ROOT, "lib", "cve-cli.js"),
+  rfc:             () => path.join(PKG_ROOT, "lib", "rfc-cli.js"),
   // Seven-phase playbook verbs — handled in-process via lib/playbook-runner.js.
   plan:     null,
   govern:   null,
@@ -384,7 +398,7 @@ Canonical verbs
                              --evidence <file|->    flat or nested submission
                              --evidence-dir <dir>   per-playbook submission files
                              --vex <file>           CycloneDX / OpenVEX filter
-                             --format <fmt> ...     csaf-2.0 | sarif | openvex | markdown | summary
+                             --format <fmt> ...     csaf-2.0 | sarif | openvex | markdown | summary | json
                              --diff-from-latest     drift vs prior attestation
                              --ci                   exit-code gate (use \`exceptd ci\` instead)
                              --operator <name>      bind attestation to identity
@@ -458,8 +472,10 @@ Canonical verbs
                              --prefetch             populate offline cache
                              --from-cache           consume offline cache
                              --indexes-only         rebuild indexes only
-                             Sources: kev|epss|nvd|rfc|pins|ghsa (v0.12.0).
+                             Sources: kev|epss|nvd|rfc|pins|ghsa|osv.
                                                     ghsa drafts pass validator as warnings.
+                             --check-advisories     poll primary-source advisory
+                                                    feeds; report-only diffs[].
 
 Removed verbs (refused — these now error with a pointer to the replacement)
 ───────────────────────────────────────────────────────────────────────────
@@ -476,12 +492,10 @@ here so old scripts know where each moved:
 Deprecated aliases (still work — prefer the canonical verb)
 ───────────────────────────────────────────────────────────
 
-These still run but emit a one-time deprecation banner. The [DEPRECATED]
-prefix keeps them out of the active-verbs list that
-\`exceptd help | grep '^  [a-z]'\` surfaces. Each maps to a canonical verb:
+These still run. The [DEPRECATED] prefix keeps them out of the active-verbs
+list that \`exceptd help | grep '^  [a-z]'\` surfaces. Each maps to a canonical
+verb:
 
-  [DEPRECATED] reattest <sid>    → attest diff <sid>
-  [DEPRECATED] list-attestations → attest list
   [DEPRECATED] scan              → discover --scan-only
   [DEPRECATED] dispatch          → discover
   [DEPRECATED] currency          → doctor --currency
@@ -492,6 +506,11 @@ prefix keeps them out of the active-verbs list that
   [DEPRECATED] prefetch          → refresh --no-network
   [DEPRECATED] build-indexes     → refresh --indexes-only
 
+Accepted short forms (canonical — not deprecated):
+
+  reattest <sid>        short form of \`attest diff <sid>\`
+  list-attestations     short form of \`attest list\`
+
 Output: default human-readable (v0.11.0). --json for machine output.
         --pretty for indented JSON.
 
@@ -711,6 +730,26 @@ function main() {
     return;
   }
 
+  // `skill` and `framework-gap` are spawned subcommands that never reach the
+  // in-process per-verb --help, and (unlike `refresh`/`prefetch`, which print
+  // their own help) the orchestrator forwards `--help` as a positional —
+  // `skill --help` tried to resolve a skill literally named "--help"
+  // ("Skill not found: --help") and `framework-gap --help` errored on missing
+  // args. Intercept --help for just these so they honor it. Scoped to the
+  // verbs that lack their own help handler, so spawns that do (refresh,
+  // prefetch) keep their detailed usage.
+  const SPAWN_HELP_USAGE = {
+    skill: "exceptd skill <name>          Show the full context document for one skill.",
+    "framework-gap": "exceptd framework-gap <framework> <cve-or-scenario>   One-framework gap analysis.",
+    "framework-gap-analysis": "exceptd framework-gap <framework> <cve-or-scenario>   One-framework gap analysis.",
+    cve: "exceptd cve <CVE-ID> [--json] [--air-gap|--no-network]   Resolve a CVE: published/rejected/disputed/fabricated/nonexistent (catalog -> cache -> NVD).",
+    rfc: "exceptd rfc <number> [--check \"<title>\"] [--json] [--air-gap]   Resolve an RFC number -> title + status (local index, offline).",
+  };
+  if ((effectiveRest.includes("--help") || effectiveRest.includes("-h")) && SPAWN_HELP_USAGE[effectiveCmd]) {
+    process.stdout.write(SPAWN_HELP_USAGE[effectiveCmd] + "\n  Full reference: exceptd help\n");
+    return;
+  }
+
   // Orchestrator subcommands need the subcommand name preserved as argv[0]
   // for orchestrator/index.js's switch statement.
   const finalArgs = ORCHESTRATOR_PASSTHROUGH.has(effectiveCmd) ? [script, effectiveCmd, ...effectiveRest] : [script, ...effectiveRest];
@@ -1203,6 +1242,7 @@ function dispatchPlaybook(cmd, argv) {
     "publisher-namespace", "mode", "scope", "playbook", "phase", "tlp",
     "against", "since", "bundle-epoch", "attestation-root", "format",
     "cwd",  // exceptd collect <pb> --cwd <path>
+    "limit",  // exceptd attest list --limit <n>
   ]);
   const verbAllowlist = flagsFor(cmd);
   const allowlistSet = new Set(verbAllowlist);
@@ -1242,21 +1282,29 @@ function dispatchPlaybook(cmd, argv) {
       }
       continue;
     }
-    // Refuse only when a close suggestion exists (likely typo). Unknown
-    // flags with no near-match fall through to verb-level handling so a
-    // future addition doesn't require an allowlist edit in this file
-    // before it can ship. The PASSTHROUGH_FLAGS list above plus the
-    // per-verb allowlist in lib/flag-suggest.js together cover every
-    // shipped flag; anything that misses both AND has a typo suggestion
-    // is the case operators benefit from refusing.
+    // A flag valid on SOME other verb (e.g. `--csaf-status` on `brief`) is
+    // cross-verb misuse — fall through so the verb handler can emit its
+    // tailored "that flag belongs on a run-class verb" guidance rather than
+    // a blanket refusal here.
+    if (ALL_KNOWN_FLAGS.has(key)) continue;
+    // Unknown everywhere — refuse it as a typo / unsupported flag. Silently
+    // ignoring an unrecognized flag let a mistyped cap or output-format flag
+    // look like it applied when it did nothing. Surface a suggestion
+    // when one is close, and always list the accepted flags so the operator
+    // can self-correct. Adding a new flag to a verb means appending it to
+    // that verb's allowlist (or PASSTHROUGH_FLAGS) — the test suite exercises
+    // every shipped flag, so a missing registration fails CI rather than
+    // silently breaking the flag.
     const suggestion = suggestFlag(key, verbAllowlist);
-    if (suggestion) {
-      return emitError(
-        `unknown flag --${key}`,
-        { verb: cmd, suggested: suggestion },
-        pretty
-      );
-    }
+    return emitError(
+      `${cmd}: unknown flag --${key}`,
+      {
+        verb: cmd,
+        unknown_flags: [{ flag: `--${key}`, did_you_mean: suggestion ? [`--${suggestion}`] : [] }],
+        known_flags: verbAllowlist.filter((f) => typeof f === "string").sort().map((f) => `--${f}`),
+      },
+      pretty
+    );
   }
   const runOpts = {
     // Air-gap can be requested via the explicit flag OR the
@@ -1798,10 +1846,14 @@ Flags:
                           or not_affected | fixed (OpenVEX) drop out of
                           analyze.matched_cves. The disposition is preserved
                           under analyze.vex.dropped_cves.
-  --format <fmt> ...      Emit the close.evidence_package bundle in additional
-                          formats. Repeatable. Supported: csaf-2.0 | sarif |
-                          openvex | markdown. CSAF is always primary; extras
-                          populate close.evidence_package.bundles_by_format.
+  --format <fmt> ...      Transform stdout. Supported: summary | markdown |
+                          csaf-2.0 | csaf | sarif | openvex | json (json = the
+                          full run result). Standardized bundles (csaf/sarif/
+                          openvex) are emitted as spec-conformant documents.
+                          Repeatable, but only ONE document goes to stdout — the
+                          first; every requested bundle is embedded under
+                          close.evidence_package.bundles_by_format (see via
+                          --json). Passing several prints a note to stderr.
   --explain               Dry-run: emit preconditions, required artifacts,
                           recognized signal keys, and a submission skeleton.
                           Does not run detect/analyze/validate/close.
@@ -2390,7 +2442,14 @@ function cmdCollect(runner, args, runOpts, pretty) {
   // Spread `submission` first, then explicit fields, so a submission key
   // named `air_gap_mode` (currently always undefined but defensive against
   // future collector contracts) can't clobber the envelope marker.
-  emit({ verb: "collect", playbook_id: playbookId, ...submission, air_gap_mode: collectAirGap }, pretty, (obj) => {
+  const collectBody = { verb: "collect", playbook_id: playbookId, ...submission, air_gap_mode: collectAirGap };
+  // collect's primary purpose is the pipe `exceptd collect <pb> | exceptd run
+  // <pb> --evidence -`. When stdout is NOT a TTY (a pipe / redirect), emit JSON
+  // so that one-liner just works; the human summary is only for an interactive
+  // operator at a terminal. Explicit --json / --pretty force JSON regardless.
+  // Without this gate, emit()'s default-human behavior printed a prose summary
+  // into the pipe and the downstream `run --evidence -` failed to parse it.
+  const collectHuman = process.stdout.isTTY ? (obj) => {
     const lines = [];
     const meta = obj.collector_meta || {};
     lines.push(`collect: ${obj.playbook_id}  (${meta.collector_version || "?"} on ${meta.platform || "?"})`);
@@ -2427,10 +2486,11 @@ function cmdCollect(runner, args, runOpts, pretty) {
       }
       if (errs.length > 5) lines.push(`  … ${errs.length - 5} more`);
     }
-    lines.push(`\n→ next: exceptd collect ${obj.playbook_id} --json | exceptd run ${obj.playbook_id} --evidence -`);
+    lines.push(`\n→ next: exceptd collect ${obj.playbook_id} | exceptd run ${obj.playbook_id} --evidence -`);
     lines.push(`Full structured result: --json (or --pretty for indented JSON).`);
     return lines.join("\n");
-  });
+  } : undefined;
+  emit(collectBody, pretty, collectHuman);
 }
 
 function cmdLint(runner, args, runOpts, pretty) {
@@ -3480,7 +3540,8 @@ function cmdRun(runner, args, runOpts, pretty) {
   //   --format csaf-2.0/sarif/openvex → the corresponding bundle from close
   //   (default — no --format) → full JSON result as before
   if (args.format) {
-    const requested = Array.isArray(args.format) ? args.format[0] : args.format;
+    const requestedAll = Array.isArray(args.format) ? args.format : [args.format];
+    const requested = requestedAll[0];
     const VALID = ["summary", "markdown", "csaf-2.0", "csaf", "sarif", "openvex", "json"];
     if (!VALID.includes(requested)) {
       const dym = suggestFlag(String(requested), VALID);
@@ -3491,6 +3552,25 @@ function cmdRun(runner, args, runOpts, pretty) {
         pretty,
       );
     }
+    // Only one document can be written to stdout. When several --format values
+    // are given, emit the first and tell the operator where the rest live so
+    // the extras aren't silently dropped.
+    if (requestedAll.length > 1) {
+      process.stderr.write(
+        `[exceptd] note: ${requestedAll.length} --format values given; emitting "${requested}" to stdout. ` +
+        `All requested bundles are embedded under phases.close.evidence_package.bundles_by_format — ` +
+        `re-run with --json to see them.\n`
+      );
+    }
+    // `json` means "the full run result as JSON" — the same body the default
+    // (no --format) path emits. Without this it fell through to the bundle
+    // lookup, found the runner's "unknown format" stub under
+    // bundles_by_format.json, and emitted that 150-byte stub instead of the
+    // scan — silently discarding the result with a success exit code.
+    if (requested === "json") {
+      emit(result, pretty);
+      return;
+    }
     if (requested === "summary") {
       const cls = result.phases?.detect?.classification;
       const rwep = result.phases?.analyze?.rwep?.adjusted ?? 0;
@@ -3546,7 +3626,15 @@ function cmdRun(runner, args, runOpts, pretty) {
     const bbf = result.phases?.close?.evidence_package?.bundles_by_format || {};
     const body = bbf[formatNorm] || result.phases?.close?.evidence_package?.bundle_body;
     if (body) {
-      emit(body, pretty);
+      // SARIF / CSAF / OpenVEX are self-describing standard documents. Write
+      // them verbatim rather than through emit(), which prepends the tool's
+      // own `ok` envelope key — `ok` is not a permitted top-level property in
+      // any of these schemas and makes strict validators (GitHub code-scanning
+      // SARIF upload, a CSAF trusted-provider check) reject the output. The
+      // namespaced `exceptd_extension` block (CSAF vendor extension carrying
+      // publisher-namespace provenance) is preserved intentionally.
+      const { ok: _ok, ...spec } = body;
+      process.stdout.write(JSON.stringify(spec, null, pretty ? 2 : 0) + "\n");
       return;
     }
     // Fallback: full result
@@ -7040,10 +7128,28 @@ function cmdListAttestations(runner, args, runOpts, pretty) {
     }
   }
   entries.sort((a, b) => (b.captured_at || "").localeCompare(a.captured_at || ""));
+  const total = entries.length;
+  // --limit caps the inventory (newest first). Without it, JSON returns every
+  // session and the human table shows the first 50 with an "… and N more"
+  // footer. With it, both surfaces honor the cap and report `total`.
+  let limitN = null;
+  if (args.limit != null) {
+    limitN = Number(args.limit);
+    if (!Number.isInteger(limitN) || limitN < 0) {
+      return emitError(
+        `attest list: --limit must be a non-negative integer; got ${JSON.stringify(String(args.limit))}.`,
+        { verb: "attest list", provided: args.limit },
+        pretty,
+      );
+    }
+  }
+  const shown = limitN != null ? entries.slice(0, limitN) : entries;
   emit({
     ok: true,
-    attestations: entries,
-    count: entries.length,
+    attestations: shown,
+    count: total,
+    shown: shown.length,
+    limit: limitN,
     filter: { playbook: playbookFilter ? [...playbookFilter] : null, since: args.since || null },
     roots_searched: [...seenRoots],
     // Cycle 11 F5 (v0.12.32): every candidate root + whether it existed,
@@ -7068,10 +7174,17 @@ function cmdListAttestations(runner, args, runOpts, pretty) {
     }
     lines.push(`  ${"session-id".padEnd(20)}  ${"playbook".padEnd(16)}  ${"captured-at".padEnd(20)}  evidence-hash`);
     lines.push(`  ${"-".repeat(20)}  ${"-".repeat(16)}  ${"-".repeat(20)}  ${"-".repeat(20)}`);
-    for (const e of obj.attestations.slice(0, 50)) {
+    // When --limit was given, obj.attestations is already capped; show all of
+    // it. Otherwise show the first 50 and footer the remainder.
+    const rows = obj.limit != null ? obj.attestations : obj.attestations.slice(0, 50);
+    for (const e of rows) {
       lines.push(`  ${(e.session_id || "?").padEnd(20)}  ${(e.playbook_id || "?").padEnd(16)}  ${(e.captured_at || "").slice(0, 19).padEnd(20)}  ${e.evidence_hash || ""}`);
     }
-    if (obj.count > 50) lines.push(`  … and ${obj.count - 50} more (use --json for full list)`);
+    if (obj.limit != null) {
+      if (obj.count > rows.length) lines.push(`  showing ${rows.length} of ${obj.count} (raise --limit or use --json for the full list)`);
+    } else if (obj.count > 50) {
+      lines.push(`  … and ${obj.count - 50} more (use --limit <n> or --json for the full list)`);
+    }
     return lines.join("\n");
   });
 }

package/data/_indexes/_meta.json

@@ -1,10 +1,10 @@
 {
   "schema_version": "1.1.0",
-  "generated_at": "2026-05-27T04:33:05.318Z",
+  "generated_at": "2026-05-27T12:31:54.921Z",
   "generator": "scripts/build-indexes.js",
   "source_count": 54,
   "source_hashes": {
-    "manifest.json": "13900334f14a87189b4cda1d1357f2efc6075283f24eb1c149ec4309db01a400",
+    "manifest.json": "cc72d668222e9cd18eaef7928e173ad17434ff4b411235bbba2b13fca722db9e",
     "data/atlas-ttps.json": "d24bc02859d40ccf1615db75cca68c077585904e41e0d8f6de448121e9b1abb0",
     "data/attack-techniques.json": "fa193f0d2d248176a8beddb641e9fe56ba4faa9e15dc253ff876dbf0c5d58a77",
     "data/cve-catalog.json": "3d451dda7ac0c7d57a4075ae4bafd3148c6184b35dc1bc59d8b81d1f2641e430",