@event4u/agent-config 1.17.0 → 1.18.0

package/scripts/check_one_off_location.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+"""One-off script-location guard (Phase 0a.2 of road-to-rule-hardening).
+
+Every ``_one_off_*.py`` script under ``scripts/`` must live inside the
+archive folder ``scripts/ai_council/one_off_archive/<YYYY-MM>/``. The
+guard fails CI if a new probe lands anywhere else in the tree.
+
+Rationale: one-off council probes / phase-specific measurements are
+inherently single-purpose; their durable artefact is the council
+session under ``agents/council-sessions/``. Keeping them in the
+archive prevents the ``scripts/`` root from accumulating noise and
+makes their lifecycle visible (folder == month archived).
+
+Exit codes:
+    0 = clean
+    1 = violation (script outside the archive)
+    3 = internal error
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+SCRIPTS = REPO_ROOT / "scripts"
+ARCHIVE = SCRIPTS / "ai_council" / "one_off_archive"
+ARCHIVE_MONTH_RE = re.compile(r"^\d{4}-\d{2}$")
+
+
+def find_violations() -> list[Path]:
+    """Return one-off scripts that are outside the archive folder."""
+    violations: list[Path] = []
+    for path in SCRIPTS.rglob("_one_off_*.py"):
+        if not path.is_file():
+            continue
+        # Must live under scripts/ai_council/one_off_archive/<YYYY-MM>/
+        try:
+            rel = path.relative_to(ARCHIVE)
+        except ValueError:
+            violations.append(path)
+            continue
+        # rel = "<YYYY-MM>/<name>.py"
+        parts = rel.parts
+        if len(parts) != 2 or not ARCHIVE_MONTH_RE.match(parts[0]):
+            violations.append(path)
+    return violations
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.strip().splitlines()[0])
+    parser.add_argument("--quiet", action="store_true", help="Only print on failure")
+    args = parser.parse_args()
+
+    try:
+        violations = find_violations()
+    except Exception as exc:  # pragma: no cover — defensive
+        print(f"❌  internal error: {exc}", file=sys.stderr)
+        return 3
+
+    if violations:
+        print("❌  one-off scripts outside the archive:", file=sys.stderr)
+        for path in violations:
+            rel = path.relative_to(REPO_ROOT)
+            print(f"    {rel}", file=sys.stderr)
+        print(
+            "\n  Move them under "
+            "scripts/ai_council/one_off_archive/<YYYY-MM>/ "
+            "(see that folder's README.md).",
+            file=sys.stderr,
+        )
+        return 1
+
+    if not args.quiet:
+        print("✅  all _one_off_*.py scripts are archived")
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

package/scripts/check_references.py

@@ -274,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/compress.py

@@ -561,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/hooks/augment-context-hygiene.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# Augment Code lifecycle-hook trampoline for context-hygiene.
+#
+# Augment requires hook scripts to use the .sh extension and live at
+# either a system path (/etc/augment/...) or user scope
+# (~/.augment/...). This trampoline lives at user scope and dispatches
+# every PostToolUse event to whichever workspace fired it, so a single
+# install covers every project that has ./agent-config available.
+#
+# Behaviour:
+#   - Read the JSON event from stdin into a buffer.
+#   - Extract workspace_roots[0]; bail silently when missing.
+#   - cd into that workspace; bail silently when it is not a directory
+#     or does not contain ./agent-config.
+#   - Re-pipe the original JSON into
+#       ./agent-config context-hygiene:hook --platform augment
+#     so context_hygiene_hook.py can update the per-turn tracker.
+#   - Always exit 0 — PostToolUse hooks must never block.
+
+set -u
+
+EVENT_DATA="$(cat)"
+
+WORKSPACE=""
+if command -v jq >/dev/null 2>&1; then
+    WORKSPACE="$(printf '%s' "$EVENT_DATA" \
+        | jq -r '.workspace_roots[0] // empty' 2>/dev/null)"
+elif command -v python3 >/dev/null 2>&1; then
+    WORKSPACE="$(printf '%s' "$EVENT_DATA" | python3 -c '
+import json, sys
+try:
+    data = json.load(sys.stdin)
+except Exception:
+    sys.exit(0)
+roots = data.get("workspace_roots") or []
+if roots:
+    print(roots[0])
+' 2>/dev/null)"
+fi
+
+if [ -z "$WORKSPACE" ] || [ ! -d "$WORKSPACE" ]; then
+    exit 0
+fi
+
+cd "$WORKSPACE" 2>/dev/null || exit 0
+
+if [ ! -x ./agent-config ]; then
+    exit 0
+fi
+
+printf '%s' "$EVENT_DATA" \
+    | ./agent-config context-hygiene:hook --platform augment \
+        >/dev/null 2>&1 || true
+
+exit 0

package/scripts/hooks/augment-onboarding-gate.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# Augment Code lifecycle-hook trampoline for onboarding-gate.
+#
+# Augment requires hook scripts to use the .sh extension and live at
+# either a system path (/etc/augment/...) or user scope
+# (~/.augment/...). This trampoline lives at user scope and dispatches
+# every event to whichever workspace fired it, so a single install
+# covers every project that has ./agent-config available.
+#
+# Behaviour:
+#   - Read the JSON event from stdin into a buffer.
+#   - Extract workspace_roots[0]; bail silently when missing.
+#   - cd into that workspace; bail silently when it is not a directory
+#     or does not contain ./agent-config.
+#   - Re-pipe the original JSON into
+#       ./agent-config onboarding-gate:hook --platform augment
+#     so onboarding_gate_hook.py can refresh the state file.
+#   - Always exit 0 — onboarding-gate must never block the agent loop.
+
+set -u
+
+EVENT_DATA="$(cat)"
+
+WORKSPACE=""
+if command -v jq >/dev/null 2>&1; then
+    WORKSPACE="$(printf '%s' "$EVENT_DATA" \
+        | jq -r '.workspace_roots[0] // empty' 2>/dev/null)"
+elif command -v python3 >/dev/null 2>&1; then
+    WORKSPACE="$(printf '%s' "$EVENT_DATA" | python3 -c '
+import json, sys
+try:
+    data = json.load(sys.stdin)
+except Exception:
+    sys.exit(0)
+roots = data.get("workspace_roots") or []
+if roots:
+    print(roots[0])
+' 2>/dev/null)"
+fi
+
+if [ -z "$WORKSPACE" ] || [ ! -d "$WORKSPACE" ]; then
+    exit 0
+fi
+
+cd "$WORKSPACE" 2>/dev/null || exit 0
+
+if [ ! -x ./agent-config ]; then
+    exit 0
+fi
+
+printf '%s' "$EVENT_DATA" \
+    | ./agent-config onboarding-gate:hook --platform augment \
+        >/dev/null 2>&1 || true
+
+exit 0

package/scripts/install.py

@@ -466,6 +466,8 @@ AUGMENT_USER_DIR = Path.home() / ".augment"
 AUGMENT_USER_HOOKS_DIR = AUGMENT_USER_DIR / "hooks"
 AUGMENT_CHAT_HISTORY_TRAMPOLINE = "augment-chat-history.sh"
 AUGMENT_ROADMAP_PROGRESS_TRAMPOLINE = "augment-roadmap-progress.sh"
+AUGMENT_ONBOARDING_GATE_TRAMPOLINE = "augment-onboarding-gate.sh"
+AUGMENT_CONTEXT_HYGIENE_TRAMPOLINE = "augment-context-hygiene.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
@@ -475,6 +477,10 @@ AUGMENT_HOOK_BINDINGS = (
      ("SessionStart", "SessionEnd", "Stop", "PostToolUse")),
     (AUGMENT_ROADMAP_PROGRESS_TRAMPOLINE,
      ("PostToolUse",)),
+    (AUGMENT_ONBOARDING_GATE_TRAMPOLINE,
+     ("SessionStart",)),
+    (AUGMENT_CONTEXT_HYGIENE_TRAMPOLINE,
+     ("PostToolUse",)),
 )
 
 
@@ -505,10 +511,15 @@ def ensure_augment_user_hooks(package_root: Path, force: bool) -> None:
     payload and dispatches into whichever project is active at hook-fire
     time.
 
-    Two trampolines are deployed:
-      - augment-chat-history.sh   → SessionStart/SessionEnd/Stop/PostToolUse
+    Trampolines deployed (see AUGMENT_HOOK_BINDINGS for the source of
+    truth):
+      - augment-chat-history.sh    → SessionStart/SessionEnd/Stop/PostToolUse
       - augment-roadmap-progress.sh → PostToolUse (path-filtered to
         agents/roadmaps/ — see scripts/roadmap_progress_hook.py)
+      - augment-onboarding-gate.sh  → SessionStart (refresh
+        agents/state/onboarding-gate.json from .agent-settings.yml)
+      - augment-context-hygiene.sh  → PostToolUse (per-turn counter,
+        loop detection, freshness milestones)
     """
     per_event: dict[str, list] = {}
     for name, events in AUGMENT_HOOK_BINDINGS:
