@sienklogic/plan-build-run 2.18.1 → 2.19.1

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

@@ -0,0 +1,452 @@
+#!/usr/bin/env node
+
+/**
+ * PostToolUse hook on Task: Validates that subagent outputs exist.
+ *
+ * Maps agent types to expected output files and warns if they're missing
+ * 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/
+ *
+ * Exit codes:
+ *   0 = always (informational hook, never blocks -- PostToolUse can only warn)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+const { KNOWN_AGENTS, sessionLoad } = require('./pbr-tools');
+const { resolveConfig } = require('./lib/local-llm/health');
+const { classifyError } = require('./lib/local-llm/operations/classify-error');
+const { resolveSessionPath } = require('./lib/core');
+const { logEvent } = require('./event-logger');
+const { recordOutcome } = require('./trust-tracker');
+
+// 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;
+
+/**
+ * Log plan-checker completion results to hooks.jsonl for audit trail.
+ * Extracts phase, status, dimension count, and blocker count from agent output.
+ */
+function logPlanCheckerResult(data) {
+  try {
+    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) {
+    // Never let logging failures block the hook
+  }
+}
+
+function readStdin() {
+  try {
+    const input = fs.readFileSync(0, 'utf8').trim();
+    if (input) return JSON.parse(input);
+  } catch (_e) {
+    // empty or non-JSON stdin
+  }
+  return {};
+}
+
+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 (_) {
+    return resolveConfig(undefined);
+  }
+}
+
+async function main() {
+  const data = readStdin();
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+
+  // Only relevant for Plan-Build-Run projects
+  if (!fs.existsSync(planningDir)) {
+    process.exit(0);
+  }
+
+  // Extract agent type from the Task completion data
+  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);
+  }
+
+  // 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);
+
+  const genericMissing = found.length === 0 && !outputSpec.noFileExpected;
+
+  // Skill-specific post-completion validation
+  const skillWarnings = [];
+
+  // ACTIVE-SKILL ENFORCEMENT: Auto-create .active-skill when missing.
+  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}). 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 check after executor or verifier completes
+  if (agentType === 'pbr:executor' || agentType === 'pbr:verifier') {
+    const roadmapWarning = checkRoadmapStaleness(planningDir);
+    if (roadmapWarning) {
+      skillWarnings.push(roadmapWarning);
+    }
+  }
+
+  // Mtime-based recency check for researcher and synthesizer
+  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.`);
+  }
+
+  // Skill-specific dispatch via SKILL_CHECKS lookup
+  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.');
+      }
+    }
+  }
+
+  // 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
+  if (genericMissing && skillWarnings.length > 0) {
+    logHook('check-subagent-output', 'PostToolUse', 'skill-warning', {
+      skill: activeSkill,
+      agent_type: agentType,
+      warnings: skillWarnings
+    });
+    // LLM error classification -- advisory enrichment
+    let llmCategoryNote = '';
+    try {
+      const llmConfig = loadLocalLlmConfig(cwd);
+      const errorText = (data.tool_output || '').substring(0, 500);
+      if (errorText) {
+        const llmResult = await classifyError(llmConfig, planningDir, errorText, agentType, data.session_id);
+        if (llmResult && llmResult.category) {
+          llmCategoryNote = `\nLLM error category: ${llmResult.category} (confidence: ${(llmResult.confidence * 100).toFixed(0)}%)`;
+        }
+      }
+    } catch (_llmErr) {
+      // Never propagate
+    }
+    const msg = `Warning: Agent ${agentType} completed but no ${outputSpec.description} was found.\nSkill-specific warnings:\n` +
+      skillWarnings.map(w => `- ${w}`).join('\n') + llmCategoryNote;
+    process.stdout.write(JSON.stringify({ additionalContext: msg }));
+  } else if (genericMissing) {
+    logHook('check-subagent-output', 'PostToolUse', 'warning', {
+      agent_type: agentType,
+      expected: outputSpec.description,
+      found: 'none'
+    });
+    // LLM error classification -- advisory enrichment
+    let llmCategoryNote = '';
+    try {
+      const llmConfig = loadLocalLlmConfig(cwd);
+      const errorText = (data.tool_output || '').substring(0, 500);
+      if (errorText) {
+        const llmResult = await classifyError(llmConfig, planningDir, errorText, agentType, data.session_id);
+        if (llmResult && llmResult.category) {
+          llmCategoryNote = `\nLLM error category: ${llmResult.category} (confidence: ${(llmResult.confidence * 100).toFixed(0)}%)`;
+        }
+      }
+    } catch (_llmErr) {
+      // Never propagate
+    }
+    const output = {
+      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.` + llmCategoryNote
+    };
+    process.stdout.write(JSON.stringify(output));
+  } else if (skillWarnings.length > 0) {
+    logHook('check-subagent-output', 'PostToolUse', 'skill-warning', {
+      skill: activeSkill,
+      agent_type: agentType,
+      warnings: skillWarnings
+    });
+    process.stdout.write(JSON.stringify({
+      additionalContext: 'Skill-specific warnings:\n' + skillWarnings.map(w => `- ${w}`).join('\n')
+    }));
+  } else {
+    logHook('check-subagent-output', 'PostToolUse', 'verified', {
+      agent_type: agentType,
+      found: found
+    });
+  }
+
+  process.exit(0);
+}
+
+/**
+ * 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.');
+      }
+    }
+  }
+
+  // LLM classification helper (advisory, never throws)
+  async function getLlmNote() {
+    try {
+      const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+      const llmConfig = loadLocalLlmConfig(cwd);
+      const errorText = (data.tool_output || '').substring(0, 500);
+      if (!errorText) return '';
+      const llmResult = await classifyError(llmConfig, planningDir, errorText, agentType, data.session_id);
+      if (llmResult && llmResult.category) {
+        return `\nLLM error category: ${llmResult.category} (confidence: ${(llmResult.confidence * 100).toFixed(0)}%)`;
+      }
+    } catch (_e) { /* never propagate */ }
+    return '';
+  }
+
+  if (genericMissing && skillWarnings.length > 0) {
+    logHook('check-subagent-output', 'PostToolUse', 'skill-warning', { skill: activeSkill, agent_type: agentType, warnings: skillWarnings });
+    const llmCategoryNote = await getLlmNote();
+    const msg = `Warning: Agent ${agentType} completed but no ${outputSpec.description} was found.\nSkill-specific warnings:\n` +
+      skillWarnings.map(w => `- ${w}`).join('\n') + llmCategoryNote;
+    return { additionalContext: msg };
+  } else if (genericMissing) {
+    logHook('check-subagent-output', 'PostToolUse', 'warning', { agent_type: agentType, expected: outputSpec.description, found: 'none' });
+    const llmCategoryNote = await getLlmNote();
+    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.` + llmCategoryNote
+    };
+  } 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(); }

package/plugins/pbr/dist/check-summary-gate.js

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+
+/**
+ * PreToolUse hook (Write|Edit): Blocks STATE.md updates that advance
+ * phase status to "built" or "verified" unless a SUMMARY file exists
+ * for the current phase.
+ *
+ * This prevents the scenario where verification runs and STATE.md is
+ * updated but the executor never wrote a SUMMARY — leaving the project
+ * in an inconsistent state.
+ *
+ * Trigger: Write|Edit to STATE.md (via pre-write-dispatch.js)
+ *
+ * Logic:
+ *   1. Only fires when the target file is STATE.md
+ *   2. Reads the new content being written (from tool_input)
+ *   3. Extracts the phase slug and status from frontmatter
+ *   4. If status is advancing to "built", "verified", or "complete",
+ *      checks that a SUMMARY-*.md file exists in the phase directory
+ *   5. Blocks (exit 2) if no SUMMARY found
+ *
+ * Exit codes:
+ *   0 = allowed or not applicable
+ *   2 = blocked (no SUMMARY exists for advancing phase)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+
+// Statuses that indicate a phase has been executed
+const ADVANCED_STATUSES = ['built', 'verified', 'complete'];
+
+/**
+ * Extract YAML frontmatter values from markdown content.
+ * Returns an object with parsed key-value pairs.
+ */
+function parseFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return {};
+  const result = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const kv = line.match(/^(\w[\w_]*):\s*"?([^"\r\n]*)"?$/);
+    if (kv) result[kv[1]] = kv[2].trim();
+  }
+  return result;
+}
+
+/**
+ * Check if a SUMMARY file exists for the given phase directory.
+ */
+function hasSummaryFile(phaseDir) {
+  if (!fs.existsSync(phaseDir)) return false;
+  try {
+    const files = fs.readdirSync(phaseDir);
+    return files.some(f => /^SUMMARY.*\.md$/i.test(f));
+  } catch (_e) {
+    return false;
+  }
+}
+
+/**
+ * Find the phase directory matching a slug or phase number.
+ */
+function findPhaseDir(planningDir, phaseSlug, phaseNumber) {
+  const phasesDir = path.join(planningDir, 'phases');
+  if (!fs.existsSync(phasesDir)) return null;
+
+  try {
+    const dirs = fs.readdirSync(phasesDir);
+
+    // Try exact slug match first
+    if (phaseSlug) {
+      const match = dirs.find(d => d === phaseSlug);
+      if (match) return path.join(phasesDir, match);
+    }
+
+    // Fall back to phase number prefix
+    if (phaseNumber) {
+      const padded = String(phaseNumber).padStart(2, '0');
+      const match = dirs.find(d => d.startsWith(padded + '-'));
+      if (match) return path.join(phasesDir, match);
+    }
+  } catch (_e) {
+    // best-effort
+  }
+  return null;
+}
+
+function checkSummaryGate(data) {
+  const filePath = data.tool_input?.file_path || data.tool_input?.path || '';
+  if (!filePath) return null;
+
+  // Only check STATE.md writes
+  const normalizedPath = filePath.replace(/\\/g, '/');
+  if (!normalizedPath.endsWith('.planning/STATE.md')) return null;
+
+  // Get the new content being written
+  // For Write: tool_input.content
+  // For Edit: tool_input.new_string (partial — check for status changes)
+  const content = data.tool_input?.content || '';
+  const newString = data.tool_input?.new_string || '';
+  const textToCheck = content || newString;
+
+  if (!textToCheck) return null;
+
+  // Parse frontmatter from the content
+  const fm = parseFrontmatter(textToCheck);
+  const newStatus = (fm.status || '').toLowerCase();
+
+  // For Edit operations, check if the new_string contains a status advancement
+  let editAdvancing = false;
+  if (!content && newString) {
+    const statusMatch = newString.match(/status:\s*"?(\w+)"?/);
+    if (statusMatch) {
+      const editStatus = statusMatch[1].toLowerCase();
+      editAdvancing = ADVANCED_STATUSES.includes(editStatus);
+    }
+  }
+
+  // Only gate on status advancement
+  if (!ADVANCED_STATUSES.includes(newStatus) && !editAdvancing) return null;
+
+  // Determine phase from content
+  const cwd = process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+  const phaseSlug = fm.phase_slug || '';
+  const phaseNumber = fm.current_phase || '';
+
+  // Also try to extract from body text for Edit operations
+  let effectiveSlug = phaseSlug;
+  let effectiveNumber = phaseNumber;
+  if (!effectiveSlug && !effectiveNumber) {
+    const slugMatch = textToCheck.match(/phase_slug:\s*"?([^"\r\n]+)"?/);
+    const numMatch = textToCheck.match(/current_phase:\s*(\d+)/);
+    if (slugMatch) effectiveSlug = slugMatch[1].trim();
+    if (numMatch) effectiveNumber = numMatch[1];
+  }
+
+  // For Edit operations where we only see the diff, read current STATE.md
+  if (!effectiveSlug && !effectiveNumber) {
+    try {
+      const currentState = fs.readFileSync(path.join(planningDir, 'STATE.md'), 'utf8');
+      const currentFm = parseFrontmatter(currentState);
+      effectiveSlug = currentFm.phase_slug || '';
+      effectiveNumber = currentFm.current_phase || '';
+    } catch (_e) {
+      // Can't determine phase — allow the write
+      return null;
+    }
+  }
+
+  const phaseDir = findPhaseDir(planningDir, effectiveSlug, effectiveNumber);
+  if (!phaseDir) return null; // Can't find phase dir — don't block
+
+  if (hasSummaryFile(phaseDir)) return null; // SUMMARY exists — all good
+
+  const effectiveStatus = editAdvancing
+    ? (newString.match(/status:\s*"?(\w+)"?/) || [])[1]
+    : newStatus;
+
+  logHook('check-summary-gate', 'PreToolUse', 'block', {
+    status: effectiveStatus,
+    phase: effectiveSlug || effectiveNumber,
+    phaseDir: path.basename(phaseDir)
+  });
+
+  return {
+    exitCode: 2,
+    output: {
+      decision: 'block',
+      reason: `SUMMARY gate: Cannot set status to "${effectiveStatus}" — no SUMMARY file found in ${path.basename(phaseDir)}/.\n\nThe executor must write a SUMMARY-{plan_id}.md before STATE.md can advance. This prevents inconsistent state where a phase appears complete but has no build receipt.\n\nTo fix:\n  1. Run the executor to generate the SUMMARY file\n  2. Or manually create SUMMARY-{plan_id}.md in .planning/phases/${path.basename(phaseDir)}/`
+    }
+  };
+}
+
+// Standalone mode
+function main() {
+  let input = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => { input += chunk; });
+  process.stdin.on('end', () => {
+    try {
+      const data = JSON.parse(input);
+      const result = checkSummaryGate(data);
+      if (result) {
+        process.stdout.write(JSON.stringify(result.output));
+        process.exit(result.exitCode || 0);
+      }
+      process.exit(0);
+    } catch (_e) {
+      process.stdout.write(JSON.stringify({ additionalContext: '⚠ [PBR] check-summary-gate failed: ' + _e.message }));
+      process.exit(0);
+    }
+  });
+}
+
+module.exports = { checkSummaryGate, parseFrontmatter, hasSummaryFile, findPhaseDir, ADVANCED_STATUSES };
+if (require.main === module || process.argv[1] === __filename) { main(); }