@blamejs/exceptd-skills 0.15.45 → 0.15.47

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.15.47 — 2026-05-30
+
+A consistency pass on error envelopes and flag handling.
+
+An invalid `--session-id`, `--attestation-root`, `--session-key`, `--mode`, or `--operator` passed to `ci`, `run-all`, or `ai-run` now reports the verb you actually ran instead of always saying "run:", and the error envelope carries the matching `verb` field. `brief --ack` — and every "irrelevant flag" refusal — now carries `flag` and `error_class` consistently for machine consumers.
+
+`run --format` with no value now refuses instead of silently proceeding, and `--format` / `--air-gap` typos are suggested on `run` / `collect`. `discover --help` documents `--cwd`. The `framework-gap` unknown-framework error carries `verb`. `validate-cves --offline` exits through the flush-safe path so its final summary line is never truncated when piped.
+
+## 0.15.46 — 2026-05-30
+
+A correctness and help-accuracy pass.
+
+`exceptd help <verb>` for a verb removed in v0.13.0 — `plan`, `govern`, `direct`, `look`, `ingest` — now refuses with the replacement command and a non-zero exit, matching what the bare verb already did, instead of printing stale help for a command that no longer runs.
+
+Help text now matches behavior: `brief --help` documents `--flat`, `attest --help` lists the `prune` subverb, and `ai-run --help` shows the correct exit code for a session-id collision. `doctor` accepts `--air-gap` consistently across its flag-validation paths. Error messages and accepted-verb lists no longer recommend removed verbs.
+
+A failure opening the `watch --log-file` target now exits with the generic-failure code instead of the detected-escalation code, so a filesystem error no longer trips a CI gate keyed on escalation. The worst-of active-exploitation reduction used in finding drafts now ranks a "theoretical" CVE correctly instead of dropping it or overstating an empty set as "unknown".
+
+Validator warnings describe their `--strict` / predeploy enforcement rather than promising an already-shipped version.
+
 ## 0.15.45 — 2026-05-30
 
 An operator-experience pass.

package/CONTEXT.md

@@ -228,7 +228,7 @@ The `researcher` **skill** (front-door dispatcher) and `threat-researcher` **age
 - `data/global-frameworks.json` — load for multi-jurisdiction questions
 - `data/atlas-ttps.json`, `data/attack-techniques.json` — load for TTP-driven work
 - Individual skill files — 15–40 KB each; load on match, not preemptively
-- Playbook JSON — load on demand via `exceptd direct/look`; the engine handles phase orchestration
+- Playbook JSON — load on demand via `exceptd brief <playbook>` (or `--phase look` for just the artifact spec); the engine handles phase orchestration
 
 ### What This Repo Does Not Contain
 

package/bin/exceptd.js

@@ -28,13 +28,10 @@
  * Seven-phase playbook contract (govern → direct → look → detect →
  * analyze → validate → close):
  *
- *   plan                  List playbooks + directives for session planning.
- *   govern <playbook>     Phase 1: load GRC context.
- *   direct <playbook>     Phase 2: scope the investigation.
- *   look <playbook>       Phase 3: emit artifact-collection spec for agent.
+ *   brief [--all]         Phases 1-3 (govern/direct/look) in one info doc.
+ *     <playbook>          Add --phase govern|direct|look for a single phase.
  *   run <playbook>        Phases 4-7 (detect/analyze/validate/close) from
  *                         agent submission JSON.
- *   ingest                Alias for `run` matching AGENTS.md terminology.
  *   reattest <session>    Re-run a prior session and diff evidence_hash.
  *
  *   help, --help, -h      This help.
@@ -169,7 +166,7 @@ const ORCHESTRATOR_PASSTHROUGH = new Set([
   "framework-gap", "framework-gap-analysis",
 ]);
 
-// Cycle 17 P2 S13 (v0.12.37): Levenshtein-1 did-you-mean for unknown verbs.
+// Levenshtein-1 did-you-mean for unknown verbs.
 // Catches common single-char / transposition typos against the COMMANDS
 // table without false-positive flood: only suggests verbs within distance
 // 1 (one insert / delete / substitute / transpose). For typed-distance 2+
@@ -385,6 +382,7 @@ Canonical verbs
                              --all                  every playbook
                              --scope <type>         system | code | service | cross-cutting
                              --directives           expand directive metadata
+                             --flat                 ungrouped list (omit scope grouping)
                              --phase <name>         emit only one phase (legacy compat)
 
   run [playbook]             Phases 4-7. Auto-detects cwd context when no
