gsd-opencode 1.22.0 → 1.30.0

package/get-shit-done/bin/lib/phase.cjs

@@ -4,12 +4,12 @@
 
 const fs = require('fs');
 const path = require('path');
-const { escapeRegex, normalizePhaseName, comparePhaseNum, findPhaseInternal, getArchivedPhaseDirs, generateSlugInternal, getMilestonePhaseFilter, toPosixPath, output, error } = require('./core.cjs');
+const { escapeRegex, loadConfig, normalizePhaseName, comparePhaseNum, findPhaseInternal, getArchivedPhaseDirs, generateSlugInternal, getMilestonePhaseFilter, stripShippedMilestones, extractCurrentMilestone, replaceInCurrentMilestone, toPosixPath, planningDir, output, error, readSubdirectories } = require('./core.cjs');
 const { extractFrontmatter } = require('./frontmatter.cjs');
-const { writeStateMd } = require('./state.cjs');
+const { writeStateMd, stateExtractField, stateReplaceField, stateReplaceFieldWithFallback } = require('./state.cjs');
 
 function cmdPhasesList(cwd, options, raw) {
-  const phasesDir = path.join(cwd, '.planning', 'phases');
+  const phasesDir = path.join(planningDir(cwd), 'phases');
   const { type, phase, includeArchived } = options;
 
   // If no phases directory, return empty
@@ -85,7 +85,7 @@ function cmdPhasesList(cwd, options, raw) {
 }
 
 function cmdPhaseNextDecimal(cwd, basePhase, raw) {
-  const phasesDir = path.join(cwd, '.planning', 'phases');
+  const phasesDir = path.join(planningDir(cwd), 'phases');
   const normalized = normalizePhaseName(basePhase);
 
   // Check if phases directory exists
@@ -154,7 +154,7 @@ function cmdFindPhase(cwd, phase, raw) {
     error('phase identifier required');
   }
 
-  const phasesDir = path.join(cwd, '.planning', 'phases');
+  const phasesDir = path.join(planningDir(cwd), 'phases');
   const normalized = normalizePhaseName(phase);
 
   const notFound = { found: false, directory: null, phase_number: null, phase_name: null, plans: [], summaries: [] };
@@ -180,7 +180,7 @@ function cmdFindPhase(cwd, phase, raw) {
 
     const result = {
       found: true,
-      directory: toPosixPath(path.join('.planning', 'phases', match)),
+      directory: toPosixPath(path.join(path.relative(cwd, planningDir(cwd)), 'phases', match)),
       phase_number: phaseNumber,
       phase_name: phaseName,
       plans,
@@ -203,7 +203,7 @@ function cmdPhasePlanIndex(cwd, phase, raw) {
     error('phase required for phase-plan-index');
   }
 
-  const phasesDir = path.join(cwd, '.planning', 'phases');
+  const phasesDir = path.join(planningDir(cwd), 'phases');
   const normalized = normalizePhaseName(phase);
 
   // Find phase directory
@@ -308,60 +308,75 @@ function cmdPhasePlanIndex(cwd, phase, raw) {
   output(result, raw);
 }
 
-function cmdPhaseAdd(cwd, description, raw) {
+function cmdPhaseAdd(cwd, description, raw, customId) {
   if (!description) {
     error('description required for phase add');
   }
 
-  const roadmapPath = path.join(cwd, '.planning', 'ROADMAP.md');
+  const config = loadConfig(cwd);
+  const roadmapPath = path.join(planningDir(cwd), 'ROADMAP.md');
   if (!fs.existsSync(roadmapPath)) {
     error('ROADMAP.md not found');
   }
 
-  const content = fs.readFileSync(roadmapPath, 'utf-8');
+  const rawContent = fs.readFileSync(roadmapPath, 'utf-8');
+  const content = extractCurrentMilestone(rawContent, cwd);
   const slug = generateSlugInternal(description);
 
-  // Find highest integer phase number
-  const phasePattern = /#{2,4}\s*Phase\s+(\d+)[A-Z]?(?:\.\d+)*:/gi;
-  let maxPhase = 0;
-  let m;
-  while ((m = phasePattern.exec(content)) !== null) {
-    const num = parseInt(m[1], 10);
-    if (num > maxPhase) maxPhase = num;
+  let newPhaseId;
+  let dirName;
+
+  if (customId || config.phase_naming === 'custom') {
+    // Custom phase naming: use provided ID or generate from description
+    newPhaseId = customId || slug.toUpperCase().replace(/-/g, '-');
+    if (!newPhaseId) error('--id required when phase_naming is "custom"');
+    dirName = `${newPhaseId}-${slug}`;
+  } else {
+    // Sequential mode: find highest integer phase number (in current milestone only)
+    const phasePattern = /#{2,4}\s*Phase\s+(\d+)[A-Z]?(?:\.\d+)*:/gi;
+    let maxPhase = 0;
+    let m;
+    while ((m = phasePattern.exec(content)) !== null) {
+      const num = parseInt(m[1], 10);
+      if (num > maxPhase) maxPhase = num;
+    }
+
+    newPhaseId = maxPhase + 1;
+    const paddedNum = String(newPhaseId).padStart(2, '0');
+    dirName = `${paddedNum}-${slug}`;
   }
 
-  const newPhaseNum = maxPhase + 1;
-  const paddedNum = String(newPhaseNum).padStart(2, '0');
-  const dirName = `${paddedNum}-${slug}`;
-  const dirPath = path.join(cwd, '.planning', 'phases', dirName);
+  const dirPath = path.join(planningDir(cwd), 'phases', dirName);
 
   // Create directory with .gitkeep so git tracks empty folders
   fs.mkdirSync(dirPath, { recursive: true });
   fs.writeFileSync(path.join(dirPath, '.gitkeep'), '');
 
   // Build phase entry
-  const phaseEntry = `\n### Phase ${newPhaseNum}: ${description}\n\n**Goal:** [To be planned]\n**Requirements**: TBD\n**Depends on:** Phase ${maxPhase}\n**Plans:** 0 plans\n\nPlans:\n- [ ] TBD (run /gsd-plan-phase ${newPhaseNum} to break down)\n`;
+  const dependsOn = config.phase_naming === 'custom' ? '' : `\n**Depends on:** Phase ${typeof newPhaseId === 'number' ? newPhaseId - 1 : 'TBD'}`;
+  const phaseEntry = `\n### Phase ${newPhaseId}: ${description}\n\n**Goal:** [To be planned]\n**Requirements**: TBD${dependsOn}\n**Plans:** 0 plans\n\nPlans:\n- [ ] TBD (run /gsd-plan-phase ${newPhaseId} to break down)\n`;
 
   // Find insertion point: before last "---" or at end
   let updatedContent;
-  const lastSeparator = content.lastIndexOf('\n---');
+  const lastSeparator = rawContent.lastIndexOf('\n---');
   if (lastSeparator > 0) {
-    updatedContent = content.slice(0, lastSeparator) + phaseEntry + content.slice(lastSeparator);
+    updatedContent = rawContent.slice(0, lastSeparator) + phaseEntry + rawContent.slice(lastSeparator);
   } else {
-    updatedContent = content + phaseEntry;
+    updatedContent = rawContent + phaseEntry;
   }
 
   fs.writeFileSync(roadmapPath, updatedContent, 'utf-8');
 
   const result = {
-    phase_number: newPhaseNum,
-    padded: paddedNum,
+    phase_number: typeof newPhaseId === 'number' ? newPhaseId : String(newPhaseId),
+    padded: typeof newPhaseId === 'number' ? String(newPhaseId).padStart(2, '0') : String(newPhaseId),
     name: description,
     slug,
-    directory: `.planning/phases/${dirName}`,
+    directory: toPosixPath(path.join(path.relative(cwd, planningDir(cwd)), 'phases', dirName)),
+    naming_mode: config.phase_naming,
   };
 
-  output(result, raw, paddedNum);
+  output(result, raw, result.padded);
 }
 
 function cmdPhaseInsert(cwd, afterPhase, description, raw) {
@@ -369,12 +384,13 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) {
     error('after-phase and description required for phase insert');
   }
 
-  const roadmapPath = path.join(cwd, '.planning', 'ROADMAP.md');
+  const roadmapPath = path.join(planningDir(cwd), 'ROADMAP.md');
   if (!fs.existsSync(roadmapPath)) {
     error('ROADMAP.md not found');
   }
 
-  const content = fs.readFileSync(roadmapPath, 'utf-8');
+  const rawContent = fs.readFileSync(roadmapPath, 'utf-8');
+  const content = extractCurrentMilestone(rawContent, cwd);
   const slug = generateSlugInternal(description);
 
   // Normalize input then strip leading zeros for flexible matching
@@ -387,7 +403,7 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) {
   }
 
   // Calculate next decimal using existing logic
-  const phasesDir = path.join(cwd, '.planning', 'phases');
+  const phasesDir = path.join(planningDir(cwd), 'phases');
   const normalizedBase = normalizePhaseName(afterPhase);
   let existingDecimals = [];
 
@@ -399,12 +415,12 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) {
       const dm = dir.match(decimalPattern);
       if (dm) existingDecimals.push(parseInt(dm[1], 10));
     }
-  } catch {}
+  } catch { /* intentionally empty */ }
 
   const nextDecimal = existingDecimals.length === 0 ? 1 : Math.max(...existingDecimals) + 1;
   const decimalPhase = `${normalizedBase}.${nextDecimal}`;
   const dirName = `${decimalPhase}-${slug}`;
-  const dirPath = path.join(cwd, '.planning', 'phases', dirName);
+  const dirPath = path.join(planningDir(cwd), 'phases', dirName);
 
   // Create directory with .gitkeep so git tracks empty folders
   fs.mkdirSync(dirPath, { recursive: true });
@@ -415,23 +431,23 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) {
 
   // Insert after the target phase section
   const headerPattern = new RegExp(`(#{2,4}\\s*Phase\\s+0*${afterPhaseEscaped}:[^\\n]*\\n)`, 'i');
-  const headerMatch = content.match(headerPattern);
+  const headerMatch = rawContent.match(headerPattern);
   if (!headerMatch) {
     error(`Could not find Phase ${afterPhase} header`);
   }
 
-  const headerIdx = content.indexOf(headerMatch[0]);
-  const afterHeader = content.slice(headerIdx + headerMatch[0].length);
+  const headerIdx = rawContent.indexOf(headerMatch[0]);
+  const afterHeader = rawContent.slice(headerIdx + headerMatch[0].length);
   const nextPhaseMatch = afterHeader.match(/\n#{2,4}\s+Phase\s+\d/i);
 
   let insertIdx;
   if (nextPhaseMatch) {
     insertIdx = headerIdx + headerMatch[0].length + nextPhaseMatch.index;
   } else {
-    insertIdx = content.length;
+    insertIdx = rawContent.length;
   }
 
-  const updatedContent = content.slice(0, insertIdx) + phaseEntry + content.slice(insertIdx);
+  const updatedContent = rawContent.slice(0, insertIdx) + phaseEntry + rawContent.slice(insertIdx);
   fs.writeFileSync(roadmapPath, updatedContent, 'utf-8');
 
   const result = {
@@ -439,263 +455,175 @@ function cmdPhaseInsert(cwd, afterPhase, description, raw) {
     after_phase: afterPhase,
     name: description,
     slug,
-    directory: `.planning/phases/${dirName}`,
+    directory: toPosixPath(path.join(path.relative(cwd, planningDir(cwd)), 'phases', dirName)),
   };
 
   output(result, raw, decimalPhase);
 }
 
-function cmdPhaseRemove(cwd, targetPhase, options, raw) {
-  if (!targetPhase) {
-    error('phase number required for phase remove');
+/**
+ * Renumber sibling decimal phases after a decimal phase is removed.
+ * e.g. removing 06.2 → 06.3 becomes 06.2, 06.4 becomes 06.3, etc.
+ * Returns { renamedDirs, renamedFiles }.
+ */
+function renameDecimalPhases(phasesDir, baseInt, removedDecimal) {
+  const renamedDirs = [], renamedFiles = [];
+  const decPattern = new RegExp(`^${baseInt}\\.(\\d+)-(.+)$`);
+  const dirs = readSubdirectories(phasesDir, true);
+  const toRename = dirs
+    .map(dir => { const m = dir.match(decPattern); return m ? { dir, oldDecimal: parseInt(m[1], 10), slug: m[2] } : null; })
+    .filter(item => item && item.oldDecimal > removedDecimal)
+    .sort((a, b) => b.oldDecimal - a.oldDecimal); // descending to avoid conflicts
+
+  for (const item of toRename) {
+    const newDecimal = item.oldDecimal - 1;
+    const oldPhaseId = `${baseInt}.${item.oldDecimal}`;
+    const newPhaseId = `${baseInt}.${newDecimal}`;
+    const newDirName = `${baseInt}.${newDecimal}-${item.slug}`;
+    fs.renameSync(path.join(phasesDir, item.dir), path.join(phasesDir, newDirName));
+    renamedDirs.push({ from: item.dir, to: newDirName });
+    for (const f of fs.readdirSync(path.join(phasesDir, newDirName))) {
+      if (f.includes(oldPhaseId)) {
+        const newFileName = f.replace(oldPhaseId, newPhaseId);
+        fs.renameSync(path.join(phasesDir, newDirName, f), path.join(phasesDir, newDirName, newFileName));
+        renamedFiles.push({ from: f, to: newFileName });
+      }
+    }
   }
+  return { renamedDirs, renamedFiles };
+}
 
-  const roadmapPath = path.join(cwd, '.planning', 'ROADMAP.md');
-  const phasesDir = path.join(cwd, '.planning', 'phases');
-  const force = options.force || false;
-
-  if (!fs.existsSync(roadmapPath)) {
-    error('ROADMAP.md not found');
+/**
+ * Renumber all integer phases after removedInt.
+ * e.g. removing phase 5 → phase 6 becomes 5, phase 7 becomes 6, etc.
+ * Returns { renamedDirs, renamedFiles }.
+ */
+function renameIntegerPhases(phasesDir, removedInt) {
+  const renamedDirs = [], renamedFiles = [];
+  const dirs = readSubdirectories(phasesDir, true);
+  const toRename = dirs
+    .map(dir => {
+      const m = dir.match(/^(\d+)([A-Z])?(?:\.(\d+))?-(.+)$/i);
+      if (!m) return null;
+      const dirInt = parseInt(m[1], 10);
+      return dirInt > removedInt ? { dir, oldInt: dirInt, letter: m[2] ? m[2].toUpperCase() : '', decimal: m[3] ? parseInt(m[3], 10) : null, slug: m[4] } : null;
+    })
+    .filter(Boolean)
+    .sort((a, b) => a.oldInt !== b.oldInt ? b.oldInt - a.oldInt : (b.decimal || 0) - (a.decimal || 0));
+
+  for (const item of toRename) {
+    const newInt = item.oldInt - 1;
+    const newPadded = String(newInt).padStart(2, '0');
+    const oldPadded = String(item.oldInt).padStart(2, '0');
+    const letterSuffix = item.letter || '';
+    const decimalSuffix = item.decimal !== null ? `.${item.decimal}` : '';
+    const oldPrefix = `${oldPadded}${letterSuffix}${decimalSuffix}`;
+    const newPrefix = `${newPadded}${letterSuffix}${decimalSuffix}`;
+    const newDirName = `${newPrefix}-${item.slug}`;
+    fs.renameSync(path.join(phasesDir, item.dir), path.join(phasesDir, newDirName));
+    renamedDirs.push({ from: item.dir, to: newDirName });
+    for (const f of fs.readdirSync(path.join(phasesDir, newDirName))) {
+      if (f.startsWith(oldPrefix)) {
+        const newFileName = newPrefix + f.slice(oldPrefix.length);
+        fs.renameSync(path.join(phasesDir, newDirName, f), path.join(phasesDir, newDirName, newFileName));
+        renamedFiles.push({ from: f, to: newFileName });
+      }
+    }
   }
+  return { renamedDirs, renamedFiles };
+}
 
-  // Normalize the target
-  const normalized = normalizePhaseName(targetPhase);
-  const isDecimal = targetPhase.includes('.');
+/**
+ * Remove a phase section from ROADMAP.md and renumber all subsequent integer phases.
+ */
+function updateRoadmapAfterPhaseRemoval(roadmapPath, targetPhase, isDecimal, removedInt) {
+  let content = fs.readFileSync(roadmapPath, 'utf-8');
+  const escaped = escapeRegex(targetPhase);
 
-  // Find and validate target directory
-  let targetDir = null;
-  try {
-    const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
-    const dirs = entries.filter(e => e.isDirectory()).map(e => e.name).sort((a, b) => comparePhaseNum(a, b));
-    targetDir = dirs.find(d => d.startsWith(normalized + '-') || d === normalized);
-  } catch {}
+  content = content.replace(new RegExp(`\\n?#{2,4}\\s*Phase\\s+${escaped}\\s*:[\\s\\S]*?(?=\\n#{2,4}\\s+Phase\\s+\\d|$)`, 'i'), '');
+  content = content.replace(new RegExp(`\\n?-\\s*\\[[ x]\\]\\s*.*Phase\\s+${escaped}[:\\s][^\\n]*`, 'gi'), '');
+  content = content.replace(new RegExp(`\\n?\\|\\s*${escaped}\\.?\\s[^|]*\\|[^\\n]*`, 'gi'), '');
 
-  // Check for executed work (SUMMARY.md files)
-  if (targetDir && !force) {
-    const targetPath = path.join(phasesDir, targetDir);
-    const files = fs.readdirSync(targetPath);
-    const summaries = files.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md');
-    if (summaries.length > 0) {
-      error(`Phase ${targetPhase} has ${summaries.length} executed plan(s). Use --force to remove anyway.`);
+  if (!isDecimal) {
+    const MAX_PHASE = 99;
+    for (let oldNum = MAX_PHASE; oldNum > removedInt; oldNum--) {
+      const newNum = oldNum - 1;
+      const oldStr = String(oldNum), newStr = String(newNum);
+      const oldPad = oldStr.padStart(2, '0'), newPad = newStr.padStart(2, '0');
+      content = content.replace(new RegExp(`(#{2,4}\\s*Phase\\s+)${oldStr}(\\s*:)`, 'gi'), `$1${newStr}$2`);
+      content = content.replace(new RegExp(`(Phase\\s+)${oldStr}([:\\s])`, 'g'), `$1${newStr}$2`);
+      content = content.replace(new RegExp(`${oldPad}-(\\d{2})`, 'g'), `${newPad}-$1`);
+      content = content.replace(new RegExp(`(\\|\\s*)${oldStr}\\.\\s`, 'g'), `$1${newStr}. `);
+      content = content.replace(new RegExp(`(Depends on:\\*\\*\\s*Phase\\s+)${oldStr}\\b`, 'gi'), `$1${newStr}`);
     }
   }
 
-  // Delete target directory
-  if (targetDir) {
-    fs.rmSync(path.join(phasesDir, targetDir), { recursive: true, force: true });
-  }
-
-  // Renumber subsequent phases
-  const renamedDirs = [];
-  const renamedFiles = [];
-
-  if (isDecimal) {
-    // Decimal removal: renumber sibling decimals (e.g., removing 06.2 → 06.3 becomes 06.2)
-    const baseParts = normalized.split('.');
-    const baseInt = baseParts[0];
-    const removedDecimal = parseInt(baseParts[1], 10);
-
-    try {
-      const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
-      const dirs = entries.filter(e => e.isDirectory()).map(e => e.name).sort((a, b) => comparePhaseNum(a, b));
+  fs.writeFileSync(roadmapPath, content, 'utf-8');
+}
 
-      // Find sibling decimals with higher numbers
-      const decPattern = new RegExp(`^${baseInt}\\.(\\d+)-(.+)$`);
-      const toRename = [];
-      for (const dir of dirs) {
-        const dm = dir.match(decPattern);
-        if (dm && parseInt(dm[1], 10) > removedDecimal) {
-          toRename.push({ dir, oldDecimal: parseInt(dm[1], 10), slug: dm[2] });
-        }
-      }
+function cmdPhaseRemove(cwd, targetPhase, options, raw) {
+  if (!targetPhase) error('phase number required for phase remove');
 
-      // Sort descending to avoid conflicts
-      toRename.sort((a, b) => b.oldDecimal - a.oldDecimal);
-
-      for (const item of toRename) {
-        const newDecimal = item.oldDecimal - 1;
-        const oldPhaseId = `${baseInt}.${item.oldDecimal}`;
-        const newPhaseId = `${baseInt}.${newDecimal}`;
-        const newDirName = `${baseInt}.${newDecimal}-${item.slug}`;
-
-        // Rename directory
-        fs.renameSync(path.join(phasesDir, item.dir), path.join(phasesDir, newDirName));
-        renamedDirs.push({ from: item.dir, to: newDirName });
-
-        // Rename files inside
-        const dirFiles = fs.readdirSync(path.join(phasesDir, newDirName));
-        for (const f of dirFiles) {
-          // Files may have phase prefix like "06.2-01-PLAN.md"
-          if (f.includes(oldPhaseId)) {
-            const newFileName = f.replace(oldPhaseId, newPhaseId);
-            fs.renameSync(
-              path.join(phasesDir, newDirName, f),
-              path.join(phasesDir, newDirName, newFileName)
-            );
-            renamedFiles.push({ from: f, to: newFileName });
-          }
-        }
-      }
-    } catch {}
+  const roadmapPath = path.join(planningDir(cwd), 'ROADMAP.md');
+  const phasesDir = path.join(planningDir(cwd), 'phases');
 
-  } else {
-    // Integer removal: renumber all subsequent integer phases
-    const removedInt = parseInt(normalized, 10);
+  if (!fs.existsSync(roadmapPath)) error('ROADMAP.md not found');
 
-    try {
-      const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
-      const dirs = entries.filter(e => e.isDirectory()).map(e => e.name).sort((a, b) => comparePhaseNum(a, b));
+  const normalized = normalizePhaseName(targetPhase);
+  const isDecimal = targetPhase.includes('.');
+  const force = options.force || false;
 
-      // Collect directories that need renumbering (integer phases > removed, and their decimals/letters)
-      const toRename = [];
-      for (const dir of dirs) {
-        const dm = dir.match(/^(\d+)([A-Z])?(?:\.(\d+))?-(.+)$/i);
-        if (!dm) continue;
-        const dirInt = parseInt(dm[1], 10);
-        if (dirInt > removedInt) {
-          toRename.push({
-            dir,
-            oldInt: dirInt,
-            letter: dm[2] ? dm[2].toUpperCase() : '',
-            decimal: dm[3] ? parseInt(dm[3], 10) : null,
-            slug: dm[4],
-          });
-        }
-      }
+  // Find target directory
+  const targetDir = readSubdirectories(phasesDir, true)
+    .find(d => d.startsWith(normalized + '-') || d === normalized) || null;
 
-      // Sort descending to avoid conflicts
-      toRename.sort((a, b) => {
-        if (a.oldInt !== b.oldInt) return b.oldInt - a.oldInt;
-        return (b.decimal || 0) - (a.decimal || 0);
-      });
-
-      for (const item of toRename) {
-        const newInt = item.oldInt - 1;
-        const newPadded = String(newInt).padStart(2, '0');
-        const oldPadded = String(item.oldInt).padStart(2, '0');
-        const letterSuffix = item.letter || '';
-        const decimalSuffix = item.decimal !== null ? `.${item.decimal}` : '';
-        const oldPrefix = `${oldPadded}${letterSuffix}${decimalSuffix}`;
-        const newPrefix = `${newPadded}${letterSuffix}${decimalSuffix}`;
-        const newDirName = `${newPrefix}-${item.slug}`;
-
-        // Rename directory
-        fs.renameSync(path.join(phasesDir, item.dir), path.join(phasesDir, newDirName));
-        renamedDirs.push({ from: item.dir, to: newDirName });
-
-        // Rename files inside
-        const dirFiles = fs.readdirSync(path.join(phasesDir, newDirName));
-        for (const f of dirFiles) {
-          if (f.startsWith(oldPrefix)) {
-            const newFileName = newPrefix + f.slice(oldPrefix.length);
-            fs.renameSync(
-              path.join(phasesDir, newDirName, f),
-              path.join(phasesDir, newDirName, newFileName)
-            );
-            renamedFiles.push({ from: f, to: newFileName });
-          }
-        }
-      }
-    } catch {}
+  // Guard against removing executed work
+  if (targetDir && !force) {
+    const files = fs.readdirSync(path.join(phasesDir, targetDir));
+    const summaries = files.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md');
+    if (summaries.length > 0) {
+      error(`Phase ${targetPhase} has ${summaries.length} executed plan(s). Use --force to remove anyway.`);
+    }
   }
 
-  // Update ROADMAP.md
-  let roadmapContent = fs.readFileSync(roadmapPath, 'utf-8');
-
-  // Remove the target phase section
-  const targetEscaped = escapeRegex(targetPhase);
-  const sectionPattern = new RegExp(
-    `\\n?#{2,4}\\s*Phase\\s+${targetEscaped}\\s*:[\\s\\S]*?(?=\\n#{2,4}\\s+Phase\\s+\\d|$)`,
-    'i'
-  );
-  roadmapContent = roadmapContent.replace(sectionPattern, '');
-
-  // Remove from phase list (checkbox)
-  const checkboxPattern = new RegExp(`\\n?-\\s*\\[[ x]\\]\\s*.*Phase\\s+${targetEscaped}[:\\s][^\\n]*`, 'gi');
-  roadmapContent = roadmapContent.replace(checkboxPattern, '');
-
-  // Remove from progress table
-  const tableRowPattern = new RegExp(`\\n?\\|\\s*${targetEscaped}\\.?\\s[^|]*\\|[^\\n]*`, 'gi');
-  roadmapContent = roadmapContent.replace(tableRowPattern, '');
+  if (targetDir) fs.rmSync(path.join(phasesDir, targetDir), { recursive: true, force: true });
 
-  // Renumber references in ROADMAP for subsequent phases
-  if (!isDecimal) {
-    const removedInt = parseInt(normalized, 10);
-
-    // Collect all integer phases > removedInt
-    const maxPhase = 99; // reasonable upper bound
-    for (let oldNum = maxPhase; oldNum > removedInt; oldNum--) {
-      const newNum = oldNum - 1;
-      const oldStr = String(oldNum);
-      const newStr = String(newNum);
-      const oldPad = oldStr.padStart(2, '0');
-      const newPad = newStr.padStart(2, '0');
-
-      // Phase headings: ## Phase 18: or ### Phase 18: → ## Phase 17: or ### Phase 17:
-      roadmapContent = roadmapContent.replace(
-        new RegExp(`(#{2,4}\\s*Phase\\s+)${oldStr}(\\s*:)`, 'gi'),
-        `$1${newStr}$2`
-      );
-
-      // Checkbox items: - [ ] **Phase 18:** → - [ ] **Phase 17:**
-      roadmapContent = roadmapContent.replace(
-        new RegExp(`(Phase\\s+)${oldStr}([:\\s])`, 'g'),
-        `$1${newStr}$2`
-      );
-
-      // Plan references: 18-01 → 17-01
-      roadmapContent = roadmapContent.replace(
-        new RegExp(`${oldPad}-(\\d{2})`, 'g'),
-        `${newPad}-$1`
-      );
-
-      // Table rows: | 18. → | 17.
-      roadmapContent = roadmapContent.replace(
-        new RegExp(`(\\|\\s*)${oldStr}\\.\\s`, 'g'),
-        `$1${newStr}. `
-      );
-
-      // Depends on references
-      roadmapContent = roadmapContent.replace(
-        new RegExp(`(Depends on:\\*\\*\\s*Phase\\s+)${oldStr}\\b`, 'gi'),
-        `$1${newStr}`
-      );
-    }
-  }
+  // Renumber subsequent phases on disk
+  let renamedDirs = [], renamedFiles = [];
+  try {
+    const renamed = isDecimal
+      ? renameDecimalPhases(phasesDir, normalized.split('.')[0], parseInt(normalized.split('.')[1], 10))
+      : renameIntegerPhases(phasesDir, parseInt(normalized, 10));
+    renamedDirs = renamed.renamedDirs;
+    renamedFiles = renamed.renamedFiles;
+  } catch { /* intentionally empty */ }
 
-  fs.writeFileSync(roadmapPath, roadmapContent, 'utf-8');
+  // Update ROADMAP.md
+  updateRoadmapAfterPhaseRemoval(roadmapPath, targetPhase, isDecimal, parseInt(normalized, 10));
 
   // Update STATE.md phase count
-  const statePath = path.join(cwd, '.planning', 'STATE.md');
+  const statePath = path.join(planningDir(cwd), 'STATE.md');
   if (fs.existsSync(statePath)) {
     let stateContent = fs.readFileSync(statePath, 'utf-8');
-    // Update "Total Phases" field
-    const totalPattern = /(\*\*Total Phases:\*\*\s*)(\d+)/;
-    const totalMatch = stateContent.match(totalPattern);
-    if (totalMatch) {
-      const oldTotal = parseInt(totalMatch[2], 10);
-      stateContent = stateContent.replace(totalPattern, `$1${oldTotal - 1}`);
+    const totalRaw = stateExtractField(stateContent, 'Total Phases');
+    if (totalRaw) {
+      stateContent = stateReplaceField(stateContent, 'Total Phases', String(parseInt(totalRaw, 10) - 1)) || stateContent;
     }
-    // Update "Phase: X of Y" pattern
-    const ofPattern = /(\bof\s+)(\d+)(\s*(?:\(|phases?))/i;
-    const ofMatch = stateContent.match(ofPattern);
+    const ofMatch = stateContent.match(/(\bof\s+)(\d+)(\s*(?:\(|phases?))/i);
     if (ofMatch) {
-      const oldTotal = parseInt(ofMatch[2], 10);
-      stateContent = stateContent.replace(ofPattern, `$1${oldTotal - 1}$3`);
+      stateContent = stateContent.replace(/(\bof\s+)(\d+)(\s*(?:\(|phases?))/i, `$1${parseInt(ofMatch[2], 10) - 1}$3`);
     }
     writeStateMd(statePath, stateContent, cwd);
   }
 
-  const result = {
+  output({
     removed: targetPhase,
-    directory_deleted: targetDir || null,
+    directory_deleted: targetDir,
     renamed_directories: renamedDirs,
     renamed_files: renamedFiles,
     roadmap_updated: true,
     state_updated: fs.existsSync(statePath),
-  };
-
-  output(result, raw);
+  }, raw);
 }
 
 function cmdPhaseComplete(cwd, phaseNum, raw) {
@@ -703,9 +631,9 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
     error('phase number required for phase complete');
   }
 
-  const roadmapPath = path.join(cwd, '.planning', 'ROADMAP.md');
-  const statePath = path.join(cwd, '.planning', 'STATE.md');
-  const phasesDir = path.join(cwd, '.planning', 'phases');
+  const roadmapPath = path.join(planningDir(cwd), 'ROADMAP.md');
+  const statePath = path.join(planningDir(cwd), 'STATE.md');
+  const phasesDir = path.join(planningDir(cwd), 'phases');
   const normalized = normalizePhaseName(phaseNum);
   const today = new Date().toISOString().split('T')[0];
 
@@ -717,6 +645,28 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
 
   const planCount = phaseInfo.plans.length;
   const summaryCount = phaseInfo.summaries.length;
+  let requirementsUpdated = false;
+
+  // Check for unresolved verification debt (non-blocking warnings)
+  const warnings = [];
+  try {
+    const phaseFullDir = path.join(cwd, phaseInfo.directory);
+    const phaseFiles = fs.readdirSync(phaseFullDir);
+
+    for (const file of phaseFiles.filter(f => f.includes('-UAT') && f.endsWith('.md'))) {
+      const content = fs.readFileSync(path.join(phaseFullDir, file), 'utf-8');
+      if (/result: pending/.test(content)) warnings.push(`${file}: has pending tests`);
+      if (/result: blocked/.test(content)) warnings.push(`${file}: has blocked tests`);
+      if (/status: partial/.test(content)) warnings.push(`${file}: testing incomplete (partial)`);
+      if (/status: diagnosed/.test(content)) warnings.push(`${file}: has diagnosed gaps`);
+    }
+
+    for (const file of phaseFiles.filter(f => f.includes('-VERIFICATION') && f.endsWith('.md'))) {
+      const content = fs.readFileSync(path.join(phaseFullDir, file), 'utf-8');
+      if (/status: human_needed/.test(content)) warnings.push(`${file}: needs human verification`);
+      if (/status: gaps_found/.test(content)) warnings.push(`${file}: has unresolved gaps`);
+    }
+  } catch {}
 
   // Update ROADMAP.md: mark phase complete
   if (fs.existsSync(roadmapPath)) {
@@ -727,39 +677,53 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
       `(-\\s*\\[)[ ](\\]\\s*.*Phase\\s+${escapeRegex(phaseNum)}[:\\s][^\\n]*)`,
       'i'
     );
-    roadmapContent = roadmapContent.replace(checkboxPattern, `$1x$2 (completed ${today})`);
+    roadmapContent = replaceInCurrentMilestone(roadmapContent, checkboxPattern, `$1x$2 (completed ${today})`);
 
-    // Progress table: update Status to Complete, add date
+    // Progress table: update Status to Complete, add date (handles 4 or 5 column tables)
     const phaseEscaped = escapeRegex(phaseNum);
-    const tablePattern = new RegExp(
-      `(\\|\\s*${phaseEscaped}\\.?\\s[^|]*\\|[^|]*\\|)\\s*[^|]*(\\|)\\s*[^|]*(\\|)`,
-      'i'
-    );
-    roadmapContent = roadmapContent.replace(
-      tablePattern,
-      `$1 Complete    $2 ${today} $3`
+    const tableRowPattern = new RegExp(
+      `^(\\|\\s*${phaseEscaped}\\.?\\s[^|]*(?:\\|[^\\n]*))$`,
+      'im'
     );
+    roadmapContent = roadmapContent.replace(tableRowPattern, (fullRow) => {
+      const cells = fullRow.split('|').slice(1, -1);
+      if (cells.length === 5) {
+        // 5-col: Phase | Milestone | Plans | Status | Completed
+        cells[3] = ' Complete    ';
+        cells[4] = ` ${today} `;
+      } else if (cells.length === 4) {
+        // 4-col: Phase | Plans | Status | Completed
+        cells[2] = ' Complete    ';
+        cells[3] = ` ${today} `;
+      }
+      return '|' + cells.join('|') + '|';
+    });
 
     // Update plan count in phase section
     const planCountPattern = new RegExp(
       `(#{2,4}\\s*Phase\\s+${phaseEscaped}[\\s\\S]*?\\*\\*Plans:\\*\\*\\s*)[^\\n]+`,
       'i'
     );
-    roadmapContent = roadmapContent.replace(
-      planCountPattern,
+    roadmapContent = replaceInCurrentMilestone(
+      roadmapContent, planCountPattern,
       `$1${summaryCount}/${planCount} plans complete`
     );
 
     fs.writeFileSync(roadmapPath, roadmapContent, 'utf-8');
 
     // Update REQUIREMENTS.md traceability for this phase's requirements
-    const reqPath = path.join(cwd, '.planning', 'REQUIREMENTS.md');
+    const reqPath = path.join(planningDir(cwd), 'REQUIREMENTS.md');
     if (fs.existsSync(reqPath)) {
-      // Extract Requirements line from roadmap for this phase
-      const reqMatch = roadmapContent.match(
-        new RegExp(`Phase\\s+${escapeRegex(phaseNum)}[\\s\\S]*?\\*\\*Requirements:\\*\\*\\s*([^\\n]+)`, 'i')
+      // Extract the current phase section from roadmap (scoped to avoid cross-phase matching)
+      const phaseEsc = escapeRegex(phaseNum);
+      const currentMilestoneRoadmap = extractCurrentMilestone(roadmapContent, cwd);
+      const phaseSectionMatch = currentMilestoneRoadmap.match(
+        new RegExp(`(#{2,4}\\s*Phase\\s+${phaseEsc}[:\\s][\\s\\S]*?)(?=#{2,4}\\s*Phase\\s+|$)`, 'i')
       );
 
+      const sectionText = phaseSectionMatch ? phaseSectionMatch[1] : '';
+      const reqMatch = sectionText.match(/\*\*Requirements:\*\*\s*([^\n]+)/i);
+
       if (reqMatch) {
         const reqIds = reqMatch[1].replace(/[\[\]]/g, '').split(/[,\s]+/).map(r => r.trim()).filter(Boolean);
         let reqContent = fs.readFileSync(reqPath, 'utf-8');
@@ -771,14 +735,15 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
             new RegExp(`(-\\s*\\[)[ ](\\]\\s*\\*\\*${reqEscaped}\\*\\*)`, 'gi'),
             '$1x$2'
           );
-          // Update traceability table: | REQ-ID | Phase N | Pending | → | REQ-ID | Phase N | Complete |
+          // Update traceability table: | REQ-ID | Phase N | Pending/In Progress | → | REQ-ID | Phase N | Complete |
           reqContent = reqContent.replace(
-            new RegExp(`(\\|\\s*${reqEscaped}\\s*\\|[^|]+\\|)\\s*Pending\\s*(\\|)`, 'gi'),
+            new RegExp(`(\\|\\s*${reqEscaped}\\s*\\|[^|]+\\|)\\s*(?:Pending|In Progress)\\s*(\\|)`, 'gi'),
             '$1 Complete $2'
           );
         }
 
         fs.writeFileSync(reqPath, reqContent, 'utf-8');
+        requirementsUpdated = true;
       }
     }
   }
@@ -809,13 +774,13 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
         }
       }
     }
-  } catch {}
+  } catch { /* intentionally empty */ }
 
   // Fallback: if filesystem found no next phase, check ROADMAP.md
   // for phases that are defined but not yet planned (no directory on disk)
   if (isLastPhase && fs.existsSync(roadmapPath)) {
     try {
-      const roadmapForPhases = fs.readFileSync(roadmapPath, 'utf-8');
+      const roadmapForPhases = extractCurrentMilestone(fs.readFileSync(roadmapPath, 'utf-8'), cwd);
       const phasePattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:\s*([^\n]+)/gi;
       let pm;
       while ((pm = phasePattern.exec(roadmapForPhases)) !== null) {
@@ -826,50 +791,69 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
           break;
         }
       }
-    } catch {}
+    } catch { /* intentionally empty */ }
   }
 
-  // Update STATE.md
+  // Update STATE.md — use shared helpers that handle both **bold:** and plain Field: formats
   if (fs.existsSync(statePath)) {
     let stateContent = fs.readFileSync(statePath, 'utf-8');
 
-    // Update Current Phase
-    stateContent = stateContent.replace(
-      /(\*\*Current Phase:\*\*\s*).*/,
-      `$1${nextPhaseNum || phaseNum}`
-    );
+    // Update Current Phase — preserve "X of Y (Name)" compound format
+    const phaseValue = nextPhaseNum || phaseNum;
+    const existingPhaseField = stateExtractField(stateContent, 'Current Phase')
+      || stateExtractField(stateContent, 'Phase');
+    let newPhaseValue = String(phaseValue);
+    if (existingPhaseField) {
+      const totalMatch = existingPhaseField.match(/of\s+(\d+)/);
+      const nameMatch = existingPhaseField.match(/\(([^)]+)\)/);
+      if (totalMatch) {
+        const total = totalMatch[1];
+        const nameStr = nextPhaseName ? ` (${nextPhaseName.replace(/-/g, ' ')})` : (nameMatch ? ` (${nameMatch[1]})` : '');
+        newPhaseValue = `${phaseValue} of ${total}${nameStr}`;
+      }
+    }
+    stateContent = stateReplaceFieldWithFallback(stateContent, 'Current Phase', 'Phase', newPhaseValue);
 
     // Update Current Phase Name
     if (nextPhaseName) {
-      stateContent = stateContent.replace(
-        /(\*\*Current Phase Name:\*\*\s*).*/,
-        `$1${nextPhaseName.replace(/-/g, ' ')}`
-      );
+      stateContent = stateReplaceFieldWithFallback(stateContent, 'Current Phase Name', null, nextPhaseName.replace(/-/g, ' '));
     }
 
     // Update Status
-    stateContent = stateContent.replace(
-      /(\*\*Status:\*\*\s*).*/,
-      `$1${isLastPhase ? 'Milestone complete' : 'Ready to plan'}`
-    );
+    stateContent = stateReplaceFieldWithFallback(stateContent, 'Status', null,
+      isLastPhase ? 'Milestone complete' : 'Ready to plan');
 
     // Update Current Plan
-    stateContent = stateContent.replace(
-      /(\*\*Current Plan:\*\*\s*).*/,
-      `$1Not started`
-    );
+    stateContent = stateReplaceFieldWithFallback(stateContent, 'Current Plan', 'Plan', 'Not started');
 
     // Update Last Activity
-    stateContent = stateContent.replace(
-      /(\*\*Last Activity:\*\*\s*).*/,
-      `$1${today}`
-    );
+    stateContent = stateReplaceFieldWithFallback(stateContent, 'Last Activity', 'Last activity', today);
 
     // Update Last Activity Description
-    stateContent = stateContent.replace(
-      /(\*\*Last Activity Description:\*\*\s*).*/,
-      `$1Phase ${phaseNum} complete${nextPhaseNum ? `, transitioned to Phase ${nextPhaseNum}` : ''}`
-    );
+    stateContent = stateReplaceFieldWithFallback(stateContent, 'Last Activity Description', null,
+      `Phase ${phaseNum} complete${nextPhaseNum ? `, transitioned to Phase ${nextPhaseNum}` : ''}`);
+
+    // Increment Completed Phases counter (#956)
+    const completedRaw = stateExtractField(stateContent, 'Completed Phases');
+    if (completedRaw) {
+      const newCompleted = parseInt(completedRaw, 10) + 1;
+      stateContent = stateReplaceField(stateContent, 'Completed Phases', String(newCompleted)) || stateContent;
+
+      // Recalculate percent based on completed / total (#956)
+      const totalRaw = stateExtractField(stateContent, 'Total Phases');
+      if (totalRaw) {
+        const totalPhases = parseInt(totalRaw, 10);
+        if (totalPhases > 0) {
+          const newPercent = Math.round((newCompleted / totalPhases) * 100);
+          stateContent = stateReplaceField(stateContent, 'Progress', `${newPercent}%`) || stateContent;
+          // Also update percent field if it exists separately
+          stateContent = stateContent.replace(
+            /(percent:\s*)\d+/,
+            `$1${newPercent}`
+          );
+        }
+      }
+    }
 
     writeStateMd(statePath, stateContent, cwd);
   }
@@ -884,6 +868,9 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
     date: today,
     roadmap_updated: fs.existsSync(roadmapPath),
     state_updated: fs.existsSync(statePath),
+    requirements_updated: requirementsUpdated,
+    warnings,
+    has_warnings: warnings.length > 0,
   };
 
   output(result, raw);