@event4u/agent-config 1.15.0 → 1.17.0

package/scripts/install.py

@@ -464,44 +464,65 @@ def ensure_augment_bridge(project_root: Path, force: bool) -> None:
 # .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")
+AUGMENT_CHAT_HISTORY_TRAMPOLINE = "augment-chat-history.sh"
+AUGMENT_ROADMAP_PROGRESS_TRAMPOLINE = "augment-roadmap-progress.sh"
+# (trampoline name, list of events it should fire on). Each trampoline
+# is a self-contained workspace router; mapping them per-event keeps the
+# wiring explicit and lets a future hook bind to a different surface
+# without touching the chat-history one.
+AUGMENT_HOOK_BINDINGS = (
+    (AUGMENT_CHAT_HISTORY_TRAMPOLINE,
+     ("SessionStart", "SessionEnd", "Stop", "PostToolUse")),
+    (AUGMENT_ROADMAP_PROGRESS_TRAMPOLINE,
+     ("PostToolUse",)),
+)
+
+
+def _deploy_augment_trampoline(package_root: Path, name: str, force: bool) -> Path | None:
+    src = package_root / "scripts" / "hooks" / name
+    if not src.exists():
+        skip(f"augment trampoline missing in package: {src}")
+        return None
+    AUGMENT_USER_HOOKS_DIR.mkdir(parents=True, exist_ok=True)
+    dst = AUGMENT_USER_HOOKS_DIR / 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/{name} already up to date")
+    else:
+        dst.write_text(src_text, encoding="utf-8")
+        dst.chmod(0o755)
+        success(f"~/.augment/hooks/{name} installed")
+    return dst
 
 
 def ensure_augment_user_hooks(package_root: Path, force: bool) -> None:
