@ktpartners/dgs-platform 2.6.2

package/deliver-great-systems/bin/lib/conflict-agent.cjs

@@ -0,0 +1,1063 @@
+/**
+ * Conflict Agent -- Resolution engine, report generation, verification, semantic detection, and cascading context
+ *
+ * Provides the conflict resolution brain that takes a conflicted merge state,
+ * reads plan context for both sides, produces resolved file contents, and
+ * records the full audit trail. Uses Phase 38's detection and classification primitives.
+ *
+ * Exported functions:
+ *   resolveConflicts           Full resolution flow (alias for cmdConflictAgentRun)
+ *   verifyResolution           Post-resolution test/lint verification
+ *   detectSemanticConflicts    Flag same-domain changes in cleanly merged files
+ *   selectResolutionStrategy   Per-hunk strategy selection from classified hunks
+ *   resolveFileContent         Apply per-hunk strategies to produce resolved file
+ *   buildResolutionReport      Generate RESOLUTION-REPORT.md content
+ *   createLearningContext      Extract learnings from completed resolutions
+ *   mergeLearningContexts      Accumulate learnings across sequential phase merges
+ *   cmdConflictAgentRun        CLI handler: orchestrate full resolution
+ *   cmdConflictAgentResolveFile  CLI handler: resolve a single file
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const { execGit, safeReadFile, loadConfig, output, error } = require('./core.cjs');
+const { classifyConflictHunks, cmdMergeConflictsDetect, cmdMergeConflictsContext } = require('./merge-conflicts.cjs');
+const { extractFrontmatter } = require('./frontmatter.cjs');
+const { parseReposMd } = require('./repos.cjs');
+
+// ─── Section 1: Resolution Strategy Selection ────────────────────────────────
+
+/**
+ * Select a resolution strategy for each classified hunk.
+ *
+ * Pure function taking classified hunks (from classifyConflictHunks),
+ * plan context for both sides, and optional accumulated learnings.
+ *
+ * @param {Array<{type: string, confidence: string, ours: string, theirs: string, start_line: number, end_line: number}>} classifiedHunks
+ * @param {Array<{task_name: string, action_excerpt: string}>|null} planContext
+ * @param {Object|null} learnings - Accumulated learnings from previous resolutions
+ * @returns {Array<{hunk_index: number, strategy: string, confidence: string, reasoning: string}>}
+ */
+function selectResolutionStrategy(classifiedHunks, planContext, learnings) {
+  const contextText = planContext && Array.isArray(planContext)
+    ? planContext.map(c => (c.task_name || '') + ' ' + (c.action_excerpt || '')).join(' ').toLowerCase()
+    : '';
+
+  return classifiedHunks.map((hunk, index) => {
+    let strategy = 'escalate';
+    let confidence = hunk.confidence || 'LOW';
+    let reasoning = '';
+
+    switch (hunk.type) {
+      case 'ADDITIVE': {
+        // Take the side that adds content
+        const oursEmpty = !hunk.ours || hunk.ours.trim().length === 0;
+        const theirsEmpty = !hunk.theirs || hunk.theirs.trim().length === 0;
+
+        if (oursEmpty && !theirsEmpty) {
+          strategy = 'theirs';
+          confidence = 'HIGH';
+          reasoning = 'Additive hunk: theirs adds new content, ours is empty';
+        } else if (theirsEmpty && !oursEmpty) {
+          strategy = 'ours';
+          confidence = 'HIGH';
+          reasoning = 'Additive hunk: ours adds new content, theirs is empty';
+        } else {
+          // Both sides have content but one is a superset -- take the superset
+          const oursLines = hunk.ours.split('\n').filter(l => l.trim());
+          const theirsLines = hunk.theirs.split('\n').filter(l => l.trim());
+          if (theirsLines.length >= oursLines.length) {
+            strategy = 'theirs';
+            confidence = 'HIGH';
+            reasoning = 'Additive hunk: theirs is a superset of ours';
+          } else {
+            strategy = 'ours';
+            confidence = 'HIGH';
+            reasoning = 'Additive hunk: ours is a superset of theirs';
+          }
+        }
+        break;
+      }
+
+      case 'DELETION': {
+        // Take the side that keeps content unless plan context says deletion was intentional
+        const deletionIntentional = contextText.includes('remove') || contextText.includes('delete') ||
+          contextText.includes('deprecat') || contextText.includes('clean up') || contextText.includes('strip');
+
+        if (deletionIntentional) {
+          // Plan context suggests deletion was intentional
+          const oursEmpty = !hunk.ours || hunk.ours.trim().length === 0;
+          strategy = oursEmpty ? 'ours' : 'theirs';
+          confidence = 'MEDIUM';
+          reasoning = 'Deletion hunk: plan context suggests removal was intentional';
+        } else {
+          // Keep content (take the non-empty side)
+          const oursEmpty = !hunk.ours || hunk.ours.trim().length === 0;
+          strategy = oursEmpty ? 'theirs' : 'ours';
+          confidence = 'MEDIUM';
+          reasoning = 'Deletion hunk: keeping content (no plan context for intentional deletion)';
+        }
+        break;
+      }
+
+      case 'STRUCTURAL': {
+        // Attempt combined resolution if changes are to different structural elements
+        const oursLines = (hunk.ours || '').split('\n').filter(l => l.trim());
+        const theirsLines = (hunk.theirs || '').split('\n').filter(l => l.trim());
+
+        // Check if both sides add imports/requires (combinable)
+        const oursImports = oursLines.filter(l => /^\s*(const\s+\w+\s*=\s*require|import\s+|require\s*\()/.test(l));
+        const theirsImports = theirsLines.filter(l => /^\s*(const\s+\w+\s*=\s*require|import\s+|require\s*\()/.test(l));
+
+        if (oursImports.length > 0 && theirsImports.length > 0) {
+          // Both sides add imports -- can combine
+          strategy = 'combined';
+          confidence = 'HIGH';
+          reasoning = 'Structural hunk: both sides add imports/requires, combining and deduplicating';
+        } else if (oursImports.length > 0 || theirsImports.length > 0) {
+          // Only one side has imports
+          strategy = 'combined';
+          confidence = 'MEDIUM';
+          reasoning = 'Structural hunk: one side adds imports, combining with other changes';
+        } else {
+          // Same structural element modified differently
+          const oursSet = new Set(oursLines.map(l => l.trim()));
+          const theirsSet = new Set(theirsLines.map(l => l.trim()));
+          const overlap = oursLines.filter(l => theirsSet.has(l.trim()));
+
+          if (overlap.length === 0) {
+            // Different structural elements -- can combine
+            strategy = 'combined';
+            confidence = 'MEDIUM';
+            reasoning = 'Structural hunk: changes target different structural elements';
+          } else {
+            // Same element modified differently
+            strategy = 'escalate';
+            confidence = 'LOW';
+            reasoning = 'Structural hunk: same structural element modified differently, needs manual review';
+          }
+        }
+        break;
+      }
+
+      case 'DIVERGENT': {
+        // Use plan context to determine intent
+        if (contextText.length > 0) {
+          // Check if both plan tasks explain their changes clearly
+          const oursLines = (hunk.ours || '').split('\n').filter(l => l.trim());
+          const theirsLines = (hunk.theirs || '').split('\n').filter(l => l.trim());
+          const oursSet = new Set(oursLines.map(l => l.trim()));
+          const theirsSet = new Set(theirsLines.map(l => l.trim()));
+          const overlap = oursLines.filter(l => theirsSet.has(l.trim()));
+
+          if (overlap.length === 0) {
+            // No overlapping lines, changes don't conflict semantically
+            strategy = 'combined';
+            confidence = 'MEDIUM';
+            reasoning = 'Divergent hunk: plan context available, no overlapping lines, attempting combined resolution';
+          } else {
+            strategy = 'escalate';
+            confidence = 'LOW';
+            reasoning = 'Divergent hunk: overlapping lines with plan context, needs manual review';
+          }
+        } else {
+          strategy = 'escalate';
+          confidence = 'LOW';
+          reasoning = 'Divergent hunk: no plan context available, needs manual review';
+        }
+        break;
+      }
+
+      default:
+        strategy = 'escalate';
+        confidence = 'LOW';
+        reasoning = 'Unknown hunk type: ' + hunk.type;
+    }
+
+    // Boost confidence if accumulated learnings contain info about same domain/file
+    if (learnings && learnings.domain_changes) {
+      const domains = Object.keys(learnings.domain_changes);
+      if (domains.length > 0) {
+        const hunkText = ((hunk.ours || '') + ' ' + (hunk.theirs || '')).toLowerCase();
+        const domainMatch = domains.some(d => hunkText.includes(d.toLowerCase()));
+
+        if (domainMatch) {
+          if (confidence === 'LOW') {
+            confidence = 'MEDIUM';
+            reasoning += '. Confidence boosted by accumulated learnings from same domain';
+          } else if (confidence === 'MEDIUM') {
+            confidence = 'HIGH';
+            reasoning += '. Confidence boosted by accumulated learnings from same domain';
+          }
+        }
+      }
+    }
+
+    return { hunk_index: index, strategy, confidence, reasoning };
+  });
+}
+
+// ─── Section 2: Whole-File Resolution ────────────────────────────────────────
+
+/**
+ * Resolve a file's content by applying per-hunk strategy decisions.
+ *
+ * @param {string} fileContent - File content with conflict markers
+ * @param {Array<{hunk_index: number, strategy: string}>} strategies - Per-hunk strategy decisions
+ * @param {string|null} mergeBaseContent - Optional file content from merge-base
+ * @returns {{resolved_content: string, has_unresolved: boolean, applied: number, escalated: number}}
+ */
+function resolveFileContent(fileContent, strategies, mergeBaseContent) {
+  const lines = fileContent.split('\n');
+  const result = [];
+  let inConflict = false;
+  let inOurs = false;
+  let hunkIndex = 0;
+  let oursLines = [];
+  let theirsLines = [];
+  let applied = 0;
+  let escalated = 0;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    if (/^<{7}/.test(line)) {
+      inConflict = true;
+      inOurs = true;
+      oursLines = [];
+      theirsLines = [];
+      continue;
+    }
+
+    if (inConflict && /^={7}/.test(line)) {
+      inOurs = false;
+      continue;
+    }
+
+    if (inConflict && /^>{7}/.test(line)) {
+      // End of conflict hunk -- apply strategy
+      const strategyEntry = strategies.find(s => s.hunk_index === hunkIndex);
+      const strategy = strategyEntry ? strategyEntry.strategy : 'escalate';
+
+      switch (strategy) {
+        case 'ours':
+          result.push(...oursLines);
+          applied++;
+          break;
+
+        case 'theirs':
+          result.push(...theirsLines);
+          applied++;
+          break;
+
+        case 'combined': {
+          // For structural hunks with imports/requires, deduplicate and sort
+          const oursImportLines = oursLines.filter(l => /^\s*(const\s+\w+\s*=\s*require|import\s+|require\s*\()/.test(l));
+          const theirsImportLines = theirsLines.filter(l => /^\s*(const\s+\w+\s*=\s*require|import\s+|require\s*\()/.test(l));
+
+          if (oursImportLines.length > 0 && theirsImportLines.length > 0 &&
+              oursImportLines.length === oursLines.length && theirsImportLines.length === theirsLines.length) {
+            // All lines are imports -- deduplicate and sort alphabetically
+            const allImports = [...oursLines, ...theirsLines];
+            const unique = [...new Set(allImports.map(l => l.trim()))];
+            unique.sort((a, b) => a.localeCompare(b));
+            result.push(...unique);
+          } else {
+            // General combined: ours first, then theirs
+            result.push(...oursLines);
+            result.push(...theirsLines);
+          }
+          applied++;
+          break;
+        }
+
+        case 'escalate':
+        default:
+          // Leave conflict markers in place
+          result.push('<<<<<<< ours');
+          result.push(...oursLines);
+          result.push('=======');
+          result.push(...theirsLines);
+          result.push('>>>>>>> theirs');
+          escalated++;
+          break;
+      }
+
+      hunkIndex++;
+      inConflict = false;
+      inOurs = false;
+      continue;
+    }
+
+    if (inConflict) {
+      if (inOurs) {
+        oursLines.push(line);
+      } else {
+        theirsLines.push(line);
+      }
+    } else {
+      result.push(line);
+    }
+  }
+
+  const resolvedContent = result.join('\n');
+  return {
+    resolved_content: resolvedContent,
+    has_unresolved: escalated > 0,
+    applied,
+    escalated,
+  };
+}
+
+// ─── Section 3: Resolution Report ────────────────────────────────────────────
+
+/**
+ * Build a RESOLUTION-REPORT.md content string from per-file resolution results.
+ *
+ * @param {Array<{file: string, hunks: Array, strategies: Array, result: Object}>} fileResults
+ * @param {{branches: {ours: string, theirs: string}, phase: string, timestamp: string, semantic_warnings: Array}} metadata
+ * @returns {string}
+ */
+function buildResolutionReport(fileResults, metadata) {
+  const lines = [];
+
+  lines.push('# Conflict Resolution Report');
+  lines.push('');
+  lines.push('## Metadata');
+  lines.push('');
+  lines.push('| Field | Value |');
+  lines.push('| ----- | ----- |');
+  lines.push(`| Phase | ${metadata.phase || 'unknown'} |`);
+  lines.push(`| Ours Branch | ${metadata.branches?.ours || 'unknown'} |`);
+  lines.push(`| Theirs Branch | ${metadata.branches?.theirs || 'unknown'} |`);
+  lines.push(`| Timestamp | ${metadata.timestamp || new Date().toISOString()} |`);
+  lines.push(`| Total Files | ${fileResults.length} |`);
+
+  // Confidence breakdown
+  const confidenceCounts = { HIGH: 0, MEDIUM: 0, LOW: 0 };
+  const strategyCounts = { ours: 0, theirs: 0, combined: 0, escalate: 0 };
+
+  for (const fr of fileResults) {
+    for (const s of (fr.strategies || [])) {
+      if (confidenceCounts[s.confidence] !== undefined) confidenceCounts[s.confidence]++;
+      if (strategyCounts[s.strategy] !== undefined) strategyCounts[s.strategy]++;
+    }
+  }
+
+  lines.push(`| HIGH Confidence | ${confidenceCounts.HIGH} |`);
+  lines.push(`| MEDIUM Confidence | ${confidenceCounts.MEDIUM} |`);
+  lines.push(`| LOW Confidence | ${confidenceCounts.LOW} |`);
+  lines.push('');
+
+  // Resolved Conflicts section
+  lines.push('## Resolved Conflicts');
+  lines.push('');
+
+  for (const fr of fileResults) {
+    lines.push(`### ${fr.file}`);
+    lines.push('');
+
+    if (fr.strategies && fr.hunks) {
+      for (let i = 0; i < fr.strategies.length; i++) {
+        const s = fr.strategies[i];
+        const h = fr.hunks[i];
+
+        lines.push(`**Hunk ${i + 1}** (lines ${h ? h.start_line : '?'}-${h ? h.end_line : '?'})`);
+        lines.push('');
+        lines.push(`- Classification: ${h ? h.type : 'unknown'}`);
+        lines.push(`- Strategy: ${s.strategy}`);
+        lines.push(`- Confidence: ${s.confidence}`);
+        lines.push(`- Reasoning: ${s.reasoning}`);
+        lines.push('');
+
+        // Before/after snippets (truncated to 10 lines each side)
+        if (h) {
+          const oursSnippet = (h.ours || '').split('\n').slice(0, 10).join('\n');
+          const theirsSnippet = (h.theirs || '').split('\n').slice(0, 10).join('\n');
+
+          if (oursSnippet.trim()) {
+            lines.push('<details><summary>Ours side (truncated)</summary>');
+            lines.push('');
+            lines.push('```');
+            lines.push(oursSnippet);
+            lines.push('```');
+            lines.push('</details>');
+            lines.push('');
+          }
+
+          if (theirsSnippet.trim()) {
+            lines.push('<details><summary>Theirs side (truncated)</summary>');
+            lines.push('');
+            lines.push('```');
+            lines.push(theirsSnippet);
+            lines.push('```');
+            lines.push('</details>');
+            lines.push('');
+          }
+        }
+      }
+    }
+
+    if (fr.result) {
+      lines.push(`**Result:** ${fr.result.applied} applied, ${fr.result.escalated} escalated`);
+      lines.push('');
+    }
+  }
+
+  // Semantic Warnings section
+  lines.push('## Semantic Warnings');
+  lines.push('');
+
+  const warnings = metadata.semantic_warnings || [];
+  if (warnings.length === 0) {
+    lines.push('No semantic conflicts detected.');
+  } else {
+    for (const w of warnings) {
+      lines.push(`- **${w.file}** (${w.risk}): ${w.domain} -- ours: ${w.ours_changes}, theirs: ${w.theirs_changes}`);
+    }
+  }
+  lines.push('');
+
+  // Summary section
+  lines.push('## Summary');
+  lines.push('');
+  lines.push('| Strategy | Count |');
+  lines.push('| -------- | ----- |');
+  lines.push(`| ours | ${strategyCounts.ours} |`);
+  lines.push(`| theirs | ${strategyCounts.theirs} |`);
+  lines.push(`| combined | ${strategyCounts.combined} |`);
+  lines.push(`| escalate | ${strategyCounts.escalate} |`);
+  lines.push('');
+  lines.push('| Confidence | Count |');
+  lines.push('| ---------- | ----- |');
+  lines.push(`| HIGH | ${confidenceCounts.HIGH} |`);
+  lines.push(`| MEDIUM | ${confidenceCounts.MEDIUM} |`);
+  lines.push(`| LOW | ${confidenceCounts.LOW} |`);
+  lines.push('');
+
+  const allHigh = confidenceCounts.LOW === 0 && confidenceCounts.MEDIUM === 0;
+  const hasLow = confidenceCounts.LOW > 0;
+  const assessment = allHigh ? 'Clean merge -- all resolutions are HIGH confidence'
+    : hasLow ? 'Manual review recommended -- LOW confidence resolutions present'
+    : 'Mostly clean merge -- MEDIUM confidence resolutions may need review';
+
+  lines.push(`**Overall Assessment:** ${assessment}`);
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+// ─── Section 4: Post-Resolution Verification ─────────────────────────────────
+
+/**
+ * Run post-resolution verification (tests, linting, syntax check) on resolved files.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string[]} resolvedFiles - List of resolved file paths
+ * @returns {{passed: boolean, test_output: string|null, lint_output: string|null, errors: string[]}}
+ */
+function verifyResolution(cwd, resolvedFiles) {
+  const errors = [];
+  let testOutput = null;
+  let lintOutput = null;
+
+  // Check for package.json with test/lint scripts
+  const pkgPath = path.join(cwd, 'package.json');
+  const pkgContent = safeReadFile(pkgPath);
+  let pkg = null;
+
+  if (pkgContent) {
+    try {
+      pkg = JSON.parse(pkgContent);
+    } catch {
+      // Invalid package.json
+    }
+  }
+
+  const hasTestScript = pkg && pkg.scripts && pkg.scripts.test && pkg.scripts.test !== 'echo "Error: no test specified" && exit 1';
+  const hasLintScript = pkg && pkg.scripts && (pkg.scripts.lint || pkg.scripts.eslint);
+
+  // Run tests if available
+  if (hasTestScript) {
+    try {
+      testOutput = execSync('npm test', {
+        cwd,
+        stdio: 'pipe',
+        encoding: 'utf-8',
+        timeout: 60000,
+      });
+    } catch (err) {
+      testOutput = (err.stdout || '') + '\n' + (err.stderr || '');
+      errors.push('Test suite failed: ' + (err.stderr || err.message || '').slice(0, 500));
+    }
+  }
+
+  // Run linter if available
+  if (hasLintScript) {
+    const lintCmd = pkg.scripts.lint ? 'npm run lint' : 'npm run eslint';
+    try {
+      lintOutput = execSync(lintCmd, {
+        cwd,
+        stdio: 'pipe',
+        encoding: 'utf-8',
+        timeout: 30000,
+      });
+    } catch (err) {
+      lintOutput = (err.stdout || '') + '\n' + (err.stderr || '');
+      errors.push('Linter failed: ' + (err.stderr || err.message || '').slice(0, 500));
+    }
+  }
+
+  // If no test/lint scripts, check syntax for JS/CJS/TS files
+  if (!hasTestScript && !hasLintScript) {
+    for (const filePath of resolvedFiles) {
+      const ext = path.extname(filePath).toLowerCase();
+      if (['.js', '.cjs', '.mjs', '.ts'].includes(ext)) {
+        const fullPath = path.isAbsolute(filePath) ? filePath : path.join(cwd, filePath);
+        try {
+          execSync('node --check ' + JSON.stringify(fullPath), {
+            cwd,
+            stdio: 'pipe',
+            encoding: 'utf-8',
+            timeout: 10000,
+          });
+        } catch (err) {
+          errors.push('Syntax error in ' + filePath + ': ' + (err.stderr || err.message || '').slice(0, 300));
+        }
+      }
+    }
+  }
+
+  return {
+    passed: errors.length === 0,
+    test_output: testOutput,
+    lint_output: lintOutput,
+    errors,
+  };
+}
+
+// ─── Section 5: Semantic Conflict Detection ──────────────────────────────────
+
+/**
+ * Detect semantic conflicts in cleanly merged files.
+ *
+ * For files that merged cleanly (no conflict markers), checks if both branches
+ * modified the same file and if plan context shows they touched the same domain.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string[]} cleanFiles - Files that merged cleanly
+ * @param {Array<{task_name: string, action_excerpt: string}>|null} planContext
+ * @returns {Array<{file: string, domain: string, ours_changes: string, theirs_changes: string, risk: string}>}
+ */
+function detectSemanticConflicts(cwd, cleanFiles, planContext) {
+  const warnings = [];
+
+  for (const filePath of cleanFiles) {
+    // Check if BOTH branches modified this file
+    const oursLog = execGit(cwd, ['log', '--oneline', 'MERGE_HEAD..HEAD', '--', filePath]);
+    const theirsLog = execGit(cwd, ['log', '--oneline', 'HEAD..MERGE_HEAD', '--', filePath]);
+
+    const oursModified = oursLog.exitCode === 0 && oursLog.stdout && oursLog.stdout.trim().length > 0;
+    const theirsModified = theirsLog.exitCode === 0 && theirsLog.stdout && theirsLog.stdout.trim().length > 0;
+
+    if (!oursModified || !theirsModified) continue;
+
+    // Both branches modified this file -- check if same domain
+    const oursChanges = oursLog.stdout.split('\n').filter(l => l.trim()).map(l => l.trim()).join('; ');
+    const theirsChanges = theirsLog.stdout.split('\n').filter(l => l.trim()).map(l => l.trim()).join('; ');
+
+    // Extract domain from file path and plan context
+    const fileName = path.basename(filePath, path.extname(filePath));
+    let domain = fileName;
+
+    // Check plan context for domain overlap
+    let risk = 'info';
+    if (planContext && Array.isArray(planContext)) {
+      const contextText = planContext.map(c => (c.task_name || '') + ' ' + (c.action_excerpt || '')).join(' ').toLowerCase();
+
+      // Check if plan context mentions this file's domain
+      if (contextText.includes(fileName.toLowerCase())) {
+        // Both branches have plan context for this file's domain -- higher risk
+        risk = 'warning';
+        domain = fileName + ' (plan context overlap)';
+      }
+    }
+
+    // Check for same-function/class/exports modifications using diff
+    const oursDiff = execGit(cwd, ['diff', 'MERGE_HEAD...HEAD', '--', filePath]);
+    const theirsDiff = execGit(cwd, ['diff', 'HEAD...MERGE_HEAD', '--', filePath]);
+
+    if (oursDiff.exitCode === 0 && theirsDiff.exitCode === 0) {
+      const oursFunctions = extractModifiedFunctions(oursDiff.stdout);
+      const theirsFunctions = extractModifiedFunctions(theirsDiff.stdout);
+
+      const sharedFunctions = oursFunctions.filter(f => theirsFunctions.includes(f));
+      if (sharedFunctions.length > 0) {
+        risk = 'warning';
+        domain = sharedFunctions.join(', ');
+      }
+    }
+
+    warnings.push({
+      file: filePath,
+      domain,
+      ours_changes: oursChanges.slice(0, 200),
+      theirs_changes: theirsChanges.slice(0, 200),
+      risk,
+    });
+  }
+
+  return warnings;
+}
+
+/**
+ * Extract function/class names from a git diff output.
+ *
+ * @param {string} diffOutput - Output from git diff
+ * @returns {string[]}
+ */
+function extractModifiedFunctions(diffOutput) {
+  const functions = [];
+  const lines = diffOutput.split('\n');
+
+  for (const line of lines) {
+    if (!line.startsWith('+') && !line.startsWith('-')) continue;
+    if (line.startsWith('+++') || line.startsWith('---')) continue;
+
+    const content = line.slice(1);
+    const funcMatch = content.match(/^\s*(?:function\s+(\w+)|(?:const|let|var)\s+(\w+)\s*=\s*(?:function|async\s+function|\(|async\s*\())/);
+    if (funcMatch) {
+      functions.push(funcMatch[1] || funcMatch[2]);
+    }
+
+    const classMatch = content.match(/^\s*class\s+(\w+)/);
+    if (classMatch) {
+      functions.push(classMatch[1]);
+    }
+
+    const exportsMatch = content.match(/^\s*module\.exports\s*[.=]/);
+    if (exportsMatch) {
+      functions.push('module.exports');
+    }
+  }
+
+  return [...new Set(functions)];
+}
+
+// ─── Section 6: Cascading Context ────────────────────────────────────────────
+
+/**
+ * Extract learnings from completed resolution results.
+ *
+ * @param {Array<{file: string, strategies: Array, result: Object}>} resolutionResults
+ * @returns {{files_resolved: string[], strategies_used: Array, domain_changes: Object, phase_merges_completed: number}}
+ */
+function createLearningContext(resolutionResults) {
+  const filesResolved = [];
+  const strategiesUsed = [];
+  const domainChanges = {};
+
+  for (const res of resolutionResults) {
+    filesResolved.push(res.file);
+
+    if (res.strategies) {
+      for (const s of res.strategies) {
+        strategiesUsed.push({ file: res.file, strategy: s.strategy });
+      }
+    }
+
+    // Extract domain from file path
+    const domain = path.basename(res.file, path.extname(res.file));
+    domainChanges[domain] = `Resolved via ${(res.strategies || []).map(s => s.strategy).join(', ')}`;
+  }
+
+  return {
+    files_resolved: filesResolved,
+    strategies_used: strategiesUsed,
+    domain_changes: domainChanges,
+    phase_merges_completed: 1,
+  };
+}
+
+/**
+ * Accumulate learnings across sequential phase merges.
+ *
+ * @param {Object|null} existing - Existing learnings context
+ * @param {Object} newLearnings - New learnings to merge
+ * @returns {{files_resolved: string[], strategies_used: Array, domain_changes: Object, phase_merges_completed: number}}
+ */
+function mergeLearningContexts(existing, newLearnings) {
+  if (!existing) return { ...newLearnings };
+
+  return {
+    files_resolved: [...(existing.files_resolved || []), ...(newLearnings.files_resolved || [])],
+    strategies_used: [...(existing.strategies_used || []), ...(newLearnings.strategies_used || [])],
+    domain_changes: { ...(existing.domain_changes || {}), ...(newLearnings.domain_changes || {}) },
+    phase_merges_completed: (existing.phase_merges_completed || 0) + (newLearnings.phase_merges_completed || 0),
+  };
+}
+
+// ─── Section 7: CLI Command Handlers ─────────────────────────────────────────
+
+/**
+ * Orchestrate the full conflict resolution flow.
+ *
+ * 1. Detect conflicted files
+ * 2. For each file: get context, classify hunks, select strategy, resolve
+ * 3. Write resolved content to files
+ * 4. Run verification
+ * 5. If verification fails: roll back resolved files
+ * 6. If verification passes: record resolutions, build report
+ * 7. Output JSON summary
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} phaseDir - Phase directory for context and report output
+ * @param {boolean} raw - Raw output mode
+ * @param {string|null} learningsFile - Path to accumulated learnings JSON file
+ */
+function cmdConflictAgentRun(cwd, phaseDir, raw, learningsFile) {
+  if (!phaseDir) error('--phase-dir required for conflict-agent run');
+
+  const absPhaseDir = path.isAbsolute(phaseDir) ? phaseDir : path.join(cwd, phaseDir);
+
+  // Load accumulated learnings from prior phase merges
+  let learnings = null;
+  if (learningsFile) {
+    try {
+      const learningsContent = safeReadFile(learningsFile);
+      if (learningsContent) {
+        learnings = JSON.parse(learningsContent);
+      }
+    } catch {
+      // Learnings file not parseable -- proceed without
+    }
+  }
+  const timestamp = new Date().toISOString();
+
+  // Step 1: Detect conflicted files
+  const diffResult = execGit(cwd, ['diff', '--name-only', '--diff-filter=U']);
+  const conflictedFiles = diffResult.exitCode === 0 && diffResult.stdout
+    ? diffResult.stdout.split('\n').filter(f => f.trim())
+    : [];
+
+  if (conflictedFiles.length === 0) {
+    // No conflicts -- check for semantic conflicts in cleanly merged files
+    const mergeHeadResult = execGit(cwd, ['rev-parse', 'MERGE_HEAD']);
+    let semanticWarnings = [];
+
+    if (mergeHeadResult.exitCode === 0) {
+      // Get list of all files modified in the merge
+      const mergeFiles = execGit(cwd, ['diff', '--name-only', 'HEAD...MERGE_HEAD']);
+      if (mergeFiles.exitCode === 0 && mergeFiles.stdout) {
+        const cleanFiles = mergeFiles.stdout.split('\n').filter(f => f.trim());
+        semanticWarnings = detectSemanticConflicts(cwd, cleanFiles, null);
+      }
+    }
+
+    output({
+      resolved_count: 0,
+      escalated_count: 0,
+      verified: true,
+      semantic_warnings: semanticWarnings.length,
+      report_path: null,
+    }, raw);
+    return;
+  }
+
+  // Step 2: For each file, get context, classify, select strategy, resolve
+  const fileResults = [];
+  const resolvedFilePaths = [];
+  const originalContents = {};
+
+  for (const filePath of conflictedFiles) {
+    const fullPath = path.join(cwd, filePath);
+    const fileContent = safeReadFile(fullPath);
+    if (!fileContent) continue;
+
+    // Save original for rollback
+    originalContents[filePath] = fileContent;
+
+    // Assemble plan context from phase dir
+    let planContext = [];
+    try {
+      const phaseFiles = fs.readdirSync(absPhaseDir);
+      const planFiles = phaseFiles.filter(f => f.match(/\d+-PLAN\.md$/i) || f === 'PLAN.md');
+
+      for (const planFile of planFiles) {
+        const planContent = safeReadFile(path.join(absPhaseDir, planFile));
+        if (!planContent) continue;
+
+        const fm = extractFrontmatter(planContent);
+        const planNumber = fm.plan || planFile.replace(/-PLAN\.md$/i, '');
+
+        const taskPattern = /<task\b[^>]*>([\s\S]*?)<\/task>/g;
+        let match;
+        while ((match = taskPattern.exec(planContent)) !== null) {
+          const taskBody = match[1];
+          const nameMatch = taskBody.match(/<name>([\s\S]*?)<\/name>/);
+          const filesMatch = taskBody.match(/<files>([\s\S]*?)<\/files>/);
+          const actionMatch = taskBody.match(/<action>([\s\S]*?)<\/action>/);
+
+          if (filesMatch) {
+            const filesList = filesMatch[1].split(/[\n,]/).map(f => f.trim()).filter(f => f);
+            const normalizedFilePath = filePath.replace(/^\.\//, '');
+
+            if (filesList.some(f => normalizedFilePath.includes(f.replace(/^\.\//, '')) || f.replace(/^\.\//, '').includes(normalizedFilePath))) {
+              planContext.push({
+                plan: planNumber,
+                task_name: nameMatch ? nameMatch[1].trim() : 'unnamed',
+                action_excerpt: actionMatch ? actionMatch[1].trim().slice(0, 200) : '',
+              });
+            }
+          }
+        }
+      }
+    } catch {
+      // Phase dir not readable
+    }
+
+    // Classify hunks
+    const classifiedHunks = classifyConflictHunks(fileContent, planContext.length > 0 ? planContext : null);
+
+    // Select strategies
+    const strategies = selectResolutionStrategy(classifiedHunks, planContext, learnings);
+
+    // Resolve file content
+    const result = resolveFileContent(fileContent, strategies, null);
+
+    fileResults.push({
+      file: filePath,
+      hunks: classifiedHunks,
+      strategies,
+      result,
+    });
+
+    // Step 3: Write resolved content to file
+    if (!result.has_unresolved) {
+      fs.writeFileSync(fullPath, result.resolved_content, 'utf-8');
+      resolvedFilePaths.push(filePath);
+    }
+  }
+
+  // Step 4: Run verification
+  const verification = verifyResolution(cwd, resolvedFilePaths);
+
+  if (!verification.passed) {
+    // Step 5: Roll back resolved files
+    for (const filePath of resolvedFilePaths) {
+      const fullPath = path.join(cwd, filePath);
+      if (originalContents[filePath]) {
+        fs.writeFileSync(fullPath, originalContents[filePath], 'utf-8');
+      }
+    }
+
+    output({
+      resolved_count: 0,
+      escalated_count: fileResults.reduce((acc, fr) => acc + (fr.result?.escalated || 0), 0),
+      verified: false,
+      verification_errors: verification.errors,
+      semantic_warnings: 0,
+      report_path: null,
+    }, raw);
+    return;
+  }
+
+  // Step 6: Record resolutions and build report
+  // Record each resolution via merge-conflicts resolved (internal function call)
+  for (const fr of fileResults) {
+    if (fr.result && !fr.result.has_unresolved) {
+      const resolutionJson = JSON.stringify({
+        strategy: fr.strategies.length === 1 ? fr.strategies[0].strategy : 'combined',
+        description: fr.strategies.map(s => s.reasoning).join('; '),
+        confidence: fr.strategies.reduce((min, s) => {
+          const order = { HIGH: 3, MEDIUM: 2, LOW: 1 };
+          return (order[s.confidence] || 0) < (order[min] || 0) ? s.confidence : min;
+        }, 'HIGH'),
+      });
+
+      // Write resolution record
+      const resolutionsPath = path.join(absPhaseDir, 'RESOLUTIONS.md');
+      let existing = safeReadFile(resolutionsPath);
+      if (!existing) {
+        const phaseName = path.basename(absPhaseDir);
+        existing = `# Merge Conflict Resolutions\n\n**Phase:** ${phaseName}\n**Created:** ${timestamp}\n\n---\n\n`;
+      }
+
+      const res = JSON.parse(resolutionJson);
+      const entry = [
+        `### ${fr.file}\n`,
+        `- **Strategy:** ${res.strategy}`,
+        `- **Confidence:** ${res.confidence}`,
+        `- **Description:** ${res.description || 'No description provided'}`,
+        `- **Resolved:** ${timestamp}`,
+        '',
+      ].join('\n');
+
+      fs.writeFileSync(resolutionsPath, existing + entry + '\n', 'utf-8');
+    }
+  }
+
+  // Detect semantic conflicts in cleanly merged files
+  let semanticWarnings = [];
+  const mergeHeadResult = execGit(cwd, ['rev-parse', 'MERGE_HEAD']);
+  if (mergeHeadResult.exitCode === 0) {
+    const allDiff = execGit(cwd, ['diff', '--name-only', 'HEAD...MERGE_HEAD']);
+    if (allDiff.exitCode === 0 && allDiff.stdout) {
+      const allFiles = allDiff.stdout.split('\n').filter(f => f.trim());
+      const cleanFiles = allFiles.filter(f => !conflictedFiles.includes(f));
+      if (cleanFiles.length > 0) {
+        semanticWarnings = detectSemanticConflicts(cwd, cleanFiles, null);
+      }
+    }
+  }
+
+  // Get branch info for report
+  const branchResult = execGit(cwd, ['branch', '--show-current']);
+  const oursBranch = branchResult.exitCode === 0 ? branchResult.stdout : 'unknown';
+  let theirsBranch = 'unknown';
+  if (mergeHeadResult.exitCode === 0) {
+    const theirsRef = execGit(cwd, ['log', '-1', '--format=%D', 'MERGE_HEAD']);
+    if (theirsRef.exitCode === 0 && theirsRef.stdout) {
+      theirsBranch = theirsRef.stdout;
+    }
+  }
+
+  // Build report
+  const reportContent = buildResolutionReport(fileResults, {
+    branches: { ours: oursBranch, theirs: theirsBranch },
+    phase: path.basename(absPhaseDir),
+    timestamp,
+    semantic_warnings: semanticWarnings,
+  });
+
+  const reportPath = path.join(absPhaseDir, 'RESOLUTION-REPORT.md');
+  fs.writeFileSync(reportPath, reportContent, 'utf-8');
+
+  // Step 7: Output summary
+  const totalResolved = fileResults.reduce((acc, fr) => acc + (fr.result?.applied || 0), 0);
+  const totalEscalated = fileResults.reduce((acc, fr) => acc + (fr.result?.escalated || 0), 0);
+
+  // Extract learnings from resolution results for cascading context
+  const newLearnings = createLearningContext(fileResults);
+
+  output({
+    resolved_count: totalResolved,
+    escalated_count: totalEscalated,
+    verified: true,
+    semantic_warnings: semanticWarnings.length,
+    report_path: reportPath,
+    learnings: newLearnings,
+  }, raw);
+}
+
+/**
+ * Resolve a single file (used by escalation retry flow).
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} filePath - Path to the conflicted file
+ * @param {string} phaseDir - Phase directory for context
+ * @param {boolean} raw - Raw output mode
+ * @param {string|null} hint - Optional user hint text for guiding resolution strategy
+ */
+function cmdConflictAgentResolveFile(cwd, filePath, phaseDir, raw, hint) {
+  if (!filePath) error('File path required');
+  if (!phaseDir) error('--phase-dir required for resolve-file command');
+
+  const fullPath = path.isAbsolute(filePath) ? filePath : path.join(cwd, filePath);
+  const fileContent = safeReadFile(fullPath);
+
+  if (!fileContent) {
+    error('File not found: ' + filePath);
+  }
+
+  if (!/^<{7}/m.test(fileContent)) {
+    error('File has no conflict markers: ' + filePath);
+  }
+
+  const absPhaseDir = path.isAbsolute(phaseDir) ? phaseDir : path.join(cwd, phaseDir);
+
+  // Assemble plan context
+  let planContext = [];
+  try {
+    const phaseFiles = fs.readdirSync(absPhaseDir);
+    const planFiles = phaseFiles.filter(f => f.match(/\d+-PLAN\.md$/i) || f === 'PLAN.md');
+
+    for (const planFile of planFiles) {
+      const planContent = safeReadFile(path.join(absPhaseDir, planFile));
+      if (!planContent) continue;
+
+      const fm = extractFrontmatter(planContent);
+      const planNumber = fm.plan || planFile.replace(/-PLAN\.md$/i, '');
+
+      const taskPattern = /<task\b[^>]*>([\s\S]*?)<\/task>/g;
+      let match;
+      while ((match = taskPattern.exec(planContent)) !== null) {
+        const taskBody = match[1];
+        const nameMatch = taskBody.match(/<name>([\s\S]*?)<\/name>/);
+        const filesMatch = taskBody.match(/<files>([\s\S]*?)<\/files>/);
+        const actionMatch = taskBody.match(/<action>([\s\S]*?)<\/action>/);
+
+        if (filesMatch) {
+          const filesList = filesMatch[1].split(/[\n,]/).map(f => f.trim()).filter(f => f);
+          const normalizedFilePath = filePath.replace(/^\.\//, '');
+
+          if (filesList.some(f => normalizedFilePath.includes(f.replace(/^\.\//, '')) || f.replace(/^\.\//, '').includes(normalizedFilePath))) {
+            planContext.push({
+              plan: planNumber,
+              task_name: nameMatch ? nameMatch[1].trim() : 'unnamed',
+              action_excerpt: actionMatch ? actionMatch[1].trim().slice(0, 200) : '',
+            });
+          }
+        }
+      }
+    }
+  } catch {
+    // Phase dir not readable
+  }
+
+  // Classify and resolve
+  const classifiedHunks = classifyConflictHunks(fileContent, planContext.length > 0 ? planContext : null);
+
+  // Augment plan context with user hint if provided
+  let augmentedContext = planContext;
+  if (hint && hint.trim()) {
+    augmentedContext = [...planContext, {
+      plan: 'user-hint',
+      task_name: 'User escalation hint',
+      action_excerpt: hint.trim(),
+    }];
+  }
+  const strategies = selectResolutionStrategy(classifiedHunks, augmentedContext, null);
+  const result = resolveFileContent(fileContent, strategies, null);
+
+  // Write resolved content
+  if (!result.has_unresolved) {
+    fs.writeFileSync(fullPath, result.resolved_content, 'utf-8');
+  }
+
+  output({
+    file: filePath,
+    hint_applied: !!hint,
+    hunks: classifiedHunks.length,
+    applied: result.applied,
+    escalated: result.escalated,
+    has_unresolved: result.has_unresolved,
+    strategies: strategies.map(s => ({ strategy: s.strategy, confidence: s.confidence })),
+  }, raw);
+}
+
+// ─── Exports ─────────────────────────────────────────────────────────────────
+
+module.exports = {
+  resolveConflicts: cmdConflictAgentRun,
+  verifyResolution,
+  detectSemanticConflicts,
+  selectResolutionStrategy,
+  resolveFileContent,
+  buildResolutionReport,
+  createLearningContext,
+  mergeLearningContexts,
+  cmdConflictAgentRun,
+  cmdConflictAgentResolveFile,
+};