@julioborges/gantry 1.0.5 → 1.1.0

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

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import argparse
 import json
+import re
 import sys
 from pathlib import Path
 from typing import Any
@@ -69,6 +70,59 @@ def load_schema(role: str) -> dict[str, Any]:
     return schema
 
 
+def extract_json(raw: str) -> Any:
+    """Extract and parse JSON from raw string, handling markdown fences and delimiters."""
+    if not raw or not raw.strip():
+        raise json.JSONDecodeError("Expecting value: empty input", raw or "", 0)
+
+    text = raw.strip()
+    # 1. Try parsing directly
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        pass
+
+    # 2. Extract from markdown code fence (```json ... ``` or ``` ... ```)
+    fence_pattern = re.compile(r"```+(?:json|JSON)?\s*\n([\s\S]*?)\n```+", re.MULTILINE)
+    matches = fence_pattern.findall(text)
+    for block in matches:
+        try:
+            return json.loads(block.strip())
+        except json.JSONDecodeError:
+            continue
+
+    fence_pattern_inline = re.compile(r"```+(?:json|JSON)?\s*([\s\S]*?)\s*```+", re.MULTILINE)
+    matches_inline = fence_pattern_inline.findall(text)
+    for block in matches_inline:
+        try:
+            return json.loads(block.strip())
+        except json.JSONDecodeError:
+            continue
+
+    # 3. Try outermost JSON object braces `{ ... }`
+    first_brace = text.find("{")
+    last_brace = text.rfind("}")
+    if first_brace != -1 and last_brace != -1 and last_brace > first_brace:
+        candidate = text[first_brace : last_brace + 1].strip()
+        try:
+            return json.loads(candidate)
+        except json.JSONDecodeError:
+            pass
+
+    # 4. Try outermost JSON array brackets `[ ... ]`
+    first_bracket = text.find("[")
+    last_bracket = text.rfind("]")
+    if first_bracket != -1 and last_bracket != -1 and last_bracket > first_bracket:
+        candidate = text[first_bracket : last_bracket + 1].strip()
+        try:
+            return json.loads(candidate)
+        except json.JSONDecodeError:
+            pass
+
+    # Fallback to direct json.loads to raise original JSONDecodeError
+    return json.loads(text)
+
+
 def main() -> int:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("--role", required=True, choices=ROLES, help="role contract to validate")
@@ -84,7 +138,8 @@ def main() -> int:
         print(json.dumps(schema))
         return 0
     try:
-        result = json.load(sys.stdin)
+        raw_input = sys.stdin.read()
+        result = extract_json(raw_input)
     except json.JSONDecodeError as error:
         errors = [f"$: invalid JSON: {error.msg}"]
     else:

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

@@ -34,12 +34,13 @@ EVENTS = {
     "review.finding",
     "role.selected",
     "role.changed",
+    "operator.approved",
 }
 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", "issue.paused", "refutation", "review.finding", "role.selected", "role.changed"}
+ISSUE_EVENTS = {"issue.done", "issue.blocked", "issue.paused", "refutation", "review.finding", "role.selected", "role.changed", "operator.approved"}
 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._:-]*$")

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

@@ -15,24 +15,97 @@ def merge_dicts(base: dict, update: dict) -> dict:
             base[k] = v
     return base
 
+def detect_codex(repo_root: Path) -> bool:
+    """Detect presence of Codex CLI on PATH or .codex directory in project."""
+    return bool(
+        shutil.which("codex")
+        or (repo_root / ".codex").exists()
+        or os.environ.get("CODEX_HOME")
+        or os.environ.get("CODEX_CLI")
+    )
+
 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")
+    parser.add_argument("--harness", choices=["codex", "claude-code", "antigravity", "opencode"], help="Explicit target harness")
+    parser.add_argument("--verify-auth", action="store_true", help="Explicitly guide/verify authentication and discovery before finalizing")
     args = parser.parse_args()
 
+    repo_root = Path.cwd()
+    config = None
+
     if args.config_file:
         config = json.loads(Path(args.config_file).read_text(encoding="utf-8"))
     elif args.config:
         config = json.loads(args.config)
