# Phase 01.2.6: File Overlap Detection [CONDITIONAL]

**Purpose:** Detect file overlaps with parallel stories before TDD workflow begins (STORY-094).

**When to execute:** After dependency-graph-analyzer (Phase 01.2.5), before workflow adaptation (Phase 01.3).

**Pre-check: Has technical_specification optimization:**

```
# Check if story has technical_specification section
IF technical_specification section is empty OR not present:
    Display: "ℹ️ No technical_specification - skipping spec-based overlap detection"
    Display: "   Post-flight git-based detection will still run after Phase 3"
    $FILE_OVERLAP_PRE_FLIGHT = false
    SKIP to Phase 01.3
    RETURN
```

**Invoke file-overlap-detector subagent:**

```
Task(
  subagent_type="file-overlap-detector",
  description="Detect file overlaps for ${STORY_ID}",
  prompt="Analyze file overlaps for story ${STORY_ID}.

    Mode: pre-flight
    Story path: devforgeai/specs/Stories/

    Tasks:
    1. Parse technical_specification from target story
    2. Extract all file_path values from components
    3. Scan stories with status 'In Development'
    4. Detect overlapping files
    5. Filter out depends_on story overlaps
    6. Generate recommendations

    Return JSON with overlap analysis.
    WARNING: Return status=WARNING if overlaps detected
    BLOCKING: Return status=BLOCKED if >= 10 files overlap"
)
```

**Parse subagent response:**

```javascript
result = parse_json(subagent_output)

IF result.status == "PASS":
    Display: "✓ File overlap check passed"
    Display: "  No overlapping files with parallel stories"
    $FILE_OVERLAP_PRE_FLIGHT = true
    // Continue to Phase 01.3

ELIF result.status == "WARNING":
    // Overlaps detected but below blocking threshold
    Display: "⚠️ FILE OVERLAPS DETECTED"
    Display: ""
    Display: "Overlapping files found with parallel story/stories:"

    FOR story_id, files in result.overlaps:
        Display: "  • {story_id}: {files.length} file(s)"
        FOR file in files:
            Display: "    - {file}"
    Display: ""

    // Interactive prompt
    AskUserQuestion(
        questions=[{
            question: "File overlap detected. How would you like to proceed?",
            header: "Overlap Warning",
            multiSelect: false,
            options: [
                {
                    label: "Yes - Proceed",
                    description: "Continue with development (accept overlap risk)"
                },
                {
                    label: "No - Cancel",
                    description: "Cancel development to resolve overlap"
                },
                {
                    label: "Review - Show detailed report",
                    description: "View full overlap report before deciding"
                }
            ]
        }]
    )

    SWITCH user_response:
        CASE "Yes - Proceed":
            Display: "✓ Proceeding with acknowledged overlaps"
            $FILE_OVERLAP_PRE_FLIGHT = true
            // Continue to Phase 01.3

        CASE "No - Cancel":
            Display: "Development cancelled due to file overlaps"
            HALT workflow

        CASE "Review - Show detailed report":
            Read(file_path=result.report_path)
            // Re-ask question after review

ELIF result.status == "BLOCKED":
    // >= blocking_threshold overlaps
    Display: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
    Display: "❌ FILE OVERLAP DETECTION - BLOCKED"
    Display: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
    Display: ""
    Display: "Severe file overlap detected ({result.overlap_count} files)"
    Display: ""
    FOR rec in result.recommendations:
        Display: "  • {rec}"
    Display: ""
    Display: "Report saved to: {result.report_path}"

    IF $FORCE_FLAG == true:
        // Log bypass
        Display: "⚠️ FILE OVERLAP CHECK BYPASSED (--force flag)"
        $FILE_OVERLAP_PRE_FLIGHT = true
        // Continue to Phase 01.3
    ELSE:
        Display: "To bypass (not recommended):"
        Display: "  /dev {STORY_ID} --force"
        HALT workflow

ELIF result.status == "ERROR":
    Display: "⚠️ File overlap analysis error: {result.error}"
    Display: "Proceeding with caution (spec-based detection skipped)..."
    $FILE_OVERLAP_PRE_FLIGHT = false
    // Continue to Phase 01.3 (graceful degradation)
```

**Token cost:** ~2,000 tokens

**References:**
- Subagent: `.claude/agents/file-overlap-detector.md`
- Story: STORY-094 - File Overlap Detection
