@sienklogic/plan-build-run 2.18.1 → 2.19.1

package/plugins/pbr/dist/trust-tracker.js

@@ -0,0 +1,193 @@
+/**
+ * trust-tracker.js — Per-agent pass/fail trust scoring.
+ *
+ * Tracks agent outcomes by type and task category, persisting scores
+ * to .planning/trust/agent-scores.json. Used by confidence calibration
+ * to weight deliverable confidence based on historical accuracy.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const TRUST_DIR = 'trust';
+const TRUST_FILE = 'agent-scores.json';
+
+const HIGH_THRESHOLD = 0.9;
+const MEDIUM_THRESHOLD = 0.7;
+
+/**
+ * Load trust scores from disk.
+ * @param {string} planningDir - Path to .planning directory
+ * @returns {object} Parsed scores or empty object
+ */
+function loadScores(planningDir) {
+  const filePath = path.join(planningDir, TRUST_DIR, TRUST_FILE);
+  try {
+    const raw = fs.readFileSync(filePath, 'utf8');
+    return JSON.parse(raw);
+  } catch (_err) {
+    return {};
+  }
+}
+
+/**
+ * Save trust scores to disk (creates dir if needed).
+ * @param {string} planningDir - Path to .planning directory
+ * @param {object} scores - Scores object to persist
+ */
+function saveScores(planningDir, scores) {
+  const dirPath = path.join(planningDir, TRUST_DIR);
+  fs.mkdirSync(dirPath, { recursive: true });
+  fs.writeFileSync(
+    path.join(dirPath, TRUST_FILE),
+    JSON.stringify(scores, null, 2),
+    'utf8'
+  );
+}
+
+/**
+ * Record a pass or fail outcome for an agent+category.
+ * @param {string} planningDir - Path to .planning directory
+ * @param {string} agentType - Agent identifier (e.g. "executor")
+ * @param {string} taskCategory - Task category (e.g. "build")
+ * @param {boolean} passed - Whether the outcome was a pass
+ */
+function recordOutcome(planningDir, agentType, taskCategory, passed) {
+  const scores = loadScores(planningDir);
+  if (!scores[agentType]) scores[agentType] = {};
+  if (!scores[agentType][taskCategory]) {
+    scores[agentType][taskCategory] = { pass: 0, fail: 0, rate: 0 };
+  }
+  const entry = scores[agentType][taskCategory];
+  if (passed) {
+    entry.pass++;
+  } else {
+    entry.fail++;
+  }
+  const total = entry.pass + entry.fail;
+  entry.rate = total > 0 ? entry.pass / total : 0;
+  saveScores(planningDir, scores);
+  logTrustEvent(planningDir, agentType, taskCategory, passed, entry.rate);
+}
+
+/**
+ * Get confidence data for an agent+category.
+ * @param {string} planningDir - Path to .planning directory
+ * @param {string} agentType - Agent identifier
+ * @param {string} taskCategory - Task category
+ * @returns {{ rate: number, total: number, label: string } | null}
+ */
+function getConfidence(planningDir, agentType, taskCategory) {
+  const scores = loadScores(planningDir);
+  if (!scores[agentType] || !scores[agentType][taskCategory]) return null;
+  const entry = scores[agentType][taskCategory];
+  const total = entry.pass + entry.fail;
+  let label;
+  if (entry.rate >= HIGH_THRESHOLD) {
+    label = 'high';
+  } else if (entry.rate >= MEDIUM_THRESHOLD) {
+    label = 'medium';
+  } else {
+    label = 'low';
+  }
+  return { rate: entry.rate, total, label };
+}
+
+/**
+ * Log a trust event to .planning/logs/trust-events.jsonl for audit trail.
+ * Never throws — failures are silently swallowed.
+ * @param {string} planningDir - Path to .planning directory
+ * @param {string} agent - Agent identifier
+ * @param {string} category - Task category
+ * @param {boolean} passed - Whether the outcome was a pass
+ * @param {number} newRate - Updated pass rate after this outcome
+ */
+function logTrustEvent(planningDir, agent, category, passed, newRate) {
+  try {
+    const logsDir = path.join(planningDir, 'logs');
+    fs.mkdirSync(logsDir, { recursive: true });
+    const entry = {
+      ts: new Date().toISOString(),
+      agent,
+      category,
+      passed,
+      new_rate: newRate
+    };
+    fs.appendFileSync(
+      path.join(logsDir, 'trust-events.jsonl'),
+      JSON.stringify(entry) + '\n',
+      'utf8'
+    );
+  } catch (_err) {
+    // Never throw from audit logging
+  }
+}
+
+/**
+ * Get a confidence summary for an agent across all categories.
+ * @param {string} planningDir - Path to .planning directory
+ * @param {string} agentType - Agent identifier
+ * @returns {{ agent: string, categories: object, overall_rate: number, overall_total: number } | null}
+ */
+function getConfidenceSummary(planningDir, agentType) {
+  const scores = loadScores(planningDir);
+  if (!scores[agentType]) return null;
+  const agentScores = scores[agentType];
+  const categories = {};
+  let totalPass = 0;
+  let totalFail = 0;
+  for (const [cat, entry] of Object.entries(agentScores)) {
+    const total = (entry.pass || 0) + (entry.fail || 0);
+    let label;
+    if (entry.rate >= HIGH_THRESHOLD) {
+      label = 'high';
+    } else if (entry.rate >= MEDIUM_THRESHOLD) {
+      label = 'medium';
+    } else {
+      label = 'low';
+    }
+    categories[cat] = {
+      pass: entry.pass || 0,
+      fail: entry.fail || 0,
+      rate: entry.rate || 0,
+      total,
+      label
+    };
+    totalPass += entry.pass || 0;
+    totalFail += entry.fail || 0;
+  }
+  const overallTotal = totalPass + totalFail;
+  const overallRate = overallTotal > 0 ? totalPass / overallTotal : 0;
+  return {
+    agent: agentType,
+    categories,
+    overall_rate: overallRate,
+    overall_total: overallTotal
+  };
+}
+
+/**
+ * Delete the trust scores file.
+ * @param {string} planningDir - Path to .planning directory
+ */
+function resetScores(planningDir) {
+  const filePath = path.join(planningDir, TRUST_DIR, TRUST_FILE);
+  try {
+    fs.unlinkSync(filePath);
+  } catch (_err) {
+    // File doesn't exist — no-op
+  }
+}
+
+module.exports = {
+  loadScores,
+  recordOutcome,
+  getConfidence,
+  getConfidenceSummary,
+  logTrustEvent,
+  resetScores,
+  TRUST_DIR,
+  TRUST_FILE
+};

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

