@sienklogic/plan-build-run 2.21.1 → 2.21.2

package/plugins/pbr/scripts/post-write-dispatch.js

@@ -14,60 +14,230 @@
  *   - SUMMARY*.md or VERIFICATION.md in .planning/phases/ → state sync (auto-update tracking files)
  *   - Other files → exit immediately (no work needed)
  *
+ * Independent dispatch (RH-21):
+ *   All checks run independently — no early returns. Results are collected
+ *   into an array and merged into a single additionalContext response.
+ *   Individual check failures are logged via logHook() and do not prevent
+ *   other checks from running.
+ *
  * Exit codes:
  *   0 = always (PostToolUse hooks are advisory)
  */
 
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
 const { checkPlanWrite, checkStateWrite } = require('./check-plan-format');
 const { checkSync } = require('./check-roadmap-sync');
 const { checkStateSync } = require('./check-state-sync');
+const { checkQuality } = require('./post-write-quality');
+const { syncContextToClaude } = require('./sync-context-to-claude');
+const { checkReadFirst } = require('./check-read-first');
+
+// Conditionally import validateRoadmap (may not exist yet if PLAN-01 hasn't landed)
+let validateRoadmap;
+try {
+  const cpf = require('./check-plan-format');
+  validateRoadmap = cpf.validateRoadmap || null;
+} catch (_e) {
+  validateRoadmap = null;
+}
+
+/**
+ * Validate ROADMAP.md writes inside .planning/.
+ * @param {Object} data - Parsed hook input
+ * @returns {null|{output: Object}}
+ */
+function checkRoadmapWrite(data) {
+  const filePath = data.tool_input?.file_path || '';
+  if (!filePath.endsWith('ROADMAP.md')) return null;
+
+  // Only validate ROADMAP.md inside .planning/
+  const normalized = filePath.replace(/\\/g, '/');
+  if (!normalized.includes('.planning/') && !normalized.includes('.planning\\')) return null;
+
+  if (!validateRoadmap) return null;
+
+  const fs = require('fs');
+  if (!fs.existsSync(filePath)) return null;
+
+  const content = fs.readFileSync(filePath, 'utf8');
+  const result = validateRoadmap(content);
+  const combined = [...(result.errors || []), ...(result.warnings || [])];
+  if (combined.length > 0) {
+    return {
+      output: {
+        additionalContext: `[ROADMAP Validation] ${combined.join('; ')}`
+      }
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Route .planning/CONTEXT.md writes to the sync hook.
+ * Syncs Locked Decisions from CONTEXT.md into project CLAUDE.md.
+ * Always returns null (advisory only — never short-circuits other checks).
+ * @param {Object} data - Parsed hook input
+ * @returns {null}
+ */
+function checkContextWrite(data) {
+  const filePath = data.tool_input?.file_path || '';
+  const normalized = filePath.replace(/\\/g, '/');
+  // Only trigger for project-level CONTEXT.md inside .planning/
+  if (!normalized.endsWith('.planning/CONTEXT.md')) return null;
+  syncContextToClaude(process.env.PBR_PROJECT_ROOT || process.cwd());
+  return null; // Advisory only — no output needed
+}
+
+/**
+ * Core dispatch logic extracted for both stdin (main) and HTTP (handleHttp) paths.
+ *
+ * @param {Object} data - Parsed hook input (same as stdin JSON)
+ * @param {string} planningDir - Absolute path to .planning/ directory
+ * @returns {Promise<Object|null>} Hook response object or null
+ */
+async function processEvent(data, planningDir) {
+  const results = [];
+
+  /**
+   * Extract additionalContext string from a check result.
+   * Checks return various shapes: { output: { additionalContext } }, { additionalContext },
+   * { output: { decision, reason } }. Normalize to a string or null.
+   */
+  function extractContext(result) {
+    if (!result) return null;
+    const output = result.output || result;
+    if (output.additionalContext) return output.additionalContext;
+    if (output.decision && output.reason) return `[${output.decision}] ${output.reason}`;
+    return null;
+  }
+
+  // Route CONTEXT.md writes to sync hook (side-effect only, always returns null)
+  try {
+    checkContextWrite(data);
+  } catch (e) {
+    logHook('post-write-dispatch', 'PostToolUse', 'error', { check: 'checkContextWrite', error: e.message });
+  }
+
+  // Plan format check (PLAN.md, SUMMARY*.md)
+  // SUMMARY files trigger BOTH this check AND the state-sync check below.
+  try {
+    const planResult = await checkPlanWrite(data);
+    const ctx = extractContext(planResult);
+    if (ctx) results.push(ctx);
+  } catch (e) {
+    logHook('post-write-dispatch', 'PostToolUse', 'error', { check: 'checkPlanWrite', error: e.message });
+  }
+
+  // ROADMAP.md structural validation
+  try {
+    const roadmapResult = checkRoadmapWrite(data);
+    const ctx = extractContext(roadmapResult);
+    if (ctx) results.push(ctx);
+  } catch (e) {
+    logHook('post-write-dispatch', 'PostToolUse', 'error', { check: 'checkRoadmapWrite', error: e.message });
+  }
+
+  // Roadmap sync check (STATE.md)
+  try {
+    const syncResult = checkSync(data);
+    const ctx = extractContext(syncResult);
+    if (ctx) results.push(ctx);
+  } catch (e) {
+    logHook('post-write-dispatch', 'PostToolUse', 'error', { check: 'checkSync', error: e.message });
+  }
+
+  // STATE.md frontmatter validation (advisory only)
+  try {
+    const stateResult = await checkStateWrite(data);
+    const ctx = extractContext(stateResult);
+    if (ctx) results.push(ctx);
+  } catch (e) {
+    logHook('post-write-dispatch', 'PostToolUse', 'error', { check: 'checkStateWrite', error: e.message });
+  }
+
+  // State sync check (SUMMARY/VERIFICATION → STATE.md + ROADMAP.md)
+  try {
+    const stateSyncResult = await checkStateSync(data);
+    const ctx = extractContext(stateSyncResult);
+    if (ctx) results.push(ctx);
+  } catch (e) {
+    logHook('post-write-dispatch', 'PostToolUse', 'error', { check: 'checkStateSync', error: e.message });
+  }
+
+  // Quality checks (Prettier, tsc, console.log detection)
+  try {
+    const qualityResult = checkQuality(data);
+    const ctx = extractContext(qualityResult);
+    if (ctx) results.push(ctx);
+  } catch (e) {
+    logHook('post-write-dispatch', 'PostToolUse', 'error', { check: 'checkQuality', error: e.message });
+  }
+
+  // read_first enforcement (advisory)
+  try {
+    const rfResult = checkReadFirst(data, planningDir, data.session_id);
+    const ctx = extractContext(rfResult);
+    if (ctx) results.push(ctx);
+  } catch (e) {
+    logHook('post-write-dispatch', 'PostToolUse', 'error', { check: 'checkReadFirst', error: e.message });
+  }
+
+  // Merge all results into a single response
+  if (results.length > 0) {
+    return { additionalContext: results.join('\n') };
+  }
+
+  return null;
+}
+
+/**
+ * HTTP handler for hook-server.js.
+ * Called as handleHttp(reqBody, cache) where reqBody = { event, tool, data, planningDir, cache }.
+ * Must NOT call process.exit().
+ *
+ * @param {Object} reqBody - Request body from hook-server
+ * @param {Object} _cache - In-memory server cache (unused, config read from disk)
+ * @returns {Promise<Object|null>} Hook response or null
+ */
+async function handleHttp(reqBody, _cache) {
+  const data = reqBody.data || {};
+  const planningDir = reqBody.planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  try {
+    return await processEvent(data, planningDir);
+  } catch (_e) {
+    logHook('post-write-dispatch', 'PostToolUse', 'error', { error: _e.message, stack: (_e.stack || '').split('\n').slice(0, 3).join(' | ') });
+    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);
+      const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+      const planningDir = path.join(cwd, '.planning');
 
-      // Plan format check (PLAN.md, SUMMARY*.md)
-      // Note: SUMMARY files intentionally trigger BOTH this check AND the state-sync
-      // check below. The plan format check validates frontmatter structure, while
-      // state-sync auto-updates ROADMAP.md and STATE.md tracking fields.
-      const planResult = checkPlanWrite(data);
-      if (planResult) {
-        process.stdout.write(JSON.stringify(planResult.output));
-        process.exit(0);
+      const output = await processEvent(data, planningDir);
+      if (output) {
+        process.stdout.write(JSON.stringify(output));
       }
-
-      // Roadmap sync check (STATE.md)
-      const syncResult = checkSync(data);
-      if (syncResult) {
-        process.stdout.write(JSON.stringify(syncResult.output));
-        process.exit(0);
-      }
-
-      // STATE.md frontmatter validation (after roadmap sync, advisory only)
-      const stateResult = checkStateWrite(data);
-      if (stateResult) {
-        process.stdout.write(JSON.stringify(stateResult.output));
-        process.exit(0);
-      }
-
-      // State sync check (SUMMARY/VERIFICATION → STATE.md + ROADMAP.md)
-      const stateSyncResult = checkStateSync(data);
-      if (stateSyncResult) {
-        process.stdout.write(JSON.stringify(stateSyncResult.output));
-        process.exit(0);
-      }
-
       process.exit(0);
     } catch (_e) {
       // Don't block on parse errors
+      logHook('post-write-dispatch', 'PostToolUse', 'error', { error: _e.message, stack: (_e.stack || '').split('\n').slice(0, 3).join(' | ') });
+      process.stdout.write(JSON.stringify({ additionalContext: '⚠ [PBR] post-write-dispatch failed: ' + _e.message }));
       process.exit(0);
     }
   });
 }
 
+module.exports = { handleHttp, processEvent };
+
 if (require.main === module || process.argv[1] === __filename) { main(); }

package/plugins/pbr/scripts/post-write-quality.js

@@ -20,7 +20,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { execSync } = require('child_process');
+const { execFileSync } = require('child_process');
 const { logHook } = require('./hook-logger');
 
 const JS_TS_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs']);
@@ -40,6 +40,7 @@ function main() {
       }
       process.exit(0);
     } catch (_e) {
+      process.stdout.write(JSON.stringify({ additionalContext: '⚠ [PBR] post-write-quality failed: ' + _e.message }));
       process.exit(0);
     }
   });
