@blamejs/exceptd-skills 0.19.32 → 0.19.34

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;

package/scripts/check-codebase-patterns.js

@@ -1,39 +1,16 @@
 #!/usr/bin/env node
 "use strict";
 /**
- * check-codebase-patterns.js — grep-gate enforcement for code-shape bug
- * classes that have recurred across exceptd releases. One run surfaces every
- * class as a single numbered report instead of dying on the first hit.
+ * Grep gate for code-shape bug classes that recur across releases; CLASSES
+ * below is the registry.
  *
- * Shipped v1 classes:
- *   - process-exit-after-stdout-write : a library-callable function writes to
- *       the result channel (process.stdout.write / console.log) and then calls
- *       process.exit(), which truncates the buffered write when stdout is
- *       piped. Route through `safeExit(EXIT_CODES.X); return;` (lib/exit-codes).
- *       This is the stdout-flush-truncation class the validate-cves fix closed by hand.
- *   - dynamic-regex : `new RegExp(<non-literal>)` — a ReDoS sink when the
- *       pattern derives from operator input. Use a static literal, or anchor +
- *       length-cap the input, or mark the site `// allow:dynamic-regex —
- *       <reason>` when the source is a trusted bundled schema.
- *   - orphan-allow-class : an `// allow:<class>` marker whose class is not in
- *       VALID_ALLOW_CLASSES, or is missing the `— <reason>` tail. A typo'd
- *       marker suppresses nothing, so the underlying violation would ship
- *       unflagged — this meta-guard keeps the marker mechanism trustworthy.
- *   - unsorted-marked-array : a flat string array tagged `// keep-sorted` that
- *       drifted out of alphabetical order. Opt-in — only marked arrays are
- *       checked, so a one-time allowlist sort becomes a standing guarantee.
- *   - misaligned-marked-run : a `// keep-aligned` const/weight table whose
- *       `=`/`:` assignment columns are not all equal. Opt-in, same shape.
- *
- * Exceptions live at the violation site, not in this file:
+ * Exceptions live at the violation site:
  *   - file-level, in the first 50 lines:  // codebase-patterns:allow-file <class> — <reason>
  *   - per-line, on the same line or up to 2 lines above:  // allow:<class> — <reason>
  *
- * NOT covered here (owned elsewhere — do not duplicate):
- *   - internal phase/version vocabulary in comments  -> scripts/check-version-tags.js
- *   - process.exit on the top-level CLI dispatch      -> tests/safe-exit-grep.test.js
- *   - anti-coincidence test assertions                -> scripts/check-test-coverage.js
- *   - internal-path leaks in operator output          -> tests/operator-leak-grep.test.js
+ * Owned elsewhere: phase/version vocabulary (check-version-tags.js), CLI-dispatch
+ * process.exit (tests/safe-exit-grep.test.js), test assertions
+ * (check-test-coverage.js), operator-output path leaks (operator-leak-grep.test.js).
  */
 
 const fs = require("node:fs");
@@ -41,8 +18,8 @@ const path = require("node:path");
 
 const ROOT = path.resolve(__dirname, "..");
 
