@sienklogic/plan-build-run 2.18.1 → 2.19.1

package/plugins/pbr/dist/pre-write-dispatch.js

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+
+/**
+ * PreToolUse dispatcher for Write|Edit hooks.
+ *
+ * Consolidates all PreToolUse Write|Edit checks into a single process,
+ * reading stdin once and running all checks sequentially.
+ *
+ * -- Dispatch Order & Rationale --
+ *
+ *   1. enforce-pbr-workflow  -- Warns or blocks source code writes that
+ *      happen without an active PBR skill. Runs first because this is
+ *      the most fundamental enforcement: if no PBR skill is managing
+ *      the session, all other skill-specific checks are moot.
+ *      Can block (exit 2) or advise (exit 0). Config-driven.
+ *
+ *   2. check-agent-state-write -- Blocks subagents from writing STATE.md
+ *      directly (except pbr:general). Runs before skill-specific checks
+ *      because agent isolation is a hard invariant. Can block (exit 2).
+ *
+ *   3. check-skill-workflow  -- Enforces planning-phase rules (e.g. no
+ *      code writes during the plan phase). Can block (exit 2).
+ *
+ *   4. check-summary-gate    -- Blocks STATE.md status advancement
+ *      (to built/verified/complete) unless a SUMMARY file exists for
+ *      the current phase. Can block (exit 2).
+ *
+ *   5. check-phase-boundary  -- Guards against writes that target files
+ *      outside the current phase directory. Can block (exit 2)
+ *      or warn (exit 0 with message).
+ *
+ *   6. check-doc-sprawl      -- Prevents creation of new .md/.txt files
+ *      outside a known allowlist (when enabled in config). Can block (exit 2).
+ *
+ *   7. prompt-guard           -- Scans .planning/ writes for prompt injection
+ *      patterns. Advisory only (exit 0).
+ *
+ * -- Short-Circuit Behavior --
+ *
+ *   If an earlier check returns a result (blocking or warning with
+ *   output), later checks are skipped entirely. For blocking results
+ *   (exit 2), this means the write is rejected without evaluating
+ *   remaining checks. This is intentional: the first failure is the
+ *   most relevant, and running further checks would be wasteful.
+ *
+ * -- Adding New Checks --
+ *
+ *   1. Create a new check module exporting a function that takes
+ *      the parsed hook data and returns null (pass) or
+ *      { output: {...}, exitCode: N }.
+ *   2. require() it at the top of this file.
+ *   3. Add the call in sequence below, following the pattern:
+ *        const result = checkFoo(data);
+ *        if (result) { write output; exit with code; }
+ *   4. Position the check based on severity: more fundamental /
+ *      broader checks should run earlier; narrow / granular checks
+ *      should run later.
+ *
+ * Exit codes:
+ *   0 = allowed or warning only
+ *   2 = blocked (workflow violation or phase boundary enforcement)
+ */
+
+const { logHook } = require('./hook-logger');
+const { checkAgentStateWrite } = require('./check-agent-state-write');
+const { checkWorkflow } = require('./check-skill-workflow');
+const { checkSummaryGate } = require('./check-summary-gate');
+const { checkBoundary } = require('./check-phase-boundary');
+const { checkDocSprawl } = require('./check-doc-sprawl');
+const { checkPromptInjection } = require('./prompt-guard');
+const { checkUnmanagedSourceWrite } = require('./enforce-pbr-workflow');
+
+/**
+ * Core dispatch logic extracted for both stdin (main) and HTTP (handleHttp) paths.
+ *
+ * Runs checks sequentially with short-circuit on first block.
+ * Advisory results are returned as { decision: 'allow', additionalContext }.
+ *
+ * @param {Object} data - Parsed hook input (same as stdin JSON)
+ * @returns {Object|null} Hook response: { decision: 'block', reason } or { decision: 'allow', additionalContext? } or advisory output or null
+ */
+function processEvent(data) {
+  try {
+    // Unmanaged source write check -- runs first as the most fundamental
+    // workflow enforcement: warn/block when source code is edited without
+    // an active PBR skill managing the session.
+    const unmanagedResult = checkUnmanagedSourceWrite(data);
+    if (unmanagedResult) {
+      if (unmanagedResult.exitCode === 2) {
+        return { decision: 'block', reason: unmanagedResult.output.reason || unmanagedResult.output.additionalContext || 'Unmanaged source write blocked' };
+      }
+      return unmanagedResult.output;
+    }
+
+    // Agent STATE.md write blocker -- most fundamental check
+    const agentResult = checkAgentStateWrite(data);
+    if (agentResult) {
+      if (agentResult.exitCode === 2) {
+        return { decision: 'block', reason: agentResult.output.reason || agentResult.output.additionalContext || 'Agent STATE.md write blocked' };
+      }
+      return agentResult.output;
+    }
+
+    // Skill workflow check -- can block
+    const workflowResult = checkWorkflow(data);
+    if (workflowResult) {
+      if (workflowResult.exitCode === 2) {
+        return { decision: 'block', reason: workflowResult.output.reason || workflowResult.output.additionalContext || 'Workflow violation' };
+      }
+      return workflowResult.output;
+    }
+
+    // SUMMARY gate -- blocks STATE.md advancement without SUMMARY
+    const summaryGateResult = checkSummaryGate(data);
+    if (summaryGateResult) {
+      if (summaryGateResult.exitCode === 2) {
+        return { decision: 'block', reason: summaryGateResult.output.reason || summaryGateResult.output.additionalContext || 'Summary gate violation' };
+      }
+      return summaryGateResult.output;
+    }
+
+    // Phase boundary check -- can block or warn
+    const boundaryResult = checkBoundary(data);
+    if (boundaryResult) {
+      if (boundaryResult.exitCode === 2) {
+        return { decision: 'block', reason: boundaryResult.output.reason || boundaryResult.output.additionalContext || 'Phase boundary violation' };
+      }
+      return boundaryResult.output;
+    }
+
+    // Doc sprawl check -- blocks new .md/.txt outside allowlist
+    const sprawlResult = checkDocSprawl(data);
+    if (sprawlResult) {
+      if (sprawlResult.exitCode === 2) {
+        return { decision: 'block', reason: sprawlResult.output.reason || sprawlResult.output.additionalContext || 'Doc sprawl blocked' };
+      }
+      return sprawlResult.output;
+    }
+
+    // Prompt injection scan -- advisory only (never blocks)
+    const injectionResult = checkPromptInjection(data);
+    if (injectionResult) {
+      return injectionResult.output;
+    }
+
+    // Soft warning: writing outside current phase directory
+    // (only when all hard checks passed and we're in a phase)
+    const filePath = data.tool_input?.file_path || data.tool_input?.path || '';
+    if (filePath) {
+      const normalized = filePath.replace(/\\/g, '/');
+      // Warn about writes to other phase directories (not blocked, just advisory)
+      const phaseMatch = normalized.match(/\.planning\/phases\/(\d+)-/);
+      if (phaseMatch) {
+        const fs = require('fs');
+        const path = require('path');
+        const statePath = path.join(process.env.PBR_PROJECT_ROOT || process.cwd(), '.planning', 'STATE.md');
+        try {
+          const stateContent = fs.readFileSync(statePath, 'utf8');
+          const currentPhase = stateContent.match(/Phase:\s*(\d+)\s+of/);
+          if (currentPhase && parseInt(phaseMatch[1], 10) !== parseInt(currentPhase[1], 10)) {
+            return {
+              additionalContext: `[pbr] Advisory: writing to phase ${phaseMatch[1]} but current phase is ${currentPhase[1]}. Ensure this cross-phase write is intentional.`
+            };
+          }
+        } catch (_e) {
+          // No STATE.md -- skip warning
+        }
+      }
+    }
+
+    // Log pass-through so hook activity is visible in logs AND session JSONL
+    const file = (data.tool_input?.file_path || data.tool_input?.path || '').split(/[/\\]/).pop();
+    logHook('pre-write-dispatch', 'PreToolUse', 'allow', { file });
+    return { decision: 'allow' };
+  } catch (e) {
+    logHook('pre-write-dispatch', 'PreToolUse', 'error', { error: e.message });
+    return null;
+  }
+}
+
+/**
+ * HTTP handler for hook-server.js.
+ * Called as handleHttp(reqBody, cache) where reqBody = { event, tool, data, planningDir, cache }.
+ * Must NOT call process.exit().
+ *
+ * @param {Object} reqBody - Request body from hook-server
+ * @param {Object} _cache - In-memory server cache (unused)
+ * @returns {Object|null} Hook response or null
+ */
+async function handleHttp(reqBody, _cache) {
+  const data = reqBody.data || {};
+  try {
+    return processEvent(data);
+  } catch (_e) {
+    logHook('pre-write-dispatch', 'PreToolUse', 'error', { error: _e.message });
+    return null;
+  }
+}
+
+module.exports = { handleHttp, processEvent };
+
+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 = processEvent(data);
+
+      if (result && result.decision === 'block') {
+        process.stdout.write(JSON.stringify(result));
+        process.exit(2);
+      }
+
+      if (result) {
+        process.stdout.write(JSON.stringify(result));
+      } else {
+        // processEvent returned null (error) -- allow through
+        process.stdout.write(JSON.stringify({ decision: 'allow' }));
+      }
+      process.exit(0);
+    } catch (_e) {
+      // Don't block on errors -- emit valid output for Claude Code
+      process.stderr.write(`[pbr] pre-write-dispatch error: ${_e.message}\n`);
+      process.stdout.write(JSON.stringify({ decision: "allow", additionalContext: '\u26a0 [PBR] pre-write-dispatch failed: ' + _e.message }));
+      process.exit(0);
+    }
+  });
+}
+
+if (require.main === module || process.argv[1] === __filename) { main(); }

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

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+
+/**
+ * SessionStart hook: Auto-detects .planning/ directory and injects
+ * project state as additionalContext.
+ *
+ * If no .planning/ directory exists, exits silently (non-Plan-Build-Run project).
+ * If STATE.md exists, reads and outputs a concise summary.
+ *
+ * Heavy lifting delegated to:
+ *   - ./lib/session-briefing.js  (context building, health, intel, decisions)
+ *   - ./lib/dashboard-launch.js  (dashboard + hook-server launchers, enriched context)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+const { logEvent } = require('./event-logger');
+const { configLoad, sessionSave } = require('./pbr-tools');
+const { ensureSessionDir, cleanStaleSessions } = require('./lib/core');
+const { resolveConfig, checkHealth, warmUp } = require('./lib/local-llm/health');
+
+// Re-export from extracted modules for backward compatibility
+const {
+  buildEnhancedBriefing,
+  buildContext,
+  getHookHealthSummary,
+  getDecisionBriefing,
+  getNegativeKnowledgeBriefing,
+  getIntelContext,
+  getIntelStalenessWarning,
+  checkLearningsDeferrals,
+  detectOtherSessions,
+  extractSection,
+  findContinueFiles,
+  countNotes,
+  FAILURE_DECISIONS,
+  HOOK_HEALTH_MAX_ENTRIES,
+} = require('./lib/session-briefing');
+
+const {
+  tryLaunchDashboard,
+  tryLaunchHookServer,
+  getEnrichedContext,
+} = require('./lib/dashboard-launch');
+
+function readStdin() {
+  try {
+    const input = fs.readFileSync(0, 'utf8').trim();
+    if (input) return JSON.parse(input);
+  } catch (_e) {
+    // empty or non-JSON stdin
+  }
+  return {};
+}
+
+async function main() {
+  const data = readStdin();
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+  const stateFile = path.join(planningDir, 'STATE.md');
+
+  // Not a Plan-Build-Run project
+  if (!fs.existsSync(planningDir)) {
+    process.exit(0);
+  }
+
+  // Extract session_id from hook input
+  const sessionId = data.session_id || null;
+
+  // Reset compaction counter for new session
+  const { resetCounter } = require('./suggest-compact');
+  resetCounter(planningDir, sessionId);
+
+  // Reset session phase counter for new session
+  const { resetTracker } = require('./session-tracker');
+  resetTracker(planningDir, sessionId);
+
+  // Create session directory and clean stale sessions
+  if (sessionId) {
+    try {
+      ensureSessionDir(planningDir, sessionId);
+    } catch (_e) { /* non-fatal */ }
+    try {
+      const staleRemoved = cleanStaleSessions(planningDir);
+      if (staleRemoved.length > 0) {
+        logHook('progress-tracker', 'SessionStart', 'stale-sessions-removed', {
+          count: staleRemoved.length,
+          removed: staleRemoved.map(s => s.sessionId).join(', ')
+        });
+      }
+    } catch (_e) { /* non-fatal */ }
+  }
+
+  // Detect other active sessions and build warning
+  let sessionWarning = '';
+  if (sessionId) {
+    try {
+      const otherSessions = detectOtherSessions(planningDir, sessionId);
+      if (otherSessions.length > 0) {
+        // Read current phase from STATE.md for conflict detection context
+        let currentPhase = 'unknown';
+        try {
+          if (fs.existsSync(stateFile)) {
+            const stateContent = fs.readFileSync(stateFile, 'utf8');
+            const phaseMatch = stateContent.match(/Phase:\s*(\d+)\s+of\s+\d+/);
+            if (phaseMatch) currentPhase = phaseMatch[1];
+          }
+        } catch (_e) { /* best-effort */ }
+
+        const warnings = otherSessions.map(s => {
+          const skillPart = s.skill ? `skill: ${s.skill}` : 'no active skill';
+          return `WARNING: Another PBR session is active (${skillPart}, phase: ${currentPhase}, age: ${s.age}min). Working on different phases is safe; same phase will conflict.`;
+        });
+        sessionWarning = '\n' + warnings.join('\n');
+        logHook('progress-tracker', 'SessionStart', 'other-sessions-detected', {
+          count: otherSessions.length,
+          sessions: otherSessions.map(s => s.sessionId).join(', ')
+        });
+      }
+    } catch (_e) { /* non-fatal */ }
+  }
+
+  const context = buildContext(planningDir, stateFile);
+
+  // Auto-launch dashboard if configured
+  const config = configLoad(planningDir);
+  if (config && config.dashboard && config.dashboard.auto_launch) {
+    tryLaunchDashboard(config.dashboard.port || 3000, planningDir, cwd);
+  }
+
+  // Auto-launch hook server
+  if (config) {
+    tryLaunchHookServer(config, planningDir);
+  }
+
+  // Write session-start timestamp for local-llm metrics correlation
+  // Primary: write to .session.json (unified session state)
+  // Legacy: also write .session-start file for session-cleanup.js backward compat
+  const sessionStart = new Date().toISOString();
+  try { sessionSave(planningDir, { sessionStart }, sessionId); } catch (_e) { /* non-fatal */ }
+  const sessionStartFile = path.join(planningDir, '.session-start');
+  try {
+    fs.writeFileSync(sessionStartFile, sessionStart, 'utf8');
+  } catch (_e) { /* non-fatal */ }
+
+  // Local LLM health check (advisory only -- never blocks SessionStart)
+  let llmContext = '';
+  try {
+    const rawLlmConfig = config && config.local_llm;
+    const llmConfig = resolveConfig(rawLlmConfig);
+    if (llmConfig.enabled) {
+      const health = await checkHealth(llmConfig);
+      if (health.available) {
+        llmContext = `\nLocal LLM: ${llmConfig.model} (${health.warm ? 'warm' : 'cold start'})`;
+        if (!health.warm) {
+          // Fire warm-up without awaiting -- 23s cold start must not block hook
+          warmUp(llmConfig);
+        }
+      } else if (health.reason !== 'disabled') {
+        llmContext = `\nLocal LLM: unavailable -- ${health.detail || health.reason}`;
+      }
+    }
+  } catch (_e) { /* graceful degradation -- never surface to user */ }
+
+  // Enrich context with recent session activity from hook server (advisory, fail-open)
+  let enrichedContext = '';
+  try {
+    const enriched = await getEnrichedContext(config, planningDir);
+    if (enriched && typeof enriched === 'object' && Array.isArray(enriched.recentEvents)) {
+      const skillList = Array.isArray(enriched.activeSkillHistory) ? enriched.activeSkillHistory.join(', ') || 'none' : 'none';
+      enrichedContext = `\n## Recent Session Activity\n- ${enriched.recentEvents.length} recent events tracked\n- Active skills: ${skillList}`;
+      if (Array.isArray(enriched.advisoryMessages) && enriched.advisoryMessages.length > 0) {
+        const lastThree = enriched.advisoryMessages.slice(-3);
+        enrichedContext += '\n- Recent advisories: ' + lastThree.map(m => m.additionalContext || '').filter(Boolean).join(' | ');
+      }
+    }
+  } catch (_e) { /* graceful degradation */ }
+
+  if (context) {
+    const output = {
+      additionalContext: context + sessionWarning + llmContext + enrichedContext
+    };
+    process.stdout.write(JSON.stringify(output));
+    logHook('progress-tracker', 'SessionStart', 'injected', { hasState: true });
+    logEvent('workflow', 'session-start', { hasState: true });
+  } else {
+    logHook('progress-tracker', 'SessionStart', 'skipped', { hasState: false });
+    logEvent('workflow', 'session-start', { hasState: false });
+  }
+
+  process.exit(0);
+}
+
+// Exported for testing — re-exports from extracted modules
+module.exports = { buildEnhancedBriefing, buildContext, getHookHealthSummary, checkLearningsDeferrals, getEnrichedContext, detectOtherSessions, getIntelContext, getIntelStalenessWarning, getDecisionBriefing, getNegativeKnowledgeBriefing, FAILURE_DECISIONS, HOOK_HEALTH_MAX_ENTRIES, tryLaunchDashboard, tryLaunchHookServer };
+
+if (require.main === module || process.argv[1] === __filename) { main().catch(() => {}); }

