@ktpartners/dgs-platform 2.8.0 → 3.0.4

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

@@ -224,7 +224,12 @@ function cmdRoadmapAnalyze(cwd, raw) {
   output(result, raw);
 }
 
-function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
+/**
+ * Internal helper: performs the ROADMAP.md plan-progress update for a single
+ * phase and returns { result, roadmapPath, rawValue } without emitting/exiting.
+ * External callers (cmdRoadmapUpdatePlanProgress, cmdPlanFinalize) handle output.
+ */
+function roadmapUpdatePlanProgressInternal(cwd, phaseNum) {
   if (!phaseNum) {
     error('phase number required for roadmap update-plan-progress');
   }
@@ -240,8 +245,11 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
   const summaryCount = phaseInfo.summaries.length;
 
   if (planCount === 0) {
-    output({ updated: false, reason: 'No plans found', plan_count: 0, summary_count: 0 }, raw, 'no plans');
-    return;
+    return {
+      result: { updated: false, reason: 'No plans found', plan_count: 0, summary_count: 0 },
+      roadmapPath,
+      rawValue: 'no plans',
+    };
   }
 
   const isComplete = summaryCount >= planCount;
@@ -249,8 +257,11 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
   const today = new Date().toISOString().split('T')[0];
 
   if (!fs.existsSync(roadmapPath)) {
-    output({ updated: false, reason: 'ROADMAP.md not found', plan_count: planCount, summary_count: summaryCount }, raw, 'no roadmap');
-    return;
+    return {
+      result: { updated: false, reason: 'ROADMAP.md not found', plan_count: planCount, summary_count: summaryCount },
+      roadmapPath,
+      rawValue: 'no roadmap',
+    };
   }
 
   let roadmapContent = fs.readFileSync(roadmapPath, 'utf-8');
@@ -288,18 +299,28 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
 
   fs.writeFileSync(roadmapPath, roadmapContent, 'utf-8');
 
-  output({
-    updated: true,
-    phase: phaseNum,
-    plan_count: planCount,
-    summary_count: summaryCount,
-    status,
-    complete: isComplete,
-  }, raw, `${summaryCount}/${planCount} ${status}`);
+  return {
+    result: {
+      updated: true,
+      phase: phaseNum,
+      plan_count: planCount,
+      summary_count: summaryCount,
+      status,
+      complete: isComplete,
+    },
+    roadmapPath,
+    rawValue: `${summaryCount}/${planCount} ${status}`,
+  };
+}
+
+function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
+  const { result, rawValue } = roadmapUpdatePlanProgressInternal(cwd, phaseNum);
+  output(result, raw, rawValue);
 }
 
 module.exports = {
   cmdRoadmapGetPhase,
   cmdRoadmapAnalyze,
   cmdRoadmapUpdatePlanProgress,
+  roadmapUpdatePlanProgressInternal,
 };

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

