@event4u/agent-config 9.24.0 → 9.26.0

package/src/scripts/check_depth_budget.ts

@@ -0,0 +1,295 @@
+#!/usr/bin/env tsx
+/**
+ * check_depth_budget — a per-file ceiling on the on-demand depth layer.
+ *
+ * ## The gap
+ *
+ * Rules carry a char cap (`lint_load_context.cap_for`). Skills carry a token
+ * budget class (`lint_token_budget_discipline`). The always-loaded set carries
+ * two budgets (`check_always_budget`). The 161 context and guideline files those
+ * rules and skills *route to* carry none — which is where the budget the other
+ * three gates defend leaks back in as on-demand bloat.
+ *
+ * The existence proof is in the corpus and is self-documenting:
+ * `contexts/execution/roadmap-process-loop.md` states **"Size budget: ≤ 4,000
+ * chars"** in its own header and is over 20,000. It declared a budget, nothing
+ * measured it, and it went 5× over.
+ *
+ * ## What this number is — and what it is NOT
+ *
+ * 16,000 chars is a **growth ratchet, not a quality threshold.** Say it plainly
+ * because the temptation to dress it up is exactly the failure this suite
+ * records elsewhere: a published measurement over 7,308 trajectories was used
+ * two days ago to set a *skill* ceiling at 3,500 tokens, and that measurement
+ * does not transfer here. Skills are procedural and load together; depth files
+ * are declarative and load one or two at a time. Applying the skill number to
+ * this layer would be a percentile wearing a study's clothes.
+ *
+ * So the honest claim is narrow: 16,000 sits just above the current p99, it
+ * makes the four existing outliers visible, and it stops a fifth from arriving
+ * unnoticed. Nothing here claims a reader comprehends 15,999 chars and fails at
+ * 16,001. If someone later measures comprehension degradation on *this* layer,
+ * that measurement replaces this number and this paragraph.
+ *
+ * ## Why a ratchet rather than advisory
+ *
+ * The plan said advisory-until-classified. Advisory is right when a new gate
+ * would land as an unfixable blocker — but it has a second-order cost this
+ * repository has already paid: an advisory line in a gate that exits 0 is a
+ * number nobody is obliged to move, and the four outliers would still be four
+ * outliers a year from now.
+ *
+ * The ratchet gives both halves. The four current over-ceiling files are
+ * recorded as a baseline and do not block; a fifth does. Shrink-only, so the
+ * count may fall and never rise. That is enforcement without a flag day, and it
+ * is the mechanism this suite already uses for exactly this shape.
+ *
+ * Exit codes: 0 = at or under baseline, 1 = a new over-ceiling file, 2 = usage.
+ */
+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 { checkRatchet } from './_lib/gate_baseline.js';
+import { GateLedger } from './_lib/gate_ledger.js';
+import { runGateCli, runSelfTest } from './_lib/gate_self_test.js';
+import { reportScanned } from './_lib/scan_scope.js';
+
+const SCRIPTS_DIR = path.dirname(fileURLToPath(import.meta.url));
+const REAL_REPO_ROOT = path.dirname(path.dirname(SCRIPTS_DIR));
+
+/**
+ * The ceiling, in characters.
+ *
+ * Deliberately expressed in chars, not tokens: every sibling budget in this
+ * suite that must be cheap to check uses chars, and a char count is the one
+ * measure that cannot drift with a tokenizer version.
+ */
+export const DEPTH_CEILING_CHARS = 16_000;
+
+/** The two roots that make up the on-demand depth layer. */
+export const DEPTH_ROOTS = ['src/agent-src/contexts', 'docs/guidelines'] as const;
+
+export interface DepthFile {
+    readonly file: string;
+    readonly chars: number;
+}
+
+function* walk(dir: string): Generator<string> {
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+        return;
+    }
+    for (const e of entries.sort((a, b) => (a.name < b.name ? -1 : 1))) {
+        const full = path.join(dir, e.name);
+        if (e.isDirectory()) {
+            yield* walk(full);
+        } else if (e.isFile() && e.name.endsWith('.md')) {
+            yield full;
+        }
+    }
+}
+
+export function collectDepthFiles(repoRoot: string): string[] {
+    const out: string[] = [];
+    for (const root of DEPTH_ROOTS) {
+        for (const f of walk(path.join(repoRoot, root))) {
+            out.push(f);
+        }
+    }
+    // A file reachable from both roots would be counted twice; dedupe on the
+    // resolved path so the published `scanned:` count is the number of distinct
+    // artefacts judged.
+    return [...new Set(out)].sort();
+}
+
+export function measure(repoRoot: string, files: readonly string[]): DepthFile[] {
+    const out: DepthFile[] = [];
+    for (const f of files) {
+        let chars: number;
+        try {
+            chars = fs.readFileSync(f, 'utf-8').length;
+        } catch {
+            continue;
+        }
+        out.push({ file: path.relative(repoRoot, f).split(path.sep).join('/'), chars });
+    }
+    return out;
+}
+
+interface Args {
+    readonly json: boolean;
+    readonly quiet: boolean;
+}
+
+function parseArgs(argv: readonly string[]): Args {
+    let json = false;
+    let quiet = false;
+    for (const arg of argv) {
+        if (arg === '--json') { json = true; }
+        else if (arg === '--quiet') { quiet = true; }
+        else if (arg === '-h' || arg === '--help') {
+            process.stdout.write('usage: check_depth_budget [--json] [--quiet]\n');
+            process.exit(0);
+        } else {
+            process.stderr.write(`check_depth_budget: unrecognized argument: ${arg}\n`);
+            process.exit(2);
+        }
+    }
+    return { json, quiet };
+}
+
+export function selfTest(): number {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'cdb-selftest-'));
+    const mkRepo = (bodies: Record<string, number>): string => {
+        const root = fs.mkdtempSync(path.join(tmp, 'repo-'));
+        for (const [rel, size] of Object.entries(bodies)) {
+            const p = path.join(root, rel);
+            fs.mkdirSync(path.dirname(p), { recursive: true });
+            fs.writeFileSync(p, 'x'.repeat(size), 'utf-8');
+        }
+        // A baseline of 0 makes any over-ceiling file a violation, which is the
+        // discrimination the self-test needs to prove.
+        const cfg = path.join(root, 'src', 'config');
+        fs.mkdirSync(cfg, { recursive: true });
+        fs.writeFileSync(
+            path.join(cfg, 'gate-violation-baselines.json'),
+            JSON.stringify({ gates: {} }),
+            'utf-8',
+        );
+        return root;
+    };
+    const run = (root: string): number => {
+        // `runGateCli` forwards the parent env, so this is how the child is
+        // pointed at the synthetic tree.
+        process.env['CHECK_DEPTH_BUDGET_ROOT'] = root;
+        try {
+            return runGateCli(REAL_REPO_ROOT, 'src/scripts/check_depth_budget.ts', ['--quiet'], root);
+        } finally {
+            delete process.env['CHECK_DEPTH_BUDGET_ROOT'];
+        }
+    };
+
+    try {
+        const over = mkRepo({ 'docs/guidelines/big.md': DEPTH_CEILING_CHARS + 1 });
+        const under = mkRepo({ 'docs/guidelines/ok.md': DEPTH_CEILING_CHARS - 1 });
+        const exact = mkRepo({ 'docs/guidelines/edge.md': DEPTH_CEILING_CHARS });
+        const empty = mkRepo({ 'README.md': 10 });
+        return runSelfTest({
+            gate: 'check_depth_budget',
+            minCases: 3,
+            minRejectCases: 2,
+            cases: [
+                { name: 'a file one char over the ceiling is rejected', expect: 'reject', run: () => run(over) },
+                { name: 'a file one char under the ceiling passes', expect: 'accept', run: () => run(under) },
+                {
+                    name: 'the ceiling itself is inclusive — exactly at the limit passes',
+                    expect: 'accept',
+                    run: () => run(exact),
+                },
+                {
+                    name: 'a dead scan root is rejected, not reported as clean',
+                    expect: 'reject',
+                    run: () => run(empty),
+                },
+            ],
+        });
+    } finally {
+        fs.rmSync(tmp, { recursive: true, force: true });
+    }
+}
+
+export function main(argv?: readonly string[]): number {
+    const raw = argv ?? process.argv.slice(2);
+    if (raw.includes('--self-test')) {
+        return selfTest();
+    }
+    const args = parseArgs(raw);
+    // Default to the root derived from this file's own location — robust to
+    // whatever cwd a wrapper or hook invokes the gate from. The env override
+    // exists so the self-test can drive the REAL binary against a synthetic
+    // tree; deliberately NOT a cwd fallback, because a "use the real repo when
+    // the given root looks empty" rule would make the dead-scan-root case
+    // silently pass by scanning the wrong corpus — the exact failure the
+    // `assertScanned` contract exists to catch.
+    const root = process.env['CHECK_DEPTH_BUDGET_ROOT'] ?? REAL_REPO_ROOT;
+
+    const files = collectDepthFiles(root);
+    const ledger = new GateLedger('check_depth_budget');
+    ledger.plan(files.map((f) => path.relative(root, f).split(path.sep).join('/')));
+
+    const measured = measure(root, files);
+    const over = measured.filter((m) => m.chars > DEPTH_CEILING_CHARS)
+        .sort((a, b) => b.chars - a.chars);
+    const overSet = new Set(over.map((o) => o.file));
+    for (const m of measured) {
+        if (overSet.has(m.file)) {
+            ledger.fail(m.file, `${String(m.chars)} chars > ceiling ${String(DEPTH_CEILING_CHARS)}`);
+        } else {
+            ledger.complete(m.file);
+        }
+    }
+    const tally = ledger.finalize();
+
+    if (args.json) {
+        process.stdout.write(
+            `${JSON.stringify(
+                { version: 1, ceiling: DEPTH_CEILING_CHARS, over, scanned: measured.length, ledger: tally },
+                null,
+                2,
+            )}\n`,
+        );
+    } else if (!args.quiet && over.length > 0) {
+        process.stdout.write(
+            `\nOver the ${String(DEPTH_CEILING_CHARS)}-char depth ceiling ` +
+                '(a growth ratchet, NOT a measured quality threshold):\n',
+        );
+        for (const o of over) {
+            process.stdout.write(`  ${String(o.chars).padStart(7, ' ')}  ${o.file}\n`);
+        }
+    }
+
+    reportScanned({
+        gate: 'check_depth_budget',
+        scanned: measured.length,
+        units: 'depth file(s)',
+        roots: [...DEPTH_ROOTS],
+    });
+
+    const verdict = checkRatchet({
+        gate: 'check_depth_budget',
+        actual: over.length,
+        repoRoot: root,
+    });
+    if (verdict.ok) {
+        process.stdout.write(`\n⚠️   ${verdict.message}\n`);
+        return 0;
+    }
+    process.stderr.write(`\n❌  ${verdict.message}\n`);
+    return 1;
+}
+
+const _HERE = fileURLToPath(import.meta.url);
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    if (import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+        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) {
+    process.exit(main());
+}

