@sienklogic/plan-build-run 2.1.0 → 2.1.1

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

@@ -0,0 +1,137 @@
+'use strict';
+
+const { complete, tryParseJSON, isDisabled } = require('../client');
+const { logMetric } = require('../metrics');
+const { route } = require('../router');
+
+const VALID_CLASSIFICATIONS = ['correct', 'type_mismatch', 'vague'];
+
+const CONVENTIONAL_COMMIT_RE = /^(feat|fix|refactor|test|docs|chore|wip|perf|ci|build|revert)(\(.*?\))?!?:/;
+
+const TEST_FILE_RE = /(?:^|[/\\])tests[/\\]|\.test\.[jt]sx?$|\.spec\.[jt]sx?$/;
+const MARKDOWN_RE = /\.mdx?$/i;
+const CONFIG_TOOLING_RE = /\.(?:json|ya?ml|toml|ini|env|lock)$|(?:^|[/\\])(?:\.github|\.husky|scripts)[/\\]|(?:Makefile|Dockerfile|\.eslintrc|\.prettierrc|babel\.config|jest\.config|tsconfig|webpack\.config|rollup\.config)/i;
+
+/**
+ * Heuristic-first classifier for git commit messages.
+ * Runs before the LLM path and returns early for unambiguous cases.
+ *
+ * @param {string} commitMessage - the commit message to classify
+ * @param {string[]} [stagedFiles] - optional list of staged file paths
+ * @returns {{ classification: string, confidence: number }|null} result or null (fall through to LLM)
+ */
+function classifyCommitHeuristic(commitMessage, stagedFiles) {
+  const match = CONVENTIONAL_COMMIT_RE.exec(commitMessage);
+  if (!match) return null;
+
+  const type = match[1];
+  const files = stagedFiles && stagedFiles.length > 0 ? stagedFiles : [];
+
+  // Check for "fix" type but description implies addition
+  const descriptionPart = commitMessage.slice(match[0].length).trim();
+  if (type === 'fix' && /^(?:add|adds|adding|new\b)/i.test(descriptionPart)) {
+    return { classification: 'type_mismatch', confidence: 0.9 };
+  }
+
+  // Type-to-file alignment checks (only when staged files are known)
+  if (files.length > 0) {
+    if (type === 'test' && files.every(f => TEST_FILE_RE.test(f))) {
+      return { classification: 'correct', confidence: 1.0 };
+    }
+
+    if (type === 'docs' && files.every(f => MARKDOWN_RE.test(f))) {
+      return { classification: 'correct', confidence: 1.0 };
+    }
+
+    if ((type === 'chore' || type === 'ci' || type === 'build') && files.every(f => CONFIG_TOOLING_RE.test(f))) {
+      return { classification: 'correct', confidence: 1.0 };
+    }
+  }
+
+  // Type parsed cleanly — most conventional commits are typed correctly
+  return { classification: 'correct', confidence: 0.8 };
+}
+
+/**
+ * Classifies a git commit message for semantic correctness using the local LLM.
+ * Goes beyond regex validation — checks whether the commit type matches the
+ * description and whether the scope aligns with the staged files.
+ *
+ * @param {object} config - resolved local_llm config block
+ * @param {string} planningDir - path to the .planning directory
+ * @param {string} commitMessage - the commit message to classify
+ * @param {string[]} [stagedFiles] - optional list of staged file paths
+ * @param {string} [sessionId] - optional session identifier for metrics
+ * @returns {Promise<{ classification: string, confidence: number, latency_ms: number, fallback_used: boolean }|null>}
+ */
+async function classifyCommit(config, planningDir, commitMessage, stagedFiles, sessionId) {
+  if (!config.enabled || !config.features.commit_classification) return null;
+  if (isDisabled('commit-classification', config.advanced.disable_after_failures)) return null;
+
+  // Heuristic-first: skip LLM for unambiguous cases
+  const heuristic = classifyCommitHeuristic(commitMessage, stagedFiles);
+  if (heuristic !== null) {
+    logMetric(planningDir, {
+      session_id: sessionId || 'unknown',
+      timestamp: new Date().toISOString(),
+      operation: 'commit-classification',
+      model: 'heuristic',
+      latency_ms: 0,
+      tokens_used_local: 0,
+      tokens_saved_frontier: 150,
+      result: heuristic.classification,
+      fallback_used: false,
+      confidence: heuristic.confidence
+    });
+    return {
+      classification: heuristic.classification,
+      confidence: heuristic.confidence,
+      latency_ms: 0,
+      fallback_used: false
+    };
+  }
+
+  const filesContext = stagedFiles && stagedFiles.length > 0
+    ? '\nStaged files: ' + stagedFiles.slice(0, 20).join(', ')
+    : '';
+
+  const prompt =
+    'Classify this git commit. Rules: "feat" = adds new feature/file, "fix" = repairs broken behavior, "refactor" = restructures without changing behavior, "test" = adds/changes tests only, "docs" = documentation only, "chore" = maintenance/tooling. Check if the type word matches what the description says. Respond JSON only: {"classification": "correct"|"type_mismatch"|"vague", "confidence": 0.0-1.0}\n\nCommit: ' +
+    commitMessage + filesContext;
+
+  try {
+    const result = await route(config, prompt, 'commit-classification', (logprobs) =>
+      complete(config, prompt, 'commit-classification', { logprobs })
+    );
+    if (result === null) return null;
+    const parsed = tryParseJSON(result.content);
+    if (!parsed.ok) return null;
+
+    if (!parsed.data.classification || !VALID_CLASSIFICATIONS.includes(parsed.data.classification)) return null;
+
+    const metricEntry = {
+      session_id: sessionId || 'unknown',
+      timestamp: new Date().toISOString(),
+      operation: 'commit-classification',
+      model: config.model,
+      latency_ms: result.latency_ms,
+      tokens_used_local: result.tokens,
+      tokens_saved_frontier: 150,
+      result: parsed.data.classification,
+      fallback_used: false,
+      confidence: parsed.data.confidence || 0.9
+    };
+    logMetric(planningDir, metricEntry);
+
+    return {
+      classification: parsed.data.classification,
+      confidence: parsed.data.confidence || 0.9,
+      latency_ms: result.latency_ms,
+      fallback_used: false
+    };
+  } catch (_) {
+    return null;
+  }
+}
+
+module.exports = { classifyCommit, classifyCommitHeuristic, VALID_CLASSIFICATIONS };

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

