@sienklogic/plan-build-run 2.19.0 → 2.19.1

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

@@ -0,0 +1,302 @@
+/**
+ * Frontmatter — YAML frontmatter parsing, serialization, and CRUD commands
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { safeReadFile, output, error } = require('./core');
+
+// ─── Parsing engine ───────────────────────────────────────────────────────────
+
+function extractFrontmatter(content) {
+  const frontmatter = {};
+  const match = content.match(/^---\n([\s\S]+?)\n---/);
+  if (!match) return frontmatter;
+
+  const yaml = match[1];
+  const lines = yaml.split('\n');
+
+  // Stack to track nested objects: [{obj, key, indent}]
+  // obj = object to write to, key = current key collecting array items, indent = indentation level
+  let stack = [{ obj: frontmatter, key: null, indent: -1 }];
+
+  for (const line of lines) {
+    // Skip empty lines
+    if (line.trim() === '') continue;
+
+    // Calculate indentation (number of leading spaces)
+    const indentMatch = line.match(/^(\s*)/);
+    const indent = indentMatch ? indentMatch[1].length : 0;
+
+    // Pop stack back to appropriate level
+    while (stack.length > 1 && indent <= stack[stack.length - 1].indent) {
+      stack.pop();
+    }
+
+    const current = stack[stack.length - 1];
+
+    // Check for key: value pattern
+    const keyMatch = line.match(/^(\s*)([a-zA-Z0-9_-]+):\s*(.*)/);
+    if (keyMatch) {
+      const key = keyMatch[2];
+      const value = keyMatch[3].trim();
+
+      if (value === '' || value === '[') {
+        // Key with no value or opening bracket — could be nested object or array
+        // We'll determine based on next lines, for now create placeholder
+        current.obj[key] = value === '[' ? [] : {};
+        current.key = null;
+        // Push new context for potential nested content
+        stack.push({ obj: current.obj[key], key: null, indent });
+      } else if (value.startsWith('[') && value.endsWith(']')) {
+        // Inline array: key: [a, b, c]
+        current.obj[key] = value.slice(1, -1).split(',').map(s => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
+        current.key = null;
+      } else {
+        // Simple key: value
+        current.obj[key] = value.replace(/^["']|["']$/g, '');
+        current.key = null;
+      }
+    } else if (line.trim().startsWith('- ')) {
+      // Array item
+      const itemValue = line.trim().slice(2).replace(/^["']|["']$/g, '');
+
+      // If current context is an empty object, convert to array
+      if (typeof current.obj === 'object' && !Array.isArray(current.obj) && Object.keys(current.obj).length === 0) {
+        // Find the key in parent that points to this object and convert it
+        const parent = stack.length > 1 ? stack[stack.length - 2] : null;
+        if (parent) {
+          for (const k of Object.keys(parent.obj)) {
+            if (parent.obj[k] === current.obj) {
+              parent.obj[k] = [itemValue];
+              current.obj = parent.obj[k];
+              break;
+            }
+          }
+        }
+      } else if (Array.isArray(current.obj)) {
+        current.obj.push(itemValue);
+      }
+    }
+  }
+
+  return frontmatter;
+}
+
+function reconstructFrontmatter(obj) {
+  const lines = [];
+  for (const [key, value] of Object.entries(obj)) {
+    if (value === null || value === undefined) continue;
+    if (Array.isArray(value)) {
+      if (value.length === 0) {
+        lines.push(`${key}: []`);
+      } else if (value.every(v => typeof v === 'string') && value.length <= 3 && value.join(', ').length < 60) {
+        lines.push(`${key}: [${value.join(', ')}]`);
+      } else {
+        lines.push(`${key}:`);
+        for (const item of value) {
+          lines.push(`  - ${typeof item === 'string' && (item.includes(':') || item.includes('#')) ? `"${item}"` : item}`);
+        }
+      }
+    } else if (typeof value === 'object') {
+      lines.push(`${key}:`);
+      for (const [subkey, subval] of Object.entries(value)) {
+        if (subval === null || subval === undefined) continue;
+        if (Array.isArray(subval)) {
+          if (subval.length === 0) {
+            lines.push(`  ${subkey}: []`);
+          } else if (subval.every(v => typeof v === 'string') && subval.length <= 3 && subval.join(', ').length < 60) {
+            lines.push(`  ${subkey}: [${subval.join(', ')}]`);
+          } else {
+            lines.push(`  ${subkey}:`);
+            for (const item of subval) {
+              lines.push(`    - ${typeof item === 'string' && (item.includes(':') || item.includes('#')) ? `"${item}"` : item}`);
+            }
+          }
+        } else if (typeof subval === 'object') {
+          lines.push(`  ${subkey}:`);
+          for (const [subsubkey, subsubval] of Object.entries(subval)) {
+            if (subsubval === null || subsubval === undefined) continue;
+            if (Array.isArray(subsubval)) {
+              if (subsubval.length === 0) {
+                lines.push(`    ${subsubkey}: []`);
+              } else {
+                lines.push(`    ${subsubkey}:`);
+                for (const item of subsubval) {
+                  lines.push(`      - ${item}`);
+                }
+              }
+            } else {
+              lines.push(`    ${subsubkey}: ${subsubval}`);
+            }
+          }
+        } else {
+          const sv = String(subval);
+          lines.push(`  ${subkey}: ${sv.includes(':') || sv.includes('#') ? `"${sv}"` : sv}`);
+        }
+      }
+    } else {
+      const sv = String(value);
+      if (sv.includes(':') || sv.includes('#') || sv.startsWith('[') || sv.startsWith('{')) {
+        lines.push(`${key}: "${sv}"`);
+      } else {
+        lines.push(`${key}: ${sv}`);
+      }
+    }
+  }
+  return lines.join('\n');
+}
+
+function spliceFrontmatter(content, newObj) {
+  const yamlStr = reconstructFrontmatter(newObj);
+  const match = content.match(/^---\n[\s\S]+?\n---/);
+  if (match) {
+    return `---\n${yamlStr}\n---` + content.slice(match[0].length);
+  }
+  return `---\n${yamlStr}\n---\n\n` + content;
+}
+
+function parseMustHavesBlock(content, blockName) {
+  // Extract a specific block from must_haves in raw frontmatter YAML
+  // Handles 3-level nesting: must_haves > artifacts/key_links > [{path, provides, ...}]
+  const fmMatch = content.match(/^---\n([\s\S]+?)\n---/);
+  if (!fmMatch) return [];
+
+  const yaml = fmMatch[1];
+  // Find the block (e.g., "truths:", "artifacts:", "key_links:")
+  const blockPattern = new RegExp(`^\\s{4}${blockName}:\\s*$`, 'm');
+  const blockStart = yaml.search(blockPattern);
+  if (blockStart === -1) return [];
+
+  const afterBlock = yaml.slice(blockStart);
+  const blockLines = afterBlock.split('\n').slice(1); // skip the header line
+
+  const items = [];
+  let current = null;
+
+  for (const line of blockLines) {
+    // Stop at same or lower indent level (non-continuation)
+    if (line.trim() === '') continue;
+    const indent = line.match(/^(\s*)/)[1].length;
+    if (indent <= 4 && line.trim() !== '') break; // back to must_haves level or higher
+
+    if (line.match(/^\s{6}-\s+/)) {
+      // New list item at 6-space indent
+      if (current) items.push(current);
+      current = {};
+      // Check if it's a simple string item
+      // Note: strings may contain ':' as part of file path notation (e.g., "src/app.js: >50 lines")
+      // Only treat as key-value if the part before ':' is a simple word (no dots, slashes, spaces)
+      const simpleMatch = line.match(/^\s{6}-\s+"?([^"]+)"?\s*$/);
+      const hasYamlKv = line.match(/^\s{6}-\s+(\w+):\s/);
+      if (simpleMatch && !hasYamlKv) {
+        current = simpleMatch[1];
+      } else {
+        // Key-value on same line as dash: "- path: value"
+        const kvMatch = line.match(/^\s{6}-\s+(\w+):\s*"?([^"]*)"?\s*$/);
+        if (kvMatch) {
+          current = {};
+          current[kvMatch[1]] = kvMatch[2];
+        }
+      }
+    } else if (current && typeof current === 'object') {
+      // Continuation key-value at 8+ space indent
+      const kvMatch = line.match(/^\s{8,}(\w+):\s*"?([^"]*)"?\s*$/);
+      if (kvMatch) {
+        const val = kvMatch[2];
+        // Try to parse as number
+        current[kvMatch[1]] = /^\d+$/.test(val) ? parseInt(val, 10) : val;
+      }
+      // Array items under a key
+      const arrMatch = line.match(/^\s{10,}-\s+"?([^"]+)"?\s*$/);
+      if (arrMatch) {
+        // Find the last key added and convert to array
+        const keys = Object.keys(current);
+        const lastKey = keys[keys.length - 1];
+        if (lastKey && !Array.isArray(current[lastKey])) {
+          current[lastKey] = current[lastKey] ? [current[lastKey]] : [];
+        }
+        if (lastKey) current[lastKey].push(arrMatch[1]);
+      }
+    }
+  }
+  if (current) items.push(current);
+
+  return items;
+}
+
+// ─── Frontmatter CRUD commands ────────────────────────────────────────────────
+
+const FRONTMATTER_SCHEMAS = {
+  plan: { required: ['phase', 'plan', 'type', 'wave', 'depends_on', 'files_modified', 'autonomous', 'must_haves'] },
+  summary: { required: ['phase', 'plan', 'subsystem', 'tags', 'duration', 'completed'] },
+  verification: { required: ['phase', 'verified', 'status', 'score'] },
+};
+
+function cmdFrontmatterGet(cwd, filePath, field, raw) {
+  if (!filePath) { error('file path required'); }
+  const fullPath = path.isAbsolute(filePath) ? filePath : path.join(cwd, filePath);
+  const content = safeReadFile(fullPath);
+  if (!content) { output({ error: 'File not found', path: filePath }, raw); return; }
+  const fm = extractFrontmatter(content);
+  if (field) {
+    const value = fm[field];
+    if (value === undefined) { output({ error: 'Field not found', field }, raw); return; }
+    output({ [field]: value }, raw, JSON.stringify(value));
+  } else {
+    output(fm, raw);
+  }
+}
+
+function cmdFrontmatterSet(cwd, filePath, field, value, raw) {
+  if (!filePath || !field || value === undefined) { error('file, field, and value required'); }
+  const fullPath = path.isAbsolute(filePath) ? filePath : path.join(cwd, filePath);
+  if (!fs.existsSync(fullPath)) { output({ error: 'File not found', path: filePath }, raw); return; }
+  const content = fs.readFileSync(fullPath, 'utf-8');
+  const fm = extractFrontmatter(content);
+  let parsedValue;
+  try { parsedValue = JSON.parse(value); } catch { parsedValue = value; }
+  fm[field] = parsedValue;
+  const newContent = spliceFrontmatter(content, fm);
+  fs.writeFileSync(fullPath, newContent, 'utf-8');
+  output({ updated: true, field, value: parsedValue }, raw, 'true');
+}
+
+function cmdFrontmatterMerge(cwd, filePath, data, raw) {
+  if (!filePath || !data) { error('file and data required'); }
+  const fullPath = path.isAbsolute(filePath) ? filePath : path.join(cwd, filePath);
+  if (!fs.existsSync(fullPath)) { output({ error: 'File not found', path: filePath }, raw); return; }
+  const content = fs.readFileSync(fullPath, 'utf-8');
+  const fm = extractFrontmatter(content);
+  let mergeData;
+  try { mergeData = JSON.parse(data); } catch { error('Invalid JSON for --data'); return; }
+  Object.assign(fm, mergeData);
+  const newContent = spliceFrontmatter(content, fm);
+  fs.writeFileSync(fullPath, newContent, 'utf-8');
+  output({ merged: true, fields: Object.keys(mergeData) }, raw, 'true');
+}
+
+function cmdFrontmatterValidate(cwd, filePath, schemaName, raw) {
+  if (!filePath || !schemaName) { error('file and schema required'); }
+  const schema = FRONTMATTER_SCHEMAS[schemaName];
+  if (!schema) { error(`Unknown schema: ${schemaName}. Available: ${Object.keys(FRONTMATTER_SCHEMAS).join(', ')}`); }
+  const fullPath = path.isAbsolute(filePath) ? filePath : path.join(cwd, filePath);
+  const content = safeReadFile(fullPath);
+  if (!content) { output({ error: 'File not found', path: filePath }, raw); return; }
+  const fm = extractFrontmatter(content);
+  const missing = schema.required.filter(f => fm[f] === undefined);
+  const present = schema.required.filter(f => fm[f] !== undefined);
+  output({ valid: missing.length === 0, missing, present, schema: schemaName }, raw, missing.length === 0 ? 'valid' : 'invalid');
+}
+
+module.exports = {
+  extractFrontmatter,
+  reconstructFrontmatter,
+  spliceFrontmatter,
+  parseMustHavesBlock,
+  FRONTMATTER_SCHEMAS,
+  cmdFrontmatterGet,
+  cmdFrontmatterSet,
+  cmdFrontmatterMerge,
+  cmdFrontmatterValidate,
+};

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,115 @@
+'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, isPlanSpeculative } = 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 depPhaseDir = path.join(phasesDir, pDirs[0]);
+      const depFiles = fs.readdirSync(depPhaseDir);
+
+      // If dep phase has only speculative plans, it is a future phase being planned ahead.
+      // Skip VERIFICATION check — speculative deps haven't been built yet and that's expected.
+      const hasNonSpeculativePlan = depFiles.some(f => {
+        if (!/^PLAN.*\.md$/i.test(f)) return false;
+        const fullPath = path.join(depPhaseDir, f);
+        try {
+          if (fs.statSync(fullPath).size === 0) return false;
+          return !isPlanSpeculative(fullPath);
+        } catch (_e) { return false; }
+      });
+      if (!hasNonSpeculativePlan) continue;
+
+      const hasVerification = fs.existsSync(path.join(depPhaseDir, '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,104 @@
+'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, isPlanSpeculative } = 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;
+
+  // Allow inline execution bypass — when .inline-active signal file exists,
+  // the build skill is executing tasks inline (no Task() needed)
+  try {
+    if (fs.existsSync(path.join(planningDir, '.inline-active'))) {
+      return null;
+    }
+  } catch (_e) { /* ignore */ }
+
+  // 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);
+
+    // Only count non-speculative plans. Speculative plans are created for future phases
+    // and must not block builds of the current target phase.
+    const actionablePlans = files.filter(f => {
+      if (!/^PLAN.*\.md$/i.test(f)) return false;
+      const fullPath = path.join(phaseDir, f);
+      try {
+        if (fs.statSync(fullPath).size === 0) return false;
+      } catch (_e) {
+        return false;
+      }
+      return !isPlanSpeculative(fullPath);
+    });
+
+    if (actionablePlans.length === 0) {
+      // No non-speculative plans found. Check whether any non-hidden files exist at all.
+      // An empty or speculative-only directory was created lazily for a future phase — allow.
+      const hasNonHiddenFiles = files.some(f => !f.startsWith('.'));
+      const hasSpeculativeOnly = files.some(f => {
+        if (!/^PLAN.*\.md$/i.test(f)) return false;
+        const fullPath = path.join(phaseDir, f);
+        try {
+          if (fs.statSync(fullPath).size === 0) return false;
+          return isPlanSpeculative(fullPath);
+        } catch (_e) { return false; }
+      });
+      if (!hasNonHiddenFiles || hasSpeculativeOnly) return null;
+      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 };