@sienklogic/plan-build-run 2.19.0 → 2.19.2

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

@@ -0,0 +1,271 @@
+#!/usr/bin/env node
+
+/**
+ * PreToolUse hook: Validates Task() calls before execution.
+ *
+ * Blocking checks (exit 2):
+ *   - When active skill is "quick" and pbr:executor is spawned without
+ *     a PLAN.md in .planning/quick/{NNN}-{slug}/
+ *
+ * Advisory checks (exit 0, logs warnings):
+ *   - description exists and is non-empty
+ *   - description is reasonably short (<=100 chars)
+ *   - subagent_type is a known pbr: agent type when applicable
+ *
+ * Exit codes:
+ *   0 = pass (advisory warnings only)
+ *   2 = block (missing quick task PLAN.md)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+const { checkNonPbrAgent } = require('./enforce-pbr-workflow');
+const { KNOWN_AGENTS } = require('./lib/core');
+
+// 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 { checkPlanValidationGate } = require('./lib/gates/plan-validation');
+const { checkDebuggerAdvisory, checkCheckpointManifest, checkActiveSkillIntegrity } = require('./lib/gates/advisories');
+const { checkDocExistence } = require('./lib/gates/doc-existence');
+const { checkUserConfirmationGate } = require('./lib/gates/user-confirmation');
+
+const MAX_DESCRIPTION_LENGTH = 100;
+
+/**
+ * Check a parsed hook data object for Task() validation issues.
+ * Returns an array of warning strings (empty if all good).
+ */
+function checkTask(data) {
+  const warnings = [];
+  const toolInput = data.tool_input || {};
+
+  const description = toolInput.description;
+  const subagentType = toolInput.subagent_type;
+
+  // Check description exists and is non-empty
+  if (!description || (typeof description === 'string' && !description.trim())) {
+    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) {
+      warnings.push(
+        `Task() description is ${description.length} chars (recommended <=100). ` +
+        'Keep descriptions to 3-5 words.'
+      );
+    }
+
+    // If description mentions pbr: patterns but no subagent_type is set
+    if (/\bpbr:/.test(description) && !subagentType) {
+      warnings.push(
+        'Task() description contains "pbr:" but no subagent_type is set. ' +
+        'Use subagent_type: "pbr:{name}" for automatic agent loading.'
+      );
+    }
+  }
+
+  // Validate subagent_type if it starts with pbr:
+  if (typeof subagentType === 'string' && subagentType.startsWith('pbr:')) {
+    const agentName = subagentType.slice(4);
+    if (!KNOWN_AGENTS.includes(agentName)) {
+      warnings.push(
+        `Unknown pbr agent type: "${subagentType}". ` +
+        `Known types: ${KNOWN_AGENTS.map(a => 'pbr:' + a).join(', ')}`
+      );
+    }
+  }
+
+  return warnings;
+}
+
+function main() {
+  let input = '';
+
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => { input += chunk; });
+  process.stdin.on('end', async () => {
+    try {
+      const data = JSON.parse(input);
+
+      // Blocking gate: user confirmation required for gated operations
+      const userConfGate = checkUserConfirmationGate(data);
+      if (userConfGate && userConfGate.block) {
+        logHook('validate-task', 'PreToolUse', 'blocked', { reason: userConfGate.reason });
+        process.stdout.write(JSON.stringify({
+          decision: 'block',
+          reason: userConfGate.reason
+        }));
+        process.exit(2);
+        return;
+      }
+      // Advisory: non-blocking user confirmation warning
+      if (userConfGate && userConfGate.warning) {
+        logHook('validate-task', 'PreToolUse', 'warn', { warning: userConfGate.warning });
+      }
+
+      // Blocking gate: quick executor must have PLAN.md
+      const gate = checkQuickExecutorGate(data);
+      if (gate && gate.block) {
+        logHook('validate-task', 'PreToolUse', 'blocked', { reason: gate.reason });
+        process.stdout.write(JSON.stringify({
+          decision: 'block',
+          reason: gate.reason
+        }));
+        process.exit(2);
+        return;
+      }
+
+      // Blocking gate: build executor must have PLAN.md in phase dir
+      const buildGate = checkBuildExecutorGate(data);
+      if (buildGate && buildGate.block) {
+        logHook('validate-task', 'PreToolUse', 'blocked', { reason: buildGate.reason });
+        process.stdout.write(JSON.stringify({
+          decision: 'block',
+          reason: buildGate.reason
+        }));
+        process.exit(2);
+        return;
+      }
+
+      // Blocking gate: plan validation artifact must exist and pass
+      const planValGate = checkPlanValidationGate(data);
+      if (planValGate && planValGate.block) {
+        logHook('validate-task', 'PreToolUse', 'blocked', { reason: planValGate.reason });
+        process.stdout.write(JSON.stringify({ decision: 'block', reason: planValGate.reason }));
+        process.exit(2);
+        return;
+      }
+
+      // Blocking gate: review skill planner needs VERIFICATION.md
+      const reviewGate = checkReviewPlannerGate(data);
+      if (reviewGate && reviewGate.block) {
+        logHook('validate-task', 'PreToolUse', 'blocked', { reason: reviewGate.reason });
+        process.stdout.write(JSON.stringify({
+          decision: 'block',
+          reason: reviewGate.reason
+        }));
+        process.exit(2);
+        return;
+      }
+
+      // Blocking gate: plan skill cannot spawn executors
+      const planGate = checkPlanExecutorGate(data);
+      if (planGate && planGate.block) {
+        logHook('validate-task', 'PreToolUse', 'blocked', { reason: planGate.reason });
+        process.stdout.write(JSON.stringify({
+          decision: 'block',
+          reason: planGate.reason
+        }));
+        process.exit(2);
+        return;
+      }
+
+      // Blocking gate: review verifier needs SUMMARY.md
+      const reviewVerifierGate = checkReviewVerifierGate(data);
+      if (reviewVerifierGate && reviewVerifierGate.block) {
+        logHook('validate-task', 'PreToolUse', 'blocked', { reason: reviewVerifierGate.reason });
+        process.stdout.write(JSON.stringify({
+          decision: 'block',
+          reason: reviewVerifierGate.reason
+        }));
+        process.exit(2);
+        return;
+      }
+
+      // Blocking gate: milestone complete needs all phases verified
+      const milestoneGate = checkMilestoneCompleteGate(data);
+      if (milestoneGate && milestoneGate.block) {
+        logHook('validate-task', 'PreToolUse', 'blocked', { reason: milestoneGate.reason });
+        process.stdout.write(JSON.stringify({
+          decision: 'block',
+          reason: milestoneGate.reason
+        }));
+        process.exit(2);
+        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) {
+        logHook('validate-task', 'PreToolUse', 'blocked', { reason: buildDepGate.reason });
+        process.stdout.write(JSON.stringify({
+          decision: 'block',
+          reason: buildDepGate.reason
+        }));
+        process.exit(2);
+        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);
+      if (userConfGate && userConfGate.warning) warnings.push(userConfGate.warning);
+      const manifestWarning = checkCheckpointManifest(data);
+      if (manifestWarning) warnings.push(manifestWarning);
+      const debuggerWarning = checkDebuggerAdvisory(data);
+      if (debuggerWarning) warnings.push(debuggerWarning);
+      const activeSkillWarning = checkActiveSkillIntegrity(data);
+      if (activeSkillWarning) warnings.push(activeSkillWarning);
+      if (nonPbrAgentResult) warnings.push(nonPbrAgentResult.output.additionalContext);
+      if (planValGate && planValGate.warning) warnings.push(planValGate.warning);
+
+      if (warnings.length > 0) {
+        for (const warning of warnings) {
+          logHook('validate-task', 'PreToolUse', 'warn', { warning });
+        }
+        process.stdout.write(JSON.stringify({
+          additionalContext: 'Task() validation warnings:\n' + warnings.map(w => '- ' + w).join('\n')
+        }));
+      }
+
+      process.exit(0);
+    } catch (_e) {
+      // 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", additionalContext: '⚠ [PBR] validate-task failed: ' + _e.message }));
+      process.exit(0);
+    }
+  });
+}
+
+module.exports = { checkTask, checkQuickExecutorGate, checkBuildExecutorGate, checkPlanValidationGate, checkPlanExecutorGate, checkReviewPlannerGate, checkReviewVerifierGate, checkMilestoneCompleteGate, checkMilestoneSummaryGate, checkBuildDependencyGate, checkCheckpointManifest, checkDebuggerAdvisory, getVerificationStatus, checkActiveSkillIntegrity, checkDocExistence, checkUserConfirmationGate, KNOWN_AGENTS, MAX_DESCRIPTION_LENGTH };
+if (require.main === module || process.argv[1] === __filename) { main(); }

