@blamejs/exceptd-skills 0.14.9 → 0.14.11

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 0.14.11 — 2026-05-27
+
+Security: `reattest <session-id>` now validates the session-id before it is joined into a filesystem path, the same gate the other read verbs use. A `../`-bearing id previously escaped the attestation root — reading a forged attestation and writing a signed replay record outside the root. Such an id is now refused (exit 1) and nothing is written.
+
+Air-gap is now honored on every external-source path that previously leaked. `watchlist --org-scan`, `refresh --network`, and `prefetch` all consulted the network even under `--air-gap` / `EXCEPTD_AIR_GAP=1`; each now refuses (or, for `prefetch`, runs report-only) instead of egressing.
+
+The `sbom` collector no longer reports `lockfile-no-integrity` on every clean repository. It counted the npm lockfile's root entry — which legitimately has no integrity hash — as a missing-integrity dependency, so the indicator fired on any normal `package-lock.json`. It now counts only remote-tarball entries that lack integrity.
+
+The `secrets` collector no longer fires on the published AWS documentation example key (`AKIAIOSFODNN7EXAMPLE`), and a text file skipped for exceeding the size limit is now surfaced in `collector_errors` instead of being dropped silently. Secret/citation/crypto findings now carry the exact line in their evidence locations, so SARIF points at the line rather than the file.
+
+Cache-integrity refusals during `refresh` (sha256 mismatch, tampered or unindexed cache) now exit 4 — the documented "cache precondition failed" code — instead of the generic 1. `refresh --source ""` errors with the valid-source list instead of silently running every source; `cve "  "` (whitespace) is treated as a missing argument; `refresh --advisory "  "` gets the dedicated empty-advisory message. `refresh --help` documents exit 1 and the full meaning of exit 4.
+
+Human-readable output gaps closed across several verbs:
+- `run --all` / `run-all` print a per-playbook summary table instead of dumping the full JSON.
+- `attest diff --against` renders the same one-screen summary the no-argument form already did, rather than raw JSON.
+- A matched CVE renders `KEV=Y`/`KEV=N` (not the raw boolean); a deterministic indicator no longer prints `deterministic/deterministic`; a truncated remediation, an over-long fired-indicator list, and the `ci` framework-gap / jurisdiction-clock rollups now show how much was elided; a preflight warning that carries its text in `message` and a runtime warning that carries only context fields are now shown instead of `(no detail)` / a blank line.
+- `framework-gap <framework> <scenario>` summary line counts only the queried framework's gaps, matching the per-framework body (it previously reported the all-frameworks total).
+- `report executive` writes its progress notice to stderr so piped markdown is clean.
+- The synopsis now describes `watchlist` (the one-shot forward-watch aggregator) and `watch` (the long-running daemon) correctly; the inverted deprecation arrow is gone. `cve`/`rfc` help states their exit-2 contract.
+
+## 0.14.10 — 2026-05-27
+
+`ci <playbook> --evidence -` no longer reports a false PASS when handed a flat submission. `run` accepts a flat submission (`{ "signal_overrides": {...} }`) and so do operators by habit; `ci` keyed the input by playbook id, found nothing under that key, and evaluated an empty submission — a detected finding came back PASS. A single-positional `ci` invocation now treats a flat (non-bundle-shaped) submission as belonging to that playbook, so `ci` and `run` agree. A real bundle keyed by playbook id is still routed per-key.
+
+`ai-run <playbook> --no-stream --evidence -` now rejects a non-object submission (`null`, an array, a scalar) at the read boundary, matching `run`. Previously the no-stream path skipped the shape guard and ran a malformed submission as if it were empty, so an operator believed a bad payload had been evaluated.
+
+The `ci` framework-gap rollup now carries the gap explanation. Each rollup entry's `why_insufficient` was always null because the rollup read a field that doesn't exist on a gap record; the text lives in `actual_gap`, which is now surfaced (alongside `required_control`).
+
+A regulatory clock now starts on an engine-confirmed detection, not only on an agent-submitted classification. When indicators fire and the engine itself classifies the detect phase as `detected`, `--ack` starts the notification clock and computes the jurisdiction deadlines — previously the clock only moved if the submission also carried `detection_classification: "detected"`, so an engine-confirmed finding left every deadline stalled at `pending_clock_start_event`.
+
+`framework-gap <framework> <scenario>` refuses an unknown framework instead of returning a zero-gap report that reads as "no gaps found." A typo or an untracked framework now errors with the list of frameworks the catalog covers; the documented short forms (`NIST-800-53`, `PCI-DSS-4.0`) and `all` continue to resolve.
+
 ## 0.14.9 — 2026-05-27
 
 `refresh --advisory <id> --air-gap` now refuses (no network) instead of egressing. The `--air-gap` flag was parsed but dropped before the fetch, so an air-gapped advisory seed silently reached GHSA/OSV — an air-gap-guarantee violation. Both the flag and the `EXCEPTD_AIR_GAP=1` env now refuse identically.

package/bin/exceptd.js

@@ -464,7 +464,8 @@ Canonical verbs
                              (citation-hygiene) resolves uncatalogued citations.
   skill <name>               Show context for a specific skill.
   framework-gap <fw> <ref>   Programmatic gap analysis (one framework, one CVE/scenario).
