@sienklogic/plan-build-run 2.21.0 → 2.21.2

package/plugins/pbr/scripts/hooks-schema.json

@@ -10,6 +10,7 @@
       "type": "object",
       "properties": {
         "SessionStart": { "$ref": "#/definitions/hookEntryList" },
+        "InstructionsLoaded": { "$ref": "#/definitions/hookEntryList" },
         "PreToolUse": { "$ref": "#/definitions/hookEntryList" },
         "PostToolUse": { "$ref": "#/definitions/hookEntryList" },
         "PostToolUseFailure": { "$ref": "#/definitions/hookEntryList" },
@@ -19,7 +20,9 @@
         "SubagentStop": { "$ref": "#/definitions/hookEntryList" },
         "TaskCompleted": { "$ref": "#/definitions/hookEntryList" },
         "ConfigChange": { "$ref": "#/definitions/hookEntryList" },
-        "SessionEnd": { "$ref": "#/definitions/hookEntryList" }
+        "SessionEnd": { "$ref": "#/definitions/hookEntryList" },
+        "WorktreeCreate": { "$ref": "#/definitions/hookEntryList" },
+        "WorktreeRemove": { "$ref": "#/definitions/hookEntryList" }
       },
       "additionalProperties": false
     }
@@ -51,12 +54,16 @@
       "properties": {
         "type": {
           "type": "string",
-          "enum": ["command"],
-          "description": "Hook type — currently only 'command' is supported"
+          "enum": ["command", "http"],
+          "description": "Hook type — 'command' spawns a process, 'http' sends POST to a URL"
         },
         "command": {
           "type": "string",
-          "description": "Shell command to execute (use ${CLAUDE_PLUGIN_ROOT} for script paths)"
+          "description": "Shell command to execute (use ${CLAUDE_PLUGIN_ROOT} for script paths). Required when type is 'command'."
+        },
+        "url": {
+          "type": "string",
+          "description": "HTTP endpoint URL for type: http hooks (e.g. http://127.0.0.1:19836/hook/PostToolUse/Write). Required when type is 'http'."
         },
         "statusMessage": {
           "type": "string",
@@ -73,7 +80,7 @@
           "description": "Maximum seconds before hook is killed (required when async: true)"
         }
       },
-      "required": ["type", "command"],
+      "required": ["type"],
       "additionalProperties": false
     }
   }

