@blamejs/exceptd-skills 0.12.13 → 0.12.16

package/scripts/predeploy.js

@@ -19,6 +19,15 @@
  * Single-source-of-truth: the GATES list below mirrors the job sequence
  * in .github/workflows/ci.yml. Test coverage in tests/predeploy.test.js
  * asserts the two stay in sync.
+ *
+ * Audit G F5 — when the manifest-snapshot gate fails, the fix is NOT to
+ * run `npm run refresh-snapshot` blindly. The refresh script now refuses
+ * unless the operator passes `--commit-only` or sets
+ * EXCEPTD_SNAPSHOT_AUDIT_ACK=1. This is intentional: a failing snapshot
+ * gate means a breaking change was detected, and an accidental refresh
+ * would silently rewrite the baseline. Read the breaking-change list
+ * first, then run `node scripts/refresh-manifest-snapshot.js --commit-only`
+ * if the change is intentional.
  */
 
 const { execFileSync } = require("child_process");
@@ -62,28 +71,15 @@ const GATES = [
     args: [path.join(ROOT, "lib", "validate-cve-catalog.js")],
     ciJobName: "Data integrity (catalog + manifest snapshot)",
   },
-  {
-    name: "Validate offline CVE catalog state",
-    command: process.execPath,
-    args: [
-      path.join(ROOT, "orchestrator", "index.js"),
-      "validate-cves",
-      "--offline",
-      "--no-fail",
-    ],
-    ciJobName: "Data integrity (catalog + manifest snapshot)",
-  },
-  {
-    name: "Validate offline RFC catalog state",
-    command: process.execPath,
-    args: [
-      path.join(ROOT, "orchestrator", "index.js"),
-      "validate-rfcs",
-      "--offline",
-      "--no-fail",
-    ],
-    ciJobName: "Data integrity (catalog + manifest snapshot)",
-  },
+  // Audit G F13 — the "validate-cves --offline --no-fail" and
+  // "validate-rfcs --offline --no-fail" gates were enumeration-only sanity
+  // checks: `--no-fail` forced them to always exit 0, so they never blocked
+  // a release on a real catalog problem. The deep catalog validation is
+  // already performed by the gate above (`lib/validate-cve-catalog.js`),
+  // including cross-catalog reference resolution after this same audit.
+  // Keeping the no-op gates as predeploy steps inflated the gate count for
+  // no marginal value and risked false confidence ("X gates passed"). They
+  // are removed in v0.12.14; document the removal in CHANGELOG.
   {
     name: "Manifest snapshot gate (breaking-change detector)",
     command: process.execPath,
@@ -97,9 +93,13 @@ const GATES = [
     ciJobName: "Lint skill files",
   },
   {
-    // Informational only — surfaces the forward_watch horizon across all
-    // skills as a sanity signal. Emits the count but never fails the run;
-    // a parse problem is reported, not blocking.
+    // Informational — surfaces the forward_watch horizon across all skills.
+    // Audit G F12: an exit code of 0 means "ok", 1 means "items present
+    // (informational)", 2+ means a runtime error in the gate itself.
+    // The runner now distinguishes the two: 0/1 stay informational, 2+
+    // surface as a real failure. Pre-fix, any non-zero exit was rolled up
+    // as informational, which hid crashes (a 137 OOM looked the same as
+    // "found 12 items to review").
     name: "Forward-watch aggregator (informational)",
     command: process.execPath,
     args: [
@@ -108,6 +108,7 @@ const GATES = [
     ],
     ciJobName: "Data integrity (catalog + manifest snapshot)",
     informational: true,
+    informationalMaxExitCode: 1,
   },
   {
     name: "Validate catalog _meta (tlp + source_confidence + freshness_policy)",
@@ -192,25 +193,60 @@ function runGate(gate) {
     }
   }
   const t0 = Date.now();
-  try {
-    execFileSync(gate.command, gate.args, { stdio: "inherit", cwd: ROOT });
-    return { status: "passed", durationMs: Date.now() - t0 };
-  } catch (e) {
-    if (gate.informational) {
+  // Audit G F21 — spawn the child with piped stdio + tee to the parent so we
+  // can count `WARN ` lines for the summary table. We still want the live
+  // output, so each chunk is forwarded as it arrives.
+  const { spawnSync } = require("child_process");
+  const r = spawnSync(gate.command, gate.args, {
+    cwd: ROOT,
+    encoding: "utf8",
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  const durationMs = Date.now() - t0;
+  if (r.stdout) process.stdout.write(r.stdout);
+  if (r.stderr) process.stderr.write(r.stderr);
+  // Count WARN-labelled lines in the combined stream so the summary table
+  // can surface them. Lint / validate output uses "WARN  " at line start;
+  // count both the table form and an inline "[warn]" form.
+  const combined = (r.stdout || "") + (r.stderr || "");
+  const warnCount = (
+    combined.match(/^WARN\b/gm) || []
+  ).length + (
+    combined.match(/\[warn\]/g) || []
+  ).length;
+  if (r.status === 0) {
+    return { status: "passed", durationMs, warnCount };
+  }
+  // Audit G F12 — gates may declare informationalMaxExitCode to distinguish
+  // "soft signal" (exit codes 0..N) from "crash" (> N). Default behaviour
+  // for an informational gate without that field stays the same.
+  if (gate.informational) {
+    const ceil = typeof gate.informationalMaxExitCode === "number"
+      ? gate.informationalMaxExitCode
+      : Infinity;
+    if (r.status !== null && r.status > ceil) {
       return {
-        status: "informational",
-        exitCode: e.status ?? null,
-        message: e.message,
-        durationMs: Date.now() - t0,
+        status: "failed",
+        exitCode: r.status,
+        message: `informational gate crashed (exit ${r.status} > informationalMaxExitCode=${ceil})`,
+        durationMs,
+        warnCount,
       };
     }
     return {
-      status: "failed",
-      exitCode: e.status ?? null,
-      message: e.message,
-      durationMs: Date.now() - t0,
+      status: "informational",
+      exitCode: r.status ?? null,
+      durationMs,
+      warnCount,
     };
   }
+  return {
+    status: "failed",
+    exitCode: r.status ?? null,
+    message: r.error ? r.error.message : `exit ${r.status}`,
+    durationMs,
+    warnCount,
+  };
 }
 
 function fmtMs(ms) {
@@ -258,8 +294,16 @@ function main() {
         : "✗";
     const timing = fmtMs(outcome.durationMs);
     const timingSuffix = timing ? `  (${timing})` : "";
+    // F21 — surface WARN counts so a gate that "passed (3 warnings)" is
+    // distinguishable from one that passed cleanly. Pre-fix, warnings
+    // printed by individual gates (validate-cve-catalog, lint-skills,
+    // validate-playbooks) scrolled past invisible in the summary.
+    const warnSuffix =
+      outcome.warnCount && outcome.warnCount > 0
+        ? ` (${outcome.warnCount} warning${outcome.warnCount === 1 ? "" : "s"})`
+        : "";
     process.stdout.write(
-      `  ${icon} ${gate.name.padEnd(widest)}  ${outcome.status}${timingSuffix}\n`
+      `  ${icon} ${gate.name.padEnd(widest)}  ${outcome.status}${warnSuffix}${timingSuffix}\n`
     );
   }
 

package/scripts/refresh-manifest-snapshot.js

@@ -11,10 +11,22 @@
  * blindly — read the breaking-change list first. A breaking change is
  * a surface narrowing every downstream consumer needs to know about.
  *
+ * Audit G F5 — commitOnly mode. Pass `--commit-only` (or set the env
+ * EXCEPTD_SNAPSHOT_AUDIT_ACK=1) to acknowledge that the operator
+ * deliberately wants to overwrite the committed snapshot. When neither
+ * flag nor env is set AND the snapshot would actually change, the
+ * script refuses and emits a structured diff hint. This stops an
+ * accidental `npm run refresh-snapshot` (run as muscle-memory while
+ * triaging a failing gate) from masking a real breaking change.
+ *
  * Usage:
- *   node scripts/refresh-manifest-snapshot.js
- *   git add manifest-snapshot.json
- *   git commit -m "refresh manifest snapshot: <what changed>"
+ *   node scripts/refresh-manifest-snapshot.js              # dry-shows the diff
+ *   EXCEPTD_SNAPSHOT_AUDIT_ACK=1 \
+ *     node scripts/refresh-manifest-snapshot.js            # writes the new snapshot
+ *   node scripts/refresh-manifest-snapshot.js --commit-only   # same thing, on argv
+ *
+ * The flag is documented in scripts/predeploy.js so contributors see it
+ * the moment the snapshot gate fails.
  */
 
 const fs = require("fs");
@@ -50,8 +62,47 @@ function captureSurface(manifest) {
 
 const manifest = JSON.parse(fs.readFileSync(MANIFEST_PATH, "utf8"));
 const snapshot = captureSurface(manifest);
+const newJson = JSON.stringify(snapshot, null, 2) + "\n";
+
+// F5 — refuse to overwrite an existing snapshot unless the operator
+// has explicitly acknowledged the rewrite (env or --commit-only flag).
+const argv = process.argv.slice(2);
+const commitOnly =
+  argv.includes("--commit-only") ||
+  process.env.EXCEPTD_SNAPSHOT_AUDIT_ACK === "1";
 
-fs.writeFileSync(SNAPSHOT_PATH, JSON.stringify(snapshot, null, 2) + "\n", "utf8");
+if (fs.existsSync(SNAPSHOT_PATH) && !commitOnly) {
+  const current = fs.readFileSync(SNAPSHOT_PATH, "utf8");
+  // Normalise the _generated_at timestamp for comparison — that field
+  // changes every run and shouldn't trigger the guard.
+  const stripGenerated = (s) => s.replace(
+    /"_generated_at":\s*"[^"]+",?\s*\n?/, ""
+  );
+  if (stripGenerated(current) === stripGenerated(newJson)) {
+    console.log("[refresh-manifest-snapshot] snapshot unchanged — nothing to do.");
+    process.exit(0);
+  }
+  process.stderr.write(
+    "[refresh-manifest-snapshot] REFUSING to overwrite manifest-snapshot.json — " +
+    "the captured surface differs from the committed snapshot.\n" +
+    "  Re-run with `--commit-only` (or EXCEPTD_SNAPSHOT_AUDIT_ACK=1) to confirm " +
+    "the rewrite is intentional. The check-manifest-snapshot.js gate exists to " +
+    "force a deliberate decision about removed skills / triggers / refs before " +
+    "the baseline is rewritten.\n"
+  );
+  process.exit(1);
+}
+
+fs.writeFileSync(SNAPSHOT_PATH, newJson, "utf8");
 
 console.log(`[refresh-manifest-snapshot] wrote ${snapshot.skill_count} skills to manifest-snapshot.json`);
 console.log("[refresh-manifest-snapshot] commit this file alongside the surface change.");
+
+// Audit G F23 — write a tracked SHA-256 of the snapshot so the
+// check-manifest-snapshot.js gate can verify integrity (no hand edits
+// after refresh).
+const crypto = require("crypto");
+const snapshotSha = crypto.createHash("sha256").update(newJson).digest("hex");
+const snapshotShaPath = path.join(ROOT, "manifest-snapshot.sha256");
+fs.writeFileSync(snapshotShaPath, snapshotSha + "  manifest-snapshot.json\n", "utf8");
+console.log(`[refresh-manifest-snapshot] wrote integrity hash to manifest-snapshot.sha256`);

package/scripts/validate-vendor-online.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * scripts/validate-vendor-online.js — Audit G F6.
+ *
+ * Optional, network-touching companion to lib/validate-vendor.js. For every
+ * file recorded in vendor/blamejs/_PROVENANCE.json, fetches the upstream
+ * blob from github.com/<source_repo>/blob/<pinned_commit>/<upstream_path>
+ * (via the raw.githubusercontent.com mirror), hashes it, and compares the
+ * result against the `upstream_sha256_at_pin` recorded in _PROVENANCE.json.
+ *
+ * This catches the class where _PROVENANCE.json was hand-edited to
+ * advertise a `upstream_sha256_at_pin` that does not actually match what
+ * upstream had at that commit. lib/validate-vendor.js only checks that the
+ * local vendored file matches its own recorded hash — that's self-attesting.
+ * This script extends the check to upstream, closing the gap.
+ *
+ * Not part of `npm run predeploy` by default — the predeploy gate sequence
+ * must remain network-independent (offline gates only). Run manually:
+ *
+ *   node scripts/validate-vendor-online.js
+ *   node scripts/validate-vendor-online.js --timeout 30000
+ *   node scripts/validate-vendor-online.js --json
+ *
+ * Exit codes:
+ *   0  every vendored file's upstream_sha256_at_pin matched upstream
+ *   1  at least one mismatch
+ *   2  runtime / network error
+ *
+ * Zero npm deps. Node 24 stdlib only.
+ */
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const https = require("https");
+
+const ROOT = path.join(__dirname, "..");
+const PROV_PATH = path.join(ROOT, "vendor", "blamejs", "_PROVENANCE.json");
+
+function parseArgs(argv) {
+  const out = { timeoutMs: 15000, json: false };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--timeout") out.timeoutMs = Number(argv[++i]) || out.timeoutMs;
+    else if (a === "--json") out.json = true;
+    else if (a === "--help" || a === "-h") {
+      process.stdout.write(
+        "Usage: node scripts/validate-vendor-online.js [--timeout <ms>] [--json]\n"
+      );
+      process.exit(0);
+    } else {
+      process.stderr.write(`Unknown argument: ${a}\n`);
+      process.exit(2);
+    }
+  }
+  return out;
+}
+
+function rawUrlForPin(sourceRepo, commit, upstreamPath) {
+  // Translate https://github.com/owner/repo → raw.githubusercontent.com/owner/repo
+  // sourceRepo may end in .git; strip it. Tolerate trailing slash.
+  const m = (sourceRepo || "").match(
+    /^https?:\/\/github\.com\/([^/]+)\/([^/]+?)(?:\.git)?\/?$/
+  );
+  if (!m) return null;
+  const [, owner, repo] = m;
+  const cleanPath = String(upstreamPath || "").replace(/^\/+/, "");
+  return `https://raw.githubusercontent.com/${owner}/${repo}/${commit}/${cleanPath}`;
+}
+
+const MAX_REDIRECTS = 5;
+
+function fetchBuffer(url, timeoutMs, redirectsLeft = MAX_REDIRECTS) {
+  return new Promise((resolve, reject) => {
+    const req = https.get(url, (res) => {
+      // v0.12.14 (codex P2): cap redirect hops. A redirect loop (or a
+      // hostile / mis-configured upstream that keeps returning 3xx with
+      // Location pointing back to itself) used to recurse until stack
+      // overflow or hang. Now: count hops, fail clean on exhaustion.
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        res.resume();
+        if (redirectsLeft <= 0) {
+          return reject(new Error(`exceeded ${MAX_REDIRECTS} redirects fetching ${url}`));
+        }
+        return resolve(fetchBuffer(res.headers.location, timeoutMs, redirectsLeft - 1));
+      }
+      if (res.statusCode !== 200) {
+        res.resume();
+        return reject(new Error(`HTTP ${res.statusCode} for ${url}`));
+      }
+      const chunks = [];
+      res.on("data", (c) => chunks.push(c));
+      res.on("end", () => resolve(Buffer.concat(chunks)));
+      res.on("error", reject);
+    });
+    req.on("error", reject);
+    req.setTimeout(timeoutMs, () => {
+      req.destroy(new Error(`timeout after ${timeoutMs}ms fetching ${url}`));
+    });
+  });
+}
+
+async function main() {
+  const opts = parseArgs(process.argv);
+  if (!fs.existsSync(PROV_PATH)) {
+    process.stderr.write(`vendor/blamejs/_PROVENANCE.json missing\n`);
+    process.exitCode = 2;
+    return;
+  }
+  const prov = JSON.parse(fs.readFileSync(PROV_PATH, "utf8"));
+  const sourceRepo = prov.source_repo;
+  const pinnedCommit = prov.pinned_commit;
+  if (!sourceRepo || !pinnedCommit) {
+    process.stderr.write(`_PROVENANCE.json missing source_repo or pinned_commit\n`);
+    process.exitCode = 2;
+    return;
+  }
+
+  const findings = [];
+  for (const [name, info] of Object.entries(prov.files || {})) {
+    const url = rawUrlForPin(sourceRepo, pinnedCommit, info.upstream_path);
+    if (!url) {
+      findings.push({ name, ok: false, reason: `cannot compute raw URL for ${sourceRepo}` });
+      continue;
+    }
+    try {
+      const buf = await fetchBuffer(url, opts.timeoutMs);
+      const sha = crypto.createHash("sha256").update(buf).digest("hex");
+      if (info.upstream_sha256_at_pin && sha !== info.upstream_sha256_at_pin) {
+        findings.push({
+          name,
+          ok: false,
+          reason:
+            `upstream sha mismatch: recorded ${String(info.upstream_sha256_at_pin).slice(0, 12)}…, ` +
+            `live ${sha.slice(0, 12)}…`,
+          url,
+        });
+      } else {
+        findings.push({ name, ok: true, sha, url });
+      }
+    } catch (e) {
+      findings.push({ name, ok: false, reason: `fetch failed: ${e.message}`, url });
+    }
+  }
+
+  const failed = findings.filter((f) => !f.ok);
+  if (opts.json) {
+    process.stdout.write(JSON.stringify({ ok: failed.length === 0, findings }, null, 2) + "\n");
+  } else {
+    for (const f of findings) {
+      if (f.ok) process.stdout.write(`PASS  ${f.name}  ${f.sha.slice(0, 12)}…\n`);
+      else process.stdout.write(`FAIL  ${f.name}  ${f.reason}\n`);
+    }
+    process.stdout.write(
+      `\n${findings.length - failed.length}/${findings.length} vendored files match upstream pin.\n`
+    );
+  }
+  process.exitCode = failed.length === 0 ? 0 : 1;
+}
+
+if (require.main === module) {
+  main().catch((e) => {
+    process.stderr.write(`runtime error: ${e.message}\n`);
+    process.exitCode = 2;
+  });
+}
+
+module.exports = { rawUrlForPin, fetchBuffer };

package/scripts/verify-shipped-tarball.js

@@ -18,6 +18,20 @@
  * The bug was invisible because CI's verify ran against the SOURCE tree,
  * not the shipped tarball. This gate closes that gap.
  *
+ * Audit G:
+ *   F9  — After the first-pass extraction (using the source-tree parseTar),
+ *         re-parse the tarball using the parseTar shipped INSIDE the
+ *         extracted tree itself. If the two parses disagree, fail with a
+ *         structured error. Catches the class where the shipped parser
+ *         silently rejects entries the source parser accepts (or vice
+ *         versa), which would mean operators run a different extractor
+ *         than CI exercised.
+ *   F15 — Invoke `npm pack --offline` so the gate cannot be blocked by
+ *         registry reachability problems during predeploy.
+ *   F4  — Cross-check the extracted public.pem against
+ *         keys/EXPECTED_FINGERPRINT (warn-and-continue when missing, fail
+ *         when present-but-mismatched and KEYS_ROTATED != 1).
+ *
  * Exit codes:
  *   0  verify passed against the packed tarball
  *   1  verify failed against the packed tarball (the bug class above)
@@ -31,6 +45,19 @@ const path = require("path");
 const os = require("os");
 const { spawnSync } = require("child_process");
 
+// v0.12.16 (audit I P1-1): mirror the byte-stability normalize() contract
+// from lib/sign.js + lib/verify.js + lib/refresh-network.js. Duplicated
+// (not require'd) to keep this script's dep surface minimal and to ensure
+// a bug in the normalize() implementation in lib/ doesn't simultaneously
+// disable both the source-tree-verify path AND the shipped-tarball-verify
+// gate (we want at least one independent check). ANY change to normalize()
+// in any of these four files must be mirrored in all of them.
+function normalizeSkillBytes(buf) {
+  let s = Buffer.isBuffer(buf) ? buf.toString("utf8") : String(buf);
+  if (s.length > 0 && s.charCodeAt(0) === 0xFEFF) s = s.slice(1);
+  return Buffer.from(s.replace(/\r\n/g, "\n"), "utf8");
+}
+
 const ROOT = path.resolve(__dirname, "..");
 
 function emit(msg) { process.stdout.write(`[verify-shipped-tarball] ${msg}\n`); }
@@ -42,7 +69,10 @@ function fail(msg, code = 1) {
 const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "verify-shipped-"));
 try {
   emit(`packing into ${tmpRoot} ...`);
-  const pack = spawnSync("npm", ["pack", "--pack-destination", tmpRoot], {
+  // F15 — pass --offline. Predeploy must run without registry
+  // reachability; `npm pack` does not need the network for a local
+  // package and forcing offline mode hard-locks the assumption.
+  const pack = spawnSync("npm", ["pack", "--offline", "--pack-destination", tmpRoot], {
     cwd: ROOT,
     encoding: "utf8",
     shell: process.platform === "win32",
@@ -60,10 +90,10 @@ try {
   const extractDir = path.join(tmpRoot, "extract");
   fs.mkdirSync(extractDir, { recursive: true });
   const zlib = require("zlib");
-  const { parseTar } = require(path.join(ROOT, "lib", "refresh-network.js"));
+  const { parseTar: parseTarSource } = require(path.join(ROOT, "lib", "refresh-network.js"));
   const tgz = fs.readFileSync(tarballPath);
   const tarBuf = zlib.gunzipSync(tgz);
-  const entries = parseTar(tarBuf);
+  const entries = parseTarSource(tarBuf);
   for (const e of entries) {
     if (!e.name) continue;
     const dst = path.join(extractDir, e.name);
@@ -77,6 +107,65 @@ try {
   }
   emit(`extracted to ${pkgRoot}`);
 
+  // Audit G F9 — load the extracted tree's OWN parseTar and re-parse the
+  // tarball. If the two parsers diverge on entry list or content, the
+  // gate trips: this means CI exercised a different parser than operators
+  // will. Defense against drift between source and shipped tarball when
+  // someone edits lib/refresh-network.js without re-vendoring or vice
+  // versa.
+  const shippedParserPath = path.join(pkgRoot, "lib", "refresh-network.js");
+  if (!fs.existsSync(shippedParserPath)) {
+    fail(`extracted tree missing lib/refresh-network.js (cannot run F9 cross-parse check)`, 2);
+  }
+  let parseTarShipped;
+  try {
+    parseTarShipped = require(shippedParserPath).parseTar;
+  } catch (e) {
+    fail(`failed to load extracted parseTar: ${e.message}`, 2);
+  }
+  if (typeof parseTarShipped !== "function") {
+    fail(`extracted lib/refresh-network.js does not export parseTar`, 2);
+  }
+  const shippedEntries = parseTarShipped(tarBuf);
+  // Compare counts first — fast bailout.
+  const divergences = [];
+  if (shippedEntries.length !== entries.length) {
+    divergences.push(
+      `entry count divergence: source-tree parser produced ${entries.length}, ` +
+      `shipped parser produced ${shippedEntries.length}`
+    );
+  } else {
+    // Walk in parallel; tarball entry order is deterministic so positional
+    // compare is correct. Compare name + byte length + body bytes.
+    for (let i = 0; i < entries.length; i++) {
+      const a = entries[i];
+      const b = shippedEntries[i];
+      if (a.name !== b.name) {
+        divergences.push(`entry[${i}] name mismatch: source=${a.name} shipped=${b.name}`);
+        continue;
+      }
+      const aBuf = Buffer.isBuffer(a.body) ? a.body : Buffer.from(a.body);
+      const bBuf = Buffer.isBuffer(b.body) ? b.body : Buffer.from(b.body);
+      if (aBuf.length !== bBuf.length || !aBuf.equals(bBuf)) {
+        divergences.push(
+          `entry[${i}] (${a.name}) body bytes differ between source-tree and shipped parser ` +
+          `(source ${aBuf.length} bytes vs shipped ${bBuf.length} bytes)`
+        );
+      }
+    }
+  }
+  if (divergences.length > 0) {
+    emit(`*** F9: parseTar divergence between source-tree and shipped tree ***`);
+    for (const d of divergences.slice(0, 5)) emit(`  - ${d}`);
+    if (divergences.length > 5) emit(`  ... and ${divergences.length - 5} more`);
+    fail(
+      `parseTar implementations diverge between source tree and shipped tarball. ` +
+      `Operators will run a different extractor than CI exercised. Refusing to publish.`,
+      1
+    );
+  }
+  emit(`F9: source-tree and shipped parseTar agree on ${entries.length} entries`);
+
   // Run the verifier inline against the extracted package tree. This avoids
   // having to spawn a separate process whose cwd resolution differs across
   // platforms.
@@ -108,6 +197,33 @@ try {
     emit(`*** Something between sign and pack is swapping the key. Verify will fail below. ***`);
   }
 
+  // Audit G F4 — key-pin cross-check against the EXTRACTED tree. The pin
+  // is consumed from keys/EXPECTED_FINGERPRINT in the extracted package —
+  // that's the file operators will actually receive on `npm install`.
+  // Warn when absent, fail when present-but-mismatched (unless KEYS_ROTATED).
+  const expectedFpPath = path.join(pkgRoot, "keys", "EXPECTED_FINGERPRINT");
+  if (fs.existsSync(expectedFpPath)) {
+    const raw = fs.readFileSync(expectedFpPath, "utf8").trim();
+    const firstLine = raw.split(/\r?\n/).map((l) => l.trim()).find((l) => l.length > 0) || "";
+    const liveFpLine = `SHA256:${pubFp}`;
+    if (firstLine !== liveFpLine) {
+      if (process.env.KEYS_ROTATED === "1") {
+        emit(`WARN: extracted public.pem fingerprint ${liveFpLine} differs from pin ${firstLine}; KEYS_ROTATED=1 accepted`);
+      } else {
+        fail(
+          `keys/EXPECTED_FINGERPRINT (${firstLine}) does not match the extracted ` +
+          `public.pem fingerprint (${liveFpLine}). If this is an intentional rotation ` +
+          `set KEYS_ROTATED=1 and commit the new pin.`,
+          1
+        );
+      }
+    } else {
+      emit(`F4: key pin verified — ${liveFpLine} matches keys/EXPECTED_FINGERPRINT`);
+    }
+  } else {
+    emit(`WARN: keys/EXPECTED_FINGERPRINT not in extracted tree — key-pin check skipped`);
+  }
+
   let pass = 0, miss = 0, fail_count = 0;
   const failures = [];
   for (const s of (manifest.skills || [])) {
@@ -118,22 +234,38 @@ try {
       failures.push(`${s.name}: file not found at ${s.path}`);
       continue;
     }
-    const content = fs.readFileSync(skillPath);
-    const ok = crypto.verify(null, content, pubKey, Buffer.from(s.signature, "base64"));
+    // v0.12.16 (audit I P1-1): the prior code passed the raw file bytes
+    // directly to crypto.verify. lib/sign.js + lib/verify.js both NORMALIZE
+    // bytes (strip UTF-8 BOM, convert CRLF -> LF) before sign/verify, per
+    // the byte-stability contract in lib/verify.js's normalize() header.
+    // Without the same normalization here, this gate (which was added
+    // specifically to catch the v0.11.x signature regression class!) would
+    // itself report 0/38 on any tree where line-ending normalization
+    // touched the source between sign and pack — a Windows contributor
+    // with `core.autocrlf=true`, or a tool like Prettier between sign and
+    // pack. CLAUDE.md flags this as the recurring CRLF-bypass class.
+    const rawContent = fs.readFileSync(skillPath);
+    const normalizedContent = normalizeSkillBytes(rawContent);
+    const ok = crypto.verify(null, normalizedContent, pubKey, Buffer.from(s.signature, "base64"));
     if (ok) pass++;
     else {
       fail_count++;
       // Forensic detail: log size + sha256 of tarball-extracted content vs source-tree content
       // so we can pinpoint which bytes changed between npm pack and what was signed.
-      const tarSha = crypto.createHash("sha256").update(content).digest("hex").slice(0, 16);
+      // v0.12.16: forensic logging uses rawContent (pre-normalization
+      // bytes) so an operator inspecting failures sees the actual on-disk
+      // shape, but tarSha is computed over the NORMALIZED bytes that
+      // were actually fed to crypto.verify — making the comparison to
+      // sign-time bytes meaningful.
+      const tarSha = crypto.createHash("sha256").update(normalizedContent).digest("hex").slice(0, 16);
       let srcSha = "<missing>", srcSize = 0, srcContent;
       if (fs.existsSync(sourceSkillPath)) {
         srcContent = fs.readFileSync(sourceSkillPath);
         srcSize = srcContent.length;
-        srcSha = crypto.createHash("sha256").update(srcContent).digest("hex").slice(0, 16);
+        srcSha = crypto.createHash("sha256").update(normalizeSkillBytes(srcContent)).digest("hex").slice(0, 16);
       }
-      const equal = srcContent && content.equals(srcContent) ? "equal" : "DIFFER";
-      failures.push(`${s.name}: signature did not verify (tarball size=${content.length} sha=${tarSha}; source size=${srcSize} sha=${srcSha}; bytes ${equal})`);
+      const equal = srcContent && rawContent.equals(srcContent) ? "equal" : "DIFFER";
+      failures.push(`${s.name}: signature did not verify (tarball size=${rawContent.length} sha-normalized=${tarSha}; source size=${srcSize} sha-normalized=${srcSha}; raw bytes ${equal})`);
     }
   }