@sienklogic/plan-build-run 2.21.1 → 2.21.2

package/plugins/pbr/scripts/lib/audit.js

@@ -0,0 +1,65 @@
+/**
+ * Audit utilities for Plan-Build-Run.
+ *
+ * Provides functions to query hooks.jsonl logs for plan-checker
+ * and other audit-relevant events.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { resolveProjectRoot } = require('./resolve-root');
+
+/**
+ * Query plan-checker results from hooks.jsonl log files.
+ *
+ * @param {object} options
+ * @param {number} [options.last=30] - Number of days to look back
+ * @returns {{ entries: Array, total: number, passed: number, failed: number, date_range: { from: string, to: string } }}
+ */
+function auditPlanChecks(options = {}) {
+  const cwd = resolveProjectRoot();
+  const logsDir = path.join(cwd, '.planning', 'logs');
+  if (!fs.existsSync(logsDir)) return { entries: [], total: 0, passed: 0, failed: 0, date_range: { from: '', to: '' } };
+
+  const files = fs.readdirSync(logsDir)
+    .filter(f => /^hooks-\d{4}-\d{2}-\d{2}\.jsonl$/.test(f))
+    .sort();
+
+  // Filter to last N days
+  const lastDays = options.last || 30;
+  const cutoff = new Date(Date.now() - lastDays * 86400000).toISOString().slice(0, 10);
+  const relevantFiles = files.filter(f => {
+    const dateStr = f.replace('hooks-', '').replace('.jsonl', '');
+    return dateStr >= cutoff;
+  });
+
+  const entries = [];
+  for (const file of relevantFiles) {
+    const filePath = path.join(logsDir, file);
+    const lines = fs.readFileSync(filePath, 'utf8').split('\n').filter(Boolean);
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line);
+        if (entry.hook === 'plan-checker' && entry.action === 'validate') {
+          entries.push({
+            timestamp: entry.ts,
+            phase: entry.phase,
+            status: entry.status,
+            dimensions: entry.dimensions,
+            blockers: entry.blockers
+          });
+        }
+      } catch (_e) { /* skip malformed lines */ }
+    }
+  }
+
+  return {
+    entries,
+    total: entries.length,
+    passed: entries.filter(e => e.status === 'passed').length,
+    failed: entries.filter(e => e.status === 'issues_found').length,
+    date_range: { from: cutoff, to: new Date().toISOString().slice(0, 10) }
+  };
+}
+
+module.exports = { auditPlanChecks };

package/plugins/pbr/scripts/lib/auto-cleanup.js