package/plugins/pbr/scripts/instructions-loaded.js

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+
+/**
+ * InstructionsLoaded hook: Lightweight PBR state reminder after CLAUDE.md loads.
+ *
+ * Fires each time Claude Code loads CLAUDE.md or .claude/rules/*.md files.
+ * For PBR projects: injects a brief reminder that PBR workflow is active.
+ * Debounces mid-session re-fires using .session.json load timestamp.
+ *
+ * Non-blocking — always exits 0.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+const { resolveSessionPath } = require('./lib/core');
+
+function readStdin() {
+  try {
+    const input = fs.readFileSync(0, 'utf8').trim();
+    if (input) return JSON.parse(input);
+  } catch (_e) { /* empty or non-JSON stdin */ }
+  return {};
+}
+
+function main() {
+  const data = readStdin();
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+
+  // Only relevant for PBR projects
+  if (!fs.existsSync(planningDir)) {
+    process.exit(0);
+  }
+
+  // Debounce: only emit additionalContext on first fire per session.
+  // .session.json is written by progress-tracker.js at SessionStart.
+  // If it exists with a sessionStart timestamp, this is a mid-session reload.
+  const sessionId = data.session_id || null;
+  let isMidSession = false;
+  try {
+    const sessionFile = sessionId
+      ? resolveSessionPath(planningDir, '.session.json', sessionId)
+      : path.join(planningDir, '.session.json');
+    if (fs.existsSync(sessionFile)) {
+      const session = JSON.parse(fs.readFileSync(sessionFile, 'utf8'));
+      if (session.sessionStart) {
+        isMidSession = true;
+      }
+    }
+  } catch (_e) { /* non-fatal */ }
+
+  logHook('instructions-loaded', 'InstructionsLoaded', isMidSession ? 'mid-session-reload' : 'initial-load', {
+    instructions_file: data.instructions_file || null
+  });
+
+  // Track hook count changes across reloads
+  try {
+    const hookCountFile = path.join(planningDir, '.hook-count');
+    const hooksJsonPath = path.join(__dirname, '..', 'hooks', 'hooks.json');
+    const altHooksPath = path.join(__dirname, 'hooks.json');
+    const hooksPath = fs.existsSync(hooksJsonPath) ? hooksJsonPath : (fs.existsSync(altHooksPath) ? altHooksPath : null);
+    if (hooksPath) {
+      const hooksConfig = JSON.parse(fs.readFileSync(hooksPath, 'utf8'));
+      let currentCount = 0;
+      for (const event of Object.values(hooksConfig)) {
+        if (Array.isArray(event)) currentCount += event.length;
+      }
+
+      if (fs.existsSync(hookCountFile)) {
+        const previousCount = parseInt(fs.readFileSync(hookCountFile, 'utf8').trim(), 10);
+        if (!isNaN(previousCount) && currentCount < previousCount) {
+          logHook('instructions-loaded', 'InstructionsLoaded', 'hook-count-decreased', {
+            previous: previousCount,
+            current: currentCount,
+            lost: previousCount - currentCount
+          });
+          const warning = `[PBR] Hook count decreased after reload: ${previousCount} -> ${currentCount} (${previousCount - currentCount} hooks lost). Some workflow enforcement may be degraded. Run /pbr:health to check.`;
+          process.stdout.write(JSON.stringify({ additionalContext: warning }));
+          fs.writeFileSync(hookCountFile, String(currentCount));
+          process.exit(0);
+        }
+      }
+      // Save current count for future comparison
+      fs.writeFileSync(hookCountFile, String(currentCount));
+    }
+  } catch (_e) {
+    // Never crash the hook for hook-count tracking
+  }
+
+  // Mid-session: note that instructions reloaded (CLAUDE.md may have changed)
+  if (isMidSession) {
+    process.stdout.write(JSON.stringify({
+      additionalContext: '[Plan-Build-Run] Project CLAUDE.md was reloaded mid-session. If PBR workflow rules changed, current skill invocation may be affected. Check .planning/STATE.md for current position.'
+    }));
+    process.exit(0);
+  }
+
+  // Initial load: no additionalContext needed — progress-tracker.js already
+  // injected full state at SessionStart. Avoid double-injection.
+  process.exit(0);
+}
+
+/**
+ * handleHttp — hook-server.js interface.
+ * reqBody = { event, tool, data, planningDir, cache }
+ * Returns { additionalContext: "..." } or null. Never calls process.exit().
+ */
+function handleHttp(reqBody) {
+  const data = (reqBody && reqBody.data) || {};
+  const planningDir = reqBody && reqBody.planningDir;
+  if (!planningDir || !fs.existsSync(planningDir)) return null;
+
+  const sessionId = data.session_id || null;
+  let isMidSession = false;
+  try {
+    const sessionFile = sessionId
+      ? resolveSessionPath(planningDir, '.session.json', sessionId)
+      : path.join(planningDir, '.session.json');
+    if (fs.existsSync(sessionFile)) {
+      const session = JSON.parse(fs.readFileSync(sessionFile, 'utf8'));
+      if (session.sessionStart) isMidSession = true;
+    }
+  } catch (_e) { /* non-fatal */ }
+
+  logHook('instructions-loaded', 'InstructionsLoaded', isMidSession ? 'mid-session-reload' : 'initial-load', {
+    instructions_file: data.instructions_file || null
+  });
+
+  // Track hook count changes across reloads
+  try {
+    const hookCountFile = path.join(planningDir, '.hook-count');
+    const hooksJsonPath = path.join(__dirname, '..', 'hooks', 'hooks.json');
+    const altHooksPath = path.join(__dirname, 'hooks.json');
+    const hooksPath = fs.existsSync(hooksJsonPath) ? hooksJsonPath : (fs.existsSync(altHooksPath) ? altHooksPath : null);
+    if (hooksPath) {
+      const hooksConfig = JSON.parse(fs.readFileSync(hooksPath, 'utf8'));
+      let currentCount = 0;
+      for (const event of Object.values(hooksConfig)) {
+        if (Array.isArray(event)) currentCount += event.length;
+      }
+
+      if (fs.existsSync(hookCountFile)) {
+        const previousCount = parseInt(fs.readFileSync(hookCountFile, 'utf8').trim(), 10);
+        if (!isNaN(previousCount) && currentCount < previousCount) {
+          logHook('instructions-loaded', 'InstructionsLoaded', 'hook-count-decreased', {
+            previous: previousCount,
+            current: currentCount,
+            lost: previousCount - currentCount
+          });
+          const warning = `[PBR] Hook count decreased after reload: ${previousCount} -> ${currentCount} (${previousCount - currentCount} hooks lost). Some workflow enforcement may be degraded. Run /pbr:health to check.`;
+          fs.writeFileSync(hookCountFile, String(currentCount));
+          return { additionalContext: warning };
+        }
+      }
+      fs.writeFileSync(hookCountFile, String(currentCount));
+    }
+  } catch (_e) {
+    // Never crash the hook for hook-count tracking
+  }
+
+  if (isMidSession) {
+    return {
+      additionalContext: '[Plan-Build-Run] Project CLAUDE.md was reloaded mid-session. If PBR workflow rules changed, current skill invocation may be affected. Check .planning/STATE.md for current position.'
+    };
+  }
+  return null;
+}
+
+if (require.main === module || process.argv[1] === __filename) { main(); }
+module.exports = { main, handleHttp };

