@ktpartners/dgs-platform 2.6.2

package/deliver-great-systems/bin/lib/milestone.cjs

@@ -0,0 +1,243 @@
+/**
+ * Milestone — Milestone and requirements lifecycle operations
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { escapeRegex, getMilestonePhaseFilter, output, error } = require('./core.cjs');
+const { extractFrontmatter } = require('./frontmatter.cjs');
+const { getPlanningRoot } = require('./paths.cjs');
+const { writeStateMd } = require('./state.cjs');
+
+function cmdRequirementsMarkComplete(cwd, reqIdsRaw, raw) {
+  if (!reqIdsRaw || reqIdsRaw.length === 0) {
+    error('requirement IDs required. Usage: requirements mark-complete REQ-01,REQ-02 or REQ-01 REQ-02');
+  }
+
+  // Accept comma-separated, space-separated, or bracket-wrapped: [REQ-01, REQ-02]
+  const reqIds = reqIdsRaw
+    .join(' ')
+    .replace(/[\[\]]/g, '')
+    .split(/[,\s]+/)
+    .map(r => r.trim())
+    .filter(Boolean);
+
+  if (reqIds.length === 0) {
+    error('no valid requirement IDs found');
+  }
+
+  const reqPath = path.join(getPlanningRoot(cwd), 'REQUIREMENTS.md');
+  if (!fs.existsSync(reqPath)) {
+    output({ updated: false, reason: 'REQUIREMENTS.md not found', ids: reqIds }, raw, 'no requirements file');
+    return;
+  }
+
+  let reqContent = fs.readFileSync(reqPath, 'utf-8');
+  const updated = [];
+  const notFound = [];
+
+  for (const reqId of reqIds) {
+    let found = false;
+    const reqEscaped = escapeRegex(reqId);
+
+    // Update checkbox: - [ ] **REQ-ID** → - [x] **REQ-ID**
+    const checkboxPattern = new RegExp(`(-\\s*\\[)[ ](\\]\\s*\\*\\*${reqEscaped}\\*\\*)`, 'gi');
+    if (checkboxPattern.test(reqContent)) {
+      reqContent = reqContent.replace(checkboxPattern, '$1x$2');
+      found = true;
+    }
+
+    // Update traceability table: | REQ-ID | Phase N | Pending | → | REQ-ID | Phase N | Complete |
+    const tablePattern = new RegExp(`(\\|\\s*${reqEscaped}\\s*\\|[^|]+\\|)\\s*Pending\\s*(\\|)`, 'gi');
+    if (tablePattern.test(reqContent)) {
+      // Re-read since test() advances lastIndex for global regex
+      reqContent = reqContent.replace(
+        new RegExp(`(\\|\\s*${reqEscaped}\\s*\\|[^|]+\\|)\\s*Pending\\s*(\\|)`, 'gi'),
+        '$1 Complete $2'
+      );
+      found = true;
+    }
+
+    if (found) {
+      updated.push(reqId);
+    } else {
+      notFound.push(reqId);
+    }
+  }
+
+  if (updated.length > 0) {
+    fs.writeFileSync(reqPath, reqContent, 'utf-8');
+  }
+
+  output({
+    updated: updated.length > 0,
+    marked_complete: updated,
+    not_found: notFound,
+    total: reqIds.length,
+  }, raw, `${updated.length}/${reqIds.length} requirements marked complete`);
+}
+
+function cmdMilestoneComplete(cwd, version, options, raw) {
+  if (!version) {
+    error('version required for milestone complete (e.g., v1.0)');
+  }
+
+  const planRoot = getPlanningRoot(cwd);
+  const roadmapPath = path.join(planRoot, 'ROADMAP.md');
+  const reqPath = path.join(planRoot, 'REQUIREMENTS.md');
+  const statePath = path.join(planRoot, 'STATE.md');
+  const milestonesPath = path.join(planRoot, 'MILESTONES.md');
+  const archiveDir = path.join(planRoot, 'milestones');
+  const phasesDir = path.join(planRoot, 'phases');
+  const today = new Date().toISOString().split('T')[0];
+  const milestoneName = options.name || version;
+
+  // Ensure archive directory exists
+  fs.mkdirSync(archiveDir, { recursive: true });
+
+  // Scope stats and accomplishments to only the phases belonging to the
+  // current milestone's ROADMAP.  Uses the shared filter from core.cjs
+  // (same logic used by cmdPhasesList and other callers).
+  const isDirInMilestone = getMilestonePhaseFilter(cwd);
+
+  // Gather stats from phases (scoped to current milestone only)
+  let phaseCount = 0;
+  let totalPlans = 0;
+  let totalTasks = 0;
+  const accomplishments = [];
+
+  try {
+    const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+    const dirs = entries.filter(e => e.isDirectory()).map(e => e.name).sort();
+
+    for (const dir of dirs) {
+      if (!isDirInMilestone(dir)) continue;
+
+      phaseCount++;
+      const phaseFiles = fs.readdirSync(path.join(phasesDir, dir));
+      const plans = phaseFiles.filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md');
+      const summaries = phaseFiles.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md');
+      totalPlans += plans.length;
+
+      // Extract one-liners from summaries
+      for (const s of summaries) {
+        try {
+          const content = fs.readFileSync(path.join(phasesDir, dir, s), 'utf-8');
+          const fm = extractFrontmatter(content);
+          if (fm['one-liner']) {
+            accomplishments.push(fm['one-liner']);
+          }
+          // Count tasks
+          const taskMatches = content.match(/##\s*Task\s*\d+/gi) || [];
+          totalTasks += taskMatches.length;
+        } catch {}
+      }
+    }
+  } catch {}
+
+  // Archive ROADMAP.md
+  if (fs.existsSync(roadmapPath)) {
+    const roadmapContent = fs.readFileSync(roadmapPath, 'utf-8');
+    fs.writeFileSync(path.join(archiveDir, `${version}-ROADMAP.md`), roadmapContent, 'utf-8');
+  }
+
+  // Archive REQUIREMENTS.md
+  if (fs.existsSync(reqPath)) {
+    const reqContent = fs.readFileSync(reqPath, 'utf-8');
+    const archiveHeader = `# Requirements Archive: ${version} ${milestoneName}\n\n**Archived:** ${today}\n**Status:** SHIPPED\n\nFor current requirements, see \`.planning/REQUIREMENTS.md\`.\n\n---\n\n`;
+    fs.writeFileSync(path.join(archiveDir, `${version}-REQUIREMENTS.md`), archiveHeader + reqContent, 'utf-8');
+  }
+
+  // Archive audit file if exists
+  const auditFile = path.join(planRoot, `${version}-MILESTONE-AUDIT.md`);
+  if (fs.existsSync(auditFile)) {
+    fs.renameSync(auditFile, path.join(archiveDir, `${version}-MILESTONE-AUDIT.md`));
+  }
+
+  // Create/append MILESTONES.md entry
+  const accomplishmentsList = accomplishments.map(a => `- ${a}`).join('\n');
+  const milestoneEntry = `## ${version} ${milestoneName} (Shipped: ${today})\n\n**Phases completed:** ${phaseCount} phases, ${totalPlans} plans, ${totalTasks} tasks\n\n**Key accomplishments:**\n${accomplishmentsList || '- (none recorded)'}\n\n---\n\n`;
+
+  if (fs.existsSync(milestonesPath)) {
+    const existing = fs.readFileSync(milestonesPath, 'utf-8');
+    if (!existing.trim()) {
+      // Empty file — treat like new
+      fs.writeFileSync(milestonesPath, `# Milestones\n\n${milestoneEntry}`, 'utf-8');
+    } else {
+      // Insert after the header line(s) for reverse chronological order (newest first)
+      const headerMatch = existing.match(/^(#{1,3}\s+[^\n]*\n\n?)/);
+      if (headerMatch) {
+        const header = headerMatch[1];
+        const rest = existing.slice(header.length);
+        fs.writeFileSync(milestonesPath, header + milestoneEntry + rest, 'utf-8');
+      } else {
+        // No recognizable header — prepend the entry
+        fs.writeFileSync(milestonesPath, milestoneEntry + existing, 'utf-8');
+      }
+    }
+  } else {
+    fs.writeFileSync(milestonesPath, `# Milestones\n\n${milestoneEntry}`, 'utf-8');
+  }
+
+  // Update STATE.md
+  if (fs.existsSync(statePath)) {
+    let stateContent = fs.readFileSync(statePath, 'utf-8');
+    stateContent = stateContent.replace(
+      /(\*\*Status:\*\*\s*).*/,
+      `$1${version} milestone complete`
+    );
+    stateContent = stateContent.replace(
+      /(\*\*Last Activity:\*\*\s*).*/,
+      `$1${today}`
+    );
+    stateContent = stateContent.replace(
+      /(\*\*Last Activity Description:\*\*\s*).*/,
+      `$1${version} milestone completed and archived`
+    );
+    writeStateMd(statePath, stateContent, cwd);
+  }
+
+  // Archive phase directories if requested
+  let phasesArchived = false;
+  if (options.archivePhases) {
+    try {
+      const phaseArchiveDir = path.join(archiveDir, `${version}-phases`);
+      fs.mkdirSync(phaseArchiveDir, { recursive: true });
+
+      const phaseEntries = fs.readdirSync(phasesDir, { withFileTypes: true });
+      const phaseDirNames = phaseEntries.filter(e => e.isDirectory()).map(e => e.name);
+      let archivedCount = 0;
+      for (const dir of phaseDirNames) {
+        if (!isDirInMilestone(dir)) continue;
+        fs.renameSync(path.join(phasesDir, dir), path.join(phaseArchiveDir, dir));
+        archivedCount++;
+      }
+      phasesArchived = archivedCount > 0;
+    } catch {}
+  }
+
+  const result = {
+    version,
+    name: milestoneName,
+    date: today,
+    phases: phaseCount,
+    plans: totalPlans,
+    tasks: totalTasks,
+    accomplishments,
+    archived: {
+      roadmap: fs.existsSync(path.join(archiveDir, `${version}-ROADMAP.md`)),
+      requirements: fs.existsSync(path.join(archiveDir, `${version}-REQUIREMENTS.md`)),
+      audit: fs.existsSync(path.join(archiveDir, `${version}-MILESTONE-AUDIT.md`)),
+      phases: phasesArchived,
+    },
+    milestones_updated: true,
+    state_updated: fs.existsSync(statePath),
+  };
+
+  output(result, raw);
+}
+
+module.exports = {
+  cmdRequirementsMarkComplete,
+  cmdMilestoneComplete,
+};

