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

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

// 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

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