@blamejs/exceptd-skills 0.19.33 → 0.19.35

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",

package/scripts/predeploy.js

@@ -1,33 +1,8 @@
 "use strict";
 /**
- * scripts/predeploy.js
- *
- * Local mirror of the CI pre-deployment gate sequence. Runs every gate
- * the `.github/workflows/ci.yml` workflow runs, in order. Each gate is
- * isolated — a failure does not short-circuit the rest, so a single run
- * surfaces all problems instead of just the first one (matches the CI
- * shape where each job runs independently).
- *
- * Run before pushing to main or opening a PR:
- *   npm run predeploy
- *
- * Exit code:
- *   0  — all gates passed
- *   1  — one or more gates failed (per-gate output already printed)
- *   2  — runner-level error (missing script, fork failure, etc.)
- *
- * 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.
- *
- * 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.
+ * Local mirror of the CI pre-deployment gate sequence. Gates are isolated, so one
+ * failure does not short-circuit the rest and a single run surfaces every problem.
+ * Exit 0 all passed, 1 one or more failed, 2 runner-level error.
  */
 
 const { execFileSync } = require("child_process");
@@ -36,10 +11,7 @@ const fs = require("fs");
 
 const ROOT = path.join(__dirname, "..");
 
-// Ordered list of CI gates. Each entry: { name, command, args, ciJobName }.
-// ciJobName matches the `name:` field of the corresponding job in
-// .github/workflows/ci.yml (or scorecard.yml). Used by the workflow-sync
-// test to assert the two never drift.
+// Ordered CI gates; `ciJobName` matches the job `name:` in .github/workflows/ci.yml.
 const GATES = [
   {
     name: "Verify skill signatures (Ed25519)",
@@ -51,39 +23,19 @@ const GATES = [
   {
     name: "Run tests (node:test)",
     command: process.execPath,
-    // Glob form rather than a directory arg: Node 25.x on Windows
-    // resolves a bare directory path through the module loader before
-    // the test runner sees it, which fails for a working dir that
-    // sits inside a path containing parentheses (e.g. Dropbox).
-    //
-    // --test-concurrency=1 forces sequential file execution. Several
-    // test files (build-incremental, indexes-v070, refresh-*) touch
-    // shared filesystem state under data/_indexes/ + refresh-report.json
-    // + skill bodies; running in parallel produces flaky races. Sequential
-    // is ~1.5s slower locally but eliminates the false negative we hit
-    // on the Linux CI runner in the v0.9.0 release attempt.
+    // Glob, not a directory arg: on Windows a bare directory resolves through the
+    // module loader and fails under a path containing parentheses. --test-concurrency=1
+    // is required — build-incremental, indexes-v070 and refresh-* share state.
     args: ["--test", "--test-concurrency=1", "tests/*.test.js"],
     ciJobName: "Tests",
   },
   {
     name: "Validate CVE catalog schema + zero-day learning coverage",
     command: process.execPath,
-    // --strict promotes the deferred warning checks (cross-catalog ref
-    // resolution, strict CVSS-vector prefix, KEV-date-required, Hard-Rule-#14
-    // IoCs) to hard failures so they block a release rather than scrolling
-    // past. Auto-imported drafts stay exempt.
+    // --strict promotes deferred warnings to hard failures; drafts stay exempt.
     args: [path.join(ROOT, "lib", "validate-cve-catalog.js"), "--strict"],
     ciJobName: "Data integrity (catalog + manifest snapshot)",
   },
-  // 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,13 +49,7 @@ const GATES = [
     ciJobName: "Lint skill files",
   },
   {
-    // Informational — surfaces the forward_watch horizon across all skills.
-    // 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").
+    // Exit 0 ok, 1 "items present"; 2+ is a gate runtime error and fails the run.
     name: "Forward-watch aggregator (informational)",
     command: process.execPath,
     args: [
@@ -145,11 +91,7 @@ const GATES = [
     ciJobName: "Data integrity (catalog + manifest snapshot)",
   },
   {
-    // v0.12.3 — packs the tarball, extracts it, runs Ed25519 verify on the
-    // EXTRACTED tree. Catches the class of bug where verify-on-source-tree
-    // passes (38/38) but verify-on-shipped-tarball fails (0/38) because
-    // something between sign and pack swapped keys/public.pem. Every release
-    // v0.11.x through v0.12.2 shipped this regression invisibly.
+    // Verifies the EXTRACTED tarball: a step between sign and pack can swap keys/public.pem.
     name: "Verify shipped tarball (sign + pack + extract + verify round-trip)",
     command: process.execPath,
     args: [path.join(ROOT, "scripts", "verify-shipped-tarball.js")],
@@ -157,170 +99,100 @@ const GATES = [
     requiresKeys: true,
   },
   {
-    // AGENTS.md hard rule #15 (e2e no-MVP). Every diff that touches a
-    // CLI verb, CLI flag, lib/orchestrator/scripts export, playbook
-    // indicator, or CVE iocs field must land with a covering test
-    // reference in the same PR. The analyzer parses git diff against
-    // origin/main, classifies each change shape, and fails if a covered
-    // surface lacks a test literal anywhere under tests/. Blocking — a
-    // covered surface change without a covering test fails the gate.
+    // AGENTS.md Hard Rule #15: a CLI/export/indicator/iocs diff lands with a covering test.
     name: "Diff coverage (feature changes require test coverage)",
     command: process.execPath,
     args: [path.join(ROOT, "scripts", "check-test-coverage.js")],
     ciJobName: "Diff coverage",
   },
   {
-    // Validate every playbook in data/playbooks/ against the JSON schema
-    // + cross-playbook + cross-catalog references. v0.12.12 first wired
-    // this as informational so the patch-class release could land without
-    // retroactively breaking schema-drift cases; v0.13.0 flips it to
-    // required because the 20-playbook canonical set (including the 4
-    // v0.13.0 additions) all validate cleanly.
     name: "Validate playbooks (schema + cross-refs)",
     command: process.execPath,
     args: [path.join(ROOT, "lib", "validate-playbooks.js"), "--strict"],
     ciJobName: "Validate playbooks",
   },
   {
-    // v0.13.2: refuse silent test-set shrinkage. Static-counts `test(`
-    // declarations across tests/*.test.js and compares to the pinned
-    // baseline in tests/.test-count-baseline.json. Catches the class
-    // of regression where a test file gets accidentally deleted, a
-    // skip-all lands without review, or a misnamed file slips through
-    // the glob. The baseline is operator-refreshed on releases that
-    // intentionally add many new tests; --update-baseline rewrites it.
+    // Refuses silent test-set shrinkage: a deleted file, a skip-all or a misnamed
+    // file cannot pass. --update-baseline rewrites the pinned baseline.
     name: "Test-count baseline (no silent shrinkage)",
     command: process.execPath,
     args: [path.join(ROOT, "scripts", "check-test-count.js")],
-    // Folds under the existing Data integrity CI job rather than a
-    // dedicated job — the check is fast (~70ms) static analysis and
-    // shares the integrity-tier framing with manifest-snapshot etc.
     ciJobName: "Data integrity (catalog + manifest snapshot)",
   },
   {
-    // v0.13.21: catalog-gap budget gate. Runs the seven extended
-    // detection classes added in v0.13.21 (content-quality,
-    // temporal-staleness, logical-consistency, cross-ref-completeness,
-    // schema-evolution, operator-action-sla, unused-orphan) against
-    // the shipped catalog and fails if any class regresses beyond its
-    // documented budget. Mirrors the budget enforced by
-    // tests/shipped-catalog-integrity.test.js so the regression
-    // surfaces in BOTH the gate-summary table AND the test output.
+    // Fails if a detection class regresses past its budget. The same budget is in
+    // tests/shipped-catalog-integrity.test.js; the two must not drift.
     name: "Catalog-gap budget (v0.13.21 extended detection classes)",
     command: process.execPath,
     args: [path.join(ROOT, "scripts", "check-catalog-gap-budget.js")],
     ciJobName: "Data integrity (catalog + manifest snapshot)",
   },
   {
-    // Global-first framework-gap coverage gate (AGENTS.md Hard Rule #5).
-    // Every curated CVE must declare a framework_control_gaps statement for
-    // all five jurisdiction buckets (NIST, EU, UK, AU, ISO). Drafts are
-    // exempt. Prevents a US-centric subset from shipping in the offline
-    // catalog's framework-gap output for multi-jurisdiction operators.
+    // AGENTS.md Hard Rule #5: every curated CVE declares framework_control_gaps for
+    // all five jurisdiction buckets (NIST, EU, UK, AU, ISO). Drafts exempt.
     name: "Framework-gap jurisdiction coverage (Hard Rule #5)",
     command: process.execPath,
     args: [path.join(ROOT, "scripts", "check-framework-gap-coverage.js")],
     ciJobName: "Data integrity (catalog + manifest snapshot)",
   },
   {
-    // TTP reference-integrity gate. The two pinned MITRE catalogs define the
-    // techniques; every other file naming one is referring into them. MITRE
-    // retires and renumbers between releases, and a reference living outside
-    // the source catalogs is never dereferenced at runtime — so a stale id
-    // keeps rendering in operator output, pointing at a page that no longer
-    // resolves and leaving any control mapped to it orphaned (Hard Rule #4).
-    // Resolves against the pin rather than the network, so it can block.
+    // MITRE retires and renumbers technique ids, and a reference outside the two
+    // pinned catalogs is never dereferenced at runtime, orphaning its control.
     name: "TTP reference integrity (no orphaned technique ids)",
     command: process.execPath,
     args: [path.join(ROOT, "scripts", "check-ttp-references.js")],
     ciJobName: "Data integrity (catalog + manifest snapshot)",
   },
   {
-    // EPSS pair-consistency gate. A CVE's epss_score and epss_percentile come
-    // from the same daily publication, where the percentile is the score's
-    // rank — so sorting a publication's entries by score must sort them by
-    // percentile too. Refreshing one field without the other leaves an entry
-    // that passes every range and type check while ranking a CVE on a score
-    // that no longer supports it, which is precisely the input operators
-    // prioritise by. The ordering check catches that offline.
+    // epss_percentile is the score's rank within one daily publication, so a
+    // publication's entries must sort the same way by both.
     name: "EPSS score/percentile consistency",
     command: process.execPath,
     args: [path.join(ROOT, "scripts", "check-epss-consistency.js")],
     ciJobName: "Data integrity (catalog + manifest snapshot)",
   },
   {
-    // Version-tag drift gate. Compares the tracked tree against a
-    // baseline snapshot of pre-existing `// vX.Y.Z` comments and
-    // `*-vX_Y_Z.test.js` filenames. Fails on NEW additions outside
-    // the authoritative version surfaces (package.json /
-    // manifest.json / CHANGELOG headings / git tags). The full rule
-    // is documented at the top of check-version-tags.js; refresh the
-    // baseline after an organic cleanup via
-    // `node scripts/check-version-tags.js --update-baseline`.
+    // Fails on NEW `// vX.Y.Z` comments and `*-vX_Y_Z.test.js` filenames: versions
+    // live in package.json, manifest.json, CHANGELOG headings and git tags.
     name: "Version-tag drift (no new phase residue)",
     command: process.execPath,
     args: [path.join(ROOT, "scripts", "check-version-tags.js")],
     ciJobName: "Data integrity (catalog + manifest snapshot)",
   },
   {
-    // AGENTS.md collector enumeration drift gate. Catches the case
-    // where lib/collectors/ gets a new module but AGENTS.md's
-    // "<N> reference collectors ship today (...)" paragraph isn't
-    // bumped (or vice versa). The paragraph is the canonical source
-    // for AI-agent consumers; drift produces stale enumeration.
+    // Keeps lib/collectors/ and AGENTS.md's collector-enumeration paragraph in step.
     name: "AGENTS.md collector enumeration drift",
     command: process.execPath,
     args: [path.join(ROOT, "scripts", "check-agents-md-collectors.js")],
     ciJobName: "Data integrity (catalog + manifest snapshot)",
   },
   {
-    // Codebase-pattern gate. Blocks the code-shape bug classes that
-    // recurred across releases: a library-callable function that writes to
-    // stdout then calls process.exit() (truncates the buffered write when
-    // piped — the stdout-flush-truncation class), and a stale/typo'd `// allow:` marker.
-    // dynamic-RegExp construction is surfaced warn-only this release. The
-    // exception mechanism + the "owned elsewhere" boundary are documented in
-    // the script header.
+    // Blocks a library-callable function that writes to stdout then calls
+    // process.exit(), and an orphaned allow marker. Dynamic RegExp is warn-only.
     name: "Codebase-pattern gates (stdout-flush, dynamic RegExp, bidi codepoints, orphan markers)",
     command: process.execPath,
     args: [path.join(ROOT, "scripts", "check-codebase-patterns.js")],
     ciJobName: "Data integrity (catalog + manifest snapshot)",
   },
   {
-    // Test-subject coverage gate. Bidirectional: every tests/<x>.test.js must
-    // be named after a real SUBJECT the codebase has (a module / CLI verb /
-    // CVE id / playbook / data primitive / repo artifact), and every such
-    // subject must have a test. Blocks the naming drift that lets a test be
-    // filed under a version/finding label (where downstream readers can't find
-    // it) and surfaces any module/playbook that ships without a test. Derived
-    // dynamically from the source tree, so the list is never hand-maintained.
+    // Bidirectional: every tests/<x>.test.js names a real subject, and every subject
+    // has a test. Derived from the source tree, never hand-maintained.
     name: "Test-subject coverage (every test maps to a subject; every subject has a test)",
     command: process.execPath,
     args: [path.join(ROOT, "scripts", "check-test-subjects.js")],
     ciJobName: "Data integrity (catalog + manifest snapshot)",
   },
   {
-    // Release-notes extract + quality gate. Runs the same `## <version>`
-    // CHANGELOG extraction the release workflow publishes as the GitHub
-    // Release body, and lints it for operator-facing quality (no internal
-    // phase/pass/slice narrative, no agent-dispatch / conversation residue,
-    // no tautological green claims). A malformed or internal-narrative section
-    // fails here rather than shipping as the public release body / falling
-    // back to the generic "Release of v<version>." line.
+    // Runs the same `## <version>` CHANGELOG extraction the release workflow
+    // publishes, then lints it, so a bad section fails here rather than publicly.
     name: "Release-notes extract + operator-facing lint (CHANGELOG section)",
     command: process.execPath,
     args: [path.join(ROOT, "scripts", "check-changelog-extract.js")],
     ciJobName: "Data integrity (catalog + manifest snapshot)",
   },
   {
-    // Version-bump cadence gate. Patch is the ONLY default bump; a minor or
-    // major requires an explicit, committed authorization
-    // (tests/.version-bump-ack.json naming the exact target version).
-    // Compares the top two `## X.Y.Z` CHANGELOG headings — hermetic, so it
-    // enforces identically locally and in the release.yml validate job. A
-    // hand-bumped minor without the ack fails here rather than shipping a
-    // wrong version number (the class of error behind two mis-versioned
-    // releases). Full contract at the top of check-version-bump.js.
+    // Patch is the ONLY default bump; a minor or major needs a committed
+    // tests/.version-bump-ack.json naming the exact target version.
     name: "Version-bump cadence (patch-only default)",
     command: process.execPath,
     args: [path.join(ROOT, "scripts", "check-version-bump.js")],
@@ -341,9 +213,7 @@ function runGate(gate) {
     }
   }
   const t0 = Date.now();
-  // 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.
+  // Piped stdio, forwarded on: the summary needs a WARN count from the output.
   const { spawnSync } = require("child_process");
   const r = spawnSync(gate.command, gate.args, {
     cwd: ROOT,
@@ -353,9 +223,7 @@ function runGate(gate) {
   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.
+  // Both forms count: "WARN" at line start, and an inline "[warn]".
   const combined = (r.stdout || "") + (r.stderr || "");
   const warnCount = (
     combined.match(/^WARN\b/gm) || []
@@ -365,23 +233,13 @@ function runGate(gate) {
   if (r.status === 0) {
     return { status: "passed", durationMs, warnCount };
   }
-  // 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.
+  // informationalMaxExitCode separates a soft signal (0..N) from a crash; absent = any.
   if (gate.informational) {
     const ceil = typeof gate.informationalMaxExitCode === "number"
       ? gate.informationalMaxExitCode
       : Infinity;
-    // A spawn failure (spawnSync returns r.error set, status:null, signal:null —
-    // e.g. the gate command is missing / ENOENT / EACCES) is a crash, not an
-    // informational soft-signal. So is a signal kill (status:null with r.signal
-    // set — e.g. a 137 OOM kill) and a status that exceeds the soft-signal
-    // ceiling. Without surfacing the spawn-error case, an informational gate
-    // that never even ran fell through to "informational" and the release
-    // proceeded as if the gate had merely produced advisory output. The
-    // status===null && !signal case (no error object, but the process never
-    // produced an exit code) is treated the same way — a gate that did not
-    // exit cleanly cannot be classified as a soft signal.
+    // A gate that never ran cleanly is a crash, not a soft signal: spawn failure,
+    // a signal kill (137 OOM), and a status above the ceiling all fail here.
     const spawnFailed = !!r.error || (r.status === null && !r.signal);
     if (r.error || r.signal || spawnFailed || (r.status !== null && r.status > ceil)) {
       return {
@@ -442,7 +300,6 @@ function main() {
     }
   }
 
-  // Summary table.
   process.stdout.write("\n=== Pre-deploy summary ===\n");
   const widest = results.reduce(
     (n, r) => Math.max(n, r.gate.name.length),
@@ -459,10 +316,7 @@ 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.
+    // A gate that "passed (3 warnings)" must be distinguishable from a clean pass.
     const warnSuffix =
       outcome.warnCount && outcome.warnCount > 0
         ? ` (${outcome.warnCount} warning${outcome.warnCount === 1 ? "" : "s"})`