[Phase 4] Multi-agent conflict detection and resolution

[frankbria]

Summary

Detect and resolve conflicts when multiple agents work on overlapping files concurrently.

Problem

When multiple agents execute in parallel, they may modify the same files, leading to:

• Overwritten changes
• Merge conflicts
• Inconsistent state

Proposed Solution

Conflict Detection

• Track file locks per agent execution
• Detect concurrent modifications to same files
• Identify conflicting changes before commit

Resolution Strategies

1. Serialize: Queue conflicting tasks for sequential execution
2. Merge: Attempt automatic merge of non-overlapping changes
3. Escalate: Create blocker for human decision

Implementation

• codeframe/core/conflict_detector.py - Conflict detection logic
• codeframe/core/conductor.py - Integration with batch orchestration
• File lock tracking in execution state

Acceptance Criteria

• Conflicts detected before file corruption
• 3+ resolution strategies available
• 90%+ conflicts resolved automatically
• Human escalation for complex conflicts
• Audit log of conflict resolutions

Related

• Part of Phase 4 multi-agent work
• Depends on agent role system

[traycerai]

Plan

Observations

The codebase has a robust batch execution system in file:codeframe/core/conductor.py with parallel/serial strategies, dependency graph analysis in file:codeframe/core/dependency_graph.py, and file change tracking in file:codeframe/core/executor.py. The FileChange dataclass already tracks file operations (create, edit, delete) with timestamps. An event system exists in file:codeframe/core/events.py for audit logging. However, there's no file lock tracking per agent, no conflict detection for concurrent file modifications, and no resolution strategies when multiple agents work on overlapping files.

Approach

Implement a conflict detection and resolution system that integrates with the existing batch conductor. Create a ConflictDetector class to track file locks per agent execution and detect concurrent modifications before commit. Implement three resolution strategies: serialize (queue conflicting tasks), merge (automatic non-overlapping changes), and escalate (create blocker for human decision). Extend the event system with conflict-specific event types and integrate with the existing GlobalFixCoordinator pattern. This approach leverages existing infrastructure while adding minimal new components.

Implementation Steps

1. Create Conflict Detection Module

Create file:codeframe/core/conflict_detector.py with the following components:

Data Structures:

• FileLock dataclass: Track file path, agent_id, task_id, operation type (read/write), timestamp, lock_id
• ConflictInfo dataclass: Track conflicting file path, agent_ids involved, conflict type (concurrent_write, write_after_read, overlapping_edit), severity (low/medium/high), detected_at timestamp
• ResolutionStrategy enum: SERIALIZE, MERGE, ESCALATE
• ConflictResolution dataclass: Track conflict_id, strategy used, resolution_details, resolved_at, resolved_by (auto/human)

ConflictDetector Class:

• __init__(): Initialize with workspace, thread-safe lock registry (dict mapping file_path -> list of FileLock), conflict history
• acquire_lock(file_path, agent_id, task_id, operation): Acquire file lock, return lock_id or raise ConflictDetected
• release_lock(lock_id): Release file lock by lock_id
• detect_conflicts(pending_changes): Analyze pending file changes from multiple agents, return list of ConflictInfo
• check_file_conflicts(file_path, new_operation, agent_id): Check if new operation conflicts with existing locks
• get_active_locks(file_path): Return all active locks for a file
• clear_agent_locks(agent_id): Clear all locks held by an agent (cleanup on completion/failure)

Conflict Detection Logic:

• Concurrent writes: Two agents attempting to write/edit same file simultaneously
• Write-after-read: Agent B writes file that Agent A is reading (potential stale data)
• Overlapping edits: Multiple agents editing same file with different content
• Use file path normalization to handle relative vs absolute paths
• Track lock acquisition order to detect potential deadlocks

2. Implement Resolution Strategies

Create file:codeframe/core/conflict_resolver.py:

ConflictResolver Class:

