devcouncil 0.3.1 → 0.4.1

package/src/devcouncil/cli/commands/integrate.py

@@ -1,1089 +1,107 @@
-import json
-import shlex
+from devcouncil.utils.json_persist import dump_json
+import logging
 import shutil
-import subprocess
-import sys
-from contextlib import contextmanager
 from pathlib import Path
 
 import typer
-import yaml  # type: ignore[import-untyped]
 from rich.console import Console
 from rich.table import Table
+from devcouncil.telemetry.stages import log_stage, log_step
 
 from devcouncil.executors.agent_registry import (
-    BUILTIN_CODING_EXECUTOR_NAMES,
-    CODING_CLI_INTEGRATION_INFO,
+    GEMINI_DEPRECATION_MESSAGE,
     VALID_INPUT_MODES,
     agent_config_entry,
-    detect_available_coding_cli,
-    integration_tier_label,
     is_reserved_agent_name,
     load_agent_profiles,
-    load_cli_agent_specs,
     normalize_agent_name,
-    resolve_automated_executor,
-    resolve_coding_cli_executable,
-    resolve_coding_cli_probe_order,
 )
 from devcouncil.integrations.actions import apply_integration_target
-from devcouncil.utils.subprocess_env import clean_subprocess_env
-from devcouncil.integrations.check import (
-    build_integration_check_report,
-    integration_status_summary,
+from devcouncil.integrations.integration_cli import (
+    print_integration_matrix,
+    print_integration_status,
+    print_recommendations,
+    run_integration_check,
+)
+from devcouncil.integrations.setup import (
+    apply_agent_flow_setup,
+    apply_code_review_graph_setup,
+    build_integrations_doctor_table,
+)
+from devcouncil.integrations.clients import (
+    antigravity as antigravity_client,
+    aider as aider_client,
+    claude as claude_client,
+    codex as codex_client,
+    common,
+    cursor as cursor_client,
+    gemini as gemini_client,
+    grok as grok_client,
+    hooks as hooks_client,
+    opencode as opencode_client,
+    warp as warp_client,
 )
 
 app = typer.Typer(help="Set up DevCouncil integrations with coding CLIs.")
 setup_app = typer.Typer(help="Set up optional external companion integrations.")
 app.add_typer(setup_app, name="setup")
 console = Console()
+logger = logging.getLogger(__name__)
 
-SUPPORTED_TOOLS = ("codex", "gemini", "claude", "cursor", "opencode", "antigravity", "warp", "aider")
-SUPPORTED_HOOK_TOOLS = ("codex", "gemini", "claude", "cursor")
-OPENCODE_HOOK_PLUGIN_NAME = "opencode_devcouncil_plugin.mjs"
+SUPPORTED_TOOLS = ("claude", "codex", "cursor", "grok", "opencode", "antigravity", "warp", "aider", "gemini")
+SUPPORTED_HOOK_TOOLS = common.SUPPORTED_HOOK_TOOLS
+OPENCODE_HOOK_PLUGIN_NAME = common.OPENCODE_HOOK_PLUGIN_NAME
 PREFERRED_COMMAND = "dev integrate"
 LEGACY_COMMAND = "dev setup --integrate"
 
-
-def _project_root(path: str | Path | None) -> Path:
-    return Path(path or ".").expanduser().resolve()
-
-
-def _warn_if_verify_only(client: str) -> None:
-    """Print a prominent containment warning when wiring a verify-only client.
-
-    Verify-only clients have no native pre-tool-use hook, so DevCouncil cannot block a
-    forbidden write or command before it happens — it is only caught post-hoc at verify
-    time. Surface this loudly so users don't assume hard containment."""
-    info = CODING_CLI_INTEGRATION_INFO.get(normalize_agent_name(client))
-    if info is not None and not info.hooks:
-        console.print(
-            f"[bold yellow]Warning ({info.label}): No pre-action containment — "
-            "forbidden writes/commands are caught only at verify time.[/bold yellow]"
-        )
-
-
-def _server_args(project_root: Path) -> list[str]:
-    return ["devcouncil", "mcp-server"]
-
-
-def _codex_command(project_root: Path) -> list[str]:
-    return [
-        "codex",
-        "mcp",
-        "add",
-        "devcouncil",
-        "--env",
-        f"DEVCOUNCIL_PROJECT_ROOT={project_root}",
-        "--",
-        *_server_args(project_root),
-    ]
-
-
-def _gemini_command(project_root: Path, scope: str) -> list[str]:
-    return [
-        "gemini",
-        "mcp",
-        "add",
-        "--scope",
-        scope,
-        "--env",
-        f"DEVCOUNCIL_PROJECT_ROOT={project_root}",
-        "devcouncil",
-        *_server_args(project_root),
-    ]
-
-
-def _claude_command(project_root: Path, scope: str) -> list[str]:
-    # The server name must come BEFORE --env: the current Claude CLI treats --env
-    # as variadic, so `--env KEY=VALUE devcouncil` swallows the name `devcouncil`
-    # as a second (invalid) env var. Putting the name first — matching the working
-    # codex form — and terminating options with `--` avoids that.
-    return [
-        "claude",
-        "mcp",
-        "add",
-        "--scope",
-        scope,
-        "devcouncil",
-        "--env",
-        f"DEVCOUNCIL_PROJECT_ROOT={project_root}",
-        "--",
-        *_server_args(project_root),
-    ]
-
-
-def _cursor_config_path(project_root: Path) -> Path:
-    return project_root / ".cursor" / "mcp.json"
-
-
-def _cursor_mcp_config(project_root: Path) -> dict:
-    return {
-        "mcpServers": {
-            "devcouncil": {
-                "type": "stdio",
-                "command": "devcouncil",
-                "args": ["mcp-server"],
-                "env": {"DEVCOUNCIL_PROJECT_ROOT": str(project_root)},
-            }
-        }
-    }
-
-
-def _warp_mcp_config(project_root: Path) -> dict:
-    return {
-        "devcouncil": {
-            "command": "devcouncil",
-            "args": ["mcp-server"],
-            "env": {"DEVCOUNCIL_PROJECT_ROOT": str(project_root)},
-        }
-    }
-
-
-def _warp_mcp_path(project_root: Path) -> Path:
-    return project_root / ".devcouncil" / "integrations" / "warp-mcp.json"
-
-
-def _opencode_config_path(project_root: Path) -> Path:
-    return project_root / "opencode.json"
-
-
-def _opencode_mcp_entry(project_root: Path) -> dict:
-    return {
-        "type": "local",
-        "command": ["devcouncil", "mcp-server"],
-        "environment": {"DEVCOUNCIL_PROJECT_ROOT": str(project_root)},
-        "enabled": True,
-        "timeout": 10000,
-    }
-
-
-def _antigravity_mcp_path(project_root: Path) -> Path:
-    return project_root / ".agents" / "mcp_config.json"
-
-
-def _antigravity_mcp_config(project_root: Path) -> dict:
-    return {
-        "mcpServers": {
-            "devcouncil": {
-                "command": "devcouncil",
-                "args": ["mcp-server"],
-                "env": {"DEVCOUNCIL_PROJECT_ROOT": str(project_root)},
-                "cwd": str(project_root),
-            }
-        }
-    }
-
-
-def _write_warp_mcp_config(project_root: Path) -> Path:
-    path = _warp_mcp_path(project_root)
-    _save_json(path, _warp_mcp_config(project_root))
-    return path
-
-
-def _write_cursor_config(project_root: Path) -> Path:
-    path = _cursor_config_path(project_root)
-    data = _load_json_strict(path, "Cursor")
-    mcp_servers = data.setdefault("mcpServers", {})
-    mcp_servers["devcouncil"] = _cursor_mcp_config(project_root)["mcpServers"]["devcouncil"]
-    _save_json(path, data)
-    return path
-
-
-# When set, _mutate_raw_config applies record mutations in memory and
-# _batched_raw_config saves config.yaml once at the end (used by
-# `dev integrate all --apply`, which otherwise re-parses YAML per tool).
-_PENDING_RAW_CONFIG: dict | None = None
-
-
-@contextmanager
-def _batched_raw_config(project_root: Path):
-    global _PENDING_RAW_CONFIG
-    # Re-entrant: if a batch is already active, participate in it instead of
-    # starting a nested load/save (which would otherwise reset the shared
-    # buffer to None on inner exit and drop the outer batch's mutations).
-    if _PENDING_RAW_CONFIG is not None:
-        yield
-        return
-    _PENDING_RAW_CONFIG = _load_raw_config(project_root)
-    try:
-        yield
-    finally:
-        # Persist whatever mutations accumulated, even if an inner installer raised
-        # partway through — matching the old per-installer save, which committed each
-        # installer's change immediately rather than dropping the whole batch on a
-        # mid-loop failure.
-        pending = _PENDING_RAW_CONFIG
-        _PENDING_RAW_CONFIG = None
-        if pending is not None:
-            _save_raw_config(project_root, pending)
-
-
-def _mutate_raw_config(project_root: Path, mutate) -> None:
-    if _PENDING_RAW_CONFIG is not None:
-        mutate(_PENDING_RAW_CONFIG)
-        return
-    config = _load_raw_config(project_root)
-    mutate(config)
-    _save_raw_config(project_root, config)
-
-
-def _record_cursor_config(project_root: Path) -> None:
-    def mutate(config: dict) -> None:
-        cursor = config.setdefault("integrations", {}).setdefault("cursor", {})
-        cursor.update({
-            "enabled": True,
-            "config_path": str(_cursor_config_path(project_root).relative_to(project_root)),
-        })
-
-    _mutate_raw_config(project_root, mutate)
-
-
-def _record_warp_config(project_root: Path) -> None:
-    def mutate(config: dict) -> None:
-        warp = config.setdefault("integrations", {}).setdefault("warp", {})
-        warp.update({
-            "enabled": True,
-            "command": warp.get("command", "oz"),
-            "run_mode": warp.get("run_mode", "local"),
-            "mcp_config_path": str(_warp_mcp_path(project_root).relative_to(project_root)),
-        })
-
-    _mutate_raw_config(project_root, mutate)
-
-
-def _record_opencode_config(project_root: Path) -> None:
-    def mutate(config: dict) -> None:
-        opencode = config.setdefault("integrations", {}).setdefault("opencode", {})
-        opencode.update({
-            "enabled": True,
-            "config_path": str(_opencode_config_path(project_root).relative_to(project_root)),
-        })
-
-    _mutate_raw_config(project_root, mutate)
-
-
-def _record_antigravity_config(project_root: Path) -> None:
-    def mutate(config: dict) -> None:
-        antigravity = config.setdefault("integrations", {}).setdefault("antigravity", {})
-        antigravity.update({
-            "enabled": True,
-            "mcp_config_path": str(_antigravity_mcp_path(project_root).relative_to(project_root)),
-        })
-
-    _mutate_raw_config(project_root, mutate)
-
-
-def _load_json_strict(path: Path, label: str = "JSON") -> dict:
-    if not path.exists():
-        return {}
-    try:
-        return json.loads(path.read_text(encoding="utf-8")) or {}
-    except json.JSONDecodeError as exc:
-        raise ValueError(f"{path} is not valid JSON. Fix the {label} config before rerunning integration setup.") from exc
-
-
-def _write_opencode_config(project_root: Path) -> Path:
-    path = _opencode_config_path(project_root)
-    data = _load_json_strict(path, "OpenCode")
-    data.setdefault("$schema", "https://opencode.ai/config.json")
-    mcp = data.setdefault("mcp", {})
-    mcp["devcouncil"] = _opencode_mcp_entry(project_root)
-    _save_json(path, data)
-    return path
-
-
-def _write_antigravity_mcp_config(project_root: Path) -> Path:
-    path = _antigravity_mcp_path(project_root)
-    data = _load_json_strict(path, "Antigravity")
-    mcp_servers = data.setdefault("mcpServers", {})
-    mcp_servers["devcouncil"] = _antigravity_mcp_config(project_root)["mcpServers"]["devcouncil"]
-    _save_json(path, data)
-    return path
-
-
-def _configure_cursor(project_root: Path, apply: bool) -> bool:
-    path = _cursor_config_path(project_root)
-    config = _cursor_mcp_config(project_root)
-    if not apply:
-        console.print("[bold]Cursor[/bold]")
-        console.print(f"Project MCP config file: [dim]{path}[/dim]")
-        console.print(json.dumps(config, separators=(",", ":")), soft_wrap=True)
-        console.print("Verify in Cursor CLI with: [dim]cursor-agent mcp list[/dim]")
-        return True
-
-    if not shutil.which("cursor") and not shutil.which("cursor-agent"):
-        console.print("[yellow]Cursor CLI not found on PATH. Project MCP config will still be available to Cursor.[/yellow]")
-    try:
-        written = _write_cursor_config(project_root)
-    except ValueError as exc:
-        console.print(f"[red]{exc}[/red]")
-        return False
-    _record_cursor_config(project_root)
-    console.print(f"[green]Cursor MCP config written:[/green] {written}")
-    return True
-
-
-def _configure_opencode(project_root: Path, apply: bool) -> bool:
-    path = _opencode_config_path(project_root)
-    config = {
-        "$schema": "https://opencode.ai/config.json",
-        "mcp": {"devcouncil": _opencode_mcp_entry(project_root)},
-    }
-    if not apply:
-        console.print("[bold]OpenCode[/bold]")
-        console.print(f"Project config file: [dim]{path}[/dim]")
-        console.print(json.dumps(config, separators=(",", ":")), soft_wrap=True)
-        console.print(
-            "Direct executor command: "
-            "[dim]opencode run --file .devcouncil/TASK-001-opencode-task.md "
-            '"Execute the DevCouncil task described in the attached prompt file."[/dim]'
-        )
-        return True
-
-    if not shutil.which("opencode"):
-        console.print("[yellow]OpenCode CLI not found on PATH. Install it before using `dev run --executor opencode`.[/yellow]")
-    try:
-        written = _write_opencode_config(project_root)
-    except ValueError as exc:
-        console.print(f"[red]{exc}[/red]")
-        return False
-    _record_opencode_config(project_root)
-    console.print(f"[green]OpenCode MCP config written:[/green] {written}")
-    return True
-
-
-def _configure_antigravity(project_root: Path, apply: bool) -> bool:
-    path = _antigravity_mcp_path(project_root)
-    config = _antigravity_mcp_config(project_root)
-    if not apply:
-        console.print("[bold]Google Antigravity CLI[/bold]")
-        console.print(f"Project MCP config file: [dim]{path}[/dim]")
-        console.print(json.dumps(config, separators=(",", ":")), soft_wrap=True)
-        console.print(
-            "Direct executor command: "
-            "[dim]agy --print --print-timeout 30m "
-            '"Read and execute the DevCouncil task prompt at .devcouncil/TASK-001-antigravity-task.md."[/dim]'
-        )
-        return True
-
-    if not shutil.which("agy"):
-        console.print("[yellow]Antigravity CLI (`agy`) not found on PATH. Install it before using `dev run --executor antigravity`.[/yellow]")
-    try:
-        written = _write_antigravity_mcp_config(project_root)
-    except ValueError as exc:
-        console.print(f"[red]{exc}[/red]")
-        return False
-    _record_antigravity_config(project_root)
-    console.print(f"[green]Antigravity MCP config written:[/green] {written}")
-    return True
-
-
-def _configure_warp(project_root: Path, apply: bool) -> bool:
-    path = _warp_mcp_path(project_root)
-    config = _warp_mcp_config(project_root)
-    if not apply:
-        console.print("[bold]Warp / Oz[/bold]")
-        console.print(f"MCP config file: [dim]{path}[/dim]")
-        console.print(json.dumps(config, separators=(",", ":")), soft_wrap=True)
-        console.print(f"Direct executor command: [dim]oz agent run --cwd {project_root} --mcp {path} --prompt <task prompt>[/dim]")
-        return True
-
-    written = _write_warp_mcp_config(project_root)
-    _record_warp_config(project_root)
-    console.print(f"[green]Warp MCP config written:[/green] {written}")
-    if not shutil.which("oz"):
-        console.print("[yellow]oz CLI not found on PATH. Install Warp/Oz before using `dev run --executor warp`.[/yellow]")
-    return True
-
-
-def _format_command(command: list[str]) -> str:
-    if sys.platform == "win32":
-        return " ".join(_quote_powershell_arg(arg) for arg in command)
-    return shlex.join(command)
-
-
-def _quote_powershell_arg(arg: str) -> str:
-    if arg == "":
-        return "''"
-    special_chars = set(" \t\r\n'\"{}[](),;|&<>")
-    if not any(char in special_chars for char in arg):
-        return arg
-    return "'" + arg.replace("'", "''") + "'"
-
-
-def _opencode_plugin_source() -> Path:
-    return Path(__file__).resolve().parents[2] / "integrations" / OPENCODE_HOOK_PLUGIN_NAME
-
-
-def _opencode_plugin_path(project_root: Path) -> Path:
-    return project_root / ".devcouncil" / "integrations" / OPENCODE_HOOK_PLUGIN_NAME
-
-
-def _hook_command(project_root: Path, client: str, event: str) -> str:
-    return _format_command([
-        "devcouncil",
-        "hook",
-        event,
-        "--client",
-        client,
-        "--project-root",
-        str(project_root),
-    ])
-
-
-def _probe_mcp_tools(root: Path, *, timeout_seconds: float = 30.0) -> list[str]:
-    from mcp import ClientSession, StdioServerParameters
-    from mcp.client.stdio import stdio_client
-    import asyncio
-    import os
-
-    async def _list_tools() -> list[str]:
-        env = os.environ.copy()
-        env["DEVCOUNCIL_PROJECT_ROOT"] = str(root)
-        params = StdioServerParameters(
-            command=sys.executable,
-            args=["-m", "devcouncil", "mcp-server"],
-            cwd=str(root),
-            env=env,
-        )
-        async with stdio_client(params) as (read, write):
-            async with ClientSession(read, write) as session:
-                await session.initialize()
-                tools = await session.list_tools()
-                return [tool.name for tool in tools.tools]
-
-    async def _list_tools_with_deadline() -> list[str]:
-        # A wedged server process would otherwise block `dev integrate check`
-        # indefinitely; the caller treats TimeoutError as a failed probe.
-        return await asyncio.wait_for(_list_tools(), timeout=timeout_seconds)
-
-    return asyncio.run(_list_tools_with_deadline())
-
-
-def _run(command: list[str]) -> int:
-    executable = shutil.which(command[0])
-    if not executable:
-        return 127
-    resolved = [executable, *command[1:]]
-    use_shell = sys.platform == "win32" and Path(executable).suffix.lower() in {".bat", ".cmd", ".ps1"}
-    invocation = subprocess.list2cmdline(resolved) if use_shell else resolved
-    try:
-        result = subprocess.run(invocation, text=True, shell=use_shell)
-    except (FileNotFoundError, OSError):
-        return 127
-    return result.returncode
-
-
-def _run_capture(command: list[str], timeout: int = 10) -> tuple[int, str]:
-    executable = shutil.which(command[0])
-    if not executable:
-        return 127, f"{command[0]} not found on PATH"
-
-    resolved = [executable, *command[1:]]
-    use_shell = sys.platform == "win32" and Path(executable).suffix.lower() in {".bat", ".cmd", ".ps1"}
-    invocation = subprocess.list2cmdline(resolved) if use_shell else resolved
-    try:
-        result = subprocess.run(
-            invocation,
-            capture_output=True,
-            text=True,
-            encoding="utf-8",
-            errors="replace",
-            shell=use_shell,
-            timeout=timeout,
-            env=clean_subprocess_env(),
-        )
-    except subprocess.TimeoutExpired:
-        return 124, "timed out"
-    except (FileNotFoundError, OSError) as exc:
-        return 127, f"{command[0]} could not be executed: {exc}"
-    return result.returncode, (result.stdout + result.stderr).strip()
-
-
-def _config_path(project_root: Path) -> Path:
-    return project_root / ".devcouncil" / "config.yaml"
-
-
-def _load_raw_config(project_root: Path) -> dict:
-    path = _config_path(project_root)
-    if not path.exists():
-        return {}
-    return yaml.safe_load(path.read_text(encoding="utf-8")) or {}
-
-
-def _save_raw_config(project_root: Path, config: dict) -> None:
-    path = _config_path(project_root)
-    path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(yaml.safe_dump(config, sort_keys=False), encoding="utf-8")
-
-
-def _load_json(path: Path) -> dict:
-    if not path.exists():
-        return {}
-    try:
-        return json.loads(path.read_text(encoding="utf-8")) or {}
-    except json.JSONDecodeError:
-        return {}
-
-
-def _save_json(path: Path, data: dict) -> None:
-    path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
-
-
-def _upsert_hook(settings: dict, event: str, matcher: str, command: str, name: str) -> None:
-    hooks = settings.setdefault("hooks", {})
-    groups = hooks.setdefault(event, [])
-    for group in groups:
-        if group.get("matcher") == matcher:
-            group_hooks = group.setdefault("hooks", [])
-            if not any(hook.get("command") == command for hook in group_hooks):
-                group_hooks.append({
-                    "type": "command",
-                    "name": name,
-                    "command": command,
-                    "timeout": 10000,
-                })
-            return
-    groups.append({
-        "matcher": matcher,
-        "hooks": [{
-            "type": "command",
-            "name": name,
-            "command": command,
-            "timeout": 10000,
-        }],
-    })
-
-
-def _ensure_codex_hooks_enabled(project_root: Path) -> Path:
-    config_path = project_root / ".codex" / "config.toml"
-    config_path.parent.mkdir(parents=True, exist_ok=True)
-    existing = config_path.read_text(encoding="utf-8") if config_path.exists() else ""
-    if "codex_hooks" not in existing:
-        if "[features]" in existing:
-            lines = existing.splitlines()
-            updated: list[str] = []
-            in_features = False
-            inserted = False
-            for line in lines:
-                stripped = line.strip()
-                if stripped == "[features]":
-                    in_features = True
-                    updated.append(line)
-                    continue
-                if in_features and stripped.startswith("[") and stripped.endswith("]"):
-                    updated.append("codex_hooks = true")
-                    inserted = True
-                    in_features = False
-                updated.append(line)
-            if in_features and not inserted:
-                updated.append("codex_hooks = true")
-            config_path.write_text("\n".join(updated) + "\n", encoding="utf-8")
-        else:
-            separator = "\n" if existing and not existing.endswith("\n") else ""
-            config_path.write_text(f"{existing}{separator}\n[features]\ncodex_hooks = true\n", encoding="utf-8")
-    return config_path
-
-
-def _install_codex_hooks(project_root: Path) -> list[Path]:
-    path = project_root / ".codex" / "hooks.json"
-    settings = _load_json(path)
-    matcher = "Bash|shell_command|exec_command|local_shell|Write|Edit|MultiEdit|write_file|edit_file|apply_patch"
-    _upsert_hook(
-        settings,
-        "PreToolUse",
-        matcher,
-        _hook_command(project_root, "codex", "pre-tool-use"),
-        "devcouncil-pre-tool-use",
-    )
-    _upsert_hook(
-        settings,
-        "PostToolUse",
-        matcher,
-        _hook_command(project_root, "codex", "post-tool-use"),
-        "devcouncil-post-tool-use",
-    )
-    _save_json(path, settings)
-    return [path, _ensure_codex_hooks_enabled(project_root)]
-
-
-def _install_gemini_hooks(project_root: Path) -> list[Path]:
-    path = project_root / ".gemini" / "settings.json"
-    settings = _load_json(path)
-    matcher = "run_shell_command|shell_command|write_file|edit_file|replace|apply_patch"
-    _upsert_hook(
-        settings,
-        "BeforeTool",
-        matcher,
-        _hook_command(project_root, "gemini", "pre-tool-use"),
-        "devcouncil-pre-tool-use",
-    )
-    _upsert_hook(
-        settings,
-        "AfterTool",
-        matcher,
-        _hook_command(project_root, "gemini", "post-tool-use"),
-        "devcouncil-post-tool-use",
-    )
-    _save_json(path, settings)
-    return [path]
-
-
-def _upsert_cursor_hook(settings: dict, event: str, matcher: str, command: str) -> None:
-    hooks = settings.setdefault("hooks", {})
-    entries = hooks.setdefault(event, [])
-    for entry in entries:
-        if entry.get("command") == command:
-            return
-    payload: dict = {"command": command}
-    if matcher:
-        payload["matcher"] = matcher
-    entries.append(payload)
-
-
-def _install_cursor_hooks(project_root: Path) -> list[Path]:
-    path = project_root / ".cursor" / "hooks.json"
-    settings = _load_json(path)
-    settings.setdefault("version", 1)
-    matcher = "Shell|Write|Edit|MultiEdit|Read|Task"
-    _upsert_cursor_hook(
-        settings,
-        "preToolUse",
-        matcher,
-        _hook_command(project_root, "cursor", "pre-tool-use"),
-    )
-    _upsert_cursor_hook(
-        settings,
-        "postToolUse",
-        matcher,
-        _hook_command(project_root, "cursor", "post-tool-use"),
-    )
-    _save_json(path, settings)
-
-    def mutate(config: dict) -> None:
-        cursor = config.setdefault("integrations", {}).setdefault("cursor", {})
-        cursor.update({
-            "hooks_path": str(path.relative_to(project_root)),
-        })
-
-    _mutate_raw_config(project_root, mutate)
-    return [path]
-
-
-def _install_opencode_hooks(project_root: Path) -> list[Path]:
-    source = _opencode_plugin_source()
-    if not source.exists():
-        raise FileNotFoundError(f"Missing bundled OpenCode hook plugin: {source}")
-    destination = _opencode_plugin_path(project_root)
-    destination.parent.mkdir(parents=True, exist_ok=True)
-    destination.write_text(source.read_text(encoding="utf-8"), encoding="utf-8")
-
-    path = _opencode_config_path(project_root)
-    data = _load_json_strict(path, "OpenCode") if path.exists() else {"$schema": "https://opencode.ai/config.json"}
-    data.setdefault("$schema", "https://opencode.ai/config.json")
-    plugins_raw = data.setdefault("plugin", [])
-    if not isinstance(plugins_raw, list):
-        plugins_raw = []
-        data["plugin"] = plugins_raw
-    plugins: list[str] = [str(item) for item in plugins_raw]
-    data["plugin"] = plugins
-    plugin_ref = f"./.devcouncil/integrations/{OPENCODE_HOOK_PLUGIN_NAME}"
-    if plugin_ref not in plugins:
-        plugins.append(plugin_ref)
-    _save_json(path, data)
-    _record_opencode_config(project_root)
-    return [destination, path]
-
-
-def _install_claude_hooks(project_root: Path, *, write_gate: bool = False) -> list[Path]:
-    """Install DevCouncil's Claude Code hooks into .claude/settings.local.json.
-
-    By default this installs only the *assistive* lifecycle hooks (status injection on
-    SessionStart/UserPromptSubmit, the live-review Stop signal, and the SessionEnd/
-    PreCompact/SubagentStop/Notification trace hooks). These never block a tool call.
-
-    The blocking pre-action **write-gate** (PreToolUse/PostToolUse, which denies any
-    Bash/Write/Edit not authorized by an active task lease) is installed ONLY when
-    ``write_gate`` is True. It is meant for autonomous executor runs, not interactive
-    human sessions — in an interactive session there is no task lease, so the gate would
-    fail-closed and deny every command. (``dev run --executor claude`` does its own
-    post-hoc scope enforcement and does not depend on this hook, so leaving it off by
-    default loses no containment.)"""
-    path = project_root / ".claude" / "settings.local.json"
-    settings = _load_json(path)
-    matcher = "Bash|Write|Edit|MultiEdit"
-    if write_gate:
-        _upsert_hook(
-            settings,
-            "PreToolUse",
-            matcher,
-            _hook_command(project_root, "claude", "pre-tool-use"),
-            "devcouncil-pre-tool-use",
-        )
-        _upsert_hook(
-            settings,
-            "PostToolUse",
-            matcher,
-            _hook_command(project_root, "claude", "post-tool-use"),
-            "devcouncil-post-tool-use",
-        )
-    _upsert_hook(
-        settings,
-        "Stop",
-        "",
-        _hook_command(project_root, "claude", "agent-response"),
-        "devcouncil-agent-response-ready",
-    )
-    # Lifecycle events: status-on-start/prompt, teardown, compaction, subagent finish,
-    # and notifications. These complete DevCouncil's coverage of the documented Claude
-    # Code hook surface beyond the pre/post/stop gate.
-    _upsert_hook(
-        settings,
-        "SessionStart",
-        "startup|resume",
-        _hook_command(project_root, "claude", "session-start"),
-        "devcouncil-session-start",
-    )
-    _upsert_hook(
-        settings,
-        "UserPromptSubmit",
-        "",
-        _hook_command(project_root, "claude", "user-prompt-submit"),
-        "devcouncil-user-prompt-submit",
-    )
-    _upsert_hook(
-        settings,
-        "SessionEnd",
-        "",
-        _hook_command(project_root, "claude", "session-end"),
-        "devcouncil-session-end",
-    )
-    _upsert_hook(
-        settings,
-        "PreCompact",
-        "",
-        _hook_command(project_root, "claude", "pre-compact"),
-        "devcouncil-pre-compact",
-    )
-    _upsert_hook(
-        settings,
-        "SubagentStop",
-        "",
-        _hook_command(project_root, "claude", "subagent-stop"),
-        "devcouncil-subagent-stop",
-    )
-    _upsert_hook(
-        settings,
-        "Notification",
-        "",
-        _hook_command(project_root, "claude", "notification"),
-        "devcouncil-notification",
-    )
-    _save_json(path, settings)
-    return [path]
-
-
-def _devcouncil_version() -> str:
-    """Package version for plugin manifests, or a stable placeholder when uninstalled."""
-    import importlib.metadata
-
-    try:
-        return importlib.metadata.version("devcouncil")
-    except importlib.metadata.PackageNotFoundError:
-        return "0.0.0"
-
-
-# Read-only DevCouncil commands the generated slash commands / hooks shell out to. Adding
-# them to the Claude permissions allow-list keeps the integration from prompting on every
-# `dev status`/`dev report` the slash commands run.
-_CLAUDE_PERMISSION_ALLOW = [
-    "Bash(dev status:*)",
-    "Bash(dev report:*)",
-    "Bash(dev tasks:*)",
-    "Bash(dev verify:*)",
-    "Bash(dev repair:*)",
-    "Bash(dev plan:*)",
-    "Bash(dev watch:*)",
-    "Bash(devcouncil mcp-server)",
-]
-
-
-def _install_claude_settings(project_root: Path) -> tuple[Path, bool]:
-    """Write the statusLine, MCP enablement, and permission allow-list into Claude settings.
-
-    Merges into .claude/settings.local.json without clobbering existing user entries.
-    Returns (path, changed); only rewrites the file when the merge changes something so
-    re-running integration is a true no-op."""
-    path = project_root / ".claude" / "settings.local.json"
-    settings = _load_json(path)
-    before = json.dumps(settings, sort_keys=True)
-
-    settings["statusLine"] = {
-        "type": "command",
-        "command": "devcouncil hook claude-statusline",
-    }
-    # Auto-enable the project-scoped DevCouncil MCP server so a teammate cloning the repo
-    # doesn't have to approve it interactively.
-    enabled = settings.setdefault("enabledMcpjsonServers", [])
-    if isinstance(enabled, list) and "devcouncil" not in enabled:
-        enabled.append("devcouncil")
-
-    permissions = settings.setdefault("permissions", {})
-    if isinstance(permissions, dict):
-        allow = permissions.setdefault("allow", [])
-        if isinstance(allow, list):
-            for rule in _CLAUDE_PERMISSION_ALLOW:
-                if rule not in allow:
-                    allow.append(rule)
-
-    changed = json.dumps(settings, sort_keys=True) != before
-    if changed:
-        _save_json(path, settings)
-    return path, changed
-
-
-def _selected_skill_assets(project_root: Path):
-    """Scaffold the applicable skills and return them as GeneratedAsset-like records.
-
-    Returns (written_paths, skill_assets) where skill_assets carry (path, content) for the
-    plugin bundler so the plugin ships the same skill bodies that land in .claude/skills/."""
-    from devcouncil.integrations.claude_assets import GeneratedAsset
-    from devcouncil.skills.registry import scaffold_skills, select_skills
-
-    skills = select_skills("", project_root)
-    written = scaffold_skills(project_root, skills)
-    assets: list[GeneratedAsset] = []
-    skills_root = project_root / ".claude" / "skills"
-    for skill in skills:
-        target = skills_root / skill.name / "SKILL.md"
-        if target.exists():
-            assets.append(GeneratedAsset(target, target.read_text(encoding="utf-8")))
-    return written, assets
-
-
-def _install_claude_assets(project_root: Path) -> list[Path]:
-    """Generate the static Claude Code asset surface (commands, agents, output style,
-    statusline, permissions) and scaffold the applicable skills. Idempotent."""
-    from devcouncil.integrations import claude_assets
-
-    written: list[Path] = []
-    assets: list[claude_assets.GeneratedAsset] = []
-    assets += claude_assets.build_slash_commands(project_root)
-    assets += claude_assets.build_subagents(project_root)
-    assets += claude_assets.build_output_style(project_root)
-    for asset in assets:
-        if asset.write_if_changed():
-            written.append(asset.path)
-
-    skills_written, _ = _selected_skill_assets(project_root)
-    written.extend(skills_written)
-    settings_path, settings_changed = _install_claude_settings(project_root)
-    if settings_changed:
-        written.append(settings_path)
-    return written
-
-
-def _install_claude_plugin(project_root: Path, *, write_gate: bool = False) -> list[Path]:
-    """Build the self-contained Claude Code plugin + single-repo marketplace bundle.
-
-    Bundles the commands, agents, applicable skills, hooks, and MCP config so the entire
-    DevCouncil integration installs with one `/plugin install`. Assist-mode hooks by
-    default; pass write_gate=True to bundle the blocking containment gate."""
-    from devcouncil.integrations import claude_assets
-
-    _, skill_assets = _selected_skill_assets(project_root)
-    bundle = claude_assets.build_plugin_bundle(
-        project_root, version=_devcouncil_version(), skill_assets=skill_assets, write_gate=write_gate
-    )
-    return [asset.path for asset in bundle if asset.write_if_changed()]
-
-
-def _uninstall_claude(project_root: Path) -> list[str]:
-    """Remove everything DevCouncil installed into a Claude Code project. Idempotent.
-
-    Strips DevCouncil's hooks (every event), the DevCouncil statusLine, the MCP enablement
-    and permission rules from .claude/settings.local.json (leaving any user-authored
-    entries untouched), deletes the generated commands/subagents/output-style files, and
-    best-effort de-registers the MCP server via `claude mcp remove`. Returns a list of the
-    changes made. The recoverable, in-band counterpart to a fail-closed write-gate."""
-    removed: list[str] = []
-    path = project_root / ".claude" / "settings.local.json"
-    settings = _load_json(path)
-    before = json.dumps(settings, sort_keys=True)
-
-    # Hooks: drop any entry whose command invokes `devcouncil hook`, then prune empties.
-    hooks = settings.get("hooks")
-    if isinstance(hooks, dict):
-        for event in list(hooks):
-            groups = hooks.get(event)
-            if not isinstance(groups, list):
-                continue
-            kept_groups = []
-            for group in groups:
-                inner = group.get("hooks", []) if isinstance(group, dict) else []
-                inner_kept = [
-                    h for h in inner
-                    if "devcouncil hook" not in str(h.get("command", ""))
-                ]
-                if inner_kept:
-                    group["hooks"] = inner_kept
-                    kept_groups.append(group)
-            if kept_groups:
-                hooks[event] = kept_groups
-            else:
-                hooks.pop(event)
-        if not hooks:
-            settings.pop("hooks")
-        removed.append(f"hooks in {path.name}")
-
-    # statusLine: only remove ours.
-    status = settings.get("statusLine")
-    if isinstance(status, dict) and "devcouncil" in str(status.get("command", "")):
-        settings.pop("statusLine")
-        removed.append("statusLine")
-
-    enabled = settings.get("enabledMcpjsonServers")
-    if isinstance(enabled, list) and "devcouncil" in enabled:
-        enabled.remove("devcouncil")
-        if not enabled:
-            settings.pop("enabledMcpjsonServers")
-        removed.append("enabledMcpjsonServers entry")
-
-    permissions = settings.get("permissions")
-    if isinstance(permissions, dict) and isinstance(permissions.get("allow"), list):
-        kept = [r for r in permissions["allow"] if r not in _CLAUDE_PERMISSION_ALLOW]
-        if len(kept) != len(permissions["allow"]):
-            permissions["allow"] = kept
-            removed.append("permission allow-rules")
-        if not permissions.get("allow"):
-            permissions.pop("allow", None)
-        if not permissions:
-            settings.pop("permissions")
-
-    if json.dumps(settings, sort_keys=True) != before:
-        if settings:
-            _save_json(path, settings)
-        elif path.exists():
-            path.unlink()
-            removed.append(f"deleted empty {path.name}")
-
-    # Generated asset files.
-    targets = [
-        project_root / ".claude" / "commands" / "devcouncil",
-        project_root / ".claude" / "output-styles" / "devcouncil.md",
-    ]
-    targets += [
-        project_root / ".claude" / "agents" / f"{name}.md"
-        for name in ("devcouncil-implementer", "devcouncil-verifier", "devcouncil-reviewer")
-    ]
-    for target in targets:
-        if target.is_dir():
-            shutil.rmtree(target)
-            removed.append(str(target.relative_to(project_root)))
-        elif target.exists():
-            target.unlink()
-            removed.append(str(target.relative_to(project_root)))
-
-    # De-register the MCP server (best-effort; only if the claude CLI is present).
-    if shutil.which("claude"):
-        code = _run(["claude", "mcp", "remove", "devcouncil"])
-        if code == 0:
-            removed.append("claude mcp server registration")
-
-    return removed
-
-
-def _preview_hook_paths(project_root: Path, tool: str) -> list[tuple[str, Path]]:
-    paths = {
-        "codex": [project_root / ".codex" / "hooks.json", project_root / ".codex" / "config.toml"],
-        "gemini": [project_root / ".gemini" / "settings.json"],
-        "claude": [project_root / ".claude" / "settings.local.json"],
-        "cursor": [project_root / ".cursor" / "hooks.json"],
-        "opencode": [_opencode_plugin_path(project_root), _opencode_config_path(project_root)],
-    }
-    selected: tuple[str, ...]
-    if tool == "all":
-        selected = (*SUPPORTED_HOOK_TOOLS, "opencode")
-    elif tool == "opencode":
-        selected = ("opencode",)
-    else:
-        selected = (tool,)
-    return [(client, path) for client in selected for path in paths.get(client, [])]
-
-
-def _configure_native_hooks(
-    project_root: Path, tool: str = "all", apply: bool = False, *, claude_write_gate: bool = False
-) -> None:
-    allowed = {"all", *SUPPORTED_HOOK_TOOLS, "opencode"}
-    if tool not in allowed:
-        console.print("[red]--tool must be one of: all, codex, gemini, claude, cursor, opencode.[/red]")
-        raise typer.Exit(code=2)
-
-    if not apply:
-        console.print("[bold]Native hook config preview[/bold]")
-        for client, path in _preview_hook_paths(project_root, tool):
-            console.print(f"{client}: {path}", soft_wrap=True)
-        console.print("[yellow]Preview only. Rerun with --apply to write hook config files.[/yellow]")
-        return
-
-    selected: tuple[str, ...]
-    if tool == "all":
-        selected = (*SUPPORTED_HOOK_TOOLS, "opencode")
-    elif tool == "opencode":
-        selected = ("opencode",)
-    else:
-        selected = (tool,)
-    installers = {
-        "codex": _install_codex_hooks,
-        "gemini": _install_gemini_hooks,
-        # Claude's blocking write-gate is opt-in (assist-mode default); the other clients
-        # install their native pre/post hooks unconditionally as before.
-        "claude": lambda root: _install_claude_hooks(root, write_gate=claude_write_gate),
-        "cursor": _install_cursor_hooks,
-        "opencode": _install_opencode_hooks,
-    }
-    # Batch the per-installer config.yaml record updates (cursor/opencode)
-    # into one load/save instead of re-parsing YAML per tool.
-    with _batched_raw_config(project_root):
-        for client in selected:
-            try:
-                written = installers[client](project_root)
-            except (ValueError, FileNotFoundError) as exc:
-                console.print(f"[red]{client} hook setup failed: {exc}[/red]")
-                raise typer.Exit(code=1) from exc
-            console.print(f"[green]{client} native hooks configured:[/green] {', '.join(str(path) for path in written)}")
-
-
-def _print_command(tool: str, command: list[str], apply: bool):
-    if apply:
-        console.print(f"[cyan]Configuring {tool} MCP integration...[/cyan]")
-    else:
-        console.print(f"[bold]{tool}[/bold]")
-        console.print(_format_command(command), soft_wrap=True)
-
-
-def _configure(tool: str, command: list[str], apply: bool) -> bool:
-    executable = command[0]
-    if not shutil.which(executable):
-        console.print(f"[yellow]{tool} CLI not found on PATH. Install it first, then rerun this command.[/yellow]")
-        console.print(_format_command(command), soft_wrap=True)
-        return False
-
-    _print_command(tool, command, apply)
-    if not apply:
-        return True
-
-    code = _run(command)
-    if code == 0:
-        console.print(f"[green]{tool} integration configured.[/green]")
-        return True
-
-    console.print(f"[red]{tool} integration command failed with exit code {code}.[/red]")
-    console.print("You can rerun it manually:")
-    console.print(_format_command(command), soft_wrap=True)
-    return False
+# Back-compat re-exports for tests and apply_integration_target
+_project_root = common._project_root
+_warn_if_verify_only = common._warn_if_verify_only
+_server_args = common._server_args
+_codex_command = codex_client._codex_command
+_gemini_command = gemini_client._gemini_command
+_claude_command = claude_client._claude_command
+_cursor_config_path = cursor_client._cursor_config_path
+_configure_cursor = cursor_client._configure_cursor
+_configure_grok = grok_client._configure_grok
+_configure_opencode = opencode_client._configure_opencode
+_configure_antigravity = antigravity_client._configure_antigravity
+_configure_warp = warp_client._configure_warp
+_configure_aider = aider_client._configure_aider
+_write_cursor_config = cursor_client._write_cursor_config
+_grok_config_path = grok_client._grok_config_path
+_write_opencode_config = opencode_client._write_opencode_config
+_write_antigravity_mcp_config = antigravity_client._write_antigravity_mcp_config
+_write_warp_mcp_config = warp_client._write_warp_mcp_config
+_record_cursor_config = cursor_client._record_cursor_config
+_record_grok_config = grok_client._record_grok_config
+_record_claude_config = claude_client._record_claude_config
+_record_opencode_config = opencode_client._record_opencode_config
+_record_antigravity_config = antigravity_client._record_antigravity_config
+_record_warp_config = warp_client._record_warp_config
+_record_aider_config = aider_client._record_aider_config
+_batched_raw_config = common._batched_raw_config
+_mutate_raw_config = common._mutate_raw_config
+_load_raw_config = common._load_raw_config
+_save_raw_config = common._save_raw_config
+_config_path = common._config_path
+_load_json = common._load_json
+_save_json = common._save_json
+_format_command = common._format_command
+_configure = common._configure
+_run = common._run
+_run_capture = common._run_capture
+_probe_mcp_tools = common._probe_mcp_tools
+_cursor_mcp_config = cursor_client._cursor_mcp_config
+_opencode_plugin_source = opencode_client._opencode_plugin_source
+_install_claude_hooks = hooks_client._install_claude_hooks
+_install_codex_hooks = hooks_client._install_codex_hooks
+_install_claude_assets = claude_client._install_claude_assets
+_install_claude_plugin = claude_client._install_claude_plugin
+_uninstall_claude = claude_client._uninstall_claude
+_configure_native_hooks = hooks_client._configure_native_hooks
+_opencode_config_path = opencode_client._opencode_config_path
+_opencode_plugin_path = opencode_client._opencode_plugin_path
 
 
 @app.callback(invoke_without_command=True)
@@ -1094,31 +112,40 @@ def overview(ctx: typer.Context):
     if ctx.invoked_subcommand is not None:
         return
 
-    table = Table(title="DevCouncil Coding CLI Integrations")
-    table.add_column("Tool", style="cyan")
-    table.add_column("Setup command", style="green")
-    table.add_column("Notes")
-    table.add_row("Codex CLI", f"{PREFERRED_COMMAND} codex --apply", "Adds DevCouncil as a stdio MCP server.")
-    table.add_row("Gemini CLI", f"{PREFERRED_COMMAND} gemini --apply", "Adds DevCouncil as a project-scoped stdio MCP server.")
-    table.add_row("Claude Code", f"{PREFERRED_COMMAND} claude --apply", "MCP + assistive hooks + slash commands, subagents, output style, skills, statusline. Add --write-gate for blocking containment.")
-    table.add_row("Claude assets", f"{PREFERRED_COMMAND} claude-assets --apply", "Slash commands, subagents, output style, statusline, permissions, skills (no MCP/hooks).")
-    table.add_row("Claude plugin", f"{PREFERRED_COMMAND} claude-plugin --apply", "Self-contained Claude Code plugin + marketplace bundling everything for /plugin install.")
-    table.add_row("Claude uninstall", f"{PREFERRED_COMMAND} claude --uninstall", "Remove DevCouncil hooks, statusline, MCP enablement, and generated assets from .claude/.")
-    table.add_row("Cursor", f"{PREFERRED_COMMAND} cursor --apply", "Writes project .cursor/mcp.json for Cursor editor and cursor-agent.")
-    table.add_row("OpenCode", f"{PREFERRED_COMMAND} opencode --apply", "Adds DevCouncil as a project-scoped OpenCode MCP server and executor.")
-    table.add_row("Google Antigravity CLI", f"{PREFERRED_COMMAND} antigravity --apply", "Writes project .agents/mcp_config.json and enables the agy executor.")
-    table.add_row("Warp / Oz", f"{PREFERRED_COMMAND} warp --apply", "Writes a Warp-compatible MCP JSON file for local agents and Oz CLI.")
-    table.add_row("Aider", f"{PREFERRED_COMMAND} aider --apply", "Enables the built-in Aider headless executor (no MCP).")
-    table.add_row("Bring your own CLI", f"{PREFERRED_COMMAND} cli-agent NAME --command TOOL --apply", "Registers any prompt-taking CLI as a DevCouncil executor.")
-    table.add_row("All", f"{PREFERRED_COMMAND} all --apply", "Runs MCP setup and installs native hooks.")
-    table.add_row("Native hooks", f"{PREFERRED_COMMAND} hooks --apply", "Installs Codex, Gemini, Claude, Cursor, and OpenCode hook files.")
-    table.add_row("Recommend", f"{PREFERRED_COMMAND} recommend", "Show the best executor for this machine and project.")
-    table.add_row("Status", f"{PREFERRED_COMMAND} status", "Compact PATH + config summary (no MCP probe).")
-    table.add_row("Matrix", f"{PREFERRED_COMMAND} matrix", "Print built-in coding CLI integration tiers.")
-    table.add_row("Check", f"{PREFERRED_COMMAND} check", "Verify MCP, hooks, and optional CLIs (--strict, --json for CI).")
-    console.print(table)
-    console.print(f"\nIf your install exposes only the setup flow, use: {LEGACY_COMMAND} --apply")
-    console.print("\nRun without [bold]--apply[/bold] to preview the exact commands first.")
+    logger.info("dev integrate: overview")
+    with log_stage("integrate", subcommand="overview"):
+        log_step("integrate/1: listing integration options", trace=True)
+        table = Table(title="DevCouncil Coding CLI Integrations")
+        table.add_column("Tool", style="cyan")
+        table.add_column("Setup command", style="green")
+        table.add_column("Notes")
+        table.add_row("Claude Code", f"{PREFERRED_COMMAND} claude --apply", "MCP + assistive hooks + slash commands, subagents, output style, skills, statusline. Add --write-gate for blocking containment.")
+        table.add_row("Codex CLI", f"{PREFERRED_COMMAND} codex --apply", "MCP + native lifecycle hooks. Review project hooks with /hooks after setup.")
+        table.add_row("Gemini CLI (deprecated)", f"{PREFERRED_COMMAND} gemini --apply", "Deprecated — use dev integrate antigravity --apply instead.")
+        table.add_row("Claude assets", f"{PREFERRED_COMMAND} claude-assets --apply", "Slash commands, subagents, output style, statusline, permissions, skills (no MCP/hooks).")
+        table.add_row("Claude plugin", f"{PREFERRED_COMMAND} claude-plugin --apply", "Self-contained Claude Code plugin + marketplace bundling everything for /plugin install.")
+        table.add_row("Claude uninstall", f"{PREFERRED_COMMAND} claude --uninstall", "Remove DevCouncil hooks, statusline, MCP enablement, and generated assets from .claude/.")
+        table.add_row("Cursor", f"{PREFERRED_COMMAND} cursor --apply", "Writes project .cursor/mcp.json for Cursor editor and agent/cursor-agent.")
+        table.add_row("Grok Build", f"{PREFERRED_COMMAND} grok --apply", "Registers DevCouncil MCP via grok mcp add or .grok/config.toml fallback.")
+        table.add_row("OpenCode", f"{PREFERRED_COMMAND} opencode --apply", "Adds DevCouncil as a project-scoped OpenCode MCP server and executor.")
+        table.add_row("Google Antigravity CLI", f"{PREFERRED_COMMAND} antigravity --apply", "Writes project .agents/mcp_config.json and enables the agy executor.")
+        table.add_row("Warp / Oz", f"{PREFERRED_COMMAND} warp --apply", "Writes a Warp-compatible MCP JSON file for local agents and Oz CLI.")
+        table.add_row("Aider", f"{PREFERRED_COMMAND} aider --apply", "Enables the built-in Aider headless executor (no MCP).")
+        table.add_row("Bring your own CLI", f"{PREFERRED_COMMAND} cli-agent NAME --command TOOL --apply", "Registers any prompt-taking CLI as a DevCouncil executor.")
+        table.add_row("All", f"{PREFERRED_COMMAND} all --apply", "Runs MCP setup and installs native hooks.")
+        table.add_row("Native hooks", f"{PREFERRED_COMMAND} hooks --apply", "Installs Codex, Claude, Cursor, Grok, and OpenCode hook files.")
+        table.add_row("Recommend", f"{PREFERRED_COMMAND} recommend", "Show the best executor for this machine and project.")
+        table.add_row("Status", f"{PREFERRED_COMMAND} status", "Compact PATH + config summary (no MCP probe).")
+        table.add_row("Matrix", f"{PREFERRED_COMMAND} matrix", "Print built-in coding CLI integration tiers.")
+        table.add_row(
+            "Check",
+            f"{PREFERRED_COMMAND} check",
+            "Verify MCP, hooks, and integrations (--strict fails on real defects; optional coding CLIs stay warnings).",
+        )
+        console.print(table)
+        console.print(f"\nIf your install exposes only the setup flow, use: {LEGACY_COMMAND} --apply")
+        console.print("\nRun without [bold]--apply[/bold] to preview the exact commands first.")
+        log_step("integrate/complete", trace=True)
 
 
 @app.command("doctor")
@@ -1127,51 +154,7 @@ def integrations_doctor(
 ):
     """Check optional integration tools and local client wiring prerequisites."""
     root = _project_root(project_root)
-    table = Table(title="DevCouncil Integration Doctor")
-    table.add_column("Integration", style="cyan", no_wrap=True)
-    table.add_column("Status")
-    table.add_column("Notes", overflow="fold")
-
-    checks = [
-        ("Agent Flow", "agent-flow-app", "Optional live/replay visualizer for trace JSONL."),
-        ("code-review-graph", "code-review-graph", "Optional structural graph context adapter."),
-        ("Claude Code", "claude", "Optional MCP client and native hook runtime for pre-tool-use enforcement."),
-        ("Codex CLI", "codex", "Optional MCP client, headless executor companion, and native hook runtime."),
-        ("Gemini CLI", "gemini", "Optional MCP client companion and native hook runtime."),
-        ("Cursor", "cursor-agent", "Optional MCP client, cursor-agent executor, and native hooks."),
-        ("OpenCode", "opencode", "Optional MCP client and headless coding-agent executor."),
-        ("Google Antigravity CLI", "agy", "Optional Antigravity CLI companion and headless coding-agent executor."),
-        ("Warp / Oz", "oz", "Optional Warp/Oz CLI companion and agent executor."),
-        ("Aider", "aider", "Optional headless executor via `dev run --executor aider` (no MCP)."),
-    ]
-    for label, executable, notes in checks:
-        found = shutil.which(executable)
-        table.add_row(label, "[green]OK[/green]" if found else "[yellow]Missing[/yellow]", found or notes)
-
-    profiles = load_agent_profiles(root)
-    for name, spec in load_cli_agent_specs(root).items():
-        if spec.built_in:
-            continue
-        found = shutil.which(spec.executable)
-        mode_ok = spec.input_mode in VALID_INPUT_MODES
-        profile_ok = spec.default_profile in profiles
-        status = "[green]OK[/green]" if found and mode_ok and profile_ok else "[red]Invalid[/red]"
-        if not found:
-            status = "[yellow]Missing[/yellow]"
-        details = found or f"{spec.executable} not found on PATH"
-        if not mode_ok:
-            details = f"invalid input_mode={spec.input_mode}"
-        if not profile_ok:
-            details = f"{details}; missing profile={spec.default_profile}"
-        table.add_row(f"CLI agent: {name}", status, details)
-
-    config = _config_path(root)
-    table.add_row(
-        "DevCouncil config",
-        "[green]OK[/green]" if config.exists() else "[red]Missing[/red]",
-        str(config) if config.exists() else "Run dev init first.",
-    )
-    console.print(table)
+    console.print(build_integrations_doctor_table(root))
 
 
 @app.command("codex")
@@ -1180,11 +163,22 @@ def codex(
     project_root: Path | None = typer.Option(None, "--project-root", help="Repository root containing .devcouncil/."),
 ):
     """
-    Set up DevCouncil MCP tools for Codex CLI.
+    Set up DevCouncil MCP tools and native lifecycle hooks for Codex CLI.
     """
     root = _project_root(project_root)
     command = _codex_command(root)
     ok = _configure("Codex CLI", command, apply)
+    if apply and ok:
+        try:
+            written = _install_codex_hooks(root)
+            common.record_hook_dev_executable(root)
+        except (ValueError, FileNotFoundError, OSError) as exc:
+            console.print(f"[red]Codex hook setup failed: {exc}[/red]")
+            raise typer.Exit(code=1) from exc
+        console.print(
+            f"[green]Codex integration installed[/green] ({len(written)} hook/config file(s)): MCP + native hooks."
+        )
+        console.print("[yellow]Open Codex in this project and run /hooks to review and trust the generated hooks.[/yellow]")
     if not ok and apply:
         raise typer.Exit(code=1)
 
@@ -1203,8 +197,9 @@ def gemini(
         raise typer.Exit(code=2)
 
     root = _project_root(project_root)
+    console.print(f"[yellow]{GEMINI_DEPRECATION_MESSAGE}[/yellow]")
     command = _gemini_command(root, scope)
-    ok = _configure("Gemini CLI", command, apply)
+    ok = _configure("Gemini CLI (deprecated)", command, apply)
     if not ok and apply:
         raise typer.Exit(code=1)
 
@@ -1256,6 +251,7 @@ def claude(
         try:
             written = _install_claude_hooks(root, write_gate=write_gate)
             written += _install_claude_assets(root)
+            _record_claude_config(root, scope=scope, write_gate=write_gate)
         except (ValueError, FileNotFoundError, OSError) as exc:
             console.print(f"[red]Claude asset setup failed: {exc}[/red]")
             raise typer.Exit(code=1) from exc
@@ -1356,6 +352,37 @@ def claude_plugin_cmd(
     console.print("  [dim]/plugin install devcouncil@devcouncil-local[/dim]")
 
 
+@app.command("claude-github")
+def claude_github(
+    apply: bool = typer.Option(False, "--apply", help="Write the workflow file instead of previewing it."),
+    project_root: Path | None = typer.Option(None, "--project-root", help="Repository root containing .devcouncil/."),
+):
+    """
+    Generate a GitHub Actions workflow that runs DevCouncil + Claude Code on repo events.
+
+    Read-only DevCouncil verification on pull requests, and gated autonomous task pickup via
+    headless Claude Code on manual dispatch or a nightly schedule. This is the stable-primitive
+    alternative to Claude Code's experimental cloud Routines; the autonomous job needs an
+    ANTHROPIC_API_KEY repository secret.
+    """
+    from devcouncil.integrations.claude_assets import build_github_workflow
+
+    root = _project_root(project_root)
+    asset = build_github_workflow(root)
+    if not apply:
+        console.print("[bold]DevCouncil GitHub Actions workflow (preview)[/bold]")
+        console.print(f"Would write: [dim]{asset.path}[/dim]")
+        console.print("[yellow]Preview only. Rerun with --apply to write the workflow.[/yellow]")
+        return
+    changed = asset.write_if_changed()
+    rel = asset.path.relative_to(root)
+    if changed:
+        console.print(f"[green]Wrote GitHub Actions workflow[/green] at {rel}")
+    else:
+        console.print(f"[dim]GitHub Actions workflow already up to date at {rel}[/dim]")
+    console.print("Add an [bold]ANTHROPIC_API_KEY[/bold] repository secret for the autonomous runs.")
+
+
 @app.command("cursor")
 def cursor(
     apply: bool = typer.Option(False, "--apply", help="Write project Cursor MCP config instead of printing it."),
@@ -1377,6 +404,27 @@ def cursor(
         raise typer.Exit(code=1)
 
 
+@app.command("grok")
+def grok(
+    apply: bool = typer.Option(False, "--apply", help="Register Grok MCP config instead of printing it."),
+    project_root: Path | None = typer.Option(None, "--project-root", help="Repository root containing .devcouncil/."),
+):
+    """
+    Set up DevCouncil MCP tools for Grok Build.
+    """
+    root = _project_root(project_root)
+    if apply:
+        report = apply_integration_target(root, "grok")
+        if not report.ok:
+            console.print(report.to_json())
+            raise typer.Exit(code=1)
+        console.print("[green]Grok integration configured.[/green]")
+        return
+    ok = _configure_grok(root, apply)
+    if not ok and apply:
+        raise typer.Exit(code=1)
+
+
 @app.command("opencode")
 def opencode(
     apply: bool = typer.Option(False, "--apply", help="Write project OpenCode config instead of printing it."),
@@ -1441,29 +489,6 @@ def warp(
     _configure_warp(root, apply)
 
 
-def _record_aider_config(project_root: Path) -> None:
-    def mutate(config: dict) -> None:
-        config.setdefault("integrations", {}).setdefault("aider", {}).update({"enabled": True})
-
-    _mutate_raw_config(project_root, mutate)
-
-
-def _configure_aider(project_root: Path, apply: bool) -> bool:
-    command = ["aider", "--yes", "--no-show-model-warnings", "--message", "<task prompt>"]
-    if not apply:
-        console.print("[bold]Aider[/bold]")
-        console.print("Built-in executor: [dim]dev run TASK-001 --executor aider[/dim]")
-        console.print("Launch command: [dim]" + _format_command(command) + "[/dim]")
-        console.print("Aider does not expose a first-party DevCouncil MCP server.")
-        return True
-
-    if not shutil.which("aider"):
-        console.print("[yellow]Aider CLI not found on PATH. Install it before using `dev run --executor aider`.[/yellow]")
-    _record_aider_config(project_root)
-    console.print("[green]Aider executor enabled in .devcouncil/config.yaml.[/green]")
-    return True
-
-
 @app.command("aider")
 def aider(
     apply: bool = typer.Option(False, "--apply", help="Record the built-in Aider executor in DevCouncil config."),
@@ -1542,7 +567,7 @@ def cli_agent(
     if not apply:
         console.print("[bold]Bring your own CLI executor preview[/bold]")
         console.print(f"Executor: [cyan]{normalized}[/cyan]")
-        console.print(json.dumps(entry, indent=2), soft_wrap=True)
+        console.print(dump_json(entry, indent=2), soft_wrap=True)
         console.print(f"Run with: [dim]dev run TASK-001 --executor {normalized}[/dim]")
         console.print("[yellow]Preview only. Rerun with --apply to update .devcouncil/config.yaml.[/yellow]")
         return
@@ -1570,7 +595,7 @@ def all_tools(
     strict: bool = typer.Option(
         False,
         "--strict",
-        help="After --apply, run dev integrate check --strict and fail on missing optional CLIs.",
+        help="After --apply, run dev integrate check --strict (fails on real integration defects; missing optional coding CLIs stay warnings).",
     ),
 ):
     """
@@ -1601,13 +626,13 @@ def all_tools(
         return
 
     commands = [
-        ("Codex CLI", _codex_command(root)),
-        ("Gemini CLI", _gemini_command(root, gemini_scope)),
         ("Claude Code", _claude_command(root, claude_scope)),
+        ("Codex CLI", _codex_command(root)),
     ]
     for tool, command in commands:
         _configure(tool, command, apply)
     _configure_cursor(root, apply)
+    _configure_grok(root, apply)
     _configure_opencode(root, apply)
     _configure_antigravity(root, apply)
     _configure_warp(root, apply)
@@ -1621,47 +646,7 @@ def recommend(
     project_root: Path | None = typer.Option(None, "--project-root", help="Repository root containing .devcouncil/."),
 ):
     """Recommend a coding CLI executor for this machine and project."""
-    root = _project_root(project_root)
-    probe_order = resolve_coding_cli_probe_order(root)
-    detected = detect_available_coding_cli(root, probe_order=probe_order)
-    resolved = resolve_automated_executor(root, None)
-
-    table = Table(title="DevCouncil Integration Recommendations")
-    table.add_column("Client", style="cyan")
-    table.add_column("PATH")
-    table.add_column("Tier")
-    table.add_column("MCP")
-    table.add_column("Hooks")
-
-    for client in probe_order:
-        info = CODING_CLI_INTEGRATION_INFO.get(client)
-        on_path = resolve_coding_cli_executable(root, client)
-        table.add_row(
-            client,
-            "[green]yes[/green]" if on_path else "[dim]no[/dim]",
-            integration_tier_label(client),
-            "yes" if info and info.mcp else "no",
-            "yes" if info and info.hooks else "no",
-        )
-
-    console.print(table)
-    if summary := integration_status_summary(root):
-        if summary.get("custom_probe_order"):
-            console.print(
-                f"\n[dim]Probe order:[/dim] {', '.join(summary['probe_order'])} "
-                f"(from execution.coding_cli_probe_order)"
-            )
-        else:
-            console.print(f"\n[dim]Probe order:[/dim] {', '.join(summary['probe_order'])} (default)")
-    if detected:
-        console.print(f"\n[bold]Recommended executor:[/bold] [cyan]{resolved}[/cyan]")
-        console.print(f"Run: [dim]dev run TASK-001 --executor {resolved}[/dim]")
-        console.print(f"Or:  [dim]dev go \"Your goal\" --executor {resolved}[/dim]")
-        console.print(f"Setup: [dim]{PREFERRED_COMMAND} {resolved} --apply[/dim]")
-    else:
-        console.print("\n[yellow]No built-in coding CLI was found on PATH.[/yellow]")
-        console.print("Install Codex, Gemini, Claude Code, Cursor Agent, OpenCode, or register a custom CLI:")
-        console.print(f"[dim]{PREFERRED_COMMAND} cli-agent NAME --command TOOL --apply[/dim]")
+    print_recommendations(_project_root(project_root), console)
 
 
 @app.command("status")
@@ -1670,46 +655,7 @@ def status(
     as_json: bool = typer.Option(False, "--json", help="Emit machine-readable JSON."),
 ):
     """Show a compact integration summary without running the MCP server probe."""
-    root = _project_root(project_root)
-    summary = integration_status_summary(root)
-    raw_config = _load_raw_config(root) if (root / ".devcouncil").exists() else {}
-    integrations = raw_config.get("integrations", {})
-
-    if as_json:
-        payload = {
-            **summary,
-            "integrations_enabled": {
-                name: bool(integrations.get(name, {}).get("enabled"))
-                for name in ("cursor", "opencode", "antigravity", "warp", "aider")
-            },
-        }
-        typer.echo(json.dumps(payload, indent=2))
-        return
-
-    table = Table(title="DevCouncil Integration Status")
-    table.add_column("Setting", style="cyan")
-    table.add_column("Value")
-
-    table.add_row("Project", "[green]initialized[/green]" if summary["project_initialized"] else "[yellow]not initialized[/yellow]")
-    table.add_row("Default executor", summary["default_executor"])
-    table.add_row("Resolved executor", summary["resolved_executor"])
-    table.add_row("CLIs on PATH", ", ".join(summary["coding_clis_on_path"]) or "[dim]none[/dim]")
-    table.add_row("Probe order", ", ".join(summary["probe_order"]))
-    table.add_row("Stream CLI output", "yes" if summary["stream_cli_output"] else "no")
-    table.add_row("Cursor resume mode", summary["cursor_resume_mode"])
-
-    for name in ("cursor", "opencode", "antigravity", "warp", "aider"):
-        enabled = bool(integrations.get(name, {}).get("enabled"))
-        table.add_row(f"{name} integration", "[green]enabled[/green]" if enabled else "[dim]off[/dim]")
-
-    console.print(table)
-    if summary["resolved_executor"] not in {"", "manual"}:
-        console.print(
-            f"\n[dim]Next:[/dim] dev run TASK-001 --executor {summary['resolved_executor']} "
-            f"| {PREFERRED_COMMAND} check for full readiness"
-        )
-    else:
-        console.print(f"\n[dim]Next:[/dim] {PREFERRED_COMMAND} recommend | {PREFERRED_COMMAND} check")
+    print_integration_status(_project_root(project_root), console, as_json=as_json)
 
 
 @app.command("matrix")
@@ -1717,36 +663,8 @@ def matrix(
     project_root: Path | None = typer.Option(None, "--project-root", help="Repository root containing .devcouncil/."),
 ):
     """Print built-in coding CLI integration tiers and capabilities."""
-    root = _project_root(project_root)
-    _ = root
-    table = Table(title="DevCouncil Coding CLI Integration Matrix")
-    table.add_column("Client", style="cyan")
-    table.add_column("Tier")
-    table.add_column("Headless")
-    table.add_column("MCP setup")
-    table.add_column("Native hooks")
-    table.add_column("Enforcement")
-    table.add_column("Notes")
-
-    for client in sorted(BUILTIN_CODING_EXECUTOR_NAMES):
-        info = CODING_CLI_INTEGRATION_INFO.get(client)
-        posture = info.enforcement if info else "verify-only"
-        posture_render = "[green]pre-action[/green]" if posture == "pre-action" else "[yellow]verify-only[/yellow]"
-        table.add_row(
-            client,
-            integration_tier_label(client),
-            "yes" if info and info.tier == 1 else "no",
-            "yes" if info and info.mcp else "no",
-            "yes" if info and info.hooks else "verify only",
-            posture_render,
-            info.notes if info else "",
-        )
-    console.print(table)
-    console.print(
-        "\n[dim]Enforcement:[/dim] [green]pre-action[/green] blocks forbidden writes/commands "
-        "before they happen; [yellow]verify-only[/yellow] catches them only at verify time."
-    )
-    console.print("\nSee [dim]docs/integration-tiers.md[/dim] for workflow guidance.")
+    _ = _project_root(project_root)
+    print_integration_matrix(console)
 
 
 @app.command("hooks")
@@ -1758,27 +676,117 @@ def hooks(
         False,
         "--write-gate/--no-write-gate",
         "--contain/--no-contain",
-        help="Install Claude's blocking PreToolUse/PostToolUse write-gate too (off by default; "
+        help="Install Claude's blocking PreToolUse write-gate too (off by default; "
         "fail-closes an interactive session without a task lease).",
     ),
+    git: bool = typer.Option(
+        True,
+        "--git/--no-git",
+        help="Install git post-commit/post-merge/post-checkout hooks that run "
+        "`dev map --if-stale` (on by default with --apply).",
+    ),
+    check: bool = typer.Option(
+        False,
+        "--check",
+        help="Report whether installed hook commands still point at the resolved project `dev` executable.",
+    ),
 ):
     """
     Install DevCouncil hook configuration for Codex, Gemini, Claude, Cursor, and OpenCode.
 
-    Claude installs only assistive hooks by default; add --write-gate for pre-action
-    containment (intended for autonomous executor runs).
+    Claude installs assistive hooks plus refresh-only PostToolUse by default; add
+    --write-gate for pre-action PreToolUse containment (autonomous executor runs).
+    Git map-refresh hooks install by default with --apply (use --no-git to skip).
     """
     root = _project_root(project_root)
+    if check:
+        ok, details = common.check_hook_dev_executable(root)
+        current = common.resolve_dev_executable(root)
+        recorded = common.recorded_hook_dev_executable(root)
+        console.print(f"Resolved `dev`: [cyan]{current}[/cyan]")
+        console.print(f"Recorded for hooks: [cyan]{recorded or '(none)'}[/cyan]")
+        if ok:
+            console.print(f"[green]OK[/green] — {details}")
+            raise typer.Exit(code=0)
+        console.print(f"[red]MISMATCH[/red] — {details}")
+        console.print(
+            f"[dim]Re-run `{PREFERRED_COMMAND} hooks --apply` to retarget hook commands.[/dim]"
+        )
+        raise typer.Exit(code=1)
     if apply and tool == "all":
         report = apply_integration_target(root, "hooks", claude_write_gate=write_gate)
         if not report.ok:
             console.print(report.to_json())
             raise typer.Exit(code=1)
         console.print("[green]Native hooks configured.[/green]")
-        return
-    _configure_native_hooks(root, tool, apply, claude_write_gate=write_gate)
+    else:
+        _configure_native_hooks(root, tool, apply, claude_write_gate=write_gate)
+    if git:
+        written = _install_git_map_hooks(root, apply=apply)
+        for path in written:
+            console.print(f"[green]{'Wrote' if apply else 'Would write'} git hook:[/green] {path}")
+
+
+def _install_git_map_hooks(root: Path, *, apply: bool) -> list[str]:
+    """Install post-commit/post-merge/post-checkout hooks that refresh the map when stale."""
+    hooks_dir = root / ".git" / "hooks"
+    if not (root / ".git").exists():
+        console.print("[yellow]No .git directory; skipping git map hooks.[/yellow]")
+        return []
+    executable = common.resolve_dev_executable(root)
+    # Quote for POSIX shell; absolute path avoids PATH shadowing by a stale global install.
+    quoted = common._format_command([executable])
+    script = f"""#!/bin/sh
+# DevCouncil: refresh repo map after git operations (best-effort).
+{quoted} map --if-stale --no-wiki --project-root "$(git rev-parse --show-toplevel)" >/dev/null 2>&1 || true
+"""
+    written: list[str] = []
+    for name in ("post-commit", "post-merge", "post-checkout"):
+        path = hooks_dir / name
+        rel = str(path.relative_to(root)) if path.is_relative_to(root) else str(path)
+        written.append(rel)
+        if not apply:
+            continue
+        hooks_dir.mkdir(parents=True, exist_ok=True)
+        existing = path.read_text(encoding="utf-8") if path.exists() else ""
+        marker = "# DevCouncil: refresh repo map"
+        if marker in existing:
+            # Retarget the executable if a previous install used a different path.
+            if quoted not in existing:
+                updated = _retarget_git_hook_script(existing, quoted)
+                path.write_text(updated, encoding="utf-8")
+            continue
+        if existing and not existing.endswith("\n"):
+            existing += "\n"
+        path.write_text(existing + script if existing else script, encoding="utf-8")
+        path.chmod(path.stat().st_mode | 0o111)
+    if apply:
+        common.record_hook_dev_executable(root, executable)
+    return written
 
 
+def _retarget_git_hook_script(existing: str, quoted_executable: str) -> str:
+    """Replace the DevCouncil map-refresh command line with the current executable."""
+    import re
+
+    pattern = re.compile(
+        r"(?m)^.*\bmap --if-stale\b.*$|^.*\bmap --no-wiki\b.*$",
+    )
+    replacement = (
+        f'{quoted_executable} map --if-stale --no-wiki '
+        f'--project-root "$(git rev-parse --show-toplevel)" >/dev/null 2>&1 || true'
+    )
+    if pattern.search(existing):
+        return pattern.sub(replacement, existing, count=1)
+    # Marker present but no recognizable command line — append a fresh one.
+    suffix = existing if existing.endswith("\n") else existing + "\n"
+    return (
+        suffix
+        + "# DevCouncil: refresh repo map after git operations (best-effort).\n"
+        + replacement
+        + "\n"
+    )
+
 @app.command("uninstall")
 def uninstall(
     project_root: Path | None = typer.Option(None, "--project-root", help="Repository root containing .devcouncil/."),
@@ -1807,7 +815,7 @@ def check(
     strict: bool = typer.Option(
         False,
         "--strict",
-        help="Treat missing optional coding CLIs as failures instead of warnings.",
+        help="Fail on real project/integration defects (broken state, hooks, MCP, configured-client auth). Missing optional coding CLIs stay warnings.",
     ),
     as_json: bool = typer.Option(False, "--json", help="Emit machine-readable JSON for CI."),
     report_file: Path | None = typer.Option(
@@ -1821,48 +829,14 @@ def check(
     """
     Check whether DevCouncil is ready to integrate with coding CLIs.
     """
-    root = _project_root(project_root)
-    report = build_integration_check_report(root, strict=strict)
-    table = Table(title="DevCouncil Integration Check")
-    table.add_column("Check", style="cyan")
-    table.add_column("Status", style="magenta")
-    table.add_column("Details")
-
-    for row in report.checks:
-        if row.status == "ok":
-            rendered = "[green]OK[/green]"
-        elif row.status == "skip":
-            rendered = "[dim]SKIP[/dim]"
-        elif row.status == "missing":
-            rendered = "[yellow]Missing[/yellow]"
-        else:
-            rendered = "[red]FAIL[/red]"
-        table.add_row(row.name, rendered, row.details)
-
-    write_json = as_json or report_file is not None
-    if write_json:
-        json_text = report.to_json()
-        if report_file is not None:
-            report_path = Path(report_file).expanduser().resolve()
-            report_path.parent.mkdir(parents=True, exist_ok=True)
-            report_path.write_text(json_text + "\n", encoding="utf-8")
-            if not as_json:
-                console.print(f"[dim]Wrote integration report to[/dim] {report_path}")
-        if as_json:
-            typer.echo(json_text)
-    if not write_json or not as_json:
-        console.print(table)
-
-    if report.failures:
-        if not as_json:
-            console.print(
-                f"\n[yellow]Fix failed checks, then run:[/yellow] {PREFERRED_COMMAND} all --apply "
-                f"(or {LEGACY_COMMAND} --apply)."
-            )
-        raise typer.Exit(code=1)
-
-    if not as_json:
-        console.print(f"\n[green]Ready.[/green] Run: {PREFERRED_COMMAND} all --apply (or {LEGACY_COMMAND} --apply).")
+    run_integration_check(
+        _project_root(project_root),
+        console,
+        strict=strict,
+        as_json=as_json,
+        report_file=report_file,
+        legacy_command=LEGACY_COMMAND,
+    )
 
 
 @setup_app.command("agent-flow")
@@ -1882,33 +856,7 @@ def setup_agent_flow(
         console.print("[yellow]Preview only. Rerun with --apply to record this integration in config.[/yellow]")
         return
 
-    config = _load_raw_config(root)
-    integrations = config.setdefault("integrations", {})
-    integrations["agent_flow"] = {
-        "enabled": True,
-        "trace_path": str(trace_path),
-        "mode": "jsonl",
-    }
-    _save_raw_config(root, config)
-    docs_dir = root / ".devcouncil" / "integrations"
-    docs_dir.mkdir(parents=True, exist_ok=True)
-    (docs_dir / "agent-flow.md").write_text(
-        "\n".join([
-            "# Agent Flow",
-            "",
-            f"DevCouncil writes trace events to `{trace_path}`.",
-            "",
-            "Local replay:",
-            "",
-            "```bash",
-            "dev trace tail --follow",
-            "```",
-            "",
-            "External visualizers can watch the JSONL file directly. DevCouncil does not modify global editor or Claude Code settings from this setup command.",
-            "",
-        ]),
-        encoding="utf-8",
-    )
+    trace_path = apply_agent_flow_setup(root)
     console.print("[green]Agent Flow trace integration recorded in .devcouncil/config.yaml.[/green]")
 
 
@@ -1930,44 +878,7 @@ def setup_code_review_graph(
         console.print("[yellow]Preview only. Rerun with --apply to record this integration.[/yellow]")
         return
 
-    if not ignore_path.exists():
-        ignore_path.write_text(
-            "\n".join([
-                ".devcouncil/**",
-                ".git/**",
-                ".venv/**",
-                "dist/**",
-                "node_modules/**",
-                "",
-            ]),
-            encoding="utf-8",
-        )
+    _executable, ignore_path, created = apply_code_review_graph_setup(root)
+    if created:
         console.print(f"[green]Created {ignore_path}.[/green]")
-
-    config = _load_raw_config(root)
-    integrations = config.setdefault("integrations", {})
-    integrations["code_review_graph"] = {
-        "enabled": True,
-        "command": "code-review-graph",
-        "optional": True,
-    }
-    _save_raw_config(root, config)
-    docs_dir = root / ".devcouncil" / "integrations"
-    docs_dir.mkdir(parents=True, exist_ok=True)
-    (docs_dir / "code-review-graph.md").write_text(
-        "\n".join([
-            "# code-review-graph",
-            "",
-            "Install and build the graph outside DevCouncil:",
-            "",
-            "```bash",
-            "pipx install code-review-graph",
-            "code-review-graph build",
-            "```",
-            "",
-            "DevCouncil uses this as an optional context adapter for mapping, prompts, verification traces, and MCP graph context.",
-            "",
-        ]),
-        encoding="utf-8",
-    )
     console.print("[green]code-review-graph adapter recorded in .devcouncil/config.yaml.[/green]")