@event4u/agent-config 1.16.0 → 1.18.0

package/scripts/lint_examples.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""Phase 3.4 demo-shape linter — wrong / right / why per demo.
+
+Cap: ≤ 100 LOC, stdlib only. Hooked into `task ci` via
+`Taskfile.yml` ▸ `check-examples-shape`. Validates every
+`docs/guidelines/agent-infra/*-demos.md`: frontmatter keys
+(`demo_for:`, `layer: pattern-memory`, `prose_delta:` with before /
+after char counts), and each `## Demo N` section having Wrong /
+Right shape headings, a `**Failure mode:**` line, and a Why-it-works
+explanation (heading or inline).
+"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+DEMO_GLOB = "docs/guidelines/agent-infra/*-demos.md"
+REQUIRED_FM_KEYS = ("demo_for:", "layer: pattern-memory", "prose_delta:")
+REQUIRED_FM_DELTA = ("rule_chars_before:", "rule_chars_after:")
+
+
+def _frontmatter(text: str) -> str:
+    if not text.startswith("---\n"):
+        return ""
+    end = text.find("\n---\n", 4)
+    return text[4:end] if end != -1 else ""
+
+
+def _check_frontmatter(fm: str, problems: list[str]) -> None:
+    for key in (*REQUIRED_FM_KEYS, *REQUIRED_FM_DELTA):
+        if key not in fm:
+            problems.append(f"frontmatter missing: {key!r}")
+
+
+def _check_demo_sections(text: str, problems: list[str]) -> None:
+    demo_pat = re.compile(r"^## Demo \d+\b.*$", re.MULTILINE)
+    demo_starts = [m.start() for m in demo_pat.finditer(text)]
+    if not demo_starts:
+        problems.append("no '## Demo N — …' sections found")
+        return
+    bounds = demo_starts + [len(text)]
+    for i, start in enumerate(demo_starts):
+        section = text[start:bounds[i + 1]]
+        title = section.splitlines()[0]
+        if "### Wrong shape" not in section:
+            problems.append(f"{title!r}: missing '### Wrong shape'")
+        if "### Right shape" not in section:
+            problems.append(f"{title!r}: missing '### Right shape'")
+        if "**Failure mode:**" not in section:
+            problems.append(f"{title!r}: missing '**Failure mode:**' line")
+        has_why_section = "### Why it works" in section
+        has_why_inline = "**Why it works:**" in section
+        if not (has_why_section or has_why_inline):
+            problems.append(
+                f"{title!r}: missing 'Why it works' explanation "
+                "(### Why it works or **Why it works:** inline)"
+            )
+
+
+def lint_demo(path: Path) -> list[str]:
+    text = path.read_text(encoding="utf-8")
+    problems: list[str] = []
+    fm = _frontmatter(text)
+    if not fm:
+        problems.append("missing YAML frontmatter (--- block at top)")
+    else:
+        _check_frontmatter(fm, problems)
+    _check_demo_sections(text, problems)
+    return problems
+
+
+def main() -> int:
+    demos = sorted(REPO_ROOT.glob(DEMO_GLOB))
+    if not demos:
+        print(f"❌  no demo files matched {DEMO_GLOB}", file=sys.stderr)
+        return 1
+    failed = 0
+    for demo in demos:
+        rel = demo.relative_to(REPO_ROOT)
+        problems = lint_demo(demo)
+        if problems:
+            failed += 1
+            print(f"❌  {rel}", file=sys.stderr)
+            for p in problems:
+                print(f"    - {p}", file=sys.stderr)
+        else:
+            print(f"✅  {rel}")
+    if failed:
+        print(f"\n❌  {failed} demo file(s) failed shape lint", file=sys.stderr)
+        return 1
+    print(f"\n✅  {len(demos)} demo file(s) shape-clean")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/lint_no_new_atomic_commands.py

@@ -43,24 +43,24 @@ class Violation:
 
 
 def load_locked_clusters() -> set[str]:
-    """Parse the Phase 1 cluster table from the locked contract."""
+    """Parse the locked cluster table from the 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
+    # Locate the locked-clusters table; cluster names sit in backticks in column 1.
+    in_table = False
     clusters: set[str] = set()
     for line in text.splitlines():
-        if line.startswith("## Phase 1 clusters"):
-            in_phase_1 = True
+        if line.startswith("## Locked clusters"):
+            in_table = True
             continue
-        if in_phase_1 and line.startswith("## "):
+        if in_table and line.startswith("## "):
             break
-        if in_phase_1:
+        if in_table:
             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}",
+            f"❌  Could not parse locked-clusters table from {CLUSTER_CONTRACT}",
             file=sys.stderr,
         )
         sys.exit(3)
@@ -83,7 +83,7 @@ def added_command_files(baseline: str) -> list[Path]:
               file=sys.stderr)
         sys.exit(3)
     files = [Path(p) for p in result.stdout.splitlines()
-             if p.endswith(".md") and p != ""]
+             if p.endswith(".md") and p != "" and Path(p).name != "AGENTS.md"]
     # Also include untracked (newly added, uncommitted) files.
     try:
         wt = subprocess.run(
@@ -97,7 +97,7 @@ def added_command_files(baseline: str) -> list[Path]:
             if status.strip() not in ("A", "??", "AM"):
                 continue
             path = line[3:].strip().split(" -> ")[-1]
-            if path.endswith(".md"):
+            if path.endswith(".md") and Path(path).name != "AGENTS.md":
                 p = Path(path)
                 if p not in files:
                     files.append(p)
@@ -107,7 +107,8 @@ def added_command_files(baseline: str) -> list[Path]:
 
 
 def all_command_files() -> list[Path]:
-    return sorted((ROOT / COMMANDS_DIR).glob("*.md"))
+    return sorted(p for p in (ROOT / COMMANDS_DIR).rglob("*.md")
+                  if p.name != "AGENTS.md")
 
 
 def parse_frontmatter(path: Path) -> dict[str, str]:

package/scripts/lint_roadmap_complexity.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""Phase 5.2 roadmap-complexity linter.
+
+Enforces the measurable subset of
+`docs/contracts/roadmap-complexity-standard.md`:
+
+  - every `agents/roadmaps/*.md` declares `complexity: lightweight`
+    or `complexity: structural` in frontmatter;
+  - lightweight roadmaps have ≤ 600 total lines and ≤ 6 `## Phase N`
+    headings, and contain no `## Council Round N` / `### Verdict`
+    sections;
+  - structural roadmaps have no upper cap, but the tag must be
+    declared.
+
+Cap: ≤ 150 LOC, stdlib only. Hooked into `task ci` via
+`task lint-roadmap-complexity`.
+"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+ROADMAP_GLOB = "agents/roadmaps/*.md"
+LIGHTWEIGHT_LINE_CAP = 600
+LIGHTWEIGHT_PHASE_CAP = 6
+
+PHASE_PAT = re.compile(r"^## Phase \d+\b", re.MULTILINE)
+COUNCIL_PAT = re.compile(r"^## Council Round \d+\b", re.MULTILINE)
+VERDICT_PAT = re.compile(r"^### Verdict\b", re.MULTILINE)
+COMPLEXITY_PAT = re.compile(
+    r"^complexity:\s*(lightweight|structural)\s*$", re.MULTILINE
+)
+
+
+def _frontmatter(text: str) -> str:
+    if not text.startswith("---\n"):
+        return ""
+    end = text.find("\n---\n", 4)
+    return text[4:end] if end != -1 else ""
+
+
+def _read_complexity(fm: str) -> str | None:
+    m = COMPLEXITY_PAT.search(fm)
+    return m.group(1) if m else None
+
+
+def _check_lightweight(text: str, line_count: int, problems: list[str]) -> None:
+    if line_count > LIGHTWEIGHT_LINE_CAP:
+        problems.append(
+            f"lightweight cap exceeded: {line_count} lines "
+            f"(max {LIGHTWEIGHT_LINE_CAP}); consider tagging structural "
+            f"or trimming"
+        )
+    phases = len(PHASE_PAT.findall(text))
+    if phases > LIGHTWEIGHT_PHASE_CAP:
+        problems.append(
+            f"lightweight phase cap exceeded: {phases} phases "
+            f"(max {LIGHTWEIGHT_PHASE_CAP})"
+        )
+    if COUNCIL_PAT.search(text):
+        problems.append(
+            "lightweight roadmap contains '## Council Round N' "
+            "block — council debates belong in structural roadmaps"
+        )
+    if VERDICT_PAT.search(text):
+        problems.append(
+            "lightweight roadmap contains '### Verdict' block — "
+            "council verdicts belong in structural roadmaps"
+        )
+
+
+def lint_roadmap(path: Path) -> list[str]:
+    text = path.read_text(encoding="utf-8")
+    line_count = text.count("\n") + (1 if text and not text.endswith("\n") else 0)
+    problems: list[str] = []
+    fm = _frontmatter(text)
+    complexity = _read_complexity(fm) if fm else None
+    if complexity is None:
+        problems.append(
+            "missing 'complexity:' frontmatter "
+            "(must declare 'lightweight' or 'structural')"
+        )
+        return problems
+    if complexity == "lightweight":
+        _check_lightweight(text, line_count, problems)
+    return problems
+
+
+def main() -> int:
+    roadmaps = sorted(REPO_ROOT.glob(ROADMAP_GLOB))
+    if not roadmaps:
+        print(f"❌  no roadmaps matched {ROADMAP_GLOB}", file=sys.stderr)
+        return 1
+    failed = 0
+    summary: list[tuple[str, str]] = []
+    for roadmap in roadmaps:
+        rel = roadmap.relative_to(REPO_ROOT)
+        problems = lint_roadmap(roadmap)
+        text = roadmap.read_text(encoding="utf-8")
+        complexity = _read_complexity(_frontmatter(text)) or "untagged"
+        summary.append((str(rel), complexity))
+        if problems:
+            failed += 1
+            print(f"❌  {rel}  [{complexity}]", file=sys.stderr)
+            for p in problems:
+                print(f"    - {p}", file=sys.stderr)
+        else:
+            print(f"✅  {rel}  [{complexity}]")
+    print()
+    light = sum(1 for _, c in summary if c == "lightweight")
+    structural = sum(1 for _, c in summary if c == "structural")
+    untagged = sum(1 for _, c in summary if c == "untagged")
+    print(
+        f"summary: {light} lightweight · {structural} structural · "
+        f"{untagged} untagged · {len(summary)} total"
+    )
+    if failed:
+        print(f"\n❌  {failed} roadmap(s) failed complexity lint", file=sys.stderr)
+        return 1
+    print(f"\n✅  {len(roadmaps)} roadmap(s) complexity-clean")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/onboarding_gate_hook.py

@@ -0,0 +1,137 @@
+#!/usr/bin/env python3
+"""Platform-agnostic hook for the `onboarding-gate` rule.
+
+Reads `.agent-settings.yml` from the consumer repo and writes a
+deterministic state file the rule body can cite as the source of
+truth for "do I need to prompt the user about /onboard?".
+
+Output is written to `agents/state/onboarding-gate.json` with:
+  {
+    "required": <bool>,         // true → rule fires on first turn
+    "reason":   "<string>",     // why this state was set
+    "checked_at": "<iso8601>",  // last hook run
+    "settings_present": <bool>  // .agent-settings.yml exists
+  }
+
+Exit code is **always 0**. Hooks must never block the agent loop.
+
+Output discipline:
+  - stdout: nothing (Augment surfaces stdout to the user)
+  - stderr: one short line in --verbose mode, otherwise silent
+
+CLI:
+  python3 scripts/onboarding_gate_hook.py [--platform NAME] [--verbose]
+"""
+from __future__ import annotations
+
+import argparse
+import datetime as _dt
+import json
+import re
+import sys
+from pathlib import Path
+
+SETTINGS_FILE = ".agent-settings.yml"
+STATE_DIR = Path("agents") / "state"
+STATE_FILE = STATE_DIR / "onboarding-gate.json"
+
+
+def _read_onboarded(settings_path: Path) -> tuple[bool, str]:
+    """Return (required, reason) — minimal, dependency-free YAML parsing.
+
+    We only need a single key under the `onboarding:` block. Full YAML is
+    overkill (and would pull in a runtime dep). We scan line-by-line for
+    `onboarded: <bool>` inside the `onboarding:` section.
+    """
+    if not settings_path.is_file():
+        return (False, "settings_file_missing")  # legacy: do not block
+
+    try:
+        text = settings_path.read_text(encoding="utf-8")
+    except OSError:
+        return (False, "settings_file_unreadable")
+
+    in_onboarding = False
+    onboarded_value: str | None = None
+    for raw in text.splitlines():
+        line = raw.rstrip()
+        if not line or line.lstrip().startswith("#"):
+            continue
+        if re.match(r"^onboarding\s*:\s*$", line):
+            in_onboarding = True
+            continue
+        if in_onboarding:
+            # Section ends when a top-level (non-indented) key starts.
+            if line and not line.startswith((" ", "\t")):
+                break
+            m = re.match(r"^\s+onboarded\s*:\s*(\S+)\s*(?:#.*)?$", line)
+            if m:
+                onboarded_value = m.group(1).strip().lower()
+
+    if onboarded_value is None:
+        return (False, "key_missing")  # legacy / pre-rule project
+    if onboarded_value in ("true", "yes", "on"):
+        return (False, "already_onboarded")
+    if onboarded_value in ("false", "no", "off"):
+        return (True, "explicit_false")
+    return (False, f"unknown_value:{onboarded_value}")
+
+
+def _write_state(consumer_root: Path, required: bool, reason: str,
+                 settings_present: bool) -> None:
+    """Write `agents/state/onboarding-gate.json` atomically."""
+    state_dir = consumer_root / STATE_DIR
+    state_dir.mkdir(parents=True, exist_ok=True)
+    payload = {
+        "required": required,
+        "reason": reason,
+        "checked_at": _dt.datetime.now(_dt.timezone.utc).isoformat(
+            timespec="seconds"),
+        "settings_present": settings_present,
+    }
+    target = consumer_root / STATE_FILE
+    tmp = target.with_suffix(".json.tmp")
+    tmp.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+    tmp.replace(target)
+
+
+def run(*, consumer_root: Path, verbose: bool = False) -> int:
+    settings_path = consumer_root / SETTINGS_FILE
+    settings_present = settings_path.is_file()
+    try:
+        required, reason = _read_onboarded(settings_path)
+    except Exception:  # pragma: no cover — defensive
+        required, reason = (False, "hook_error")
+
+    try:
+        _write_state(consumer_root, required, reason, settings_present)
+    except OSError:
+        if verbose:
+            print("onboarding-gate-hook: state write failed",
+                  file=sys.stderr)
+        return 0  # never block
+
+    if verbose:
+        print(f"onboarding-gate-hook: required={required} reason={reason}",
+              file=sys.stderr)
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--platform", default="generic",
+                        help="informational platform tag")
+    parser.add_argument("--verbose", action="store_true",
+                        help="emit one stderr line per invocation")
+    args = parser.parse_args(argv)
+    # Drain stdin so callers piping JSON don't block on a SIGPIPE on
+    # platforms that strictly require stdin to be consumed.
+    try:
+        sys.stdin.read()
+    except Exception:
+        pass
+    return run(consumer_root=Path.cwd(), verbose=args.verbose)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

package/scripts/requirements-evals.txt

@@ -5,3 +5,4 @@
 # be upgraded, bump the version here and rerun the setup script.
 
 anthropic==0.96.0
+openai==1.109.1

package/scripts/roadmap_progress_hook.py

@@ -0,0 +1,159 @@
+#!/usr/bin/env python3
+"""Platform-agnostic PostToolUse hook for the `roadmap-progress-sync` rule.
+
+Reads a JSON event from stdin (Augment / Claude / Cursor / Cline /
+Windsurf / Gemini PostToolUse-shaped envelopes), decides whether the
+tool call wrote to a roadmap file under `agents/roadmaps/`, and — when
+it did — re-runs `update_roadmap_progress.py` so the dashboard stays
+in sync without depending on agent self-discipline.
+
+Exit code is **always 0**. Hooks must never block the agent loop; the
+worst-case is a no-op when stdin is malformed or the regenerator is
+missing.
+
+Output discipline:
+  - stdout: nothing (Augment would surface stdout to the user)
+  - stderr: one short line in --verbose mode, otherwise silent
+
+CLI:
+  python3 scripts/roadmap_progress_hook.py [--platform NAME] [--verbose]
+
+The `--platform` flag is informational only — the filter logic reads
+the same field names across platforms (tool_name, tool_input.path,
+file_changes[].path).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+# Tools whose successful execution can write to a roadmap file. We keep
+# the list explicit so an unknown tool name (e.g. a new MCP tool that
+# happens to mention a roadmap path in its input) does not trigger a
+# spurious regeneration.
+WRITE_TOOLS = frozenset({
+    "str-replace-editor",
+    "save-file",
+    "remove-files",
+    # Claude Code / Cursor naming variants — kept for cross-platform
+    # parity if this hook is ever wired beyond Augment.
+    "Edit",
+    "Write",
+    "MultiEdit",
+})
+
+ROADMAP_PREFIX = "agents/roadmaps/"
+# Paths under these subtrees are tracked but not part of the open list
+# the dashboard summarises — regenerating on every archived edit would
+# be wasteful. The check still fires on the parent dir itself.
+ROADMAP_EXCLUDED_PARTS = frozenset({"archive", "skipped"})
+DASHBOARD_PATH = "agents/roadmaps-progress.md"
+
+
+def _candidate_paths(payload: dict) -> list[str]:
+    """Pull every plausible file path out of a PostToolUse payload."""
+    out: list[str] = []
+    fc = payload.get("file_changes")
+    if isinstance(fc, list):
+        for entry in fc:
+            if isinstance(entry, dict):
+                p = entry.get("path")
+                if isinstance(p, str) and p:
+                    out.append(p)
+    ti = payload.get("tool_input")
+    if isinstance(ti, dict):
+        for key in ("path", "file_path", "target_file"):
+            v = ti.get(key)
+            if isinstance(v, str) and v:
+                out.append(v)
+    return out
+
+
+def _is_roadmap_touch(path: str) -> bool:
+    """Return True if `path` is a roadmap file we should react to."""
+    norm = path.lstrip("./").replace("\\", "/")
+    if not norm.startswith(ROADMAP_PREFIX):
+        return False
+    if norm == DASHBOARD_PATH:
+        # Defensive — the dashboard sits at agents/roadmaps-progress.md,
+        # NOT inside agents/roadmaps/. The prefix check above already
+        # excludes it, but keep this explicit so a future relocation
+        # cannot turn the hook into an infinite loop.
+        return False
+    rest = norm[len(ROADMAP_PREFIX):]
+    parts = rest.split("/")
+    if len(parts) >= 2 and parts[0] in ROADMAP_EXCLUDED_PARTS:
+        return False
+    if not norm.endswith(".md"):
+        return False
+    return True
+
+
+def _resolve_regenerator(consumer_root: Path) -> Path | None:
+    """Find the regenerator script — package-shipped or installed copy."""
+    for candidate in (
+        consumer_root / ".augment" / "scripts" / "update_roadmap_progress.py",
+        consumer_root / ".agent-src" / "scripts" / "update_roadmap_progress.py",
+        consumer_root / ".agent-src.uncompressed" / "scripts" / "update_roadmap_progress.py",
+    ):
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def run(stdin_text: str, *, consumer_root: Path, verbose: bool = False) -> int:
+    payload: dict = {}
+    if stdin_text.strip():
+        try:
+            decoded = json.loads(stdin_text)
+            if isinstance(decoded, dict):
+                payload = decoded
+        except json.JSONDecodeError:
+            return 0  # malformed stdin → silent no-op, never block
+
+    tool = payload.get("tool_name") or payload.get("toolName") or payload.get("tool")
+    if not isinstance(tool, str) or tool not in WRITE_TOOLS:
+        return 0
+
+    paths = _candidate_paths(payload)
+    if not any(_is_roadmap_touch(p) for p in paths):
+        return 0
+
+    script = _resolve_regenerator(consumer_root)
+    if script is None:
+        if verbose:
+            print("roadmap-progress-hook: regenerator not found, skipping",
+                  file=sys.stderr)
+        return 0
+
+    try:
+        subprocess.run(
+            [sys.executable, str(script)],
+            cwd=consumer_root, check=False,
+            stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+            timeout=30,
+        )
+    except (OSError, subprocess.SubprocessError):
+        pass  # never propagate regenerator failures into the agent loop
+
+    if verbose:
+        print(f"roadmap-progress-hook: regenerated for tool={tool}",
+              file=sys.stderr)
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--platform", default="generic",
+                        help="informational platform tag (augment/claude/...)")
+    parser.add_argument("--verbose", action="store_true",
+                        help="emit one stderr line per invocation")
+    args = parser.parse_args(argv)
+    return run(sys.stdin.read(), consumer_root=Path.cwd(), verbose=args.verbose)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

package/scripts/schemas/command.schema.json

@@ -9,7 +9,8 @@
   "properties": {
     "name": {
       "type": "string",
-      "pattern": "^[a-z][a-z0-9-]*$"
+      "pattern": "^[a-z][a-z0-9-]*(:[a-z][a-z0-9-]*)?$",
+      "$comment": "Top-level commands use the bare slug (`commit`). Nested cluster commands under `commands/<cluster>/<sub>.md` use the colon form (`council:default`) to mirror Claude Code's `/cluster:sub` rendering. Directory slug for `.claude/skills/` is the hyphenated form (`council-default`), generated by compress.py."
     },
     "description": {
       "type": "string",
@@ -40,8 +41,8 @@
     },
     "superseded_by": {
       "type": "string",
-      "pattern": "^[a-z][a-z0-9-]*( [a-z][a-z0-9-]*)?$",
-      "description": "Set on deprecation shims. Format: '<cluster> <sub>' (e.g. 'fix ci'). See docs/contracts/command-clusters.md § Deprecation shim contract."
+      "pattern": "^[a-z][a-z0-9-]*( (--[a-z][a-z0-9-]*|[a-z][a-z0-9-]*))?$",
+      "description": "Set on deprecation shims. Format: '<cluster> <sub>' (e.g. 'fix ci') or '<cluster> --<flag>' for flag-clusters (e.g. 'commit --in-chunks'). See docs/contracts/command-clusters.md § Deprecation shim contract."
     },
     "deprecated_in": {
       "type": "string",

package/scripts/schemas/rule.schema.json

@@ -33,6 +33,11 @@
       "type": "array",
       "items": {"type": "string", "pattern": "\\.md$"},
       "description": "Eager auto-loaded context references. Counts against the per-rule char budget; enforced by scripts/lint_load_context.py."
+    },
+    "tier": {
+      "type": "string",
+      "enum": ["1", "2a", "2b", "3", "safety-floor", "mechanical-already"],
+      "description": "Hardening tier per road-to-rule-hardening.md. Optional today, recommended for new rules. Tracked in agents/contexts/rule-trigger-matrix.md. Tier 3 rules also referenced in agents/contexts/tier-3-dispositions.md."
     }
   }
 }

package/scripts/skill_linter.py

@@ -886,6 +886,7 @@ def lint_command(path: Path, text: str) -> LintResult:
                     "error", "shim_missing_warning",
                     "Deprecation shim must contain a one-line warning matching "
                     "'⚠️  /<old-name> is deprecated; use /<cluster> <sub> instead.'"
+                    " (or '/<cluster> --<flag>' for flag-clusters)"
                     " (see docs/contracts/command-clusters.md § Deprecation shim contract)"
                 ))
 

package/scripts/sync_agent_settings.py

@@ -136,8 +136,31 @@ def _append_unknown(body: str, user_flat: dict[str, object], known: set[str]) ->
 
 
 def render_target(template_body: str, user_data: dict) -> str:
-    """Return the desired `.agent-settings.yml` body for the given user data."""
-    user_flat = _flatten(user_data) if user_data else {}
+    """Return the desired `.agent-settings.yml` body for the given user data.
+
+    The trailing ``_user:`` block (emitted by :func:`_append_unknown`) is
+    already in dotted-key form on every read after the first sync. Re-
+    flattening it would prepend another ``_user.`` segment on every run
+    and accumulate forever, so we strip the wrapper and merge its
+    contents straight into the flat dict.
+    """
+    if user_data:
+        user_only = user_data.pop("_user", None) if isinstance(user_data, dict) else None
+        user_flat = _flatten(user_data)
+        if isinstance(user_only, dict):
+            for key, value in user_only.items():
+                # Dotted keys round-trip verbatim — never re-flatten them.
+                if isinstance(key, str):
+                    # Heal legacy corruption: pre-fix syncs prepended a
+                    # `_user.` segment per run, so a key may carry an
+                    # arbitrary number of them. Strip them all back to
+                    # the original leaf path.
+                    healed = key
+                    while healed.startswith("_user."):
+                        healed = healed[len("_user."):]
+                    user_flat[healed] = value
+    else:
+        user_flat = {}
     known = _template_keys(template_body)
     body = _apply_user_values(template_body, user_flat)
     return _append_unknown(body, user_flat, known)

package/scripts/update_counts.py

@@ -37,6 +37,13 @@ def count(kind: str) -> int:
         if not pdir.exists():
             return 0
         return sum(1 for f in pdir.glob("*.md") if f.name != "README.md")
+    if kind == "commands":
+        # Commands may be flat (`commands/<name>.md`) or nested under a
+        # cluster directory (`commands/<cluster>/<sub>.md`). Walk the tree
+        # and skip the AGENTS.md reference orchestrator.
+        return sum(
+            1 for f in (SRC / kind).rglob("*.md") if f.name != "AGENTS.md"
+        )
     return sum(1 for _ in (SRC / kind).glob("*.md"))