@sienklogic/plan-build-run 2.0.0

package/plugins/pbr/scripts/event-logger.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+
+/**
+ * Workflow event logger for Plan-Build-Run observability.
+ *
+ * Usage as module:
+ *   const { logEvent } = require('./event-logger');
+ *   logEvent('workflow', 'phase-start', { phase: 3, name: 'API' });
+ *
+ * Usage as CLI:
+ *   node event-logger.js <category> <event> [JSON-details]
+ *
+ * Log file: .planning/logs/events.jsonl
+ * Format: One JSON line per entry (JSONL)
+ * Rotation: Keeps last 1000 entries max
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const MAX_ENTRIES = 1000;
+
+function getLogPath() {
+  const cwd = process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+  if (!fs.existsSync(planningDir)) return null;
+  const logsDir = path.join(planningDir, 'logs');
+  if (!fs.existsSync(logsDir)) {
+    fs.mkdirSync(logsDir, { recursive: true });
+  }
+  return path.join(logsDir, 'events.jsonl');
+}
+
+function logEvent(category, event, details = {}) {
+  const logPath = getLogPath();
+  if (!logPath) return;
+
+  const entry = {
+    ts: new Date().toISOString(),
+    cat: category,
+    event,
+    ...details
+  };
+
+  try {
+    let lines = [];
+    if (fs.existsSync(logPath)) {
+      const content = fs.readFileSync(logPath, 'utf8').trim();
+      if (content) {
+        lines = content.split('\n');
+      }
+    }
+
+    lines.push(JSON.stringify(entry));
+
+    if (lines.length > MAX_ENTRIES) {
+      lines = lines.slice(lines.length - MAX_ENTRIES);
+    }
+
+    fs.writeFileSync(logPath, lines.join('\n') + '\n', 'utf8');
+  } catch (_e) {
+    // Best-effort logging — never fail the caller
+  }
+}
+
+// CLI mode
+function main() {
+  const args = process.argv.slice(2);
+  const category = args[0];
+  const event = args[1];
+  let details = {};
+
+  if (args[2]) {
+    try {
+      details = JSON.parse(args[2]);
+    } catch (_e) {
+      details = { raw: args[2] };
+    }
+  }
+
+  if (!category || !event) {
+    process.stdout.write(JSON.stringify({ error: 'Usage: event-logger.js <category> <event> [JSON-details]' }));
+    process.exit(1);
+  }
+
+  logEvent(category, event, details);
+  process.stdout.write(JSON.stringify({ logged: true, category, event }));
+  process.exit(0);
+}
+
+if (require.main === module) { main(); }
+module.exports = { logEvent };

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

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+
+/**
+ * Shared hook execution logger.
+ *
+ * Usage in hooks:
+ *   const { logHook } = require('./hook-logger');
+ *   logHook('validate-commit', 'PreToolUse', 'allow', { message: 'chore: ...' });
+ *
+ * Log file: .planning/logs/hooks.jsonl (in the project's .planning directory)
+ * Format: One JSON line per entry (JSONL)
+ * Rotation: Keeps last 200 entries max
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const MAX_ENTRIES = 200;
+
+function getLogPath() {
+  const cwd = process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+  if (!fs.existsSync(planningDir)) return null;
+
+  const logsDir = path.join(planningDir, 'logs');
+  const newPath = path.join(logsDir, 'hooks.jsonl');
+  const oldPath = path.join(planningDir, '.hook-log');
+
+  // Auto-create logs/ directory if it doesn't exist
+  if (!fs.existsSync(logsDir)) {
+    fs.mkdirSync(logsDir, { recursive: true });
+  }
+
+  // One-time migration: move old .hook-log to new location
+  if (fs.existsSync(oldPath) && !fs.existsSync(newPath)) {
+    fs.renameSync(oldPath, newPath);
+  }
+
+  return newPath;
+}
+
+function logHook(hookName, eventType, decision, details = {}) {
+  const logPath = getLogPath();
+  if (!logPath) return; // Not a Plan-Build-Run project
+
+  const entry = {
+    ts: new Date().toISOString(),
+    hook: hookName,
+    event: eventType,
+    decision,
+    ...details
+  };
+
+  try {
+    let lines = [];
+    if (fs.existsSync(logPath)) {
+      const content = fs.readFileSync(logPath, 'utf8').trim();
+      if (content) {
+        lines = content.split('\n');
+      }
+    }
+
+    lines.push(JSON.stringify(entry));
+
+    // Keep only last MAX_ENTRIES
+    if (lines.length > MAX_ENTRIES) {
+      lines = lines.slice(lines.length - MAX_ENTRIES);
+    }
+
+    fs.writeFileSync(logPath, lines.join('\n') + '\n', 'utf8');
+  } catch (_e) {
+    // Best-effort logging — never fail the hook
+  }
+}
+
+module.exports = { logHook };

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

@@ -0,0 +1,79 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Plan-Build-Run Hooks",
+  "description": "Schema for Claude Code hooks.json configuration",
+  "type": "object",
+  "properties": {
+    "$schema": { "type": "string" },
+    "description": { "type": "string" },
+    "hooks": {
+      "type": "object",
+      "properties": {
+        "SessionStart": { "$ref": "#/definitions/hookEntryList" },
+        "PreToolUse": { "$ref": "#/definitions/hookEntryList" },
+        "PostToolUse": { "$ref": "#/definitions/hookEntryList" },
+        "PostToolUseFailure": { "$ref": "#/definitions/hookEntryList" },
+        "PreCompact": { "$ref": "#/definitions/hookEntryList" },
+        "Stop": { "$ref": "#/definitions/hookEntryList" },
+        "SubagentStart": { "$ref": "#/definitions/hookEntryList" },
+        "SubagentStop": { "$ref": "#/definitions/hookEntryList" },
+        "TaskCompleted": { "$ref": "#/definitions/hookEntryList" },
+        "SessionEnd": { "$ref": "#/definitions/hookEntryList" }
+      },
+      "additionalProperties": false
+    }
+  },
+  "required": ["hooks"],
+  "additionalProperties": true,
+  "definitions": {
+    "hookEntryList": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/hookEntry" }
+    },
+    "hookEntry": {
+      "type": "object",
+      "properties": {
+        "matcher": {
+          "type": "string",
+          "description": "Regex tested against the tool name (e.g. 'Write|Edit', 'Bash', 'Task')"
+        },
+        "hooks": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/hookCommand" }
+        }
+      },
+      "required": ["hooks"],
+      "additionalProperties": false
+    },
+    "hookCommand": {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["command"],
+          "description": "Hook type — currently only 'command' is supported"
+        },
+        "command": {
+          "type": "string",
+          "description": "Shell command to execute (use ${CLAUDE_PLUGIN_ROOT} for script paths)"
+        },
+        "statusMessage": {
+          "type": "string",
+          "description": "Status message shown in Claude Code UI while hook runs"
+        },
+        "async": {
+          "type": "boolean",
+          "description": "Run in background without blocking (stdout not captured)",
+          "default": false
+        },
+        "timeout": {
+          "type": "number",
+          "minimum": 1,
+          "description": "Maximum seconds before hook is killed (required when async: true)"
+        }
+      },
+      "required": ["type", "command"],
+      "additionalProperties": false
+    }
+  }
+}

package/plugins/pbr/scripts/log-subagent.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+
+/**
+ * SubagentStart / SubagentStop logging hook.
+ *
+ * Usage:
+ *   node log-subagent.js start   — called on SubagentStart
+ *   node log-subagent.js stop    — called on SubagentStop
+ *
+ * On start: logs spawn event and injects project context via additionalContext.
+ * On stop: logs completion event.
+ *
+ * Non-blocking — exits 0 always.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+const { logEvent } = require('./event-logger');
+const { configLoad } = require('./pbr-tools');
+
+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 action = process.argv[2]; // 'start' or 'stop'
+  const data = readStdin();
+
+  if (action === 'start') {
+    logHook('log-subagent', 'SubagentStart', 'spawned', {
+      agent_id: data.agent_id || null,
+      agent_type: data.agent_type || data.subagent_type || null,
+      description: data.description || null
+    });
+    logEvent('agent', 'spawn', {
+      agent_id: data.agent_id || null,
+      agent_type: data.agent_type || data.subagent_type || null,
+      description: data.description || null
+    });
+
+    // Write .active-agent signal so other hooks know a subagent is running
+    writeActiveAgent(data.agent_type || data.subagent_type || 'unknown');
+
+    // Inject project context into subagent
+    const context = buildAgentContext();
+    if (context) {
+      const output = {
+        hookSpecificOutput: {
+          hookEventName: 'SubagentStart',
+          additionalContext: context
+        }
+      };
+      process.stdout.write(JSON.stringify(output));
+    }
+  } else if (action === 'stop') {
+    // Remove .active-agent signal
+    removeActiveAgent();
+    logHook('log-subagent', 'SubagentStop', 'completed', {
+      agent_id: data.agent_id || null,
+      agent_type: data.agent_type || data.subagent_type || null,
+      duration_ms: data.duration_ms || null
+    });
+    logEvent('agent', 'complete', {
+      agent_id: data.agent_id || null,
+      agent_type: data.agent_type || data.subagent_type || null,
+      duration_ms: data.duration_ms || null
+    });
+  }
+
+  process.exit(0);
+}
+
+function writeActiveAgent(agentType) {
+  try {
+    const cwd = process.cwd();
+    const filePath = path.join(cwd, '.planning', '.active-agent');
+    if (fs.existsSync(path.join(cwd, '.planning'))) {
+      fs.writeFileSync(filePath, agentType, 'utf8');
+    }
+  } catch (_e) {
+    // Best-effort
+  }
+}
+
+function removeActiveAgent() {
+  try {
+    const cwd = process.cwd();
+    const filePath = path.join(cwd, '.planning', '.active-agent');
+    if (fs.existsSync(filePath)) {
+      fs.unlinkSync(filePath);
+    }
+  } catch (_e) {
+    // Best-effort
+  }
+}
+
+function buildAgentContext() {
+  const cwd = process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+
+  if (!fs.existsSync(planningDir)) return '';
+
+  const parts = [];
+
+  // Current phase and status from STATE.md
+  const stateFile = path.join(planningDir, 'STATE.md');
+  if (fs.existsSync(stateFile)) {
+    try {
+      const state = fs.readFileSync(stateFile, 'utf8');
+      const phaseMatch = state.match(/Phase:\s*(\d+)\s+of\s+(\d+)/);
+      const statusMatch = state.match(/\*{0,2}(?:Phase\s+)?Status\*{0,2}:\s*["']?(\w+)["']?/i);
+      if (phaseMatch) {
+        parts.push(`Phase ${phaseMatch[1]} of ${phaseMatch[2]}${statusMatch ? ' (' + statusMatch[1] + ')' : ''}`);
+      }
+    } catch (_e) {
+      // skip
+    }
+  }
+
+  // Active skill context
+  const activeSkillFile = path.join(planningDir, '.active-skill');
+  if (fs.existsSync(activeSkillFile)) {
+    try {
+      const skill = fs.readFileSync(activeSkillFile, 'utf8').trim();
+      if (skill) parts.push(`Active skill: /pbr:${skill}`);
+    } catch (_e) {
+      // skip
+    }
+  }
+
+  // Config highlights
+  const config = configLoad(planningDir);
+  if (config) {
+    const configParts = [];
+    if (config.depth) configParts.push(`depth=${config.depth}`);
+    if (config.git && config.git.auto_commit !== undefined) configParts.push(`auto_commit=${config.git.auto_commit}`);
+    if (configParts.length > 0) parts.push(`Config: ${configParts.join(', ')}`);
+  }
+
+  if (parts.length === 0) return '';
+  return '[Plan-Build-Run Project Context] ' + parts.join(' | ');
+}
+
+module.exports = { buildAgentContext };
+if (require.main === module) { main(); }

package/plugins/pbr/scripts/log-tool-failure.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+
+/**
+ * PostToolUseFailure hook: Logs tool failures to events.jsonl
+ * and provides recovery hints via additionalContext.
+ *
+ * Fires when any tool execution fails. Captures tool name, error,
+ * and session context for debugging.
+ *
+ * Exit codes:
+ *   0 = always (informational hook, never blocks)
+ */
+
+const { logHook } = require('./hook-logger');
+const { logEvent } = require('./event-logger');
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let input = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { input += chunk; });
+    process.stdin.on('end', () => {
+      try {
+        resolve(JSON.parse(input));
+      } catch (_e) {
+        resolve({});
+      }
+    });
+  });
+}
+
+async function main() {
+  const data = await readStdin();
+
+  const toolName = data.tool_name || 'unknown';
+  const error = data.error || 'unknown error';
+  const isInterrupt = data.is_interrupt || false;
+  const toolInput = data.tool_input || {};
+
+  // Log to hooks.jsonl
+  logHook('log-tool-failure', 'PostToolUseFailure', 'logged', {
+    tool: toolName,
+    error: typeof error === 'string' ? error.substring(0, 200) : JSON.stringify(error).substring(0, 200),
+    interrupt: isInterrupt
+  });
+
+  // Log to events.jsonl with more detail
+  logEvent('tool', 'failure', {
+    tool: toolName,
+    error: typeof error === 'string' ? error.substring(0, 500) : JSON.stringify(error).substring(0, 500),
+    interrupt: isInterrupt,
+    input_summary: summarizeInput(toolName, toolInput)
+  });
+
+  // Provide recovery hints for Bash failures (most common actionable failure)
+  if (toolName === 'Bash' && !isInterrupt) {
+    const output = {
+      hookSpecificOutput: {
+        hookEventName: 'PostToolUseFailure',
+        additionalContext: 'Bash command failed. If this is a recurring issue, consider using /pbr:debug for systematic investigation.'
+      }
+    };
+    process.stdout.write(JSON.stringify(output));
+  }
+
+  process.exit(0);
+}
+
+function summarizeInput(toolName, toolInput) {
+  switch (toolName) {
+  case 'Bash':
+    return (toolInput.command || '').substring(0, 100);
+  case 'Write':
+  case 'Read':
+  case 'Edit':
+    return toolInput.file_path || '';
+  case 'Glob':
+    return toolInput.pattern || '';
+  case 'Grep':
+    return toolInput.pattern || '';
+  case 'Task':
+    return (toolInput.description || '').substring(0, 100);
+  default:
+    return '';
+  }
+}
+
+main();