@sienklogic/plan-build-run 2.18.1 → 2.19.1

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

@@ -0,0 +1,254 @@
+'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:        thresholds scale with context_window_tokens from config
+ *                     (default 200k tokens: < 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
+
+const BASE_TOKENS = 200000;
+const BASE_CHARS = BASE_TOKENS * 4; // 800000
+
+/**
+ * Get heuristic thresholds scaled to context_window_tokens from config.
+ * Base thresholds at 200k tokens: proceed=30000, checkpoint=60000, compact=100000.
+ *
+ * @param {string} planningDir - Path to .planning/
+ * @returns {{ proceed: number, checkpoint: number, compact: number }}
+ */
+function getHeuristicThresholds(planningDir) {
+  try {
+    const { configLoad } = require('../pbr-tools');
+    const config = configLoad(planningDir);
+    const tokens = (config && config.context_window_tokens) || BASE_TOKENS;
+    const scale = (tokens * 4) / BASE_CHARS;
+    return {
+      proceed: Math.round(30000 * scale),
+      checkpoint: Math.round(60000 * scale),
+      compact: Math.round(100000 * scale)
+    };
+  } catch (_e) {
+    return { proceed: 30000, checkpoint: 60000, compact: 100000 };
+  }
+}
+
+/**
+ * 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;
+
+  // Load adaptive thresholds for bridge percentage decisions
+  let bridgeThresholds = { degrading: 50, poor: 70 };
+  try {
+    const { getEffectiveThresholds } = require('../context-bridge');
+    const eff = getEffectiveThresholds(pd);
+    bridgeThresholds = { degrading: eff.degrading, poor: eff.poor };
+  } catch (_e) { /* use defaults */ }
+
+  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 < bridgeThresholds.degrading) {
+      recommendation = 'PROCEED';
+    } else if (percentage <= bridgeThresholds.poor) {
+      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;
+
+    const thresholds = getHeuristicThresholds(pd);
+    if (totalChars < thresholds.proceed) {
+      recommendation = 'PROCEED';
+    } else if (totalChars <= thresholds.checkpoint) {
+      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-work 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, getHeuristicThresholds };

package/plugins/pbr/scripts/lib/contextual-help.js

@@ -0,0 +1,207 @@
+'use strict';
+
+/**
+ * lib/contextual-help.cjs — Activity-aware contextual help suggestions.
+ *
+ * Reads STATE.md status and recent hook logs to produce workflow-relevant
+ * suggestions for the current development activity.
+ *
+ * Provides:
+ *   getContextualHelp(planningDir, config) — suggestions based on current state
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ─── Help templates ────────────────────────────────────────────────────────────
+
+const HELP_TEMPLATES = {
+  planning: [
+    'Use /pbr:plan-phase to start or refine the plan for the current phase.',
+    'Check .planning/ROADMAP.md to confirm phase dependencies before planning.',
+    'Use /pbr:discuss to talk through design decisions before committing to a plan.',
+    'Ensure PLAN.md tasks have clear <files>, <action>, and <verify> elements.',
+    'Run `pbr-tools validate health` to confirm .planning/ integrity before building.',
+  ],
+  building: [
+    'Follow TDD: write failing tests first (RED), then implement (GREEN), then clean up (REFACTOR).',
+    'Use atomic commits — one task per commit with `feat/fix/test({scope}): description` format.',
+    'After each task, run the <verify> command from the plan to confirm correctness.',
+    'Use /pbr:do for small inline tasks, /pbr:build for full phase execution.',
+    'Check STATE.md blockers field if the build appears stuck.',
+  ],
+  executing: [
+    'Follow TDD: write failing tests first (RED), then implement (GREEN), then clean up (REFACTOR).',
+    'Use atomic commits — one task per commit with `feat/fix/test({scope}): description` format.',
+    'After each task, run the <verify> command from the plan to confirm correctness.',
+    'Check STATE.md blockers field if the build appears stuck.',
+    'Run `pbr-tools validate health` periodically to detect drift.',
+  ],
+  verifying: [
+    'Use /pbr:review to run the verifier agent on a completed plan.',
+    'Check must_haves in PLAN.md frontmatter — all must be DONE in SUMMARY.md.',
+    'Run `pbr-tools verify plan-structure <plan-file>` for structural validation.',
+    'Check key_links: each link should be verifiable with grep commands.',
+    'Review VERIFICATION.md if present for prior verifier findings.',
+  ],
+  blocked: [
+    'Use /pbr:debug to diagnose failing tests or broken builds.',
+    'Check STATE.md blockers array for the root cause.',
+    'Run `pbr-tools validate health` to identify .planning/ integrity issues.',
+    'Check .planning/logs/hooks.jsonl for recent hook errors.',
+    'Consider /pbr:discuss to think through the blocker before coding.',
+  ],
+  default: [
+    'Use /pbr:status to get a current project overview.',
+    'Run `pbr-tools validate health` to check .planning/ integrity.',
+    'Use /pbr:plan-phase to plan the next phase.',
+    'Use /pbr:build to execute the current phase.',
+    'Run `pbr-tools suggest-next` for a routing recommendation.',
+  ],
+  blocker_extra: [
+    'A blocker is preventing progress. Use /pbr:debug for diagnosis.',
+    'Check .planning/logs/hooks.jsonl for error patterns.',
+    'Consider reaching a CHECKPOINT if the blocker requires architectural decision.',
+  ],
+  error_extra: [
+    'Recent hook errors detected in logs. Check .planning/logs/hooks.jsonl for details.',
+    'Hook errors often indicate plan format issues or missing required fields.',
+    'Run `pbr-tools validate health` to check for common issues.',
+  ],
+};
+
+// ─── STATE.md parser ─────────────────────────────────────────────────────────
+
+/**
+ * Extract status and blockers from STATE.md frontmatter.
+ * Returns a minimal object — does not use the heavy stateLoad function.
+ *
+ * @param {string} statePath - Path to STATE.md
+ * @returns {{ status: string, blockers: string[] }}
+ */
+function parseStateFrontmatter(statePath) {
+  const defaults = { status: 'unknown', blockers: [] };
+  try {
+    if (!fs.existsSync(statePath)) return defaults;
+    const content = fs.readFileSync(statePath, 'utf8');
+    // Extract frontmatter between --- delimiters
+    const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!fmMatch) return defaults;
+    const fm = fmMatch[1];
+
+    // Parse status
+    const statusMatch = fm.match(/^status:\s*["']?([^"'\r\n]+)["']?/m);
+    const status = statusMatch ? statusMatch[1].trim() : 'unknown';
+
+    // Parse blockers array
+    const blockers = [];
+    const blockersMatch = fm.match(/^blockers:\s*\[(.*?)\]/ms);
+    if (blockersMatch) {
+      // Inline array format: blockers: ["item1", "item2"]
+      const items = blockersMatch[1].match(/"([^"]+)"/g) || [];
+      blockers.push(...items.map(i => i.replace(/"/g, '')));
+    } else {
+      // Multi-line array format
+      const blockersSection = fm.match(/^blockers:\s*\r?\n((?:\s+- .*\r?\n?)*)/m);
+      if (blockersSection) {
+        const lines = blockersSection[1].split(/\r?\n/);
+        for (const line of lines) {
+          const item = line.match(/^\s+- ["']?(.+?)["']?\s*$/);
+          if (item) blockers.push(item[1]);
+        }
+      }
+    }
+
+    return { status, blockers };
+  } catch (_e) {
+    return defaults;
+  }
+}
+
+// ─── Recent hook errors ───────────────────────────────────────────────────────
+
+/**
+ * Check if recent hook log entries contain errors.
+ * Reads the last 20 lines of hooks.jsonl.
+ *
+ * @param {string} planningDir - Path to .planning/ directory
+ * @returns {boolean} True if error-level entries found
+ */
+function hasRecentHookErrors(planningDir) {
+  const logPath = path.join(planningDir, 'logs', 'hooks.jsonl');
+  try {
+    if (!fs.existsSync(logPath)) return false;
+    const content = fs.readFileSync(logPath, 'utf8');
+    const lines = content.split('\n').filter(Boolean);
+    const recent = lines.slice(-20);
+    for (const line of recent) {
+      try {
+        const entry = JSON.parse(line);
+        if (entry.level === 'error' || entry.type === 'error') return true;
+      } catch (_e) {
+        // skip malformed lines
+      }
+    }
+    return false;
+  } catch (_e) {
+    return false;
+  }
+}
+
+// ─── Main function ─────────────────────────────────────────────────────────────
+
+/**
+ * Get contextual help suggestions based on current STATE.md status and logs.
+ *
+ * @param {string} planningDir - Path to .planning/ directory
+ * @param {object|null} config  - Parsed config object
+ * @returns {{ enabled: boolean, activity: string, suggestions: string[], blockers: string[] }}
+ */
+function getContextualHelp(planningDir, config) {
+  const features = (config && config.features) || {};
+
+  // Check feature toggle (default: enabled)
+  if (features.contextual_help === false) {
+    return { enabled: false, suggestions: [] };
+  }
+
+  const statePath = path.join(planningDir, 'STATE.md');
+  const { status, blockers } = parseStateFrontmatter(statePath);
+
+  // Select suggestions based on status
+  const statusKey = status.toLowerCase();
+  const baseSuggestions = HELP_TEMPLATES[statusKey] || HELP_TEMPLATES.default;
+  const suggestions = [...baseSuggestions];
+
+  // Prepend blocker-specific suggestions if blockers exist
+  if (blockers.length > 0) {
+    suggestions.unshift(...HELP_TEMPLATES.blocker_extra);
+  }
+
+  // Append error-context suggestions if recent hook errors found
+  if (hasRecentHookErrors(planningDir)) {
+    suggestions.push(...HELP_TEMPLATES.error_extra);
+  }
+
+  // Log audit evidence
+  try {
+    const { logAuditEvidence } = require('./progress-visualization');
+    logAuditEvidence(planningDir, 'contextual_help', 'ok');
+  } catch (_e) {
+    // Non-fatal
+  }
+
+  return {
+    enabled: true,
+    activity: status,
+    suggestions,
+    blockers,
+  };
+}
+
+// ─── Exports ──────────────────────────────────────────────────────────────────
+
+module.exports = {
+  getContextualHelp,
+  HELP_TEMPLATES,
+};