@event4u/agent-config 1.16.0 → 1.17.0

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/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/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"))