@ktpartners/dgs-platform 3.4.2 → 3.5.0

package/CHANGELOG.md

@@ -8,6 +8,20 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [3.5.0] - 2026-06-27
+
+### Added — v25.0 Per-Milestone Phase Numbering via Directory Namespacing (Phases 163-170)
+- **Phase numbers now restart at `01` per milestone**, stored in version-namespaced directories `phases/<version>/NN-slug/` instead of one global flat `phases/`. The product-global version sequence (`vX.Y`) is unchanged — only phase *numbers* became milestone-local. Pre-existing flat-layout projects keep working (dual-mode), so no migration is forced.
+- **Authoritative version signal** — the active milestone version is sourced from STATE.md `current_milestone` (grammar-validated `^v\d+\.\d+$`, fail-loud, never silently defaulting to `v1.0`); the ROADMAP marker is advisory, and on mismatch the resolver warns and trusts STATE.md. `new-milestone` + `init.cjs` are the sole setters.
+- **Canonical version-aware resolver** — a single `phasesDir(cwd)` returns `phases/<version>/` when that directory exists and falls back to flat `phases/` otherwise, consolidating phase-path logic that was previously duplicated across the init/commands/context/state/phase/roadmap/jobs/governance/milestone modules.
+- **Version-aware lookup, state context, and structural archival**, with dual-mode (versioned + legacy-flat) test fixtures and the full library test suite greened.
+
+### Added
+- **Ad-hoc milestones support the full phase lifecycle (quick-260627-mv4)** — `milestone create-adhoc` now atomically seeds the planning scaffolding it previously skipped: it writes `current_milestone` to STATE.md, creates the versioned `phases/<version>/` directory, and seeds an `## Active Milestone` ROADMAP section. A hand-added phase therefore flows through `/dgs:add-phase` → `plan-phase` → `execute-phase` inside an ad-hoc container, with no requirements/roadmapper ceremony. `abandon-milestone` mirrors the teardown (removes the seeded versioned dir and restores the docs), and the three new artifacts fold into create-adhoc's existing atomic rollback so a failed creation leaves no residue.
+
+### Fixed
+- **Workflow-discipline hook self-heals stale installs (quick-260627-o37)** — the installer's PreToolUse registration now upgrades an existing `dgs-enforce-discipline` entry whose matcher lacks `Bash` by appending `|Bash` in place, instead of only adding the entry when absent. Previously a machine that installed before the `Bash` matcher existed kept the stale `Edit|Write|Skill` matcher forever — the marker-on-init branch never fired for inline `/dgs:*` flows, so Edit/Write was falsely blocked, and `/dgs:update` could not fix it. Idempotent once `Bash` is present.
+
 ## [3.4.2] - 2026-06-25
 
 ### Fixed

package/README.md

