@event4u/agent-config 2.9.0 → 2.10.0

package/scripts/hooks/replay_hook.py

@@ -0,0 +1,144 @@
+#!/usr/bin/env python3
+"""Fixture-driven hook replay — read-only dispatch through the runtime.
+
+Reads a stdin payload fixture from `tests/fixtures/hooks/` (one file per
+event in `EVENT_VOCABULARY`), sets `AGENT_CONFIG_REPLAY=1`, and invokes
+the universal dispatcher with the platform / event / payload tuple. The
+replay flag tells `state_io` (and concerns that honour it) to skip every
+write under `agents/state/` so the replay never mutates real session
+state.
+
+Invocation:
+
+    python3 scripts/hooks/replay_hook.py \\
+        --platform <name> \\
+        --event <agent-config-event> \\
+        --payload tests/fixtures/hooks/<event>.json \\
+        [--native-event <native>] \\
+        [--manifest <path>] \\
+        [--json]
+
+The `--json` flag prints a structured replay summary on stdout
+(platform, event, dispatcher exit code, captured stderr lines).
+Non-zero exit is propagated from the dispatcher.
+
+Contract reference: `docs/contracts/hook-architecture-v1.md` § Replay
+mode. Roadmap step: P2.4b of `agents/roadmaps/road-to-proof-not-features.md`.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+DISPATCHER = REPO_ROOT / "scripts" / "hooks" / "dispatch_hook.py"
+DEFAULT_MANIFEST = REPO_ROOT / "scripts" / "hook_manifest.yaml"
+FIXTURE_DIR = REPO_ROOT / "tests" / "fixtures" / "hooks"
+REPLAY_ENV_VAR = "AGENT_CONFIG_REPLAY"
+
+
+def _resolve_payload(arg: str) -> Path:
+    """Accept either an absolute path, a path relative to CWD, or a bare
+    event name that resolves to `tests/fixtures/hooks/<name>.json`."""
+    candidate = Path(arg)
+    if candidate.is_file():
+        return candidate
+    bare = FIXTURE_DIR / f"{arg}.json"
+    if bare.is_file():
+        return bare
+    raise FileNotFoundError(
+        f"replay_hook: payload not found — tried '{candidate}' and '{bare}'")
+
+
+def _build_argparser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("--platform", required=True,
+                   help="Platform key as declared in hook_manifest.yaml "
+                        "(augment, claude, cursor, cline, windsurf, gemini, copilot).")
+    p.add_argument("--event", required=True,
+                   help="agent-config event (see EVENT_VOCABULARY in "
+                        "scripts/hooks/dispatch_hook.py).")
+    p.add_argument("--payload", required=True,
+                   help="Path to a fixture JSON file, or a bare event name "
+                        "resolved under tests/fixtures/hooks/.")
+    p.add_argument("--native-event", default="",
+                   help="Optional native event name for diagnostics.")
+    p.add_argument("--manifest", default=str(DEFAULT_MANIFEST),
+                   help=f"Hook manifest path (default: {DEFAULT_MANIFEST}).")
+    p.add_argument("--json", action="store_true",
+                   help="Emit a structured summary on stdout.")
+    p.add_argument("--dry-run", action="store_true",
+                   help="Resolve concerns and print the dispatch plan; "
+                        "do not invoke concerns.")
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _build_argparser().parse_args(argv)
+
+    try:
+        payload_path = _resolve_payload(args.payload)
+    except FileNotFoundError as exc:
+        sys.stderr.write(f"❌  {exc}\n")
+        return 2
+
+    payload_text = payload_path.read_text(encoding="utf-8")
+    # Validate JSON early so dispatcher stderr stays focused on real
+    # concern problems. Empty / non-object payloads are still dispatched
+    # — that mirrors the platform contract (stdin can be empty).
+    try:
+        decoded = json.loads(payload_text) if payload_text.strip() else {}
+    except (ValueError, TypeError) as exc:
+        sys.stderr.write(f"❌  replay_hook: invalid JSON in {payload_path}: {exc}\n")
+        return 2
+
+    env = dict(os.environ)
+    env[REPLAY_ENV_VAR] = "1"
+
+    cmd = [sys.executable, str(DISPATCHER),
+           "--platform", args.platform,
+           "--event", args.event,
+           "--manifest", args.manifest]
+    if args.native_event:
+        cmd.extend(["--native-event", args.native_event])
+    if args.dry_run:
+        cmd.append("--dry-run")
+
+    proc = subprocess.run(
+        cmd, input=payload_text, capture_output=True, text=True, env=env,
+        check=False,
+    )
+
+    if args.json:
+        summary = {
+            "platform": args.platform,
+            "event": args.event,
+            "native_event": args.native_event or "",
+            "payload": str(payload_path.relative_to(REPO_ROOT)
+                           if str(payload_path).startswith(str(REPO_ROOT))
+                           else payload_path),
+            "session_id": decoded.get("session_id") if isinstance(decoded, dict) else None,
+            "exit_code": proc.returncode,
+            "dispatcher_stdout": (proc.stdout or "").strip(),
+            "dispatcher_stderr": (proc.stderr or "").strip(),
+            "replay_mode": True,
+        }
+        print(json.dumps(summary, indent=2))
+    else:
+        if proc.stdout:
+            sys.stdout.write(proc.stdout)
+        if proc.stderr:
+            sys.stderr.write(proc.stderr)
+        sys.stderr.write(
+            f"replay_hook: platform={args.platform} event={args.event} "
+            f"payload={payload_path.name} rc={proc.returncode} "
+            f"(AGENT_CONFIG_REPLAY=1, no writes)\n")
+    return proc.returncode
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

package/scripts/hooks/state_io.py

@@ -40,6 +40,18 @@ except ImportError:  # pragma: no cover — Windows
 
 LOCK_BASENAME = ".dispatcher.lock"
 
+REPLAY_ENV_VAR = "AGENT_CONFIG_REPLAY"
+
+
+def is_replay_mode() -> bool:
+    """True when the caller signalled read-only fixture replay.
+
+    Concerns and the dispatcher honour the flag by skipping side
+    effects under `agents/state/` (and any other concern-owned state
+    surface). See `docs/contracts/hook-architecture-v1.md` § Replay mode.
+    """
+    return os.environ.get(REPLAY_ENV_VAR, "").strip() == "1"
+
 
 def _lock_path(state_dir: Path) -> Path:
     return state_dir / LOCK_BASENAME
@@ -52,7 +64,12 @@ def atomic_write_json(target: Path, payload: Any, *, indent: int = 2) -> None:
     directory the caller treats as the lock scope). The lock file is
     `<target.parent>/.dispatcher.lock`. Caller does not need to create
     the directory in advance — this function ensures it.
+
+    Under `AGENT_CONFIG_REPLAY=1` the call is a no-op so fixture
+    replay never mutates real session state.
     """
