@sienklogic/plan-build-run 2.1.0 → 2.1.1

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

@@ -4,10 +4,26 @@
   "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)" },
+    "session_phase_limit": { "type": "integer", "minimum": 0, "maximum": 20, "default": 3, "description": "Maximum phases to complete per session before suggesting a pause. 0 = disabled." },
+    "context_window_tokens": {
+      "type": "integer",
+      "minimum": 100000,
+      "maximum": 2000000,
+      "default": 200000,
+      "description": "Context window size in tokens for the active Claude model. Used to scale hook thresholds, agent checkpoint rules, and output budgets. Default 200000 matches Claude Sonnet/Haiku. Set to 1000000 for Claude models with 1M context."
+    },
+    "agent_checkpoint_pct": {
+      "type": "integer",
+      "minimum": 40,
+      "maximum": 80,
+      "default": 50,
+      "description": "Context usage percentage at which agents should checkpoint and return output. Default 50 matches standard 200k models. Set to 65 for 1M-context models where agents can safely work longer before compacting."
+    },
     "features": {
       "type": "object",
       "properties": {
@@ -51,6 +67,24 @@
       },
       "additionalProperties": false
     },
+    "model_profiles": {
+      "type": "object",
+      "description": "User-defined custom model profiles. Each key is a profile name; value is an object mapping agent names to model strings (sonnet, opus, haiku, inherit). Partial profiles allowed — omitted agents fall back to the active profile defaults.",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "researcher": { "type": "string" },
+          "planner": { "type": "string" },
+          "executor": { "type": "string" },
+          "verifier": { "type": "string" },
+          "integration_checker": { "type": "string" },
+          "debugger": { "type": "string" },
+          "mapper": { "type": "string" },
+          "synthesizer": { "type": "string" }
+        },
+        "additionalProperties": false
+      }
+    },
     "parallelization": {
       "type": "object",
       "properties": {
@@ -118,7 +152,12 @@
         "confirm_plan": { "type": "boolean" },
         "confirm_execute": { "type": "boolean" },
         "confirm_transition": { "type": "boolean" },
-        "issues_review": { "type": "boolean" }
+        "issues_review": { "type": "boolean" },
+        "confirm_research": { "type": "boolean" },
+        "confirm_seeds": { "type": "boolean" },
+        "confirm_deferred": { "type": "boolean" },
+        "confirm_commit_docs": { "type": "boolean" },
+        "auto_checkpoints": { "type": "boolean", "default": false, "description": "When true, executor auto-resolves checkpoint:human-verify tasks by running automated verify and approving if it passes. checkpoint:decision and checkpoint:human-action always require human input." }
       },
       "additionalProperties": false
     },
@@ -131,6 +170,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": {
@@ -142,6 +190,18 @@
       },
       "additionalProperties": false
     },
+    "prd": {
+      "type": "object",
+      "description": "Settings for PRD import via /pbr:import --prd.",
+      "properties": {
+        "auto_extract": {
+          "type": "boolean",
+          "default": false,
+          "description": "When true, skip the confirmation gate during PRD import and write files immediately. Default: false (confirm-first)."
+        }
+      },
+      "additionalProperties": false
+    },
     "depth_profiles": {
       "type": "object",
       "description": "Depth profile overrides. Each profile maps depth value to effective feature/gate settings.",
@@ -211,6 +271,14 @@
       },
       "additionalProperties": false
     },
+    "dashboard": {
+      "type": "object",
+      "properties": {
+        "auto_launch": { "type": "boolean" },
+        "port": { "type": "integer", "minimum": 1024, "maximum": 65535 }
+      },
+      "additionalProperties": false
+    },
     "status_line": {
       "type": "object",
       "properties": {
@@ -245,6 +313,93 @@
         }
       },
       "additionalProperties": false