• __init__(workspace, conflict_detector, llm_provider): Initialize with dependencies
• resolve_conflict(conflict_info): Main entry point, routes to appropriate strategy
• _serialize_strategy(conflict_info): Queue conflicting tasks for sequential execution, update batch execution order
• _merge_strategy(conflict_info): Attempt automatic merge using diff3-style algorithm for non-overlapping changes
• _escalate_strategy(conflict_info): Create blocker with conflict details for human decision
• _can_auto_merge(changes_a, changes_b): Analyze if changes can be merged automatically (check line overlap, semantic conflicts)
• _apply_merge(base_content, changes_a, changes_b): Apply merged changes to base content
• _create_conflict_blocker(conflict_info): Create blocker using existing blocker system from file:codeframe/core/blockers.py

Strategy Selection Logic:

• SERIALIZE: Default for high-severity conflicts (same lines modified, delete vs edit)
• MERGE: For low-severity conflicts (different sections of file, non-overlapping imports)
• ESCALATE: For medium-severity conflicts where auto-merge uncertain, or when MERGE fails
• Use heuristics: file type (code vs config), change size, agent confidence scores
• Configurable strategy preferences per workspace

Merge Algorithm:

• Use difflib to compute line-level diffs for each agent's changes
• Identify overlapping line ranges
• If no overlap: combine changes (MERGE)
• If overlap but semantically compatible (e.g., both adding imports): attempt smart merge
• If overlap with conflicts: escalate or serialize based on severity

3. Integrate with Batch Conductor

Modify file:codeframe/core/conductor.py:

Add Conflict Detection to Execution Flow:

• In _execute_parallel(): Before starting each task, acquire locks for target files
• In _execute_single_task(): Wrap execution with lock acquisition/release
• After task completion: Check for conflicts before committing changes
• On conflict detection: Pause execution, invoke resolver, apply resolution strategy

Integration Points:

• Add conflict_detector parameter to start_batch(), default to global singleton
• In _execute_group_parallel(): Before launching parallel tasks, pre-check for potential conflicts
• Modify _execute_task_subprocess(): Pass agent_id and task_id for lock tracking
• Add conflict resolution retry logic: if SERIALIZE chosen, re-queue task for later execution

Lock Lifecycle:

• Acquire locks when task starts (based on plan steps from file:codeframe/core/planner.py)
• Hold locks during execution
• Release locks on success, failure, or cancellation
• Implement timeout for lock acquisition (configurable, default 30s)

Coordination with GlobalFixCoordinator:

• Extend existing GlobalFixCoordinator pattern to include conflict resolution
• Share conflict resolution decisions across parallel agents
• Cache resolution strategies for similar conflicts

4. Extend Event System for Audit Logging

Modify file:codeframe/core/events.py:

Add Conflict Event Types:

CONFLICT_DETECTED = "CONFLICT_DETECTED"
CONFLICT_RESOLVED = "CONFLICT_RESOLVED"
CONFLICT_ESCALATED = "CONFLICT_ESCALATED"
CONFLICT_MERGE_ATTEMPTED = "CONFLICT_MERGE_ATTEMPTED"
CONFLICT_MERGE_SUCCESS = "CONFLICT_MERGE_SUCCESS"
CONFLICT_MERGE_FAILED = "CONFLICT_MERGE_FAILED"
FILE_LOCK_ACQUIRED = "FILE_LOCK_ACQUIRED"
FILE_LOCK_RELEASED = "FILE_LOCK_RELEASED"
FILE_LOCK_TIMEOUT = "FILE_LOCK_TIMEOUT"

Event Payload Structure:

• CONFLICT_DETECTED: file_path, agent_ids, conflict_type, severity, timestamp
• CONFLICT_RESOLVED: conflict_id, strategy, resolution_time_ms, auto_resolved (bool)
• CONFLICT_ESCALATED: conflict_id, blocker_id, reason
• FILE_LOCK_ACQUIRED: file_path, agent_id, task_id, lock_id, operation

