@ktpartners/dgs-platform 3.5.0 → 3.5.3

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

@@ -18,6 +18,7 @@ const {
   parseJobFile, updateJobStep, moveJobFile,
   generateMilestoneSteps, buildJobFileContent,
   cmdJobsCreateMilestone, cmdJobsMilestonePreview,
+  analyzeMilestonePhases, detectActiveMilestone,
   findJobFile, updateJobHeader, insertJobSteps,
   buildGapFixSteps, insertGapFixSection,
   listJobs, cancelJob, recordStartShas, rollbackJob,
@@ -1379,6 +1380,199 @@ Plans:
     });
   });
 
+  // ─── Bold-line single-milestone format Tests ────────────────────────────
+
+  describe('bold-line single-milestone format', () => {
+    let fixture;
+
+    afterEach(() => {
+      if (fixture) fixture.cleanup();
+    });
+
+    const BOLD_LINE_ROADMAP = `# Roadmap: Tenant data-quality metrics in Admin UI (v30.1)
+
+**Milestone:** v30.1 — Tenant data-quality metrics in Admin UI
+
+## Overview
+
+Single-milestone roadmap. Version is only in the title and the bold line.
+
+### Phase 1: Metrics schema
+**Goal**: Define metrics tables
+Plans:
+- [ ] 01-01-PLAN.md
+
+### Phase 2: Admin UI surface
+**Goal**: Surface metrics in admin
+Plans:
+- [ ] 02-01-PLAN.md
+`;
+
+    const MULTI_MILESTONE_WITH_BOLD = `# Roadmap (v9.9)
+
+**Milestone:** v9.9 — stray bold line
+
+## v1.0 Foundation (SHIPPED)
+### Phase 1: Base
+### Phase 2: More base
+
+## v2.0 Next (In Progress)
+### Phase 3: New
+### Phase 4: Newer
+`;
+
+    it('detectActiveMilestone returns v30.1 from the bold line', () => {
+      assert.equal(detectActiveMilestone(BOLD_LINE_ROADMAP), 'v30.1');
+    });
+
+    it('analyzeMilestonePhases derives phases 1 and 2 from the bold-line roadmap', () => {
+      fixture = createFixture({
+        'ROADMAP.md': BOLD_LINE_ROADMAP,
+        'phases/01-metrics-schema/01-01-PLAN.md': '',
+        'phases/02-admin-ui/02-01-PLAN.md': '',
+      });
+
+      const phases = analyzeMilestonePhases(fixture.cwd, 'v30.1');
+      assert.equal(phases.length, 2);
+      assert.deepEqual(phases.map(p => p.number), ['1', '2']);
+    });
+
+    it('cmdJobsMilestonePreview succeeds with an explicit version', () => {
+      fixture = createFixture({
+        'ROADMAP.md': BOLD_LINE_ROADMAP,
+        'phases/01-metrics-schema/01-01-PLAN.md': '',
+        'phases/02-admin-ui/02-01-PLAN.md': '',
+      });
+
+      const result = cmdJobsMilestonePreview(fixture.cwd, 'v30.1', true, false);
+      assert.equal(result.preview, true);
+      assert.equal(result.version, 'v30.1');
+      assert.ok(result.step_count > 0, 'expected at least one step');
+    });
+
+    it('cmdJobsMilestonePreview auto-detects the bold-line version', () => {
+      fixture = createFixture({
+        'ROADMAP.md': BOLD_LINE_ROADMAP,
+        'phases/01-metrics-schema/01-01-PLAN.md': '',
+        'phases/02-admin-ui/02-01-PLAN.md': '',
+      });
+
+      const result = cmdJobsMilestonePreview(fixture.cwd, null, true, false);
+      assert.equal(result.version, 'v30.1');
+    });
+
+    it('analyzeMilestonePhases throws on a multi-milestone roadmap with a stray bold line', () => {
+      fixture = createFixture({
+        'ROADMAP.md': MULTI_MILESTONE_WITH_BOLD,
+        'phases/01-base/01-01-PLAN.md': '',
+        'phases/03-new/03-01-PLAN.md': '',
+      });
+
+      assert.throws(
+        () => analyzeMilestonePhases(fixture.cwd, 'v9.9'),
+        (err) => /v9\.9|not found/i.test(err.message)
+      );
+    });
+
+    it('detectActiveMilestone prefers the In-Progress heading over the bold line', () => {
+      assert.equal(detectActiveMilestone(MULTI_MILESTONE_WITH_BOLD), 'v2.0');
+    });
+  });
+
+  // ─── Ad-hoc container format ────────────────────────────────────────────
+  describe('ad-hoc container format', () => {
+    let fixture;
+
+    afterEach(() => {
+      if (fixture) fixture.cleanup();
+    });
+
+    // Bare seedAdhocRoadmapSection output: version on the heading, in-progress
+    // on a SEPARATE **Status:** line, NO parenthetical on the heading, and NO
+    // phase headings. Used only for the pure detectActiveMilestone assertions.
+    const ADHOC_ROADMAP = `# Roadmap
+
+## Active Milestone: v25.1 add-prs
+
+**Goal:** add-prs
+**Status:** In progress (ad-hoc container — phases added on demand via /dgs:add-phase)
+
+Phases:
+
+---
+`;
+
+    // Ad-hoc container that has accrued a phase (heading + matching PLAN dir),
+    // so analyzeMilestonePhases (called by cmdJobsMilestonePreview) resolves
+    // rather than throwing "Milestone vX.Y not found".
+    const ADHOC_ROADMAP_WITH_PHASE = `# Roadmap
+
+## Active Milestone: v25.1 add-prs
+
+**Goal:** add-prs
+**Status:** In progress (ad-hoc container — phases added on demand via /dgs:add-phase)
+
+Phases:
+
+### Phase 1: First ad-hoc phase
+**Goal**: Do the first thing
+Plans:
+- [ ] 01-01-PLAN.md
+
+---
+`;
+
+    // Local copies of the multi-milestone / bold-line fixtures (the originals
+    // are scoped to the sibling describe block) for the over-match guard and
+    // bold-line regression assertions.
+    const MULTI_MILESTONE_WITH_BOLD = `# Roadmap (v9.9)
+
+**Milestone:** v9.9 — stray bold line
+
+## v1.0 Foundation (SHIPPED)
+### Phase 1: Base
+### Phase 2: More base
+
+## v2.0 Next (In Progress)
+### Phase 3: New
+### Phase 4: Newer
+`;
+
+    const BOLD_LINE_ROADMAP = `# Roadmap: Tenant data-quality metrics in Admin UI (v30.1)
+
+**Milestone:** v30.1 — Tenant data-quality metrics in Admin UI
+
+## Overview
+
+Single-milestone roadmap. Version is only in the title and the bold line.
+
+### Phase 1: Metrics schema
+### Phase 2: Admin UI surface
+`;
+
+    it('detectActiveMilestone resolves v25.1 from the ad-hoc heading', () => {
+      assert.equal(detectActiveMilestone(ADHOC_ROADMAP), 'v25.1');
+    });
+
+    it('detectActiveMilestone prefers the In-Progress heading over an ad-hoc branch (no hijack)', () => {
+      assert.equal(detectActiveMilestone(MULTI_MILESTONE_WITH_BOLD), 'v2.0');
+    });
+
+    it('detectActiveMilestone leaves the bold-line branch unchanged', () => {
+      assert.equal(detectActiveMilestone(BOLD_LINE_ROADMAP), 'v30.1');
+    });
+
+    it('cmdJobsMilestonePreview auto-detects v25.1 from an ad-hoc roadmap', () => {
+      fixture = createFixture({
+        'ROADMAP.md': ADHOC_ROADMAP_WITH_PHASE,
+        'phases/01-first-ad-hoc-phase/01-01-PLAN.md': '',
+      });
+
+      const result = cmdJobsMilestonePreview(fixture.cwd, null, true, false);
+      assert.equal(result.version, 'v25.1');
+    });
+  });
+
   // ─── findJobFile Tests ──────────────────────────────────────────────────
 
   describe('findJobFile', () => {
@@ -1986,10 +2180,11 @@ Plans:
       assert.deepEqual(result.completed, []);
     });
 