@@ -433,7 +431,7 @@ Canonical verbs
                              2 detected/escalate, 3 ran-but-no-evidence,
                              4 blocked (ok:false), 5 jurisdiction clock started.
                              (Codes 6/7/8/9 surface on attest verify / run /
-                             ai-run / ingest, not ci.)
+                             ai-run, not ci.)
                              --all | --scope <type> | (auto-detect)
                              --max-rwep <n>         cap below playbook default
                              --block-on-jurisdiction-clock
@@ -597,13 +595,25 @@ function main() {
   const rest = argv.slice(1);
 
   if (cmd === "help" || cmd === "--help" || cmd === "-h") {
-    // Cycle 11 F4 (v0.12.32): `exceptd help <verb>` previously dropped the
+    // `exceptd help <verb>` previously dropped the
     // verb argument and printed the top-level help. Route through the same
     // printPlaybookVerbHelp() that `exceptd <verb> --help` already uses so
     // operators get a consistent verb-specific help surface regardless of
     // which way they reached it.
     if (rest.length > 0 && typeof rest[0] === 'string' && rest[0].length > 0) {
       const verb = rest[0];
+      // A removed verb has no live help. Refuse with the same structured
+      // removal error the bare verb emits, so `help <removed>` and
+      // `<removed> --help` agree (both exit non-zero, both name the
+      // replacement) instead of printing stale help for a verb that no
+      // longer dispatches.
+      if (REMOVED_VERBS[verb]) {
+        emitError(
+          `'${verb}' was removed in v0.13.0. Use \`exceptd ${REMOVED_VERBS[verb]}\` instead.`,
+          { verb, removed_in: "0.13.0", replacement: REMOVED_VERBS[verb] }
+        );
+        return;
+      }
       if (printPlaybookVerbHelp(verb)) {
         process.exit(0);
       }
@@ -730,7 +740,7 @@ function main() {
     // UNKNOWN_COMMAND (10) afterwards. Cycle 9 split this away from
     // DETECTED_ESCALATE (2) — the two semantics had collided since v0.12.24.
     //
-    // Cycle 17 P2 S13 (v0.12.37): add a did-you-mean suggestion when the
+    // add a did-you-mean suggestion when the
     // unknown verb is within Levenshtein-1 of a real verb (catches the
     // common single-char typos: `discoer` → `discover`, `attst` → `attest`,
     // `valdiate-cves` → `validate-cves`).
@@ -1034,7 +1044,7 @@ function readEvidence(evidenceFlag, opts = {}) {
     }
     const text = Buffer.concat(chunks).toString("utf8");
     if (!text.trim()) {
-      // Cycle 17 P1 S4 (v0.12.37): pre-fix empty stdin silently became {}
+      // pre-fix empty stdin silently became {}
       // — operator got a "successful" run on no evidence with no warning,
       // and the evidence_hash for `{}` is deterministic so subsequent
       // runs didn't even reveal the mistake. Emit a stderr nudge so the
@@ -1138,7 +1148,7 @@ function hasReadableStdin() {
   // PowerShell / MSYS pipes working (isTTY === false when piped). Do NOT
   // gate on size > 0 here: a Windows pipe with bytes queued reports as
   // a regular file with size 0, and gating would silently skip every
-  // `echo {...} | exceptd run|ingest|ai-run` invocation.
+  // `echo {...} | exceptd run|ai-run` invocation.
   if (process.platform === "win32" && process.stdin.isTTY === false) return true;
   return false;
 }
@@ -1406,8 +1416,8 @@ function dispatchPlaybook(cmd, argv) {
     const r = validateIdComponent(sid, "session");
     if (!r.ok) {
       return emitError(
-        `run: --session-id ${r.reason}. Path separators and '..' are rejected.`,
-        { provided: typeof sid === "string" ? sid.slice(0, 80) : typeof sid },
+        `${cmd}: --session-id ${r.reason}. Path separators and '..' are rejected.`,
+        { verb: cmd, provided: typeof sid === "string" ? sid.slice(0, 80) : typeof sid },
         pretty
       );
     }
@@ -1420,13 +1430,13 @@ function dispatchPlaybook(cmd, argv) {
     // happens in resolveAttestationRoot — this is the input-validation layer.
     const ar = args["attestation-root"];
     if (typeof ar !== "string" || ar.length === 0) {
-      return emitError("run: --attestation-root must be a non-empty string.", { provided: typeof ar }, pretty);
+      return emitError(`${cmd}: --attestation-root must be a non-empty string.`, { verb: cmd, provided: typeof ar }, pretty);
     }
     const arSegments = ar.split(/[\\/]/);
     if (arSegments.some(seg => seg === "..")) {
       return emitError(
-        "run: --attestation-root must not contain '..' path segments. Pass an absolute path under your home directory or an explicit project-relative path without traversal.",
-        { provided: ar.slice(0, 200) },
+        `${cmd}: --attestation-root must not contain '..' path segments. Pass an absolute path under your home directory or an explicit project-relative path without traversal.`,
+        { verb: cmd, provided: ar.slice(0, 200) },
         pretty
       );
     }
@@ -1439,8 +1449,8 @@ function dispatchPlaybook(cmd, argv) {
     // every collapsed-equivalent shape.
     if (arSegments.some(seg => seg.length > 0 && /^\.+$/.test(seg))) {
       return emitError(
-        "run: --attestation-root path segment cannot consist entirely of dots (rejected: '.', '..', '...', etc.). Pass an absolute path or a project-relative path without traversal.",
-        { provided: ar.slice(0, 200) },
+        `${cmd}: --attestation-root path segment cannot consist entirely of dots (rejected: '.', '..', '...', etc.). Pass an absolute path or a project-relative path without traversal.`,
+        { verb: cmd, provided: ar.slice(0, 200) },
         pretty
       );
     }
@@ -1451,10 +1461,10 @@ function dispatchPlaybook(cmd, argv) {
     // silently accepted; HMAC signing then either failed silently or produced
     // an unverifiable signature.
     if (!/^[0-9a-fA-F]+$/.test(args["session-key"])) {
-      return emitError("run: --session-key must be hex characters only (0-9, a-f). Generate with: node -e \"console.log(require('crypto').randomBytes(32).toString('hex'))\"", { provided_length: args["session-key"].length }, pretty);
+      return emitError(`${cmd}: --session-key must be hex characters only (0-9, a-f). Generate with: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`, { verb: cmd, provided_length: args["session-key"].length }, pretty);
     }
     if (args["session-key"].length < 16) {
-      return emitError("run: --session-key is too short (need at least 16 hex chars / 64 bits of entropy).", { provided_length: args["session-key"].length }, pretty);
+      return emitError(`${cmd}: --session-key is too short (need at least 16 hex chars / 64 bits of entropy).`, { verb: cmd, provided_length: args["session-key"].length }, pretty);
     }
     runOpts.session_key = args["session-key"];
   }
@@ -1467,8 +1477,8 @@ function dispatchPlaybook(cmd, argv) {
       const dym = suggestFlag(String(args.mode), VALID_MODES);
       const hint = dym ? ` Did you mean "${dym}"?` : '';
       return emitError(
-        `run: --mode "${args.mode}" not in accepted set ${JSON.stringify(VALID_MODES)}.${hint}`,
-        { provided: args.mode, accepted: VALID_MODES, did_you_mean: dym ? [dym] : [] },
+        `${cmd}: --mode "${args.mode}" not in accepted set ${JSON.stringify(VALID_MODES)}.${hint}`,
+        { verb: cmd, provided: args.mode, accepted: VALID_MODES, did_you_mean: dym ? [dym] : [] },
         pretty,
       );
     }
@@ -1486,27 +1496,27 @@ function dispatchPlaybook(cmd, argv) {
   // chars (\x00-\x1F + \x7F), cap length at 256, reject if all-whitespace.
   if (args.operator !== undefined) {
     if (typeof args.operator !== "string") {
-      return emitError("run: --operator must be a string.", { provided: typeof args.operator }, pretty);
+      return emitError(`${cmd}: --operator must be a string.`, { verb: cmd, provided: typeof args.operator }, pretty);
     }
     // eslint-disable-next-line no-control-regex
     if (/[\x00-\x1F\x7F]/.test(args.operator)) {
       return emitError(
-        "run: --operator contains ASCII control characters (newline, tab, NUL, etc.). Refusing — these would corrupt attestation export shape and enable forgery via multi-line injection.",
-        { provided_length: args.operator.length },
+        `${cmd}: --operator contains ASCII control characters (newline, tab, NUL, etc.). Refusing — these would corrupt attestation export shape and enable forgery via multi-line injection.`,
+        { verb: cmd, provided_length: args.operator.length },
         pretty
       );
     }
     if (args.operator.length > 256) {
       return emitError(
-        `run: --operator too long: ${args.operator.length} chars (limit 256). Use a stable identifier (email, service-account name) — not a free-form description.`,
-        { provided_length: args.operator.length },
+        `${cmd}: --operator too long: ${args.operator.length} chars (limit 256). Use a stable identifier (email, service-account name) — not a free-form description.`,
+        { verb: cmd, provided_length: args.operator.length },
         pretty
       );
     }
     if (args.operator.trim().length === 0) {
       return emitError(
-        "run: --operator is empty or whitespace-only. Pass a meaningful identifier or omit the flag.",
-        null,
+        `${cmd}: --operator is empty or whitespace-only. Pass a meaningful identifier or omit the flag.`,
+        { verb: cmd },
         pretty
       );
     }
@@ -1529,15 +1539,15 @@ function dispatchPlaybook(cmd, argv) {
     try { normalized = args.operator.normalize("NFC"); }
     catch (e) {
       return emitError(
-        `run: --operator failed Unicode NFC normalisation: ${e.message}`,
-        { provided_length: args.operator.length },
+        `${cmd}: --operator failed Unicode NFC normalisation: ${e.message}`,
+        { verb: cmd, provided_length: args.operator.length },
         pretty
       );
     }
     if (normalized.length === 0) {
       return emitError(
-        "run: --operator is empty after Unicode NFC normalisation. Pass a meaningful identifier or omit the flag.",
-        null,
+        `${cmd}: --operator is empty after Unicode NFC normalisation. Pass a meaningful identifier or omit the flag.`,
+        { verb: cmd },
         pretty
       );
     }
@@ -1552,8 +1562,8 @@ function dispatchPlaybook(cmd, argv) {
         }
       }
       return emitError(
-        `run: --operator contains a Unicode control / format / private-use / unassigned codepoint (${offending}). Bidi overrides (U+202E), zero-width joiners (U+200B–D), and format marks corrupt attestation rendering and enable name-forgery. Use printable identifiers only.`,
-        { provided_length: args.operator.length, offending_codepoint: offending },
+        `${cmd}: --operator contains a Unicode control / format / private-use / unassigned codepoint (${offending}). Bidi overrides (U+202E), zero-width joiners (U+200B–D), and format marks corrupt attestation rendering and enable name-forgery. Use printable identifiers only.`,
+        { verb: cmd, provided_length: args.operator.length, offending_codepoint: offending },
         pretty
       );
     }
@@ -1561,16 +1571,15 @@ function dispatchPlaybook(cmd, argv) {
   }
 
   // --csaf-status and --publisher-namespace shape the CSAF bundle emitted by
-  // phases 5-7. Verbs that don't drive those phases (brief, plan, govern,
-  // direct, look, attest, list-attestations, discover, doctor, lint, ask,
-  // verify-attestation, reattest) never assemble a bundle, so silently
-  // consuming these flags is a UX trap. Refuse on those verbs so the
-  // operator knows the flag was discarded — same pattern as --ack. Error
-  // message templates and emitError prefixes use the in-scope `cmd` verb so
-  // a brief invocation says "brief:" rather than misattributing the flag
-  // to run.
+  // phases 5-7. Verbs that don't drive those phases (brief, attest,
+  // list-attestations, discover, doctor, lint, ask, verify-attestation,
+  // reattest) never assemble a bundle, so silently consuming these flags is
+  // a UX trap. Refuse on those verbs so the operator knows the flag was
+  // discarded — same pattern as --ack. Error message templates and emitError
+  // prefixes use the in-scope `cmd` verb so a brief invocation says "brief:"
+  // rather than misattributing the flag to run.
   const BUNDLE_FLAG_RELEVANT_VERBS = new Set([
-    "run", "ci", "run-all", "ai-run", "ingest",
+    "run", "ci", "run-all", "ai-run",
   ]);
 
   // --publisher-namespace <url> threads into the CSAF
@@ -1722,21 +1731,20 @@ function dispatchPlaybook(cmd, argv) {
   // consent was explicit vs. implicit. AGENTS.md says the AI should surface
   // and wait for ack — this is how the ack gets recorded.
   //
-  // --ack only makes sense on verbs that drive phases 5-7 (run / ingest /
-  // ai-run / ci / run-all / reattest). Info-only verbs (brief, plan,
-  // govern, direct, look, attest, list-attestations, discover, doctor,
-  // lint, ask, verify-attestation) never consume an attestation clock —
-  // accepting --ack silently is a UX trap where operators believe they have
-  // recorded consent. Refuse on those verbs so the operator knows the flag
-  // is irrelevant.
+  // --ack only makes sense on verbs that drive phases 5-7 (run / ai-run /
+  // ci / run-all / reattest). Info-only verbs (brief, attest,
+  // list-attestations, discover, doctor, lint, ask, verify-attestation)
+  // never consume an attestation clock — accepting --ack silently is a UX
+  // trap where operators believe they have recorded consent. Refuse on those
+  // verbs so the operator knows the flag is irrelevant.
   const ACK_RELEVANT_VERBS = new Set([
-    "run", "ingest", "ai-run", "ci", "run-all", "reattest",
+    "run", "ai-run", "ci", "run-all", "reattest",
   ]);
   if (args.ack) {
     if (!ACK_RELEVANT_VERBS.has(cmd)) {
       return emitError(
         `${cmd}: --ack is irrelevant on this verb (no jurisdiction clock at stake). --ack only applies to verbs that drive phases 5-7: ${[...ACK_RELEVANT_VERBS].sort().join(", ")}. Re-invoke without --ack, or use \`exceptd run ${cmd === "brief" ? args._[0] || "<playbook>" : "<playbook>"} --ack\` once you're past the briefing step.`,
-        { verb: cmd, accepted_verbs: [...ACK_RELEVANT_VERBS].sort() },
+        { verb: cmd, flag: "ack", error_class: "irrelevant-flag", accepted_verbs: [...ACK_RELEVANT_VERBS].sort() },
         pretty
       );
     }
@@ -1894,44 +1902,6 @@ With <id>:  expands that recipe's ordered skill_chain and notes.
 
 Flags:
   --json   Machine-readable output.`,
-    plan: `plan — list playbooks + directives, grouped by scope.
-
-Flags:
-  --playbook <id> ...     Filter to one or more playbook IDs.
-  --scope <type>          Filter by scope: system | code | service | cross-cutting | all
-  --flat                  Disable grouped-by-scope output; emit flat list.
-  --directives            Include directive id + title + applies_to per playbook.
-  --session-id <id>       Reuse a specific session ID for the planning output.
-  --mode <m>              Investigation mode forwarded into govern.
-  --pretty                Indented JSON output.`,
-    govern: `govern <playbook> — phase 1, load GRC context for a playbook.
-
-Args / flags:
-  <playbook>              Playbook ID. Required positional.
-  --directive <id>        Specific directive (default: first one).
-  --mode <m>              Investigation mode forwarded into govern policy.
-  --air-gap               Honor _meta.air_gap_mode + air_gap_alternative paths.
-  --pretty                Indented JSON output.
-
-Output: jurisdiction_obligations, theater_fingerprints, framework_context, skill_preload.`,
-    direct: `direct <playbook> — phase 2, threat context + skill chain + token budget.
-
-Args / flags:
-  <playbook>              Required positional.
-  --directive <id>        Specific directive (default: first one).
-  --pretty                Indented JSON output.`,
-    look: `look <playbook> — phase 3, artifact-collection spec the host AI executes.
-
-Args / flags:
-  <playbook>              Required positional.
-  --directive <id>        Specific directive (default: first one).
-  --air-gap               Honor air_gap_alternative paths.
-  --pretty                Indented JSON output.
-
-Output includes a 'preconditions' array — the host AI MUST verify each
-precondition with its own probes and declare results back in the submission as:
-  { "precondition_checks": { "<id>": true | false } }
-The runner refuses the run if a precondition with on_fail=halt is unverified.`,
     run: `run [playbook] — phases 4-7 (detect → analyze → validate → close).
 
 Invocation modes:
@@ -2047,36 +2017,6 @@ Other operator-facing flags (full list in source; surfaced here for grep):
   --attestation-root <p>  Override .exceptd/ root for this run.
   --mode <m>              Investigation mode (self_service | authorized_pentest
                           | ir_response | ctf | research | compliance_audit).`,
-    ingest: `ingest — alias for 'run' matching AGENTS.md terminology.
-
-Flags:
-  --domain <id>           Playbook ID (overrides submission.playbook_id).
-  --directive <id>        Directive ID (overrides submission.directive_id).
-  --evidence <file|->     Submission JSON. May include playbook_id/directive_id.
-  --session-id <id>       Reuse a specific session id (must satisfy
-                          /^[A-Za-z0-9._-]{1,64}$/).
-  --force-overwrite       Override session-id collision refusal.
-  --operator <name>       Bind attestation to a specific identity.
-  --ack                   Explicit operator consent for jurisdiction clock.
-  --attestation-root <p>  Override .exceptd/ root for this ingest.
-  --mode <m>              Investigation mode (self_service | authorized_pentest
-                          | ir_response | ctf | research | compliance_audit).
-  --air-gap               Honor air_gap_alternative paths.
-  --force-stale           Override threat_currency_score<50 gate.
-  --csaf-status <s>       CSAF tracking.status for the close.evidence_package
-                          bundle. One of: draft | interim (default) | final.
-                          'final' commits to CSAF §3.1.11.3.5.1 immutability —
-                          set this only after operator review of the advisory.
-  --publisher-namespace <url>
-                          CSAF document.publisher.namespace (§3.1.7.4). The
-                          operator's organisation URL, NOT the tooling vendor.
-                          Must be an http://… or https://… URL, ≤256 chars.
-  --bundle-deterministic  Emit byte-stable bundles (frozen timestamps).
-  --bundle-epoch <ISO>    Frozen epoch for --bundle-deterministic.
-  --pretty                Indented JSON output.
-
-Exit codes: 0 PASS, 1 framework, 4 blocked, 7 SESSION_ID_COLLISION,
-8 LOCK_CONTENTION, 9 STORAGE_EXHAUSTED.`,
     reattest: `reattest [<session-id> | --latest] — replay a prior session and diff the evidence_hash.
 
 Args / flags:
@@ -2102,7 +2042,7 @@ Lists every attestation under .exceptd/attestations/<session_id>/, sorted
 newest-first, with truncated evidence_hash + capture timestamp + file path.`,
     attest: `attest <subverb> <session-id> — auditor-facing attestation operations.
 
-Subverbs (list | show | export | verify | diff):
+Subverbs (list | show | export | verify | diff | prune):
   attest show <sid>       Emit the full (unredacted) attestation.
   attest list             Inventory every prior attestation under
                           ~/.exceptd/attestations/ (or EXCEPTD_HOME when set).
@@ -2126,6 +2066,9 @@ Subverbs (list | show | export | verify | diff):
                           for the same playbook, or against --against <other-sid>
                           for an explicit pair. Reports unchanged | drifted |
                           resolved per evidence_hash + classification deltas.
+  attest prune            GC stale sessions: delete attestations older than
+                          --all-older-than <ISO>. --dry-run previews the set
+                          without deleting.
 
 All subverbs honor --pretty for indented JSON output.
 
@@ -2144,6 +2087,7 @@ on Linux reads /etc/os-release to detect host distro. Emits a list of
 recommended exceptd playbooks tailored to what was found.
 
 Flags:
+  --cwd <dir>             Scan <dir> instead of the current directory.
   --scan-only             Also include legacy \`scan\` output under legacy_scan.
   --json                  Emit JSON (default is human-readable text).
   --pretty                Indented JSON output (implies --json).
@@ -2241,7 +2185,7 @@ Flags:
 Exit codes:
   0  done                  Run completed; emitted {"event":"done","ok":true}.
   1  framework error       Engine threw or stdin parse failure.
-  3  SESSION_ID_COLLISION  --session-id duplicate; pass --force-overwrite or fresh id.
+  7  SESSION_ID_COLLISION  --session-id duplicate; pass --force-overwrite or fresh id.
   8  LOCK_CONTENTION       Concurrent persistAttestation lock held.
   9  STORAGE_EXHAUSTED     Disk/quota/RO filesystem on attestation write.
 
@@ -2352,7 +2296,7 @@ Exit codes:
                            etc.) and the operator has not acked.
 
 (ci does not persist attestations per-run; exit codes 6/7/8/9 surface on
-\`attest verify\` and on \`run\` / \`ai-run\` / \`ingest\`, not on \`ci\`.)
+\`attest verify\` and on \`run\` / \`ai-run\`, not on \`ci\`.)
 
 Output: verb, session_id, playbooks_run, summary{total, detected,
 max_rwep_observed, jurisdiction_clocks_started, verdict, fail_reasons[]},
@@ -2373,9 +2317,10 @@ Flags:
                           submission, not a human digest).`,
     brief: `brief [playbook] — unified info doc (v0.11.0).
 
-Collapses the three info-only phases plan + govern + direct + look into a
-single document. Phases 1-3 of the seven-phase contract are entirely
-informational; brief reads them in one CLI invocation instead of three.
+Collapses the info-only phases govern + direct + look into a single document,
+and replaces the removed plan / govern / direct / look verbs. Phases 1-3 of
+the seven-phase contract are entirely informational; brief reads them in one
+CLI invocation instead of three.
 
 Modes:
   brief                   Auto-detect playbooks for the cwd. Returns a list.
@@ -2389,6 +2334,8 @@ Modes:
 
 Flags:
   --directives            Expand directive metadata per playbook.
+  --flat                  Ungrouped playbook list (omit grouped_by_scope +
+                          scope_summary). Use with --all / --scope.
   --pretty                Indented JSON output.
   --json                  Force single-line JSON.
 
@@ -2431,7 +2378,7 @@ Flags (selected — see \`exceptd run --help\` for the full list):
   --bundle-deterministic  Emit byte-stable bundles across the multi-run set.
   --bundle-epoch <ISO>    Frozen epoch for --bundle-deterministic.`,
   };
-  // Cycle 11 F4 (v0.12.32): return whether a verb-specific help block was
+  // return whether a verb-specific help block was
   // found so the `exceptd help <verb>` caller can decide whether to fall
   // through to the top-level help (verb unknown) or stop here (verb known).
   if (cmds[verb]) {
@@ -2988,7 +2935,7 @@ function cmdPlan(runner, args, runOpts, pretty) {
     }
   }
   emit(plan, pretty, (obj) => {
-    // Human renderer for `brief` / `brief --all` / `plan`. Pre-fix this
+    // Human renderer for `brief` / `brief --all`. Pre-fix this
     // verb dumped 36+ KB of JSON to the terminal — operators running
     // `exceptd brief` to explore had no scannable view.
     const lines = [];
@@ -4380,9 +4327,11 @@ function cmdRunMulti(runner, ids, args, runOpts, pretty, meta) {
   // the aggregate JSON emitted above is allowed to fully drain.
   //
   // Aggregate exit-code precedence: LOCK_CONTENTION > STORAGE_EXHAUSTED >
-  // BLOCKED. Lock contention is transient (retry-from-outside fixes it);
-  // storage exhaustion is an infra event requiring operator action;
-  // ok:false in a per-playbook result is the BLOCKED case. Surfacing the
+  // SESSION_ID_COLLISION > GENERIC_FAILURE. Lock contention is transient
+  // (retry-from-outside fixes it); storage exhaustion is an infra event
+  // requiring operator action; a session-id collision mirrors the single-run
+  // code; any remaining ok:false per-playbook result yields GENERIC_FAILURE
+  // (exit 1) — distinct from the single-run BLOCKED (4) path. Surfacing the
   // most-specific code first means a CI gate can branch on the right
   // remediation without parsing the body.
   const anyLockBusy = results.some(r => r.attestation_persist && r.attestation_persist.lock_contention === true);
@@ -7506,7 +7455,7 @@ function cmdListAttestations(runner, args, runOpts, pretty) {
   }
   // Enumerate sessions across both v0.11.0 default root and legacy cwd-
   // relative root, so operators with prior attestations still see them.
-  // Cycle 11 F5 (v0.12.32): also track candidate roots that didn't exist
+  // also track candidate roots that didn't exist
   // so operators can tell whether the directory was scanned-and-empty or
   // simply never created. Pre-fix the human output said "(no attestations
   // under )" with no path — operators couldn't see where the verb looked.
@@ -7593,7 +7542,7 @@ function cmdListAttestations(runner, args, runOpts, pretty) {
     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,
+    // every candidate root + whether it existed,
     // so JSON consumers can distinguish scanned-and-empty from never-created.
     // The human renderer below also surfaces this rather than printing
     // "(no attestations under )" with an empty path list.
@@ -8395,7 +8344,7 @@ function cmdCi(runner, args, runOpts, pretty) {
   // --scope and --all. Operators specifying an explicit set get exactly that
   // set, no more, no less. Pre-0.11.9 the flag was silently ignored.
   let ids;
-  // Cycle 11 F1 (v0.12.31): positional args (`exceptd ci kernel cred-stores`)
+  // positional args (`exceptd ci kernel cred-stores`)
   // were silently ignored and the cwd-autodetect path ran instead. Operators
   // got a green PASS for playbooks that were never actually executed. Treat
   // positional args as an inline --required, with the same unknown-id refusal.
@@ -8531,7 +8480,7 @@ function cmdCi(runner, args, runOpts, pretty) {
   let clockStartedReasons = [];
 
   for (const id of ids) {
-    // Cycle 9 B4: defense-in-depth — validate id even though the catalog-iter
+    // defense-in-depth — validate id even though the catalog-iter
     // upstream is trusted. A corrupt catalog returning a malformed id would
     // otherwise reach loadPlaybook unchecked. Matches the cmdRunMulti pattern.
     const idCheck = validateIdComponent(id, "playbook");

package/data/_indexes/_meta.json

@@ -1,10 +1,10 @@
 {
   "schema_version": "1.1.0",
-  "generated_at": "2026-05-30T16:43:35.543Z",
+  "generated_at": "2026-05-30T18:46:17.416Z",
   "generator": "scripts/build-indexes.js",
   "source_count": 54,
   "source_hashes": {
-    "manifest.json": "0b52ef7f74953dd925a1a5e718c30e8d4c9b4bb0d43da3109e0e0276837cca68",
+    "manifest.json": "913d165fe1132e187dfdb9938d26d905af595901ad839f7adb079ac3c78445d8",
     "data/atlas-ttps.json": "878b4a08bb73c8d20396d85cf433a88f2bc5e7a8cbf7f6ab773ce7ede0a11251",
     "data/attack-techniques.json": "84fad74c8497cab922ed64b814752f54aa4620c2a938cb06642ff1510e1c5cb3",
     "data/cve-catalog.json": "7a5f4e31401505e53330cdc4b54b39f8a8b04459d6b9411676d291c583ae535f",

package/lib/flag-suggest.js

@@ -10,8 +10,10 @@
  * distance ≤ 2 AND ≤ floor(flag.length / 2).
  *
  * Per-verb allowlists are the canonical CLI surface. Adding a new flag to a
- * verb means appending to the allowlist here AND updating the printPlaybookVerbHelp
- * block; a test asserts the two sets agree.
+ * verb means appending to the allowlist here AND updating the
+ * printPlaybookVerbHelp block; keep the two in sync. doctor maintains its own
+ * KNOWN_DOCTOR_FLAGS set in bin/exceptd.js — keep VERB_FLAG_ALLOWLIST.doctor
+ * aligned with it (tests/lib-flag-suggest.test.js pins the shared flags).
  */
 
 function editDistance(a, b) {
@@ -73,7 +75,7 @@ const VERB_FLAG_ALLOWLIST = Object.freeze({
     'publisher-namespace', 'vex', 'diff-from-latest', 'all', 'scope',
     'strict-preconditions', 'ci', 'block-on-jurisdiction-clock', 'upstream-check',
     'session-key', 'tlp', 'bundle-deterministic', 'bundle-epoch',
-    'include-judgement-shaped',
+    'include-judgement-shaped', 'format',
   ],
   ci: [
     'evidence', 'evidence-dir', 'session-id', 'force-overwrite', 'attestation-root',
@@ -96,12 +98,6 @@ const VERB_FLAG_ALLOWLIST = Object.freeze({
     'mode', 'force-stale', 'tlp',
     'bundle-deterministic', 'bundle-epoch',
   ],
-  ingest: [
-    'evidence', 'session-id', 'force-overwrite', 'attestation-root', 'operator',
-    'ack', 'csaf-status', 'publisher-namespace', 'air-gap', 'force-stale',
-    'strict-preconditions',
-    'bundle-deterministic', 'bundle-epoch',
-  ],
   brief: ['all', 'scope', 'directives', 'flat', 'phase'],
   discover: ['scan-only', 'scope', 'cwd'],
   ask: [],
@@ -112,9 +108,9 @@ const VERB_FLAG_ALLOWLIST = Object.freeze({
   reattest: [
     'playbook', 'since', 'latest', 'force-replay', 'attestation-root',
   ],
-  doctor: ['signatures', 'cves', 'rfcs', 'fix', 'registry-check', 'exit-codes', 'shipped-tarball', 'ai-config', 'currency', 'collectors'],
+  doctor: ['signatures', 'cves', 'rfcs', 'fix', 'registry-check', 'exit-codes', 'shipped-tarball', 'ai-config', 'currency', 'collectors', 'air-gap'],
   lint: ['evidence'],
-  collect: ['cwd', 'attest-ownership', 'resolve'],
+  collect: ['cwd', 'attest-ownership', 'resolve', 'air-gap'],
   refresh: [
     'apply', 'dry-run', 'from-cache', 'from-fixture', 'network', 'source',
     'advisory', 'check-advisories', 'force-stale', 'force-stale-acked', 'air-gap', 'swarm',