@sienklogic/plan-build-run 2.19.0 → 2.19.1

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

@@ -0,0 +1,120 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Check health of the convention_memory feature.
+ * @param {string} planningDir - Absolute path to .planning/ directory
+ * @param {object} config - Parsed config.json object
+ * @returns {{ feature: string, status: string, details?: object }}
+ */
+function checkConventionMemory(planningDir, config) {
+  if (config.features?.convention_memory === false) {
+    return { feature: 'convention_memory', status: 'disabled' };
+  }
+
+  const convDir = path.join(planningDir, 'conventions');
+  try {
+    const entries = fs.readdirSync(convDir).filter(f => f.endsWith('.md'));
+    if (entries.length > 0) {
+      // Get most recent mtime
+      let latestMtime = 0;
+      for (const entry of entries) {
+        const stat = fs.statSync(path.join(convDir, entry));
+        if (stat.mtimeMs > latestMtime) latestMtime = stat.mtimeMs;
+      }
+      return {
+        feature: 'convention_memory',
+        status: 'healthy',
+        details: {
+          files: entries.length,
+          last_updated: new Date(latestMtime).toISOString()
+        }
+      };
+    }
+  } catch (_e) {
+    // Directory doesn't exist or can't be read
+  }
+
+  return {
+    feature: 'convention_memory',
+    status: 'degraded',
+    details: { reason: 'No conventions detected yet. Run a build to trigger detection.' }
+  };
+}
+
+/**
+ * Check health of the mental_model_snapshots feature.
+ * @param {string} planningDir - Absolute path to .planning/ directory
+ * @param {object} config - Parsed config.json object
+ * @returns {{ feature: string, status: string, details?: object }}
+ */
+function checkMentalModelSnapshots(planningDir, config) {
+  if (config.features?.mental_model_snapshots === false) {
+    return { feature: 'mental_model_snapshots', status: 'disabled' };
+  }
+
+  const snapDir = path.join(planningDir, 'sessions', 'snapshots');
+  try {
+    const entries = fs.readdirSync(snapDir).filter(f => f.endsWith('.md'));
+    if (entries.length > 0) {
+      // Sort to find latest by filename (timestamped)
+      entries.sort();
+      return {
+        feature: 'mental_model_snapshots',
+        status: 'healthy',
+        details: {
+          snapshots: entries.length,
+          latest: entries[entries.length - 1]
+        }
+      };
+    }
+  } catch (_e) {
+    // Directory doesn't exist or can't be read
+  }
+
+  return {
+    feature: 'mental_model_snapshots',
+    status: 'degraded',
+    details: { reason: 'No snapshots yet. End a session to trigger capture.' }
+  };
+}
+
+/**
+ * Write audit evidence for health check results to .planning/logs/audit-evidence.jsonl.
+ * @param {string} planningDir - Absolute path to .planning/ directory
+ * @param {Array<object>} featureResults - Array of health check results
+ */
+function writeAuditEvidence(planningDir, featureResults) {
+  const logsDir = path.join(planningDir, 'logs');
+  try {
+    fs.mkdirSync(logsDir, { recursive: true });
+    const logFile = path.join(logsDir, 'audit-evidence.jsonl');
+    const ts = new Date().toISOString();
+    const lines = featureResults.map(r =>
+      JSON.stringify({ ts, cat: 'health', feature: r.feature, status: r.status, details: r.details || {} })
+    ).join('\n') + '\n';
+    fs.appendFileSync(logFile, lines);
+  } catch (_e) {
+    // Best-effort logging; do not fail health checks on write errors
+  }
+}
+
+/**
+ * Check all Phase 06 features and return array of results.
+ * Also writes audit evidence to .planning/logs/audit-evidence.jsonl.
+ * @param {string} planningDir - Absolute path to .planning/ directory
+ * @param {object} config - Parsed config.json object
+ * @returns {Array<{ feature: string, status: string, details?: object }>}
+ */
+function checkAll(planningDir, config) {
+  const results = [
+    checkConventionMemory(planningDir, config),
+    checkMentalModelSnapshots(planningDir, config)
+  ];
+  writeAuditEvidence(planningDir, results);
+  return results;
+}
+
+module.exports = { checkConventionMemory, checkMentalModelSnapshots, checkAll };

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

