@ktpartners/dgs-platform 3.4.2 → 3.5.0

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

@@ -0,0 +1,134 @@
+/**
+ * Restart-at-1 behaviour test (NUM-01).
+ *
+ * Dedicated file (separate from phase.test.cjs, which plan 02 owns) proving that a
+ * fresh versioned milestone's FIRST add-phase is numbered `01` (zero-padded) and
+ * lands UNDER the milestone's own phases/<version>/ directory — i.e. phase numbering
+ * restarts per milestone with NO arithmetic change (empty roadmap → maxPhase=0 →
+ * newPhaseNum=1 → '01'), and no global / MILESTONES.md continuation leaks into the number.
+ *
+ * Uses Node.js built-in test runner (node:test) + assert.
+ */
+
+const { describe, it } = require('node:test');
+const assert = require('node:assert');
+const fs = require('node:fs');
+const path = require('node:path');
+const { createFixture } = require('./test-helpers.cjs');
+const { cmdPhaseInitVersionedDir, cmdPhaseAdd } = require('./phase.cjs');
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+/**
+ * Capture stdout from CLI commands that call output() (process.stdout.write +
+ * process.exit). Mirrors phase.test.cjs's captureStdout so multiple 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 };
+}
+
+/**
+ * Fresh-milestone v2 fixture. STATE.md frontmatter `current_milestone` is what
+ * resolveMilestoneVersion(required) reads. The ROADMAP has NO `### Phase` heading
+ * (fresh milestone) plus a `---` trailer so cmdPhaseAdd's insertion logic has a
+ * separator. `roadmapBody` lets a test seed a high-number context to prove
+ * milestone-local numbering.
+ */
+function freshMilestoneFixture({ slug = 'auth-overhaul', milestone = 'v26.0', roadmapBody } = {}) {
+  return createFixture({
+    'config.json': JSON.stringify({}),
+    'config.local.json': JSON.stringify({ current_project: slug }),
+    'PROJECTS.md': '# Projects\n\n| Project | Status |\n',
+    'REPOS.md': '# Repos\n\n| Name | Path |\n',
+    [`projects/${slug}/PROJECT.md`]: '# Project',
+    [`projects/${slug}/STATE.md`]: `---\ncurrent_milestone: ${milestone}\n---\n# State`,
+    [`projects/${slug}/ROADMAP.md`]: roadmapBody || '# Roadmap\n\n## Phases\n\n---\n',
+    [`projects/${slug}/phases/`]: null,
+  });
+}
+
+// ─── Restart-at-1 (NUM-01) ────────────────────────────────────────────────────
+
+describe('restart-at-1 in a fresh versioned milestone (NUM-01)', () => {
+  it('Test 1: first add-phase is 01 and lands under phases/<version>/', () => {
+    const fixture = freshMilestoneFixture({ slug: 'auth-overhaul', milestone: 'v26.0' });
+    try {
+      // new-milestone flow materialises phases/v26.0/ (NUM-02 command).
+      captureStdout(() => cmdPhaseInitVersionedDir(fixture.cwd, true));
+
+      // First add-phase in the fresh versioned milestone.
+      const { json } = captureStdout(() =>
+        cmdPhaseAdd(fixture.cwd, 'first thing', false)
+      );
+
+      assert.ok(json, 'add-phase should emit JSON');
+      // Restart-at-1: empty versioned roadmap → maxPhase=0 → newPhaseNum=1 → '01'.
+      assert.equal(json.padded, '01', 'first phase is zero-padded 01');
+      assert.equal(json.phase_number, 1, 'first phase_number is 1');
+
+      // The created dir is UNAMBIGUOUS evidence: phases/v26.0/01-first-thing.
+      const expectedDir = path.join('projects', 'auth-overhaul', 'phases', 'v26.0', '01-first-thing');
+      assert.equal(json.directory, expectedDir, 'phase dir is numbered 01 under the versioned dir');
+      assert.ok(
+        fs.existsSync(path.join(fixture.cwd, expectedDir)),
+        'phases/v26.0/01-first-thing exists on disk'
+      );
+    } finally {
+      fixture.cleanup();
+    }
+  });
+
+  it('Test 2: numbers stay milestone-local (no global continuation leaks into 01)', () => {
+    // Seed a ROADMAP with prose that mentions high phase numbers but NO `### Phase`
+    // heading. A global / MILESTONES.md continuation scheme would have produced a
+    // high number; the milestone-local maxPhase scan sees zero `### Phase` headings,
+    // so the first add-phase is still 01.
+    const roadmapBody =
+      '# Roadmap\n\n' +
+      'Continuation note: the previous milestone ended at phase 162.\n\n' +
+      '## Phases\n\n' +
+      '---\n';
+    const fixture = freshMilestoneFixture({
+      slug: 'auth-overhaul',
+      milestone: 'v26.0',
+      roadmapBody,
+    });
+    try {
+      captureStdout(() => cmdPhaseInitVersionedDir(fixture.cwd, true));
+      const { json } = captureStdout(() =>
+        cmdPhaseAdd(fixture.cwd, 'first thing', false)
+      );
+      assert.ok(json, 'add-phase should emit JSON');
+      // Still 01 — proves no MILESTONES.md / global 163-continuation leaks into the number.
+      assert.equal(json.padded, '01', 'milestone-local: first phase is 01 despite prose mentioning 162');
+      assert.equal(json.phase_number, 1, 'milestone-local: phase_number is 1');
+      assert.ok(
+        json.directory.startsWith(path.join('projects', 'auth-overhaul', 'phases', 'v26.0')),
+        `phase dir must be under the versioned dir: ${json.directory}`
+      );
+    } finally {
+      fixture.cleanup();
+    }
+  });
+});

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

