@event4u/agent-config 14.11.0 → 14.13.0

package/src/scripts/check_adr_frontmatter.ts

@@ -60,6 +60,20 @@ const ADR_DIR = path.join(REPO_ROOT, 'docs', 'decisions');
  */
 export const REVIEW_TRIGGER_SINCE = '2026-07-25';
 
+/**
+ * Staging date for the `## Not reopened` obligation on a scoped supersession
+ * (road-to-runtime-governance-flip step 1.4). Same shape and same reason as
+ * `REVIEW_TRIGGER_SINCE`: a new structural requirement is an error on records
+ * written after it and a warning on records written before, so the gate does
+ * not retroactively red the corpus it is being added to.
+ *
+ * Two records predate it and warn: `ADR-124` (2026-07-23) and `ADR-209`
+ * (2026-08-03). Both carry a real `supersedes_scope` and neither states its
+ * remainder in a section — measured, not assumed, and left visible as a warning
+ * rather than silenced with a baseline file.
+ */
+export const SCOPED_SUPERSESSION_SINCE = '2026-08-27';
+
 /** Fields every ADR must carry — the shape that already exists in practice. */
 const REQUIRED = ['adr', 'status', 'date', 'decision'] as const;
 
@@ -150,6 +164,12 @@ export function check_reopen_authority(
 }
 
 const ALLOWED_STATUS = new Set([
+    // `challenged` — accepted, and under active question. It names NO successor
+    // and SUSPENDS NOTHING: an ADR at `challenged` still binds until something
+    // replaces it. Without that clause the status becomes a way to stop obeying
+    // a decision without reopening it, which is the failure mode
+    // road-to-decision-conformance 1.2 exists to prevent.
+    'challenged',
     'accepted',
     'proposed',
     'superseded',
@@ -258,6 +278,7 @@ export function check_one(rel: string, text: string): AdrFinding[] {
     }
     check_reopen_authority(rel, fm, findings);
     check_amendment_shape(rel, fm, findings);
+    check_scoped_supersession(rel, fm, text, findings);
     const parsed = readAdrFrontmatter(text);
     if (parsed !== null) check_descriptive_axes(rel, parsed, findings);
     return findings;
@@ -546,6 +567,111 @@ export function check_amendment_shape(
     }
 }
 
+/**
+ * Validate a SCOPED supersession — the `supersedes_scope` / `superseded_scope`
+ * pair documented at `docs/contracts/adr-layout.md:59-60, 105-117`.
+ *
+ * Two invariants, both decidable from one file, both taken from that contract's
+ * own text rather than invented here:
+ *
+ * 1. **A scope with no refs is not a supersession.** The contract says so
+ *    literally — "A scope with no refs is not a supersession and renders as
+ *    `—`" — and `regenerate_index.ts` → `supersessionCell` silently drops the
+ *    scope in that case, so the author's intent disappears with no signal.
+ * 2. **A scoped supersession names what it did NOT reopen.** Narrowing a
+ *    prohibition to one row is precisely when a reader needs the boundary
+ *    stated, and a `## Not reopened` section is where this corpus states it.
+ *    Without the section, "supersedes ADR-NNN, partially" is an assertion with
+ *    no stated remainder, and the remainder is the whole content of a partial
+ *    supersession.
+ *
+ * **What this deliberately does NOT check**, because it is not observable: it
+ * cannot require a scope wherever partial supersession was *intended*. Intent
+ * is not in the file. A whole-document supersession that should have been
+ * scoped passes this check, and closing that gap needs stable section
+ * identifiers rather than prose scopes — recorded as the known limit rather
+ * than implied away.
+ *
+ * road-to-runtime-governance-flip step 1.4, which asked for exactly one thing:
+ * make the required section enforceable, or drop the word "required".
+ */
+/**
+ * Is there a `## Not reopened` section WITH content under it?
+ *
+ * Two corrections a neutral review made to the first version, both real:
+ *
+ * 1. **The level is exactly `##`.** The first pattern was `#{2,3}`, so a `###`
+ *    subsection satisfied a contract and a diagnostic that both say `##`. A gate
+ *    accepting a shape its own message forbids teaches the message is decorative.
+ * 2. **The section must say something.** Matching the heading alone let an empty
+ *    section pass while the error text promises one "naming what the narrowing
+ *    leaves standing". A heading with nothing under it is the absence the check
+ *    exists to catch, wearing the right title.
+ *
+ * "Content" is deliberately weak — one non-blank, non-heading line. No gate can
+ * judge whether the prose is true, and pretending otherwise would be the
+ * masquerade the sibling gate's docstring warns about.
+ */
+export function hasNotReopenedSection(text: string): boolean {
+    const lines = text.split('\n');
+    const start = lines.findIndex((l) => /^##\s+Not reopened\s*$/i.test(l));
+    if (start === -1) return false;
+    for (const line of lines.slice(start + 1)) {
+        if (/^#{1,6}\s/.test(line)) break;
+        if (line.trim() !== '') return true;
+    }
+    return false;
+}
+
+export function check_scoped_supersession(
+    rel: string,
+    fm: Record<string, string>,
+    text: string,
+    findings: AdrFinding[],
+): void {
+    const placeholder = (v: string | undefined): boolean =>
+        v === undefined || v.trim() === '' || v.trim() === '—' || v.trim() === '-';
+
+    for (const [scopeKey, refKey] of [
+        ['supersedes_scope', 'supersedes'],
+        ['superseded_scope', 'superseded_by'],
+    ] as const) {
+        if (placeholder(fm[scopeKey])) continue;
+        if (placeholder(fm[refKey])) {
+            findings.push({
+                file: rel,
+                level: 'error',
+                message:
+                    `\`${scopeKey}\` is set but \`${refKey}\` names no ADR. A scope with no refs ` +
+                    'is not a supersession (adr-layout § Frontmatter) — the index renders it as ' +
+                    '`—` and the scope text is lost. Name the record, or drop the scope.',
+            });
+        }
+    }
+
+    // The "Not reopened" obligation is on the record that PERFORMS the scoped
+    // supersession, never on the one that receives it: the successor is what
+    // has to state the remainder.
+    if (placeholder(fm['supersedes_scope'])) return;
+    if (!hasNotReopenedSection(text)) {
+        // A well-formed ISO date, or no grandfathering. A malformed `date:`
+        // sorts unpredictably against the staging constant, and the safe
+        // direction for an unreadable date is the error, not the warning.
+        const date = fm['date'] ?? '';
+        const wellFormed = /^\d{4}-\d{2}-\d{2}$/.test(date);
+        const staged = wellFormed && date < SCOPED_SUPERSESSION_SINCE;
+        findings.push({
+            file: rel,
+            level: staged ? 'warn' : 'error',
+            message:
+                'a scoped supersession (`supersedes_scope`) must carry a `## Not reopened` ' +
+                'section naming what the narrowing leaves standing. Partially superseding a ' +
+                'record without stating the remainder reads as a general relaxation, which is ' +
+                'the reading a safety floor cannot survive.',
+        });
+    }
+}
+
 /**
  * Corpus-level check: every `amends:` has its reciprocal `amended_by:` and vice
  * versa. Its absence for the `supersedes:` / `superseded_by:` pair is exactly

package/src/scripts/check_benchmark_report_fields.ts

@@ -0,0 +1,207 @@
+#!/usr/bin/env tsx
+/**
+ * A benchmark or cost report that omits a required cache field fails, naming the
+ * field (`road-to-runtime-context-floors` step 4.1).
+ *
+ * `cache.read_write_ratio` and `cache.stable_prefix_share` are REQUIRED. A report
+ * that cannot compute one emits `{ unavailable: "<reason>" }`; it does not omit
+ * the key and it does not emit a zero. A blank reads as "no cache activity" and a
+ * zero reads as "the worst possible ratio" — both are claims, and neither is the
+ * claim "this was not measured".
+ *
+ * Contract: `docs/contracts/benchmark-report-schema.md` § The `cache` block.
+ *
+ * Exit codes: 0 every scanned report carries both fields · 1 a report is missing
+ * or malformed · 2 misuse / unreadable input.
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/check_benchmark_report_fields [--dir <path>] [--quiet]
+ *   ./scripts-run src/scripts/check_benchmark_report_fields --self-test
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+import { describeProblem, validateCacheBlock, validateProvenanceBlock } from './_lib/benchmark_cache_fields.js';
+import { GateLedger } from './_lib/gate_ledger.js';
+import { runGateCli, runSelfTest, type SelfTestCase } from './_lib/gate_self_test.js';
+import { DeadScopeError, reportScanned } from './_lib/scan_scope.js';
+
+const HERE = path.dirname(new URL(import.meta.url).pathname);
+const REPO_ROOT = path.resolve(HERE, '..', '..');
+const DEFAULT_DIR = path.join(REPO_ROOT, 'internal', 'bench', 'reports');
+
+export interface ReportFinding {
+    file: string;
+    message: string;
+}
+
+export interface FieldVerdict {
+    scanned: number;
+    findings: ReportFinding[];
+}
+
+/** Only files that ANNOUNCE themselves as benchmark reports are in the corpus. */
+function isBenchmarkReport(doc: unknown): boolean {
+    const d = doc as { schema_version?: unknown; selection?: unknown; corpus?: unknown } | null;
+    if (d === null || typeof d !== 'object') return false;
+    return d.schema_version !== undefined && (d.selection !== undefined || d.corpus !== undefined);
+}
+
+export function evaluate(dir: string = DEFAULT_DIR, ledger?: GateLedger): FieldVerdict {
+    const findings: ReportFinding[] = [];
+    let scanned = 0;
+    if (!fs.existsSync(dir)) return { scanned, findings };
+
+    const names = fs.readdirSync(dir).sort();
+    ledger?.plan(names);
+
+    for (const name of names) {
+        if (!name.endsWith('.json')) {
+            ledger?.outOfScope(name, 'not_applicable_kind');
+            continue;
+        }
+        const file = path.join(dir, name);
+        let doc: unknown;
+        try {
+            doc = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        } catch {
+            // Not our corpus; a malformed JSON is another gate's finding.
+            ledger?.skip(name, 'binary_content');
+            continue;
+        }
+        if (!isBenchmarkReport(doc)) {
+            ledger?.outOfScope(name, 'not_applicable_kind');
+            continue;
+        }
+        scanned += 1;
+        const problems = [...validateCacheBlock(doc), ...validateProvenanceBlock(doc)];
+        for (const p of problems) {
+            findings.push({ file: path.relative(REPO_ROOT, file), message: describeProblem(p) });
+        }
+        if (problems.length > 0) ledger?.fail(name, `${String(problems.length)} missing or malformed required field(s)`);
+        else ledger?.complete(name);
+    }
+    return { scanned, findings };
+}
+
+// ---------------------------------------------------------------- self-test
+
+const BASE = { schema_version: 1, corpus: { id: 'x' }, selection: { top_k: 3 } };
+
+const GOOD_CACHE = { read_write_ratio: 2, stable_prefix_share: 0.5 };
+
+/** A provenance block that passes, so a cache-field case tests only cache fields. */
+const GOOD_PROVENANCE = {
+    host_binary_hash: 'sha256:deadbeef',
+    harness_commit: 'abc1234',
+    harness_dirty: false,
+    reproducibility: 'task bench-run --corpus x at the commit above',
+};
+
+function plant(dir: string, cache: unknown, provenance: unknown = GOOD_PROVENANCE): void {
+    const doc: Record<string, unknown> = { ...BASE };
+    if (cache !== undefined) doc['cache'] = cache;
+    if (provenance !== undefined) doc['provenance'] = provenance;
+    fs.writeFileSync(path.join(dir, 'report.json'), JSON.stringify(doc));
+}
+
+function selfTestCases(): SelfTestCase[] {
+    const mk = (name: string, expect: 'reject' | 'accept', cache: unknown, provenance?: unknown): SelfTestCase => ({
+        name,
+        expect,
+        run: () => {
+            const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'brf-'));
+            try {
+                plant(dir, cache, provenance === undefined ? GOOD_PROVENANCE : provenance);
+                return runGateCli(REPO_ROOT, 'src/scripts/check_benchmark_report_fields.ts', ['--dir', dir, '--quiet'], REPO_ROOT);
+            } finally {
+                fs.rmSync(dir, { recursive: true, force: true });
+            }
+        },
+    });
+    return [
+        mk('no cache block at all → reject', 'reject', undefined),
+        mk('read_write_ratio missing → reject', 'reject', { stable_prefix_share: 0.5 }),
+        mk('stable_prefix_share missing → reject', 'reject', { read_write_ratio: 2 }),
+        mk('both present as numbers → accept', 'accept', { read_write_ratio: 2, stable_prefix_share: 0.5 }),
+        mk('unavailable WITH a reason → accept', 'accept', {
+            read_write_ratio: { unavailable: 'no cache_creation tokens in window' },
+            stable_prefix_share: 0.5,
+        }),
+        mk('unavailable with a BLANK reason → reject', 'reject', {
+            read_write_ratio: { unavailable: '  ' },
+            stable_prefix_share: 0.5,
+        }),
+        mk('a share above 1 → reject', 'reject', { read_write_ratio: 2, stable_prefix_share: 1.5 }),
+        // Provenance half (step 4.2) — the four reproducibility fields.
+        mk('no provenance block at all → reject', 'reject', GOOD_CACHE, null),
+        mk('harness_commit missing → reject', 'reject', GOOD_CACHE, { ...GOOD_PROVENANCE, harness_commit: undefined }),
+        mk('reproducibility is an empty string → reject', 'reject', GOOD_CACHE, { ...GOOD_PROVENANCE, reproducibility: '  ' }),
+        mk('harness_dirty as a string → reject', 'reject', GOOD_CACHE, { ...GOOD_PROVENANCE, harness_dirty: 'no' }),
+        // `false` is the GOOD case for a dirty flag, and a truthiness check
+        // would silently reject it. Pinned so it cannot regress.
+        mk('harness_dirty: false → accept', 'accept', GOOD_CACHE, { ...GOOD_PROVENANCE, harness_dirty: false }),
+        mk('harness_dirty: true → accept — a fact, not a failure', 'accept', GOOD_CACHE, { ...GOOD_PROVENANCE, harness_dirty: true }),
+        mk('a field unavailable WITH a reason → accept', 'accept', GOOD_CACHE, {
+            ...GOOD_PROVENANCE,
+            host_binary_hash: { unavailable: 'the host binary is not on PATH in this runner' },
+        }),
+    ];
+}
+
+// ---------------------------------------------------------------------- CLI
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+    if (argv.includes('--self-test')) {
+        return runSelfTest({ gate: 'check_benchmark_report_fields', cases: selfTestCases(), minCases: 12, minRejectCases: 8 });
+    }
+    const quiet = argv.includes('--quiet');
+    const di = argv.indexOf('--dir');
+    const dirArg = di !== -1 ? argv[di + 1] : undefined;
+    const dir = dirArg !== undefined ? path.resolve(dirArg) : DEFAULT_DIR;
+
+    const ledger = new GateLedger('check_benchmark_report_fields');
+    let v: FieldVerdict;
+    try {
+        v = evaluate(dir, ledger);
+    } catch (err) {
+        process.stderr.write(`❌  check_benchmark_report_fields: ${(err as Error).message}\n`);
+        return 2;
+    }
+
+    try {
+        reportScanned({
+            gate: 'check_benchmark_report_fields',
+            scanned: v.scanned,
+            units: 'benchmark report(s)',
+            roots: [path.relative(REPO_ROOT, dir)],
+            // A tree with no committed benchmark report is a real state: reports
+            // are run artefacts, not source. The gate exists to fail the day one
+            // is committed without the block, not to demand one exist.
+            allowEmpty: 'OPTIONAL_INPUT: benchmark reports are run artefacts; a checkout may legitimately carry none',
+        });
+    } catch (err) {
+        if (err instanceof DeadScopeError) {
+            process.stderr.write(`❌  check_benchmark_report_fields: ${err.message}\n`);
+            return 2;
+        }
+        throw err;
+    }
+
+    ledger.report();
+
+    if (v.findings.length > 0) {
+        for (const f of v.findings) process.stderr.write(`❌  ${f.file}: ${f.message}\n`);
+        process.stderr.write(`\n    Contract: docs/contracts/benchmark-report-schema.md § The \`cache\` block.\n`);
+        return 1;
+    }
+    if (!quiet) process.stdout.write(`✅  every benchmark report carries its required cache and provenance fields (${String(v.scanned)} report(s)).\n`);
+    return 0;
+}
+
+if (process.env['GATE_SELF_TEST_CHILD'] !== '1' || process.argv.includes('--dir')) {
+    if (process.argv[1] !== undefined && import.meta.url === `file://${process.argv[1]}`) {
+        process.exit(main());
+    }
+}

