@event4u/agent-config 1.13.0 → 1.15.0

package/scripts/command_suggester/types.py

@@ -0,0 +1,78 @@
+"""Type definitions for the command suggestion engine.
+
+Plain dataclasses — no third-party deps. Kept in a sibling module so
+match/rank/cooldown/render can import without cycles.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class CommandSpec:
+    """Loaded command metadata that drives matching.
+
+    Fields mirror the `suggestion:` frontmatter block plus the
+    command's `name` and `description`. Ineligible commands are
+    represented with `eligible=False` and are never returned by the
+    matcher; the loader keeps them so cross-referencing stays simple.
+    """
+
+    name: str
+    description: str
+    eligible: bool
+    trigger_description: str = ""
+    trigger_context: str = ""
+    rationale: str = ""
+    confidence_floor: Optional[float] = None
+    cooldown: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class Match:
+    """A scored candidate. `score` is 0.0–1.0 inclusive.
+
+    `matched_trigger` is "description" | "context" | "both" and lets
+    the renderer surface why a command surfaced. `evidence` is the
+    short substring that fired (debugging / golden tests / explain).
+    `has_structural_bonus` is True when a heavy-signal pattern (ticket
+    key, file path, glob) co-occurred in the message — the ranker
+    treats those as specific enough to bypass vague-input suppression.
+    """
+
+    command: str
+    score: float
+    matched_trigger: str
+    evidence: str
+    has_structural_bonus: bool = False
+
+
+@dataclass(frozen=True)
+class Settings:
+    """Runtime knobs read from `.agent-settings.yml`.
+
+    Defaults match the "open decisions" leans in the roadmap.
+    Per-command frontmatter values override the global floor /
+    cooldown.
+    """
+
+    enabled: bool = True
+    confidence_floor: float = 0.6
+    cooldown_seconds: int = 600  # 10m
+    max_options: int = 4
+    blocklist: tuple[str, ...] = ()
+
+
+@dataclass
+class CooldownState:
+    """Per-conversation cooldown tracker — mutable on purpose."""
+
+    last_shown: dict[tuple[str, str], float] = field(default_factory=dict)
+    """Key: (command_name, trigger_evidence). Value: unix timestamp."""
+
+    explicit_invocations: dict[str, float] = field(default_factory=dict)
+    """Commands the user explicitly typed; clears their cooldown."""
+
+    disabled_for_conversation: bool = False
+    """Set by the `/command-suggestion-off` directive (Phase 5)."""

package/scripts/hooks/augment-chat-history.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# Augment Code lifecycle-hook trampoline for chat-history.
+#
+# Augment requires hook scripts to use the .sh extension and live at
+# either a system path (/etc/augment/...) or user scope
+# (~/.augment/...). This trampoline lives at user scope and dispatches
+# every event to whichever workspace fired it, so a single install
+# covers every project that has ./agent-config available.
+#
+# Behaviour:
+#   - Read the JSON event from stdin into a buffer.
+#   - Extract workspace_roots[0]; bail silently when missing.
+#   - cd into that workspace; bail silently when it is not a directory
+#     or does not contain ./agent-config.
+#   - Re-pipe the original JSON into
+#       ./agent-config chat-history:hook --platform augment
+#     so chat_history.py can run the platform mapping.
+#   - Always exit 0 — chat-history must never block the agent loop.
+
+set -u
+
+EVENT_DATA="$(cat)"
+
+# Extract workspace_roots[0] using whichever JSON tool is available.
+WORKSPACE=""
+if command -v jq >/dev/null 2>&1; then
+    WORKSPACE="$(printf '%s' "$EVENT_DATA" \
+        | jq -r '.workspace_roots[0] // empty' 2>/dev/null)"
+elif command -v python3 >/dev/null 2>&1; then
+    WORKSPACE="$(printf '%s' "$EVENT_DATA" | python3 -c '
+import json, sys
+try:
+    data = json.load(sys.stdin)
+except Exception:
+    sys.exit(0)
+roots = data.get("workspace_roots") or []
+if roots:
+    print(roots[0])
+' 2>/dev/null)"
+fi
+
+if [ -z "$WORKSPACE" ] || [ ! -d "$WORKSPACE" ]; then
+    exit 0
+fi
+
+cd "$WORKSPACE" 2>/dev/null || exit 0
+
+if [ ! -x ./agent-config ]; then
+    exit 0
+fi
+
+printf '%s' "$EVENT_DATA" \
+    | ./agent-config chat-history:hook --platform augment \
+        >/dev/null 2>&1 || true
+
+exit 0

package/scripts/install-hooks.sh

@@ -27,3 +27,70 @@ EOF
 
 chmod +x "$HOOKS_DIR/pre-push"
 echo "✅  Pre-push hook installed."
+
+# Pre-commit: marketplace consistency -----------------------------------------
+#
+# Distribution manifests (.claude-plugin/marketplace.json) drift silently —
+# adding a skill on disk without updating the manifest renders it invisible to
+# Claude Code Plugin Marketplace consumers. CI catches it, but a structural
+# pre-commit gate stops the bad commit from landing in the first place.
+# Runtime is ~40 ms; always-on is cheaper than scoped detection.
+
+cat > "$HOOKS_DIR/pre-commit" << 'EOF'
+#!/usr/bin/env bash
+# Pre-commit hook: verify .claude-plugin/marketplace.json lists every skill
+# that exists on disk under .claude/skills/.
+
+python3 scripts/lint_marketplace.py
+status=$?
+
+if [ $status -ne 0 ]; then
+    echo ""
+    echo "❌  Commit blocked — .claude-plugin/marketplace.json is out of sync."
+    echo "   Add the missing skill to the manifest (or remove the stale entry),"
+    echo "   then re-stage and commit. To bypass for an unrelated WIP commit:"
+    echo "       git commit --no-verify"
+    exit 1
+fi
+EOF
+
+chmod +x "$HOOKS_DIR/pre-commit"
+echo "✅  Pre-commit hook installed."
+
+# Chat-history bridge hooks ----------------------------------------------------
+#
+# Augment IDE plugin (and any other agent surface without native chat
+# lifecycle hooks) cannot fire SessionStart/Stop/PostToolUse. Git hooks
+# are the platform-agnostic lifecycle surface that fires regardless of
+# IDE — every commit, merge, checkout, and rewrite turns into a phase
+# boundary in .agent-chat-history when an agent session is active.
+#
+# The hooks are silent no-ops when no agent session is active (the
+# chat_history.py hook-append script returns "skipped_no_sidecar" with
+# exit 0) and `|| true` belt-and-suspenders ensures git operations are
+# never blocked.
+
+write_chat_history_hook() {
+    local name="$1"
+    local phase_tag="$2"
+    cat > "$HOOKS_DIR/$name" << EOF
+#!/usr/bin/env bash
+# $name: append a phase boundary to .agent-chat-history when an agent
+# session is active. Silent no-op otherwise. Never blocks git.
+
+if [ -x ./agent-config ]; then
+    ref="\$(git rev-parse --short HEAD 2>/dev/null || echo unknown)"
+    payload="{\"phase\":\"$phase_tag\",\"source\":\"git-hook:\$ref\"}"
+    ./agent-config chat-history:checkpoint --payload "\$payload" \
+        >/dev/null 2>&1 || true
+fi
+exit 0
+EOF
+    chmod +x "$HOOKS_DIR/$name"
+    echo "✅  $name hook installed."
+}
+
+write_chat_history_hook "post-commit"   "git:post-commit"
+write_chat_history_hook "post-merge"    "git:post-merge"
+write_chat_history_hook "post-checkout" "git:post-checkout"
+write_chat_history_hook "post-rewrite"  "git:post-rewrite"

package/scripts/install.py

@@ -251,45 +251,67 @@ def _yaml_scalar(value: str) -> str:
 def _replace_template_value(template: str, dotted_path: str, value: str) -> str:
     """Replace the default value for a dotted-path key in the YAML template.
 