package/plugins/pbr/dist/worktree-create.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+
+/**
+ * WorktreeCreate hook: Initializes .planning/ directory structure in new git worktrees.
+ *
+ * Fires when a new git worktree is created. Copies the minimal .planning/ structure
+ * from the parent project so PBR skills work correctly in the new worktree context.
+ *
+ * Non-blocking — always exits 0.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+
+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 main() {
+  try {
+    const data = readStdin();
+
+    const worktreePath = data.worktree_path || process.env.PBR_PROJECT_ROOT || process.cwd();
+    const parentRoot = data.project_root || process.env.PBR_PROJECT_ROOT || process.cwd();
+
+    const planningDir = path.join(worktreePath, '.planning');
+    const parentPlanningDir = path.join(parentRoot, '.planning');
+
+    // Skip if parent has no .planning/ — not a PBR project
+    if (!fs.existsSync(parentPlanningDir)) {
+      logHook('worktree-create', 'WorktreeCreate', 'skip-no-parent', { worktree_path: worktreePath });
+      process.stdout.write(JSON.stringify({ additionalContext: '[Plan-Build-Run] Worktree skip — no parent .planning/ found.' }));
+      process.exit(0); return;
+    }
+
+    // Skip if worktree already has .planning/ initialized
+    if (fs.existsSync(planningDir)) {
+      logHook('worktree-create', 'WorktreeCreate', 'skip-exists', { worktree_path: worktreePath });
+      process.stdout.write(JSON.stringify({ additionalContext: '[Plan-Build-Run] Worktree .planning/ already initialized.' }));
+      process.exit(0); return;
+    }
+
+    // Create .planning/ directory
+    fs.mkdirSync(planningDir, { recursive: true });
+
+    // Create .planning/logs/ directory
+    fs.mkdirSync(path.join(planningDir, 'logs'), { recursive: true });
+
+    // Write a minimal STATE.md
+    const stateMd = `# STATE
+
+## Current Position
+phase: (none)
+status: Worktree initialized — run /pbr:resume-work or /pbr:progress for project state.
+
+## Source
+parent: ${parentRoot}
+initialized: ${new Date().toISOString()}
+`;
+    fs.writeFileSync(path.join(planningDir, 'STATE.md'), stateMd, 'utf8');
+
+    // Copy config.json from parent if it exists
+    try {
+      const srcConfig = path.join(parentPlanningDir, 'config.json');
+      const destConfig = path.join(planningDir, 'config.json');
+      if (fs.existsSync(srcConfig)) {
+        fs.copyFileSync(srcConfig, destConfig);
+      }
+    } catch (_e) { /* non-fatal — config copy is best-effort */ }
+
+    logHook('worktree-create', 'WorktreeCreate', 'initialized', {
+      worktree_path: worktreePath,
+      parent_root: parentRoot
+    });
+
+    process.stdout.write(JSON.stringify({
+      additionalContext: '[Plan-Build-Run] Worktree .planning/ initialized. Run /pbr:progress to see project state.'
+    }));
+
+    process.exit(0);
+  } catch (err) {
+    logHook('worktree-create', 'WorktreeCreate', 'error', { error: err.message });
+    process.stdout.write(JSON.stringify({ additionalContext: `[Plan-Build-Run] Worktree init error: ${err.message}` }));
+    process.exit(0);
+  }
+}
+
+/**
+ * handleHttp — hook-server.js interface.
+ * reqBody = { event, tool, data, planningDir, cache }
+ * Returns { additionalContext: "..." } or null. Never calls process.exit().
+ */
+function handleHttp(reqBody) {
+  try {
+    const data = (reqBody && reqBody.data) || {};
+    const worktreePath = data.worktree_path || process.env.PBR_PROJECT_ROOT || process.cwd();
+    const parentRoot = data.project_root || process.env.PBR_PROJECT_ROOT || process.cwd();
+
+    const planningDir = path.join(worktreePath, '.planning');
+    const parentPlanningDir = path.join(parentRoot, '.planning');
+
+    if (!fs.existsSync(parentPlanningDir)) {
+      logHook('worktree-create', 'WorktreeCreate', 'skip-no-parent', { worktree_path: worktreePath });
+      return { additionalContext: '[Plan-Build-Run] Worktree skip — no parent .planning/ found.' };
+    }
+
+    if (fs.existsSync(planningDir)) {
+      logHook('worktree-create', 'WorktreeCreate', 'skip-exists', { worktree_path: worktreePath });
+      return { additionalContext: '[Plan-Build-Run] Worktree .planning/ already initialized.' };
+    }
+
+    fs.mkdirSync(planningDir, { recursive: true });
+    fs.mkdirSync(path.join(planningDir, 'logs'), { recursive: true });
+
+    const stateMd = `# STATE\n\n## Current Position\nphase: (none)\nstatus: Worktree initialized — run /pbr:resume-work or /pbr:progress for project state.\n\n## Source\nparent: ${parentRoot}\ninitialized: ${new Date().toISOString()}\n`;
+    fs.writeFileSync(path.join(planningDir, 'STATE.md'), stateMd, 'utf8');
+
+    try {
+      const srcConfig = path.join(parentPlanningDir, 'config.json');
+      const destConfig = path.join(planningDir, 'config.json');
+      if (fs.existsSync(srcConfig)) fs.copyFileSync(srcConfig, destConfig);
+    } catch (_e) { /* non-fatal */ }
+
+    logHook('worktree-create', 'WorktreeCreate', 'initialized', {
+      worktree_path: worktreePath,
+      parent_root: parentRoot
+    });
+
+    return { additionalContext: '[Plan-Build-Run] Worktree .planning/ initialized. Run /pbr:progress to see project state.' };
+  } catch (err) {
+    logHook('worktree-create', 'WorktreeCreate', 'error', { error: err.message });
+    return { additionalContext: `[Plan-Build-Run] Worktree init error: ${err.message}` };
+  }
+}
+
+if (require.main === module || process.argv[1] === __filename) { main(); }
+module.exports = { main, handleHttp };

