@event4u/agent-config 9.9.0 → 9.11.0

package/src/scripts/check_gate_coverage.ts

@@ -0,0 +1,299 @@
+#!/usr/bin/env tsx
+/**
+ * Meta-gate: verify that the repo's gates actually inspect something.
+ *
+ * A gate that scans nothing exits 0 and certifies coverage that does not exist.
+ * That is strictly worse than having no gate, because the green is believed. On
+ * 2026-07-29 a sweep found three such gates in CI, each pointing at a tree
+ * emptied by the ADR-051 flat-`src/` migration; one of them printed the literal
+ * count `0` in its own output for as long as it was broken.
+ *
+ * This guard reads `src/config/gate-coverage.yml`, runs each listed gate with the
+ * CI-identical arguments declared there, reads the `scanned: <N>` line the gate
+ * emits, and fails when N falls below the declared floor.
+ *
+ * Three design rules, each traceable to a concrete failure — see the manifest
+ * header for the full rationale:
+ *   1. Gates emit a machine-readable count; the guard never parses human output.
+ *   2. Invocations mirror CI exactly (a bare probe produced a false alarm during
+ *      the sweep).
+ *   3. The check is a baseline floor, not `> 0` (428 → 3 is also a collapse).
+ *
+ * Self-honesty: this guard must not become the thing it catches. It fails when
+ * the manifest is empty or unreadable, and it REPORTS `pending` gates (listed but
+ * not yet emitting a count) instead of skipping them silently.
+ *
+ * CLI:
+ *   ./scripts-run src/scripts/check_gate_coverage            # enforce
+ *   ./scripts-run src/scripts/check_gate_coverage --list     # show the manifest
+ *   ./scripts-run src/scripts/check_gate_coverage --format json
+ *
+ * Exit codes: 0 all enforced gates cleared their floor · 1 a gate is blind,
+ * collapsed, or silent · 2 the manifest itself is missing/empty/malformed.
+ */
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import yaml from 'js-yaml';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+const MANIFEST = path.join(REPO_ROOT, 'src/config/gate-coverage.yml');
+
+/** The one line a gate must emit. Deliberately narrow: no format guessing. */
+const SCANNED_RE = /^\s*scanned:\s*(\d+)\s*$/m;
+
+export interface GateSpec {
+  id: string;
+  argv: string[];
+  min_scanned: number;
+  corpus: string;
+  status: 'enforced' | 'pending';
+  /**
+   * Exit code meaning "my prerequisite is absent, so I inspected nothing" — e.g.
+   * check_site_links exits 2 when the site is unbuilt or stale. Without this the
+   * guard reads that as `silent` and fails, which would make it red on every machine
+   * lacking a build artefact: a gate that blocks for an environmental reason teaches
+   * people to ignore it, which is worse than no gate. Reported as `unavailable`
+   * rather than skipped, so the partial coverage stays visible — the same reason
+   * `pending` is reported instead of hidden.
+   */
+  unavailable_exit?: number;
+  note?: string;
+}
+
+export type Verdict = 'ok' | 'below_floor' | 'silent' | 'crashed' | 'pending' | 'unavailable';
+
+export interface GateResult {
+  id: string;
+  status: GateSpec['status'];
+  verdict: Verdict;
+  scanned: number | null;
+  min_scanned: number;
+  message: string;
+}
+
+function _require_int(v: unknown, id: string, i: number): number {
+  const n = Number(v);
+  if (!Number.isInteger(n)) {
+    throw new Error(`gates[${String(i)}] (${id}): unavailable_exit must be an integer exit code`);
+  }
+  return n;
+}
+
+/** Parse + validate the manifest. Throws on anything that would make the guard
+ * silently vacuous — an empty gate list is a hard error, not an empty pass. */
+export function load_manifest(file = MANIFEST): GateSpec[] {
+  if (!fs.existsSync(file)) {
+    throw new Error(`manifest not found: ${path.relative(REPO_ROOT, file)}`);
+  }
+  const doc = yaml.load(fs.readFileSync(file, 'utf-8')) as { gates?: unknown[] };
+  const raw = Array.isArray(doc?.gates) ? doc.gates : [];
+  if (raw.length === 0) {
+    throw new Error('manifest declares zero gates — a coverage guard over an empty set is vacuous');
+  }
+  return raw.map((entry, i) => {
+    const e = entry as Record<string, unknown>;
+    const id = String(e['id'] ?? '');
+    if (id === '') throw new Error(`gates[${i}]: missing id`);
+    const min = Number(e['min_scanned']);
+    if (!Number.isInteger(min) || min < 0) {
+      throw new Error(`gates[${i}] (${id}): min_scanned must be a non-negative integer`);
+    }
+    const status = String(e['status'] ?? 'enforced');
+    if (status !== 'enforced' && status !== 'pending') {
+      throw new Error(`gates[${i}] (${id}): status must be 'enforced' or 'pending'`);
+    }
+    return {
+      id,
+      argv: Array.isArray(e['argv']) ? e['argv'].map(String) : [],
+      min_scanned: min,
+      corpus: String(e['corpus'] ?? ''),
+      status,
+      ...(e['unavailable_exit'] === undefined
+        ? {}
+        : { unavailable_exit: _require_int(e['unavailable_exit'], id, i) }),
+      ...(e['note'] === undefined ? {} : { note: String(e['note']) }),
+    };
+  });
+}
+
+/** Extract the contract line. Returns null when the gate emitted no count. */
+export function parse_scanned(output: string): number | null {
+  const m = SCANNED_RE.exec(output);
+  return m === null ? null : Number(m[1]);
+}
+
+/** Classify one gate's run against its declared floor. Pure — testable without
+ * spawning anything. */
+export function classify(
+  spec: GateSpec,
+  scanned: number | null,
+  crashed: boolean,
+  exit_code?: number | null,
+): GateResult {
+  const base = { id: spec.id, status: spec.status, scanned, min_scanned: spec.min_scanned };
+  if (spec.status === 'pending') {
+    return {
+      ...base,
+      verdict: 'pending',
+      message:
+        scanned === null
+          ? `not yet emitting 'scanned:' — listed as pending, NOT enforced (coverage gap is visible, not hidden)`
+          : `reports ${String(scanned)}; floor ${String(spec.min_scanned)} not enforced while pending`,
+    };
+  }
+  if (crashed) {
+    return { ...base, verdict: 'crashed', message: 'gate could not be executed' };
+  }
+  if (
+    spec.unavailable_exit !== undefined &&
+    exit_code !== undefined &&
+    exit_code !== null &&
+    exit_code === spec.unavailable_exit
+  ) {
+    return {
+      ...base,
+      verdict: 'unavailable',
+      message:
+        `exited ${String(exit_code)} — prerequisite absent, nothing inspected. ` +
+        `Coverage unverified here; CI is where this gate has its inputs`,
+    };
+  }
+  if (scanned === null) {
+    return {
+      ...base,
+      verdict: 'silent',
+      message: `emitted no 'scanned: <N>' line — an enforced gate must report what it inspected`,
+    };
+  }
+  if (scanned < spec.min_scanned) {
+    return {
+      ...base,
+      verdict: 'below_floor',
+      message:
+        `scanned ${String(scanned)}, floor ${String(spec.min_scanned)} (${spec.corpus}) — ` +
+        `a gate inspecting this little cannot certify the corpus`,
+    };
+  }
+  return { ...base, verdict: 'ok', message: `scanned ${String(scanned)} ≥ ${String(spec.min_scanned)}` };
+}
+
+function run_gate(spec: GateSpec): { scanned: number | null; crashed: boolean; exit_code: number | null } {
+  const runner = path.join(REPO_ROOT, 'scripts-run');
+  const r = spawnSync(runner, [`src/scripts/${spec.id}`, ...spec.argv], {
+    cwd: REPO_ROOT,
+    encoding: 'utf8',
+  });
+  if (r.error !== undefined || r.status === null) return { scanned: null, crashed: true, exit_code: null };
+  // A gate may legitimately exit non-zero (it found real violations) and still
+  // have scanned plenty — coverage and verdict are different questions.
+  return { scanned: parse_scanned(`${r.stdout}\n${r.stderr}`), crashed: false, exit_code: r.status };
+}
+
+const ICON: Record<Verdict, string> = {
+  ok: '✅',
+  below_floor: '❌',
+  silent: '❌',
+  crashed: '❌',
+  pending: '⚠️',
+  unavailable: '⚠️',
+};
+
+export function main(argv: readonly string[]): number {
+  const wantJson = argv.includes('--format') && argv[argv.indexOf('--format') + 1] === 'json';
+  const listOnly = argv.includes('--list');
+
+  let specs: GateSpec[];
+  try {
+    specs = load_manifest();
+  } catch (e) {
+    process.stderr.write(`❌  gate-coverage manifest: ${(e as Error).message}\n`);
+    return 2;
+  }
+
+  if (listOnly) {
+    for (const s of specs) {
+      process.stdout.write(
+        `  ${s.status === 'enforced' ? '[enforced]' : '[pending] '} ${s.id} ` +
+          `argv=[${s.argv.join(' ')}] floor=${String(s.min_scanned)}\n`,
+      );
+    }
+    process.stdout.write(`scanned: ${String(specs.length)}\n`);
+    return 0;
+  }
+
+  const results = specs.map((s) => {
+    if (spec_is_pending(s)) {
+      const { scanned, crashed } = probe_pending(s);
+      return classify(s, scanned, crashed);
+    }
+    const { scanned, crashed, exit_code } = run_gate(s);
+    return classify(s, scanned, crashed, exit_code);
+  });
+
+  if (wantJson) {
+    process.stdout.write(`${JSON.stringify({ generated_by: 'check_gate_coverage', results }, null, 2)}\n`);
+  } else {
+    for (const r of results) {
+      process.stdout.write(`  ${ICON[r.verdict]} ${r.id}: ${r.message}\n`);
+    }
+  }
+
+  const failed = results.filter((r) => r.verdict === 'below_floor' || r.verdict === 'silent' || r.verdict === 'crashed');
+  const pending = results.filter((r) => r.verdict === 'pending');
+  const unavailable = results.filter((r) => r.verdict === 'unavailable');
+
+  // The guard reports its OWN coverage. Hiding a pending gate behind a green
+  // summary is exactly the failure mode this file exists to prevent.
+  process.stdout.write(
+    `\nscanned: ${String(results.length)}\n` +
+      `  enforced ${String(results.length - pending.length)} · pending ${String(pending.length)} · ` +
+      `unavailable ${String(unavailable.length)} · failing ${String(failed.length)}\n`,
+  );
+  if (unavailable.length > 0) {
+    process.stdout.write(
+      `⚠️  ${String(unavailable.length)} gate(s) could not run here (prerequisite absent) — ` +
+        `their coverage is unverified locally, not proven.\n`,
+    );
+  }
+  if (pending.length > 0) {
+    process.stdout.write(
+      `⚠️  ${String(pending.length)} gate(s) are listed but NOT enforced — this guard's coverage is partial by declaration.\n`,
+    );
+  }
+  if (failed.length > 0) {
+    process.stdout.write(`❌  ${String(failed.length)} gate(s) failed the coverage floor.\n`);
+    return 1;
+  }
+  process.stdout.write('✅  every enforced gate cleared its coverage floor.\n');
+  return 0;
+}
+
+function spec_is_pending(s: GateSpec): boolean {
+  return s.status === 'pending';
+}
+
+/** Pending gates are still probed (so the report shows what they currently do),
+ * but their count never fails the build. */
+function probe_pending(s: GateSpec): { scanned: number | null; crashed: boolean } {
+  return run_gate(s);
+}
+
+function _isCliEntry(): boolean {
+  if (process.argv[1] === undefined) return false;
+  const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+  if (argvUrl === import.meta.url) return true;
+  try {
+    return pathToFileURL(fs.realpathSync(path.resolve(process.argv[1]))).href === import.meta.url;
+  } catch {
+    return false;
+  }
+}
+
+if (_isCliEntry()) {
+  process.exit(main(process.argv.slice(2)));
+}

