@blamejs/exceptd-skills 0.14.11 → 0.14.12

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 0.14.12 — 2026-05-27
+
+Structured-bundle accuracy:
+- CSAF advisories no longer attribute exploitation to the CISA KEV catalog for a CVE that is confirmed-exploited but not actually in KEV — the "(CISA KEV)" parenthetical is now conditional on the CVE's KEV status.
+- An empty-evidence run emits a `csaf_informational_advisory` instead of a `csaf_security_advisory` with an empty `vulnerabilities` array (Profile 4 expects vulnerabilities; the informational profile does not).
+- SARIF `cve_match` results now carry a `locations` entry. Without it, GitHub Code Scanning silently dropped the highest-severity result class.
+- SARIF and OpenVEX render "not assessed" for an unassessed blast radius instead of the literal "null" / "null/5".
+- `ci --format csaf|sarif|openvex` emits a JSON array of the pure documents instead of an exceptd wrapper carrying a top-level `ok` key (which is invalid in all three formats). Each array element is now a conformant document.
+
+External-source command hardening:
+- `validate-rfcs` / `validate-cves` reject an unknown flag before doing any work, instead of silently defaulting to a live-network run that hangs on a typo'd flag.
+- `cve` and `rfc` now return `ok:false` (not `ok:true`) when the citation fails to stand up — the envelope matched the exit code was already 2, but `ok` was inverted.
+- `refresh`, `prefetch`, and the `scan`/`dispatch`/`currency`/`watchlist` verbs reject unknown flags instead of silently ignoring them; the latter four also emit a top-level `ok` in their `--json` output.
+- `framework-gap` and `skill` honor `--json` on their missing-argument paths (structured error, not plain text), and `skill --json` no longer treats `--json` as the skill name.
+
+`doctor`:
+- `doctor --rfcs` counts the whole RFC catalog (including the CSAF/draft/ISO citation families it previously dropped) with a `by_prefix` breakdown, and its freshness fields read the real catalog file instead of a path that never existed.
+- `doctor --fix` re-verifies signatures after generating a key and signing, so a successful bootstrap reports success (exit 0) rather than carrying the pre-fix "signatures failed" state through to a non-zero exit. It also refuses to generate a key when a fingerprint pin is present without the public key (a corrupted checkout) rather than producing an install that can never verify.
+- `doctor --shipped-tarball` runs the tarball round-trip even when combined with another selective flag (it was silently skipped). `doctor --ai-config` reports a warning when its scan hits the file cap, rather than an unqualified clean pass on an incomplete walk.
+
+Playbook validation hardening (enforcement for future drift; the shipped corpus is unaffected):
+- `domain.attack_refs` are cross-referenced against the ATT&CK catalog (they were unchecked).
+- An air-gap playbook with a network-sourced artifact lacking an `air_gap_alternative` is now rejected (the schema's air-gap conditional was never executed by the validator).
+- Empty `detect.indicators` / `look.artifacts` are rejected; every playbook must map to at least one real TTP (cross-cutting analysis playbooks excepted). Dangling `false_positive_profile` indicator references and invalid `clock_starts` / `frameworks_in_scope` values now fail validation instead of passing as warnings.
+
+RWEP factor validation accepts a numeric string consistently with the scorer (the two surfaces previously disagreed).
+
 ## 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.

package/bin/exceptd.js

@@ -6469,7 +6469,11 @@ function cmdDoctor(runner, args, runOpts, pretty) {
   const onlyAiConfig = !!args["ai-config"];
   const onlyCollectors = !!args.collectors;
   const anySelected = onlySigs || onlyCurrency || onlyCves || onlyRfcs || onlyAiConfig || onlyCollectors;
-  const runSigs = !anySelected || onlySigs;
+  // --shipped-tarball lives inside the signatures check, so it must imply it.
+  // Pre-fix, `doctor --shipped-tarball --cves` made runSigs false (a selective
+  // flag was set, but not --signatures), silently skipping the tarball
+  // round-trip while the operator believed it ran.
+  const runSigs = !anySelected || onlySigs || !!args["shipped-tarball"];
   const runCurrency = !anySelected || onlyCurrency;
   const runCves = !anySelected || onlyCves;
   const runRfcs = !anySelected || onlyRfcs;
@@ -6670,23 +6674,34 @@ function cmdDoctor(runner, args, runOpts, pretty) {
         timeout: 30000,
       });
       const text = (res.stdout || "") + (res.stderr || "");
-      const rfcRows = (text.match(/^RFC-\d+/gm) || []).length;
       const driftMatch = text.match(/drift[:\s]+(\d+)/i);
       const ok = res.status === 0;
-      // Audit 3 B.7: surface the RFC catalog file's mtime + age so
-      // operators can answer "is the offline RFC index fresh?" without
-      // running a separate refresh.
+      // Count the catalog directly (same approach the CVE subcheck uses) rather
+      // than scraping `^RFC-\d+` table rows from the validate-rfcs output. The
+      // text scrape dropped every non-RFC family (CSAF / DRAFT / ISO entries),
+      // undercounting the catalog and hiding those citation families. Read the
+      // canonical file and emit a by_prefix breakdown.
+      const rfcCatalogPath = path.join(PKG_ROOT, "data", "rfc-references.json");
+      let rfcTotal = 0;
+      const byPrefix = {};
       let rfcMtime = null;
       let rfcAgeDays = null;
       try {
-        const rfcPath = path.join(PKG_ROOT, "data", "rfc-index.json");
-        const st = fs.statSync(rfcPath);
+        const catalog = JSON.parse(fs.readFileSync(rfcCatalogPath, "utf8"));
+        for (const k of Object.keys(catalog)) {
+          if (k.startsWith("_")) continue;
+          rfcTotal++;
+          const prefix = (k.match(/^[A-Za-z]+/) || ["?"])[0].toUpperCase();
+          byPrefix[prefix] = (byPrefix[prefix] || 0) + 1;
+        }
+        const st = fs.statSync(rfcCatalogPath);
         rfcMtime = st.mtime.toISOString();
         rfcAgeDays = Math.floor((Date.now() - st.mtimeMs) / 86400000);
-      } catch { /* file may not exist on contributor checkouts */ }
+      } catch { /* file may be absent on exotic installs — total stays 0 */ }
       checks.rfcs = {
         ok,
-        total: rfcRows,
+        total: rfcTotal,
+        by_prefix: byPrefix,
         drift: driftMatch ? Number(driftMatch[1]) : 0,
         index_last_modified: rfcMtime,
         index_age_days: rfcAgeDays,
@@ -6968,9 +6983,14 @@ function cmdDoctor(runner, args, runOpts, pretty) {
       }
     }
 
