@sienklogic/plan-build-run 2.21.0 → 2.21.2

package/plugins/pbr/dist/suggest-compact.js

@@ -0,0 +1,307 @@
+#!/usr/bin/env node
+
+/**
+ * PostToolUse hook on Write|Edit: Tracks tool call count per session
+ * and suggests /compact when approaching context limits.
+ *
+ * Primary path: reads .planning/.context-budget.json (written by context-bridge.js)
+ * and emits tier-labeled warnings (DEGRADING/POOR/CRITICAL) when bridge data is
+ * fresh (<60s old). CRITICAL tier always emits; others use REMINDER_INTERVAL debounce.
+ *
+ * Fallback: when bridge is absent or stale, uses call-count threshold.
+ * Counter stored in .planning/.compact-counter (JSON) and .session.json.
+ * Threshold configurable via config.json hooks.compactThreshold (default: 50).
+ * Counter resets on SessionStart (via progress-tracker.js).
+ *
+ * Exit codes:
+ *   0 = always (advisory only)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+const { loadBridge, getEffectiveThresholds, TIER_MESSAGES } = require('./context-bridge');
+const { readLedger } = require('./track-context-budget');
+
+
+const DEFAULT_THRESHOLD = 50;
+const REMINDER_INTERVAL = 25;
+
+const BASE_THRESHOLD = DEFAULT_THRESHOLD; // 50 at 200k tokens
+const BASE_TOKENS = 200000;
+
+/**
+ * Get the compact threshold scaled to context_window_tokens from config.
+ * Base threshold at 200k tokens: 50. At 1M tokens: 250.
+ *
+ * @param {string} planningDir - Path to .planning/
+ * @returns {number} Scaled threshold
+ */
+function getScaledThreshold(planningDir) {
+  try {
+    const { configLoad } = require('./lib/config');
+    const config = configLoad(planningDir);
+    const tokens = (config && config.context_window_tokens) || BASE_TOKENS;
+    const budgetPct = (config && config.orchestrator_budget_pct) || 25;
+    const scale = tokens / BASE_TOKENS;
+    const budgetScale = budgetPct / 25;
+    return Math.round(BASE_THRESHOLD * scale * budgetScale);
+  } catch (_e) {
+    return BASE_THRESHOLD;
+  }
+}
+
+/**
+ * Build composition-aware compact advice from the context ledger.
+ * Groups ledger entries by phase, identifies stale content, and returns
+ * a human-readable breakdown string. Returns null when no ledger data exists.
+ *
+ * @param {string} planningDir - Path to .planning/ directory
+ * @returns {string|null} Composition advice string, or null if no data
+ */
+function buildCompositionAdvice(planningDir) {
+  const entries = readLedger(planningDir);
+  if (!entries || entries.length === 0) return null;
+
+  // Read stale_after_minutes from config (default 60)
+  let staleMinutes = 60;
+  try {
+    const { configLoad } = require('./lib/config');
+    const config = configLoad(planningDir);
+    if (config && config.context_ledger && config.context_ledger.stale_after_minutes != null) {
+      staleMinutes = config.context_ledger.stale_after_minutes;
+    }
+  } catch (_e) { /* use default */ }
+
+  const now = Date.now();
+  const staleThresholdMs = staleMinutes * 60 * 1000;
+
+  // Group entries by phase
+  const groups = {};
+  let totalTokens = 0;
+
+  for (const entry of entries) {
+    const phase = entry.phase || 'untracked';
+    if (!groups[phase]) {
+      groups[phase] = { tokens: 0, staleCount: 0, staleTokens: 0, count: 0 };
+    }
+    const tokens = entry.est_tokens || 0;
+    groups[phase].tokens += tokens;
+    groups[phase].count += 1;
+    totalTokens += tokens;
+
+    // Check staleness
+    if (entry.timestamp) {
+      const entryAge = now - new Date(entry.timestamp).getTime();
+      if (entryAge >= staleThresholdMs) {
+        groups[phase].staleCount += 1;
+        groups[phase].staleTokens += tokens;
+      }
+    }
+  }
+
+  const totalK = Math.round(totalTokens / 1000);
+  let msg = `Context composition: ~${totalK}k tokens across ${entries.length} reads.`;
+
+  // Add phase-level stale info
+  for (const [phase, data] of Object.entries(groups)) {
+    if (data.staleCount > 0) {
+      const phaseK = Math.round(data.staleTokens / 1000);
+      msg += ` Phase ${phase}: ~${phaseK}k (${data.staleCount} stale reads >=${staleMinutes}m).`;
+    }
+  }
+
+  // Check if any stale content exists
+  const hasStale = Object.values(groups).some(g => g.staleCount > 0);
+  if (hasStale) {
+    msg += ' Consider /compact to free stale context.';
+  }
+
+  return msg;
+}
+
+function main() {
+  process.stdin.setEncoding('utf8');
+  process.stdin.resume();
+  process.stdin.on('end', () => {
+    try {
+      const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+      const planningDir = path.join(cwd, '.planning');
+      if (!fs.existsSync(planningDir)) {
+        process.exit(0);
+      }
+
+      const result = checkCompaction(planningDir, cwd);
+      if (result) {
+        process.stdout.write(JSON.stringify(result));
+      }
+      process.exit(0);
+    } catch (_e) {
+      process.stdout.write(JSON.stringify({ additionalContext: '⚠ [PBR] suggest-compact failed: ' + _e.message }));
+      process.exit(0);
+    }
+  });
+}
+
+/**
+ * Check the context bridge for the current tier.
+ * Returns { tier, message } for actionable tiers (DEGRADING/POOR/CRITICAL),
+ * or null if bridge is absent, stale (>60s), or tier is PEAK/GOOD (<50%).
+ * @param {string} planningDir - Path to .planning/ directory
+ * @returns {{ tier: string, message: string }|null}
+ */
+function checkBridgeTier(planningDir) {
+  const bridgePath = path.join(planningDir, '.context-budget.json');
+  const bridge = loadBridge(bridgePath);
+  if (!bridge) return null;
+
+  // Check staleness: if timestamp is older than 60 seconds, treat as stale
+  if (bridge.timestamp) {
+    const ageMs = Date.now() - new Date(bridge.timestamp).getTime();
+    if (ageMs > 60000) return null;
+  }
+
+  const percent = bridge.estimated_percent || 0;
+  const thresholds = getEffectiveThresholds(planningDir);
+
+  if (percent >= thresholds.critical) {
+    return { tier: 'CRITICAL', message: TIER_MESSAGES.CRITICAL };
+  } else if (percent >= thresholds.poor) {
+    return { tier: 'POOR', message: TIER_MESSAGES.POOR };
+  } else if (percent >= thresholds.degrading) {
+    return { tier: 'DEGRADING', message: TIER_MESSAGES.DEGRADING };
+  }
+
+  // Below degrading threshold — no tier message needed
+  return null;
+}
+
+/**
+ * Increment tool call counter and return a suggestion if threshold is reached.
+ * Checks bridge tier first; falls back to call-count when bridge is absent or stale.
+ * @param {string} planningDir - Path to .planning/ directory
+ * @param {string} cwd - Current working directory (for config loading)
+ * @returns {Object|null} Hook output with additionalContext, or null
+ */
+function checkCompaction(planningDir, cwd) {
+  const counterPath = path.join(planningDir, '.compact-counter');
+  const counter = loadCounter(counterPath);
+  const threshold = getThreshold(cwd);
+
+  counter.count += 1;
+  saveCounter(counterPath, counter);
+
+  // Check bridge tier first
+  const bridgeTier = checkBridgeTier(planningDir);
+  if (bridgeTier !== null) {
+    const { tier, message } = bridgeTier;
+    const isFirstSuggestion = !counter.lastSuggested;
+    const callsSinceSuggestion = counter.count - (counter.lastSuggested || 0);
+    const shouldEmit = tier === 'CRITICAL' || isFirstSuggestion || callsSinceSuggestion >= REMINDER_INTERVAL;
+
+    if (shouldEmit) {
+      counter.lastSuggested = counter.count;
+      saveCounter(counterPath, counter);
+
+      logHook('suggest-compact', 'PostToolUse', 'tier-suggest', { tier, count: counter.count });
+
+      const composition = buildCompositionAdvice(planningDir);
+      const baseMsg = `[Context Budget - ${tier}] ${message}`;
+      return {
+        additionalContext: composition ? `${baseMsg}\n${composition}` : baseMsg
+      };
+    }
+    return null;
+  }
+
+  // Fall back to counter-based suggestion when bridge is absent or stale
+  if (counter.count < threshold) return null;
+
+  const isFirstSuggestion = !counter.lastSuggested;
+  const callsSinceSuggestion = counter.count - (counter.lastSuggested || 0);
+
+  if (isFirstSuggestion || callsSinceSuggestion >= REMINDER_INTERVAL) {
+    counter.lastSuggested = counter.count;
+    saveCounter(counterPath, counter);
+
+    logHook('suggest-compact', 'PostToolUse', 'suggest', {
+      count: counter.count,
+      threshold
+    });
+
+    return {
+      additionalContext: `[Context Budget] ${counter.count} tool calls this session (threshold: ${threshold}). Consider running /compact to free context space before quality degrades.`
+    };
+  }
+
+  return null;
+}
+
+function loadCounter(counterPath) {
+  try {
+    const content = fs.readFileSync(counterPath, 'utf8');
+    const data = JSON.parse(content);
+    return { count: data.count || 0, lastSuggested: data.lastSuggested || 0 };
+  } catch (_e) {
+    return { count: 0, lastSuggested: 0 };
+  }
+}
+
+function saveCounter(counterPath, counter) {
+  try {
+    fs.writeFileSync(counterPath, JSON.stringify(counter), 'utf8');
+  } catch (_e) {
+    // Best-effort
+  }
+  // Mirror to .session.json for consolidated session state tracking
+  // Derive planningDir from counterPath (counterPath is planningDir/.compact-counter)
+  try {
+    const planningDir = path.dirname(counterPath);
+    const { sessionSave } = require('./lib/core');
+    // Note: saveCounter doesn't have sessionId context — mirror to legacy path
+    sessionSave(planningDir, { compactCounter: counter });
+  } catch (_e) { /* non-fatal mirror */ }
+}
+
+function getThreshold(cwd) {
+  const planningDir = path.join(cwd, '.planning');
+  const { configLoad } = require('./lib/config');
+  const config = configLoad(planningDir);
+  // Honor explicit hooks.compactThreshold override first
+  if (config && config.hooks && config.hooks.compactThreshold != null) {
+    return config.hooks.compactThreshold;
+  }
+  return getScaledThreshold(planningDir);
+}
+
+function resetCounter(planningDir, sessionId) {
+  // Primary: reset compactCounter in .session.json to 0
+  try {
+    const { sessionSave } = require('./lib/core');
+    sessionSave(planningDir, { compactCounter: { count: 0, lastSuggested: 0 } }, sessionId);
+  } catch (_e) { /* best-effort */ }
+
+  // .compact-counter cleanup removed -- legacy file no longer used
+}
+
+/**
+ * HTTP handler for hook-server integration.
+ * Wraps the existing checkCompaction logic for use as a route handler.
+ *
+ * @param {Object} reqBody - { event, tool, data, planningDir, cache }
+ * @param {Object} _cache - In-memory server cache (unused; suggest-compact reads its own state)
+ * @returns {Object|null} Hook output with additionalContext, or null
+ */
+function handleHttp(reqBody, _cache) {
+  try {
+    const planningDir = reqBody.planningDir;
+    if (!planningDir) return null;
+    const cwd = path.dirname(planningDir);
+    return checkCompaction(planningDir, cwd);
+  } catch (_e) {
+    return null;
+  }
+}
+
+module.exports = { checkCompaction, checkBridgeTier, buildCompositionAdvice, loadCounter, saveCounter, getThreshold, getScaledThreshold, resetCounter, DEFAULT_THRESHOLD, REMINDER_INTERVAL, handleHttp };
+if (require.main === module || process.argv[1] === __filename) { main(); }

