@sienklogic/plan-build-run 2.21.0 → 2.21.2

package/plugins/pbr/scripts/prompt-routing.js

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+
+/**
+ * UserPromptSubmit hook: Detects PBR-relevant intent in user prompts
+ * and injects routing hints when the user isn't using /pbr:* commands.
+ *
+ * Only activates for PBR projects (has .planning/ directory).
+ * Skips prompts that already start with /pbr: or other slash commands.
+ *
+ * Intent detection patterns:
+ *   - Bug/error reports → suggests /pbr:debug
+ *   - Feature requests or task descriptions → suggests /pbr:do
+ *   - Planning/architecture discussion → suggests /pbr:explore
+ *   - Status/progress queries → suggests /pbr:progress
+ *
+ * Exit codes:
+ *   0 = always (advisory only, never blocks user input)
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+
+// NL routing: try to load classifyIntent from intent-router.cjs
+let classifyIntent = null;
+try {
+  const intentRouter = require(path.join(__dirname, 'intent-router.cjs'));
+  classifyIntent = intentRouter.classifyIntent;
+} catch (_e) {
+  // intent-router.cjs not available — NL routing disabled gracefully
+}
+
+/**
+ * Load NL routing config from .planning/config.json.
+ * Returns { nlEnabled: boolean } based on features.natural_language_routing toggle.
+ * Defaults to true if config missing or toggle absent.
+ */
+function loadNLConfig(planningDir) {
+  try {
+    const configPath = path.join(planningDir, 'config.json');
+    if (!fs.existsSync(configPath)) return { nlEnabled: true };
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    const features = config.features || {};
+    return { nlEnabled: features.natural_language_routing !== false };
+  } catch (_e) {
+    return { nlEnabled: true };
+  }
+}
+
+/**
+ * Intent patterns ranked by specificity. First match wins.
+ * Each pattern maps user intent to a PBR command suggestion.
+ */
+const INTENT_PATTERNS = [
+  {
+    pattern: /\b(bug|error|crash|exception|stack\s*trace|failing|broken|doesn'?t\s+work|not\s+working)\b/i,
+    command: '/pbr:debug',
+    hint: 'This looks like a bug report. Use /pbr:debug for systematic investigation with hypothesis tracking.'
+  },
+  {
+    pattern: /\b(status|progress|where\s+(are|were)\s+we|what'?s\s+next|current\s+phase)\b/i,
+    command: '/pbr:progress',
+    hint: 'Use /pbr:progress to see project status and next steps.'
+  },
+  {
+    pattern: /\b(explore|research|how\s+(does|do|should|would)|what\s+if|compare|pros\s+and\s+cons|trade-?offs?)\b/i,
+    command: '/pbr:explore',
+    hint: 'This sounds exploratory. Use /pbr:explore for Socratic investigation.'
+  },
+  {
+    pattern: /\b(refactor|migrate|redesign|architect|restructure|overhaul|rewrite)\b/i,
+    command: '/pbr:plan-phase add',
+    hint: 'Complex work like this benefits from full planning. Use /pbr:plan-phase add.'
+  },
+  {
+    // Generic task — anything actionable that doesn't match above
+    pattern: /\b(add|create|implement|build|write|update|change|fix|remove|delete|set\s+up|configure|install)\b/i,
+    command: '/pbr:do',
+    hint: 'Use /pbr:do to auto-route this to the right PBR skill.'
+  }
+];
+
+/**
+ * Analyze a user prompt and return a routing suggestion if applicable.
+ * Returns null if no suggestion is warranted.
+ *
+ * @param {string} prompt - The user's raw prompt text
+ * @param {string} planningDir - Path to .planning/ directory
+ * @returns {{ command: string, hint: string }|null}
+ */
+function analyzePrompt(prompt, planningDir) {
+  if (!prompt || typeof prompt !== 'string') return null;
+
+  const trimmed = prompt.trim();
+
+  // Skip slash commands — user already knows what they want
+  if (trimmed.startsWith('/')) return null;
+
+  // Skip very short prompts (likely follow-up responses like "yes", "ok", "3")
+  if (trimmed.length < 15) return null;
+
+  // Skip if .planning/ doesn't exist (not a PBR project)
+  if (!fs.existsSync(planningDir)) return null;
+
+  // Skip if no active PBR project (no STATE.md)
+  if (!fs.existsSync(path.join(planningDir, 'STATE.md'))) return null;
+
+  // NL routing: use classifyIntent when available and enabled
+  const { nlEnabled } = loadNLConfig(planningDir);
+  if (nlEnabled && classifyIntent) {
+    try {
+      const hasRoadmap = fs.existsSync(path.join(planningDir, 'ROADMAP.md'));
+      const result = classifyIntent(trimmed, { hasRoadmap });
+
+      if (result && result.confidence >= 0.7) {
+        // Map intent-router route names to /pbr: commands
+        const routeCommandMap = {
+          'debug': '/pbr:debug',
+          'explore': '/pbr:explore',
+          'plan-phase': '/pbr:plan-phase add',
+          'quick': '/pbr:do',
+          'note': '/pbr:note',
+          'verify-work': '/pbr:review'
+        };
+        const command = routeCommandMap[result.route] || '/pbr:do';
+        return {
+          command,
+          hint: `This looks like a ${result.route} task. Consider using /pbr:do for automatic routing, or ${command} directly.`,
+          nlRoute: { route: result.route, confidence: result.confidence }
+        };
+      }
+      // Low confidence from classifyIntent — fall through to pattern matching
+    } catch (_e) {
+      // classifyIntent error — fall through to pattern matching
+    }
+  }
+
+  // Fallback: pattern-based routing (always available)
+  for (const intent of INTENT_PATTERNS) {
+    if (intent.pattern.test(trimmed)) {
+      return { command: intent.command, hint: intent.hint };
+    }
+  }
+
+  return null;
+}
+
+function main() {
+  let input = '';
+
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => { input += chunk; });
+  process.stdin.on('end', () => {
+    try {
+      const data = JSON.parse(input);
+      const prompt = data.prompt || data.user_prompt || data.content || '';
+      const cwd = data.cwd || process.env.PBR_PROJECT_ROOT || process.cwd();
+      const planningDir = path.join(cwd, '.planning');
+
+      const suggestion = analyzePrompt(prompt, planningDir);
+
+      if (suggestion) {
+        logHook('prompt-routing', 'UserPromptSubmit', 'suggest', {
+          command: suggestion.command
+        });
+        process.stdout.write(JSON.stringify({
+          additionalContext: `[pbr] ${suggestion.hint}\n\`${suggestion.command}\``
+        }));
+      }
+
+      process.exit(0);
+    } catch (_e) {
+      // Never block on errors
+      process.stdout.write(JSON.stringify({ additionalContext: '⚠ [PBR] prompt-routing failed: ' + _e.message }));
+      process.exit(0);
+    }
+  });
+}
+
+/**
+ * HTTP handler for hook-server.js.
+ * @param {Object} reqBody - { event, tool, data, planningDir }
+ * @returns {{ additionalContext: string }|null}
+ */
+function handleHttp(reqBody) {
+  try {
+    const data = reqBody.data || {};
+    const prompt = data.prompt || data.user_prompt || data.content || '';
+    const planningDir = reqBody.planningDir || path.join(process.cwd(), '.planning');
+
+    const suggestion = analyzePrompt(prompt, planningDir);
+    if (suggestion) {
+      logHook('prompt-routing', 'UserPromptSubmit', 'suggest', {
+        command: suggestion.command
+      });
+      return {
+        additionalContext: `[pbr] ${suggestion.hint}\n\`${suggestion.command}\``
+      };
+    }
+  } catch (_e) {
+    // Never propagate
+  }
+  return null;
+}
+
+module.exports = { analyzePrompt, handleHttp, INTENT_PATTERNS };
+if (require.main === module || process.argv[1] === __filename) { main(); }

package/plugins/pbr/scripts/quick-status.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+
+/**
+ * quick-status.js -- Lightweight status snapshot for Plan-Build-Run.
+ *
+ * Reads ONLY STATE.md and ROADMAP.md to produce a 10-line plain text summary.
+ * Designed to complete in <2 seconds with minimal I/O.
+ *
+ * Usage:
+ *   node quick-status.js                    # standalone
+ *   node pbr-tools.js quick-status          # via dispatcher
+ *
+ * Programmatic:
+ *   const { quickStatus } = require('./quick-status');
+ *   const { text, data } = quickStatus(planningDir);
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { parseYamlFrontmatter } = require('./lib/core');
+const { normalizeMsysPath } = require('./lib/msys-path');
+
+/**
+ * Parse milestone information from ROADMAP.md content.
+ * Returns { activeName, activeVersion, phaseCount, shippedCount }.
+ */
+function parseRoadmapInfo(content) {
+  if (!content) {
+    return { activeName: 'none', activeVersion: '', phaseCount: 0, shippedCount: 0 };
+  }
+
+  const normalized = content.replace(/\r\n/g, '\n');
+  const lines = normalized.split('\n');
+
+  let activeName = 'none';
+  let activeVersion = '';
+  let phaseCount = 0;
+  let shippedCount = 0;
+  let inActiveMilestone = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    // Detect ## Milestone: Name (vX.Y) headings
+    const msMatch = line.match(/^##\s+Milestone[:\s]+(.+)/i);
+    if (msMatch) {
+      const raw = msMatch[1].trim();
+      const isCompleted = /COMPLETED/i.test(raw) || /SHIPPED/i.test(raw);
+
+      if (isCompleted) {
+        shippedCount++;
+        inActiveMilestone = false;
+        continue;
+      }
+
+      // This is an active milestone
+      const versionMatch = raw.match(/\(?(v[\d.]+)\)?/i);
+      activeVersion = versionMatch ? versionMatch[1] : '';
+      activeName = raw
+        .replace(/\(v[\d.]+\)/i, '')
+        .replace(/\bCOMPLETED\b/i, '')
+        .replace(/\bSHIPPED\b/i, '')
+        .replace(/[[\]]/g, '')
+        .replace(/--?\s*$/, '')
+        .trim()
+        .replace(/\s+/g, ' ');
+      inActiveMilestone = true;
+      phaseCount = 0;
+      continue;
+    }
+
+    // Count phases under active milestone
+    if (inActiveMilestone) {
+      // Stop at next ## heading that isn't a milestone phase
+      if (/^##\s/.test(line) && !msMatch) {
+        inActiveMilestone = false;
+        continue;
+      }
+      if (/^###\s+Phase\s+\d+/i.test(line)) {
+        phaseCount++;
+      }
+    }
+  }
+
+  // Also count shipped milestones from the summary table
+  // Table rows like: | vX.Y | Name | SHIPPED | date |
+  const tableShipped = lines.filter(l => /^\|.*SHIPPED/i.test(l)).length;
+  if (tableShipped > shippedCount) {
+    shippedCount = tableShipped;
+  }
+
+  return { activeName, activeVersion, phaseCount, shippedCount };
+}
+
+/**
+ * Produce a lightweight 10-line status snapshot.
+ *
+ * @param {string} planningDir - Path to .planning/ directory
+ * @returns {{ text: string, data: object }}
+ */
+function quickStatus(planningDir) {
+  // Resolve planningDir from env if not provided
+  if (!planningDir) {
+    let cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+    cwd = normalizeMsysPath(cwd);
+    planningDir = path.join(cwd, '.planning');
+  }
+
+  // --- Read STATE.md ---
+  let stateFm = {};
+  const statePath = path.join(planningDir, 'STATE.md');
+  try {
+    if (fs.existsSync(statePath)) {
+      const stateContent = fs.readFileSync(statePath, 'utf8');
+      stateFm = parseYamlFrontmatter(stateContent) || {};
+    }
+  } catch (_e) { /* graceful fallback */ }
+
+  const currentPhase = stateFm.current_phase != null ? stateFm.current_phase : 'unknown';
+  const phaseSlug = stateFm.phase_slug || stateFm.phase_name || 'unknown';
+  const status = stateFm.status || 'unknown';
+  const plansTotal = stateFm.plans_total != null ? stateFm.plans_total : 0;
+  const plansComplete = stateFm.plans_complete != null ? stateFm.plans_complete : 0;
+  const progressPercent = stateFm.progress_percent != null ? stateFm.progress_percent : 0;
+  const lastActivity = stateFm.last_activity || 'none';
+
+  // --- Read ROADMAP.md ---
+  let roadmapInfo = { activeName: 'none', activeVersion: '', phaseCount: 0, shippedCount: 0 };
+  const roadmapPath = path.join(planningDir, 'ROADMAP.md');
+  try {
+    if (fs.existsSync(roadmapPath)) {
+      const roadmapContent = fs.readFileSync(roadmapPath, 'utf8');
+      roadmapInfo = parseRoadmapInfo(roadmapContent);
+    }
+  } catch (_e) { /* graceful fallback */ }
+
+  // --- Build data object ---
+  const data = {
+    current_phase: currentPhase,
+    phase_slug: phaseSlug,
+    status,
+    plans_total: plansTotal,
+    plans_complete: plansComplete,
+    progress_percent: progressPercent,
+    milestone_name: roadmapInfo.activeName,
+    milestone_version: roadmapInfo.activeVersion,
+    phases_in_milestone: roadmapInfo.phaseCount,
+    milestones_shipped: roadmapInfo.shippedCount,
+    last_activity: lastActivity
+  };
+
+  // --- Build 10-line text output ---
+  const milestoneLabel = roadmapInfo.activeVersion
+    ? `${roadmapInfo.activeName} (${roadmapInfo.activeVersion})`
+    : roadmapInfo.activeName;
+
+  const text = [
+    'PBR Quick Status',
+    '================',
+    `Phase: ${currentPhase} (${phaseSlug})`,
+    `Status: ${status}`,
+    `Progress: ${plansComplete}/${plansTotal} plans (${progressPercent}%)`,
+    `Milestone: ${milestoneLabel}`,
+    `Phases in milestone: ${roadmapInfo.phaseCount}`,
+    `Milestones shipped: ${roadmapInfo.shippedCount}`,
+    `Last activity: ${lastActivity}`,
+    '================'
+  ].join('\n');
+
+  return { text, data };
+}
+
+// --- CLI entry point ---
+if (require.main === module || process.argv[1] === __filename) {
+  const result = quickStatus();
+  process.stdout.write(result.text + '\n');
+}
+
+module.exports = { quickStatus };

package/plugins/pbr/scripts/record-incident.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+
+/**
+ * record-incident.js — Shared hook helper for incident journal recording.
+ *
+ * All hooks require this module and call recordIncident() after block/warn
+ * decisions. Never throws — all errors are silently swallowed so hook
+ * behavior is unaffected.
+ *
+ * Exit-code contract: This module has no effect on hook exit codes.
+ */
+'use strict';
+
+let incidents;
+try {
+  // Resolve relative to plugin scripts dir → lib/incidents
+  incidents = require('./lib/incidents');
+} catch (_e) {
+  incidents = null;
+}
+
+/**
+ * Record an incident to the journal. Fire-and-forget.
+ *
+ * @param {Object} entry - Incident fields (see incidents.cjs entry format)
+ * @param {Object} [opts] - { cwd, planningDir }
+ */
+function recordIncident(entry, opts) {
+  if (!incidents) return;
+  try {
+    incidents.record(entry, opts || {});
+  } catch (_e) {
+    // Silently swallow — never affect hook behavior
+  }
+}
+
+module.exports = { recordIncident };

package/plugins/pbr/scripts/risk-classifier.cjs

@@ -0,0 +1,123 @@
+/**
+ * Risk classifier — categorizes task descriptions into low/medium/high risk
+ * with corresponding ceremony level recommendations.
+ *
+ * Pure function: no side effects, no file I/O. Consumable by /pbr:do and prompt-routing hook.
+ */
+
+'use strict';
+
+const RISK_LEVELS = {
+  LOW: 'low',
+  MEDIUM: 'medium',
+  HIGH: 'high'
+};
+
+const CEREMONY_MAP = {
+  low: 'inline',
+  medium: 'lightweight-plan',
+  high: 'full-plan-build-verify'
+};
+
+const HIGH_SIGNALS = [
+  'migrate', 'redesign', 'refactor across', 'refactor', 'architecture',
+  'security', 'database schema', 'database', 'breaking change',
+  'entire', 'across'
+];
+
+const MEDIUM_SIGNALS = [
+  'implement', 'create', 'integrate', 'add feature',
+  'new endpoint', 'write test', 'add', 'endpoint', 'api'
+];
+
+const LOW_SIGNALS = [
+  'typo', 'rename', 'config', 'update', 'fix typo',
+  'comment', 'readme', 'docs'
+];
+
+/**
+ * Match text against signal patterns and return score adjustment + signal descriptions.
+ * @param {string} text - Lowercase normalized input
+ * @param {string[]} patterns - Signal patterns to match
+ * @param {number} weight - Score per match
+ * @returns {{ score: number, signals: string[] }}
+ */
+function matchSignals(text, patterns, weight) {
+  let score = 0;
+  const signals = [];
+  for (const pattern of patterns) {
+    if (text.includes(pattern)) {
+      score += weight;
+      signals.push(pattern);
+    }
+  }
+  return { score, signals };
+}
+
+/**
+ * Classify risk level for a task description.
+ *
+ * @param {string} text - Task description
+ * @param {object} [context={}] - Optional context signals
+ * @param {number} [context.fileCount] - Number of files affected
+ * @param {number} [context.subsystems] - Number of subsystems involved
+ * @param {boolean} [context.hasTests] - Whether existing tests exist
+ * @returns {{ risk: string, ceremony: string, signals: string[] }}
+ */
+function classifyRisk(text, context) {
+  if (context === undefined) context = {};
+  const normalized = text.toLowerCase();
+
+  let score = 0;
+  const signals = [];
+
+  // Keyword scoring
+  const high = matchSignals(normalized, HIGH_SIGNALS, 3);
+  score += high.score;
+  signals.push(...high.signals.map(s => 'high-signal: ' + s));
+
+  const medium = matchSignals(normalized, MEDIUM_SIGNALS, 1);
+  score += medium.score;
+  signals.push(...medium.signals.map(s => 'medium-signal: ' + s));
+
+  const low = matchSignals(normalized, LOW_SIGNALS, -1);
+  score += low.score;
+  signals.push(...low.signals.map(s => 'low-signal: ' + s));
+
+  // Context scoring
+  if (context.fileCount >= 8) {
+    score += 3;
+    signals.push('8+ files affected');
+  } else if (context.fileCount >= 3) {
+    score += 1;
+    signals.push('3+ files affected');
+  }
+
+  if (context.subsystems >= 3) {
+    score += 5;
+    signals.push('3+ subsystems');
+  }
+
+  if (context.hasTests === false) {
+    score += 1;
+    signals.push('no existing tests');
+  }
+
+  // Threshold mapping
+  let risk;
+  if (score >= 4) {
+    risk = RISK_LEVELS.HIGH;
+  } else if (score >= 1) {
+    risk = RISK_LEVELS.MEDIUM;
+  } else {
+    risk = RISK_LEVELS.LOW;
+  }
+
+  return {
+    risk,
+    ceremony: CEREMONY_MAP[risk],
+    signals
+  };
+}
+
+module.exports = { classifyRisk, CEREMONY_MAP, RISK_LEVELS };

package/plugins/pbr/scripts/run-hook.js

@@ -16,28 +16,31 @@
  *     'scripts','run-hook.js'))(process.argv[1])\" <script> [args...]"
  *
  * Or directly (when CLAUDE_PLUGIN_ROOT resolves correctly):
