@sienklogic/plan-build-run 2.21.0 → 2.22.0

package/plugins/pbr/agents/planner.md

@@ -9,11 +9,12 @@ tools:
   - Bash
   - Glob
   - Grep
-  - WebFetch
 ---
 
 # Plan-Build-Run Planner
 
+> **Memory note:** Project memory is enabled to provide planning continuity and awareness of prior phase decisions.
+
 You are **planner**, the planning agent for the Plan-Build-Run development system. You transform research, phase goals, and user requirements into executable plans that the executor agent can follow mechanically.
 
 ## Core Principle: Context Fidelity

package/plugins/pbr/agents/researcher.md

@@ -60,6 +60,8 @@ All claims must be attributed to a source level. Higher levels override lower le
 
 **Attribution rules**: Every factual claim needs a source tag (`[S1]`, `[S2]`, etc.). Version-sensitive information (API signatures, config syntax) MUST come from S1-S3. When citing S2, note the version: `[S2-v14.2]`. Contradictions resolve in favor of higher source level.
 
+**Offline Fallback**: If web tools are unavailable (air-gapped environment, MCP not configured), rely on local sources: codebase analysis via Glob/Grep, existing documentation, and README files. Assign these S3-S4 confidence levels. Do not attempt WebFetch or WebSearch — note in the output header that external sources were unavailable.
+
 ---
 
 ## Confidence Levels

package/plugins/pbr/agents/synthesizer.md

@@ -6,7 +6,6 @@ memory: none
 tools:
   - Read
   - Write
-  - Bash
 ---
 
 # Plan-Build-Run Synthesizer

package/plugins/pbr/agents/verifier.md

@@ -222,7 +222,7 @@ Read `references/stub-patterns.md` for stub detection patterns by technology. Re
 
 ### Verifier-Specific Anti-Patterns
 1. DO NOT trust SUMMARY.md claims without verifying the actual codebase
-2. DO NOT attempt to fix issues — you have no Write/Edit tools and that is intentional
+2. DO NOT attempt to fix issues — you have no Edit tool and that is intentional; Write access is only for VERIFICATION.md output
 3. DO NOT mark stubs as SUBSTANTIVE — if it has a TODO, it's a stub
 4. DO NOT mark orphaned code as WIRED — if nothing imports it, it's orphaned
 5. DO NOT skip Level 2 or Level 3 checks — existence alone is insufficient

package/plugins/pbr/commands/do.md

@@ -0,0 +1,5 @@
+---
+description: "Route freeform text to the right PBR skill automatically."
+---
+
+This command is provided by the `pbr:do` skill.

package/plugins/pbr/hooks/hooks.json

@@ -77,6 +77,16 @@
       }
     ],
     "PreToolUse": [
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "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'))\" block-skill-self-read.js",
+            "statusMessage": "Checking skill self-read..."
+          }
+        ]
+      },
       {
         "matcher": "Bash",
         "hooks": [
@@ -87,6 +97,16 @@
           }
         ]
       },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "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'))\" check-cross-plugin-sync.js",
