@sienklogic/plan-build-run 2.1.0 → 2.1.1

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

@@ -0,0 +1,129 @@
+'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');
+const { resolveSessionPath } = require('../core');
+
+/**
+ * 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 sessionId = data.session_id || null;
+  const activeSkillFile = sessionId
+    ? resolveSessionPath(planningDir, '.active-skill', sessionId)
+    : path.join(planningDir, '.active-skill');
+  if (!fs.existsSync(activeSkillFile)) {
+    return 'Active-skill integrity: .active-skill not found for this session. Skill-specific enforcement is disabled. The invoking skill should write this file. To fix: Wait for the current skill to finish, or delete .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: .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 .active-skill if stale.`;
+    }
+  } 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:verify-work ${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:verify-work ${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-phase {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-phase ${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-phase ${currentPhase} to create plans first.`
+      };
+    }
+  } catch (_e) {
+    return null;
+  }
+
+  return null;
+}
+
+module.exports = { checkBuildExecutorGate };

package/plugins/pbr/scripts/lib/gates/doc-existence.js

@@ -0,0 +1,46 @@
+'use strict';
+
+/**
+ * Blocking gate: warns when a PBR project is missing PROJECT.md or REQUIREMENTS.md.
+ * These files are created by /pbr:new-project. If they are absent on a project that has
+ * STATE.md + ROADMAP.md, the user likely needs to run /pbr:new-project first.
+ * Returns { block: true, reason } when docs are missing.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { readActiveSkill } = require('./helpers');
+
+/**
+ * Check whether PROJECT.md and REQUIREMENTS.md exist in .planning/ for an
+ * established PBR project (one that already has STATE.md + ROADMAP.md).
+ *
+ * @param {object} _data - hook data (unused, kept for consistent gate signature)
+ * @returns {{ block: true, reason: string }|null}
+ */
+function checkDocExistence(_data) {
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+
+  // Only block for plan and build active skills
+  const activeSkill = readActiveSkill(planningDir);
+  if (activeSkill !== 'plan' && activeSkill !== 'build') return null;
+
+  // Only block if this is an established PBR project (has STATE.md + ROADMAP.md)
+  const statePath = path.join(planningDir, 'STATE.md');
+  const roadmapPath = path.join(planningDir, 'ROADMAP.md');
+  if (!fs.existsSync(statePath) || !fs.existsSync(roadmapPath)) return null;
+
+  const missing = [];
+  if (!fs.existsSync(path.join(planningDir, 'PROJECT.md'))) missing.push('PROJECT.md');
+  if (!fs.existsSync(path.join(planningDir, 'REQUIREMENTS.md'))) missing.push('REQUIREMENTS.md');
+
+  if (missing.length === 0) return null;
+
+  return {
+    block: true,
+    reason: `Missing planning documents: ${missing.join(', ')}.\n\nThese files are generated by /pbr:new-project and document project vision and requirements.\n\nRun /pbr:new-project to generate them, or create them manually from the templates at plugins/pbr/templates/.`
+  };
+}
+
+module.exports = { checkDocExistence };

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

@@ -0,0 +1,74 @@
+'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');
+const { resolveSessionPath } = require('../core');
+
+/**
+ * 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
+ * @param {string|null} [sessionId] - session identifier for session-scoped path
+ * @returns {string|null}
+ */
+function readActiveSkill(planningDir, sessionId) {
+  // Check .session.json first (consistent with check-subagent-output.js and log-subagent.js)
+  try {
+    const { sessionLoad } = require('../../pbr-tools');
+    const session = sessionLoad(planningDir, sessionId);
+    if (session && session.activeSkill) return session.activeSkill;
+  } catch (_e) { /* pbr-tools unavailable */ }
+  // Fall back to .active-skill file (session-scoped when sessionId available)
+  try {
+    const skillPath = sessionId
+      ? resolveSessionPath(planningDir, '.active-skill', sessionId)
+      : path.join(planningDir, '.active-skill');
+    return fs.readFileSync(skillPath, '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 };

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:verify-work ${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:verify-work ${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:verify-work ${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:execute-phase 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 };