@sienklogic/plan-build-run 2.11.0 → 2.12.1

package/plan-build-run/bin/lib/health.cjs

@@ -0,0 +1,133 @@
+/**
+ * lib/health.cjs — Multi-agent health checks for Plan-Build-Run.
+ *
+ * Reports enabled/disabled/healthy/degraded status for all multi-agent features.
+ * Part of Phase 13: Multi-Agent Evolution (experimental).
+ */
+
+const path = require('path');
+
+/**
+ * Feature-to-module mapping for multi-agent capabilities.
+ * @private
+ */
+const FEATURE_MODULE_MAP = {
+  agent_teams: './team-coordinator.cjs',
+  competing_hypotheses: './hypothesis-runner.cjs',
+  dynamic_teams: './team-composer.cjs'
+};
+
+/**
+ * Check health status of all multi-agent features.
+ * Pure function: config passed in, no side effects.
+ *
+ * @param {object} config - Config object with features section
+ * @returns {object[]} Array of { feature, status, error? } objects
+ *   - status: 'disabled' | 'healthy' | 'degraded'
+ *   - error: present only when status is 'degraded'
+ */
+function checkMultiAgentHealth(config) {
+  const features = (config && config.features) || {};
+  const results = [];
+
+  for (const [featureName, modulePath] of Object.entries(FEATURE_MODULE_MAP)) {
+    if (!features[featureName]) {
+      results.push({ feature: featureName, status: 'disabled' });
+      continue;
+    }
+
+    try {
+      require(path.resolve(__dirname, modulePath));
+      results.push({ feature: featureName, status: 'healthy' });
+    } catch (err) {
+      results.push({ feature: featureName, status: 'degraded', error: err.message });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Map Phase 9 feature names to their module paths (relative to scriptsDir).
+ * @private
+ */
+const PHASE9_MODULE_MAP = {
+  smart_next_task: 'lib/smart-next-task.js',
+  dependency_break_detection: 'lib/dependency-break.js',
+  pre_research: 'lib/pre-research.js',
+  pattern_routing: 'lib/pattern-routing.js',
+  tech_debt_surfacing: 'lib/tech-debt-scanner.js'
+};
+
+/**
+ * Check health status of a single feature by name.
+ * @param {string} name - Feature name (e.g. 'smart_next_task')
+ * @param {object} config - Config with features section
+ * @param {string} scriptsDir - Directory to look for the module
+ * @returns {{ name: string, status: 'healthy'|'disabled'|'degraded', error?: string }}
+ */
+function checkFeatureHealth(name, config, scriptsDir) {
+  const features = (config && config.features) || {};
+  if (features[name] === false) {
+    return { name, status: 'disabled' };
+  }
+  const modulePath = PHASE9_MODULE_MAP[name];
+  if (!modulePath) {
+    return { name, status: 'degraded', reason: `Unknown feature: ${name}` };
+  }
+  try {
+    require(path.join(scriptsDir, modulePath));
+    return { name, status: 'healthy' };
+  } catch (err) {
+    return { name, status: 'degraded', reason: err.message };
+  }
+}
+
+/**
+ * Check health of zero_friction_quick feature.
+ * @param {object} config - Config with features section
+ * @returns {{ feature: string, status: string }}
+ */
+function checkZeroFrictionHealth(config) {
+  const features = (config && config.features) || {};
+  const enabled = features.zero_friction_quick !== false;
+  return { feature: 'zero_friction_quick', status: enabled ? 'healthy' : 'disabled' };
+}
+
+/**
+ * Check health of post_hoc_artifacts feature.
+ * @param {object} config - Config with features section
+ * @returns {{ feature: string, status: string, detail: string }}
+ */
+function checkPostHocHealth(config) {
+  const features = (config && config.features) || {};
+  if (features.post_hoc_artifacts === false) {
+    return { feature: 'post_hoc_artifacts', status: 'disabled', detail: 'Feature disabled by config' };
+  }
+  try {
+    require(path.resolve(__dirname, '../../../plugins/pbr/scripts/lib/post-hoc.cjs'));
+    return { feature: 'post_hoc_artifacts', status: 'healthy', detail: 'post-hoc.cjs loaded successfully' };
+  } catch (err) {
+    // Try alternate path
+    try {
+      require(path.resolve(__dirname, 'post-hoc.cjs'));
+      return { feature: 'post_hoc_artifacts', status: 'healthy', detail: 'post-hoc.cjs loaded successfully' };
+    } catch (_e) {
+      return { feature: 'post_hoc_artifacts', status: 'degraded', detail: err.message };
+    }
+  }
+}
+
+/**
+ * Get health report for all zero-friction (Phase 3+10) features.
+ * @param {object} config - Config with features section
+ * @returns {object[]} Array of health check results
+ */
+function getZeroFrictionHealthReport(config) {
+  return [
+    checkZeroFrictionHealth(config),
+    checkPostHocHealth(config)
+  ];
+}
+
+module.exports = { checkMultiAgentHealth, checkFeatureHealth, checkZeroFrictionHealth, checkPostHocHealth, getZeroFrictionHealthReport };

package/plan-build-run/bin/lib/history.cjs

@@ -0,0 +1,147 @@
+/**
+ * lib/history.cjs -- 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)
+        const historyIdx = content.indexOf('## History');
+        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);
+      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
+};

package/plan-build-run/bin/lib/hypothesis-runner.cjs

@@ -0,0 +1,127 @@
+/**
+ * lib/hypothesis-runner.cjs — Competing hypotheses for Plan-Build-Run.
+ *
+ * Spawns multiple agents with different approach prompts on the same task,
+ * then scores and selects the best result.
+ * Part of Phase 13: Multi-Agent Evolution (experimental).
+ */
+
+const { TeamCoordinator } = require('./team-coordinator.cjs');
+
+const MAX_HYPOTHESES = 3;
+
+class HypothesisRunner {
+  /**
+   * Create a HypothesisRunner instance.
+   *
+   * @param {object} opts
+   * @param {string} [opts.planningDir] - Path to .planning directory
+   * @param {object} [opts.config] - Pre-loaded config object
+   */
+  constructor({ planningDir, config } = {}) {
+    this.config = config || {};
+    this.planningDir = planningDir;
+  }
+
+  /**
+   * Create task definitions for competing hypothesis agents.
+   * Each hypothesis gets a separate worktree-isolated agent with a unique prompt.
+   *
+   * @param {object} opts
+   * @param {object[]} opts.hypotheses - Array of { name, prompt } objects
+   * @param {string} opts.planId - Plan identifier
+   * @param {string} opts.baseAgent - Agent type to use for all hypotheses (e.g., 'executor')
+   * @returns {{ skipped: boolean, reason?: string, tasks?: object[], warning?: string }}
+   */
+  runHypotheses({ hypotheses = [], planId, baseAgent } = {}) {
+    const features = this.config.features || {};
+    if (!features.competing_hypotheses) {
+      return { skipped: true, reason: 'competing_hypotheses disabled' };
+    }
+
+    let warning;
+    let activeHypotheses = hypotheses;
+    if (hypotheses.length > MAX_HYPOTHESES) {
+      activeHypotheses = hypotheses.slice(0, MAX_HYPOTHESES);
+      warning = `Capped to 3 hypotheses (received ${hypotheses.length})`;
+    }
+
+    const tasks = activeHypotheses.map(h => ({
+      agentType: baseAgent,
+      isolation: 'worktree',
+      planId,
+      hypothesisName: h.name,
+      context: h.prompt
+    }));
+
+    return { skipped: false, tasks, warning };
+  }
+
+  /**
+   * Score a single hypothesis result.
+   * Formula: testsPassed * 100 - filesModified.length
+   *
+   * @param {object} result - Hypothesis result
+   * @returns {number} Numeric score
+   * @private
+   */
+  _scoreHypothesis(result) {
+    const testsPassed = result.testsPassed || 0;
+    const fileCount = (result.filesModified || []).length;
+    return testsPassed * 100 - fileCount;
+  }
+
+  /**
+   * Compare hypothesis results and select the winner.
+   * Primary sort: testsPassed descending. Tiebreak: fewer filesModified wins.
+   *
+   * @param {object[]} hypothesisResults - Array of result objects
+   * @param {string} hypothesisResults[].name - Hypothesis name
+   * @param {number} hypothesisResults[].testsPassed - Number of tests that passed
+   * @param {number} hypothesisResults[].testsTotal - Total number of tests
+   * @param {string[]} hypothesisResults[].filesModified - Files modified
+   * @param {string} hypothesisResults[].status - 'success' or 'failed'
+   * @returns {{ winner: object, rankings: object[], scores: object }}
+   */
+  compareResults(hypothesisResults = []) {
+    const scores = {};
+    for (const r of hypothesisResults) {
+      scores[r.name] = this._scoreHypothesis(r);
+    }
+
+    const rankings = [...hypothesisResults].sort((a, b) => {
+      return scores[b.name] - scores[a.name];
+    });
+
+    return {
+      winner: rankings[0] || null,
+      rankings,
+      scores
+    };
+  }
+
+  /**
+   * Format a markdown comparison report from hypothesis results.
+   *
+   * @param {object} comparisonResult - Output from compareResults()
+   * @returns {string} Markdown table string
+   */
+  formatReport(comparisonResult) {
+    const { winner, rankings, scores } = comparisonResult;
+    const lines = [
+      '| Hypothesis | Tests Passed | Files Modified | Score | Winner |',
+      '|------------|-------------|----------------|-------|--------|'
+    ];
+
+    for (const r of rankings) {
+      const isWinner = winner && r.name === winner.name;
+      const fileCount = (r.filesModified || []).length;
+      const winnerMark = isWinner ? '<-- WINNER' : '';
+      lines.push(`| ${r.name} | ${r.testsPassed || 0}/${r.testsTotal || 0} | ${fileCount} | ${scores[r.name]} | ${winnerMark} |`);
+    }
+
+    return lines.join('\n');
+  }
+}
+
+module.exports = { HypothesisRunner };