Skip to content

Commit 217ec1f

Browse files
cdeustclaude
andcommitted
fix(gitignore): anchor .Codex/ to repo root, report outside worktrees (ADR-1078)
.gitignore's .Codex/ rule (#601) was unanchored, matching a .Codex directory at any depth instead of just the repo root. Anchor to /.Codex/. The condition that rule hid: a git worktree living outside .claude/worktrees/, the only location docs/agent-guidance.md:160-166 names, stays where the owner decided it stays, but is now reported rather than silenced. mcp_server/doctor.py gains an optional, non-blocking "worktree locations" check (surfaced through python -m mcp_server.doctor, check_setup, and /preflight) that lists any git worktree list --porcelain entry outside <main-worktree>/.claude/worktrees/. The allowed root is derived from the main worktree's own listing (always first, per git-worktree(1) section list) rather than git rev-parse --show-toplevel, which resolves to a linked worktree's own path and would false-positive on every sibling worktree run from inside one. Decision recorded as ADR-1078. Co-Authored-By: Claude Sonnet 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01Cz7A6goxVzfKL9NT7k4zDH
1 parent dd29c89 commit 217ec1f

7 files changed

Lines changed: 243 additions & 1 deletion

‎.gitignore‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@ traces/
6363
# .claude/worktrees/ this project's rule names, and the directory was one
6464
# `git add -A` away from being committed (observed 2026-09-16 while
6565
# reviewing PR #600).
66-
.Codex/
66+
/.Codex/
6767
tasks/
6868
benchmarks/snapshots/
6969
.memsearch/