+    if is_replay_mode():
+        return
     target = Path(target)
     state_dir = target.parent
     state_dir.mkdir(parents=True, exist_ok=True)
@@ -63,7 +80,11 @@ def atomic_write_json(target: Path, payload: Any, *, indent: int = 2) -> None:
 def atomic_write_text(target: Path, text: str) -> None:
     """Write text to `target` atomically and concurrency-safely. Same
     locking discipline as `atomic_write_json` — useful for non-JSON
-    state payloads (chat-history transcript, status text)."""
+    state payloads (chat-history transcript, status text).
+
+    Under `AGENT_CONFIG_REPLAY=1` the call is a no-op."""
+    if is_replay_mode():
+        return
     target = Path(target)
     state_dir = target.parent
     state_dir.mkdir(parents=True, exist_ok=True)
@@ -117,6 +138,8 @@ __all__ = [
     "atomic_write_json",
     "atomic_write_text",
     "feedback_dir",
+    "is_replay_mode",
     "LOCK_BASENAME",
     "FEEDBACK_DIRNAME",
+    "REPLAY_ENV_VAR",
 ]

package/scripts/hooks_doctor.py

@@ -0,0 +1,184 @@
+#!/usr/bin/env python3
+"""Hook doctor — read-only diagnostic over the hook runtime.
+
+Wraps `scripts/hooks_status.py` (bridge presence + manifest bindings)
+and adds three diagnostics the bare status table does not surface:
+
+  * **Concerns** — every concern declared in the manifest, its
+    `fail_closed` posture, the on-disk script path, and a one-line
+    file-exists check.
+  * **Trampolines** — per-platform shell trampoline expected under
+    `scripts/hooks/<platform>-dispatcher.sh`; flags any platform that
+    has manifest bindings but no trampoline on disk.
+  * **Last feedback** — for each concern, the most-recent dispatcher
+    feedback file under `agents/state/.dispatcher/*/<concern>.json`,
+    plus the per-rule state file under `agents/state/<concern>.json`
+    when one exists.
+
+This is a **read-only** report. It never installs, modifies, or runs
+anything — same contract as `hooks_status.py`. CI uses `--strict` to
+turn missing bindings / trampolines into a non-zero exit.
+
+Schema: docs/contracts/hook-architecture-v1.md.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+sys.path.insert(0, str(REPO_ROOT / "scripts" / "hooks"))
+
+import dispatch_hook  # noqa: E402
+import hooks_status  # noqa: E402
+
+TRAMPOLINE_DIR = REPO_ROOT / "scripts" / "hooks"
+STATE_DIR_DEFAULT = "agents/state"
+
+# Platforms whose bridge file (settings.json) invokes the universal
+# dispatcher directly — no shell trampoline required. Excluded from the
+# "missing trampoline" check.
+NATIVE_DISPATCH_PLATFORMS = frozenset({"claude"})
+
+
+def _trampoline_for(platform: str) -> Path:
+    return TRAMPOLINE_DIR / f"{platform}-dispatcher.sh"
+
+
+def _concern_state_file(state_dir: Path, concern: str) -> Path | None:
+    target = state_dir / f"{concern}.json"
+    return target if target.is_file() else None
+
+
+def _latest_feedback(state_dir: Path, concern: str) -> Path | None:
+    """Return the most-recent dispatcher feedback file for the concern,
+    walking `agents/state/.dispatcher/<session>/<concern>.json`."""
+    dispatcher_dir = state_dir / ".dispatcher"
+    if not dispatcher_dir.is_dir():
+        return None
+    candidates = sorted(
+        dispatcher_dir.glob(f"*/{concern}.json"),
+        key=lambda p: p.stat().st_mtime,
+        reverse=True,
+    )
+    return candidates[0] if candidates else None
+
+
+def _rel(path: Path | None, root: Path) -> str | None:
+    if path is None:
+        return None
+    try:
+        return str(path.resolve().relative_to(root.resolve()))
+    except ValueError:
+        return str(path)
+
+
+def collect(project_root: Path, manifest: dict,
+            state_dir_rel: str = STATE_DIR_DEFAULT) -> dict:
+    """Build the doctor payload — JSON-serialisable."""
+    matrix = hooks_status.collect(project_root, manifest)
+    state_dir = project_root / state_dir_rel
+
+    concerns_def = manifest.get("concerns") or {}
+    concerns: list[dict] = []
+    for name, spec in sorted(concerns_def.items()):
+        script_rel = (spec or {}).get("script") or ""
+        script_path = REPO_ROOT / script_rel if script_rel else None
+        state_file = _concern_state_file(state_dir, name)
+        last_feedback = _latest_feedback(state_dir, name)
+        concerns.append({
+            "concern": name,
+            "fail_closed": bool((spec or {}).get("fail_closed", False)),
+            "script": script_rel or None,
+            "script_present": bool(script_path and script_path.is_file()),
+            "state_file": _rel(state_file, project_root),
+            "last_feedback": _rel(last_feedback, project_root),
+        })
+
+    trampolines: list[dict] = []
+    for row in matrix["platforms"]:
+        platform = row["platform"]
+        needs_trampoline = bool(row["bindings"]) and platform not in NATIVE_DISPATCH_PLATFORMS
+        tpath = _trampoline_for(platform)
+        trampolines.append({
+            "platform": platform,
+            "expected": _rel(tpath, REPO_ROOT),
+            "present": tpath.is_file(),
+            "required": needs_trampoline,
+            "missing": needs_trampoline and not tpath.is_file(),
+        })
+
+    return {
+        "schema_version": 1,
+        "platforms": matrix["platforms"],
+        "concerns": concerns,
+        "trampolines": trampolines,
+    }
+
+
+def _render_table(payload: dict) -> str:
+    lines: list[str] = [hooks_status._render_table(payload), ""]
+    lines.append("Concerns")
+    lines.append("-" * 60)
+    for c in payload["concerns"]:
+        posture = "fail-closed" if c["fail_closed"] else "fail-open"
+        script_mark = "✅ " if c["script_present"] else "❌ "
+        lines.append(f"{script_mark}{c['concern']:<22} {posture:<11} {c['script'] or '(no script)'}")
+        if c["state_file"]:
+            lines.append(f"    state:    {c['state_file']}")
+        if c["last_feedback"]:
+            lines.append(f"    feedback: {c['last_feedback']}")
+    lines.append("")
+    lines.append("Trampolines")
+    lines.append("-" * 60)
+    for t in payload["trampolines"]:
+        marker = "❌ " if t["missing"] else ("·  " if not t["required"] else "✅ ")
+        suffix = "" if t["required"] else "  (not required)"
+        lines.append(f"{marker}{t['platform']:<9} {t['expected']}{suffix}")
+    return "\n".join(lines)
+
+
+def _final_exit_code(payload: dict, strict: bool) -> int:
+    if not strict:
+        return 0
+    rc = hooks_status._final_exit_code(payload, strict)
+    if rc:
+        return rc
+    if any(t["missing"] for t in payload["trampolines"]):
+        return 1
+    if any(not c["script_present"] for c in payload["concerns"]):
+        return 1
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--format", choices=["table", "json"], default="table")
+    parser.add_argument("--project-root", default=".",
+                        help="Project root to inspect (default: cwd)")
+    parser.add_argument("--manifest", default=str(dispatch_hook.MANIFEST_PATH))
+    parser.add_argument("--strict", action="store_true",
+                        help="Exit non-zero on missing bridges, trampolines, "
+                             "or concern scripts (CI-friendly).")
+    args = parser.parse_args(argv)
+
+    manifest_path = Path(args.manifest)
+    if not manifest_path.exists():
+        sys.stderr.write(f"hooks_doctor: manifest missing at {manifest_path}\n")
+        return 2
+    manifest = dispatch_hook._load_yaml(manifest_path)
+    project_root = Path(args.project_root).resolve()
+    payload = collect(project_root, manifest)
+
+    if args.format == "json":
+        print(json.dumps(payload, indent=2, sort_keys=True))
+    else:
+        print(_render_table(payload))
+    return _final_exit_code(payload, args.strict)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/lint_hook_concern_budget.py

