graphite-code 0.3.0__py3-none-any.whl

graphite/init.py

@@ -0,0 +1,791 @@
+"""Interactive project initialization for Graphite-aware AI coding agents."""
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Iterable, TextIO
+
+from .agent_settings import ensure_claude_settings
+from .bootstrap import ensure_gitignore, daemon_visibility
+from .git import GitError, GitRunner
+# Imported as a module, not `from .hookinstall import install_hooks`: this
+# file also has an `install_hooks` *parameter* below, and that local name
+# would shadow a bare function import. `hookinstall.install_hooks(...)` stays
+# unambiguous either way.
+from . import hookinstall
+from .hookinstall import DEFAULT_HOOKS_DIRNAME
+from .io import atomic_write_text
+
+# Bump whenever GRAPHITE_DOC, SHARED_POINTER, or CURSOR_POINTER changes;
+# test_template_change_requires_doc_version_bump pins the pairing. Files
+# written before versioning existed count as version 1 ("legacy unversioned")
+# and are never rewritten automatically.
+DOC_VERSION = 14
+
+MANAGED_BEGIN = f"<!-- graphite:managed version={DOC_VERSION} -->"
+MANAGED_END = "<!-- graphite:managed-end -->"
+_MANAGED_BEGIN_RE = re.compile(r"<!-- graphite:managed version=(\d{1,9}) -->")
+
+GRAPHITE_DOC_HEADER = "# Graphite Development Context"
+GRAPHITE_REQUIRED_WORKFLOW = "## Required Workflow"
+GRAPHITE_DOC = """# Graphite Development Context
+
+Graphite is the shared local code graph for this project. Codex, Claude Code, Gemini CLI, Antigravity, Visual Studio, and other coding agents should use the same graph instead of rebuilding separate mental maps.
+
+All commands below use `python -m graphite`, which works in every shell and for every agent as long as the Python environment has Graphite installed. A bare `graphite` command is equivalent where the console script is on PATH.
+
+## Required Workflow
+
+Graphite-first is required, not advisory. Before any cross-file exploration, consult the graph first. Manual search (grep, glob, directory walking) is the fallback, not the default: use it for literal text and filename lookups, or after a Graphite answer proved insufficient — and say so when you fall back.
+
+| Question shape | Run first |
+| --- | --- |
+| Who calls / reads / imports this symbol? | `python -m graphite query "callers <symbol>"` |
+| What does this symbol call? | `python -m graphite query "calls <symbol>"` |
+| Where is this symbol defined? | `python -m graphite search "<symbol>"` |
+| What breaks if this file changes? | `python -m graphite impact <file>` |
+| What surrounds this file (callers, tests, neighbors)? | `python -m graphite context <file>` |
+| How is the project structured? | `python -m graphite query "stats"` |
+| Literal string or filename lookup | grep/glob — Graphite not required |
+| Where is the shared agent channel? | `python -m graphite channel` |
+
+Before non-trivial code changes:
+
+1. Run `python -m graphite check .`
+2. Run `python -m graphite context <target-file>` before editing important files.
+3. Run `python -m graphite impact <target-file>` before changing shared logic, APIs, data flow, auth, persistence, deployment behavior, or other high-risk paths.
+4. Use `python -m graphite search "<symbol, path, or concept>"` to locate nodes; use `python -m graphite query "stats"` when project structure is unclear.
+5. Discover supported commands, query verbs, and limits with `python -m graphite capabilities --json` — do not guess query verbs. `query` takes structured verbs; `query --natural "<question>"` accepts only the fixed deterministic grammar listed by capabilities (no inference — unmatched questions fall back to ranked search).
+6. Graph answers carry an `answer` block: `grade: decision_grade` means this answer's own relations/languages are healthy (an empty result is a trustworthy absence, subject to `caveats`); `advisory` means verify with grep and say so; `inconclusive` (also the legacy `"inconclusive": true`) means unknown, not safe. Check `known limits`/`caveats` before trusting empties.
+7. `python -m graphite incidents list` shows recorded failures (build errors, malformed artifacts, inconclusive queries). Check it when a graph answer looks wrong; recurring incidents belong in a governed round.
+
+After edits:
+
+1. Run `python -m graphite build .` when `python -m graphite check .` reports the graph stale. Otherwise this repo's graph refreshes on its own while it is open in a coding agent.
+2. Run relevant tests, typechecks, or validation commands.
+3. Do not edit `graph-out/` manually.
+
+Graph freshness is never a reason to avoid the graph. Always query it for
+relationship questions: every answer carries its own `answer.grade`, so trust
+that rather than guessing whether the graph is current. If an answer comes back
+`inconclusive` or insufficient, fall back to search and say that you did.
+
+## Repository Isolation
+
+**Your repository is your world.** Do not read, write, or run commands in any other repository — including its `graph-out/`. This holds even when the other repo sits on the same machine, is a dependency of this one, or plainly contains the answer you need.
+
+Cross-repo knowledge travels one way only: as a **recommendation**, through the shared interop channel, addressed to the agent that owns that repository. That agent decides and acts. A defect you find elsewhere is a request, never a patch — and never a read.
+
+- Do not open another repo's source, tests, config, or `graph.json`. Each repo's graph describes that repo and belongs to its agent.
+- Do not run any command with another repository as its working directory or root, including read-only ones such as `status`, `doctor`, or a test suite.
+- Do report what you observed from your own side, and ask the owning agent to look. Say plainly which parts you could not verify.
+- Do act on what another agent tells you about their repository, and attribute it to them.
+
+**If you need a fact from another repo, ask for it.** A claim clearly labelled unverified is safer than a verified one obtained out of bounds — the boundary is the control, and stepping over it to be thorough defeats it.
+
+### The one exception: the shared agent channel
+
+There is one shared **agent channel** on this machine: a directory named `.agent-channel/`, its own git repository, living outside every project and belonging to no repo and no agent. **Every agent may read it and write to it**, whichever repository it is responsible for, and nothing in it is any project's source or data.
+
+Its absolute location is machine-local and deliberately kept out of this file: project files are committed and pushed, so a local directory layout does not belong in them. **Resolve it with `python -m graphite channel`** (`--json` for a machine-readable form, reporting whether it exists and is a git repo). The path goes to stdout and diagnostics to stderr, so `$(python -m graphite channel)` is safe to use directly.
+
+This is the exception that makes isolation workable: isolation without a channel is a wall, not a boundary. Read the channel's `PROTOCOL.md` before writing there.
+
+**Use the broker, not the filesystem.** Graphite exposes the channel as MCP tools, so you never need write access outside your own repository — and if you are sandboxed to your workspace, these are the only way in:
+
+| tool | what it does |
+| --- | --- |
+| `graphite_channel_inbox` | messages addressed to you that you have not been handed yet — **call this at the start of a session** |
+| `graphite_channel_post` | write a new round |
+| `graphite_channel_status` | `acknowledged` / `blocked` (give a reason) / `done` / `withdrawn` |
+| `graphite_channel_list` | every round with its author and current status |
+| `graphite_channel_read` | one round by number |
+
+Four things that will bite you if you assume otherwise:
+
+- **You cannot post as another agent.** There is no author field; your identity comes from the repository the server runs in. `unregistered_project` means ask the operator to register you, not look for a way around it.
+- **Rounds are immutable.** Create-only — no edit, no append, no delete. Correct one by posting another with `supersedes`.
+- **Graphite assigns round numbers.** Do not pick one.
+- **Delivery is recorded by the broker**, as `inbox` hands a message over. You cannot assert or decline it, and anything left `delivered` or `acknowledged` for more than 3 days is reported as stalled.
+
+Every commit there carries your agent's `Co-Authored-By` trailer and states its reason; a `commit-msg` hook rejects commits that name no agent, because all agents commit under one identity and the trailer is what makes the history auditable. The broker satisfies that hook for you. An operator can audit the whole channel at any time with `python -m graphite channel report`, which grades every row by what it can actually vouch for.
+
+### Agent boundary vs. tool boundary
+
+These are different questions and one must not be used to argue about the other.
+
+- **An agent** may act only within its own repository.
+- **A tool doing what it was designed to do is not an agent crossing a boundary.** `graphite init` onboarding a repository, or a security gate running against one, is the operator's tooling operating on a repo. That is by design and is not governed by the agent rule.
+
+The distinction belongs to the operator invoking the tool. It is not a licence to reclassify yourself as a tool in order to reach into another repository.
+
+## Canonical Graph Isolation
+
+`scan`, `build`, `report`, `check`, `validate`, `query`, `context`, `impact`,
+`watch`, and `daemon` are inference-free canonical operations. They do not read
+provider credentials, ignore ambient `GRAPHITE_LLM*` configuration, and reject
+legacy non-`none` LLM flags. Model-generated annotations belong only in the
+explicit, non-authoritative overlay boundary and must never replace or modify
+canonical `graph-out` artifacts.
+
+## Operating Rules
+
+- Treat Graphite as a project map, not as proof of correctness.
+- Always read the source files and tests that Graphite identifies before changing behavior.
+- Graphite-first: prefer graph commands over manual cross-file search; fall back only when the graph answer is insufficient, and say so.
+- If `python -m graphite check .` reports stale output, rebuild before relying on context or impact data.
+- Canonical Graphite operations run locally and never use LLM or network inference.
+- For TypeScript resolver issues, use `python -m graphite --typescript-resolver disabled build .` only as a fallback.
+- Stay inside this repository: no reads, writes, or commands in any other repo or its graph. Findings about another repo go to its agent as a recommendation via the shared `.agent-channel/`.
+"""
+
+SHARED_POINTER_HEADER = "## Shared Graphite Instructions"
+SHARED_POINTER = """## Shared Graphite Instructions
+
+Graphite-first is required in this repo. Follow `GRAPHITE.md` before making non-trivial code changes: for cross-file questions (who-calls, where-defined, impact, data flow, structure) run the Graphite commands first; grep/glob are for literal text and filename lookups only. Fall back to manual search only after a Graphite answer proved insufficient, and say so. Use the existing `graph-out/graph.json` as the shared project graph, and do not edit `graph-out/` manually.
+
+**Stay inside this repository.** Do not read, write, or run commands in any other repo, including its graph. Findings about another repo go to its agent as a recommendation through the shared `.agent-channel/` (see its `PROTOCOL.md`); that agent decides and acts. A tool doing its designed job is a separate question from an agent's boundary. See `GRAPHITE.md` section "Repository Isolation".
+"""
+
+CURSOR_POINTER = """---
+description: Graphite-first project context is required before non-trivial code changes
+alwaysApply: true
+---
+
+# Graphite Instructions
+
+Graphite-first is required in this repo. Follow `GRAPHITE.md` before making non-trivial code changes: for cross-file questions (who-calls, where-defined, impact, data flow, structure) run the Graphite commands first; grep/glob are for literal text and filename lookups only. Fall back to manual search only after a Graphite answer proved insufficient, and say so. Use the existing `graph-out/graph.json` as the shared project graph, and do not edit `graph-out/` manually.
+"""
+
+PLATFORM_ORDER: tuple[str, ...] = (
+    "codex",
+    "claude",
+    "gemini",
+    "antigravity",
+    "visual-studio",
+    "cursor",
+    "windsurf",
+)
+
+DEFAULT_PLATFORMS: tuple[str, ...] = (
+    "codex",
+    "claude",
+    "antigravity",
+    "visual-studio",
+)
+
+
+@dataclass(frozen=True)
+class PlatformSpec:
+    key: str
+    label: str
+    files: tuple[str, ...]
+    content: str = SHARED_POINTER
+
+
+PLATFORMS: dict[str, PlatformSpec] = {
+    "codex": PlatformSpec("codex", "Codex CLI / Codex Desktop", ("AGENTS.md",)),
+    "claude": PlatformSpec("claude", "Claude Code", ("CLAUDE.md",)),
+    "gemini": PlatformSpec("gemini", "Gemini CLI", ("GEMINI.md",)),
+    "antigravity": PlatformSpec("antigravity", "Antigravity IDE", ("ANTIGRAVITY.md",)),
+    "visual-studio": PlatformSpec("visual-studio", "Visual Studio / GitHub Copilot", (".github/copilot-instructions.md",)),
+    "cursor": PlatformSpec("cursor", "Cursor", (".cursor/rules/graphite.mdc",), CURSOR_POINTER),
+    "windsurf": PlatformSpec("windsurf", "Windsurf", (".windsurfrules",)),
+}
+
+ALIASES: dict[str, str] = {
+    "agent": "codex",
+    "agents": "codex",
+    "codex-cli": "codex",
+    "codex-desktop": "codex",
+    "claude-code": "claude",
+    "gemini-cli": "gemini",
+    "google-gemini": "gemini",
+    "google-antigravity": "antigravity",
+    "vs": "visual-studio",
+    "vscode": "visual-studio",
+    "visualstudio": "visual-studio",
+    "visual-studio-code": "visual-studio",
+    "copilot": "visual-studio",
+    "github-copilot": "visual-studio",
+}
+
+
+def managed_doc_paths() -> tuple[Path, ...]:
+    """Every repo-relative path `init` may generate, as the one source of
+    truth for "graphite wrote this file".
+
+    Derived from `PLATFORMS` rather than listed by hand so that adding a
+    platform cannot silently leave its file unwatched by
+    `doctor.check_managed_docs` -- the same one-true-registry argument
+    `ensure_platform_file` already relies on. `GRAPHITE.md` and
+    `.claude/settings.json` are added explicitly because they are written
+    outside the platform loop (`run_init` steps for the shared doc and the
+    agent-hook settings), and `.vscode/tasks.json` likewise
+    (`ensure_vscode_activation_task`).
+
+    `.vscode/tasks.json` was missing here until 2026-07-31, and the cost was
+    concrete: `graphite init` wrote it into aramid's repo on 07-28 and it sat
+    untracked for three days on a machine running this very check, which is how
+    graphite came to assert three rounds running that it had never written
+    there. A registry that omits a path is indistinguishable from a clean repo.
+
+    Git hooks are deliberately NOT here -- their directory is not a fixed
+    repo-relative path (`hookinstall.hooks_dir` honours an existing
+    `core.hooksPath`), so they need a root to resolve. See
+    `doctor.managed_hook_paths`.
+
+    Returns the full candidate set, not the set present in any given repo:
+    callers filter by existence, because a platform a repo never selected is
+    absent and that is not a finding.
+    """
+    paths = {
+        Path("GRAPHITE.md"),
+        Path(".claude/settings.json"),
+        Path(".vscode/tasks.json"),
+        # `.mcp.json` is how the channel broker actually reaches a repo. Left out
+        # of this set it would be generated and then never checked, which is the
+        # exact failure `.vscode/tasks.json` had until 2026-07-31.
+        Path(".mcp.json"),
+    }
+    for spec in PLATFORMS.values():
+        paths.update(Path(rel) for rel in spec.files)
+    return tuple(sorted(paths, key=lambda path: path.as_posix()))
+
+
+@dataclass(frozen=True)
+class InitResult:
+    project_root: Path
+    platforms: tuple[str, ...]
+    graphite_doc: dict[str, Any]
+    gitignore: dict[str, Any]
+    platform_files: list[dict[str, Any]]
+    allowlist: dict[str, Any]
+    daemon: dict[str, Any]
+    agent_hooks: dict[str, Any]
+    hooks: dict[str, Any]
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "project_root": str(self.project_root),
+            "platforms": list(self.platforms),
+            "graphite_doc": self.graphite_doc,
+            "gitignore": self.gitignore,
+            "platform_files": self.platform_files,
+            "allowlist": self.allowlist,
+            "daemon": self.daemon,
+            "agent_hooks": self.agent_hooks,
+            "hooks": self.hooks,
+        }
+
+
+def platform_choices() -> list[dict[str, str]]:
+    return [{"key": key, "label": PLATFORMS[key].label} for key in PLATFORM_ORDER]
+
+
+def resolve_platform_selection(
+    requested: Iterable[str] | None,
+    *,
+    interactive: bool = False,
+    stdin: TextIO | None = None,
+    stdout: TextIO | None = None,
+) -> tuple[str, ...]:
+    tokens = [token for value in requested or [] for token in _split_platform_tokens(value)]
+    if not tokens and interactive:
+        tokens = list(_prompt_for_platforms(stdin=stdin, stdout=stdout))
+    if not tokens:
+        tokens = list(DEFAULT_PLATFORMS)
+
+    resolved: list[str] = []
+    for token in tokens:
+        normalized = _normalize_platform(token)
+        if normalized == "all":
+            for key in PLATFORM_ORDER:
+                if key not in resolved:
+                    resolved.append(key)
+            continue
+        if normalized not in PLATFORMS:
+            valid = ", ".join([*PLATFORM_ORDER, "all"])
+            raise ValueError(f"unknown platform '{token}'. Valid platforms: {valid}")
+        if normalized not in resolved:
+            resolved.append(normalized)
+    return tuple(resolved)
+
+
+def _is_git_repo(root: Path) -> bool:
+    """Ground truth, not a `.git`-exists heuristic: `--is-inside-work-tree`
+    also answers correctly for a repo `root` nested inside a larger one,
+    matching how `hookinstall`'s own `git -C root ...` calls resolve."""
+    result = subprocess.run(
+        ["git", "-C", str(root), "rev-parse", "--is-inside-work-tree"],
+        capture_output=True, text=True,
+        # See `channel._git`: `text=True` alone uses the locale codec, and a
+        # decode failure returns None instead of raising -- which here would
+        # read as "not a git repo" and silently skip hook installation.
+        encoding="utf-8", errors="replace",
+    )
+    return result.returncode == 0 and result.stdout.strip() == "true"
+
+
+def init_project(
+    project_root: Path,
+    *,
+    platforms: Iterable[str],
+    daemon_base: Path | None = None,
+    agent_hooks_mode: str | None = None,
+    install_agent_hooks: bool = True,
+    install_hooks: bool = True,
+    interpreter: Path | None = None,
+    adopt: bool = False,
+) -> InitResult:
+    root = project_root.resolve()
+    if not root.exists():
+        raise FileNotFoundError(root)
+    if not root.is_dir():
+        raise NotADirectoryError(root)
+
+    selected = resolve_platform_selection(platforms)
+    graphite_doc = ensure_graphite_doc(root / "GRAPHITE.md", adopt=adopt)
+    gitignore = ensure_gitignore(root / ".gitignore")
+    platform_files: list[dict[str, Any]] = []
+    instruction_paths = [Path("GRAPHITE.md")]
+
+    for key in selected:
+        spec = PLATFORMS[key]
+        for rel in spec.files:
+            rel_path = Path(rel)
+            platform_files.append(ensure_platform_file(root / rel_path, spec=spec, adopt=adopt))
+            instruction_paths.append(rel_path)
+
+    if install_agent_hooks:
+        # Strict is the default for every caller, not just the CLI. A setting
+        # that must be applied by sweeping repos decays as soon as a new repo
+        # appears, and the sweep itself rebuilds repos nobody has open. Strict
+        # denials are health-gated and re-arm on their own, so this cannot trap
+        # an agent behind a bad graph.
+        agent_hooks = ensure_claude_settings(root, mode=agent_hooks_mode or "strict")
+        instruction_paths.append(Path(".claude/settings.json"))
+    else:
+        agent_hooks = {
+            "path": str(root / ".claude" / "settings.json"),
+            "changed": False,
+            "action": "skipped",
+            "mode": None,
+        }
+
+    if install_hooks and _is_git_repo(root):
+        # Same reasoning as install_agent_hooks above: hooks-on is the default
+        # for every caller, not just the CLI. A setting applied by sweeping
+        # repos by hand decays the moment a new repo appears, and relocation
+        # (see hookinstall's docstring) means turning this on is never a
+        # surprise to another tool's hooks -- only ever reported.
+        relocated = hookinstall.install_hooks(root, interpreter or Path(sys.executable))
+        hooks_result: dict[str, Any] = {
+            "path": str(hookinstall.hooks_dir(root)),
+            "action": "installed",
+            "relocated": relocated,
+        }
+    elif install_hooks:
+        # Not a git repo (yet). `hookinstall.install_hooks` would still write
+        # trampolines into `.githooks/`, but with no `.git` for `core.hooksPath`
+        # to live in, git would never dispatch to them -- reporting "installed"
+        # here would be a confident, silent wrong answer. Report honestly and
+        # skip, rather than leave inert files that look like they did something.
+        hooks_result = {
+            "path": str(root / hookinstall.DEFAULT_HOOKS_DIRNAME),
+            "action": "skipped",
+            "relocated": [],
+            "reason": "not a git repository",
+        }
+    else:
+        # install_hooks=False says nothing about whether this is a git repo
+        # (unlike the branch above) -- go through hookinstall.hooks_dir so an
+        # existing core.hooksPath (husky et al.) is still reported accurately
+        # rather than defaulting to a path graphite wouldn't actually use.
+        hooks_result = {
+            "path": str(hookinstall.hooks_dir(root)),
+            "action": "skipped",
+            "relocated": [],
+        }
+
+    ensure_vscode_activation_task(root / ".vscode" / "tasks.json")
+    ensure_mcp_config(root / ".mcp.json")
+    # Measured after the files are written -- `ls-files --others` only sees
+    # what exists on disk, and a file init just created is exactly the one at
+    # risk of being swallowed.
+    # `init` also writes the VS Code task, and a repo that ignores `.vscode/`
+    # swallows it exactly as it would an instruction file. `tasks.json` is
+    # portable -- `python -m graphite activate .`, no absolute paths -- so
+    # committing it is correct. The hook trampolines are NOT included: they
+    # embed this machine's interpreter path and are ignored, not committed.
+    managed_paths = [*instruction_paths, Path(".vscode/tasks.json"), Path(".mcp.json")]
+    allowlist = ensure_gitignore_allowlist(
+        root / ".gitignore",
+        managed_paths,
+        swallowed=gitignored_managed_paths(root, managed_paths),
+    )
+    daemon = daemon_visibility(root, daemon_base=daemon_base)
+    return InitResult(
+        project_root=root,
+        platforms=selected,
+        graphite_doc=graphite_doc,
+        gitignore=gitignore,
+        platform_files=platform_files,
+        allowlist=allowlist,
+        daemon=daemon,
+        agent_hooks=agent_hooks,
+        hooks=hooks_result,
+    )
+
+
+VSCODE_ACTIVATION_LABEL = "graphite: activate repo"
+
+
+def ensure_vscode_activation_task(path: Path) -> dict[str, Any]:
+    """Register this repo as open when the folder is opened in an editor.
+
+    VS Code, Cursor and Antigravity are all VS Code-derived and honour
+    ``runOn: folderOpen``. This is what lets a repo edited outside an agent CLI
+    still be supervised, without the daemon scanning anything.
+
+    Existing tasks are preserved: destroying hand-written config is the #13
+    mistake, and a tasks.json is far more likely to be hand-written than not.
+    An unparseable file is left completely alone rather than replaced.
+    """
+    document: dict[str, Any] = {"version": "2.0.0", "tasks": []}
+    if path.is_file():
+        try:
+            loaded = json.loads(path.read_text(encoding="utf-8"))
+        except Exception:
+            return {"path": str(path), "changed": False, "action": "skipped", "reason": "unparseable"}
+        if isinstance(loaded, dict):
+            document = loaded
+            document.setdefault("version", "2.0.0")
+            if not isinstance(document.get("tasks"), list):
+                document["tasks"] = []
+
+    existing = [t for t in document["tasks"] if isinstance(t, dict)]
+    kept = [t for t in existing if t.get("label") != VSCODE_ACTIVATION_LABEL]
+    kept.append(
+        {
+            "label": VSCODE_ACTIVATION_LABEL,
+            "type": "shell",
+            # `-P` for the same reason as `.mcp.json`, and this one is worse in
+            # one respect: `runOn: folderOpen` below means it fires by itself.
+            # Nobody has to invoke anything -- opening the folder in VS Code,
+            # Cursor or Antigravity executes a planted `graphite.py`.
+            "command": "python -P -m graphite activate .",
+            "presentation": {"reveal": "never", "panel": "dedicated"},
+            "runOptions": {"runOn": "folderOpen"},
+        }
+    )
+    document["tasks"] = kept
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(document, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    return {"path": str(path), "changed": True, "action": "written"}
+
+
+MCP_SERVER_NAME = "graphite"
+
+
+def ensure_mcp_config(path: Path) -> dict[str, Any]:
+    """Register graphite's MCP server so the channel broker actually reaches a repo.
+
+    Without this the channel tools have to be wired by hand, per repo, per agent
+    -- which is how a capability ends up existing and unused. `init` writing it
+    is the difference between the broker working everywhere and working only
+    where somebody remembered.
+
+    The command is `python -m graphite.mcp`, never `sys.executable`. This file is
+    committed and pushed in consumer repos, so an absolute interpreter path would
+    publish this machine's layout onto their remotes AND break on every other
+    machine. That is the same reason the hook trampolines are gitignored rather
+    than committed -- and the same mistake a guard caught here on 2026-08-01.
+
+    Other servers are preserved: destroying hand-written config is the #13
+    mistake, and an `.mcp.json` is very likely to have other servers in it. An
+    unparseable file is left completely alone rather than replaced.
+    """
+    document: dict[str, Any] = {"mcpServers": {}}
+    if path.is_file():
+        try:
+            loaded = json.loads(path.read_text(encoding="utf-8"))
+        except Exception:
+            return {"path": str(path), "changed": False, "action": "skipped", "reason": "unparseable"}
+        if isinstance(loaded, dict):
+            document = loaded
+            if not isinstance(document.get("mcpServers"), dict):
+                document["mcpServers"] = {}
+
+    # `-P` FIRST. This launches with the consumer's repo root as cwd, so
+    # `python -m graphite.mcp` puts that root at `sys.path[0]` and a
+    # `graphite.py` -- or a `graphite/` directory -- there beats the installed
+    # package. Same defect as the agent hooks and the git trampolines, on a
+    # surface neither of those fixes covered (found by codex-agent, round 62).
+    #
+    # It is the most serious of the three: MCP is how every non-Claude agent
+    # reaches graphite, so a shadowed launch means the agent is talking to
+    # whatever the repository planted, over the channel broker's own transport.
+    #
+    # `-P` rather than `-I` here, unlike the committed commit-msg hook: this
+    # command is run by graphite's own supported interpreters (>=3.11), and `-I`
+    # would additionally strip PYTHONPATH and user site-packages, which an
+    # editable or user install can legitimately need.
+    document["mcpServers"][MCP_SERVER_NAME] = {
+        "command": "python",
+        "args": ["-P", "-m", "graphite.mcp"],
+    }
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(document, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    return {"path": str(path), "changed": True, "action": "written"}
+
+
+def _managed_block(body: str) -> str:
+    if not body.endswith("\n"):
+        body += "\n"
+    return f"{MANAGED_BEGIN}\n{body}{MANAGED_END}"
+
+
+def _ensure_managed_text(
+    original: str, body: str, *, is_legacy: bool, heading: str = "", adopt: bool = False
+) -> tuple[str | None, str]:
+    """Return (new_text_or_None, action) for a versioned managed region."""
+    begin = _MANAGED_BEGIN_RE.search(original)
+    if begin is not None:
+        end_index = original.find(MANAGED_END, begin.end())
+        if end_index < 0:
+            return None, "managed markers damaged"
+        version = int(begin.group(1))
+        if version == DOC_VERSION:
+            return None, "already current"
+        if version > DOC_VERSION:
+            return None, "newer than tool"
+        replaced = (
+            original[: begin.start()]
+            + _managed_block(body)
+            + original[end_index + len(MANAGED_END):]
+        )
+        return replaced, "refreshed"
+
+    if is_legacy:
+        if not adopt:
+            # Pre-versioning content, possibly hand-curated; never rewrite it
+            # automatically. Reported so the operator can reconcile and opt in.
+            return None, "legacy unversioned"
+        # --adopt is that opt-in. It APPENDS the managed block and leaves the
+        # legacy text untouched above it, so hand-curated owner policy survives
+        # (#13). Nothing is overwritten: this is the same non-destructive path
+        # an unmarked non-legacy doc already takes, and once the markers exist
+        # later runs refresh normally.
+        return _append_section(original, _managed_block(body)), "adopted"
+
+    if not original.strip():
+        return heading + _managed_block(body) + "\n", "created"
+    return _append_section(original, _managed_block(body)), "updated"
+
+
+def ensure_graphite_doc(path: Path, *, adopt: bool = False) -> dict[str, Any]:
+    original = path.read_text(encoding="utf-8") if path.exists() else ""
+    new_text, action = _ensure_managed_text(
+        original,
+        GRAPHITE_DOC,
+        is_legacy=GRAPHITE_DOC_HEADER in original and GRAPHITE_REQUIRED_WORKFLOW in original,
+        adopt=adopt,
+    )
+    if new_text is not None:
+        atomic_write_text(path, new_text)
+    return {"path": str(path), "changed": new_text is not None, "action": action}
+
+
+def ensure_platform_file(path: Path, *, spec: PlatformSpec, adopt: bool = False) -> dict[str, Any]:
+    original = path.read_text(encoding="utf-8") if path.exists() else ""
+    new_text, action = _ensure_managed_text(
+        original,
+        spec.content,
+        is_legacy="GRAPHITE.md" in original and "graph-out/graph.json" in original,
+        heading=f"# {spec.label} Project Instructions\n\n",
+        adopt=adopt,
+    )
+    if new_text is not None:
+        atomic_write_text(path, new_text)
+    return {"platform": spec.key, "path": str(path), "changed": new_text is not None, "action": action}
+
+
+def gitignored_managed_paths(root: Path, rel_paths: Iterable[Path]) -> tuple[str, ...]:
+    """Managed paths Git will never hand to a clone: untracked AND ignored.
+
+    The conjunction matters in both directions, and each half alone is a bug
+    that was measured live on 2026-07-31. `git status` -- even with
+    `--ignored=matching` -- collapses the report to the ignored DIRECTORY
+    (`.claude/`), which never matches the managed path, so it reported
+    `BytesAI Learning`'s hook file as fine. `git check-ignore` alone answers
+    "does a pattern match?", which is true but inert for an already-tracked
+    file, so it would have condemned `demo-store2`'s tracked `CLAUDE.md`.
+
+    `ls-files --others --ignored` is the conjunction itself: `--others`
+    restricts to untracked, `--ignored` to ignored. Tracked-and-matched drops
+    out by Git's own semantics rather than by a rule reimplemented here.
+
+    Fails open (empty) on any Git trouble: a repo that cannot be interrogated
+    is not evidence of a swallowed file, and this result gates a `.gitignore`
+    rewrite.
+    """
+    wanted = {Path(rel).as_posix() for rel in rel_paths}
+    if not wanted:
+        return ()
+    try:
+        result = GitRunner(root).run(
+            ["ls-files", "-z", "--others", "--ignored", "--exclude-standard", "--", *sorted(wanted)],
+            timeout_seconds=10.0,
+            max_stdout_bytes=1024 * 1024,
+        )
+        if result.returncode != 0:
+            return ()
+        found = {entry for entry in result.stdout.decode("utf-8").split("\0") if entry}
+    except (GitError, OSError, UnicodeDecodeError):
+        return ()
+    return tuple(sorted(found & wanted))
+
+
+def ensure_gitignore_allowlist(path: Path, rel_paths: Iterable[Path], *, swallowed: Iterable[Path] = ()) -> dict[str, Any]:
+    if not path.exists():
+        return {"path": str(path), "changed": False, "added": [], "reason": "missing gitignore"}
+    original = path.read_text(encoding="utf-8")
+    lines = original.splitlines()
+    default_deny = any(line.strip() == "/*" for line in lines)
+    # `default_deny` is a prediction -- a `/*` gitignore will swallow managed
+    # files, so allowlist them all up front. `swallowed` is a measurement:
+    # these specific files are being swallowed right now, by whatever rule.
+    #
+    # Measuring as well as predicting is what closes the `BytesAI Learning`
+    # case: an ordinary allow-by-default gitignore with a plain `.claude/`
+    # deny is not default-deny, so init wrote the file carrying the
+    # graph-first hook into a path Git would never take -- and reported
+    # success. Repair only what is measured, so a repo that merely looks
+    # unusual keeps its .gitignore untouched.
+    swallowed = tuple(swallowed)
+    if not default_deny and not swallowed:
+        return {"path": str(path), "changed": False, "added": [], "reason": "not default-deny"}
+    targets: list[Path] = list(rel_paths) if default_deny else []
+    for rel in swallowed:
+        candidate = Path(rel)
+        if candidate not in targets:
+            targets.append(candidate)
+
+    existing = {line.strip() for line in lines}
+    added: list[str] = []
+    # A sandwich is emitted WHOLE or not at all, and deduped only within this
+    # run -- never against patterns already in the file. gitignore is
+    # last-match-wins, so appending the complete unit is what guarantees the
+    # re-ignore lands before the file negation. Skipping a pattern merely
+    # because it appears somewhere earlier inverts the sandwich: with
+    # `/.githooks/*` already present, emitting only `!/.githooks/` and
+    # `!/.githooks/post-commit` puts the directory un-ignore last and exposes
+    # `post-commit.local`, the private hook the sandwich exists to protect.
+    #
+    # Idempotent because the guard is "are they ALL already here" -- once the
+    # unit has been appended, a later run skips it and writes nothing.
+    for rel in targets:
+        patterns = _allowlist_patterns(rel)
+        if not patterns or all(pattern in existing for pattern in patterns):
+            continue
+        for pattern in patterns:
+            if pattern not in added:
+                added.append(pattern)
+
+    if added:
+        new_text = original
+        if new_text and not new_text.endswith("\n"):
+            new_text += "\n"
+        if new_text and not new_text.endswith("\n\n"):
+            new_text += "\n"
+        new_text += "\n".join(added) + "\n"
+        atomic_write_text(path, new_text)
+    return {"path": str(path), "changed": bool(added), "added": added, "reason": "default-deny" if default_deny else "swallowed"}
+
+
+def _prompt_for_platforms(*, stdin: TextIO | None, stdout: TextIO | None) -> tuple[str, ...]:
+    stdin = stdin or __import__("sys").stdin
+    stdout = stdout or __import__("sys").stdout
+    print("Select AI platforms to configure for Graphite:", file=stdout)
+    for index, key in enumerate(PLATFORM_ORDER, start=1):
+        print(f"  {index}. {PLATFORMS[key].label} [{key}]", file=stdout)
+    default = ", ".join(DEFAULT_PLATFORMS)
+    print("  all. All supported platforms", file=stdout)
+    print(f"Enter numbers/names separated by commas, or press Enter for: {default}", file=stdout)
+    stdout.flush()
+    answer = stdin.readline().strip()
+    if not answer:
+        return DEFAULT_PLATFORMS
+    return tuple(_split_platform_tokens(answer))
+
+
+def _split_platform_tokens(value: str) -> list[str]:
+    return [part.strip() for part in value.replace(";", ",").split(",") if part.strip()]
+
+
+def _normalize_platform(value: str) -> str:
+    token = value.strip().lower().replace("_", "-")
+    if token.isdigit():
+        index = int(token) - 1
+        if 0 <= index < len(PLATFORM_ORDER):
+            return PLATFORM_ORDER[index]
+    return ALIASES.get(token, token)
+
+
+def _append_section(original: str, section: str) -> str:
+    new_text = original
+    if new_text and not new_text.endswith("\n"):
+        new_text += "\n"
+    if new_text and not new_text.endswith("\n\n"):
+        new_text += "\n"
+    new_text += section
+    if not new_text.endswith("\n"):
+        new_text += "\n"
+    return new_text
+
+
+# Directories where a bare "!/dir/" un-ignore would expose more than the one
+# file graphite needs committed, so the patterns are sandwiched instead:
+# un-ignore the directory, re-ignore its contents, un-ignore only our file.
+#
+#   .claude/   holds settings.local.json -- machine-local permissions, possibly
+#              secrets.
+#   .vscode/   holds settings.json and launch.json, routinely user-specific.
+#
+# `.githooks/` is deliberately NOT here and is not allowlisted at all: the
+# trampolines are machine-local (they embed an absolute interpreter path) and
+# are distributed by git template rather than by the repository. See
+# `bootstrap.GRAPHITE_GITIGNORE_LINES`, which ignores them.
+_SANDWICHED_DIRS = frozenset({".claude", ".vscode"})
+
+
+def _allowlist_patterns(rel: Path) -> list[str]:
+    rel = Path(*[part for part in rel.parts if part not in ("", ".")])
+    parts = rel.parts
+    if not parts:
+        return []
+    if parts[0] == DEFAULT_HOOKS_DIRNAME:
+        # Refused here rather than only by not passing hook paths in, because
+        # a guard that lives in one caller is a guard the next caller removes.
+        # Trampolines embed an absolute interpreter path and are distributed by
+        # git template, so un-ignoring them invites committing one machine's
+        # Python location -- and a bare `!/.githooks/` would additionally expose
+        # `post-commit.local`, the private hook graphite chained to but never
+        # wrote. Both were briefly true on 2026-07-31.
+        return []
+    if len(parts) == 2 and parts[0] in _SANDWICHED_DIRS:
+        directory = parts[0]
+        return [f"!/{directory}/", f"/{directory}/*", f"!/{directory}/{parts[1]}"]
+    patterns: list[str] = []
+    if len(parts) > 1:
+        current: list[str] = []
+        for directory in parts[:-1]:
+            current.append(directory)
+            patterns.append("!/" + "/".join(current) + "/")
+    patterns.append("!/" + "/".join(parts))
+    return patterns