@event4u/agent-config 16.1.0 → 16.3.0

package/src/scripts/check_kill_switch_table.ts

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+/**
+ * The kill-switch table says what it counts — this checks that it still does.
+ *
+ * `docs/contracts/hook-architecture-v1.md` § Kill switches enumerates every
+ * `AGENT_CONFIG_*` identifier a file under `src/scripts/hooks/` or
+ * `src/scripts/_lib/` carries, and publishes the command that reproduces the
+ * count. An equality between a hand-written table and a grep over a growing
+ * tree is exactly the claim that decays without anybody touching the document:
+ * the table shipped at 28 == 28 and was stale within a day, because a merge
+ * brought in one hook carrying one new switch. Found by an independent review,
+ * which is a worse way to find it than a gate.
+ *
+ * WHAT IS CHECKED, and it is the equality itself rather than a proxy for it:
+ * the gate runs the published enumeration and compares the SET against the
+ * table's rows. A set comparison rather than a count, because two errors that
+ * cancel — one switch added, one row for a deleted switch left behind — is the
+ * failure a count cannot see, and it is the one that leaves a reader chasing a
+ * variable nothing reads.
+ *
+ * WHAT IS DELIBERATELY NOT CHECKED: the owner class, and the prose of each row.
+ * Whether a switch is `maintainer` or `harness` is a judgement about who is
+ * expected to set it, and a gate that guessed at it would either be wrong or
+ * would have to encode the judgement somewhere else — which is the table.
+ *
+ * THE TWO EXCLUSIONS ARE PART OF THE CONTRACT, not a convenience.
+ * `__AGENT_CONFIG_BUNDLE__` and `__AGENT_CONFIG_CLI_DELEGATE__` are esbuild
+ * `--define` identifiers (see `package.json`'s `build:*` scripts): nothing can
+ * set one at runtime, so neither is a switch. They are excluded on the emitted
+ * token, because `grep -o` strips the leading underscores and the naive
+ * `grep -v __AGENT_CONFIG_BUNDLE__` therefore matches nothing.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { GateLedger } from './_lib/gate_ledger.js';
+import { runGateCli, runSelfTest, type SelfTestCase } from './_lib/gate_self_test.js';
+import { assertScanned, reportScanned } from './_lib/scan_scope.js';
+
+const GATE = 'check_kill_switch_table';
+const CONTRACT = path.join('docs', 'contracts', 'hook-architecture-v1.md');
+const SECTION = '## Kill switches';
+const ROOTS = [path.join('src', 'scripts', 'hooks'), path.join('src', 'scripts', '_lib')];
+
+/** The esbuild defines. Not environment variables, so not switches. */
+const BUILD_DEFINES: ReadonlySet<string> = new Set([
+    'AGENT_CONFIG_BUNDLE__',
+    'AGENT_CONFIG_CLI_DELEGATE__',
+]);
+
+const TOKEN = /AGENT_CONFIG_[A-Z_]+/g;
+/** A table row: `| \`AGENT_CONFIG_X\` | owner | … |`. */
+const ROW = /^\|\s*`(AGENT_CONFIG_[A-Z_]+)`\s*\|/gm;
+
+function walk(dir: string, out: string[]): void {
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+        return;
+    }
+    for (const e of entries) {
+        const full = path.join(dir, e.name);
+        if (e.isDirectory()) {
+            walk(full, out);
+        } else if (e.isFile()) {
+            out.push(full);
+        }
+    }
+}
+
+/** Every switch name the declared roots carry, minus the build defines. */
+export function switchesInTree(root: string): { names: Set<string>; files: number } {
+    const files: string[] = [];
+    for (const rel of ROOTS) {
+        walk(path.join(root, rel), files);
+    }
+    const names = new Set<string>();
+    for (const f of files) {
+        let text: string;
+        try {
+            text = fs.readFileSync(f, 'utf-8');
+        } catch {
+            continue;
+        }
+        for (const m of text.matchAll(TOKEN)) {
+            const name = m[0];
+            if (!BUILD_DEFINES.has(name)) names.add(name);
+        }
+    }
+    return { names, files: files.length };
+}
+
+/** Every switch the contract's table has a row for. */
+export function switchesInTable(root: string): { names: Set<string>; present: boolean } {
+    let text: string;
+    try {
+        text = fs.readFileSync(path.join(root, CONTRACT), 'utf-8');
+    } catch {
+        return { names: new Set(), present: false };
+    }
+    const at = text.indexOf(SECTION);
+    if (at === -1) return { names: new Set(), present: false };
+    const rest = text.slice(at + SECTION.length);
+    const end = rest.indexOf('\n## ');
+    const section = end === -1 ? rest : rest.slice(0, end);
+    const names = new Set<string>();
+    for (const m of section.matchAll(ROW)) {
+        const n = m[1];
+        if (n !== undefined) names.add(n);
+    }
+    return { names, present: true };
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    if (argv.includes('--self-test')) return selfTest();
+
+    const root = process.cwd();
+    const ledger = new GateLedger(GATE);
+    ledger.plan(['tree-enumeration', 'table-rows', 'set-equality']);
+
+    const tree = switchesInTree(root);
+    const scope = {
+        gate: GATE,
+        scanned: tree.files,
+        units: 'source file(s)',
+        roots: ROOTS,
+    };
+    // BEFORE the verdict, per the empty-corpus contract: a run that read no
+    // source file must refuse rather than report an empty tree as agreement
+    // with an empty table.
+    assertScanned(scope);
+    reportScanned(scope);
+    ledger.complete('tree-enumeration');
+
+    const table = switchesInTable(root);
+    if (!table.present) {
+        ledger.fail('table-rows', `no "${SECTION}" section in ${CONTRACT}`);
+        ledger.fail('set-equality', 'nothing to compare against');
+        ledger.report();
+        process.stderr.write(
+            `❌  ${GATE}: ${CONTRACT} carries no "${SECTION}" section. The section is the\n` +
+                '    contract; a tree enumeration with nothing to compare it against is not a pass.\n',
+        );
+        return 1;
+    }
+    ledger.complete('table-rows');
+
+    const missing = [...tree.names].filter((n) => !table.names.has(n)).sort();
+    const extra = [...table.names].filter((n) => !tree.names.has(n)).sort();
+
+    if (missing.length === 0 && extra.length === 0) {
+        ledger.complete('set-equality');
+        ledger.report();
+        process.stdout.write(
+            `✅  ${GATE}: ${String(tree.names.size)} switch(es) in ` +
+                `${String(tree.files)} file(s), ${String(table.names.size)} table row(s), sets equal\n`,
+        );
+        return 0;
+    }
+
+    ledger.fail('set-equality', `${String(missing.length + extra.length)} mismatch(es)`);
+    ledger.report();
+    process.stderr.write(`❌  ${GATE}: the table and the tree disagree.\n\n`);
+    for (const n of missing) {
+        process.stderr.write(`  MISSING ROW  ${n} — read by the tree, absent from the table\n`);
+    }
+    for (const n of extra) {
+        process.stderr.write(
+            `  STALE ROW    ${n} — a table row for a name the tree no longer carries\n`,
+        );
+    }
+    process.stderr.write(
+        `\nAdd or remove the row in ${CONTRACT} § Kill switches. A switch with no row is\n` +
+            'one an operator cannot find; a row with no switch is one they will set expecting\n' +
+            'an effect. If a name is genuinely read outside the two declared roots, the row\n' +
+            'stays and says so — the row still has to exist.\n',
+    );
+    return 1;
+}
+
+// ---------------------------------------------------------------------------
+// Self-test — the gate proving its own rejections still fire
+// ---------------------------------------------------------------------------
+
+function fixture(body: { tree: string; table: string }): string {
+    const dir = fs.mkdtempSync(path.join(process.cwd(), '.kst-'));
+    fs.mkdirSync(path.join(dir, 'src', 'scripts', 'hooks'), { recursive: true });
+    fs.mkdirSync(path.join(dir, 'src', 'scripts', '_lib'), { recursive: true });
+    fs.mkdirSync(path.join(dir, 'docs', 'contracts'), { recursive: true });
+    fs.writeFileSync(path.join(dir, 'src', 'scripts', 'hooks', 'a.ts'), body.tree, 'utf-8');
+    fs.writeFileSync(path.join(dir, CONTRACT), body.table, 'utf-8');
+    return dir;
+}
+
+function table(...names: string[]): string {
+    const rows = names.map((n) => `| \`${n}\` | maintainer | does a thing | a.ts:1 |`).join('\n');
+    return `# Contract\n\n${SECTION}\n\n| Switch | Owner | What | Read at |\n|---|---|---|---|\n${rows}\n\n## Stability\n\nBeta.\n`;
+}
+
+function selfTest(): number {
+    const repoRoot = process.cwd();
+    const script = path.join('src', 'scripts', 'check_kill_switch_table.ts');
+    const dirs: string[] = [];
+    const run = (body: { tree: string; table: string }): number => {
+        const dir = fixture(body);
+        dirs.push(dir);
+        return runGateCli(repoRoot, script, [], dir);
+    };
+
+    const cases: SelfTestCase[] = [
+        {
+            name: 'equal sets pass',
+            expect: 'accept',
+            run: () =>
+                run({
+                    tree: "const A = process.env['AGENT_CONFIG_ALPHA'];\n",
+                    table: table('AGENT_CONFIG_ALPHA'),
+                }),
+        },
+        {
+            name: 'a switch with no row is rejected',
+            expect: 'reject',
+            run: () =>
+                run({
+                    tree: "const A = process.env['AGENT_CONFIG_ALPHA'];\nconst B = process.env['AGENT_CONFIG_BETA'];\n",
+                    table: table('AGENT_CONFIG_ALPHA'),
+                }),
+        },
+        {
+            name: 'a row with no switch is rejected',
+            expect: 'reject',
+            run: () =>
+                run({
+                    tree: "const A = process.env['AGENT_CONFIG_ALPHA'];\n",
+                    table: table('AGENT_CONFIG_ALPHA', 'AGENT_CONFIG_GONE'),
+                }),
+        },
+        {
+            name: 'one added and one stale do NOT cancel — the count would hide it',
+            expect: 'reject',
+            run: () =>
+                run({
+                    tree: "const B = process.env['AGENT_CONFIG_BETA'];\n",
+                    table: table('AGENT_CONFIG_ALPHA'),
+                }),
+        },
+        {
+            name: 'the esbuild defines are excluded, not counted',
+            expect: 'accept',
+            run: () =>
+                run({
+                    tree:
+                        'declare const __AGENT_CONFIG_BUNDLE__: boolean;\n'
+                        + 'declare const __AGENT_CONFIG_CLI_DELEGATE__: boolean;\n'
+                        + "const A = process.env['AGENT_CONFIG_ALPHA'];\n",
+                    table: table('AGENT_CONFIG_ALPHA'),
+                }),
+        },
+        {
+            name: 'a missing section is rejected, never read as an empty table',
+            expect: 'reject',
+            run: () =>
+                run({
+                    tree: "const A = process.env['AGENT_CONFIG_ALPHA'];\n",
+                    table: '# Contract\n\n## Stability\n\nBeta.\n',
+                }),
+        },
+    ];
+
+    try {
+        return runSelfTest({ gate: GATE, cases, minCases: 6, minRejectCases: 4 });
+    } finally {
+        for (const d of dirs) fs.rmSync(d, { recursive: true, force: true });
+    }
+}
+
+function isCliEntry(): boolean {
+    const argv1 = process.argv[1];
+    if (argv1 === undefined) return false;
+    try {
+        return (
+            fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(argv1))
+        );
+    } catch {
+        return pathToFileURL(argv1).href === import.meta.url;
+    }
+}
+
+if (isCliEntry()) {
+    process.exit(main());
+}

