@blamejs/exceptd-skills 0.12.13 → 0.12.16

package/lib/validate-catalog-meta.js

@@ -52,15 +52,17 @@ const PLACEHOLDER_TOKENS = [
 ];
 
 function parseArgs(argv) {
-  const opts = { quiet: false };
+  const opts = { quiet: false, strict: false };
   for (let i = 2; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--quiet' || a === '-q') opts.quiet = true;
+    else if (a === '--strict') opts.strict = true;
     else if (a === '--help' || a === '-h') {
       console.log(
-        'Usage: node lib/validate-catalog-meta.js [--quiet]\n' +
+        'Usage: node lib/validate-catalog-meta.js [--quiet] [--strict]\n' +
           '\n' +
-          '  --quiet   Suppress per-catalog PASS output; show failures only.\n',
+          '  --quiet   Suppress per-catalog PASS output; show failures only.\n' +
+          '  --strict  Promote v0.13.0-preview warnings (freshness) to errors.\n',
       );
       process.exit(0);
     } else {
@@ -80,8 +82,9 @@ function containsPlaceholder(s) {
   return PLACEHOLDER_TOKENS.some((re) => re.test(s));
 }
 
-function validateMeta(catalogPath) {
+function validateMeta(catalogPath, opts) {
   const errors = [];
+  const warnings = [];
   const data = readJson(catalogPath);
   const meta = data._meta;
 
@@ -159,8 +162,46 @@ function validateMeta(catalogPath) {
         );
       }
     }
+
+    /* Audit G F3 — freshness enforcement. When both meta.last_updated and
+     * freshness_policy.stale_after_days are present, surface a warning if
+     * (now - last_updated) > stale_after_days. Patch-class release emits at
+     * WARN level (does not fail validation); v0.13.0 will flip to an error.
+     *
+     * Optional `opts.strict` (or `opts.errorOnStale`) promotes the warning
+     * to an error today; predeploy keeps the warning posture.
+     */
+    if (
+      typeof meta.last_updated === 'string' &&
+      typeof fp.stale_after_days === 'number' &&
+      fp.stale_after_days > 0
+    ) {
+      const lu = new Date(meta.last_updated + (
+        /^\d{4}-\d{2}-\d{2}$/.test(meta.last_updated) ? 'T00:00:00Z' : ''
+      ));
+      if (!Number.isNaN(lu.getTime())) {
+        const ageDays = Math.floor((Date.now() - lu.getTime()) / 86400000);
+        if (ageDays > fp.stale_after_days) {
+          const msg =
+            `_meta freshness: last_updated ${meta.last_updated} is ${ageDays} days old ` +
+            `(stale_after_days = ${fp.stale_after_days}); refresh the catalog or bump _meta.last_updated. ` +
+            `Will hard-fail in v0.13.0.`;
+          if (opts && (opts.strict || opts.errorOnStale)) {
+            errors.push(msg);
+          } else {
+            warnings.push(msg);
+          }
+        }
+      }
+    }
   }
 
+  // Warnings are appended after errors when callers ask for the combined
+  // shape via opts.includeWarnings. Default return is errors only so the
+  // public function signature is unchanged for existing callers.
+  if (opts && opts.includeWarnings) {
+    return { errors, warnings };
+  }
   return errors;
 }
 
@@ -172,23 +213,37 @@ function main() {
     .sort();
 
   let failed = 0;
+  let warned = 0;
   for (const f of files) {
-    const errors = validateMeta(path.join(DATA_DIR, f));
-    if (errors.length === 0) {
+    const result = validateMeta(path.join(DATA_DIR, f), {
+      includeWarnings: true,
+      strict: opts.strict,
+    });
+    const errors = result.errors;
+    const warnings = result.warnings || [];
+    if (errors.length === 0 && warnings.length === 0) {
       if (!opts.quiet) console.log(`PASS  ${f}`);
+    } else if (errors.length === 0) {
+      warned++;
+      if (!opts.quiet) console.log(`WARN  ${f}`);
+      for (const w of warnings) console.log(`        - [warn] ${w}`);
     } else {
       failed++;
       console.log(`FAIL  ${f}`);
       for (const e of errors) console.log(`        - ${e}`);
+      for (const w of warnings) console.log(`        - [warn] ${w}`);
     }
   }
 
   const total = files.length;
-  const passed = total - failed;
+  const passed = total - failed - warned;
+  const warnSuffix = warned ? `, ${warned} with warnings` : '';
+  const failSuffix = failed ? `, ${failed} failed` : '';
   console.log(
-    `\n${passed}/${total} catalogs validated${failed ? `, ${failed} failed` : ''}.`,
+    `\n${passed}/${total} catalogs validated${warnSuffix}${failSuffix}.`,
   );
-  process.exit(failed === 0 ? 0 : 1);
+  // F18: process.exitCode + return so buffered writes drain.
+  process.exitCode = failed === 0 ? 0 : 1;
 }
 
 if (require.main === module) {

package/lib/validate-cve-catalog.js

@@ -33,6 +33,9 @@ const CATALOG_PATH = path.join(REPO_ROOT, 'data', 'cve-catalog.json');
 const LESSONS_PATH = path.join(REPO_ROOT, 'data', 'zeroday-lessons.json');
 const ATLAS_PATH = path.join(REPO_ROOT, 'data', 'atlas-ttps.json');
 const CWE_PATH = path.join(REPO_ROOT, 'data', 'cwe-catalog.json');
+const ATTACK_PATH = path.join(REPO_ROOT, 'data', 'attack-techniques.json');
+const D3FEND_PATH = path.join(REPO_ROOT, 'data', 'd3fend-catalog.json');
+const FRAMEWORK_GAPS_PATH = path.join(REPO_ROOT, 'data', 'framework-control-gaps.json');
 
 // v0.12.12 — patterns that mark a verification_sources URL as a public exploit
 // or PoC location. When poc_available: true AND a verification source matches
@@ -67,15 +70,17 @@ const DATE_FIELDS = [
 ];
 
 function parseArgs(argv) {
-  const opts = { quiet: false };
+  const opts = { quiet: false, strict: false };
   for (let i = 2; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--quiet' || a === '-q') opts.quiet = true;
+    else if (a === '--strict') opts.strict = true;
     else if (a === '--help' || a === '-h') {
       console.log(
-        'Usage: node lib/validate-cve-catalog.js [--quiet]\n' +
+        'Usage: node lib/validate-cve-catalog.js [--quiet] [--strict]\n' +
           '\n' +
-          '  --quiet   Suppress per-CVE PASS output; show failures only.\n',
+          '  --quiet   Suppress per-CVE PASS output; show failures only.\n' +
+          '  --strict  Promote v0.13.0-preview warnings to errors. Off by default.\n',
       );
       process.exit(0);
     } else {
@@ -239,19 +244,31 @@ function additionalChecks(key, entry, ctx) {
   }
 
   // V2 — Cross-catalog reference resolution. Unresolved refs are warnings
-  // for v0.12.12; v0.13.0 will flip to hard failures.
-  for (const ref of entry.atlas_refs || []) {
-    if (!ctx.atlasKeys.has(ref)) {
-      warnings.push(
-        `${key}: atlas_refs entry "${ref}" not in data/atlas-ttps.json (will hard-fail in v0.13.0)`,
-      );
-    }
-  }
-  for (const ref of entry.cwe_refs || []) {
-    if (!ctx.cweKeys.has(ref)) {
-      warnings.push(
-        `${key}: cwe_refs entry "${ref}" not in data/cwe-catalog.json (will hard-fail in v0.13.0)`,
-      );
+  // for v0.12.x; v0.13.0 will flip to hard failures. Audit D's V2 expansion
+  // (Audit G) extends the walk from cwe_refs only to attack_refs, atlas_refs,
+  // d3fend_refs, AND framework_control_gaps.
+  const REF_FIELDS = [
+    { field: 'atlas_refs', set: ctx.atlasKeys, file: 'data/atlas-ttps.json' },
+    { field: 'cwe_refs', set: ctx.cweKeys, file: 'data/cwe-catalog.json' },
+    { field: 'attack_refs', set: ctx.attackKeys, file: 'data/attack-techniques.json' },
+    { field: 'd3fend_refs', set: ctx.d3fendKeys, file: 'data/d3fend-catalog.json' },
+    {
+      field: 'framework_control_gaps',
+      set: ctx.frameworkKeys,
+      file: 'data/framework-control-gaps.json',
+    },
+  ];
+  for (const { field, set, file } of REF_FIELDS) {
+    if (!set) continue; // catalog absent — skip silently (defense-in-depth)
+    const refs = entry[field];
+    if (!Array.isArray(refs)) continue;
+    for (const ref of refs) {
+      if (typeof ref !== 'string') continue;
+      if (!set.has(ref)) {
+        warnings.push(
+          `${key}: ${field} entry "${ref}" not in ${file} (will hard-fail in v0.13.0)`,
+        );
+      }
     }
   }
 
@@ -285,10 +302,24 @@ function main() {
   const lessons = readJson(LESSONS_PATH);
   const atlas = fs.existsSync(ATLAS_PATH) ? readJson(ATLAS_PATH) : {};
   const cwe = fs.existsSync(CWE_PATH) ? readJson(CWE_PATH) : {};
+  const attack = fs.existsSync(ATTACK_PATH) ? readJson(ATTACK_PATH) : null;
+  const d3fend = fs.existsSync(D3FEND_PATH) ? readJson(D3FEND_PATH) : null;
+  const frameworks = fs.existsSync(FRAMEWORK_GAPS_PATH)
+    ? readJson(FRAMEWORK_GAPS_PATH)
+    : null;
 
   const ctx = {
     atlasKeys: new Set(Object.keys(atlas).filter((k) => !k.startsWith('_'))),
     cweKeys: new Set(Object.keys(cwe).filter((k) => !k.startsWith('_'))),
+    attackKeys: attack
+      ? new Set(Object.keys(attack).filter((k) => !k.startsWith('_')))
+      : null,
+    d3fendKeys: d3fend
+      ? new Set(Object.keys(d3fend).filter((k) => !k.startsWith('_')))
+      : null,
+    frameworkKeys: frameworks
+      ? new Set(Object.keys(frameworks).filter((k) => !k.startsWith('_')))
+      : null,
   };
 
   const cveKeys = Object.keys(catalog).filter((k) => !k.startsWith('_'));
@@ -325,12 +356,18 @@ function main() {
     // `exceptd run cve-curation --advisory <id>`.
     const isDraft = entry && (entry._auto_imported === true || entry._draft === true);
     const errors = validate(entry, schema, 'cve', key);
-    const warnings = additionalChecks(key, entry, ctx);
+    let warnings = additionalChecks(key, entry, ctx);
     if (!lessonKeys.has(key) && !isDraft) {
       errors.push(
         `${key}: missing matching entry in data/zeroday-lessons.json (rule #6: zero-day learning is live)`,
       );
     }
+    // F20 — --strict promotes per-CVE warnings to errors. Drafts are
+    // exempt (drafts already exit non-fail).
+    if (opts.strict && !isDraft) {
+      errors.push(...warnings);
+      warnings = [];
+    }
     if (isDraft) {
       drafts++;
       if (!opts.quiet) {
@@ -381,7 +418,8 @@ function main() {
     (warned ? `, ${warned} with warnings` : '') +
     (failed ? `, ${failed} failed` : '') + '.';
   console.log(summary);
-  process.exit(failed === 0 ? 0 : 1);
+  // F18: process.exitCode + return so buffered output drains.
+  process.exitCode = failed === 0 ? 0 : 1;
 }
 
 module.exports = {

package/lib/validate-indexes.js

@@ -12,6 +12,8 @@
  *   3. Fail if any hash diverges (the indexes are stale).
  *   4. Fail if a new source file exists that's not in the index (the
  *      index doesn't reflect current state).
+ *   5. Fail if source_hashes is empty (build-indexes never ran).
+ *   6. Fail if any data/*.json or listed source is a symlink.
  *
  * Exit 0 on success, 1 on staleness.
  *
@@ -34,50 +36,99 @@ function sha256(buf) {
   return crypto.createHash("sha256").update(buf).digest("hex");
 }
 
-if (!fs.existsSync(META)) {
-  console.error("[validate-indexes] data/_indexes/_meta.json missing — run `npm run build-indexes`.");
-  process.exit(1);
-}
+function main() {
+  if (!fs.existsSync(META)) {
+    console.error("[validate-indexes] data/_indexes/_meta.json missing — run `npm run build-indexes`.");
+    // v0.11.13 pattern: exitCode + return so async stdout/stderr writes drain.
+    process.exitCode = 1;
+    return;
+  }
 
-const meta = JSON.parse(fs.readFileSync(META, "utf8"));
-const recorded = meta.source_hashes || {};
+  const meta = JSON.parse(fs.readFileSync(META, "utf8"));
+  const recorded = meta.source_hashes || {};
 
-// Discover the current canonical source set.
-const manifest = JSON.parse(fs.readFileSync(ABS("manifest.json"), "utf8"));
-const liveSources = new Set();
-liveSources.add("manifest.json");
-for (const f of fs.readdirSync(ABS("data"))) {
-  if (f.endsWith(".json")) liveSources.add("data/" + f);
-}
-for (const s of manifest.skills) liveSources.add(s.path);
+  // Audit G F1 — reject an empty source_hashes table outright. The previous
+  // gate would silently pass when source_hashes was {} (or missing entirely)
+  // because the for-loop body never executed; the resulting "0 sources" pass
+  // banner falsely advertised the indexes as current. An empty source-hash
+  // table means build-indexes was never run, or was run against an empty
+  // repo, and the index files themselves are not trustworthy.
+  if (Object.keys(recorded).length === 0) {
+    console.error(
+      "[validate-indexes] data/_indexes/_meta.json source_hashes is empty — " +
+      "this means build-indexes did not populate the index. " +
+      "Regenerate with: npm run build-indexes"
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  // Discover the current canonical source set.
+  const manifest = JSON.parse(fs.readFileSync(ABS("manifest.json"), "utf8"));
+  const liveSources = new Set();
+  liveSources.add("manifest.json");
+  // Audit G F16 — use lstat to detect symlinks. A symlinked .json under data/
+  // would be hashed via the followed target, allowing a malicious checkout
+  // (or a misconfigured filesystem) to swap data origin without tripping the
+  // gate. Reject symlinks outright.
+  for (const f of fs.readdirSync(ABS("data"))) {
+    if (!f.endsWith(".json")) continue;
+    const abs = ABS("data/" + f);
+    const st = fs.lstatSync(abs);
+    if (st.isSymbolicLink()) {
+      console.error(
+        `[validate-indexes] data/${f} is a symbolic link — refusing to follow. ` +
+        `Replace with the real file or remove the entry.`
+      );
+      process.exitCode = 1;
+      return;
+    }
+    liveSources.add("data/" + f);
+  }
+  for (const s of manifest.skills) liveSources.add(s.path);
 
-const drift = [];
-const missing = [];
-const recordedKeys = new Set(Object.keys(recorded));
+  const drift = [];
+  const missing = [];
+  const recordedKeys = new Set(Object.keys(recorded));
 
-for (const p of liveSources) {
-  if (!recordedKeys.has(p)) {
-    missing.push(`new source not in index: ${p}`);
-    continue;
+  for (const p of liveSources) {
+    if (!recordedKeys.has(p)) {
+      missing.push(`new source not in index: ${p}`);
+      continue;
+    }
+    const abs = ABS(p);
+    // F16 — also check listed-but-symlinked sources. lstatSync on a missing
+    // file throws; mirror the existsSync semantics by guarding it.
+    if (fs.existsSync(abs)) {
+      const st = fs.lstatSync(abs);
+      if (st.isSymbolicLink()) {
+        missing.push(`source ${p} is a symbolic link — refusing to follow`);
+        continue;
+      }
+    }
+    const live = sha256(fs.readFileSync(abs));
+    if (live !== recorded[p]) {
+      drift.push(`hash drift: ${p} (recorded ${recorded[p].slice(0, 12)}…, live ${live.slice(0, 12)}…)`);
+    }
   }
-  const live = sha256(fs.readFileSync(ABS(p)));
-  if (live !== recorded[p]) {
-    drift.push(`hash drift: ${p} (recorded ${recorded[p].slice(0, 12)}…, live ${live.slice(0, 12)}…)`);
+  for (const p of recordedKeys) {
+    if (!liveSources.has(p)) {
+      missing.push(`stale source in index (file removed): ${p}`);
+    }
   }
-}
-for (const p of recordedKeys) {
-  if (!liveSources.has(p)) {
-    missing.push(`stale source in index (file removed): ${p}`);
+
+  const issues = [...drift, ...missing];
+  if (issues.length === 0) {
+    console.log(`[validate-indexes] indexes current — ${recordedKeys.size} sources hashed at ${meta.generated_at}.`);
+    return;
   }
-}
 
-const issues = [...drift, ...missing];
-if (issues.length === 0) {
-  console.log(`[validate-indexes] indexes current — ${recordedKeys.size} sources hashed at ${meta.generated_at}.`);
-  process.exit(0);
+  console.error("[validate-indexes] indexes STALE:");
+  for (const i of issues) console.error("  • " + i);
+  console.error("[validate-indexes] regenerate with: npm run build-indexes");
+  process.exitCode = 1;
 }
 
-console.error("[validate-indexes] indexes STALE:");
-for (const i of issues) console.error("  • " + i);
-console.error("[validate-indexes] regenerate with: npm run build-indexes");
-process.exit(1);
+if (require.main === module) main();
+
+module.exports = { main };

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,

package/lib/verify.js

@@ -51,6 +51,14 @@ const SKILLS_DIR = path.join(ROOT, 'skills');
 const PUBLIC_KEY_PATH = path.join(ROOT, 'keys', 'public.pem');
 const PRIVATE_KEY_PATH = path.join(ROOT, '.keys', 'private.pem');
 const MANIFEST_SCHEMA_PATH = path.join(__dirname, 'schemas', 'manifest.schema.json');
+// Audit G F4 — key-pin file. When present, lib/verify.js compares the live
+// public-key fingerprint against the pinned one and fails the verify run
+// if they differ (unless the operator sets KEYS_ROTATED=1). The file format
+// is a single line "SHA256:<base64>" matching the publicKeyFingerprint()
+// shape. The file is OPTIONAL: when missing, the gate warns-and-continues
+// rather than failing — this preserves bootstrap compatibility on fresh
+// clones / new key ceremonies. Patch-class semantics.
+const EXPECTED_FINGERPRINT_PATH = path.join(ROOT, 'keys', 'EXPECTED_FINGERPRINT');
 
 // --- public API ---
 
@@ -386,6 +394,38 @@ function validateAgainstSchema(value, schema, here, root) {
  * @param {string|null} pemKey  PEM-encoded public key (or null)
  * @returns {{sha256: string, sha3_512: string}|{error: string}}
  */
+/**
+ * Audit G F4 — compare the live public-key fingerprint against the optional
+ * pinned fingerprint in keys/EXPECTED_FINGERPRINT. Returns one of:
+ *   { status: 'no-pin' }      — keys/EXPECTED_FINGERPRINT not present.
+ *                               Callers should warn and continue.
+ *   { status: 'match' }       — live fingerprint matches the pin.
+ *   { status: 'mismatch',     — divergence; caller should fail unless
+ *     expected, actual,         KEYS_ROTATED=1 is set in the environment.
+ *     rotationOverride }
+ *
+ * @param {{sha256:string}|null} liveFp  publicKeyFingerprint() output
+ * @param {string} [pinPath]             optional override (testability)
+ */
+function checkExpectedFingerprint(liveFp, pinPath) {
+  const p = pinPath || EXPECTED_FINGERPRINT_PATH;
+  if (!fs.existsSync(p)) return { status: 'no-pin' };
+  if (!liveFp || typeof liveFp.sha256 !== 'string') {
+    return { status: 'mismatch', expected: 'unknown', actual: '(invalid)', rotationOverride: false };
+  }
+  const expected = fs.readFileSync(p, 'utf8').trim();
+  // Tolerate trailing comment / whitespace on the same line; the file's
+  // first non-empty line is the canonical fingerprint.
+  const firstLine = expected.split(/\r?\n/).map((l) => l.trim()).find((l) => l.length > 0) || '';
+  if (firstLine === liveFp.sha256) return { status: 'match' };
+  return {
+    status: 'mismatch',
+    expected: firstLine,
+    actual: liveFp.sha256,
+    rotationOverride: process.env.KEYS_ROTATED === '1',
+  };
+}
+
 function publicKeyFingerprint(pemKey) {
   if (!pemKey) return { sha256: '(no key)', sha3_512: '(no key)' };
   try {
@@ -468,6 +508,35 @@ if (require.main === module) {
   console.log(`[verify] ${fp.sha256}`);
   console.log(`[verify] ${fp.sha3_512}`);
 
+  // Audit G F4 — pin check. When keys/EXPECTED_FINGERPRINT exists, the
+  // live fingerprint MUST match it (or KEYS_ROTATED=1 must be set to
+  // intentionally override). When the file is absent, emit a single-line
+  // warning but continue — fresh clones / bootstrap workflows should not
+  // fail the gate before the operator has committed a fingerprint.
+  const pinResult = checkExpectedFingerprint(fp);
+  if (pinResult.status === 'no-pin') {
+    console.warn(
+      `[verify] WARN: keys/EXPECTED_FINGERPRINT not present — key-pin check skipped. ` +
+      `Create it with the current ${fp.sha256} line to enable pinning.`
+    );
+  } else if (pinResult.status === 'mismatch') {
+    if (pinResult.rotationOverride) {
+      console.warn(
+        `[verify] WARN: live key fingerprint ${pinResult.actual} differs from pin ` +
+        `${pinResult.expected}. KEYS_ROTATED=1 set — accepting rotation. ` +
+        `Update keys/EXPECTED_FINGERPRINT to lock the new pin.`
+      );
+    } else {
+      console.error(
+        `[verify] FAIL: live key fingerprint ${pinResult.actual} does not match ` +
+        `keys/EXPECTED_FINGERPRINT ${pinResult.expected}. ` +
+        `If this is an intentional rotation, re-run with KEYS_ROTATED=1 and ` +
+        `then commit the new fingerprint to keys/EXPECTED_FINGERPRINT.`
+      );
+      process.exit(1);
+    }
+  }
+
   if (result.invalid.length > 0) process.exit(1);
   if (result.missing_sig.length > 0) process.exit(1);
   if (result.missing_file.length > 0) process.exit(1);
@@ -483,4 +552,7 @@ module.exports = {
   validateSkillPath,
   loadManifestValidated,
   validateAgainstSchema,
+  publicKeyFingerprint,
+  checkExpectedFingerprint,
+  EXPECTED_FINGERPRINT_PATH,
 };

package/manifest-snapshot.json

@@ -1,6 +1,6 @@
 {
   "_comment": "Auto-generated by scripts/refresh-manifest-snapshot.js — do not hand-edit. Public skill surface used by check-manifest-snapshot.js to detect breaking removals.",
-  "_generated_at": "2026-05-14T14:28:31.798Z",
+  "_generated_at": "2026-05-14T15:55:39.383Z",
   "atlas_version": "5.1.0",
   "skill_count": 38,
   "skills": [

package/manifest-snapshot.sha256

@@ -0,0 +1 @@
+ca9d31e533c9d494e1ac5875e0a45176101438c3d75d44387187e367ccae21ad  manifest-snapshot.json