feat(governance): port #185 TS-allowlist regex+allowlist to Deno script (Layer 4b/4c) (#225)

## Summary

Owner picked #185's two-layer approach 2026-05-27. Both #183 and #185
were already closed since they targeted the eradicated Python heredoc.
This is the canonical port into the live Deno detector
(`scripts/check-ts-allowlist.ts`).

## Two changes

**1. Heading-regex relaxation in `loadExemptionsFromClaudeMd`**

Was: `/TypeScript [Ee]xemptions/` (literal).
Now:
`^#{1,4}\s+.*(?:TypeScript|JavaScript|TS|JS|\.tsx?)\b[^#\n]*[Ee]xemption`

Anchored to markdown heading prefix; matches every variant the estate
uses (`### TypeScript Exemptions`, `### TypeScript / JavaScript
Exemptions (Approved)`, `### TypeScript Exemption`, `### .ts Exemptions
...`). Multi-section: every heading scanned, supports multiple exemption
tables in one CLAUDE.md.

**2. New Layer 4c: `.governance-allowlist`**

Optional plain-text allowlist at the repo root. One glob per line,
`#`-comments supported. Decoupled from CLAUDE.md heading text →
gate-pass survives doc reformatting. Both sources merge additively.

## Files

- `scripts/check-ts-allowlist.ts` — `loadExemptionsFromClaudeMd`
(relaxed regex + multi-table) + new `loadExemptionsFromAllowlistFile` +
merged `loadExemptions`. Error message lists both options.
- `docs/EXEMPTION-MECHANISMS.adoc` — new "Layer 4: Governance
language-policy TS-allowlist" section with 4a/4b/4c breakdown,
pick-between guide, and historical context.

## Closes

Closes #183 (heading regex fix — chosen
approach).
Closes #185 (Layer 2.5 allowlist file — chosen
approach).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

docs/EXEMPTION-MECHANISMS.adoc

@@ -128,9 +128,113 @@ These have been attempted and should be refused at review:
   If a rule is wrong for one repo, the rule needs scoping in the
   upstream, not a fork.
 