-    it('returns jobs grouped by status with correct fields', () => {
+    it('groups FLAT jobs by frontmatter status with correct fields', () => {
+      // Flat layout: jobs/milestone-*.md grouped by parsed status header.
       fixture = createFixture({
-        'jobs/in-progress/milestone-v6.0.md': WELL_FORMED_JOB,
-        'jobs/completed/milestone-v5.0.md': ALL_COMPLETED_JOB,
+        'jobs/milestone-v6.0.md': WELL_FORMED_JOB,
+        'jobs/milestone-v5.0.md': ALL_COMPLETED_JOB,
       });
       const result = listJobs(fixture.cwd);
 
@@ -2011,6 +2206,40 @@ Plans:
       assert.equal(comp.progress, '2/2');
     });
 
+    it('still lists legacy-subdir jobs (back-compat)', () => {
+      fixture = createFixture({
+        'jobs/in-progress/milestone-v6.0.md': WELL_FORMED_JOB,
+        'jobs/completed/milestone-v5.0.md': ALL_COMPLETED_JOB,
+      });
+      const result = listJobs(fixture.cwd);
+
+      assert.equal(result.in_progress.length, 1);
+      assert.equal(result.completed.length, 1);
+      assert.equal(result.in_progress[0].version, 'v6.0');
+      assert.equal(result.completed[0].version, 'v5.0');
+    });
+
+    it('dedupes a job present both flat and in a legacy subdir (by version)', () => {
+      fixture = createFixture({
+        'jobs/milestone-v6.0.md': WELL_FORMED_JOB,
+        'jobs/in-progress/milestone-v6.0.md': WELL_FORMED_JOB,
+      });
+      const result = listJobs(fixture.cwd);
+      assert.equal(result.in_progress.length, 1, 'flat + legacy same version should dedupe to 1');
+      assert.equal(result.in_progress[0].version, 'v6.0');
+    });
+
+    it('creates no legacy subdirs (read-only on the filesystem)', () => {
+      fixture = createFixture({
+        'jobs/milestone-v6.0.md': WELL_FORMED_JOB,
+      });
+      listJobs(fixture.cwd);
+
+      assert.equal(fs.existsSync(path.join(fixture.cwd, 'jobs', 'pending')), false);
+      assert.equal(fs.existsSync(path.join(fixture.cwd, 'jobs', 'in-progress')), false);
+      assert.equal(fs.existsSync(path.join(fixture.cwd, 'jobs', 'completed')), false);
+    });
+
     it('shows check flag false when --no-check was used', () => {
       fixture = createFixture({
         'jobs/completed/milestone-v5.0.md': ALL_COMPLETED_JOB,
@@ -2182,18 +2411,46 @@ Plans:
       assert.equal(result.job_count, 0);
     });
 
-    it('returns healthy: false listing issues for missing directories, then auto-creates them', () => {
+    it('does not create legacy subdirs and stays healthy when they are absent', () => {
       fixture = createFixture({
         '': null,
       });
       const result = healthCheck(fixture.cwd);
 
-      // Should report missing directories but auto-create them
+      // An empty project (no legacy subdirs) is healthy with no jobs.
+      assert.equal(result.healthy, true);
+      assert.equal(result.job_count, 0);
       assert.ok(Array.isArray(result.directories));
-      // After auto-create, directories should exist
-      assert.ok(fs.existsSync(path.join(fixture.cwd, 'jobs', 'pending')));
-      assert.ok(fs.existsSync(path.join(fixture.cwd, 'jobs', 'in-progress')));
-      assert.ok(fs.existsSync(path.join(fixture.cwd, 'jobs', 'completed')));
+      // Legacy subdirs must NOT be auto-created.
+      assert.equal(fs.existsSync(path.join(fixture.cwd, 'jobs', 'pending')), false);
+      assert.equal(fs.existsSync(path.join(fixture.cwd, 'jobs', 'in-progress')), false);
+      assert.equal(fs.existsSync(path.join(fixture.cwd, 'jobs', 'completed')), false);
+    });
+
+    it('reports healthy: true for a flat jobs layout and does not create legacy subdirs', () => {
+      fixture = createFixture({
+        'jobs/milestone-v6.0.md': WELL_FORMED_JOB,
+      });
+      const result = healthCheck(fixture.cwd);
+
+      assert.equal(result.healthy, true);
+      assert.equal(result.job_count, 1);
+      assert.equal(result.issues.length, 0);
+      // No legacy subdirs created for a flat layout.
+      assert.equal(fs.existsSync(path.join(fixture.cwd, 'jobs', 'pending')), false);
+      assert.equal(fs.existsSync(path.join(fixture.cwd, 'jobs', 'in-progress')), false);
+      assert.equal(fs.existsSync(path.join(fixture.cwd, 'jobs', 'completed')), false);
+    });
+
+    it('excludes job-*-SUMMARY.md files from job_count in a flat layout', () => {
+      fixture = createFixture({
+        'jobs/milestone-v6.0.md': WELL_FORMED_JOB,
+        'jobs/job-v6.0-SUMMARY.md': '# Summary',
+      });
+      const result = healthCheck(fixture.cwd);
+
+      assert.equal(result.job_count, 1);
+      assert.equal(result.healthy, true);
     });
 
     it('validates each job file parses successfully; reports parse failures as issues', () => {
@@ -2546,14 +2803,14 @@ describe('jobs root-layout', () => {
     
   });
 
-  it('healthCheck creates jobs dirs at root layout', () => {
+  it('healthCheck does not create legacy subdirs at root layout', () => {
     fixture = createTempProject({ layout: 'root' });
     const result = healthCheck(fixture.cwd);
-    assert.ok(result.directories.length >= 3);
-    // Verify dirs were created at root
-    assert.ok(fs.existsSync(path.join(fixture.cwd, 'jobs', 'pending')));
-    assert.ok(fs.existsSync(path.join(fixture.cwd, 'jobs', 'in-progress')));
-    assert.ok(fs.existsSync(path.join(fixture.cwd, 'jobs', 'completed')));
+    assert.equal(result.healthy, true);
+    // Legacy subdirs must NOT be auto-created.
+    assert.equal(fs.existsSync(path.join(fixture.cwd, 'jobs', 'pending')), false);
+    assert.equal(fs.existsSync(path.join(fixture.cwd, 'jobs', 'in-progress')), false);
+    assert.equal(fs.existsSync(path.join(fixture.cwd, 'jobs', 'completed')), false);
   });
 
   it('listJobs works in root layout', () => {

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

@@ -8,7 +8,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { safeReadFile, getProjectFolders, output, error, getProjectDir } = require('./core.cjs');
+const { safeReadFile, getProjectFolders, output, error, getProjectDir, isValidMilestoneVersion } = require('./core.cjs');
 const { parseProjectsMd, readProjectState } = require('./projects.cjs');
 const { parseReposMd, resolveFileToRepo } = require('./repos.cjs');
 
@@ -32,18 +32,28 @@ function scanProjectPlanFiles(cwd, slug) {
   const phasesDir = path.join(getProjectDir(cwd, slug), 'phases');
   const results = [];
 
+  // Per-milestone versioned layout: descend a single vN.N child dir if present
+  // (phases/<version>/NN-slug). Detect via core.isValidMilestoneVersion — no
+  // parallel version regex. No version child → stay flat (back-compat).
+  let scanRoot = phasesDir;
   try {
-    const phaseDirs = fs.readdirSync(phasesDir, { withFileTypes: true })
+    const kids = fs.readdirSync(scanRoot, { withFileTypes: true });
+    const vd = kids.find(e => e.isDirectory() && isValidMilestoneVersion(e.name));
+    if (vd) scanRoot = path.join(scanRoot, vd.name);
+  } catch {}
+
+  try {
+    const phaseDirs = fs.readdirSync(scanRoot, { withFileTypes: true })
       .filter(e => e.isDirectory())
       .map(e => e.name);
 
     // Exclude archived phase directories
     const activePhaseDirs = excludeArchivedPhases(
-      phaseDirs.map(d => path.join(phasesDir, d))
+      phaseDirs.map(d => path.join(scanRoot, d))
     ).map(d => path.basename(d));
 
     for (const phaseDir of activePhaseDirs) {
-      const fullPhaseDir = path.join(phasesDir, phaseDir);
+      const fullPhaseDir = path.join(scanRoot, phaseDir);
       let files;
       try {
         files = fs.readdirSync(fullPhaseDir)

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

@@ -85,6 +85,19 @@ describe('scanProjectPlanFiles', () => {
     assert.deepStrictEqual(result[0].files, ['web-app/src/app.js', 'web-app/src/index.js']);
   });
 
+  it('descends versioned phases/<version>/ layout (260628-p59)', () => {
+    createProject(tmpDir, 'project-a');
+    // Plan lives one level deeper, under phases/v25.0/01-setup/
+    createPlanFile(tmpDir, 'project-a', 'v25.0/01-setup', '01-01-PLAN.md', [
+      { name: 'Task 1', files: ['web-app/src/index.js'], repos: ['web-app'] },
+    ]);
+    const result = scanProjectPlanFiles(tmpDir, 'project-a');
+    assert.strictEqual(result.length, 1, 'plan under phases/v25.0/ must be found');
+    assert.deepStrictEqual(result[0].repos, ['web-app']);
+    assert.deepStrictEqual(result[0].files, ['web-app/src/index.js']);
+    assert.strictEqual(result[0].plan, '01-setup/01-01-PLAN.md');
+  });
+
   it('handles plans with multiple tasks', () => {
     createProject(tmpDir, 'project-a');
     createPlanFile(tmpDir, 'project-a', '01-setup', '01-01-PLAN.md', [

package/deliver-great-systems/bin/lib/package-scan-report.cjs

@@ -25,6 +25,7 @@ const fs = require('fs');
 const path = require('path');
 const { getPlanningRoot } = require('./paths.cjs');
 const { getLocalConfigPath } = require('./config.cjs');
+const { isValidMilestoneVersion } = require('./core.cjs');
 
 // ─── Canonical frontmatter constants ─────────────────────────────────────────
 // Every findings[] entry emitted by this module carries these two constant
@@ -886,6 +887,24 @@ function _resolveReportPath(cwd, opts) {
         const phaseEntries = fs.readdirSync(phasesDir, { withFileTypes: true });
         for (const phEnt of phaseEntries) {
           if (!phEnt.isDirectory()) continue;
+          // Per-milestone versioned layout: the immediate child is a vN.N dir, so
+          // the active phase lives one level deeper (phases/<version>/NN-slug).
+          // Detect via core.isValidMilestoneVersion (no parallel version regex)
+          // and match the active phase among the version dir's children.
+          if (isValidMilestoneVersion(phEnt.name)) {
+            const versionDir = path.join(phasesDir, phEnt.name);
+            let candidates;
+            try { candidates = fs.readdirSync(versionDir, { withFileTypes: true }); } catch { continue; }
+            for (const cand of candidates) {
+              if (!cand.isDirectory()) continue;
+              if (cand.name === activeContext) {
+                const cm = cand.name.match(/^(\d+)/);
+                const cprefix = cm ? cm[1] : cand.name;
+                return path.join(versionDir, cand.name, cprefix + '-PACKAGE-SCAN.md');
+              }
+            }
+            continue;
+          }
           if (phEnt.name === activeContext) {
             const m = phEnt.name.match(/^(\d+)/);
             const prefix = m ? m[1] : phEnt.name;

package/deliver-great-systems/bin/lib/package-scan-report.test.cjs

@@ -494,6 +494,24 @@ describe('_resolveReportPath — tier 1 (active phase)', () => {
     }
   });
 
+  test('active_context resolves under versioned phases/<version>/ layout (260628-p59)', () => {
+    tmpDir = setupPlanningRoot({
+      local: {
+        current_project: 'gsd',
+        execution: { active_context: '03-foo' },
+      },
+    });
+    // Phase dir lives one level deeper, under phases/v25.0/03-foo
+    const versionedPhaseDir = path.join(tmpDir, 'projects', 'gsd', 'phases', 'v25.0', '03-foo');
+    fs.mkdirSync(versionedPhaseDir, { recursive: true });
+    try {
+      const resolved = _resolveReportPath(tmpDir, {});
+      assert.equal(resolved, path.join(versionedPhaseDir, '03-PACKAGE-SCAN.md'));
+    } finally {
+      cleanup(tmpDir);
+    }
+  });
+
   test('active_context points at a phase that does NOT exist → falls through', () => {
     tmpDir = setupPlanningRoot({
       local: {

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

@@ -381,14 +381,22 @@ function cmdPhaseAdd(cwd, description, raw) {
     updatedContent = content + phaseEntry;
   }
 
-  // Update milestone summary range (e.g., "Phases 124-128" -> "Phases 124-129")
-  const rangePattern = /Phases\s+(\d+)-(\d+)\s*\(in progress\)/;
+  // Update milestone summary range. Handles both the legacy non-namespaced form
+  // ("Phases 124-128" -> "Phases 124-129") and the per-milestone-namespaced form
+  // ("Phases v25.1/1-9" -> "Phases v25.1/1-10"). In the live namespaced layout the
+  // START endpoint carries the `vX.Y/` prefix while the END endpoint is BARE
+  // (e.g. start "v25.1/1", end "9"), so the prefix is derived from whichever
+  // endpoint carries it; the START (rangeMatch[1]) is preserved verbatim and the
+  // rebuilt END reuses the END endpoint's own prefix (empty in the live form).
+  const rangePattern = /Phases\s+((?:v\d+\.\d+\/)?\d+)\s*-\s*((?:v\d+\.\d+\/)?\d+)\s*\(in progress\)/i;
   const rangeMatch = updatedContent.match(rangePattern);
   if (rangeMatch) {
-    const rangeEnd = parseInt(rangeMatch[2], 10);
+    const endRaw = rangeMatch[2];                          // e.g. "9" (bare) or "v25.1/9"
+    const prefix = (endRaw.match(/^v\d+\.\d+\//) || [''])[0];
+    const rangeEnd = parseInt(endRaw.replace(/^v\d+\.\d+\//, ''), 10);
     if (newPhaseNum > rangeEnd) {
       updatedContent = updatedContent.replace(rangePattern,
-        `Phases ${rangeMatch[1]}-${newPhaseNum} (in progress)`);
+        `Phases ${rangeMatch[1]}-${prefix}${newPhaseNum} (in progress)`);
     }
   }
 

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

@@ -585,3 +585,72 @@ describe('cmdPhaseInitVersionedDir (NUM-02 versioned write path)', () => {
     }
   });
 });
+
+describe('cmdPhaseAdd milestone-summary range bump', () => {
+  let phase;
+
+  beforeEach(() => {
+    resetPaths();
+    delete require.cache[require.resolve('./phase.cjs')];
+    phase = require('./phase.cjs');
+  });
+
+  afterEach(() => {
+    resetPaths();
+  });
+
+  it('bumps a namespaced "Phases v25.1/1-9 (in progress)" range to v25.1/1-10, preserving the prefix', () => {
+    // maxPhase resolves to 9 from the `### Phase 9:` heading → newPhaseNum=10.
+    const roadmap = `# Roadmap
+
+- 🚧 **v25.1 add-prs** -- Phases v25.1/1-9 (in progress)
+
+## Phases
+
+### Phase 9: Ninth
+**Goal:** done
+
+---
+`;
+    const fixture = createFixture({ 'config.json': JSON.stringify({}), 'ROADMAP.md': roadmap });
+    try {
+      captureStdout(() => phase.cmdPhaseAdd(fixture.cwd, 'Tenth phase', false));
+      const updated = fs.readFileSync(path.join(fixture.cwd, 'ROADMAP.md'), 'utf-8');
+      assert.ok(
+        updated.includes('Phases v25.1/1-10 (in progress)'),
+        `expected namespaced bump to v25.1/1-10, got:\n${updated}`
+      );
+      // Prefix preserved on the START endpoint; END stays bare (no v25.1/ on the 10).
+      assert.ok(!/Phases v25\.1\/1-v25\.1\/10/.test(updated), 'END endpoint must stay bare');
+      assert.ok(!updated.includes('Phases v25.1/1-9 (in progress)'), 'old range must be gone');
+    } finally {
+      fixture.cleanup();
+    }
+  });
+
+  it('bumps a legacy non-namespaced "Phases 124-129 (in progress)" range to 124-130 (regression)', () => {
+    const roadmap = `# Roadmap
+
+- 🚧 **v19.0 Git Worktrees** -- Phases 124-129 (in progress)
+
+## Phases
+
+### Phase 129: One-twenty-nine
+**Goal:** done
+
+---
+`;
+    const fixture = createFixture({ 'config.json': JSON.stringify({}), 'ROADMAP.md': roadmap });
+    try {
+      captureStdout(() => phase.cmdPhaseAdd(fixture.cwd, 'One thirty', false));
+      const updated = fs.readFileSync(path.join(fixture.cwd, 'ROADMAP.md'), 'utf-8');
+      assert.ok(
+        updated.includes('Phases 124-130 (in progress)'),
+        `expected legacy bump to 124-130, got:\n${updated}`
+      );
+      assert.ok(!updated.includes('Phases 124-129 (in progress)'), 'old range must be gone');
+    } finally {
+      fixture.cleanup();
+    }
+  });
+});

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

@@ -8,7 +8,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { safeReadFile, getProjectFolders, generateSlugInternal, isV2Install, output, error, loadConfig, getProjectDir } = require('./core.cjs');
+const { safeReadFile, getProjectFolders, generateSlugInternal, isV2Install, output, error, loadConfig, getProjectDir, isValidMilestoneVersion } = require('./core.cjs');
 const { writeConfigField } = require('./config.cjs');
 const { getPlanningRoot } = require('./paths.cjs');
 
@@ -126,13 +126,23 @@ function scanProjectReposTags(cwd, slug) {
   const phasesDir = path.join(getProjectDir(cwd, slug), 'phases');
   const allRepos = new Set();
 
+  // Per-milestone versioned layout: descend a single vN.N child dir if present
+  // (phases/<version>/NN-slug). Detect via core.isValidMilestoneVersion — no
+  // parallel version regex. No version child → stay flat (back-compat).
+  let scanRoot = phasesDir;
   try {
-    const phaseDirs = fs.readdirSync(phasesDir, { withFileTypes: true })
+    const kids = fs.readdirSync(scanRoot, { withFileTypes: true });
+    const vd = kids.find(e => e.isDirectory() && isValidMilestoneVersion(e.name));
+    if (vd) scanRoot = path.join(scanRoot, vd.name);
+  } catch {}
+
+  try {
+    const phaseDirs = fs.readdirSync(scanRoot, { 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(scanRoot, phaseDir);
       let planFiles;
       try {
         planFiles = fs.readdirSync(fullPhaseDir)

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

@@ -320,6 +320,14 @@ describe('scanProjectReposTags', () => {
     const repos = scanProjectReposTags(tmpDir, 'proj');
     assert.deepStrictEqual(repos, []);
   });
+
+  it('descends versioned phases/<version>/ layout (260628-p59)', () => {
+    createProjectManually(tmpDir, 'proj', '# State\n');
+    // Plan lives one level deeper, under phases/v25.0/01-setup/
+    createPlanFile(tmpDir, 'proj', 'v25.0/01-setup', '01-01-PLAN.md', '<repos>server</repos>\n');
+    const repos = scanProjectReposTags(tmpDir, 'proj');
+    assert.deepStrictEqual(repos, ['server']);
+  });
 });
 
 // ─── regenerateProjectsMd ───────────────────────────────────────────────────

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

@@ -188,6 +188,20 @@ function cmdRoadmapAnalyze(cwd, raw) {
       version: 'v' + mMatch[2],
     });
   }
+  // Bold-line single-milestone fallback: a `**Milestone:** vX.Y` roadmap has no
+  // `## vX.Y` heading, so the scan above yields []. Fire ONLY when the heading
+  // scan produced zero milestones — the `milestones.length === 0` guard is the
+  // over-match gate, so any roadmap that already has `##` version headings (incl.
+  // the `## Active Milestone:` ad-hoc heading, already matched above) ignores it.
+  if (milestones.length === 0) {
+    const bold = content.match(/^\*\*Milestone:\*\*\s*(v\d+\.\d+)([^\n]*)/im);
+    if (bold) {
+      milestones.push({
+        heading: ('Milestone: ' + bold[1] + bold[2]).trim(),
+        version: bold[1],
+      });
+    }
+  }
 
   // Find current and next phase
   const currentPhase = phases.find(p => p.disk_status === 'planned' || p.disk_status === 'partial') || null;
@@ -268,17 +282,24 @@ function roadmapUpdatePlanProgressInternal(cwd, phaseNum) {
   }
 
   let roadmapContent = fs.readFileSync(roadmapPath, 'utf-8');
-  const phaseEscaped = escapeRegex(phaseNum);
-
-  // Progress table row: update Plans column (summaries/plans) and Status column
+  // Derive a BARE numeric phase key by stripping any leading `vX.Y/` prefix.
+  // Checklist lines and detail headings are always bare, so the bare key drives
+  // the heading/checkbox regexes; the progress-row matcher allows an optional
+  // version prefix and Milestone column on top of the same bare key.
+  const bareKey = String(phaseNum).replace(/^v\d+\.\d+\//, '');
+  const phaseEscaped = escapeRegex(bareKey);
+
+  // Progress table row: update Plans column (summaries/plans) and Status column.
+  // Format-agnostic: optional `vX.Y/` prefix on the Phase cell and an optional
+  // Milestone column (a pure-version cell) between Phase and Plans, both preserved.
   const tablePattern = new RegExp(
-    `(\\|\\s*${phaseEscaped}\\.?\\s[^|]*\\|)[^|]*(\\|)\\s*[^|]*(\\|)\\s*[^|]*(\\|)`,
+    `(\\|\\s*(?:v\\d+\\.\\d+/)?${phaseEscaped}\\.?\\s[^|]*\\|)(\\s*v\\d+\\.\\d+\\s*\\|)?[^|]*(\\|)\\s*[^|]*(\\|)\\s*[^|]*(\\|)`,
     'i'
   );
   const dateField = isComplete ? ` ${today} ` : '  ';
   roadmapContent = roadmapContent.replace(
     tablePattern,
-    `$1 ${summaryCount}/${planCount} $2 ${status.padEnd(11)}$3${dateField}$4`
+    `$1$2 ${summaryCount}/${planCount} $3 ${status.padEnd(11)}$4${dateField}$5`
   );
 
   // Update plan count in phase detail section