@sienklogic/plan-build-run 2.53.0 → 2.55.0

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

@@ -0,0 +1,203 @@
+'use strict';
+
+/**
+ * alternatives.js — Conversational error recovery helpers for PBR skills.
+ *
+ * Provides structured JSON responses for three error scenarios:
+ *   phaseAlternatives(slug, planningDir)      — phase-not-found recovery
+ *   prerequisiteAlternatives(phase, planningDir) — missing-prereq recovery
+ *   configAlternatives(field, value, planningDir) — config-invalid recovery
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Known config fields and their valid values
+const KNOWN_CONFIG_FIELDS = {
+  'depth': ['quick', 'standard', 'deep'],
+  'git.branching': ['phase', 'main', 'off'],
+  'gates.confirm_plan': [true, false, 'true', 'false'],
+  'gates.confirm_execute': [true, false, 'true', 'false'],
+  'gates.confirm_review': [true, false, 'true', 'false'],
+  'gates.confirm_milestone': [true, false, 'true', 'false'],
+  'parallelism': ['off', 'wave', 'full'],
+  'models.default': ['haiku', 'sonnet', 'inherit'],
+  'models.planner': ['haiku', 'sonnet', 'inherit'],
+  'models.executor': ['haiku', 'sonnet', 'inherit'],
+  'models.verifier': ['haiku', 'sonnet', 'inherit']
+};
+
+/**
+ * Score similarity between two strings using character overlap.
+ * Returns a value between 0 and 1 (higher = more similar).
+ *
+ * @param {string} a - First string
+ * @param {string} b - Second string
+ * @returns {number} Similarity score between 0 and 1
+ */
+function scoreSlug(a, b) {
+  if (!a || !b) return 0;
+  const lowerA = a.toLowerCase();
+  const lowerB = b.toLowerCase();
+  // Count shared characters (by frequency)
+  const freqA = {};
+  for (const ch of lowerA) freqA[ch] = (freqA[ch] || 0) + 1;
+  let shared = 0;
+  const freqB = {};
+  for (const ch of lowerB) freqB[ch] = (freqB[ch] || 0) + 1;
+  for (const ch of Object.keys(freqA)) {
+    if (freqB[ch]) shared += Math.min(freqA[ch], freqB[ch]);
+  }
+  // Also boost score when one string contains the other as substring
+  let substringBonus = 0;
+  if (lowerB.includes(lowerA) || lowerA.includes(lowerB)) substringBonus = 0.2;
+  const score = shared / Math.max(lowerA.length, lowerB.length) + substringBonus;
+  return Math.min(score, 1);
+}
+
+/**
+ * Generate alternatives for a phase-not-found error.
+ *
+ * @param {string} slug - The unknown phase slug
+ * @param {string} planningDir - Path to .planning directory
+ * @returns {{ error_type: string, slug: string, available: string[], suggestions: string[] }}
+ */
+function phaseAlternatives(slug, planningDir) {
+  const phasesDir = path.join(planningDir, 'phases');
+  let available = [];
+
+  try {
+    if (fs.existsSync(phasesDir)) {
+      const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+      available = entries
+        .filter(e => e.isDirectory())
+        .map(e => e.name);
+    }
+  } catch (_e) {
+    // If we can't read, return empty
+    available = [];
+  }
+
+  let suggestions = [];
+  if (slug && slug.length > 0 && available.length > 0) {
+    const scored = available
+      .map(name => ({ name, score: scoreSlug(slug, name) }))
+      .filter(s => s.score > 0.3)
+      .sort((a, b) => b.score - a.score)
+      .slice(0, 3)
+      .map(s => s.name);
+    suggestions = scored;
+  }
+
+  return {
+    error_type: 'phase-not-found',
+    slug,
+    available,
+    suggestions
+  };
+}
+
+/**
+ * Generate alternatives for a missing-prerequisite error.
+ *
+ * @param {string} phase - The phase slug to check
+ * @param {string} planningDir - Path to .planning directory
+ * @returns {{ error_type: string, phase: string, existing_summaries: string[], missing_summaries: string[], suggested_action: string }}
+ */
+function prerequisiteAlternatives(phase, planningDir) {
+  const phasesDir = path.join(planningDir, 'phases');
+
+  // Find the phase directory (exact match or prefix match)
+  let phaseDir = null;
+  try {
+    if (fs.existsSync(phasesDir)) {
+      const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+      const match = entries.find(e => e.isDirectory() && (e.name === phase || e.name.endsWith('-' + phase) || e.name === phase));
+      if (match) {
+        phaseDir = path.join(phasesDir, match.name);
+      } else {
+        // Try exact slug match
+        const exact = path.join(phasesDir, phase);
+        if (fs.existsSync(exact)) phaseDir = exact;
+      }
+    }
+  } catch (_e) { /* best effort */ }
+
+  const existing_summaries = [];
+  const missing_summaries = [];
+
+  if (phaseDir && fs.existsSync(phaseDir)) {
+    try {
+      const files = fs.readdirSync(phaseDir);
+      const planFiles = files.filter(f => /^PLAN-\d+\.md$/i.test(f));
+
+      for (const planFile of planFiles) {
+        // Extract plan ID from filename (e.g. PLAN-01.md → look for SUMMARY-{phase-num}-01.md)
+        const match = planFile.match(/^PLAN-(\d+)\.md$/i);
+        if (!match) continue;
+        const planNum = match[1];
+
+        // Check for any SUMMARY file matching this plan number
+        const summaryFiles = files.filter(f => {
+          const sm = f.match(/^SUMMARY[-.](.*?)\.md$/i);
+          if (!sm) return false;
+          return sm[1].endsWith('-' + planNum) || sm[1] === planNum;
+        });
+
+        if (summaryFiles.length > 0) {
+          existing_summaries.push(summaryFiles[0]);
+        } else {
+          // Infer the expected plan ID from directory name prefix + plan number
+          const dirMatch = (phaseDir.split(path.sep).pop() || '').match(/^(\d+)-/);
+          const phaseNum = dirMatch ? dirMatch[1] : '';
+          const expectedId = phaseNum ? `${phaseNum}-${planNum}` : planNum;
+          missing_summaries.push(`SUMMARY-${expectedId}.md`);
+        }
+      }
+    } catch (_e) { /* best effort */ }
+  }
+
+  return {
+    error_type: 'missing-prereq',
+    phase,
+    existing_summaries,
+    missing_summaries,
+    suggested_action: `Run /pbr:build ${phase} to generate missing summaries`
+  };
+}
+
+/**
+ * Generate alternatives for a config-invalid error.
+ *
+ * @param {string} field - The config field name
+ * @param {string} value - The current invalid value
+ * @param {string} _planningDir - Path to .planning directory (unused, for API consistency)
+ * @returns {{ error_type: string, field: string, current_value: string, valid_values: Array, suggested_fix: string }}
+ */
+function configAlternatives(field, value, _planningDir) {
+  const knownValues = KNOWN_CONFIG_FIELDS[field];
+
+  if (knownValues !== undefined) {
+    // Convert to string representations for JSON output
+    const validStrings = knownValues
+      .filter(v => typeof v === 'string')
+      .filter((v, i, arr) => arr.indexOf(v) === i); // dedupe
+    return {
+      error_type: 'config-invalid',
+      field,
+      current_value: value,
+      valid_values: validStrings.length > 0 ? validStrings : knownValues.filter(v => typeof v !== 'boolean'),
+      suggested_fix: `Set ${field} to one of: ${validStrings.join(', ')}`
+    };
+  }
+
+  return {
+    error_type: 'config-invalid',
+    field,
+    current_value: value,
+    valid_values: [],
+    suggested_fix: 'Remove this field from config.json or check spelling'
+  };
+}
+
+module.exports = { phaseAlternatives, prerequisiteAlternatives, configAlternatives };

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