@@ -4,7 +4,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { escapeRegex, normalizePhaseName, comparePhaseNum, findPhaseInternal, getArchivedPhaseDirs, generateSlugInternal, getMilestonePhaseFilter, toPosixPath, output, error, getProjectRoot, loadConfig, execGit } = require('./core.cjs');
+const { escapeRegex, normalizePhaseName, comparePhaseNum, findPhaseInternal, getArchivedPhaseDirs, generateSlugInternal, getMilestonePhaseFilter, toPosixPath, output, error, getProjectRoot, phasesDir, resolveProjectPath, resolveMilestoneVersion, loadConfig, execGit } = require('./core.cjs');
 const { extractFrontmatter } = require('./frontmatter.cjs');
 const { writeStateMd } = require('./state.cjs');
 
@@ -14,13 +14,13 @@ const { writeStateMd } = require('./state.cjs');
  * from getProjectRoot() or '.' as fallback.
  */
 function resolvePhasesDir(cwd) {
-  let projectRoot;
+  let phasesRel;
   try {
-    projectRoot = getProjectRoot(cwd);
+    phasesRel = phasesDir(cwd);
   } catch {
-    projectRoot = '.';
+    phasesRel = 'phases';   // flat-layout fallback (== path.join('.', 'phases'))
   }
-  return path.join(cwd, projectRoot, 'phases');
+  return path.join(cwd, phasesRel);
 }
 
 /**
@@ -406,6 +406,54 @@ function cmdPhaseAdd(cwd, description, raw) {
   output(result, raw, paddedNum);
 }
 
+/**
+ * Create the current milestone's versioned phases directory: phases/<version>/.
+ * This is the SOLE creator of a phases/<version> directory (NUM-02). It requires a
+ * determinable milestone version (fail-loud) so a phase is never written to phases/v1.0/.
+ * Idempotent: recursive mkdir is a no-op when the directory already exists.
+ * cmdPhaseAdd never calls this — it routes through the version-aware phasesDir resolver,
+ * which returns this directory once it exists.
+ */
+/**
+ * Internal, output-free creator of the current milestone's versioned phases dir.
+ * Shared by the CLI wrapper (cmdPhaseInitVersionedDir) AND create-adhoc seeding
+ * (milestone.cjs) so there is exactly ONE versioned-dir creator (Decision C / NUM-02).
+ *
+ * required:true → throws the Phase-163 remediation Error when the version is
+ * undeterminable; never writes phases/v1.0/. Idempotent: recursive mkdir is a
+ * no-op when the directory already exists, and `created` reflects whether THIS
+ * call materialized the directory (probed via existsSync BEFORE mkdir).
+ *
+ * @param {string} cwd - planning root
+ * @returns {{ version: string, directory: string, created: boolean }}
+ *          `directory` is relative to cwd.
+ */
+function phaseInitVersionedDirInternal(cwd) {
+  // required:true → throws the Phase-163 remediation Error when undeterminable; never v1.0.
+  const version = resolveMilestoneVersion(cwd, { required: true });
+  // resolveProjectPath returns the FLAT relative phases base (NOT version-aware), so joining
+  // the version is correct and idempotent on re-run. It is a function call — not a
+  // path.join(..., 'phases') literal — so the 164-05 RSLV-03 phases-join gate stays GREEN.
+  const flatBase = resolveProjectPath(cwd, 'phases');       // relative: projects/<slug>/phases or phases
+  const versionedDir = path.join(cwd, flatBase, version);   // absolute phases/<version>
+  const created = !fs.existsSync(versionedDir);             // did THIS call create it?
+  fs.mkdirSync(versionedDir, { recursive: true });          // idempotent
+  return { version, directory: path.relative(cwd, versionedDir), created };
+}
+
+/**
+ * Create the current milestone's versioned phases directory: phases/<version>/.
+ * This is the SOLE creator of a phases/<version> directory (NUM-02). It requires a
+ * determinable milestone version (fail-loud) so a phase is never written to phases/v1.0/.
+ * Idempotent: recursive mkdir is a no-op when the directory already exists.
+ * cmdPhaseAdd never calls this — it routes through the version-aware phasesDir resolver,
+ * which returns this directory once it exists.
+ */
+function cmdPhaseInitVersionedDir(cwd, raw) {
+  const { version, directory, created } = phaseInitVersionedDirInternal(cwd);
+  output({ version, directory, created }, raw, directory);
+}
+
 function cmdPhaseInsert(cwd, afterPhase, description, raw) {
   if (!afterPhase || !description) {
     error('after-phase and description required for phase insert');
@@ -767,8 +815,11 @@ function phaseCompleteInternal(cwd, phaseNum) {
 
   // Verify phase info
   const phaseInfo = findPhaseInternal(cwd, phaseNum);
-  if (!phaseInfo) {
-    error(`Phase ${phaseNum} not found`);
+  // Guard on `found`: a LOOK-01 ambiguity object is truthy but has no
+  // .directory/.plans, so neither is reached for an ambiguity object. Surface
+  // its milestone-qualified message instead of throwing.
+  if (!phaseInfo || !phaseInfo.found) {
+    error(phaseInfo?.message || `Phase ${phaseNum} not found`);
   }
 
   // Absolute phase directory (phaseInfo.directory is relative to cwd)
@@ -1046,6 +1097,8 @@ module.exports = {
   cmdFindPhase,
   cmdPhasePlanIndex,
   cmdPhaseAdd,
+  cmdPhaseInitVersionedDir,
+  phaseInitVersionedDirInternal,
   cmdPhaseInsert,
   cmdPhaseRemove,
   cmdPhaseComplete,

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

@@ -11,7 +11,8 @@ const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
 
-const { createTempProject } = require('./test-helpers.cjs');
+const { createTempProject, createFixture } = require('./test-helpers.cjs');
+const { initPaths, resetPaths } = require('./paths.cjs');
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 
@@ -418,3 +419,169 @@ describe('cmdPlanFinalize', () => {
     assert.equal(gitLastMessage(fixture.cwd), 'docs(04-01): complete execution plan');
   });
 });
+
+// ─── cmdPhaseInitVersionedDir (NUM-02 versioned write path) ────────────────────
+
+describe('cmdPhaseInitVersionedDir (NUM-02 versioned write path)', () => {
+  let phase;
+
+  beforeEach(() => {
+    // Reload phase.cjs fresh so each fixture's config/paths are re-read.
+    delete require.cache[require.resolve('./phase.cjs')];
+    phase = require('./phase.cjs');
+  });
+
+  // Shared v2 project-context builder. STATE.md frontmatter `current_milestone`
+  // is what resolveMilestoneVersion(required) reads. `roadmapBody`/`extraDirs`
+  // let individual tests scaffold a versioned ROADMAP context or pre-create dirs.
+  function v2Fixture({ slug = 'auth-overhaul', stateBody, roadmapBody, extraDirs } = {}) {
+    const tree = {
+      'config.json': JSON.stringify({}),
+      'config.local.json': JSON.stringify({ current_project: slug }),
+      'PROJECTS.md': '# Projects\n\n| Project | Status |\n',
+      'REPOS.md': '# Repos\n\n| Name | Path |\n',
+      [`projects/${slug}/PROJECT.md`]: '# Project',
+      [`projects/${slug}/STATE.md`]: stateBody,
+      [`projects/${slug}/ROADMAP.md`]: roadmapBody || '# Roadmap',
+      [`projects/${slug}/phases/`]: null,
+    };
+    for (const d of (extraDirs || [])) tree[d] = null;
+    return createFixture(tree);
+  }
+
+  it('Test 1: creates the current milestone versioned dir phases/<version>/', () => {
+    const fixture = v2Fixture({ stateBody: '---\ncurrent_milestone: v26.0\n---\n# State' });
+    try {
+      // raw=false → output() emits structured JSON (raw=true would print the human relDir line).
+      const { json } = captureStdout(() =>
+        phase.cmdPhaseInitVersionedDir(fixture.cwd, false)
+      );
+      const versioned = path.join(fixture.cwd, 'projects', 'auth-overhaul', 'phases', 'v26.0');
+      assert.ok(fs.existsSync(versioned), 'phases/v26.0/ must be created');
+      assert.ok(fs.statSync(versioned).isDirectory(), 'phases/v26.0/ must be a directory');
+      // Output reports the version + relative directory.
+      assert.ok(json, 'should emit JSON output');
+      assert.equal(json.version, 'v26.0');
+      assert.equal(json.created, true);
+      assert.equal(
+        json.directory,
+        path.join('projects', 'auth-overhaul', 'phases', 'v26.0')
+      );
+    } finally {
+      fixture.cleanup();
+    }
+  });
+
+  it('Test 2: idempotent — re-run does NOT throw and creates NO nested phases/<version>/<version>/', () => {
+    const fixture = v2Fixture({ stateBody: '---\ncurrent_milestone: v26.0\n---\n# State' });
+    try {
+      // First invocation creates phases/v26.0/. Now phasesDir(cwd) is version-aware
+      // and would return phases/v26.0 — so a wrong (version-aware-base) construction
+      // would yield phases/v26.0/v26.0 on the SECOND run. This asserts it does NOT.
+      assert.doesNotThrow(() => {
+        captureStdout(() => phase.cmdPhaseInitVersionedDir(fixture.cwd, true));
+        captureStdout(() => phase.cmdPhaseInitVersionedDir(fixture.cwd, true));
+      });
+      const versioned = path.join(fixture.cwd, 'projects', 'auth-overhaul', 'phases', 'v26.0');
+      const nested = path.join(versioned, 'v26.0');
+      assert.ok(fs.existsSync(versioned), 'phases/v26.0/ exists exactly once');
+      assert.ok(!fs.existsSync(nested), 'NO nested phases/v26.0/v26.0/ (flat-base idempotency)');
+    } finally {
+      fixture.cleanup();
+    }
+  });
+
+  it('Test 3: fail-loud — undeterminable version throws (current_milestone remediation), writes NO phases/v1.0/', () => {
+    const fixture = v2Fixture({ stateBody: '# State (no milestone frontmatter)' });
+    try {
+      let thrown = null;
+      try {
+        captureStdout(() => phase.cmdPhaseInitVersionedDir(fixture.cwd, true));
+      } catch (e) {
+        thrown = e;
+      }
+      assert.ok(thrown, 'must throw on undeterminable version');
+      assert.match(thrown.message, /current_milestone/, 'remediation references current_milestone');
+      assert.match(thrown.message, /STATE\.md/, 'remediation references STATE.md');
+      assert.ok(!/v1\.0/.test(thrown.message), 'message must NOT mention v1.0');
+      // Critical: no phases/v1.0/ and no phases/undefined/ were written.
+      const phasesBase = path.join(fixture.cwd, 'projects', 'auth-overhaul', 'phases');
+      assert.ok(!fs.existsSync(path.join(phasesBase, 'v1.0')), 'NO phases/v1.0/ created');
+      assert.ok(!fs.existsSync(path.join(phasesBase, 'undefined')), 'NO phases/undefined/ created');
+    } finally {
+      fixture.cleanup();
+    }
+  });
+
+  it('Test 4: after create, cmdPhaseAdd lands the new phase under phases/<version>/', () => {
+    const fixture = v2Fixture({
+      stateBody: '---\ncurrent_milestone: v26.0\n---\n# State',
+      // Versioned ROADMAP context so maxPhase resolves (empty here → maxPhase=0 → newPhaseNum=1).
+      roadmapBody: '# Roadmap\n\n## Phases\n\n',
+    });
+    try {
+      captureStdout(() => phase.cmdPhaseInitVersionedDir(fixture.cwd, true));
+      const { json } = captureStdout(() =>
+        phase.cmdPhaseAdd(fixture.cwd, 'First versioned phase', false)
+      );
+      assert.ok(json, 'add-phase should emit JSON');
+      // New phase dir lands UNDER phases/v26.0/ because version-aware phasesDir returns it.
+      assert.ok(
+        json.directory.startsWith(path.join('projects', 'auth-overhaul', 'phases', 'v26.0')),
+        `phase dir must be under versioned dir: ${json.directory}`
+      );
+      assert.equal(json.padded, '01', 'restart-at-1: empty versioned roadmap numbers from 01');
+      assert.ok(fs.existsSync(path.join(fixture.cwd, json.directory)), 'new phase dir exists on disk');
+    } finally {
+      fixture.cleanup();
+    }
+  });
+
+  it('Test 5: two active milestones — each add-phase lands in its own phases/<version>/', () => {
+    const roadmap = '# Roadmap\n\n## Phases\n\n';
+    const fixtureA = v2Fixture({
+      slug: 'proj-a',
+      stateBody: '---\ncurrent_milestone: v26.0\n---\n# State',
+      roadmapBody: roadmap,
+    });
+    const fixtureB = v2Fixture({
+      slug: 'proj-b',
+      stateBody: '---\ncurrent_milestone: v27.0\n---\n# State',
+      roadmapBody: roadmap,
+    });
+    try {
+      // Create each milestone's versioned dir, then add-phase in each context.
+      // Both fixtures live simultaneously; the planning-root cache is a single
+      // per-process value (createFixture primed it for whichever was built last),
+      // so reset + re-prime for each project before operating on it, otherwise
+      // operations on the other would read a stale root / wrong current_project.
+      resetPaths();
+      initPaths(fixtureA.cwd);
+      captureStdout(() => phase.cmdPhaseInitVersionedDir(fixtureA.cwd, true));
+      const { json: jsonA } = captureStdout(() =>
+        phase.cmdPhaseAdd(fixtureA.cwd, 'A first phase', false)
+      );
+      resetPaths();
+      initPaths(fixtureB.cwd);
+      captureStdout(() => phase.cmdPhaseInitVersionedDir(fixtureB.cwd, true));
+      const { json: jsonB } = captureStdout(() =>
+        phase.cmdPhaseAdd(fixtureB.cwd, 'B first phase', false)
+      );
+
+      assert.ok(
+        jsonA.directory.startsWith(path.join('projects', 'proj-a', 'phases', 'v26.0')),
+        `A lands in v26.0: ${jsonA.directory}`
+      );
+      assert.ok(
+        jsonB.directory.startsWith(path.join('projects', 'proj-b', 'phases', 'v27.0')),
+        `B lands in v27.0: ${jsonB.directory}`
+      );
+      // Each numbered relative to its own (initially-empty) versioned roadmap.
+      assert.equal(jsonA.padded, '01');
+      assert.equal(jsonB.padded, '01');
+    } finally {
+      fixtureA.cleanup();
+      fixtureB.cleanup();
+    }
+  });
+});

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

@@ -225,6 +225,44 @@ describe('readProjectState', () => {
     assert.ok(state !== null);
     assert.strictEqual(state.phase, 'Unknown');
   });
+
+  it('returns a non-stale phase for a shipped, production-shaped STATE.md', () => {
+    // Regression (DASH-STALE-01): after a milestone ships, markMilestoneComplete
+    // resets the Current Position Phase: line to the between-milestones form. This
+    // proves readProjectState — whose Phase: read regex is UNANCHORED — yields a
+    // non-stale phase when given a realistic, fully-synced production STATE.md
+    // (full frontmatter block, NOT a bare `# Project State` body).
+    const shippedState = `---
+dgs_state_version: 1.0
+milestone: v1.0
+milestone_name: milestone
+status: milestone_shipped
+last_updated: "2026-06-27T00:00:00.000Z"
+completed_date: 2026-06-27
+progress:
+  total_phases: 8
+  completed_phases: 8
+  total_plans: 20
+  completed_plans: 20
+  percent: 100
+---
+
+# Project State
+
+## Current Position
+
+Phase: — (between milestones; v1.0 shipped 2026-06-27)
+Status: Milestone v1.0 shipped 2026-06-27
+Progress: [██████████] 100%
+`;
+    createProjectManually(tmpDir, 'proj', shippedState);
+    const state = readProjectState(tmpDir, 'proj');
+    assert.ok(
+      !/\d+\s+of\s+\d+/.test(state.phase),
+      `Shipped STATE should yield a non-stale phase, got: ${state.phase}`
+    );
+    assert.ok(/between milestones/.test(state.phase), 'phase reflects between-milestones form');
+  });
 });
 
 // ─── scanProjectReposTags ───────────────────────────────────────────────────

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

@@ -8,7 +8,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { safeReadFile, execGit, isV2Install, output, error } = require('./core.cjs');
+const { safeReadFile, execGit, isV2Install, output, error, phasesDir } = require('./core.cjs');
 const { writeConfigField } = require('./config.cjs');
 const { getPlanningRoot, resetPaths } = require('./paths.cjs');
 
@@ -997,15 +997,19 @@ function cmdReposRemove(cwd, repoName, options, raw) {
  */
 function scanRepoReferences(cwd, repoName) {
   const references = [];
-  const phasesDir = path.join(getPlanningRoot(cwd), 'phases');
 
   try {
-    const phaseDirs = fs.readdirSync(phasesDir, { withFileTypes: true })
+    // RSLV-03 residue (Phase 170): resolve the project + version scoped phases dir
+    // via the canonical resolver so `repos repo show` finds phase hits under a
+    // versioned layout. phasesDir(cwd) is fail-loud; the throw degrades to empty
+    // references through this same catch, matching the prior readdirSync-throws path.
+    const phasesAbs = path.join(cwd, phasesDir(cwd));
+    const phaseDirs = fs.readdirSync(phasesAbs, { withFileTypes: true })
       .filter(e => e.isDirectory())
       .map(e => e.name);
 
     for (const phaseDir of phaseDirs) {
-      const fullPhaseDir = path.join(phasesDir, phaseDir);
+      const fullPhaseDir = path.join(phasesAbs, phaseDir);
       const planFiles = fs.readdirSync(fullPhaseDir)
         .filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md');
 

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

@@ -618,9 +618,13 @@ describe('writeReposMd -> parseReposMd roundtrip', () => {
   afterEach(() => { resetPaths(); cleanupDir(tmpDir); });
 
   it('write then parse produces identical data', () => {
+    // parseReposMd always returns a `setup` field (defensive 6th-column read);
+    // writeReposMd's standard 4-column table omits an empty setup, so the
+    // roundtrip normalizes setup to '' for every row. Expected objects must
+    // include it to match shipped parser behaviour.
     const repos = [
-      { name: 'web', path: './web', url: 'https://github.com/org/web', description: 'Frontend' },
-      { name: 'api', path: './api', url: '', description: 'Backend API' },
+      { name: 'web', path: './web', url: 'https://github.com/org/web', description: 'Frontend', setup: '' },
+      { name: 'api', path: './api', url: '', description: 'Backend API', setup: '' },
     ];
     writeReposMd(tmpDir, repos);
     const parsed = parseReposMd(tmpDir);

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

@@ -4,7 +4,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { escapeRegex, normalizePhaseName, output, error, findPhaseInternal, resolveProjectPath } = require('./core.cjs');
+const { escapeRegex, normalizePhaseName, output, error, findPhaseInternal, resolveProjectPath, phasesDir } = require('./core.cjs');
 
 function cmdRoadmapGetPhase(cwd, phaseNum, raw) {
   const roadmapPath = path.join(cwd, resolveProjectPath(cwd, 'ROADMAP.md'));
@@ -99,7 +99,7 @@ function cmdRoadmapAnalyze(cwd, raw) {
   }
 
   const content = fs.readFileSync(roadmapPath, 'utf-8');
-  const phasesDir = path.join(cwd, resolveProjectPath(cwd, 'phases'));
+  const phasesAbs = path.join(cwd, phasesDir(cwd));
 
   // Extract all phase headings: ## Phase N: Name or ### Phase N: Name
   const phasePattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:\s*([^\n]+)/gi;
@@ -132,12 +132,12 @@ function cmdRoadmapAnalyze(cwd, raw) {
     let hasResearch = false;
 
     try {
-      const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+      const entries = fs.readdirSync(phasesAbs, { withFileTypes: true });
       const dirs = entries.filter(e => e.isDirectory()).map(e => e.name);
       const dirMatch = dirs.find(d => d.startsWith(normalized + '-') || d === normalized);
 
       if (dirMatch) {
-        const phaseFiles = fs.readdirSync(path.join(phasesDir, dirMatch));
+        const phaseFiles = fs.readdirSync(path.join(phasesAbs, dirMatch));
         planCount = phaseFiles.filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md').length;
         summaryCount = phaseFiles.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md').length;
         hasContext = phaseFiles.some(f => f.endsWith('-CONTEXT.md') || f === 'CONTEXT.md');
@@ -237,8 +237,11 @@ function roadmapUpdatePlanProgressInternal(cwd, phaseNum) {
   const roadmapPath = path.join(cwd, resolveProjectPath(cwd, 'ROADMAP.md'));
 
   const phaseInfo = findPhaseInternal(cwd, phaseNum);
-  if (!phaseInfo) {
-    error(`Phase ${phaseNum} not found`);
+  // Guard on `found`: a LOOK-01 ambiguity object is truthy but has no .plans,
+  // so `phaseInfo.plans.length` is not reached for an ambiguity object. Surface
+  // its milestone-qualified message instead of throwing.
+  if (!phaseInfo || !phaseInfo.found) {
+    error(phaseInfo?.message || `Phase ${phaseNum} not found`);
   }
 
   const planCount = phaseInfo.plans.length;