@event4u/agent-config 8.4.1 → 8.6.0

package/src/scripts/bench_rtk_savings.ts

@@ -2,8 +2,8 @@
 /**
  * Measure rtk's token savings on a fixed corpus of verbose CLI invocations.
  *
- * TypeScript twin of `src/scripts/bench_rtk_savings.py` (ADR-200 py2ts
- * Phase 8 / Wave 8d). The CLI contract mirrors the Python original
+ * Ported from the retired Python `src/scripts/bench_rtk_savings.py` (ADR-200 py2ts
+ * Phase 8 / Wave 8d). The CLI contract mirrors the retired Python implementation
  * EXACTLY — `--corpus`, `--out`, `--quiet`, exit codes, stdout/stderr
  * split, the one-line headline summary, and byte-identical written
  * reports (`json.dumps(indent=2, ensure_ascii=False)` + trailing
@@ -53,7 +53,7 @@ type Dict = Record<string, unknown>;
  * Marker for a value that is a Python `float`. CPython's `json.dumps`
  * renders a float `0.0` as `0.0` (not `0`); JS numbers lose that
  * distinction. Wrapping the report's float fields keeps the written
- * JSON byte-identical with the Python original.
+ * JSON byte-identical with the retired Python implementation.
  */
 class PyFloat {
     constructor(readonly value: number) {}
@@ -366,7 +366,7 @@ export function run(corpus_path: string = DEFAULT_CORPUS, out_dir: string = DEFA
 
 /**
  * Mirror Path.relative_to(REPO_ROOT) — raises (ValueError-equivalent) when
- * the path is not under REPO_ROOT, matching the Python original's behaviour.
+ * the path is not under REPO_ROOT, matching the retired Python implementation's behaviour.
  */
 function _relativeToRepo(p: string): string {
     const resolvedRoot = path.resolve(REPO_ROOT);

package/src/scripts/bench_run.ts

@@ -2,8 +2,8 @@
 /**
  * Bench orchestrator — step-4 measurement-and-benchmark Phase 2.
  *
- * TypeScript twin of `src/scripts/bench_run.py` (ADR-200, Phase 8 /
- * Wave 8d). The CLI contract mirrors the Python original EXACTLY — same
+ * Ported from the retired Python `src/scripts/bench_run.py` (ADR-200, Phase 8 /
+ * Wave 8d). The CLI contract pins the historical contract exactly — same
  * flags, exit codes, stdout/stderr split, byte-identical headline / Markdown
  * stdout and byte-identical written report JSON
  * (`json.dumps(indent=2) + "\n"`). No behaviour changes — latent Python
@@ -23,7 +23,7 @@
  * `ai_council.clients` module (it carries no legacy source-tree literal, so
  * ADR-051 does not require porting it in this wave). The `--telegraph-dry-run`
  * path is fully self-contained; the live path degrades to the same "cannot
- * build Anthropic client" exit-2 surface the Python original produces when the
+ * build Anthropic client" exit-2 surface the retired Python implementation produces when the
  * client can't be built. Flagged as a divergence candidate.
  */
 import * as fs from 'node:fs';
@@ -390,7 +390,7 @@ function _run_telegraph(args: Args): number {
 /**
  * Live-API telegraph path. Builds the Anthropic client; on any failure prints
  * the same "cannot build Anthropic client" message and returns 2, mirroring
- * the Python original's `try/except Exception` guard. Because the
+ * the retired Python implementation's `try/except Exception` guard. Because the
  * `ai_council.clients` twin is not yet present, this currently always takes
  * the failure branch (flagged divergence — the live happy path is unreachable
  * until that module is ported).

package/src/scripts/bench_runner.ts

@@ -2,7 +2,7 @@
 /**
  * Bench runner for the eval corpora — step-4 measurement-and-benchmark Phase 1.
  *
- * TypeScript twin of `src/scripts/bench_runner.py` (ADR-200 Python→TS
+ * Ported from the retired Python `src/scripts/bench_runner.py` (ADR-200 Python→TS
  * migration, Phase 8 / Wave 8d). Mirrors the CLI contract EXACTLY: flags
  * (`--corpus`, `--top-k`, `--json`), exit codes (0 PASS / 1 FAIL / 2 corpus
  * not found), byte-identical stdout/stderr, and byte-identical JSON

package/src/scripts/build_cloud_bundle.ts

@@ -2,7 +2,7 @@
 /**
  * build_cloud_bundle.ts — package skills as Anthropic Skills ZIP bundles.
  *
- * TypeScript twin of `src/scripts/build_cloud_bundle.py` (ADR-200 —
+ * Ported from the retired Python `src/scripts/build_cloud_bundle.py` (ADR-200 —
  * Python→TS migration, Phase 8 / Wave 8b). The CLI contract is mirrored
  * EXACTLY — the mutually-exclusive `--skill` / `--all` / `--check` flags,
  * `--out` / `--strict-budget` / `--clean`, exit codes, the stdout/stderr
@@ -12,7 +12,7 @@
  * CONTENTS written into each ZIP are byte-identical.
  *
  * Imports the `audit_cloud_compatibility` twin (the SAME `scan` /
- * `detect_cloud_marker` surfaces the Python original imports) for tier
+ * `detect_cloud_marker` surfaces the retired Python implementation imports) for tier
  * classification.
  *
  * DIVERGENCE CANDIDATE (documented under the ADR-200 process):
@@ -25,7 +25,7 @@
  * compares decompressed entry maps (name → bytes), the manifest JSON, and the
  * console output — not the raw archive bytes.
  *
- * Note on error semantics: the Python original raises bare
+ * Note on error semantics: the retired Python implementation raises bare
  * `SystemExit("❌  …")` for budget / source / T3-H failures. A string
  * SystemExit prints the message to stderr and exits with code 1 (NOT the
  * 2/3/4/5 codes named in the docstring, which never fire). This twin

package/src/scripts/build_discovery_manifest.ts

@@ -2,8 +2,8 @@
 /**
  * Release-time discovery scanner — produces discovery-manifest.json.
  *
- * TypeScript twin of `src/scripts/build_discovery_manifest.py` (ADR-200,
- * Phase 5). The CLI contract is mirrored EXACTLY — every flag (`--write`,
+ * Ported from the retired Python `src/scripts/build_discovery_manifest.py` (ADR-200,
+ * Phase 5). The CLI contract is pinned — every flag (`--write`,
  * `--out`, `--summary`, `--deprecation-report`, `--trust-report`,
  * `--orphan-report`, `--workspaces-json`, `--packs-json`, `--strict`,
  * `--quiet`), the CI-strict env override, exit codes, the stdout/stderr
@@ -20,18 +20,17 @@
  *
  * Imports the `_lib/agent_src` twin for the artefact walk and the
  * `validate_frontmatter` twin for frontmatter parse + schema-default
- * injection (the SAME functions the Python original imports). The checksum
+ * injection (the SAME functions the retired Python implementation imports). The checksum
  * primitive `_artefact_checksum` / `_CATEGORY_SCHEMA` / `_FRONTMATTER_RE` are
  * replicated here EXACTLY and kept in agreement with the inline copy in
  * `check_artefact_checksums.ts`.
  *
- * No behaviour changes — latent Python quirks replicated.
+ * Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour.
  *
  * DIVERGENCE CANDIDATE (documented under the ADR-200 process):
- * `_scanner_version()` in the Python original hashes the scanner file's OWN
- * bytes (`Path(__file__).read_bytes()`). For the TS-built manifest to remain
- * byte-identical to the Python-built one — and to keep passing the
- * Python-rebuild diff in `validate_discovery_manifest.py` — this twin hashes
+ * `_scanner_version()` in the retired Python implementation hashes the scanner file's OWN
+ * bytes (`Path(__file__).read_bytes()`). During the migration the TS-built
+ * manifest had to match the Python-built one byte-for-byte, so this port hashes
  * the SIBLING `build_discovery_manifest.py` bytes (falling back to its own
  * `.ts` bytes only when the `.py` is absent, e.g. after the same-PR deletion).
  * Until the `.py` is deleted the manifest is byte-identical; after deletion
@@ -68,7 +67,7 @@ const _HERE = fileURLToPath(import.meta.url);
 
 // --- Module-level path config (mutable to mirror Python monkeypatch seam) ----
 //
-// The Python original derives ROOT / SRC / VOCAB_DIR / DEFAULT_* as
+// the retired Python implementation derives ROOT / SRC / VOCAB_DIR / DEFAULT_* as
 // module-level constants and `tests/test_build_discovery_manifest.py`
 // reassigns `mod.ROOT`, `mod.SRC`, `mod.VOCAB_DIR`, `mod.artefact_roots`, and
 // `mod.resolve_logical` via monkeypatch. To preserve that injection surface,
@@ -314,11 +313,10 @@ function _vocab(): [VocabEntry[], VocabEntry[], Record<string, string>] {
 }
 
 function _scanner_version(): string {
-    // DIVERGENCE CANDIDATE: hash the SIBLING build_discovery_manifest.py bytes
-    // so the manifest stays byte-identical to the Python-built one (and keeps
-    // passing the Python-rebuild diff in validate_discovery_manifest.py). Fall
-    // back to this twin's own bytes once the .py is deleted (same-PR; the
-    // manifest is regenerated then anyway).
+    // Scanner version = hash of this file's own bytes (the .py-sibling branch
+    // below is inert since the teardown — no sibling exists; kept because the
+    // manifest checksum gates pin the current output and removing the branch
+    // is a behaviour-neutral cleanup for its own change).
     const pyPath = path.join(path.dirname(_HERE), 'build_discovery_manifest.py');
     const target = _isFile(pyPath) ? pyPath : _HERE;
     const h = crypto.createHash('sha256').update(fs.readFileSync(target)).digest('hex');
@@ -827,7 +825,7 @@ function _cmpStr(a: string, b: string): number {
  * 0, "" and the EMPTY array/object — distinct from JS, where `[]`/`{}` are
  * truthy. Used at the optional-field emission sites in `_build` so an empty
  * `optional_packs` / `example_roles` / `suggests` is omitted exactly as the
- * Python original omits it.
+ * retired Python implementation omitted it.
  */
 function _pyTruthy(v: Json): boolean {
     if (v === undefined || v === null || v === false || v === '' || v === 0) {

package/src/scripts/build_linear_digest.ts

@@ -2,7 +2,7 @@
 /**
  * build_linear_digest.ts — build the Linear AI rules digest.
  *
- * TypeScript twin of `src/scripts/build_linear_digest.py` (ADR-200 —
+ * Ported from the retired Python `src/scripts/build_linear_digest.py` (ADR-200 —
  * Python→TS migration, Phase 8 / Wave 8b). The CLI contract is mirrored
  * EXACTLY — the `--max-bytes` / `--out-dir` / `--strict-missing` flags,
  * exit codes (0 ok · 2 over-budget · 3 missing rule file · 4
@@ -12,7 +12,7 @@
  * Concatenates a curated set of cloud-safe rules from `dist/agent-src/rules/`
  * into three Markdown files under `dist/linear/`.
  *
- * No behaviour changes — latent Python quirks replicated.
+ * Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour.
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';

package/src/scripts/build_mcp_registry_manifest.ts

@@ -2,8 +2,8 @@
 /**
  * Build `dist/mcp/registry-manifest.json` + the two rendered payloads.
  *
- * TypeScript twin of `src/scripts/build_mcp_registry_manifest.py` (ADR-200,
- * Phase 5). The CLI contract is mirrored EXACTLY — every flag (`--write`,
+ * Ported from the retired Python `src/scripts/build_mcp_registry_manifest.py` (ADR-200,
+ * Phase 5). The CLI contract is pinned — every flag (`--write`,
  * `--strict`, `--quiet`), exit codes (0 = ok; 2 = `--strict` drift without
  * `--write`; 1 = missing discovery prereq via SystemExit), the stdout/stderr
  * split, byte-identical messages, AND byte-identical generated output:
@@ -16,7 +16,7 @@
  * (`status`, `submitted_at`, `pr_url`, `last_verified`) is preserved from the
  * previous manifest.
  *
- * No behaviour changes — latent Python quirks replicated.
+ * Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour.
  *
  * Schema: `docs/contracts/mcp-registry-manifest.schema.json`
  */

package/src/scripts/build_proof.ts

@@ -83,6 +83,12 @@ function render(): string {
     }
     L.push('');
     L.push(`**${backed.length} backed claim(s)** — all evidence pointers resolve in CI.`);
+    L.push('');
+    L.push('Artefact counts in public prose (skills, commands, governed rules,');
+    L.push('guidelines, personas) are **generated from source and CI-drift-checked**:');
+    L.push('`update_counts.ts` writes the numbers, `check_artefact_count_messaging.ts`');
+    L.push('fails the build on any count-shaped prose mention that drifts from the');
+    L.push('source count — or on two different numbers for the same artefact kind.');
     if (unbacked.length > 0) {
         L.push('');
         L.push(`We also publish our **debt**: ${unbacked.length} claim(s) are logged as`);

package/src/scripts/build_rule_trigger_matrix.ts

@@ -2,7 +2,7 @@
 /**
  * Build agents/settings/contexts/rule-trigger-matrix.md.
  *
- * TypeScript twin of `src/scripts/build_rule_trigger_matrix.py` (ADR-200,
+ * Ported from the retired Python `src/scripts/build_rule_trigger_matrix.py` (ADR-200,
  * Phase 8 / Wave 8g). Mirrors the Python contract EXACTLY — same generated
  * markdown (byte-identical), same `CLASSIFICATION` table, same stdout
  * (`✅  Wrote …` line) + stderr (unclassified-rule warning) split, exit codes
@@ -340,7 +340,7 @@ function emit(): number {
     lines.push('');
     lines.push('**Source:** Phase 1 of `road-to-rule-hardening.md` (self-check audit) +');
     lines.push('Phase 1 of `road-to-context-layer-maturity.md` (`load_context:` inventory).');
-    lines.push('**Generated by:** `scripts/build_rule_trigger_matrix.py` — re-run after rule');
+    lines.push('**Generated by:** `src/scripts/build_rule_trigger_matrix.ts` — re-run after rule');
     lines.push("set changes. Manual classifications live in the script's `CLASSIFICATION`");
     lines.push('table; size and context-chain columns are derived from the rule files.');
     lines.push('');

package/src/scripts/capture_showcase_session.ts

@@ -2,7 +2,7 @@
 /**
  * capture_showcase_session.ts — wrap and measure showcase sessions.
  *
- * TypeScript twin of `src/scripts/capture_showcase_session.py` (ADR-200 —
+ * Ported from the retired Python `src/scripts/capture_showcase_session.py` (ADR-200 —
  * Python→TS migration, Phase 8 / Wave 8g). Mirrors the Python CLI contract
  * EXACTLY — the `capture` / `metrics` subcommands, every flag, exit codes
  * (0 success / 1 user error / 2 metric-gate pending), the stdout/stderr
@@ -24,8 +24,8 @@
  *
  * `commit_sha` (git HEAD) and `started`/`ended` (now) are non-deterministic;
  * golden parity supplies fixed timestamps via `--started`/`--ended` and
- * excludes `commit_sha`. No behaviour changes — latent Python quirks
- * replicated.
+ * excludes `commit_sha`. No behaviour changes — historical quirks
+ * preserved.
  */
 import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';

package/src/scripts/chat_history.ts

@@ -1,6 +1,6 @@
 // Persistent chat-history log for crash recovery.
 //
-// TypeScript twin of `src/scripts/chat_history.py` (ADR-200 — Python→TS
+// Ported from the retired Python `src/scripts/chat_history.py` (ADR-200 — Python→TS
 // migration). Public API mirrors the Python module exactly (snake_case kept
 // deliberately) so callers — including the MCP tools layer
 // (`src/scripts/mcp_server/tools.ts`) — depend on one source of truth.

package/src/scripts/check_always_budget.ts

@@ -3,7 +3,7 @@
  * Always-rule budget gate (Phases 7.1 + 7.4 of road-to-pr-34-followups,
  * extended by Phase 0.2 of road-to-structural-optimization).
  *
- * TypeScript twin of `src/scripts/check_always_budget.py` (ADR-200 —
+ * Ported from the retired Python `src/scripts/check_always_budget.py` (ADR-200 —
  * Python→TS migration, Phase 4 / Wave 4a). Mirrors the Python CLI
  * contract exactly: flags (`--quiet`, `--no-trend`), exit codes
  * (0 = pass/warn, 1 = fail, 3 = internal error), stdout/stderr split,

package/src/scripts/check_artefact_checksums.ts

@@ -2,14 +2,14 @@
 /**
  * Phase-6 checksum-stability gate (monorepo Phase 2, ADR-015).
  *
- * TypeScript twin of `src/scripts/check_artefact_checksums.py` (ADR-200,
- * Phase 4 / Wave 4c). The CLI contract is mirrored EXACTLY — `--manifest`
+ * Ported from the retired Python `src/scripts/check_artefact_checksums.py` (ADR-200,
+ * Phase 4 / Wave 4c). The CLI contract is pinned — `--manifest`
  * / `--quiet` flags, exit codes (0 match, 1 drift / malformed / missing),
  * stdout/stderr split, byte-identical messages, the same per-artefact
  * checksum recomputation and the same error truncation (first 20 + "… and N
- * more"). No behaviour changes — latent bugs replicated.
+ * more"). Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour.
  *
- * The Python original imports `_artefact_checksum` + `_CATEGORY_SCHEMA` from
+ * the retired Python implementation imports `_artefact_checksum` + `_CATEGORY_SCHEMA` from
  * `build_discovery_manifest.py` (which has no TS twin yet). To keep the TS
  * twin self-contained AND in lockstep, the checksum primitive is ported
  * inline here from `build_discovery_manifest._artefact_checksum` /

package/src/scripts/check_artefact_count_messaging.ts

@@ -0,0 +1,197 @@
+#!/usr/bin/env tsx
+/**
+ * Artefact-count messaging gate (road-to-truth-and-reference-hygiene Phase 1).
+ *
+ * Generalises `check_command_count_messaging.ts` (which stays wired as
+ * `task check-command-count` — its badge/browse anchors are required-check
+ * contract surface and are NOT removed here) from commands-only to every
+ * artefact kind: any count-shaped prose mention of skills / commands /
+ * governed rules / guidelines / personas on a flagship public surface must
+ * equal the canonical source count, and no surface may carry two DIFFERENT
+ * numbers for the same kind (the 150-vs-162-vs-166 failure mode that
+ * motivated this gate).
+ *
+ * Ownership split:
+ *   - `update_counts.ts` GENERATES the numbers into anchored positions
+ *     (badges + prose) and `--check`s those exact anchors.
+ *   - THIS gate SCANS the flagship surfaces for any count-shaped phrase —
+ *     anchored or not — so a hand-typed new sentence with a stale number
+ *     fails CI even though no anchor covers it yet.
+ *   - `check_command_count_messaging.ts` keeps the command-specific
+ *     active-vs-shim split checks.
+ *
+ * Scope: flagship surfaces only (SURFACES below). Dated census / analysis
+ * snapshots (SKILL_CENSUS, skills-taxonomy, positioning-evidence, …) carry
+ * point-in-time counts by design and are deliberately out of scope — the
+ * gate's charter is the surfaces a fresh reader treats as current.
+ *
+ * Exit codes: 0 clean · 1 drift or internal inconsistency.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { canonical_counts } from './check_command_count_messaging.js';
+import { count } from './update_counts.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+export const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+/** Flagship public prose surfaces (repo-relative). Missing files are skipped
+ * with a warning so a doc rename does not hard-break the gate. */
+export const SURFACES: readonly string[] = [
+    'README.md',
+    'AGENTS.md',
+    'llms.txt',
+    'docs/CLAIMS.md',
+    'docs/getting-started.md',
+    'docs/getting-started-by-role.md',
+    'docs/architecture.md',
+    'docs/command-flows.md',
+    'docs/governance-advantage.md',
+    'docs/featured-skills.md',
+    'docs/featured-commands.md',
+    'docs/proof.md',
+    'site/src/content/docs/index.mdx',
+    'site/src/content/docs/claims.md',
+];
+
+/** kind → canonical-count resolver. "governed rules" is the canonical total
+ * phrasing for rules; bare "N rules" is NOT matched (too many legitimate
+ * subset scopes: kernel rules, router rules, maintainer-only rules …). */
+const KIND_PATTERNS: ReadonlyArray<[string, RegExp]> = [
+    ['skills', /(~?)(\d+)\+?\s+skills\b/g],
+    ['commands', /(~?)(\d+)\+?\s+commands\b/g],
+    ['rules', /(~?)(\d+)\+?\s+governed rules\b/g],
+    ['guidelines', /(~?)(\d+)\+?\s+guidelines\b/g],
+    ['personas', /(~?)(\d+)\+?\s+personas\b/g],
+];
+
+export interface Finding {
+    file: string;
+    line: number;
+    kind: string;
+    found: number;
+    expected: number;
+    approx: boolean;
+}
+
+export function canonical_for(kind: string): number {
+    if (kind === 'commands') {
+        // Prose command mentions carry the ACTIVE count (total − shims),
+        // matching the hero badge owned by check_command_count_messaging.
+        const [, , active] = canonical_counts();
+        return active;
+    }
+    return count(kind);
+}
+
+/** Scan one text body; returns findings + the per-kind numbers seen. */
+export function scan_text(
+    rel: string,
+    text: string,
+    expected: Readonly<Record<string, number>>,
+): { findings: Finding[]; seen: Record<string, Set<number>> } {
+    const findings: Finding[] = [];
+    const seen: Record<string, Set<number>> = {};
+    const lines = text.split('\n');
+    for (const [kind, pattern] of KIND_PATTERNS) {
+        for (let i = 0; i < lines.length; i++) {
+            const re = new RegExp(pattern.source, pattern.flags);
+            for (const m of lines[i]!.matchAll(re)) {
+                const found = Number.parseInt(m[2]!, 10);
+                (seen[kind] ??= new Set()).add(found);
+                const exp = expected[kind]!;
+                const approx = m[1] === '~';
+                if (found !== exp || approx) {
+                    findings.push({ file: rel, line: i + 1, kind, found, expected: exp, approx });
+                }
+            }
+        }
+    }
+    return { findings, seen };
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    const QUIET = argv.includes('--quiet');
+    const expected: Record<string, number> = {};
+    for (const [kind] of KIND_PATTERNS) {
+        expected[kind] = canonical_for(kind);
+    }
+    process.stdout.write(
+        `Canonical: skills=${expected['skills']} commands=${expected['commands']} ` +
+            `rules=${expected['rules']} guidelines=${expected['guidelines']} ` +
+            `personas=${expected['personas']}\n`,
+    );
+
+    const allFindings: Finding[] = [];
+    const global_seen: Record<string, Set<number>> = {};
+    for (const rel of SURFACES) {
+        const p = path.join(ROOT, rel);
+        if (!fs.existsSync(p)) {
+            process.stderr.write(`  ⚠️  surface missing (skipped): ${rel}\n`);
+            continue;
+        }
+        const { findings, seen } = scan_text(rel, fs.readFileSync(p, 'utf-8'), expected);
+        allFindings.push(...findings);
+        for (const [kind, nums] of Object.entries(seen)) {
+            for (const n of nums) (global_seen[kind] ??= new Set()).add(n);
+        }
+    }
+
+    // Internal-inconsistency check — the regression case this gate exists
+    // for: multiple DIFFERENT numbers for one kind across the surfaces.
+    const inconsistent: string[] = [];
+    for (const [kind, nums] of Object.entries(global_seen)) {
+        if (nums.size > 1) {
+            inconsistent.push(`${kind}: {${[...nums].sort((a, b) => a - b).join(', ')}}`);
+        }
+    }
+
+    if (allFindings.length === 0 && inconsistent.length === 0) {
+        if (!QUIET) {
+            process.stdout.write('✅  All artefact-count prose in sync with source.\n');
+        }
+        return 0;
+    }
+
+    process.stdout.write(
+        `❌  Artefact-count messaging drift — ${allFindings.length} mismatch(es):\n`,
+    );
+    for (const f of allFindings) {
+        const tag = f.approx ? ' (approximation "~" not allowed on flagship surfaces)' : '';
+        process.stdout.write(
+            `    ${f.file}:${f.line}: ${f.kind} says ${f.found}, expected ${f.expected}${tag}\n`,
+        );
+    }
+    for (const line of inconsistent) {
+        process.stdout.write(`    internal inconsistency — ${line}\n`);
+    }
+    process.stdout.write(
+        '\nFix: run `./scripts-run src/scripts/update_counts` for anchored positions,\n' +
+            'or correct the prose to the canonical number (never hand-type a new one).\n',
+    );
+    return 1;
+}
+
+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 {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
+    process.exit(main(process.argv.slice(2)));
+}

package/src/scripts/check_augment_description_cap.ts

@@ -3,11 +3,11 @@
  * Auto-rule description-length CI gate (Phase 1.3 of
  * road-to-augment-limit-fit).
  *
- * TypeScript twin of `src/scripts/check_augment_description_cap.py` (ADR-200,
- * Phase 4 / Wave 4c). The CLI contract is mirrored EXACTLY — no flags, exit
+ * Ported from the retired Python `src/scripts/check_augment_description_cap.py` (ADR-200,
+ * Phase 4 / Wave 4c). The CLI contract is pinned — no flags, exit
  * codes (0 pass, 1 over-cap), stdout/stderr split, byte-identical finding
  * messages, same scan scope (`.agent-src.uncondensed/rules/*.md`) and file
- * ordering. No behaviour changes — latent bugs replicated.
+ * ordering. Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour.
  *
  * For every `type: auto` rule under `.agent-src.uncondensed/rules/`,
  * fail CI when the frontmatter `description:` exceeds DESC_CAP chars.

package/src/scripts/check_augmentignore.ts

@@ -2,7 +2,7 @@
 /**
  * Advisory check for `.augmentignore` (road-to-governance-cleanup F6.3).
  *
- * TypeScript twin of `src/scripts/check_augmentignore.py` (ADR-200,
+ * Ported from the retired Python `src/scripts/check_augmentignore.py` (ADR-200,
  * Phase 4 / Wave 4c). CLI contract mirrored EXACTLY — `--quiet` flag,
  * always exits 0, byte-identical advisory messages, same staleness /
  * min-useful-lines thresholds, stdout-only output.

package/src/scripts/check_beta_review_markers.ts

@@ -2,12 +2,12 @@
 /**
  * Beta-review-marker checker for `docs/contracts/`.
  *
- * TypeScript twin of `src/scripts/check_beta_review_markers.py` (ADR-200,
- * Phase 4 / Wave 4c). The CLI contract is mirrored EXACTLY — `--json`
+ * Ported from the retired Python `src/scripts/check_beta_review_markers.py` (ADR-200,
+ * Phase 4 / Wave 4c). The CLI contract is pinned — `--json`
  * flag, exit codes (0 clean, 1 violations, 3 internal error), stdout/stderr
  * split, byte-identical messages, the same scan order and the same date
  * arithmetic (`keep-beta-until` ≤ today + 90 days). No behaviour changes —
- * latent bugs replicated.
+ * historical quirks preserved (consumers pin the exact behaviour).
  *
  * Every contract whose frontmatter declares `stability: beta` MUST carry
  * exactly one of `promote-to: stable` | `keep-beta-until: YYYY-MM-DD` |

package/src/scripts/check_bite_sized_granularity.ts

@@ -2,7 +2,7 @@
 /**
  * Bite-sized task granularity gate for structural roadmaps (P1.5).
  *
- * TypeScript twin of `src/scripts/check_bite_sized_granularity.py` (ADR-200,
+ * Ported from the retired Python `src/scripts/check_bite_sized_granularity.py` (ADR-200,
  * Phase 4 / Wave 4c). This module is a pure library (no CLI / main); the
  * Python module is imported as a test surface. The exported API mirrors the
  * Python public API EXACTLY:

package/src/scripts/check_cluster_patterns.ts

@@ -2,17 +2,22 @@
 /**
  * Cluster-pattern compliance check.
  *
- * TypeScript twin of `src/scripts/check_cluster_patterns.py` (ADR-200,
- * Phase 4 / Wave 4c). The CLI contract is mirrored EXACTLY — no flags,
+ * Ported from the retired Python `src/scripts/check_cluster_patterns.py` (ADR-200,
+ * Phase 4 / Wave 4c). The CLI contract is pinned — no flags,
  * exit codes (0 clean, 1 pattern violations, 3 internal error),
  * stdout/stderr split, byte-identical finding messages, the same
  * locked-clusters table parse, the same domains slug map (via the
  * `_lib/agent_src` twin), and the same dispatcher-structure checks. No
- * behaviour changes — latent bugs replicated.
+ * behaviour changes — historical quirks preserved (consumers pin the exact behaviour).
  *
  * Compares each cluster dispatcher against the Phase 1 reference patterns
  * (`fix`, `optimize`, `feature`).
  *
+ * Phase 4 additions (ADR-115): every `routes_to:` entry on a dispatcher must
+ * resolve to a real src/domains command slug, and the `## Dispatch` section
+ * must document the bare-invocation behaviour (menu / default route /
+ * detection fallback) per command-clusters.md § Bare invocation.
+ *
  * Exit codes: 0 = clean, 1 = pattern violations, 3 = internal error.
  */
 
@@ -212,6 +217,45 @@ export function check_dispatcher(cluster: string, slug_map: Map<string, string>)
     if (body.includes('## Sub-commands') && !TABLE_HEADER_RE.test(body)) {
         rep.errors.push('Sub-commands table header must be `| Sub-command | Routes to | Purpose |`');
     }
+
+    // routes_to entries must resolve to real commands (Phase 4 / ADR-115).
+    const routesRaw = fm['routes_to'];
+    if (routesRaw !== undefined) {
+        const m = /^\[(.*)\]$/.exec(routesRaw.trim());
+        const entries = m
+            ? (m[1] as string)
+                  .split(',')
+                  .map((s) => s.trim().replace(/^['"]|['"]$/g, ''))
+                  .filter((s) => s.length > 0)
+            : [];
+        for (const entry of entries) {
+            // routes_to entries name either a command slug or a skill
+            // (e.g. `git-commit` routes to the `git-workflow` skill).
+            const skillPath = path.join(ROOT, 'src', 'skills', entry, 'SKILL.md');
+            if (!slug_map.has(entry) && !_isFile(skillPath)) {
+                rep.errors.push(
+                    `routes_to entry \`${entry}\` resolves to no src/domains command slug ` +
+                        'and no src/skills skill',
+                );
+            }
+        }
+    }
+
+    // Bare-invocation story (Phase 4 / ADR-115): the Dispatch section must say
+    // what a bare `/<cluster>` does — a menu, a default route, or detection.
+    const dispatchIdx = body.indexOf('## Dispatch');
+    if (dispatchIdx !== -1) {
+        const rest = body.slice(dispatchIdx + '## Dispatch'.length);
+        const nextSection = rest.search(/\n## /);
+        const section = nextSection === -1 ? rest : rest.slice(0, nextSection);
+        if (!/menu|bare|no argument|unknown or missing|detection|default/i.test(section)) {
+            rep.errors.push(
+                '`## Dispatch` must document the bare-invocation behaviour ' +
+                    '(menu, default route, or detection fallback) per ' +
+                    'command-clusters.md § Bare invocation',
+            );
+        }
+    }
     return rep;
 }
 

package/src/scripts/check_command_count_messaging.ts

@@ -2,8 +2,8 @@
 /**
  * Command-count messaging gate (road-to-pr-34-followups 1.2).
  *
- * TypeScript twin of `src/scripts/check_command_count_messaging.py`
- * (ADR-200, Phase 4 / Wave 4c). Mirrors the Python CLI contract EXACTLY —
+ * Ported from the retired Python `src/scripts/check_command_count_messaging.py`
+ * (ADR-200, Phase 4 / Wave 4c). The CLI contract is pinned —
  * `--quiet` flag (positional anywhere in argv), exit codes (0 clean,
  * 1 drift, 1 no-commands-dir via stderr), stdout/stderr split,
  * byte-identical messages, same canonical-count derivation