@ktpartners/dgs-platform 3.4.2 → 3.5.1

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

@@ -16,6 +16,7 @@ const { createFixture, createTempProject } = require('./test-helpers.cjs');
 // Import the functions under test
 const {
   resolveProjectPath,
+  phasesDir,
   getProjectRoot,
   requireProjectRoot,
   isV2Install,
@@ -26,6 +27,7 @@ const {
   getProjectDir,
   resolveModelInternal,
   MODEL_PROFILES,
+  findPhaseInternal,
 } = require('./core.cjs');
 
 // ─── Root layout (no v2 markers) Tests ───────────────────────────────────────
@@ -145,6 +147,246 @@ describe('v2 mode without current_project (guard trigger)', () => {
   });
 });
 
+// ─── phasesDir canonical resolver contract Tests ──────────────────────────────
+
+describe('phasesDir canonical resolver', () => {
+  it('v1/flat layout returns phases', () => {
+    const fixture = createFixture({
+      'config.json': JSON.stringify({}),
+      'STATE.md': '# State',
+      'ROADMAP.md': '# Roadmap',
+      'phases/': null,
+    });
+
+    try {
+      const result = phasesDir(fixture.cwd);
+      assert.equal(result, path.join('.', 'phases'));
+      assert.equal(result, 'phases');
+    } finally {
+      fixture.cleanup();
+    }
+  });
+
+  it('v2 layout returns projects/<slug>/phases', () => {
+    const fixture = createFixture({
+      'config.json': JSON.stringify({}),
+      'config.local.json': JSON.stringify({ current_project: 'auth-overhaul' }),
+      'PROJECTS.md': '# Projects\n\n| Project | Status |\n',
+      'REPOS.md': '# Repos\n\n| Name | Path |\n',
+      'projects/auth-overhaul/STATE.md': '# State',
+      'projects/auth-overhaul/ROADMAP.md': '# Roadmap',
+      'projects/auth-overhaul/phases/': null,
+    });
+
+    try {
+      const result = phasesDir(fixture.cwd);
+      assert.equal(result, path.join('projects', 'auth-overhaul', 'phases'));
+    } finally {
+      fixture.cleanup();
+    }
+  });
+
+  it('v2 install with NO current_project throws (fail-loud, no fallback)', () => {
+    const fixture = createFixture({
+      'config.json': JSON.stringify({}),
+      'PROJECTS.md': '# Projects\n\n| Project | Status |\n',
+    });
+
+    try {
+      assert.throws(
+        () => phasesDir(fixture.cwd),
+        (err) => err.message === 'NO_CURRENT_PROJECT_V2'
+      );
+    } finally {
+      fixture.cleanup();
+    }
+  });
+});
+
+// ─── Version-aware (dual-mode) resolver Tests (Phase 165, RSLV-04) ─────────────
+
+describe('phasesDir version-aware (dual-mode)', () => {
+  // Shared v2 project context builder. STATE.md frontmatter `current_milestone`
+  // is what resolveMilestoneVersion reads; `phasesExtra` lets each test add the
+  // versioned sub-directory (or not) to exercise the existsSync branch.
+  function v2Fixture(stateBody, phasesExtra) {
+    const tree = {
+      'config.json': JSON.stringify({}),
+      'config.local.json': JSON.stringify({ current_project: 'auth-overhaul' }),
+      'PROJECTS.md': '# Projects\n\n| Project | Status |\n',
+      'REPOS.md': '# Repos\n\n| Name | Path |\n',
+      'projects/auth-overhaul/PROJECT.md': '# Project',
+      'projects/auth-overhaul/STATE.md': stateBody,
+      'projects/auth-overhaul/ROADMAP.md': '# Roadmap',
+      'projects/auth-overhaul/phases/': null,
+    };
+    if (phasesExtra) tree[phasesExtra] = null;
+    return createFixture(tree);
+  }
+
+  it('Test A: versioned dir present → returns projects/<slug>/phases/<version>', () => {
+    const fixture = v2Fixture(
+      '---\ncurrent_milestone: v26.0\n---\n# State',
+      'projects/auth-overhaul/phases/v26.0/'
+    );
+    try {
+      const result = phasesDir(fixture.cwd);
+      assert.equal(
+        result,
+        path.join('projects', 'auth-overhaul', 'phases', 'v26.0')
+      );
+    } finally {
+      fixture.cleanup();
+    }
+  });
+
+  it('Test B: version present but NO versioned dir → flat fallback (v25.0 invariant)', () => {
+    const fixture = v2Fixture(
+      '---\ncurrent_milestone: v25.0\n---\n# State',
+      null
+    );
+    try {
+      const result = phasesDir(fixture.cwd);
+      assert.equal(result, path.join('projects', 'auth-overhaul', 'phases'));
+      assert.ok(!result.includes('v25.0'), `must not resolve versioned: ${result}`);
+    } finally {
+      fixture.cleanup();
+    }
+  });
+
+  it('Test C: version undeterminable → flat fallback, no throw, never v1.0', () => {
+    const fixture = v2Fixture('# State (no milestone frontmatter)', null);
+    try {
+      let result;
+      assert.doesNotThrow(() => { result = phasesDir(fixture.cwd); });
+      assert.equal(result, path.join('projects', 'auth-overhaul', 'phases'));
+      assert.ok(!result.includes('v1.0'), `must never default to v1.0: ${result}`);
+    } finally {
+      fixture.cleanup();
+    }
+  });
+
+  it('Test D: flat/v1 layout unchanged (regression guard)', () => {
+    const fixture = createFixture({
+      'config.json': JSON.stringify({}),
+      'STATE.md': '# State',
+      'ROADMAP.md': '# Roadmap',
+      'phases/': null,
+    });
+    try {
+      const result = phasesDir(fixture.cwd);
+      assert.equal(result, 'phases');
+    } finally {
+      fixture.cleanup();
+    }
+  });
+});
+
+// ─── findPhaseInternal version-aware archive (LOOK-01) Tests ──────────────────
+
+describe('findPhaseInternal version-aware archive (LOOK-01)', () => {
+  // Build a v2 project with active phases plus milestone archives. Active phases
+  // live (flat, v25.0 invariant) at projects/<slug>/phases/<NN>-slug/; archives
+  // live product-level at milestones/<v>-phases/<NN>-slug/. Each phase dir needs
+  // at least one *-PLAN.md so searchPhaseInDir matches it.
+  function look01Fixture(activePhaseDirs, archives) {
+    const tree = {
+      'config.json': JSON.stringify({}),
+      'config.local.json': JSON.stringify({ current_project: 'auth-overhaul' }),
+      'PROJECTS.md': '# Projects\n\n| Project | Status |\n',
+      'REPOS.md': '# Repos\n\n| Name | Path |\n',
+      'projects/auth-overhaul/PROJECT.md': '# Project',
+      'projects/auth-overhaul/STATE.md': '---\ncurrent_milestone: v25.0\n---\n# State',
+      'projects/auth-overhaul/ROADMAP.md': '# Roadmap',
+      'projects/auth-overhaul/phases/': null,
+    };
+    for (const dir of activePhaseDirs || []) {
+      tree[`projects/auth-overhaul/phases/${dir}/01-PLAN.md`] = '# Plan';
+    }
+    // archives: { 'v3.0': ['07-foo'], 'v4.0': ['03-b'], ... }
+    for (const [version, dirs] of Object.entries(archives || {})) {
+      for (const dir of dirs) {
+        tree[`milestones/${version}-phases/${dir}/01-PLAN.md`] = '# Plan';
+      }
+    }
+    return createFixture(tree);
+  }
+
+  it('Test 1: active phase wins (unchanged) — bare number in active phases', () => {
+    const fixture = look01Fixture(
+      ['03-active-feature'],
+      { 'v3.0': ['03-archived-feature'] }
+    );
+    try {
+      const result = findPhaseInternal(fixture.cwd, '03');
+      assert.ok(result, 'expected an active match');
+      assert.equal(result.found, true);
+      assert.equal(result.archived, undefined, 'active match must not carry .archived');
+      assert.equal(result.ambiguous, undefined, 'active match must not be ambiguous');
+      assert.ok(result.directory.includes('03-active-feature'));
+    } finally {
+      fixture.cleanup();
+    }
+  });
+
+  it('Test 2: unique archive (flat-layout preserved) — bare number in exactly ONE archive', () => {
+    const fixture = look01Fixture(
+      [],
+      { 'v3.0': ['07-foo'] }
+    );
+    try {
+      const result = findPhaseInternal(fixture.cwd, '07');
+      assert.ok(result, 'expected a single archived match');
+      assert.equal(result.found, true, 'single-archive match preserves found:true');
+      assert.equal(result.archived, 'v3.0', 'single-archive match tagged with its version');
+      assert.equal(result.ambiguous, undefined, 'single archive is not ambiguous');
+      assert.ok(result.directory.includes('07-foo'));
+    } finally {
+      fixture.cleanup();
+    }
+  });
+
+  it('Test 3: cross-milestone collision → structured ambiguity, NOT silent newest', () => {
+    const fixture = look01Fixture(
+      [],
+      { 'v3.0': ['03-a'], 'v4.0': ['03-b'] }
+    );
+    try {
+      const result = findPhaseInternal(fixture.cwd, '03');
+      assert.ok(result, 'expected a structured ambiguity object, not null');
+      assert.equal(result.found, false, 'ambiguity is found:false');
+      assert.equal(result.ambiguous, true, 'ambiguity flag set');
+      assert.equal(result.directory, undefined, 'ambiguity must NOT point at either archive dir');
+      assert.equal(result.archived, undefined, 'ambiguity carries no single archived tag');
+      assert.ok(Array.isArray(result.matches), 'matches is an array');
+      assert.equal(result.matches.length, 2, 'both archives listed');
+      const versions = result.matches.map(m => m.milestone).sort();
+      assert.deepEqual(versions, ['v3.0', 'v4.0'], 'both milestone versions named');
+      assert.ok(typeof result.message === 'string' && result.message.length > 0);
+      assert.ok(result.message.includes('v3.0'), 'message names v3.0');
+      assert.ok(result.message.includes('v4.0'), 'message names v4.0');
+    } finally {
+      fixture.cleanup();
+    }
+  });
+
+  it('Test 4: collision with an active number is irrelevant — active wins', () => {
+    const fixture = look01Fixture(
+      ['01-active'],
+      { 'v3.0': ['01-a'], 'v4.0': ['01-b'] }
+    );
+    try {
+      const result = findPhaseInternal(fixture.cwd, '01');
+      assert.ok(result, 'expected the active match');
+      assert.equal(result.found, true);
+      assert.equal(result.ambiguous, undefined, 'active match short-circuits ambiguity');
+      assert.ok(result.directory.includes('01-active'));
+    } finally {
+      fixture.cleanup();
+    }
+  });
+});
+
 // ─── Strict v2 Marker Validation Tests ────────────────────────────────────────
 
 describe('strict v2 marker validation', () => {

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

@@ -404,6 +404,13 @@ function detectRepoChanges(cwd, repoNames, useActiveContext) {
  */
 function createRepoBranches(cwd, repoNames, branchName, config, baseBranch) {
 
+  // Honour the branching strategy: 'none' disables branch creation entirely.
+  // The function accepts config.branching_strategy and must respect it — a
+  // 'none' strategy is an explicit signal to create no branches.
+  if (config && config.branching_strategy === 'none') {
+    return { created: false, reason: 'branching_disabled' };
+  }
+
   const parsed = parseReposMd(cwd);
   const repos = parsed ? parsed.repos : [];
   const branches = [];

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

@@ -10,7 +10,7 @@
 const fs = require('fs');
 const path = require('path');
 const { extractNameFromAuthor } = require('./identity.cjs');
-const { getMilestonePhaseFilter, getProjectRoot } = require('./core.cjs');
+const { getMilestonePhaseFilter, getProjectRoot, phasesDir } = require('./core.cjs');
 const { extractFrontmatter } = require('./frontmatter.cjs');
 const { getPlanningRoot } = require('./paths.cjs');
 
@@ -58,23 +58,23 @@ function getContributors(cwd) {
     const planRoot = getPlanningRoot(cwd);
     const projectRootRel = getProjectRoot(cwd);
     const projectRoot = path.join(planRoot, projectRootRel);
-    const phasesDir = path.join(projectRoot, 'phases');
+    const phasesAbs = path.join(cwd, phasesDir(cwd));
     const isDirInMilestone = getMilestonePhaseFilter(cwd);
 
-    if (fs.existsSync(phasesDir)) {
-      const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+    if (fs.existsSync(phasesAbs)) {
+      const entries = fs.readdirSync(phasesAbs, { withFileTypes: true });
       const dirs = entries.filter(e => e.isDirectory()).map(e => e.name).sort();
 
       for (const dir of dirs) {
         if (!isDirInMilestone(dir)) continue;
 
-        const phaseFiles = fs.readdirSync(path.join(phasesDir, dir));
+        const phaseFiles = fs.readdirSync(path.join(phasesAbs, dir));
 
         // Read SUMMARY.md executed_by
         const summaries = phaseFiles.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md');
         for (const s of summaries) {
           try {
-            const content = fs.readFileSync(path.join(phasesDir, dir, s), 'utf-8');
+            const content = fs.readFileSync(path.join(phasesAbs, dir, s), 'utf-8');
             const fm = extractFrontmatter(content);
             addContributor(fm.executed_by);
           } catch { /* skip unreadable files */ }
@@ -84,7 +84,7 @@ function getContributors(cwd) {
         const plans = phaseFiles.filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md');
         for (const p of plans) {
           try {
-            const content = fs.readFileSync(path.join(phasesDir, dir, p), 'utf-8');
+            const content = fs.readFileSync(path.join(phasesAbs, dir, p), 'utf-8');
             const fm = extractFrontmatter(content);
             addContributor(fm.created_by);
           } catch { /* skip unreadable files */ }

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();
+    }
+  });
+});