@event4u/agent-config 1.16.0 → 1.18.0

package/scripts/check_references.py

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

package/scripts/check_safety_floor_untouched.py

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

package/scripts/command_suggester/loader.py

@@ -26,7 +26,10 @@ def load_commands(commands_dir: Path) -> list[CommandSpec]:
     this loader.
     """
     specs: list[CommandSpec] = []
-    for path in sorted(commands_dir.glob("*.md")):
+    for path in sorted(commands_dir.rglob("*.md")):
+        # Skip cluster authoring docs — not commands.
+        if path.name == "AGENTS.md":
+            continue
         text = path.read_text(encoding="utf-8")
         data, _offset = parse_frontmatter(text)
         if data is None:

package/scripts/compress.py

@@ -312,6 +312,29 @@ def generate_gemini_md() -> None:
     print("  ✅  Created GEMINI.md → AGENTS.md symlink")
 
 
+def _command_slug(source_file: Path) -> str:
+    """Return the flat .claude/skills/ slug for a command source file.
+
+    Top-level commands keep their stem (`commit.md` → `commit`). Nested
+    commands flatten the relative path with `-` (`council/default.md` →
+    `council-default`). Keeps slug collisions out of `.claude/skills/`
+    while preserving native nested invocation in `.agent-src/commands/`.
+    """
+    rel = source_file.relative_to(COMMANDS_SOURCE)
+    return "-".join(rel.with_suffix("").parts)
+
+
+def _iter_commands():
+    """Yield (source_file, slug) for every command .md file (recursive)."""
+    if not COMMANDS_SOURCE.exists():
+        return
+    for source_file in sorted(COMMANDS_SOURCE.rglob("*.md")):
+        # Skip the cluster AGENTS.md authoring doc (not a command).
+        if source_file.name == "AGENTS.md":
+            continue
+        yield source_file, _command_slug(source_file)
+
+
 def generate_claude_skills() -> None:
     """Create .claude/skills/ symlinks for ALL skills in .agent-src/skills/.
     """
@@ -321,16 +344,14 @@ def generate_claude_skills() -> None:
 
     # All skill directories in .agent-src/skills/
     skills = sorted([d.name for d in SKILLS_SOURCE.iterdir() if d.is_dir()])
-    # All command names (to protect from stale cleanup)
-    command_names = set()
-    if COMMANDS_SOURCE.exists():
-        command_names = {f.stem for f in COMMANDS_SOURCE.glob("*.md")}
+    # All command slugs (to protect from stale cleanup)
+    command_slugs = {slug for _, slug in _iter_commands()}
 
     CLAUDE_SKILLS_DIR.mkdir(parents=True, exist_ok=True)
 
     # Clean stale symlinks (but not converted commands or README)
     for item in CLAUDE_SKILLS_DIR.iterdir():
-        if item.is_symlink() and item.name not in skills and item.name not in command_names and item.name != "README.md":
+        if item.is_symlink() and item.name not in skills and item.name not in command_slugs and item.name != "README.md":
             item.unlink()
 
     count = 0
@@ -357,11 +378,15 @@ def extract_description_from_md(content: str) -> str:
 
 
 def generate_claude_commands() -> None:
-    """Create .claude/skills/{name}/SKILL.md symlinks for ALL Augment commands.
+    """Create .claude/skills/{slug}/SKILL.md symlinks for ALL Augment commands.
 
     Commands in .agent-src/commands/ are the single source of truth.
     They must include name: and disable-model-invocation: true in frontmatter
     (added once, then maintained as part of the command file).
+
+    Top-level commands use their filename stem as the slug. Nested
+    cluster commands (e.g. `commands/council/default.md`) are flattened
+    to `council-default` so directories never collide in `.claude/skills/`.
     """
     if not COMMANDS_SOURCE.exists():
         print("  ⚠️  .agent-src/commands/ not found — skipping commands")
@@ -374,32 +399,53 @@ def generate_claude_commands() -> None:
     if SKILLS_SOURCE.exists():
         skill_names = {d.name for d in SKILLS_SOURCE.iterdir() if d.is_dir()}
 
+    # Track current command slugs for stale-directory cleanup
+    current_slugs: set[str] = set()
     count = 0
     skipped = 0
-    for source_file in sorted(COMMANDS_SOURCE.glob("*.md")):
-        name = source_file.stem
-
+    for source_file, slug in _iter_commands():
         # Skip if a real skill with the same name exists — skill takes priority
-        if name in skill_names:
+        if slug in skill_names:
             skipped += 1
             continue
 
+        current_slugs.add(slug)
+
         # Create skill directory (real dir, symlinked SKILL.md inside)