-  watch [--alerts]           Forward-watch aggregator across skills.
+  watchlist [--alerts]       Forward-watch aggregator across skills (one-shot).
+  watch                      Long-running forward-watch daemon (blocks; Ctrl-C).
   report [executive]         Structured posture report.
   path                       Absolute path to the installed package.
   version                    Package version.
@@ -519,7 +520,6 @@ surfaces.
   [DEPRECATED] verify            → doctor --signatures
   [DEPRECATED] validate-cves     → doctor --cves
   [DEPRECATED] validate-rfcs     → doctor --rfcs
-  [DEPRECATED] watchlist         → watch
   [DEPRECATED] prefetch          → refresh --no-network
   [DEPRECATED] build-indexes     → refresh --indexes-only
 
@@ -759,8 +759,8 @@ function main() {
     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).",
+    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).",
+    rfc: "exceptd rfc <number> [--check \"<title>\"] [--json] [--air-gap]   Resolve an RFC number -> title + status (local index, offline). Exit 2 when nonexistent or --check title MISMATCH.",
   };
   if ((effectiveRest.includes("--help") || effectiveRest.includes("-h")) && SPAWN_HELP_USAGE[effectiveCmd]) {
     process.stdout.write(SPAWN_HELP_USAGE[effectiveCmd] + "\n  Full reference: exceptd help\n");
@@ -2858,13 +2858,14 @@ function cmdBrief(runner, args, runOpts, pretty) {
     const required = (obj.artifacts || []).filter(a => a.required);
     const optional = (obj.artifacts || []).filter(a => !a.required);
     lines.push(`\nRequired artifacts (${required.length}): ${required.map(a => a.id).join(", ") || "(none)"}`);
-    if (optional.length) lines.push(`Optional artifacts (${optional.length}): ${optional.map(a => a.id).slice(0, 8).join(", ")}${optional.length > 8 ? ", …" : ""}`);
+    if (optional.length) lines.push(`Optional artifacts (${optional.length}): ${optional.map(a => a.id).slice(0, 8).join(", ")}${optional.length > 8 ? `, … +${optional.length - 8}` : ""}`);
     const indicators = obj.detect_indicators_preview || [];
-    lines.push(`\nIndicators (${indicators.length}): ${indicators.map(i => i.id).slice(0, 8).join(", ")}${indicators.length > 8 ? ", …" : ""}`);
+    lines.push(`\nIndicators (${indicators.length}): ${indicators.map(i => i.id).slice(0, 8).join(", ")}${indicators.length > 8 ? `, … +${indicators.length - 8}` : ""}`);
     if (obj.preconditions?.length) {
       lines.push(`\nPreconditions (${obj.preconditions.length}):`);
       for (const p of obj.preconditions) {
-        lines.push(`  ${p.id} (${p.on_fail}): ${p.description?.slice(0, 80) || p.check}`);
+        const pdesc = p.description || p.check || "";
+        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`);
@@ -3859,7 +3860,7 @@ function cmdRun(runner, args, runOpts, pretty) {
       lines.push(`\nMatched CVEs (${cves.length}):`);
       for (const c of cves.slice(0, 6)) {
         const via = Array.isArray(c.correlated_via) && c.correlated_via.length ? `  via ${c.correlated_via[0]}${c.correlated_via.length > 1 ? ` (+${c.correlated_via.length - 1})` : ""}` : "";
-        lines.push(`  ${c.cve_id}  RWEP ${c.rwep}  KEV=${c.cisa_kev}  ${c.active_exploitation || ""}${via}`);
+        lines.push(`  ${c.cve_id}  RWEP ${c.rwep}  KEV=${c.cisa_kev ? "Y" : "N"}  ${c.active_exploitation || ""}${via}`);
       }
       if (cves.length > 6) lines.push(`  … ${cves.length - 6} more`);
     } else if (baseline.length) {
@@ -3872,7 +3873,13 @@ function cmdRun(runner, args, runOpts, pretty) {
     const hits = indicators.filter(i => i.verdict === "hit");
     if (hits.length) {
       lines.push(`\nIndicators that fired (${hits.length}):`);
-      for (const i of hits.slice(0, 8)) lines.push(`  ${i.id}  (${i.confidence}${i.deterministic ? "/deterministic" : ""})`);
+      for (const i of hits.slice(0, 8)) {
+        // Don't double-print "deterministic/deterministic" when confidence is
+        // already the literal "deterministic".
+        const detSuffix = (i.deterministic && i.confidence !== "deterministic") ? "/deterministic" : "";
+        lines.push(`  ${i.id}  (${i.confidence}${detSuffix})`);
+      }
+      if (hits.length > 8) lines.push(`  … ${hits.length - 8} more`);
     }
     // selected_remediation is informational on non-detect runs:
     // validate() always picks the highest-priority remediation path
@@ -3888,7 +3895,8 @@ function cmdRun(runner, args, runOpts, pretty) {
       } else {
         lines.push(`\nRemediation path (informational — verdict=${cls}, no action required now): ${rem.id} (priority ${rem.priority})`);
       }
-      lines.push(`  ${rem.description?.slice(0, 200) || ""}`);
+      const remDesc = rem.description || "";
+      lines.push(`  ${remDesc.length > 200 ? remDesc.slice(0, 200) + "… (full steps: --json)" : remDesc}`);
     }
     // Surface BOTH started and pending notification clocks on detected
     // runs. The detection IS the regulatory event for the obligations
@@ -3940,7 +3948,9 @@ function cmdRun(runner, args, runOpts, pretty) {
       // to the description if `check` is missing too.
       for (const i of issues) {
         const tag = i.on_fail ? `[${i.on_fail}] ` : "";
-        const detail = i.check || i.description || i.reason || "(no detail)";
+        // precondition_warn issues carry their text in `message`; without it in
+        // the fallback chain they rendered "(no detail)".
+        const detail = i.check || i.description || i.reason || i.message || "(no detail)";
         lines.push(`  ${tag}${i.id}: ${detail}`);
       }
     }
@@ -3953,7 +3963,11 @@ function cmdRun(runner, args, runOpts, pretty) {
     if (runtimeErrors.length) {
       lines.push(`\nRuntime warnings (${runtimeErrors.length}):`);
       for (const e of runtimeErrors) {
-        const reason = (e.reason || "").length > 180 ? (e.reason || "").slice(0, 177) + "..." : (e.reason || "");
+        // Some runtime-warning kinds (e.g. csaf_branch_unparseable) carry no
+        // `reason` but do carry context fields (component / cve_id); compose
+        // from those rather than rendering a blank line.
+        const rawReason = e.reason || [e.component, e.cve_id].filter(Boolean).join(" / ") || "(no detail)";
+        const reason = rawReason.length > 180 ? rawReason.slice(0, 177) + "..." : rawReason;
         lines.push(`  [${e.kind || "warning"}] ${reason}`);
         if (e.remediation) lines.push(`    → ${e.remediation}`);
       }
@@ -4242,7 +4256,39 @@ function cmdRunMulti(runner, ids, args, runOpts, pretty, meta) {
     },
     jurisdiction_clock_rollup: jurisdictionClockRollup,
     results,
-  }, pretty);
+  }, pretty, (obj) => {
+    // Per-playbook summary table. Without this renderer a multi-run dumped its
+    // entire (often hundreds-of-KB) JSON even in default human mode.
+    const s = obj.summary;
+    const lines = [];
+    const detectedTotal = s.detected;
+    const icon = s.blocked > 0 ? "[!! BLOCKED]" : detectedTotal > 0 ? "[!! DETECTED]" : "[ok]";
+    lines.push(`run ${obj.trigger || "multi"}: ${obj.playbooks_run.length} playbook(s)  session-id: ${obj.session_id}`);
+    lines.push(`\n${icon}  detected=${detectedTotal}  inconclusive=${s.inconclusive}  clean=${s.total - detectedTotal - s.inconclusive - s.blocked}  blocked=${s.blocked}  total=${s.total}`);
+    const rows = (obj.results || []).map(r => (r && r.ok === false)
+      ? { id: r.playbook_id || "?", verdict: "blocked", rwep: "-", evidence: r.evidence_completeness || "not-evaluated", top: r.blocked_by || r.reason || r.error || "" }
+      : { id: r.playbook_id || "?", verdict: r?.phases?.detect?.classification || r?.verdict || "?", rwep: (r?.rwep_score != null) ? String(r.rwep_score) : "-", evidence: r?.evidence_completeness || "unknown", top: r?.top_finding || "" });
+    const wId = Math.max(8, ...rows.map(r => r.id.length));
+    const wV = Math.max(8, ...rows.map(r => r.verdict.length));
+    const wR = Math.max(4, ...rows.map(r => r.rwep.length));
+    const wE = Math.max(8, ...rows.map(r => r.evidence.length));
+    const pad = (str, w) => (str + " ".repeat(w)).slice(0, w);
+    lines.push("");
+    lines.push(`  ${pad("playbook", wId)}  ${pad("verdict", wV)}  ${pad("rwep", wR)}  ${pad("evidence", wE)}  finding`);
+    lines.push(`  ${"-".repeat(wId)}  ${"-".repeat(wV)}  ${"-".repeat(wR)}  ${"-".repeat(wE)}  -------`);
+    for (const row of rows) {
+      const finding = row.top.length > 80 ? row.top.slice(0, 77) + "..." : row.top;
+      lines.push(`  ${pad(row.id, wId)}  ${pad(row.verdict, wV)}  ${pad(row.rwep, wR)}  ${pad(row.evidence, wE)}  ${finding}`);
+    }
+    const clocks = obj.jurisdiction_clock_rollup || [];
+    if (clocks.length) {
+      lines.push(`\nJurisdiction clocks (${clocks.length}):`);
+      for (const n of clocks.slice(0, 5)) lines.push(`  ${n.jurisdiction || "?"}/${n.regulation || "?"} → deadline ${n.deadline || "?"}`);
+      if (clocks.length > 5) lines.push(`  … ${clocks.length - 5} more (--json for all)`);
+    }
+    lines.push(`\nFull structured results: --json or --pretty`);
+    return lines.join("\n");
+  });
   // v0.11.9 (#100): cmdRunMulti exits non-zero when any individual run
   // returned ok:false. Pre-0.11.9 the aggregate result had {ok:false} in
   // the body but exit code stayed 0 — CI gates couldn't distinguish "ran
@@ -5076,6 +5122,15 @@ function cmdReattest(runner, args, runOpts, pretty) {
     attFile = found.file;
   }
   if (!sessionId) return emitError("reattest: missing <session-id>. Pass a session-id or --latest [--playbook <id>] [--since <ISO>].", null, pretty);
+  // Validate the session-id BEFORE it is joined into a filesystem path. The
+  // other read verbs (attest show/verify/diff --against) gate on this; reattest
+  // did not, so `findSessionDir` returning null let the `||` fallback join an
+  // unvalidated `../`-bearing id straight onto the attestation root — escaping
+  // it to read a forged attestation and write a signed replay record outside
+  // the root. Ids resolved from the store via the latest-match path are already
+  // safe; an operator-supplied id is the one that must be checked.
+  try { validateSessionIdForRead(sessionId); }
+  catch (e) { return emitError(`reattest: ${e.message}`, { session_id_input: typeof sessionId === "string" ? sessionId.slice(0, 80) : typeof sessionId }, pretty); }
   const dir = findSessionDir(sessionId, runOpts) || path.join(resolveAttestationRoot(runOpts), sessionId);
   if (!attFile) attFile = path.join(dir, "attestation.json");
   if (!fs.existsSync(attFile)) {
@@ -5437,6 +5492,31 @@ function classifySidecarVerify(verify) {
  *   show <session-id>     Emit the full (unredacted) attestation. Convenience
  *                         alias for `cat .exceptd/attestations/<sid>/attestation.json`.
  */
+// Shared one-screen renderer for `attest diff` (both the --against and the
+// no-against/most-recent-prior branches). Reads only fields off the emitted
+// object so both call sites render identically; the sidecar line is shown only
+// when a sidecar verification was performed (the --against path may omit it).
+function renderAttestDiff(obj) {
+  const lines = [];
+  lines.push(`attest diff: ${obj.a_session}${obj.a_playbook ? ` (${obj.a_playbook})` : ""}`);
+  lines.push(`  vs ${obj.b_session}${obj.b_captured ? ` (captured ${obj.b_captured})` : ""}`);
+  const icon = obj.status === "unchanged" ? "[ok]" : "[!]";
+  lines.push(`  ${icon}  status=${obj.status}  evidence_hash=${(obj.a_evidence_hash || "").slice(0, 12)}...`);
+  const ad = obj.artifact_diff || {};
+  const sd = obj.signal_override_diff || {};
+  lines.push(`  artifact diff:  ${ad.added?.length ?? 0} added, ${ad.removed?.length ?? 0} removed, ${ad.changed?.length ?? 0} changed, ${ad.unchanged_count ?? 0} unchanged (of ${ad.total_compared ?? 0})`);
+  lines.push(`  signal diff:    ${sd.changed?.length ?? 0} changed, ${sd.unchanged_count ?? 0} unchanged (of ${sd.total_compared ?? 0})`);
+  if (obj.sidecar_verify) {
+    const sv = obj.sidecar_verify;
+    let sidecarClass = "verified";
+    if (!sv.signed && sv.reason && sv.reason.includes("explicitly unsigned")) sidecarClass = "explicitly-unsigned";
+    else if (!sv.signed && sv.reason && sv.reason.includes("no .sig sidecar")) sidecarClass = "no-sidecar";
+    else if (sv.signed && !sv.verified) sidecarClass = "tamper-detected";
+    else if (!sv.signed) sidecarClass = "no-public-key";
+    lines.push(`  sidecar verify: ${sidecarClass}`);
+  }
+  return lines.join("\n");
+}
 function cmdAttest(runner, args, runOpts, pretty) {
   const subverb = args._[0];
   const sessionId = args._[1];
@@ -5574,12 +5654,14 @@ function cmdAttest(runner, args, runOpts, pretty) {
       emit({
         verb: "attest diff",
         a_session: sessionId,
+        a_playbook: self.playbook_id,
         b_session: args.against,
         a_captured: self.captured_at,
         b_captured: other.captured_at,
         a_evidence_hash: self.evidence_hash,
         b_evidence_hash: other.evidence_hash,
         status: self.evidence_hash === other.evidence_hash ? "unchanged" : "drifted",
+        sidecar_verify: verifyAttestationSidecar(path.join(dir, "attestation.json")),
         // v0.11.8 (#102): normalize submissions before diffing so flat-shape
         // (observations + verdict) submissions emit meaningful artifact_diff
         // counts. Pre-0.11.8 (self.submission||{}).artifacts was undefined
@@ -5593,7 +5675,7 @@ function cmdAttest(runner, args, runOpts, pretty) {
           normalizedSignalOverrides(self.submission, runner, self.playbook_id),
           normalizedSignalOverrides(other.submission, runner, other.playbook_id)
         ),
-      }, pretty);
+      }, pretty, renderAttestDiff);
       return;
     }
     // No --against: find the most-recent prior attestation for the
@@ -5628,6 +5710,7 @@ function cmdAttest(runner, args, runOpts, pretty) {
     emit({
       verb: "attest diff",
       a_session: sessionId,
+      a_playbook: self.playbook_id,
       b_session: prior.sessionId,
       a_captured: self.captured_at,
       b_captured: other.captured_at,
@@ -5643,28 +5726,7 @@ function cmdAttest(runner, args, runOpts, pretty) {
         normalizedSignalOverrides(self.submission, runner, self.playbook_id),
         normalizedSignalOverrides(other.submission, runner, other.playbook_id),
       ),
-    }, pretty, (obj) => {
-      // Human renderer for the no-against `attest diff` path. Same
-      // one-screen shape the old cmdReattest renderer used so the
-      // operator sees the verdict + drift summary + sidecar class.
-      const lines = [];
-      lines.push(`attest diff: ${obj.a_session} (${self.playbook_id})`);
-      lines.push(`  vs prior: ${obj.b_session} (captured ${obj.b_captured})`);
-      const icon = obj.status === "unchanged" ? "[ok]" : "[!]";
-      lines.push(`  ${icon}  status=${obj.status}  evidence_hash=${(obj.a_evidence_hash || "").slice(0, 12)}...`);
-      const ad = obj.artifact_diff || {};
-      const sd = obj.signal_override_diff || {};
-      lines.push(`  artifact diff:  ${ad.added?.length ?? 0} added, ${ad.removed?.length ?? 0} removed, ${ad.changed?.length ?? 0} changed, ${ad.unchanged_count ?? 0} unchanged (of ${ad.total_compared ?? 0})`);
-      lines.push(`  signal diff:    ${sd.changed?.length ?? 0} changed, ${sd.unchanged_count ?? 0} unchanged (of ${sd.total_compared ?? 0})`);
-      const sv = obj.sidecar_verify || {};
-      let sidecarClass = "verified";
-      if (!sv.signed && sv.reason && sv.reason.includes("explicitly unsigned")) sidecarClass = "explicitly-unsigned";
-      else if (!sv.signed && sv.reason && sv.reason.includes("no .sig sidecar")) sidecarClass = "no-sidecar";
-      else if (sv.signed && !sv.verified) sidecarClass = "tamper-detected";
-      else if (!sv.signed) sidecarClass = "no-public-key";
-      lines.push(`  sidecar verify: ${sidecarClass}`);
-      return lines.join("\n");
-    });
+    }, pretty, renderAttestDiff);
     return;
   }
 
@@ -7544,17 +7606,47 @@ function cmdAiRun(runner, args, runOpts, pretty) {
     // Read any pre-supplied evidence from stdin OR from --evidence flag.
     let payload = { observations: {}, verdict: {} };
     if (args.evidence) {
-      try { payload = readEvidence(args.evidence); }
+      // Apply the same shape guard `run` enforces at its read boundary: a
+      // submission must be a JSON object. Without this, `--no-stream` accepted
+      // `null` / `[]` / a scalar and ran as if empty, so an operator believed a
+      // malformed submission was evaluated (the streaming path is unaffected —
+      // it only fires on a well-formed evidence event).
+      try { payload = asEvidenceObject(readEvidence(args.evidence)); }
       catch (e) { return emitError(`ai-run: failed to read --evidence: ${e.message}`, null, pretty); }
     } else if (hasReadableStdin()) {
       // hasReadableStdin() probes via fstat before falling into
       // readFileSync(0). Wrapped-stdin test harnesses (isTTY===undefined,
       // size===0) would otherwise hang here.
       // Drain stdin for any evidence event.
-      try {
-        const buf = fs.readFileSync(0, "utf8");
-        if (buf.trim()) {
-          // Accept either a bare submission object or a single evidence event.
+      let buf = "";
+      try { buf = fs.readFileSync(0, "utf8"); }
+      catch { /* stdin empty / unreadable — fall through with empty payload */ }
+      if (buf.trim()) {
+        // First treat stdin as a single JSON document — the common
+        // `echo '<json>' | ai-run … --no-stream` shape. If it parses as one
+        // value we can apply the same shape guard `--evidence` gets: a bare
+        // `null` / `[]` / scalar is a malformed submission, not "no evidence",
+        // and must be rejected rather than silently run as empty.
+        let single;
+        let singleParsed = false;
+        try { single = JSON.parse(buf); singleParsed = true; } catch { /* not a single doc — fall to JSONL scan */ }
+        if (singleParsed) {
+          // An evidence event wrapper is the one object shape that is NOT
+          // itself the submission — unwrap it before guarding.
+          if (single && typeof single === "object" && !Array.isArray(single) && single.event === "evidence" && single.payload) {
+            payload = single.payload;
+          } else {
+            try { payload = asEvidenceObject(single); }
+            catch (e) { return emitError(`ai-run: failed to read evidence from stdin: ${e.message}`, null, pretty); }
+            // Normalize a bare submission into the {observations, verdict} shape.
+            if (!payload.observations && (payload.artifacts || payload.signal_overrides || payload.signals)) {
+              payload = { observations: { ...(payload.artifacts || {}), ...(payload.signal_overrides || {}) }, verdict: payload.signals || {} };
+            }
+          }
+        } else {
+          // JSONL / interleaved host-AI chatter: scan line-by-line for the
+          // first evidence event or bare submission, ignoring non-matching
+          // status frames the host may interleave.
           for (const line of buf.split(/\r?\n/)) {
             const t = line.trim();
             if (!t) continue;
@@ -7574,7 +7666,7 @@ function cmdAiRun(runner, args, runOpts, pretty) {
             } catch { /* skip non-JSON lines */ }
           }
         }
-      } catch { /* stdin empty / unreadable — fall through with empty payload */ }
+      }
     }
     const submission = buildSubmissionFromPayload(payload);
     let result;
@@ -8213,6 +8305,20 @@ function cmdCi(runner, args, runOpts, pretty) {
     }
   }
 
+  // Flat-submission tolerance for a single positional playbook. `ci` keys its
+  // bundle by playbook id (so --evidence-dir / multi-playbook bundles work),
+  // but `ci <pb> --evidence -` with the SAME flat/nested submission shape that
+  // `run` accepts would otherwise land as bundle[<pb>]=undefined → empty run →
+  // a false PASS that silently ignores the operator's evidence. When exactly
+  // one playbook is in scope and the bundle carries no playbook-id key (it's a
+  // single submission, not a multi-playbook bundle), treat it as that
+  // playbook's evidence.
+  if (ids.length === 1 && Object.keys(bundle).length > 0 && !(ids[0] in bundle)) {
+    const allIds = new Set(runner.listPlaybooks());
+    const looksLikeBundle = Object.keys(bundle).some(k => allIds.has(k));
+    if (!looksLikeBundle) bundle = { [ids[0]]: bundle };
+  }
+
   const results = [];
   let fail = false;
   let failReasons = [];
@@ -8340,7 +8446,10 @@ function cmdCi(runner, args, runOpts, pretty) {
         gapRollupMap.set(key, {
           framework: g.framework || null,
           claimed_control: g.claimed_control || null,
-          why_insufficient: g.why_insufficient || null,
+          // The explanatory text lives in `actual_gap`; the rollup previously
+          // read a nonexistent `why_insufficient` key and so was always null.
+          why_insufficient: g.actual_gap || g.why_insufficient || null,
+          required_control: g.required_control || null,
           playbooks: [r.playbook_id],
         });
       }
@@ -8529,17 +8638,21 @@ function cmdCi(runner, args, runOpts, pretty) {
       // Jurisdiction clocks.
       if (s.jurisdiction_clocks_started > 0) {
         lines.push(`\nJurisdiction clocks started: ${s.jurisdiction_clocks_started}`);
-        for (const n of (s.jurisdiction_clock_rollup || []).slice(0, 5)) {
+        const clocks = s.jurisdiction_clock_rollup || [];
+        for (const n of clocks.slice(0, 5)) {
           lines.push(`  ${n.jurisdiction || "?"}/${n.regulation || "?"} → deadline ${n.deadline || "?"}`);
         }
+        if (clocks.length > 5) lines.push(`  … ${clocks.length - 5} more (--json for all)`);
       }
 
       // Framework gap rollup.
       if (s.framework_gap_count > 0) {
         lines.push(`\nFramework gaps (${s.framework_gap_count}):`);
-        for (const g of (s.framework_gap_rollup || []).slice(0, 5)) {
+        const fgaps = s.framework_gap_rollup || [];
+        for (const g of fgaps.slice(0, 5)) {
           lines.push(`  ${g.framework || "?"} :: ${g.claimed_control || "?"}  (${g.playbooks.length} playbook(s))`);
         }
+        if (fgaps.length > 5) lines.push(`  … ${fgaps.length - 5} more (--json for all)`);
       }
 
       // Fail reasons.
@@ -8561,17 +8674,21 @@ function cmdCi(runner, args, runOpts, pretty) {
       //   CLOCK_STARTED  → notification clock running; see deadline above.
       //   PASS           → nothing to do.
       const blockedRows = (obj.results || []).filter(r => r && r.ok === false);
-      const lintCmd = (id) => `  exceptd lint ${id} -                          # paste {} on stdin, get exact JSON paths`;
+      // Pad the playbook id to a common width so the trailing `#` comments line
+      // up across variable-length ids instead of using a fixed space run.
+      const lintCmd = (id, w) => `  exceptd lint ${(id + " ".repeat(w)).slice(0, w)} -   # paste {} on stdin, get exact JSON paths`;
       if (s.verdict === "BLOCKED" && blockedRows.length) {
         lines.push(`\nNext steps (unblock the ${blockedRows.length} halted playbook(s)):`);
-        for (const row of blockedRows.slice(0, 4)) {
-          lines.push(lintCmd(row.playbook_id || "?"));
+        const shown = blockedRows.slice(0, 4);
+        const wLint = Math.max(...shown.map(r => (r.playbook_id || "?").length));
+        for (const row of shown) {
+          lines.push(lintCmd(row.playbook_id || "?", wLint));
         }
         lines.push(`  exceptd run <playbook> --evidence <file>     # re-run after filling in evidence`);
       } else if (s.verdict === "NO_EVIDENCE") {
         const firstId = (obj.results[0] && obj.results[0].playbook_id) || (obj.playbooks_run[0]) || "<playbook>";
         lines.push(`\nNext steps (every playbook ran inconclusive — no evidence supplied):`);
-        lines.push(lintCmd(firstId));
+        lines.push(lintCmd(firstId, firstId.length));
         lines.push(`  exceptd ci --scope <type> --evidence-dir <dir>  # gate again with real submissions`);
       } else if (s.verdict === "FAIL") {
         // FAIL fires in two distinct shapes:

package/data/_indexes/_meta.json

@@ -1,10 +1,10 @@
 {
   "schema_version": "1.1.0",
-  "generated_at": "2026-05-27T18:39:39.915Z",
+  "generated_at": "2026-05-27T20:36:13.795Z",
   "generator": "scripts/build-indexes.js",
   "source_count": 54,
   "source_hashes": {
-    "manifest.json": "9b1abf00a40118b264552a1897b4d1857e831d33e929a5179a1bf83348e04999",
+    "manifest.json": "3db842fa75688111c96edd57712b9447a3df84cb250df1e052ac45b38aff74f2",
     "data/atlas-ttps.json": "d24bc02859d40ccf1615db75cca68c077585904e41e0d8f6de448121e9b1abb0",
     "data/attack-techniques.json": "fa193f0d2d248176a8beddb641e9fe56ba4faa9e15dc253ff876dbf0c5d58a77",
     "data/cve-catalog.json": "3d451dda7ac0c7d57a4075ae4bafd3148c6184b35dc1bc59d8b81d1f2641e430",

package/lib/citation-resolve.js

@@ -116,7 +116,10 @@ function isAirGap(opts) {
  * from:   format | catalog | cache | network | offline | error
  */
 async function resolveCve(id, opts = {}) {
-  const cveId = String(id || "").toUpperCase();
+  // Trim before the format test — matches resolveRfc — so a whitespace-only
+  // identifier is "fabricated/malformed" (empty form) rather than a literal
+  // whitespace string fed straight into CVE_RE.
+  const cveId = String(id || "").trim().toUpperCase();
   const base = { id: cveId, kind: "cve" };
 
   if (!CVE_RE.test(cveId)) {

package/lib/collectors/cicd-pipeline-compromise.js

@@ -21,7 +21,13 @@
 
 const fs = require("node:fs");
 const path = require("node:path");
-const { isLinkedWorktreeDir, buildEvidenceLocations } = require("./scan-excludes");
+const { codeExcludeSet, isLinkedWorktreeDir, buildEvidenceLocations } = require("./scan-excludes");
+
+// Shared code-scope name exclusions (dependency caches, build output, VCS +
+// agent scratch). Threaded into the OIDC-policy descent so a trust JSON in a
+// build-output dir (e.g. `dist/`) is not scanned — consistent with the other
+// tree-walking collectors.
+const OIDC_WALK_EXCLUDES = codeExcludeSet();
 
 const COLLECTOR_ID = "cicd-pipeline-compromise";
 
@@ -218,7 +224,7 @@ function scanOidcPolicies(root) {
     try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
     catch { return; }
     for (const e of entries) {
-      if (e.name === "node_modules" || e.name === ".git") continue;
+      if (OIDC_WALK_EXCLUDES.has(e.name)) continue;
       const full = path.join(dir, e.name);
       if (e.isDirectory()) {
         // Skip linked git worktrees (gitdir-pointer `.git` file), e.g.

package/lib/collectors/citation-hygiene.js

@@ -30,7 +30,7 @@
 const fs = require("node:fs");
 const path = require("node:path");
 
-const { codeExcludeSet, isLinkedWorktreeDir, buildEvidenceLocations } = require("./scan-excludes");
+const { codeExcludeSet, isLinkedWorktreeDir, buildEvidenceLocations, lineFromOffset } = require("./scan-excludes");
 
 const COLLECTOR_ID = "citation-hygiene";
 
@@ -334,12 +334,15 @@ function collect({ cwd = process.cwd() } = {}) {
     for (const m of content.matchAll(CVE_CITATION_RE)) {
       const full = m[0];
       totalCveCitations++;
+      // 1-based line of the citation so the evidence location carries a SARIF
+      // startLine region. Does not change any hit/miss verdict.
+      const cveLine = lineFromOffset(content, m.index);
       const canonical = CVE_CANONICAL_RE.test(full);
       if (!canonical) {
         // Fabricated / malformed. Illustrative surfaces (templates,
         // fixtures, the format-explaining docs) are demoted.
         if (!illustrative) {
-          hits["fabricated-cve-id"].push({ file: f.rel, citation: full });
+          hits["fabricated-cve-id"].push({ file: f.rel, citation: full, line: cveLine });
         }
         continue;
       }
@@ -347,7 +350,7 @@ function collect({ cwd = process.cwd() } = {}) {
       if (cveKeys.has(full)) {
         const note = cveNotes.get(full) || "";
         if (REJECT_DISPUTE_RE.test(note) && !illustrative) {
-          hits["rejected-or-disputed-cve"].push({ file: f.rel, citation: full });
+          hits["rejected-or-disputed-cve"].push({ file: f.rel, citation: full, line: cveLine });
         }
       } else if (catalogsLoaded && !illustrative) {
         // Absent from the curated catalog: needs an external lookup.
@@ -362,6 +365,7 @@ function collect({ cwd = process.cwd() } = {}) {
       const num = Number(m[1]);
       if (!Number.isFinite(num)) continue;
       const line = lineAround(content, m.index);
+      const rfcLineNo = lineFromOffset(content, m.index);
       if (rfcTitles.has(num)) {
         const verdict = classifyRfcTitle(line, rfcTitles.get(num));
         if (verdict === "mismatch" && !illustrative) {
@@ -369,6 +373,7 @@ function collect({ cwd = process.cwd() } = {}) {
             file: f.rel,
             citation: `RFC ${num}`,
             real_title: rfcTitles.get(num),
+            line: rfcLineNo,
           });
         }
       } else if (catalogsLoaded && !illustrative) {
@@ -449,8 +454,8 @@ function collect({ cwd = process.cwd() } = {}) {
 
   // Per-indicator file locations for the indicators flipped to "hit",
   // so SARIF results point at the source file that carries the bad
-  // citation. The hits record the file but not a line, so locations are
-  // file-level (no startLine).
+  // citation. The hits record a 1-based `line` (from the match offset),
+  // so locations include a startLine region.
   const evidence_locations = {};
   for (const id of Object.keys(hits)) {
     if (signal_overrides[id] === "hit") {

package/lib/collectors/crypto-codebase.js

@@ -16,7 +16,7 @@
 
 const fs = require("node:fs");
 const path = require("node:path");
-const { codeExcludeSet, isLinkedWorktreeDir, buildEvidenceLocations } = require("./scan-excludes");
+const { codeExcludeSet, isLinkedWorktreeDir, buildEvidenceLocations, lineFromOffset } = require("./scan-excludes");
 
 const COLLECTOR_ID = "crypto-codebase";
 
@@ -298,14 +298,17 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
       if (RSA_1024_RE.test(content)) {
         hits["rsa-1024-anywhere"].push({ file: f.rel });
       }
+      // Attach a 1-based `line` (from the match offset) so the evidence
+      // location carries a SARIF startLine region rather than pointing at
+      // the file. Does not change hit/miss — the same matches still fire.
       const mrHits = scanMathRandom(content);
-      for (const h of mrHits) hits["math-random-in-security-path"].push({ file: f.rel, offset: h.offset });
+      for (const h of mrHits) hits["math-random-in-security-path"].push({ file: f.rel, offset: h.offset, line: lineFromOffset(content, h.offset) });
 
       const pHits = scanPbkdf2(content);
-      for (const h of pHits) hits["pbkdf2-under-iterated"].push({ file: f.rel, iter: h.iter, threshold: h.threshold });
+      for (const h of pHits) hits["pbkdf2-under-iterated"].push({ file: f.rel, offset: h.offset, line: lineFromOffset(content, h.offset), iter: h.iter, threshold: h.threshold });
 
       const bHits = scanBcrypt(content);
-      for (const h of bHits) hits["bcrypt-cost-low"].push({ file: f.rel, cost: h.cost });
+      for (const h of bHits) hits["bcrypt-cost-low"].push({ file: f.rel, offset: h.offset, line: lineFromOffset(content, h.offset), cost: h.cost });
 
       if (PEM_RE.test(content)) {
         hits["hardcoded-key-material"].push({ file: f.rel });
@@ -460,8 +463,10 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
   // no-ml-kem-implementation, fips-claim-without-runtime-activation,
   // vendored-pqc-no-provenance) describe a whole-repo state rather than a
   // single offending file, so they carry no file-level location. The
-  // call-site scans record the file but not a line, so locations are
-  // file-level (no startLine).
+  // offset-bearing call-site scans (math-random / pbkdf2 / bcrypt) now record
+  // a 1-based `line`, so their locations include a startLine region; the
+  // remaining whole-file scans (weak-hash / weak-cipher / rsa-1024 /
+  // hardcoded-key / tls) stay file-level (no startLine).
   const evidence_locations = {};
   for (const id of Object.keys(hits)) {
     if (signal_overrides[id] === "hit") {

package/lib/collectors/sbom.js

@@ -356,8 +356,15 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
       let withoutIntegrity = 0;
       const walk = (obj) => {
         if (!obj || typeof obj !== "object") return;
-        if (obj.integrity != null) withIntegrity++;
-        else if (obj.resolved != null || obj.version != null) withoutIntegrity++;
+        // Only remote-tarball entries (those with a `resolved` URL) are
+        // expected to carry an `integrity` hash. The npm 7+ root entry
+        // `"": { name, version }` legitimately has no `resolved` and no
+        // `integrity`, so keying off `version` would false-positive on
+        // every clean lockfile. Mirror library-author.js's guard.
+        if (obj.resolved != null) {
+          if (obj.integrity != null) withIntegrity++;
+          else withoutIntegrity++;
+        }
         for (const v of Object.values(obj)) if (v && typeof v === "object") walk(v);
       };
       walk(j.packages || j.dependencies || {});