@sienklogic/plan-build-run 2.19.0 → 2.19.2

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

@@ -0,0 +1,174 @@
+'use strict';
+
+/**
+ * lib/preview.js — Dry-run preview for /pbr:execute-phase and /pbr:plan-phase.
+ *
+ * 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/progress-visualization.js

@@ -0,0 +1,296 @@
+'use strict';
+
+/**
+ * lib/progress-visualization.cjs — Progress data, phase dependency graph, and agent activity.
+ *
+ * Provides:
+ *   getProgressData(planningDir, config)      — Combined phase graph + agent activity + summary
+ *   getPhaseDependencyGraph(planningDir)       — Phase nodes and dependency edges from ROADMAP.md
+ *   getAgentActivity(planningDir)             — Recent agent sessions from hooks.jsonl
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ─── Disabled stub ────────────────────────────────────────────────────────────
+
+const DISABLED_STUB = {
+  enabled: false,
+  phases: [],
+  dependencies: [],
+  agentActivity: [],
+};
+
+// ─── ROADMAP.md phase parsing ─────────────────────────────────────────────────
+
+/**
+ * Parse phases from ROADMAP.md content.
+ * Extracts phase headings, dependency references, and completion status.
+ *
+ * @param {string} content - Raw ROADMAP.md content
+ * @returns {Array<{id: string, name: string, status: string, goal: string, dependsOn: string[]}>}
+ */
+function parseRoadmapPhases(content) {
+  const phases = [];
+
+  // Match phase headings: ## Phase N: Name or ### Phase N: Name
+  const phaseHeadingRe = /^#{2,4}\s*Phase\s+(\d+(?:\.\d+)*)\s*:\s*([^\n]+)/gim;
+  // Match checklist items: - [x] or - [ ]
+  const checklistRe = /^[-*]\s*\[(x| )\]/im;
+  // Match depends-on lines
+  const dependsOnRe = /\*\*Depends\s+on[^:]*:\*\*\s*([^\n]+)/i;
+  const dependsOnRe2 = /Depends\s+on[^:]*:\s*([^\n]+)/i;
+
+  // Split content into phase blocks by finding heading positions
+  const headingMatches = [];
+  let m;
+  while ((m = phaseHeadingRe.exec(content)) !== null) {
+    headingMatches.push({ index: m.index, id: m[1], name: m[2].trim(), end: -1 });
+  }
+
+  for (let i = 0; i < headingMatches.length; i++) {
+    const start = headingMatches[i].index;
+    const end = i + 1 < headingMatches.length ? headingMatches[i + 1].index : content.length;
+    const block = content.slice(start, end);
+
+    // Check completion status from checklist items
+    const checkMatches = block.match(/^[-*]\s*\[(x| )\]/gim) || [];
+    const totalChecks = checkMatches.length;
+    const doneChecks = checkMatches.filter(c => c.includes('[x]') || c.includes('[X]')).length;
+
+    let status = 'planned';
+    if (totalChecks > 0) {
+      if (doneChecks === totalChecks) status = 'completed';
+      else if (doneChecks > 0) status = 'in-progress';
+      else status = 'planned';
+    }
+
+    // Extract depends-on references
+    const depMatch = block.match(dependsOnRe) || block.match(dependsOnRe2);
+    const dependsOn = [];
+    if (depMatch) {
+      const depText = depMatch[1];
+      const depNums = depText.match(/\d+(?:\.\d+)*/g) || [];
+      dependsOn.push(...depNums);
+    }
+
+    // Extract goal (first non-heading, non-empty line after heading)
+    const blockLines = block.split('\n').slice(1).map(l => l.trim()).filter(Boolean);
+    const goalLine = blockLines.find(l => !l.startsWith('#') && !l.startsWith('-') && !l.startsWith('*') && !l.startsWith('**Depends'));
+    const goal = goalLine ? goalLine.replace(/^\*+|\*+$/g, '').trim() : '';
+
+    phases.push({
+      id: headingMatches[i].id,
+      name: headingMatches[i].name,
+      status,
+      goal,
+      dependsOn,
+    });
+  }
+
+  return phases;
+}
+
+// ─── Phase dependency graph ────────────────────────────────────────────────────
+
+/**
+ * Build a phase dependency graph from ROADMAP.md.
+ *
+ * @param {string} planningDir - Path to .planning/ directory
+ * @returns {{ nodes: Array, edges: Array }}
+ */
+function getPhaseDependencyGraph(planningDir) {
+  const roadmapPath = path.join(planningDir, 'ROADMAP.md');
+
+  if (!fs.existsSync(roadmapPath)) {
+    return { nodes: [], edges: [] };
+  }
+
+  const content = fs.readFileSync(roadmapPath, 'utf8');
+  const phases = parseRoadmapPhases(content);
+
+  const nodes = phases.map(p => ({
+    id: p.id,
+    name: p.name,
+    status: p.status,
+    goal: p.goal,
+  }));
+
+  const edges = [];
+  for (const phase of phases) {
+    for (const depId of phase.dependsOn) {
+      edges.push({ from: depId, to: phase.id });
+    }
+  }
+
+  return { nodes, edges };
+}
+
+// ─── Agent activity ────────────────────────────────────────────────────────────
+
+/**
+ * Read recent agent sessions from hooks.jsonl.
+ * Pairs start/stop events by sessionId, computes duration.
+ *
+ * @param {string} planningDir - Path to .planning/ directory
+ * @returns {Array<{agent: string, startTime: string, endTime: string|null, duration: number|null, status: string}>}
+ */
+function getAgentActivity(planningDir) {
+  const hooksLog = path.join(planningDir, 'logs', 'hooks.jsonl');
+
+  if (!fs.existsSync(hooksLog)) {
+    return [];
+  }
+
+  let lines;
+  try {
+    lines = fs.readFileSync(hooksLog, 'utf8').split('\n').filter(Boolean);
+  } catch (_e) {
+    return [];
+  }
+
+  // Parse only log-subagent entries
+  const entries = [];
+  for (const line of lines) {
+    try {
+      const entry = JSON.parse(line);
+      if (entry.hook === 'log-subagent' || entry.type === 'subagent') {
+        entries.push(entry);
+      }
+    } catch (_e) {
+      // Skip malformed lines
+    }
+  }
+
+  // Pair start/stop by sessionId
+  const sessions = new Map();
+  for (const entry of entries) {
+    const sid = entry.sessionId || entry.session_id || entry.id;
+    if (!sid) continue;
+
+    if (entry.event === 'start') {
+      sessions.set(sid, {
+        agent: entry.agent || entry.agentType || 'unknown',
+        startTime: entry.timestamp,
+        endTime: null,
+        duration: null,
+        status: 'running',
+      });
+    } else if (entry.event === 'stop') {
+      if (sessions.has(sid)) {
+        const session = sessions.get(sid);
+        session.endTime = entry.timestamp;
+        session.status = entry.exitCode === 0 ? 'success' : 'failed';
+        if (session.startTime && session.endTime) {
+          const start = new Date(session.startTime).getTime();
+          const end = new Date(session.endTime).getTime();
+          if (!isNaN(start) && !isNaN(end)) {
+            session.duration = Math.round((end - start) / 1000);
+          }
+        }
+      } else {
+        // Got a stop without a start — add partial entry
+        sessions.set(sid, {
+          agent: entry.agent || entry.agentType || 'unknown',
+          startTime: null,
+          endTime: entry.timestamp,
+          duration: null,
+          status: entry.exitCode === 0 ? 'success' : 'failed',
+        });
+      }
+    }
+  }
+
+  // Sort by startTime descending, limit to 50
+  const result = Array.from(sessions.values())
+    .sort((a, b) => {
+      const ta = a.startTime ? new Date(a.startTime).getTime() : 0;
+      const tb = b.startTime ? new Date(b.startTime).getTime() : 0;
+      return tb - ta;
+    })
+    .slice(0, 50);
+
+  return result;
+}
+
+// ─── Combined progress data ────────────────────────────────────────────────────
+
+/**
+ * Get combined progress data: phase graph + agent activity + summary stats.
+ *
+ * @param {string} planningDir - Path to .planning/ directory
+ * @param {object|null} config  - Parsed config object (or null)
+ * @returns {object} Progress data or disabled stub
+ */
+function getProgressData(planningDir, config) {
+  const features = (config && config.features) || {};
+
+  // Check feature toggle (default: enabled)
+  if (features.progress_visualization === false) {
+    return { ...DISABLED_STUB };
+  }
+
+  const { nodes, edges } = getPhaseDependencyGraph(planningDir);
+  const agentActivity = getAgentActivity(planningDir);
+
+  const total = nodes.length;
+  const completed = nodes.filter(n => n.status === 'completed').length;
+  const inProgress = nodes.filter(n => n.status === 'in-progress').length;
+  const percentComplete = total > 0 ? Math.round((completed / total) * 100) : 0;
+
+  // Log audit evidence
+  logAuditEvidence(planningDir, 'progress_visualization', 'ok');
+
+  return {
+    enabled: true,
+    phases: nodes,
+    dependencies: edges,
+    agentActivity,
+    summary: {
+      total,
+      completed,
+      inProgress,
+      percentComplete,
+    },
+  };
+}
+
+// ─── Audit evidence ────────────────────────────────────────────────────────────
+
+/**
+ * Append an audit evidence entry to .planning/logs/hooks.jsonl.
+ * Used to provide evidence that Phase 15 features are active.
+ *
+ * @param {string} planningDir - Path to .planning/ directory
+ * @param {string} feature     - Feature name (e.g., "progress_visualization")
+ * @param {string} result      - "ok" or "error"
+ */
+function logAuditEvidence(planningDir, feature, result) {
+  try {
+    const logsDir = path.join(planningDir, 'logs');
+    if (!fs.existsSync(logsDir)) {
+      fs.mkdirSync(logsDir, { recursive: true });
+    }
+    const logPath = path.join(logsDir, 'hooks.jsonl');
+    const entry = JSON.stringify({
+      timestamp: new Date().toISOString(),
+      hook: 'dx-progress',
+      type: 'audit',
+      feature,
+      result,
+    });
+    fs.appendFileSync(logPath, entry + '\n');
+  } catch (_e) {
+    // Never throw from audit logging
+  }
+}
+
+// ─── Exports ──────────────────────────────────────────────────────────────────
+
+module.exports = {
+  getProgressData,
+  getPhaseDependencyGraph,
+  getAgentActivity,
+  logAuditEvidence,
+  parseRoadmapPhases,
+};

package/plugins/pbr/scripts/lib/quick-init.js

@@ -0,0 +1,131 @@
+/**
+ * lib/quick-init.js — Quick task directory creation and PLAN.md generation.
+ *
+ * Fixes the #1 documented PBR failure mode: LLM skipping directory creation
+ * under cognitive load. This command atomically creates the directory and
+ * writes PLAN.md so the skill doesn't have to.
+ *
+ * Usage:
+ *   node pbr-tools.js quick init "fix the auth bug in login flow"
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Articles and short prepositions to strip from slugs
+const STOP_WORDS = new Set([
+  'a', 'an', 'the', 'of', 'in', 'for', 'to', 'on', 'at', 'by', 'with',
+  'and', 'or', 'but', 'is', 'it', 'its', 'be', 'as', 'do', 'so', 'up'
+]);
+
+/**
+ * Generate a smart slug from a description.
+ * Removes articles/prepositions, keeps first 4-5 meaningful words, max 50 chars.
+ *
+ * @param {string} text - Description text
+ * @returns {string} Hyphenated slug
+ */
+function generateQuickSlug(text) {
+  if (!text || !text.trim()) return 'task';
+
+  const words = text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, '')
+    .split(/\s+/)
+    .filter(w => w && !STOP_WORDS.has(w));
+
+  if (words.length === 0) return 'task';
+
+  // Take first 5 meaningful words, then trim to 50 chars
+  const slug = words.slice(0, 5).join('-');
+  if (slug.length <= 50) return slug;
+
+  // Trim at last hyphen before 50 chars
+  const trimmed = slug.substring(0, 50);
+  const lastHyphen = trimmed.lastIndexOf('-');
+  return lastHyphen > 0 ? trimmed.substring(0, lastHyphen) : trimmed;
+}
+
+/**
+ * Create a quick task directory and write PLAN.md.
+ *
+ * @param {string} description - Task description
+ * @param {string} planningDir - Absolute path to .planning/ directory
+ * @returns {object} JSON result with number, slug, dir, plan_path, task_id — or {error}
+ */
+function quickInit(description, planningDir) {
+  // Validate inputs
+  if (!description || !description.trim()) {
+    return { error: 'Description required' };
+  }
+
+  if (!fs.existsSync(planningDir)) {
+    return { error: 'No .planning/ directory. Run /pbr:begin first.' };
+  }
+
+  const quickDir = path.join(planningDir, 'quick');
+
+  // Scan for highest existing task number
+  let nextNum = 1;
+  if (fs.existsSync(quickDir)) {
+    const dirs = fs.readdirSync(quickDir)
+      .filter(d => /^\d{3}-/.test(d))
+      .sort();
+    if (dirs.length > 0) {
+      nextNum = parseInt(dirs[dirs.length - 1].substring(0, 3), 10) + 1;
+    }
+  } else {
+    // Create .planning/quick/ if it doesn't exist
+    fs.mkdirSync(quickDir, { recursive: true });
+  }
+
+  const paddedNum = String(nextNum).padStart(3, '0');
+  const slug = generateQuickSlug(description);
+  const dirName = `${paddedNum}-${slug}`;
+  const taskDir = path.join(quickDir, dirName);
+  const taskId = `quick-${paddedNum}`;
+
+  // Create the task directory
+  fs.mkdirSync(taskDir, { recursive: true });
+
+  // Write PLAN.md
+  const planContent = [
+    '---',
+    `task_id: "${taskId}"`,
+    `description: "${description.replace(/"/g, '\\"')}"`,
+    `created: "${new Date().toISOString()}"`,
+    'status: planned',
+    '---',
+    '',
+    `# Quick Task: ${description}`,
+    '',
+    '## Objective',
+    '',
+    description,
+    '',
+    '## Tasks',
+    '',
+    '- [ ] Implement the change',
+    '- [ ] Verify it works',
+    '- [ ] Commit with conventional format',
+    ''
+  ].join('\n');
+
+  const planPath = path.join(taskDir, 'PLAN.md');
+  fs.writeFileSync(planPath, planContent, 'utf8');
+
+  // Return relative paths (as the spec shows)
+  const relDir = path.join('.planning', 'quick', dirName);
+  return {
+    number: paddedNum,
+    slug: slug,
+    dir: relDir,
+    plan_path: path.join(relDir, 'PLAN.md'),
+    task_id: taskId
+  };
+}
+
+module.exports = {
+  quickInit,
+  generateQuickSlug
+};