@blamejs/exceptd-skills 0.19.33 → 0.19.35

package/scripts/check-agents-md-collectors.js

@@ -2,24 +2,9 @@
 "use strict";
 
 /**
- * scripts/check-agents-md-collectors.js
- *
- * Predeploy gate. Verifies that AGENTS.md's "<N> reference collectors
- * ship today" paragraph stays in sync with the actual contents of
- * lib/collectors/. Drift is silent today - AGENTS.md gets bumped by
- * hand each release; a missed bump produces inaccurate count + stale
- * enumeration that downstream AI consumers parse.
- *
- * Checks:
- *   1. The numeric count word in the paragraph (Eleven / Twelve /
- *      Thirteen / ...) matches the actual count of
- *      lib/collectors/*.js modules.
- *   2. Every collector named in the parenthesized list exists at
- *      lib/collectors/<name>.js.
- *   3. Every lib/collectors/<name>.js module appears in the
- *      parenthesized list.
- *
- * Exit codes: 0 ok, 1 drift, 2 parse error.
+ * Predeploy gate: AGENTS.md's "<N> reference collectors ship today" paragraph
+ * must agree with lib/collectors/ — the count word and the enumeration, both
+ * directions. Exit codes: 0 ok, 1 drift, 2 parse error.
  */
 
 const fs = require("node:fs");
@@ -28,31 +13,20 @@ const path = require("node:path");
 const ROOT = path.join(__dirname, "..");
 const AGENTS = path.join(ROOT, "AGENTS.md");
 const REAL_COLLECTOR_DIR = path.join(ROOT, "lib", "collectors");
-// EXCEPTD_COLLECTOR_DIR lets the test suite drive the gate against a throwaway
-// tempdir (so the require-throw / leaked-fixture behaviours are exercised
-// without writing into the real lib/collectors/). It is honored ONLY when the
-// explicit test-only switch EXCEPTD_COLLECTOR_DIR_TESTONLY=1 is also set, so a
-// stray env var in CI or a developer shell can never point the release gate at
-// an alternate directory and let missing/broken real collectors pass.
+// EXCEPTD_COLLECTOR_DIR is honored ONLY alongside EXCEPTD_COLLECTOR_DIR_TESTONLY=1,
+// so a stray env var cannot aim the release gate at another directory.
 const COLLECTOR_DIR =
   process.env.EXCEPTD_COLLECTOR_DIR_TESTONLY === "1" && process.env.EXCEPTD_COLLECTOR_DIR
     ? path.resolve(process.env.EXCEPTD_COLLECTOR_DIR)
     : REAL_COLLECTOR_DIR;
 
-// A real shipped collector is named [a-z0-9-]+.js — the AGENTS.md enumeration
-// regex (`lib/collectors/([a-z0-9-]+\.js)`) cannot even reference an
-// underscore-prefixed file. So a `__`-prefixed file is never a collector:
-// it is test scaffolding or a stray artifact. classifyCollectors SKIPS it so a
-// leaked fixture cannot poison the count/enumeration/load-error scan; the gate
-// separately FORBIDS it (see findReservedFixtures) so a leaked fixture cannot
-// silently ship in the wholesale-published lib/ tree either.
+// A shipped collector is named [a-z0-9-]+.js, so a `__`-prefixed file is test
+// scaffolding: classifyCollectors skips it, findReservedFixtures forbids it in lib/.
 function isReservedFixture(f) {
   return f.startsWith("__");
 }
 
