@event4u/agent-config 16.1.0 → 16.3.0

package/src/scripts/lint_exit_codes.ts

@@ -0,0 +1,262 @@
+#!/usr/bin/env tsx
+/**
+ * A hook's exit code comes from the table, never from a numeral.
+ *
+ * road-to-a-kernel-that-guards-its-plumbing 4.1, the enforcing half.
+ * `hooks/exit_codes.ts` is the table; this is what keeps it the only one.
+ *
+ * WHAT THE NUMERALS COST. Thirty-three files under `src/scripts/hooks/` each
+ * declared their own `EXIT_ALLOW = 0` / `EXIT_BLOCK = 1` / `EXIT_WARN = 2`, two
+ * of them under a third name. The danger is not a typo: 1 and 2 mean the
+ * OPPOSITE things on Claude Code from what they mean in this tree's internal
+ * language, which is why `host_semantics.ts` exists to lower one onto the
+ * other. A bare `process.exit(1)` in a concern is a claim about which of the
+ * two dialects the writer had in mind, and the source does not record which.
+ *
+ * WHAT IT SCANS. `.ts` under `src/scripts/hooks/`, refusing a call whose
+ * argument is a bare numeric literal. An identifier is accepted whatever it is
+ * called — this gate does not verify that the identifier came from the table,
+ * because a gate that resolved imports would be a type-checker, and the thing
+ * it would catch (a local `const EXIT_BLOCK = 1` shadowing the import) is
+ * already visible in review as a duplicate declaration. Stated rather than left
+ * for a reader to assume the green covers it.
+ *
+ * WHY THE DISPATCHERS ARE OUT OF SCOPE. The `*-dispatcher.sh` trampolines carry
+ * `process.exit(0)` inside a `node -e` one-liner that reads a workspace root
+ * off stdin. They are shell, they cannot import, and their exit code is the
+ * one-liner's, never a verdict. The table's own header says so; this gate scans
+ * `.ts` only, which is the same boundary stated once more where it is enforced.
+ *
+ * THE TABLE FILE ITSELF is excluded, and that is the one exclusion: it is where
+ * the numerals are DEFINED, so a gate that refused them there would forbid the
+ * fix it exists to require.
+ *
+ * Exit codes: 0 clean · 1 a bare numeral reached `process.exit` · 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 { reportScanned } from './_lib/scan_scope.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+export const GATE = 'lint_exit_codes';
+
+const HOOKS_REL = path.join('src', 'scripts', 'hooks');
+
+/** The file that DEFINES the numerals. Excluding it is not a carve-out. */
+const TABLE_BASENAME = 'exit_codes.ts';
+
+/**
+ * The fixture import line, ASSEMBLED rather than written out.
+ *
+ * `prepack-check.mjs` scans source text for relative imports and cannot tell a
+ * string literal from a real one, so a fixture containing the words
+ * `from './exit_codes.js'` reads as this file importing a sibling that does not
+ * exist beside it — the table lives under `hooks/`. It reported exactly that
+ * before this was assembled. Splitting the specifier is the smallest change
+ * that keeps the fixture honest about what a passing hook file looks like
+ * without asserting an import this file does not make.
+ */
+const FIXTURE_IMPORT = (name: string): string => `import { ${name} } from '.` + `/${TABLE_BASENAME.replace('.ts', '.js')}';\n`;
+
+/**
+ * `process.exit(<digits>)`, with optional whitespace.
+ *
+ * Deliberately anchored on `process.exit` rather than on any `exit(`: a
+ * concern's own helper named `exit` is not the process boundary, and widening
+ * the pattern to catch it would red on ordinary code.
+ */
+const BARE_EXIT = /process\s*\.\s*exit\s*\(\s*(-?\d+)\s*\)/g;
+
+export interface ExitFinding {
+    readonly file: string;
+    readonly line: number;
+    readonly code: string;
+}
+
+/** Findings in one file's text. Pure, so a test reads the decision. */
+export function findBareExits(rel: string, text: string): ExitFinding[] {
+    const out: ExitFinding[] = [];
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] as string;
+        // A commented example is prose about the rule, not an exit.
+        if (/^\s*(\*|\/\/)/.test(line)) continue;
+        BARE_EXIT.lastIndex = 0;
+        let m: RegExpExecArray | null;
+        while ((m = BARE_EXIT.exec(line)) !== null) {
+            out.push({ file: rel, line: i + 1, code: m[1] as string });
+        }
+    }
+    return out;
+}
+
+function hookFiles(root: string): string[] {
+    const dir = path.join(root, HOOKS_REL);
+    let entries: string[];
+    try {
+        entries = fs.readdirSync(dir);
+    } catch {
+        return [];
+    }
+    return entries
+        .filter((f) => f.endsWith('.ts') && f !== TABLE_BASENAME)
+        .map((f) => path.join(HOOKS_REL, f))
+        .sort();
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    if (argv.includes('--self-test')) return selfTest();
+    const i = argv.indexOf('--root');
+    if (i !== -1 && (argv[i + 1] === undefined || argv[i + 1]?.startsWith('-') === true)) {
+        process.stderr.write(`${GATE}: \`--root\` needs a directory.\n`);
+        return 2;
+    }
+    const root = i === -1 ? ROOT : (argv[i + 1] as string);
+
+    const files = hookFiles(root);
+    const findings: ExitFinding[] = [];
+    // A file the gate cannot READ is not a file it cleared. The first version
+    // of this loop skipped it and then counted it complete, which is a false
+    // green with a number behind it — the exact shape `assertScanned` exists to
+    // refuse one level up, reintroduced inside the loop. Reported by an
+    // independent review before this landed.
+    const unreadable: string[] = [];
+    for (const rel of files) {
+        let text: string;
+        try {
+            text = fs.readFileSync(path.join(root, rel), 'utf-8');
+        } catch {
+            unreadable.push(rel);
+            continue;
+        }
+        findings.push(...findBareExits(rel, text));
+    }
+    if (unreadable.length > 0) {
+        for (const rel of unreadable) {
+            process.stderr.write(`❌  ${GATE}: cannot read ${rel} — the corpus is incomplete.\n`);
+        }
+        return 2;
+    }
+
+    // Before the verdict: a corpus of zero is a gate that read nothing, and a
+    // green over it says the tree is clean when nobody looked.
+    try {
+        reportScanned({ gate: GATE, scanned: files.length, units: 'hook file(s)', roots: [HOOKS_REL] });
+    } catch (exc) {
+        process.stderr.write(`❌  ${String((exc as Error).message)}\n`);
+        return 2;
+    }
+
+    const ledger = new GateLedger(GATE);
+    ledger.plan(files);
+    const failed = new Set(findings.map((f) => f.file));
+    for (const f of findings) {
+        ledger.fail(f.file, `bare exit numeral ${f.code} at line ${String(f.line)}`);
+    }
+    for (const rel of files) if (!failed.has(rel)) ledger.complete(rel);
+    ledger.report();
+
+    if (findings.length > 0) {
+        for (const f of findings) {
+            process.stdout.write(
+                `❌  ${GATE}: ${f.file}:${String(f.line)} exits with the bare numeral ` +
+                    `\`${f.code}\`. Import the name from \`hooks/exit_codes.ts\` — the numbers ` +
+                    'mean opposite things in this tree and on the host, and a numeral records ' +
+                    'neither.\n',
+            );
+        }
+        return 1;
+    }
+    process.stdout.write(
+        `✅  ${GATE}: ${String(files.length)} hook file(s), no bare exit numeral.\n`,
+    );
+    return 0;
+}
+
+function selfTest(): number {
+    const plant = (name: string, body: string): string => {
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), `exit-codes-${name}-`));
+        fs.mkdirSync(path.join(dir, HOOKS_REL), { recursive: true });
+        fs.writeFileSync(path.join(dir, HOOKS_REL, 'probe_hook.ts'), body, 'utf-8');
+        // The table itself, so the exclusion is exercised rather than assumed.
+        fs.writeFileSync(
+            path.join(dir, HOOKS_REL, TABLE_BASENAME),
+            'export const EXIT_ALLOW = 0;\nprocess.exit(0);\n',
+            'utf-8',
+        );
+        return dir;
+    };
+    const run = (root: string): number =>
+        runGateCli(ROOT, path.join('src', 'scripts', 'lint_exit_codes.ts'), ['--root', root], ROOT);
+
+    return runSelfTest({
+        gate: GATE,
+        minCases: 6,
+        minRejectCases: 4,
+        cases: [
+            {
+                name: 'an empty corpus is refused, not certified green',
+                expect: 'reject',
+                run: () => run(fs.mkdtempSync(path.join(os.tmpdir(), 'exit-codes-empty-'))),
+            },
+            {
+                name: 'a bare deny numeral fails',
+                expect: 'reject',
+                run: () => run(plant('block', 'process.exit(1);\n')),
+            },
+            {
+                name: 'a bare allow numeral fails too — 0 is the one people think is harmless',
+                expect: 'reject',
+                run: () => run(plant('allow', 'process.exit(0);\n')),
+            },
+            {
+                name: 'whitespace inside the call does not hide it',
+                expect: 'reject',
+                run: () => run(plant('spaced', 'process . exit ( 2 );\n')),
+            },
+            {
+                name: 'an imported name passes',
+                expect: 'accept',
+                run: () =>
+                    run(
+                        plant(
+                            'named',
+                            `${FIXTURE_IMPORT('EXIT_ALLOW')}process.exit(EXIT_ALLOW);\n`,
+                        ),
+                    ),
+            },
+            {
+                // The table defines the numerals; refusing them there would
+                // forbid the fix this gate exists to require. Exercised, not
+                // assumed — the plant writes a bare exit into it every time.
+                name: 'the table file is excluded even though it carries a numeral',
+                expect: 'accept',
+                run: () =>
+                    run(
+                        plant(
+                            'table',
+                            `${FIXTURE_IMPORT('EXIT_WARN')}process.exit(EXIT_WARN);\n`,
+                        ),
+                    ),
+            },
+        ],
+    });
+}
+
+function _isCliEntry(): boolean {
+    const entry = process.argv[1];
+    return entry !== undefined && import.meta.url === pathToFileURL(entry).href;
+}
+
+if (_isCliEntry()) {
+    process.exit(main());
+}

