@sienklogic/plan-build-run 2.1.0 → 2.1.1

package/plugins/pbr/scripts/pbr-tools.js

@@ -3,8 +3,16 @@
 /**
  * pbr-tools.js — Structured JSON state operations for Plan-Build-Run skills.
  *
- * Provides read-only commands that return JSON, replacing LLM-based text parsing
- * of STATE.md, ROADMAP.md, and config.json. Skills call this via:
+ * Thin dispatcher that imports from lib/ modules. All core logic lives in:
+ *   lib/core.js    — Foundation utilities (parsers, file ops, constants)
+ *   lib/config.js  — Config loading, validation, depth profiles
+ *   lib/state.js   — STATE.md operations (load, update, patch, advance)
+ *   lib/roadmap.js — ROADMAP.md operations (parse, update status/plans)
+ *   lib/phase.js   — Phase operations (add, remove, list, info, plan-index)
+ *   lib/init.js    — Compound init commands (execute-phase, plan-phase, etc.)
+ *   lib/history.js — History operations (append to STATE.md ## History, load with HISTORY.md fallback)
+ *
+ * Skills call this via:
  *   node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js <command> [args]
  *
  * Commands:
@@ -18,196 +26,677 @@
  *   phase-info <phase>      — Comprehensive single-phase status → JSON
  *   roadmap update-status <phase> <status>      — Update phase status in ROADMAP.md
  *   roadmap update-plans <phase> <complete> <total> — Update phase plans in ROADMAP.md
- *   history append <type> <title> [body] — Append record to HISTORY.md
- *   history load                         — Load all HISTORY.md records as JSON
+ *   history append <type> <title> [body] — Append record to STATE.md ## History (fallback: HISTORY.md)
+ *   history load                         — Load history records as JSON (STATE.md first, HISTORY.md fallback)
+ *   todo list [--theme X] [--status Y]  — List todos as JSON (default: pending)
+ *   todo get <NNN>                       — Get a specific todo by number
+ *   todo add <title> [--priority P] [--theme T] — Add a new todo
+ *   todo done <NNN>                      — Mark a todo as complete
+ *   llm metrics [--session <ISO>]        — Lifetime or session-scoped LLM usage metrics
+ *   validate-project        — Comprehensive .planning/ integrity check
+ *   phase add <slug> [--after N] [--goal "..."] [--depends-on N] — Add phase with ROADMAP.md integration
+ *   phase remove <N>             — Remove an empty phase directory (with renumbering)
+ *   phase list                   — List all phase directories with status
+ *   phase complete <N>           — Mark phase N complete, advance STATE.md to next phase
+ *   phase insert <N> <slug> [--goal "..."] [--depends-on N] — Insert phase at position N, renumber subsequent
+ *   phase commits-for <N>       — Read .phase-manifest.json for phase N, output commits JSON. Falls back to git log
+ *   phase first-last-commit <N> — Output { first, last } commit hashes from manifest or git log
+ *   learnings ingest <json-file>  — Ingest a learning entry into global store
+ *   learnings query [--tags X] [--min-confidence Y] [--stack S] [--type T] — Query learnings
+ *   learnings check-thresholds   — Check deferral trigger conditions
+ *   spot-check <phaseSlug> <planId>  — Verify SUMMARY, key_files, and commits exist for a plan
+ *   staleness-check <phase-slug>  — Check if phase plans are stale vs dependencies
+ *   summary-gate <phase-slug> <plan-id>  — Verify SUMMARY.md exists, non-empty, valid frontmatter
+ *   checkpoint init <phase-slug> [--plans "id1,id2"]  — Initialize checkpoint manifest
+ *   checkpoint update <phase-slug> --wave N --resolved id [--sha hash]  — Update manifest
+ *   seeds match <phase-slug> <phase-number>  — Find matching seed files for a phase
+ *   session get <key>              — Read a key from .planning/.session.json
+ *   session set <key> <value>      — Write a key to .planning/.session.json
+ *   session clear [key]            — Delete .session.json or set key to null
+ *   session dump                   — Print entire .session.json content
+ *   skill-section <skill> <section>       — Extract a section from a skill's SKILL.md → JSON
+ *   skill-section --list <skill>          — List all headings in a skill → JSON
+ *   step-verify [skill] [step] [checklist-json]  — Validate per-step completion checklist → JSON
+ *   build-preview [phase-slug]            — Preview what /pbr:execute-phase would do for a phase → JSON
+ *   claim acquire <phase-slug> --session-id <id> --skill <name> — Acquire phase claim
+ *   claim release <phase-slug> --session-id <id>              — Release phase claim
+ *   claim list                                                 — List all active phase claims
+ *   suggest-alternatives phase-not-found [slug]       — List available phases for unknown slug → JSON
+ *   suggest-alternatives missing-prereq [phase]        — List missing prerequisites for a phase → JSON
+ *   suggest-alternatives config-invalid [field] [val]  — List valid values for invalid config field → JSON
+ *
+ * Environment: PBR_PROJECT_ROOT — Override project root directory (used when hooks fire from subagent cwd)
  */
 
 const fs = require('fs');
 const path = require('path');
 
-const cwd = process.cwd();
-const planningDir = path.join(cwd, '.planning');
+// --- Import lib modules ---
+const {
+  KNOWN_AGENTS,
+  VALID_STATUS_TRANSITIONS,
+  validateStatusTransition,
+  output,
+  error,
+  parseYamlFrontmatter,
+  parseMustHaves,
+  findFiles,
+  tailLines,
+  countMustHaves,
+  determinePhaseStatus,
+  atomicWrite,
+  lockedFileUpdate,
+  writeActiveSkill,
+  sessionLoad,
+  sessionSave,
+  SESSION_ALLOWED_KEYS,
+  STALE_SESSION_MS,
+  resolveSessionPath,
+  acquireClaim,
+  releaseClaim,
+  releaseSessionClaims: _releaseSessionClaims,
+  listClaims: _listClaims
+} = require('./lib/core');
+
+const {
+  configLoad: _configLoad,
+  configClearCache: _configClearCache,
+  configValidate: _configValidate,
+  resolveDepthProfile,
+  DEPTH_PROFILE_DEFAULTS,
+  loadUserDefaults,
+  saveUserDefaults,
+  mergeUserDefaults,
+  USER_DEFAULTS_PATH
+} = require('./lib/config');
+
+const {
+  parseStateMd,
+  updateLegacyStateField,
+  updateFrontmatterField,
+  stateLoad: _stateLoad,
+  stateCheckProgress: _stateCheckProgress,
+  stateUpdate: _stateUpdate,
+  statePatch: _statePatch,
+  stateAdvancePlan: _stateAdvancePlan,
+  stateRecordMetric: _stateRecordMetric,
+  stateRecordActivity: _stateRecordActivity,
+  stateUpdateProgress: _stateUpdateProgress
+} = require('./lib/state');
+
+const {
+  parseRoadmapMd,
+  findRoadmapRow,
+  updateTableRow,
+  roadmapUpdateStatus: _roadmapUpdateStatus,
+  roadmapUpdatePlans: _roadmapUpdatePlans,
+  roadmapAnalyze: _roadmapAnalyze,
+  roadmapAppendPhase: _roadmapAppendPhase,
+  roadmapRemovePhase: _roadmapRemovePhase,
+  roadmapRenumberPhases: _roadmapRenumberPhases,
+  roadmapInsertPhase: _roadmapInsertPhase
+} = require('./lib/roadmap');
+
+const {
+  frontmatter: _frontmatter,
+  planIndex: _planIndex,
+  mustHavesCollect: _mustHavesCollect,
+  phaseInfo: _phaseInfo,
+  phaseAdd: _phaseAdd,
+  phaseRemove: _phaseRemove,
+  phaseList: _phaseList,
+  milestoneStats: _milestoneStats,
+  phaseComplete: _phaseComplete,
+  phaseInsert: _phaseInsert
+} = require('./lib/phase');
+
+const {
+  initExecutePhase: _initExecutePhase,
+  initPlanPhase: _initPlanPhase,
+  initQuick: _initQuick,
+  initVerifyWork: _initVerifyWork,
+  initResume: _initResume,
+  initProgress: _initProgress,
+  initStateBundle: _initStateBundle
+} = require('./lib/init');
+
+const {
+  historyAppend: _historyAppend,
+  historyLoad: _historyLoad
+} = require('./lib/history');
+
+const {
+  todoList: _todoList,
+  todoGet: _todoGet,
+  todoAdd: _todoAdd,
+  todoDone: _todoDone
+} = require('./lib/todo');
+
+const {
+  applyMigrations: _applyMigrations
+} = require('./lib/migrate');
+
+const {
+  spotCheck: _spotCheck
+} = require('./lib/spot-check');
+
+const {
+  learningsIngest: _learningsIngest,
+  learningsQuery: _learningsQuery,
+  checkDeferralThresholds: _checkDeferralThresholds
+} = require('./lib/learnings');
+
+const {
+  referenceGet: _referenceGet
+} = require('./lib/reference');
+
+const {
+  skillSection: _skillSection,
+  listAvailableSkills: _listAvailableSkills
+} = require('./lib/skill-section');
+
+const {
+  stepVerify: _stepVerify
+} = require('./lib/step-verify');
+
+const {
+  buildPreview: _buildPreview
+} = require('./lib/preview');
+
+const {
+  contextTriage: _contextTriage
+} = require('./lib/context');
+
+const {
+  phaseAlternatives: _phaseAlternatives,
+  prerequisiteAlternatives: _prereqAlternatives,
+  configAlternatives: _configAlternatives
+} = require('./lib/alternatives');
+
+const {
+  stalenessCheck: _stalenessCheck,
+  summaryGate: _summaryGate,
+  checkpointInit: _checkpointInit,
+  checkpointUpdate: _checkpointUpdate,
+  seedsMatch: _seedsMatch,
+  ciPoll: _ciPoll,
+  rollback: _rollback
+} = require('./lib/build');
+
+// --- Local LLM imports (not extracted — separate module tree) ---
+const { resolveConfig, checkHealth } = require('./local-llm/health');
+const { classifyArtifact } = require('./local-llm/operations/classify-artifact');
+const { scoreSource } = require('./local-llm/operations/score-source');
+const { classifyError } = require('./local-llm/operations/classify-error');
+const { summarizeContext } = require('./local-llm/operations/summarize-context');
+const { readSessionMetrics, summarizeMetrics, computeLifetimeMetrics } = require('./local-llm/metrics');
+const { computeThresholdAdjustments } = require('./local-llm/threshold-tuner');
+
+// --- Module-level state (for backwards compatibility) ---
+
+let cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+let planningDir = path.join(cwd, '.planning');
+
+// --- Wrapper functions that pass planningDir to lib modules ---
+// These preserve the original function signatures (no planningDir param)
+// so existing callers (hook scripts, tests) continue to work.
 
-// --- Phase status transition state machine ---
+function configLoad(dir) {
+  return _configLoad(dir || planningDir);
+}
 
-/**
- * Valid phase status transitions. Each key is a current status, and its value
- * is an array of statuses that are legal to transition to. This is advisory —
- * invalid transitions produce a stderr warning but are not blocked, to avoid
- * breaking existing workflows.
- *
- * State machine:
- *   pending -> planned, skipped
- *   planned -> building
- *   building -> built, partial, needs_fixes
- *   built -> verified, needs_fixes
- *   partial -> building, needs_fixes
- *   verified -> building (re-execution)
- *   needs_fixes -> planned, building
- *   skipped -> pending (unskip)
- */
-const VALID_STATUS_TRANSITIONS = {
-  pending:     ['planned', 'skipped'],
-  planned:     ['building'],
-  building:    ['built', 'partial', 'needs_fixes'],
-  built:       ['verified', 'needs_fixes'],
-  partial:     ['building', 'needs_fixes'],
-  verified:    ['building'],
-  needs_fixes: ['planned', 'building'],
-  skipped:     ['pending']
-};
+function configClearCache() {
+  _configClearCache();
+  cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+  planningDir = path.join(cwd, '.planning');
+}
 