package/src/scripts/check_iron_law_prominence.ts

@@ -28,6 +28,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { assertScanned } from './_lib/scan_scope.js';
+
 const HEADING_RE = /^(#{1,6})\s+(.+?)\s*$/;
 const IRON_LAW_RE = /\biron\s+laws?\b/i;
 const FENCE_RE = /^\s*```/;
@@ -247,7 +249,11 @@ function parse_args(argv: readonly string[]): Args {
         i++;
     }
     return {
-        paths: paths.length ? paths : ['.agent-src.uncondensed/rules'],
+        // ADR-051 moved rule authoring to `src/rules`. Until 2026-07-29 this
+        // default still named the retired container, so both CI call sites
+        // (consistency.yml + ci-fast.yml) resolved 0 targets and printed
+        // "✅ Iron Law prominence clean (0 file(s) scanned)" forever.
+        paths: paths.length ? paths : ['src/rules'],
         format,
         quiet,
     };
@@ -257,6 +263,21 @@ export function main(argv?: readonly string[]): number {
     const args = parse_args(argv ?? process.argv.slice(2));
 
     const targets = _resolve_targets(args.paths);
+
+    // Scope assertion: 0 targets means the root moved, not that the tree is
+    // clean. Without this the gate reported success while reading nothing.
+    try {
+        assertScanned({
+            gate: 'check_iron_law_prominence',
+            scanned: targets.length,
+            units: 'rule file(s)',
+            roots: args.paths,
+        });
+    } catch (exc) {
+        process.stderr.write(`❌  ${exc instanceof Error ? exc.message : String(exc)}\n`);
+        return 2;
+    }
+
     const all_violations: Violation[] = [];
     for (const p of targets) {
         if (!_exists(p)) {

package/src/scripts/check_no_new_legacy_path.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env tsx
 /**
- * Regression guard: no NEW `.agent-src.uncondensed/` references in `src/`.
+ * Regression guard: no NEW dead-root references in `src/` or `tests/`.
  *
  * Ported from the retired Python `src/scripts/check_no_new_legacy_path.py` (ADR-200,
  * Phase 4 / Wave 4c). The CLI contract is pinned — `--base`
@@ -104,12 +104,22 @@ function find_offenders(diffText: string, twinCheck: TwinCheck = _is_faithful_tw
             continue;
         }
         if (line.startsWith('+') && !line.startsWith('+++')) {
-            // src/-scoped: a full diff (e.g. `gh pr diff`) carries every path;
-            // only added lines under src/ (minus the exempt detectors and
-            // faithful TS twins) count.
+            // Scoped to src/ + tests/: a full diff (e.g. `gh pr diff`) carries
+            // every path; only added lines under those roots (minus the exempt
+            // detectors and faithful TS twins) count.
+            //
+            // tests/ added 2026-07-29. Four separate tests were found pinning the
+            // dead root — two via fixture paths, one via a `resolve_entry`
+            // expectation, one asserting that a missing root exits 0 — and each
+            // kept a gate's blindness green because test and implementation agreed
+            // on a tree reality had abandoned. A FULL-tree lint over tests/ is the
+            // wrong shape (44 files / 213 hits, most of them legitimate: the
+            // legacy detectors' own tests, validator_ignore substrings, and
+            // synthetic fixtures under tmpdir()). Diff-scoping is what makes this
+            // tractable — existing debt stays, growth stops, no allowlist.
             if (
                 curFile &&
-                curFile.startsWith('src/') &&
+                (curFile.startsWith('src/') || curFile.startsWith('tests/')) &&
                 !EXEMPT.has(curFile) &&
                 line.includes(LEGACY) &&
                 !twinCheck(curFile)
@@ -135,7 +145,7 @@ function main(): number {
         // additions (robust locally and where the working tree is the branch tip).
         let proc: ReturnType<typeof spawnSync>;
         try {
-            proc = spawnSync('git', ['diff', base, '--', 'src/'], {
+            proc = spawnSync('git', ['diff', base, '--', 'src/', 'tests/'], {
                 encoding: 'utf-8',
             });
         } catch (exc) {

package/src/scripts/check_no_roadmap_refs.ts

@@ -18,7 +18,7 @@
  * `agents/roadmaps/skipped/`). Forbidden: specific `*.md` files inside those
  * directories.
  *
- * Contract: .agent-src.uncondensed/rules/no-roadmap-references.md
+ * Contract: src/rules/no-roadmap-references.md
  *
  * Exit codes: 0 = clean, 1 = violations, 3 = internal error.
  */
@@ -34,13 +34,20 @@ const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 
 // Stable artefact trees — every `*.md` below MUST be free of roadmap-file
 // citations. Directory mentions stay allowed (the regex below excludes them).
+// Retargeted 2026-07-29: these six pointed at the pre-relocation source tree,
+// emptied by the ADR-051 flat-`src/` migration. The gate kept enforcing the rule
+// for `docs/` while the rule + skill layer — the layer `no-roadmap-references` is
+// actually about — went unscanned, and reported green. No violation had slipped
+// through yet (verified), so this closes a latent gap rather than a live breach.
+// (Phrased without the dead path literal on purpose: `check_no_new_legacy_path`
+// guards against those accumulating, and this comment tripped it.)
 const STABLE_TREES = [
-    '.agent-src.uncondensed/rules',
-    '.agent-src.uncondensed/skills',
-    '.agent-src.uncondensed/commands',
-    '.agent-src.uncondensed/contexts',
-    '.agent-src.uncondensed/templates',
-    '.agent-src.uncondensed/personas',
+    'src/rules',
+    'src/skills',
+    'src/agent-src/commands',
+    'src/agent-src/contexts',
+    'src/agent-src/templates',
+    'src/agent-src/personas',
     'agents/settings/contexts',
     'docs/guidelines',
     'docs/contracts',
@@ -69,7 +76,7 @@ const ROADMAP_FILE_RE =
 // documentation purposes — the rule itself, the companion CI script docs,
 // and the contract doc that names the rule.
 const SELF_DOCUMENTING_ALLOWLIST: ReadonlySet<string> = new Set([
-    '.agent-src.uncondensed/rules/no-roadmap-references.md',
+    'src/rules/no-roadmap-references.md',
     'docs/guidelines/agent-infra/no-roadmap-references.md',
 ]);
 
@@ -172,9 +179,15 @@ function _collect_targets(root: string): string[] {
 
 function scan(root: string): Violation[] {
     const out: Violation[] = [];
+    let scanned = 0;
     for (const p of _collect_targets(root)) {
+        scanned += 1;
         out.push(..._scan_file(p, root));
     }
+    // Gate-coverage contract (src/config/gate-coverage.yml): report what was
+    // actually inspected, so a future dead root fails `check_gate_coverage`
+    // instead of printing a green "no violations" over an empty set.
+    process.stdout.write(`scanned: ${String(scanned)}\n`);
     return out;
 }
 
@@ -190,7 +203,7 @@ function format_text(violations: Violation[]): string {
     }
     lines.push(
         '\nPromote the durable conclusion to agents/settings/contexts/ and cite that ' +
-            'instead. See .agent-src.uncondensed/rules/no-roadmap-references.md.',
+            'instead. See src/rules/no-roadmap-references.md.',
     );
     return lines.join('\n');
 }

package/src/scripts/check_originality_freshness.ts

@@ -0,0 +1,167 @@
+#!/usr/bin/env tsx
+/**
+ * Freshness check for the committed originality report.
+ *
+ * `agents/reports/originality.{json,md}` is a committed artefact that nothing
+ * regenerates on a schedule, and the report itself "blocks NOTHING on its own" —
+ * so it can drift silently. It did: on 2026-07-31 the committed copy read 507
+ * artifacts while the identical corpus produced 508, meaning it predated an
+ * artefact and nobody noticed.
+ *
+ * This check regenerates the report, compares it against the committed bytes,
+ * restores the committed bytes either way, and **always exits 0**. Warning, not
+ * a gate — the report's non-blocking character is deliberate, and turning a
+ * stale doc into a red build would be a worse trade than a visible warning.
+ *
+ * Restoring is what keeps it safe to run inside a pipeline: the working tree is
+ * byte-identical afterwards, so no later step sees a spurious diff.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { main as runOriginality } from './lint_originality.js';
+
+const REPO_ROOT = path.resolve(path.dirname(new URL(import.meta.url).pathname), '..', '..');
+export const REPORTS = [
+    path.join(REPO_ROOT, 'agents', 'reports', 'originality.json'),
+    path.join(REPO_ROOT, 'agents', 'reports', 'originality.md'),
+];
+
+/** `null` for a report that is not committed yet — absence is not drift. */
+function snapshot(files: readonly string[]): Map<string, Buffer | null> {
+    const out = new Map<string, Buffer | null>();
+    for (const f of files) {
+        try {
+            out.set(f, fs.readFileSync(f));
+        } catch {
+            out.set(f, null);
+        }
+    }
+    return out;
+}
+
+/**
+ * Put the committed bytes back. Best-effort per file and never throwing: this
+ * check runs inside pipelines, so a restore failure (read-only mount, a
+ * concurrent writer) must not become the exception that fails the build for an
+ * advisory. A file it could not restore is named loudly instead — that is the
+ * one case where the tree is left dirty, and the reader has to know.
+ */
+function restore(before: Map<string, Buffer | null>): void {
+    for (const [f, buf] of before) {
+        try {
+            if (buf === null) {
+                fs.rmSync(f, { force: true });
+            } else {
+                fs.writeFileSync(f, buf);
+            }
+        } catch (err) {
+            const why = err instanceof Error ? err.message : String(err);
+            process.stdout.write(
+                `⚠️  could not restore ${f} after the freshness sweep: ${why}\n` +
+                    '    The working tree now holds a REGENERATED report. Restore it with\n' +
+                    `    \`git checkout -- ${f}\` if that was not intended.\n`,
+            );
+        }
+    }
+}
+
+/** Default regeneration: the real sweep, which writes into `REPORTS`. */
+function regenerateReports(): void {
+    runOriginality(['--quiet']);
+}
+
+/**
+ * `regenerate` is injectable for one reason: a test that exercised the drift
+ * path against the real reports would have to write a stale version into a
+ * TRACKED file, and vitest runs suites in parallel — any sibling test asserting
+ * "the working tree is clean" would see that transient write and fail. (It did:
+ * `backfill_model_tier`'s dry-run purity check caught exactly that.) With the
+ * hook, drift and restore behaviour is provable entirely in temp space, and the
+ * real wiring stays covered by the fresh-path test, which is tree-neutral
+ * because rewriting identical bytes is invisible to git.
+ */
+export function checkFreshness(
+    files: readonly string[] = REPORTS,
+    regenerate: () => void = regenerateReports,
+): {
+    drifted: string[];
+    missing: string[];
+} {
+    const before = snapshot(files);
+    try {
+        regenerate();
+    } catch {
+        // A sweep that cannot run is not a drift signal; leave the tree as found.
+        restore(before);
+        return { drifted: [], missing: [] };
+    }
+    const drifted: string[] = [];
+    const missing: string[] = [];
+    for (const [f, buf] of before) {
+        let now: Buffer | null;
+        try {
+            now = fs.readFileSync(f);
+        } catch {
+            now = null;
+        }
+        if (buf === null) {
+            if (now !== null) missing.push(f);
+            continue;
+        }
+        if (now === null || !now.equals(buf)) drifted.push(f);
+    }
+    restore(before);
+    return { drifted, missing };
+}
+
+/**
+ * LOCAL-ONLY, established empirically. On a CI runner the sweep produced
+ * different bytes than the committed report even with a byte-identical corpus
+ * (verified: 508 members on both this branch and `main`, report fresh locally,
+ * both files reported stale in `Node Tests`). Something in the CI environment
+ * moves the output, and chasing it would mean designing a reproducibility gate
+ * for a report that "blocks nothing on its own" — a bad trade for a warning.
+ *
+ * So this stays a developer-side surface. A freshness warning that fires on
+ * every PR regardless of staleness is exactly the never-turns-off warning this
+ * check was written to remove.
+ */
+export function main(): number {
+    if (process.env['CI'] !== undefined && process.env['CI'] !== '') {
+        process.stdout.write(
+            'ℹ️  originality freshness: skipped on CI — the sweep is not byte-reproducible\n' +
+                '    across environments, so a CI warning here would fire regardless of\n' +
+                '    staleness. Run it locally before quoting the report numbers.\n',
+        );
+        return 0;
+    }
+    const { drifted, missing } = checkFreshness();
+    const rel = (f: string): string => path.relative(REPO_ROOT, f);
+
+    if (missing.length > 0) {
+        process.stdout.write(
+            `⚠️  originality report is not committed yet: ${missing.map(rel).join(', ')}\n` +
+                '    Run `./scripts-run src/scripts/lint_originality` and commit the result.\n',
+        );
+    }
+    if (drifted.length === 0 && missing.length === 0) {
+        process.stdout.write('✅  originality report is fresh.\n');
+        return 0;
+    }
+    if (drifted.length > 0) {
+        process.stdout.write(
+            `⚠️  originality report is STALE: ${drifted.map(rel).join(', ')}\n` +
+                '    Regenerating from the current corpus produces different bytes, so the\n' +
+                '    committed numbers describe an older corpus. Not a build failure — this\n' +
+                '    report blocks nothing on its own — but the counts should not be quoted\n' +
+                '    until refreshed: `./scripts-run src/scripts/lint_originality`.\n',
+        );
+    }
+    // Always 0: this is a warning surface by design.
+    return 0;
+}
+
+if (process.argv[1] !== undefined && import.meta.url === `file://${process.argv[1]}`) {
+    process.exit(main());
+}