@event4u/agent-config 15.0.0 → 16.1.0

package/src/scripts/check_test_weakening.ts

@@ -0,0 +1,299 @@
+#!/usr/bin/env tsx
+/**
+ * check_test_weakening — a test that asserts less than it did needs a verdict.
+ *
+ * `road-to-adversarial-verification-and-long-runs` Phase 2.4, second of two.
+ * `evaluator-independence` § Tests are evaluators forbids an implementer from
+ * silently weakening an assertion, deleting a failing test, skipping it, or
+ * loosening a threshold. This gate sees the shape of that in a diff.
+ *
+ * **NET counts, never raw removals — the whole gate turns on this.** Editing an
+ * assertion removes one line and adds another, so a gate counting removals reds
+ * every legitimate test edit. A gate that reds every PR gets its exemption
+ * widened until it finds nothing, which is Risk 4 of the roadmap that
+ * commissioned it and the allowlist-growth antipattern `autonomous-execution`
+ * already names. A NET loss is a different, much narrower claim: after this
+ * diff, the file asserts less than before.
+ *
+ * **What makes a weakening legitimate is an independent verdict**, and this gate
+ * checks only that one was COMMITTED in the same diff. Whether it actually
+ * contains an independent verdict is a judgement no gate can make, so it is not
+ * claimed here.
+ *
+ * Usage:
+ *   check_test_weakening [--diff-file F] [--files F …] [--base-ref REF]
+ *                        [--root DIR] [--quiet] [--self-test]
+ *
+ * Exit codes: 0 = pass (or discharged) · 1 = fail · 2 = usage error.
+ */
+
+import { spawnSync } from 'node:child_process';
+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 { GateLedger } from './_lib/gate_ledger.js';
+import { runGateCli, runSelfTest } from './_lib/gate_self_test.js';
+import { reportScanned } from './_lib/scan_scope.js';
+import {
+    isTestPath,
+    isVerdictArtefact,
+    isWeakening,
+    parseUnifiedDiff,
+    weakeningSignal,
+    type WeakeningSignal,
+} from './_lib/test_delta.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO = path.resolve(path.dirname(_HERE), '..', '..');
+
+export interface WeakeningReport {
+    readonly signals: readonly WeakeningSignal[];
+    readonly discharged: boolean;
+    readonly scanned: number;
+}
+
+/** The decision, pure: which test files weakened, and was a verdict committed. */
+export function analyse(diff: string, changedFiles: readonly string[]): WeakeningReport {
+    const files = parseUnifiedDiff(diff).filter((f) => isTestPath(f.path));
+    const signals = files.map(weakeningSignal).filter(isWeakening);
+    return {
+        signals,
+        discharged: changedFiles.some(isVerdictArtefact),
+        scanned: files.length,
+    };
+}
+
+/** One human-readable line per weakened file. */
+export function renderSignal(s: WeakeningSignal): string {
+    const parts: string[] = [];
+    if (s.assertionsLost > 0) parts.push(`${String(s.assertionsLost)} assertion(s) net-removed`);
+    if (s.suppressionsGained > 0) {
+        parts.push(`${String(s.suppressionsGained)} suppression(s) net-added`);
+    }
+    return `${s.path}: ${parts.join(' · ')}`;
+}
+
+function git(args: readonly string[], root: string): string | null {
+    const r = spawnSync('git', [...args], { cwd: root, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
+    return r.status === 0 ? r.stdout : null;
+}
+
+function resolveBaseRef(explicit: string | null, root: string): string {
+    if (explicit !== null) return explicit;
+    for (const ref of ['origin/main', 'origin/master', 'main', 'master']) {
+        if (git(['rev-parse', '--verify', '--quiet', ref], root) !== null) return ref;
+    }
+    return 'HEAD~1';
+}
+
+function usage(): string {
+    return (
+        'usage: check_test_weakening [--diff-file F] [--files F …] [--base-ref REF]\n' +
+        '                            [--root DIR] [--quiet] [--self-test]\n'
+    );
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    if (argv.includes('--help') || argv.includes('-h')) {
+        process.stdout.write(usage());
+        return 0;
+    }
+    if (argv.includes('--self-test')) return selfTest();
+
+    const quiet = argv.includes('--quiet');
+    const at = (flag: string): string | null => {
+        const i = argv.indexOf(flag);
+        return i >= 0 ? (argv[i + 1] ?? null) : null;
+    };
+    const root = at('--root') ?? REPO;
+
+    let diff: string;
+    let changed: string[];
+    const diffFile = at('--diff-file');
+    const fi = argv.indexOf('--files');
+    if (diffFile !== null) {
+        try {
+            diff = fs.readFileSync(diffFile, 'utf8');
+        } catch {
+            process.stderr.write(`check_test_weakening: cannot read ${diffFile}\n`);
+            return 2;
+        }
+        changed = fi >= 0 ? argv.slice(fi + 1).filter((a) => !a.startsWith('--')) : [];
+    } else {
+        const base = resolveBaseRef(at('--base-ref'), root);
+        const d = git(['diff', '--unified=0', `${base}...HEAD`], root);
+        const names = git(['diff', '--name-only', `${base}...HEAD`], root);
+        if (d === null || names === null) {
+            process.stderr.write('check_test_weakening: git diff failed\n');
+            return 2;
+        }
+        diff = d;
+        changed = names.split('\n').map((s) => s.trim()).filter((s) => s !== '');
+    }
+
+    // Per-file accounting: a changed test file either measured clean, measured
+    // weakened, or was discharged by a committed verdict. Without it, "no test
+    // file changed" and "every test file was skipped" print the same green line.
+    const parsed = parseUnifiedDiff(diff);
+    const ledger = new GateLedger('check_test_weakening');
+    ledger.plan(parsed.map((f) => `file:${f.path}`));
+    const report = analyse(diff, changed);
+    const weakened = new Set(report.signals.map((s) => s.path));
+    for (const f of parsed) {
+        const target = `file:${f.path}`;
+        if (!isTestPath(f.path)) {
+            ledger.outOfScope(target, 'not_applicable_kind');
+            continue;
+        }
+        if (!weakened.has(f.path)) ledger.complete(target);
+        else if (report.discharged) ledger.outOfScope(target, 'declared_exemption');
+        else ledger.fail(target, renderSignal(weakeningSignal(f)));
+    }
+    ledger.report();
+
+    reportScanned({
+        gate: 'check_test_weakening',
+        scanned: report.scanned,
+        units: 'changed test file(s)',
+        roots: ['<the diff against the base ref>'],
+        // A diff touching no test file is the normal case for a docs or config
+        // change, and reporting it as a dead scope would make the gate cry wolf
+        // on most of the PRs it runs against.
+        allowEmpty: 'EMPTY_VALID: a diff that changes no test file has nothing to weaken',
+    });
+
+    if (report.signals.length === 0) {
+        if (!quiet) {
+            process.stdout.write(
+                `✅  check_test_weakening: ${String(report.scanned)} test file(s), no net weakening\n`,
+            );
+        }
+        return 0;
+    }
+
+    if (report.discharged) {
+        process.stdout.write(
+            `✅  check_test_weakening: ${String(report.signals.length)} weakened file(s), ` +
+                'discharged by an independent-verdict artefact under agents/evidence/reviews/\n',
+        );
+        return 0;
+    }
+
+    process.stderr.write(
+        `❌  check_test_weakening: ${String(report.signals.length)} test file(s) assert less ` +
+            'than before, with no independent-verdict artefact in this diff:\n' +
+            report.signals.map((s) => `  - ${renderSignal(s)}\n`).join('') +
+            '  An implementer may not weaken a test silently (src/rules/evaluator-independence.md\n' +
+            '  § Tests are evaluators). Where the test is genuinely wrong: evidence → independent\n' +
+            '  test review → council or team, then commit the verdict under agents/evidence/reviews/.\n',
+    );
+    return 1;
+}
+
+function selfTest(): number {
+    const withDiff = (diff: string, files: readonly string[] = []): number => {
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ctw-'));
+        const f = path.join(dir, 'd.diff');
+        fs.writeFileSync(f, diff);
+        try {
+            const args = ['--diff-file', f, '--quiet'];
+            if (files.length > 0) args.push('--files', ...files);
+            return runGateCli(REPO, 'src/scripts/check_test_weakening.ts', args, dir);
+        } finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    };
+    const header = (p: string): string => `diff --git a/${p} b/${p}\n--- a/${p}\n+++ b/${p}\n@@\n`;
+
+    return runSelfTest({
+        gate: 'check_test_weakening',
+        minCases: 6,
+        minRejectCases: 3,
+        cases: [
+            {
+                name: 'a net-removed assertion is REJECTED',
+                expect: 'reject',
+                run: () =>
+                    withDiff(header('tests/a.test.ts') + "-    expect(x).toBe(1);\n"),
+            },
+            {
+                name: 'an added it.skip is REJECTED',
+                expect: 'reject',
+                run: () => withDiff(header('tests/a.test.ts') + "+    it.skip('x', () => {});\n"),
+            },
+            {
+                name: 'an added @pytest.mark.skip is REJECTED — not a one-framework gate',
+                expect: 'reject',
+                run: () => withDiff(header('tests/a_test.py') + '+@pytest.mark.skip\n'),
+            },
+            {
+                name: 'EDITING an assertion is not weakening — the net is zero',
+                expect: 'accept',
+                run: () =>
+                    withDiff(
+                        header('tests/a.test.ts') +
+                            "-    expect(x).toBe(1);\n+    expect(x).toBe(2);\n",
+                    ),
+            },
+            {
+                name: 'ADDING assertions is never weakening',
+                expect: 'accept',
+                run: () =>
+                    withDiff(
+                        header('tests/a.test.ts') +
+                            "+    expect(x).toBe(1);\n+    expect(y).toBe(2);\n",
+                    ),
+            },
+            {
+                name: 'DELETING a whole test file is the maximal weakening, and REDS',
+                expect: 'reject',
+                run: () =>
+                    withDiff(
+                        'diff --git a/tests/a.test.ts b/tests/a.test.ts\n' +
+                            '--- a/tests/a.test.ts\n+++ /dev/null\n@@\n' +
+                            '-expect(x).toBe(1);\n',
+                    ),
+            },
+            {
+                name: 'a removed assertion in PRODUCTION code is out of scope',
+                expect: 'accept',
+                run: () => withDiff(header('src/a.ts') + '-    expect(x).toBe(1);\n'),
+            },
+            {
+                name: 'REMOVING a skip is the opposite of weakening',
+                expect: 'accept',
+                run: () => withDiff(header('tests/a.test.ts') + "-    it.skip('x', () => {});\n"),
+            },
+            {
+                name: 'a DIFF FIXTURE held as string data is not a suppression',
+                expect: 'accept',
+                run: () =>
+                    withDiff(
+                        header('tests/gate.test.ts') +
+                            '+            \'+@pytest.mark.skip\\n\',\n',
+                    ),
+            },
+            {
+                name: '…and the same construct written as CODE still reds',
+                expect: 'reject',
+                run: () => withDiff(header('tests/gate.test.ts') + '+@pytest.mark.skip\n'),
+            },
+            {
+                name: 'a committed verdict artefact discharges a real weakening',
+                expect: 'accept',
+                run: () =>
+                    withDiff(header('tests/a.test.ts') + '-    expect(x).toBe(1);\n', [
+                        'agents/evidence/reviews/some-review.md',
+                    ]),
+            },
+        ],
+    });
+}
+
+/* c8 ignore start — CLI entry, exercised by the self-test rather than in-process. */
+if (import.meta.url === pathToFileURL(path.resolve(process.argv[1] ?? '')).href) {
+    process.exit(main());
+}
+/* c8 ignore stop */

package/src/scripts/closure_scan.ts

@@ -0,0 +1,333 @@
+#!/usr/bin/env tsx
+/**
+ * The closure detector — finds the open decisions in a plan, and classifies
+ * each one by OWNERSHIP. It never resolves one.
+ *
+ * That boundary is the whole design. A decision dispatcher was killed on
+ * purpose: no TypeScript path routes a decision, and this script adds none.
+ * What it adds is the half that can be mechanical — *which questions are open,
+ * and whose they are* — so the claim "this plan reached execution with twelve
+ * open technical decisions and asked the owner none of them" is falsifiable
+ * rather than a feeling.
+ *
+ * Detector families, each a phrase an author writes when they KNOW something
+ * is open. Deliberately narrow: a detector that fires on ordinary plan prose
+ * turns every producer red at once, and the cheapest repair is then to weaken
+ * it until it finds nothing.
+ *
+ *   `tbd`                      TBD / to be decided / decide later
+ *   `unpicked-alternative`     "either X or Y", "option A … option B"
+ *   `unchecked-assumption`     "assuming", "presumably", "probably fine"
+ *   `missing-verify`           an open step with no `verify:` line
+ *   `ambiguous-acceptance`     a vague acceptance criterion (improve / clean up
+ *                              / best practices / handle errors properly)
+ *   `contradictory`            "contradicts", "conflicts with", "but also"
+ *   `product-semantics`        two valid user-visible outcomes
+ *   `typed-op`                 an operation from the typed vocabulary
+ *   `spend`                    a ceiling or quota question
+ *
+ * Ownership classification is the output that matters. Six families classify
+ * to a technical class the agent, an independent session, a council or a team
+ * resolves; exactly two reach the owner (`product-semantics` → `product-owned`,
+ * `typed-op` → `destructive-owned`); `spend` reaches nobody — it pauses and
+ * reports (ADR-268 § 8).
+ *
+ * Exit codes: 0 no open decisions · 1 open decisions found · 2 bad argv.
+ * Finding open decisions is the POINT, so `--strict` is what makes exit 1 a
+ * failure for a caller that wants one; the default is a report.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+const _PROG = 'closure_scan';
+
+export type Kind =
+    | 'tbd'
+    | 'unpicked-alternative'
+    | 'unchecked-assumption'
+    | 'missing-verify'
+    | 'ambiguous-acceptance'
+    | 'contradictory'
+    | 'product-semantics'
+    | 'typed-op'
+    | 'spend';
+
+export interface Finding {
+    readonly id: string;
+    readonly line: number;
+    readonly kind: Kind;
+    readonly ownership: string;
+    readonly excerpt: string;
+}
+
+/**
+ * Kind → ownership class. The two owner-routed rows are the whole cost of
+ * closure: everything else is resolved without reaching a person, which is
+ * what "zero owner questions for twelve technical ambiguities" means.
+ */
+export const OWNERSHIP_BY_KIND: Readonly<Record<Kind, string>> = {
+    tbd: 'contested-technical',
+    'unpicked-alternative': 'contested-technical',
+    'unchecked-assumption': 'reversible-technical',
+    'missing-verify': 'deterministic',
+    'ambiguous-acceptance': 'reversible-technical',
+    contradictory: 'contested-technical',
+    'product-semantics': 'product-owned',
+    'typed-op': 'destructive-owned',
+    spend: 'spend-exhaustion',
+};
+
+/** Classes that reach a person. Everything else closes without an ask. */
+export const OWNER_ROUTED: ReadonlySet<string> = new Set([
+    'product-owned',
+    'business-owned',
+    'destructive-owned',
+]);
+
+interface Pattern {
+    readonly kind: Kind;
+    readonly re: RegExp;
+}
+
+const LINE_PATTERNS: readonly Pattern[] = [
+    { kind: 'tbd', re: /\bTBD\b/ },
+    { kind: 'tbd', re: /\bto be decided\b/i },
+    { kind: 'tbd', re: /\bdecide later\b/i },
+    { kind: 'unpicked-alternative', re: /\beither\b[^.]{3,80}\bor\b/i },
+    { kind: 'unpicked-alternative', re: /\boption A\b[^.]{0,120}\boption B\b/i },
+    { kind: 'unpicked-alternative', re: /\bwe could (?:either )?\w+[^.]{0,80}\bor\b/i },
+    // "two equal technical strategies" is the canonical unpicked alternative,
+    // and the phrasing an author reaches for when the choice is genuinely open
+    // — it carries no `either`, no `or` and no `option A`.
+    { kind: 'unpicked-alternative', re: /\btwo (?:equal|competing)\b[^.]{0,60}\b(?:strateg|approach|design|option)/i },
+    { kind: 'unchecked-assumption', re: /\bassuming\b/i },
+    { kind: 'unchecked-assumption', re: /\bpresumably\b/i },
+    { kind: 'unchecked-assumption', re: /\bprobably (?:fine|works|ok)\b/i },
+    { kind: 'ambiguous-acceptance', re: /\b(?:improve|optimi[sz]e)\b(?![^.]*\bby\b)/i },
+    { kind: 'ambiguous-acceptance', re: /\bmake it (?:better|cleaner|nicer)\b/i },
+    { kind: 'ambiguous-acceptance', re: /\buse best practices\b/i },
+    { kind: 'ambiguous-acceptance', re: /\bhandle errors properly\b/i },
+    { kind: 'contradictory', re: /\bcontradicts\b/i },
+    { kind: 'contradictory', re: /\bconflicts with\b/i },
+    { kind: 'product-semantics', re: /\buser-visible\b[^.]{0,80}\b(?:or|versus|vs\.?)\b/i },
+    { kind: 'product-semantics', re: /\bwhat the user sees\b/i },
+    { kind: 'product-semantics', re: /\btwo valid (?:user|product) semantics\b/i },
+    { kind: 'typed-op', re: /\b(?:merge|force-push|deploy|publish|purchase|rotate the secret)\b/i },
+    { kind: 'spend', re: /\b(?:over|above|crosses?) the (?:configured )?(?:spend )?ceiling\b/i },
+    { kind: 'spend', re: /\bquota (?:is )?(?:exhausted|gone)\b/i },
+];
+
+const STEP_RE = /^\s*-\s\[[ x~-]\]\s/;
+const OPEN_STEP_RE = /^\s*-\s\[ \]\s/;
+const H2_RE = /^##\s+/;
+const DISCHARGE_H2_RE = /^##\s+(Decisions|Blockers|Kill register|Risk Register)\s*$/;
+const ACCEPTANCE_H2_RE = /^##\s+Acceptance Criteria\s*$/;
+
+function _isFence(line: string): boolean {
+    return /^\s*(```|~~~)/.test(line);
+}
+
+/**
+ * A scan unit: one logical statement, which is NOT one physical line.
+ *
+ * A roadmap step wraps over several lines, and the ambiguity it carries
+ * routinely straddles the wrap ("either newline-delimited JSON / or a single
+ * array"). Matching per line missed exactly those, which are the ones an
+ * author is least likely to notice. A step block is therefore ONE unit, joined
+ * and matched once — which also means one finding per step at most, so a step
+ * carrying two hedges is one open decision rather than two.
+ */
+export interface Unit {
+    /** 1-based line of the unit's first line. */
+    readonly line: number;
+    readonly text: string;
+    readonly inAcceptance: boolean;
+    readonly isOpenStep: boolean;
+    readonly hasVerify: boolean;
+}
+
+export function units(lines: readonly string[]): Unit[] {
+    const out: Unit[] = [];
+    let inFence = false;
+    let inDischarge = false;
+    let inAcceptance = false;
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i] as string;
+        if (_isFence(line)) {
+            inFence = !inFence;
+            i += 1;
+            continue;
+        }
+        if (inFence) {
+            i += 1;
+            continue;
+        }
+        if (H2_RE.test(line)) {
+            inDischarge = DISCHARGE_H2_RE.test(line);
+            inAcceptance = ACCEPTANCE_H2_RE.test(line);
+        }
+        if (inDischarge) {
+            i += 1;
+            continue;
+        }
+        if (STEP_RE.test(line)) {
+            let j = i + 1;
+            while (j < lines.length && !STEP_RE.test(lines[j] as string) && !H2_RE.test(lines[j] as string)) {
+                j += 1;
+            }
+            const block = lines.slice(i, j);
+            out.push({
+                line: i + 1,
+                // Whitespace-normalised: a wrapped step joined with a single
+                // space still carries the next line's indent, so a pattern
+                // written with single spaces stops matching across the wrap —
+                // which is the case this unit exists to catch.
+                text: block.join(' ').replace(/\s+/g, ' '),
+                inAcceptance,
+                isOpenStep: OPEN_STEP_RE.test(line),
+                hasVerify: /(?:^|\s)verify:/m.test(block.join('\n')),
+            });
+            i = j;
+            continue;
+        }
+        out.push({
+            line: i + 1,
+            text: line,
+            inAcceptance,
+            isOpenStep: false,
+            hasVerify: false,
+        });
+        i += 1;
+    }
+    return out;
+}
+
+export function scan(text: string): Finding[] {
+    const lines = text.split('\n');
+    const findings: Finding[] = [];
+
+    for (const u of units(lines)) {
+        if (/<!--\s*closure:\s*ignore\s*-->/.test(u.text)) continue;
+        let matched: Kind | null = null;
+        for (const { kind, re } of LINE_PATTERNS) {
+            if (re.test(u.text)) {
+                matched = kind;
+                break;
+            }
+        }
+        // An open step carries a `verify:` line — a step whose success cannot
+        // be checked is a trigger for a question, not for work. Acceptance
+        // criteria are criteria, not steps: they have their own contract and
+        // carry no verify line by design.
+        if (matched === null && u.isOpenStep && !u.hasVerify && !u.inAcceptance) {
+            matched = 'missing-verify';
+        }
+        if (matched === null) continue;
+        findings.push({
+            id: '',
+            line: u.line,
+            kind: matched,
+            ownership: OWNERSHIP_BY_KIND[matched],
+            excerpt: u.text.trim().replace(/\s+/g, ' ').slice(0, 120),
+        });
+    }
+
+    findings.sort((a, b) => a.line - b.line);
+    return findings.map((f, idx) => ({ ...f, id: `C${String(idx + 1)}` }));
+}
+
+/** The `## Decisions` skeleton — one row per finding, resolution left open. */
+export function renderRows(findings: readonly Finding[]): string {
+    const header = '| ID | ownership | resolved by | decision | evidence | revisit if |';
+    const sep = '|---|---|---|---|---|---|';
+    const rows = findings.map(
+        (f) => `| ${f.id} | ${f.ownership} | <resolver> | <decision> | ${f.kind}:${String(f.line)} | <condition> |`,
+    );
+    return [header, sep, ...rows].join('\n');
+}
+
+export function ownerQuestionCount(findings: readonly Finding[]): number {
+    return findings.filter((f) => OWNER_ROUTED.has(f.ownership)).length;
+}
+
+// --------------------------------------------------------------------------
+// CLI.
+// --------------------------------------------------------------------------
+
+function _usage(): string {
+    return (
+        `usage: ${_PROG} [-h] [--json] [--rows] [--strict] <roadmap.md>\n\n` +
+        `Find and classify the open decisions in a plan. Resolves nothing.\n`
+    );
+}
+
+export function main(argv?: readonly string[]): number {
+    const args = argv ?? process.argv.slice(2);
+    let json = false;
+    let rows = false;
+    let strict = false;
+    const paths: string[] = [];
+    for (const a of args) {
+        if (a === '-h' || a === '--help') {
+            process.stdout.write(_usage());
+            return 0;
+        } else if (a === '--json') json = true;
+        else if (a === '--rows') rows = true;
+        else if (a === '--strict') strict = true;
+        else if (a.startsWith('-')) {
+            process.stderr.write(`${_usage()}${_PROG}: error: unrecognized arguments: ${a}\n`);
+            return 2;
+        } else paths.push(a);
+    }
+    if (paths.length !== 1) {
+        process.stderr.write(`${_usage()}${_PROG}: error: exactly one roadmap path is required\n`);
+        return 2;
+    }
+    const target = path.resolve(paths[0] as string);
+    let text: string;
+    try {
+        text = fs.readFileSync(target, 'utf-8');
+    } catch {
+        process.stderr.write(`${_PROG}: error: cannot read ${paths[0] as string}\n`);
+        return 2;
+    }
+
+    const findings = scan(text);
+    const owner = ownerQuestionCount(findings);
+
+    if (json) {
+        process.stdout.write(
+            JSON.stringify({ findings, open: findings.length, owner_questions: owner }, null, 2) + '\n',
+        );
+    } else if (rows) {
+        process.stdout.write(renderRows(findings) + '\n');
+    } else {
+        process.stdout.write(`open decisions: ${String(findings.length)}\n`);
+        process.stdout.write(`owner questions: ${String(owner)}\n`);
+        for (const f of findings) {
+            process.stdout.write(
+                `  ${f.id}  ${String(f.line).padStart(4)}  ${f.kind.padEnd(20)} ${f.ownership.padEnd(22)} ${f.excerpt}\n`,
+            );
+        }
+    }
+    if (!findings.length) return 0;
+    return strict ? 1 : 0;
+}
+
+function _isCliEntry(): boolean {
+    if (!process.argv[1]) return false;
+    try {
+        return fs.realpathSync(_HERE) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
+    process.exitCode = main();
+}

package/src/scripts/compile_hook_manifest.ts

@@ -23,10 +23,21 @@
  * Run after editing the manifest:
  *     ./scripts-run src/scripts/compile_hook_manifest
  *
+ * `--out <path>` writes the compiled bytes THERE and leaves the tree alone. It
+ * exists for `check_generator_sync`, whose contract is that a triple regenerates
+ * into a temp dir the gate owns and never into the working tree — a gate that
+ * repaired the artefact it is measuring would turn every staleness into a silent
+ * green plus an unexplained dirty file. Anything that wants to compare against
+ * the committed JSON uses this flag; anything that wants to FIX it omits it.
+ *
  * `tests/hooks/hook_manifest_compiled.test.ts` fails if the committed JSON
- * stops matching the YAML, so a forgotten run is caught rather than shipped.
+ * stops matching the YAML, so a forgotten run is caught rather than shipped —
+ * but only against the COMMITTED blob in CI. Locally that same test reads the
+ * working tree, so a recompile that was run and never committed makes it pass
+ * over a defect that is still on the branch. See the discriminator in
+ * `check_generator_sync`'s header.
  *
- * Exit codes: 0 written (or already current) · 2 internal error.
+ * Exit codes: 0 written (or already current) · 2 internal error or usage.
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
@@ -46,9 +57,38 @@ export function compile(yamlText: string): string {
     });
 }
 
-export function main(): number {
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    let outPath: string | null = null;
+    for (let i = 0; i < argv.length; i += 1) {
+        const a = argv[i] as string;
+        if (a === '--out') {
+            const next = argv[i + 1];
+            if (next === undefined || next.startsWith('--')) {
+                process.stderr.write('compile_hook_manifest: --out needs a path\n');
+                return 2;
+            }
+            outPath = next;
+            i += 1;
+            continue;
+        }
+        process.stderr.write(
+            `compile_hook_manifest: unknown argument ${JSON.stringify(a)}\n` +
+                'usage: compile_hook_manifest [--out <path>]\n',
+        );
+        return 2;
+    }
+
     const text = fs.readFileSync(YAML_PATH, 'utf-8');
     const next = compile(text);
+
+    if (outPath !== null) {
+        // Comparison copy. No `already current` short-circuit: the caller asked
+        // for the bytes, and an unwritten file would read as a generator that
+        // silently did nothing.
+        fs.writeFileSync(outPath, next);
+        return 0;
+    }
+
     const current = fs.existsSync(JSON_PATH) ? fs.readFileSync(JSON_PATH, 'utf-8') : null;
     if (current === next) {
         process.stdout.write('compile_hook_manifest: already current\n');