@blamejs/exceptd-skills 0.12.13 → 0.12.15

package/orchestrator/scheduler.js

@@ -3,12 +3,21 @@
 /**
  * Scheduled task coordinator for skill currency maintenance.
  *
- * Schedules: weekly currency check, monthly CVE validation, annual full audit.
- * Emits events via event-bus.js when currency thresholds are breached.
+ * Schedules: weekly currency check, monthly CVE validation reminder, annual
+ * full audit reminder. Emits events via event-bus.js when currency thresholds
+ * are breached.
  *
  * This is a simple interval-based scheduler. For production use, swap for a
  * proper cron daemon or cloud scheduler without changing the task definitions.
  *
+ * Bootstrap-fire policy. Long-cadence tasks (monthly, annual) are also
+ * evaluated on `start()` so a freshly-restarted watcher does not silently
+ * skip a due interval. Whether a task fires on bootstrap is gated by a
+ * persisted "last fired" timestamp store at
+ * `~/.exceptd/scheduler-last-fired.json` — the task fires only when the
+ * elapsed time since the persisted timestamp exceeds the interval. The
+ * weekly currency check always fires on bootstrap (legacy behavior).
+ *
  * Implementation note — INT32 overflow guard. `setInterval` / `setTimeout`
  * delay values are coerced to a signed 32-bit integer; any value above
  * 2^31 - 1 ms (~24.8 days) is silently clamped to 1 ms by Node, which
@@ -19,6 +28,10 @@
  * delay — including multi-year intervals — fires exactly when due.
  */
 
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
 const { bus, EVENT_TYPES } = require('./event-bus');
 const { currencyCheck } = require('./pipeline');
 
@@ -36,9 +49,64 @@ const CURRENCY_THRESHOLDS = {
   warning: 70
 };
 
+const LAST_FIRED_KEYS = {
+  WEEKLY_CURRENCY: 'weekly_currency_check',
+  MONTHLY_CVE_VALIDATION: 'monthly_cve_validation',
+  ANNUAL_AUDIT: 'annual_full_audit'
+};
+
 let unschedulers = [];
 let running = false;
 
