@sienklogic/plan-build-run 2.34.0 → 2.38.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/migrate.js

@@ -0,0 +1,169 @@
+/**
+ * lib/migrate.js — Schema migration for Plan-Build-Run config.json.
+ *
+ * Tracks config.json schema version and applies sequential migrations
+ * to bring outdated configs up to the current version.
+ *
+ * Usage:
+ *   const { applyMigrations, CURRENT_SCHEMA_VERSION } = require('./migrate');
+ *   const result = await applyMigrations(planningDir, { dryRun: false });
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { atomicWrite } = require('./core');
+
+/** The current schema version supported by this version of PBR. */
+const CURRENT_SCHEMA_VERSION = 1;
+
+/**
+ * Migration registry. Each entry describes one schema version step.
+ * Migrations MUST be listed in ascending `from` order.
+ *
+ * @type {Array<{ from: number, to: number, description: string, migrate: function }>}
+ */
+const MIGRATIONS = [
+  {
+    from: 0,
+    to: 1,
+    description: 'Add schema_version field',
+    migrate(config) {
+      config.schema_version = 1;
+    }
+  }
+];
+
+/**
+ * Detect the current schema version from a config object.
+ * Returns 0 if schema_version is absent or non-numeric.
+ *
+ * @param {object} config - Parsed config.json object
+ * @returns {number} Detected schema version
+ */
+function detectSchemaVersion(config) {
+  const v = config && config.schema_version;
+  if (typeof v === 'number' && Number.isFinite(v)) return v;
+  return 0;
+}
+
+/**
+ * Return the ordered list of migrations needed to go from `fromVersion` to `toVersion`.
+ * Returns an empty array if versions are equal.
+ * Throws if fromVersion > toVersion (downgrade not supported).
+ *
+ * @param {number} fromVersion - Current schema version
+ * @param {number} toVersion - Target schema version
+ * @returns {Array} Ordered migrations to apply
+ */
+function getMigrationPath(fromVersion, toVersion) {
+  if (fromVersion > toVersion) {
+    throw new Error(`Cannot downgrade schema from version ${fromVersion} to ${toVersion}`);
+  }
+  if (fromVersion === toVersion) return [];
+  return MIGRATIONS.filter(m => m.from >= fromVersion && m.to <= toVersion);
+}
+
+/**
+ * Apply pending migrations to config.json in planningDir.
+ *
+ * Options:
+ *   dryRun {boolean} — If true, simulate migration without writing files (default: false)
+ *   force  {boolean} — Reserved for future use (default: false)
+ *
+ * Returns:
+ *   { migrated: false, version: N }                          — already current
+ *   { migrated: false, message: string }                     — future version, no-op
+ *   { migrated: true, fromVersion, toVersion, applied, backupPath } — success
+ *   { error: string }                                        — failure
+ *
+ * @param {string} planningDir - Path to .planning directory
+ * @param {object} [options] - Options { dryRun, force }
+ * @returns {Promise<object>} Result object
+ */
+async function applyMigrations(planningDir, options) {
+  const opts = options || {};
+  const dryRun = opts.dryRun === true;
+
+  const configPath = path.join(planningDir, 'config.json');
+
+  // Load config.json
+  if (!fs.existsSync(configPath)) {
+    return { error: 'config.json not found in ' + planningDir };
+  }
+
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  } catch (e) {
+    return { error: 'config.json is not valid JSON: ' + e.message };
+  }
+
+  const currentVersion = detectSchemaVersion(config);
+
+  // Future version — don't touch it
+  if (currentVersion > CURRENT_SCHEMA_VERSION) {
+    return {
+      migrated: false,
+      version: currentVersion,
+      message: `config.json schema_version (${currentVersion}) is newer than this PBR version supports (${CURRENT_SCHEMA_VERSION}). No migration applied.`
+    };
+  }
+
+  // Already current
+  if (currentVersion === CURRENT_SCHEMA_VERSION) {
+    return { migrated: false, version: currentVersion };
+  }
+
+  // Determine migrations to apply
+  const migrations = getMigrationPath(currentVersion, CURRENT_SCHEMA_VERSION);
+  if (migrations.length === 0) {
+    return { migrated: false, version: currentVersion };
+  }
+
+  // Clone config for mutation
+  const updatedConfig = JSON.parse(JSON.stringify(config));
+
+  // Apply each migration in sequence
+  const applied = [];
+  for (const m of migrations) {
+    m.migrate(updatedConfig);
+    applied.push(m.description);
+  }
+
+  if (dryRun) {
+    return {
+      migrated: true,
+      fromVersion: currentVersion,
+      toVersion: CURRENT_SCHEMA_VERSION,
+      applied,
+      dryRun: true
+    };
+  }
+
+  // Create backup
+  const backupDir = path.join(planningDir, '.migration-backup');
+  const backupPath = path.join(backupDir, 'config.json.bak');
+  if (!fs.existsSync(backupDir)) {
+    fs.mkdirSync(backupDir, { recursive: true });
+  }
+  fs.copyFileSync(configPath, backupPath);
+
+  // Write updated config atomically
+  atomicWrite(configPath, JSON.stringify(updatedConfig, null, 2));
+
+  return {
+    migrated: true,
+    fromVersion: currentVersion,
+    toVersion: CURRENT_SCHEMA_VERSION,
+    applied,
+    backupPath
+  };
+}
+
+module.exports = {
+  CURRENT_SCHEMA_VERSION,
+  MIGRATIONS,
+  detectSchemaVersion,
+  getMigrationPath,
+  applyMigrations
+};

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
+};