package/plugins/pbr/scripts/intent-router.cjs

@@ -0,0 +1,147 @@
+/**
+ * Intent router — classifies freeform text into PBR skill routes with confidence scoring.
+ *
+ * Pure function: no side effects, no file I/O. Consumable by /pbr:do and prompt-routing hook.
+ */
+
+'use strict';
+
+const ROUTE_MAP = {
+  debug: {
+    keywords: ['bug', 'error', 'crash', 'fix', 'broken', 'failing', 'exception', 'stacktrace', 'debug'],
+    weight: 1.0
+  },
+  explore: {
+    keywords: ['explore', 'research', 'investigate', 'how does', 'how do', 'how the', 'understand', 'analyze', 'compare', 'works'],
+    weight: 1.0
+  },
+  'plan-phase': {
+    keywords: ['plan', 'architect', 'design', 'migrate', 'refactor across', 'refactor', 'redesign', 'system', 'new'],
+    weight: 0.9
+  },
+  quick: {
+    keywords: ['add', 'create', 'update', 'change', 'rename', 'remove', 'write test', 'implement', 'button', 'feature', 'refactor'],
+    weight: 0.85
+  },
+  note: {
+    keywords: ['remember', 'note', 'todo', 'idea', 'later', "don't forget", 'remind'],
+    weight: 1.0
+  },
+  'verify-work': {
+    keywords: ['review', 'check', 'verify', 'quality', 'looks right'],
+    weight: 0.9
+  }
+};
+
+/**
+ * Score a single route against input text.
+ * Returns a value between 0 and 1 based on keyword match density and weight.
+ * @param {string} text - Lowercase normalized input
+ * @param {{ keywords: string[], weight: number }} routeConfig
+ * @returns {number} Score in 0-1 range
+ */
+function scoreRoute(text, routeConfig) {
+  let matches = 0;
+  for (const keyword of routeConfig.keywords) {
+    if (text.includes(keyword)) {
+      matches++;
+    }
+  }
+  if (matches === 0) return 0;
+
+  // Confidence based on match count:
+  // 1 match = 0.5, 2 matches = 0.75, 3+ matches = 0.95+
+  // Uses diminishing returns: 0.5 + 0.25 * (1 - 1/(matches+1))
+  const baseConfidence = 0.5 + 0.5 * (1 - 1 / (matches + 1));
+
+  return baseConfidence * routeConfig.weight;
+}
+
+/**
+ * Classify freeform text into a PBR skill route with confidence scoring.
+ *
+ * @param {string} text - User's natural language input
+ * @param {object} [context={}] - Optional context signals
+ * @param {string} [context.recentError] - Recent error message (boosts debug)
+ * @param {boolean} [context.activePhase] - Whether a phase is active (boosts plan-phase)
+ * @param {boolean} [context.hasRoadmap] - Whether a roadmap exists (demotes plan-phase if false)
+ * @returns {{ route: string, confidence: number, candidates: Array<{ route: string, confidence: number }> }}
+ */
+function classifyIntent(text, context) {
+  if (context === undefined) context = {};
+  const normalized = text.toLowerCase();
+
+  // Score each route
+  const scores = {};
+  for (const [route, config] of Object.entries(ROUTE_MAP)) {
+    scores[route] = scoreRoute(normalized, config);
+  }
+
+  // Apply context boosters
+  if (context.recentError) {
+    scores.debug = (scores.debug || 0) + 0.3;
+  }
+  if (context.activePhase) {
+    scores['plan-phase'] = (scores['plan-phase'] || 0) + 0.1;
+  }
+  if (context.hasRoadmap === false) {
+    scores['plan-phase'] = (scores['plan-phase'] || 0) - 0.2;
+  }
+
+  // Clamp all scores to 0-1
+  for (const route of Object.keys(scores)) {
+    scores[route] = Math.max(0, Math.min(1, scores[route]));
+  }
+
+  // Sort by score descending
+  const sorted = Object.entries(scores)
+    .map(([route, confidence]) => ({ route, confidence }))
+    .sort((a, b) => b.confidence - a.confidence);
+
+  // No matches at all
+  if (sorted.length === 0 || sorted[0].confidence === 0) {
+    return {
+      route: 'quick',
+      confidence: 0.3,
+      candidates: [{ route: 'quick', confidence: 0.3 }],
+      auditEntry: {
+        timestamp: new Date().toISOString(),
+        input: text.substring(0, 100),
+        route: 'quick',
+        confidence: 0.3,
+        risk: null
+      }
+    };
+  }
+
+  const top = sorted[0];
+
+  // Build audit entry for logging by callers
+  const auditEntry = {
+    timestamp: new Date().toISOString(),
+    input: text.substring(0, 100),
+    route: top.route,
+    confidence: top.confidence,
+    risk: null  // populated by caller when risk-classifier is used
+  };
+
+  if (top.confidence >= 0.7) {
+    return {
+      route: top.route,
+      confidence: top.confidence,
+      candidates: [top],
+      auditEntry
+    };
+  }
+
+  // Ambiguous — return top 3 candidates with non-zero confidence
+  const topThree = sorted.slice(0, 3).filter(c => c.confidence > 0);
+  return {
+    route: top.route,
+    confidence: top.confidence,
+    candidates: topThree,
+    auditEntry
+  };
+}
+
+module.exports = { classifyIntent, ROUTE_MAP };

