adl-toolkit 0.0.0-stage → 0.1.3

package/adl_drift/harness/setup.py

@@ -0,0 +1,832 @@
+"""Auto-configuration for MCP clients + the `doctor` diagnostic.
+
+`adl-drift mcp setup` writes the client configs that point at the stdio
+server and installs the skill file that teaches the agent when to use the
+tools. `adl-drift mcp doctor` spawns the real server and runs the JSON-RPC
+handshake so "it doesn't work" is diagnosable in one command.
+
+Config writes merge — existing servers/keys in a config file are preserved;
+the legacy `drift` entry is migrated to `adl-drift`.
+"""
+
+from __future__ import annotations
+
+import json
+import queue
+import re
+import subprocess
+import sys
+import tempfile
+import threading
+from importlib import resources
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+SERVER_NAME = "adl-drift"
+LEGACY_SERVER_NAME = "drift"
+SKILL_PACKAGE = "adl_drift.harness"
+
+# Where each client looks for things, relative to the project root.
+CLAUDE_MCP_CONFIG = ".mcp.json"
+CLAUDE_SKILL_PATH = ".claude/skills/adl-drift/SKILL.md"
+CURSOR_MCP_CONFIG = ".cursor/mcp.json"
+CURSOR_RULE_PATH = ".cursor/rules/drift.mdc"
+CODEX_MCP_CONFIG = ".codex/config.toml"
+
+# Antigravity (Google's VS Code-derived IDE) keeps MCP config under
+# ~/.gemini/, with a recent migration from a legacy path to a unified path.
+# We detect the migration marker at install time and sweep both paths on
+# uninstall for safety. Antigravity has no project-local config concept.
+ANTIGRAVITY_UNIFIED_DIR = ".gemini/config"
+ANTIGRAVITY_LEGACY_DIR = ".gemini/antigravity"
+ANTIGRAVITY_MCP_CONFIG = "mcp_config.json"
+ANTIGRAVITY_MIGRATED_MARKER = ".migrated"
+
+_CURSOR_RULE_FRONTMATTER = (
+    "---\n"
+    "description: Call-graph and pattern index for this repo (ADL Drift MCP tools).\n"
+    "alwaysApply: false\n"
+    "---\n\n"
+)
+
+
+def server_entry() -> Dict[str, Any]:
+    """The mcpServers entry both clients share.
+
+    `sys.executable` is the venv Python running `adl-drift mcp setup` — the
+    one place the right interpreter is always known. `--project .` resolves
+    against the client's cwd, which for project-scoped configs is the
+    project root, so the file stays committable across machines only if the
+    venv path matches; `doctor` flags a dangling interpreter either way.
+    """
+    return {
+        "command": sys.executable,
+        "args": ["-m", "adl_drift.server.mcp_stdio", "--project", "."],
+    }
+
+
+def antigravity_server_entry(project_path: Path) -> Dict[str, Any]:
+    """The MCP-server entry for Antigravity IDE.
+
+    Antigravity rejects the `type: "stdio"` field that other clients accept,
+    so this entry omits it. Because Antigravity config is global (not
+    project-scoped), we pin the absolute project path so the server always
+    indexes the project that was configured.
+    """
+    return {
+        "command": sys.executable,
+        "args": [
+            "-m", "adl_drift.server.mcp_stdio",
+            "--project", str(Path(project_path).resolve()),
+        ],
+    }
+
+
+def codex_server_entry(project_path: Path) -> Dict[str, Any]:
+    """Project-scoped MCP entry for Codex CLI and its VS Code extension."""
+    return {
+        "command": sys.executable,
+        "args": [
+            "-m", "adl_drift.server.mcp_stdio",
+            "--project", str(Path(project_path).resolve()),
+        ],
+    }
+
+
+def _codex_table(entry: Dict[str, Any]) -> str:
+    return (
+        "[mcp_servers.adl-drift]\n"
+        f"command = {json.dumps(entry['command'])}\n"
+        f"args = {json.dumps(entry['args'])}\n"
+    )
+
+
+def _replace_codex_table(text: str, replacement: str = "") -> str:
+    """Replace ADL Drift and legacy TOML tables, preserving other settings."""
+    return re.sub(
+        r"(?ms)^\[mcp_servers\.(?:adl-drift|drift)(?:\.[^\]]+)?\]\n.*?"
+        r"(?=^\[(?!mcp_servers\.(?:adl-drift|drift)(?:\.|\]))|\Z)",
+        replacement,
+        text,
+    )
+
+
+def _merge_codex_config(config_path: Path, project_path: Path) -> tuple[str, str]:
+    existing = config_path.read_text(encoding="utf-8") if config_path.exists() else ""
+    updated = _replace_codex_table(existing).rstrip()
+    table = _codex_table(codex_server_entry(project_path))
+    updated = f"{updated}\n\n{table}" if updated else table
+    action = (
+        "created" if not config_path.exists()
+        else "unchanged" if existing == updated else "updated"
+    )
+    return updated, action
+
+
+def _remove_codex_entry(config_path: Path) -> Optional[Dict[str, str]]:
+    if not config_path.exists():
+        return None
+    existing = config_path.read_text(encoding="utf-8")
+    updated = _replace_codex_table(existing).strip()
+    if updated == existing.strip():
+        return None
+    if updated:
+        config_path.write_text(updated + "\n", encoding="utf-8")
+    else:
+        config_path.unlink()
+    return {"path": CODEX_MCP_CONFIG, "action": "removed"}
+
+
+def _codex_config_entry(config_path: Path) -> Optional[Dict[str, Any]]:
+    if not config_path.exists():
+        return None
+    text = config_path.read_text(encoding="utf-8")
+    match = None
+    for name in (SERVER_NAME, LEGACY_SERVER_NAME):
+        match = re.search(
+            rf"(?ms)^\[mcp_servers\.{re.escape(name)}\]\n(.*?)"
+            rf"(?=^\[(?!mcp_servers\.{re.escape(name)}(?:\.|\]))|\Z)",
+            text,
+        )
+        if match:
+            break
+    if match is None:
+        return None
+    values = dict(re.findall(r"(?m)^(command|args)\s*=\s*(.+)$", match.group(1)))
+    try:
+        return {"command": json.loads(values["command"]), "args": json.loads(values["args"])}
+    except (KeyError, json.JSONDecodeError):
+        return None
+
+
+def _antigravity_paths(home: Optional[Path] = None) -> Dict[str, Path]:
+    home = home or Path.home()
+    unified_dir = home / ANTIGRAVITY_UNIFIED_DIR
+    legacy_dir = home / ANTIGRAVITY_LEGACY_DIR
+    return {
+        "unified_dir": unified_dir,
+        "unified_file": unified_dir / ANTIGRAVITY_MCP_CONFIG,
+        "legacy_dir": legacy_dir,
+        "legacy_file": legacy_dir / ANTIGRAVITY_MCP_CONFIG,
+        "migrated_marker": unified_dir / ANTIGRAVITY_MIGRATED_MARKER,
+    }
+
+
+def _antigravity_preferred_config_path(home: Optional[Path] = None) -> Path:
+    """Return the Antigravity MCP config path to write to.
+
+    Prefer the unified path when Antigravity has signalled migration (marker
+    file present) or when the unified file already exists; otherwise fall
+    back to the legacy path.
+    """
+    paths = _antigravity_paths(home)
+    if paths["migrated_marker"].exists() or paths["unified_file"].exists():
+        return paths["unified_file"]
+    return paths["legacy_file"]
+
+
+def read_skill(name: str = "adl-drift.md") -> str:
+    return (resources.files(SKILL_PACKAGE) / "skills" / name).read_text(encoding="utf-8")
+
+
+# AGENTS.md marker-fenced section installed for Codex and Antigravity. The
+# fenced block lets setup merge updates without overwriting hand-written
+# content, and lets uninstall remove only the workflow that ADL Drift owns.
+AGENTS_MD_PATH = "AGENTS.md"
+ANTIGRAVITY_RULE_PATH = ".agents/rules/drift.md"
+AGENTS_MD_MARKER_START = "<!-- BEGIN DRIFT WORKFLOW -->"
+AGENTS_MD_MARKER_END = "<!-- END DRIFT WORKFLOW -->"
+_LEGACY_AGENTS_MD_MARKER_START = "<!-- BEGIN DRIFT ANTIGRAVITY WORKFLOW -->"
+_LEGACY_AGENTS_MD_MARKER_END = "<!-- END DRIFT ANTIGRAVITY WORKFLOW -->"
+
+
+def _agents_workflow_section() -> str:
+    """Return the marker-fenced ADL Drift workflow section for AGENTS.md."""
+    body = read_skill("drift-antigravity.md")
+    return (
+        f"{AGENTS_MD_MARKER_START}\n"
+        f"{body}\n"
+        f"{AGENTS_MD_MARKER_END}\n"
+    )
+
+
+def _antigravity_configured_for_project(project_path: Path) -> bool:
+    """Return whether Antigravity has an ADL Drift entry for this project."""
+    expected_args = antigravity_server_entry(project_path)["args"]
+    paths = _antigravity_paths()
+    for config_path in (paths["unified_file"], paths["legacy_file"]):
+        if not config_path.exists():
+            continue
+        try:
+            config = json.loads(config_path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            continue
+        if not isinstance(config, dict):
+            continue
+        servers = config.get("mcpServers", {})
+        if isinstance(servers, dict) and any(
+            isinstance(servers.get(name), dict)
+            and servers[name].get("args") == expected_args
+            for name in (SERVER_NAME, LEGACY_SERVER_NAME)
+        ):
+            return True
+    return False
+
+
+def _agents_md_block(existing: str) -> tuple[int, int, str] | None:
+    """Find the current or legacy ADL Drift workflow fence in ``existing``."""
+    for start, end in (
+        (AGENTS_MD_MARKER_START, AGENTS_MD_MARKER_END),
+        (_LEGACY_AGENTS_MD_MARKER_START, _LEGACY_AGENTS_MD_MARKER_END),
+    ):
+        start_idx = existing.find(start)
+        end_idx = existing.find(end)
+        if start_idx != -1 and end_idx > start_idx:
+            return start_idx, end_idx + len(end), start
+    return None
+
+
+def _merge_agents_md(project_path: Path, section: str) -> tuple[str, str]:
+    """Return (merged content, action) for AGENTS.md without writing.
+
+    The section is treated as an opaque block bounded by the marker comments.
+    Re-running setup with the same section produces an unchanged action.
+    """
+    path = project_path / AGENTS_MD_PATH
+    existing = path.read_text(encoding="utf-8") if path.exists() else ""
+
+    block = _agents_md_block(existing)
+    if block:
+        start_idx, end_idx, _ = block
+        before = existing[:start_idx].rstrip("\n")
+        after = existing[end_idx:].lstrip("\n")
+        merged = ""
+        if before:
+            merged += before + "\n\n"
+        merged += section
+        if after:
+            merged += "\n" + after + "\n"
+        action = "updated" if merged != existing else "unchanged"
+    elif not existing:
+        merged = f"# Project Agents\n\n{section}"
+        action = "created"
+    else:
+        merged = existing.rstrip("\n") + "\n\n" + section
+        action = "updated"
+    return merged, action
+
+
+def detect_clients(project_path: Path) -> List[str]:
+    """Config-dir probing: project dirs first, then home dirs."""
+    found = []
+    home = Path.home()
+    if (project_path / ".claude").is_dir() or (home / ".claude").is_dir():
+        found.append("claude")
+    if (project_path / ".cursor").is_dir() or (home / ".cursor").is_dir():
+        found.append("cursor")
+    if (project_path / CODEX_MCP_CONFIG).exists():
+        found.append("codex")
+    paths = _antigravity_paths(home)
+    if (
+        paths["unified_dir"].is_dir()
+        or paths["legacy_dir"].is_dir()
+        or paths["unified_file"].exists()
+        or paths["legacy_file"].exists()
+    ):
+        found.append("antigravity")
+    return found
+
+
+def _load_config_json(config_path: Path) -> Dict[str, Any]:
+    """Load a JSON config file, treating an empty/whitespace file as `{}`."""
+    if not config_path.exists():
+        return {}
+    text = config_path.read_text(encoding="utf-8").strip()
+    if not text:
+        return {}
+    try:
+        config = json.loads(text)
+    except json.JSONDecodeError as e:
+        raise ValueError(f"{config_path} is not valid JSON ({e}); fix or remove it") from e
+    if not isinstance(config, dict):
+        raise ValueError(f"{config_path} top level must be a JSON object")
+    return config
+
+
+def _merge_server_config(config_path: Path) -> tuple[Dict[str, Any], str]:
+    """Return (merged config, action) without writing."""
+    config = _load_config_json(config_path)
+
+    servers = config.setdefault("mcpServers", {})
+    entry = server_entry()
+    legacy_removed = servers.pop(LEGACY_SERVER_NAME, None) is not None
+    if servers.get(SERVER_NAME) == entry and not legacy_removed:
+        return config, "unchanged"
+    action = "updated" if config_path.exists() else "created"
+    servers[SERVER_NAME] = entry
+    return config, action
+
+
+def _merge_antigravity_config(
+    config_path: Path, project_path: Path
+) -> tuple[Dict[str, Any], str]:
+    """Merge the ADL Drift entry into an Antigravity `mcp_config.json`.
+
+    Antigravity's top-level key is also `mcpServers`, but the entry omits
+    the `type` field used by Claude/Cursor. Existing keys other than the
+    ADL Drift entry are preserved. Empty/whitespace files are treated as `{}`.
+    """
+    config = _load_config_json(config_path)
+
+    servers = config.setdefault("mcpServers", {})
+    entry = antigravity_server_entry(project_path)
+    legacy_removed = servers.pop(LEGACY_SERVER_NAME, None) is not None
+    if servers.get(SERVER_NAME) == entry and not legacy_removed:
+        return config, "unchanged"
+    action = "updated" if config_path.exists() else "created"
+    servers[SERVER_NAME] = entry
+    return config, action
+
+
+def _plan_file(path: Path, content: str) -> str:
+    if not path.exists():
+        return "created"
+    return "unchanged" if path.read_text(encoding="utf-8") == content else "updated"
+
+
+def _remove_antigravity_entry(config_path: Path, unlink_empty: bool = False) -> Optional[Dict[str, str]]:
+    """Remove ADL Drift entries from an Antigravity config file.
+
+    Returns an action record if the file existed and contained a drift entry,
+    otherwise None. Empty `mcpServers` objects are pruned. By default the file
+    is left in place (Antigravity manages it); pass `unlink_empty=True` to
+    delete the file when it becomes empty.
+    """
+    if not config_path.exists():
+        return None
+    try:
+        config = json.loads(config_path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, ValueError):
+        return None
+    if not isinstance(config, dict):
+        return None
+    servers = config.get("mcpServers", {})
+    names = {SERVER_NAME, LEGACY_SERVER_NAME} & set(servers) if isinstance(servers, dict) else set()
+    if not names:
+        return None
+    for name in names:
+        del servers[name]
+    if not servers:
+        config.pop("mcpServers", None)
+    if unlink_empty and not config:
+        config_path.unlink()
+    else:
+        config_path.write_text(json.dumps(config, indent=2) + "\n", encoding="utf-8")
+    return {"path": str(config_path), "action": "removed"}
+
+
+def setup(
+    project_path: Path,
+    claude: bool = False,
+    cursor: bool = False,
+    antigravity: bool = False,
+    codex: bool = False,
+    dry_run: bool = False,
+) -> List[Dict[str, str]]:
+    """Configure MCP clients. No flags = configure every detected client
+    (generic .mcp.json if none detected). Returns one action record per
+    file: {path, action: created|updated|unchanged|removed}."""
+    project_path = Path(project_path).resolve()
+    if not claude and not cursor and not antigravity and not codex:
+        detected = detect_clients(project_path)
+        claude = "claude" in detected
+        cursor = "cursor" in detected
+        antigravity = "antigravity" in detected
+        codex = True
+        if not detected:
+            claude = True  # generic fallback: .mcp.json is the open format
+
+    actions: List[Dict[str, str]] = []
+
+    def _write_json(rel: str) -> None:
+        path = project_path / rel
+        config, action = _merge_server_config(path)
+        actions.append({"path": rel, "action": action})
+        if not dry_run and action != "unchanged":
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(json.dumps(config, indent=2) + "\n", encoding="utf-8")
+
+    def _write_text(rel: str, content: str) -> None:
+        path = project_path / rel
+        action = _plan_file(path, content)
+        actions.append({"path": rel, "action": action})
+        if not dry_run and action != "unchanged":
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(content, encoding="utf-8")
+
+    if claude:
+        _write_json(CLAUDE_MCP_CONFIG)
+        _write_text(CLAUDE_SKILL_PATH, read_skill())
+    if cursor:
+        _write_json(CURSOR_MCP_CONFIG)
+        _write_text(CURSOR_RULE_PATH, _CURSOR_RULE_FRONTMATTER + read_skill("drift-generic.md"))
+    if codex:
+        config_path = project_path / CODEX_MCP_CONFIG
+        config, _ = _merge_codex_config(config_path, project_path)
+        _write_text(CODEX_MCP_CONFIG, config)
+    if codex or antigravity:
+        agents_content, agents_action = _merge_agents_md(
+            project_path, _agents_workflow_section()
+        )
+        actions.append({"path": AGENTS_MD_PATH, "action": agents_action})
+        if not dry_run and agents_action != "unchanged":
+            (project_path / AGENTS_MD_PATH).write_text(agents_content, encoding="utf-8")
+    if antigravity:
+        preferred = _antigravity_preferred_config_path()
+        if dry_run:
+            # Report what would happen without touching disk.
+            actions.append({"path": str(preferred), "action": "created"})
+            actions.append({"path": ANTIGRAVITY_RULE_PATH, "action": "created"})
+        else:
+            config, action = _merge_antigravity_config(preferred, project_path)
+            preferred.parent.mkdir(parents=True, exist_ok=True)
+            preferred.write_text(json.dumps(config, indent=2) + "\n", encoding="utf-8")
+            actions.append({"path": str(preferred), "action": action})
+
+            # If the user originally installed on the legacy path and Antigravity
+            # has since migrated, strip the stale legacy entry so they don't wind
+            # up with two competing ADL Drift configs.
+            paths = _antigravity_paths()
+            if preferred == paths["unified_file"] and paths["legacy_file"].exists():
+                removed = _remove_antigravity_entry(paths["legacy_file"])
+                if removed:
+                    actions.append(removed)
+
+            # Native Antigravity workspace rules are evaluated for every
+            # prompt; AGENTS.md remains installed for compatibility.
+            _write_text(ANTIGRAVITY_RULE_PATH, read_skill("drift-antigravity.md"))
+
+    return actions
+
+
+# ---------------------------------------------------------------- uninstall
+
+
+def _remove_server_entry(config_path: Path) -> Optional[Dict[str, str]]:
+    """Remove ADL Drift entries from a Claude/Cursor style config file.
+
+    Returns an action record if the file existed and contained a drift entry,
+    otherwise None. Empty `mcpServers` objects are pruned; if the whole file
+    becomes empty it is removed.
+    """
+    if not config_path.exists():
+        return None
+    try:
+        config = json.loads(config_path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, ValueError):
+        return None
+    if not isinstance(config, dict):
+        return None
+    servers = config.get("mcpServers", {})
+    names = {SERVER_NAME, LEGACY_SERVER_NAME} & set(servers) if isinstance(servers, dict) else set()
+    if not names:
+        return None
+    for name in names:
+        del servers[name]
+    if not servers:
+        config.pop("mcpServers", None)
+    if not config:
+        config_path.unlink()
+    else:
+        config_path.write_text(json.dumps(config, indent=2) + "\n", encoding="utf-8")
+    return {"path": str(config_path), "action": "removed"}
+
+
+def _remove_text_file_if_matches(path: Path, expected_content: str) -> Optional[Dict[str, str]]:
+    """Remove a skill/rule file if its current content exactly matches ours."""
+    if not path.exists():
+        return None
+    try:
+        current = path.read_text(encoding="utf-8")
+    except OSError:
+        return None
+    if current != expected_content:
+        return {"path": str(path), "action": "unchanged"}
+    path.unlink()
+    return {"path": str(path), "action": "removed"}
+
+
+def _remove_agents_md_section(project_path: Path) -> Optional[Dict[str, str]]:
+    """Remove the marker-fenced ADL Drift section from AGENTS.md.
+
+    Returns an action record if AGENTS.md existed and contained the section.
+    If removing the section leaves only whitespace or the generic header we
+    created, the whole file is removed.
+    """
+    path = project_path / AGENTS_MD_PATH
+    if not path.exists():
+        return None
+    existing = path.read_text(encoding="utf-8")
+    block = _agents_md_block(existing)
+    if not block:
+        return {"path": AGENTS_MD_PATH, "action": "unchanged"}
+    start_idx, end_idx, _ = block
+    before = existing[:start_idx].rstrip("\n")
+    after = existing[end_idx:].lstrip("\n")
+    merged = ""
+    if before:
+        merged += before + "\n"
+    if after:
+        merged += after + "\n"
+    remaining = merged.strip()
+    # If the file only contains our generic header (or nothing), remove it.
+    if not remaining or remaining == "# Project Agents":
+        path.unlink()
+    else:
+        path.write_text(merged, encoding="utf-8")
+    return {"path": AGENTS_MD_PATH, "action": "removed"}
+
+
+def uninstall(
+    project_path: Path,
+    claude: bool = False,
+    cursor: bool = False,
+    antigravity: bool = False,
+    codex: bool = False,
+    dry_run: bool = False,
+) -> List[Dict[str, str]]:
+    """Remove ADL Drift MCP client configuration. No flags = uninstall every
+    detected client. Returns one action record per touched file."""
+    project_path = Path(project_path).resolve()
+    if not claude and not cursor and not antigravity and not codex:
+        detected = detect_clients(project_path)
+        claude = "claude" in detected
+        cursor = "cursor" in detected
+        antigravity = "antigravity" in detected
+        codex = "codex" in detected
+        if not detected:
+            claude = True  # generic fallback
+
+    actions: List[Dict[str, str]] = []
+    remove_agents_workflow = (codex or antigravity) and not (
+        (not codex and _codex_config_entry(project_path / CODEX_MCP_CONFIG))
+        or (not antigravity and _antigravity_configured_for_project(project_path))
+    )
+
+    if claude:
+        if dry_run:
+            actions.append({"path": CLAUDE_MCP_CONFIG, "action": "removed"})
+            actions.append({"path": CLAUDE_SKILL_PATH, "action": "removed"})
+        else:
+            removed = _remove_server_entry(project_path / CLAUDE_MCP_CONFIG)
+            if removed:
+                removed["path"] = CLAUDE_MCP_CONFIG
+                actions.append(removed)
+            removed = _remove_text_file_if_matches(
+                project_path / CLAUDE_SKILL_PATH, read_skill()
+            )
+            if removed:
+                removed["path"] = CLAUDE_SKILL_PATH
+                actions.append(removed)
+
+    if cursor:
+        if dry_run:
+            actions.append({"path": CURSOR_MCP_CONFIG, "action": "removed"})
+            actions.append({"path": CURSOR_RULE_PATH, "action": "removed"})
+        else:
+            removed = _remove_server_entry(project_path / CURSOR_MCP_CONFIG)
+            if removed:
+                removed["path"] = CURSOR_MCP_CONFIG
+                actions.append(removed)
+            removed = _remove_text_file_if_matches(
+                project_path / CURSOR_RULE_PATH,
+                _CURSOR_RULE_FRONTMATTER + read_skill("drift-generic.md"),
+            )
+            if removed:
+                removed["path"] = CURSOR_RULE_PATH
+                actions.append(removed)
+
+    if codex:
+        if dry_run:
+            actions.append({"path": CODEX_MCP_CONFIG, "action": "removed"})
+        else:
+            removed = _remove_codex_entry(project_path / CODEX_MCP_CONFIG)
+            if removed:
+                actions.append(removed)
+
+    if remove_agents_workflow:
+        if dry_run:
+            actions.append({"path": AGENTS_MD_PATH, "action": "removed"})
+        else:
+            removed = _remove_agents_md_section(project_path)
+            if removed:
+                actions.append(removed)
+
+    if antigravity:
+        paths = _antigravity_paths()
+        preferred = _antigravity_preferred_config_path()
+        if dry_run:
+            actions.append({"path": str(preferred), "action": "removed"})
+            actions.append({"path": ANTIGRAVITY_RULE_PATH, "action": "removed"})
+        else:
+            for config_path in (paths["unified_file"], paths["legacy_file"]):
+                removed = _remove_antigravity_entry(config_path, unlink_empty=True)
+                if removed:
+                    actions.append(removed)
+            removed = _remove_text_file_if_matches(
+                project_path / ANTIGRAVITY_RULE_PATH,
+                read_skill("drift-antigravity.md"),
+            )
+            if removed:
+                removed["path"] = ANTIGRAVITY_RULE_PATH
+                actions.append(removed)
+
+    return actions
+
+
+# ---------------------------------------------------------------- doctor
+
+
+def _configured_entry(project_path: Path) -> Optional[Dict[str, Any]]:
+    """The ADL Drift entry from a supported project or Antigravity config, if any."""
+    for rel in (CLAUDE_MCP_CONFIG, CURSOR_MCP_CONFIG):
+        path = project_path / rel
+        if not path.exists():
+            continue
+        try:
+            servers = json.loads(path.read_text(encoding="utf-8")).get("mcpServers", {})
+        except (json.JSONDecodeError, AttributeError):
+            continue
+        for name in (SERVER_NAME, LEGACY_SERVER_NAME):
+            if name in servers:
+                return servers[name]
+    codex_entry = _codex_config_entry(project_path / CODEX_MCP_CONFIG)
+    if codex_entry:
+        return codex_entry
+    # Antigravity config lives in the home dir, not the project.
+    antigravity_path = _antigravity_preferred_config_path()
+    if antigravity_path.exists():
+        try:
+            servers = json.loads(antigravity_path.read_text(encoding="utf-8")).get("mcpServers", {})
+        except (json.JSONDecodeError, AttributeError):
+            servers = {}
+        for name in (SERVER_NAME, LEGACY_SERVER_NAME):
+            if name in servers:
+                return servers[name]
+    return None
+
+
+def _handshake(command: List[str], cwd: Path, timeout: float) -> Dict[str, Any]:
+    """Spawn the stdio server, run initialize + tools/list, return findings."""
+    # A file drains startup tracebacks without blocking the server's stderr pipe.
+    with tempfile.TemporaryFile() as stderr:
+        proc = subprocess.Popen(
+            command, cwd=cwd, text=True, encoding="utf-8", errors="replace",
+            stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=stderr,
+        )
+
+        def send(msg: Dict[str, Any]) -> None:
+            assert proc.stdin is not None
+            proc.stdin.write(json.dumps(msg) + "\n")
+            proc.stdin.flush()
+
+        def recv(want_id: int) -> Dict[str, Any]:
+            assert proc.stdout is not None
+            while True:
+                line = proc.stdout.readline()
+                if not line:
+                    raise RuntimeError("server closed stdout before responding")
+                try:
+                    msg = json.loads(line)
+                except json.JSONDecodeError:
+                    raise RuntimeError(f"non-JSON on stdout (framing corruption): {line[:120]!r}")
+                if not isinstance(msg, dict):
+                    raise TypeError("invalid JSON-RPC response: expected an object")
+                if msg.get("id") == want_id:
+                    if "error" in msg:
+                        raise RuntimeError(f"JSON-RPC request {want_id} failed: {msg['error']}")
+                    if not isinstance(msg.get("result"), dict):
+                        raise RuntimeError(f"JSON-RPC request {want_id} returned an invalid result")
+                    return msg
+
+        responses: queue.Queue[tuple[dict[str, Any] | None, Exception | None]] = queue.Queue()
+
+        def exchange() -> None:
+            try:
+                send({
+                    "jsonrpc": "2.0", "id": 1, "method": "initialize",
+                    "params": {
+                        "protocolVersion": "2024-11-05", "capabilities": {},
+                        "clientInfo": {"name": "adl-drift-doctor", "version": "1.0"},
+                    },
+                })
+                init = recv(1)["result"]
+                info = init.get("serverInfo")
+                if not isinstance(info, dict) or info.get("name") != SERVER_NAME:
+                    raise RuntimeError("initialize did not identify the adl-drift server")
+                send({"jsonrpc": "2.0", "method": "notifications/initialized"})
+                send({"jsonrpc": "2.0", "id": 2, "method": "tools/list"})
+                tools = recv(2)["result"].get("tools")
+                if (not isinstance(tools, list) or not tools
+                        or any(not isinstance(t, dict) or not isinstance(t.get("name"), str) for t in tools)):
+                    raise RuntimeError("tools/list returned no valid tools")
+                responses.put(({"server_info": info, "tools": [t["name"] for t in tools]}, None))
+            except (RuntimeError, OSError, ValueError, TypeError, KeyError) as error:
+                responses.put((None, error))
+
+        worker = threading.Thread(target=exchange, daemon=True)
+        try:
+            worker.start()
+            try:
+                result, error = responses.get(timeout=timeout)
+            except queue.Empty:
+                result, error = None, RuntimeError(f"MCP handshake timed out after {timeout:g}s")
+            if error is not None and proc.poll() is None:
+                proc.kill()
+            worker.join(timeout=1)
+            if proc.stdin is not None:
+                try:
+                    proc.stdin.close()
+                except OSError:
+                    pass
+            try:
+                proc.wait(timeout=1)
+            except subprocess.TimeoutExpired:
+                proc.kill()
+                proc.wait()
+            if error is not None:
+                stderr.seek(0, 2)
+                stderr.seek(max(0, stderr.tell() - 4096))
+                detail = stderr.read().decode("utf-8", errors="replace").strip()
+                raise RuntimeError(str(error) + (f"\nServer stderr:\n{detail}" if detail else "")) from error
+            assert result is not None
+            return result
+        finally:
+            if proc.poll() is None:
+                proc.kill()
+                proc.wait()
+            worker.join(timeout=1)
+            if proc.stdin is not None:
+                try:
+                    proc.stdin.close()
+                except OSError:
+                    pass
+            if proc.stdout is not None:
+                proc.stdout.close()
+
+
+def doctor(project_path: Path, timeout: float = 30.0) -> Dict[str, Any]:
+    """Verify the wiring end-to-end. Returns {ok, checks: [...]}; `ok`
+    covers the required chain (interpreter → SDK → live handshake);
+    config/skill presence is reported but only required for client pickup."""
+    project_path = Path(project_path).resolve()
+    checks: List[Dict[str, Any]] = []
+
+    def check(name: str, ok: bool, detail: str, required: bool = True) -> None:
+        checks.append({"name": name, "ok": ok, "detail": detail, "required": required})
+
+    entry = _configured_entry(project_path)
+    if entry is None:
+        check("config", False,
+              "no adl-drift entry in .mcp.json, .cursor/mcp.json, .codex/config.toml, or Antigravity config — run `adl-drift mcp setup`",
+              required=False)
+        command = [sys.executable, "-m", "adl_drift.server.mcp_stdio", "--project", "."]
+    else:
+        check("config", True, f"adl-drift entry found (command: {entry.get('command')})",
+              required=False)
+        command = [entry["command"], *entry.get("args", [])]
+
+    interpreter = Path(command[0])
+    if interpreter.exists():
+        check("interpreter", True, str(interpreter))
+    else:
+        check("interpreter", False, f"{interpreter} does not exist — re-run `adl-drift mcp setup`")
+
+    probe = subprocess.run(
+        [command[0], "-c", "import mcp"], capture_output=True, text=True,
+    ) if interpreter.exists() else None
+    if probe is not None and probe.returncode == 0:
+        check("mcp-sdk", True, "`import mcp` ok in the configured interpreter")
+    else:
+        detail = probe.stderr.strip().splitlines()[-1] if probe and probe.stderr else "interpreter missing"
+        check("mcp-sdk", probe is not None and probe.returncode == 0, detail)
+
+    if all(c["ok"] for c in checks if c["required"]):
+        try:
+            result = _handshake(command, cwd=project_path, timeout=timeout)
+            names = result["tools"]
+            check("handshake", True,
+                  f"{result['server_info'].get('name')} {result['server_info'].get('version')} "
+                  f"— {len(names)} tools: {', '.join(names)}")
+        except (RuntimeError, OSError, KeyError, subprocess.SubprocessError) as e:
+            check("handshake", False, str(e))
+    else:
+        check("handshake", False, "skipped — fix the checks above first")
+
+    skill = project_path / CLAUDE_SKILL_PATH
+    check("skill", skill.exists(),
+          str(skill) if skill.exists()
+          else "no skill installed (fine for MCP-only mode; `mcp setup --claude` adds it)",
+          required=False)
+
+    return {"ok": all(c["ok"] for c in checks if c["required"]), "checks": checks}