@event4u/agent-config 14.10.0 → 14.12.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_estate_count.ts

@@ -152,6 +152,7 @@ import { reportScanned, DeadScopeError } from './_lib/scan_scope.js';
 import { GateLedger } from './_lib/gate_ledger.js';
 import { resolveBaseRef } from './_lib/ratchet_base_ref.js';
 import { materialiseSubtree } from './_lib/base_tree.js';
+import { SKILLS_POSIX, measureSkillEstate } from './_lib/skill_estate.js';
 import { runGateCli, runSelfTest, type SelfTestCase } from './_lib/gate_self_test.js';
 
 const GATE = 'check_estate_count';
@@ -171,11 +172,35 @@ export interface EstateCounts {
     active_roadmaps: number;
     later_roadmaps: number;
     open_blockers: number;
+    /**
+     * Maintained `SKILL.md` files — `lifecycle: deprecated` excluded.
+     *
+     * A FOURTH corpus on the same machinery, added 2026-08-24 on AI council 2/2
+     * over the alternative of a second budget file and a second gate: the
+     * floor-from-the-base-ref machinery is the expensive part and should not be
+     * written twice, and a second ratchet is a second place to forget.
+     */
+    skill_count: number;
+    /**
+     * Exact-BPE tokens across those skills' `description:` fields.
+     *
+     * The second DIMENSION, not a companion figure. A count ratchet alone is
+     * gameable by merging four large skills into one file: the count falls, the
+     * payload a host must carry does not. `0` here means UNRESOLVED, never
+     * "no tokens" — see `tokensExact`.
+     */
+    skill_description_tokens: number;
 }
 
 export type MetricName = keyof EstateCounts;
 
