@sienklogic/plan-build-run 2.33.1 → 2.37.0

package/plugins/pbr/references/pbr-tools-cli.md

@@ -283,3 +283,118 @@ node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js event error hook-failure '{"scri
 **Output:** `{ "logged": true, "category": "build", "event": "plan-complete" }`
 
 If the JSON-details argument is not valid JSON, it's stored as `{ "raw": "<the string>" }`.
+
+---
+
+## Compound Init Commands
+
+Compound commands that compose multiple data sources into a single JSON response.
+Replace multi-step context loading in skills with a single CLI call.
+
+### `init execute-phase <phase>`
+
+Everything an executor needs to start building a phase.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js init execute-phase 3
+```
+
+**Output:**
+```json
+{
+  "executor_model": "sonnet",
+  "verifier_model": "sonnet",
+  "config": { "depth": "standard", "mode": "interactive", "parallelization": {}, "planning": {}, "gates": {}, "features": {} },
+  "phase": { "num": "3", "dir": "03-auth", "name": "auth", "goal": "...", "has_context": false, "status": "planned", "plan_count": 2, "completed": 0 },
+  "plans": [{ "file": "PLAN-01.md", "plan_id": "01", "wave": 1, "autonomous": true, "has_summary": false, "must_haves_count": 4, "depends_on": [] }],
+  "waves": { "wave_1": ["01", "02"] },
+  "branch_name": "main",
+  "git_clean": true
+}
+```
+
+### `init plan-phase <phase>`
+
+Everything a planner needs to start phase planning.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js init plan-phase 3
+```
+
+**Output:** `researcher_model`, `planner_model`, `checker_model`, `config` (depth profile, features, planning settings), `phase` (num, dir, goal, depends_on), `existing_artifacts`, `workflow` flags.
+
+### `init quick <description>`
+
+Everything the quick skill needs: next task number, slug, directory path.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js init quick "add search feature"
+```
+
+**Output:** `next_task_number`, `slug`, `dir`, `dir_name`, `timestamp`, `config` subset.
+
+### `init verify-work <phase>`
+
+Everything a verifier needs to start verification.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js init verify-work 3
+```
+
+**Output:** `verifier_model`, `phase` info, `has_verification`, `prior_attempts`, `prior_status`, `summaries`.
+
+### `init resume`
+
+Detect interrupted state and suggest continuation.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js init resume
+```
+
+**Output:** `state`, `auto_next`, `continue_here`, `active_skill`, `current_phase`, `progress`.
+
+### `init progress`
+
+All phases with status and completion data.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js init progress
+```
+
+**Output:** `current_phase`, `total_phases`, `status`, `phases` array, `total_plans`, `completed_plans`, `percentage`.
+
+---
+
+## State Mutation Extensions
+
+### `state patch <JSON>`
+
+Multi-field atomic STATE.md update. Updates all fields in a single pass.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state patch '{"status":"executing","last_activity":"now"}'
+```
+
+**Valid fields:** `current_phase`, `status`, `plans_complete`, `last_activity`, `progress_percent`, `phase_slug`, `total_phases`, `last_command`, `blockers`
+
+**Output:** `{ "success": true, "updated": ["status", "last_activity"] }`
+
+### `state advance-plan`
+
+Increment current plan number in STATE.md and update progress percentage.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state advance-plan
+```
+
+**Output:** `{ "success": true, "previous_plan": 1, "current_plan": 2, "total_plans": 5, "progress_percent": 40 }`
+
+### `state record-metric [--duration Nm] [--plans-completed N]`
+
+Record session/execution metrics. Appends to HISTORY.md and updates last_activity.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state record-metric --duration 15m --plans-completed 3
+```
+
+**Output:** `{ "success": true, "duration_minutes": 15, "plans_completed": 3 }`

package/plugins/pbr/references/questioning.md

@@ -212,3 +212,24 @@ See **[skills/shared/domain-probes.md](../shared/domain-probes.md)** for technol
 9. **DO NOT** lead the user toward a particular solution
 10. **DO NOT** forget to summarize and confirm understanding
 11. **DO NOT** ask what you already know — track what the user has stated and never re-ask it. If they said "I'm using React", do not later ask "Are you using a frontend framework?" If they said "PostgreSQL", do not ask "What database are you using?" Redundant questions waste exchanges and erode trust. Instead, build on what you know: "You mentioned React — are you using Next.js or plain CRA?"
+
+---
+
+## Dream Extraction Philosophy
+
+The goal of questioning is not to gather requirements — it's to extract the user's dream and make it buildable.
+
+### 4-Item Context Checklist
+Before planning can begin, you must know:
+1. **What** are we building? (concrete deliverable, not abstract concept)
+2. **Why** does it exist? (the problem it solves, not the tech it uses)
+3. **Who** is it for? (specific users, not "everyone")
+4. **What does done look like?** (observable outcomes, not technical milestones)
+
+### Conversation Rules
+- **Start open**: "Tell me about what you want to build"
+- **Follow energy**: When they light up about something, dig deeper there
+- **Challenge vagueness**: "You said 'user-friendly' — what does that mean specifically?"
+- **Know when to stop**: When you have the 4 items above, move to planning
+- **NEVER ask about technical experience**: It's irrelevant and condescending
+- **NEVER present a menu of options**: Open questions reveal more than multiple choice

package/plugins/pbr/references/verification-patterns.md

@@ -196,3 +196,55 @@ Bad:  "Tests pass"
 Good: "All 5 auth middleware tests pass: valid token, expired token,
        missing token, malformed token, and correct user extraction"
 ```
