@blamejs/exceptd-skills 0.14.11 → 0.14.13

package/lib/playbook-runner.js

@@ -691,15 +691,26 @@ function detect(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
         }
       }
     } else {
-      // Without an explicit override, treat any captured artifact as evidence
+      // An override WAS supplied for this indicator but its value didn't
+      // canonicalize to hit/miss/inconclusive (e.g. "maybe", "present", a
+      // number). Pre-fix this was silently dropped — the operator believed
+      // they'd asserted a result but the signal vanished, yielding a false
+      // not_detected. Surface it as a runtime_error (mirrors the
+      // classification_override_invalid signal) so the drop is visible.
+      if (rawOverride !== undefined && runOpts && Array.isArray(runOpts._runErrors)) {
+        pushRunError(runOpts._runErrors, {
+          kind: 'signal_override_unrecognized',
+          indicator_id: ind.id,
+          supplied_value: (typeof rawOverride === 'object') ? JSON.stringify(rawOverride).slice(0, 80) : String(rawOverride).slice(0, 80),
+          message: `signal_overrides["${ind.id}"] value was not recognized (expected hit/miss/inconclusive or a boolean); the signal was ignored.`,
+        }, { dedupeKey: e => e.indicator_id || '' });
+      }
+      // Without a usable override, treat any captured artifact as evidence
       // the indicator could be evaluated. Mark inconclusive if any artifact
       // was captured (engine doesn't pattern-match raw artifact content; the
       // host AI is responsible for that). With NO captured artifacts, this is
       // a clean empty submission — emit 'miss' so the run can reach
       // classification:'not_detected' rather than getting stuck inconclusive.
-      // A clean empty run with no captured artifacts must emit 'miss' so
-      // classification can reach 'not_detected'; otherwise theater_verdict
-      // stays 'pending_agent_run' indefinitely.
       const anyCaptured = Object.values(artifacts).some(a => a && a.captured);
       verdict = anyCaptured ? 'inconclusive' : 'miss';
     }
