@sienklogic/plan-build-run 2.19.0 → 2.19.1

package/plugins/pbr/dist/event-handler.js

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+
+/**
+ * SubagentStop event handler for auto-verification triggering.
+ *
+ * Detects executor agent completion and conditionally queues verification
+ * by writing a .auto-verify signal file. Respects depth profile and
+ * config.features.goal_verification setting.
+ *
+ * Non-blocking — exits 0 always.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+const { logEvent } = require('./event-logger');
+const { incrementTracker } = require('./session-tracker');
+const { shouldAutoVerify, getPhaseFromState, writeAutoVerifySignal, isTrustTrackingEnabled } = require('./lib/auto-verify');
+const { handleDecisionExtraction, extractDecisions } = require('./lib/decision-extraction');
+
+function readStdin() {
+  try {
+    const input = fs.readFileSync(0, 'utf8').trim();
+    if (input) return JSON.parse(input);
+  } catch (_e) {
+    // Intentional silence: stdin may be empty or non-JSON, this is expected
+  }
+  return {};
+}
+
+/**
+ * Check if the stdin data represents an executor agent completion.
+ * @param {object} data - Parsed stdin JSON from SubagentStop event
+ * @returns {boolean}
+ */
+function isExecutorAgent(data) {
+  const agentType = data.agent_type || data.subagent_type || null;
+  return agentType === 'pbr:executor';
+}
+
+/**
+ * Check if the stdin data represents a verifier agent completion.
+ * @param {object} data - Parsed stdin JSON from SubagentStop event
+ * @returns {boolean}
+ */
+function isVerifierAgent(data) {
+  const agentType = data.agent_type || data.subagent_type || null;
+  return agentType === 'pbr:verifier';
+}
+
+/**
+ * Build verify hint from executor output for downstream context.
+ * @param {string} lastMsg - last_assistant_message from agent output
+ * @returns {string}
+ */
+function buildVerifyHint(lastMsg) {
+  if (!lastMsg) return '';
+  const lowerMsg = lastMsg.toLowerCase();
+  if (lowerMsg.includes('error') || lowerMsg.includes('failed') || lowerMsg.includes('warning')) {
+    return ' Note: executor output mentions errors/warnings — verification should pay close attention.';
+  }
+  return '';
+}
+
+/**
+ * Core logic for handling executor completion and auto-verify queueing.
+ * Shared between main() (stdin mode) and handleHttp (server mode).
+ * @param {object} data - Parsed event data
+ * @param {string} planningDir - Path to .planning directory
+ * @returns {{ additionalContext: string }|null}
+ */
+function processExecutorCompletion(data, planningDir) {
+  const agentType = data.agent_type || data.subagent_type || '';
+
+  logHook('event-handler', 'SubagentStop', 'executor-complete', { agent_type: agentType });
+  logEvent('workflow', 'executor-complete', { agent_type: agentType });
+
+  if (!planningDir || !fs.existsSync(planningDir)) return null;
+
+  const stateInfo = getPhaseFromState(planningDir);
+  if (!stateInfo || stateInfo.status !== 'building') {
+    logHook('event-handler', 'SubagentStop', 'skip-verify', {
+      reason: stateInfo ? `status=${stateInfo.status}` : 'no-state'
+    });
+    return null;
+  }
+
+  // Increment session phase counter (before auto-verify gate)
+  try {
+    incrementTracker(planningDir);
+  } catch (e) {
+    logHook('event-handler', 'SubagentStop', 'increment-tracker-error', { error: e.message });
+  }
+
+  if (!shouldAutoVerify(planningDir)) {
+    logHook('event-handler', 'SubagentStop', 'skip-verify', { reason: 'config/depth' });
+    return null;
+  }
+
+  writeAutoVerifySignal(planningDir, stateInfo.phase);
+
+  const verifyHint = buildVerifyHint(data.last_assistant_message || '');
+  return {
+    additionalContext: `Executor complete. Auto-verification queued for Phase ${stateInfo.phase}.${verifyHint}`
+  };
+}
+
+/**
+ * Handle verifier agent completion — log trust-update-queued.
+ * @param {object} data - Parsed event data
+ * @param {string|null} planningDir - Path to .planning directory
+ */
+function processVerifierCompletion(data, planningDir) {
+  const agentType = data.agent_type || data.subagent_type;
+  logHook('event-handler', 'SubagentStop', 'verifier-complete', { agent_type: agentType });
+  logEvent('workflow', 'verifier-complete', { agent_type: agentType });
+
+  if (planningDir && fs.existsSync(planningDir) && isTrustTrackingEnabled(planningDir)) {
+    logEvent(planningDir, 'trust-update-queued', { agent: 'pbr:verifier' });
+  }
+}
+
+/**
+ * Handle decision extraction for any agent type.
+ * @param {object} data - Parsed event data
+ * @param {string} planningDir - Path to .planning directory
+ */
+function processDecisionExtraction(data, planningDir) {
+  const agentType = data.agent_type || data.subagent_type || '';
+  if (!agentType || !planningDir || !fs.existsSync(planningDir)) return;
+
+  const agentOutput = data.output || data.stdout || data.last_assistant_message || '';
+  try {
+    handleDecisionExtraction(planningDir, agentOutput, agentType.replace('pbr:', ''));
+  } catch (e) {
+    logHook('event-handler', 'SubagentStop', 'decision-extraction-error', { error: e.message });
+  }
+}
+
+function main() {
+  const data = readStdin();
+  const planningDir = path.join(process.cwd(), '.planning');
+
+  // Decision extraction runs for ALL agent types (not just executor)
+  processDecisionExtraction(data, planningDir);
+
+  // Handle verifier agent completions — log trust-update-queued
+  if (isVerifierAgent(data)) {
+    processVerifierCompletion(data, planningDir);
+    process.exit(0);
+  }
+
+  // Only handle executor agent completions for auto-verify
+  if (!isExecutorAgent(data)) {
+    process.exit(0);
+  }
+
+  const result = processExecutorCompletion(data, planningDir);
+  if (result) {
+    process.stdout.write(JSON.stringify(result));
+  }
+  process.exit(0);
+}
+
+/**
+ * HTTP handler for hook-server.js integration.
+ * Called as handleHttp(reqBody, cache) where reqBody = { event, tool, data, planningDir, ... }.
+ * Must NOT call process.exit().
+ * @param {{ data: object, planningDir: string }} reqBody
+ * @returns {{ additionalContext: string }|null}
+ */
+function handleHttp(reqBody) {
+  const data = reqBody.data || {};
+  const planningDir = reqBody.planningDir;
+
+  // Decision extraction runs for ALL agent types
+  processDecisionExtraction(data, planningDir);
+
+  // Handle verifier completions — log trust-update-queued
+  if (isVerifierAgent(data)) {
+    processVerifierCompletion(data, planningDir);
+    return null;
+  }
+
+  if (!isExecutorAgent(data)) return null;
+
+  return processExecutorCompletion(data, planningDir);
+}
+
+module.exports = {
+  isExecutorAgent,
+  isVerifierAgent,
+  shouldAutoVerify,
+  getPhaseFromState,
+  handleHttp,
+  extractDecisions,
+  handleDecisionExtraction,
+  // New exports for internal use
+  writeAutoVerifySignal,
+  isTrustTrackingEnabled,
+};
+if (require.main === module || process.argv[1] === __filename) { main(); }

