@sienklogic/plan-build-run 2.41.0 → 2.42.0

package/plugins/pbr/scripts/lib/gates/milestone-complete.js

@@ -0,0 +1,120 @@
+'use strict';
+
+/**
+ * Gate: milestone complete verification check.
+ * When active skill is "milestone" and a general/planner agent is spawned
+ * for a "complete" operation, verify all milestone phases have VERIFICATION.md.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { readActiveSkill, readCurrentPhaseInt } = require('./helpers');
+
+/**
+ * Parse VERIFICATION.md frontmatter to extract status field.
+ * Returns the status string or 'unknown' if not parseable.
+ * @param {string} filePath - path to VERIFICATION.md
+ * @returns {string}
+ */
+function getVerificationStatus(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!fmMatch) return 'unknown';
+    const statusMatch = fmMatch[1].match(/^status:\s*(\S+)/m);
+    return statusMatch ? statusMatch[1] : 'unknown';
+  } catch (_e) {
+    return 'unknown';
+  }
+}
+
+/**
+ * Blocking check: when the active skill is "milestone" and a general/planner agent
+ * is being spawned for a "complete" operation, verify all milestone phases 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 checkMilestoneCompleteGate(data) {
+  const toolInput = data.tool_input || {};
+  const subagentType = toolInput.subagent_type || '';
+  const description = toolInput.description || '';
+
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+
+  // Only gate when active skill is "milestone"
+  const activeSkill = readActiveSkill(planningDir);
+  if (activeSkill !== 'milestone') return null;
+
+  // Only gate pbr:general and pbr:planner
+  if (subagentType !== 'pbr:general' && subagentType !== 'pbr:planner') return null;
+
+  // Only gate "complete" operations
+  if (!/complete/i.test(description)) return null;
+
+  // Read STATE.md for current phase
+  const currentPhase = readCurrentPhaseInt(planningDir);
+  if (!currentPhase) return null;
+
+  // Read ROADMAP.md and find the milestone containing the current phase
+  const roadmapFile = path.join(planningDir, 'ROADMAP.md');
+  try {
+    const roadmap = fs.readFileSync(roadmapFile, 'utf8');
+
+    // Split into milestone sections
+    const milestoneSections = roadmap.split(/^## Milestone:/m).slice(1);
+
+    for (const section of milestoneSections) {
+      // Parse phase numbers from table rows
+      const phaseNumbers = [];
+      const tableRowRegex = /^\|\s*(\d+)\s*\|/gm;
+      let match;
+      while ((match = tableRowRegex.exec(section)) !== null) {
+        phaseNumbers.push(parseInt(match[1], 10));
+      }
+
+      // Check if current phase is in this milestone
+      if (!phaseNumbers.includes(currentPhase)) continue;
+
+      // Found the right milestone — check all phases have VERIFICATION.md
+      const phasesDir = path.join(planningDir, 'phases');
+      if (!fs.existsSync(phasesDir)) return null;
+
+      for (const phaseNum of phaseNumbers) {
+        const paddedPhase = String(phaseNum).padStart(2, '0');
+        const pDirs = fs.readdirSync(phasesDir).filter(d => d.startsWith(paddedPhase + '-'));
+        if (pDirs.length === 0) {
+          return {
+            block: true,
+            reason: `Milestone complete gate: phase ${paddedPhase} directory not found.\n\nAll milestone phases must exist and have a passing VERIFICATION.md before the milestone can be completed.\n\nRun /pbr:review ${paddedPhase} to verify the phase (it must reach status: passed).`
+          };
+        }
+        const verificationFile = path.join(phasesDir, pDirs[0], 'VERIFICATION.md');
+        const hasVerification = fs.existsSync(verificationFile);
+        if (!hasVerification) {
+          return {
+            block: true,
+            reason: `Milestone complete gate: phase ${paddedPhase} (${pDirs[0]}) lacks VERIFICATION.md.\n\nAll milestone phases must have a passing VERIFICATION.md before the milestone can be completed.\n\nRun /pbr:review ${paddedPhase} to verify the phase (it must reach status: passed).`
+          };
+        }
+        const verStatus = getVerificationStatus(verificationFile);
+        if (verStatus === 'gaps_found') {
+          return {
+            block: true,
+            reason: `Milestone complete gate: phase ${paddedPhase} VERIFICATION.md has status: gaps_found.\n\nAll gaps must be closed before the milestone can be completed. The verifier found issues that need resolution.\n\nRun /pbr:review ${paddedPhase} to close gaps (phase must reach status: passed).`
+          };
+        }
+      }
+
+      // All phases verified
+      return null;
+    }
+  } catch (_e) {
+    return null;
+  }
+
+  return null;
+}
+
+module.exports = { checkMilestoneCompleteGate, getVerificationStatus };

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

@@ -0,0 +1,36 @@
+'use strict';
+
+/**
+ * Gate: plan skill executor block.
+ * The plan skill should never spawn executors.
+ */
+
+const path = require('path');
+const { readActiveSkill } = require('./helpers');
+
+/**
+ * Blocking check: when the active skill is "plan", block executor spawning.
+ * 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 checkPlanExecutorGate(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');
+
+  const activeSkill = readActiveSkill(planningDir);
+  if (activeSkill !== 'plan') return null;
+
+  return {
+    block: true,
+    reason: 'Plan skill cannot spawn executors.\n\nThe plan skill creates plans; the build skill executes them. Spawning an executor from the plan skill violates the separation of concerns.\n\nRun /pbr:build to execute plans instead.'
+  };
+}
+
+module.exports = { checkPlanExecutorGate };

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

@@ -0,0 +1,76 @@
+'use strict';
+
+/**
+ * Gate: quick executor PLAN.md check.
+ * When active skill is "quick" and pbr:executor is spawned, verify
+ * that at least one .planning/quick/{NNN}-{slug}/PLAN.md exists.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { readActiveSkill } = require('./helpers');
+
+/**
+ * Blocking check: when the active skill is "quick" and an executor is being
+ * spawned, verify that at least one .planning/quick/{NNN}-{slug}/PLAN.md exists.
+ * Returns { block: true, reason: "..." } if the executor should be blocked,
+ * or null if it's OK to proceed.
+ * @param {object} data - hook data with tool_input
+ * @returns {{ block: boolean, reason: string }|null}
+ */
+function checkQuickExecutorGate(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 "quick"
+  const activeSkill = readActiveSkill(planningDir);
+  if (activeSkill !== 'quick') return null;
+
+  // Check for any PLAN.md in .planning/quick/*/
+  const quickDir = path.join(planningDir, 'quick');
+  if (!fs.existsSync(quickDir)) {
+    return {
+      block: true,
+      reason: 'Cannot spawn executor: .planning/quick/ directory does not exist.\n\nThe quick skill must create the task directory and PLAN.md before an executor can run (Steps 4-6).\n\nRe-run /pbr:quick to create the quick task directory and PLAN.md.'
+    };
+  }
+
+  try {
+    const dirs = fs.readdirSync(quickDir).filter(d => {
+      return /^\d{3}-/.test(d) && fs.statSync(path.join(quickDir, d)).isDirectory();
+    });
+
+    // Look for the most recent quick task dir that has a PLAN.md
+    const hasPlan = dirs.some(d => {
+      const planFile = path.join(quickDir, d, 'PLAN.md');
+      try {
+        const stat = fs.statSync(planFile);
+        return stat.size > 0;
+      } catch (_e) {
+        return false;
+      }
+    });
+
+    if (!hasPlan) {
+      return {
+        block: true,
+        reason: 'Cannot spawn executor: no PLAN.md found in any .planning/quick/*/ directory.\n\nThe quick skill must write a non-empty PLAN.md inside .planning/quick/{NNN}-{slug}/ before an executor can run (Steps 4-6).\n\nRe-run /pbr:quick to create the quick task directory and PLAN.md.'
+      };
+    }
+  } catch (_e) {
+    return {
+      block: true,
+      reason: 'Cannot spawn executor: failed to read .planning/quick/ directory.\n\nThe directory exists but could not be read, possibly due to a permissions issue or filesystem error.\n\nRe-run /pbr:quick to recreate the quick task directory and PLAN.md.'
+    };
+  }
+
+  return null;
+}
+
+module.exports = { checkQuickExecutorGate };

