@sienklogic/plan-build-run 2.22.2 → 2.24.0

package/plugins/pbr/scripts/local-llm/router.js

@@ -0,0 +1,101 @@
+'use strict';
+
+const { runShadow } = require('./shadow');
+
+const COMPLEXITY_HIGH_THRESHOLD = 0.65;
+
+/**
+ * Scores the complexity of a prompt using a weighted surface heuristic.
+ * Returns a value in [0, 1] where higher means more complex.
+ *
+ * @param {string} prompt
+ * @returns {number}
+ */
+function scoreComplexity(prompt) {
+  const words = prompt.split(/\s+/).length;
+  const codeBlocks = (prompt.match(/```/g) || []).length / 2;
+  const constraints = (prompt.match(/\b(must|should|exactly|only|never|always)\b/gi) || []).length;
+  const reasoning = (prompt.match(/\b(why|explain|compare|analyze|reason|evaluate)\b/gi) || []).length;
+  const structuredOut = /\b(json|schema|yaml|frontmatter)\b/i.test(prompt) ? 1 : 0;
+  return Math.min(words / 500, 1.0) * 0.25 +
+         Math.min(codeBlocks / 3, 1.0) * 0.20 +
+         Math.min(constraints / 5, 1.0) * 0.20 +
+         Math.min(reasoning / 3, 1.0) * 0.20 +
+         structuredOut * 0.15;
+}
+
+/**
+ * Extracts a confidence score from logprobs data returned by the local LLM.
+ * Returns a value in [0, 1] or null if no logprobs data is available.
+ *
+ * @param {Array<{token: string, logprob: number}>|null|undefined} logprobsData
+ * @returns {number|null}
+ */
+function extractConfidence(logprobsData) {
+  if (!logprobsData || logprobsData.length === 0) return null;
+  const sum = logprobsData.reduce((acc, t) => acc + t.logprob, 0);
+  const avgLogprob = sum / logprobsData.length;
+  return Math.min(1, Math.max(0, Math.exp(avgLogprob)));
+}
+
+/**
+ * Routes a prompt through local LLM or signals caller to use frontier model.
+ * Returns the local LLM result if local is suitable, or null if caller should
+ * fall back to frontier. Never throws — all errors return null.
+ *
+ * @param {object} config - local_llm config block with routing_strategy and advanced settings
+ * @param {string} prompt - the prompt being routed
+ * @param {string} operationType - operation identifier
+ * @param {function(boolean): Promise<{content: string, logprobsData: Array|null}>} callLocalFn
+ *   Async function accepting a logprobs boolean, returns the local LLM result object.
+ * @param {string} [planningDir] - path to .planning directory; when provided enables shadow mode
+ * @param {Function} [frontierResultFn] - async function that calls the frontier model;
+ *   NOTE: parameter inversion vs shadow.js — here LOCAL has already run (it's the primary result)
+ *   and FRONTIER is the shadow. We pass frontierResultFn as shadow.js arg 4 (localResultFn slot)
+ *   so shadow.js calls it, and result.content as arg 5 (frontierResult slot, the committed result).
+ * @returns {Promise<{content: string, logprobsData: Array|null}|null>}
+ */
+async function route(config, prompt, operationType, callLocalFn, planningDir, frontierResultFn) {
+  try {
+    const routingStrategy = (config && config.routing_strategy) || 'local_first';
+    const confidenceThreshold = (config && config.advanced && config.advanced.confidence_threshold) || 0.9;
+
+    if (routingStrategy === 'quality_first') {
+      const score = scoreComplexity(prompt);
+      if (score >= 0.3) return null;
+      const result = await callLocalFn(false);
+      if (result !== null && planningDir && frontierResultFn) {
+        runShadow(config, planningDir, operationType, frontierResultFn, result.content);
+      }
+      return result;
+    }
+
+    if (routingStrategy === 'balanced') {
+      const score = scoreComplexity(prompt);
+      if (score > 0.45) return null;
+      const result = await callLocalFn(true);
+      const confidence = extractConfidence(result && result.logprobsData);
+      if (confidence === null || confidence < 0.75) return null;
+      if (result !== null && planningDir && frontierResultFn) {
+        runShadow(config, planningDir, operationType, frontierResultFn, result.content);
+      }
+      return result;
+    }
+
+    // Default: local_first
+    const score = scoreComplexity(prompt);
+    if (score > COMPLEXITY_HIGH_THRESHOLD) return null;
+    const result = await callLocalFn(true);
+    const confidence = extractConfidence(result && result.logprobsData);
+    if (confidence === null || confidence < confidenceThreshold) return null;
+    if (result !== null && planningDir && frontierResultFn) {
+      runShadow(config, planningDir, operationType, frontierResultFn, result.content);
+    }
+    return result;
+  } catch (_) {
+    return null;
+  }
+}
+
+module.exports = { route, scoreComplexity, extractConfidence };
+module.exports.COMPLEXITY_HIGH_THRESHOLD = COMPLEXITY_HIGH_THRESHOLD;

package/plugins/pbr/scripts/local-llm/shadow.js

@@ -0,0 +1,60 @@
+'use strict';
+
+const { logAgreement } = require('./metrics');
+
+/**
+ * Fire-and-forget shadow comparison.
+ * When shadow_mode is enabled, runs localResultFn() in the background and
+ * logs agreement/disagreement with frontierResult — but ALWAYS returns frontierResult.
+ *
+ * @param {object} config - resolved config from resolveConfig()
+ * @param {string} planningDir - path to the .planning directory
+ * @param {string} operationType - e.g. 'artifact_classification'
+ * @param {Function} localResultFn - async function that returns the local LLM result
+ * @param {*} frontierResult - the result already returned to the caller (never changed)
+ * @param {string} [sessionId] - current session identifier
+ * @returns {*} frontierResult — unchanged
+ */
+function runShadow(config, planningDir, operationType, localResultFn, frontierResult, sessionId) {
+  // Shadow off or LLM disabled — return immediately
+  if (!config.advanced || !config.advanced.shadow_mode) {
+    return frontierResult;
+  }
+  if (!config.enabled) {
+    return frontierResult;
+  }
+
+  // Fire-and-forget: never propagates errors, never affects frontierResult
+  Promise.resolve()
+    .then(async () => {
+      let localValue;
+      try {
+        const raw = await localResultFn();
+        localValue = typeof raw === 'string' ? raw : JSON.stringify(raw);
+      } catch (_) {
+        // Local call failed — log as disagreement
+        localValue = null;
+      }
+
+      const frontierStr =
+        typeof frontierResult === 'string' ? frontierResult : JSON.stringify(frontierResult);
+      const localStr = localValue != null ? localValue.trim() : null;
+      const agrees = localStr !== null && localStr === frontierStr.trim();
+
+      logAgreement(planningDir, {
+        timestamp: new Date().toISOString(),
+        operation: operationType,
+        session_id: sessionId || 'unknown',
+        agrees,
+        local_result: localStr,
+        frontier_result: frontierStr
+      });
+    })
+    .catch(() => {
+      // Swallow all errors — shadow must never throw
+    });
+
+  return frontierResult;
+}
+
+module.exports = { runShadow };

package/plugins/pbr/scripts/local-llm/threshold-tuner.js

@@ -0,0 +1,118 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// --- Constants ---
+
+/** Minimum shadow log entries per operation before suggesting an adjustment */
+const MIN_SAMPLES = 20;
+
+/** Step size for each threshold adjustment */
+const ADJUST_STEP = 0.05;
+
+/** Clamp floor for suggested threshold */
+const THRESHOLD_MIN = 0.5;
+
+/** Clamp ceiling for suggested threshold */
+const THRESHOLD_MAX = 0.99;
+
+/**
+ * Failure rate above which local LLM is considered too unreliable.
+ * Suggests raising the confidence_threshold so fewer calls are routed locally.
+ */
+const HIGH_FAILURE_RATE = 0.20;
+
+/**
+ * Failure rate below which local LLM is considered very reliable.
+ * Suggests lowering the confidence_threshold so more calls are routed locally.
+ */
+const LOW_FAILURE_RATE = 0.05;
+
+/**
+ * Reads the shadow agreement log and returns advisory threshold adjustments
+ * per operation type.
+ *
+ * Only emits a suggestion for an operation when it has >= MIN_SAMPLES entries.
+ * All suggestions are ±ADJUST_STEP clamped to [THRESHOLD_MIN, THRESHOLD_MAX].
+ * Never writes to config — purely advisory.
+ *
+ * @param {string} planningDir - Absolute path to the .planning directory
+ * @param {number} currentThreshold - Current confidence_threshold from config
+ * @returns {Array<{operation: string, current: number, suggested: number, sample_count: number, agreement_rate: number}>}
+ */
+function computeThresholdAdjustments(planningDir, currentThreshold) {
+  try {
+    const shadowLogPath = path.join(planningDir, 'logs', 'local-llm-shadow.jsonl');
+
+    if (!fs.existsSync(shadowLogPath)) {
+      return [];
+    }
+
+    const raw = fs.readFileSync(shadowLogPath, 'utf8');
+    const lines = raw.split('\n').filter(l => l.trim().length > 0);
+
+    // Parse lines, skip unparseable
+    const entries = [];
+    for (const line of lines) {
+      try {
+        const parsed = JSON.parse(line);
+        if (parsed && typeof parsed === 'object') {
+          entries.push(parsed);
+        }
+      } catch (_e) {
+        // Skip malformed lines
+      }
+    }
+
+    // Group by operation
+    const groups = {};
+    for (const entry of entries) {
+      const op = entry.operation;
+      if (!op) continue;
+      if (!groups[op]) {
+        groups[op] = { count: 0, agrees: 0 };
+      }
+      groups[op].count += 1;
+      if (entry.agrees === true) {
+        groups[op].agrees += 1;
+      }
+    }
+
+    // Build suggestions for operations with enough samples
+    const suggestions = [];
+    for (const [operation, stats] of Object.entries(groups)) {
+      if (stats.count < MIN_SAMPLES) continue;
+
+      const agreementRate = stats.agrees / stats.count;
+      const failureRate = 1 - agreementRate;
+
+      let suggested;
+      if (failureRate > HIGH_FAILURE_RATE) {
+        // Local is too unreliable — raise threshold (fewer local calls)
+        suggested = Math.min(THRESHOLD_MAX, currentThreshold + ADJUST_STEP);
+      } else if (failureRate < LOW_FAILURE_RATE) {
+        // Local is very reliable — lower threshold (more local calls)
+        suggested = Math.max(THRESHOLD_MIN, currentThreshold - ADJUST_STEP);
+      } else {
+        // Within acceptable range — no change
+        suggested = currentThreshold;
+      }
+
+      suggestions.push({
+        operation,
+        current: currentThreshold,
+        suggested,
+        sample_count: stats.count,
+        agreement_rate: agreementRate
+      });
+    }
+
+    return suggestions;
+  } catch (_e) {
+    // Never throws
+    return [];
+  }
+}
+
+module.exports = { computeThresholdAdjustments };

package/plugins/pbr/scripts/pbr-tools.js

@@ -20,10 +20,18 @@
  *   roadmap update-plans <phase> <complete> <total> — Update phase plans in ROADMAP.md
  *   history append <type> <title> [body] — Append record to HISTORY.md
  *   history load                         — Load all HISTORY.md records as JSON
+ *   llm metrics [--session <ISO>]        — Lifetime or session-scoped LLM usage metrics
  */
 
 const fs = require('fs');
 const path = require('path');
+const { resolveConfig, checkHealth } = require('./local-llm/health');
+const { classifyArtifact } = require('./local-llm/operations/classify-artifact');
+const { scoreSource } = require('./local-llm/operations/score-source');
+const { classifyError } = require('./local-llm/operations/classify-error');
+const { summarizeContext } = require('./local-llm/operations/summarize-context');
+const { readSessionMetrics, summarizeMetrics, computeLifetimeMetrics } = require('./local-llm/metrics');
+const { computeThresholdAdjustments } = require('./local-llm/threshold-tuner');
 
 const cwd = process.cwd();
 const planningDir = path.join(cwd, '.planning');
@@ -207,7 +215,7 @@ function resolveDepthProfile(config) {
   return { depth, profile };
 }
 
-function main() {
+async function main() {
   const args = process.argv.slice(2);
   const command = args[0];
   const subcommand = args[1];
@@ -292,8 +300,117 @@ function main() {
       const { logEvent } = require('./event-logger');
       logEvent(category, event, details);
       output({ logged: true, category, event });
+    } else if (command === 'llm' && subcommand === 'health') {
+      let rawConfig = {};
+      try { rawConfig = configLoad(planningDir) || {}; } catch (_e) { /* use defaults */ }
+      const llmConfig = resolveConfig(rawConfig.local_llm);
+      const health = await checkHealth(llmConfig);
+      output(health);
+    } else if (command === 'llm' && subcommand === 'status') {
+      let rawConfig = {};
+      try { rawConfig = configLoad(planningDir) || {}; } catch (_e) { /* use defaults */ }
+      const llmConfig = resolveConfig(rawConfig.local_llm);
+      output({
+        enabled: llmConfig.enabled,
+        model: llmConfig.model,
+        endpoint: llmConfig.endpoint,
+        features: llmConfig.features,
+        metrics_file: path.join(planningDir, 'logs', 'local-llm-metrics.jsonl'),
+        timeout_ms: llmConfig.timeout_ms,
+        disable_after_failures: llmConfig.advanced.disable_after_failures
+      });
+    } else if (command === 'llm' && subcommand === 'classify') {
+      const fileType = args[2];
+      const filePath = args[3];
+      if (!fileType || !filePath) {
+        error('Usage: pbr-tools.js llm classify <PLAN|SUMMARY> <filepath>');
+      }
+      const upperType = fileType.toUpperCase();
+      if (upperType !== 'PLAN' && upperType !== 'SUMMARY') {
+        error('llm classify: fileType must be PLAN or SUMMARY');
+      }
+      let content = '';
+      try {
+        content = fs.readFileSync(filePath, 'utf8');
+      } catch (_e) {
+        error('llm classify: cannot read file: ' + filePath);
+      }
+      let rawConfig = {};
+      try { rawConfig = configLoad(planningDir) || {}; } catch (_e) { /* use defaults */ }
+      const llmConfig = resolveConfig(rawConfig.local_llm);
+      const result = await classifyArtifact(llmConfig, planningDir, content, upperType, undefined);
+      output(result || { classification: null, reason: 'LLM disabled or unavailable' });
+    } else if (command === 'llm' && subcommand === 'score-source') {
+      const sourceUrl = args[2];
+      const filePath = args[3];
+      if (!sourceUrl || !filePath) {
+        error('Usage: pbr-tools.js llm score-source <url> <file-path>');
+      }
+      if (!fs.existsSync(filePath)) {
+        error('File not found: ' + filePath);
+      }
+      const content = fs.readFileSync(filePath, 'utf8');
+      let rawConfig = {};
+      try { rawConfig = configLoad(planningDir) || {}; } catch (_e) { /* use defaults */ }
+      const llmConfig = resolveConfig(rawConfig.local_llm);
+      const result = await scoreSource(llmConfig, planningDir, content, sourceUrl, undefined);
+      output(result || { level: null, reason: 'LLM disabled or unavailable' });
+    } else if (command === 'llm' && subcommand === 'classify-error') {
+      const filePath = args[2];
+      const agentType = args[3] || 'unknown';
+      if (!filePath) {
+        error('Usage: pbr-tools.js llm classify-error <file-path> [agent-type]');
+      }
+      if (!fs.existsSync(filePath)) {
+        error('File not found: ' + filePath);
+      }
+      const errorText = fs.readFileSync(filePath, 'utf8');
+      let rawConfig = {};
+      try { rawConfig = configLoad(planningDir) || {}; } catch (_e) { /* use defaults */ }
+      const llmConfig = resolveConfig(rawConfig.local_llm);
+      const result = await classifyError(llmConfig, planningDir, errorText, agentType, undefined);
+      output(result || { category: null, reason: 'LLM disabled or unavailable' });
+    } else if (command === 'llm' && subcommand === 'summarize') {
+      const filePath = args[2];
+      const maxWords = args[3] ? parseInt(args[3], 10) : undefined;
+      if (!filePath) {
+        error('Usage: pbr-tools.js llm summarize <file-path> [max-words]');
+      }
+      if (!fs.existsSync(filePath)) {
+        error('File not found: ' + filePath);
+      }
+      const contextText = fs.readFileSync(filePath, 'utf8');
+      let rawConfig = {};
+      try { rawConfig = configLoad(planningDir) || {}; } catch (_e) { /* use defaults */ }
+      const llmConfig = resolveConfig(rawConfig.local_llm);
+      const result = await summarizeContext(llmConfig, planningDir, contextText, maxWords, undefined);
+      output(result || { summary: null, reason: 'LLM disabled or unavailable' });
+    } else if (command === 'llm' && subcommand === 'metrics') {
+      const sessionFlag = args[2]; // '--session'
+      const sessionStart = args[3]; // ISO timestamp
+      let rawConfig = {};
+      try { rawConfig = configLoad(planningDir) || {}; } catch (_e) { /* defaults */ }
+      const rate = rawConfig.local_llm && rawConfig.local_llm.metrics && rawConfig.local_llm.metrics.frontier_token_rate
+        ? rawConfig.local_llm.metrics.frontier_token_rate : 3.0;
+      if (sessionFlag === '--session' && sessionStart) {
+        const entries = readSessionMetrics(planningDir, sessionStart);
+        const summary = summarizeMetrics(entries, rate);
+        output({ scope: 'session', session_start: sessionStart, ...summary });
+      } else {
+        const lifetime = computeLifetimeMetrics(planningDir, rate);
+        output({ scope: 'lifetime', ...lifetime });
+      }
+    } else if (command === 'llm' && subcommand === 'adjust-thresholds') {
+      let rawConfig = {};
+      try { rawConfig = configLoad(planningDir) || {}; } catch (_e) { /* use defaults */ }
+      const llmConfig = resolveConfig(rawConfig.local_llm);
+      const currentThreshold = llmConfig.advanced.confidence_threshold;
+      const suggestions = computeThresholdAdjustments(planningDir, currentThreshold);
+      output(suggestions.length > 0
+        ? { suggestions }
+        : { suggestions: [], message: 'Not enough shadow samples yet (need >= 20 per operation)' });
     } else {
-      error(`Unknown command: ${args.join(' ')}\nCommands: state load|check-progress|update, config validate, plan-index, frontmatter, must-haves, phase-info, roadmap update-status|update-plans, history append|load, event`);
+      error(`Unknown command: ${args.join(' ')}\nCommands: state load|check-progress|update, config validate, plan-index, frontmatter, must-haves, phase-info, roadmap update-status|update-plans, history append|load, event, llm health|status|classify|score-source|classify-error|summarize|metrics [--session <ISO>]|adjust-thresholds`);
     }
   } catch (e) {
     error(e.message);
@@ -1374,5 +1491,5 @@ function atomicWrite(filePath, content) {
   }
 }
 
-if (require.main === module || process.argv[1] === __filename) { main(); }
+if (require.main === module || process.argv[1] === __filename) { main().catch(err => { process.stderr.write(err.message + '\n'); process.exit(1); }); }
 module.exports = { parseStateMd, parseRoadmapMd, parseYamlFrontmatter, parseMustHaves, countMustHaves, stateLoad, stateCheckProgress, configLoad, configClearCache, configValidate, lockedFileUpdate, planIndex, determinePhaseStatus, findFiles, atomicWrite, tailLines, frontmatter, mustHavesCollect, phaseInfo, stateUpdate, roadmapUpdateStatus, roadmapUpdatePlans, updateLegacyStateField, updateFrontmatterField, updateTableRow, findRoadmapRow, resolveDepthProfile, DEPTH_PROFILE_DEFAULTS, historyAppend, historyLoad, VALID_STATUS_TRANSITIONS, validateStatusTransition };

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

@@ -68,7 +68,7 @@ function main() {
 
   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);
 
@@ -76,7 +76,7 @@ function main() {
       // Note: SUMMARY files intentionally trigger BOTH this check AND the state-sync
       // check below. The plan format check validates frontmatter structure, while
       // state-sync auto-updates ROADMAP.md and STATE.md tracking fields.
-      const planResult = checkPlanWrite(data);
+      const planResult = await checkPlanWrite(data);
       if (planResult) {
         process.stdout.write(JSON.stringify(planResult.output));
         process.exit(0);

package/plugins/pbr/scripts/progress-tracker.js

@@ -15,8 +15,9 @@ const { execSync } = require('child_process');
 const { logHook } = require('./hook-logger');
 const { logEvent } = require('./event-logger');
 const { configLoad } = require('./pbr-tools');
+const { resolveConfig, checkHealth, warmUp } = require('./local-llm/health');
 
-function main() {
+async function main() {
   const cwd = process.cwd();
   const planningDir = path.join(cwd, '.planning');
   const stateFile = path.join(planningDir, 'STATE.md');
@@ -38,9 +39,34 @@ function main() {
     tryLaunchDashboard(config.dashboard.port || 3000, planningDir, cwd);
   }
 
+  // Write session-start timestamp for local-llm metrics correlation
+  const sessionStartFile = path.join(planningDir, '.session-start');
+  try {
+    fs.writeFileSync(sessionStartFile, new Date().toISOString(), 'utf8');
+  } catch (_e) { /* non-fatal */ }
+
+  // Local LLM health check (advisory only — never blocks SessionStart)
+  let llmContext = '';
+  try {
+    const rawLlmConfig = config && config.local_llm;
+    const llmConfig = resolveConfig(rawLlmConfig);
+    if (llmConfig.enabled) {
+      const health = await checkHealth(llmConfig);
+      if (health.available) {
+        llmContext = `\nLocal LLM: ${llmConfig.model} (${health.warm ? 'warm' : 'cold start'})`;
+        if (!health.warm) {
+          // Fire warm-up without awaiting — 23s cold start must not block hook
+          warmUp(llmConfig);
+        }
+      } else if (health.reason !== 'disabled') {
+        llmContext = `\nLocal LLM: unavailable — ${health.detail || health.reason}`;
+      }
+    }
+  } catch (_e) { /* graceful degradation — never surface to user */ }
+
   if (context) {
     const output = {
-      additionalContext: context
+      additionalContext: context + llmContext
     };
     process.stdout.write(JSON.stringify(output));
     logHook('progress-tracker', 'SessionStart', 'injected', { hasState: true });
@@ -373,4 +399,4 @@ function tryLaunchDashboard(port, _planningDir, projectDir) {
 // Exported for testing
 module.exports = { getHookHealthSummary, FAILURE_DECISIONS, HOOK_HEALTH_MAX_ENTRIES, tryLaunchDashboard };
 
-main();
+main().catch(() => {});

package/plugins/pbr/scripts/session-cleanup.js

@@ -20,7 +20,8 @@
 const fs = require('fs');
 const path = require('path');
 const { logHook } = require('./hook-logger');
-const { tailLines } = require('./pbr-tools');
+const { tailLines, configLoad } = require('./pbr-tools');
+const { readSessionMetrics, summarizeMetrics, formatSessionSummary } = require('./local-llm/metrics');
 
 function readStdin() {
   try {
@@ -238,6 +239,36 @@ function main() {
   // Write session history log
   writeSessionHistory(planningDir, data);
 
+  // Local LLM metrics summary (SessionEnd — sync reads only, never throws)
+  let llmAdditionalContext = null;
+  try {
+    const sessionStartFile = path.join(planningDir, '.session-start');
+    if (fs.existsSync(sessionStartFile)) {
+      const sessionStartTime = fs.readFileSync(sessionStartFile, 'utf8').trim();
+      const entries = readSessionMetrics(planningDir, sessionStartTime);
+      if (entries.length > 0) {
+        const summary = summarizeMetrics(entries);
+        logHook('session-cleanup', 'SessionEnd', 'llm-metrics', {
+          total_calls: summary.total_calls,
+          fallback_count: summary.fallback_count,
+          avg_latency_ms: summary.avg_latency_ms,
+          tokens_saved: summary.tokens_saved,
+          cost_saved_usd: summary.cost_saved_usd
+        });
+        if (summary.total_calls > 0) {
+          let modelName = null;
+          try {
+            const rawConfig = configLoad(planningDir) || {};
+            modelName = (rawConfig.local_llm && rawConfig.local_llm.model) || null;
+          } catch (_e) { /* config read failure is non-fatal */ }
+          llmAdditionalContext = formatSessionSummary(summary, modelName);
+        }
+      }
+      // Clean up session-start file
+      try { fs.unlinkSync(sessionStartFile); } catch (_e) { /* non-fatal */ }
+    }
+  } catch (_e) { /* metrics never crash the hook */ }
+
   const decision = cleaned.length > 0 ? 'cleaned' : 'nothing';
   logHook('session-cleanup', 'SessionEnd', decision, {
     reason: data.reason || null,
@@ -246,6 +277,10 @@ function main() {
     orphaned_progress_files: orphans.length > 0 ? orphans : undefined
   });
 
+  if (llmAdditionalContext) {
+    process.stdout.write(JSON.stringify({ additionalContext: llmAdditionalContext }) + '\n');
+  }
+
   process.exit(0);
 }
 

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

@@ -20,6 +20,23 @@
 const fs = require('fs');
 const path = require('path');
 const { logHook } = require('./hook-logger');
+const { resolveConfig } = require('./local-llm/health');
+const { validateTask: llmValidateTask } = require('./local-llm/operations/validate-task');
+
+/**
+ * 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).
+ * @param {string} cwd - working directory to resolve .planning/config.json from
+ */
+function loadLocalLlmConfig(cwd) {
+  try {
+    const configPath = path.join(cwd, '.planning', 'config.json');
+    const parsed = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    return resolveConfig(parsed.local_llm);
+  } catch (_e) {
+    return resolveConfig(undefined);
+  }
+}
 
 const KNOWN_AGENTS = [
   'researcher',
@@ -687,7 +704,7 @@ function main() {
 
   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);
 
@@ -784,6 +801,18 @@ function main() {
       const activeSkillWarning = checkActiveSkillIntegrity(data);
       if (activeSkillWarning) warnings.push(activeSkillWarning);
 
+      // LLM task coherence check — advisory only
+      try {
+        const llmConfig = loadLocalLlmConfig(process.cwd());
+        const planningDir = path.join(process.cwd(), '.planning');
+        const llmResult = await llmValidateTask(llmConfig, planningDir, data.tool_input || {}, data.session_id);
+        if (llmResult && !llmResult.coherent) {
+          warnings.push('LLM task coherence advisory: ' + (llmResult.issue || 'Task description may not match intended operation.') + ' (confidence: ' + (llmResult.confidence * 100).toFixed(0) + '%)');
+        }
+      } catch (_llmErr) {
+        // Never propagate LLM errors
+      }
+
       if (warnings.length > 0) {
         for (const warning of warnings) {
           logHook('validate-task', 'PreToolUse', 'warn', { warning });

package/plugins/pbr/skills/health/SKILL.md

@@ -130,7 +130,7 @@ Read `.planning/config.json` and check for fields referenced by skills:
 - PASS: All expected fields present with correct types
 - WARN (missing fields): Report each missing field and which skill uses it — "Run `/pbr:config` to set all options."
 
-### Check 10: Orphaned Crash Recovery Files
+### Check 10: Orphaned Crash Recovery & Lock Files
 
 The executor creates `.PROGRESS-{plan_id}` files as crash recovery breadcrumbs during builds and deletes them after `SUMMARY.md` is written. Similarly, `.checkpoint-manifest.json` files track checkpoint state during execution. If the executor crashes mid-build, these files remain and could confuse future runs.
 
@@ -150,6 +150,13 @@ Glob for `.planning/phases/**/.PROGRESS-*` and `.planning/phases/**/.checkpoint-
   ```
   Fix suggestion: "Checkpoint manifests are leftover from interrupted builds. Safe to delete if no `/pbr:build` is currently running. Remove with `rm <path>`."
 
+Also check for `.planning/.active-skill`:
+
+- If the file does not exist: no action needed (PASS for this sub-check)
+- If the file exists, check its age by comparing the file modification time to the current time:
+  - If older than 1 hour: WARN with fix suggestion: "Stale .active-skill lock file detected (set {age} ago). No PBR skill appears to be running. Safe to delete with `rm .planning/.active-skill`."
+  - If younger than 1 hour: INFO: "Active skill lock exists ({content}). A PBR skill may be running."
+
 ---
 
 ## Auto-Fix for Common Corruption Patterns

package/plugins/pbr/skills/help/SKILL.md

@@ -214,10 +214,10 @@ The `features.team_discussions` config flag (and `/pbr:build --team`) enables **
 ║  ▶ NEXT UP                                                   ║
 ╚══════════════════════════════════════════════════════════════╝
 
-→ `/pbr:begin` — start a new project
-→ `/pbr:status` — check current project status
-→ `/pbr:config` — configure workflow settings
-→ `/pbr:help <command>` — detailed help for a specific command
+- `/pbr:begin` — start a new project
+- `/pbr:status` — check current project status
+- `/pbr:config` — configure workflow settings
+- `/pbr:help <command>` — detailed help for a specific command
 
 
 ```