@ktpartners/dgs-platform 3.5.0 → 3.5.3

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

@@ -0,0 +1,86 @@
+/**
+ * Tests for roadmap.cjs::cmdRoadmapAnalyze milestone enumeration.
+ *
+ * Focus: the bold-line single-milestone fallback (`**Milestone:** vX.Y`) that
+ * fires ONLY when the `## vX.Y` heading scan yields zero milestones, gated by
+ * `milestones.length === 0` so it never double-counts a heading roadmap.
+ *
+ * Invokes the dgs-tools.cjs CLI via execSync against isolated temp fixtures
+ * (mirrors init.test.cjs's CLI-invocation style).
+ */
+
+const { describe, it, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+const { execSync } = require('child_process');
+const path = require('path');
+
+const { createFixture } = require('./test-helpers.cjs');
+
+// Path to CLI entry point
+const CLI = path.resolve(__dirname, '..', 'dgs-tools.cjs');
+
+/**
+ * Run `dgs-tools roadmap analyze --raw` in a fixture and return parsed JSON.
+ */
+function runAnalyze(cwd) {
+  const stdout = execSync(`node "${CLI}" roadmap analyze --raw`, {
+    cwd,
+    encoding: 'utf-8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+  return JSON.parse(stdout.trim());
+}
+
+describe('cmdRoadmapAnalyze milestone enumeration', () => {
+  let fixture;
+
+  afterEach(() => {
+    if (fixture) fixture.cleanup();
+  });
+
+  // Single-milestone roadmap whose version lives only in the title + bold line —
+  // there is NO `## vX.Y` heading, so the heading scan yields [].
+  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.
+
+### Phase 1: Metrics schema
+**Goal:** Define metrics tables
+
+### Phase 2: Admin UI surface
+**Goal:** Surface metrics in admin
+`;
+
+  // Classic multi-milestone heading roadmap WITH a stray bold line: the heading
+  // scan enumerates the `## vX.Y` headings; the bold fallback must stay inert.
+  const HEADING_ROADMAP = `# Roadmap
+
+**Milestone:** v9.9 — stray bold line that must NOT be enumerated
+
+## v1.0 Foundation
+### Phase 1: Base
+
+## v2.0 Next (In Progress)
+### Phase 2: New
+`;
+
+  it('enumerates a bold-line-only roadmap (>=1 milestone, correct version)', () => {
+    fixture = createFixture({ 'config.json': JSON.stringify({}), 'ROADMAP.md': BOLD_LINE_ROADMAP });
+    const result = runAnalyze(fixture.cwd);
+    assert.ok(result.milestones.length >= 1, 'expected at least one milestone');
+    assert.equal(result.milestones[0].version, 'v30.1');
+  });
+
+  it('still enumerates a `## vX.Y` heading roadmap via headings (bold fallback inert, no double-count)', () => {
+    fixture = createFixture({ 'config.json': JSON.stringify({}), 'ROADMAP.md': HEADING_ROADMAP });
+    const result = runAnalyze(fixture.cwd);
+    const versions = result.milestones.map(m => m.version);
+    assert.deepEqual(versions, ['v1.0', 'v2.0']);
+    // The stray bold line (v9.9) was NOT enumerated — the length===0 gate held.
+    assert.ok(!versions.includes('v9.9'), 'stray bold line must not be enumerated');
+  });
+});

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

@@ -161,8 +161,10 @@ function parseFrontmatter(content) {
 // ─── Content Scanners ───────────────────────────────────────────────────────
 
 /**
- * Scan ideas directories for searchable idea files.
- * Scans ideas/{pending,done,rejected}/ for .md files.
+ * Scan ideas for searchable idea files — flat-first.
+ * Reads flat ideas/*.md deriving `state` from frontmatter.status (mirror
+ * scanSpecs / cmdIdeasList). Legacy ideas/{pending,done,rejected}/ subdirs are
+ * an existence-gated dedup fallback so back-compat installs still surface.
  *
  * @param {string} cwd - Working directory
  * @param {object} options - { include_rejected, tags }
@@ -172,12 +174,60 @@ function scanIdeas(cwd, options) {
   const results = [];
   const planRoot = getPlanningRoot(cwd);
   const planRootRel = path.relative(cwd, planRoot) || '.';
-  const states = options.include_rejected
+  const includeRejected = !!options.include_rejected;
+  const seenIds = new Set();
+
+  // Tag filter: if tags option set, idea must have at least one matching tag (OR logic).
+  function tagMatches(tags) {
+    if (!options.tags) return true;
+    const filterTags = options.tags.split(',').map(t => t.trim().toLowerCase());
+    const ideaTags = tags.map(t => t.toLowerCase());
+    return filterTags.some(ft => ideaTags.includes(ft));
+  }
+
+  // Flat-first scan: ideas/*.md (excluding subdirs), state from frontmatter.status.
+  const flatDir = path.join(planRoot, 'ideas');
+  let flatFiles;
+  try {
+    flatFiles = fs.readdirSync(flatDir).filter(f => f.endsWith('.md')
+      && !fs.statSync(path.join(flatDir, f)).isDirectory());
+  } catch {
+    flatFiles = [];
+  }
+
+  for (const file of flatFiles) {
+    const content = safeReadFile(path.join(flatDir, file));
+    if (!content) continue;
+
+    const { frontmatter, body } = parseFrontmatter(content);
+    const state = frontmatter.status || 'pending';
+    if (!includeRejected && state === 'rejected') continue;
+
+    const tags = frontmatter.tags || [];
+    if (!tagMatches(tags)) continue;
+
+    results.push({
+      type: 'idea',
+      id: frontmatter.id,
+      title: frontmatter.title || file,
+      filePath: path.join(planRootRel, 'ideas', file),
+      state,
+      tags,
+      author: frontmatter.author || '',
+      content: (frontmatter.title || '') + ' ' + body,
+    });
+    if (frontmatter.id !== undefined) seenIds.add(frontmatter.id);
+  }
+
+  // Legacy subdir fallback (existence-gated, deduped by id).
+  const legacyStates = includeRejected
     ? ['pending', 'done', 'rejected']
     : ['pending', 'done'];
 
-  for (const state of states) {
-    const dir = path.join(planRoot, 'ideas', state);
+  for (const dirState of legacyStates) {
+    const dir = path.join(planRoot, 'ideas', dirState);
+    if (!fs.existsSync(dir)) continue;
+
     let files;
     try {
       files = fs.readdirSync(dir).filter(f => f.endsWith('.md'));
@@ -191,26 +241,22 @@ function scanIdeas(cwd, options) {
       if (!content) continue;
 
       const { frontmatter, body } = parseFrontmatter(content);
-      const tags = frontmatter.tags || [];
+      if (frontmatter.id !== undefined && seenIds.has(frontmatter.id)) continue;
 
-      // Tag filter: if tags option set, idea must have at least one matching tag (OR logic)
-      if (options.tags) {
-        const filterTags = options.tags.split(',').map(t => t.trim().toLowerCase());
-        const ideaTags = tags.map(t => t.toLowerCase());
-        const hasMatch = filterTags.some(ft => ideaTags.includes(ft));
-        if (!hasMatch) continue;
-      }
+      const tags = frontmatter.tags || [];
+      if (!tagMatches(tags)) continue;
 
       results.push({
         type: 'idea',
         id: frontmatter.id,
         title: frontmatter.title || file,
-        filePath: path.join(planRootRel, 'ideas', state, file),
-        state,
+        filePath: path.join(planRootRel, 'ideas', dirState, file),
+        state: frontmatter.status || dirState,
         tags,
         author: frontmatter.author || '',
         content: (frontmatter.title || '') + ' ' + body,
       });
+      if (frontmatter.id !== undefined) seenIds.add(frontmatter.id);
     }
   }
 
@@ -553,6 +599,7 @@ function cmdSearch(cwd, query, options, raw) {
 
 module.exports = {
   cmdSearch,
+  scanIdeas,
   fuzzyMatch,
   levenshteinDistance,
   matchesQuery,

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

@@ -0,0 +1,94 @@
+/**
+ * Tests for search.cjs scanIdeas — flat-first idea scanning.
+ *
+ * Verifies that scanIdeas reads the migrated flat layout (ideas/*.md with
+ * `status:` in frontmatter), honours include_rejected, and still surfaces
+ * legacy status-subdir ideas as an existence-gated fallback.
+ */
+
+const { describe, it, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+const { createFixture } = require('./test-helpers.cjs');
+const { resetPaths } = require('./paths.cjs');
+const { scanIdeas } = require('./search.cjs');
+
+function ideaContent(id, title, status, tags = []) {
+  const tagsStr = tags.length > 0 ? `[${tags.map(t => `"${t}"`).join(', ')}]` : '[]';
+  return `---\nid: ${id}\ntitle: "${title}"\nstatus: ${status}\ntags: ${tagsStr}\n---\n\n${title} body.\n`;
+}
+
+describe('search scanIdeas (flat-first)', () => {
+  let fixture;
+
+  afterEach(() => {
+    if (fixture) fixture.cleanup();
+    resetPaths();
+  });
+
+  it('finds flat-layout ideas with state derived from frontmatter.status', () => {
+    fixture = createFixture({
+      'ideas/001-alpha.md': ideaContent(1, 'Alpha', 'pending', ['api']),
+      'ideas/002-beta.md': ideaContent(2, 'Beta', 'done', ['ui']),
+    });
+
+    const results = scanIdeas(fixture.cwd, { include_rejected: false });
+    assert.equal(results.length, 2);
+
+    const byId = Object.fromEntries(results.map(r => [r.id, r]));
+    assert.equal(byId[1].state, 'pending');
+    assert.equal(byId[1].title, 'Alpha');
+    assert.equal(byId[2].state, 'done');
+    // filePath is the flat location — no status subdir segment.
+    assert.match(byId[1].filePath, /ideas[\\/]001-alpha\.md$/);
+    assert.ok(!byId[1].filePath.includes('pending'));
+  });
+
+  it('hides rejected flat ideas by default and includes them when requested', () => {
+    fixture = createFixture({
+      'ideas/001-alpha.md': ideaContent(1, 'Alpha', 'pending'),
+      'ideas/009-reject.md': ideaContent(9, 'Rejected idea', 'rejected'),
+    });
+
+    const hidden = scanIdeas(fixture.cwd, { include_rejected: false });
+    assert.equal(hidden.length, 1);
+    assert.equal(hidden[0].id, 1);
+
+    const shown = scanIdeas(fixture.cwd, { include_rejected: true });
+    assert.equal(shown.length, 2);
+    assert.ok(shown.some(r => r.id === 9 && r.state === 'rejected'));
+  });
+
+  it('still finds legacy subdir ideas (back-compat)', () => {
+    fixture = createFixture({
+      'ideas/pending/003-gamma.md': ideaContent(3, 'Gamma', 'pending'),
+    });
+
+    const results = scanIdeas(fixture.cwd, { include_rejected: false });
+    assert.equal(results.length, 1);
+    assert.equal(results[0].id, 3);
+    assert.equal(results[0].state, 'pending');
+    assert.match(results[0].filePath, /ideas[\\/]pending[\\/]003-gamma\.md$/);
+  });
+
+  it('dedupes a flat idea against a legacy subdir copy (by id)', () => {
+    fixture = createFixture({
+      'ideas/003-gamma.md': ideaContent(3, 'Gamma flat', 'pending'),
+      'ideas/pending/003-gamma.md': ideaContent(3, 'Gamma legacy', 'pending'),
+    });
+
+    const results = scanIdeas(fixture.cwd, { include_rejected: false });
+    assert.equal(results.length, 1);
+    assert.equal(results[0].title, 'Gamma flat');
+  });
+
+  it('applies the OR tag filter', () => {
+    fixture = createFixture({
+      'ideas/001-alpha.md': ideaContent(1, 'Alpha', 'pending', ['api']),
+      'ideas/002-beta.md': ideaContent(2, 'Beta', 'pending', ['ui']),
+    });
+
+    const results = scanIdeas(fixture.cwd, { include_rejected: false, tags: 'api' });
+    assert.equal(results.length, 1);
+    assert.equal(results[0].id, 1);
+  });
+});

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

@@ -5,7 +5,7 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-const { safeReadFile, normalizePhaseName, execGit, findPhaseInternal, getMilestoneInfo, output, error } = require('./core.cjs');
+const { safeReadFile, normalizePhaseName, execGit, findPhaseInternal, getMilestoneInfo, output, error, phasesDir } = require('./core.cjs');
 const { getPlanningRoot } = require('./paths.cjs');
 const { extractFrontmatter, parseMustHavesBlock } = require('./frontmatter.cjs');
 const { parseReposMd, validateRepoPaths } = require('./repos.cjs');
@@ -399,7 +399,15 @@ function cmdVerifyKeyLinks(cwd, planFilePath, raw) {
 function cmdValidateConsistency(cwd, raw) {
   const planRoot = getPlanningRoot(cwd);
   const roadmapPath = path.join(planRoot, 'ROADMAP.md');
-  const phasesDir = path.join(planRoot, 'phases');
+  // Resolve phases directory via the canonical version-aware resolver; keep the
+  // soft flat-layout fallback (matches core.findPhaseInternal). Under a versioned
+  // milestone layout this descends phases/<version>/ so diskPhases is populated.
+  // NB: join to planRoot (the git-resolved planning root used everywhere else in
+  // this function), NOT cwd — on macOS git realpaths /var → /private/var, so a
+  // cwd-based join would diverge from planRoot and break downstream path.relative.
+  let phasesRel;
+  try { phasesRel = phasesDir(cwd); } catch { phasesRel = 'phases'; }
+  const phasesAbs = path.join(planRoot, phasesRel);
   const errors = [];
   const warnings = [];
 
@@ -423,7 +431,7 @@ function cmdValidateConsistency(cwd, raw) {
   // Get phases on disk
   const diskPhases = new Set();
   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);
     for (const dir of dirs) {
       const dm = dir.match(/^(\d+[A-Z]?(?:\.\d+)?)/i);
@@ -460,11 +468,11 @@ function cmdValidateConsistency(cwd, raw) {
 
   // Check: plan numbering within phases
   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).sort();
 
     for (const dir of dirs) {
-      const phaseFiles = fs.readdirSync(path.join(phasesDir, dir));
+      const phaseFiles = fs.readdirSync(path.join(phasesAbs, dir));
       const plans = phaseFiles.filter(f => f.endsWith('-PLAN.md')).sort();
 
       // Extract plan numbers
@@ -495,15 +503,15 @@ function cmdValidateConsistency(cwd, raw) {
 
   // Check: frontmatter in plans has required fields
   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);
 
     for (const dir of dirs) {
-      const phaseFiles = fs.readdirSync(path.join(phasesDir, dir));
+      const phaseFiles = fs.readdirSync(path.join(phasesAbs, dir));
       const plans = phaseFiles.filter(f => f.endsWith('-PLAN.md'));
 
       for (const plan of plans) {
-        const content = fs.readFileSync(path.join(phasesDir, dir, plan), 'utf-8');
+        const content = fs.readFileSync(path.join(phasesAbs, dir, plan), 'utf-8');
         const fm = extractFrontmatter(content);
 
         if (!fm.wave) {
@@ -523,7 +531,16 @@ function cmdValidateHealth(cwd, options, raw) {
   const roadmapPath = path.join(planningDir, 'ROADMAP.md');
   const statePath = path.join(planningDir, 'STATE.md');
   const configPath = path.join(planningDir, 'config.json');
-  const phasesDir = path.join(planningDir, 'phases');
+  // Version-aware phases dir (descends phases/<version>/ when present) with the
+  // canonical soft flat-layout fallback. All checks below walk this root so the
+  // Check-12 W010 walker and consistency checks see versioned-layout phase dirs.
+  // NB: join to planningDir (the git-resolved root used by the W010 walker's
+  // path.relative + git ls-files), NOT cwd — on macOS git realpaths /var →
+  // /private/var, so a cwd-based join would diverge and mis-report tracked
+  // artifacts as untracked.
+  let phasesRel;
+  try { phasesRel = phasesDir(cwd); } catch { phasesRel = 'phases'; }
+  const phasesAbs = path.join(planningDir, phasesRel);
 
   const errors = [];
   const warnings = [];
@@ -577,7 +594,7 @@ function cmdValidateHealth(cwd, options, raw) {
     // Get disk phases
     const diskPhases = new Set();
     try {
-      const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+      const entries = fs.readdirSync(phasesAbs, { withFileTypes: true });
       for (const e of entries) {
         if (e.isDirectory()) {
           const m = e.name.match(/^(\d+(?:\.\d+)?)/);
@@ -619,7 +636,7 @@ function cmdValidateHealth(cwd, options, raw) {
 
   // ─── Check 6: Phase directory naming (NN-name format) ─────────────────────
   try {
-    const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+    const entries = fs.readdirSync(phasesAbs, { withFileTypes: true });
     for (const e of entries) {
       if (e.isDirectory() && !e.name.match(/^\d{2,}(?:\.\d+)*-[\w-]+$/)) {
         addIssue('warning', 'W005', `Phase directory "${e.name}" doesn't follow NN-name format`, 'Rename to match pattern (e.g., 01-setup)');
@@ -629,10 +646,10 @@ function cmdValidateHealth(cwd, options, raw) {
 
   // ─── Check 7: Orphaned plans (PLAN without SUMMARY) ───────────────────────
   try {
-    const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+    const entries = fs.readdirSync(phasesAbs, { withFileTypes: true });
     for (const e of entries) {
       if (!e.isDirectory()) continue;
-      const phaseFiles = fs.readdirSync(path.join(phasesDir, e.name));
+      const phaseFiles = fs.readdirSync(path.join(phasesAbs, e.name));
       const plans = phaseFiles.filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md');
       const summaries = phaseFiles.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md');
       const summaryBases = new Set(summaries.map(s => s.replace('-SUMMARY.md', '').replace('SUMMARY.md', '')));
@@ -659,7 +676,7 @@ function cmdValidateHealth(cwd, options, raw) {
 
     const diskPhases = new Set();
     try {
-      const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+      const entries = fs.readdirSync(phasesAbs, { withFileTypes: true });
       for (const e of entries) {
         if (e.isDirectory()) {
           const dm = e.name.match(/^(\d+[A-Z]?(?:\.\d+)?)/i);
@@ -756,7 +773,7 @@ function cmdValidateHealth(cwd, options, raw) {
         const trackingVerif = [];
         if (completedPhases.size > 0) {
           try {
-            const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+            const entries = fs.readdirSync(phasesAbs, { withFileTypes: true });
             for (const e of entries) {
               if (!e.isDirectory()) continue;
               const dm = e.name.match(/^(\d+[A-Z]?(?:\.\d+)*)/i);
@@ -764,10 +781,10 @@ function cmdValidateHealth(cwd, options, raw) {
               const phaseNum = dm[1];
               const unpadded = String(parseInt(phaseNum, 10));
               if (!completedPhases.has(phaseNum) && !completedPhases.has(unpadded)) continue;
-              const phaseFiles = fs.readdirSync(path.join(phasesDir, e.name));
+              const phaseFiles = fs.readdirSync(path.join(phasesAbs, e.name));
               for (const f of phaseFiles) {
                 if (/-VERIFICATION\.md$/i.test(f)) {
-                  trackingVerif.push(path.relative(gitRoot, path.join(phasesDir, e.name, f)));
+                  trackingVerif.push(path.relative(gitRoot, path.join(phasesAbs, e.name, f)));
                 }
               }
             }
@@ -858,12 +875,12 @@ function cmdValidateHealth(cwd, options, raw) {
   // the dangling artifact on the next /dgs:health run.
   try {
     const untracked = [];
-    if (fs.existsSync(phasesDir)) {
+    if (fs.existsSync(phasesAbs)) {
       const ARTIFACT_RE = /^[0-9].*-(PLAN|CONTEXT|RESEARCH|UAT|VERIFICATION)\.md$/;
-      const phaseEntries = fs.readdirSync(phasesDir, { withFileTypes: true });
+      const phaseEntries = fs.readdirSync(phasesAbs, { withFileTypes: true });
       for (const entry of phaseEntries) {
         if (!entry.isDirectory()) continue;
-        const phaseDirAbs = path.join(phasesDir, entry.name);
+        const phaseDirAbs = path.join(phasesAbs, entry.name);
         let files;
         try { files = fs.readdirSync(phaseDirAbs); } catch { continue; }
         for (const f of files) {

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

@@ -80,3 +80,61 @@ test('REL-12: cmdValidateHealth does NOT flag tracked .gitkeep files', () => {
 });
 
 // REL-12 sentinel — flag this block as a Wave-0 RED scaffold for plan 04.
+
+// ─── 260628-p59: versioned phases/<version>/ layout regression ──────────────
+// cmdValidateConsistency must descend phases/<version>/ (via core.phasesDir) so a
+// phase dir living under phases/v25.0/NN-slug is seen on disk and does NOT trigger
+// a spurious "Phase N in ROADMAP.md but no directory on disk" warning.
+
+function setupVersionedConsistencyFixture() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'p59-consist-'));
+  // getPlanningRoot requires a git repo (it process.exit(1)s otherwise, which would
+  // make the child shim emit empty stdout and falsely "pass"). Initialise one.
+  execSync('git init -q', { cwd: root });
+  execSync('git config user.email test@test', { cwd: root });
+  execSync('git config user.name test', { cwd: root });
+  fs.writeFileSync(path.join(root, 'STATE.md'), '---\nmilestone: v25.0\n---\n# State\n');
+  fs.writeFileSync(path.join(root, 'ROADMAP.md'), '# Roadmap\n\n### Phase 3: Foo\n');
+  const phaseDir = path.join(root, 'phases', 'v25.0', '03-foo');
+  fs.mkdirSync(phaseDir, { recursive: true });
+  fs.writeFileSync(path.join(phaseDir, '03-01-PLAN.md'),
+    '---\nphase: 3\nplan: 01\nwave: 1\n---\n# Plan\n');
+  return root;
+}
+
+function captureConsistencyOutput(root) {
+  // cmdValidateConsistency calls output() which process.exit(0)s — run in a child
+  // process and capture stdout JSON (mirrors captureHealthOutput above).
+  const verifyPath = path.resolve(__dirname, 'verify.cjs');
+  // cmdValidateConsistency passes a status word as output()'s third arg, so it
+  // must be called with raw=false to emit the JSON payload (not the status word).
+  const shim = [
+    `const v = require(${JSON.stringify(verifyPath)});`,
+    `v.cmdValidateConsistency(${JSON.stringify(root)}, false);`,
+  ].join('\n');
+  const shimPath = path.join(os.tmpdir(), `p59-consist-shim-${process.pid}-${Date.now()}.cjs`);
+  fs.writeFileSync(shimPath, shim);
+  try {
+    const stdout = execSync(`node ${JSON.stringify(shimPath)}`, { encoding: 'utf-8' });
+    try { return JSON.parse(stdout); } catch { return { stdout, warnings: [] }; }
+  } catch (err) {
+    const out = err.stdout && err.stdout.toString();
+    try { return JSON.parse(out); } catch { return { stdout: out, warnings: [] }; }
+  } finally {
+    try { fs.unlinkSync(shimPath); } catch { /* ignore */ }
+  }
+}
+
+test('260628-p59: cmdValidateConsistency descends phases/<version>/ (no spurious missing-directory warning)', () => {
+  const root = setupVersionedConsistencyFixture();
+  const result = captureConsistencyOutput(root);
+  // Guard against a silent false-pass: confirm the JSON payload actually parsed
+  // (a crashed child would yield {warnings: []} and trivially pass the filter).
+  assert.ok(Object.prototype.hasOwnProperty.call(result, 'passed'),
+    'expected a parsed consistency result with a `passed` field');
+  const missingDirWarnings = (result.warnings || []).filter(
+    w => /Phase 3 in ROADMAP.*no directory on disk/.test(w)
+  );
+  assert.strictEqual(missingDirWarnings.length, 0,
+    'phases/v25.0/03-foo should be seen on disk; no missing-directory warning expected');
+});

package/deliver-great-systems/references/git-integration.md

@@ -228,7 +228,7 @@ Each plan produces 2-4 commits (tasks + metadata). Clear, granular, bisectable.
 
 **Context engineering for AI:**
 - Git history becomes primary context source for future Claude sessions
-- `git log --grep="{phase}-{plan}"` shows all work for a plan
+- `git log $(git merge-base main HEAD)..HEAD --grep="{phase}-{plan}"` shows all work for a plan on the current milestone branch
 - `git diff <hash>^..<hash>` shows exact changes per task
 - Less reliance on parsing SUMMARY.md = more context for actual work
 

package/deliver-great-systems/workflows/audit-milestone.md

@@ -149,7 +149,7 @@ For each phase's VERIFICATION.md, extract the expanded requirements table:
 
 For each phase's SUMMARY.md, extract `requirements-completed` from YAML frontmatter:
 ```bash
-for summary in ${project_root}/phases/*-*/*-SUMMARY.md; do
+for summary in $(find ${project_root}/phases -name '*-SUMMARY.md' 2>/dev/null); do
   node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" summary-extract "$summary" --fields requirements_completed | jq -r '.requirements_completed'
 done
 ```

package/deliver-great-systems/workflows/cleanup.md

@@ -66,7 +66,7 @@ Extract phase numbers and names from the archived roadmap (e.g., Phase 1: Founda
 Check which of those phase directories still exist in `${project_root}/phases/`:
 
 ```bash
-ls -d ${project_root}/phases/*/ 2>/dev/null
+find ${project_root}/phases -mindepth 1 -maxdepth 2 -type d -name '[0-9]*-*' 2>/dev/null
 ```
 
 Match phase directories to milestone membership. Only include directories that still exist in `${project_root}/phases/`.

package/deliver-great-systems/workflows/codereview.md

@@ -21,7 +21,7 @@ Multi-agent code review that runs 3 passes of 3 parallel agents each (9 total re
 Compute the diff from the plan's task commits.
 
 ```bash
-FIRST_TASK_COMMIT=$(git -C "${CODE_REPO_PATH}" log --oneline --grep="feat(${PHASE}-${PLAN}):" --grep="fix(${PHASE}-${PLAN}):" --grep="test(${PHASE}-${PLAN}):" --grep="refactor(${PHASE}-${PLAN}):" --reverse | head -1 | cut -d' ' -f1)
+FIRST_TASK_COMMIT=$(git -C "${CODE_REPO_PATH}" log $(git -C "${CODE_REPO_PATH}" merge-base main HEAD)..HEAD --oneline --grep="feat(${PHASE}-${PLAN}):" --grep="fix(${PHASE}-${PLAN}):" --grep="test(${PHASE}-${PLAN}):" --grep="refactor(${PHASE}-${PLAN}):" --reverse | head -1 | cut -d' ' -f1)
 ```
 
 If FIRST_TASK_COMMIT is empty, exit with message: "No task commits found for ${PHASE}-${PLAN}, skipping code review."

package/deliver-great-systems/workflows/complete-milestone.md

@@ -433,7 +433,7 @@ If mark-milestone-complete fails, log a warning but continue to gather_stats (no
 Calculate milestone statistics:
 
 ```bash
-git log --oneline --grep="feat(" | head -20
+git log --oneline FIRST_COMMIT..LAST_COMMIT --grep="feat(" | head -20
 git diff --stat FIRST_COMMIT..LAST_COMMIT | tail -1
 find . -name "*.swift" -o -name "*.ts" -o -name "*.py" | xargs wc -l 2>/dev/null
 git log --format="%ai" FIRST_COMMIT | tail -1
@@ -461,7 +461,7 @@ Extract one-liners from SUMMARY.md files using summary-extract:
 
 ```bash
 # For each phase in milestone, extract one-liner
-for summary in ${project_root}/phases/*-*/*-SUMMARY.md; do
+for summary in ${phases_dir}/*/*-SUMMARY.md; do
   node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" summary-extract "$summary" --fields one_liner | jq -r '.one_liner'
 done
 ```
@@ -494,7 +494,7 @@ Full PROJECT.md evolution review at milestone completion.
 Read all phase summaries:
 
 ```bash
-cat ${project_root}/phases/*-*/*-SUMMARY.md
+cat ${phases_dir}/*/*-SUMMARY.md
 ```
 
 **Full review checklist:**

package/deliver-great-systems/workflows/discuss-phase.md

@@ -482,7 +482,11 @@ Use values from init: `phase_dir`, `phase_slug`, `padded_phase`.
 
 If `phase_dir` is null (phase exists in roadmap but no directory). Use `project_root` from init:
 ```bash
-mkdir -p "${project_root}/phases/${padded_phase}-${phase_slug}"
+# Resolve version-aware phases base (mirror phasesDir(): versioned -> phases/<version>/, flat -> phases/)
+PHASES_BASE="${project_root}/phases"
+VERSION_DIR=$(ls -d ${project_root}/phases/v[0-9]*.[0-9]*/ 2>/dev/null | tail -1)
+[ -n "$VERSION_DIR" ] && PHASES_BASE="${VERSION_DIR%/}"
+mkdir -p "${PHASES_BASE}/${padded_phase}-${phase_slug}"
 ```
 
 **File location:** `${phase_dir}/${padded_phase}-CONTEXT.md`

package/deliver-great-systems/workflows/execute-phase.md

@@ -377,7 +377,7 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
 
    For each SUMMARY.md:
    - Verify first 2 files from `key-files.created` exist on disk
-   - Check `git log --oneline --all --grep="{phase}-{plan}"` returns ≥1 commit
+   - Check `git log --oneline $(git merge-base main HEAD)..HEAD --grep="{phase}-{plan}"` returns ≥1 commit
    - Check for `## Self-Check: FAILED` marker
 
    If ANY spot-check fails: report which plan failed, route to failure handler.
@@ -450,7 +450,7 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
 
    Compute diff reference for the plan's task commits:
    ```bash
-   FIRST_TASK_COMMIT=$(git -C "${CODE_REPO_PATH}" log --oneline --grep="feat(${PHASE}-${PLAN}):" --grep="fix(${PHASE}-${PLAN}):" --grep="test(${PHASE}-${PLAN}):" --grep="refactor(${PHASE}-${PLAN}):" --reverse | head -1 | cut -d' ' -f1)
+   FIRST_TASK_COMMIT=$(git -C "${CODE_REPO_PATH}" log $(git -C "${CODE_REPO_PATH}" merge-base main HEAD)..HEAD --oneline --grep="feat(${PHASE}-${PLAN}):" --grep="fix(${PHASE}-${PLAN}):" --grep="test(${PHASE}-${PLAN}):" --grep="refactor(${PHASE}-${PLAN}):" --reverse | head -1 | cut -d' ' -f1)
    ```
 
    If FIRST_TASK_COMMIT is empty (no task commits found), skip codereview for this plan with message: "No task commits found for {phase}-{plan}, skipping code review."

package/deliver-great-systems/workflows/execute-plan.md

@@ -114,7 +114,7 @@ Pattern B only (verify-only checkpoints). Skip for A/C.
    - Main route: execute tasks using standard flow (step name="execute")
 3. After ALL segments: aggregate files/deviations/decisions → create SUMMARY.md → commit → self-check:
    - Verify key-files.created exist on disk with `[ -f ]`
-   - Check `git log --oneline --all --grep="{phase}-{plan}"` returns ≥1 commit
+   - Check `git log --oneline $(git merge-base main HEAD)..HEAD --grep="{phase}-{plan}"` returns ≥1 commit
    - Append `## Self-Check: PASSED` or `## Self-Check: FAILED` to SUMMARY
 
    **Known Claude Code bug (classifyHandoffIfNeeded):** If any segment agent reports "failed" with `classifyHandoffIfNeeded is not defined`, this is a Claude Code runtime bug — not a real failure. Run spot-checks; if they pass, treat as successful.
@@ -490,7 +490,7 @@ The plan name is auto-extracted from the PLAN.md `plan_name` frontmatter field (
 If ${project_root}/codebase/ doesn't exist: skip.
 
 ```bash
-FIRST_TASK=$(git log --oneline --grep="feat({phase}-{plan}):" --grep="fix({phase}-{plan}):" --grep="test({phase}-{plan}):" --reverse | head -1 | cut -d' ' -f1)
+FIRST_TASK=$(git log $(git merge-base main HEAD)..HEAD --oneline --grep="feat({phase}-{plan}):" --grep="fix({phase}-{plan}):" --grep="test({phase}-{plan}):" --reverse | head -1 | cut -d' ' -f1)
 git diff --name-only ${FIRST_TASK}^..HEAD 2>/dev/null
 ```
 

package/deliver-great-systems/workflows/pause-work.md

@@ -25,7 +25,7 @@ Find current phase directory from most recently modified files:
 
 ```bash
 # Find most recent phase directory with work
-ls -lt ${project_root}/phases/*/PLAN.md 2>/dev/null | head -1 | grep -oP 'phases/\K[^/]+'
+ls -t ${project_root}/phases/*/*-PLAN.md ${project_root}/phases/*/*/*-PLAN.md 2>/dev/null | head -1 | xargs -r dirname | xargs -r basename
 ```
 
 If no active phase detected, ask user which phase they're pausing work on.