@event4u/agent-config 16.5.0 → 17.0.0

package/src/scripts/check_claims.ts

@@ -117,6 +117,32 @@ const PUBLISH_SURFACES = [
     '.claude-plugin/marketplace.json',
 ];
 
+/**
+ * Trees whose files justify parked or refused work. A retired phrasing there is
+ * a rationale resting on a property the package no longer claims, so it is
+ * read like a publish surface; the archive is history and is not.
+ */
+const RATIONALE_DIRS = ['agents/roadmaps/later', 'agents/roadmaps/stubs', 'agents/settings/contexts'];
+
+function rationaleFiles(): string[] {
+    const out: string[] = [];
+    const walk = (rel: string): void => {
+        let entries: fs.Dirent[];
+        try {
+            entries = fs.readdirSync(path.join(REPO, rel), { withFileTypes: true });
+        } catch {
+            return;
+        }
+        for (const e of entries) {
+            const child = `${rel}/${e.name}`;
+            if (e.isDirectory()) walk(child);
+            else if (e.isFile() && e.name.endsWith('.md')) out.push(child);
+        }
+    };
+    for (const d of RATIONALE_DIRS) walk(d);
+    return out.sort();
+}
+
 /** The sentinel `retires_phrasings` value for a claim that never left the ledger. */
 const NEVER_PUBLISHED = 'never-published';
 
