@sienklogic/plan-build-run 2.24.0 → 2.26.0

package/plugins/pbr/scripts/local-llm/operations/classify-file-intent.js

@@ -0,0 +1,73 @@
+'use strict';
+
+const { complete, tryParseJSON, isDisabled } = require('../client');
+const { logMetric } = require('../metrics');
+const { route } = require('../router');
+
+const VALID_FILE_TYPES = ['plan', 'state', 'code', 'test', 'config', 'docs', 'template', 'other'];
+const VALID_INTENTS = ['create', 'update', 'fix', 'refactor', 'delete'];
+
+/**
+ * Classifies the type and intent of a Write/Edit operation using the local LLM.
+ * Uses the file path and a short content snippet to determine what kind of file
+ * is being written and why, enabling smarter downstream dispatch.
+ *
+ * @param {object} config - resolved local_llm config block
+ * @param {string} planningDir - path to the .planning directory
+ * @param {string} filePath - the target file path
+ * @param {string} contentSnippet - first ~200 chars of the content being written
+ * @param {string} [sessionId] - optional session identifier for metrics
+ * @returns {Promise<{ file_type: string, intent: string, confidence: number, latency_ms: number, fallback_used: boolean }|null>}
+ */
+async function classifyFileIntent(config, planningDir, filePath, contentSnippet, sessionId) {
+  if (!config.enabled || !config.features.file_intent_classification) return null;
+  if (isDisabled('file-intent', config.advanced.disable_after_failures)) return null;
+
+  const snippet = contentSnippet.length > 800 ? contentSnippet.slice(0, 800) : contentSnippet;
+
+  const prompt =
+    'Classify this file write operation. Based on the file path and content snippet, determine: (1) file_type: plan (PLAN.md, ROADMAP.md, planning docs), state (STATE.md, status tracking), code (source code, scripts), test (test files), config (JSON/YAML config, package.json), docs (README, documentation), template (templates, EJS), other. (2) intent: create (new file), update (modify existing), fix (bug fix), refactor (restructure), delete (removing content). Respond with JSON: {"file_type": "<one of 8>", "intent": "<one of 5>", "confidence": 0.0-1.0}\n\nPath: ' +
+    filePath + '\nContent snippet:\n' + snippet;
+
+  try {
+    const result = await route(config, prompt, 'file-intent', (logprobs) =>
+      complete(config, prompt, 'file-intent', { logprobs })
+    );
+    if (result === null) return null;
+    const parsed = tryParseJSON(result.content);
+    if (!parsed.ok) return null;
+
+    const fileType = VALID_FILE_TYPES.includes(parsed.data.file_type)
+      ? parsed.data.file_type
+      : 'other';
+    const intent = VALID_INTENTS.includes(parsed.data.intent)
+      ? parsed.data.intent
+      : 'update';
+
+    const metricEntry = {
+      session_id: sessionId || 'unknown',
+      timestamp: new Date().toISOString(),
+      operation: 'file-intent',
+      model: config.model,
+      latency_ms: result.latency_ms,
+      tokens_used_local: result.tokens,
+      tokens_saved_frontier: 150,
+      result: fileType + '/' + intent,
+      fallback_used: false,
+      confidence: parsed.data.confidence || 0.9
+    };
+    logMetric(planningDir, metricEntry);
+
+    return {
+      file_type: fileType,
+      intent,
+      confidence: parsed.data.confidence || 0.9,
+      latency_ms: result.latency_ms,
+      fallback_used: false
+    };
+  } catch (_) {
+    return null;
+  }
+}
+
+module.exports = { classifyFileIntent, VALID_FILE_TYPES, VALID_INTENTS };

package/plugins/pbr/scripts/local-llm/operations/triage-test-output.js

