@sienklogic/plan-build-run 2.33.1 → 2.37.0

package/plugins/pbr/scripts/lib/init.js

@@ -0,0 +1,166 @@
+/**
+ * lib/init.js — Compound init commands for Plan-Build-Run tools.
+ *
+ * These aggregate state from multiple sources into single JSON payloads
+ * for skill initialization. Each init function returns everything a skill
+ * needs to start work without additional file reads.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { stateLoad, stateCheckProgress } = require('./state');
+const { configLoad, resolveDepthProfile } = require('./config');
+const { phaseInfo, planIndex } = require('./phase');
+
+/**
+ * Initialize context for executing a phase (building plans).
+ *
+ * @param {string} phaseNum - Phase number
+ * @param {string} [planningDir] - Path to .planning directory
+ */
+function initExecutePhase(phaseNum, planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const state = stateLoad(dir);
+  if (!state.exists) return { error: "No .planning/ directory found" };
+  const phase = phaseInfo(phaseNum, dir);
+  if (phase.error) return { error: phase.error };
+  const plans = planIndex(phaseNum, dir);
+  const config = configLoad(dir) || {};
+  const depthProfile = resolveDepthProfile(config);
+  const models = config.models || {};
+  let gitState = { branch: null, clean: null };
+  try {
+    const { execSync } = require("child_process");
+    const branch = execSync("git rev-parse --abbrev-ref HEAD", { encoding: "utf8", timeout: 5000 }).trim();
+    const status = execSync("git status --porcelain", { encoding: "utf8", timeout: 5000 }).trim();
+    gitState = { branch, clean: status === "" };
+  } catch (_e) { /* not a git repo */ }
+  return {
+    executor_model: models.executor || "sonnet",
+    verifier_model: models.verifier || "sonnet",
+    config: { depth: depthProfile.depth, mode: config.mode || "interactive", parallelization: config.parallelization || { enabled: false }, planning: config.planning || {}, gates: config.gates || {}, features: config.features || {} },
+    phase: { num: phaseNum, dir: phase.phase, name: phase.name, goal: phase.goal, has_context: phase.has_context, status: phase.filesystem_status, plan_count: phase.plan_count, completed: phase.completed },
+    plans: (plans.plans || []).map(p => ({ file: p.file, plan_id: p.plan_id, wave: p.wave, autonomous: p.autonomous, has_summary: p.has_summary, must_haves_count: p.must_haves_count, depends_on: p.depends_on })),
+    waves: plans.waves || {},
+    branch_name: gitState.branch, git_clean: gitState.clean
+  };
+}
+
+/**
+ * Initialize context for planning a phase.
+ *
+ * @param {string} phaseNum - Phase number
+ * @param {string} [planningDir] - Path to .planning directory
+ */
+function initPlanPhase(phaseNum, planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const state = stateLoad(dir);
+  if (!state.exists) return { error: "No .planning/ directory found" };
+  const config = configLoad(dir) || {};
+  const models = config.models || {};
+  const depthProfile = resolveDepthProfile(config);
+  const phasesDir = path.join(dir, "phases");
+  const paddedPhase = String(phaseNum).padStart(2, "0");
+  let existingArtifacts = [], phaseDirName = null;
+  if (fs.existsSync(phasesDir)) {
+    const dirs = fs.readdirSync(phasesDir).filter(d => d.startsWith(paddedPhase + "-"));
+    if (dirs.length > 0) { phaseDirName = dirs[0]; existingArtifacts = fs.readdirSync(path.join(phasesDir, phaseDirName)).filter(f => f.endsWith(".md")); }
+  }
+  let phaseGoal = null, phaseDeps = null;
+  if (state.roadmap && state.roadmap.phases) {
+    const rp = state.roadmap.phases.find(p => p.number === paddedPhase);
+    if (rp) { phaseGoal = rp.goal; phaseDeps = rp.depends_on; }
+  }
+  return {
+    researcher_model: models.researcher || "sonnet", planner_model: models.planner || "sonnet", checker_model: models.planner || "sonnet",
+    config: { depth: depthProfile.depth, profile: depthProfile.profile, features: config.features || {}, planning: config.planning || {} },
+    phase: { num: phaseNum, dir: phaseDirName, goal: phaseGoal, depends_on: phaseDeps },
+    existing_artifacts: existingArtifacts,
+    workflow: { research_phase: (config.features || {}).research_phase !== false, plan_checking: (config.features || {}).plan_checking !== false }
+  };
+}
+
+/**
+ * Initialize context for a quick task.
+ *
+ * @param {string} description - Task description
+ * @param {string} [planningDir] - Path to .planning directory
+ */
+function initQuick(description, planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const config = configLoad(dir) || {};
+  const quickDir = path.join(dir, "quick");
+  let nextNum = 1;
+  if (fs.existsSync(quickDir)) {
+    const dirs = fs.readdirSync(quickDir).filter(d => /^\d{3}-/.test(d)).sort();
+    if (dirs.length > 0) { nextNum = parseInt(dirs[dirs.length - 1].substring(0, 3), 10) + 1; }
+  }
+  const slug = (description || "task").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").substring(0, 30);
+  const paddedNum = String(nextNum).padStart(3, "0");
+  return {
+    next_task_number: paddedNum, slug, dir: path.join(".planning", "quick", paddedNum + "-" + slug),
+    dir_name: paddedNum + "-" + slug, timestamp: new Date().toISOString(),
+    config: { depth: config.depth || "standard", mode: config.mode || "interactive", models: config.models || {}, planning: config.planning || {} }
+  };
+}
+
+/**
+ * Initialize context for verifying phase work.
+ *
+ * @param {string} phaseNum - Phase number
+ * @param {string} [planningDir] - Path to .planning directory
+ */
+function initVerifyWork(phaseNum, planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const phase = phaseInfo(phaseNum, dir);
+  if (phase.error) return { error: phase.error };
+  const config = configLoad(dir) || {};
+  const models = config.models || {};
+  let priorAttempts = 0;
+  if (phase.verification) { priorAttempts = parseInt(phase.verification.attempt, 10) || 0; }
+  return {
+    verifier_model: models.verifier || "sonnet",
+    phase: { num: phaseNum, dir: phase.phase, name: phase.name, goal: phase.goal, plan_count: phase.plan_count, completed: phase.completed },
+    has_verification: !!phase.verification, prior_attempts: priorAttempts,
+    prior_status: phase.verification ? (phase.verification.status || "unknown") : null,
+    summaries: phase.summaries || []
+  };
+}
+
+/**
+ * Initialize context for resuming work.
+ *
+ * @param {string} [planningDir] - Path to .planning directory
+ */
+function initResume(planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const state = stateLoad(dir);
+  if (!state.exists) return { error: "No .planning/ directory found" };
+  let autoNext = null, continueHere = null, activeSkill = null;
+  try { autoNext = fs.readFileSync(path.join(dir, ".auto-next"), "utf8").trim(); } catch (_e) { /* file not found */ }
+  try { continueHere = fs.readFileSync(path.join(dir, ".continue-here"), "utf8").trim(); } catch (_e) { /* file not found */ }
+  try { activeSkill = fs.readFileSync(path.join(dir, ".active-skill"), "utf8").trim(); } catch (_e) { /* file not found */ }
+  return { state: state.state, auto_next: autoNext, continue_here: continueHere, active_skill: activeSkill, current_phase: state.current_phase, progress: state.progress };
+}
+
+/**
+ * Initialize context for progress display.
+ *
+ * @param {string} [planningDir] - Path to .planning directory
+ */
+function initProgress(planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const state = stateLoad(dir);
+  if (!state.exists) return { error: "No .planning/ directory found" };
+  const progress = stateCheckProgress(dir);
+  return { current_phase: state.current_phase, total_phases: state.phase_count, status: state.state ? state.state.status : null, phases: progress.phases, total_plans: progress.total_plans, completed_plans: progress.completed_plans, percentage: progress.percentage };
+}
+
+module.exports = {
+  initExecutePhase,
+  initPlanPhase,
+  initQuick,
+  initVerifyWork,
+  initResume,
+  initProgress
+};

