David Kong e59752034e docs: address code review findings for issue-1

- Split Validation Checklist into verifiable docs vs deferred implementation checks (AGENTS.md)
- Correct README example output to match actual `git worktree list` format
- Add pi platform version requirement (`pi >= 0.5.0`) to Requirements section
- Add Testing Strategy section with unit, integration, and manual verification procedures (DESIGN.md)
- Document annotated `git worktree list` raw output format with parsing rules (DOMAIN.md)
- Add permission fail condition for `create` tool in Tool Behaviors table

2026-07-24 13:43:13 +10:00

3.2 KiB

Raw Blame History

DOMAIN.md — Git Worktree Concepts

Git Worktrees

A git worktree is a linked working directory that shares the same repository but checks out a different branch. Multiple worktrees can exist simultaneously, each on its own branch, without switching branches in any of them.

Key Commands

git worktree list — show all linked worktrees with paths and branches
git worktree add <path> [branch] — create a new linked worktree
git worktree add -b <new-branch> <path> — create with a new branch
git worktree remove <path> — remove a linked worktree (refuses if uncommitted changes)
git worktree prune — clean up stale entries for deleted worktrees

Terminology

Term	Definition
Main repo	The original repository directory (where `.git/` lives for non-bare repos)
Linked worktree	An additional working directory linked to the same repo via `git worktree add`
Bare repo	A `.git/` without a working tree — used as the central store when all worktrees are linked
Detached HEAD	When a worktree checks out a commit directly instead of a branch

Raw Output Format — `git worktree list`

The parser should expect this exact pipe-separated format from git worktree list:

/home/user/project          abc1234 [main]           # main repo (current)
/tmp/feature-x              def5678 [feature-x]      # linked worktree on a branch
/tmp/detached               fedcba HEAD               # detached HEAD (no branch name)

Field	Position	Description
Path	Column 1	Absolute path to the working tree directory
Hash	Column 2	Short commit hash (HEAD) for this worktree
Branch	Column 3+	Branch name in `[brackets]`, or `HEAD` if detached

Parsing rules:

Lines with [branch-name] → the branch is identified by what's inside the brackets.
Lines with HEAD (no brackets) → detached HEAD; identify this worktree by path only.
The first entry in the output is always the main repo — mark it as isCurrent: true.
Worktrees listed after the first entry are linked worktrees (isCurrent: false).

Constraints (from git itself)

You cannot create a nested worktree (worktree inside a worktree).
Multiple worktrees on the same branch is possible with -f but dangerous and not recommended.
git worktree remove refuses if there are uncommitted or untracked changes.
The main repo counts as a "worktree" in git worktree list.

pi Session Concepts

Term	Definition
Session	A conversation context within pi, tied to a specific cwd/branch
Cwd change	When pi changes its working directory (e.g., switching worktrees)
Branch display	The footer indicator showing which git branch pi is tracking
Back-switching	Restoring the previous session when returning to the main repo from a worktree

How Sessions Relate to Worktrees

Each worktree can have its own session for focused context.
Switching worktrees updates the branch display automatically (pi reads HEAD from the new cwd).
Users are offered a choice: create a fresh session or keep the current one.
Back-switching restores the session that was active before leaving the main repo.

3.2 KiB Raw Blame History