‎CHANGELOG.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,20 @@ adheres to [Semantic Versioning](https://semver.org/).
5555

5656
### Fixed
5757

58+
- **`.gitignore`'s `.Codex/` rule was unanchored, so it matched at any
59+
depth (#601 follow-up, ADR-1078).** `git status` silently swallowed any
60+
nested `.Codex` directory anywhere in the tree, not just the repo-root
61+
one PR #601 intended. Anchored to `/.Codex/`. The condition that rule
62+
was hiding — a git worktree outside `.claude/worktrees/`, the only
63+
location `docs/agent-guidance.md` names — is now reported, never
64+
silenced: `python -m mcp_server.doctor` (and `check_setup`,
65+
`/preflight`) gained an optional, non-blocking `worktree locations`
66+
check that lists any `git worktree list --porcelain` entry outside
67+
`<main-worktree>/.claude/worktrees/`, sourced from the main worktree's
68+
own listing rather than `git rev-parse --show-toplevel` (which
69+
resolves to a linked worktree's own path and would false-positive on
70+
every sibling). The worktree itself is left exactly where it is.
71+
5872
- **Procedural skills are stored on the default backend too (#596).** The
5973
`procedural_skills` table existed only on PostgreSQL, so on SQLite the
6074
session-end writer mined its skills and lost every one to an
Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
<!-- Generated by Cortex wiki_reindex from wiki/adr/cortex/1078-report-out-of-convention-git-worktrees-as-an-optional-doctor-warn.md; ADR-1078. Read-only mirror: edit the canonical wiki page. -->
2+
3+
---
4+
created: 2026-09-16T21:21:15Z
5+
kind: adr
6+
number: 1078
7+
status: accepted
8+
tags: [doctor, worktree, diagnostics]
9+
title: Report out-of-convention git worktrees as an optional doctor WARN
10+
---
11+
# ADR-1078: Report out-of-convention git worktrees as an optional doctor WARN
12+
13+
## Status
14+
15+
accepted
16+
17+
## Context
18+
19+
PR #601 anchored .gitignore's .Codex/ rule to the repo root, which hides Codex-created worktrees living outside .claude/worktrees/ from git status without resolving the condition docs/agent-guidance.md:160-166 names as the only allowed location. The owner decided the worktree itself stays where it is; what was missing was visibility of the condition to the owner.
20+
21+
## Decision
22+
23+
Add an optional (WARN, never FAIL) doctor check, mcp_server/doctor.py, that lists git worktrees registered by 'git worktree list --porcelain' whose path is not under <main-worktree>/.claude/worktrees/. The allowed root is derived from the first worktree block of that same command (the main worktree is always listed first per git-worktree(1) section list), never from 'git rev-parse --show-toplevel', which resolves to the linked worktree when run from inside one and would false-positive on every sibling worktree. The check never blocks doctor's exit code and its fix text cites docs/agent-guidance.md:160-166 as the source of the rule it reports.
24+
25+
## Consequences
26+
27+
Positive: the owner sees the condition (e.g. .Codex/worktrees/... on this machine today) via 'python -m mcp_server.doctor', check_setup, and the preflight command without git status noise. Negative: a marketplace user running doctor inside an unrelated repo that happens to keep worktrees elsewhere will see an advisory WARN naming a Cortex-authored convention; the fix text makes that source explicit so it reads as advisory, not a bug report.

‎mcp_server/doctor.py‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,10 @@
1919
from mcp_server.infrastructure.sqlite_store import SqliteMemoryStore
2020
from mcp_server.infrastructure.backend_marker import effective_backend
2121
from mcp_server.doctor_mcp import run_mcp
22+
from mcp_server.shared.subprocess_safe import run_with_hard_timeout
23+
24+
# source: validate_memory.py:29 precedent (_GIT_CHECK_TIMEOUT_S)
25+
_WORKTREE_LIST_TIMEOUT_S = 2.0
2226

2327

2428
def ensure_reranker_ready():
@@ -247,6 +251,109 @@ def _codebase_pipeline() -> Check:
247251
)
248252

249253

254+
def _worktree_list() -> list[dict[str, object]] | None:
255+
"""Parse ``git worktree list --porcelain``, main worktree first.
256+
257+
precondition: none — safe to call outside a git checkout.
258+
postcondition: returns one dict per worktree block, in the order git
259+
printed them (the main worktree is always first — git-worktree(1)
260+
section list). Each dict carries ``path`` (str), ``bare`` (bool),
261+
``prunable`` (bool). Returns ``None`` when ``git`` is missing, the cwd
262+
isn't a git checkout, or the command times out — every failure mode
263+
of ``run_with_hard_timeout`` collapses to the same "not applicable"
264+
signal, never a raised exception.
265+
266+
source: ADR-1078"""
267+
out = run_with_hard_timeout(
268+
["git", "worktree", "list", "--porcelain"],
269+
cwd=Path.cwd(),
270+
timeout=_WORKTREE_LIST_TIMEOUT_S,
271+
)
272+
if out is None:
273+
return None
274+
entries: list[dict[str, object]] = []
275+
current: dict[str, object] | None = None
276+
for line in out.splitlines():
277+
if line.startswith("worktree "):
278+
if current is not None:
279+
entries.append(current)
280+
current = {
281+
"path": line[len("worktree ") :].strip(),
282+
"bare": False,
283+
"prunable": False,
284+
}
285+
elif line == "bare" and current is not None:
286+
current["bare"] = True
287+
elif line.startswith("prunable") and current is not None:
288+
current["prunable"] = True
289+
if current is not None:
290+
entries.append(current)
291+
return entries or None
292+
293+
294+
def _worktree_locations() -> Check:
295+
"""Optional: WARN when a registered worktree lives outside
296+
``<main-worktree>/.claude/worktrees/``.
297+
298+
Reports only — never fixes, never moves the worktree, never fails
299+
doctor's exit code (``optional=True``). The allowed root is derived
300+
from the FIRST entry ``git worktree list --porcelain`` prints (always
301+
the main worktree, per git-worktree(1) section list), never from
302+
``git rev-parse --show-toplevel`` — that call resolves to the linked
303+
worktree's own path when run from inside one, which would flag every
304+
sibling worktree as a false positive.
305+
306+
source: ADR-1078 (rule reported: docs/agent-guidance.md:160-166)"""
307+
entries = _worktree_list()
308+
if not entries:
309+
return Check(
310+
"worktree locations (optional)", True, "not a git checkout", optional=True
311+
)
312+
313+
main = entries[0]
314+
if main.get("bare"):
315+
return Check(
316+
"worktree locations (optional)",
317+
True,
318+
"bare repository — rule not applicable",
319+
optional=True,
320+
)
321+
322+
allowed_root = (Path(str(main["path"])) / ".claude" / "worktrees").resolve()
323+
outside = [
324+
str(Path(str(e["path"])).resolve())
325+
for e in entries[1:]
326+
if not e.get("prunable")
327+
and not _under(Path(str(e["path"])).resolve(), allowed_root)
328+
]
329+
330+
if not outside:
331+
return Check(
332+
"worktree locations (optional)",
333+
True,
334+
f"all worktrees under {allowed_root}",
335+
optional=True,
336+
)
337+
return Check(
338+
"worktree locations (optional)",
339+
False,
340+
f"outside {allowed_root}: {', '.join(outside)}",
341+
"Move or remove these worktrees — the only allowed location is "
342+
"<repo>/.claude/worktrees/<name>/ "
343+
"(source: docs/agent-guidance.md:160-166).",
344+
optional=True,
345+
)
346+
347+
348+
def _under(path: Path, root: Path) -> bool:
349+
"""True iff ``path`` is ``root`` or a descendant of it (both resolved)."""
350+
try:
351+
path.relative_to(root)
352+
return True
353+
except ValueError:
354+
return False
355+
356+
250357
def _i10_config() -> Check:
251358
"""Verify pool config respects I10 invariant without opening a pool."""
252359
try:
@@ -301,6 +408,7 @@ def _sqlite_store() -> Check:
301408
_methodology_dir,
302409
_i10_config,
303410
_codebase_pipeline, # optional — doesn't fail doctor
411+
_worktree_locations, # optional — doesn't fail doctor
304412
]
305413

306414
SQLITE_CHECKS: list[Callable[[], Check]] = [
@@ -309,6 +417,7 @@ def _sqlite_store() -> Check:
309417
_methodology_dir,
310418
_i10_config,
311419
_codebase_pipeline, # optional — doesn't fail doctor
420+
_worktree_locations, # optional — doesn't fail doctor
312421
]
313422

314423

‎tests_py/test_doctor.py‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@
1010

1111
from __future__ import annotations
1212

13+
import subprocess
14+
1315
import pytest
1416

1517
from mcp_server.doctor import (
@@ -20,6 +22,7 @@
2022
_pg_driver,
2123
_python_version,
2224
_sqlite_store,
25+
_worktree_locations,
2326
active_checks,
2427
ensure_reranker_ready,
2528
run,
@@ -95,6 +98,66 @@ def test_sqlite_store_check_passes_on_fresh_store(self, tmp_path, monkeypatch):
9598
assert "memories" in check.detail
9699

97100

101+
@pytest.fixture
102+
def real_git_repo(tmp_path):
103+
"""Bare-bones repo with an initial commit, git identity set explicitly
104+
(CI runners have none) — mirrors
105+
tests_py/handlers/test_auto_task_record_writer_git_commits.py's
106+
module-local fixture rather than importing across modules."""
107+
repo = tmp_path / "repo"
108+
repo.mkdir()
109+
subprocess.run(["git", "init", "-q"], cwd=repo, check=True)
110+
subprocess.run(
111+
["git", "config", "user.email", "[email protected]"], cwd=repo, check=True
112+
)
113+
subprocess.run(["git", "config", "user.name", "Test"], cwd=repo, check=True)
114+
(repo / "a.txt").write_text("hello\n")
115+
subprocess.run(["git", "add", "a.txt"], cwd=repo, check=True)
116+
subprocess.run(
117+
["git", "commit", "-q", "-m", "initial commit"], cwd=repo, check=True
118+
)
119+
return repo
120+
121+
122+
class TestWorktreeLocations:
123+
"""source: ADR-1078 — the check reports docs/agent-guidance.md:160-166,
124+
never blocks (optional=True), never rewrites the rule."""
125+
126+
def test_main_checkout_only_passes(self, real_git_repo, monkeypatch):
127+
monkeypatch.chdir(real_git_repo)
128+
check = _worktree_locations()
129+
assert check.ok is True
130+
assert check.optional is True
131+
132+
def test_not_a_git_checkout_passes(self, tmp_path, monkeypatch):
133+
monkeypatch.chdir(tmp_path) # plain dir, no .git
134+
check = _worktree_locations()
135+
assert check.ok is True
136+
assert check.optional is True
137+
138+
def test_flags_worktree_outside_claude_worktrees(self, real_git_repo, monkeypatch):
139+
subprocess.run(
140+
["git", "worktree", "add", "-q", ".claude/worktrees/good", "-b", "good"],
141+
cwd=real_git_repo,
142+
check=True,
143+
)
144+
outside = real_git_repo.parent / "outside-wt"
145+
subprocess.run(
146+
["git", "worktree", "add", "-q", str(outside), "-b", "bad"],
147+
cwd=real_git_repo,
148+
check=True,
149+
)
150+
monkeypatch.chdir(real_git_repo)
151+
152+
check = _worktree_locations()
153+
154+
assert check.ok is False
155+
assert check.optional is True
156+
good_path = str((real_git_repo / ".claude" / "worktrees" / "good").resolve())
157+
assert good_path not in check.detail
158+
assert str(outside.resolve()) in check.detail
159+
160+
98161
class TestEnsureRerankerReady:
99162
"""core/reranker_model.py's filesystem seam (issue #560) is unwired
100163
unless a composition root configured it first; ensure_reranker_ready()
Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
---
2+
created: 2026-09-16T21:21:15Z
3+
kind: adr
4+
number: 1078
5+
status: accepted
6+
tags: [doctor, worktree, diagnostics]
7+
title: Report out-of-convention git worktrees as an optional doctor WARN
8+
---
9+
# ADR-1078: Report out-of-convention git worktrees as an optional doctor WARN
10+
11+
## Status
12+
13+
accepted
14+
15+
## Context
16+
17+
PR #601 anchored .gitignore's .Codex/ rule to the repo root, which hides Codex-created worktrees living outside .claude/worktrees/ from git status without resolving the condition docs/agent-guidance.md:160-166 names as the only allowed location. The owner decided the worktree itself stays where it is; what was missing was visibility of the condition to the owner.
18+
19+
## Decision
20+
21+
Add an optional (WARN, never FAIL) doctor check, mcp_server/doctor.py, that lists git worktrees registered by 'git worktree list --porcelain' whose path is not under <main-worktree>/.claude/worktrees/. The allowed root is derived from the first worktree block of that same command (the main worktree is always listed first per git-worktree(1) section list), never from 'git rev-parse --show-toplevel', which resolves to the linked worktree when run from inside one and would false-positive on every sibling worktree. The check never blocks doctor's exit code and its fix text cites docs/agent-guidance.md:160-166 as the source of the rule it reports.
22+
23+
## Consequences
24+
25+
Positive: the owner sees the condition (e.g. .Codex/worktrees/... on this machine today) via 'python -m mcp_server.doctor', check_setup, and the preflight command without git status noise. Negative: a marketplace user running doctor inside an unrelated repo that happens to keep worktrees elsewhere will see an advisory WARN naming a Cortex-authored convention; the fix text makes that source explicit so it reads as advisory, not a bug report.

‎wiki/manifest.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3479,6 +3479,10 @@
34793479
"ADR-1077": {
34803480
"mirror": "ADR-1077-the-advertised-tool-count-is-read-from-the-registries.md",
34813481
"path": "adr/cortex/1077-the-advertised-tool-count-is-read-from-the-registries.md"
3482+
},
3483+
"ADR-1078": {
3484+
"mirror": "ADR-1078-report-out-of-convention-git-worktrees-as-an-optional-doctor-warn.md",
3485+
"path": "adr/cortex/1078-report-out-of-convention-git-worktrees-as-an-optional-doctor-warn.md"
34823486
}
34833487
},
34843488
"project": "cortex",

0 commit comments

Comments
 (0)