@sienklogic/plan-build-run 2.21.1 → 2.21.2

package/plugins/pbr/scripts/lib/gates/multi-phase-loader.js

@@ -0,0 +1,149 @@
+'use strict';
+
+/**
+ * Multi-Phase Plan Loader
+ *
+ * Loads plan files from the current phase and adjacent phases to provide
+ * cross-phase awareness to Task() agents. Respects the multi_phase_awareness
+ * feature toggle and max_phases_in_context workflow config.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('../../hook-logger');
+
+/**
+ * Load plans from the current phase and adjacent phases.
+ *
+ * @param {string} planningDir - path to .planning directory
+ * @param {number} currentPhaseNum - current phase number (1-based)
+ * @param {object} config - project config object
+ * @returns {{ phases: Array<{ phaseNum: number, phaseName: string, plans: Array<{ planId: string, content: string }> }>, totalPlans: number, phasesLoaded: number }}
+ */
+function loadMultiPhasePlans(planningDir, currentPhaseNum, config) {
+  const phasesDir = path.join(planningDir, 'phases');
+
+  // List and sort all phase directories
+  const allPhaseDirs = listPhaseDirs(phasesDir);
+
+  // Determine which phases to load
+  const featureEnabled = !(config && config.features && config.features.multi_phase_awareness === false);
+  const maxPhases = (config && config.workflow && config.workflow.max_phases_in_context) || 3;
+
+  let selectedPhaseNums;
+  if (!featureEnabled) {
+    // Only current phase
+    selectedPhaseNums = [currentPhaseNum];
+  } else {
+    selectedPhaseNums = selectPhases(allPhaseDirs, currentPhaseNum, maxPhases);
+  }
+
+  // Load plans from selected phases
+  const phases = [];
+  let totalPlans = 0;
+
+  for (const phaseNum of selectedPhaseNums) {
+    const phaseInfo = allPhaseDirs.find(p => p.num === phaseNum);
+    if (!phaseInfo) continue;
+
+    const plans = loadPlansFromDir(phaseInfo.fullPath);
+    if (plans.length === 0) continue; // Skip phases with no plans
+
+    phases.push({
+      phaseNum: phaseInfo.num,
+      phaseName: phaseInfo.name,
+      plans,
+    });
+    totalPlans += plans.length;
+  }
+
+  return {
+    phases,
+    totalPlans,
+    phasesLoaded: phases.length,
+  };
+}
+
+/**
+ * List phase directories sorted by phase number.
+ * @param {string} phasesDir - path to .planning/phases/
+ * @returns {Array<{ num: number, name: string, fullPath: string }>}
+ */
+function listPhaseDirs(phasesDir) {
+  if (!fs.existsSync(phasesDir)) return [];
+
+  const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+  const dirs = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const match = entry.name.match(/^(\d+)-(.+)/);
+    if (!match) continue;
+    dirs.push({
+      num: parseInt(match[1], 10),
+      name: entry.name,
+      fullPath: path.join(phasesDir, entry.name),
+    });
+  }
+
+  return dirs.sort((a, b) => a.num - b.num);
+}
+
+/**
+ * Select up to maxPhases phases centered on currentPhaseNum.
+ * Always includes current. Then adds previous, next, then extends forward.
+ */
+function selectPhases(allPhaseDirs, currentPhaseNum, maxPhases) {
+  const allNums = allPhaseDirs.map(p => p.num);
+  if (allNums.length === 0) return [currentPhaseNum];
+
+  const selected = new Set();
+  selected.add(currentPhaseNum);
+
+  // Add previous phase
+  const prevPhases = allNums.filter(n => n < currentPhaseNum).sort((a, b) => b - a);
+  if (prevPhases.length > 0 && selected.size < maxPhases) {
+    selected.add(prevPhases[0]); // closest previous
+  }
+
+  // Add next phase
+  const nextPhases = allNums.filter(n => n > currentPhaseNum).sort((a, b) => a - b);
+  if (nextPhases.length > 0 && selected.size < maxPhases) {
+    selected.add(nextPhases[0]); // closest next
+  }
+
+  // If max > 3, extend forward
+  for (let i = 1; i < nextPhases.length && selected.size < maxPhases; i++) {
+    selected.add(nextPhases[i]);
+  }
+
+  // If still room, extend backward
+  for (let i = 1; i < prevPhases.length && selected.size < maxPhases; i++) {
+    selected.add(prevPhases[i]);
+  }
+
+  return Array.from(selected).sort((a, b) => a - b);
+}
+
+/**
+ * Load all PLAN-*.md files from a phase directory.
+ * @param {string} phaseDir - full path to phase directory
+ * @returns {Array<{ planId: string, content: string }>}
+ */
+function loadPlansFromDir(phaseDir) {
+  try {
+    const files = fs.readdirSync(phaseDir)
+      .filter(f => /^PLAN-\d+\.md$/i.test(f))
+      .sort();
+
+    return files.map(f => ({
+      planId: f.replace(/\.md$/i, ''),
+      content: fs.readFileSync(path.join(phaseDir, f), 'utf8'),
+    }));
+  } catch (_e) {
+    logHook('gate:multi-phase-loader', 'debug', 'Failed to read plans from phase dir', { error: _e.message, phaseDir });
+    return [];
+  }
+}
+
+module.exports = { loadMultiPhasePlans };

