@sienklogic/plan-build-run 2.18.1 → 2.19.1

package/plugins/pbr/scripts/instructions-loaded.js

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+
+/**
+ * InstructionsLoaded hook: Lightweight PBR state reminder after CLAUDE.md loads.
+ *
+ * Fires each time Claude Code loads CLAUDE.md or .claude/rules/*.md files.
+ * For PBR projects: injects a brief reminder that PBR workflow is active.
+ * Debounces mid-session re-fires using .session.json load timestamp.
+ *
+ * Non-blocking — always exits 0.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+const { resolveSessionPath } = require('./lib/core');
+
+function readStdin() {
+  try {
+    const input = fs.readFileSync(0, 'utf8').trim();
+    if (input) return JSON.parse(input);
+  } catch (_e) { /* empty or non-JSON stdin */ }
+  return {};
+}
+
+function main() {
+  const data = readStdin();
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+
+  // Only relevant for PBR projects
+  if (!fs.existsSync(planningDir)) {
+    process.exit(0);
+  }
+
+  // Debounce: only emit additionalContext on first fire per session.
+  // .session.json is written by progress-tracker.js at SessionStart.
+  // If it exists with a sessionStart timestamp, this is a mid-session reload.
+  const sessionId = data.session_id || null;
+  let isMidSession = false;
+  try {
+    const sessionFile = sessionId
+      ? resolveSessionPath(planningDir, '.session.json', sessionId)
+      : path.join(planningDir, '.session.json');
+    if (fs.existsSync(sessionFile)) {
+      const session = JSON.parse(fs.readFileSync(sessionFile, 'utf8'));
+      if (session.sessionStart) {
+        isMidSession = true;
+      }
+    }
+  } catch (_e) { /* non-fatal */ }
+
+  logHook('instructions-loaded', 'InstructionsLoaded', isMidSession ? 'mid-session-reload' : 'initial-load', {
+    instructions_file: data.instructions_file || null
+  });
+
+  // Track hook count changes across reloads
+  try {
+    const hookCountFile = path.join(planningDir, '.hook-count');
+    const hooksJsonPath = path.join(__dirname, '..', 'hooks', 'hooks.json');
+    const altHooksPath = path.join(__dirname, 'hooks.json');
+    const hooksPath = fs.existsSync(hooksJsonPath) ? hooksJsonPath : (fs.existsSync(altHooksPath) ? altHooksPath : null);
+    if (hooksPath) {
+      const hooksConfig = JSON.parse(fs.readFileSync(hooksPath, 'utf8'));
+      let currentCount = 0;
+      for (const event of Object.values(hooksConfig)) {
+        if (Array.isArray(event)) currentCount += event.length;
+      }
+
+      if (fs.existsSync(hookCountFile)) {
+        const previousCount = parseInt(fs.readFileSync(hookCountFile, 'utf8').trim(), 10);
+        if (!isNaN(previousCount) && currentCount < previousCount) {
+          logHook('instructions-loaded', 'InstructionsLoaded', 'hook-count-decreased', {
+            previous: previousCount,
+            current: currentCount,
+            lost: previousCount - currentCount
+          });
+          const warning = `[PBR] Hook count decreased after reload: ${previousCount} -> ${currentCount} (${previousCount - currentCount} hooks lost). Some workflow enforcement may be degraded. Run /pbr:health to check.`;
+          process.stdout.write(JSON.stringify({ additionalContext: warning }));
+          fs.writeFileSync(hookCountFile, String(currentCount));
+          process.exit(0);
+        }
+      }
+      // Save current count for future comparison
+      fs.writeFileSync(hookCountFile, String(currentCount));
+    }
+  } catch (_e) {
+    // Never crash the hook for hook-count tracking
+  }
+
+  // Mid-session: note that instructions reloaded (CLAUDE.md may have changed)
+  if (isMidSession) {
+    process.stdout.write(JSON.stringify({
+      additionalContext: '[Plan-Build-Run] Project CLAUDE.md was reloaded mid-session. If PBR workflow rules changed, current skill invocation may be affected. Check .planning/STATE.md for current position.'
+    }));
+    process.exit(0);
+  }
+
+  // Initial load: no additionalContext needed — progress-tracker.js already
+  // injected full state at SessionStart. Avoid double-injection.
+  process.exit(0);
+}
+
+/**
+ * handleHttp — hook-server.js interface.
+ * reqBody = { event, tool, data, planningDir, cache }
+ * Returns { additionalContext: "..." } or null. Never calls process.exit().
+ */
+function handleHttp(reqBody) {
+  const data = (reqBody && reqBody.data) || {};
+  const planningDir = reqBody && reqBody.planningDir;
+  if (!planningDir || !fs.existsSync(planningDir)) return null;
+
+  const sessionId = data.session_id || null;
+  let isMidSession = false;
+  try {
+    const sessionFile = sessionId
+      ? resolveSessionPath(planningDir, '.session.json', sessionId)
+      : path.join(planningDir, '.session.json');
+    if (fs.existsSync(sessionFile)) {
+      const session = JSON.parse(fs.readFileSync(sessionFile, 'utf8'));
+      if (session.sessionStart) isMidSession = true;
+    }
+  } catch (_e) { /* non-fatal */ }
+
+  logHook('instructions-loaded', 'InstructionsLoaded', isMidSession ? 'mid-session-reload' : 'initial-load', {
+    instructions_file: data.instructions_file || null
+  });
+
+  // Track hook count changes across reloads
+  try {
+    const hookCountFile = path.join(planningDir, '.hook-count');
+    const hooksJsonPath = path.join(__dirname, '..', 'hooks', 'hooks.json');
+    const altHooksPath = path.join(__dirname, 'hooks.json');
+    const hooksPath = fs.existsSync(hooksJsonPath) ? hooksJsonPath : (fs.existsSync(altHooksPath) ? altHooksPath : null);
+    if (hooksPath) {
+      const hooksConfig = JSON.parse(fs.readFileSync(hooksPath, 'utf8'));
+      let currentCount = 0;
+      for (const event of Object.values(hooksConfig)) {
+        if (Array.isArray(event)) currentCount += event.length;
+      }
+
+      if (fs.existsSync(hookCountFile)) {
+        const previousCount = parseInt(fs.readFileSync(hookCountFile, 'utf8').trim(), 10);
+        if (!isNaN(previousCount) && currentCount < previousCount) {
+          logHook('instructions-loaded', 'InstructionsLoaded', 'hook-count-decreased', {
+            previous: previousCount,
+            current: currentCount,
+            lost: previousCount - currentCount
+          });
+          const warning = `[PBR] Hook count decreased after reload: ${previousCount} -> ${currentCount} (${previousCount - currentCount} hooks lost). Some workflow enforcement may be degraded. Run /pbr:health to check.`;
+          fs.writeFileSync(hookCountFile, String(currentCount));
+          return { additionalContext: warning };
+        }
+      }
+      fs.writeFileSync(hookCountFile, String(currentCount));
+    }
+  } catch (_e) {
+    // Never crash the hook for hook-count tracking
+  }
+
+  if (isMidSession) {
+    return {
+      additionalContext: '[Plan-Build-Run] Project CLAUDE.md was reloaded mid-session. If PBR workflow rules changed, current skill invocation may be affected. Check .planning/STATE.md for current position.'
+    };
+  }
+  return null;
+}
+
+if (require.main === module || process.argv[1] === __filename) { main(); }
+module.exports = { main, handleHttp };