-export const METRICS: readonly MetricName[] = ['active_roadmaps', 'later_roadmaps', 'open_blockers'];
+export const METRICS: readonly MetricName[] = [
+    'active_roadmaps',
+    'later_roadmaps',
+    'open_blockers',
+    'skill_count',
+    'skill_description_tokens',
+];
 
 export interface EstateBudget {
     /**
@@ -247,6 +272,16 @@ export interface EstateVerdict {
     authorisedGrowth: GrowthFinding[];
     /** The claims found in this change's diff, with their reasons. */
     claims: GrowthClaim[];
+    /**
+     * Metrics dropped from the compare, each with its reason.
+     *
+     * Never empty-and-silent: a skill metric drops when the base ref carries no
+     * `src/skills` (an old tag, a shallow clone) or when the tokeniser resolved
+     * on one side and not the other. Comparing an exact reading against a proxy
+     * one would move the number by more than the growth this gate exists to
+     * catch, so the metric is stated unavailable rather than guessed.
+     */
+    skippedMetrics: { metric: MetricName; reason: string }[];
     /** `null` when the diff half could not run; the reason is printed either way. */
     offsets: OffsetLedger | null;
     offsetSkipReason: string | null;
@@ -342,13 +377,26 @@ export function countEstate(repoRoot: string): EstateCounts {
     const stats = collect(roadmapRoot);
     const openOf = (rows: readonly { open_blockers: readonly unknown[] }[]): number =>
         rows.reduce((n, r) => n + r.open_blockers.length, 0);
+    const skills = measureSkillEstate(repoRoot);
     return {
         active_roadmaps: stats.length,
         later_roadmaps: countIn(roadmapRoot, 'later'),
         open_blockers: openOf(stats) + openOf(laterRoadmaps(roadmapRoot)),
+        skill_count: skills.skill_count,
+        // 0 stands for unresolved. `skillTokensExact` below is what the caller
+        // reads to tell that apart from a genuinely empty corpus, and the
+        // verdict skips the metric rather than comparing an exact reading
+        // against a proxy one — they differ by more than the growth a ratchet
+        // is trying to catch.
+        skill_description_tokens: skills.skill_description_tokens ?? 0,
     };
 }
 
+/** Did the tokeniser resolve under `root`? A ratchet must not mix the two modes. */
+export function skillTokensExact(root: string): boolean {
+    return measureSkillEstate(root).skill_description_tokens !== null;
+}
+
 /** `agents/roadmaps/<name>.md` — the active top level, never a subdirectory. */
 function isActiveTopLevel(rel: string): boolean {
     const norm = rel.split(path.sep).join('/');
@@ -506,19 +554,57 @@ export function evaluate(
     // property, and unlike a number nobody has to remember to update it.
     let floor: EstateCounts | null = null;
     let floorSkipReason: string | null = null;
+    /** Set when the base ref carries no `src/skills` — the skill metrics drop. */
+    let skillFloorSkipReason: string | null = null;
+    /** Set when either side's tokeniser did not resolve — that ONE metric drops. */
+    let skillTokenSkipReason: string | null = null;
+    if (!skillTokensExact(repoRoot)) {
+        skillTokenSkipReason =
+            'the tokeniser did not resolve at HEAD; an exact reading may not be compared ' +
+            'against a proxy one';
+    }
     if (baseRef === null || baseRef === undefined) {
         floorSkipReason =
             'no base ref resolved (no origin/main, no merge-commit parent) — the floor cannot be measured';
     } else {
         const base = materialiseSubtree(repoRoot, baseRef, ROADMAPS_POSIX);
+        // TWO subtrees, because the estate now spans two corpora and the floor
+        // must be measured on the base ref's own tree for BOTH. Materialised
+        // separately rather than widening the first call: `materialiseSubtree`
+        // takes one prefix, and the roadmap tree must stay readable even when
+        // the skills read fails (a `src/skills`-less base ref is a real state —
+        // an old tag, a shallow clone), in which case the skill metrics skip and
+        // the roadmap metrics still ratchet.
+        const baseSkills = materialiseSubtree(repoRoot, baseRef, SKILLS_POSIX);
         try {
             if (base.error !== null || base.files === 0) {
                 floorSkipReason = `could not read ${ROADMAPS_POSIX} at ${baseRef} — ${base.error ?? 'no files'}`;
             } else {
-                floor = countEstate(base.root);
+                const roadmapFloor = countEstate(base.root);
+                if (baseSkills.error !== null || baseSkills.files === 0) {
+                    // Roadmap floor stands; the skill floor is stated as
+                    // unavailable and its metrics are dropped from the compare.
+                    floor = roadmapFloor;
+                    skillFloorSkipReason =
+                        `could not read ${SKILLS_POSIX} at ${baseRef} — ` +
+                        `${baseSkills.error ?? 'no files'}`;
+                } else {
+                    const s = measureSkillEstate(baseSkills.root);
+                    floor = {
+                        ...roadmapFloor,
+                        skill_count: s.skill_count,
+                        skill_description_tokens: s.skill_description_tokens ?? 0,
+                    };
+                    if (s.skill_description_tokens === null) {
+                        skillTokenSkipReason =
+                            `the tokeniser did not resolve at ${baseRef}; an exact reading may ` +
+                            'not be compared against a proxy one';
+                    }
+                }
             }
         } finally {
             fs.rmSync(base.root, { recursive: true, force: true });
+            fs.rmSync(baseSkills.root, { recursive: true, force: true });
         }
     }
 
@@ -571,11 +657,32 @@ export function evaluate(
         active_roadmaps: offsets?.exempt.length ?? 0,
         later_roadmaps: offsets?.parked.length ?? 0,
         open_blockers: 0,
+        // The skill corpus gets NO allowance, and that is the whole point of the
+        // metric: the defect it addresses is a corpus that grew +8 in one release
+        // with nothing objecting. An addition takes the `estate_growth_exempt`
+        // claim path — a recorded reason in the diff — or it fails.
+        skill_count: 0,
+        skill_description_tokens: 0,
+    };
+
+    /** Metrics dropped from the compare, with the reason, never silently. */
+    const skippedMetrics: { metric: MetricName; reason: string }[] = [];
+    const skipMetric = (metric: MetricName): boolean => {
+        if (skillFloorSkipReason !== null && (metric === 'skill_count' || metric === 'skill_description_tokens')) {
+            skippedMetrics.push({ metric, reason: skillFloorSkipReason });
+            return true;
+        }
+        if (skillTokenSkipReason !== null && metric === 'skill_description_tokens') {
+            skippedMetrics.push({ metric, reason: skillTokenSkipReason });
+            return true;
+        }
+        return false;
     };
 
     const over: GrowthFinding[] = [];
     if (floor !== null) {
         for (const metric of METRICS) {
+            if (skipMetric(metric)) continue;
             const live = counts[metric];
             const allowed = floor[metric] + allowance[metric];
             if (live > allowed) {
@@ -596,6 +703,7 @@ export function evaluate(
         growth,
         authorisedGrowth,
         claims,
+        skippedMetrics,
         offsets,
         offsetSkipReason,
         unpaid,
@@ -1010,8 +1118,12 @@ export function main(argv: string[] = process.argv.slice(2)): number {
 
     for (const g of verdict.growth) {
         const allow = g.allowance > 0 ? ` (+${String(g.allowance)} allowed here)` : '';
+        // Two corpora share this gate, so the line names which one grew. It used
+        // to say "the roadmap estate" unconditionally, which was already the
+        // wrong noun for `skill_count` the moment that metric landed.
+        const corpus = g.metric.startsWith('skill_') ? 'the skill estate' : 'the roadmap estate';
         process.stderr.write(
-            `❌  the roadmap estate grew: ${g.metric} ${String(g.floor)} → ${String(g.live)}${allow}.\n` +
+            `❌  ${corpus} grew: ${g.metric} ${String(g.floor)} → ${String(g.live)}${allow}.\n` +
                 `    The floor is the measurement at ${verdict.floorRef ?? 'the base ref'}, not a number in a\n` +
                 '    config — so there is no number to edit and nothing to walk. The estate does not\n' +
                 '    walk down by itself, which is the defect this ratchet exists for. Either close,\n' +
@@ -1022,6 +1134,13 @@ export function main(argv: string[] = process.argv.slice(2)): number {
         );
     }
 
+    // A dropped metric is REPORTED, never silent: a reader must be able to tell
+    // "within its ratchet" from "within the ratchet of the metrics that could be
+    // measured". This is the same distinction the floor-skip reason above keeps.
+    for (const s of verdict.skippedMetrics) {
+        process.stdout.write(`  ⏭️  ${s.metric} not compared — ${s.reason}\n`);
+    }
+
     if (verdict.unpaid > 0 && verdict.offsets !== null) {
         process.stderr.write(
             `❌  ${String(verdict.unpaid)} new active roadmap(s) with no offset in the same change.\n` +

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);