@julioborges/gantry 0.1.0

package/.agents/skills/gantry/scripts/runlog.py

@@ -0,0 +1,491 @@
+#!/usr/bin/env python3
+"""Append and query the machine-local, append-only Gantry Run log."""
+from __future__ import annotations
+
+import argparse
+import datetime
+import hashlib
+import json
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+EVENTS = {
+    "run.started",
+    "run.resumed",
+    "run.cancelled",
+    "run.finished",
+    "round.started",
+    "round.finished",
+    "phase.started",
+    "phase.finished",
+    "subagent.started",
+    "subagent.stopped",
+    "compaction",
+    "hook.denied",
+    "hook.degraded",
+    "policy.changed",
+    "issue.done",
+    "issue.blocked",
+    "refutation",
+    "review.finding",
+}
+RUN_EVENTS = {"run.started", "run.resumed", "run.cancelled", "run.finished"}
+ROUND_EVENTS = {"round.started", "round.finished"}
+PHASE_EVENTS = {"phase.started", "phase.finished"}
+SUBAGENT_EVENTS = {"subagent.started", "subagent.stopped"}
+ISSUE_EVENTS = {"issue.done", "issue.blocked", "refutation", "review.finding"}
+FINISHED_EVENTS = {"run.cancelled", "run.finished"}
+UNIT_ID_RE = re.compile(r"^[0-9a-f]{12}$")
+RUN_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:-]*$")
+ISSUE_RE = re.compile(r"^[a-z0-9][a-z0-9-]*#\d{2,}$")
+PROHIBITED_KEY_TOKENS = {"command", "commands", "cmd", "diff", "diffs", "output", "outputs", "patch", "patches", "stderr", "stdout"}
+
+
+class EventError(ValueError):
+    """An event cannot safely be written to the Run log."""
+
+
+def state_root(value: str | None) -> Path:
+    return Path(value).expanduser().resolve() if value else Path.home() / ".gantry" / "state"
+
+
+def unit_id(cwd: Path) -> str:
+    """Derive the shared execution-unit identifier for a repository worktree."""
+    try:
+        common_dir = subprocess.run(
+            ["git", "rev-parse", "--git-common-dir"],
+            cwd=cwd,
+            text=True,
+            capture_output=True,
+            check=True,
+        ).stdout.strip()
+    except (OSError, subprocess.CalledProcessError) as error:
+        raise EventError(f"could not resolve Git common directory: {error}") from error
+    path = Path(common_dir)
+    real_common_dir = (cwd / path).resolve() if not path.is_absolute() else path.resolve()
+    return hashlib.sha256(str(real_common_dir).encode("utf-8")).hexdigest()[:12]
+
+
+def git_dir(cwd: Path) -> Path:
+    """The *per-worktree* git directory of `cwd` (`.git`, or `.git/worktrees/<name>`).
+
+    Unlike `unit_id`, which deliberately shares one identity across every worktree of a
+    clone, this is the one directory git itself keeps per worktree -- which is exactly the
+    keying a "current Run" marker needs, so two worktrees of one execution unit running
+    different Runs concurrently never attribute a hook denial to each other's Run.
+    """
+    try:
+        raw = subprocess.run(
+            ["git", "rev-parse", "--git-dir"],
+            cwd=cwd,
+            text=True,
+            capture_output=True,
+            check=True,
+        ).stdout.strip()
+    except (OSError, subprocess.CalledProcessError) as error:
+        raise EventError(f"could not resolve Git directory: {error}") from error
+    path = Path(raw)
+    return path.resolve() if path.is_absolute() else (cwd / path).resolve()
+
+
+def marker_path(cwd: Path) -> Path:
+    return git_dir(cwd) / "gantry" / "current-run.json"
+
+
+def write_marker(cwd: Path, run: str, state_root_value: str | None) -> Path:
+    """Record which Run is currently executing in this worktree."""
+    if not RUN_ID_RE.fullmatch(run):
+        raise EventError("run must contain only letters, numbers, dots, colons, underscores, or hyphens")
+    path = marker_path(cwd)
+    payload: dict[str, str] = {"run": run, "worktree": str(cwd.resolve())}
+    if state_root_value:
+        payload["stateRoot"] = str(state_root(state_root_value))
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, sort_keys=True) + "\n", encoding="utf-8")
+    return path
+
+
+def read_marker(cwd: Path) -> dict | None:
+    """The current-Run marker of `cwd`'s worktree, or `None` when there is none to trust."""
+    try:
+        payload = json.loads(marker_path(cwd).read_text(encoding="utf-8"))
+    except (EventError, OSError, json.JSONDecodeError):
+        return None
+    if not isinstance(payload, dict):
+        return None
+    run = payload.get("run")
+    if not isinstance(run, str) or not RUN_ID_RE.fullmatch(run):
+        return None
+    return payload
+
+
+def clear_marker(cwd: Path) -> None:
+    try:
+        marker_path(cwd).unlink(missing_ok=True)
+    except (EventError, OSError):
+        return
+
+
+def resolve_hook_run(cwd: Path) -> tuple[str | None, str | None]:
+    """Resolve (run id, state root) for a hook process, environment first, marker second.
+
+    A harness that exports `GANTRY_RUN_ID` into the hook's environment wins; otherwise the
+    Run is read from this worktree's own current-Run marker, which the round workflow writes
+    before any agent works in the worktree. This is what makes a `hook.denied` recording a
+    guarantee rather than a best-effort: a git hook inherits its environment from whatever
+    shelled out to `git`, but it always runs inside the worktree the marker describes.
+    """
+    env_state_root = os.environ.get("GANTRY_STATE_ROOT") or None
+    env_run = os.environ.get("GANTRY_RUN_ID")
+    if env_run and RUN_ID_RE.fullmatch(env_run):
+        return env_run, env_state_root
+    marker = read_marker(cwd)
+    if not marker:
+        return None, env_state_root
+    marked_root = marker.get("stateRoot")
+    return marker["run"], env_state_root or (marked_root if isinstance(marked_root, str) else None)
+
+
+def require_string(value: object, name: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise EventError(f"{name} must be a non-empty string")
+    return value
+
+
+def require_positive_integer(value: object, name: str) -> int:
+    if not isinstance(value, int) or isinstance(value, bool) or value <= 0:
+        raise EventError(f"{name} must be a positive integer")
+    return value
+
+
+def validate_timestamp(value: object) -> None:
+    timestamp = require_string(value, "ts")
+    try:
+        datetime.datetime.fromisoformat(timestamp.replace("Z", "+00:00"))
+    except ValueError as error:
+        raise EventError("ts must be an ISO 8601 timestamp") from error
+
+
+def validate_sensitive_data(value: object, path: str = "data") -> None:
+    """Reject command, output, diff, and patch fields at every nesting level."""
+    if isinstance(value, dict):
+        for key, nested in value.items():
+            if not isinstance(key, str):
+                raise EventError(f"{path} keys must be strings")
+            words = re.sub(r"([a-z0-9])([A-Z])", r"\1 \2", key)
+            tokens = re.findall(r"[a-z]+", words.lower())
+            if any(token in PROHIBITED_KEY_TOKENS for token in tokens):
+                raise EventError(f"{path}.{key} must not be stored in the Run log")
+            validate_sensitive_data(nested, f"{path}.{key}")
+    elif isinstance(value, list):
+        for index, nested in enumerate(value):
+            validate_sensitive_data(nested, f"{path}[{index}]")
+
+
+def validate_secret_checks(value: object, path: str = "data") -> None:
+    if isinstance(value, dict):
+        if value.get("secrets") is True:
+            permitted = {"secrets", "exitCode", "counts"}
+            unexpected = sorted(set(value) - permitted)
+            if unexpected:
+                raise EventError(f"{path} for a secrets check may record only exitCode and counts")
+            if "exitCode" not in value or "counts" not in value:
+                raise EventError(f"{path} for a secrets check requires exitCode and counts")
+            if not isinstance(value["exitCode"], int) or isinstance(value["exitCode"], bool):
+                raise EventError(f"{path}.exitCode must be an integer")
+            if not isinstance(value["counts"], dict):
+                raise EventError(f"{path}.counts must be an object")
+        for key, nested in value.items():
+            validate_secret_checks(nested, f"{path}.{key}")
+    elif isinstance(value, list):
+        for index, nested in enumerate(value):
+            validate_secret_checks(nested, f"{path}[{index}]")
+
+
+def validate_event(payload: object) -> dict:
+    """Validate a stable event envelope before it reaches persistent state."""
+    if not isinstance(payload, dict):
+        raise EventError("event must be a JSON object")
+    unknown = sorted(set(payload) - {"ts", "run", "event", "issue", "phase", "data"})
+    if unknown:
+        raise EventError(f"unknown event fields: {', '.join(unknown)}")
+    for field in ("ts", "run", "event"):
+        if field not in payload:
+            raise EventError(f"event is missing required field: {field}")
+    validate_timestamp(payload["ts"])
+    run = require_string(payload["run"], "run")
+    if not RUN_ID_RE.fullmatch(run):
+        raise EventError("run must contain only letters, numbers, dots, colons, underscores, or hyphens")
+    event = payload["event"]
+    if event not in EVENTS:
+        raise EventError(f"unknown event: {event!r}")
+    if "issue" in payload:
+        issue = require_string(payload["issue"], "issue")
+        if not ISSUE_RE.fullmatch(issue):
+            raise EventError("issue must be an Issue reference such as sample#01")
+    if "phase" in payload:
+        require_string(payload["phase"], "phase")
+    data = payload.get("data")
+    if data is not None and not isinstance(data, dict):
+        raise EventError("data must be an object when supplied")
+    validate_sensitive_data(data)
+    validate_secret_checks(data)
+
+    if event == "run.started":
+        if "data" not in payload:
+            raise EventError("run.started requires data")
+        for field in ("repositoryRoot", "policyHash", "tier", "staleAfterSeconds"):
+            if field not in data:
+                raise EventError(f"run.started data is missing required field: {field}")
+        require_string(data["repositoryRoot"], "data.repositoryRoot")
+        require_string(data["policyHash"], "data.policyHash")
+        require_string(data["tier"], "data.tier")
+        require_positive_integer(data["staleAfterSeconds"], "data.staleAfterSeconds")
+    elif event in ROUND_EVENTS:
+        if not isinstance(data, dict) or "round" not in data:
+            raise EventError(f"{event} requires data.round")
+        require_positive_integer(data["round"], "data.round")
+    elif event in PHASE_EVENTS:
+        if "issue" not in payload or "phase" not in payload:
+            raise EventError(f"{event} requires issue and phase")
+    elif event in SUBAGENT_EVENTS:
+        if not isinstance(data, dict) or "role" not in data:
+            raise EventError(f"{event} requires data.role")
+        require_string(data["role"], "data.role")
+    elif event == "compaction":
+        if not isinstance(data, dict) or "source" not in data:
+            raise EventError("compaction requires data.source")
+        require_string(data["source"], "data.source")
+    elif event == "hook.denied":
+        if not isinstance(data, dict) or not {"rule", "path"} <= set(data):
+            raise EventError("hook.denied requires data.rule and data.path")
+        require_string(data["rule"], "data.rule")
+        require_string(data["path"], "data.path")
+    elif event == "hook.degraded":
+        if not isinstance(data, dict) or not {"source", "missing"} <= set(data):
+            raise EventError("hook.degraded requires data.source and data.missing")
+        require_string(data["source"], "data.source")
+        missing = data["missing"]
+        if not isinstance(missing, list) or not all(isinstance(item, str) and item for item in missing):
+            raise EventError("data.missing must be a list of non-empty strings")
+        if data.get("degraded") is not True:
+            raise EventError("hook.degraded requires data.degraded to be true")
+    elif event == "policy.changed":
+        if not isinstance(data, dict) or "policyHash" not in data:
+            raise EventError("policy.changed requires data.policyHash")
+        require_string(data["policyHash"], "data.policyHash")
+    elif event in ISSUE_EVENTS and "issue" not in payload:
+        raise EventError(f"{event} requires issue")
+    return payload
+
+
+def run_log_path(root: Path, unit: str, run: str) -> Path:
+    return root / unit / "runs" / f"{run}.jsonl"
+
+
+def append_event(path: Path, payload: dict) -> None:
+    """Append a sub-64 KB JSONL event with exactly one write system call."""
+    encoded = (json.dumps(payload, separators=(",", ":"), ensure_ascii=False) + "\n").encode("utf-8")
+    if len(encoded) > 64 * 1024:
+        raise EventError("event exceeds the 64 KB atomic append limit")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    descriptor = os.open(path, os.O_APPEND | os.O_CREAT | os.O_WRONLY, 0o600)
+    try:
+        written = os.write(descriptor, encoded)
+        if written != len(encoded):
+            raise EventError("could not write a complete Run log event")
+    finally:
+        os.close(descriptor)
+
+
+def read_valid_events(path: Path) -> list[dict]:
+    events: list[dict] = []
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return events
+    for line in lines:
+        try:
+            payload = validate_event(json.loads(line))
+        except (EventError, json.JSONDecodeError):
+            continue
+        if payload["run"] != path.stem:
+            continue
+        events.append(payload)
+    return events
+
+
+def inflight(root: Path, unit: str) -> list[dict]:
+    """Derive unfinished Issue phases from valid events only."""
+    result: list[dict] = []
+    for path in sorted((root / unit / "runs").glob("*.jsonl")):
+        events = read_valid_events(path)
+        if not events or events[0]["event"] != "run.started":
+            continue
+        started = events[0]
+        active: dict[str, dict] = {}
+        finished = False
+        for event in events[1:]:
+            if event["event"] in FINISHED_EVENTS:
+                finished = True
+                continue
+            if event["event"] == "phase.started":
+                active[event["issue"]] = {
+                    "run": event["run"],
+                    "issue": event["issue"],
+                    "phase": event["phase"],
+                    "worktree": event.get("data", {}).get("worktree"),
+                }
+            elif event["event"] == "phase.finished":
+                active.pop(event["issue"], None)
+            elif event["event"] in {"issue.done", "issue.blocked"}:
+                active.pop(event["issue"], None)
+        if not finished:
+            for item in active.values():
+                if isinstance(item["worktree"], str) and item["worktree"]:
+                    result.append(
+                        {
+                            **item,
+                            "repositoryRoot": started["data"]["repositoryRoot"],
+                            "policyHash": started["data"]["policyHash"],
+                            "tier": started["data"]["tier"],
+                            "staleAfterSeconds": started["data"]["staleAfterSeconds"],
+                        }
+                    )
+    return result
+
+
+def derive_corrections_spent(events: list[dict], issue_ref: str) -> int:
+    """Apply the documented derivation rule to one Run's own valid events.
+
+    `runlog.py inflight` never reports `correctionsSpent`: it is derived here from (1) the
+    `run.resumed.data.correctionsSpent` recorded on this same Run, but only when that same
+    `run.resumed` event also names `issue_ref` as `data.issue` (0 otherwise, including when the Run
+    has no `run.resumed` event, or when its `run.resumed` names a different Issue), plus (2) the
+    number of `refutation` events for `issue_ref` that are each followed, later in the same log, by a
+    `phase.started` `Implement` event for that same Issue — i.e. only refutations whose correction
+    pass actually started count toward the spent budget. The base is per-Issue, not per-Run: a Run
+    resumed for one Issue must never lend its `correctionsSpent` base to any other Issue that also
+    happens to appear in the same Run's log.
+    """
+    resumed = next((event for event in events if event["event"] == "run.resumed"), None)
+    base = (
+        resumed["data"].get("correctionsSpent", 0)
+        if resumed and resumed["data"].get("issue") == issue_ref
+        else 0
+    )
+    started_corrections = 0
+    for index, event in enumerate(events):
+        if event["event"] != "refutation" or event.get("issue") != issue_ref:
+            continue
+        later = events[index + 1 :]
+        if any(
+            later_event["event"] == "phase.started"
+            and later_event.get("issue") == issue_ref
+            and later_event.get("phase") == "Implement"
+            for later_event in later
+        ):
+            started_corrections += 1
+    return base + started_corrections
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    unit_parser = subparsers.add_parser("unit-id", help="print the current repository execution-unit ID")
+    unit_parser.add_argument("--cwd", default=".", help="repository or worktree to inspect")
+    unit_parser.add_argument("--json", action="store_true", help="emit machine-readable output")
+    append_parser = subparsers.add_parser("append", help="append one JSON event from standard input")
+    append_parser.add_argument("unit_id", help="twelve-hex repository execution-unit ID")
+    append_parser.add_argument("run_id", nargs="?", help="optional Run ID, which must match the event")
+    append_parser.add_argument("--state-root", help="override ~/.gantry/state")
+    query_parser = subparsers.add_parser("inflight", help="list interrupted Issue phases")
+    query_parser.add_argument("unit_id", help="twelve-hex repository execution-unit ID")
+    query_parser.add_argument("--state-root", help="override ~/.gantry/state")
+    query_parser.add_argument("--json", action="store_true", help="emit machine-readable output")
+    corrections_parser = subparsers.add_parser(
+        "corrections", help="derive correctionsSpent for one Issue from one Run's own log"
+    )
+    corrections_parser.add_argument("unit_id", help="twelve-hex repository execution-unit ID")
+    corrections_parser.add_argument("run_id", help="the Run whose log to read")
+    corrections_parser.add_argument("issue", help="Issue reference such as sample#01")
+    corrections_parser.add_argument("--state-root", help="override ~/.gantry/state")
+    corrections_parser.add_argument("--json", action="store_true", help="emit machine-readable output")
+    mark_parser = subparsers.add_parser("mark", help="record which Run is executing in this worktree")
+    mark_parser.add_argument("run_id", help="the Run currently executing here")
+    mark_parser.add_argument("--cwd", default=".", help="repository or worktree to mark")
+    mark_parser.add_argument("--state-root", help="override ~/.gantry/state for hooks in this worktree")
+    current_parser = subparsers.add_parser("current", help="print the Run marked as executing in this worktree")
+    current_parser.add_argument("--cwd", default=".", help="repository or worktree to inspect")
+    current_parser.add_argument("--json", action="store_true", help="emit machine-readable output")
+    unmark_parser = subparsers.add_parser("unmark", help="remove this worktree's current-Run marker")
+    unmark_parser.add_argument("--cwd", default=".", help="repository or worktree to clear")
+    args = parser.parse_args()
+
+    try:
+        if args.command == "mark":
+            write_marker(Path(args.cwd).resolve(), args.run_id, args.state_root)
+            return 0
+        if args.command == "current":
+            marker = read_marker(Path(args.cwd).resolve())
+            if not marker:
+                return 2
+            print(json.dumps(marker, sort_keys=True) if args.json else marker["run"])
+            return 0
+        if args.command == "unmark":
+            clear_marker(Path(args.cwd).resolve())
+            return 0
+        if args.command == "unit-id":
+            value = unit_id(Path(args.cwd).resolve())
+            payload = {"unitId": value}
+            print(json.dumps(payload, sort_keys=True) if args.json else value)
+            return 0
+        if not UNIT_ID_RE.fullmatch(args.unit_id):
+            raise EventError("unit-id must be exactly twelve lowercase hexadecimal characters")
+        root = state_root(args.state_root)
+        if args.command == "append":
+            try:
+                payload = json.loads(sys.stdin.read())
+            except json.JSONDecodeError as error:
+                raise EventError(f"standard input must contain one JSON event: {error.msg}") from error
+            event = validate_event(payload)
+            if args.run_id and event["run"] != args.run_id:
+                raise EventError("positional run-id must match event.run")
+            path = run_log_path(root, args.unit_id, event["run"])
+            if path.exists() and event["event"] == "run.started":
+                raise EventError("a Run log already starts for this run-id")
+            if not path.exists() and event["event"] != "run.started":
+                raise EventError("the first event of a Run must be run.started")
+            append_event(path, event)
+            return 0
+        if args.command == "corrections":
+            if not ISSUE_RE.fullmatch(args.issue):
+                raise EventError("issue must be an Issue reference such as sample#01")
+            path = run_log_path(root, args.unit_id, args.run_id)
+            if not path.exists():
+                raise EventError(f"no Run log for {args.run_id}")
+            events = read_valid_events(path)
+            spent = derive_corrections_spent(events, args.issue)
+            payload = {
+                "unitId": args.unit_id,
+                "runId": args.run_id,
+                "issue": args.issue,
+                "correctionsSpent": spent,
+            }
+            print(json.dumps(payload, sort_keys=True) if args.json else str(spent))
+            return 0
+        payload = {"unitId": args.unit_id, "inflight": inflight(root, args.unit_id)}
+        print(json.dumps(payload, sort_keys=True) if args.json else "\n".join(
+            f"{item['run']} {item['issue']} {item['phase']} {item['worktree']}" for item in payload["inflight"]
+        ))
+        return 0
+    except EventError as error:
+        print(f"runlog error: {error}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/.agents/skills/gantry/scripts/setup.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""Conversational setup wizard for Gantry policy and hooks."""
+import argparse
+import json
+import sys
+from pathlib import Path
+
+def merge_dicts(base: dict, update: dict) -> dict:
+    for k, v in update.items():
+        if isinstance(v, dict) and k in base and isinstance(base[k], dict):
+            merge_dicts(base[k], v)
+        else:
+            base[k] = v
+    return base
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Gantry Setup config writer")
+    parser.add_argument("--config", help="JSON config string")
+    parser.add_argument("--config-file", help="Path to JSON config file")
+    args = parser.parse_args()
+
+    if args.config_file:
+        config = json.loads(Path(args.config_file).read_text(encoding="utf-8"))
+    elif args.config:
+        config = json.loads(args.config)
+    else:
+        print("Error: No config provided", file=sys.stderr)
+        sys.exit(2)
+
+    print("Proposed .gantry/config.json:")
+    print(json.dumps(config, indent=2))
+
+    repo_root = Path.cwd()
+    gantry_dir = repo_root / ".gantry"
+    config_path = gantry_dir / "config.json"
+
+    if config_path.exists():
+        choice = input("Config exists. [M]erge, [O]verwrite, or [A]bort? ").strip().lower()
+        if choice.startswith('a'):
+            print("Aborted.")
+            sys.exit(1)
+        elif choice.startswith('o'):
+            final_config = config
+        elif choice.startswith('m'):
+            existing = json.loads(config_path.read_text(encoding="utf-8"))
+            final_config = merge_dicts(existing, config)
+        else:
+            print("Invalid choice, aborted.")
+            sys.exit(1)
+    else:
+        choice = input("Write this policy? [y/N] ").strip().lower()
+        if not choice.startswith('y'):
+            print("Aborted.")
+            sys.exit(1)
+        final_config = config
+
+    gantry_dir.mkdir(parents=True, exist_ok=True)
+    config_path.write_text(json.dumps(final_config, indent=2) + "\n", encoding="utf-8")
+
+    hook_frag_path = Path(__file__).resolve().parents[1] / "hooks" / "claude-code.settings.json"
+    if hook_frag_path.exists():
+        hook_frag = json.loads(hook_frag_path.read_text(encoding="utf-8"))
+        settings_path = repo_root / ".claude" / "settings.json"
+        settings_path.parent.mkdir(parents=True, exist_ok=True)
+        content = settings_path.read_text(encoding="utf-8") if settings_path.exists() else ""
+        
+        new_hooks = hook_frag.get("hooks", {})
+        if not content.strip():
+            settings_path.write_text(json.dumps({"hooks": new_hooks}, indent=2) + "\n", encoding="utf-8")
+        else:
+            # Parse top level to check if hooks exists
+            parsed = json.loads(content)
+            if "hooks" not in parsed:
+                last_brace = content.rfind('}')
+                if last_brace != -1:
+                    hooks_json = json.dumps({"hooks": new_hooks}, indent=2)[1:-1]
+                    if not parsed:
+                        new_content = content[:last_brace] + hooks_json + content[last_brace:]
+                    else:
+                        new_content = content[:last_brace] + "," + hooks_json + content[last_brace:]
+                    settings_path.write_text(new_content, encoding="utf-8")
+            else:
+                import re
+                match = re.search(r'"hooks"\s*:\s*\{', content)
+                if match:
+                    start_idx = match.end() - 1
+                    brace_count = 0
+                    end_idx = start_idx
+                    in_string = False
+                    escape = False
+                    for i in range(start_idx, len(content)):
+                        c = content[i]
+                        if not in_string:
+                            if c == '{': brace_count += 1
+                            elif c == '}':
+                                brace_count -= 1
+                                if brace_count == 0:
+                                    end_idx = i + 1
+                                    break
+                            elif c == '"': in_string = True
+                        else:
+                            if escape: escape = False
+                            elif c == '\\': escape = True
+                            elif c == '"': in_string = False
+                    old_hooks = json.loads(content[start_idx:end_idx])
+                    for k, v in new_hooks.items():
+                        old_hooks[k] = v
+                    lines = content[:start_idx].split('\n')
+                    base_indent = len(lines[-1]) - len(lines[-1].lstrip()) if lines else 2
+                    new_hooks_text = json.dumps(old_hooks, indent=2)
+                    indented_new_hooks = new_hooks_text.replace('\n', '\n' + ' ' * base_indent)
+                    settings_path.write_text(content[:start_idx] + indented_new_hooks + content[end_idx:], encoding="utf-8")
+
+    agents_path = repo_root / "AGENTS.md"
+    content = agents_path.read_text(encoding="utf-8") if agents_path.exists() else ""
+    begin_marker = "<!-- gantry:begin -->"
+    end_marker = "<!-- gantry:end -->"
+    
+    new_section = (
+        f"{begin_marker}\n"
+        "## Gantry Repository Policy\n\n"
+        "This repository uses Gantry for its agentic SDLC.\n"
+        "Artifacts, templates, and checks are configured in `.gantry/config.json`.\n"
+        f"{end_marker}\n"
+    )
+
+    if begin_marker in content and end_marker in content:
+        start = content.find(begin_marker)
+        end = content.find(end_marker) + len(end_marker)
+        if content[end:end+1] == "\n":
+            end += 1
+        new_content = content[:start] + new_section + content[end:]
+    else:
+        new_content = content + ("\n" if content and not content.endswith("\n") else "") + new_section
+
+    agents_path.write_text(new_content, encoding="utf-8")
+
+if __name__ == "__main__":
+    main()