@caddis/cli 0.2.6 → 0.4.0

package/bundles/antigravity-plugin/scripts/claudster_migrate_rules.py

@@ -0,0 +1,300 @@
+"""claudster_migrate_rules — migrate a repo's rules hierarchy to AGENTS.md-canonical + CLAUDE.md shims.
+
+`AGENTS.md` is the canonical rules file every agent reads (Claude Code, Codex CLI, Antigravity); each
+`CLAUDE.md` becomes a thin `@AGENTS.md` import shim. This tool migrates an existing repo — root pair +
+every subfolder `CLAUDE.md` — to that layout, safely and idempotently.
+
+Behavior (per target repo):
+  • ROOT: CLAUDE.md's (fuller, possibly enriched) content becomes the canonical AGENTS.md, re-headed
+    agent-neutrally; CLAUDE.md becomes the shim. An existing AGENTS.md that is the old caddis mirror
+    (a subset of CLAUDE.md) is replaced. If the existing AGENTS.md carries content CLAUDE.md LACKS
+    (project enrichments on both sides), it is a CONFLICT — the root pair is skipped and reported
+    (exit 1); a human resolves the few by hand-merge, then re-runs to confirm.
+  • SUBFOLDERS: each <dir>/CLAUDE.md is `git mv`'d to <dir>/AGENTS.md (content verbatim) + a <dir>/CLAUDE.md shim.
+  • Idempotent (a re-run is a no-op); refuses a dirty tree (unless --allow-dirty); `--dry-run` is the
+    default (`--apply` executes); `git mv` when tracked; never touches archived `done/`-style files.
+  • --check (fork detector): flags any CLAUDE.md that is NOT a shim beside an AGENTS.md (drifted shim),
+    and any bare CLAUDE.md with no sibling AGENTS.md (a hand-created fork). Exit 1 on findings.
+
+Usage:
+    python scripts/claudster_migrate_rules.py [target]              # dry-run (default)
+    python scripts/claudster_migrate_rules.py [target] --apply      # execute
+    python scripts/claudster_migrate_rules.py [target] --check      # fork detector (gate)
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+# Reuse the harness templates + folder shim so the migration output matches what the generator emits.
+try:
+    from setup_project_ai import HARNESS_DIR, SUBFOLDER_SHIM, render as _render
+except Exception:  # pragma: no cover — standalone fallback if setup_project_ai isn't importable
+    HARNESS_DIR = None
+    SUBFOLDER_SHIM = ("# Folder conventions — canonical in AGENTS.md (imported below; Claude Code inlines it)\n"
+                      "@AGENTS.md\n")
+
+    def _render(text, mapping):  # type: ignore
+        for k, v in mapping.items():
+            text = text.replace("{{" + k + "}}", v)
+        return text
+
+# Directories we never migrate into (vendored/generated + archived rules).
+SKIP_DIRS = {".git", "node_modules", ".venv", "venv", "__pycache__", ".mypy_cache", ".ruff_cache",
+             ".pytest_cache", "dist", "build", ".tanstack", "done", "archive", "archived"}
+
+# Section headings whose bodies are pure template boilerplate — their wording differs between the old
+# root.md.tmpl and agents.md.tmpl, so they are excluded from the divergence check (only PROJECT content
+# is compared). "What this project is" is intentionally NOT here — its content IS compared.
+_BOILERPLATE_HEADING_KEYS = (
+    "the laws", "the harness", "development harness", "context discipline", "conventions",
+    "where things live", "doc discipline", "resuming a session", "resources", "why subagents",
+)
+
+_CANONICAL_PREAMBLE = (
+    "> **This is the canonical rules file.** Every coding agent reads it — Claude Code (via the one-line\n"
+    "> `@AGENTS.md` import in `CLAUDE.md`), OpenAI Codex CLI, and Antigravity (`agy`). `CLAUDE.md` is a\n"
+    "> thin `@AGENTS.md` import shim; keep durable project rules HERE, never in the shim."
+)
+
+
+# ── git helpers ──────────────────────────────────────────────────────────────
+def _git(target: Path, *args: str) -> subprocess.CompletedProcess:
+    return subprocess.run(["git", *args], cwd=str(target), capture_output=True, text=True)
+
+
+def _in_git_repo(target: Path) -> bool:
+    r = _git(target, "rev-parse", "--is-inside-work-tree")
+    return r.returncode == 0 and r.stdout.strip() == "true"
+
+
+def _is_dirty(target: Path) -> bool:
+    return bool(_git(target, "status", "--porcelain").stdout.strip())
+
+
+def _is_tracked(target: Path, rel: str) -> bool:
+    return bool(_git(target, "ls-files", "--error-unmatch", rel).returncode == 0)
+
+
+# ── content helpers ──────────────────────────────────────────────────────────
+def is_shim(text: str) -> bool:
+    """A CLAUDE.md is a shim iff it carries a bare `@AGENTS.md` import line."""
+    return any(ln.strip() == "@AGENTS.md" for ln in text.splitlines())
+
+
+def _project_name(claude_text: str, target: Path) -> str:
+    for ln in claude_text.splitlines():
+        if ln.startswith("# "):
+            title = ln[2:].strip()
+            # "<name> — Project Memory (root)" -> "<name>"
+            for sep in (" — ", " - ", " –– "):
+                if sep in title:
+                    return title.split(sep, 1)[0].strip()
+            return title
+    return target.name
+
+
+def _meaningful(text: str) -> set[str]:
+    """Normalized set of content lines (md markers/whitespace stripped), for subset comparison."""
+    out: set[str] = set()
+    for ln in text.splitlines():
+        s = ln.strip().lstrip("#>-*").strip()
+        # drop an ordered-list prefix like "1. "
+        while s[:1].isdigit():
+            s = s[1:]
+        s = s.lstrip(". ").strip()
+        if len(s) >= 8:
+            out.add(s.lower())
+    return out
+
+
+def _checkable_lines(agents_text: str) -> set[str]:
+    """AGENTS.md's PROJECT content — meaningful lines from non-boilerplate-heading sections (and the
+    preamble is dropped). Compared against CLAUDE.md to detect divergence."""
+    lines = agents_text.splitlines()
+    # find section spans by "## " headings
+    heads = [i for i, l in enumerate(lines) if l.startswith("## ")]
+    out: set[str] = set()
+    for k, start in enumerate(heads):
+        heading = lines[start][3:].strip().lower()
+        if any(key in heading for key in _BOILERPLATE_HEADING_KEYS):
+            continue
+        end = heads[k + 1] if k + 1 < len(heads) else len(lines)
+        out |= _meaningful("\n".join(lines[start:end]))
+    return out
+
+
+def root_conflict(claude_text: str, agents_text: str) -> list[str]:
+    """Return AGENTS.md project lines that CLAUDE.md lacks (the enrichment residue). Non-empty => the
+    two files diverged and must not be auto-merged."""
+    residue = _checkable_lines(agents_text) - _meaningful(claude_text)
+    return sorted(residue)
+
+
+def reheaded_agents(claude_text: str, name: str) -> str:
+    """Canonical AGENTS.md from CLAUDE.md content: replace the shim/mirror preamble (everything before
+    the first `## ` heading) with a canonical header + preamble; keep the body (enrichments) verbatim."""
+    lines = claude_text.splitlines()
+    idx = next((i for i, l in enumerate(lines) if l.startswith("## ")), None)
+    body = "\n".join(lines[idx:]) if idx is not None else claude_text
+    header = f"# {name} — Project Memory (canonical rules)\n\n{_CANONICAL_PREAMBLE}\n\n"
+    text = header + body
+    return text if text.endswith("\n") else text + "\n"
+
+
+def root_shim(name: str) -> str:
+    """The root CLAUDE.md shim — the harness root.md.tmpl rendered (reused, so no drift)."""
+    if HARNESS_DIR is not None:
+        tmpl = HARNESS_DIR / "claude-md" / "root.md.tmpl"
+        if tmpl.is_file():
+            return _render(tmpl.read_text(encoding="utf-8"), {"PROJECT_NAME": name})
+    return (f"# {name} — Project Memory\n\n@AGENTS.md\n\n"
+            "> **Canonical rules live in `AGENTS.md`** (imported above — Claude Code inlines it). This\n"
+            "> shim adds only Claude-native conveniences; durable rules go in `AGENTS.md`.\n")
+
+
+# ── migration steps ──────────────────────────────────────────────────────────
+def _write(target: Path, rel: str, content: str, apply: bool, report: list[str], verb: str):
+    report.append(f"{verb}: {rel}")
+    if apply:
+        dest = target / rel
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(content, encoding="utf-8")
+
+
+def _move(target: Path, src_rel: str, dst_rel: str, apply: bool, report: list[str]):
+    report.append(f"move: {src_rel} -> {dst_rel}")
+    if not apply:
+        return
+    if _is_tracked(target, src_rel):
+        r = _git(target, "mv", src_rel, dst_rel)
+        if r.returncode == 0:
+            return
+    # untracked (or git mv failed): plain rename
+    (target / dst_rel).parent.mkdir(parents=True, exist_ok=True)
+    os.replace(target / src_rel, target / dst_rel)
+
+
+def migrate_root(target: Path, apply: bool, report: list[str]) -> int:
+    """Migrate the root pair. Returns 1 on conflict (root skipped), else 0."""
+    claude = target / "CLAUDE.md"
+    agents = target / "AGENTS.md"
+    if not claude.exists() and not agents.exists():
+        report.append("root: no CLAUDE.md/AGENTS.md — nothing to migrate")
+        return 0
+    claude_text = claude.read_text(encoding="utf-8") if claude.exists() else ""
+    if claude.exists() and is_shim(claude_text) and agents.exists():
+        report.append("root: already migrated (CLAUDE.md is a shim) — no-op")
+        return 0
+    if not claude.exists():
+        report.append("root: AGENTS.md present, no CLAUDE.md — leaving as-is (already canonical or hand-authored)")
+        return 0
+    name = _project_name(claude_text, target)
+    if agents.exists():
+        conflict = root_conflict(claude_text, agents.read_text(encoding="utf-8"))
+        if conflict:
+            report.append("root: CONFLICT — AGENTS.md carries content CLAUDE.md lacks; skipping root pair. "
+                          "Hand-merge into CLAUDE.md, then re-run. Divergent line(s): "
+                          + "; ".join(conflict[:5]) + (" …" if len(conflict) > 5 else ""))
+            return 1
+    # safe: CLAUDE.md content -> canonical AGENTS.md; CLAUDE.md -> shim
+    _write(target, "AGENTS.md", reheaded_agents(claude_text, name), apply, report,
+           "rewrite (canonical)" if agents.exists() else "create (canonical)")
+    _write(target, "CLAUDE.md", root_shim(name), apply, report, "shim")
+    return 0
+
+
+def _iter_subfolder_claude(target: Path):
+    for dirpath, dirnames, filenames in os.walk(target):
+        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
+        d = Path(dirpath)
+        if d == target:
+            continue  # root handled separately
+        if "CLAUDE.md" in filenames:
+            yield d
+
+
+def migrate_subfolders(target: Path, apply: bool, report: list[str]) -> None:
+    for d in _iter_subfolder_claude(target):
+        rel = d.relative_to(target).as_posix()
+        claude_text = (d / "CLAUDE.md").read_text(encoding="utf-8")
+        if is_shim(claude_text) and (d / "AGENTS.md").exists():
+            report.append(f"{rel}/: already migrated — no-op")
+            continue
+        if (d / "AGENTS.md").exists():
+            report.append(f"{rel}/: CONFLICT — both AGENTS.md and a non-shim CLAUDE.md present; skipped")
+            continue
+        _move(target, f"{rel}/CLAUDE.md", f"{rel}/AGENTS.md", apply, report)
+        _write(target, f"{rel}/CLAUDE.md", SUBFOLDER_SHIM, apply, report, "shim")
+
+
+def check_forks(target: Path) -> list[str]:
+    """Fork detector: non-shim CLAUDE.md beside an AGENTS.md, or a bare CLAUDE.md with no sibling AGENTS.md."""
+    findings: list[str] = []
+    for dirpath, dirnames, filenames in os.walk(target):
+        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
+        if "CLAUDE.md" not in filenames:
+            continue
+        d = Path(dirpath)
+        rel = (d / "CLAUDE.md").relative_to(target).as_posix()
+        text = (d / "CLAUDE.md").read_text(encoding="utf-8", errors="replace")
+        if "AGENTS.md" in filenames:
+            if not is_shim(text):
+                findings.append(f"{rel}: CLAUDE.md is not a shim but a sibling AGENTS.md exists (drifted shim)")
+        else:
+            findings.append(f"{rel}: CLAUDE.md has no sibling AGENTS.md (hand-created fork — run /caddis:add-rules semantics)")
+    return findings
+
+
+# ── main ─────────────────────────────────────────────────────────────────────
+def main(argv: list[str] | None = None) -> int:
+    for _stream in (sys.stdout, sys.stderr):  # Windows cp1252 can't encode em-dashes in our messages
+        if hasattr(_stream, "reconfigure"):
+            _stream.reconfigure(encoding="utf-8")
+    ap = argparse.ArgumentParser(description="Migrate a repo to AGENTS.md-canonical rules + CLAUDE.md shims.")
+    ap.add_argument("target", nargs="?", default=".", type=Path)
+    ap.add_argument("--apply", action="store_true", help="Execute (default is --dry-run).")
+    ap.add_argument("--allow-dirty", action="store_true", help="Proceed even if the working tree is dirty.")
+    ap.add_argument("--check", action="store_true", help="Fork detector only (gate mode); exit 1 on findings.")
+    args = ap.parse_args(argv)
+
+    target = args.target.resolve()
+    if not target.is_dir():
+        print(f"ERROR: target not a directory: {target}", file=sys.stderr)
+        return 2
+
+    if args.check:
+        findings = check_forks(target)
+        for f in findings:
+            print(f"  fork: {f}")
+        if findings:
+            print(f"\n{len(findings)} rules-file fork(s) found.")
+            return 1
+        print("No rules-file forks — CLAUDE.md shims are clean.")
+        return 0
+
+    apply = args.apply
+    if not _in_git_repo(target):
+        print(f"ERROR: {target} is not a git repository (rules migration uses git mv).", file=sys.stderr)
+        return 2
+    if apply and _is_dirty(target) and not args.allow_dirty:
+        print("ERROR: working tree is dirty — commit/stash first, or pass --allow-dirty.", file=sys.stderr)
+        return 2
+
+    print(f"=== caddis-migrate-rules -> {target} {'(APPLY)' if apply else '(dry-run)'}")
+    report: list[str] = []
+    rc = migrate_root(target, apply, report)
+    migrate_subfolders(target, apply, report)
+    for line in report:
+        print(f"   {line}")
+    if not apply:
+        print("\n(dry-run — no files changed; pass --apply to execute)")
+    print(f"\nresult: {'CONFLICT (root skipped)' if rc else 'ok'}")
+    return rc
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundles/antigravity-plugin/scripts/enforcement_inventory.py

@@ -0,0 +1,261 @@
+#!/usr/bin/env python3
+"""Inventory caddis's load-bearing rules, and measure how many are actually enforced.
+
+WHY THIS EXISTS
+---------------
+Three independent audits reached the same conclusion in different words: strip the prose from
+this plugin and the machine content is very small. Nearly every "MUST" / "NEVER" / "STOP" is a
+sentence in a markdown file that a model may or may not honour. Those degrade silently under
+model change, context pressure, a cheaper lane, or a distracted session — and they read as
+guarantees, which is worse than reading as advice.
+
+The things that actually held under pressure were the ones with exit codes: pytest,
+validate_pool, the hooks, oss_review's exit 2.
+
+So this script measures the ratio of rules that a machine can fail on, to rules that only a
+model can choose to honour. That number is the health metric for the plugin. It is expected to
+start LOW; the point is that it is visible and moves in one direction.
+
+THE ANTI-FLATTERY RULE
+----------------------
+The classification is DERIVED FROM THE LINT TESTS, never asserted by hand. A rule counts as
+`machine` only when a test that targets its file asserts a literal string contained in that
+rule's text — i.e. deleting the rule would turn a test red. Everything else is `advisory`.
+
+This matters because the first version of this script DID use a hand-written registry, and it
+was wrong in both directions: a global substring match credited an unrelated skill's "ALWAYS ask
+via AskUserQuestion" to the headless-mode test, while genuinely-covered rules went uncounted
+because their sentence lacked the registry keyword. A metric you can talk yourself into is not a
+metric. Deriving it from the tests also means it moves on its own the moment someone adds or
+removes a lint, which is the only way a health number stays honest.
+
+Known limit, stated rather than hidden: matching is per-line, so a rule spanning two lines can be
+missed, and a long asserted literal can match a neighbouring sentence. Treat the ratio as an
+order-of-magnitude signal and a direction of travel, not a precise score.
+
+Usage:
+  python scripts/enforcement_inventory.py            # summary + ratio
+  python scripts/enforcement_inventory.py --list     # every rule, classified
+  python scripts/enforcement_inventory.py --advisory # only the unenforced ones
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+
+REPO = Path(__file__).resolve().parents[1]
+SCAN_ROOTS = [REPO / "claude-harness" / "commands", REPO / ".github" / "skills"]
+
+# An imperative that makes a promise. Ordered longest-first so MUST NOT wins over MUST.
+IMPERATIVE = re.compile(
+    r"\b(MUST NOT|MUST|NEVER|ALWAYS|REQUIRED|STOP|DO NOT|Do not)\b"
+)
+
+# ── Deriving enforcement FROM THE TESTS, not from a hand-written claim ──────
+# An earlier version used a hand-maintained registry of rule->enforcer. It was wrong in both
+# directions: a global substring match credited brand-design's "ALWAYS ask via AskUserQuestion"
+# to the headless-mode test, which has nothing to do with it, while genuinely-covered rules went
+# uncounted because their sentence lacked the registry's keyword.
+#
+# So the classifier now READS THE LINT TESTS. For each test module it works out which source
+# files that module targets (from its module-level Path constants) and which literal strings it
+# asserts on. A rule is `machine` when a test targeting ITS file asserts a literal contained in
+# its text. Nothing is claimed that a test does not actually check, and the metric updates itself
+# the moment someone adds or deletes a lint - which is the property a health metric must have.
+LINT_TEST_DIRS = [REPO / "scripts" / "tests", REPO / "claude-harness" / "hooks" / "tests"]
+
+# Literals shorter than this match too much to mean anything.
+MIN_LITERAL = 10
+
+
+def _test_modules() -> list[tuple[set[str], set[str]]]:
+    """(source files this test targets, literals it asserts) for every lint test module."""
+    import ast
+    out = []
+    for d in LINT_TEST_DIRS:
+        if not d.exists():
+            continue
+        for f in sorted(d.glob("test_*.py")):
+            if f.name == "test_enforcement_inventory.py":
+                continue  # measures the metric; must not feed it
+            try:
+                tree = ast.parse(f.read_text(encoding="utf-8", errors="ignore"))
+            except SyntaxError:
+                continue
+            # ONLY literals inside an `assert` count. Scanning every string constant swept in
+            # docstrings and fixture data, and this module's own test docstrings describe the very
+            # rules being measured - so prose about a rule was being counted as enforcement OF that
+            # rule. The metric was measuring how much we had WRITTEN about enforcement.
+            literals: set[str] = set()
+            for node in ast.walk(tree):
+                if not isinstance(node, ast.Assert):
+                    continue
+                for sub in ast.walk(node):
+                    if isinstance(sub, ast.Constant) and isinstance(sub.value, str):
+                        v = sub.value.strip()
+                        if len(v) >= MIN_LITERAL:
+                            literals.add(v)
+            # TARGETS come from ALL string constants, not just asserts: a module names the file
+            # it lints in a module-level Path constant (`_IMPLEMENT = ... / "implement.md"`), which
+            # is not an assert. Deriving both from the assert set emptied every target and drove
+            # the ratio to a false 0.0% - caught by this module's own plausibility test.
+            targets = {
+                v.strip() for node in ast.walk(tree)
+                if isinstance(node, ast.Constant) and isinstance(node.value, str)
+                for v in [node.value] if v.strip().endswith(".md")
+            }
+            out.append((targets, literals))
+    return out
+
+
+_MODULES = _test_modules()
+
+
+def _enforcer_for(rel_path: str, text: str) -> str | None:
+    """The lint that would fail if this rule were deleted, or None."""
+    fname = rel_path.rsplit("/", 1)[-1]
+    for targets, literals in _MODULES:
+        if not any(t == fname or t.endswith(fname) for t in targets):
+            continue
+        for lit in literals:
+            if lit.lower() in text.lower():
+                return "lint"
+    return None
+
+
+# ── Gates: rules enforced by an executable, not merely by a content lint ────
+# The first version counted only lint tests, so a rule backed by a REAL gate scored the same as
+# one backed by nothing - the metric was blind to the strongest form of enforcement and would
+# have shown no movement for the phase that introduced it. A rule counts as gate-enforced when
+# its file invokes caddis_gate.py AND the rule concerns one of the gate's actual subcommands.
+# The subcommand must exist in the script: a claim nobody implements is exactly what this file
+# refuses to reward.
+GATE_SCRIPT = REPO / "scripts" / "caddis_gate.py"
+GATE_CONCERNS = {
+    "lane-check": ("lane", "spawn", "launch command", "--print", "-p"),
+    "verdict-gate": ("verdict", "advisory-hub", "blocked-pending-hub", "accept-degraded"),
+    "tracker-vs-git": ("tracker",),
+}
+
+
+def _live_gates() -> dict[str, tuple[str, ...]]:
+    """Subcommands the gate script actually implements. Verified, never assumed."""
+    if not GATE_SCRIPT.is_file():
+        return {}
+    src = GATE_SCRIPT.read_text(encoding="utf-8", errors="ignore")
+    return {k: v for k, v in GATE_CONCERNS.items() if f'"{k}"' in src or f"'{k}'" in src}
+
+
+_GATES = _live_gates()
+
+
+def _gate_for(file_text: str, text: str) -> str | None:
+    if "caddis_gate.py" not in file_text:
+        return None
+    low = text.lower()
+    for sub, needles in _GATES.items():
+        if any(n.lower() in low for n in needles):
+            return sub
+    return None
+
+
+@dataclass
+class Rule:
+    path: str
+    line: int
+    marker: str
+    text: str
+    enforcer: str | None = None
+
+    @property
+    def machine(self) -> bool:
+        return self.enforcer is not None
+
+
+def _sentence(line: str) -> str:
+    return " ".join(line.split())[:150]
+
+
+def collect(roots: list[Path] | None = None) -> list[Rule]:
+    rules: list[Rule] = []
+    for root in (roots or SCAN_ROOTS):
+        if not root.exists():
+            continue
+        for f in sorted(root.rglob("*.md")):
+            try:
+                lines = f.read_text(encoding="utf-8", errors="ignore").splitlines()
+            except Exception:
+                continue
+            # Fall back to the absolute path for roots outside the repo, so collect() can be
+            # pointed at a fixture directory. A metric script that cannot be tested on a fixture
+            # can only be verified by eyeballing its output, which is how metrics start lying.
+            whole = "\n".join(lines)
+            try:
+                rel = str(f.relative_to(REPO)).replace("\\", "/")
+            except ValueError:
+                rel = str(f).replace("\\", "/")
+            for i, line in enumerate(lines, 1):
+                m = IMPERATIVE.search(line)
+                if not m:
+                    continue
+                text = _sentence(line)
+                enf = _enforcer_for(rel, text) or _gate_for(whole, text)
+                rules.append(Rule(rel, i, m.group(1), text, enf))
+    return rules
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description="caddis enforcement inventory")
+    ap.add_argument("--list", action="store_true", help="print every rule, classified")
+    ap.add_argument("--advisory", action="store_true", help="print only the unenforced rules")
+    args = ap.parse_args(argv)
+
+    rules = collect()
+    machine = [r for r in rules if r.machine]
+    advisory = [r for r in rules if not r.machine]
+    total = len(rules)
+    ratio = (len(machine) / total) if total else 0.0
+
+    if args.list or args.advisory:
+        for r in rules:
+            if args.advisory and r.machine:
+                continue
+            tag = f"machine <- {r.enforcer}" if r.machine else "advisory"
+            print(f"  [{tag}] {r.path}:{r.line}  {r.marker}")
+            print(f"      {r.text}")
+        print()
+
+    # Report the SPLIT, not just the headline. A single blended number is actively misleading:
+    # it is dominated by the ~235 skill rules, which are guidance ("prefer this", "consider that")
+    # and SHOULD be advisory - turning them into exit codes would be theatre. The number that
+    # matters is commands, because that is the execution path where a broken guarantee costs you.
+    cmd = [r for r in rules if "/commands/" in r.path]
+    skl = [r for r in rules if "/commands/" not in r.path]
+    def _pct(group):
+        return (sum(1 for r in group if r.machine) / len(group)) if group else 0.0
+
+    print("=" * 62)
+    print(f"  load-bearing rules found : {total}")
+    print(f"  machine-enforced         : {len(machine)}")
+    print(f"  advisory only            : {len(advisory)}")
+    print("-" * 62)
+    print(f"  COMMANDS (execution path): {sum(1 for r in cmd if r.machine)}/{len(cmd)}  "
+          f"= {_pct(cmd):.1%}   <- the figure that matters")
+    print(f"  SKILLS   (guidance)      : {sum(1 for r in skl if r.machine)}/{len(skl)}  "
+          f"= {_pct(skl):.1%}   (advisory is correct here)")
+    print(f"  blended                  : {ratio:.1%}")
+    print("=" * 62)
+    print("  A low number is not a bug report - it is the starting point. Advisory rules are")
+    print("  legitimate; the danger is an advisory rule that READS like a guarantee. Move the")
+    print("  load-bearing ones to exit codes, and label the rest honestly.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())