@@ -377,6 +403,17 @@ export interface LedgerEntry {
      * on legitimate prose and is muted within a release.
      */
     retires_phrasings: string;
+    /**
+     * REQUIRED on a `measured-in-repo` entry, forbidden elsewhere: the
+     * consumer-side evidence that would promote the row to `backed`.
+     *
+     * A finished bench or fixture reading of a consumer-facing mechanism, taken
+     * in the maintainer tree, is neither `backed` (nothing ran where the
+     * consumer stands) nor `unbacked` (the reading is finished, not owed).
+     * Without a named closure path the status is the dumping ground the ledger
+     * warns about, so the field is required rather than optional.
+     */
+    promotion_evidence: string;
     /**
      * Whether the `- retires_phrasings:` LINE exists at all, independent of
      * whether it carries a value.
@@ -438,6 +475,7 @@ function load_ledger(): Map<string, LedgerEntry> {
                 measured_on: cur.measured_on ?? '',
                 non_inference: cur.non_inference ?? '',
                 retires_phrasings: cur.retires_phrasings ?? '',
+                promotion_evidence: cur.promotion_evidence ?? '',
                 retires_phrasings_present: cur.retires_phrasings_present ?? false,
             });
         }
@@ -456,7 +494,7 @@ function load_ledger(): Map<string, LedgerEntry> {
         // would have silently ignored the second and dropped whichever field
         // came from the other branch. One union, both fields.
         const field = line.match(
-            /^-\s+(claim|kind|evidence|status|last_verified|superseded_by|retired_by|measured_on|non_inference|retires_phrasings):\s*(.*)$/,
+            /^-\s+(claim|kind|evidence|status|last_verified|superseded_by|retired_by|measured_on|non_inference|retires_phrasings|promotion_evidence):\s*(.*)$/,
         );
         if (field) {
             const key = field[1] as keyof LedgerEntry;
@@ -671,6 +709,42 @@ function main(argv: string[] = process.argv.slice(2)): number {
         }
     }
 
+    // 2c'. `measured-in-repo` — a finished in-repo reading of a consumer-facing
+    //      mechanism. It may not carry a public marker (rule 1 already refuses
+    //      every non-`backed` marker), and it must say what it measured on, keep
+    //      a resolving report pointer, and name the consumer-side evidence that
+    //      would promote it.
+    for (const entry of ledger.values()) {
+        if (entry.status !== 'measured-in-repo') {
+            if (entry.promotion_evidence) {
+                findings.push({
+                    id: entry.id,
+                    file: LEDGER_REL,
+                    reason: `promotion_evidence is only meaningful on a measured-in-repo entry (status: ${entry.status || 'missing'})`,
+                });
+            }
+            continue;
+        }
+        if (entry.promotion_evidence.length < 20) {
+            findings.push({
+                id: entry.id,
+                file: LEDGER_REL,
+                reason: 'measured-in-repo entry names no `promotion_evidence` — the consumer-side evidence that would make it `backed`',
+            });
+        }
+        if (!entry.measured_on) {
+            findings.push({
+                id: entry.id,
+                file: LEDGER_REL,
+                reason: 'measured-in-repo entry names no `measured_on` — the tree, corpus or environment the reading was taken on',
+            });
+        }
+        const un = pointer_unresolved(entry.evidence);
+        if (un) {
+            findings.push({ id: entry.id, file: LEDGER_REL, reason: `measured-in-repo entry has dangling evidence — ${un}` });
+        }
+    }
+
     // 2d. `retires_phrasings` — shape. A retirement that names no wording
     //     forbids no wording, and a wording too short to be specific forbids
     //     half the tree. Both are findings at any count; the COVERAGE question
@@ -777,10 +851,11 @@ function main(argv: string[] = process.argv.slice(2)): number {
             });
         }
     }
+    const scanned = usableNeedles.size > 0 ? [...liveSurfaces, ...rationaleFiles()] : liveSurfaces;
     for (const entry of ledger.values()) {
         const phrasings = usableNeedles.get(entry.id);
         if (phrasings === undefined) continue;
-        for (const rel of liveSurfaces) {
+        for (const rel of scanned) {
             const abs = path.join(REPO, rel);
             const body = fs.readFileSync(abs, 'utf8').toLowerCase();
             for (const ph of phrasings) {

package/src/scripts/check_completion_review.ts

@@ -52,6 +52,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { gitEnv } from './_lib/git_env.js';
 import { splitMarkdownRow } from './_lib/md_table.js';
 import { completionReviewDisabled } from './_lib/planning_settings.js';
+import { REVIEW_ROUND_CAP, checkReviewRound, countReviewPasses, type RecordedPasses } from './_lib/review_round.js';
 import { DeadScopeError, assertScanned } from './_lib/scan_scope.js';
 import {
     computeReviewScope,
@@ -62,6 +63,8 @@ import {
     type ParsedManifest,
 } from './dispatch_r2_reviewer.js';
 
+export { REVIEW_ROUND_CAP };
+
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
@@ -107,6 +110,17 @@ export interface Marker {
      * an attributable record instead of an absent one.
      */
     promptHash?: string;
+    /**
+     * OPTIONAL — the review round this artefact records (≥ 1): the number of
+     * review passes its path records, this one included.
+     *
+     * A fix pass re-binds the same artefact in place (§ 2.5), so before this
+     * field the number of rounds was agent-carried convention and nothing could
+     * count it. Absent reads as round 1, so every committed v1 artefact is valid
+     * unchanged; once any version carries it, the header must match the derived
+     * count (`round-miscounted`), and the cap applies (`round-cap-exceeded`).
+     */
+    round?: number;
 }
 
 export interface HonestNull {
@@ -325,7 +339,7 @@ export function isCodePath(p: string): boolean {
  * `| author: …` follow it without being swallowed.
  */
 const MARKER_RE =
-    /^<!--\s*completion-review:\s*v1\s*\|\s*reviewed:\s*(\d{4}-\d{2}-\d{2})\s*\|\s*scope:\s*([0-9a-fA-F]{64})\s*\|\s*diff:\s*([0-9a-fA-F]{7,40})\s*\|\s*reviewer:\s*(\S(?:[^|>]*[^|>\s])?)(?:\s*\|\s*author:\s*(\S(?:[^|>]*[^|>\s])?))?(?:\s*\|\s*prompt_hash:\s*([0-9a-fA-F]{64}))?\s*-->$/;
+    /^<!--\s*completion-review:\s*v1\s*\|\s*reviewed:\s*(\d{4}-\d{2}-\d{2})\s*\|\s*scope:\s*([0-9a-fA-F]{64})\s*\|\s*diff:\s*([0-9a-fA-F]{7,40})\s*\|\s*reviewer:\s*(\S(?:[^|>]*[^|>\s])?)(?:\s*\|\s*author:\s*(\S(?:[^|>]*[^|>\s])?))?(?:\s*\|\s*prompt_hash:\s*([0-9a-fA-F]{64}))?(?:\s*\|\s*round:\s*([1-9]\d*))?\s*-->$/;
 
 export function parseMarkerLine(line: string): Marker | null {
     const m = MARKER_RE.exec(line.trim());
@@ -344,6 +358,9 @@ export function parseMarkerLine(line: string): Marker | null {
     if (m[6] !== undefined) {
         marker.promptHash = m[6].toLowerCase();
     }
+    if (m[7] !== undefined) {
+        marker.round = Number(m[7]);
+    }
     return marker;
 }
 
@@ -995,6 +1012,10 @@ function evaluate(input: EvalInput): Violation[] {
                 detail: 'artifact has neither a findings table nor an honest-null / skip declaration line',
             });
         }
+        if (art.marker !== null) {
+            const rel = path.relative(repo, file).split(path.sep).join('/');
+            violations.push(...checkReviewRound(repo, file, art.marker, art.rows, recordedReviewPasses(repo, rel)));
+        }
     }
 
     if (relevant.length === 0) {
@@ -1030,6 +1051,18 @@ function evaluate(input: EvalInput): Violation[] {
     return violations;
 }
 
+/** Every review-artefact version committed at `rel`, read for {@link countReviewPasses}. */
+export function recordedReviewPasses(repo: string, rel: string): RecordedPasses {
+    const log = gitTry(repo, ['log', '--format=%H', '--', rel]);
+    const shas = log.stdout.split('\n').map((l) => l.trim()).filter(Boolean);
+    return countReviewPasses(
+        shas.map((sha) => {
+            const shown = gitTry(repo, ['show', `${sha}:${rel}`]);
+            return shown.ok ? parseArtifact(shown.stdout).marker : null;
+        }),
+    );
+}
+
 /** Contract §2.5 — the artifact's FIRST-add commit must precede every fix commit. */
 function checkFindingsBeforeFixes(repo: string, artifactAbs: string, rows: readonly FindingRow[]): Violation[] {
     const violations: Violation[] = [];

package/src/scripts/check_concern_admissions.ts

@@ -66,6 +66,16 @@ export const REQUIRED_ANSWERS = [
     'per_event_budget_impact',
 ] as const;
 
+/**
+ * Dispatcher stages that run like a concern but are not manifest keys, so the
+ * added-concern set difference cannot see them. Each needs a complete admitted
+ * row whenever its module exists — always, not only when newly added, because
+ * the list is closed and short and a stage has no grandfathered population.
+ */
+export const DISPATCHER_STAGES: readonly { id: string; source: string }[] = [
+    { id: 'egress-stage', source: 'src/scripts/hooks/egress_stage.ts' },
+];
+
 export const DECISIONS = ['admitted', 'rejected'] as const;
 export type Decision = (typeof DECISIONS)[number];
 
@@ -188,16 +198,18 @@ export function evaluate(root = REPO_ROOT, baseRef: string | null): Finding[] {
         }
     }
 
-    if (baseRef === null) return findings;
-
     const admitted = new Map(rows.filter((r) => r.decision === 'admitted').map((r) => [r.concern, r]));
-    for (const id of addedConcerns(root, baseRef)) {
+    const stages = DISPATCHER_STAGES.filter((s) => fs.existsSync(path.join(root, s.source))).map((s) => s.id);
+    const required = baseRef === null ? stages : [...stages, ...addedConcerns(root, baseRef)];
+    for (const id of required) {
         const row = admitted.get(id);
         if (row === undefined) {
             findings.push({
                 concern: id,
                 kind: 'missing_row',
-                message: `added since ${baseRef} with no \`admitted\` row in ${LEDGER_REL}`,
+                message: stages.includes(id)
+                    ? `dispatcher stage with no \`admitted\` row in ${LEDGER_REL}`
+                    : `added since ${String(baseRef)} with no \`admitted\` row in ${LEDGER_REL}`,
             });
             continue;
         }
@@ -248,7 +260,12 @@ function selfTest(): number {
     const script = path.join('src', 'scripts', 'check_concern_admissions.ts');
 
     /** A throwaway repo with a base commit and a working-tree change on top. */
-    const fixture = (opts: { base: readonly string[]; head: readonly string[]; ledger?: string }): number => {
+    const fixture = (opts: {
+        base: readonly string[];
+        head: readonly string[];
+        ledger?: string;
+        files?: readonly string[];
+    }): number => {
         const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ca-selftest-'));
         roots.push(dir);
         const g = (...a: string[]): void => {
@@ -267,6 +284,7 @@ function selfTest(): number {
         g('commit', '-q', '-m', 'base');
         put(CONCERN_MANIFEST_POSIX, MANIFEST(opts.head));
         if (opts.ledger !== undefined) put(LEDGER_REL, `${opts.ledger}\n`);
+        for (const rel of opts.files ?? []) put(rel, '');
         // repoRoot locates tsx AND resolves the relative script path, so it is
         // THIS checkout; cwd and --root are the fixture.
         return runGateCli(REPO_ROOT, script, ['--base', 'main', '--root', dir], dir);
@@ -301,6 +319,24 @@ function selfTest(): number {
             expect: 'reject',
             run: () => fixture({ base: ['one', 'two'], head: ['one', 'two'], ledger: ROW('two', 'rejected') }),
         },
+        {
+            // A dispatcher stage is not a manifest key, so the set difference
+            // cannot see it; its row is required whenever its module exists.
+            name: 'a dispatcher stage with no ledger row → reject',
+            expect: 'reject',
+            run: () => fixture({ base: ['one'], head: ['one'], files: [DISPATCHER_STAGES[0]!.source] }),
+        },
+        {
+            name: 'a dispatcher stage WITH a complete admitted row → accept',
+            expect: 'accept',
+            run: () =>
+                fixture({
+                    base: ['one'],
+                    head: ['one'],
+                    files: [DISPATCHER_STAGES[0]!.source],
+                    ledger: ROW(DISPATCHER_STAGES[0]!.id, 'admitted'),
+                }),
+        },
         {
             // The grandfathering, asserted rather than assumed: pre-existing
             // concerns must never demand a row.

package/src/scripts/check_consumer_scope_flip.ts

@@ -66,7 +66,7 @@ export function verify_flip(repoRoot = '.'): FlipVerdict {
     const template = parseYaml(fs.readFileSync(path.join(repoRoot, TEMPLATE), 'utf-8')) as Record<string, unknown>;
     const scope = ruleScopeFromSettings(template, repoRoot);
     if (scope.workspaces === null) {
-        throw new Error('template rule_workspaces is empty — nothing flipped, nothing to verify');
+        throw new Error('the derived consumer workspace set is empty — packs.yml unreadable, nothing to verify');
     }
     const rulesDir = path.join(repoRoot, RULES_DIR);
     const excluded = excludedRuleBasenames(rulesDir, scope);

package/src/scripts/check_context_paths.ts

@@ -245,6 +245,8 @@ function _check_orphans(contexts: string[], corpus: string, root: string): Viola
             rel_short,
             `](${base})`,
             `](./${base})`,
+            `](${base}#`,
+            `](./${base}#`,
         ];
         let own_text = '';
         try {

package/src/scripts/check_council_layout.ts

@@ -32,6 +32,12 @@ const CANONICAL_DIRS: readonly string[] = [
 ];
 // Top-level subdirectories exempt from the layout check.
 const EXEMPT_DIR_PREFIXES = ['audits', 'runtime'] as const;
+// Tracked evidence homes that may hold a council record deliberately kept as
+// evidence (AI council 2026-10-14, 2/2): a narrow allowlist, never the whole of
+// `evidence/`, because a retention class is not a placement licence.
+const EVIDENCE_COUNCIL_DIRS: readonly string[] = ['evidence/council', 'evidence/audits'];
+// A completion-review artefact is named after its branch slug.
+const REVIEW_FINDINGS_RE = /^evidence\/reviews\/council-[a-z0-9-]+\.findings\.md$/;
 // `council-` or `.council-` prefix (excludes `road-to-ai-council.md`).
 const COUNCIL_PREFIX_RE = /^\.?council-/;
 
@@ -138,6 +144,9 @@ function find_violations(root: string): string[] {
         if (EXEMPT_DIR_PREFIXES.some((d) => parts[0]!.startsWith(d))) {
             continue;
         }
+        if (EVIDENCE_COUNCIL_DIRS.some((d) => relPosix.startsWith(d + '/')) || REVIEW_FINDINGS_RE.test(relPosix)) {
+            continue;
+        }
         findings.push(
             `${_posix(p)}: council artefact in non-canonical directory ` +
                 `agents/${parts[0]}/ — only ` +

package/src/scripts/check_credential_spelling.ts

@@ -0,0 +1,267 @@
+#!/usr/bin/env tsx
+/**
+ * Within `src/scripts` and `src/cli`, the rule table is the only place a raw-key
+ * prefix is spelled. `src/server`, `src/shared`, `src/install`, skill scripts,
+ * test files and `fixtures/` directories are outside the scan.
+ *
+ * Every non-test TypeScript file under `src/scripts` and `src/cli` is read, from
+ * the filesystem rather than the index so a file not yet added is seen too; a
+ * code line outside `src/scripts/_lib/egress_rules.ts` (and its generated,
+ * equality-checked projection `egress_prefixes.ts`) that spells one of the
+ * table's declared prefixes at a token start fails. A second spelling is how the
+ * seven private copies of F2 drifted apart — one key shape caught by one
+ * consumer and passed unchanged by the next.
+ *
+ * What it sees: a prefix written as a literal, in a string or a regex, with
+ * backslash escapes removed first so `ya29\.` counts; a prefix spelled through a
+ * character class or an alternation (`gh[pousr]_`, `(sk|pk)-`) that expands to
+ * one of the table's prefixes; and a keyword-assignment shape — a credential
+ * keyword of the table's vocabulary and the `[:=]` operator class on one line
+ * (step 2.7). What it does not see: a shape assembled across lines, or a keyword
+ * spelled through a variable. A line that names a prefix in prose or as an inert
+ * fake value carries `not-a-credential-pattern: <reason>`; a bare marker does
+ * not mute.
+ *
+ * Exit: 0 one spelling · 1 a second spelling found.
+ */
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { CREDENTIAL_PREFIXES as PROJECTED } from './_lib/egress_prefixes.js';
+import { ASSIGNMENT_KEYWORDS, CREDENTIAL_PREFIXES, EGRESS_RULES } from './_lib/egress_rules.js';
+import { GateLedger } from './_lib/gate_ledger.js';
+import { runGateCli, runSelfTest } from './_lib/gate_self_test.js';
+import { reportScanned } from './_lib/scan_scope.js';
+
+const GATE = 'check_credential_spelling';
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+export const SCAN_DIRS: readonly string[] = ['src/scripts', 'src/cli'];
+export const OWNER = 'src/scripts/_lib/egress_rules.ts';
+/** The bundled projection of the table's prefix list, checked equal to it by its own test. */
+export const PROJECTION = 'src/scripts/_lib/egress_prefixes.ts';
+
+function walk(dir: string, out: string[]): void {
+    if (!fs.existsSync(dir)) return;
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+        const p = path.join(dir, e.name);
+        if (e.isDirectory()) {
+            if (e.name === 'node_modules' || e.name === 'fixtures') continue;
+            walk(p, out);
+        } else if (/\.(ts|mts)$/.test(e.name) && !/\.(test|spec)\.ts$/.test(e.name)) {
+            out.push(p);
+        }
+    }
+}
+
+const escapeRe = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/** A prefix at a token start; `task-` does not spell `sk-`. */
+function prefixSpelling(prefixes: readonly string[]): RegExp {
+    const alt = [...prefixes].sort((a, b) => b.length - a.length).map(escapeRe).join('|');
+    return new RegExp(`(?<![A-Za-z0-9])(?:${alt})`);
+}
+
+const NOT_A_PATTERN = /not-a-credential-pattern: \S/;
+
+// A quoted rule id names a row (`'xai-api-key'`); it is not a spelling of the
+// prefix it happens to start with, so it is removed before the line is judged.
+const RULE_ID = new RegExp(
+    `(['"\`])(?:${EGRESS_RULES.map((r) => escapeRe(r.rule)).join('|')})\\1`,
+    'g',
+);
+
+// One alternative of a class spelling: a stem with at most one character class.
+const CLASS_ALT = /^([a-z_]{1,16})(?:\[([a-z]{1,16})\])?$/;
+// What follows a class spelling: one separator, or a class of separators.
+const SEPARATOR = /^(?:\[[-_]{1,2}\]|[-_])/;
+const CLASS_GROUP = /\(([a-z_|[\]]{1,80})\)/g;
+const BARE_CLASS = /(?<![A-Za-z0-9_(|])([a-z]{1,16})\[([a-z]{1,16})\]/g;
+
+function expandAlt(alt: string): string[] {
+    const m = CLASS_ALT.exec(alt);
+    if (m === null) return [];
+    const stem = m[1] as string;
+    return m[2] === undefined ? [stem] : [...(m[2] as string)].map((c) => stem + c);
+}
+
+/** The table prefixes a class or alternation spelling on this line expands to. */
+export function classSpelledHits(code: string, prefixes: readonly string[] = CREDENTIAL_PREFIXES): string[] {
+    const hits = new Set<string>();
+    const judge = (stems: readonly string[], after: string): void => {
+        const sep = SEPARATOR.exec(after)?.[0];
+        if (sep === undefined) return;
+        const seps = sep.length === 1 ? [sep] : [...sep.slice(1, -1)];
+        for (const stem of stems) for (const c of seps) if (prefixes.includes(stem + c)) hits.add(stem + c);
+    };
+    for (const m of code.matchAll(CLASS_GROUP)) {
+        judge(
+            (m[1] as string).split('|').flatMap(expandAlt),
+            code.slice((m.index ?? 0) + m[0].length),
+        );
+    }
+    for (const m of code.matchAll(BARE_CLASS)) {
+        judge(expandAlt(`${m[1] as string}[${m[2] as string}]`), code.slice((m.index ?? 0) + m[0].length));
+    }
+    return [...hits];
+}
+
+const KEYWORD = new RegExp(Object.values(ASSIGNMENT_KEYWORDS).map(escapeRe).join('|'), 'i');
+const ASSIGNMENT_OPERATOR = /\[:=\]/;
+
+/** A keyword-assignment shape spelled on one line: a table keyword beside the `[:=]` operator class. */
+export function spellsAssignmentShape(code: string): boolean {
+    return ASSIGNMENT_OPERATOR.test(code) && KEYWORD.test(code);
+}
+
+/** 1-based lines that spell a prefix or a shape; comment lines and reasoned markers excluded. */
+export function offendingLines(text: string, prefixes: readonly string[] = CREDENTIAL_PREFIXES): number[] {
+    const re = prefixSpelling(prefixes);
+    const out: number[] = [];
+    text.split('\n').forEach((line, i) => {
+        const code = line.trim();
+        if (code.startsWith('//') || code.startsWith('*') || code.startsWith('/*')) return;
+        if (NOT_A_PATTERN.test(code)) return;
+        const bare = code.replace(RULE_ID, '');
+        if (
+            re.test(bare.replace(/\\/g, '')) ||
+            classSpelledHits(bare, prefixes).length > 0 ||
+            spellsAssignmentShape(bare)
+        ) {
+            out.push(i + 1);
+        }
+    });
+    return out;
+}
+
+/** Every `file:line` outside the table that spells a prefix, and the file count read. */
+export function findSpellings(root: string, ledger?: GateLedger): { hits: string[]; scanned: number } {
+    const files: string[] = [];
+    for (const d of SCAN_DIRS) walk(path.join(root, d), files);
+    const hits: string[] = [];
+    for (const f of files) {
+        const rel = path.relative(root, f).split(path.sep).join('/');
+        ledger?.plan(rel);
+        if (rel === OWNER || rel === PROJECTION) {
+            ledger?.outOfScope(rel, 'declared_exemption');
+            continue;
+        }
+        const lines = offendingLines(fs.readFileSync(f, 'utf-8'));
+        for (const line of lines) hits.push(`${rel}:${String(line)}`);
+        if (lines.length > 0) ledger?.fail(rel, `${String(lines.length)} spelling(s)`);
+        else ledger?.complete(rel);
+    }
+    return { hits, scanned: files.length };
+}
+
+export function check(root: string): number {
+    const ledger = new GateLedger(GATE);
+    const { hits, scanned } = findSpellings(root, ledger);
+    ledger.report();
+    reportScanned({ gate: GATE, scanned, units: 'TypeScript source file(s)', roots: [...SCAN_DIRS] });
+    if (JSON.stringify(PROJECTED) !== JSON.stringify(CREDENTIAL_PREFIXES)) {
+        process.stderr.write(`❌  ${GATE}: ${PROJECTION} no longer equals the table's prefix list — regenerate it.\n`);
+        return 1;
+    }
+    if (hits.length > 0) {
+        process.stderr.write(`❌  ${GATE}: a raw-key prefix is spelled outside ${OWNER}:\n`);
+        for (const h of hits) process.stderr.write(`  · ${h}\n`);
+        process.stderr.write(
+            '\nRead the shape from the table (prefixesOf, rawKeyPrefixPattern, detect) instead of spelling it,\n' +
+                'or mark an inert mention with `not-a-credential-pattern: <reason>`.\n',
+        );
+        return 1;
+    }
+    process.stdout.write(`✅  ${GATE}: one spelling — every raw-key prefix under ${SCAN_DIRS.join(', ')} lives in ${OWNER}.\n`);
+    return 0;
+}
+
+function selfTest(): number {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'credential-spelling-selftest-'));
+    const prefix = CREDENTIAL_PREFIXES.find((p) => p.endsWith('_')) ?? (CREDENTIAL_PREFIXES[0] as string);
+    const dotted = CREDENTIAL_PREFIXES.find((p) => p.includes('.')) ?? prefix;
+    const fixture = (name: string, rel: string, body: string): string => {
+        const root = path.join(tmp, name);
+        fs.mkdirSync(path.join(root, path.dirname(rel)), { recursive: true });
+        fs.writeFileSync(path.join(root, rel), body);
+        fs.mkdirSync(path.join(root, 'src/scripts'), { recursive: true });
+        fs.writeFileSync(path.join(root, 'src/scripts/clean.ts'), 'export const x = 1;\n');
+        return root;
+    };
+    const run = (root: string): number => runGateCli(REPO_ROOT, 'src/scripts/check_credential_spelling.ts', ['--root', root], root);
+    try {
+        return runSelfTest({
+            gate: GATE,
+            minCases: 8,
+            minRejectCases: 5,
+            cases: [
+                {
+                    name: 'a prefix spelled in a regex under src/scripts is rejected',
+                    expect: 'reject',
+                    run: () => run(fixture('regex', 'src/scripts/a.ts', `const RE = /${prefix}[A-Za-z0-9]{36}/;\n`)),
+                },
+                {
+                    name: 'a regex-escaped prefix under src/cli is rejected',
+                    expect: 'reject',
+                    run: () => run(fixture('escaped', 'src/cli/b.ts', `const P = ['${escapeRe(dotted)}', 'x'];\n`)),
+                },
+                {
+                    name: 'a bare marker with no reason does not mute',
+                    expect: 'reject',
+                    run: () => run(fixture('bare', 'src/scripts/c.ts', `const k = '${prefix}x'; // not-a-credential-pattern:\n`)),
+                },
+                {
+                    name: 'a reasoned marker mutes an inert value',
+                    expect: 'accept',
+                    run: () =>
+                        run(fixture('marked', 'src/scripts/d.ts', `const k = '${prefix}x'; // not-a-credential-pattern: fake\n`)),
+                },
+                {
+                    name: 'a prefix family spelled as a character class is rejected',
+                    expect: 'reject',
+                    run: () => run(fixture('class', 'src/scripts/e.ts', 'const RE = /\\b(gh[pousr]|x)[-_][A-Za-z0-9]{8,}/g;\n')), // not-a-credential-pattern: self-test fixture
+                },
+                {
+                    name: 'a keyword-assignment shape spelled outside the table is rejected',
+                    expect: 'reject',
+                    run: () => run(fixture('assign', 'src/cli/f.ts', 'const RE = /(?:password|api[_-]?key)\\s*[:=]\\s*\\S{8,}/i;\n')), // not-a-credential-pattern: self-test fixture
+                },
+                {
+                    name: 'a shape read from the table passes',
+                    expect: 'accept',
+                    run: () =>
+                        run(
+                            fixture(
+                                'reads',
+                                'src/scripts/g.ts',
+                                "const RE = assignmentPattern({ keywords: ['password'], value: '\\\\S{8,}' }, 'i');\n",
+                            ),
+                        ),
+                },
+                {
+                    name: 'a spelling inside the table itself passes',
+                    expect: 'accept',
+                    run: () => run(fixture('owner', OWNER, `const RE = /${prefix}[A-Za-z0-9]{36}/;\n`)),
+                },
+            ],
+        });
+    } finally {
+        fs.rmSync(tmp, { recursive: true, force: true });
+    }
+}
+
+export function main(argv: readonly string[]): number {
+    if (argv.includes('--help') || argv.includes('-h')) {
+        process.stdout.write(`usage: ${GATE} [--root DIR] [--self-test]\n`);
+        return 0;
+    }
+    if (argv.includes('--self-test')) return selfTest();
+    const i = argv.indexOf('--root');
+    return check(i === -1 ? REPO_ROOT : (argv[i + 1] ?? REPO_ROOT));
+}
+
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+    process.exit(main(process.argv.slice(2)));
+}