-        skill_dir = CLAUDE_SKILLS_DIR / name
+        skill_dir = CLAUDE_SKILLS_DIR / slug
         skill_dir.mkdir(parents=True, exist_ok=True)
 
         skill_file = skill_dir / "SKILL.md"
         if skill_file.exists() or skill_file.is_symlink():
             skill_file.unlink()
 
-        # Symlink: .claude/skills/{name}/SKILL.md → ../../../.agent-src/commands/{name}.md
-        rel_target = Path("../../../.agent-src/commands") / source_file.name
+        # Symlink: .claude/skills/{slug}/SKILL.md → ../../../.agent-src/commands/<rel-path>
+        rel_path = source_file.relative_to(COMMANDS_SOURCE)
+        rel_target = Path("../../../.agent-src/commands") / rel_path
         skill_file.symlink_to(rel_target)
         count += 1
 
+    # Clean stale command skill directories — real dirs from removed commands.
+    # Only delete if the directory contains exactly the SKILL.md symlink we created.
+    removed_dirs = 0
+    for item in CLAUDE_SKILLS_DIR.iterdir():
+        if not item.is_dir() or item.is_symlink():
+            continue
+        if item.name in skill_names or item.name in current_slugs:
+            continue
+        skill_md = item / "SKILL.md"
+        if skill_md.is_symlink():
+            entries = list(item.iterdir())
+            if len(entries) == 1 and entries[0].name == "SKILL.md":
+                skill_md.unlink()
+                item.rmdir()
+                removed_dirs += 1
+
     msg = f"  ✅  Created {count} command symlinks in .claude/skills/"
     if skipped:
         msg += f" ({skipped} skipped — same-name skill exists)"
+    if removed_dirs:
+        msg += f" ({removed_dirs} stale dirs removed)"
     print(msg)
 
 
@@ -515,8 +561,11 @@ def project_to_augment() -> None:
             dst.symlink_to(Path("..") / ".agent-src" / name)
             print(f"  ✅  Symlinked .augment/{name} → ../.agent-src/{name}")
 
-    # Cleanup: remove any stray top-level entries in .augment/ that are no longer projected
-    known = set(AUGMENT_SYMLINK_DIRS) | set(AUGMENT_SYMLINK_FILES) | {"rules"}
+    # Cleanup: remove any stray top-level entries in .augment/ that are no longer projected.
+    # `state` holds runtime state files written by hooks (onboarding-gate,
+    # context-hygiene, …) and must survive sync — it is regenerated by
+    # the next hook fire, not by compress.
+    known = set(AUGMENT_SYMLINK_DIRS) | set(AUGMENT_SYMLINK_FILES) | {"rules", "state"}
     for item in AUGMENT_DIR.iterdir():
         if item.name in known:
             continue

package/scripts/context_hygiene_hook.py