package/plugins/pbr/scripts/lib/gates/plan-executor.js

@@ -0,0 +1,36 @@
+'use strict';
+
+/**
+ * Gate: plan skill executor block.
+ * The plan skill should never spawn executors.
+ */
+
+const path = require('path');
+const { readActiveSkill } = require('./helpers');
+
+/**
+ * Blocking check: when the active skill is "plan", block executor spawning.
+ * Returns { block: true, reason: "..." } if blocked, or null if OK.
+ * @param {object} data - hook data with tool_input
+ * @returns {{ block: boolean, reason: string }|null}
+ */
+function checkPlanExecutorGate(data) {
+  const toolInput = data.tool_input || {};
+  const subagentType = toolInput.subagent_type || '';
+
+  // Only gate pbr:executor
+  if (subagentType !== 'pbr:executor') return null;
+
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+
+  const activeSkill = readActiveSkill(planningDir);
+  if (activeSkill !== 'plan') return null;
+
+  return {
+    block: true,
+    reason: 'Plan skill cannot spawn executors.\n\nThe plan skill creates plans; the build skill executes them. Spawning an executor from the plan skill violates the separation of concerns.\n\nRun /pbr:execute-phase to execute plans instead.'
+  };
+}
+
+module.exports = { checkPlanExecutorGate };

package/plugins/pbr/scripts/lib/gates/plan-validation.js

