@sienklogic/plan-build-run 2.11.0 → 2.12.1

package/plugins/pbr/scripts/lib/gates/inline-execution.js

@@ -0,0 +1,185 @@
+'use strict';
+
+/**
+ * Gate: inline execution decision.
+ * Determines whether a plan can be executed inline (in the orchestrator's
+ * context) rather than spawning a Task() subagent.
+ *
+ * Conditions for inline execution:
+ *   1. config.workflow.inline_execution is truthy
+ *   2. contextPct < config.workflow.inline_context_cap_pct (HARD CAP, checked first)
+ *   3. Task count <= config.workflow.inline_max_tasks
+ *   4. ALL tasks have complexity="simple"
+ */
+
+const fs = require('fs');
+
+const DEFAULT_MAX_TASKS = 2;
+const DEFAULT_CONTEXT_CAP_PCT = 40;
+const DEFAULT_MAX_FILES = 5;
+const DEFAULT_MAX_LINES = 50;
+
+// Lines-per-task estimation by complexity
+const LINES_PER_COMPLEXITY = {
+  simple: 20,
+  medium: 80,
+  complex: 200,
+  unknown: 100
+};
+
+/**
+ * Parse plan content string to extract task metadata.
+ * Returns array of { id, complexity, name } objects.
+ * @param {string} planContent - raw plan file content
+ * @returns {Array<{ id: string, complexity: string, name: string }>}
+ */
+function parsePlanTasks(planContent) {
+  const tasks = [];
+  // Match <task ...> opening tags and extract attributes
+  const taskRegex = /<task\s+([^>]*)>/g;
+  let match;
+
+  while ((match = taskRegex.exec(planContent)) !== null) {
+    const attrs = match[1];
+    const idMatch = attrs.match(/id="([^"]*)"/);
+    const complexityMatch = attrs.match(/complexity="([^"]*)"/);
+
+    // Extract name from <name>...</name> after this task tag
+    const afterTag = planContent.slice(match.index);
+    const nameMatch = afterTag.match(/<name>([\s\S]*?)<\/name>/);
+
+    tasks.push({
+      id: idMatch ? idMatch[1] : '',
+      complexity: complexityMatch ? complexityMatch[1] : 'unknown',
+      name: nameMatch ? nameMatch[1].trim() : ''
+    });
+  }
+
+  return tasks;
+}
+
+/**
+ * Parse plan content to extract YAML frontmatter fields.
+ * Returns an object with at least `files_modified` (array of strings).
+ * @param {string} planContent - raw plan file content
+ * @returns {{ files_modified: string[] }}
+ */
+function parsePlanFrontmatter(planContent) {
+  const result = { files_modified: [] };
+  const fmMatch = planContent.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!fmMatch) return result;
+
+  const fm = fmMatch[1];
+  // Extract files_modified array (YAML list format)
+  const filesSection = fm.match(/files_modified:\s*\n((?:\s+-\s+.*\n?)*)/);
+  if (filesSection) {
+    const items = filesSection[1].match(/^\s+-\s+"?([^"\n]+)"?\s*$/gm);
+    if (items) {
+      result.files_modified = items.map(line => {
+        const m = line.match(/^\s+-\s+"?([^"\n]+?)"?\s*$/);
+        return m ? m[1] : '';
+      }).filter(Boolean);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Decide whether a plan should be executed inline or via Task() subagent.
+ *
+ * @param {string} planPath - absolute path to the PLAN.md file
+ * @param {object} config - project config object with workflow.* properties
+ * @param {number} contextPct - current context usage percentage (0-100)
+ * @returns {{ inline: boolean, reason?: string, taskCount?: number, complexity?: string }}
+ */
+function shouldInlineExecution(planPath, config, contextPct) {
+  const workflow = (config && config.workflow) || {};
+  const features = (config && config.features) || {};
+
+  // Feature toggle check (independent of workflow.inline_execution)
+  if (features.inline_simple_tasks === false) {
+    return { inline: false, reason: 'feature disabled' };
+  }
+
+  // Check if inline execution is enabled
+  if (!workflow.inline_execution) {
+    return { inline: false, reason: 'inline_execution disabled' };
+  }
+
+  const capPct = typeof workflow.inline_context_cap_pct === 'number'
+    ? workflow.inline_context_cap_pct
+    : DEFAULT_CONTEXT_CAP_PCT;
+  const maxTasks = typeof workflow.inline_max_tasks === 'number'
+    ? workflow.inline_max_tasks
+    : DEFAULT_MAX_TASKS;
+
+  // HARD CAP: context budget check runs FIRST, before other conditions
+  if (contextPct >= capPct) {
+    return { inline: false, reason: 'context budget exceeded cap' };
+  }
+
+  // Read and parse plan file
+  let planContent;
+  try {
+    planContent = fs.readFileSync(planPath, 'utf8');
+  } catch (_e) {
+    return { inline: false, reason: 'cannot read plan file' };
+  }
+
+  const tasks = parsePlanTasks(planContent);
+
+  // Check task count
+  if (tasks.length > maxTasks) {
+    return {
+      inline: false,
+      reason: `task count ${tasks.length} exceeds max ${maxTasks}`
+    };
+  }
+
+  // Check all tasks are simple complexity
+  const nonSimple = tasks.filter(t => t.complexity !== 'simple');
+  if (nonSimple.length > 0) {
+    return {
+      inline: false,
+      reason: `non-simple complexity: ${nonSimple.map(t => t.id + '=' + t.complexity).join(', ')}`
+    };
+  }
+
+  // File count check from frontmatter
+  const frontmatter = parsePlanFrontmatter(planContent);
+  const maxFiles = typeof workflow.inline_max_files === 'number'
+    ? workflow.inline_max_files
+    : DEFAULT_MAX_FILES;
+  const fileCount = frontmatter.files_modified.length;
+  if (fileCount > maxFiles) {
+    return {
+      inline: false,
+      reason: `file count ${fileCount} exceeds max ${maxFiles}`
+    };
+  }
+
+  // Line estimation check from task complexity
+  const maxLines = typeof workflow.inline_max_lines === 'number'
+    ? workflow.inline_max_lines
+    : DEFAULT_MAX_LINES;
+  const estimatedLines = tasks.reduce((sum, t) => {
+    return sum + (LINES_PER_COMPLEXITY[t.complexity] || LINES_PER_COMPLEXITY.unknown);
+  }, 0);
+  if (estimatedLines > maxLines) {
+    return {
+      inline: false,
+      reason: `estimated lines ${estimatedLines} exceeds max ${maxLines}`
+    };
+  }
+
+  return {
+    inline: true,
+    taskCount: tasks.length,
+    complexity: 'simple',
+    fileCount,
+    estimatedLines
+  };
+}
+
+module.exports = { shouldInlineExecution, parsePlanTasks, parsePlanFrontmatter };

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

