@sienklogic/plan-build-run 2.21.1 → 2.21.2

package/plugins/pbr/scripts/check-subagent-output.js

@@ -7,296 +7,97 @@
  * after the agent completes. This catches silent agent failures early
  * rather than discovering them during verification.
  *
- * Agent → Expected output mapping:
- *   executor   → SUMMARY-{plan_id}.md (or SUMMARY.md) in the phase directory
- *   planner    → PLAN-{MM}.md in the phase directory
- *   verifier   → VERIFICATION.md in the phase directory
- *   researcher → RESEARCH.md (or domain-specific .md) in research/
+ * Agent -> Expected output mapping:
+ *   executor   -> SUMMARY-{plan_id}.md (or SUMMARY.md) in the phase directory
+ *   planner    -> PLAN-{MM}.md in the phase directory
+ *   verifier   -> VERIFICATION.md in the phase directory
+ *   researcher -> RESEARCH.md (or domain-specific .md) in research/
  *
  * Exit codes:
- *   0 = always (informational hook, never blocks — PostToolUse can only warn)
+ *   0 = always (informational hook, never blocks -- PostToolUse can only warn)
  */
 
 const fs = require('fs');
 const path = require('path');
 const { logHook } = require('./hook-logger');
-
-/**
- * Check if a file was modified recently (within thresholdMs).
- * Returns false if file doesn't exist or on error.
- */
-function isRecent(filePath, thresholdMs = 300000) {
+const { KNOWN_AGENTS, sessionLoad } = require('./pbr-tools');
+const { resolveSessionPath } = require('./lib/core');
+const { logEvent } = require('./event-logger');
+const { recordOutcome } = require('./trust-tracker');
+const { checkPrematureCompletion } = require('./lib/premature-completion');
+
+// Stress-test disablement check
+function isDisabledForStressTest(planningDir, hookName) {
   try {
-    const stat = fs.statSync(filePath);
-    return (Date.now() - stat.mtimeMs) < thresholdMs;
-  } catch (_e) {
-    return false;
-  }
+    const configPath = require('path').join(planningDir, 'config.json');
+    const config = JSON.parse(require('fs').readFileSync(configPath, 'utf8'));
+    const disabled = config.stress_test && config.stress_test.disabled_hooks;
+    return Array.isArray(disabled) && disabled.includes(hookName);
+  } catch (_e) { return false; }
 }
 
