@event4u/agent-config 1.14.0 → 1.15.0

package/docs/migrations/commands-1.15.0.md

@@ -0,0 +1,112 @@
+# Command migration — 1.15.0
+
+> **Audience:** consumers of `event4u/agent-config` upgrading from
+> `1.14.x` to `1.15.0`.
+> **Authoritative spec:** [`docs/contracts/command-clusters.md`](../contracts/command-clusters.md).
+
+`1.15.0` collapses 15 atomic commands into 3 verb clusters
+(`fix`, `optimize`, `feature`) to reduce command-palette
+fragmentation. **Old commands keep working through the entire
+1.15.x cycle**; they emit a one-line deprecation warning on
+invocation and are removed in `1.16.0`.
+
+## Summary table
+
+| Old command | New invocation | Removed in |
+|---|---|---|
+| `/fix-ci` | `/fix ci` | 1.16.0 |
+| `/fix-pr-comments` | `/fix pr` | 1.16.0 |
+| `/fix-pr-bot-comments` | `/fix pr-bots` | 1.16.0 |
+| `/fix-pr-developer-comments` | `/fix pr-developers` | 1.16.0 |
+| `/fix-portability` | `/fix portability` | 1.16.0 |
+| `/fix-references` | `/fix refs` | 1.16.0 |
+| `/fix-seeder` | `/fix seeder` | 1.16.0 |
+| `/optimize-agents` | `/optimize agents` | 1.16.0 |
+| `/optimize-augmentignore` | `/optimize augmentignore` | 1.16.0 |
+| `/optimize-rtk-filters` | `/optimize rtk` | 1.16.0 |
+| `/optimize-skills` | `/optimize skills` | 1.16.0 |
+| `/feature-explore` | `/feature explore` | 1.16.0 |
+| `/feature-plan` | `/feature plan` | 1.16.0 |
+| `/feature-refactor` | `/feature refactor` | 1.16.0 |
+| `/feature-roadmap` | `/feature roadmap` | 1.16.0 |
+
+## What changes for you
+
+**Nothing breaks in 1.15.x.** Old slugs continue to work — the agent
+recognises them, dispatches to the new cluster command, and prints
+one warning line at the top of the reply:
+
+```
+⚠️  /fix-ci is deprecated; use /fix ci instead.
+```
+
+**Your existing custom skills, rules, or agents/roadmaps that
+reference old slugs do not need to change in 1.15.x.** Update at
+your own pace.
+
+## What to update before 1.16.0
+
+Search your project for any direct references to the old slugs and
+swap them for the new invocation:
+
+```bash
+# Find references in agents/, docs/, README, custom rules
+rg -n '/(fix|optimize|feature)-[a-z-]+' \
+   agents/ docs/ README.md AGENTS.md .github/ 2>/dev/null
+```
+
+Common spots:
+
+- `agents/roadmaps/*.md` — roadmap steps that name commands
+- `agents/contexts/*.md` — context docs cross-linking commands
+- Custom skills/rules under `.augment/` overrides
+- Internal team docs / runbooks / onboarding pages
+
+## Why this changed
+
+The atomic-command surface had grown to 77 commands by 1.14.0. Three
+prefix families (`fix-*`, `optimize-*`, `feature-*`) accounted for 15
+of those — same verb, same invocation pattern, only the noun
+differed. Collapsing the families into clusters:
+
+- Reduces palette noise (15 → 3 top-level entries).
+- Makes new sub-commands additive (`/fix tests` ships without a new
+  top-level slug).
+- Holds the line: `scripts/lint_no_new_atomic_commands.py` fails CI
+  if a new atomic command lands without a `cluster:` field declared
+  in [`docs/contracts/command-clusters.md`](../contracts/command-clusters.md).
+
+## Phase 2 (deferred)
+
+A second wave of collapses (`chat-history`, `agents`, `memory`,
+`roadmap`, `module`, `tests`, `context`, `override`, `copilot-agents`,
+`commit`, `judge`, `create-pr`) is scheduled after 1.15.0 ships and
+the deprecation cycle for Phase 1 closes. Tracked in
+[`agents/roadmaps/road-to-governance-cleanup.md`](../../agents/roadmaps/road-to-governance-cleanup.md)
+§ F2.
+
+## Related rule split — `chat-history` (post-1.15.0)
+
+The monolithic `rules/chat-history.md` was split into three sibling
+`always` rules in the post-1.15.0 optimization phase:
+
+- [`chat-history-ownership`](../../.agent-src/rules/chat-history-ownership.md) — sole owner of file I/O + first-turn handshake.
+- [`chat-history-cadence`](../../.agent-src/rules/chat-history-cadence.md) — when to persist (SessionStart / StepEnd / append boundaries).
+- [`chat-history-visibility`](../../.agent-src/rules/chat-history-visibility.md) — heartbeat marker contract for user-facing reporting.
+
+Decision record: [`docs/contracts/adr-chat-history-split.md`](../contracts/adr-chat-history-split.md).
+Cross-references in commands and contexts now point to
+`chat-history-ownership` as the entry point.
+
+## Rollback
+
+If a deprecation warning blocks tooling that screen-scrapes agent
+output, suppress it for the 1.15.x cycle by setting
+`commands.deprecation_warnings: false` in `.agent-settings.yml`.
+The setting disappears in 1.16.0 along with the shims.
+
+## See also
+
+- [`docs/contracts/command-clusters.md`](../contracts/command-clusters.md) — locked cluster spec.
+- [`docs/contracts/STABILITY.md`](../contracts/STABILITY.md) — public-surface stability tiers.
+- [`agents/roadmaps/archive/road-to-post-pr29-optimize.md`](../../agents/roadmaps/archive/road-to-post-pr29-optimize.md) — P0.8 anchor for this migration.