+// --- persistent last-fired store ---
+
+/**
+ * Resolve the path of the last-fired persistence file. Defaults to
+ * `~/.exceptd/scheduler-last-fired.json`. Honors EXCEPTD_HOME for the test
+ * suite so unit tests stay isolated from the maintainer's real home dir.
+ */
+function _lastFiredStorePath() {
+  const root = process.env.EXCEPTD_HOME || path.join(os.homedir(), '.exceptd');
+  return path.join(root, 'scheduler-last-fired.json');
+}
+
+function _loadLastFired() {
+  const p = _lastFiredStorePath();
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function _saveLastFired(store) {
+  const p = _lastFiredStorePath();
+  try {
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify(store, null, 2));
+  } catch (err) {
+    // Persistence is best-effort. A failed write only means the next start
+    // can't tell whether the task fired; it does not break the running
+    // scheduler.
+    console.error('[scheduler] could not persist last-fired:', err.message);
+  }
+}
+
+function _markFired(key, when) {
+  const store = _loadLastFired();
+  store[key] = when || new Date().toISOString();
+  _saveLastFired(store);
+}
+
+function _shouldBootstrapFire(key, intervalMs) {
+  const store = _loadLastFired();
+  const stamp = store[key];
+  if (!stamp) return true;
+  const last = Date.parse(stamp);
+  if (!Number.isFinite(last)) return true;
+  return (Date.now() - last) >= intervalMs;
+}
+
 // --- scheduling primitive ---
 
 /**
@@ -71,16 +139,56 @@ function scheduleEvery(intervalMs, handler) {
 // --- public API ---
 
 /**
- * Start the scheduler. Runs all tasks immediately on start, then on schedule.
+ * Start the scheduler. Runs the weekly task immediately, then schedules all
+ * three on their intervals. Monthly and annual tasks are also "bootstrap
+ * fired" on start when the persisted last-fired timestamp is older than the
+ * interval (or absent), so a restarted watcher does not silently skip a due
+ * window. Bootstrap-fire happens inside the same try/catch the periodic
+ * wrapper uses so a single thrown task cannot crash the watcher.
  */
 function start() {
   if (running) return;
   running = true;
 
-  runWeeklyCurrencyCheck();
-  unschedulers.push(scheduleEvery(INTERVALS.WEEKLY_CURRENCY, runWeeklyCurrencyCheck));
-  unschedulers.push(scheduleEvery(INTERVALS.MONTHLY_CVE_VALIDATION, runMonthlyCveValidation));
-  unschedulers.push(scheduleEvery(INTERVALS.ANNUAL_AUDIT, runAnnualAudit));
+  const safeRun = (label, fn) => {
+    try { fn(); }
+    catch (e) { console.error('[scheduler] ' + label + ' failed:', e); }
+  };
+
+  // Weekly always fires on bootstrap (legacy behavior).
+  safeRun('weekly currency bootstrap', () => {
+    runWeeklyCurrencyCheck();
+    _markFired(LAST_FIRED_KEYS.WEEKLY_CURRENCY);
+  });
+
+  // Monthly + annual bootstrap-fire only when the persisted timestamp is
+  // older than the interval. This closes the "freshly-restarted watcher
+  // never fires the long-cadence task" gap.
+  if (_shouldBootstrapFire(LAST_FIRED_KEYS.MONTHLY_CVE_VALIDATION, INTERVALS.MONTHLY_CVE_VALIDATION)) {
+    safeRun('monthly CVE bootstrap', () => {
+      runMonthlyCveValidation();
+      _markFired(LAST_FIRED_KEYS.MONTHLY_CVE_VALIDATION);
+    });
+  }
+  if (_shouldBootstrapFire(LAST_FIRED_KEYS.ANNUAL_AUDIT, INTERVALS.ANNUAL_AUDIT)) {
+    safeRun('annual audit bootstrap', () => {
+      runAnnualAudit();
+      _markFired(LAST_FIRED_KEYS.ANNUAL_AUDIT);
+    });
+  }
+
+  unschedulers.push(scheduleEvery(INTERVALS.WEEKLY_CURRENCY, () => {
+    runWeeklyCurrencyCheck();
+    _markFired(LAST_FIRED_KEYS.WEEKLY_CURRENCY);
+  }));
+  unschedulers.push(scheduleEvery(INTERVALS.MONTHLY_CVE_VALIDATION, () => {
+    runMonthlyCveValidation();
+    _markFired(LAST_FIRED_KEYS.MONTHLY_CVE_VALIDATION);
+  }));
+  unschedulers.push(scheduleEvery(INTERVALS.ANNUAL_AUDIT, () => {
+    runAnnualAudit();
+    _markFired(LAST_FIRED_KEYS.ANNUAL_AUDIT);
+  }));
 
   console.log('[scheduler] Started. Weekly currency check, monthly CVE validation, annual audit scheduled.');
 }
