@event4u/agent-config 14.7.0 → 14.9.0

package/src/scripts/check_no_stub_inventory_table.ts

@@ -0,0 +1,292 @@
+#!/usr/bin/env tsx
+/**
+ * Stub-inventory-table guard.
+ *
+ * `agents/roadmaps/stubs/README.md` carried a hand-maintained index of the stub
+ * files sitting beside it: two tables, 6 demand-gated rows and 27 transfer rows,
+ * appended by hand by every roadmap-transfer session. It was the largest
+ * *authored* merge-conflict path in the repository — everything above it in the
+ * ranking is generated — and every row duplicated facts already in the stub it
+ * pointed at. `3793855b3` deleted it on 2026-08-21, after the AI council chose
+ * deletion over building a generator (both seats) and after all 33 rows were
+ * checked cell by cell against their stub file.
+ *
+ * It came back on 2026-08-22. A merge (`28ba2f592`, PR #1505) reintroduced a
+ * 12-row version; both parents of that merge lacked the table, so it was not a
+ * mis-resolved `modify/delete` but a deliberate restore — taken against a note
+ * in `agents/evidence/notes/drain-run-handoff.md` written in the same change as
+ * the deletion for the express purpose of preventing one. Three further rows
+ * were then appended by later sessions.
+ *
+ * That is the whole reason this gate exists rather than another paragraph: the
+ * paragraph was tried, and it lost to a merge. Prose cannot refuse.
+ *
+ * WHAT IT REJECTS — the structure, never "tables"
+ * ----------------------------------------------
+ * Two signatures, both keyed to an inventory of the guarded file's own
+ * directory:
+ *
+ *   1. a table header row whose first cell is `Stub` — the header both
+ *      historical tables used (`| Stub | Transferred from | … |` and
+ *      `| Stub | Triggers org-mode surface | Gates |`);
+ *   2. a table body row whose FIRST cell links to a `.md` file in the SAME
+ *      directory — an inventory row by construction.
+ *
+ * A `../`-prefixed or otherwise pathed link does not match: a prose table that
+ * cites parent roadmaps is not an index of this directory. A future two-column
+ * glossary, a decision matrix, or any table that does not enumerate the
+ * neighbouring stubs is unaffected. This narrowness is deliberate and was asked
+ * for by review: a blanket ban on markdown tables in the file would block
+ * legitimate documentation to stop one specific regression.
+ *
+ * WHY A WATCH LIST AND NOT A TREE WALK
+ * ------------------------------------
+ * The guarded set is one known file, so there is no corpus to count, and a
+ * one-path guard is exactly the shape that rots into a permanent pass when the
+ * path moves — `check_safety_floor_untouched` announced "4 rules guarded" while
+ * guarding none for months. `assertWatchlistResolves` refuses to report clean when its
+ * targets do not resolve, so a rename reds this gate instead of retiring it
+ * silently.
+ *
+ * Exit codes: 0 clean · 1 findings or a dead watch list.
+ */
+// ledger-exempt: the scope is ONE watch-list file, not a collected population — there is
+// no per-target accounting to publish, and the empty path is already refused by
+// assertWatchlistResolves rather than skipped. Same shape as check_branch_freshness.
+
+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 { runGateCli, runSelfTest, type SelfTestCase } from './_lib/gate_self_test.js';
+import { assertWatchlistResolves, DeadScopeError, reportScanned } from './_lib/scan_scope.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+export const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+/**
+ * Self-test floors. Below these, `--self-test` fails instead of printing success —
+ * deleting cases would otherwise be the cheapest route to a green self-test.
+ */
+const SELF_TEST_MIN_CASES = 5;
+const SELF_TEST_MIN_REJECT = 3;
+
+/** This script's repo-relative path, for the self-test's CLI invocations. */
+const SELF = 'src/scripts/check_no_stub_inventory_table.ts';
+
+/** Files whose inventory tables are banned. Repo-relative. */
+export const GUARDED: readonly string[] = ['agents/roadmaps/stubs/README.md'];
+
+/**
+ * A header row that opens with the literal `Stub` column.
+ *
+ * Both deleted tables used it, and it is not a phrase a prose table reaches for
+ * by accident: a first cell of exactly `Stub` announces a per-stub listing.
+ */
+const INVENTORY_HEADER = /^\|\s*Stub\s*\|/;
+
+/**
+ * A body row whose first cell links to a `.md` file in the same directory.
+ *
+ * `[^)/]*` is the load-bearing part: it excludes `../road-to-x.md` and any other
+ * pathed target, so only a link to a sibling of the guarded file matches. That
+ * is what makes this an inventory signature rather than a link count.
+ */
+const INVENTORY_ROW = /^\|\s*\[`?[^\]]*`?\]\([^)/]*\.md\)/;
+
+export interface Finding {
+    readonly file: string;
+    readonly line: number;
+    readonly kind: 'inventory-header' | 'inventory-row';
+    readonly text: string;
+}
+
+export function scan_file(rel: string, text: string): Finding[] {
+    const findings: Finding[] = [];
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i]!;
+        if (INVENTORY_HEADER.test(line)) {
+            findings.push({ file: rel, line: i + 1, kind: 'inventory-header', text: line.trim() });
+        } else if (INVENTORY_ROW.test(line)) {
+            findings.push({ file: rel, line: i + 1, kind: 'inventory-row', text: line.trim() });
+        }
+    }
+    return findings;
+}
+
+/**
+ * Read `--root <path>` / `--root=<path>` out of argv.
+ *
+ * Parsed by NAME, never by position. `lint_handoffs` took `args[0]` as its scan
+ * root, and the Taskfile injects `--quiet` first — so the flag became the root,
+ * the scan found nothing, and the gate was red under the argv CI runs while
+ * green under a bare probe. A named flag cannot make that mistake.
+ */
+export function parseRoot(argv: readonly string[], fallback: string): string {
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i]!;
+        if (a.startsWith('--root=')) return path.resolve(a.slice('--root='.length));
+        if (a === '--root' && argv[i + 1] !== undefined) return path.resolve(argv[i + 1]!);
+    }
+    return fallback;
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2), root?: string): number {
+    const QUIET = argv.includes('--quiet');
+    root = root ?? parseRoot(argv, ROOT);
+    let present: readonly string[];
+    try {
+        present = assertWatchlistResolves({
+            gate: 'check_no_stub_inventory_table',
+            candidates: GUARDED,
+            repoRoot: root,
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stdout.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
+    const findings: Finding[] = [];
+    for (const rel of present) {
+        findings.push(...scan_file(rel, fs.readFileSync(path.join(root, rel), 'utf-8')));
+    }
+
+    // Outside the --quiet guard on purpose: CI passes --quiet, and a gate whose
+    // count disappears under the real argv reads as `silent` to the coverage guard.
+    reportScanned({
+        gate: 'check_no_stub_inventory_table',
+        scanned: present.length,
+        units: 'guarded file(s)',
+        roots: GUARDED,
+    });
+
+    if (findings.length === 0) {
+        if (!QUIET) process.stdout.write('✅  No stub-inventory table in the guarded file(s).\n');
+        return 0;
+    }
+
+    process.stdout.write(
+        `❌  Stub-inventory table reintroduced — ${String(findings.length)} row(s):\n`,
+    );
+    for (const f of findings) {
+        process.stdout.write(`    ${f.file}:${String(f.line)}: ${f.kind} — ${f.text.slice(0, 100)}\n`);
+    }
+    process.stdout.write(
+        '\nThe stub files ARE the inventory; `ls agents/roadmaps/stubs/*.md` lists them.\n' +
+            'If you reached this while resolving a merge conflict, the resolution\n' +
+            'WITHOUT a table is the correct one — the table was deleted deliberately\n' +
+            '(3793855b3, AI council 2026-08-21) and restored once by a merge already.\n' +
+            'If you need a per-stub fact, it is in that stub; all 33 rows were verified\n' +
+            'against their stub file before deletion and all 15 again before the second.\n',
+    );
+    return 1;
+}
+
+/**
+ * Build a fixture repository holding one guarded file with `body`, or none at all
+ * when `body` is null (the dead-watch-list case).
+ */
+function _fixture(body: string | null): string {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'stub-inv-self-'));
+    if (body !== null) {
+        const target = path.join(dir, GUARDED[0]!);
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, body);
+    }
+    return dir;
+}
+
+/**
+ * Prove the gate's rejections still fire, through the CLI a contributor runs.
+ *
+ * The three rejecting cases are the sabotage probes this gate was verified with
+ * by hand before it landed; keeping them here is what stops the verification
+ * from being a one-time claim in a commit message.
+ */
+export function selfTest(): number {
+    const cases: SelfTestCase[] = [
+        {
+            name: 'rejects a restored transfer table (header + rows)',
+            expect: 'reject',
+            run: () =>
+                runGateCli(
+                    ROOT,
+                    SELF,
+                    ['--quiet', '--root', _fixture(
+                        '| Stub | Transferred from |\n|---|---|\n' +
+                            '| [`road-to-a.md`](road-to-a.md) | p |\n',
+                    )],
+                    ROOT,
+                ),
+        },
+        {
+            name: 'rejects the inventory header on its own',
+            expect: 'reject',
+            run: () => runGateCli(ROOT, SELF, ['--quiet', '--root', _fixture('| Stub | Gates |\n')], ROOT),
+        },
+        {
+            name: 'rejects a dead watch list rather than reporting clean',
+            expect: 'reject',
+            run: () => runGateCli(ROOT, SELF, ['--quiet', '--root', _fixture(null)], ROOT),
+        },
+        {
+            name: 'accepts a guarded file with no inventory table',
+            expect: 'accept',
+            run: () =>
+                runGateCli(
+                    ROOT,
+                    SELF,
+                    ['--quiet', '--root', _fixture('# Stubs\n\nThe directory is the index.\n')],
+                    ROOT,
+                ),
+        },
+        {
+            name: 'accepts a glossary table and a table citing parent roadmaps',
+            expect: 'accept',
+            run: () =>
+                runGateCli(
+                    ROOT,
+                    SELF,
+                    ['--quiet', '--root', _fixture(
+                        '| Term | Meaning |\n|---|---|\n| capability-gated | env missing |\n\n' +
+                            '| Parent | Phase |\n|---|---|\n' +
+                            '| [`road-to-x.md`](../archive/road-to-x.md) | 2.1 |\n',
+                    )],
+                    ROOT,
+                ),
+        },
+    ];
+    return runSelfTest({
+        gate: 'check_no_stub_inventory_table',
+        cases,
+        minCases: SELF_TEST_MIN_CASES,
+        minRejectCases: SELF_TEST_MIN_REJECT,
+    });
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) return true;
+    try {
+        return (
+            fs.realpathSync(fileURLToPath(import.meta.url)) ===
+            fs.realpathSync(path.resolve(process.argv[1]))
+        );
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
+    const argv = process.argv.slice(2);
+    if (argv.includes('--self-test') && process.env['GATE_SELF_TEST_CHILD'] !== '1') {
+        process.exit(selfTest());
+    }
+    process.exit(main(argv));
+}