package/plugins/pbr/scripts/lib/phase.js

@@ -0,0 +1,364 @@
+/**
+ * lib/phase.js — Phase operations for Plan-Build-Run tools.
+ *
+ * Handles phase directory management (add/remove/list), plan indexing,
+ * must-haves collection, and comprehensive phase info.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const {
+  parseYamlFrontmatter,
+  findFiles,
+  countMustHaves,
+  determinePhaseStatus
+} = require('./core');
+
+/**
+ * Parse a markdown file's YAML frontmatter and return as JSON.
+ * Wraps parseYamlFrontmatter().
+ *
+ * @param {string} filePath - Path to markdown file
+ * @returns {object} Parsed frontmatter or error
+ */
+function frontmatter(filePath) {
+  const resolved = path.resolve(filePath);
+  if (!fs.existsSync(resolved)) {
+    return { error: `File not found: ${resolved}` };
+  }
+  const content = fs.readFileSync(resolved, 'utf8');
+  return parseYamlFrontmatter(content);
+}
+
+/**
+ * Plan inventory for a phase, grouped by wave.
+ *
+ * @param {string} phaseNum - Phase number
+ * @param {string} [planningDir] - Path to .planning directory
+ * @returns {object} Plan index
+ */
+function planIndex(phaseNum, planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const phasesDir = path.join(dir, 'phases');
+  if (!fs.existsSync(phasesDir)) {
+    return { error: 'No phases directory found' };
+  }
+
+  // Find phase directory matching the number
+  const entries = fs.readdirSync(phasesDir, { withFileTypes: true })
+    .filter(e => e.isDirectory());
+
+  const phaseDir = entries.find(e => e.name.startsWith(phaseNum.padStart(2, '0') + '-'));
+  if (!phaseDir) {
+    return { error: `No phase directory found matching phase ${phaseNum}` };
+  }
+
+  const fullDir = path.join(phasesDir, phaseDir.name);
+  const planFiles = findFiles(fullDir, /-PLAN\.md$/);
+
+  const plans = [];
+  const waves = {};
+
+  for (const file of planFiles) {
+    const content = fs.readFileSync(path.join(fullDir, file), 'utf8');
+    const fm = parseYamlFrontmatter(content);
+
+    const plan = {
+      file,
+      plan_id: fm.plan || file.replace(/-PLAN\.md$/, ''),
+      wave: parseInt(fm.wave, 10) || 1,
+      type: fm.type || 'unknown',
+      autonomous: fm.autonomous !== false,
+      depends_on: fm.depends_on || [],
+      gap_closure: fm.gap_closure || false,
+      has_summary: fs.existsSync(path.join(fullDir, `SUMMARY-${fm.plan || ''}.md`)),
+      must_haves_count: countMustHaves(fm.must_haves)
+    };
+
+    plans.push(plan);
+
+    const waveKey = `wave_${plan.wave}`;
+    if (!waves[waveKey]) waves[waveKey] = [];
+    waves[waveKey].push(plan.plan_id);
+  }
+
+  return {
+    phase: phaseDir.name,
+    total_plans: plans.length,
+    plans,
+    waves
+  };
+}
+
+/**
+ * Collect all must-haves from all PLAN.md files in a phase.
+ * Returns per-plan grouping + flat deduplicated list + total count.
+ *
+ * @param {string} phaseNum - Phase number
+ * @param {string} [planningDir] - Path to .planning directory
+ */
+function mustHavesCollect(phaseNum, planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const phasesDir = path.join(dir, 'phases');
+  if (!fs.existsSync(phasesDir)) {
+    return { error: 'No phases directory found' };
+  }
+
+  const entries = fs.readdirSync(phasesDir, { withFileTypes: true })
+    .filter(e => e.isDirectory());
+  const phaseDir = entries.find(e => e.name.startsWith(phaseNum.padStart(2, '0') + '-'));
+  if (!phaseDir) {
+    return { error: `No phase directory found matching phase ${phaseNum}` };
+  }
+
+  const fullDir = path.join(phasesDir, phaseDir.name);
+  const planFiles = findFiles(fullDir, /-PLAN\.md$/);
+
+  const perPlan = {};
+  const allTruths = new Set();
+  const allArtifacts = new Set();
+  const allKeyLinks = new Set();
+
+  for (const file of planFiles) {
+    const content = fs.readFileSync(path.join(fullDir, file), 'utf8');
+    const fm = parseYamlFrontmatter(content);
+    const planId = fm.plan || file.replace(/-PLAN\.md$/, '');
+    const mh = fm.must_haves || { truths: [], artifacts: [], key_links: [] };
+
+    perPlan[planId] = mh;
+    (mh.truths || []).forEach(t => allTruths.add(t));
+    (mh.artifacts || []).forEach(a => allArtifacts.add(a));
+    (mh.key_links || []).forEach(k => allKeyLinks.add(k));
+  }
+
+  const all = {
+    truths: [...allTruths],
+    artifacts: [...allArtifacts],
+    key_links: [...allKeyLinks]
+  };
+
+  return {
+    phase: phaseDir.name,
+    plans: perPlan,
+    all,
+    total: all.truths.length + all.artifacts.length + all.key_links.length
+  };
+}
+
+/**
+ * Comprehensive single-phase status combining roadmap, filesystem, and plan data.
+ *
+ * @param {string} phaseNum - Phase number
+ * @param {string} [planningDir] - Path to .planning directory
+ */
+function phaseInfo(phaseNum, planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const { parseRoadmapMd } = require('./roadmap');
+  const phasesDir = path.join(dir, 'phases');
+  if (!fs.existsSync(phasesDir)) {
+    return { error: 'No phases directory found' };
+  }
+
+  const entries = fs.readdirSync(phasesDir, { withFileTypes: true })
+    .filter(e => e.isDirectory());
+  const phaseDir = entries.find(e => e.name.startsWith(phaseNum.padStart(2, '0') + '-'));
+  if (!phaseDir) {
+    return { error: `No phase directory found matching phase ${phaseNum}` };
+  }
+
+  const fullDir = path.join(phasesDir, phaseDir.name);
+
+  // Get roadmap info
+  let roadmapInfo = null;
+  const roadmapPath = path.join(dir, 'ROADMAP.md');
+  if (fs.existsSync(roadmapPath)) {
+    const roadmapContent = fs.readFileSync(roadmapPath, 'utf8');
+    const roadmap = parseRoadmapMd(roadmapContent);
+    roadmapInfo = roadmap.phases.find(p => p.number === phaseNum.padStart(2, '0')) || null;
+  }
+
+  // Get plan index
+  const plans = planIndex(phaseNum, dir);
+
+  // Check for verification
+  const verificationPath = path.join(fullDir, 'VERIFICATION.md');
+  let verification = null;
+  if (fs.existsSync(verificationPath)) {
+    const vContent = fs.readFileSync(verificationPath, 'utf8');
+    verification = parseYamlFrontmatter(vContent);
+  }
+
+  // Check summaries
+  const summaryFiles = findFiles(fullDir, /^SUMMARY-.*\.md$/);
+  const summaries = summaryFiles.map(f => {
+    const content = fs.readFileSync(path.join(fullDir, f), 'utf8');
+    const fm = parseYamlFrontmatter(content);
+    return { file: f, plan: fm.plan || f.replace(/^SUMMARY-|\.md$/g, ''), status: fm.status || 'unknown' };
+  });
+
+  // Determine filesystem status
+  const planCount = plans.total_plans || 0;
+  const completedCount = summaries.filter(s => s.status === 'complete').length;
+  const hasVerification = fs.existsSync(verificationPath);
+  const fsStatus = determinePhaseStatus(planCount, completedCount, summaryFiles.length, hasVerification, fullDir);
+
+  return {
+    phase: phaseDir.name,
+    name: roadmapInfo ? roadmapInfo.name : phaseDir.name.replace(/^\d+-/, ''),
+    goal: roadmapInfo ? roadmapInfo.goal : null,
+    roadmap_status: roadmapInfo ? roadmapInfo.status : null,
+    filesystem_status: fsStatus,
+    plans: plans.plans || [],
+    plan_count: planCount,
+    summaries,
+    completed: completedCount,
+    verification,
+    has_context: fs.existsSync(path.join(fullDir, 'CONTEXT.md'))
+  };
+}
+
+/**
+ * Add a new phase directory (with renumbering).
+ *
+ * @param {string} slug - Phase slug
+ * @param {string|null} afterPhase - Insert after this phase number
+ * @param {string} [planningDir] - Path to .planning directory
+ */
+function phaseAdd(slug, afterPhase, planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const phasesDir = path.join(dir, 'phases');
+  if (!fs.existsSync(phasesDir)) {
+    fs.mkdirSync(phasesDir, { recursive: true });
+  }
+
+  // Determine next phase number
+  const existing = fs.readdirSync(phasesDir)
+    .filter(d => /^\d+-/.test(d))
+    .map(d => parseInt(d.split('-')[0], 10))
+    .sort((a, b) => a - b);
+
+  let newNum;
+  if (afterPhase) {
+    const after = parseInt(afterPhase, 10);
+    // Find the next number after the specified phase
+    const higher = existing.filter(n => n > after);
+    if (higher.length > 0) {
+      // Need to renumber: insert between after and next
+      newNum = after + 1;
+      // Renumber all phases >= newNum
+      for (const dirName of fs.readdirSync(phasesDir).sort().reverse()) {
+        const num = parseInt(dirName.split('-')[0], 10);
+        if (num >= newNum) {
+          const newName = dirName.replace(/^\d+/, String(num + 1).padStart(2, '0'));
+          fs.renameSync(path.join(phasesDir, dirName), path.join(phasesDir, newName));
+        }
+      }
+    } else {
+      newNum = after + 1;
+    }
+  } else {
+    newNum = existing.length > 0 ? Math.max(...existing) + 1 : 1;
+  }
+
+  const dirName = `${String(newNum).padStart(2, '0')}-${slug}`;
+  const fullPath = path.join(phasesDir, dirName);
+  fs.mkdirSync(fullPath, { recursive: true });
+
+  return {
+    phase: newNum,
+    slug,
+    directory: dirName,
+    path: fullPath,
+    renumbered: afterPhase ? true : false
+  };
+}
+
+/**
+ * Remove an empty phase directory (with renumbering).
+ *
+ * @param {string} phaseNum - Phase number to remove
+ * @param {string} [planningDir] - Path to .planning directory
+ */
+function phaseRemove(phaseNum, planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const phasesDir = path.join(dir, 'phases');
+  const padded = String(phaseNum).padStart(2, '0');
+  const dirs = fs.readdirSync(phasesDir).filter(d => d.startsWith(padded + '-'));
+
+  if (dirs.length === 0) {
+    return { removed: false, error: `Phase ${phaseNum} not found` };
+  }
+
+  const dirName = dirs[0];
+  const fullPath = path.join(phasesDir, dirName);
+
+  // Check if phase has artifacts
+  const contents = fs.readdirSync(fullPath);
+  if (contents.length > 0) {
+    return {
+      removed: false,
+      error: `Phase ${phaseNum} (${dirName}) has ${contents.length} files. Remove contents first or use --force.`,
+      files: contents
+    };
+  }
+
+  fs.rmdirSync(fullPath);
+
+  // Renumber subsequent phases
+  const allDirs = fs.readdirSync(phasesDir)
+    .filter(d => /^\d+-/.test(d))
+    .sort();
+
+  for (const d of allDirs) {
+    const num = parseInt(d.split('-')[0], 10);
+    if (num > parseInt(phaseNum, 10)) {
+      const newName = d.replace(/^\d+/, String(num - 1).padStart(2, '0'));
+      fs.renameSync(path.join(phasesDir, d), path.join(phasesDir, newName));
+    }
+  }
+
+  return {
+    removed: true,
+    directory: dirName,
+    renumbered: true
+  };
+}
+
+/**
+ * List all phase directories with status.
+ *
+ * @param {string} [planningDir] - Path to .planning directory
+ */
+function phaseList(planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const phasesDir = path.join(dir, 'phases');
+  if (!fs.existsSync(phasesDir)) {
+    return { phases: [] };
+  }
+
+  const phases = fs.readdirSync(phasesDir)
+    .filter(d => /^\d+-/.test(d))
+    .sort()
+    .map(d => {
+      const num = parseInt(d.split('-')[0], 10);
+      const slug = d.replace(/^\d+-/, '');
+      const fullPath = path.join(phasesDir, d);
+      const files = fs.readdirSync(fullPath);
+      const hasPlan = files.some(f => /^PLAN/i.test(f));
+      const hasSummary = files.some(f => /^SUMMARY/i.test(f));
+      const hasVerification = files.some(f => /^VERIFICATION/i.test(f));
+      return { num, slug, directory: d, files: files.length, hasPlan, hasSummary, hasVerification };
+    });
+
+  return { phases };
+}
+
+module.exports = {
+  frontmatter,
+  planIndex,
+  mustHavesCollect,
+  phaseInfo,
+  phaseAdd,
+  phaseRemove,
+  phaseList
+};