@@ -0,0 +1,115 @@
+'use strict';
+
+/**
+ * Gate: plan-validation artifact check.
+ * When active skill is "build" and pbr:executor is spawned, verify
+ * that .plan-check.json exists in the phase directory with status: "passed".
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { readActiveSkill, readCurrentPhase } = require('./helpers');
+const { logHook } = require('../../hook-logger');
+
+/**
+ * Blocking check: when the active skill is "build" and an executor is being
+ * spawned, verify that .plan-check.json exists and has status === "passed".
+ * Returns { block: true, reason: "..." } if blocked,
+ *         { warning: "..." } if advisory (quick depth),
+ *         or null if OK.
+ * @param {object} data - hook data with tool_input
+ * @returns {{ block: boolean, reason: string }|{ warning: string }|null}
+ */
+function checkPlanValidationGate(data) {
+  const toolInput = data.tool_input || {};
+  const subagentType = toolInput.subagent_type || '';
+
+  // Only gate pbr:executor
+  if (subagentType !== 'pbr:executor') return null;
+
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+
+  // Only gate when active skill is "build"
+  const activeSkill = readActiveSkill(planningDir);
+  if (activeSkill !== 'build') return null;
+
+  // Allow inline execution bypass
+  try {
+    if (fs.existsSync(path.join(planningDir, '.inline-active'))) {
+      return null;
+    }
+  } catch (_e) { /* intentionally silent: .inline-active file may not exist */ }
+
+  // Read STATE.md for current phase
+  const currentPhase = readCurrentPhase(planningDir);
+  if (!currentPhase) return null;
+
+  try {
+    const phasesDir = path.join(planningDir, 'phases');
+    if (!fs.existsSync(phasesDir)) return null;
+
+    const dirs = fs.readdirSync(phasesDir).filter(d => d.startsWith(currentPhase + '-'));
+    if (dirs.length === 0) return null;
+
+    const phaseDir = path.join(phasesDir, dirs[0]);
+
+    // Skip gate if no PLAN files exist (empty/speculative phase dir)
+    const files = fs.readdirSync(phaseDir);
+    const hasPlanFiles = files.some(f => /^PLAN.*\.md$/i.test(f));
+    if (!hasPlanFiles) return null;
+
+    const checkFile = path.join(phaseDir, '.plan-check.json');
+
+    // Read depth from config
+    let depth = 'standard';
+    try {
+      const configPath = path.join(planningDir, 'config.json');
+      const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+      if (config.depth) depth = config.depth;
+    } catch (_e) { /* intentionally silent: config.json may not exist, default to standard */ }
+
+    // Check if .plan-check.json exists
+    if (!fs.existsSync(checkFile)) {
+      if (depth === 'quick') {
+        return { warning: 'Plan validation advisory (quick depth) — .plan-check.json missing. Run /pbr:plan-phase to generate it.' };
+      }
+      return { block: true, reason: `Cannot spawn executor: .plan-check.json not found in phase directory.\n\nThe build gate requires a passing plan-check artifact before executor spawn. This artifact is written by the plan-checker agent during /pbr:plan-phase.\n\nRun /pbr:plan-phase ${currentPhase} with plan-checker enabled first.` };
+    }
+
+    // Parse the JSON
+    const checkData = JSON.parse(fs.readFileSync(checkFile, 'utf8'));
+
+    if (checkData.status !== 'passed') {
+      if (depth === 'quick') {
+        return { warning: 'Plan validation advisory (quick depth) — plan-check has unresolved issues (status: ' + checkData.status + '). Review recommended before building.' };
+      }
+      return {
+        block: true,
+        reason: `Cannot spawn executor: plan validation failed.\n\nThe plan-check artifact indicates unresolved issues (status: ${checkData.status}, blockers: ${checkData.blockers || 0}). Plans must pass validation before executors can run.\n\nFix plan issues and re-run /pbr:plan-phase ${currentPhase}.`
+      };
+    }
+
+    // Check requirements coverage
+    if (checkData.requirements_coverage) {
+      const rc = checkData.requirements_coverage;
+      if (Array.isArray(rc.uncovered) && rc.uncovered.length > 0) {
+        if (depth === 'quick') {
+          return { warning: `Requirements coverage incomplete (${rc.covered}/${rc.total}) — uncovered: ${rc.uncovered.join(', ')}` };
+        }
+        return {
+          block: true,
+          reason: `Cannot spawn executor: requirements coverage incomplete.\n\n${rc.uncovered.length} requirement(s) not covered by any plan's implements field: ${rc.uncovered.join(', ')}.\n\nAdd missing requirements to plan implements: fields and re-run /pbr:plan-phase.`
+        };
+      }
+    }
+
+    // status === "passed" — allow
+    return null;
+  } catch (_e) {
+    logHook('gate:plan-validation', 'warn', 'PlanValidation gate check crashed', { error: _e.message });
+    return null;
+  }
+}
+
+module.exports = { checkPlanValidationGate };

package/plugins/pbr/scripts/lib/gates/quick-executor.js

@@ -0,0 +1,78 @@
+'use strict';
+
+/**
+ * Gate: quick executor PLAN.md check.
+ * When active skill is "quick" and pbr:executor is spawned, verify
+ * that at least one .planning/quick/{NNN}-{slug}/PLAN.md exists.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { readActiveSkill } = require('./helpers');
+const { logHook } = require('../../hook-logger');
+
+/**
+ * Blocking check: when the active skill is "quick" and an executor is being
+ * spawned, verify that at least one .planning/quick/{NNN}-{slug}/PLAN.md exists.
+ * Returns { block: true, reason: "..." } if the executor should be blocked,
+ * or null if it's OK to proceed.
+ * @param {object} data - hook data with tool_input
+ * @returns {{ block: boolean, reason: string }|null}
+ */
+function checkQuickExecutorGate(data) {
+  const toolInput = data.tool_input || {};
+  const subagentType = toolInput.subagent_type || '';
+
+  // Only gate pbr:executor
+  if (subagentType !== 'pbr:executor') return null;
+
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+
+  // Only gate when active skill is "quick"
+  const activeSkill = readActiveSkill(planningDir);
+  if (activeSkill !== 'quick') return null;
+
+  // Check for any PLAN.md in .planning/quick/*/
+  const quickDir = path.join(planningDir, 'quick');
+  if (!fs.existsSync(quickDir)) {
+    return {
+      block: true,
+      reason: 'Cannot spawn executor: .planning/quick/ directory does not exist.\n\nThe quick skill must create the task directory and PLAN.md before an executor can run (Steps 4-6).\n\nRe-run /pbr:quick to create the quick task directory and PLAN.md.'
+    };
+  }
+
+  try {
+    const dirs = fs.readdirSync(quickDir).filter(d => {
+      return /^\d{3}-/.test(d) && fs.statSync(path.join(quickDir, d)).isDirectory();
+    });
+
+    // Look for the most recent quick task dir that has a PLAN.md
+    const hasPlan = dirs.some(d => {
+      const planFile = path.join(quickDir, d, 'PLAN.md');
+      try {
+        const stat = fs.statSync(planFile);
+        return stat.size > 0;
+      } catch (_e) {
+        return false;
+      }
+    });
+
+    if (!hasPlan) {
+      return {
+        block: true,
+        reason: 'Cannot spawn executor: no PLAN.md found in any .planning/quick/*/ directory.\n\nThe quick skill must write a non-empty PLAN.md inside .planning/quick/{NNN}-{slug}/ before an executor can run (Steps 4-6).\n\nRe-run /pbr:quick to create the quick task directory and PLAN.md.'
+      };
+    }
+  } catch (_e) {
+    logHook('gate:quick-executor', 'warn', 'QuickExecutor gate check crashed', { error: _e.message });
+    return {
+      block: true,
+      reason: 'Cannot spawn executor: failed to read .planning/quick/ directory.\n\nThe directory exists but could not be read, possibly due to a permissions issue or filesystem error.\n\nRe-run /pbr:quick to recreate the quick task directory and PLAN.md.'
+    };
+  }
+
+  return null;
+}
+
+module.exports = { checkQuickExecutorGate };

package/plugins/pbr/scripts/lib/gates/review-planner.js

@@ -0,0 +1,63 @@
+'use strict';
+
+/**
+ * Gate: review planner VERIFICATION.md check.
+ * When active skill is "review" and pbr:planner is spawned, verify
+ * that a VERIFICATION.md exists in the current phase directory.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { readActiveSkill, readCurrentPhase } = require('./helpers');
+const { logHook } = require('../../hook-logger');
+
+/**
+ * Blocking check: when the active skill is "review" and a planner is being
+ * spawned, verify that a VERIFICATION.md exists in the current phase directory.
+ * Returns { block: true, reason: "..." } if blocked, or null if OK.
+ * @param {object} data - hook data with tool_input
+ * @returns {{ block: boolean, reason: string }|null}
+ */
+function checkReviewPlannerGate(data) {
+  const toolInput = data.tool_input || {};
+  const subagentType = toolInput.subagent_type || '';
+
+  // Only gate pbr:planner
+  if (subagentType !== 'pbr:planner') return null;
+
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+
+  // Only gate when active skill is "review"
+  const activeSkill = readActiveSkill(planningDir);
+  if (activeSkill !== 'review') return null;
+
+  // Read STATE.md for current phase
+  const currentPhase = readCurrentPhase(planningDir);
+  if (!currentPhase) return null;
+
+  try {
+    const phasesDir = path.join(planningDir, 'phases');
+    if (!fs.existsSync(phasesDir)) return null;
+
+    const dirs = fs.readdirSync(phasesDir).filter(d => d.startsWith(currentPhase + '-'));
+    if (dirs.length === 0) return null;
+
+    const phaseDir = path.join(phasesDir, dirs[0]);
+    const hasVerification = fs.existsSync(path.join(phaseDir, 'VERIFICATION.md'));
+
+    if (!hasVerification) {
+      return {
+        block: true,
+        reason: 'Review planner gate: cannot spawn planner without VERIFICATION.md.\n\nGap closure requires an existing VERIFICATION.md to identify which gaps need closing. Without it, the planner has no input.\n\nRun /pbr:verify-work {N} to create VERIFICATION.md first.'
+      };
+    }
+  } catch (_e) {
+    logHook('gate:review-planner', 'warn', 'ReviewPlanner gate check crashed', { error: _e.message });
+    return null;
+  }
+
+  return null;
+}
+
+module.exports = { checkReviewPlannerGate };

package/plugins/pbr/scripts/lib/gates/review-verifier.js

@@ -0,0 +1,71 @@
+'use strict';
+
+/**
+ * Gate: review verifier SUMMARY.md check.
+ * When active skill is "review" and pbr:verifier is spawned, verify
+ * that a SUMMARY*.md exists in the current phase directory.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { readActiveSkill, readCurrentPhase } = require('./helpers');
+const { logHook } = require('../../hook-logger');
+
+/**
+ * Blocking check: when the active skill is "review" and a verifier is being
+ * spawned, verify that a SUMMARY*.md exists in the current phase directory.
+ * Returns { block: true, reason: "..." } if blocked, or null if OK.
+ * @param {object} data - hook data with tool_input
+ * @returns {{ block: boolean, reason: string }|null}
+ */
+function checkReviewVerifierGate(data) {
+  const toolInput = data.tool_input || {};
+  const subagentType = toolInput.subagent_type || '';
+
+  // Only gate pbr:verifier
+  if (subagentType !== 'pbr:verifier') return null;
+
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+
+  // Only gate when active skill is "review"
+  const activeSkill = readActiveSkill(planningDir);
+  if (activeSkill !== 'review') return null;
+
+  // Read STATE.md for current phase
+  const currentPhase = readCurrentPhase(planningDir);
+  if (!currentPhase) return null;
+
+  try {
+    const phasesDir = path.join(planningDir, 'phases');
+    if (!fs.existsSync(phasesDir)) return null;
+
+    const dirs = fs.readdirSync(phasesDir).filter(d => d.startsWith(currentPhase + '-'));
+    if (dirs.length === 0) return null;
+
+    const phaseDir = path.join(phasesDir, dirs[0]);
+    const files = fs.readdirSync(phaseDir);
+    const hasSummary = files.some(f => {
+      if (!/^SUMMARY/i.test(f)) return false;
+      try {
+        return fs.statSync(path.join(phaseDir, f)).size > 0;
+      } catch (_e) {
+        return false;
+      }
+    });
+
+    if (!hasSummary) {
+      return {
+        block: true,
+        reason: 'Review verifier gate: cannot spawn verifier without SUMMARY.md.\n\nThe verifier checks executor output against the plan. Without a SUMMARY.md, there is nothing to verify.\n\nRun /pbr:execute-phase {N} to create SUMMARY.md first.'
+      };
+    }
+  } catch (_e) {
+    logHook('gate:review-verifier', 'warn', 'ReviewVerifier gate check crashed', { error: _e.message });
+    return null;
+  }
+
+  return null;
+}
+
+module.exports = { checkReviewVerifierGate };

package/plugins/pbr/scripts/lib/gates/rich-agent-context.js