@@ -0,0 +1,136 @@
+'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));
+      }
+
+      // Fallback: parse from **Phases:** line or ### Phase NN: headings
+      if (phaseNumbers.length === 0) {
+        const phasesLineMatch = section.match(/\*\*Phases:\*\*\s*([\d,\s-]+)/);
+        if (phasesLineMatch) {
+          const nums = phasesLineMatch[1].match(/\d+/g);
+          if (nums) nums.forEach(n => phaseNumbers.push(parseInt(n, 10)));
+        }
+      }
+      if (phaseNumbers.length === 0) {
+        const headingRegex = /^###\s+Phase\s+(\d+):/gm;
+        let hMatch;
+        while ((hMatch = headingRegex.exec(section)) !== null) {
+          phaseNumbers.push(parseInt(hMatch[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/milestone-summary.js

@@ -0,0 +1,119 @@
+'use strict';
+
+/**
+ * Gate: milestone complete SUMMARY.md check.
+ * When active skill is "milestone" and a general/planner agent is spawned
+ * for a "complete" operation, verify all milestone phases have SUMMARY.md.
+ *
+ * This mirrors milestone-complete.js (which checks VERIFICATION.md) to
+ * close the enforcement gap where SUMMARY.md was only advisory.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { readActiveSkill, readCurrentPhaseInt } = require('./helpers');
+
+/**
+ * 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 SUMMARY.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 checkMilestoneSummaryGate(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));
+      }
+
+      // Fallback: parse from **Phases:** line or ### Phase NN: headings
+      if (phaseNumbers.length === 0) {
+        const phasesLineMatch = section.match(/\*\*Phases:\*\*\s*([\d,\s-]+)/);
+        if (phasesLineMatch) {
+          const nums = phasesLineMatch[1].match(/\d+/g);
+          if (nums) nums.forEach(n => phaseNumbers.push(parseInt(n, 10)));
+        }
+      }
+      if (phaseNumbers.length === 0) {
+        const headingRegex = /^###\s+Phase\s+(\d+):/gm;
+        let hMatch;
+        while ((hMatch = headingRegex.exec(section)) !== null) {
+          phaseNumbers.push(parseInt(hMatch[1], 10));
+        }
+      }
+
+      // Check if current phase is in this milestone
+      if (!phaseNumbers.includes(currentPhase)) continue;
+
+      // Found the right milestone — check all phases have SUMMARY.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) continue; // Phase dir missing is caught by milestone-complete gate
+
+        const phaseDir = path.join(phasesDir, pDirs[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: `Milestone SUMMARY gate: phase ${paddedPhase} (${pDirs[0]}) lacks SUMMARY.md.\n\nAll milestone phases must have SUMMARY.md before the milestone can be completed. This file is created by the executor agent during /pbr:build.\n\nRun /pbr:execute-phase ${paddedPhase} to build this phase and create SUMMARY.md.`
+          };
+        }
+      }
+
+      // All phases have SUMMARY.md
+      return null;
+    }
+  } catch (_e) {
+    return null;
+  }
+
+  return null;
+}
+
+module.exports = { checkMilestoneSummaryGate };

package/plugins/pbr/scripts/lib/gates/multi-phase-loader.js

@@ -0,0 +1,147 @@
+'use strict';
+
+/**
+ * Multi-Phase Plan Loader
+ *
+ * Loads plan files from the current phase and adjacent phases to provide
+ * cross-phase awareness to Task() agents. Respects the multi_phase_awareness
+ * feature toggle and max_phases_in_context workflow config.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Load plans from the current phase and adjacent phases.
+ *
+ * @param {string} planningDir - path to .planning directory
+ * @param {number} currentPhaseNum - current phase number (1-based)
+ * @param {object} config - project config object
+ * @returns {{ phases: Array<{ phaseNum: number, phaseName: string, plans: Array<{ planId: string, content: string }> }>, totalPlans: number, phasesLoaded: number }}
+ */
+function loadMultiPhasePlans(planningDir, currentPhaseNum, config) {
+  const phasesDir = path.join(planningDir, 'phases');
+
+  // List and sort all phase directories
+  const allPhaseDirs = listPhaseDirs(phasesDir);
+
+  // Determine which phases to load
+  const featureEnabled = !(config && config.features && config.features.multi_phase_awareness === false);
+  const maxPhases = (config && config.workflow && config.workflow.max_phases_in_context) || 3;
+
+  let selectedPhaseNums;
+  if (!featureEnabled) {
+    // Only current phase
+    selectedPhaseNums = [currentPhaseNum];
+  } else {
+    selectedPhaseNums = selectPhases(allPhaseDirs, currentPhaseNum, maxPhases);
+  }
+
+  // Load plans from selected phases
+  const phases = [];
+  let totalPlans = 0;
+
+  for (const phaseNum of selectedPhaseNums) {
+    const phaseInfo = allPhaseDirs.find(p => p.num === phaseNum);
+    if (!phaseInfo) continue;
+
+    const plans = loadPlansFromDir(phaseInfo.fullPath);
+    if (plans.length === 0) continue; // Skip phases with no plans
+
+    phases.push({
+      phaseNum: phaseInfo.num,
+      phaseName: phaseInfo.name,
+      plans,
+    });
+    totalPlans += plans.length;
+  }
+
+  return {
+    phases,
+    totalPlans,
+    phasesLoaded: phases.length,
+  };
+}
+
+/**
+ * List phase directories sorted by phase number.
+ * @param {string} phasesDir - path to .planning/phases/
+ * @returns {Array<{ num: number, name: string, fullPath: string }>}
+ */
+function listPhaseDirs(phasesDir) {
+  if (!fs.existsSync(phasesDir)) return [];
+
+  const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+  const dirs = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const match = entry.name.match(/^(\d+)-(.+)/);
+    if (!match) continue;
+    dirs.push({
+      num: parseInt(match[1], 10),
+      name: entry.name,
+      fullPath: path.join(phasesDir, entry.name),
+    });
+  }
+
+  return dirs.sort((a, b) => a.num - b.num);
+}
+
+/**
+ * Select up to maxPhases phases centered on currentPhaseNum.
+ * Always includes current. Then adds previous, next, then extends forward.
+ */
+function selectPhases(allPhaseDirs, currentPhaseNum, maxPhases) {
+  const allNums = allPhaseDirs.map(p => p.num);
+  if (allNums.length === 0) return [currentPhaseNum];
+
+  const selected = new Set();
+  selected.add(currentPhaseNum);
+
+  // Add previous phase
+  const prevPhases = allNums.filter(n => n < currentPhaseNum).sort((a, b) => b - a);
+  if (prevPhases.length > 0 && selected.size < maxPhases) {
+    selected.add(prevPhases[0]); // closest previous
+  }
+
+  // Add next phase
+  const nextPhases = allNums.filter(n => n > currentPhaseNum).sort((a, b) => a - b);
+  if (nextPhases.length > 0 && selected.size < maxPhases) {
+    selected.add(nextPhases[0]); // closest next
+  }
+
+  // If max > 3, extend forward
+  for (let i = 1; i < nextPhases.length && selected.size < maxPhases; i++) {
+    selected.add(nextPhases[i]);
+  }
+
+  // If still room, extend backward
+  for (let i = 1; i < prevPhases.length && selected.size < maxPhases; i++) {
+    selected.add(prevPhases[i]);
+  }
+
+  return Array.from(selected).sort((a, b) => a - b);
+}
+
+/**
+ * Load all PLAN-*.md files from a phase directory.
+ * @param {string} phaseDir - full path to phase directory
+ * @returns {Array<{ planId: string, content: string }>}
+ */
+function loadPlansFromDir(phaseDir) {
+  try {
+    const files = fs.readdirSync(phaseDir)
+      .filter(f => /^PLAN-\d+\.md$/i.test(f))
+      .sort();
+
+    return files.map(f => ({
+      planId: f.replace(/\.md$/i, ''),
+      content: fs.readFileSync(path.join(phaseDir, f), 'utf8'),
+    }));
+  } catch (_e) {
+    return [];
+  }
+}
+
+module.exports = { loadMultiPhasePlans };

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 };