package/plugins/pbr/dist/worktree-remove.js

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+
+/**
+ * WorktreeRemove hook: Cleans up worktree-specific .planning/ state on git worktree removal.
+ *
+ * Fires when a git worktree is removed. Performs non-destructive cleanup of
+ * session-specific files only. Guards against accidentally cleaning the parent
+ * project's .planning/ directory.
+ *
+ * Non-blocking — always exits 0.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+
+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 main() {
+  try {
+    const data = readStdin();
+
+    const worktreePath = data.worktree_path || process.env.PBR_PROJECT_ROOT || process.cwd();
+    const planningDir = path.join(worktreePath, '.planning');
+
+    // Skip if no .planning/ exists in worktree
+    if (!fs.existsSync(planningDir)) {
+      logHook('worktree-remove', 'WorktreeRemove', 'skip-no-planning', { worktree_path: worktreePath });
+      process.stdout.write('{}');
+      process.exit(0); return;
+    }
+
+    // Guard: only clean up if STATE.md has the "parent:" marker — this indicates
+    // it was initialized by worktree-create.js and is safe to clean up.
+    // If STATE.md has no "parent:" line, this might be the parent project itself.
+    const stateMdPath = path.join(planningDir, 'STATE.md');
+    if (fs.existsSync(stateMdPath)) {
+      const stateContent = fs.readFileSync(stateMdPath, 'utf8');
+      if (!stateContent.includes('parent:')) {
+        logHook('worktree-remove', 'WorktreeRemove', 'skip-not-worktree', { worktree_path: worktreePath });
+        process.stdout.write('{}');
+        process.exit(0); return;
+      }
+    }
+
+    // Non-destructive cleanup: remove session-specific files only
+    const sessionFiles = [
+      '.session.json',
+      '.session-start',
+      '.active-skill',
+      '.auto-next'
+    ];
+
+    for (const filename of sessionFiles) {
+      try {
+        const filePath = path.join(planningDir, filename);
+        if (fs.existsSync(filePath)) {
+          fs.unlinkSync(filePath);
+        }
+      } catch (_e) { /* non-fatal — best-effort cleanup */ }
+    }
+
+    // Remove .sessions/ directory (session-scoped state)
+    try {
+      const sessionsDir = path.join(planningDir, '.sessions');
+      if (fs.existsSync(sessionsDir)) {
+        fs.rmSync(sessionsDir, { recursive: true, force: true });
+      }
+    } catch (_e) { /* non-fatal — best-effort cleanup */ }
+
+    logHook('worktree-remove', 'WorktreeRemove', 'cleaned', {
+      worktree_path: worktreePath,
+      files_removed: ['session files']
+    });
+
+    process.stdout.write('{}');
+    process.exit(0);
+  } catch (err) {
+    logHook('worktree-remove', 'WorktreeRemove', 'error', { error: err.message });
+    process.stdout.write(JSON.stringify({ additionalContext: '⚠ [PBR] worktree-remove failed: ' + err.message }));
+    process.exit(0);
+  }
+}
+
+/**
+ * handleHttp — hook-server.js interface.
+ * reqBody = { event, tool, data, planningDir, cache }
+ * Returns null. Never calls process.exit().
+ */
+function handleHttp(reqBody) {
+  try {
+    const data = (reqBody && reqBody.data) || {};
+    const worktreePath = data.worktree_path || process.env.PBR_PROJECT_ROOT || process.cwd();
+    const planningDir = path.join(worktreePath, '.planning');
+
+    if (!fs.existsSync(planningDir)) {
+      logHook('worktree-remove', 'WorktreeRemove', 'skip-no-planning', { worktree_path: worktreePath });
+      return {};
+    }
+
+    const stateMdPath = path.join(planningDir, 'STATE.md');
+    if (fs.existsSync(stateMdPath)) {
+      const stateContent = fs.readFileSync(stateMdPath, 'utf8');
+      if (!stateContent.includes('parent:')) {
+        logHook('worktree-remove', 'WorktreeRemove', 'skip-not-worktree', { worktree_path: worktreePath });
+        return {};
+      }
+    }
+
+    const sessionFiles = ['.session.json', '.session-start', '.active-skill', '.auto-next'];
+    for (const filename of sessionFiles) {
+      try {
+        const filePath = path.join(planningDir, filename);
+        if (fs.existsSync(filePath)) fs.unlinkSync(filePath);
+      } catch (_e) { /* non-fatal */ }
+    }
+
+    // Remove .sessions/ directory (session-scoped state)
+    try {
+      const sessionsDir = path.join(planningDir, '.sessions');
+      if (fs.existsSync(sessionsDir)) {
+        fs.rmSync(sessionsDir, { recursive: true, force: true });
+      }
+    } catch (_e) { /* non-fatal */ }
+
+    logHook('worktree-remove', 'WorktreeRemove', 'cleaned', {
+      worktree_path: worktreePath,
+      files_removed: ['session files']
+    });
+
+    return {};
+  } catch (err) {
+    logHook('worktree-remove', 'WorktreeRemove', 'error', { error: err.message });
+    return {};
+  }
+}
+
+if (require.main === module || process.argv[1] === __filename) { main(); }
+module.exports = { main, handleHttp };