@event4u/agent-config 9.28.0 → 9.30.0

package/src/scripts/bench_hook_injection.ts

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+/**
+ * Hook-injection byte bench + CI gate (road-to-token-economy-cache Phase 3.2)
+ * — the latency harness's twin for the INJECTION side.
+ *
+ * Runs every concern bound on the `claude` platform against the committed
+ * fixture envelope of each slot it is bound to (tests/fixtures/hooks/
+ * <event>.json), in-process via CONCERN_REGISTRY with the hook-stdin
+ * override, under AGENT_CONFIG_REPLAY=1 (state writes skipped). Measures the
+ * bytes of the stdout payload fields a concern injects — `reason` +
+ * `additional_context` + `context` — and gates them against
+ * `src/config/hook-token-budget.json`:
+ *
+ *   - a concern whose emission exceeds its row (or the default cap) → RED
+ *   - an EMITTING concern with no explicit row above the default is fine;
+ *     the default cap IS its row — but a breach names the missing row so
+ *     the fix is a registered decision, not a silent default bump
+ *   - per-slot SUM over all bound concerns > the slot cap → RED
+ *
+ * HONEST SCOPE, stated up front: concerns are conditional-silence by design —
+ * a generic fixture triggers few of them, so most measure 0 bytes here. The
+ * gate therefore enforces the cap on whatever DOES fire under the committed
+ * fixtures (deterministic, CI-reproducible), while the census mode
+ * (`--record`) measures REAL sessions: it appends counts-only lines
+ * ({ts, slot, concern, bytes}) to agents/runtime/state/injection-census.jsonl
+ * — the repeat-injection-census blocker's instrument. Claiming the fixture
+ * numbers are the live distribution would be the coverage inflation this
+ * repo's gate discipline refuses; the two modes exist because neither
+ * substitutes for the other.
+ *
+ * Class A: in-process, no daemon, no network. Exit 0 green · 1 breach ·
+ * 2 unusable invocation. Dead-scope guarded: zero concerns run = RED.
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/bench_hook_injection [--format text|json]
+ *     [--record] [--platform claude]
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { CONCERN_REGISTRY } from './hooks/concern_registry.js';
+import { setHookStdinOverride, clearHookStdinOverride } from './hooks/hook_stdin.js';
+import { _load_yaml, _resolve_concerns, EVENT_VOCABULARY, type JsonObject } from './hooks/dispatch_hook.js';
+
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+const _IN_BUNDLE = typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__;
+const REPO_ROOT = path.resolve(
+    path.dirname(fileURLToPath(import.meta.url)),
+    ...(_IN_BUNDLE ? ['..'] : ['..', '..']),
+);
+const MANIFEST = path.join(REPO_ROOT, 'src', 'scripts', 'hook_manifest.yaml');
+const BUDGET = path.join(REPO_ROOT, 'src', 'config', 'hook-token-budget.json');
+const FIXTURES = path.join(REPO_ROOT, 'tests', 'fixtures', 'hooks');
+const CENSUS_FILE = path.join('agents', 'runtime', 'state', 'injection-census.jsonl');
+
+export interface Measurement {
+    slot: string;
+    concern: string;
+    bytes: number;
+    cap: number;
+    breach: boolean;
+}
+
+interface Budget {
+    default_cap_bytes: number;
+    per_concern_caps_bytes: Record<string, number | string>;
+    per_slot_sum_caps_bytes: Record<string, number | string>;
+}
+
+function capFor(budget: Budget, concern: string): number {
+    const v = budget.per_concern_caps_bytes[concern];
+    return typeof v === 'number' ? v : budget.default_cap_bytes;
+}
+
+/** Run one registered concern in-process with the fixture envelope; return payload bytes. */
+export function runConcernOnce(
+    script: string,
+    args: readonly string[],
+    envelope: JsonObject,
+): number {
+    const main = CONCERN_REGISTRY[script];
+    if (main === undefined) return -1; // not in registry — parity tests own that failure
+    let out = '';
+    const prevWrite = process.stdout.write;
+    const prevErr = process.stderr.write;
+    const prevArgv = process.argv;
+    const prevReplay = process.env['AGENT_CONFIG_REPLAY'];
+    setHookStdinOverride(JSON.stringify(envelope));
+    process.env['AGENT_CONFIG_REPLAY'] = '1';
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    process.stdout.write = ((chunk: any, enc?: any, cb?: any): boolean => {
+        out += typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf-8');
+        const callback = typeof enc === 'function' ? enc : cb;
+        if (typeof callback === 'function') callback();
+        return true;
+    }) as typeof process.stdout.write;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    process.stderr.write = ((chunk: any, enc?: any, cb?: any): boolean => {
+        const callback = typeof enc === 'function' ? enc : cb;
+        if (typeof callback === 'function') callback();
+        return true;
+    }) as typeof process.stderr.write;
+    try {
+        process.argv = [prevArgv[0] as string, script, ...args, '--platform', 'claude'];
+        main([...args, '--platform', 'claude']);
+    } catch {
+        /* a crashing concern injects nothing — latency/parity suites own crashes */
+    } finally {
+        process.stdout.write = prevWrite;
+        process.stderr.write = prevErr;
+        process.argv = prevArgv;
+        if (prevReplay === undefined) delete process.env['AGENT_CONFIG_REPLAY'];
+        else process.env['AGENT_CONFIG_REPLAY'] = prevReplay;
+        clearHookStdinOverride();
+    }
+    const text = out.trim();
+    if (!text) return 0;
+    try {
+        const parsed = JSON.parse(text) as Record<string, unknown>;
+        let bytes = 0;
+        for (const key of ['reason', 'additional_context', 'context']) {
+            const v = parsed[key];
+            if (typeof v === 'string') bytes += Buffer.byteLength(v, 'utf-8');
+        }
+        return bytes;
+    } catch {
+        return Buffer.byteLength(text, 'utf-8'); // non-JSON stdout counts whole
+    }
+}
+
+export function bench(opts: { platform?: string; budgetPath?: string } = {}): { measurements: Measurement[]; slotSums: Record<string, { bytes: number; cap: number; breach: boolean }>; errors: string[] } {
+    const platform = opts.platform ?? 'claude';
+    const manifest = _load_yaml(MANIFEST);
+    const budget = JSON.parse(fs.readFileSync(opts.budgetPath ?? BUDGET, 'utf8')) as Budget;
+    const measurements: Measurement[] = [];
+    const slotSums: Record<string, { bytes: number; cap: number; breach: boolean }> = {};
+    const errors: string[] = [];
+
+    for (const event of EVENT_VOCABULARY) {
+        const fixtureFile = path.join(FIXTURES, `${event}.json`);
+        if (!fs.existsSync(fixtureFile)) continue;
+        const envelope = JSON.parse(fs.readFileSync(fixtureFile, 'utf8')) as JsonObject;
+        const concerns = _resolve_concerns(manifest, platform, event);
+        let sum = 0;
+        for (const concern of concerns) {
+            const bytes = runConcernOnce(String(concern['script']), Array.isArray(concern['args']) ? concern['args'].map(String) : [], envelope);
+            if (bytes < 0) {
+                errors.push(`${event}/${String(concern['name'])}: not in CONCERN_REGISTRY`);
+                continue;
+            }
+            const cap = capFor(budget, String(concern['name']));
+            const breach = bytes > cap;
+            measurements.push({ slot: event, concern: String(concern['name']), bytes, cap, breach });
+            sum += bytes;
+        }
+        const slotCapRaw = budget.per_slot_sum_caps_bytes[event];
+        const slotCap = typeof slotCapRaw === 'number' ? slotCapRaw : Number.MAX_SAFE_INTEGER;
+        slotSums[event] = { bytes: sum, cap: slotCap, breach: sum > slotCap };
+    }
+    return { measurements, slotSums, errors };
+}
+
+export function main(argv: readonly string[]): number {
+    let format: 'text' | 'json' = 'text';
+    let record = false;
+    let platform = 'claude';
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--format') format = argv[++i] === 'json' ? 'json' : 'text';
+        else if (a === '--record') record = true;
+        else if (a === '--platform') platform = argv[++i] ?? platform;
+    }
+    let result: ReturnType<typeof bench>;
+    try {
+        result = bench({ platform });
+    } catch (err) {
+        process.stderr.write(`bench_hook_injection: ${err instanceof Error ? err.message : String(err)}\n`);
+        return 2;
+    }
+    // Dead-scope guard: a bench that ran zero concerns proves nothing (a
+    // gate that scans nothing exits green is the recorded failure class).
+    if (result.measurements.length === 0) {
+        process.stderr.write('bench_hook_injection: DEAD SCOPE — zero concerns ran; fixtures or manifest unreadable\n');
+        return 1;
+    }
+    if (record) {
+        try {
+            const file = path.join(process.cwd(), CENSUS_FILE);
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+            const ts = new Date().toISOString();
+            for (const m of result.measurements) {
+                if (m.bytes > 0) {
+                    fs.appendFileSync(file, JSON.stringify({ ts, slot: m.slot, concern: m.concern, bytes: m.bytes }) + '\n');
+                }
+            }
+        } catch {
+            /* census is observability — never fails the bench */
+        }
+    }
+    const breaches = result.measurements.filter((m) => m.breach);
+    const slotBreaches = Object.entries(result.slotSums).filter(([, s]) => s.breach);
+    if (format === 'json') {
+        process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    } else {
+        const emitting = result.measurements.filter((m) => m.bytes > 0);
+        process.stdout.write(`bench_hook_injection: ${result.measurements.length} concern-slot pairs · ${emitting.length} emitted under the committed fixtures\n`);
+        for (const m of emitting) {
+            process.stdout.write(`  ${m.slot.padEnd(20)} ${m.concern.padEnd(24)} ${String(m.bytes).padStart(6)} B (cap ${m.cap})${m.breach ? '  ❌ BREACH' : ''}\n`);
+        }
+        for (const [slot, s] of Object.entries(result.slotSums)) {
+            if (s.bytes > 0) process.stdout.write(`  slot-sum ${slot.padEnd(20)} ${String(s.bytes).padStart(6)} B (cap ${s.cap === Number.MAX_SAFE_INTEGER ? '—' : s.cap})${s.breach ? '  ❌ BREACH' : ''}\n`);
+        }
+        for (const e of result.errors) process.stdout.write(`  warn: ${e}\n`);
+    }
+    if (breaches.length > 0 || slotBreaches.length > 0) {
+        process.stderr.write(`bench_hook_injection: ${breaches.length} concern breach(es), ${slotBreaches.length} slot-sum breach(es) — the budget row is the decision surface (src/config/hook-token-budget.json)\n`);
+        return 1;
+    }
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    if (_IN_BUNDLE) return false;
+    if (process.argv[1] === undefined) return false;
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) return true;
+    try {
+        return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+if (_isCliEntry()) process.exit(main(process.argv.slice(2)));

package/src/scripts/check_adr_frontmatter.ts

@@ -35,6 +35,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { GateLedger } from './_lib/gate_ledger.js';
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = path.dirname(fileURLToPath(import.meta.url));
@@ -101,48 +102,81 @@ export function trigger_is_meaningful(value: string): boolean {
     return true;
 }
 
-export function check(dir: string = ADR_DIR): AdrFinding[] {
+/** Every frontmatter finding for one ADR file. Pure — no I/O, no enumeration. */
+export function check_one(rel: string, text: string): AdrFinding[] {
+    const findings: AdrFinding[] = [];
+    const fm = parse_frontmatter(text);
+
+    if (fm === null) {
+        findings.push({ file: rel, level: 'error', message: 'no YAML frontmatter block' });
+        return findings;
+    }
+    for (const req of REQUIRED) {
+        if (!fm[req]) findings.push({ file: rel, level: 'error', message: `missing \`${req}\`` });
+    }
+    if (fm['status'] && !ALLOWED_STATUS.has(fm['status'])) {
+        findings.push({
+            file: rel,
+            level: 'error',
+            message: `status \`${fm['status']}\` is not one of: ${[...ALLOWED_STATUS].sort().join(', ')}`,
+        });
+    }
+
+    const date = fm['date'] ?? '';
+    const grandfathered = date !== '' && date < REVIEW_TRIGGER_SINCE;
+    const trigger = fm['review_trigger'];
+
+    if (!trigger) {
+        findings.push({
+            file: rel,
+            level: grandfathered ? 'warn' : 'error',
+            message: grandfathered
+                ? `no \`review_trigger\` (grandfathered — dated ${date}, before ${REVIEW_TRIGGER_SINCE})`
+                : `missing \`review_trigger\` — name the CONDITION that would reopen this decision`,
+        });
+    } else if (!trigger_is_meaningful(trigger)) {
+        findings.push({
+            file: rel,
+            level: grandfathered ? 'warn' : 'error',
+            message: `\`review_trigger\` is a cadence, not a condition: "${trigger}". A calendar review is ignored; an event fires.`,
+        });
+    }
+    return findings;
+}
+
+/**
+ * Check every ADR in `dir`, optionally recording per-file completeness.
+ *
+ * The candidate set is every `*.md` in the directory, not the `ADR-*.md` subset:
+ * the name filter used to be a bare `continue`, so a decision record saved as
+ * `adr-131-foo.md` (lower case) or `131-foo.md` left the corpus without a trace
+ * and the gate still printed a green line over the files it did read. It is now
+ * an out-of-scope outcome with a reason, and it prints.
+ *
+ * A `warn`-level finding resolves as `complete`: warnings are allowed by this
+ * gate's exit-code contract, so `fail` is reserved for what actually reds it.
+ */
+export function check(dir: string = ADR_DIR, ledger?: GateLedger): AdrFinding[] {
     const findings: AdrFinding[] = [];
     if (!fs.existsSync(dir)) return findings;
 
-    for (const name of fs.readdirSync(dir).sort()) {
-        if (!/^ADR-.*\.md$/.test(name)) continue;
-        const rel = path.relative(REPO_ROOT, path.join(dir, name));
-        const fm = parse_frontmatter(fs.readFileSync(path.join(dir, name), 'utf-8'));
+    const candidates = fs.readdirSync(dir).filter((n) => n.endsWith('.md')).sort();
+    ledger?.plan(candidates);
 
-        if (fm === null) {
-            findings.push({ file: rel, level: 'error', message: 'no YAML frontmatter block' });
+    for (const name of candidates) {
+        if (!/^ADR-.*\.md$/.test(name)) {
+            ledger?.outOfScope(name, 'not_applicable_kind');
             continue;
         }
-        for (const req of REQUIRED) {
-            if (!fm[req]) findings.push({ file: rel, level: 'error', message: `missing \`${req}\`` });
-        }
-        if (fm['status'] && !ALLOWED_STATUS.has(fm['status'])) {
-            findings.push({
-                file: rel,
-                level: 'error',
-                message: `status \`${fm['status']}\` is not one of: ${[...ALLOWED_STATUS].sort().join(', ')}`,
-            });
-        }
+        const rel = path.relative(REPO_ROOT, path.join(dir, name));
+        const own = check_one(rel, fs.readFileSync(path.join(dir, name), 'utf-8'));
+        findings.push(...own);
 
-        const date = fm['date'] ?? '';
-        const grandfathered = date !== '' && date < REVIEW_TRIGGER_SINCE;
-        const trigger = fm['review_trigger'];
-
-        if (!trigger) {
-            findings.push({
-                file: rel,
-                level: grandfathered ? 'warn' : 'error',
-                message: grandfathered
-                    ? `no \`review_trigger\` (grandfathered — dated ${date}, before ${REVIEW_TRIGGER_SINCE})`
-                    : `missing \`review_trigger\` — name the CONDITION that would reopen this decision`,
-            });
-        } else if (!trigger_is_meaningful(trigger)) {
-            findings.push({
-                file: rel,
-                level: grandfathered ? 'warn' : 'error',
-                message: `\`review_trigger\` is a cadence, not a condition: "${trigger}". A calendar review is ignored; an event fires.`,
-            });
+        const errors = own.filter((f) => f.level === 'error').length;
+        if (errors > 0) {
+            ledger?.fail(name, `${String(errors)} frontmatter error(s)`);
+        } else {
+            ledger?.complete(name);
         }
     }
     return findings;
@@ -150,10 +184,17 @@ export function check(dir: string = ADR_DIR): AdrFinding[] {
 
 function main(argv: string[]): number {
     const as_json = argv.includes('--json');
-    const findings = check();
-    const total = fs.existsSync(ADR_DIR)
-        ? fs.readdirSync(ADR_DIR).filter((f) => /^ADR-.*\.md$/.test(f)).length
-        : 0;
+    const ledger = new GateLedger('check_adr_frontmatter');
+    const findings = check(ADR_DIR, ledger);
+    // Finalized here, printed later by `report()` (which re-finalizes — the call
+    // is pure): the denominator is needed for the scope assertion below, which
+    // runs before any output. It is the ledger's own per-file accounting — the
+    // ADRs that actually reached a checked outcome — where it used to be a SECOND
+    // `readdirSync` of the same directory, independent of the loop that did the
+    // work, so the printed count could not disagree with the scan even when the
+    // scan had skipped files.
+    const tally = ledger.finalize();
+    const total = tally.completed + tally.failed;
 
     // `check()` returns findings, never a count, so a moved `docs/decisions/`
     // yields an empty list — reported as "0 ADR(s) · 0 error(s)" and green.
@@ -174,7 +215,9 @@ function main(argv: string[]): number {
     }
 
     if (as_json) {
-        process.stdout.write(JSON.stringify({ findings }, null, 2) + '\n');
+        // The tally rides in the payload rather than on stdout: `ledger.report()`
+        // would print beside the JSON and break every parser of this mode.
+        process.stdout.write(JSON.stringify({ findings, ledger: tally }, null, 2) + '\n');
         return 0;
     }
 
@@ -185,6 +228,7 @@ function main(argv: string[]): number {
         `ADR frontmatter: ${total} ADR(s) · ${errors.length} error(s) · ` +
             `${warns.length} grandfathered without a revisit condition\n`,
     );
+    ledger.report();
     for (const e of errors) process.stderr.write(`    ❌ ${e.file}: ${e.message}\n`);
 
     if (errors.length > 0) {

package/src/scripts/check_branch_freshness.ts

@@ -41,6 +41,7 @@ import { fileURLToPath } from "node:url";
 import { runGateCli, runSelfTest, type SelfTestCase } from "./_lib/gate_self_test.js";
 import { reportScanned } from "./_lib/scan_scope.js";
 
+// ledger-exempt: single remote-ref probe — the entire scope is ONE ls-remote answer (0 or 1 refs) resolved to one aggregate ancestor verdict, and every empty path already publishes its reason via reportScanned allowEmpty; there is no per-target collection to account.
 const DEFAULT_BASE = "main";
 const SELF_TEST_MIN_CASES = 3;
 const SELF_TEST_MIN_REJECT = 1;

package/src/scripts/check_corpus_staleness.ts

@@ -49,6 +49,7 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { GateLedger } from './_lib/gate_ledger.js';
 import { runGateCli, runSelfTest } from './_lib/gate_self_test.js';
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
@@ -423,20 +424,32 @@ export interface RunResult {
     readonly corpora: number;
     /** CSVs actually opened, reported so "checked nothing" cannot read as clean. */
     readonly csvs: number;
+    /** Per-corpus completeness accounting — every discovered corpus reaches one outcome. */
+    readonly ledger: GateLedger;
 }
 
 export function run_checks(todayStamp: number, skillsDir: string = SKILLS_DIR): RunResult {
     const corpora = discover_corpora(skillsDir);
+    const ledger = new GateLedger('check_corpus_staleness');
+    ledger.plan(corpora.map((c) => c.slug));
     const findings: CorpusFinding[] = [];
     let csvs = 0;
     for (const corpus of corpora) {
-        findings.push(...check_staleness(corpus, todayStamp));
-        findings.push(...check_attribution_pin(corpus));
+        const found: CorpusFinding[] = [
+            ...check_staleness(corpus, todayStamp),
+            ...check_attribution_pin(corpus),
+        ];
         const csv = check_csv_integrity(corpus);
-        findings.push(...csv.findings);
+        found.push(...csv.findings);
         csvs += csv.opened;
+        findings.push(...found);
+        if (found.length > 0) {
+            ledger.fail(corpus.slug, `${String(found.length)} corpus finding(s)`);
+        } else {
+            ledger.complete(corpus.slug);
+        }
     }
-    return { findings, corpora: corpora.length, csvs };
+    return { findings, corpora: corpora.length, csvs, ledger };
 }
 
 const HELP = `check_corpus_staleness — offline staleness + CSV-integrity gate for the grounding corpora
@@ -651,6 +664,7 @@ export function main(argv: string[] = process.argv.slice(2)): number {
 
     // gate-coverage contract (src/config/gate-coverage.yml): corpora inspected.
     process.stdout.write(`scanned: ${String(result.corpora)}\n`);
+    result.ledger.report();
 
     if (result.findings.length > 0) {
         process.stdout.write(`❌  ${String(result.findings.length)} corpus finding(s):\n`);

package/src/scripts/check_detector_corpus.ts

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+/**
+ * Detector corpus gate (P4.3 of road-to-rule-delivery-integrity).
+ *
+ * Every self-repair detector must carry all THREE fixture classes, and every
+ * fixture must behave as its class says:
+ *
+ *   fire            a recorded real failure the detector must catch
+ *   near-miss-fire  a real failure phrased unlike the canonical one, which must
+ *                   still be caught — recall at the boundary
+ *   must-not-fire   text that superficially matches and must stay silent
+ *
+ * The three-class rule is the point of the gate rather than a stylistic one.
+ * Precision and recall fail in opposite directions and a single corpus hides
+ * that: a detector with `fire` cases only looks perfect while opening records on
+ * praise, which is exactly what `detectUserReport` did until 2026-08-09 (it
+ * fired on "das ist fine, du hast nichts falsch gemacht"). A missing class is
+ * therefore a gate failure, not a warning — the absent half is where the defects
+ * live.
+ *
+ * Registration is explicit: a detector added to `self_repair.ts` without a
+ * matching corpus entry fails here, which is the coupling that keeps the corpus
+ * from silently lagging the code.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import * as YAML from 'yaml';
+
+import { GateLedger } from './_lib/gate_ledger.js';
+import {
+    type DefectFinding,
+    type TurnSnapshot,
+    detectCouncilClaim,
+    detectLanguageMirror,
+    detectUserReport,
+} from './_lib/self_repair.js';
+import { assertScanned } from './_lib/scan_scope.js';
+
+export const CORPUS_REL = path.join('tests', 'fixtures', 'self-repair-detector-corpus.yml');
+
+const GATE = 'check_detector_corpus';
+const CLASSES = ['fire', 'near-miss-fire', 'must-not-fire'] as const;
+type FixtureClass = (typeof CLASSES)[number];
+
+/** One corpus entry, in the union of shapes the three detectors need. */
+export interface Fixture {
+    text?: string;
+    reply?: string;
+    pinned_language?: 'de' | 'en';
+    tool_commands?: string[];
+    note?: string;
+}
+
+export type Corpus = Record<string, Partial<Record<FixtureClass, Fixture[]>>>;
+
+/**
+ * Every detector that must appear in the corpus, with how to run it.
+ *
+ * Keyed by the `defect_class` the detector produces, so the corpus reads as a
+ * list of defect classes rather than of function names.
+ */
+export const DETECTORS: Record<string, (f: Fixture) => DefectFinding | null> = {
+    'user-reported': (f) => detectUserReport(f.text ?? f.reply ?? ''),
+    'council-availability-claim': (f) => detectCouncilClaim(asTurn(f)),
+    'language-mirror': (f) => detectLanguageMirror(asTurn(f)),
+};
+
+function asTurn(f: Fixture): TurnSnapshot {
+    return {
+        prompt: f.text ?? '',
+        reply: f.reply ?? '',
+        toolCommands: f.tool_commands ?? [],
+        pinnedLanguage: f.pinned_language ?? null,
+    };
+}
+
+export interface Finding {
+    detector: string;
+    kind: 'missing-class' | 'empty-class' | 'wrong-outcome' | 'unregistered';
+    message: string;
+}
+
+/** Pure: audit a parsed corpus against the registered detectors. */
+export function auditCorpus(corpus: Corpus): { findings: Finding[]; fixtures: number } {
+    const findings: Finding[] = [];
+    let fixtures = 0;
+
+    for (const name of Object.keys(corpus)) {
+        if (!(name in DETECTORS)) {
+            findings.push({
+                detector: name,
+                kind: 'unregistered',
+                message: `corpus names "${name}", which is not a registered detector`,
+            });
+        }
+    }
+
+    for (const [name, run] of Object.entries(DETECTORS)) {
+        const entry = corpus[name];
+        if (entry === undefined) {
+            findings.push({
+                detector: name,
+                kind: 'missing-class',
+                message: `no corpus entry at all — needs all of: ${CLASSES.join(', ')}`,
+            });
+            continue;
+        }
+        for (const cls of CLASSES) {
+            const cases = entry[cls];
+            if (cases === undefined) {
+                findings.push({
+                    detector: name,
+                    kind: 'missing-class',
+                    message: `missing the \`${cls}\` class`,
+                });
+                continue;
+            }
+            if (cases.length === 0) {
+                // An empty class is the same hole as a missing one wearing a key.
+                findings.push({
+                    detector: name,
+                    kind: 'empty-class',
+                    message: `\`${cls}\` is present but empty`,
+                });
+                continue;
+            }
+            for (const f of cases) {
+                fixtures += 1;
+                const fired = run(f) !== null;
+                const shouldFire = cls !== 'must-not-fire';
+                if (fired !== shouldFire) {
+                    const what = f.text ?? f.reply ?? '(empty)';
+                    findings.push({
+                        detector: name,
+                        kind: 'wrong-outcome',
+                        message:
+                            `\`${cls}\` fixture ${shouldFire ? 'did NOT fire' : 'FIRED'}: ` +
+                            JSON.stringify(what.slice(0, 90)),
+                    });
+                }
+            }
+        }
+    }
+    return { findings, fixtures };
+}
+
+export function loadCorpus(repoRoot: string): Corpus {
+    const p = path.join(repoRoot, CORPUS_REL);
+    const parsed = YAML.parse(fs.readFileSync(p, 'utf-8')) as { detectors?: Corpus };
+    return parsed.detectors ?? {};
+}
+
+export function main(repoRoot: string = process.cwd()): number {
+    const corpus = loadCorpus(repoRoot);
+    const { findings, fixtures } = auditCorpus(corpus);
+
+    // A corpus that parsed to nothing is the dead-scope case, not a pass.
+    assertScanned({
+        gate: GATE,
+        scanned: fixtures,
+        units: 'detector fixtures',
+        roots: [CORPUS_REL],
+    });
+
+    // Per-detector completeness: every registered detector AND every corpus
+    // entry reaches exactly one outcome, so a detector silently absent from the
+    // loop above could not read as a pass.
+    const ledger = new GateLedger(GATE);
+    const names = [...new Set([...Object.keys(DETECTORS), ...Object.keys(corpus)])].sort();
+    ledger.plan(names);
+    const failing = new Set(findings.map((f) => f.detector));
+    for (const name of names) {
+        if (failing.has(name)) {
+            ledger.fail(name, 'corpus finding(s) against this detector');
+        } else {
+            ledger.complete(name);
+        }
+    }
+    ledger.report();
+
+    if (findings.length > 0) {
+        process.stderr.write(`${GATE}: ${String(findings.length)} finding(s)\n\n`);
+        for (const f of findings) {
+            process.stderr.write(`  ${f.detector}: ${f.message}\n`);
+        }
+        process.stderr.write(
+            `\nEvery detector needs all three classes (${CLASSES.join(', ')}) and every\n` +
+                'fixture must behave as its class says. Precision and recall fail in\n' +
+                'opposite directions; a corpus missing one half hides the other.\n',
+        );
+        return 1;
+    }
+
+    process.stdout.write(
+        `✅  ${GATE}: ${String(Object.keys(DETECTORS).length)} detector(s) × ` +
+            `${String(CLASSES.length)} classes, ${String(fixtures)} fixtures, all behaving\n`,
+    );
+    return 0;
+}
+
+function isCliEntry(): boolean {
+    const argv1 = process.argv[1];
+    if (argv1 === undefined) {
+        return false;
+    }
+    try {
+        return (
+            fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(argv1))
+        );
+    } catch {
+        return pathToFileURL(argv1).href === import.meta.url;
+    }
+}
+
+if (isCliEntry()) {
+    process.exit(main());
+}