docs(decisions): architecture decision for worktree heuristic (#531)

[bradygaster]

Resolves #531 (parent: #525)

Summary

Architecture decision document for worktree vs checkout heuristic. This decision unblocks #528 (worktree variant in ralph-commands.ts) and #529 (coordinator pre-spawn worktree creation).

Key Decisions

1. Opt-in configuration (not heuristic-based)

• Default: worktrees: false (backward compatible)
• Enable: worktrees: true in squad.config.ts or .squad/config.json
• Override: SQUAD_WORKTREES=1 env var

Rationale: Heuristics are brittle. Configuration is explicit and user-controlled.

2. Worktree path convention

• Pattern: {repo-parent}/{repo-name}-{issue}
• Example: Main repo C:\src\squad → Issue chore: remove internal team-docs from main #42 worktree C:\src\squad-42
• Configurable via worktreePath in config

3. Dependency management

• Recommended: Junction (Windows) or symlink (Unix) for node_modules
• Fallback: npm install if junction/symlink fails
• Coordinator handles automatically after git worktree add

4. Platform support

• All 3 adapters (GitHub, Azure DevOps, Planner) get identical worktree support
• Commands: createWorktree, removeWorktree

Implications for Sibling Issues

#528 (ralph-commands.ts):

• Add createWorktree? and removeWorktree? to RalphCommands interface
• No breaking changes

#529 (coordinator pre-spawn):

• Read config at session start
• Create worktree if enabled, pass WORKTREE_PATH to agents
• Handle dependency management

#530 (post-merge cleanup):

• Trigger removeWorktree after PR merge
• Log cleanup, handle failures gracefully

Migration Path

✅ Zero breaking changes — existing workflows use git checkout -b
✅ Teams opt-in when ready
✅ New teams can enable during init

Files Changed

• .squad/decisions/inbox/flight-worktree-heuristic.md — Full architecture decision document

Next Steps

After this PR merges:

1. Scribe merges decision from inbox into .squad/decisions.md
2. EECOM implements feat(#525): Add worktree branch creation variant to ralph-commands.ts #528 (worktree commands)
3. Flight or EECOM implements feat(#525): Add worktree creation to coordinator spawn flow #529 (coordinator flow)
4. Flight or EECOM implements feat(#525): Implement post-merge worktree cleanup lifecycle #530 (cleanup)
5. PAO updates docs

---

Working as Flight (Lead / Architect)