package/plugins/pbr/dist/prompt-guard.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+
+/**
+ * PreToolUse check: Advisory scan of .planning/ writes for prompt injection patterns.
+ *
+ * Scans content being written to .planning/ files for common prompt injection
+ * techniques. ADVISORY ONLY — never blocks, always exits 0.
+ *
+ * Pattern categories:
+ *   1. INSTRUCTION_OVERRIDE — "ignore previous instructions" etc.
+ *   2. ROLE_MANIPULATION — "you are now a" etc.
+ *   3. SYSTEM_PROMPT_EXTRACTION — "repeat your system prompt" etc.
+ *   4. XML_TAG_MIMICKING — fake <system>, <tool_result> etc.
+ *   5. INVISIBLE_UNICODE — zero-width chars, directional overrides
+ *
+ * Called by pre-write-dispatch.js — not wired directly in hooks.json.
+ *
+ * Exit codes:
+ *   0 = always (advisory only, never blocks)
+ */
+
+const { logHook } = require('./hook-logger');
+
+/**
+ * Paths that legitimately contain XML examples and tag references.
+ * These are excluded from XML_TAG_MIMICKING checks.
+ */
+const XML_ALLOWLIST_SEGMENTS = ['/skills/', '/agents/', '/templates/', '/references/'];
+
+const PATTERN_CATEGORIES = {
+  INSTRUCTION_OVERRIDE: [
+    /ignore\s+(all\s+)?previous\s+instructions/i,
+    /disregard\s+(all\s+)?prior/i,
+    /forget\s+everything\s+(above|before|you)/i,
+    /do\s+not\s+follow\s+(the|your)\s+(previous|above|prior)/i,
+  ],
+  ROLE_MANIPULATION: [
+    /you\s+are\s+now\s+a/i,
+    /act\s+as\s+(a|an|if)\b/i,
+    /pretend\s+(to\s+be|you\s+are)/i,
+    /from\s+now\s+on[,\s]+(you|your)\s+(are|role)/i,
+  ],
+  SYSTEM_PROMPT_EXTRACTION: [
+    /repeat\s+your\s+(system\s+)?prompt/i,
+    /show\s+me\s+your\s+(instructions|system\s+prompt)/i,
+    /what\s+(are|is)\s+your\s+(system\s+)?instructions/i,
+    /output\s+your\s+(entire\s+)?(system\s+)?prompt/i,
+  ],
+  XML_TAG_MIMICKING: [
+    /<\/?system>/,
+    /<\/?tool_result>/,
+    /<\/?function_calls>/,
+    /<\/?antml:/,
+    /<\/?human>/,
+    /<\/?assistant>/,
+  ],
+  INVISIBLE_UNICODE: [
+    /\u200B|\u200C|\u200D|\uFEFF/,
+    /[\u202A-\u202E]/,
+    /[\u2066-\u2069]/,
+  ],
+};
+
+/**
+ * Scan content written to .planning/ for prompt injection patterns.
+ * @param {Object} data - Parsed hook input (tool_input, etc.)
+ * @returns {null|{exitCode: number, output: Object}} null if clean, advisory result otherwise
+ */
+function checkPromptInjection(data) {
+  const filePath = data.tool_input?.file_path || data.tool_input?.path || '';
+  if (!filePath) return null;
+
+  const normalized = filePath.replace(/\\/g, '/');
+
+  // Only scan .planning/ writes
+  if (!normalized.includes('.planning/')) return null;
+
+  // Get content from Write (content) or Edit (new_string)
+  const content = data.tool_input?.content || data.tool_input?.new_string || '';
+  if (!content) return null;
+
+  // Check if this path is allowlisted for XML tag patterns
+  const isXmlAllowlisted = XML_ALLOWLIST_SEGMENTS.some((seg) => normalized.includes(seg));
+
+  const matches = [];
+
+  for (const [category, patterns] of Object.entries(PATTERN_CATEGORIES)) {
+    // Skip XML tag check for allowlisted paths
+    if (category === 'XML_TAG_MIMICKING' && isXmlAllowlisted) continue;
+
+    for (const pattern of patterns) {
+      if (pattern.test(content)) {
+        matches.push({ category, pattern: pattern.source });
+        break; // One match per category is enough
+      }
+    }
+  }
+
+  if (matches.length === 0) return null;
+
+  const categories = [...new Set(matches.map((m) => m.category))].join(', ');
+  const file = normalized.split('/').pop();
+
+  logHook('prompt-guard', 'PreToolUse', 'warn', { file, categories });
+
+  return {
+    exitCode: 0,
+    output: {
+      additionalContext: `[pbr:prompt-guard] Advisory: detected ${matches.length} potential prompt injection pattern(s) in .planning/ write: ${categories}. Review content for safety.`
+    }
+  };
+}
+
+module.exports = { checkPromptInjection, PATTERN_CATEGORIES };