@blamejs/exceptd-skills 0.19.33 → 0.19.34

package/scripts/check-ttp-references.js

@@ -2,30 +2,14 @@
 "use strict";
 
 /**
- * TTP reference-integrity gate.
+ * 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
+ * naming a technique refers into them, and this proves those references resolve.
+ * Resolution runs against the pins, not against MITRE:
+ * scripts/check-ttp-upstream.js is the network check on whether the pins
+ * themselves are current, and it cannot block a release. This one can.
  *
- * 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.
+ * Exit 0 when every reference resolves, 1 when any does not.
  */
 
 const fs = require("node:fs");
@@ -34,11 +18,10 @@ 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.
+ * ATT&CK ids are TNNNN[.NNN]; ATLAS ids are AML.TNNNN[.NNN]. Without the
+ * lookbehind the ATT&CK alternative matches the "T0017" inside "AML.T0017" and
+ * reports a phantom bare-ATT&CK reference for every ATLAS id. It covers the
+ * hyphen too, since ATLAS ids also appear in filenames.
  */
 const TTP_PATTERN = /\bAML\.T\d{4}(?:\.\d{3})?\b|(?<!AML[.-])\bT\d{4}(?:\.\d{3})?\b/g;
 
@@ -50,17 +33,10 @@ 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.
+ * Tokens that match the pattern without referencing a technique. Every entry needs
+ * a reason: an unexplained allowlist is how a real stale id gets parked here.
  */
-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",
-  },
-];
+const NOT_REFERENCES = [];
 
 function loadKnownIds() {
   const known = new Set();

package/scripts/check-ttp-upstream.js

@@ -2,31 +2,11 @@
 "use strict";
 
 /**
- * scripts/check-ttp-upstream.js — validates every shipped TTP id against the
- * pinned upstream release.
+ * Validates every shipped TTP id in data/attack-techniques.json and
+ * data/atlas-ttps.json against the pinned upstream MITRE release. A network
+ * check, so it runs in the refresh workflow rather than in offline predeploy.
  *
- * 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").
+ * Exit 0 clean, 1 findings, 2 upstream unreachable — never a silent pass.
  */
 
 const fs = require("node:fs");
@@ -41,14 +21,8 @@ function readJson(p) {
 }
 
 /**
- * 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
+ * A pin is catalog data interpolated into an upstream URL, so its shape is
+ * bounded here: ATT&CK is major.minor, ATLAS is CalVer YYYY.MM with optional .N.
  */
 const VERSION_SHAPES = {
   attack: /^\d{1,3}\.\d{1,3}$/,
@@ -66,13 +40,8 @@ function assertPinShape(kind, value) {
 }
 
 /**
- * The only hosts this checker may ever contact. `assertPinShape` already bounds
- * the catalog-sourced version to a digit-and-dot shape before it reaches a URL,
- * but that guard sits a long way from the request — a later edit could add a
- * caller that skips it, and static analysis reasonably flags file data reaching
- * an outbound request when the barrier is that distant. Re-check the resolved
- * origin at the sink so the property is enforced where it matters and is
- * verifiable by reading ten lines rather than tracing the whole module.
+ * The only hosts this checker may contact. Re-checked at the sink even though
+ * `assertPinShape` bounds the version, so a later caller cannot route past it.
  */
 const ALLOWED_ORIGINS = new Set(["https://raw.githubusercontent.com"]);
 
@@ -89,7 +58,6 @@ function assertAllowedUrl(rawUrl) {
         `${[...ALLOWED_ORIGINS].join(", ")}`
     );
   }
-  // Reject anything that could smuggle credentials or redirect the path.
   if (parsed.username || parsed.password || parsed.search || parsed.hash) {
     throw new Error(`refusing to fetch a URL carrying credentials or a query/fragment: ${parsed.origin}${parsed.pathname}`);
   }

package/scripts/check-version-bump.js

@@ -2,45 +2,9 @@
 'use strict';
 
 /**
- * scripts/check-version-bump.js — patch-only-cadence predeploy gate.
- *
- * Why this exists. The project cadence is "patch is the only default bump; a
- * minor or major requires explicit human authorization." That rule lived in
- * the contributor guide and in maintainer memory — and was violated anyway
- * (two releases shipped as minors that should have been patches). A written
- * rule the tooling does not enforce is one a tired/automated contributor will
- * eventually skip. This gate makes the rule mechanical: an unauthorized
- * minor/major version bump fails predeploy and cannot ship.
- *
- * Hermetic by design. Authorization is a COMMITTED artifact
- * (tests/.version-bump-ack.json), not an environment variable, because
- * `npm run predeploy` runs in the release.yml validate job as well as locally.
- * An env-var scheme would either false-fail a legitimately-authorized minor in
- * CI or require per-release CI config. A committed ack file travels with the
- * checkout, so the gate enforces identically everywhere — and a minor bump
- * becomes a loud, reviewable line in the PR diff instead of a silent change to
- * a version string.
- *
- * Mechanism:
- *   prev = the most recent OTHER `## X.Y.Z` heading in CHANGELOG.md
- *   cur  = package.json version (== the top CHANGELOG heading; the version-sync
- *          gate enforces that match separately)
- *   classify prev -> cur as patch | minor | major | none | downgrade
- *     - patch / none      -> pass (the default; zero ceremony)
- *     - downgrade / bad   -> fail (versions only move forward)
- *     - minor / major     -> pass ONLY if tests/.version-bump-ack.json names
- *                            the exact `cur` version with the matching type;
- *                            otherwise fail with remediation.
- *
- * To authorize a minor (only after the user explicitly asks for one):
- *   echo '{"version":"0.19.0","type":"minor"}' > tests/.version-bump-ack.json
- * and commit it. The ack is version-specific, so a stale ack cannot authorize
- * a different future bump.
- *
- * Output:
- *   stdout: structured JSON when --json, else a one-line summary
- *   exit 0: patch/none, or an authorized minor/major
- *   exit 1: unauthorized minor/major, downgrade, or unparseable version
+ * Patch-only-cadence gate. A minor or major fails unless the committed
+ * tests/.version-bump-ack.json names that exact version, so an ack travels with
+ * the checkout and a stale one cannot authorize a later bump.
  */
 
 const fs = require('fs');
@@ -57,7 +21,6 @@ function parseSemver(v) {
   return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]) };
 }
 
