@event4u/agent-config 14.9.0 → 14.11.0

package/src/scripts/check_enforcement_denominator.ts

@@ -0,0 +1,365 @@
+#!/usr/bin/env tsx
+/**
+ * CI gate: exactly one enforcement denominator is quotable, and it comes from
+ * the resolver.
+ *
+ * WHY. Measured on 2026-08-23, the tree published **five** figures for one
+ * property — how many governed rules declare no enforcement backstop.
+ * `docs/proof.md` carried **86** in one place and **89** in another (two
+ * different frames quoted under one heading); a frontmatter-strict grep of
+ * `src/rules/` returned **87**; an any-line grep returned **82**; and a
+ * hand-written ledger entry at `docs/CLAIMS.md:203` carried its own snapshot.
+ * A reader had no way to tell which was the answer, and correcting any single
+ * figure would have left the plurality intact.
+ *
+ * `check_enforcement_coverage` is the only citable source: it RESOLVES rather
+ * than counts (a declared validator no workflow reaches is `unwired`, not
+ * covered) and it publishes its denominator with the frame that produced it.
+ * `docs/proof.md` § 4b projects that output. This gate is what stops a sixth
+ * number appearing — a sixth number would be the defect, not the fix.
+ *
+ * THE CONTRACT. In the scanned corpus, a line stating an enforcement count is a
+ * finding, full stop. Not "a wrong one" — the gate deliberately does NOT compare
+ * values against the resolver, because a hand-written figure that happens to be
+ * right today is the mechanism by which the plurality returned every previous
+ * time. The remedy is to cite the generated projection or the resolver's own
+ * output instead of restating a number.
+ *
+ * SCOPE, and why each exclusion is not a loophole:
+ *   · `docs/**` plus `README.md` — the published surfaces. `agents/` is
+ *     excluded wholesale because an evidence artefact records a measurement
+ *     taken at a stated time, which is its job; freezing those would forbid
+ *     measurement itself.
+ *   · `docs/decisions/` — an ADR is a dated record of what was true when the
+ *     decision was made. Rewriting one to today's number destroys the record.
+ *   · `docs/archive/` — shipped changelogs, immutable by construction.
+ *   · Any file whose head declares `GENERATED by` — that IS the resolver's
+ *     projection, which is the sanctioned home for the number.
+ *
+ * Escape hatch: `<!-- enforcement-count-ok: <reason> -->` on the line, reason
+ * mandatory. A bare marker stays a finding.
+ *
+ * Exit codes:
+ *   0 — no hand-written enforcement count in the published corpus
+ *   1 — at least one (or a marker with no reason)
+ *   2 — the gate could not run (dead scan scope, bad args)
+ */
+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, LedgerUsageError } from './_lib/gate_ledger.js';
+import { runGateCli, runSelfTest, type SelfTestCase } from './_lib/gate_self_test.js';
+import { DeadScopeError, reportScanned } from './_lib/scan_scope.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const DEFAULT_ROOT = path.join(path.dirname(_HERE), '..', '..');
+const SELF = 'src/scripts/check_enforcement_denominator.ts';
+
+const SELF_TEST_MIN_CASES = 7;
+const SELF_TEST_MIN_REJECT = 3;
+
+/** Roots walked, repo-relative. */
+const SCAN_ROOTS = ['docs', 'README.md'] as const;
+
+/** Repo-relative prefixes excluded — see the docstring for why each is not a loophole. */
+const EXCLUDED_PREFIXES = ['docs/decisions/', 'docs/archive/'] as const;
+
+/** A file declaring this in its first few lines is the resolver's own projection. */
+const GENERATED_MARKER = 'GENERATED by';
+const GENERATED_HEAD_LINES = 5;
+
+/** Same-line exemption; the reason after the colon must be non-empty. */
+const MARKER = 'enforcement-count-ok:';
+
+/**
+ * A line is a candidate only when it talks about enforcement AND carries a
+ * rule-count shape. Both halves are load-bearing: the keyword alone matches
+ * every prose mention of a backstop, and the shape alone matches "2 rules" in a
+ * concepts page, which is not this property at all.
+ */
+const ENFORCEMENT_KEYWORDS =
+    /undeclared|enforced_by|enforcement coverage|carry a backstop|backstop that fails/;
+
+const COUNT_SHAPES: readonly RegExp[] = [
+    /\b\d+\s+of\s+\d+\s+(?:governed\s+)?rules?\b/,
+    /\b\d+\s+(?:governed\s+)?rules?\b/,
+    /\b\d+\s+undeclared\b/,
+    /\bundeclared\s+\d+\b/,
+];
+
+export interface Finding {
+    file: string;
+    line: number;
+    excerpt: string;
+    /** `raw` — an unmarked count. `bare-marker` — a marker with no reason. */
+    kind: 'raw' | 'bare-marker';
+}
+
+function markerOn(line: string): 'none' | 'bare' | 'reasoned' {
+    const at = line.indexOf(MARKER);
+    if (at < 0) return 'none';
+    const tail = line.slice(at + MARKER.length).replace(/-->\s*$/, '').trim();
+    return tail === '' ? 'bare' : 'reasoned';
+}
+
+export function scanText(relPath: string, text: string): Finding[] {
+    const out: Finding[] = [];
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i] ?? '';
+        if (!ENFORCEMENT_KEYWORDS.test(line)) continue;
+        if (!COUNT_SHAPES.some((re) => re.test(line))) continue;
+        const marker = markerOn(line);
+        if (marker === 'reasoned') continue;
+        out.push({
+            file: relPath,
+            line: i + 1,
+            excerpt: line.trim().slice(0, 120),
+            kind: marker === 'bare' ? 'bare-marker' : 'raw',
+        });
+    }
+    return out;
+}
+
+/** `true` when the file declares itself generated — i.e. it IS the projection. */
+export function isGenerated(text: string): boolean {
+    return text.split('\n', GENERATED_HEAD_LINES).join('\n').includes(GENERATED_MARKER);
+}
+
+/** Every markdown file in scope, repo-relative, sorted. */
+export function corpus(root: string): string[] {
+    const out: string[] = [];
+    const walk = (rel: string): void => {
+        const abs = path.join(root, rel);
+        let st: fs.Stats;
+        try {
+            st = fs.statSync(abs);
+        } catch {
+            return;
+        }
+        if (st.isFile()) {
+            if (!rel.endsWith('.md')) return;
+            if (EXCLUDED_PREFIXES.some((p) => rel.startsWith(p))) return;
+            out.push(rel);
+            return;
+        }
+        if (!st.isDirectory()) return;
+        for (const name of fs.readdirSync(abs).sort()) walk(path.posix.join(rel, name));
+    };
+    for (const r of SCAN_ROOTS) walk(r);
+    return out.sort();
+}
+
+export function check(root: string): { code: number; findings: Finding[]; scanned: number } {
+    const files = corpus(root);
+    const findings: Finding[] = [];
+    const ledger = new GateLedger('check_enforcement_denominator');
+
+    try {
+        reportScanned({
+            gate: 'check_enforcement_denominator',
+            scanned: files.length,
+            units: 'published markdown file(s)',
+            roots: [...SCAN_ROOTS],
+        });
+    } catch (err) {
+        if (err instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${err.message}\n`);
+            return { code: 2, findings, scanned: files.length };
+        }
+        throw err;
+    }
+
+    try {
+        ledger.plan(files);
+        for (const rel of files) {
+            const text = fs.readFileSync(path.join(root, rel), 'utf-8');
+            if (isGenerated(text)) {
+                ledger.complete(rel);
+                continue;
+            }
+            const found = scanText(rel, text);
+            if (found.length > 0) {
+                findings.push(...found);
+                ledger.fail(rel, `${String(found.length)} hand-written enforcement count(s)`);
+            } else {
+                ledger.complete(rel);
+            }
+        }
+    } catch (err) {
+        if (err instanceof LedgerUsageError) {
+            process.stderr.write(`❌  ${err.message}\n`);
+            return { code: 2, findings, scanned: files.length };
+        }
+        throw err;
+    }
+    ledger.report();
+
+    return { code: findings.length > 0 ? 1 : 0, findings, scanned: files.length };
+}
+
+/* ------------------------------------------------------------------ *
+ * Self-test
+ * ------------------------------------------------------------------ */
+
+function fixtureRoot(files: Record<string, string>): string {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'enf-denom-'));
+    for (const [rel, body] of Object.entries(files)) {
+        const abs = path.join(dir, rel);
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        fs.writeFileSync(abs, body);
+    }
+    return dir;
+}
+
+export function selfTest(): number {
+    const made: string[] = [];
+    const run = (files: Record<string, string>): number => {
+        const d = fixtureRoot(files);
+        made.push(d);
+        return runGateCli(DEFAULT_ROOT, SELF, ['--quiet', '--root', d], DEFAULT_ROOT);
+    };
+    const CLEAN = '# Docs\n\nNothing about counts here.\n';
+
+    const cases: SelfTestCase[] = [
+        {
+            name: 'rejects a hand-written "N of M governed rules … backstop" figure',
+            expect: 'reject',
+            run: () =>
+                run({
+                    'docs/a.md': '15 of 120 governed rules carry a backstop that fails a CI build.\n',
+                }),
+        },
+        {
+            name: 'rejects a hand-written undeclared count',
+            expect: 'reject',
+            run: () => run({ 'docs/a.md': 'Today 86 rules are undeclared.\n' }),
+        },
+        {
+            name: 'rejects the same figure in README.md',
+            expect: 'reject',
+            run: () => run({ 'README.md': '86 undeclared rules have no enforced_by.\n' }),
+        },
+        {
+            name: 'rejects a marker with no reason',
+            expect: 'reject',
+            run: () =>
+                run({
+                    'docs/a.md': `86 rules are undeclared. <!-- ${MARKER} -->\n`,
+                }),
+        },
+        {
+            name: 'accepts a marker carrying a reason',
+            expect: 'accept',
+            run: () =>
+                run({
+                    'docs/a.md': `86 rules are undeclared. <!-- ${MARKER} historical, dated in place -->\n`,
+                }),
+        },
+        {
+            name: "accepts the resolver's own generated projection",
+            expect: 'accept',
+            run: () =>
+                run({
+                    'docs/proof.md':
+                        `<!-- ${GENERATED_MARKER} src/scripts/build_proof.ts -->\n\n` +
+                        '120 rules · 15 blocking · 86 undeclared (no enforced_by yet).\n',
+                }),
+        },
+        {
+            name: 'accepts a dated ADR record (docs/decisions/ is excluded)',
+            expect: 'accept',
+            run: () =>
+                run({
+                    'docs/a.md': CLEAN,
+                    'docs/decisions/ADR-001-x.md': '86 rules were undeclared on 2026-08-12.\n',
+                }),
+        },
+        {
+            name: 'accepts a rule count with no enforcement sense ("2 rules" in a concepts page)',
+            expect: 'accept',
+            run: () => run({ 'docs/a.md': 'The kernel splits into 2 rules and a router.\n' }),
+        },
+        {
+            name: 'rejects a moved scan root rather than reporting clean (exit 2)',
+            expect: 'reject',
+            run: () =>
+                runGateCli(
+                    DEFAULT_ROOT,
+                    SELF,
+                    ['--quiet', '--root', path.join(DEFAULT_ROOT, 'no-such-root')],
+                    DEFAULT_ROOT,
+                ),
+        },
+    ];
+
+    try {
+        return runSelfTest({
+            gate: 'check_enforcement_denominator',
+            cases,
+            minCases: SELF_TEST_MIN_CASES,
+            minRejectCases: SELF_TEST_MIN_REJECT,
+        });
+    } finally {
+        for (const d of made) fs.rmSync(d, { recursive: true, force: true });
+    }
+}
+
+export function main(argv?: readonly string[]): number {
+    const args = argv ?? process.argv.slice(2);
+    if (args.includes('--self-test')) return selfTest();
+    const quiet = args.includes('--quiet');
+    const rootIdx = args.indexOf('--root');
+    const root = rootIdx >= 0 ? (args[rootIdx + 1] ?? DEFAULT_ROOT) : DEFAULT_ROOT;
+
+    const { code, findings, scanned } = check(root);
+    if (code === 2) return 2;
+
+    if (findings.length > 0) {
+        process.stdout.write('❌  hand-written enforcement count(s) in a published doc:\n\n');
+        for (const f of findings) {
+            const why =
+                f.kind === 'bare-marker' ? `\`${MARKER}\` with no reason` : 'hand-written count';
+            process.stdout.write(`  ${f.file}:${String(f.line)} — ${why}\n      ${f.excerpt}\n`);
+        }
+        process.stdout.write(
+            '\nExactly one enforcement denominator is quotable, and it comes from\n' +
+                '`check_enforcement_coverage` — which resolves rather than counts, and prints\n' +
+                'its denominator with the frame that produced it. `docs/proof.md` § 4b projects\n' +
+                'that output; cite the projection instead of restating a number. A figure that\n' +
+                'is right today is how the plurality returned every previous time.\n' +
+                `If the number is a dated record rather than a live claim, say so on the line:\n` +
+                `  <!-- ${MARKER} <reason> -->\n`,
+        );
+        return 1;
+    }
+
+    if (!quiet) {
+        process.stdout.write(
+            `✅  one citable enforcement denominator: ${String(scanned)} published doc(s) restate none of it.\n`,
+        );
+    }
+    return 0;
+}
+
+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) {
+    process.exit(main());
+}
+
+export { SCAN_ROOTS, EXCLUDED_PREFIXES, MARKER };