+
+---
+
+## Wiring Verification Patterns
+
+4 concrete patterns for verifying components are actually connected, not just present.
+
+### Pattern 1: Component to API
+1. Find the fetch/axios call in the component
+2. Verify the call is NOT commented out
+3. Verify the response is assigned to state (not discarded)
+4. Verify error handling exists (try/catch or .catch)
+
+### Pattern 2: API to Database
+1. Find the database query in the route handler
+2. Verify `await` is present (not fire-and-forget)
+3. Verify the result is returned in the response (not discarded)
+4. Verify error cases return appropriate HTTP status codes
+
+### Pattern 3: Form to Handler
+1. Find the form's onSubmit handler
+2. Verify it calls an API function (not just preventDefault)
+3. Verify form validation runs before the API call
+4. Verify success/error feedback is shown to the user
+
+### Pattern 4: State to Render
+1. Find state variables (useState, store, etc.)
+2. Verify they appear in JSX/template via .map(), interpolation, or conditional rendering
+3. Verify loading/error states are rendered (not just success state)
+4. Verify empty state is handled (not just "no data" crash)
+
+### Quick Verification Checklists
+
+**Component Checklist (8 items):**
+- [ ] Component file exists and exports correctly
+- [ ] Props/types are defined (not `any`)
+- [ ] API calls use actual endpoints (not hardcoded data)
+- [ ] Loading state renders something meaningful
+- [ ] Error state renders something meaningful
+- [ ] Empty state renders something meaningful
+- [ ] User interactions trigger actual handlers
+- [ ] Component is imported and rendered in parent
+
+**API Route Checklist (8 items):**
+- [ ] Route file exists and exports handler
+- [ ] Route is registered in router/app
+- [ ] Request validation exists (body, params, query)
+- [ ] Database query uses parameterized inputs
+- [ ] Success response includes expected data shape
+- [ ] Error response includes status code and message
+- [ ] Authentication/authorization check exists if needed
+- [ ] Response matches what the frontend expects

package/plugins/pbr/scripts/check-plan-format.js

@@ -24,7 +24,7 @@ const fs = require('fs');
 const path = require('path');
 const { logHook } = require('./hook-logger');
 const { logEvent } = require('./event-logger');
-const { atomicWrite } = require('./pbr-tools');
+const { lockedFileUpdate } = require('./pbr-tools');
 const { resolveConfig } = require('./local-llm/health');
 const { classifyArtifact } = require('./local-llm/operations/classify-artifact');
 
@@ -194,7 +194,7 @@ function validatePlan(content, _filePath) {
 
     // Skip checkpoint tasks - they have different required elements
     const taskTag = taskTags[index] || '';
-    if (taskTag.includes('checkpoint')) {
+    if (/\btype\s*=\s*["']?checkpoint/i.test(taskTag) || /\bcheckpoint\s*[:=]/i.test(taskTag)) {
       return; // Checkpoint tasks have different structure
     }
 
@@ -205,6 +205,18 @@ function validatePlan(content, _filePath) {
     }
   });
 
+  // Path traversal check: ensure <files> elements don't escape project root
+  const filesTags = content.match(/<files>([\s\S]*?)<\/files>/g) || [];
+  for (const filesTag of filesTags) {
+    const filesContent = filesTag.replace(/<\/?files>/g, '');
+    const paths = filesContent.split(/[\n,]/).map(p => p.trim()).filter(Boolean);
+    for (const p of paths) {
+      if (p.includes('..') || path.isAbsolute(p.replace(/^[A-Za-z]:/, ''))) {
+        warnings.push(`Path traversal risk in <files>: "${p}" — use relative paths without ".." segments`);
+      }
+    }
+  }
+
   return { errors, warnings };
 }
 
