@event4u/agent-config 9.6.0 → 9.8.0

package/src/scripts/bench_adversarial_council.ts

@@ -0,0 +1,292 @@
+/**
+ * Two-stage residual-detection benchmark runner for the adversarial-council
+ * finding-coverage claim (ADR-122, road-to-adversarial-council-benchmark,
+ * design: docs/design/adversarial-council-eval.md).
+ *
+ * Protocol (documented here so the verdict is reproducible; 2 working providers
+ * — anthropic + openai — so the design is adapted to isolate panel VALUE without
+ * a structural-zero artifact):
+ *
+ *   Stage 1 — define the residual. BOTH providers review the 12 defect fixtures
+ *   under a NEUTRAL review prompt. Residual R = defects that NEITHER neutral pass
+ *   caught (the judge-survivable pool: it survived a strong 2-vendor first read).
+ *
+ *   Stage 2 — single skeptic vs cross-vendor panel, on R + the clean controls,
+ *   under an ADVERSARIAL SKEPTIC prompt (the shipped Mode-9 posture):
+ *     - single_judge  = anthropic-skeptic alone.
+ *     - panel         = reconciled union of {anthropic, openai} skeptics.
+ *   Because panel ⊇ single, lift ≥ 0 and measures the MARGINAL value the
+ *   second vendor adds at a fixed skeptic posture — exactly "does a cross-vendor
+ *   panel out-find a single skeptic on the residual, at no-worse FP".
+ *
+ *   evaluateCouncilBench applies the LOCKED dual threshold → backed | honest-null.
+ *
+ * Limitation (recorded honestly): with 2 vendors this isolates the 2nd-vendor
+ * marginal contribution, not an N-vendor scaling curve. gemini/xai are stubbed
+ * or disabled in this CLI build.
+ *
+ * `--mock` runs the whole pipeline on canned responses (no spend) to pre-validate
+ * parsing + residual + scoring + gate in BOTH directions. `--run` fires the real
+ * paid cross-vendor calls (maintainer spend-gated).
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import {
+    AnthropicClient,
+    OpenAIClient,
+    load_anthropic_key,
+    load_openai_key,
+    type ExternalAIClient,
+} from './ai_council/clients.js';
+import { evaluateCouncilBench, type CouncilBenchInputs } from './_lib/adversarial_council_gate.js';
+import {
+    caughtDefect,
+    isFalsePositive,
+    recall,
+    fpRate,
+    categoryFamily,
+    type Finding,
+    type GroundTruth,
+} from './_lib/adversarial_bench_score.js';
+
+const REPO_ROOT = process.cwd();
+const CORPUS_PATH = path.join(REPO_ROOT, 'internal/bench/adversarial-council/corpus.json');
+const SINGLE_SKEPTIC = 'anthropic'; // the single-judge baseline in stage 2
+
+interface CorpusItem {
+    id: string;
+    class: string;
+    defect_category: string;
+    is_clean: boolean;
+    files: { path: string; content: string }[];
+    ground_truth: { defect_files: string[]; defect_summary: string };
+}
+
+function loadCorpus(): CorpusItem[] {
+    return JSON.parse(fs.readFileSync(CORPUS_PATH, 'utf8')).items as CorpusItem[];
+}
+function groundTruth(item: CorpusItem): GroundTruth {
+    return {
+        id: item.id,
+        is_clean: item.is_clean,
+        defect_files: item.ground_truth.defect_files,
+        defect_category: item.is_clean ? 'none' : categoryFamily(item.defect_category),
+    };
+}
+function codeBlock(item: CorpusItem): string {
+    return item.files.map((f) => `FILE: ${f.path}\n\`\`\`ts\n${f.content}\`\`\``).join('\n\n');
+}
+const JSON_SHAPE =
+    '{"findings":[{"file":"<file path>","category":"<defect category>","confidence":"high|medium|low","summary":"<one line>"}]}';
+function neutralPrompt(item: CorpusItem): string {
+    return [
+        'You are a senior code reviewer. Review the TypeScript below for REAL defects and report only genuine bugs you are confident about. If it is correct, report an empty findings array — do not invent problems.',
+        `Respond with STRICT JSON only, exactly: ${JSON_SHAPE}`,
+        '',
+        codeBlock(item),
+    ].join('\n');
+}
+function skepticPrompt(item: CorpusItem): string {
+    return [
+        'You are an adversarial security/correctness skeptic. Assume this code may hide a subtle, non-obvious defect that a normal review missed — a masked access-control/SSRF/traversal flaw, a boundary/logic inversion, a concurrency or resource-leak edge, a cross-file contract mismatch. Hunt for it. Report only defects you can concretely justify; if after hard scrutiny it is genuinely correct, report an empty array (do not fabricate).',
+        `Respond with STRICT JSON only, exactly: ${JSON_SHAPE}`,
+        '',
+        codeBlock(item),
+    ].join('\n');
+}
+
+function parseFindings(text: string): Finding[] {
+    if (!text) return [];
+    const start = text.indexOf('{');
+    if (start < 0) return [];
+    let depth = 0;
+    let end = -1;
+    for (let i = start; i < text.length; i++) {
+        if (text[i] === '{') depth++;
+        else if (text[i] === '}' && --depth === 0) {
+            end = i;
+            break;
+        }
+    }
+    if (end < 0) return [];
+    try {
+        const obj = JSON.parse(text.slice(start, end + 1)) as { findings?: unknown };
+        const arr = Array.isArray(obj.findings) ? obj.findings : [];
+        return arr
+            .filter((f): f is Record<string, unknown> => typeof f === 'object' && f !== null)
+            .map((f) => ({
+                file: String(f.file ?? ''),
+                category: String(f.category ?? ''),
+                confidence: (['high', 'medium', 'low'].includes(String(f.confidence)) ? String(f.confidence) : 'high') as
+                    | 'high'
+                    | 'medium'
+                    | 'low',
+            }))
+            .filter((f) => f.file.length > 0);
+    } catch {
+        return [];
+    }
+}
+
+type Reviews = Record<string, Record<string, Finding[]>>; // fixtureId → member → findings
+
+// Direct, INDEPENDENT client calls — NOT council_cli. The council `run`/`debate`
+// transport imposes multi-round peer-review with cross-member visibility and
+// returns prose ("## Round 2 … Reviewer A"), which (a) violates the claim's
+// independent-skeptic requirement and (b) defeats JSON parsing. We call each
+// provider's client once, in isolation, with a strict-JSON system prompt.
+const SYSTEM_JSON =
+    'You are a code reviewer. Output ONLY one JSON object — no prose, no markdown, no code fences. ' +
+    'Shape exactly: {"findings":[{"file":"<path>","category":"<category>","confidence":"high|medium|low","summary":"<one line>"}]}. ' +
+    'If the code is correct, output {"findings":[]}. Do not include any text before or after the JSON object.';
+
+let _clients: Record<string, ExternalAIClient> | null = null;
+function getClients(): Record<string, ExternalAIClient> {
+    if (!_clients) {
+        _clients = {
+            anthropic: new AnthropicClient({ model: 'claude-sonnet-4-5', api_key: load_anthropic_key() }),
+            openai: new OpenAIClient({ model: 'gpt-4o', api_key: load_openai_key() }),
+        };
+    }
+    return _clients;
+}
+
+async function directReview(item: CorpusItem, userPrompt: string): Promise<Record<string, Finding[]>> {
+    const cs = getClients();
+    const out: Record<string, Finding[]> = {};
+    for (const [name, client] of Object.entries(cs)) {
+        let text = '';
+        try {
+            const resp = await client.ask(SYSTEM_JSON, userPrompt, 1200);
+            text = resp.text ?? '';
+        } catch (e) {
+            process.stderr.write(`  ${name} error on ${item.id}: ${(e as Error).message}\n`);
+        }
+        out[name] = parseFindings(text);
+    }
+    return out;
+}
+
+interface Passes {
+    neutral: Reviews; // defect fixtures only
+    skeptic: Reviews; // residual + controls
+    residualIds: string[];
+}
+
+async function realPasses(items: CorpusItem[]): Promise<Passes> {
+    const defects = items.filter((i) => !i.is_clean);
+    const controls = items.filter((i) => i.is_clean);
+    const neutral: Reviews = {};
+    process.stderr.write('stage 1 (neutral, independent per vendor) over 12 defects…\n');
+    for (const d of defects) {
+        neutral[d.id] = await directReview(d, neutralPrompt(d));
+        process.stderr.write(`  neutral ${d.id}: ${Object.entries(neutral[d.id] ?? {}).map(([m, f]) => `${m}=${f.length}`).join(' ')}\n`);
+    }
+    const residual = defects.filter((d) => !Object.values(neutral[d.id] ?? {}).flat().some((f) => caughtDefect(groundTruth(d), [f])));
+    process.stderr.write(`residual (missed by BOTH neutral passes): ${residual.map((r) => r.id).join(', ') || '(none)'}\n`);
+    const skeptic: Reviews = {};
+    process.stderr.write('stage 2 (adversarial skeptic, independent per vendor) over residual + controls…\n');
+    for (const item of [...residual, ...controls]) {
+        skeptic[item.id] = await directReview(item, skepticPrompt(item));
+        process.stderr.write(`  skeptic ${item.id}: ${Object.entries(skeptic[item.id] ?? {}).map(([m, f]) => `${m}=${f.length}`).join(' ')}\n`);
+    }
+    return { neutral, skeptic, residualIds: residual.map((r) => r.id) };
+}
+
+function mockPasses(items: CorpusItem[]): Passes {
+    // Deterministic proof that the pipeline discriminates: neutral 2-vendor pass
+    // catches the "easier" defects; a hard residual survives; the skeptic panel
+    // then recovers more of the residual than a single skeptic, at controlled FP.
+    const defects = items.filter((i) => !i.is_clean);
+    const controls = items.filter((i) => i.is_clean);
+    const neutralCatch = new Set(['sec-01', 'sec-02', 'inv-01', 'inv-02', 'state-03', 'mfi-01']); // 6 caught neutrally
+    // residual = the other 6: sec-03, inv-03, state-01, state-02, mfi-02, mfi-03
+    const anthropicSkepticCatch = new Set(['sec-03', 'state-01']); // single skeptic recovers 2/6
+    const openaiSkepticExtra = new Set(['inv-03', 'mfi-02', 'mfi-03']); // openai adds 3 more → panel 5/6
+    const hit = (i: CorpusItem): Finding[] => [
+        { file: i.ground_truth.defect_files[0] ?? i.files[0]?.path ?? '', category: i.defect_category, confidence: 'high' as const },
+    ];
+    const neutral: Reviews = {};
+    for (const d of defects) neutral[d.id] = { anthropic: neutralCatch.has(d.id) ? hit(d) : [], openai: [] };
+    const skeptic: Reviews = {};
+    const residual = defects.filter((d) => !neutralCatch.has(d.id));
+    for (const d of residual) {
+        skeptic[d.id] = {
+            anthropic: anthropicSkepticCatch.has(d.id) ? hit(d) : [],
+            openai: openaiSkepticExtra.has(d.id) ? hit(d) : [],
+        };
+    }
+    for (const c of controls)
+        skeptic[c.id] = { anthropic: [], openai: c.id === 'clean-02' ? [{ file: c.files[0]?.path ?? '', category: 'correctness', confidence: 'high' }] : [] };
+    return { neutral, skeptic, residualIds: residual.map((r) => r.id) };
+}
+
+function scorePasses(items: CorpusItem[], p: Passes): { inputs: CouncilBenchInputs; detail: Record<string, unknown> } {
+    const byId = new Map(items.map((i) => [i.id, i]));
+    const residual = p.residualIds.map((id) => byId.get(id)!);
+    const controls = items.filter((i) => i.is_clean);
+
+    const singleCaught: Record<string, boolean> = {};
+    const panelCaught: Record<string, boolean> = {};
+    for (const d of residual) {
+        const gt = groundTruth(d);
+        singleCaught[d.id] = caughtDefect(gt, p.skeptic[d.id]?.[SINGLE_SKEPTIC] ?? []);
+        panelCaught[d.id] = caughtDefect(gt, Object.values(p.skeptic[d.id] ?? {}).flat());
+    }
+    const singleFp: Record<string, boolean> = {};
+    const panelFp: Record<string, boolean> = {};
+    for (const c of controls) {
+        const gt = groundTruth(c);
+        singleFp[c.id] = isFalsePositive(gt, p.skeptic[c.id]?.[SINGLE_SKEPTIC] ?? []);
+        panelFp[c.id] = isFalsePositive(gt, Object.values(p.skeptic[c.id] ?? {}).flat());
+    }
+    const inputs: CouncilBenchInputs = {
+        single_judge_residual_recall: recall(singleCaught),
+        panel_residual_recall: recall(panelCaught),
+        single_judge_fp_rate: fpRate(singleFp),
+        panel_fp_rate: fpRate(panelFp),
+        fp_noise_margin: 1 / 3,
+    };
+    const detail = {
+        total_defects: items.filter((i) => !i.is_clean).length,
+        residual_ids: p.residualIds,
+        residual_size: residual.length,
+        single_skeptic: SINGLE_SKEPTIC,
+        single_residual_caught: Object.entries(singleCaught).filter(([, v]) => v).map(([k]) => k),
+        panel_residual_caught: Object.entries(panelCaught).filter(([, v]) => v).map(([k]) => k),
+        single_fp: Object.entries(singleFp).filter(([, v]) => v).map(([k]) => k),
+        panel_fp: Object.entries(panelFp).filter(([, v]) => v).map(([k]) => k),
+    };
+    return { inputs, detail };
+}
+
+async function main(argv: string[]): Promise<number> {
+    const mock = argv.includes('--mock');
+    const run = argv.includes('--run');
+    if (!mock && !run) {
+        process.stderr.write('usage: bench_adversarial_council (--mock | --run)\n');
+        return 2;
+    }
+    const items = loadCorpus();
+    const passes = mock ? mockPasses(items) : await realPasses(items);
+    const { inputs, detail } = scorePasses(items, passes);
+    const verdict = evaluateCouncilBench(inputs);
+    const report = {
+        mode: mock ? 'mock' : 'run',
+        corpus: 'internal/bench/adversarial-council/corpus.json',
+        protocol:
+            'stage1 2-vendor neutral → residual (missed by both); stage2 single skeptic (anthropic) vs cross-vendor panel union on residual; FP on clean controls',
+        inputs,
+        detail,
+        verdict,
+    };
+    process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+    return 0;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+    void main(process.argv.slice(2)).then((code) => process.exit(code));
+}
+
+export { parseFindings, scorePasses, main };

package/src/scripts/build_proof.ts

@@ -41,6 +41,105 @@ class ExitCode extends Error {
     }
 }
 
+/**
+ * The prevented-failure table.
+ *
+ * Every row names a **failure mode that is prevented**, never a feature. That
+ * constraint is the whole discipline: "cross-platform" is a feature and says
+ * nothing; "the same rules do not silently differ between the agent you run
+ * today and the one you switch to" names what goes wrong without it.
+ *
+ * Every row cites a ledger claim, and `backs` is not decoration — a cited id
+ * that is missing or not `backed` throws, so the table cannot outlive its
+ * evidence. This is the guard against the failure it was modelled on: the
+ * reference ships an equivalent table whose headline efficiency figure appears
+ * only there, an order of magnitude below the cheapest scenario in its own
+ * generated benchmark. A number with nowhere to resolve is exactly what this
+ * ledger exists to catch, so the table is held to the ledger's own bar.
+ *
+ * A row with no resolving claim ships WITHOUT a number rather than with an
+ * approximate one.
+ */
+export const PREVENTED_FAILURES: { failure: string; mechanism: string; backs: string }[] = [
+    {
+        failure: 'A rule says MUST, and nothing anywhere enforces it — so the rule reads as a guarantee while being honour-system.',
+        mechanism:
+            'Each rule declares `enforced_by:`, and the check **resolves** it: a validator reachable from no taskfile, workflow, or hook manifest counts as unwired, not as covered. Undeclared counts as uncovered.',
+        backs: 'enforcement-coverage-resolved',
+    },
+    {
+        failure:
+            'A shipped artefact carries a hidden-Unicode or instruction-smuggling payload, and reaches consumers because only the source tree was scanned.',
+        mechanism:
+            'Source **and** the condensed projection are scanned in CI; a finding blocks the release before publish, not merely the merge.',
+        backs: 'shipped-artifacts-hidden-instruction-scanned',
+    },
+    {
+        failure:
+            'A count in public prose drifts from the source, and the marketing number quietly stops being true.',
+        mechanism:
+            'Counts are generated from source and drift-checked; the build fails on a count-shaped prose mention that disagrees, or on two different numbers for the same artefact kind.',
+        backs: 'skill-count',
+    },
+    {
+        failure:
+            'A host-coverage claim understates or overstates what actually works — for months, on the one surface everybody reads.',
+        mechanism: 'The number is pinned by a test over real detection, and the test is re-run as the claim evidence.',
+        backs: 'host-agent-count',
+    },
+    {
+        failure:
+            'A non-coding domain skill implies proven correctness it never had, because it was forged on a different domain and never checked against one.',
+        mechanism:
+            'Domain skills are labelled unvalidated until they pass a sourced domain-truth fixture, and the validated count is ratcheted so it cannot quietly fall.',
+        backs: 'domain-soundness-scoped',
+    },
+    {
+        failure:
+            'Behavioural-eval coverage regresses as skills are added, and the suite looks healthy because only the absolute number is reported.',
+        mechanism: 'Coverage is measured per tier and ratcheted in CI, so it can only rise; the gap is published rather than implied away.',
+        backs: 'eval-coverage-ratcheted',
+    },
+];
+
+export function renderPreventedFailures(ledger: ReturnType<typeof load_ledger>): string {
+    const L: string[] = [];
+    L.push('## What this prevents');
+    L.push('');
+    L.push('Each row is a failure mode, not a feature — and each cites the ledger');
+    L.push('claim that backs it. A row whose claim stopped resolving would fail this');
+    L.push('page\'s own generator, so the table cannot outlive its evidence.');
+    L.push('');
+    L.push('| Failure this prevents | How | Backed by |');
+    L.push('|---|---|---|');
+    for (const row of PREVENTED_FAILURES) {
+        const entry = ledger.get(row.backs);
+        if (!entry) {
+            throw new Error(
+                `build_proof: prevented-failure row cites claim '${row.backs}', which has no ledger entry. ` +
+                    'Bind it in docs/CLAIMS.md or drop the row — the table may not carry an unbacked cell.',
+            );
+        }
+        if (entry.status !== 'backed') {
+            throw new Error(
+                `build_proof: prevented-failure row cites claim '${row.backs}', whose ledger status is ` +
+                    `'${entry.status}', not 'backed'. The table may not carry an unbacked cell.`,
+            );
+        }
+        const reverifies = entry.evidence.trim().startsWith('exec:') ? ' ⟳' : '';
+        L.push(
+            `| ${row.failure.replace(/\|/g, '\\|')} | ${row.mechanism.replace(/\|/g, '\\|')} | ` +
+                `[\`${row.backs}\`](CLAIMS.md)${reverifies} |`,
+        );
+    }
+    L.push('');
+    L.push('⟳ — the claim carries `exec:` evidence: CI re-runs the command and');
+    L.push('compares its exit code, so a stale row turns the build red rather than');
+    L.push('ageing quietly into marketing.');
+    L.push('');
+    return L.join('\n');
+}
+
 function render(): string {
     const ledger = load_ledger();
     const entries = [...ledger.values()].sort((a, b) => a.id.localeCompare(b.id));
@@ -59,6 +158,7 @@ function render(): string {
     L.push('every check below on a fresh checkout. This page is itself generated');
     L.push('from those sources and fails CI if it drifts.');
     L.push('');
+    L.push(renderPreventedFailures(ledger));
     L.push('## See it run (< 60s, real output)');
     L.push('');
     L.push('![The trust surface running green — every "verify it yourself" command below, recorded from a real run](media/proof-demo.gif)');
@@ -86,6 +186,39 @@ function render(): string {
     L.push('');
     L.push(`**${backed.length} backed claim(s)** — all evidence pointers resolve in CI.`);
     L.push('');
+
+    // Re-verifiable vs. merely-resolving. The distinction is the point: a
+    // pointer proves an artefact exists, not that the claim is still true. Any
+    // page that reported only the backed total would hide exactly the gap this
+    // ledger was built to expose.
+    const execBacked = backed.filter((e) => e.evidence.trim().startsWith('exec:'));
+    const pointerOnly = backed.filter((e) => !e.evidence.trim().startsWith('exec:'));
+    L.push('### How many of those re-derive themselves');
+    L.push('');
+    L.push(`**${execBacked.length} of ${backed.length}** backed claims carry \`exec:\` evidence —`);
+    L.push('CI re-runs the command and compares its exit code to the claim, so a');
+    L.push('stale one turns the build red. The other');
+    L.push(`**${pointerOnly.length}** rest on a pointer: CI checks that the artefact`);
+    L.push('exists and contains what it should, which cannot distinguish a live');
+    L.push('claim from one whose producer nobody has run in months.');
+    L.push('');
+    L.push('That residue is not an oversight, and it is listed rather than rounded');
+    L.push('away. A claim can only re-derive itself when a deterministic command');
+    L.push("carries the verdict in its exit code. These cannot, for the reasons");
+    L.push('given:');
+    L.push('');
+    L.push('| Claim | Why it cannot re-execute |');
+    L.push('|---|---|');
+    for (const e of pointerOnly) {
+        const ev = e.evidence.trim();
+        const why = /^https?:\/\//.test(ev)
+            ? 'external cite — CI does not fetch the network'
+            : /benchmark|bench\/|results-/.test(ev)
+              ? 'benchmark output — regenerating it needs paid or stochastic model calls no CI job can re-derive'
+              : 'prose or contract artefact — no exit code carries the verdict';
+        L.push(`| ${e.claim.replace(/\|/g, '\\|').slice(0, 110)} | ${why} |`);
+    }
+    L.push('');
     L.push('Artefact counts in public prose (skills, commands, governed rules,');
     L.push('guidelines, personas) are **generated from source and CI-drift-checked**:');
     L.push('`update_counts.ts` writes the numbers, `check_artefact_count_messaging.ts`');
@@ -224,6 +357,35 @@ function render(): string {
             L.push(`| ${claim} | ${ours} | ${theirs} | ${r.checkable ? '✅' : '—'} |`);
         }
     }
+
+    // Second lens on the SAME rows: what each one prevents, for a reader who has
+    // not asked "compared to what". Membership is a data property — a row appears
+    // here iff it carries a `failure_mode` — so nobody curates a short-list that
+    // then drifts from the table above. The pointer is the same pointer, resolved
+    // by the same gate, so no cell reaches this view unbound.
+    const fmRows = cmpRows.filter((r) => (r.failure_mode ?? '').trim() !== '');
+    if (fmRows.length > 0) {
+        L.push('');
+        L.push('### What each one prevents');
+        L.push('');
+        L.push('The same rows, read as failure modes rather than as comparisons. Each names');
+        L.push('something that goes wrong without the control and carries the identical');
+        L.push('resolvable pointer — a projection of the table above, not a second list to');
+        L.push('keep in sync.');
+        L.push('');
+        L.push('| Without it | The control | Evidence |');
+        L.push('|---|---|---|');
+        for (const r of fmRows) {
+            const fm = (r.failure_mode ?? '').replace(/\|/g, '\\|').trim();
+            const claim = r.claim.replace(/\|/g, '\\|');
+            const filePart = (r.our_evidence.split('#')[0] ?? r.our_evidence).split(':')[0] ?? r.our_evidence;
+            const ours = pointer_unresolved(r.our_evidence) === null
+                ? `[\`${r.our_evidence}\`](../${filePart})`
+                : `\`${r.our_evidence}\``;
+            L.push(`| ${fm} | ${claim} | ${ours} |`);
+        }
+    }
+
     L.push('');
     L.push('## 5. Verify it yourself');
     L.push('');

package/src/scripts/check_adr_frontmatter.ts

@@ -0,0 +1,195 @@
+#!/usr/bin/env tsx
+/**
+ * ADR frontmatter gate — and the `review_trigger` field that makes a decision
+ * revisitable on purpose rather than by archaeology.
+ *
+ * Two findings drive this. First, ADR frontmatter was **entirely unvalidated**:
+ * `validate_frontmatter.ts` covers skills, rules, commands, and personas, and
+ * nothing covered `docs/decisions/`. That is why `review_date` drifted into 11
+ * ADRs and back out again with nobody noticing.
+ *
+ * Second, of 128 ADRs, zero named the condition under which they should be
+ * reconsidered — while `decision-record` SKILL § step 4 already *mandates* a
+ * "Revisit-if" line and `decision-revisit-gate` already treats an ADR as a lock
+ * that must be re-openable. The doctrine was canon; the template just never
+ * emitted a slot for it, so 33 authors wrote it in prose and it stayed
+ * unfindable. This is a missing field, not a missing idea.
+ *
+ * `review_trigger` is a named CONDITION, never a date. "Review annually" is
+ * ignored by everyone and rots into ceremony; "when a second consumer reports a
+ * preservation surprise" fires exactly when it should.
+ *
+ * Grandfathering is by authorship date, not an allowlist: ADRs dated before the
+ * switch warn, ADRs dated on or after it fail. No list to maintain and no
+ * exemption to forget — a retrofit of 128 files would be busywork that teaches
+ * nobody anything.
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/check_adr_frontmatter          # gate
+ *   ./scripts-run src/scripts/check_adr_frontmatter --json
+ *
+ * Exit codes: 0 ok (warnings allowed) · 1 violation · 2 usage/env error.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(_HERE, '..', '..');
+const ADR_DIR = path.join(REPO_ROOT, 'docs', 'decisions');
+
+/**
+ * Grandfathering switch. ADRs dated before this warn on a missing
+ * `review_trigger`; ADRs dated on or after it fail.
+ */
+export const REVIEW_TRIGGER_SINCE = '2026-07-25';
+
+/** Fields every ADR must carry — the shape that already exists in practice. */
+const REQUIRED = ['adr', 'status', 'date', 'decision'] as const;
+
+const ALLOWED_STATUS = new Set([
+    'accepted',
+    'proposed',
+    'superseded',
+    'rejected',
+    'deprecated',
+    'draft',
+]);
+
+export interface AdrFinding {
+    file: string;
+    level: 'error' | 'warn';
+    message: string;
+}
+
+export function parse_frontmatter(text: string): Record<string, string> | null {
+    if (!text.startsWith('---\n')) return null;
+    const end = text.indexOf('\n---\n', 4);
+    if (end === -1) return null;
+    const out: Record<string, string> = {};
+    let key: string | null = null;
+    for (const raw of text.slice(4, end).split('\n')) {
+        const line = raw.replace(/\s+$/, '');
+        if (!line || line.trimStart().startsWith('#')) continue;
+        // Continuation of a folded/indented value.
+        if (/^\s/.test(line) && key) {
+            out[key] = `${out[key]} ${line.trim()}`.trim();
+            continue;
+        }
+        const idx = line.indexOf(':');
+        if (idx === -1) continue;
+        key = line.slice(0, idx).trim();
+        out[key] = line
+            .slice(idx + 1)
+            .trim()
+            .replace(/^["'](.*)["']$/, '$1');
+    }
+    return out;
+}
+
+/** A trigger must name a condition. A bare cadence is the failure mode. */
+export function trigger_is_meaningful(value: string): boolean {
+    const v = value.trim();
+    if (v.length < 20) return false;
+    // "annually" / "every 6 months" / a bare date is a calendar, not a condition.
+    if (/^(annually|yearly|quarterly|monthly|every\s+\d+\s+\w+|\d{4}-\d{2}-\d{2})\.?$/i.test(v)) {
+        return false;
+    }
+    return true;
+}
+
+export function check(dir: string = ADR_DIR): 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'));
+
+        if (fm === null) {
+            findings.push({ file: rel, level: 'error', message: 'no YAML frontmatter block' });
+            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 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;
+}
+
+function main(argv: string[]): number {
+    const as_json = argv.includes('--json');
+    const findings = check();
+
+    if (as_json) {
+        process.stdout.write(JSON.stringify({ findings }, null, 2) + '\n');
+        return 0;
+    }
+
+    const errors = findings.filter((f) => f.level === 'error');
+    const warns = findings.filter((f) => f.level === 'warn');
+    const total = fs.existsSync(ADR_DIR)
+        ? fs.readdirSync(ADR_DIR).filter((f) => /^ADR-.*\.md$/.test(f)).length
+        : 0;
+
+    process.stdout.write(
+        `ADR frontmatter: ${total} ADR(s) · ${errors.length} error(s) · ` +
+            `${warns.length} grandfathered without a revisit condition\n`,
+    );
+    for (const e of errors) process.stderr.write(`    ❌ ${e.file}: ${e.message}\n`);
+
+    if (errors.length > 0) {
+        process.stderr.write(
+            `\n❌  check_adr_frontmatter: ${errors.length} error(s). ` +
+                `ADRs dated ${REVIEW_TRIGGER_SINCE} or later must name a \`review_trigger\`.\n`,
+        );
+        return 1;
+    }
+    process.stdout.write('✅  check_adr_frontmatter: no errors\n');
+    return 0;
+}
+
+// Main-guard (realpath-compared, mirrors the repo convention).
+if (process.argv[1] !== undefined) {
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv1 = fs.realpathSync(path.resolve(process.argv[1]));
+        if (here === argv1) {
+            process.exit(main(process.argv.slice(2)));
+        }
+    } catch {
+        const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+        if (import.meta.url === argvUrl) {
+            process.exit(main(process.argv.slice(2)));
+        }
+    }
+}