@@ -0,0 +1,75 @@
+'use strict';
+
+const { complete, tryParseJSON, isDisabled } = require('../client');
+const { logMetric } = require('../metrics');
+const { route } = require('../router');
+
+const ERROR_CATEGORIES = [
+  'connection_refused',
+  'timeout',
+  'missing_output',
+  'wrong_output_format',
+  'permission_error',
+  'unknown'
+];
+
+/**
+ * Classifies an agent error into one of 6 categories using the local LLM.
+ *
+ * @param {object} config - resolved local_llm config block
+ * @param {string} planningDir - path to the .planning directory
+ * @param {string} errorText - the error message or stack trace
+ * @param {string} [agentType] - the agent type that produced the error
+ * @param {string} [sessionId] - optional session identifier for metrics
+ * @returns {Promise<{ category: string, confidence: number, latency_ms: number, fallback_used: boolean }|null>}
+ */
+async function classifyError(config, planningDir, errorText, agentType, sessionId) {
+  if (!config.enabled) return null;
+  if (isDisabled('error-classification', config.advanced.disable_after_failures)) return null;
+
+  const truncatedError = errorText.length > 500 ? errorText.slice(0, 500) : errorText;
+
+  const prompt =
+    'Classify this agent error into one category. Categories: connection_refused (network/ECONNREFUSED), timeout (operation timed out), missing_output (expected file/artifact not found), wrong_output_format (output exists but malformed), permission_error (filesystem/permission issue), unknown (none of the above). Respond with JSON: {"category": "<one of the 6>", "confidence": 0.0-1.0}\n\nAgent: ' +
+    (agentType || 'unknown') +
+    '\nError: ' +
+    truncatedError;
+
+  try {
+    const result = await route(config, prompt, 'error-classification', (logprobs) =>
+      complete(config, prompt, 'error-classification', { logprobs })
+    );
+    if (result === null) return null;
+    const parsed = tryParseJSON(result.content);
+    if (!parsed.ok) return null;
+
+    const category = ERROR_CATEGORIES.includes(parsed.data.category)
+      ? parsed.data.category
+      : 'unknown';
+
+    const metricEntry = {
+      session_id: sessionId || 'unknown',
+      timestamp: new Date().toISOString(),
+      operation: 'error-classification',
+      model: config.model,
+      latency_ms: result.latency_ms,
+      tokens_used_local: result.tokens,
+      tokens_saved_frontier: 120,
+      result: category,
+      fallback_used: false,
+      confidence: parsed.data.confidence || 0.9
+    };
+    logMetric(planningDir, metricEntry);
+
+    return {
+      category,
+      confidence: parsed.data.confidence || 0.9,
+      latency_ms: result.latency_ms,
+      fallback_used: false
+    };
+  } catch (_) {
+    return null;
+  }
+}
+
+module.exports = { classifyError, ERROR_CATEGORIES };

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

