@sienklogic/plan-build-run 2.41.0 → 2.42.0

package/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to Plan-Build-Run will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.42.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.41.0...plan-build-run-v2.42.0) (2026-02-28)
+
+
+### Features
+
+* **48-02:** add localhost-only validation for local_llm.endpoint in configValidate ([511e038](https://github.com/SienkLogic/plan-build-run/commit/511e038bc5821518d261ac49d3098ac8281970cd))
+* **48-02:** add persistent cross-process circuit breaker in lib/circuit-state.js ([85ee2fd](https://github.com/SienkLogic/plan-build-run/commit/85ee2fdb07ee9357c467d80f2ec02b6af2e0378e))
+* **48-02:** replace busy-wait loop with Atomics.wait in lockedFileUpdate ([0099aa2](https://github.com/SienkLogic/plan-build-run/commit/0099aa2b172b7705bba2c834be8601d225667b10))
+
+
+### Bug Fixes
+
+* **48-03:** remove unused imports causing ESLint failures in CI ([f459004](https://github.com/SienkLogic/plan-build-run/commit/f4590048e4847e802ace067b47d10d9c865d0f21))
+* **48-03:** remove unused variable in run-hook.test.js to pass ESLint ([2b553b1](https://github.com/SienkLogic/plan-build-run/commit/2b553b1df752231f9e78246fe6f4d6326f872f87))
+
+
+### Documentation
+
+* **48-03:** add bootstrap documentation and drift-detection test for hooks.json ([d29c015](https://github.com/SienkLogic/plan-build-run/commit/d29c01524bdbc2b01741f4c634b8e3855a3fa0b0))
+
 ## [2.41.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.40.1...plan-build-run-v2.41.0) (2026-02-28)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sienklogic/plan-build-run",
-  "version": "2.41.0",
+  "version": "2.42.0",
   "description": "Plan it, Build it, Run it — structured development workflow for Claude Code",
   "keywords": [
     "claude-code",

package/plugins/copilot-pbr/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.41.0",
+  "version": "2.42.0",
   "description": "Plan-Build-Run — Structured development workflow for GitHub Copilot CLI. Solves context rot through disciplined agent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",

package/plugins/cursor-pbr/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.41.0",
+  "version": "2.42.0",
   "description": "Plan-Build-Run — Structured development workflow for Cursor. Solves context rot through disciplined subagent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",

package/plugins/pbr/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pbr",
-  "version": "2.41.0",
+  "version": "2.42.0",
   "description": "Plan-Build-Run — Structured development workflow for Claude Code. Solves context rot through disciplined subagent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",

package/plugins/pbr/hooks/hooks.json

@@ -1,6 +1,11 @@
 {
   "$schema": "../scripts/hooks-schema.json",
   "description": "Plan-Build-Run workflow hooks for state tracking, validation, and auto-continuation",
+  "$bootstrap": {
+    "why": "Claude Code expands ${CLAUDE_PLUGIN_ROOT} before shell execution. On Windows+Git Bash this produces an MSYS path like /d/Repos/... which Node.js cannot resolve. The one-liner converts /d/Repos/... to D:\\Repos\\... before requiring run-hook.js.",
+    "pattern": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'scripts','run-hook.js'))\" {script}.js",
+    "run-hook": "scripts/run-hook.js handles MSYS path fix, argv normalization, and require() isolation"
+  },
   "hooks": {
     "SessionStart": [
       {

package/plugins/pbr/scripts/lib/circuit-state.js

@@ -0,0 +1,134 @@
+'use strict';
+
+/**
+ * lib/circuit-state.js — Persistent cross-process circuit breaker state.
+ *
+ * Stores circuit state in .planning/logs/local-llm-circuit.json so multiple
+ * hook processes share the same failure counts across process boundaries.
+ *
+ * Entries expire after STALE_TTL_MS (30 minutes) since the last failure.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const STALE_TTL_MS = 30 * 60 * 1000; // 30 minutes
+const STATE_FILENAME = 'local-llm-circuit.json';
+
+/**
+ * Returns the path to the circuit state file.
+ * @param {string} planningDir
+ * @returns {string}
+ */
+function _statePath(planningDir) {
+  return path.join(planningDir, 'logs', STATE_FILENAME);
+}
+
+/**
+ * Load circuit state from disk. Returns an empty object on any error.
+ * Prunes entries whose last_failure timestamp is older than STALE_TTL_MS.
+ *
+ * @param {string} planningDir - Path to .planning directory
+ * @returns {object} Map of operationType -> { failures, disabled, last_failure }
+ */
+function loadCircuitState(planningDir) {
+  const statePath = _statePath(planningDir);
+  let raw = {};
+  try {
+    if (!fs.existsSync(statePath)) return {};
+    raw = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+  } catch (_e) {
+    return {};
+  }
+
+  const now = Date.now();
+  const pruned = {};
+  for (const [opType, entry] of Object.entries(raw)) {
+    if (entry && typeof entry.last_failure === 'number') {
+      if (now - entry.last_failure < STALE_TTL_MS) {
+        pruned[opType] = entry;
+      }
+      // else: stale — drop it
+    }
+  }
+  return pruned;
+}
+
+/**
+ * Atomically write circuit state to disk.
+ * Uses a temp-file + rename pattern to avoid partial writes.
+ *
+ * @param {string} planningDir - Path to .planning directory
+ * @param {object} state - State object to write
+ */
+function saveCircuitState(planningDir, state) {
+  const logsDir = path.join(planningDir, 'logs');
+  try {
+    if (!fs.existsSync(logsDir)) {
+      fs.mkdirSync(logsDir, { recursive: true });
+    }
+    const statePath = _statePath(planningDir);
+    const tmpPath = statePath + '.tmp.' + process.pid;
+    fs.writeFileSync(tmpPath, JSON.stringify(state, null, 2), 'utf8');
+    fs.renameSync(tmpPath, statePath);
+  } catch (_e) {
+    // Best-effort — never crash the calling hook
+  }
+}
+
+/**
+ * Returns true if the circuit is open (disabled) for the given operation type,
+ * based on persistent state.
+ *
+ * @param {string} planningDir
+ * @param {string} operationType
+ * @param {number} maxFailures
+ * @returns {boolean}
+ */
+function isDisabledPersistent(planningDir, operationType, maxFailures) {
+  const state = loadCircuitState(planningDir);
+  const entry = state[operationType];
+  if (!entry) return false;
+  return entry.disabled === true || entry.failures >= maxFailures;
+}
+
+/**
+ * Records a failure for the given operation type in persistent state.
+ * Marks the circuit disabled when maxFailures is reached.
+ *
+ * @param {string} planningDir
+ * @param {string} operationType
+ * @param {number} maxFailures
+ */
+function recordFailurePersistent(planningDir, operationType, maxFailures) {
+  const state = loadCircuitState(planningDir);
+  const entry = state[operationType] || { failures: 0, disabled: false, last_failure: 0 };
+  entry.failures += 1;
+  entry.last_failure = Date.now();
+  if (entry.failures >= maxFailures) {
+    entry.disabled = true;
+  }
+  state[operationType] = entry;
+  saveCircuitState(planningDir, state);
+}
+
+/**
+ * Resets the persistent circuit state for the given operation type.
+ *
+ * @param {string} planningDir
+ * @param {string} operationType
+ */
+function resetCircuitPersistent(planningDir, operationType) {
+  const state = loadCircuitState(planningDir);
+  delete state[operationType];
+  saveCircuitState(planningDir, state);
+}
+
+module.exports = {
+  loadCircuitState,
+  saveCircuitState,
+  isDisabledPersistent,
+  recordFailurePersistent,
+  resetCircuitPersistent,
+  STALE_TTL_MS
+};

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

@@ -92,6 +92,23 @@ function configValidate(preloadedConfig, planningDir) {
     warnings.push(`config.json schema is outdated. Run: node pbr-tools.js migrate`);
   }
 
+  // Local LLM endpoint must be localhost-only for security
+  if (config.local_llm && config.local_llm.enabled === true && config.local_llm.endpoint) {
+    try {
+      const parsed = new URL(config.local_llm.endpoint);
+      const hostname = parsed.hostname.toLowerCase();
+      const localhostNames = ['localhost', '127.0.0.1', '::1', '[::1]'];
+      if (!localhostNames.includes(hostname)) {
+        errors.push(
+          `local_llm.endpoint must be a localhost address (localhost, 127.0.0.1, or ::1). ` +
+          `Got: "${hostname}". Non-localhost endpoints are not supported for security reasons.`
+        );
+      }
+    } catch (_urlErr) {
+      errors.push(`local_llm.endpoint is not a valid URL: "${config.local_llm.endpoint}"`);
+    }
+  }
+
   // Semantic conflict detection — logical contradictions that pass schema validation
   // Clear contradictions -> errors; ambiguous/preference issues -> warnings
   if (config.mode === 'autonomous' && config.gates) {

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

@@ -395,9 +395,11 @@ function lockedFileUpdate(filePath, updateFn, opts = {}) {
           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)
+            try {
+              Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, waitMs);
+            } catch (_atomicsErr) {
+              const end = Date.now() + waitMs;
+              while (Date.now() < end) { /* last-resort fallback */ }
             }
             continue;
           }

package/plugins/pbr/scripts/lib/gates/advisories.js

@@ -0,0 +1,125 @@
+'use strict';
+
+/**
+ * Advisory checks for validate-task.
+ * These return warning strings rather than blocking the tool call.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { readActiveSkill } = require('./helpers');
+
+/**
+ * Advisory check: when pbr:debugger is spawned and .active-skill is 'debug',
+ * warn if .planning/debug/ directory does not exist.
+ * Returns a warning string or null.
+ * @param {object} data - hook data with tool_input
+ * @returns {string|null}
+ */
+function checkDebuggerAdvisory(data) {
+  const subagentType = data.tool_input?.subagent_type || '';
+  if (subagentType !== 'pbr:debugger') return null;
+
+  // Only advise when spawned from the debug skill
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+  const activeSkill = readActiveSkill(planningDir);
+  if (activeSkill !== 'debug') return null;
+
+  const debugDir = path.join(planningDir, 'debug');
+  if (!fs.existsSync(debugDir)) {
+    return 'Debugger advisory: .planning/debug/ does not exist. Create it before spawning the debugger so output has a target location.';
+  }
+  return null;
+}
+
+/**
+ * Advisory check: when pbr:executor is spawned in build context,
+ * warn if .checkpoint-manifest.json is missing from the phase directory.
+ * Returns a warning string or null.
+ * @param {object} data - hook data with tool_input
+ * @returns {string|null}
+ */
+function checkCheckpointManifest(data) {
+  const toolInput = data.tool_input || {};
+  const subagentType = toolInput.subagent_type || '';
+
+  if (subagentType !== 'pbr:executor') return null;
+
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+
+  const activeSkill = readActiveSkill(planningDir);
+  if (activeSkill !== 'build') return null;
+
+  // Find current phase dir
+  const stateFile = path.join(planningDir, 'STATE.md');
+  try {
+    const state = fs.readFileSync(stateFile, 'utf8');
+    const phaseMatch = state.match(/Phase:\s*(\d+)\s+of\s+\d+/);
+    if (!phaseMatch) return null;
+
+    const currentPhase = phaseMatch[1].padStart(2, '0');
+    const phasesDir = path.join(planningDir, 'phases');
+    if (!fs.existsSync(phasesDir)) return null;
+
+    const dirs = fs.readdirSync(phasesDir).filter(d => d.startsWith(currentPhase + '-'));
+    if (dirs.length === 0) return null;
+
+    const phaseDir = path.join(phasesDir, dirs[0]);
+    const manifestFile = path.join(phaseDir, '.checkpoint-manifest.json');
+    if (!fs.existsSync(manifestFile)) {
+      return 'Build advisory: .checkpoint-manifest.json not found in phase directory. The build skill should write this before spawning executors. To fix: Run /pbr:health to regenerate checkpoint manifest.';
+    }
+  } catch (_e) {
+    return null;
+  }
+
+  return null;
+}
+
+/**
+ * Advisory check: when any pbr:* agent is being spawned, warn if
+ * .planning/.active-skill doesn't exist. Without this file, all
+ * skill-specific enforcement is silently disabled.
+ * Returns a warning string or null.
+ * @param {object} data - hook data with tool_input
+ * @returns {string|null}
+ */
+function checkActiveSkillIntegrity(data) {
+  const toolInput = data.tool_input || {};
+  const subagentType = toolInput.subagent_type || '';
+
+  if (typeof subagentType !== 'string' || !subagentType.startsWith('pbr:')) return null;
+
+  // Advisory agents that run without an active skill context — exempt from .active-skill checks
+  const EXEMPT_AGENTS = ['pbr:researcher', 'pbr:synthesizer', 'pbr:audit', 'pbr:dev-sync', 'pbr:general'];
+  if (EXEMPT_AGENTS.includes(subagentType)) return null;
+
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+
+  // Only check if .planning/ exists (PBR project)
+  if (!fs.existsSync(planningDir)) return null;
+
+  const activeSkillFile = path.join(planningDir, '.active-skill');
+  if (!fs.existsSync(activeSkillFile)) {
+    return 'Active-skill integrity: .planning/.active-skill not found. Skill-specific enforcement is disabled. The invoking skill should write this file. To fix: Wait for the current skill to finish, or delete .planning/.active-skill if stale.';
+  }
+
+  // Stale lock detection: warn if .active-skill is older than 2 hours
+  try {
+    const stat = fs.statSync(activeSkillFile);
+    const ageMs = Date.now() - stat.mtimeMs;
+    const TWO_HOURS = 2 * 60 * 60 * 1000;
+    if (ageMs > TWO_HOURS) {
+      const ageHours = Math.round(ageMs / (60 * 60 * 1000));
+      const skill = fs.readFileSync(activeSkillFile, 'utf8').trim();
+      return `Active-skill integrity: .planning/.active-skill is ${ageHours}h old (skill: "${skill}"). This may be a stale lock from a crashed session. Run /pbr:health to diagnose, or delete .planning/.active-skill if the previous session is no longer running.`;
+    }
+  } catch (_e) { /* best-effort */ }
+
+  return null;
+}
+
+module.exports = { checkDebuggerAdvisory, checkCheckpointManifest, checkActiveSkillIntegrity };

package/plugins/pbr/scripts/lib/gates/build-dependency.js

@@ -0,0 +1,100 @@
+'use strict';
+
+/**
+ * Gate: build dependency verification check.
+ * When active skill is "build" and pbr:executor is spawned, verify
+ * that dependent phases (from ROADMAP.md) have VERIFICATION.md.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { readActiveSkill } = require('./helpers');
+
+/**
+ * Blocking check: when the active skill is "build" and an executor is being
+ * spawned, verify that dependent phases (from ROADMAP.md) have VERIFICATION.md.
+ * Returns { block: true, reason: "..." } if blocked, or null if OK.
+ * @param {object} data - hook data with tool_input
+ * @returns {{ block: boolean, reason: string }|null}
+ */
+function checkBuildDependencyGate(data) {
+  const toolInput = data.tool_input || {};
+  const subagentType = toolInput.subagent_type || '';
+
+  // Only gate pbr:executor
+  if (subagentType !== 'pbr:executor') return null;
+
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+
+  // Only gate when active skill is "build"
+  const activeSkill = readActiveSkill(planningDir);
+  if (activeSkill !== 'build') return null;
+
+  // Read STATE.md for current phase (as integer for roadmap matching)
+  let currentPhase;
+  try {
+    const state = fs.readFileSync(path.join(planningDir, 'STATE.md'), 'utf8');
+    const phaseMatch = state.match(/Phase:\s*(\d+)/);
+    if (!phaseMatch) return null;
+    currentPhase = parseInt(phaseMatch[1], 10);
+  } catch (_e) {
+    return null;
+  }
+
+  // Read ROADMAP.md, find current phase section, check dependencies
+  const roadmapFile = path.join(planningDir, 'ROADMAP.md');
+  try {
+    const roadmap = fs.readFileSync(roadmapFile, 'utf8');
+
+    // Find ### Phase N: section
+    const phaseRegex = new RegExp(`### Phase ${currentPhase}:[\\s\\S]*?(?=### Phase \\d|$)`);
+    const phaseSection = roadmap.match(phaseRegex);
+    if (!phaseSection) return null;
+
+    // Look for **Depends on:** line
+    const depMatch = phaseSection[0].match(/\*\*Depends on:\*\*\s*(.*)/);
+    if (!depMatch) return null;
+
+    const depLine = depMatch[1].trim();
+    if (!depLine || /^none$/i.test(depLine)) return null;
+
+    // Parse phase numbers from "Phase 1", "Phase 1, Phase 2", etc.
+    const depPhases = [];
+    const depRegex = /Phase\s+(\d+)/gi;
+    let match;
+    while ((match = depRegex.exec(depLine)) !== null) {
+      depPhases.push(parseInt(match[1], 10));
+    }
+
+    if (depPhases.length === 0) return null;
+
+    // Check each dependent phase has VERIFICATION.md
+    const phasesDir = path.join(planningDir, 'phases');
+    if (!fs.existsSync(phasesDir)) return null;
+
+    for (const depPhase of depPhases) {
+      const paddedPhase = String(depPhase).padStart(2, '0');
+      const pDirs = fs.readdirSync(phasesDir).filter(d => d.startsWith(paddedPhase + '-'));
+      if (pDirs.length === 0) {
+        return {
+          block: true,
+          reason: `Build dependency gate: dependent phase ${paddedPhase} lacks VERIFICATION.md.\n\nPhase ${currentPhase} depends on phase ${paddedPhase}, which must be verified before building can proceed.\n\nRun /pbr:review ${paddedPhase} to verify the dependency phase first.`
+        };
+      }
+      const hasVerification = fs.existsSync(path.join(phasesDir, pDirs[0], 'VERIFICATION.md'));
+      if (!hasVerification) {
+        return {
+          block: true,
+          reason: `Build dependency gate: dependent phase ${paddedPhase} lacks VERIFICATION.md.\n\nPhase ${currentPhase} depends on phase ${paddedPhase}, which must be verified before building can proceed.\n\nRun /pbr:review ${paddedPhase} to verify the dependency phase first.`
+        };
+      }
+    }
+  } catch (_e) {
+    return null;
+  }
+
+  return null;
+}
+
+module.exports = { checkBuildDependencyGate };

package/plugins/pbr/scripts/lib/gates/build-executor.js

@@ -0,0 +1,79 @@
+'use strict';
+
+/**
+ * Gate: build executor PLAN.md check.
+ * When active skill is "build" and pbr:executor is spawned, verify
+ * that a PLAN*.md exists in the current phase directory.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { readActiveSkill, readCurrentPhase } = require('./helpers');
+
+/**
+ * Blocking check: when the active skill is "build" and an executor is being
+ * spawned, verify that a PLAN*.md exists in the current phase directory.
+ * Returns { block: true, reason: "..." } if blocked, or null if OK.
+ * @param {object} data - hook data with tool_input
+ * @returns {{ block: boolean, reason: string }|null}
+ */
+function checkBuildExecutorGate(data) {
+  const toolInput = data.tool_input || {};
+  const subagentType = toolInput.subagent_type || '';
+
+  // Only gate pbr:executor
+  if (subagentType !== 'pbr:executor') return null;
+
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+
+  // Only gate when active skill is "build"
+  const activeSkill = readActiveSkill(planningDir);
+  if (activeSkill !== 'build') return null;
+
+  // Read STATE.md for current phase
+  const currentPhase = readCurrentPhase(planningDir);
+  if (!currentPhase) return null;
+
+  try {
+    const phasesDir = path.join(planningDir, 'phases');
+    if (!fs.existsSync(phasesDir)) {
+      return {
+        block: true,
+        reason: 'Cannot spawn executor: .planning/phases/ directory does not exist.\n\nThe build skill requires a phases directory with at least one PLAN.md before an executor can run.\n\nRun /pbr:plan {N} to create plans first.'
+      };
+    }
+
+    const dirs = fs.readdirSync(phasesDir).filter(d => d.startsWith(currentPhase + '-'));
+    if (dirs.length === 0) {
+      return {
+        block: true,
+        reason: `Cannot spawn executor: no phase directory found for phase ${currentPhase}.\n\nThe build skill needs a phase directory (e.g., .planning/phases/${currentPhase}-slug/) containing PLAN.md files.\n\nRun /pbr:plan ${currentPhase} to create plans first.`
+      };
+    }
+
+    const phaseDir = path.join(phasesDir, dirs[0]);
+    const files = fs.readdirSync(phaseDir);
+    const hasPlan = files.some(f => {
+      if (!/^PLAN.*\.md$/i.test(f)) return false;
+      try {
+        return fs.statSync(path.join(phaseDir, f)).size > 0;
+      } catch (_e) {
+        return false;
+      }
+    });
+
+    if (!hasPlan) {
+      return {
+        block: true,
+        reason: `Cannot spawn executor: no PLAN.md found in .planning/phases/${dirs[0]}/.\n\nThe phase directory exists but contains no PLAN.md files. The executor needs at least one non-empty PLAN.md to work from.\n\nRun /pbr:plan ${currentPhase} to create plans first.`
+      };
+    }
+  } catch (_e) {
+    return null;
+  }
+
+  return null;
+}
+
+module.exports = { checkBuildExecutorGate };

package/plugins/pbr/scripts/lib/gates/helpers.js

@@ -0,0 +1,62 @@
+'use strict';
+
+/**
+ * Shared helpers for gate modules.
+ * Centralizes repeated .active-skill reads and STATE.md phase parsing.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Read the current .active-skill value.
+ * Returns the trimmed string, or null if the file doesn't exist or can't be read.
+ * @param {string} planningDir - path to .planning directory
+ * @returns {string|null}
+ */
+function readActiveSkill(planningDir) {
+  try {
+    return fs.readFileSync(path.join(planningDir, '.active-skill'), 'utf8').trim();
+  } catch (_e) {
+    return null;
+  }
+}
+
+/**
+ * Parse STATE.md for the current phase string (zero-padded, e.g. "01").
+ * Returns the padded phase string, or null if not found.
+ * @param {string} planningDir - path to .planning directory
+ * @returns {string|null}
+ */
+function readCurrentPhase(planningDir) {
+  try {
+    const state = fs.readFileSync(path.join(planningDir, 'STATE.md'), 'utf8');
+    const phaseMatch = state.match(/Phase:\s*(\d+)/);
+    if (!phaseMatch) return null;
+    return phaseMatch[1].padStart(2, '0');
+  } catch (_e) {
+    return null;
+  }
+}
+
+/**
+ * Parse STATE.md for the current phase as an integer.
+ * Checks frontmatter current_phase first, then falls back to body Phase: line.
+ * Returns the integer, or null if not found.
+ * @param {string} planningDir - path to .planning directory
+ * @returns {number|null}
+ */
+function readCurrentPhaseInt(planningDir) {
+  try {
+    const state = fs.readFileSync(path.join(planningDir, 'STATE.md'), 'utf8');
+    const fmMatch = state.match(/current_phase:\s*(\d+)/);
+    if (fmMatch) return parseInt(fmMatch[1], 10);
+    const bodyMatch = state.match(/Phase:\s*(\d+)/);
+    if (bodyMatch) return parseInt(bodyMatch[1], 10);
+    return null;
+  } catch (_e) {
+    return null;
+  }
+}
+
+module.exports = { readActiveSkill, readCurrentPhase, readCurrentPhaseInt };