@ktpartners/dgs-platform 3.4.1 → 3.5.0

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

@@ -99,22 +99,22 @@ describe('parseTierDefinitions', () => {
     assert.equal(none.files.length, 0, 'none tier files should be empty');
   });
 
-  it('lite tier has 3 files (PROJECT.md, STATE.md, config.json)', () => {
+  it('lite tier has 4 files (PROJECT.md, PRODUCT-SUMMARY.md, STATE.md, config.json)', () => {
     const tiers = parseTierDefinitions();
     const lite = tiers.get('lite');
     assert.ok(Array.isArray(lite.files), 'lite tier files should be array');
-    assert.equal(lite.files.length, 3, 'lite tier should have 3 files');
+    assert.equal(lite.files.length, 4, 'lite tier should have 4 files');
     const paths = lite.files.map(f => f.path);
     assert.ok(paths.includes('PROJECT.md'), 'should include PROJECT.md');
     assert.ok(paths.includes('STATE.md'), 'should include STATE.md');
     assert.ok(paths.includes('config.json'), 'should include config.json');
   });
 
-  it('planning tier has 3 own files plus dynamic codebase glob', () => {
+  it('planning tier has 4 own files plus dynamic codebase glob', () => {
     const tiers = parseTierDefinitions();
     const planning = tiers.get('planning');
     assert.ok(Array.isArray(planning.files), 'planning tier files should be array');
-    assert.equal(planning.files.length, 3, 'planning tier should have 3 own files');
+    assert.equal(planning.files.length, 4, 'planning tier should have 4 own files');
     const paths = planning.files.map(f => f.path);
     assert.ok(paths.includes('ROADMAP.md'), 'should include ROADMAP.md');
     assert.ok(paths.includes('REQUIREMENTS.md'), 'should include REQUIREMENTS.md');
@@ -674,20 +674,20 @@ describe('resolveTierFiles', () => {
   it('returns lite files for lite tier', () => {
     const tiers = parseTierDefinitions();
     const result = resolveTierFiles('lite', tiers);
-    assert.equal(result.length, 3);
+    assert.equal(result.length, 4);
   });
 
   it('planning tier inherits lite files', () => {
     const tiers = parseTierDefinitions();
     const result = resolveTierFiles('planning', tiers);
-    // lite has 3, planning adds 3 more
-    assert.equal(result.length, 6, 'planning should have 6 static files (3 lite + 3 planning)');
+    // lite has 4, planning adds 4 more
+    assert.equal(result.length, 8, 'planning should have 8 static files (4 lite + 4 planning)');
   });
 
   it('execution tier inherits planning+lite files', () => {
     const tiers = parseTierDefinitions();
     const result = resolveTierFiles('execution', tiers);
-    // execution has files: [] itself but inherits from planning which has 6
-    assert.equal(result.length, 6, 'execution inherits all planning files');
+    // execution has files: [] itself but inherits from planning which has 8
+    assert.equal(result.length, 8, 'execution inherits all planning files');
   });
 });

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

@@ -289,18 +289,17 @@ function findPhaseInternal(cwd, phase) {
 
   const normalized = normalizePhaseName(phase);
 
-  // Resolve phases directory: project root or '.' fallback
-  let projectRoot;
+  // Resolve phases directory via canonical resolver; keep soft '.' fallback
+  let phasesRel;
   try {
-    projectRoot = getProjectRoot(cwd);
+    phasesRel = phasesDir(cwd);
   } catch {
-    projectRoot = '.';
+    phasesRel = 'phases';   // flat-layout fallback (== path.join('.', 'phases'))
   }
-  const phasesRel = path.join(projectRoot, 'phases');
-  const phasesDir = path.join(cwd, phasesRel);
+  const phasesAbs = path.join(cwd, phasesRel);
 
   // Search current phases first
-  const current = searchPhaseInDir(phasesDir, phasesRel, normalized);
+  const current = searchPhaseInDir(phasesAbs, phasesRel, normalized);
   if (current) return current;
 
   // Search archived milestone phases (newest first)
@@ -318,6 +317,12 @@ function findPhaseInternal(cwd, phase) {
       .reverse();
 
     const planRootRel = path.relative(cwd, planRoot);
+
+    // LOOK-01: collect ALL archive matches before deciding, instead of
+    // returning the first newest-first hit. Once phase numbers restart per
+    // milestone (Phase 165), a bare number can collide across several milestone
+    // archives; silently returning the newest is a correctness bug.
+    const collected = [];
     for (const archiveName of archiveDirs) {
       const version = archiveName.match(/^(v[\d.]+)-phases$/)[1];
       const archivePath = path.join(milestonesDir, archiveName);
@@ -325,9 +330,35 @@ function findPhaseInternal(cwd, phase) {
       const result = searchPhaseInDir(archivePath, relBase, normalized);
       if (result) {
         result.archived = version;
-        return result;
+        collected.push({ version, result });
       }
     }
+
+    // Branch on the collected count:
+    //  - 0 matches  → null (unchanged)
+    //  - 1 match    → return that match with .archived set — BYTE-IDENTICAL to
+    //                 the previous single-archive path. Flat-layout / globally-
+    //                 unique numbers always land here, so their behaviour is
+    //                 preserved exactly.
+    //  - 2+ matches → return a PINNED, NON-throwing structured ambiguity signal:
+    //                 { found:false, ambiguous:true, phase, matches:[{milestone,
+    //                 directory}...], message }. It carries NO top-level
+    //                 `directory` and NO single `archived` tag, so callers that
+    //                 guard on `!phaseInfo.found` treat it as not-found, while
+    //                 hardened callers surface its `message`. This object shape
+    //                 is part of findPhaseInternal's return contract.
+    if (collected.length === 0) return null;
+    if (collected.length === 1) return collected[0].result;
+
+    const versions = collected.map(c => c.version);
+    const newestVersion = [...versions].sort().reverse()[0];
+    return {
+      found: false,
+      ambiguous: true,
+      phase: normalized,
+      matches: collected.map(c => ({ milestone: c.version, directory: c.result.directory })),
+      message: `Phase ${normalized} is ambiguous across milestones ${versions.join(', ')} — use a milestone-qualified reference (e.g. ${newestVersion}/${normalized})`,
+    };
   } catch {}
 
   return null;
@@ -514,12 +545,122 @@ function getMilestoneInfo(cwd) {
   }
 }
 
+// ─── Authoritative milestone-version signal (Phase 163-01) ─────────────────────
+//
+// Grounding (verified 2026-06-25) — the canonical structured field name:
+//   - The field persisted in STATE.md frontmatter TODAY is `milestone:`
+//     (written by state.cjs buildStateFrontmatter, derived from the getMilestoneInfo
+//     ROADMAP prose scrape). `current_milestone` exists only in init.cjs JSON output
+//     (init.cjs:560), NOT as a persisted STATE.md field.
+//   - The spec/CONTEXT name the authoritative field `current_milestone`.
+//   - To honour the locked name WHILE staying compatible with what exists today,
+//     resolveMilestoneVersion reads `current_milestone` FIRST and falls back to
+//     `milestone` SECOND. Plan 02 standardises the writer on `current_milestone`.
+//
+// This is the structured-first, grammar-validated, FAIL-LOUD signal. It deliberately
+// does NOT trust getMilestoneInfo's `v1.0` default — that scrape is advisory only and
+// is consulted here solely for an optional mismatch warning.
+
+/** Canonical milestone-version grammar (RSLV-05): exactly `vN.N`, no trim, no flags. */
+const MILESTONE_VERSION_RE = /^v\d+\.\d+$/;
+
+/**
+ * Validate a milestone-version string against the canonical grammar `^v\d+\.\d+$`.
+ * Out-of-grammar values are rejected, never coerced. Does NOT trim — trimming is the
+ * caller's choice, so malformed (whitespace-padded) input is not silently masked.
+ *
+ * @param {*} value
+ * @returns {boolean}
+ */
+function isValidMilestoneVersion(value) {
+  return typeof value === 'string' && MILESTONE_VERSION_RE.test(value);
+}
+
+/**
+ * Resolve the current milestone version from the structured STATE.md frontmatter
+ * field (authoritative), validate it against the canonical grammar, and FAIL LOUD
+ * when it is required but undeterminable. NEVER defaults to or returns 'v1.0'.
+ *
+ * Read precedence within STATE.md frontmatter: `current_milestone` then `milestone`.
+ * On a STATE-vs-ROADMAP mismatch, warns to stderr and trusts STATE.
+ *
+ * @param {string} cwd - Working directory
+ * @param {{ required?: boolean }} [opts]
+ * @returns {string|null} The validated `vN.N` version, or null when undeterminable
+ *                        and not required.
+ * @throws {Error} when required is true and the version is undeterminable/invalid.
+ */
+function resolveMilestoneVersion(cwd, { required = false } = {}) {
+  const remediation =
+    "Cannot determine current milestone version — set 'current_milestone' " +
+    '(e.g. v25.0) in STATE.md frontmatter.';
+
+  // 1. Read STATE.md (structured, authoritative). Mirror getMilestoneInfo's
+  //    project-scoped read: project STATE.md first, then planning-root STATE.md.
+  let stateContent = null;
+  try {
+    const projectRoot = getProjectRoot(cwd);
+    stateContent = safeReadFile(path.join(cwd, projectRoot, 'STATE.md'));
+  } catch {
+    stateContent = null;
+  }
+  if (stateContent === null) {
+    stateContent = safeReadFile(path.join(getPlanningRoot(cwd), 'STATE.md'));
+  }
+
+  // 2. Local minimal frontmatter parse. Intentionally does NOT import the
+  //    frontmatter parser module to avoid a require cycle (that module requires this one).
+  let raw;
+  if (stateContent) {
+    const fmMatch = stateContent.match(/^---\n([\s\S]+?)\n---/);
+    if (fmMatch) {
+      const block = fmMatch[1];
+      const currentMatch = block.match(/^current_milestone:\s*["']?(\S+?)["']?\s*$/m);
+      const fallbackMatch = block.match(/^milestone:\s*["']?(\S+?)["']?\s*$/m);
+      raw = (currentMatch && currentMatch[1]) || (fallbackMatch && fallbackMatch[1]);
+    }
+  }
+
+  // 3-4. Valid grammar → optional advisory mismatch warning, then return.
+  if (isValidMilestoneVersion(raw)) {
+    try {
+      const advisory = getMilestoneInfo(cwd);
+      if (advisory && advisory.version && advisory.version !== raw) {
+        process.stderr.write(
+          `Warning: milestone version mismatch — STATE.md says ${raw} but ROADMAP ` +
+          `says ${advisory.version}. Trusting STATE.md (${raw}).\n`
+        );
+      }
+    } catch { /* advisory only — never block on the prose scrape */ }
+    return raw;
+  }
+
+  // 5-6. Present-but-invalid or absent → fail loud if required, else null.
+  //      The abandoned getMilestoneInfo default is deliberately NOT used here.
+  if (required) {
+    throw new Error(remediation);
+  }
+  return null;
+}
+
 /**
  * Returns a filter function that checks whether a phase directory belongs
- * to the current milestone based on ROADMAP.md phase headings.
+ * to the current milestone.
+ * Under versioned layout (phases/<version>/) membership is structural — every
+ * entry already belongs to the milestone — so this returns a pass-all predicate.
+ * Under flat layout (shared phases/) it returns a ROADMAP number-set predicate.
  * If no ROADMAP exists or no phases are listed, returns a pass-all filter.
  */
 function getMilestonePhaseFilter(cwd) {
+  // Versioned layout: phases/<version>/ is already milestone-scoped — every entry belongs to the milestone, so number-set filtering is redundant (NUM-04).
+  let versioned = false;
+  try { versioned = /^v\d+\.\d+$/.test(path.basename(phasesDir(cwd))); } catch { versioned = false; }
+  if (versioned) {
+    const passAll = () => true;
+    passAll.phaseCount = 0;
+    return passAll;
+  }
+
   const milestonePhaseNums = new Set();
   try {
     let roadmap;
@@ -662,6 +803,52 @@ function resolveProjectPath(cwd, relativePath) {
   return relativePath ? path.join(root, relativePath) : root;
 }
 
+/**
+ * Canonical resolver for the active-project phases directory.
+ *
+ * Returns the RELATIVE project-scoped phases path:
+ *   - v2 layout: 'projects/<slug>/phases'
+ *   - v1 / flat layout: 'phases'
+ *
+ * FAIL-LOUD: delegates to resolveProjectPath -> requireProjectRoot, which
+ * throws when there is no project root. Callers that want a soft fallback
+ * (e.g. flat-layout tooling) keep their own try/catch around this call —
+ * the fallback policy stays local to each call site, never buried here.
+ *
+ * This is the SINGLE seam for phases-path resolution, and it IS version-aware
+ * (Phase 165 / RSLV-04): when a 'phases/<version>' directory exists on disk under
+ * the active project — where <version> is the validated `vN.N` milestone signal
+ * (resolveMilestoneVersion, Phase 163) — it returns the RELATIVE versioned path
+ * 'phases/<version>'. Otherwise it falls back to flat 'phases'. The fallback is
+ * permanent and intentional (dual-mode cutover): pre-existing flat layouts and the
+ * in-flight milestone (no 'phases/<version>' dir on disk) resolve FLAT by design —
+ * versioning is never applied retroactively. The read path NEVER defaults to 'v1.0'
+ * and NEVER throws on an undeterminable version (it just resolves flat).
+ *
+ * Do not reintroduce ad-hoc path.join(...,'phases') sites — path-audit.test.cjs
+ * gates against that. The only phases-bearing joins below are path.join(base, version)
+ * (relative return) and the existsSync probe path.join(cwd, base, version); neither is
+ * a bare path.join(..., 'phases') literal, so the 164-05 gate stays satisfied.
+ *
+ * @param {string} cwd - Working directory
+ * @returns {string} Relative project-scoped phases path ('phases', 'projects/<slug>/phases',
+ *                   or the versioned '…/phases/<version>')
+ * @throws {Error} NO_CURRENT_PROJECT_V2 | PROJECT_NOT_FOUND | INVALID_PROJECT_NAME | PROJECT_COMPLETED
+ */
+function phasesDir(cwd) {
+  const base = resolveProjectPath(cwd, 'phases');   // RELATIVE, fail-loud (unchanged)
+  let version = null;
+  try {
+    version = resolveMilestoneVersion(cwd);          // non-required: validated vN.N or null, never throws, never v1.0
+  } catch {
+    version = null;                                  // read path never blocks on an undeterminable version
+  }
+  if (version && fs.existsSync(path.join(cwd, base, version))) {
+    return path.join(base, version);                 // versioned dir present → return RELATIVE versioned path
+  }
+  return base;                                       // dual-mode fallback: flat phases/ (incl. the in-flight v25.0)
+}
+
 /**
  * Check if a project is completed by reading its STATE.md directly.
  *
@@ -749,9 +936,12 @@ module.exports = {
   pathExistsInternal,
   generateSlugInternal,
   getMilestoneInfo,
+  isValidMilestoneVersion,
+  resolveMilestoneVersion,
   getMilestonePhaseFilter,
   toPosixPath,
   resolveProjectPath,
+  phasesDir,
   getProjectRoot,
   requireProjectRoot,
   isV2Install,

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 */ }