@@ -464,7 +476,7 @@ function syncStateBody(content, filePath) {
   if (!needsFix) return null;
 
   try {
-    atomicWrite(filePath, updated);
+    lockedFileUpdate(filePath, () => updated);
     logHook('check-plan-format', 'PostToolUse', 'body-sync', {
       fromPhase: bodyPhaseMatch[1], toPhase: fmPhase
     });

package/plugins/pbr/scripts/check-state-sync.js

@@ -26,7 +26,25 @@ const fs = require('fs');
 const path = require('path');
 const { logHook } = require('./hook-logger');
 const { logEvent } = require('./event-logger');
-const { atomicWrite } = require('./pbr-tools');
+
+/**
+ * Write content to a file atomically using write-then-rename.
+ * Writes to a PID-stamped temp file, then renames over the original.
+ * If the rename fails, cleans up the temp file and re-throws.
+ *
+ * @param {string} filePath - Target file path
+ * @param {string} content - Content to write
+ */
+function atomicWriteFile(filePath, content) {
+  const tmpPath = filePath + '.tmp.' + process.pid;
+  try {
+    fs.writeFileSync(tmpPath, content, 'utf8');
+    fs.renameSync(tmpPath, filePath);
+  } catch (e) {
+    try { fs.unlinkSync(tmpPath); } catch (_) { /* best effort cleanup */ }
+    throw e;
+  }
+}
 
 /**
  * Extract phase number from a phase directory name.
@@ -326,7 +344,7 @@ function checkStateSync(data) {
     return null;
   }
 
-  const cwd = process.cwd();
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
   const planningDir = path.join(cwd, '.planning');
   const roadmapPath = path.join(planningDir, 'ROADMAP.md');
   const statePath = path.join(planningDir, 'STATE.md');
@@ -370,7 +388,7 @@ function checkStateSync(data) {
         } else {
           const updatedRoadmap = updateProgressTable(roadmapContent, phaseNum, plansComplete, newStatus, completedDate);
           if (updatedRoadmap !== roadmapContent) {
-            atomicWrite(roadmapPath, updatedRoadmap);
+            atomicWriteFile(roadmapPath, updatedRoadmap);
             messages.push(`ROADMAP.md: Phase ${phaseNum} → ${plansComplete} plans, ${newStatus}`);
           }
         }
@@ -410,7 +428,7 @@ function checkStateSync(data) {
 
         const updatedState = updateStatePosition(stateContent, stateUpdates);
         if (updatedState !== stateContent) {
-          atomicWrite(statePath, updatedState);
+          atomicWriteFile(statePath, updatedState);
           messages.push(`STATE.md: ${artifacts.completeSummaries}/${artifacts.plans} plans, ${overallPct}%`);
         }
       } catch (e) {
@@ -455,7 +473,7 @@ function checkStateSync(data) {
         } else {
           const updatedRoadmap = updateProgressTable(roadmapContent, phaseNum, plansComplete, roadmapStatus, completedDate);
           if (updatedRoadmap !== roadmapContent) {
-            atomicWrite(roadmapPath, updatedRoadmap);
+            atomicWriteFile(roadmapPath, updatedRoadmap);
             messages.push(`ROADMAP.md: Phase ${phaseNum} → ${roadmapStatus}`);
           }
         }
@@ -493,7 +511,7 @@ function checkStateSync(data) {
 
         const updatedState = updateStatePosition(stateContent, stateUpdates);
         if (updatedState !== stateContent) {
-          atomicWrite(statePath, updatedState);
+          atomicWriteFile(statePath, updatedState);
           messages.push(`STATE.md: ${stateStatus}, ${overallPct}%`);
         }
       } catch (e) {
@@ -543,7 +561,7 @@ function checkStateSync(data) {
             const plansComplete = `${artifacts.completeSummaries}/${artifacts.plans}`;
             const updatedRoadmap = updateProgressTable(roadmapContent, phaseNum, plansComplete, 'Planning', null);
             if (updatedRoadmap !== roadmapContent) {
-              atomicWrite(roadmapPath, updatedRoadmap);
+              atomicWriteFile(roadmapPath, updatedRoadmap);
               messages.push(`ROADMAP.md: Phase ${phaseNum} → Planning`);
             }
           }
@@ -588,6 +606,7 @@ function main() {
 
 if (require.main === module || process.argv[1] === __filename) { main(); }
 module.exports = {
+  atomicWriteFile,
   extractPhaseNum,
   countPhaseArtifacts,
   updateProgressTable,

package/plugins/pbr/scripts/check-subagent-output.js

@@ -20,6 +20,7 @@
 const fs = require('fs');
 const path = require('path');
 const { logHook } = require('./hook-logger');
+const { KNOWN_AGENTS } = require('./pbr-tools');
 const { resolveConfig } = require('./local-llm/health');
 const { classifyError } = require('./local-llm/operations/classify-error');
 
@@ -27,7 +28,7 @@ const { classifyError } = require('./local-llm/operations/classify-error');
  * Check if a file was modified recently (within thresholdMs).
  * Returns false if file doesn't exist or on error.
  */
-function isRecent(filePath, thresholdMs = 300000) {
+function isRecent(filePath, thresholdMs = 1800000) {
   try {
     const stat = fs.statSync(filePath);
     return (Date.now() - stat.mtimeMs) < thresholdMs;
@@ -151,6 +152,25 @@ const AGENT_OUTPUTS = {
     description: 'advisory output (no file expected)',
     noFileExpected: true,
     check: () => []
+  },
+  'pbr:audit': {
+    description: 'audit report in .planning/audits/',
+    check: (planningDir) => {
+      const auditsDir = path.join(planningDir, 'audits');
+      if (!fs.existsSync(auditsDir)) return [];
+      try {
+        return fs.readdirSync(auditsDir)
+          .filter(f => f.endsWith('.md'))
+          .map(f => path.join('audits', f));
+      } catch (_e) {
+        return [];
+      }
+    }
+  },
+  'pbr:dev-sync': {
+    description: 'advisory output (no file expected)',
+    noFileExpected: true,
+    check: () => []
   }
 };
 
@@ -324,7 +344,7 @@ function loadLocalLlmConfig(cwd) {
 
 async function main() {
   const data = readStdin();
-  const cwd = process.cwd();
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
   const planningDir = path.join(cwd, '.planning');
 
   // Only relevant for Plan-Build-Run projects
@@ -338,6 +358,14 @@ async function main() {
   // Only check known Plan-Build-Run agent types
   const outputSpec = AGENT_OUTPUTS[agentType];
   if (!outputSpec) {
+    // Log when agent is in KNOWN_AGENTS but missing from AGENT_OUTPUTS
+    const shortName = agentType.startsWith('pbr:') ? agentType.slice(4) : agentType;
+    if (KNOWN_AGENTS && KNOWN_AGENTS.includes && KNOWN_AGENTS.includes(shortName)) {
+      logHook('check-subagent-output', 'PostToolUse', 'missing-output-spec', {
+        agent_type: agentType,
+        message: `Agent ${agentType} is in KNOWN_AGENTS but has no AGENT_OUTPUTS entry. Add one to check-subagent-output.js.`
+      });
+    }
     process.exit(0);
   }
 

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

@@ -4,7 +4,8 @@
   "description": "Configuration schema for .planning/config.json",
   "type": "object",
   "properties": {
-    "version": { "type": "integer", "enum": [1, 2] },
+    "version": { "type": ["integer", "string"], "enum": [1, 2, "1", "2"], "description": "Planning format version. v2 is current." },
+    "schema_version": { "type": "integer", "enum": [1], "description": "Config schema version for migration detection. Increment when config structure changes." },
     "context_strategy": { "type": "string", "enum": ["aggressive", "conservative", "balanced"] },
     "mode": { "type": "string", "enum": ["interactive", "autonomous"] },
     "depth": { "type": "string", "enum": ["quick", "standard", "comprehensive"], "description": "Workflow depth: quick = budget mode (fewer spawns, skip optional stages), standard = balanced mode (conditional spawns), comprehensive = thorough mode (all spawns, current default)" },
@@ -131,6 +132,15 @@
       },
       "additionalProperties": false
     },
+    "timeouts": {
+      "type": "object",
+      "properties": {
+        "task_default_ms": { "type": "integer", "minimum": 30000, "description": "Default timeout per task in milliseconds (default: 300000 = 5 min)" },
+        "build_max_ms": { "type": "integer", "minimum": 60000, "description": "Maximum time for entire build command in milliseconds" },
+        "verify_max_ms": { "type": "integer", "minimum": 30000, "description": "Maximum time for verification in milliseconds" }
+      },
+      "additionalProperties": false
+    },
     "hooks": {
       "type": "object",
       "properties": {

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

@@ -0,0 +1,259 @@
+#!/usr/bin/env node
+
+/**
+ * PostToolUse hook: Context monitor bridge.
+ *
+ * Replaces heuristic context budget estimation with real data when available.
+ * Writes context state to .planning/.context-budget.json for consumption by
+ * track-context-budget.js and suggest-compact.js.
+ *
+ * Context tiers:
+ *   PEAK      (0-30%)  — no warnings
+ *   GOOD      (30-50%) — no warnings
+ *   DEGRADING (50-70%) — suggest subagent delegation
+ *   POOR      (70%+)   — recommend /pbr:pause
+ *
+ * Debounce: same-tier warnings suppressed for 5 tool calls.
+ * Tier escalation always warns immediately.
+ *
+ * Exit codes:
+ *   0 = always (PostToolUse hook, advisory only)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+
+const TIERS = [
+  { name: 'PEAK', min: 0, max: 30 },
+  { name: 'GOOD', min: 30, max: 50 },
+  { name: 'DEGRADING', min: 50, max: 70 },
+  { name: 'POOR', min: 70, max: 100 }
+];
+
+const TIER_MESSAGES = {
+  DEGRADING: 'Context is filling. Consider delegating heavy work to subagents.',
+  POOR: 'Context critically low. Recommend /pbr:pause to save state.'
+};
+
+const DEBOUNCE_INTERVAL = 5; // tool calls between same-tier warnings
+
+/**
+ * Determine the context tier for a given percentage.
+ * @param {number} percent - Context usage percentage (0-100)
+ * @returns {{ name: string, min: number, max: number }}
+ */
+function getTier(percent) {
+  for (const tier of TIERS) {
+    if (percent < tier.max) return tier;
+  }
+  return TIERS[TIERS.length - 1];
+}
+
+/**
+ * Load the bridge state file.
+ * @param {string} bridgePath - Absolute path to .context-budget.json
+ * @returns {Object} Bridge state
+ */
+function loadBridge(bridgePath) {
+  try {
+    const content = fs.readFileSync(bridgePath, 'utf8');
+    return JSON.parse(content);
+  } catch (_e) {
+    return null;
+  }
+}
+
+/**
+ * Save the bridge state file atomically.
+ * @param {string} bridgePath - Absolute path to .context-budget.json
+ * @param {Object} data - Bridge state to persist
+ */
+function saveBridge(bridgePath, data) {
+  try {
+    const tmpPath = bridgePath + '.' + process.pid;
+    fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2), 'utf8');
+    fs.renameSync(tmpPath, bridgePath);
+  } catch (_e) {
+    // Best-effort — clean up temp file if rename failed
+    try { fs.unlinkSync(bridgePath + '.' + process.pid); } catch (_e2) { /* best-effort */ }
+  }
+}
+
+/**
+ * Estimate context percentage from heuristic tracker data.
+ * Uses the .context-tracker file written by track-context-budget.js.
+ * Assumes 200k token context window (~800k chars).
+ *
+ * @param {string} planningDir - Path to .planning/
+ * @returns {number} Estimated context usage percentage (0-100)
+ */
+function estimateFromHeuristic(planningDir) {
+  const trackerPath = path.join(planningDir, '.context-tracker');
+  try {
+    const content = fs.readFileSync(trackerPath, 'utf8');
+    const tracker = JSON.parse(content);
+    const totalChars = tracker.total_chars || 0;
+    // 200k tokens ~ 800k chars; use 800000 as denominator
+    const percent = Math.min(100, Math.round((totalChars / 800000) * 100));
+    return percent;
+  } catch (_e) {
+    return 0;
+  }
+}
+
+/**
+ * Check if a tier warning should fire, applying debounce logic.
+ *
+ * @param {Object} bridge - Current bridge state
+ * @param {string} tierName - Current tier name
+ * @returns {boolean} True if warning should fire
+ */
+function shouldWarn(bridge, tierName) {
+  // No warning for PEAK or GOOD
+  if (tierName === 'PEAK' || tierName === 'GOOD') return false;
+
+  const prevTier = bridge.last_warned_tier || 'PEAK';
+  const callsSinceWarn = bridge.calls_since_warn || 0;
+
+  // Tier escalation — always warn
+  const tierOrder = { PEAK: 0, GOOD: 1, DEGRADING: 2, POOR: 3 };
+  if ((tierOrder[tierName] || 0) > (tierOrder[prevTier] || 0)) {
+    return true;
+  }
+
+  // Same tier — debounce
+  if (callsSinceWarn >= DEBOUNCE_INTERVAL) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Core bridge logic: update bridge state, return warning if applicable.
+ *
+ * @param {string} planningDir - Path to .planning/
+ * @param {Object} stdinData - Parsed stdin JSON from Claude Code
+ * @returns {{ bridge: Object, output: Object|null }} Updated bridge and optional warning output
+ */
+function updateBridge(planningDir, stdinData) {
+  const bridgePath = path.join(planningDir, '.context-budget.json');
+
+  // Check if Claude Code provides real context percentage in stdin
+  // Look for context_percent, usage_percent, context_usage, or similar fields
+  const contextPercent = stdinData.context_percent
+    || stdinData.usage_percent
+    || (stdinData.context && stdinData.context.percent)
+    || null;
+
+  const source = contextPercent !== null ? 'bridge' : 'heuristic';
+  const estimatedPercent = contextPercent !== null
+    ? Math.round(contextPercent)
+    : estimateFromHeuristic(planningDir);
+
+  // Load existing bridge state
+  let bridge = loadBridge(bridgePath) || {
+    timestamp: new Date().toISOString(),
+    estimated_percent: 0,
+    source: 'heuristic',
+    chars_read: 0,
+    warnings_issued: [],
+    last_warned_tier: 'PEAK',
+    calls_since_warn: 0,
+    tool_calls: 0
+  };
+
+  // Update bridge
+  bridge.timestamp = new Date().toISOString();
+  bridge.estimated_percent = estimatedPercent;
+  bridge.source = source;
+  bridge.tool_calls = (bridge.tool_calls || 0) + 1;
+  bridge.calls_since_warn = (bridge.calls_since_warn || 0) + 1;
+
+  // Read chars from tracker if available
+  const trackerPath = path.join(planningDir, '.context-tracker');
+  try {
+    const tracker = JSON.parse(fs.readFileSync(trackerPath, 'utf8'));
+    bridge.chars_read = tracker.total_chars || 0;
+  } catch (_e) {
+    // Keep existing value
+  }
+
+  const tier = getTier(estimatedPercent);
+  let output = null;
+
+  if (shouldWarn(bridge, tier.name)) {
+    const msg = TIER_MESSAGES[tier.name];
+    if (msg) {
+      bridge.last_warned_tier = tier.name;
+      bridge.calls_since_warn = 0;
+      bridge.warnings_issued = bridge.warnings_issued || [];
+      bridge.warnings_issued.push({
+        tier: tier.name,
+        percent: estimatedPercent,
+        timestamp: new Date().toISOString()
+      });
+
+      // Keep only last 20 warnings
+      if (bridge.warnings_issued.length > 20) {
+        bridge.warnings_issued = bridge.warnings_issued.slice(-20);
+      }
+
+      output = {
+        additionalContext: `[Context Monitor — ${tier.name}] ${estimatedPercent}% used (${source}). ${msg}`
+      };
+    }
+  }
+
+  // Save bridge state
+  saveBridge(bridgePath, bridge);
+
+  return { bridge, output };
+}
+
+function main() {
+  let input = '';
+
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => { input += chunk; });
+  process.stdin.on('end', () => {
+    try {
+      const cwd = process.cwd();
+      const planningDir = path.join(cwd, '.planning');
+      if (!fs.existsSync(planningDir)) {
+        process.exit(0);
+      }
+
+      const data = input ? JSON.parse(input) : {};
+      const { output } = updateBridge(planningDir, data);
+
+      if (output) {
+        logHook('context-bridge', 'PostToolUse', 'warn', {
+          percent: output.additionalContext.match(/(\d+)%/)?.[1],
+          source: 'bridge'
+        });
+        process.stdout.write(JSON.stringify(output));
+      }
+
+      process.exit(0);
+    } catch (_e) {
+      // Never block on tracking errors
+      process.exit(0);
+    }
+  });
+}
+
+module.exports = {
+  getTier,
+  loadBridge,
+  saveBridge,
+  estimateFromHeuristic,
+  shouldWarn,
+  updateBridge,
+  TIERS,
+  TIER_MESSAGES,
+  DEBOUNCE_INTERVAL
+};
+
+if (require.main === module || process.argv[1] === __filename) { main(); }