-// Classify the transition prev -> cur. Pure; exported for unit tests.
 function classifyBump(prev, cur) {
   const a = parseSemver(prev);
   const b = parseSemver(cur);
@@ -68,8 +31,7 @@ function classifyBump(prev, cur) {
   return 'none';
 }
 
-// Decide whether a bump is allowed given the committed ack (or null). Pure;
-// exported for unit tests. ack = { version, type } | null.
+// `ack` is { version, type } or null.
 function checkBump(prev, cur, ack) {
   if (!prev) return { ok: true, bump: 'initial', reason: 'no previous version recorded' };
   const bump = classifyBump(prev, cur);
@@ -82,7 +44,6 @@ function checkBump(prev, cur, ack) {
   if (bump === 'patch' || bump === 'none') {
     return { ok: true, bump, reason: `${bump} bump (${prev} -> ${cur})` };
   }
-  // minor or major — requires explicit committed authorization for this exact version.
   if (ack && ack.version === cur && ack.type === bump) {
     return { ok: true, bump, reason: `${bump} bump authorized for ${cur} via tests/.version-bump-ack.json` };
   }
@@ -93,7 +54,7 @@ function checkBump(prev, cur, ack) {
   };
 }
 
-// Extract `## X.Y.Z` version headings from CHANGELOG.md, in document order.
+// Document order — newest first, which determinePrevious relies on.
 function changelogVersions(text) {
   const out = [];
   const re = /^##\s+(\d+\.\d+\.\d+)\b/gm;
@@ -107,14 +68,8 @@ function suggestPatch(prev) {
   return a ? `${a.major}.${a.minor}.${a.patch + 1}` : null;
 }
 
-// Resolve the previous version from CHANGELOG text, or fail closed. Pure;
-// exported for unit tests. A release gate must NOT treat an unreadable or
-// heading-less CHANGELOG as a "first release" — doing so silently authorized
-// ANY bump (including an unapproved major), because checkBump(null, ...) takes
-// the initial-release pass. `text` is the CHANGELOG contents, or null when the
-// read failed. Returns { ok, prev?, reason? }: ok:false fails the gate; ok:true
-// yields prev, which is null ONLY for a genuine first release whose sole
-// `## X.Y.Z` heading equals cur (versions === [cur]).
+// Fails closed: an unreadable or heading-less CHANGELOG must not look like a
+// first release, because checkBump(null, ...) then authorizes any bump.
 function determinePrevious(text, cur) {
   if (text == null) {
     return { ok: false, reason: 'CHANGELOG.md could not be read' };
@@ -149,12 +104,7 @@ function main() {
   }
   const cur = pkg.version;
 
-  // Fail closed when CHANGELOG is unreadable or carries no version headings.
-  // Swallowing a read error to '' previously made versions=[] -> prev=null ->
-  // checkBump's initial-release pass, so a missing/malformed CHANGELOG silently
-  // authorized any bump. A genuine first release still passes: its sole
-  // `## X.Y.Z` heading equals cur, so determinePrevious returns prev=null with
-  // ok:true and checkBump takes the legitimate initial path.
+  // null on a read failure, never '' — determinePrevious fails closed on null.
   let changelogText = null;
   try { changelogText = fs.readFileSync(CHANGELOG_PATH, 'utf8'); } catch (_e) { changelogText = null; }
   const prevRes = determinePrevious(changelogText, cur);
@@ -163,7 +113,6 @@ function main() {
     process.exitCode = 1;
     return;
   }
-  // prev = the most recent heading that differs from the current version.
   const prev = prevRes.prev;
 
   const ack = readAck();
@@ -191,8 +140,7 @@ function main() {
       if (patch) process.stderr.write(`[check-version-bump] If this should be a patch, set the version to ${patch}.\n`);
       process.stderr.write(`[check-version-bump] If the user explicitly authorized a ${res.bump}, commit tests/.version-bump-ack.json = {"version":"${cur}","type":"${res.bump}"}.\n`);
     }
-    // process.exitCode (not process.exit) so the buffered stdout write above
-    // is not truncated when stdout is piped (the stdout-flush-truncation class).
+    // `process.exitCode`, not process.exit(): exit truncates the buffered stdout write.
     process.exitCode = 1;
     return;
   }

package/scripts/check-version-tags.js

@@ -2,43 +2,11 @@
 "use strict";
 
 /**
- * scripts/check-version-tags.js
- *
- * Refuses NEW version-stamped lines / filenames in the tracked source
- * tree. "Line" is deliberate and broader than "comment": a 0.x version
- * stamp is residue wherever a stranger reads it, which per the
- * operator-facing-surface rules includes string literals that ship to
- * operators — CLI `--help` text, error messages, and test descriptions —
- * not just `//` comments. The scan therefore tests the WHOLE line, so a
- * `version: '0.18.7'` data literal or a `--flag (v0.18.7)` help string
- * counts the same as a `// v0.18.7` comment. Genuinely-load-bearing
- * version references (real test fixtures, deprecation timelines) get the
- * file added to COMMENT_EXEMPT below. The authoritative version surfaces
- * are:
- *
- *   1. package.json / manifest.json `"version"` field
- *   2. CHANGELOG.md `## X.Y.Z` headings
- *   3. git tags
- *   4. CLI `version` verb output (reads from package.json)
- *
- * Anywhere else, `// v0.13.22` / `Pre-v0.13.22` / `*-v0_13_22.test.js`
- * is phase residue — operators don't have the roadmap, version tags
- * rot the moment the next release lands, and `git clone` ships every
- * comment to operators along with the code.
- *
- * The check uses a baseline snapshot (`tests/.version-tag-baseline.
- * json`) capturing current violation counts per file. Future scans
- * compare against the baseline:
- *
- *   - Filename violations beyond baseline → fail.
- *   - Line violations beyond baseline (in any file)           → fail.
- *   - Violations strictly within baseline                     → ok.
- *   - Violations below baseline (drift reduced)               → ok +
- *     suggestion to refresh the baseline.
- *
- * Refresh: `node scripts/check-version-tags.js --update-baseline`.
- *
- * Wired into `npm run predeploy` as a gate.
+ * Predeploy gate refusing new version-stamped lines and filenames in the tracked
+ * source tree. Whole lines, not just comments: a stamp in a data literal or a
+ * help string is residue too, and a load-bearing one is exempted by path in
+ * COMMENT_EXEMPT rather than by narrowing the scan. Counts must not rise above
+ * tests/.version-tag-baseline.json; refresh it with `--update-baseline`.
  */
 
 const fs = require("node:fs");
@@ -48,24 +16,14 @@ const { execFileSync } = require("node:child_process");
 const ROOT = path.join(__dirname, "..");
 const BASELINE_PATH = path.join(ROOT, "tests", ".version-tag-baseline.json");
 
-// Directories we do not walk at all.
 const SKIP_DIRS = new Set([
   "node_modules", ".git", ".keys", ".cache", ".scratch",
   "data", "vendor", ".husky",
 ]);
 
-// File extensions we scan for comment violations.
 const SCAN_EXTS = new Set([".js", ".cjs", ".mjs", ".md"]);
 
-// Paths that the project intentionally version-stamps:
-//   - CHANGELOG headings are how operators navigate the file
-//   - package.json / manifest.json carry the canonical version field
-//   - manifest-snapshot.json + sbom.cdx.json contain version-pinned
-//     metadata (the SBOM IS a version-stamped manifest)
-//   - lib/version-pins.js is a version-constant lookup table
-//   - This checker itself documents what it forbids
-//   - .git-blame-ignore-revs carries commit hashes, not version tags,
-//     but is conventional config the user maintains
+// Paths where a version reference is load-bearing.
 const COMMENT_EXEMPT = new Set([
   "package.json",
   "manifest.json",
@@ -74,45 +32,20 @@ const COMMENT_EXEMPT = new Set([
   "CHANGELOG.md",
   "lib/version-pins.js",
   "scripts/check-version-tags.js",
-  // The release-notes-extract gate test asserts version-based CHANGELOG
-  // extraction + the shorter-vs-longer prefix-collision guard, so its fixtures
-  // MUST embed real `## X.Y.Z` headings (e.g. 0.15.5 vs 0.15.50) — load-bearing
-  // test data, not sprinkled release tags.
+  // Fixtures embed real `## X.Y.Z` headings, including a prefix collision.
   "tests/check-changelog-extract.test.js",
-  // The extract gate's orphan-tag allowlist must name the exact versions of
-  // tags that exist with no published release (outage-recovery bumps), so the
-  // heading-completeness check can skip them — load-bearing references to git
-  // tags, an authoritative version surface.
+  // Allowlists the exact versions of tags with no published release.
   "scripts/check-changelog-extract.js",
-  // The version-bump cadence gate's subject IS version comparison: its doc
-  // shows an example ack naming a target version, and its test compares real
-  // X.Y.Z transitions (patch vs minor vs major vs downgrade). Those version
-  // literals are load-bearing data, not sprinkled release tags.
+  // Version comparison is the subject: real X.Y.Z transitions under test.
   "scripts/check-version-bump.js",
   "tests/version-bump-cadence.test.js",
-  // The version-tag gate's own regression test asserts the trailing-period /
-  // IPv4 / longer-run boundaries and the PHASE_RESIDUE_RES / FILENAME_VERSION_RE
-  // / countLineViolations exports, so it MUST embed literal stamps like
-  // `0.18.9.`, `0.18.99`, `Pre-0.13.22`, and `foo-v0_13_2.test.js` as the inputs
-  // under test — load-bearing data for the detector's boundary cases, not
-  // sprinkled release tags.
+  // The detector's own boundary cases appear literally as the inputs under test.
   "tests/check-version-tags.test.js",
 ]);
 
-// Git-ignored files (a contributor's local-only working docs, scratch) are
-// never scanned — the gate enforces on the would-be-shipped surface, with no
-// 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.
+// The ignored subset of `relPaths`, or null when git cannot answer. "No path
+// matched" and "the question could not be asked" must not collapse into the same
+// empty set, which would reclassify every local-only file as shipped surface.
 function gitIgnoredSet(relPaths) {
   if (!relPaths.length) return new Set();
   try {
@@ -122,9 +55,7 @@ function gitIgnoredSet(relPaths) {
     });
     return new Set(out.split(/\r?\n/).filter(Boolean));
   } catch (e) {
-    // 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.
+    // Exit 1 with no stderr is git's "no path matched" — a real answer, not a failure.
     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) : "";
@@ -133,20 +64,11 @@ function gitIgnoredSet(relPaths) {
   }
 }
 
-// Pattern: project version like `v0.13.22` or bare `0.13.22`. Matches
-// our pre-1.0 release range. External package versions like ATLAS
-// `v5.6.0` or CycloneDX `1.6` don't match because the major is 0.
-// The trailing lookahead rejects a longer minor/patch digit (so `0.18.99`
-// still matches, but the stamp can't be part of a wider number) and a
-// dot-followed-by-digit (an IPv4 next octet / longer dotted-numeric run, e.g.
-// `127.0.0.1`, whose `0.0.1` tail would otherwise register). A sentence-ending
-// period after the patch (dot followed by non-digit / end-of-line, e.g.
-// `// fixed in 0.18.9.`) is NOT excluded — that is exactly the version residue
-// the gate must catch. The leading `(?<![\d.])` lookbehind keeps the IPv4
-// suppression on the other side.
+// A pre-1.0 project version, `v0.13.22` or bare; a non-0.x external version such
+// as CycloneDX `1.6` misses. The lookarounds keep the stamp out of a wider number
+// or a dotted run like `127.0.0.1`, whose tail would otherwise register.
 const VERSION_TAG_RE = /(?<![\d.])v?0\.\d+\.\d+(?!\d)(?!\.\d)/;
 
-// Phase residue patterns — broader than just version tags.
 const PHASE_RESIDUE_RES = [
   /\bcycle\s+\d+\b/i,        // "cycle 13 P3 F3"
   /\bphase\s+\d+(\.\d+)+\b/i,// "phase 9.11k"
@@ -173,12 +95,6 @@ function walk(dir, results = []) {
   return results;
 }
 
-// Counts version-stamp lines in a file. Intentionally WHOLE-LINE, not
-// comment-only: a 0.x stamp inside a shipped string literal (CLI --help text,
-// an error message, a test description) is operator-readable residue just like
-// a `//` comment, so it counts the same. A file with a genuinely load-bearing
-// version literal (real test fixture, deprecation timeline) is exempted by path
-// in COMMENT_EXEMPT, not by narrowing the scan.
 function countLineViolations(rel) {
   if (COMMENT_EXEMPT.has(rel)) return 0;
   const ext = path.extname(rel);
@@ -199,16 +115,11 @@ 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.
+  // Without git, local-only files are indistinguishable from tracked ones.
   if (ignored === null) return { byFile: {}, filenameViolations: [], surfaceUnknown: true };
   const byFile = {};
   const filenameViolations = [];
   for (const rel of files) {
-    // 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);
@@ -248,15 +159,8 @@ function main() {
   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.
+    // A baseline written from this scan would bake in the wrong surface. In
+    // automation this fails rather than skips: predeploy guards publishing.
     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");
@@ -291,8 +195,6 @@ function main() {
 
   const regressions = [];
 
-  // Filename regressions: any new filename matching the pattern that
-  // wasn't in the baseline.
   for (const rel of current.filenameViolations) {
     if (!baseline.filenameViolations.includes(rel)) {
       regressions.push({
@@ -303,7 +205,6 @@ function main() {
     }
   }
 
-  // Comment regressions: per-file count grew.
   for (const [rel, n] of Object.entries(current.byFile)) {
     const prior = baseline.byFile[rel] || 0;
     if (n > prior) {
@@ -317,11 +218,9 @@ function main() {
     }
   }
 
-  // Files newly added to the violation set (not in baseline at all).
   for (const rel of Object.keys(current.byFile)) {
     if (!(rel in baseline.byFile)) {
       const n = current.byFile[rel];
-      // Skip if already captured as a count regression above.
       if (regressions.some(r => r.path === rel)) continue;
       regressions.push({
         kind: "comment",