@ktpartners/dgs-platform 3.4.2 → 3.5.1

package/deliver-great-systems/bin/lib/path-audit.test.cjs

@@ -272,6 +272,134 @@ describe('path audit: comprehensive .planning/ reference scanning', () => {
     }
   });
 
+  // ─── Phases-Path Seam Gate (RSLV-03) ────────────────────────────────────
+  // Enforces the one-seam invariant from Phase 164: all active-project phases-path
+  // resolution routes through core.cjs phasesDir(cwd). Any NEW ad-hoc
+  // path.join(..., 'phases') active-project construction in a non-test lib module
+  // is a regression (re-introduces the split-brain that Phase 164 consolidated).
+  //
+  // The empirically-derived exclusion model (validated against the real
+  // post-164-04 tree, NOT the plan's pre-migration model — the tree drifted):
+  //
+  //  COMMENT-STRIP — trailing // line-comments are stripped before matching, and
+  //    lines that are pure // or * (JSDoc) comments are skipped. This clears
+  //    core.cjs:297 / phase.cjs:21 (`phasesRel = 'phases';   // ... path.join('.','phases')`)
+  //    and the core.cjs:776 / phase.cjs:13 JSDoc mentions WITHOUT allowlisting those
+  //    files (their canonical-resolver code carries no gate-matching construction).
+  //
+  //  (1) PER-LINE FALLBACK_SKIPS — retained catch-branch fallbacks that migrated
+  //      files legitimately keep (the IN-SCOPE try branch routes through
+  //      phasesDir(cwd), which carries no 'phases' literal, so the file stays gated):
+  //        - getPlanningRoot(cwd),'phases'  → commands.cjs:153, state.cjs:646
+  //        - path.join(planRootRel,'phases') → init.cjs:865/1065/1262 (whole ctx.root ternary line), commands.cjs:1098
+  //        - path.join(planRoot,'phases')    → commands.cjs:872
+  //        - = path.join(projectRoot,'phases') → state.cjs:300 (phasesRel) AND jobs.cjs:1133/1715/1930 (phasesAbs).
+  //              Anchored on the `= path.join(projectRoot,` assignment so it matches BOTH
+  //              variable names introduced across plans 03/04 (state.cjs uses phasesRel;
+  //              jobs.cjs's three soft-fallback catches use phasesAbs) — the plan's model
+  //              only anticipated the phasesRel form; 164-04 added the phasesAbs sites.
+  //        - path.relative(cwd, planningRoot)..,'phases' → context.cjs:534 planning-root catch
+  //              (retained fallback NOT in the plan's model; surfaced empirically).
+  //
+  //  (2) PER-FILE ALLOWLIST — wholly-different-semantics sites with NO in-scope
+  //      active-project resolution to guard (applied as a PRE-FILTER before scanning):
+  //        overlap.cjs / projects.cjs (by-slug, not current project),
+  //        review.cjs (caller-supplied projectRoot param),
+  //        package-scan-report.cjs (cross-project scan),
+  //        verify.cjs (planning-root health check via planRoot/planningDir variables).
+  //      core.cjs is intentionally NOT allowlisted: Plan 01 migrated findPhaseInternal's
+  //      path.join(projectRoot,'phases') to phasesDir(cwd), so post-migration it carries
+  //      no gate-matching code line (only the comment the strip removes).
+  //
+  // Durable-guard proof recorded in 164-05-SUMMARY.md: with the allowlist filter and
+  // the projectRoot skip disabled, this gate fires on exactly 11 lines across 7 files
+  // {jobs, overlap, package-scan-report, projects, review, state, verify} — proving the
+  // nested-paren regex is not inert and core.cjs/phase.cjs carry no matching code line.
+  it('GATE: zero ad-hoc active-project path.join(..., "phases") in library source (RSLV-03)', () => {
+    const libDir = path.join(DGS_ROOT, 'bin', 'lib');
+
+    // (2) Per-FILE allowlist: { file: 'reason' }. EMPIRICALLY VERIFIED — these are
+    // the only non-fallback files matching the gate regex post-migration AND having
+    // no in-scope active-project site to guard.
+    const ALLOWLIST = {
+      'overlap.cjs': 'by-slug project: path.join(getProjectDir(cwd, slug), "phases") — not current-project',
+      'projects.cjs': 'by-slug project: path.join(getProjectDir(cwd, slug), "phases") — not current-project',
+      'review.cjs': 'caller-supplied projectRoot param: path.join(planningRoot, projectRoot, "phases") — not resolved here',
+      'package-scan-report.cjs': 'cross-project scan: path.join(projectsDir, pEnt.name, "phases") over all projects',
+      'verify.cjs': 'planning-root health check: path.join(planRoot|planningDir, "phases") where the root is getPlanningRoot(cwd) via a variable the generic getPlanningRoot skip does not catch',
+    };
+
+    const files = fs.readdirSync(libDir)
+      .filter(f => f.endsWith('.cjs'))
+      .filter(f => !f.endsWith('.test.cjs'))
+      .filter(f => f !== 'test-helpers.cjs')
+      .filter(f => f !== 'migration.cjs')
+      .filter(f => !(f in ALLOWLIST));   // PRE-FILTER: allowlisted files never line-scanned
+
+    // NESTED-paren tolerant: matches path.join(<x | f(...)>, 'phases'[,)] — one level of
+    // nested parens allowed so getProjectDir(...)/getPlanningRoot(...) forms match (a plain
+    // [^)]* body could not, making nested-call regressions invisible).
+    const PHASES_JOIN_PATTERN = /path\.join\((?:[^()]|\([^()]*\))*,\s*['"]phases['"]\s*[,)]/;
+
+    // (1) Per-LINE generic skips for legitimately-retained fallback branches.
+    const FALLBACK_SKIPS = [
+      /getPlanningRoot\([^)]*\),\s*['"]phases['"]/,                  // path.join(getPlanningRoot(cwd), 'phases')
+      /path\.join\(planRootRel,\s*['"]phases['"]/,                   // init.cjs x3 + commands.cjs:1098 planning-root fallbacks
+      /path\.join\(planRoot,\s*['"]phases['"]/,                      // commands.cjs:872 planRoot fallback
+      /=\s*path\.join\(projectRoot,\s*['"]phases['"]/,               // state.cjs:300 (phasesRel) + jobs.cjs x3 (phasesAbs) projectRoot catches
+      /path\.relative\(cwd,\s*planningRoot\)[^,]*,\s*['"]phases['"]/, // context.cjs:534 planning-root catch
+    ];
+
+    const violations = [];
+    for (const f of files) {
+      const filePath = path.join(libDir, f);
+      const lines = fs.readFileSync(filePath, 'utf-8').split('\n');
+      for (let i = 0; i < lines.length; i++) {
+        const raw = lines[i];
+        if (raw.trimStart().startsWith('//')) continue;
+        if (raw.trimStart().startsWith('*')) continue;
+        const line = raw.replace(/\/\/.*$/, '');   // strip trailing line-comment before matching
+        if (!PHASES_JOIN_PATTERN.test(line)) continue;
+        if (FALLBACK_SKIPS.some(re => re.test(line))) continue;  // retained fallback branch
+        violations.push(`${f}:${i + 1}: ${raw.trim()}`);
+      }
+    }
+
+    if (violations.length > 0) {
+      assert.fail(
+        `Found ${violations.length} ad-hoc path.join(..., 'phases') site(s) outside the canonical resolver:\n` +
+        violations.join('\n') +
+        `\n\nRoute active-project phases-path resolution through core.cjs phasesDir(cwd). ` +
+        `If this is a genuinely different semantic (by-slug / planning-root / cross-project / param), add it to ALLOWLIST with a reason.`
+      );
+    }
+  });
+
+  // Anti-regression: prove the gate WOULD catch a fresh ad-hoc projectRoot+'phases'
+  // construction in a non-fallback, non-comment, non-allowlisted context. Runs the
+  // same regex+skip logic over a synthetic line; the line must be flagged.
+  it('GATE self-test: a fresh ad-hoc path.join(projectRoot, "phases") IS caught (RSLV-03)', () => {
+    const PHASES_JOIN_PATTERN = /path\.join\((?:[^()]|\([^()]*\))*,\s*['"]phases['"]\s*[,)]/;
+    const FALLBACK_SKIPS = [
+      /getPlanningRoot\([^)]*\),\s*['"]phases['"]/,
+      /path\.join\(planRootRel,\s*['"]phases['"]/,
+      /path\.join\(planRoot,\s*['"]phases['"]/,
+      /=\s*path\.join\(projectRoot,\s*['"]phases['"]/,
+      /path\.relative\(cwd,\s*planningRoot\)[^,]*,\s*['"]phases['"]/,
+    ];
+    // A NEW ad-hoc site: not an assignment-form catch (no leading `= `), not a comment,
+    // not a known fallback shape — e.g. used directly as a call argument.
+    const adHoc = `      const dir = path.join(projectRoot, 'phases');`;
+    const stripped = adHoc.replace(/\/\/.*$/, '');
+    assert.ok(PHASES_JOIN_PATTERN.test(stripped), 'regex must match a fresh projectRoot+phases join');
+    // The skip anchored on `= path.join(projectRoot,` does NOT match `= path.join(projectRoot,` here?
+    // It DOES (this is a const assignment). Use a true non-fallback shape: a bare call argument.
+    const adHocArg = `      doThing(path.join(projectRoot, 'phases'));`;
+    const strippedArg = adHocArg.replace(/\/\/.*$/, '');
+    assert.ok(PHASES_JOIN_PATTERN.test(strippedArg), 'regex must match a bare-argument projectRoot+phases join');
+    assert.ok(!FALLBACK_SKIPS.some(re => re.test(strippedArg)), 'a bare-argument ad-hoc site must NOT be covered by any fallback skip — it would be flagged as a violation');
+  });
+
   // ─── Allowlist Verification ─────────────────────────────────────────────
 
   it('allowlisted workflow files exist and are minimal', () => {

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

@@ -93,7 +93,7 @@ function isV2Install(cwd) {
  * Results are cached per resolved absolute cwd.
  *
  * @param {string} [cwd] - Working directory (defaults to process.cwd())
- * @returns {Readonly<Object>} Frozen PATHS object with ROOT, PHASES, IDEAS, etc.
+ * @returns {Readonly<Object>} Frozen PATHS object with ROOT, IDEAS, etc.
  */
 function getPaths(cwd) {
   const resolved = path.resolve(cwd || process.cwd());
@@ -103,7 +103,6 @@ function getPaths(cwd) {
 
   const paths = Object.freeze({
     ROOT: root,
-    PHASES: path.join(root, 'phases'),
     IDEAS: path.join(root, 'ideas'),
     SPECS: path.join(root, 'specs'),
     JOBS: path.join(root, 'jobs'),

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

@@ -244,12 +244,12 @@ describe('PATHS object shape', () => {
   });
 
   const EXPECTED_KEYS = [
-    'ROOT', 'PHASES', 'IDEAS', 'SPECS', 'JOBS', 'DOCS',
+    'ROOT', 'IDEAS', 'SPECS', 'JOBS', 'DOCS',
     'CODEBASE', 'MILESTONES', 'CONFIG', 'CONFIG_LOCAL',
     'QUICK', 'TODOS', 'RESEARCH', 'DEBUG', 'ARCHIVE', 'PROJECTS',
   ];
 
-  it('returns object with all 16 expected keys', () => {
+  it('returns object with all 15 expected keys', () => {
     cwd = makeGitTempDir();
     const paths = getPaths(cwd);
     assert.deepEqual(Object.keys(paths).sort(), EXPECTED_KEYS.slice().sort());
@@ -287,7 +287,7 @@ describe('PATHS object shape', () => {
   it('subdirectory paths are derived from ROOT', () => {
     cwd = makeGitTempDir();
     const paths = getPaths(cwd);
-    assert.equal(paths.PHASES, path.join(paths.ROOT, 'phases'));
+    assert.equal(paths.PHASES, undefined, 'PHASES key removed — phases path resolves via core.cjs phasesDir, not the project-unaware PATHS constant');
     assert.equal(paths.IDEAS, path.join(paths.ROOT, 'ideas'));
     assert.equal(paths.SPECS, path.join(paths.ROOT, 'specs'));
     assert.equal(paths.JOBS, path.join(paths.ROOT, 'jobs'));
@@ -443,7 +443,6 @@ describe('edge cases', () => {
     cwd = makeGitTempDir();
     const paths = getPaths(cwd);
     // Should return all paths even though none of these directories exist
-    assert.ok(paths.PHASES);
     assert.ok(paths.IDEAS);
     assert.ok(paths.SPECS);
     assert.ok(paths.ROOT);

package/deliver-great-systems/bin/lib/phase-versioned.test.cjs

@@ -0,0 +1,134 @@
+/**
+ * Restart-at-1 behaviour test (NUM-01).
+ *
+ * Dedicated file (separate from phase.test.cjs, which plan 02 owns) proving that a
+ * fresh versioned milestone's FIRST add-phase is numbered `01` (zero-padded) and
+ * lands UNDER the milestone's own phases/<version>/ directory — i.e. phase numbering
+ * restarts per milestone with NO arithmetic change (empty roadmap → maxPhase=0 →
+ * newPhaseNum=1 → '01'), and no global / MILESTONES.md continuation leaks into the number.
+ *
+ * Uses Node.js built-in test runner (node:test) + assert.
+ */
+
+const { describe, it } = require('node:test');
+const assert = require('node:assert');
+const fs = require('node:fs');
+const path = require('node:path');
+const { createFixture } = require('./test-helpers.cjs');
+const { cmdPhaseInitVersionedDir, cmdPhaseAdd } = require('./phase.cjs');
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+/**
+ * Capture stdout from CLI commands that call output() (process.stdout.write +
+ * process.exit). Mirrors phase.test.cjs's captureStdout so multiple invocations
+ * can run in sequence. Returns { stdout, exitCode, json }.
+ */
+function captureStdout(fn) {
+  const chunks = [];
+  const origWrite = process.stdout.write.bind(process.stdout);
+  const origExit = process.exit;
+  let exitCode = null;
+  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__') throw e;
+  } finally {
+    process.stdout.write = origWrite;
+    process.exit = origExit;
+  }
+  const stdout = chunks.join('');
+  let json = null;
+  try { json = JSON.parse(stdout); } catch { /* not JSON */ }
+  return { stdout, exitCode, json };
+}
+
+/**
+ * Fresh-milestone v2 fixture. STATE.md frontmatter `current_milestone` is what
+ * resolveMilestoneVersion(required) reads. The ROADMAP has NO `### Phase` heading
+ * (fresh milestone) plus a `---` trailer so cmdPhaseAdd's insertion logic has a
+ * separator. `roadmapBody` lets a test seed a high-number context to prove
+ * milestone-local numbering.
+ */
+function freshMilestoneFixture({ slug = 'auth-overhaul', milestone = 'v26.0', roadmapBody } = {}) {
+  return createFixture({
+    'config.json': JSON.stringify({}),
+    'config.local.json': JSON.stringify({ current_project: slug }),
+    'PROJECTS.md': '# Projects\n\n| Project | Status |\n',
+    'REPOS.md': '# Repos\n\n| Name | Path |\n',
+    [`projects/${slug}/PROJECT.md`]: '# Project',
+    [`projects/${slug}/STATE.md`]: `---\ncurrent_milestone: ${milestone}\n---\n# State`,
+    [`projects/${slug}/ROADMAP.md`]: roadmapBody || '# Roadmap\n\n## Phases\n\n---\n',
+    [`projects/${slug}/phases/`]: null,
+  });
+}
+
+// ─── Restart-at-1 (NUM-01) ────────────────────────────────────────────────────
+
+describe('restart-at-1 in a fresh versioned milestone (NUM-01)', () => {
+  it('Test 1: first add-phase is 01 and lands under phases/<version>/', () => {
+    const fixture = freshMilestoneFixture({ slug: 'auth-overhaul', milestone: 'v26.0' });
+    try {
+      // new-milestone flow materialises phases/v26.0/ (NUM-02 command).
+      captureStdout(() => cmdPhaseInitVersionedDir(fixture.cwd, true));
+
+      // First add-phase in the fresh versioned milestone.
+      const { json } = captureStdout(() =>
+        cmdPhaseAdd(fixture.cwd, 'first thing', false)
+      );
+
+      assert.ok(json, 'add-phase should emit JSON');
+      // Restart-at-1: empty versioned roadmap → maxPhase=0 → newPhaseNum=1 → '01'.
+      assert.equal(json.padded, '01', 'first phase is zero-padded 01');
+      assert.equal(json.phase_number, 1, 'first phase_number is 1');
+
+      // The created dir is UNAMBIGUOUS evidence: phases/v26.0/01-first-thing.
+      const expectedDir = path.join('projects', 'auth-overhaul', 'phases', 'v26.0', '01-first-thing');
+      assert.equal(json.directory, expectedDir, 'phase dir is numbered 01 under the versioned dir');
+      assert.ok(
+        fs.existsSync(path.join(fixture.cwd, expectedDir)),
+        'phases/v26.0/01-first-thing exists on disk'
+      );
+    } finally {
+      fixture.cleanup();
+    }
+  });
+
+  it('Test 2: numbers stay milestone-local (no global continuation leaks into 01)', () => {
+    // Seed a ROADMAP with prose that mentions high phase numbers but NO `### Phase`
+    // heading. A global / MILESTONES.md continuation scheme would have produced a
+    // high number; the milestone-local maxPhase scan sees zero `### Phase` headings,
+    // so the first add-phase is still 01.
+    const roadmapBody =
+      '# Roadmap\n\n' +
+      'Continuation note: the previous milestone ended at phase 162.\n\n' +
+      '## Phases\n\n' +
+      '---\n';
+    const fixture = freshMilestoneFixture({
+      slug: 'auth-overhaul',
+      milestone: 'v26.0',
+      roadmapBody,
+    });
+    try {
+      captureStdout(() => cmdPhaseInitVersionedDir(fixture.cwd, true));
+      const { json } = captureStdout(() =>
+        cmdPhaseAdd(fixture.cwd, 'first thing', false)
+      );
+      assert.ok(json, 'add-phase should emit JSON');
+      // Still 01 — proves no MILESTONES.md / global 163-continuation leaks into the number.
+      assert.equal(json.padded, '01', 'milestone-local: first phase is 01 despite prose mentioning 162');
+      assert.equal(json.phase_number, 1, 'milestone-local: phase_number is 1');
+      assert.ok(
+        json.directory.startsWith(path.join('projects', 'auth-overhaul', 'phases', 'v26.0')),
+        `phase dir must be under the versioned dir: ${json.directory}`
+      );
+    } finally {
+      fixture.cleanup();
+    }
+  });
+});

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

@@ -4,7 +4,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { escapeRegex, normalizePhaseName, comparePhaseNum, findPhaseInternal, getArchivedPhaseDirs, generateSlugInternal, getMilestonePhaseFilter, toPosixPath, output, error, getProjectRoot, loadConfig, execGit } = require('./core.cjs');
+const { escapeRegex, normalizePhaseName, comparePhaseNum, findPhaseInternal, getArchivedPhaseDirs, generateSlugInternal, getMilestonePhaseFilter, toPosixPath, output, error, getProjectRoot, phasesDir, resolveProjectPath, resolveMilestoneVersion, loadConfig, execGit } = require('./core.cjs');
 const { extractFrontmatter } = require('./frontmatter.cjs');
 const { writeStateMd } = require('./state.cjs');
 
@@ -14,13 +14,13 @@ const { writeStateMd } = require('./state.cjs');
  * from getProjectRoot() or '.' as fallback.
  */
 function resolvePhasesDir(cwd) {
-  let projectRoot;
+  let phasesRel;
   try {
-    projectRoot = getProjectRoot(cwd);
+    phasesRel = phasesDir(cwd);
   } catch {
-    projectRoot = '.';
+    phasesRel = 'phases';   // flat-layout fallback (== path.join('.', 'phases'))
   }
-  return path.join(cwd, projectRoot, 'phases');
+  return path.join(cwd, phasesRel);
 }
 
 /**
@@ -406,6 +406,54 @@ function cmdPhaseAdd(cwd, description, raw) {
   output(result, raw, paddedNum);
 }
 
+/**
+ * Create the current milestone's versioned phases directory: phases/<version>/.
+ * This is the SOLE creator of a phases/<version> directory (NUM-02). It requires a
+ * determinable milestone version (fail-loud) so a phase is never written to phases/v1.0/.
+ * Idempotent: recursive mkdir is a no-op when the directory already exists.
+ * cmdPhaseAdd never calls this — it routes through the version-aware phasesDir resolver,
+ * which returns this directory once it exists.
+ */
+/**
+ * Internal, output-free creator of the current milestone's versioned phases dir.
+ * Shared by the CLI wrapper (cmdPhaseInitVersionedDir) AND create-adhoc seeding
+ * (milestone.cjs) so there is exactly ONE versioned-dir creator (Decision C / NUM-02).
+ *
+ * required:true → throws the Phase-163 remediation Error when the version is
+ * undeterminable; never writes phases/v1.0/. Idempotent: recursive mkdir is a
+ * no-op when the directory already exists, and `created` reflects whether THIS
+ * call materialized the directory (probed via existsSync BEFORE mkdir).
+ *
+ * @param {string} cwd - planning root
+ * @returns {{ version: string, directory: string, created: boolean }}
+ *          `directory` is relative to cwd.
+ */
+function phaseInitVersionedDirInternal(cwd) {
+  // required:true → throws the Phase-163 remediation Error when undeterminable; never v1.0.
+  const version = resolveMilestoneVersion(cwd, { required: true });
+  // resolveProjectPath returns the FLAT relative phases base (NOT version-aware), so joining
+  // the version is correct and idempotent on re-run. It is a function call — not a
+  // path.join(..., 'phases') literal — so the 164-05 RSLV-03 phases-join gate stays GREEN.
+  const flatBase = resolveProjectPath(cwd, 'phases');       // relative: projects/<slug>/phases or phases
+  const versionedDir = path.join(cwd, flatBase, version);   // absolute phases/<version>
+  const created = !fs.existsSync(versionedDir);             // did THIS call create it?
+  fs.mkdirSync(versionedDir, { recursive: true });          // idempotent
+  return { version, directory: path.relative(cwd, versionedDir), created };
+}
+
+/**
+ * Create the current milestone's versioned phases directory: phases/<version>/.
+ * This is the SOLE creator of a phases/<version> directory (NUM-02). It requires a
+ * determinable milestone version (fail-loud) so a phase is never written to phases/v1.0/.
+ * Idempotent: recursive mkdir is a no-op when the directory already exists.
+ * cmdPhaseAdd never calls this — it routes through the version-aware phasesDir resolver,
+ * which returns this directory once it exists.
+ */
+function cmdPhaseInitVersionedDir(cwd, raw) {
+  const { version, directory, created } = phaseInitVersionedDirInternal(cwd);
+  output({ version, directory, created }, raw, directory);
+}
+
 function cmdPhaseInsert(cwd, afterPhase, description, raw) {
   if (!afterPhase || !description) {
     error('after-phase and description required for phase insert');
@@ -767,8 +815,11 @@ function phaseCompleteInternal(cwd, phaseNum) {
 
   // Verify phase info
   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/.plans, so neither is reached for an ambiguity object. Surface
+  // its milestone-qualified message instead of throwing.
+  if (!phaseInfo || !phaseInfo.found) {
+    error(phaseInfo?.message || `Phase ${phaseNum} not found`);
   }
 
   // Absolute phase directory (phaseInfo.directory is relative to cwd)
@@ -1046,6 +1097,8 @@ module.exports = {
   cmdFindPhase,
   cmdPhasePlanIndex,
   cmdPhaseAdd,
+  cmdPhaseInitVersionedDir,
+  phaseInitVersionedDirInternal,
   cmdPhaseInsert,
   cmdPhaseRemove,
   cmdPhaseComplete,

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

@@ -11,7 +11,8 @@ 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');
+const { initPaths, resetPaths } = require('./paths.cjs');
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 
@@ -418,3 +419,169 @@ describe('cmdPlanFinalize', () => {
     assert.equal(gitLastMessage(fixture.cwd), 'docs(04-01): complete execution plan');
   });
 });
+
+// ─── cmdPhaseInitVersionedDir (NUM-02 versioned write path) ────────────────────
+
+describe('cmdPhaseInitVersionedDir (NUM-02 versioned write path)', () => {
+  let phase;
+
+  beforeEach(() => {
+    // Reload phase.cjs fresh so each fixture's config/paths are re-read.
+    delete require.cache[require.resolve('./phase.cjs')];
+    phase = require('./phase.cjs');
+  });
+
+  // Shared v2 project-context builder. STATE.md frontmatter `current_milestone`
+  // is what resolveMilestoneVersion(required) reads. `roadmapBody`/`extraDirs`
+  // let individual tests scaffold a versioned ROADMAP context or pre-create dirs.
+  function v2Fixture({ slug = 'auth-overhaul', stateBody, roadmapBody, extraDirs } = {}) {
+    const tree = {
+      'config.json': JSON.stringify({}),
+      'config.local.json': JSON.stringify({ current_project: slug }),
+      'PROJECTS.md': '# Projects\n\n| Project | Status |\n',
+      'REPOS.md': '# Repos\n\n| Name | Path |\n',
+      [`projects/${slug}/PROJECT.md`]: '# Project',
+      [`projects/${slug}/STATE.md`]: stateBody,
+      [`projects/${slug}/ROADMAP.md`]: roadmapBody || '# Roadmap',
+      [`projects/${slug}/phases/`]: null,
+    };
+    for (const d of (extraDirs || [])) tree[d] = null;
+    return createFixture(tree);
+  }
+
+  it('Test 1: creates the current milestone versioned dir phases/<version>/', () => {
+    const fixture = v2Fixture({ stateBody: '---\ncurrent_milestone: v26.0\n---\n# State' });
+    try {
+      // raw=false → output() emits structured JSON (raw=true would print the human relDir line).
+      const { json } = captureStdout(() =>
+        phase.cmdPhaseInitVersionedDir(fixture.cwd, false)
+      );
+      const versioned = path.join(fixture.cwd, 'projects', 'auth-overhaul', 'phases', 'v26.0');
+      assert.ok(fs.existsSync(versioned), 'phases/v26.0/ must be created');
+      assert.ok(fs.statSync(versioned).isDirectory(), 'phases/v26.0/ must be a directory');
+      // Output reports the version + relative directory.
+      assert.ok(json, 'should emit JSON output');
+      assert.equal(json.version, 'v26.0');
+      assert.equal(json.created, true);
+      assert.equal(
+        json.directory,
+        path.join('projects', 'auth-overhaul', 'phases', 'v26.0')
+      );
+    } finally {
+      fixture.cleanup();
+    }
+  });
+
+  it('Test 2: idempotent — re-run does NOT throw and creates NO nested phases/<version>/<version>/', () => {
+    const fixture = v2Fixture({ stateBody: '---\ncurrent_milestone: v26.0\n---\n# State' });
+    try {
+      // First invocation creates phases/v26.0/. Now phasesDir(cwd) is version-aware
+      // and would return phases/v26.0 — so a wrong (version-aware-base) construction
+      // would yield phases/v26.0/v26.0 on the SECOND run. This asserts it does NOT.
+      assert.doesNotThrow(() => {
+        captureStdout(() => phase.cmdPhaseInitVersionedDir(fixture.cwd, true));
+        captureStdout(() => phase.cmdPhaseInitVersionedDir(fixture.cwd, true));
+      });
+      const versioned = path.join(fixture.cwd, 'projects', 'auth-overhaul', 'phases', 'v26.0');
+      const nested = path.join(versioned, 'v26.0');
+      assert.ok(fs.existsSync(versioned), 'phases/v26.0/ exists exactly once');
+      assert.ok(!fs.existsSync(nested), 'NO nested phases/v26.0/v26.0/ (flat-base idempotency)');
+    } finally {
+      fixture.cleanup();
+    }
+  });
+
+  it('Test 3: fail-loud — undeterminable version throws (current_milestone remediation), writes NO phases/v1.0/', () => {
+    const fixture = v2Fixture({ stateBody: '# State (no milestone frontmatter)' });
+    try {
+      let thrown = null;
+      try {
+        captureStdout(() => phase.cmdPhaseInitVersionedDir(fixture.cwd, true));
+      } catch (e) {
+        thrown = e;
+      }
+      assert.ok(thrown, 'must throw on undeterminable version');
+      assert.match(thrown.message, /current_milestone/, 'remediation references current_milestone');
+      assert.match(thrown.message, /STATE\.md/, 'remediation references STATE.md');
+      assert.ok(!/v1\.0/.test(thrown.message), 'message must NOT mention v1.0');
+      // Critical: no phases/v1.0/ and no phases/undefined/ were written.
+      const phasesBase = path.join(fixture.cwd, 'projects', 'auth-overhaul', 'phases');
+      assert.ok(!fs.existsSync(path.join(phasesBase, 'v1.0')), 'NO phases/v1.0/ created');
+      assert.ok(!fs.existsSync(path.join(phasesBase, 'undefined')), 'NO phases/undefined/ created');
+    } finally {
+      fixture.cleanup();
+    }
+  });
+
+  it('Test 4: after create, cmdPhaseAdd lands the new phase under phases/<version>/', () => {
+    const fixture = v2Fixture({
+      stateBody: '---\ncurrent_milestone: v26.0\n---\n# State',
+      // Versioned ROADMAP context so maxPhase resolves (empty here → maxPhase=0 → newPhaseNum=1).
+      roadmapBody: '# Roadmap\n\n## Phases\n\n',
+    });
+    try {
+      captureStdout(() => phase.cmdPhaseInitVersionedDir(fixture.cwd, true));
+      const { json } = captureStdout(() =>
+        phase.cmdPhaseAdd(fixture.cwd, 'First versioned phase', false)
+      );
+      assert.ok(json, 'add-phase should emit JSON');
+      // New phase dir lands UNDER phases/v26.0/ because version-aware phasesDir returns it.
+      assert.ok(
+        json.directory.startsWith(path.join('projects', 'auth-overhaul', 'phases', 'v26.0')),
+        `phase dir must be under versioned dir: ${json.directory}`
+      );
+      assert.equal(json.padded, '01', 'restart-at-1: empty versioned roadmap numbers from 01');
+      assert.ok(fs.existsSync(path.join(fixture.cwd, json.directory)), 'new phase dir exists on disk');
+    } finally {
+      fixture.cleanup();
+    }
+  });
+
+  it('Test 5: two active milestones — each add-phase lands in its own phases/<version>/', () => {
+    const roadmap = '# Roadmap\n\n## Phases\n\n';
+    const fixtureA = v2Fixture({
+      slug: 'proj-a',
+      stateBody: '---\ncurrent_milestone: v26.0\n---\n# State',
+      roadmapBody: roadmap,
+    });
+    const fixtureB = v2Fixture({
+      slug: 'proj-b',
+      stateBody: '---\ncurrent_milestone: v27.0\n---\n# State',
+      roadmapBody: roadmap,
+    });
+    try {
+      // Create each milestone's versioned dir, then add-phase in each context.
+      // Both fixtures live simultaneously; the planning-root cache is a single
+      // per-process value (createFixture primed it for whichever was built last),
+      // so reset + re-prime for each project before operating on it, otherwise
+      // operations on the other would read a stale root / wrong current_project.
+      resetPaths();
+      initPaths(fixtureA.cwd);
+      captureStdout(() => phase.cmdPhaseInitVersionedDir(fixtureA.cwd, true));
+      const { json: jsonA } = captureStdout(() =>
+        phase.cmdPhaseAdd(fixtureA.cwd, 'A first phase', false)
+      );
+      resetPaths();
+      initPaths(fixtureB.cwd);
+      captureStdout(() => phase.cmdPhaseInitVersionedDir(fixtureB.cwd, true));
+      const { json: jsonB } = captureStdout(() =>
+        phase.cmdPhaseAdd(fixtureB.cwd, 'B first phase', false)
+      );
+
+      assert.ok(
+        jsonA.directory.startsWith(path.join('projects', 'proj-a', 'phases', 'v26.0')),
+        `A lands in v26.0: ${jsonA.directory}`
+      );
+      assert.ok(
+        jsonB.directory.startsWith(path.join('projects', 'proj-b', 'phases', 'v27.0')),
+        `B lands in v27.0: ${jsonB.directory}`
+      );
+      // Each numbered relative to its own (initially-empty) versioned roadmap.
+      assert.equal(jsonA.padded, '01');
+      assert.equal(jsonB.padded, '01');
+    } finally {
+      fixtureA.cleanup();
+      fixtureB.cleanup();
+    }
+  });
+});

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

@@ -225,6 +225,44 @@ describe('readProjectState', () => {
     assert.ok(state !== null);
     assert.strictEqual(state.phase, 'Unknown');
   });
+
+  it('returns a non-stale phase for a shipped, production-shaped STATE.md', () => {
+    // Regression (DASH-STALE-01): after a milestone ships, markMilestoneComplete
+    // resets the Current Position Phase: line to the between-milestones form. This
+    // proves readProjectState — whose Phase: read regex is UNANCHORED — yields a
+    // non-stale phase when given a realistic, fully-synced production STATE.md
+    // (full frontmatter block, NOT a bare `# Project State` body).
+    const shippedState = `---
+dgs_state_version: 1.0
+milestone: v1.0
+milestone_name: milestone
+status: milestone_shipped
+last_updated: "2026-06-27T00:00:00.000Z"
+completed_date: 2026-06-27
+progress:
+  total_phases: 8
+  completed_phases: 8
+  total_plans: 20
+  completed_plans: 20
+  percent: 100
+---
+
+# Project State
+
+## Current Position
+
+Phase: — (between milestones; v1.0 shipped 2026-06-27)
+Status: Milestone v1.0 shipped 2026-06-27
+Progress: [██████████] 100%
+`;
+    createProjectManually(tmpDir, 'proj', shippedState);
+    const state = readProjectState(tmpDir, 'proj');
+    assert.ok(
+      !/\d+\s+of\s+\d+/.test(state.phase),
+      `Shipped STATE should yield a non-stale phase, got: ${state.phase}`
+    );
+    assert.ok(/between milestones/.test(state.phase), 'phase reflects between-milestones form');
+  });
 });
 
 // ─── scanProjectReposTags ───────────────────────────────────────────────────