+    // A truncated walk (hit the file/depth cap) means the audit is INCOMPLETE —
+    // a sensitive file beyond the cap would be unseen. Don't report an
+    // unqualified clean pass: downgrade to a warn so automation can branch on
+    // incompleteness even when zero findings surfaced within the cap.
+    const baseSeverity = errorFindings.length > 0 && fixesFailed > 0 ? 'warn' : (errorFindings.length > 0 && !args.fix ? 'warn' : 'info');
     checks.ai_config = {
-      ok: errorFindings.length === 0 || (args.fix && fixesFailed === 0),
-      severity: errorFindings.length > 0 && fixesFailed > 0 ? 'warn' : (errorFindings.length > 0 && !args.fix ? 'warn' : 'info'),
+      ok: (errorFindings.length === 0 || (args.fix && fixesFailed === 0)) && !walkAborted,
+      severity: walkAborted && baseSeverity === 'info' ? 'warn' : baseSeverity,
       scanned_dirs: scannedDirs,
       scanned_files: scannedFiles,
       walk_truncated: walkAborted,
@@ -7089,8 +7109,8 @@ function cmdDoctor(runner, args, runOpts, pretty) {
   // global `npm install -g` reported `failed_checks: ["signing"]` with
   // `warnings_count: 0`, contradicting the [!! warn] text-mode icon.
   const { bucketChecks } = require(path.join(PKG_ROOT, "lib", "doctor-bucketing.js"));
-  const { warnList, errorList } = bucketChecks(checks);
-  const allGreen = errorList.length === 0 && warnList.length === 0;
+  let { warnList, errorList } = bucketChecks(checks);
+  let allGreen = errorList.length === 0 && warnList.length === 0;
   // Audit 3 B.11: surface the local version on the default doctor output
   // so operators answer both "is my install healthy?" AND "which version
   // am I running?" without having to invoke `exceptd version` separately.
@@ -7127,10 +7147,21 @@ function cmdDoctor(runner, args, runOpts, pretty) {
   // `exceptd doctor` (signatures check) reports 0/N passing.
   if (args.fix && checks.signing && !checks.signing.private_key_present) {
     const pubKeyExists = fs.existsSync(path.join(PKG_ROOT, "keys", "public.pem"));
+    const fingerprintPinExists = fs.existsSync(path.join(PKG_ROOT, "keys", "EXPECTED_FINGERPRINT"));
     if (pubKeyExists) {
       out.summary.fix_attempted = "ed25519_keypair_generation_declined";
       out.summary.fix_decline_reason = "keys/public.pem already exists but no matching private key. Generating a fresh keypair would overwrite the public key and orphan every shipped signature. If you intend to establish a new signing identity, run `node $(exceptd path)/lib/sign.js generate-keypair --rotate` followed by sign-all.";
       process.stderr.write("[doctor --fix] refused: keys/public.pem present without matching private key. Pass --rotate via the underlying lib/sign.js if a new identity is intended.\n");
+    } else if (fingerprintPinExists) {
+      // A committed EXPECTED_FINGERPRINT without keys/public.pem signals an
+      // intended committed signing identity on a corrupted/partial checkout.
+      // Generating a fresh keypair here would write a public.pem whose
+      // fingerprint can never match the pin, leaving verify.js permanently
+      // refusing (fingerprint-mismatch) while --fix claimed success. Decline
+      // and tell the operator to restore the real public key.
+      out.summary.fix_attempted = "ed25519_keypair_generation_declined";
+      out.summary.fix_decline_reason = "keys/EXPECTED_FINGERPRINT is present but keys/public.pem is missing — this is a corrupted checkout of a project with a committed signing identity, not a fresh contributor checkout. Generating a keypair would produce a public key whose fingerprint cannot match the pin, so verify would refuse forever. Restore keys/public.pem from version control instead (git checkout -- keys/public.pem).";
+      process.stderr.write("[doctor --fix] refused: keys/EXPECTED_FINGERPRINT present without keys/public.pem. Restore the committed public key (git checkout -- keys/public.pem) rather than generating a new identity.\n");
     } else {
       process.stderr.write("[doctor --fix] generating Ed25519 keypair...\n");
       const r = require("child_process").spawnSync(process.execPath, [path.join(PKG_ROOT, "lib", "sign.js"), "generate-keypair"], {
@@ -7188,6 +7219,37 @@ function cmdDoctor(runner, args, runOpts, pretty) {
     }
   }
 
+  // After a --fix that re-signed skills (keypair generation OR re-sign), the
+  // captured `checks.signatures` is STALE — it was the verify.js result taken
+  // before any key existed. Re-verify now and recompute the buckets, so a
+  // successful --fix reports success (and exits 0) instead of carrying the
+  // pre-fix "signatures FAILED" through to failed_checks + a non-zero exit.
+  if (args.fix
+      && (out.summary.fix_applied === "ed25519_keypair_generated_and_skills_signed"
+          || out.summary.fix_applied === "skills_resigned_against_current_keypair")) {
+    try {
+      const verifyPath = path.join(PKG_ROOT, "lib", "verify.js");
+      const rv = spawnSync(process.execPath, [verifyPath], { encoding: "utf8", cwd: PKG_ROOT, timeout: 30000 });
+      const rvText = (rv.stdout || "") + (rv.stderr || "");
+      const rvMatch = rvText.match(/(\d+)\/(\d+)\s+skills?\s+passed/i);
+      const rvFp = rvText.match(/SHA256:\s*([A-Za-z0-9+/=]+)/);
+      const rvOk = rv.status === 0;
+      checks.signatures = {
+        ok: rvOk,
+        skills_passed: rvMatch ? Number(rvMatch[1]) : null,
+        skills_total: rvMatch ? Number(rvMatch[2]) : null,
+        fingerprint_sha256: rvFp ? rvFp[1] : null,
+        ...(rvOk ? {} : { exit_code: rv.status, raw: rvText.slice(0, 500) }),
+      };
+      out.checks = checks;
+      ({ warnList, errorList } = bucketChecks(checks));
+      allGreen = errorList.length === 0 && warnList.length === 0;
+      out.summary.failed_checks = errorList;
+      out.summary.warning_checks = warnList;
+      out.summary.all_green = allGreen;
+    } catch { /* re-verify best-effort; leave the pre-fix state if it throws */ }
+  }
+
   // Audit 3 B.3: --fix was passed but nothing to fix. Pre-fix this was
   // silently a no-op — operators couldn't distinguish "we tried and were
   // already healthy" from "we tried and failed silently." Now surfaces a
@@ -8543,9 +8605,15 @@ function cmdCi(runner, args, runOpts, pretty) {
     }
     process.stdout.write(lines.join("\n") + "\n");
   } else if (fmt === "csaf" || fmt === "sarif" || fmt === "openvex") {
-    // Aggregate the per-run bundles_by_format if present.
+    // Aggregate the per-run bundles_by_format if present. ci spans N playbooks,
+    // so there is no single conformant CSAF/SARIF/OpenVEX document — emit a JSON
+    // ARRAY of the pure documents. Critically, do NOT wrap them in an exceptd
+    // envelope carrying a top-level `ok` key: that key is invalid in all three
+    // standard formats, so a downstream CSAF/SARIF/OpenVEX consumer pointed at
+    // `ci --format` output got a non-conformant top-level shape. Each array
+    // element is now a verbatim, conformant document.
     const bundles = results.map(r => r.phases?.close?.evidence_package?.bundles_by_format?.[fmt === "csaf" ? "csaf-2.0" : fmt]).filter(Boolean);
-    emit({ verb: "ci", session_id: sessionId, format: fmt, bundles_count: bundles.length, bundles }, pretty);
+    process.stdout.write(JSON.stringify(bundles, null, pretty ? 2 : 0) + "\n");
   } else if (fmt && fmt !== "json") {
     // v0.11.4 (#76): garbage format rejected with structured error, not silent empty stdout.
     // Route through emitError so the body propagates exit codes via the

package/data/_indexes/_meta.json

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

package/lib/cve-cli.js

@@ -45,7 +45,12 @@ const { resolveCve } = require("./citation-resolve.js");
   }
 
   const r = await resolveCve(id, { airGap: flags.has("--air-gap"), noNetwork: flags.has("--no-network") });
-  const body = { ok: true, verb: "cve", ...r };
+  // A citation that won't stand up exits non-zero so a CI/script gate trips.
+  // Derive `ok` from the same set of statuses that drive the exit code — a
+  // non-zero exit must carry ok:false, never the inverted ok:true the
+  // envelope previously hardcoded.
+  const fails = r.status === "rejected" || r.status === "fabricated" || r.status === "nonexistent" || r.status === "withdrawn";
+  const body = { verb: "cve", ...r, ok: !fails };
 
   if (json) {
     process.stdout.write(JSON.stringify(body, null, pretty ? 2 : 0) + "\n");
@@ -61,8 +66,7 @@ const { resolveCve } = require("./citation-resolve.js");
     if (r.reason) line += `\n  ${r.reason}`;
     process.stdout.write(line + "\n");
   }
-  // A citation that won't stand up is a non-zero exit so a CI/script gate trips.
-  if (r.status === "rejected" || r.status === "fabricated" || r.status === "nonexistent" || r.status === "withdrawn") {
+  if (fails) {
     process.exitCode = 2;
   }
 })();

package/lib/playbook-runner.js

@@ -2345,7 +2345,7 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
       }] : [];
       const base = {
         scores,
-        threats: c.active_exploitation === 'confirmed' ? [{ category: 'exploit_status', details: 'Active exploitation confirmed (CISA KEV).' }] : [],
+        threats: c.active_exploitation === 'confirmed' ? [{ category: 'exploit_status', details: `Active exploitation confirmed${c.cisa_kev ? ' (CISA KEV)' : ''}.` }] : [],
         remediations,
         product_status: isFixed ? { fixed: [productId] } : { known_affected: [productId] }
       };
@@ -2473,9 +2473,18 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
       ? { tlp: { label: CSAF_TLP_LABEL[runOpts.tlp] }, text: `TLP:${runOpts.tlp}` }
       : null;
 
+    // CSAF 2.0: an advisory with zero vulnerabilities is a csaf_informational_advisory
+    // (Profile 5, which does not require /vulnerabilities) rather than a
+    // csaf_security_advisory (Profile 4, where an empty vulnerabilities array is
+    // semantically wrong and warns under strict profile validators). A clean run
+    // becomes an informational attestation; any firing CVE/indicator keeps the
+    // security-advisory category.
+    const csafCategory = (cveVulns.length + indicatorVulns.length) > 0
+      ? 'csaf_security_advisory'
+      : 'csaf_informational_advisory';
     return {
       document: {
-        category: 'csaf_security_advisory',
+        category: csafCategory,
         csaf_version: '2.0',
         publisher: publisherBlock,
         title: `exceptd finding: ${playbook.domain.name} (${analyze.matched_cves.length} CVE(s), ${indicatorHits.length} indicator hit(s), ${(analyze.framework_gap_mapping || []).length} framework gap(s))`,
@@ -2562,20 +2571,29 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
     // every rule definition is unambiguously attributable to one playbook,
     // and cross-playbook merges retain all results.
     const rulePrefix = `${playbookSlug}/`;
-    const cveResults = analyze.matched_cves.map(c => ({
-      ruleId: `${rulePrefix}${c.cve_id}`,
-      level: c.rwep >= 90 ? 'error' : c.rwep >= 70 ? 'warning' : 'note',
-      message: { text: `${c.cve_id}: RWEP ${c.rwep}, blast_radius ${analyze.blast_radius_score}. ${validate.selected_remediation?.description || ''}` },
-      properties: stripNulls({
-        kind: 'cve_match',
-        rwep: c.rwep,
-        cisa_kev: c.cisa_kev,
-        cisa_kev_due_date: c.cisa_kev_due_date ?? null,
-        active_exploitation: c.active_exploitation ?? null,
-        ai_discovered: c.ai_discovered ?? null,
-        blast_radius_score: analyze.blast_radius_score,
-      }),
-    }));
+    // CVE-match results get the coarse playbook-source location fallback
+    // (passing a null indicator skips the per-indicator evidence-locations
+    // branch). Without any `locations`, GitHub Code Scanning silently DROPS
+    // these results — the highest-severity result class would never surface.
+    const cveFallbackLocs = sarifLocationsForIndicator(playbook, null);
+    const cveResults = analyze.matched_cves.map(c => {
+      const result = {
+        ruleId: `${rulePrefix}${c.cve_id}`,
+        level: c.rwep >= 90 ? 'error' : c.rwep >= 70 ? 'warning' : 'note',
+        message: { text: `${c.cve_id}: RWEP ${c.rwep}, blast_radius ${analyze.blast_radius_score == null ? 'not assessed' : analyze.blast_radius_score}. ${validate.selected_remediation?.description || ''}` },
+        properties: stripNulls({
+          kind: 'cve_match',
+          rwep: c.rwep,
+          cisa_kev: c.cisa_kev,
+          cisa_kev_due_date: c.cisa_kev_due_date ?? null,
+          active_exploitation: c.active_exploitation ?? null,
+          ai_discovered: c.ai_discovered ?? null,
+          blast_radius_score: analyze.blast_radius_score,
+        }),
+      };
+      if (cveFallbackLocs) result.locations = cveFallbackLocs;
+      return result;
+    });
     const indicatorHits = (analyze._detect_indicators || []).filter(i => i.verdict === 'hit');
     const indicatorResults = indicatorHits.map(i => {
       const locs = sarifLocationsForIndicator(playbook, i);
@@ -2696,7 +2714,7 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
         vulnerability: { '@id': vulnIdToUrn(c.cve_id), name: c.cve_id },
         products: [productEntry],
         timestamp: issued,
-        impact_statement: `RWEP ${c.rwep}. Blast radius ${analyze.blast_radius_score}/5.`,
+        impact_statement: `RWEP ${c.rwep}. ${analyze.blast_radius_score == null ? 'Blast radius not assessed.' : `Blast radius ${analyze.blast_radius_score}/5.`}`,
       };
       if (c.vex_status === 'fixed') {
         stmt.status = 'fixed';
@@ -2767,11 +2785,14 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
       vexAuthor = vexOperatorClean;
     } else {
       vexAuthor = 'urn:exceptd:operator:unknown';
+      // Same shape + singleton dedupe as the CSAF path so a multi-format emit
+      // produces one canonical bundle_publisher_unclaimed entry that machine
+      // consumers can read consistently (reason/remediation, not message).
       pushRunError(runOpts._runErrors, {
         kind: 'bundle_publisher_unclaimed',
-        format: 'openvex',
-        message: 'OpenVEX author falls back to urn:exceptd:operator:unknown — supply runOpts.operator or runOpts.publisherNamespace to claim disposition attribution.',
-      });
+        reason: 'OpenVEX author fell back to urn:exceptd:operator:unknown because no --publisher-namespace and no URL-shaped --operator were supplied. Disposition attribution is unclaimed on this VEX document.',
+        remediation: 'Re-run with --publisher-namespace <https-url> (or a URL-shaped --operator).'
+      }, { dedupeKey: () => 'singleton' });
     }
     return {
       '@context': 'https://openvex.dev/ns/v0.2.0',

package/lib/prefetch.js

@@ -121,6 +121,12 @@ function parseArgs(argv) {
     else if (a.startsWith("--max-age=")) out.maxAgeMs = parseDuration(a.slice("--max-age=".length));
     else if (a === "--cache-dir") out.cacheDir = path.resolve(argv[++i]);
     else if (a.startsWith("--cache-dir=")) out.cacheDir = path.resolve(a.slice("--cache-dir=".length));
+    // Any remaining --flag is an unrecognized typo. Record it; main() refuses
+    // before any network work rather than silently dropping it.
+    else if (typeof a === "string" && a.startsWith("--")) {
+      const base = a.indexOf("=") === -1 ? a : a.slice(0, a.indexOf("="));
+      (out._unknownFlags || (out._unknownFlags = [])).push(base);
+    }
   }
   // The global air-gap switch implies a report-only / no-egress run: treat
   // EXCEPTD_AIR_GAP=1 the same as --no-network so prefetch never plans live
@@ -650,12 +656,36 @@ function readCached(cacheDir, source, id, opts = {}) {
   }
 }
 
+// Known --flag base names prefetch accepts. Drives the unknown-flag error
+// message's known list.
+const PREFETCH_KNOWN_FLAGS = Object.freeze([
+  "--force", "--no-network", "--dry-run", "--air-gap", "--quiet", "--help", "-h",
+  "--source", "--max-age", "--cache-dir",
+]);
+
 async function main() {
   const opts = parseArgs(process.argv);
   if (opts.help) {
     printHelp();
     return;
   }
+
+  // Reject unknown flags BEFORE any network work. A swallowed typo (e.g.
+  // `--max-aeg 12h`) previously fell through to a default full-cache fetch.
+  // Exit 2 matches prefetch's existing usage-error convention (invalid
+  // --source / --max-age also surface as exit 2 via main()'s catch).
+  if (Array.isArray(opts._unknownFlags) && opts._unknownFlags.length > 0) {
+    const uniq = [...new Set(opts._unknownFlags)];
+    process.stderr.write(JSON.stringify({
+      ok: false,
+      verb: "prefetch",
+      error: `prefetch: unknown flag(s): ${uniq.join(", ")}`,
+      unknown_flags: uniq,
+      known_flags: PREFETCH_KNOWN_FLAGS,
+    }) + "\n");
+    process.exitCode = 2;
+    return;
+  }
   // Why process.exitCode and not process.exit():
   // On Windows + Node 25 (libuv), calling process.exit() synchronously
   // while in-flight fetch / AbortController teardown is still mid-close

package/lib/refresh-external.js

@@ -109,6 +109,22 @@ function parseArgs(argv) {
     // older than 7d or one that was prefetched without a signing keypair.
     // EXCEPTD_FORCE_STALE=1 mirrors for non-interactive automation.
     else if (a === "--force-stale") out.forceStale = true;
+    // Aliases that bin/exceptd.js may pass through or translate; accept them
+    // here so the unknown-flag guard below doesn't false-reject a legitimate
+    // operator invocation. (--no-network / --indexes-only / --network /
+    // --curate / --prefetch are normally rewritten upstream, but tolerate
+    // them when refresh-external is invoked directly.)
+    else if (
+      a === "--no-network" || a === "--prefetch" || a === "--indexes-only" ||
+      a === "--network" || a === "--curate" || a === "--force-stale-acked"
+    ) { /* accepted, no-op at this layer */ }
+    // Any remaining --flag is an unrecognized typo. Record it; refuse after
+    // the loop rather than silently dropping it into a default full-refresh
+    // (which previously hit the live network on every source).
+    else if (typeof a === "string" && a.startsWith("--")) {
+      const base = a.indexOf("=") === -1 ? a : a.slice(0, a.indexOf("="));
+      (out._unknownFlags || (out._unknownFlags = [])).push(base);
+    }
   }
   if (process.env.EXCEPTD_FORCE_STALE === "1") out.forceStale = true;
   // Report-only is intrinsic to the advisory poll regardless of flag order —
@@ -1423,6 +1439,15 @@ async function seedSingleAdvisory(opts) {
   process.exitCode = 3;
 }
 
+// Known --flag base names refresh accepts (operator-facing surface + the
+// bin-translated aliases). Drives the unknown-flag error message's known list.
+const REFRESH_KNOWN_FLAGS = Object.freeze([
+  "--apply", "--quiet", "--swarm", "--json", "--help", "-h", "--advisory",
+  "--check-advisories", "--catalog", "--from-cache", "--source", "--from-fixture",
+  "--report-out", "--air-gap", "--force-stale", "--force-stale-acked",
+  "--no-network", "--prefetch", "--indexes-only", "--network", "--curate",
+]);
+
 async function main() {
   const opts = parseArgs(process.argv);
   if (opts.help) {
@@ -1432,6 +1457,22 @@ async function main() {
     return;
   }
 
+  // Reject unknown flags BEFORE any network / catalog work. A swallowed typo
+  // (e.g. `--aply`) previously fell through to a default all-sources live
+  // refresh. Exit 2 matches refresh's own scheme (2 = error / unknown source).
+  if (Array.isArray(opts._unknownFlags) && opts._unknownFlags.length > 0) {
+    const uniq = [...new Set(opts._unknownFlags)];
+    process.stderr.write(JSON.stringify({
+      ok: false,
+      verb: "refresh",
+      error: `refresh: unknown flag(s): ${uniq.join(", ")}`,
+      unknown_flags: uniq,
+      known_flags: REFRESH_KNOWN_FLAGS,
+    }) + "\n");
+    process.exitCode = 2;
+    return;
+  }
+
   // v0.12.0: `--advisory <id>` short-circuits the normal source loop and
   // seeds a single CVE catalog entry from GHSA. Exits non-zero ("draft
   // written, please review") so CI pipelines surface the needed editorial

package/lib/rfc-cli.js

@@ -57,7 +57,12 @@ const { resolveRfc } = require("./citation-resolve.js");
     const a = norm(claimedTitle), b = norm(r.title);
     titleMatch = a.length > 0 && (b.includes(a) || a.includes(b));
   }
-  const body = { ok: true, verb: "rfc", ...r, ...(claimedTitle ? { claimed_title: claimedTitle, title_match: titleMatch } : {}) };
+  // Derive `ok` from the resolved status + title-check the same way the exit
+  // code is derived below — a non-zero exit (status nonexistent OR an explicit
+  // title mismatch) must carry ok:false, not the inverted ok:true the envelope
+  // previously hardcoded.
+  const fails = r.status === "nonexistent" || titleMatch === false;
+  const body = { verb: "rfc", ...r, ...(claimedTitle ? { claimed_title: claimedTitle, title_match: titleMatch } : {}), ok: !fails };
 
   if (json) {
     process.stdout.write(JSON.stringify(body, null, pretty ? 2 : 0) + "\n");
@@ -77,5 +82,5 @@ const { resolveRfc } = require("./citation-resolve.js");
     process.stdout.write(line + "\n");
   }
   // A mismatched or nonexistent citation is a non-zero exit for gates.
-  if (r.status === "nonexistent" || titleMatch === false) process.exitCode = 2;
+  if (fails) process.exitCode = 2;
 })();

package/lib/schemas/playbook.schema.json

@@ -151,7 +151,7 @@
         "attack_refs": { "type": "array", "items": { "type": "string", "pattern": "^T\\d{4}(\\.\\d{3})?$" } },
         "cve_refs": { "type": "array", "items": { "type": "string", "pattern": "^CVE-\\d{4}-\\d{4,}$" }, "description": "All CVEs must exist in data/cve-catalog.json." },
         "cwe_refs": { "type": "array", "items": { "type": "string", "pattern": "^CWE-\\d+$" } },
-        "d3fend_refs": { "type": "array", "items": { "type": "string" } },
+        "d3fend_refs": { "type": "array", "items": { "type": "string", "pattern": "^D3-[A-Z]+$" } },
         "frameworks_in_scope": {
           "type": "array",
           "items": {
@@ -300,6 +300,7 @@
           "properties": {
             "artifacts": {
               "type": "array",
+              "minItems": 1,
               "items": {
                 "type": "object",
                 "required": ["id", "type", "source", "description", "required"],
@@ -364,6 +365,7 @@
           "properties": {
             "indicators": {
               "type": "array",
+              "minItems": 1,
               "items": {
                 "type": "object",
                 "required": ["id", "type", "value", "confidence", "deterministic"],

package/lib/scoring.js

@@ -132,7 +132,14 @@ function validateFactors(factors) {
   if (factors.blast_radius === undefined || factors.blast_radius === null) {
     warnings.push('blast_radius: missing (treated as 0)');
   } else if (typeof factors.blast_radius !== 'number') {
-    warnings.push(`blast_radius: expected number, got ${typeof factors.blast_radius} (${JSON.stringify(factors.blast_radius)})`);
+    // scoreCustom coerces a numeric string (e.g. "30") via Number(); keep the
+    // two surfaces consistent — accept a finite numeric string with a soft note
+    // rather than rejecting what the scorer will happily use.
+    if (typeof factors.blast_radius === 'string' && Number.isFinite(Number(factors.blast_radius)) && factors.blast_radius.trim() !== '') {
+      warnings.push(`blast_radius: numeric string "${factors.blast_radius}" accepted (coerced to ${Number(factors.blast_radius)}); prefer a JSON number`);
+    } else {
+      warnings.push(`blast_radius: expected number, got ${typeof factors.blast_radius} (${JSON.stringify(factors.blast_radius)})`);
+    }
   } else if (Number.isNaN(factors.blast_radius)) {
     warnings.push('blast_radius: NaN is not a valid numeric value (treated as 0)');
   } else if (!Number.isFinite(factors.blast_radius)) {