@sienklogic/plan-build-run 2.11.0 → 2.12.1

package/plugins/pbr/scripts/validate-task.js

@@ -20,19 +20,37 @@
 const fs = require('fs');
 const path = require('path');
 const { logHook } = require('./hook-logger');
+const { resolveConfig } = require('./local-llm/health');
+const { validateTask: llmValidateTask } = require('./local-llm/operations/validate-task');
+const { checkNonPbrAgent } = require('./enforce-pbr-workflow');
+const { KNOWN_AGENTS } = require('./pbr-tools');
+
+// Gate modules
+const { checkQuickExecutorGate } = require('./lib/gates/quick-executor');
+const { checkBuildExecutorGate } = require('./lib/gates/build-executor');
+const { checkPlanExecutorGate } = require('./lib/gates/plan-executor');
+const { checkReviewPlannerGate } = require('./lib/gates/review-planner');
+const { checkReviewVerifierGate } = require('./lib/gates/review-verifier');
+const { checkMilestoneCompleteGate, getVerificationStatus } = require('./lib/gates/milestone-complete');
+const { checkMilestoneSummaryGate } = require('./lib/gates/milestone-summary');
+const { checkBuildDependencyGate } = require('./lib/gates/build-dependency');
+const { checkDebuggerAdvisory, checkCheckpointManifest, checkActiveSkillIntegrity } = require('./lib/gates/advisories');
+const { checkDocExistence } = require('./lib/gates/doc-existence');
 
-const KNOWN_AGENTS = [
-  'researcher',
-  'planner',
-  'plan-checker',
-  'executor',
-  'verifier',
-  'integration-checker',
-  'debugger',
-  'codebase-mapper',
-  'synthesizer',
-  'general'
-];
+/**
+ * Load and resolve the local_llm config block from .planning/config.json.
+ * Returns a resolved config (always safe to use — disabled by default on error).
+ * @param {string} cwd - working directory to resolve .planning/config.json from
+ */
+function loadLocalLlmConfig(cwd) {
+  try {
+    const configPath = path.join(cwd, '.planning', 'config.json');
+    const parsed = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    return resolveConfig(parsed.local_llm);
+  } catch (_e) {
+    return resolveConfig(undefined);
+  }
+}
 
 const MAX_DESCRIPTION_LENGTH = 100;
 
