@sienklogic/plan-build-run 2.11.0 → 2.12.1

package/hooks/dist/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('../plan-build-run/bin/lib/config.cjs');
+    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('../plan-build-run/bin/lib/config.cjs');
+      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/hooks/dist/enforce-pbr-workflow.js

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+
+/**
+ * PBR workflow enforcement checks.
+ *
+ * Provides advisory and blocking checks that ensure PBR workflow is
+ * followed even when the user doesn't explicitly invoke /pbr:* commands.
+ *
+ * Functions:
+ *   loadEnforcementConfig(planningDir) — reads config.json for enforcement level
+ *   checkUnmanagedSourceWrite(data)    — PreToolUse Write|Edit: warns/blocks unmanaged source writes
+ *   checkNonPbrAgent(data)             — PreToolUse Task: advises using pbr:* agents
+ *   checkUnmanagedCommit(data)         — PreToolUse Bash: advises git commits to use /pbr:quick
+ *
+ * All functions return null for pass, or { exitCode, output } for action.
+ * checkNonPbrAgent defaults to blocking (exitCode 2) — blocks non-PBR agents.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+const { resolveSessionPath } = require('../plan-build-run/bin/lib/core.cjs');
+
+/**
+ * Load the enforcement configuration from .planning/config.json.
+ * Also checks for .planning/.native-mode which bypasses all enforcement.
+ *
+ * @param {string} planningDir - absolute path to the .planning directory
+ * @returns {{ level: "advisory"|"block"|"off" }}
+ */
+function loadEnforcementConfig(planningDir) {
+  // .native-mode bypass takes precedence over all config settings
+  const nativeModeFile = path.join(planningDir, '.native-mode');
+  if (fs.existsSync(nativeModeFile)) {
+    return { level: 'off' };
+  }
+
+  try {
+    const configPath = path.join(planningDir, 'config.json');
+    const parsed = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    const level = parsed.workflow && parsed.workflow.enforce_pbr_skills;
+    if (level === 'advisory' || level === 'block' || level === 'off') {
+      return { level };
+    }
+  } catch (_e) {
+    // No config or parse error — use default
+  }
+
+  return { level: 'advisory' };
+}
+
+/**
+ * PreToolUse Write|Edit: warns or blocks source file writes that happen
+ * without an active PBR skill.
+ *
+ * Skip conditions:
+ *   - No .planning/ directory (not a PBR project)
+ *   - .planning/.active-skill exists (PBR skill is managing the session)
+ *   - Target file is inside .planning/ (planning files are always OK)
+ *   - Enforcement level is "off"
+ *
+ * @param {Object} data - parsed hook input from Claude Code
+ * @returns {null|{ exitCode: number, output: Object }}
+ */
+function checkUnmanagedSourceWrite(data) {
+  const filePath = data.tool_input && (data.tool_input.file_path || data.tool_input.path);
+  if (!filePath) return null;
+
+  const cwd = process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+
+  // Skip if not a PBR project
+  if (!fs.existsSync(planningDir)) return null;
+
+  // Skip if a PBR skill is active — session-scoped when session_id available
+  const { sessionLoad } = require('../plan-build-run/bin/lib/core.cjs');
+  const sessionId = data.session_id || null;
+  let activeSkill = sessionLoad(planningDir, sessionId).activeSkill || '';
+  if (!activeSkill) {
+    const skillPath = sessionId
+      ? resolveSessionPath(planningDir, '.active-skill', sessionId)
+      : path.join(planningDir, '.active-skill');
+    try { activeSkill = fs.readFileSync(skillPath, 'utf8').trim(); } catch (_) { /* file missing */ }
+  }
+  if (activeSkill) return null;
+
+  // Skip if writing inside .planning/
+  const normalizedFile = filePath.replace(/\\/g, '/');
+  const normalizedPlanning = planningDir.replace(/\\/g, '/');
+  if (normalizedFile.startsWith(normalizedPlanning)) return null;
+
+  // Also check with resolved symlinks (macOS /var → /private/var)
+  try {
+    const resolvedPlanning = fs.realpathSync(planningDir).replace(/\\/g, '/');
+    if (normalizedFile.startsWith(resolvedPlanning)) return null;
+  } catch (_e) { /* not resolvable */ }
+
+  const config = loadEnforcementConfig(planningDir);
+  if (config.level === 'off') return null;
+
+  const message =
+    'PBR workflow required: You are editing source code without an active PBR skill. ' +
+    'Route this work through a PBR command: /pbr:quick (small fix), /pbr:execute-phase (planned work), ' +
+    'or /pbr:do (auto-route). Set workflow.enforce_pbr_skills: off in config to disable.';
+
+  if (config.level === 'block') {
+    logHook('enforce-pbr-workflow', 'PreToolUse', 'block', { file: path.basename(filePath), level: 'block' });
+    return {
+      exitCode: 2,
+      output: { decision: 'block', reason: message }
+    };
+  }
+
+  // advisory (default)
+  logHook('enforce-pbr-workflow', 'PreToolUse', 'advisory', { file: path.basename(filePath), level: 'advisory' });
+  return {
+    exitCode: 0,
+    output: { additionalContext: '[pbr] ' + message }
+  };
+}
+
+/**
+ * Agent type → PBR agent mapping for advisory messages.
+ */
+const AGENT_MAPPING = {
+  'Explore': 'pbr:researcher or pbr:codebase-mapper',
+  'general-purpose': 'pbr:general',
+  'Plan': 'pbr:planner',
+  'Bash': 'pbr:executor'
+};
+
+/**
+ * PreToolUse Task: advises using pbr:* agents instead of generic agents.
+ *
+ * Skip conditions:
+ *   - No .planning/ directory (not a PBR project)
+ *   - subagent_type starts with "pbr:" (already using PBR agent)
+ *   - subagent_type is missing/empty (can't determine type)
+ *   - Enforcement level is "off"
+ *
+ * Defaults to **blocking** (exitCode 2) unless config overrides to "advisory".
+ * This is stricter than checkUnmanagedSourceWrite/checkUnmanagedCommit because
+ * non-PBR agents bypass audit logging, workflow context, and project-aware prompts.
+ *
+ * @param {Object} data - parsed hook input from Claude Code
+ * @returns {null|{ exitCode: number, output: Object }}
+ */
+function checkNonPbrAgent(data) {
+  const subagentType = data.tool_input && data.tool_input.subagent_type;
+  if (!subagentType || typeof subagentType !== 'string') return null;
+
+  // Already using a PBR agent
+  if (subagentType.startsWith('pbr:')) return null;
+
+  // Per-call bypass: user says "use native agents" and the LLM includes [native] in description
+  const description = (data.tool_input && data.tool_input.description) || '';
+  if (/\[native\]/i.test(description)) return null;
+
+  const cwd = process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+
+  // Skip if not a PBR project
+  if (!fs.existsSync(planningDir)) return null;
+
+  const config = loadEnforcementConfig(planningDir);
+  if (config.level === 'off') return null;
+
+  // For agent enforcement, determine the effective level.
+  // Priority: workflow.enforce_pbr_agents > workflow.enforce_pbr_skills > default "block"
+  // Agent enforcement is stricter than source write/commit checks — blocks by default.
+  let agentLevel = 'block'; // default: block non-PBR agents
+  try {
+    const configPath = path.join(planningDir, 'config.json');
+    const parsed = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    const agentExplicit = parsed.workflow && parsed.workflow.enforce_pbr_agents;
+    const skillExplicit = parsed.workflow && parsed.workflow.enforce_pbr_skills;
+    if (agentExplicit === 'advisory' || agentExplicit === 'block' || agentExplicit === 'off') {
+      agentLevel = agentExplicit;
+    } else if (skillExplicit === 'advisory' || skillExplicit === 'block' || skillExplicit === 'off') {
+      agentLevel = skillExplicit;
+    }
+  } catch (_e) {
+    // No config — keep default (block)
+  }
+
+  if (agentLevel === 'off') return null;
+
+  const suggestion = AGENT_MAPPING[subagentType] || 'a pbr:* agent (e.g., pbr:researcher, pbr:general, pbr:executor)';
+
+  // Block non-PBR agents unless explicitly set to advisory
+  if (agentLevel !== 'advisory') {
+    const blockMessage =
+      `PBR workflow violation: spawning generic agent "${subagentType}" is blocked. ` +
+      `Use ${suggestion} instead. ` +
+      'PBR agents are auto-loaded via subagent_type — just change the type, no extra setup needed. ' +
+      'If the user explicitly requested a native agent, add [native] to the Task description to bypass this check.';
+
+    logHook('enforce-pbr-workflow', 'PreToolUse', 'block', { agentType: subagentType, suggestion });
+    return {
+      exitCode: 2,
+      output: { decision: 'block', reason: '[pbr] ' + blockMessage }
+    };
+  }
+
+  // advisory (default)
+  const message =
+    `PBR workflow advisory: spawning generic agent "${subagentType}" without PBR routing. ` +
+    `Use ${suggestion} instead to maintain audit logging and workflow context. ` +
+    'PBR agents are auto-loaded via subagent_type — no extra setup needed.';
+
+  logHook('enforce-pbr-workflow', 'PreToolUse', 'advisory', { agentType: subagentType, suggestion });
+  return {
+    exitCode: 0,
+    output: { additionalContext: '[pbr] ' + message }
+  };
+}
+
+/**
+ * PreToolUse Bash: advises using /pbr:quick when git commit is run without
+ * an active PBR skill.
+ *
+ * Skip conditions:
+ *   - No .planning/ directory (not a PBR project)
+ *   - .planning/.active-skill exists (PBR skill is managing the session)
+ *   - Command is not a git commit
+ *   - Enforcement level is "off"
+ *
+ * @param {Object} data - parsed hook input from Claude Code
+ * @returns {null|{ exitCode: 0, output: Object }}
+ */
+function checkUnmanagedCommit(data) {
+  const command = data.tool_input && data.tool_input.command;
+  if (!command || typeof command !== 'string') return null;
+
+  // Only check git commit commands
+  if (!/\bgit\s+commit\b/.test(command)) return null;
+
+  const cwd = process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+
+  // Skip if not a PBR project
+  if (!fs.existsSync(planningDir)) return null;
+
+  // Skip if a PBR skill is active — session-scoped when session_id available
+  const { sessionLoad } = require('../plan-build-run/bin/lib/core.cjs');
+  const sessionIdCommit = data.session_id || null;
+  let activeSkillCommit = sessionLoad(planningDir, sessionIdCommit).activeSkill || '';
+  if (!activeSkillCommit) {
+    const skillPath = sessionIdCommit
+      ? resolveSessionPath(planningDir, '.active-skill', sessionIdCommit)
+      : path.join(planningDir, '.active-skill');
+    try { activeSkillCommit = fs.readFileSync(skillPath, 'utf8').trim(); } catch (_) { /* file missing */ }
+  }
+  if (activeSkillCommit) return null;
+
+  const config = loadEnforcementConfig(planningDir);
+  if (config.level === 'off') return null;
+
+  const message =
+    'Committing without PBR tracking. Use /pbr:quick to track this work. ' +
+    'PBR quick tasks create atomic commits with proper scope and audit trail.';
+
+  logHook('enforce-pbr-workflow', 'PreToolUse', 'advisory', { check: 'unmanaged-commit' });
+  return {
+    exitCode: 0,
+    output: { additionalContext: '[pbr] ' + message }
+  };
+}
+
+module.exports = {
+  loadEnforcementConfig,
+  checkUnmanagedSourceWrite,
+  checkNonPbrAgent,
+  checkUnmanagedCommit
+};