package/src/scripts/check_gate_coverage.ts

@@ -363,6 +363,7 @@ export function main(argv: readonly string[]): number {
     );
   }
   const hardening = report_hardening_ratchet();
+  const selfTest = report_self_test_ratchet();
   if (failed.length > 0) {
     process.stdout.write(`❌  ${String(failed.length)} gate(s) failed the coverage floor.\n`);
     return 1;
@@ -370,6 +371,9 @@ export function main(argv: readonly string[]): number {
   if (hardening !== 0) {
     return hardening;
   }
+  if (selfTest !== 0) {
+    return selfTest;
+  }
   process.stdout.write('✅  every enforced gate cleared its coverage floor.\n');
   return 0;
 }
@@ -400,6 +404,69 @@ export function report_hardening_ratchet(): number {
   return verdict.ok ? 0 : 1;
 }
 
+/**
+ * Registered gates that carry no `--self-test` and no exemption — the count
+ * that must not RISE.
+ *
+ * `_lib/gate_self_test.ts` proves a gate DISCRIMINATES: it drives the real
+ * binary through cases that must reject and cases that must accept, with a
+ * `minRejectCases` floor so an all-accepting suite cannot satisfy it. A gate
+ * that emits an enforced `scanned:` count has proven it read something; only a
+ * self-test proves the reading changes the verdict.
+ *
+ * ## Why this is a NON-ADOPTER count and not an adoption column
+ *
+ * The roadmap item asked for adoption as a column in `gate-coverage.yml`,
+ * ratcheted upward. That is the exact shape `report_hardening_ratchet` above
+ * rejects in this same file — a coverage-percentage ratchet "tracks how far the
+ * fix has spread and can never regress, so it grades the solution instead of
+ * the problem". Inverting it fixes that: the number below can regress (a new
+ * registered gate written without a self-test raises it), and the target is 0.
+ * That is also the shape the sibling adoption ratchet already uses —
+ * `check_gate_completeness`'s ledger baseline is a shrink-only count of
+ * non-adopters, not a rising percentage.
+ *
+ * Population is the MANIFEST, not every script under `src/scripts`: a self-test
+ * is a claim about a gate CI runs against a floor. Padding the manifest to move
+ * this number would add a floor per row, which is the opposite of gaming.
+ *
+ * Exemption marker: `// self-test-exempt: <reason>` with a non-empty reason. A
+ * bare marker does not count — same discipline as `// no-index:` and
+ * `// ledger-exempt:`.
+ */
+export function list_self_test_non_adopters(
+  dir = path.join(REPO_ROOT, 'src/scripts'),
+  ids: ReadonlySet<string> = enforced_manifest_ids(),
+): string[] {
+  const out: string[] = [];
+  for (const id of [...ids].sort()) {
+    let src: string;
+    try {
+      src = fs.readFileSync(path.join(dir, `${id}.ts`), 'utf8');
+    } catch {
+      // A registered id with no readable script cannot prove discrimination.
+      out.push(id);
+      continue;
+    }
+    const adopts = /_lib\/gate_self_test\.js/.test(src);
+    const exempt = /\/\/\s*self-test-exempt:\s*\S/.test(src);
+    if (!adopts && !exempt) out.push(id);
+  }
+  return out;
+}
+
+/** Ratchet wrapper for {@link list_self_test_non_adopters}. */
+export function report_self_test_ratchet(): number {
+  const missing = list_self_test_non_adopters();
+  const verdict = checkRatchet({
+    gate: 'gate-self-test:registered-non-adopters',
+    actual: missing.length,
+    repoRoot: REPO_ROOT,
+  });
+  process.stdout.write(`  ${verdict.ok ? '✅' : '❌'} ${verdict.message}\n`);
+  return verdict.ok ? 0 : 1;
+}
+
 /**
  * Manifest ids whose `scanned:` line is actually ENFORCED against a floor.
  *

package/src/scripts/check_hook_bundle_freshness.ts

@@ -0,0 +1,183 @@
+#!/usr/bin/env tsx
+/**
+ * Fail when the self-hosted hook bundle is older than the hook sources it
+ * bundles — i.e. when this repo's own agent is running a hook fix that has
+ * not been built.
+ *
+ * WHY THIS EXISTS — measured, not hypothetical.
+ *
+ * The Claude hook command resolves its dispatcher in two steps: the installed
+ * package copy (`node_modules/@event4u/agent-config/dist/hooks/dispatch.js`)
+ * if present, else this repo's OWN `dist/hooks/dispatch.js`. In the
+ * agent-config repo the second branch always wins — that is the dogfooding
+ * path, and it is the only place these hooks are exercised before release.
+ *
+ * `dist/hooks/dispatch.js` is UNTRACKED (a build artifact) and is produced
+ * only by `npm run build:hooks`, which no Taskfile target, no `task ci`
+ * target, and no workflow invokes. `prepack` runs the full build, so a
+ * PUBLISHED package is always fresh and consumers are unaffected. The gap is
+ * local and it is exactly where the testing happens.
+ *
+ * Consequence, observed on 2026-08-06: the conformance round-2 PR (#1195)
+ * merged four hook fixes — among them the language-mirror pin — while the
+ * running bundle was from 07:27 that morning, before any of them existed.
+ * Ten hook sources were newer than the bundle. In the very session that
+ * shipped the language fix, the scanner counted four German-prompt /
+ * English-reply violations: the fix was merged, correct, and not loaded.
+ *
+ * A hook fix that cannot reach the agent that wrote it is indistinguishable
+ * from no fix, and nothing said so. This gate says so.
+ *
+ * WHAT IT DOES NOT DO: it never builds. Building into a live hook path is a
+ * documented hazard in this repo (an esbuild run that overwrites the
+ * dispatcher a running hook is executing can wedge the tool loop), so the
+ * remedy is printed for a human to run deliberately.
+ *
+ * Exit codes: 0 = fresh, or no self-hosted bundle to check · 1 = stale.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { parse as parseYaml } from "yaml";
+
+import { reportScanned } from "./_lib/scan_scope.js";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(HERE, "..", "..");
+const BUNDLE = path.join("dist", "hooks", "dispatch.js");
+const MANIFEST = path.join("src", "scripts", "hook_manifest.yaml");
+const HOOK_DIR = path.join("src", "scripts", "hooks");
+const REMEDY = "npm run build:hooks";
+
+/** Every source whose edit changes the bundle's behaviour. */
+export function bundledSources(root: string): string[] {
+  const out = new Set<string>();
+
+  const manifestAbs = path.join(root, MANIFEST);
+  if (fs.existsSync(manifestAbs)) {
+    out.add(MANIFEST);
+    try {
+      const doc = parseYaml(fs.readFileSync(manifestAbs, "utf-8")) as {
+        concerns?: Record<string, { script?: string }>;
+      };
+      for (const def of Object.values(doc?.concerns ?? {})) {
+        const s = def?.script;
+        // A concern script is bundled wherever it lives, not only under hooks/.
+        if (typeof s === "string" && s.endsWith(".ts")) out.add(s);
+      }
+    } catch {
+      // A malformed manifest is another gate's problem; still check the dir.
+    }
+  }
+
+  const hookDirAbs = path.join(root, HOOK_DIR);
+  if (fs.existsSync(hookDirAbs)) {
+    for (const e of fs.readdirSync(hookDirAbs, { withFileTypes: true })) {
+      if (e.isFile() && e.name.endsWith(".ts")) out.add(path.join(HOOK_DIR, e.name));
+    }
+  }
+
+  return [...out].filter((rel) => fs.existsSync(path.join(root, rel))).sort();
+}
+
+export interface Result {
+  /** No self-hosted bundle → the installed package copy is authoritative. */
+  skipped: boolean;
+  bundleMtimeMs: number;
+  /** Sources strictly newer than the bundle, newest first. */
+  stale: { file: string; mtimeMs: number }[];
+  checked: number;
+}
+
+export function check(root: string): Result {
+  const bundleAbs = path.join(root, BUNDLE);
+  if (!fs.existsSync(bundleAbs)) {
+    return { skipped: true, bundleMtimeMs: 0, stale: [], checked: 0 };
+  }
+  const bundleMtimeMs = fs.statSync(bundleAbs).mtimeMs;
+  const sources = bundledSources(root);
+  const stale = sources
+    .map((file) => ({ file, mtimeMs: fs.statSync(path.join(root, file)).mtimeMs }))
+    .filter((s) => s.mtimeMs > bundleMtimeMs)
+    .sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return { skipped: false, bundleMtimeMs, stale, checked: sources.length };
+}
+
+function stamp(ms: number): string {
+  return new Date(ms).toISOString().replace("T", " ").slice(0, 16);
+}
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+  const root = REPO_ROOT;
+  const quiet = argv.includes("--quiet");
+  const r = check(root);
+
+  // Scope hardening: publish the count and refuse a silent zero. The one
+  // legitimate zero is the absent self-hosted bundle — an optional input, and
+  // the reason survives the manifest's own test ("if the scan root were
+  // deleted, would this still make sense?"): with no bundle there is no stale
+  // dispatcher to catch, which is a correct verdict rather than blindness.
+  reportScanned({
+    gate: "check_hook_bundle_freshness",
+    scanned: r.checked,
+    units: "bundled hook source(s)",
+    roots: [BUNDLE, HOOK_DIR, MANIFEST],
+    ...(r.skipped
+      ? {
+          allowEmpty:
+            "OPTIONAL_INPUT: no self-hosted dist/hooks/dispatch.js — this repo is not " +
+            "running its own bundle (fresh checkout / CI), so there is nothing to compare against.",
+        }
+      : {}),
+  });
+
+  // A gate that scans nothing must SAY it scanned nothing — a silent green
+  // here is indistinguishable from a pass.
+  if (r.skipped) {
+    if (!quiet) {
+      process.stdout.write(
+        `✅  OK  hook bundle: no self-hosted ${BUNDLE} — the installed package copy is in use, nothing to check\n`,
+      );
+    }
+    return 0;
+  }
+
+  if (r.stale.length === 0) {
+    if (!quiet) {
+      process.stdout.write(
+        `✅  OK  hook bundle: fresh (built ${stamp(r.bundleMtimeMs)}, ${String(r.checked)} bundled source(s) checked)\n`,
+      );
+    }
+    return 0;
+  }
+
+  console.error(
+    `❌  hook bundle is STALE — the running dispatcher predates ${r.stale.length} of ${r.checked} bundled source(s).`,
+  );
+  console.error(`    ${BUNDLE} built ${stamp(r.bundleMtimeMs)}; newer sources:`);
+  for (const s of r.stale.slice(0, 10)) {
+    console.error(`      ${stamp(s.mtimeMs)}  ${s.file}`);
+  }
+  if (r.stale.length > 10) console.error(`      … and ${r.stale.length - 10} more`);
+  console.error("");
+  console.error(`    Your hooks are running the OLD code. Rebuild:  ${REMEDY}`);
+  console.error(
+    "    (This gate never builds for you — writing into a live hook path can wedge the tool loop.)",
+  );
+  return 1;
+}
+
+const invokedDirectly = ((): boolean => {
+  const entry = process.argv[1];
+  if (entry === undefined) return false;
+  try {
+    return fs.realpathSync(path.resolve(entry)) === fs.realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+})();
+
+if (invokedDirectly) {
+  process.exit(main());
+}