package/deliver-great-systems/bin/lib/overlap.cjs

@@ -0,0 +1,437 @@
+/**
+ * Overlap — Cross-project overlap detection at repo and file level
+ *
+ * Scans plan files across all active projects to detect which repos and files
+ * are touched by multiple projects simultaneously. Provides both repo-level
+ * and file-level overlap reporting.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { safeReadFile, getProjectFolders, output, error, getProjectDir } = require('./core.cjs');
+const { parseProjectsMd, readProjectState } = require('./projects.cjs');
+const { parseReposMd, resolveFileToRepo } = require('./repos.cjs');
+
+// ─── Severity Order ─────────────────────────────────────────────────────────
+
+const SEVERITY_ORDER = { HIGH: 0, MEDIUM: 1, LOW: 2 };
+
+// ─── Scan Project Plan Files ─────────────────────────────────────────────────
+
+/**
+ * Scan a project's plan files and extract repos and files from XML tags.
+ *
+ * Scans all *-PLAN.md files under .planning/projects/<slug>/phases/ subdirectories.
+ * For each plan file, extracts all <repos> and <files> tags.
+ *
+ * @param {string} cwd - Working directory (product root)
+ * @param {string} slug - Project slug
+ * @returns {Array<{ plan: string, repos: string[], files: string[] }>}
+ */
+function scanProjectPlanFiles(cwd, slug) {
+  const phasesDir = path.join(getProjectDir(cwd, slug), 'phases');
+  const results = [];
+
+  try {
+    const phaseDirs = fs.readdirSync(phasesDir, { withFileTypes: true })
+      .filter(e => e.isDirectory())
+      .map(e => e.name);
+
+    // Exclude archived phase directories
+    const activePhaseDirs = excludeArchivedPhases(
+      phaseDirs.map(d => path.join(phasesDir, d))
+    ).map(d => path.basename(d));
+
+    for (const phaseDir of activePhaseDirs) {
+      const fullPhaseDir = path.join(phasesDir, phaseDir);
+      let files;
+      try {
+        files = fs.readdirSync(fullPhaseDir)
+          .filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md');
+      } catch {
+        continue;
+      }
+
+      for (const planFile of files) {
+        const content = safeReadFile(path.join(fullPhaseDir, planFile));
+        if (!content) continue;
+
+        const repos = new Set();
+        const filesList = new Set();
+
+        // Extract <repos> tags
+        const reposMatches = content.match(/<repos>([^<]*)<\/repos>/g);
+        if (reposMatches) {
+          for (const match of reposMatches) {
+            const inner = match.replace(/<\/?repos>/g, '');
+            inner.split(',').map(n => n.trim()).filter(n => n).forEach(n => repos.add(n));
+          }
+        }
+
+        // Extract <files> tags
+        const filesMatches = content.match(/<files>([^<]*)<\/files>/g);
+        if (filesMatches) {
+          for (const match of filesMatches) {
+            const inner = match.replace(/<\/?files>/g, '');
+            inner.split(/[,\n]/).map(n => n.trim()).filter(n => n).forEach(n => filesList.add(n));
+          }
+        }
+
+        results.push({
+          plan: `${phaseDir}/${planFile}`,
+          repos: Array.from(repos).sort(),
+          files: Array.from(filesList).sort(),
+        });
+      }
+    }
+  } catch {
+    // phases directory doesn't exist or other error
+  }
+
+  return results;
+}
+
+// ─── Exclude Archived Phases ─────────────────────────────────────────────────
+
+/**
+ * Filter out phase directories that are in archived milestone paths.
+ *
+ * Archived paths match patterns like:
+ *   .planning/milestones/v1.0-phases/01-setup
+ *
+ * @param {string[]} phaseDirs - Array of full phase directory paths
+ * @returns {string[]} Filtered array with archived paths removed
+ */
+function excludeArchivedPhases(phaseDirs) {
+  return phaseDirs.filter(dir => {
+    const normalized = dir.replace(/\\/g, '/');
+    return !normalized.includes('/milestones/');
+  });
+}
+
+// ─── Classify Overlap Severity ───────────────────────────────────────────────
+
+/**
+ * Classify the severity of an overlap between projects in a shared repo.
+ *
+ * - HIGH: Two or more projects modify the exact same file(s).
+ * - MEDIUM: No same-file conflicts, but projects share directories.
+ * - LOW: Projects touch different directories in the same repo.
+ *
+ * @param {{ file_conflicts: Array<{ file: string, projects: string[] }>, project_files: Object<string, string[]> }} overlapEntry
+ *   - file_conflicts: files touched by 2+ projects
+ *   - project_files: mapping of project slug -> array of file paths in this repo
+ * @returns {{ severity: string, reason: string }}
+ */
+function classifyOverlapSeverity(overlapEntry) {
+  const { file_conflicts, project_files } = overlapEntry;
+
+  // HIGH: actual file-level conflicts
+  if (file_conflicts && file_conflicts.length > 0) {
+    const fileList = file_conflicts.map(f => f.file).join(', ');
+    return {
+      severity: 'HIGH',
+      reason: `${file_conflicts.length} file(s) modified by multiple projects: ${fileList}`,
+    };
+  }
+
+  // Compute per-project directory sets
+  if (project_files) {
+    const projectDirSets = {};
+    for (const [project, files] of Object.entries(project_files)) {
+      const dirs = new Set();
+      for (const file of files) {
+        dirs.add(path.dirname(file));
+      }
+      projectDirSets[project] = dirs;
+    }
+
+    // Check for directory intersection between any two projects
+    const projects = Object.keys(projectDirSets);
+    const sharedDirs = new Set();
+    for (let i = 0; i < projects.length; i++) {
+      for (let j = i + 1; j < projects.length; j++) {
+        for (const dir of projectDirSets[projects[i]]) {
+          if (projectDirSets[projects[j]].has(dir)) {
+            sharedDirs.add(dir);
+          }
+        }
+      }
+    }
+
+    if (sharedDirs.size > 0) {
+      const dirList = Array.from(sharedDirs).sort().join(', ');
+      return {
+        severity: 'MEDIUM',
+        reason: `Projects share ${sharedDirs.size} directory(ies): ${dirList}`,
+      };
+    }
+  }
+
+  // LOW: different directories in same repo
+  return {
+    severity: 'LOW',
+    reason: 'Projects touch different directories in same repo',
+  };
+}
+
+// ─── Get Active Project Slugs ────────────────────────────────────────────────
+
+/**
+ * Get slugs of all active (non-completed) projects.
+ *
+ * Reads PROJECTS.md to get active project slugs. Falls back to scanning
+ * .planning/ subfolders if PROJECTS.md is missing. Applies ghost project
+ * guard (skips folders without STATE.md).
+ *
+ * @param {string} cwd - Working directory (product root)
+ * @returns {string[]} Array of active project slugs
+ */
+function getActiveProjectSlugs(cwd) {
+  // Try PROJECTS.md first
+  const projectsMd = parseProjectsMd(cwd);
+  if (projectsMd && projectsMd.active) {
+    // Filter to only those with folders on disk and valid STATE.md
+    return projectsMd.active
+      .map(p => p.name)
+      .filter(slug => {
+        const state = readProjectState(cwd, slug);
+        return state !== null;
+      });
+  }
+
+  // Fallback: scan .planning/ subfolders
+  const folders = getProjectFolders(cwd);
+  return folders.filter(slug => {
+    const state = readProjectState(cwd, slug);
+    if (!state) return false;
+    // Exclude completed projects
+    return !state.status.toLowerCase().includes('completed');
+  });
+}
+
+// ─── Build Overlap Matrix ────────────────────────────────────────────────────
+
+/**
+ * Scan all active projects and build the overlap matrix.
+ *
+ * For each active project, scans plan files and extracts repos/files tags.
+ * Builds a repo-to-projects mapping, then filters to repos touched by 2+ projects.
+ * For overlapping repos, identifies specific file-level conflicts.
+ *
+ * @param {string} cwd - Working directory (product root)
+ * @returns {{ overlapping_repos: Array<{ repo: string, projects: string[], file_conflicts: Array<{ file: string, projects: string[] }> }>, warnings: string[] }}
+ */
+function buildOverlapMatrix(cwd) {
+  const warnings = [];
+  const activeSlugs = getActiveProjectSlugs(cwd);
+
+  // Load registered repos for centralized file-to-repo resolution
+  const reposMd = parseReposMd(cwd);
+  const registeredRepos = reposMd ? reposMd.repos : [];
+
+  // repo -> { projects: Set, files: Map<file, Set<project>>, project_files: Map<project, Set<file>> }
+  const repoMap = {};
+
+  for (const slug of activeSlugs) {
+    // Ghost project guard
+    const projectDir = getProjectDir(cwd, slug);
+    if (!fs.existsSync(projectDir)) {
+      warnings.push(`Ghost project: ${slug} (folder missing)`);
+      continue;
+    }
+
+    const planData = scanProjectPlanFiles(cwd, slug);
+    for (const plan of planData) {
+      for (const repo of plan.repos) {
+        if (!repoMap[repo]) {
+          repoMap[repo] = { projects: new Set(), files: {}, project_files: {} };
+        }
+        repoMap[repo].projects.add(slug);
+      }
+      // Map files to repos using plan's <repos> context (repo-relative paths
+      // can't be resolved via prefix-match alone)
+      for (const file of plan.files) {
+        // If plan has explicit repos, use them as context
+        const targetRepos = plan.repos.length > 0 ? plan.repos : [];
+
+        // Fallback: try resolveFileToRepo for legacy product-root-relative paths
+        if (targetRepos.length === 0) {
+          const resolved = resolveFileToRepo(file, registeredRepos);
+          const targetRepo = resolved ? resolved.name : '__unknown__';
+          if (!repoMap[targetRepo]) {
+            repoMap[targetRepo] = { projects: new Set(), files: {}, project_files: {} };
+          }
+          repoMap[targetRepo].projects.add(slug);
+          if (!repoMap[targetRepo].files[file]) {
+            repoMap[targetRepo].files[file] = new Set();
+          }
+          repoMap[targetRepo].files[file].add(slug);
+          if (!repoMap[targetRepo].project_files[slug]) {
+            repoMap[targetRepo].project_files[slug] = [];
+          }
+          if (!repoMap[targetRepo].project_files[slug].includes(file)) {
+            repoMap[targetRepo].project_files[slug].push(file);
+          }
+          continue;
+        }
+
+        for (const repoName of targetRepos) {
+          if (!repoMap[repoName]) {
+            repoMap[repoName] = { projects: new Set(), files: {}, project_files: {} };
+          }
+          repoMap[repoName].projects.add(slug);
+          if (!repoMap[repoName].files[file]) {
+            repoMap[repoName].files[file] = new Set();
+          }
+          repoMap[repoName].files[file].add(slug);
+          if (!repoMap[repoName].project_files[slug]) {
+            repoMap[repoName].project_files[slug] = [];
+          }
+          if (!repoMap[repoName].project_files[slug].includes(file)) {
+            repoMap[repoName].project_files[slug].push(file);
+          }
+        }
+      }
+    }
+  }
+
+  // Also check PROJECTS.md for ghost projects not caught above
+  const projectsMd = parseProjectsMd(cwd);
+  if (projectsMd && projectsMd.active) {
+    for (const p of projectsMd.active) {
+      const projectDir = getProjectDir(cwd, p.name);
+      if (!fs.existsSync(projectDir) && !warnings.some(w => w.includes(p.name))) {
+        warnings.push(`Ghost project: ${p.name} (folder missing)`);
+      }
+    }
+  }
+
+  // Filter to repos touched by 2+ projects
+  const overlapping_repos = [];
+  for (const [repo, data] of Object.entries(repoMap)) {
+    if (repo === '__unknown__') continue;
+    if (data.projects.size < 2) continue;
+
+    // Identify file-level conflicts (files touched by 2+ projects)
+    const file_conflicts = [];
+    for (const [file, projectSet] of Object.entries(data.files)) {
+      if (projectSet.size >= 2) {
+        file_conflicts.push({
+          file,
+          projects: Array.from(projectSet).sort(),
+        });
+      }
+    }
+
+    // Classify severity based on file conflicts and project file locations
+    const severityResult = classifyOverlapSeverity({
+      file_conflicts,
+      project_files: data.project_files,
+    });
+
+    overlapping_repos.push({
+      repo,
+      projects: Array.from(data.projects).sort(),
+      file_conflicts: file_conflicts.sort((a, b) => a.file.localeCompare(b.file)),
+      severity: severityResult.severity,
+      severity_reason: severityResult.reason,
+    });
+  }
+
+  // Sort by severity (HIGH first, then MEDIUM, then LOW), then by repo name within same severity
+  overlapping_repos.sort((a, b) => {
+    const sevDiff = SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity];
+    if (sevDiff !== 0) return sevDiff;
+    return a.repo.localeCompare(b.repo);
+  });
+
+  return { overlapping_repos, warnings };
+}
+
+// ─── Format Overlap Report ───────────────────────────────────────────────────
+
+/**
+ * Format the overlap matrix for human-readable display.
+ *
+ * @param {{ overlapping_repos: Array, warnings: string[] }} matrix
+ * @returns {string} Formatted report text
+ */
+function formatOverlapReport(matrix) {
+  if (!matrix.overlapping_repos || matrix.overlapping_repos.length === 0) {
+    return 'No cross-project overlaps detected.\n\nEach active project touches unique repos.';
+  }
+
+  const lines = [];
+  const count = matrix.overlapping_repos.length;
+  lines.push(`${count} repo(s) touched by multiple active projects\n`);
+
+  // Repo-level table with severity column
+  lines.push('| Repo | Severity | Projects |');
+  lines.push('|------|----------|----------|');
+  for (const overlap of matrix.overlapping_repos) {
+    const severity = overlap.severity || 'LOW';
+    lines.push(`| ${overlap.repo} | ${severity} | ${overlap.projects.join(', ')} |`);
+  }
+
+  // File-level drill-down only for HIGH severity repos
+  const highSeverityRepos = matrix.overlapping_repos.filter(
+    o => o.severity === 'HIGH' && o.file_conflicts && o.file_conflicts.length > 0
+  );
+  if (highSeverityRepos.length > 0) {
+    lines.push('');
+    lines.push('### File-Level Conflicts');
+    for (const overlap of highSeverityRepos) {
+      lines.push('');
+      lines.push(`**${overlap.repo}:**`);
+      for (const conflict of overlap.file_conflicts) {
+        lines.push(`- ${conflict.file} — ${conflict.projects.join(', ')}`);
+      }
+    }
+  }
+
+  lines.push('');
+  lines.push('This is informational — overlapping repos don\'t block work.');
+  lines.push('Coordinate merges manually if projects touch the same files.');
+
+  if (matrix.warnings.length > 0) {
+    lines.push('');
+    lines.push('### Warnings');
+    for (const w of matrix.warnings) {
+      lines.push(`- ${w}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+// ─── CLI Command Function ────────────────────────────────────────────────────
+
+/**
+ * CLI: Run overlap check and output results.
+ *
+ * @param {string} cwd - Working directory (product root)
+ * @param {boolean} raw - Raw output mode
+ */
+function cmdOverlapCheck(cwd, raw) {
+  const matrix = buildOverlapMatrix(cwd);
+
+  if (raw) {
+    output(matrix, raw);
+  } else {
+    const report = formatOverlapReport(matrix);
+    output({ ...matrix, report }, false);
+  }
+}
+
+// ─── Exports ────────────────────────────────────────────────────────────────
+
+module.exports = {
+  scanProjectPlanFiles,
+  buildOverlapMatrix,
+  excludeArchivedPhases,
+  formatOverlapReport,
+  getActiveProjectSlugs,
+  classifyOverlapSeverity,
+  cmdOverlapCheck,
+};