@sienklogic/plan-build-run 2.45.0 → 2.46.0

package/CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to Plan-Build-Run will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.46.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.45.0...plan-build-run-v2.46.0) (2026-03-01)
+
+
+### Features
+
+* **51-01:** implement initStateBundle in lib/init.js ([0e1b103](https://github.com/SienkLogic/plan-build-run/commit/0e1b1038953c974266f36af9a8ecd08e5f54dc13))
+* **51-01:** wire state-bundle into pbr-tools.js dispatch ([7092b58](https://github.com/SienkLogic/plan-build-run/commit/7092b58aa3376bc858bfa7ff69b68e0e3b96b9f1))
+* **51-02:** add milestoneStats function and milestone-stats CLI command ([d962ad2](https://github.com/SienkLogic/plan-build-run/commit/d962ad27510ece26b14a2439f50c9d5dde21a491))
+* **51-03:** create lib/reference.js with listHeadings, extractSection, resolveReferencePath, referenceGet ([5f5e340](https://github.com/SienkLogic/plan-build-run/commit/5f5e340381d61aa450ef2afebaa0d6c8b3b55546))
+* **51-03:** wire reference subcommand into pbr-tools.js dispatch with --section and --list flags ([b638ed9](https://github.com/SienkLogic/plan-build-run/commit/b638ed9d8a7ecefec56bd5ae88d555ad9dd5e906))
+* **51-04:** create lib/context.js with contextTriage function ([e77982e](https://github.com/SienkLogic/plan-build-run/commit/e77982ed220fb17fe911e1e3d6323570b8309044))
+* **51-04:** wire context-triage dispatch into pbr-tools.js ([2f6fcb4](https://github.com/SienkLogic/plan-build-run/commit/2f6fcb4a8212f43fa84d3b01a74234cee46fe80a))
+
+
+### Bug Fixes
+
+* **51-04:** remove unused test imports to fix lint errors ([a7e90e0](https://github.com/SienkLogic/plan-build-run/commit/a7e90e0533448d8be4a13a74711b52da0ec993d0))
+* **tools:** fix planIndex regex to match PLAN-NN.md naming convention ([a4aadc1](https://github.com/SienkLogic/plan-build-run/commit/a4aadc1f95baeaa285b722d3d88ea607a4addd59))
+
 ## [2.45.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.44.0...plan-build-run-v2.45.0) (2026-03-01)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sienklogic/plan-build-run",
-  "version": "2.45.0",
+  "version": "2.46.0",
   "description": "Plan it, Build it, Run it — structured development workflow for Claude Code",
   "keywords": [
     "claude-code",

package/plugins/copilot-pbr/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.45.0",
+  "version": "2.46.0",
   "description": "Plan-Build-Run — Structured development workflow for GitHub Copilot CLI. Solves context rot through disciplined agent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",

package/plugins/cursor-pbr/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.45.0",
+  "version": "2.46.0",
   "description": "Plan-Build-Run — Structured development workflow for Cursor. Solves context rot through disciplined subagent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",

package/plugins/pbr/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pbr",
-  "version": "2.45.0",
+  "version": "2.46.0",
   "description": "Plan-Build-Run — Structured development workflow for Claude Code. Solves context rot through disciplined subagent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",

package/plugins/pbr/scripts/check-state-sync.js

@@ -67,7 +67,7 @@ function extractPhaseNum(dirName) {
 function countPhaseArtifacts(phaseDir) {
   try {
     const files = fs.readdirSync(phaseDir);
-    const plans = files.filter(f => /-PLAN\.md$/.test(f));
+    const plans = files.filter(f => /PLAN.*\.md$/i.test(f));
     const summaries = files.filter(f => /SUMMARY.*\.md$/.test(f) || /.*SUMMARY.*\.md$/.test(f));
 
     // Filter for summaries that have status: complete in frontmatter

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
 };

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

@@ -0,0 +1,236 @@
+'use strict';
+
+/**
+ * reference.js — Targeted reference document access for Plan-Build-Run agents.
+ *
+ * Enables surgical extraction of specific sections from reference documents,
+ * reducing token usage from 1,500-3,500 tokens (full file) to 50-200 tokens (section only).
+ *
+ * Exported functions:
+ *   listHeadings(content)                   — Extract all H2/H3 headings
+ *   extractSection(content, query)          — Extract a section by heading query
+ *   resolveReferencePath(name, pluginRoot)  — Resolve a ref name to a file path
+ *   referenceGet(name, options, pluginRoot) — Main entry point
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Extract all H2 and H3 headings from markdown content.
+ * Handles CRLF line endings (Windows compatibility).
+ *
+ * @param {string} content - Markdown content
+ * @returns {Array<{level: number, heading: string}>}
+ */
+function listHeadings(content) {
+  const headings = [];
+  const regex = /^(#{2,3})\s+(.+?)\r?$/gm;
+  let match;
+  while ((match = regex.exec(content)) !== null) {
+    headings.push({
+      level: match[1].length,
+      heading: match[2].replace(/\r$/, '')
+    });
+  }
+  return headings;
+}
+
+/**
+ * Extract a section matching the query using 4-tier fuzzy matching.
+ * Matching tiers (applied in order):
+ *   1. Exact match (case-insensitive)
+ *   2. Starts-with match
+ *   3. Contains match
+ *   4. Word-boundary: all words in query appear in heading
+ *
+ * For H2: captures content until next H2 or end of file.
+ * For H3: captures content until next H3, next H2, or end of file.
+ *
+ * @param {string} content - Markdown content
+ * @returns {{ heading: string, level: number, content: string, char_count: number } | null}
+ */
+function extractSection(content, query) {
+  // Collect all headings with their character offsets
+  const headings = [];
+  const regex = /^(#{2,3})\s+(.+?)\r?$/gm;
+  let match;
+  while ((match = regex.exec(content)) !== null) {
+    headings.push({
+      level: match[1].length,
+      heading: match[2].replace(/\r$/, ''),
+      index: match.index,
+      fullMatch: match[0]
+    });
+  }
+
+  if (headings.length === 0) return null;
+
+  const q = query.toLowerCase();
+
+  // 4-tier fuzzy matching
+  let matched = null;
+
+  // Tier 1: Exact match
+  matched = headings.find(h => h.heading.toLowerCase() === q);
+
+  // Tier 2: Starts-with
+  if (!matched) {
+    matched = headings.find(h => h.heading.toLowerCase().startsWith(q));
+  }
+
+  // Tier 3: Contains
+  if (!matched) {
+    matched = headings.find(h => h.heading.toLowerCase().includes(q));
+  }
+
+  // Tier 4: Word-boundary — all words in query appear in heading
+  if (!matched) {
+    const words = q.split(/\s+/).filter(Boolean);
+    matched = headings.find(h => {
+      const hl = h.heading.toLowerCase();
+      return words.every(w => hl.includes(w));
+    });
+  }
+
+  if (!matched) return null;
+
+  // Determine section boundaries
+  const startIdx = matched.index;
+  // Find where the section content starts (after the heading line)
+  const headingEnd = startIdx + matched.fullMatch.length;
+  // Skip the newline after the heading
+  const contentStart = headingEnd + (content[headingEnd] === '\r' ? 2 : content[headingEnd] === '\n' ? 1 : 0);
+
+  // Find where section ends
+  let endIdx = content.length;
+
+  if (matched.level === 2) {
+    // H2: ends at next H2 or end of file
+    const nextH2 = /\n## /g;
+    nextH2.lastIndex = contentStart;
+    const nextMatch = nextH2.exec(content);
+    if (nextMatch) endIdx = nextMatch.index;
+  } else {
+    // H3: ends at next H3 or H2 or end of file
+    const nextSection = /\n#{2,3} /g;
+    nextSection.lastIndex = contentStart;
+    const nextMatch = nextSection.exec(content);
+    if (nextMatch) endIdx = nextMatch.index;
+  }
+
+  const sectionContent = content.slice(startIdx, endIdx).trimEnd();
+
+  return {
+    heading: matched.heading,
+    level: matched.level,
+    content: sectionContent,
+    char_count: sectionContent.length
+  };
+}
+
+/**
+ * Resolve a reference name to its full file path.
+ *
+ * @param {string} name - Reference name (with or without .md extension)
+ * @param {string} pluginRoot - Plugin root directory
+ * @returns {string | { error: string, available: string[] }}
+ */
+function resolveReferencePath(name, pluginRoot) {
+  // Strip .md extension if present
+  const baseName = name.endsWith('.md') ? name.slice(0, -3) : name;
+  const refPath = path.join(pluginRoot, 'references', baseName + '.md');
+
+  if (fs.existsSync(refPath)) {
+    return refPath;
+  }
+
+  // File not found — list available references
+  const refsDir = path.join(pluginRoot, 'references');
+  let available = [];
+  try {
+    available = fs.readdirSync(refsDir)
+      .filter(f => f.endsWith('.md'))
+      .map(f => f.slice(0, -3));
+  } catch (_e) {
+    // references dir doesn't exist
+  }
+
+  return {
+    error: `Reference '${baseName}' not found in ${refsDir}`,
+    available
+  };
+}
+
+/**
+ * Strip YAML frontmatter from content if present in first 5 lines.
+ * @param {string} content
+ * @returns {string}
+ */
+function stripFrontmatter(content) {
+  const lines = content.split(/\r?\n/);
+  if (lines[0] !== '---') return content;
+  // Find closing ---
+  for (let i = 1; i < Math.min(lines.length, 200); i++) {
+    if (lines[i] === '---') {
+      // Return everything after the closing ---
+      return lines.slice(i + 1).join('\n').replace(/^\n+/, '');
+    }
+  }
+  return content;
+}
+
+/**
+ * Main entry point for reference access.
+ *
+ * @param {string} name - Reference name (e.g. "plan-format")
+ * @param {{ section?: string, list?: boolean }} options
+ * @param {string} pluginRoot - Plugin root directory
+ * @returns {object}
+ */
+function referenceGet(name, options, pluginRoot) {
+  const opts = options || {};
+
+  // Resolve file path
+  const resolved = resolveReferencePath(name, pluginRoot);
+  if (typeof resolved === 'object' && resolved.error) {
+    return resolved;
+  }
+
+  // Read content
+  let content;
+  try {
+    content = fs.readFileSync(resolved, 'utf8');
+  } catch (e) {
+    return { error: `Cannot read reference file: ${e.message}` };
+  }
+
+  // Strip YAML frontmatter if present in first 5 lines
+  const firstLines = content.split(/\r?\n/).slice(0, 5).join('\n');
+  if (firstLines.includes('---')) {
+    content = stripFrontmatter(content);
+  }
+
+  // --list flag: return available headings
+  if (opts.list) {
+    return { name, headings: listHeadings(content) };
+  }
+
+  // --section flag: extract specific section
+  if (opts.section) {
+    const result = extractSection(content, opts.section);
+    if (!result) {
+      const available = listHeadings(content);
+      return {
+        error: `Section '${opts.section}' not found in reference '${name}'`,
+        available
+      };
+    }
+    return { name, section: opts.section, ...result };
+  }
+
+  // No flags: return full content
+  return { name, content, char_count: content.length };
+}
+
+module.exports = { listHeadings, extractSection, resolveReferencePath, referenceGet };

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

@@ -246,7 +246,7 @@ function stateCheckProgress(planningDir) {
 
   for (const entry of entries) {
     const phaseDir = path.join(phasesDir, entry.name);
-    const plans = findFiles(phaseDir, /-PLAN\.md$/);
+    const plans = findFiles(phaseDir, /PLAN.*\.md$/i);
     const summaries = findFiles(phaseDir, /^SUMMARY-.*\.md$/);
     const verification = fs.existsSync(path.join(phaseDir, 'VERIFICATION.md'));
 

package/plugins/pbr/scripts/pbr-tools.js

@@ -105,7 +105,8 @@ const {
   phaseInfo: _phaseInfo,
   phaseAdd: _phaseAdd,
   phaseRemove: _phaseRemove,
-  phaseList: _phaseList
+  phaseList: _phaseList,
+  milestoneStats: _milestoneStats
 } = require('./lib/phase');
 
 const {
@@ -114,7 +115,8 @@ const {
   initQuick: _initQuick,
   initVerifyWork: _initVerifyWork,
   initResume: _initResume,
-  initProgress: _initProgress
+  initProgress: _initProgress,
+  initStateBundle: _initStateBundle
 } = require('./lib/init');
 
 const {
@@ -143,6 +145,14 @@ const {
   checkDeferralThresholds: _checkDeferralThresholds
 } = require('./lib/learnings');
 
+const {
+  referenceGet: _referenceGet
+} = require('./lib/reference');
+
+const {
+  contextTriage: _contextTriage
+} = require('./lib/context');
+
 // --- Local LLM imports (not extracted — separate module tree) ---
 const { resolveConfig, checkHealth } = require('./local-llm/health');
 const { classifyArtifact } = require('./local-llm/operations/classify-artifact');
@@ -235,6 +245,10 @@ function phaseList() {
   return _phaseList(planningDir);
 }
 
+function milestoneStats(version) {
+  return _milestoneStats(version, planningDir);
+}
+
 function initExecutePhase(phaseNum) {
   return _initExecutePhase(phaseNum, planningDir);
 }
@@ -259,6 +273,10 @@ function initProgress() {
   return _initProgress(planningDir);
 }
 
+function stateBundle(phaseNum) {
+  return _initStateBundle(phaseNum, planningDir);
+}
+
 function historyAppend(entry, dir) {
   return _historyAppend(entry, dir || planningDir);
 }
@@ -291,6 +309,20 @@ function spotCheck(phaseDir, planId) {
   return _spotCheck(planningDir, phaseDir, planId);
 }
 
+function referenceGet(name, options) {
+  // Resolve plugin root — try CLAUDE_PLUGIN_ROOT env, then walk up from __dirname
+  const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT || path.resolve(__dirname, '..');
+  // Fix MSYS paths on Windows (same pattern as run-hook.js)
+  let root = pluginRoot;
+  const msysMatch = root.match(/^\/([a-zA-Z])\/(.*)/);
+  if (msysMatch) root = msysMatch[1] + ':' + path.sep + msysMatch[2];
+  return _referenceGet(name, options, root);
+}
+
+function contextTriage(options) {
+  return _contextTriage(options, planningDir);
+}
+
 // --- validateProject stays here (cross-cutting across modules) ---
 
 /**
@@ -633,6 +665,10 @@ async function main() {
       output(initResume());
     } else if (command === "init" && subcommand === "progress") {
       output(initProgress());
+    } else if (command === 'state-bundle') {
+      const phaseNum = args[1];
+      if (!phaseNum) error('Usage: pbr-tools.js state-bundle <phase-number>');
+      output(stateBundle(phaseNum));
     // --- State patch/advance/metric ---
     } else if (command === "state" && subcommand === "patch") {
       const jsonStr = args[2];
@@ -729,10 +765,30 @@ async function main() {
         error('Usage: spot-check <phaseSlug> <planId>');
       }
       output(spotCheck(phaseSlug, planId));
+    } else if (command === 'context-triage') {
+      const options = {};
+      const agentsIdx = args.indexOf('--agents-done');
+      if (agentsIdx !== -1) options.agentsDone = parseInt(args[agentsIdx + 1], 10);
+      const plansIdx = args.indexOf('--plans-total');
+      if (plansIdx !== -1) options.plansTotal = parseInt(args[plansIdx + 1], 10);
+      const stepIdx = args.indexOf('--step');
+      if (stepIdx !== -1) options.currentStep = args[stepIdx + 1];
+      output(contextTriage(options));
+    } else if (command === 'reference') {
+      const name = args[1];
+      if (!name) error('Usage: pbr-tools.js reference <name> [--section <heading>] [--list]');
+      const listFlag = args.includes('--list');
+      const sectionIdx = args.indexOf('--section');
+      const section = sectionIdx !== -1 ? args.slice(sectionIdx + 1).join(' ') : null;
+      output(referenceGet(name, { section: section, list: listFlag }));
+    } else if (command === 'milestone-stats') {
+      const version = args[1];
+      if (!version) error('Usage: pbr-tools.js milestone-stats <version>');
+      output(milestoneStats(version));
     } else if (command === 'validate-project') {
       output(validateProject());
     } else {
-      error(`Unknown command: ${args.join(' ')}\nCommands: state load|check-progress|update|patch|advance-plan|record-metric, config validate|load-defaults|save-defaults|resolve-depth, validate-project, migrate [--dry-run] [--force], init execute-phase|plan-phase|quick|verify-work|resume|progress, plan-index, frontmatter, must-haves, phase-info, phase add|remove|list, roadmap update-status|update-plans, history append|load, todo list|get|add|done, event, llm health|status|classify|score-source|classify-error|summarize|metrics [--session <ISO>]|adjust-thresholds, learnings ingest|query|check-thresholds`);
+      error(`Unknown command: ${args.join(' ')}\nCommands: state load|check-progress|update|patch|advance-plan|record-metric, config validate|load-defaults|save-defaults|resolve-depth, validate-project, migrate [--dry-run] [--force], init execute-phase|plan-phase|quick|verify-work|resume|progress, state-bundle <phase>, plan-index, frontmatter, must-haves, phase-info, phase add|remove|list, roadmap update-status|update-plans, history append|load, todo list|get|add|done, event, llm health|status|classify|score-source|classify-error|summarize|metrics [--session <ISO>]|adjust-thresholds, learnings ingest|query|check-thresholds, milestone-stats <version>, context-triage [--agents-done N] [--plans-total N] [--step NAME]`);
     }
   } catch (e) {
     error(e.message);
@@ -740,6 +796,6 @@ async function main() {
 }
 
 if (require.main === module || process.argv[1] === __filename) { main().catch(err => { process.stderr.write(err.message + '\n'); process.exit(1); }); }
-module.exports = { KNOWN_AGENTS, initExecutePhase, initPlanPhase, initQuick, initVerifyWork, initResume, initProgress, statePatch, stateAdvancePlan, stateRecordMetric, parseStateMd, parseRoadmapMd, parseYamlFrontmatter, parseMustHaves, countMustHaves, stateLoad, stateCheckProgress, configLoad, configClearCache, configValidate, lockedFileUpdate, planIndex, determinePhaseStatus, findFiles, atomicWrite, tailLines, frontmatter, mustHavesCollect, phaseInfo, stateUpdate, roadmapUpdateStatus, roadmapUpdatePlans, updateLegacyStateField, updateFrontmatterField, updateTableRow, findRoadmapRow, resolveDepthProfile, DEPTH_PROFILE_DEFAULTS, historyAppend, historyLoad, VALID_STATUS_TRANSITIONS, validateStatusTransition, writeActiveSkill, validateProject, phaseAdd, phaseRemove, phaseList, loadUserDefaults, saveUserDefaults, mergeUserDefaults, USER_DEFAULTS_PATH, todoList, todoGet, todoAdd, todoDone, migrate, spotCheck };
+module.exports = { KNOWN_AGENTS, initExecutePhase, initPlanPhase, initQuick, initVerifyWork, initResume, initProgress, initStateBundle: stateBundle, stateBundle, statePatch, stateAdvancePlan, stateRecordMetric, parseStateMd, parseRoadmapMd, parseYamlFrontmatter, parseMustHaves, countMustHaves, stateLoad, stateCheckProgress, configLoad, configClearCache, configValidate, lockedFileUpdate, planIndex, determinePhaseStatus, findFiles, atomicWrite, tailLines, frontmatter, mustHavesCollect, phaseInfo, stateUpdate, roadmapUpdateStatus, roadmapUpdatePlans, updateLegacyStateField, updateFrontmatterField, updateTableRow, findRoadmapRow, resolveDepthProfile, DEPTH_PROFILE_DEFAULTS, historyAppend, historyLoad, VALID_STATUS_TRANSITIONS, validateStatusTransition, writeActiveSkill, validateProject, phaseAdd, phaseRemove, phaseList, loadUserDefaults, saveUserDefaults, mergeUserDefaults, USER_DEFAULTS_PATH, todoList, todoGet, todoAdd, todoDone, migrate, spotCheck, referenceGet, milestoneStats, contextTriage };
 // NOTE: validateProject, phaseAdd, phaseRemove, phaseList were previously CLI-only (not exported).
 // They are now exported for testability. This is additive and backwards-compatible.