@event4u/agent-config 2.8.0 → 2.10.0

package/scripts/_cli/cmd_settings_check.py

@@ -0,0 +1,171 @@
+"""``agent-config settings:check`` — validate ``.agent-settings.yml`` against the supported YAML subset.
+
+Read-only. Implements P3.2 of road-to-proof-not-features.md. The contract
+this checks against is pinned in
+``docs/contracts/settings-sync-yaml-subset.md``; out-of-subset constructs
+cause :class:`sync_yaml_rt` to raise ``ValueError`` during a sync. This
+CLI surfaces the same findings *before* a sync runs, so users can fix
+their file without watching the merge fail.
+
+Output line format::
+
+    line:N  <kind>  <verdict>  <fix hint>
+
+Exit codes:
+
+* ``0`` — file is inside the supported subset (or absent and ``--allow-missing``).
+* ``1`` — one or more findings (verdict ``not supported``).
+* ``2`` — file absent (without ``--allow-missing``) or unreadable.
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+# Imported lazily inside ``main`` so a missing engine cannot break ``--help``.
+
+DEFAULT_PATH = ".agent-settings.yml"
+
+# Out-of-subset patterns detected by a line-level pre-scan. Each rule is
+# (label, regex, fix hint). The regex is applied to the *stripped* body
+# of each non-comment line so leading indent does not affect matching.
+_PRESCAN_RULES: tuple[tuple[str, re.Pattern[str], str], ...] = (
+    (
+        "multi-doc separator",
+        re.compile(r"^(---|\.\.\.)\s*(#.*)?$"),
+        "remove the separator — one YAML document per file only.",
+    ),
+    (
+        "complex key",
+        re.compile(r"^\?\s"),
+        "rewrite as a plain ``key: value`` mapping line.",
+    ),
+    (
+        "block-scalar indicator",
+        re.compile(r":\s*[|>][+-]?\s*(#.*)?$"),
+        "inline the value as a single-line quoted scalar.",
+    ),
+    (
+        "tagged scalar",
+        re.compile(r":\s*!!?[A-Za-z_]"),
+        "remove the ``!tag``; the parser does not honour it.",
+    ),
+    (
+        "anchor / alias",
+        re.compile(r":\s*[&*][A-Za-z_]"),
+        "expand the anchor inline — anchors / aliases are not supported.",
+    ),
+    (
+        "nested flow-mapping",
+        re.compile(r":\s*\{[^}]*:[^}]*\}"),
+        "rewrite as a block-style nested mapping (indented child keys).",
+    ),
+)
+
+
+def _scan_line(stripped: str) -> tuple[str, str] | None:
+    if not stripped or stripped.startswith("#"):
+        return None
+    for label, pattern, hint in _PRESCAN_RULES:
+        if pattern.search(stripped):
+            return label, hint
+    return None
+
+
+def _scan_text(text: str) -> list[dict]:
+    findings: list[dict] = []
+    for lineno, raw in enumerate(text.splitlines(), 1):
+        stripped = raw.strip()
+        if "\t" in raw[: len(raw) - len(raw.lstrip(" \t"))]:
+            findings.append({
+                "line": lineno,
+                "kind": "tab in indent",
+                "verdict": "not supported",
+                "hint": "replace leading tabs with 2 or 4 spaces.",
+            })
+            continue
+        hit = _scan_line(stripped)
+        if hit is not None:
+            label, hint = hit
+            findings.append({
+                "line": lineno,
+                "kind": label,
+                "verdict": "not supported",
+                "hint": hint,
+            })
+    return findings
+
+
+def _format(finding: dict) -> str:
+    return (
+        f"  ❌  line:{finding['line']:<4}  "
+        f"{finding['kind']:<22}  {finding['verdict']:<14}  {finding['hint']}"
+    )
+
+
+def _parse(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="agent-config settings:check",
+        description=(
+            "Validate .agent-settings.yml against the supported YAML subset "
+            "(docs/contracts/settings-sync-yaml-subset.md). Read-only."
+        ),
+    )
+    parser.add_argument("--path", default=DEFAULT_PATH,
+                        help=f"target settings file (default: ./{DEFAULT_PATH})")
+    parser.add_argument("--allow-missing", action="store_true",
+                        help="exit 0 when the file is absent (CI-friendly)")
+    parser.add_argument("--quiet", action="store_true",
+                        help="suppress non-essential output")
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str]) -> int:
+    opts = _parse(argv)
+    target = Path(opts.path)
+    if not target.is_file():
+        if opts.allow_missing:
+            if not opts.quiet:
+                print(f"✅  {target}: file absent (allow-missing).")
+            return 0
+        print(f"❌  {target}: file not found.", file=sys.stderr)
+        print("    Run `./agent-config sync-agent-settings` to create it.", file=sys.stderr)
+        return 2
+    try:
+        text = target.read_text(encoding="utf-8")
+    except OSError as exc:
+        print(f"❌  {target}: cannot read: {exc}", file=sys.stderr)
+        return 2
+
+    findings = _scan_text(text)
+    if not findings:
+        # Final gate: run the round-trip parser to catch anything the
+        # pre-scan missed (mismatched indent, malformed mapping lines).
+        from scripts import sync_yaml_rt as _rt  # noqa: PLC0415
+        try:
+            _rt.parse(text)
+        except ValueError as exc:
+            findings.append({
+                "line": 0, "kind": "parser",
+                "verdict": "not supported", "hint": str(exc),
+            })
+
+    if not findings:
+        if not opts.quiet:
+            print(f"✅  {target}: inside the supported subset "
+                  "(docs/contracts/settings-sync-yaml-subset.md).")
+        return 0
+    print(f"❌  {target}: {len(findings)} finding(s) outside the supported subset.",
+          file=sys.stderr)
+    for finding in findings:
+        print(_format(finding), file=sys.stderr)
+    print("", file=sys.stderr)
+    print("    Contract: docs/contracts/settings-sync-yaml-subset.md",
+          file=sys.stderr)
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/scripts/_cli/cmd_validate.py

@@ -130,6 +130,7 @@ def main(argv: list[str]) -> int:
     if data is None:
         _emit(opts.quiet, f"❌  No manifest found at {manifest}")
         _emit(opts.quiet, "    Run `./agent-config init --tools=<id>` to create one.")
+        _emit(opts.quiet, "    Diagnose: `./agent-config doctor --check manifest-integrity`")
         return 1
 
     entries = list(data.get("tools") or [])
@@ -157,6 +158,15 @@ def main(argv: list[str]) -> int:
     _emit(opts.quiet, "")
     _emit(opts.quiet, "Run `./agent-config sync` to replay missing bridges, or")
     _emit(opts.quiet, "`./agent-config init --tools=<id> --force` to refresh the manifest.")
+    # Deeplink: route per-kind to the matching `doctor` check so users can
+    # copy-paste even though `doctor` is Tier-1 and absent from --help.
+    kinds = {issue["kind"] for issue in issues}
+    if "version_drift" in kinds:
+        _emit(opts.quiet, "Diagnose:  `./agent-config doctor --check lockfile-freshness`")
+    if kinds & {"marker_missing", "scope_divergence"}:
+        _emit(opts.quiet, "Diagnose:  `./agent-config doctor --check bridge-drift`")
+    if "manifest_corrupt" in kinds:
+        _emit(opts.quiet, "Diagnose:  `./agent-config doctor --check manifest-integrity`")
     return 1
 
 

package/scripts/agent-config

@@ -62,17 +62,6 @@ Tier 0 — daily-driver (init → sync → validate → work):
                              (Option-A loop; called by the /work command)
   implement-ticket           Drive the work_engine Python engine on a ticket envelope
                              (Option-A loop; called by the /implement-ticket command)
-  first-run                  Guided first-run setup — cost profile, settings, tooling
-  keys:install-anthropic     Install the Anthropic API key for the AI Council
-                             (interactive, /dev/tty only, writes ~/.config/agent-config/anthropic.key 0600)
-  keys:install-openai        Install the OpenAI API key for the AI Council
-                             (interactive, /dev/tty only, writes ~/.config/agent-config/openai.key 0600)
-  council:estimate           Pre-call council cost preview (no API call, no spend)
-                             Usage: council:estimate <question> [--input-mode prompt|roadmap]
-  council:run                Run the council. Requires --confirm to spend.
-                             Usage: council:run <question> --output <path> --confirm
-  council:render             Re-render a saved council responses JSON to markdown
-                             Usage: council:render <responses.json>
   help                       Show this help (default Tier-0; --tier=1|all expands)
   --version, -V              Print package version
 EOF
@@ -110,6 +99,17 @@ Tier 1 — power-user (release shape, audit, migration):
                              Flags: --json | --project=<path>
   migrate                    One-shot migration off legacy composer / npm install paths
                              Flags: --dry-run (detect only)
+  first-run                  Guided first-run setup — cost profile, settings, tooling
+  keys:install-anthropic     Install the Anthropic API key for the AI Council
+                             (interactive, /dev/tty only, writes ~/.config/agent-config/anthropic.key 0600)
+  keys:install-openai        Install the OpenAI API key for the AI Council
+                             (interactive, /dev/tty only, writes ~/.config/agent-config/openai.key 0600)
+  council:estimate           Pre-call council cost preview (no API call, no spend)
+                             Usage: council:estimate <question> [--input-mode prompt|roadmap]
+  council:run                Run the council. Requires --confirm to spend.
+                             Usage: council:run <question> --output <path> --confirm
+  council:render             Re-render a saved council responses JSON to markdown
+                             Usage: council:render <responses.json>
 EOF
   fi
 
@@ -124,12 +124,25 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
                              (one-line MCP server onboarding; idempotent)
   mcp:run                    Run the built-in MCP server over stdio
                              (requires `mcp:setup` first; see docs/mcp-server.md)
+                             (experimental — beta gates: docs/contracts/mcp-beta-criteria.md)
   roadmap:progress           Regenerate agents/roadmaps-progress.md from open roadmaps
   roadmap:progress-check     Fail if agents/roadmaps-progress.md is stale (for CI)
+  settings:check             Validate .agent-settings.yml against the YAML-subset contract
+                             (docs/contracts/settings-sync-yaml-subset.md). Read-only.
+                             Exit 0 clean, 1 finding(s), 2 file absent / unreadable.
   hooks:install              Install the pre-commit roadmap-progress hook
                              (use --print to dump it, --force to overwrite an existing hook)
   hooks:status               Print the runtime hook matrix (per-platform install + bindings)
                              Flags: --format json|table, --strict (CI), --project-root <path>
+  hooks:doctor               Diagnose hook health: concerns + fail-open/closed posture,
+                             last dispatcher feedback per concern, missing trampolines.
+                             Wraps hooks:status. Read-only.
+                             Flags: --format json|table, --strict (CI), --project-root <path>
+  hooks:replay               Replay a fixture through the universal dispatcher with
+                             AGENT_CONFIG_REPLAY=1 (no writes under agents/state/).
+                             Usage: hooks:replay --platform <name> --event <event>
+                                    --payload <path|event-name> [--native-event <native>]
+                                    [--manifest <path>] [--json] [--dry-run]
   migrate-state              Migrate a legacy .implement-ticket-state.json file
                              to the v1 .work-state.json schema (preserves .bak)
   memory:lookup              Retrieve memory entries (text or JSON envelope)
@@ -161,7 +174,7 @@ EOF
   if [[ "$tier" == "0" ]]; then
     cat <<'EOF'
 
-(Hidden: 9 Tier-1 + 26 Tier-2 commands. Run `./agent-config --help --tier=1`
+(Hidden: 15 Tier-1 + 26 Tier-2 commands. Run `./agent-config --help --tier=1`
 or `--tier=all` to see them. Tier criteria: docs/contracts/command-surface-tiers.md.)
 EOF
   fi
@@ -173,14 +186,8 @@ Examples (Tier 0):
   ./agent-config sync --dry-run
   ./agent-config sync
   ./agent-config validate
-  ./agent-config first-run
   ./agent-config work --state-file .work-state.json --prompt-file prompt.txt
   ./agent-config implement-ticket --state-file .work-state.json
-  ./agent-config keys:install-anthropic
-  ./agent-config keys:install-openai
-  ./agent-config council:estimate prompt.txt
-  ./agent-config council:run prompt.txt --output agents/council-sessions/out.json --confirm
-  ./agent-config council:render agents/council-sessions/out.json
 EOF
 
   if [[ "$tier" == "1" || "$tier" == "all" ]]; then
@@ -203,6 +210,12 @@ Examples (Tier 1):
   ./agent-config versions --json
   ./agent-config init --offline --tools=claude-code,cursor --yes
   ./agent-config update --offline --to=2.2.0
+  ./agent-config first-run
+  ./agent-config keys:install-anthropic
+  ./agent-config keys:install-openai
+  ./agent-config council:estimate prompt.txt
+  ./agent-config council:run prompt.txt --output agents/council-sessions/out.json --confirm
+  ./agent-config council:render agents/council-sessions/out.json
 EOF
   fi
 
@@ -216,7 +229,9 @@ Examples (Tier 2):
   ./agent-config mcp:setup
   ./agent-config mcp:run
   ./agent-config roadmap:progress
+  ./agent-config settings:check
   ./agent-config hooks:install
+  ./agent-config hooks:replay --platform augment --event post_tool_use --payload post_tool_use --json
   ./agent-config migrate-state
   ./agent-config memory:lookup --types domain-invariants --key billing
   ./agent-config memory:signal --type architecture-decision --path src/Foo.php --body "…"
@@ -506,6 +521,20 @@ cmd_hooks_status() {
   exec python3 "$script" "$@"
 }
 
+cmd_hooks_doctor() {
+  require_python3
+  local script
+  script="$(resolve_script "scripts/hooks_doctor.py")" || return 1
+  exec python3 "$script" "$@"
+}
+
+cmd_hooks_replay() {
+  require_python3
+  local script
+  script="$(resolve_script "scripts/hooks/replay_hook.py")" || return 1
+  exec python3 "$script" "$@"
+}
+
 cmd_chat_history_checkpoint() {
   require_python3
   local script
@@ -675,6 +704,15 @@ cmd_validate() {
   exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_validate "$@"
 }
 
+# `agent-config settings:check` — read-only YAML-subset validator for
+# `.agent-settings.yml` (P3.2 of road-to-proof-not-features.md). Contract
+# pinned in docs/contracts/settings-sync-yaml-subset.md. Exit 0 clean,
+# 1 finding(s), 2 file absent / unreadable.
+cmd_settings_check() {
+  require_python3
+  exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_settings_check "$@"
+}
+
 # `agent-config uninstall` — remove bridge markers (project) or lockfile
 # entries (global). Idempotent. Pass `--purge` to also delete deployed
 # content directories under user-scope anchors (destructive). See
@@ -743,6 +781,8 @@ main() {
     context-hygiene:hook)    cmd_context_hygiene_hook "$@" ;;
     dispatch:hook)           cmd_dispatch_hook "$@" ;;
     hooks:status)            cmd_hooks_status "$@" ;;
+    hooks:doctor)            cmd_hooks_doctor "$@" ;;
+    hooks:replay)            cmd_hooks_replay "$@" ;;
     telemetry:record)        cmd_telemetry_record "$@" ;;
     telemetry:status)        cmd_telemetry_status "$@" ;;
     telemetry:report)        cmd_telemetry_report "$@" ;;
@@ -756,6 +796,7 @@ main() {
     export)                  cmd_export "$@" ;;
     sync)                    cmd_sync "$@" ;;
     validate)                cmd_validate "$@" ;;
+    settings:check)          cmd_settings_check "$@" ;;
     uninstall)               cmd_uninstall "$@" ;;
     prune)                   cmd_prune "$@" ;;
     doctor)                  cmd_doctor "$@" ;;

package/scripts/chat_history.py

@@ -48,6 +48,15 @@ SCHEMA_VERSION = 4
 DEFAULT_MAX_SESSIONS = 5
 VALID_FREQS = {"per_turn", "per_phase", "per_tool"}
 VALID_OVERFLOW = {"rotate", "compress"}
+
+# Replay-mode signal — when set, every write to the on-disk transcript
+# is a no-op. Honoured per `docs/contracts/hook-architecture-v1.md`
+# § Replay mode so fixture dispatches never mutate real session state.
+REPLAY_ENV_VAR = "AGENT_CONFIG_REPLAY"
+
+
+def _is_replay_mode() -> bool:
+    return os.environ.get(REPLAY_ENV_VAR, "").strip() == "1"
 _WS_RE = re.compile(r"\s+")
 SESSION_ID_LEN = 16
 SESSION_ID_UNKNOWN = "<unknown>"
@@ -247,6 +256,8 @@ def init(freq: str = "per_phase", *,
         raise ValueError(f"freq must be one of {sorted(VALID_FREQS)}")
     p = path or file_path()
     header = _build_header(freq)
+    if _is_replay_mode():
+        return header
     p.parent.mkdir(parents=True, exist_ok=True)
     with p.open("w", encoding="utf-8") as fh:
         fh.write(json.dumps(header, ensure_ascii=False) + "\n")
@@ -318,6 +329,8 @@ def append(entry: dict[str, Any], *, path: Path | None = None,
         entry["s"] = session
     elif "s" not in entry and _session_tag_enabled():
         entry["s"] = _last_body_session_id(p)
+    if _is_replay_mode():
+        return
     with p.open("a", encoding="utf-8") as fh:
         fh.write(json.dumps(entry, ensure_ascii=False) + "\n")
 
@@ -328,7 +341,11 @@ def _atomic_write_text(p: Path, text: str) -> None:
     Multiple processes writing to the same target use disjoint tmp paths
     (PID + uuid), so concurrent writes no longer collide on a shared
     ``.tmp`` file. The final ``replace`` is atomic on POSIX.
+
+    Under `AGENT_CONFIG_REPLAY=1` the call is a no-op.
     """