@@ -531,36 +542,64 @@ def ensure_augment_user_hooks(package_root: Path, force: bool) -> None:
     )
 
 
-def _chat_history_hook_block(platform: str) -> dict:
-    """Single hook entry that calls ./agent-config chat-history:hook --platform <name>."""
+def _claude_hook_block(subcommand: str) -> dict:
+    """Single hook entry that calls ./agent-config <subcommand> --platform claude."""
     return {
         "hooks": [
             {
                 "type": "command",
-                "command": f"./agent-config chat-history:hook --platform {platform}",
+                "command": f"./agent-config {subcommand} --platform claude",
             },
         ],
     }
 
 
-def ensure_claude_bridge(project_root: Path, force: bool) -> None:
-    """Deploy .claude/settings.json with plugin enablement and chat-history hooks.
+# Claude Code Tier 1 hook bindings — keep in sync with AUGMENT_HOOK_BINDINGS.
+# `chat-history:hook` is the cross-cutting transcript hook; the three
+# rule-specific hooks are the Phase 4 Tier 1 set from
+# `road-to-rule-hardening.md`.
+CLAUDE_HOOK_SUBCOMMANDS = {
+    "chat-history":     "chat-history:hook",
+    "roadmap-progress": "roadmap-progress:hook",
+    "onboarding-gate":  "onboarding-gate:hook",
+    "context-hygiene":  "context-hygiene:hook",
+}
+# (subcommand-key, list of Claude Code lifecycle events). Mirrors
+# AUGMENT_HOOK_BINDINGS so each rule fires on the same logical surface
+# on both platforms — the contract from
+# `agents/contexts/hardening-pattern.md` § Cross-platform parity.
+CLAUDE_HOOK_BINDINGS = (
+    ("chat-history",
+     ("SessionStart", "UserPromptSubmit", "PostToolUse", "Stop", "SessionEnd")),
+    ("roadmap-progress",
+     ("PostToolUse",)),
+    ("onboarding-gate",
+     ("SessionStart",)),
+    ("context-hygiene",
+     ("PostToolUse",)),
+)
 
-    Hooks dispatch to scripts/chat_history.py via the project-root ./agent-config
-    wrapper. They are no-ops when chat_history.enabled is false in
-    .agent-settings.yml. Idempotent: reruns merge cleanly without duplicating
-    entries (deep_merge replaces hook arrays rather than appending).
+
+def ensure_claude_bridge(project_root: Path, force: bool) -> None:
+    """Deploy .claude/settings.json with plugin enablement and Tier 1 hooks.
+
+    Hooks dispatch to the project-root ./agent-config wrapper, which routes
+    to the per-rule Python implementation (chat_history.py,
+    roadmap_progress_hook.py, onboarding_gate_hook.py,
+    context_hygiene_hook.py). They are no-ops when the relevant feature is
+    disabled in .agent-settings.yml. Idempotent: reruns merge cleanly
+    without duplicating entries (deep_merge replaces hook arrays rather
+    than appending).
     """
-    claude_hook = _chat_history_hook_block("claude")
+    per_event: dict[str, list] = {}
+    for key, events in CLAUDE_HOOK_BINDINGS:
+        block = _claude_hook_block(CLAUDE_HOOK_SUBCOMMANDS[key])
+        for event in events:
+            per_event.setdefault(event, []).append(block)
+
     bridge = {
         "enabledPlugins": {"agent-conf@event4u": True},
-        "hooks": {
-            "SessionStart":     [claude_hook],
-            "UserPromptSubmit": [claude_hook],
-            "PostToolUse":      [claude_hook],
-            "Stop":             [claude_hook],
-            "SessionEnd":       [claude_hook],
-        },
+        "hooks": per_event,
     }
     merge_json_file(project_root / ".claude" / "settings.json", bridge, force, ".claude/settings.json")
 

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