@sienklogic/plan-build-run 2.12.0 → 2.12.1

package/plan-build-run/bin/lib/post-hoc.cjs

@@ -0,0 +1,160 @@
+/**
+ * lib/post-hoc.cjs — Post-hoc SUMMARY.md generation from git history.
+ *
+ * Generates SUMMARY.md artifacts by analyzing git log and diff output
+ * after task execution, enabling zero-friction quick task workflows.
+ *
+ * Exports: generateSummary, parseGitLog, buildCommitGrep
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execGit, currentTimestamp } = require('./core.cjs');
+
+/**
+ * Parse git log --oneline output into structured commit data.
+ *
+ * @param {string} logOutput - Raw output from git log --oneline
+ * @returns {Array<{hash: string, type: string, scope: string, message: string}>}
+ */
+function parseGitLog(logOutput) {
+  if (!logOutput) return [];
+
+  const lines = logOutput.trim().split('\n').filter(Boolean);
+  const conventionalRe = /^(\S+)\s+(\w+)\(([^)]*)\):\s*(.+)$/;
+
+  return lines.map(line => {
+    const match = line.match(conventionalRe);
+    if (match) {
+      return { hash: match[1], type: match[2], scope: match[3], message: match[4] };
+    }
+    // Non-conventional: extract hash and rest as message
+    const parts = line.match(/^(\S+)\s+(.+)$/);
+    if (parts) {
+      return { hash: parts[1], type: 'unknown', scope: '', message: parts[2] };
+    }
+    return { hash: '', type: 'unknown', scope: '', message: line };
+  });
+}
+
+/**
+ * Build a grep pattern for matching commits by task ID.
+ *
+ * @param {string} taskId - Task identifier (e.g., 'quick-001', '03-01')
+ * @returns {string} Grep pattern string
+ */
+function buildCommitGrep(taskId) {
+  return taskId;
+}
+
+/**
+ * Generate a SUMMARY.md from git history for a completed task.
+ *
+ * @param {string} planningDir - Path to the .planning directory (or project root for git)
+ * @param {string} taskDir - Directory to write SUMMARY.md into
+ * @param {object} [options={}] - Generation options
+ * @param {string} [options.commitPattern] - Grep pattern to match commits (default: 'quick-\\d+')
+ * @param {string} [options.since] - ISO timestamp to limit git log range
+ * @param {string} [options.description] - Task description for the summary body
+ * @returns {{status: string, path: string, commitCount: number, keyFiles: string[]}}
+ */
+function generateSummary(planningDir, taskDir, options = {}) {
+  const summaryPath = path.join(taskDir, 'SUMMARY.md');
+  const grepPattern = options.commitPattern
+    ? buildCommitGrep(options.commitPattern)
+    : 'quick-\\d+';
+  const gitCwd = planningDir;
+
+  let commits = [];
+  let keyFiles = [];
+
+  try {
+    // Get matching commits
+    const logArgs = ['log', '--oneline', '--grep=' + grepPattern];
+    if (options.since) {
+      logArgs.push('--since=' + options.since);
+    }
+    const logOutput = execGit(gitCwd, logArgs);
+    commits = parseGitLog(logOutput);
+
+    // Get changed files if commits exist
+    if (commits.length > 0) {
+      try {
+        const diffOutput = execGit(gitCwd, ['diff', '--name-only', 'HEAD~' + commits.length + '..HEAD']);
+        keyFiles = diffOutput.trim().split('\n').filter(Boolean);
+      } catch (_e) {
+        // diff may fail for single-commit repos; fall back to show
+        try {
+          const showOutput = execGit(gitCwd, ['show', '--name-only', '--format=', commits[0].hash]);
+          keyFiles = showOutput.trim().split('\n').filter(Boolean);
+        } catch (_e2) {
+          // ignore
+        }
+      }
+    }
+  } catch (_e) {
+    // git commands failed entirely (empty repo, bad revision, etc.)
+  }
+
+  const status = commits.length > 0 ? 'complete' : 'failed';
+  const commitHashes = commits.map(c => c.hash);
+  const timestamp = currentTimestamp();
+
+  // Build SUMMARY.md content
+  const frontmatter = [
+    '---',
+    'status: "' + status + '"',
+    'requires: []',
+    'key_files:',
+    ...keyFiles.map(f => '  - "' + f + '"'),
+    'deferred: []',
+    'provides: []',
+    'key_decisions: []',
+    'patterns: []',
+    'generated: "post-hoc"',
+    'commits:',
+    ...commitHashes.map(h => '  - "' + h + '"'),
+    'timestamp: "' + timestamp + '"',
+    '---',
+  ].join('\n');
+
+  const description = options.description || 'Task completed.';
+
+  const changesSection = commits.length > 0
+    ? commits.map(c => '- ' + c.type + '(' + c.scope + '): ' + c.message + ' (`' + c.hash + '`)').join('\n')
+    : 'No commits found.';
+
+  const filesSection = keyFiles.length > 0
+    ? keyFiles.map(f => '- ' + f).join('\n')
+    : 'No files changed.';
+
+  const body = [
+    '',
+    '# Summary',
+    '',
+    description,
+    '',
+    '## Changes',
+    '',
+    changesSection,
+    '',
+    '## Files Modified',
+    '',
+    filesSection,
+    '',
+  ].join('\n');
+
+  const content = frontmatter + body;
+
+  // Ensure taskDir exists
+  fs.mkdirSync(taskDir, { recursive: true });
+  fs.writeFileSync(summaryPath, content, 'utf-8');
+
+  return { status, path: summaryPath, commitCount: commits.length, keyFiles };
+}
+
+module.exports = {
+  generateSummary,
+  parseGitLog,
+  buildCommitGrep,
+};

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

@@ -0,0 +1,174 @@
+'use strict';
+
+/**
+ * lib/preview.cjs -- 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.cjs');
+
+/**
+ * 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)
+ * @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 files (matches both NN-MM-PLAN.md and legacy PLAN-NN.md naming)
+  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/plan-build-run/bin/lib/progress-visualization.cjs

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