@@ -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.js',
+  competing_hypotheses: './hypothesis-runner.js',
+  dynamic_teams: './team-composer.js'
+};
+
+/**
+ * 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('./post-hoc');
+    return { feature: 'post_hoc_artifacts', status: 'healthy', detail: 'post-hoc.cjs loaded successfully' };
+  } catch (err) {
+    // Try alternate path
+    try {
+      require('./post-hoc');
+      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/plugins/pbr/scripts/lib/help.js

@@ -0,0 +1,151 @@
+'use strict';
+
+/**
+ * lib/help.js — CLI help and skill metadata for Plan-Build-Run.
+ *
+ * Provides structured JSON output for skill discovery and metadata lookup.
+ *
+ * Exported functions:
+ *   helpList(pluginRoot)                   — List all skills with metadata
+ *   skillMetadata(skillName, pluginRoot)   — Get metadata for a single skill
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Parse YAML frontmatter from markdown content.
+ * Uses the same --- delimiter pattern as core.js:parseYamlFrontmatter.
+ *
+ * @param {string} content - Markdown content with optional frontmatter
+ * @returns {object} Parsed frontmatter fields
+ */
+function parseFrontmatter(content) {
+  const normalized = content.replace(/\r\n/g, '\n');
+  const match = normalized.match(/^---\s*\n([\s\S]*?)\n---/);
+  if (!match) return {};
+
+  const yaml = match[1];
+  const result = {};
+  let currentKey = null;
+
+  for (const line of yaml.split('\n')) {
+    // Array item
+    if (/^\s+-\s+/.test(line) && currentKey) {
+      const val = line.replace(/^\s+-\s+/, '').trim().replace(/^["']|["']$/g, '');
+      if (!result[currentKey]) result[currentKey] = [];
+      if (Array.isArray(result[currentKey])) {
+        result[currentKey].push(val);
+      }
+      continue;
+    }
+
+    // Key-value pair
+    const kvMatch = line.match(/^([\w][\w-]*)\s*:\s*(.*)/);
+    if (kvMatch) {
+      currentKey = kvMatch[1];
+      let val = kvMatch[2].trim();
+
+      if (val === '' || val === '|') continue;
+
+      // Handle arrays on same line: [a, b, c]
+      if (val.startsWith('[') && val.endsWith(']')) {
+        result[currentKey] = val.slice(1, -1).split(',')
+          .map(v => v.trim().replace(/^["']|["']$/g, ''))
+          .filter(Boolean);
+        continue;
+      }
+
+      // Clean quotes
+      val = val.replace(/^["']|["']$/g, '');
+      result[currentKey] = val;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * List all skills with their metadata from skills/ directory.
+ *
+ * @param {string} pluginRoot - Plugin root directory
+ * @returns {{ skills: Array<{ name: string, description: string, allowed_tools: string[], argument_hint: string }> }}
+ */
+function helpList(pluginRoot) {
+  const skillsDir = path.join(pluginRoot, 'skills');
+  let entries;
+  try {
+    entries = fs.readdirSync(skillsDir, { withFileTypes: true })
+      .filter(e => e.isDirectory());
+  } catch (_e) {
+    return { skills: [] };
+  }
+
+  const skills = [];
+  for (const entry of entries) {
+    const skillMd = path.join(skillsDir, entry.name, 'SKILL.md');
+    try {
+      const content = fs.readFileSync(skillMd, 'utf8');
+      const fm = parseFrontmatter(content);
+      const allowedTools = fm['allowed-tools']
+        ? (Array.isArray(fm['allowed-tools'])
+          ? fm['allowed-tools']
+          : String(fm['allowed-tools']).split(',').map(t => t.trim()).filter(Boolean))
+        : [];
+      skills.push({
+        name: fm.name || entry.name,
+        description: fm.description || '',
+        allowed_tools: allowedTools,
+        argument_hint: fm['argument-hint'] || ''
+      });
+    } catch (_e) {
+      // Skip unreadable skills
+    }
+  }
+
+  skills.sort((a, b) => a.name.localeCompare(b.name));
+  return { skills };
+}
+
+/**
+ * Get metadata for a single skill.
+ *
+ * @param {string} skillName - Skill name (e.g., "build", "quick")
+ * @param {string} pluginRoot - Plugin root directory
+ * @returns {object} Skill metadata or error object
+ */
+function skillMetadata(skillName, pluginRoot) {
+  const skillMd = path.join(pluginRoot, 'skills', skillName, 'SKILL.md');
+
+  if (!fs.existsSync(skillMd)) {
+    const skillsDir = path.join(pluginRoot, 'skills');
+    let available = [];
+    try {
+      available = fs.readdirSync(skillsDir, { withFileTypes: true })
+        .filter(e => e.isDirectory())
+        .map(e => e.name);
+    } catch (_e) { /* empty */ }
+    return { error: 'Skill not found', skill: skillName, available };
+  }
+
+  try {
+    const content = fs.readFileSync(skillMd, 'utf8');
+    const fm = parseFrontmatter(content);
+    const allowedTools = fm['allowed-tools']
+      ? (Array.isArray(fm['allowed-tools'])
+        ? fm['allowed-tools']
+        : String(fm['allowed-tools']).split(',').map(t => t.trim()).filter(Boolean))
+      : [];
+    return {
+      name: fm.name || skillName,
+      description: fm.description || '',
+      allowed_tools: allowedTools,
+      argument_hint: fm['argument-hint'] || '',
+      file_path: skillMd
+    };
+  } catch (e) {
+    return { error: `Cannot read skill file: ${e.message}` };
+  }
+}
+
+module.exports = { helpList, skillMetadata };

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
+};

package/plugins/pbr/scripts/lib/hypothesis-runner.js

@@ -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');
+
+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 };