@@ -0,0 +1,173 @@
+#!/usr/bin/env python3
+"""Platform-agnostic PostToolUse hook for the `context-hygiene` rule.
+
+Maintains a deterministic state file the rule body cites for the
+freshness threshold, the 3-failure stop, and tool-loop detection. The
+agent's job shrinks from "remember three counters" to "read this file
+before responding".
+
+Output: `agents/state/context-hygiene.json`
+  {
+    "tool_calls": <int>,                 // running PostToolUse count
+    "consecutive_same_tool": <int>,      // includes the latest call
+    "last_tool": "<name>",
+    "tool_history": [..., last 5 names],
+    "loop_detected": <bool>,             // ≥ 3 same tool in a row
+    "freshness_threshold": <int|null>,   // 20/40/60 milestone hit
+    "checked_at": "<iso8601>"
+  }
+
+Exit code is always 0.
+
+CLI:
+  python3 scripts/context_hygiene_hook.py [--platform NAME] [--verbose]
+"""
+from __future__ import annotations
+
+import argparse
+import datetime as _dt
+import json
+import sys
+from pathlib import Path
+
+STATE_DIR = Path("agents") / "state"
+STATE_FILE = STATE_DIR / "context-hygiene.json"
+
+LOOP_THRESHOLD = 3                  # 3+ consecutive same-tool calls
+HISTORY_DEPTH = 5
+FRESHNESS_MILESTONES = (20, 40, 60)
+
+
+def _load_state(target: Path) -> dict:
+    if not target.is_file():
+        return {
+            "tool_calls": 0,
+            "consecutive_same_tool": 0,
+            "last_tool": None,
+            "tool_history": [],
+            "loop_detected": False,
+            "freshness_threshold": None,
+        }
+    try:
+        decoded = json.loads(target.read_text(encoding="utf-8"))
+        if isinstance(decoded, dict):
+            return decoded
+    except (OSError, json.JSONDecodeError):
+        pass
+    # Corrupt — start fresh, never block.
+    return {
+        "tool_calls": 0,
+        "consecutive_same_tool": 0,
+        "last_tool": None,
+        "tool_history": [],
+        "loop_detected": False,
+        "freshness_threshold": None,
+    }
+
+
+def _extract_tool(payload: dict) -> str | None:
+    for key in ("tool_name", "toolName", "tool"):
+        v = payload.get(key)
+        if isinstance(v, str) and v:
+            return v
+    return None
+
+
+def _milestone_hit(prev: int, curr: int) -> int | None:
+    """Return the milestone crossed by going from `prev` to `curr`, else None."""
+    for ms in FRESHNESS_MILESTONES:
+        if prev < ms <= curr:
+            return ms
+    return None
+
+
+def _update(state: dict, tool: str | None) -> dict:
+    if tool is None:
+        # Non-tool event (e.g. malformed payload) — still mark we ran.
+        state["checked_at"] = _dt.datetime.now(_dt.timezone.utc).isoformat(
+            timespec="seconds")
+        return state
+
+    prev_count = int(state.get("tool_calls") or 0)
+    curr_count = prev_count + 1
+    state["tool_calls"] = curr_count
+
+    last = state.get("last_tool")
+    if last == tool:
+        state["consecutive_same_tool"] = int(
+            state.get("consecutive_same_tool") or 0) + 1
+    else:
+        state["consecutive_same_tool"] = 1
+    state["last_tool"] = tool
+
+    hist = state.get("tool_history") or []
+    if not isinstance(hist, list):
+        hist = []
+    hist.append(tool)
+    state["tool_history"] = hist[-HISTORY_DEPTH:]
+
+    state["loop_detected"] = (
+        state["consecutive_same_tool"] >= LOOP_THRESHOLD)
+
+    ms = _milestone_hit(prev_count, curr_count)
+    if ms is not None:
+        state["freshness_threshold"] = ms
+    state["checked_at"] = _dt.datetime.now(_dt.timezone.utc).isoformat(
+        timespec="seconds")
+    return state
+
+
+def _write_state(consumer_root: Path, state: dict) -> None:
+    state_dir = consumer_root / STATE_DIR
+    state_dir.mkdir(parents=True, exist_ok=True)
+    target = consumer_root / STATE_FILE
+    tmp = target.with_suffix(".json.tmp")
+    tmp.write_text(json.dumps(state, indent=2) + "\n", encoding="utf-8")
+    tmp.replace(target)
+
+
+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:
+            pass  # silent no-op, never block
+
+    target = consumer_root / STATE_FILE
+    state = _load_state(target)
+    state = _update(state, _extract_tool(payload))
+
+    try:
+        _write_state(consumer_root, state)
+    except OSError:
+        if verbose:
+            print("context-hygiene-hook: state write failed",
+                  file=sys.stderr)
+        return 0
+
+    if verbose:
+        print(
+            f"context-hygiene-hook: tool_calls={state.get('tool_calls')} "
+            f"loop={state.get('loop_detected')} "
+            f"threshold={state.get('freshness_threshold')}",
+            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)
+    return run(sys.stdin.read(), consumer_root=Path.cwd(),
+               verbose=args.verbose)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

package/scripts/generate_index.py

@@ -95,7 +95,10 @@ def _collect_rules() -> list[Entry]:
 
 def _collect_commands() -> list[Entry]:
     out = []
-    for cmd_md in sorted((SRC / "commands").glob("*.md")):
+    cmd_dir = SRC / "commands"
+    for cmd_md in sorted(cmd_dir.rglob("*.md")):
+        if cmd_md.name == "AGENTS.md":
+            continue
         fm = _parse_frontmatter(cmd_md.read_text(encoding="utf-8"))
         is_shim = bool(fm.get("superseded_by"))
         extra = ""
@@ -103,12 +106,13 @@ def _collect_commands() -> list[Entry]:
             extra = f"shim → /{fm['superseded_by']}"
         elif fm.get("cluster"):
             extra = f"cluster: {fm['cluster']}"
+        rel = cmd_md.relative_to(cmd_dir)
         out.append(Entry(
             kind="shim" if is_shim else "command",
             name=fm.get("name") or cmd_md.stem,
             description=_truncate(fm.get("description", "")),
             extra=extra,
-            path=f".agent-src.uncompressed/commands/{cmd_md.name}",
+            path=f".agent-src.uncompressed/commands/{rel}",
         ))
     return out