package/plugins/pbr/dist/sync-context-to-claude.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+/**
+ * Syncs Locked Decisions from .planning/CONTEXT.md into project CLAUDE.md.
+ * Called by post-write-dispatch.js when .planning/CONTEXT.md is written.
+ *
+ * Algorithm:
+ *   1. Read .planning/CONTEXT.md — extract ## Locked Decisions table rows
+ *   2. Find project CLAUDE.md (cwd/CLAUDE.md)
+ *   3. Replace or append a "### Locked Decisions (PBR)" section
+ *
+ * Idempotent: re-running produces the same result.
+ * Advisory only: never throws, never blocks.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+
+const SECTION_START = '### Locked Decisions (PBR)';
+const SECTION_END_MARKER = '<!-- /pbr:locked-decisions -->';
+
+/**
+ * Extract decision rows from the ## Locked Decisions table in CONTEXT.md.
+ * Handles both \n and \r\n line endings.
+ * @param {string} contextContent - Full content of CONTEXT.md
+ * @returns {{ decision: string, rationale: string }[]}
+ */
+function extractLockedDecisions(contextContent) {
+  // Find ## Locked Decisions section (handle \r\n line endings)
+  const sectionMatch = contextContent.match(/## Locked Decisions\r?\n([\s\S]*?)(?=\r?\n## |\r?\n# |$)/);
+  if (!sectionMatch) return [];
+  const sectionText = sectionMatch[1];
+  // Extract table rows (skip header and separator lines)
+  const rows = sectionText.split(/\r?\n/).filter(l => l.startsWith('|') && !l.includes('---') && !l.includes('Decision'));
+  return rows.map(row => {
+    const cols = row.split('|').map(c => c.trim()).filter(Boolean);
+    return cols.length >= 2 ? { decision: cols[0], rationale: cols[1] } : null;
+  }).filter(Boolean);
+}
+
+/**
+ * Build the Locked Decisions CLAUDE.md section string from decisions array.
+ * Returns empty string if decisions is empty (caller should skip sync).
+ * @param {{ decision: string, rationale: string }[]} decisions
+ * @returns {string}
+ */
+function buildSection(decisions) {
+  if (decisions.length === 0) return '';
+  const rows = decisions.map(d => `| ${d.decision} | ${d.rationale} |`).join('\n');
+  return `${SECTION_START}\n\n> Auto-synced from \`.planning/CONTEXT.md\`. Edit source file, not this section.\n\n| Decision | Rationale |\n|----------|-----------|\n${rows}\n\n${SECTION_END_MARKER}`;
+}
+
+/**
+ * Main sync function. Reads CONTEXT.md from cwd/.planning/ and writes/updates
+ * the Locked Decisions section in cwd/CLAUDE.md.
+ * @param {string} cwd - Project root directory
+ */
+function syncContextToClaude(cwd) {
+  try {
+    const contextPath = path.join(cwd, '.planning', 'CONTEXT.md');
+    const claudePath = path.join(cwd, 'CLAUDE.md');
+
+    if (!fs.existsSync(contextPath)) return;
+
+    const contextContent = fs.readFileSync(contextPath, 'utf8');
+    const decisions = extractLockedDecisions(contextContent);
+
+    if (decisions.length === 0) return; // Nothing to sync
+
+    const section = buildSection(decisions);
+    let claudeContent = fs.existsSync(claudePath) ? fs.readFileSync(claudePath, 'utf8') : '';
+
+    // Replace existing section or append
+    const startIdx = claudeContent.indexOf(SECTION_START);
+    const endIdx = claudeContent.indexOf(SECTION_END_MARKER);
+
+    if (startIdx !== -1 && endIdx !== -1) {
+      // Replace existing section in-place
+      claudeContent = claudeContent.substring(0, startIdx) + section + claudeContent.substring(endIdx + SECTION_END_MARKER.length);
+    } else {
+      // Append new section
+      claudeContent = claudeContent.trimEnd() + '\n\n' + section + '\n';
+    }
+
+    fs.writeFileSync(claudePath, claudeContent, 'utf8');
+    logHook('sync-context-to-claude', 'PostToolUse', 'pass', { decisions: decisions.length });
+  } catch (_e) {
+    // Advisory only — never propagate errors
+  }
+}
+
+module.exports = { syncContextToClaude, extractLockedDecisions, buildSection };
+
+// Main entry point when run as a hook script
+if (require.main === module || process.argv[1] === __filename) {
+  syncContextToClaude(process.env.PBR_PROJECT_ROOT || process.cwd());
+  process.exit(0);
+}

package/plugins/pbr/dist/task-completed.js

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+
+/**
+ * TaskCompleted hook: Logs agent task completion with output summary.
+ *
+ * Fires when a Task() sub-agent finishes (distinct from SubagentStop).
+ * Logs the completion event and agent type for workflow tracking.
+ * Returns continue:false if a verifier finds critical gaps or an executor
+ * produces no SUMMARY.md — preventing the orchestrator from silently moving on.
+ *
+ * Non-blocking — exits 0 always.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+const { logEvent } = require('./event-logger');
+const { performance } = require('perf_hooks');
+
+/**
+ * Read current_phase from STATE.md frontmatter.
+ * Lightweight — avoids heavy stateLoad() which parses roadmap/config too.
+ * Uses direct readFileSync (no existsSync) to avoid double stat.
+ */
+function readCurrentPhase(planningDir) {
+  try {
+    const statePath = path.join(planningDir, 'STATE.md');
+    const content = fs.readFileSync(statePath, 'utf8');
+    const match = content.match(/^current_phase:\s*(\d+)/m);
+    return match ? match[1] : null;
+  } catch (e) {
+    if (e.code !== 'ENOENT') {
+      logHook('task-completed', 'TaskCompleted', 'state-read-error', { error: e.message });
+    }
+    return null;
+  }
+}
+
+function readStdin() {
+  try {
+    const input = fs.readFileSync(0, 'utf8').trim();
+    if (input) return JSON.parse(input);
+  } catch (_e) {
+    // Intentional silence: stdin may be empty or non-JSON, this is expected
+  }
+  return {};
+}
+
+/**
+ * Resolve the phase directory for a given phase number.
+ * Caches readdirSync result for repeated calls.
+ * @param {string} phasesDir - Path to the phases directory
+ * @param {string} phaseNum - Zero-padded phase number (e.g., "03")
+ * @returns {string|null} - Full path to the matching phase dir, or null
+ */
+function resolvePhaseDir(phasesDir, phaseNum) {
+  try {
+    const entries = fs.readdirSync(phasesDir);
+    const prefix = phaseNum + '-';
+    for (let i = 0; i < entries.length; i++) {
+      if (entries[i].startsWith(prefix)) {
+        return path.join(phasesDir, entries[i]);
+      }
+    }
+  } catch (e) {
+    if (e.code !== 'ENOENT') {
+      logHook('task-completed', 'TaskCompleted', 'phases-read-error', { error: e.message });
+    }
+  }
+  return null;
+}
+
+/**
+ * Check whether a halt signal should be emitted after a PBR agent completes.
+ * Returns null (no halt) or { continue: false, stopReason: "..." }.
+ *
+ * @param {object} data - parsed stdin JSON from the TaskCompleted event
+ * @param {string} planningDir - absolute path to the .planning directory
+ * @returns {{ continue: false, stopReason: string }|null}
+ */
+function checkHaltConditions(data, planningDir) {
+  const agentType = data.agent_type || data.subagent_type || null;
+  if (!agentType) return null;
+
+  // Only check for pbr:verifier and pbr:executor
+  if (agentType !== 'pbr:verifier' && agentType !== 'pbr:executor') return null;
+
+  // Read phase once for both checks
+  const rawPhase = readCurrentPhase(planningDir);
+  const phaseNum = rawPhase ? String(rawPhase).padStart(2, '0') : null;
+  if (!phaseNum) return null;
+
+  const phasesDir = path.join(planningDir, 'phases');
+  const phaseDir = resolvePhaseDir(phasesDir, phaseNum);
+  if (!phaseDir) return null;
+
+  // --- Verifier: halt if VERIFICATION.md reports gaps_found or failed ---
+  if (agentType === 'pbr:verifier') {
+    try {
+      const target = path.join(phaseDir, 'VERIFICATION.md');
+      const content = fs.readFileSync(target, 'utf8');
+      const statusMatch = content.match(/^status:\s*(.+)$/m);
+      const status = statusMatch ? statusMatch[1].trim() : null;
+      if (status === 'gaps_found' || status === 'failed') {
+        return {
+          continue: false,
+          stopReason: `Verifier found critical gaps in Phase ${phaseNum} (status: ${status}). Run /pbr:verify-work to address gaps before continuing.`
+        };
+      }
+    } catch (e) {
+      if (e.code !== 'ENOENT') {
+        logHook('task-completed', 'TaskCompleted', 'verification-read-error', { error: e.message });
+      }
+    }
+  }
+
+  // --- Executor: halt if SUMMARY.md is missing from current phase dir ---
+  if (agentType === 'pbr:executor') {
+    const target = path.join(phaseDir, 'SUMMARY.md');
+    try {
+      fs.accessSync(target, fs.constants.F_OK);
+    } catch (_e) {
+      return {
+        continue: false,
+        stopReason: `Executor completed Phase ${phaseNum} but produced no SUMMARY.md. Review executor output and re-run /pbr:execute-phase.`
+      };
+    }
+  }
+
+  return null;
+}
+
+function main() {
+  const t0 = performance.now();
+  const data = readStdin();
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+
+  logHook('task-completed', 'TaskCompleted', 'completed', {
+    agent_type: data.agent_type || data.subagent_type || null,
+    agent_id: data.agent_id || null,
+    agent_duration_ms: data.duration_ms || null
+  });
+
+  logEvent('agent', 'task-completed', {
+    agent_type: data.agent_type || data.subagent_type || null,
+    agent_id: data.agent_id || null,
+    agent_duration_ms: data.duration_ms || null
+  });
+
+  try {
+    fs.accessSync(planningDir, fs.constants.F_OK);
+    const halt = checkHaltConditions(data, planningDir);
+    if (halt) {
+      logHook('task-completed', 'TaskCompleted', 'halting', halt);
+      process.stdout.write(JSON.stringify(halt));
+      logHook('task-completed', 'TaskCompleted', 'hook_ms', { ms: Math.round(performance.now() - t0) });
+      process.exit(0);
+    }
+  } catch (_e) {
+    // planningDir does not exist — no halt checks needed
+  }
+
+  logHook('task-completed', 'TaskCompleted', 'hook_ms', { ms: Math.round(performance.now() - t0) });
+  process.exit(0);
+}
+
+/**
+ * HTTP handler for hook-server.js integration.
+ * Called as handleHttp(reqBody, cache) where reqBody = { event, tool, data, planningDir, ... }.
+ * Must NOT call process.exit().
+ * @param {{ data: object, planningDir: string }} reqBody
+ * @returns {{ continue: false, stopReason: string }|null}
+ */
+function handleHttp(reqBody) {
+  const t0 = performance.now();
+  const data = reqBody.data || {};
+  const planningDir = reqBody.planningDir;
+
+  logHook('task-completed', 'TaskCompleted', 'completed', {
+    agent_type: data.agent_type || data.subagent_type || null,
+    agent_id: data.agent_id || null,
+    agent_duration_ms: data.duration_ms || null
+  });
+
+  logEvent('agent', 'task-completed', {
+    agent_type: data.agent_type || data.subagent_type || null,
+    agent_id: data.agent_id || null,
+    agent_duration_ms: data.duration_ms || null
+  });
+
+  if (planningDir && fs.existsSync(planningDir)) {
+    const halt = checkHaltConditions(data, planningDir);
+    if (halt) {
+      logHook('task-completed', 'TaskCompleted', 'halting', halt);
+      logHook('task-completed', 'TaskCompleted', 'hook_ms', { ms: Math.round(performance.now() - t0) });
+      return halt;
+    }
+  }
+
+  logHook('task-completed', 'TaskCompleted', 'hook_ms', { ms: Math.round(performance.now() - t0) });
+  return null;
+}
+
+if (require.main === module || process.argv[1] === __filename) { main(); }
+module.exports = { main, checkHaltConditions, readCurrentPhase, handleHttp };