@blamejs/exceptd-skills 0.15.44 → 0.15.46

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
@@ -564,6 +562,31 @@ function main() {
     };
   }
 
+  // --quiet: suppress advisory stderr chatter — the "[exceptd] note:" and
+  // "[exceptd] tip:" lines, the deprecation banner, and the unsigned-
+  // attestation warning — while keeping the actual result on stdout and all
+  // errors on stderr. Narrower than --json-stdout-only, which silences ALL
+  // stderr and forces JSON output; --quiet preserves human-readable output and
+  // exit codes and only drops the non-essential advisories. Skipped when
+  // --json-stdout-only is also present (that flag already silenced everything
+  // and patched stderr first; double-wrapping would be redundant).
+  if (argv.includes("--quiet") && !argv.includes("--json-stdout-only")) {
+    global.__exceptdQuiet = true;
+    process.env.EXCEPTD_DEPRECATION_SHOWN = "1";
+    process.env.EXCEPTD_UNSIGNED_WARNED = "1";
+    const origStderrWrite = process.stderr.write.bind(process.stderr);
+    process.stderr.write = (chunk, encoding, cb) => {
+      // Drop only the advisory-prefixed lines. Contract-violation notes
+      // ("[exceptd run] ..."), error frames, and uncaught exceptions still
+      // surface so --quiet never hides why a run failed or exited non-zero.
+      if (typeof chunk === "string" && /^\[exceptd\] (note|tip):/.test(chunk)) {
+        if (typeof cb === "function") cb();
+        return true;
+      }
+      return origStderrWrite(chunk, encoding, cb);
+    };
+  }
+
   if (argv.length === 0) {
     printWelcome();
     process.exit(0);
@@ -572,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);
       }
@@ -705,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`).
@@ -752,7 +787,7 @@ function main() {
   // 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.",
+    skill: "exceptd skill <name>          Show the full context document for one skill. Run `exceptd skill` with no arguments to list all skill IDs.",
     "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). Exit 2 when the citation won't stand up (rejected/fabricated/nonexistent/withdrawn).",
@@ -761,7 +796,7 @@ function main() {
     // to spawning the blocking daemon, hanging the operator's terminal.
     watch: "exceptd watch          Long-running forward-watch daemon (blocks; Ctrl-C to stop). For a one-shot aggregator use `exceptd watchlist`.",
     watchlist: "exceptd watchlist [--alerts] [--org-scan --org <login>] [--by-skill] [--json]   One-shot forward-watch aggregator across skills.",
-    report: "exceptd report [executive] [--json]   Structured posture report.",
+    report: "exceptd report [executive] [--json]   Structured posture report. Markdown by default; pass --json for machine-readable output.",
     scan: "exceptd scan [--json]          [legacy] Working-directory CVE/KEV scan (orchestrator). See `exceptd discover`.",
     dispatch: "exceptd dispatch [--json]      [legacy] Scan + route findings to skills (orchestrator). See `exceptd discover`.",
     currency: "exceptd currency [--json]      [legacy] Skill threat-currency report. See `exceptd doctor --currency`.",
@@ -981,7 +1016,7 @@ function asEvidenceObject(parsed) {
   return parsed;
 }
 
-function readEvidence(evidenceFlag) {
+function readEvidence(evidenceFlag, opts = {}) {
   if (!evidenceFlag) return {};
   // v0.12.12: file-path branch enforces a max size to defend against an
   // operator accidentally passing a multi-gigabyte file (binary, log, or
@@ -1009,7 +1044,7 @@ function readEvidence(evidenceFlag) {
     }
     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
@@ -1017,11 +1052,20 @@ function readEvidence(evidenceFlag) {
       // certainly meant to pipe something. Don't change exit semantics;
       // the empty-payload path is still legitimately useful for posture-
       // only playbooks (govern + direct + look-only walks).
-      process.stderr.write(
-        `[exceptd] note: --evidence - read 0 bytes from stdin. Treating as empty evidence {}. ` +
-        `If you meant to pipe a submission, run \`exceptd brief <playbook>\` to see the expected shape; ` +
-        `if you wanted a posture-only walk, this message is informational and the run will proceed.\n`,
-      );
+      //
+      // Only nudge when `--evidence -` was EXPLICITLY requested. On the stdin
+      // auto-promotion path (no --evidence flag, just a non-TTY handle such as
+      // `run kernel </dev/null` or a CI runner) the operator never asked to
+      // read stdin, so an empty read is not a mistake to flag — and emitting to
+      // stderr there corrupted `run ... 2>&1 | jq` pipelines that worked at a
+      // TTY but broke in CI.
+      if (opts.explicit !== false) {
+        process.stderr.write(
+          `[exceptd] note: --evidence - read 0 bytes from stdin. Treating as empty evidence {}. ` +
+          `If you meant to pipe a submission, run \`exceptd brief <playbook>\` to see the expected shape; ` +
+          `if you wanted a posture-only walk, this message is informational and the run will proceed.\n`,
+        );
+      }
       return {};
     }
     return asEvidenceObject(JSON.parse(text));