@@ -774,13 +774,13 @@ function cmdSpecsFinalize(cwd, idOrFilename, raw, author) {
   const content = buildSpecContent(spec.frontmatter, spec.body);
   fs.writeFileSync(spec.path, content, 'utf-8');
 
-  // Move source ideas to done
+  // Set source ideas to done via frontmatter edit (no file moves)
+  const { setIdeaStatus } = require('./ideas.cjs');
   const ideasMoved = [];
   const ideasFailed = [];
   const sourceIdeas = spec.frontmatter.source_ideas || [];
 
   for (const ideaFilename of sourceIdeas) {
-    // Extract idea ID from filename (e.g., "001-slug.md" -> "001")
     const idMatch = ideaFilename.match(/^(\d+)/);
     if (!idMatch) {
       ideasFailed.push({ idea: ideaFilename, reason: 'could not parse ID' });
@@ -789,90 +789,13 @@ function cmdSpecsFinalize(cwd, idOrFilename, raw, author) {
     const ideaId = idMatch[1];
 
     try {
-      // Move ideas to done manually (ideas.cjs cmd functions call process.exit,
-      // so we use the internal helpers directly instead)
-      // Instead, do the move manually following the same pattern
-      const { findIdeaFile, ensureIdeasDirs } = require('./ideas.cjs');
-      const idea = findIdeaFile(cwd, ideaId);
-
-      if (!idea) {
-        ideasFailed.push({ idea: ideaFilename, reason: 'idea not found' });
-        continue;
-      }
-
-      if (idea.state === 'done') {
-        // Already done, skip
-        ideasMoved.push(ideaFilename);
-        continue;
-      }
-
-      if (idea.state === 'consolidated') {
-        // Consolidated ideas cannot be used as spec sources
-        ideasFailed.push({ idea: ideaFilename, reason: 'idea is consolidated' });
-        continue;
-      }
-
-      ensureIdeasDirs(cwd);
-
-      const planRootRel = path.relative(cwd, getPlanningRoot(cwd)) || '.';
-      const fromRel = path.join(planRootRel, 'ideas', idea.state, idea.filename);
-      const toRel = path.join(planRootRel, 'ideas', 'done', idea.filename);
-      const mvResult = execGit(cwd, ['mv', fromRel, toRel]);
-
-      if (mvResult.exitCode !== 0) {
-        ideasFailed.push({ idea: ideaFilename, reason: mvResult.stderr || 'git mv failed' });
-        continue;
-      }
-
+      setIdeaStatus(cwd, ideaId, 'done');
       ideasMoved.push(ideaFilename);
     } catch (err) {
       ideasFailed.push({ idea: ideaFilename, reason: err.message || 'unknown error' });
     }
   }
 
-  // Move associated research documents and update links in idea files
-  const researchDocsMoved = [];
-
-  for (const ideaFilename of ideasMoved) {
-    try {
-      // Extract slug from idea filename: "001-my-idea.md" -> "my-idea"
-      const slug = ideaFilename.replace(/^\d+-/, '').replace(/\.md$/, '');
-      const researchDocName = `${slug}-research.md`;
-      const specPlanRoot = getPlanningRoot(cwd);
-      const specPlanRootRel = path.relative(cwd, specPlanRoot) || '.';
-      const sourcePath = path.join(specPlanRoot, 'docs', 'ideas', 'pending', researchDocName);
-
-      // Skip if no research doc exists (graceful handling)
-      if (!fs.existsSync(sourcePath)) continue;
-
-      // Ensure done directory exists
-      fs.mkdirSync(path.join(specPlanRoot, 'docs', 'ideas', 'done'), { recursive: true });
-
-      const sourceRel = path.join(specPlanRootRel, 'docs', 'ideas', 'pending', researchDocName);
-      const targetRel = path.join(specPlanRootRel, 'docs', 'ideas', 'done', researchDocName);
-      const mvResult = execGit(cwd, ['mv', sourceRel, targetRel]);
-
-      if (mvResult.exitCode !== 0) continue;
-
-      researchDocsMoved.push(researchDocName);
-
-      // Update documentLink paths in the idea file (now in done/)
-      const ideaDonePath = path.join(getPlanningRoot(cwd), 'ideas', 'done', ideaFilename);
-      if (fs.existsSync(ideaDonePath)) {
-        let ideaContent = fs.readFileSync(ideaDonePath, 'utf-8');
-        // Replace pending/ paths with done/ for this research doc
-        const pendingPattern = `docs/ideas/pending/${researchDocName}`;
-        const doneReplacement = `docs/ideas/done/${researchDocName}`;
-        if (ideaContent.includes(pendingPattern)) {
-          ideaContent = ideaContent.split(pendingPattern).join(doneReplacement);
-          fs.writeFileSync(ideaDonePath, ideaContent, 'utf-8');
-        }
-      }
-    } catch {
-      // Graceful handling: skip on any error
-    }
-  }
-
   // Auto-commit the spec status change and idea moves
   execGit(cwd, ['add', '-A']);
   const title = spec.frontmatter.title || spec.frontmatter.id;
@@ -884,7 +807,6 @@ function cmdSpecsFinalize(cwd, idOrFilename, raw, author) {
     status: 'final',
     ideas_moved: ideasMoved,
     ideas_failed: ideasFailed,
-    research_docs_moved: researchDocsMoved,
   };
   output(result, raw);
 }

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

@@ -0,0 +1,160 @@
+/**
+ * GATE tests: State Transition Invariant
+ *
+ * Enforces that no code path in ideas, todos, jobs, or specs uses file moves
+ * (git mv, renameSync, unlinkSync) for state transitions. All state changes
+ * must use frontmatter edits (setIdeaStatus, setTodoStatus, setJobStatus).
+ *
+ * This GATE was introduced in Phase 133 (v20.0) after rewriting all 9 file-move
+ * state transitions to frontmatter edits.
+ */
+
+const { describe, it } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
+
+const LIB_DIR = path.join(__dirname);
+
+// State subdirectory patterns that indicate directory-based state management
+const STATE_DIR_PATTERNS = [
+  /ideas\/pending\//,
+  /ideas\/done\//,
+  /ideas\/rejected\//,
+  /ideas\/consolidated\//,
+  /todos\/pending\//,
+  /todos\/completed\//,
+  /jobs\/pending\//,
+  /jobs\/in-progress\//,
+  /jobs\/completed\//,
+];
+
+// Move/rename/delete operations that are prohibited in state transition contexts
+const MOVE_PATTERNS = [
+  { pattern: /execGit\([^)]*\[\s*['"]mv['"]/, label: 'git mv' },
+  { pattern: /renameSync\(/, label: 'fs.renameSync' },
+];
+
+// Files to scan (source files only, not tests)
+const TARGET_FILES = ['ideas.cjs', 'commands.cjs', 'jobs.cjs', 'specs.cjs'];
+
+/**
+ * Scan a file for lines containing both a state directory pattern AND a move operation.
+ * Returns violations as { line: number, text: string, stateDir: string, operation: string }.
+ */
+function scanForViolations(filePath) {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const lines = content.split('\n');
+  const violations = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    // Skip comments
+    if (line.trim().startsWith('//') || line.trim().startsWith('*')) continue;
+
+    // Check each move pattern
+    for (const { pattern: movePattern, label: moveLabel } of MOVE_PATTERNS) {
+      if (!movePattern.test(line)) continue;
+
+      // Check if this line or nearby lines reference state directories
+      // Check a window of +/-5 lines for state directory context
+      const windowStart = Math.max(0, i - 5);
+      const windowEnd = Math.min(lines.length - 1, i + 5);
+      const window = lines.slice(windowStart, windowEnd + 1).join('\n');
+
+      for (const statePattern of STATE_DIR_PATTERNS) {
+        if (statePattern.test(window)) {
+          violations.push({
+            line: i + 1,
+            text: line.trim(),
+            stateDir: statePattern.source,
+            operation: moveLabel,
+          });
+          break; // One violation per line is enough
+        }
+      }
+    }
+  }
+
+  return violations;
+}
+
+describe('state transition gate: no file moves for state changes', () => {
+
+  for (const fileName of TARGET_FILES) {
+    it(`GATE: zero file-move state transitions in ${fileName}`, () => {
+      const filePath = path.join(LIB_DIR, fileName);
+
+      if (!fs.existsSync(filePath)) {
+        // File doesn't exist — not a violation, just skip
+        return;
+      }
+
+      const violations = scanForViolations(filePath);
+
+      if (violations.length > 0) {
+        const details = violations.map(v =>
+          `  Line ${v.line}: ${v.operation} near ${v.stateDir}\n    ${v.text}`
+        ).join('\n');
+
+        assert.fail(
+          `Found ${violations.length} file-move state transition(s) in ${fileName}:\n${details}\n\n` +
+          'All state transitions must use frontmatter edits (setIdeaStatus, setTodoStatus, setJobStatus).\n' +
+          'Replace git mv / renameSync with the appropriate set*Status helper.'
+        );
+      }
+
+      assert.equal(violations.length, 0,
+        `${fileName} should have zero file-move state transitions`);
+    });
+  }
+
+  it('GATE: cmdTodoComplete has no unlinkSync (copy+delete pattern)', () => {
+    const filePath = path.join(LIB_DIR, 'commands.cjs');
+    if (!fs.existsSync(filePath)) return;
+
+    const content = fs.readFileSync(filePath, 'utf-8');
+
+    // Find cmdTodoComplete function body
+    const fnStart = content.indexOf('function cmdTodoComplete');
+    if (fnStart === -1) return; // Function not found
+
+    // Find next function definition or module.exports as boundary
+    const afterFn = content.slice(fnStart + 1);
+    const fnEnd = afterFn.search(/\nfunction\s|\nmodule\.exports/);
+    const fnBody = fnEnd > 0 ? afterFn.slice(0, fnEnd) : afterFn;
+
+    if (fnBody.includes('unlinkSync')) {
+      assert.fail(
+        'cmdTodoComplete contains unlinkSync — this is a copy+delete state transition pattern.\n' +
+        'Use setTodoStatus to edit frontmatter instead of copying and deleting files.'
+      );
+    }
+  });
+
+  it('GATE: cmdSpecsFinalize has no research doc moving', () => {
+    const filePath = path.join(LIB_DIR, 'specs.cjs');
+    if (!fs.existsSync(filePath)) return;
+
+    const content = fs.readFileSync(filePath, 'utf-8');
+
+    // Find cmdSpecsFinalize function body
+    const fnStart = content.indexOf('function cmdSpecsFinalize');
+    if (fnStart === -1) return;
+
+    const afterFn = content.slice(fnStart + 1);
+    const fnEnd = afterFn.search(/\nfunction\s|\nmodule\.exports/);
+    const fnBody = fnEnd > 0 ? afterFn.slice(0, fnEnd) : afterFn;
+
+    // Check for research doc directory references
+    const hasResearchDocMove = /docs\/ideas\/(pending|done|rejected|consolidated)/.test(fnBody);
+
+    if (hasResearchDocMove) {
+      assert.fail(
+        'cmdSpecsFinalize still references research doc state directories.\n' +
+        'Research doc flattening is handled by Phase 134 — remove from finalize.'
+      );
+    }
+  });
+});

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

@@ -4,7 +4,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { loadConfig, getMilestoneInfo, output, error, getProjectRoot } = require('./core.cjs');
+const { loadConfig, getMilestoneInfo, getMilestonePhaseFilter, output, error, getProjectRoot } = require('./core.cjs');
 const { extractFrontmatter, reconstructFrontmatter } = require('./frontmatter.cjs');
 const { getPlanningRoot } = require('./paths.cjs');
 
@@ -69,9 +69,6 @@ function cmdStateLoad(cwd, raw) {
     const lines = [
       `model_profile=${c.model_profile}`,
       `commit_docs=${c.commit_docs}`,
-      `branching_strategy=${c.branching_strategy}`,
-      `phase_branch_template=${c.phase_branch_template}`,
-      `milestone_branch_template=${c.milestone_branch_template}`,
       `base_branch=${c.base_branch}`,
       `parallelization=${c.parallelization}`,
       `research=${c.research}`,
@@ -282,11 +279,19 @@ function cmdStateRecordMetric(cwd, options, raw) {
   }
 }
 
-function cmdStateUpdateProgress(cwd, raw) {
+/**
+ * Internal helper: recalculates the progress bar from disk and updates STATE.md.
+ * Returns { updated, percent, completed, total, bar, reason, statePath, rawValue }
+ * WITHOUT calling output()/exit. Callers handle output emission themselves.
+ * `rawValue` is the string emitted by the CLI in raw mode (progressStr or 'false').
+ */
+function stateUpdateProgressInternal(cwd) {
   let projectRoot;
   try { projectRoot = getProjectRoot(cwd); } catch { projectRoot = path.relative(cwd, getPlanningRoot(cwd)) || '.'; }
   const statePath = path.join(cwd, projectRoot, 'STATE.md');
-  if (!fs.existsSync(statePath)) { output({ error: 'STATE.md not found' }, raw); return; }
+  if (!fs.existsSync(statePath)) {
+    return { result: { error: 'STATE.md not found' }, statePath, rawValue: undefined };
+  }
 
   let content = fs.readFileSync(statePath, 'utf-8');
 
@@ -317,13 +322,35 @@ function cmdStateUpdateProgress(cwd, raw) {
   if (boldProgressPattern.test(content)) {
     content = content.replace(boldProgressPattern, (_match, prefix) => `${prefix}${progressStr}`);
     writeStateMd(statePath, content, cwd);
-    output({ updated: true, percent, completed: totalSummaries, total: totalPlans, bar: progressStr }, raw, progressStr);
+    return {
+      result: { updated: true, percent, completed: totalSummaries, total: totalPlans, bar: progressStr },
+      statePath,
+      rawValue: progressStr,
+    };
   } else if (plainProgressPattern.test(content)) {
     content = content.replace(plainProgressPattern, (_match, prefix) => `${prefix}${progressStr}`);
     writeStateMd(statePath, content, cwd);
-    output({ updated: true, percent, completed: totalSummaries, total: totalPlans, bar: progressStr }, raw, progressStr);
+    return {
+      result: { updated: true, percent, completed: totalSummaries, total: totalPlans, bar: progressStr },
+      statePath,
+      rawValue: progressStr,
+    };
   } else {
-    output({ updated: false, reason: 'Progress field not found in STATE.md' }, raw, 'false');
+    return {
+      result: { updated: false, reason: 'Progress field not found in STATE.md' },
+      statePath,
+      rawValue: 'false',
+    };
+  }
+}
+
+function cmdStateUpdateProgress(cwd, raw) {
+  const { result, rawValue } = stateUpdateProgressInternal(cwd);
+  if (rawValue === undefined) {
+    // STATE.md missing branch — original used `output({ error: ... }, raw)`
+    output(result, raw);
+  } else {
+    output(result, raw, rawValue);
   }
 }
 
@@ -564,40 +591,6 @@ function cmdStateSnapshot(cwd, raw) {
 
 // ─── State Frontmatter Sync ──────────────────────────────────────────────────
 
-/**
- * Build a milestone phase filter from ROADMAP.md.
- * Returns a function that checks if a phase directory belongs to the current milestone.
- */
-function getMilestonePhaseFilter(cwd) {
-  const milestonePhaseNums = new Set();
-  try {
-    const roadmap = fs.readFileSync(path.join(getPlanningRoot(cwd), 'ROADMAP.md'), 'utf-8');
-    const phasePattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:/gi;
-    let m;
-    while ((m = phasePattern.exec(roadmap)) !== null) {
-      milestonePhaseNums.add(m[1]);
-    }
-  } catch {}
-
-  if (milestonePhaseNums.size === 0) {
-    const passAll = () => true;
-    passAll.phaseCount = 0;
-    return passAll;
-  }
-
-  const normalized = new Set(
-    [...milestonePhaseNums].map(n => (n.replace(/^0+/, '') || '0').toLowerCase())
-  );
-
-  function isDirInMilestone(dirName) {
-    const m = dirName.match(/^0*(\d+[A-Za-z]?(?:\.\d+)*)/);
-    if (!m) return false;
-    return normalized.has(m[1].toLowerCase());
-  }
-  isDirInMilestone.phaseCount = milestonePhaseNums.size;
-  return isDirInMilestone;
-}
-
 /**
  * Extract machine-readable fields from STATE.md markdown body and build
  * a YAML frontmatter object. Allows hooks and scripts to read state
@@ -632,7 +625,13 @@ function buildStateFrontmatter(bodyContent, cwd) {
 
   if (cwd) {
     try {
-      const phasesDir = path.join(getPlanningRoot(cwd), 'phases');
+      let phasesDir;
+      try {
+        const projectRoot = getProjectRoot(cwd);
+        phasesDir = path.join(cwd, projectRoot, 'phases');
+      } catch {
+        phasesDir = path.join(getPlanningRoot(cwd), 'phases');
+      }
       if (fs.existsSync(phasesDir)) {
         const isDirInMilestone = getMilestonePhaseFilter(cwd);
         const phaseDirs = fs.readdirSync(phasesDir, { withFileTypes: true })
@@ -751,11 +750,12 @@ function cmdStateJson(cwd, raw) {
 
 // ─── Quick Task Archival ─────────────────────────────────────────────────────
 
-function cmdStateArchiveQuickTasks(cwd, raw) {
-  const statePath = resolveStatePath(cwd);
+// Internal helper: archive the Quick Tasks Completed section from a single
+// STATE.md file. Returns a status object describing the outcome; does not
+// emit output directly so the caller can aggregate across multiple files.
+function _archiveSingleStateFile(statePath, cwd) {
   if (!fs.existsSync(statePath)) {
-    output({ error: 'STATE.md not found' }, raw);
-    return;
+    return { archived: false, state_path: statePath, reason: 'not_found', row_count: 0 };
   }
 
   let content = fs.readFileSync(statePath, 'utf-8');
@@ -765,8 +765,7 @@ function cmdStateArchiveQuickTasks(cwd, raw) {
   const sectionMatch = content.match(sectionPattern);
 
   if (!sectionMatch) {
-    output({ archived: false, reason: 'no_section', row_count: 0 }, raw);
-    return;
+    return { archived: false, state_path: statePath, reason: 'no_section', row_count: 0 };
   }
 
   const sectionBody = sectionMatch[2];
@@ -800,8 +799,7 @@ function cmdStateArchiveQuickTasks(cwd, raw) {
   }
 
   if (dataRows.length <= 20) {
-    output({ archived: false, reason: 'under_threshold', row_count: dataRows.length }, raw);
-    return;
+    return { archived: false, state_path: statePath, reason: 'under_threshold', row_count: dataRows.length };
   }
 
   // Archive down to 15 rows (buffer below the 20 threshold)
@@ -818,7 +816,8 @@ function cmdStateArchiveQuickTasks(cwd, raw) {
   content = content.replace(sectionPattern, (_match, header) => `${header}${rebuiltSection}`);
   writeStateMd(statePath, content, cwd);
 
-  // Build HISTORY.md path
+  // Build HISTORY.md path — naturally lands beside the STATE.md being archived
+  // (product → planning-root quick/HISTORY.md; project → projects/<p>/quick/HISTORY.md).
   const historyPath = path.join(path.dirname(statePath), 'quick', 'HISTORY.md');
 
   // Ensure quick/ directory exists
@@ -869,7 +868,93 @@ Archived quick/fast task records from STATE.md.
 
   fs.writeFileSync(historyPath, historyContent, 'utf-8');
 
-  output({ archived: true, count: archiveCount, remaining: 15, history_path: historyPath }, raw);
+  return { archived: true, state_path: statePath, count: archiveCount, remaining: 15, history_path: historyPath };
+}
+
+// Dual-scan archival: quick tasks can land in either the product-level
+// STATE.md (planning root, used by `/dgs:quick --main` and product-mode
+// quicks) or the project-level STATE.md (milestone-context quicks). Both
+// files can accumulate tracking rows independently, so archival has to
+// scan both and archive each over-threshold section into its own
+// sibling quick/HISTORY.md file.
+function cmdStateArchiveQuickTasks(cwd, raw) {
+  const productStatePath = path.join(getPlanningRoot(cwd), 'STATE.md');
+  const projectStatePath = resolveStatePath(cwd);
+
+  // Deduplicate — root layout without a project subdir resolves both to the
+  // same file, so only scan once to avoid double-processing.
+  const candidates = [productStatePath];
+  if (path.resolve(projectStatePath) !== path.resolve(productStatePath)) {
+    candidates.push(projectStatePath);
+  }
+
+  const results = candidates.map((p) => _archiveSingleStateFile(p, cwd));
+  const anyArchived = results.some((r) => r.archived);
+
+  output({ archived: anyArchived, results, scanned: candidates }, raw);
+}
+
+// ─── Milestone Completion ────────────────────────────────────────────────────
+
+/**
+ * Mark the current milestone as complete in STATE.md.
+ * Updates frontmatter status to "complete", progress.percent to 100,
+ * last_updated to current ISO timestamp, and adds completed_date.
+ *
+ * Called by the complete-milestone workflow after all code repos have
+ * successfully merged.
+ *
+ * @param {string} cwd - Planning root directory
+ * @returns {{ success: boolean, milestone: string, completed_date: string }}
+ */
+function markMilestoneComplete(cwd) {
+  const statePath = resolveStatePath(cwd);
+  if (!fs.existsSync(statePath)) {
+    error('STATE.md not found');
+  }
+
+  let content = fs.readFileSync(statePath, 'utf-8');
+  const fm = extractFrontmatter(content);
+  const milestone = fm.milestone || 'unknown';
+  const today = new Date().toISOString().split('T')[0];
+  const now = new Date().toISOString();
+
+  // Update frontmatter fields
+  fm.status = 'complete';
+  if (!fm.progress) fm.progress = {};
+  fm.progress.percent = 100;
+  fm.last_updated = now;
+  fm.completed_date = today;
+
+  // 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';
+  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)`);
+
+  const yamlStr = reconstructFrontmatter(fm);
+  content = `---\n${yamlStr}\n---\n\n${body}`;
+
+  fs.writeFileSync(statePath, content, 'utf-8');
+
+  return { success: true, milestone: milestone, completed_date: today };
+}
+
+function cmdMarkMilestoneComplete(cwd, raw) {
+  const result = markMilestoneComplete(cwd);
+  output(result, raw);
 }
 
 module.exports = {
@@ -883,6 +968,7 @@ module.exports = {
   cmdStateAdvancePlan,
   cmdStateRecordMetric,
   cmdStateUpdateProgress,
+  stateUpdateProgressInternal,
   cmdStateAddDecision,
   cmdStateAddBlocker,
   cmdStateResolveBlocker,
@@ -890,4 +976,6 @@ module.exports = {
   cmdStateSnapshot,
   cmdStateJson,
   cmdStateArchiveQuickTasks,
+  markMilestoneComplete,
+  cmdMarkMilestoneComplete,
 };