@sienklogic/plan-build-run 2.45.0 → 2.47.0

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

@@ -0,0 +1,218 @@
+'use strict';
+
+/**
+ * lib/context.js — Context triage for orchestrator decision-making.
+ *
+ * Provides contextTriage() which reads data from the context-bridge and
+ * context-tracker files to return a concrete PROCEED / CHECKPOINT / COMPACT
+ * recommendation, replacing vague LLM self-assessment with data-driven logic.
+ *
+ * Data sources (in priority order):
+ *   1. .context-budget.json   — written by context-bridge.js, contains real % from Claude
+ *   2. .context-tracker       — written by track-context-budget.js, heuristic char count
+ *
+ * Decision thresholds:
+ *   Bridge (fresh):   < 50% → PROCEED, 50-70% → CHECKPOINT, > 70% → COMPACT
+ *   Heuristic:        < 30k → PROCEED, 30k-60k → CHECKPOINT, > 60k → COMPACT
+ *
+ * Adjustments:
+ *   Near completion (agentsDone/plansTotal > 0.8): relax one tier
+ *   currentStep contains "finalize" or "cleanup":  always PROCEED
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const BRIDGE_STALENESS_MS = 60 * 1000; // 60 seconds
+
+/**
+ * Read and parse .context-budget.json.
+ * @param {string} planningDir
+ * @returns {{ percentage: number, tier: string, timestamp: string, chars_read: number, stale: boolean } | null}
+ */
+function readBridgeData(planningDir) {
+  const bridgePath = path.join(planningDir, '.context-budget.json');
+  try {
+    const stat = fs.statSync(bridgePath);
+    const content = fs.readFileSync(bridgePath, 'utf8');
+    const data = JSON.parse(content);
+    const ageMs = Date.now() - stat.mtimeMs;
+    data.stale = ageMs > BRIDGE_STALENESS_MS;
+    return data;
+  } catch (_e) {
+    return null;
+  }
+}
+
+/**
+ * Read and parse .context-tracker.
+ * @param {string} planningDir
+ * @returns {{ total_chars: number, unique_files: number } | null}
+ */
+function readTrackerData(planningDir) {
+  const trackerPath = path.join(planningDir, '.context-tracker');
+  try {
+    const content = fs.readFileSync(trackerPath, 'utf8');
+    return JSON.parse(content);
+  } catch (_e) {
+    return null;
+  }
+}
+
+/**
+ * Apply near-completion relaxation: relax CHECKPOINT → PROCEED or COMPACT → CHECKPOINT.
+ * @param {string} recommendation
+ * @returns {string} Possibly relaxed recommendation
+ */
+function relaxTier(recommendation) {
+  if (recommendation === 'CHECKPOINT') return 'PROCEED';
+  if (recommendation === 'COMPACT') return 'CHECKPOINT';
+  return recommendation;
+}
+
+/**
+ * Main context triage function.
+ *
+ * @param {Object} options
+ * @param {number} [options.agentsDone]   — How many agents/plans have completed
+ * @param {number} [options.plansTotal]   — Total plans in current phase
+ * @param {string} [options.currentStep]  — Name/description of the current step
+ * @param {string} [planningDir]          — Override .planning/ directory path
+ * @returns {{
+ *   recommendation: 'PROCEED'|'CHECKPOINT'|'COMPACT',
+ *   reason: string,
+ *   data_source: 'bridge'|'heuristic'|'stale_bridge',
+ *   percentage: number|null,
+ *   tier: string|null,
+ *   agents_done: number|null,
+ *   plans_total: number|null
+ * }}
+ */
+function contextTriage(options, planningDir) {
+  options = options || {};
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+  const pd = planningDir || path.join(cwd, '.planning');
+
+  const agentsDone = (typeof options.agentsDone === 'number' && !isNaN(options.agentsDone))
+    ? options.agentsDone : null;
+  const plansTotal = (typeof options.plansTotal === 'number' && !isNaN(options.plansTotal))
+    ? options.plansTotal : null;
+  const currentStep = options.currentStep || '';
+
+  // Cleanup/finalize override — always PROCEED
+  const isCleanup = /finalize|cleanup/i.test(currentStep);
+
+  // Read data sources
+  const bridge = readBridgeData(pd);
+  const tracker = readTrackerData(pd);
+
+  let recommendation;
+  let dataSource;
+  let percentage = null;
+  let tier = null;
+
+  if (bridge && !bridge.stale) {
+    // Fresh bridge data — authoritative
+    dataSource = 'bridge';
+    percentage = typeof bridge.percentage === 'number' ? bridge.percentage : null;
+    tier = bridge.tier || null;
+
+    if (percentage === null) {
+      // Bridge exists but has no percentage — fall through to heuristic
+      dataSource = 'heuristic';
+    } else if (percentage < 50) {
+      recommendation = 'PROCEED';
+    } else if (percentage <= 70) {
+      recommendation = 'CHECKPOINT';
+    } else {
+      recommendation = 'COMPACT';
+    }
+  }
+
+  if (!recommendation) {
+    // Stale bridge or missing bridge — use heuristic
+    if (bridge && bridge.stale) {
+      dataSource = 'stale_bridge';
+      // Use stale percentage as a hint for tier/percentage display
+      percentage = typeof bridge.percentage === 'number' ? bridge.percentage : null;
+      tier = bridge.tier || null;
+    } else {
+      dataSource = 'heuristic';
+    }
+
+    const totalChars = tracker && typeof tracker.total_chars === 'number'
+      ? tracker.total_chars : 0;
+
+    if (totalChars < 30000) {
+      recommendation = 'PROCEED';
+    } else if (totalChars <= 60000) {
+      recommendation = 'CHECKPOINT';
+    } else {
+      recommendation = 'COMPACT';
+    }
+
+    // Use tracker chars to estimate a pseudo-percentage for heuristic source
+    if (dataSource === 'heuristic' && percentage === null) {
+      // Map 0-100k chars to 0-100% for display purposes
+      percentage = Math.min(100, Math.round((totalChars / 100000) * 100));
+      tier = percentage < 30 ? 'PEAK'
+        : percentage < 50 ? 'GOOD'
+          : percentage < 70 ? 'DEGRADING'
+            : percentage < 85 ? 'POOR'
+              : 'CRITICAL';
+    }
+  }
+
+  // Cleanup override — before near-completion so it always wins
+  if (isCleanup) {
+    recommendation = 'PROCEED';
+  } else {
+    // Near-completion adjustment
+    const nearComplete = agentsDone !== null && plansTotal !== null && plansTotal > 0
+      && (agentsDone / plansTotal) > 0.8;
+    if (nearComplete) {
+      recommendation = relaxTier(recommendation);
+    }
+  }
+
+  // Build human-readable reason
+  const pctStr = percentage !== null ? `${percentage}%` : 'unknown';
+  const tierStr = tier || 'unknown';
+
+  let reason;
+  if (dataSource === 'bridge') {
+    reason = `Context at ${pctStr} (${tierStr} tier).`;
+  } else if (dataSource === 'stale_bridge') {
+    reason = `Bridge data is stale (>60s old). Using heuristic fallback. Last known: ${pctStr} (${tierStr}).`;
+  } else {
+    const charsStr = tracker ? `${Math.round((tracker.total_chars || 0) / 1000)}k chars read` : 'no read data';
+    reason = `No bridge data. Heuristic: ${charsStr} (estimated ${pctStr}).`;
+  }
+
+  if (agentsDone !== null && plansTotal !== null) {
+    reason += ` ${agentsDone} of ${plansTotal} plans complete.`;
+  }
+
+  if (isCleanup) {
+    reason += ' Cleanup/finalize step — not interrupting.';
+  } else if (agentsDone !== null && plansTotal !== null && plansTotal > 0 && (agentsDone / plansTotal) > 0.8) {
+    reason += ' Near completion — threshold relaxed.';
+  }
+
+  const safeLabel = recommendation === 'PROCEED' ? 'Safe to continue.'
+    : recommendation === 'CHECKPOINT' ? 'Suggest /pbr:pause after current agent completes.'
+      : 'Suggest running /compact immediately.';
+  reason += ' ' + safeLabel;
+
+  return {
+    recommendation,
+    reason,
+    data_source: dataSource,
+    percentage,
+    tier,
+    agents_done: agentsDone,
+    plans_total: plansTotal
+  };
+}
+
+module.exports = { contextTriage, readBridgeData, readTrackerData };

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

@@ -272,7 +272,7 @@ function calculateProgress(planningDir) {
 
   for (const entry of entries) {
     const dir = path.join(phasesDir, entry.name);
-    const plans = findFiles(dir, /-PLAN\.md$/);
+    const plans = findFiles(dir, /PLAN.*\.md$/i);
     total += plans.length;
 
     const summaries = findFiles(dir, /^SUMMARY-.*\.md$/);

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

@@ -156,11 +156,136 @@ function initProgress(planningDir) {
   return { current_phase: state.current_phase, total_phases: state.phase_count, status: state.state ? state.state.status : null, phases: progress.phases, total_plans: progress.total_plans, completed_plans: progress.completed_plans, percentage: progress.percentage };
 }
 
+/**
+ * Aggregate all state an orchestrator skill needs to begin work on a phase.
+ * Replaces 5-10 individual file reads with a single CLI call returning ~1,500 tokens of JSON.
+ *
+ * @param {string} phaseNum - Phase number
+ * @param {string} [planningDir] - Path to .planning directory
+ */
+function initStateBundle(phaseNum, planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+  const { parseYamlFrontmatter } = require('./core');
+
+  // 1. State
+  const stateResult = stateLoad(dir);
+  if (!stateResult.exists) return { error: 'No .planning/ directory found' };
+  const st = stateResult.state || {};
+  const state = {
+    current_phase: stateResult.current_phase,
+    status: st.status || stateResult.status || null,
+    progress: stateResult.progress,
+    total_phases: stateResult.phase_count || null,
+    last_activity: st.last_activity || null,
+    blockers: st.blockers || []
+  };
+
+  // 2. Config summary
+  const config = configLoad(dir) || {};
+  const depthProfile = resolveDepthProfile(config);
+  const models = config.models || {};
+  const config_summary = {
+    depth: depthProfile.depth,
+    mode: config.mode || 'interactive',
+    parallelization: config.parallelization || { enabled: false },
+    gates: config.gates || {},
+    features: config.features || {},
+    models: { executor: models.executor || 'sonnet', verifier: models.verifier || 'sonnet', planner: models.planner || 'sonnet' }
+  };
+
+  // 3. Phase info
+  const phaseResult = phaseInfo(phaseNum, dir);
+  if (phaseResult.error) return { error: phaseResult.error };
+  const phase = {
+    num: phaseNum,
+    dir: phaseResult.phase,
+    name: phaseResult.name,
+    goal: phaseResult.goal,
+    has_context: phaseResult.has_context,
+    status: phaseResult.filesystem_status,
+    plan_count: phaseResult.plan_count,
+    completed: phaseResult.completed
+  };
+
+  // 4. Plans
+  const plansResult = planIndex(phaseNum, dir);
+  const plans = (plansResult.plans || []).map(p => ({
+    file: p.file,
+    plan_id: p.plan_id,
+    wave: p.wave,
+    autonomous: p.autonomous,
+    has_summary: p.has_summary,
+    must_haves_count: p.must_haves_count,
+    depends_on: p.depends_on
+  }));
+  const waves = plansResult.waves || {};
+
+  // 5. Prior summaries — scan all phase directories for SUMMARY*.md, extract frontmatter only
+  const prior_summaries = [];
+  const phasesDir = path.join(dir, 'phases');
+  if (fs.existsSync(phasesDir)) {
+    const phaseDirs = fs.readdirSync(phasesDir).filter(d => {
+      try { return fs.statSync(path.join(phasesDir, d)).isDirectory(); } catch (_e) { return false; }
+    }).sort();
+    for (const pd of phaseDirs) {
+      if (prior_summaries.length >= 10) break;
+      const pdPath = path.join(phasesDir, pd);
+      let summaryFiles;
+      try { summaryFiles = fs.readdirSync(pdPath).filter(f => /^SUMMARY.*\.md$/i.test(f)).sort(); } catch (_e) { continue; }
+      for (const sf of summaryFiles) {
+        if (prior_summaries.length >= 10) break;
+        try {
+          const content = fs.readFileSync(path.join(pdPath, sf), 'utf8');
+          const fm = parseYamlFrontmatter(content);
+          if (fm && !fm.error) {
+            const entry = {
+              phase: fm.phase !== undefined ? fm.phase : null,
+              plan: fm.plan !== undefined ? fm.plan : null,
+              status: fm.status || null,
+              provides: fm.provides || [],
+              requires: fm.requires || [],
+              key_files: fm.key_files || []
+            };
+            if (fm.key_decisions !== undefined) entry.key_decisions = fm.key_decisions;
+            prior_summaries.push(entry);
+          }
+        } catch (_e) { /* skip unreadable */ }
+      }
+    }
+  }
+
+  // 6. Context file existence
+  const has_project_context = fs.existsSync(path.join(dir, 'CONTEXT.md'));
+  const has_phase_context = phaseResult.has_context || false;
+
+  // 7. Git state
+  let git = { branch: null, clean: null };
+  try {
+    const { execSync } = require('child_process');
+    const branch = execSync('git rev-parse --abbrev-ref HEAD', { encoding: 'utf8', timeout: 5000 }).trim();
+    const status = execSync('git status --porcelain', { encoding: 'utf8', timeout: 5000 }).trim();
+    git = { branch, clean: status === '' };
+  } catch (_e) { /* not a git repo */ }
+
+  return {
+    state,
+    config_summary,
+    phase,
+    plans,
+    waves,
+    prior_summaries,
+    git,
+    has_project_context,
+    has_phase_context
+  };
+}
+
 module.exports = {
   initExecutePhase,
   initPlanPhase,
   initQuick,
   initVerifyWork,
   initResume,
-  initProgress
+  initProgress,
+  initStateBundle
 };

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

@@ -54,7 +54,8 @@ function planIndex(phaseNum, planningDir) {
   }
 
   const fullDir = path.join(phasesDir, phaseDir.name);
-  const planFiles = findFiles(fullDir, /-PLAN\.md$/);
+  // Match both PLAN-NN.md (current) and NN-PLAN.md / slug-NN-PLAN.md (legacy)
+  const planFiles = findFiles(fullDir, /PLAN.*\.md$/i);
 
   const plans = [];
   const waves = {};
@@ -65,7 +66,7 @@ function planIndex(phaseNum, planningDir) {
 
     const plan = {
       file,
-      plan_id: fm.plan || file.replace(/-PLAN\.md$/, ''),
+      plan_id: fm.plan || file.replace(/^PLAN-?/i, '').replace(/-PLAN/i, '').replace(/\.md$/i, ''),
       wave: parseInt(fm.wave, 10) || 1,
       type: fm.type || 'unknown',
       autonomous: fm.autonomous !== false,
@@ -112,7 +113,8 @@ function mustHavesCollect(phaseNum, planningDir) {
   }
 
   const fullDir = path.join(phasesDir, phaseDir.name);
-  const planFiles = findFiles(fullDir, /-PLAN\.md$/);
+  // Match both PLAN-NN.md (current) and NN-PLAN.md / slug-NN-PLAN.md (legacy)
+  const planFiles = findFiles(fullDir, /PLAN.*\.md$/i);
 
   const perPlan = {};
   const allTruths = new Set();
@@ -122,7 +124,7 @@ function mustHavesCollect(phaseNum, planningDir) {
   for (const file of planFiles) {
     const content = fs.readFileSync(path.join(fullDir, file), 'utf8');
     const fm = parseYamlFrontmatter(content);
-    const planId = fm.plan || file.replace(/-PLAN\.md$/, '');
+    const planId = fm.plan || file.replace(/^PLAN-?/i, '').replace(/-PLAN/i, '').replace(/\.md$/i, '');
     const mh = fm.must_haves || { truths: [], artifacts: [], key_links: [] };
 
     perPlan[planId] = mh;
@@ -353,6 +355,201 @@ function phaseList(planningDir) {
   return { phases };
 }
 
+/**
+ * Extract frontmatter-only stats from all SUMMARY.md files across a milestone's phases.
+ * Never reads SUMMARY body content — only YAML frontmatter.
+ *
+ * Strategy for finding phases:
+ *   1. Check milestone archive: .planning/milestones/v{version}/phases/
+ *   2. Fall back to active phases dir: .planning/phases/
+ *      matching phase numbers extracted from ROADMAP.md milestone section.
+ *
+ * @param {string} version - Milestone version string (e.g. "5.0", "6.0")
+ * @param {string} [planningDir] - Path to .planning directory
+ * @returns {object} Milestone stats with per-phase summaries and aggregated fields
+ */
+function milestoneStats(version, planningDir) {
+  const dir = planningDir || path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning');
+
+  const phases = [];
+
+  // --- Strategy 1: Check milestone archive ---
+  const archivePhasesDir = path.join(dir, 'milestones', `v${version}`, 'phases');
+  if (fs.existsSync(archivePhasesDir)) {
+    const phaseDirs = fs.readdirSync(archivePhasesDir, { withFileTypes: true })
+      .filter(e => e.isDirectory() && /^\d+-/.test(e.name))
+      .sort((a, b) => a.name.localeCompare(b.name));
+
+    for (const phaseEntry of phaseDirs) {
+      const phaseData = _collectPhaseStats(path.join(archivePhasesDir, phaseEntry.name), phaseEntry.name);
+      if (phaseData) phases.push(phaseData);
+    }
+  } else {
+    // --- Strategy 2: Parse ROADMAP.md to find phase numbers for this milestone ---
+    const roadmapPath = path.join(dir, 'ROADMAP.md');
+    const phaseNums = _extractMilestonePhaseNums(roadmapPath, version);
+    const phasesDir = path.join(dir, 'phases');
+
+    if (fs.existsSync(phasesDir) && phaseNums.length > 0) {
+      const allDirs = fs.readdirSync(phasesDir, { withFileTypes: true })
+        .filter(e => e.isDirectory() && /^\d+-/.test(e.name))
+        .sort((a, b) => a.name.localeCompare(b.name));
+
+      for (const phaseEntry of allDirs) {
+        const num = parseInt(phaseEntry.name.split('-')[0], 10);
+        if (phaseNums.includes(num)) {
+          const phaseData = _collectPhaseStats(path.join(phasesDir, phaseEntry.name), phaseEntry.name);
+          if (phaseData) phases.push(phaseData);
+        }
+      }
+    }
+  }
+
+  // --- Aggregate across all phases ---
+  const providesSet = new Set();
+  const keyFilesSet = new Set();
+  const patternsSet = new Set();
+  const allKeyDecisions = [];
+  const allDeferred = [];
+  const totalMetrics = { tasks_completed: 0, commits: 0, files_changed: 0 };
+
+  for (const phase of phases) {
+    for (const summary of phase.summaries) {
+      (summary.provides || []).forEach(v => providesSet.add(v));
+      (summary.key_files || []).forEach(v => keyFilesSet.add(v));
+      (summary.patterns || []).forEach(v => patternsSet.add(v));
+      (summary.key_decisions || []).forEach(v => allKeyDecisions.push(v));
+      (summary.deferred || []).forEach(v => allDeferred.push(v));
+      const m = summary.metrics || {};
+      totalMetrics.tasks_completed += parseInt(m.tasks_completed, 10) || 0;
+      totalMetrics.commits += parseInt(m.commits, 10) || 0;
+      totalMetrics.files_changed += parseInt(m.files_changed, 10) || 0;
+    }
+  }
+
+  return {
+    version,
+    phase_count: phases.length,
+    phases,
+    aggregated: {
+      all_provides: [...providesSet],
+      all_key_files: [...keyFilesSet],
+      all_key_decisions: allKeyDecisions,
+      all_patterns: [...patternsSet],
+      all_deferred: allDeferred,
+      total_metrics: totalMetrics
+    }
+  };
+}
+
+/**
+ * Collect frontmatter-only stats from all SUMMARY*.md files in a single phase directory.
+ *
+ * @param {string} fullDir - Full path to phase directory
+ * @param {string} dirName - Directory name (e.g. "46-agent-contracts")
+ * @returns {object}
+ */
+function _collectPhaseStats(fullDir, dirName) {
+  const numStr = dirName.split('-')[0];
+  const name = dirName.replace(/^\d+-/, '');
+
+  const summaryFiles = findFiles(fullDir, /^SUMMARY.*\.md$/i);
+  const summaries = [];
+
+  for (const file of summaryFiles) {
+    const filePath = path.join(fullDir, file);
+    const content = fs.readFileSync(filePath, 'utf8');
+
+    // Extract ONLY the YAML frontmatter — never read body content
+    const fm = parseYamlFrontmatter(content);
+
+    // Collect only the documented frontmatter fields
+    const entry = {};
+    const fields = ['phase', 'plan', 'status', 'provides', 'requires', 'key_files',
+      'key_decisions', 'patterns', 'metrics', 'deferred', 'tags'];
+    for (const field of fields) {
+      if (fm[field] !== undefined) {
+        entry[field] = fm[field];
+      }
+    }
+    summaries.push(entry);
+  }
+
+  return {
+    number: numStr,
+    name,
+    summaries
+  };
+}
+
+/**
+ * Parse ROADMAP.md to find phase numbers belonging to a milestone version.
+ * Scans for milestone section headers containing the version string, then
+ * collects phase numbers from "### Phase N:" headings or "Phases N-M" text.
+ *
+ * @param {string} roadmapPath - Path to ROADMAP.md
+ * @param {string} version - Version string (e.g. "5.0")
+ * @returns {number[]} Array of phase numbers
+ */
+function _extractMilestonePhaseNums(roadmapPath, version) {
+  if (!fs.existsSync(roadmapPath)) return [];
+
+  const content = fs.readFileSync(roadmapPath, 'utf8');
+  const lines = content.split(/\r?\n/);
+
+  const phaseNums = [];
+  let inMilestoneSection = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    // Detect milestone section header (## Milestone: ... (vX.Y) or containing version)
+    if (/^##\s+Milestone:/i.test(line)) {
+      inMilestoneSection = line.includes(`v${version}`) || line.includes(`(${version})`);
+      continue;
+    }
+
+    // If we hit a new ## section (not ###), exit the milestone section
+    if (/^##\s+[^#]/.test(line)) {
+      if (inMilestoneSection) break;
+      continue;
+    }
+
+    if (!inMilestoneSection) continue;
+
+    // Extract phase numbers from "### Phase N:" headings
+    const phaseHeading = line.match(/^###\s+Phase\s+(\d+)/i);
+    if (phaseHeading) {
+      phaseNums.push(parseInt(phaseHeading[1], 10));
+      continue;
+    }
+
+    // Extract from "Phases N-M" or "Phase N" text
+    const phaseRange = line.match(/Phases?\s+(\d+)(?:-(\d+))?/gi);
+    if (phaseRange) {
+      for (const match of phaseRange) {
+        const rangeMatch = match.match(/(\d+)(?:-(\d+))?/);
+        if (rangeMatch) {
+          const start = parseInt(rangeMatch[1], 10);
+          const end = rangeMatch[2] ? parseInt(rangeMatch[2], 10) : start;
+          for (let n = start; n <= end; n++) {
+            if (!phaseNums.includes(n)) phaseNums.push(n);
+          }
+        }
+      }
+    }
+
+    // Row entries in phase overview tables: | 51 | CLI Foundation | ...
+    const tableRow = line.match(/^\|\s*(\d+)\s*\|/);
+    if (tableRow) {
+      const n = parseInt(tableRow[1], 10);
+      if (!phaseNums.includes(n)) phaseNums.push(n);
+    }
+  }
+
+  return phaseNums;
+}
+
 module.exports = {
   frontmatter,
   planIndex,
@@ -360,5 +557,6 @@ module.exports = {
   phaseInfo,
   phaseAdd,
   phaseRemove,
-  phaseList
+  phaseList,
+  milestoneStats
 };