@event4u/agent-config 1.16.0 → 1.17.0

package/scripts/check_context_paths.py

@@ -0,0 +1,201 @@
+#!/usr/bin/env python3
+"""Context-file path & orphan checker.
+
+Validates that every `*.md` under `.agent-src.uncompressed/contexts/`:
+
+1. Lives in a locked sub-tree (or is one of six grandfathered root files).
+2. Does not collide on basename with another context file in another sub-tree.
+3. Is referenced by at least one rule, skill, command, or other context
+   (via `load_context:` frontmatter or a markdown body path mention).
+
+Contract: docs/contracts/context-paths.md
+Roadmap:  road-to-structural-optimization.md § 0.6
+
+Exit codes: 0 = clean, 1 = violations, 3 = internal error.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+CONTEXTS_ROOT = ROOT / ".agent-src.uncompressed" / "contexts"
+
+# Sub-trees that may contain context files. Update in lock-step with
+# docs/contracts/context-paths.md whenever a roadmap revision adds one.
+LOCKED_SUBTREES = (
+    "communication/rules-always",
+    "communication/rules-auto",
+    "judges",
+    "analysis",
+    "skills",
+    "chat-history",
+    "execution",
+    "authority",
+)
+
+# Files allowed to remain at the contexts root. Anything else at the root
+# fails the path check. New context files MUST live in a sub-tree.
+GRANDFATHERED_ROOT_FILES = frozenset({
+    "augment-infrastructure.md",
+    "documentation-hierarchy.md",
+    "model-recommendations.md",
+    "override-system.md",
+    "skills-and-commands.md",
+    "subagent-configuration.md",
+})
+
+# Directories whose content we scan for references to a context file.
+# `agents/roadmaps` is included because in-flight roadmap docs are
+# legitimate referrers during multi-phase rollouts — a context can land
+# in phase N while its first rule/skill referrer lands in phase N+k.
+# Without this scan dir, every newly-introduced context would orphan
+# until the consuming artefact lands, blocking phase-by-phase commits.
+REFERENCE_SCAN_DIRS = (
+    ".agent-src.uncompressed/rules",
+    ".agent-src.uncompressed/skills",
+    ".agent-src.uncompressed/commands",
+    ".agent-src.uncompressed/contexts",
+    "agents/roadmaps",
+)
+
+
+@dataclass
+class Violation:
+    file: str
+    kind: str          # "out-of-tree" | "root-not-grandfathered" | "collision" | "orphan"
+    detail: str
+
+
+def _collect_contexts(root: Path) -> list[Path]:
+    if not (root / CONTEXTS_ROOT.relative_to(ROOT)).exists():
+        return []
+    return sorted((root / CONTEXTS_ROOT.relative_to(ROOT)).rglob("*.md"))
+
+
+def _check_path(ctx: Path, contexts_root: Path) -> Violation | None:
+    rel = ctx.relative_to(contexts_root)
+    parts = rel.parts
+    if len(parts) == 1:
+        if parts[0] not in GRANDFATHERED_ROOT_FILES:
+            return Violation(
+                file=str(ctx),
+                kind="root-not-grandfathered",
+                detail=(f"new file at contexts/ root — must live in one of "
+                        f"{sorted(LOCKED_SUBTREES)} or be added to "
+                        "GRANDFATHERED_ROOT_FILES via a roadmap revision"),
+            )
+        return None
+    subtree = "/".join(parts[:-1])
+    # Allow nested matches: e.g. communication/rules-always/foo/bar.md still
+    # lives under "communication/rules-always". Direct prefix match suffices.
+    for allowed in LOCKED_SUBTREES:
+        if subtree == allowed or subtree.startswith(allowed + "/"):
+            return None
+    return Violation(
+        file=str(ctx),
+        kind="out-of-tree",
+        detail=(f"sub-tree '{subtree}' is not in LOCKED_SUBTREES — see "
+                "docs/contracts/context-paths.md to add a new sub-tree"),
+    )
+
+
+def _check_collisions(contexts: list[Path], contexts_root: Path) -> list[Violation]:
+    by_name: dict[str, list[Path]] = {}
+    for ctx in contexts:
+        by_name.setdefault(ctx.name, []).append(ctx)
+    out: list[Violation] = []
+    for name, paths in by_name.items():
+        if len(paths) <= 1:
+            continue
+        rels = sorted(str(p.relative_to(contexts_root)) for p in paths)
+        for p in paths:
+            out.append(Violation(
+                file=str(p),
+                kind="collision",
+                detail=f"basename '{name}' shared with: {', '.join(r for r in rels if r != str(p.relative_to(contexts_root)))}",
+            ))
+    return out
+
+
+def _build_reference_corpus(root: Path) -> str:
+    chunks: list[str] = []
+    for d in REFERENCE_SCAN_DIRS:
+        base = root / d
+        if not base.exists():
+            continue
+        for f in base.rglob("*.md"):
+            try:
+                chunks.append(f.read_text(encoding="utf-8"))
+            except OSError:
+                continue
+    return "\n".join(chunks)
+
+
+def _check_orphans(contexts: list[Path], corpus: str, root: Path) -> list[Violation]:
+    out: list[Violation] = []
+    for ctx in contexts:
+        rel_src = str(ctx.relative_to(root))                       # .agent-src.uncompressed/contexts/...
+        rel_short = rel_src.split("contexts/", 1)[-1]               # judges/persona-voice-rubric.md
+        candidates = (rel_src, f"contexts/{rel_short}", rel_short)
+        # Exclude self-references: drop this file's own content from the
+        # corpus check by reading the file and subtracting its substring.
+        try:
+            own_text = ctx.read_text(encoding="utf-8")
+        except OSError:
+            own_text = ""
+        external_corpus = corpus.replace(own_text, "") if own_text else corpus
+        if not any(c in external_corpus for c in candidates):
+            out.append(Violation(
+                file=str(ctx),
+                kind="orphan",
+                detail="not referenced by any rule, skill, command, or other context",
+            ))
+    return out
+
+
+def scan(root: Path) -> list[Violation]:
+    contexts_root = root / CONTEXTS_ROOT.relative_to(ROOT)
+    contexts = _collect_contexts(root)
+    violations: list[Violation] = []
+    for ctx in contexts:
+        v = _check_path(ctx, contexts_root)
+        if v:
+            violations.append(v)
+    violations.extend(_check_collisions(contexts, contexts_root))
+    corpus = _build_reference_corpus(root)
+    violations.extend(_check_orphans(contexts, corpus, root))
+    return violations
+
+
+def format_text(violations: list[Violation]) -> str:
+    if not violations:
+        return "✅  No context-path violations."
+    lines = [f"❌  Found {len(violations)} context-path violation(s):\n"]
+    for v in violations:
+        lines.append(f"  🔴 [{v.kind}] {v.file}\n      {v.detail}")
+    return "\n".join(lines)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--format", choices=["text", "json"], default="text")
+    parser.add_argument("--root", type=Path, default=ROOT)
+    args = parser.parse_args()
+    try:
+        violations = scan(args.root)
+    except Exception as e:    # pragma: no cover
+        print(f"Internal error: {e}", file=sys.stderr)
+        return 3
+    if args.format == "json":
+        print(json.dumps([asdict(v) for v in violations], indent=2))
+    else:
+        print(format_text(violations))
+    return 1 if violations else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/check_no_roadmap_refs.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+"""No-roadmap-references checker.
+
+Stable artifacts (rules, skills, commands, contexts, guidelines, AGENTS.md,
+README, copilot-instructions) must NOT cite a specific roadmap file in
+`agents/roadmaps/`. Roadmap files are transient — archived, skipped, or
+deleted as work completes — and stable artifacts citing them rot.
+
+Allowed: directory mentions (`agents/roadmaps/`, `agents/roadmaps/archive/`,
+`agents/roadmaps/skipped/`). Forbidden: specific `*.md` files inside those
+directories.
+
+Contract: .agent-src.uncompressed/rules/no-roadmap-references.md
+
+Exit codes: 0 = clean, 1 = violations, 3 = internal error.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+
+# Stable artefact trees — every `*.md` below MUST be free of roadmap-file
+# citations. Directory mentions stay allowed (the regex below excludes them).
+STABLE_TREES = (
+    ".agent-src.uncompressed/rules",
+    ".agent-src.uncompressed/skills",
+    ".agent-src.uncompressed/commands",
+    ".agent-src.uncompressed/contexts",
+    ".agent-src.uncompressed/templates",
+    ".agent-src.uncompressed/personas",
+    "agents/contexts",
+    "docs/guidelines",
+    "docs/contracts",
+)
+
+# Stable single-file artefacts at well-known paths.
+STABLE_FILES = (
+    "AGENTS.md",
+    "README.md",
+    "copilot-instructions.md",
+    "docs/architecture.md",
+    "docs/customization.md",
+    "docs/getting-started.md",
+    "docs/catalog.md",
+)
+
+# Roadmap-file pattern: any `*.md` file under `agents/roadmaps/` at any
+# depth (including `archive/`, `skipped/`, and nested topical subfolders
+# like `agent-memory/`). Directory-only mentions (`agents/roadmaps/`
+# with trailing slash, no filename) and placeholder mentions like
+# `agents/roadmaps/<file>.md` (angle-bracket placeholder) do NOT match.
+ROADMAP_FILE_RE = re.compile(
+    r"agents/roadmaps/(?:[a-z0-9][a-z0-9_-]*/)*[a-z0-9][a-z0-9_-]*\.md",
+    re.IGNORECASE,
+)
+
+# Files that may legitimately quote forbidden patterns inside backticks for
+# documentation purposes — the rule itself, the companion CI script docs,
+# and the contract doc that names the rule.
+SELF_DOCUMENTING_ALLOWLIST = frozenset({
+    ".agent-src.uncompressed/rules/no-roadmap-references.md",
+    "docs/guidelines/agent-infra/no-roadmap-references.md",
+})
+
+
+@dataclass
+class Violation:
+    file: str
+    line: int
+    match: str
+
+
+def _scan_file(path: Path, root: Path) -> list[Violation]:
+    rel = str(path.relative_to(root))
+    if rel in SELF_DOCUMENTING_ALLOWLIST:
+        return []
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return []
+    out: list[Violation] = []
+    in_fence = False
+    for n, line in enumerate(text.splitlines(), start=1):
+        # Skip fenced code blocks — path listings inside ``` are functional
+        # constants (command contracts, runtime checks), not link rot.
+        stripped = line.lstrip()
+        if stripped.startswith("```"):
+            in_fence = not in_fence
+            continue
+        if in_fence:
+            continue
+        for m in ROADMAP_FILE_RE.finditer(line):
+            out.append(Violation(file=rel, line=n, match=m.group(0)))
+    return out
+
+
+def _collect_targets(root: Path) -> list[Path]:
+    targets: list[Path] = []
+    for d in STABLE_TREES:
+        base = root / d
+        if not base.exists():
+            continue
+        targets.extend(sorted(base.rglob("*.md")))
+    for f in STABLE_FILES:
+        p = root / f
+        if p.exists():
+            targets.append(p)
+    return targets
+
+
+def scan(root: Path) -> list[Violation]:
+    out: list[Violation] = []
+    for path in _collect_targets(root):
+        out.extend(_scan_file(path, root))
+    return out
+
+
+def format_text(violations: list[Violation]) -> str:
+    if not violations:
+        return "✅  No roadmap-file references in stable artifacts."
+    lines = [f"❌  Found {len(violations)} roadmap reference(s) in stable artifacts:\n"]
+    for v in violations:
+        lines.append(f"  🔴 {v.file}:{v.line}  →  {v.match}")
+    lines.append(
+        "\nPromote the durable conclusion to agents/contexts/ and cite that "
+        "instead. See .agent-src.uncompressed/rules/no-roadmap-references.md."
+    )
+    return "\n".join(lines)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--format", choices=["text", "json"], default="text")
+    parser.add_argument("--root", type=Path, default=ROOT)
+    args = parser.parse_args()
+    try:
+        violations = scan(args.root)
+    except Exception as e:    # pragma: no cover
+        print(f"Internal error: {e}", file=sys.stderr)
+        return 3
+    if args.format == "json":
+        print(json.dumps([asdict(v) for v in violations], indent=2))
+    else:
+        print(format_text(violations))
+    return 1 if violations else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/check_phase_coupling.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""Phase 6 → Phase 2B coupling guard (Phase 0.3.3).
+
+Re-runs the audit recorded in `agents/roadmaps/phase6-2b-coupling.md`
+on every CI run. Fails the build if any of the 13 Phase-2B target
+rules introduces a reference to one of the three Phase-6-owned rules
+(`chat-history-cadence`, `chat-history-ownership`,
+`chat-history-visibility`) — by rule name, `load_context:` entry, or
+body link / cite.
+
+Excluded from the coupling probe (separate infrastructure, not
+reshaped by Phase 6):
+
+- The CLI dispatcher subcommand `./agent-config chat-history:hook`
+  and any other `chat-history:*` colon-suffix command surface.
+
+Exit codes: 0 = decoupling intact, 1 = coupling detected,
+3 = internal error (target rule missing, unreadable file).
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+SRC_RULES = REPO_ROOT / ".agent-src.uncompressed" / "rules"
+COMP_RULES = REPO_ROOT / ".agent-src" / "rules"
+
+# Phase 2B priority list — see road-to-structural-optimization.md § Phase 2 → 2B.
+TARGET_RULES: tuple[str, ...] = (
+    "roadmap-progress-sync",
+    "user-interaction",
+    "augment-source-of-truth",
+    "command-suggestion-policy",
+    "artifact-engagement-recording",
+    "review-routing-awareness",
+    "autonomous-execution",
+    "docs-sync",
+    "cli-output-handling",
+    "augment-portability",
+    "ui-audit-gate",
+    "skill-quality",
+    "package-ci-checks",
+)
+
+# Phase 6 owns these three rule names. Match must be a *rule reference*,
+# not a *dispatcher reference* (chat-history:hook etc).
+PHASE6_RULES: tuple[str, ...] = (
+    "chat-history-cadence",
+    "chat-history-ownership",
+    "chat-history-visibility",
+)
+
+# Rule-reference pattern: rule name not immediately followed by `:` (which
+# would mark it as a CLI subcommand like `chat-history:hook`). Allows
+# trailing word-boundary characters typical of Markdown / YAML contexts.
+_RULE_REF_RE = re.compile(
+    r"\bchat-history-(?:cadence|ownership|visibility)\b(?!:)"
+)
+
+
+def _scan(file: Path) -> list[tuple[int, str]]:
+    """Return [(line_no, line)] of rule-reference matches in `file`."""
+    if not file.is_file():
+        return []
+    hits: list[tuple[int, str]] = []
+    for i, line in enumerate(file.read_text(encoding="utf-8").splitlines(), 1):
+        if _RULE_REF_RE.search(line):
+            hits.append((i, line.strip()))
+    return hits
+
+
+def _check_surface(label: str, base: Path) -> tuple[int, list[str]]:
+    """Scan `base` for all 13 Phase-2B targets; return (#hits, formatted lines)."""
+    if not base.is_dir():
+        return 0, [f"❌  {label} dir missing: {base}"]
+    out: list[str] = []
+    total = 0
+    for rule in TARGET_RULES:
+        path = base / f"{rule}.md"
+        if not path.is_file():
+            return 0, [f"❌  target rule missing: {path}"]
+        hits = _scan(path)
+        if not hits:
+            continue
+        total += len(hits)
+        for line_no, line in hits:
+            out.append(f"  {label}/{rule}.md:{line_no}  {line}")
+    return total, out
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--quiet",
+        action="store_true",
+        help="suppress the per-rule breakdown when no coupling found",
+    )
+    args = parser.parse_args()
+
+    hits_src, lines_src = _check_surface("uncompressed", SRC_RULES)
+    if any(line.startswith("❌") for line in lines_src):
+        for line in lines_src:
+            print(line, file=sys.stderr)
+        return 3
+    hits_comp, lines_comp = _check_surface("compressed", COMP_RULES)
+    if any(line.startswith("❌") for line in lines_comp):
+        for line in lines_comp:
+            print(line, file=sys.stderr)
+        return 3
+
+    total = hits_src + hits_comp
+
+    if total == 0:
+        if not args.quiet:
+            print(
+                f"✅  Phase 6 → 2B decoupling intact: 0 rule-references "
+                f"across {len(TARGET_RULES)} Phase-2B targets "
+                f"(uncompressed + compressed surfaces)."
+            )
+            print(
+                "      probe: rule names, load_context: entries, body "
+                "link/cite — dispatcher subcommand chat-history:hook "
+                "excluded by design."
+            )
+        return 0
+
+    print(
+        f"❌  Phase 6 → 2B coupling detected: {total} rule-reference(s) "
+        f"across Phase-2B targets:"
+    )
+    for line in lines_src + lines_comp:
+        print(line)
+    print(
+        "\n      Action: see agents/roadmaps/phase6-2b-coupling.md. "
+        "Either drop the new reference, migrate it to the dispatcher "
+        "(chat-history:hook), or trigger the >0-hits branch in 0.3.2 "
+        "(Phase 6 ships call-signature contract before Phase 2B "
+        "touches the coupled rule)."
+    )
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/check_portability.py