@@ -0,0 +1,203 @@
+#!/usr/bin/env python3
+"""Lint the hook concern budget against `scripts/hook_manifest.yaml`.
+
+P3.3 of `agents/roadmaps/road-to-proof-not-features.md`. Static gate
+that mirrors the always-rule budget pattern:
+
+- **max concerns per (platform, event)** — warns when any cell exceeds
+  the configured threshold. Default threshold is a placeholder sourced
+  from `current-max × 1.5, rounded up` until Phase 1 captures real
+  decision-trace evidence (`max(observed-in-Phase-1) × 1.5`).
+- **fail-closed only for declared Tier-1 concerns** — errors when a
+  concern carries `fail_closed: true` without being listed in
+  `hooks.concern_budget.tier1_concerns`.
+
+Out of scope for the static gate: **max execution time per concern**.
+That signal lives in runtime decision-trace logs (Phase 2) and is
+checked by a separate runtime probe once Phase 1 sessions produce
+data — tracked as a P3.3 follow-up, not blocking this gate.
+
+Defaults (override in `.agent-settings.yml`):
+
+    hooks:
+      concern_budget:
+        max_per_event: 8
+        tier1_concerns: []
+        hard_fail: false
+
+Exit codes (warn-only mode, the default):
+
+    0 — clean, OR violations exist but `hard_fail` is false
+    1 — schema load failed (file absent / malformed)
+    2 — `hard_fail: true` and at least one violation
+
+Hard-fail mode is gated on Phase 1 evidence (≥10 captured sessions per
+the roadmap exit criterion).
+
+Invocation:
+
+    python3 scripts/lint_hook_concern_budget.py [--manifest PATH]
+                                                [--settings PATH]
+                                                [--strict]
+
+`--strict` upgrades warn-only to hard-fail regardless of settings — for
+CI lanes that want to surface the gate on every PR.
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+DEFAULT_MANIFEST = REPO_ROOT / "scripts" / "hook_manifest.yaml"
+DEFAULT_SETTINGS = REPO_ROOT / ".agent-settings.yml"
+
+DEFAULT_MAX_PER_EVENT = 8
+DEFAULT_TIER1: list[str] = []
+DEFAULT_HARD_FAIL = False
+
+
+def _load_manifest(path: Path) -> dict:
+    sys.path.insert(0, str(REPO_ROOT / "scripts"))
+    from hooks.dispatch_hook import _load_yaml  # noqa: E402
+    return _load_yaml(path)
+
+
+def _read_settings_block(settings_path: Path) -> dict:
+    """Minimal YAML walk for `hooks.concern_budget.*`. Mirrors the
+    pattern used by `scripts/minimal_safe_diff_hook.py` — no PyYAML
+    dependency, tolerant of missing keys / blocks."""
+    out: dict = {}
+    if not settings_path.is_file():
+        return out
+    in_hooks = False
+    in_budget = False
+    in_tier1 = False
+    try:
+        text = settings_path.read_text(encoding="utf-8")
+    except OSError:
+        return out
+    for raw in text.splitlines():
+        line = raw.rstrip()
+        if re.match(r"^hooks\s*:\s*(?:#.*)?$", line):
+            in_hooks, in_budget, in_tier1 = True, False, False
+            continue
+        if in_hooks and re.match(r"^\S", line):
+            in_hooks = in_budget = in_tier1 = False
+        if in_hooks and re.match(r"^\s{2}concern_budget\s*:\s*(?:#.*)?$", line):
+            in_budget, in_tier1 = True, False
+            continue
+        if in_budget and re.match(r"^\s{2}\S", line):
+            in_budget = in_tier1 = False
+        if in_budget:
+            m = re.match(r"^\s{4}max_per_event\s*:\s*(\d+)", line)
+            if m:
+                out["max_per_event"] = int(m.group(1))
+                in_tier1 = False
+                continue
+            m = re.match(r"^\s{4}hard_fail\s*:\s*(true|false)", line)
+            if m:
+                out["hard_fail"] = m.group(1) == "true"
+                in_tier1 = False
+                continue
+            if re.match(r"^\s{4}tier1_concerns\s*:\s*\[\s*\]", line):
+                out["tier1_concerns"] = []
+                in_tier1 = False
+                continue
+            if re.match(r"^\s{4}tier1_concerns\s*:\s*(?:#.*)?$", line):
+                out.setdefault("tier1_concerns", [])
+                in_tier1 = True
+                continue
+            if in_tier1:
+                m = re.match(r"^\s{6}-\s*([A-Za-z0-9_\-]+)", line)
+                if m:
+                    out.setdefault("tier1_concerns", []).append(m.group(1))
+    return out
+
+
+def _check_concern_counts(manifest: dict, max_per_event: int,
+                          warnings: list[str]) -> None:
+    platforms = manifest.get("platforms") or {}
+    if not isinstance(platforms, dict):
+        return
+    for plat, block in platforms.items():
+        if not isinstance(block, dict) or block.get("fallback_only"):
+            continue
+        for event, names in block.items():
+            if not isinstance(names, list):
+                continue
+            count = len(names)
+            if count > max_per_event:
+                warnings.append(
+                    f"platforms.{plat}.{event}: {count} concerns "
+                    f"(threshold {max_per_event}). Trim or raise "
+                    "hooks.concern_budget.max_per_event in .agent-settings.yml."
+                )
+
+
+def _check_fail_closed_tier(manifest: dict, tier1: list[str],
+                            errors: list[str]) -> None:
+    concerns = manifest.get("concerns") or {}
+    if not isinstance(concerns, dict):
+        return
+    allowed = set(tier1)
+    for name, spec in concerns.items():
+        if not isinstance(spec, dict):
+            continue
+        if spec.get("fail_closed") is True and name not in allowed:
+            errors.append(
+                f"concerns.{name}: fail_closed=true but not declared in "
+                "hooks.concern_budget.tier1_concerns. Promotion to Tier-1 "
+                "is explicit opt-in (Phase 1 evidence required)."
+            )
+
+
+def lint(manifest_path: Path, settings_path: Path, *,
+         strict: bool = False) -> int:
+    if not manifest_path.is_file():
+        sys.stderr.write(f"lint_hook_concern_budget: file not found: "
+                         f"{manifest_path}\n")
+        return 1
+    try:
+        manifest = _load_manifest(manifest_path)
+    except Exception as exc:  # pragma: no cover
+        sys.stderr.write(f"lint_hook_concern_budget: load error: {exc}\n")
+        return 1
+    if not isinstance(manifest, dict):
+        sys.stderr.write("lint_hook_concern_budget: manifest is not a mapping\n")
+        return 1
+
+    settings = _read_settings_block(settings_path)
+    max_per_event = settings.get("max_per_event", DEFAULT_MAX_PER_EVENT)
+    tier1 = settings.get("tier1_concerns", DEFAULT_TIER1)
+    hard_fail = settings.get("hard_fail", DEFAULT_HARD_FAIL) or strict
+
+    warnings: list[str] = []
+    errors: list[str] = []
+    _check_concern_counts(manifest, max_per_event, warnings)
+    _check_fail_closed_tier(manifest, tier1, errors)
+
+    for w in warnings:
+        sys.stderr.write(f"warn: {w}\n")
+    for e in errors:
+        sys.stderr.write(f"error: {e}\n")
+
+    if hard_fail and (warnings or errors):
+        return 2
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--manifest", type=Path, default=DEFAULT_MANIFEST)
+    parser.add_argument("--settings", type=Path, default=DEFAULT_SETTINGS)
+    parser.add_argument("--strict", action="store_true",
+                        help="upgrade warn-only to hard-fail")
+    args = parser.parse_args(argv)
+    return lint(args.manifest, args.settings, strict=args.strict)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/roadmap_progress_hook.py

@@ -26,10 +26,13 @@ from __future__ import annotations
 
 import argparse
 import json
+import os
 import subprocess
 import sys
 from pathlib import Path
 
+REPLAY_ENV_VAR = "AGENT_CONFIG_REPLAY"
+
 # 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
@@ -134,6 +137,14 @@ def run(stdin_text: str, *, consumer_root: Path, verbose: bool = False) -> int:
                   file=sys.stderr)
         return 0
 
+    # Replay mode (`AGENT_CONFIG_REPLAY=1`) skips the regenerator subprocess
+    # so fixture dispatches never rewrite agents/roadmaps-progress.md.
+    if os.environ.get(REPLAY_ENV_VAR, "").strip() == "1":
+        if verbose:
+            print("roadmap-progress-hook: replay mode, skipping regenerator",
+                  file=sys.stderr)
+        return 0
+
     try:
         subprocess.run(
             [sys.executable, str(script)],