@@ -0,0 +1,171 @@
+'use strict';
+
+const { complete, tryParseJSON, isDisabled } = require('../client');
+const { logMetric } = require('../metrics');
+const { route } = require('../router');
+const path = require('path');
+
+const VALID_FILE_TYPES = ['plan', 'state', 'code', 'test', 'config', 'docs', 'template', 'other'];
+const VALID_INTENTS = ['create', 'update', 'fix', 'refactor', 'delete'];
+
+// Normalize path separators to forward slashes for consistent pattern matching.
+function normalizePath(filePath) {
+  return filePath.replace(/\\/g, '/');
+}
+
+/**
+ * Heuristic-based file classification. Runs before the LLM path and returns a
+ * result object for clear-cut cases, or null for ambiguous inputs that should
+ * fall through to the LLM.
+ *
+ * @param {string} filePath - the target file path
+ * @param {string} contentSnippet - first ~200 chars of the content being written
+ * @returns {{ file_type: string, intent: string, confidence: number }|null}
+ */
+function classifyFileIntentHeuristic(filePath, contentSnippet) {
+  const normalized = normalizePath(filePath);
+  const basename = path.basename(normalized);
+  const snippet = contentSnippet || '';
+
+  // --- Extension map (test extensions checked before generic ones) ---
+  if (/\.(test|spec)\.(js|ts|mjs|cjs)$/.test(basename)) {
+    return { file_type: 'test', intent: 'update', confidence: 1.0 };
+  }
+  if (/\.(tmpl|ejs)$/.test(basename)) {
+    return { file_type: 'template', intent: 'update', confidence: 1.0 };
+  }
+  if (/\.(json|yaml|yml)$/.test(basename)) {
+    return { file_type: 'config', intent: 'update', confidence: 1.0 };
+  }
+  if (/\.(js|ts|mjs|cjs)$/.test(basename)) {
+    // Even if in tests/ directory the double-extension rule above already caught it,
+    // but check path pattern here too as an extra safety net.
+    if (/(?:^|\/)(?:tests?|__tests__)\//.test(normalized)) {
+      return { file_type: 'test', intent: 'update', confidence: 1.0 };
+    }
+    return { file_type: 'code', intent: 'update', confidence: 1.0 };
+  }
+
+  // --- Path patterns (checked before .md extension so directory wins) ---
+  if (/(?:^|\/)(?:tests?|__tests__)\//.test(normalized)) {
+    return { file_type: 'test', intent: 'update', confidence: 1.0 };
+  }
+  if (/(?:^|\/)docs\//.test(normalized)) {
+    return { file_type: 'docs', intent: 'update', confidence: 1.0 };
+  }
+  if (/(?:^|\/)scripts\//.test(normalized)) {
+    return { file_type: 'code', intent: 'update', confidence: 1.0 };
+  }
+  // .planning/ special cases — STATE.md first, then general plan
+  if (/(?:^|\/)\.planning\//.test(normalized)) {
+    if (basename === 'STATE.md') {
+      return { file_type: 'state', intent: 'update', confidence: 1.0 };
+    }
+    return { file_type: 'plan', intent: 'update', confidence: 1.0 };
+  }
+
+  // --- Content signals (apply to any extension) ---
+  const trimmed = snippet.trimStart();
+  if (/^(?:describe|test|it)\s*\(/.test(trimmed)) {
+    return { file_type: 'test', intent: 'update', confidence: 1.0 };
+  }
+
+  // --- .md extension: only classify when in a recognized path, else null ---
+  if (/\.md$/.test(basename)) {
+    // docs/ and .planning/ were already handled above; all other .md is ambiguous.
+    return null;
+  }
+
+  // Anything else is ambiguous — let the LLM decide.
+  return null;
+}
+
+/**
+ * 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;
+
+  // --- Heuristic fast-path: skip the LLM for deterministic cases ---
+  const heuristic = classifyFileIntentHeuristic(filePath, snippet);
+  if (heuristic !== null) {
+    logMetric(planningDir, {
+      session_id: sessionId || 'unknown',
+      timestamp: new Date().toISOString(),
+      operation: 'file-intent',
+      model: 'heuristic',
+      latency_ms: 0,
+      tokens_used_local: 0,
+      tokens_saved_frontier: 150,
+      result: heuristic.file_type + '/' + heuristic.intent,
+      fallback_used: false,
+      confidence: heuristic.confidence
+    });
+    return {
+      file_type: heuristic.file_type,
+      intent: heuristic.intent,
+      confidence: heuristic.confidence,
+      latency_ms: 0,
+      fallback_used: false
+    };
+  }
+  // --- End heuristic fast-path ---
+
+  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, classifyFileIntentHeuristic, VALID_FILE_TYPES, VALID_INTENTS };

package/plugins/pbr/scripts/local-llm/operations/score-source.js

@@ -0,0 +1,72 @@
+'use strict';
+
+const { complete, tryParseJSON, isDisabled } = require('../client');
+const { logMetric } = require('../metrics');
+const { route } = require('../router');
+
+const SOURCE_LEVELS = ['S0', 'S1', 'S2', 'S3', 'S4', 'S5', 'S6'];
+
+/**
+ * Scores a research source on the S0-S6 credibility scale using the local LLM.
+ *
+ * S0=local prior research, S1=live MCP docs, S2=official docs, S3=official GitHub,
+ * S4=verified WebSearch (2+ sources), S5=unverified WebSearch, S6=training knowledge.
+ *
+ * @param {object} config - resolved local_llm config block
+ * @param {string} planningDir - path to the .planning directory
+ * @param {string} sourceText - text content from the source
+ * @param {string} sourceUrl - URL or identifier for the source
+ * @param {string} [sessionId] - optional session identifier for metrics
+ * @returns {Promise<{ level: string, confidence: number, reason: string, latency_ms: number, fallback_used: boolean }|null>}
+ */
+async function scoreSource(config, planningDir, sourceText, sourceUrl, sessionId) {
+  if (!config.enabled) return null;
+  if (!config.features || !config.features.source_scoring) return null;
+  if (isDisabled('source-scoring', config.advanced.disable_after_failures)) return null;
+
+  const maxChars = (config.advanced.max_input_tokens || 1024) * 4;
+  const truncated = sourceText.length > maxChars ? sourceText.slice(0, maxChars) : sourceText;
+
+  const prompt =
+    'Score this research source on the S0-S6 credibility scale. S0=local prior research, S1=live MCP docs, S2=official docs, S3=official GitHub, S4=verified WebSearch (2+ sources), S5=unverified WebSearch, S6=training knowledge. Respond with JSON: {"level": "S0"-"S6", "confidence": 0.0-1.0, "reason": "one sentence"}\n\nURL: ' +
+    sourceUrl +
+    '\nContent excerpt:\n' +
+    truncated;
+
+  try {
+    const result = await route(config, prompt, 'source-scoring', (logprobs) =>
+      complete(config, prompt, 'source-scoring', { logprobs })
+    );
+    if (result === null) return null;
+    const parsed = tryParseJSON(result.content);
+    if (!parsed.ok) return null;
+
+    const level = SOURCE_LEVELS.includes(parsed.data.level) ? parsed.data.level : 'S6';
+
+    const metricEntry = {
+      session_id: sessionId || 'unknown',
+      timestamp: new Date().toISOString(),
+      operation: 'source-scoring',
+      model: config.model,
+      latency_ms: result.latency_ms,
+      tokens_used_local: result.tokens,
+      tokens_saved_frontier: 80,
+      result: level,
+      fallback_used: false,
+      confidence: parsed.data.confidence || 0.9
+    };
+    logMetric(planningDir, metricEntry);
+
+    return {
+      level,
+      confidence: parsed.data.confidence || 0.9,
+      reason: parsed.data.reason || '',
+      latency_ms: result.latency_ms,
+      fallback_used: false
+    };
+  } catch (_) {
+    return null;
+  }
+}
+
+module.exports = { scoreSource, SOURCE_LEVELS };

package/plugins/pbr/scripts/local-llm/operations/summarize-context.js

@@ -0,0 +1,62 @@
+'use strict';
+
+const { complete, isDisabled } = require('../client');
+const { logMetric } = require('../metrics');
+const { route } = require('../router');
+
+/**
+ * Produces a concise plain-text summary of project context using the local LLM.
+ *
+ * @param {object} config - resolved local_llm config block
+ * @param {string} planningDir - path to the .planning directory
+ * @param {string} contextText - project context text to summarize
+ * @param {number} [maxWords] - target word count for the summary (default 150)
+ * @param {string} [sessionId] - optional session identifier for metrics
+ * @returns {Promise<{ summary: string, latency_ms: number, fallback_used: boolean }|null>}
+ */
+async function summarizeContext(config, planningDir, contextText, maxWords, sessionId) {
+  if (!config.enabled) return null;
+  if (!config.features.context_summarization) return null;
+  if (isDisabled('context-summarization', config.advanced.disable_after_failures)) return null;
+
+  const maxChars = (config.advanced.max_input_tokens || 1024) * 4;
+  const truncated = contextText.length > maxChars ? contextText.slice(0, maxChars) : contextText;
+  const targetWords = maxWords || 150;
+
+  const prompt =
+    'Summarize the following project context in under ' +
+    targetWords +
+    ' words. Focus on: current phase goal, key decisions made, what is built so far, and what is still needed. Output plain text only — no JSON, no headings, no bullet points.\n\nContext:\n' +
+    truncated;
+
+  try {
+    const result = await route(config, prompt, 'context-summarization', (logprobs) =>
+      complete(config, prompt, 'context-summarization', { logprobs })
+    );
+    if (result === null) return null;
+
+    const metricEntry = {
+      session_id: sessionId || 'unknown',
+      timestamp: new Date().toISOString(),
+      operation: 'context-summarization',
+      model: config.model,
+      latency_ms: result.latency_ms,
+      tokens_used_local: result.tokens,
+      tokens_saved_frontier: 350,
+      result: 'summary',
+      fallback_used: false,
+      confidence: 0.9
+    };
+    logMetric(planningDir, metricEntry);
+
+    return {
+      summary: result.content.trim(),
+      latency_ms: result.latency_ms,
+      fallback_used: false
+    };
+  } catch (_) {
+    return null;
+  }
+}
+
+module.exports = { summarizeContext };

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/local-llm/operations/validate-task.js

@@ -0,0 +1,59 @@
+'use strict';
+
+const { complete, tryParseJSON, isDisabled } = require('../client');
+const { logMetric } = require('../metrics');
+const { route } = require('../router');
+
+/**
+ * Validates a Task() call for coherence using the local LLM.
+ *
+ * @param {object} config - resolved local_llm config block
+ * @param {string} planningDir - path to the .planning directory
+ * @param {{ description: string, subagent_type: string }} taskInput - the Task() call to validate
+ * @param {string} [sessionId] - optional session identifier for metrics
+ * @returns {Promise<{ coherent: boolean, confidence: number, issue: string|null, latency_ms: number, fallback_used: boolean }|null>}
+ */
+async function validateTask(config, planningDir, taskInput, sessionId) {
+  if (!config.enabled || !config.features.task_validation) return null;
+  if (isDisabled('task-validation', config.advanced.disable_after_failures)) return null;
+
+  const prompt =
+    'Assess this Task() call for coherence. Check: (1) description is meaningful and not empty, (2) if subagent_type starts with \'pbr:\' the agent name is valid, (3) description matches the intended operation. Known pbr agents: researcher, planner, plan-checker, executor, verifier, integration-checker, debugger, codebase-mapper, synthesizer, general. Respond with JSON: {"coherent": true|false, "confidence": 0.0-1.0, "issue": "null or one sentence describing the problem"}\n\nTask input: ' +
+    JSON.stringify({ description: taskInput.description, subagent_type: taskInput.subagent_type });
+
+  try {
+    const result = await route(config, prompt, 'task-validation', (logprobs) =>
+      complete(config, prompt, 'task-validation', { logprobs })
+    );
+    if (result === null) return null;
+    const parsed = tryParseJSON(result.content);
+    if (!parsed.ok) return null;
+    if (typeof parsed.data.coherent !== 'boolean') return null;
+
+    const metricEntry = {
+      session_id: sessionId || 'unknown',
+      timestamp: new Date().toISOString(),
+      operation: 'task-validation',
+      model: config.model,
+      latency_ms: result.latency_ms,
+      tokens_used_local: result.tokens,
+      tokens_saved_frontier: 180,
+      result: parsed.data.coherent ? 'coherent' : 'incoherent',
+      fallback_used: false,
+      confidence: parsed.data.confidence || 0.9
+    };
+    logMetric(planningDir, metricEntry);
+
+    return {
+      coherent: parsed.data.coherent,
+      confidence: parsed.data.confidence || 0.9,
+      issue: parsed.data.issue || null,
+      latency_ms: result.latency_ms,
+      fallback_used: false
+    };
+  } catch (_) {
+    return null;
+  }
+}
+
+module.exports = { validateTask };