+    },
+    "workflow": {
+      "type": "object",
+      "properties": {
+        "enforce_pbr_skills": {
+          "type": "string",
+          "enum": ["advisory", "block", "off"],
+          "default": "advisory",
+          "description": "Enforcement level for PBR workflow compliance"
+        }
+      },
+      "additionalProperties": false
+    },
+    "hook_server": {
+      "type": "object",
+      "description": "Persistent HTTP hook server settings. When enabled, hooks POST to the server instead of spawning per-hook processes.",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": false,
+          "description": "When true, hook-server-client.js routes hook events to the persistent hook-server.js process."
+        },
+        "port": {
+          "type": "integer",
+          "minimum": 1024,
+          "maximum": 65535,
+          "default": 19836,
+          "description": "TCP port the hook server listens on (127.0.0.1 only)."
+        },
+        "event_log": {
+          "type": "boolean",
+          "default": true,
+          "description": "When true, all hook events are appended to .planning/.hook-events.jsonl."
+        }
+      },
+      "additionalProperties": false
+    },
+    "local_llm": {
+      "type": "object",
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "provider": { "type": "string", "enum": ["ollama"] },
+        "endpoint": { "type": "string", "format": "uri" },
+        "model": { "type": "string" },
+        "timeout_ms": { "type": "integer", "minimum": 500 },
+        "max_retries": { "type": "integer", "minimum": 0, "maximum": 3 },
+        "fallback": { "type": "string", "enum": ["frontier", "skip"] },
+        "routing_strategy": { "type": "string", "enum": ["local_first", "frontier_first"] },
+        "features": {
+          "type": "object",
+          "properties": {
+            "artifact_classification": { "type": "boolean" },
+            "task_validation": { "type": "boolean" },
+            "plan_adequacy": { "type": "boolean" },
+            "gap_detection": { "type": "boolean" },
+            "context_summarization": { "type": "boolean" },
+            "source_scoring": { "type": "boolean" },
+            "commit_classification": { "type": "boolean" },
+            "test_triage": { "type": "boolean" },
+            "file_intent_classification": { "type": "boolean" }
+          },
+          "additionalProperties": false
+        },
+        "metrics": {
+          "type": "object",
+          "properties": {
+            "enabled": { "type": "boolean" },
+            "log_file": { "type": "string" },
+            "show_session_summary": { "type": "boolean" },
+            "frontier_token_rate": { "type": "number", "minimum": 0 }
+          },
+          "additionalProperties": false
+        },
+        "advanced": {
+          "type": "object",
+          "properties": {
+            "confidence_threshold": { "type": "number", "minimum": 0, "maximum": 1 },
+            "max_input_tokens": { "type": "integer", "minimum": 100 },
+            "keep_alive": { "type": "string" },
+            "num_ctx": { "type": "integer", "minimum": 512 },
+            "disable_after_failures": { "type": "integer", "minimum": 1 },
+            "shadow_mode": { "type": "boolean" }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
     }
   },
   "additionalProperties": false

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

@@ -0,0 +1,342 @@
+#!/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-85%) — recommend /pbr:pause-work
+ *   CRITICAL  (85%+)   — urgent stop, context rot imminent
+ *
+ * Debounce: same-tier warnings suppressed for 5 tool calls (2 for CRITICAL).
+ * 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: 85 },
+  { name: 'CRITICAL', min: 85, max: 100 }
+];
+
+const TIER_MESSAGES = {
+  DEGRADING: 'Context at ~50-70%. Delegate heavy reads and analysis to Task() subagents to preserve orchestrator quality.',
+  POOR: 'Context at ~70-85%. Run /pbr:pause-work soon to save state before quality degrades.',
+  CRITICAL: 'STOP — Context at 85%+. Run /pbr:pause-work NOW. Context rot is imminent — further work risks hallucinations and skipped steps.'
+};
+
+const DEBOUNCE_INTERVAL = 5; // tool calls between same-tier warnings
+const CRITICAL_DEBOUNCE_INTERVAL = 2; // shorter debounce for CRITICAL tier
+
+/**
+ * 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), '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 */ }
+  }
+}
+
+/**
+ * Get the char denominator for heuristic context estimation.
+ * Reads context_window_tokens from config (default 200k) and multiplies by 4 chars/token.
+ *
+ * @param {string} planningDir - Path to .planning/
+ * @returns {number} Total char capacity (context_window_tokens × 4, default 800000)
+ */
+function getCharDenominator(planningDir) {
+  try {
+    const { configLoad } = require('./pbr-tools');
+    const config = configLoad(planningDir);
+    const tokens = (config && config.context_window_tokens) || 200000;
+    return tokens * 4;
+  } catch (_e) {
+    return 800000; // 200k tokens × 4 chars/token
+  }
+}
+
+/**
+ * Estimate context percentage from heuristic tracker data.
+ * Uses the .context-tracker file written by track-context-budget.js.
+ * Assumes context_window_tokens × 4 chars (default 200k tokens = 800k chars, loaded from config).
+ *
+ * @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;
+    const percent = Math.min(100, Math.round((totalChars / getCharDenominator(planningDir)) * 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, CRITICAL: 4 };
+  if ((tierOrder[tierName] || 0) > (tierOrder[prevTier] || 0)) {
+    return true;
+  }
+
+  // Same tier — debounce (CRITICAL uses shorter interval)
+  const interval = tierName === 'CRITICAL' ? CRITICAL_DEBOUNCE_INTERVAL : DEBOUNCE_INTERVAL;
+  if (callsSinceWarn >= 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);
+      }
+
+      // For Write|Edit tools, also run suggest-compact check in-process
+      // (eliminates a separate Node process spawn per Write/Edit).
+      // Detect Write|Edit by presence of file_path in tool_input.
+      const toolInput = data.tool_input || {};
+      if (toolInput.file_path || toolInput.path) {
+        try {
+          const { checkCompaction } = require('./suggest-compact');
+          const compactResult = checkCompaction(planningDir, cwd);
+          if (compactResult) {
+            process.stdout.write(JSON.stringify(compactResult));
+          }
+        } catch (_e) { /* best-effort — never block on compact check */ }
+      }
+
+      process.exit(0);
+    } catch (_e) {
+      // Never block on tracking errors
+      process.exit(0);
+    }
+  });
+}
+
+/**
+ * HTTP handler for hook-server.js.
+ * Called directly instead of spawning a subprocess.
+ *
+ * @param {Object} reqBody - Full hook request body { event, tool, data, planningDir, cache }
+ * @param {Object} _cache - Server in-memory cache (unused by this handler)
+ * @returns {{ additionalContext: string }|null}
+ */
+function handleHttp(reqBody, _cache) {
+  try {
+    const planningDir = reqBody.planningDir;
+    const data = reqBody.data || {};
+    if (!planningDir || !fs.existsSync(planningDir)) {
+      return null;
+    }
+
+    const { output } = updateBridge(planningDir, data);
+
+    if (output) {
+      logHook('context-bridge', 'PostToolUse', 'warn', {
+        percent: output.additionalContext.match(/(\d+)%/)?.[1],
+        source: 'bridge'
+      });
+    }
+
+    // For Write|Edit tools, also run suggest-compact check in-process
+    const toolInput = data.tool_input || {};
+    if (!output && (toolInput.file_path || toolInput.path)) {
+      try {
+        const { checkCompaction } = require('./suggest-compact');
+        const compactResult = checkCompaction(planningDir, reqBody.planningDir ? reqBody.planningDir.replace(/[/\\]\.planning$/, '') : process.cwd());
+        if (compactResult) {
+          return compactResult;
+        }
+      } catch (_e) { /* best-effort — never block on compact check */ }
+    }
+
+    return output || null;
+  } catch (_e) {
+    return null;
+  }
+}
+
+module.exports = {
+  getTier,
+  loadBridge,
+  saveBridge,
+  getCharDenominator,
+  estimateFromHeuristic,
+  shouldWarn,
+  updateBridge,
+  handleHttp,
+  TIERS,
+  TIER_MESSAGES,
+  DEBOUNCE_INTERVAL,
+  CRITICAL_DEBOUNCE_INTERVAL
+};
+
+if (require.main === module || process.argv[1] === __filename) { main(); }