pan-wizard 3.8.0 → 3.10.0

package/pan-wizard-core/bin/lib/cost.cjs

@@ -30,7 +30,7 @@
  *   - hit rate: cache_read / (cache_read + input - cache_write) if any cache activity
  *
  * Rate table is approximate — real pricing comes from the provider's API.
- * Rates are US dollars per million tokens, indicative as of 2026-04. Users
+ * Rates are US dollars per million tokens, indicative as of 2026-06. Users
  * can override with `.planning/config.json` → `cost.rates`.
  */
 
@@ -48,21 +48,32 @@ const TOKENS_FILE = 'tokens.jsonl';
  * Override per-model in config.json → cost.rates.
  */
 const DEFAULT_RATES = {
-  // Anthropic
-  'claude-opus-4-7':    { input: 15.0, output: 75.0, cache_read: 1.5,  cache_write: 18.75 },
-  'claude-opus-4-6':    { input: 15.0, output: 75.0, cache_read: 1.5,  cache_write: 18.75 },
+  // Anthropic — verified against platform pricing 2026-06. Opus 4.6+ is $5/$25
+  // (the old $15/$75 Opus pricing ended with the 4.5 generation). Cache rates
+  // follow Anthropic's convention: read ≈ 0.1× input, write ≈ 1.25× input.
+  'claude-fable-5':     { input: 10.0, output: 50.0, cache_read: 1.0,  cache_write: 12.5 },
+  'claude-opus-4-8':    { input: 5.0,  output: 25.0, cache_read: 0.5,  cache_write: 6.25 },
+  'claude-opus-4-7':    { input: 5.0,  output: 25.0, cache_read: 0.5,  cache_write: 6.25 },
+  'claude-opus-4-6':    { input: 5.0,  output: 25.0, cache_read: 0.5,  cache_write: 6.25 },
   'claude-sonnet-4-6':  { input: 3.0,  output: 15.0, cache_read: 0.3,  cache_write: 3.75 },
   'claude-haiku-4-5':   { input: 1.0,  output: 5.0,  cache_read: 0.1,  cache_write: 1.25 },
 
+  // OpenAI — verified against published pricing 2026-06 ($5/$30 standard tier).
+  // Prompt caching is a 90% input discount with no separate write charge, so
+  // cache_write bills at the plain input rate.
+  'gpt-5.5':            { input: 5.0,  output: 30.0, cache_read: 0.5,  cache_write: 5.0 },
+
   // Google Gemini — published rates (per million tokens, approximate; users can override via config.json → cost.rates).
-  // 2.5 tier uses the <=200K-context tier; long-context calls may be billed at ~2x. Cache rates are Google's context-cache pricing (~25% of input rate).
+  // Pro tiers use the <=200K-context tier; long-context calls may be billed at ~2x. Cache rates are Google's context-cache pricing (~25% of input rate).
+  // (gemini-1.5-pro removed 2026-06: retired model; records for it fall back to tier rates.)
+  'gemini-3.1-pro':         { input: 2.00, output: 12.0, cache_read: 0.50,   cache_write: 2.00 },
+  'gemini-3.1-pro-preview': { input: 2.00, output: 12.0, cache_read: 0.50,   cache_write: 2.00 },
   'gemini-2.5-pro':         { input: 1.25, output: 10.0, cache_read: 0.3125, cache_write: 1.25 },
   'gemini-2.5-flash':       { input: 0.30, output: 2.50, cache_read: 0.075,  cache_write: 0.30 },
   'gemini-2.5-flash-lite':  { input: 0.10, output: 0.40, cache_read: 0.025,  cache_write: 0.10 },
-  'gemini-1.5-pro':         { input: 1.25, output: 5.00, cache_read: 0.3125, cache_write: 1.25 },
 
-  // Tier fallbacks when model id is unknown
-  'reasoning': { input: 15.0, output: 75.0, cache_read: 1.5,  cache_write: 18.75 },
+  // Tier fallbacks when model id is unknown (reasoning tracks current Opus pricing)
+  'reasoning': { input: 5.0,  output: 25.0, cache_read: 0.5,  cache_write: 6.25 },
   'mid':       { input: 3.0,  output: 15.0, cache_read: 0.3,  cache_write: 3.75 },
   'fast':      { input: 1.0,  output: 5.0,  cache_read: 0.1,  cache_write: 1.25 },
 };