@@ -113,14 +221,25 @@ function runWeeklyCurrencyCheck() {
 
   const { currency_report, action_required, critical_count } = currencyCheck();
 
-  for (const skill of currency_report) {
-    if (skill.currency_score < CURRENCY_THRESHOLDS.critical) {
-      bus.skillCurrencyLow({
-        skill_name: skill.skill,
-        currency_score: skill.currency_score,
-        days_since_review: skill.days_since_review
-      });
-    }
+  // Emit ONE aggregated SKILL_CURRENCY_LOW_AGGREGATE event per run instead
+  // of N per-skill events. Per-run aggregate prevents downstream consumers
+  // (`watch`, dashboards, alerting webhooks) from receiving an event storm
+  // when N skills are simultaneously stale — common after a long pause
+  // between runs or on first bootstrap. The aggregate payload carries
+  // critical_count + the full array of stale skills so consumers can still
+  // drill in. The legacy per-skill SKILL_CURRENCY_LOW signature is preserved
+  // for callers (and tests) that consume bus.skillCurrencyLow() directly.
+  const critical = currency_report.filter(s => s.currency_score < CURRENCY_THRESHOLDS.critical);
+  if (critical.length > 0) {
+    bus.emit(EVENT_TYPES.SKILL_CURRENCY_LOW_AGGREGATE, {
+      critical_count: critical.length,
+      skills: critical.map(s => ({
+        skill_name: s.skill,
+        currency_score: s.currency_score,
+        days_since_review: s.days_since_review
+      })),
+      timestamp
+    });
   }
 
   const result = {
@@ -129,7 +248,7 @@ function runWeeklyCurrencyCheck() {
     skills_checked: currency_report.length,
     action_required,
     critical_count,
-    critical_skills: currency_report.filter(s => s.currency_score < CURRENCY_THRESHOLDS.critical).map(s => s.skill),
+    critical_skills: critical.map(s => s.skill),
     warning_skills: currency_report.filter(s =>
       s.currency_score >= CURRENCY_THRESHOLDS.critical && s.currency_score < CURRENCY_THRESHOLDS.warning
     ).map(s => s.skill)
@@ -177,4 +296,18 @@ function runAnnualAudit() {
   };
 }
 
-module.exports = { start, stop, runCurrencyNow, scheduleEvery, SAFE_MAX_MS, TICK_MS };
+module.exports = {
+  start,
+  stop,
+  runCurrencyNow,
+  scheduleEvery,
+  SAFE_MAX_MS,
+  TICK_MS,
+  INTERVALS,
+  LAST_FIRED_KEYS,
+  // Internal hooks exposed for tests; not part of the operator surface.
+  _lastFiredStorePath,
+  _shouldBootstrapFire,
+  _markFired,
+  _loadLastFired,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/exceptd-skills",
-  "version": "0.12.13",
+  "version": "0.12.15",
   "description": "AI security skills grounded in mid-2026 threat reality, not stale framework documentation. 38 skills, 10 catalogs, 34 jurisdictions, pre-computed indexes, Ed25519-signed.",
   "keywords": [
     "ai-security",
@@ -54,8 +54,10 @@
     "data/",
     "skills/",
     "keys/public.pem",
+    "keys/EXPECTED_FINGERPRINT",
     "manifest.json",
     "manifest-snapshot.json",
+    "manifest-snapshot.sha256",
     "sbom.cdx.json",
     "AGENTS.md",
     "ARCHITECTURE.md",

package/sbom.cdx.json

@@ -1,10 +1,10 @@
 {
   "bomFormat": "CycloneDX",
   "specVersion": "1.6",
-  "serialNumber": "urn:uuid:4ab68946-cb1d-4bca-82a3-99dd37c31e07",
+  "serialNumber": "urn:uuid:0fb3661f-4f3b-4d31-98b3-d5fd759aa8c1",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-14T14:28:32.202Z",
+    "timestamp": "2026-05-14T16:47:04.535Z",
     "tools": [
       {
         "name": "hand-written",
@@ -13,10 +13,10 @@
       }
     ],
     "component": {
-      "bom-ref": "pkg:npm/@blamejs/exceptd-skills@0.12.13",
+      "bom-ref": "pkg:npm/@blamejs/exceptd-skills@0.12.15",
       "type": "application",
       "name": "@blamejs/exceptd-skills",
-      "version": "0.12.13",
+      "version": "0.12.15",
       "description": "AI security skills grounded in mid-2026 threat reality, not stale framework documentation. 38 skills, 10 catalogs, 34 jurisdictions, pre-computed indexes, Ed25519-signed.",
       "licenses": [
         {
@@ -25,11 +25,11 @@
           }
         }
       ],
-      "purl": "pkg:npm/%40blamejs/exceptd-skills@0.12.13",
+      "purl": "pkg:npm/%40blamejs/exceptd-skills@0.12.15",
       "externalReferences": [
         {
           "type": "distribution",
-          "url": "https://www.npmjs.com/package/@blamejs/exceptd-skills/v/0.12.13"
+          "url": "https://www.npmjs.com/package/@blamejs/exceptd-skills/v/0.12.15"
         },
         {
           "type": "vcs",
@@ -129,7 +129,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "57d8f5c3bca23cd4ef2a16adf4107bc60c4da3fbc9bb861580edc76ed9a2d132"
+          "content": "fa9814c2d18db221a2dc552cf2a5047467d87a2590cbc9d64b8a0a340e545b55"
         }
       ],
       "externalReferences": [

package/scripts/check-manifest-snapshot.js

@@ -32,10 +32,12 @@
 
 const fs = require("fs");
 const path = require("path");
+const crypto = require("crypto");
 
 const ROOT = path.join(__dirname, "..");
 const MANIFEST_PATH = path.join(ROOT, "manifest.json");
 const SNAPSHOT_PATH = path.join(ROOT, "manifest-snapshot.json");
+const SNAPSHOT_SHA_PATH = path.join(ROOT, "manifest-snapshot.sha256");
 
 function captureSurface(manifest) {
   // Public surface = the set of facts downstream consumers may have
@@ -188,6 +190,36 @@ if (require.main === module) {
       process.exit(2);
     }
 
+    // Audit G F23 — when manifest-snapshot.sha256 is present, validate that
+    // the on-disk snapshot still hashes to the recorded value. Catches a
+    // hand-edit of manifest-snapshot.json that bypassed refresh-manifest-
+    // snapshot.js (so the F5 commit-only guard never had a chance to fire).
+    // The file is OPTIONAL: when absent, the gate warns-and-continues so
+    // pre-v0.12.14 trees still work.
+    if (fs.existsSync(SNAPSHOT_SHA_PATH)) {
+      const expectedLine = fs.readFileSync(SNAPSHOT_SHA_PATH, "utf8").trim();
+      const expectedSha = expectedLine.split(/\s+/)[0];
+      const liveSha = crypto
+        .createHash("sha256")
+        .update(fs.readFileSync(SNAPSHOT_PATH))
+        .digest("hex");
+      if (expectedSha !== liveSha) {
+        console.error(
+          "[check-manifest-snapshot] manifest-snapshot.json integrity check FAILED " +
+          `(expected ${expectedSha.slice(0, 12)}…, live ${liveSha.slice(0, 12)}…). ` +
+          "Someone edited manifest-snapshot.json without running refresh-manifest-snapshot.js. " +
+          "Re-run `node scripts/refresh-manifest-snapshot.js --commit-only` to regenerate."
+        );
+        process.exit(1);
+      }
+    } else {
+      console.warn(
+        "[check-manifest-snapshot] WARN: manifest-snapshot.sha256 missing — " +
+        "integrity check skipped. Run `node scripts/refresh-manifest-snapshot.js --commit-only` " +
+        "to generate it."
+      );
+    }
+
     const manifest = JSON.parse(fs.readFileSync(MANIFEST_PATH, "utf8"));
     const current = captureSurface(manifest);
     const result = diff(baseline, current);

package/scripts/check-sbom-currency.js

@@ -62,11 +62,67 @@ function checkSbomCurrency(root) {
   if (sbom.bomFormat !== "CycloneDX" || sbom.specVersion !== "1.6") {
     errors.push("SBOM is not CycloneDX 1.6");
   }
+
+  // Audit G F2 — component-level cross-check. A renamed or version-bumped
+  // skill that never made it into the SBOM refresh will pass the count
+  // check (the cardinality is unchanged) but the per-component name +
+  // version comparison surfaces it. Two component classes are recognised:
+  //
+  //   1. Skill components — bom-ref begins with "skill:" OR the component
+  //      name matches a manifest.skills[].name. Each one must exist in
+  //      manifest.skills with the same version.
+  //   2. Vendor components — bom-ref begins with "vendor:". Validated
+  //      against vendor/blamejs/_PROVENANCE.json when present.
+  //
+  // Components that don't fit either pattern are surfaced as warnings
+  // (not errors) so the gate isn't brittle against future component types.
+  const components = Array.isArray(sbom.components) ? sbom.components : [];
+  const skillByName = new Map(
+    (manifest.skills || []).map((s) => [s.name, s])
+  );
+  const provPath = path.join(root, "vendor", "blamejs", "_PROVENANCE.json");
+  let vendorProv = null;
+  if (fs.existsSync(provPath)) {
+    try { vendorProv = JSON.parse(fs.readFileSync(provPath, "utf8")); } catch { /* leave null */ }
+  }
+  for (const comp of components) {
+    const bomRef = typeof comp["bom-ref"] === "string" ? comp["bom-ref"] : "";
+    const name = comp.name;
+    const version = comp.version;
+    if (bomRef.startsWith("skill:") || skillByName.has(name)) {
+      const skillName = bomRef.startsWith("skill:")
+        ? bomRef.slice("skill:".length)
+        : name;
+      const live = skillByName.get(skillName);
+      if (!live) {
+        errors.push(
+          `SBOM component "${name}" (bom-ref ${bomRef}) is not in manifest.skills — skill renamed or removed without SBOM refresh`
+        );
+        continue;
+      }
+      if (live.version && version && String(live.version) !== String(version)) {
+        errors.push(
+          `SBOM component "${name}" version ${version} != manifest.skills version ${live.version} — bump without SBOM refresh`
+        );
+      }
+    } else if (bomRef.startsWith("vendor:")) {
+      if (vendorProv && vendorProv.pinned_commit) {
+        const expected = vendorProv.pinned_commit.slice(0, 12);
+        if (version && String(version) !== expected) {
+          errors.push(
+            `SBOM vendor component "${name}" version ${version} != _PROVENANCE.json pinned_commit ${expected}`
+          );
+        }
+      }
+    }
+  }
+
   return {
     ok: errors.length === 0,
     errors,
     skills: sbomSkills,
     catalogs: sbomCatalogs,
+    components_validated: components.length,
   };
 }
 
@@ -76,10 +132,16 @@ function main() {
   if (!result.ok) {
     for (const e of result.errors) process.stderr.write(e + "\n");
     process.stderr.write("Run `npm run refresh-sbom` to regenerate sbom.cdx.json.\n");
-    process.exit(1);
+    // v0.11.13 pattern: set exitCode + return so buffered stdout/stderr
+    // writes drain before the event loop exits. process.exit() can
+    // truncate piped output (CI log capture, JSON consumers).
+    process.exitCode = 1;
+    return;
   }
-  process.stdout.write(`SBOM current — ${result.skills} skills, ${result.catalogs} catalogs.\n`);
-  process.exit(0);
+  process.stdout.write(
+    `SBOM current — ${result.skills} skills, ${result.catalogs} catalogs, ` +
+    `${result.components_validated} components validated.\n`
+  );
 }
 
 module.exports = { checkSbomCurrency, resolveRoot };

package/scripts/check-test-coverage.js

@@ -89,10 +89,49 @@ function git(args, cwd) {
 // findings masked. Codex P1 flag on PR #2 of v0.12.8.
 function resolveBaseRef(opts, cwd) {
   if (opts.staged) return null; // staged mode uses --cached / HEAD throughout
+  // F14 — fall back gracefully when origin/main is unreachable. The
+  // original implementation tried `merge-base HEAD <opts.base>` and, on
+  // failure, returned opts.base verbatim — which then failed every
+  // subsequent git invocation, surfacing as a runner-level error. In CI
+  // (full clones) the original ref usually resolves; on a developer
+  // laptop without `origin/main` configured (fresh clone, detached
+  // worktree, alternative remote name) the gate would fail entirely.
+  //
+  // Order of preference:
+  //   1. merge-base against the requested base
+  //   2. requested base verbatim, if `git rev-parse --verify` resolves it
+  //   3. local `main` HEAD if it exists
+  //   4. HEAD~1 as a last resort (single-commit diff)
+  const tryResolve = (ref) => {
+    try {
+      git(["merge-base", "HEAD", ref], cwd).trim();
+      return ref;
+    } catch { /* not resolvable */ }
+    try {
+      git(["rev-parse", "--verify", ref], cwd).trim();
+      return ref;
+    } catch { return null; }
+  };
   try {
     const mb = git(["merge-base", "HEAD", opts.base], cwd).trim();
     if (mb) return mb;
-  } catch { /* base may not exist locally; fall back to ref literal */ }
+  } catch { /* fall through */ }
+  const direct = tryResolve(opts.base);
+  if (direct) return direct;
+  const local = tryResolve("main");
+  if (local) {
+    process.stderr.write(
+      `[check-test-coverage] WARN: ${opts.base} unreachable; falling back to local main\n`
+    );
+    return local;
+  }
+  const parent = tryResolve("HEAD~1");
+  if (parent) {
+    process.stderr.write(
+      `[check-test-coverage] WARN: ${opts.base} unreachable and no local main; falling back to HEAD~1\n`
+    );
+    return parent;
+  }
   return opts.base;
 }
 
@@ -165,6 +204,23 @@ function categorize(file) {
   if (norm.startsWith("scripts/") && norm.endsWith(".js")) return "lib";
   if (norm.startsWith("data/playbooks/") && norm.endsWith(".json")) return "playbook";
   if (norm === "data/cve-catalog.json") return "cve-catalog";
+  // F11 — files matching catalog/schema/SBOM shapes are surfaced for manual
+  // review rather than silent allowlist. These changes (manifest.json,
+  // schemas/*, data/*.json, sbom.cdx.json, manifest-snapshot.*) can carry
+  // semantic surface but the analyzer has no syntactic surface extractor
+  // for them — humans should look.
+  if (norm === "manifest.json") return "manual-review";
+  if (norm === "manifest-snapshot.json") return "manual-review";
+  if (norm === "manifest-snapshot.sha256") return "manual-review";
+  if (norm === "sbom.cdx.json") return "manual-review";
+  if (norm.startsWith("lib/schemas/")) return "manual-review";
+  // v0.12.14: data/_indexes/ is auto-regenerated from data/ + manifest by
+  // `npm run build-indexes`; the source-of-truth diff is in the data/
+  // files themselves. Allowlist the derived index files so they don't
+  // perpetually surface as manual-review on every release commit.
+  if (norm.startsWith("data/_indexes/")) return "allowlist-derived";
+  if (norm.startsWith("data/") && norm.endsWith(".json")) return "manual-review";
+  if (norm === "package.json") return "manual-review";
   return "other";
 }
 
@@ -271,15 +327,20 @@ function safeParse(s) { try { return s ? JSON.parse(s) : null; } catch { return
 
 function loadTestCorpus(cwd) {
   const root = path.join(cwd, "tests");
-  if (!fs.existsSync(root)) return "";
+  if (!fs.existsSync(root)) return { joined: "", files: [] };
   const acc = [];
+  const files = [];
   walk(root, p => {
     const norm = p.replace(/\\/g, "/");
     if (/\.(js|json)$/.test(norm)) {
-      try { acc.push(fs.readFileSync(p, "utf8")); } catch { /* ignore unreadable */ }
+      try {
+        const content = fs.readFileSync(p, "utf8");
+        acc.push(content);
+        files.push({ path: norm, content });
+      } catch { /* ignore unreadable */ }
     }
   });
-  return acc.join("\n\x00\n");
+  return { joined: acc.join("\n\x00\n"), files };
 }
 
 function walk(dir, fn) {
@@ -302,22 +363,76 @@ function coversCliFlag(corpus, flag) {
   return corpus.includes(flag);
 }
 
+// F10 — same-file context check. A test corpus is no longer treated as
+// one giant string for lib-export coverage: the identifier must appear
+// inside a real test block (`test(`, `it(`, `describe(`, or an `assert(`
+// argument) within the SAME file that issues the matching require().
+// Pre-fix: an `assert.equal(...)` mention in one test file plus a stray
+// `require('../lib/x')` in a completely different test file counted as
+// coverage. That's not coverage — it's textual coincidence.
+//
+// `corpus` may be either a string (legacy joined corpus, used by
+// CLI/playbook/CVE coverage probes) or the structured shape
+// `{ joined, files }` produced by loadTestCorpus().
 function coversLibExport(corpus, libRel, ident) {
   const baseName = path.basename(libRel).replace(/\.js$/, "");
   const baseFile = path.basename(libRel); // e.g. "check-sbom-currency.js"
   const identRe = new RegExp("\\b" + escapeRe(ident) + "\\b");
-  // Primary: a `require()` that mentions the module name AND a reference
-  // to the identifier anywhere in the test corpus. Catches the canonical
-  // `const { foo } = require('../lib/x')` test shape.
   const requireRe = new RegExp("require\\([^)]*" + escapeRe(baseName) + "[^)]*\\)");
-  if (requireRe.test(corpus) && identRe.test(corpus)) return true;
-  // v0.12.9: a test that spawns the script under test (e.g.
-  // `spawnSync(node, [".../scripts/check-sbom-currency.js", ...])`) is
-  // real coverage too. Accept that shape when the corpus references the
-  // full filename AND the identifier elsewhere. The `.js` suffix is what
-  // distinguishes a real spawn-path from an arbitrary mention of the
-  // module base name.
-  if (corpus.includes(baseFile) && identRe.test(corpus)) return true;
+  // Accept the structured shape (preferred). Walk files individually.
+  if (corpus && Array.isArray(corpus.files)) {
+    for (const f of corpus.files) {
+      const hasRequire = requireRe.test(f.content);
+      const mentionsSpawnPath = f.content.includes(baseFile);
+      if (!hasRequire && !mentionsSpawnPath) continue;
+      if (!identRe.test(f.content)) continue;
+      // F10 — require the identifier appears inside a test block in this
+      // file. Recognise `test(`, `it(`, `describe(`, or `assert(` (or any
+      // `assert.<member>(`) bracketed argument that mentions the ident.
+      if (mentionsIdentInTestContext(f.content, ident)) return true;
+    }
+    return false;
+  }
+  // Fallback: legacy joined-string corpus.
+  const joined = typeof corpus === "string" ? corpus : (corpus && corpus.joined) || "";
+  if (requireRe.test(joined) && identRe.test(joined)) return true;
+  if (joined.includes(baseFile) && identRe.test(joined)) return true;
+  return false;
+}
+
+// Returns true when `ident` appears as a token inside the body of any
+// `test( ... )`, `it( ... )`, `describe( ... )`, `assert( ... )` or
+// `assert.<member>( ... )` call in the file. We approximate "the body of
+// the call" by finding the opening paren after the keyword, then walking
+// matched parens until the call closes. This is a syntactic-enough check
+// for vanilla JavaScript tests; the goal is to refuse "ident only appears
+// in a top-level comment" while still accepting `assert.deepEqual(foo, ...)`.
+function mentionsIdentInTestContext(content, ident) {
+  const tokenRe = new RegExp("\\b" + escapeRe(ident) + "\\b");
+  // Quick reject: file does not mention the identifier at all.
+  if (!tokenRe.test(content)) return false;
+  const callRe = /\b(test|it|describe|assert(?:\.[A-Za-z_$][\w$]*)?)\s*\(/g;
+  let m;
+  while ((m = callRe.exec(content)) !== null) {
+    const start = m.index + m[0].length; // pointer to first char inside (
+    let depth = 1;
+    let i = start;
+    let inStr = null;
+    while (i < content.length && depth > 0) {
+      const c = content[i];
+      if (inStr) {
+        if (c === "\\") { i += 2; continue; }
+        if (c === inStr) inStr = null;
+      } else {
+        if (c === '"' || c === "'" || c === "`") inStr = c;
+        else if (c === "(") depth++;
+        else if (c === ")") depth--;
+      }
+      i++;
+    }
+    const body = content.slice(start, i - 1);
+    if (tokenRe.test(body)) return true;
+  }
   return false;
 }
 
@@ -341,7 +456,8 @@ function analyze(opts) {
   // between calls produces false add/remove findings.
   const resolvedBase = resolveBaseRef(opts, cwd);
   const changed = listChangedFiles(opts, cwd, resolvedBase);
-  const corpus = loadTestCorpus(cwd);
+  const corpusObj = loadTestCorpus(cwd);
+  const corpus = corpusObj.joined;
 
   const findings = [];
   const allowlisted = [];
@@ -355,7 +471,12 @@ function analyze(opts) {
     }
     if (cat === "skill") { allowlisted.push({ file: ch.file, reason: "skill-signed" }); continue; }
     if (cat === "workflow") { manualReview.push({ file: ch.file, reason: "workflow" }); continue; }
-    if (cat === "other") { allowlisted.push({ file: ch.file, reason: "out-of-scope" }); continue; }
+    // F11 — data catalogs, schemas, manifests, SBOM go to manual review
+    // instead of being silently allowlisted. They show up in CI output.
+    if (cat === "manual-review") { manualReview.push({ file: ch.file, reason: "manual-review" }); continue; }
+    // v0.12.14: derived index files allowlist (auto-regenerated artifacts).
+    if (cat === "allowlist-derived") { allowlisted.push({ file: ch.file, reason: "derived-artifact" }); continue; }
+    if (cat === "other") { manualReview.push({ file: ch.file, reason: "unclassified" }); continue; }
     if (ch.status !== "D" && isWhitespaceOnly(opts, ch.file, cwd, resolvedBase)) {
       allowlisted.push({ file: ch.file, reason: "whitespace-only" });
       continue;
@@ -381,9 +502,11 @@ function analyze(opts) {
       const b = extractLibExports(before);
       const a = extractLibExports(after);
       const d = diffSets(b, a);
-      for (const id of d.added) if (!coversLibExport(corpus, ch.file, id))
+      // F10 — pass the structured corpus so coversLibExport can enforce
+      // same-file require()+identifier-in-test-context coverage.
+      for (const id of d.added) if (!coversLibExport(corpusObj, ch.file, id))
         findings.push({ file: ch.file, kind: "lib-export", surface: id, change: "added" });
-      for (const id of d.removed) if (coversLibExport(corpus, ch.file, id))
+      for (const id of d.removed) if (coversLibExport(corpusObj, ch.file, id))
         findings.push({ file: ch.file, kind: "lib-export", surface: id, change: "removed-but-test-remains" });
     } else if (cat === "playbook") {
       const b = extractPlaybookIds(before);