@@ -0,0 +1,72 @@
+'use strict';
+
+const { complete, tryParseJSON, isDisabled } = require('../client');
+const { logMetric } = require('../metrics');
+const { route } = require('../router');
+
+const VALID_CATEGORIES = ['assertion', 'timeout', 'import', 'syntax', 'environment', 'runtime', 'unknown'];
+
+/**
+ * Triages test failure output into a category using the local LLM.
+ * Classifies the failure type and extracts a file hint when possible,
+ * saving the frontier model from parsing raw test output.
+ *
+ * @param {object} config - resolved local_llm config block
+ * @param {string} planningDir - path to the .planning directory
+ * @param {string} testOutput - stderr/stdout from the test run (truncated by caller)
+ * @param {string} [testRunner] - optional runner identifier (jest, vitest, pytest, etc.)
+ * @param {string} [sessionId] - optional session identifier for metrics
+ * @returns {Promise<{ category: string, file_hint: string|null, confidence: number, latency_ms: number, fallback_used: boolean }|null>}
+ */
+async function triageTestOutput(config, planningDir, testOutput, testRunner, sessionId) {
+  if (!config.enabled || !config.features.test_triage) return null;
+  if (isDisabled('test-triage', config.advanced.disable_after_failures)) return null;
+
+  const maxChars = (config.advanced.max_input_tokens || 1024) * 4;
+  const truncated = testOutput.length > maxChars ? testOutput.slice(0, maxChars) : testOutput;
+
+  const runnerHint = testRunner ? '\nTest runner: ' + testRunner : '';
+
+  const prompt =
+    'Classify this test failure output into one category. Categories: assertion (expect/assert failed), timeout (test or operation timed out), import (module not found or import error), syntax (parse error or syntax issue), environment (missing env var, port conflict, permissions), runtime (uncaught exception, null reference, type error), unknown (none of the above). Also extract the most likely failing file and line if visible. Respond with JSON: {"category": "<one of 7>", "file_hint": "path:line or null", "confidence": 0.0-1.0}' +
+    runnerHint + '\n\nTest output:\n' + truncated;
+
+  try {
+    const result = await route(config, prompt, 'test-triage', (logprobs) =>
+      complete(config, prompt, 'test-triage', { logprobs })
+    );
+    if (result === null) return null;
+    const parsed = tryParseJSON(result.content);
+    if (!parsed.ok) return null;
+
+    const category = VALID_CATEGORIES.includes(parsed.data.category)
+      ? parsed.data.category
+      : 'unknown';
+
+    const metricEntry = {
+      session_id: sessionId || 'unknown',
+      timestamp: new Date().toISOString(),
+      operation: 'test-triage',
+      model: config.model,
+      latency_ms: result.latency_ms,
+      tokens_used_local: result.tokens,
+      tokens_saved_frontier: 250,
+      result: category,
+      fallback_used: false,
+      confidence: parsed.data.confidence || 0.9
+    };
+    logMetric(planningDir, metricEntry);
+
+    return {
+      category,
+      file_hint: parsed.data.file_hint || null,
+      confidence: parsed.data.confidence || 0.9,
+      latency_ms: result.latency_ms,
+      fallback_used: false
+    };
+  } catch (_) {
+    return null;
+  }
+}
+
+module.exports = { triageTestOutput, VALID_CATEGORIES };

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

@@ -0,0 +1,132 @@
+#!/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('./local-llm/health');
+const { triageTestOutput } = require('./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;
+}
+
+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));
+      }
+      process.exit(0);
+    } catch (_e) {
+      // Don't block on errors
+      process.exit(0);
+    }
+  });
+}
+
+module.exports = { checkTestTriage, detectTestRunner };
+if (require.main === module || process.argv[1] === __filename) { main(); }

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

@@ -18,10 +18,14 @@
  *   0 = always (PostToolUse hooks are advisory)
  */
 
+const fs = require('fs');
+const path = require('path');
 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 { resolveConfig } = require('./local-llm/health');
+const { classifyFileIntent } = require('./local-llm/operations/classify-file-intent');
 
 // Conditionally import validateRoadmap (may not exist yet if PLAN-01 hasn't landed)
 let validateRoadmap;
@@ -117,6 +121,46 @@ function main() {
         process.exit(0);
       }
 
+      // LLM file intent classification — advisory enrichment for non-planning files
+      // Skipped for .planning/ files (already handled by plan format / state checks above)
+      const filePath = data.tool_input?.file_path || data.tool_input?.path || '';
+      const normalizedPath = filePath.replace(/\\/g, '/');
+      if (filePath && !normalizedPath.includes('.planning/') && !normalizedPath.includes('.planning\\')) {
+        try {
+          const cwd = process.cwd();
+          const planningDir = path.join(cwd, '.planning');
+          const llmConfig = (() => {
+            try {
+              const configPath = path.join(planningDir, 'config.json');
+              const parsed = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+              return resolveConfig(parsed.local_llm);
+            } catch (_e) {
+              return resolveConfig(undefined);
+            }
+          })();
+
+          let contentSnippet = '';
+          try {
+            const content = data.tool_input?.content || data.tool_input?.new_string || '';
+            contentSnippet = content.slice(0, 400);
+          } catch (_e) {
+            // No content available
+          }
+
+          if (contentSnippet) {
+            const llmResult = await classifyFileIntent(llmConfig, planningDir, filePath, contentSnippet, data.session_id);
+            if (llmResult && llmResult.file_type) {
+              process.stdout.write(JSON.stringify({
+                additionalContext: `[pbr] File classified: ${llmResult.file_type}/${llmResult.intent} (confidence: ${(llmResult.confidence * 100).toFixed(0)}%)`
+              }));
+              process.exit(0);
+            }
+          }
+        } catch (_llmErr) {
+          // Never propagate LLM errors
+        }
+      }
+
       process.exit(0);
     } catch (_e) {
       // Don't block on parse errors

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

@@ -48,14 +48,14 @@
 
 const { logHook } = require('./hook-logger');
 const { checkDangerous } = require('./check-dangerous-commands');
-const { checkCommit } = require('./validate-commit');
+const { checkCommit, enrichCommitLlm } = require('./validate-commit');
 
 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);
 