@@ -81,6 +92,15 @@ function resolveRate(model, tier, configRates) {
     if (tier && configRates[tier]) return configRates[tier];
   }
   if (model && DEFAULT_RATES[model]) return DEFAULT_RATES[model];
+  // Transcript/hook-captured ids are versioned ("claude-opus-4-8-20260301",
+  // "claude-fable-5[1m]") while the table uses family keys — prefix-match,
+  // longest key first so the most specific family wins.
+  if (model) {
+    const families = Object.keys(DEFAULT_RATES)
+      .filter(k => model.startsWith(k))
+      .sort((a, b) => b.length - a.length);
+    if (families.length > 0) return DEFAULT_RATES[families[0]];
+  }
   if (tier && DEFAULT_RATES[tier]) return DEFAULT_RATES[tier];
   return null;
 }
@@ -342,6 +362,37 @@ function cmdCostClear(cwd, raw) {
   }
 }
 
+// ─── Rate-table staleness ───────────────────────────────────────────────────
+
+// Date DEFAULT_RATES was last verified against published provider pricing.
+// Bump this whenever the table is re-verified; `models check` flags the table
+// once it is older than RATES_STALE_AFTER_DAYS (provider prices move faster
+// than PAN releases do).
+const RATES_VERIFIED_AT = '2026-06-10';
+const RATES_STALE_AFTER_DAYS = 180;
+const RATE_TIERS = ['reasoning', 'mid', 'fast'];
+
+function checkRatesStaleness(now = new Date()) {
+  const verified = new Date(RATES_VERIFIED_AT + 'T00:00:00Z');
+  const ageDays = Math.floor((now.getTime() - verified.getTime()) / 86400000);
+  return {
+    rates_verified_at: RATES_VERIFIED_AT,
+    age_days: ageDays,
+    stale_after_days: RATES_STALE_AFTER_DAYS,
+    stale: ageDays > RATES_STALE_AFTER_DAYS,
+    models: Object.keys(DEFAULT_RATES).filter(k => !RATE_TIERS.includes(k)),
+    tiers: RATE_TIERS,
+  };
+}
+
+function cmdModelsCheck(raw) {
+  const result = checkRatesStaleness();
+  const human = result.stale
+    ? `Rate table verified ${result.rates_verified_at} (${result.age_days} days ago) — STALE: re-verify provider pricing and bump RATES_VERIFIED_AT in cost.cjs`
+    : `Rate table verified ${result.rates_verified_at} (${result.age_days} days ago) — OK`;
+  output(result, raw, human);
+}
+
 module.exports = {
   computeCost,
   appendRecord,
@@ -350,10 +401,13 @@ module.exports = {
   renderTable,
   renderChart,
   resolveRate,
+  checkRatesStaleness,
   cmdCostReport,
   cmdCostAppend,
   cmdCostClear,
+  cmdModelsCheck,
   METRICS_DIR,
   TOKENS_FILE,
   DEFAULT_RATES,
+  RATES_VERIFIED_AT,
 };

package/pan-wizard-core/bin/lib/git.cjs

@@ -272,7 +272,12 @@ function cmdGitTag(cwd, sub, opts, raw) {
   }
   if (sub === 'create') {
     if (!name) { error('--name required for tag create'); }
-    const args = message ? ['tag', '-m', message, name] : ['tag', name];
+    // tag.gpgsign=true in user config would force signing (and fail outright
+    // for lightweight tags) in non-interactive runs — PAN tags are automation
+    // markers, so signing is explicitly disabled.
+    const args = message
+      ? ['-c', 'tag.gpgsign=false', 'tag', '-m', message, name]
+      : ['-c', 'tag.gpgsign=false', 'tag', name];
     const r = execGit(cwd, args);
     if (r.exitCode !== 0) {
       output({ created: false, tag: name, detail: r.stderr }, raw, 'tag create failed');

package/pan-wizard-core/bin/lib/lock.cjs

@@ -0,0 +1,108 @@
+/**
+ * Lock — advisory file locking + atomic writes for .planning/ concurrency
+ * (ADR-0030). Zero dependencies, synchronous (matches the CJS codebase),
+ * cross-platform: exclusive-create (`wx`) is atomic on NTFS and POSIX alike.
+ *
+ * v1 semantics are BEST-EFFORT serialization: when the lock cannot be
+ * acquired within the retry budget, callers fall back to the unlocked write
+ * (today's behavior) rather than failing — concurrent fleets get lost-update
+ * protection in the common case without introducing a new failure mode for
+ * single-agent users. Strict mode (fail on timeout) is the documented
+ * escalation path in ADR-0030.
+ */
+
+'use strict';
+
+const fs = require('fs');
+
+const DEFAULT_RETRIES = 40;
+const DEFAULT_INTERVAL_MS = 25;
+const DEFAULT_STALE_MS = 10_000;
+
+// Synchronous sleep without busy-waiting: Atomics.wait on a throwaway buffer.
+function sleepSync(ms) {
+  const sab = new SharedArrayBuffer(4);
+  Atomics.wait(new Int32Array(sab), 0, 0, ms);
+}
+
+/**
+ * Try to acquire <filePath>.lock. Stale locks (older than staleMs — a crashed
+ * holder) are stolen.
+ * @returns {{ acquired: boolean, lockPath: string }}
+ */
+function acquireLock(filePath, opts = {}) {
+  const retries = opts.retries ?? DEFAULT_RETRIES;
+  const intervalMs = opts.intervalMs ?? DEFAULT_INTERVAL_MS;
+  const staleMs = opts.staleMs ?? DEFAULT_STALE_MS;
+  const lockPath = filePath + '.lock';
+
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      fs.writeFileSync(lockPath, String(process.pid), { flag: 'wx' });
+      return { acquired: true, lockPath };
+    } catch (err) {
+      if (err.code !== 'EEXIST') {
+        // Lock dir unwritable etc. — treat as unacquirable, don't spin.
+        return { acquired: false, lockPath };
+      }
+      try {
+        const age = Date.now() - fs.statSync(lockPath).mtimeMs;
+        if (age > staleMs) {
+          // Holder likely crashed — steal and retry immediately.
+          try { fs.unlinkSync(lockPath); } catch { /* racing steal — loop retries */ }
+          continue;
+        }
+      } catch { /* lock vanished between EEXIST and stat — loop retries */ }
+      if (attempt < retries) sleepSync(intervalMs);
+    }
+  }
+  return { acquired: false, lockPath };
+}
+
+/** Release a lock acquired by acquireLock. Best-effort. */
+function releaseLock(lockPath) {
+  try { fs.unlinkSync(lockPath); } catch { /* already gone */ }
+}
+
+/**
+ * Run fn while holding <filePath>.lock.
+ * @param {string} filePath - The file the lock guards (lock is filePath + '.lock')
+ * @param {Function} fn - Critical section
+ * @param {object} [opts] - {retries, intervalMs, staleMs}
+ * @returns {{ locked: boolean, result: any }} locked=false means fn ran
+ *   WITHOUT the lock (best-effort fallback — see module header).
+ */
+function withFileLock(filePath, fn, opts = {}) {
+  const { acquired, lockPath } = acquireLock(filePath, opts);
+  try {
+    return { locked: acquired, result: fn() };
+  } finally {
+    if (acquired) releaseLock(lockPath);
+  }
+}
+
+/**
+ * Atomic file write: temp file in the same directory + rename. Readers never
+ * observe a torn/partial file. The temp name embeds pid to avoid collisions
+ * between concurrent writers.
+ */
+function writeFileAtomic(filePath, content) {
+  const tmpPath = `${filePath}.${process.pid}.tmp`;
+  fs.writeFileSync(tmpPath, content, 'utf-8');
+  try {
+    fs.renameSync(tmpPath, filePath);
+  } catch (err) {
+    // Windows can refuse rename-over-open-file; fall back to direct write so
+    // the content still lands, then clean the temp.
+    fs.writeFileSync(filePath, content, 'utf-8');
+    try { fs.unlinkSync(tmpPath); } catch { /* best-effort */ }
+  }
+}
+
+module.exports = {
+  acquireLock,
+  releaseLock,
+  withFileLock,
+  writeFileAtomic,
+  sleepSync,
+};

package/pan-wizard-core/bin/lib/milestone.cjs

@@ -260,9 +260,10 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     if (commitResult.exitCode === 0) {
       const hashResult = execGit(cwd, ['rev-parse', '--short', 'HEAD']);
       result.commit_hash = hashResult.exitCode === 0 ? hashResult.stdout : null;
-      // Create tag
+      // Create tag. Signing is explicitly disabled: tag.gpgsign=true in user
+      // config turns plain `git tag` into sign-or-fail in non-interactive runs.
       const tagName = `milestone-${version}`;
-      const tagResult = execGit(cwd, ['tag', tagName]);
+      const tagResult = execGit(cwd, ['-c', 'tag.gpgsign=false', 'tag', tagName]);
       result.tag = tagResult.exitCode === 0 ? tagName : null;
     }
   }