-    """Deploy the Augment lifecycle-hook trampoline at user scope.
+    """Deploy the Augment lifecycle-hook trampolines 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.
+    project) — each trampoline reads workspace_roots from the event
+    payload and dispatches into whichever project is active at hook-fire
+    time.
+
+    Two trampolines are deployed:
+      - augment-chat-history.sh   → SessionStart/SessionEnd/Stop/PostToolUse
+      - augment-roadmap-progress.sh → PostToolUse (path-filtered to
+        agents/roadmaps/ — see scripts/roadmap_progress_hook.py)
     """
-    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
+    per_event: dict[str, list] = {}
+    for name, events in AUGMENT_HOOK_BINDINGS:
+        dst = _deploy_augment_trampoline(package_root, name, force)
+        if dst is None:
+            continue
+        entry = {"hooks": [{"type": "command", "command": str(dst)}]}
+        for event in events:
+            per_event.setdefault(event, []).append(entry)
 
-    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")
+    if not per_event:
+        return
 
-    hook_entry = {
-        "hooks": [
-            {
-                "type": "command",
-                "command": str(dst),
-            },
-        ],
-    }
-    settings_patch: dict = {"hooks": {event: [hook_entry] for event in AUGMENT_HOOK_EVENTS}}
+    settings_patch: dict = {"hooks": per_event}
     merge_json_file(
         AUGMENT_USER_DIR / "settings.json",
         settings_patch,

package/scripts/install_anthropic_key.sh

@@ -99,3 +99,8 @@ echo "✅  Key installed: ${TARGET_FILE} (mode 0600)."
 echo "    Verify:  ls -la ${TARGET_FILE}"
 echo "    Rotate:  rerun this script (you'll be prompted to overwrite)."
 echo "    Remove:  rm ${TARGET_FILE}"
+echo
+echo "ℹ️   Key install ≠ enable. To use this provider in /council:"
+echo "    set ai_council.enabled: true and ai_council.members.anthropic.enabled: true"
+echo "    in .agent-settings.yml. Council is a 'full' cost_profile feature; under"
+echo "    'minimal' / 'balanced' the runtime hooks stay inactive."

package/scripts/install_openai_key.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# Interactive OpenAI-API-key installer for scripts/ai_council/clients.py.
+#
+# Reads the key with `read -s` so it never echoes to the terminal and
+# never lands in shell history or scrollback. Writes atomically to
+# ~/.config/agent-config/openai.key with mode 0600.
+#
+# Contract — companion to scripts/ai_council/clients.py:
+#   - File path:  $HOME/.config/agent-config/openai.key
+#   - File mode:  0600 (owner read/write only)
+#   - Key format: must start with `sk-`
+#   - No --force, no --yes, no env-var bypass. Piped stdin is rejected.
+#
+# The runner re-checks all of the above at every live invocation and
+# refuses to run if the file drifts from this contract.
+
+set -euo pipefail
+
+TARGET_DIR="${HOME}/.config/agent-config"
+TARGET_FILE="${TARGET_DIR}/openai.key"
+
+# ── controlling-terminal requirement ─────────────────────────────────────
+# We read from /dev/tty directly (fd 3), not from stdin. This is the
+# stricter and more portable contract:
+#   - works under `task`, `script`, `sudo`, anything that reattaches stdin
+#   - forces every character to come from the user's real keyboard, so a
+#     pipe or redirected file cannot smuggle the key into the process
+#   - exits cleanly if there is no controlling terminal at all (e.g. CI,
+#     cron, agent automation)
+if ! exec 3</dev/tty 2>/dev/null; then
+    echo "❌  install_openai_key.sh requires a controlling terminal." >&2
+    echo "    /dev/tty not available — refusing to run under automation." >&2
+    exit 2
+fi
+
+# ── overwrite confirmation ───────────────────────────────────────────────
+if [[ -e "${TARGET_FILE}" ]]; then
+    echo "⚠️   ${TARGET_FILE} already exists."
+    printf "Overwrite? [type 'yes' to replace, anything else aborts]: "
+    read -r -u 3 answer
+    if [[ "${answer}" != "yes" ]]; then
+        echo "Aborted. Existing key untouched."
+        exit 0
+    fi
+fi
+
+# ── read key (no echo, no history) ───────────────────────────────────────
+echo "Paste your OpenAI API key (input is hidden, no echo)."
+echo "The key should start with 'sk-'."
+printf "Key: "
+# -s = silent (no echo), read from fd 3 = /dev/tty, not stdin.
+read -r -s -u 3 API_KEY
+echo
+
+if [[ -z "${API_KEY}" ]]; then
+    echo "❌  Empty input — no file written." >&2
+    exit 2
+fi
+
+if [[ "${API_KEY}" != sk-* ]]; then
+    echo "❌  Input does not look like an OpenAI key (missing 'sk-' prefix)." >&2
+    echo "    No file written." >&2
+    exit 2
+fi
+
+# ── create config dir with 0700, atomic write with 0600 ──────────────────
+mkdir -p "${TARGET_DIR}"
+chmod 0700 "${TARGET_DIR}"
+
+TMP_FILE="$(mktemp "${TARGET_DIR}/.openai.key.XXXXXX")"
+cleanup() { rm -f "${TMP_FILE}"; }
+trap cleanup EXIT
+
+# chmod the tmpfile BEFORE writing the key, so there is no window where
+# the key sits on disk with group/other-readable permissions.
+chmod 0600 "${TMP_FILE}"
+printf '%s\n' "${API_KEY}" > "${TMP_FILE}"
+mv "${TMP_FILE}" "${TARGET_FILE}"
+trap - EXIT
+
+# Clear the variable and the `mv` positional argument — defence in depth
+# against a crash handler that dumps the process environment.
+API_KEY=""
+
+# ── verify mode post-write (portable stat: BSD on macOS, GNU on Linux) ───
+if ACTUAL_MODE=$(stat -f '%Lp' "${TARGET_FILE}" 2>/dev/null); then
+    :  # macOS / BSD
+else
+    ACTUAL_MODE=$(stat -c '%a' "${TARGET_FILE}")
+fi
+
+if [[ "${ACTUAL_MODE}" != "600" ]]; then
+    echo "❌  Permissions verification failed: ${TARGET_FILE} has mode ${ACTUAL_MODE}, expected 600." >&2
+    echo "    Delete and reinstall:  rm ${TARGET_FILE} && $0" >&2
+    exit 3
+fi
+
+echo "✅  Key installed: ${TARGET_FILE} (mode 0600)."
+echo "    Verify:  ls -la ${TARGET_FILE}"
+echo "    Rotate:  rerun this script (you'll be prompted to overwrite)."
+echo "    Remove:  rm ${TARGET_FILE}"
+echo
+echo "ℹ️   Key install ≠ enable. To use this provider in /council:"
+echo "    set ai_council.enabled: true and ai_council.members.openai.enabled: true"
+echo "    in .agent-settings.yml. Council is a 'full' cost_profile feature; under"
+echo "    'minimal' / 'balanced' the runtime hooks stay inactive."

package/scripts/lint_load_context.py

@@ -0,0 +1,163 @@
+#!/usr/bin/env python3
+"""Lint the `load_context:` / `load_context_eager:` frontmatter schema.
+
+Validates per docs/contracts/load-context-schema.md:
+  - Paths exist and are .md
+  - Allowed roots only (.agent-src*/contexts/, agents/contexts/)
+  - No public→project-local leak (warn)
+  - No circular refs across lazy + eager edges
+  - Combined char-budget for eager edges (rule + eager targets ≤ cap)
+
+Exits non-zero on error; warnings are reported but do not fail.
+Used in CI via `task lint-load-context`.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Iterable
+
+import yaml
+
+ROOT = Path(__file__).resolve().parent.parent
+
+SCAN_DIRS = [
+    ROOT / ".agent-src.uncompressed" / "rules",
+    ROOT / ".agent-src.uncompressed" / "contexts",
+    ROOT / "agents" / "contexts",
+]
+
+ALLOWED_PREFIXES = (
+    ".agent-src.uncompressed/contexts/",
+    ".agent-src/contexts/",
+    "agents/contexts/",
+)
+
+PUBLIC_RULE_PREFIX = ".agent-src.uncompressed/rules/"
+PROJECT_LOCAL_PREFIX = "agents/contexts/"
+
+HARD_FLOOR_RULES = {"non-destructive-by-default", "security-sensitive-stop"}
+
+CAP_ALWAYS = 2_500
+CAP_AUTO = 4_000
+CAP_SAFETY = 5_000
+
+
+def parse_frontmatter(path: Path) -> dict:
+    text = path.read_text(encoding="utf-8")
+    if not text.startswith("---\n"):
+        return {}
+    end = text.find("\n---\n", 4)
+    if end == -1:
+        return {}
+    try:
+        data = yaml.safe_load(text[4:end])
+    except yaml.YAMLError:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def collect_files() -> Iterable[Path]:
+    for d in SCAN_DIRS:
+        if d.exists():
+            yield from d.rglob("*.md")
+
+
+def rel(p: Path) -> str:
+    return p.relative_to(ROOT).as_posix()
+
+
+def cap_for(rule_path: Path, fm: dict) -> int:
+    if rule_path.stem in HARD_FLOOR_RULES:
+        return CAP_SAFETY
+    rtype = (fm.get("type") or "").strip('"').strip("'")
+    if rtype == "always":
+        return CAP_ALWAYS
+    if rtype == "auto":
+        return CAP_AUTO
+    return CAP_AUTO  # default for non-rule contexts cited in eager (won't trigger)
+
+
+def find_cycles(graph: dict[str, list[str]]) -> list[list[str]]:
+    cycles: list[list[str]] = []
+    visiting: set[str] = set()
+    visited: set[str] = set()
+    stack: list[str] = []
+
+    def dfs(node: str) -> None:
+        if node in visiting:
+            i = stack.index(node)
+            cycles.append(stack[i:] + [node])
+            return
+        if node in visited:
+            return
+        visiting.add(node)
+        stack.append(node)
+        for nxt in graph.get(node, []):
+            dfs(nxt)
+        stack.pop()
+        visiting.discard(node)
+        visited.add(node)
+
+    for n in graph:
+        dfs(n)
+    return cycles
+
+
+def main() -> int:
+    errors: list[str] = []
+    warnings: list[str] = []
+    graph: dict[str, list[str]] = {}
+
+    for f in collect_files():
+        fm = parse_frontmatter(f)
+        lazy = fm.get("load_context") or []
+        eager = fm.get("load_context_eager") or []
+        if not (lazy or eager):
+            continue
+        if not isinstance(lazy, list) or not isinstance(eager, list):
+            errors.append(f"{rel(f)}: load_context* must be a list")
+            continue
+
+        edges = list(lazy) + list(eager)
+        graph[rel(f)] = edges
+
+        for entry in edges:
+            if not isinstance(entry, str) or not entry.endswith(".md"):
+                errors.append(f"{rel(f)}: entry not str ending in .md → {entry!r}")
+                continue
+            if not entry.startswith(ALLOWED_PREFIXES):
+                errors.append(f"{rel(f)}: disallowed root → {entry}")
+                continue
+            target = ROOT / entry
+            if not target.exists():
+                errors.append(f"{rel(f)}: target missing → {entry}")
+                continue
+            if rel(f).startswith(PUBLIC_RULE_PREFIX) and entry.startswith(PROJECT_LOCAL_PREFIX):
+                warnings.append(f"{rel(f)}: public rule references project-local context → {entry}")
+
+        if eager:
+            cap = cap_for(f, fm)
+            total = len(f.read_text(encoding="utf-8"))
+            for entry in eager:
+                tgt = ROOT / entry
+                if tgt.exists():
+                    total += len(tgt.read_text(encoding="utf-8"))
+            if total > cap:
+                errors.append(f"{rel(f)}: eager-load combined chars {total} > cap {cap}")
+
+    for cycle in find_cycles(graph):
+        errors.append("circular load_context: " + " → ".join(cycle))
+
+    for w in warnings:
+        print(f"⚠️  {w}")
+    for e in errors:
+        print(f"❌  {e}")
+    if errors:
+        return 1
+    print(f"✅  load_context schema clean ({len(graph)} declarer(s))")
+    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/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",
@@ -28,6 +29,26 @@
         "pattern": "^[a-z][a-z0-9-]*$"
       }
     },
+    "cluster": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Locked verb cluster this command belongs to. See docs/contracts/command-clusters.md."
+    },
+    "sub": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Sub-command identifier within the cluster (e.g. `ci` for `/fix ci`)."
+    },
+    "superseded_by": {
+      "type": "string",
+      "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",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
+      "description": "Semver release in which this command became a shim (e.g. '1.15.0')."
+    },
     "suggestion": {
       "type": "object",
       "additionalProperties": false,

package/scripts/schemas/rule.schema.json

@@ -23,6 +23,16 @@
     "alwaysApply": {
       "type": "boolean",
       "description": "Optional sidecar for Cursor/Cline; by convention true when type=always, false when type=auto."
+    },
+    "load_context": {
+      "type": "array",
+      "items": {"type": "string", "pattern": "\\.md$"},
+      "description": "Lazy on-demand context references. Path rules and budget caps enforced by scripts/lint_load_context.py. Contract: docs/contracts/load-context-schema.md."
+    },
+    "load_context_eager": {
+      "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."
     }
   }
 }