package/plugins/pbr/scripts/lib/gates/review-planner.js

@@ -0,0 +1,61 @@
+'use strict';
+
+/**
+ * Gate: review planner VERIFICATION.md check.
+ * When active skill is "review" and pbr:planner is spawned, verify
+ * that a VERIFICATION.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 "review" and a planner is being
+ * spawned, verify that a VERIFICATION.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 checkReviewPlannerGate(data) {
+  const toolInput = data.tool_input || {};
+  const subagentType = toolInput.subagent_type || '';
+
+  // Only gate pbr:planner
+  if (subagentType !== 'pbr:planner') return null;
+
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+
+  // Only gate when active skill is "review"
+  const activeSkill = readActiveSkill(planningDir);
+  if (activeSkill !== 'review') 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 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 hasVerification = fs.existsSync(path.join(phaseDir, 'VERIFICATION.md'));
+
+    if (!hasVerification) {
+      return {
+        block: true,
+        reason: 'Review planner gate: cannot spawn planner without VERIFICATION.md.\n\nGap closure requires an existing VERIFICATION.md to identify which gaps need closing. Without it, the planner has no input.\n\nRun /pbr:review {N} to create VERIFICATION.md first.'
+      };
+    }
+  } catch (_e) {
+    return null;
+  }
+
+  return null;
+}
+
+module.exports = { checkReviewPlannerGate };

package/plugins/pbr/scripts/lib/gates/review-verifier.js

@@ -0,0 +1,69 @@
+'use strict';
+
+/**
+ * Gate: review verifier SUMMARY.md check.
+ * When active skill is "review" and pbr:verifier is spawned, verify
+ * that a SUMMARY*.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 "review" and a verifier is being
+ * spawned, verify that a SUMMARY*.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 checkReviewVerifierGate(data) {
+  const toolInput = data.tool_input || {};
+  const subagentType = toolInput.subagent_type || '';
+
+  // Only gate pbr:verifier
+  if (subagentType !== 'pbr:verifier') return null;
+
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+
+  // Only gate when active skill is "review"
+  const activeSkill = readActiveSkill(planningDir);
+  if (activeSkill !== 'review') 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 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 files = fs.readdirSync(phaseDir);
+    const hasSummary = files.some(f => {
+      if (!/^SUMMARY/i.test(f)) return false;
+      try {
+        return fs.statSync(path.join(phaseDir, f)).size > 0;
+      } catch (_e) {
+        return false;
+      }
+    });
+
+    if (!hasSummary) {
+      return {
+        block: true,
+        reason: 'Review verifier gate: cannot spawn verifier without SUMMARY.md.\n\nThe verifier checks executor output against the plan. Without a SUMMARY.md, there is nothing to verify.\n\nRun /pbr:build {N} to create SUMMARY.md first.'
+      };
+    }
+  } catch (_e) {
+    return null;
+  }
+
+  return null;
+}
+
+module.exports = { checkReviewVerifierGate };

package/plugins/pbr/scripts/local-llm/client.js

@@ -1,6 +1,12 @@
 /* global fetch, AbortSignal, performance */
 'use strict';
 
