@bicorne/task-flow 0.1.0

package/references/GIT-WORKTREE-SOP.md

@@ -0,0 +1,109 @@
+# Git Worktree SOP
+
+Standard Operating Procedure for git worktree management in task-flow.
+
+## Applicable Scope
+
+This SOP applies to development workflows under task-flow, covering:
+- Main worktree (main branch) Git management
+- Worktree (task branch) Git management
+- Operation boundaries during phase transitions
+
+---
+
+## Role Boundaries
+
+- **Main worktree**: Only for process-level management actions, not task code implementation
+- **Worktree**: Only for corresponding task code changes, verification, and commit preparation
+- **Merge actions**: Executed in the main worktree
+
+---
+
+## Standard Process
+
+### 1. Create Task and Worktree in Main Worktree
+
+```bash
+git worktree add .worktrees/harness-feat-<task-id> -b feat/<task-id>-<desc>
+```
+
+Update:
+- `spec/changes/<change-name>/tasks/PHASE-*.json`
+- `.harness/state.json`
+
+### 2. Enter Worktree for Implementation
+
+```bash
+cd .worktrees/harness-feat-<task-id>
+git status
+```
+
+Complete within this directory:
+- Code modifications
+- Build and test
+- Review preparation
+
+### 3. Execute Merge and Cleanup in Main Worktree
+
+```bash
+cd <project-root>
+git merge feat/<task-id>-<desc> --squash
+git worktree remove .worktrees/harness-feat-<task-id>
+git branch -d feat/<task-id>-<desc>
+```
+
+Update:
+- `.harness/state.json` (clean up corresponding worktree and currentTask)
+
+---
+
+## Must Follow Rules
+
+- Do not modify task code directly in main worktree that should be handled by worktree
+- Do not run multiple agents in a single worktree
+- Do not skip lint/build/test validation
+- Do not force merge without resolving conflicts
+
+---
+
+## Common Troubleshooting
+
+### Worktree Creation Failed
+
+```bash
+git worktree prune
+git branch -D <branch>
+git worktree add <path> -b <branch>
+```
+
+### Merge Conflict
+
+```bash
+git diff --name-only --diff-filter=U
+git merge --abort
+```
+
+### State File Inconsistent with Reality
+
+Order of resolution:
+1. Use `git worktree list` as the source of truth
+2. Correct `.harness/state.json`
+3. Re-check current phase and currentTask
+
+---
+
+## Checklist
+
+Before entering implementation:
+- [ ] Task JSON created
+- [ ] Worktree created with correct branch
+- [ ] state.json recorded current task
+
+Before entering review:
+- [ ] Code completed in target worktree
+- [ ] Lint/test passed
+
+Before merge:
+- [ ] Main worktree is clean
+- [ ] Target branch is mergeable
+- [ ] state.json can be synchronized