git-worktree-isolation

Git Worktree Isolation

用途

• 确保每个开发任务（feature / fix / spike）在 隔离的 worktree + 分支 中执行，主工作区始终保持可切换状态。
• 在多 agent 并行场景下，每个 agent 拥有独立文件系统视图，避免写冲突。
• 任务完成后提供 结构化收口决策（merge / PR / keep / discard），而不是任凭 worktree 积累。

触发信号

• /team-execute 分派的并行实现任务。
• wave-execution 中同一 Wave 的多个工作项。
• 需要在不影响主分支的情况下进行探索性实现或 spike。
• 当前工作区有未提交变更，但需要紧急处理另一个任务。
• Code review 后的修改需要在隔离环境中完成。

核心原则

1. 一个任务 = 一个 worktree = 一个分支——不共用 worktree。
2. worktree 有明确生命周期——创建时绑定任务 ID，完成后必须做收口决策。
3. 主工作区是调度中心——编排和合并在主工作区进行，实现在 worktree 中进行。

工作流

1. 创建隔离环境

# 命名规则: .worktrees/{slug}-{task-id}
git worktree add .worktrees/{slug}-{task-id} -b task/{slug}/{task-id}

# 验证隔离
cd .worktrees/{slug}-{task-id}
git branch --show-current   # → task/{slug}/{task-id}

命名约定：

元素	格式	示例
Worktree 路径	.worktrees/{slug}-{task-id}	.worktrees/auth-T001
分支名	task/{slug}/{task-id}	task/auth/T001
Spike 分支	spike/{slug}/{description}	spike/auth/oauth-flow

2. 在 worktree 中执行

进入 worktree 目录 →
  加载任务上下文（STATE.md 对应工作项）→
  执行实现 →
  运行测试 →
  提交到 worktree 分支

执行约束：

• 每个 worktree 中的 agent 只操作任务范围内的文件。
• 不在 worktree 中修改共享配置（package.json / pom.xml 等），除非任务明确要求。
• 提交信息包含任务 ID：feat(T001): implement auth flow。

3. 收口决策

任务完成后，在 主工作区 执行收口：

决策	条件	操作
Merge	代码通过 review + 测试	git merge task/{slug}/{task-id} + 清理 worktree
PR	需要异步 review 或 CI	创建 PR + 保留 worktree 直到合并
Keep	任务暂停但稳定	标记为 paused，保留 worktree
Discard	spike 完成或方向废弃	删除 worktree + 分支

# Merge 路径
cd /path/to/main-worktree
git merge --no-ff task/{slug}/{task-id} -m "feat(T001): implement auth flow"
git worktree remove .worktrees/{slug}-{task-id}
git branch -d task/{slug}/{task-id}

# Discard 路径
git worktree remove --force .worktrees/{slug}-{task-id}
git branch -D spike/{slug}/{description}

4. 清理巡检

定期（或每次 /team-review 前）执行清理：

# 列出所有 worktree
git worktree list

# 清理已删除的 worktree 引用
git worktree prune

# 查找已合并但未清理的任务分支
git branch --merged main | grep 'task/'

与 parallel-execution 的关系

关注点	parallel-execution	git-worktree-isolation
核心目标	多实例并行加速	任务级文件隔离
Worktree 使用	作为并行基础设施	作为隔离策略
分支管理	自动创建/合并	结构化收口决策
清理策略	任务结束自动清理	显式四选一决策
集成点	wave-execution 调用	为 parallel-execution 提供隔离规范

parallel-execution 调用 git-worktree-isolation 的隔离规范创建 worktree，git-worktree-isolation 依赖 parallel-execution 的任务分发能力。

与 session-continuity 的关系

• /pause 时：记录活跃 worktree 列表到 HANDOFF.json 的 active_worktrees 字段。
• /resume 时：检查 worktree 状态，标记哪些仍然有效、哪些需要清理。

配套约束

1. .worktrees/ 目录加入 .gitignore，不提交到远程仓库。
2. worktree 中不执行 git rebase 主分支——避免在隔离环境中引入合并复杂度。
3. 超过 7 天未活动的 worktree 在清理巡检时标记为候选清理项。
4. 共享锁文件（lockfile）变更在 merge 阶段统一解决，不在 worktree 中各自更新。

验证标准

• 创建的 worktree 路径遵循 .worktrees/{slug}-{task-id} 命名规范
• 每个 worktree 对应唯一分支，无分支共用
• 任务完成后在 24h 内执行收口决策（merge / PR / keep / discard）
• git worktree list 无孤立 worktree
• 已合并分支已被删除