@@ -0,0 +1,221 @@
+'use strict';
+
+/**
+ * lib/auto-cleanup.js — Auto-cleanup for completed phases.
+ *
+ * Matches pending todos and notes against phase completion context,
+ * then closes todos (move to done/) or archives notes (add frontmatter flag).
+ * Requires 2+ signal matches before taking action.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { todoList, todoDone } = require('./todo');
+const { parseYamlFrontmatter, atomicWrite } = require('./core');
+
+// Common stop words excluded from keyword matching
+const STOP_WORDS = new Set([
+  'a', 'an', 'the', 'to', 'in', 'on', 'for', 'of', 'and', 'or',
+  'is', 'it', 'with', 'by', 'at', 'from', 'as', 'be', 'was', 'are',
+  'has', 'had', 'have', 'this', 'that', 'not', 'but', 'if', 'do',
+  'no', 'so', 'up', 'out', 'can', 'will', 'all', 'its', 'add', 'use'
+]);
+
+/**
+ * Tokenize a string into lowercase non-stop-words.
+ * @param {string} text
+ * @returns {Set<string>}
+ */
+function tokenize(text) {
+  if (!text) return new Set();
+  const words = text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, ' ')
+    .split(/[\s-]+/)
+    .filter(w => w.length > 2 && !STOP_WORDS.has(w));
+  return new Set(words);
+}
+
+/**
+ * Score how well an item matches the phase completion context.
+ *
+ * @param {{ title: string, body: string }} item - Todo or note content
+ * @param {{ phaseName: string, phaseNum: number|string, keyFiles: string[], commitMessages: string[], summaryDescriptions: string[] }} context
+ * @returns {{ score: number, signals: string[] }}
+ */
+function matchScore(item, context) {
+  const signals = [];
+  const title = (item.title || '').toLowerCase();
+  const body = (item.body || '').toLowerCase();
+  const combined = title + ' ' + body;
+
+  // Signal A: Title keyword match (2+ shared non-stop-words with phaseName)
+  const titleTokens = tokenize(item.title);
+  const phaseTokens = tokenize(context.phaseName);
+  let sharedCount = 0;
+  for (const word of titleTokens) {
+    if (phaseTokens.has(word)) sharedCount++;
+  }
+  if (sharedCount >= 2) {
+    signals.push('title-keyword');
+  }
+
+  // Signal B: File path match
+  const keyFiles = context.keyFiles || [];
+  for (const filePath of keyFiles) {
+    if (filePath && combined.includes(filePath.toLowerCase())) {
+      signals.push('file-path');
+      break;
+    }
+  }
+
+  // Signal C: Commit message match
+  const commitMessages = context.commitMessages || [];
+  for (const msg of commitMessages) {
+    if (msg && msg.length > 5 && combined.includes(msg.toLowerCase())) {
+      signals.push('commit-message');
+      break;
+    }
+  }
+
+  // Signal D: Summary description match
+  const summaryDescriptions = context.summaryDescriptions || [];
+  for (const desc of summaryDescriptions) {
+    if (desc && desc.length > 5 && combined.includes(desc.toLowerCase())) {
+      signals.push('summary-description');
+      break;
+    }
+  }
+
+  return { score: signals.length, signals };
+}
+
+/**
+ * Auto-close pending todos that match the phase completion context.
+ * Requires 2+ signals before closing.
+ *
+ * @param {string} planningDir - Path to .planning/
+ * @param {{ phaseName: string, phaseNum: number|string, keyFiles: string[], commitMessages: string[], summaryDescriptions: string[] }} context
+ * @returns {{ closed: object[], partial: object[], skipped: number }}
+ */
+function autoCloseTodos(planningDir, context) {
+  const { todos } = todoList(planningDir, { status: 'pending' });
+  const closed = [];
+  const partial = [];
+  let skipped = 0;
+
+  for (const todo of todos) {
+    const result = matchScore(
+      { title: todo.title, body: todo.body },
+      context
+    );
+
+    if (result.score >= 2) {
+      const doneResult = todoDone(planningDir, todo.number);
+      if (doneResult.success) {
+        closed.push({
+          number: todo.number,
+          title: todo.title,
+          signals: result.signals,
+          score: result.score
+        });
+      } else {
+        // If todoDone failed, treat as partial
+        partial.push({
+          number: todo.number,
+          title: todo.title,
+          signals: result.signals,
+          score: result.score,
+          error: doneResult.error
+        });
+      }
+    } else if (result.score === 1) {
+      partial.push({
+        number: todo.number,
+        title: todo.title,
+        signals: result.signals,
+        score: result.score
+      });
+    } else {
+      skipped++;
+    }
+  }
+
+  return { closed, partial, skipped };
+}
+
+/**
+ * Auto-archive notes that match the phase completion context.
+ * Adds archived: true to frontmatter. Does NOT move files.
+ * Requires 2+ signals before archiving.
+ *
+ * @param {string} planningDir - Path to .planning/
+ * @param {{ phaseName: string, phaseNum: number|string, keyFiles: string[], commitMessages: string[], summaryDescriptions: string[] }} context
+ * @returns {{ archived: object[], partial: object[], skipped: number }}
+ */
+function autoArchiveNotes(planningDir, context) {
+  const notesDir = path.join(planningDir, 'notes');
+  const archived = [];
+  const partial = [];
+  let skipped = 0;
+
+  if (!fs.existsSync(notesDir)) {
+    return { archived, partial, skipped };
+  }
+
+  const files = fs.readdirSync(notesDir).filter(f => f.endsWith('.md'));
+
+  for (const filename of files) {
+    const filePath = path.join(notesDir, filename);
+    const content = fs.readFileSync(filePath, 'utf8');
+    const fm = parseYamlFrontmatter(content);
+
+    // Skip already-archived notes
+    if (fm.archived === true || fm.archived === 'true') {
+      skipped++;
+      continue;
+    }
+
+    const itemTitle = (fm.date ? fm.date + ' ' : '') + filename.replace(/\.md$/, '');
+    const result = matchScore(
+      { title: itemTitle, body: content },
+      context
+    );
+
+    if (result.score >= 2) {
+      // Add archived fields to frontmatter
+      const archiveFields = `archived: true\narchived_reason: "Addressed by Phase ${context.phaseNum}"`;
+      let updatedContent;
+
+      // Insert before closing --- of frontmatter
+      const fmMatch = content.match(/^(---\s*\r?\n[\s\S]*?\r?\n)(---)/);
+      if (fmMatch) {
+        updatedContent = fmMatch[1] + archiveFields + '\n' + fmMatch[2] + content.slice(fmMatch[0].length);
+      } else {
+        // No frontmatter — add one
+        updatedContent = `---\n${archiveFields}\n---\n${content}`;
+      }
+
+      const writeResult = atomicWrite(filePath, updatedContent);
+      if (writeResult.success) {
+        archived.push({
+          filename,
+          signals: result.signals,
+          score: result.score
+        });
+      }
+    } else if (result.score === 1) {
+      partial.push({
+        filename,
+        signals: result.signals,
+        score: result.score
+      });
+    } else {
+      skipped++;
+    }
+  }
+
+  return { archived, partial, skipped };
+}
+
+module.exports = { matchScore, autoCloseTodos, autoArchiveNotes };