Audit Trail:

• Emit events at each conflict lifecycle stage
• Store conflict resolution history in database (extend workspace schema)
• Add conflict_resolutions table: id, conflict_id, strategy, details, created_at, resolved_at

5. Database Schema Extensions

Modify file:codeframe/core/workspace.py in _init_database():

Add Conflict Tracking Tables:

CREATE TABLE file_locks (
    id TEXT PRIMARY KEY,
    workspace_id TEXT NOT NULL,
    file_path TEXT NOT NULL,
    agent_id TEXT NOT NULL,
    task_id TEXT NOT NULL,
    operation TEXT NOT NULL,
    acquired_at TEXT NOT NULL,
    released_at TEXT,
    FOREIGN KEY (workspace_id) REFERENCES workspace(id)
)

CREATE TABLE conflicts (
    id TEXT PRIMARY KEY,
    workspace_id TEXT NOT NULL,
    batch_id TEXT,
    file_path TEXT NOT NULL,
    agent_ids TEXT NOT NULL,
    conflict_type TEXT NOT NULL,
    severity TEXT NOT NULL,
    detected_at TEXT NOT NULL,
    resolved_at TEXT,
    resolution_strategy TEXT,
    resolution_details TEXT,
    FOREIGN KEY (workspace_id) REFERENCES workspace(id),
    FOREIGN KEY (batch_id) REFERENCES batch_runs(id)
)

CREATE INDEX idx_file_locks_file ON file_locks(file_path)
CREATE INDEX idx_file_locks_agent ON file_locks(agent_id)
CREATE INDEX idx_conflicts_batch ON conflicts(batch_id)

6. Implement Conflict Resolution Metrics

Create file:codeframe/core/conflict_metrics.py:

ConflictMetrics Class:

• track_conflict(conflict_info): Record conflict occurrence
• track_resolution(conflict_id, strategy, success, duration_ms): Record resolution outcome
• get_resolution_rate(): Calculate percentage of auto-resolved conflicts
• get_strategy_effectiveness(): Return success rate per strategy
• get_conflict_hotspots(): Identify files with frequent conflicts
• generate_report(batch_id): Generate conflict summary for batch execution

Metrics to Track:

• Total conflicts detected
• Conflicts resolved automatically (target: 90%+)
• Conflicts escalated to human
• Average resolution time per strategy
• Most conflicted files/agents
• Strategy distribution (serialize vs merge vs escalate)

7. CLI Integration

