@blamejs/exceptd-skills 0.19.32 → 0.19.34

package/lib/validate-playbooks.js

@@ -1,76 +1,10 @@
 #!/usr/bin/env node
 /*
- * lib/validate-playbooks.js — exceptd playbook validator.
- *
- * Walks every JSON file in data/playbooks/, validates it against
- * lib/schemas/playbook.schema.json (using the same inline JSON-Schema
- * subset validator as lib/validate-cve-catalog.js), and additionally
- * resolves every cross-playbook + cross-catalog reference the playbook
- * shape carries.
- *
- * Cross-references checked:
- *   - _meta.feeds_into[].playbook_id  → other playbook files
- *   - _meta.mutex[]                   → other playbook files
- *   - _meta.skill_chain[]             → manifest.json.skills[]
- *     (legacy alias; the canonical chain lives under
- *      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
- *   - directives[].applies_to.cve     → data/cve-catalog.json keys
- *   - directives[].applies_to.atlas_ttp → data/atlas-ttps.json keys
- *   - directives[].applies_to.attack_technique → data/attack-techniques.json
- *   - directives[].phase_overrides.govern.jurisdiction_obligations[].clock_starts
- *                                     → closed clock_starts vocabulary
- *   - directives[].phase_overrides.direct.rwep_threshold → ordering + range
- *   - directives[].phase_overrides.close.notification_actions[].obligation_ref
- *                                     → effective jurisdiction_obligations
- *
- * 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
- *     govern.jurisdiction_obligations[] (the schema does not give
- *     jurisdiction_obligations an explicit `id` field; the shipped playbooks
- *     reference them by this composite string).
- *   - _meta.mutex is symmetric across the whole playbook set: if A lists B,
- *     B must list A. Asymmetry surfaces as a warning by default (promoted to
- *     an error under --strict) — see checkMutexReciprocity().
- *
- * Finding severity:
- *   - error   — structural problems that block the runner (missing required
- *               field, JSON parse error, internal ordering violation,
- *               duplicate indicator id).
- *   - warning — schema-shape drift the runner can still tolerate (enum
- *               vocabulary lag, cross-catalog refs introduced after the
- *               playbook last shipped). Surfaced to the operator without
- *               failing the gate by default; promoted to hard errors under
- *               --strict (predeploy `informational: false`).
- *
- * Exit code: 0 if no errors (warnings allowed), 1 if any errors, 2 on
- *            argv error.
- *
- * Usage:
- *   node lib/validate-playbooks.js          validate every playbook
- *   node lib/validate-playbooks.js --quiet  only print FAIL playbooks + summary
- *   node lib/validate-playbooks.js --strict treat warnings as errors (used by
- *                                           the predeploy gate).
+ * lib/validate-playbooks.js — validates every data/playbooks/*.json against
+ * lib/schemas/playbook.schema.json and resolves the cross-references it carries.
+ * Findings are `error` (blocks the runner) or `warning` (tolerated drift);
+ * --strict promotes every warning to an error. Exits 0 clean, 1 on any error,
+ * 2 on an argv error.
  */
 
 'use strict';
@@ -79,33 +13,15 @@ const fs = require('node:fs');
 const path = require('node:path');
 const process = require('node:process');
 const { safeExit } = require('./exit-codes');
-// _evalCondition is the SAME parser the runner uses at analyze/validate/close
-// time. Exercising every escalation / feeds_into / remediation-precondition
-// condition through the real evaluator lets the validator reject a condition the
-// engine cannot parse (condition_unparsed) — a prose / bare-token /
-// unimplemented-syntax condition that would silently return false for every
-// input and disable the escalation it gates. No cycle: playbook-runner does not
-// require this validator. Loaded defensively: the engine carries a dependency
-// closure (scoring / cross-ref-api / id-validation) that a stripped test mirror
-// staging only the validator + schema does not copy, so a hard top-level require
-// would crash the validator there. In the real repo and the shipped tarball the
-// engine is always present, so the parse-gate always runs; when it is genuinely
-// unresolvable the gate surfaces a WARNING (never a silent error-skip — see
-// checkCrossRefs) so the degradation is observable rather than a false pass.
+// The SAME parser the runner uses, so a condition the engine cannot parse is
+// rejected here instead of silently returning false for every input. Required
+// defensively: a stripped test mirror stages this validator without the engine.
 let _evalCondition = null;
 try { ({ _evalCondition } = require('./playbook-runner')); } catch { /* warned at the gate */ }
 
