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 7fcb1cb
Browse filesBrowse the repository at this point in the historyBrowse files
<!-- Generated by Cortex wiki_reindex from wiki/adr/cortex/1079-report-out-of-convention-git-worktrees-as-an-optional-doctor-warn.md; ADR-1079. Read-only mirror: edit the canonical wiki page. -->
2
+
3
+
---
4
+
created: 2026-09-16T21:21:15Z
5
+
kind: adr
6
+
number: 1079
7
+
status: accepted
8
+
tags: [doctor, worktree, diagnostics]
9
+
title: Report out-of-convention git worktrees as an optional doctor WARN
10
+
---
11
+
# ADR-1079: Report out-of-convention git worktrees as an optional doctor WARN
12
+
13
+
## Status
14
+
15
+
accepted
16
+
17
+
## Context
18
+
19
+
PR #601 left an unanchored `.Codex/` ignore rule. The repository guidance previously allowed only `.claude/worktrees/`, while the current Codex instructions mandate `.Codex/worktrees/`. Each host needs its own repository-local directory.
20
+
21
+
## Decision
22
+
23
+
Anchor the ignore rule to `/.Codex/`. Add an optional doctor warning for registered worktrees outside both `<main-worktree>/.claude/worktrees/` and `<main-worktree>/.Codex/worktrees/`. Keep the existing Claude convention and honor the current Codex instructions. Update the repository guidance to name both host locations.
24
+
25
+
Derive the roots from the first worktree in `git worktree list --porcelain -z`, which git-worktree(1) documents as the main worktree. This also works from a linked checkout. Skip bare repositories and prunable entries. The check never moves a worktree and never changes the doctor exit code.
26
+
27
+
## Consequences
28
+
29
+
Positive: the owner sees worktrees outside both host directories 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.
30
+
31
+
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.
title: Report out-of-convention git worktrees as an optional doctor WARN
8
+
---
9
+
# ADR-1079: Report out-of-convention git worktrees as an optional doctor WARN
10
+
11
+
## Status
12
+
13
+
accepted
14
+
15
+
## Context
16
+
17
+
PR #601 left an unanchored `.Codex/` ignore rule. The repository guidance previously allowed only `.claude/worktrees/`, while the current Codex instructions mandate `.Codex/worktrees/`. Each host needs its own repository-local directory.
18
+
19
+
## Decision
20
+
21
+
Anchor the ignore rule to `/.Codex/`. Add an optional doctor warning for registered worktrees outside both `<main-worktree>/.claude/worktrees/` and `<main-worktree>/.Codex/worktrees/`. Keep the existing Claude convention and honor the current Codex instructions. Update the repository guidance to name both host locations.
22
+
23
+
Derive the roots from the first worktree in `git worktree list --porcelain -z`, which git-worktree(1) documents as the main worktree. This also works from a linked checkout. Skip bare repositories and prunable entries. The check never moves a worktree and never changes the doctor exit code.
24
+
25
+
## Consequences
26
+
27
+
Positive: the owner sees worktrees outside both host directories 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.
28
+
29
+
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.
0 commit comments