-    Strategy: walk the template lines, track the current top-level
-    section, and replace the first matching line. Comments and indentation
-    are preserved.
+    Convenience wrapper: formats *value* as a YAML scalar (via
+    :func:`_yaml_scalar`) and delegates to :func:`_replace_template_value_raw`.
+    """
+    return _replace_template_value_raw(template, dotted_path, _yaml_scalar(value))
+
+
+def _replace_template_value_raw(template: str, dotted_path: str, raw_yaml: str) -> str:
+    """Replace the value at *dotted_path* with the pre-formatted *raw_yaml*.
+
+    Handles arbitrary nesting depth. The template uses 2-space indents;
+    parent sections are tracked by indent level so the leaf scalar is
+    only replaced when every parent matches the dotted path.
+
+    Comments and indentation are preserved. Returns *template* unchanged
+    if the path cannot be located.
     """
     parts = dotted_path.split(".")
-    if len(parts) == 1:
-        section, key = None, parts[0]
-    elif len(parts) == 2:
-        section, key = parts[0], parts[1]
-    else:
-        return template  # deeper nesting not supported in current schema
+    if not parts:
+        return template
 
-    lines = template.splitlines()
-    current_section: "str | None" = None
-    section_re = re.compile(r"^([A-Za-z_][A-Za-z0-9_]*):\s*$")
-    scalar_top_re = re.compile(r"^([A-Za-z_][A-Za-z0-9_]*):\s*.*$")
-    scalar_sub_re = re.compile(r"^(\s+)([A-Za-z_][A-Za-z0-9_]*):\s*.*$")
+    sections = parts[:-1]
+    key = parts[-1]
+    target_indent = "  " * len(sections)
+
+    header_re = re.compile(r"^(\s*)([A-Za-z_][A-Za-z0-9_]*):\s*$")
+    scalar_re = re.compile(r"^(\s*)([A-Za-z_][A-Za-z0-9_]*):\s*\S.*$")
+
+    # Stack of section names by depth; None entries mean "not yet seen
+    # at this depth" or "left this section". For path a.b.c we need
+    # current_path == ['a', 'b'] when scanning for key 'c' at indent 4.
+    current_path: list[str | None] = [None] * len(sections)
 
-    replacement = _yaml_scalar(value)
+    lines = template.splitlines()
     for idx, line in enumerate(lines):
-        # Top-level section header
-        m_section = section_re.match(line)
-        if m_section:
-            current_section = m_section.group(1)
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
             continue
-        if section is None:
-            # Top-level scalar target
-            m_top = scalar_top_re.match(line)
-            if m_top and m_top.group(1) == key and not line.startswith((" ", "\t")):
-                lines[idx] = f"{key}: {replacement}"
-                return "\n".join(lines) + ("\n" if template.endswith("\n") else "")
-        else:
-            if current_section != section:
-                continue
-            m_sub = scalar_sub_re.match(line)
-            if m_sub and m_sub.group(2) == key:
-                indent = m_sub.group(1)
-                lines[idx] = f"{indent}{key}: {replacement}"
-                return "\n".join(lines) + ("\n" if template.endswith("\n") else "")
+
+        m_header = header_re.match(line)
+        if m_header:
+            indent = m_header.group(1)
+            name = m_header.group(2)
+            depth = len(indent) // 2
+            if depth < len(sections):
+                current_path[depth] = name
+                # Reset deeper levels — we just entered a new sub-tree.
+                for d in range(depth + 1, len(sections)):
+                    current_path[d] = None
+            continue
+
+        m_scalar = scalar_re.match(line)
+        if not m_scalar:
+            continue
+        indent = m_scalar.group(1)
+        name = m_scalar.group(2)
+        if name != key or indent != target_indent:
+            continue
+        if current_path != list(sections):
+            continue
+        lines[idx] = f"{indent}{key}: {raw_yaml}"
+        return "\n".join(lines) + ("\n" if template.endswith("\n") else "")
     return template
 
 
@@ -436,6 +458,92 @@ def ensure_augment_bridge(project_root: Path, force: bool) -> None:
     merge_json_file(project_root / ".augment" / "settings.json", bridge, force, ".augment/settings.json")
 
 
+# Augment lifecycle hooks live at user scope (~/.augment/settings.json) per
+# https://docs.augmentcode.com/cli/hooks — that is the only path read by both
+# the CLI and the IDE plugins (VSCode, IntelliJ). Project-local
+# .augment/settings.json is plugin enablement, not hooks.
+AUGMENT_USER_DIR = Path.home() / ".augment"
+AUGMENT_USER_HOOKS_DIR = AUGMENT_USER_DIR / "hooks"
+AUGMENT_TRAMPOLINE_NAME = "augment-chat-history.sh"
+AUGMENT_HOOK_EVENTS = ("SessionStart", "SessionEnd", "Stop", "PostToolUse")
+
+
+def ensure_augment_user_hooks(package_root: Path, force: bool) -> None:
+    """Deploy the Augment lifecycle-hook trampoline at user scope.
+
+    Augment hook scripts must use the .sh extension and be referenced by
+    absolute path; user scope is the only surface that fires for both the
+    CLI and the IDE plugins. This installs once per developer (not per
+    project) — the trampoline reads workspace_roots from the event payload
+    and dispatches into whichever project is active at hook-fire time.
+    """
+    src = package_root / "scripts" / "hooks" / AUGMENT_TRAMPOLINE_NAME
+    if not src.exists():
+        skip(f"augment trampoline missing in package: {src}")
+        return
+
+    AUGMENT_USER_HOOKS_DIR.mkdir(parents=True, exist_ok=True)
+    dst = AUGMENT_USER_HOOKS_DIR / AUGMENT_TRAMPOLINE_NAME
+
+    src_text = src.read_text(encoding="utf-8")
+    if dst.exists() and dst.read_text(encoding="utf-8") == src_text and not force:
+        skip(f"~/.augment/hooks/{AUGMENT_TRAMPOLINE_NAME} already up to date")
+    else:
+        dst.write_text(src_text, encoding="utf-8")
+        dst.chmod(0o755)
+        success(f"~/.augment/hooks/{AUGMENT_TRAMPOLINE_NAME} installed")
+
+    hook_entry = {
+        "hooks": [
+            {
+                "type": "command",
+                "command": str(dst),
+            },
+        ],
+    }
+    settings_patch: dict = {"hooks": {event: [hook_entry] for event in AUGMENT_HOOK_EVENTS}}
+    merge_json_file(
+        AUGMENT_USER_DIR / "settings.json",
+        settings_patch,
+        force,
+        "~/.augment/settings.json",
+    )
+
+
+def _chat_history_hook_block(platform: str) -> dict:
+    """Single hook entry that calls ./agent-config chat-history:hook --platform <name>."""
+    return {
+        "hooks": [
+            {
+                "type": "command",
+                "command": f"./agent-config chat-history:hook --platform {platform}",
+            },
+        ],
+    }
+
+
+def ensure_claude_bridge(project_root: Path, force: bool) -> None:
+    """Deploy .claude/settings.json with plugin enablement and chat-history hooks.
+
+    Hooks dispatch to scripts/chat_history.py via the project-root ./agent-config
+    wrapper. They are no-ops when chat_history.enabled is false in
+    .agent-settings.yml. Idempotent: reruns merge cleanly without duplicating
+    entries (deep_merge replaces hook arrays rather than appending).
+    """
+    claude_hook = _chat_history_hook_block("claude")
+    bridge = {
+        "enabledPlugins": {"agent-conf@event4u": True},
+        "hooks": {
+            "SessionStart":     [claude_hook],
+            "UserPromptSubmit": [claude_hook],
+            "PostToolUse":      [claude_hook],
+            "Stop":             [claude_hook],
+            "SessionEnd":       [claude_hook],
+        },
+    }
+    merge_json_file(project_root / ".claude" / "settings.json", bridge, force, ".claude/settings.json")
+
+
 def ensure_copilot_bridge(project_root: Path, force: bool) -> None:
     target = project_root / ".github" / "plugin" / "marketplace.json"
 
@@ -474,6 +582,11 @@ def parse_options(argv: list[str]) -> argparse.Namespace:
     )
     parser.add_argument("--force", action="store_true", help="overwrite existing files")
     parser.add_argument("--skip-bridges", action="store_true", help="only create .agent-settings.yml")
+    parser.add_argument(
+        "--augment-user-hooks",
+        action="store_true",
+        help="also deploy ~/.augment/settings.json + ~/.augment/hooks/ (user-scope, all projects)",
+    )
     parser.add_argument("--project", default=None, help="project root (default: cwd or PROJECT_ROOT env)")
     parser.add_argument("--package", default=None, help="package root (default: auto-detect under project)")
     parser.add_argument("--quiet", action="store_true", help="suppress info/success output (warnings/errors still shown)")
@@ -516,8 +629,12 @@ def main(argv: list[str]) -> int:
     if not opts.skip_bridges:
         ensure_vscode_bridge(project_root, package_type, opts.force)
         ensure_augment_bridge(project_root, opts.force)
+        ensure_claude_bridge(project_root, opts.force)
         ensure_copilot_bridge(project_root, opts.force)
 
+    if opts.augment_user_hooks:
+        ensure_augment_user_hooks(package_root, opts.force)
+
     if not QUIET:
         print()
         success("Done.")

package/scripts/lint_marketplace.py

@@ -10,6 +10,8 @@ shape used by anthropics/skills:
   - metadata must have description + version
   - metadata.version must match package.json (single source of truth)
   - every plugins[].skills[] entry must exist on disk and carry a SKILL.md
+  - every SKILL.md on disk under .claude/skills/ must be listed in some
+    plugin's skills[] (drift detection)
 
 Exit codes: 0 = clean, 1 = problems found, 3 = internal error.
 """
