@sienklogic/plan-build-run 2.19.0 → 2.19.2

package/plugins/pbr/dist/auto-continue.js

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+
+/**
+ * Stop hook: Auto-continue via config flag (with signal file backward compat).
+ *
+ * When enabled (features.auto_continue: true in config.json),
+ * reads workflow._auto_chain_active from config.json on session stop.
+ * If set, reads the next command and clears the flag (one-shot).
+ * Falls back to .planning/.auto-next signal file for backward compat.
+ *
+ * Hard stops (flag NOT set):
+ * - Milestone completion
+ * - human_needed flag set
+ * - Execution errors
+ * - Gap closure attempted 3+ times
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+const { logHook } = require('./hook-logger');
+const { configLoad } = require('./lib/config');
+const { loadTracker } = require('./session-tracker');
+const { resolveSessionPath } = require('./lib/core');
+
+function main() {
+  try {
+    // Parse hook input from stdin (Claude Code passes JSON with stop_hook_active flag)
+    let hookInput = {};
+    try {
+      const stdin = fs.readFileSync(0, 'utf8').trim();
+      if (stdin) hookInput = JSON.parse(stdin);
+    } catch (_parseErr) {
+      // No stdin or invalid JSON — proceed with defaults
+    }
+
+    // Guard against infinite loops: if we're already in a Stop hook continuation, bail out
+    if (hookInput.stop_hook_active) {
+      logHook('auto-continue', 'Stop', 'already-active', {});
+      process.exit(0);
+    }
+
+    const cwd = hookInput.cwd || process.cwd();
+    const planningDir = path.join(cwd, '.planning');
+    const sessionId = hookInput.session_id || null;
+    const signalPath = sessionId
+      ? resolveSessionPath(planningDir, '.auto-next', sessionId)
+      : path.join(planningDir, '.auto-next');
+
+    // Check if auto-continue is enabled
+    const config = configLoad(planningDir);
+    if (!config || !config.features || !config.features.auto_continue) {
+      process.exit(0);
+    }
+
+    // Phase-limit detection: check if session has completed enough phases to trigger a cycle
+    // Scale default limit with context window: 3 at 200k, 6 at 500k+, 8 at 1M
+    const tracker = loadTracker(planningDir, sessionId);
+    let phaseLimit;
+    if (config.session_phase_limit !== undefined) {
+      phaseLimit = config.session_phase_limit;
+    } else {
+      const ctxTokens = config.context_window_tokens || 200000;
+      phaseLimit = ctxTokens >= 1000000 ? 8 : ctxTokens >= 500000 ? 6 : 3;
+    }
+    if (phaseLimit > 0 && tracker && tracker.phases_completed >= phaseLimit) {
+      // Write signal file with /pbr:pause-work to trigger the pause chain
+      try { fs.writeFileSync(signalPath, '/pbr:pause-work', 'utf8'); } catch (_writeErr) { /* ignore */ }
+
+      let reasonStr;
+      // session_cycling: "tmux" | "compact-first" | "compact" | "manual"
+      // compact-first: try /compact first, only cycle if still degraded (user must opt in)
+      // Default: tmux if in TMUX env, otherwise compact
+      const cyclingMethod = config.session_cycling || (process.env.TMUX ? 'tmux' : 'compact');
+      if (cyclingMethod === 'compact-first') {
+        // Try compact first, then cycle — gentler on long 1M sessions
+        logHook('auto-continue', 'Stop', 'cycle-compact-first', { phases: tracker.phases_completed, limit: phaseLimit });
+        reasonStr = 'Auto-continue: session checkpoint after ' + tracker.phases_completed + ' phases.\n\n'
+          + 'COMPACT-FIRST CYCLING: Try compacting before cycling to a fresh session.\n'
+          + 'Steps IN ORDER:\n'
+          + '1. Run /pbr:pause-work to save session state\n'
+          + '2. Run /compact to compress context\n'
+          + '3. Run /pbr:resume-work to continue\n'
+          + '4. IF quality degrades after compact, THEN run /clear + /pbr:resume-work for a full cycle\n\n'
+          + 'Execute /pbr:pause-work now.';
+      } else if (cyclingMethod === 'tmux') {
+        // TMUX environment: spawn detached process to auto-cycle
+        // On Windows, Claude Code's bash is MSYS2 (no tmux) — bridge through wsl.exe to reach the WSL tmux server
+        // On Linux/macOS, tmux is available directly
+        const isWindows = process.platform === 'win32';
+        let cycleCmd;
+        if (isWindows) {
+          // Use pbr-tmux cycle which handles pane targeting via WSL tmux
+          cycleCmd = 'sleep 3 && wsl.exe -d Ubuntu -- pbr-tmux cycle --non-interactive';
+        } else {
+          cycleCmd = 'sleep 3 && tmux send-keys "/clear" Enter && sleep 1 && tmux send-keys "/pbr:resume-work" Enter';
+        }
+        const child = spawn('bash', ['-c', cycleCmd], { detached: true, stdio: 'ignore' });
+        child.unref();
+        logHook('auto-continue', 'Stop', 'cycle-tmux', { phases: tracker.phases_completed, limit: phaseLimit, bridge: isWindows ? 'wsl' : 'native' });
+        reasonStr = 'Auto-continue: execute /pbr:pause-work \u2014 Session checkpoint after ' + tracker.phases_completed + ' phases. TMUX auto-cycle will send /clear + /pbr:resume-work after pause completes.';
+      } else if (cyclingMethod === 'compact') {
+        // Compact mode: keep session alive, compress context, then continue
+        logHook('auto-continue', 'Stop', 'cycle-compact', { phases: tracker.phases_completed, limit: phaseLimit });
+        reasonStr = 'Auto-continue: session checkpoint after ' + tracker.phases_completed + ' phases.\n\n'
+          + 'IMPORTANT: Context cycling required. You MUST do these steps IN ORDER:\n'
+          + '1. Run /pbr:pause-work to save session state\n'
+          + '2. Run /compact to compress context\n'
+          + '3. Run /pbr:resume-work to continue with fresh context\n\n'
+          + 'Execute /pbr:pause-work now.';
+      } else {
+        // Manual mode or unknown: show checkpoint banner with manual instructions
+        logHook('auto-continue', 'Stop', 'cycle-banner', { phases: tracker.phases_completed, limit: phaseLimit });
+        reasonStr = 'Auto-continue: execute /pbr:pause-work \u2014 Session checkpoint after ' + tracker.phases_completed + ' phases.\n\n'
+          + '+==============================================================+\n'
+          + '|  PLAN-BUILD-RUN > SESSION CHECKPOINT                         |\n'
+          + '+==============================================================+\n\n'
+          + 'Context cycling recommended after ' + tracker.phases_completed + ' phases completed.\n'
+          + 'After pause completes, run:\n\n'
+          + '  1. /clear\n'
+          + '  2. /pbr:resume-work\n';
+      }
+
+      process.stdout.write(JSON.stringify({ decision: 'block', reason: reasonStr }));
+      process.exit(0);
+    }
+
+    // Phase boundary clear enforcement
+    // When workflow.phase_boundary_clear is "enforce", block auto-continue
+    // until the user runs /clear. The build skill writes .phase-boundary-pending
+    // as a signal that a clear is required.
+    const phaseBoundaryPath = path.join(planningDir, '.phase-boundary-pending');
+    if (fs.existsSync(phaseBoundaryPath)) {
+      const phaseBoundaryClear = (config.workflow && config.workflow.phase_boundary_clear) || 'off';
+      if (phaseBoundaryClear === 'enforce') {
+        logHook('auto-continue', 'Stop', 'phase-boundary-enforce', {});
+        // Delete the signal file (one-shot)
+        try { fs.unlinkSync(phaseBoundaryPath); } catch (_e) { /* ignore */ }
+        // Also delete .auto-next if it exists (enforce overrides auto-continue)
+        try { fs.unlinkSync(signalPath); } catch (_e) { /* ignore */ }
+        const reasonStr = 'Phase boundary clear is enforced. Run /clear before continuing to the next phase.\n\n'
+          + 'This ensures fresh context quality for the next phase. After /clear, run /pbr:resume-work to continue.';
+        process.stdout.write(JSON.stringify({ decision: 'block', reason: reasonStr }));
+        process.exit(0);
+      } else if (phaseBoundaryClear === 'recommend') {
+        // Advisory only — let auto-continue proceed but add a note
+        logHook('auto-continue', 'Stop', 'phase-boundary-recommend', {});
+        try { fs.unlinkSync(phaseBoundaryPath); } catch (_e) { /* ignore */ }
+        // Don't block — just log. The build skill already showed the advisory.
+      } else {
+        // "off" — clean up stale signal file
+        try { fs.unlinkSync(phaseBoundaryPath); } catch (_e) { /* ignore */ }
+      }
+    }
+
+    // Primary: read next command from config flag workflow._auto_chain_active
+    let nextCommand = '';
+    let source = 'none';
+    if (config.workflow && config.workflow._auto_chain_active) {
+      nextCommand = String(config.workflow._auto_chain_active).trim();
+      source = 'config-flag';
+      // Clear the flag immediately (one-shot) by writing config back without it
+      try {
+        const configPath = path.join(planningDir, 'config.json');
+        const rawConfig = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        if (rawConfig.workflow) {
+          delete rawConfig.workflow._auto_chain_active;
+        }
+        fs.writeFileSync(configPath, JSON.stringify(rawConfig, null, 2), 'utf8');
+      } catch (_clearErr) {
+        logHook('auto-continue', 'Stop', 'flag-clear-failed', { error: _clearErr.message });
+      }
+    }
+
+    // Backward compat: fall back to .auto-next signal file if config flag was empty
+    let signalFileRead = false;
+    if (!nextCommand && fs.existsSync(signalPath)) {
+      nextCommand = fs.readFileSync(signalPath, 'utf8').trim();
+      signalFileRead = true;
+      source = nextCommand ? 'signal-file' : 'none';
+      // Delete the signal file (migration path — old writers may still create it)
+      for (let attempt = 0; attempt < 3; attempt++) {
+        try {
+          fs.unlinkSync(signalPath);
+          break;
+        } catch (unlinkErr) {
+          if (attempt === 2) {
+            logHook('auto-continue', 'Stop', 'unlink-failed', { error: unlinkErr.message });
+          } else {
+            const delay = 100 * Math.pow(2, attempt);
+            try {
+              const buf = new SharedArrayBuffer(4);
+              Atomics.wait(new Int32Array(buf), 0, 0, delay);
+            } catch (_atomicsErr) {
+              // No SharedArrayBuffer — skip delay, retry immediately
+            }
+          }
+        }
+      }
+    }
+
+    if (!nextCommand) {
+      // Signal file existed but was empty
+      if (signalFileRead) {
+        logHook('auto-continue', 'Stop', 'empty-signal', {});
+        process.exit(0);
+      }
+      // No auto-continue signal — check for pending todos as a reminder
+      const todoPendingDir = path.join(planningDir, 'todos', 'pending');
+      try {
+        if (fs.existsSync(todoPendingDir)) {
+          const pending = fs.readdirSync(todoPendingDir).filter(f => f.endsWith('.md'));
+          if (pending.length > 0) {
+            logHook('auto-continue', 'Stop', 'pending-todos', { count: pending.length });
+            process.stderr.write(`[pbr] ${pending.length} pending todo(s) in .planning/todos/pending/ — run /pbr:todo list to review\n`);
+          }
+        }
+      } catch (_todoErr) {
+        // Ignore errors scanning todos
+      }
+      // Reset continue count on normal session stop (no signal)
+      const countPathNoSig = path.join(planningDir, '.continue-count');
+      try { fs.unlinkSync(countPathNoSig); } catch (_e) { /* ignore */ }
+      logHook('auto-continue', 'Stop', 'no-signal', {});
+      process.exit(0);
+    }
+
+    if (!nextCommand) {
+      logHook('auto-continue', 'Stop', 'empty-signal', {});
+      process.exit(0);
+    }
+
+    // Track consecutive continues for session length guard
+    const countPath = path.join(planningDir, '.continue-count');
+    let continueCount = 0;
+    try {
+      continueCount = parseInt(fs.readFileSync(countPath, 'utf8').trim(), 10) || 0;
+    } catch (_e) { /* file missing — start at 0 */ }
+    continueCount++;
+    try { fs.writeFileSync(countPath, String(continueCount)); } catch (_e) { /* ignore */ }
+
+    // Hard stop after 6 consecutive continues — context is likely degraded
+    if (continueCount > 6) {
+      logHook('auto-continue', 'Stop', 'hard-stop-session-length', { count: continueCount });
+      process.exit(0);
+    }
+
+    // Extract last_assistant_message for richer continuation context
+    const lastMsg = hookInput.last_assistant_message || '';
+    const msgSuffix = lastMsg
+      ? ` (last message excerpt: ${lastMsg.slice(0, 200)})`
+      : '';
+
+    logHook('auto-continue', 'Stop', 'continue', { next: nextCommand, source, hasLastMsg: !!lastMsg, continueCount });
+
+    // Build reason string with optional advisory
+    let reasonStr = `Auto-continue: execute ${nextCommand}${msgSuffix}`;
+    if (continueCount > 3) {
+      reasonStr += `\n\n[pbr] Advisory: ${continueCount} consecutive continues. Consider /pbr:pause-work + fresh session to avoid context degradation.`;
+    }
+
+    // Block the stop and inject the next command as Claude's continuation reason.
+    // Claude Code Stop hooks use { decision: "block", reason: "..." } to keep going.
+    const output = {
+      decision: 'block',
+      reason: reasonStr
+    };
+    process.stdout.write(JSON.stringify(output));
+    process.exit(0);
+  } catch (_e) {
+    // Don't block on errors
+    process.stdout.write(JSON.stringify({ additionalContext: '⚠ [PBR] auto-continue failed: ' + _e.message }));
+    process.exit(0);
+  }
+}
+
+main();

