You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 217ec1f
Browse filesBrowse the repository at this point in the historyBrowse files
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
<!-- 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.
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.
0 commit comments