@sienklogic/plan-build-run 2.19.0 → 2.19.1

package/plugins/pbr/scripts/post-bash-triage.js

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+
+/**
+ * PostToolUse hook for Bash: Triages test failure output using the local LLM.
+ *
+ * When a Bash command that looks like a test invocation exits with a non-zero
+ * exit code, this hook sends the output to the local LLM for classification.
+ * The triage result is returned as advisory context to help the frontier model
+ * focus on the right failure category without re-parsing raw test output.
+ *
+ * Exit codes:
+ *   0 = always (PostToolUse hook, never blocks)
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+const { resolveConfig } = require('./lib/local-llm/health');
+const { triageTestOutput } = require('./lib/local-llm/operations/triage-test-output');
+
+const TEST_COMMAND_PATTERNS = [
+  /\bnpm\s+test\b/,
+  /\bnpx\s+jest\b/,
+  /\bnpx\s+vitest\b/,
+  /\bpytest\b/,
+  /\bmocha\b/,
+  /\bjest\b/,
+  /\bvitest\b/,
+  /\bcargo\s+test\b/,
+  /\bgo\s+test\b/,
+  /\bnpm\s+run\s+test/
+];
+
+/**
+ * Detect the test runner from the command string.
+ * @param {string} command
+ * @returns {string|null}
+ */
+function detectTestRunner(command) {
+  if (/jest/i.test(command)) return 'jest';
+  if (/vitest/i.test(command)) return 'vitest';
+  if (/pytest/i.test(command)) return 'pytest';
+  if (/mocha/i.test(command)) return 'mocha';
+  if (/cargo\s+test/i.test(command)) return 'cargo';
+  if (/go\s+test/i.test(command)) return 'go';
+  return null;
+}
+
+/**
+ * Load and resolve the local_llm config block from .planning/config.json.
+ */
+function loadLocalLlmConfig(cwd) {
+  try {
+    const configPath = path.join(cwd || process.cwd(), '.planning', 'config.json');
+    const parsed = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    return resolveConfig(parsed.local_llm);
+  } catch (_e) {
+    return resolveConfig(undefined);
+  }
+}
+
+/**
+ * Check if Bash output contains test failure and triage it.
+ * @param {object} data - parsed hook data
+ * @returns {Promise<{output: object}|null>}
+ */
+async function checkTestTriage(data) {
+  const command = data.tool_input?.command || '';
+  const toolOutput = data.tool_output || '';
+  const exitCode = data.tool_exit_code;
+
+  // Only triage test commands that failed
+  if (exitCode === 0 || exitCode === undefined) return null;
+  if (!TEST_COMMAND_PATTERNS.some(p => p.test(command))) return null;
+  if (!toolOutput || toolOutput.length < 20) return null;
+
+  const cwd = process.cwd();
+  const llmConfig = loadLocalLlmConfig(cwd);
+  const planningDir = path.join(cwd, '.planning');
+  const testRunner = detectTestRunner(command);
+
+  // Truncate to last 2000 chars — test failures are usually at the end
+  const tail = toolOutput.length > 2000 ? toolOutput.slice(-2000) : toolOutput;
+
+  try {
+    const llmResult = await triageTestOutput(llmConfig, planningDir, tail, testRunner, data.session_id);
+    if (llmResult && llmResult.category && llmResult.category !== 'unknown') {
+      logHook('post-bash-triage', 'PostToolUse', 'triage', {
+        category: llmResult.category,
+        file_hint: llmResult.file_hint,
+        runner: testRunner
+      });
+
+      let msg = `[pbr] Test failure triage: ${llmResult.category}`;
+      if (llmResult.file_hint) {
+        msg += ` (likely: ${llmResult.file_hint})`;
+      }
+      msg += ` (confidence: ${(llmResult.confidence * 100).toFixed(0)}%)`;
+
+      return { output: { additionalContext: msg } };
+    }
+  } catch (_llmErr) {
+    // Never propagate LLM errors
+  }
+
+  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 {
+    const result = await checkTestTriage(data);
+    return result ? result.output : null;
+  } 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 checkTestTriage(data);
+      if (result) {
+        process.stdout.write(JSON.stringify(result.output));
+      } else {
+        process.stdout.write('{}');
+      }
+      process.exit(0);
+    } catch (_e) {
+      // Don't block on errors
+      process.stdout.write(JSON.stringify({ additionalContext: '⚠ [PBR] post-bash-triage failed: ' + _e.message }));
+      process.exit(0);
+    }
+  });
+}
+
+module.exports = { checkTestTriage, detectTestRunner, handleHttp };
+if (require.main === module || process.argv[1] === __filename) { main(); }