package/plugins/pbr/dist/block-skill-self-read.js

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+
+/**
+ * PreToolUse Read hook: blocks skills from re-reading their own SKILL.md.
+ *
+ * Skills are already loaded into context by Claude Code -- re-reading
+ * wastes ~13k tokens. This hook checks .planning/.active-skill to
+ * determine the current skill and blocks if the Read target matches.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+const { resolveSessionPath } = require('./lib/core');
+
+/**
+ * Core check logic extracted for both stdin (main) and HTTP (handleHttp) paths.
+ *
+ * @param {Object} data - Parsed hook input (same as stdin JSON)
+ * @returns {Object|null} { decision: 'block', reason } if self-read detected, null otherwise
+ */
+function checkSelfRead(data) {
+  try {
+    const cwd = data.cwd || process.cwd();
+    const toolInput = data.tool_input || {};
+    const filePath = toolInput.file_path || '';
+
+    if (!filePath) {
+      return null;
+    }
+
+    // Read .active-skill to get current skill name (session-scoped)
+    const sessionId = data.session_id || null;
+    const planningDir = path.join(cwd, '.planning');
+    const activeSkillPath = sessionId
+      ? resolveSessionPath(planningDir, '.active-skill', sessionId)
+      : path.join(planningDir, '.active-skill');
+    let skillName = '';
+    try {
+      skillName = fs.readFileSync(activeSkillPath, 'utf8').trim();
+    } catch (_readErr) {
+      // No .active-skill file -- nothing to block
+      return null;
+    }
+
+    if (!skillName) {
+      return null;
+    }
+
+    // Check if file_path ends with skills/{skill-name}/SKILL.md
+    const normalized = filePath.replace(/\\/g, '/');
+    const pattern = `skills/${skillName}/SKILL.md`.toLowerCase();
+    const match = normalized.toLowerCase().endsWith(pattern);
+
+    if (match) {
+      logHook('block-skill-self-read', 'PreToolUse', 'block', { skill: skillName, file: filePath });
+      return {
+        decision: 'block',
+        reason: `SKILL.md self-read blocked.\n\nThe active skill (${skillName}) attempted to read its own SKILL.md. Skills are already loaded into context by Claude Code \u2014 re-reading wastes ~13k tokens.\n\nNo action needed. The skill content is already available in your prompt.`
+      };
+    }
+
+    logHook('block-skill-self-read', 'PreToolUse', 'allow', { skill: skillName, file: filePath });
+    return null;
+  } catch (_e) {
+    logHook('block-skill-self-read', '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 {Object|null} Hook response or null
+ */
+async function handleHttp(reqBody, _cache) {
+  const data = reqBody.data || {};
+  try {
+    return checkSelfRead(data);
+  } catch (_e) {
+    logHook('block-skill-self-read', 'PreToolUse', 'error', { error: _e.message });
+    return null;
+  }
+}
+
+module.exports = { handleHttp, checkSelfRead };
+
+function main() {
+  try {
+    let hookInput = {};
+    try {
+      const stdin = fs.readFileSync(0, 'utf8').trim();
+      if (stdin) hookInput = JSON.parse(stdin);
+    } catch (_parseErr) {
+      // No stdin or invalid JSON
+    }
+
+    const result = checkSelfRead(hookInput);
+
+    if (result && result.decision === 'block') {
+      process.stdout.write(JSON.stringify(result));
+      process.exit(0);
+    }
+
+    if (result) {
+      process.stdout.write(JSON.stringify(result));
+    }
+
+    process.exit(0);
+  } catch (_e) {
+    // Don't block on errors -- emit valid output for Claude Code
+    process.stderr.write(`[pbr] block-skill-self-read error: ${_e.message}\n`);
+    process.stdout.write(JSON.stringify({ decision: "allow", additionalContext: '\u26a0 [PBR] block-skill-self-read failed: ' + _e.message }));
+    process.exit(0);
+  }
+}
+
+if (require.main === module || process.argv[1] === __filename) { main(); }

package/plugins/pbr/dist/check-agent-state-write.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+
+/**
+ * PreToolUse hook: Blocks subagents (except pbr:general) from writing STATE.md.
+ *
+ * STATE.md is the source of truth for project position and should only be
+ * written by skills (orchestrators) or the general agent, never by specialized
+ * agents like executor, planner, or verifier.
+ *
+ * Detection: reads .planning/.active-agent (written by log-subagent.js).
+ *
+ * Exit codes:
+ *   0 = allowed or not applicable
+ *   2 = blocked (agent not allowed to write STATE.md)
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const BLOCKED_AGENTS = [
+  'pbr:executor',
+  'pbr:planner',
+  'pbr:verifier',
+  'pbr:researcher',
+  'pbr:plan-checker',
+  'pbr:integration-checker',
+  'pbr:debugger',
+  'pbr:codebase-mapper',
+  'pbr:synthesizer',
+  'pbr:audit',
+];
+
+function checkAgentStateWrite(data) {
+  const filePath = data.tool_input?.file_path || data.tool_input?.path || '';
+  if (!filePath) return null;
+
+  const normalized = filePath.replace(/\\/g, '/');
+  if (!normalized.endsWith('.planning/STATE.md')) return null;
+
+  // Check if we're inside a subagent
+  const cwd = process.cwd();
+  const agentFile = path.join(cwd, '.planning', '.active-agent');
+
+  let agent;
+  try {
+    agent = fs.readFileSync(agentFile, 'utf8').trim();
+  } catch (_e) {
+    // No .active-agent file — not in an agent context
+    return null;
+  }
+
+  if (!agent || !BLOCKED_AGENTS.includes(agent)) return null;
+
+  return {
+    exitCode: 2,
+    output: {
+      decision: 'block',
+      reason: `Agent write to STATE.md blocked.\n\n${agent} is not allowed to write STATE.md. Only skills (orchestrators) and pbr:general may update this file to prevent state corruption.\n\nReturn results to the calling skill and let it update STATE.md.`
+    }
+  };
+}
+
+module.exports = { checkAgentStateWrite, BLOCKED_AGENTS };

package/plugins/pbr/dist/check-config-change.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+
+/**
+ * ConfigChange hook: Validates config.json changes and warns about inconsistencies.
+ *
+ * Fires when Claude Code detects configuration file changes (v2.1.49+).
+ * Checks .planning/config.json for:
+ *   - Required top-level keys
+ *   - Semantic conflicts (e.g., parallel agents enabled with max=1)
+ *   - Version field presence
+ *
+ * Exit codes:
+ *   0 = always (advisory hook, never blocks)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+const { logEvent } = require('./event-logger');
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let input = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { input += chunk; });
+    process.stdin.on('end', () => {
+      try {
+        resolve(JSON.parse(input));
+      } catch (_e) {
+        resolve({});
+      }
+    });
+  });
+}
+
+function findPlanningDir() {
+  let dir = process.cwd();
+  const root = path.parse(dir).root;
+  while (dir !== root) {
+    const candidate = path.join(dir, '.planning');
+    if (fs.existsSync(candidate)) return candidate;
+    dir = path.dirname(dir);
+  }
+  return null;
+}
+
+function validateConfig(configPath) {
+  const warnings = [];
+
+  let config;
+  try {
+    const raw = fs.readFileSync(configPath, 'utf8');
+    config = JSON.parse(raw);
+  } catch (e) {
+    warnings.push(`config.json parse error: ${e.message}`);
+    return warnings;
+  }
+
+  // Check required top-level keys
+  const requiredKeys = ['version', 'features', 'models', 'gates'];
+  for (const key of requiredKeys) {
+    if (!(key in config)) {
+      warnings.push(`Missing required key: ${key}`);
+    }
+  }
+
+  // Check version
+  if (config.version && config.version < 2) {
+    warnings.push(`Config version ${config.version} is outdated — expected version 2+`);
+  }
+
+  // Check semantic conflicts
+  if (config.parallelization) {
+    const p = config.parallelization;
+    if (p.enabled && p.max_concurrent_agents === 1) {
+      warnings.push('Semantic conflict: parallelization.enabled=true but max_concurrent_agents=1');
+    }
+    if (!p.enabled && (p.plan_level || p.task_level)) {
+      warnings.push('Semantic conflict: parallelization.enabled=false but plan_level/task_level are true');
+    }
+  }
+
+  // Check model values
+  if (config.models) {
+    const validModels = ['sonnet', 'opus', 'haiku', 'inherit'];
+    for (const [role, model] of Object.entries(config.models)) {
+      if (!validModels.includes(model)) {
+        warnings.push(`Invalid model "${model}" for ${role} — expected: ${validModels.join(', ')}`);
+      }
+    }
+  }
+
+  return warnings;
+}
+
+async function main() {
+  await readStdin();
+  const startTime = Date.now();
+
+  const planningDir = findPlanningDir();
+  if (!planningDir) {
+    logHook('check-config-change', 'ConfigChange', 'skip', { reason: 'no .planning dir' }, startTime);
+    process.exit(0);
+  }
+
+  const configPath = path.join(planningDir, 'config.json');
+  if (!fs.existsSync(configPath)) {
+    logHook('check-config-change', 'ConfigChange', 'skip', { reason: 'no config.json' }, startTime);
+    process.exit(0);
+  }
+
+  const warnings = validateConfig(configPath);
+
+  if (warnings.length > 0) {
+    const msg = `⚠️ Config validation (${warnings.length} issue${warnings.length > 1 ? 's' : ''}):\n${warnings.map(w => `  - ${w}`).join('\n')}`;
+
+    logHook('check-config-change', 'ConfigChange', 'warn', { warnings }, startTime);
+    logEvent('workflow', 'config-change', { warnings });
+
+    process.stdout.write(JSON.stringify({ additionalContext: msg }));
+  } else {
+    logHook('check-config-change', 'ConfigChange', 'ok', {}, startTime);
+    logEvent('workflow', 'config-change', { status: 'valid' });
+  }
+
+  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) {
+  const planningDir = (reqBody && reqBody.planningDir) || findPlanningDir();
+  if (!planningDir) return null;
+
+  const configPath = path.join(planningDir, 'config.json');
+  if (!fs.existsSync(configPath)) return null;
+
+  const warnings = validateConfig(configPath);
+  if (warnings.length > 0) {
+    const msg = `\u26a0\ufe0f Config validation (${warnings.length} issue${warnings.length > 1 ? 's' : ''}):\n${warnings.map(w => `  - ${w}`).join('\n')}`;
+    logHook('check-config-change', 'ConfigChange', 'warn', { warnings });
+    logEvent('workflow', 'config-change', { warnings });
+    return { additionalContext: msg };
+  }
+
+  logHook('check-config-change', 'ConfigChange', 'ok', {});
+  logEvent('workflow', 'config-change', { status: 'valid' });
+  return null;
+}
+
+if (require.main === module || process.argv[1] === __filename) main();
+module.exports = { validateConfig, findPlanningDir, handleHttp };