@@ -0,0 +1,148 @@
+'use strict';
+
+/**
+ * Rich Agent Context Builder
+ *
+ * Builds a prioritized context string from .planning/ sources for enriching
+ * Task() spawn prompts. Respects the rich_agent_prompts feature toggle and
+ * a configurable character budget.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { extractFrontmatter } = require('../frontmatter');
+const { logHook } = require('../../hook-logger');
+
+/**
+ * Build a rich context string from .planning/ sources.
+ * Sections are built in priority order (highest first). If total exceeds
+ * budgetChars, lowest-priority sections are dropped.
+ *
+ * @param {string} planningDir - path to .planning directory
+ * @param {object} config - project config object
+ * @param {number} [budgetChars=5000] - maximum character budget
+ * @returns {string} context string or empty string if disabled
+ */
+function buildRichAgentContext(planningDir, config, budgetChars = 5000) {
+  // Check feature toggle — only explicitly false disables it
+  if (config && config.features && config.features.rich_agent_prompts === false) {
+    return '';
+  }
+
+  const sections = [];
+
+  // 1. Project summary (highest priority)
+  try {
+    const projectPath = path.join(planningDir, 'PROJECT.md');
+    if (fs.existsSync(projectPath)) {
+      const content = fs.readFileSync(projectPath, 'utf8');
+      const lines = content.split(/\r?\n/).slice(0, 20);
+      sections.push({ priority: 1, header: '### Project Summary', body: lines.join('\n') });
+    }
+  } catch (_e) {
+    logHook('gate:rich-agent-context', 'debug', 'Failed to read PROJECT.md', { error: _e.message });
+  }
+
+  // 2. Current state from STATE.md frontmatter
+  try {
+    const statePath = path.join(planningDir, 'STATE.md');
+    if (fs.existsSync(statePath)) {
+      const content = fs.readFileSync(statePath, 'utf8');
+      const stateInfo = parseStateFrontmatter(content);
+      if (stateInfo) {
+        sections.push({ priority: 2, header: '### Current State', body: stateInfo });
+      }
+    }
+  } catch (_e) {
+    logHook('gate:rich-agent-context', 'debug', 'Failed to read STATE.md', { error: _e.message });
+  }
+
+  // 3. Recent decisions (up to 5 most recent)
+  try {
+    const decisionsDir = path.join(planningDir, 'decisions');
+    if (fs.existsSync(decisionsDir)) {
+      const files = fs.readdirSync(decisionsDir)
+        .filter(f => f.endsWith('.md'))
+        .sort()
+        .slice(-5);
+      if (files.length > 0) {
+        const titles = files.map(f => `- ${f.replace(/\.md$/, '')}`).join('\n');
+        sections.push({ priority: 3, header: '### Recent Decisions', body: titles });
+      }
+    }
+  } catch (_e) {
+    logHook('gate:rich-agent-context', 'debug', 'Failed to read decisions dir', { error: _e.message });
+  }
+
+  // 4. Active conventions
+  try {
+    const convDir = path.join(planningDir, 'conventions');
+    if (fs.existsSync(convDir)) {
+      const files = fs.readdirSync(convDir)
+        .filter(f => f.endsWith('.md'))
+        .sort();
+      if (files.length > 0) {
+        const titles = files.map(f => `- ${f.replace(/\.md$/, '')}`).join('\n');
+        sections.push({ priority: 4, header: '### Active Conventions', body: titles });
+      }
+    }
+  } catch (_e) {
+    logHook('gate:rich-agent-context', 'debug', 'Failed to read conventions dir', { error: _e.message });
+  }
+
+  // 5. Working set from STATE.md (lowest priority)
+  try {
+    const statePath = path.join(planningDir, 'STATE.md');
+    if (fs.existsSync(statePath)) {
+      const content = fs.readFileSync(statePath, 'utf8');
+      const wsMatch = content.match(/working_set:\s*\n((?:\s+-\s+.+\n?)+)/);
+      if (wsMatch) {
+        sections.push({ priority: 5, header: '### Working Set', body: wsMatch[1].trim() });
+      }
+    }
+  } catch (_e) {
+    logHook('gate:rich-agent-context', 'debug', 'Failed to read STATE.md working set', { error: _e.message });
+  }
+
+  // Assemble with budget control — drop lowest priority sections first
+  // Sort by priority (ascending = highest priority first)
+  sections.sort((a, b) => a.priority - b.priority);
+
+  let result = '';
+  for (const section of sections) {
+    const addition = `${section.header}\n${section.body}\n\n`;
+    if ((result + addition).length > budgetChars) {
+      // Try truncating just this section's body to fit
+      const remaining = budgetChars - result.length - section.header.length - 2; // 2 for \n after header + \n at end
+      if (remaining > 20) {
+        result += `${section.header}\n${section.body.slice(0, remaining - 3)}...`;
+      }
+      break; // Don't add any more sections
+    }
+    result += addition;
+  }
+
+  return result.trimEnd();
+}
+
+/**
+ * Parse STATE.md frontmatter for key state info.
+ * @param {string} content - STATE.md content
+ * @returns {string|null} formatted state info or null
+ */
+/**
+ * Parse STATE.md and format as a human-readable string.
+ * Delegates to canonical parseStateMd from lib/state.js.
+ */
+const parseStateFrontmatter = (content) => {
+  const fm = extractFrontmatter(content);
+  if (!fm || (!fm.current_phase && !fm.status)) return null;
+  const parts = [];
+  if (fm.current_phase) parts.push(`Phase: ${fm.current_phase}`);
+  if (fm.status) parts.push(`Status: ${fm.status}`);
+  if (fm.progress_percent) parts.push(`Progress: ${fm.progress_percent}%`);
+  if (fm.phase_slug) parts.push(`Phase: ${fm.phase_slug}`);
+  return parts.length > 0 ? parts.join('\n') : null;
+};
+
+module.exports = { buildRichAgentContext };