Modify file:codeframe/cli/batch_commands.py (or create if doesn't exist):

Add Conflict Management Commands:

• codeframe batch conflicts <batch-id>: List conflicts for a batch
• codeframe batch conflicts resolve <conflict-id> <strategy>: Manually resolve conflict
• codeframe batch conflicts report <batch-id>: Generate conflict resolution report
• codeframe batch config set-conflict-strategy <strategy>: Set default resolution strategy

Display Conflict Information:

• Show conflict count in batch status output
• Highlight files with active locks
• Display resolution strategy effectiveness in summary

8. Testing Strategy

Create test files:

Unit Tests (file:tests/core/test_conflict_detector.py):

• Test lock acquisition and release
• Test conflict detection for various scenarios
• Test lock timeout handling
• Test deadlock detection

Unit Tests (file:tests/core/test_conflict_resolver.py):

• Test each resolution strategy independently
• Test merge algorithm with various file types
• Test blocker creation for escalation
• Test strategy selection logic

Integration Tests (file:tests/integration/test_conflict_resolution.py):

• Test end-to-end conflict detection in batch execution
• Test parallel agents modifying same file
• Test automatic merge of non-overlapping changes
• Test escalation to blocker system
• Test conflict metrics collection

Performance Tests:

• Test lock contention with high parallelism (10+ agents)
• Test conflict detection overhead on large batches
• Verify 90%+ auto-resolution target

9. Documentation

Create file:docs/CONFLICT_RESOLUTION.md:

Document:

• Conflict detection mechanism and triggers
• Resolution strategy descriptions and when each is used
• How to configure conflict resolution preferences
• How to interpret conflict metrics and reports
• Troubleshooting guide for common conflict scenarios
• Best practices for minimizing conflicts (task decomposition, file ownership)

Update Existing Docs:

• Add conflict resolution section to file:docs/BATCH_EXECUTION_PLAN.md
• Update file:AGENTS.md with multi-agent conflict handling guidelines

10. Configuration and Tuning

Add to file:codeframe/core/config.py:

Conflict Resolution Configuration:

class ConflictConfig:
    default_strategy: ResolutionStrategy = SERIALIZE
    enable_auto_merge: bool = True
    lock_timeout_seconds: int = 30
    max_merge_attempts: int = 3
    escalation_threshold: float = 0.7  # confidence threshold
    track_read_locks: bool = False  # performance vs safety tradeoff

Tunable Parameters:

• Lock acquisition timeout
• Merge confidence threshold
• Strategy selection weights
• Conflict severity thresholds
• Enable/disable specific strategies per workspace

Sequence Diagram

sequenceDiagram
    participant Conductor
    participant ConflictDetector
    participant Agent1
    participant Agent2
    participant ConflictResolver
    participant BlockerSystem
    participant EventLog

    Conductor->>ConflictDetector: start_batch([task1, task2])
    Conductor->>Agent1: execute(task1)
    Conductor->>Agent2: execute(task2)
    
    Agent1->>ConflictDetector: acquire_lock(file.py, write)
    ConflictDetector-->>Agent1: lock_id_1
    ConflictDetector->>EventLog: emit(FILE_LOCK_ACQUIRED)
    
    Agent2->>ConflictDetector: acquire_lock(file.py, write)
    ConflictDetector->>ConflictDetector: check_file_conflicts()
    ConflictDetector-->>Agent2: ConflictDetected
    ConflictDetector->>EventLog: emit(CONFLICT_DETECTED)
    
    Agent2->>ConflictResolver: resolve_conflict(conflict_info)
    ConflictResolver->>ConflictResolver: select_strategy()
    
    alt Strategy: SERIALIZE
        ConflictResolver->>Conductor: queue_task(task2, after=task1)
        ConflictResolver->>EventLog: emit(CONFLICT_RESOLVED, strategy=SERIALIZE)
    else Strategy: MERGE
        ConflictResolver->>ConflictResolver: _can_auto_merge()
        alt Merge Success
            ConflictResolver->>ConflictResolver: _apply_merge()
            ConflictResolver->>EventLog: emit(CONFLICT_MERGE_SUCCESS)
        else Merge Failed
            ConflictResolver->>ConflictResolver: _escalate_strategy()
            ConflictResolver->>EventLog: emit(CONFLICT_MERGE_FAILED)
        end
    else Strategy: ESCALATE
        ConflictResolver->>BlockerSystem: create_blocker(conflict_info)
        BlockerSystem-->>ConflictResolver: blocker_id
        ConflictResolver->>EventLog: emit(CONFLICT_ESCALATED)
    end
    
    Agent1->>ConflictDetector: release_lock(lock_id_1)
    ConflictDetector->>EventLog: emit(FILE_LOCK_RELEASED)
    
    Conductor->>EventLog: emit(BATCH_COMPLETED)

Loading

Acceptance Criteria Mapping

• Conflicts detected before file corruption: ConflictDetector checks locks before file writes in _execute_single_task()
• 3+ resolution strategies available: SERIALIZE, MERGE, ESCALATE implemented in ConflictResolver
• 90%+ conflicts resolved automatically: Metrics tracked in ConflictMetrics, tunable via merge algorithm and strategy selection
• Human escalation for complex conflicts: ESCALATE strategy creates blockers using existing blocker system
• Audit log of conflict resolutions: Event system extended with conflict-specific events, conflicts table stores resolution history

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has a robust batch execution system in `file:codeframe/core/conductor.py` with parallel/serial strategies, dependency graph analysis in `file:codeframe/core/dependency_graph.py`, and file change tracking in `file:codeframe/core/executor.py`. The `FileChange` dataclass already tracks file operations (create, edit, delete) with timestamps. An event system exists in `file:codeframe/core/events.py` for audit logging. However, there's no file lock tracking per agent, no conflict detection for concurrent file modifications, and no resolution strategies when multiple agents work on overlapping files.

## Approach

Implement a conflict detection and resolution system that integrates with the existing batch conductor. Create a `ConflictDetector` class to track file locks per agent execution and detect concurrent modifications before commit. Implement three resolution strategies: serialize (queue conflicting tasks), merge (automatic non-overlapping changes), and escalate (create blocker for human decision). Extend the event system with conflict-specific event types and integrate with the existing `GlobalFixCoordinator` pattern. This approach leverages existing infrastructure while adding minimal new components.

## Implementation Steps

### 1. Create Conflict Detection Module

Create `file:codeframe/core/conflict_detector.py` with the following components:

**Data Structures**:
- `FileLock` dataclass: Track file path, agent_id, task_id, operation type (read/write), timestamp, lock_id
- `ConflictInfo` dataclass: Track conflicting file path, agent_ids involved, conflict type (concurrent_write, write_after_read, overlapping_edit), severity (low/medium/high), detected_at timestamp
- `ResolutionStrategy` enum: SERIALIZE, MERGE, ESCALATE
- `ConflictResolution` dataclass: Track conflict_id, strategy used, resolution_details, resolved_at, resolved_by (auto/human)

**ConflictDetector Class**:
- `__init__()`: Initialize with workspace, thread-safe lock registry (dict mapping file_path -> list of FileLock), conflict history
- `acquire_lock(file_path, agent_id, task_id, operation)`: Acquire file lock, return lock_id or raise ConflictDetected
- `release_lock(lock_id)`: Release file lock by lock_id
- `detect_conflicts(pending_changes)`: Analyze pending file changes from multiple agents, return list of ConflictInfo
- `check_file_conflicts(file_path, new_operation, agent_id)`: Check if new operation conflicts with existing locks
- `get_active_locks(file_path)`: Return all active locks for a file
- `clear_agent_locks(agent_id)`: Clear all locks held by an agent (cleanup on completion/failure)

**Conflict Detection Logic**:
- Concurrent writes: Two agents attempting to write/edit same file simultaneously
- Write-after-read: Agent B writes file that Agent A is reading (potential stale data)
- Overlapping edits: Multiple agents editing same file with different content
- Use file path normalization to handle relative vs absolute paths
- Track lock acquisition order to detect potential deadlocks

### 2. Implement Resolution Strategies

Create `file:codeframe/core/conflict_resolver.py`:

**ConflictResolver Class**:
- `__init__(workspace, conflict_detector, llm_provider)`: Initialize with dependencies
- `resolve_conflict(conflict_info)`: Main entry point, routes to appropriate strategy
- `_serialize_strategy(conflict_info)`: Queue conflicting tasks for sequential execution, update batch execution order
- `_merge_strategy(conflict_info)`: Attempt automatic merge using diff3-style algorithm for non-overlapping changes
- `_escalate_strategy(conflict_info)`: Create blocker with conflict details for human decision
- `_can_auto_merge(changes_a, changes_b)`: Analyze if changes can be merged automatically (check line overlap, semantic conflicts)
- `_apply_merge(base_content, changes_a, changes_b)`: Apply merged changes to base content
- `_create_conflict_blocker(conflict_info)`: Create blocker using existing blocker system from `file:codeframe/core/blockers.py`

**Strategy Selection Logic**:
- SERIALIZE: Default for high-severity conflicts (same lines modified, delete vs edit)
- MERGE: For low-severity conflicts (different sections of file, non-overlapping imports)
- ESCALATE: For medium-severity conflicts where auto-merge uncertain, or when MERGE fails
- Use heuristics: file type (code vs config), change size, agent confidence scores
- Configurable strategy preferences per workspace

**Merge Algorithm**:
- Use difflib to compute line-level diffs for each agent's changes
- Identify overlapping line ranges
- If no overlap: combine changes (MERGE)
- If overlap but semantically compatible (e.g., both adding imports): attempt smart merge
- If overlap with conflicts: escalate or serialize based on severity

### 3. Integrate with Batch Conductor

Modify `file:codeframe/core/conductor.py`:

**Add Conflict Detection to Execution Flow**:
- In `_execute_parallel()`: Before starting each task, acquire locks for target files
- In `_execute_single_task()`: Wrap execution with lock acquisition/release
- After task completion: Check for conflicts before committing changes
- On conflict detection: Pause execution, invoke resolver, apply resolution strategy

**Integration Points**:
- Add `conflict_detector` parameter to `start_batch()`, default to global singleton
- In `_execute_group_parallel()`: Before launching parallel tasks, pre-check for potential conflicts
- Modify `_execute_task_subprocess()`: Pass agent_id and task_id for lock tracking
- Add conflict resolution retry logic: if SERIALIZE chosen, re-queue task for later execution

**Lock Lifecycle**:
- Acquire locks when task starts (based on plan steps from `file:codeframe/core/planner.py`)
- Hold locks during execution
- Release locks on success, failure, or cancellation
- Implement timeout for lock acquisition (configurable, default 30s)

**Coordination with GlobalFixCoordinator**:
- Extend existing `GlobalFixCoordinator` pattern to include conflict resolution
- Share conflict resolution decisions across parallel agents
- Cache resolution strategies for similar conflicts

### 4. Extend Event System for Audit Logging

Modify `file:codeframe/core/events.py`:

**Add Conflict Event Types**:
```python
CONFLICT_DETECTED = "CONFLICT_DETECTED"
CONFLICT_RESOLVED = "CONFLICT_RESOLVED"
CONFLICT_ESCALATED = "CONFLICT_ESCALATED"
CONFLICT_MERGE_ATTEMPTED = "CONFLICT_MERGE_ATTEMPTED"
CONFLICT_MERGE_SUCCESS = "CONFLICT_MERGE_SUCCESS"
CONFLICT_MERGE_FAILED = "CONFLICT_MERGE_FAILED"
FILE_LOCK_ACQUIRED = "FILE_LOCK_ACQUIRED"
FILE_LOCK_RELEASED = "FILE_LOCK_RELEASED"
FILE_LOCK_TIMEOUT = "FILE_LOCK_TIMEOUT"
```

**Event Payload Structure**:
- CONFLICT_DETECTED: file_path, agent_ids, conflict_type, severity, timestamp
- CONFLICT_RESOLVED: conflict_id, strategy, resolution_time_ms, auto_resolved (bool)
- CONFLICT_ESCALATED: conflict_id, blocker_id, reason
- FILE_LOCK_ACQUIRED: file_path, agent_id, task_id, lock_id, operation

**Audit Trail**:
- Emit events at each conflict lifecycle stage
- Store conflict resolution history in database (extend workspace schema)
- Add `conflict_resolutions` table: id, conflict_id, strategy, details, created_at, resolved_at

### 5. Database Schema Extensions

Modify `file:codeframe/core/workspace.py` in `_init_database()`:

**Add Conflict Tracking Tables**:
```sql
CREATE TABLE file_locks (
    id TEXT PRIMARY KEY,
    workspace_id TEXT NOT NULL,
    file_path TEXT NOT NULL,
    agent_id TEXT NOT NULL,
    task_id TEXT NOT NULL,
    operation TEXT NOT NULL,
    acquired_at TEXT NOT NULL,
    released_at TEXT,
    FOREIGN KEY (workspace_id) REFERENCES workspace(id)
)

CREATE TABLE conflicts (
    id TEXT PRIMARY KEY,
    workspace_id TEXT NOT NULL,
    batch_id TEXT,
    file_path TEXT NOT NULL,
    agent_ids TEXT NOT NULL,
    conflict_type TEXT NOT NULL,
    severity TEXT NOT NULL,
    detected_at TEXT NOT NULL,
    resolved_at TEXT,
    resolution_strategy TEXT,
    resolution_details TEXT,
    FOREIGN KEY (workspace_id) REFERENCES workspace(id),
    FOREIGN KEY (batch_id) REFERENCES batch_runs(id)
)

CREATE INDEX idx_file_locks_file ON file_locks(file_path)
CREATE INDEX idx_file_locks_agent ON file_locks(agent_id)
CREATE INDEX idx_conflicts_batch ON conflicts(batch_id)
```

### 6. Implement Conflict Resolution Metrics

Create `file:codeframe/core/conflict_metrics.py`:

**ConflictMetrics Class**:
- `track_conflict(conflict_info)`: Record conflict occurrence
- `track_resolution(conflict_id, strategy, success, duration_ms)`: Record resolution outcome
- `get_resolution_rate()`: Calculate percentage of auto-resolved conflicts
- `get_strategy_effectiveness()`: Return success rate per strategy
- `get_conflict_hotspots()`: Identify files with frequent conflicts
- `generate_report(batch_id)`: Generate conflict summary for batch execution

**Metrics to Track**:
- Total conflicts detected
- Conflicts resolved automatically (target: 90%+)
- Conflicts escalated to human
- Average resolution time per strategy
- Most conflicted files/agents
- Strategy distribution (serialize vs merge vs escalate)

### 7. CLI Integration

Modify `file:codeframe/cli/batch_commands.py` (or create if doesn't exist):

**Add Conflict Management Commands**:
- `codeframe batch conflicts <batch-id>`: List conflicts for a batch
- `codeframe batch conflicts resolve <conflict-id> <strategy>`: Manually resolve conflict
- `codeframe batch conflicts report <batch-id>`: Generate conflict resolution report
- `codeframe batch config set-conflict-strategy <strategy>`: Set default resolution strategy

**Display Conflict Information**:
- Show conflict count in batch status output
- Highlight files with active locks
- Display resolution strategy effectiveness in summary

### 8. Testing Strategy

Create test files:

**Unit Tests** (`file:tests/core/test_conflict_detector.py`):
- Test lock acquisition and release
- Test conflict detection for various scenarios
- Test lock timeout handling
- Test deadlock detection

**Unit Tests** (`file:tests/core/test_conflict_resolver.py`):
- Test each resolution strategy independently
- Test merge algorithm with various file types
- Test blocker creation for escalation
- Test strategy selection logic

**Integration Tests** (`file:tests/integration/test_conflict_resolution.py`):
- Test end-to-end conflict detection in batch execution
- Test parallel agents modifying same file
- Test automatic merge of non-overlapping changes
- Test escalation to blocker system
- Test conflict metrics collection

**Performance Tests**:
- Test lock contention with high parallelism (10+ agents)
- Test conflict detection overhead on large batches
- Verify 90%+ auto-resolution target

### 9. Documentation

Create `file:docs/CONFLICT_RESOLUTION.md`:

**Document**:
- Conflict detection mechanism and triggers
- Resolution strategy descriptions and when each is used
- How to configure conflict resolution preferences
- How to interpret conflict metrics and reports
- Troubleshooting guide for common conflict scenarios
- Best practices for minimizing conflicts (task decomposition, file ownership)

**Update Existing Docs**:
- Add conflict resolution section to `file:docs/BATCH_EXECUTION_PLAN.md`
- Update `file:AGENTS.md` with multi-agent conflict handling guidelines

### 10. Configuration and Tuning

Add to `file:codeframe/core/config.py`:

**Conflict Resolution Configuration**:
```python
class ConflictConfig:
    default_strategy: ResolutionStrategy = SERIALIZE
    enable_auto_merge: bool = True
    lock_timeout_seconds: int = 30
    max_merge_attempts: int = 3
    escalation_threshold: float = 0.7  # confidence threshold
    track_read_locks: bool = False  # performance vs safety tradeoff
```

**Tunable Parameters**:
- Lock acquisition timeout
- Merge confidence threshold
- Strategy selection weights
- Conflict severity thresholds
- Enable/disable specific strategies per workspace

## Sequence Diagram

```mermaid
sequenceDiagram
    participant Conductor
    participant ConflictDetector
    participant Agent1
    participant Agent2
    participant ConflictResolver
    participant BlockerSystem
    participant EventLog

    Conductor->>ConflictDetector: start_batch([task1, task2])
    Conductor->>Agent1: execute(task1)
    Conductor->>Agent2: execute(task2)
    
    Agent1->>ConflictDetector: acquire_lock(file.py, write)
    ConflictDetector-->>Agent1: lock_id_1
    ConflictDetector->>EventLog: emit(FILE_LOCK_ACQUIRED)
    
    Agent2->>ConflictDetector: acquire_lock(file.py, write)
    ConflictDetector->>ConflictDetector: check_file_conflicts()
    ConflictDetector-->>Agent2: ConflictDetected
    ConflictDetector->>EventLog: emit(CONFLICT_DETECTED)
    
    Agent2->>ConflictResolver: resolve_conflict(conflict_info)
    ConflictResolver->>ConflictResolver: select_strategy()
    
    alt Strategy: SERIALIZE
        ConflictResolver->>Conductor: queue_task(task2, after=task1)
        ConflictResolver->>EventLog: emit(CONFLICT_RESOLVED, strategy=SERIALIZE)
    else Strategy: MERGE
        ConflictResolver->>ConflictResolver: _can_auto_merge()
        alt Merge Success
            ConflictResolver->>ConflictResolver: _apply_merge()
            ConflictResolver->>EventLog: emit(CONFLICT_MERGE_SUCCESS)
        else Merge Failed
            ConflictResolver->>ConflictResolver: _escalate_strategy()
            ConflictResolver->>EventLog: emit(CONFLICT_MERGE_FAILED)
        end
    else Strategy: ESCALATE
        ConflictResolver->>BlockerSystem: create_blocker(conflict_info)
        BlockerSystem-->>ConflictResolver: blocker_id
        ConflictResolver->>EventLog: emit(CONFLICT_ESCALATED)
    end
    
    Agent1->>ConflictDetector: release_lock(lock_id_1)
    ConflictDetector->>EventLog: emit(FILE_LOCK_RELEASED)
    
    Conductor->>EventLog: emit(BATCH_COMPLETED)
```

## Acceptance Criteria Mapping

- **Conflicts detected before file corruption**: ConflictDetector checks locks before file writes in `_execute_single_task()`
- **3+ resolution strategies available**: SERIALIZE, MERGE, ESCALATE implemented in ConflictResolver
- **90%+ conflicts resolved automatically**: Metrics tracked in ConflictMetrics, tunable via merge algorithm and strategy selection
- **Human escalation for complex conflicts**: ESCALATE strategy creates blockers using existing blocker system
- **Audit log of conflict resolutions**: Event system extended with conflict-specific events, conflicts table stores resolution history

---

Execution Information

Branch: main
Commit: e768c1d

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Related PRs

#9 - Merge Sprint 4 Multi-Agent Coordination work into main [merged]
#128 - Implement bottleneck detection for workflow monitoring [merged]
#151 - Integrate QualityTracker with workflow system [merged]
#246 - feat(agents): trigger multi-agent execution after task approval [merged]

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!