package/src/scripts/check_pack_size.ts

@@ -28,6 +28,7 @@ import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+import { runSelfTest } from './_lib/gate_self_test.js';
 
 const REPO_ROOT = path.resolve(fileURLToPath(import.meta.url), '..', '..', '..');
 const BUDGET_PATH = path.join(REPO_ROOT, 'src', 'config', 'pack-size-budget.json');
@@ -98,6 +99,126 @@ export function skillBytes(files: readonly PackFile[]): { perSkill: Record<strin
 }
 
 /** Every violation, as human-readable lines. Empty array means green. */
+/**
+ * Content classes the published payload is checked for.
+ *
+ * The gap this closes: before it, the tarball was measured by SIZE and by build
+ * correctness, and by nothing that read what the files ARE. A payload can be
+ * comfortably under budget and still ship compiled tests, an IDE directory, or
+ * a credential-shaped file.
+ *
+ * `limit: 0` is a hard class — nothing of that shape may ship. A positive limit
+ * is a RATCHET: the number was measured, not chosen, and it may only walk down.
+ * The distinction is in `measured_in`, which every entry carries, because the
+ * same `npm pack` reports a fifth of the source maps in an unbuilt worktree as
+ * in a built one. A threshold with no stated tree reads as drift the first time
+ * someone runs it from a fresh checkout.
+ */
+interface ContentClass {
+    id: string;
+    /** Matches a payload path. */
+    match: (p: string) => boolean;
+    /** 0 = must not ship at all. > 0 = shrink-only ratchet. */
+    limit: number;
+    /** Which tree the limit was measured in, and when. */
+    measured_in: string;
+    /**
+     * True when the class only exists in a BUILT tree.
+     *
+     * This is the difference between a check and a false pass. `npm pack
+     * --dry-run --ignore-scripts` on a clean checkout — which is the condition
+     * `pack-size-budget.json` declares for its own numbers — produces no
+     * `dist/cli/**` at all, so a source-map count of 22 sails under a limit of
+     * 120 while measuring a fifth of the payload. Reported NOT MEASURABLE
+     * instead, on the same principle as the dead-scope assertion above: a check
+     * that could not run is not a clean bill.
+     */
+    requires_build: boolean;
+    why: string;
+}
+
+/**
+ * Was this payload produced from a built tree?
+ *
+ * Keyed on the payload itself rather than on the filesystem, so it describes
+ * the thing being judged instead of the machine judging it.
+ */
+function payloadIsBuilt(files: readonly PackFile[]): boolean {
+    return files.some((f) => f.path.startsWith('dist/cli/'));
+}
+
+const CONTENT_CLASSES: readonly ContentClass[] = [
+    {
+        id: 'compiled-test-artefact',
+        requires_build: true,
+        match: (p) => /\.(test|spec)\.(js|js\.map|d\.ts)$/.test(p),
+        limit: 0,
+        measured_in: 'built main checkout, 2026-08-22: 8 `.test.js` + 8 `.test.js.map` were shipping before the `files[]` negations landed',
+        why: "a compiled test's output has no consumer-facing purpose; council 2026-08-22 decision (b') strips BOTH the JS and its map, because stripping only the maps left the compiled tests themselves in the tarball",
+    },
+    {
+        id: 'credential-shaped',
+        requires_build: false,
+        match: (p) => /(^|\/)\.env(\.|$)|\.pem$|(^|\/)id_(rsa|ed25519)$|\.p12$|\.pfx$/.test(p),
+        limit: 0,
+        measured_in: 'built main checkout, 2026-08-22: 0 present',
+        why: 'a clean class with no check is indistinguishable from a class nobody looked at — and this one is worth a canary precisely because it is empty today',
+    },
+    {
+        id: 'ide-metadata',
+        requires_build: false,
+        match: (p) => /(^|\/)\.(idea|vscode)\//.test(p),
+        limit: 0,
+        measured_in: 'built main checkout, 2026-08-22: 0 present',
+        why: 'same reason as the credential class: empty and unchecked is not the same as empty and verified',
+    },
+    {
+        id: 'source-map',
+        requires_build: true,
+        match: (p) => p.endsWith('.js.map'),
+        limit: 120,
+        measured_in: 'built worktree, 2026-08-22, AFTER the compiled-test negations: 120 product maps (128 total minus 8 test maps)',
+        why: "a product source map is a consumer debugging affordance — proper line mapping and stepping over shipped JS — so council 2026-08-22 kept the 119/120 product maps and refused a blanket zero. Recorded as a PROVISIONAL measured ratchet, not an architectural constant: nothing here establishes that any consumer debugs the shipped JS, and nothing establishes they do not",
+    },
+];
+
+/**
+ * Count each content class in the payload and report over-limit classes.
+ *
+ * Returns one error string per violating class, with the offending paths — the
+ * count alone tells a reader a rule broke and not which file broke it.
+ */
+export function classifyPayload(files: readonly PackFile[]): string[] {
+    const out: string[] = [];
+    const built = payloadIsBuilt(files);
+    for (const c of CONTENT_CLASSES) {
+        if (c.requires_build && !built) continue;
+        const hits = files.filter((f) => c.match(f.path)).map((f) => f.path);
+        if (hits.length <= c.limit) continue;
+        const shown = hits.slice(0, 8);
+        out.push(
+            `content class \`${c.id}\`: ${String(hits.length)} entr${hits.length === 1 ? 'y' : 'ies'} ` +
+                `exceeds its limit of ${String(c.limit)} (measured in: ${c.measured_in}) — ` +
+                `${shown.join(', ')}${hits.length > shown.length ? `, +${String(hits.length - shown.length)} more` : ''}. ` +
+                `Why this class is checked: ${c.why}`,
+        );
+    }
+    return out;
+}
+
+/** Per-class counts, for the green-path report. */
+export function payloadClassCounts(
+    files: readonly PackFile[],
+): Array<{ id: string; count: number; limit: number; measurable: boolean }> {
+    const built = payloadIsBuilt(files);
+    return CONTENT_CLASSES.map((c) => ({
+        id: c.id,
+        count: files.filter((f) => c.match(f.path)).length,
+        limit: c.limit,
+        measurable: built || !c.requires_build,
+    }));
+}
+
 export function evaluate(budget: PackSizeBudget, pack: PackResult): string[] {
     const errors: string[] = [];
 
@@ -163,7 +284,103 @@ function readPack(argv: readonly string[]): PackResult {
     return parsePackJson(stdout);
 }
 
+/**
+ * Per-class discrimination, proven rather than asserted.
+ *
+ * WHY THIS EXISTS AND THE CANARY DOES NOT COVER IT. `gate-coverage.yml` carries
+ * `canary?: CanarySpec` — exactly ONE recipe per gate id, not a list (see
+ * `check_gate_coverage.ts`'s entry shape). The roadmap step behind this asked
+ * for "one canary per class", which the register cannot express. Two of the four
+ * classes cannot be planted through it at all: `compiled-test-artefact` is
+ * excluded from the payload by the `files[]` negations that fixed it, so a plant
+ * never ships and never reds, and `source-map` needs 121 files in a BUILT tree.
+ *
+ * So the register gets the one canary it can hold — the credential-shaped plant,
+ * chosen because that class is empty today and an empty unchecked class is
+ * indistinguishable from one nobody looked at — and every class is proven red
+ * here, over a synthetic payload, deterministically and with no pack run.
+ *
+ * A test file was the alternative and is weaker: the non-adopter ratchet in
+ * `check_gate_coverage` requires a NEW registered gate to carry a `--self-test`
+ * or an exemption, and a self-test drives the gate's own decision function
+ * rather than a copy of it.
+ */
+function packFiles(...paths: readonly string[]): PackFile[] {
+    return paths.map((path) => ({ path, size: 1 }));
+}
+
+/** A payload that looks built, so `requires_build` classes do not abstain. */
+function builtPayload(...paths: readonly string[]): PackFile[] {
+    return packFiles('dist/cli/agent-config.js', ...paths);
+}
+
+function selfTest(): number {
+    // NOT under `dist/cli/` — that prefix is exactly what `payloadIsBuilt`
+    // keys on, so maps placed there would make an "unbuilt" fixture built and
+    // the abstain case would test nothing. Found by the case failing, which is
+    // the self-test doing its job on its own fixtures.
+    const maps = (n: number): string[] =>
+        Array.from({ length: n }, (_, i) => `dist/hooks/chunk-${String(i)}.js.map`);
+    return runSelfTest({
+        gate: 'check_pack_size',
+        minCases: 9,
+        minRejectCases: 5,
+        cases: [
+            {
+                name: 'credential-shaped: a .pem in the payload is refused',
+                expect: 'reject',
+                run: () => (classifyPayload(packFiles('src/scripts/x.pem')).length > 0 ? 1 : 0),
+            },
+            {
+                name: 'credential-shaped: a dotted .env form is refused',
+                expect: 'reject',
+                run: () => (classifyPayload(packFiles('src/config/.env.production')).length > 0 ? 1 : 0),
+            },
+            {
+                name: 'ide-metadata: a .vscode entry is refused',
+                expect: 'reject',
+                run: () => (classifyPayload(packFiles('src/scripts/.vscode/settings.json')).length > 0 ? 1 : 0),
+            },
+            {
+                name: 'compiled-test-artefact: a shipped .test.js is refused',
+                expect: 'reject',
+                run: () => (classifyPayload(builtPayload('dist/cli/a.test.js')).length > 0 ? 1 : 0),
+            },
+            {
+                name: 'source-map: one over the measured ratchet is refused',
+                expect: 'reject',
+                run: () => (classifyPayload(builtPayload(...maps(121))).length > 0 ? 1 : 0),
+            },
+            {
+                name: 'source-map: the ratchet boundary itself passes',
+                expect: 'accept',
+                run: () => (classifyPayload(builtPayload(...maps(120))).length > 0 ? 1 : 0),
+            },
+            {
+                name: 'a plain payload passes — the classes are not firing on everything',
+                expect: 'accept',
+                run: () => (classifyPayload(packFiles('src/scripts/x.ts', 'README.md')).length > 0 ? 1 : 0),
+            },
+            {
+                // The false pass 1.2 closed. An unbuilt payload carries a fifth
+                // of the source maps, so a build-gated class must ABSTAIN there
+                // rather than report clean — and must not report a failure
+                // either, or every clean-checkout run would red.
+                name: 'unbuilt payload: build-gated classes abstain, not pass and not fail',
+                expect: 'accept',
+                run: () => (classifyPayload(packFiles(...maps(121))).length > 0 ? 1 : 0),
+            },
+            {
+                name: 'unbuilt payload: a build-INDEPENDENT class still fires',
+                expect: 'reject',
+                run: () => (classifyPayload(packFiles('src/scripts/id_rsa')).length > 0 ? 1 : 0),
+            },
+        ],
+    });
+}
+
 export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    if (argv.includes('--self-test')) return selfTest();
     let budget: PackSizeBudget;
     let pack: PackResult;
     try {
@@ -199,7 +416,14 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
         throw err;
     }
 
-    const errors = evaluate(budget, pack);
+    // The coverage register requires an enforced gate to report what it
+    // inspected, and it is the same reason `assertScanned` runs above: a verdict
+    // with no denominator cannot be told apart from a verdict over nothing.
+    // Printed on EVERY path, including the failing one, so a reader of a red run
+    // still knows the population it was red over.
+    process.stdout.write(`scanned: ${String(pack.files.length)}\n`);
+
+    const errors = [...evaluate(budget, pack), ...classifyPayload(pack.files)];
     const { perSkill, total } = skillBytes(pack.files);
     if (argv.includes('--json')) {
         process.stdout.write(
@@ -216,6 +440,15 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
             `${Object.keys(perSkill).length} skills, largest share ` +
             `${Math.max(...Object.values(perSkill).map((b) => (b / total) * 100)).toFixed(2)}%\n`,
     );
+    // Printed on the GREEN path on purpose. A class that is clean and silent is
+    // indistinguishable from a class nobody checks, which is the whole reason
+    // two of these four are limit-0 over an empty set today.
+    for (const c of payloadClassCounts(pack.files)) {
+        const verdict = c.measurable
+            ? `${String(c.count)} / ${c.limit === 0 ? 'must be 0' : `${String(c.limit)} max`}`
+            : 'NOT MEASURABLE — this payload has no dist/cli/**, so the tree is unbuilt and the class is out of view';
+        process.stdout.write(`    content class ${c.id}: ${verdict}\n`);
+    }
     return 0;
 }