+    elif args.harness == "codex":
+        config = {
+            "execution": {
+                "hostHarness": "codex",
+                "roles": {
+                    "plan": {"harness": "codex", "model": "gpt-5.2-codex"},
+                    "implement": {"harness": "codex", "model": "gpt-5.2-codex"},
+                    "review": {"harness": "codex", "model": "gpt-5.2-codex"},
+                    "critic": {"harness": "codex", "model": "gpt-5.2-codex"},
+                },
+            }
+        }
     else:
+        # Interactive detection when no config is passed
+        if detect_codex(repo_root):
+            source = "PATH" if shutil.which("codex") else ".codex"
+            print(f"Detected Codex in environment ({source}).")
+            try:
+                ans = input("Configure Codex as host harness? [Y/n] ").strip().lower()
+            except (EOFError, KeyboardInterrupt):
+                ans = "n"
+            if ans in ("", "y", "yes"):
+                config = {
+                    "execution": {
+                        "hostHarness": "codex",
+                        "roles": {
+                            "plan": {"harness": "codex", "model": "gpt-5.2-codex"},
+                            "implement": {"harness": "codex", "model": "gpt-5.2-codex"},
+                            "review": {"harness": "codex", "model": "gpt-5.2-codex"},
+                            "critic": {"harness": "codex", "model": "gpt-5.2-codex"},
+                        },
+                    }
+                }
+
+    if config is None:
         print("Error: No config provided", file=sys.stderr)
         sys.exit(2)
 
+    if args.harness:
+        if "execution" not in config or not isinstance(config["execution"], dict):
+            config["execution"] = {}
+        config["execution"]["hostHarness"] = args.harness
+
+    is_codex = (
+        (args.harness == "codex")
+        or (isinstance(config, dict) and config.get("execution", {}).get("hostHarness") == "codex")
+    )
+
+    if is_codex or args.verify_auth:
+        print("Codex host harness selected or detected.")
+        print("Guidance: Ensure Codex CLI is authenticated via `codex login` before execution.")
+        print("Testing Codex model discovery...")
+        scripts_dir = Path(__file__).resolve().parent
+        if str(scripts_dir) not in sys.path:
+            sys.path.insert(0, str(scripts_dir))
+        try:
+            import discovery
+            models = discovery.discover_codex_models(use_cache=False)
+            model_ids = [m["id"] for m in models]
+            print(f"Codex discovery verified: {len(models)} model(s) discovered ({', '.join(model_ids[:3])}).")
+        except Exception as exc:
+            print(f"Notice: Codex discovery check: {exc}")
+            print("Remediation: Run `codex login` to verify credentials before running Gantry tasks.")
+
     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"
 
@@ -119,7 +192,7 @@ def main() -> None:
         if ag_hook_frag_path.exists():
             ag_hook_frag = json.loads(ag_hook_frag_path.read_text(encoding="utf-8"))
         else:
-            guard_cmd = 'python3 ".agents/skills/gantry/scripts/guard.py" PreToolUse --json'
+            guard_cmd = 'python3 "skills/gantry/scripts/guard.py" PreToolUse --json'
             ag_hook_frag = {
                 "hooks": {
                     "PreToolUse": [
@@ -150,18 +223,38 @@ def main() -> None:
         else:
             hooks_json_path.write_text(json.dumps(ag_hook_frag, indent=2) + "\n", encoding="utf-8")
 
+    is_codex_final = (
+        final_config.get("execution", {}).get("hostHarness") == "codex"
+        or args.harness == "codex"
+    )
+
     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 is_codex_final:
+        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\n"
+            "### Codex Host Orchestration & Guardrails\n\n"
+            "When Codex operates as host harness or execution runner:\n"
+            "- Bounded Execution: Role agents (Implementer, Reviewer, Critic) are executed via bounded sub-processes (`codex exec` or cross-harness dispatch).\n"
+            "- Invariant Protection: Never hand-edit `ROADMAP.md` or issue checkboxes/status lines directly. Only `roadmap.py done` updates them after Critic acceptance.\n"
+            "- Branch Isolation: Direct commits to `main` are forbidden; all work proceeds on dedicated issue branches.\n"
+            "- Defense in Depth: Because Codex lacks native tool hooks, git hooks and adversarial Critic verification enforce delivery integrity and contract validation (`result.py`).\n"
+            f"{end_marker}\n"
+        )
+    else:
+        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)

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

@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+"""Wait for operator approval after Critic verification before starting Integrate."""
+from __future__ import annotations
+
+import argparse
+import datetime
+import json
+import os
+import sys
+import threading
+import time
+from pathlib import Path
+
+from runlog import ISSUE_RE, RUN_ID_RE, UNIT_ID_RE, append_event, read_marker, resolve_hook_run, run_log_path, state_root as default_state_root, unit_id as derive_unit_id
+
+
+class WaitGateError(ValueError):
+    """The gate check cannot execute safely with the provided arguments."""
+
+
+def approval_marker_path(root: Path, unit: str, issue: str) -> Path:
+    return root / unit / "approvals" / f"{issue}.json"
+
+
+def read_approval_marker(root: Path, unit: str, issue: str) -> dict | None:
+    path = approval_marker_path(root, unit, issue)
+    if not path.exists():
+        return None
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        if isinstance(data, dict) and data.get("issue") == issue:
+            return data
+    except (OSError, json.JSONDecodeError):
+        pass
+    return None
+
+
+def write_approval_marker(root: Path, unit: str, run: str, issue: str, source: str = "terminal") -> Path:
+    path = approval_marker_path(root, unit, issue)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    payload = {
+        "unit": unit,
+        "run": run,
+        "issue": issue,
+        "approvedAt": datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "source": source,
+    }
+    path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+
+    # Record operator.approved in Run log if run log exists
+    log_path = run_log_path(root, unit, run)
+    if log_path.exists():
+        try:
+            append_event(
+                log_path,
+                {
+                    "ts": payload["approvedAt"],
+                    "run": run,
+                    "event": "operator.approved",
+                    "issue": issue,
+                    "data": {"approvedAt": payload["approvedAt"], "source": source},
+                },
+            )
+        except Exception:
+            pass
+    return path
+
+
+def wait_for_gate(
+    root: Path,
+    unit: str,
+    run: str,
+    issue: str,
+    timeout: float | None = None,
+    poll_interval: float = 0.2,
+    prompt: bool = True,
+) -> int:
+    start_time = time.time()
+    marker = read_approval_marker(root, unit, issue)
+    if marker:
+        print(json.dumps({"approved": True, "issue": issue, "source": marker.get("source", "marker"), "approvedAt": marker.get("approvedAt")}))
+        return 0
+
+    user_input: list[str] = []
+    if prompt and sys.stdin.isatty():
+        sys.stderr.write(f"\n[GANTRY GATE] Issue {issue} passed Critic verification.\n")
+        sys.stderr.write("Press [Enter] or type 'y' to approve and proceed to Integrate (or approve in Dashboard UI): ")
+        sys.stderr.flush()
+
+        def _reader() -> None:
+            try:
+                line = sys.stdin.readline()
+                user_input.append(line.strip().lower())
+            except Exception:
+                pass
+
+        t = threading.Thread(target=_reader, daemon=True)
+        t.start()
+
+    while True:
+        # 1. Check approval marker
+        marker = read_approval_marker(root, unit, issue)
+        if marker:
+            print(json.dumps({"approved": True, "issue": issue, "source": marker.get("source", "marker"), "approvedAt": marker.get("approvedAt")}))
+            return 0
+
+        # 2. Check terminal stdin if available
+        if user_input:
+            line = user_input[0]
+            if line in ("", "y", "yes", "approve", "ok", "1"):
+                write_approval_marker(root, unit, run, issue, source="terminal")
+                print(json.dumps({"approved": True, "issue": issue, "source": "terminal"}))
+                return 0
+
+        if timeout is not None and timeout > 0:
+            if (time.time() - start_time) >= timeout:
+                sys.stderr.write(f"\n[GANTRY GATE] Timeout waiting for operator approval for {issue}.\n")
+                return 1
+
+        time.sleep(poll_interval)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("issue", nargs="?", help="Issue reference e.g. sample#01")
+    parser.add_argument("--issue", dest="opt_issue", help="Issue reference")
+    parser.add_argument("--unit", help="Execution unit ID")
+    parser.add_argument("--run", help="Run ID")
+    parser.add_argument("--state-root", help="State root directory")
+    parser.add_argument("--cwd", default=".", help="Current working directory")
+    parser.add_argument("--poll-interval", type=float, default=0.2, help="Poll interval in seconds")
+    parser.add_argument("--timeout", type=float, default=None, help="Timeout in seconds")
+    parser.add_argument("--check", action="store_true", help="Check approval status non-blocking and exit")
+    parser.add_argument("--approve", action="store_true", help="Approve gate immediately and exit")
+    args = parser.parse_args(argv)
+
+    issue = args.issue or args.opt_issue
+    if not issue or not ISSUE_RE.fullmatch(issue):
+        print(f"wait-gate error: valid issue reference required (e.g. sample#01), got {issue!r}", file=sys.stderr)
+        return 2
+
+    cwd = Path(args.cwd).resolve()
+    root = Path(args.state_root).expanduser().resolve() if args.state_root else default_state_root(None)
+
+    unit = args.unit
+    if not unit:
+        try:
+            unit = derive_unit_id(cwd)
+        except Exception:
+            unit = "000000000000"
+    if not UNIT_ID_RE.fullmatch(unit):
+        print(f"wait-gate error: invalid unit id {unit!r}", file=sys.stderr)
+        return 2
+
+    run = args.run
+    if not run:
+        env_run, _ = resolve_hook_run(cwd)
+        run = env_run or "run-default"
+    if not RUN_ID_RE.fullmatch(run):
+        print(f"wait-gate error: invalid run id {run!r}", file=sys.stderr)
+        return 2
+
+    if args.approve:
+        write_approval_marker(root, unit, run, issue, source="terminal")
+        print(json.dumps({"approved": True, "issue": issue, "source": "terminal"}))
+        return 0
+
+    if args.check:
+        marker = read_approval_marker(root, unit, issue)
+        if marker:
+            print(json.dumps({"approved": True, "issue": issue, "source": marker.get("source", "marker"), "approvedAt": marker.get("approvedAt")}))
+            return 0
+        return 1
+
+    return wait_for_gate(root, unit, run, issue, timeout=args.timeout, poll_interval=args.poll_interval)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/.agents/skills/gantry-dashboard/SKILL.md

@@ -12,10 +12,16 @@ changed from the dashboard.
 
 ## Open the dashboard
 
+### Foreground server
 ```
 python3 <skillDir>/../gantry/scripts/dashboard.py serve
 ```
 
+### Background daemon
+```
+python3 <skillDir>/../gantry/scripts/dashboard.py start --daemon
+```
+
 - Binds `127.0.0.1` only; the script refuses any other `--host` value and exits non-zero
   before opening a socket. There is no way to expose the dashboard beyond the local machine.
 - Defaults to port `4600`; pass `--port 0` for an OS-assigned ephemeral port (the script
@@ -25,6 +31,17 @@ python3 <skillDir>/../gantry/scripts/dashboard.py serve
   example when inspecting a fixture.
 - Open `http://127.0.0.1:<port>/` in a browser once the server is listening.
 
+## Daemon subcommands and status
+
+- Query status: `python3 <skillDir>/../gantry/scripts/dashboard.py status [--json]`
+- Terminate daemon: `python3 <skillDir>/../gantry/scripts/dashboard.py stop`
+
+## Round lifecycle hooks
+
+Gantry's round workflow automates dashboard lifecycle checks:
+- **Pre-implementation hook**: Prior to starting the `Implement` phase, the workflow checks `dashboard.py status --json`. If inactive, it asks the operator whether to launch the dashboard with `dashboard.py start --daemon`. If approved, it launches the daemon and displays the URL. If the operator declines, it proceeds without prompting again. If already active, it logs the active URL without prompting.
+- **Post-integration hook**: After completing `Integrate`, if `dashboard.py status --json` reports active, it asks the operator whether to terminate the dashboard with `dashboard.py stop`. If approved, it cleanly stops the daemon.
+
 ## What you see
 
 - One swimlane per Run (`<repositoryRoot> — <run> [tier: …]`), across every execution unit
@@ -51,5 +68,7 @@ tests.
 
 ## Stopping the server
 
-`Ctrl-C` in the terminal running `dashboard.py serve` stops it; nothing it does needs
-cleanup, because it never wrote anything.
+- For the foreground server: `Ctrl-C` in the terminal running `dashboard.py serve`.
+- For the daemon: `python3 <skillDir>/../gantry/scripts/dashboard.py stop`.
+- From the browser: click the **SHUTDOWN** button in the dashboard rig header and confirm in the dialog.
+

package/.agents/skills/gantry-plan/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: gantry-plan
+description: Socratic Gate planning and tracer-bullet vertical slicing. Guides interactive goal discovery, challenges architectural assumptions, decomposes specs into thin vertical slices, audits token budgets, and validates through Plan Critic.
+argument-hint: <spec-slug | spec-path | "free-text goal">
+---
+
+# Gantry Plan
+
+A harness-neutral planning skill that unifies Socratic interviewing and tracer-bullet
+vertical slicing (`to-issues` pattern). It turns unrefined goals or raw specs into
+verifiable, end-to-end demonstrable Issues scheduled into execution waves.
+
+```
+Goal or Spec → [Socratic Gate / Spec Validation] → Tracer-Bullet Slicing
+             → Budget Audit → Plan Critic → Operator Quiz → Approval Transition
+             → Execution Handoff
+```
+
+## Dual Entry Modes
+
+### 1. Free-Text Goal
+
+When invoked with a free-text prompt or goal (e.g. `/gantry-plan "add webhook support"`):
+1. **Context Exploration**: Explore repository context in the background:
+   - Glossary: `CONTEXT.md`
+   - Requirements: `PRD.md`
+   - Standing decisions: `docs/adr/`
+   - Existing modules under `scripts/` and `.agents/skills/`.
+2. **Telemetry Initiation**: Emit a `phase.started` event in the Run log for milestone
+   `<slug>#00` with `phase: "Plan"` and `data.operatorWaiting: true`. The Gantry Kanban
+   dashboard displays an *"Awaiting Operator"* badge in the `Plan` column.
+3. **Socratic Gate Interview**: Guide the operator across 4 structured phases:
+   - **Problem Statement & Context**: Pain point, concrete use case, user personas.
+   - **Architectural Boundaries & Seams**: Seam locations, CLI/API contracts, dependencies.
+   - **Scope & Non-Goals**: Strictly in-scope capabilities vs explicit out-of-scope boundaries.
+   - **Verifiable Criteria & Scenarios**: Acceptance criteria and primary Gherkin scenarios.
+   Each question presents a concise recommended answer based on repository conventions.
+4. **Operator Response Logging**: When the operator answers, record `operator.approved`
+   in the Run log for `<slug>#00`.
+5. **Spec Synthesis**: Generate `.scratch/<slug>/spec.md` conforming to the Gantry spec template
+   (`Blueprint`, `Contract`, `Definition of Done`, `Regression Guardrails`, `Scenarios`,
+   `Out of Scope`, `Changelog`).
+6. **Spec Verification**: Verify the synthesized spec passes `python3 <skillDir>/../gantry/scripts/spec.py --check <spec-path>`.
+
+### 2. Spec-Provided
+
+When invoked with an existing spec path or slug (e.g. `/gantry-plan .scratch/auth/spec.md` or `/gantry-plan auth`):
+1. Validate the spec structurally via `python3 <skillDir>/../gantry/scripts/spec.py --check <spec-path>`.
+2. Run read-only Requirement Critic evaluation (checking for ambiguity, coherence, verifiability, and non-goals).
+
+## Tracer-Bullet Vertical Slicing
+
+Decompose the approved spec into end-to-end demonstrable vertical slices:
+1. **Prefactoring First**: Isolate prefactoring into `<slug>#01` ("Make the change easy, then make the easy change").
+   Slice 01 has no implementation blockers. Subsequent slices depend on Slice 01 (`Blocked by: <slug>#01`).
+2. **Vertical Slices**: Every slice cuts across all necessary layers (CLI/API, domain logic, tests) rather than
+   horizontal layers (no "database-only" or "frontend-only" issues).
+3. **Issue Metadata**: Maintain standard Gantry issue headers:
+   - `Type: issue`
+   - `Status: draft`
+   - `Slice: <slug>#NN`
+   - `Spec: .scratch/<slug>/spec.md`
+   - `### Files to read`
+   - `## Acceptance criteria` (with `- [ ]` checkboxes)
+   - `## Blocked by`
+4. **Context Budget Audit**: Verify each issue fits within model token windows via `budget.py`.
+5. **Plan Critic**: Verify that:
+   - Blocker graph forms a valid directed acyclic graph (DAG) without cycles.
+   - Every issue has observable acceptance criteria.
+   - No horizontal slicing smells are present.
+6. **Operator Quiz**: Quiz the operator on:
+   - Granularity (are slices sized for single-round TDD deliveries?).
+   - Dependency sequence (is prefactoring prioritized?).
+   - Split / merge preferences.
+7. **Persist Issues**: Write issues to `.scratch/<slug>/issues/NN-<slug>.md`.
+
+## Planning Approval Transition
+
+Upon operator approval of the issue breakdown:
+1. **Update Issue Status**: Set status of generated issues to `ready-for-agent`:
+   ```bash
+   python3 <skillDir>/../gantry/scripts/roadmap.py status <ref> ready-for-agent
+   ```
+2. **Recompute Waves**: Update `ROADMAP.md` wave layout:
+   ```bash
+   python3 <skillDir>/../gantry/scripts/roadmap.py waves
+   ```
+3. **Verify Integrity**: Ensure zero drift:
+   ```bash
+   python3 <skillDir>/../gantry/scripts/roadmap.py check
+   ```
+4. **Complete Planning Milestone**: Record milestone completion in the Run log:
+   - Append `issue.done` for milestone `<slug>#00` with `phase: "Plan"`.
+   (Alternatively, use `python3 <skillDir>/../gantry/scripts/plan.py --approve <slug>`).
+
+## Execution Handoff
+
+- **Standalone Invocation (`/gantry-plan`)**:
+  Present the computed execution waves and prompt the operator:
+  > Planning approved and scheduled into Wave N. Would you like to launch execution now with `/gantry`?
+  Wait for explicit confirmation before launching `gantry`.
+- **Delegated Invocation (from `/gantry`)**:
+  When delegated from `/gantry`, automatically proceed directly into Gantry's TDD
+  implementation round loop without additional prompting.

package/.agents/skills/gantry-setup/SKILL.md

@@ -29,15 +29,21 @@ You are the sole conversational writer of repository policy.
    - When Antigravity is detected (`.agents/` directory or `agy` CLI on PATH), `setup.py` generates or merges `.agents/hooks.json` to wire `PreToolUse` to `guard.py PreToolUse --json`.
    - Unrelated repository policy, hook settings and Caveman opt-in are preserved during merges.
 
-5. **Constraints**:
+5. **Codex Host Harness & Defense in Depth**:
+   - Detect Codex in environment via `codex` CLI on PATH, `.codex` configuration, or explicit `--harness codex`.
+   - Guide operator to verify authentication (`codex login`) and test model discovery (`discovery.py --harness codex`) before finalizing configuration.
+   - Configure `execution.hostHarness: "codex"` and role model assignments in `.gantry/config.json`.
+   - Inject Codex-specific orchestration rules (bounded subprocess dispatch via `codex exec`) and defense-in-depth guardrail directives into the marked Gantry policy block in `AGENTS.md`.
+
+6. **Constraints**:
    - Creates no engine, database, MCP service, or automatic cleanup.
    - All setup-generated policy, prompts, and marked content must be English.
 
-6. **Applying the Policy**:
+7. **Applying the Policy**:
    Once the operator confirms the settings, construct the JSON configuration and pipe it to `setup.py`:
    
    ```bash
    python3 .agents/skills/gantry/scripts/setup.py --config '{...}'
    ```
    
-   The `setup.py` script renders the full proposed `.gantry/config.json` before writing, supports merge, overwrite, and abort for an existing policy, handles idempotent merging of the Claude Code hook fragment into `.claude/settings.json`, configures `.agents/hooks.json` when Antigravity is detected, and adds or replaces only the marked Gantry section in `AGENTS.md`. Do not modify these files directly.
+   The `setup.py` script renders the full proposed `.gantry/config.json` before writing, supports merge, overwrite, and abort for an existing policy, handles idempotent merging of the Claude Code hook fragment into `.claude/settings.json`, configures `.agents/hooks.json` when Antigravity is detected, supports `--harness codex` with discovery verification, and adds or replaces only the marked Gantry section in `AGENTS.md`. Do not modify these files directly.