- *   "node ${CLAUDE_PLUGIN_ROOT}/scripts/run-hook.js <script-name> [args...]"
+ *   "node ${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.js <script-name> [args...]"
  */
 
 'use strict';
 
+const fs = require('fs');
 const path = require('path');
+const { normalizeMsysPath } = require('./lib/msys-path');
 
-/**
- * Fix MSYS-style paths on Windows.
- * Converts /d/Repos/... to D:\Repos\...
- */
-function fixMsysPath(p) {
-  if (!p) return p;
-  const match = p.match(/^\/([a-zA-Z])\/(.*)/);
-  if (match) {
-    return match[1].toUpperCase() + ':\\' + match[2].replace(/\//g, '\\');
-  }
-  return p;
-}
+// Scripts that must run even without .planning/ (lifecycle hooks).
+// All per-tool-call hooks (PreToolUse, PostToolUse, etc.) are PBR-specific
+// and can early-exit when .planning/ doesn't exist, skipping their entire
+// require() chain (~10-20ms saved per hook invocation on non-PBR projects).
+const ALWAYS_RUN = new Set([
+  'progress-tracker.js',   // SessionStart — reports non-PBR status
+  'session-cleanup.js',    // SessionEnd — cleanup
+  'worktree-create.js',    // WorktreeCreate — creates .planning/ in worktrees
+  'worktree-remove.js',    // WorktreeRemove — cleans up worktrees
+  'instructions-loaded.js', // InstructionsLoaded — detects instruction changes
+  'check-config-change.js', // ConfigChange — monitors config
+  'hook-server-client.js', // HTTP dispatcher — routes lifecycle hooks (WorktreeCreate, etc.)
+]);
 
 // Fix CLAUDE_PLUGIN_ROOT in environment
-const pluginRoot = fixMsysPath(process.env.CLAUDE_PLUGIN_ROOT || '');
+const pluginRoot = normalizeMsysPath(process.env.CLAUDE_PLUGIN_ROOT || '');
 
 // When invoked via `node -e "..." scriptName`, process.argv is:
 //   [node, scriptName, ...extra]
@@ -60,7 +63,10 @@ if (invokedViaEval) {
 
 // When required as a module from -e bootstrap, export a runner function
 if (typeof module !== 'undefined' && module.exports) {
+  const BOOTSTRAP_SNIPPET = "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'scripts','run-hook.js'))\"";
   module.exports = runScript;
+  module.exports.BOOTSTRAP_SNIPPET = BOOTSTRAP_SNIPPET;
+  module.exports.runScript = runScript;
 }
 
 // If we have a script name, run it immediately
@@ -70,23 +76,57 @@ if (scriptName) {
 
 function runScript(name, args) {
   args = args || [];
+
   // Try __dirname first, then pluginRoot
   const candidates = [
     path.resolve(__dirname, name),
-    pluginRoot ? path.resolve(pluginRoot, 'scripts', name) : null
+    pluginRoot ? path.resolve(pluginRoot, 'hooks', name) : null
   ].filter(Boolean);
 
+  // Phase 1: Resolve the script path (cheap — just fs.statSync, no require).
+  // This must happen before the .planning/ check so missing scripts still
+  // get proper error messages regardless of project type.
+  let resolvedPath = null;
   for (const candidate of candidates) {
     try {
-      process.argv = [process.argv[0], candidate, ...args];
-      require(candidate);
-      return;
-    } catch (err) {
-      if (err.code !== 'MODULE_NOT_FOUND') throw err;
+      fs.statSync(candidate);
+      resolvedPath = candidate;
+      break;
+    } catch (_e) {
+      // Not found at this path
     }
   }
 
-  process.stderr.write(`run-hook: cannot find script: ${name}\n`);
-  process.stderr.write(`  searched: ${candidates.join(', ')}\n`);
-  process.exit(1);
+  if (!resolvedPath) {
+    process.stderr.write(`run-hook: cannot find script: ${name}\n`);
+    process.stderr.write(`  searched: ${candidates.join(', ')}\n`);
+    process.exit(1);
+  }
+
+  // Phase 2: Early-exit for non-PBR projects. Script exists but .planning/
+  // doesn't — skip loading the module entirely. This avoids the full
+  // require() chain (~10-20ms) for every hook invocation in non-PBR projects.
+  if (!ALWAYS_RUN.has(name)) {
+    const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+    try {
+      fs.statSync(path.join(cwd, '.planning'));
+    } catch (_e) {
+      process.exit(0);
+    }
+  }
+
+  // Phase 3: Load and execute the script with timing.
+  const startTime = process.hrtime();
+  process.argv = [process.argv[0], resolvedPath, ...args];
+  require(resolvedPath);
+
+  // Log slow hooks (>200ms) to stderr for diagnostics.
+  // Measures module load + synchronous setup time only.
+  // Async hooks (progress-tracker, post-write-dispatch, etc.) exit before this runs,
+  // so their actual execution time is NOT captured here.
+  const [secs, nanos] = process.hrtime(startTime);
+  const elapsedMs = secs * 1000 + nanos / 1e6;
+  if (elapsedMs > 200) {
+    process.stderr.write(`[pbr-timing] ${name}: ${Math.round(elapsedMs)}ms (>200ms threshold)\n`);
+  }
 }