@sienklogic/plan-build-run 2.11.0 → 2.12.1

package/plugins/pbr/scripts/lib/dashboard-launch.js

@@ -0,0 +1,170 @@
+'use strict';
+
+/**
+ * Dashboard and hook server launch module — extracted from progress-tracker.js.
+ * Contains functions for launching the dashboard and hook server, plus enriched context.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const http = require('http');
+const { logHook } = require('../hook-logger');
+
+/**
+ * Attempt to launch the dashboard in a detached background process.
+ * Checks if the port is already in use before spawning.
+ */
+function tryLaunchDashboard(port, _planningDir, projectDir) {
+  const net = require('net');
+  const { spawn } = require('child_process');
+
+  // Quick port probe -- if something is already listening, skip launch
+  const probe = net.createConnection({ port, host: '127.0.0.1' });
+  probe.on('connect', () => {
+    probe.destroy();
+    logHook('progress-tracker', 'SessionStart', 'dashboard-already-running', { port });
+  });
+  probe.on('error', () => {
+    // Port is free -- launch dashboard
+    const cliPath = path.join(__dirname, '..', '..', 'dashboard', 'bin', 'cli.js');
+    if (!fs.existsSync(cliPath)) {
+      logHook('progress-tracker', 'SessionStart', 'dashboard-cli-missing', { cliPath });
+      return;
+    }
+
+    try {
+      const child = spawn(process.execPath, [cliPath, '--dir', projectDir, '--port', String(port)], {
+        detached: true,
+        stdio: 'ignore',
+        cwd: projectDir
+      });
+      child.unref();
+      logHook('progress-tracker', 'SessionStart', 'dashboard-launched', { port, pid: child.pid });
+    } catch (e) {
+      logHook('progress-tracker', 'SessionStart', 'dashboard-launch-error', { error: e.message });
+    }
+  });
+
+  // Don't let the probe keep the process alive
+  probe.unref();
+}
+
+/**
+ * Attempt to launch the hook server in a detached background process.
+ * Checks if the port is already in use before spawning.
+ */
+function tryLaunchHookServer(config, planningDir) {
+  if (config.hook_server && config.hook_server.enabled === false) {
+    return;
+  }
+
+  const port = (config.hook_server && config.hook_server.port) || 19836;
+  const projectRoot = planningDir.replace(/[/\\]\.planning$/, '');
+
+  const net = require('net');
+  const { spawn } = require('child_process');
+
+  // Quick port probe -- if something is already listening, skip launch
+  const probe = net.createConnection({ port, host: '127.0.0.1' });
+  probe.on('connect', () => {
+    probe.destroy();
+    logHook('progress-tracker', 'SessionStart', 'hook-server-already-running', { port });
+  });
+  probe.on('error', () => {
+    // Port is free -- launch hook server
+    const serverPath = path.join(__dirname, '..', 'hook-server.js');
+    if (!fs.existsSync(serverPath)) {
+      logHook('progress-tracker', 'SessionStart', 'hook-server-missing', { serverPath });
+      return;
+    }
+
+    try {
+      let child;
+      if (process.platform === 'win32') {
+        // On Windows, Node's detached: true doesn't escape the parent's Job Object.
+        // Claude Code uses a Job Object with KILL_ON_JOB_CLOSE, so all child
+        // processes die when the session recycles. WMIC process call create
+        // spawns a truly independent process outside any Job Object.
+        const { execSync } = require('child_process');
+        const cmdLine = `"${process.execPath}" "${serverPath}" --port ${port} --dir "${planningDir}"`;
+        try {
+          const wmicOut = execSync(`wmic process call create "${cmdLine.replace(/"/g, '\\"')}"`, {
+            timeout: 5000, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'],
+            windowsHide: true
+          });
+          const pidMatch = wmicOut.match(/ProcessId\s*=\s*(\d+)/);
+          logHook('progress-tracker', 'SessionStart', 'hook-server-launched', {
+            port, pid: pidMatch ? parseInt(pidMatch[1], 10) : null, method: 'wmic'
+          });
+        } catch (wmicErr) {
+          logHook('progress-tracker', 'SessionStart', 'hook-server-launch-error', {
+            error: wmicErr.message, method: 'wmic'
+          });
+        }
+        return; // wmic doesn't return a child handle -- skip unref below
+      } else {
+        child = spawn(process.execPath, [serverPath, '--port', String(port), '--dir', planningDir], {
+          detached: true,
+          stdio: 'ignore',
+          cwd: projectRoot
+        });
+      }
+      child.unref();
+      logHook('progress-tracker', 'SessionStart', 'hook-server-launched', { port, pid: child.pid });
+    } catch (e) {
+      logHook('progress-tracker', 'SessionStart', 'hook-server-launch-error', { error: e.message });
+    }
+  });
+
+  // Don't let the probe keep the process alive
+  probe.unref();
+}
+
+/**
+ * Query the hook server's /context endpoint and return enriched session context.
+ * Returns null if the server is down or any error occurs (fail-open).
+ */
+async function getEnrichedContext(config, _planningDir) {
+  try {
+    if (config && config.hook_server && config.hook_server.enabled === false) {
+      return null;
+    }
+    const port = (config && config.hook_server && config.hook_server.port) || 19836;
+
+    // TCP probe -- check if server is reachable before making HTTP request
+    const reachable = await new Promise(resolve => {
+      const net = require('net');
+      const probe = net.createConnection({ port, host: '127.0.0.1' });
+      probe.setTimeout(500);
+      probe.on('connect', () => { probe.destroy(); resolve(true); });
+      probe.on('error', () => resolve(false));
+      probe.on('timeout', () => { probe.destroy(); resolve(false); });
+    });
+
+    if (!reachable) return null;
+
+    // HTTP GET /context with 500ms timeout
+    const result = await new Promise((resolve, _reject) => {
+      const req = http.get({ hostname: '127.0.0.1', port, path: '/context' }, res => {
+        let data = '';
+        res.setEncoding('utf8');
+        res.on('data', chunk => { data += chunk; });
+        res.on('end', () => {
+          try { resolve(JSON.parse(data)); } catch (_e) { resolve(null); }
+        });
+      });
+      req.on('error', () => resolve(null));
+      req.setTimeout(500, () => { req.destroy(); resolve(null); });
+    });
+
+    return result;
+  } catch (_e) {
+    return null;
+  }
+}
+
+module.exports = {
+  tryLaunchDashboard,
+  tryLaunchHookServer,
+  getEnrichedContext,
+};

