@event4u/agent-config 9.14.0 → 9.16.0

package/src/scripts/check_always_budget.ts

@@ -36,7 +36,42 @@ const RULES_DIR = path.join(REPO_ROOT, 'dist/agent-src', 'rules');
 const SRC_PREFIX = '.agent-src.uncondensed/';
 const COMP_PREFIX = 'dist/agent-src/';
 
+/**
+ * TWO BUDGETS, TWO DIMENSIONS (road-to-renewal-foundation Phase 1; council
+ * 2026-08-02 option B, 2/2).
+ *
+ * `TOTAL_CAP` governs the **raw** dimension — the always-loaded kernel rule
+ * bodies themselves. That is the dimension this cap was calibrated for and the
+ * only one it ever actually enforced: until the dead-root repair in this same
+ * change, `srcToCondensed()` resolved every `load_context` entry to a path that
+ * could not exist, so the walker counted ZERO context files and `ext` always
+ * equalled `raw`. The gate printed a confident `60.1%` of a dimension it was
+ * not measuring.
+ *
+ * `EXT_TOTAL_CAP` governs the **extended** dimension — raw plus the transitive
+ * closure of `load_context` / `load_context_eager` (depth ≤ 2). It is seeded at
+ * the FIRST REAL MEASUREMENT, taken 2026-08-02 after the repair, and is a hard
+ * gate (the council rejected an advisory cycle: an advisory number creates no
+ * pressure and just defers the collision).
+ *
+ * The seed is a baseline of revealed debt, NOT a target and NOT an approval.
+ * It exists so the number is visible and ratcheted; it may only move DOWN. The
+ * Phase 2 token work of this roadmap is what pays it down.
+ *
+ * Deliberately NOT done: raising `TOTAL_CAP` to swallow the ext number. That
+ * would silently redefine the kernel budget to ~2× what the maintainer approved
+ * and remove exactly the pressure Phase 2 exists to apply.
+ *
+ * Deliberately DEFERRED: splitting lazy `load_context` from eager
+ * `load_context_eager` (only the latter is unconditionally always-loaded). The
+ * distinction is real and encoded in the schema, but narrowing an aggregate on
+ * a semantic argument is a separate decision from repairing its measurement —
+ * and it cannot claim the "live and green" protection the house discriminator
+ * grants an enforced contract, because this dimension was never enforced.
+ */
 const TOTAL_CAP = 49_000;
+const EXT_TOTAL_CAP = 60_254;
+const EXT_MEASURED_AT = '2026-08-02';
 const WARN_THRESHOLD = 0.8;
 const FAIL_THRESHOLD = 0.9;
 
@@ -63,16 +98,36 @@ const TREND_LOG = path.join(REPO_ROOT, '.github', 'budget-trend.jsonl');
 const TREND_LOG_MAX_RECORDS = 500;
 const TOLERANCE_BAND = 0.02;
 const PER_RULE_CAP = 6_000;
-const TOP3_CAP = Math.trunc(TOTAL_CAP / 2);
+// Top-3 is an EXT measure, so it is capped against the ext budget, not the raw
+// one. Seeded 2026-08-02 at the measured 37,855 rather than the derived
+// EXT_TOTAL_CAP/2 (30,127): the derived value was never met and would fail on
+// day one, which is a baseline the gate cannot hold. Ratchet — moves DOWN only.
+const TOP3_CAP = 37_855;
 const MAX_DEPTH = 2;
 const MAX_CONTEXTS_PER_RULE = 3;
 
 const RECOVERY_BAND_ENABLED = true;
 const BASELINE_FILE = path.join(REPO_ROOT, '.github', 'budget-baseline.txt');
 
