@ktpartners/dgs-platform 3.4.2 → 3.5.1

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

@@ -11,7 +11,7 @@ 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');
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 
@@ -774,3 +774,223 @@ describe('cmdListTodos flat-first scanning', () => {
     }
   });
 });
+
+// ─── findPhaseInternal ambiguity surfacing (LOOK-01 callers) ──────────────────
+
+describe('findPhaseInternal ambiguity surfacing (LOOK-01 callers)', () => {
+  // Captures stderr + the error()-driven process.exit so a guarded caller's
+  // milestone-qualified message is inspectable without killing the test worker.
+  // error() (core.cjs) writes to process.stderr then process.exit(1).
+  function captureError(fn) {
+    const chunks = [];
+    const origStderr = process.stderr.write.bind(process.stderr);
+    const origStdout = process.stdout.write.bind(process.stdout);
+    const origExit = process.exit;
+    let exitCode = null;
+    let threw = null;
+    process.stderr.write = (data) => { chunks.push(String(data)); return true; };
+    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__') threw = e;
+    } finally {
+      process.stderr.write = origStderr;
+      process.stdout.write = origStdout;
+      process.exit = origExit;
+    }
+    return { output: chunks.join(''), exitCode, threw };
+  }
+
+  // Build a v2 project where bare "03" is NOT an active phase but exists in TWO
+  // milestone archives — the cross-milestone collision case.
+  function ambiguousFixture() {
+    return createFixture({
+      'config.json': JSON.stringify({}),
+      'config.local.json': JSON.stringify({ current_project: 'auth-overhaul' }),
+      'PROJECTS.md': '# Projects\n\n| Project | Status |\n',
+      'REPOS.md': '# Repos\n\n| Name | Path |\n',
+      'projects/auth-overhaul/PROJECT.md': '# Project',
+      'projects/auth-overhaul/STATE.md': '---\ncurrent_milestone: v25.0\n---\n# State',
+      'projects/auth-overhaul/ROADMAP.md': '# Roadmap',
+      'projects/auth-overhaul/phases/': null,
+      'milestones/v3.0-phases/03-alpha/01-PLAN.md': '# Plan',
+      'milestones/v4.0-phases/03-beta/01-PLAN.md': '# Plan',
+    });
+  }
+
+  it('cmdPlanFinalize (commands.cjs:623 path) surfaces the milestone-qualified message, not a TypeError or silent resolution', () => {
+    const commands = require('./commands.cjs');
+    const fixture = ambiguousFixture();
+    try {
+      const { output, exitCode, threw } = captureError(() =>
+        commands.cmdPlanFinalize(fixture.cwd, '03', '01', {}, true)
+      );
+      // Must NOT crash with a TypeError (the pre-hardening failure mode).
+      assert.equal(threw, null, threw ? `unexpected throw: ${threw.stack}` : 'no throw');
+      // The guard fired with error() → exit(1).
+      assert.equal(exitCode, 1, 'guarded caller exits via error()');
+      // The milestone-qualified ambiguity message surfaced, naming both versions.
+      assert.ok(output.includes('v3.0'), `output names v3.0: ${output}`);
+      assert.ok(output.includes('v4.0'), `output names v4.0: ${output}`);
+      assert.ok(/ambiguous/i.test(output), `output flags ambiguity: ${output}`);
+      // NOT silently resolved to one archive directory.
+      assert.ok(!output.includes('03-alpha'), 'must not silently resolve to v3.0 dir');
+      assert.ok(!output.includes('03-beta'), 'must not silently resolve to v4.0 dir');
+    } finally {
+      fixture.cleanup();
+    }
+  });
+});
+
+// ─── cmdHistoryDigest composite key (LOOK-02) ──────────────────────────────────
+//
+// Documented output shape (composite {milestone, phase} key, string encoding):
+//   - When an entry carries a milestone (archived dirs, or current-phase entries
+//     once the current milestone is resolvable via resolveMilestoneVersion), the
+//     bucket key is `"<milestone>/<phase>"` (e.g. `digest.phases['v4.0/03']`).
+//   - When an entry has no resolvable milestone (flat-layout repos), the key is the
+//     bare phase number (e.g. `digest.phases['03']`) — byte-identical to the
+//     pre-LOOK-02 shape, so flat installs see no data loss and no key change.
+//   - decisions[] entries carry both `phase` and `milestone` so two milestones'
+//     same-numbered decisions are never ambiguous.
+describe('cmdHistoryDigest composite key (LOOK-02)', () => {
+  const { cmdHistoryDigest } = require('./commands.cjs');
+
+  // Build a fixture with TWO milestone archives that BOTH contain a phase "03",
+  // plus a current active phase. STATE.md carries current_milestone so the
+  // current-phase entry resolves to that milestone.
+  function twoMilestoneFixture(currentMilestone) {
+    const structure = {
+      'config.json': JSON.stringify({}),
+      'config.local.json': JSON.stringify({ planningRoot: '.' }),
+      'PROJECT.md': '# Project\n',
+      'ROADMAP.md': '# Roadmap\n',
+      'PROJECTS.md': '# Projects\n',
+      'REPOS.md': '# Repos\n',
+      'STATE.md':
+        '---\n' +
+        'dgs_state_version: 1.0\n' +
+        (currentMilestone ? `current_milestone: ${currentMilestone}\n` : '') +
+        'milestone: v5.0\n' +
+        '---\n\n# Project State\n\nPhase: 7\n',
+      // v3.0 archive, phase 03 → provides A
+      'milestones/v3.0-phases/v3.0-ROADMAP.md': '# v3.0\n',
+      'milestones/v3.0-phases/03-alpha/03-SUMMARY.md':
+        '---\nphase: "03"\nname: "Alpha"\nprovides:\n  - "A"\nkey-decisions:\n  - "Decision Alpha"\n---\n',
+      // v4.0 archive, phase 03 → provides B
+      'milestones/v4.0-phases/v4.0-ROADMAP.md': '# v4.0\n',
+      'milestones/v4.0-phases/03-beta/03-SUMMARY.md':
+        '---\nphase: "03"\nname: "Beta"\nprovides:\n  - "B"\nkey-decisions:\n  - "Decision Beta"\n---\n',
+      // current active phase 07 → provides Current
+      'phases/07-current/07-SUMMARY.md':
+        '---\nphase: "07"\nname: "Current"\nprovides:\n  - "Current"\n---\n',
+    };
+    return createFixture(structure);
+  }
+
+  function runDigest(cwd) {
+    const { json } = captureStdout(() => cmdHistoryDigest(cwd, false));
+    assert.ok(json, 'digest JSON emitted');
+    return json;
+  }
+
+  it('Test 1 (no conflation): restarted "03" from two milestones lands in DISTINCT buckets', () => {
+    const fixture = twoMilestoneFixture('v5.0');
+    try {
+      const digest = runDigest(fixture.cwd);
+      const v3 = digest.phases['v3.0/03'];
+      const v4 = digest.phases['v4.0/03'];
+      assert.ok(v3, "v3.0/03 bucket exists");
+      assert.ok(v4, "v4.0/03 bucket exists");
+      // v3.0 bucket has A, NOT B; v4.0 bucket has B, NOT A.
+      assert.ok(v3.provides.includes('A'), `v3.0/03 provides A: ${JSON.stringify(v3.provides)}`);
+      assert.ok(!v3.provides.includes('B'), 'v3.0/03 must NOT contain B');
+      assert.ok(v4.provides.includes('B'), `v4.0/03 provides B: ${JSON.stringify(v4.provides)}`);
+      assert.ok(!v4.provides.includes('A'), 'v4.0/03 must NOT contain A');
+      // The old conflated bare bucket must NOT exist for these milestone entries.
+      assert.ok(!digest.phases['03'], 'no conflated bare "03" bucket for milestone entries');
+    } finally {
+      fixture.cleanup();
+    }
+  });
+
+  it('Test 2 (current phase carries milestone): current-phase entry keyed under current milestone', () => {
+    const fixture = twoMilestoneFixture('v5.0');
+    try {
+      const digest = runDigest(fixture.cwd);
+      assert.ok(digest.phases['v5.0/07'], 'current phase 07 keyed under v5.0');
+      assert.ok(
+        digest.phases['v5.0/07'].provides.includes('Current'),
+        'current phase provides surfaced under its milestone bucket'
+      );
+      // Must NOT be keyed under bare "07" (would mean milestone was not assigned).
+      assert.ok(!digest.phases['07'], 'current phase must not land in a bare "07" bucket');
+    } finally {
+      fixture.cleanup();
+    }
+  });
+
+  it('Test 3 (documented shape): keys use the "<milestone>/<phase>" encoding', () => {
+    const fixture = twoMilestoneFixture('v5.0');
+    try {
+      const digest = runDigest(fixture.cwd);
+      const keys = Object.keys(digest.phases);
+      assert.ok(keys.includes('v3.0/03'), `keys include v3.0/03: ${keys}`);
+      assert.ok(keys.includes('v4.0/03'), `keys include v4.0/03: ${keys}`);
+      assert.ok(keys.includes('v5.0/07'), `keys include v5.0/07: ${keys}`);
+      // Every milestone-qualified key matches the documented grammar.
+      for (const k of keys) {
+        assert.ok(/^(v\d+\.\d+\/.+|[^/]+)$/.test(k), `key '${k}' matches documented shape`);
+      }
+    } finally {
+      fixture.cleanup();
+    }
+  });
+
+  it('Test 4 (decisions carry milestone): decisions tagged so two milestones are not ambiguous', () => {
+    const fixture = twoMilestoneFixture('v5.0');
+    try {
+      const digest = runDigest(fixture.cwd);
+      const alpha = digest.decisions.find(d => d.decision === 'Decision Alpha');
+      const beta = digest.decisions.find(d => d.decision === 'Decision Beta');
+      assert.ok(alpha, 'Decision Alpha present');
+      assert.ok(beta, 'Decision Beta present');
+      assert.strictEqual(alpha.milestone, 'v3.0', 'Decision Alpha tagged with v3.0');
+      assert.strictEqual(beta.milestone, 'v4.0', 'Decision Beta tagged with v4.0');
+      assert.strictEqual(alpha.phase, '03', 'Decision Alpha keeps readable phase');
+    } finally {
+      fixture.cleanup();
+    }
+  });
+
+  it('Test 5 (flat-layout backward-compat): no milestone → bare phase key preserved', () => {
+    // Flat repo: no milestones/ archives, no current_milestone. Current phases
+    // must keep the byte-identical bare-number key shape (information preserved).
+    const fixture = createFixture({
+      'config.json': JSON.stringify({}),
+      'config.local.json': JSON.stringify({ planningRoot: '.' }),
+      'PROJECT.md': '# Project\n',
+      'ROADMAP.md': '# Roadmap\n',
+      'PROJECTS.md': '# Projects\n',
+      'REPOS.md': '# Repos\n',
+      'STATE.md': '# Project State\n\nPhase: 1\n',
+      'phases/01-foundation/01-SUMMARY.md':
+        '---\nphase: "01"\nname: "Foundation"\nprovides:\n  - "DB"\n---\n',
+      'phases/02-api/02-SUMMARY.md':
+        '---\nphase: "02"\nname: "API"\nprovides:\n  - "REST"\n---\n',
+    });
+    try {
+      const digest = runDigest(fixture.cwd);
+      assert.ok(digest.phases['01'], 'flat phase 01 keyed bare');
+      assert.ok(digest.phases['02'], 'flat phase 02 keyed bare');
+      assert.ok(digest.phases['01'].provides.includes('DB'), 'flat 01 provides preserved');
+      assert.ok(digest.phases['02'].provides.includes('REST'), 'flat 02 provides preserved');
+      // No spurious milestone-qualified keys in a flat repo.
+      assert.ok(!Object.keys(digest.phases).some(k => k.includes('/')), 'no milestone-qualified keys in flat repo');
+    } finally {
+      fixture.cleanup();
+    }
+  });
+});

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

