@ktpartners/dgs-platform 2.6.2

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

@@ -0,0 +1,747 @@
+/**
+ * Tests for overlap.cjs — Cross-project overlap detection at repo and file level
+ */
+
+const { describe, it, beforeEach, afterEach } = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const { createTempDir, cleanupDir, writeFile } = require('./test-helpers.cjs');
+
+// Helper to create a minimal project with STATE.md under .planning/projects/<slug>/
+function createProject(cwd, slug, status = 'Ready to execute') {
+  writeFile(cwd, `.planning/projects/${slug}/STATE.md`, `# Project State\n\nPhase: 1\nStatus: ${status}\nProgress: [░░░░░░░░░░] 0%\n`);
+  writeFile(cwd, `.planning/projects/${slug}/PROJECT.md`, `# Project: ${slug}\n`);
+  fs.mkdirSync(path.join(cwd, '.planning', 'projects', slug, 'phases'), { recursive: true });
+}
+
+// Helper to create a plan file with repos and files tags under .planning/projects/<slug>/phases/
+function createPlanFile(cwd, slug, phaseDir, planName, tasks) {
+  let content = `---\nphase: ${phaseDir}\nplan: 01\n---\n\n<tasks>\n`;
+  for (const task of tasks) {
+    content += `\n<task type="auto">\n  <name>${task.name}</name>\n  <files>${(task.files || []).join(', ')}</files>\n`;
+    if (task.repos) {
+      content += `  <repos>${task.repos.join(', ')}</repos>\n`;
+    }
+    content += `  <action>Do something</action>\n  <verify>Check it</verify>\n  <done>Done</done>\n</task>\n`;
+  }
+  content += '\n</tasks>\n';
+  writeFile(cwd, `.planning/projects/${slug}/phases/${phaseDir}/${planName}`, content);
+}
+
+// Helper to create PROJECTS.md
+function createProjectsMd(cwd, projects) {
+  let content = '# Projects\n\n## Active\n\n';
+  content += '| Project | Status | Repos Touched | Current Phase |\n';
+  content += '|---------|--------|---------------|---------------|\n';
+  for (const p of projects.filter(p => p.status !== 'completed')) {
+    content += `| ${p.name} | ${p.status} | ${p.repos || ''} | ${p.phase || '1'} |\n`;
+  }
+  content += '\n## Completed\n\n';
+  content += '| Project | Completed | Duration |\n';
+  content += '|---------|-----------|----------|\n';
+  for (const p of projects.filter(p => p.status === 'completed')) {
+    content += `| ${p.name} | ${p.completed || ''} | |\n`;
+  }
+  writeFile(cwd, '.planning/PROJECTS.md', content);
+}
+
+const {
+  scanProjectPlanFiles,
+  buildOverlapMatrix,
+  excludeArchivedPhases,
+  formatOverlapReport,
+  getActiveProjectSlugs,
+  classifyOverlapSeverity,
+} = require('./overlap.cjs');
+
+// ─── scanProjectPlanFiles ────────────────────────────────────────────────────
+
+describe('scanProjectPlanFiles', () => {
+  let tmpDir;
+  beforeEach(() => { tmpDir = createTempDir(); });
+  afterEach(() => { cleanupDir(tmpDir); });
+
+  it('returns empty array when project has no phases directory', () => {
+    createProject(tmpDir, 'project-a');
+    // Remove phases dir
+    fs.rmSync(path.join(tmpDir, '.planning', 'projects', 'project-a', 'phases'), { recursive: true, force: true });
+    const result = scanProjectPlanFiles(tmpDir, 'project-a');
+    assert.ok(Array.isArray(result));
+    assert.strictEqual(result.length, 0);
+  });
+
+  it('returns repos and files from plan file tags', () => {
+    createProject(tmpDir, 'project-a');
+    createPlanFile(tmpDir, 'project-a', '01-setup', '01-01-PLAN.md', [
+      { name: 'Task 1', files: ['web-app/src/index.js', 'web-app/src/app.js'], repos: ['web-app'] },
+    ]);
+    const result = scanProjectPlanFiles(tmpDir, 'project-a');
+    assert.strictEqual(result.length, 1);
+    assert.deepStrictEqual(result[0].repos, ['web-app']);
+    assert.deepStrictEqual(result[0].files, ['web-app/src/app.js', 'web-app/src/index.js']);
+  });
+
+  it('handles plans with multiple tasks', () => {
+    createProject(tmpDir, 'project-a');
+    createPlanFile(tmpDir, 'project-a', '01-setup', '01-01-PLAN.md', [
+      { name: 'Task 1', files: ['web-app/src/a.js'], repos: ['web-app'] },
+      { name: 'Task 2', files: ['server/src/b.js'], repos: ['server'] },
+    ]);
+    const result = scanProjectPlanFiles(tmpDir, 'project-a');
+    assert.strictEqual(result.length, 1);
+    // Should aggregate repos and files across all tasks in the plan
+    assert.ok(result[0].repos.includes('web-app'));
+    assert.ok(result[0].repos.includes('server'));
+    assert.ok(result[0].files.includes('web-app/src/a.js'));
+    assert.ok(result[0].files.includes('server/src/b.js'));
+  });
+
+  it('skips non-PLAN.md files', () => {
+    createProject(tmpDir, 'project-a');
+    createPlanFile(tmpDir, 'project-a', '01-setup', '01-01-PLAN.md', [
+      { name: 'Task 1', files: ['web-app/src/a.js'], repos: ['web-app'] },
+    ]);
+    // Create a SUMMARY.md file (should be skipped)
+    writeFile(tmpDir, '.planning/projects/project-a/phases/01-setup/01-01-SUMMARY.md', '<repos>server</repos>\n<files>server/x.js</files>');
+    // Create a CONTEXT.md file (should be skipped)
+    writeFile(tmpDir, '.planning/projects/project-a/phases/01-setup/01-CONTEXT.md', '<repos>other</repos>');
+    const result = scanProjectPlanFiles(tmpDir, 'project-a');
+    assert.strictEqual(result.length, 1);
+    // Only web-app from the PLAN.md, not server from SUMMARY.md
+    assert.deepStrictEqual(result[0].repos, ['web-app']);
+  });
+
+  it('handles multiple phases with multiple plans', () => {
+    createProject(tmpDir, 'project-a');
+    createPlanFile(tmpDir, 'project-a', '01-setup', '01-01-PLAN.md', [
+      { name: 'Task 1', files: ['web-app/src/a.js'], repos: ['web-app'] },
+    ]);
+    createPlanFile(tmpDir, 'project-a', '02-build', '02-01-PLAN.md', [
+      { name: 'Task 1', files: ['server/src/b.js'], repos: ['server'] },
+    ]);
+    const result = scanProjectPlanFiles(tmpDir, 'project-a');
+    assert.strictEqual(result.length, 2);
+  });
+
+  it('handles plan files without repos or files tags', () => {
+    createProject(tmpDir, 'project-a');
+    writeFile(tmpDir, '.planning/projects/project-a/phases/01-setup/01-01-PLAN.md',
+      '---\nphase: 01\n---\n\n<tasks>\n<task type="auto">\n  <name>Task 1</name>\n  <action>Do</action>\n</task>\n</tasks>\n'
+    );
+    const result = scanProjectPlanFiles(tmpDir, 'project-a');
+    assert.strictEqual(result.length, 1);
+    assert.deepStrictEqual(result[0].repos, []);
+    assert.deepStrictEqual(result[0].files, []);
+  });
+});
+
+// ─── buildOverlapMatrix ──────────────────────────────────────────────────────
+
+describe('buildOverlapMatrix', () => {
+  let tmpDir;
+  beforeEach(() => { tmpDir = createTempDir(); });
+  afterEach(() => { cleanupDir(tmpDir); });
+
+  it('returns empty overlap when only one project exists', () => {
+    createProject(tmpDir, 'project-a');
+    createProjectsMd(tmpDir, [{ name: 'project-a', status: 'Active' }]);
+    writeFile(tmpDir, '.planning/REPOS.md', '# Repos\n\n| Name | Path |\n|------|------|\n| web-app | ./web-app |\n');
+    createPlanFile(tmpDir, 'project-a', '01-setup', '01-01-PLAN.md', [
+      { name: 'Task 1', files: ['web-app/src/a.js'], repos: ['web-app'] },
+    ]);
+    const result = buildOverlapMatrix(tmpDir);
+    assert.ok(result);
+    assert.strictEqual(result.overlapping_repos.length, 0);
+  });
+
+  it('detects repo-level overlap when two projects touch the same repo', () => {
+    createProject(tmpDir, 'project-a');
+    createProject(tmpDir, 'project-b');
+    createProjectsMd(tmpDir, [
+      { name: 'project-a', status: 'Active' },
+      { name: 'project-b', status: 'Active' },
+    ]);
+    writeFile(tmpDir, '.planning/REPOS.md', '# Repos\n\n| Name | Path |\n|------|------|\n| web-app | ./web-app |\n');
+    createPlanFile(tmpDir, 'project-a', '01-setup', '01-01-PLAN.md', [
+      { name: 'Task 1', files: ['web-app/src/a.js'], repos: ['web-app'] },
+    ]);
+    createPlanFile(tmpDir, 'project-b', '01-setup', '01-01-PLAN.md', [
+      { name: 'Task 1', files: ['web-app/src/b.js'], repos: ['web-app'] },
+    ]);
+    const result = buildOverlapMatrix(tmpDir);
+    assert.strictEqual(result.overlapping_repos.length, 1);
+    assert.strictEqual(result.overlapping_repos[0].repo, 'web-app');
+    assert.ok(result.overlapping_repos[0].projects.includes('project-a'));
+    assert.ok(result.overlapping_repos[0].projects.includes('project-b'));
+  });
+
+  it('returns file-level detail for overlapping repos', () => {
+    createProject(tmpDir, 'project-a');
+    createProject(tmpDir, 'project-b');
+    createProjectsMd(tmpDir, [
+      { name: 'project-a', status: 'Active' },
+      { name: 'project-b', status: 'Active' },
+    ]);
+    writeFile(tmpDir, '.planning/REPOS.md', '# Repos\n\n| Name | Path |\n|------|------|\n| web-app | ./web-app |\n');
+    createPlanFile(tmpDir, 'project-a', '01-setup', '01-01-PLAN.md', [
+      { name: 'Task 1', files: ['web-app/src/shared.js', 'web-app/src/a.js'], repos: ['web-app'] },
+    ]);
+    createPlanFile(tmpDir, 'project-b', '01-setup', '01-01-PLAN.md', [
+      { name: 'Task 1', files: ['web-app/src/shared.js', 'web-app/src/b.js'], repos: ['web-app'] },
+    ]);
+    const result = buildOverlapMatrix(tmpDir);
+    assert.strictEqual(result.overlapping_repos.length, 1);
+    const overlap = result.overlapping_repos[0];
+    // file_conflicts should contain shared.js (touched by both)
+    assert.ok(overlap.file_conflicts);
+    const sharedConflict = overlap.file_conflicts.find(f => f.file === 'web-app/src/shared.js');
+    assert.ok(sharedConflict, 'Expected shared.js to be in file_conflicts');
+    assert.ok(sharedConflict.projects.includes('project-a'));
+    assert.ok(sharedConflict.projects.includes('project-b'));
+  });
+
+  it('skips completed projects', () => {
+    createProject(tmpDir, 'project-a');
+    createProject(tmpDir, 'project-b', 'completed');
+    createProjectsMd(tmpDir, [
+      { name: 'project-a', status: 'Active' },
+      { name: 'project-b', status: 'completed', completed: '2026-01-01' },
+    ]);
+    writeFile(tmpDir, '.planning/REPOS.md', '# Repos\n\n| Name | Path |\n|------|------|\n| web-app | ./web-app |\n');
+    createPlanFile(tmpDir, 'project-a', '01-setup', '01-01-PLAN.md', [
+      { name: 'Task 1', files: ['web-app/src/a.js'], repos: ['web-app'] },
+    ]);
+    createPlanFile(tmpDir, 'project-b', '01-setup', '01-01-PLAN.md', [
+      { name: 'Task 1', files: ['web-app/src/b.js'], repos: ['web-app'] },
+    ]);
+    const result = buildOverlapMatrix(tmpDir);
+    assert.strictEqual(result.overlapping_repos.length, 0);
+  });
+
+  it('ghost project guard: skips projects with missing folders', () => {
+    createProject(tmpDir, 'project-a');
+    createProjectsMd(tmpDir, [
+      { name: 'project-a', status: 'Active' },
+      { name: 'ghost-project', status: 'Active' },
+    ]);
+    writeFile(tmpDir, '.planning/REPOS.md', '# Repos\n\n| Name | Path |\n|------|------|\n| web-app | ./web-app |\n');
+    createPlanFile(tmpDir, 'project-a', '01-setup', '01-01-PLAN.md', [
+      { name: 'Task 1', files: ['web-app/src/a.js'], repos: ['web-app'] },
+    ]);
+    // ghost-project has no folder on disk
+    const result = buildOverlapMatrix(tmpDir);
+    assert.ok(result);
+    assert.ok(result.warnings.some(w => w.includes('ghost-project')));
+  });
+
+  it('no overlap when projects touch different repos', () => {
+    createProject(tmpDir, 'project-a');
+    createProject(tmpDir, 'project-b');
+    createProjectsMd(tmpDir, [
+      { name: 'project-a', status: 'Active' },
+      { name: 'project-b', status: 'Active' },
+    ]);
+    writeFile(tmpDir, '.planning/REPOS.md', '# Repos\n\n| Name | Path |\n|------|------|\n| web-app | ./web-app |\n| server | ./server |\n');
+    createPlanFile(tmpDir, 'project-a', '01-setup', '01-01-PLAN.md', [
+      { name: 'Task 1', files: ['web-app/src/a.js'], repos: ['web-app'] },
+    ]);
+    createPlanFile(tmpDir, 'project-b', '01-setup', '01-01-PLAN.md', [
+      { name: 'Task 1', files: ['server/src/b.js'], repos: ['server'] },
+    ]);
+    const result = buildOverlapMatrix(tmpDir);
+    assert.strictEqual(result.overlapping_repos.length, 0);
+  });
+
+  it('handles three projects overlapping on same repo', () => {
+    createProject(tmpDir, 'project-a');
+    createProject(tmpDir, 'project-b');
+    createProject(tmpDir, 'project-c');
+    createProjectsMd(tmpDir, [
+      { name: 'project-a', status: 'Active' },
+      { name: 'project-b', status: 'Active' },
+      { name: 'project-c', status: 'Active' },
+    ]);
+    writeFile(tmpDir, '.planning/REPOS.md', '# Repos\n\n| Name | Path |\n|------|------|\n| shared | ./shared |\n');
+    createPlanFile(tmpDir, 'project-a', '01-setup', '01-01-PLAN.md', [
+      { name: 'Task 1', files: ['shared/lib.js'], repos: ['shared'] },
+    ]);
+    createPlanFile(tmpDir, 'project-b', '01-setup', '01-01-PLAN.md', [
+      { name: 'Task 1', files: ['shared/utils.js'], repos: ['shared'] },
+    ]);
+    createPlanFile(tmpDir, 'project-c', '01-setup', '01-01-PLAN.md', [
+      { name: 'Task 1', files: ['shared/core.js'], repos: ['shared'] },
+    ]);
+    const result = buildOverlapMatrix(tmpDir);
+    assert.strictEqual(result.overlapping_repos.length, 1);
+    assert.strictEqual(result.overlapping_repos[0].projects.length, 3);
+  });
+
+  it('resolves files to correct repos using resolveFileToRepo (nested prefixes)', () => {
+    createProject(tmpDir, 'project-a');
+    createProject(tmpDir, 'project-b');
+    createProjectsMd(tmpDir, [
+      { name: 'project-a', status: 'Active' },
+      { name: 'project-b', status: 'Active' },
+    ]);
+    writeFile(tmpDir, '.planning/REPOS.md', '# Repos\n\n| Name | Path |\n|------|------|\n| services-api | ./services/api |\n| services-api-gateway | ./services/api-gateway |\n');
+    createPlanFile(tmpDir, 'project-a', '01-setup', '01-01-PLAN.md', [
+      { name: 'Task 1', files: ['services/api/shared.ts', 'services/api-gateway/handler.ts'], repos: ['services-api', 'services-api-gateway'] },
+    ]);
+    createPlanFile(tmpDir, 'project-b', '01-setup', '01-01-PLAN.md', [
+      { name: 'Task 1', files: ['services/api/shared.ts'], repos: ['services-api'] },
+    ]);
+    const result = buildOverlapMatrix(tmpDir);
+    // services-api overlaps (both projects touch it)
+    const apiOverlap = result.overlapping_repos.find(o => o.repo === 'services-api');
+    assert.ok(apiOverlap, 'Expected services-api to overlap');
+    assert.ok(apiOverlap.projects.includes('project-a'));
+    assert.ok(apiOverlap.projects.includes('project-b'));
+    // shared.ts is the file-level conflict under services-api
+    const sharedConflict = apiOverlap.file_conflicts.find(f => f.file === 'services/api/shared.ts');
+    assert.ok(sharedConflict, 'Expected services/api/shared.ts in file_conflicts');
+    // services-api-gateway should NOT overlap (only project-a touches it)
+    const gatewayOverlap = result.overlapping_repos.find(o => o.repo === 'services-api-gateway');
+    assert.strictEqual(gatewayOverlap, undefined, 'services-api-gateway should not overlap');
+  });
+
+  it('maps repo-relative file paths to repos when <repos> tags are present', () => {
+    createProject(tmpDir, 'project-a');
+    createProject(tmpDir, 'project-b');
+    createProjectsMd(tmpDir, [
+      { name: 'project-a', status: 'Active' },
+      { name: 'project-b', status: 'Active' },
+    ]);
+    writeFile(tmpDir, '.planning/REPOS.md', '# Repos\n\n| Name | Path |\n|------|------|\n| web-app | ./web-app |\n');
+    // Repo-relative paths: src/index.ts instead of web-app/src/index.ts
+    createPlanFile(tmpDir, 'project-a', '01-setup', '01-01-PLAN.md', [
+      { name: 'Task 1', files: ['src/index.ts', 'src/app.ts'], repos: ['web-app'] },
+    ]);
+    createPlanFile(tmpDir, 'project-b', '01-setup', '01-01-PLAN.md', [
+      { name: 'Task 1', files: ['src/index.ts', 'src/other.ts'], repos: ['web-app'] },
+    ]);
+    const result = buildOverlapMatrix(tmpDir);
+    assert.strictEqual(result.overlapping_repos.length, 1);
+    assert.strictEqual(result.overlapping_repos[0].repo, 'web-app');
+    assert.ok(result.overlapping_repos[0].projects.includes('project-a'));
+    assert.ok(result.overlapping_repos[0].projects.includes('project-b'));
+    // src/index.ts should appear as a file conflict
+    const indexConflict = result.overlapping_repos[0].file_conflicts.find(f => f.file === 'src/index.ts');
+    assert.ok(indexConflict, 'Expected src/index.ts in file_conflicts');
+    assert.ok(indexConflict.projects.includes('project-a'));
+    assert.ok(indexConflict.projects.includes('project-b'));
+  });
+
+  it('falls back to resolveFileToRepo for legacy paths without <repos> tags', () => {
+    createProject(tmpDir, 'project-a');
+    createProject(tmpDir, 'project-b');
+    createProjectsMd(tmpDir, [
+      { name: 'project-a', status: 'Active' },
+      { name: 'project-b', status: 'Active' },
+    ]);
+    writeFile(tmpDir, '.planning/REPOS.md', '# Repos\n\n| Name | Path |\n|------|------|\n| web-app | ./web-app |\n');
+    // Legacy paths without repos tags — files include repo prefix
+    createPlanFile(tmpDir, 'project-a', '01-setup', '01-01-PLAN.md', [
+      { name: 'Task 1', files: ['web-app/src/shared.js'] },
+    ]);
+    createPlanFile(tmpDir, 'project-b', '01-setup', '01-01-PLAN.md', [
+      { name: 'Task 1', files: ['web-app/src/shared.js'] },
+    ]);
+    const result = buildOverlapMatrix(tmpDir);
+    // Without repos tags, files still get resolved via resolveFileToRepo
+    // Both projects touch web-app/src/shared.js
+    assert.strictEqual(result.overlapping_repos.length, 1);
+    assert.strictEqual(result.overlapping_repos[0].repo, 'web-app');
+  });
+});
+
+// ─── excludeArchivedPhases ───────────────────────────────────────────────────
+
+describe('excludeArchivedPhases', () => {
+  let tmpDir;
+  beforeEach(() => { tmpDir = createTempDir(); });
+  afterEach(() => { cleanupDir(tmpDir); });
+
+  it('keeps current phase directories', () => {
+    const dirs = [
+      path.join(tmpDir, '.planning/projects/project-a/phases/01-setup'),
+      path.join(tmpDir, '.planning/projects/project-a/phases/02-build'),
+    ];
+    const result = excludeArchivedPhases(dirs);
+    assert.strictEqual(result.length, 2);
+  });
+
+  it('excludes directories in milestones archive path', () => {
+    const dirs = [
+      path.join(tmpDir, '.planning/projects/project-a/phases/01-setup'),
+      path.join(tmpDir, '.planning/milestones/v1.0-phases/01-setup'),
+    ];
+    const result = excludeArchivedPhases(dirs);
+    assert.strictEqual(result.length, 1);
+    assert.ok(result[0].includes('project-a'));
+  });
+
+  it('returns empty array for empty input', () => {
+    const result = excludeArchivedPhases([]);
+    assert.strictEqual(result.length, 0);
+  });
+});
+
+// ─── formatOverlapReport ─────────────────────────────────────────────────────
+
+describe('formatOverlapReport', () => {
+  it('returns no-overlap message when matrix is empty', () => {
+    const matrix = { overlapping_repos: [], warnings: [] };
+    const report = formatOverlapReport(matrix);
+    assert.ok(report.includes('No cross-project overlaps'));
+  });
+
+  it('formats repo-level overlap table', () => {
+    const matrix = {
+      overlapping_repos: [
+        { repo: 'web-app', projects: ['project-a', 'project-b'], file_conflicts: [] },
+      ],
+      warnings: [],
+    };
+    const report = formatOverlapReport(matrix);
+    assert.ok(report.includes('web-app'));
+    assert.ok(report.includes('project-a'));
+    assert.ok(report.includes('project-b'));
+  });
+
+  it('includes file-level drill-down for HIGH severity overlapping repos', () => {
+    const matrix = {
+      overlapping_repos: [
+        {
+          repo: 'web-app',
+          projects: ['project-a', 'project-b'],
+          file_conflicts: [
+            { file: 'web-app/src/shared.js', projects: ['project-a', 'project-b'] },
+          ],
+          severity: 'HIGH',
+          severity_reason: '1 file(s) modified by multiple projects',
+        },
+      ],
+      warnings: [],
+    };
+    const report = formatOverlapReport(matrix);
+    assert.ok(report.includes('shared.js'));
+    assert.ok(report.includes('project-a'));
+    assert.ok(report.includes('project-b'));
+  });
+
+  it('handles multiple overlapping repos', () => {
+    const matrix = {
+      overlapping_repos: [
+        { repo: 'web-app', projects: ['project-a', 'project-b'], file_conflicts: [] },
+        { repo: 'server', projects: ['project-a', 'project-c'], file_conflicts: [] },
+      ],
+      warnings: [],
+    };
+    const report = formatOverlapReport(matrix);
+    assert.ok(report.includes('web-app'));
+    assert.ok(report.includes('server'));
+  });
+});
+
+// ─── classifyOverlapSeverity ──────────────────────────────────────────────────
+
+describe('classifyOverlapSeverity', () => {
+  it('returns HIGH when two projects touch the same file', () => {
+    const result = classifyOverlapSeverity({
+      file_conflicts: [
+        { file: 'web-app/src/shared.js', projects: ['project-a', 'project-b'] },
+      ],
+      project_files: {
+        'project-a': ['web-app/src/shared.js'],
+        'project-b': ['web-app/src/shared.js'],
+      },
+    });
+    assert.strictEqual(result.severity, 'HIGH');
+    assert.ok(result.reason.includes('1 file(s)'));
+    assert.ok(result.reason.includes('shared.js'));
+  });
+
+  it('returns MEDIUM when projects share a directory but not files', () => {
+    const result = classifyOverlapSeverity({
+      file_conflicts: [],
+      project_files: {
+        'project-a': ['web-app/src/auth/login.js'],
+        'project-b': ['web-app/src/auth/signup.js'],
+      },
+    });
+    assert.strictEqual(result.severity, 'MEDIUM');
+    assert.ok(result.reason.includes('1 directory'));
+    assert.ok(result.reason.includes('web-app/src/auth'));
+  });
+
+  it('returns LOW when projects touch different directories', () => {
+    const result = classifyOverlapSeverity({
+      file_conflicts: [],
+      project_files: {
+        'project-a': ['web-app/src/auth/login.js'],
+        'project-b': ['web-app/src/billing/invoice.js'],
+      },
+    });
+    assert.strictEqual(result.severity, 'LOW');
+    assert.ok(result.reason.includes('different directories'));
+  });
+
+  it('returns HIGH with multiple file conflicts', () => {
+    const result = classifyOverlapSeverity({
+      file_conflicts: [
+        { file: 'web-app/src/a.js', projects: ['project-a', 'project-b'] },
+        { file: 'web-app/src/b.js', projects: ['project-a', 'project-b'] },
+      ],
+      project_files: {
+        'project-a': ['web-app/src/a.js', 'web-app/src/b.js'],
+        'project-b': ['web-app/src/a.js', 'web-app/src/b.js'],
+      },
+    });
+    assert.strictEqual(result.severity, 'HIGH');
+    assert.ok(result.reason.includes('2 file(s)'));
+  });
+
+  it('returns LOW when no file_conflicts and no project_files', () => {
+    const result = classifyOverlapSeverity({
+      file_conflicts: [],
+      project_files: {},
+    });
+    assert.strictEqual(result.severity, 'LOW');
+  });
+});
+
+// ─── buildOverlapMatrix severity integration ─────────────────────────────────
+
+describe('buildOverlapMatrix severity', () => {
+  let tmpDir;
+  beforeEach(() => { tmpDir = createTempDir(); });
+  afterEach(() => { cleanupDir(tmpDir); });
+
+  it('two projects sharing same file -> severity HIGH', () => {
+    createProject(tmpDir, 'project-a');
+    createProject(tmpDir, 'project-b');
+    createProjectsMd(tmpDir, [
+      { name: 'project-a', status: 'Active' },
+      { name: 'project-b', status: 'Active' },
+    ]);
+    writeFile(tmpDir, '.planning/REPOS.md', '# Repos\n\n| Name | Path |\n|------|------|\n| web-app | ./web-app |\n');
+    createPlanFile(tmpDir, 'project-a', '01-setup', '01-01-PLAN.md', [
+      { name: 'Task 1', files: ['web-app/src/shared.js'], repos: ['web-app'] },
+    ]);
+    createPlanFile(tmpDir, 'project-b', '01-setup', '01-01-PLAN.md', [
+      { name: 'Task 1', files: ['web-app/src/shared.js'], repos: ['web-app'] },
+    ]);
+    const result = buildOverlapMatrix(tmpDir);
+    assert.strictEqual(result.overlapping_repos.length, 1);
+    assert.strictEqual(result.overlapping_repos[0].severity, 'HIGH');
+    assert.ok(result.overlapping_repos[0].severity_reason.includes('file(s)'));
+  });
+
+  it('two projects in same dir, different files -> severity MEDIUM', () => {
+    createProject(tmpDir, 'project-a');
+    createProject(tmpDir, 'project-b');
+    createProjectsMd(tmpDir, [
+      { name: 'project-a', status: 'Active' },
+      { name: 'project-b', status: 'Active' },
+    ]);
+    writeFile(tmpDir, '.planning/REPOS.md', '# Repos\n\n| Name | Path |\n|------|------|\n| web-app | ./web-app |\n');
+    createPlanFile(tmpDir, 'project-a', '01-setup', '01-01-PLAN.md', [
+      { name: 'Task 1', files: ['web-app/src/auth/login.js'], repos: ['web-app'] },
+    ]);
+    createPlanFile(tmpDir, 'project-b', '01-setup', '01-01-PLAN.md', [
+      { name: 'Task 1', files: ['web-app/src/auth/signup.js'], repos: ['web-app'] },
+    ]);
+    const result = buildOverlapMatrix(tmpDir);
+    assert.strictEqual(result.overlapping_repos.length, 1);
+    assert.strictEqual(result.overlapping_repos[0].severity, 'MEDIUM');
+    assert.ok(result.overlapping_repos[0].severity_reason.includes('directory'));
+  });
+
+  it('two projects in different dirs of same repo -> severity LOW', () => {
+    createProject(tmpDir, 'project-a');
+    createProject(tmpDir, 'project-b');
+    createProjectsMd(tmpDir, [
+      { name: 'project-a', status: 'Active' },
+      { name: 'project-b', status: 'Active' },
+    ]);
+    writeFile(tmpDir, '.planning/REPOS.md', '# Repos\n\n| Name | Path |\n|------|------|\n| web-app | ./web-app |\n');
+    createPlanFile(tmpDir, 'project-a', '01-setup', '01-01-PLAN.md', [
+      { name: 'Task 1', files: ['web-app/src/auth/login.js'], repos: ['web-app'] },
+    ]);
+    createPlanFile(tmpDir, 'project-b', '01-setup', '01-01-PLAN.md', [
+      { name: 'Task 1', files: ['web-app/src/billing/invoice.js'], repos: ['web-app'] },
+    ]);
+    const result = buildOverlapMatrix(tmpDir);
+    assert.strictEqual(result.overlapping_repos.length, 1);
+    assert.strictEqual(result.overlapping_repos[0].severity, 'LOW');
+    assert.ok(result.overlapping_repos[0].severity_reason.includes('different directories'));
+  });
+
+  it('existing tests still have severity field present', () => {
+    createProject(tmpDir, 'project-a');
+    createProject(tmpDir, 'project-b');
+    createProjectsMd(tmpDir, [
+      { name: 'project-a', status: 'Active' },
+      { name: 'project-b', status: 'Active' },
+    ]);
+    writeFile(tmpDir, '.planning/REPOS.md', '# Repos\n\n| Name | Path |\n|------|------|\n| web-app | ./web-app |\n');
+    createPlanFile(tmpDir, 'project-a', '01-setup', '01-01-PLAN.md', [
+      { name: 'Task 1', files: ['web-app/src/a.js'], repos: ['web-app'] },
+    ]);
+    createPlanFile(tmpDir, 'project-b', '01-setup', '01-01-PLAN.md', [
+      { name: 'Task 1', files: ['web-app/src/b.js'], repos: ['web-app'] },
+    ]);
+    const result = buildOverlapMatrix(tmpDir);
+    assert.strictEqual(result.overlapping_repos.length, 1);
+    assert.ok(result.overlapping_repos[0].severity, 'severity field should be present');
+    assert.ok(result.overlapping_repos[0].severity_reason, 'severity_reason field should be present');
+  });
+
+  it('multiple overlaps sorted by severity (HIGH before LOW)', () => {
+    createProject(tmpDir, 'project-a');
+    createProject(tmpDir, 'project-b');
+    createProjectsMd(tmpDir, [
+      { name: 'project-a', status: 'Active' },
+      { name: 'project-b', status: 'Active' },
+    ]);
+    writeFile(tmpDir, '.planning/REPOS.md', '# Repos\n\n| Name | Path |\n|------|------|\n| server | ./server |\n| web-app | ./web-app |\n');
+    // Use separate plan files per repo so each plan has a single <repos> tag
+    // This ensures files are mapped precisely to one repo each
+    // project-a: server plan (shared.js) + web-app plan (auth)
+    createPlanFile(tmpDir, 'project-a', '01-setup', '01-01-PLAN.md', [
+      { name: 'Task 1', files: ['src/shared.js'], repos: ['server'] },
+    ]);
+    createPlanFile(tmpDir, 'project-a', '02-build', '02-01-PLAN.md', [
+      { name: 'Task 1', files: ['src/auth/login.js'], repos: ['web-app'] },
+    ]);
+    // project-b: server plan (same shared.js -> HIGH) + web-app plan (billing -> LOW)
+    createPlanFile(tmpDir, 'project-b', '01-setup', '01-01-PLAN.md', [
+      { name: 'Task 1', files: ['src/shared.js'], repos: ['server'] },
+    ]);
+    createPlanFile(tmpDir, 'project-b', '02-build', '02-01-PLAN.md', [
+      { name: 'Task 1', files: ['src/billing/invoice.js'], repos: ['web-app'] },
+    ]);
+    const result = buildOverlapMatrix(tmpDir);
+    assert.strictEqual(result.overlapping_repos.length, 2);
+    // HIGH first
+    assert.strictEqual(result.overlapping_repos[0].severity, 'HIGH');
+    assert.strictEqual(result.overlapping_repos[0].repo, 'server');
+    // LOW second
+    assert.strictEqual(result.overlapping_repos[1].severity, 'LOW');
+    assert.strictEqual(result.overlapping_repos[1].repo, 'web-app');
+  });
+});
+
+// ─── formatOverlapReport severity ────────────────────────────────────────────
+
+describe('formatOverlapReport severity', () => {
+  it('severity column appears in table output', () => {
+    const matrix = {
+      overlapping_repos: [
+        { repo: 'web-app', projects: ['project-a', 'project-b'], file_conflicts: [], severity: 'LOW', severity_reason: 'Different dirs' },
+      ],
+      warnings: [],
+    };
+    const report = formatOverlapReport(matrix);
+    assert.ok(report.includes('| Repo | Severity | Projects |'));
+    assert.ok(report.includes('| web-app | LOW | project-a, project-b |'));
+  });
+
+  it('HIGH overlaps listed before LOW overlaps', () => {
+    const matrix = {
+      overlapping_repos: [
+        { repo: 'server', projects: ['project-a', 'project-b'], file_conflicts: [{ file: 'server/shared.js', projects: ['project-a', 'project-b'] }], severity: 'HIGH', severity_reason: '1 file(s)' },
+        { repo: 'web-app', projects: ['project-a', 'project-b'], file_conflicts: [], severity: 'LOW', severity_reason: 'Different dirs' },
+      ],
+      warnings: [],
+    };
+    const report = formatOverlapReport(matrix);
+    const serverIdx = report.indexOf('server');
+    const webAppIdx = report.indexOf('web-app');
+    assert.ok(serverIdx < webAppIdx, 'HIGH severity (server) should appear before LOW (web-app)');
+  });
+
+  it('file-level drill-down only shown for HIGH severity repos', () => {
+    const matrix = {
+      overlapping_repos: [
+        { repo: 'server', projects: ['project-a', 'project-b'], file_conflicts: [{ file: 'server/shared.js', projects: ['project-a', 'project-b'] }], severity: 'HIGH', severity_reason: '1 file(s)' },
+        { repo: 'web-app', projects: ['project-a', 'project-b'], file_conflicts: [], severity: 'LOW', severity_reason: 'Different dirs' },
+      ],
+      warnings: [],
+    };
+    const report = formatOverlapReport(matrix);
+    assert.ok(report.includes('### File-Level Conflicts'));
+    assert.ok(report.includes('server/shared.js'));
+    // web-app should NOT have file-level section
+  });
+
+  it('no file-level section when no HIGH severity repos', () => {
+    const matrix = {
+      overlapping_repos: [
+        { repo: 'web-app', projects: ['project-a', 'project-b'], file_conflicts: [], severity: 'LOW', severity_reason: 'Different dirs' },
+      ],
+      warnings: [],
+    };
+    const report = formatOverlapReport(matrix);
+    assert.ok(!report.includes('### File-Level Conflicts'));
+  });
+});
+
+// ─── getActiveProjectSlugs ───────────────────────────────────────────────────
+
+describe('getActiveProjectSlugs', () => {
+  let tmpDir;
+  beforeEach(() => { tmpDir = createTempDir(); });
+  afterEach(() => { cleanupDir(tmpDir); });
+
+  it('returns active slugs from PROJECTS.md', () => {
+    createProject(tmpDir, 'project-a');
+    createProject(tmpDir, 'project-b');
+    createProjectsMd(tmpDir, [
+      { name: 'project-a', status: 'Active' },
+      { name: 'project-b', status: 'Active' },
+    ]);
+    const result = getActiveProjectSlugs(tmpDir);
+    assert.ok(result.includes('project-a'));
+    assert.ok(result.includes('project-b'));
+  });
+
+  it('filters out completed projects', () => {
+    createProject(tmpDir, 'project-a');
+    createProject(tmpDir, 'project-b', 'completed');
+    createProjectsMd(tmpDir, [
+      { name: 'project-a', status: 'Active' },
+      { name: 'project-b', status: 'completed', completed: '2026-01-01' },
+    ]);
+    const result = getActiveProjectSlugs(tmpDir);
+    assert.ok(result.includes('project-a'));
+    assert.ok(!result.includes('project-b'));
+  });
+
+  it('falls back to scanning folders when PROJECTS.md missing', () => {
+    createProject(tmpDir, 'project-a');
+    createProject(tmpDir, 'project-b');
+    // No PROJECTS.md — should scan .planning/ subfolders
+    const result = getActiveProjectSlugs(tmpDir);
+    assert.ok(result.includes('project-a'));
+    assert.ok(result.includes('project-b'));
+  });
+
+  it('ghost project guard: skips folders without STATE.md', () => {
+    createProject(tmpDir, 'project-a');
+    // Create a ghost folder without STATE.md
+    fs.mkdirSync(path.join(tmpDir, '.planning', 'projects', 'ghost-project'), { recursive: true });
+    const result = getActiveProjectSlugs(tmpDir);
+    assert.ok(result.includes('project-a'));
+    assert.ok(!result.includes('ghost-project'));
+  });
+
+  it('returns empty array when no projects exist', () => {
+    fs.mkdirSync(path.join(tmpDir, '.planning'), { recursive: true });
+    const result = getActiveProjectSlugs(tmpDir);
+    assert.strictEqual(result.length, 0);
+  });
+});