+const {
+  isDisabledPersistent,
+  recordFailurePersistent,
+  resetCircuitPersistent
+} = require('../lib/circuit-state');
+
 // Circuit breaker: Map<operationType, { failures: number, disabled: boolean }>
 const circuitState = new Map();
 
@@ -109,6 +115,7 @@ function resetCircuit(operationType) {
  * @param {string} operationType - operation identifier for circuit breaker tracking
  * @param {object} [options={}] - optional parameters
  * @param {boolean} [options.logprobs] - if true, request logprobs from the API
+ * @param {string} [options.planningDir] - optional .planning directory for persistent circuit breaker state
  * @returns {Promise<{ content: string, latency_ms: number, tokens: number, logprobsData: Array<{token: string, logprob: number}>|null }>}
  */
 async function complete(config, prompt, operationType, options = {}) {
@@ -119,12 +126,19 @@ async function complete(config, prompt, operationType, options = {}) {
   const numCtx = (config.advanced && config.advanced.num_ctx) || 4096;
   const keepAlive = (config.advanced && config.advanced.keep_alive) || '30m';
   const maxFailures = (config.advanced && config.advanced.disable_after_failures) || 3;
+  const planningDir = options.planningDir || null;
 
+  // Check in-memory circuit first (fast path), then persistent state
   if (isDisabled(operationType, maxFailures)) {
     const err = new Error('Circuit open for operation: ' + operationType);
     err.type = 'circuit_open';
     throw err;
   }
+  if (planningDir && isDisabledPersistent(planningDir, operationType, maxFailures)) {
+    const err = new Error('Circuit open for operation: ' + operationType);
+    err.type = 'circuit_open';
+    throw err;
+  }
 
   const bodyObj = {
     model,
@@ -185,6 +199,7 @@ async function complete(config, prompt, operationType, options = {}) {
       if (isConnRefused) {
         // Server not running — no point retrying
         recordFailure(operationType, maxFailures);
+        if (planningDir) recordFailurePersistent(planningDir, operationType, maxFailures);
         throw err;
       }
 
@@ -197,18 +212,26 @@ async function complete(config, prompt, operationType, options = {}) {
       }
 
       // Final attempt or non-retryable error
-      if (attempt === totalAttempts - 1) {
-        recordFailure(operationType, maxFailures);
-      } else {
-        recordFailure(operationType, maxFailures);
-      }
+      recordFailure(operationType, maxFailures);
+      if (planningDir) recordFailurePersistent(planningDir, operationType, maxFailures);
       throw err;
     }
   }
 
   // Should not reach here, but guard anyway
   recordFailure(operationType, maxFailures);
+  if (planningDir) recordFailurePersistent(planningDir, operationType, maxFailures);
   throw lastErr;
 }
 
-module.exports = { tryParseJSON, categorizeError, isDisabled, recordFailure, resetCircuit, complete };
+module.exports = {
+  tryParseJSON,
+  categorizeError,
+  isDisabled,
+  recordFailure,
+  resetCircuit,
+  complete,
+  isDisabledPersistent,
+  recordFailurePersistent,
+  resetCircuitPersistent
+};

package/plugins/pbr/scripts/run-hook.js

@@ -60,7 +60,10 @@ if (invokedViaEval) {
 
 // When required as a module from -e bootstrap, export a runner function
 if (typeof module !== 'undefined' && module.exports) {
+  const BOOTSTRAP_SNIPPET = "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'))\"";
   module.exports = runScript;
+  module.exports.BOOTSTRAP_SNIPPET = BOOTSTRAP_SNIPPET;
+  module.exports.runScript = runScript;
 }
 
 // If we have a script name, run it immediately