@ktpartners/dgs-platform 3.5.0 → 3.5.1

package/CHANGELOG.md

@@ -8,6 +8,20 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [3.5.1] - 2026-06-28
+
+### Added
+- **`dgs-tools state reconcile-milestone` (quick-260627-m3k)** — self-heals a project whose milestone shipped (a `## <version>` heading in MILESTONES.md AND a matching git tag both present) but whose STATE.md was never flipped, so `/dgs:list-projects` stops showing a stale in-progress phase or false `executing` status. Conservative (no-op unless both shipped markers are present), idempotent, and current-project scoped.
+
+### Fixed
+- **Dashboard staleness after milestone completion (quick-260627-m3k)** — `markMilestoneComplete` now resets the STATE.md `Phase:` line (via a shared `_finalizeMilestoneStateBody` helper) instead of leaving it frozen at the last in-progress value, so a shipped milestone no longer surfaces a stale phase / `executing` status on the dashboard.
+- **Per-milestone finalize matcher (quick-260628-ikd)** — `roadmapUpdatePlanProgressInternal` is now format-agnostic: it updates progress-table rows keyed in the composite `<version>/N.` form (and bare `N.`) and preserves the optional Milestone column, so `phase finalize` / `plan finalize` update per-milestone ROADMAPs instead of silently no-op'ing.
+- **Branch-bounded diff-ref and self-check lookups (quick-260628-mlk)** — the codereview diff-ref, phase-prefix self-check probes, and the milestone-stats query are now bounded to the milestone branch, so per-milestone commit-prefix collisions (`feat(NN-NN):` reused across milestones) no longer reach unrelated commits from a different milestone.
+- **Jobs healthCheck flat-first (quick-260628-kxr-01)** — reworked the jobs `healthCheck` to be flat-first.
+
+### Documentation
+- **Stale-dashboard recovery guide (quick-260627-kvy)** — added a "Recovering a stale milestone dashboard" section to `docs/USER-GUIDE.md` documenting `state reconcile-milestone` and the per-project recovery playbook.
+
 ## [3.5.0] - 2026-06-27
 
 ### Added — v25.0 Per-Milestone Phase Numbering via Directory Namespacing (Phases 163-170)

package/bin/install.js

@@ -615,6 +615,22 @@ function convertClaudeToGeminiToml(content) {
   return toml;
 }
 