-/**
- * Check whether a phase status transition is valid according to the state machine.
- * Returns { valid, warning? } — never blocks, only advises.
- *
- * @param {string} oldStatus - Current phase status
- * @param {string} newStatus - Desired phase status
- * @returns {{ valid: boolean, warning?: string }}
- */
-function validateStatusTransition(oldStatus, newStatus) {
-  const from = (oldStatus || '').trim().toLowerCase();
-  const to = (newStatus || '').trim().toLowerCase();
+function configValidate(preloadedConfig) {
+  return _configValidate(preloadedConfig, planningDir);
+}
 
-  // If the status isn't changing, that's always fine
-  if (from === to) {
-    return { valid: true };
-  }
+function stateLoad() {
+  return _stateLoad(planningDir);
+}
 
-  // If the old status is unknown to our map, we can't validate — allow it
-  if (!VALID_STATUS_TRANSITIONS[from]) {
-    return { valid: true };
-  }
+function stateCheckProgress() {
+  return _stateCheckProgress(planningDir);
+}
+
+function stateUpdate(field, value) {
+  return _stateUpdate(field, value, planningDir);
+}
+
+function statePatch(jsonStr) {
+  return _statePatch(jsonStr, planningDir);
+}
+
+function stateAdvancePlan() {
+  return _stateAdvancePlan(planningDir);
+}
+
+function stateRecordMetric(metricArgs) {
+  return _stateRecordMetric(metricArgs, planningDir);
+}
+
+function stateRecordActivity(description) {
+  return _stateRecordActivity(description, planningDir);
+}
+
+function stateUpdateProgress() {
+  return _stateUpdateProgress(planningDir);
+}
+
+function roadmapAnalyze() {
+  return _roadmapAnalyze(planningDir);
+}
+
+function roadmapUpdateStatus(phaseNum, newStatus) {
+  return _roadmapUpdateStatus(phaseNum, newStatus, planningDir);
+}
+
+function roadmapUpdatePlans(phaseNum, complete, total) {
+  return _roadmapUpdatePlans(phaseNum, complete, total, planningDir);
+}
+
+function frontmatter(filePath) {
+  return _frontmatter(filePath);
+}
+
+function planIndex(phaseNum) {
+  return _planIndex(phaseNum, planningDir);
+}
+
+function mustHavesCollect(phaseNum) {
+  return _mustHavesCollect(phaseNum, planningDir);
+}
+
+function phaseInfo(phaseNum) {
+  return _phaseInfo(phaseNum, planningDir);
+}
+
+function phaseAdd(slug, afterPhase, options) {
+  return _phaseAdd(slug, afterPhase, planningDir, options);
+}
+
+function phaseRemove(phaseNum) {
+  return _phaseRemove(phaseNum, planningDir);
+}
+
+function phaseList() {
+  return _phaseList(planningDir);
+}
+
+function phaseComplete(phaseNum) {
+  return _phaseComplete(phaseNum, planningDir);
+}
+
+function phaseInsert(position, slug, options) {
+  return _phaseInsert(position, slug, planningDir, options);
+}
+
+function milestoneStats(version) {
+  return _milestoneStats(version, planningDir);
+}
+
+function initExecutePhase(phaseNum, overridePlanningDir, overrideModel) {
+  return _initExecutePhase(phaseNum, overridePlanningDir || planningDir, overrideModel);
+}
+
+function initPlanPhase(phaseNum, overridePlanningDir, overrideModel) {
+  return _initPlanPhase(phaseNum, overridePlanningDir || planningDir, overrideModel);
+}
+
+function initQuick(description) {
+  return _initQuick(description, planningDir);
+}
+
+function initVerifyWork(phaseNum, overridePlanningDir, overrideModel) {
+  return _initVerifyWork(phaseNum, overridePlanningDir || planningDir, overrideModel);
+}
+
+function initResume() {
+  return _initResume(planningDir);
+}
+
+function initProgress() {
+  return _initProgress(planningDir);
+}
+
+function stateBundle(phaseNum) {
+  return _initStateBundle(phaseNum, planningDir);
+}
+
+function historyAppend(entry, dir) {
+  return _historyAppend(entry, dir || planningDir);
+}
+
+function historyLoad(dir) {
+  return _historyLoad(dir || planningDir);
+}
+
+function todoList(opts) {
+  return _todoList(planningDir, opts);
+}
+
+function todoGet(num) {
+  return _todoGet(planningDir, num);
+}
+
+function todoAdd(title, opts) {
+  return _todoAdd(planningDir, title, opts);
+}
+
+function todoDone(num) {
+  return _todoDone(planningDir, num);
+}
+
+function migrate(options) {
+  return _applyMigrations(planningDir, options);
+}
+
+function spotCheck(phaseDir, planId) {
+  return _spotCheck(planningDir, phaseDir, planId);
+}
+
+function referenceGet(name, options) {
+  // Resolve plugin root — try CLAUDE_PLUGIN_ROOT env, then walk up from __dirname
+  const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT || path.resolve(__dirname, '..');
+  // Fix MSYS paths on Windows (same pattern as run-hook.js)
+  let root = pluginRoot;
+  const msysMatch = root.match(/^\/([a-zA-Z])\/(.*)/);
+  if (msysMatch) root = msysMatch[1] + ':' + path.sep + msysMatch[2];
+  return _referenceGet(name, options, root);
+}
+
+function resolvePluginRoot() {
+  // Resolve plugin root — try CLAUDE_PLUGIN_ROOT env, then walk up from __dirname
+  const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT || path.resolve(__dirname, '..');
+  // Fix MSYS paths on Windows (same pattern as run-hook.js)
+  let root = pluginRoot;
+  const msysMatch = root.match(/^\/([a-zA-Z])\/(.*)/);
+  if (msysMatch) root = msysMatch[1] + ':' + path.sep + msysMatch[2];
+  return root;
+}
+
+function skillSectionGet(skillName, sectionQuery) {
+  return _skillSection(skillName, sectionQuery, resolvePluginRoot());
+}
 
-  const allowed = VALID_STATUS_TRANSITIONS[from];
-  if (allowed.includes(to)) {
-    return { valid: true };
+function listSkillHeadings(skillName) {
+  const { listHeadings } = require('./lib/reference');
+  const root = resolvePluginRoot();
+  const skillPath = require('path').join(root, 'skills', skillName, 'SKILL.md');
+  if (!require('fs').existsSync(skillPath)) {
+    return { error: `Skill not found: ${skillName}`, available: _listAvailableSkills(root) };
   }
+  const content = require('fs').readFileSync(skillPath, 'utf8');
+  return { skill: skillName, headings: listHeadings(content) };
+}
 
-  return {
-    valid: false,
-    warning: `Suspicious status transition: "${from}" -> "${to}". Expected one of: [${allowed.join(', ')}]. Proceeding anyway (advisory).`
-  };
+function contextTriage(options) {
+  return _contextTriage(options, planningDir);
 }
 
-// --- Cached config loader ---
+function stalenessCheck(phaseSlug) { return _stalenessCheck(phaseSlug, planningDir); }
+function summaryGate(phaseSlug, planId) { return _summaryGate(phaseSlug, planId, planningDir); }
+function checkpointInit(phaseSlug, plans) { return _checkpointInit(phaseSlug, plans, planningDir); }
+function checkpointUpdate(phaseSlug, opts) { return _checkpointUpdate(phaseSlug, opts, planningDir); }
+function seedsMatch(phaseSlug, phaseNum) { return _seedsMatch(phaseSlug, phaseNum, planningDir); }
+function ciPoll(runId, timeoutSecs) { return _ciPoll(runId, timeoutSecs, planningDir); }
+function rollbackPlan(manifestPath) { return _rollback(manifestPath, planningDir); }
 
-let _configCache = null;
-let _configMtime = 0;
-let _configPath = null;
+// --- Phase commit query functions ---
 
 /**
- * Load config.json with in-process mtime-based caching.
- * Returns the parsed config object, or null if not found / parse error.
- * Cache invalidates when file mtime changes or path differs.
- *
- * @param {string} [dir] - Path to .planning directory (defaults to cwd/.planning)
- * @returns {object|null} Parsed config or null
+ * Read .phase-manifest.json for phase N, output JSON array of commits.
+ * Falls back to git log if no manifest exists.
  */
-function configLoad(dir) {
-  const configPath = path.join(dir || planningDir, 'config.json');
+function _phaseCommitsFor(phaseNum) {
+  const padded = String(phaseNum).padStart(2, '0');
+  const phasesDir = path.join(planningDir, 'phases');
+  if (!fs.existsSync(phasesDir)) return { error: 'No phases directory found' };
+
+  const phaseDir = fs.readdirSync(phasesDir).find(d => d.startsWith(padded + '-'));
+  if (!phaseDir) return { error: `Phase ${phaseNum} directory not found` };
+
+  const manifestPath = path.join(phasesDir, phaseDir, '.phase-manifest.json');
+  if (fs.existsSync(manifestPath)) {
+    try {
+      const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+      return { source: 'manifest', commits: manifest.commits || [] };
+    } catch (_e) { /* fall through to git log */ }
+  }
+
+  // Fallback: scan git log for commits matching this phase scope
   try {
-    if (!fs.existsSync(configPath)) return null;
-    const stat = fs.statSync(configPath);
-    const mtime = stat.mtimeMs;
-    if (_configCache && mtime === _configMtime && configPath === _configPath) {
-      return _configCache;
-    }
-    _configCache = JSON.parse(fs.readFileSync(configPath, 'utf8'));
-    _configMtime = mtime;
-    _configPath = configPath;
-    return _configCache;
+    const { execSync } = require('child_process');
+    const log = execSync('git log --oneline --no-merges -100', { encoding: 'utf8' });
+    const phasePattern = new RegExp(`\\((${padded}-|phase.*${phaseNum})`, 'i');
+    const commits = log.split('\n')
+      .filter(l => l.trim() && phasePattern.test(l))
+      .map(l => {
+        const parts = l.match(/^([0-9a-f]+)\s+(.*)/);
+        return parts ? { hash: parts[1], message: parts[2] } : null;
+      })
+      .filter(Boolean);
+    return { source: 'git_log', commits };
   } catch (_e) {
-    return null;
+    return { error: 'Could not read git log', commits: [] };
   }
 }
 
 /**
- * Clear the configLoad() in-process cache.
- * Useful in tests where multiple temp directories are used in rapid succession.
+ * Output { first, last } commit hashes from phase manifest or git log.
  */
-function configClearCache() {
-  _configCache = null;
-  _configMtime = 0;
-  _configPath = null;
+function _phaseFirstLastCommit(phaseNum) {
+  const result = _phaseCommitsFor(phaseNum);
+  if (result.error && !result.commits) return result;
+  const commits = result.commits || [];
+  return {
+    source: result.source,
+    first: commits.length > 0 ? commits[0].hash : null,
+    last: commits.length > 0 ? commits[commits.length - 1].hash : null,
+    total: commits.length
+  };
 }
 
-/**
- * Read the last N lines from a file efficiently.
- * Reads the entire file but only parses (JSON.parse) the trailing entries.
- * For JSONL files where full parsing is expensive, this avoids parsing
- * all lines when you only need recent entries.
- *
- * @param {string} filePath - Absolute path to the file
- * @param {number} n - Number of trailing lines to return
- * @returns {string[]} Array of raw line strings (last n lines)
- */
-function tailLines(filePath, n) {
-  try {
-    if (!fs.existsSync(filePath)) return [];
-    const content = fs.readFileSync(filePath, 'utf8').trim();
-    if (!content) return [];
-    const lines = content.split('\n');
-    if (lines.length <= n) return lines;
-    return lines.slice(lines.length - n);
-  } catch (_e) {
-    return [];
-  }
+// --- Claim wrapper functions ---
+
+function claimAcquire(phaseSlug, sessionId, skill) {
+  const phaseDir = path.join(planningDir, 'phases', phaseSlug);
+  if (!fs.existsSync(phaseDir)) return { error: `Phase directory not found: ${phaseSlug}` };
+  return acquireClaim(planningDir, phaseDir, sessionId, skill);
+}
+
+function claimRelease(phaseSlug, sessionId) {
+  const phaseDir = path.join(planningDir, 'phases', phaseSlug);
+  if (!fs.existsSync(phaseDir)) return { error: `Phase directory not found: ${phaseSlug}` };
+  return releaseClaim(planningDir, phaseDir, sessionId);
+}
+
+function claimList() {
+  return _listClaims(planningDir);
 }
 
+// --- validateProject stays here (cross-cutting across modules) ---
+
 /**
- * Built-in depth profile defaults. These define the effective settings
- * for each depth level. User config.depth_profiles overrides these.
+ * Comprehensive .planning/ integrity check.
+ * Returns { valid, errors, warnings, checks } — errors mean workflow should not proceed.
  */
-const DEPTH_PROFILE_DEFAULTS = {
-  quick: {
-    'features.research_phase': false,
-    'features.plan_checking': false,
-    'features.goal_verification': false,
-    'features.inline_verify': false,
-    'scan.mapper_count': 2,
-    'scan.mapper_areas': ['tech', 'arch'],
-    'debug.max_hypothesis_rounds': 3
-  },
-  standard: {
-    'features.research_phase': true,
-    'features.plan_checking': true,
-    'features.goal_verification': true,
-    'features.inline_verify': false,
-    'scan.mapper_count': 4,
-    'scan.mapper_areas': ['tech', 'arch', 'quality', 'concerns'],
-    'debug.max_hypothesis_rounds': 5
-  },
-  comprehensive: {
-    'features.research_phase': true,
-    'features.plan_checking': true,
-    'features.goal_verification': true,
-    'features.inline_verify': true,
-    'scan.mapper_count': 4,
-    'scan.mapper_areas': ['tech', 'arch', 'quality', 'concerns'],
-    'debug.max_hypothesis_rounds': 10
+function validateProject() {
+  const checks = [];
+  const errors = [];
+  const warnings = [];
+
+  // 1. .planning/ directory exists
+  if (!fs.existsSync(planningDir)) {
+    return { valid: false, errors: ['.planning/ directory not found'], warnings: [], checks: ['directory_exists: FAIL'] };
   }
-};
+  checks.push('directory_exists: PASS');
 
-/**
- * Resolve the effective depth profile for the current config.
- * Merges built-in defaults with any user overrides from config.depth_profiles.
- *
- * @param {object|null} config - Parsed config.json (from configLoad). If null, returns 'standard' defaults.
- * @returns {{ depth: string, profile: object }} The resolved depth name and flattened profile settings.
- */
-function resolveDepthProfile(config) {
-  const depth = (config && config.depth) || 'standard';
-  const defaults = DEPTH_PROFILE_DEFAULTS[depth] || DEPTH_PROFILE_DEFAULTS.standard;
+  // 2. config.json exists and is valid
+  const config = configLoad();
+  if (!config) {
+    errors.push('config.json missing or invalid JSON');
+    checks.push('config_valid: FAIL');
+  } else {
+    const configResult = configValidate(config);
+    if (!configResult.valid) {
+      errors.push(...configResult.errors.map(e => 'config: ' + e));
+    }
+    warnings.push(...(configResult.warnings || []).map(w => 'config: ' + w));
+    checks.push('config_valid: ' + (configResult.valid ? 'PASS' : 'FAIL'));
+  }
+
+  // 3. STATE.md exists and has valid frontmatter
+  const statePath = path.join(planningDir, 'STATE.md');
+  if (!fs.existsSync(statePath)) {
+    errors.push('STATE.md not found');
+    checks.push('state_exists: FAIL');
+  } else {
+    try {
+      const stateContent = fs.readFileSync(statePath, 'utf8');
+      const fm = parseYamlFrontmatter(stateContent);
+      if (!fm || !fm.current_phase) {
+        warnings.push('STATE.md frontmatter missing current_phase');
+        checks.push('state_frontmatter: WARN');
+      } else {
+        checks.push('state_frontmatter: PASS');
+      }
+    } catch (e) {
+      errors.push('STATE.md unreadable: ' + e.message);
+      checks.push('state_readable: FAIL');
+    }
+  }
+
+  // 4. ROADMAP.md exists
+  const roadmapPath = path.join(planningDir, 'ROADMAP.md');
+  if (!fs.existsSync(roadmapPath)) {
+    warnings.push('ROADMAP.md not found (may be a new project)');
+    checks.push('roadmap_exists: WARN');
+  } else {
+    checks.push('roadmap_exists: PASS');
+  }
+
+  // 5. Phase directory matches STATE.md current_phase
+  try {
+    if (fs.existsSync(statePath)) {
+      const stateContent = fs.readFileSync(statePath, 'utf8');
+      const fm = parseYamlFrontmatter(stateContent);
+      if (fm && fm.current_phase) {
+        const phaseNum = String(fm.current_phase).padStart(2, '0');
+        const phasesDir = path.join(planningDir, 'phases');
+        if (fs.existsSync(phasesDir)) {
+          const dirs = fs.readdirSync(phasesDir).filter(d => d.startsWith(phaseNum + '-'));
+          if (dirs.length === 0) {
+            warnings.push(`Phase directory for current_phase ${fm.current_phase} not found in .planning/phases/`);
+            checks.push('phase_directory: WARN');
+          } else {
+            checks.push('phase_directory: PASS');
+          }
+        }
+      }
+    }
+  } catch (_e) { /* best effort */ }
+
+  // 6. No stale .active-skill (>2 hours old)
+  const activeSkillPath = path.join(planningDir, '.active-skill');
+  if (fs.existsSync(activeSkillPath)) {
+    try {
+      const stat = fs.statSync(activeSkillPath);
+      const ageMs = Date.now() - stat.mtimeMs;
+      if (ageMs > 2 * 60 * 60 * 1000) {
+        const ageHours = Math.round(ageMs / (60 * 60 * 1000));
+        warnings.push(`.active-skill is ${ageHours}h old — may be stale from a crashed session`);
+        checks.push('active_skill_fresh: WARN');
+      } else {
+        checks.push('active_skill_fresh: PASS');
+      }
+    } catch (_e) { checks.push('active_skill_fresh: SKIP'); }
+  } else {
+    checks.push('active_skill_fresh: SKIP');
+  }
+
+  // 7. No .tmp files left from atomic writes
+  try {
+    const tmpFiles = fs.readdirSync(planningDir).filter(f => f.endsWith('.tmp.' + process.pid) || f.match(/\.tmp\.\d+$/));
+    if (tmpFiles.length > 0) {
+      warnings.push(`Found ${tmpFiles.length} leftover temp files in .planning/: ${tmpFiles.join(', ')}`);
+      checks.push('no_temp_files: WARN');
+    } else {
+      checks.push('no_temp_files: PASS');
+    }
+  } catch (_e) { /* best effort */ }
+
+  // 8. Session directory scan — count active, flag stale
+  const sessionsResult = { count: 0, active: [], stale: [] };
+  const sessionsDir = path.join(planningDir, '.sessions');
+  try {
+    if (fs.existsSync(sessionsDir)) {
+      const entries = fs.readdirSync(sessionsDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        sessionsResult.count++;
+        sessionsResult.active.push(entry.name);
+
+        // Check for staleness via meta.json
+        const metaPath = path.join(sessionsDir, entry.name, 'meta.json');
+        try {
+          const meta = JSON.parse(fs.readFileSync(metaPath, 'utf8'));
+          const ageMs = Date.now() - new Date(meta.created).getTime();
+          if (ageMs > STALE_SESSION_MS) {
+            sessionsResult.stale.push(entry.name);
+          }
+        } catch (_metaErr) {
+          // Fall back to directory mtime
+          try {
+            const stats = fs.statSync(path.join(sessionsDir, entry.name));
+            const ageMs = Date.now() - stats.mtimeMs;
+            if (ageMs > STALE_SESSION_MS) {
+              sessionsResult.stale.push(entry.name);
+            }
+          } catch (_statErr) { /* skip */ }
+        }
+      }
+
+      if (sessionsResult.stale.length > 0) {
+        warnings.push(`${sessionsResult.stale.length} stale session(s) found: ${sessionsResult.stale.join(', ')}. Run cleanStaleSessions to remove.`);
+        checks.push('sessions_stale: WARN');
+      } else {
+        checks.push('sessions_stale: PASS');
+      }
 
-  // Merge user overrides if present
-  const userOverrides = (config && config.depth_profiles && config.depth_profiles[depth]) || {};
-  const profile = { ...defaults, ...userOverrides };
+      // Check for singleton .active-skill coexisting with session-scoped ones
+      if (fs.existsSync(path.join(planningDir, '.active-skill'))) {
+        let hasSessionSkill = false;
+        for (const sid of sessionsResult.active) {
+          if (fs.existsSync(path.join(sessionsDir, sid, '.active-skill'))) {
+            hasSessionSkill = true;
+            break;
+          }
+        }
+        if (hasSessionSkill) {
+          warnings.push('.active-skill exists at both singleton and session-scoped paths — possible migration artifact. Consider removing the singleton .planning/.active-skill.');
+          checks.push('active_skill_dual: WARN');
+        }
+      }
+    }
+  } catch (_e) { /* best effort */ }
 
-  return { depth, profile };
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    checks,
+    sessions: sessionsResult
+  };
 }
 
-function main() {
+// --- CLI entry point ---
+
+async function main() {
   const args = process.argv.slice(2);
   const command = args[0];
   const subcommand = args[1];
@@ -221,11 +710,18 @@ function main() {
       const field = args[2];
       const value = args[3];
       if (!field || value === undefined) {
-        error('Usage: pbr-tools.js state update <field> <value>\nFields: current_phase, status, plans_complete, last_activity');
+        error('Usage: pbr-tools.js state update <field> <value>\nFields: current_phase, status, plans_complete, last_activity, progress_percent, phase_slug, last_command, blockers');
       }
       output(stateUpdate(field, value));
     } else if (command === 'config' && subcommand === 'validate') {
       output(configValidate());
+    } else if (command === 'config' && subcommand === 'load-defaults') {
+      const defaults = loadUserDefaults();
+      output(defaults || { exists: false, path: USER_DEFAULTS_PATH });
+    } else if (command === 'config' && subcommand === 'save-defaults') {
+      const config = configLoad();
+      if (!config) error('No config.json found. Run /pbr:setup first.');
+      output(saveUserDefaults(config));
     } else if (command === 'config' && subcommand === 'resolve-depth') {
       const dir = args[2] || undefined;
       const config = configLoad(dir);
@@ -269,6 +765,8 @@ function main() {
         error('Usage: pbr-tools.js roadmap update-plans <phase-number> <complete> <total>');
       }
       output(roadmapUpdatePlans(phase, complete, total));
+    } else if (command === 'roadmap' && subcommand === 'analyze') {
+      output(roadmapAnalyze());
     } else if (command === 'history' && subcommand === 'append') {
       const type = args[2];   // 'milestone' or 'phase'
       const title = args[3];
@@ -292,1087 +790,500 @@ function main() {
       const { logEvent } = require('./event-logger');
       logEvent(category, event, details);
       output({ logged: true, category, event });
+    } else if (command === 'llm' && subcommand === 'health') {
+      let rawConfig = {};
+      try { rawConfig = configLoad(planningDir) || {}; } catch (_e) { /* use defaults */ }
+      const llmConfig = resolveConfig(rawConfig.local_llm);
+      const health = await checkHealth(llmConfig);
+      output(health);
+    } else if (command === 'llm' && subcommand === 'status') {
+      let rawConfig = {};
+      try { rawConfig = configLoad(planningDir) || {}; } catch (_e) { /* use defaults */ }
+      const llmConfig = resolveConfig(rawConfig.local_llm);
+      output({
+        enabled: llmConfig.enabled,
+        model: llmConfig.model,
+        endpoint: llmConfig.endpoint,
+        features: llmConfig.features,
+        metrics_file: path.join(planningDir, 'logs', 'local-llm-metrics.jsonl'),
+        timeout_ms: llmConfig.timeout_ms,
+        disable_after_failures: llmConfig.advanced.disable_after_failures
+      });
+    } else if (command === 'llm' && subcommand === 'classify') {
+      const fileType = args[2];
+      const filePath = args[3];
+      if (!fileType || !filePath) {
+        error('Usage: pbr-tools.js llm classify <PLAN|SUMMARY> <filepath>');
+      }
+      const upperType = fileType.toUpperCase();
+      if (upperType !== 'PLAN' && upperType !== 'SUMMARY') {
+        error('llm classify: fileType must be PLAN or SUMMARY');
+      }
+      let content = '';
+      try {
+        content = fs.readFileSync(filePath, 'utf8');
+      } catch (_e) {
+        error('llm classify: cannot read file: ' + filePath);
+      }
+      let rawConfig = {};
+      try { rawConfig = configLoad(planningDir) || {}; } catch (_e) { /* use defaults */ }
+      const llmConfig = resolveConfig(rawConfig.local_llm);
+      const result = await classifyArtifact(llmConfig, planningDir, content, upperType, undefined);
+      output(result || { classification: null, reason: 'LLM disabled or unavailable' });
+    } else if (command === 'llm' && subcommand === 'score-source') {
+      const sourceUrl = args[2];
+      const filePath = args[3];
+      if (!sourceUrl || !filePath) {
+        error('Usage: pbr-tools.js llm score-source <url> <file-path>');
+      }
+      if (!fs.existsSync(filePath)) {
+        error('File not found: ' + filePath);
+      }
+      const content = fs.readFileSync(filePath, 'utf8');
+      let rawConfig = {};
+      try { rawConfig = configLoad(planningDir) || {}; } catch (_e) { /* use defaults */ }
+      const llmConfig = resolveConfig(rawConfig.local_llm);
+      const result = await scoreSource(llmConfig, planningDir, content, sourceUrl, undefined);
+      output(result || { level: null, reason: 'LLM disabled or unavailable' });
+    } else if (command === 'llm' && subcommand === 'classify-error') {
+      const filePath = args[2];
+      const agentType = args[3] || 'unknown';
+      if (!filePath) {
+        error('Usage: pbr-tools.js llm classify-error <file-path> [agent-type]');
+      }
+      if (!fs.existsSync(filePath)) {
+        error('File not found: ' + filePath);
+      }
+      const errorText = fs.readFileSync(filePath, 'utf8');
+      let rawConfig = {};
+      try { rawConfig = configLoad(planningDir) || {}; } catch (_e) { /* use defaults */ }
+      const llmConfig = resolveConfig(rawConfig.local_llm);
+      const result = await classifyError(llmConfig, planningDir, errorText, agentType, undefined);
+      output(result || { category: null, reason: 'LLM disabled or unavailable' });
+    } else if (command === 'llm' && subcommand === 'summarize') {
+      const filePath = args[2];
+      const maxWords = args[3] ? parseInt(args[3], 10) : undefined;
+      if (!filePath) {
+        error('Usage: pbr-tools.js llm summarize <file-path> [max-words]');
+      }
+      if (!fs.existsSync(filePath)) {
+        error('File not found: ' + filePath);
+      }
+      const contextText = fs.readFileSync(filePath, 'utf8');
+      let rawConfig = {};
+      try { rawConfig = configLoad(planningDir) || {}; } catch (_e) { /* use defaults */ }
+      const llmConfig = resolveConfig(rawConfig.local_llm);
+      const result = await summarizeContext(llmConfig, planningDir, contextText, maxWords, undefined);
+      output(result || { summary: null, reason: 'LLM disabled or unavailable' });
+    } else if (command === 'llm' && subcommand === 'metrics') {
+      const sessionFlag = args[2]; // '--session'
+      const sessionStart = args[3]; // ISO timestamp
+      let rawConfig = {};
+      try { rawConfig = configLoad(planningDir) || {}; } catch (_e) { /* defaults */ }
+      const rate = rawConfig.local_llm && rawConfig.local_llm.metrics && rawConfig.local_llm.metrics.frontier_token_rate
+        ? rawConfig.local_llm.metrics.frontier_token_rate : 3.0;
+      if (sessionFlag === '--session' && sessionStart) {
+        const entries = readSessionMetrics(planningDir, sessionStart);
+        const summary = summarizeMetrics(entries, rate);
+        output({ scope: 'session', session_start: sessionStart, ...summary });
+      } else {
+        const lifetime = computeLifetimeMetrics(planningDir, rate);
+        output({ scope: 'lifetime', ...lifetime });
+      }
+    } else if (command === 'llm' && subcommand === 'adjust-thresholds') {
+      let rawConfig = {};
+      try { rawConfig = configLoad(planningDir) || {}; } catch (_e) { /* use defaults */ }
+      const llmConfig = resolveConfig(rawConfig.local_llm);
+      const currentThreshold = llmConfig.advanced.confidence_threshold;
+      const suggestions = computeThresholdAdjustments(planningDir, currentThreshold);
+      output(suggestions.length > 0
+        ? { suggestions }
+        : { suggestions: [], message: 'Not enough shadow samples yet (need >= 20 per operation)' });
+    // --- Compound init commands ---
+    } else if (command === "init" && subcommand === "execute-phase") {
+      const phase = args[2];
+      if (!phase) error("Usage: pbr-tools.js init execute-phase <phase-number>");
+      output(initExecutePhase(phase));
+    } else if (command === "init" && subcommand === "plan-phase") {
+      const phase = args[2];
+      if (!phase) error("Usage: pbr-tools.js init plan-phase <phase-number>");
+      output(initPlanPhase(phase));
+    } else if (command === "init" && subcommand === "quick") {
+      const desc = args.slice(2).join(" ") || "";
+      output(initQuick(desc));
+    } else if (command === "init" && subcommand === "verify-work") {
+      const phase = args[2];
+      if (!phase) error("Usage: pbr-tools.js init verify-work <phase-number>");
+      output(initVerifyWork(phase));
+    } else if (command === "init" && subcommand === "resume") {
+      output(initResume());
+    } else if (command === "init" && subcommand === "progress") {
+      output(initProgress());
+    } else if (command === 'state-bundle') {
+      const phaseNum = args[1];
+      if (!phaseNum) error('Usage: pbr-tools.js state-bundle <phase-number>');
+      output(stateBundle(phaseNum));
+    // --- State patch/advance/metric ---
+    } else if (command === "state" && subcommand === "patch") {
+      const jsonStr = args[2];
+      if (!jsonStr) error("Usage: pbr-tools.js state patch JSON");
+      output(statePatch(jsonStr));
+    } else if (command === "state" && subcommand === "advance-plan") {
+      output(stateAdvancePlan());
+    } else if (command === "state" && subcommand === "record-metric") {
+      output(stateRecordMetric(args.slice(2)));
+    } else if (command === "state" && subcommand === "record-activity") {
+      const description = args.slice(2).join(' ');
+      if (!description) error("Usage: pbr-tools.js state record-activity <description>");
+      output(stateRecordActivity(description));
+    } else if (command === "state" && subcommand === "update-progress") {
+      output(stateUpdateProgress());
+    } else if (command === 'phase' && subcommand === 'add') {
+      const slug = args[2];
+      if (!slug) { error('Usage: phase add <slug> [--after N] [--goal "..."] [--depends-on N]'); }
+      const afterIdx = args.indexOf('--after');
+      const afterPhase = afterIdx !== -1 ? args[afterIdx + 1] : null;
+      const goalIdx = args.indexOf('--goal');
+      const goal = goalIdx !== -1 ? args[goalIdx + 1] : null;
+      const depIdx = args.indexOf('--depends-on');
+      const dependsOn = depIdx !== -1 ? args[depIdx + 1] : null;
+      const addOpts = {};
+      if (goal) addOpts.goal = goal;
+      if (dependsOn) addOpts.dependsOn = dependsOn;
+      output(phaseAdd(slug, afterPhase, Object.keys(addOpts).length > 0 ? addOpts : undefined));
+    } else if (command === 'phase' && subcommand === 'remove') {
+      const phaseNum = args[2];
+      if (!phaseNum) { error('Usage: phase remove <phase_num>'); }
+      output(phaseRemove(phaseNum));
+    } else if (command === 'phase' && subcommand === 'list') {
+      output(phaseList());
+    } else if (command === 'phase' && subcommand === 'complete') {
+      const phaseNum = args[2];
+      if (!phaseNum) { error('Usage: phase complete <phase_num>'); }
+      output(phaseComplete(phaseNum));
+    } else if (command === 'phase' && subcommand === 'insert') {
+      const position = args[2];
+      const slug = args[3];
+      if (!position || !slug) { error('Usage: phase insert <N> <slug> [--goal "..."] [--depends-on N]'); }
+      const goalIdx = args.indexOf('--goal');
+      const goal = goalIdx !== -1 ? args[goalIdx + 1] : null;
+      const depIdx = args.indexOf('--depends-on');
+      const dependsOn = depIdx !== -1 ? args[depIdx + 1] : null;
+      const insertOpts = {};
+      if (goal) insertOpts.goal = goal;
+      if (dependsOn) insertOpts.dependsOn = dependsOn;
+      output(phaseInsert(parseInt(position, 10), slug, Object.keys(insertOpts).length > 0 ? insertOpts : undefined));
+    } else if (command === 'phase' && subcommand === 'commits-for') {
+      const phaseNum = args[2];
+      if (!phaseNum) { error('Usage: phase commits-for <N>'); }
+      output(_phaseCommitsFor(phaseNum));
+    } else if (command === 'phase' && subcommand === 'first-last-commit') {
+      const phaseNum = args[2];
+      if (!phaseNum) { error('Usage: phase first-last-commit <N>'); }
+      output(_phaseFirstLastCommit(phaseNum));
+    } else if (command === 'todo' && subcommand === 'list') {
+      const opts = {};
+      const themeIdx = args.indexOf('--theme');
+      if (themeIdx !== -1 && args[themeIdx + 1]) opts.theme = args[themeIdx + 1];
+      const statusIdx = args.indexOf('--status');
+      if (statusIdx !== -1 && args[statusIdx + 1]) opts.status = args[statusIdx + 1];
+      output(todoList(opts));
+    } else if (command === 'todo' && subcommand === 'get') {
+      const num = args[2];
+      if (!num) error('Usage: pbr-tools.js todo get <NNN>');
+      output(todoGet(num));
+    } else if (command === 'todo' && subcommand === 'add') {
+      const titleParts = [];
+      const opts = {};
+      // Parse: todo add <title words...> [--priority P1] [--theme security] [--source cli]
+      for (let i = 2; i < args.length; i++) {
+        if (args[i] === '--priority' && args[i + 1]) { opts.priority = args[++i]; }
+        else if (args[i] === '--theme' && args[i + 1]) { opts.theme = args[++i]; }
+        else if (args[i] === '--source' && args[i + 1]) { opts.source = args[++i]; }
+        else { titleParts.push(args[i]); }
+      }
+      const title = titleParts.join(' ');
+      if (!title) error('Usage: pbr-tools.js todo add <title> [--priority P1|P2|P3] [--theme <theme>]');
+      output(todoAdd(title, opts));
+    } else if (command === 'todo' && subcommand === 'done') {
+      const num = args[2];
+      if (!num) error('Usage: pbr-tools.js todo done <NNN>');
+      output(todoDone(num));
+    } else if (command === 'migrate') {
+      const dryRun = args.includes('--dry-run');
+      const force = args.includes('--force');
+      const result = await migrate({ dryRun, force });
+      output(result);
+    } else if (command === 'learnings') {
+      const subCmd = args[1];
+
+      if (subCmd === 'ingest') {
+        // learnings ingest <json-file-path>
+        const jsonFile = args[2];
+        if (!jsonFile) { error('Usage: learnings ingest <json-file>'); process.exit(1); }
+        const raw = fs.readFileSync(jsonFile, 'utf8');
+        const entry = JSON.parse(raw);
+        const result = _learningsIngest(entry);
+        output(result);
+
+      } else if (subCmd === 'query') {
+        // learnings query [--tags tag1,tag2] [--min-confidence low|medium|high] [--stack react] [--type tech-pattern]
+        const filters = {};
+        for (let i = 2; i < args.length; i++) {
+          if (args[i] === '--tags' && args[i + 1]) { filters.tags = args[++i].split(',').map(t => t.trim()); }
+          else if (args[i] === '--min-confidence' && args[i + 1]) { filters.minConfidence = args[++i]; }
+          else if (args[i] === '--stack' && args[i + 1]) { filters.stack = args[++i]; }
+          else if (args[i] === '--type' && args[i + 1]) { filters.type = args[++i]; }
+        }
+        const results = _learningsQuery(filters);
+        output(results);
+
+      } else if (subCmd === 'check-thresholds') {
+        // learnings check-thresholds — for progress-tracker to call
+        const triggered = _checkDeferralThresholds();
+        output(triggered);
+
+      } else {
+        error('Usage: learnings <ingest|query|check-thresholds>');
+        process.exit(1);
+      }
+    } else if (command === 'spot-check') {
+      // spot-check <phaseSlug> <planId>
+      // Returns JSON: { ok, summary_exists, key_files_checked, commits_present, detail }
+      const phaseSlug = args[1];
+      const planId = args[2];
+      if (!phaseSlug || !planId) {
+        error('Usage: spot-check <phaseSlug> <planId>');
+      }
+      output(spotCheck(phaseSlug, planId));
+    } else if (command === 'staleness-check') {
+      const slug = args[1];
+      if (!slug) { error('Usage: staleness-check <phase-slug>'); process.exit(1); }
+      output(stalenessCheck(slug));
+    } else if (command === 'summary-gate') {
+      const [slug, planId] = args.slice(1);
+      if (!slug || !planId) { error('Usage: summary-gate <phase-slug> <plan-id>'); process.exit(1); }
+      output(summaryGate(slug, planId));
+    } else if (command === 'checkpoint') {
+      const sub = args[1];
+      const slug = args[2];
+      if (sub === 'init') {
+        const plans = args[3] || '';
+        output(checkpointInit(slug, plans));
+      } else if (sub === 'update') {
+        const waveIdx = args.indexOf('--wave');
+        const wave = waveIdx !== -1 ? parseInt(args[waveIdx + 1], 10) : 1;
+        const resolvedIdx = args.indexOf('--resolved');
+        const resolved = resolvedIdx !== -1 ? args[resolvedIdx + 1] : '';
+        const shaIdx = args.indexOf('--sha');
+        const sha = shaIdx !== -1 ? args[shaIdx + 1] : '';
+        output(checkpointUpdate(slug, { wave, resolved, sha }));
+      } else {
+        error('Usage: checkpoint init|update <phase-slug> [options]'); process.exit(1);
+      }
+    } else if (command === 'seeds') {
+      const sub = args[1];
+      if (sub === 'match') {
+        const slug = args[2];
+        const num = args[3];
+        if (!slug) { error('Usage: seeds match <phase-slug> <phase-number>'); process.exit(1); }
+        output(seedsMatch(slug, num));
+      } else {
+        error('Usage: seeds match <phase-slug> <phase-number>'); process.exit(1);
+      }
+    } else if (command === 'ci-poll') {
+      const runId = args[1];
+      const timeoutIdx = args.indexOf('--timeout');
+      const timeoutSecs = timeoutIdx !== -1 ? parseInt(args[timeoutIdx + 1], 10) : 300;
+      if (!runId) { error('Usage: pbr-tools.js ci-poll <run-id> [--timeout <seconds>]'); return; }
+      output(ciPoll(runId, timeoutSecs));
+    } else if (command === 'rollback') {
+      const manifestPath = args[1];
+      if (!manifestPath) { error('Usage: pbr-tools.js rollback <manifest-path>'); return; }
+      output(rollbackPlan(manifestPath));
+    } else if (command === 'session') {
+      const sub = args[1];
+      // Extract --session-id flag from remaining args
+      const sessionIdIdx = args.indexOf('--session-id');
+      const sessionId = sessionIdIdx !== -1 ? args[sessionIdIdx + 1] : null;
+      // Filter out --session-id and its value from positional args
+      const positional = sessionIdIdx !== -1
+        ? args.filter((_a, i) => i !== sessionIdIdx && i !== sessionIdIdx + 1)
+        : args;
+      const key = positional[2];
+      const value = positional[3];
+      const dir = planningDir;
+      if (sub === 'get') {
+        if (!key) { error('Usage: pbr-tools.js session get <key> [--session-id <id>]'); return; }
+        if (!SESSION_ALLOWED_KEYS.includes(key)) { error(`Unknown session key: ${key}. Allowed: ${SESSION_ALLOWED_KEYS.join(', ')}`); return; }
+        const data = sessionLoad(dir, sessionId);
+        const val = Object.prototype.hasOwnProperty.call(data, key) ? data[key] : null;
+        output({ key, value: val });
+      } else if (sub === 'set') {
+        if (!key || value === undefined) { error('Usage: pbr-tools.js session set <key> <value> [--session-id <id>]'); return; }
+        if (!SESSION_ALLOWED_KEYS.includes(key)) { error(`Unknown session key: ${key}. Allowed: ${SESSION_ALLOWED_KEYS.join(', ')}`); return; }
+        // Coerce numeric strings
+        let coerced = value;
+        if (/^\d+$/.test(value)) coerced = parseInt(value, 10);
+        else if (value === 'null') coerced = null;
+        const result = sessionSave(dir, { [key]: coerced }, sessionId);
+        if (!result.success) { error(result.error || 'Failed to save session'); return; }
+        output({ ok: true });
+      } else if (sub === 'clear') {
+        if (key) {
+          // Clear a specific key — set to null
+          if (!SESSION_ALLOWED_KEYS.includes(key)) { error(`Unknown session key: ${key}. Allowed: ${SESSION_ALLOWED_KEYS.join(', ')}`); return; }
+          const result = sessionSave(dir, { [key]: null }, sessionId);
+          if (!result.success) { error(result.error || 'Failed to clear session key'); return; }
+        } else {
+          // Clear entire session file
+          const sessionPath = sessionId
+            ? resolveSessionPath(dir, '.session.json', sessionId)
+            : path.join(dir, '.session.json');
+          try { if (fs.existsSync(sessionPath)) fs.unlinkSync(sessionPath); } catch (e) { error(e.message); return; }
+        }
+        output({ ok: true });
+      } else if (sub === 'dump') {
+        const data = sessionLoad(dir, sessionId);
+        output(data);
+      } else {
+        error('Usage: pbr-tools.js session get|set|clear|dump <key> [value] [--session-id <id>]');
+      }
+    } else if (command === 'context-triage') {
+      const options = {};
+      const agentsIdx = args.indexOf('--agents-done');
+      if (agentsIdx !== -1) options.agentsDone = parseInt(args[agentsIdx + 1], 10);
+      const plansIdx = args.indexOf('--plans-total');
+      if (plansIdx !== -1) options.plansTotal = parseInt(args[plansIdx + 1], 10);
+      const stepIdx = args.indexOf('--step');
+      if (stepIdx !== -1) options.currentStep = args[stepIdx + 1];
+      output(contextTriage(options));
+    } else if (command === 'reference') {
+      const name = args[1];
+      if (!name) error('Usage: pbr-tools.js reference <name> [--section <heading>] [--list]');
+      const listFlag = args.includes('--list');
+      const sectionIdx = args.indexOf('--section');
+      const section = sectionIdx !== -1 ? args.slice(sectionIdx + 1).join(' ') : null;
+      output(referenceGet(name, { section: section, list: listFlag }));
+    } else if (command === 'milestone-stats') {
+      const version = args[1];
+      if (!version) error('Usage: pbr-tools.js milestone-stats <version>');
+      output(milestoneStats(version));
+    } else if (command === 'validate-project') {
+      output(validateProject());
+    } else if (command === 'skill-section') {
+      // skill-section --list <skill>  — list all headings
+      if (args[1] === '--list') {
+        const skillName = args[2];
+        if (!skillName) { error('Usage: pbr-tools.js skill-section --list <skill>'); return; }
+        const listResult = listSkillHeadings(skillName);
+        output(listResult);
+        if (listResult.error) process.exit(1);
+      } else {
+        // skill-section <skill> <section...>
+        const skillName = args[1];
+        const sectionQuery = args.slice(2).join(' ');
+        if (!skillName || !sectionQuery) {
+          error('Usage: pbr-tools.js skill-section <skill> <section>');
+          return;
+        }
+        const secResult = skillSectionGet(skillName, sectionQuery);
+        output(secResult);
+        if (secResult.error) process.exit(1);
+      }
+    } else if (command === 'step-verify') {
+      // step-verify <skill> <step> <checklist-json>
+      const skill = args[1];
+      const step = args[2];
+      const checklistStr = args[3] || '[]';
+      let checklist;
+      try {
+        checklist = JSON.parse(checklistStr);
+      } catch (_e) {
+        output({ error: 'Invalid checklist JSON' });
+        process.exit(1);
+        return;
+      }
+      const svPlanningDir = path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+      const svContext = {
+        planningDir: svPlanningDir,
+        phaseSlug: process.env.PBR_PHASE_SLUG || '',
+        planId: process.env.PBR_PLAN_ID || ''
+      };
+      const svResult = _stepVerify(skill, step, checklist, svContext);
+      output(svResult);
+      if (svResult.error || svResult.all_passed === false) process.exit(1);
+    } else if (command === 'build-preview') {
+      const phaseSlug = args[1];
+      if (!phaseSlug) {
+        error('Usage: pbr-tools.js build-preview <phase-slug>');
+        return;
+      }
+      const previewPlanningDir = path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+      const previewPluginRoot = path.resolve(__dirname, '..');
+      const result = _buildPreview(phaseSlug, {}, previewPlanningDir, previewPluginRoot);
+      if (result && result.error) {
+        output(result);
+        process.exit(1);
+      }
+      output(result);
+    } else if (command === 'suggest-alternatives') {
+      const errorType = args[1];
+      const altPlanningDir = path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+      if (errorType === 'phase-not-found') {
+        output(_phaseAlternatives(args[2] || '', altPlanningDir));
+      } else if (errorType === 'missing-prereq') {
+        output(_prereqAlternatives(args[2] || '', altPlanningDir));
+      } else if (errorType === 'config-invalid') {
+        output(_configAlternatives(args[2] || '', args[3] || '', altPlanningDir));
+      } else {
+        output({ error: 'Unknown error type. Valid: phase-not-found, missing-prereq, config-invalid' });
+        process.exit(1);
+      }
+    } else if (command === 'claim' && subcommand === 'acquire') {
+      const phaseSlug = args[2];
+      const sidIdx = args.indexOf('--session-id');
+      const sessionId = sidIdx !== -1 ? args[sidIdx + 1] : null;
+      const skillIdx = args.indexOf('--skill');
+      const skill = skillIdx !== -1 ? args[skillIdx + 1] : 'unknown';
+      if (!phaseSlug || !sessionId) {
+        error('Usage: pbr-tools.js claim acquire <phase-slug> --session-id <id> --skill <name>');
+      }
+      output(claimAcquire(phaseSlug, sessionId, skill));
+    } else if (command === 'claim' && subcommand === 'release') {
+      const phaseSlug = args[2];
+      const sidIdx = args.indexOf('--session-id');
+      const sessionId = sidIdx !== -1 ? args[sidIdx + 1] : null;
+      if (!phaseSlug || !sessionId) {
+        error('Usage: pbr-tools.js claim release <phase-slug> --session-id <id>');
+      }
+      output(claimRelease(phaseSlug, sessionId));
+    } else if (command === 'claim' && subcommand === 'list') {
+      output(claimList());
+    } else if (command === 'tmux' && subcommand === 'detect') {
+      const tmuxEnv = process.env.TMUX || '';
+      const result = {
+        in_tmux: !!tmuxEnv,
+        pane: process.env.TMUX_PANE || null,
+        session: null
+      };
+      if (tmuxEnv) {
+        // TMUX env format: /socket/path,PID,INDEX
+        const parts = tmuxEnv.split(',');
+        if (parts.length >= 1) {
+          result.session = parts[0].split('/').pop() || null;
+        }
+      }
+      output(result);
     } else {
-      error(`Unknown command: ${args.join(' ')}\nCommands: state load|check-progress|update, config validate, plan-index, frontmatter, must-haves, phase-info, roadmap update-status|update-plans, history append|load, event`);
+      error(`Unknown command: ${args.join(' ')}\nCommands: state load|check-progress|update|patch|advance-plan|record-metric, config validate|load-defaults|save-defaults|resolve-depth, validate-project, migrate [--dry-run] [--force], init execute-phase|plan-phase|quick|verify-work|resume|progress, state-bundle <phase>, plan-index, frontmatter, must-haves, phase-info, phase add|remove|list|complete, roadmap update-status|update-plans, history append|load, todo list|get|add|done, event, llm health|status|classify|score-source|classify-error|summarize|metrics [--session <ISO>]|adjust-thresholds, learnings ingest|query|check-thresholds, milestone-stats <version>, context-triage [--agents-done N] [--plans-total N] [--step NAME], ci-poll <run-id> [--timeout <seconds>], rollback <manifest-path>, session get|set|clear|dump, claim acquire|release|list, skill-section <skill> <section>|--list <skill>, step-verify <skill> <step> <checklist-json>, suggest-alternatives phase-not-found|missing-prereq|config-invalid [args], tmux detect`);
     }
   } catch (e) {
     error(e.message);
   }
 }
 
-// --- Commands ---
-
-function stateLoad() {
-  const result = {
-    exists: false,
-    config: null,
-    state: null,
-    roadmap: null,
-    phase_count: 0,
-    current_phase: null,
-    progress: null
-  };
-
-  if (!fs.existsSync(planningDir)) {
-    return result;
-  }
-  result.exists = true;
-
-  // Load config.json
-  const configPath = path.join(planningDir, 'config.json');
-  if (fs.existsSync(configPath)) {
-    try {
-      result.config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
-    } catch (_) {
-      result.config = { _error: 'Failed to parse config.json' };
-    }
-  }
-
-  // Load STATE.md
-  const statePath = path.join(planningDir, 'STATE.md');
-  if (fs.existsSync(statePath)) {
-    const content = fs.readFileSync(statePath, 'utf8');
-    result.state = parseStateMd(content);
-  }
-
-  // Load ROADMAP.md
-  const roadmapPath = path.join(planningDir, 'ROADMAP.md');
-  if (fs.existsSync(roadmapPath)) {
-    const content = fs.readFileSync(roadmapPath, 'utf8');
-    result.roadmap = parseRoadmapMd(content);
-    result.phase_count = result.roadmap.phases.length;
-  }
-
-  // Extract current phase
-  if (result.state && result.state.current_phase) {
-    result.current_phase = result.state.current_phase;
-  }
-
-  // Calculate progress
-  result.progress = calculateProgress();
-
-  return result;
-}
-
-function stateCheckProgress() {
-  const phasesDir = path.join(planningDir, 'phases');
-  if (!fs.existsSync(phasesDir)) {
-    return { phases: [], total_plans: 0, completed_plans: 0, percentage: 0 };
-  }
-
-  const phases = [];
-  let totalPlans = 0;
-  let completedPlans = 0;
-
-  const entries = fs.readdirSync(phasesDir, { withFileTypes: true })
-    .filter(e => e.isDirectory())
-    .sort((a, b) => a.name.localeCompare(b.name));
-
-  for (const entry of entries) {
-    const phaseDir = path.join(phasesDir, entry.name);
-    const plans = findFiles(phaseDir, /-PLAN\.md$/);
-    const summaries = findFiles(phaseDir, /^SUMMARY-.*\.md$/);
-    const verification = fs.existsSync(path.join(phaseDir, 'VERIFICATION.md'));
-
-    const completedSummaries = summaries.filter(s => {
-      const content = fs.readFileSync(path.join(phaseDir, s), 'utf8');
-      return /status:\s*["']?complete/i.test(content);
-    });
-
-    const phaseInfo = {
-      directory: entry.name,
-      plans: plans.length,
-      summaries: summaries.length,
-      completed: completedSummaries.length,
-      has_verification: verification,
-      status: determinePhaseStatus(plans.length, completedSummaries.length, summaries.length, verification, phaseDir)
-    };
-
-    phases.push(phaseInfo);
-    totalPlans += plans.length;
-    completedPlans += completedSummaries.length;
-  }
-
-  return {
-    phases,
-    total_plans: totalPlans,
-    completed_plans: completedPlans,
-    percentage: totalPlans > 0 ? Math.round((completedPlans / totalPlans) * 100) : 0
-  };
-}
-
-function planIndex(phaseNum) {
-  const phasesDir = path.join(planningDir, '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 frontmatter = parseYamlFrontmatter(content);
-
-    const plan = {
-      file,
-      plan_id: frontmatter.plan || file.replace(/-PLAN\.md$/, ''),
-      wave: parseInt(frontmatter.wave, 10) || 1,
-      type: frontmatter.type || 'unknown',
-      autonomous: frontmatter.autonomous !== false,
-      depends_on: frontmatter.depends_on || [],
-      gap_closure: frontmatter.gap_closure || false,
-      has_summary: fs.existsSync(path.join(fullDir, `SUMMARY-${frontmatter.plan || ''}.md`)),
-      must_haves_count: countMustHaves(frontmatter.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
-  };
-}
-
-function configValidate(preloadedConfig) {
-  let config;
-  if (preloadedConfig) {
-    config = preloadedConfig;
-  } else {
-    const configPath = path.join(planningDir, 'config.json');
-    if (!fs.existsSync(configPath)) {
-      return { valid: false, errors: ['config.json not found'], warnings: [] };
-    }
-
-    try {
-      config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
-    } catch (e) {
-      return { valid: false, errors: [`config.json is not valid JSON: ${e.message}`], warnings: [] };
-    }
-  }
-
-  const schema = JSON.parse(fs.readFileSync(path.join(__dirname, 'config-schema.json'), 'utf8'));
-  const warnings = [];
-  const errors = [];
-
-  validateObject(config, schema, '', errors, warnings);
-
-  // Semantic conflict detection — logical contradictions that pass schema validation
-  // Clear contradictions → errors; ambiguous/preference issues → warnings
-  if (config.mode === 'autonomous' && config.gates) {
-    const activeGates = Object.entries(config.gates || {}).filter(([, v]) => v === true).map(([k]) => k);
-    if (activeGates.length > 0) {
-      errors.push(`mode=autonomous with active gates (${activeGates.join(', ')}): gates are unreachable in autonomous mode`);
-    }
-  }
-  if (config.features && config.features.auto_continue && config.mode === 'interactive') {
-    warnings.push('features.auto_continue=true with mode=interactive: auto_continue only fires in autonomous mode');
-  }
-  if (config.parallelization) {
-    if (config.parallelization.enabled === false && config.parallelization.plan_level === true) {
-      warnings.push('parallelization.enabled=false with plan_level=true: plan_level is ignored when parallelization is disabled');
-    }
-    if (config.parallelization.max_concurrent_agents === 1 && config.teams && config.teams.coordination) {
-      errors.push('parallelization.max_concurrent_agents=1 with teams.coordination set: teams require concurrent agents to be useful');
-    }
-  }
-
-  return {
-    valid: errors.length === 0,
-    errors,
-    warnings
-  };
-}
-
-// --- New read-only commands ---
-
-/**
- * Parse a markdown file's YAML frontmatter and return as JSON.
- * Wraps parseYamlFrontmatter() + parseMustHaves().
- */
-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);
-}
-
-/**
- * Collect all must-haves from all PLAN.md files in a phase.
- * Returns per-plan grouping + flat deduplicated list + total count.
- */
-function mustHavesCollect(phaseNum) {
-  const phasesDir = path.join(planningDir, '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.
- */
-function phaseInfo(phaseNum) {
-  const phasesDir = path.join(planningDir, '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(planningDir, '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);
-
-  // 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'))
-  };
-}
-
-// --- Mutation commands ---
-
-/**
- * Atomically update a field in STATE.md using lockedFileUpdate.
- * Supports both legacy and frontmatter (v2) formats.
- *
- * @param {string} field - One of: current_phase, status, plans_complete, last_activity
- * @param {string} value - New value (use 'now' for last_activity to auto-timestamp)
- */
-function stateUpdate(field, value) {
-  const statePath = path.join(planningDir, 'STATE.md');
-  if (!fs.existsSync(statePath)) {
-    return { success: false, error: 'STATE.md not found' };
-  }
-
-  const validFields = ['current_phase', 'status', 'plans_complete', 'last_activity'];
-  if (!validFields.includes(field)) {
-    return { success: false, error: `Invalid field: ${field}. Valid fields: ${validFields.join(', ')}` };
-  }
-
-  // Auto-timestamp
-  if (field === 'last_activity' && value === 'now') {
-    value = new Date().toISOString().slice(0, 19).replace('T', ' ');
-  }
-
-  const result = lockedFileUpdate(statePath, (content) => {
-    const fm = parseYamlFrontmatter(content);
-    if (fm.version === 2 || fm.current_phase !== undefined) {
-      return updateFrontmatterField(content, field, value);
-    }
-    return updateLegacyStateField(content, field, value);
-  });
-
-  if (result.success) {
-    return { success: true, field, value };
-  }
-  return { success: false, error: result.error };
-}
-
-/**
- * Append a record to HISTORY.md. Creates the file if it doesn't exist.
- * Each entry is a markdown section appended at the end.
- *
- * @param {object} entry - { type: 'milestone'|'phase', title: string, body: string }
- * @param {string} [dir] - Path to .planning directory (defaults to cwd/.planning)
- * @returns {{success: boolean, error?: string}}
- */
-function historyAppend(entry, dir) {
-  const historyPath = path.join(dir || planningDir, 'HISTORY.md');
-  const timestamp = new Date().toISOString().slice(0, 10);
-
-  let header = '';
-  if (!fs.existsSync(historyPath)) {
-    header = '# Project History\n\nCompleted milestones and phase records. This file is append-only.\n\n';
-  }
-
-  const section = `${header}## ${entry.type === 'milestone' ? 'Milestone' : 'Phase'}: ${entry.title}\n_Completed: ${timestamp}_\n\n${entry.body.trim()}\n\n---\n\n`;
-
-  try {
-    fs.appendFileSync(historyPath, section, 'utf8');
-    return { success: true };
-  } catch (e) {
-    return { success: false, error: e.message };
-  }
-}
-
-/**
- * Load HISTORY.md and parse it into structured records.
- * Returns null if HISTORY.md doesn't exist.
- *
- * @param {string} [dir] - Path to .planning directory
- * @returns {object|null} { records: [{type, title, date, body}], line_count }
- */
-function historyLoad(dir) {
-  const historyPath = path.join(dir || planningDir, 'HISTORY.md');
-  if (!fs.existsSync(historyPath)) return null;
-
-  const content = fs.readFileSync(historyPath, 'utf8');
-  const records = [];
-  const sectionRegex = /^## (Milestone|Phase): (.+)\n_Completed: (\d{4}-\d{2}-\d{2})_\n\n([\s\S]*?)(?=\n---|\s*$)/gm;
-
-  let match;
-  while ((match = sectionRegex.exec(content)) !== null) {
-    records.push({
-      type: match[1].toLowerCase(),
-      title: match[2].trim(),
-      date: match[3],
-      body: match[4].trim()
-    });
-  }
-
-  return {
-    records,
-    line_count: content.split('\n').length
-  };
-}
-
-/**
- * Update the Status column for a phase in ROADMAP.md's Phase Overview table.
- */
-function roadmapUpdateStatus(phaseNum, newStatus) {
-  const roadmapPath = path.join(planningDir, '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.
- */
-function roadmapUpdatePlans(phaseNum, complete, total) {
-  const roadmapPath = path.join(planningDir, '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 };
-}
-
-// --- Mutation helpers ---
-
-/**
- * Update a field in legacy (non-frontmatter) STATE.md content.
- * Pure function: content in, content out.
- */
-function updateLegacyStateField(content, field, value) {
-  const lines = content.split('\n');
-
-  switch (field) {
-    case 'current_phase': {
-      const idx = lines.findIndex(l => /Phase:\s*\d+\s+of\s+\d+/.test(l));
-      if (idx !== -1) {
-        lines[idx] = lines[idx].replace(/(Phase:\s*)\d+/, `$1${value}`);
-      }
-      break;
-    }
-    case 'status': {
-      const idx = lines.findIndex(l => /^Status:/i.test(l));
-      if (idx !== -1) {
-        lines[idx] = `Status: ${value}`;
-      } else {
-        const phaseIdx = lines.findIndex(l => /Phase:/.test(l));
-        if (phaseIdx !== -1) {
-          lines.splice(phaseIdx + 1, 0, `Status: ${value}`);
-        } else {
-          lines.push(`Status: ${value}`);
-        }
-      }
-      break;
-    }
-    case 'plans_complete': {
-      const idx = lines.findIndex(l => /Plan:\s*\d+\s+of\s+\d+/.test(l));
-      if (idx !== -1) {
-        lines[idx] = lines[idx].replace(/(Plan:\s*)\d+/, `$1${value}`);
-      }
-      break;
-    }
-    case 'last_activity': {
-      const idx = lines.findIndex(l => /^Last Activity:/i.test(l));
-      if (idx !== -1) {
-        lines[idx] = `Last Activity: ${value}`;
-      } else {
-        const statusIdx = lines.findIndex(l => /^Status:/i.test(l));
-        if (statusIdx !== -1) {
-          lines.splice(statusIdx + 1, 0, `Last Activity: ${value}`);
-        } else {
-          lines.push(`Last Activity: ${value}`);
-        }
-      }
-      break;
-    }
-  }
-
-  return lines.join('\n');
-}
-
-/**
- * Update a field in YAML frontmatter content.
- * Pure function: content in, content out.
- */
-function updateFrontmatterField(content, field, value) {
-  const match = content.match(/^(---\s*\n)([\s\S]*?)(\n---)/);
-  if (!match) return content;
-
-  const before = match[1];
-  let yaml = match[2];
-  const after = match[3];
-  const rest = content.slice(match[0].length);
-
-  // Format value: integers stay bare, strings get quotes
-  const isNum = /^\d+$/.test(String(value));
-  const formatted = isNum ? value : `"${value}"`;
-
-  const fieldRegex = new RegExp(`^(${field})\\s*:.*$`, 'm');
-  if (fieldRegex.test(yaml)) {
-    yaml = yaml.replace(fieldRegex, `${field}: ${formatted}`);
-  } else {
-    yaml = yaml + `\n${field}: ${formatted}`;
-  }
-
-  return before + yaml + after + rest;
-}
-
-/**
- * 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('|');
-}
-
-/**
- * Lightweight JSON Schema validator — supports type, enum, properties,
- * additionalProperties, minimum, maximum for the config schema.
- */
-function validateObject(value, schema, prefix, errors, warnings) {
-  if (schema.type && typeof value !== schema.type) {
-    if (!(schema.type === 'integer' && typeof value === 'number' && Number.isInteger(value))) {
-      errors.push(`${prefix || 'root'}: expected ${schema.type}, got ${typeof value}`);
-      return;
-    }
-  }
-
-  if (schema.enum && !schema.enum.includes(value)) {
-    errors.push(`${prefix || 'root'}: value "${value}" not in allowed values [${schema.enum.join(', ')}]`);
-    return;
-  }
-
-  if (schema.minimum !== undefined && value < schema.minimum) {
-    errors.push(`${prefix || 'root'}: value ${value} is below minimum ${schema.minimum}`);
-  }
-  if (schema.maximum !== undefined && value > schema.maximum) {
-    errors.push(`${prefix || 'root'}: value ${value} is above maximum ${schema.maximum}`);
-  }
-
-  if (schema.type === 'object' && schema.properties) {
-    const knownKeys = new Set(Object.keys(schema.properties));
-
-    for (const key of Object.keys(value)) {
-      const fullKey = prefix ? `${prefix}.${key}` : key;
-      if (!knownKeys.has(key)) {
-        if (schema.additionalProperties === false) {
-          warnings.push(`${fullKey}: unrecognized key (possible typo?)`);
-        }
-        continue;
-      }
-      validateObject(value[key], schema.properties[key], fullKey, errors, warnings);
-    }
-  }
-}
-
-/**
- * Locked file update: read-modify-write with exclusive lockfile.
- * Prevents concurrent writes to STATE.md and ROADMAP.md.
- *
- * @param {string} filePath - Absolute path to the file to update
- * @param {function} updateFn - Receives current content, returns new content
- * @param {object} opts - Options: { retries: 3, retryDelayMs: 100, timeoutMs: 5000 }
- * @returns {object} { success, content?, error? }
- */
-function lockedFileUpdate(filePath, updateFn, opts = {}) {
-  const retries = opts.retries || 3;
-  const retryDelayMs = opts.retryDelayMs || 100;
-  const timeoutMs = opts.timeoutMs || 5000;
-  const lockPath = filePath + '.lock';
-
-  let lockFd = null;
-  let lockAcquired = false;
-
-  try {
-    // Acquire lock with retries
-    for (let attempt = 0; attempt < retries; attempt++) {
-      try {
-        lockFd = fs.openSync(lockPath, 'wx');
-        lockAcquired = true;
-        break;
-      } catch (e) {
-        if (e.code === 'EEXIST') {
-          // Lock exists — check if stale (older than timeoutMs)
-          try {
-            const stats = fs.statSync(lockPath);
-            if (Date.now() - stats.mtimeMs > timeoutMs) {
-              // Stale lock — remove and retry
-              fs.unlinkSync(lockPath);
-              continue;
-            }
-          } catch (_statErr) {
-            // Lock disappeared between check — retry
-            continue;
-          }
-
-          if (attempt < retries - 1) {
-            // Wait and retry
-            const waitMs = retryDelayMs * (attempt + 1);
-            const start = Date.now();
-            while (Date.now() - start < waitMs) {
-              // Busy wait (synchronous context)
-            }
-            continue;
-          }
-          return { success: false, error: `Could not acquire lock for ${path.basename(filePath)} after ${retries} attempts` };
-        }
-        throw e;
-      }
-    }
-
-    if (!lockAcquired) {
-      return { success: false, error: `Could not acquire lock for ${path.basename(filePath)}` };
-    }
-
-    // Write PID to lock file for debugging
-    fs.writeSync(lockFd, `${process.pid}`);
-    fs.closeSync(lockFd);
-    lockFd = null;
-
-    // Read current content
-    let content = '';
-    if (fs.existsSync(filePath)) {
-      content = fs.readFileSync(filePath, 'utf8');
-    }
-
-    // Apply update
-    const newContent = updateFn(content);
-
-    // Write back atomically
-    const writeResult = atomicWrite(filePath, newContent);
-    if (!writeResult.success) {
-      return { success: false, error: writeResult.error };
-    }
-
-    return { success: true, content: newContent };
-  } catch (e) {
-    return { success: false, error: e.message };
-  } finally {
-    // Close fd if still open
-    try {
-      if (lockFd !== null) fs.closeSync(lockFd);
-    } catch (_e) { /* ignore */ }
-    // Only release lock if we acquired it
-    if (lockAcquired) {
-      try {
-        fs.unlinkSync(lockPath);
-      } catch (_e) { /* ignore — may already be cleaned up */ }
-    }
-  }
-}
-
-// --- Parsers ---
-
-function parseStateMd(content) {
-  const result = {
-    current_phase: null,
-    phase_name: null,
-    progress: null,
-    status: null,
-    line_count: content.split('\n').length,
-    format: 'legacy' // 'legacy' or 'frontmatter'
-  };
-
-  // Check for YAML frontmatter (version 2 format)
-  const frontmatter = parseYamlFrontmatter(content);
-  if (frontmatter.version === 2 || frontmatter.current_phase !== undefined) {
-    result.format = 'frontmatter';
-    result.current_phase = frontmatter.current_phase || null;
-    result.total_phases = frontmatter.total_phases || null;
-    result.phase_name = frontmatter.phase_slug || frontmatter.phase_name || null;
-    result.status = frontmatter.status || null;
-    result.progress = frontmatter.progress_percent !== undefined ? frontmatter.progress_percent : null;
-    result.plans_total = frontmatter.plans_total || null;
-    result.plans_complete = frontmatter.plans_complete || null;
-    result.last_activity = frontmatter.last_activity || null;
-    result.last_command = frontmatter.last_command || null;
-    result.blockers = frontmatter.blockers || [];
-    return result;
-  }
-
-  // Legacy regex-based parsing (version 1 format, no frontmatter)
-  // DEPRECATED (2026-02): v1 STATE.md format (no YAML frontmatter) is deprecated.
-  // New projects should use v2 (frontmatter) format, generated by /pbr:setup.
-  // v1 support will be removed in a future major version.
-  process.stderr.write('[pbr] WARNING: STATE.md uses legacy v1 format. Run /pbr:setup to migrate to v2 format.\n');
-  // Extract "Phase: N of M"
-  const phaseMatch = content.match(/Phase:\s*(\d+)\s+of\s+(\d+)/);
-  if (phaseMatch) {
-    result.current_phase = parseInt(phaseMatch[1], 10);
-    result.total_phases = parseInt(phaseMatch[2], 10);
-  }
-
-  // Extract phase name (line after "Phase:")
-  const nameMatch = content.match(/--\s+(.+?)(?:\n|$)/);
-  if (nameMatch) {
-    result.phase_name = nameMatch[1].trim();
-  }
-
-  // Extract progress percentage
-  const progressMatch = content.match(/(\d+)%/);
-  if (progressMatch) {
-    result.progress = parseInt(progressMatch[1], 10);
-  }
-
-  // Extract plan status
-  const statusMatch = content.match(/Status:\s*(.+?)(?:\n|$)/i);
-  if (statusMatch) {
-    result.status = statusMatch[1].trim();
-  }
-
-  return result;
-}
-
-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;
-}
-
-function parseYamlFrontmatter(content) {
-  const match = content.match(/^---\s*\n([\s\S]*?)\n---/);
-  if (!match) return {};
-
-  const yaml = match[1];
-  const result = {};
-
-  // Simple YAML parser for flat and basic nested values
-  const lines = yaml.split('\n');
-  let currentKey = null;
-
-  for (const line of lines) {
-    // Array item
-    if (/^\s+-\s+/.test(line) && currentKey) {
-      const val = line.replace(/^\s+-\s+/, '').trim().replace(/^["']|["']$/g, '');
-      if (!result[currentKey]) result[currentKey] = [];
-      if (Array.isArray(result[currentKey])) {
-        result[currentKey].push(val);
-      }
-      continue;
-    }
-
-    // Key-value pair
-    const kvMatch = line.match(/^(\w[\w_]*)\s*:\s*(.*)/);
-    if (kvMatch) {
-      currentKey = kvMatch[1];
-      let val = kvMatch[2].trim();
-
-      if (val === '' || val === '|') {
-        // Possible array or block follows
-        continue;
-      }
-
-      // Handle arrays on same line: [a, b, c]
-      if (val.startsWith('[') && val.endsWith(']')) {
-        result[currentKey] = val.slice(1, -1).split(',')
-          .map(v => v.trim().replace(/^["']|["']$/g, ''))
-          .filter(Boolean);
-        continue;
-      }
-
-      // Clean quotes
-      val = val.replace(/^["']|["']$/g, '');
-
-      // Type coercion
-      if (val === 'true') val = true;
-      else if (val === 'false') val = false;
-      else if (/^\d+$/.test(val)) val = parseInt(val, 10);
-
-      result[currentKey] = val;
-    }
-  }
-
-  // Handle must_haves as a nested object
-  if (yaml.includes('must_haves:')) {
-    result.must_haves = parseMustHaves(yaml);
-  }
-
-  return result;
-}
-
-function parseMustHaves(yaml) {
-  const result = { truths: [], artifacts: [], key_links: [] };
-  let section = null;
-
-  const inMustHaves = yaml.split('\n');
-  let collecting = false;
-
-  for (const line of inMustHaves) {
-    if (/^\s*must_haves:/.test(line)) {
-      collecting = true;
-      continue;
-    }
-    if (collecting) {
-      if (/^\s{2}truths:/.test(line)) { section = 'truths'; continue; }
-      if (/^\s{2}artifacts:/.test(line)) { section = 'artifacts'; continue; }
-      if (/^\s{2}key_links:/.test(line)) { section = 'key_links'; continue; }
-      if (/^\w/.test(line)) break; // New top-level key, stop
-
-      if (section && /^\s+-\s+/.test(line)) {
-        result[section].push(line.replace(/^\s+-\s+/, '').trim().replace(/^["']|["']$/g, ''));
-      }
-    }
-  }
-
-  return result;
-}
-
-// --- Helpers ---
-
-function findFiles(dir, pattern) {
-  try {
-    return fs.readdirSync(dir).filter(f => pattern.test(f)).sort();
-  } catch (_) {
-    return [];
-  }
-}
-
-function determinePhaseStatus(planCount, completedCount, summaryCount, hasVerification, phaseDir) {
-  if (planCount === 0) {
-    // Check for CONTEXT.md (discussed only)
-    if (fs.existsSync(path.join(phaseDir, 'CONTEXT.md'))) return 'discussed';
-    return 'not_started';
-  }
-  if (completedCount === 0 && summaryCount === 0) return 'planned';
-  if (completedCount < planCount) return 'building';
-  if (!hasVerification) return 'built';
-  // Check verification status
-  try {
-    const vContent = fs.readFileSync(path.join(phaseDir, 'VERIFICATION.md'), 'utf8');
-    if (/status:\s*["']?passed/i.test(vContent)) return 'verified';
-    if (/status:\s*["']?gaps_found/i.test(vContent)) return 'needs_fixes';
-    return 'reviewed';
-  } catch (_) {
-    return 'built';
-  }
-}
-
-function countMustHaves(mustHaves) {
-  if (!mustHaves) return 0;
-  return (mustHaves.truths || []).length +
-    (mustHaves.artifacts || []).length +
-    (mustHaves.key_links || []).length;
-}
-
-function calculateProgress() {
-  const phasesDir = path.join(planningDir, 'phases');
-  if (!fs.existsSync(phasesDir)) {
-    return { total: 0, completed: 0, percentage: 0 };
-  }
-
-  let total = 0;
-  let completed = 0;
-
-  const entries = fs.readdirSync(phasesDir, { withFileTypes: true })
-    .filter(e => e.isDirectory());
-
-  for (const entry of entries) {
-    const dir = path.join(phasesDir, entry.name);
-    const plans = findFiles(dir, /-PLAN\.md$/);
-    total += plans.length;
-
-    const summaries = findFiles(dir, /^SUMMARY-.*\.md$/);
-    for (const s of summaries) {
-      const content = fs.readFileSync(path.join(dir, s), 'utf8');
-      if (/status:\s*["']?complete/i.test(content)) completed++;
-    }
-  }
-
-  return {
-    total,
-    completed,
-    percentage: total > 0 ? Math.round((completed / total) * 100) : 0
-  };
-}
-
-function output(data) {
-  process.stdout.write(JSON.stringify(data, null, 2));
-  process.exit(0);
-}
-
-function error(msg) {
-  process.stdout.write(JSON.stringify({ error: msg }));
-  process.exit(1);
-}
-
-/**
- * Write content to a file atomically: write to .tmp, backup original to .bak,
- * rename .tmp over original. On failure, restore from .bak if available.
- *
- * @param {string} filePath - Target file path
- * @param {string} content - Content to write
- * @returns {{success: boolean, error?: string}} Result
- */
-function atomicWrite(filePath, content) {
-  const tmpPath = filePath + '.tmp';
-  const bakPath = filePath + '.bak';
-
-  try {
-    // 1. Write to temp file
-    fs.writeFileSync(tmpPath, content, 'utf8');
-
-    // 2. Backup original if it exists
-    if (fs.existsSync(filePath)) {
-      try {
-        fs.copyFileSync(filePath, bakPath);
-      } catch (_e) {
-        // Backup failure is non-fatal — proceed with rename
-      }
-    }
-
-    // 3. Rename temp over original (atomic on most filesystems)
-    fs.renameSync(tmpPath, filePath);
-
-    return { success: true };
-  } catch (e) {
-    // Rename failed — try to restore from backup
-    try {
-      if (fs.existsSync(bakPath)) {
-        fs.copyFileSync(bakPath, filePath);
-      }
-    } catch (_restoreErr) {
-      // Restore also failed — nothing more we can do
-    }
-
-    // Clean up temp file if it still exists
-    try {
-      if (fs.existsSync(tmpPath)) {
-        fs.unlinkSync(tmpPath);
-      }
-    } catch (_cleanupErr) {
-      // Best-effort cleanup
-    }
-
-    return { success: false, error: e.message };
-  }
-}
-
-if (require.main === module || process.argv[1] === __filename) { main(); }
-module.exports = { parseStateMd, parseRoadmapMd, parseYamlFrontmatter, parseMustHaves, countMustHaves, stateLoad, stateCheckProgress, configLoad, configClearCache, configValidate, lockedFileUpdate, planIndex, determinePhaseStatus, findFiles, atomicWrite, tailLines, frontmatter, mustHavesCollect, phaseInfo, stateUpdate, roadmapUpdateStatus, roadmapUpdatePlans, updateLegacyStateField, updateFrontmatterField, updateTableRow, findRoadmapRow, resolveDepthProfile, DEPTH_PROFILE_DEFAULTS, historyAppend, historyLoad, VALID_STATUS_TRANSITIONS, validateStatusTransition };
+if (require.main === module || process.argv[1] === __filename) { main().catch(err => { process.stderr.write(err.message + '\n'); process.exit(1); }); }
+module.exports = { KNOWN_AGENTS, initExecutePhase, initPlanPhase, initQuick, initVerifyWork, initResume, initProgress, initStateBundle: stateBundle, stateBundle, statePatch, stateAdvancePlan, stateRecordMetric, stateRecordActivity, stateUpdateProgress, parseStateMd, parseRoadmapMd, parseYamlFrontmatter, parseMustHaves, countMustHaves, stateLoad, stateCheckProgress, configLoad, configClearCache, configValidate, lockedFileUpdate, planIndex, determinePhaseStatus, findFiles, atomicWrite, tailLines, frontmatter, mustHavesCollect, phaseInfo, stateUpdate, roadmapUpdateStatus, roadmapUpdatePlans, roadmapAnalyze, updateLegacyStateField, updateFrontmatterField, updateTableRow, findRoadmapRow, resolveDepthProfile, DEPTH_PROFILE_DEFAULTS, historyAppend, historyLoad, VALID_STATUS_TRANSITIONS, validateStatusTransition, writeActiveSkill, validateProject, phaseAdd, phaseRemove, phaseList, loadUserDefaults, saveUserDefaults, mergeUserDefaults, USER_DEFAULTS_PATH, todoList, todoGet, todoAdd, todoDone, migrate, spotCheck, referenceGet, milestoneStats, contextTriage, stalenessCheck, summaryGate, checkpointInit, checkpointUpdate, seedsMatch, ciPoll, rollbackPlan, sessionLoad, sessionSave, SESSION_ALLOWED_KEYS, claimAcquire, claimRelease, claimList, skillSectionGet, listSkillHeadings, stepVerify: _stepVerify, phaseAlternatives: _phaseAlternatives, prerequisiteAlternatives: _prereqAlternatives, configAlternatives: _configAlternatives, phaseComplete, phaseInsert };
+// NOTE: validateProject, phaseAdd, phaseRemove, phaseList were previously CLI-only (not exported).
+// They are now exported for testability. This is additive and backwards-compatible.