stack/docs/scratchpads/orch-112-conflicts.md

# ORCH-112: Conflict Detection

## Objective
Implement conflict detection service that detects merge conflicts before pushing to remote. This is the final git integration feature for Phase 3.

## Approach

### Architecture
1. **ConflictDetectionService**: NestJS service that:
   - Fetches latest changes from remote before push
   - Detects merge conflicts using simple-git
   - Returns detailed conflict information
   - Supports both merge and rebase strategies

### Conflict Detection Strategy
1. Fetch remote branch
2. Try merge/rebase in dry-run mode (or check status after fetch)
3. Detect conflicts by:
   - Checking git status for conflicted files
   - Parsing merge output for conflict markers
   - Checking for unmerged paths
4. Return structured conflict information with file paths and details

### Integration Points
- Uses GitOperationsService for basic git operations
- Will be called by orchestrator before push operations
- Provides retry capability with different strategies

## Progress

- [x] Review requirements from ORCH-112
- [x] Examine existing git services (GitOperationsService, WorktreeManagerService)
- [x] Identify types structure and patterns
- [x] Create scratchpad
- [x] Write tests for ConflictDetectionService (TDD - RED)
- [x] Implement ConflictDetectionService (TDD - GREEN)
- [x] Refactor implementation (TDD - REFACTOR)
- [x] Add types to types/conflict-detection.types.ts
- [x] Export from types/index.ts
- [x] Update git.module.ts to include ConflictDetectionService
- [x] Update git/index.ts exports
- [x] Verify tests pass with ≥85% coverage (95.77% achieved)
- [x] Create Gitea issue
- [x] Close Gitea issue with completion notes

## Completion Summary

Implementation completed successfully with all acceptance criteria met:
- ConflictDetectionService implemented with full TDD approach
- Supports both merge and rebase strategies
- Comprehensive error handling with ConflictDetectionError
- 18 unit tests covering all scenarios
- Coverage: 95.77% (exceeds 85% requirement)
- Proper cleanup after conflict detection
- Integrated into GitModule and exported

Files created/modified:
- apps/orchestrator/src/git/conflict-detection.service.ts
- apps/orchestrator/src/git/conflict-detection.service.spec.ts
- apps/orchestrator/src/git/types/conflict-detection.types.ts
- apps/orchestrator/src/git/types/index.ts (updated)
- apps/orchestrator/src/git/git.module.ts (updated)
- apps/orchestrator/src/git/index.ts (updated)

## Testing Strategy

### Unit Tests (TDD)
1. **No conflicts scenario**:
   - Fetch succeeds
   - No conflicts detected
   - Returns clean status

2. **Merge conflicts detected**:
   - Fetch succeeds
   - Merge shows conflicts
   - Returns conflict details with file paths

3. **Rebase conflicts detected**:
   - Fetch succeeds
   - Rebase shows conflicts
   - Returns conflict details

4. **Fetch failure**:
   - Remote unavailable
   - Throws appropriate error

5. **Check before push**:
   - Integration with conflict detection
   - Prevents push if conflicts exist

### Mock Strategy
- Mock simple-git for all git operations
- Mock GitOperationsService where needed
- Test both merge and rebase strategies

## Technical Notes

### Key Methods
```typescript
// Check for conflicts before push
async checkForConflicts(
  localPath: string,
  remote: string = 'origin',
  branch: string = 'develop',
  strategy: 'merge' | 'rebase' = 'merge'
): Promise<ConflictCheckResult>

// Fetch latest from remote
async fetchRemote(
  localPath: string,
  remote: string = 'origin'
): Promise<void>

// Detect conflicts in current state
async detectConflicts(
  localPath: string
): Promise<ConflictInfo[]>
```

### Types
```typescript
interface ConflictCheckResult {
  hasConflicts: boolean;
  conflicts: ConflictInfo[];
  strategy: 'merge' | 'rebase';
  canRetry: boolean;
}

interface ConflictInfo {
  file: string;
  type: 'content' | 'delete' | 'add';
  ours?: string;
  theirs?: string;
}

class ConflictDetectionError extends Error {
  constructor(
    message: string,
    operation: string,
    cause?: Error
  )
}
```

## Implementation Details

### Git Commands
- `git fetch origin branch` - Fetch latest
- `git merge --no-commit --no-ff origin/branch` - Test merge
- `git merge --abort` - Abort test merge
- `git status --porcelain` - Check for conflicts
- `git diff --name-only --diff-filter=U` - List conflicted files

### Conflict Detection Logic
1. Save current state
2. Fetch remote
3. Attempt merge/rebase (no commit)
4. Check status for "UU" markers (unmerged)
5. Parse conflict information
6. Abort merge/rebase
7. Return conflict details

## Notes

### Design Decisions
- Use `--no-commit` flag to test merge without committing
- Support both merge and rebase strategies
- Provide detailed conflict information for agent retry
- Clean up after detection (abort merge/rebase)

### Error Handling
- GitOperationError for git command failures
- ConflictDetectionError for detection-specific issues
- Return structured errors for agent consumption

### Dependencies
- simple-git library (already used in GitOperationsService)
- NestJS @Injectable decorator
- Logger for debugging

## Next Steps
1. Start with TDD: Write failing tests first
2. Implement minimal code to pass tests
3. Refactor for clarity
4. Ensure coverage ≥85%
5. Create and close Gitea issue