package/plugins/pbr/scripts/intent-router.cjs

@@ -0,0 +1,147 @@
+/**
+ * Intent router — classifies freeform text into PBR skill routes with confidence scoring.
+ *
+ * Pure function: no side effects, no file I/O. Consumable by /pbr:do and prompt-routing hook.
+ */
+
+'use strict';
+
+const ROUTE_MAP = {
+  debug: {
+    keywords: ['bug', 'error', 'crash', 'fix', 'broken', 'failing', 'exception', 'stacktrace', 'debug'],
+    weight: 1.0
+  },
+  explore: {
+    keywords: ['explore', 'research', 'investigate', 'how does', 'how do', 'how the', 'understand', 'analyze', 'compare', 'works'],
+    weight: 1.0
+  },
+  'plan-phase': {
+    keywords: ['plan', 'architect', 'design', 'migrate', 'refactor across', 'refactor', 'redesign', 'system', 'new'],
+    weight: 0.9
+  },
+  quick: {
+    keywords: ['add', 'create', 'update', 'change', 'rename', 'remove', 'write test', 'implement', 'button', 'feature', 'refactor'],
+    weight: 0.85
+  },
+  note: {
+    keywords: ['remember', 'note', 'todo', 'idea', 'later', "don't forget", 'remind'],
+    weight: 1.0
+  },
+  'verify-work': {
+    keywords: ['review', 'check', 'verify', 'quality', 'looks right'],
+    weight: 0.9
+  }
+};
+
+/**
+ * Score a single route against input text.
+ * Returns a value between 0 and 1 based on keyword match density and weight.
+ * @param {string} text - Lowercase normalized input
+ * @param {{ keywords: string[], weight: number }} routeConfig
+ * @returns {number} Score in 0-1 range
+ */
+function scoreRoute(text, routeConfig) {
+  let matches = 0;
+  for (const keyword of routeConfig.keywords) {
+    if (text.includes(keyword)) {
+      matches++;
+    }
+  }
+  if (matches === 0) return 0;
+
+  // Confidence based on match count:
+  // 1 match = 0.5, 2 matches = 0.75, 3+ matches = 0.95+
+  // Uses diminishing returns: 0.5 + 0.25 * (1 - 1/(matches+1))
+  const baseConfidence = 0.5 + 0.5 * (1 - 1 / (matches + 1));
+
+  return baseConfidence * routeConfig.weight;
+}
+
+/**
+ * Classify freeform text into a PBR skill route with confidence scoring.
+ *
+ * @param {string} text - User's natural language input
+ * @param {object} [context={}] - Optional context signals
+ * @param {string} [context.recentError] - Recent error message (boosts debug)
+ * @param {boolean} [context.activePhase] - Whether a phase is active (boosts plan-phase)
+ * @param {boolean} [context.hasRoadmap] - Whether a roadmap exists (demotes plan-phase if false)
+ * @returns {{ route: string, confidence: number, candidates: Array<{ route: string, confidence: number }> }}
+ */
+function classifyIntent(text, context) {
+  if (context === undefined) context = {};
+  const normalized = text.toLowerCase();
+
+  // Score each route
+  const scores = {};
+  for (const [route, config] of Object.entries(ROUTE_MAP)) {
+    scores[route] = scoreRoute(normalized, config);
+  }
+
+  // Apply context boosters
+  if (context.recentError) {
+    scores.debug = (scores.debug || 0) + 0.3;
+  }
+  if (context.activePhase) {
+    scores['plan-phase'] = (scores['plan-phase'] || 0) + 0.1;
+  }
+  if (context.hasRoadmap === false) {
+    scores['plan-phase'] = (scores['plan-phase'] || 0) - 0.2;
+  }
+
+  // Clamp all scores to 0-1
+  for (const route of Object.keys(scores)) {
+    scores[route] = Math.max(0, Math.min(1, scores[route]));
+  }
+
+  // Sort by score descending
+  const sorted = Object.entries(scores)
+    .map(([route, confidence]) => ({ route, confidence }))
+    .sort((a, b) => b.confidence - a.confidence);
+
+  // No matches at all
+  if (sorted.length === 0 || sorted[0].confidence === 0) {
+    return {
+      route: 'quick',
+      confidence: 0.3,
+      candidates: [{ route: 'quick', confidence: 0.3 }],
+      auditEntry: {
+        timestamp: new Date().toISOString(),
+        input: text.substring(0, 100),
+        route: 'quick',
+        confidence: 0.3,
+        risk: null
+      }
+    };
+  }
+
+  const top = sorted[0];
+
+  // Build audit entry for logging by callers
+  const auditEntry = {
+    timestamp: new Date().toISOString(),
+    input: text.substring(0, 100),
+    route: top.route,
+    confidence: top.confidence,
+    risk: null  // populated by caller when risk-classifier is used
+  };
+
+  if (top.confidence >= 0.7) {
+    return {
+      route: top.route,
+      confidence: top.confidence,
+      candidates: [top],
+      auditEntry
+    };
+  }
+
+  // Ambiguous — return top 3 candidates with non-zero confidence
+  const topThree = sorted.slice(0, 3).filter(c => c.confidence > 0);
+  return {
+    route: top.route,
+    confidence: top.confidence,
+    candidates: topThree,
+    auditEntry
+  };
+}
+
+module.exports = { classifyIntent, ROUTE_MAP };