@@ -23,6 +25,7 @@ from pathlib import Path
 ROOT = Path(".")
 MARKETPLACE = ROOT / ".claude-plugin" / "marketplace.json"
 PACKAGE_JSON = ROOT / "package.json"
+CLAUDE_SKILLS_DIR = ROOT / ".claude" / "skills"
 
 
 def fail(errors: list[str]) -> int:
@@ -121,6 +124,30 @@ def main() -> int:
             if not skill_md.exists():
                 errors.append(f"{entry} has no SKILL.md: `{path}`")
 
+    # Reverse-completeness: every SKILL.md on disk under .claude/skills/
+    # must appear in some plugin's skills[]. Catches the drift where new
+    # skills are generated but never added to the marketplace manifest.
+    listed: set[str] = set()
+    for plugin in plugins:
+        if not isinstance(plugin, dict):
+            continue
+        for path in plugin.get("skills", []):
+            if isinstance(path, str):
+                listed.add(path.removeprefix("./"))
+
+    if CLAUDE_SKILLS_DIR.exists():
+        for skill_dir in sorted(CLAUDE_SKILLS_DIR.iterdir()):
+            if not skill_dir.is_dir():
+                continue
+            if not (skill_dir / "SKILL.md").exists():
+                continue
+            rel = f".claude/skills/{skill_dir.name}"
+            if rel not in listed:
+                errors.append(
+                    f"skill exists on disk but is not listed in marketplace.json: "
+                    f"`./{rel}`"
+                )
+
     if errors:
         return fail(errors)
 

