@sienklogic/plan-build-run 2.0.0

package/plugins/pbr/scripts/track-context-budget.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+
+/**
+ * PostToolUse hook on Read: Tracks cumulative file reads per skill invocation.
+ *
+ * Maintains a session-scoped counter in .planning/.context-tracker.
+ * Warns when reads exceed thresholds (15 reads or 30k chars).
+ * Resets when .active-skill changes (new skill invocation).
+ *
+ * Exit codes:
+ *   0 = always (PostToolUse hook, advisory only)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+
+const READ_THRESHOLD = 20;
+const CHAR_THRESHOLD = 30000;
+
+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 = JSON.parse(input);
+      const filePath = data.tool_input?.file_path || '';
+      if (!filePath) {
+        process.exit(0);
+      }
+
+      // Estimate chars read (use limit if provided, otherwise assume ~2000 lines × 40 chars avg)
+      const limit = data.tool_input?.limit;
+      const estimatedChars = limit ? limit * 40 : 80000;
+      // Use actual output length if available
+      const actualChars = data.tool_output ? String(data.tool_output).length : estimatedChars;
+
+      const trackerPath = path.join(planningDir, '.context-tracker');
+      const skillPath = path.join(planningDir, '.active-skill');
+
+      // Check if active skill changed (reset tracker)
+      const currentSkill = readFileSafe(skillPath);
+      let tracker = loadTracker(trackerPath);
+
+      if (tracker.skill !== currentSkill) {
+        tracker = { skill: currentSkill, reads: 0, total_chars: 0, files: [] };
+      }
+
+      // Update tracker
+      tracker.reads += 1;
+      tracker.total_chars += actualChars;
+      if (!tracker.files.includes(filePath)) {
+        tracker.files.push(filePath);
+      }
+
+      // Save tracker
+      try {
+        fs.writeFileSync(trackerPath, JSON.stringify(tracker), 'utf8');
+      } catch (_e) {
+        // Best-effort
+      }
+
+      // Check thresholds
+      if (tracker.reads >= READ_THRESHOLD || tracker.total_chars >= CHAR_THRESHOLD) {
+        const warnings = [];
+        if (tracker.reads >= READ_THRESHOLD) {
+          warnings.push(`${tracker.reads} file reads (threshold: ${READ_THRESHOLD})`);
+        }
+        if (tracker.total_chars >= CHAR_THRESHOLD) {
+          const kChars = Math.round(tracker.total_chars / 1000);
+          warnings.push(`~${kChars}k chars read (threshold: ${CHAR_THRESHOLD / 1000}k)`);
+        }
+
+        logHook('track-context-budget', 'PostToolUse', 'warn', {
+          reads: tracker.reads,
+          total_chars: tracker.total_chars,
+          unique_files: tracker.files.length,
+        });
+
+        const output = {
+          additionalContext: `[Context Budget Warning] ${warnings.join(', ')}. ${tracker.files.length} unique files read. Consider delegating remaining reads to a Task() subagent to protect orchestrator context.`
+        };
+        process.stdout.write(JSON.stringify(output));
+      }
+
+      process.exit(0);
+    } catch (_e) {
+      // Never block on tracking errors
+      process.exit(0);
+    }
+  });
+}
+
+function readFileSafe(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf8').trim();
+  } catch (_e) {
+    return '';
+  }
+}
+
+function loadTracker(trackerPath) {
+  try {
+    const content = fs.readFileSync(trackerPath, 'utf8');
+    return JSON.parse(content);
+  } catch (_e) {
+    return { skill: '', reads: 0, total_chars: 0, files: [] };
+  }
+}
+
+main();

package/plugins/pbr/scripts/validate-commit.js

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+
+/**
+ * PreToolUse hook: Validates git commit message format.
+ *
+ * Expected format: {type}({phase}-{plan}): {description}
+ * Valid types: feat, fix, refactor, test, docs, chore
+ *
+ * Also accepts:
+ * - Merge commits (starts with "Merge")
+ * - Quick task commits: {type}(quick-{NNN}): {description}
+ * - Planning doc commits: docs(planning): {description}
+ * - WIP commits: wip: {description} or wip({area}): {description}
+ *
+ * Exit codes:
+ *   0 = not a commit command or valid format
+ *   2 = invalid commit message format (blocks the tool)
+ */
+
+const path = require('path');
+const { execSync } = require('child_process');
+const { logHook } = require('./hook-logger');
+const { logEvent } = require('./event-logger');
+
+const VALID_TYPES = ['feat', 'fix', 'refactor', 'test', 'docs', 'chore', 'wip'];
+
+const SENSITIVE_PATTERNS = [
+  /^\.env$/,                          // .env exactly (not .env.example)
+  /\.env\.[^.]+$/,                    // .env.production, .env.local etc (but not .env.example)
+  /\.key$/i,
+  /\.pem$/i,
+  /\.pfx$/i,
+  /\.p12$/i,
+  /credential/i,
+  /secret/i,
+];
+
+const SAFE_PATTERNS = [
+  /\.example$/i,
+  /\.template$/i,
+  /\.sample$/i,
+  /^tests?[\\/]/i,
+];
+
+// Pattern: type(scope): description
+// Scope can be: NN-MM (phase-plan), quick-NNN, planning, or any word
+const COMMIT_PATTERN = /^(feat|fix|refactor|test|docs|chore|wip)(\([a-zA-Z0-9._-]+\))?:\s+.+/;
+
+// Merge commits are always allowed
+const MERGE_PATTERN = /^Merge\s/;
+
+// AI co-author patterns to block
+const AI_COAUTHOR_PATTERN = /Co-Authored-By:.*(?:Claude|Anthropic|noreply@anthropic\.com|OpenAI|Copilot|GPT|AI Assistant)/i;
+
+function checkAiCoAuthorResult(command) {
+  if (AI_COAUTHOR_PATTERN.test(command)) {
+    logHook('validate-commit', 'PreToolUse', 'block-coauthor', { command: command.substring(0, 200) });
+    return {
+      output: {
+        decision: 'block',
+        reason: 'Commit blocked: contains AI co-author attribution.\n\nPlan-Build-Run commits must not include Co-Authored-By lines referencing AI tools (Claude, Copilot, GPT, etc.).\n\nRemove the Co-Authored-By line and try again.'
+      },
+      exitCode: 2
+    };
+  }
+  return null;
+}
+
+function checkSensitiveFilesResult() {
+  try {
+    const output = execSync('git diff --cached --name-only', { encoding: 'utf8' });
+    const files = output.trim().split('\n').filter(Boolean);
+
+    const matched = files.filter((file) => {
+      // Skip files matching safe patterns
+      if (SAFE_PATTERNS.some((pattern) => pattern.test(file))) return false;
+      // Check against sensitive patterns (test basename and full path)
+      const basename = path.basename(file);
+      return SENSITIVE_PATTERNS.some((pattern) => pattern.test(basename) || pattern.test(file));
+    });
+
+    if (matched.length > 0) {
+      logHook('validate-commit', 'PreToolUse', 'block-sensitive', { files: matched });
+      return {
+        output: {
+          decision: 'block',
+          reason: `Commit blocked: staged files may contain sensitive data.\n\nFiles: ${matched.join(', ')}\n\nRemove these files from staging with:\n  git reset HEAD ${matched.join(' ')}\n\nIf these files are intentionally safe (e.g., test fixtures), rename them to include .example, .template, or .sample.`
+        },
+        exitCode: 2
+      };
+    }
+  } catch (_e) {
+    // Not in a git repo or git not available - silently continue
+  }
+  return null;
+}
+
+/**
+ * Check a parsed hook data object for commit validation issues.
+ * Returns { output, exitCode } if the command should be blocked, or null if allowed.
+ * Used by pre-bash-dispatch.js for consolidated hook execution.
+ */
+function checkCommit(data) {
+  const command = data.tool_input?.command || '';
+
+  // Only validate git commit commands
+  if (!isGitCommit(command)) {
+    return null;
+  }
+
+  // Extract the commit message
+  const message = extractCommitMessage(command);
+  if (!message) {
+    // Could not parse message - let it through (might be --amend or other form)
+    logHook('validate-commit', 'PreToolUse', 'allow', { reason: 'unparseable message' });
+    return null;
+  }
+
+  // Validate format
+  if (MERGE_PATTERN.test(message)) {
+    logHook('validate-commit', 'PreToolUse', 'allow', { message, reason: 'merge commit' });
+    return null;
+  }
+
+  if (!COMMIT_PATTERN.test(message)) {
+    logHook('validate-commit', 'PreToolUse', 'block', { message });
+    logEvent('workflow', 'commit-validated', { message: message.substring(0, 80), status: 'block' });
+    return {
+      output: {
+        decision: 'block',
+        reason: `Invalid commit message format.\n\nExpected: {type}({scope}): {description}\nTypes: ${VALID_TYPES.join(', ')}\nExamples:\n  feat(03-01): add user authentication\n  fix(02-02): resolve database connection timeout\n  docs(planning): update roadmap with phase 4\n  wip: save progress on auth middleware\n\nGot: "${message}"`
+      },
+      exitCode: 2
+    };
+  }
+
+  // Valid format
+  logHook('validate-commit', 'PreToolUse', 'allow', { message });
+  logEvent('workflow', 'commit-validated', { message: message.substring(0, 80), status: 'allow' });
+
+  // Check AI co-author
+  const coAuthorResult = checkAiCoAuthorResult(command);
+  if (coAuthorResult) return coAuthorResult;
+
+  // Check sensitive files
+  const sensitiveResult = checkSensitiveFilesResult();
+  if (sensitiveResult) return sensitiveResult;
+
+  return null;
+}
+
+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 = checkCommit(data);
+      if (result) {
+        process.stdout.write(JSON.stringify(result.output));
+        process.exit(result.exitCode);
+      }
+      process.exit(0);
+    } catch (_e) {
+      // Parse error - don't block
+      process.exit(0);
+    }
+  });
+}
+
+function isGitCommit(command) {
+  // Match: git commit anywhere in the command string
+  // Handles chained commands like "cd /dir && git commit ..." or "git add . && git commit ..."
+  const trimmed = command.trim();
+  return /\bgit\s+commit\b/.test(trimmed) && !trimmed.includes('--amend --no-edit');
+}
+
+function extractCommitMessage(command) {
+  // Try -m "message" or -m 'message'
+  const mFlagMatch = command.match(/-m\s+["']([^"']+)["']/);
+  if (mFlagMatch) return mFlagMatch[1];
+
+  // Try -m "message" with escaped quotes
+  const mFlagMatch2 = command.match(/-m\s+"([^"]+)"/);
+  if (mFlagMatch2) return mFlagMatch2[1];
+
+  // Try heredoc: -m "$(cat <<'EOF'\n...\nEOF\n)"
+  const heredocMatch = command.match(/<<'?EOF'?\s*\n([\s\S]*?)\nEOF/);
+  if (heredocMatch) {
+    // First line of heredoc is the commit message
+    return heredocMatch[1].trim().split('\n')[0].trim();
+  }
+
+  return null;
+}
+
+module.exports = { checkCommit };
+if (require.main === module) { main(); }