+            "statusMessage": "Checking cross-plugin sync..."
+          }
+        ]
+      },
       {
         "matcher": "Write|Edit",
         "hooks": [

package/plugins/pbr/scripts/auto-continue.js

@@ -63,6 +63,9 @@ function main() {
       } catch (_todoErr) {
         // Ignore errors scanning todos
       }
+      // Reset continue count on normal session stop (no signal)
+      const countPathNoSig = path.join(planningDir, '.continue-count');
+      try { fs.unlinkSync(countPathNoSig); } catch (_e) { /* ignore */ }
       logHook('auto-continue', 'Stop', 'no-signal', {});
       process.exit(0);
     }
@@ -97,19 +100,40 @@ function main() {
       process.exit(0);
     }
 
+    // Track consecutive continues for session length guard
+    const countPath = path.join(planningDir, '.continue-count');
+    let continueCount = 0;
+    try {
+      continueCount = parseInt(fs.readFileSync(countPath, 'utf8').trim(), 10) || 0;
+    } catch (_e) { /* file missing — start at 0 */ }
+    continueCount++;
+    try { fs.writeFileSync(countPath, String(continueCount)); } catch (_e) { /* ignore */ }
+
+    // Hard stop after 6 consecutive continues — context is likely degraded
+    if (continueCount > 6) {
+      logHook('auto-continue', 'Stop', 'hard-stop-session-length', { count: continueCount });
+      process.exit(0);
+    }
+
     // Extract last_assistant_message for richer continuation context
     const lastMsg = hookInput.last_assistant_message || '';
     const msgSuffix = lastMsg
       ? ` (last message excerpt: ${lastMsg.slice(0, 200)})`
       : '';
 
-    logHook('auto-continue', 'Stop', 'continue', { next: nextCommand, hasLastMsg: !!lastMsg });
+    logHook('auto-continue', 'Stop', 'continue', { next: nextCommand, hasLastMsg: !!lastMsg, continueCount });
+
+    // Build reason string with optional advisory
+    let reasonStr = `Auto-continue: execute ${nextCommand}${msgSuffix}`;
+    if (continueCount > 3) {
+      reasonStr += `\n\n[pbr] Advisory: ${continueCount} consecutive continues. Consider /pbr:pause + fresh session to avoid context degradation.`;
+    }
 
     // Block the stop and inject the next command as Claude's continuation reason.
     // Claude Code Stop hooks use { decision: "block", reason: "..." } to keep going.
     const output = {
       decision: 'block',
-      reason: `Auto-continue: execute ${nextCommand}${msgSuffix}`
+      reason: reasonStr
     };
     process.stdout.write(JSON.stringify(output));
     process.exit(0);

package/plugins/pbr/scripts/block-skill-self-read.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+
+/**
+ * PreToolUse Read hook: blocks skills from re-reading their own SKILL.md.
+ *
+ * Skills are already loaded into context by Claude Code — re-reading
+ * wastes ~13k tokens. This hook checks .planning/.active-skill to
+ * determine the current skill and blocks if the Read target matches.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+
+function main() {
+  try {
+    let hookInput = {};
+    try {
+      const stdin = fs.readFileSync(0, 'utf8').trim();
+      if (stdin) hookInput = JSON.parse(stdin);
+    } catch (_parseErr) {
+      // No stdin or invalid JSON
+    }
+
+    const cwd = hookInput.cwd || process.cwd();
+    const toolInput = hookInput.tool_input || {};
+    const filePath = toolInput.file_path || '';
+
+    if (!filePath) {
+      process.exit(0);
+    }
+
+    // Read .active-skill to get current skill name
+    const activeSkillPath = path.join(cwd, '.planning', '.active-skill');
+    let skillName = '';
+    try {
+      skillName = fs.readFileSync(activeSkillPath, 'utf8').trim();
+    } catch (_readErr) {
+      // No .active-skill file — nothing to block
+      process.exit(0);
+    }
+
+    if (!skillName) {
+      process.exit(0);
+    }
+
+    // Check if file_path ends with skills/{skill-name}/SKILL.md
+    const normalized = filePath.replace(/\\/g, '/');
+    const pattern = `skills/${skillName}/SKILL.md`.toLowerCase();
+    const match = normalized.toLowerCase().endsWith(pattern);
+
+    if (match) {
+      logHook('block-skill-self-read', 'PreToolUse', 'block', { skill: skillName, file: filePath });
+      const output = {
+        decision: 'block',
+        reason: `SKILL.md self-read blocked.\n\nThe active skill (${skillName}) attempted to read its own SKILL.md. Skills are already loaded into context by Claude Code \u2014 re-reading wastes ~13k tokens.\n\nNo action needed. The skill content is already available in your prompt.`
+      };
+      process.stdout.write(JSON.stringify(output));
+    } else {
+      logHook('block-skill-self-read', 'PreToolUse', 'allow', { skill: skillName, file: filePath });
+    }
+
+    process.exit(0);
+  } catch (_e) {
+    // Don't block on errors
+    process.exit(0);
+  }
+}
+
+main();

package/plugins/pbr/scripts/check-agent-state-write.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+
+/**
+ * PreToolUse hook: Blocks subagents (except pbr:general) from writing STATE.md.
+ *
+ * STATE.md is the source of truth for project position and should only be
+ * written by skills (orchestrators) or the general agent, never by specialized
+ * agents like executor, planner, or verifier.
+ *
+ * Detection: reads .planning/.active-agent (written by log-subagent.js).
+ *
+ * Exit codes:
+ *   0 = allowed or not applicable
+ *   2 = blocked (agent not allowed to write STATE.md)
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const BLOCKED_AGENTS = [
+  'pbr:executor',
+  'pbr:planner',
+  'pbr:verifier',
+  'pbr:researcher',
+  'pbr:plan-checker',
+  'pbr:integration-checker',
+  'pbr:debugger',
+  'pbr:codebase-mapper',
+  'pbr:synthesizer',
+  'pbr:audit',
+];
+
+function checkAgentStateWrite(data) {
+  const filePath = data.tool_input?.file_path || data.tool_input?.path || '';
+  if (!filePath) return null;
+
+  const normalized = filePath.replace(/\\/g, '/');
+  if (!normalized.endsWith('.planning/STATE.md')) return null;
+
+  // Check if we're inside a subagent
+  const cwd = process.cwd();
+  const agentFile = path.join(cwd, '.planning', '.active-agent');
+
+  let agent;
+  try {
+    agent = fs.readFileSync(agentFile, 'utf8').trim();
+  } catch (_e) {
+    // No .active-agent file — not in an agent context
+    return null;
+  }
+
+  if (!agent || !BLOCKED_AGENTS.includes(agent)) return null;
+
+  return {
+    exitCode: 2,
+    output: {
+      decision: 'block',
+      reason: `Agent write to STATE.md blocked.\n\n${agent} is not allowed to write STATE.md. Only skills (orchestrators) and pbr:general may update this file to prevent state corruption.\n\nReturn results to the calling skill and let it update STATE.md.`
+    }
+  };
+}
+
+module.exports = { checkAgentStateWrite, BLOCKED_AGENTS };

package/plugins/pbr/scripts/check-cross-plugin-sync.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+
+/**
+ * PreToolUse Bash hook: Advisory warning when committing pbr skill/agent
+ * changes without corresponding cursor-pbr/copilot-pbr counterparts.
+ *
+ * Only fires on `git commit` commands. Scripts directory is excluded
+ * because cursor-pbr and copilot-pbr share scripts via ../pbr/scripts/.
+ *
+ * Exit codes:
+ *   0 = always (advisory only, never blocks)
+ */
+
+const { execSync } = require('child_process');
+const { logHook } = require('./hook-logger');
+
+/**
+ * Check if a git commit has cross-plugin sync drift.
+ * @param {Object} data - Parsed hook input
+ * @returns {null|{additionalContext: string}} null if clean, advisory if drift
+ */
+function checkCrossPluginSync(data) {
+  const command = data.tool_input?.command || '';
+
+  // Only check git commit commands
+  if (!/\bgit\s+commit\b/.test(command)) {
+    return null;
+  }
+
+  let stagedFiles;
+  try {
+    stagedFiles = execSync('git diff --cached --name-only', { encoding: 'utf8' }).trim().split('\n').filter(Boolean);
+  } catch (_e) {
+    return null;
+  }
+
+  // Find pbr skill/agent files (not scripts — those are shared)
+  const pbrSyncFiles = stagedFiles.filter(f =>
+    /^plugins\/pbr\/(skills|agents)\//.test(f)
+  );
+
+  if (pbrSyncFiles.length === 0) {
+    return null;
+  }
+
+  // Check for missing counterparts
+  const missingCounterparts = [];
+  for (const pbrFile of pbrSyncFiles) {
+    const relativePath = pbrFile.replace(/^plugins\/pbr\//, '');
+    const cursorPath = `plugins/cursor-pbr/${relativePath}`;
+    const copilotPath = `plugins/copilot-pbr/${relativePath}`;
+
+    const hasCursor = stagedFiles.some(f => f === cursorPath);
+    const hasCopilot = stagedFiles.some(f => f === copilotPath);
+
+    if (!hasCursor || !hasCopilot) {
+      const missing = [];
+      if (!hasCursor) missing.push('cursor-pbr');
+      if (!hasCopilot) missing.push('copilot-pbr');
+      missingCounterparts.push(`${pbrFile} (missing: ${missing.join(', ')})`);
+    }
+  }
+
+  if (missingCounterparts.length === 0) {
+    return null;
+  }
+
+  const msg = `Advisory: Cross-plugin sync may be needed. Changed pbr files without cursor-pbr/copilot-pbr counterparts:\n${missingCounterparts.map(f => `  - ${f}`).join('\n')}`;
+  logHook('check-cross-plugin-sync', 'PreToolUse', 'warn', { missingCounterparts });
+
+  return { additionalContext: msg };
+}
+
+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 result = checkCrossPluginSync(data);
+      if (result) {
+        process.stdout.write(JSON.stringify(result));
+      }
+    } catch (_e) {
+      // Don't block on errors
+    }
+    process.exit(0);
+  });
+}
+
+module.exports = { checkCrossPluginSync };
+if (require.main === module || process.argv[1] === __filename) { main(); }

