@blamejs/exceptd-skills 0.12.15 → 0.12.18

package/lib/scoring.js

@@ -3,6 +3,40 @@
 /**
  * RWEP — Real-World Exploit Priority scoring engine
  * Supplements CVSS with exploit availability, active exploitation, and operational constraints.
+ *
+ * ----------------------------------------------------------------------------
+ * `rwep_factors` dual-semantics (audit J F2)
+ * ----------------------------------------------------------------------------
+ * Catalog entries (data/cve-catalog.json) store `rwep_factors` as an object
+ * whose values are POST-WEIGHT CONTRIBUTIONS for boolean / ladder factors
+ * but the RAW BLAST RADIUS for `blast_radius`. The two shapes coexist because
+ * each surface has different requirements:
+ *
+ *   cisa_kev:             0 OR +25         (post-weight contribution)
+ *   poc_available:        0 OR +20         (post-weight contribution)
+ *   ai_factor:            0 OR +15         (post-weight contribution)
+ *   active_exploitation:  0 / 10 / 5 / 20  (post-weight contribution from ladder)
+ *   blast_radius:         0..30 RAW        (intentionally NOT post-weight —
+ *                                          mirrors the weight ceiling so it
+ *                                          reads as raw blast magnitude)
+ *   patch_available:      0 OR -15         (post-weight contribution)
+ *   live_patch_available: 0 OR -10         (post-weight contribution)
+ *   reboot_required:      0 OR +5          (post-weight contribution)
+ *
+ * Operator-facing implication: summing `Object.values(rwep_factors)` produces
+ * the stored `rwep_score` for catalog entries because the blast weight is 30
+ * (matches the raw cap). This dual-shape is intentional but easy to misuse;
+ * direct boolean inputs should go through `scoreCustom()` instead.
+ *
+ * scoreCustom() input shape is DIFFERENT — it accepts BOOLEAN factors plus
+ * a numeric blast_radius and a string active_exploitation ladder value.
+ * `deriveRwepFromFactors()` is the shape-detecting bridge: if values look
+ * numeric (post-weighted), it sums; if values look boolean / string-ladder,
+ * it routes through scoreCustom.
+ *
+ * The semantic ambiguity is grandfathered. A clean rename (raw_factors vs
+ * weighted_contributions) is a minor-bump change and is deferred.
+ * ----------------------------------------------------------------------------
  */
 
 const CVE_SCHEMA_REQUIRED = [
@@ -28,6 +62,29 @@ const RWEP_WEIGHTS = {
   reboot_required:       5
 };
 
+// audit J F4: active_exploitation ladder. Aligned with playbook-runner's
+// _activeExploitationLadder so the catalog scorer and the runtime evaluator
+// produce identical results for the same string value. 'unknown' contributes
+// a quarter of the confirmed weight (5 points) — operationally "we have not
+// confirmed, but absence of evidence is not evidence of absence; do not
+// score zero on a fresh CVE that hasn't been triaged yet".
+const ACTIVE_EXPLOITATION_LADDER = {
+  confirmed: 1.0,
+  suspected: 0.5,
+  unknown:   0.25,
+  none:      0,
+};
+
+// The canonical set of factor keys scoreCustom recognises. Used by
+// validateFactors to flag unknown keys (audit J F8).
+const RECOGNISED_FACTOR_KEYS = new Set([
+  'cisa_kev', 'poc_available', 'ai_assisted_weapon', 'ai_discovered',
+  'active_exploitation', 'blast_radius', 'patch_available',
+  'live_patch_available', 'reboot_required',
+  // accepted alias for the catalog field name
+  'patch_required_reboot',
+]);
+
 function score(cveId, catalog) {
   const entry = catalog[cveId];
   if (!entry) throw new Error(`CVE not in catalog: ${cveId}`);
@@ -68,13 +125,29 @@ function validateFactors(factors) {
   } else if (!aeAllowed.includes(factors.active_exploitation)) {
     warnings.push(`active_exploitation: expected one of ${aeAllowed.join(', ')}, got ${JSON.stringify(factors.active_exploitation)}`);
   }
+  // audit J F6: NaN diagnostics. The prior message read "expected number,
+  // got number (null)" because `JSON.stringify(NaN) === 'null'` and `typeof
+  // NaN === 'number'`. Number.isFinite catches NaN + Infinity + -Infinity
+  // and emits a useful message.
   if (factors.blast_radius === undefined || factors.blast_radius === null) {
     warnings.push('blast_radius: missing (treated as 0)');
-  } else if (typeof factors.blast_radius !== 'number' || Number.isNaN(factors.blast_radius)) {
+  } else if (typeof factors.blast_radius !== 'number') {
     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)) {
+    warnings.push(`blast_radius: ${factors.blast_radius > 0 ? 'Infinity' : '-Infinity'} is not a finite numeric value (treated as 0)`);
   } else if (factors.blast_radius < 0 || factors.blast_radius > 30) {
     warnings.push(`blast_radius: ${factors.blast_radius} out of expected range [0, 30] (clamped to weight ceiling, but the value usually indicates a unit-of-measure mistake)`);
   }
+  // audit J F8: surface unknown factor keys so a typo'd answer file
+  // (`patch_avilable`, `cisa-kev`, etc.) doesn't silently default to false
+  // with no diagnostic.
+  for (const k of Object.keys(factors)) {
+    if (!RECOGNISED_FACTOR_KEYS.has(k)) {
+      warnings.push(`unknown factor: ${k} (ignored — not in the recognised key set)`);
+    }
+  }
   return warnings;
 }
 