package/scripts/lint_no_new_atomic_commands.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+"""
+Atomic-command linter for the command-collapse policy.
+
+Reads the locked verb clusters from `docs/contracts/command-clusters.md`,
+finds every command file under `.agent-src.uncompressed/commands/` that
+was **added** since `--baseline` (default: `main`), and requires each
+new file to declare either:
+
+  - `cluster: <locked-name>`   (file is a cluster entry or sub-command), or
+  - `superseded_by: <slug>`    (file is a deprecation shim).
+
+Modifications to pre-existing files are NOT flagged — only additions.
+This stops the atomic surface from growing without forcing every existing
+command into a Phase 1 cluster (most aren't in Phase 1).
+
+Exit codes: 0 = clean, 1 = violations found, 3 = internal error.
+
+Usage:
+    python3 scripts/lint_no_new_atomic_commands.py
+    python3 scripts/lint_no_new_atomic_commands.py --baseline origin/main
+    python3 scripts/lint_no_new_atomic_commands.py --all       # ignore baseline
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+COMMANDS_DIR = Path(".agent-src.uncompressed/commands")
+CLUSTER_CONTRACT = Path("docs/contracts/command-clusters.md")
+
+
+@dataclass
+class Violation:
+    file: str
+    reason: str
+
+
+def load_locked_clusters() -> set[str]:
+    """Parse the Phase 1 cluster table from the locked contract."""
+    text = (ROOT / CLUSTER_CONTRACT).read_text(encoding="utf-8")
+    # Locate the Phase 1 table; cluster names sit in backticks in column 1.
+    in_phase_1 = False
+    clusters: set[str] = set()
+    for line in text.splitlines():
+        if line.startswith("## Phase 1 clusters"):
+            in_phase_1 = True
+            continue
+        if in_phase_1 and line.startswith("## "):
+            break
+        if in_phase_1:
+            m = re.match(r"\|\s*`([a-z][a-z0-9-]*)`\s*\|", line)
+            if m:
+                clusters.add(m.group(1))
+    if not clusters:
+        print(
+            f"❌  Could not parse Phase 1 cluster table from {CLUSTER_CONTRACT}",
+            file=sys.stderr,
+        )
+        sys.exit(3)
+    return clusters
+
+
+def added_command_files(baseline: str) -> list[Path]:
+    """Files under commands/ added (status A) since baseline."""
+    try:
+        result = subprocess.run(
+            ["git", "diff", "--name-only", "--diff-filter=A",
+             f"{baseline}...HEAD", "--", str(COMMANDS_DIR)],
+            capture_output=True, text=True, cwd=ROOT, timeout=15,
+        )
+    except (FileNotFoundError, subprocess.TimeoutExpired) as exc:
+        print(f"❌  git diff failed: {exc}", file=sys.stderr)
+        sys.exit(3)
+    if result.returncode != 0:
+        print(f"❌  git diff exit {result.returncode}: {result.stderr}",
+              file=sys.stderr)
+        sys.exit(3)
+    files = [Path(p) for p in result.stdout.splitlines()
+             if p.endswith(".md") and p != ""]
+    # Also include untracked (newly added, uncommitted) files.
+    try:
+        wt = subprocess.run(
+            ["git", "status", "--porcelain", "--", str(COMMANDS_DIR)],
+            capture_output=True, text=True, cwd=ROOT, timeout=10,
+        )
+        for line in wt.stdout.splitlines():
+            if len(line) < 4:
+                continue
+            status = line[:2]
+            if status.strip() not in ("A", "??", "AM"):
+                continue
+            path = line[3:].strip().split(" -> ")[-1]
+            if path.endswith(".md"):
+                p = Path(path)
+                if p not in files:
+                    files.append(p)
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        pass
+    return files
+
+
+def all_command_files() -> list[Path]:
+    return sorted((ROOT / COMMANDS_DIR).glob("*.md"))
+
+
+def parse_frontmatter(path: Path) -> dict[str, str]:
+    text = path.read_text(encoding="utf-8")
+    if not text.startswith("---"):
+        return {}
+    end = text.find("\n---", 3)
+    if end == -1:
+        return {}
+    fm: dict[str, str] = {}
+    for line in text[3:end].splitlines():
+        if ":" in line:
+            k, _, v = line.partition(":")
+            fm[k.strip()] = v.strip()
+    return fm
+
+
+def check_file(path: Path, clusters: set[str]) -> Violation | None:
+    abs_path = path if path.is_absolute() else ROOT / path
+    if not abs_path.exists():
+        return None  # deleted file, nothing to check
+    fm = parse_frontmatter(abs_path)
+    if "superseded_by" in fm:
+        return None  # shim — exempt
+    cluster = fm.get("cluster")
+    if not cluster:
+        return Violation(str(path),
+                         "missing `cluster:` frontmatter "
+                         f"(allowed: {sorted(clusters)})")
+    if cluster not in clusters:
+        return Violation(str(path),
+                         f"`cluster: {cluster}` is not a locked cluster "
+                         f"(allowed: {sorted(clusters)})")
+    return None
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--baseline", default="main",
+                    help="git ref to diff against (default: main)")
+    ap.add_argument("--all", action="store_true",
+                    help="check every command file, not just changed ones")
+    args = ap.parse_args()
+
+    clusters = load_locked_clusters()
+    targets = (all_command_files() if args.all
+               else added_command_files(args.baseline))
+    if not targets:
+        print(f"✅  No new commands added under {COMMANDS_DIR} "
+              f"(baseline: {args.baseline}).")
+        return 0
+
+    violations = [v for v in (check_file(p, clusters) for p in targets)
+                  if v is not None]
+    if violations:
+        print(f"❌  {len(violations)} newly-added atomic command(s) violate "
+              f"the command-cluster policy:")
+        for v in violations:
+            print(f"  • {v.file} — {v.reason}")
+        print(f"\nSee docs/contracts/command-clusters.md for the locked "
+              f"cluster names and frontmatter contract.")
+        return 1
+    print(f"✅  {len(targets)} newly-added command(s) all declare a valid "
+          f"`cluster:` (or `superseded_by:`).")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())