package/src/scripts/check_beta_review_markers.ts

@@ -16,11 +16,13 @@
  * Exit codes: 0 = clean, 1 = violations found, 3 = internal error.
  */
 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 { asOf } from './_lib/as_of.js';
-import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+import { runGateCli, runSelfTest } from './_lib/gate_self_test.js';
+import { DeadScopeError, reportScanned } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -30,6 +32,85 @@ const FRONTMATTER_RE = /^---\s*\n([\s\S]*?)\n---\s*\n/;
 const STABILITY_RE = /^stability:\s*(\w+)\s*$/m;
 const PROMOTE_RE = /^promote-to:\s*stable\s*$/m;
 const KEEP_RE = /^keep-beta-until:\s*(\d{4}-\d{2}-\d{2})\s*$/m;
+
+/**
+ * The frozen no-growth baseline of contracts already lapsed at 2026-08-25.
+ *
+ * AI council 2/2 (2026-08-25) chose a **ratchet** over both a flat report and a
+ * flat error. The shape, and each clause is load-bearing:
+ *
+ *   - a lapsed contract **in** the baseline  -> warning (inherited debt)
+ *   - a lapsed contract **not** in it        -> ERROR   (a fresh lapse, today)
+ *
+ * So new work is enforced immediately while the 86-contract cohort does not red
+ * an arbitrary future PR whose author caused none of it. The cohort is real:
+ * 44 of the 86 lapsed on the same day and 64 within four days, which is one past
+ * session's uniform window expiring at once rather than 86 lapses of discipline.
+ *
+ * **The list may not grow, and an entry may not be re-added.** Both are the
+ * ratchet, and both fall out of the rule above rather than needing their own
+ * check: anything not already in the file errors.
+ *
+ * **Removal is derived from the contract's own state, never from editing this
+ * file.** An entry stops mattering because the contract stopped being a lapsed
+ * beta — promoted, recorded unmaintained, superseded, or given a reviewed new
+ * deadline. One seat asked for exactly this qualification, on the ground that an
+ * allowlist whose entries can simply be deleted is cosmetic.
+ */
+const BASELINE_REL = 'src/config/lapsed-beta-baseline.json';
+
+interface LapsedBaseline {
+    contracts: string[];
+}
+
+let _baselineCache: Set<string> | null = null;
+
+export function loadLapsedBaseline(root: string = ROOT): Set<string> {
+    if (_baselineCache !== null) {
+        return _baselineCache;
+    }
+    const p = path.join(root, BASELINE_REL);
+    if (!fs.existsSync(p)) {
+        // The baseline reaching zero is the SUCCESS state: the file is deleted
+        // in the same change that flips the severity. An absent file therefore
+        // means "no inherited debt", i.e. every lapse is fresh and errors.
+        _baselineCache = new Set<string>();
+        return _baselineCache;
+    }
+    const parsed = JSON.parse(fs.readFileSync(p, 'utf-8')) as LapsedBaseline;
+    _baselineCache = new Set(parsed.contracts);
+    return _baselineCache;
+}
+
+/** Test seam — the module-level cache would otherwise outlive a fixture. */
+export function _resetLapsedBaseline(): void {
+    _baselineCache = null;
+}
+
+/**
+ * Severity of the LAPSED-deadline finding — `keep-beta-until` in the past.
+ *
+ * `warning` on purpose, and this constant exists so that promoting it is a
+ * one-word, reviewable change rather than an edit buried in a branch.
+ *
+ * Until 2026-08-25 the gate compared `keep-beta-until` ONLY against
+ * `today + MAX_REVIEW_WINDOW_DAYS` and errored when the date was too far in the
+ * FUTURE. There was no floor, so a date arbitrarily far in the PAST passed and
+ * the gate printed "All beta contracts carry a valid review marker" while 86 of
+ * the 121 beta contracts were lapsed. The gate enforced the ceiling of the
+ * review window and never its expiry.
+ *
+ * It ships as a report rather than an error because the backlog is a COHORT:
+ * 44 of those 86 lapsed on the same day (2026-08-12) and 64 within four days,
+ * which is one past session's uniform window expiring en masse rather than 86
+ * independent lapses. Erroring on a cohort artifact produces one loud failure on
+ * an arbitrary future PR whose author did nothing wrong — the way a gate gets
+ * waived instead of adopted. The inventory and its dispositions are
+ * `agents/evidence/analysis/lapsed-beta-inventory-2026-08-25.md`; the decision on
+ * whether this becomes an error is that roadmap's step 0.2 and is not taken here.
+ */
+const LAPSED_SEVERITY_IN_BASELINE: 'error' | 'warning' = 'warning';
+const LAPSED_SEVERITY_FRESH: 'error' | 'warning' = 'error';
 const SUPERSEDED_RE = /^superseded-by:\s*\S+\s*$/m;
 
 const MAX_REVIEW_WINDOW_DAYS = 90;
