@sienklogic/plan-build-run 2.19.0 → 2.19.1

package/plugins/pbr/scripts/context-budget-check.js

@@ -19,9 +19,11 @@
 
 const fs = require('fs');
 const path = require('path');
-const { logHook } = require('./hook-logger');
-const { logEvent } = require('./event-logger');
-const { atomicWrite, configLoad, tailLines } = require('./pbr-tools');
+const { logHook, getLogPath: getHooksLogPath } = require('./hook-logger');
+const { logEvent, getLogPath: getEventsLogPath } = require('./event-logger');
+const { configLoad } = require('./lib/config');
+const { tailLines, lockedFileUpdate, sessionLoad } = require('./lib/core');
+// Session-scoped paths: sessionLoad accepts sessionId, delegates to resolveSessionPath internally
 
 function main() {
   const cwd = process.cwd();
@@ -39,11 +41,14 @@ function main() {
 
     // Gather context from multiple sources
     const activeOp = readActiveOperation(planningDir);
+    const activeSkill = readActiveSkill(planningDir);
     const roadmapSummary = readRoadmapSummary(planningDir);
     const currentPlan = readCurrentPlan(planningDir, content);
     const configHighlights = readConfigHighlights(planningDir);
     const recentErrors = readRecentErrors(planningDir, 3);
     const recentAgents = readRecentAgents(planningDir, 5);
+    const blockers = readBlockers(content);
+    const pendingTodos = readPendingTodos(planningDir, 5);
 
     // Build continuity section
     const continuityParts = [
@@ -51,6 +56,9 @@ function main() {
       'Compaction occurred: context was auto-compacted at this point'
     ];
 
+    if (activeSkill) {
+      continuityParts.push(`Active skill at compaction: /pbr:${activeSkill}`);
+    }
     if (activeOp) {
       continuityParts.push(`Active operation at compaction: ${activeOp}`);
     }
@@ -69,6 +77,12 @@ function main() {
     if (recentAgents.length > 0) {
       continuityParts.push(`Recent agents: ${recentAgents.join(', ')}`);
     }
+    if (blockers) {
+      continuityParts.push(`Blockers at compaction:\n${blockers}`);
+    }
+    if (pendingTodos.length > 0) {
+      continuityParts.push(`Pending todos: ${pendingTodos.join('; ')}`);
+    }
 
     continuityParts.push('Note: Some conversation context may have been lost. Check STATE.md and SUMMARY.md files for ground truth.');
 
@@ -87,10 +101,10 @@ function main() {
       content = content.trimEnd() + `\n\n${continuityHeader}\n${continuityContent}\n`;
     }
 
-    atomicWrite(stateFile, content);
+    lockedFileUpdate(stateFile, () => content);
 
     // Output additionalContext for post-compaction recovery
-    const recoveryContext = buildRecoveryContext(activeOp, roadmapSummary, currentPlan, configHighlights, recentErrors, recentAgents);
+    const recoveryContext = buildRecoveryContext(activeOp, roadmapSummary, currentPlan, configHighlights, recentErrors, recentAgents, activeSkill, blockers, pendingTodos);
     if (recoveryContext) {
       const output = {
         additionalContext: recoveryContext
@@ -107,12 +121,71 @@ function main() {
     logEvent('workflow', 'compaction', { timestamp });
   } catch (e) {
     logHook('context-budget-check', 'PreCompact', 'error', { error: e.message });
+    process.stdout.write(JSON.stringify({ additionalContext: '⚠ [PBR] context-budget-check failed: ' + e.message }));
   }
 
   process.exit(0);
 }
 
-function readActiveOperation(planningDir) {
+/**
+ * Read the current active skill name from session state.
+ */
+function readActiveSkill(planningDir, sessionId) {
+  try {
+    const session = sessionLoad(planningDir, sessionId);
+    if (session.activeSkill) return session.activeSkill;
+  } catch (_e) { /* fall through */ }
+
+  const activeSkillFile = path.join(planningDir, '.active-skill');
+  try {
+    return fs.readFileSync(activeSkillFile, 'utf8').trim() || '';
+  } catch (_e) {
+    return '';
+  }
+}
+
+/**
+ * Extract blockers from STATE.md content.
+ */
+function readBlockers(stateContent) {
+  const match = stateContent.match(/## Blockers\/Concerns\s*\n([\s\S]*?)(?=\n## |\s*$)/);
+  if (!match) return '';
+  const blockers = match[1].trim();
+  if (!blockers || blockers.toLowerCase() === 'none') return '';
+  // Return first 3 lines max
+  return blockers.split('\n').slice(0, 3).join('\n');
+}
+
+/**
+ * Read pending todo titles from .planning/todos/pending/.
+ */
+function readPendingTodos(planningDir, maxTodos) {
+  const count = maxTodos || 5;
+  const todosDir = path.join(planningDir, 'todos', 'pending');
+  try {
+    if (!fs.existsSync(todosDir)) return [];
+    const files = fs.readdirSync(todosDir).filter(f => f.endsWith('.md')).slice(0, count);
+    return files.map(f => {
+      try {
+        const content = fs.readFileSync(path.join(todosDir, f), 'utf8');
+        const titleMatch = content.match(/^#\s+(.+)/m);
+        return titleMatch ? titleMatch[1].substring(0, 60) : f.replace('.md', '');
+      } catch (_e) {
+        return f.replace('.md', '');
+      }
+    });
+  } catch (_e) {
+    return [];
+  }
+}
+
+function readActiveOperation(planningDir, sessionId) {
+  // Try .session.json first (new), fall back to legacy .active-operation file
+  try {
+    const session = sessionLoad(planningDir, sessionId);
+    if (session.activeOperation) return session.activeOperation;
+  } catch (_e) { /* fall through */ }
+
   const activeOpFile = path.join(planningDir, '.active-operation');
   if (!fs.existsSync(activeOpFile)) return '';
   try {
@@ -159,7 +232,13 @@ function readRoadmapSummary(planningDir) {
   }
 }
 
-function readCurrentPlan(planningDir, stateContent) {
+function readCurrentPlan(planningDir, stateContent, sessionId) {
+  // Try .session.json first (new), then .active-plan file (legacy)
+  try {
+    const session = sessionLoad(planningDir, sessionId);
+    if (session.activePlan) return session.activePlan;
+  } catch (_e) { /* fall through */ }
+
   // Prefer .active-plan signal file (definitive) over directory listing (guesswork)
   const activePlanFile = path.join(planningDir, '.active-plan');
   if (fs.existsSync(activePlanFile)) {
@@ -185,8 +264,8 @@ function readCurrentPlan(planningDir, stateContent) {
 
     const phaseDir = path.join(phasesDir, dirs[0]);
 
-    // Find PLAN.md files
-    const planFiles = fs.readdirSync(phaseDir).filter(f => f.endsWith('PLAN.md'));
+    // Find PLAN*.md files (matches PLAN.md, PLAN-01.md, 01-PLAN.md, etc.)
+    const planFiles = fs.readdirSync(phaseDir).filter(f => /PLAN.*\.md$/i.test(f));
     if (planFiles.length === 0) return 'No PLAN.md found in current phase';
 
     // Read the last plan's objective only (frontmatter + objective tag)
@@ -205,7 +284,7 @@ function readCurrentPlan(planningDir, stateContent) {
 function readRecentErrors(planningDir, maxErrors) {
   const count = maxErrors || 3;
   try {
-    const eventsLog = path.join(planningDir, 'logs', 'events.jsonl');
+    const eventsLog = getEventsLogPath();
     // Only read the last 50 lines — errors are rare, so 50 tail lines
     // is more than enough to find the most recent ones
     const lines = tailLines(eventsLog, 50);
@@ -230,7 +309,7 @@ function readRecentErrors(planningDir, maxErrors) {
 function readRecentAgents(planningDir, maxAgents) {
   const count = maxAgents || 5;
   try {
-    const hooksLog = path.join(planningDir, 'logs', 'hooks.jsonl');
+    const hooksLog = getHooksLogPath();
     // Only read the last 30 lines — agent spawns are interspersed with
     // other hook events, so 30 tail lines covers recent agents well
     const lines = tailLines(hooksLog, 30);
@@ -267,12 +346,18 @@ function readConfigHighlights(planningDir) {
   return parts.join(', ');
 }
 
-function buildRecoveryContext(activeOp, roadmapSummary, currentPlan, configHighlights, recentErrors, recentAgents) {
-  const parts = ['[Post-Compaction Recovery] Context was auto-compacted. Key state preserved:'];
+function buildRecoveryContext(activeOp, roadmapSummary, currentPlan, configHighlights, recentErrors, recentAgents, activeSkill, blockers, pendingTodos) {
+  const parts = [
+    '[Post-Compaction Recovery] Context was auto-compacted. Key state preserved:',
+    '[PBR WORKFLOW REQUIRED — Route all work through PBR commands]\n- Fix a bug or small task → /pbr:quick\n- Plan a feature → /pbr:plan-phase N\n- Build from a plan → /pbr:execute-phase N\n- Explore or research → /pbr:explore\n- Freeform request → /pbr:do\n- Do NOT write source code or spawn generic agents without an active PBR skill.\n- Use PBR agents (pbr:researcher, pbr:executor, etc.) not Explore/general-purpose.'
+  ];
 
+  if (activeSkill) parts.push(`Active skill: /pbr:${activeSkill}`);
   if (activeOp) parts.push(`Active operation: ${activeOp}`);
   if (currentPlan) parts.push(`Current plan: ${currentPlan}`);
   if (configHighlights) parts.push(`Config: ${configHighlights}`);
+  if (blockers) parts.push(`Blockers: ${blockers}`);
+  if (pendingTodos && pendingTodos.length > 0) parts.push(`Pending todos: ${pendingTodos.join('; ')}`);
   if (recentErrors && recentErrors.length > 0) parts.push(`Recent errors: ${recentErrors.join('; ')}`);
   if (recentAgents && recentAgents.length > 0) parts.push(`Recent agents: ${recentAgents.join(', ')}`);
   if (roadmapSummary) parts.push(`Progress:\n${roadmapSummary}`);
@@ -283,5 +368,75 @@ function buildRecoveryContext(activeOp, roadmapSummary, currentPlan, configHighl
   return parts.length > 2 ? parts.join('\n') : '';
 }
 
-module.exports = { readRoadmapSummary, readCurrentPlan, readConfigHighlights, buildRecoveryContext, readRecentErrors, readRecentAgents };
+/**
+ * handleHttp — hook-server.js interface.
+ * reqBody = { event, tool, data, planningDir, cache }
+ * Returns { additionalContext: "..." } or null. Never calls process.exit().
+ */
+function handleHttp(reqBody) {
+  const planningDir = reqBody && reqBody.planningDir;
+  const stateFile = planningDir && path.join(planningDir, 'STATE.md');
+
+  if (!stateFile || !fs.existsSync(stateFile)) return null;
+
+  try {
+    let content = fs.readFileSync(stateFile, 'utf8');
+    const timestamp = new Date().toISOString();
+
+    const activeOp = readActiveOperation(planningDir);
+    const activeSkill = readActiveSkill(planningDir);
+    const roadmapSummary = readRoadmapSummary(planningDir);
+    const currentPlan = readCurrentPlan(planningDir, content);
+    const configHighlights = readConfigHighlights(planningDir);
+    const recentErrors = readRecentErrors(planningDir, 3);
+    const recentAgents = readRecentAgents(planningDir, 5);
+    const blockers = readBlockers(content);
+    const pendingTodos = readPendingTodos(planningDir, 5);
+
+    const continuityParts = [
+      `Last session: ${timestamp}`,
+      'Compaction occurred: context was auto-compacted at this point'
+    ];
+    if (activeSkill) continuityParts.push(`Active skill at compaction: /pbr:${activeSkill}`);
+    if (activeOp) continuityParts.push(`Active operation at compaction: ${activeOp}`);
+    if (roadmapSummary) continuityParts.push(`Roadmap progress:\n${roadmapSummary}`);
+    if (currentPlan) continuityParts.push(`Current plan: ${currentPlan}`);
+    if (configHighlights) continuityParts.push(`Config: ${configHighlights}`);
+    if (recentErrors.length > 0) continuityParts.push(`Recent errors:\n${recentErrors.map(e => '  - ' + e).join('\n')}`);
+    if (recentAgents.length > 0) continuityParts.push(`Recent agents: ${recentAgents.join(', ')}`);
+    if (blockers) continuityParts.push(`Blockers at compaction:\n${blockers}`);
+    if (pendingTodos.length > 0) continuityParts.push(`Pending todos: ${pendingTodos.join('; ')}`);
+    continuityParts.push('Note: Some conversation context may have been lost. Check STATE.md and SUMMARY.md files for ground truth.');
+
+    const continuityHeader = '## Session Continuity';
+    const continuityContent = continuityParts.join('\n');
+
+    if (content.includes(continuityHeader)) {
+      content = content.replace(
+        /## Session Continuity[\s\S]*?(?=\n## |\n---|\s*$)/,
+        () => `${continuityHeader}\n${continuityContent}\n`
+      );
+    } else {
+      content = content.trimEnd() + `\n\n${continuityHeader}\n${continuityContent}\n`;
+    }
+
+    lockedFileUpdate(stateFile, () => content);
+
+    const recoveryContext = buildRecoveryContext(activeOp, roadmapSummary, currentPlan, configHighlights, recentErrors, recentAgents, activeSkill, blockers, pendingTodos);
+    if (recoveryContext) {
+      logHook('context-budget-check', 'PreCompact', 'saved', {
+        stateFile: 'STATE.md',
+        hasRoadmap: !!roadmapSummary,
+        hasPlan: !!currentPlan,
+        hasConfig: !!configHighlights
+      });
+      return { additionalContext: recoveryContext };
+    }
+  } catch (e) {
+    logHook('context-budget-check', 'PreCompact', 'error', { error: e.message });
+  }
+  return null;
+}
+
+module.exports = { readRoadmapSummary, readCurrentPlan, readConfigHighlights, buildRecoveryContext, readRecentErrors, readRecentAgents, readActiveSkill, readBlockers, readPendingTodos, handleHttp };
 if (require.main === module || process.argv[1] === __filename) { main(); }

package/plugins/pbr/scripts/context-quality.js

@@ -0,0 +1,271 @@
+#!/usr/bin/env node
+
+/**
+ * Context Quality Scoring — Measures signal-to-noise ratio of context reads.
+ *
+ * Produces a 0-100 score based on three dimensions:
+ *   - Freshness (40%): % of entries less than stale_after_minutes old
+ *   - Relevance (40%): % of entries matching the current phase
+ *   - Diversity (20%): penalizes when >80% of tokens come from one directory
+ *
+ * Gated by features.context_quality_scoring in config.json.
+ * Report written to .planning/.context-quality.json for dashboard/audit consumption.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+
+/**
+ * Score context quality based on ledger entries.
+ *
+ * @param {Array} entries - Ledger entries from .context-ledger.json
+ * @param {Object} config - Config object (needs context_ledger.stale_after_minutes)
+ * @param {string} [currentPhase] - Current phase identifier for relevance scoring
+ * @returns {number} Score 0-100
+ */
+function scoreContext(entries, config, currentPhase) {
+  if (!entries || entries.length === 0) return 100;
+
+  const staleMinutes = (config && config.context_ledger && config.context_ledger.stale_after_minutes) || 60;
+  const staleThresholdMs = staleMinutes * 60 * 1000;
+  const now = Date.now();
+
+  // Freshness: % of entries that are fresh (< stale_after_minutes old)
+  let freshCount = 0;
+  for (const entry of entries) {
+    if (entry.timestamp) {
+      const age = now - new Date(entry.timestamp).getTime();
+      if (age < staleThresholdMs) {
+        freshCount++;
+      }
+    }
+  }
+  const freshness = Math.round((freshCount / entries.length) * 100);
+
+  // Relevance: % of entries matching current phase
+  let relevantCount = 0;
+  if (currentPhase) {
+    for (const entry of entries) {
+      if (entry.phase === currentPhase) {
+        relevantCount++;
+      }
+    }
+  } else {
+    // If no current phase known, treat all as relevant
+    relevantCount = entries.length;
+  }
+  const relevance = Math.round((relevantCount / entries.length) * 100);
+
+  // Diversity: penalize when >80% of tokens come from a single directory group
+  const groups = {};
+  let totalTokens = 0;
+  for (const entry of entries) {
+    const tokens = entry.est_tokens || 0;
+    totalTokens += tokens;
+    const dir = entry.file ? path.dirname(entry.file) : 'unknown';
+    groups[dir] = (groups[dir] || 0) + tokens;
+  }
+
+  let diversity = 100;
+  if (totalTokens > 0) {
+    const maxGroupPct = Math.max(...Object.values(groups)) / totalTokens * 100;
+    if (maxGroupPct > 80) {
+      diversity = Math.max(0, Math.round(100 - (maxGroupPct - 80) * 2.5));
+    }
+  }
+
+  // Weighted average
+  const score = freshness * 0.4 + relevance * 0.4 + diversity * 0.2;
+  return Math.round(score);
+}
+
+/**
+ * Generate a quality report from the context ledger.
+ * Returns null if the feature is disabled.
+ *
+ * @param {string} planningDir - Path to .planning/ directory
+ * @returns {Object|null} { score, breakdown, timestamp, entry_count } or null
+ */
+function getQualityReport(planningDir) {
+  // Load config and check toggle
+  let config;
+  try {
+    const { configLoad } = require('./lib/config');
+    config = configLoad(planningDir);
+  } catch (_e) {
+    try {
+      const configPath = path.join(planningDir, 'config.json');
+      config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    } catch (_e2) {
+      return null;
+    }
+  }
+
+  if (!config || (config.features && config.features.context_quality_scoring === false)) {
+    return null;
+  }
+
+  // Read ledger
+  let entries;
+  try {
+    const { readLedger } = require('./track-context-budget');
+    entries = readLedger(planningDir);
+  } catch (_e) {
+    try {
+      const ledgerPath = path.join(planningDir, '.context-ledger.json');
+      entries = JSON.parse(fs.readFileSync(ledgerPath, 'utf8'));
+    } catch (_e2) {
+      entries = [];
+    }
+  }
+
+  // Detect current phase from STATE.md
+  let currentPhase = null;
+  try {
+    const statePath = path.join(planningDir, 'STATE.md');
+    const stateContent = fs.readFileSync(statePath, 'utf8');
+    const phaseMatch = stateContent.match(/phase_name:\s*"?([^"\n]+)"?/);
+    if (phaseMatch) {
+      currentPhase = phaseMatch[1].trim();
+    }
+  } catch (_e) { /* best-effort */ }
+
+  // Calculate sub-scores for breakdown
+  const staleMinutes = (config.context_ledger && config.context_ledger.stale_after_minutes) || 60;
+  const staleThresholdMs = staleMinutes * 60 * 1000;
+  const now = Date.now();
+
+  let freshCount = 0;
+  for (const entry of entries) {
+    if (entry.timestamp) {
+      const age = now - new Date(entry.timestamp).getTime();
+      if (age < staleThresholdMs) freshCount++;
+    }
+  }
+  const freshness = entries.length > 0 ? Math.round((freshCount / entries.length) * 100) : 100;
+
+  let relevantCount = 0;
+  if (currentPhase && entries.length > 0) {
+    for (const entry of entries) {
+      if (entry.phase === currentPhase) relevantCount++;
+    }
+  } else {
+    relevantCount = entries.length;
+  }
+  const relevance = entries.length > 0 ? Math.round((relevantCount / entries.length) * 100) : 100;
+
+  const groups = {};
+  let totalTokens = 0;
+  for (const entry of entries) {
+    const tokens = entry.est_tokens || 0;
+    totalTokens += tokens;
+    const dir = entry.file ? path.dirname(entry.file) : 'unknown';
+    groups[dir] = (groups[dir] || 0) + tokens;
+  }
+  let diversity = 100;
+  if (totalTokens > 0) {
+    const maxGroupPct = Math.max(...Object.values(groups)) / totalTokens * 100;
+    if (maxGroupPct > 80) {
+      diversity = Math.max(0, Math.round(100 - (maxGroupPct - 80) * 2.5));
+    }
+  }
+
+  const score = scoreContext(entries, config, currentPhase);
+
+  return {
+    score,
+    breakdown: { freshness, relevance, diversity },
+    timestamp: new Date().toISOString(),
+    entry_count: entries.length
+  };
+}
+
+/**
+ * Write quality report to .planning/.context-quality.json (atomic write).
+ *
+ * @param {string} planningDir - Path to .planning/ directory
+ * @param {Object} report - Quality report object
+ */
+function writeQualityReport(planningDir, report) {
+  try {
+    const filePath = path.join(planningDir, '.context-quality.json');
+    const tmpPath = filePath + '.' + process.pid;
+    fs.writeFileSync(tmpPath, JSON.stringify(report, null, 2), 'utf8');
+    fs.renameSync(tmpPath, filePath);
+    logHook('context-quality', 'score', 'updated', { score: report.score });
+  } catch (_e) {
+    // Fire-and-forget
+    try { fs.unlinkSync(path.join(planningDir, '.context-quality.json.' + process.pid)); } catch (_e2) { /* cleanup */ }
+  }
+}
+
+/**
+ * Check if the project is eligible for Skip-RAG (loading entire codebase).
+ *
+ * @param {string} planningDir - Path to .planning/ directory
+ * @returns {{ eligible: boolean, reason?: string, line_count?: number, max?: number }}
+ */
+function isSkipRagEligible(planningDir) {
+  try {
+    // Load config
+    let config;
+    try {
+      const { configLoad } = require('./lib/config');
+      config = configLoad(planningDir);
+    } catch (_e) {
+      try {
+        const configPath = path.join(planningDir, 'config.json');
+        config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+      } catch (_e2) {
+        return { eligible: false, reason: 'config not found' };
+      }
+    }
+
+    if (!config || !config.features || config.features.skip_rag !== true) {
+      return { eligible: false, reason: 'disabled' };
+    }
+
+    const maxLines = config.skip_rag_max_lines || 50000;
+
+    // Count project lines using git ls-files
+    const { execSync } = require('child_process');
+    const projectRoot = planningDir.replace(/[/\\]\.planning$/, '');
+    const codeExtensions = ['js', 'ts', 'py', 'jsx', 'tsx', 'cjs', 'mjs', 'vue', 'svelte', 'go', 'rs', 'java', 'c', 'cpp', 'h', 'cs', 'rb', 'php'];
+
+    // Get list of tracked code files
+    const files = execSync(`git ls-files --cached`, {
+      encoding: 'utf8',
+      cwd: projectRoot,
+      timeout: 10000
+    }).trim().split('\n').filter(f => {
+      const ext = f.split('.').pop();
+      return codeExtensions.includes(ext);
+    });
+
+    // Count lines by reading files directly
+    let totalLines = 0;
+    const batchSize = 50;
+    for (let i = 0; i < files.length; i += batchSize) {
+      const batch = files.slice(i, i + batchSize);
+      try {
+        for (const file of batch) {
+          try {
+            const filePath = path.join(projectRoot, file);
+            const content = fs.readFileSync(filePath, 'utf8');
+            totalLines += content.split('\n').length;
+          } catch (_e) { /* skip unreadable files */ }
+        }
+      } catch (_e) { /* skip batch errors */ }
+    }
+
+    if (totalLines < maxLines) {
+      return { eligible: true, line_count: totalLines };
+    }
+    return { eligible: false, reason: 'project too large', line_count: totalLines, max: maxLines };
+  } catch (_e) {
+    return { eligible: false, reason: 'count failed' };
+  }
+}
+
+module.exports = { scoreContext, getQualityReport, writeQualityReport, isSkipRagEligible };

package/plugins/pbr/scripts/enforce-context-budget.js

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+
+/**
+ * PreToolUse hook: Context budget hard-stop enforcement.
+ *
+ * Blocks Skill and Task invocations when context usage reaches the
+ * hard_stop_percent threshold (default 70%). Read-only tools (Read, Glob,
+ * Grep) and Bash are never blocked — only Skill and Task, which spawn
+ * expensive subagents or skill flows.
+ *
+ * Reads .planning/.context-budget.json (written by context-bridge.js)
+ * for current estimated_percent. Configurable via config.json:
+ *   context_budget.hard_stop_percent (default: 70)
+ *   context_budget.enforce (default: true)
+ *
+ * Exit codes:
+ *   0 = always (PreToolUse hooks must exit 0; use decision:block in output)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+
+const DEFAULT_HARD_STOP_PERCENT = 70;
+const STALE_THRESHOLD_MS = 60000; // 60 seconds
+
+/**
+ * Core enforcement logic. Returns block output or null (allow).
+ *
+ * @param {Object} options
+ * @param {string} options.toolName - Name of the tool being invoked
+ * @param {string} options.planningDir - Path to .planning/ directory
+ * @returns {Object|null} { decision: "block", reason: "..." } or null
+ */
+function checkBudget({ toolName, planningDir }) {
+  // Only enforce for Task and Skill
+  if (toolName !== 'Task' && toolName !== 'Skill') {
+    return null;
+  }
+
+  // Read bridge file
+  const bridgePath = path.join(planningDir, '.context-budget.json');
+  let bridge;
+  try {
+    const content = fs.readFileSync(bridgePath, 'utf8');
+    bridge = JSON.parse(content);
+  } catch (_e) {
+    // No bridge file or unreadable — no enforcement
+    return null;
+  }
+
+  // Check staleness
+  if (bridge.timestamp) {
+    const ageMs = Date.now() - new Date(bridge.timestamp).getTime();
+    if (ageMs > STALE_THRESHOLD_MS) {
+      return null; // Stale data is unreliable
+    }
+  }
+
+  // Read config for thresholds and enforcement toggle
+  let hardStopPercent = DEFAULT_HARD_STOP_PERCENT;
+  let enforce = true;
+  try {
+    const { configLoad } = require('./lib/config');
+    const config = configLoad(planningDir);
+    if (config && config.context_budget) {
+      if (config.context_budget.hard_stop_percent != null) {
+        hardStopPercent = config.context_budget.hard_stop_percent;
+      }
+      if (config.context_budget.enforce === false) {
+        enforce = false;
+      }
+    }
+  } catch (_e) {
+    // Use defaults
+  }
+
+  if (!enforce) {
+    return null;
+  }
+
+  const percent = bridge.estimated_percent || 0;
+
+  if (percent >= hardStopPercent) {
+    logHook('enforce-context-budget', 'PreToolUse', 'block', {
+      percent,
+      threshold: hardStopPercent,
+      tool: toolName
+    });
+    return {
+      decision: 'block',
+      reason: `Context budget at ${percent}% (threshold: ${hardStopPercent}%). Run /clear or /compact and start a fresh session. Read-only tools still work.`
+    };
+  }
+
+  return null;
+}
+
+function main() {
+  let input = '';
+
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => { input += chunk; });
+  process.stdin.on('end', () => {
+    try {
+      const data = input ? JSON.parse(input) : {};
+      const toolName = data.tool_name || '';
+
+      // Quick exit for non-target tools
+      if (toolName !== 'Task' && toolName !== 'Skill') {
+        process.stdout.write(JSON.stringify({}));
+        process.exit(0);
+      }
+
+      const planningDir = path.join(
+        process.env.PBR_PROJECT_ROOT || process.cwd(),
+        '.planning'
+      );
+
+      if (!fs.existsSync(planningDir)) {
+        process.stdout.write(JSON.stringify({}));
+        process.exit(0);
+      }
+
+      const result = checkBudget({ toolName, planningDir });
+      process.stdout.write(JSON.stringify(result || {}));
+      process.exit(0);
+    } catch (_e) {
+      // Never crash — allow on error
+      process.stdout.write(JSON.stringify({}));
+      process.exit(0);
+    }
+  });
+}
+
+module.exports = { checkBudget };
+
+if (require.main === module || process.argv[1] === __filename) { main(); }