package/src/scripts/check_memory.ts

@@ -607,7 +607,13 @@ function _checkAppendOnly(base: string | null, findings: Finding[]): void {
         '--no-color',
         ref,
         '--',
-        'agents/memory/intake/',
+        // The JSONL drops, not the directory. `INTAKE_GLOB`, this module's
+        // docstring and every fixture in the suite all scope this check to
+        // `*.jsonl`; asking git for the directory made it govern the tracked
+        // skeleton too, so editing the README that documents the append-only
+        // rule was reported as a violation of it. `:(glob)` is explicit rather
+        // than relying on the default pathspec magic.
+        ':(glob)agents/memory/intake/*.jsonl',
     ]);
     if (rc !== 0) {
         findings.push(new Finding(INTAKE_GLOB, 0, 'warning', `append-only: git diff failed vs ${ref}`));

package/src/scripts/check_placeholder_drift.ts

@@ -0,0 +1,221 @@
+#!/usr/bin/env tsx
+/**
+ * The placeholder-drift ratchet — foreign placeholder syntaxes in prose may
+ * shrink, never grow.
+ *
+ * road-to-an-invocation-contract-that-reaches-the-wire 1.2.
+ *
+ * WHAT IT GATES, AND WHAT IT DELIBERATELY DOES NOT
+ *
+ * It fails on GROWTH of the foreign forms only. It never fails on the absolute
+ * number, and it never fails on the plurality form — so holding at the seeded
+ * counts is permanently green, and nothing here asks for a rewrite of a working
+ * body. That is the whole of Risk 2's mitigation: a committed number naming two
+ * syntaxes as foreign reads like a canon ruling whose obvious next move is
+ * rewriting those bodies, and a gate that is green at the seed removes the
+ * pressure to do it.
+ *
+ * THE SEED IS MEASURED, NOT COPIED
+ *
+ * The roadmap's step text says "seeded at the measured 4 and 2". The operative
+ * word is MEASURED: under the census's published unit — a token in PROSE,
+ * outside fenced blocks, indented blocks and inline code spans — the corpus
+ * carries different numbers, because the source figures counted tokens inside
+ * demonstrated code (JS template literals in `playwright-testing`, HCL in
+ * `terragrunt`, a table-cell marker the prose is talking ABOUT in
+ * `livewire-architect`). The seed below is this tree's own reading. The
+ * reasoning lives in `report_invocation_surface.ts`'s module header, and the
+ * per-file breakdown is in the census artifact, so the definition is arguable
+ * rather than merely asserted.
+ *
+ * A NOTE ON WHAT A ZERO SEED MEANS. `{{…}}` seeds at zero. That is not "the
+ * check has nothing to do" — a zero-seeded ratchet is the strictest form of
+ * this gate, because the first occurrence is growth. It is also the cheapest
+ * possible moment to hold a line: no existing body has to change for it.
+ *
+ * Exit codes: 0 within the ratchet · 1 growth · 2 the corpus could not be read.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { GateLedger } from './_lib/gate_ledger.js';
+import { runGateCli, runSelfTest } from './_lib/gate_self_test.js';
+import { assertScanned, reportScanned } from './_lib/scan_scope.js';
+import { SYNTAXES, type SyntaxId, census } from './report_invocation_surface.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+export const GATE = 'check_placeholder_drift';
+
+/** Where the seed lives, so a deliberate change is a reviewable diff. */
+export const BUDGET_REL = path.join('src', 'config', 'placeholder-drift-budget.json');
+
+export interface Budget {
+    readonly seeded_at: string;
+    readonly note: string;
+    readonly ceilings: Readonly<Partial<Record<SyntaxId, number>>>;
+}
+
+export function readBudget(root: string): Budget | null {
+    const p = path.join(root, BUDGET_REL);
+    if (!fs.existsSync(p)) return null;
+    try {
+        return JSON.parse(fs.readFileSync(p, 'utf8')) as Budget;
+    } catch {
+        return null;
+    }
+}
+
+export interface Finding {
+    readonly syntax: SyntaxId;
+    readonly ceiling: number;
+    readonly measured: number;
+}
+
+/** Which foreign syntaxes exceed their ceiling. Plurality forms are skipped. */
+export function findings(
+    occurrences: Readonly<Record<SyntaxId, number>>,
+    budget: Budget,
+): Finding[] {
+    const out: Finding[] = [];
+    for (const s of SYNTAXES) {
+        if (s.canonical) continue;
+        const ceiling = budget.ceilings[s.id];
+        if (ceiling === undefined) continue;
+        const measured = occurrences[s.id] ?? 0;
+        if (measured > ceiling) out.push({ syntax: s.id, ceiling, measured });
+    }
+    return out;
+}
+
+export function main(argv: readonly string[]): number {
+    if (argv.includes('--self-test')) return selfTest();
+    const rootIdx = argv.indexOf('--root');
+    const root = rootIdx === -1 ? ROOT : (argv[rootIdx + 1] ?? ROOT);
+
+    const budget = readBudget(root);
+    if (budget === null) {
+        process.stderr.write(
+            `❌  ${GATE}: ${BUDGET_REL} is missing or unreadable. A ratchet that cannot read ` +
+                'its own seed must not pass — it would be a green nobody earned.\n',
+        );
+        return 2;
+    }
+
+    const c = census(root);
+    const foreign = SYNTAXES.filter((s) => !s.canonical);
+    const ledger = new GateLedger(GATE);
+    ledger.plan(foreign.map((s) => s.id));
+
+    const found = findings(c.occurrences, budget);
+    for (const s of foreign) {
+        const f = found.find((x) => x.syntax === s.id);
+        if (f === undefined) ledger.complete(s.id);
+        else ledger.fail(s.id, `${String(f.measured)} occurrence(s) against a ceiling of ${String(f.ceiling)}`);
+    }
+
+    // A gate that read nothing has not passed. This fires BEFORE the verdict,
+    // because certifying against an empty corpus is the false green the coverage
+    // manifest exists to refuse — named by the provider-diverse ratification
+    // review as one condition that would have flipped its verdict.
+    assertScanned({ gate: GATE, scanned: c.rows.length, units: 'artifact(s)', roots: [BUDGET_REL, 'dist/agent-src/commands', 'src/skills'] });
+
+    reportScanned({
+        gate: GATE,
+        scanned: c.rows.length,
+        units: 'artifact(s)',
+        roots: [BUDGET_REL],
+    });
+    ledger.report();
+
+    if (found.length > 0) {
+        for (const f of found) {
+            const label = SYNTAXES.find((s) => s.id === f.syntax)?.label ?? f.syntax;
+            process.stdout.write(
+                `❌  ${GATE}: \`${label}\` grew to ${String(f.measured)} prose occurrence(s), ceiling ${String(f.ceiling)}.\n`,
+            );
+        }
+        process.stdout.write(
+            '\nThe ratchet walks DOWN only. Use the plurality form instead, or — if the new ' +
+                `occurrence is genuinely right — lower nothing and raise the ceiling in ` +
+                `\`${BUDGET_REL}\` in the same change, with the reason in the diff.\n` +
+                'Counting unit and the per-file breakdown: ' +
+                '`./scripts-run src/scripts/report_invocation_surface --write`.\n',
+        );
+        return 1;
+    }
+
+    process.stdout.write(
+        `✅  ${GATE}: foreign placeholder syntaxes within their ratchet ` +
+            `(${foreign.map((s) => `${s.label} ${String(c.occurrences[s.id])}/${String(budget.ceilings[s.id] ?? 0)}`).join(' · ')}).\n`,
+    );
+    return 0;
+}
+
+/**
+ * A ratchet that cannot be shown to move is a number, not a gate. Each rejecting
+ * case is one occurrence over a ceiling; the accepting cases are the seed itself
+ * and a shrink, because a suite that only proves failures proves a gate that is
+ * merely loud.
+ */
+function selfTest(): number {
+    const plant = (name: string, bodies: readonly string[], ceilings: Record<string, number>): string => {
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), `drift-${name}-`));
+        fs.mkdirSync(path.join(dir, 'src', 'config'), { recursive: true });
+        fs.writeFileSync(
+            path.join(dir, 'src', 'config', 'placeholder-drift-budget.json'),
+            JSON.stringify({ seeded_at: '2026-09-29', note: 'fixture', ceilings }, null, 2),
+            'utf-8',
+        );
+        bodies.forEach((body, i) => {
+            const d = path.join(dir, 'src', 'skills', `probe-${String(i)}`);
+            fs.mkdirSync(d, { recursive: true });
+            fs.writeFileSync(path.join(d, 'SKILL.md'), `---\nname: probe-${String(i)}\n---\n\n${body}\n`, 'utf-8');
+        });
+        return dir;
+    };
+    const run = (root: string): number =>
+        runGateCli(ROOT, path.join('src', 'scripts', 'check_placeholder_drift.ts'), ['--root', root], ROOT);
+
+    return runSelfTest({
+        gate: GATE,
+        minCases: 5,
+        minRejectCases: 3,
+        cases: [
+            {
+                name: 'at the seed it is green',
+                expect: 'accept',
+                run: () => run(plant('seed', ['Uses {{a}} once.'], { 'double-brace': 1, 'angle-upper': 0 })),
+            },
+            {
+                name: 'below the seed it stays green — it never fails on the absolute number',
+                expect: 'accept',
+                run: () => run(plant('shrink', ['no placeholders'], { 'double-brace': 1, 'angle-upper': 0 })),
+            },
+            {
+                name: 'one occurrence over the ceiling fails',
+                expect: 'reject',
+                run: () => run(plant('grow', ['Uses {{a}} and {{b}}.'], { 'double-brace': 1, 'angle-upper': 0 })),
+            },
+            {
+                name: 'a zero ceiling makes the first occurrence growth',
+                expect: 'reject',
+                run: () => run(plant('zero', ['Uses <NAME> here.'], { 'double-brace': 0, 'angle-upper': 0 })),
+            },
+            {
+                name: 'an unreadable budget refuses rather than certifying a green',
+                expect: 'reject',
+                run: () => runGateCli(ROOT, path.join('src', 'scripts', 'check_placeholder_drift.ts'),
+                    ['--root', fs.mkdtempSync(path.join(os.tmpdir(), 'drift-nobudget-'))], ROOT),
+            },
+        ],
+    });
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+    process.exit(main(process.argv.slice(2)));
+}