-// Decompose a condition into its leaf atoms the SAME way evalCondition does —
-// strip wrapping parens, split on top-level OR (lowest precedence), then on
-// top-level AND, quote- and depth-aware. This exists because evalCondition
-// evaluates AND via `.every` / OR via `.some`, which SHORT-CIRCUIT: a dead
-// (unparseable) sub-clause behind a leading clause that resolves false (AND) or
-// true (OR) in the empty validation context is never reached, so running the
-// whole condition once never surfaces its condition_unparsed. Atomizing and
-// parse-checking each leaf independently catches a dead sub-clause regardless of
-// short-circuit (e.g. `blast_radius_score >= 3 AND any deterministic indicator
-// fires` — the first clause is false with no signals, so the dead prose second
-// clause never parsed). Mirrors evalCondition's splitAtTopLevel / stripOuterParens.
+// Decompose a condition into leaf atoms the way evalCondition does. Checking each
+// leaf independently catches a dead sub-clause: evalCondition short-circuits AND
+// via `.every` and OR via `.some`, so a later clause never reports unparsed.
 function _splitTopLevel(expr, sep) {
   const parts = []; const needle = ' ' + sep + ' ';
   let depth = 0, buf = '', i = 0, quote = null;
@@ -193,13 +109,9 @@ function typeOf(value) {
   return typeof value;
 }
 
-// Strict ISO calendar-date check for format:date fields. The shape regex alone
-// accepts impossible dates — `new Date('2026-02-30T00:00:00Z')` does NOT throw,
-// it silently rolls over to March 2 and reports a valid getTime() — so a
-// malformed _meta.last_threat_review or changelog `date` (2026-02-30,
-// 2026-13-40) would pass with only the YYYY-MM-DD shape test. Require the
-// parsed Y-M-D to round-trip back to the input components, mirroring
-// parseIsoDateStrict in lib/validate-catalog-meta.js.
+// Strict ISO calendar check: the shape regex alone accepts impossible dates —
+// `new Date('2026-02-30T00:00:00Z')` rolls over to March 2 — so the parsed Y-M-D
+// must round-trip. Mirrors parseIsoDateStrict in lib/validate-catalog-meta.js.
 function isStrictIsoDate(value) {
   if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(value)) return false;
   const d = new Date(value + 'T00:00:00Z');
@@ -219,12 +131,10 @@ function typeMatches(value, expected) {
   return actual === expected;
 }
 
-/* Inline JSON-Schema subset validator. Returns a flat list of finding objects
- * shaped as { severity, message }. Severity defaults to 'error'; enum
- * mismatches and unknown additional properties under
- * additionalProperties:false are downgraded to 'warning' so vocabulary drift
- * between the schema and shipped playbooks does not hard-fail by default.
- * Promoted to errors under --strict / predeploy informational:false. */
+/* Inline JSON-Schema subset validator. Returns a flat list of
+ * { severity, message }: 'error' except enum mismatches and unknown properties
+ * under additionalProperties:false, which are 'warning' so vocabulary drift does
+ * not hard-fail outside --strict. */
 function validate(value, schema, schemaName, pathStr) {
   const findings = [];
   const here = pathStr || schemaName;
@@ -239,8 +149,6 @@ function validate(value, schema, schemaName, pathStr) {
 
   if (schema.enum !== undefined) {
     if (!schema.enum.includes(value)) {
-      // Enum drift is downgraded to a warning so vocabulary-evolution does
-      // not break patch-class releases.
       err(
         `${here}: value ${JSON.stringify(value)} not in enum ${JSON.stringify(schema.enum)}`,
         'warning',
@@ -315,8 +223,6 @@ function validate(value, schema, schemaName, pathStr) {
       } else if (addlSchema) {
         findings.push(...validate(v, addlSchema, schemaName, `${here}.${k}`));
       } else if (!allowAdditional) {
-        // Drift between schema and shipped data: surface as warning, not
-        // an error. Promoted to an error under --strict.
         err(`${here}: unexpected property "${k}"`, 'warning');
       }
     }
@@ -331,19 +237,11 @@ function loadContext() {
   const cve = readJson(CVE_PATH);
   const cwe = readJson(CWE_PATH);
   const d3 = readJson(D3FEND_PATH);
-  // Required, like the other ref catalogs (cwe / d3fend). It is committed and
-  // always present; loading it optionally let attack_ref validation skip
-  // silently when it was absent — the asymmetry that allowed an unresolvable
-  // attack_ref to ship. Its absence must fail loud.
+  // Required, not optional: an optional load skips attack_ref validation silently.
   const attack = readJson(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.
+  // Sourced from the schema so the hard-error checks in checkCrossRefs stay in
+  // lockstep with its enum lists.
   let clockStartsEnum = null;
   let frameworksEnum = null;
   try {
@@ -354,13 +252,10 @@ function loadContext() {
     frameworksEnum =
       schema.properties.domain.properties.frameworks_in_scope.items.enum || null;
   } catch (e) {
-    // The playbook schema is a committed, required file. Swallowing a read error
-    // here silently disabled the clock_starts / frameworks_in_scope closed-vocab
-    // checks, so a typo in those fields could ship. Fail loud instead.
     throw new Error(`validate-playbooks: cannot read playbook schema ${SCHEMA_PATH} — ${e && e.message}. The closed-vocabulary checks must not silently disable.`);
   }
-  // A successful parse with the wrong shape (enum path moved/renamed) would also
-  // leave the enums null and disable the checks. Treat that as fatal too.
+  // A wrong-shape parse leaves the enums null and disables the checks, so it is
+  // fatal too.
   if (!Array.isArray(clockStartsEnum) || !Array.isArray(frameworksEnum)) {
     throw new Error(`validate-playbooks: playbook schema ${SCHEMA_PATH} did not yield the clock_starts / frameworks_in_scope enums (shape changed). Refusing to validate with the closed-vocab checks silently disabled — fix the schema path expressions in loadContext().`);
   }
@@ -397,21 +292,14 @@ function loadPlaybooks() {
 }
 
 function obligationKey(o) {
-  // The schema does not define an explicit `id` field on
-  // jurisdiction_obligations entries; the shipped playbooks reference them
-  // by the composite "<jurisdiction>/<regulation> <window_hours>h" string.
+  // Obligations carry no `id`; playbooks reference one by this composite string.
   return `${o.jurisdiction}/${o.regulation} ${o.window_hours}h`;
 }
 
 function checkCrossRefs(playbook, ctx, playbookIds) {
   const findings = [];
-  // A null/array/primitive playbook has no cross-refs to check, and validate()
-  // already emits the top-level `expected type "object", got null` error for
-  // it (main() line ~755). Guarding here turns the uncaught `playbook._meta`
-  // TypeError on a literal-null playbook file into a clean no-op so main()
-  // still reports the FAIL and continues to the remaining playbooks instead of
-  // aborting the whole gate. The FAIL is preserved — it originates in
-  // validate(), not here.
+  // validate() already emits the type error; returning empty keeps main()
+  // reporting the FAIL instead of dying on `playbook._meta`.
   if (!playbook || typeof playbook !== 'object' || Array.isArray(playbook)) {
     return findings;
   }
@@ -431,9 +319,7 @@ function checkCrossRefs(playbook, ctx, playbookIds) {
       warn(`_meta.mutex: unresolved playbook_id "${m}"`);
     }
   }
-  // Some playbooks may carry a legacy _meta.skill_chain[] (string list); the
-  // canonical chain lives at phases.direct.skill_chain[].skill but we still
-  // resolve a flat list if present, per the task brief.
+  // _meta.skill_chain[] aliases the canonical phases.direct.skill_chain[].skill.
   for (const s of meta.skill_chain || []) {
     if (typeof s === 'string' && !ctx.skillKeys.has(s)) {
       warn(`_meta.skill_chain: unresolved skill "${s}"`);
@@ -459,10 +345,7 @@ 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.
+  // Hard Rule #4: domain-level TTPs resolve against the ATT&CK catalog.
   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)`);
@@ -484,7 +367,6 @@ function checkCrossRefs(playbook, ctx, playbookIds) {
     }
   }
 
-  // Indicators: id uniqueness, attack_ref / atlas_ref / cve_ref resolution.
   const detect = phases.detect || {};
   const indIds = new Set();
   const indicators = detect.indicators || [];
@@ -516,10 +398,7 @@ 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).
+  // A dangling indicator_id wires an FP test to nothing the runner can apply.
   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)) {
@@ -529,12 +408,8 @@ function checkCrossRefs(playbook, ctx, playbookIds) {
     }
   }
 
-  // validate.remediation_paths[].for_signals[] must reference real indicator
-  // ids. A dangling ref silently never matches, so selected_remediation falls
-  // back to priority-1 without surfacing the intended finding-specific link —
-  // exactly the kind of "looks wired, does nothing" drift this gate exists to
-  // catch. Warning severity (promoted to a hard error under --strict, matching
-  // the false_positive_profile precedent above).
+  // A dangling for_signals never matches: selected_remediation falls back to
+  // priority 1 without the finding-specific link.
   const validatePhase = phases.validate || {};
   for (const [i, rp] of (validatePhase.remediation_paths || []).entries()) {
     if (!rp || typeof rp !== 'object' || !Array.isArray(rp.for_signals)) continue;
@@ -547,18 +422,11 @@ function checkCrossRefs(playbook, ctx, playbookIds) {
     }
   }
 
-  // rwep_threshold ordering. Hard error — a misordered threshold actively
-  // breaks the scoring path. Factored into a helper so the same check runs
-  // against the playbook-level direct phase AND any directive-level
-  // phase_overrides.direct copy the runner deep-merges at run time.
+  // Helpers, so the same checks run against a directive's phase_overrides copy.
   checkRwepThreshold(direct.rwep_threshold, 'phases.direct.rwep_threshold');
 
-  // clock_starts closed-vocab against the base govern phase. Factored into a
-  // helper for the same reason — an override-supplied jurisdiction_obligations
-  // copy must pass the same closed-vocabulary gate.
   checkClockStarts(govern.jurisdiction_obligations, 'phases.govern.jurisdiction_obligations');
 
-  // notification_actions obligation_ref resolution.
   const obligationKeys = new Set(
     (govern.jurisdiction_obligations || []).map(obligationKey),
   );
@@ -572,15 +440,9 @@ function checkCrossRefs(playbook, ctx, playbookIds) {
     }
   }
 
-  // Escalation / feeds_into condition path-root resolvability. The
-  // analyze-phase escalation context resolves the flat keys (rwep,
-  // blast_radius_score, theater_verdict, agent signals) plus the `analyze`
-  // and `finding` roots; close()'s feeds_into context additionally resolves
-  // `validate` and `theater_score`. A dotted path rooted at any OTHER phase
-  // name can never resolve at evaluation time — the condition would
-  // silently never fire — so it is rejected here. Bare (un-dotted)
-  // identifiers are agent-signal names, an open vocabulary, and are not
-  // checked.
+  // The escalation context resolves the flat keys plus `analyze` and `finding`;
+  // feeds_into also resolves `validate`. A dotted path rooted at any other phase
+  // name never resolves. Bare identifiers are agent-signal names, not checked.
   const conditionPathRoots = (cond) => {
     if (typeof cond !== 'string') return [];
     const stripped = cond.replace(/'[^']*'|"[^"]*"|\/[^/\n]*\//g, ' ');
@@ -614,31 +476,12 @@ function checkCrossRefs(playbook, ctx, playbookIds) {
     }
   }
 
-  // Condition PARSEABILITY gate. The path-root check above only catches a
-  // dotted path rooted at an unavailable phase; the broader and far more common
-  // dead-condition shape is a condition the evaluator cannot parse AT ALL —
-  // free-text prose ("A single compromised identity can rewrite the trail"), a
-  // bare-truthiness token without `== true`, an unimplemented keyword
-  // (`<tok> fired`, `not in`, `is`), or an apostrophe-bearing token that fails
-  // the LHS pattern. Every such condition falls through evalCondition to a
-  // silent `false` for every input, so the raise_severity / trigger_playbook /
-  // remediation-precondition it gates never fires — and nothing flagged it,
-  // because the validator never ran the actual evaluator. Run each condition in
-  // the THREE locations the runner threads through evalCondition (analyze
-  // escalation_criteria, _meta.feeds_into, validate remediation_paths
-  // preconditions) and hard-fail on condition_unparsed. Scoped to exactly those
-  // three: scoring_rubric entries are descriptive blast-level prose (never
-  // evaluated — the score comes from agentSignals.blast_radius_score) and
-  // regression_trigger conditions are consumed by computeRegressionNextRun's own
-  // cadence/event parser, so neither is in scope here. Gate ONLY on
-  // condition_unparsed — a genuine PARSE failure is input-independent;
-  // condition_path_unresolved / condition_type_mismatch are runtime data
-  // diagnostics that would false-positive against this empty validation context
-  // (a dotted path legitimately resolves null when no run has populated it).
+  // Parseability gate over the three places the runner threads a condition through
+  // evalCondition: analyze escalation_criteria, _meta.feeds_into, and validate
+  // remediation_paths preconditions. Only condition_unparsed gates: a parse failure
+  // is input-independent, where condition_path_unresolved and
+  // condition_type_mismatch are runtime diagnostics that false-positive here.
   if (!_evalCondition) {
-    // Engine module not resolvable from this validator location (a stripped
-    // test mirror). Surface it as a WARNING so the skip is observable — in the
-    // real repo + shipped tarball the engine always loads and this never fires.
     warn(
       'escalation/feeds_into/precondition parse-gate skipped: lib/playbook-runner.js (the condition evaluator) was not resolvable from this validator location, so condition parseability was not checked',
     );
@@ -646,9 +489,6 @@ function checkCrossRefs(playbook, ctx, playbookIds) {
   const conditionParses = (cond) => {
     if (typeof cond !== 'string' || !cond.trim()) return true;
     if (!_evalCondition) return true; // engine unavailable — warned above, never a silent error-skip
-    // Check EACH atomic leaf, not the whole condition once: evalCondition's
-    // AND/OR short-circuit hides a dead sub-clause behind a leading clause that
-    // resolves false (AND) / true (OR) in the empty validation context.
     for (const atom of atomizeCondition(cond)) {
       const runErrors = [];
       try { _evalCondition(atom, { _runErrors: runErrors }, { _runErrors: runErrors }); }
@@ -682,26 +522,15 @@ 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.
+  // Under _meta.air_gap_mode the runner refuses the network, so a network-sourced
+  // artifact needs a non-empty air_gap_alternative. The schema states this as an
+  // allOf/if/then block the inline validator does not implement.
   if (meta.air_gap_mode === true) {
     const look = phases.look || {};
-    // Case-insensitive + word-bounded so `HTTPS://`, `Curl`, and `fetch(` (no
-    // trailing space) still flag a network source — otherwise an artifact could
-    // ship under air_gap_mode with no offline alternative and run incomplete.
-    // Network-source detection includes API-verb-phrased sources ("GET
-    // /directoryRoles via Graph", "Entra ID", "Okta", "Microsoft Graph") so a
-    // REST/Graph endpoint described in prose still flags under air_gap_mode and
-    // is not silently collected offline-incomplete. `api/v\d` is deliberately
-    // NOT a token — it false-positives on local code-scan artifacts that merely
-    // reference an API path. NOTE: lib/schemas/playbook.schema.json carries the
-    // same narrow `source` pattern and must be broadened in lockstep with this
-    // regex (main-thread item — that file is not edited here).
+    // `api/v\d` is deliberately not a token — it false-positives on local
+    // code-scan artifacts that merely reference an API path. The same `source`
+    // pattern lives in lib/schemas/playbook.schema.json and must be broadened
+    // in lockstep with this one.
     const netSourceRe = /(https?:\/\/|\bgh (?:api|release)\b|\bcurl\b|\bwget\b|\bfetch\b|\b(?:GET|POST|PUT|PATCH|DELETE)\s+\/|\bGraph\b|\b(?:Okta|Entra ID|Microsoft Graph)\b)/i;
     for (const [i, art] of (look.artifacts || []).entries()) {
       if (!art || typeof art !== 'object') continue;
@@ -716,11 +545,8 @@ function checkCrossRefs(playbook, ctx, playbookIds) {
     }
   }
 
-  // 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.
+  // TTP-mapping floor (Hard Rule #4): every playbook maps to at least one
+  // technique. The cross-cutting correlation layer has no first-party TTPs.
   const atlasCount = (domain.atlas_refs || []).length;
   const attackCount = (domain.attack_refs || []).length;
   if (atlasCount === 0 && attackCount === 0 && meta.scope !== 'cross-cutting') {
@@ -729,9 +555,8 @@ function checkCrossRefs(playbook, ctx, playbookIds) {
     );
   }
 
-  // frameworks_in_scope closed vocabulary. A value outside the schema's closed
-  // enum is an error, not a warning, so a typo cannot ship — frameworks_in_scope
-  // drives gap-analysis routing.
+  // frameworks_in_scope drives gap-analysis routing, so a value outside the
+  // schema's closed enum errors rather than warns.
   if (ctx.frameworksEnum) {
     for (const [i, f] of (domain.frameworks_in_scope || []).entries()) {
       if (typeof f === 'string' && !ctx.frameworksEnum.has(f)) {
@@ -742,19 +567,12 @@ function checkCrossRefs(playbook, ctx, playbookIds) {
     }
   }
 
-  // Directive-level coverage. A directive's applies_to fields and its
-  // phase_overrides both reach the runner live (the runner selects directives
-  // by id, deep-merges phase_overrides into the base phase, and surfaces
-  // applies_to in the discovery API) but neither was cross-referenced or
-  // re-validated — so a stale CVE/TTP reference or a tampered override
-  // (bogus clock_starts, out-of-range rwep_threshold) shipped past this gate
-  // even though the identical content is a hard error at playbook level.
+  // Directives reach the runner live — phase_overrides deep-merged into the base
+  // phase — so they face the same cross-reference and override checks.
   for (const [i, d] of (playbook.directives || []).entries()) {
     if (!d || typeof d !== 'object') continue;
     const label = d.id ? `directives[${i}] (${d.id})` : `directives[${i}]`;
 
-    // applies_to.{cve,atlas_ttp,attack_technique} resolution, mirroring the
-    // domain-ref checks at warning severity (promoted to error under --strict).
     const at = d.applies_to;
     if (at && typeof at === 'object') {
       if (at.cve && !ctx.cveKeys.has(at.cve)) {
@@ -763,17 +581,13 @@ function checkCrossRefs(playbook, ctx, playbookIds) {
       if (at.atlas_ttp && !ctx.atlasKeys.has(at.atlas_ttp)) {
         warn(`${label}.applies_to.atlas_ttp: unresolved "${at.atlas_ttp}" (not in data/atlas-ttps.json)`);
       }
-      // Guard the attack catalog the same way domain.attack_refs does:
-      // attack-techniques.json is loaded via readJsonIfExists and may be null.
       if (at.attack_technique && ctx.attackKeys && !ctx.attackKeys.has(at.attack_technique)) {
         warn(`${label}.applies_to.attack_technique: unresolved "${at.attack_technique}" (not in data/attack-techniques.json)`);
       }
     }
 
-    // phase_overrides re-validation. The runner merges these into the base
-    // phase before govern()/close() consume them, so an override-supplied
-    // clock_starts or rwep_threshold must pass the same gates as the base
-    // phase or the regulatory clock / scoring path breaks at run time.
+    // The runner merges these into the base phase, so an override-supplied
+    // clock_starts or rwep_threshold must clear the same gates.
     const ov = d.phase_overrides;
     if (ov && typeof ov === 'object') {
       if (ov.govern && typeof ov.govern === 'object') {
@@ -788,10 +602,8 @@ function checkCrossRefs(playbook, ctx, playbookIds) {
           `${label}.phase_overrides.direct.rwep_threshold`,
         );
       }
-      // An override-supplied notification obligation_ref must resolve against
-      // the EFFECTIVE obligation set the runner sees after the merge: the
-      // base govern obligations, plus any the override adds. Warning severity,
-      // matching the base-phase obligation_ref precedent.
+      // Resolved against the effective set the runner sees after the merge: the
+      // override's own obligations when it supplies them, else the base phase's.
       if (ov.close && typeof ov.close === 'object' && Array.isArray(ov.close.notification_actions)) {
         const overrideObligations =
           (ov.govern && Array.isArray(ov.govern.jurisdiction_obligations))
@@ -812,29 +624,21 @@ function checkCrossRefs(playbook, ctx, playbookIds) {
 
   return findings;
 
-  // ---- local helpers (hoisted; close over `findings`/`ctx`/`err`) ----
+  // Hoisted for the calls above; they close over `findings`, `ctx` and `err`.
 
-  // rwep_threshold ordering + range. close <= monitor <= escalate, each in
-  // 0..100. Error severity — a misordered or out-of-range threshold actively
-  // breaks the scoring path. `pathPrefix` keeps the message accurate whether
-  // the source is the base phase or a directive override.
+  // close <= monitor <= escalate, each in 0..100. `pathPrefix` keeps the message
+  // accurate for both the base phase and a directive override.
   function checkRwepThreshold(rwepObj, pathPrefix) {
     const rwep = rwepObj || {};
-    // Range check is PER-KEY and independent of the others. A directive's
-    // phase_overrides.direct.rwep_threshold is a partial fragment the runner
-    // deep-merges, so it may carry only one of the three keys — gating the
-    // whole check on all-three-present let an out-of-range single-key override
-    // (e.g. {escalate: 150} or {close: -5}) ship unchecked and reach the
-    // runner. Validate each present numeric key on its own.
+    // Per-key and independent: an override is a partial fragment, so gating the
+    // range check on all three keys present lets `{escalate: 150}` through.
     for (const k of ['close', 'monitor', 'escalate']) {
       const v = rwep[k];
       if (typeof v === 'number' && (v < 0 || v > 100)) {
         err(`${pathPrefix}.${k}: ${v} outside 0..100`);
       }
     }
-    // Ordering is only meaningful when the full triple is present (a partial
-    // override inherits the missing edges from the base phase, so close <=
-    // monitor <= escalate can't be evaluated on the fragment alone).
+    // Ordering needs the full triple: a partial override inherits its missing edges.
     if (
       typeof rwep.close === 'number' &&
       typeof rwep.monitor === 'number' &&
@@ -848,9 +652,8 @@ function checkCrossRefs(playbook, ctx, playbookIds) {
     }
   }
 
-  // clock_starts closed-vocabulary check over a jurisdiction_obligations list.
-  // Error severity — clock_starts decides when a notification deadline starts
-  // counting; an out-of-vocabulary value silently never starts the clock.
+  // clock_starts decides when a notification deadline begins counting; an
+  // out-of-vocabulary value never starts the clock.
   function checkClockStarts(obligations, pathPrefix) {
     if (!ctx.clockStartsEnum || !Array.isArray(obligations)) return;
     for (const [i, o] of obligations.entries()) {
@@ -864,19 +667,10 @@ function checkCrossRefs(playbook, ctx, playbookIds) {
   }
 }
 
-/* Cross-playbook mutex-reciprocity check.
- *
- * `_meta.mutex` is a symmetric relation: if playbook A lists B, B must list A.
- * Asymmetry is a latent runner bug — the engine's mutex enforcement only
- * blocks concurrent execution from whichever side declared the conflict, so
- * an asymmetric declaration silently degrades to a race condition when the
- * undeclared side is started first.
- *
- * Emits one warning per asymmetric pair (keyed off the side that declares
- * the edge). Kept at warning severity by default per the patch-class
- * cadence; promoted to an error under --strict / predeploy
- * `informational: false`.
- */
+/* `_meta.mutex` is symmetric: if playbook A lists B, B must list A. The engine
+ * blocks concurrency only from the side that declared the conflict, so an
+ * asymmetric declaration degrades to a race. Returns one warning per asymmetric
+ * pair, keyed by the declaring playbook. */
 function checkMutexReciprocity(playbooks) {
   const mutexMap = new Map();
   for (const pb of playbooks) {