+/**
+ * Per-rule EXT ceilings, reseeded 2026-08-02 at the first real measurement.
+ *
+ * The previous values (`non-destructive-by-default` 7,908 · `scope-control`
+ * 8,550) were ~2× those rules' raw sizes, which is why they are evidence the
+ * ext dimension once counted contexts — but they have been unenforceable for as
+ * long as the resolver was broken, so they describe a tree that no longer
+ * exists. Reseeding them to the measured values is a baseline of revealed debt,
+ * not an approval: these are ratchets and may only move DOWN.
+ *
+ * `commit-policy` and `verify-before-complete` are new entries for the same
+ * reason — they breach the 6,000 per-rule cap only now that their context
+ * closures are actually counted.
+ */
 const KNOWN_PER_RULE_BREACHES: Record<string, number> = {
-    'non-destructive-by-default.md': 7_908,
-    'scope-control.md': 8_550,
+    'scope-control.md': 19_332,
+    'non-destructive-by-default.md': 9_657,
+    'commit-policy.md': 8_866,
+    'verify-before-complete.md': 7_140,
 };
 
 const PROG = 'check_always_budget.py';
@@ -198,11 +253,51 @@ function loadContextPaths(filePath: string): string[] {
     return out;
 }
 
-function srcToCondensed(entry: string): string {
-    if (entry.startsWith(SRC_PREFIX)) {
-        return path.join(REPO_ROOT, COMP_PREFIX + entry.slice(SRC_PREFIX.length));
+/**
+ * Resolve one `load_context` entry to the projected file it names.
+ *
+ * DEAD-ROOT REPAIR (road-to-renewal-foundation Phase 1). This used to be:
+ *
+ *     if (entry.startsWith(<retired authoring root>)) → dist/agent-src/<rest>
+ *     else                                             → REPO_ROOT/<entry>
+ *
+ * The retired authoring root was deleted by ADR-051, so the first branch was
+ * unreachable. The second branch was wrong for every real entry: `load_context`
+ * values are relative to the file that declares them
+ * (`../contexts/execution/autonomy-mechanics.md` from a rule in
+ * `dist/agent-src/rules/`), never repo-root-relative. Joining them to the repo
+ * root produced `<repo>/contexts/…`, which never exists — and `walkContexts`
+ * silently `continue`s on a missing path.
+ *
+ * Net effect: the transitive-context dimension of this budget counted ZERO
+ * files while the gate printed a confident percentage. It reported ~60% of a
+ * cap it was not measuring, and would have reported the same had every rule
+ * pulled in a megabyte of context.
+ *
+ * `skill:` / `guideline:` entries are scheme references, not paths — they have
+ * no file to size and are skipped explicitly rather than by accidental
+ * existsSync failure.
+ *
+ * @param entry the raw frontmatter value
+ * @param fromFile absolute path of the file that declared it
+ * @returns absolute path, or `null` when the entry names no file
+ */
+function resolveContextEntry(entry: string, fromFile: string): string | null {
+    const trimmed = entry.trim();
+    if (trimmed === '' || /^[a-z][a-z0-9+.-]*:/i.test(trimmed)) {
+        // `skill:foo`, `guideline:bar/baz`, or any other scheme reference.
+        return null;
+    }
+    if (trimmed.startsWith(SRC_PREFIX)) {
+        // Legacy authoring-root form, kept so a stale entry still resolves to
+        // its projected twin instead of silently counting zero.
+        return path.join(REPO_ROOT, COMP_PREFIX + trimmed.slice(SRC_PREFIX.length));
     }
-    return path.join(REPO_ROOT, entry);
+    if (trimmed.startsWith(COMP_PREFIX) || path.isAbsolute(trimmed)) {
+        return path.resolve(REPO_ROOT, trimmed);
+    }
+    // The real shape: relative to the declaring file's directory.
+    return path.resolve(path.dirname(fromFile), trimmed);
 }
 
 /** Return [set of context files counted, list of depth-violation chains]. */
@@ -214,8 +309,9 @@ function walkContexts(rule: string): [Set<string>, Array<[string, string]>] {
     while (stack.length > 0) {
         const [node, depth, chain] = stack.pop() as [string, number, string];
         for (const entry of loadContextPaths(node)) {
-            const comp = srcToCondensed(entry);
+            const comp = resolveContextEntry(entry, node);
             const newChain = `${chain} → ${entry}`;
+            if (comp === null) continue;
             if (depth + 1 > MAX_DEPTH) {
                 violations.push([ruleName, newChain]);
                 continue;
@@ -473,8 +569,16 @@ function main(): number {
     // sizes.sort(key=lambda x: -x[2]) — stable descending by ext.
     sizes.sort((a, b) => b[2] - a[2]);
     let totalExt = 0;
-    for (const s of sizes) totalExt += s[2];
-    const pct = totalExt / TOTAL_CAP;
+    let totalRaw = 0;
+    for (const s of sizes) {
+        totalRaw += s[1];
+        totalExt += s[2];
+    }
+    // TOTAL_CAP is the RAW budget (see the two-budgets note at the top); the
+    // extended dimension has its own seeded cap.
+    const pct = totalRaw / TOTAL_CAP;
+    const extPct = totalExt / EXT_TOTAL_CAP;
+    const extBreach = totalExt > EXT_TOTAL_CAP;
     let top3 = 0;
     for (const s of sizes.slice(0, 3)) top3 += s[2];
     const top3Breach = top3 > TOP3_CAP;
@@ -503,6 +607,7 @@ function main(): number {
     const failing =
         (pct >= FAIL_THRESHOLD && !inTolerance && !inRecoveryBand && pct < 1.0) ||
         pct > 1.0 + TOLERANCE_BAND ||
+        extBreach ||
         overPerRule.length > 0 ||
         grewOverCeiling.length > 0 ||
         top3Breach ||
@@ -532,9 +637,15 @@ function main(): number {
 
     const out: string[] = [];
     out.push(
-        `${status}  always-rule extended budget: ${comma(totalExt)} / ` +
+        `${status}  always-rule raw budget: ${comma(totalRaw)} / ` +
             `${comma(TOTAL_CAP)} chars (${fixed(pct * 100, 1)}%) across ${rules.length} rule(s)`,
     );
+    out.push(
+        `      extended (raw + load_context closure): ${comma(totalExt)} / ` +
+            `${comma(EXT_TOTAL_CAP)} chars (${fixed(extPct * 100, 1)}%)` +
+            `${extBreach ? '  ❌ over the seeded ext cap' : ''}` +
+            `  — ratchet seeded at the first real measurement ${EXT_MEASURED_AT}; may only move DOWN`,
+    );
     out.push(
         `      thresholds: warn ${fixed(WARN_THRESHOLD * 100, 0)}% · ` +
             `fail ${fixed(FAIL_THRESHOLD * 100, 0)}% · ` +

package/src/scripts/check_augment_description_cap.ts

@@ -91,11 +91,32 @@ function _globMdSorted(dir: string): string[] {
     return out;
 }
 
-export function main(): number {
+/**
+ * Injection seam for tests: `--root <dir>` overrides the scan root.
+ *
+ * Additive — no flag means the CI-identical bare call scans `RULES_DIR`, so the
+ * pinned CLI contract is unchanged. Without a seam the only way to exercise a
+ * real over-cap violation was to tamper with a committed rule, which is why this
+ * gate shipped with tests that never called `main()` at all.
+ */
+function _resolve_root(argv: readonly string[]): string {
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i] as string;
+        if (a === '--root') {
+            const v = argv[i + 1];
+            if (v !== undefined) return path.resolve(v);
+        } else if (a.startsWith('--root=')) {
+            return path.resolve(a.slice('--root='.length));
+        }
+    }
+    return RULES_DIR;
+}
+
+export function main(argv: readonly string[] = []): number {
     const failures: Array<[string, number, string]> = [];
     let checked = 0;
 
-    for (const p of _globMdSorted(RULES_DIR)) {
+    for (const p of _globMdSorted(_resolve_root(argv))) {
         const text = fs.readFileSync(p, 'utf-8');
         const fm = parse_frontmatter(text);
         if (fm['type'] !== 'auto') {
@@ -157,7 +178,7 @@ function _isCliEntry(): boolean {
 }
 
 if (_isCliEntry() || process.argv[1] === _HERE) {
-    process.exit(main());
+    process.exit(main(process.argv.slice(2)));
 }
 
 export { REPO_ROOT, RULES_DIR, DESC_CAP };

package/src/scripts/check_ci_strict_superset.ts

@@ -0,0 +1,150 @@
+#!/usr/bin/env tsx
+/**
+ * Assert `ci-strict` is a superset of `ci` BY CONSTRUCTION.
+ *
+ * WHY THIS EXISTS (road-to-renewal-foundation Phase 1, council 2026-08-02
+ * decision A1, 2/2):
+ *
+ * `Taskfile.yml` used to carry `ci` (202 gate entries) and `ci-strict` (197)
+ * as two independently maintained literal lists. They drifted, and nothing
+ * detected it — `check_ci_local_parity.ts` deliberately scopes itself to
+ * `LOCAL_ROOTS = ['ci', 'consistency']`, so `ci-strict` was outside every
+ * assertion in the repo. Six gates ran in `ci` with no counterpart in
+ * `ci-strict` at all:
+ *
+ *   preflight (fans out to 11 scripts, incl. check_no_new_legacy_path and
+ *   check_kernel_rule_bundle), check-ci-local-parity,
+ *   check-gitignore-freshness, check-generator-output-coverage,
+ *   check-tracked-but-ignored, check-generated-artefact-headers
+ *
+ * — so the "release-tag gate" was strictly WEAKER than the everyday gate on
+ * ~16 concrete script runs. A stricter tier that checks less is the worst
+ * possible shape for a release gate: it is trusted more and proves less.
+ *
+ * The fix was structural, not a bigger checker: `ci-strict` now delegates to
+ * `ci` and adds only strict-only entries on top, so the superset property is
+ * tautological. This gate guards the ONE invariant that keeps it tautological
+ * — the first gate entry of `ci-strict` is `- task: ci`.
+ *
+ * It deliberately does NOT re-parse and diff both lists. That would recreate
+ * the very "maintain a second model of the same thing" problem the delegation
+ * removed, and it would pass happily on a re-forked pair of lists that merely
+ * happened to match on the day it ran.
+ *
+ * Exit codes: 0 ok · 1 invariant violated · 2 usage / environment error.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+const TASKFILE = path.join(REPO_ROOT, 'Taskfile.yml');
+
+/** The delegation entry that makes the superset property tautological. */
+const DELEGATION = '- task: ci';
+
+/**
+ * Extract the `cmds:` entries of a top-level task, in order.
+ *
+ * Minimal line scan rather than a YAML dependency: the shape is fixed
+ * (`  <name>:` at two-space indent, `    cmds:` at four, `      - ...` at
+ * six) and the repo has no YAML anchors anywhere, so a parser buys nothing
+ * here and adds an import to a gate that must stay cheap.
+ */
+function taskCmds(source: string, taskName: string): string[] | null {
+    const lines = source.split('\n');
+    const header = `  ${taskName}:`;
+    let i = lines.findIndex((l) => l === header);
+    if (i === -1) {
+        return null;
+    }
+    const out: string[] = [];
+    let inCmds = false;
+    for (i += 1; i < lines.length; i++) {
+        const line = lines[i]!;
+        if (line.trim() === '') {
+            continue;
+        }
+        // Any line at two-space indent that is not deeper ends this task.
+        if (/^ {2}\S/.test(line)) {
+            break;
+        }
+        if (/^ {4}cmds:\s*$/.test(line)) {
+            inCmds = true;
+            continue;
+        }
+        if (!inCmds) {
+            continue;
+        }
+        const m = /^ {6}(- .*)$/.exec(line);
+        if (m) {
+            out.push(m[1]!.trim());
+        }
+    }
+    return out;
+}
+
+export function main(): number {
+    let source: string;
+    try {
+        source = fs.readFileSync(TASKFILE, 'utf-8');
+    } catch (err) {
+        process.stderr.write(`❌  check_ci_strict_superset: cannot read ${TASKFILE}: ${String(err)}\n`);
+        return 2;
+    }
+
+    const strict = taskCmds(source, 'ci-strict');
+    if (strict === null) {
+        process.stderr.write(
+            '❌  check_ci_strict_superset: no `ci-strict:` task found in Taskfile.yml.\n' +
+                '    The gate cannot verify an invariant on a task that does not exist.\n',
+        );
+        return 2;
+    }
+    if (taskCmds(source, 'ci') === null) {
+        process.stderr.write(
+            '❌  check_ci_strict_superset: no `ci:` task found in Taskfile.yml.\n',
+        );
+        return 2;
+    }
+
+    // Skip the internal timing wrappers; they carry no gate semantics and
+    // `ci-strict` intentionally does not repeat them (`ci` already brackets
+    // the run, so the duration line prints once).
+    const gateEntries = strict.filter(
+        (e) => !e.startsWith('- defer:') && e !== '- task: _ci-start' && e !== '- task: _ci-end',
+    );
+
+    if (gateEntries.length === 0) {
+        process.stderr.write('❌  check_ci_strict_superset: `ci-strict` has no gate entries.\n');
+        return 1;
+    }
+
+    if (gateEntries[0] !== DELEGATION) {
+        process.stderr.write(
+            '❌  check_ci_strict_superset: `ci-strict` no longer delegates to `ci`.\n' +
+                `    expected first gate entry: \`${DELEGATION}\`\n` +
+                `    found:                    \`${gateEntries[0]}\`\n\n` +
+                '    `ci-strict` must run every `ci` gate plus strict-only extras. It used\n' +
+                '    to be an independently maintained copy of the list and silently drifted\n' +
+                '    to SIX fewer gates than `ci` — a release gate that proved less than the\n' +
+                '    everyday gate. Delegation is what makes the superset property structural\n' +
+                '    instead of asserted. If you need a strict variant of a gate, add the\n' +
+                '    `-strict` task AFTER the delegation entry; never re-inline the list.\n',
+        );
+        return 1;
+    }
+
+    const extras = gateEntries.slice(1);
+    process.stdout.write(
+        `✅  ci-strict ⊇ ci by construction (delegates to \`ci\`, plus ${extras.length} strict-only ` +
+            `entr${extras.length === 1 ? 'y' : 'ies'}).\n`,
+    );
+    return 0;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    process.exit(main());
+}

package/src/scripts/check_cli_registry_budget_sync.ts

@@ -0,0 +1,168 @@
+#!/usr/bin/env tsx
+/**
+ * CLI-registry ↔ evaluator-budget sync gate.
+ *
+ * The evaluator budget `cli_help_command_count` (src/config/evaluator-budgets.json)
+ * and the committed measurement record (agents/evidence/metrics/
+ * evaluator-measurements.json) are derived from `src/cli/registry.ts`, but until
+ * this gate nothing forced the PR that changes the registry to move them: the
+ * breach only WARNED on main and BLOCKED the next release. That is how 9.15.0
+ * went red — f02db54c2 registered `routing:doctor` (80 → 81 entries) and the
+ * drift surfaced days later, at release time, on an unrelated branch.
+ *
+ * This gate runs on every PR (Static Checks + `task preflight`) and fails the
+ * moment the three numbers disagree, so the registering PR carries the budget
+ * move itself.
+ *
+ * The count uses the SAME pinned method as evaluator_umbrella.sh — the number
+ * of `{ name: ` entry openers in src/cli/registry.ts (NOT --help prose
+ * parsing; methods historically disagreed 74 vs 76 vs 79).
+ *
+ * Exit codes: 0 in sync · 1 out of sync · 2 a required file is missing or
+ * unparseable (fail-closed: a gate that cannot read its inputs must not
+ * certify them).
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+const REGISTRY_PATH = path.join(REPO_ROOT, 'src/cli/registry.ts');
+const BUDGETS_PATH = path.join(REPO_ROOT, 'src/config/evaluator-budgets.json');
+const RECORD_PATH = path.join(REPO_ROOT, 'agents/evidence/metrics/evaluator-measurements.json');
+
+const METRIC = 'cli_help_command_count';
+
+/** Pinned method — byte-for-byte the umbrella's CLI_COUNT probe. */
+function count_registry_entries(source: string): number {
+    return (source.match(/\{ name: /g) || []).length;
+}
+
+interface BudgetEntry {
+    max?: unknown;
+    last_measured?: unknown;
+}
+
+interface SyncInputs {
+    count: number;
+    budget: BudgetEntry | undefined;
+    recorded: unknown;
+}
+
+const REMEDY =
+    'Fix, in THIS PR (the one that moves src/cli/registry.ts):\n' +
+    `  1. src/config/evaluator-budgets.json → budgets.${METRIC}: set max +\n` +
+    '     last_measured to the new count, bump last_measured_at, and extend\n' +
+    '     baseline_note naming the commit that moves the surface.\n' +
+    '  2. Regenerate the committed record (never hand-edit):\n' +
+    '       node src/scripts/record_evaluator_measurements.mjs \\\n' +
+    '         --measurements <file with the re-measured metrics> \\\n' +
+    '         --out agents/evidence/metrics/evaluator-measurements.json \\\n' +
+    '         --sha "$(git rev-parse HEAD)"\n' +
+    'Otherwise the drift stays invisible until the next release, where the\n' +
+    'evaluator gate blocks it (the 9.15.0 failure mode this gate exists to stop).\n';
+
+/** Pure comparison — the CLI owns the filesystem. */
+function collect_findings(inputs: SyncInputs): string[] {
+    const findings: string[] = [];
+    const { count, budget, recorded } = inputs;
+
+    if (budget === undefined) {
+        findings.push(`budgets.${METRIC} is missing from evaluator-budgets.json`);
+        return findings;
+    }
+    if (budget.last_measured !== count) {
+        findings.push(
+            `registry has ${count} entries but budgets.${METRIC}.last_measured says ` +
+                `${String(budget.last_measured)}`,
+        );
+    }
+    if (typeof budget.max !== 'number' || count > budget.max) {
+        findings.push(
+            `registry has ${count} entries but budgets.${METRIC}.max is ` +
+                `${String(budget.max)}`,
+        );
+    }
+    if (recorded === undefined) {
+        findings.push(
+            `measurements.${METRIC} is missing from the committed record ` +
+                '(agents/evidence/metrics/evaluator-measurements.json)',
+        );
+    } else if (recorded !== count) {
+        findings.push(
+            `registry has ${count} entries but the committed record says ` +
+                `${String(recorded)}`,
+        );
+    }
+    return findings;
+}
+
+function _read_json(p: string): Record<string, unknown> {
+    return JSON.parse(fs.readFileSync(p, 'utf-8')) as Record<string, unknown>;
+}
+
+function main(): number {
+    let registrySource: string;
+    let budgetsDoc: Record<string, unknown>;
+    let recordDoc: Record<string, unknown>;
+    try {
+        registrySource = fs.readFileSync(REGISTRY_PATH, 'utf-8');
+        budgetsDoc = _read_json(BUDGETS_PATH);
+        recordDoc = _read_json(RECORD_PATH);
+    } catch (err) {
+        process.stderr.write(
+            `ERROR: cannot read a gate input: ${err instanceof Error ? err.message : String(err)}\n`,
+        );
+        return 2;
+    }
+
+    const count = count_registry_entries(registrySource);
+    const budgets = budgetsDoc['budgets'] as Record<string, BudgetEntry> | undefined;
+    const measurements = recordDoc['measurements'] as Record<string, unknown> | undefined;
+    const findings = collect_findings({
+        count,
+        budget: budgets?.[METRIC],
+        recorded: measurements?.[METRIC],
+    });
+
+    process.stdout.write('scanned: 3\n');
+    if (findings.length > 0) {
+        for (const f of findings) {
+            process.stdout.write(`❌  ${METRIC} out of sync: ${f}\n`);
+        }
+        process.stdout.write('\n' + REMEDY);
+        return 1;
+    }
+    process.stdout.write(
+        `✅  ${METRIC} in sync — registry (${count}) == budget == committed record.\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;
+    }
+    // Symlinked invocations (installed projections, macOS /var → /private/var)
+    // make the raw URLs differ — compare realpaths so the entry guard fires.
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argvPath = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argvPath;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
+    process.exit(main());
+}
+
+export { collect_findings, count_registry_entries, main };

package/src/scripts/check_cluster_patterns.ts

@@ -18,6 +18,19 @@
  * must document the bare-invocation behaviour (menu / default route /
  * detection fallback) per command-clusters.md § Bare invocation.
  *
+ * Filesystem-enumeration addition (road-to-renewal-leverage, 2026-08-02): the
+ * checks above all read the CONTRACT and ask "does what it names exist?".
+ * Nothing asked the inverse — "does what exists get named?" — so a
+ * sub-command could sit on disk while appearing in neither its hub's
+ * `## Sub-commands` table nor its `routes_to:`, invisibly. Two instances were
+ * live when this was added (`/roadmap:materialize`, `/memory:learn-low-impact`)
+ * plus incomplete `routes_to` on 12 of 25 dispatch clusters.
+ * `check_completeness` closes that direction: for a `type: orchestrator`
+ * dispatcher, every on-disk `<sub>/command.md` sibling directory must be named
+ * in the table and listed in `routes_to`. Scoped to orchestrators on purpose —
+ * a few contract rows point at full working commands that merely happen to
+ * carry one nested sub-command, and those own no dispatch table.
+ *
  * Exit codes: 0 = clean, 1 = pattern violations, 3 = internal error.
  */
 
@@ -170,6 +183,90 @@ function _repr(v: string | undefined): string {
     return `'${v.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
 }
 
+/** Parse a `routes_to: [a, b]` frontmatter value into its entries. */
+export function parse_routes_to(raw: string | undefined): string[] {
+    if (raw === undefined) {
+        return [];
+    }
+    const m = /^\[(.*)\]$/.exec(raw.trim());
+    if (!m) {
+        return [];
+    }
+    return (m[1] as string)
+        .split(',')
+        .map((s) => s.trim().replace(/^['"]|['"]$/g, ''))
+        .filter((s) => s.length > 0);
+}
+
+/** Sub-command directory names that carry a `command.md`, sorted. */
+export function on_disk_subs(dispatcher_path: string): string[] {
+    const dir = path.dirname(dispatcher_path);
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+        return [];
+    }
+    return entries
+        .filter((e) => e.isDirectory() && _isFile(path.join(dir, e.name, 'command.md')))
+        .map((e) => e.name)
+        .sort();
+}
+
+/**
+ * Does the body name `<sub>` as a sub-command of `<cluster>`?
+ *
+ * Both `` `/cluster:sub` `` and `` `/cluster sub` `` count — command-clusters.md
+ * § 157 makes the space form a first-class equivalent of the colon form, so
+ * requiring one of them would be inventing a rule the contract does not carry.
+ * The trailing class allows a row that decorates the name inside the same
+ * backticks (`` `/team review [--background]` ``).
+ */
+export function names_sub(body: string, cluster: string, sub: string): boolean {
+    const re = new RegExp('`/' + cluster + '[: ]' + sub + '(?![a-z0-9-])');
+    return re.test(body);
+}
+
+/**
+ * Every on-disk sub-command of an orchestrator must be named in its
+ * `## Sub-commands` table and listed in `routes_to:`.
+ *
+ * Non-orchestrator dispatchers are skipped: a handful of contract rows point
+ * at full working commands that merely happen to carry a nested sub-command,
+ * and those own no dispatch table to be complete against.
+ */
+export function check_completeness(
+    cluster: string,
+    dispatcher_path: string,
+    fm: Record<string, string>,
+    body: string,
+): string[] {
+    if (fm['type'] !== 'orchestrator') {
+        return [];
+    }
+    const subs = on_disk_subs(dispatcher_path);
+    if (subs.length === 0) {
+        return [];
+    }
+    const errors: string[] = [];
+    const routes = parse_routes_to(fm['routes_to']);
+    for (const sub of subs) {
+        if (!names_sub(body, cluster, sub)) {
+            errors.push(
+                `sub-command \`${sub}\` exists on disk but is not named in the ` +
+                    '`## Sub-commands` table',
+            );
+        }
+        if (!routes.includes(`${cluster}-${sub}`) && !routes.includes(sub)) {
+            errors.push(
+                `sub-command \`${sub}\` exists on disk but is missing from ` +
+                    '`routes_to:`',
+            );
+        }
+    }
+    return errors;
+}
+
 export function check_dispatcher(cluster: string, slug_map: Map<string, string>): FileReport {
     const p = _resolve_command(cluster, slug_map);
     if (p === null) {
@@ -241,6 +338,9 @@ export function check_dispatcher(cluster: string, slug_map: Map<string, string>)
         }
     }
 
+    // Completeness (2026-08-02): every sub-command that EXISTS must be named.
+    rep.errors.push(...check_completeness(cluster, p, fm, body));
+
     // 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');