package/plugins/pbr/scripts/check-dangerous-commands.js

@@ -86,7 +86,7 @@ function checkDangerous(data) {
       return {
         output: {
           decision: 'block',
-          reason: `Dangerous command blocked.\n\n${reason}\n\nCommand: ${command.substring(0, 150)}`
+          reason: `Dangerous command blocked.\n\n${reason} Command: ${command.substring(0, 150)}\n\nUse a safer alternative or ask the user for explicit confirmation before running destructive commands.`
         },
         exitCode: 2
       };
@@ -146,7 +146,7 @@ function checkSkillSpecificBash(command) {
     return {
       output: {
         decision: 'block',
-        reason: 'CRITICAL: Use Read + Write tools for JSON files, not shell text manipulation. Shell tools can corrupt JSON structure.'
+        reason: 'JSON shell manipulation blocked.\n\nShell tools like sed, awk, and perl can corrupt JSON structure. The statusline skill must use structured tools for JSON editing.\n\nUse the Read and Write tools to modify JSON files instead of shell text manipulation.'
       },
       exitCode: 2
     };

package/plugins/pbr/scripts/check-phase-boundary.js

@@ -102,10 +102,7 @@ function main() {
         process.exit(2);
       } else {
         const output = {
-          hookSpecificOutput: {
-            hookEventName: 'PreToolUse',
-            additionalContext: `Warning: editing phase ${filePhase} file but current phase is ${currentPhase}. Ensure this cross-phase edit is intentional.`
-          }
+          additionalContext: `Warning: editing phase ${filePhase} file but current phase is ${currentPhase}. Ensure this cross-phase edit is intentional.`
         };
         process.stdout.write(JSON.stringify(output));
       }
@@ -184,10 +181,7 @@ function checkBoundary(data) {
   return {
     exitCode: 0,
     output: {
-      hookSpecificOutput: {
-        hookEventName: 'PreToolUse',
-        additionalContext: `Warning: editing phase ${filePhase} file but current phase is ${currentPhase}. Ensure this cross-phase edit is intentional.`
-      }
+      additionalContext: `Warning: editing phase ${filePhase} file but current phase is ${currentPhase}. Ensure this cross-phase edit is intentional.`
     }
   };
 }