package/plugins/pbr/scripts/intercept-plan-mode.js

@@ -4,44 +4,78 @@
  * PreToolUse hook on EnterPlanMode: Warns users in PBR projects that
  * native plan mode won't integrate with PBR's planning system.
  *
- * Suggests /pbr:plan instead. Does NOT block — just advises.
+ * Suggests /pbr:plan-phase instead. Does NOT block — just advises.
  *
  * Exit codes:
- *   0 = always (advisory only, never blocks)
+ *   0 = not a PBR project (passes through)
+ *   2 = blocked (PBR project detected — redirects to /pbr:plan-phase)
  */
 
 const fs = require('fs');
 const path = require('path');
 const { logHook } = require('./hook-logger');
 
+/**
+ * Core detection logic extracted for both stdin (main) and HTTP (handleHttp) paths.
+ *
+ * @param {Object} data - Parsed hook input (same as stdin JSON)
+ * @returns {Object|null} { decision: 'block', reason } if PBR project detected, null otherwise
+ */
+function checkPlanMode(data) {
+  const cwd = (data && data.cwd) || process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+
+  // Only relevant for Plan-Build-Run projects
+  if (!fs.existsSync(planningDir)) {
+    return null;
+  }
+
+  logHook('intercept-plan-mode', 'PreToolUse', 'warn', {
+    reason: 'native plan mode used in PBR project'
+  });
+
+  return {
+    decision: 'block',
+    reason: 'This is a Plan-Build-Run project. Native plan mode stores plans outside .planning/ and won\'t integrate with PBR\'s workflow.\n\nUse instead:\n  /pbr:plan-phase <phase>  — Create a PBR-formatted plan for a phase\n  /pbr:quick         — Plan and execute an ad-hoc task\n  /pbr:import        — Import an external plan document into PBR format\n\nIf you already generated a plan in native plan mode, paste it into /pbr:import to convert it.'
+  };
+}
+
+/**
+ * HTTP handler for hook-server.js.
+ * Called as handleHttp(reqBody, cache) where reqBody = { event, tool, data, planningDir, cache }.
+ * Must NOT call process.exit().
+ *
+ * @param {Object} reqBody - Request body from hook-server
+ * @param {Object} _cache - In-memory server cache (unused)
+ * @returns {Object|null} Hook response or null
+ */
+async function handleHttp(reqBody, _cache) {
+  try {
+    const data = (reqBody && reqBody.data) ? reqBody.data : {};
+    return checkPlanMode(data);
+  } catch (_e) {
+    return null;
+  }
+}
+
 function main() {
   process.stdin.setEncoding('utf8');
   process.stdin.on('data', () => {});
   process.stdin.on('end', () => {
     try {
-      const cwd = process.cwd();
-      const planningDir = path.join(cwd, '.planning');
-
-      // Only relevant for Plan-Build-Run projects
-      if (!fs.existsSync(planningDir)) {
+      const result = checkPlanMode({});
+      if (!result) {
         process.exit(0);
       }
-
-      logHook('intercept-plan-mode', 'PreToolUse', 'warn', {
-        reason: 'native plan mode used in PBR project'
-      });
-
-      const output = {
-        decision: 'block',
-        reason: 'This is a Plan-Build-Run project. Native plan mode stores plans outside .planning/ and won\'t integrate with PBR\'s workflow.\n\nUse instead:\n  /pbr:plan <phase>  — Create a PBR-formatted plan for a phase\n  /pbr:quick         — Plan and execute an ad-hoc task\n  /pbr:import        — Import an external plan document into PBR format\n\nIf you already generated a plan in native plan mode, paste it into /pbr:import to convert it.'
-      };
-      process.stdout.write(JSON.stringify(output));
+      process.stdout.write(JSON.stringify(result));
       process.exit(2);
     } catch (_e) {
+      process.stderr.write(`[pbr] intercept-plan-mode error: ${_e.message}\n`);
+      process.stdout.write(JSON.stringify({ decision: 'allow', additionalContext: '⚠ [PBR] intercept-plan-mode failed: ' + _e.message }));
       process.exit(0);
     }
   });
 }
 
 if (require.main === module || process.argv[1] === __filename) { main(); }
-module.exports = { main };
+module.exports = { main, checkPlanMode, handleHttp };

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

@@ -0,0 +1,203 @@
+'use strict';
+
+/**
+ * alternatives.js — Conversational error recovery helpers for PBR skills.
+ *
+ * Provides structured JSON responses for three error scenarios:
+ *   phaseAlternatives(slug, planningDir)      — phase-not-found recovery
+ *   prerequisiteAlternatives(phase, planningDir) — missing-prereq recovery
+ *   configAlternatives(field, value, planningDir) — config-invalid recovery
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Known config fields and their valid values
+const KNOWN_CONFIG_FIELDS = {
+  'depth': ['quick', 'standard', 'deep'],
+  'git.branching': ['phase', 'main', 'off'],
+  'gates.confirm_plan': [true, false, 'true', 'false'],
+  'gates.confirm_execute': [true, false, 'true', 'false'],
+  'gates.confirm_review': [true, false, 'true', 'false'],
+  'gates.confirm_milestone': [true, false, 'true', 'false'],
+  'parallelism': ['off', 'wave', 'full'],
+  'models.default': ['haiku', 'sonnet', 'inherit'],
+  'models.planner': ['haiku', 'sonnet', 'inherit'],
+  'models.executor': ['haiku', 'sonnet', 'inherit'],
+  'models.verifier': ['haiku', 'sonnet', 'inherit']
+};
+
+/**
+ * Score similarity between two strings using character overlap.
+ * Returns a value between 0 and 1 (higher = more similar).
+ *
+ * @param {string} a - First string
+ * @param {string} b - Second string
+ * @returns {number} Similarity score between 0 and 1
+ */
+function scoreSlug(a, b) {
+  if (!a || !b) return 0;
+  const lowerA = a.toLowerCase();
+  const lowerB = b.toLowerCase();
+  // Count shared characters (by frequency)
+  const freqA = {};
+  for (const ch of lowerA) freqA[ch] = (freqA[ch] || 0) + 1;
+  let shared = 0;
+  const freqB = {};
+  for (const ch of lowerB) freqB[ch] = (freqB[ch] || 0) + 1;
+  for (const ch of Object.keys(freqA)) {
+    if (freqB[ch]) shared += Math.min(freqA[ch], freqB[ch]);
+  }
+  // Also boost score when one string contains the other as substring
+  let substringBonus = 0;
+  if (lowerB.includes(lowerA) || lowerA.includes(lowerB)) substringBonus = 0.2;
+  const score = shared / Math.max(lowerA.length, lowerB.length) + substringBonus;
+  return Math.min(score, 1);
+}
+
+/**
+ * Generate alternatives for a phase-not-found error.
+ *
+ * @param {string} slug - The unknown phase slug
+ * @param {string} planningDir - Path to .planning directory
+ * @returns {{ error_type: string, slug: string, available: string[], suggestions: string[] }}
+ */
+function phaseAlternatives(slug, planningDir) {
+  const phasesDir = path.join(planningDir, 'phases');
+  let available = [];
+
+  try {
+    if (fs.existsSync(phasesDir)) {
+      const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+      available = entries
+        .filter(e => e.isDirectory())
+        .map(e => e.name);
+    }
+  } catch (_e) {
+    // If we can't read, return empty
+    available = [];
+  }
+
+  let suggestions = [];
+  if (slug && slug.length > 0 && available.length > 0) {
+    const scored = available
+      .map(name => ({ name, score: scoreSlug(slug, name) }))
+      .filter(s => s.score > 0.3)
+      .sort((a, b) => b.score - a.score)
+      .slice(0, 3)
+      .map(s => s.name);
+    suggestions = scored;
+  }
+
+  return {
+    error_type: 'phase-not-found',
+    slug,
+    available,
+    suggestions
+  };
+}
+
+/**
+ * Generate alternatives for a missing-prerequisite error.
+ *
+ * @param {string} phase - The phase slug to check
+ * @param {string} planningDir - Path to .planning directory
+ * @returns {{ error_type: string, phase: string, existing_summaries: string[], missing_summaries: string[], suggested_action: string }}
+ */
+function prerequisiteAlternatives(phase, planningDir) {
+  const phasesDir = path.join(planningDir, 'phases');
+
+  // Find the phase directory (exact match or prefix match)
+  let phaseDir = null;
+  try {
+    if (fs.existsSync(phasesDir)) {
+      const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+      const match = entries.find(e => e.isDirectory() && (e.name === phase || e.name.endsWith('-' + phase) || e.name === phase));
+      if (match) {
+        phaseDir = path.join(phasesDir, match.name);
+      } else {
+        // Try exact slug match
+        const exact = path.join(phasesDir, phase);
+        if (fs.existsSync(exact)) phaseDir = exact;
+      }
+    }
+  } catch (_e) { /* best effort */ }
+
+  const existing_summaries = [];
+  const missing_summaries = [];
+
+  if (phaseDir && fs.existsSync(phaseDir)) {
+    try {
+      const files = fs.readdirSync(phaseDir);
+      const planFiles = files.filter(f => /^PLAN-\d+\.md$/i.test(f));
+
+      for (const planFile of planFiles) {
+        // Extract plan ID from filename (e.g. PLAN-01.md → look for SUMMARY-{phase-num}-01.md)
+        const match = planFile.match(/^PLAN-(\d+)\.md$/i);
+        if (!match) continue;
+        const planNum = match[1];
+
+        // Check for any SUMMARY file matching this plan number
+        const summaryFiles = files.filter(f => {
+          const sm = f.match(/^SUMMARY[-.](.*?)\.md$/i);
+          if (!sm) return false;
+          return sm[1].endsWith('-' + planNum) || sm[1] === planNum;
+        });
+
+        if (summaryFiles.length > 0) {
+          existing_summaries.push(summaryFiles[0]);
+        } else {
+          // Infer the expected plan ID from directory name prefix + plan number
+          const dirMatch = (phaseDir.split(path.sep).pop() || '').match(/^(\d+)-/);
+          const phaseNum = dirMatch ? dirMatch[1] : '';
+          const expectedId = phaseNum ? `${phaseNum}-${planNum}` : planNum;
+          missing_summaries.push(`SUMMARY-${expectedId}.md`);
+        }
+      }
+    } catch (_e) { /* best effort */ }
+  }
+
+  return {
+    error_type: 'missing-prereq',
+    phase,
+    existing_summaries,
+    missing_summaries,
+    suggested_action: `Run /pbr:execute-phase ${phase} to generate missing summaries`
+  };
+}
+
+/**
+ * Generate alternatives for a config-invalid error.
+ *
+ * @param {string} field - The config field name
+ * @param {string} value - The current invalid value
+ * @param {string} _planningDir - Path to .planning directory (unused, for API consistency)
+ * @returns {{ error_type: string, field: string, current_value: string, valid_values: Array, suggested_fix: string }}
+ */
+function configAlternatives(field, value, _planningDir) {
+  const knownValues = KNOWN_CONFIG_FIELDS[field];
+
+  if (knownValues !== undefined) {
+    // Convert to string representations for JSON output
+    const validStrings = knownValues
+      .filter(v => typeof v === 'string')
+      .filter((v, i, arr) => arr.indexOf(v) === i); // dedupe
+    return {
+      error_type: 'config-invalid',
+      field,
+      current_value: value,
+      valid_values: validStrings.length > 0 ? validStrings : knownValues.filter(v => typeof v !== 'boolean'),
+      suggested_fix: `Set ${field} to one of: ${validStrings.join(', ')}`
+    };
+  }
+
+  return {
+    error_type: 'config-invalid',
+    field,
+    current_value: value,
+    valid_values: [],
+    suggested_fix: 'Remove this field from config.json or check spelling'
+  };
+}
+
+module.exports = { phaseAlternatives, prerequisiteAlternatives, configAlternatives };

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

@@ -0,0 +1,65 @@
+/**
+ * Audit utilities for Plan-Build-Run.
+ *
+ * Provides functions to query hooks.jsonl logs for plan-checker
+ * and other audit-relevant events.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { resolveProjectRoot } = require('./resolve-root');
+
+/**
+ * Query plan-checker results from hooks.jsonl log files.
+ *
+ * @param {object} options
+ * @param {number} [options.last=30] - Number of days to look back
+ * @returns {{ entries: Array, total: number, passed: number, failed: number, date_range: { from: string, to: string } }}
+ */
+function auditPlanChecks(options = {}) {
+  const cwd = resolveProjectRoot();
+  const logsDir = path.join(cwd, '.planning', 'logs');
+  if (!fs.existsSync(logsDir)) return { entries: [], total: 0, passed: 0, failed: 0, date_range: { from: '', to: '' } };
+
+  const files = fs.readdirSync(logsDir)
+    .filter(f => /^hooks-\d{4}-\d{2}-\d{2}\.jsonl$/.test(f))
+    .sort();
+
+  // Filter to last N days
+  const lastDays = options.last || 30;
+  const cutoff = new Date(Date.now() - lastDays * 86400000).toISOString().slice(0, 10);
+  const relevantFiles = files.filter(f => {
+    const dateStr = f.replace('hooks-', '').replace('.jsonl', '');
+    return dateStr >= cutoff;
+  });
+
+  const entries = [];
+  for (const file of relevantFiles) {
+    const filePath = path.join(logsDir, file);
+    const lines = fs.readFileSync(filePath, 'utf8').split('\n').filter(Boolean);
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line);
+        if (entry.hook === 'plan-checker' && entry.action === 'validate') {
+          entries.push({
+            timestamp: entry.ts,
+            phase: entry.phase,
+            status: entry.status,
+            dimensions: entry.dimensions,
+            blockers: entry.blockers
+          });
+        }
+      } catch (_e) { /* skip malformed lines */ }
+    }
+  }
+
+  return {
+    entries,
+    total: entries.length,
+    passed: entries.filter(e => e.status === 'passed').length,
+    failed: entries.filter(e => e.status === 'issues_found').length,
+    date_range: { from: cutoff, to: new Date().toISOString().slice(0, 10) }
+  };
+}
+
+module.exports = { auditPlanChecks };