package/plugins/pbr/scripts/post-compact.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+
+/**
+ * PostCompact hook: Restores context after lossy compaction.
+ *
+ * After Claude Code compacts conversation context, this hook:
+ * - Re-injects STATE.md summary + active phase context via additionalContext
+ * - Resets context budget tracker counter (.context-tracker)
+ * - Resets context ledger (.context-ledger.json) via resetLedger()
+ * - Logs the compaction event to hooks.jsonl and events.jsonl
+ *
+ * Complementary to context-budget-check.js (PreCompact) which saves state
+ * before compaction. This hook restores it after.
+ *
+ * Exit codes:
+ *   0 = always (informational hook, never blocks)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+const { logEvent } = require('./event-logger');
+const { stateLoad } = require('./lib/state');
+const { resetLedger } = require('./track-context-budget');
+
+/**
+ * Build a concise context string from STATE.md for post-compaction recovery.
+ *
+ * @param {string} planningDir - Path to .planning/ directory
+ * @returns {string} Context string or empty string if STATE.md missing
+ */
+function buildPostCompactContext(planningDir) {
+  const stateFile = path.join(planningDir, 'STATE.md');
+  if (!fs.existsSync(stateFile)) return '';
+
+  const fullState = stateLoad(planningDir);
+  const state = (fullState && fullState.state) || {};
+
+  const phase = state.current_phase || 'unknown';
+  const phaseName = state.phase_name || '';
+  const status = state.status || 'unknown';
+
+  const parts = [
+    '[Post-Compaction Context Recovery]',
+    `Phase: ${phase}${phaseName ? ' (' + phaseName + ')' : ''}`,
+    `Status: ${status}`,
+    '[PBR WORKFLOW REQUIRED — Route all work through PBR commands]\n- Fix a bug or small task → /pbr:quick\n- Plan a feature → /pbr:plan-phase N\n- Build from a plan → /pbr:execute-phase N\n- Explore or research → /pbr:explore\n- Freeform request → /pbr:do\n- Do NOT write source code or spawn generic agents without an active PBR skill.\n- Use PBR agents (pbr:researcher, pbr:executor, etc.) not Explore/general-purpose.',
+    'Read .planning/STATE.md for full context.'
+  ];
+
+  return parts.join('\n');
+}
+
+/**
+ * Reset context budget tracker files after compaction.
+ *
+ * @param {string} planningDir - Path to .planning/ directory
+ * @returns {{ trackerReset: boolean, ledgerReset: boolean }}
+ */
+function resetBudgetTracker(planningDir) {
+  const result = { trackerReset: false, ledgerReset: false };
+
+  // Delete .context-tracker file (best-effort)
+  try {
+    const trackerPath = path.join(planningDir, '.context-tracker');
+    fs.unlinkSync(trackerPath);
+    result.trackerReset = true;
+  } catch (_e) {
+    // File may not exist — that's fine
+  }
+
+  // Delete .context-ledger.json via resetLedger
+  try {
+    resetLedger(planningDir);
+    result.ledgerReset = true;
+  } catch (_e) {
+    // Best-effort
+  }
+
+  return result;
+}
+
+/**
+ * Main entry point for command-line execution.
+ */
+function main() {
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+  const stateFile = path.join(planningDir, 'STATE.md');
+
+  // Not a PBR project — exit silently
+  if (!fs.existsSync(stateFile)) {
+    process.exit(0);
+  }
+
+  const context = buildPostCompactContext(planningDir);
+  const resetResult = resetBudgetTracker(planningDir);
+
+  logHook('post-compact', 'PostCompact', 'restored', { ...resetResult });
+  logEvent('workflow', 'post-compact', { timestamp: new Date().toISOString() });
+
+  if (context) {
+    process.stdout.write(JSON.stringify({ additionalContext: context }));
+  }
+
+  process.exit(0);
+}
+
+/**
+ * HTTP handler for 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;
+  if (!planningDir) return null;
+
+  const stateFile = path.join(planningDir, 'STATE.md');
+  if (!fs.existsSync(stateFile)) return null;
+
+  const context = buildPostCompactContext(planningDir);
+  const resetResult = resetBudgetTracker(planningDir);
+
+  logHook('post-compact', 'PostCompact', 'restored', { ...resetResult });
+  logEvent('workflow', 'post-compact', { timestamp: new Date().toISOString() });
+
+  if (context) {
+    return { additionalContext: context };
+  }
+
+  return null;
+}
+
+module.exports = { buildPostCompactContext, resetBudgetTracker, handleHttp };
+if (require.main === module || process.argv[1] === __filename) { main(); }

package/plugins/pbr/scripts/post-hoc.js

@@ -0,0 +1,286 @@
+'use strict';
+
+/**
+ * post-hoc.js — Phase-level post-hoc artifact generation.
+ *
+ * Generates SUMMARY.md and LEARNINGS.md content from git history,
+ * PLAN frontmatter, VERIFICATION.md gaps, and hook logs.
+ *
+ * Exports: generateSummary, generateLearnings, isEnabled
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+/**
+ * Minimal YAML frontmatter parser. Returns key-value pairs from --- blocks.
+ * Handles arrays (lines starting with "  - ") and nested objects (indented keys).
+ */
+function parseFrontmatter(content) {
+  if (!content) return {};
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return {};
+
+  const lines = match[1].split(/\r?\n/);
+  const result = {};
+  let currentKey = null;
+  let currentNested = null;
+
+  for (const line of lines) {
+    // Nested array item: "  - value"
+    const arrayMatch = line.match(/^(\s{2,})- "?([^"]*)"?$/);
+    if (arrayMatch && currentKey) {
+      if (currentNested) {
+        if (!result[currentKey]) result[currentKey] = {};
+        if (!result[currentKey][currentNested]) result[currentKey][currentNested] = [];
+        result[currentKey][currentNested].push(arrayMatch[2]);
+      } else {
+        if (!Array.isArray(result[currentKey])) result[currentKey] = [];
+        result[currentKey].push(arrayMatch[2]);
+      }
+      continue;
+    }
+
+    // Nested key: "  key:"
+    const nestedKeyMatch = line.match(/^\s{2,}(\w+):\s*$/);
+    if (nestedKeyMatch && currentKey) {
+      currentNested = nestedKeyMatch[1];
+      if (!result[currentKey]) result[currentKey] = {};
+      continue;
+    }
+
+    // Top-level key-value: "key: value" or "key:"
+    const kvMatch = line.match(/^(\w[\w_]*):\s*(.*)$/);
+    if (kvMatch) {
+      currentKey = kvMatch[1];
+      currentNested = null;
+      const val = kvMatch[2].replace(/^"(.*)"$/, '$1').trim();
+      result[currentKey] = val || null;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Read all PLAN-*.md files from phaseDir and parse their frontmatter.
+ */
+function readPlanFiles(phaseDir) {
+  const plans = [];
+  try {
+    const files = fs.readdirSync(phaseDir).filter(f => /^PLAN.*\.md$/i.test(f));
+    for (const file of files) {
+      const content = fs.readFileSync(path.join(phaseDir, file), 'utf-8');
+      const fm = parseFrontmatter(content);
+      plans.push(fm);
+    }
+  } catch (_e) {
+    // phaseDir may not exist or be unreadable
+  }
+  return plans;
+}
+
+/**
+ * Run a git command and return stdout, or empty string on failure.
+ */
+function gitExec(args, cwd) {
+  try {
+    return execSync(`git ${args}`, { cwd, encoding: 'utf-8', timeout: 10000, stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+  } catch (_e) {
+    return '';
+  }
+}
+
+/**
+ * Read last N lines from a file (like tail -n).
+ */
+function readTailLines(filePath, n) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const lines = content.split(/\r?\n/);
+    return lines.slice(-n);
+  } catch (_e) {
+    return [];
+  }
+}
+
+/**
+ * Generate SUMMARY.md content from plan files and git history.
+ * Does NOT write to disk — returns { path, content }.
+ *
+ * @param {string} phaseDir - Path to the phase directory containing PLAN-*.md files
+ * @param {string} planningDir - Path to the .planning directory
+ * @returns {{ path: string, content: string }}
+ */
+function generateSummary(phaseDir, planningDir) {
+  const plans = readPlanFiles(phaseDir);
+
+  // Collect provides, files_modified, must_haves from all plans
+  const allProvides = [];
+  const allFiles = new Set();
+  const allTruths = [];
+
+  for (const plan of plans) {
+    // provides
+    if (Array.isArray(plan.provides)) {
+      allProvides.push(...plan.provides);
+    }
+    // files_modified
+    if (Array.isArray(plan.files_modified)) {
+      plan.files_modified.forEach(f => allFiles.add(f));
+    }
+    // must_haves.truths
+    if (plan.must_haves && typeof plan.must_haves === 'object') {
+      if (Array.isArray(plan.must_haves.truths)) {
+        allTruths.push(...plan.must_haves.truths);
+      }
+    }
+  }
+
+  const keyFiles = Array.from(allFiles);
+
+  // Get git log for phase files (last 50 commits)
+  let commitLog = '';
+  if (keyFiles.length > 0) {
+    const fileArgs = keyFiles.map(f => `"${f}"`).join(' ');
+    commitLog = gitExec(`log --oneline --no-decorate -50 -- ${fileArgs}`, planningDir);
+  }
+
+  // Read hook logs
+  const hookLogPath = path.join(planningDir, 'logs', 'hooks.jsonl');
+  const _hookLines = readTailLines(hookLogPath, 100);
+
+  // Determine phase name from directory
+  const phaseName = path.basename(phaseDir);
+
+  // Build YAML frontmatter
+  const fmLines = [
+    '---',
+    `phase: "${phaseName}"`,
+    'status: "complete"',
+    'requires: []',
+    'key_files:',
+    ...keyFiles.map(f => `  - "${f}"`),
+    'deferred: []',
+    'key_decisions: []',
+    'patterns: []',
+    '---'
+  ];
+
+  // Build body
+  const bodyLines = [
+    '',
+    '## What Was Built',
+    '',
+    ...allProvides.map(p => `- ${p}`),
+    '',
+    '## Commits',
+    '',
+    commitLog || 'No matching commits found.',
+    '',
+    '## Must-Have Results',
+    '',
+    ...allTruths.map(t => `- ${t}`),
+    ''
+  ];
+
+  const content = fmLines.join('\n') + '\n' + bodyLines.join('\n');
+  const summaryPath = path.join(phaseDir, 'SUMMARY.md');
+
+  return { path: summaryPath, content };
+}
+
+/**
+ * Generate LEARNINGS.md content from VERIFICATION.md gaps and git diffs.
+ * Does NOT write to disk — returns { path, content }.
+ *
+ * @param {string} phaseDir - Path to the phase directory
+ * @param {string} _planningDir - Path to the .planning directory
+ * @returns {{ path: string, content: string }}
+ */
+function generateLearnings(phaseDir, _planningDir) {
+  // Check for VERIFICATION.md
+  const verPath = path.join(phaseDir, 'VERIFICATION.md');
+  let verStatus = '';
+  let gaps = [];
+
+  try {
+    const verContent = fs.readFileSync(verPath, 'utf-8');
+    const fm = parseFrontmatter(verContent);
+    verStatus = fm.status || '';
+    if (Array.isArray(fm.gaps)) {
+      gaps = fm.gaps;
+    }
+  } catch (_e) {
+    // No VERIFICATION.md — that's fine
+  }
+
+  // Get git diff stats for change hotspots
+  const diffStat = gitExec('diff --stat HEAD~10..HEAD', _planningDir);
+
+  // Read plan files for file list
+  const plans = readPlanFiles(phaseDir);
+  const allFiles = new Set();
+  for (const plan of plans) {
+    if (Array.isArray(plan.files_modified)) {
+      plan.files_modified.forEach(f => allFiles.add(f));
+    }
+  }
+
+  // Build content
+  const bodyLines = [
+    '---',
+    `phase: "${path.basename(phaseDir)}"`,
+    '---',
+    '',
+    '## What Worked',
+    '',
+    verStatus === 'complete' || !verStatus
+      ? 'All verifications passed.'
+      : 'Partial verification — see gaps below.',
+    '',
+    '## What Failed',
+    '',
+    gaps.length > 0
+      ? gaps.map(g => `- ${g}`).join('\n')
+      : 'No gaps identified.',
+    '',
+    '## Patterns',
+    '',
+    allFiles.size > 0
+      ? `Files modified across plans: ${Array.from(allFiles).join(', ')}`
+      : 'No file modification patterns detected.',
+    '',
+    diffStat ? `### Change Hotspots\n\n\`\`\`\n${diffStat}\n\`\`\`` : '',
+    ''
+  ];
+
+  const content = bodyLines.join('\n');
+  const learningsPath = path.join(phaseDir, 'LEARNINGS.md');
+
+  return { path: learningsPath, content };
+}
+
+/**
+ * Check if post-hoc artifact generation is enabled in config.
+ *
+ * @param {string} planningDir - Path to the .planning directory
+ * @returns {boolean}
+ */
+function isEnabled(planningDir) {
+  try {
+    const configPath = path.join(planningDir, 'config.json');
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    return config?.features?.post_hoc_artifacts !== false;
+  } catch (_e) {
+    // No config or parse error — default to enabled
+    return true;
+  }
+}
+
+module.exports = {
+  generateSummary,
+  generateLearnings,
+  isEnabled,
+};