@event4u/agent-config 1.16.0 → 1.17.0

package/scripts/check_always_budget.py

@@ -1,50 +1,244 @@
 #!/usr/bin/env python3
-"""Always-rule budget gate (Phases 7.1 + 7.4 of road-to-pr-34-followups).
+"""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).
 
-Enforces a stricter budget contract than `tests/test_always_budget.py`:
-the test suite fails only at 100% utilization (49,000 chars). This
-script lives in CI as:
+Enforces the budget contract under **Model (b) literal** — see
+`docs/contracts/load-context-budget-model.md`. Effective size of a
+`type: "always"` rule is its own char count plus the char count of
+every context it loads (transitively, depth ≤ 2).
 
+Caps:
 - Warn-at-80% / fail-at-90% global trend gate (Phase 7.1).
-- Per-rule cap (≤ 6,000 chars per always-rule, Phase 7.4).
-- Top-3 cap (top-3 combined ≤ 50% of TOTAL_CAP, Phase 7.4).
+- Per-rule cap (≤ 6,000 chars per always-rule, Phase 7.4) — measured
+  on extended size, with a transitional `KNOWN_PER_RULE_BREACHES`
+  allowlist that Phase 2A retires.
+- Top-3 cap (top-3 combined ≤ 50% of TOTAL_CAP, Phase 7.4) — extended.
+- Depth-2 nesting cap on `load_context:` chains.
 