@@ -77,9 +77,9 @@ function main() {
 
       // Soft warnings for risky-but-allowed commands
       const command = data.tool_input?.command || '';
-      if (command) {
-        const warnings = [];
+      const warnings = [];
 
+      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');
@@ -95,14 +95,20 @@ function main() {
         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');
         }
+      }
 
-        if (warnings.length > 0) {
-          process.stdout.write(JSON.stringify({
-            decision: 'allow',
-            additionalContext: `[pbr] Advisory: ${warnings.join('; ')}.`
-          }));
-          process.exit(0);
-        }
+      // LLM commit semantic classification — advisory only
+      const llmAdvisory = await enrichCommitLlm(data);
+      if (llmAdvisory) {
+        warnings.push(llmAdvisory);
+      }
+
+      if (warnings.length > 0) {
+        process.stdout.write(JSON.stringify({
+          decision: 'allow',
+          additionalContext: `[pbr] Advisory: ${warnings.join('; ')}.`
+        }));
+        process.exit(0);
       }
 
       process.exit(0);

package/plugins/pbr/scripts/status-line.js

@@ -15,6 +15,7 @@ const path = require('path');
 const cp = require('child_process');
 const { logHook } = require('./hook-logger');
 const { configLoad } = require('./pbr-tools');
+const llmMetricsModule = require('./local-llm/metrics');
 
 // ANSI color codes
 const c = {
@@ -36,7 +37,7 @@ const c = {
 
 // Default status_line config — works out of the box with zero config
 const DEFAULTS = {
-  sections: ['phase', 'plan', 'status', 'git', 'context'],
+  sections: ['phase', 'plan', 'status', 'git', 'context', 'llm'],
   brand_text: '\u25C6 Plan-Build-Run',
   max_status_length: 50,
   context_bar: {
@@ -170,6 +171,17 @@ function formatDuration(ms) {
   return `${minutes}m`;
 }
 
+/**
+ * Format a token count with K/M suffixes for compact display.
+ * @param {number} tokens
+ * @returns {string}
+ */
+function formatTokens(tokens) {
+  if (tokens >= 1_000_000) return (tokens / 1_000_000).toFixed(1) + 'M';
+  if (tokens >= 1_000) return (tokens / 1_000).toFixed(1) + 'K';
+  return String(tokens);
+}
+
 function main() {
   const stdinData = readStdin();
   const cwd = process.cwd();
@@ -184,7 +196,7 @@ function main() {
     const slConfig = loadStatusLineConfig(planningDir);
     const content = fs.readFileSync(stateFile, 'utf8');
     const ctxPercent = getContextPercent(stdinData);
-    const status = buildStatusLine(content, ctxPercent, slConfig, stdinData);
+    const status = buildStatusLine(content, ctxPercent, slConfig, stdinData, planningDir);
 
     if (status) {
       process.stdout.write(status);
@@ -214,7 +226,7 @@ function parseFrontmatter(content) {
   return result;
 }
 
-function buildStatusLine(content, ctxPercent, cfg, stdinData) {
+function buildStatusLine(content, ctxPercent, cfg, stdinData, planningDir) {
   const config = cfg || DEFAULTS;
   const sections = config.sections || DEFAULTS.sections;
   const brandText = config.brand_text || DEFAULTS.brand_text;
@@ -314,8 +326,41 @@ function buildStatusLine(content, ctxPercent, cfg, stdinData) {
 
   if (parts.length === 0) return null;
 
-  return parts.join(` ${c.dim}\u2502${c.reset} `);
+  let output = parts.join(` ${c.dim}\u2502${c.reset} `);
+
+  // LLM offload section — renders on a second line below the main status
+  // Shows session stats + lifetime total when both are available
+  if (sections.includes('llm') && planningDir) {
+    try {
+      const lifetime = llmMetricsModule.computeLifetimeMetrics(planningDir);
+      if (lifetime && lifetime.total_calls > 0) {
+        // Try to get session-scoped metrics using duration from stdin
+        let sessionPart = '';
+        const durationMs = sd.cost && sd.cost.total_duration_ms;
+        if (durationMs != null && durationMs > 0) {
+          const sessionStart = new Date(Date.now() - durationMs);
+          const sessionEntries = llmMetricsModule.readSessionMetrics(planningDir, sessionStart);
+          const session = llmMetricsModule.summarizeMetrics(sessionEntries);
+          if (session.total_calls > 0) {
+            sessionPart = `${c.dim}${session.total_calls} calls${c.reset} ${c.dim}\u00B7${c.reset} ${c.green}${formatTokens(session.tokens_saved)} saved${c.reset}`;
+          }
+        }
+
+        const lifetimePart = `${c.dim}${formatTokens(lifetime.tokens_saved)} lifetime${c.reset}`;
+
+        if (sessionPart) {
+          output += `\n${c.green}Local LLM${c.reset} ${sessionPart} ${c.dim}\u2502${c.reset} ${lifetimePart}`;
+        } else {
+          output += `\n${c.green}Local LLM${c.reset} ${c.dim}${lifetime.total_calls} calls${c.reset} ${c.dim}\u00B7${c.reset} ${c.green}${formatTokens(lifetime.tokens_saved)} saved${c.reset}`;
+        }
+      }
+    } catch (_e) {
+      // No metrics available — skip silently
+    }
+  }
+
+  return output;
 }
 
 if (require.main === module || process.argv[1] === __filename) { main(); }
-module.exports = { buildStatusLine, buildContextBar, getContextPercent, getGitInfo, formatDuration, loadStatusLineConfig, parseFrontmatter, DEFAULTS };
+module.exports = { buildStatusLine, buildContextBar, getContextPercent, getGitInfo, formatDuration, formatTokens, loadStatusLineConfig, parseFrontmatter, DEFAULTS };

package/plugins/pbr/scripts/validate-commit.js

@@ -17,10 +17,13 @@
  *   2 = invalid commit message format (blocks the tool)
  */
 
+const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
 const { logHook } = require('./hook-logger');
 const { logEvent } = require('./event-logger');
+const { resolveConfig } = require('./local-llm/health');
+const { classifyCommit } = require('./local-llm/operations/classify-commit');
 
 const VALID_TYPES = ['feat', 'fix', 'refactor', 'test', 'docs', 'chore', 'wip'];
 
@@ -149,12 +152,64 @@ function checkCommit(data) {
   return null;
 }
 
+/**
+ * Load and resolve the local_llm config block from .planning/config.json.
+ * Returns a resolved config (always safe to use — disabled by default on error).
+ */
+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);
+  }
+}
+
+/**
+ * Async LLM enrichment for commit messages. Returns an advisory string or null.
+ * Called after checkCommit passes (valid format) to provide semantic classification.
+ *
+ * @param {object} data - parsed hook data
+ * @returns {Promise<string|null>}
+ */
+async function enrichCommitLlm(data) {
+  try {
+    const command = data.tool_input?.command || '';
+    const message = extractCommitMessage(command);
+    if (!message) return null;
+
+    const cwd = process.cwd();
+    const llmConfig = loadLocalLlmConfig(cwd);
+    const planningDir = path.join(cwd, '.planning');
+
+    // Get staged files for scope validation
+    let stagedFiles = [];
+    try {
+      const output = execSync('git diff --cached --name-only', { encoding: 'utf8' });
+      stagedFiles = output.trim().split('\n').filter(Boolean);
+    } catch (_e) {
+      // Not in a git repo — skip staged files context
+    }
+
+    const llmResult = await classifyCommit(llmConfig, planningDir, message, stagedFiles, data.session_id);
+    if (llmResult && llmResult.classification !== 'correct') {
+      return 'LLM commit advisory: ' + llmResult.classification +
+        ' (confidence: ' + (llmResult.confidence * 100).toFixed(0) + '%)';
+    }
+    return null;
+  } catch (_llmErr) {
+    // Never propagate LLM errors
+    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 result = checkCommit(data);
@@ -162,6 +217,15 @@ function main() {
         process.stdout.write(JSON.stringify(result.output));
         process.exit(result.exitCode);
       }
+
+      // LLM semantic classification — advisory only (after format validation passes)
+      const llmAdvisory = await enrichCommitLlm(data);
+      if (llmAdvisory) {
+        process.stdout.write(JSON.stringify({
+          additionalContext: '[pbr] ' + llmAdvisory
+        }));
+      }
+
       process.exit(0);
     } catch (_e) {
       // Parse error - don't block
@@ -197,5 +261,5 @@ function extractCommitMessage(command) {
   return null;
 }
 
-module.exports = { checkCommit };
+module.exports = { checkCommit, enrichCommitLlm };
 if (require.main === module || process.argv[1] === __filename) { main(); }