package/src/scripts/check_gate_coverage.ts

@@ -49,6 +49,7 @@ import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import * as yaml from 'js-yaml';
+import { asOf } from './_lib/as_of.js';
 import { checkRatchet } from './_lib/gate_baseline.js';
 import { GateLedger, type GateSkipReason } from './_lib/gate_ledger.js';
 import { runCountedProbe } from './_lib/counted_probe.js';
@@ -979,7 +980,7 @@ function run_canary_mode(specs: readonly GateSpec[], argv: readonly string[]): n
     process.stdout.write(`  ❌ DISAGREEMENT [${d.kind}] ${d.gate}: ${d.detail}\n`);
   }
 
-  const cycleId = `gate-surface-${new Date().toISOString().slice(0, 10)}`;
+  const cycleId = `gate-surface-${asOf().toISOString().slice(0, 10)}`;
   const li = argv.indexOf('--ledger');
   if (li >= 0 && argv[li + 1] !== undefined) {
     const out = path.resolve(REPO_ROOT, argv[li + 1] as string);

package/src/scripts/check_hook_bundle_freshness.ts

@@ -28,6 +28,18 @@
  * 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 — ORDERING IS NOT EQUIVALENCE. This gate compares
+ * mtimes, so `touch dist/hooks/dispatch.js` makes every source look older and
+ * this gate green while the executing bytes are stale. Demonstrated on this tree
+ * rather than argued (2026-08-23): a one-constant edit to
+ * `block_unauthorized_git.ts` plus a `touch` on the bundle left THIS gate at
+ * exit 0 while `check_hook_bundle_content` exited 1 with executing
+ * `sha256 ce21579b7c14` against rebuilt `ac83e2f51118` — identical byte count,
+ * different bytes. That is why the success line below says "ordering" and names
+ * the digest gate instead of claiming freshness outright, and why preflight runs
+ * the two together (`taskfiles/ci-fast.yml`). The content comparison is NOT
+ * duplicated here: one home per invariant.
+ *
  * 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
@@ -169,7 +181,7 @@ export function main(argv: string[] = process.argv.slice(2)): number {
   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`,
+        `✅  OK  hook bundle: ordering fresh (built ${stamp(r.bundleMtimeMs)}, ${String(r.checked)} bundled source(s) checked) — byte-equivalence is check_hook_bundle_content's\n`,
       );
     }
     return 0;

