> ## Documentation Index
> Fetch the complete documentation index at: https://prism.ntecdev.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# ADR-43: Git worktrees must live under $PROJECT_ROOT/.worktrees/, not alongside project directories

> # ADR — Git Worktree Location Convention  ## Decision  All git worktrees created by Prism agents (or by `prism install` / bootstrap tooling) MUST be placed unde

<Info>**Status:** `superseded` · **ADR-43** · Filed 2026-05-02</Info>

# ADR — Git Worktree Location Convention

## Decision

All git worktrees created by Prism agents (or by `prism install` / bootstrap tooling) MUST be placed under `$PROJECT_ROOT/.worktrees/<worktree-name>`, never directly in `$PROJECT_ROOT/`.

A per-repo git alias `wt` SHALL be configured at install time:

```
git config alias.wt '!f() { git worktree add "$PROJECT_ROOT/.worktrees/$1" "$2"; }; f'
```

so that `git wt prism-daemon-skeleton daemon/skeleton` automatically lands in the correct location.

The `$PROJECT_ROOT/.worktrees/` directory SHALL be:

* Created by `prism install` (both local and LAN modes)
* Added to the project's `.gitignore` if not already present
* Documented in HOST\_CONTRACT.md

## Rationale

Git does not allow worktrees inside the repo they belong to (nested `.git` references are ambiguous). Agents defaulted to creating worktrees in `$PROJECT_ROOT/` — the parent directory — because it was the simplest path satisfying git's constraint. This caused 28 worktree directories to accumulate alongside actual project directories (Prism, MemRGR, DFW), making `~/projects/` unreadable and confusing to the operator.

A hidden dot-directory (`.worktrees/`) keeps `$PROJECT_ROOT/` clean for actual projects while remaining persistent and accessible. The git alias eliminates the need for agents to remember or construct the path manually.

## Alternatives Considered

1. **`$PROJECT_ROOT/<ProjectName>-worktrees/`** — visible, explicit, but still clutters the project listing and requires per-project naming.
2. **`/tmp/prism-worktrees/`** — ephemeral, cleaned on reboot, unsuitable for long-lived feature branches.
3. **No convention (status quo)** — rejected; 28 stray directories in `~/projects/` is the direct consequence.
4. **Per-repo `.worktrees/` inside each project** — rejected; git prohibits worktrees nested inside their parent repo.

## Implementation

1. **Retrofit (Donna):** Prune merged-branch worktrees, `git worktree move` surviving ones to `$PROJECT_ROOT/.worktrees/`, run `git worktree prune`.
2. **Install integration (Lafonda):** Add `mkdir -p $PROJECT_ROOT/.worktrees` + git alias setup to `prism install` flow in `cli/src/index.ts`.
3. **Methodology rule:** Agents creating worktrees MUST use the alias or the full `.worktrees/` path. Direct `git worktree add ../<name>` in `$PROJECT_ROOT/` is a methodology violation.