@@ -0,0 +1,174 @@
+'use strict';
+
+/**
+ * lib/preview.js — Dry-run preview for /pbr:build and /pbr:plan.
+ *
+ * Reads PLAN.md frontmatter from a phase directory, aggregates file lists,
+ * counts task tags, and builds a structured preview object without executing
+ * any agents or making any state changes.
+ *
+ * Exports: buildPreview(phaseSlug, options, planningDir, pluginRoot)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { parseYamlFrontmatter, findFiles } = require('./core');
+
+/**
+ * Group an array of plan objects by their wave number.
+ * Returns an array of { wave, plans, parallel } sorted ascending by wave.
+ *
+ * parallel = true when the wave contains more than one plan.
+ *
+ * @param {Array<object>} plans
+ * @returns {Array<{wave: number, plans: Array<object>, parallel: boolean}>}
+ */
+function groupByWave(plans) {
+  const waveMap = new Map();
+  for (const plan of plans) {
+    const waveNum = typeof plan.wave === 'number' ? plan.wave : 1;
+    if (!waveMap.has(waveNum)) {
+      waveMap.set(waveNum, []);
+    }
+    waveMap.get(waveNum).push(plan);
+  }
+
+  return Array.from(waveMap.entries())
+    .sort(([a], [b]) => a - b)
+    .map(([wave, wavePlans]) => ({
+      wave,
+      plans: wavePlans,
+      parallel: wavePlans.length > 1
+    }));
+}
+
+/**
+ * Build a preview object for a phase without executing any agents.
+ *
+ * @param {string} phaseSlug - Phase slug (partial match, e.g. "advanced-orchestrator-features" or "56-advanced-...")
+ * @param {object} _options  - Reserved for future options (currently unused)
+ * @param {string} planningDir - Absolute path to the .planning/ directory
+ * @param {string} _pluginRoot - Plugin root (passed for API consistency, unused here)
+ * @returns {object} Preview data or { error: string }
+ */
+function buildPreview(phaseSlug, _options, planningDir, _pluginRoot) {
+  const phasesDir = path.join(planningDir, 'phases');
+
+  // Find the phase directory
+  let phaseDir = null;
+  let phaseDirName = null;
+  try {
+    const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name === phaseSlug || entry.name.endsWith('-' + phaseSlug) || entry.name.includes(phaseSlug)) {
+        phaseDir = path.join(phasesDir, entry.name);
+        phaseDirName = entry.name;
+        break;
+      }
+    }
+  } catch (_e) {
+    return { error: `Phase not found: ${phaseSlug}` };
+  }
+
+  if (!phaseDir) {
+    return { error: `Phase not found: ${phaseSlug}` };
+  }
+
+  // Find all PLAN-*.md files
+  const planFiles = findFiles(phaseDir, /^PLAN.*\.md$/i);
+
+  if (planFiles.length === 0) {
+    return {
+      phase: phaseDirName,
+      plans: [],
+      waves: [],
+      files_affected: [],
+      agent_count: 0,
+      critical_path: [],
+      dependency_chain: []
+    };
+  }
+
+  // Parse each plan file
+  const plans = [];
+  for (const filename of planFiles) {
+    const filePath = path.join(phaseDir, filename);
+    let content = '';
+    try {
+      content = fs.readFileSync(filePath, 'utf8');
+    } catch (_e) {
+      continue;
+    }
+
+    const fm = parseYamlFrontmatter(content);
+
+    // Count task tags by matching "task id=" occurrences
+    const taskMatches = content.match(/task id=/g);
+    const taskCount = taskMatches ? taskMatches.length : 0;
+
+    // Normalize wave to a number
+    const wave = typeof fm.wave === 'number' ? fm.wave : (parseInt(fm.wave, 10) || 1);
+
+    // Normalize depends_on to an array
+    let dependsOn = fm.depends_on;
+    if (!dependsOn) {
+      dependsOn = [];
+    } else if (!Array.isArray(dependsOn)) {
+      dependsOn = [dependsOn];
+    }
+
+    // Normalize files_modified to an array
+    let filesModified = fm.files_modified;
+    if (!filesModified) {
+      filesModified = [];
+    } else if (!Array.isArray(filesModified)) {
+      filesModified = [filesModified];
+    }
+
+    plans.push({
+      id: fm.plan || filename.replace(/\.md$/i, ''),
+      wave,
+      depends_on: dependsOn,
+      files_modified: filesModified,
+      task_count: taskCount
+    });
+  }
+
+  // Group plans by wave
+  const waves = groupByWave(plans);
+
+  // Aggregate files_affected: union of all files_modified, deduplicated and sorted
+  const filesSet = new Set();
+  for (const plan of plans) {
+    for (const f of plan.files_modified) {
+      filesSet.add(f);
+    }
+  }
+  const files_affected = Array.from(filesSet).sort();
+
+  // Sum agent_count
+  const agent_count = plans.reduce((sum, p) => sum + p.task_count, 0);
+
+  // Critical path: first plan ID from each wave in order
+  const critical_path = waves.map(w => w.plans[0].id);
+
+  // Dependency chain: [{id, wave, depends_on}] for all plans
+  const dependency_chain = plans.map(p => ({
+    id: p.id,
+    wave: p.wave,
+    depends_on: p.depends_on
+  }));
+
+  return {
+    phase: phaseDirName,
+    plans,
+    waves,
+    files_affected,
+    agent_count,
+    critical_path,
+    dependency_chain
+  };
+}
+
+module.exports = { buildPreview, groupByWave };

package/plugins/pbr/scripts/lib/skill-section.js

@@ -0,0 +1,99 @@
+'use strict';
+
+/**
+ * skill-section.js — Targeted SKILL.md section extraction for Plan-Build-Run.
+ *
+ * Enables surgical extraction of specific sections from skill files (SKILL.md),
+ * reducing token usage by fetching only the needed section on demand.
+ *
+ * Exported functions:
+ *   skillSection(skillName, sectionQuery, pluginRoot)  — Main entry point
+ *   resolveSkillPath(skillName, pluginRoot)            — Resolve skill name to file path
+ *   listAvailableSkills(pluginRoot)                    — List all available skill names
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { extractSection, listHeadings } = require('./reference');
+
+/**
+ * Resolve a skill name to its SKILL.md file path.
+ *
+ * @param {string} skillName - Skill name (e.g., "build", "plan")
+ * @param {string} pluginRoot - Plugin root directory
+ * @returns {string | null} - Full path to SKILL.md, or null if not found
+ */
+function resolveSkillPath(skillName, pluginRoot) {
+  const skillPath = path.join(pluginRoot, 'skills', skillName, 'SKILL.md');
+  if (!fs.existsSync(skillPath)) return null;
+  return skillPath;
+}
+
+/**
+ * List all available skill names from the skills/ directory.
+ *
+ * @param {string} pluginRoot - Plugin root directory
+ * @returns {string[]} - Array of skill names (directory names)
+ */
+function listAvailableSkills(pluginRoot) {
+  const skillsDir = path.join(pluginRoot, 'skills');
+  try {
+    return fs.readdirSync(skillsDir, { withFileTypes: true })
+      .filter(e => e.isDirectory())
+      .map(e => e.name);
+  } catch (_e) {
+    return [];
+  }
+}
+
+/**
+ * Extract a specific section from a skill's SKILL.md.
+ *
+ * @param {string} skillName - Skill name (e.g., "build", "plan")
+ * @param {string} sectionQuery - Section heading query (fuzzy matched)
+ * @param {string} pluginRoot - Plugin root directory
+ * @returns {object} - { skill, section, heading, content, char_count } or { error, available? }
+ */
+function skillSection(skillName, sectionQuery, pluginRoot) {
+  // Validate section query
+  if (!sectionQuery || !sectionQuery.trim()) {
+    return { error: 'Section query required' };
+  }
+
+  // Resolve skill path
+  const skillPath = resolveSkillPath(skillName, pluginRoot);
+  if (!skillPath) {
+    return {
+      error: `Skill not found: ${skillName}`,
+      available: listAvailableSkills(pluginRoot)
+    };
+  }
+
+  // Read skill content
+  let content;
+  try {
+    content = fs.readFileSync(skillPath, 'utf8');
+  } catch (e) {
+    return { error: `Cannot read skill file: ${e.message}` };
+  }
+
+  // Normalize query: replace hyphens with spaces for better fuzzy matching
+  // e.g., "step-3" → "step 3" to match "Step 3: Automated Verification"
+  const normalizedQuery = sectionQuery.replace(/-/g, ' ');
+
+  // Extract the requested section (try normalized first, then original)
+  let result = extractSection(content, normalizedQuery);
+  if (!result && normalizedQuery !== sectionQuery) {
+    result = extractSection(content, sectionQuery);
+  }
+  if (!result) {
+    return {
+      error: `Section '${sectionQuery}' not found in skill '${skillName}'`,
+      available: listHeadings(content)
+    };
+  }
+
+  return { skill: skillName, section: sectionQuery, ...result };
+}
+
+module.exports = { skillSection, resolveSkillPath, listAvailableSkills };

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

@@ -0,0 +1,149 @@
+'use strict';
+
+/**
+ * lib/step-verify.js — Per-step completion checklist verifier for Plan-Build-Run.
+ *
+ * Provides stepVerify(skill, step, checklist, context) which maps checklist item
+ * strings to filesystem predicates using keyword matching and returns a structured
+ * pass/fail result.
+ *
+ * Usage (CLI via pbr-tools.js):
+ *   node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js step-verify build step-6f '["STATE.md updated","SUMMARY.md exists"]'
+ *
+ * Returns: { skill, step, passed: string[], failed: string[], all_passed: boolean }
+ * On invalid checklist: { error: 'Invalid checklist JSON' }
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+/**
+ * Match a single checklist item string to a filesystem predicate.
+ *
+ * @param {string} item - Checklist item string (e.g. "STATE.md updated")
+ * @param {object} context - { planningDir, phaseSlug, planId }
+ * @returns {{ passed: boolean, reason: string }}
+ */
+function matchPredicate(item, context) {
+  const lower = item.toLowerCase();
+  const { planningDir, phaseSlug, planId } = context;
+
+  const phasesDir = path.join(planningDir, 'phases');
+  const phaseDir = phaseSlug ? path.join(phasesDir, phaseSlug) : null;
+
+  // SUMMARY.md exists: check phaseDir for SUMMARY-{planId}.md or SUMMARY.md
+  if (lower.includes('summary') && lower.includes('exist')) {
+    if (!phaseDir) {
+      return { passed: false, reason: 'phaseSlug not provided in context' };
+    }
+    const summaryNamedPath = planId
+      ? path.join(phaseDir, `SUMMARY-${planId}.md`)
+      : null;
+    const summaryGenericPath = path.join(phaseDir, 'SUMMARY.md');
+    const exists =
+      (summaryNamedPath && fs.existsSync(summaryNamedPath)) ||
+      fs.existsSync(summaryGenericPath);
+    return {
+      passed: exists,
+      reason: exists ? 'SUMMARY file found' : 'No SUMMARY file in phase dir'
+    };
+  }
+
+  // STATE.md updated or exists: check planningDir/STATE.md
+  if (lower.includes('state') && (lower.includes('update') || lower.includes('exist'))) {
+    const statePath = path.join(planningDir, 'STATE.md');
+    const exists = fs.existsSync(statePath);
+    return {
+      passed: exists,
+      reason: exists ? 'STATE.md found' : 'STATE.md not found in planningDir'
+    };
+  }
+
+  // PLAN.md exists: check phaseDir has at least one PLAN*.md file
+  if (lower.includes('plan') && lower.includes('exist')) {
+    if (!phaseDir) {
+      return { passed: false, reason: 'phaseSlug not provided in context' };
+    }
+    let planFiles = [];
+    try {
+      planFiles = fs.readdirSync(phaseDir).filter(f => /^PLAN.*\.md$/i.test(f));
+    } catch (_e) {
+      return { passed: false, reason: 'Phase directory not accessible' };
+    }
+    const exists = planFiles.length > 0;
+    return {
+      passed: exists,
+      reason: exists ? `Found: ${planFiles.join(', ')}` : 'No PLAN*.md files in phase dir'
+    };
+  }
+
+  // ROADMAP.md updated: check planningDir/ROADMAP.md
+  if (lower.includes('roadmap') && lower.includes('update')) {
+    const roadmapPath = path.join(planningDir, 'ROADMAP.md');
+    const exists = fs.existsSync(roadmapPath);
+    return {
+      passed: exists,
+      reason: exists ? 'ROADMAP.md found' : 'ROADMAP.md not found in planningDir'
+    };
+  }
+
+  // commit made: spawn 'git log --oneline -1'; pass if stdout non-empty
+  if (lower.includes('commit')) {
+    const result = spawnSync('git', ['log', '--oneline', '-1'], {
+      encoding: 'utf8',
+      timeout: 5000
+    });
+    const output = (result.stdout || '').trim();
+    const passed = output.length > 0;
+    return {
+      passed,
+      reason: passed ? `Last commit: ${output}` : 'git log returned no output'
+    };
+  }
+
+  // No predicate matched
+  return {
+    passed: false,
+    reason: 'No predicate matched'
+  };
+}
+
+/**
+ * Verify a list of checklist items for a given skill step.
+ *
+ * @param {string} skill - Skill name (e.g. 'build')
+ * @param {string} step - Step label (e.g. 'step-6f')
+ * @param {Array<string>|*} checklist - Array of checklist item strings
+ * @param {object} context - { planningDir, phaseSlug, planId }
+ * @returns {{ skill, step, passed: string[], failed: string[], all_passed: boolean }
+ *           | { error: string }}
+ */
+function stepVerify(skill, step, checklist, context) {
+  if (!Array.isArray(checklist)) {
+    return { error: 'Invalid checklist JSON' };
+  }
+
+  const passed = [];
+  const failed = [];
+
+  for (const item of checklist) {
+    const { passed: itemPassed } = matchPredicate(item, context || {});
+    if (itemPassed) {
+      passed.push(item);
+    } else {
+      failed.push(item);
+    }
+  }
+
+  return {
+    skill,
+    step,
+    passed,
+    failed,
+    all_passed: failed.length === 0
+  };
+}
+
+// matchPredicate exported for unit testing of individual predicate branches
+module.exports = { stepVerify, matchPredicate };