@event4u/agent-config 14.12.0 → 14.14.0

package/src/scripts/check_adr_frontmatter.ts

@@ -43,7 +43,9 @@ import {
     AGENTIC_MODES,
     DISCOVERY_STATES,
     EVIDENCE_STRENGTHS,
+    PROTECTED_DIMENSIONS,
     PROVENANCE_KINDS,
+    REOPEN_POLICIES,
     evidenceOf,
     provenanceOf,
     readAdrFrontmatter,
@@ -60,6 +62,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;
 
@@ -73,16 +89,9 @@ const REQUIRED = ['adr', 'status', 'date', 'decision'] as const;
  * the same words. This validator therefore checks the VALUE when present and
  * never requires the KEY.
  */
-const ALLOWED_REOPEN_POLICY = new Set(['directional', 'owner', 'unclassified']);
-
-const ALLOWED_PROTECTED_DIMENSIONS = new Set([
-    'purpose',
-    'security_floor',
-    'privacy_floor',
-    'external_commitment',
-    'governance',
-    'none',
-]);
+const ALLOWED_REOPEN_POLICY = new Set<string>(REOPEN_POLICIES);
+
+const ALLOWED_PROTECTED_DIMENSIONS = new Set<string>(PROTECTED_DIMENSIONS);
 
 /** Split an inline `[a, b]` list or a folded multi-value string into members. */
 export function split_dimensions(raw: string): string[] {
@@ -150,6 +159,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 +273,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 +562,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());
+    }
+}