+== Layer 4: Governance language-policy TS-allowlist
+
+A separate sub-system from Layers 1-3 (which gate the Hypatia
+scanner). This layer gates the `governance / Language / package
+anti-pattern policy` workflow step that enforces "no new TypeScript"
+across the estate. Three sub-layers:
+
+=== 4a: Built-in path / filename allowlist
+
+Hard-coded in `scripts/check-ts-allowlist.ts`. Covers paths that are
+*always* exempt regardless of per-repo configuration:
+
+* Directory segments: `bindings`, `tests`, `test`, `scripts`,
+  `mcp-adapter`, `cli`, `vendor`, `examples`, `ffi`, `node_modules`,
+  `benchmarks`.
+* Any segment containing `vscode` or starting with `deno-`.
+* Filename patterns: `*.d.ts`, `mod.ts`, `lsp-server.ts`, `lsp.ts`,
+  `*-lsp.ts`, `*.bench.ts`, `*_bench.ts`.
+
+Changing this layer requires a standards-repo PR.
+
+=== 4b: Per-repo `.claude/CLAUDE.md` heading-table
+
+Per-repo exemptions documented as a markdown table under a heading
+that contains both a language token and `Exemption[s]`. The
+heading-match regex is:
+
+----
+^#{1,4}\s+.*(?:TypeScript|JavaScript|TS|JS|\.tsx?)\b[^#\n]*[Ee]xemption
+----
+
+Matches all of:
+
+* `### TypeScript Exemptions (Approved)`
+* `### TypeScript / JavaScript Exemptions (Approved)`
+* `### TypeScript Exemption`
+* `### .ts Exemptions (foo bar)`
+
+Table rows have shape `| \`<glob>\` | <count> | <rationale> | <unblock-condition> |`.
+
+Multi-section: every heading on the page is scanned, so a repo can
+keep separate exemption tables (e.g. one for `.ts` bridge code, one
+for vendored test fixtures).
+
+Best for: exemptions whose *rationale* belongs in human-readable
+documentation alongside the prose explaining why the repo exists.
+
+=== 4c: `.governance-allowlist` (typed infrastructure file)
+
+Optional plain-text file at the repo root. One glob per line. Lines
+starting with `#` are comments. Blank lines are ignored.
+
+----
+# Telegram bot binding (no AffineScript binding planned)
+avow-protocol/telegram-bot/avow-telegram-bot/**
+
+# Bench harness fixtures
+test/perf/fixtures/*.ts
+----
+
+Best for: exemptions that are *infrastructure config* (typed,
+machine-validated) rather than human-readable rationale prose. Pairs
+cleanly with the estate's "machine-readable everywhere" trajectory.
+Decoupled from CLAUDE.md heading text so reformatting the docs
+doesn't accidentally break the gate.
+
+Both 4b and 4c are additive — declaring an exemption in either is
+sufficient. Most repos will pick one or the other.
+
+=== Picking between 4b and 4c
+
+[cols="1,3,3"]
+|===
+| Layer | Use when | Avoid when
+
+| 4b (CLAUDE.md table)
+| The exemption needs human-readable rationale next to the glob.
+  Reviewers reading CLAUDE.md should immediately understand *why*.
+| The repo's CLAUDE.md is large and heading-text drift breaks the
+  gate.
+
+| 4c (`.governance-allowlist`)
+| The exemption is structural and the rationale belongs elsewhere
+  (tracked in an issue / ADR / commit message). Or the repo wants
+  the gate-pass list to live in version-controlled infrastructure
+  rather than prose.
+| The exemption is one-off and CLAUDE.md prose is the right home.
+|===
+
+=== History
+
+* Original implementation: inline Python heredoc in
+  `governance-reusable.yml`, regex literal `TypeScript [Ee]xemptions`.
+  Failed silently on every `affinescript`-style heading (the slash and
+  `JavaScript` between keywords meant the regex never matched, and 3
+  legitimate exemptions were dropped → gate red on every PR).
+* Python eradication (standards#189): ported to
+  `scripts/check-ts-allowlist.ts`. Brittle regex carried over.
+* Layer 4b fix + Layer 4c introduction (2026-05-27): regex relaxation
+  + new typed-infrastructure file. Owner picked the Layer-2.5 approach
+  (standards#185) over the minimal regex-only fix (standards#183).
+  This document seeds the doctrine.
+
 == Cross-references
 
 * `docs/HYPATIA-BASELINE-FORMAT.adoc` — the baseline file format.
 * `.machine_readable/hypatia-baseline.schema.json` — machine schema.
+* `scripts/check-ts-allowlist.ts` — the Deno detector behind Layer 4.
 * `hyperpolymath/standards#????` — proposal that landed this consumer.
 * `hyperpolymath/hypatia` — the scanner that emits findings.

scripts/check-ts-allowlist.ts

@@ -72,19 +72,44 @@ function globToRegex(g: string): RegExp {
 
 interface Exemption { raw: string; rx: RegExp; }
 
-async function loadExemptions(): Promise<Exemption[]> {
+async function loadExemptionsFromClaudeMd(): Promise<Exemption[]> {
+  // Layer 2 — heading-table exemptions parsed from `.claude/CLAUDE.md`.
+  //
+  // Heading regex relaxation (was: literal `TypeScript [Ee]xemptions`):
+  // now matches any markdown heading containing the substring sequence
+  // (TypeScript|JavaScript|TS|JS|.tsx?) … Exemption(s). Picks up
+  // `### TypeScript / JavaScript Exemptions (Approved)` (the
+  // affinescript form), the singular `### TypeScript Exemption`, and
+  // `.ts` / `.tsx`-mentioning variants. Anchored to a markdown heading
+  // prefix so prose mentions of the phrase elsewhere in the file do
+  // NOT trigger table parsing.
+  //
+  // Multi-table support: scans every heading; on hitting any heading
+  // that's NOT an exemption-section heading we leave table-mode (the
+  // original "break on first heading" was correct for the heredoc but
+  // a multi-section file would miss the second exemption table).
   const exemptions: Exemption[] = [];
   let text: string;
   try {
     text = await Deno.readTextFile(".claude/CLAUDE.md");
   } catch {
     return exemptions;
   }
+  const tsHeading =
+    /^#{1,4}\s+.*(?:TypeScript|JavaScript|TS|JS|\.tsx?)\b[^#\n]*[Ee]xemption/;
+  const anyHeading = /^#{1,4}\s/;
   let inTable = false;
-  const headingRx = /TypeScript [Ee]xemptions/;
   for (const line of text.split("\n")) {
-    if (headingRx.test(line)) { inTable = true; continue; }
-    if (inTable && (line.startsWith("### ") || line.startsWith("## ") || line.startsWith("# "))) break;
+    if (tsHeading.test(line)) {
+      inTable = true;
+      continue;
+    }
+    if (inTable && anyHeading.test(line)) {
+      // A different heading — leave table mode but keep scanning for
+      // another exemption section in the same file.
+      inTable = false;
+      continue;
+    }
     if (inTable && line.startsWith("|")) {
       const m = line.match(/^\|\s*`([^`]+)`/);
       if (m) {
@@ -95,6 +120,34 @@ async function loadExemptions(): Promise<Exemption[]> {
   return exemptions;
 }
 
+async function loadExemptionsFromAllowlistFile(): Promise<Exemption[]> {
+  // Layer 2.5 — optional plain-text allowlist at the repo root.
+  // One glob per line. Lines starting with `#` are comments; blank
+  // lines are ignored. Decouples gate-pass from documentation prose
+  // (the CLAUDE.md heading-table is the documented variant; this
+  // file is the typed-infrastructure variant). Both sources merge
+  // additively — either alone is sufficient.
+  const exemptions: Exemption[] = [];
+  let text: string;
+  try {
+    text = await Deno.readTextFile(".governance-allowlist");
+  } catch {
+    return exemptions;
+  }
+  for (const rawLine of text.split("\n")) {
+    const line = rawLine.trim();
+    if (line === "" || line.startsWith("#")) continue;
+    exemptions.push({ raw: line, rx: globToRegex(line) });
+  }
+  return exemptions;
+}
+
+async function loadExemptions(): Promise<Exemption[]> {
+  const fromCm = await loadExemptionsFromClaudeMd();
+  const fromAllow = await loadExemptionsFromAllowlistFile();
+  return [...fromCm, ...fromAllow];
+}
+
 function exempt(p: string, exemptions: Exemption[]): boolean {
   for (const e of exemptions) {
     if (e.rx.test(p)) return true;
@@ -138,13 +191,16 @@ async function main() {
     console.log("To resolve, choose one:");
     console.log("  (a) migrate the file to AffineScript");
     console.log("  (b) move to an allowlisted bridge path");
-    console.log("  (c) add an entry to the 'TypeScript Exemptions' table in .claude/CLAUDE.md");
+    console.log("  (c) add an entry to a 'TypeScript Exemptions' table in .claude/CLAUDE.md (Layer 2)");
+    console.log("  (d) add a line to .governance-allowlist at the repo root (Layer 2.5 — typed infrastructure file)");
+    console.log("");
+    console.log("See docs/EXEMPTION-MECHANISMS.adoc for the full mechanism reference.");
     if (exemptions.length > 0) {
-      console.log(`\n(Currently ${exemptions.length} exemption(s) parsed from .claude/CLAUDE.md.)`);
+      console.log(`\n(Currently ${exemptions.length} exemption(s) parsed across both layers.)`);
     }
     Deno.exit(1);
   }
-  console.log(`✅ No TypeScript files outside allowlist (${exemptions.length} per-repo exemption(s) parsed).`);
+  console.log(`✅ No TypeScript files outside allowlist (${exemptions.length} per-repo exemption(s) parsed across CLAUDE.md + .governance-allowlist).`);
 }
 
 if (import.meta.main) {