@@ -315,6 +315,7 @@ _TASK_FENCE_RE = re.compile(r"^\s*task\s+([a-z][a-z0-9:_-]*)\b")
 # by the task-invocation detector (but still scanned for layer 1 + 2).
 _TASK_DETECTOR_SKIP = (
     "rules/augment-portability.md",
+    "contexts/communication/rules-auto/augment-portability-mechanics.md",
 )
 
 
@@ -422,6 +423,7 @@ _CLI_INVOCATION_MAP: list[tuple[re.Pattern, str]] = [
 # own help, the portability rule that defines the mapping).
 _CLI_DETECTOR_SKIP = (
     "rules/augment-portability.md",
+    "contexts/communication/rules-auto/augment-portability-mechanics.md",
 )
 
 

package/scripts/check_references.py

@@ -101,6 +101,14 @@ EXAMPLE_PATH_PATTERNS = [
     re.compile(r"skills/[\w-]+/SKILL\.md"),    # example skill paths in commands
     re.compile(r"\{"),                         # template placeholders like {module}
     re.compile(r"\.compression-hashes\.json"), # JSON file, not .md
+    # Forward references inside in-flight planning docs (road-to-
+    # structural-optimization.md and its companion spike protocols).
+    # Each pattern below is removed once the matching phase lands.
+    re.compile(r"structural-optimization-3a-spike\.md"),       # 3a.0.2
+    re.compile(r"contexts/judges/no-consolidate-rationale"),   # 3a.0.2 abort
+    re.compile(r"contexts/judges/judge-shared-procedure"),     # 3a.1
+    re.compile(r"contexts/analysis/project-analysis-core-procedure"),  # 3b.1
+    re.compile(r"agents/roadmaps/phase6-non-overlap-evidence"),        # 6.1 conditional
 ]
 
 
@@ -118,8 +126,20 @@ def collect_artifacts(root: Path) -> dict[str, set[str]]:
             arts["skills"].add(d.name)
     for f in (augment / "rules").glob("*.md") if (augment / "rules").exists() else []:
         arts["rules"].add(f.stem)
-    for f in (augment / "commands").glob("*.md") if (augment / "commands").exists() else []:
-        arts["commands"].add(f.stem)
+    cmd_dir = augment / "commands"
+    if cmd_dir.exists():
+        for f in cmd_dir.rglob("*.md"):
+            if f.name == "AGENTS.md":
+                continue
+            # Top-level: bare stem ("commit"). Nested: cluster-sub ("council-default")
+            # AND the cluster:sub form, since references may use either.
+            rel = f.relative_to(cmd_dir).with_suffix("")
+            parts = rel.parts
+            if len(parts) == 1:
+                arts["commands"].add(parts[0])
+            else:
+                arts["commands"].add("-".join(parts))
+                arts["commands"].add(":".join(parts))
     gdir = augment / "guidelines"
     if gdir.exists():
         for f in gdir.rglob("*.md"):
@@ -225,6 +245,13 @@ def check_file(filepath: Path, artifacts: dict[str, set[str]], root: Path) -> Li
             if any(p.search(raw_ref) for p in EXAMPLE_PATH_PATTERNS):
                 continue
 
+            # Skip references into directories already excluded from scanning
+            # (gitignored audit trails, archived roadmaps). Files there are
+            # not committed, so existence checks would always fail in CI.
+            if any(raw_ref.startswith(skip + "/") or raw_ref == skip
+                   for skip in SKIP_DIRS):
+                continue
+
             resolved = False
             # Try raw ref as-is from root (covers .agent-src/..., agents/..., etc.)
             if (root / raw_ref).exists():

package/scripts/check_safety_floor_untouched.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python3
+"""Safety-floor exclusion linter (Phase 2A.0 of road-to-structural-optimization).
+
+Per Q3=A locked decision (council Round 3, 2026-05-03), the four
+safety-floor always-rules are out of scope for Phase 2A slimming:
+
+  - non-destructive-by-default
+  - commit-policy
+  - scope-control
+  - verify-before-complete
+
+This linter compares HEAD against a baseline ref (default: ``main``)
+and fails CI if any of those four rule files were modified by the
+working branch.
+
+Lift via the two-gate rollback documented in
+``agents/roadmaps/road-to-structural-optimization.md`` § Phase 2A
+Abort/rollback.
+
+Exit codes: 0 = clean (or skipped — see ``--skip-if-no-baseline``),
+1 = safety-floor file modified, 3 = internal error.
+"""
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+RULES_DIR_REL = ".agent-src.uncompressed/rules"
+SAFETY_FLOOR = (
+    "non-destructive-by-default.md",
+    "commit-policy.md",
+    "scope-control.md",
+    "verify-before-complete.md",
+)
+
+
+def _run_git(args: list[str]) -> tuple[int, str]:
+    proc = subprocess.run(
+        ["git", *args],
+        cwd=REPO_ROOT,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    return proc.returncode, (proc.stdout or "") + (proc.stderr or "")
+
+
+def _baseline_exists(ref: str) -> bool:
+    code, _ = _run_git(["rev-parse", "--verify", "--quiet", ref])
+    return code == 0
+
+
+def _changed_files(baseline: str) -> list[str]:
+    code, output = _run_git(["diff", "--name-only", f"{baseline}...HEAD"])
+    if code != 0:
+        raise RuntimeError(f"git diff failed: {output}")
+    return [line.strip() for line in output.splitlines() if line.strip()]
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--baseline",
+        default="origin/main",
+        help="Baseline ref (default: origin/main)",
+    )
+    parser.add_argument(
+        "--skip-if-no-baseline",
+        action="store_true",
+        help="Exit 0 silently if baseline ref does not exist (local dev)",
+    )
+    args = parser.parse_args()
+
+    if not _baseline_exists(args.baseline):
+        if args.skip_if_no_baseline:
+            print(f"ℹ️  baseline {args.baseline} not found — skipped")
+            return 0
+        # Fallback: try plain `main`
+        if _baseline_exists("main"):
+            args.baseline = "main"
+        else:
+            print(
+                f"❌  baseline {args.baseline} (and `main`) not found. "
+                "Pass --skip-if-no-baseline to silence in local dev.",
+                file=sys.stderr,
+            )
+            return 3
+
+    try:
+        changed = _changed_files(args.baseline)
+    except RuntimeError as exc:
+        print(f"❌  {exc}", file=sys.stderr)
+        return 3
+
+    floor_paths = {f"{RULES_DIR_REL}/{name}" for name in SAFETY_FLOOR}
+    breaches = sorted(p for p in changed if p in floor_paths)
+
+    if breaches:
+        print(
+            "❌  Safety-floor rule(s) modified — Phase 2A is not allowed to "
+            "touch these (Q3=A locked decision):",
+            file=sys.stderr,
+        )
+        for path in breaches:
+            print(f"    {path}", file=sys.stderr)
+        print(
+            "\n    Lift via the two-gate rollback documented in "
+            "agents/roadmaps/road-to-structural-optimization.md "
+            "§ Phase 2A Abort/rollback.",
+            file=sys.stderr,
+        )
+        return 1
+
+    print(
+        f"✅  Safety-floor untouched ({len(SAFETY_FLOOR)} rules guarded "
+        f"vs. {args.baseline})."
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())