@@ -0,0 +1,271 @@
+#!/usr/bin/env node
+
+/**
+ * PreToolUse hook: Validates git commit message format.
+ *
+ * Expected format: {type}({scope}): {description}
+ * Valid types: feat, fix, refactor, test, docs, chore, wip, revert, perf, ci, build
+ *
+ * Scopes: Component names (hooks, skills, agents, cli, dashboard, templates,
+ * plugin, ci, config, tests, commands, refs), descriptive words, quick-{NNN},
+ * planning, or legacy phase-plan numbers ({NN}-{MM}).
+ *
+ * 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('./lib/local-llm/health');
+const { classifyCommit } = require('./lib/local-llm/operations/classify-commit');
+
+const VALID_TYPES = ['feat', 'fix', 'refactor', 'test', 'docs', 'chore', 'wip', 'revert', 'perf', 'ci', 'build'];
+
+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: component name, NN-MM (phase-plan), quick-NNN, planning, or any word
+const COMMIT_PATTERN = /^(feat|fix|refactor|test|docs|chore|wip|revert|perf|ci|build)(\([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, sessionId) {
+  if (AI_COAUTHOR_PATTERN.test(command)) {
+    logHook('validate-commit', 'PreToolUse', 'block-coauthor', { command: command.substring(0, 200), sessionId });
+    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(sessionId) {
+  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, sessionId });
+      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 || '';
+  const sessionId = data.session_id || null;
+
+  // 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', sessionId });
+    return null;
+  }
+
+  // Validate format
+  if (MERGE_PATTERN.test(message)) {
+    logHook('validate-commit', 'PreToolUse', 'allow', { message, reason: 'merge commit', sessionId });
+    return null;
+  }
+
+  if (!COMMIT_PATTERN.test(message)) {
+    logHook('validate-commit', 'PreToolUse', 'block', { message, sessionId });
+    logEvent('workflow', 'commit-validated', { message: message.substring(0, 80), status: 'block', sessionId });
+    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, sessionId });
+  logEvent('workflow', 'commit-validated', { message: message.substring(0, 80), status: 'allow', sessionId });
+
+  // Check AI co-author
+  const coAuthorResult = checkAiCoAuthorResult(command, sessionId);
+  if (coAuthorResult) return coAuthorResult;
+
+  // Check sensitive files
+  const sensitiveResult = checkSensitiveFilesResult(sessionId);
+  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.stdout.write(JSON.stringify({ additionalContext: '⚠ [PBR] validate-commit failed: ' + _e.message }));
+      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/plugins/pbr/dist/validate-skill-args.js

@@ -0,0 +1,222 @@
+#!/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 — emit valid output for Claude Code
+      process.stderr.write(`[pbr] validate-skill-args error: ${_e.message}
+`);
+      process.stdout.write(JSON.stringify({ decision: "allow", additionalContext: '⚠ [PBR] validate-skill-args failed: ' + _e.message }));
+      process.exit(0);
+    }
+  });
+}
+
+module.exports = { checkSkillArgs, suggestSkill, validatePhaseExists, PLAN_VALID_PATTERN, ROUTE_PATTERNS, PHASE_SKILLS };
+if (require.main === module || process.argv[1] === __filename) { main(); }