@ktpartners/dgs-platform 2.6.2

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

@@ -0,0 +1,871 @@
+/**
+ * Tests for projects.cjs — Project lifecycle: subfolder creation, state reading,
+ * PROJECTS.md regeneration, repo tag scanning, project completion
+ */
+
+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, createFixture } = require('./test-helpers.cjs');
+const { getProjectRoot } = require('./core.cjs');
+
+// Helper: create .planning/projects/ directory structure
+function setupPlanning(cwd) {
+  fs.mkdirSync(path.join(cwd, '.planning', 'projects'), { recursive: true });
+}
+
+// Helper: create a project subfolder with STATE.md manually under .planning/projects/<slug>/
+function createProjectManually(cwd, slug, stateContent) {
+  const projDir = path.join(cwd, '.planning', 'projects', slug);
+  fs.mkdirSync(projDir, { recursive: true });
+  if (stateContent) {
+    fs.writeFileSync(path.join(projDir, 'STATE.md'), stateContent);
+  }
+}
+
+// Helper: create plan file with <repos> tags under .planning/projects/<slug>/phases/
+function createPlanFile(cwd, slug, phaseDir, planName, content) {
+  const dir = path.join(cwd, '.planning', 'projects', slug, 'phases', phaseDir);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, planName), content);
+}
+
+const {
+  createProjectSubfolder,
+  readProjectState,
+  scanProjectReposTags,
+  regenerateProjectsMd,
+  completeProject,
+  reactivateProject,
+  parseProjectsMd,
+  checkSlugPrefixCollision,
+} = require('./projects.cjs');
+
+// ─── createProjectSubfolder ─────────────────────────────────────────────────
+
+describe('createProjectSubfolder', () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = createTempDir();
+    setupPlanning(tmpDir);
+  });
+
+  afterEach(() => cleanupDir(tmpDir));
+
+  it('creates project directory at .planning/projects/<slug>/', () => {
+    const result = createProjectSubfolder(tmpDir, 'auth-overhaul', 'Auth Overhaul');
+    assert.strictEqual(result.created, true);
+    assert.ok(fs.existsSync(path.join(tmpDir, '.planning', 'projects', 'auth-overhaul')));
+  });
+
+  it('creates all required subdirectories', () => {
+    createProjectSubfolder(tmpDir, 'auth-overhaul', 'Auth Overhaul');
+    const expectedDirs = ['phases', 'research', 'todos', 'quick', 'debug'];
+    for (const dir of expectedDirs) {
+      assert.ok(
+        fs.existsSync(path.join(tmpDir, '.planning', 'projects', 'auth-overhaul', dir)),
+        `Missing directory: ${dir}`
+      );
+    }
+  });
+
+  it('creates all required files', () => {
+    createProjectSubfolder(tmpDir, 'auth-overhaul', 'Auth Overhaul');
+    const expectedFiles = ['PROJECT.md', 'REQUIREMENTS.md', 'ROADMAP.md', 'STATE.md'];
+    for (const file of expectedFiles) {
+      assert.ok(
+        fs.existsSync(path.join(tmpDir, '.planning', 'projects', 'auth-overhaul', file)),
+        `Missing file: ${file}`
+      );
+    }
+  });
+
+  it('PROJECT.md contains project name in header', () => {
+    createProjectSubfolder(tmpDir, 'auth-overhaul', 'Auth Overhaul');
+    const content = fs.readFileSync(
+      path.join(tmpDir, '.planning', 'projects', 'auth-overhaul', 'PROJECT.md'),
+      'utf-8'
+    );
+    assert.ok(content.includes('# Project: Auth Overhaul'));
+  });
+
+  it('STATE.md contains initial "Not started" status', () => {
+    createProjectSubfolder(tmpDir, 'auth-overhaul', 'Auth Overhaul');
+    const content = fs.readFileSync(
+      path.join(tmpDir, '.planning', 'projects', 'auth-overhaul', 'STATE.md'),
+      'utf-8'
+    );
+    assert.ok(content.includes('Not started'));
+    assert.ok(content.includes('Status: New'));
+  });
+
+  it('returns the project directory path', () => {
+    const result = createProjectSubfolder(tmpDir, 'auth-overhaul', 'Auth Overhaul');
+    assert.ok(result.path.endsWith('auth-overhaul'));
+  });
+
+  it('does NOT overwrite if directory already exists', () => {
+    createProjectSubfolder(tmpDir, 'auth-overhaul', 'Auth Overhaul');
+    const result = createProjectSubfolder(tmpDir, 'auth-overhaul', 'Auth Overhaul');
+    assert.strictEqual(result.created, false);
+    assert.strictEqual(result.reason, 'already_exists');
+  });
+
+  it('handles slug that is already clean', () => {
+    const result = createProjectSubfolder(tmpDir, 'my-cool-project', 'My Cool Project');
+    assert.strictEqual(result.created, true);
+    assert.ok(fs.existsSync(path.join(tmpDir, '.planning', 'projects', 'my-cool-project')));
+  });
+});
+
+// ─── readProjectState ───────────────────────────────────────────────────────
+
+describe('readProjectState', () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = createTempDir();
+    setupPlanning(tmpDir);
+  });
+
+  afterEach(() => cleanupDir(tmpDir));
+
+  it('extracts phase from "Phase: 3 of 7 (Name)" format', () => {
+    createProjectManually(tmpDir, 'proj', '# Project State\n\nPhase: 3 of 7 (Project Lifecycle)\nStatus: In progress\n');
+    const state = readProjectState(tmpDir, 'proj');
+    assert.ok(state.phase.includes('3 of 7'));
+  });
+
+  it('extracts status from "Status: Ready to plan"', () => {
+    createProjectManually(tmpDir, 'proj', '# Project State\n\nPhase: 1\nStatus: Ready to plan\n');
+    const state = readProjectState(tmpDir, 'proj');
+    assert.strictEqual(state.status, 'Ready to plan');
+  });
+
+  it('extracts progress percentage from progress bar', () => {
+    createProjectManually(
+      tmpDir,
+      'proj',
+      '# Project State\n\nPhase: 2\nStatus: Active\nProgress: [████░░░░░░] 40%\n'
+    );
+    const state = readProjectState(tmpDir, 'proj');
+    assert.strictEqual(state.progress, 40);
+  });
+
+  it('returns null for nonexistent project', () => {
+    const state = readProjectState(tmpDir, 'nonexistent');
+    assert.strictEqual(state, null);
+  });
+
+  it('returns defaults for STATE.md with missing fields', () => {
+    createProjectManually(tmpDir, 'proj', '# Project State\n\nSome random content.\n');
+    const state = readProjectState(tmpDir, 'proj');
+    assert.strictEqual(state.phase, 'Unknown');
+    assert.strictEqual(state.status, 'Unknown');
+    assert.strictEqual(state.progress, 0);
+  });
+
+  it('handles "Status: completed" in STATE.md', () => {
+    createProjectManually(tmpDir, 'proj', '# Project State\n\nStatus: completed\nCompleted: 2026-02-20\n');
+    const state = readProjectState(tmpDir, 'proj');
+    assert.strictEqual(state.status, 'completed');
+  });
+
+  it('extracts completed_date from "Completed: YYYY-MM-DD"', () => {
+    createProjectManually(tmpDir, 'proj', '# Project State\n\nStatus: completed\nCompleted: 2026-02-20\n');
+    const state = readProjectState(tmpDir, 'proj');
+    assert.strictEqual(state.completed_date, '2026-02-20');
+  });
+
+  it('handles STATE.md with only a header', () => {
+    createProjectManually(tmpDir, 'proj', '# Project State\n');
+    const state = readProjectState(tmpDir, 'proj');
+    assert.ok(state !== null);
+    assert.strictEqual(state.phase, 'Unknown');
+  });
+});
+
+// ─── scanProjectReposTags ───────────────────────────────────────────────────
+
+describe('scanProjectReposTags', () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = createTempDir();
+    setupPlanning(tmpDir);
+  });
+
+  afterEach(() => cleanupDir(tmpDir));
+
+  it('returns empty array when no phases directory exists', () => {
+    createProjectManually(tmpDir, 'proj', '# State\n');
+    const repos = scanProjectReposTags(tmpDir, 'proj');
+    assert.deepStrictEqual(repos, []);
+  });
+
+  it('returns empty array when no plan files exist', () => {
+    createProjectManually(tmpDir, 'proj', '# State\n');
+    fs.mkdirSync(path.join(tmpDir, '.planning', 'projects', 'proj', 'phases', '01-setup'), {
+      recursive: true,
+    });
+    const repos = scanProjectReposTags(tmpDir, 'proj');
+    assert.deepStrictEqual(repos, []);
+  });
+
+  it('extracts repo names from <repos> tags', () => {
+    createProjectManually(tmpDir, 'proj', '# State\n');
+    createPlanFile(tmpDir, 'proj', '01-setup', '01-01-PLAN.md', '<repos>web-app, server</repos>\n');
+    const repos = scanProjectReposTags(tmpDir, 'proj');
+    assert.deepStrictEqual(repos, ['server', 'web-app']);
+  });
+
+  it('deduplicates across multiple plan files', () => {
+    createProjectManually(tmpDir, 'proj', '# State\n');
+    createPlanFile(tmpDir, 'proj', '01-setup', '01-01-PLAN.md', '<repos>web-app, server</repos>\n');
+    createPlanFile(tmpDir, 'proj', '01-setup', '01-02-PLAN.md', '<repos>server, shared-lib</repos>\n');
+    const repos = scanProjectReposTags(tmpDir, 'proj');
+    assert.deepStrictEqual(repos, ['server', 'shared-lib', 'web-app']);
+  });
+
+  it('sorts results alphabetically', () => {
+    createProjectManually(tmpDir, 'proj', '# State\n');
+    createPlanFile(tmpDir, 'proj', '01-setup', '01-01-PLAN.md', '<repos>zebra, alpha, middle</repos>\n');
+    const repos = scanProjectReposTags(tmpDir, 'proj');
+    assert.deepStrictEqual(repos, ['alpha', 'middle', 'zebra']);
+  });
+
+  it('returns empty array for plans with no <repos> tags', () => {
+    createProjectManually(tmpDir, 'proj', '# State\n');
+    createPlanFile(tmpDir, 'proj', '01-setup', '01-01-PLAN.md', 'No repos tags here.\n');
+    const repos = scanProjectReposTags(tmpDir, 'proj');
+    assert.deepStrictEqual(repos, []);
+  });
+});
+
+// ─── regenerateProjectsMd ───────────────────────────────────────────────────
+
+describe('regenerateProjectsMd', () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = createTempDir();
+    setupPlanning(tmpDir);
+  });
+
+  afterEach(() => cleanupDir(tmpDir));
+
+  it('writes Active table with correct columns', () => {
+    createProjectManually(tmpDir, 'proj-a', '# Project State\n\nPhase: 1\nStatus: Active\nProgress: [██░░░░░░░░] 20%\n');
+    regenerateProjectsMd(tmpDir);
+    const content = fs.readFileSync(path.join(tmpDir, '.planning', 'PROJECTS.md'), 'utf-8');
+    assert.ok(content.includes('| Project | Status | Repos Touched | Current Phase |'));
+  });
+
+  it('writes Completed table with correct columns', () => {
+    createProjectManually(tmpDir, 'proj-a', '# Project State\n\nStatus: Active\n');
+    regenerateProjectsMd(tmpDir);
+    const content = fs.readFileSync(path.join(tmpDir, '.planning', 'PROJECTS.md'), 'utf-8');
+    assert.ok(content.includes('| Project | Completed | Duration |'));
+  });
+
+  it('active projects appear in Active table', () => {
+    createProjectManually(tmpDir, 'proj-a', '# Project State\n\nPhase: 2\nStatus: Active\n');
+    regenerateProjectsMd(tmpDir);
+    const content = fs.readFileSync(path.join(tmpDir, '.planning', 'PROJECTS.md'), 'utf-8');
+    // Find active section and check for project row
+    const activeSection = content.split('## Completed')[0];
+    assert.ok(activeSection.includes('proj-a'));
+  });
+
+  it('completed projects appear in Completed table', () => {
+    createProjectManually(tmpDir, 'proj-done', '# Project State\n\nStatus: completed\nCompleted: 2026-02-20\n');
+    regenerateProjectsMd(tmpDir);
+    const content = fs.readFileSync(path.join(tmpDir, '.planning', 'PROJECTS.md'), 'utf-8');
+    const completedSection = content.split('## Completed')[1];
+    assert.ok(completedSection.includes('proj-done'));
+  });
+
+  it('ghost projects emit warning and are omitted', () => {
+    // Create directory but NO STATE.md
+    fs.mkdirSync(path.join(tmpDir, '.planning', 'projects', 'ghost-project'), { recursive: true });
+    // getProjectFolders requires STATE.md, so ghost won't even be found
+    // But let's also test a project whose STATE.md is unreadable
+    createProjectManually(tmpDir, 'real-project', '# State\n\nStatus: Active\n');
+    const result = regenerateProjectsMd(tmpDir);
+    assert.ok(Array.isArray(result.warnings));
+    // ghost-project won't appear in projects because getProjectFolders filters on STATE.md
+    assert.ok(!result.projects.some(p => p.name === 'ghost-project'));
+  });
+
+  it('returns warnings array', () => {
+    createProjectManually(tmpDir, 'proj-a', '# State\n\nStatus: Active\n');
+    const result = regenerateProjectsMd(tmpDir);
+    assert.ok(Array.isArray(result.warnings));
+  });
+
+  it('empty project list produces tables with headers but no data rows', () => {
+    regenerateProjectsMd(tmpDir);
+    const content = fs.readFileSync(path.join(tmpDir, '.planning', 'PROJECTS.md'), 'utf-8');
+    assert.ok(content.includes('# Projects'));
+    assert.ok(content.includes('## Active'));
+    assert.ok(content.includes('## Completed'));
+  });
+
+  it('starts with # Projects header (v2 marker)', () => {
+    regenerateProjectsMd(tmpDir);
+    const content = fs.readFileSync(path.join(tmpDir, '.planning', 'PROJECTS.md'), 'utf-8');
+    assert.ok(content.startsWith('# Projects'));
+  });
+});
+
+// ─── completeProject ────────────────────────────────────────────────────────
+
+describe('completeProject', () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = createTempDir();
+    setupPlanning(tmpDir);
+  });
+
+  afterEach(() => cleanupDir(tmpDir));
+
+  it('adds "Status: completed" to STATE.md', () => {
+    createProjectManually(tmpDir, 'proj', '# Project State\n\nPhase: 3\nStatus: Active\n');
+    completeProject(tmpDir, 'proj');
+    const content = fs.readFileSync(path.join(tmpDir, '.planning', 'projects', 'proj', 'STATE.md'), 'utf-8');
+    assert.ok(content.includes('Status: completed'));
+  });
+
+  it('adds "Completed: YYYY-MM-DD" to STATE.md', () => {
+    createProjectManually(tmpDir, 'proj', '# Project State\n\nStatus: Active\n');
+    const result = completeProject(tmpDir, 'proj');
+    const content = fs.readFileSync(path.join(tmpDir, '.planning', 'projects', 'proj', 'STATE.md'), 'utf-8');
+    assert.ok(content.includes('Completed:'));
+    assert.ok(/Completed: \d{4}-\d{2}-\d{2}/.test(content));
+  });
+
+  it('returns success result with completion date', () => {
+    createProjectManually(tmpDir, 'proj', '# Project State\n\nStatus: Active\n');
+    const result = completeProject(tmpDir, 'proj');
+    assert.strictEqual(result.completed, true);
+    assert.ok(result.date);
+    assert.ok(/^\d{4}-\d{2}-\d{2}$/.test(result.date));
+  });
+
+  it('returns error if project directory does not exist', () => {
+    const result = completeProject(tmpDir, 'nonexistent');
+    assert.strictEqual(result.completed, false);
+    assert.strictEqual(result.error, 'not_found');
+  });
+
+  it('returns error if STATE.md does not exist', () => {
+    fs.mkdirSync(path.join(tmpDir, '.planning', 'projects', 'no-state'), { recursive: true });
+    const result = completeProject(tmpDir, 'no-state');
+    assert.strictEqual(result.completed, false);
+    assert.strictEqual(result.error, 'no_state_md');
+  });
+
+  it('returns error if project is already completed', () => {
+    createProjectManually(tmpDir, 'proj', '# Project State\n\nStatus: completed\nCompleted: 2026-01-15\n');
+    const result = completeProject(tmpDir, 'proj');
+    assert.strictEqual(result.completed, false);
+    assert.strictEqual(result.error, 'already_completed');
+  });
+});
+
+// ─── reactivateProject ───────────────────────────────────────────────────────
+
+describe('reactivateProject', () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = createTempDir();
+    setupPlanning(tmpDir);
+  });
+
+  afterEach(() => cleanupDir(tmpDir));
+
+  it('changes Status from completed back to In progress', () => {
+    createProjectManually(tmpDir, 'proj', '# Project State\n\nStatus: completed\nCompleted: 2026-01-15\n');
+    reactivateProject(tmpDir, 'proj');
+    const content = fs.readFileSync(path.join(tmpDir, '.planning', 'projects', 'proj', 'STATE.md'), 'utf-8');
+    assert.ok(content.includes('Status: In progress'));
+  });
+
+  it('removes Completed date line', () => {
+    createProjectManually(tmpDir, 'proj', '# Project State\n\nStatus: completed\nCompleted: 2026-01-15\n');
+    reactivateProject(tmpDir, 'proj');
+    const content = fs.readFileSync(path.join(tmpDir, '.planning', 'projects', 'proj', 'STATE.md'), 'utf-8');
+    assert.ok(!content.includes('Completed:'));
+  });
+
+  it('returns success result', () => {
+    createProjectManually(tmpDir, 'proj', '# Project State\n\nStatus: completed\nCompleted: 2026-01-15\n');
+    const result = reactivateProject(tmpDir, 'proj');
+    assert.strictEqual(result.reactivated, true);
+  });
+
+  it('returns error if project directory does not exist', () => {
+    const result = reactivateProject(tmpDir, 'nonexistent');
+    assert.strictEqual(result.reactivated, false);
+    assert.strictEqual(result.error, 'not_found');
+  });
+
+  it('returns error if STATE.md does not exist', () => {
+    fs.mkdirSync(path.join(tmpDir, '.planning', 'projects', 'no-state'), { recursive: true });
+    const result = reactivateProject(tmpDir, 'no-state');
+    assert.strictEqual(result.reactivated, false);
+    assert.strictEqual(result.error, 'no_state_md');
+  });
+
+  it('returns error if project is not completed', () => {
+    createProjectManually(tmpDir, 'proj', '# Project State\n\nStatus: Active\n');
+    const result = reactivateProject(tmpDir, 'proj');
+    assert.strictEqual(result.reactivated, false);
+    assert.strictEqual(result.error, 'not_completed');
+  });
+
+  it('preserves existing STATE.md content beyond status fields', () => {
+    const original = '# Project State\n\n## Current Position\n\nPhase: 5 of 7\nStatus: completed\nCompleted: 2026-01-15\n\n## Decisions\n\n- Some important decision\n';
+    createProjectManually(tmpDir, 'proj', original);
+    reactivateProject(tmpDir, 'proj');
+    const content = fs.readFileSync(path.join(tmpDir, '.planning', 'projects', 'proj', 'STATE.md'), 'utf-8');
+    assert.ok(content.includes('# Project State'));
+    assert.ok(content.includes('## Decisions'));
+    assert.ok(content.includes('Some important decision'));
+    assert.ok(content.includes('Status: In progress'));
+  });
+
+  it('does not modify STATE.md when project is not completed', () => {
+    const original = '# Project State\n\nStatus: Active\n';
+    createProjectManually(tmpDir, 'proj', original);
+    reactivateProject(tmpDir, 'proj');
+    const content = fs.readFileSync(path.join(tmpDir, '.planning', 'projects', 'proj', 'STATE.md'), 'utf-8');
+    assert.strictEqual(content, original);
+  });
+
+  it('handles case-insensitive Status: Completed', () => {
+    createProjectManually(tmpDir, 'proj', '# Project State\n\nStatus: Completed\nCompleted: 2026-01-15\n');
+    const result = reactivateProject(tmpDir, 'proj');
+    assert.strictEqual(result.reactivated, true);
+    const content = fs.readFileSync(path.join(tmpDir, '.planning', 'projects', 'proj', 'STATE.md'), 'utf-8');
+    assert.ok(content.includes('Status: In progress'));
+  });
+});
+
+// ─── parseProjectsMd ────────────────────────────────────────────────────────
+
+describe('parseProjectsMd', () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = createTempDir();
+    setupPlanning(tmpDir);
+  });
+
+  afterEach(() => cleanupDir(tmpDir));
+
+  it('parses Active table rows into structured objects', () => {
+    const content = `# Projects
+
+## Active
+
+| Project | Status | Repos Touched | Current Phase |
+|---------|--------|---------------|---------------|
+| auth-overhaul | Active | web-app, server | Phase 2 |
+
+## Completed
+
+| Project | Completed | Duration |
+|---------|-----------|----------|
+`;
+    fs.writeFileSync(path.join(tmpDir, '.planning', 'PROJECTS.md'), content);
+    const result = parseProjectsMd(tmpDir);
+    assert.strictEqual(result.active.length, 1);
+    assert.strictEqual(result.active[0].name, 'auth-overhaul');
+    assert.strictEqual(result.active[0].status, 'Active');
+    assert.strictEqual(result.active[0].repos_touched, 'web-app, server');
+    assert.strictEqual(result.active[0].current_phase, 'Phase 2');
+  });
+
+  it('parses Completed table rows into structured objects', () => {
+    const content = `# Projects
+
+## Active
+
+| Project | Status | Repos Touched | Current Phase |
+|---------|--------|---------------|---------------|
+
+## Completed
+
+| Project | Completed | Duration |
+|---------|-----------|----------|
+| old-project | 2026-01-15 | 30 days |
+`;
+    fs.writeFileSync(path.join(tmpDir, '.planning', 'PROJECTS.md'), content);
+    const result = parseProjectsMd(tmpDir);
+    assert.strictEqual(result.completed.length, 1);
+    assert.strictEqual(result.completed[0].name, 'old-project');
+    assert.strictEqual(result.completed[0].completed, '2026-01-15');
+    assert.strictEqual(result.completed[0].duration, '30 days');
+  });
+
+  it('returns null if file does not exist', () => {
+    const result = parseProjectsMd(tmpDir);
+    assert.strictEqual(result, null);
+  });
+
+  it('returns null if file does not start with # Projects', () => {
+    fs.writeFileSync(path.join(tmpDir, '.planning', 'PROJECTS.md'), '# Not Projects\n');
+    const result = parseProjectsMd(tmpDir);
+    assert.strictEqual(result, null);
+  });
+
+  it('handles empty tables (headers only)', () => {
+    const content = `# Projects
+
+## Active
+
+| Project | Status | Repos Touched | Current Phase |
+|---------|--------|---------------|---------------|
+
+## Completed
+
+| Project | Completed | Duration |
+|---------|-----------|----------|
+`;
+    fs.writeFileSync(path.join(tmpDir, '.planning', 'PROJECTS.md'), content);
+    const result = parseProjectsMd(tmpDir);
+    assert.strictEqual(result.active.length, 0);
+    assert.strictEqual(result.completed.length, 0);
+  });
+});
+
+// ─── Edge Cases and Integration ─────────────────────────────────────────────
+
+describe('createProjectSubfolder edge cases', () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = createTempDir();
+    setupPlanning(tmpDir);
+  });
+
+  afterEach(() => cleanupDir(tmpDir));
+
+  it('includes initial_repos in PROJECT.md when provided', () => {
+    createProjectSubfolder(tmpDir, 'my-proj', 'My Project', {
+      initial_repos: 'web-app, server, shared-lib',
+    });
+    const content = fs.readFileSync(
+      path.join(tmpDir, '.planning', 'projects', 'my-proj', 'PROJECT.md'),
+      'utf-8'
+    );
+    assert.ok(content.includes('## Initial Repos'));
+    assert.ok(content.includes('web-app, server, shared-lib'));
+  });
+
+  it('STATE.md has 0% progress bar initially', () => {
+    createProjectSubfolder(tmpDir, 'my-proj', 'My Project');
+    const content = fs.readFileSync(
+      path.join(tmpDir, '.planning', 'projects', 'my-proj', 'STATE.md'),
+      'utf-8'
+    );
+    assert.ok(content.includes('0%'));
+  });
+});
+
+describe('readProjectState edge cases', () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = createTempDir();
+    setupPlanning(tmpDir);
+  });
+
+  afterEach(() => cleanupDir(tmpDir));
+
+  it('extracts multi-part Phase field', () => {
+    createProjectManually(
+      tmpDir,
+      'proj',
+      '# State\n\nPhase: 3 of 7 (Project Lifecycle)\nStatus: In progress\n'
+    );
+    const state = readProjectState(tmpDir, 'proj');
+    assert.strictEqual(state.phase, '3 of 7 (Project Lifecycle)');
+  });
+
+  it('returns progress 0 when no progress bar present', () => {
+    createProjectManually(tmpDir, 'proj', '# State\n\nPhase: 1\nStatus: Active\n');
+    const state = readProjectState(tmpDir, 'proj');
+    assert.strictEqual(state.progress, 0);
+  });
+
+  it('returns null completed_date when not present', () => {
+    createProjectManually(tmpDir, 'proj', '# State\n\nStatus: Active\n');
+    const state = readProjectState(tmpDir, 'proj');
+    assert.strictEqual(state.completed_date, null);
+  });
+});
+
+describe('scanProjectReposTags edge cases', () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = createTempDir();
+    setupPlanning(tmpDir);
+  });
+
+  afterEach(() => cleanupDir(tmpDir));
+
+  it('handles multiple <repos> tags in one plan file', () => {
+    createProjectManually(tmpDir, 'proj', '# State\n');
+    createPlanFile(
+      tmpDir,
+      'proj',
+      '01-setup',
+      '01-01-PLAN.md',
+      '<repos>web-app</repos>\n\nSome content\n\n<repos>server, shared-lib</repos>\n'
+    );
+    const repos = scanProjectReposTags(tmpDir, 'proj');
+    assert.deepStrictEqual(repos, ['server', 'shared-lib', 'web-app']);
+  });
+
+  it('handles whitespace in repo names', () => {
+    createProjectManually(tmpDir, 'proj', '# State\n');
+    createPlanFile(
+      tmpDir,
+      'proj',
+      '01-setup',
+      '01-01-PLAN.md',
+      '<repos>  web-app ,  server  </repos>\n'
+    );
+    const repos = scanProjectReposTags(tmpDir, 'proj');
+    assert.deepStrictEqual(repos, ['server', 'web-app']);
+  });
+});
+
+describe('regenerateProjectsMd edge cases', () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = createTempDir();
+    setupPlanning(tmpDir);
+  });
+
+  afterEach(() => cleanupDir(tmpDir));
+
+  it('handles mix of active and completed projects', () => {
+    createProjectManually(tmpDir, 'active-proj', '# State\n\nPhase: 2\nStatus: In progress\n');
+    createProjectManually(tmpDir, 'done-proj', '# State\n\nStatus: completed\nCompleted: 2026-01-15\n');
+    const result = regenerateProjectsMd(tmpDir);
+    assert.strictEqual(result.projects.length, 2);
+    const content = fs.readFileSync(path.join(tmpDir, '.planning', 'PROJECTS.md'), 'utf-8');
+    const activeSection = content.split('## Completed')[0];
+    const completedSection = content.split('## Completed')[1];
+    assert.ok(activeSection.includes('active-proj'));
+    assert.ok(completedSection.includes('done-proj'));
+  });
+
+  it('handles project with no phases directory', () => {
+    createProjectManually(tmpDir, 'proj', '# State\n\nStatus: Active\n');
+    // No phases dir created
+    const result = regenerateProjectsMd(tmpDir);
+    assert.strictEqual(result.projects.length, 1);
+    assert.strictEqual(result.projects[0].repos_touched, '');
+  });
+
+  it('includes repos touched in Active table', () => {
+    createProjectManually(tmpDir, 'proj', '# State\n\nStatus: Active\nPhase: 1\n');
+    createPlanFile(tmpDir, 'proj', '01-setup', '01-01-PLAN.md', '<repos>web-app, server</repos>\n');
+    regenerateProjectsMd(tmpDir);
+    const content = fs.readFileSync(path.join(tmpDir, '.planning', 'PROJECTS.md'), 'utf-8');
+    assert.ok(content.includes('server, web-app'));
+  });
+});
+
+describe('completeProject edge cases', () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = createTempDir();
+    setupPlanning(tmpDir);
+  });
+
+  afterEach(() => cleanupDir(tmpDir));
+
+  it('preserves existing STATE.md content', () => {
+    const original = '# Project State\n\n## Current Position\n\nPhase: 5 of 7\nStatus: In progress\nProgress: [████████░░] 80%\n\n## Decisions\n\n- Some important decision\n';
+    createProjectManually(tmpDir, 'proj', original);
+    completeProject(tmpDir, 'proj');
+    const content = fs.readFileSync(path.join(tmpDir, '.planning', 'projects', 'proj', 'STATE.md'), 'utf-8');
+    assert.ok(content.includes('# Project State'));
+    assert.ok(content.includes('## Decisions'));
+    assert.ok(content.includes('Some important decision'));
+    assert.ok(content.includes('Status: completed'));
+  });
+
+  it('overwrites existing Status line instead of adding duplicate', () => {
+    createProjectManually(tmpDir, 'proj', '# State\n\nStatus: Active\n');
+    completeProject(tmpDir, 'proj');
+    const content = fs.readFileSync(path.join(tmpDir, '.planning', 'projects', 'proj', 'STATE.md'), 'utf-8');
+    const statusCount = (content.match(/Status:/g) || []).length;
+    assert.strictEqual(statusCount, 1);
+  });
+
+  it('does not modify STATE.md when project is already completed', () => {
+    const original = '# Project State\n\nStatus: completed\nCompleted: 2026-01-15\n';
+    createProjectManually(tmpDir, 'proj', original);
+    completeProject(tmpDir, 'proj');
+    const content = fs.readFileSync(path.join(tmpDir, '.planning', 'projects', 'proj', 'STATE.md'), 'utf-8');
+    assert.strictEqual(content, original);
+  });
+
+  it('detects already completed status case-insensitively', () => {
+    createProjectManually(tmpDir, 'proj', '# Project State\n\nStatus: Completed\n');
+    const result = completeProject(tmpDir, 'proj');
+    assert.strictEqual(result.completed, false);
+    assert.strictEqual(result.error, 'already_completed');
+  });
+});
+
+describe('roundtrip integration', () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = createTempDir();
+    setupPlanning(tmpDir);
+  });
+
+  afterEach(() => cleanupDir(tmpDir));
+
+  it('create -> read -> regenerate -> parse produces consistent data', () => {
+    // Create
+    createProjectSubfolder(tmpDir, 'test-project', 'Test Project');
+
+    // Read
+    const state = readProjectState(tmpDir, 'test-project');
+    assert.ok(state);
+    assert.strictEqual(state.status, 'New');
+    assert.strictEqual(state.progress, 0);
+
+    // Regenerate
+    const regenResult = regenerateProjectsMd(tmpDir);
+    assert.strictEqual(regenResult.projects.length, 1);
+    assert.strictEqual(regenResult.projects[0].name, 'test-project');
+
+    // Parse
+    const parsed = parseProjectsMd(tmpDir);
+    assert.ok(parsed);
+    assert.strictEqual(parsed.active.length, 1);
+    assert.strictEqual(parsed.active[0].name, 'test-project');
+    assert.strictEqual(parsed.active[0].status, 'New');
+  });
+
+  it('create -> complete -> regenerate -> parse shows completed project', () => {
+    createProjectSubfolder(tmpDir, 'done-proj', 'Done Project');
+    completeProject(tmpDir, 'done-proj');
+    regenerateProjectsMd(tmpDir);
+    const parsed = parseProjectsMd(tmpDir);
+    assert.strictEqual(parsed.active.length, 0);
+    assert.strictEqual(parsed.completed.length, 1);
+    assert.strictEqual(parsed.completed[0].name, 'done-proj');
+  });
+});
+
+// ─── checkSlugPrefixCollision ─────────────────────────────────────────────────
+
+describe('checkSlugPrefixCollision', () => {
+  it('detects existing slug as prefix of new slug', () => {
+    const result = checkSlugPrefixCollision('api-v2-hotfix', ['api-v2', 'dashboard']);
+    assert.strictEqual(result.collision, true);
+    assert.strictEqual(result.collidingSlug, 'api-v2');
+  });
+
+  it('detects new slug as prefix of existing slug', () => {
+    const result = checkSlugPrefixCollision('api-v2', ['api-v2-hotfix', 'dashboard']);
+    assert.strictEqual(result.collision, true);
+    assert.strictEqual(result.collidingSlug, 'api-v2-hotfix');
+  });
+
+  it('no collision when slugs are unrelated', () => {
+    const result = checkSlugPrefixCollision('billing', ['api-v2', 'dashboard']);
+    assert.strictEqual(result.collision, false);
+    assert.strictEqual(result.collidingSlug, undefined);
+  });
+
+  it('detects short prefix collision', () => {
+    const result = checkSlugPrefixCollision('api', ['api-v2']);
+    assert.strictEqual(result.collision, true);
+    assert.strictEqual(result.collidingSlug, 'api-v2');
+  });
+
+  it('no collision with empty existing slugs', () => {
+    const result = checkSlugPrefixCollision('new-project', []);
+    assert.strictEqual(result.collision, false);
+  });
+
+  it('exact match is not flagged (handled by createProjectSubfolder)', () => {
+    const result = checkSlugPrefixCollision('api-v2', ['api-v2', 'dashboard']);
+    assert.strictEqual(result.collision, false);
+  });
+});
+
+// ─── cmdProjectsSwitch Guards ─────────────────────────────────────────────────
+
+describe('cmdProjectsSwitch guards', () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = createTempDir();
+    setupPlanning(tmpDir);
+  });
+
+  afterEach(() => cleanupDir(tmpDir));
+
+  it('readProjectState detects completed status for cmdProjectsSwitch guard', () => {
+    createProjectManually(tmpDir, 'completed-proj', '# Project State\n\nStatus: completed\nCompleted: 2026-02-20\n');
+    const state = readProjectState(tmpDir, 'completed-proj');
+    assert.ok(state);
+    assert.ok(state.status.toLowerCase().includes('completed'));
+  });
+
+  it('readProjectState detects active status does not trigger guard', () => {
+    createProjectManually(tmpDir, 'active-proj', '# Project State\n\nStatus: Active\n');
+    const state = readProjectState(tmpDir, 'active-proj');
+    assert.ok(state);
+    assert.ok(!state.status.toLowerCase().includes('completed'));
+  });
+
+  it('completeProject sets status that triggers the switch guard', () => {
+    createProjectManually(tmpDir, 'proj', '# Project State\n\nStatus: Active\n');
+    completeProject(tmpDir, 'proj');
+    const state = readProjectState(tmpDir, 'proj');
+    assert.ok(state);
+    assert.ok(state.status.toLowerCase().includes('completed'));
+  });
+
+  it('getProjectRoot throws PROJECT_COMPLETED for completed project (integration)', () => {
+    // Set up a v2 fixture with completed project as current_project
+    const fixture = createFixture({
+      '.planning/config.json': JSON.stringify({ current_project: 'finished-proj' }),
+      '.planning/PROJECTS.md': '# Projects\n\n## Active\n\n| Project | Status | Repos Touched | Current Phase |\n|---------|--------|---------------|---------------|\n\n## Completed\n\n| Project | Completed | Duration |\n|---------|-----------|----------|\n| finished-proj | 2026-02-20 | |\n',
+      '.planning/REPOS.md': '# Repos\n\n| Name | Path |\n',
+      '.planning/projects/finished-proj/STATE.md': '# Project State\n\nStatus: completed\nCompleted: 2026-02-20\n',
+    });
+
+    try {
+      assert.throws(
+        () => getProjectRoot(fixture.cwd),
+        (err) => err.message.includes('PROJECT_COMPLETED')
+      );
+    } finally {
+      fixture.cleanup();
+    }
+  });
+});