package/plugins/pbr/dist/event-logger.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+
+/**
+ * Workflow event logger for Plan-Build-Run observability.
+ *
+ * Usage as module:
+ *   const { logEvent } = require('./event-logger');
+ *   logEvent('workflow', 'phase-start', { phase: 3, name: 'API' });
+ *
+ * Usage as CLI:
+ *   node event-logger.js <category> <event> [JSON-details]
+ *
+ * Log files: .planning/logs/events-YYYY-MM-DD.jsonl (one file per day, no size cap)
+ * Format: One JSON line per entry (JSONL), append-only
+ * Retention: Old daily files are cleaned up after MAX_DAYS days by session-cleanup.js
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const MAX_DAYS = 30;
+
+/** Return today's date string as YYYY-MM-DD (local time). */
+function getTodayDate() {
+  const d = new Date();
+  const yyyy = d.getFullYear();
+  const mm = String(d.getMonth() + 1).padStart(2, '0');
+  const dd = String(d.getDate()).padStart(2, '0');
+  return `${yyyy}-${mm}-${dd}`;
+}
+
+/** Return the log filename for a given date (defaults to today). */
+function getLogFilename(date) {
+  return `events-${date || getTodayDate()}.jsonl`;
+}
+
+/** Return the full path to the events log for a given date (defaults to today). */
+function getLogPath(date) {
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+  const logsDir = path.join(cwd, '.planning', 'logs');
+  // Auto-create .planning/logs/ if needed.
+  if (!fs.existsSync(logsDir)) {
+    fs.mkdirSync(logsDir, { recursive: true });
+  }
+
+  // One-time migration: rename legacy events.jsonl to yesterday's dated file.
+  const legacyPath = path.join(logsDir, 'events.jsonl');
+  if (fs.existsSync(legacyPath)) {
+    const yesterday = new Date(Date.now() - 86400000);
+    const yDate = `${yesterday.getFullYear()}-${String(yesterday.getMonth() + 1).padStart(2, '0')}-${String(yesterday.getDate()).padStart(2, '0')}`;
+    const migratedPath = path.join(logsDir, `events-${yDate}.jsonl`);
+    if (!fs.existsSync(migratedPath)) {
+      try { fs.renameSync(legacyPath, migratedPath); } catch (_e) { /* best-effort */ }
+    } else {
+      try { fs.unlinkSync(legacyPath); } catch (_e) { /* best-effort */ }
+    }
+  }
+
+  return path.join(logsDir, getLogFilename(date));
+}
+
+function logEvent(category, event, details = {}) {
+  const logPath = getLogPath();
+  if (!logPath) return;
+
+  const entry = {
+    ts: new Date().toISOString(),
+    cat: category,
+    event,
+    ...details
+  };
+
+  try {
+    fs.appendFileSync(logPath, JSON.stringify(entry) + '\n', 'utf8');
+  } catch (_e) {
+    // Best-effort logging — never fail the caller
+  }
+}
+
+/**
+ * Delete events-*.jsonl files older than MAX_DAYS days.
+ * Called by session-cleanup.js at session end.
+ */
+function cleanOldEventLogs(logsDir) {
+  try {
+    const cutoff = Date.now() - MAX_DAYS * 86400000;
+    const files = fs.readdirSync(logsDir);
+    for (const file of files) {
+      if (!/^events-\d{4}-\d{2}-\d{2}\.jsonl$/.test(file)) continue;
+      const filePath = path.join(logsDir, file);
+      const stat = fs.statSync(filePath);
+      if (stat.mtimeMs < cutoff) fs.unlinkSync(filePath);
+    }
+  } catch (_e) {
+    // Best-effort cleanup — never fail the caller
+  }
+}
+
+// CLI mode
+function main() {
+  const args = process.argv.slice(2);
+  const category = args[0];
+  const event = args[1];
+  let details = {};
+
+  if (args[2]) {
+    try {
+      details = JSON.parse(args[2]);
+    } catch (_e) {
+      details = { raw: args[2] };
+    }
+  }
+
+  if (!category || !event) {
+    process.stdout.write(JSON.stringify({ error: 'Usage: event-logger.js <category> <event> [JSON-details]' }));
+    process.exit(1);
+  }
+
+  logEvent(category, event, details);
+  process.stdout.write(JSON.stringify({ logged: true, category, event }));
+  process.exit(0);
+}
+
+if (require.main === module || process.argv[1] === __filename) { main(); }
+module.exports = { logEvent, getLogPath, getLogFilename, cleanOldEventLogs };

