@ktpartners/dgs-platform 3.4.2 → 3.5.0

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

@@ -5,7 +5,7 @@
 const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
-const { loadConfig, resolveModelInternal, findPhaseInternal, getRoadmapPhaseInternal, pathExistsInternal, generateSlugInternal, getMilestoneInfo, normalizePhaseName, toPosixPath, output, error, resolveProjectPath, getProjectRoot, isV2Install, getProjectFolders, getV2Hint, safeReadFile } = require('./core.cjs');
+const { loadConfig, resolveModelInternal, findPhaseInternal, getRoadmapPhaseInternal, pathExistsInternal, generateSlugInternal, getMilestoneInfo, normalizePhaseName, toPosixPath, output, error, resolveProjectPath, getProjectRoot, phasesDir, isV2Install, getProjectFolders, getV2Hint, safeReadFile, isValidMilestoneVersion } = require('./core.cjs');
 const { requireGitIdentity, formatAuthorString } = require('./identity.cjs');
 const { getPlanningRoot, PROJECTS_DIR } = require('./paths.cjs');
 const { parseReposMd, validateReposMdEager } = require('./repos.cjs');
@@ -242,7 +242,7 @@ function cmdInitExecutePhase(cwd, phase, raw) {
   const config = loadConfig(cwd);
   const ctx = resolveProjectContext(cwd);
   let phaseInfo = findPhaseInternal(cwd, phase);
-  if (phaseInfo?.archived) phaseInfo = null;
+  if (phaseInfo?.archived || phaseInfo?.ambiguous) phaseInfo = null;
   const milestone = getMilestoneInfo(cwd);
   const planRootRel = path.relative(cwd, getPlanningRoot(cwd)) || '.';
 
@@ -348,7 +348,7 @@ function cmdInitPlanPhase(cwd, phase, raw) {
   const config = loadConfig(cwd);
   const ctx = resolveProjectContext(cwd);
   let phaseInfo = findPhaseInternal(cwd, phase);
-  if (phaseInfo?.archived) phaseInfo = null;
+  if (phaseInfo?.archived || phaseInfo?.ambiguous) phaseInfo = null;
   const planRootRel = path.relative(cwd, getPlanningRoot(cwd)) || '.';
 
   const roadmapPhase = getRoadmapPhaseInternal(cwd, phase);
@@ -556,8 +556,11 @@ function cmdInitNewMilestone(cwd, raw) {
     cadence_pull: getCadence('new-milestone').pull,
     cadence_push: getCadence('new-milestone').push,
 
-    // Current milestone
-    current_milestone: milestone.version,
+    // Current milestone — current_milestone is the authoritative structured
+    // version signal. new-milestone (this flow) and init.cjs are the SOLE
+    // setters. Emit only a grammar-valid value; surface a gap as null rather
+    // than persisting an out-of-grammar value (and NEVER coerce to v1.0).
+    current_milestone: isValidMilestoneVersion(milestone.version) ? milestone.version : null,
     current_milestone_name: milestone.name,
 
     // File existence (project-qualified)
@@ -747,7 +750,7 @@ function cmdInitVerifyWork(cwd, phase, raw) {
   const config = loadConfig(cwd);
   const ctx = resolveProjectContext(cwd);
   let phaseInfo = findPhaseInternal(cwd, phase);
-  if (phaseInfo?.archived) phaseInfo = null;
+  if (phaseInfo?.archived || phaseInfo?.ambiguous) phaseInfo = null;
 
   const result = {
     // Models
@@ -792,7 +795,7 @@ function cmdInitAuditPhase(cwd, phase, raw) {
   const config = loadConfig(cwd);
   const ctx = resolveProjectContext(cwd);
   let phaseInfo = findPhaseInternal(cwd, phase);
-  if (phaseInfo?.archived) phaseInfo = null;
+  if (phaseInfo?.archived || phaseInfo?.ambiguous) phaseInfo = null;
 
   const result = {
     // Models
@@ -834,7 +837,7 @@ function cmdInitPhaseOp(cwd, phase, raw, workflow) {
   const ctx = resolveProjectContext(cwd);
   const planRootRel = path.relative(cwd, getPlanningRoot(cwd)) || '.';
   let phaseInfo = findPhaseInternal(cwd, phase);
-  if (phaseInfo?.archived) phaseInfo = null;
+  if (phaseInfo?.archived || phaseInfo?.ambiguous) phaseInfo = null;
   const cadence = getCadence(workflow || 'plan-phase');
 
   // Fallback to ROADMAP.md if no directory exists (e.g., Plans: TBD)
@@ -858,6 +861,9 @@ function cmdInitPhaseOp(cwd, phase, raw, workflow) {
     }
   }
 
+  let phasesDirRel;
+  try { phasesDirRel = phasesDir(cwd); } catch { phasesDirRel = ctx.root ? path.join(ctx.root, 'phases') : path.join(planRootRel, 'phases'); }
+
   const result = {
     // Config
     commit_docs: config.commit_docs,
@@ -891,7 +897,7 @@ function cmdInitPhaseOp(cwd, phase, raw, workflow) {
     roadmap_path: ctx.root ? path.join(ctx.root, 'ROADMAP.md') : path.join(planRootRel, 'ROADMAP.md'),
     requirements_path: ctx.root ? path.join(ctx.root, 'REQUIREMENTS.md') : path.join(planRootRel, 'REQUIREMENTS.md'),
     project_path: ctx.root ? path.join(ctx.root, 'PROJECT.md') : path.join(planRootRel, 'PROJECT.md'),
-    phases_dir: ctx.root ? path.join(ctx.root, 'phases') : path.join(planRootRel, 'phases'),
+    phases_dir: phasesDirRel,
 
     // Author
     author: resolveAuthorSafe(cwd),
@@ -1055,17 +1061,18 @@ function cmdInitMilestoneOp(cwd, raw, workflow) {
   // Count phases (project-qualified)
   let phaseCount = 0;
   let completedPhases = 0;
-  const phasesBase = ctx.root ? path.join(ctx.root, 'phases') : path.join(planRootRel, 'phases');
-  const phasesDir = path.join(cwd, phasesBase);
+  let phasesBase;
+  try { phasesBase = phasesDir(cwd); } catch { phasesBase = ctx.root ? path.join(ctx.root, 'phases') : path.join(planRootRel, 'phases'); }
+  const phasesAbs = path.join(cwd, phasesBase);
   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);
     phaseCount = dirs.length;
 
     // Count phases with summaries (completed)
     for (const dir of dirs) {
       try {
-        const phaseFiles = fs.readdirSync(path.join(phasesDir, dir));
+        const phaseFiles = fs.readdirSync(path.join(phasesAbs, dir));
         const hasSummary = phaseFiles.some(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md');
         if (hasSummary) completedPhases++;
       } catch {}
@@ -1251,14 +1258,15 @@ function cmdInitProgress(cwd, raw) {
   const planRootRel = path.relative(cwd, getPlanningRoot(cwd)) || '.';
 
   // Analyze phases (project-qualified)
-  const phasesBase = ctx.root ? path.join(ctx.root, 'phases') : path.join(planRootRel, 'phases');
-  const phasesDir = path.join(cwd, phasesBase);
+  let phasesBase;
+  try { phasesBase = phasesDir(cwd); } catch { phasesBase = ctx.root ? path.join(ctx.root, 'phases') : path.join(planRootRel, 'phases'); }
+  const phasesAbs = path.join(cwd, phasesBase);
   const phases = [];
   let currentPhase = null;
   let nextPhase = null;
 
   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) {
@@ -1266,7 +1274,7 @@ function cmdInitProgress(cwd, raw) {
       const phaseNumber = match ? match[1] : dir;
       const phaseName = match && match[2] ? match[2] : null;
 
-      const phasePath = path.join(phasesDir, dir);
+      const phasePath = path.join(phasesAbs, dir);
       const phaseFiles = fs.readdirSync(phasePath);
 
       const plans = phaseFiles.filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md');

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

@@ -1657,16 +1657,6 @@ describe('cmdInitQuick quick_dir resolution', () => {
     beforeEach(() => {
       fixture = createFixture({
         'config.json': JSON.stringify({ current_project: 'test-project' }),
-        'config.local.json': JSON.stringify({
-          execution: { active_context: 'v19-git-worktrees' },
-          projects: {
-            'test-project': {
-              worktrees: {
-                'v19-git-worktrees': { type: 'milestone' }
-              }
-            }
-          }
-        }),
         'PROJECTS.md': '# Projects\n\n| Project | Status |\n|---------|--------|\n| test-project | Active |\n',
         'REPOS.md': '# Repos\n\n| Name | Path |\n|------|------|\n',
         'projects/test-project/STATE.md': '# State',
@@ -1676,6 +1666,35 @@ describe('cmdInitQuick quick_dir resolution', () => {
         'projects/test-project/phases/01-test-phase/01-CONTEXT.md': '# Context',
         'projects/test-project/phases/01-test-phase/01-01-PLAN.md': '---\nphase: 01-test-phase\nplan: 01\n---\n# Plan',
       });
+
+      // Establish a GENUINE milestone context. detectQuickMode treats a
+      // milestone worktree entry as active only when its `repos` map points at
+      // an on-disk directory; a bare { type: 'milestone' } entry with no live
+      // repos is treated as stale and falls through to PRODUCT mode (the
+      // documented stale-defence from bug 260507-pdp). The previous fixture
+      // omitted `repos`, so it silently exercised product mode and the
+      // project-scoped expectations below could never pass. Create a real
+      // worktree dir inside the fixture (cleaned up with it) and point the
+      // entry at it so milestone-context resolution actually fires.
+      const worktreeDir = path.join(fixture.cwd, 'worktrees', 'v19-git-worktrees');
+      fs.mkdirSync(worktreeDir, { recursive: true });
+      fs.writeFileSync(
+        path.join(fixture.cwd, 'config.local.json'),
+        JSON.stringify({
+          execution: { active_context: 'v19-git-worktrees' },
+          projects: {
+            'test-project': {
+              worktrees: {
+                'v19-git-worktrees': {
+                  type: 'milestone',
+                  repos: { 'deliver-great-systems': worktreeDir },
+                },
+              },
+            },
+          },
+        }),
+        'utf-8'
+      );
     });
 
     afterEach(() => {
@@ -2196,3 +2215,43 @@ describe('v2 mode multi-project: end-to-end', () => {
     }
   });
 });
+
+// ─── LOOK-01: init coerces a cross-milestone-ambiguous bare number to not-found ─
+
+describe('init execute-phase coerces ambiguous archive number to not-found (LOOK-01)', () => {
+  // A v2 project where bare "03" is NOT an active phase but exists in TWO
+  // milestone archives. findPhaseInternal returns a {found:false, ambiguous:true}
+  // signal; the init.cjs coercion must treat it as not-found rather than silently
+  // adopting one archive's directory (the pre-fix Group C bug).
+  function ambiguousArchiveFixture() {
+    return createFixture({
+      'config.json': JSON.stringify({}),
+      'config.local.json': JSON.stringify({ current_project: 'auth-overhaul' }),
+      'PROJECTS.md': '# Projects\n\n| Project | Status |\n|---------|--------|\n| auth-overhaul | Active |\n',
+      'REPOS.md': '# Repos\n\n| Name | Path |\n|------|------|\n',
+      'projects/auth-overhaul/STATE.md': '---\ncurrent_milestone: v25.0\n---\n# State',
+      'projects/auth-overhaul/ROADMAP.md': '# Roadmap',
+      'projects/auth-overhaul/REQUIREMENTS.md': '# Requirements',
+      'projects/auth-overhaul/PROJECT.md': '# Project',
+      '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('does NOT silently resolve to either archive directory', () => {
+    const fixture = ambiguousArchiveFixture();
+    try {
+      const result = runInit(fixture.cwd, 'execute-phase 03');
+      // Coerced to not-found: the ambiguity object was nulled out.
+      assert.equal(result.phase_found, false, 'ambiguous number must be not-found');
+      assert.equal(result.phase_dir, null, 'no archive directory adopted');
+      // Belt-and-suspenders: neither archived dir leaked into the result.
+      const blob = JSON.stringify(result);
+      assert.ok(!blob.includes('03-alpha'), 'must not adopt v3.0 archive dir');
+      assert.ok(!blob.includes('03-beta'), 'must not adopt v4.0 archive dir');
+    } finally {
+      fixture.cleanup();
+    }
+  });
+});

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

@@ -30,7 +30,7 @@
 const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
-const { output, error, getProjectRoot } = require('./core.cjs');
+const { output, error, getProjectRoot, phasesDir } = require('./core.cjs');
 const { getPlanningRoot } = require('./paths.cjs');
 const { requireGitIdentity, formatAuthorString } = require('./identity.cjs');
 const { extractFrontmatter, spliceFrontmatter, reconstructFrontmatter } = require('./frontmatter.cjs');
@@ -1128,7 +1128,9 @@ function analyzeMilestonePhases(cwd, version) {
   }
 
   const content = fs.readFileSync(roadmapPath, 'utf-8');
-  const phasesDir = path.join(projectRoot, 'phases');
+  let phasesAbs;
+  try { phasesAbs = path.join(cwd, phasesDir(cwd)); }
+  catch { phasesAbs = path.join(projectRoot, 'phases'); }
 
   // Find the milestone section: look for heading containing the version + "In Progress" or "SHIPPED"
   // Also match the milestone in the summary list to find its phase range
@@ -1222,12 +1224,12 @@ function analyzeMilestonePhases(cwd, version) {
     let diskStatus = 'no_directory';
 
     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);
       const dirMatch = dirs.find(d => d.startsWith(padded + '-') || d === padded);
 
       if (dirMatch) {
-        const phaseFiles = fs.readdirSync(path.join(phasesDir, dirMatch));
+        const phaseFiles = fs.readdirSync(path.join(phasesAbs, dirMatch));
         const planCount = phaseFiles.filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md').length;
         const summaryCount = phaseFiles.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md').length;
         const hasContext = phaseFiles.some(f => f.endsWith('-CONTEXT.md') || f === 'CONTEXT.md');
@@ -1708,7 +1710,9 @@ function generateJobSummary(cwd, version) {
   try {
     const milestonePhases = analyzeMilestonePhases(cwd, normalizedVersion);
     const projectRoot = resolveProjectRoot(cwd);
-    const phasesDir = path.join(projectRoot, 'phases');
+    let phasesAbs;
+    try { phasesAbs = path.join(cwd, phasesDir(cwd)); }
+    catch { phasesAbs = path.join(projectRoot, 'phases'); }
 
     for (const phase of milestonePhases) {
       const phaseNum = phase.number;
@@ -1717,7 +1721,7 @@ function generateJobSummary(cwd, version) {
       // Find the phase directory on disk
       let phaseDir = null;
       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);
         phaseDir = dirs.find(d => d.startsWith(padded + '-') || d === padded);
       } catch {}
@@ -1725,7 +1729,7 @@ function generateJobSummary(cwd, version) {
       if (!phaseDir) continue;
 
       // Look for UAT file
-      const uatPath = path.join(phasesDir, phaseDir, `${padded}-UAT.md`);
+      const uatPath = path.join(phasesAbs, phaseDir, `${padded}-UAT.md`);
       let uatContent = null;
       try {
         uatContent = fs.readFileSync(uatPath, 'utf-8');
@@ -1921,7 +1925,9 @@ function rollbackJob(cwd, version) {
 
   // Identify executed phases from completed steps
   const projectRoot = resolveProjectRoot(cwd);
-  const phasesDir = path.join(projectRoot, 'phases');
+  let phasesAbs;
+  try { phasesAbs = path.join(cwd, phasesDir(cwd)); }
+  catch { phasesAbs = path.join(projectRoot, 'phases'); }
 
   for (const step of parsed.steps) {
     if (step.status === 'completed' && step.command === 'execute-phase') {
@@ -1932,12 +1938,12 @@ function rollbackJob(cwd, version) {
       const padded = phaseNum.replace(/^(\d+)/, (m) => m.padStart(2, '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);
         const dirMatch = dirs.find(d => d.startsWith(padded + '-') || d === padded);
 
         if (dirMatch) {
-          const phaseDir = path.join(phasesDir, dirMatch);
+          const phaseDir = path.join(phasesAbs, dirMatch);
           const phaseFiles = fs.readdirSync(phaseDir);
           const summaryFiles = phaseFiles.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md');
 

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

@@ -2124,8 +2124,24 @@ Plans:
     });
 
     it('returns not_in_progress when job is in pending/', () => {
+      // findJobFile's contract: frontmatter Status is authoritative, the
+      // legacy directory is advisory only ("Frontmatter wins"). A genuinely
+      // pending job therefore needs Status: pending in its frontmatter — using
+      // a status:in-progress fixture here would (correctly) be cancellable.
+      const PENDING_JOB = `# Milestone Job: v6.0
+
+**Version:** v6.0
+**Created:** 2026-03-02T10:00:00Z
+**Status:** pending
+**Check:** true
+
+## Steps
+
+- [ ] \`/dgs:plan-phase 41\`
+- [ ] \`/dgs:execute-phase 41\`
+`;
       fixture = createFixture({
-        'jobs/pending/milestone-v6.0.md': WELL_FORMED_JOB,
+        'jobs/pending/milestone-v6.0.md': PENDING_JOB,
       });
       const result = cancelJob(fixture.cwd, 'v6.0');
 

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

@@ -423,6 +423,14 @@ describe('CLI: migrate command (MIG-08, OPT-02)', () => {
 
   beforeEach(() => {
     dir = makeGitDir();
+    // Real DGS repos gitignore config.local.json — the local half of the
+    // documented two-file config layout (config.json tracked / config.local.json
+    // gitignored). dgs-tools writes config.local.json on startup (e.g.
+    // { branching_migration_done: true }); without the .gitignore that real
+    // installs carry, that untracked write dirties the tree and trips migrate's
+    // (correct) clean-working-tree guard with exit 1. Mirror the real layout so
+    // the guard is exercised honestly rather than failing on a fixture artifact.
+    writeFile(dir, '.gitignore', 'config.local.json\n');
   });
 
   afterEach(() => {

package/deliver-great-systems/bin/lib/milestone-archival.test.cjs

@@ -0,0 +1,186 @@
+/**
+ * Tests for cmdMilestoneComplete — structural phase archival (Phase 167, NUM-03/NUM-04)
+ *
+ * Covers the versioned single-move archival path, the collision-abort guard,
+ * mixed-layout correctness, and flat-mode preservation.
+ *
+ * Uses Node.js built-in test runner (node:test) and assert (node:assert/strict).
+ * Each test creates an isolated temp directory fixture and cleans up after.
+ */
+
+const { describe, it, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
+
+const { createFixture } = require('./test-helpers.cjs');
+const { cmdMilestoneComplete } = require('./milestone.cjs');
+
+// Helper: capture stdout from cmdMilestoneComplete (which calls output()).
+// Also stubs process.exit so error()-guarded paths return instead of exiting.
+function captureResult(fn) {
+  const chunks = [];
+  const origWrite = process.stdout.write;
+  process.stdout.write = function (chunk) {
+    chunks.push(String(chunk));
+  };
+  const origStderrWrite = process.stderr.write;
+  process.stderr.write = function () {};
+  const origExit = process.exit;
+  process.exit = function () {};
+  try {
+    fn();
+  } finally {
+    process.stdout.write = origWrite;
+    process.stderr.write = origStderrWrite;
+    process.exit = origExit;
+  }
+  const raw = chunks.join('');
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Creates a root-layout fixture suitable for cmdMilestoneComplete.
+ * Pass `extras` to add/override structure entries (e.g. a versioned STATE.md
+ * with current_milestone frontmatter and phases/v26.0/ dirs).
+ */
+function createMilestoneFixture(extras) {
+  const base = {
+    'config.json': JSON.stringify({}),
+    'config.local.json': JSON.stringify({ planningRoot: '.' }),
+    'STATE.md': '# Project State\n\nPhase: 1\nStatus: Ready\nProgress: [----------] 0%\n',
+    'ROADMAP.md': '# Roadmap\n\n## Phase 1: Test\n',
+    'phases/': null,
+  };
+  if (extras) {
+    Object.assign(base, extras);
+  }
+  return createFixture(base);
+}
+
+// Versioned STATE.md with current_milestone frontmatter so resolveMilestoneVersion → v26.0.
+const VERSIONED_STATE =
+  '---\ncurrent_milestone: v26.0\nmilestone: v26.0\n---\n\n# Project State\n\nPhase: 1\nStatus: Ready\n';
+
+describe('cmdMilestoneComplete versioned structural archival', () => {
+  let fixture;
+
+  afterEach(() => {
+    if (fixture) fixture.cleanup();
+    fixture = undefined;
+  });
+
+  it('versioned single-move: archives phases/v26.0 to milestones/v26.0-phases via one rename', () => {
+    fixture = createMilestoneFixture({
+      'STATE.md': VERSIONED_STATE,
+      'phases/v26.0/01-foo/01-foo-SUMMARY.md': '---\none-liner: foo\n---\n## Task 1\n',
+      'phases/v26.0/02-bar/02-bar-SUMMARY.md': '---\none-liner: bar\n---\n## Task 1\n',
+    });
+    const cwd = fixture.cwd;
+
+    const result = captureResult(() => {
+      cmdMilestoneComplete(cwd, 'v26.0', { archivePhases: true }, false);
+    });
+
+    assert.ok(
+      fs.existsSync(path.join(cwd, 'milestones', 'v26.0-phases', '01-foo')),
+      '01-foo should be archived under milestones/v26.0-phases/'
+    );
+    assert.ok(
+      fs.existsSync(path.join(cwd, 'milestones', 'v26.0-phases', '02-bar')),
+      '02-bar should be archived under milestones/v26.0-phases/'
+    );
+    assert.ok(
+      !fs.existsSync(path.join(cwd, 'phases', 'v26.0')),
+      'phases/v26.0 should be MOVED (not copied) — source must no longer exist'
+    );
+    assert.ok(result, 'Should return result JSON');
+    assert.equal(result.archived.phases, true, 'archived.phases should be true');
+  });
+
+  it('versioned collision abort: aborts when milestones/v26.0-phases already exists, leaves source intact', () => {
+    fixture = createMilestoneFixture({
+      'STATE.md': VERSIONED_STATE,
+      'phases/v26.0/01-foo/01-foo-SUMMARY.md': '---\none-liner: foo\n---\n## Task 1\n',
+      'milestones/v26.0-phases/old/keep.md': 'PRESERVE ME',
+    });
+    const cwd = fixture.cwd;
+
+    captureResult(() => {
+      cmdMilestoneComplete(cwd, 'v26.0', { archivePhases: true }, false);
+    });
+
+    // Source NOT moved on collision.
+    assert.ok(
+      fs.existsSync(path.join(cwd, 'phases', 'v26.0', '01-foo')),
+      'source phases/v26.0/01-foo should still exist after collision abort'
+    );
+    // Pre-existing archive untouched — no overwrite, no merge.
+    const keepPath = path.join(cwd, 'milestones', 'v26.0-phases', 'old', 'keep.md');
+    assert.ok(fs.existsSync(keepPath), 'pre-existing archive entry should be untouched');
+    assert.equal(
+      fs.readFileSync(keepPath, 'utf-8'),
+      'PRESERVE ME',
+      'pre-existing archive content should not be overwritten'
+    );
+    // No source dir merged into the existing archive.
+    assert.ok(
+      !fs.existsSync(path.join(cwd, 'milestones', 'v26.0-phases', '01-foo')),
+      'source dir should NOT be merged into the existing archive'
+    );
+  });
+
+  it('mixed-layout: archives only phases/v26.0, leaves sibling flat phases/NN-slug dirs untouched', () => {
+    fixture = createMilestoneFixture({
+      'STATE.md': VERSIONED_STATE,
+      'phases/v26.0/01-foo/01-foo-SUMMARY.md': '---\none-liner: foo\n---\n## Task 1\n',
+      'phases/90-legacy/PLAN.md': '# Legacy flat phase',
+    });
+    const cwd = fixture.cwd;
+
+    captureResult(() => {
+      cmdMilestoneComplete(cwd, 'v26.0', { archivePhases: true }, false);
+    });
+
+    assert.ok(
+      fs.existsSync(path.join(cwd, 'milestones', 'v26.0-phases', '01-foo')),
+      'versioned phase 01-foo should be archived'
+    );
+    assert.ok(
+      fs.existsSync(path.join(cwd, 'phases', '90-legacy', 'PLAN.md')),
+      'unrelated sibling flat phase phases/90-legacy/ must NOT be disturbed'
+    );
+    assert.ok(
+      !fs.existsSync(path.join(cwd, 'phases', 'v26.0')),
+      'versioned subtree should be moved away'
+    );
+  });
+
+  it('flat mode preserved: per-directory filtered move still works (no frontmatter version)', () => {
+    fixture = createMilestoneFixture({
+      'ROADMAP.md': '# Roadmap\n\n## Phase 1: Test\n',
+      'phases/01-foo/01-foo-SUMMARY.md': '---\none-liner: foo\n---\n## Task 1\n',
+    });
+    const cwd = fixture.cwd;
+
+    const result = captureResult(() => {
+      cmdMilestoneComplete(cwd, 'v1.0', { archivePhases: true }, false);
+    });
+
+    assert.ok(
+      fs.existsSync(path.join(cwd, 'milestones', 'v1.0-phases', '01-foo')),
+      'flat per-dir move should archive 01-foo to milestones/v1.0-phases/'
+    );
+    // Flat phases/ is mkdir-archived FROM, not moved wholesale → it still exists as a dir.
+    assert.ok(
+      fs.existsSync(path.join(cwd, 'phases')),
+      'flat phases/ directory should still exist (archived from, not moved wholesale)'
+    );
+    assert.ok(result, 'Should return result JSON');
+    assert.equal(result.archived.phases, true, 'archived.phases should be true in flat mode');
+  });
+});