@@ -146,6 +227,26 @@ function check_one(p: string, todayOrdinal: number): Violation[] {
     if (km) {
         const [ry, rm, rd] = _parseISODate(km[1]!);
         const reviewOrdinal = _dateOrdinal(ry, rm, rd);
+        // Lower bound — the deadline has passed. Checked BEFORE the upper
+        // bound because a lapsed date can never also exceed the forward window,
+        // so the order is a readability choice rather than a precedence one.
+        if (reviewOrdinal < todayOrdinal) {
+            const inherited = loadLapsedBaseline().has(rel);
+            const age = todayOrdinal - reviewOrdinal;
+            return [
+                {
+                    file: rel,
+                    reason:
+                        `keep-beta-until=${_ordinalToISO(reviewOrdinal)} has LAPSED ` +
+                        `(${age} day(s) ago); review the contract and ` +
+                        'promote it, extend the window with a reason, or record it as superseded' +
+                        (inherited
+                            ? ' [inherited: in the frozen 2026-08-25 baseline, clear by 2026-11-23]'
+                            : ' [FRESH lapse — not in the frozen baseline, which may not grow]'),
+                    severity: inherited ? LAPSED_SEVERITY_IN_BASELINE : LAPSED_SEVERITY_FRESH,
+                },
+            ];
+        }
         const maxOrdinal = todayOrdinal + MAX_REVIEW_WINDOW_DAYS;
         if (reviewOrdinal > maxOrdinal) {
             return [
@@ -162,17 +263,65 @@ function check_one(p: string, todayOrdinal: number): Violation[] {
     return [];
 }
 
+
+/**
+ * STABILITY.md's own re-audit condition, as a command instead of as prose.
+ *
+ * `STABILITY.md`:
+ *
+ *   "The audit is repeated whenever the `keep-beta-until` date passes for
+ *    >= 25 % of beta contracts, or at the start of any roadmap phase that
+ *    touches the contract surface."
+ *
+ * That condition was met at 71.1 % and nothing noticed, which is the defect
+ * `road-to-contract-review-deadlines` D2 records. A trigger nobody can run is
+ * how a threshold gets crossed by a factor of three in silence — so the
+ * percentage is computed here, next to the data, and printed.
+ *
+ * Deliberately a REPORT, not a gate: the enforcement half is the frozen
+ * baseline plus the fresh-lapse error above. A second failing check over the
+ * same population would red the same PRs twice for one cause.
+ */
+export const REAUDIT_TRIGGER_PCT = 25;
+
+export interface TriggerVerdict {
+    betaContracts: number;
+    lapsed: number;
+    pct: number;
+    fired: boolean;
+}
+
+export function evaluateTrigger(violations: readonly Violation[], betaContracts: number): TriggerVerdict {
+    const lapsed = violations.filter((v) => v.reason.includes('has LAPSED')).length;
+    const pct = betaContracts === 0 ? 0 : (lapsed / betaContracts) * 100;
+    return { betaContracts, lapsed, pct, fired: pct >= REAUDIT_TRIGGER_PCT };
+}
+
 interface ParsedArgs {
     json: boolean;
+    trigger: boolean;
+    /** Fixture root, for `--self-test`. A fixture is never judged against the repo baseline. */
+    root: string | null;
 }
 
 function parse_args(argv: readonly string[]): ParsedArgs {
-    const args: ParsedArgs = { json: false };
-    for (const arg of argv) {
+    const args: ParsedArgs = { json: false, trigger: false, root: null };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i] as string;
         if (arg === '--json') {
             args.json = true;
+        } else if (arg === '--root') {
+            args.root = argv[i + 1] ?? null;
+            i += 1;
+        } else if (arg === '--trigger') {
+            args.trigger = true;
         } else if (arg === '-h' || arg === '--help') {
-            process.stdout.write('usage: check_beta_review_markers [-h] [--json]\n');
+            process.stdout.write(
+                'usage: check_beta_review_markers [-h] [--json] [--trigger]\n' +
+                    '  --trigger  print the lapsed percentage and whether STABILITY.md\n' +
+                    '             re-audit condition (>= 25 %) has fired. Reports; never fails.\n' +
+                    '  --root DIR judge a fixture tree instead of the repo (self-test seam).\n',
+            );
             process.exit(0);
         } else {
             process.stderr.write(
@@ -190,12 +339,70 @@ function _todayOrdinal(): number {
     return _dateOrdinal(now.getFullYear(), now.getMonth() + 1, now.getDate());
 }
 
+
+/**
+ * Self-test — the gate proving it still DISCRIMINATES, not merely that it ran.
+ *
+ * A `scanned:` floor proves a gate read something; only a rejecting case proves
+ * the reading changes the verdict. All four cases shell out to the real CLI
+ * through a fixture `docs/contracts/`, because an in-process call cannot catch
+ * an argv parser or an entry guard that silently no-ops.
+ */
+export function selfTest(): number {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'beta-selftest-'));
+    const write = (name: string, body: string): string => {
+        const dir = path.join(tmp, name, 'docs', 'contracts');
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(path.join(dir, 'sample.md'), body, 'utf-8');
+        return path.join(tmp, name);
+    };
+    const run = (root: string): number =>
+        runGateCli(ROOT, 'src/scripts/check_beta_review_markers.ts', ['--root', root], root);
+
+    try {
+        return runSelfTest({
+            gate: 'check_beta_review_markers',
+            minCases: 4,
+            minRejectCases: 2,
+            cases: [
+                {
+                    name: 'a lapsed deadline outside the frozen baseline is rejected',
+                    expect: 'reject',
+                    run: () => run(write('lapsed', '---\nstability: beta\nkeep-beta-until: 2020-01-01\n---\n')),
+                },
+                {
+                    name: 'a beta contract with NO marker at all is rejected',
+                    expect: 'reject',
+                    run: () => run(write('nomarker', '---\nstability: beta\n---\n')),
+                },
+                {
+                    name: 'a beta contract inside its window passes',
+                    expect: 'accept',
+                    run: () => run(write('fresh', `---\nstability: beta\nkeep-beta-until: ${_ordinalToISO(_todayOrdinal() + 30)}\n---\n`)),
+                },
+                {
+                    name: 'a stable contract needs no marker and passes',
+                    expect: 'accept',
+                    run: () => run(write('stable', '---\nstability: stable\n---\n')),
+                },
+            ],
+        });
+    } finally {
+        fs.rmSync(tmp, { recursive: true, force: true });
+    }
+}
+
 function main(): number {
+    if (process.argv.slice(2).includes('--self-test')) return selfTest();
     const args = parse_args(process.argv.slice(2));
     const todayOrdinal = _todayOrdinal();
     const violations: Violation[] = [];
-    const contracts = _globMdSorted(path.join(ROOT, CONTRACTS_DIR));
+    const scanRoot = args.root ?? ROOT;
+    const contracts = _globMdSorted(path.join(scanRoot, CONTRACTS_DIR));
+    let betaContracts = 0;
     for (const p of contracts) {
+        const fm = read_frontmatter(p);
+        if (fm !== null && /^stability:\s*beta\s*$/m.test(fm)) betaContracts += 1;
         violations.push(...check_one(p, todayOrdinal));
     }
     // Count every contract read, not the `stability: beta` subset: over a moved
@@ -203,7 +410,13 @@ function main(): number {
     // the same clean line, and only the second is a dead gate. Exit 1 is the
     // violation code; 3 stays reserved for the internal-error handler below.
     try {
-        assertScanned({
+        // `reportScanned`, not `assertScanned`: the gate-coverage manifest's
+        // rule 1 requires exactly one machine-readable `scanned: <N>` line, and
+        // asserting without printing satisfies the scope guard while leaving the
+        // census blind — which is the same "green over nothing" shape both
+        // mechanisms exist to end. Emitted on the RED path too, so the gate
+        // cannot report its coverage only when it passes.
+        reportScanned({
             gate: 'check_beta_review_markers',
             scanned: contracts.length,
             units: 'contract file(s)',
@@ -216,6 +429,22 @@ function main(): number {
         }
         throw exc;
     }
+    if (args.trigger) {
+        const t = evaluateTrigger(violations, betaContracts);
+        const line =
+            `beta contracts: ${String(t.betaContracts)} · lapsed: ${String(t.lapsed)} · ` +
+            `${t.pct.toFixed(1)} % · STABILITY.md re-audit trigger (>= ${String(REAUDIT_TRIGGER_PCT)} %): ` +
+            (t.fired ? 'FIRED' : 'not fired');
+        if (args.json) {
+            process.stdout.write(JSON.stringify({ trigger: t }, null, 2) + '\n');
+        } else {
+            process.stdout.write(`${line}\n`);
+        }
+        // A report never fails a build. The enforcement half is the frozen
+        // baseline plus the fresh-lapse error; failing here too would red the
+        // same pull request twice for one cause.
+        return 0;
+    }
     if (args.json) {
         process.stdout.write(JSON.stringify({ violations }, null, 2) + '\n');
     } else {