@@ -612,6 +612,8 @@ See the [User Guide](docs/USER-GUIDE.md#context-tiers) for the complete command-
 
 ### Testing & Dependency Scanning
 
+Run the full automated test suite (repo-root `tests/` plus the nested `deliver-great-systems/bin/lib/` library tree) with a single command: `npm test`. To run only the library tree: `npm run test:lib`.
+
 | Command | What it does |
 |---------|--------------|
 | `/dgs:package-scan [--threshold critical\|high\|medium\|low] [--repo <name>] [--json] [--include-dev-deps\|--no-include-dev-deps]` | Scan every registered repo + product root for known dependency vulnerabilities and licence issues. Cascades Snyk → OSV-Scanner → ecosystem-native tool (`npm audit`, `pip-audit`, `govulncheck`, `bundler-audit`). Report is committed to the active phase dir, active milestone dir, or a timestamped project-root file. See `deliver-great-systems/references/package-scan-config.md` for config keys and installation. |

package/agents/dgs-codebase-cross-analyzer.md

@@ -11,7 +11,7 @@ You are a DGS codebase cross-analyzer. You read per-repo codebase documents and
 You are spawned by `/dgs:map-codebase` after all synthesizer agents have completed. There is one cross-analyzer instance per mapping run.
 
 You receive these prompt variables from the orchestrator:
-- **codebase_dir**: Path to the codebase directory (e.g., `.planning/codebase`)
+- **codebase_dir**: Path to the codebase directory (e.g., `codebase/` under the planning root)
 - **repo_names**: JSON array of repo names that were mapped (e.g., `["business", "newarch"]`)
 
 Your job: Read per-repo maps, compare across repos, write CROSS-REPO.md with comparison tables, return confirmation only.

package/agents/dgs-codebase-mapper.md

@@ -156,7 +156,7 @@ Read key files identified during exploration. Use Glob and Grep with paths under
 <step name="write_documents">
 Write document(s) to `${codebase_dir}/` using the templates below.
 
-**Note:** `${codebase_dir}` is set by the orchestrator and already includes the repo subdirectory path (e.g., `.planning/codebase/business/`). Write directly to it.
+**Note:** `${codebase_dir}` is set by the orchestrator and already includes the repo subdirectory path (e.g., `codebase/business/`). Write directly to it.
 
 **Document naming:** UPPERCASE.md (e.g., STACK.md, ARCHITECTURE.md)
 

package/agents/dgs-codebase-synthesizer.md

@@ -11,7 +11,7 @@ You are a DGS codebase synthesizer. You read per-repo codebase documents and pro
 You are spawned by `/dgs:map-codebase` after all per-repo mapper agents have completed. Each synthesizer instance handles one document type.
 
 You receive these prompt variables from the orchestrator:
-- **codebase_dir**: Path to the codebase directory (e.g., `.planning/codebase`)
+- **codebase_dir**: Path to the codebase directory (e.g., `codebase/` under the planning root)
 - **repo_names**: List of repo names that were mapped (e.g., `["business", "newarch"]`)
 - **doc_type**: Which document to synthesize (one of: ARCHITECTURE, STACK, STRUCTURE, CONVENTIONS, TESTING, INTEGRATIONS, CONCERNS)
 

package/agents/dgs-phase-researcher.md

@@ -306,7 +306,7 @@ Verified patterns from official sources:
 
 ## Validation Architecture
 
-> Skip this section entirely if workflow.nyquist_validation is explicitly set to false in .planning/config.json. If the key is absent, treat as enabled.
+> Skip this section entirely if workflow.nyquist_validation is explicitly set to false in `${config_path}`. If the key is absent, treat as enabled.
 
 ### Test Framework
 | Property | Value |

package/bin/install.js

@@ -1816,11 +1816,11 @@ function install(isGlobal, runtime = 'claude') {
       settings.hooks.PreToolUse = [];
     }
 
-    const hasDisciplineHook = settings.hooks.PreToolUse.some(entry =>
+    const disciplineHookEntry = settings.hooks.PreToolUse.find(entry =>
       entry.hooks && entry.hooks.some(h => h.command && h.command.includes('dgs-enforce-discipline'))
     );
 
-    if (!hasDisciplineHook) {
+    if (!disciplineHookEntry) {
       settings.hooks.PreToolUse.push({
         matcher: 'Edit|Write|Skill|Bash',
         hooks: [
@@ -1831,6 +1831,16 @@ function install(isGlobal, runtime = 'claude') {
         ]
       });
       console.log(`  ${green}✓${reset} Configured workflow discipline hook`);
+    } else if (
+      typeof disciplineHookEntry.matcher === 'string' &&
+      !disciplineHookEntry.matcher.split('|').includes('Bash')
+    ) {
+      // Self-heal stale installs: older versions registered this matcher without
+      // Bash, so the marker-on-init branch never fired for inline /dgs:* flows and
+      // Edit/Write got falsely blocked. Upgrade the existing entry in place so a
+      // plain /dgs:update fixes it. Idempotent once Bash is present.
+      disciplineHookEntry.matcher = disciplineHookEntry.matcher + '|Bash';
+      console.log(`  ${green}✓${reset} Upgraded workflow discipline hook matcher (added Bash)`);
     }
 
     // Configure PostToolUse hook for discipline marker cleanup (Skill completion)

package/deliver-great-systems/bin/dgs-tools.cjs

@@ -15,6 +15,7 @@
  *   state patch --field val ...        Batch update STATE.md fields
  *   state archive-quick-tasks          Archive excess quick task rows to HISTORY.md
  *   state mark-milestone-complete      Mark milestone complete in STATE.md
+ *   state reconcile-milestone          Self-heal a shipped-but-not-flipped STATE.md
  *   resolve-model <agent-type>         Get model for agent based on profile
  *   find-phase <phase>                 Find phase directory by number
  *   commit <message> [--files f1 f2]   Commit planning docs
@@ -37,6 +38,7 @@
  * Phase Operations:
  *   phase next-decimal <phase>         Calculate next decimal phase number
  *   phase add <description>            Append new phase to roadmap + create dir
+ *   phase init-versioned-dir           Create current milestone's phases/<version>/ (fail-loud; new-milestone only)
  *   phase insert <after> <description> Insert decimal phase after existing
  *   phase remove <phase> [--force]     Remove phase, renumber all subsequent
  *   phase complete <phase>             Mark phase done, update state + roadmap
@@ -708,6 +710,8 @@ async function main() {
         state.cmdStateArchiveQuickTasks(cwd, raw);
       } else if (subcommand === 'mark-milestone-complete') {
         state.cmdMarkMilestoneComplete(cwd, raw);
+      } else if (subcommand === 'reconcile-milestone') {
+        state.cmdReconcileMilestone(cwd, raw);
       } else if (subcommand === 'read-adhoc') {
         state.cmdStateReadAdhoc(cwd, raw);
       } else if (subcommand === 'adhoc-readiness') {
@@ -1178,6 +1182,8 @@ async function main() {
         phase.cmdPhaseNextDecimal(cwd, args[2], raw);
       } else if (subcommand === 'add') {
         phase.cmdPhaseAdd(cwd, args.slice(2).join(' '), raw);
+      } else if (subcommand === 'init-versioned-dir') {
+        phase.cmdPhaseInitVersionedDir(cwd, raw);
       } else if (subcommand === 'insert') {
         phase.cmdPhaseInsert(cwd, args[2], args.slice(3).join(' '), raw);
       } else if (subcommand === 'remove') {
@@ -1189,7 +1195,7 @@ async function main() {
         const push = args.includes('--push');
         phase.cmdPhaseFinalize(cwd, args[2], { push }, raw);
       } else {
-        error('Unknown phase subcommand. Available: next-decimal, add, insert, remove, complete, finalize');
+        error('Unknown phase subcommand. Available: next-decimal, add, init-versioned-dir, insert, remove, complete, finalize');
       }
       break;
     }

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

@@ -4,7 +4,7 @@
 const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
-const { safeReadFile, loadConfig, isGitIgnored, execGit, normalizePhaseName, comparePhaseNum, getArchivedPhaseDirs, generateSlugInternal, getMilestoneInfo, getProjectRoot, resolveModelInternal, MODEL_PROFILES, toPosixPath, output, error, findPhaseInternal } = require('./core.cjs');
+const { safeReadFile, loadConfig, isGitIgnored, execGit, normalizePhaseName, comparePhaseNum, getArchivedPhaseDirs, generateSlugInternal, getMilestoneInfo, getProjectRoot, phasesDir, resolveMilestoneVersion, resolveModelInternal, MODEL_PROFILES, toPosixPath, output, error, findPhaseInternal } = require('./core.cjs');
 const { extractFrontmatter, spliceFrontmatter, reconstructFrontmatter } = require('./frontmatter.cjs');
 const { getPlanningRoot } = require('./paths.cjs');
 
@@ -146,15 +146,35 @@ function cmdVerifyPathExists(cwd, targetPath, raw) {
 }
 
 function cmdHistoryDigest(cwd, raw) {
-  let phasesDir;
+  let phasesAbs;
   try {
-    const projectRoot = getProjectRoot(cwd);
-    phasesDir = path.join(cwd, projectRoot, 'phases');
+    phasesAbs = path.join(cwd, phasesDir(cwd));
   } catch {
-    phasesDir = path.join(getPlanningRoot(cwd), 'phases');
+    phasesAbs = path.join(getPlanningRoot(cwd), 'phases');
   }
   const digest = { phases: {}, decisions: [], tech_stack: new Set() };
 
+  // Output shape (LOOK-02, composite {milestone, phase} key):
+  //   Phases are keyed by a composite of milestone + phase number so a restarted
+  //   phase number that exists in two milestones is NEVER conflated into one bucket.
+  //   - Milestone-qualified entries (archived dirs, and current-phase entries once
+  //     the current milestone is resolvable) → key = "<milestone>/<phase>"
+  //       e.g. digest.phases['v4.0/03']
+  //   - Entries with no resolvable milestone (flat-layout repos) → key = "<phase>"
+  //       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` (readable) and `milestone` so two
+  //   milestones' same-numbered decisions are unambiguous.
+
+  // Resolve the current milestone once (non-required: validated vN.N or null,
+  // never throws on a read path — flat repos must keep working).
+  let currentMilestone = null;
+  try {
+    currentMilestone = resolveMilestoneVersion(cwd);
+  } catch {
+    currentMilestone = null;
+  }
+
   // Collect all phase directories: archived + current
   const allPhaseDirs = [];
 
@@ -164,15 +184,16 @@ function cmdHistoryDigest(cwd, raw) {
     allPhaseDirs.push({ name: a.name, fullPath: a.fullPath, milestone: a.milestone });
   }
 
-  // Add current phases
-  if (fs.existsSync(phasesDir)) {
+  // Add current phases — assign the current milestone (archived entries already
+  // carry their own milestone; current entries are milestone: null until now).
+  if (fs.existsSync(phasesAbs)) {
     try {
-      const currentDirs = fs.readdirSync(phasesDir, { withFileTypes: true })
+      const currentDirs = fs.readdirSync(phasesAbs, { withFileTypes: true })
         .filter(e => e.isDirectory())
         .map(e => e.name)
         .sort();
       for (const dir of currentDirs) {
-        allPhaseDirs.push({ name: dir, fullPath: path.join(phasesDir, dir), milestone: null });
+        allPhaseDirs.push({ name: dir, fullPath: path.join(phasesAbs, dir), milestone: currentMilestone });
       }
     } catch {}
   }
@@ -184,7 +205,7 @@ function cmdHistoryDigest(cwd, raw) {
   }
 
   try {
-    for (const { name: dir, fullPath: dirPath } of allPhaseDirs) {
+    for (const { name: dir, fullPath: dirPath, milestone } of allPhaseDirs) {
       const summaries = fs.readdirSync(dirPath).filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md');
 
       for (const summary of summaries) {
@@ -193,9 +214,12 @@ function cmdHistoryDigest(cwd, raw) {
           const fm = extractFrontmatter(content);
 
           const phaseNum = fm.phase || dir.split('-')[0];
+          // Composite key: "<milestone>/<phase>" when a milestone is present,
+          // else the bare phase number (flat-layout byte-identical behaviour).
+          const phaseKey = milestone ? `${milestone}/${phaseNum}` : phaseNum;
 
-          if (!digest.phases[phaseNum]) {
-            digest.phases[phaseNum] = {
+          if (!digest.phases[phaseKey]) {
+            digest.phases[phaseKey] = {
               name: fm.name || dir.split('-').slice(1).join(' ') || 'Unknown',
               provides: new Set(),
               affects: new Set(),
@@ -205,25 +229,26 @@ function cmdHistoryDigest(cwd, raw) {
 
           // Merge provides
           if (fm['dependency-graph'] && fm['dependency-graph'].provides) {
-            fm['dependency-graph'].provides.forEach(p => digest.phases[phaseNum].provides.add(p));
+            fm['dependency-graph'].provides.forEach(p => digest.phases[phaseKey].provides.add(p));
           } else if (fm.provides) {
-            fm.provides.forEach(p => digest.phases[phaseNum].provides.add(p));
+            fm.provides.forEach(p => digest.phases[phaseKey].provides.add(p));
           }
 
           // Merge affects
           if (fm['dependency-graph'] && fm['dependency-graph'].affects) {
-            fm['dependency-graph'].affects.forEach(a => digest.phases[phaseNum].affects.add(a));
+            fm['dependency-graph'].affects.forEach(a => digest.phases[phaseKey].affects.add(a));
           }
 
           // Merge patterns
           if (fm['patterns-established']) {
-            fm['patterns-established'].forEach(p => digest.phases[phaseNum].patterns.add(p));
+            fm['patterns-established'].forEach(p => digest.phases[phaseKey].patterns.add(p));
           }
 
-          // Merge decisions
+          // Merge decisions — tag with milestone so two milestones' same-numbered
+          // decisions are unambiguous; keep `phase` for readability.
           if (fm['key-decisions']) {
             fm['key-decisions'].forEach(d => {
-              digest.decisions.push({ phase: phaseNum, decision: d });
+              digest.decisions.push({ milestone: milestone || null, phase: phaseNum, decision: d });
             });
           }
 
@@ -622,7 +647,10 @@ function cmdPlanFinalize(cwd, phaseNum, planNum, options, raw) {
 
   // Resolve phase dir via findPhaseInternal (returns phases/NN-name relative path)
   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,
+  // so a bare `!phaseInfo` guard would deref undefined and crash. Surface its
+  // milestone-qualified message instead.
+  if (!phaseInfo || !phaseInfo.found) error(phaseInfo?.message || `Phase ${phaseNum} not found`);
   const phaseDir = path.join(cwd, phaseInfo.directory);
 
   // Locate PLAN.md + SUMMARY.md within the phase dir using `${phaseNum}-${planNum}` prefix
@@ -862,15 +890,15 @@ async function cmdWebsearch(query, options, raw) {
 }
 
 function cmdProgressRender(cwd, format, raw) {
-  let phasesDir, roadmapPath;
+  let phasesAbs, roadmapPath;
   try {
     const projectRoot = getProjectRoot(cwd);
     const projectAbs = path.join(cwd, projectRoot);
-    phasesDir = path.join(projectAbs, 'phases');
+    phasesAbs = path.join(cwd, phasesDir(cwd));
     roadmapPath = path.join(projectAbs, 'ROADMAP.md');
   } catch {
     const planRoot = getPlanningRoot(cwd);
-    phasesDir = path.join(planRoot, 'phases');
+    phasesAbs = path.join(planRoot, 'phases');
     roadmapPath = path.join(planRoot, 'ROADMAP.md');
   }
   const milestone = getMilestoneInfo(cwd);
@@ -880,14 +908,14 @@ function cmdProgressRender(cwd, format, raw) {
   let totalSummaries = 0;
 
   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((a, b) => comparePhaseNum(a, b));
 
     for (const dir of dirs) {
       const dm = dir.match(/^(\d+(?:\.\d+)*)-?(.*)/);
       const phaseNum = dm ? dm[1] : dir;
       const phaseName = dm && dm[2] ? dm[2].replace(/-/g, ' ') : '';
-      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') || f === 'PLAN.md').length;
       const summaries = phaseFiles.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md').length;
 
@@ -1029,10 +1057,12 @@ function cmdScaffold(cwd, type, options, raw) {
 
   // Find phase directory
   const phaseInfo = phase ? findPhaseInternal(cwd, phase) : null;
-  const phaseDir = phaseInfo ? path.join(cwd, phaseInfo.directory) : null;
+  // Gate phaseDir on `found`+`directory`: a LOOK-01 ambiguity object is truthy
+  // but carries no .directory, so `path.join(cwd, undefined)` would throw.
+  const phaseDir = (phaseInfo && phaseInfo.found && phaseInfo.directory) ? path.join(cwd, phaseInfo.directory) : null;
 
   if (phase && !phaseDir && type !== 'phase-dir') {
-    error(`Phase ${phase} directory not found`);
+    error(phaseInfo?.message || `Phase ${phase} directory not found`);
   }
 
   let filePath, content;
@@ -1059,12 +1089,19 @@ function cmdScaffold(cwd, type, options, raw) {
       }
       const slug = generateSlugInternal(name);
       const dirName = `${padded}-${slug}`;
-      const phasesParent = path.join(getPlanningRoot(cwd), 'phases');
+      const planRootRel = path.relative(cwd, getPlanningRoot(cwd)) || '.';
+      // RSLV-03 residue (Phase 170): create the phase dir through the canonical
+      // version-aware resolver so the dir we CREATE is the dir we REPORT. Under a
+      // versioned layout this mkdir's phases/<version>/NN-slug/, not the flat root.
+      let phasesRel;
+      try { phasesRel = phasesDir(cwd); }
+      catch { phasesRel = path.join(planRootRel, 'phases'); }
+      const phasesParent = path.join(cwd, phasesRel);
       fs.mkdirSync(phasesParent, { recursive: true });
       const dirPath = path.join(phasesParent, dirName);
       fs.mkdirSync(dirPath, { recursive: true });
-      const planRootRel = path.relative(cwd, getPlanningRoot(cwd)) || '.';
-      output({ created: true, directory: path.join(planRootRel, 'phases', dirName), path: dirPath }, raw, dirPath);
+      const dirRel = path.join(phasesRel, dirName);
+      output({ created: true, directory: dirRel, path: dirPath }, raw, dirPath);
       return;
     }
     default:

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 {}