package/src/scripts/check_knowledge_cards.ts

@@ -37,6 +37,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 // tolerantly (try/except → None) so the project-local linter still runs if the
 // _lib package layout shifts; the TS twins always exist, so a static import is
 // byte-faithful for behaviour (the only observable effect is the --global path).
+import { asOf } from './_lib/as_of.js';
 import * as _kg from './_lib/knowledge_global.js';
 import * as _kgr from './_lib/knowledge_global_redaction.js';
 import { assertScanned } from './_lib/scan_scope.js';
@@ -485,7 +486,7 @@ function _maxDate(parsed: PyDate[]): PyDate {
 }
 
 function _todayUtcDate(): PyDate {
-    const now = new Date();
+    const now = asOf();
     return { year: now.getUTCFullYear(), month: now.getUTCMonth() + 1, day: now.getUTCDate() };
 }
 

package/src/scripts/check_knowledge_pages.ts

@@ -29,6 +29,7 @@ import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 import YAML from 'yaml';
 
+import { asOf } from './_lib/as_of.js';
 import { assertScanned } from './_lib/scan_scope.js';
 
 const PROG = 'check_knowledge_pages.ts';
@@ -72,7 +73,7 @@ function bodyLineCount(body: string): number {
 }
 
 /** Lint a single page's already-read content. Pure — no filesystem access — for direct unit testing. */
-export function lintPage(relPath: string, content: string, today: Date = new Date()): Warning[] {
+export function lintPage(relPath: string, content: string, today: Date = asOf()): Warning[] {
     const warnings: Warning[] = [];
     const fm = readFrontmatter(content);
 
@@ -145,7 +146,7 @@ function countPages(knowledgeRoot: string): number {
     );
 }
 
-export function lintAll(knowledgeRoot: string, today: Date = new Date()): Warning[] {
+export function lintAll(knowledgeRoot: string, today: Date = asOf()): Warning[] {
     const warnings: Warning[] = [];
     for (const dir of TYPED_DIRS) {
         const scanDir = path.join(knowledgeRoot, dir);

package/src/scripts/check_memory.ts

@@ -53,6 +53,7 @@ import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import YAML, { parseDocument } from 'yaml';
 
+import { asOf } from './_lib/as_of.js';
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 type Severity = 'error' | 'warning' | 'info';
@@ -276,7 +277,7 @@ function _dateDiffDays(today: PyDate, lv: PyDate): number {
 }
 
 function _today(): PyDate {
-    const now = new Date();
+    const now = asOf();
     return new PyDate(now.getFullYear(), now.getMonth() + 1, now.getDate());
 }