@@ -49,7 +67,7 @@ function checkTask(data) {
 
   // Check description exists and is non-empty
   if (!description || (typeof description === 'string' && !description.trim())) {
-    warnings.push('Task() called without a description. Descriptions help track agent purpose.');
+    warnings.push('Task() called without a description. Descriptions are required for audit logging and skill enforcement. Add a short description (3-5 words), e.g.: "Build phase 3 executor".');
   } else if (typeof description === 'string') {
     // Check description length
     if (description.length > MAX_DESCRIPTION_LENGTH) {
@@ -82,610 +100,12 @@ function checkTask(data) {
   return warnings;
 }
 
-/**
- * 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.
- */
-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.cwd();
-  const planningDir = path.join(cwd, '.planning');
-  const activeSkillFile = path.join(planningDir, '.active-skill');
-
-  // Only gate when active skill is "quick"
-  try {
-    const activeSkill = fs.readFileSync(activeSkillFile, 'utf8').trim();
-    if (activeSkill !== 'quick') return null;
-  } catch (_e) {
-    // No .active-skill file — not in a quick task flow
-    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. ' +
-        'You must create the quick task directory and PLAN.md first (Steps 4-6). ' +
-        'To fix: Re-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. ' +
-          'You must create .planning/quick/{NNN}-{slug}/PLAN.md first (Steps 4-6). ' +
-          'To fix: Re-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. ' +
-        'To fix: Re-run /pbr:quick to create the quick task directory and PLAN.md.'
-    };
-  }
-
-  return null;
-}
-
-/**
- * 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.
- */
-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.cwd();
-  const planningDir = path.join(cwd, '.planning');
-  const activeSkillFile = path.join(planningDir, '.active-skill');
-
-  // Only gate when active skill is "build"
-  try {
-    const activeSkill = fs.readFileSync(activeSkillFile, 'utf8').trim();
-    if (activeSkill !== 'build') return null;
-  } catch (_e) {
-    return null;
-  }
-
-  // Read STATE.md for current phase
-  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 {
-        block: true,
-        reason: 'Cannot spawn executor: .planning/phases/ directory does not exist. To fix: Run /pbr:plan {N} to create plans first.'
-      };
-    }
-
-    const dirs = fs.readdirSync(phasesDir).filter(d => d.startsWith(currentPhase + '-'));
-    if (dirs.length === 0) {
-      return {
-        block: true,
-        reason: `Cannot spawn executor: no phase directory found for phase ${currentPhase}. To fix: Run /pbr:plan ${currentPhase} to create plans first.`
-      };
-    }
-
-    const phaseDir = path.join(phasesDir, dirs[0]);
-    const files = fs.readdirSync(phaseDir);
-    const hasPlan = files.some(f => {
-      if (!/^PLAN.*\.md$/i.test(f)) return false;
-      try {
-        return fs.statSync(path.join(phaseDir, f)).size > 0;
-      } catch (_e) {
-        return false;
-      }
-    });
-
-    if (!hasPlan) {
-      return {
-        block: true,
-        reason: `Cannot spawn executor: no PLAN.md found in .planning/phases/${dirs[0]}/. To fix: Run /pbr:plan ${currentPhase} to create plans first.`
-      };
-    }
-  } catch (_e) {
-    return null;
-  }
-
-  return null;
-}
-
-/**
- * Blocking check: when the active skill is "plan", block executor spawning.
- * The plan skill should never spawn executors.
- * Returns { block: true, reason: "..." } if blocked, or null if OK.
- */
-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.cwd();
-  const planningDir = path.join(cwd, '.planning');
-  const activeSkillFile = path.join(planningDir, '.active-skill');
-
-  try {
-    const activeSkill = fs.readFileSync(activeSkillFile, 'utf8').trim();
-    if (activeSkill !== 'plan') return null;
-  } catch (_e) {
-    return null;
-  }
-
-  return {
-    block: true,
-    reason: 'Plan skill should not spawn executors. To fix: Run /pbr:build to execute plans. The plan skill creates plans; the build skill executes them.'
-  };
-}
-
-/**
- * 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.
- */
-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.cwd();
-  const planningDir = path.join(cwd, '.planning');
-  const activeSkillFile = path.join(planningDir, '.active-skill');
-
-  // Only gate when active skill is "review"
-  try {
-    const activeSkill = fs.readFileSync(activeSkillFile, 'utf8').trim();
-    if (activeSkill !== 'review') return null;
-  } catch (_e) {
-    return null;
-  }
-
-  // Read STATE.md for current phase
-  const stateFile = path.join(planningDir, 'STATE.md');
-  try {
-    const state = fs.readFileSync(stateFile, 'utf8');
-    const phaseMatch = state.match(/Phase:\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 hasVerification = fs.existsSync(path.join(phaseDir, 'VERIFICATION.md'));
-
-    if (!hasVerification) {
-      return {
-        block: true,
-        reason: 'Review planner gate: Cannot spawn planner for gap closure without a VERIFICATION.md. To fix: Run /pbr:review {N} to create VERIFICATION.md first.'
-      };
-    }
-  } catch (_e) {
-    return null;
-  }
-
-  return null;
-}
-
-/**
- * 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.
- */
-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.cwd();
-  const planningDir = path.join(cwd, '.planning');
-  const activeSkillFile = path.join(planningDir, '.active-skill');
-
-  // Only gate when active skill is "review"
-  try {
-    const activeSkill = fs.readFileSync(activeSkillFile, 'utf8').trim();
-    if (activeSkill !== 'review') return null;
-  } catch (_e) {
-    return null;
-  }
-
-  // Read STATE.md for current phase
-  const stateFile = path.join(planningDir, 'STATE.md');
-  try {
-    const state = fs.readFileSync(stateFile, 'utf8');
-    const phaseMatch = state.match(/Phase:\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 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 in phase directory. To fix: Run /pbr:build {N} to create SUMMARY.md first.'
-      };
-    }
-  } catch (_e) {
-    return null;
-  }
-
-  return null;
-}
-
-/**
- * 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.
- */
-function checkMilestoneCompleteGate(data) {
-  const toolInput = data.tool_input || {};
-  const subagentType = toolInput.subagent_type || '';
-  const description = toolInput.description || '';
-
-  const cwd = process.cwd();
-  const planningDir = path.join(cwd, '.planning');
-  const activeSkillFile = path.join(planningDir, '.active-skill');
-
-  // Only gate when active skill is "milestone"
-  try {
-    const activeSkill = fs.readFileSync(activeSkillFile, 'utf8').trim();
-    if (activeSkill !== 'milestone') return null;
-  } catch (_e) {
-    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 stateFile = path.join(planningDir, 'STATE.md');
-  let currentPhase;
-  try {
-    const state = fs.readFileSync(stateFile, 'utf8');
-    const fmMatch = state.match(/current_phase:\s*(\d+)/);
-    if (fmMatch) {
-      currentPhase = parseInt(fmMatch[1], 10);
-    } else {
-      const bodyMatch = state.match(/Phase:\s*(\d+)/);
-      if (bodyMatch) currentPhase = parseInt(bodyMatch[1], 10);
-    }
-    if (!currentPhase) return null;
-  } catch (_e) {
-    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. All milestone phases must be verified before completing milestone. To fix: Run /pbr:review ${paddedPhase} — phase must have 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. All milestone phases must be verified before completing milestone. To fix: Run /pbr:review ${paddedPhase} — phase must have 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. Close all gaps before completing milestone. To fix: Run /pbr:review ${paddedPhase} — phase must have status: passed.`
-          };
-        }
-      }
-
-      // All phases verified
-      return null;
-    }
-  } catch (_e) {
-    return null;
-  }
-
-  return null;
-}
-
-/**
- * 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.
- */
-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.cwd();
-  const planningDir = path.join(cwd, '.planning');
-  const activeSkillFile = path.join(planningDir, '.active-skill');
-
-  // Only gate when active skill is "build"
-  try {
-    const activeSkill = fs.readFileSync(activeSkillFile, 'utf8').trim();
-    if (activeSkill !== 'build') return null;
-  } catch (_e) {
-    return null;
-  }
-
-  // Read STATE.md for current phase
-  const stateFile = path.join(planningDir, 'STATE.md');
-  let currentPhase;
-  try {
-    const state = fs.readFileSync(stateFile, '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. To fix: Run /pbr:review on 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. To fix: Run /pbr:review on the dependency phase first.`
-        };
-      }
-    }
-  } catch (_e) {
-    return null;
-  }
-
-  return null;
-}
-
-/**
- * Advisory check: when active skill is "build" and an executor is being
- * spawned, warn if .checkpoint-manifest.json is missing in the phase dir.
- * Returns a warning string or null.
- */
-/**
- * Parse VERIFICATION.md frontmatter to extract status field.
- * Returns the status string or 'unknown' if not parseable.
- */
-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';
-  }
-}
-
-/**
- * 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.
- */
-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 activeSkillPath = path.join(process.cwd(), '.planning', '.active-skill');
-  try {
-    const activeSkill = fs.readFileSync(activeSkillPath, 'utf8').trim();
-    if (activeSkill !== 'debug') return null;
-  } catch (_e) {
-    return null; // No .active-skill file — skip advisory
-  }
-  const debugDir = path.join(process.cwd(), '.planning', '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;
-}
-
-function checkCheckpointManifest(data) {
-  const toolInput = data.tool_input || {};
-  const subagentType = toolInput.subagent_type || '';
-
-  if (subagentType !== 'pbr:executor') return null;
-
-  const cwd = process.cwd();
-  const planningDir = path.join(cwd, '.planning');
-  const activeSkillFile = path.join(planningDir, '.active-skill');
-
-  try {
-    const activeSkill = fs.readFileSync(activeSkillFile, 'utf8').trim();
-    if (activeSkill !== 'build') return null;
-  } catch (_e) {
-    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.
- */
-function checkActiveSkillIntegrity(data) {
-  const toolInput = data.tool_input || {};
-  const subagentType = toolInput.subagent_type || '';
-
-  if (typeof subagentType !== 'string' || !subagentType.startsWith('pbr:')) return null;
-
-  const cwd = process.cwd();
-  const planningDir = path.join(cwd, '.planning');
-
-  // Only check if .planning/ exists (PBR project)
-  if (!fs.existsSync(planningDir)) return null;
-
-  const activeSkillFile = path.join(planningDir, '.active-skill');
-  if (!fs.existsSync(activeSkillFile)) {
-    return 'Active-skill integrity: .planning/.active-skill not found. Skill-specific enforcement is disabled. The invoking skill should write this file. To fix: Wait for the current skill to finish, or delete .planning/.active-skill if stale.';
-  }
-
-  return null;
-}
-
 function main() {
   let input = '';
 
   process.stdin.setEncoding('utf8');
   process.stdin.on('data', (chunk) => { input += chunk; });
-  process.stdin.on('end', () => {
+  process.stdin.on('end', async () => {
     try {
       const data = JSON.parse(input);
 
@@ -761,6 +181,18 @@ function main() {
         return;
       }
 
+      // Blocking gate: milestone complete needs SUMMARY.md in all phases
+      const milestoneSummaryGate = checkMilestoneSummaryGate(data);
+      if (milestoneSummaryGate && milestoneSummaryGate.block) {
+        logHook('validate-task', 'PreToolUse', 'blocked', { reason: milestoneSummaryGate.reason });
+        process.stdout.write(JSON.stringify({
+          decision: 'block',
+          reason: milestoneSummaryGate.reason
+        }));
+        process.exit(2);
+        return;
+      }
+
       // Blocking gate: build dependency check
       const buildDepGate = checkBuildDependencyGate(data);
       if (buildDepGate && buildDepGate.block) {
@@ -773,6 +205,26 @@ function main() {
         return;
       }
 
+      // Blocking gate: PROJECT.md + REQUIREMENTS.md must exist for plan/build
+      const docGate = checkDocExistence(data);
+      if (docGate && docGate.block) {
+        logHook('validate-task', 'PreToolUse', 'blocked', { reason: docGate.reason });
+        process.stdout.write(JSON.stringify({
+          decision: 'block',
+          reason: docGate.reason
+        }));
+        process.exit(2);
+        return;
+      }
+
+      // Blocking/advisory gate: non-PBR agent enforcement
+      const nonPbrAgentResult = checkNonPbrAgent(data);
+      if (nonPbrAgentResult && nonPbrAgentResult.exitCode === 2) {
+        process.stdout.write(JSON.stringify(nonPbrAgentResult.output));
+        process.exit(2);
+        return;
+      }
+
       // Advisory warnings
       const warnings = checkTask(data);
       const manifestWarning = checkCheckpointManifest(data);
@@ -781,6 +233,20 @@ function main() {
       if (debuggerWarning) warnings.push(debuggerWarning);
       const activeSkillWarning = checkActiveSkillIntegrity(data);
       if (activeSkillWarning) warnings.push(activeSkillWarning);
+      if (nonPbrAgentResult) warnings.push(nonPbrAgentResult.output.additionalContext);
+
+      // LLM task coherence check — advisory only
+      try {
+        const llmCwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+        const llmConfig = loadLocalLlmConfig(llmCwd);
+        const planningDir = path.join(llmCwd, '.planning');
+        const llmResult = await llmValidateTask(llmConfig, planningDir, data.tool_input || {}, data.session_id);
+        if (llmResult && !llmResult.coherent) {
+          warnings.push('LLM task coherence advisory: ' + (llmResult.issue || 'Task description may not match intended operation.') + ' (confidence: ' + (llmResult.confidence * 100).toFixed(0) + '%)');
+        }
+      } catch (_llmErr) {
+        // Never propagate LLM errors
+      }
 
       if (warnings.length > 0) {
         for (const warning of warnings) {
@@ -793,11 +259,24 @@ function main() {
 
       process.exit(0);
     } catch (_e) {
-      // Parse error — don't block
+      // Fail-open telemetry: log error details to hooks.jsonl
+      try {
+        logHook('validate-task', 'PreToolUse', 'error', {
+          error: _e.message,
+          stack: _e.stack,
+          gate: 'unknown'
+        });
+      } catch (_logErr) {
+        // fail-open: logging failure must not block
+      }
+      // Don't block on errors — emit valid output for Claude Code
+      process.stderr.write(`[pbr] validate-task error: ${_e.message}
+`);
+      process.stdout.write(JSON.stringify({ decision: "allow" }));
       process.exit(0);
     }
   });
 }
 
-module.exports = { checkTask, checkQuickExecutorGate, checkBuildExecutorGate, checkPlanExecutorGate, checkReviewPlannerGate, checkReviewVerifierGate, checkMilestoneCompleteGate, checkBuildDependencyGate, checkCheckpointManifest, checkDebuggerAdvisory, getVerificationStatus, checkActiveSkillIntegrity, KNOWN_AGENTS, MAX_DESCRIPTION_LENGTH };
+module.exports = { checkTask, checkQuickExecutorGate, checkBuildExecutorGate, checkPlanExecutorGate, checkReviewPlannerGate, checkReviewVerifierGate, checkMilestoneCompleteGate, checkMilestoneSummaryGate, checkBuildDependencyGate, checkCheckpointManifest, checkDebuggerAdvisory, getVerificationStatus, checkActiveSkillIntegrity, checkDocExistence, KNOWN_AGENTS, MAX_DESCRIPTION_LENGTH };
 if (require.main === module || process.argv[1] === __filename) { main(); }