@ktpartners/dgs-platform 3.5.1 → 3.5.3

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/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/complete-milestone.md

@@ -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/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.

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

@@ -53,7 +53,11 @@ Set `NON_INTERACTIVE = true` if `--non-interactive` flag present OR `--auto` fla
 
 **If `phase_found` is false:** Validate phase exists in ROADMAP.md. If valid, create the directory using `phase_slug` and `padded_phase` from init. Use `project_root` from init for the base path:
 ```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}"
 ```
 
 **Existing artifacts from init:** `has_research`, `has_plans`, `plan_count`.
@@ -548,7 +552,7 @@ Before constructing the checker prompt, discover up to 3 most recent completed p
 
 ```bash
 # Find SUMMARY files from completed phases, sorted by modification time (most recent first)
-SUMMARY_FILES=$(ls -t ${project_root}/phases/*/[0-9]*-*-SUMMARY.md 2>/dev/null | head -9)
+SUMMARY_FILES=$(ls -t ${project_root}/phases/*/[0-9]*-*-SUMMARY.md ${project_root}/phases/*/*/[0-9]*-*-SUMMARY.md 2>/dev/null | head -9)
 # Filter to only the 3 most recent unique phases (a phase may have multiple SUMMARYs)
 SEEN_PHASES=""
 SUMMARY_PATHS=""

package/deliver-great-systems/workflows/resume-project.md

@@ -68,10 +68,10 @@ Look for incomplete work that needs attention:
 
 ```bash
 # Check for continue-here files (mid-plan resumption)
-ls ${project_root}/phases/*/.continue-here*.md 2>/dev/null
+find ${project_root}/phases -name '.continue-here*.md' 2>/dev/null
 
 # Check for plans without summaries (incomplete execution)
-for plan in ${project_root}/phases/*/*-PLAN.md; do
+for plan in $(find ${project_root}/phases -name '*-PLAN.md' 2>/dev/null); do
   summary="${plan/PLAN/SUMMARY}"
   [ ! -f "$summary" ] && echo "Incomplete: $plan"
 done 2>/dev/null

package/package.json

@@ -8,7 +8,7 @@
   "bugs": {
     "url": "https://github.com/KT-Partners-Ltd/dgs-platform-docs/issues"
   },
-  "version": "3.5.1",
+  "version": "3.5.3",
   "description": "Deliver Great Systems Platform — A meta-prompting, context engineering and spec-driven development system for Claude Code and Gemini by KT Partners.",
   "bin": {
     "dgs": "bin/install.js"