@@ -526,15 +526,15 @@ function getMilestoneSummaries(cwd, planningRoot, currentPhaseNum) {
   const isDirInMilestone = getMilestonePhaseFilter(cwd);
 
   // Scan phases directory for milestone phases with summaries
-  let projectRoot;
+  const { phasesDir: resolvePhasesDir } = require('./core.cjs');
+  let phasesRel;
   try {
-    const { getProjectRoot } = require('./core.cjs');
-    projectRoot = getProjectRoot(cwd);
+    phasesRel = resolvePhasesDir(cwd);
   } catch {
-    projectRoot = path.relative(cwd, planningRoot) || '.';
+    phasesRel = path.join(path.relative(cwd, planningRoot) || '.', 'phases');
   }
 
-  const phasesDir = path.join(cwd, projectRoot, 'phases');
+  const phasesDir = path.join(cwd, phasesRel);
   if (!fs.existsSync(phasesDir)) return results;
 
   try {
@@ -561,7 +561,7 @@ function getMilestoneSummaries(cwd, planningRoot, currentPhaseNum) {
         const phaseFiles = fs.readdirSync(phasePath);
         const summaries = phaseFiles.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md');
         for (const summary of summaries) {
-          const relPath = toPosixPath(path.join(projectRoot, 'phases', dir, summary));
+          const relPath = toPosixPath(path.join(phasesRel, dir, summary));
           results.push({ path: relPath, category: 'milestone-summary' });
         }
       } catch {}

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

@@ -99,22 +99,22 @@ describe('parseTierDefinitions', () => {
     assert.equal(none.files.length, 0, 'none tier files should be empty');
   });
 
-  it('lite tier has 3 files (PROJECT.md, STATE.md, config.json)', () => {
+  it('lite tier has 4 files (PROJECT.md, PRODUCT-SUMMARY.md, STATE.md, config.json)', () => {
     const tiers = parseTierDefinitions();
     const lite = tiers.get('lite');
     assert.ok(Array.isArray(lite.files), 'lite tier files should be array');
-    assert.equal(lite.files.length, 3, 'lite tier should have 3 files');
+    assert.equal(lite.files.length, 4, 'lite tier should have 4 files');
     const paths = lite.files.map(f => f.path);
     assert.ok(paths.includes('PROJECT.md'), 'should include PROJECT.md');
     assert.ok(paths.includes('STATE.md'), 'should include STATE.md');
     assert.ok(paths.includes('config.json'), 'should include config.json');
   });
 
-  it('planning tier has 3 own files plus dynamic codebase glob', () => {
+  it('planning tier has 4 own files plus dynamic codebase glob', () => {
     const tiers = parseTierDefinitions();
     const planning = tiers.get('planning');
     assert.ok(Array.isArray(planning.files), 'planning tier files should be array');
-    assert.equal(planning.files.length, 3, 'planning tier should have 3 own files');
+    assert.equal(planning.files.length, 4, 'planning tier should have 4 own files');
     const paths = planning.files.map(f => f.path);
     assert.ok(paths.includes('ROADMAP.md'), 'should include ROADMAP.md');
     assert.ok(paths.includes('REQUIREMENTS.md'), 'should include REQUIREMENTS.md');
@@ -674,20 +674,20 @@ describe('resolveTierFiles', () => {
   it('returns lite files for lite tier', () => {
     const tiers = parseTierDefinitions();
     const result = resolveTierFiles('lite', tiers);
-    assert.equal(result.length, 3);
+    assert.equal(result.length, 4);
   });
 
   it('planning tier inherits lite files', () => {
     const tiers = parseTierDefinitions();
     const result = resolveTierFiles('planning', tiers);
-    // lite has 3, planning adds 3 more
-    assert.equal(result.length, 6, 'planning should have 6 static files (3 lite + 3 planning)');
+    // lite has 4, planning adds 4 more
+    assert.equal(result.length, 8, 'planning should have 8 static files (4 lite + 4 planning)');
   });
 
   it('execution tier inherits planning+lite files', () => {
     const tiers = parseTierDefinitions();
     const result = resolveTierFiles('execution', tiers);
-    // execution has files: [] itself but inherits from planning which has 6
-    assert.equal(result.length, 6, 'execution inherits all planning files');
+    // execution has files: [] itself but inherits from planning which has 8
+    assert.equal(result.length, 8, 'execution inherits all planning files');
   });
 });

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

@@ -289,18 +289,17 @@ function findPhaseInternal(cwd, phase) {
 
   const normalized = normalizePhaseName(phase);
 
-  // Resolve phases directory: project root or '.' fallback
-  let projectRoot;
+  // Resolve phases directory via canonical resolver; keep soft '.' fallback
+  let phasesRel;
   try {
-    projectRoot = getProjectRoot(cwd);
+    phasesRel = phasesDir(cwd);
   } catch {
-    projectRoot = '.';
+    phasesRel = 'phases';   // flat-layout fallback (== path.join('.', 'phases'))
   }
-  const phasesRel = path.join(projectRoot, 'phases');
-  const phasesDir = path.join(cwd, phasesRel);
+  const phasesAbs = path.join(cwd, phasesRel);
 
   // Search current phases first
-  const current = searchPhaseInDir(phasesDir, phasesRel, normalized);
+  const current = searchPhaseInDir(phasesAbs, phasesRel, normalized);
   if (current) return current;
 
   // Search archived milestone phases (newest first)
@@ -318,6 +317,12 @@ function findPhaseInternal(cwd, phase) {
       .reverse();
 
     const planRootRel = path.relative(cwd, planRoot);
+
+    // LOOK-01: collect ALL archive matches before deciding, instead of
+    // returning the first newest-first hit. Once phase numbers restart per
+    // milestone (Phase 165), a bare number can collide across several milestone
+    // archives; silently returning the newest is a correctness bug.
+    const collected = [];
     for (const archiveName of archiveDirs) {
       const version = archiveName.match(/^(v[\d.]+)-phases$/)[1];
       const archivePath = path.join(milestonesDir, archiveName);
@@ -325,9 +330,35 @@ function findPhaseInternal(cwd, phase) {
       const result = searchPhaseInDir(archivePath, relBase, normalized);
       if (result) {
         result.archived = version;
-        return result;
+        collected.push({ version, result });
       }
     }
+
+    // Branch on the collected count:
+    //  - 0 matches  → null (unchanged)
+    //  - 1 match    → return that match with .archived set — BYTE-IDENTICAL to
+    //                 the previous single-archive path. Flat-layout / globally-
+    //                 unique numbers always land here, so their behaviour is
+    //                 preserved exactly.
+    //  - 2+ matches → return a PINNED, NON-throwing structured ambiguity signal:
+    //                 { found:false, ambiguous:true, phase, matches:[{milestone,
+    //                 directory}...], message }. It carries NO top-level
+    //                 `directory` and NO single `archived` tag, so callers that
+    //                 guard on `!phaseInfo.found` treat it as not-found, while
+    //                 hardened callers surface its `message`. This object shape
+    //                 is part of findPhaseInternal's return contract.
+    if (collected.length === 0) return null;
+    if (collected.length === 1) return collected[0].result;
+
+    const versions = collected.map(c => c.version);
+    const newestVersion = [...versions].sort().reverse()[0];
+    return {
+      found: false,
+      ambiguous: true,
+      phase: normalized,
+      matches: collected.map(c => ({ milestone: c.version, directory: c.result.directory })),
+      message: `Phase ${normalized} is ambiguous across milestones ${versions.join(', ')} — use a milestone-qualified reference (e.g. ${newestVersion}/${normalized})`,
+    };
   } catch {}
 
   return null;
@@ -514,12 +545,122 @@ function getMilestoneInfo(cwd) {
   }
 }
 
+// ─── Authoritative milestone-version signal (Phase 163-01) ─────────────────────
+//
+// Grounding (verified 2026-06-25) — the canonical structured field name:
+//   - The field persisted in STATE.md frontmatter TODAY is `milestone:`
+//     (written by state.cjs buildStateFrontmatter, derived from the getMilestoneInfo
+//     ROADMAP prose scrape). `current_milestone` exists only in init.cjs JSON output
+//     (init.cjs:560), NOT as a persisted STATE.md field.
+//   - The spec/CONTEXT name the authoritative field `current_milestone`.
+//   - To honour the locked name WHILE staying compatible with what exists today,
+//     resolveMilestoneVersion reads `current_milestone` FIRST and falls back to
+//     `milestone` SECOND. Plan 02 standardises the writer on `current_milestone`.
+//
+// This is the structured-first, grammar-validated, FAIL-LOUD signal. It deliberately
+// does NOT trust getMilestoneInfo's `v1.0` default — that scrape is advisory only and
+// is consulted here solely for an optional mismatch warning.
+
+/** Canonical milestone-version grammar (RSLV-05): exactly `vN.N`, no trim, no flags. */
+const MILESTONE_VERSION_RE = /^v\d+\.\d+$/;
+
+/**
+ * Validate a milestone-version string against the canonical grammar `^v\d+\.\d+$`.
+ * Out-of-grammar values are rejected, never coerced. Does NOT trim — trimming is the
+ * caller's choice, so malformed (whitespace-padded) input is not silently masked.
+ *
+ * @param {*} value
+ * @returns {boolean}
+ */
+function isValidMilestoneVersion(value) {
+  return typeof value === 'string' && MILESTONE_VERSION_RE.test(value);
+}
+
+/**
+ * Resolve the current milestone version from the structured STATE.md frontmatter
+ * field (authoritative), validate it against the canonical grammar, and FAIL LOUD
+ * when it is required but undeterminable. NEVER defaults to or returns 'v1.0'.
+ *
+ * Read precedence within STATE.md frontmatter: `current_milestone` then `milestone`.
+ * On a STATE-vs-ROADMAP mismatch, warns to stderr and trusts STATE.
+ *
+ * @param {string} cwd - Working directory
+ * @param {{ required?: boolean }} [opts]
+ * @returns {string|null} The validated `vN.N` version, or null when undeterminable
+ *                        and not required.
+ * @throws {Error} when required is true and the version is undeterminable/invalid.
+ */
+function resolveMilestoneVersion(cwd, { required = false } = {}) {
+  const remediation =
+    "Cannot determine current milestone version — set 'current_milestone' " +
+    '(e.g. v25.0) in STATE.md frontmatter.';
+
+  // 1. Read STATE.md (structured, authoritative). Mirror getMilestoneInfo's
+  //    project-scoped read: project STATE.md first, then planning-root STATE.md.
+  let stateContent = null;
+  try {
+    const projectRoot = getProjectRoot(cwd);
+    stateContent = safeReadFile(path.join(cwd, projectRoot, 'STATE.md'));
+  } catch {
+    stateContent = null;
+  }
+  if (stateContent === null) {
+    stateContent = safeReadFile(path.join(getPlanningRoot(cwd), 'STATE.md'));
+  }
+
+  // 2. Local minimal frontmatter parse. Intentionally does NOT import the
+  //    frontmatter parser module to avoid a require cycle (that module requires this one).
+  let raw;
+  if (stateContent) {
+    const fmMatch = stateContent.match(/^---\n([\s\S]+?)\n---/);
+    if (fmMatch) {
+      const block = fmMatch[1];
+      const currentMatch = block.match(/^current_milestone:\s*["']?(\S+?)["']?\s*$/m);
+      const fallbackMatch = block.match(/^milestone:\s*["']?(\S+?)["']?\s*$/m);
+      raw = (currentMatch && currentMatch[1]) || (fallbackMatch && fallbackMatch[1]);
+    }
+  }
+
+  // 3-4. Valid grammar → optional advisory mismatch warning, then return.
+  if (isValidMilestoneVersion(raw)) {
+    try {
+      const advisory = getMilestoneInfo(cwd);
+      if (advisory && advisory.version && advisory.version !== raw) {
+        process.stderr.write(
+          `Warning: milestone version mismatch — STATE.md says ${raw} but ROADMAP ` +
+          `says ${advisory.version}. Trusting STATE.md (${raw}).\n`
+        );
+      }
+    } catch { /* advisory only — never block on the prose scrape */ }
+    return raw;
+  }
+
+  // 5-6. Present-but-invalid or absent → fail loud if required, else null.
+  //      The abandoned getMilestoneInfo default is deliberately NOT used here.
+  if (required) {
+    throw new Error(remediation);
+  }
+  return null;
+}
+
 /**
  * Returns a filter function that checks whether a phase directory belongs
- * to the current milestone based on ROADMAP.md phase headings.
+ * to the current milestone.
+ * Under versioned layout (phases/<version>/) membership is structural — every
+ * entry already belongs to the milestone — so this returns a pass-all predicate.
+ * Under flat layout (shared phases/) it returns a ROADMAP number-set predicate.
  * If no ROADMAP exists or no phases are listed, returns a pass-all filter.
  */
 function getMilestonePhaseFilter(cwd) {
+  // Versioned layout: phases/<version>/ is already milestone-scoped — every entry belongs to the milestone, so number-set filtering is redundant (NUM-04).
+  let versioned = false;
+  try { versioned = /^v\d+\.\d+$/.test(path.basename(phasesDir(cwd))); } catch { versioned = false; }
+  if (versioned) {
+    const passAll = () => true;
+    passAll.phaseCount = 0;
+    return passAll;
+  }
+
   const milestonePhaseNums = new Set();
   try {
     let roadmap;
@@ -662,6 +803,52 @@ function resolveProjectPath(cwd, relativePath) {
   return relativePath ? path.join(root, relativePath) : root;
 }
 
+/**
+ * Canonical resolver for the active-project phases directory.
+ *
+ * Returns the RELATIVE project-scoped phases path:
+ *   - v2 layout: 'projects/<slug>/phases'
+ *   - v1 / flat layout: 'phases'
+ *
+ * FAIL-LOUD: delegates to resolveProjectPath -> requireProjectRoot, which
+ * throws when there is no project root. Callers that want a soft fallback
+ * (e.g. flat-layout tooling) keep their own try/catch around this call —
+ * the fallback policy stays local to each call site, never buried here.
+ *
+ * This is the SINGLE seam for phases-path resolution, and it IS version-aware
+ * (Phase 165 / RSLV-04): when a 'phases/<version>' directory exists on disk under
+ * the active project — where <version> is the validated `vN.N` milestone signal
+ * (resolveMilestoneVersion, Phase 163) — it returns the RELATIVE versioned path
+ * 'phases/<version>'. Otherwise it falls back to flat 'phases'. The fallback is
+ * permanent and intentional (dual-mode cutover): pre-existing flat layouts and the
+ * in-flight milestone (no 'phases/<version>' dir on disk) resolve FLAT by design —
+ * versioning is never applied retroactively. The read path NEVER defaults to 'v1.0'
+ * and NEVER throws on an undeterminable version (it just resolves flat).
+ *
+ * Do not reintroduce ad-hoc path.join(...,'phases') sites — path-audit.test.cjs
+ * gates against that. The only phases-bearing joins below are path.join(base, version)
+ * (relative return) and the existsSync probe path.join(cwd, base, version); neither is
+ * a bare path.join(..., 'phases') literal, so the 164-05 gate stays satisfied.
+ *
+ * @param {string} cwd - Working directory
+ * @returns {string} Relative project-scoped phases path ('phases', 'projects/<slug>/phases',
+ *                   or the versioned '…/phases/<version>')
+ * @throws {Error} NO_CURRENT_PROJECT_V2 | PROJECT_NOT_FOUND | INVALID_PROJECT_NAME | PROJECT_COMPLETED
+ */
+function phasesDir(cwd) {
+  const base = resolveProjectPath(cwd, 'phases');   // RELATIVE, fail-loud (unchanged)
+  let version = null;
+  try {
+    version = resolveMilestoneVersion(cwd);          // non-required: validated vN.N or null, never throws, never v1.0
+  } catch {
+    version = null;                                  // read path never blocks on an undeterminable version
+  }
+  if (version && fs.existsSync(path.join(cwd, base, version))) {
+    return path.join(base, version);                 // versioned dir present → return RELATIVE versioned path
+  }
+  return base;                                       // dual-mode fallback: flat phases/ (incl. the in-flight v25.0)
+}
+
 /**
  * Check if a project is completed by reading its STATE.md directly.
  *
@@ -749,9 +936,12 @@ module.exports = {
   pathExistsInternal,
   generateSlugInternal,
   getMilestoneInfo,
+  isValidMilestoneVersion,
+  resolveMilestoneVersion,
   getMilestonePhaseFilter,
   toPosixPath,
   resolveProjectPath,
+  phasesDir,
   getProjectRoot,
   requireProjectRoot,
   isV2Install,