feat(projman): add file conflict prevention for parallel agents (#234)

Add pre-dispatch conflict detection:
- Analyze target files for each task before parallel dispatch
- Check for file overlap between tasks in same batch
- If overlap detected, sequentialize those specific tasks
- Example analysis showing conflict detection workflow

Branch isolation protocol:
- Each task MUST have its own branch
- Never have two agents work on the same branch
- Sequential merge after completion (not simultaneous)
- Handle merge conflicts by stopping second task

Conflict resolution rules:
- Same file → MUST sequentialize
- Same directory → Usually safe, review
- Shared config → Sequentialize
- Shared test fixture → Sequentialize or assign different files

This prevents parallel agents from modifying the same files
and causing git merge conflicts.

Closes #234

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
2026-01-28 10:47:36 -05:00
parent f2a62627d0
commit a69a4d19d0
2 changed files with 123 additions and 9 deletions

View File

@@ -72,6 +72,67 @@ Parallel Execution Batches:
**Independent tasks in the same batch run in parallel.**
## File Conflict Prevention (MANDATORY)
**CRITICAL: Before dispatching parallel agents, check for file overlap.**
**Pre-Dispatch Conflict Check:**
1. **Identify target files** for each task in the batch
2. **Check for overlap** - Do any tasks modify the same file?
3. **If overlap detected** - Sequentialize those specific tasks
**Example Conflict Detection:**
```
Batch 1 Analysis:
#45 - Implement JWT service
Files: auth/jwt_service.py, auth/__init__.py, tests/test_jwt.py
#48 - Update API documentation
Files: docs/api.md, README.md
Overlap: NONE → Safe to parallelize
Batch 2 Analysis:
#46 - Build login endpoint
Files: api/routes/auth.py, auth/__init__.py
#49 - Add auth tests
Files: tests/test_auth.py, auth/__init__.py
Overlap: auth/__init__.py → CONFLICT!
Action: Sequentialize #46 and #49 (run #46 first)
```
**Conflict Resolution Rules:**
| Conflict Type | Action |
|---------------|--------|
| Same file in checklist | Sequentialize tasks |
| Same directory | Review if safe, usually OK |
| Shared test file | Sequentialize or assign different test files |
| Shared config | Sequentialize |
**Branch Isolation Protocol:**
Even for parallel tasks, each MUST run on its own branch:
```
Task #45 → feat/45-jwt-service (isolated)
Task #48 → feat/48-api-docs (isolated)
```
**Sequential Merge After Completion:**
```
1. Task #45 completes → merge feat/45-jwt-service to development
2. Task #48 completes → merge feat/48-api-docs to development
3. Never merge simultaneously - always sequential to detect conflicts
```
**If Merge Conflict Occurs:**
1. Stop second task
2. Resolve conflict manually or assign to human
3. Resume/restart second task with updated base
## Branch Naming Convention (MANDATORY)
When creating branches for tasks: