@sienklogic/plan-build-run 2.11.0 → 2.12.1

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/smart-next-task.js

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+
+/**
+ * Smart next-task suggestion module.
+ *
+ * Parses ROADMAP.md dependency graph and STATE.md to suggest
+ * the highest-impact next task based on critical path analysis.
+ *
+ * Pure function — no side effects, no file writes.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Parse ROADMAP.md into phase objects with dependencies and completion status.
+ * @param {string} content - ROADMAP.md content
+ * @returns {{ phases: Map<number, { name: string, dependsOn: number[], completed: boolean }> }}
+ */
+function parseRoadmap(content) {
+  const phases = new Map();
+
+  // Parse phase sections: ### Phase N: Name
+  const sectionRegex = /### Phase (\d+):\s*(.+)/g;
+  let match;
+  while ((match = sectionRegex.exec(content)) !== null) {
+    const num = parseInt(match[1], 10);
+    const name = match[2].trim();
+    phases.set(num, { name, dependsOn: [], completed: false });
+  }
+
+  // Parse dependencies: **Depends on:** Phase N, Phase M
+  // We need to associate each dependency with its phase section
+  const lines = content.split('\n');
+  let currentPhase = null;
+  for (const line of lines) {
+    const phaseMatch = line.match(/### Phase (\d+):/);
+    if (phaseMatch) {
+      currentPhase = parseInt(phaseMatch[1], 10);
+    }
+    const depMatch = line.match(/\*\*Depends on:\*\*\s*(.+)/);
+    if (depMatch && currentPhase !== null && phases.has(currentPhase)) {
+      const depStr = depMatch[1].trim();
+      if (depStr.toLowerCase() !== 'none') {
+        const depNums = [];
+        const depNumRegex = /Phase\s+(\d+)/gi;
+        let depNumMatch;
+        while ((depNumMatch = depNumRegex.exec(depStr)) !== null) {
+          depNums.push(parseInt(depNumMatch[1], 10));
+        }
+        phases.get(currentPhase).dependsOn = depNums;
+      }
+    }
+  }
+
+  // Parse completion status from checklist: - [x] Phase N:
+  const checkRegex = /- \[(x| )\]\s*Phase\s+(\d+):/gi;
+  while ((match = checkRegex.exec(content)) !== null) {
+    const completed = match[1].toLowerCase() === 'x';
+    const num = parseInt(match[2], 10);
+    if (phases.has(num)) {
+      phases.get(num).completed = completed;
+    }
+  }
+
+  return phases;
+}
+
+/**
+ * Parse STATE.md frontmatter for current phase info.
+ * @param {string} content - STATE.md content
+ * @returns {{ current_phase: number, status: string, plans_total: number, plans_complete: number }}
+ */
+function parseState(content) {
+  const result = { current_phase: 0, status: '', plans_total: 0, plans_complete: 0 };
+  const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!fmMatch) return result;
+
+  const fm = fmMatch[1];
+  const phaseMatch = fm.match(/current_phase:\s*(\d+)/);
+  if (phaseMatch) result.current_phase = parseInt(phaseMatch[1], 10);
+
+  const statusMatch = fm.match(/status:\s*"?(\w+)"?/);
+  if (statusMatch) result.status = statusMatch[1];
+
+  const totalMatch = fm.match(/plans_total:\s*(\d+)/);
+  if (totalMatch) result.plans_total = parseInt(totalMatch[1], 10);
+
+  const completeMatch = fm.match(/plans_complete:\s*(\d+)/);
+  if (completeMatch) result.plans_complete = parseInt(completeMatch[1], 10);
+
+  return result;
+}
+
+/**
+ * Count transitive downstream dependents for a phase.
+ * @param {Map} phases - Parsed phases map
+ * @param {number} phaseNum - Phase number to count dependents for
+ * @returns {number} Count of transitive downstream dependents
+ */
+function countDownstream(phases, phaseNum) {
+  const visited = new Set();
+  const queue = [phaseNum];
+
+  while (queue.length > 0) {
+    const current = queue.shift();
+    for (const [num, phase] of phases) {
+      if (!visited.has(num) && num !== phaseNum && phase.dependsOn.includes(current)) {
+        visited.add(num);
+        queue.push(num);
+      }
+    }
+  }
+
+  return visited.size;
+}
+
+/**
+ * Suggest the highest-impact next task based on ROADMAP.md dependency graph.
+ *
+ * @param {string} planningDir - Absolute path to .planning/ directory
+ * @returns {{ phase: number, name: string, reason: string, command: string } | null}
+ */
+function suggestNextTask(planningDir) {
+  // Read ROADMAP.md
+  const roadmapPath = path.join(planningDir, 'ROADMAP.md');
+  if (!fs.existsSync(roadmapPath)) return null;
+
+  let roadmapContent;
+  try {
+    roadmapContent = fs.readFileSync(roadmapPath, 'utf8');
+  } catch (_e) {
+    return null;
+  }
+
+  const phases = parseRoadmap(roadmapContent);
+  if (phases.size === 0) return null;
+
+  // Read STATE.md
+  const statePath = path.join(planningDir, 'STATE.md');
+  let state = { current_phase: 0, status: '', plans_total: 0, plans_complete: 0 };
+  try {
+    const stateContent = fs.readFileSync(statePath, 'utf8');
+    state = parseState(stateContent);
+  } catch (_e) {
+    // No state file — proceed with defaults
+  }
+
+  // Terminal states where the current phase is done — skip to next phase suggestion
+  const terminalStatuses = ['verified', 'complete', 'skipped', 'reviewed', 'milestone_complete'];
+
+  // If current phase is in-progress, suggest the appropriate next action
+  if (state.current_phase > 0 && state.status && !terminalStatuses.includes(state.status)) {
+    const currentPhaseData = phases.get(state.current_phase);
+    if (currentPhaseData && !currentPhaseData.completed) {
+      // Map status to appropriate command suggestion
+      let command = '/pbr:build';
+      let reason = 'Current phase in progress — continue building';
+
+      if (state.status === 'ready_to_plan' || state.status === 'discussed' || state.status === 'not_started') {
+        command = `/pbr:plan-phase ${state.current_phase}`;
+        reason = 'Current phase needs planning';
+      } else if (state.status === 'needs_fixes') {
+        command = '/pbr:build';
+        reason = 'Current phase needs fixes — continue building';
+      } else if (state.status === 'built') {
+        command = `/pbr:verify-work ${state.current_phase}`;
+        reason = 'Current phase built — verify before advancing';
+      }
+
+      return {
+        phase: state.current_phase,
+        name: currentPhaseData.name,
+        reason,
+        command
+      };
+    }
+  }
+
+  // Check if all phases are completed
+  const allCompleted = Array.from(phases.values()).every(p => p.completed);
+  if (allCompleted) return null;
+
+  // Find unblocked phases: not completed AND all dependencies completed
+  const unblocked = [];
+  for (const [num, phase] of phases) {
+    if (phase.completed) continue;
+    const allDepsCompleted = phase.dependsOn.every(dep => {
+      const depPhase = phases.get(dep);
+      return depPhase && depPhase.completed;
+    });
+    if (allDepsCompleted) {
+      unblocked.push(num);
+    }
+  }
+
+  if (unblocked.length === 0) return null;
+
+  // Rank by critical path weight (most downstream dependents)
+  let bestPhase = unblocked[0];
+  let bestWeight = countDownstream(phases, unblocked[0]);
+
+  for (let i = 1; i < unblocked.length; i++) {
+    const weight = countDownstream(phases, unblocked[i]);
+    if (weight > bestWeight) {
+      bestWeight = weight;
+      bestPhase = unblocked[i];
+    }
+  }
+
+  const phaseData = phases.get(bestPhase);
+  const downstreamCount = bestWeight;
+  const reason = downstreamCount > 0
+    ? `Critical path: ${downstreamCount} downstream phase${downstreamCount > 1 ? 's' : ''} depend on this`
+    : 'Next available phase with no blockers';
+
+  return {
+    phase: bestPhase,
+    name: phaseData.name,
+    reason,
+    command: `/pbr:plan-phase ${bestPhase}`
+  };
+}
+
+module.exports = { suggestNextTask, parseRoadmap, parseState, countDownstream };

package/plugins/pbr/scripts/lib/snapshot-manager.js

@@ -0,0 +1,225 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const MAX_SNAPSHOTS = 10;
+
+/**
+ * Parse YAML frontmatter and body from snapshot file content.
+ */
+function parseSnapshotFile(content) {
+  const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
+  if (!fmMatch) return { frontmatter: {}, body: content };
+
+  const frontmatter = {};
+  for (const line of fmMatch[1].split(/\r?\n/)) {
+    const colonIdx = line.indexOf(':');
+    if (colonIdx > 0) {
+      const key = line.slice(0, colonIdx).trim();
+      let val = line.slice(colonIdx + 1).trim();
+      // Strip quotes
+      if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+        val = val.slice(1, -1);
+      }
+      // Parse numbers
+      if (/^\d+$/.test(val)) {
+        frontmatter[key] = parseInt(val, 10);
+      } else {
+        frontmatter[key] = val;
+      }
+    }
+  }
+
+  return { frontmatter, body: fmMatch[2] };
+}
+
+/**
+ * Parse section content from markdown body.
+ */
+function parseSections(body) {
+  const sections = {};
+  const sectionRegex = /^## (.+)$/gm;
+  const matches = [];
+  let match;
+
+  while ((match = sectionRegex.exec(body)) !== null) {
+    matches.push({ title: match[1], index: match.index + match[0].length });
+  }
+
+  for (let i = 0; i < matches.length; i++) {
+    const start = matches[i].index;
+    const end = i + 1 < matches.length ? matches[i + 1].index - matches[i + 1].title.length - 3 : body.length;
+    const content = body.slice(start, end).trim();
+    const items = content.split(/\r?\n/)
+      .filter(l => l.startsWith('- '))
+      .map(l => l.slice(2).trim());
+    sections[matches[i].title] = items.length > 0 ? items : content;
+  }
+
+  return sections;
+}
+
+/**
+ * Prune snapshots directory to keep only the newest MAX_SNAPSHOTS files.
+ */
+function pruneSnapshots(snapDir) {
+  let files;
+  try {
+    files = fs.readdirSync(snapDir)
+      .filter(f => f.endsWith('-snapshot.md'))
+      .sort();
+  } catch (_e) {
+    return;
+  }
+
+  while (files.length > MAX_SNAPSHOTS) {
+    const oldest = files.shift();
+    try {
+      fs.unlinkSync(path.join(snapDir, oldest));
+    } catch (_e) { /* ignore */ }
+  }
+}
+
+/**
+ * Write a mental model snapshot to .planning/sessions/snapshots/.
+ * @param {string} planningDir - Path to .planning directory
+ * @param {object} context - Snapshot context
+ */
+function writeSnapshot(planningDir, context) {
+  const snapDir = path.join(planningDir, 'sessions', 'snapshots');
+  fs.mkdirSync(snapDir, { recursive: true });
+
+  const now = new Date();
+  const timestamp = now.toISOString();
+  // Replace colons with hyphens for Windows compat in filename
+  const fileTs = timestamp.replace(/:/g, '-').replace(/\.\d+Z$/, '');
+  const fileName = `${fileTs}-snapshot.md`;
+
+  const filesWorkingOn = context.files_working_on || [];
+  const pendingDecisions = context.pending_decisions || [];
+  const openQuestions = context.open_questions || [];
+  const recentCommits = context.recent_commits || [];
+  const currentApproach = context.current_approach || '';
+
+  const lines = [
+    '---',
+    `timestamp: "${timestamp}"`,
+    `session_id: "${context.session_id || 'unknown'}"`,
+    `files_count: ${filesWorkingOn.length}`,
+    '---',
+    '',
+    '## Working Set',
+    ...filesWorkingOn.map(f => `- ${f}`),
+    '',
+    '## Current Approach',
+    currentApproach,
+    '',
+    '## Pending Decisions',
+    ...(pendingDecisions.length > 0 ? pendingDecisions.map(d => `- ${d}`) : ['None']),
+    '',
+    '## Open Questions',
+    ...(openQuestions.length > 0 ? openQuestions.map(q => `- ${q}`) : ['None']),
+    '',
+    '## Recent Commits',
+    ...(recentCommits.length > 0 ? recentCommits.map(c => `- ${c}`) : ['None']),
+    '',
+  ];
+
+  fs.writeFileSync(path.join(snapDir, fileName), lines.join('\n'));
+
+  // Prune to max snapshots
+  pruneSnapshots(snapDir);
+}
+
+/**
+ * Load the most recent snapshot from .planning/sessions/snapshots/.
+ * @param {string} planningDir - Path to .planning directory
+ * @returns {object|null} Snapshot data or null
+ */
+function loadLatestSnapshot(planningDir) {
+  const snapDir = path.join(planningDir, 'sessions', 'snapshots');
+  if (!fs.existsSync(snapDir)) return null;
+
+  let files;
+  try {
+    files = fs.readdirSync(snapDir)
+      .filter(f => f.endsWith('-snapshot.md'))
+      .sort();
+  } catch (_e) {
+    return null;
+  }
+
+  if (files.length === 0) return null;
+
+  const latestFile = files[files.length - 1];
+  const content = fs.readFileSync(path.join(snapDir, latestFile), 'utf8');
+  const { frontmatter, body } = parseSnapshotFile(content);
+  const sections = parseSections(body);
+
+  return {
+    timestamp: frontmatter.timestamp || null,
+    session_id: frontmatter.session_id || null,
+    files_working_on: Array.isArray(sections['Working Set']) ? sections['Working Set'] : [],
+    current_approach: typeof sections['Current Approach'] === 'string' ? sections['Current Approach'] : '',
+    pending_decisions: Array.isArray(sections['Pending Decisions']) ? sections['Pending Decisions'].filter(d => d !== 'None') : [],
+    open_questions: Array.isArray(sections['Open Questions']) ? sections['Open Questions'].filter(q => q !== 'None') : [],
+    recent_commits: Array.isArray(sections['Recent Commits']) ? sections['Recent Commits'].filter(c => c !== 'None') : [],
+  };
+}
+
+/**
+ * Format a snapshot into a concise briefing text.
+ * @param {object|null} snapshot - Output from loadLatestSnapshot
+ * @returns {string} Briefing text, capped at 1200 chars
+ */
+function formatSnapshotBriefing(snapshot) {
+  if (!snapshot) return '';
+
+  const lines = [];
+
+  // Relative time
+  let timeAgo = '';
+  if (snapshot.timestamp) {
+    const diffMs = Date.now() - new Date(snapshot.timestamp).getTime();
+    const diffMin = Math.floor(diffMs / 60000);
+    if (diffMin < 60) {
+      timeAgo = `${diffMin}m ago`;
+    } else if (diffMin < 1440) {
+      timeAgo = `${Math.floor(diffMin / 60)}h ago`;
+    } else {
+      timeAgo = `${Math.floor(diffMin / 1440)}d ago`;
+    }
+  }
+
+  lines.push(`Last session${timeAgo ? ` (${timeAgo})` : ''}:`);
+
+  const files = snapshot.files_working_on || [];
+  if (files.length > 0) {
+    const shown = files.slice(0, 3).join(', ');
+    const suffix = files.length > 3 ? ` (+${files.length - 3} more)` : '';
+    lines.push(`- Working on: ${shown}${suffix} (${files.length} files)`);
+  }
+
+  if (snapshot.current_approach) {
+    const approach = snapshot.current_approach.length > 100
+      ? snapshot.current_approach.slice(0, 100) + '...'
+      : snapshot.current_approach;
+    lines.push(`- Approach: ${approach}`);
+  }
+
+  const decisions = snapshot.pending_decisions || [];
+  const questions = snapshot.open_questions || [];
+  if (decisions.length > 0 || questions.length > 0) {
+    lines.push(`- Pending: ${decisions.length} decisions, ${questions.length} open questions`);
+  }
+
+  let result = lines.join('\n');
+  if (result.length > 1200) {
+    result = result.slice(0, 1197) + '...';
+  }
+
+  return result;
+}
+
+module.exports = { writeSnapshot, loadLatestSnapshot, formatSnapshotBriefing };