package/pan-wizard-core/bin/lib/phase-remove.cjs

@@ -0,0 +1,392 @@
+/**
+ * Phase / Remove — phase removal with renumbering cascade (directories, files,
+ * roadmap references, state counts).
+ * Extracted from phase.cjs (IMPROVEMENT-TODO P2 module decomposition);
+ * phase.cjs re-exports the public pieces, so consumers are unaffected.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { escapeRegex, normalizePhaseName, comparePhaseNum, output, error } = require('./core.cjs');
+const { writeStateMd, readStateSafe } = require('./state.cjs');
+const { ROADMAP_FILE, STATE_FILE, isSummaryFile } = require('./constants.cjs');
+const { planningPath, phasesPath, fileAccessible } = require('./utils.cjs');
+
+/**
+ * Delete a phase directory from disk.
+ * @param {string} phaseDir - Absolute path to the phase directory to remove
+ */
+function removePhaseFromDisk(phaseDir) {
+  try {
+    fs.rmSync(phaseDir, { recursive: true, force: true });
+  } catch (e) {
+    return { removed: false, error: e.message };
+  }
+  return { removed: true };
+}
+
+/**
+ * Renumber sibling decimal phases after one is removed.
+ *
+ * Algorithm: When a decimal phase like 06.2 is removed, all higher-numbered
+ * siblings under the same base integer (06.3, 06.4, ...) must be decremented
+ * by 1 to fill the gap. We process in descending order to avoid directory
+ * name collisions during rename (e.g. rename 06.4 -> 06.3 before 06.3 -> 06.2).
+ *
+ * @param {string} phasesDir - Absolute path to the phases directory
+ * @param {string} baseInt - The integer portion of the removed phase (e.g. "06")
+ * @param {number} removedDecimal - The decimal portion that was removed (e.g. 2)
+ * @returns {{ renamedDirs: Array, renamedFiles: Array }}
+ */
+function renumberDecimalPhases(phasesDir, baseInt, removedDecimal) {
+  const renamedDirs = [];
+  const renamedFiles = [];
+
+  try {
+    const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+    const dirs = entries.filter(entry => entry.isDirectory()).map(entry => entry.name).sort((left, right) => comparePhaseNum(left, right));
+
+    // Find sibling decimals with higher numbers than the removed one
+    const decPattern = new RegExp(`^${baseInt}\\.(\\d+)-(.+)$`);
+    const toRename = [];
+    for (const dir of dirs) {
+      const decMatch = dir.match(decPattern);
+      if (decMatch && parseInt(decMatch[1], 10) > removedDecimal) {
+        toRename.push({ dir, oldDecimal: parseInt(decMatch[1], 10), slug: decMatch[2] });
+      }
+    }
+
+    // Sort descending so higher-numbered dirs are renamed first,
+    // preventing collisions (e.g. 06.4 -> 06.3 before 06.3 -> 06.2)
+    toRename.sort((left, right) => right.oldDecimal - left.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 the directory itself (e.g. 06.3-foo -> 06.2-foo)
+      fs.renameSync(path.join(phasesDir, item.dir), path.join(phasesDir, newDirName));
+      renamedDirs.push({ from: item.dir, to: newDirName });
+
+      // Rename files inside that contain the old phase ID prefix
+      const dirFiles = fs.readdirSync(path.join(phasesDir, newDirName));
+      for (const file of dirFiles) {
+        // Files may have phase prefix like "06.2-01-plan.md"
+        if (file.includes(oldPhaseId)) {
+          const newFileName = file.replace(oldPhaseId, newPhaseId);
+          fs.renameSync(
+            path.join(phasesDir, newDirName, file),
+            path.join(phasesDir, newDirName, newFileName)
+          );
+          renamedFiles.push({ from: file, to: newFileName });
+        }
+      }
+    }
+  } catch (e) {
+    return { renamedDirs, renamedFiles, error: `Partial rename: ${e.message}` };
+  }
+
+  return { renamedDirs, renamedFiles };
+}
+
+/**
+ * Collect phase directories that need renumbering (integer > removedInt).
+ * @param {string[]} dirs - Sorted directory names
+ * @param {number} removedInt - Removed phase integer
+ * @returns {Array} Items to rename, sorted descending to avoid collisions
+ */
+function collectDirsToRenumber(dirs, removedInt) {
+  const toRename = [];
+  for (const dir of dirs) {
+    const dirMatch = dir.match(/^(\d+)([A-Z])?(?:\.(\d+))?-(.+)$/i);
+    if (!dirMatch) continue;
+    const dirInt = parseInt(dirMatch[1], 10);
+    if (dirInt > removedInt) {
+      toRename.push({
+        dir, oldInt: dirInt,
+        letter: dirMatch[2] ? dirMatch[2].toUpperCase() : '',
+        decimal: dirMatch[3] ? parseInt(dirMatch[3], 10) : null,
+        slug: dirMatch[4],
+      });
+    }
+  }
+  toRename.sort((left, right) => {
+    if (left.oldInt !== right.oldInt) return right.oldInt - left.oldInt;
+    return (right.decimal || 0) - (left.decimal || 0);
+  });
+  return toRename;
+}
+
+/**
+ * Rename a single phase directory and its internal files.
+ * @param {string} phasesDir - Phases directory path
+ * @param {Object} item - Rename item from collectDirsToRenumber
+ * @param {Array} renamedDirs - Accumulator for renamed dirs
+ * @param {Array} renamedFiles - Accumulator for renamed files
+ */
+function renamePhaseDir(phasesDir, item, renamedDirs, renamedFiles) {
+  const newPadded = String(item.oldInt - 1).padStart(2, '0');
+  const oldPadded = String(item.oldInt).padStart(2, '0');
+  const suffix = (item.letter || '') + (item.decimal !== null ? `.${item.decimal}` : '');
+  const oldPrefix = oldPadded + suffix;
+  const newPrefix = newPadded + suffix;
+  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 file of fs.readdirSync(path.join(phasesDir, newDirName))) {
+    if (file.startsWith(oldPrefix)) {
+      const newFileName = newPrefix + file.slice(oldPrefix.length);
+      fs.renameSync(path.join(phasesDir, newDirName, file), path.join(phasesDir, newDirName, newFileName));
+      renamedFiles.push({ from: file, to: newFileName });
+    }
+  }
+}
+
+/**
+ * Renumber integer phases (and their decimal/letter children) after one is removed.
+ *
+ * Algorithm: When an integer phase like 05 is removed, all phases with a higher
+ * integer base (06, 06.1, 06A, 07, ...) must be decremented by 1. We process
+ * in descending order to avoid directory name collisions during the rename
+ * cascade (e.g. rename 07 -> 06 before 06 -> 05). Each directory and its
+ * contained files with the old phase prefix are renamed to reflect the new number.
+ *
+ * @param {string} phasesDir - Absolute path to the phases directory
+ * @param {number} removedInt - The integer phase number that was removed
+ * @returns {{ renamedDirs: Array, renamedFiles: Array }}
+ */
+function renumberIntegerPhases(phasesDir, removedInt) {
+  const renamedDirs = [];
+  const renamedFiles = [];
+  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 toRename = collectDirsToRenumber(dirs, removedInt);
+    for (const item of toRename) renamePhaseDir(phasesDir, item, renamedDirs, renamedFiles);
+  } catch (e) {
+    return { renamedDirs, renamedFiles, error: `Partial rename: ${e.message}` };
+  }
+  return { renamedDirs, renamedFiles };
+}
+
+/**
+ * Rewrite roadmap.md after a phase is removed: delete the target section,
+ * remove checkbox/table references, and renumber subsequent phase references.
+ *
+ * @param {string} cwd - Working directory path
+ * @param {string} phaseNum - The phase number that was removed (as originally specified)
+ * @param {boolean} isDecimal - Whether the removed phase was a decimal phase
+ * @param {string} normalized - The zero-padded normalized phase number
+ */
+function updateRoadmapAfterRemoval(cwd, phaseNum, isDecimal, normalized) {
+  const roadmapPath = path.join(planningPath(cwd), ROADMAP_FILE);
+  let roadmapContent;
+  try {
+    roadmapContent = fs.readFileSync(roadmapPath, 'utf-8');
+  } catch { return; }
+
+  // Remove the target phase section from roadmap.md.
+  // Matches from the phase heading to the next phase heading (or end of file).
+  const targetEscaped = escapeRegex(phaseNum);
+  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 checkbox list items referencing this phase
+  const checkboxPattern = new RegExp(`\\n?-\\s*\\[[ x]\\]\\s*.*Phase\\s+${targetEscaped}[:\\s][^\\n]*`, 'gi');
+  roadmapContent = roadmapContent.replace(checkboxPattern, '');
+
+  // Remove progress table rows referencing this phase
+  const tableRowPattern = new RegExp(`\\n?\\|\\s*${targetEscaped}\\.?\\s[^|]*\\|[^\\n]*`, 'gi');
+  roadmapContent = roadmapContent.replace(tableRowPattern, '');
+
+  // For integer phase removal, renumber all references to subsequent phases.
+  // Walk from highest phase number down to removedInt+1, decrementing each by 1.
+  // This avoids double-renaming (e.g. 8->7 then 7->6 would break if done ascending).
+  if (!isDecimal) {
+    const removedInt = parseInt(normalized, 10);
+
+    // Reasonable upper bound for phase numbers
+    const maxPhase = 99;
+    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:
+      roadmapContent = roadmapContent.replace(
+        new RegExp(`(#{2,4}\\s*Phase\\s+)${oldStr}(\\s*:)`, 'gi'),
+        `$1${newStr}$2`
+      );
+
+      // Inline phase references: "Phase 18:" or "Phase 18 " -> "Phase 17:"
+      roadmapContent = roadmapContent.replace(
+        new RegExp(`(Phase\\s+)${oldStr}([:\\s])`, 'g'),
+        `$1${newStr}$2`
+      );
+
+      // Plan references in padded form: 18-01 -> 17-01
+      roadmapContent = roadmapContent.replace(
+        new RegExp(`${oldPad}-(\\d{2})`, 'g'),
+        `${newPad}-$1`
+      );
+
+      // Progress table row numbers: | 18. -> | 17.
+      roadmapContent = roadmapContent.replace(
+        new RegExp(`(\\|\\s*)${oldStr}\\.\\s`, 'g'),
+        `$1${newStr}. `
+      );
+
+      // Depends-on references: "Depends on:** Phase 18" -> "Phase 17"
+      roadmapContent = roadmapContent.replace(
+        new RegExp(`(Depends on:\\*\\*\\s*Phase\\s+)${oldStr}\\b`, 'gi'),
+        `$1${newStr}`
+      );
+    }
+  }
+
+  try { fs.writeFileSync(roadmapPath, roadmapContent, 'utf-8'); } catch { /* best-effort */ }
+}
+
+/**
+ * Remove a phase directory, renumber subsequent phases, and update ROADMAP/STATE.
+ * @param {string} cwd - Working directory path
+ * @param {string} targetPhase - Phase number to remove
+ * @param {Object} options - Options (force: skip executed-work check)
+ * @param {boolean} raw - If true, output raw value instead of JSON
+ * @returns {void}
+ */
+function cmdPhaseRemove(cwd, targetPhase, options, raw) {
+  if (!targetPhase) {
+    error('phase number required for phase remove');
+  }
+
+  const roadmapPath = path.join(planningPath(cwd), ROADMAP_FILE);
+  const phasesDir = phasesPath(cwd);
+  const force = options.force || false;
+
+  if (!fileAccessible(roadmapPath)) {
+    error('roadmap.md not found');
+  }
+
+  // Normalize the target
+  const normalized = normalizePhaseName(targetPhase);
+  const isDecimal = targetPhase.includes('.');
+
+  // Find and validate target directory
+  let targetDir = null;
+  try {
+    const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+    const dirs = entries.filter(entry => entry.isDirectory()).map(entry => entry.name).sort((left, right) => comparePhaseNum(left, right));
+    targetDir = dirs.find(dir => dir.startsWith(normalized + '-') || dir === normalized);
+  } catch {
+    // Phases directory does not exist; targetDir remains null
+  }
+
+  // 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(isSummaryFile);
+    if (summaries.length > 0) {
+      error(`Phase ${targetPhase} has ${summaries.length} executed plan(s). Use --force to remove anyway.`);
+    }
+  }
+
+  // Delete target directory
+  let removeWarning = null;
+  if (targetDir) {
+    const removeResult = removePhaseFromDisk(path.join(phasesDir, targetDir));
+    if (!removeResult.removed) {
+      removeWarning = removeResult.error;
+    }
+  }
+
+  // Renumber subsequent phases using the appropriate strategy
+  let renamedDirs = [];
+  let renamedFiles = [];
+
+  let renameError = null;
+  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);
+    const result = renumberDecimalPhases(phasesDir, baseInt, removedDecimal);
+    renamedDirs = result.renamedDirs;
+    renamedFiles = result.renamedFiles;
+    renameError = result.error || null;
+  } else {
+    // Integer removal: renumber all subsequent integer phases
+    const removedInt = parseInt(normalized, 10);
+    const result = renumberIntegerPhases(phasesDir, removedInt);
+    renamedDirs = result.renamedDirs;
+    renamedFiles = result.renamedFiles;
+    renameError = result.error || null;
+  }
+
+  // Update roadmap.md: remove section and renumber references
+  updateRoadmapAfterRemoval(cwd, targetPhase, isDecimal, normalized);
+
+  // Update state.md phase count
+  const stateUpdated = updateStateAfterPhaseRemoval(cwd);
+
+  const result = {
+    removed: targetPhase,
+    directory_deleted: targetDir || null,
+    renamed_directories: renamedDirs,
+    renamed_files: renamedFiles,
+    roadmap_updated: true,
+    state_updated: stateUpdated,
+  };
+  if (renameError) result.rename_warning = renameError;
+  if (removeWarning) result.remove_warning = removeWarning;
+
+  output(result, raw);
+}
+
+/**
+ * Decrement phase count in state.md after a phase is removed.
+ * @param {string} cwd - Working directory path
+ * @returns {boolean} true if state.md was updated
+ */
+function updateStateAfterPhaseRemoval(cwd) {
+  const statePath = path.join(planningPath(cwd), STATE_FILE);
+  const content = readStateSafe(statePath);
+  if (content === null) return false;
+
+  let updated = content;
+  // Decrement "Total Phases" field
+  const totalPattern = /(\*\*Total Phases:\*\*\s*)(\d+)/;
+  const totalMatch = updated.match(totalPattern);
+  if (totalMatch) {
+    updated = updated.replace(totalPattern, `$1${parseInt(totalMatch[2], 10) - 1}`);
+  }
+  // Decrement "Phase: X of Y" pattern
+  const ofPattern = /(\bof\s+)(\d+)(\s*(?:\(|phases?))/i;
+  const ofMatch = updated.match(ofPattern);
+  if (ofMatch) {
+    updated = updated.replace(ofPattern, `$1${parseInt(ofMatch[2], 10) - 1}$3`);
+  }
+  writeStateMd(statePath, updated, cwd);
+  return true;
+}
+
+module.exports = {
+  removePhaseFromDisk,
+  renumberDecimalPhases,
+  collectDirsToRenumber,
+  renamePhaseDir,
+  renumberIntegerPhases,
+  updateRoadmapAfterRemoval,
+  cmdPhaseRemove,
+  updateStateAfterPhaseRemoval,
+};