@event4u/agent-config 14.10.0 → 14.12.0

package/src/scripts/lint_archived_skills.ts

@@ -19,17 +19,21 @@
  *   4. No archived slug still has a live SKILL.md (no zombies).
  *   5. No live SKILL.md cites an archived slug as a router target in its
  *      frontmatter `replaced_by:` field.
+ *   6. A slug that had a `SKILL.md` at the base ref and has none in the
+ *      working tree carries an archive note. See {@link removed_without_note}.
  *
  * Exit codes:
  *   0  contract holds
  *   1  one or more violations
  */
 
+import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { artefact_roots } from './_lib/agent_src.js';
+import { resolveBaseRef } from './_lib/ratchet_base_ref.js';
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -243,6 +247,19 @@ function main(): number {
         }
     }
 
+    // Rule 6 — removals that never entered the ledger.
+    const removalCheck = removed_without_note(REPO, archivedKeys, live);
+    if ('skipped' in removalCheck) {
+        process.stdout.write(`rule 6 skipped: ${removalCheck.skipped}\n`);
+    } else {
+        for (const slug of removalCheck.removed) {
+            errors.push(
+                `${slug}: SKILL.md removed since the base ref with no ` +
+                    `agents/evidence/archived-skills/${slug}.md note`,
+            );
+        }
+    }
+
     if (errors.length) {
         process.stderr.write(
             `❌  lint_archived_skills: ${errors.length} violation(s) across ${notes.length} note(s)\n`,
@@ -261,6 +278,82 @@ function main(): number {
     return 0;
 }
 
+/**
+ * Rule 6 — a slug that left the tree without entering the ledger.
+ *
+ * WHY THIS LIVES IN THE GATE AND NOT IN A SCAFFOLDER. The roadmap step that
+ * asked for this (`road-to-skill-link-integrity-and-manifest-sync` Phase 1
+ * Step 3) named `src/scripts/new_skill.ts --archive` as the extension point,
+ * on the premise that it is "a creation path with no symmetric removal path".
+ * That premise is false: `new_skill.ts` scaffolds into a `packages/<pack>/`
+ * container that ADR-051 retired, and its `main()` returns exit 2 with
+ * `error: no packages/ tree found` in this tree, because skill authoring moved
+ * to `src/skills/`. A mode added there could not run.
+ *
+ * The obligation is a CI property, not a tool property, and the distinction is
+ * the reason the ledger is empty: nothing forces a maintainer or an agent to
+ * delete a directory *through* a tool, so a scaffolder mode is a bypass by
+ * construction. Three slugs left this tree without a note while
+ * `agents/evidence/archived-skills/` held only a README.
+ *
+ * A RENAME IS A REMOVAL HERE, DELIBERATELY. Git would call
+ * `verify-before-complete` → `verify-completion-evidence` a rename; every link
+ * to the old slug still broke, and repairing eight of them is what produced
+ * this rule. So the old slug owes a note.
+ *
+ * THE COMPARISON IS AGAINST THE MERGE BASE, NOT THE TIP OF MAIN, and this was
+ * found the hard way: the first run of this rule reported `js-library-packaging`
+ * and `storybook-workshop` as unnoted removals. Neither had been removed — both
+ * were ADDED on main after this branch forked, so a branch that is merely
+ * BEHIND its base read every new skill as a deletion. That is the false-red
+ * class `_lib/ratchet_base_ref.ts` warns about in its own docstring ("the gate
+ * gets a reputation for false reds, and someone turns it off"). `git merge-base`
+ * answers the question the rule actually asks — did THIS branch remove it —
+ * because a skill added on main after the fork is not in the merge base at all.
+ *
+ * THE SKIP IS STATED, NEVER SILENT. With no resolvable base ref there is no
+ * "before" side, and comparing against an assumed-empty base would report every
+ * skill in the tree as removed. `resolveBaseRef` returns null in that case and
+ * this returns a `skipped` reason the caller prints — the honest default named
+ * in that helper's own contract. It is also blind to an uncommitted removal;
+ * CI is the authoritative gate and CI only ever sees committed work.
+ */
+export function removed_without_note(
+    repoRoot: string = REPO,
+    archived: ReadonlySet<string> = new Set(archived_slugs()),
+    liveSlugs: ReadonlySet<string> = new Set(live_skill_slugs()),
+): { skipped: string } | { removed: string[] } {
+    const base = resolveBaseRef(repoRoot);
+    if (base === null) {
+        return { skipped: 'no base ref resolved — nothing to compare against' };
+    }
+    const mb = spawnSync('git', ['merge-base', 'HEAD', base], {
+        cwd: repoRoot,
+        encoding: 'utf-8',
+    });
+    // A missing merge base is not "compare against the tip instead" — that is
+    // the false-red above. It is no comparable before-side at all.
+    const forkPoint = mb.status === 0 ? String(mb.stdout).trim() : '';
+    if (!forkPoint) {
+        return { skipped: `no merge base between HEAD and ${base}` };
+    }
+    const res = spawnSync(
+        'git',
+        ['ls-tree', '-r', '--name-only', forkPoint, '--', 'src/skills'],
+        { cwd: repoRoot, encoding: 'utf-8' },
+    );
+    if (res.status !== 0) {
+        return { skipped: `git ls-tree ${forkPoint} failed — base ref is not readable here` };
+    }
+    const atBase = new Set<string>();
+    for (const line of String(res.stdout).split('\n')) {
+        const m = /^src\/skills\/([^/]+)\/SKILL\.md$/.exec(line.trim());
+        if (m) atBase.add(m[1] as string);
+    }
+    const removed = [...atBase].filter((slug) => !liveSlugs.has(slug) && !archived.has(slug)).sort();
+    return { removed };
+}
+
 // --- helpers --------------------------------------------------------------
 
 function _exists(p: string): boolean {

package/src/scripts/lint_budget_ownership.ts

@@ -28,9 +28,11 @@
  * Exit codes: 0 clean · 1 findings · 2 internal error.
  */
 import * as fs from 'node:fs';
+import { parse as parseYaml } from 'yaml';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { asOf } from './_lib/as_of.js';
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const REPO_ROOT = path.resolve(fileURLToPath(import.meta.url), '..', '..', '..');
@@ -121,20 +123,69 @@ export function checkBudgetRows(relPath: string, doc: Record<string, unknown>):
     return errors;
 }
 
+/**
+ * Non-JSON budget files this gate governs, named ONE BY ONE.
+ *
+ * road-to-standing-payload-truth `b-budgets-yml-outside-ownership`: `budgets.yml`
+ * carries a `standing_rule_delivery` entry that gates the larger of the two red
+ * payload numbers, and it had no `owner` and no `review_by` because this gate
+ * filtered on `.json`.
+ *
+ * **An explicit list, NOT a widened glob**, and both council seats (2026-08-24)
+ * refused the glob for the same two reasons:
+ *
+ * 1. `*budget*.json` **IS** this gate's corpus definition (see `main`'s note), so
+ *    widening it to `*budget*.{json,yml}` means any future `*budget*.yml` dropped
+ *    into `src/config/` joins the governed set **silently**. A governed file
+ *    should be a decision, not a filename coincidence.
+ * 2. It could not have worked as written anyway: the read below was an
+ *    unconditional `JSON.parse`, so a YAML file entering through a widened glob
+ *    would have been reported as `unparseable JSON` — a red gate blaming the
+ *    file for the gate's own bug. Parsing is now dispatched on extension.
+ *
+ * Adding a row here is the whole cost of governing a new non-JSON budget, and
+ * `lint_budget_ownership.test.ts` asserts an unlisted `*budget*.yml` stays OUT.
+ */
+export const GOVERNED_NON_JSON: readonly string[] = ['budgets.yml'];
+
 export function budgetFiles(dir: string = CONFIG_DIR): string[] {
     try {
-        return fs
+        const globbed = fs
             .readdirSync(dir)
             .filter((f) => f.endsWith('.json') && f.toLowerCase().includes('budget'))
             .map((f) => path.join(dir, f));
+        const named = GOVERNED_NON_JSON.map((f) => path.join(dir, f)).filter((abs) =>
+            fs.existsSync(abs),
+        );
+        return [...globbed, ...named];
     } catch {
         return [];
     }
 }
 
+/**
+ * Parse a budget file by EXTENSION.
+ *
+ * The previous unconditional `JSON.parse` is the defect that made a widened glob
+ * unworkable; keeping it while adding a `.yml` row would have turned this gate
+ * red on the very file it was extended to govern.
+ */
+export function parseBudgetDoc(abs: string): Record<string, unknown> {
+    const text = fs.readFileSync(abs, 'utf-8');
+    if (abs.endsWith('.yml') || abs.endsWith('.yaml')) {
+        const doc = parseYaml(text) as unknown;
+        if (doc === null || typeof doc !== 'object' || Array.isArray(doc)) {
+            throw new Error('top level is not a mapping');
+        }
+        return doc as Record<string, unknown>;
+    }
+    return JSON.parse(text) as Record<string, unknown>;
+}
+
 export function main(): number {
     const files = budgetFiles();
-    // `*budget*.json` IS this gate's corpus definition, not a content-derived
+    // `*budget*.json` PLUS the explicitly named `GOVERNED_NON_JSON` rows IS this
+    // gate's corpus definition, not a content-derived
     // subset: zero matches means src/config/ moved or the budgets were deleted,
     // and the old "nothing to lint" exit 0 could not tell either from a healthy
     // tree. Of the two documented failure codes, 1 is the one the gate actually
@@ -154,14 +205,14 @@ export function main(): number {
         throw exc;
     }
     const errors: string[] = [];
-    const today = new Date().toISOString().slice(0, 10);
+    const today = asOf().toISOString().slice(0, 10);
     for (const abs of files) {
         const rel = path.relative(REPO_ROOT, abs);
         let doc: Record<string, unknown>;
         try {
-            doc = JSON.parse(fs.readFileSync(abs, 'utf-8')) as Record<string, unknown>;
+            doc = parseBudgetDoc(abs);
         } catch (e) {
-            errors.push(`${rel}: unparseable JSON (${(e as Error).message})`);
+            errors.push(`${rel}: unparseable budget file (${(e as Error).message})`);
             continue;
         }
         errors.push(...checkBudgetDoc(rel, doc));

package/src/scripts/lint_deterministic_time.ts

@@ -0,0 +1,470 @@
+#!/usr/bin/env tsx
+/**
+ * CI gate: a gate script does not read the wall clock directly.
+ *
+ * WHY. A gate's verdict should be a function of the tree, not of the hour it
+ * ran. Measured on 2026-08-23, before this gate existed, **17** of the
+ * `check_*` / `lint_*` scripts under `src/scripts/` read the clock inline, every
+ * one of them to make an age or staleness judgement. None of those 17 verdicts
+ * was reproducible from the commit alone: the same tree greens on Monday and
+ * reds on Friday, and a reviewer cannot recover which "now" produced the verdict
+ * CI published.
+ *
+ * `src/scripts/_lib/as_of.ts` is the seam that fixes it — one resolver, four
+ * rungs (`--as-of` argv, `AC_AS_OF` env, the commit date under CI, and the wall
+ * clock with an explicit non-reproducibility WARN). This gate is what stops the
+ * defect coming back: substituting the seam once is a diff, keeping it
+ * substituted is a ratchet.
+ *
+ * SCOPE is deliberately the gate prefixes only (`check_*`, `lint_*` under
+ * `src/scripts/`). A generator, a bench runner, or a hook legitimately reads
+ * real time; a *verdict* should not. Widening this to the whole tree would turn
+ * a determinism ratchet into a style rule and earn the suppressions that come
+ * with one.
+ *
+ * WHY THE MATCH RUNS OVER STRIPPED SOURCE. This file's own docstring names the
+ * construct it forbids, and its self-test fixtures are string literals
+ * containing it. A gate whose scope includes its own filename (`lint_*` does)
+ * and which matched raw text would refuse itself — so comments and string /
+ * template literals are blanked to spaces (line numbers preserved) before the
+ * patterns run. The same reason `check_no_automerge_key` anchors on a key rather
+ * than a word.
+ *
+ * THE ESCAPE HATCH, AND WHY IT IS NARROW. `// wall-clock-required: <reason>` on
+ * the offending line exempts it, and the reason is mandatory — a bare marker is
+ * still a finding. It exists for the one legitimate case this ratchet must not
+ * break: measuring *elapsed duration* inside a single run, where real time is
+ * the subject rather than a threshold input. Prefer `performance.now()` there;
+ * the marker is for when a `Date` is genuinely what the API needs.
+ *
+ * Exit codes:
+ *   0 — no gate script reads the wall clock directly
+ *   1 — at least one raw wall-clock read (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), '..', '..');
+
+/** This script's repo-relative path, for the self-test's CLI invocations. */
+const SELF = 'src/scripts/lint_deterministic_time.ts';
+
+const SELF_TEST_MIN_CASES = 6;
+const SELF_TEST_MIN_REJECT = 3;
+
+/** The directory the gate walks, and the prefixes that make a file a gate. */
+const SCAN_DIR = 'src/scripts';
+const GATE_PREFIXES = ['check_', 'lint_'] as const;
+
+/**
+ * The single sanctioned reader of the wall clock. Repo-relative, and outside
+ * {@link GATE_PREFIXES} by construction, so it is never in the scan set — named
+ * here so the failure message can point at it.
+ */
+const SEAM = 'src/scripts/_lib/as_of.ts';
+
+/** Same-line exemption. The reason after the colon must be non-empty. */
+const MARKER = 'wall-clock-required:';
+
+/**
+ * The forbidden constructs. Written as tolerant regexes rather than literals so
+ * this file's own source does not contain the strings it bans — see the
+ * docstring's note on stripped source; belt and braces, and the belt is cheap.
+ */
+const PATTERNS: readonly { id: string; re: RegExp; shown: string }[] = [
+    { id: 'date-now', re: /\bDate\s*\.\s*now\s*\(\s*\)/g, shown: 'Date' + '.now()' },
+    { id: 'new-date', re: /\bnew\s+Date\s*\(\s*\)/g, shown: 'new ' + 'Date()' },
+];
+
+/**
+ * Neutralise every non-code region, preserving line numbers and line lengths so
+ * a match's line number is still the source's.
+ *
+ * Two details are load-bearing and were both found by running this gate against
+ * the real corpus before trusting it:
+ *
+ * 1. **Comments become spaces, string bodies become `x`.** Blanking a string to
+ *    spaces collapses `new Date("2026-01-01")` into `new Date(          )`,
+ *    which the empty-parens pattern then matches — a false positive on a
+ *    perfectly deterministic parse. `check_knowledge_pages.ts:103` is exactly
+ *    that shape. Filling with a non-space keeps the argument visible as *an*
+ *    argument without keeping its content.
+ * 2. **`${...}` inside a template literal is code.** Blanking it wholesale hid a
+ *    real finding: `check_gate_coverage.ts:982` reads the clock inside a
+ *    template substitution, and the first draft of this gate reported it clean.
+ *
+ * Regex literals are left alone deliberately: a regex describing the forbidden
+ * construct (this file's own {@link PATTERNS}) does not itself match it, so
+ * there is nothing to hide, and detecting a regex literal from a `/` needs
+ * expression context this scanner does not have.
+ */
+export function stripNonCode(src: string): string {
+    const out = src.split('');
+    const n = src.length;
+    const put = (i: number, ch: string): void => {
+        if (out[i] !== '\n') out[i] = ch;
+    };
+
+    /** `//` to end of line. */
+    function lineComment(i: number): number {
+        while (i < n && src[i] !== '\n') put(i++, ' ');
+        return i;
+    }
+    /** `/*` to the closing delimiter. */
+    function blockComment(i: number): number {
+        put(i++, ' ');
+        put(i++, ' ');
+        while (i < n && !(src[i] === '*' && src[i + 1] === '/')) put(i++, ' ');
+        if (i < n) {
+            put(i++, ' ');
+            put(i++, ' ');
+        }
+        return i;
+    }
+    /** A `'` or `"` literal; an unterminated one stops at the newline. */
+    function simpleString(i: number): number {
+        const quote = src[i];
+        put(i++, 'x');
+        while (i < n) {
+            if (src[i] === '\\') {
+                put(i++, 'x');
+                if (i < n) put(i++, 'x');
+                continue;
+            }
+            if (src[i] === quote) {
+                put(i++, 'x');
+                break;
+            }
+            if (src[i] === '\n') break;
+            put(i++, 'x');
+        }
+        return i;
+    }
+    /** A `\`` literal, recursing into every `${...}` as code. */
+    function template(i: number): number {
+        put(i++, 'x');
+        while (i < n) {
+            if (src[i] === '\\') {
+                put(i++, 'x');
+                if (i < n) put(i++, 'x');
+                continue;
+            }
+            if (src[i] === '`') {
+                put(i++, 'x');
+                break;
+            }
+            if (src[i] === '$' && src[i + 1] === '{') {
+                i = substitution(i + 2);
+                continue;
+            }
+            put(i++, 'x');
+        }
+        return i;
+    }
+    /** Code inside `${ ... }`, up to the brace that closes it. */
+    function substitution(i: number): number {
+        let depth = 1;
+        while (i < n && depth > 0) {
+            const c = src[i];
+            const next = src[i + 1];
+            if (c === '/' && next === '/') {
+                i = lineComment(i);
+                continue;
+            }
+            if (c === '/' && next === '*') {
+                i = blockComment(i);
+                continue;
+            }
+            if (c === "'" || c === '"') {
+                i = simpleString(i);
+                continue;
+            }
+            if (c === '`') {
+                i = template(i);
+                continue;
+            }
+            if (c === '{') depth += 1;
+            if (c === '}') depth -= 1;
+            i += 1;
+        }
+        return i;
+    }
+
+    let i = 0;
+    while (i < n) {
+        const c = src[i];
+        const next = src[i + 1];
+        if (c === '/' && next === '/') {
+            i = lineComment(i);
+            continue;
+        }
+        if (c === '/' && next === '*') {
+            i = blockComment(i);
+            continue;
+        }
+        if (c === "'" || c === '"') {
+            i = simpleString(i);
+            continue;
+        }
+        if (c === '`') {
+            i = template(i);
+            continue;
+        }
+        i += 1;
+    }
+    return out.join('');
+}
+
+export interface Finding {
+    file: string;
+    line: number;
+    construct: string;
+    /** `raw` — an unmarked read. `bare-marker` — a marker with no reason. */
+    kind: 'raw' | 'bare-marker';
+}
+
+/** Does this raw line carry a marker, and does the marker carry a reason? */
+function markerOn(rawLine: string): 'none' | 'bare' | 'reasoned' {
+    const at = rawLine.indexOf(MARKER);
+    if (at < 0) return 'none';
+    return rawLine.slice(at + MARKER.length).trim() === '' ? 'bare' : 'reasoned';
+}
+
+export function scanSource(relPath: string, src: string): Finding[] {
+    const rawLines = src.split('\n');
+    const codeLines = stripNonCode(src).split('\n');
+    const findings: Finding[] = [];
+    for (let n = 0; n < codeLines.length; n += 1) {
+        const code = codeLines[n] ?? '';
+        for (const pat of PATTERNS) {
+            pat.re.lastIndex = 0;
+            if (!pat.re.test(code)) continue;
+            const marker = markerOn(rawLines[n] ?? '');
+            if (marker === 'reasoned') continue;
+            findings.push({
+                file: relPath,
+                line: n + 1,
+                construct: pat.shown,
+                kind: marker === 'bare' ? 'bare-marker' : 'raw',
+            });
+        }
+    }
+    return findings;
+}
+
+/** Repo-relative paths of every gate script under {@link SCAN_DIR}. */
+export function gateScripts(root: string): string[] {
+    const dir = path.join(root, SCAN_DIR);
+    let entries: string[];
+    try {
+        entries = fs.readdirSync(dir);
+    } catch {
+        return [];
+    }
+    return entries
+        .filter(
+            (name) =>
+                name.endsWith('.ts') &&
+                !name.endsWith('.test.ts') &&
+                GATE_PREFIXES.some((p) => name.startsWith(p)),
+        )
+        .sort()
+        .map((name) => `${SCAN_DIR}/${name}`);
+}
+
+export function check(root: string): { code: number; findings: Finding[]; scanned: number } {
+    const files = gateScripts(root);
+    const findings: Finding[] = [];
+    const ledger = new GateLedger('lint_deterministic_time');
+
+    try {
+        reportScanned({
+            gate: 'lint_deterministic_time',
+            scanned: files.length,
+            units: 'gate script(s)',
+            roots: [SCAN_DIR],
+        });
+    } 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 found = scanSource(rel, fs.readFileSync(path.join(root, rel), 'utf-8'));
+            if (found.length > 0) {
+                findings.push(...found);
+                ledger.fail(rel, `${String(found.length)} raw wall-clock read(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(), 'det-time-'));
+    fs.mkdirSync(path.join(dir, SCAN_DIR), { recursive: true });
+    for (const [name, body] of Object.entries(files)) {
+        fs.writeFileSync(path.join(dir, SCAN_DIR, name), body);
+    }
+    return dir;
+}
+
+const CLEAN_GATE = ['import { asOf } from ', "'./_lib/as_of.js';", '\nconst now = asOf();\n'].join('');
+
+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);
+    };
+    // Built by concatenation so this file's own source stays clean.
+    const rawNow = 'const t = ' + 'Date' + '.now();\n';
+    const rawNew = 'const d = new ' + 'Date();\n';
+
+    const cases: SelfTestCase[] = [
+        {
+            name: `rejects a planted ${PATTERNS[0]?.shown ?? ''} in a check_ script`,
+            expect: 'reject',
+            run: () => run({ 'check_planted.ts': rawNow }),
+        },
+        {
+            name: `rejects a planted bare ${PATTERNS[1]?.shown ?? ''} in a lint_ script`,
+            expect: 'reject',
+            run: () => run({ 'lint_planted.ts': rawNew }),
+        },
+        {
+            name: 'rejects a marker with no reason',
+            expect: 'reject',
+            run: () => run({ 'check_planted.ts': rawNow.trimEnd() + ' // ' + MARKER + '\n' }),
+        },
+        {
+            name: 'accepts a marker carrying a reason',
+            expect: 'accept',
+            run: () =>
+                run({
+                    'check_ok.ts': rawNow.trimEnd() + ' // ' + MARKER + ' elapsed-duration probe\n',
+                }),
+        },
+        {
+            name: 'accepts a mention inside a comment or a string literal',
+            expect: 'accept',
+            run: () =>
+                run({
+                    'check_prose.ts':
+                        '// forbids ' + 'Date' + '.now()\nconst s = "new ' + 'Date()";\n',
+                }),
+        },
+        {
+            name: 'accepts a gate that routes through the seam',
+            expect: 'accept',
+            run: () => run({ 'check_ok.ts': CLEAN_GATE }),
+        },
+        {
+            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: 'lint_deterministic_time',
+            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('❌  gate script(s) read the wall clock directly:\n\n');
+        for (const f of findings) {
+            const why =
+                f.kind === 'bare-marker'
+                    ? `\`${MARKER}\` with no reason`
+                    : `raw \`${f.construct}\``;
+            process.stdout.write(`  ${f.file}:${String(f.line)} — ${why}\n`);
+        }
+        process.stdout.write(
+            `\nA verdict that depends on the hour it ran is not reproducible from the\n` +
+                `commit. Route through \`asOf()\` in ${SEAM} — it resolves --as-of, AC_AS_OF,\n` +
+                `the commit date under CI, and the wall clock with an explicit WARN.\n` +
+                `If real elapsed time IS the subject, say so on the line:\n` +
+                `  // ${MARKER} <reason>\n`,
+        );
+        return 1;
+    }
+
+    if (!quiet) {
+        process.stdout.write(
+            `✅  no raw wall-clock read in ${String(scanned)} gate script(s) under ${SCAN_DIR}/.\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_DIR, GATE_PREFIXES, SEAM, MARKER };