@@ -1104,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;
 }
@@ -1527,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
@@ -1688,15 +1731,14 @@ 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)) {
@@ -1853,44 +1895,13 @@ function editDistance(a, b) {
 
 function printPlaybookVerbHelp(verb) {
   const cmds = {
-    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.
+    recipes: `recipes [<id>] — curated multi-skill workflows (use-case → ordered skill chain).
 
-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.
+With no id: lists every recipe with its "when to use" guidance.
+With <id>:  expands that recipe's ordered skill_chain and notes.
 
-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.`,
+Flags:
+  --json   Machine-readable output.`,
     run: `run [playbook] — phases 4-7 (detect → analyze → validate → close).
 
 Invocation modes:
@@ -2006,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:
@@ -2061,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).
@@ -2085,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.
 
@@ -2200,7 +2184,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.
 
@@ -2311,7 +2295,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[]},
@@ -2332,9 +2316,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.
@@ -2348,6 +2333,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.
 
@@ -2390,7 +2377,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]) {
@@ -2884,7 +2871,8 @@ function cmdBrief(runner, args, runOpts, pretty) {
         lines.push(`  ${p.id} (${p.on_fail}): ${pdesc.length > 80 ? pdesc.slice(0, 80) + "…" : pdesc}`);
       }
     }
-    lines.push(`\nRun: exceptd run ${obj.playbook_id} --evidence <file|-> --json`);
+    lines.push(`\nCollect evidence: exceptd collect ${obj.playbook_id} | exceptd run ${obj.playbook_id} --evidence -`);
+    lines.push(`Run with your own evidence: exceptd run ${obj.playbook_id} --evidence <file|-> --json`);
     lines.push(`Full structured doc: --json or --pretty`);
     return lines.join("\n");
   });