-// Reserved-prefix .js files present in `dir`. These are test scaffolding and
-// must never ship; the gate fails hard if any are found in the directory it
-// validates.
+// Reserved-prefix .js files present in `dir`; an unreadable dir yields [].
 function findReservedFixtures(dir) {
   try {
     return fs.readdirSync(dir).filter((f) => f.endsWith(".js") && isReservedFixture(f));
@@ -61,10 +35,20 @@ function findReservedFixtures(dir) {
   }
 }
 
-// Classify every <dir>/*.js into collectors (require succeeds + exports
-// collect()), helpers (require succeeds, no collect() — silently excluded),
-// and load-errors (require throws — surfaced, never silently dropped).
-// Exported so the test suite can drive it against a tempdir.
+// Repo-relative POSIX form of <dir>/<file> for a diagnostic, falling back to the
+// literal path when `dir` sits outside the repo (a test-only override dir).
+function collectorDisplayPath(dir, file) {
+  const abs = path.join(dir, file);
+  const rel = path.relative(ROOT, abs).split(path.sep).join("/");
+  return rel && !rel.startsWith("..") ? rel : abs.split(path.sep).join("/");
+}
+
+// Classify every <dir>/*.js: a collector requires cleanly and exports collect();
+// a require that throws becomes a load error rather than a silent omission.
+//
+// collectorFiles entries keep the literal `lib/collectors/` prefix whatever `dir`
+// is: they are compared against the paths AGENTS.md enumerates, which always name
+// the shipped location. Only the load-error diagnostic names the real path.
 function classifyCollectors(dir) {
   const jsFiles = fs.readdirSync(dir)
     .filter((f) => f.endsWith(".js") && !isReservedFixture(f))
@@ -76,7 +60,7 @@ function classifyCollectors(dir) {
     try {
       mod = require(path.join(dir, f));
     } catch (e) {
-      loadErrors.push(`lib/collectors/${f}: ${e.message.split("\n")[0]}`);
+      loadErrors.push(`${collectorDisplayPath(dir, f)}: ${e.message.split("\n")[0]}`);
       continue;
     }
     if (typeof mod.collect === "function") {
@@ -104,10 +88,7 @@ function ok(msg) {
 }
 
 function main() {
-  // Leak-guard (P2: forbid leaked reserved fixtures before packing). A
-  // `__`-prefixed file in the collectors dir is stray test scaffolding;
-  // because lib/ is published wholesale, a leaked one would otherwise ship.
-  // Fail hard, naming the file, so the release path deletes it.
+  // lib/ is published wholesale, so a stray fixture would ship.
   const stray = findReservedFixtures(COLLECTOR_DIR);
   if (stray.length > 0) {
     console.error(
@@ -126,18 +107,6 @@ function main() {
     return;
   }
 
-  // Classify every lib/collectors/*.js into exactly one of three buckets:
-  //   - collector:  require() succeeds AND exports a collect() function
-  //                 (counted; must appear in the AGENTS.md enumeration).
-  //   - helper:     require() succeeds but exports no collect() function
-  //                 (e.g. scan-excludes.js, the directory-walk exclusion
-  //                 policy) — legitimately excluded from the count.
-  //   - load-error: require() THROWS (syntax error, bad top-level require,
-  //                 init-time exception). A broken collector must NOT be
-  //                 silently dropped: doing so excludes it from BOTH the
-  //                 count and the enumeration cross-check, so a file that
-  //                 still ships in the tarball passes the gate undetected.
-  //                 Surface it as a parse error (exit 2) naming the file.
   let collectorFiles, loadErrors;
   try {
     ({ collectorFiles, loadErrors } = classifyCollectors(COLLECTOR_DIR));
@@ -149,7 +118,7 @@ function main() {
 
   if (loadErrors.length > 0) {
     console.error(
-      `[check-agents-md-collectors] cannot load ${loadErrors.length} module(s) in lib/collectors/ ` +
+      `[check-agents-md-collectors] cannot load ${loadErrors.length} module(s) in ${collectorDisplayPath(COLLECTOR_DIR, "")}/ ` +
       `- a require-time failure must not be silently excluded from the count + enumeration check:\n  ` +
       loadErrors.join("\n  ")
     );
@@ -206,4 +175,4 @@ if (require.main === module) {
   main();
 }
 
-module.exports = { classifyCollectors };
+module.exports = { classifyCollectors, collectorDisplayPath };

package/scripts/check-catalog-gap-budget.js

@@ -1,23 +1,13 @@
 #!/usr/bin/env node
 "use strict";
 /**
- * scripts/check-catalog-gap-budget.js
+ * Predeploy gate: runs the gap detectors and asserts no class exceeds its
+ * budget. Exit 0 within budget, 1 regressed, 2 internal error.
  *
- * Predeploy / CI gate that runs the v0.13.21 extended gap detectors
- * and asserts no class exceeds its budget. Mirrors the budget in
- * tests/shipped-catalog-integrity.test.js but runs as a standalone
- * predeploy gate so the check is visible in the gate summary even
- * when the broader test suite is skipped (or is the gate that's
- * failing for an unrelated reason).
- *
- * Exit codes:
- *   0 — every extended class within budget
- *   1 — at least one class regressed
- *   2 — internal error
- *
- * The budget is intentionally duplicated (here + integrity test) for
- * fail-loud-at-two-levels. Operators see the regression in BOTH the
- * test-suite output AND the predeploy gate-summary table.
+ * The budget is duplicated in tests/shipped-catalog-integrity.test.js so a
+ * regression shows in both the test output and the gate-summary table, and so
+ * the gate still reports when the suite is skipped or failing elsewhere. Both
+ * copies move together.
  */
 
 const path = require("path");
@@ -47,16 +37,13 @@ function loadAll() {
   };
 }
 
-// Per-class regression budgets. Kept in sync with the canonical version
-// in tests/shipped-catalog-integrity.test.js.
+// Per-class regression budgets, mirrored in
+// tests/shipped-catalog-integrity.test.js.
 const BUDGET = {
   "content-quality": 12,
-  // temporal-staleness now measures only maintainer-controllable data-freshness
-  // fields (source_verified > 180d, last_updated > 365d, epss_date > 90d). The
-  // calendar-driven KEV-due-passed sub-check was removed — it was an external
-  // operator-remediation date, not catalog freshness, and grew without bound as
-  // the catalog aged and KEV drafts got curated. Actual is 0 with fresh data;
-  // 10 leaves headroom for entries aging past a threshold before a refresh.
+  // temporal-staleness counts only the maintainer-controllable freshness fields,
+  // which sit at 0 on fresh data; the headroom covers entries aging past a
+  // threshold between refreshes.
   "temporal-staleness": 10,
   "logical-consistency": 5,
   "cross-ref-completeness": 5,
@@ -71,20 +58,16 @@ function main() {
   for (const f of all) byClass[f.class] = (byClass[f.class] || 0) + 1;
   const regressions = [];
 
-  // Fail-closed contract (codex P2 PR #61): every class actually
-  // emitted by the detector must have a budget entry. If a future
-  // 8th detector lands without a budget update, the gate fires with
-  // an unbudgeted-class error instead of silently passing.
+  // Fail-closed: a class the detectors emit without a budget entry fires an
+  // unbudgeted-class error rather than passing unmeasured.
   const unbudgeted = [];
   for (const cls of Object.keys(byClass)) {
     if (!(cls in BUDGET)) {
       unbudgeted.push({ class: cls, count: byClass[cls] });
     }
   }
-  // Inverse check: every class declared by the detector module's
-  // canonical class list must appear in BUDGET (covers the case where
-  // a new class produces zero findings on this run but still needs
-  // an explicit budget so a future regression caps fail-closed).
+  // The inverse: a class declared in DETECTOR_CLASSES needs a budget even when
+  // it emits nothing on this run, or the first regression has no cap to hit.
   const missingBudget = [];
   if (Array.isArray(D.DETECTOR_CLASSES)) {
     for (const cls of D.DETECTOR_CLASSES) {

package/scripts/check-changelog-extract.js

@@ -2,34 +2,14 @@
 'use strict';
 
 /**
- * Release-notes extraction + quality gate.
+ * Release-notes extraction + quality gate. .github/workflows/release.yml publishes
+ * the GitHub Release body by awk-extracting the `## <version> …` CHANGELOG section,
+ * falling back to "Release of v<version>." when the extract is empty. This runs the
+ * SAME extraction before tag-push and lints what it finds, so a malformed or
+ * internal-narrative section fails here rather than shipping as the public body.
  *
- * The release workflow (.github/workflows/release.yml) publishes the GitHub
- * Release body by awk-extracting the `## <version> ...` CHANGELOG section
- * between the version heading and the next `## ` heading, falling back to a
- * generic "Release of v<version>." line if the extract is empty. This gate
- * runs that SAME extraction locally before tag-push, and additionally lints
- * the extracted notes for operator-facing quality, so a malformed or
- * internal-narrative-laced section fails here rather than shipping as the
- * public release body.
- *
- * Two layers:
- *   1. EXTRACT  — the `## <version> — <date>` section exists, is non-empty
- *                 (won't trigger the workflow's "Release of v…" fallback),
- *                 the heading version matches package.json, and the heading
- *                 carries an ISO date.
- *   2. LINT     — the extracted body is operator-facing-clean: no internal
- *                 phase/pass/slice/sweep narrative, no agent-dispatch /
- *                 conversation residue, no tautological "all tests pass"
- *                 noise. (Mirrors the operator-facing discipline; the release
- *                 body is the most public surface there is.)
- *
- * Exit: process.exitCode 0 on pass, 1 on any failure. Functions are exported
- * for fixture-based testing (no subprocess needed).
- *
- * Usage:
- *   node scripts/check-changelog-extract.js             # uses package.json version
- *   node scripts/check-changelog-extract.js <version>   # explicit MAJOR.MINOR.PATCH
+ * process.exitCode 0 on pass, 1 on any failure. Takes an optional
+ * MAJOR.MINOR.PATCH argument, defaulting to the package.json version.
  */
 
 const fs = require('node:fs');
@@ -39,10 +19,9 @@ const ROOT = path.resolve(__dirname, '..');
 const CHANGELOG = path.join(ROOT, 'CHANGELOG.md');
 const PACKAGE_JSON = path.join(ROOT, 'package.json');
 
-// Replicates the release.yml awk: capture lines AFTER the `## <version> `
-// heading up to (not including) the next `## ` heading. The trailing space in
-// the heading match mirrors the workflow's `"^## " v " "` so a shorter version
-// heading can't accidentally match a longer one that shares its prefix.
+// Replicates the release.yml awk: lines after the `## <version> ` heading up to
+// the next `## `. The trailing space mirrors the workflow's `"^## " v " "`, so a
+// shorter version heading cannot match a longer one sharing its prefix.
 function extractSection(text, version) {
   const lines = text.split(/\r?\n/);
   const out = [];
@@ -56,8 +35,7 @@ function extractSection(text, version) {
     }
     if (startRe.test(ln)) capturing = true;
   }
-  // Trim leading/trailing blank lines (awk keeps them; the body is the same
-  // either way, but trimming makes the non-empty test honest).
+  // awk keeps the blank lines; trimming them makes the non-empty test honest.
   while (out.length && out[0].trim() === '') out.shift();
   while (out.length && out[out.length - 1].trim() === '') out.pop();
   return out;
@@ -69,10 +47,8 @@ function headingLine(text, version) {
   return text.split(/\r?\n/).find((l) => re.test(l)) || null;
 }
 
-// Operator-facing forbidden patterns. Tight, high-confidence internal-narrative
-// markers only — must not false-positive on legitimate operator prose (e.g. a
-// bare "phase" in "multi-phase attack" is fine; "Phase 9" is the tell). Each
-// entry: { id, re, why }.
+// Operator-facing forbidden patterns: high-confidence markers only, since a false
+// positive blocks a release. "multi-phase attack" is prose; "Phase 9" is the tell.
 const FORBIDDEN = [
   { id: 'phase-number', re: /\bphase\s+\d/i, why: 'internal phase number (operators have no roadmap)' },
   { id: 'pass-number', re: /\b(?:audit|curation|drift|fix|bug)?[- ]?pass\s+\d/i, why: 'internal pass/batch number' },
@@ -100,17 +76,11 @@ function readPackageVersion() {
   return JSON.parse(fs.readFileSync(PACKAGE_JSON, 'utf8')).version;
 }
 
-// Every previously released version must keep its own `## <version> ` heading.
-// The release flow edits the TOP of the file; an edit that replaces the prior
-// release's heading instead of inserting above it silently merges that
-// release's notes into the new section — the extract then spans multiple
-// releases and the public release body republishes old notes under the new
-// version. Tags are the authoritative record of what was released.
-// Tags whose release never published: the tag-push event was dropped (e.g.
-// a GitHub Actions outage) and — because the v* ruleset forbids re-pushing a
-// tag — the recovery is a version bump re-released with the same notes under
-// the NEW heading. The orphan tag therefore legitimately has no CHANGELOG
-// entry of its own. Tag exists, npm/GitHub Release do not.
+// Every released version keeps its own `## <version> ` heading; tags are the
+// authoritative record of which versions those are. An orphan is a tag whose
+// release never published: the v* ruleset forbids re-pushing a tag, so the
+// recovery was a version bump carrying the same notes under the NEW heading, and
+// such a tag legitimately has no CHANGELOG entry of its own.
 const ORPHAN_RELEASE_TAGS = new Set(['0.13.111', '0.15.25']);
 
 function releasedVersionsFromTags() {

package/scripts/check-codebase-patterns-currency.js

@@ -1,24 +1,12 @@
 #!/usr/bin/env node
 "use strict";
 /**
- * check-codebase-patterns-currency.js — advisory drift detector between
- * exceptd's adopted codebase-pattern classes and the upstream catalog they
- * were derived from (the sibling blamejs codebase-patterns test).
+ * Advisory drift detector between exceptd's adopted codebase-pattern classes
+ * and the sibling blamejs codebase-patterns test they derive from. A class
+ * present upstream but absent from UPSTREAM_TRIAGED is new and wants triage.
  *
- * exceptd's grep gate (scripts/check-codebase-patterns.js) ships a scoped
- * subset of the upstream pattern classes; the rest were triaged as either
- * already-owned by another exceptd gate, helper-dependent, or out of scope
- * for a local-file-read security CLI. UPSTREAM_TRIAGED below records every
- * class that triage covered. When upstream grows a NEW class not in that set,
- * this check flags it so the maintainer can decide whether to adopt it — the
- * same forcing function the GitHub-actions / vendored-bundle currency checks
- * provide for those surfaces.
- *
- * Advisory by design: it never fails a release. It exits 0 and prints a
- * NOTICE when upstream has drifted, and exits 0 silently when the sibling
- * repo is not present (a fresh clone / CI runner without the sibling). Point
- * it elsewhere with EXCEPTD_UPSTREAM_PATTERNS env var if the sibling lives at
- * a non-default path.
+ * Always exits 0 — it prints a NOTICE on drift and exits silently when the
+ * sibling repo is absent. EXCEPTD_UPSTREAM_PATTERNS overrides its path.
  */
 
 const fs = require("node:fs");
@@ -26,10 +14,7 @@ const path = require("node:path");
 
 const ROOT = path.resolve(__dirname, "..");
 
-// The upstream allow-class registry as triaged during the codebase-patterns adoption.
-// Every key here was classified (adopted / already-owned / helper-dependent /
-// out-of-scope). A class appearing upstream but absent here is NEW and wants
-// triage. Refresh this list (and re-triage the delta) when this check fires.
+// Refresh this list, re-triaging the delta, when this check fires.
 const UPSTREAM_TRIAGED = Object.freeze([ // keep-sorted
   "ai-disclosure-on-request-without-requested-gate",
   "archive-gz-without-safedecompress",
@@ -83,7 +68,6 @@ function upstreamPatternsPath() {
   return path.resolve(ROOT, "..", "blamejs", "test", "layer-0-primitives", "codebase-patterns.test.js");
 }
 
-// Extract the allow-class keys from the upstream VALID_ALLOW_CLASSES literal.
 function upstreamClasses(src) {
   const m = src.match(/VALID_ALLOW_CLASSES\s*=\s*(?:Object\.freeze\()?\{([\s\S]*?)\}/);
   if (!m) return null;