@ktpartners/dgs-platform 3.4.2 → 3.5.1

package/CHANGELOG.md

@@ -8,6 +8,34 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [3.5.1] - 2026-06-28
+
+### Added
+- **`dgs-tools state reconcile-milestone` (quick-260627-m3k)** — self-heals a project whose milestone shipped (a `## <version>` heading in MILESTONES.md AND a matching git tag both present) but whose STATE.md was never flipped, so `/dgs:list-projects` stops showing a stale in-progress phase or false `executing` status. Conservative (no-op unless both shipped markers are present), idempotent, and current-project scoped.
+
+### Fixed
+- **Dashboard staleness after milestone completion (quick-260627-m3k)** — `markMilestoneComplete` now resets the STATE.md `Phase:` line (via a shared `_finalizeMilestoneStateBody` helper) instead of leaving it frozen at the last in-progress value, so a shipped milestone no longer surfaces a stale phase / `executing` status on the dashboard.
+- **Per-milestone finalize matcher (quick-260628-ikd)** — `roadmapUpdatePlanProgressInternal` is now format-agnostic: it updates progress-table rows keyed in the composite `<version>/N.` form (and bare `N.`) and preserves the optional Milestone column, so `phase finalize` / `plan finalize` update per-milestone ROADMAPs instead of silently no-op'ing.
+- **Branch-bounded diff-ref and self-check lookups (quick-260628-mlk)** — the codereview diff-ref, phase-prefix self-check probes, and the milestone-stats query are now bounded to the milestone branch, so per-milestone commit-prefix collisions (`feat(NN-NN):` reused across milestones) no longer reach unrelated commits from a different milestone.
+- **Jobs healthCheck flat-first (quick-260628-kxr-01)** — reworked the jobs `healthCheck` to be flat-first.
+
+### Documentation
+- **Stale-dashboard recovery guide (quick-260627-kvy)** — added a "Recovering a stale milestone dashboard" section to `docs/USER-GUIDE.md` documenting `state reconcile-milestone` and the per-project recovery playbook.
+
+## [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

@@ -615,6 +615,22 @@ function convertClaudeToGeminiToml(content) {
   return toml;
 }
 
+/**
+ * Rewrite HOME-relative ".claude" references to the target config dir basename.
+ * Swaps ONLY the ".claude" basename, preserving the $HOME / process.env.HOME prefix.
+ * For a default ".claude" install cfgBase === ".claude" => both replaces are no-ops.
+ * @param {string} content - file content
+ * @param {string} cfgBase - target config dir basename, e.g. ".claude-v25-test" or ".claude"
+ */
+function rewriteHomeRelativeConfigPaths(content, cfgBase) {
+  // shell form: $HOME/.claude/  -> $HOME/<cfgBase>/
+  content = content.replace(/\$HOME\/\.claude\//g, '$HOME/' + cfgBase + '/');
+  // JS concat form: process.env.HOME + '/.claude/'  (both quote styles)
+  // matches a quote char followed by /.claude/ ; $1 backreference preserves the quote
+  content = content.replace(/(["'])\/\.claude\//g, '$1/' + cfgBase + '/');
+  return content;
+}
+
 /**
  * Copy commands to a flat structure for OpenCode
  * OpenCode expects: command/dgs-help.md (invoked as /dgs-help)
@@ -664,6 +680,8 @@ function copyFlattenedCommands(srcDir, destDir, prefix, pathPrefix, runtime) {
       content = content.replace(globalClaudeRegex, pathPrefix);
       content = content.replace(localClaudeRegex, `./${getDirName(runtime)}/`);
       content = content.replace(opencodeDirRegex, pathPrefix);
+      const cfgBase = pathPrefix.replace(/\/$/, '').split('/').pop();
+      content = rewriteHomeRelativeConfigPaths(content, cfgBase);
       content = processAttribution(content, getCommitAttribution(runtime));
       content = convertClaudeToOpencodeFrontmatter(content);
 
@@ -705,6 +723,8 @@ function copyWithPathReplacement(srcDir, destDir, pathPrefix, runtime, isCommand
       const localClaudeRegex = /\.\/\.claude\//g;
       content = content.replace(globalClaudeRegex, pathPrefix);
       content = content.replace(localClaudeRegex, `./${dirName}/`);
+      const cfgBase = pathPrefix.replace(/\/$/, '').split('/').pop();
+      content = rewriteHomeRelativeConfigPaths(content, cfgBase);
       content = processAttribution(content, getCommitAttribution(runtime));
 
       // Convert frontmatter for opencode compatibility
@@ -1657,6 +1677,8 @@ function install(isGlobal, runtime = 'claude') {
         // Always replace ~/.claude/ as it is the source of truth in the repo
         const dirRegex = /~\/\.claude\//g;
         content = content.replace(dirRegex, pathPrefix);
+        const cfgBase = pathPrefix.replace(/\/$/, '').split('/').pop();
+        content = rewriteHomeRelativeConfigPaths(content, cfgBase);
         content = processAttribution(content, getCommitAttribution(runtime));
         // Convert frontmatter for runtime compatibility
         if (isOpencode) {
@@ -1816,11 +1838,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 +1853,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: