@sienklogic/plan-build-run 2.11.0 → 2.12.1

package/plugins/pbr/scripts/lib/gates/review-planner.js

@@ -0,0 +1,61 @@
+'use strict';
+
+/**
+ * Gate: review planner VERIFICATION.md check.
+ * When active skill is "review" and pbr:planner is spawned, verify
+ * that a VERIFICATION.md exists in the current phase directory.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { readActiveSkill, readCurrentPhase } = require('./helpers');
+
+/**
+ * Blocking check: when the active skill is "review" and a planner is being
+ * spawned, verify that a VERIFICATION.md exists in the current phase directory.
+ * Returns { block: true, reason: "..." } if blocked, or null if OK.
+ * @param {object} data - hook data with tool_input
+ * @returns {{ block: boolean, reason: string }|null}
+ */
+function checkReviewPlannerGate(data) {
+  const toolInput = data.tool_input || {};
+  const subagentType = toolInput.subagent_type || '';
+
+  // Only gate pbr:planner
+  if (subagentType !== 'pbr:planner') return null;
+
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+
+  // Only gate when active skill is "review"
+  const activeSkill = readActiveSkill(planningDir);
+  if (activeSkill !== 'review') return null;
+
+  // Read STATE.md for current phase
+  const currentPhase = readCurrentPhase(planningDir);
+  if (!currentPhase) return null;
+
+  try {
+    const phasesDir = path.join(planningDir, 'phases');
+    if (!fs.existsSync(phasesDir)) return null;
+
+    const dirs = fs.readdirSync(phasesDir).filter(d => d.startsWith(currentPhase + '-'));
+    if (dirs.length === 0) return null;
+
+    const phaseDir = path.join(phasesDir, dirs[0]);
+    const hasVerification = fs.existsSync(path.join(phaseDir, 'VERIFICATION.md'));
+
+    if (!hasVerification) {
+      return {
+        block: true,
+        reason: 'Review planner gate: cannot spawn planner without VERIFICATION.md.\n\nGap closure requires an existing VERIFICATION.md to identify which gaps need closing. Without it, the planner has no input.\n\nRun /pbr:verify-work {N} to create VERIFICATION.md first.'
+      };
+    }
+  } catch (_e) {
+    return null;
+  }
+
+  return null;
+}
+
+module.exports = { checkReviewPlannerGate };

package/plugins/pbr/scripts/lib/gates/review-verifier.js

@@ -0,0 +1,69 @@
+'use strict';
+
+/**
+ * Gate: review verifier SUMMARY.md check.
+ * When active skill is "review" and pbr:verifier is spawned, verify
+ * that a SUMMARY*.md exists in the current phase directory.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { readActiveSkill, readCurrentPhase } = require('./helpers');
+
+/**
+ * Blocking check: when the active skill is "review" and a verifier is being
+ * spawned, verify that a SUMMARY*.md exists in the current phase directory.
+ * Returns { block: true, reason: "..." } if blocked, or null if OK.
+ * @param {object} data - hook data with tool_input
+ * @returns {{ block: boolean, reason: string }|null}
+ */
+function checkReviewVerifierGate(data) {
+  const toolInput = data.tool_input || {};
+  const subagentType = toolInput.subagent_type || '';
+
+  // Only gate pbr:verifier
+  if (subagentType !== 'pbr:verifier') return null;
+
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+
+  // Only gate when active skill is "review"
+  const activeSkill = readActiveSkill(planningDir);
+  if (activeSkill !== 'review') return null;
+
+  // Read STATE.md for current phase
+  const currentPhase = readCurrentPhase(planningDir);
+  if (!currentPhase) return null;
+
+  try {
+    const phasesDir = path.join(planningDir, 'phases');
+    if (!fs.existsSync(phasesDir)) return null;
+
+    const dirs = fs.readdirSync(phasesDir).filter(d => d.startsWith(currentPhase + '-'));
+    if (dirs.length === 0) return null;
+
+    const phaseDir = path.join(phasesDir, dirs[0]);
+    const files = fs.readdirSync(phaseDir);
+    const hasSummary = files.some(f => {
+      if (!/^SUMMARY/i.test(f)) return false;
+      try {
+        return fs.statSync(path.join(phaseDir, f)).size > 0;
+      } catch (_e) {
+        return false;
+      }
+    });
+
+    if (!hasSummary) {
+      return {
+        block: true,
+        reason: 'Review verifier gate: cannot spawn verifier without SUMMARY.md.\n\nThe verifier checks executor output against the plan. Without a SUMMARY.md, there is nothing to verify.\n\nRun /pbr:execute-phase {N} to create SUMMARY.md first.'
+      };
+    }
+  } catch (_e) {
+    return null;
+  }
+
+  return null;
+}
+
+module.exports = { checkReviewVerifierGate };

package/plugins/pbr/scripts/lib/gates/rich-agent-context.js

@@ -0,0 +1,143 @@
+'use strict';
+
+/**
+ * Rich Agent Context Builder
+ *
+ * Builds a prioritized context string from .planning/ sources for enriching
+ * Task() spawn prompts. Respects the rich_agent_prompts feature toggle and
+ * a configurable character budget.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Build a rich context string from .planning/ sources.
+ * Sections are built in priority order (highest first). If total exceeds
+ * budgetChars, lowest-priority sections are dropped.
+ *
+ * @param {string} planningDir - path to .planning directory
+ * @param {object} config - project config object
+ * @param {number} [budgetChars=5000] - maximum character budget
+ * @returns {string} context string or empty string if disabled
+ */
+function buildRichAgentContext(planningDir, config, budgetChars = 5000) {
+  // Check feature toggle — only explicitly false disables it
+  if (config && config.features && config.features.rich_agent_prompts === false) {
+    return '';
+  }
+
+  const sections = [];
+
+  // 1. Project summary (highest priority)
+  try {
+    const projectPath = path.join(planningDir, 'PROJECT.md');
+    if (fs.existsSync(projectPath)) {
+      const content = fs.readFileSync(projectPath, 'utf8');
+      const lines = content.split(/\r?\n/).slice(0, 20);
+      sections.push({ priority: 1, header: '### Project Summary', body: lines.join('\n') });
+    }
+  } catch (_e) { /* skip if unreadable */ }
+
+  // 2. Current state from STATE.md frontmatter
+  try {
+    const statePath = path.join(planningDir, 'STATE.md');
+    if (fs.existsSync(statePath)) {
+      const content = fs.readFileSync(statePath, 'utf8');
+      const stateInfo = parseStateFrontmatter(content);
+      if (stateInfo) {
+        sections.push({ priority: 2, header: '### Current State', body: stateInfo });
+      }
+    }
+  } catch (_e) { /* skip if unreadable */ }
+
+  // 3. Recent decisions (up to 5 most recent)
+  try {
+    const decisionsDir = path.join(planningDir, 'decisions');
+    if (fs.existsSync(decisionsDir)) {
+      const files = fs.readdirSync(decisionsDir)
+        .filter(f => f.endsWith('.md'))
+        .sort()
+        .slice(-5);
+      if (files.length > 0) {
+        const titles = files.map(f => `- ${f.replace(/\.md$/, '')}`).join('\n');
+        sections.push({ priority: 3, header: '### Recent Decisions', body: titles });
+      }
+    }
+  } catch (_e) { /* skip if unreadable */ }
+
+  // 4. Active conventions
+  try {
+    const convDir = path.join(planningDir, 'conventions');
+    if (fs.existsSync(convDir)) {
+      const files = fs.readdirSync(convDir)
+        .filter(f => f.endsWith('.md'))
+        .sort();
+      if (files.length > 0) {
+        const titles = files.map(f => `- ${f.replace(/\.md$/, '')}`).join('\n');
+        sections.push({ priority: 4, header: '### Active Conventions', body: titles });
+      }
+    }
+  } catch (_e) { /* skip if unreadable */ }
+
+  // 5. Working set from STATE.md (lowest priority)
+  try {
+    const statePath = path.join(planningDir, 'STATE.md');
+    if (fs.existsSync(statePath)) {
+      const content = fs.readFileSync(statePath, 'utf8');
+      const wsMatch = content.match(/working_set:\s*\n((?:\s+-\s+.+\n?)+)/);
+      if (wsMatch) {
+        sections.push({ priority: 5, header: '### Working Set', body: wsMatch[1].trim() });
+      }
+    }
+  } catch (_e) { /* skip if unreadable */ }
+
+  // Assemble with budget control — drop lowest priority sections first
+  // Sort by priority (ascending = highest priority first)
+  sections.sort((a, b) => a.priority - b.priority);
+
+  let result = '';
+  for (const section of sections) {
+    const addition = `${section.header}\n${section.body}\n\n`;
+    if ((result + addition).length > budgetChars) {
+      // Try truncating just this section's body to fit
+      const remaining = budgetChars - result.length - section.header.length - 2; // 2 for \n after header + \n at end
+      if (remaining > 20) {
+        result += `${section.header}\n${section.body.slice(0, remaining - 3)}...`;
+      }
+      break; // Don't add any more sections
+    }
+    result += addition;
+  }
+
+  return result.trimEnd();
+}
+
+/**
+ * Parse STATE.md frontmatter for key state info.
+ * @param {string} content - STATE.md content
+ * @returns {string|null} formatted state info or null
+ */
+function parseStateFrontmatter(content) {
+  const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!fmMatch) return null;
+
+  const fm = fmMatch[1];
+  const parts = [];
+
+  const phase = fm.match(/current_phase:\s*(.+)/);
+  if (phase) parts.push(`Phase: ${phase[1].trim()}`);
+
+  const status = fm.match(/status:\s*"?([^"\n]+)"?/);
+  if (status) parts.push(`Status: ${status[1].trim()}`);
+
+  const progress = fm.match(/progress_percent:\s*(\d+)/);
+  if (progress) parts.push(`Progress: ${progress[1]}%`);
+
+  const slug = fm.match(/phase_slug:\s*"?([^"\n]+)"?/);
+  if (slug) parts.push(`Phase: ${slug[1].trim()}`);
+
+  return parts.length > 0 ? parts.join('\n') : null;
+}
+
+module.exports = { buildRichAgentContext };

package/plugins/pbr/scripts/lib/health-checks.js

@@ -0,0 +1,215 @@
+'use strict';
+
+/**
+ * health-checks.js — Health check functions for Phase 10 features.
+ *
+ * Checks: post_hoc_artifacts, agent_feedback_loop, session_metrics.
+ * Each returns { name, enabled, status, detail? }.
+ *
+ * Exports: checkPostHocArtifacts, checkAgentFeedbackLoop, checkSessionMetrics, getAllPhase10Checks
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Load config features from planningDir.
+ * @param {string} planningDir
+ * @returns {Object} features object (or empty)
+ */
+function loadFeatures(planningDir) {
+  try {
+    const configPath = path.join(planningDir, 'config.json');
+    if (fs.existsSync(configPath)) {
+      const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+      return (config && config.features) || {};
+    }
+  } catch (_e) { /* best-effort */ }
+  return {};
+}
+
+/**
+ * Check post_hoc_artifacts health.
+ */
+function checkPostHocArtifacts(planningDir) {
+  const features = loadFeatures(planningDir);
+
+  // Try to load the module
+  try {
+    const postHoc = require('../post-hoc');
+    const enabled = postHoc.isEnabled ? postHoc.isEnabled(planningDir) : (features.post_hoc_artifacts !== false);
+
+    if (!enabled) {
+      return { name: 'post_hoc_artifacts', enabled: false, status: 'disabled' };
+    }
+    return { name: 'post_hoc_artifacts', enabled: true, status: 'healthy' };
+  } catch (e) {
+    return { name: 'post_hoc_artifacts', enabled: false, status: 'error', detail: 'Module not loadable: ' + e.message };
+  }
+}
+
+/**
+ * Check agent_feedback_loop health.
+ */
+function checkAgentFeedbackLoop(planningDir) {
+  const features = loadFeatures(planningDir);
+
+  try {
+    const feedbackLoop = require('../feedback-loop');
+    const enabled = feedbackLoop.isEnabled ? feedbackLoop.isEnabled(planningDir) : (features.agent_feedback_loop !== false);
+
+    if (!enabled) {
+      return { name: 'agent_feedback_loop', enabled: false, status: 'disabled' };
+    }
+
+    // Module loaded successfully — healthy
+    return { name: 'agent_feedback_loop', enabled: true, status: 'healthy' };
+  } catch (e) {
+    return { name: 'agent_feedback_loop', enabled: false, status: 'error', detail: 'Module not loadable: ' + e.message };
+  }
+}
+
+/**
+ * Check session_metrics health.
+ */
+function checkSessionMetrics(planningDir) {
+  const features = loadFeatures(planningDir);
+
+  if (features.session_metrics === false) {
+    return { name: 'session_metrics', enabled: false, status: 'disabled' };
+  }
+
+  // Check if formatSessionMetrics is exported from session-cleanup.js
+  try {
+    const sessionCleanup = require('../session-cleanup');
+    if (typeof sessionCleanup.formatSessionMetrics !== 'function') {
+      return { name: 'session_metrics', enabled: true, status: 'degraded', detail: 'formatSessionMetrics not exported' };
+    }
+    return { name: 'session_metrics', enabled: true, status: 'healthy' };
+  } catch (e) {
+    return { name: 'session_metrics', enabled: true, status: 'error', detail: 'Module not loadable: ' + e.message };
+  }
+}
+
+/**
+ * Check hook coverage by cross-referencing hooks.json against recent hook log entries.
+ * @param {string} planningDir
+ * @returns {Object} Check result with name, enabled, status, detail, configured, evidenced, missing
+ */
+function checkHookCoverage(planningDir) {
+  try {
+    // Load hooks.json from plugin root
+    let hooksConfig;
+    const primaryPath = path.resolve(__dirname, '..', '..', '..', 'hooks', 'hooks.json');
+    const fallbackPath = path.resolve(__dirname, '..', '..', 'hooks', 'hooks.json');
+
+    try {
+      hooksConfig = JSON.parse(fs.readFileSync(primaryPath, 'utf8'));
+    } catch (_e) {
+      try {
+        hooksConfig = JSON.parse(fs.readFileSync(fallbackPath, 'utf8'));
+      } catch (_e2) {
+        return { name: 'hook_coverage', enabled: false, status: 'error', detail: 'hooks.json not found' };
+      }
+    }
+
+    // Extract unique script names from hooks.json entries
+    const scriptRegex = /\b(\w[\w-]*\.js)\s*"?\s*$/;
+    const configuredHooks = new Set();
+    const hooks = hooksConfig.hooks || {};
+    for (const eventType of Object.keys(hooks)) {
+      const entries = hooks[eventType];
+      if (!Array.isArray(entries)) continue;
+      for (const entry of entries) {
+        const hookList = entry.hooks || [];
+        for (const h of hookList) {
+          if (h.command) {
+            const match = h.command.match(scriptRegex);
+            if (match) {
+              // Strip .js to match the hook field format in log entries
+              configuredHooks.add(match[1].replace(/\.js$/, ''));
+            }
+          }
+        }
+      }
+    }
+
+    const configuredArr = Array.from(configuredHooks).sort();
+
+    // Read the 3 most recent hooks-*.jsonl files (covers session-boundary hooks
+    // like progress-tracker that may only fire at SessionStart in earlier logs)
+    const logsDir = path.join(planningDir, 'logs');
+    const evidencedHooks = new Set();
+
+    if (fs.existsSync(logsDir)) {
+      const logFiles = fs.readdirSync(logsDir)
+        .filter(f => /^hooks-\d{4}-\d{2}-\d{2}\.jsonl$/.test(f))
+        .sort()
+        .reverse()
+        .slice(0, 3);
+
+      for (const logFile of logFiles) {
+        const logPath = path.join(logsDir, logFile);
+        const content = fs.readFileSync(logPath, 'utf8');
+        for (const line of content.split('\n')) {
+          if (!line.trim()) continue;
+          try {
+            const entry = JSON.parse(line);
+            if (entry.hook) evidencedHooks.add(entry.hook);
+          } catch (_e) { /* skip malformed lines */ }
+        }
+      }
+    }
+
+    const evidencedArr = Array.from(evidencedHooks).sort();
+    const allMissing = configuredArr.filter(h => !evidencedHooks.has(h));
+
+    // Hooks that only fire on rare/specific events — not concerning if absent
+    const rareEventHooks = new Set([
+      'intercept-plan-mode',  // only fires when user enters native plan mode
+      'progress-tracker',     // only fires at SessionStart (may log to different day)
+      'context-bridge'        // only fires at SessionStart
+    ]);
+
+    const missingHooks = allMissing.filter(h => !rareEventHooks.has(h));
+    const untestedHooks = allMissing.filter(h => rareEventHooks.has(h));
+
+    let status = 'healthy';
+    let detail = `All ${configuredArr.length} configured hooks accounted for`;
+    if (missingHooks.length > 0) {
+      status = 'degraded';
+      detail = `${missingHooks.length} hooks with no evidence: ${missingHooks.join(', ')}`;
+    } else if (untestedHooks.length > 0) {
+      detail += ` (${untestedHooks.length} rare-event hooks untested: ${untestedHooks.join(', ')})`;
+    }
+
+    return {
+      name: 'hook_coverage',
+      enabled: true,
+      status,
+      detail,
+      configured: configuredArr.length,
+      evidenced: evidencedArr.length,
+      missing: missingHooks,
+      untested: untestedHooks
+    };
+  } catch (e) {
+    return { name: 'hook_coverage', enabled: false, status: 'error', detail: e.message };
+  }
+}
+
+/**
+ * Run all Phase 10 health checks.
+ * @param {string} planningDir
+ * @returns {Array<Object>} Array of check results
+ */
+function getAllPhase10Checks(planningDir) {
+  return [
+    checkPostHocArtifacts(planningDir),
+    checkAgentFeedbackLoop(planningDir),
+    checkSessionMetrics(planningDir),
+    checkHookCoverage(planningDir)
+  ];
+}
+
+module.exports = { checkPostHocArtifacts, checkAgentFeedbackLoop, checkSessionMetrics, checkHookCoverage, getAllPhase10Checks };

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

@@ -0,0 +1,150 @@
+/**
+ * lib/history.js — History operations for Plan-Build-Run tools.
+ *
+ * Handles appending and loading project history records.
+ * History is stored in STATE.md under a ## History section.
+ * Backwards compat: reads from legacy HISTORY.md if STATE.md has no ## History.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Append a history record to STATE.md ## History section.
+ * Falls back to legacy HISTORY.md if STATE.md does not exist.
+ * Creates the ## History section in STATE.md if it doesn't exist.
+ *
+ * @param {object} entry - { type: 'milestone'|'phase'|'metric', title: string, body: string }
+ * @param {string} [dir] - Path to .planning directory
+ * @returns {{success: boolean, error?: string, target?: string}}
+ */
+function historyAppend(entry, dir) {
+  const planningDir = dir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const statePath = path.join(planningDir, 'STATE.md');
+  const legacyPath = path.join(planningDir, 'HISTORY.md');
+  const timestamp = new Date().toISOString().slice(0, 10);
+
+  const section = `### ${entry.type === 'milestone' ? 'Milestone' : 'Phase'}: ${entry.title}\n_Completed: ${timestamp}_\n\n${entry.body.trim()}\n\n---\n\n`;
+
+  // Primary target: STATE.md ## History section
+  if (fs.existsSync(statePath)) {
+    try {
+      let content = fs.readFileSync(statePath, 'utf8');
+
+      if (content.includes('## History')) {
+        // Append after the ## History heading (at the end of the section)
+        // Find the ## History line and append after all existing history content
+        const historyIdx = content.indexOf('## History');
+        // Find the next ## heading after ## History (or end of file)
+        const afterHistory = content.slice(historyIdx + '## History'.length);
+        const nextHeadingMatch = afterHistory.match(/\n## [^#]/);
+        const insertPos = nextHeadingMatch
+          ? historyIdx + '## History'.length + nextHeadingMatch.index
+          : content.length;
+
+        content = content.slice(0, insertPos).trimEnd() + '\n\n' + section + content.slice(insertPos);
+      } else {
+        // Add ## History section at end of STATE.md
+        content = content.trimEnd() + '\n\n## History\n\n' + section;
+      }
+
+      fs.writeFileSync(statePath, content, 'utf8');
+      return { success: true, target: 'STATE.md' };
+    } catch (e) {
+      return { success: false, error: e.message };
+    }
+  }
+
+  // Fallback: legacy HISTORY.md (if STATE.md doesn't exist)
+  let header = '';
+  if (!fs.existsSync(legacyPath)) {
+    header = '# Project History\n\nCompleted milestones and phase records. This file is append-only.\n\n';
+  }
+
+  const legacySection = `${header}## ${entry.type === 'milestone' ? 'Milestone' : 'Phase'}: ${entry.title}\n_Completed: ${timestamp}_\n\n${entry.body.trim()}\n\n---\n\n`;
+
+  try {
+    fs.appendFileSync(legacyPath, legacySection, 'utf8');
+    return { success: true, target: 'HISTORY.md (legacy)' };
+  } catch (e) {
+    return { success: false, error: e.message };
+  }
+}
+
+/**
+ * Load history records. Reads from STATE.md ## History section first,
+ * falls back to legacy HISTORY.md for backwards compatibility.
+ *
+ * @param {string} [dir] - Path to .planning directory
+ * @returns {object|null} { records: [{type, title, date, body}], line_count, source }
+ */
+function historyLoad(dir) {
+  const planningDir = dir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const statePath = path.join(planningDir, 'STATE.md');
+  const legacyPath = path.join(planningDir, 'HISTORY.md');
+
+  // Try STATE.md ## History section first
+  if (fs.existsSync(statePath)) {
+    const stateContent = fs.readFileSync(statePath, 'utf8');
+    if (stateContent.includes('## History')) {
+      const historyIdx = stateContent.indexOf('## History');
+      const afterHistory = stateContent.slice(historyIdx);
+      // Extract until next ## heading (not ###)
+      const nextHeadingMatch = afterHistory.slice('## History'.length).match(/\n## [^#]/);
+      const historyContent = nextHeadingMatch
+        ? afterHistory.slice(0, '## History'.length + nextHeadingMatch.index)
+        : afterHistory;
+
+      const records = parseHistoryRecords(historyContent);
+      if (records.length > 0) {
+        return {
+          records,
+          line_count: historyContent.split('\n').length,
+          source: 'STATE.md'
+        };
+      }
+    }
+  }
+
+  // Fallback: legacy HISTORY.md
+  if (fs.existsSync(legacyPath)) {
+    const content = fs.readFileSync(legacyPath, 'utf8');
+    const records = parseHistoryRecords(content);
+    return {
+      records,
+      line_count: content.split('\n').length,
+      source: 'HISTORY.md (legacy)'
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Parse history records from markdown content.
+ * Supports both ## and ### level headings for milestone/phase records.
+ *
+ * @param {string} content - Markdown content containing history records
+ * @returns {Array<{type: string, title: string, date: string, body: string}>}
+ */
+function parseHistoryRecords(content) {
+  const records = [];
+  const sectionRegex = /^#{2,3} (Milestone|Phase): (.+)\n_Completed: (\d{4}-\d{2}-\d{2})_\n\n([\s\S]*?)(?=\n---|\s*$)/gm;
+
+  let match;
+  while ((match = sectionRegex.exec(content)) !== null) {
+    records.push({
+      type: match[1].toLowerCase(),
+      title: match[2].trim(),
+      date: match[3],
+      body: match[4].trim()
+    });
+  }
+
+  return records;
+}
+
+module.exports = {
+  historyAppend,
+  historyLoad
+};