-// Agent type → expected output patterns
-const AGENT_OUTPUTS = {
-  'pbr:executor': {
-    description: 'SUMMARY.md in the phase or quick directory',
-    check: (planningDir) => {
-      // Check phase directory first, then quick directory
-      const phaseMatches = findInPhaseDir(planningDir, /^SUMMARY.*\.md$/i);
-      if (phaseMatches.length > 0) return phaseMatches;
-      return findInQuickDir(planningDir, /^SUMMARY.*\.md$/i);
-    }
-  },
-  'pbr:planner': {
-    description: 'PLAN.md in the phase directory',
-    check: (planningDir) => findInPhaseDir(planningDir, /^PLAN.*\.md$/i)
-  },
-  'pbr:verifier': {
-    description: 'VERIFICATION.md in the phase directory',
-    check: (planningDir) => findInPhaseDir(planningDir, /^VERIFICATION\.md$/i)
-  },
-  'pbr:researcher': {
-    description: 'research file in .planning/research/',
-    check: (planningDir) => {
-      const researchDir = path.join(planningDir, 'research');
-      if (!fs.existsSync(researchDir)) return [];
-      try {
-        const allFiles = fs.readdirSync(researchDir)
-          .filter(f => f.endsWith('.md'))
-          .map(f => path.join('research', f));
-        if (allFiles.length === 0) return [];
-        const recentFiles = allFiles.filter(f => isRecent(path.join(planningDir, f)));
-        if (recentFiles.length === 0) {
-          // Files exist but none are recent — return them but flag staleness
-          allFiles._stale = true;
-        }
-        return allFiles;
-      } catch (_e) {
-        return [];
-      }
-    }
-  },
-  'pbr:synthesizer': {
-    description: 'synthesis file in .planning/research/ or CONTEXT.md update',
-    check: (planningDir) => {
-      const researchDir = path.join(planningDir, 'research');
-      if (fs.existsSync(researchDir)) {
-        try {
-          const files = fs.readdirSync(researchDir).filter(f => f.endsWith('.md'));
-          if (files.length > 0) {
-            const allFiles = files.map(f => path.join('research', f));
-            const recentFiles = allFiles.filter(f => isRecent(path.join(planningDir, f)));
-            if (recentFiles.length === 0) {
-              allFiles._stale = true;
-            }
-            return allFiles;
-          }
-        } catch (_e) { /* best-effort */ }
-      }
-      const contextFile = path.join(planningDir, 'CONTEXT.md');
-      if (fs.existsSync(contextFile)) {
-        try {
-          const stat = fs.statSync(contextFile);
-          if (stat.size > 0) {
-            const result = ['CONTEXT.md'];
-            if (!isRecent(contextFile)) {
-              result._stale = true;
-            }
-            return result;
-          }
-        } catch (_e) { /* best-effort */ }
-      }
-      return [];
-    }
-  },
-  'pbr:plan-checker': {
-    description: 'advisory output (no file expected)',
-    noFileExpected: true,
-    check: () => []
-  },
-  'pbr:integration-checker': {
-    description: 'advisory output (no file expected)',
-    noFileExpected: true,
-    check: () => []
-  },
-  'pbr:debugger': {
-    description: 'debug file in .planning/debug/',
-    check: (planningDir) => {
-      const debugDir = path.join(planningDir, 'debug');
-      if (!fs.existsSync(debugDir)) return [];
-      try {
-        return fs.readdirSync(debugDir)
-          .filter(f => f.endsWith('.md'))
-          .map(f => path.join('debug', f));
-      } catch (_e) {
-        return [];
-      }
-    }
-  },
-  'pbr:codebase-mapper': {
-    description: 'codebase map in .planning/codebase/',
-    check: (planningDir) => {
-      const codebaseDir = path.join(planningDir, 'codebase');
-      if (!fs.existsSync(codebaseDir)) return [];
-      try {
-        return fs.readdirSync(codebaseDir)
-          .filter(f => f.endsWith('.md'))
-          .map(f => path.join('codebase', f));
-      } catch (_e) {
-        return [];
-      }
-    }
-  },
-  'pbr:general': {
-    description: 'advisory output (no file expected)',
-    noFileExpected: true,
-    check: () => []
-  }
-};
-
-/**
- * Extract current phase number from STATE.md, preferring frontmatter over body.
- * @param {string} stateContent - Full STATE.md content
- * @returns {string|null} Phase number string or null
- */
-function getCurrentPhase(stateContent) {
-  // Prefer frontmatter (always up-to-date)
-  const fmMatch = stateContent.match(/^current_phase:\s*(\d+)/m);
-  if (fmMatch) return fmMatch[1];
-  // Fall back to body text
-  const bodyMatch = stateContent.match(/Phase:\s*(\d+)\s+of\s+\d+/);
-  return bodyMatch ? bodyMatch[1] : null;
-}
+// Import all validators from extracted module
+const validators = require('./lib/subagent-validators');
+const {
+  AGENT_TO_SKILL,
+  AGENT_OUTPUTS,
+  SKILL_CHECKS,
+  findInPhaseDir,
+  findInQuickDir,
+  checkSummaryCommits,
+  checkDeviationsRequiringReview,
+  logCompliance,
+  checkTriggeredSeeds,
+  checkLearningsRequired,
+  isRecent,
+  getCurrentPhase,
+  checkRoadmapStaleness,
+  logInlineDecision,
+  extractVerificationOutcome,
+  shouldTrackTrust,
+  loadFeatureFlag,
+  updateConventionsAfterBuild,
+  validateSelfCheck
+} = validators;
 
 /**
- * Check if ROADMAP.md is stale after executor/verifier completion.
- * Detects: (1) no Progress table for current milestone, (2) table exists but
- * phase row is out of date vs. phase artifacts on disk.
- *
- * @param {string} planningDir - Path to .planning/
- * @returns {string|null} Warning message or null if in sync
+ * Log plan-checker completion results to hooks.jsonl for audit trail.
+ * Extracts phase, status, dimension count, and blocker count from agent output.
  */
