@blamejs/exceptd-skills 0.19.33 → 0.19.34

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"})`

package/scripts/refresh-manifest-snapshot.js

@@ -1,32 +1,16 @@
 "use strict";
 /**
- * scripts/refresh-manifest-snapshot.js
+ * Captures the public skill surface from manifest.json into
+ * manifest-snapshot.json. Run it AFTER an intentional surface change and commit
+ * the new snapshot alongside that change — never to "fix" a failing
+ * check-manifest-snapshot.js gate, whose breaking-change list is the thing to
+ * read first. A breaking change is a surface narrowing every downstream
+ * consumer needs to know about.
  *
- * Captures the current public skill surface from manifest.json and
- * writes it to manifest-snapshot.json. Run this AFTER an intentional
- * surface change (added skill, renamed trigger, refreshed framework
- * refs) and commit the new snapshot alongside the change.
- *
- * Do NOT run this to "fix" a failing check-manifest-snapshot.js gate
- * blindly — read the breaking-change list first. A breaking change is
- * a surface narrowing every downstream consumer needs to know about.
- *
- * 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              # 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.
+ * Overwriting an existing snapshot takes `--commit-only` or
+ * EXCEPTD_SNAPSHOT_AUDIT_ACK=1. Without either, a run whose capture differs
+ * refuses and prints a diff hint, so muscle memory cannot mask a real breaking
+ * change. scripts/predeploy.js names the flag where the gate fails.
  */
 
 const fs = require("fs");
@@ -64,18 +48,14 @@ 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";
 
-// Read the committed snapshot once and branch on the read RESULT rather than
-// an existsSync(SNAPSHOT_PATH)-then-readFileSync probe — the latter is a
-// check-then-use window (CodeQL js/file-system-race) where the existence the
-// guard decides on may not be the file it then reads. ENOENT IS the "no prior
-// snapshot, write a fresh one" signal.
+// Branch on the read RESULT, never on an existsSync-then-read probe: that is a
+// check-then-use window (CodeQL js/file-system-race) where the file the guard
+// decided on need not be the one read. ENOENT IS the "no prior snapshot" signal.
 let current = null;
 try {
   current = fs.readFileSync(SNAPSHOT_PATH, "utf8");
@@ -83,8 +63,7 @@ try {
   if (e.code !== "ENOENT") throw e;
 }
 if (current !== null && !commitOnly) {
-  // Normalise the _generated_at timestamp for comparison — that field
-  // changes every run and shouldn't trigger the guard.
+  // _generated_at changes every run, so it must not trigger the guard.
   const stripGenerated = (s) => s.replace(
     /"_generated_at":\s*"[^"]+",?\s*\n?/, ""
   );
@@ -108,9 +87,8 @@ 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.");
 
-// write a tracked SHA-256 of the snapshot so the
-// check-manifest-snapshot.js gate can verify integrity (no hand edits
-// after refresh).
+// A tracked SHA-256 lets check-manifest-snapshot.js catch a hand edit made
+// after the refresh.
 const crypto = require("crypto");
 const snapshotSha = crypto.createHash("sha256").update(newJson).digest("hex");
 const snapshotShaPath = path.join(ROOT, "manifest-snapshot.sha256");

package/scripts/refresh-mitre-atlas.js

@@ -1,14 +1,9 @@
 #!/usr/bin/env node
 "use strict";
 /**
- * scripts/refresh-mitre-atlas.js
- *
- * Thin per-type wrapper for the MITRE ATLAS refresher. Logic lives in
- * scripts/refresh-upstream-catalogs.js#refreshAtlas.
- *
- *   node scripts/refresh-mitre-atlas.js [--dry-run]
- *
- * Wired as `npm run refresh-mitre-atlas`.
+ * Thin per-type wrapper for the MITRE ATLAS refresher; the logic lives in
+ * scripts/refresh-upstream-catalogs.js#refreshAtlas. Wired as
+ * `npm run refresh-mitre-atlas`, and takes --dry-run.
  */
 const { refreshAtlas } = require("./refresh-upstream-catalogs.js");
 const dry = process.argv.includes("--dry-run");

package/scripts/refresh-mitre-attack.js

@@ -1,15 +1,8 @@
 #!/usr/bin/env node
 "use strict";
 /**
- * scripts/refresh-mitre-attack.js
- *
- * Thin per-type wrapper for the MITRE ATT&CK refresher. Logic lives in
+ * Refreshes only the MITRE ATT&CK catalog. Logic lives in
  * scripts/refresh-upstream-catalogs.js#refreshAttack.
- *
- *   node scripts/refresh-mitre-attack.js [--dry-run]
- *   CAP=200 node scripts/refresh-mitre-attack.js
- *
- * Wired as `npm run refresh-mitre-attack`.
  */
 const { refreshAttack } = require("./refresh-upstream-catalogs.js");
 const dry = process.argv.includes("--dry-run");

package/scripts/refresh-mitre-d3fend.js

@@ -1,15 +1,9 @@
 #!/usr/bin/env node
 "use strict";
 /**
- * scripts/refresh-mitre-d3fend.js
- *
- * Thin per-type wrapper for the MITRE D3FEND refresher. Logic lives in
- * scripts/refresh-upstream-catalogs.js#refreshD3fend.
- *
- *   node scripts/refresh-mitre-d3fend.js [--dry-run]
- *   CAP=120 node scripts/refresh-mitre-d3fend.js
- *
- * Wired as `npm run refresh-mitre-d3fend`.
+ * Thin wrapper for the MITRE D3FEND refresher; the logic lives in
+ * scripts/refresh-upstream-catalogs.js#refreshD3fend. Wired as
+ * `npm run refresh-mitre-d3fend`.
  */
 const { refreshD3fend } = require("./refresh-upstream-catalogs.js");
 const dry = process.argv.includes("--dry-run");

package/scripts/refresh-mitre-ics-attack.js

@@ -1,14 +1,9 @@
 #!/usr/bin/env node
 "use strict";
 /**
- * scripts/refresh-mitre-ics-attack.js
- *
- * Thin per-type wrapper for the MITRE ICS-attack STIX refresher. Logic
- * lives in scripts/refresh-upstream-catalogs.js#refreshIcsAttack.
- *
- *   node scripts/refresh-mitre-ics-attack.js [--dry-run]
- *
- * Wired as `npm run refresh-mitre-ics-attack`.
+ * `npm run refresh-mitre-ics-attack [-- --dry-run]` — per-type wrapper for the
+ * MITRE ICS-attack STIX refresher; the logic lives in
+ * scripts/refresh-upstream-catalogs.js#refreshIcsAttack.
  */
 const { refreshIcsAttack } = require("./refresh-upstream-catalogs.js");
 const dry = process.argv.includes("--dry-run");