package/plugins/pbr/scripts/intercept-plan-mode.js

@@ -4,44 +4,78 @@
  * PreToolUse hook on EnterPlanMode: Warns users in PBR projects that
  * native plan mode won't integrate with PBR's planning system.
  *
- * Suggests /pbr:plan instead. Does NOT block — just advises.
+ * Suggests /pbr:plan-phase instead. Does NOT block — just advises.
  *
  * Exit codes:
- *   0 = always (advisory only, never blocks)
+ *   0 = not a PBR project (passes through)
+ *   2 = blocked (PBR project detected — redirects to /pbr:plan-phase)
  */
 
 const fs = require('fs');
 const path = require('path');
 const { logHook } = require('./hook-logger');
 
+/**
+ * Core detection logic extracted for both stdin (main) and HTTP (handleHttp) paths.
+ *
+ * @param {Object} data - Parsed hook input (same as stdin JSON)
+ * @returns {Object|null} { decision: 'block', reason } if PBR project detected, null otherwise
+ */
+function checkPlanMode(data) {
+  const cwd = (data && data.cwd) || process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+
+  // Only relevant for Plan-Build-Run projects
+  if (!fs.existsSync(planningDir)) {
+    return null;
+  }
+
+  logHook('intercept-plan-mode', 'PreToolUse', 'warn', {
+    reason: 'native plan mode used in PBR project'
+  });
+
+  return {
+    decision: 'block',
+    reason: 'This is a Plan-Build-Run project. Native plan mode stores plans outside .planning/ and won\'t integrate with PBR\'s workflow.\n\nUse instead:\n  /pbr:plan-phase <phase>  — Create a PBR-formatted plan for a phase\n  /pbr:quick         — Plan and execute an ad-hoc task\n  /pbr:import        — Import an external plan document into PBR format\n\nIf you already generated a plan in native plan mode, paste it into /pbr:import to convert it.'
+  };
+}
+
+/**
+ * HTTP handler for hook-server.js.
+ * Called as handleHttp(reqBody, cache) where reqBody = { event, tool, data, planningDir, cache }.
+ * Must NOT call process.exit().
+ *
+ * @param {Object} reqBody - Request body from hook-server
+ * @param {Object} _cache - In-memory server cache (unused)
+ * @returns {Object|null} Hook response or null
+ */
+async function handleHttp(reqBody, _cache) {
+  try {
+    const data = (reqBody && reqBody.data) ? reqBody.data : {};
+    return checkPlanMode(data);
+  } catch (_e) {
+    return null;
+  }
+}
+
 function main() {
   process.stdin.setEncoding('utf8');
   process.stdin.on('data', () => {});
   process.stdin.on('end', () => {
     try {
-      const cwd = process.cwd();
-      const planningDir = path.join(cwd, '.planning');
-
-      // Only relevant for Plan-Build-Run projects
-      if (!fs.existsSync(planningDir)) {
+      const result = checkPlanMode({});
+      if (!result) {
         process.exit(0);
       }
-
-      logHook('intercept-plan-mode', 'PreToolUse', 'warn', {
-        reason: 'native plan mode used in PBR project'
-      });
-
-      const output = {
-        decision: 'block',
-        reason: 'This is a Plan-Build-Run project. Native plan mode stores plans outside .planning/ and won\'t integrate with PBR\'s workflow.\n\nUse instead:\n  /pbr:plan <phase>  — Create a PBR-formatted plan for a phase\n  /pbr:quick         — Plan and execute an ad-hoc task\n  /pbr:import        — Import an external plan document into PBR format\n\nIf you already generated a plan in native plan mode, paste it into /pbr:import to convert it.'
-      };
-      process.stdout.write(JSON.stringify(output));
+      process.stdout.write(JSON.stringify(result));
       process.exit(2);
     } catch (_e) {
+      process.stderr.write(`[pbr] intercept-plan-mode error: ${_e.message}\n`);
+      process.stdout.write(JSON.stringify({ decision: 'allow', additionalContext: '⚠ [PBR] intercept-plan-mode failed: ' + _e.message }));
       process.exit(0);
     }
   });
 }
 
 if (require.main === module || process.argv[1] === __filename) { main(); }
-module.exports = { main };
+module.exports = { main, checkPlanMode, handleHttp };

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

@@ -0,0 +1,203 @@
+'use strict';
+
+/**
+ * alternatives.js — Conversational error recovery helpers for PBR skills.
+ *
+ * Provides structured JSON responses for three error scenarios:
+ *   phaseAlternatives(slug, planningDir)      — phase-not-found recovery
+ *   prerequisiteAlternatives(phase, planningDir) — missing-prereq recovery
+ *   configAlternatives(field, value, planningDir) — config-invalid recovery
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Known config fields and their valid values
+const KNOWN_CONFIG_FIELDS = {
+  'depth': ['quick', 'standard', 'deep'],
+  'git.branching': ['phase', 'main', 'off'],
+  'gates.confirm_plan': [true, false, 'true', 'false'],
+  'gates.confirm_execute': [true, false, 'true', 'false'],
+  'gates.confirm_review': [true, false, 'true', 'false'],
+  'gates.confirm_milestone': [true, false, 'true', 'false'],
+  'parallelism': ['off', 'wave', 'full'],
+  'models.default': ['haiku', 'sonnet', 'inherit'],
+  'models.planner': ['haiku', 'sonnet', 'inherit'],
+  'models.executor': ['haiku', 'sonnet', 'inherit'],
+  'models.verifier': ['haiku', 'sonnet', 'inherit']
+};
+
+/**
+ * Score similarity between two strings using character overlap.
+ * Returns a value between 0 and 1 (higher = more similar).
+ *
+ * @param {string} a - First string
+ * @param {string} b - Second string
+ * @returns {number} Similarity score between 0 and 1
+ */
+function scoreSlug(a, b) {
+  if (!a || !b) return 0;
+  const lowerA = a.toLowerCase();
+  const lowerB = b.toLowerCase();
+  // Count shared characters (by frequency)
+  const freqA = {};
+  for (const ch of lowerA) freqA[ch] = (freqA[ch] || 0) + 1;
+  let shared = 0;
+  const freqB = {};
+  for (const ch of lowerB) freqB[ch] = (freqB[ch] || 0) + 1;
+  for (const ch of Object.keys(freqA)) {
+    if (freqB[ch]) shared += Math.min(freqA[ch], freqB[ch]);
+  }
+  // Also boost score when one string contains the other as substring
+  let substringBonus = 0;
+  if (lowerB.includes(lowerA) || lowerA.includes(lowerB)) substringBonus = 0.2;
+  const score = shared / Math.max(lowerA.length, lowerB.length) + substringBonus;
+  return Math.min(score, 1);
+}
+
+/**
+ * Generate alternatives for a phase-not-found error.
+ *
+ * @param {string} slug - The unknown phase slug
+ * @param {string} planningDir - Path to .planning directory
+ * @returns {{ error_type: string, slug: string, available: string[], suggestions: string[] }}
+ */
+function phaseAlternatives(slug, planningDir) {
+  const phasesDir = path.join(planningDir, 'phases');
+  let available = [];
+
+  try {
+    if (fs.existsSync(phasesDir)) {
+      const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+      available = entries
+        .filter(e => e.isDirectory())
+        .map(e => e.name);
+    }
+  } catch (_e) {
+    // If we can't read, return empty
+    available = [];
+  }
+
+  let suggestions = [];
+  if (slug && slug.length > 0 && available.length > 0) {
+    const scored = available
+      .map(name => ({ name, score: scoreSlug(slug, name) }))
+      .filter(s => s.score > 0.3)
+      .sort((a, b) => b.score - a.score)
+      .slice(0, 3)
+      .map(s => s.name);
+    suggestions = scored;
+  }
+
+  return {
+    error_type: 'phase-not-found',
+    slug,
+    available,
+    suggestions
+  };
+}
+
+/**
+ * Generate alternatives for a missing-prerequisite error.
+ *
+ * @param {string} phase - The phase slug to check
+ * @param {string} planningDir - Path to .planning directory
+ * @returns {{ error_type: string, phase: string, existing_summaries: string[], missing_summaries: string[], suggested_action: string }}
+ */
+function prerequisiteAlternatives(phase, planningDir) {
+  const phasesDir = path.join(planningDir, 'phases');
+
+  // Find the phase directory (exact match or prefix match)
+  let phaseDir = null;
+  try {
+    if (fs.existsSync(phasesDir)) {
+      const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+      const match = entries.find(e => e.isDirectory() && (e.name === phase || e.name.endsWith('-' + phase) || e.name === phase));
+      if (match) {
+        phaseDir = path.join(phasesDir, match.name);
+      } else {
+        // Try exact slug match
+        const exact = path.join(phasesDir, phase);
+        if (fs.existsSync(exact)) phaseDir = exact;
+      }
+    }
+  } catch (_e) { /* best effort */ }
+
+  const existing_summaries = [];
+  const missing_summaries = [];
+
+  if (phaseDir && fs.existsSync(phaseDir)) {
+    try {
+      const files = fs.readdirSync(phaseDir);
+      const planFiles = files.filter(f => /^PLAN-\d+\.md$/i.test(f));
+
+      for (const planFile of planFiles) {
+        // Extract plan ID from filename (e.g. PLAN-01.md → look for SUMMARY-{phase-num}-01.md)
+        const match = planFile.match(/^PLAN-(\d+)\.md$/i);
+        if (!match) continue;
+        const planNum = match[1];
+
+        // Check for any SUMMARY file matching this plan number
+        const summaryFiles = files.filter(f => {
+          const sm = f.match(/^SUMMARY[-.](.*?)\.md$/i);
+          if (!sm) return false;
+          return sm[1].endsWith('-' + planNum) || sm[1] === planNum;
+        });
+
+        if (summaryFiles.length > 0) {
+          existing_summaries.push(summaryFiles[0]);
+        } else {
+          // Infer the expected plan ID from directory name prefix + plan number
+          const dirMatch = (phaseDir.split(path.sep).pop() || '').match(/^(\d+)-/);
+          const phaseNum = dirMatch ? dirMatch[1] : '';
+          const expectedId = phaseNum ? `${phaseNum}-${planNum}` : planNum;
+          missing_summaries.push(`SUMMARY-${expectedId}.md`);
+        }
+      }
+    } catch (_e) { /* best effort */ }
+  }
+
+  return {
+    error_type: 'missing-prereq',
+    phase,
+    existing_summaries,
+    missing_summaries,
+    suggested_action: `Run /pbr:execute-phase ${phase} to generate missing summaries`
+  };
+}
+
+/**
+ * Generate alternatives for a config-invalid error.
+ *
+ * @param {string} field - The config field name
+ * @param {string} value - The current invalid value
+ * @param {string} _planningDir - Path to .planning directory (unused, for API consistency)
+ * @returns {{ error_type: string, field: string, current_value: string, valid_values: Array, suggested_fix: string }}
+ */
+function configAlternatives(field, value, _planningDir) {
+  const knownValues = KNOWN_CONFIG_FIELDS[field];
+
+  if (knownValues !== undefined) {
+    // Convert to string representations for JSON output
+    const validStrings = knownValues
+      .filter(v => typeof v === 'string')
+      .filter((v, i, arr) => arr.indexOf(v) === i); // dedupe
+    return {
+      error_type: 'config-invalid',
+      field,
+      current_value: value,
+      valid_values: validStrings.length > 0 ? validStrings : knownValues.filter(v => typeof v !== 'boolean'),
+      suggested_fix: `Set ${field} to one of: ${validStrings.join(', ')}`
+    };
+  }
+
+  return {
+    error_type: 'config-invalid',
+    field,
+    current_value: value,
+    valid_values: [],
+    suggested_fix: 'Remove this field from config.json or check spelling'
+  };
+}
+
+module.exports = { phaseAlternatives, prerequisiteAlternatives, configAlternatives };