@opengsd/gsd-core 1.2.0 → 1.3.0-rc.1

package/get-shit-done/bin/lib/roadmap-upgrade.cjs

@@ -0,0 +1,569 @@
+'use strict';
+
+/**
+ * Roadmap Upgrade — Migration tool for converting legacy 'Phase N' phase IDs
+ * to milestone-prefixed 'Phase M-NN' form.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const { planningDir } = require('./planning-workspace.cjs');
+
+// ─── Regex helpers ────────────────────────────────────────────────────────────
+
+// Matches legacy phase headings: ### Phase N: Name  (also decimal: Phase 2.1:)
+// Captures: (hashes)(spaces)(phase-number)(rest-of-line)
+const LEGACY_PHASE_HEADING_RE = /^(#{2,4})\s*(?:\[[^\]]+\]\s*)?Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:(.*)/i;
+
+// Matches already-migrated phase headings: ### Phase M-NN: Name
+const MIGRATED_PHASE_HEADING_RE = /^#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+\d+-\d{2}\s*:/i;
+
+// Matches milestone section headings: ## v1.0, ## Roadmap v2.0, ## ✅ v1.0, ## [GSD] v1.0, etc.
+// The optional bracket-token prefix (e.g., [GSD]) must be tested before the emoji group.
+const MILESTONE_HEADING_RE = /^##\s+(?:\[[^\]]+\]\s+|Roadmap\s+|[✅🚧]\s*)?v(\d+)\.(\d+)(?:\s|:)/iu;
+
+// Matches checklist phase references: - [ ] **Phase N:** or - [x] **Phase N:**  (also decimal)
+const CHECKLIST_PHASE_RE = /^(\s*-\s*\[[ x]\]\s*\*{0,2})Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:/gi;
+
+// ─── Pure computation helpers ─────────────────────────────────────────────────
+
+/**
+ * Parse the ROADMAP.md content and build a list of phase entries with their
+ * enclosing milestone major version.
+ *
+ * Returns an array of:
+ *   { lineIndex, headingLine, milestoneInt, legacyPhaseNum, phaseName }
+ */
+function parseRoadmapPhases(lines) {
+  const results = [];
+  let currentMilestoneInt = null;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    const milestoneMatch = line.match(MILESTONE_HEADING_RE);
+    if (milestoneMatch) {
+      currentMilestoneInt = parseInt(milestoneMatch[1], 10);
+      continue;
+    }
+
+    if (MIGRATED_PHASE_HEADING_RE.test(line)) {
+      // Already-migrated heading found — caller will detect this
+      results.push({ lineIndex: i, headingLine: line, alreadyMigrated: true });
+      continue;
+    }
+
+    const phaseMatch = line.match(LEGACY_PHASE_HEADING_RE);
+    if (phaseMatch) {
+      results.push({
+        lineIndex: i,
+        headingLine: line,
+        milestoneInt: currentMilestoneInt,
+        legacyPhaseNum: phaseMatch[2],
+        phaseName: phaseMatch[3].trim(),
+        hashes: phaseMatch[1],
+        alreadyMigrated: false,
+      });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Assign sub-indices within each milestone, building a per-entry mapping.
+ *
+ * Input: array from parseRoadmapPhases (non-migrated entries only).
+ * Returns: Map<lineIndex, { newId, milestoneInt, subIndex }>
+ *
+ * Keyed by `lineIndex` (the unique position of the heading line in ROADMAP.md)
+ * so that identical legacy phase numbers in different milestones (e.g., two
+ * `Phase 1` headings in v1.0 and v2.0) each get their own correct M-NN ID
+ * instead of the later milestone's mapping overwriting the earlier one.
+ *
+ * Sub-indices are 1-based and sequential within each milestone.
+ */
+function assignSubIndices(phaseEntries) {
+  const milestoneCounters = new Map(); // milestoneInt → counter
+  const mapping = new Map(); // lineIndex → { newId, milestoneInt, subIndex }
+
+  for (const entry of phaseEntries) {
+    if (entry.alreadyMigrated) continue;
+    const m = entry.milestoneInt;
+    if (m === null || m === undefined) continue;
+
+    const counter = (milestoneCounters.get(m) || 0) + 1;
+    milestoneCounters.set(m, counter);
+
+    const subIndex = String(counter).padStart(2, '0');
+    const newId = `${m}-${subIndex}`;
+
+    mapping.set(entry.lineIndex, { newId, milestoneInt: m, subIndex: counter, legacyPhaseNum: entry.legacyPhaseNum });
+  }
+
+  return mapping;
+}
+
+/**
+ * Read a phase directory name and return its numeric token (stripping project_code prefix).
+ * e.g. "GSD-01-setup" → "01", "01-setup" → "01", "02-implement" → "02", "02.1-hotfix" → "02.1"
+ */
+function extractPhaseNumFromDir(dirName) {
+  // Strip optional project_code prefix: "GSD-01-setup" → "01-setup"
+  const stripped = dirName.replace(/^[A-Z]{1,6}-(?=\d)/i, '');
+  // Matches: digits + optional letter + optional decimal suffix, followed by '-' or end.
+  // e.g. "02.1-hotfix" → "02.1", "01-setup" → "01"
+  const m = stripped.match(/^(\d+[A-Z]?(?:\.\d+)*)(?:-|$)/i);
+  return m ? m[1] : null;
+}
+
+
+/**
+ * Build the new directory name from old name and new phase ID.
+ * old: "01-setup"         newId: "1-02"  projectCode: "GSD"  → "GSD-01-02-setup"
+ * old: "01-setup"         newId: "1-02"  projectCode: null   → "01-02-setup"
+ * old: "GSD-01-setup"     newId: "1-02"  projectCode: "GSD"  → "GSD-01-02-setup"
+ */
+function buildNewDirName(oldDirName, newId, projectCode) {
+  // Strip existing project_code prefix
+  const stripped = oldDirName.replace(/^[A-Z]{1,6}-(?=\d)/i, '');
+
+  // Extract slug: everything after "NN-" (the old phase num, including decimal like 02.1)
+  const slugMatch = stripped.match(/^\d+[A-Z]?(?:\.\d+)*-(.*)/i);
+  const slug = slugMatch ? slugMatch[1] : stripped;
+
+  // Build M-NN prefix (zero-pad both parts)
+  const [milestoneStr, subStr] = newId.split('-');
+  const milestoneInt = parseInt(milestoneStr, 10);
+  const subIndex = subStr;
+  const paddedMilestone = String(milestoneInt).padStart(2, '0');
+  const newBase = slug ? `${paddedMilestone}-${subIndex}-${slug}` : `${paddedMilestone}-${subIndex}`;
+
+  return projectCode ? `${projectCode}-${newBase}` : newBase;
+}
+
+/**
+ * Read project_code from config.json if present.
+ */
+function readProjectCode(configPath) {
+  try {
+    const raw = fs.readFileSync(configPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed.project_code || null;
+  } catch {
+    return null;
+  }
+}
+
+// ─── computeMigrationPlan ─────────────────────────────────────────────────────
+
+/**
+ * Compute a migration plan without touching the filesystem.
+ *
+ * @param {string} cwd
+ * @param {object} [options]
+ * @returns {{
+ *   alreadyMigrated: boolean,
+ *   phases: Array<{oldId, newId, oldDir, newDir}>,
+ *   roadmapEdits: Array<{lineIndex, from, to}>,
+ *   crossRefEdits: Array<{file, from, to}>,
+ * }}
+ */
+function computeMigrationPlan(cwd, options = {}) {
+  const pDir = planningDir(cwd);
+  const roadmapPath = path.join(pDir, 'ROADMAP.md');
+  const configPath = path.join(pDir, 'config.json');
+  const phasesDir = path.join(pDir, 'phases');
+
+  // ── Check config for existing convention ─────────────────────────────────
+  let configData = {};
+  try {
+    configData = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  } catch { /* config may not exist */ }
+
+  if (configData.phase_id_convention === 'milestone-prefixed') {
+    return { alreadyMigrated: true, phases: [], roadmapEdits: [], crossRefEdits: [] };
+  }
+
+  const projectCode = configData.project_code || null;
+
+  // ── Read ROADMAP.md ───────────────────────────────────────────────────────
+  let roadmapContent = '';
+  try {
+    roadmapContent = fs.readFileSync(roadmapPath, 'utf8');
+  } catch {
+    throw new Error(`ROADMAP.md not found at ${roadmapPath}`);
+  }
+
+  const lines = roadmapContent.split('\n');
+  const parsedPhases = parseRoadmapPhases(lines);
+
+  // Check for any already-migrated headings
+  const hasAnyMigrated = parsedPhases.some(e => e.alreadyMigrated);
+  if (hasAnyMigrated) {
+    return { alreadyMigrated: true, phases: [], roadmapEdits: [], crossRefEdits: [] };
+  }
+
+  const legacyPhases = parsedPhases.filter(e => !e.alreadyMigrated);
+  const idMapping = assignSubIndices(legacyPhases);
+
+  // Secondary lookup: (milestoneInt, normalizedLegacyNum) → newId
+  // Used for directory renames and checklist rewrites where line position is unknown.
+  // For simplicity, each milestone gets its own Map from legacy num → newId.
+  const milestoneIdMap = new Map(); // milestoneInt → Map<normalizedLegacyNum, newId>
+  for (const [, entry] of idMapping) {
+    if (!milestoneIdMap.has(entry.milestoneInt)) {
+      milestoneIdMap.set(entry.milestoneInt, new Map());
+    }
+    const mMap = milestoneIdMap.get(entry.milestoneInt);
+    const legacyNum = entry.legacyPhaseNum;
+    // Register integer forms (covers plain numeric and letter-suffix IDs)
+    const intPart = parseInt(legacyNum, 10);
+    const paddedLegacy = String(intPart).padStart(2, '0');
+    const unpaddedLegacy = String(intPart);
+    mMap.set(paddedLegacy, entry.newId);
+    mMap.set(unpaddedLegacy, entry.newId);
+    // Also register the original form and padded-integer+decimal form
+    // so decimal IDs like "2.1" / "02.1" round-trip correctly.
+    mMap.set(legacyNum, entry.newId);
+    const dotIdx = legacyNum.indexOf('.');
+    if (dotIdx !== -1) {
+      const decimalSuffix = legacyNum.slice(dotIdx); // e.g. ".1"
+      mMap.set(paddedLegacy + decimalSuffix, entry.newId);
+      mMap.set(unpaddedLegacy + decimalSuffix, entry.newId);
+    }
+  }
+
+  // ── Read existing phase directories ───────────────────────────────────────
+  let existingDirs = [];
+  try {
+    existingDirs = fs.readdirSync(phasesDir).filter(d => {
+      try {
+        return fs.statSync(path.join(phasesDir, d)).isDirectory();
+      } catch { return false; }
+    });
+  } catch { /* phases dir may not exist */ }
+
+  // ── Build phase rename pairs ───────────────────────────────────────────────
+  // Flat ordered list of (legacyPhaseNum, newId) in ROADMAP order, for dir matching.
+  const orderedMappings = [...idMapping.values()].map(e => ({
+    legacyPhaseNum: e.legacyPhaseNum,
+    newId: e.newId,
+    milestoneInt: e.milestoneInt,
+    _used: false,
+  }));
+
+  // Note: if the same legacy phase number appears in multiple milestones (the exact legacy
+  // ambiguity this tool is designed to resolve), directories are matched in ROADMAP document
+  // order — the first ROADMAP occurrence of a given number claims the first matching disk dir.
+  // This is the only unambiguous assignment strategy for flat dirs that carry no milestone
+  // context. The dry-run output shows the complete rename plan so users can review before
+  // applying with --apply.
+
+  const phases = [];
+  for (const dirName of existingDirs) {
+    const phaseNum = extractPhaseNumFromDir(dirName);
+    if (!phaseNum) continue;
+
+    const intPart = parseInt(phaseNum, 10);
+    const paddedPhaseNum = String(intPart).padStart(2, '0');
+    const unpaddedPhaseNum = String(intPart);
+    // For decimal IDs like "02.1", also try "2.1"
+    const dotIdx = phaseNum.indexOf('.');
+    const decimalUnpadded = dotIdx !== -1 ? unpaddedPhaseNum + phaseNum.slice(dotIdx) : null;
+
+    // Find the first unused mapping whose legacy number matches (exact, padded, unpadded, or decimal)
+    const found = orderedMappings.find(m => !m._used && (
+      m.legacyPhaseNum === phaseNum ||
+      m.legacyPhaseNum === paddedPhaseNum ||
+      m.legacyPhaseNum === unpaddedPhaseNum ||
+      (decimalUnpadded && m.legacyPhaseNum === decimalUnpadded)
+    ));
+    if (!found) continue;
+    found._used = true;
+
+    const newDirName = buildNewDirName(dirName, found.newId, projectCode);
+    if (newDirName !== dirName) {
+      phases.push({
+        oldId: phaseNum,
+        newId: found.newId,
+        oldDir: dirName,
+        newDir: newDirName,
+      });
+    }
+  }
+
+  // ── Build ROADMAP.md line edits ────────────────────────────────────────────
+  const roadmapEdits = [];
+
+  for (const entry of legacyPhases) {
+    // Use lineIndex as the canonical key (not legacyPhaseNum, which may collide across milestones)
+    const mapping = idMapping.get(entry.lineIndex);
+    if (!mapping) continue;
+
+    // Rewrite heading line: "### Phase N: Name" → "### Phase M-NN: Name"
+    const oldLine = lines[entry.lineIndex];
+    const newLine = oldLine.replace(
+      /^(#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+)\d+[A-Z]?(?:\.\d+)*(\s*:)/i,
+      `$1${mapping.newId}$2`
+    );
+    if (newLine !== oldLine) {
+      roadmapEdits.push({ lineIndex: entry.lineIndex, from: oldLine, to: newLine });
+    }
+  }
+
+  // Rewrite checklist lines in ROADMAP.md — use milestone context to resolve collisions.
+  let currentChecklistMilestone = null;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    // Track enclosing milestone section for context-aware lookup
+    const milestoneHeadingMatch = line.match(MILESTONE_HEADING_RE);
+    if (milestoneHeadingMatch) {
+      currentChecklistMilestone = parseInt(milestoneHeadingMatch[1], 10);
+    }
+
+    // Already in roadmapEdits? skip
+    if (roadmapEdits.some(e => e.lineIndex === i)) continue;
+
+    // Match checklist items: "- [ ] **Phase N:**" or "- [x] Phase N:"  (also decimal)
+    const checklistMatch = line.match(/^(\s*-\s*\[[ x]\]\s*\*{0,2}Phase\s+)(\d+[A-Z]?(?:\.\d+)*)(\s*[:\s*])/i);
+    if (checklistMatch) {
+      const legacyNum = checklistMatch[2];
+      const cIntPart = parseInt(legacyNum, 10);
+      const paddedLegacy = String(cIntPart).padStart(2, '0');
+      const unpaddedLegacy = String(cIntPart);
+      const cDotIdx = legacyNum.indexOf('.');
+      const paddedLegacyDecimal = cDotIdx !== -1 ? paddedLegacy + legacyNum.slice(cDotIdx) : null;
+
+      // Prefer milestone-context lookup (avoids collision across milestones)
+      let newId;
+      if (currentChecklistMilestone !== null && milestoneIdMap.has(currentChecklistMilestone)) {
+        const mMap = milestoneIdMap.get(currentChecklistMilestone);
+        newId = mMap.get(legacyNum) || mMap.get(paddedLegacy) || mMap.get(unpaddedLegacy);
+        if (!newId && paddedLegacyDecimal) newId = mMap.get(paddedLegacyDecimal);
+      }
+      if (!newId) {
+        // Fallback: use ordered flat list (no milestone collision in this roadmap)
+        const found = orderedMappings.find(m =>
+          m.legacyPhaseNum === legacyNum ||
+          m.legacyPhaseNum === paddedLegacy ||
+          m.legacyPhaseNum === unpaddedLegacy ||
+          (paddedLegacyDecimal && m.legacyPhaseNum === paddedLegacyDecimal)
+        );
+        if (found) newId = found.newId;
+      }
+
+      if (newId) {
+        const newLine = line.replace(
+          /^(\s*-\s*\[[ x]\]\s*\*{0,2}Phase\s+)\d+[A-Z]?(?:\.\d+)*(\s*[:\s*])/i,
+          `$1${newId}$2`
+        );
+        if (newLine !== line) {
+          roadmapEdits.push({ lineIndex: i, from: line, to: newLine });
+        }
+      }
+    }
+  }
+
+  // ── Build cross-ref edits for STATE.md and PROJECT.md ────────────────────
+  const crossRefEdits = [];
+  const crossRefFiles = ['STATE.md', 'PROJECT.md'];
+
+  for (const fileName of crossRefFiles) {
+    const filePath = path.join(pDir, fileName);
+    if (!fs.existsSync(filePath)) continue;
+
+    const fileContent = fs.readFileSync(filePath, 'utf8');
+
+    // Iterate using orderedMappings (ROADMAP order) — idMapping is now keyed by lineIndex.
+    for (const m of orderedMappings) {
+      const legacyNum = m.legacyPhaseNum;
+      const xIntPart = parseInt(legacyNum, 10);
+      const paddedNum = String(xIntPart).padStart(2, '0');
+      const unpaddedNum = String(xIntPart);
+      // Decimal suffix (e.g. ".1" from "2.1") — preserve in cross-ref patterns
+      const xDotIdx = legacyNum.indexOf('.');
+      const decimalSuffix = xDotIdx !== -1 ? legacyNum.slice(xDotIdx) : '';
+
+      // Rewrite project_code-prefixed references: "GSD-01-" → "GSD-01-02-"
+      if (projectCode) {
+        const [milestoneStr, subStr] = m.newId.split('-');
+        const paddedMilestone = String(parseInt(milestoneStr, 10)).padStart(2, '0');
+        const prefixedNew = `${projectCode}-${paddedMilestone}-${subStr}-`;
+        // Try both padded and original forms as old prefix
+        for (const oldNum of new Set([paddedNum + decimalSuffix, unpaddedNum + decimalSuffix, paddedNum, unpaddedNum])) {
+          const prefixedOld = `${projectCode}-${oldNum}-`;
+          if (fileContent.includes(prefixedOld)) {
+            crossRefEdits.push({ file: fileName, from: prefixedOld, to: prefixedNew });
+          }
+        }
+      }
+
+      // Rewrite prose references: "Phase 1:" → "Phase 1-01:", "Phase 2.1:" → "Phase 1-02:"
+      const proseOldPatterns = new Set([
+        `Phase ${unpaddedNum}${decimalSuffix}:`,
+        `Phase ${paddedNum}${decimalSuffix}:`,
+        `Phase ${legacyNum}:`,
+      ]);
+      for (const proseOld of proseOldPatterns) {
+        if (fileContent.includes(proseOld)) {
+          const proseNew = `Phase ${m.newId}:`;
+          crossRefEdits.push({ file: fileName, from: proseOld, to: proseNew });
+        }
+      }
+    }
+  }
+
+  return {
+    alreadyMigrated: false,
+    phases,
+    roadmapEdits,
+    crossRefEdits,
+  };
+}
+
+// ─── applyMigration ───────────────────────────────────────────────────────────
+
+/**
+ * Apply the migration plan computed by computeMigrationPlan().
+ *
+ * @param {string} cwd
+ * @param {{ alreadyMigrated, phases, roadmapEdits, crossRefEdits }} plan
+ * @param {object} [options]
+ * @param {boolean} [options.dryRun=true] - Print plan and exit without mutating.
+ * @returns {{
+ *   applied?: boolean,
+ *   alreadyMigrated?: boolean,
+ *   renamedDirs?: string[],
+ *   editedFiles?: string[],
+ * }}
+ */
+function applyMigration(cwd, plan, options = {}) {
+  const dryRun = options.dryRun !== false; // default true
+
+  if (plan.alreadyMigrated) {
+    return { alreadyMigrated: true };
+  }
+
+  if (dryRun) {
+    process.stdout.write(JSON.stringify(plan, null, 2) + '\n');
+    return { dryRun: true };
+  }
+
+  // ── Real run: verify clean working tree ───────────────────────────────────
+  let gitStatus;
+  try {
+    gitStatus = execSync('git status --porcelain', { cwd, encoding: 'utf8' });
+  } catch (err) {
+    throw new Error(`git status failed: ${err.message}`);
+  }
+  if (gitStatus.trim().length > 0) {
+    throw new Error('Working tree is dirty. Commit or stash changes before migrating.');
+  }
+
+  // Capture HEAD sha for rollback
+  let headSha;
+  try {
+    headSha = execSync('git rev-parse HEAD', { cwd, encoding: 'utf8' }).trim();
+  } catch (err) {
+    throw new Error(`git rev-parse HEAD failed: ${err.message}`);
+  }
+
+  const pDir = planningDir(cwd);
+  const phasesDir = path.join(pDir, 'phases');
+  const roadmapPath = path.join(pDir, 'ROADMAP.md');
+  const configPath = path.join(pDir, 'config.json');
+
+  const renamedDirs = [];
+  const editedFiles = [];
+
+  try {
+    // 1. Rename phase directories
+    for (const phaseEntry of plan.phases) {
+      const oldPath = path.join(phasesDir, phaseEntry.oldDir);
+      const newPath = path.join(phasesDir, phaseEntry.newDir);
+      if (fs.existsSync(oldPath)) {
+        fs.renameSync(oldPath, newPath);
+        renamedDirs.push(`${phaseEntry.oldDir} → ${phaseEntry.newDir}`);
+      }
+    }
+
+    // 2. Rewrite ROADMAP.md phase headings
+    if (plan.roadmapEdits.length > 0) {
+      const roadmapContent = fs.readFileSync(roadmapPath, 'utf8');
+      const lines = roadmapContent.split('\n');
+
+      // Sort edits by lineIndex to apply in order
+      const sortedEdits = [...plan.roadmapEdits].sort((a, b) => a.lineIndex - b.lineIndex);
+      for (const edit of sortedEdits) {
+        if (lines[edit.lineIndex] === edit.from) {
+          lines[edit.lineIndex] = edit.to;
+        }
+      }
+
+      fs.writeFileSync(roadmapPath, lines.join('\n'), 'utf8');
+      editedFiles.push('ROADMAP.md');
+    }
+
+    // 3. Rewrite cross-refs in STATE.md and PROJECT.md
+    const crossRefsByFile = new Map();
+    for (const edit of plan.crossRefEdits) {
+      if (!crossRefsByFile.has(edit.file)) {
+        crossRefsByFile.set(edit.file, []);
+      }
+      crossRefsByFile.get(edit.file).push(edit);
+    }
+
+    for (const [fileName, edits] of crossRefsByFile) {
+      const filePath = path.join(pDir, fileName);
+      if (!fs.existsSync(filePath)) continue;
+
+      let content = fs.readFileSync(filePath, 'utf8');
+      let changed = false;
+
+      for (const edit of edits) {
+        if (content.includes(edit.from)) {
+          // Replace all occurrences
+          content = content.split(edit.from).join(edit.to);
+          changed = true;
+        }
+      }
+
+      if (changed) {
+        fs.writeFileSync(filePath, content, 'utf8');
+        editedFiles.push(fileName);
+      }
+    }
+
+    // 4. Update config.json: set phase_id_convention to 'milestone-prefixed'
+    let configData = {};
+    try {
+      configData = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    } catch { /* config may not exist yet */ }
+
+    configData.phase_id_convention = 'milestone-prefixed';
+    fs.writeFileSync(configPath, JSON.stringify(configData, null, 2) + '\n', 'utf8');
+    editedFiles.push('config.json');
+
+  } catch (err) {
+    // Rollback via git reset --hard + git clean
+    try {
+      execSync(`git reset --hard ${headSha}`, { cwd, stdio: 'pipe' });
+      execSync('git clean -fd .planning/phases/', { cwd, stdio: 'pipe' });
+    } catch (rollbackErr) {
+      // Swallow rollback errors — surface original error
+    }
+    throw new Error(`Migration failed (rolled back to ${headSha}): ${err.message}`);
+  }
+
+  return { applied: true, renamedDirs, editedFiles };
+}
+
+// ─── Exports ──────────────────────────────────────────────────────────────────
+
+module.exports = {
+  computeMigrationPlan,
+  applyMigration,
+};

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

@@ -63,7 +63,7 @@ function countPhasePlansAndSummaries(phaseDir) {
 function searchPhaseInContent(content, escapedPhase, phaseNum) {
   // Match "## Phase X:", "### Phase X:", or "#### Phase X:" with optional name
   const phasePattern = new RegExp(
-    `#{2,4}\\s*Phase\\s+${escapedPhase}:\\s*([^\\n]+)`,
+    `#{2,4}\\s*(?:\\[[^\\]]+\\]\\s*)?Phase\\s+${escapedPhase}:\\s*([^\\n]+)`,
     'i'
   );
   const headerMatch = content.match(phasePattern);
@@ -92,9 +92,10 @@ function searchPhaseInContent(content, escapedPhase, phaseNum) {
   const phaseName = headerMatch[1].trim();
   const headerIndex = headerMatch.index;
 
-  // Find the end of this section (next ## or ### phase header, or end of file)
+  // Find the end of this section (next ## or ### phase header, or end of file).
+  // Also matches bracket-prefixed headings like ### [GSD] Phase 2-01:.
   const restOfContent = content.slice(headerIndex);
-  const nextHeaderMatch = restOfContent.match(/\n#{2,4}\s+Phase\s+[\w][\w.-]*/i);
+  const nextHeaderMatch = restOfContent.match(/\n#{2,4}\s+(?:\[[^\]]+\]\s*)?Phase\s+[\w][\w.-]*/i);
   const sectionEnd = nextHeaderMatch
     ? headerIndex + nextHeaderMatch.index
     : content.length;
@@ -203,7 +204,7 @@ function cmdRoadmapAnalyze(cwd, raw) {
   const phasesDir = planningPaths(cwd).phases;
 
   // 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;
+  const phasePattern = /#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+(\d+[A-Z]?(?:[.-]\d+)*)\s*:\s*([^\n]+)/gi;
   const phases = [];
   let match;
 
@@ -225,7 +226,7 @@ function cmdRoadmapAnalyze(cwd, raw) {
     const restOfContent = content.slice(sectionStart);
     // #3691: `\d` → `\d[\d.]*` so decimal phase headings (e.g. `### Phase 02.3:`) are
     // recognised as section boundaries.
-    const nextHeader = restOfContent.match(/\n#{2,4}\s+Phase\s+\d[\d.]*/i);
+    const nextHeader = restOfContent.match(/\n#{2,4}\s+(?:\[[^\]]+\]\s*)?Phase\s+\d[\d.-]*/i);
     const sectionEnd = nextHeader ? sectionStart + nextHeader.index : content.length;
     const section = content.slice(sectionStart, sectionEnd);
 

package/get-shit-done/bin/lib/semver-compare.cjs

@@ -1,35 +1,42 @@
-'use strict';
-
+"use strict";
+/**
+ * Shared semver comparison utility (ADR-457 pilot: first hand-written
+ * bin/lib/*.cjs collapsed to a TypeScript source of truth).
+ *
+ * Logic is preserved byte-for-behaviour from the prior hand-written
+ * `get-shit-done/bin/lib/semver-compare.cjs`; only types are added. The
+ * normalization policy here is locked by `tests/semver-compare.test.cjs` and
+ * consumed by update-check, statusline dev-install detection, and changeset
+ * range compare (`scripts/changeset/cli.cjs`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toNumericTuple = toNumericTuple;
+exports.compareSemverCore = compareSemverCore;
+exports.isSemverNewer = isSemverNewer;
+exports.isStableTripletSemver = isStableTripletSemver;
 function toNumericTuple(input) {
-  const cleaned = String(input == null ? '' : input).trim().replace(/^v/, '');
-  const base = cleaned.replace(/[-+].*$/, '');
-  const parts = base.split('.');
-  const major = Number.parseInt(parts[0], 10) || 0;
-  const minor = Number.parseInt(parts[1], 10) || 0;
-  const patch = Number.parseInt(parts[2], 10) || 0;
-  return [major, minor, patch];
+    const cleaned = String(input == null ? '' : input).trim().replace(/^v/, '');
+    const base = cleaned.replace(/[-+].*$/, '');
+    const parts = base.split('.');
+    const major = Number.parseInt(parts[0], 10) || 0;
+    const minor = Number.parseInt(parts[1], 10) || 0;
+    const patch = Number.parseInt(parts[2], 10) || 0;
+    return [major, minor, patch];
 }
-
 function compareSemverCore(a, b) {
-  const [a0, a1, a2] = toNumericTuple(a);
-  const [b0, b1, b2] = toNumericTuple(b);
-  if (a0 !== b0) return a0 > b0 ? 1 : -1;
-  if (a1 !== b1) return a1 > b1 ? 1 : -1;
-  if (a2 !== b2) return a2 > b2 ? 1 : -1;
-  return 0;
+    const [a0, a1, a2] = toNumericTuple(a);
+    const [b0, b1, b2] = toNumericTuple(b);
+    if (a0 !== b0)
+        return a0 > b0 ? 1 : -1;
+    if (a1 !== b1)
+        return a1 > b1 ? 1 : -1;
+    if (a2 !== b2)
+        return a2 > b2 ? 1 : -1;
+    return 0;
 }
-
 function isSemverNewer(a, b) {
-  return compareSemverCore(a, b) > 0;
+    return compareSemverCore(a, b) > 0;
 }
-
 function isStableTripletSemver(v) {
-  return /^\d+\.\d+\.\d+$/.test(String(v || '').replace(/^v/, ''));
+    return /^\d+\.\d+\.\d+$/.test(String(v || '').replace(/^v/, ''));
 }
-
-module.exports = {
-  compareSemverCore,
-  isSemverNewer,
-  isStableTripletSemver,
-  toNumericTuple,
-};