package/plugins/pbr/scripts/lib/roadmap.js

@@ -0,0 +1,175 @@
+/**
+ * lib/roadmap.js — ROADMAP.md operations for Plan-Build-Run tools.
+ *
+ * Handles parsing and updating the ROADMAP.md phase overview table.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { lockedFileUpdate, validateStatusTransition } = require('./core');
+
+// --- Parsers ---
+
+function parseRoadmapMd(content) {
+  const result = { phases: [], has_progress_table: false };
+
+  // Find Phase Overview table
+  const overviewMatch = content.match(/## Phase Overview[\s\S]*?\|[\s\S]*?(?=\n##|\s*$)/);
+  if (overviewMatch) {
+    const rows = overviewMatch[0].split('\n').filter(r => r.includes('|'));
+    // Skip header and separator rows
+    for (let i = 2; i < rows.length; i++) {
+      const cols = rows[i].split('|').map(c => c.trim()).filter(Boolean);
+      if (cols.length >= 3) {
+        result.phases.push({
+          number: cols[0],
+          name: cols[1],
+          goal: cols[2],
+          plans: cols[3] || '',
+          wave: cols[4] || '',
+          status: cols[5] || 'pending'
+        });
+      }
+    }
+  }
+
+  // Check for Progress table
+  result.has_progress_table = /## Progress/.test(content);
+
+  return result;
+}
+
+// --- Table helpers ---
+
+/**
+ * Find the row index of a phase in a ROADMAP.md table.
+ * @returns {number} Line index or -1 if not found
+ */
+function findRoadmapRow(lines, phaseNum) {
+  const paddedPhase = phaseNum.padStart(2, '0');
+  for (let i = 0; i < lines.length; i++) {
+    if (!lines[i].includes('|')) continue;
+    const parts = lines[i].split('|');
+    if (parts.length < 3) continue;
+    const phaseCol = parts[1] ? parts[1].trim() : '';
+    if (phaseCol === paddedPhase) {
+      return i;
+    }
+  }
+  return -1;
+}
+
+/**
+ * Update a specific column in a markdown table row.
+ * @param {string} row - The full table row string (e.g., "| 01 | Setup | ... |")
+ * @param {number} columnIndex - 0-based column index (Phase=0, Name=1, ..., Status=5)
+ * @param {string} newValue - New cell value
+ * @returns {string} Updated row
+ */
+function updateTableRow(row, columnIndex, newValue) {
+  const parts = row.split('|');
+  // parts[0] is empty (before first |), data starts at parts[1]
+  const partIndex = columnIndex + 1;
+  if (partIndex < parts.length) {
+    parts[partIndex] = ` ${newValue} `;
+  }
+  return parts.join('|');
+}
+
+// --- Mutation commands ---
+
+/**
+ * Update the Status column for a phase in ROADMAP.md's Phase Overview table.
+ *
+ * @param {string} phaseNum - Phase number
+ * @param {string} newStatus - New status value
+ * @param {string} [planningDir] - Path to .planning directory
+ */
+function roadmapUpdateStatus(phaseNum, newStatus, planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const roadmapPath = path.join(dir, 'ROADMAP.md');
+  if (!fs.existsSync(roadmapPath)) {
+    return { success: false, error: 'ROADMAP.md not found' };
+  }
+
+  let oldStatus = null;
+
+  const result = lockedFileUpdate(roadmapPath, (content) => {
+    const lines = content.split('\n');
+    const rowIdx = findRoadmapRow(lines, phaseNum);
+    if (rowIdx === -1) {
+      return content; // No matching row found
+    }
+    const parts = lines[rowIdx].split('|');
+    oldStatus = parts[6] ? parts[6].trim() : 'unknown';
+    lines[rowIdx] = updateTableRow(lines[rowIdx], 5, newStatus);
+    return lines.join('\n');
+  });
+
+  if (!oldStatus) {
+    return { success: false, error: `Phase ${phaseNum} not found in ROADMAP.md table` };
+  }
+
+  // Advisory transition validation — warn on suspicious transitions but don't block
+  const transition = validateStatusTransition(oldStatus, newStatus);
+  if (!transition.valid && transition.warning) {
+    process.stderr.write(`[pbr-tools] WARNING: ${transition.warning}\n`);
+  }
+
+  if (result.success) {
+    const response = { success: true, old_status: oldStatus, new_status: newStatus };
+    if (!transition.valid) {
+      response.transition_warning = transition.warning;
+    }
+    return response;
+  }
+  return { success: false, error: result.error };
+}
+
+/**
+ * Update the Plans column for a phase in ROADMAP.md's Phase Overview table.
+ *
+ * @param {string} phaseNum - Phase number
+ * @param {string} complete - Completed plan count
+ * @param {string} total - Total plan count
+ * @param {string} [planningDir] - Path to .planning directory
+ */
+function roadmapUpdatePlans(phaseNum, complete, total, planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const roadmapPath = path.join(dir, 'ROADMAP.md');
+  if (!fs.existsSync(roadmapPath)) {
+    return { success: false, error: 'ROADMAP.md not found' };
+  }
+
+  let oldPlans = null;
+  const newPlans = `${complete}/${total}`;
+
+  const result = lockedFileUpdate(roadmapPath, (content) => {
+    const lines = content.split('\n');
+    const rowIdx = findRoadmapRow(lines, phaseNum);
+    if (rowIdx === -1) {
+      return content;
+    }
+    const parts = lines[rowIdx].split('|');
+    oldPlans = parts[4] ? parts[4].trim() : 'unknown';
+    lines[rowIdx] = updateTableRow(lines[rowIdx], 3, newPlans);
+    return lines.join('\n');
+  });
+
+  if (!oldPlans) {
+    return { success: false, error: `Phase ${phaseNum} not found in ROADMAP.md table` };
+  }
+
+  if (result.success) {
+    return { success: true, old_plans: oldPlans, new_plans: newPlans };
+  }
+  return { success: false, error: result.error };
+}
+
+module.exports = {
+  parseRoadmapMd,
+  findRoadmapRow,
+  updateTableRow,
+  roadmapUpdateStatus,
+  roadmapUpdatePlans
+};