package/plugins/pbr/scripts/lib/decision-extraction.js

@@ -0,0 +1,267 @@
+#!/usr/bin/env node
+
+/**
+ * Decision extraction and negative knowledge functions extracted from event-handler.js.
+ *
+ * Extracts architectural decisions from agent output using pattern matching,
+ * records them via the decision journal, and handles negative knowledge
+ * extraction from VERIFICATION.md gaps.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('../hook-logger');
+
+/**
+ * Decision pattern definitions. Each entry has a regex and extraction logic.
+ * Patterns are designed to minimize false positives on common prose.
+ */
+const DECISION_PATTERNS = [
+  {
+    // "Locked Decision: ..." or "DECISION: ..."
+    name: 'explicit',
+    regex: /(?:Locked Decision|DECISION):\s*(.+?)(?:\n|$)/gi,
+    extract(match) {
+      const full = match[1].trim();
+      const rationaleMatch = full.match(/\b(?:because|since|due to)\s+(.+)$/i);
+      const decision = rationaleMatch ? full.slice(0, rationaleMatch.index).trim() : full;
+      const rationale = rationaleMatch ? rationaleMatch[1].trim() : '';
+      return { decision, rationale };
+    }
+  },
+  {
+    // "chose X over Y because Z" — requires "over" to avoid false positives
+    name: 'chose-over',
+    regex: /\bchose\s+(.+?)\s+over\s+(.+?)\s+(?:because|since|due to)\s+(.+?)(?:\.|$)/gi,
+    extract(match) {
+      const decision = `chose ${match[1].trim()} over ${match[2].trim()}`;
+      const rationale = match[3].trim();
+      return { decision, rationale, alternatives: [match[2].trim()] };
+    }
+  },
+  {
+    // "selected X instead of Y because Z" — requires "instead of" to avoid false positives
+    name: 'selected-instead',
+    regex: /\bselected\s+(.+?)\s+instead of\s+(.+?)\s+(?:because|since|due to)\s+(.+?)(?:\.|$)/gi,
+    extract(match) {
+      const decision = `selected ${match[1].trim()} instead of ${match[2].trim()}`;
+      const rationale = match[3].trim();
+      return { decision, rationale, alternatives: [match[2].trim()] };
+    }
+  },
+  {
+    // "Deviation: ..." — deviation justifications
+    name: 'deviation',
+    regex: /Deviation:\s*(.+?)(?:\n|$)/gi,
+    extract(match) {
+      const full = match[1].trim();
+      const rationaleMatch = full.match(/\b(?:because|since|due to)\s+(.+)$/i);
+      const decision = rationaleMatch ? full.slice(0, rationaleMatch.index).trim() : full;
+      const rationale = rationaleMatch ? rationaleMatch[1].trim() : '';
+      return { decision, rationale };
+    }
+  }
+];
+
+/**
+ * Extract decisions from agent output text.
+ * @param {string} agentOutput - Raw text output from an agent
+ * @param {string} agentType - Agent type identifier (e.g. 'executor', 'planner')
+ * @returns {Array<{decision: string, rationale: string, context: string, agent: string, alternatives?: string[]}>}
+ */
+function extractDecisions(agentOutput, agentType) {
+  if (!agentOutput || typeof agentOutput !== 'string') return [];
+
+  const results = [];
+  const lines = agentOutput.split('\n');
+
+  for (const pattern of DECISION_PATTERNS) {
+    // Reset regex lastIndex for each pattern
+    pattern.regex.lastIndex = 0;
+    let match;
+    while ((match = pattern.regex.exec(agentOutput)) !== null) {
+      const extracted = pattern.extract(match);
+      if (!extracted.decision) continue;
+
+      // Truncate decision title to 80 chars
+      const decision = extracted.decision.length > 80
+        ? extracted.decision.slice(0, 80)
+        : extracted.decision;
+
+      // Get surrounding context (2 lines before/after the match)
+      const matchLine = agentOutput.slice(0, match.index).split('\n').length - 1;
+      const contextStart = Math.max(0, matchLine - 2);
+      const contextEnd = Math.min(lines.length, matchLine + 3);
+      const context = lines.slice(contextStart, contextEnd).join('\n');
+
+      results.push({
+        decision,
+        rationale: extracted.rationale || '',
+        context,
+        agent: agentType,
+        alternatives: extracted.alternatives || []
+      });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Handle decision extraction for a planning directory.
+ * Checks config, extracts decisions from output, and records them.
+ * @param {string} planningDir - Path to .planning directory
+ * @param {string} agentOutput - Raw agent output text
+ * @param {string} agentType - Agent type identifier
+ */
+function handleDecisionExtraction(planningDir, agentOutput, agentType) {
+  // Check config for feature toggle
+  const configPath = path.join(planningDir, 'config.json');
+  let config;
+  try {
+    if (!fs.existsSync(configPath)) return;
+    config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  } catch (e) {
+    logHook('event-handler', 'SubagentStop', 'config-read-error', { error: e.message });
+    return;
+  }
+
+  if (!config || !config.features || !config.features.decision_journal) return;
+
+  const decisions = extractDecisions(agentOutput, agentType);
+  if (decisions.length === 0) return;
+
+  // Lazy-load decisions module — path relative to hooks/lib/
+  let recordDecision;
+  try {
+    const decisionsModule = require(path.join(__dirname, '..', '..', '..', '..', 'plan-build-run', 'bin', 'lib', 'decisions.cjs'));
+    recordDecision = decisionsModule.recordDecision;
+  } catch (e) {
+    logHook('event-handler', 'SubagentStop', 'decisions-module-load-error', { error: e.message });
+    return;
+  }
+
+  // Get phase from STATE.md — use inline require to avoid circular deps
+  const { getPhaseFromState } = require('./auto-verify');
+  const stateInfo = getPhaseFromState(planningDir);
+  const phase = stateInfo ? String(stateInfo.phase) : '';
+
+  for (const d of decisions) {
+    try {
+      recordDecision(planningDir, {
+        decision: d.decision,
+        rationale: d.rationale,
+        context: d.context,
+        agent: d.agent,
+        phase,
+        alternatives: d.alternatives || [],
+      });
+    } catch (_e) {
+      // Non-fatal — log and continue
+      try {
+        logHook('event-handler', 'SubagentStop', 'decision-record-error', { error: _e.message });
+      } catch (_logErr) {
+        // Intentional: logHook itself failed, nothing more we can do
+      }
+    }
+  }
+
+  try {
+    logHook('event-handler', 'SubagentStop', 'decisions-extracted', {
+      feature: 'decision_journal',
+      action: 'extract',
+      count: decisions.length,
+      agent: agentType
+    });
+  } catch (e) {
+    logHook('event-handler', 'SubagentStop', 'log-error', { error: e.message });
+  }
+}
+
+/**
+ * Extract negative knowledge entries from VERIFICATION.md gaps.
+ * Parses both section format (### Gap: ...) and table format (| Gap | Files | Evidence |).
+ * @param {string} planningDir - Path to .planning directory
+ * @param {string} phaseDir - Path to the specific phase directory
+ * @param {object} config - Parsed config.json object
+ */
+function extractNegativeKnowledge(planningDir, phaseDir, config) {
+  if (!config || !config.features || !config.features.negative_knowledge) return;
+
+  const verificationPath = path.join(phaseDir, 'VERIFICATION.md');
+  if (!fs.existsSync(verificationPath)) return;
+
+  const content = fs.readFileSync(verificationPath, 'utf8');
+
+  const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!fmMatch) return;
+
+  const fmText = fmMatch[1];
+  const statusMatch = fmText.match(/^status:\s*(.+)$/m);
+  const status = statusMatch ? statusMatch[1].trim() : '';
+
+  const gapsInFm = fmText.match(/^gaps:\s*\n((?:\s+-\s+.+\n?)*)/m);
+  if (!gapsInFm && status !== 'failed') return;
+  if (status !== 'failed' && !gapsInFm) return;
+
+  const body = content.slice(fmMatch[0].length);
+  const bodyNorm = body.replace(/\r\n/g, '\n');
+
+  // Parse gaps — section format: ### Gap: {title}\nFiles: {files}\n{evidence}
+  const sectionGaps = [];
+  const sectionRegex = /###\s*Gap:\s*(.+)\nFiles:\s*(.+)\n([\s\S]*?)(?=\n###|\n##|\s*$)/g;
+  let match;
+  while ((match = sectionRegex.exec(bodyNorm)) !== null) {
+    sectionGaps.push({ title: match[1].trim(), files: match[2].trim().split(/,\s*/), evidence: match[3].trim() });
+  }
+
+  // Parse gaps — table format: | Gap | Files | Evidence |
+  const tableGaps = [];
+  const tableRows = bodyNorm.split('\n').filter(line => line.includes('|') && !line.includes('---'));
+  if (tableRows.length >= 2) {
+    const headerRow = tableRows[0];
+    const isGapTable = /gap/i.test(headerRow) && /files/i.test(headerRow);
+    if (isGapTable) {
+      for (let i = 1; i < tableRows.length; i++) {
+        const cols = tableRows[i].split('|').map(c => c.trim()).filter(Boolean);
+        if (cols.length >= 3) {
+          tableGaps.push({ title: cols[0], files: cols[1].split(/,\s*/), evidence: cols[2] });
+        }
+      }
+    }
+  }
+
+  const gaps = sectionGaps.length > 0 ? sectionGaps : tableGaps;
+  if (gaps.length === 0) return;
+
+  let recordFailure;
+  try {
+    const nkModule = require(path.join(__dirname, '..', '..', '..', '..', 'plan-build-run', 'bin', 'lib', 'negative-knowledge.cjs'));
+    recordFailure = nkModule.recordFailure;
+  } catch (e) {
+    logHook('event-handler', 'SubagentStop', 'negative-knowledge-module-load-error', { error: e.message });
+    return;
+  }
+
+  const phaseName = path.basename(phaseDir);
+  const phaseMatch = phaseName.match(/^(\d+)/);
+  const phase = phaseMatch ? phaseMatch[1] : '';
+
+  for (const gap of gaps) {
+    try {
+      recordFailure(planningDir, { title: gap.title, category: 'verification-gap', filesInvolved: gap.files, whatTried: gap.title, whyFailed: gap.evidence || gap.title, phase });
+    } catch (e) {
+      logHook('event-handler', 'SubagentStop', 'negative-knowledge-record-error', { error: e.message });
+    }
+  }
+
+  try {
+    logHook('event-handler', 'SubagentStop', 'negative-knowledge-extracted', { feature: 'negative_knowledge', action: 'extract', count: gaps.length, phase });
+  } catch (e) {
+    logHook('event-handler', 'SubagentStop', 'log-error', { error: e.message });
+  }
+}
+
+module.exports = { DECISION_PATTERNS, extractDecisions, handleDecisionExtraction, extractNegativeKnowledge };

package/plugins/pbr/scripts/lib/dependency-break.js

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+
+/**
+ * Dependency break detection module.
+ *
+ * Detects when upstream SUMMARY.md changes invalidate downstream plans
+ * by comparing MD5 fingerprints stored in plan frontmatter against
+ * the current SUMMARY.md content.
+ *
+ * Pure function — no side effects, no file writes.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+/**
+ * Compute an 8-char MD5 fingerprint of a file's content.
+ * @param {string} filePath - Absolute path to file
+ * @returns {string|null} 8-char hex fingerprint, or null if file missing
+ */
+function computeFingerprint(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    return crypto.createHash('md5').update(content).digest('hex').slice(0, 8);
+  } catch (_e) {
+    return null;
+  }
+}
+
+/**
+ * Parse YAML frontmatter from a markdown file.
+ * Extracts dependency_fingerprints and plan fields.
+ * @param {string} content - File content
+ * @returns {{ plan: string, dependency_fingerprints: Object<string, string> }}
+ */
+function parsePlanFrontmatter(content) {
+  const result = { plan: '', dependency_fingerprints: {} };
+
+  const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!fmMatch) return result;
+
+  const fm = fmMatch[1];
+
+  // Extract plan ID
+  const planMatch = fm.match(/plan:\s*"?([^"\n]+)"?/);
+  if (planMatch) result.plan = planMatch[1].trim();
+
+  // Extract dependency_fingerprints — stored as JSON object in YAML
+  const fpMatch = fm.match(/dependency_fingerprints:\s*(\{[^}]+\})/);
+  if (fpMatch) {
+    try {
+      // Parse JSON-style object: { "3": "abc123" }
+      const parsed = JSON.parse(fpMatch[1].replace(/'/g, '"'));
+      result.dependency_fingerprints = parsed;
+    } catch (_e) {
+      // Malformed — return empty
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Check for dependency breaks when an upstream phase's SUMMARY.md changes.
+ *
+ * Scans all downstream plans for dependency_fingerprints that reference
+ * the changed phase, and returns breaks where fingerprints don't match.
+ *
+ * @param {string} planningDir - Absolute path to .planning/ directory
+ * @param {number} changedPhaseNum - Phase number whose SUMMARY.md changed
+ * @returns {Array<{ plan: string, dependsOn: number, expected: string, actual: string }>}
+ */
+function checkDependencyBreaks(planningDir, changedPhaseNum) {
+  const breaks = [];
+
+  // Find the changed phase's SUMMARY.md
+  const phasesDir = path.join(planningDir, 'phases');
+  if (!fs.existsSync(phasesDir)) return breaks;
+
+  let summaryPath = null;
+  const paddedNum = String(changedPhaseNum).padStart(2, '0');
+
+  try {
+    const phaseDirs = fs.readdirSync(phasesDir);
+    for (const dir of phaseDirs) {
+      if (dir.startsWith(paddedNum + '-')) {
+        const candidate = path.join(phasesDir, dir, 'SUMMARY.md');
+        if (fs.existsSync(candidate)) {
+          summaryPath = candidate;
+          break;
+        }
+      }
+    }
+  } catch (_e) {
+    return breaks;
+  }
+
+  // No SUMMARY.md for the changed phase — nothing to fingerprint
+  if (!summaryPath) return breaks;
+
+  const actualFingerprint = computeFingerprint(summaryPath);
+  if (!actualFingerprint) return breaks;
+
+  // Scan all phase directories for PLAN*.md files with dependency_fingerprints
+  try {
+    const phaseDirs = fs.readdirSync(phasesDir);
+    for (const dir of phaseDirs) {
+      const phaseDir = path.join(phasesDir, dir);
+      const stat = fs.statSync(phaseDir);
+      if (!stat.isDirectory()) continue;
+
+      const files = fs.readdirSync(phaseDir);
+      for (const file of files) {
+        if (!file.match(/^PLAN.*\.md$/i)) continue;
+
+        const planPath = path.join(phaseDir, file);
+        try {
+          const content = fs.readFileSync(planPath, 'utf8');
+          const parsed = parsePlanFrontmatter(content);
+
+          // Check if this plan has a fingerprint for the changed phase
+          const phaseKey = String(changedPhaseNum);
+          if (parsed.dependency_fingerprints[phaseKey]) {
+            const expectedFp = parsed.dependency_fingerprints[phaseKey];
+            if (expectedFp !== actualFingerprint) {
+              breaks.push({
+                plan: parsed.plan || file.replace('.md', ''),
+                dependsOn: changedPhaseNum,
+                expected: expectedFp,
+                actual: actualFingerprint
+              });
+            }
+          }
+        } catch (_e) {
+          // Skip unreadable plans
+        }
+      }
+    }
+  } catch (_e) {
+    // Return whatever breaks we found so far
+  }
+
+  return breaks;
+}
+
+module.exports = { checkDependencyBreaks, computeFingerprint };