package/src/scripts/lint_hook_manifest.ts

@@ -52,6 +52,33 @@ const DEFAULT_MANIFEST = path.join(
 const HOOKS_DIR = path.join(REPO_ROOT, "src", "scripts", "hooks");
 const DEFAULT_HOST_LOWERING = path.join(HOOKS_DIR, "host_lowering.yaml");
 
+/**
+ * What a concern does to a turn — the closed set `effect:` draws from.
+ *
+ * Read by the neighbour census, which needs to say what sharing an event with
+ * a foreign entry actually risks. A foreign entry's effect is `unknown` unless
+ * its output shape has been observed: no host exposes another package's hook
+ * execution, so the honest default is that the neighbour's effect cannot be
+ * read off its registration.
+ *
+ * - `permission`   can refuse the thing it fires on
+ * - `context`      puts text in front of the model
+ * - `verification` checks a claim or a shape and reports what it found
+ * - `telemetry`    records state, a ledger, a counter
+ * - `memory`       reads or writes the memory layer
+ * - `notification` tells the human something and changes nothing else
+ * - `formatting`   reshapes a command or a generated file
+ */
+export const CONCERN_EFFECTS: ReadonlySet<string> = new Set([
+  "permission",
+  "context",
+  "verification",
+  "telemetry",
+  "memory",
+  "notification",
+  "formatting",
+]);
+
 // Canonical event vocabulary — keep in lock-step with
 // docs/contracts/hook-architecture-v1.md and dispatch_hook.EVENT_VOCABULARY.
 const EVENT_VOCABULARY: ReadonlySet<string> = new Set([
@@ -159,6 +186,32 @@ function _check_concerns(manifest: YamlObject, errors: string[]): Set<string> {
     if (!_isFile(path.join(REPO_ROOT, script))) {
       errors.push(`concerns.${name}: script not found at '${script}'`);
     }
+    // `effect:` — what this concern DOES to a turn, from a closed set. It is
+    // what lets the neighbour census say "a foreign entry shares this event
+    // with something of ours that can refuse" rather than only "two entries".
+    // Required and enum-checked, which is a stricter rule than the optional
+    // keys below for one reason: a concern with no effect, or with a
+    // misspelled one, would silently drop out of every double-gate comparison
+    // — the warning would stay quiet and read as "no conflict", which is the
+    // wrong answer rather than a missing one. There is no unknown-key guard
+    // on this mapping, so nothing else would catch `effects:`.
+    const effect = spec["effect"];
+    if (typeof effect !== "string" || !CONCERN_EFFECTS.has(effect)) {
+      errors.push(
+        `concerns.${name}: 'effect' must be one of ` +
+          `${[...CONCERN_EFFECTS].sort().join(" | ")} (got ${JSON.stringify(effect)})`,
+      );
+    } else if ((spec["severity"] === "blocking") !== (effect === "permission")) {
+      // The two fields answer the same question from different sides, so a
+      // disagreement is a mistake in one of them, never a shade of meaning:
+      // `blocking` is the dispatcher's word for "this can refuse" and
+      // `permission` is the census's.
+      errors.push(
+        `concerns.${name}: 'effect: ${effect}' contradicts ` +
+          `'severity: ${String(spec["severity"])}' — a concern that can refuse ` +
+          `is 'permission', and only those are 'blocking'`,
+      );
+    }
     // `tools:` — the optional per-concern tool filter the dispatcher applies
     // in-process (`_concern_matches_tool`). Validated because the failure mode
     // is silent: the dispatcher fails toward RUNNING the concern on anything
@@ -716,6 +769,61 @@ export function _check_host_lowering(
       }
     }
   }
+  _check_slot_answers(table, errors);
+}
+
+/**
+ * Every (host, slot) pair carries a date, and a citation to go with it.
+ *
+ * WHY AN ERROR AND NOT A WARNING. `block_exit: null` is the value the table
+ * carries on 29 of its 32 pairs, and until this check it meant two different
+ * things at once: "read the host's contract, it honours no refusal here" and
+ * "nobody has ever looked at this pair". Those are opposite epistemic states
+ * printed as the same byte, and the file's own header promises the first one
+ * ("`verified: null` means nobody established anything") without giving the
+ * per-slot layer any way to say it. `answered_at` is that way, and a soft
+ * warning would let the ambiguity back in one undated slot at a time — the
+ * exact drift the row-level `verified` gate was added to stop one level up.
+ *
+ * THE CITATION MAY BE INHERITED. A host publishes ONE hooks page, so requiring
+ * a per-slot `docs_url` would mean five copies of the same URL per host and
+ * five places for it to rot. The row's `verified.docs_url` is the citation
+ * unless the slot overrides it; what the check refuses is a dated answer with
+ * no reachable citation at all.
+ *
+ * A slot on a row with NO `verified` block is exempt from the citation half
+ * and not from the date: an undated row is already an error wherever it carries
+ * a blocking binding, and demanding a URL from a row that has none would report
+ * the same missing provenance twice in different words.
+ */
+export function _check_slot_answers(table: HostLowering, errors: string[]): void {
+  for (const [host, surfaces] of table) {
+    for (const [surface, row] of surfaces) {
+      for (const [slot, s] of row.slots) {
+        const where = `host_lowering ${host}/${surface}/${slot}`;
+        if (s.answered_at === null) {
+          errors.push(
+            `${where}: no \`answered_at\`. Every host-slot pair carries the date it was ` +
+              "last answered, so that a `block_exit: null` is a finding with a date on it " +
+              "rather than a slot nobody looked at.",
+          );
+          continue;
+        }
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(s.answered_at)) {
+          errors.push(`${where}: \`answered_at: ${s.answered_at}\` is not an ISO \`YYYY-MM-DD\` date.`);
+        }
+        // The row-level exemption the block comment above states: a row with no
+        // `verified` block already reports its missing provenance once, at row level.
+        if (row.verified !== null && s.docs_url === null && row.verified.docs_url === null) {
+          errors.push(
+            `${where}: dated \`${s.answered_at}\` with no citation — the slot carries no ` +
+              "`docs_url` and the row's `verified.docs_url` is absent. Cite the page the " +
+              "answer was read off, on the slot or on the row.",
+          );
+        }
+      }
+    }
+  }
 }
 
 export function lint(