package/plugins/pbr/scripts/validate-plugin-structure.js

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+
+/**
+ * Validates the Plan-Build-Run plugin structure:
+ * - Every skill directory has SKILL.md
+ * - Every agent file has valid YAML frontmatter (name, description)
+ * - hooks.json references existing scripts
+ * - No broken relative links in markdown files
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..');
+let errors = 0;
+let warnings = 0;
+
+function error(msg) {
+  console.error(`ERROR: ${msg}`);
+  errors++;
+}
+
+function warn(msg) {
+  console.warn(`WARN: ${msg}`);
+  warnings++;
+}
+
+function info(msg) {
+  console.log(`OK: ${msg}`);
+}
+
+// 1. Check plugin.json exists
+const pluginJsonPath = path.join(ROOT, '.claude-plugin', 'plugin.json');
+if (!fs.existsSync(pluginJsonPath)) {
+  error('.claude-plugin/plugin.json missing');
+} else {
+  try {
+    const plugin = JSON.parse(fs.readFileSync(pluginJsonPath, 'utf8'));
+    if (!plugin.name) error('plugin.json missing "name" field');
+    if (!plugin.version) error('plugin.json missing "version" field');
+    if (!plugin.description) error('plugin.json missing "description" field');
+    info(`Plugin: ${plugin.name} v${plugin.version}`);
+  } catch (e) {
+    error(`plugin.json is not valid JSON: ${e.message}`);
+  }
+}
+
+// 2. Check every skill directory has SKILL.md
+const skillsDir = path.join(ROOT, 'skills');
+if (fs.existsSync(skillsDir)) {
+  const skillDirs = fs.readdirSync(skillsDir, { withFileTypes: true })
+    .filter(d => d.isDirectory() && d.name !== 'shared');
+
+  for (const dir of skillDirs) {
+    const skillMd = path.join(skillsDir, dir.name, 'SKILL.md');
+    if (!fs.existsSync(skillMd)) {
+      error(`skills/${dir.name}/ missing SKILL.md`);
+    } else {
+      const content = fs.readFileSync(skillMd, 'utf8');
+      if (!content.startsWith('---')) {
+        error(`skills/${dir.name}/SKILL.md missing YAML frontmatter`);
+      } else {
+        const frontmatter = content.split('---')[1];
+        if (!frontmatter.includes('name:')) {
+          error(`skills/${dir.name}/SKILL.md frontmatter missing "name" field`);
+        }
+        if (!frontmatter.includes('description:')) {
+          error(`skills/${dir.name}/SKILL.md frontmatter missing "description" field`);
+        }
+      }
+      // Check: skills with Task in allowed-tools must have Context Budget section
+      const frontmatterBlock = content.split('---')[1] || '';
+      const hasTaskTool = /allowed-tools:.*Task/.test(frontmatterBlock);
+      if (hasTaskTool && !content.includes('## Context Budget')) {
+        warn(`skills/${dir.name}/SKILL.md has Task in allowed-tools but no "## Context Budget" section`);
+      }
+
+      info(`Skill: /pbr:${dir.name}`);
+    }
+  }
+} else {
+  error('skills/ directory missing');
+}
+
+// 3. Check every agent file has valid frontmatter
+const agentsDir = path.join(ROOT, 'agents');
+if (fs.existsSync(agentsDir)) {
+  const agentFiles = fs.readdirSync(agentsDir)
+    .filter(f => f.endsWith('.md'));
+
+  for (const file of agentFiles) {
+    const content = fs.readFileSync(path.join(agentsDir, file), 'utf8');
+    if (!content.startsWith('---')) {
+      error(`agents/${file} missing YAML frontmatter`);
+    } else {
+      const frontmatter = content.split('---')[1];
+      if (!frontmatter.includes('name:')) {
+        error(`agents/${file} frontmatter missing "name" field`);
+      }
+      if (!frontmatter.includes('description:')) {
+        error(`agents/${file} frontmatter missing "description" field`);
+      }
+      const nameMatch = frontmatter.match(/name:\s*(.+)/);
+      info(`Agent: ${nameMatch ? nameMatch[1].trim() : file}`);
+    }
+  }
+} else {
+  error('agents/ directory missing');
+}
+
+// 4. Check context files have valid structure
+const contextsDir = path.join(ROOT, 'contexts');
+if (fs.existsSync(contextsDir)) {
+  const contextFiles = fs.readdirSync(contextsDir)
+    .filter(f => f.endsWith('.md'));
+
+  for (const file of contextFiles) {
+    const content = fs.readFileSync(path.join(contextsDir, file), 'utf8');
+    if (!content.startsWith('#')) {
+      warn(`contexts/${file} should start with a heading`);
+    }
+    const name = file.replace('.md', '');
+    info(`Context: ${name}`);
+  }
+} else {
+  warn('contexts/ directory not found (contexts are optional)');
+}
+
+// 5. Check hooks.json references existing scripts
+const hooksJsonPath = path.join(ROOT, 'hooks', 'hooks.json');
+if (fs.existsSync(hooksJsonPath)) {
+  try {
+    const hooksFile = JSON.parse(fs.readFileSync(hooksJsonPath, 'utf8'));
+
+    // Plugin hooks format: { hooks: { EventName: [ { matcher?, hooks: [ { type, command } ] } ] } }
+    const hooksObj = hooksFile.hooks || {};
+    for (const eventName of Object.keys(hooksObj)) {
+      const matcherGroups = hooksObj[eventName];
+      if (!Array.isArray(matcherGroups)) continue;
+      for (const group of matcherGroups) {
+        const handlers = group.hooks || [];
+        for (const handler of handlers) {
+          if (handler.command) {
+            const cmd = handler.command.replace(/\$\{CLAUDE_PLUGIN_ROOT\}/g, ROOT);
+            const parts = cmd.split(' ');
+            const scriptPart = parts.find(p => p.endsWith('.js'));
+            if (scriptPart) {
+              const scriptPath = scriptPart.replace(/\$\{CLAUDE_PLUGIN_ROOT\}/g, ROOT);
+              const resolvedPath = path.isAbsolute(scriptPath) ? scriptPath : path.join(ROOT, scriptPath);
+              if (!fs.existsSync(resolvedPath)) {
+                error(`hooks.json references missing script: ${scriptPart}`);
+              }
+            }
+          }
+        }
+      }
+    }
+    info('hooks.json validated');
+  } catch (e) {
+    error(`hooks.json is not valid JSON: ${e.message}`);
+  }
+} else {
+  warn('hooks/hooks.json not found (hooks are optional)');
+}
+
+// 6. Summary
+console.log('\n---');
+console.log(`Validation complete: ${errors} errors, ${warnings} warnings`);
+
+if (errors > 0) {
+  process.exit(1);
+}