@@ -113,8 +186,15 @@ function scoreCustom(factors, opts) {
   score += cisa_kev ? RWEP_WEIGHTS.cisa_kev : 0;
   score += poc_available ? RWEP_WEIGHTS.poc_available : 0;
   score += (ai_assisted_weapon || ai_discovered) ? RWEP_WEIGHTS.ai_factor : 0;
-  score += active_exploitation === 'confirmed' ? RWEP_WEIGHTS.active_exploitation : 0;
-  score += active_exploitation === 'suspected' ? Math.floor(RWEP_WEIGHTS.active_exploitation / 2) : 0;
+  // audit J F4 + F16: active_exploitation goes through the ladder rather
+  // than two hand-written branches with `Math.floor(weight/2)`. The floor
+  // was a no-op for even weights (20/2 = 10) but would have silently
+  // truncated to asymmetric results if a future operator bumped the
+  // weight to 21. The ladder + multiplication preserves the contribution
+  // exactly, including the new `unknown → 0.25 × weight = 5` mapping that
+  // aligns the catalog scorer with playbook-runner._activeExploitationLadder.
+  const aeMultiplier = ACTIVE_EXPLOITATION_LADDER[active_exploitation] ?? 0;
+  score += RWEP_WEIGHTS.active_exploitation * aeMultiplier;
   // v0.12.15 (audit J F1, F5): blast_radius numeric coercion must reject
   // NaN, Infinity, and strings explicitly. The prior `typeof === 'number'`
   // check passed NaN (which is `typeof === 'number'`) into `Math.min/max`
@@ -128,15 +208,60 @@ function scoreCustom(factors, opts) {
   score += live_patch_available ? RWEP_WEIGHTS.live_patch_available : 0;
   score += rebootFactor ? RWEP_WEIGHTS.reboot_required : 0;
 
+  // audit J F10: keep the pre-clamp value so collectWarnings consumers can
+  // see deduction magnitude (e.g. a -25 raw score collapsed to 0 hides the
+  // fact that the entry had three mitigating factors).
+  const rawUnclamped = score;
+
   // v0.12.15 (audit J F1): defense-in-depth clamp against any unforeseen
   // NaN production above (negative weight + Infinity + math edge case).
   const clamped = Number.isFinite(score) ? Math.min(100, Math.max(0, score)) : 0;
   if (opts && opts.collectWarnings) {
-    return { score: clamped, _scoring_warnings: validateFactors(factors) };
+    return {
+      score: clamped,
+      _rwep_raw_unclamped: Number.isFinite(rawUnclamped) ? rawUnclamped : null,
+      _scoring_warnings: validateFactors(factors),
+    };
   }
   return clamped;
 }
 
+/**
+ * audit J F3 + audit M P1-C bridge: derive an RWEP score from a
+ * `rwep_factors` object regardless of which shape it uses.
+ *
+ *   - SHAPE A (boolean / string-ladder): values are booleans + an
+ *     active_exploitation string + a numeric blast_radius. Route through
+ *     scoreCustom() — the canonical formula.
+ *   - SHAPE B (catalog post-weight): values are numeric contributions
+ *     (0 / ±N) plus a numeric blast_radius. Sum the numeric values and
+ *     clamp to [0, 100]. This is how catalog `rwep_factors` are stored.
+ *
+ * Heuristic: if every value is a number, treat as Shape B (sum). If any
+ * value is boolean or a recognised ladder string, treat as Shape A
+ * (scoreCustom). This lets the curation apply-path and the auto-discovery
+ * builder share one canonical derivation that handles either operator
+ * input style without duplicating the scoring formula.
+ */
+function deriveRwepFromFactors(factors) {
+  if (!factors || typeof factors !== 'object') return 0;
+  const values = Object.values(factors);
+  if (values.length === 0) return 0;
+  const aeAllowed = new Set(['none', 'unknown', 'suspected', 'confirmed']);
+  const hasBooleanOrLadder = values.some(
+    (v) => typeof v === 'boolean' || (typeof v === 'string' && aeAllowed.has(v)),
+  );
+  if (hasBooleanOrLadder) {
+    return scoreCustom(factors);
+  }
+  // Shape B: catalog post-weight. Sum + clamp.
+  let sum = 0;
+  for (const v of values) {
+    if (typeof v === 'number' && Number.isFinite(v)) sum += v;
+  }
+  return Math.max(0, Math.min(100, sum));
+}
+
 function timeline(rwepScore) {
   if (rwepScore >= 90) return { hours: 4, label: 'Immediate — live patch or isolate within 4 hours' };
   if (rwepScore >= 75) return { hours: 24, label: 'Urgent — patch or compensating controls within 24 hours' };
@@ -146,17 +271,36 @@ function timeline(rwepScore) {
   return { hours: null, label: 'Low — next scheduled maintenance' };
 }
 
-function compare(cveId, catalog) {
+function compare(cveId, catalog, opts) {
   const entry = catalog[cveId];
   if (!entry) throw new Error(`CVE not in catalog: ${cveId}`);
 
-  const rwep = entry.rwep_score;
+  // audit J F11: `--recompute` ignores the stored rwep_score and forces a
+  // fresh computation from rwep_factors. Useful for catching catalog drift
+  // (stored score grew stale relative to current weights) and for auditing
+  // the divergence between stored vs. formula-derived scores.
+  const recompute = !!(opts && opts.recompute);
+  let rwep;
+  if (recompute) {
+    const factors = entry.rwep_factors || {};
+    // The catalog's rwep_factors shape is "post-weight" (Shape B). Route
+    // through the shape-detecting helper so a catalog whose factors were
+    // hand-edited in either shape still produces a usable score.
+    rwep = deriveRwepFromFactors(factors);
+  } else {
+    rwep = entry.rwep_score;
+  }
   const cvss = entry.cvss_score;
   const cvssEquivalent = cvss * 10;
   const delta = rwep - cvssEquivalent;
 
+  // audit J F15: narrow the "broadly aligned" band from ±20 to ±10. The old
+  // ±20 band swallowed the Copy Fail RWEP-vs-CVSS divergence (delta = 12)
+  // where the operator-facing point is precisely that the CVSS-calibrated
+  // SLA is insufficient. ±10 is the tightest classifier that still treats
+  // ordinary CVSS rounding noise as alignment.
   let explanation = '';
-  if (delta > 20) {
+  if (delta > 10) {
     explanation = `RWEP significantly higher than CVSS equivalent. Factors driving delta: `;
     const driving = [];
     if (entry.cisa_kev) driving.push('CISA KEV (+25)');
@@ -166,7 +310,7 @@ function compare(cveId, catalog) {
     if (entry.patch_required_reboot && !entry.live_patch_available) driving.push('reboot required (+5)');
     explanation += driving.join(', ');
     explanation += '. Framework patch SLAs calibrated to CVSS are insufficient for this CVE.';
-  } else if (delta < -20) {
+  } else if (delta < -10) {
     explanation = `RWEP lower than CVSS equivalent. Mitigating factors: `;
     const mitigating = [];
     if (entry.patch_available) mitigating.push('patch available (-15)');
@@ -178,15 +322,20 @@ function compare(cveId, catalog) {
     explanation = 'CVSS and RWEP are broadly aligned for this CVE.';
   }
 
-  return {
+  const out = {
     cve_id: cveId,
     cvss: cvss,
     rwep: rwep,
     cvss_framework_sla: timeline(cvssEquivalent),
     rwep_actual_sla: timeline(rwep),
     delta,
-    explanation
+    explanation,
   };
+  if (recompute) {
+    out.stored_rwep_score = entry.rwep_score;
+    out.recomputed = true;
+  }
+  return out;
 }
 
 function validate(catalog) {
@@ -222,4 +371,15 @@ function validate(catalog) {
   return errors;
 }
 
-module.exports = { score, scoreCustom, timeline, compare, validate, validateFactors, RWEP_WEIGHTS };
+module.exports = {
+  score,
+  scoreCustom,
+  timeline,
+  compare,
+  validate,
+  validateFactors,
+  deriveRwepFromFactors,
+  RWEP_WEIGHTS,
+  ACTIVE_EXPLOITATION_LADDER,
+  RECOGNISED_FACTOR_KEYS,
+};

package/lib/sign.js

@@ -24,6 +24,38 @@
  * validateSkillPath() below). Without this a tampered manifest could
  * sign or verify arbitrary files outside the skills/ tree.
  *
+ * Manifest signing contract (must mirror lib/verify.js):
+ *   After all individual skill signatures are written, sign-all signs
+ *   the manifest itself. The canonical bytes are computed as:
+ *     1. Read the manifest object after all skill signatures land.
+ *     2. Delete the top-level `manifest_signature` field if present
+ *        (idempotency — re-signing after rotation must produce the same
+ *        canonical bytes whether or not a stale signature is there).
+ *     3. Serialize via JSON.stringify(obj, sortedTopLevelKeys, 2). The
+ *        top-level keys are stringified in lexicographic order so a
+ *        re-ordered manifest signs to the same bytes. Nested objects
+ *        keep their natural key order (skills[] entries already follow
+ *        a stable convention).
+ *     4. Apply normalize() (CRLF→LF, BOM strip) — same transform skills
+ *        use, so the manifest signature survives any line-ending churn.
+ *   ANY change to canonicalManifestBytes() or this contract requires
+ *   the matching change in lib/verify.js. A coordinated attacker who
+ *   rewrites manifest.json + manifest-snapshot.json + manifest-snapshot.sha256
+ *   without the private key produces a manifest_signature mismatch that
+ *   lib/verify.js refuses to load.
+ *
+ * Windows ACL contract:
+ *   On win32, `fs.writeFileSync(..., { mode: 0o600 })` only affects
+ *   read-only attributes — it does NOT establish a POSIX-style restrictive
+ *   ACL. Any process running under the same desktop user can read the key
+ *   by default ACL inheritance from the parent. After writing
+ *   .keys/private.pem on Windows, restrictWindowsAcl() shells to icacls
+ *   to strip inherited entries and grant Full Control only to the current
+ *   user. If icacls is unavailable (Server Core, exotic shells), the call
+ *   warns to stderr but does not fail keypair generation — generating the
+ *   key was the load-bearing step; ACL tightening is best-effort hardening
+ *   on top.
+ *
  * Signing ceremony:
  *   1. node lib/sign.js generate-keypair    — generate keypair (one time, per deployment)
  *   2. node lib/sign.js sign-all            — sign all skills (after any content change)
@@ -44,6 +76,7 @@
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
+const { execFileSync } = require('child_process');
 
 const ROOT = path.join(__dirname, '..');
 const MANIFEST_PATH = path.join(ROOT, 'manifest.json');
@@ -79,6 +112,11 @@ function generateKeypair({ rotate = false } = {}) {
   fs.writeFileSync(PRIVATE_KEY_PATH, privateKey, { encoding: 'utf8', mode: 0o600 });
   fs.writeFileSync(PUBLIC_KEY_PATH, publicKey, { encoding: 'utf8', mode: 0o644 });
 
+  // Audit I P1-3: on win32, fs.writeFileSync `mode` does not produce
+  // a POSIX-style restrictive ACL. Tighten via icacls so other desktop
+  // users on the same workstation / CI runner can't read the key.
+  restrictWindowsAcl(PRIVATE_KEY_PATH);
+
   if (rotate) {
     console.log('[sign] Keypair rotated. All existing signatures are now invalid — run: node lib/sign.js sign-all');
   } else {
@@ -128,6 +166,16 @@ function signAll() {
     signed++;
   }
 
+  // Audit I P1-4: sign the manifest itself. Removes any existing
+  // manifest_signature field so the canonical bytes are deterministic
+  // across re-runs, signs with the private key, then writes the result.
+  // A coordinated attacker who rewrites the manifest (and snapshot, and
+  // snapshot SHA) without the private key produces an invalid manifest
+  // signature; lib/verify.js refuses to load the manifest.
+  delete manifest.manifest_signature;
+  const manifestSig = signCanonicalManifest(manifest, privateKey);
+  manifest.manifest_signature = manifestSig;
+
   fs.writeFileSync(MANIFEST_PATH, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
 
   // S5: verdict line FIRST, fingerprint banner after. An operator
@@ -136,7 +184,7 @@ function signAll() {
   if (errors > 0) {
     console.error(`\n[sign] FAILED — ${signed} signed, ${errors} errors.`);
   } else {
-    console.log(`\n[sign] ${signed} skills signed.`);
+    console.log(`\n[sign] ${signed} skills signed. Manifest signed.`);
   }
   printFingerprintBanner();
 
@@ -160,6 +208,11 @@ function signOne(skillName) {
   skill.signed_at = new Date().toISOString();
   delete skill.sha256;
 
+  // P1-4: re-sign the manifest after the per-skill signature changes.
+  // Without this a single-skill sign leaves manifest_signature stale.
+  delete manifest.manifest_signature;
+  manifest.manifest_signature = signCanonicalManifest(manifest, privateKey);
+
   fs.writeFileSync(MANIFEST_PATH, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
   console.log(`[sign] Signed: ${skillName}`);
   printFingerprintBanner();
@@ -244,6 +297,105 @@ function loadManifest() {
   return JSON.parse(fs.readFileSync(MANIFEST_PATH, 'utf8'));
 }
 
+/**
+ * Audit I P1-4 — canonical byte form of the manifest, used for both
+ * signing (lib/sign.js) and verification (lib/verify.js).
+ *
+ * Contract: the same logical manifest content must produce the same bytes
+ * regardless of (a) whether a stale manifest_signature is present, (b)
+ * key order at any depth, (c) line endings or BOM.
+ *
+ *   1. Clone, delete manifest_signature.
+ *   2. Recursively sort object keys at every depth (NOT the top-level
+ *      whitelist trap — see codex P1 PR #12: passing
+ *      `Object.keys(manifest).sort()` as the JSON.stringify replacer-array
+ *      treats it as a property allowlist applied to EVERY object level.
+ *      Nested fields like `skills[].path` and `skills[].signature` got
+ *      silently dropped from the canonical bytes, letting an attacker
+ *      swap them without breaking the signature. Now we deep-canonicalize
+ *      every object).
+ *   3. Apply normalize() — strip leading BOM, convert CRLF → LF.
+ *
+ * @param {object} manifest
+ * @returns {Buffer} canonical UTF-8 bytes
+ */
+function canonicalize(value) {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (value && typeof value === 'object') {
+    const out = {};
+    for (const key of Object.keys(value).sort()) {
+      out[key] = canonicalize(value[key]);
+    }
+    return out;
+  }
+  return value;
+}
+
+function canonicalManifestBytes(manifest) {
+  const clone = { ...manifest };
+  delete clone.manifest_signature;
+  const json = JSON.stringify(canonicalize(clone), null, 2);
+  return Buffer.from(normalize(json), 'utf8');
+}
+
+/**
+ * Sign the canonical manifest bytes with the Ed25519 private key.
+ * Returns the manifest_signature object literal to splice into the
+ * manifest top level.
+ *
+ * @param {object} manifest
+ * @param {string} privateKey PEM-encoded Ed25519 private key
+ * @returns {{algorithm:'Ed25519', signature_base64:string, signed_at:string}}
+ */
+function signCanonicalManifest(manifest, privateKey) {
+  const bytes = canonicalManifestBytes(manifest);
+  const sig = crypto.sign(null, bytes, {
+    key: privateKey,
+    dsaEncoding: 'ieee-p1363',
+  });
+  return {
+    algorithm: 'Ed25519',
+    signature_base64: sig.toString('base64'),
+    signed_at: new Date().toISOString(),
+  };
+}
+
+/**
+ * Audit I P1-3 — tighten Windows ACL on the private key.
+ *
+ * fs.writeFileSync({mode: 0o600}) on win32 only affects read-only
+ * attributes; the file inherits its ACL from the parent. icacls strips
+ * inheritance and grants Full Control only to the current user. Any
+ * failure (icacls missing, exotic shell, environment without USERNAME)
+ * is warned to stderr — generating the key was the load-bearing step,
+ * ACL tightening is best-effort hardening.
+ *
+ * @param {string} targetPath absolute path of the private key file
+ */
+function restrictWindowsAcl(targetPath) {
+  if (process.platform !== 'win32') return;
+  const user = process.env.USERNAME;
+  if (!user) {
+    console.warn('[sign] WARN: USERNAME env var not set — skipping Windows ACL hardening on ' + targetPath);
+    return;
+  }
+  try {
+    execFileSync('icacls', [
+      targetPath,
+      '/inheritance:r',
+      '/grant:r',
+      `${user}:F`,
+    ], { stdio: ['ignore', 'ignore', 'pipe'] });
+  } catch (err) {
+    console.warn(
+      '[sign] WARN: icacls hardening failed on ' + targetPath + ': ' +
+      ((err && err.message) || String(err)) +
+      ' — the key was written but ACL inheritance was not stripped. ' +
+      'Other desktop users on this machine may be able to read it.'
+    );
+  }
+}
+
 function printFingerprintBanner() {
   if (!fs.existsSync(PUBLIC_KEY_PATH)) return;
   try {
@@ -303,4 +455,13 @@ Signing ceremony (first time):
   }
 }
 
-module.exports = { generateKeypair, signAll, signOne, normalize, validateSkillPath };
+module.exports = {
+  generateKeypair,
+  signAll,
+  signOne,
+  normalize,
+  validateSkillPath,
+  canonicalManifestBytes,
+  signCanonicalManifest,
+  restrictWindowsAcl,
+};

package/lib/validate-playbooks.js

@@ -31,6 +31,9 @@
  *     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 in v0.12.16 (and will
+ *     flip to error in v0.13.0) — see checkMutexReciprocity().
  *
  * Finding severity:
  *   - error   — structural problems that block the runner (missing required
@@ -397,6 +400,44 @@ function checkCrossRefs(playbook, ctx, playbookIds) {
   return findings;
 }
 
+/* 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). v0.12.16 keeps this at warning severity per the patch-class
+ * cadence; v0.13.0 will flip it to error via --strict / predeploy
+ * `informational: false`.
+ */
+function checkMutexReciprocity(playbooks) {
+  const findings = [];
+  const mutexMap = new Map();
+  for (const pb of playbooks) {
+    if (!pb.data || !pb.data._meta || !pb.data._meta.id) continue;
+    const id = pb.data._meta.id;
+    const mutex = Array.isArray(pb.data._meta.mutex) ? pb.data._meta.mutex : [];
+    mutexMap.set(id, new Set(mutex));
+  }
+  const byPlaybook = new Map(); // playbookId -> array of warning messages
+  for (const [id, mset] of mutexMap.entries()) {
+    for (const other of mset) {
+      const otherSet = mutexMap.get(other);
+      if (!otherSet) continue; // unresolved-id warning is already emitted by checkCrossRefs
+      if (!otherSet.has(id)) {
+        const msg = `_meta.mutex: asymmetric mutex with "${other}" — "${other}" does not list "${id}" in its _meta.mutex. v0.13.0 will flip this to a hard error.`;
+        if (!byPlaybook.has(id)) byPlaybook.set(id, []);
+        byPlaybook.get(id).push(msg);
+      }
+    }
+  }
+  findings.push(byPlaybook);
+  return byPlaybook;
+}
+
 function main() {
   const opts = parseArgs(process.argv);
   const schema = readJson(SCHEMA_PATH);
@@ -408,6 +449,7 @@ function main() {
       playbookIds.add(pb.data._meta.id);
     }
   }
+  const mutexAsymmetries = checkMutexReciprocity(playbooks);
 
   let errored = 0;
   let warned = 0;
@@ -425,6 +467,9 @@ function main() {
       ...validate(pb.data, schema, 'playbook', label),
       ...checkCrossRefs(pb.data, ctx, playbookIds),
     ];
+    const reciprocityMsgs =
+      (pb.data && pb.data._meta && mutexAsymmetries.get(pb.data._meta.id)) || [];
+    for (const m of reciprocityMsgs) findings.push({ severity: 'warning', message: m });
     const effective = opts.strict
       ? findings.map((f) => ({ ...f, severity: 'error' }))
       : findings;
@@ -459,6 +504,7 @@ function main() {
 module.exports = {
   validate,
   checkCrossRefs,
+  checkMutexReciprocity,
   loadContext,
   loadPlaybooks,
   obligationKey,