@@ -132,7 +133,7 @@ function runPrettier(filePath, cwd) {
   if (!bin) return null;
 
   try {
-    execSync(`"${bin}" --write "${filePath}"`, {
+    execFileSync(bin, ['--write', filePath], {
       cwd,
       timeout: 15000,
       stdio: 'pipe',
@@ -154,7 +155,7 @@ function runTypeCheck(filePath, cwd) {
   if (!fs.existsSync(path.join(cwd, 'tsconfig.json'))) return null;
 
   try {
-    execSync(`"${bin}" --noEmit`, {
+    execFileSync(bin, ['--noEmit'], {
       cwd,
       timeout: 30000,
       stdio: 'pipe',

package/plugins/pbr/scripts/pre-bash-dispatch.js

@@ -7,29 +7,29 @@
  * into a single process, reading stdin once and routing to both
  * checks sequentially. This halves the process spawns per Bash call.
  *
- * ── Dispatch Order & Rationale ──────────────────────────────────
+ * -- Dispatch Order & Rationale --
  *
- *   1. check-dangerous-commands — Blocks destructive shell operations
+ *   1. check-dangerous-commands -- Blocks destructive shell operations
  *      (rm -rf, git push --force, etc.). Runs first because safety
  *      takes priority: if a command is dangerous, we must reject it
  *      before even considering whether its commit message is valid.
  *      Can block (exit 2).
  *
- *   2. validate-commit          — Enforces conventional commit format
+ *   2. validate-commit          -- Enforces conventional commit format
  *      ({type}({scope}): {desc}) on git commit commands. Runs second
  *      because commit format validation is only relevant for git
  *      commit operations, a narrow subset of all Bash calls. There's
  *      no benefit to checking format if the command was already
  *      blocked as dangerous. Can block (exit 2).
  *
- * ── Short-Circuit Behavior ──────────────────────────────────────
+ * -- Short-Circuit Behavior --
  *
  *   If an earlier check returns a result (blocking with exit 2),
  *   later checks are skipped entirely. The first failure is the
- *   most relevant — a dangerous command should be blocked regardless
+ *   most relevant -- a dangerous command should be blocked regardless
  *   of whether it also has a valid commit message.
  *
- * ── Adding New Checks ───────────────────────────────────────────
+ * -- Adding New Checks --
  *
  *   1. Create a new check module exporting a function that takes
  *      the parsed hook data and returns null (pass) or
@@ -49,65 +49,161 @@
 const { logHook } = require('./hook-logger');
 const { checkDangerous } = require('./check-dangerous-commands');
 const { checkCommit } = require('./validate-commit');
+const { checkUnmanagedCommit } = require('./enforce-pbr-workflow');
+const { checkRequirePaths, checkMirrorSync, checkLintErrors } = require('./lib/pre-commit-checks');
+// Cross-plugin sync disabled -- derivative plugins updated separately
+// const { checkCrossPluginSync } = require('./check-cross-plugin-sync');
+
+/**
+ * Core dispatch logic extracted for both stdin (main) and HTTP (handleHttp) paths.
+ *
+ * Runs all checks sequentially. Block decisions short-circuit immediately.
+ * Warnings are collected and merged into a single advisory response.
+ *
+ * @param {Object} data - Parsed hook input (same as stdin JSON)
+ * @returns {Promise<Object|null>} Hook response: { decision: 'block', reason } or { decision: 'allow', additionalContext? } or null
+ */
+async function processEvent(data) {
+  try {
+    // Dangerous commands check first -- can block
+    const dangerousResult = checkDangerous(data);
+    if (dangerousResult) {
+      logHook('pre-bash-dispatch', 'PreToolUse', 'dispatched', { handler: 'check-dangerous-commands' });
+      if (dangerousResult.exitCode === 2) {
+        return { decision: 'block', reason: dangerousResult.output.reason || dangerousResult.output.additionalContext || 'Dangerous command blocked' };
+      }
+    }
+
+    // Commit validation check -- can block
+    const commitResult = checkCommit(data);
+    if (commitResult) {
+      logHook('pre-bash-dispatch', 'PreToolUse', 'dispatched', { handler: 'validate-commit' });
+      if (commitResult.exitCode === 2) {
+        return { decision: 'block', reason: commitResult.output.reason || commitResult.output.additionalContext || 'Invalid commit format' };
+      }
+      // exitCode 0 with output = warning
+      if (commitResult.output && commitResult.output.additionalContext) {
+        // Collect as warning below
+      }
+    }
+
+    // Soft warnings for risky-but-allowed commands
+    const command = data.tool_input?.command || '';
+    const warnings = [];
+
+    // Carry forward commit warning if it was advisory (exitCode 0)
+    if (commitResult && commitResult.exitCode === 0 && commitResult.output && commitResult.output.additionalContext) {
+      warnings.push(commitResult.output.additionalContext);
+    }
+
+    if (command) {
+      // Warn about npm publish / deploy commands
+      if (/\bnpm\s+publish\b/.test(command)) {
+        warnings.push('npm publish detected -- ensure version is correct before publishing');
+      }
+
+      // Warn about touching production config files
+      if (/\b(production|prod)\b.*\.(json|ya?ml|env|conf|cfg)\b/i.test(command) ||
+          /\.(json|ya?ml|env|conf|cfg)\b.*\b(production|prod)\b/i.test(command)) {
+        warnings.push('command references production config files -- verify you are not in a live environment');
+      }
+
+      // Warn about database operations
+      if (/\b(DROP|TRUNCATE|DELETE\s+FROM|ALTER\s+TABLE)\b/i.test(command)) {
+        warnings.push('destructive database operation (DROP/TRUNCATE/DELETE/ALTER) -- verify correct database is targeted and a backup exists');
+      }
+    }
+
+    // Pre-commit quality checks -- advisory only, on git commit commands
+    if (/\bgit\s+commit\b/.test(command)) {
+      const pathResult = checkRequirePaths(data);
+      if (pathResult) warnings.push(...pathResult.warnings);
+
+      const mirrorResult = checkMirrorSync(data);
+      if (mirrorResult) warnings.push(...mirrorResult.warnings);
+
+      const lintResult = checkLintErrors(data);
+      if (lintResult) warnings.push(...lintResult.warnings);
+    }
+
+    // Unmanaged commit advisory -- warn when git commit runs without PBR skill
+    const unmanagedCommitResult = checkUnmanagedCommit(data);
+    if (unmanagedCommitResult) {
+      warnings.push(unmanagedCommitResult.output.additionalContext);
+    }
+
+    // Cross-plugin sync advisory -- disabled (derivative plugins updated separately)
+    // const syncResult = checkCrossPluginSync(data);
+    // if (syncResult) {
+    //   warnings.push(syncResult.additionalContext);
+    // }
+
+    if (warnings.length > 0) {
+      logHook('pre-bash-dispatch', 'PreToolUse', 'warn', { warnings: warnings.length, cmd: command.substring(0, 80) });
+      return {
+        decision: 'allow',
+        additionalContext: `[pbr] Advisory: ${warnings.join('; ')}.`
+      };
+    }
+
+    // Log pass-through so hook activity is visible in logs AND session JSONL
+    logHook('pre-bash-dispatch', 'PreToolUse', 'allow', { cmd: command.substring(0, 80) });
+    return { decision: 'allow' };
+  } catch (e) {
+    logHook('pre-bash-dispatch', 'PreToolUse', 'error', { error: e.message });
+    return null;
+  }
+}
+
+/**
+ * HTTP handler for hook-server.js.
+ * Called as handleHttp(reqBody, cache) where reqBody = { event, tool, data, planningDir, cache }.
+ * Must NOT call process.exit().
+ *
+ * @param {Object} reqBody - Request body from hook-server
+ * @param {Object} _cache - In-memory server cache (unused)
+ * @returns {Promise<Object|null>} Hook response or null
+ */
+async function handleHttp(reqBody, _cache) {
+  const data = reqBody.data || {};
+  try {
+    return await processEvent(data);
+  } catch (_e) {
+    logHook('pre-bash-dispatch', 'PreToolUse', 'error', { error: _e.message });
+    return null;
+  }
+}
+
+module.exports = { handleHttp, processEvent };
 
 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);
 
-      // Dangerous commands check first — can block
-      const dangerousResult = checkDangerous(data);
-      if (dangerousResult) {
-        logHook('pre-bash-dispatch', 'PreToolUse', 'dispatched', { handler: 'check-dangerous-commands' });
-        process.stdout.write(JSON.stringify(dangerousResult.output));
-        process.exit(dangerousResult.exitCode);
-      }
+      const result = await processEvent(data);
 
-      // Commit validation check — can block
-      const commitResult = checkCommit(data);
-      if (commitResult) {
-        logHook('pre-bash-dispatch', 'PreToolUse', 'dispatched', { handler: 'validate-commit' });
-        process.stdout.write(JSON.stringify(commitResult.output));
-        process.exit(commitResult.exitCode);
+      if (result && result.decision === 'block') {
+        process.stdout.write(JSON.stringify(result));
+        process.exit(2);
       }
 
-      // Soft warnings for risky-but-allowed commands
-      const command = data.tool_input?.command || '';
-      if (command) {
-        const warnings = [];
-
-        // Warn about npm publish / deploy commands
-        if (/\bnpm\s+publish\b/.test(command)) {
-          warnings.push('npm publish detected — ensure version is correct before publishing');
-        }
-
-        // Warn about touching production config files
-        if (/\b(production|prod)\b.*\.(json|ya?ml|env|conf|cfg)\b/i.test(command) ||
-            /\.(json|ya?ml|env|conf|cfg)\b.*\b(production|prod)\b/i.test(command)) {
-          warnings.push('command references production config files');
-        }
-
-        // Warn about database operations
-        if (/\b(DROP|TRUNCATE|DELETE\s+FROM|ALTER\s+TABLE)\b/i.test(command)) {
-          warnings.push('destructive database operation detected — verify target');
-        }
-
-        if (warnings.length > 0) {
-          process.stdout.write(JSON.stringify({
-            decision: 'allow',
-            additionalContext: `[pbr] Advisory: ${warnings.join('; ')}.`
-          }));
-          process.exit(0);
-        }
+      if (result) {
+        process.stdout.write(JSON.stringify(result));
+      } else {
+        // processEvent returned null (error) -- allow through
+        process.stdout.write(JSON.stringify({ decision: 'allow' }));
       }
-
       process.exit(0);
-    } catch (_e) {
-      // Don't block on errors
+    } catch (e) {
+      // Don't block on errors -- but emit valid output so Claude Code
+      // doesn't report "hook error" for silent exit
+      process.stderr.write(`[pbr] pre-bash-dispatch error: ${e.message}\n`);
+      process.stdout.write(JSON.stringify({ decision: 'allow', additionalContext: '\u26a0 [PBR] pre-bash-dispatch failed: ' + e.message }));
       process.exit(0);
     }
   });

package/plugins/pbr/scripts/pre-skill-dispatch.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+
+/**
+ * PreToolUse dispatcher for Skill hooks.
+ *
+ * Consolidates enforce-context-budget.js and validate-skill-args.js
+ * into a single process, reading stdin once and routing to both
+ * checks sequentially. Budget check runs first (cheap) and
+ * short-circuits before skill argument validation.
+ *
+ * ── Dispatch Order & Rationale ──────────────────────────────────
+ *
+ *   1. enforce-context-budget — Blocks Skill invocations when context
+ *      usage exceeds the hard_stop_percent threshold. Runs first
+ *      because it is a cheap file read that can short-circuit before
+ *      argument validation.
+ *
+ *   2. validate-skill-args   — Validates skill arguments (phase
+ *      number existence, freeform text detection for /pbr:plan-phase).
+ *      Can block (exit 2) or allow (exit 0).
+ *
+ * Exit codes:
+ *   0 = allowed or warning only
+ *   2 = blocked (budget exceeded or invalid skill args)
+ */
+
+const path = require('path');
+const { logHook } = require('./hook-logger');
+const { checkBudget } = require('./enforce-context-budget');
+const { checkSkillArgs } = require('./validate-skill-args');
+
+/**
+ * Core dispatch logic for PreToolUse:Skill events.
+ *
+ * Step 1: Budget check (cheap, fast — short-circuits on block)
+ * Step 2: Skill argument validation
+ * Step 3: All clear
+ *
+ * @param {Object} data - Parsed hook event data
+ * @returns {Object} { decision: 'block'|'allow', reason?: string, additionalContext?: string }
+ */
+async function processEvent(data) {
+  // Step 1 — Budget check (cheap, fast)
+  const planningDir = path.join(data.cwd || process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const budgetResult = checkBudget({ toolName: 'Skill', planningDir });
+  if (budgetResult) {
+    logHook('pre-skill-dispatch', 'PreToolUse', 'blocked', { handler: 'enforce-context-budget' });
+    return budgetResult; // already { decision: 'block', reason: '...' }
+  }
+
+  // Step 2 — Skill argument validation
+  const skillResult = checkSkillArgs(data);
+  if (skillResult) {
+    if (skillResult.exitCode === 2) {
+      // Blocking result
+      logHook('pre-skill-dispatch', 'PreToolUse', 'blocked', { handler: 'validate-skill-args' });
+      return skillResult.output; // { decision: 'block', reason: '...' }
+    }
+    // Advisory result (exitCode 0 with output)
+    if (skillResult.output) {
+      logHook('pre-skill-dispatch', 'PreToolUse', 'warn', { handler: 'validate-skill-args' });
+      return skillResult.output;
+    }
+  }
+
+  // Step 3 — All clear
+  logHook('pre-skill-dispatch', 'PreToolUse', 'allow', {});
+  return { decision: 'allow' };
+}
+
+/**
+ * HTTP handler for hook-server integration.
+ *
+ * @param {Object} reqBody - HTTP request body with { data: {...} }
+ * @param {Object} _cache - Hook server cache (unused)
+ * @returns {Object|null} Hook result or null on error
+ */
+async function handleHttp(reqBody, _cache) {
+  try {
+    const data = reqBody.data || {};
+    return await processEvent(data);
+  } catch (_e) {
+    return null;
+  }
+}
+
+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);
+      const result = await processEvent(data);
+
+      if (result && result.decision === 'block') {
+        process.stdout.write(JSON.stringify(result));
+        process.exit(2);
+        return;
+      }
+
+      process.stdout.write(JSON.stringify(result || {}));
+      process.exit(0);
+    } catch (_e) {
+      process.stderr.write(`[pbr] pre-skill-dispatch error: ${_e.message}\n`);
+      process.stdout.write(JSON.stringify({ decision: 'allow', additionalContext: '[PBR] pre-skill-dispatch failed: ' + _e.message }));
+      process.exit(0);
+    }
+  });
+}
+
+module.exports = { handleHttp, processEvent };
+if (require.main === module || process.argv[1] === __filename) { main(); }