package/plugins/pbr/scripts/lib/auto-verify.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+
+/**
+ * Auto-verification helper functions extracted from event-handler.js.
+ *
+ * Provides config-based checks for whether auto-verification should run,
+ * STATE.md phase parsing, signal file writing, and trust tracking config.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('../hook-logger');
+
+/**
+ * Determine whether auto-verification should run based on config.
+ * @param {string} planningDir - Path to .planning directory
+ * @returns {boolean}
+ */
+function shouldAutoVerify(planningDir) {
+  const configPath = path.join(planningDir, 'config.json');
+  let config;
+  try {
+    if (!fs.existsSync(configPath)) return false;
+    config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  } catch (e) {
+    logHook('event-handler', 'SubagentStop', 'config-read-error', { error: e.message });
+    return false;
+  }
+  if (config === null) return false;
+
+  // Check explicit goal_verification toggle
+  if (config.features && config.features.goal_verification === false) return false;
+
+  // Check depth profile
+  const depth = (config.depth || 'standard').toLowerCase();
+  if (depth === 'quick') return false;
+
+  // "standard", "comprehensive", and any other depth default to true
+  return true;
+}
+
+/**
+ * Parse current phase info from STATE.md.
+ * @param {string} planningDir - Path to .planning directory
+ * @returns {{ phase: number, total: number, status: string } | null}
+ */
+function getPhaseFromState(planningDir) {
+  const statePath = path.join(planningDir, 'STATE.md');
+  try {
+    if (!fs.existsSync(statePath)) return null;
+    const content = fs.readFileSync(statePath, 'utf8');
+
+    const phaseMatch = content.match(/Phase:\s*(\d+)\s+of\s+(\d+)/);
+    if (!phaseMatch) return null;
+
+    const statusMatch = content.match(/\*{0,2}(?:Phase\s+)?Status\*{0,2}:\s*["']?(\w+)["']?/i);
+    const status = statusMatch ? statusMatch[1] : null;
+
+    return {
+      phase: parseInt(phaseMatch[1], 10),
+      total: parseInt(phaseMatch[2], 10),
+      status: status
+    };
+  } catch (e) {
+    logHook('event-handler', 'SubagentStop', 'state-read-error', { error: e.message });
+    return null;
+  }
+}
+
+/**
+ * Write signal file for orchestrator to pick up and spawn verifier.
+ * @param {string} planningDir - Path to .planning directory
+ * @param {number} phaseNumber - Current phase number
+ * @param {object} [options] - Optional round metadata
+ * @param {number} [options.round=1] - Current QA round number
+ * @param {number} [options.total_rounds=1] - Total QA rounds configured
+ */
+function writeAutoVerifySignal(planningDir, phaseNumber, options) {
+  const signalPath = path.join(planningDir, '.auto-verify');
+  const payload = {
+    phase: phaseNumber,
+    round: options?.round || 1,
+    total_rounds: options?.total_rounds || 1,
+    timestamp: new Date().toISOString()
+  };
+  fs.writeFileSync(signalPath, JSON.stringify(payload, null, 2), 'utf8');
+}
+
+/**
+ * Check if multi-round QA is currently active (mid-round, not yet at final round).
+ * @param {string} planningDir - Path to .planning directory
+ * @returns {boolean} True if a multi-round QA session is in progress and not on the final round
+ */
+function isMultiRoundActive(planningDir) {
+  const signalPath = path.join(planningDir, '.auto-verify');
+  try {
+    const signal = JSON.parse(fs.readFileSync(signalPath, 'utf8'));
+    return signal.total_rounds > 1 && signal.round < signal.total_rounds;
+  } catch (_e) {
+    return false;
+  }
+}
+
+/**
+ * Check if trust tracking is enabled in config.json.
+ * @param {string} planningDir - Path to .planning directory
+ * @returns {boolean}
+ */
+function isTrustTrackingEnabled(planningDir) {
+  try {
+    const configPath = path.join(planningDir, 'config.json');
+    if (!fs.existsSync(configPath)) return true; // default true
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    return config.features?.trust_tracking !== false;
+  } catch (e) {
+    logHook('event-handler', 'SubagentStop', 'trust-config-read-error', { error: e.message });
+    return true;
+  }
+}
+
+module.exports = { shouldAutoVerify, getPhaseFromState, writeAutoVerifySignal, isMultiRoundActive, isTrustTrackingEnabled };

package/plugins/pbr/scripts/lib/benchmark.js

@@ -0,0 +1,190 @@
+/**
+ * lib/benchmark.js — Cost & duration benchmarking aggregation library.
+ *
+ * Parses JSONL cost tracker files written by log-subagent.js trackAgentCost()
+ * and aggregates entries by phase, agent type, skill, or session.
+ *
+ * Exports: parseCostLine, loadCostEntries, aggregateCosts, phaseSummary
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { parseYamlFrontmatter } = require('./core');
+
+/**
+ * Parse one JSONL line from an agent cost tracker file.
+ * @param {string} line - A single JSONL line
+ * @returns {{ ts: number, type: string, ms: number, phase: string|null, skill: string|null }|null}
+ */
+function parseCostLine(line) {
+  if (!line || typeof line !== 'string') return null;
+  try {
+    const obj = JSON.parse(line.trim());
+    if (!obj || typeof obj !== 'object') return null;
+    return {
+      ts: obj.ts || 0,
+      type: obj.type || 'unknown',
+      ms: obj.ms || 0,
+      phase: obj.phase || null,
+      skill: obj.skill || null
+    };
+  } catch (_e) {
+    return null;
+  }
+}
+
+/**
+ * Load all cost entries from .planning/ cost tracker files.
+ * Scans root .agent-cost-tracker and all session-scoped tracker files.
+ * @param {string} planningDir - Path to .planning/ directory
+ * @returns {Array<{ ts: number, type: string, ms: number, phase: string|null, skill: string|null }>}
+ */
+function loadCostEntries(planningDir) {
+  const entries = [];
+  if (!planningDir) return entries;
+
+  const COST_FILE = '.agent-cost-tracker';
+
+  // Read root tracker
+  _readTrackerFile(path.join(planningDir, COST_FILE), entries);
+
+  // Read session-scoped trackers
+  const sessionsDir = path.join(planningDir, '.sessions');
+  try {
+    const sessions = fs.readdirSync(sessionsDir, { withFileTypes: true });
+    for (const dirent of sessions) {
+      if (dirent.isDirectory()) {
+        _readTrackerFile(path.join(sessionsDir, dirent.name, COST_FILE), entries);
+      }
+    }
+  } catch (_e) {
+    // No .sessions dir or read error — that's fine
+  }
+
+  return entries;
+}
+
+/**
+ * Read a single tracker file and push parsed entries into the array.
+ * @param {string} filePath
+ * @param {Array} entries
+ */
+function _readTrackerFile(filePath, entries) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const lines = content.trim().split('\n');
+    for (const line of lines) {
+      const entry = parseCostLine(line);
+      if (entry) entries.push(entry);
+    }
+  } catch (_e) {
+    // File missing or unreadable — skip
+  }
+}
+
+/**
+ * Aggregate cost entries by a specified grouping key.
+ * @param {Array<{ ts: number, type: string, ms: number, phase: string|null, skill: string|null }>} entries
+ * @param {'phase'|'agent'|'skill'|'session'} groupBy
+ * @returns {{ groups: Object<string, { count: number, total_ms: number, avg_ms: number }>, totals: { count: number, total_ms: number } }}
+ */
+function aggregateCosts(entries, groupBy) {
+  const groups = {};
+  let totalCount = 0;
+  let totalMs = 0;
+
+  const keyFn = _groupKeyFn(groupBy);
+
+  for (const entry of entries) {
+    const key = keyFn(entry) || 'unknown';
+    if (!groups[key]) {
+      groups[key] = { count: 0, total_ms: 0, avg_ms: 0 };
+    }
+    groups[key].count += 1;
+    groups[key].total_ms += entry.ms || 0;
+    totalCount += 1;
+    totalMs += entry.ms || 0;
+  }
+
+  // Compute averages
+  for (const key of Object.keys(groups)) {
+    const g = groups[key];
+    g.avg_ms = g.count > 0 ? Math.round(g.total_ms / g.count) : 0;
+  }
+
+  return {
+    groups,
+    totals: { count: totalCount, total_ms: totalMs }
+  };
+}
+
+/**
+ * Return a function that extracts the grouping key from an entry.
+ * @param {'phase'|'agent'|'skill'|'session'} groupBy
+ * @returns {function(entry): string|null}
+ */
+function _groupKeyFn(groupBy) {
+  switch (groupBy) {
+    case 'phase': return (e) => e.phase;
+    case 'agent': return (e) => e.type;
+    case 'skill': return (e) => e.skill;
+    case 'session': return (e) => e.session || null;
+    default: return (e) => e.type;
+  }
+}
+
+/**
+ * Convenience: load entries, aggregate by phase, and pair with VERIFICATION.md quality scores.
+ * @param {string} planningDir - Path to .planning/ directory
+ * @returns {{ phases: Object<string, { count: number, total_ms: number, avg_ms: number, quality: string|null }>, totals: { count: number, total_ms: number } }}
+ */
+function phaseSummary(planningDir) {
+  const entries = loadCostEntries(planningDir);
+  const { groups, totals } = aggregateCosts(entries, 'phase');
+
+  // Enrich each phase group with quality from VERIFICATION.md
+  const phases = {};
+  for (const [phaseNum, stats] of Object.entries(groups)) {
+    phases[phaseNum] = {
+      ...stats,
+      quality: _readPhaseQuality(planningDir, phaseNum)
+    };
+  }
+
+  return { phases, totals };
+}
+
+/**
+ * Read the quality/status from a phase's VERIFICATION.md frontmatter.
+ * @param {string} planningDir
+ * @param {string} phaseNum
+ * @returns {string|null}
+ */
+function _readPhaseQuality(planningDir, phaseNum) {
+  if (!phaseNum || phaseNum === 'unknown' || phaseNum === 'null') return null;
+
+  const phasesDir = path.join(planningDir, 'phases');
+  try {
+    const entries = fs.readdirSync(phasesDir);
+    const prefix = phaseNum + '-';
+    for (const entry of entries) {
+      if (entry.startsWith(prefix)) {
+        const verPath = path.join(phasesDir, entry, 'VERIFICATION.md');
+        try {
+          const content = fs.readFileSync(verPath, 'utf8');
+          const fm = parseYamlFrontmatter(content);
+          return fm.status || fm.result || null;
+        } catch (_e) {
+          return null;
+        }
+      }
+    }
+  } catch (_e) {
+    // No phases dir
+  }
+  return null;
+}
+
+module.exports = { parseCostLine, loadCostEntries, aggregateCosts, phaseSummary };