@blamejs/exceptd-skills 0.19.0 → 0.19.2

package/scripts/builders/catalog-summaries.js

@@ -18,7 +18,7 @@ const path = require("path");
 const CATALOG_PURPOSES = {
   "cve-catalog.json": "Per-CVE record (CVSS, EPSS, CISA KEV, RWEP, AI-discovery, vendor advisories, framework gaps, ATLAS/ATT&CK mappings). Cross-validated against NVD + CISA KEV + FIRST EPSS via validate-cves.",
   "cwe-catalog.json": "MITRE CWE entries used by the project (subset with skill citations), with severity hint and category. Pinned to a CWE catalog version.",
-  "atlas-ttps.json": "MITRE ATLAS TTPs (AML.T0xxx) cited by skills, with tactic, name, description. Pinned to ATLAS v2026.06 (May 2026).",
+  "atlas-ttps.json": "MITRE ATLAS TTPs (AML.T0xxx) cited by skills, with tactic, name, description. Pinned to ATLAS v2026.07 (May 2026).",
   "d3fend-catalog.json": "MITRE D3FEND countermeasures (D3-xxx) keyed by id, with tactic + name. Pinned to D3FEND v1.3.0 release.",
   "framework-control-gaps.json": "Per-control framework gap declarations: SI-2, A.8.8, PCI 6.3.3, etc. Each entry names the control, the lag, the evidence CVE, and remediation guidance.",
   "global-frameworks.json": "Multi-jurisdiction framework registry: per-jurisdiction applicable frameworks × patch_sla / notification_sla / critical_controls / framework_gaps (jurisdiction count is reported by entry_count, not duplicated here). Cross-cutting authority for jurisdiction-clocks index.",

package/scripts/builders/recipes.js

@@ -21,7 +21,7 @@ const RECIPES = [
     when_to_use: "Before scoping or executing a red-team engagement against a model, agentic system, or AI feature.",
     typical_jurisdictions: ["US", "EU", "UK", "GLOBAL"],
     steps: [
-      { skill: "ai-attack-surface", why: "Comprehensive attack-surface inventory mapped to ATLAS v2026.06 with gap flags." },
+      { skill: "ai-attack-surface", why: "Comprehensive attack-surface inventory mapped to ATLAS v2026.07 with gap flags." },
       { skill: "ai-c2-detection", why: "Detection coverage for AI-as-C2 (PROMPTFLUX / SesameOp / AI-API egress) before testing." },
       { skill: "mcp-agent-trust", why: "MCP server trust boundary for the engineering toolchain side of the surface." },
       { skill: "rag-pipeline-security", why: "RAG ingestion provenance + prompt-injection chain coverage." },

package/scripts/check-epss-consistency.js

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * EPSS score/percentile consistency gate.
+ *
+ * EPSS publishes a score and a percentile for every CVE, refreshed daily. The
+ * percentile is the score's RANK within that day's publication: if A scores
+ * higher than B on a given day, A's percentile is at least B's. That makes the
+ * pair self-checking with no network access — sort a day's entries by score and
+ * the percentiles must come out sorted too.
+ *
+ * The failure this catches is updating one field without the other. A refresh
+ * that writes a new score but keeps yesterday's percentile leaves a plausible
+ * entry: both numbers are in range, both look like EPSS values, and nothing
+ * downstream can tell they describe different days. The result is a CVE ranked
+ * as top-decile urgency on a score that no longer supports it, which is exactly
+ * the input the prioritisation model trusts most.
+ *
+ * What the ordering check does and does not establish. Monotonicity is a
+ * necessary condition, not a sufficient one: it catches a stale percentile that
+ * contradicts the new score's rank, which is what a partial refresh usually
+ * produces, but a stale value that happens to preserve the ordering passes.
+ * Proving two fields share a publication would require the fetched row, and
+ * that is not recoverable from the catalog offline. So this is a corruption
+ * detector, not a provenance proof — the provenance guarantee has to come from
+ * the write side, by fetching and writing score, percentile and date together.
+ *
+ * Three checks run:
+ *   - within each epss_date, sorting by score must sort by percentile;
+ *   - an entry carries both numeric fields or neither;
+ *   - epss_note, which is derived text, must restate the current fields.
+ *
+ * Entries are grouped by epss_date so each publication is checked against
+ * itself; comparing across days is meaningless because the whole distribution
+ * shifts.
+ *
+ * Exit codes: 0 consistent, 1 inconsistent.
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const ROOT = path.resolve(__dirname, "..");
+
+/**
+ * Percentiles are published rounded to five decimals, so two scores that are
+ * adjacent in the ranking can round to percentiles that invert by a hair. That
+ * is arithmetic, not drift. Real mismatches are pairs pulled from different
+ * days, which land orders of magnitude above this: the widest rounding artifact
+ * observed in the catalog is 8e-5, while a stale-field mismatch runs 0.05-0.9.
+ * The threshold sits between the two, far enough from each that neither
+ * classification is a close call.
+ */
+const ROUNDING_TOLERANCE = 1e-3;
+
+function loadCatalog(file) {
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+function ordinal(n) {
+  const suffixes = ["th", "st", "nd", "rd"];
+  const v = n % 100;
+  return `${n}${suffixes[(v - 20) % 10] || suffixes[v] || suffixes[0]}`;
+}
+
+/**
+ * The operator-readable restatement of an entry's EPSS fields. Entries carry it
+ * as `epss_note`, and it is derived, not authored — so it must be rebuilt
+ * whenever the numbers move.
+ */
+function renderNote(entry) {
+  const pct = Math.round(entry.epss_percentile * 100);
+  return `FIRST EPSS ${entry.epss_score} (${ordinal(pct)} percentile) as of ${entry.epss_date}.`;
+}
+
+/**
+ * Group entries by publication date. Entries missing either field are reported
+ * separately rather than skipped — a half-populated pair is its own defect, and
+ * silently ignoring it would let the gate pass on the very shape it exists to
+ * catch.
+ */
+function cohorts(catalog) {
+  const groups = new Map();
+  const incomplete = [];
+
+  for (const [id, entry] of Object.entries(catalog)) {
+    const hasScore = typeof entry.epss_score === "number";
+    const hasPercentile = typeof entry.epss_percentile === "number";
+
+    if (!hasScore && !hasPercentile) continue;
+    if (!hasScore || !hasPercentile) {
+      incomplete.push({
+        id,
+        missing: hasScore ? "epss_percentile" : "epss_score",
+      });
+      continue;
+    }
+
+    const date = entry.epss_date || "(no epss_date)";
+    if (!groups.has(date)) groups.set(date, []);
+    groups.get(date).push({ id, score: entry.epss_score, percentile: entry.epss_percentile });
+  }
+
+  return { groups, incomplete };
+}
+
+/**
+ * Sort a cohort by score and report every place the percentile goes backwards
+ * by more than rounding can explain.
+ */
+function inversions(rows) {
+  const sorted = [...rows].sort((a, b) => a.score - b.score);
+  const found = [];
+
+  for (let i = 1; i < sorted.length; i++) {
+    const prev = sorted[i - 1];
+    const cur = sorted[i];
+    const delta = prev.percentile - cur.percentile;
+    if (delta > ROUNDING_TOLERANCE) {
+      found.push({ lower: cur, higher: prev, delta });
+    }
+  }
+
+  return found;
+}
+
+function check(catalogFile) {
+  const catalog = loadCatalog(catalogFile);
+  const { groups, incomplete } = cohorts(catalog);
+  const failures = [];
+
+  for (const [date, rows] of groups) {
+    for (const bad of inversions(rows)) {
+      failures.push(
+        `${date}: ${bad.lower.id} scores ${bad.lower.score} but ranks ` +
+          `${bad.lower.percentile}, below ${bad.higher.id} which scores ` +
+          `${bad.higher.score} at ${bad.higher.percentile} ` +
+          `(gap ${bad.delta.toFixed(5)}) — the two fields are from different publications`
+      );
+    }
+  }
+
+  for (const row of incomplete) {
+    failures.push(`${row.id}: has one EPSS field but not ${row.missing} — write both together or neither`);
+  }
+
+  // The prose restatement drifts the same way the percentile does: a refresh
+  // moves the numbers and leaves the sentence describing the previous
+  // publication, so the entry states two different scores as of two different
+  // dates. It is derived text, so it can be checked exactly.
+  for (const [id, entry] of Object.entries(catalog)) {
+    if (typeof entry.epss_note !== "string") continue;
+    if (typeof entry.epss_score !== "number" || typeof entry.epss_percentile !== "number") continue;
+    const expected = renderNote(entry);
+    if (entry.epss_note !== expected) {
+      failures.push(
+        `${id}: epss_note reads ${JSON.stringify(entry.epss_note)} but the fields say ` +
+          `${JSON.stringify(expected)} — regenerate the note when the numbers move`
+      );
+    }
+  }
+
+  return { failures, cohortCount: groups.size, entryCount: [...groups.values()].reduce((n, r) => n + r.length, 0) };
+}
+
+function main() {
+  const file = process.argv[2] || path.join(ROOT, "data", "cve-catalog.json");
+  const { failures, cohortCount, entryCount } = check(file);
+
+  if (failures.length) {
+    console.error("EPSS consistency: FAIL");
+    for (const f of failures) console.error(`  ${f}`);
+    console.error(
+      `\n${failures.length} inconsistent ${failures.length === 1 ? "entry" : "entries"}. ` +
+        `Re-fetch score and percentile together from api.first.org and write them in one pass.`
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log(
+    `EPSS consistency: PASS — ${entryCount} entries across ${cohortCount} publication ${cohortCount === 1 ? "date" : "dates"}, every cohort ranks monotonically`
+  );
+}
+
+if (require.main === module) main();
+
+module.exports = { check, cohorts, inversions, renderNote, ROUNDING_TOLERANCE };

package/scripts/check-ttp-references.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * TTP reference-integrity gate.
+ *
+ * data/attack-techniques.json and data/atlas-ttps.json are the pinned copies of
+ * ATT&CK and ATLAS. Every other file that names a technique — countermeasure
+ * maps, DLP controls, playbooks, skill bodies, CVE entries — is referring INTO
+ * those two catalogs. This gate proves those references resolve.
+ *
+ * The failure it exists for: MITRE retires and renumbers techniques between
+ * releases. When a pin is bumped, the two source catalogs get remapped, but
+ * references living in other files are easy to miss — nothing dereferences them
+ * at runtime, so a stale id keeps rendering in operator output as if it were
+ * current. It points at a MITRE page that no longer resolves, and any control
+ * claiming to counter it is now mapped to nothing (AGENTS.md Hard Rule #4: no
+ * orphaned controls). A bumped pin left exactly this residue in the D3FEND and
+ * DLP maps, invisible to every other gate.
+ *
+ * The check is offline: it resolves references against the pinned catalogs, not
+ * against MITRE. That is deliberate — scripts/check-ttp-upstream.js is the
+ * network check that asks whether the PINS are current, and it cannot block a
+ * release because it needs connectivity. This one can block, because a
+ * reference that does not resolve against the pin we ship is broken no matter
+ * what upstream says.
+ *
+ * Exit codes: 0 all references resolve, 1 unresolved references found.
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const ROOT = path.resolve(__dirname, "..");
+
+/**
+ * ATT&CK ids are TNNNN[.NNN]; ATLAS ids are AML.TNNNN[.NNN]. The lookbehind
+ * matters: without it the ATT&CK alternative matches the "T0017" inside
+ * "AML.T0017" and reports a phantom bare-ATT&CK reference for every ATLAS id in
+ * the tree. It covers the hyphen as well, because ATLAS ids also appear in
+ * filenames, where the dot is not a legal separator.
+ */
+const TTP_PATTERN = /\bAML\.T\d{4}(?:\.\d{3})?\b|(?<!AML[.-])\bT\d{4}(?:\.\d{3})?\b/g;
+
+/** Files whose ids are definitions, not references. */
+const SOURCE_CATALOGS = ["data/attack-techniques.json", "data/atlas-ttps.json"];
+
+const SEARCH_ROOTS = ["data", "playbooks", "skills", "lib", "orchestrator", "bin"];
+const SEARCH_EXTS = new Set([".json", ".md", ".js"]);
+const SKIP_DIRS = new Set(["node_modules", "_indexes", "vendor", ".git"]);
+
+/**
+ * Tokens that match the pattern without being references to a technique.
+ * Every entry needs a reason: an unexplained allowlist is how a real stale id
+ * eventually gets parked here to make the gate green.
+ */
+const NOT_REFERENCES = [
+  {
+    id: "T1234",
+    file: "lib/gap-detectors.js",
+    why: "placeholder in a comment describing the reference-extraction pattern itself, not a claim about a technique",
+  },
+];
+
+function loadKnownIds() {
+  const known = new Set();
+  for (const rel of SOURCE_CATALOGS) {
+    const catalog = JSON.parse(fs.readFileSync(path.join(ROOT, rel), "utf8"));
+    for (const key of Object.keys(catalog)) {
+      if (key !== "_meta") known.add(key);
+    }
+  }
+  return known;
+}
+
+function* walk(dir) {
+  let names;
+  try {
+    names = fs.readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const name of names) {
+    if (SKIP_DIRS.has(name)) continue;
+    const full = path.join(dir, name);
+    let stat;
+    try {
+      stat = fs.statSync(full);
+    } catch {
+      continue;
+    }
+    if (stat.isDirectory()) {
+      yield* walk(full);
+    } else if (SEARCH_EXTS.has(path.extname(name))) {
+      yield full;
+    }
+  }
+}
+
+function allowed(id, rel) {
+  return NOT_REFERENCES.some((e) => e.id === id && e.file === rel);
+}
+
+function scan(root = ROOT) {
+  const known = loadKnownIds();
+  const sources = new Set(SOURCE_CATALOGS);
+  const unresolved = new Map();
+
+  for (const dirName of SEARCH_ROOTS) {
+    const dir = path.join(root, dirName);
+    if (!fs.existsSync(dir)) continue;
+
+    for (const file of walk(dir)) {
+      const rel = path.relative(root, file).replace(/\\/g, "/");
+      if (sources.has(rel)) continue;
+
+      const text = fs.readFileSync(file, "utf8");
+      for (const id of text.match(TTP_PATTERN) || []) {
+        if (known.has(id) || allowed(id, rel)) continue;
+        if (!unresolved.has(id)) unresolved.set(id, new Set());
+        unresolved.get(id).add(rel);
+      }
+    }
+  }
+
+  return { unresolved, knownCount: known.size };
+}
+
+function main() {
+  const { unresolved, knownCount } = scan();
+
+  if (unresolved.size) {
+    console.error("TTP reference integrity: FAIL");
+    for (const [id, files] of [...unresolved].sort((a, b) => a[0].localeCompare(b[0]))) {
+      console.error(`  ${id} — not defined in the pinned catalogs`);
+      for (const f of [...files].sort()) console.error(`      ${f}`);
+    }
+    console.error(
+      `\n${unresolved.size} unresolved ${unresolved.size === 1 ? "reference" : "references"}. ` +
+        `Either the id was retired upstream and these files still name it — repoint them at the ` +
+        `successor — or it is a technique the pinned catalogs do not carry yet, in which case import it.`
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log(`TTP reference integrity: PASS — every referenced technique resolves against the ${knownCount} pinned ids`);
+}
+
+if (require.main === module) main();
+
+module.exports = { scan, TTP_PATTERN, NOT_REFERENCES, loadKnownIds };

package/scripts/check-ttp-upstream.js

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * scripts/check-ttp-upstream.js — validates every shipped TTP id against the
+ * pinned upstream release.
+ *
+ * Why this exists. The catalogs in data/attack-techniques.json and
+ * data/atlas-ttps.json are curated mirrors of MITRE releases, and nothing
+ * checked that the ids in them are ids MITRE actually publishes. The ATLAS
+ * 2026.07 / ATT&CK 19.2 pin bump found eleven that were not: five ATT&CK
+ * techniques revoked upstream — already revoked in 19.1, the version pinned at
+ * the time, so they had been shipping revoked for a full release cycle — and
+ * six that appear in no upstream domain at any version. Every one of them was
+ * reachable by a skill telling an operator to map a finding to it, which is
+ * exactly what Hard Rule #4 (no orphaned controls — every control maps to a
+ * real TTP) exists to prevent.
+ *
+ * This is a NETWORK check, so it runs in the refresh workflow beside the pin
+ * checker rather than in predeploy, which is offline. Report-only: it prints
+ * findings and exits non-zero, leaving the decision to a maintainer, because a
+ * revocation needs a judgement call about the successor rather than an
+ * automatic rewrite.
+ *
+ *   node scripts/check-ttp-upstream.js            validate against the pins
+ *   node scripts/check-ttp-upstream.js --json     machine-readable output
+ *
+ * Exit: 0 clean, 1 findings, 2 upstream unreachable (never a silent pass —
+ * an unreachable upstream must not read as "all ids valid").
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const ROOT = path.resolve(__dirname, "..");
+const UA = "exceptd-ttp-validator (+https://exceptd.com)";
+const ATTACK_DOMAINS = ["enterprise-attack", "ics-attack", "mobile-attack"];
+
+function readJson(p) {
+  return JSON.parse(fs.readFileSync(path.join(ROOT, p), "utf8"));
+}
+
+/**
+ * A pinned version read out of a catalog is file data, and it is about to be
+ * interpolated into an upstream URL. Constrain it to the exact shape each
+ * project publishes before it can reach a request, so a malformed or tampered
+ * `_meta` cannot steer the fetch — and so a typo'd pin fails here with a clear
+ * message instead of as a puzzling 404 later.
+ *
+ *   ATT&CK  semver-ish major.minor           19.2
+ *   ATLAS   CalVer YYYY.MM with optional .N  2026.07, 2025.11.2
+ */
+const VERSION_SHAPES = {
+  attack: /^\d{1,3}\.\d{1,3}$/,
+  atlas: /^\d{4}\.\d{2}(\.\d{1,2})?$/,
+};
+
+function assertPinShape(kind, value) {
+  if (typeof value !== "string" || !VERSION_SHAPES[kind].test(value)) {
+    throw new Error(
+      `${kind} pin ${JSON.stringify(value)} does not match ${VERSION_SHAPES[kind]} — ` +
+        `refusing to build an upstream URL from it`
+    );
+  }
+  return value;
+}
+
+async function fetchJson(url) {
+  const res = await fetch(url, { headers: { "user-agent": UA } });
+  if (!res.ok) throw new Error(`${res.status} ${url}`);
+  return JSON.parse(await res.text());
+}
+
+async function fetchText(url) {
+  const res = await fetch(url, { headers: { "user-agent": UA } });
+  if (!res.ok) throw new Error(`${res.status} ${url}`);
+  return res.text();
+}
+
+/** Every ATT&CK technique id in the pinned release, with its revocation state. */
+async function liveAttack(rawVersion) {
+  const version = encodeURIComponent(assertPinShape("attack", rawVersion));
+  const out = new Map();
+  for (const dom of ATTACK_DOMAINS) {
+    const j = await fetchJson(
+      `https://raw.githubusercontent.com/mitre-attack/attack-stix-data/v${version}/${dom}/${dom}.json`
+    );
+    const byId = new Map(j.objects.map((o) => [o.id, o]));
+    for (const o of j.objects) {
+      if (o.type !== "attack-pattern") continue;
+      const ext = (o.external_references || []).find(
+        (r) => r.source_name && r.source_name.includes("attack")
+      );
+      if (!ext || !ext.external_id) continue;
+      let supersededBy = null;
+      if (o.revoked) {
+        const rel = j.objects.find(
+          (r) => r.type === "relationship" && r.relationship_type === "revoked-by" && r.source_ref === o.id
+        );
+        const tgt = rel && byId.get(rel.target_ref);
+        const te = tgt && (tgt.external_references || []).find(
+          (r) => r.source_name && r.source_name.includes("attack")
+        );
+        supersededBy = te ? te.external_id : null;
+      }
+      out.set(ext.external_id, {
+        revoked: !!o.revoked,
+        deprecated: !!o.x_mitre_deprecated,
+        supersededBy,
+        name: o.name,
+      });
+    }
+  }
+  return out;
+}
+
+/** Every ATLAS id in the pinned content release. */
+async function liveAtlas(rawVersion) {
+  const version = encodeURIComponent(assertPinShape("atlas", rawVersion));
+  const yaml = await fetchText(
+    `https://raw.githubusercontent.com/mitre-atlas/atlas-data/v${version}/dist/v6/ATLAS-${version}.yaml`
+  );
+  // The dist bundle is a mapping keyed by id, each block repeating `id:`.
+  return new Set(
+    (yaml.match(/^\s*id:\s*(AML\.[A-Za-z]+[0-9.]*)\s*$/gm) || []).map((l) =>
+      l.replace(/.*id:\s*/, "").trim()
+    )
+  );
+}
+
+async function main() {
+  const asJson = process.argv.includes("--json");
+  const attackCat = readJson("data/attack-techniques.json");
+  const atlasCat = readJson("data/atlas-ttps.json");
+  const attackVersion = attackCat._meta.attack_version;
+  const atlasVersion = atlasCat._meta.atlas_version;
+
+  let attack;
+  let atlas;
+  try {
+    [attack, atlas] = await Promise.all([liveAttack(attackVersion), liveAtlas(atlasVersion)]);
+  } catch (err) {
+    process.stderr.write(
+      `[check-ttp-upstream] UNREACHABLE — could not fetch upstream (${err.message}). ` +
+        `Not treating this as a pass: an unreachable upstream proves nothing about the shipped ids.\n`
+    );
+    process.exitCode = 2;
+    return;
+  }
+
+  if (attack.size === 0 || atlas.size === 0) {
+    process.stderr.write("[check-ttp-upstream] UNREACHABLE — upstream returned an empty id set.\n");
+    process.exitCode = 2;
+    return;
+  }
+
+  const findings = [];
+  for (const id of Object.keys(attackCat)) {
+    if (id === "_meta") continue;
+    const live = attack.get(id);
+    if (!live) {
+      findings.push({ catalog: "attack", id, issue: "absent-upstream", detail: `not published in ATT&CK v${attackVersion} in any domain` });
+    } else if (live.revoked) {
+      findings.push({ catalog: "attack", id, issue: "revoked", detail: `revoked upstream${live.supersededBy ? ` — superseded by ${live.supersededBy}` : ""}` });
+    } else if (live.deprecated) {
+      findings.push({ catalog: "attack", id, issue: "deprecated", detail: "deprecated upstream" });
+    }
+  }
+  for (const id of Object.keys(atlasCat)) {
+    if (id === "_meta") continue;
+    if (!atlas.has(id)) {
+      findings.push({ catalog: "atlas", id, issue: "absent-upstream", detail: `not published in ATLAS v${atlasVersion}` });
+    }
+  }
+
+  if (asJson) {
+    process.stdout.write(JSON.stringify({ attackVersion, atlasVersion, findings }, null, 2) + "\n");
+  } else {
+    process.stdout.write(
+      `[check-ttp-upstream] ATT&CK v${attackVersion} (${attack.size} live ids) · ATLAS v${atlasVersion} (${atlas.size} live ids)\n`
+    );
+    if (findings.length === 0) {
+      process.stdout.write("[check-ttp-upstream] ok — every shipped TTP id exists upstream and is neither revoked nor deprecated.\n");
+    } else {
+      for (const f of findings) {
+        process.stdout.write(`  ✗ ${f.catalog} ${f.id}: ${f.detail}\n`);
+      }
+      process.stdout.write(
+        `[check-ttp-upstream] ${findings.length} finding(s). A revocation needs a maintainer decision on the ` +
+          `successor — remap the id and carry its cve_refs across rather than deleting the entry.\n`
+      );
+    }
+  }
+  process.exitCode = findings.length ? 1 : 0;
+}
+
+if (require.main === module) main().catch((err) => {
+  process.stderr.write(`[check-ttp-upstream] ERROR ${err && err.stack ? err.stack : err}\n`);
+  process.exitCode = 2;
+});
+
+module.exports = { VERSION_SHAPES, assertPinShape };

package/scripts/check-version-tags.js

@@ -104,18 +104,32 @@ const COMMENT_EXEMPT = new Set([
 // need to name individual local-only files. Untracked-but-NOT-ignored files
 // ARE still scanned: a new file a contributor is about to commit is exactly
 // what the gate must catch. Computed via `git check-ignore` over the walked set.
+// Returns the ignored subset, or NULL when git cannot answer.
+//
+// "No path matched" and "the question could not be asked" are different
+// results and must not collapse into the same empty set. Without a repository
+// — a build context that omits .git/, or git not installed — an empty set
+// silently reclassifies every local-only file as part of the shipped surface,
+// so the gate reports violations in files a clone never contains. Returning
+// null lets the caller say it could not determine the surface instead of
+// asserting a wrong one.
 function gitIgnoredSet(relPaths) {
   if (!relPaths.length) return new Set();
   try {
     const out = execFileSync("git", ["check-ignore", "--stdin"], {
       cwd: ROOT, input: relPaths.join("\n"), encoding: "utf8", maxBuffer: 64 * 1024 * 1024,
+      stdio: ["pipe", "pipe", "pipe"],
     });
     return new Set(out.split(/\r?\n/).filter(Boolean));
   } catch (e) {
-    // `git check-ignore --stdin` exits 1 when NO path is ignored (not an
-    // error); any paths it did match are on stdout. Absent that, none ignored.
+    // Exit 1 with no stderr is git's way of saying "no path matched" — a real
+    // answer, and an empty set is correct. Anything else (git missing, not a
+    // repository, .git absent) means the question went unanswered.
+    const status = e && typeof e.status === "number" ? e.status : null;
+    const stderr = e && e.stderr ? String(e.stderr).trim() : "";
     const out = e && e.stdout ? String(e.stdout) : "";
-    return new Set(out.split(/\r?\n/).filter(Boolean));
+    if (status === 1 && !stderr) return new Set(out.split(/\r?\n/).filter(Boolean));
+    return null;
   }
 }
 
@@ -185,12 +199,16 @@ function countLineViolations(rel) {
 function scanCurrent() {
   const files = walk(ROOT);
   const ignored = gitIgnoredSet(files);
+  // Without git the shipped surface is unknowable: local-only files are
+  // indistinguishable from tracked ones, so any result would be a guess.
+  // Report that rather than emit findings the baseline cannot be compared to.
+  if (ignored === null) return { byFile: {}, filenameViolations: [], surfaceUnknown: true };
   const byFile = {};
   const filenameViolations = [];
   for (const rel of files) {
-    // Skip git-ignored, local-only files (a contributor's private working notes
-    // that `git clone` never ships). Untracked-but-not-ignored files are still
-    // scanned — a new file about to be committed is what the gate guards.
+    // Skip git-ignored, local-only files that `git clone` never ships.
+    // Untracked-but-not-ignored files are still scanned — a new file about to
+    // be committed is exactly what the gate guards.
     if (ignored.has(rel)) continue;
     if (FILENAME_VERSION_RE.test(rel)) filenameViolations.push(rel);
     const n = countLineViolations(rel);
@@ -229,6 +247,32 @@ function main() {
   const wantUpdate = process.argv.includes("--update-baseline");
   const current = scanCurrent();
 
+  if (current.surfaceUnknown) {
+    // Never write a baseline from a scan that could not tell shipped files from
+    // local ones — that would bake the wrong surface in permanently.
+    //
+    // Automation is the one place this must not degrade to a skip. This gate
+    // runs inside predeploy, and predeploy guards the publish job, so a
+    // silently-skipped run there stops enforcing on exactly the path that
+    // ships. Locally — a container built without .git, a tarball inspection —
+    // skipping is the honest answer, because the shipped surface genuinely is
+    // not knowable there and failing would only punish the harness.
+    const inAutomation = process.env.CI === "true" || !!process.env.GITHUB_ACTIONS;
+    if (inAutomation) {
+      console.error("[check-version-tags] FAIL — no git repository available, so the shipped");
+      console.error("  surface cannot be determined. In automation this is a failure, not a skip:");
+      console.error("  this gate runs inside predeploy, which guards publishing. Ensure the job");
+      console.error("  checks out git metadata (actions/checkout provides it by default).");
+      process.exitCode = 2;
+      return;
+    }
+    console.error("[check-version-tags] SKIPPED — no git repository available, so the shipped");
+    console.error("  surface cannot be determined. This is not a pass; run it where git metadata");
+    console.error("  is present. In CI the same condition fails instead.");
+    process.exitCode = 0;
+    return;
+  }
+
   if (wantUpdate) {
     writeBaseline(current);
     process.exitCode = 0;