-function checkRoadmapStaleness(planningDir) {
-  const roadmapPath = path.join(planningDir, 'ROADMAP.md');
-  if (!fs.existsSync(roadmapPath)) return null;
-
-  try {
-    const content = fs.readFileSync(roadmapPath, 'utf8');
-
-    // Check if there's a Progress table at all
-    const hasProgressTable = /Plans\s*Complete/i.test(content);
-    if (!hasProgressTable) {
-      return 'ROADMAP.md has no Progress table for the current milestone. The orchestrator should add a Progress table with columns: Phase | Plans Complete | Status | Completed. See skills/shared/state-update.md for format.';
-    }
-
-    // If table exists, check if current phase row is present
-    const stateFile = path.join(planningDir, 'STATE.md');
-    if (fs.existsSync(stateFile)) {
-      const stateContent = fs.readFileSync(stateFile, 'utf8');
-      const currentPhase = getCurrentPhase(stateContent);
-      if (currentPhase) {
-        const paddedPhase = currentPhase.padStart(2, '0');
-        const phaseInTable = new RegExp(`\\|\\s*${paddedPhase}\\.`).test(content) ||
-          new RegExp(`\\|\\s*${parseInt(currentPhase, 10)}\\.`).test(content);
-        if (!phaseInTable) {
-          return `ROADMAP.md Progress table exists but has no row for Phase ${currentPhase}. Add a row for the current phase.`;
-        }
-      }
-    }
-  } catch (_e) {
-    // best-effort
-  }
-  return null;
-}
-
-function findInPhaseDir(planningDir, pattern) {
-  const matches = [];
-  const phasesDir = path.join(planningDir, 'phases');
-  if (!fs.existsSync(phasesDir)) return matches;
-
+function logPlanCheckerResult(data) {
   try {
-    // Find the active phase from STATE.md (prefer frontmatter over body)
-    const stateFile = path.join(planningDir, 'STATE.md');
-    if (!fs.existsSync(stateFile)) return matches;
-
-    const stateContent = fs.readFileSync(stateFile, 'utf8');
-    const phaseNum = getCurrentPhase(stateContent);
-    if (!phaseNum) return matches;
-
-    const currentPhase = phaseNum.padStart(2, '0');
-    const dirs = fs.readdirSync(phasesDir).filter(d => d.startsWith(currentPhase));
-    if (dirs.length === 0) return matches;
-
-    const phaseDir = path.join(phasesDir, dirs[0]);
-    const files = fs.readdirSync(phaseDir);
-    for (const file of files) {
-      if (pattern.test(file)) {
-        // Check it's non-empty
-        const filePath = path.join(phaseDir, file);
-        const stat = fs.statSync(filePath);
-        if (stat.size > 0) {
-          matches.push(path.join('phases', dirs[0], file));
-        }
-      }
-    }
-  } catch (_e) {
-    // best-effort
-  }
-  return matches;
-}
-
-function findInQuickDir(planningDir, pattern) {
-  const matches = [];
-  const quickDir = path.join(planningDir, 'quick');
-  if (!fs.existsSync(quickDir)) return matches;
-
-  try {
-    // Find the most recent quick task directory (highest NNN)
-    const dirs = fs.readdirSync(quickDir)
-      .filter(d => /^\d{3}-/.test(d))
-      .sort()
-      .reverse();
-    if (dirs.length === 0) return matches;
-
-    const latestDir = path.join(quickDir, dirs[0]);
-    const stat = fs.statSync(latestDir);
-    if (!stat.isDirectory()) return matches;
-
-    const files = fs.readdirSync(latestDir);
-    for (const file of files) {
-      if (pattern.test(file)) {
-        const filePath = path.join(latestDir, file);
-        const fileStat = fs.statSync(filePath);
-        if (fileStat.size > 0) {
-          matches.push(path.join('quick', dirs[0], file));
-        }
-      }
-    }
+    const toolOutput = data.tool_output || '';
+
+    // Extract phase number from output or tool_input
+    let phaseNum = null;
+    const phaseMatch = toolOutput.match(/phase[:\s]+(\d+)/i) ||
+      (data.tool_input && JSON.stringify(data.tool_input).match(/phase[:\s"]+(\d+)/i));
+    if (phaseMatch) phaseNum = parseInt(phaseMatch[1], 10);
+
+    // Determine status from output patterns
+    let status = 'unknown';
+    if (/BLOCKER/i.test(toolOutput)) status = 'issues_found';
+    else if (/WARNING/i.test(toolOutput) && !/BLOCKER/i.test(toolOutput)) status = 'warnings';
+    else if (/pass|clean|no issues/i.test(toolOutput)) status = 'passed';
+    else if (toolOutput.length > 0) status = 'completed';
+
+    // Count dimensions checked (D1: through D9: patterns)
+    const dimensionMatches = toolOutput.match(/D\d+[:\s]/g);
+    const dimensionCount = dimensionMatches ? new Set(dimensionMatches.map(d => d.trim())).size : 0;
+
+    // Count blockers
+    const blockerMatches = toolOutput.match(/BLOCKER/gi);
+    const blockerCount = blockerMatches ? blockerMatches.length : 0;
+
+    logHook('plan-checker', 'SubagentStop', 'complete', {
+      action: 'validate',
+      phase: phaseNum,
+      status: status,
+      dimensions: dimensionCount,
+      blockers: blockerCount
+    });
   } catch (_e) {
-    // best-effort
-  }
-  return matches;
-}
-
-function checkSummaryCommits(planningDir, foundFiles, warnings) {
-  // Look for SUMMARY files in found list
-  const summaryFiles = foundFiles.filter(f => /SUMMARY/i.test(f));
-  for (const relPath of summaryFiles) {
-    try {
-      const fullPath = path.join(planningDir, relPath);
-      const content = fs.readFileSync(fullPath, 'utf8');
-      // Parse frontmatter for commits field
-      const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-      if (!fmMatch) continue;
-      const fm = fmMatch[1];
-      const commitsMatch = fm.match(/commits:\s*(\[.*?\]|.*)/);
-      if (!commitsMatch) {
-        warnings.push(`${relPath}: No "commits" field in frontmatter. Executor should record commit hashes.`);
-        continue;
-      }
-      const commitsVal = commitsMatch[1].trim();
-      if (commitsVal === '[]' || commitsVal === '' || commitsVal === '~' || commitsVal === 'null') {
-        warnings.push(`${relPath}: "commits" field is empty. Executor may have failed to commit changes.`);
-      }
-    } catch (_e) { /* best-effort */ }
+    // Never let logging failures block the hook
   }
 }
 
@@ -310,9 +111,10 @@ function readStdin() {
   return {};
 }
 
-function main() {
+
+async function main() {
   const data = readStdin();
-  const cwd = process.cwd();
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
   const planningDir = path.join(cwd, '.planning');
 
   // Only relevant for Plan-Build-Run projects
@@ -320,20 +122,43 @@ function main() {
     process.exit(0);
   }
 
+  // Stress-test disablement: skip validation when this hook is disabled
+  if (isDisabledForStressTest(planningDir, 'check-subagent-output')) {
+    logHook('stress-test', 'check-subagent-output', 'disabled for stress testing');
+    process.exit(0);
+  }
+
   // Extract agent type from the Task completion data
-  const agentType = data.tool_input?.subagent_type || data.subagent_type || '';
+  const agentType = data.agent_type || data.tool_input?.subagent_type || data.subagent_type || '';
 
   // Only check known Plan-Build-Run agent types
   const outputSpec = AGENT_OUTPUTS[agentType];
   if (!outputSpec) {
+    // Log when agent is in KNOWN_AGENTS but missing from AGENT_OUTPUTS
+    const shortName = agentType.startsWith('pbr:') ? agentType.slice(4) : agentType;
+    if (KNOWN_AGENTS && KNOWN_AGENTS.includes && KNOWN_AGENTS.includes(shortName)) {
+      logHook('check-subagent-output', 'PostToolUse', 'missing-output-spec', {
+        agent_type: agentType,
+        message: `Agent ${agentType} is in KNOWN_AGENTS but has no AGENT_OUTPUTS entry. Add one to check-subagent-output.js.`
+      });
+    }
     process.exit(0);
   }
 
-  // Read active skill
-  let activeSkill = '';
-  try {
-    activeSkill = fs.readFileSync(path.join(planningDir, '.active-skill'), 'utf8').trim();
-  } catch (_e) { /* no active skill */ }
+  // Log plan-checker completions for audit trail
+  if (agentType === 'pbr:plan-checker') {
+    logPlanCheckerResult(data);
+  }
+
+  // Read active skill -- session-scoped when session_id available
+  const sessionId = data.session_id || null;
+  let activeSkill = sessionLoad(planningDir, sessionId).activeSkill || '';
+  if (!activeSkill) {
+    const skillPath = sessionId
+      ? resolveSessionPath(planningDir, '.active-skill', sessionId)
+      : path.join(planningDir, '.active-skill');
+    try { activeSkill = fs.readFileSync(skillPath, 'utf8').trim(); } catch (_) { /* file missing */ }
+  }
 
   // Check for expected outputs
   const found = outputSpec.check(planningDir);
@@ -343,16 +168,27 @@ function main() {
   // Skill-specific post-completion validation
   const skillWarnings = [];
 
-  // ACTIVE-SKILL ENFORCEMENT: Warn when no .active-skill file exists.
-  // Skills are instructed (with CRITICAL markers) to write this file, but LLMs
-  // skip it under cognitive load. This warning reminds the orchestrator.
+  // ACTIVE-SKILL ENFORCEMENT: Auto-create .active-skill when missing.
   if (!activeSkill && agentType !== 'pbr:general' && agentType !== 'pbr:plan-checker' && agentType !== 'pbr:integration-checker') {
-    skillWarnings.push('.active-skill file is missing — the orchestrating skill never wrote it. This means skill-workflow guards were inactive for this entire operation. CRITICAL: Write the skill name to .planning/.active-skill BEFORE spawning agents.');
+    const inferredSkill = AGENT_TO_SKILL[agentType];
+    if (inferredSkill) {
+      try {
+        const skillPath = sessionId
+          ? resolveSessionPath(planningDir, '.active-skill', sessionId)
+          : path.join(planningDir, '.active-skill');
+        fs.writeFileSync(skillPath, inferredSkill, 'utf8');
+        activeSkill = inferredSkill;
+        logHook('check-subagent-output', 'PostToolUse', 'active-skill-auto-created', { skill: inferredSkill, agent: agentType });
+        skillWarnings.push(`.active-skill was missing — auto-created as "${inferredSkill}" (inferred from ${agentType}). Skill-specific enforcement is now active for subsequent agents.`);
+      } catch (_writeErr) {
+        skillWarnings.push('.active-skill file is missing and auto-creation failed. Skill-workflow guards were inactive for this operation.');
+      }
+    } else {
+      skillWarnings.push('.active-skill file is missing — the orchestrating skill never wrote it. This means skill-workflow guards were inactive for this entire operation. CRITICAL: Write the skill name to .planning/.active-skill BEFORE spawning agents.');
+    }
   }
 
-  // ROADMAP.md SYNC: After executor or verifier completes, check if ROADMAP.md
-  // needs updating. Subagent writes (SUMMARY/VERIFICATION) trigger check-state-sync
-  // in the subagent context, but the main context ROADMAP.md may still be stale.
+  // ROADMAP.md SYNC check after executor or verifier completes
   if (agentType === 'pbr:executor' || agentType === 'pbr:verifier') {
     const roadmapWarning = checkRoadmapStaleness(planningDir);
     if (roadmapWarning) {
@@ -366,57 +202,55 @@ function main() {
     skillWarnings.push(`${label} output may be stale — no recent output files detected.`);
   }
 
-  // GAP-04: Begin planner must produce core files
-  if (activeSkill === 'begin' && agentType === 'pbr:planner') {
-    const coreFiles = ['REQUIREMENTS.md', 'ROADMAP.md', 'STATE.md'];
-    for (const f of coreFiles) {
-      if (!fs.existsSync(path.join(planningDir, f))) {
-        skillWarnings.push(`Begin planner: ${f} was not created. The project may be in an incomplete state.`);
-      }
-    }
+  // Skill-specific dispatch via SKILL_CHECKS lookup
+  const skillCheckKey = `${activeSkill}:${agentType}`;
+  const skillCheck = SKILL_CHECKS[skillCheckKey];
+  if (skillCheck) {
+    skillCheck.check(planningDir, found, skillWarnings);
   }
 
-  // GAP-05: Plan researcher should produce phase-level RESEARCH.md
-  if (activeSkill === 'plan' && agentType === 'pbr:researcher') {
-    const phaseResearch = findInPhaseDir(planningDir, /^RESEARCH\.md$/i);
-    if (found.length === 0 && phaseResearch.length === 0) {
-      skillWarnings.push('Plan researcher: No research output found in .planning/research/ or in the phase directory.');
+  // Completion marker validation for executor agents
+  if (agentType === 'pbr:executor') {
+    const toolOutput = data.tool_output || '';
+    const hasCompletionMarker = /## PLAN COMPLETE|## PLAN FAILED|## CHECKPOINT:/i.test(toolOutput);
+    if (toolOutput && !hasCompletionMarker) {
+      skillWarnings.push('Executor did not return a completion marker (expected ## PLAN COMPLETE, ## PLAN FAILED, or ## CHECKPOINT:). Build skill may not route correctly.');
     }
-  }
 
-  // GAP-08: Scan codebase-mapper should produce all 4 focus areas
-  if (activeSkill === 'scan' && agentType === 'pbr:codebase-mapper') {
-    const expectedAreas = ['tech', 'arch', 'quality', 'concerns'];
-    const codebaseDir = path.join(planningDir, 'codebase');
-    if (fs.existsSync(codebaseDir)) {
-      try {
-        const files = fs.readdirSync(codebaseDir).map(f => f.toLowerCase());
-        for (const area of expectedAreas) {
-          if (!files.some(f => f.includes(area))) {
-            skillWarnings.push(`Scan mapper: No output file containing "${area}" found in .planning/codebase/. One of the 4 mappers may have failed.`);
+    // Self-Check section validation in SUMMARY.md body
+    if (found.length > 0) {
+      const summaryFiles = found.filter(f => /SUMMARY/i.test(f));
+      let hasSelfCheckSection = false;
+      for (const relPath of summaryFiles) {
+        try {
+          const fullPath = path.join(planningDir, relPath);
+          const content = fs.readFileSync(fullPath, 'utf8');
+          if (/^## Self-Check:\s*(PASSED|FAILED)/mi.test(content)) {
+            hasSelfCheckSection = true;
+            break;
           }
-        }
-      } catch (_e) { /* best-effort */ }
+        } catch (_e) { /* best-effort */ }
+      }
+      if (!hasSelfCheckSection) {
+        skillWarnings.push('Executor SUMMARY.md missing ## Self-Check section. Self-verification may have been skipped.');
+      }
     }
   }
 
-  // GAP-07: Review verifier should produce meaningful VERIFICATION.md status
-  if (activeSkill === 'review' && agentType === 'pbr:verifier') {
-    const verFiles = findInPhaseDir(planningDir, /^VERIFICATION\.md$/i);
-    for (const vf of verFiles) {
-      try {
-        const content = fs.readFileSync(path.join(planningDir, vf), 'utf8');
-        const statusMatch = content.match(/^status:\s*(\S+)/mi);
-        if (statusMatch && statusMatch[1] === 'gaps_found') {
-          skillWarnings.push('Review verifier: VERIFICATION.md has status "gaps_found" — ensure gaps are surfaced to the user.');
-        }
-      } catch (_e) { /* best-effort */ }
-    }
+  // Premature completion detection (REQ-HI-08)
+  const prematureResult = checkPrematureCompletion(agentType, data, planningDir);
+  if (prematureResult && prematureResult.warning) {
+    skillWarnings.push(`[ADVISORY] Possible premature completion: ${prematureResult.warning} (signals: ${prematureResult.signals.join(', ')})`);
   }
 
-  // GAP-06: Build/quick executor SUMMARY should have commits
-  if ((activeSkill === 'build' || activeSkill === 'quick') && agentType === 'pbr:executor') {
-    checkSummaryCommits(planningDir, found, skillWarnings);
+  // Log compliance violations for tracking and session-end summary
+  if (genericMissing) {
+    logCompliance(planningDir, agentType, `Missing expected output: ${outputSpec.description}`, 'required');
+  }
+  for (const w of skillWarnings) {
+    if (w.startsWith('[REQUIRED]')) {
+      logCompliance(planningDir, agentType, w.replace('[REQUIRED] ', ''), 'required');
+    }
   }
 
   // Output logic: avoid duplicating warnings
@@ -436,7 +270,7 @@ function main() {
       found: 'none'
     });
     const output = {
-      additionalContext: `Warning: Agent ${agentType} completed but no ${outputSpec.description} was found. The agent may have failed silently. Check agent output for errors.`
+      additionalContext: `[WARN] Agent ${agentType} completed but no ${outputSpec.description} was found. Likely causes: (1) agent hit an error mid-run, (2) wrong working directory. To fix: re-run the parent skill — the executor gate will block until the output is present. Check the Task() output above for error details.`
     };
     process.stdout.write(JSON.stringify(output));
   } else if (skillWarnings.length > 0) {
@@ -458,5 +292,134 @@ function main() {
   process.exit(0);
 }
 
-module.exports = { AGENT_OUTPUTS, findInPhaseDir, findInQuickDir, checkSummaryCommits, isRecent, getCurrentPhase, checkRoadmapStaleness };
+/**
+ * HTTP handler for hook-server.js integration.
+ * Called as handleHttp(reqBody, cache) where reqBody = { event, tool, data, planningDir, cache }.
+ * Must NOT call process.exit().
+ * @param {{ data: object, planningDir: string }} reqBody
+ * @returns {Promise<{ additionalContext: string }|null>}
+ */
+async function handleHttp(reqBody) {
+  const data = reqBody.data || {};
+  const planningDir = reqBody.planningDir;
+  if (!planningDir || !fs.existsSync(planningDir)) return null;
+
+  const agentType = data.agent_type || data.tool_input?.subagent_type || data.subagent_type || '';
+  const outputSpec = AGENT_OUTPUTS[agentType];
+  if (!outputSpec) {
+    const shortName = agentType.startsWith('pbr:') ? agentType.slice(4) : agentType;
+    if (KNOWN_AGENTS && KNOWN_AGENTS.includes && KNOWN_AGENTS.includes(shortName)) {
+      logHook('check-subagent-output', 'PostToolUse', 'missing-output-spec', {
+        agent_type: agentType,
+        message: `Agent ${agentType} is in KNOWN_AGENTS but has no AGENT_OUTPUTS entry. Add one to check-subagent-output.js.`
+      });
+    }
+    return null;
+  }
+
+  // Log plan-checker completions for audit trail
+  if (agentType === 'pbr:plan-checker') {
+    logPlanCheckerResult(data);
+  }
+
+  const sessionId = data.session_id || null;
+  let activeSkill = sessionLoad(planningDir, sessionId).activeSkill || '';
+  if (!activeSkill) {
+    const skillPath = sessionId
+      ? resolveSessionPath(planningDir, '.active-skill', sessionId)
+      : path.join(planningDir, '.active-skill');
+    try { activeSkill = fs.readFileSync(skillPath, 'utf8').trim(); } catch (_) { /* file missing */ }
+  }
+
+  const found = outputSpec.check(planningDir);
+  const genericMissing = found.length === 0 && !outputSpec.noFileExpected;
+  const skillWarnings = [];
+
+  if (!activeSkill && agentType !== 'pbr:general' && agentType !== 'pbr:plan-checker' && agentType !== 'pbr:integration-checker') {
+    const inferredSkill = AGENT_TO_SKILL[agentType];
+    if (inferredSkill) {
+      try {
+        const skillPath = sessionId
+          ? resolveSessionPath(planningDir, '.active-skill', sessionId)
+          : path.join(planningDir, '.active-skill');
+        fs.writeFileSync(skillPath, inferredSkill, 'utf8');
+        activeSkill = inferredSkill;
+        logHook('check-subagent-output', 'PostToolUse', 'active-skill-auto-created', { skill: inferredSkill, agent: agentType });
+        skillWarnings.push(`.active-skill was missing — auto-created as "${inferredSkill}" (inferred from ${agentType}).`);
+      } catch (_writeErr) {
+        skillWarnings.push('.active-skill file is missing and auto-creation failed.');
+      }
+    } else {
+      skillWarnings.push('.active-skill file is missing — the orchestrating skill never wrote it. CRITICAL: Write the skill name to .planning/.active-skill BEFORE spawning agents.');
+    }
+  }
+
+  if (agentType === 'pbr:executor' || agentType === 'pbr:verifier') {
+    const roadmapWarning = checkRoadmapStaleness(planningDir);
+    if (roadmapWarning) skillWarnings.push(roadmapWarning);
+  }
+
+  if (found._stale && (agentType === 'pbr:researcher' || agentType === 'pbr:synthesizer')) {
+    const label = agentType === 'pbr:researcher' ? 'Researcher' : 'Synthesizer';
+    skillWarnings.push(`${label} output may be stale — no recent output files detected.`);
+  }
+
+  const skillCheckKey = `${activeSkill}:${agentType}`;
+  const skillCheck = SKILL_CHECKS[skillCheckKey];
+  if (skillCheck) skillCheck.check(planningDir, found, skillWarnings);
+
+  // Completion marker validation for executor agents
+  if (agentType === 'pbr:executor') {
+    const toolOutput = data.tool_output || '';
+    const hasCompletionMarker = /## PLAN COMPLETE|## PLAN FAILED|## CHECKPOINT:/i.test(toolOutput);
+    if (toolOutput && !hasCompletionMarker) {
+      skillWarnings.push('Executor did not return a completion marker (expected ## PLAN COMPLETE, ## PLAN FAILED, or ## CHECKPOINT:). Build skill may not route correctly.');
+    }
+
+    // Self-Check section validation in SUMMARY.md body
+    if (found.length > 0) {
+      const summaryFiles = found.filter(f => /SUMMARY/i.test(f));
+      let hasSelfCheckSection = false;
+      for (const relPath of summaryFiles) {
+        try {
+          const fullPath = path.join(planningDir, relPath);
+          const content = fs.readFileSync(fullPath, 'utf8');
+          if (/^## Self-Check:\s*(PASSED|FAILED)/mi.test(content)) {
+            hasSelfCheckSection = true;
+            break;
+          }
+        } catch (_e) { /* best-effort */ }
+      }
+      if (!hasSelfCheckSection) {
+        skillWarnings.push('Executor SUMMARY.md missing ## Self-Check section. Self-verification may have been skipped.');
+      }
+    }
+  }
+
+  // Premature completion detection (REQ-HI-08)
+  const prematureResult = checkPrematureCompletion(agentType, data, planningDir);
+  if (prematureResult && prematureResult.warning) {
+    skillWarnings.push(`[ADVISORY] Possible premature completion: ${prematureResult.warning} (signals: ${prematureResult.signals.join(', ')})`);
+  }
+
+  if (genericMissing && skillWarnings.length > 0) {
+    logHook('check-subagent-output', 'PostToolUse', 'skill-warning', { skill: activeSkill, agent_type: agentType, warnings: skillWarnings });
+    const msg = `Warning: Agent ${agentType} completed but no ${outputSpec.description} was found.\nSkill-specific warnings:\n` +
+      skillWarnings.map(w => `- ${w}`).join('\n');
+    return { additionalContext: msg };
+  } else if (genericMissing) {
+    logHook('check-subagent-output', 'PostToolUse', 'warning', { agent_type: agentType, expected: outputSpec.description, found: 'none' });
+    return {
+      additionalContext: `[WARN] Agent ${agentType} completed but no ${outputSpec.description} was found. Likely causes: (1) agent hit an error mid-run, (2) wrong working directory. To fix: re-run the parent skill — the executor gate will block until the output is present. Check the Task() output above for error details.`
+    };
+  } else if (skillWarnings.length > 0) {
+    logHook('check-subagent-output', 'PostToolUse', 'skill-warning', { skill: activeSkill, agent_type: agentType, warnings: skillWarnings });
+    return { additionalContext: 'Skill-specific warnings:\n' + skillWarnings.map(w => `- ${w}`).join('\n') };
+  } else {
+    logHook('check-subagent-output', 'PostToolUse', 'verified', { agent_type: agentType, found: found });
+    return null;
+  }
+}
+
+module.exports = { ...validators, handleHttp };
 if (require.main === module || process.argv[1] === __filename) { main(); }