package/docs/ui-track-mental-model.md

@@ -0,0 +1,121 @@
+---
+stability: stable
+---
+
+# UI Track — Mental Model (1 page)
+
+> **Audience:** anyone driving `/work` or `/implement-ticket` on a UI-shaped
+> prompt, or reading code that touches `state.directive_set`.
+> **Not a contract.** For shapes, schemas, and slot wiring see
+> [`ui-track-flow.md`](contracts/ui-track-flow.md) and
+> [`adr-product-ui-track.md`](contracts/adr-product-ui-track.md).
+> **Not a roadmap.** Phased delivery lives in
+> [`road-to-product-ui-track.md`](../agents/roadmaps/archive/road-to-product-ui-track.md)
+> and [`road-to-visual-review-loop.md`](../agents/roadmaps/archive/road-to-visual-review-loop.md).
+> This page is the picture you keep in your head while the engine runs.
+
+## The three (+1) directive sets
+
+| Set | Shape | Halt budget |
+|---|---|---:|
+| `backend` | `refine → memory → analyze → plan → implement → test → verify → report` | depends on confidence band |
+| `ui` | `audit → design → apply → review → polish → report` | **2** (audit pick + design sign-off) |
+| `ui-trivial` | `refine → apply → test → report` | **0** on the happy path |
+| `mixed` | `refine → memory → analyze → contract → ui → stitch → verify → report` | inherits both |
+
+The first three are sibling routes; `mixed` stitches `backend` and `ui`
+in one envelope. The dispatcher picks one and refuses to switch
+mid-flight.
+
+## When to pick which
+
+| Signal | Set |
+|---|---|
+| No UI keywords, no UI envelope, prompt edits services / migrations / tests / config | `backend` |
+| New component / screen / partial; "improve this dashboard"; "build a settings panel"; major edit to a screen | `ui` |
+| Bounded edit, **provably** ≤ 1 file, ≤ 5 changed lines, no new component, no new state, no new dependency | `ui-trivial` |
+| One prompt that adds a backend endpoint **and** the screen that consumes it | `mixed` |
+
+The classifier picks; the agent does not override the pick silently.
+A misclassified `ui-trivial` that grows during edit must reclassify
+**loudly** (stop, restart at `audit`) — never quietly upgrade in place.
+
+## What the agent must never do
+
+1. **Skip the audit.** No new component, screen, or partial without
+   `state.ui_audit` populated (or `greenfield_decision` recorded).
+   Defense-in-depth: dispatcher refuses *and* `ui-audit-before-build`
+   refuses, even when the engine is not in the loop.
+2. **Render the UI.** The engine never opens a browser, never takes a
+   screenshot, never runs axe. Rendering and a11y scanning happen
+   out-of-process; the engine consumes the `preview_envelope` /
+   `a11y` envelope written by the skill.
+3. **Edit microcopy.** The design brief is **locked**. `apply` reads
+   strings verbatim. `<placeholder>`, `lorem`, `todo:`, `tbd`, `xxx`
+   are rejected at the producer (design) **and** the consumer (apply).
+4. **Loop polish indefinitely.** Hard ceiling is 2 rounds, +1 with
+   the explicit Extend pick (one-shot, never returns). Round 4 is
+   rejected on disk regardless of flags.
+5. **Confuse "ship as-is" with "review clean".** `review_clean=False`
+   plus `findings=[]` is a malformed envelope, not a green light.
+
+## Where each set stops
+
+| Set | Stops cleanly when … | Stops with a halt when … |
+|---|---|---|
+| `ui` | `report` written; design brief + audit + apply + review + polish all `SUCCESS` | audit ambiguous · greenfield decision missing · design unconfirmed · review dirty at ceiling · a11y violation un-accepted · preview render failed |
+| `ui-trivial` | `report` written; classifier preconditions held throughout | preconditions fail mid-flight → reclassify to `ui` (loud halt) |
+| `mixed` | `stitch` joins both subtrees; `verify` + `report` clean | either subtree halts → mixed waits, never auto-completes the other |
+
+## What "audit" actually means
+
+A non-empty `state.ui_audit` carrying **at least one of**:
+
+- `components_found` — `[{path, name, kind, similarity?}]` from
+  [`existing-ui-audit`](../.agent-src/skills/existing-ui-audit/SKILL.md).
+- `greenfield: true` plus `greenfield_decision ∈ {scaffold, bare, external_reference}`.
+- Legacy `components` alias — same shape.
+
+Empty dict, `null`, or a dict without those keys is **not** an audit.
+The gate fires; the dispatcher emits `@agent-directive: existing-ui-audit`
+instead of advancing.
+
+## What "design locked" actually means
+
+The brief carries `layout`, `components`, `states`, `microcopy`,
+`a11y`. State coverage requires `empty`, `loading`, `error`, `success`,
+`disabled`. `apply` does not re-decide microcopy — it copies strings.
+"The button label feels off" is a **new** design pass, not a polish
+fix.
+
+## Polish termination — subjective vs objective
+
+| Findings at ceiling | Halt branch | User options |
+|---|---|---|
+| Non-a11y only | `polish_ceiling_reached` | ship as-is · abort · hand off |
+| Includes a11y violation | `polish_a11y_blocking` | extend (one-shot, sets `extension_used=True`) · accept (rule ids land in `accepted_violations`) · abort |
+
+Pre-existing a11y violations recorded in `state.ui_audit.a11y_baseline`
+stay informational and never block.
+
+## Stack dispatch (apply / review / polish)
+
+`state.stack.frontend` decides which skill bundle runs:
+
+| Stack | Skill bundle |
+|---|---|
+| `blade-livewire-flux` | `flux` + `livewire` + `blade-ui` |
+| `react-shadcn` | `react-shadcn-ui` |
+| `vue` | `ui-apply-vue` |
+| `plain` (or unknown) | `blade-ui` + Tailwind base |
+
+The directive set stays `ui`; only the skill changes. Adding a new
+stack ships as a new skill bundle and a recipe — see
+[`ui-stack-extension.md`](contracts/ui-stack-extension.md).
+
+## See also
+
+- [`adr-product-ui-track.md`](contracts/adr-product-ui-track.md) — *why* this shape.
+- [`ui-track-flow.md`](contracts/ui-track-flow.md) — slot-by-slot contract.
+- [`ui-stack-extension.md`](contracts/ui-stack-extension.md) — adding a stack.
+- [`ui-audit-before-build`](../.agent-src/rules/ui-audit-before-build.md) — the always-on rule that mirrors the dispatcher gate.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "1.14.0",
+    "version": "1.15.0",
     "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,