@@ -2946,7 +2934,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 = [];
@@ -3223,6 +3211,19 @@ function cmdRun(runner, args, runOpts, pretty) {
   // Single-playbook path (existing behavior).
   const playbookId = positional;
   if (refuseInvalidPlaybookId("run", playbookId, pretty)) return;
+  // --evidence-dir is a contract input: cmdRunMulti reads one
+  // <playbook-id>.json per playbook in an --all / --scope run. With a single
+  // named playbook it was silently ignored, so `run secrets --evidence-dir ./ev`
+  // ran against EMPTY evidence and reported a clean "not_detected" verdict — a
+  // falsely-reassuring result from a security tool. Refuse loudly and point the
+  // operator at the flag that actually loads evidence for one playbook.
+  if (args["evidence-dir"]) {
+    return emitError(
+      `run ${playbookId}: --evidence-dir applies to contract runs (exceptd run --all / --scope <type>), where it reads one <playbook-id>.json per playbook. For a single playbook, pass its evidence directly: exceptd collect ${playbookId} | exceptd run ${playbookId} --evidence -  (or --evidence ${playbookId}.json).`,
+      { playbook: playbookId, provided: "--evidence-dir", use_instead: "--evidence <file|->" },
+      pretty
+    );
+  }
   const pb = runner.loadPlaybook(playbookId);
   const directiveId = args.directive || (pb.directives[0] && pb.directives[0].id);
   if (!directiveId) return refuseNoDirectives("run", playbookId, pretty);
@@ -3286,12 +3287,16 @@ function cmdRun(runner, args, runOpts, pretty) {
   // first, then falls back to a strict isTTY===false check only on Windows
   // (where fstat on a pipe is unreliable). MSYS-bash on win32 reports
   // isTTY === false for genuine piped input, so that path still works.
-  if (!args.evidence && hasReadableStdin()) {
+  const autoStdin = !args.evidence && hasReadableStdin();
+  if (autoStdin) {
     args.evidence = "-";
   }
   if (args.evidence) {
     try {
-      submission = readEvidence(args.evidence);
+      // explicit:false on the auto-promotion path suppresses the empty-stdin
+      // nudge (which otherwise writes to stderr and breaks `run ... 2>&1 | jq`
+      // on every no-evidence CI run); an explicit `--evidence -` still nudges.
+      submission = readEvidence(args.evidence, { explicit: !autoStdin });
     } catch (e) {
       return emitError(`run: failed to read evidence: ${e.message}`, { evidence: args.evidence }, pretty);
     }
@@ -3531,7 +3536,40 @@ function cmdRun(runner, args, runOpts, pretty) {
     // Set exitCode BEFORE emit(): emit's ok:false fallback only fires when
     // exitCode is not already set, so the BLOCKED override survives.
     process.exitCode = args.ci ? EXIT_CODES.BLOCKED : EXIT_CODES.GENERIC_FAILURE;
-    emit(result, pretty);
+    emit(result, pretty, (obj) => {
+      // Human renderer for a halted run. Without this, a blocked verdict
+      // (preflight precondition unmet, mutex conflict, stale currency,
+      // corrupt catalog) dumped the raw ok:false JSON envelope even in human
+      // mode — so a non-Linux operator's first `run` against any Linux-gated
+      // playbook was a wall of JSON instead of one line saying why it stopped
+      // and what to do. --json / --pretty still return the full envelope.
+      const v = obj.verdict || "error";
+      const tag = v === "blocked" ? "[blocked]" : "[error]";
+      const lines = [`${tag}  ${obj.playbook_id || "run"}${obj.directive_id ? ` (${obj.directive_id})` : ""}`];
+      // summary_line is already a complete sentence ("<pb>: blocked at
+      // preflight (<cause>) — <reason>"); prefer it, else fall back to reason.
+      const detail = obj.summary_line || obj.reason;
+      if (detail) lines.push(`  ${detail}`);
+      // remediation is the engine's own actionable next step when it has one;
+      // otherwise synthesize a hint from blocked_by so the operator never hits
+      // a dead end. Hints reference only current verbs (plan/direct were
+      // removed in v0.13.0; brief --all is the replacement listing verb).
+      if (obj.remediation) {
+        lines.push(`  → ${obj.remediation}`);
+      } else {
+        const hints = {
+          precondition: "→ Preconditions are not met on this host (often a platform gate, e.g. a Linux-only playbook). List playbooks that fit your platform: exceptd brief --all",
+          mutex: "→ Another run holds this playbook's mutex. Wait for it to finish, then retry.",
+          currency: "→ Threat intel is stale. Refresh sources (exceptd refresh) or re-run with --force-stale to override.",
+          catalog_corrupt: "→ The CVE catalog failed to load. Reinstall the package or run: exceptd doctor",
+          playbook_not_found: "→ Unknown playbook. List available playbooks: exceptd brief --all",
+          directive_not_found: `→ Unknown directive for this playbook. See its directives: exceptd brief ${obj.playbook_id || "<playbook>"}`,
+        };
+        if (obj.blocked_by && hints[obj.blocked_by]) lines.push(`  ${hints[obj.blocked_by]}`);
+      }
+      lines.push("  Full envelope: re-run with --json");
+      return lines.join("\n");
+    });
     return;
   }
 
@@ -4288,9 +4326,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);
@@ -6386,8 +6426,10 @@ function cmdDoctor(runner, args, runOpts, pretty) {
     "json", "pretty", "fix", "air-gap",
     "signatures", "currency", "cves", "rfcs", "registry-check",
     "ai-config", "collectors", "exit-codes", "shipped-tarball",
-    // Global flags the parser may inject regardless of verb.
-    "_", "json-stdout-only", "_jsonMode",
+    // Global flags the parser may inject regardless of verb. Keep in sync
+    // with VERB_FLAG_ALLOWLIST._global in lib/flag-suggest.js — quiet/verbose
+    // are accepted on every verb, so doctor must not refuse them as typos.
+    "_", "json-stdout-only", "_jsonMode", "quiet", "verbose",
   ]);
   const unknownFlags = Object.keys(args).filter(k => !KNOWN_DOCTOR_FLAGS.has(k));
   if (unknownFlags.length > 0) {
@@ -7285,7 +7327,7 @@ function cmdDoctor(runner, args, runOpts, pretty) {
     if (c.ahead) {
       return `npm registry: local v${c.local_version ?? "?"} AHEAD of published v${c.published_version ?? "?"} (unreleased / dev install)`;
     }
-    return `npm registry: check returned no comparison (raw exit=${c.exit_code ?? "?"})`;
+    return "npm registry: could not compare versions (registry unreachable, offline, or no published version yet). Run `npm view @blamejs/exceptd-skills version` to see the latest, then `npm install -g @blamejs/exceptd-skills@latest` if you are behind.";
   });
   // v0.12.9 (P3 #10): surface shipped_tarball sub-check when --shipped-tarball was used.
   if (checks.signatures?.shipped_tarball) {
@@ -7412,7 +7454,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.
@@ -7499,7 +7541,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.
@@ -8301,7 +8343,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.
@@ -8437,7 +8479,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,13 +1,13 @@
 {
   "schema_version": "1.1.0",
-  "generated_at": "2026-05-30T07:26:49.002Z",
+  "generated_at": "2026-05-30T18:00:00.612Z",
   "generator": "scripts/build-indexes.js",
   "source_count": 54,
   "source_hashes": {
-    "manifest.json": "178af7478515ce7e87d7daadbecccfedc69b819058d5b49f0fd0a9595453c52c",
+    "manifest.json": "cfe4088da8f1fdddb4218f88bbadce04004046ad7105c5e16cc58fdf1aa958b8",
     "data/atlas-ttps.json": "878b4a08bb73c8d20396d85cf433a88f2bc5e7a8cbf7f6ab773ce7ede0a11251",
     "data/attack-techniques.json": "84fad74c8497cab922ed64b814752f54aa4620c2a938cb06642ff1510e1c5cb3",
-    "data/cve-catalog.json": "4a1b5d7a722a0717211058777c7d40d0ded814d231d1cda9e8aa94517da4b905",
+    "data/cve-catalog.json": "7a5f4e31401505e53330cdc4b54b39f8a8b04459d6b9411676d291c583ae535f",
     "data/cwe-catalog.json": "0fd275c2a61754958d68cea03a92794a67cf1c1d4d609f81a5728334df013ee3",
     "data/d3fend-catalog.json": "9a54bccb9f24f84b32024216cc3f53819a053721ac8ab43c326859e68fc0ffaf",
     "data/dlp-controls.json": "d2406c482dddd30e49203879999dc4b3a7fd4d0494d6a61d86b91ee76415df19",
@@ -32,7 +32,7 @@
     "skills/skill-update-loop/skill.md": "16cd5a61ccd87c61901e9b209fff0e26ca6540c0cfcb8e231ac17917c50d56bb",
     "skills/security-maturity-tiers/skill.md": "de7a67b1f6ae79be490656939ac59b5772aa648dae4759733d80d6bf4595c278",
     "skills/researcher/skill.md": "9f1211d177c64e4c465407a45ad9e2901c5c6c0af410a0d0a51cc8fb780420d4",
-    "skills/attack-surface-pentest/skill.md": "6174a20b777a82c83941ef64d27e8c7e4091649358930ac1ba564a0ad4d9399f",
+    "skills/attack-surface-pentest/skill.md": "8d1137c3270763f1c90a3fa8c1c19ab5dc769623c1a35d6a71859bdb8cca2a3e",
     "skills/fuzz-testing-strategy/skill.md": "07e2ee5f773a3f0e82bd21b8a7e8cf6d5b1a8bf3ac6f71602f16550561ade553",
     "skills/dlp-gap-analysis/skill.md": "89dedc6c062fa2afd2284e608f4a51effda819e9288fbf38ab16a7891ccd8a10",
     "skills/supply-chain-integrity/skill.md": "7c568ee9805f4c822c16c266348e35fa6f2d7a3c76135fa34b0cfa77f003a878",
@@ -44,7 +44,7 @@
     "skills/webapp-security/skill.md": "9dc8c0e51c78ad93ef9de91dd9054370dfebeea2161a87f909202ecacfad1504",
     "skills/ai-risk-management/skill.md": "3e116dc6f03f31e32f1ee885516d72d9c11d3ff67d2184108b13dcbdf5f417bf",
     "skills/sector-healthcare/skill.md": "148520af64959a60018a24f4368670925980db3e73aa09af73194f8ea61f1fcc",
-    "skills/sector-financial/skill.md": "eb526fdd9fff84943fff951ca7762de4304adbf3212eb26c73521a8979bb776d",
+    "skills/sector-financial/skill.md": "ad33faa8dddbeb23fed88f464205c630e3fa50c669d3e1ba7ed54f23719efd55",
     "skills/sector-federal-government/skill.md": "870dead2eae1b2664b1e151dd73d8fa240a62a297bdbcddee37bd1cb60e5e5f4",
     "skills/sector-energy/skill.md": "432213dfc9ee271631ce3171daf62a103a010b27a51911dd1112bd5d8bc6c152",
     "skills/sector-telecom/skill.md": "4b80771e78a474e3f43227ecc730ddda1684bff98d7e6e53f5ec373e1e886f34",
@@ -56,7 +56,7 @@
     "skills/ransomware-response/skill.md": "d0f456f1c31ec2968bb4c2cea67eb628d5baf857f17650ab204cf7931b3317ef",
     "skills/email-security-anti-phishing/skill.md": "0965eca982e8fc633b85e70c0ba6becb8c0f5ee7bdd0be96ad73a9a222bb8816",
     "skills/age-gates-child-safety/skill.md": "6d4d29e54a115314c3c0ea9f5df47bdc2828f3b226fff4b5974d898b56c0cd73",
-    "skills/cloud-iam-incident/skill.md": "5ec3800a0049b2123aff67bfab4ff28491a86d2daeb712283e5e88b10c3d5d7b",
+    "skills/cloud-iam-incident/skill.md": "6aab2e400d1e87df7ac2b6f0a17dac6aa99723b217258c4a7b446703d1521775",
     "skills/idp-incident-response/skill.md": "cb2f2c5b90de4592bfd66dcd55f9bf2004f370746d519cad577fcbaf36125878"
   },
   "skill_count": 42,
@@ -78,7 +78,7 @@
     "handoff_dag_nodes": 42,
     "summary_cards": 42,
     "section_offsets_skills": 42,
-    "token_budget_total_approx": 418479,
+    "token_budget_total_approx": 418426,
     "recipes": 8,
     "jurisdiction_clocks": 29,
     "did_ladders": 8,

package/data/_indexes/activity-feed.json

@@ -5,6 +5,14 @@
     "event_count": 54
   },
   "events": [
+    {
+      "date": "2026-05-30",
+      "type": "catalog_update",
+      "artifact": "data/cve-catalog.json",
+      "path": "data/cve-catalog.json",
+      "schema_version": "1.0.0",
+      "entry_count": 427
+    },
     {
       "date": "2026-05-27",
       "type": "catalog_update",
@@ -143,14 +151,6 @@
       "path": "skills/email-security-anti-phishing/skill.md",
       "note": "Email security + anti-phishing for mid-2026 — SPF/DKIM/DMARC/BIMI/ARC/MTA-STS/TLSRPT, AI-augmented phishing (vishing, deepfake video, hyperpersonalized email), Business Email Compromise, secure email gateways"
     },
-    {
-      "date": "2026-05-18",
-      "type": "catalog_update",
-      "artifact": "data/cve-catalog.json",
-      "path": "data/cve-catalog.json",
-      "schema_version": "1.0.0",
-      "entry_count": 427
-    },
     {
       "date": "2026-05-18",
       "type": "catalog_update",

package/data/_indexes/catalog-summaries.json

@@ -53,7 +53,7 @@
       "path": "data/cve-catalog.json",
       "purpose": "Per-CVE record (CVSS, EPSS, CISA KEV, RWEP, AI-discovery, vendor advisories, framework gaps, ATLAS/ATT&CK mappings). Cross-validated against NVD + CISA KEV + FIRST EPSS via validate-cves.",
       "schema_version": "1.0.0",
-      "last_updated": "2026-05-18",
+      "last_updated": "2026-05-30",
       "tlp": "CLEAR",
       "source_confidence_default": "A1",
       "freshness_policy": {