@ktpartners/dgs-platform 3.4.2 → 3.5.1

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

@@ -8,7 +8,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { safeReadFile, execGit, isV2Install, output, error } = require('./core.cjs');
+const { safeReadFile, execGit, isV2Install, output, error, phasesDir } = require('./core.cjs');
 const { writeConfigField } = require('./config.cjs');
 const { getPlanningRoot, resetPaths } = require('./paths.cjs');
 
@@ -997,15 +997,19 @@ function cmdReposRemove(cwd, repoName, options, raw) {
  */
 function scanRepoReferences(cwd, repoName) {
   const references = [];
-  const phasesDir = path.join(getPlanningRoot(cwd), 'phases');
 
   try {
-    const phaseDirs = fs.readdirSync(phasesDir, { withFileTypes: true })
+    // RSLV-03 residue (Phase 170): resolve the project + version scoped phases dir
+    // via the canonical resolver so `repos repo show` finds phase hits under a
+    // versioned layout. phasesDir(cwd) is fail-loud; the throw degrades to empty
+    // references through this same catch, matching the prior readdirSync-throws path.
+    const phasesAbs = path.join(cwd, phasesDir(cwd));
+    const phaseDirs = fs.readdirSync(phasesAbs, { withFileTypes: true })
       .filter(e => e.isDirectory())
       .map(e => e.name);
 
     for (const phaseDir of phaseDirs) {
-      const fullPhaseDir = path.join(phasesDir, phaseDir);
+      const fullPhaseDir = path.join(phasesAbs, phaseDir);
       const planFiles = fs.readdirSync(fullPhaseDir)
         .filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md');
 

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

@@ -618,9 +618,13 @@ describe('writeReposMd -> parseReposMd roundtrip', () => {
   afterEach(() => { resetPaths(); cleanupDir(tmpDir); });
 
   it('write then parse produces identical data', () => {
+    // parseReposMd always returns a `setup` field (defensive 6th-column read);
+    // writeReposMd's standard 4-column table omits an empty setup, so the
+    // roundtrip normalizes setup to '' for every row. Expected objects must
+    // include it to match shipped parser behaviour.
     const repos = [
-      { name: 'web', path: './web', url: 'https://github.com/org/web', description: 'Frontend' },
-      { name: 'api', path: './api', url: '', description: 'Backend API' },
+      { name: 'web', path: './web', url: 'https://github.com/org/web', description: 'Frontend', setup: '' },
+      { name: 'api', path: './api', url: '', description: 'Backend API', setup: '' },
     ];
     writeReposMd(tmpDir, repos);
     const parsed = parseReposMd(tmpDir);

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

@@ -4,7 +4,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { escapeRegex, normalizePhaseName, output, error, findPhaseInternal, resolveProjectPath } = require('./core.cjs');
+const { escapeRegex, normalizePhaseName, output, error, findPhaseInternal, resolveProjectPath, phasesDir } = require('./core.cjs');
 
 function cmdRoadmapGetPhase(cwd, phaseNum, raw) {
   const roadmapPath = path.join(cwd, resolveProjectPath(cwd, 'ROADMAP.md'));
@@ -99,7 +99,7 @@ function cmdRoadmapAnalyze(cwd, raw) {
   }
 
   const content = fs.readFileSync(roadmapPath, 'utf-8');
-  const phasesDir = path.join(cwd, resolveProjectPath(cwd, 'phases'));
+  const phasesAbs = path.join(cwd, phasesDir(cwd));
 
   // Extract all phase headings: ## Phase N: Name or ### Phase N: Name
   const phasePattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:\s*([^\n]+)/gi;
@@ -132,12 +132,12 @@ function cmdRoadmapAnalyze(cwd, raw) {
     let hasResearch = false;
 
     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(normalized + '-') || d === normalized);
 
       if (dirMatch) {
-        const phaseFiles = fs.readdirSync(path.join(phasesDir, dirMatch));
+        const phaseFiles = fs.readdirSync(path.join(phasesAbs, dirMatch));
         planCount = phaseFiles.filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md').length;
         summaryCount = phaseFiles.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md').length;
         hasContext = phaseFiles.some(f => f.endsWith('-CONTEXT.md') || f === 'CONTEXT.md');
@@ -237,8 +237,11 @@ function roadmapUpdatePlanProgressInternal(cwd, phaseNum) {
   const roadmapPath = path.join(cwd, resolveProjectPath(cwd, 'ROADMAP.md'));
 
   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 .plans,
+  // so `phaseInfo.plans.length` is not reached for an ambiguity object. Surface
+  // its milestone-qualified message instead of throwing.
+  if (!phaseInfo || !phaseInfo.found) {
+    error(phaseInfo?.message || `Phase ${phaseNum} not found`);
   }
 
   const planCount = phaseInfo.plans.length;
@@ -265,17 +268,24 @@ function roadmapUpdatePlanProgressInternal(cwd, phaseNum) {
   }
 
   let roadmapContent = fs.readFileSync(roadmapPath, 'utf-8');
-  const phaseEscaped = escapeRegex(phaseNum);
-
-  // Progress table row: update Plans column (summaries/plans) and Status column
+  // Derive a BARE numeric phase key by stripping any leading `vX.Y/` prefix.
+  // Checklist lines and detail headings are always bare, so the bare key drives
+  // the heading/checkbox regexes; the progress-row matcher allows an optional
+  // version prefix and Milestone column on top of the same bare key.
+  const bareKey = String(phaseNum).replace(/^v\d+\.\d+\//, '');
+  const phaseEscaped = escapeRegex(bareKey);
+
+  // Progress table row: update Plans column (summaries/plans) and Status column.
+  // Format-agnostic: optional `vX.Y/` prefix on the Phase cell and an optional
+  // Milestone column (a pure-version cell) between Phase and Plans, both preserved.
   const tablePattern = new RegExp(
-    `(\\|\\s*${phaseEscaped}\\.?\\s[^|]*\\|)[^|]*(\\|)\\s*[^|]*(\\|)\\s*[^|]*(\\|)`,
+    `(\\|\\s*(?:v\\d+\\.\\d+/)?${phaseEscaped}\\.?\\s[^|]*\\|)(\\s*v\\d+\\.\\d+\\s*\\|)?[^|]*(\\|)\\s*[^|]*(\\|)\\s*[^|]*(\\|)`,
     'i'
   );
   const dateField = isComplete ? ` ${today} ` : '  ';
   roadmapContent = roadmapContent.replace(
     tablePattern,
-    `$1 ${summaryCount}/${planCount} $2 ${status.padEnd(11)}$3${dateField}$4`
+    `$1$2 ${summaryCount}/${planCount} $3 ${status.padEnd(11)}$4${dateField}$5`
   );
 
   // Update plan count in phase detail section

package/deliver-great-systems/bin/lib/state-snapshot.test.cjs

@@ -0,0 +1,134 @@
+/**
+ * State snapshot milestone-context test (LOOK-03).
+ *
+ * Dedicated file (no state test file existed before) proving that
+ * `cmdStateSnapshot` ("state-snapshot") surfaces `current_milestone` alongside
+ * the existing `current_phase` so a bare "phase 3" in the snapshot is
+ * unambiguous about which milestone it belongs to.
+ *
+ * The milestone value is read from the AUTHORITATIVE STATE.md frontmatter
+ * signal (Phase 163) with the pinned precedence `current_milestone` then
+ * `milestone`, grammar-validated via isValidMilestoneVersion, and surfaced as
+ * `null` (never coerced, never thrown) when absent/out-of-grammar — existing
+ * snapshot consumers keep working in the flat / pre-versioned case.
+ *
+ * Uses Node.js built-in test runner (node:test) + assert.
+ */
+
+const { describe, it } = require('node:test');
+const assert = require('node:assert');
+const { createFixture } = require('./test-helpers.cjs');
+const { cmdStateSnapshot } = require('./state.cjs');
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+/**
+ * Capture stdout from CLI commands that call output() (process.stdout.write +
+ * process.exit). Mirrors phase-versioned.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 };
+}
+
+/**
+ * v2 project fixture whose STATE.md frontmatter + body the snapshot reads.
+ * `current_project` in config.local.json makes resolveStatePath resolve to
+ * projects/<slug>/STATE.md (mirrors phase-versioned.test.cjs's layout).
+ *
+ * @param {string} frontmatter - YAML lines between the `---` fences (no fences).
+ * @param {string} [body] - markdown body after the frontmatter (defaults to a
+ *   minimal "**Current Phase:** 3" body so current_phase is populated).
+ */
+function stateFixture(frontmatter, body = '\n# Project State\n\n## Current Position\n\n**Current Phase:** 3\n') {
+  const slug = 'demo';
+  const fm = frontmatter ? `---\n${frontmatter}\n---` : '';
+  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`]: `${fm}${body}`,
+  });
+}
+
+// ─── cmdStateSnapshot current_milestone (LOOK-03) ─────────────────────────────
+
+describe('cmdStateSnapshot current_milestone (LOOK-03)', () => {
+  it('Test 1: surfaces current_milestone alongside current_phase (both present)', () => {
+    const fixture = stateFixture('current_milestone: v26.0');
+    try {
+      const { json } = captureStdout(() => cmdStateSnapshot(fixture.cwd, false));
+      assert.ok(json, 'snapshot should emit JSON');
+      // The milestone qualifies the phase: both surfaced, unambiguous together.
+      assert.equal(json.current_milestone, 'v26.0', 'current_milestone surfaced from frontmatter');
+      assert.equal(json.current_phase, '3', 'current_phase still surfaced from body');
+    } finally {
+      fixture.cleanup();
+    }
+  });
+
+  it('Test 2: falls back to milestone when current_milestone absent (real-repo shape)', () => {
+    // Mirrors the real repo: only the advisory `milestone:` field is present.
+    const fixture = stateFixture('milestone: v25.0');
+    try {
+      const { json } = captureStdout(() => cmdStateSnapshot(fixture.cwd, false));
+      assert.ok(json, 'snapshot should emit JSON');
+      // Phase-163 precedence: current_milestone first, milestone second.
+      assert.equal(json.current_milestone, 'v25.0', 'precedence fallback to milestone honoured');
+    } finally {
+      fixture.cleanup();
+    }
+  });
+
+  it('Test 3: absent milestone → null, no throw, rest of snapshot still populated', () => {
+    // Flat / pre-versioned STATE: no milestone frontmatter at all.
+    const fixture = stateFixture('');
+    try {
+      let result;
+      assert.doesNotThrow(() => {
+        result = captureStdout(() => cmdStateSnapshot(fixture.cwd, false));
+      }, 'snapshot must not throw when no milestone signal is present');
+      const json = result.json;
+      assert.ok(json, 'snapshot should emit JSON');
+      assert.equal(json.current_milestone, null, 'current_milestone is null when absent');
+      // Backward-compat: the rest of the snapshot is unaffected.
+      assert.equal(json.current_phase, '3', 'current_phase still populated (no regression)');
+    } finally {
+      fixture.cleanup();
+    }
+  });
+
+  it('Test 4: out-of-grammar current_milestone rejected (null), never coerced', () => {
+    const fixture = stateFixture('current_milestone: garbage');
+    try {
+      const { json } = captureStdout(() => cmdStateSnapshot(fixture.cwd, false));
+      assert.ok(json, 'snapshot should emit JSON');
+      // isValidMilestoneVersion rejects non-^v\d+\.\d+$ → null, never the raw string.
+      assert.equal(json.current_milestone, null, 'out-of-grammar value rejected, not coerced');
+    } finally {
+      fixture.cleanup();
+    }
+  });
+});

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

@@ -4,7 +4,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { loadConfig, getMilestoneInfo, getMilestonePhaseFilter, output, error, getProjectRoot } = require('./core.cjs');
+const { loadConfig, getMilestoneInfo, getMilestonePhaseFilter, output, error, getProjectRoot, phasesDir, isValidMilestoneVersion, execGit } = require('./core.cjs');
 const { extractFrontmatter, reconstructFrontmatter, spliceFrontmatter } = require('./frontmatter.cjs');
 const { getPlanningRoot } = require('./paths.cjs');
 
@@ -296,15 +296,17 @@ function stateUpdateProgressInternal(cwd) {
   let content = fs.readFileSync(statePath, 'utf-8');
 
   // Count summaries across all phases
-  const phasesDir = path.join(cwd, projectRoot, 'phases');
+  let phasesRel;
+  try { phasesRel = phasesDir(cwd); } catch { phasesRel = path.join(projectRoot, 'phases'); }
+  const phasesAbs = path.join(cwd, phasesRel);
   let totalPlans = 0;
   let totalSummaries = 0;
 
-  if (fs.existsSync(phasesDir)) {
-    const phaseDirs = fs.readdirSync(phasesDir, { withFileTypes: true })
+  if (fs.existsSync(phasesAbs)) {
+    const phaseDirs = fs.readdirSync(phasesAbs, { withFileTypes: true })
       .filter(e => e.isDirectory()).map(e => e.name);
     for (const dir of phaseDirs) {
-      const files = fs.readdirSync(path.join(phasesDir, dir));
+      const files = fs.readdirSync(path.join(phasesAbs, dir));
       totalPlans += files.filter(f => f.match(/-PLAN\.md$/i)).length;
       totalSummaries += files.filter(f => f.match(/-SUMMARY\.md$/i)).length;
     }
@@ -502,6 +504,17 @@ function cmdStateSnapshot(cwd, raw) {
 
   const content = fs.readFileSync(statePath, 'utf-8');
 
+  // Resolve the milestone signal that qualifies the current phase (LOOK-03).
+  // Read the AUTHORITATIVE structured frontmatter field (Phase 163) with the
+  // pinned precedence `current_milestone` then `milestone`, grammar-validated.
+  // Surface `null` (never coerced, never thrown) when absent/out-of-grammar so
+  // flat / pre-versioned STATE.md still produces a valid snapshot.
+  const fm = extractFrontmatter(content) || {};
+  let currentMilestone = null;
+  for (const v of [fm.current_milestone, fm.milestone]) {
+    if (isValidMilestoneVersion(v)) { currentMilestone = v; break; }
+  }
+
   // Extract basic fields
   const currentPhase = stateExtractField(content, 'Current Phase');
   const currentPhaseName = stateExtractField(content, 'Current Phase Name');
@@ -571,6 +584,7 @@ function cmdStateSnapshot(cwd, raw) {
   }
 
   const result = {
+    current_milestone: currentMilestone,
     current_phase: currentPhase,
     current_phase_name: currentPhaseName,
     total_phases: totalPhases,
@@ -596,7 +610,7 @@ function cmdStateSnapshot(cwd, raw) {
  * a YAML frontmatter object. Allows hooks and scripts to read state
  * reliably via `state json` instead of fragile regex parsing.
  */
-function buildStateFrontmatter(bodyContent, cwd) {
+function buildStateFrontmatter(bodyContent, cwd, options) {
   const currentPhase = stateExtractField(bodyContent, 'Current Phase');
   const currentPhaseName = stateExtractField(bodyContent, 'Current Phase Name');
   const currentPlan = stateExtractField(bodyContent, 'Current Plan');
@@ -625,16 +639,15 @@ function buildStateFrontmatter(bodyContent, cwd) {
 
   if (cwd) {
     try {
-      let phasesDir;
+      let phasesAbs;
       try {
-        const projectRoot = getProjectRoot(cwd);
-        phasesDir = path.join(cwd, projectRoot, 'phases');
+        phasesAbs = path.join(cwd, phasesDir(cwd));
       } catch {
-        phasesDir = path.join(getPlanningRoot(cwd), 'phases');
+        phasesAbs = path.join(getPlanningRoot(cwd), 'phases');
       }
-      if (fs.existsSync(phasesDir)) {
+      if (fs.existsSync(phasesAbs)) {
         const isDirInMilestone = getMilestonePhaseFilter(cwd);
-        const phaseDirs = fs.readdirSync(phasesDir, { withFileTypes: true })
+        const phaseDirs = fs.readdirSync(phasesAbs, { withFileTypes: true })
           .filter(e => e.isDirectory()).map(e => e.name)
           .filter(isDirInMilestone);
         let diskTotalPlans = 0;
@@ -642,7 +655,7 @@ function buildStateFrontmatter(bodyContent, cwd) {
         let diskCompletedPhases = 0;
 
         for (const dir of phaseDirs) {
-          const files = fs.readdirSync(path.join(phasesDir, dir));
+          const files = fs.readdirSync(path.join(phasesAbs, dir));
           const plans = files.filter(f => f.match(/-PLAN\.md$/i)).length;
           const summaries = files.filter(f => f.match(/-SUMMARY\.md$/i)).length;
           diskTotalPlans += plans;
@@ -689,6 +702,17 @@ function buildStateFrontmatter(bodyContent, cwd) {
 
   const fm = { dgs_state_version: '1.0' };
 
+  // Preserve the authoritative structured current_milestone signal through the
+  // rebuild. The STATE sync re-derives the advisory `milestone`/`milestone_name`
+  // fields from the ROADMAP prose scrape, but the structured `current_milestone`
+  // field is set only by the milestone-lifecycle writers (new-milestone flow +
+  // init.cjs). If the existing frontmatter carries a grammar-valid value, carry
+  // it forward verbatim; reject (omit) out-of-grammar values — never coerce.
+  const existingCM = options && options.existingFm ? options.existingFm.current_milestone : undefined;
+  if (isValidMilestoneVersion(existingCM)) {
+    fm.current_milestone = existingCM;
+  }
+
   if (milestone) fm.milestone = milestone;
   if (milestoneName) fm.milestone_name = milestoneName;
   if (currentPhase) fm.current_phase = currentPhase;
@@ -716,8 +740,12 @@ function stripFrontmatter(content) {
 }
 
 function syncStateFrontmatter(content, cwd) {
+  // Read the existing frontmatter BEFORE stripping so the structured
+  // current_milestone signal (set only by milestone-lifecycle writers) is
+  // carried through the rebuild rather than silently dropped.
+  const existingFm = extractFrontmatter(content);
   const body = stripFrontmatter(content);
-  const fm = buildStateFrontmatter(body, cwd);
+  const fm = buildStateFrontmatter(body, cwd, { existingFm });
   const yamlStr = reconstructFrontmatter(fm);
   return `---\n${yamlStr}\n---\n\n${body}`;
 }
@@ -910,6 +938,37 @@ function cmdStateArchiveQuickTasks(cwd, raw) {
  * @param {string} cwd - Planning root directory
  * @returns {{ success: boolean, milestone: string, completed_date: string }}
  */
+/**
+ * Shared STATE-body finalization for milestone completion.
+ *
+ * Performs all the "milestone shipped" body rewrites: the progress bar, the
+ * Current focus / Status / Last activity lines, AND the Current Position
+ * `Phase:` reset that keeps the dashboard from showing a frozen, mid-execution
+ * phase after a milestone ships (DASH-STALE-01).
+ *
+ * Used by both markMilestoneComplete (normal completion) and reconcileMilestone
+ * (self-heal) so the two paths produce byte-identical STATE bodies.
+ *
+ * @param {string} body - STATE.md body (frontmatter already stripped)
+ * @param {{ milestone: string, today: string, totalPhases: (number|string), totalPlans: (number|string) }} opts
+ * @returns {string} the rewritten body
+ */
+function _finalizeMilestoneStateBody(body, { milestone, today, totalPhases, totalPlans }) {
+  // Update progress bar
+  body = body.replace(/Progress:\s*\[[^\]]*\]\s*\d+%/, 'Progress: [██████████] 100%');
+  // Update current focus
+  body = body.replace(/\*\*Current focus:\*\*\s*.+/, `**Current focus:** Milestone ${milestone} complete — shipped ${today}`);
+  // Update status line in Current Position
+  body = body.replace(/Status:\s*.+/, `Status: Milestone ${milestone} shipped ${today}`);
+  // Update last activity in Current Position
+  body = body.replace(/(Last activity:\s*).+/, `$1${today} -- Milestone ${milestone} shipped (${totalPhases} phases, ${totalPlans} plans)`);
+  // Reset the Current Position Phase: line so the dashboard no longer references
+  // an in-progress phase. Multiline-anchored so it targets the line-leading
+  // `Phase:` entry, not substrings like "Phases completed".
+  body = body.replace(/^Phase:\s*.+$/m, `Phase: — (between milestones; ${milestone} shipped ${today})`);
+  return body;
+}
+
 function markMilestoneComplete(cwd) {
   const statePath = resolveStatePath(cwd);
   if (!fs.existsSync(statePath)) {
@@ -933,20 +992,10 @@ function markMilestoneComplete(cwd) {
   // Reconstruct frontmatter and preserve body
   let body = content.replace(/^---\n[\s\S]*?\n---\n*/, '');
 
-  // Update markdown body to reflect completion
-  const milestoneName = fm.milestone_name || fm.milestone || 'unknown';
+  // Update markdown body to reflect completion (shared with reconcileMilestone)
   const totalPhases = (fm.progress && fm.progress.total_phases) || '?';
   const totalPlans = (fm.progress && fm.progress.total_plans) || '?';
-  const lastPhase = (fm.progress && fm.progress.completed_phases) || totalPhases;
-
-  // Update progress bar
-  body = body.replace(/Progress:\s*\[[^\]]*\]\s*\d+%/, 'Progress: [██████████] 100%');
-  // Update current focus
-  body = body.replace(/\*\*Current focus:\*\*\s*.+/, `**Current focus:** Milestone ${milestone} complete — shipped ${today}`);
-  // Update status line in Current Position
-  body = body.replace(/Status:\s*.+/, `Status: Milestone ${milestone} shipped ${today}`);
-  // Update last activity in Current Position
-  body = body.replace(/(Last activity:\s*).+/, `$1${today} -- Milestone ${milestone} shipped (${totalPhases} phases, ${totalPlans} plans)`);
+  body = _finalizeMilestoneStateBody(body, { milestone, today, totalPhases, totalPlans });
 
   const yamlStr = reconstructFrontmatter(fm);
   content = `---\n${yamlStr}\n---\n\n${body}`;
@@ -961,6 +1010,99 @@ function cmdMarkMilestoneComplete(cwd, raw) {
   output(result, raw);
 }
 
+/**
+ * Self-heal a shipped-but-not-flipped project (DASH-STALE-02).
+ *
+ * Completion's STATE flip is sometimes skipped, leaving a project that has a
+ * MILESTONES.md entry AND a matching git tag (i.e. genuinely shipped) but whose
+ * STATE.md still reports status `executing` and a mid-execution `Phase:` line.
+ * This applies the SAME finalization as markMilestoneComplete to bring STATE in
+ * line. It is idempotent — a no-op on an already-correct or not-yet-shipped
+ * project. Scope is the CURRENT project (the resolved STATE.md) only.
+ *
+ * @param {string} cwd - Planning root directory
+ * @returns {{ healed: boolean, milestone: (string|null), changes?: string[], reason?: string }}
+ */
+function reconcileMilestone(cwd) {
+  const statePath = resolveStatePath(cwd);
+  if (!fs.existsSync(statePath)) {
+    error('STATE.md not found');
+  }
+
+  const content = fs.readFileSync(statePath, 'utf-8');
+  const fm = extractFrontmatter(content) || {};
+
+  // Determine milestone version: structured fields first, then ROADMAP scrape.
+  let version = null;
+  for (const v of [fm.current_milestone, fm.milestone]) {
+    if (isValidMilestoneVersion(v)) { version = v; break; }
+  }
+  if (!version) {
+    try {
+      const info = getMilestoneInfo(cwd);
+      if (isValidMilestoneVersion(info.version)) version = info.version;
+    } catch {}
+  }
+
+  // Detect "shipped": MILESTONES.md heading AND a matching git tag — both required.
+  let shipped = false;
+  if (version) {
+    let hasMilestoneEntry = false;
+    try {
+      const milestonesPath = path.join(getPlanningRoot(cwd), 'MILESTONES.md');
+      const mContent = fs.readFileSync(milestonesPath, 'utf-8');
+      const headingRe = new RegExp(`^##\\s+${escapeRegex(version)}\\b`, 'm');
+      hasMilestoneEntry = headingRe.test(mContent);
+    } catch {}
+    const tagResult = execGit(cwd, ['tag', '-l', version]);
+    const hasTag = tagResult.exitCode === 0 &&
+      tagResult.stdout.split('\n').map((s) => s.trim()).includes(version);
+    shipped = hasMilestoneEntry && hasTag;
+  }
+
+  if (!shipped) {
+    return { healed: false, milestone: version, reason: 'not_shipped' };
+  }
+
+  // Detect "not flipped": status not milestone_shipped OR the Phase: line still
+  // references an in-progress phase.
+  const statusFlipped = fm.status === 'milestone_shipped';
+  const body = content.replace(/^---\n[\s\S]*?\n---\n*/, '');
+  const phaseLine = body.match(/^Phase:\s*(.+)$/m);
+  const phaseInProgress = phaseLine ? /\d+\s+of\s+\d+/.test(phaseLine[1]) : false;
+
+  if (statusFlipped && !phaseInProgress) {
+    return { healed: false, milestone: version, reason: 'already_correct' };
+  }
+
+  // Heal: apply the same finalization as markMilestoneComplete.
+  const today = new Date().toISOString().split('T')[0];
+  const now = new Date().toISOString();
+  const changes = [];
+  if (!statusFlipped) changes.push('status');
+  if (phaseInProgress) changes.push('phase');
+
+  fm.status = 'milestone_shipped';
+  if (!fm.progress) fm.progress = {};
+  fm.progress.percent = 100;
+  fm.last_updated = now;
+  fm.completed_date = today;
+
+  const totalPhases = (fm.progress && fm.progress.total_phases) || '?';
+  const totalPlans = (fm.progress && fm.progress.total_plans) || '?';
+  const newBody = _finalizeMilestoneStateBody(body, { milestone: version, today, totalPhases, totalPlans });
+
+  const yamlStr = reconstructFrontmatter(fm);
+  fs.writeFileSync(statePath, `---\n${yamlStr}\n---\n\n${newBody}`, 'utf-8');
+
+  return { healed: true, milestone: version, changes };
+}
+
+function cmdReconcileMilestone(cwd, raw) {
+  const result = reconcileMilestone(cwd);
+  output(result, raw, JSON.stringify(result));
+}
+
 // ─── Ad-hoc milestone marker (Phase 159, ADH-04 primary) ─────────────────────
 
 /**
@@ -1109,6 +1251,8 @@ function cmdStateAdhocReadiness(cwd, raw) {
 module.exports = {
   stateExtractField,
   stateReplaceField,
+  buildStateFrontmatter,
+  syncStateFrontmatter,
   writeStateMd,
   cmdStateLoad,
   cmdStateGet,
@@ -1125,8 +1269,11 @@ module.exports = {
   cmdStateSnapshot,
   cmdStateJson,
   cmdStateArchiveQuickTasks,
+  _finalizeMilestoneStateBody,
   markMilestoneComplete,
   cmdMarkMilestoneComplete,
+  reconcileMilestone,
+  cmdReconcileMilestone,
   stateReadAdhoc,
   stateSetAdhoc,
   cmdStateReadAdhoc,

package/deliver-great-systems/references/git-integration.md

@@ -228,7 +228,7 @@ Each plan produces 2-4 commits (tasks + metadata). Clear, granular, bisectable.
 
 **Context engineering for AI:**
 - Git history becomes primary context source for future Claude sessions
-- `git log --grep="{phase}-{plan}"` shows all work for a plan
+- `git log $(git merge-base main HEAD)..HEAD --grep="{phase}-{plan}"` shows all work for a plan on the current milestone branch
 - `git diff <hash>^..<hash>` shows exact changes per task
 - Less reliance on parsing SUMMARY.md = more context for actual work
 

package/deliver-great-systems/templates/milestone-archive.md

@@ -121,5 +121,5 @@ _For current project status, see ROADMAP.md_
 
 - Update ROADMAP.md to collapse completed milestone in `<details>` tag
 - Update PROJECT.md to brownfield format with Current State section
-- Continue phase numbering in next milestone (never restart at 01)
+- Restart phase numbering at `01` in the next milestone — numbering is per-milestone, with the milestone version disambiguating (active phases live under `phases/<version>/NN-slug/`). Already-archived milestones keep their original numbers; no renumbering.
   </guidelines>

package/deliver-great-systems/templates/roadmap.md

@@ -95,7 +95,7 @@ Plans:
 ## Progress
 
 **Execution Order:**
-Phases execute in numeric order: 2 → 2.1 → 2.2 → 3 → 3.1 → 4
+Phases execute in numeric order within a milestone: 2 → 2.1 → 2.2 → 3 → 3.1 → 4
 
 | Phase | Plans Complete | Status | Completed |
 |-------|----------------|--------|-----------|
@@ -125,7 +125,7 @@ Phases execute in numeric order: 2 → 2.1 → 2.2 → 3 → 3.1 → 4
 **After milestones ship:**
 - Collapse completed milestones in `<details>` tags
 - Add new milestone sections for upcoming work
-- Keep continuous phase numbering (never restart at 01)
+- Restart phase numbering at `01` for each new milestone — numbering is per-milestone, scoped under `phases/<version>/NN-slug/` with the milestone version as the disambiguator (mirrors the `milestones/<version>-phases/` archive layout). Pre-existing flat-layout projects keep their existing global numbers — numbering is never rewritten.
 </guidelines>
 
 <status_values>
@@ -145,8 +145,8 @@ After completing first milestone, reorganize with milestone groupings:
 ## Milestones
 
 - ✅ **v1.0 MVP** - Phases 1-4 (shipped YYYY-MM-DD)
-- 🚧 **v1.1 [Name]** - Phases 5-6 (in progress)
-- 📋 **v2.0 [Name]** - Phases 7-10 (planned)
+- 🚧 **v1.1 [Name]** - Phases 1-2 (in progress)
+- 📋 **v2.0 [Name]** - Phases 1-4 (planned)
 
 ## Phases
 
@@ -170,14 +170,16 @@ Plans:
 
 **Milestone Goal:** [What v1.1 delivers]
 
-#### Phase 5: [Name]
+**Phase directory:** `phases/v1.1/` (numbering restarts at `01` for this milestone)
+
+#### Phase 1: [Name]
 **Goal**: [What this phase delivers]
-**Depends on**: Phase 4
+**Depends on**: v1.0 milestone (first phase of v1.1 — numbering restarts at 01)
 **Plans**: 2 plans
 
 Plans:
-- [ ] 05-01: [Brief description]
-- [ ] 05-02: [Brief description]
+- [ ] 01-01: [Brief description]
+- [ ] 01-02: [Brief description]
 
 [... remaining v1.1 phases ...]
 
@@ -193,12 +195,12 @@ Plans:
 |-------|-----------|----------------|--------|-----------|
 | 1. Foundation | v1.0 | 3/3 | Complete | YYYY-MM-DD |
 | 2. Features | v1.0 | 2/2 | Complete | YYYY-MM-DD |
-| 5. Security | v1.1 | 0/2 | Not started | - |
+| 1. Security | v1.1 | 0/2 | Not started | - |
 ```
 
 **Notes:**
 - Milestone emoji: ✅ shipped, 🚧 in progress, 📋 planned
 - Completed milestones collapsed in `<details>` for readability
 - Current/future milestones expanded
-- Continuous phase numbering (01-99)
+- Per-milestone phase numbering: each milestone restarts at `01` (zero-padded), namespaced under `phases/<version>/`
 - Progress table includes milestone column