package/plugins/pbr/dist/feedback-loop.js

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+
+'use strict';
+
+/**
+ * Agent Feedback Loop — Reflexion-inspired verification feedback extraction.
+ *
+ * Reads VERIFICATION.md from a phase directory, extracts actionable gap
+ * descriptions, and formats them into a compact prompt for executor agents
+ * on retry attempts. This closes the loop between verification and execution.
+ *
+ * Exports:
+ *   extractFeedback(phaseDir)       — Parse VERIFICATION.md gaps
+ *   formatFeedbackPrompt(feedback)  — Format feedback as markdown (<500 tokens)
+ *   isEnabled(planningDir)          — Check config toggle
+ *
+ * Used by: check-subagent-output.js (PostToolUse on Task)
+ * Config: features.agent_feedback_loop (default: true)
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Parse YAML-ish frontmatter from markdown content.
+ * Lightweight parser — no dependency on pbr-tools to avoid circular deps.
+ * @param {string} content - Full file content
+ * @returns {{ frontmatter: object, body: string }}
+ */
+function parseFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return { frontmatter: {}, body: content };
+
+  const fm = {};
+  const lines = match[1].split(/\r?\n/);
+  for (const line of lines) {
+    const kvMatch = line.match(/^(\w[\w_]*):\s*(.+)/);
+    if (kvMatch) {
+      const key = kvMatch[1];
+      let val = kvMatch[2].trim();
+      // Parse numbers
+      if (/^\d+$/.test(val)) val = parseInt(val, 10);
+      // Strip quotes
+      if (typeof val === 'string' && val.startsWith('"') && val.endsWith('"')) {
+        val = val.slice(1, -1);
+      }
+      fm[key] = val;
+    }
+  }
+
+  const body = content.slice(match[0].length).trim();
+  return { frontmatter: fm, body };
+}
+
+/**
+ * Extract actionable feedback from VERIFICATION.md in a phase directory.
+ *
+ * @param {string} phaseDir - Absolute path to the phase directory
+ * @returns {{ status: string, attempt: number, pass_rate: number, gaps: Array<{ name: string, category: string, evidence: string, suggested_fix: string }> }|null}
+ */
+function extractFeedback(phaseDir) {
+  const verPath = path.join(phaseDir, 'VERIFICATION.md');
+  if (!fs.existsSync(verPath)) return null;
+
+  let content;
+  try {
+    content = fs.readFileSync(verPath, 'utf8');
+  } catch (_e) {
+    return null;
+  }
+
+  const { frontmatter, body } = parseFrontmatter(content);
+
+  const status = frontmatter.status;
+  if (!status) return null;
+
+  // No feedback needed if verification passed
+  if (status === 'passed' || status === 'all_passed') return null;
+
+  const attempt = typeof frontmatter.attempt === 'number' ? frontmatter.attempt : 1;
+  const passed = typeof frontmatter.must_haves_passed === 'number' ? frontmatter.must_haves_passed : 0;
+  const total = typeof frontmatter.must_haves_total === 'number' ? frontmatter.must_haves_total : 1;
+  const pass_rate = total > 0 ? passed / total : 0;
+
+  // Parse gap sections from body
+  const gaps = [];
+  const gapPattern = /### Gap:\s*(.+)/g;
+  let gapMatch;
+  const gapStarts = [];
+
+  while ((gapMatch = gapPattern.exec(body)) !== null) {
+    gapStarts.push({ name: gapMatch[1].trim(), index: gapMatch.index });
+  }
+
+  for (let i = 0; i < gapStarts.length; i++) {
+    const start = gapStarts[i].index;
+    const end = i + 1 < gapStarts.length ? gapStarts[i + 1].index : body.length;
+    const section = body.slice(start, end);
+
+    const categoryMatch = section.match(/\*\*Category:\*\*\s*(.+)/);
+    const evidenceMatch = section.match(/\*\*Evidence:\*\*\s*(.+)/);
+    const fixMatch = section.match(/\*\*Suggested Fix:\*\*\s*(.+)/);
+
+    gaps.push({
+      name: gapStarts[i].name,
+      category: categoryMatch ? categoryMatch[1].trim() : 'unknown',
+      evidence: evidenceMatch ? evidenceMatch[1].trim() : '',
+      suggested_fix: fixMatch ? fixMatch[1].trim() : ''
+    });
+  }
+
+  // Log feedback extraction for audit trail (REQ-XC-007)
+  try {
+    const { logEvent } = require('./event-logger');
+    logEvent('feedback_loop', 'feedback_extracted', {
+      phaseDir: path.basename(phaseDir),
+      status,
+      attempt,
+      pass_rate: Math.round(pass_rate * 100),
+      gap_count: gaps.length
+    });
+  } catch (_e) {
+    // Best-effort logging — never fail the caller
+  }
+
+  return { status, attempt, pass_rate, gaps };
+}
+
+/**
+ * Format feedback into a compact markdown prompt for executor agents.
+ * Output is kept under 500 tokens (~2000 chars) to preserve agent context budget.
+ *
+ * @param {{ status: string, attempt: number, pass_rate: number, gaps: Array }|null} feedback
+ * @returns {string}
+ */
+function formatFeedbackPrompt(feedback) {
+  if (!feedback) return '';
+
+  const lines = [];
+  lines.push(`## Previous Verification Feedback (Attempt ${feedback.attempt})`);
+  lines.push('');
+  lines.push(`Pass rate: ${Math.round(feedback.pass_rate * 100)}%`);
+  lines.push('');
+
+  for (const gap of feedback.gaps) {
+    lines.push(`### ${gap.name}`);
+    lines.push(`**Category:** ${gap.category}`);
+    if (gap.evidence) lines.push(`**Evidence:** ${gap.evidence}`);
+    if (gap.suggested_fix) lines.push(`**Fix:** ${gap.suggested_fix}`);
+    lines.push('');
+  }
+
+  return lines.join('\n').trim();
+}
+
+/**
+ * Check if the agent feedback loop is enabled in config.
+ *
+ * @param {string} planningDir - Path to .planning directory
+ * @returns {boolean}
+ */
+function isEnabled(planningDir) {
+  try {
+    const configPath = path.join(planningDir, 'config.json');
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    return config?.features?.agent_feedback_loop !== false;
+  } catch (_e) {
+    return true; // Default enabled
+  }
+}
+
+module.exports = { extractFeedback, formatFeedbackPrompt, isEnabled };