@@ -765,12 +776,16 @@ function detect(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
   const anyFpDowngrade = indicatorResults.some(r => Array.isArray(r.fp_checks_unsatisfied) && r.fp_checks_unsatisfied.length > 0);
 
   let classification;
+  // Track whether the override was actually honored, so we don't report a
+  // refused override as "applied" (L6).
+  let overrideEffective = !!override;
   if (override) {
     classification = override === 'clean' ? 'not_detected' : override;
     if (anyFpDowngrade) {
       const substituted = 'inconclusive';
       const attempted = override; // record what the operator submitted, not the mapped form
       classification = substituted;
+      overrideEffective = false;
       if (runOpts && Array.isArray(runOpts._runErrors)) {
         pushRunError(runOpts._runErrors, {
           kind: 'classification_override_blocked',
@@ -782,6 +797,24 @@ function detect(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
             .map(r => ({ id: r.id, fp_checks_unsatisfied_count: r.fp_checks_unsatisfied.length })),
         }, { dedupeKey: e => String(e.attempted) });
       }
+    } else if (classification === 'not_detected' && hasDeterministicHit) {
+      // A not_detected/clean override must not silently bury a DETERMINISTIC
+      // hit. A deterministic indicator firing is high-signal evidence; hiding
+      // it as not_detected is a strictly worse false-negative than leaving the
+      // run inconclusive. (Probabilistic hits remain overridable — that's the
+      // legitimate "I confirmed these are benign" workflow.) Substitute
+      // inconclusive and surface why.
+      classification = 'inconclusive';
+      overrideEffective = false;
+      if (runOpts && Array.isArray(runOpts._runErrors)) {
+        pushRunError(runOpts._runErrors, {
+          kind: 'classification_override_masks_deterministic_hit',
+          attempted: override,
+          substituted: 'inconclusive',
+          reason: 'A not_detected/clean classification override was refused because one or more deterministic indicators fired. A deterministic hit cannot be downgraded to not_detected.',
+          deterministic_hit_indicators: hits.filter(r => r.deterministic).map(r => r.id),
+        }, { dedupeKey: e => String(e.attempted) });
+      }
     }
   } else if (hasDeterministicHit || hasHighConfHit) {
     classification = 'detected';
@@ -818,7 +851,11 @@ function detect(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
       from_observation: agentSubmission._signal_origins?.[i.id] || null,
     })),
     indicators_evaluated_count: indicatorResults.length,
-    classification_override_applied: override ? (override === 'clean' ? 'not_detected' : override) : null,
+    // Only report the override as applied when it was actually honored — a
+    // refused override (FP-downgrade or deterministic-hit masking) left
+    // `classification` as inconclusive, so reporting the attempted value here
+    // would contradict the verdict.
+    classification_override_applied: (override && overrideEffective) ? (override === 'clean' ? 'not_detected' : override) : null,
     submission_shape_seen: agentSubmission._original_shape || (agentSubmission.artifacts ? 'nested (v0.10.x)' : 'empty'),
     // Pass through any flat-shape observation collisions detected at
     // normalize time so analyze() can publish them under
@@ -2345,7 +2382,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 +2510,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 +2608,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 +2751,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 +2822,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',
@@ -3356,11 +3414,22 @@ function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
  * through directly. Avoids JSON.stringify's replacer indirection because
  * a top-level array would otherwise miss the canonicalization recursion.
  */
-function canonicalStringify(v) {
+const CANONICAL_MAX_DEPTH = 200;
+function canonicalStringify(v, _depth = 0) {
   if (v === null || typeof v !== 'object') return JSON.stringify(v);
-  if (Array.isArray(v)) return '[' + v.map(canonicalStringify).join(',') + ']';
+  // Bounded recursion: adversarial (or accidental) deeply-nested evidence
+  // would otherwise overflow the stack with an opaque "internal error". This
+  // runs on every run() (evidence_hash + session_id derivation), so the guard
+  // turns a crash into an actionable rejection. 200 levels is far beyond any
+  // legitimate submission.
+  if (_depth > CANONICAL_MAX_DEPTH) {
+    const e = new Error(`evidence nesting exceeds the maximum depth of ${CANONICAL_MAX_DEPTH} — flatten the submission`);
+    e.code = 'EVIDENCE_TOO_DEEP';
+    throw e;
+  }
+  if (Array.isArray(v)) return '[' + v.map(x => canonicalStringify(x, _depth + 1)).join(',') + ']';
   const keys = Object.keys(v).sort();
-  return '{' + keys.map(k => JSON.stringify(k) + ':' + canonicalStringify(v[k])).join(',') + '}';
+  return '{' + keys.map(k => JSON.stringify(k) + ':' + canonicalStringify(v[k], _depth + 1)).join(',') + '}';
 }
 
 /**

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)) {

package/lib/validate-playbooks.js

@@ -16,15 +16,25 @@
  *      phases.direct.skill_chain[].skill — both are resolved)
  *   - phases.govern.skill_preload[]   → manifest.json.skills[]
  *   - domain.atlas_refs[]             → data/atlas-ttps.json keys
+ *   - domain.attack_refs[]            → data/attack-techniques.json keys
  *   - domain.cve_refs[]               → data/cve-catalog.json keys
  *   - domain.cwe_refs[]               → data/cwe-catalog.json keys
  *   - domain.d3fend_refs[]            → data/d3fend-catalog.json keys
  *   - phases.detect.indicators[].attack_ref → data/attack-techniques.json
  *   - phases.detect.indicators[].atlas_ref  → data/atlas-ttps.json
  *   - phases.detect.indicators[].cve_ref    → data/cve-catalog.json
+ *   - phases.detect.false_positive_profile[].indicator_id
+ *                                     → phases.detect.indicators[].id
  *
  * Internal consistency:
  *   - Indicator ids are unique within a playbook.
+ *   - Every playbook maps to at least one TTP via domain.atlas_refs or
+ *     domain.attack_refs (the cross-cutting correlation layer is exempt).
+ *   - When _meta.air_gap_mode is true, network-sourced look.artifacts carry
+ *     a non-empty air_gap_alternative (error if missing).
+ *   - Closed controlled vocabularies (jurisdiction_obligations[].clock_starts,
+ *     domain.frameworks_in_scope[]) are enforced at error severity, unlike the
+ *     evolving-drift enums (artifact/indicator `type`) which stay warnings.
  *   - rwep_threshold ordering: close <= monitor <= escalate, each in 0..100.
  *   - close.notification_actions[].obligation_ref resolves to a synthesized
  *     "<jurisdiction>/<regulation> <window_hours>h" key from
@@ -229,6 +239,29 @@ function loadContext() {
   const d3 = readJson(D3FEND_PATH);
   const attack = readJsonIfExists(ATTACK_PATH);
 
+  // Closed controlled-vocabulary enums sourced from the schema so the
+  // hard-error enum checks in checkCrossRefs stay in lockstep with the
+  // schema's own enum lists. A typo'd clock_starts must hard-fail the
+  // predeploy gate (it changes when a notification clock starts ticking),
+  // so unlike evolving-drift enums (artifact/indicator `type`) these are
+  // promoted to error severity rather than left as generic-validator
+  // warnings.
+  let clockStartsEnum = null;
+  let frameworksEnum = null;
+  try {
+    const schema = readJson(SCHEMA_PATH);
+    clockStartsEnum =
+      schema.properties.phases.properties.govern.properties
+        .jurisdiction_obligations.items.properties.clock_starts.enum || null;
+    frameworksEnum =
+      schema.properties.domain.properties.frameworks_in_scope.items.enum || null;
+  } catch {
+    // If the schema shape changes, fall back to no closed-vocab enforcement
+    // here (the generic validator still emits warnings).
+    clockStartsEnum = null;
+    frameworksEnum = null;
+  }
+
   return {
     skillKeys: new Set(manifest.skills.map((s) => s.name)),
     atlasKeys: new Set(Object.keys(atlas).filter((k) => !k.startsWith('_'))),
@@ -238,6 +271,8 @@ function loadContext() {
     attackKeys: attack
       ? new Set(Object.keys(attack).filter((k) => !k.startsWith('_')))
       : null,
+    clockStartsEnum: clockStartsEnum ? new Set(clockStartsEnum) : null,
+    frameworksEnum: frameworksEnum ? new Set(frameworksEnum) : null,
   };
 }
 
@@ -311,6 +346,15 @@ function checkCrossRefs(playbook, ctx, playbookIds) {
       warn(`domain.atlas_refs: unresolved "${a}" (not in data/atlas-ttps.json)`);
     }
   }
+  // Hard Rule #4 ("no orphaned controls"): domain.attack_refs must resolve to
+  // the ATT&CK technique catalog, mirroring the atlas_refs block above and the
+  // detect.indicators[].attack_ref check below. Without this, every TTP listed
+  // at the domain level bypassed catalog cross-referencing.
+  for (const a of domain.attack_refs || []) {
+    if (ctx.attackKeys && !ctx.attackKeys.has(a)) {
+      warn(`domain.attack_refs: unresolved "${a}" (not in data/attack-techniques.json)`);
+    }
+  }
   for (const c of domain.cve_refs || []) {
     if (!ctx.cveKeys.has(c)) {
       warn(`domain.cve_refs: unresolved "${c}" (not in data/cve-catalog.json)`);
@@ -359,6 +403,19 @@ function checkCrossRefs(playbook, ctx, playbookIds) {
     }
   }
 
+  // false_positive_profile[].indicator_id must reference a real indicator id.
+  // A dangling reference means an FP-distinguishing test is wired to nothing,
+  // so the runner can never apply it. Warning severity (vocabulary-style
+  // drift, not a structural break).
+  for (const [i, fp] of (detect.false_positive_profile || []).entries()) {
+    if (!fp || typeof fp !== 'object') continue;
+    if (fp.indicator_id && !indIds.has(fp.indicator_id)) {
+      warn(
+        `phases.detect.false_positive_profile[${i}].indicator_id: unresolved "${fp.indicator_id}" — no matching phases.detect.indicators[].id`,
+      );
+    }
+  }
+
   // rwep_threshold ordering. Hard error — a misordered threshold actively
   // breaks the scoring path.
   const rwep = direct.rwep_threshold || {};
@@ -397,6 +454,68 @@ function checkCrossRefs(playbook, ctx, playbookIds) {
     }
   }
 
+  // Air-gap completeness. When _meta.air_gap_mode is true the runner refuses
+  // to touch the network, so every artifact whose source is a network call
+  // (https://, http://, gh api, gh release, curl, wget, fetch) MUST carry a
+  // non-empty air_gap_alternative or the run is silently incomplete. The
+  // schema encodes this as an allOf/if/then block, but the inline validator
+  // does not implement conditional keywords, so it is enforced imperatively
+  // here at error severity.
+  if (meta.air_gap_mode === true) {
+    const look = phases.look || {};
+    const netSourceRe = /(https?:\/\/|gh api|gh release|curl |wget |fetch )/;
+    for (const [i, art] of (look.artifacts || []).entries()) {
+      if (!art || typeof art !== 'object') continue;
+      if (typeof art.source === 'string' && netSourceRe.test(art.source)) {
+        const alt = art.air_gap_alternative;
+        if (typeof alt !== 'string' || alt.trim().length === 0) {
+          err(
+            `phases.look.artifacts[${i}]: _meta.air_gap_mode is true and source "${art.source}" makes a network call, but no non-empty air_gap_alternative is set — the artifact cannot be collected offline`,
+          );
+        }
+      }
+    }
+  }
+
+  // TTP-mapping floor (Hard Rule #4): every playbook must map to at least one
+  // adversary technique via domain.atlas_refs OR domain.attack_refs. The sole
+  // exemption is the cross-cutting correlation layer (_meta.scope ===
+  // "cross-cutting"), which has no first-party TTPs — it correlates findings
+  // produced by the other playbooks. Error severity for everything else.
+  const atlasCount = (domain.atlas_refs || []).length;
+  const attackCount = (domain.attack_refs || []).length;
+  if (atlasCount === 0 && attackCount === 0 && meta.scope !== 'cross-cutting') {
+    err(
+      'domain: no TTP mapping — at least one of domain.atlas_refs or domain.attack_refs must be non-empty (cross-cutting correlation playbooks are exempt)',
+    );
+  }
+
+  // Closed controlled-vocabulary enums: a value outside the schema's closed
+  // enum is an error, not a warning, so a typo cannot ship. Unlike the
+  // evolving-drift enums (artifact `type`, indicator `type`) which the generic
+  // validator keeps at warning, these vocabularies are fixed and load-bearing
+  // (clock_starts decides when a notification deadline starts counting;
+  // frameworks_in_scope drives gap-analysis routing).
+  if (ctx.clockStartsEnum) {
+    for (const [i, o] of (govern.jurisdiction_obligations || []).entries()) {
+      if (!o || typeof o !== 'object') continue;
+      if (o.clock_starts !== undefined && !ctx.clockStartsEnum.has(o.clock_starts)) {
+        err(
+          `phases.govern.jurisdiction_obligations[${i}].clock_starts: invalid value ${JSON.stringify(o.clock_starts)} — not in closed vocabulary ${JSON.stringify([...ctx.clockStartsEnum])}`,
+        );
+      }
+    }
+  }
+  if (ctx.frameworksEnum) {
+    for (const [i, f] of (domain.frameworks_in_scope || []).entries()) {
+      if (typeof f === 'string' && !ctx.frameworksEnum.has(f)) {
+        err(
+          `domain.frameworks_in_scope[${i}]: invalid value ${JSON.stringify(f)} — not in closed vocabulary`,
+        );
+      }
+    }
+  }
+
   return findings;
 }