@ktpartners/dgs-platform 2.9.0 → 3.0.4

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

@@ -0,0 +1,420 @@
+/**
+ * Tests for phase.cjs::cmdPhaseFinalize and commands.cjs::cmdPlanFinalize.
+ *
+ * Atomic "update tracking files + commit" behavior in a real temp git repo.
+ * Uses Node.js built-in test runner (node:test) and assert (node:assert).
+ */
+
+const { describe, it, beforeEach, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const { createTempProject } = require('./test-helpers.cjs');
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * Capture stdout output from CLI commands that call output() (process.stdout.write
+ * + process.exit). Mocks both so multiple CLI invocations can run in sequence.
+ * Returns { stdout, exitCode, json }.
+ */
+function captureStdout(fn) {
+  const chunks = [];
+  const origWrite = process.stdout.write.bind(process.stdout);
+  const origExit = process.exit;
+  let exitCode = null;
+  process.stdout.write = (data) => { chunks.push(String(data)); return true; };
+  process.exit = (code) => {
+    exitCode = code == null ? 0 : code;
+    throw new Error('__EXIT__');
+  };
+  try {
+    fn();
+  } catch (e) {
+    if (e && e.message !== '__EXIT__') throw e;
+  } finally {
+    process.stdout.write = origWrite;
+    process.exit = origExit;
+  }
+  const stdout = chunks.join('');
+  let json = null;
+  try { json = JSON.parse(stdout); } catch { /* not JSON */ }
+  return { stdout, exitCode, json };
+}
+
+function gitLog(cwd) {
+  return execSync('git log --oneline', { cwd, encoding: 'utf-8' })
+    .trim().split('\n').filter(Boolean);
+}
+
+function gitShowFiles(cwd, ref) {
+  return execSync(`git show --name-only --format= ${ref}`, { cwd, encoding: 'utf-8' })
+    .trim().split('\n').filter(Boolean);
+}
+
+function gitLastMessage(cwd) {
+  return execSync('git log -1 --format=%s', { cwd, encoding: 'utf-8' }).trim();
+}
+
+/**
+ * Write a rich fixture atop createTempProject for Phase 01 finalize tests.
+ * Returns { cwd, cleanup } from createTempProject after adding ROADMAP, STATE,
+ * REQUIREMENTS, phase dir, and VERIFICATION.md — all committed to a clean tree.
+ */
+function makePhaseFinalizeFixture() {
+  const fixture = createTempProject({ withGit: false, withPhases: false, withConfig: {} });
+
+  // Remove v2 markers so this is treated as a v1/root-layout project (phases at root)
+  fs.unlinkSync(path.join(fixture.cwd, 'PROJECTS.md'));
+  fs.unlinkSync(path.join(fixture.cwd, 'REPOS.md'));
+
+  // Richer ROADMAP.md with parseable Phase 01 entry + progress table row
+  fs.writeFileSync(path.join(fixture.cwd, 'ROADMAP.md'),
+    '# Roadmap\n\n' +
+    '## Progress\n\n' +
+    '| Phase | Plans | Status | Date |\n' +
+    '|-------|-------|--------|------|\n' +
+    '| 01. Test | 1/1 | In Progress |  |\n\n' +
+    '## Phases\n\n' +
+    '- [ ] **Phase 01: Test** - desc\n\n' +
+    '## Phase 01: Test Phase\n\n' +
+    '**Plans:** 1/1 plans executed\n' +
+    '**Requirements:** [REQ-01]\n'
+  );
+
+  // STATE.md with all the fields cmdPhaseComplete regex-replaces
+  fs.writeFileSync(path.join(fixture.cwd, 'STATE.md'),
+    '# State\n\n' +
+    '**Current Phase:** 01\n' +
+    '**Current Phase Name:** Test Phase\n' +
+    '**Status:** In Progress\n' +
+    '**Current Plan:** 01-01\n' +
+    '**Last Activity:** 2025-01-01\n' +
+    '**Last Activity Description:** Working\n'
+  );
+
+  // REQUIREMENTS.md
+  fs.writeFileSync(path.join(fixture.cwd, 'REQUIREMENTS.md'),
+    '# Requirements\n\n' +
+    '- [ ] **REQ-01** Do thing\n\n' +
+    '| ID | Phase | Status |\n' +
+    '|----|-------|--------|\n' +
+    '| REQ-01 | Phase 01 | Pending |\n'
+  );
+
+  // Phase dir + PLAN + SUMMARY so findPhaseInternal finds it
+  fs.mkdirSync(path.join(fixture.cwd, 'phases/01-test-phase'), { recursive: true });
+  fs.writeFileSync(path.join(fixture.cwd, 'phases/01-test-phase/01-01-PLAN.md'), '# Plan\n');
+  fs.writeFileSync(path.join(fixture.cwd, 'phases/01-test-phase/01-01-SUMMARY.md'), '# Summary\n');
+
+  // Commit fixture additions so finalize produces a clean new commit
+  execSync('git add .', { cwd: fixture.cwd, stdio: 'pipe' });
+  execSync('git commit -m "fixture setup"', { cwd: fixture.cwd, stdio: 'pipe' });
+
+  // Write VERIFICATION.md AFTER the commit — this mirrors the real workflow where
+  // the verifier writes it just before finalize. It's untracked, so finalize must
+  // stage + commit it.
+  fs.writeFileSync(path.join(fixture.cwd, 'phases/01-test-phase/01-VERIFICATION.md'), '# Verification\n\nPassed.\n');
+
+  return fixture;
+}
+
+/**
+ * Write a rich fixture for Plan 01 finalize tests. Similar to above but the
+ * PLAN.md has real frontmatter with plan_name + requirements.
+ */
+function makePlanFinalizeFixture() {
+  const fixture = createTempProject({ withGit: false, withPhases: false, withConfig: {} });
+
+  // Remove v2 markers so this is treated as a v1/root-layout project (phases at root)
+  fs.unlinkSync(path.join(fixture.cwd, 'PROJECTS.md'));
+  fs.unlinkSync(path.join(fixture.cwd, 'REPOS.md'));
+
+  // ROADMAP.md with Phase 04 (same structure pattern)
+  fs.writeFileSync(path.join(fixture.cwd, 'ROADMAP.md'),
+    '# Roadmap\n\n' +
+    '## Progress\n\n' +
+    '| Phase | Plans | Status | Date |\n' +
+    '|-------|-------|--------|------|\n' +
+    '| 04. Auth | 0/1 | Planned |  |\n\n' +
+    '## Phases\n\n' +
+    '- [ ] **Phase 04: Auth** - auth layer\n\n' +
+    '## Phase 04: Auth\n\n' +
+    '**Plans:** 0/1 plans executed\n' +
+    '**Requirements:** [AUTH-01]\n'
+  );
+
+  fs.writeFileSync(path.join(fixture.cwd, 'STATE.md'),
+    '# State\n\n' +
+    '**Current Phase:** 04\n' +
+    '**Current Plan:** 04-01\n' +
+    'Progress: [░░░░░░░░░░] 0%\n'
+  );
+
+  fs.writeFileSync(path.join(fixture.cwd, 'REQUIREMENTS.md'),
+    '# Requirements\n\n' +
+    '- [ ] **AUTH-01** Login\n\n' +
+    '| ID | Phase | Status |\n' +
+    '|----|-------|--------|\n' +
+    '| AUTH-01 | Phase 04 | Pending |\n'
+  );
+
+  // Phase dir + PLAN.md (committed before finalize runs)
+  fs.mkdirSync(path.join(fixture.cwd, 'phases/04-auth'), { recursive: true });
+  fs.writeFileSync(path.join(fixture.cwd, 'phases/04-auth/04-01-PLAN.md'),
+    '---\n' +
+    'phase: 04-auth\n' +
+    'plan: 01\n' +
+    'plan_name: auth-login\n' +
+    'requirements: [AUTH-01]\n' +
+    '---\n' +
+    '# Plan\n'
+  );
+
+  execSync('git add .', { cwd: fixture.cwd, stdio: 'pipe' });
+  execSync('git commit -m "fixture setup"', { cwd: fixture.cwd, stdio: 'pipe' });
+
+  // SUMMARY.md written AFTER the initial commit — matches real workflow where
+  // the executor produces SUMMARY.md as its final artifact before finalize runs.
+  // PLAN.md also gets touched so it's re-staged (the real workflow updates it
+  // with executed_by / completion metadata during the session).
+  fs.writeFileSync(path.join(fixture.cwd, 'phases/04-auth/04-01-SUMMARY.md'), '# Summary\n');
+  fs.appendFileSync(path.join(fixture.cwd, 'phases/04-auth/04-01-PLAN.md'), '\nexecuted.\n');
+
+  return fixture;
+}
+
+// ─── Tests ────────────────────────────────────────────────────────────────────
+
+describe('cmdPhaseFinalize', () => {
+  let fixture;
+  let phase;
+
+  beforeEach(() => {
+    fixture = makePhaseFinalizeFixture();
+    // Reload phase.cjs each time so the fixture cwd's config is re-read fresh
+    delete require.cache[require.resolve('./phase.cjs')];
+    phase = require('./phase.cjs');
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+  });
+
+  it('creates a single commit containing tracking files + VERIFICATION.md', () => {
+    const before = gitLog(fixture.cwd).length;
+    const { json } = captureStdout(() =>
+      phase.cmdPhaseFinalize(fixture.cwd, '01', { push: false }, true)
+    );
+
+    assert.ok(json, 'should emit JSON output');
+    assert.equal(json.committed, true);
+    assert.ok(json.hash, 'should return commit hash');
+    assert.equal(gitLog(fixture.cwd).length, before + 1, 'exactly one new commit');
+
+    const files = gitShowFiles(fixture.cwd, 'HEAD');
+    assert.ok(files.includes('ROADMAP.md'), 'ROADMAP.md staged');
+    assert.ok(files.includes('STATE.md'), 'STATE.md staged');
+    assert.ok(files.includes('REQUIREMENTS.md'), 'REQUIREMENTS.md staged');
+    assert.ok(
+      files.some(f => /VERIFICATION\.md$/.test(f)),
+      'VERIFICATION.md staged'
+    );
+  });
+
+  it('commit message uses docs(phase-NN): format', () => {
+    captureStdout(() =>
+      phase.cmdPhaseFinalize(fixture.cwd, '01', { push: false }, true)
+    );
+    assert.equal(gitLastMessage(fixture.cwd), 'docs(phase-01): complete phase execution');
+  });
+
+  it('succeeds when VERIFICATION.md is absent', () => {
+    // Simply delete the untracked VERIFICATION.md (never committed)
+    fs.unlinkSync(path.join(fixture.cwd, 'phases/01-test-phase/01-VERIFICATION.md'));
+
+    const { json } = captureStdout(() =>
+      phase.cmdPhaseFinalize(fixture.cwd, '01', { push: false }, true)
+    );
+
+    assert.equal(json.committed, true);
+    const files = gitShowFiles(fixture.cwd, 'HEAD');
+    assert.ok(!files.some(f => /VERIFICATION\.md$/.test(f)), 'no VERIFICATION in commit');
+    assert.ok(files.includes('ROADMAP.md'), 'ROADMAP still committed');
+  });
+
+  it('succeeds when REQUIREMENTS.md is absent', () => {
+    // VERIFICATION.md is untracked at this point — stage only the REQUIREMENTS removal.
+    fs.unlinkSync(path.join(fixture.cwd, 'REQUIREMENTS.md'));
+    execSync('git add REQUIREMENTS.md', { cwd: fixture.cwd, stdio: 'pipe' });
+    execSync('git commit -m "remove req"', { cwd: fixture.cwd, stdio: 'pipe' });
+
+    const { json } = captureStdout(() =>
+      phase.cmdPhaseFinalize(fixture.cwd, '01', { push: false }, true)
+    );
+
+    assert.equal(json.committed, true);
+    const files = gitShowFiles(fixture.cwd, 'HEAD');
+    assert.ok(!files.includes('REQUIREMENTS.md'), 'no REQUIREMENTS in commit');
+    assert.ok(files.includes('ROADMAP.md'), 'ROADMAP still committed');
+    assert.ok(files.includes('STATE.md'), 'STATE still committed');
+    assert.ok(
+      files.some(f => /VERIFICATION\.md$/.test(f)),
+      'VERIFICATION still committed'
+    );
+  });
+
+  it('honors commit_docs=false (no commit, but file writes still happen)', () => {
+    const cfgPath = path.join(fixture.cwd, 'config.json');
+    const cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf-8'));
+    cfg.commit_docs = false;
+    fs.writeFileSync(cfgPath, JSON.stringify(cfg));
+    // Commit only the config change (VERIFICATION.md is untracked; leave it)
+    execSync('git add config.json', { cwd: fixture.cwd, stdio: 'pipe' });
+    execSync('git commit -m "disable commit_docs"', { cwd: fixture.cwd, stdio: 'pipe' });
+
+    const before = gitLog(fixture.cwd).length;
+    const { json } = captureStdout(() =>
+      phase.cmdPhaseFinalize(fixture.cwd, '01', { push: false }, true)
+    );
+
+    assert.equal(json.committed, false);
+    assert.equal(json.commit_reason, 'skipped_commit_docs_false');
+    assert.equal(gitLog(fixture.cwd).length, before, 'no new commit created');
+
+    // File writes still happened: ROADMAP should have [x]
+    const roadmap = fs.readFileSync(path.join(fixture.cwd, 'ROADMAP.md'), 'utf-8');
+    assert.match(roadmap, /\[x\]/, 'roadmap checkbox updated despite no commit');
+  });
+
+  it('returns committed=false with nothing_to_commit when no files to stage', () => {
+    // Remove all tracking files and VERIFICATION.md BEFORE finalize. findPhaseInternal
+    // still succeeds via the phase dir + PLAN.md, but no files exist to stage.
+    fs.unlinkSync(path.join(fixture.cwd, 'phases/01-test-phase/01-VERIFICATION.md'));
+    fs.unlinkSync(path.join(fixture.cwd, 'ROADMAP.md'));
+    fs.unlinkSync(path.join(fixture.cwd, 'STATE.md'));
+    fs.unlinkSync(path.join(fixture.cwd, 'REQUIREMENTS.md'));
+    execSync('git add -A', { cwd: fixture.cwd, stdio: 'pipe' });
+    execSync('git commit -m "remove all tracking"', { cwd: fixture.cwd, stdio: 'pipe' });
+
+    const before = gitLog(fixture.cwd).length;
+    const { json } = captureStdout(() =>
+      phase.cmdPhaseFinalize(fixture.cwd, '01', { push: false }, true)
+    );
+    assert.equal(json.committed, false);
+    assert.equal(json.commit_reason, 'nothing_to_commit');
+    assert.equal(gitLog(fixture.cwd).length, before, 'no new commit');
+  });
+});
+
+describe('cmdPlanFinalize', () => {
+  let fixture;
+  let commands;
+
+  beforeEach(() => {
+    fixture = makePlanFinalizeFixture();
+    delete require.cache[require.resolve('./commands.cjs')];
+    commands = require('./commands.cjs');
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+  });
+
+  it('creates a single commit containing PLAN + SUMMARY + tracking files', () => {
+    const before = gitLog(fixture.cwd).length;
+    const { json } = captureStdout(() =>
+      commands.cmdPlanFinalize(fixture.cwd, '04', '01', { push: false }, true)
+    );
+
+    assert.ok(json, 'should emit JSON output');
+    assert.equal(json.committed, true);
+    assert.ok(json.hash);
+    assert.equal(gitLog(fixture.cwd).length, before + 1, 'exactly one new commit');
+
+    const files = gitShowFiles(fixture.cwd, 'HEAD');
+    assert.ok(files.some(f => f.endsWith('04-01-PLAN.md')), 'PLAN.md staged');
+    assert.ok(files.some(f => f.endsWith('04-01-SUMMARY.md')), 'SUMMARY.md staged');
+    assert.ok(files.includes('STATE.md'), 'STATE.md staged');
+    assert.ok(files.includes('ROADMAP.md'), 'ROADMAP.md staged');
+    assert.ok(files.includes('REQUIREMENTS.md'), 'REQUIREMENTS.md staged');
+  });
+
+  it('commit message uses plan_name from PLAN.md frontmatter', () => {
+    captureStdout(() =>
+      commands.cmdPlanFinalize(fixture.cwd, '04', '01', { push: false }, true)
+    );
+    assert.equal(gitLastMessage(fixture.cwd), 'docs(04-01): complete auth-login plan');
+  });
+
+  it('--plan-name flag overrides frontmatter plan_name', () => {
+    captureStdout(() =>
+      commands.cmdPlanFinalize(fixture.cwd, '04', '01', { push: false, planName: 'override-name' }, true)
+    );
+    assert.equal(gitLastMessage(fixture.cwd), 'docs(04-01): complete override-name plan');
+  });
+
+  it('marks requirements from frontmatter complete', () => {
+    const { json } = captureStdout(() =>
+      commands.cmdPlanFinalize(fixture.cwd, '04', '01', { push: false }, true)
+    );
+    assert.equal(json.committed, true);
+    assert.deepEqual(json.requirements.marked_complete, ['AUTH-01']);
+
+    const reqContent = fs.readFileSync(path.join(fixture.cwd, 'REQUIREMENTS.md'), 'utf-8');
+    assert.match(reqContent, /- \[x\] \*\*AUTH-01\*\*/, 'checkbox marked');
+    assert.match(reqContent, /\|\s*AUTH-01\s*\|[^|]+\|\s*Complete\s*\|/, 'traceability Complete');
+  });
+
+  it('succeeds gracefully when REQUIREMENTS.md is absent', () => {
+    fs.unlinkSync(path.join(fixture.cwd, 'REQUIREMENTS.md'));
+    // Stage only the REQUIREMENTS removal — leave PLAN/SUMMARY untracked/dirty
+    // so finalize picks them up in the atomic commit.
+    execSync('git add REQUIREMENTS.md', { cwd: fixture.cwd, stdio: 'pipe' });
+    execSync('git commit -m "remove req"', { cwd: fixture.cwd, stdio: 'pipe' });
+
+    const { json } = captureStdout(() =>
+      commands.cmdPlanFinalize(fixture.cwd, '04', '01', { push: false }, true)
+    );
+    assert.equal(json.committed, true);
+    const files = gitShowFiles(fixture.cwd, 'HEAD');
+    assert.ok(!files.includes('REQUIREMENTS.md'), 'REQUIREMENTS not committed');
+    assert.ok(files.some(f => f.endsWith('04-01-PLAN.md')), 'PLAN still committed');
+    assert.ok(files.some(f => f.endsWith('04-01-SUMMARY.md')), 'SUMMARY still committed');
+    assert.ok(files.includes('STATE.md'), 'STATE still committed');
+    assert.ok(files.includes('ROADMAP.md'), 'ROADMAP still committed');
+  });
+
+  it('honors commit_docs=false (no commit, but file writes still happen)', () => {
+    const cfgPath = path.join(fixture.cwd, 'config.json');
+    const cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf-8'));
+    cfg.commit_docs = false;
+    fs.writeFileSync(cfgPath, JSON.stringify(cfg));
+    execSync('git add -A', { cwd: fixture.cwd, stdio: 'pipe' });
+    execSync('git commit -m "disable commit_docs"', { cwd: fixture.cwd, stdio: 'pipe' });
+
+    const before = gitLog(fixture.cwd).length;
+    const { json } = captureStdout(() =>
+      commands.cmdPlanFinalize(fixture.cwd, '04', '01', { push: false }, true)
+    );
+    assert.equal(json.committed, false);
+    assert.equal(json.commit_reason, 'skipped_commit_docs_false');
+    assert.equal(gitLog(fixture.cwd).length, before, 'no new commit');
+  });
+
+  it('falls back to "execution" when plan_name missing and no flag', () => {
+    // Remove plan_name from frontmatter
+    const planPath = path.join(fixture.cwd, 'phases/04-auth/04-01-PLAN.md');
+    const content = fs.readFileSync(planPath, 'utf-8').replace(/plan_name:.*\n/, '');
+    fs.writeFileSync(planPath, content);
+    execSync('git add -A', { cwd: fixture.cwd, stdio: 'pipe' });
+    execSync('git commit -m "strip plan_name"', { cwd: fixture.cwd, stdio: 'pipe' });
+
+    captureStdout(() =>
+      commands.cmdPlanFinalize(fixture.cwd, '04', '01', { push: false }, true)
+    );
+    assert.equal(gitLastMessage(fixture.cwd), 'docs(04-01): complete execution plan');
+  });
+});

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

@@ -42,9 +42,11 @@ function createProjectSubfolder(cwd, slug, name, options) {
   // Create project directory
   fs.mkdirSync(projectDir, { recursive: true });
 
-  // Create standard subdirectories
+  // Create standard subdirectories with .gitkeep so git tracks empty folders
   for (const dir of STANDARD_DIRS) {
-    fs.mkdirSync(path.join(projectDir, dir), { recursive: true });
+    const dirPath = path.join(projectDir, dir);
+    fs.mkdirSync(dirPath, { recursive: true });
+    fs.writeFileSync(path.join(dirPath, '.gitkeep'), '');
   }
 
   // Create standard files with templates
@@ -163,13 +165,11 @@ function scanProjectReposTags(cwd, slug) {
   return Array.from(allRepos).sort();
 }
 
-// ─── PROJECTS.md Regeneration ───────────────────────────────────────────────
+// ─── Projects Readonly Listing ──────────────────────────────────────────────
 
 /**
- * Regenerate PROJECTS.md by scanning all project subfolders.
- *
- * Reads each project's STATE.md for status/phase/progress, scans plan
- * <repos> tags for repos touched, and writes the derived PROJECTS.md.
+ * Enumerate all project subfolders and build a { projects, warnings } result
+ * WITHOUT writing PROJECTS.md. Pure read function — no side effects.
  *
  * Ghost project guard: projects whose STATE.md is missing or unreadable
  * are warned about and omitted from the output.
@@ -177,7 +177,7 @@ function scanProjectReposTags(cwd, slug) {
  * @param {string} cwd - Working directory (product root)
  * @returns {{ projects: Array, warnings: string[] }}
  */
-function regenerateProjectsMd(cwd) {
+function listProjectsReadonly(cwd) {
   const slugs = getProjectFolders(cwd);
   const warnings = [];
   const projects = [];
@@ -200,6 +200,25 @@ function regenerateProjectsMd(cwd) {
     });
   }
 
+  return { projects, warnings };
+}
+
+// ─── PROJECTS.md Regeneration ───────────────────────────────────────────────
+
+/**
+ * Regenerate PROJECTS.md by scanning all project subfolders.
+ *
+ * Reads each project's STATE.md for status/phase/progress, scans plan
+ * <repos> tags for repos touched, and writes the derived PROJECTS.md.
+ *
+ * Delegates the read phase to listProjectsReadonly.
+ *
+ * @param {string} cwd - Working directory (product root)
+ * @returns {{ projects: Array, warnings: string[] }}
+ */
+function regenerateProjectsMd(cwd) {
+  const { projects, warnings } = listProjectsReadonly(cwd);
+
   // Write PROJECTS.md
   let content = '# Projects\n\n';
   content += '## Active\n\n';
@@ -677,6 +696,7 @@ module.exports = {
   createProjectSubfolder,
   readProjectState,
   scanProjectReposTags,
+  listProjectsReadonly,
   regenerateProjectsMd,
   completeProject,
   reactivateProject,

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

@@ -39,6 +39,7 @@ const {
   readProjectState,
   scanProjectReposTags,
   regenerateProjectsMd,
+  listProjectsReadonly,
   completeProject,
   reactivateProject,
   parseProjectsMd,
@@ -323,6 +324,91 @@ describe('regenerateProjectsMd', () => {
   });
 });
 
+// ─── listProjectsReadonly ───────────────────────────────────────────────────
+
+describe('listProjectsReadonly', () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = createTempDir(); tmpDir = fs.realpathSync(tmpDir); initGitRepo(tmpDir);
+    setupPlanning(tmpDir);
+  });
+
+  afterEach(() => { resetPaths(); cleanupDir(tmpDir); });
+
+  it('returns same projects shape as regenerateProjectsMd for a fixture with 2 active + 1 completed', () => {
+    createProjectManually(tmpDir, 'active-a', '# Project State\n\nPhase: 1\nStatus: In progress\nProgress: [##--------] 20%\n');
+    createProjectManually(tmpDir, 'active-b', '# Project State\n\nPhase: 3\nStatus: Active\nProgress: [#####-----] 50%\n');
+    createProjectManually(tmpDir, 'done-c', '# Project State\n\nPhase: 10\nStatus: completed\nProgress: [##########] 100%\nCompleted: 2026-02-15\n');
+
+    const readResult = listProjectsReadonly(tmpDir);
+    const regenResult = regenerateProjectsMd(tmpDir);
+
+    assert.ok(Array.isArray(readResult.projects));
+    assert.ok(Array.isArray(readResult.warnings));
+    assert.strictEqual(readResult.projects.length, regenResult.projects.length);
+    // Projects should have identical fields
+    const readByName = Object.fromEntries(readResult.projects.map(p => [p.name, p]));
+    const regenByName = Object.fromEntries(regenResult.projects.map(p => [p.name, p]));
+    for (const name of Object.keys(readByName)) {
+      assert.deepStrictEqual(readByName[name], regenByName[name]);
+    }
+  });
+
+  it('does NOT write PROJECTS.md', () => {
+    createProjectManually(tmpDir, 'proj-a', '# Project State\n\nPhase: 2\nStatus: Active\n');
+    const projectsMdPath = path.join(tmpDir, 'PROJECTS.md');
+    assert.strictEqual(fs.existsSync(projectsMdPath), false);
+
+    const result = listProjectsReadonly(tmpDir);
+    assert.ok(Array.isArray(result.projects));
+
+    assert.strictEqual(fs.existsSync(projectsMdPath), false, 'listProjectsReadonly must not create PROJECTS.md');
+  });
+
+  it('does NOT modify an existing PROJECTS.md', () => {
+    createProjectManually(tmpDir, 'proj-a', '# Project State\n\nPhase: 2\nStatus: Active\n');
+    const projectsMdPath = path.join(tmpDir, 'PROJECTS.md');
+    const sentinel = '# Projects\n\nSENTINEL CONTENT — should not be overwritten by listProjectsReadonly\n';
+    fs.writeFileSync(projectsMdPath, sentinel);
+
+    listProjectsReadonly(tmpDir);
+
+    const after = fs.readFileSync(projectsMdPath, 'utf-8');
+    assert.strictEqual(after, sentinel, 'listProjectsReadonly must not modify existing PROJECTS.md');
+  });
+
+  it('returns a project entry with all expected fields', () => {
+    createProjectManually(tmpDir, 'proj-a', '# Project State\n\nPhase: 5\nStatus: Active\nProgress: [###-------] 30%\n');
+    const result = listProjectsReadonly(tmpDir);
+    assert.strictEqual(result.projects.length, 1);
+    const p = result.projects[0];
+    assert.strictEqual(p.name, 'proj-a');
+    assert.strictEqual(p.status, 'Active');
+    assert.strictEqual(p.current_phase, '5');
+    assert.strictEqual(p.progress, 30);
+    assert.strictEqual(typeof p.repos_touched, 'string');
+    assert.ok('completed_date' in p);
+  });
+
+  it('returns ghost-project behavior consistent with regenerateProjectsMd (omits projects without STATE.md)', () => {
+    // Ghost project: directory exists but no STATE.md
+    fs.mkdirSync(path.join(tmpDir, 'projects', 'ghost-project'), { recursive: true });
+    // Real project
+    createProjectManually(tmpDir, 'real-project', '# State\n\nStatus: Active\n');
+
+    const result = listProjectsReadonly(tmpDir);
+    assert.ok(Array.isArray(result.warnings));
+    assert.ok(!result.projects.some(p => p.name === 'ghost-project'), 'ghost project should be omitted from projects array');
+  });
+
+  it('empty projects directory returns { projects: [], warnings: [] }', () => {
+    const result = listProjectsReadonly(tmpDir);
+    assert.deepStrictEqual(result.projects, []);
+    assert.ok(Array.isArray(result.warnings));
+  });
+});
+
 // ─── completeProject ────────────────────────────────────────────────────────
 
 describe('completeProject', () => {