+    if _is_replay_mode():
+        return
     tmp = p.with_suffix(
         f"{p.suffix}.{os.getpid()}.{uuid.uuid4().hex[:8]}.tmp",
     )
@@ -405,6 +422,8 @@ def prepend_entries(entries: list[dict[str, Any]], *,
 
 
 def clear(*, path: Path | None = None) -> None:
+    if _is_replay_mode():
+        return
     p = path or file_path()
     if p.exists():
         p.unlink()

package/scripts/check_council_references.py

@@ -14,8 +14,10 @@ council files. Directory mentions and placeholder paths
 output-path convention, not a live reference.
 
 Forbidden hits in this codebase exist today (kernel-membership ADRs
-cite real session JSONs as decision traces). Suppress them with an
-inline pragma at the end of the line:
+cite real session JSONs as decision traces). Two source/target shapes
+are exempt structurally — see STRUCTURAL_CARVEOUTS below — because
+they encode immutable decision provenance, not transient drafting
+state. Anything else needs an inline pragma at the end of the line:
 
     `agents/council-sessions/...json` <!-- council-ref-allowed: <reason> -->
 
@@ -82,6 +84,31 @@ ALLOWLIST_FILES: frozenset[str] = frozenset({
 
 INLINE_PRAGMA = re.compile(r"<!--\s*council-ref-allowed:[^>]*-->")
 
+# Structural carve-outs — (source_pattern, target_pattern) pairs where
+# the reference is immutable decision provenance rather than transient
+# drafting state. Driven by the 2026-05-14 P3.4 council round
+# (agents/council-sessions/2026-05-14-p3-4-references/synthesis.md).
+#
+# Each entry: source file matches `source` regex AND the captured
+# reference path matches `target` regex → reference is allowed without
+# an inline pragma.
+STRUCTURAL_CARVEOUTS: tuple[tuple[re.Pattern[str], re.Pattern[str]], ...] = (
+    # (a) evaluation-context → council-question:
+    # the question file is a frozen function-parameter / spend-gate
+    # input, not a documentation link.
+    (
+        re.compile(r"^agents/contexts/evaluation-[^/]+\.md$"),
+        re.compile(r"^agents/council-questions/[^/]+\.md$"),
+    ),
+    # (b) contract → council-session-synthesis:
+    # the synthesis file is the audit-trail receipt the contract cites
+    # as decision provenance; the contract inlines the decision body.
+    (
+        re.compile(r"^docs/contracts/[^/]+\.md$"),
+        re.compile(r"^agents/council-sessions/[^/]+/synthesis\.md$"),
+    ),
+)
+
 
 def _is_allowlisted(rel: str) -> bool:
     if rel in ALLOWLIST_FILES:
@@ -89,8 +116,17 @@ def _is_allowlisted(rel: str) -> bool:
     return any(rel.startswith(prefix) for prefix in ALLOWLIST_PREFIXES)
 
 
+def _is_structurally_allowed(source_rel: str, target_capture: str) -> bool:
+    """True when (source, target) matches a structural carve-out pair."""
+    for src_re, tgt_re in STRUCTURAL_CARVEOUTS:
+        if src_re.match(source_rel) and tgt_re.match(target_capture):
+            return True
+    return False
+
+
 def _scan_file(path: Path) -> list[tuple[int, str]]:
     findings: list[tuple[int, str]] = []
+    rel = path.as_posix()
     try:
         text = path.read_text(encoding="utf-8")
     except (OSError, UnicodeDecodeError):
@@ -99,6 +135,8 @@ def _scan_file(path: Path) -> list[tuple[int, str]]:
         if INLINE_PRAGMA.search(line):
             continue
         for m in PATTERN.finditer(line):
+            if _is_structurally_allowed(rel, m.group(0)):
+                continue
             findings.append((ln, m.group(0)))
     return findings
 
@@ -136,10 +174,13 @@ def main() -> int:
     print(
         "\nRule: .agent-src/rules/no-roadmap-references.md (council clause)\n"
         "Fix: inline the convergence summary (members + date) instead of\n"
-        "linking the file. Append "
+        "linking the file. Two source/target shapes are exempt structurally\n"
+        "(evaluation-context → council-question, contract →\n"
+        "council-session-synthesis) — see STRUCTURAL_CARVEOUTS in this\n"
+        "script. Otherwise append "
         "<!-- council-ref-allowed: <reason> --> on the same line to\n"
-        "suppress when the reference is genuinely required (ADR / contract\n"
-        "decision trace)."
+        "suppress when the reference is genuinely required (ADR decision\n"
+        "trace)."
     )
     return 1
 

package/scripts/hooks/dispatch_hook.py

@@ -37,7 +37,7 @@ MANIFEST_PATH = REPO_ROOT / "scripts" / "hook_manifest.yaml"
 # Lazy import — we want this module to be importable even if the
 # hooks package state_io has changed (test isolation).
 sys.path.insert(0, str(Path(__file__).resolve().parent))
-from state_io import atomic_write_json, feedback_dir  # noqa: E402
+from state_io import atomic_write_json, feedback_dir, is_replay_mode  # noqa: E402
 
 EXIT_ALLOW = 0
 EXIT_BLOCK = 1
@@ -272,6 +272,10 @@ def _write_feedback(envelope: dict, session_id: str, entries: list[dict],
     not control flow. We only swallow IO errors here; fail-open
     matches the dispatcher's overall posture.
     """
+    # Replay mode skips feedback emission entirely so fixture replays
+    # never create per-session dirs under agents/state/.dispatcher/.
+    if is_replay_mode():
+        return
     workspace = envelope.get("workspace_root") or str(Path.cwd())
     state_root = Path(workspace) / "agents" / "state"
     fb_dir = feedback_dir(state_root, session_id)

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