package/scripts/build_linear_digest.py

@@ -10,7 +10,7 @@ Concatenates a curated set of cloud-safe rules from
   personal.md   — empty stub for individual preferences
 
 Per-rule inclusion + mode is the source of truth in
-`agents/contexts/linear-ai-rules-inclusion.md`. This script encodes the
+`docs/contracts/linear-ai-rules-inclusion.md`. This script encodes the
 same lists so a drift between the two surfaces is caught by the digest
 audit (Phase 3 Step 4) — the markdown doc is the human-readable spec,
 this script is the executable.
@@ -44,7 +44,7 @@ from pathlib import Path
 ROOT = Path(__file__).resolve().parent.parent
 # Compressed source is the shipped form — denser, sharper section
 # structure; better fit for a guidance field than the verbose authoring
-# layer. The inclusion list at agents/contexts/linear-ai-rules-inclusion.md
+# layer. The inclusion list at docs/contracts/linear-ai-rules-inclusion.md
 # remains the human-readable spec.
 SOURCE = ROOT / ".agent-src" / "rules"
 OUT_DIR = ROOT / "dist" / "linear"
@@ -64,7 +64,7 @@ class RuleEntry:
 
 
 # Workspace digest — universal coding posture. Maps 1:1 to the
-# "Workspace digest" table in agents/contexts/linear-ai-rules-inclusion.md.
+# "Workspace digest" table in docs/contracts/linear-ai-rules-inclusion.md.
 WORKSPACE: list[RuleEntry] = [
     RuleEntry("ask-when-uncertain"),
     RuleEntry("commit-conventions"),
@@ -169,7 +169,7 @@ def render_digest(layer: str, entries: list[RuleEntry]) -> tuple[str, dict]:
     parts.append(
         "> Auto-generated by `scripts/build_linear_digest.py` from "
         "`.agent-src/rules/` (compressed source) plus the inclusion list "
-        "at `agents/contexts/linear-ai-rules-inclusion.md`. Do not edit "
+        "at `docs/contracts/linear-ai-rules-inclusion.md`. Do not edit "
         "this file by hand — re-run `task build-linear-digest` to "
         "regenerate.\n"
     )

package/scripts/check_portability.py

@@ -157,6 +157,8 @@ ALLOWLIST = [
     r"agent-config",               # refers to the package concept, not a specific project
     r"shared.*package",            # "shared package" concept
     r"package repository",         # "package repository" concept
+    r"scripts/mcp_server/",        # MCP server module path (road-to-mcp-server.md Phase 1)
+    r"scripts\.mcp_server",        # MCP server Python module entrypoint
 ]
 
 # Directories to scan (only package files, not project-specific agents/)

package/scripts/check_public_links.py

@@ -0,0 +1,185 @@
+#!/usr/bin/env python3
+"""
+Public-link checker for the agent-config public surface.
+
+Scans the public-surface files (README.md, AGENTS.md, docs/architecture.md)
+for markdown links into `docs/contracts/`, then validates each link against
+the `stability:` frontmatter declared by the target file (per
+`docs/contracts/STABILITY.md`).
+
+Rules:
+  - target stability=stable        → OK (no marker required).
+  - target stability=beta          → OK; warns if surrounding text has no
+                                     visible "(beta)" marker.
+  - target stability=experimental  → ERROR. Public surface MUST NOT link
+                                     to experimental contracts.
+  - target outside docs/contracts/ but referenced for contract-shaped
+    intent (links into agents/contexts/*.md from public files) → ERROR.
+  - target file missing            → ERROR.
+  - target file under docs/contracts/ without `stability:` frontmatter
+    (except STABILITY.md itself) → ERROR.
+
+Exit codes: 0 = clean, 1 = violations found, 3 = internal error.
+
+Usage:
+    python3 scripts/check_public_links.py
+    python3 scripts/check_public_links.py --list      # list contracts + levels
+    python3 scripts/check_public_links.py --json      # machine-readable
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import dataclass, asdict
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+PUBLIC_FILES = [Path("README.md"), Path("AGENTS.md"), Path("docs/architecture.md")]
+CONTRACTS_DIR = Path("docs/contracts")
+STABILITY_FILE = CONTRACTS_DIR / "STABILITY.md"
+
+LINK_RE = re.compile(r"\[(?P<text>[^\]]+)\]\((?P<href>[^)\s]+)(?:\s+\"[^\"]*\")?\)")
+FRONTMATTER_RE = re.compile(r"^---\s*\n(.*?)\n---\s*\n", re.DOTALL)
+STABILITY_RE = re.compile(r"^stability:\s*(\w+)\s*$", re.MULTILINE)
+
+
+@dataclass
+class Violation:
+    file: str
+    line: int
+    href: str
+    reason: str
+    severity: str  # "error" | "warning"
+
+
+def read_stability(path: Path) -> str | None:
+    if not path.exists():
+        return None
+    txt = path.read_text(encoding="utf-8")
+    m = FRONTMATTER_RE.match(txt)
+    if not m:
+        return None
+    sm = STABILITY_RE.search(m.group(1))
+    return sm.group(1) if sm else None
+
+
+def collect_contracts() -> dict[Path, str | None]:
+    out: dict[Path, str | None] = {}
+    for p in sorted((ROOT / CONTRACTS_DIR).glob("*.md")):
+        rel = p.relative_to(ROOT)
+        out[rel] = read_stability(p)
+    return out
+
+
+def resolve(public_file: Path, href: str) -> Path | None:
+    href = href.split("#", 1)[0]
+    if not href or href.startswith(("http://", "https://", "mailto:", "tel:")):
+        return None
+    if href.startswith("/"):
+        return Path(href.lstrip("/"))
+    return (public_file.parent / href).resolve().relative_to(ROOT.resolve())
+
+
+def scan_file(public_file: Path, contracts: dict[Path, str | None]) -> list[Violation]:
+    abs_path = ROOT / public_file
+    if not abs_path.exists():
+        return []
+    violations: list[Violation] = []
+    for lineno, line in enumerate(abs_path.read_text(encoding="utf-8").splitlines(), 1):
+        for m in LINK_RE.finditer(line):
+            href = m.group("href")
+            text = m.group("text")
+            try:
+                target = resolve(public_file, href)
+            except ValueError:
+                continue
+            if target is None:
+                continue
+            if target.parts[:2] == ("agents", "contexts") and target.suffix == ".md":
+                violations.append(Violation(str(public_file), lineno, href,
+                    "public surface MUST NOT link into agents/contexts/ — move target to docs/contracts/",
+                    "error"))
+                continue
+            if target.parts[:2] != ("docs", "contracts") or target.suffix != ".md":
+                continue
+            if target == STABILITY_FILE:
+                continue
+            if target not in contracts:
+                violations.append(Violation(str(public_file), lineno, href,
+                    f"target not found: {target}", "error"))
+                continue
+            level = contracts[target]
+            if level is None:
+                violations.append(Violation(str(public_file), lineno, href,
+                    f"target missing 'stability:' frontmatter: {target}", "error"))
+                continue
+            if level == "experimental":
+                violations.append(Violation(str(public_file), lineno, href,
+                    f"public surface MUST NOT link to experimental contract: {target}",
+                    "error"))
+                continue
+            if level == "beta":
+                window = line.lower()
+                if "(beta)" not in window and "[beta]" not in window:
+                    violations.append(Violation(str(public_file), lineno, href,
+                        f"link to beta contract '{target}' lacks visible (beta) marker",
+                        "warning"))
+    return violations
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--list", action="store_true", help="list contracts + stability levels")
+    ap.add_argument("--json", action="store_true", help="machine-readable output")
+    ap.add_argument("--strict", action="store_true",
+                    help="fail on warnings as well as errors (default: errors only)")
+    args = ap.parse_args()
+
+    contracts = collect_contracts()
+    if args.list:
+        for p, lvl in contracts.items():
+            print(f"  {lvl or '(no frontmatter)':14}  {p}")
+        return 0
+
+    missing_fm = [p for p, lvl in contracts.items() if lvl is None and p != STABILITY_FILE]
+    violations: list[Violation] = []
+    for p in missing_fm:
+        violations.append(Violation(str(p), 0, "(self)",
+            "missing 'stability:' frontmatter required by docs/contracts/STABILITY.md",
+            "error"))
+    for f in PUBLIC_FILES:
+        violations.extend(scan_file(f, contracts))
+
+    if args.json:
+        print(json.dumps([asdict(v) for v in violations], indent=2))
+    else:
+        errors = [v for v in violations if v.severity == "error"]
+        warnings = [v for v in violations if v.severity == "warning"]
+        for v in violations:
+            icon = "❌" if v.severity == "error" else "⚠️ "
+            loc = f"{v.file}:{v.line}" if v.line else v.file
+            print(f"{icon}  {loc}  {v.href}\n     → {v.reason}")
+        if not violations:
+            print(f"✅  public-link check clean — {len(contracts)} contracts scanned, "
+                  f"{len(PUBLIC_FILES)} public files clean")
+        else:
+            print(f"\nsummary: {len(errors)} error(s), {len(warnings)} warning(s)")
+
+    has_errors = any(v.severity == "error" for v in violations)
+    has_warnings = any(v.severity == "warning" for v in violations)
+    if has_errors:
+        return 1
+    if has_warnings and args.strict:
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except Exception as e:
+        print(f"❌  internal error: {e}", file=sys.stderr)
+        sys.exit(3)

package/scripts/check_references.py

@@ -78,6 +78,7 @@ EXAMPLE_PATH_PATTERNS = [
     re.compile(r"agents/overrides/"),           # override examples
     re.compile(r"commands/old-cmd"),            # example placeholder
     re.compile(r"agents/README"),               # README reference (may not exist in package)
+    re.compile(r"agents/index[\w.-]*\.md"),     # planned auto-generated artefact index (F5)
     re.compile(r"agents/docs/"),               # project-specific docs (not in package)
     re.compile(r"agents/contexts/"),           # project-specific contexts (not in package)
     re.compile(r"agents/gates"),               # project-specific policy docs

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())