-The same caps are enforced as hard assertions in
-`tests/test_always_budget.py`; this script duplicates them so a
-contributor sees a single, fast pre-test signal during local edits.
-
-Exit codes: 0 = pass (or warn), 1 = fail (≥ 90% utilization,
-per-rule breach, or top-3 breach), 3 = internal error.
+Exit codes: 0 = pass (or warn), 1 = fail (≥ 90% utilization, per-rule
+breach above ceiling, top-3 breach, or depth violation), 3 = internal
+error.
 """
 
 from __future__ import annotations
 
 import argparse
+import json
 import sys
+from datetime import datetime, timezone
 from pathlib import Path
 
+import yaml
+
 REPO_ROOT = Path(__file__).resolve().parents[1]
 RULES_DIR = REPO_ROOT / ".agent-src" / "rules"
+SRC_PREFIX = ".agent-src.uncompressed/"
+COMP_PREFIX = ".agent-src/"
 
 TOTAL_CAP = 49_000
-WARN_THRESHOLD = 0.80   # 80% — emit warning, exit 0
-FAIL_THRESHOLD = 0.90   # 90% — emit error,  exit 1
-PER_RULE_CAP = 6_000    # Phase 7.4 — no single always-rule may exceed this
-TOP3_CAP = TOTAL_CAP // 2  # Phase 7.4 — top-3 combined ≤ 50% of total budget
+WARN_THRESHOLD = 0.80
+FAIL_THRESHOLD = 0.90
+
+# Phase 5.2.1 concentration thresholds (non-safety-floor rules only).
+# Beyond the total-budget cap, fail CI when any single non-safety-floor
+# rule exceeds SINGLE_PCT of used budget OR the top-3 non-safety-floor
+# sum exceeds TOP3_PCT of used budget. Prevents post-slim concentration
+# regrowth (risk #12 in road-to-structural-optimization).
+CONCENTRATION_SINGLE_PCT = 0.12
+CONCENTRATION_TOP3_PCT = 0.30
+
+# Q3=A locked safety-floor rules — out of scope for slimming and for the
+# concentration check. Their size is intentional (Iron Laws + obligation
+# surface), not drift. See road-to-structural-optimization Phase 5.
+SAFETY_FLOOR_RULES: frozenset[str] = frozenset({
+    "non-destructive-by-default.md",
+    "commit-policy.md",
+    "scope-control.md",
+    "verify-before-complete.md",
+})
+
+# Phase 5.3 — per-rule trend log. JSONL, one record per linter run.
+# Each line: {"ts": iso8601, "total": int, "rules": {name: ext}}.
+TREND_LOG = REPO_ROOT / ".github" / "budget-trend.jsonl"
+TREND_LOG_MAX_RECORDS = 500
+# Phase 0.2 G3 tolerance band — overshoot ≤ 2 % of cap is accepted by
+# the model (b) contract; > 2 % rejects model (b) and escalates. The
+# linter treats the [100 %, 100 % + tolerance] window as a hardened
+# WARN that documents the transition; Phase 2A drops total below 100 %.
+TOLERANCE_BAND = 0.02
+PER_RULE_CAP = 6_000
+TOP3_CAP = TOTAL_CAP // 2
+MAX_DEPTH = 2
+
+# Recovery band (AI Council session 2026-05-03T12-02-42Z, verdict A1).
+# When enabled, a branch in the 90–100 % gap zone passes as WARN iff its
+# extended total is strictly below the last-green main baseline AND every
+# per-rule / top-3 / depth cap holds. Resolves the paradox where main at
+# 100.6 % passed via TOLERANCE_BAND while a strictly-better branch at
+# 96.8 % failed the gap-zone gate. Phase 5 of road-to-structural-
+# optimization flips this to False and enforces total < TOTAL_CAP strictly.
+RECOVERY_BAND_ENABLED = True
+BASELINE_FILE = REPO_ROOT / ".github" / "budget-baseline.txt"
+
+# Transitional allowlist — per-rule extended-size breaches that Phase 2A
+# of road-to-structural-optimization is contracted to retire. Each entry
+# records the measured ceiling on the day Phase 0.2 was committed; a
+# growth above the ceiling fails CI even while the entry remains.
+# When Phase 2A retires a rule, drop its entry here AND in
+# `tests/test_always_budget.py::KNOWN_PER_RULE_BREACHES`.
+KNOWN_PER_RULE_BREACHES: dict[str, int] = {
+    "non-destructive-by-default.md": 7_887,
+    "scope-control.md": 8_529,
+}
+
+
+def _load_baseline() -> int | None:
+    """Return the last-green main baseline char total, or None if absent.
+
+    Reads `.github/budget-baseline.txt`; the first non-comment, non-blank
+    line is parsed as an integer. Missing file or malformed content
+    disables the recovery band silently — the linter falls back to the
+    pre-band gate.
+    """
+    if not BASELINE_FILE.exists():
+        return None
+    for line in BASELINE_FILE.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        try:
+            return int(line)
+        except ValueError:
+            return None
+    return None
+
+
+def _frontmatter(path: Path) -> dict:
+    text = path.read_text(encoding="utf-8")
+    if not text.startswith("---\n"):
+        return {}
+    end = text.find("\n---\n", 4)
+    if end == -1:
+        return {}
+    try:
+        return yaml.safe_load(text[4:end]) or {}
+    except yaml.YAMLError:
+        return {}
+
+
+def _is_always(path: Path) -> bool:
+    return _frontmatter(path).get("type") == "always"
+
+
+def _load_context_paths(path: Path) -> list[str]:
+    fm = _frontmatter(path)
+    out: list[str] = []
+    for key in ("load_context", "load_context_eager"):
+        for entry in fm.get(key) or []:
+            out.append(str(entry))
+    return out
+
+
+def _src_to_compressed(entry: str) -> Path:
+    if entry.startswith(SRC_PREFIX):
+        return REPO_ROOT / (COMP_PREFIX + entry[len(SRC_PREFIX):])
+    return REPO_ROOT / entry
+
+
+def _walk_contexts(rule: Path) -> tuple[set[Path], list[tuple[str, str]]]:
+    """Return (set of context files counted, list of depth-violation chains)."""
+    seen: set[Path] = set()
+    violations: list[tuple[str, str]] = []
+    stack: list[tuple[Path, int, str]] = [(rule, 0, rule.name)]
+    while stack:
+        node, depth, chain = stack.pop()
+        for entry in _load_context_paths(node):
+            comp = _src_to_compressed(entry)
+            new_chain = f"{chain} → {entry}"
+            if depth + 1 > MAX_DEPTH:
+                violations.append((rule.name, new_chain))
+                continue
+            if not comp.exists():
+                continue
+            if comp in seen:
+                continue
+            seen.add(comp)
+            stack.append((comp, depth + 1, new_chain))
+    return seen, violations
 
 
 def _always_rules() -> list[Path]:
-    rules: list[Path] = []
-    for path in sorted(RULES_DIR.glob("*.md")):
-        head = path.read_text(encoding="utf-8").splitlines()[1:2]
-        if head == ['type: "always"']:
-            rules.append(path)
-    return rules
+    return sorted(p for p in RULES_DIR.glob("*.md") if _is_always(p))
+
+
+def _extended_size(rule: Path) -> tuple[int, list[tuple[str, str]]]:
+    raw = rule.stat().st_size
+    contexts, violations = _walk_contexts(rule)
+    ext = raw + sum(c.stat().st_size for c in contexts)
+    return ext, violations
+
+
+def _concentration_check(
+    sizes: list[tuple[str, int, int]],
+    total_ext: int,
+) -> tuple[list[tuple[str, int, float]], tuple[int, float] | None]:
+    """Phase 5.2.1 concentration check (non-safety-floor rules only).
+
+    Returns (single-rule breaches, top-3 breach or None). Q3=A locked
+    safety-floor rules are excluded from both numerator and the top-3
+    selection — their size is intentional, not drift.
+    """
+    non_floor = [
+        (name, raw, ext) for name, raw, ext in sizes
+        if name not in SAFETY_FLOOR_RULES
+    ]
+    single_cap = total_ext * CONCENTRATION_SINGLE_PCT
+    top3_cap = total_ext * CONCENTRATION_TOP3_PCT
+
+    single_breaches = [
+        (name, ext, ext / total_ext)
+        for name, _, ext in non_floor
+        if ext > single_cap
+    ]
+    top3_sum = sum(ext for _, _, ext in non_floor[:3])
+    top3_breach = (
+        (top3_sum, top3_sum / total_ext)
+        if top3_sum > top3_cap else None
+    )
+    return single_breaches, top3_breach
+
 
+def _record_trend(total_ext: int, sizes: list[tuple[str, int, int]]) -> None:
+    """Append the current run to the trend log (Phase 5.3)."""
+    TREND_LOG.parent.mkdir(parents=True, exist_ok=True)
+    record = {
+        "ts": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+        "total": total_ext,
+        "rules": {name: ext for name, _, ext in sizes},
+    }
+    lines: list[str] = []
+    if TREND_LOG.exists():
+        lines = TREND_LOG.read_text(encoding="utf-8").splitlines()
+    lines.append(json.dumps(record, separators=(",", ":")))
+    if len(lines) > TREND_LOG_MAX_RECORDS:
+        lines = lines[-TREND_LOG_MAX_RECORDS:]
+    TREND_LOG.write_text("\n".join(lines) + "\n", encoding="utf-8")
 
-def _summary(rules: list[Path]) -> tuple[int, list[tuple[str, int]]]:
-    sizes = [(p.name, p.stat().st_size) for p in rules]
-    return sum(s for _, s in sizes), sorted(sizes, key=lambda x: -x[1])
+
+def _last_trend() -> dict | None:
+    """Return the most recent trend record, or None if log is empty."""
+    if not TREND_LOG.exists():
+        return None
+    lines = [
+        line for line in TREND_LOG.read_text(encoding="utf-8").splitlines()
+        if line.strip()
+    ]
+    if not lines:
+        return None
+    try:
+        return json.loads(lines[-1])
+    except json.JSONDecodeError:
+        return None
 
 
 def main() -> int:
@@ -54,6 +248,11 @@ def main() -> int:
         action="store_true",
         help="suppress the per-rule breakdown unless threshold is crossed",
     )
+    parser.add_argument(
+        "--no-trend",
+        action="store_true",
+        help="skip writing to .github/budget-trend.jsonl (Phase 5.3)",
+    )
     args = parser.parse_args()
 
     if not RULES_DIR.is_dir():
@@ -65,44 +264,110 @@ def main() -> int:
         print(f"❌  no always-rules found under {RULES_DIR}", file=sys.stderr)
         return 3
 
-    total, sizes = _summary(rules)
-    pct = total / TOTAL_CAP
-    over_per_rule = [(n, s) for n, s in sizes if s > PER_RULE_CAP]
-    top3 = sum(s for _, s in sizes[:3])
+    sizes: list[tuple[str, int, int]] = []
+    all_violations: list[tuple[str, str]] = []
+    for rule in rules:
+        ext, violations = _extended_size(rule)
+        sizes.append((rule.name, rule.stat().st_size, ext))
+        all_violations.extend(violations)
+
+    sizes.sort(key=lambda x: -x[2])
+    total_ext = sum(s[2] for s in sizes)
+    pct = total_ext / TOTAL_CAP
+    top3 = sum(s[2] for s in sizes[:3])
     top3_breach = top3 > TOP3_CAP
 
-    if pct >= FAIL_THRESHOLD or over_per_rule or top3_breach:
-        status = "❌  FAIL"
-        rc = 1
+    over_per_rule: list[tuple[str, int]] = []
+    grew_over_ceiling: list[tuple[str, int, int]] = []
+    for name, _, ext in sizes:
+        if ext <= PER_RULE_CAP:
+            continue
+        ceiling = KNOWN_PER_RULE_BREACHES.get(name)
+        if ceiling is None:
+            over_per_rule.append((name, ext))
+        elif ext > ceiling:
+            grew_over_ceiling.append((name, ext, ceiling))
+
+    in_tolerance = 1.0 <= pct <= 1.0 + TOLERANCE_BAND
+    baseline = _load_baseline() if RECOVERY_BAND_ENABLED else None
+    in_recovery_band = (
+        baseline is not None
+        and FAIL_THRESHOLD <= pct < 1.0
+        and total_ext < baseline
+    )
+    single_breaches, top3_concentration_breach = _concentration_check(
+        sizes, total_ext
+    )
+    failing = (
+        (
+            pct >= FAIL_THRESHOLD
+            and not in_tolerance
+            and not in_recovery_band
+            and pct < 1.0
+        )
+        or pct > 1.0 + TOLERANCE_BAND
+        or over_per_rule
+        or grew_over_ceiling
+        or top3_breach
+        or all_violations
+        or single_breaches
+        or top3_concentration_breach is not None
+    )
+    if failing:
+        status, rc = "❌  FAIL", 1
+    elif in_tolerance:
+        status, rc = "⚠️  WARN (G3 tolerance band)", 0
+    elif in_recovery_band:
+        status, rc = (
+            f"⚠️  WARN (recovery band, baseline {baseline:,})",
+            0,
+        )
     elif pct >= WARN_THRESHOLD:
-        status = "⚠️  WARN"
-        rc = 0
+        status, rc = "⚠️  WARN", 0
     else:
-        status = "✅  OK"
-        rc = 0
+        status, rc = "✅  OK", 0
 
     print(
-        f"{status}  always-rule budget: {total:,} / {TOTAL_CAP:,} chars "
-        f"({pct * 100:.1f}%) across {len(rules)} rule(s)"
+        f"{status}  always-rule extended budget: {total_ext:,} / "
+        f"{TOTAL_CAP:,} chars ({pct * 100:.1f}%) across {len(rules)} rule(s)"
     )
     print(
         f"      thresholds: warn {WARN_THRESHOLD * 100:.0f}% · "
         f"fail {FAIL_THRESHOLD * 100:.0f}% · "
-        f"per-rule ≤ {PER_RULE_CAP:,} · top-3 ≤ {TOP3_CAP:,}"
+        f"per-rule ≤ {PER_RULE_CAP:,} (ext) · top-3 ≤ {TOP3_CAP:,} (ext) · "
+        f"depth ≤ {MAX_DEPTH}"
     )
 
     if rc != 0 or pct >= WARN_THRESHOLD or not args.quiet:
         print()
-        print(f"      breakdown (largest first; top-3 sum = {top3:,}):")
-        for i, (name, size) in enumerate(sizes):
-            mark = "  ❌" if size > PER_RULE_CAP else ""
+        print(f"      breakdown (largest extended first; top-3 sum = {top3:,}):")
+        for i, (name, raw, ext) in enumerate(sizes):
             tag = " (top-3)" if i < 3 else ""
-            print(f"        {size:>5}  {name}{tag}{mark}")
+            ceiling = KNOWN_PER_RULE_BREACHES.get(name)
+            if ceiling is not None:
+                marker = f"  ⚠️  allowlisted ≤ {ceiling:,}"
+            elif ext > PER_RULE_CAP:
+                marker = "  ❌  per-rule breach"
+            else:
+                marker = ""
+            print(
+                f"        ext={ext:>5}  raw={raw:>5}  {name}{tag}{marker}"
+            )
 
     if over_per_rule:
         names = ", ".join(f"{n}={s:,}" for n, s in over_per_rule)
         print(
-            f"\n      Per-rule cap breach (> {PER_RULE_CAP:,} chars): {names}"
+            f"\n      Per-rule cap breach (> {PER_RULE_CAP:,} chars, not allowlisted): "
+            f"{names}"
+        )
+
+    if grew_over_ceiling:
+        details = ", ".join(
+            f"{n}={ext:,} > ceiling {ceiling:,}"
+            for n, ext, ceiling in grew_over_ceiling
+        )
+        print(
+            f"\n      Allowlisted-breach growth (regression): {details}"
         )
 
     if top3_breach:
@@ -111,12 +376,65 @@ def main() -> int:
             f"(top-3 must stay ≤ 50% of {TOTAL_CAP:,} total budget)."
         )
 
+    if all_violations:
+        print(
+            f"\n      Depth-{MAX_DEPTH} nesting cap violations:"
+        )
+        for rule_name, chain in all_violations:
+            print(f"        {rule_name}: {chain}")
+
+    if single_breaches:
+        details = ", ".join(
+            f"{n}={ext:,} ({frac * 100:.1f}%)"
+            for n, ext, frac in single_breaches
+        )
+        print(
+            f"\n      Concentration breach (single rule > "
+            f"{CONCENTRATION_SINGLE_PCT * 100:.0f}% of used budget, "
+            f"non-allowlisted): {details}"
+        )
+
+    if top3_concentration_breach is not None:
+        sum_, frac = top3_concentration_breach
+        print(
+            f"\n      Concentration breach (top-3 non-allowlisted > "
+            f"{CONCENTRATION_TOP3_PCT * 100:.0f}% of used budget): "
+            f"{sum_:,} ({frac * 100:.1f}%)"
+        )
+
+    # Phase 5.3 — per-rule trend delta vs. previous run.
+    prev = _last_trend()
+    if prev is not None and not args.quiet:
+        prev_total = prev.get("total")
+        prev_rules = prev.get("rules") or {}
+        if isinstance(prev_total, int):
+            delta_total = total_ext - prev_total
+            sign = "+" if delta_total >= 0 else ""
+            print(
+                f"\n      Trend vs. previous run "
+                f"({prev.get('ts', '?')}): total {sign}{delta_total:,} chars"
+            )
+            deltas: list[tuple[str, int, int]] = []
+            for name, _, ext in sizes:
+                old = prev_rules.get(name)
+                if isinstance(old, int) and old != ext:
+                    deltas.append((name, ext - old, ext))
+            if deltas:
+                deltas.sort(key=lambda x: -abs(x[1]))
+                for name, d, ext in deltas[:5]:
+                    s = "+" if d >= 0 else ""
+                    print(f"        {name}: {s}{d:,} (now {ext:,})")
+
+    if not args.no_trend:
+        _record_trend(total_ext, sizes)
+
     if rc == 1:
         print(
             f"\n      Action: trim the offending rule(s) via load_context: "
             f"extraction (see contexts/execution + contexts/authority) "
             f"until utilization drops below {FAIL_THRESHOLD * 100:.0f}% "
-            f"and all per-rule / top-3 caps hold."
+            f"and all per-rule / top-3 / depth caps hold. See "
+            f"docs/contracts/load-context-budget-model.md."
         )
 
     return rc

package/scripts/check_cluster_patterns.py

@@ -0,0 +1,159 @@
+#!/usr/bin/env python3
+"""Cluster-pattern compliance check.
+
+Compares each cluster dispatcher under
+`.agent-src.uncompressed/commands/<cluster>.md` against the Phase 1
+reference patterns (`fix.md`, `optimize.md`, `feature.md`).
+
+Required structure:
+
+  Frontmatter:
+    - `name: <cluster>`
+    - `cluster: <cluster>`
+    - `disable-model-invocation: true`
+
+  Body:
+    - `# /<cluster>` H1
+    - `## Sub-commands` section with a markdown table whose header is
+      exactly `Sub-command | Routes to | Purpose`
+    - `## Dispatch` section
+    - `## Rules` section
+
+Cluster files are detected by reading the locked-clusters table in
+`docs/contracts/command-clusters.md` (column-1 backticks).
+
+Exit codes: 0 = clean, 1 = pattern violations, 3 = internal error.
+"""
+from __future__ import annotations
+
+import re
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+COMMANDS_DIR = ROOT / ".agent-src.uncompressed/commands"
+CONTRACT = ROOT / "docs/contracts/command-clusters.md"
+
+REQUIRED_SECTIONS = ["## Sub-commands", "## Dispatch", "## Rules"]
+TABLE_HEADER_RE = re.compile(
+    r"\|\s*Sub-command\s*\|\s*Routes to\s*\|\s*Purpose\s*\|", re.IGNORECASE
+)
+
+
+@dataclass
+class FileReport:
+    path: Path
+    cluster: str
+    errors: list[str] = field(default_factory=list)
+
+
+def load_cluster_table() -> list[tuple[str, str]]:
+    """Return [(cluster_name, kind)] where kind ∈ {"dispatch", "flag"}."""
+    text = CONTRACT.read_text(encoding="utf-8")
+    in_table = False
+    rows: list[tuple[str, str]] = []
+    row_re = re.compile(
+        r"\|\s*`([a-z][a-z0-9-]*)`\s*\|\s*\d+\s*\|\s*([^|]+)\|"
+    )
+    for line in text.splitlines():
+        if line.startswith("## Locked clusters"):
+            in_table = True
+            continue
+        if in_table and line.startswith("## "):
+            break
+        if in_table:
+            m = row_re.match(line)
+            if m:
+                name, sub_col = m.group(1), m.group(2).strip().lower()
+                kind = "flag" if sub_col.startswith("flag:") else "dispatch"
+                rows.append((name, kind))
+    return rows
+
+
+def parse_frontmatter(text: str) -> tuple[dict[str, str], str]:
+    if not text.startswith("---\n"):
+        return {}, text
+    end = text.find("\n---\n", 4)
+    if end == -1:
+        return {}, text
+    fm: dict[str, str] = {}
+    for line in text[4:end].splitlines():
+        if line and not line.startswith(" ") and ":" in line:
+            k, _, v = line.partition(":")
+            fm[k.strip()] = v.strip()
+    body = text[end + len("\n---\n"):]
+    return fm, body
+
+
+def check_dispatcher(cluster: str) -> FileReport:
+    path = COMMANDS_DIR / f"{cluster}.md"
+    rep = FileReport(path=path, cluster=cluster)
+    if not path.exists():
+        rep.errors.append(f"dispatcher file missing: {path.relative_to(ROOT)}")
+        return rep
+    text = path.read_text(encoding="utf-8")
+    fm, body = parse_frontmatter(text)
+
+    # Frontmatter checks.
+    if fm.get("name") != cluster:
+        rep.errors.append(f"frontmatter `name:` is {fm.get('name')!r}, expected {cluster!r}")
+    if fm.get("cluster") != cluster:
+        rep.errors.append(f"frontmatter `cluster:` is {fm.get('cluster')!r}, expected {cluster!r}")
+    if fm.get("disable-model-invocation") != "true":
+        rep.errors.append("frontmatter `disable-model-invocation: true` missing")
+
+    # H1 check.
+    h1 = f"# /{cluster}"
+    if h1 not in body.splitlines()[:5]:
+        rep.errors.append(f"missing top-level heading {h1!r} in first 5 body lines")
+
+    # Section presence.
+    for section in REQUIRED_SECTIONS:
+        if section not in body:
+            rep.errors.append(f"missing section header {section!r}")
+
+    # Sub-commands table header (only meaningful if Sub-commands section exists).
+    if "## Sub-commands" in body and not TABLE_HEADER_RE.search(body):
+        rep.errors.append(
+            "Sub-commands table header must be `| Sub-command | Routes to | Purpose |`"
+        )
+    return rep
+
+
+def main() -> int:
+    rows = load_cluster_table()
+    if not rows:
+        print(f"❌  No clusters parsed from {CONTRACT.relative_to(ROOT)}",
+              file=sys.stderr)
+        return 3
+
+    dispatch_clusters = [n for n, k in rows if k == "dispatch"]
+    flag_clusters = [n for n, k in rows if k == "flag"]
+
+    reports = [check_dispatcher(n) for n in dispatch_clusters]
+    bad = [r for r in reports if r.errors]
+
+    # Flag clusters: only assert the file exists; legacy shape is preserved.
+    flag_missing = [n for n in flag_clusters
+                    if not (COMMANDS_DIR / f"{n}.md").exists()]
+    if flag_missing:
+        print(f"❌  Flag-cluster file(s) missing: {flag_missing}")
+        return 1
+
+    if bad:
+        print(f"❌  {len(bad)}/{len(reports)} cluster dispatcher(s) deviate "
+              f"from the Phase-1 reference pattern:")
+        for r in bad:
+            print(f"  • {r.path.relative_to(ROOT)} (cluster `{r.cluster}`)")
+            for err in r.errors:
+                print(f"      - {err}")
+        print(f"\nReference: commands/fix.md, commands/optimize.md, commands/feature.md")
+        return 1
+    print(f"✅  {len(reports)} cluster dispatcher(s) match the Phase-1 reference "
+          f"pattern; {len(flag_clusters)} flag-cluster(s) verified present.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/check_command_count_messaging.py

@@ -53,7 +53,9 @@ def canonical_counts() -> tuple[int, int, int]:
         print(f"❌  {COMMANDS_DIR.relative_to(ROOT)} not found", file=sys.stderr)
         sys.exit(1)
     total = shims = 0
-    for f in COMMANDS_DIR.glob("*.md"):
+    for f in COMMANDS_DIR.rglob("*.md"):
+        if f.name == "AGENTS.md":
+            continue
         total += 1
         m = FM_RE.match(f.read_text(encoding="utf-8"))
         fm = m.group(1) if m else ""
@@ -82,16 +84,21 @@ def main() -> int:
         # README.md
         (README, r"<strong>(\d+) Commands</strong>", active, "hero row"),
         (README, r"Browse all (\d+) active commands", active, "browse line"),
-        (README, r"\((\d+) files total ", total, "browse meta · total files"),
-        (README, r"— (\d+) are deprecation shims", shims, "browse meta · shims"),
         (README, r"\+ (\d+) native commands\)", active, "tools blurb"),
-        # AGENTS.md (`commands/  (84 files — 69 active + 15 deprecation shims)`)
-        (AGENTS, r"commands/\s+\((\d+) files —", total, "tree · total files"),
-        (AGENTS, r"files — (\d+) active", active, "tree · active"),
-        (AGENTS, r"active \+ (\d+) deprecation shims", shims, "tree · shims"),
         # docs/getting-started.md
         (GETTING_STARTED, r"Browse all (\d+) active commands", active, "browse line"),
     ]
+    # Shim-specific messaging only applies during a deprecation window.
+    # When shims == 0 the clauses are dropped from public docs entirely;
+    # re-add these patterns when a new deprecation cycle starts.
+    if shims > 0:
+        checks.extend([
+            (README, r"\((\d+) files total ", total, "browse meta · total files"),
+            (README, r"— (\d+) are deprecation shims", shims, "browse meta · shims"),
+            (AGENTS, r"commands/\s+\((\d+) files —", total, "tree · total files"),
+            (AGENTS, r"files — (\d+) active", active, "tree · active"),
+            (AGENTS, r"active \+ (\d+) deprecation shims", shims, "tree · shims"),
+        ])
 
     errors: list[str] = []
     for path, pattern, expected, label in checks: