Codewalkers/.planning/phases/03-git-integration/03-02-PLAN.md

phase, plan, type, wave, depends_on, files_modified, autonomous

phase	plan	type	wave	depends_on	files_modified	autonomous
03-git-integration	02	execute	2	03-01	src/git/manager.ts src/git/manager.test.ts src/git/index.ts package.json	true

Implement WorktreeManager adapter with simple-git and comprehensive tests.

Purpose: Provide working git worktree operations that Phase 4 (Agent Lifecycle) will use to isolate agent work. Output: Fully tested WorktreeManager implementation covering create, remove, list, diff, and merge operations.

<execution_context> @/.claude/get-shit-done/workflows/execute-plan.md @/.claude/get-shit-done/templates/summary.md </execution_context>

@.planning/PROJECT.md @.planning/ROADMAP.md @.planning/STATE.md

Prior plan in this phase

@.planning/phases/03-git-integration/03-01-SUMMARY.md

Git types we're implementing

@src/git/types.ts

Event bus for emitting git events

@src/events/types.ts @src/events/bus.ts

Test pattern reference

@src/db/repositories/drizzle/test-helpers.ts

Task 1: Install simple-git and create WorktreeManager adapter with CRUD package.json, src/git/manager.ts, src/git/index.ts 1. Install simple-git: npm install simple-git

2. Create src/git/manager.ts with SimpleGitWorktreeManager class:

   • Constructor takes: repoPath (string), eventBus (optional EventBus)
   • Private simpleGit instance initialized with repoPath
   • Private worktreesDir computed as path.join(repoPath, '.cw-worktrees')

3. Implement CRUD methods:

   • create(id, branch, baseBranch = 'main'):

     • Compute worktree path: path.join(worktreesDir, id)
     • Run: git worktree add -b {branch} {path} {baseBranch}
     • Emit worktree:created event if eventBus provided
     • Return Worktree object

   • remove(id):

     • Compute worktree path
     • Run: git worktree remove {path} --force
     • Emit worktree:removed event if eventBus provided

   • list():

     • Run: git worktree list --porcelain
     • Parse output into Worktree[] (skip main worktree or mark isMainWorktree: true)

   • get(id):

     • Call list(), find by id (match path ending with id)
     • Return null if not found

4. Update src/git/index.ts to export SimpleGitWorktreeManager

Use async/await throughout. Handle errors by throwing with descriptive messages. Follow the EventEmitterBus pattern - eventBus is optional dependency injection. npm run build passes, SimpleGitWorktreeManager is importable WorktreeManager adapter created with create, remove, list, get methods

Task 2: Implement diff and merge operations src/git/manager.ts Add remaining methods to SimpleGitWorktreeManager:

1. diff(id):

   • Get worktree by id (throw if not found)
   • cd into worktree path
   • Run: git diff --name-status HEAD
   • Parse output into WorktreeDiff format:
     • Map each line to { path, status } based on status letter (A=added, M=modified, D=deleted)
     • Generate summary: "{n} files changed"
   • Also run: git diff --stat HEAD for the summary line

2. merge(id, targetBranch):

   • Get worktree by id (throw if not found)
   • In MAIN repo (not worktree), run:
     • git checkout {targetBranch}
     • git merge {worktree.branch} --no-edit
   • If merge succeeds:
     • Emit worktree:merged event
     • Return { success: true, message: 'Merged successfully' }
   • If merge fails with conflicts:
     • Parse conflicting files from git status
     • Emit worktree:conflict event
     • Run git merge --abort to clean up
     • Return { success: false, conflicts: [...], message: 'Merge conflicts detected' }

Handle edge cases:

• Worktree not found: throw Error('Worktree not found: {id}')
• No changes to diff: return empty WorktreeDiff
• Branch doesn't exist: let git error propagate with clear message npm run build passes diff() and merge() methods implemented with proper event emission and conflict handling

Task 3: Write tests for WorktreeManager src/git/manager.test.ts Create comprehensive tests following the repository test pattern:

1. Test setup:

   • Create temp directory for each test (use Node.js fs.mkdtemp)
   • Initialize git repo in temp dir: git init, git commit --allow-empty -m "Initial"
   • Create SimpleGitWorktreeManager with temp repo path
   • Cleanup: remove temp dir after each test

2. Test cases for CRUD:

   • create() creates worktree at expected path
   • create() creates branch from specified base
   • create() emits worktree:created event
   • remove() removes worktree directory
   • remove() emits worktree:removed event
   • list() returns all worktrees
   • list() marks main worktree correctly
   • get() returns worktree by id
   • get() returns null for non-existent id

3. Test cases for diff:

   • diff() returns empty for clean worktree
   • diff() detects added files
   • diff() detects modified files
   • diff() detects deleted files

4. Test cases for merge:

   • merge() succeeds with clean merge
   • merge() emits worktree:merged event on success
   • merge() detects conflicts and returns them
   • merge() emits worktree:conflict event on conflict
   • merge() aborts and cleans up after conflict

Use vitest (already in project). Create helper function createTestRepo() similar to createTestDatabase() pattern. npm test passes with all new tests 20+ tests covering all WorktreeManager operations including edge cases

Before declaring plan complete: - [ ] npm run build succeeds - [ ] npm test passes all tests (including new git tests) - [ ] WorktreeManager can create/remove worktrees in a test repo - [ ] Events are emitted for all git operations - [ ] Merge conflicts are properly detected and reported

<success_criteria>

• All tasks completed
• All verification checks pass
• No errors or warnings introduced
• WorktreeManager satisfies all 4 requirements:
  • GIT-01: create() provides isolated worktree per agent
  • GIT-02: diff() previews agent's changes
  • GIT-03: merge() integrates changes to target branch
  • GIT-04: remove() cleans up worktree </success_criteria>

After completion, create `.planning/phases/03-git-integration/03-02-SUMMARY.md`