+/**
+ * Rewrite HOME-relative ".claude" references to the target config dir basename.
+ * Swaps ONLY the ".claude" basename, preserving the $HOME / process.env.HOME prefix.
+ * For a default ".claude" install cfgBase === ".claude" => both replaces are no-ops.
+ * @param {string} content - file content
+ * @param {string} cfgBase - target config dir basename, e.g. ".claude-v25-test" or ".claude"
+ */
+function rewriteHomeRelativeConfigPaths(content, cfgBase) {
+  // shell form: $HOME/.claude/  -> $HOME/<cfgBase>/
+  content = content.replace(/\$HOME\/\.claude\//g, '$HOME/' + cfgBase + '/');
+  // JS concat form: process.env.HOME + '/.claude/'  (both quote styles)
+  // matches a quote char followed by /.claude/ ; $1 backreference preserves the quote
+  content = content.replace(/(["'])\/\.claude\//g, '$1/' + cfgBase + '/');
+  return content;
+}
+
 /**
  * Copy commands to a flat structure for OpenCode
  * OpenCode expects: command/dgs-help.md (invoked as /dgs-help)
@@ -664,6 +680,8 @@ function copyFlattenedCommands(srcDir, destDir, prefix, pathPrefix, runtime) {
       content = content.replace(globalClaudeRegex, pathPrefix);
       content = content.replace(localClaudeRegex, `./${getDirName(runtime)}/`);
       content = content.replace(opencodeDirRegex, pathPrefix);
+      const cfgBase = pathPrefix.replace(/\/$/, '').split('/').pop();
+      content = rewriteHomeRelativeConfigPaths(content, cfgBase);
       content = processAttribution(content, getCommitAttribution(runtime));
       content = convertClaudeToOpencodeFrontmatter(content);
 
@@ -705,6 +723,8 @@ function copyWithPathReplacement(srcDir, destDir, pathPrefix, runtime, isCommand
       const localClaudeRegex = /\.\/\.claude\//g;
       content = content.replace(globalClaudeRegex, pathPrefix);
       content = content.replace(localClaudeRegex, `./${dirName}/`);
+      const cfgBase = pathPrefix.replace(/\/$/, '').split('/').pop();
+      content = rewriteHomeRelativeConfigPaths(content, cfgBase);
       content = processAttribution(content, getCommitAttribution(runtime));
 
       // Convert frontmatter for opencode compatibility
@@ -1657,6 +1677,8 @@ function install(isGlobal, runtime = 'claude') {
         // Always replace ~/.claude/ as it is the source of truth in the repo
         const dirRegex = /~\/\.claude\//g;
         content = content.replace(dirRegex, pathPrefix);
+        const cfgBase = pathPrefix.replace(/\/$/, '').split('/').pop();
+        content = rewriteHomeRelativeConfigPaths(content, cfgBase);
         content = processAttribution(content, getCommitAttribution(runtime));
         // Convert frontmatter for runtime compatibility
         if (isOpencode) {

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

@@ -1157,52 +1157,77 @@ function analyzeMilestonePhases(cwd, version) {
     );
     const sectionMatch = content.match(sectionHeadingPattern);
     if (!sectionMatch) {
-      throw new Error(`Milestone ${version} not found in ROADMAP.md`);
-    }
+      // No ##-#### heading carries the version. Support the newer
+      // single-milestone ROADMAP format where the version appears ONLY in the
+      // `# Roadmap: ... (vX.Y)` title and a `**Milestone:** vX.Y` bold line.
+      // Gate the whole-roadmap phase scan behind a single-milestone check so a
+      // stray bold line on a multi-milestone roadmap does not mis-derive a range.
+      const boldMilestonePattern = new RegExp(
+        '^\\*\\*Milestone:\\*\\*\\s*' + escapedVersion + '\\b',
+        'im'
+      );
+      const versionHeadings = content.match(/^#{2,4}\s+.*v\d+\.\d+/gim) || [];
+      const isSingleMilestone = versionHeadings.length <= 1;
+      if (boldMilestonePattern.test(content) && isSingleMilestone) {
+        const fullPhasePattern = /Phase\s+(\d+)/gi;
+        const phaseNumbers = [];
+        let fpMatch;
+        while ((fpMatch = fullPhasePattern.exec(content)) !== null) {
+          phaseNumbers.push(parseInt(fpMatch[1], 10));
+        }
+        if (phaseNumbers.length === 0) {
+          throw new Error(`Milestone ${version} not found in ROADMAP.md`);
+        }
+        phaseStart = Math.min(...phaseNumbers);
+        phaseEnd = Math.max(...phaseNumbers);
+      } else {
+        throw new Error(`Milestone ${version} not found in ROADMAP.md`);
+      }
+    } else {
+      const headingLevel = sectionMatch[1].length;
+      const sectionStart = sectionMatch.index + sectionMatch[0].length;
 
-    const headingLevel = sectionMatch[1].length;
-    const sectionStart = sectionMatch.index + sectionMatch[0].length;
+      // Find the end of this section (next heading at same or higher level)
+      const endPattern = new RegExp(
+        `^#{2,${headingLevel}}\\s+`,
+        'im'
+      );
+      const restContent = content.slice(sectionStart);
+      const endMatch = restContent.match(endPattern);
+      const sectionContent = endMatch
+        ? restContent.slice(0, endMatch.index)
+        : restContent;
+
+      // Collect Phase N: headers within this section
+      const phaseHeaderPattern = /Phase\s+(\d+)\s*:/gi;
+      const phaseNumbers = [];
+      let phMatch;
+      while ((phMatch = phaseHeaderPattern.exec(sectionContent)) !== null) {
+        phaseNumbers.push(parseInt(phMatch[1], 10));
+      }
 
-    // Find the end of this section (next heading at same or higher level)
-    const endPattern = new RegExp(
-      `^#{2,${headingLevel}}\\s+`,
-      'im'
-    );
-    const restContent = content.slice(sectionStart);
-    const endMatch = restContent.match(endPattern);
-    const sectionContent = endMatch
-      ? restContent.slice(0, endMatch.index)
-      : restContent;
-
-    // Collect Phase N: headers within this section
-    const phaseHeaderPattern = /Phase\s+(\d+)\s*:/gi;
-    const phaseNumbers = [];
-    let phMatch;
-    while ((phMatch = phaseHeaderPattern.exec(sectionContent)) !== null) {
-      phaseNumbers.push(parseInt(phMatch[1], 10));
-    }
+      // If section-based search found nothing (common when ROADMAP has peer-level
+      // ## headings like ## v1.0, ## Overview, ## Phase Details), search the entire
+      // ROADMAP for Phase N: headings. For single-milestone ROADMAPs all phases
+      // belong to the milestone.
+      if (phaseNumbers.length === 0) {
+        const fullPhasePattern = new RegExp(
+          `Phase\\s+(\\d+)`,
+          'gi'
+        );
+        let fpMatch;
+        while ((fpMatch = fullPhasePattern.exec(content)) !== null) {
+          phaseNumbers.push(parseInt(fpMatch[1], 10));
+        }
+      }
 
-    // If section-based search found nothing (common when ROADMAP has peer-level
-    // ## headings like ## v1.0, ## Overview, ## Phase Details), search the entire
-    // ROADMAP for Phase N: headings. For single-milestone ROADMAPs all phases
-    // belong to the milestone.
-    if (phaseNumbers.length === 0) {
-      const fullPhasePattern = new RegExp(
-        `Phase\\s+(\\d+)`,
-        'gi'
-      );
-      let fpMatch;
-      while ((fpMatch = fullPhasePattern.exec(content)) !== null) {
-        phaseNumbers.push(parseInt(fpMatch[1], 10));
+      if (phaseNumbers.length === 0) {
+        throw new Error(`Milestone ${version} not found in ROADMAP.md`);
       }
-    }
 
-    if (phaseNumbers.length === 0) {
-      throw new Error(`Milestone ${version} not found in ROADMAP.md`);
+      phaseStart = Math.min(...phaseNumbers);
+      phaseEnd = Math.max(...phaseNumbers);
     }
-
-    phaseStart = Math.min(...phaseNumbers);
-    phaseEnd = Math.max(...phaseNumbers);
   }
 
   // Extract all phase detail sections: ### Phase N: Name
@@ -1272,7 +1297,13 @@ function detectActiveMilestone(content) {
   if (match) return match[1];
   // Fallback: milestone list item with (in progress)
   const listMatch = content.match(/-\s+.*?(v\d+\.\d+).*?\((?:in\s+progress)\)/i);
-  return listMatch ? listMatch[1] : null;
+  if (listMatch) return listMatch[1];
+  // Final fallback: newer single-milestone format with a `**Milestone:** vX.Y`
+  // bold line. Runs LAST so legacy In-Progress heading/list signals win when
+  // present on multi-milestone roadmaps.
+  const boldMatch = content.match(/^\*\*Milestone:\*\*\s*(v\d+\.\d+)/im);
+  if (boldMatch) return boldMatch[1];
+  return null;
 }
 
 // ─── Milestone Job CLI Wrappers ─────────────────────────────────────────────
@@ -1519,37 +1550,63 @@ function cancelJob(cwd, version) {
 }
 
 /**
- * Validate jobs directory structure. Auto-create missing directories.
+ * Validate jobs directory structure (flat-first).
+ *
+ * Scans the flat `jobs/milestone-*.md` layout first. Legacy
+ * `pending/in-progress/completed` subdirs are an existence-gated optional
+ * fallback: they are counted + parse-validated when present, but are never
+ * created and their absence is not an issue. Only genuine parse failures
+ * flip `healthy` to false.
  *
  * @param {string} cwd - Working directory
  * @returns {{ healthy: boolean, directories: Array, job_count: number, issues?: Array }}
  */
 function healthCheck(cwd) {
   const jobsDir = path.join(getPlanningRoot(cwd), 'jobs');
-  const requiredDirs = ['pending', 'in-progress', 'completed'];
   const directories = [];
   const issues = [];
   let jobCount = 0;
 
-  for (const dirName of requiredDirs) {
-    const dirPath = path.join(jobsDir, dirName);
-    const exists = fs.existsSync(dirPath);
-    let created = false;
+  // An absent/empty jobs dir is healthy. Ensure it exists, but do not flag it.
+  let jobsCreated = false;
+  if (!fs.existsSync(jobsDir)) {
+    fs.mkdirSync(jobsDir, { recursive: true });
+    jobsCreated = true;
+  }
 
-    if (!exists) {
-      fs.mkdirSync(dirPath, { recursive: true });
-      created = true;
-      issues.push(`Missing directory auto-created: ${dirName}/`);
+  // Shared flat-job predicate (identical to findJobFile/listJobs). Excludes
+  // summary files (job-*-SUMMARY.md) since they do not start with 'milestone-'.
+  const isJobFile = f => f.startsWith('milestone-') && f.endsWith('.md');
+
+  // Flat-first scan: jobs/milestone-*.md
+  try {
+    const flatFiles = fs.readdirSync(jobsDir).filter(isJobFile);
+    jobCount += flatFiles.length;
+    for (const file of flatFiles) {
+      const filePath = path.join(jobsDir, file);
+      try {
+        parseJobFile(filePath);
+      } catch (err) {
+        issues.push(`Parse failure in ${file}: ${err.message}`);
+      }
     }
+  } catch {
+    // jobs dir unreadable; treat as empty.
+  }
 
-    directories.push({ name: dirName, exists: exists || created, created });
+  directories.push({ name: 'jobs', exists: true, created: jobsCreated });
+
+  // Legacy subdirs: existence-gated optional fallback. Never created.
+  const legacyDirs = ['pending', 'in-progress', 'completed'];
+  for (const dirName of legacyDirs) {
+    const dirPath = path.join(jobsDir, dirName);
+    if (!fs.existsSync(dirPath)) continue;
+
+    directories.push({ name: dirName, exists: true, created: false });
 
-    // Scan for job files
     try {
-      const files = fs.readdirSync(dirPath).filter(f => f.startsWith('milestone-') && f.endsWith('.md'));
+      const files = fs.readdirSync(dirPath).filter(isJobFile);
       jobCount += files.length;
-
-      // Validate each file
       for (const file of files) {
         const filePath = path.join(dirPath, file);
         try {
@@ -1559,7 +1616,7 @@ function healthCheck(cwd) {
         }
       }
     } catch {
-      // Directory just created, no files
+      // Subdir unreadable; skip.
     }
   }
 
@@ -2117,6 +2174,8 @@ module.exports = {
   cmdJobsInsertPhaseGapFix,
   cmdJobsCreateMilestone,
   cmdJobsMilestonePreview,
+  analyzeMilestonePhases,
+  detectActiveMilestone,
   cmdJobsListJobs,
   cmdJobsCancelJob,
   cmdJobsRecordStartShas,

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

@@ -18,6 +18,7 @@ const {
   parseJobFile, updateJobStep, moveJobFile,
   generateMilestoneSteps, buildJobFileContent,
   cmdJobsCreateMilestone, cmdJobsMilestonePreview,
+  analyzeMilestonePhases, detectActiveMilestone,
   findJobFile, updateJobHeader, insertJobSteps,
   buildGapFixSteps, insertGapFixSection,
   listJobs, cancelJob, recordStartShas, rollbackJob,
@@ -1379,6 +1380,105 @@ Plans:
     });
   });
 
+  // ─── Bold-line single-milestone format Tests ────────────────────────────
+
+  describe('bold-line single-milestone format', () => {
+    let fixture;
+
+    afterEach(() => {
+      if (fixture) fixture.cleanup();
+    });
+
+    const BOLD_LINE_ROADMAP = `# Roadmap: Tenant data-quality metrics in Admin UI (v30.1)
+
+**Milestone:** v30.1 — Tenant data-quality metrics in Admin UI
+
+## Overview
+
+Single-milestone roadmap. Version is only in the title and the bold line.
+
+### Phase 1: Metrics schema
+**Goal**: Define metrics tables
+Plans:
+- [ ] 01-01-PLAN.md
+
+### Phase 2: Admin UI surface
+**Goal**: Surface metrics in admin
+Plans:
+- [ ] 02-01-PLAN.md
+`;
+
+    const MULTI_MILESTONE_WITH_BOLD = `# Roadmap (v9.9)
+
+**Milestone:** v9.9 — stray bold line
+
+## v1.0 Foundation (SHIPPED)
+### Phase 1: Base
+### Phase 2: More base
+
+## v2.0 Next (In Progress)
+### Phase 3: New
+### Phase 4: Newer
+`;
+
+    it('detectActiveMilestone returns v30.1 from the bold line', () => {
+      assert.equal(detectActiveMilestone(BOLD_LINE_ROADMAP), 'v30.1');
+    });
+
+    it('analyzeMilestonePhases derives phases 1 and 2 from the bold-line roadmap', () => {
+      fixture = createFixture({
+        'ROADMAP.md': BOLD_LINE_ROADMAP,
+        'phases/01-metrics-schema/01-01-PLAN.md': '',
+        'phases/02-admin-ui/02-01-PLAN.md': '',
+      });
+
+      const phases = analyzeMilestonePhases(fixture.cwd, 'v30.1');
+      assert.equal(phases.length, 2);
+      assert.deepEqual(phases.map(p => p.number), ['1', '2']);
+    });
+
+    it('cmdJobsMilestonePreview succeeds with an explicit version', () => {
+      fixture = createFixture({
+        'ROADMAP.md': BOLD_LINE_ROADMAP,
+        'phases/01-metrics-schema/01-01-PLAN.md': '',
+        'phases/02-admin-ui/02-01-PLAN.md': '',
+      });
+
+      const result = cmdJobsMilestonePreview(fixture.cwd, 'v30.1', true, false);
+      assert.equal(result.preview, true);
+      assert.equal(result.version, 'v30.1');
+      assert.ok(result.step_count > 0, 'expected at least one step');
+    });
+
+    it('cmdJobsMilestonePreview auto-detects the bold-line version', () => {
+      fixture = createFixture({
+        'ROADMAP.md': BOLD_LINE_ROADMAP,
+        'phases/01-metrics-schema/01-01-PLAN.md': '',
+        'phases/02-admin-ui/02-01-PLAN.md': '',
+      });
+
+      const result = cmdJobsMilestonePreview(fixture.cwd, null, true, false);
+      assert.equal(result.version, 'v30.1');
+    });
+
+    it('analyzeMilestonePhases throws on a multi-milestone roadmap with a stray bold line', () => {
+      fixture = createFixture({
+        'ROADMAP.md': MULTI_MILESTONE_WITH_BOLD,
+        'phases/01-base/01-01-PLAN.md': '',
+        'phases/03-new/03-01-PLAN.md': '',
+      });
+
+      assert.throws(
+        () => analyzeMilestonePhases(fixture.cwd, 'v9.9'),
+        (err) => /v9\.9|not found/i.test(err.message)
+      );
+    });
+
+    it('detectActiveMilestone prefers the In-Progress heading over the bold line', () => {
+      assert.equal(detectActiveMilestone(MULTI_MILESTONE_WITH_BOLD), 'v2.0');
+    });
+  });
+
   // ─── findJobFile Tests ──────────────────────────────────────────────────
 
   describe('findJobFile', () => {
@@ -2182,18 +2282,46 @@ Plans:
       assert.equal(result.job_count, 0);
     });
 
-    it('returns healthy: false listing issues for missing directories, then auto-creates them', () => {
+    it('does not create legacy subdirs and stays healthy when they are absent', () => {
       fixture = createFixture({
         '': null,
       });
       const result = healthCheck(fixture.cwd);
 
-      // Should report missing directories but auto-create them
+      // An empty project (no legacy subdirs) is healthy with no jobs.
+      assert.equal(result.healthy, true);
+      assert.equal(result.job_count, 0);
       assert.ok(Array.isArray(result.directories));
-      // After auto-create, directories should exist
-      assert.ok(fs.existsSync(path.join(fixture.cwd, 'jobs', 'pending')));
-      assert.ok(fs.existsSync(path.join(fixture.cwd, 'jobs', 'in-progress')));
-      assert.ok(fs.existsSync(path.join(fixture.cwd, 'jobs', 'completed')));
+      // Legacy subdirs must NOT be auto-created.
+      assert.equal(fs.existsSync(path.join(fixture.cwd, 'jobs', 'pending')), false);
+      assert.equal(fs.existsSync(path.join(fixture.cwd, 'jobs', 'in-progress')), false);
+      assert.equal(fs.existsSync(path.join(fixture.cwd, 'jobs', 'completed')), false);
+    });
+
+    it('reports healthy: true for a flat jobs layout and does not create legacy subdirs', () => {
+      fixture = createFixture({
+        'jobs/milestone-v6.0.md': WELL_FORMED_JOB,
+      });
+      const result = healthCheck(fixture.cwd);
+
+      assert.equal(result.healthy, true);
+      assert.equal(result.job_count, 1);
+      assert.equal(result.issues.length, 0);
+      // No legacy subdirs created for a flat layout.
+      assert.equal(fs.existsSync(path.join(fixture.cwd, 'jobs', 'pending')), false);
+      assert.equal(fs.existsSync(path.join(fixture.cwd, 'jobs', 'in-progress')), false);
+      assert.equal(fs.existsSync(path.join(fixture.cwd, 'jobs', 'completed')), false);
+    });
+
+    it('excludes job-*-SUMMARY.md files from job_count in a flat layout', () => {
+      fixture = createFixture({
+        'jobs/milestone-v6.0.md': WELL_FORMED_JOB,
+        'jobs/job-v6.0-SUMMARY.md': '# Summary',
+      });
+      const result = healthCheck(fixture.cwd);
+
+      assert.equal(result.job_count, 1);
+      assert.equal(result.healthy, true);
     });
 
     it('validates each job file parses successfully; reports parse failures as issues', () => {
@@ -2546,14 +2674,14 @@ describe('jobs root-layout', () => {
     
   });
 
-  it('healthCheck creates jobs dirs at root layout', () => {
+  it('healthCheck does not create legacy subdirs at root layout', () => {
     fixture = createTempProject({ layout: 'root' });
     const result = healthCheck(fixture.cwd);
-    assert.ok(result.directories.length >= 3);
-    // Verify dirs were created at root
-    assert.ok(fs.existsSync(path.join(fixture.cwd, 'jobs', 'pending')));
-    assert.ok(fs.existsSync(path.join(fixture.cwd, 'jobs', 'in-progress')));
-    assert.ok(fs.existsSync(path.join(fixture.cwd, 'jobs', 'completed')));
+    assert.equal(result.healthy, true);
+    // Legacy subdirs must NOT be auto-created.
+    assert.equal(fs.existsSync(path.join(fixture.cwd, 'jobs', 'pending')), false);
+    assert.equal(fs.existsSync(path.join(fixture.cwd, 'jobs', 'in-progress')), false);
+    assert.equal(fs.existsSync(path.join(fixture.cwd, 'jobs', 'completed')), false);
   });
 
   it('listJobs works in root layout', () => {

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

@@ -268,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/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/workflows/codereview.md

@@ -21,7 +21,7 @@ Multi-agent code review that runs 3 passes of 3 parallel agents each (9 total re
 Compute the diff from the plan's task commits.
 
 ```bash
-FIRST_TASK_COMMIT=$(git -C "${CODE_REPO_PATH}" log --oneline --grep="feat(${PHASE}-${PLAN}):" --grep="fix(${PHASE}-${PLAN}):" --grep="test(${PHASE}-${PLAN}):" --grep="refactor(${PHASE}-${PLAN}):" --reverse | head -1 | cut -d' ' -f1)
+FIRST_TASK_COMMIT=$(git -C "${CODE_REPO_PATH}" log $(git -C "${CODE_REPO_PATH}" merge-base main HEAD)..HEAD --oneline --grep="feat(${PHASE}-${PLAN}):" --grep="fix(${PHASE}-${PLAN}):" --grep="test(${PHASE}-${PLAN}):" --grep="refactor(${PHASE}-${PLAN}):" --reverse | head -1 | cut -d' ' -f1)
 ```
 
 If FIRST_TASK_COMMIT is empty, exit with message: "No task commits found for ${PHASE}-${PLAN}, skipping code review."

package/deliver-great-systems/workflows/complete-milestone.md

@@ -433,7 +433,7 @@ If mark-milestone-complete fails, log a warning but continue to gather_stats (no
 Calculate milestone statistics:
 
 ```bash
-git log --oneline --grep="feat(" | head -20
+git log --oneline FIRST_COMMIT..LAST_COMMIT --grep="feat(" | head -20
 git diff --stat FIRST_COMMIT..LAST_COMMIT | tail -1
 find . -name "*.swift" -o -name "*.ts" -o -name "*.py" | xargs wc -l 2>/dev/null
 git log --format="%ai" FIRST_COMMIT | tail -1

package/deliver-great-systems/workflows/execute-phase.md

@@ -377,7 +377,7 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
 
    For each SUMMARY.md:
    - Verify first 2 files from `key-files.created` exist on disk
-   - Check `git log --oneline --all --grep="{phase}-{plan}"` returns ≥1 commit
+   - Check `git log --oneline $(git merge-base main HEAD)..HEAD --grep="{phase}-{plan}"` returns ≥1 commit
    - Check for `## Self-Check: FAILED` marker
 
    If ANY spot-check fails: report which plan failed, route to failure handler.
@@ -450,7 +450,7 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
 
    Compute diff reference for the plan's task commits:
    ```bash
-   FIRST_TASK_COMMIT=$(git -C "${CODE_REPO_PATH}" log --oneline --grep="feat(${PHASE}-${PLAN}):" --grep="fix(${PHASE}-${PLAN}):" --grep="test(${PHASE}-${PLAN}):" --grep="refactor(${PHASE}-${PLAN}):" --reverse | head -1 | cut -d' ' -f1)
+   FIRST_TASK_COMMIT=$(git -C "${CODE_REPO_PATH}" log $(git -C "${CODE_REPO_PATH}" merge-base main HEAD)..HEAD --oneline --grep="feat(${PHASE}-${PLAN}):" --grep="fix(${PHASE}-${PLAN}):" --grep="test(${PHASE}-${PLAN}):" --grep="refactor(${PHASE}-${PLAN}):" --reverse | head -1 | cut -d' ' -f1)
    ```
 
    If FIRST_TASK_COMMIT is empty (no task commits found), skip codereview for this plan with message: "No task commits found for {phase}-{plan}, skipping code review."

package/deliver-great-systems/workflows/execute-plan.md

@@ -114,7 +114,7 @@ Pattern B only (verify-only checkpoints). Skip for A/C.
    - Main route: execute tasks using standard flow (step name="execute")
 3. After ALL segments: aggregate files/deviations/decisions → create SUMMARY.md → commit → self-check:
    - Verify key-files.created exist on disk with `[ -f ]`
-   - Check `git log --oneline --all --grep="{phase}-{plan}"` returns ≥1 commit
+   - Check `git log --oneline $(git merge-base main HEAD)..HEAD --grep="{phase}-{plan}"` returns ≥1 commit
    - Append `## Self-Check: PASSED` or `## Self-Check: FAILED` to SUMMARY
 
    **Known Claude Code bug (classifyHandoffIfNeeded):** If any segment agent reports "failed" with `classifyHandoffIfNeeded is not defined`, this is a Claude Code runtime bug — not a real failure. Run spot-checks; if they pass, treat as successful.
@@ -490,7 +490,7 @@ The plan name is auto-extracted from the PLAN.md `plan_name` frontmatter field (
 If ${project_root}/codebase/ doesn't exist: skip.
 
 ```bash
-FIRST_TASK=$(git log --oneline --grep="feat({phase}-{plan}):" --grep="fix({phase}-{plan}):" --grep="test({phase}-{plan}):" --reverse | head -1 | cut -d' ' -f1)
+FIRST_TASK=$(git log $(git merge-base main HEAD)..HEAD --oneline --grep="feat({phase}-{plan}):" --grep="fix({phase}-{plan}):" --grep="test({phase}-{plan}):" --reverse | head -1 | cut -d' ' -f1)
 git diff --name-only ${FIRST_TASK}^..HEAD 2>/dev/null
 ```
 

package/package.json

@@ -8,7 +8,7 @@
   "bugs": {
     "url": "https://github.com/KT-Partners-Ltd/dgs-platform-docs/issues"
   },
-  "version": "3.5.0",
+  "version": "3.5.1",
   "description": "Deliver Great Systems Platform — A meta-prompting, context engineering and spec-driven development system for Claude Code and Gemini by KT Partners.",
   "bin": {
     "dgs": "bin/install.js"