-// The classes that accept an `// allow:<class>` marker. orphan-allow-class is
-// the meta-guard itself and is intentionally NOT a markable class.
+// Classes that accept an `// allow:<class>` marker. orphan-allow-class is the
+// meta-guard itself, so it is not markable.
 const VALID_ALLOW_CLASSES = Object.freeze({
   "process-exit-after-stdout-write": true,
   "dynamic-regex": true,
@@ -57,8 +34,6 @@ const EXCLUDE_DIRS = new Set([
   "data", ".test-output", ".keys", "keys", "coverage",
 ]);
 
-// ---- file walk -----------------------------------------------------------
-
 function relPath(abs) {
   return path.relative(ROOT, abs).split(path.sep).join("/");
 }
@@ -104,18 +79,15 @@ function readLines(rel) {
   return lines;
 }
 
-// Strip a trailing `//` line comment for code-shape detection (so a class
-// name mentioned in a comment doesn't arm a detector). String-aware: a `//`
-// inside a quoted string (e.g. a `http://` URL) is NOT a comment, so the
-// scanner skips string contents — otherwise the rest of the line, including a
-// real `process.exit(...)` / `new RegExp(...)`, was silently truncated away and
-// the detector never fired.
+// Strip a trailing `//` line comment so a class name mentioned in a comment
+// can't arm a detector. String-aware: a `//` inside a quoted string (a `http://`
+// URL) is not a comment — truncating there hides a real hit later on the line.
 function stripLineComment(line) {
   let inStr = null; // active quote char, or null
   for (let i = 0; i < line.length; i++) {
     const ch = line[i];
     if (inStr) {
-      if (ch === "\\") { i++; continue; } // skip the escaped char
+      if (ch === "\\") { i++; continue; }
       if (ch === inStr) inStr = null;
     } else if (ch === "'" || ch === '"' || ch === "`") {
       inStr = ch;
@@ -126,8 +98,6 @@ function stripLineComment(line) {
   return line;
 }
 
-// ---- allow-marker engine -------------------------------------------------
-
 function hasFileAllow(rel, cls) {
   const head = readLines(rel).slice(0, 50);
   const re = new RegExp("codebase-patterns:allow-file\\s+" + cls + "\\b");
@@ -147,23 +117,10 @@ function filterMarkers(hits, cls) {
   return hits.filter((h) => !hasFileAllow(h.file, cls) && !hasLineAllow(h.file, h.line, cls));
 }
 
-// ---- require.main block ranges -------------------------------------------
-
-// Count `{` / `}` in `line` that are in REAL CODE context, advancing a
-// stateful tokenizer that tracks string / template / comment regions across
-// lines. Braces inside a single/double/template string, a `//` line comment,
-// or a `/* */` block comment do NOT affect depth — otherwise a `{` or `}`
-// typed inside a string literal in the require.main block miscounts the brace
-// balance and the computed block range slides onto an unrelated later function
-// (whose process.exit() is then wrongly treated as a CLI-entry exit and not
-// flagged). `inTemplate` and `inBlockComment` are the cross-line states a
-// per-line stripper cannot model, so the tokenizer state object is threaded
-// line-to-line by the caller.
-//
-// `state` is mutated in place: { inSingle, inDouble, inTemplate, inBlock,
-// templateDepth } — `templateDepth` tracks `${ … }` interpolation nesting so
-// the closing `}` of an interpolation is treated as template punctuation, not
-// a code brace, while braces INSIDE the interpolation expression still count.
+// Counts `{` / `}` in REAL CODE context only: a brace inside a string, template
+// or comment must not move the depth, or the computed require.main range slides
+// onto a later function. `state` is mutated in place and threaded line to line,
+// since `inTemplate` / `inBlock` are cross-line states.
 function countCodeBraces(line, state) {
   let delta = 0;
   for (let i = 0; i < line.length; i++) {
@@ -190,13 +147,12 @@ function countCodeBraces(line, state) {
         // Enter an interpolation expression: braces inside ARE code.
         state.templateExpr.push(0);
         state.inTemplate = false;
-        i++; // skip the `{`; the `${` opener is template punctuation
+        i++;
         continue;
       }
       continue;
     }
-    // Code context (possibly inside a template interpolation expression).
-    if (ch === "/" && next === "/") break; // `//` — rest of the line is a comment
+    if (ch === "/" && next === "/") break;
     if (ch === "/" && next === "*") { state.inBlock = true; i++; continue; }
     if (ch === "'") { state.inSingle = true; continue; }
     if (ch === '"') { state.inDouble = true; continue; }
@@ -222,17 +178,12 @@ function newBraceState() {
   return { inSingle: false, inDouble: false, inTemplate: false, inBlock: false, templateExpr: [] };
 }
 
-// Line ranges (1-based, inclusive) of `if (require.main === module) { ... }`
-// blocks — the dual-mode CLI-entry section where synchronous-print-then-exit
-// is correct. process.exit there is owned by tests/safe-exit-grep.test.js and
-// is not a library-surface concern.
+// Line ranges (1-based, inclusive) of `if (require.main === module) { ... }` blocks,
+// where print-then-exit is correct — owned by tests/safe-exit-grep.test.js.
 function requireMainRanges(lines) {
   const ranges = [];
   for (let i = 0; i < lines.length; i++) {
     if (/\brequire\.main\s*===\s*module\b/.test(lines[i])) {
-      // Find the opening brace (same line or next few), then balance —
-      // string/comment/template-aware so braces inside literals don't skew the
-      // depth (see countCodeBraces).
       let depth = 0;
       let started = false;
       let j = i;
@@ -252,17 +203,10 @@ function inRanges(ranges, lineNo) {
   return ranges.some(([a, b]) => lineNo >= a && lineNo <= b);
 }
 
-// ---- detectors -----------------------------------------------------------
-
-// A line that opens a new function body (so a backward stdout-write scan stops
-// at the enclosing function and doesn't arm an exit from an unrelated earlier
-// function). The bare-identifier (third) alternative matches a declaration /
-// method-shorthand opener (`foo() {`, `async bar() {`), but it must REFUSE
-// control-flow openers (`for (…) {`, `if (…) {`, `while/switch/catch (…) {`):
-// a control-flow block sitting between a stdout write and a process.exit() is
-// inside the SAME function, so stopping the backward scan there would wrongly
-// leave the exit unflagged. The negative lookahead excludes the control-flow
-// keywords; `function` and arrow alternatives are unchanged.
+// Opens a new function body, so the backward stdout-write scan stops at the
+// enclosing function. The bare-identifier alternative must REFUSE control-flow
+// openers (`if (…) {`, `for (…) {`): those sit inside the SAME function, and
+// stopping there leaves a real exit-after-write unflagged.
 const FUNCTION_START = /(^|[^.\w])function\b|=>\s*\{?\s*$|^\s*(async\s+)?(?!(?:if|for|while|switch|catch|do|else|with|finally|return)\b)[A-Za-z_$][\w$]*\s*\([^)]*\)\s*\{/;
 
 function detectProcessExitAfterStdout(files) {
@@ -275,8 +219,7 @@ function detectProcessExitAfterStdout(files) {
       if (!/\bprocess\.exit\s*\(/.test(code)) continue;
       const lineNo = i + 1;
       if (inRanges(mainRanges, lineNo)) continue; // CLI-entry block: legitimate
-      // Scan backward within the enclosing function for a result-channel
-      // write (console.log / process.stdout.write). Stop at a function start.
+      // Scan backward within the enclosing function for a result-channel write.
       let sawStdout = false;
       for (let k = i - 1; k >= 0 && k >= i - 60; k--) {
         const prev = stripLineComment(lines[k]);
@@ -291,11 +234,8 @@ function detectProcessExitAfterStdout(files) {
   return filterMarkers(hits, "process-exit-after-stdout-write");
 }
 
-// The first non-whitespace char of the first arg is `"`, `'`, or `/` => a
-// string/regex literal => static, safe. Anything else (an identifier, a `(`,
-// a backtick template) is operator-derivable and flagged. Backtick is NOT
-// exempt — a template literal can interpolate operator input, so it must be
-// flagged the same as a bare identifier.
+// A first arg opening with `"`, `'` or `/` is a literal, so static and safe.
+// Backtick is NOT exempt — a template literal can interpolate operator input.
 function isStaticRegexFirstChar(ch) {
   return ch === '"' || ch === "'" || ch === "/";
 }
@@ -312,23 +252,17 @@ function detectDynamicRegex(files) {
         hits.push({ file: rel, line: i + 1, content: lines[i].trim() });
         continue;
       }
-      // Multi-line form: `new RegExp(` ends the (comment-stripped) line with the
-      // open paren as the last token, and the pattern arg is on a following
-      // line. The single-line match above can't see the first-arg char, so it
-      // would silently pass a dynamic RegExp whose argument starts next line.
-      // Look ahead, skipping blank and comment-only lines (capped at 5), and
-      // inspect the first code line's first non-whitespace char.
+      // Multi-line form: the pattern arg starts on a later line, so look ahead
+      // past blank and comment-only lines, capped at 5.
       if (!/\bnew RegExp\s*\(\s*$/.test(code)) continue;
       let firstChar = null;
       for (let k = i + 1; k <= i + 5 && k < lines.length; k++) {
         const ahead = stripLineComment(lines[k]).replace(/^\s+/, "");
-        if (ahead === "") continue; // blank or comment-only — skip
+        if (ahead === "") continue;
         firstChar = ahead[0];
         break;
       }
-      // A `new RegExp(` with nothing parseable after it within the cap is
-      // suspicious — flag conservatively. Otherwise apply the SAME literal
-      // exemption as the single-line path.
+      // Nothing parseable within the cap is suspicious — flag it.
       if (firstChar !== null && isStaticRegexFirstChar(firstChar)) continue;
       hits.push({ file: rel, line: i + 1, content: lines[i].trim() });
     }
@@ -336,13 +270,9 @@ function detectDynamicRegex(files) {
   return filterMarkers(hits, "dynamic-regex");
 }
 
-// Raw bidi-override / zero-width / invisible / null codepoints embedded as
-// literals in source — the Trojan-Source class (CVE-2021-42574). A literal
-// such codepoint is invisible in review and can reorder or hide code. Source
-// should emit them programmatically (via vendor/blamejs/codepoint-class) or
-// escape them (\uXXXX), never type them literally. The range table holds only
-// numeric codepoints + the regex is built from escapes, so this detector's own
-// source is clean (and the file self-skips below regardless).
+// Raw bidi-override / zero-width / invisible / null codepoints typed as literals
+// — the Trojan-Source class (CVE-2021-42574). Source emits them via
+// vendor/blamejs/codepoint-class or a \uXXXX escape instead.
 const _BIDI_LITERAL_RANGES = [
   [0x202A, 0x202E], [0x2066, 0x2069], 0x200E, 0x200F, 0x061C, // bidi overrides + isolates
   0x200B, 0x200C, 0x200D, 0x00AD, 0x2060, 0xFEFF,             // zero-width / invisible
@@ -378,13 +308,8 @@ function detectOrphanAllowClass(files) {
       const cmt = lines[i].indexOf("//");
       if (cmt === -1) continue;
       const comment = lines[i].slice(cmt);
-      // Validate BOTH marker forms with the same class + reason rules:
-      //   per-line:    allow:<class> — <reason>
-      //   file-level:  codebase-patterns:allow-file <class> — <reason>
-      // The file-level form is the broadest exemption (it suppresses every hit
-      // of its class in the file), so a reason-less or unknown-class file-level
-      // marker must be caught here too — otherwise it would suppress silently
-      // and never reach the per-line orphan check.
+      // Both marker forms carry the same class + reason rules. The file-level
+      // form suppresses every hit of its class, so it must be caught here.
       const fileLevel = comment.match(/\bcodebase-patterns:allow-file\s+([a-z0-9-]+)\b(.*)$/);
       const perLine = comment.match(/\ballow:([a-z0-9-]+)\b(.*)$/);
       const m = fileLevel || perLine;
@@ -402,16 +327,11 @@ function detectOrphanAllowClass(files) {
   return hits;
 }
 
-// ---- opt-in readability detectors (preventative) -------------------------
-// These fire ONLY on sites that explicitly opt in via a marker, so unmarked
-// code is never flagged. They turn a one-time cleanup (sorting an allowlist,
-// aligning a const table) into a standing guarantee: mark the cleaned site and
-// the gate keeps it clean.
+// The two detectors below fire only on sites that opt in via a marker, so
+// unmarked code is never flagged.
 
-// `// keep-sorted` marks a flat string-literal array that must stay
-// alphabetically sorted (e.g. an allowlist). Only arrays whose opening line
-// carries the marker are checked; arrays containing object/nested elements are
-// skipped (not a flat string list).
+// `// keep-sorted` marks a flat string-literal array that must stay alphabetically
+// sorted; an array with object or nested elements is skipped.
 function scanUnsortedMarkedArray(rel, lines) {
   const hits = [];
   for (let i = 0; i < lines.length; i++) {
@@ -428,7 +348,7 @@ function scanUnsortedMarkedArray(rel, lines) {
       body += " " + seg;
       if (started && depth <= 0) break;
     }
-    if (/[{]/.test(body)) continue; // object/nested elements — not a flat string array
+    if (/[{]/.test(body)) continue;
     const strs = [];
     const re = /(['"])((?:\\.|(?!\1).)*)\1/g;
     let m;
@@ -452,9 +372,8 @@ function detectUnsortedMarkedArray(files) {
 }
 
 // `// keep-aligned` marks a contiguous run of `IDENT = value` / `IDENT: value`
-// lines (a const/weight table) whose assignment columns must all line up. The
-// run is the lines immediately after the marker, until a blank or non-assignment
-// line. Opt-in, so only deliberately-aligned tables are enforced.
+// lines whose assignment columns must all line up. The run starts at the line
+// after the marker and ends at the first blank or non-assignment line.
 function scanMisalignedMarkedRun(rel, lines) {
   const hits = [];
   for (let i = 0; i < lines.length; i++) {
@@ -487,22 +406,13 @@ function detectMisalignedMarkedRun(files) {
   return hits;
 }
 
-// ---- hand-rolled SQL in a file that talks to a database ------------------
-//
-// exceptd ships no database today, so this is a FORWARD guard: the moment a
-// file imports a SQL driver, any SQL STATEMENT (`"SELECT …"`) or CLAUSE built
-// by string concatenation (`… + " WHERE " + …`) is a parameterization/injection
-// sink and must use the driver's bound-parameter API instead. The SQL-driver
-// import is the gate — a SQL-looking string in a file with no driver executes
-// nothing, so prose that merely begins with "Update …" / "Delete …" in a
-// non-DB file is never scanned (no false positives). A trusted static DDL
-// string can opt out with `// allow:hand-rolled-sql — <reason>`.
+// Forward guard: the driver import is the gate, so prose merely beginning
+// "Update …" in a non-DB file is never scanned. In a file that does import one,
+// a statement or a concatenated clause is an injection sink.
 const SQL_DRIVER_IMPORT = /require\(\s*["'](?:node:sqlite|better-sqlite3|sqlite3|sqlite|pg|mysql2?|knex|sequelize|drizzle-orm|postgres|@libsql\/[\w.-]+)(?:\/[^"']*)?["']\s*\)|\bfrom\s+["'](?:node:sqlite|better-sqlite3|pg|mysql2?|knex|sequelize|drizzle-orm)(?:\/[^"']*)?["']/;
 const SQL_STMT_START = /(["'`])\s*(?:SELECT\b|INSERT\s+(?:INTO|OR)\b|REPLACE\s+INTO\b|UPDATE\s+["'`]?[A-Za-z_]|DELETE\s+FROM\b|CREATE\s+(?:TABLE|UNIQUE\s+INDEX|INDEX|TRIGGER|VIRTUAL\s+TABLE)\b|ALTER\s+TABLE\b|DROP\s+(?:TABLE|TRIGGER|INDEX)\b|MERGE\s+INTO\b)/i;
-// Trailing-concat form tolerates an embedded SQL string-quote inside the
-// clause (e.g. `" WHERE name = 'x' " + id`) by scanning to the first `+`
-// concatenation operator rather than requiring the clause string to close on
-// the same quote with no interior quotes.
+// The trailing-concat form tolerates a quote inside the clause
+// (`" WHERE name = 'x' " + id`) by scanning to the first `+`.
 const SQL_CLAUSE_FRAG = /(?:\+\s*["'`]\s*(?:SET|FROM|WHERE|VALUES|ORDER\s+BY|GROUP\s+BY|HAVING|RETURNING|LIMIT|OFFSET|ON\s+CONFLICT|(?:INNER\s+|LEFT\s+|RIGHT\s+|CROSS\s+)?JOIN)\b|["'`]\s*(?:SET|FROM|WHERE|VALUES\s*\(|ORDER\s+BY|GROUP\s+BY|HAVING|RETURNING|ON\s+CONFLICT|(?:INNER\s+|LEFT\s+|RIGHT\s+|CROSS\s+)?JOIN)\b[^+]*\+)/i;
 function detectHandRolledSql(files) {
   const hits = [];
@@ -564,11 +474,8 @@ const CLASSES = [
 ];
 
 function main() {
-  // Fail closed if the scan universe is empty. Each detector scopes to a subset
-  // of these roots and silently finds no hits when its root list is
-  // unreadable/empty — so a wholesale missing source tree would make every
-  // class report "clean" and the gate pass without scanning anything (the
-  // absent-input false-pass class). Refuse to call zero-files-scanned "clean".
+  // Fail closed on an empty scan universe: each detector silently finds no hits
+  // when its roots are unreadable. Zero files scanned is not "clean".
   const universe = filesUnder(["bin/exceptd.js", "lib", "orchestrator", "scripts"]);
   if (universe.length === 0) {
     console.error("[check-codebase-patterns] FAIL — zero source files found under bin/lib/orchestrator/scripts; refusing to report clean without scanning anything.");