@sienklogic/plan-build-run 2.0.2 → 2.1.1

package/hooks/dist/validate-commit.js

@@ -0,0 +1,265 @@
+#!/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 fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const { logHook } = require('./hook-logger');
+const { logEvent } = require('./event-logger');
+const { resolveConfig } = require('../plan-build-run/bin/lib/local-llm/health.cjs');
+const { classifyCommit } = require('../plan-build-run/bin/lib/local-llm/operations/classify-commit.cjs');
+
+const VALID_TYPES = ['feat', 'fix', 'refactor', 'test', 'docs', 'chore', 'wip', 'revert'];
+
+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|revert)(\([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;
+}
+
+/**
+ * Load and resolve the local_llm config block from .planning/config.json.
+ * Returns a resolved config (always safe to use — disabled by default on error).
+ */
+function loadLocalLlmConfig(cwd) {
+  try {
+    const configPath = path.join(cwd || process.cwd(), '.planning', 'config.json');
+    const parsed = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    return resolveConfig(parsed.local_llm);
+  } catch (_e) {
+    return resolveConfig(undefined);
+  }
+}
+
+/**
+ * Async LLM enrichment for commit messages. Returns an advisory string or null.
+ * Called after checkCommit passes (valid format) to provide semantic classification.
+ *
+ * @param {object} data - parsed hook data
+ * @returns {Promise<string|null>}
+ */
+async function enrichCommitLlm(data) {
+  try {
+    const command = data.tool_input?.command || '';
+    const message = extractCommitMessage(command);
+    if (!message) return null;
+
+    const cwd = process.cwd();
+    const llmConfig = loadLocalLlmConfig(cwd);
+    const planningDir = path.join(cwd, '.planning');
+
+    // Get staged files for scope validation
+    let stagedFiles = [];
+    try {
+      const output = execSync('git diff --cached --name-only', { encoding: 'utf8' });
+      stagedFiles = output.trim().split('\n').filter(Boolean);
+    } catch (_e) {
+      // Not in a git repo — skip staged files context
+    }
+
+    const llmResult = await classifyCommit(llmConfig, planningDir, message, stagedFiles, data.session_id);
+    if (llmResult && llmResult.classification !== 'correct') {
+      return 'LLM commit advisory: ' + llmResult.classification +
+        ' (confidence: ' + (llmResult.confidence * 100).toFixed(0) + '%)';
+    }
+    return null;
+  } catch (_llmErr) {
+    // Never propagate LLM errors
+    return null;
+  }
+}
+
+function main() {
+  let input = '';
+
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => { input += chunk; });
+  process.stdin.on('end', async () => {
+    try {
+      const data = JSON.parse(input);
+      const result = checkCommit(data);
+      if (result) {
+        process.stdout.write(JSON.stringify(result.output));
+        process.exit(result.exitCode);
+      }
+
+      // LLM semantic classification — advisory only (after format validation passes)
+      const llmAdvisory = await enrichCommitLlm(data);
+      if (llmAdvisory) {
+        process.stdout.write(JSON.stringify({
+          additionalContext: '[pbr] ' + llmAdvisory
+        }));
+      }
+
+      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 heredoc first: -m "$(cat <<'EOF'\n...\nEOF\n)" or -m "$(cat <<EOF\n...\nEOF\n)"
+  // Must check before generic -m patterns to avoid capturing heredoc syntax as the message
+  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();
+  }
+
+  // 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];
+
+  return null;
+}
+
+module.exports = { checkCommit, enrichCommitLlm };
+if (require.main === module || process.argv[1] === __filename) { main(); }

package/hooks/dist/validate-plugin-structure.js

@@ -0,0 +1,193 @@
+#!/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');
+
+function validate(rootDir) {
+  // Default to plugins/pbr/ since the plugin structure lives there, not at repo root
+  const ROOT = rootDir || path.resolve(__dirname, '..', 'plugins', 'pbr');
+  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);
+              // Handle run-hook.js bootstrap pattern: command ends with "run-hook.js\" scriptName.js"
+              const runHookMatch = cmd.match(/run-hook\.js[^"]*\)?\)?"?\s+(\S+\.js)/);
+              if (runHookMatch) {
+                // Script is dispatched via run-hook.js — look in scripts/ dir
+                const scriptName = runHookMatch[1];
+                const resolvedPath = path.join(ROOT, 'scripts', scriptName);
+                if (!fs.existsSync(resolvedPath)) {
+                  error(`hooks.json references missing script: ${scriptName}`);
+                }
+              } else {
+                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`);
+
+  return { errors, warnings };
+}
+
+module.exports = { validate };
+
+if (require.main === module || process.argv[1] === __filename) {
+  const result = validate();
+  if (result.errors > 0) {
+    process.exit(1);
+  }
+}

package/hooks/dist/validate-skill-args.js

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+
+/**
+ * PreToolUse hook: Validates Skill tool arguments before execution.
+ *
+ * Currently validates:
+ *   - /pbr:plan-phase — blocks freeform text arguments that don't match
+ *     valid patterns (phase number, subcommand, flags).
+ *
+ * When freeform text is detected, analyzes it to suggest the most
+ * appropriate skill (quick, debug, explore, todo, plan).
+ *
+ * Exit codes:
+ *   0 = allowed (valid args or non-plan skill)
+ *   2 = blocked (freeform text detected for /pbr:plan-phase)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+
+/**
+ * Skills that accept a phase number as their first argument.
+ */
+const PHASE_SKILLS = new Set([
+  'pbr:plan-phase', 'pbr:execute-phase', 'pbr:discuss-phase',
+  'pbr:research-phase', 'pbr:list-phase-assumptions',
+  'pbr:insert-phase', 'pbr:remove-phase'
+]);
+
+/**
+ * Validate that a phase number exists in ROADMAP.md.
+ * Returns null if valid or no roadmap, or an advisory string if phase not found.
+ */
+function validatePhaseExists(phaseNum) {
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+  const roadmapPath = path.join(cwd, '.planning', 'ROADMAP.md');
+  try {
+    if (!fs.existsSync(roadmapPath)) return null;
+    const roadmap = fs.readFileSync(roadmapPath, 'utf8');
+    // Look for phase number in roadmap (e.g., "| 03 |" or "## Phase 3")
+    const padded = String(phaseNum).padStart(2, '0');
+    const patterns = [
+      new RegExp(`\\|\\s*${phaseNum}\\s*\\|`),
+      new RegExp(`\\|\\s*${padded}\\s*\\|`),
+      new RegExp(`##\\s+Phase\\s+${phaseNum}\\b`),
+      new RegExp(`##\\s+Phase\\s+${padded}\\b`),
+      new RegExp(`${padded}-[a-z]`)
+    ];
+    if (patterns.some(p => p.test(roadmap))) return null;
+    // Phase not found — extract valid phase numbers
+    const phaseNums = [];
+    const tableRows = roadmap.match(/\|\s*(\d+(?:\.\d+)?)\s*\|/g);
+    if (tableRows) {
+      for (const row of tableRows) {
+        const m = row.match(/\|\s*(\d+(?:\.\d+)?)\s*\|/);
+        if (m) phaseNums.push(m[1]);
+      }
+    }
+    const validList = phaseNums.length > 0 ? ` Valid phases: ${phaseNums.join(', ')}.` : '';
+    return `Phase ${phaseNum} not found in ROADMAP.md.${validList}`;
+  } catch (_e) {
+    return null; // Can't read roadmap — don't block
+  }
+}
+
+/**
+ * Valid argument patterns for /pbr:plan-phase.
+ *
+ * Matches:
+ *   - Empty / whitespace only
+ *   - Phase number: "3", "03", "3.1"
+ *   - Phase number + flags: "3 --skip-research", "3 --assumptions", "3 --gaps", "3 --teams"
+ *   - Subcommands: "add", "insert 3", "remove 3"
+ *   - Legacy: "check"
+ */
+const PLAN_VALID_PATTERN = /^\s*$|^\s*\d+(\.\d+)?\s*(--(?:skip-research|assumptions|gaps|teams)\s*)*$|^\s*(?:add|check)\s*$|^\s*(?:insert|remove)\s+\d+(\.\d+)?\s*$/i;
+
+/**
+ * Keyword patterns for routing freeform text to the right skill.
+ * Order matters — first match wins.
+ */
+const ROUTE_PATTERNS = [
+  {
+    pattern: /\b(bugs?|fix(es|ing)?|errors?|crash(es|ing)?|fails?|failing|broken|issues?|debug(ging)?|diagnos(e|ing)|stack\s*trace|exceptions?|regress(ion|ing)?)\b/i,
+    skill: '/pbr:debug',
+    reason: 'Looks like a bug or debugging task'
+  },
+  {
+    pattern: /\b(explore|research|understand|how does|what is|analy[zs]e|evaluate|compare|pros and cons|trade-?offs?|approach(es)?)\b/i,
+    skill: '/pbr:explore',
+    reason: 'Looks like exploration or research'
+  },
+  {
+    pattern: /\b(refactor|redesign|architect|migrate|restructure|overhaul|rewrite|multi-?phase|complex|system|infrastructure)\b/i,
+    skill: '/pbr:plan-phase add',
+    reason: 'Looks like a complex task that needs full planning'
+  },
+  {
+    // Default: anything actionable goes to quick
+    pattern: /./,
+    skill: '/pbr:quick',
+    reason: 'Looks like a straightforward task'
+  }
+];
+
+/**
+ * Suggest the best skill for freeform text.
+ * Returns { skill, reason }.
+ */
+function suggestSkill(text) {
+  for (const route of ROUTE_PATTERNS) {
+    if (route.pattern.test(text)) {
+      return { skill: route.skill, reason: route.reason };
+    }
+  }
+  return { skill: '/pbr:quick', reason: 'Default routing' };
+}
+
+/**
+ * Check whether a Skill tool call has valid arguments.
+ * Returns null if valid, or { output, exitCode } if blocked.
+ */
+function checkSkillArgs(data) {
+  const toolInput = data.tool_input || {};
+  const skill = toolInput.skill || '';
+  const args = toolInput.args || '';
+
+  // Phase number existence check for all phase-taking skills
+  const fullSkillName = skill.startsWith('pbr:') ? skill : `pbr:${skill}`;
+  if (PHASE_SKILLS.has(fullSkillName) && args) {
+    const phaseMatch = args.trim().match(/^(\d+(?:\.\d+)?)/);
+    if (phaseMatch) {
+      const warning = validatePhaseExists(phaseMatch[1]);
+      if (warning) {
+        logHook('validate-skill-args', 'PreToolUse', 'phase-not-found', {
+          skill, phase: phaseMatch[1]
+        });
+        return {
+          output: {
+            decision: 'block',
+            reason: `[pbr] ${warning} Check your ROADMAP.md or use /pbr:progress to see current phases.`
+          },
+          exitCode: 2
+        };
+      }
+    }
+  }
+
+  // Only validate pbr:plan (invoked as /pbr:plan-phase) arg format for now
+  if (skill !== 'pbr:plan') {
+    return null;
+  }
+
+  // Test against valid patterns
+  if (PLAN_VALID_PATTERN.test(args)) {
+    return null;
+  }
+
+  // Freeform text detected — suggest the right skill
+  const suggestion = suggestSkill(args);
+
+  logHook('validate-skill-args', 'PreToolUse', 'blocked', {
+    skill,
+    args: args.substring(0, 100),
+    reason: 'freeform-text',
+    suggested: suggestion.skill
+  });
+
+  return {
+    output: {
+      decision: 'block',
+      reason: [
+        'BLOCKED: /pbr:plan-phase received freeform text instead of a phase number.',
+        '',
+        'The arguments "' + args.substring(0, 80) + (args.length > 80 ? '...' : '') + '" do not match any valid pattern.',
+        '',
+        'Valid /pbr:plan-phase usage:',
+        '  /pbr:plan-phase <N>              Plan phase N',
+        '  /pbr:plan-phase <N> --gaps       Create gap-closure plans',
+        '  /pbr:plan-phase add              Add a new phase',
+        '  /pbr:plan-phase insert <N>       Insert a phase at position N',
+        '  /pbr:plan-phase remove <N>       Remove phase N',
+        '',
+        'Suggested skill for this text:',
+        '  ' + suggestion.skill + ' — ' + suggestion.reason,
+        '',
+        'Or use /pbr:do to auto-route freeform text to the right skill.'
+      ].join('\n')
+    },
+    exitCode: 2
+  };
+}
+
+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 = checkSkillArgs(data);
+
+      if (result) {
+        process.stdout.write(JSON.stringify(result.output));
+        process.exit(result.exitCode);
+      }
+
+      process.exit(0);
+    } catch (_e) {
+      // Don't block on errors
+      process.exit(0);
+    }
+  });
+}
+
+module.exports = { checkSkillArgs, suggestSkill, validatePhaseExists, PLAN_VALID_PATTERN, ROUTE_PATTERNS, PHASE_SKILLS };
+if (require.main === module || process.argv[1] === __filename) { main(); }