Skip to content

Commit 28aea2a

Browse files
cdeustclaude
andcommitted
fix(doctor): a project without git is not a failed inspection (#602)
_worktree_locations() treated every failure mode of `git worktree list` (no repository, git missing, timeout) as the same "inspection unavailable" WARN. Cortex is an MCP server whose cwd is whatever project the host opened; a project with no Git repository is ordinary, not a failure to inspect, so every such session's preflight showed a WARN whose fix command (`git worktree list --porcelain -z`) can never succeed there. `run_with_hard_timeout` collapses every subprocess failure mode to `None`, so the two cases can't be told apart after the call. A new `_is_git_checkout()` stdlib probe runs first instead — the same upward walk for a `.git` entry that Git itself performs to discover a repository, no subprocess involved. No `.git` anywhere up the tree now reports `ok True, detail "not a git checkout"`; a `.git` present but Git missing from PATH or the listing timing out keeps the optional WARN. Renamed test_not_a_git_checkout_warns to test_not_a_git_checkout_passes (now asserts the ok True case) and added test_git_unavailable_in_a_checkout_warns for the WARN case with a real .git present. Updated the parametrised None case in test_unavailable_or_empty_listing_contract, whose message no longer claims "not a Git checkout" as a possible cause since that case now short-circuits before the subprocess call. ADR-1079's Consequences section records the distinction. Co-Authored-By: Claude Fable 5.1 <[email protected]> Claude-Session: https://claude.ai/code/session_01Cz7A6goxVzfKL9NT7k4zDH
1 parent 7c53741 commit 28aea2a

7 files changed

Lines changed: 65 additions & 6 deletions

‎CHANGELOG.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,11 @@ adheres to [Semantic Versioning](https://semver.org/).
101101
Outside worktrees produce a warning without changing the exit code.
102102
NUL-delimited Git output preserves newlines and spaces in their paths.
103103
Failed Git invocations produce an optional warning with a retry command.
104+
A project with no Git repository at all is an ordinary condition, not a
105+
failure to inspect, so a stdlib `.git` walk now tells that case apart
106+
from Git being unavailable or timing out before the check ever shells
107+
out: `ok True, detail "not a git checkout"` on the former, the warning
108+
kept for the latter.
104109

105110
- **Procedural skills are stored on the default backend too (#596).** The
106111
`procedural_skills` table existed only on PostgreSQL, so on SQLite the

‎CLAUDE.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ the zetetic implementation standard). Read it before any non-trivial change.
2424

2525
- Layers: `server → handlers → core ← shared`, `infrastructure → shared`; handlers are the
2626
only composition roots.
27-
- Every git worktree lives at `.claude/worktrees/<name>/`, never outside the repo.
27+
- Every git worktree lives at `.claude/worktrees/<name>/` (`.Codex/worktrees/<name>/` for
28+
Codex), never outside the repo.
2829
- No source, no implementation; benchmark before commit; no silent fallbacks or
2930
compatibility shims.

‎docs/adr/ADR-1079-report-out-of-convention-git-worktrees-as-an-optional-doctor-warn.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,3 +31,5 @@ Positive: the owner sees worktrees outside both host directories via 'python -m
3131
Git porcelain uses NUL record delimiters with `-z`; parsing those delimiters preserves literal newlines and trailing spaces in paths (git-worktree(1), Porcelain Format). A real-Git regression verifies that an outside worktree with both characters is reported by its exact path.
3232

3333
A failed Git invocation produces an optional WARN that lists the possible causes and provides the Git command to retry. The existing subprocess helper returns no failure category, so the diagnostic does not claim a specific cause. Successful empty output is reported as no registered worktrees.
34+
35+
Cortex is an MCP server whose working directory is whatever project the host opened, so a project with no Git repository is an ordinary condition, not a failure to inspect. The check tells the two cases apart with a stdlib walk from the cwd for a `.git` entry — the same discovery Git itself performs — before ever invoking `git worktree list`: no `.git` anywhere up the tree reports `ok True, detail "not a git checkout"`; a `.git` present but Git missing from PATH or the listing timing out keeps the optional WARN.

‎mcp_server/doctor.py‎

Lines changed: 36 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -327,22 +327,55 @@ def _worktree_classification(entries: list[dict[str, object]]) -> tuple[bool, st
327327
return False, f"outside {allowed}: {', '.join(outside)}"
328328

329329

330+
def _is_git_checkout(start: Path) -> bool:
331+
"""True iff ``start`` or an ancestor holds a ``.git`` entry — the same
332+
upward walk Git itself performs to discover a repository.
333+
334+
precondition: none.
335+
postcondition: returns True on the first ancestor (inclusive) carrying
336+
a ``.git`` path, file or directory (a linked worktree's ``.git`` is a
337+
file, not a directory); False once the filesystem root is reached
338+
without finding one. No subprocess: this only ever needs to tell "no
339+
repository here" apart from "git couldn't answer", which a failed
340+
subprocess call can't distinguish on its own.
341+
342+
source: git-rev-parse(1) "repository discovery" (upward walk from cwd
343+
for a `.git` entry, halting at a filesystem or ceiling boundary)"""
344+
current = start.resolve()
345+
while True:
346+
if (current / ".git").exists():
347+
return True
348+
parent = current.parent
349+
if parent == current:
350+
return False
351+
current = parent
352+
353+
330354
def _worktree_locations() -> Check:
331355
"""Optional: WARN when a registered worktree lives outside
332356
the host-specific ``.claude/worktrees`` or ``.Codex/worktrees``.
333357
Reports only — never fixes,
334358
never moves the worktree, never fails doctor's exit code
335359
(``optional=True``).
336360
361+
postcondition: a project that is not a Git checkout is an ordinary
362+
condition for an MCP server whose cwd is whatever the host opened, not
363+
a failed inspection — ``ok`` is True with detail "not a git checkout".
364+
The WARN (``ok`` False) is reserved for the cases Git itself cannot
365+
answer for: the binary missing from PATH, or the listing timing out.
366+
337367
source: ADR-1079 (rule reported: docs/agent-guidance.md, What NOT to do)"""
368+
if not _is_git_checkout(Path.cwd()):
369+
return Check(
370+
"worktree locations (optional)", True, "not a git checkout", optional=True
371+
)
338372
entries = _worktree_list()
339373
if entries is None:
340374
return Check(
341375
"worktree locations (optional)",
342376
False,
343-
"Unable to inspect worktree locations: not a Git checkout, "
344-
"Git unavailable, or command failed.",
345-
"Run from a Git checkout with Git available; retry "
377+
"Unable to inspect worktree locations: Git unavailable or command failed.",
378+
"Install Git and ensure it's on PATH; retry "
346379
"git worktree list --porcelain -z.",
347380
optional=True,
348381
)

‎tests_py/test_doctor.py‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -169,9 +169,19 @@ def test_main_checkout_only_passes(self, real_git_repo, monkeypatch):
169169
assert check.ok is True
170170
assert check.optional is True
171171

172-
def test_not_a_git_checkout_warns(self, tmp_path, monkeypatch):
172+
def test_not_a_git_checkout_passes(self, tmp_path, monkeypatch):
173173
monkeypatch.chdir(tmp_path) # plain dir, no .git
174174
check = _worktree_locations()
175+
assert check.ok is True
176+
assert check.detail == "not a git checkout"
177+
assert check.optional is True
178+
179+
def test_git_unavailable_in_a_checkout_warns(self, real_git_repo, monkeypatch):
180+
monkeypatch.chdir(real_git_repo)
181+
monkeypatch.setattr(
182+
"mcp_server.doctor.run_with_hard_timeout", lambda *a, **k: None
183+
)
184+
check = _worktree_locations()
175185
assert check.ok is False
176186
assert "Unable to inspect" in check.detail
177187
assert check.optional is True

‎tests_py/test_doctor_worktrees.py‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,14 +10,20 @@
1010

1111
@pytest.mark.parametrize("output", [None, "", "HEAD abc\0\0"])
1212
def test_unavailable_or_empty_listing_contract(monkeypatch, output):
13+
# This test runs inside the real repository checkout, so the `.git`
14+
# probe in `_worktree_locations` passes and a mocked `None` here
15+
# exercises the "Git unavailable or command failed" WARN, not the
16+
# "not a git checkout" pass — that case is covered separately by
17+
# test_not_a_git_checkout_passes / test_git_unavailable_in_a_checkout_warns
18+
# in tests_py/test_doctor.py.
1319
monkeypatch.setattr(doctor, "run_with_hard_timeout", lambda *a, **k: output)
1420
check = doctor._worktree_locations()
1521
assert check.optional
1622
if output is None:
1723
assert doctor._worktree_list() is None
1824
assert check.ok is False
1925
assert "Unable to inspect worktree locations" in check.detail
20-
assert "not a Git checkout, Git unavailable, or command failed" in check.detail
26+
assert "Git unavailable or command failed" in check.detail
2127
assert "git worktree list --porcelain -z" in check.fix
2228
else:
2329
assert doctor._worktree_list() == []

‎wiki/adr/cortex/1079-report-out-of-convention-git-worktrees-as-an-optional-doctor-warn.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,3 +29,5 @@ Positive: the owner sees worktrees outside both host directories via 'python -m
2929
Git porcelain uses NUL record delimiters with `-z`; parsing those delimiters preserves literal newlines and trailing spaces in paths (git-worktree(1), Porcelain Format). A real-Git regression verifies that an outside worktree with both characters is reported by its exact path.
3030

3131
A failed Git invocation produces an optional WARN that lists the possible causes and provides the Git command to retry. The existing subprocess helper returns no failure category, so the diagnostic does not claim a specific cause. Successful empty output is reported as no registered worktrees.
32+
33+
Cortex is an MCP server whose working directory is whatever project the host opened, so a project with no Git repository is an ordinary condition, not a failure to inspect. The check tells the two cases apart with a stdlib walk from the cwd for a `.git` entry — the same discovery Git itself performs — before ever invoking `git worktree list`: no `.git` anywhere up the tree reports `ok True, detail "not a git checkout"`; a `.git` present but Git missing from PATH or the listing timing out keeps the optional WARN.

0 commit comments

Comments
 (0)