@sienklogic/plan-build-run 2.0.2 → 2.1.1

package/hooks/dist/check-config-change.js

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+
+/**
+ * ConfigChange hook: Validates config.json changes and warns about inconsistencies.
+ *
+ * Fires when Claude Code detects configuration file changes (v2.1.49+).
+ * Checks .planning/config.json for:
+ *   - Required top-level keys
+ *   - Semantic conflicts (e.g., parallel agents enabled with max=1)
+ *   - Version field presence
+ *
+ * Exit codes:
+ *   0 = always (advisory hook, never blocks)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+const { logEvent } = require('./event-logger');
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let input = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { input += chunk; });
+    process.stdin.on('end', () => {
+      try {
+        resolve(JSON.parse(input));
+      } catch (_e) {
+        resolve({});
+      }
+    });
+  });
+}
+
+function findPlanningDir() {
+  let dir = process.cwd();
+  const root = path.parse(dir).root;
+  while (dir !== root) {
+    const candidate = path.join(dir, '.planning');
+    if (fs.existsSync(candidate)) return candidate;
+    dir = path.dirname(dir);
+  }
+  return null;
+}
+
+function validateConfig(configPath) {
+  const warnings = [];
+
+  let config;
+  try {
+    const raw = fs.readFileSync(configPath, 'utf8');
+    config = JSON.parse(raw);
+  } catch (e) {
+    warnings.push(`config.json parse error: ${e.message}`);
+    return warnings;
+  }
+
+  // Check required top-level keys
+  const requiredKeys = ['version', 'features', 'models', 'gates'];
+  for (const key of requiredKeys) {
+    if (!(key in config)) {
+      warnings.push(`Missing required key: ${key}`);
+    }
+  }
+
+  // Advisory: suggest local_llm defaults if the key is absent
+  if (!config.local_llm) {
+    warnings.push(
+      'local_llm config missing. To enable local LLM offload, add to config.json:\n' +
+      '"local_llm": {\n' +
+      '  "enabled": false,\n' +
+      '  "model": "qwen2.5-coder:7b",\n' +
+      '  "endpoint": "http://localhost:11434"\n' +
+      '} (set enabled: true after running: ollama pull qwen2.5-coder:7b)'
+    );
+  }
+
+  // Check version
+  if (config.version && config.version < 2) {
+    warnings.push(`Config version ${config.version} is outdated — expected version 2+`);
+  }
+
+  // Check semantic conflicts
+  if (config.parallelization) {
+    const p = config.parallelization;
+    if (p.enabled && p.max_concurrent_agents === 1) {
+      warnings.push('Semantic conflict: parallelization.enabled=true but max_concurrent_agents=1');
+    }
+    if (!p.enabled && (p.plan_level || p.task_level)) {
+      warnings.push('Semantic conflict: parallelization.enabled=false but plan_level/task_level are true');
+    }
+  }
+
+  // Check model values
+  if (config.models) {
+    const validModels = ['sonnet', 'opus', 'haiku', 'inherit'];
+    for (const [role, model] of Object.entries(config.models)) {
+      if (!validModels.includes(model)) {
+        warnings.push(`Invalid model "${model}" for ${role} — expected: ${validModels.join(', ')}`);
+      }
+    }
+  }
+
+  // Validate local_llm block
+  if (config.local_llm !== undefined) {
+    const llm = config.local_llm;
+    if (llm.enabled !== undefined && typeof llm.enabled !== 'boolean') {
+      warnings.push('local_llm.enabled must be a boolean');
+    }
+    if (llm.provider !== undefined && llm.provider !== 'ollama') {
+      warnings.push(`local_llm.provider "${llm.provider}" is not supported — use "ollama"`);
+    }
+    if (llm.timeout_ms !== undefined && (typeof llm.timeout_ms !== 'number' || llm.timeout_ms < 500)) {
+      warnings.push('local_llm.timeout_ms must be a number >= 500');
+    }
+    if (llm.advanced && llm.advanced.num_ctx !== undefined && llm.advanced.num_ctx !== 4096) {
+      warnings.push(`local_llm.advanced.num_ctx is ${llm.advanced.num_ctx} — strongly recommend 4096 to avoid GPU memory issues on Windows`);
+    }
+    if (llm.advanced && llm.advanced.disable_after_failures !== undefined &&
+        (typeof llm.advanced.disable_after_failures !== 'number' || llm.advanced.disable_after_failures < 1)) {
+      warnings.push('local_llm.advanced.disable_after_failures must be a number >= 1');
+    }
+  }
+
+  return warnings;
+}
+
+async function main() {
+  await readStdin();
+  const startTime = Date.now();
+
+  const planningDir = findPlanningDir();
+  if (!planningDir) {
+    logHook('check-config-change', 'ConfigChange', 'skip', { reason: 'no .planning dir' }, startTime);
+    process.exit(0);
+  }
+
+  const configPath = path.join(planningDir, 'config.json');
+  if (!fs.existsSync(configPath)) {
+    logHook('check-config-change', 'ConfigChange', 'skip', { reason: 'no config.json' }, startTime);
+    process.exit(0);
+  }
+
+  const warnings = validateConfig(configPath);
+
+  if (warnings.length > 0) {
+    const msg = `⚠️ Config validation (${warnings.length} issue${warnings.length > 1 ? 's' : ''}):\n${warnings.map(w => `  - ${w}`).join('\n')}`;
+
+    logHook('check-config-change', 'ConfigChange', 'warn', { warnings }, startTime);
+    logEvent('workflow', 'config-change', { warnings });
+
+    process.stdout.write(JSON.stringify({ additionalContext: msg }));
+  } else {
+    logHook('check-config-change', 'ConfigChange', 'ok', {}, startTime);
+    logEvent('workflow', 'config-change', { status: 'valid' });
+  }
+
+  process.exit(0);
+}
+
+/**
+ * handleHttp — hook-server.js interface.
+ * reqBody = { event, tool, data, planningDir, cache }
+ * Returns { additionalContext: "..." } or null. Never calls process.exit().
+ */
+function handleHttp(reqBody) {
+  const planningDir = (reqBody && reqBody.planningDir) || findPlanningDir();
+  if (!planningDir) return null;
+
+  const configPath = path.join(planningDir, 'config.json');
+  if (!fs.existsSync(configPath)) return null;
+
+  const warnings = validateConfig(configPath);
+  if (warnings.length > 0) {
+    const msg = `\u26a0\ufe0f Config validation (${warnings.length} issue${warnings.length > 1 ? 's' : ''}):\n${warnings.map(w => `  - ${w}`).join('\n')}`;
+    logHook('check-config-change', 'ConfigChange', 'warn', { warnings });
+    logEvent('workflow', 'config-change', { warnings });
+    return { additionalContext: msg };
+  }
+
+  logHook('check-config-change', 'ConfigChange', 'ok', {});
+  logEvent('workflow', 'config-change', { status: 'valid' });
+  return null;
+}
+
+if (require.main === module || process.argv[1] === __filename) main();
+module.exports = { validateConfig, findPlanningDir, handleHttp };

package/hooks/dist/check-dangerous-commands.js

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+
+/**
+ * PreToolUse hook: Blocks dangerous Bash commands that could destroy
+ * planning state or repository integrity.
+ *
+ * Patterns blocked (exit 2):
+ *   - rm -rf .planning (or any rm that targets .planning/)
+ *   - git reset --hard
+ *   - git push --force / -f to main/master
+ *   - git clean -fd / -fxd (removes untracked files including .planning/)
+ *
+ * Patterns warned (exit 0, additionalContext):
+ *   - Large rm operations (rm -rf on project directories)
+ *   - git checkout -- . (discards all unstaged changes)
+ *
+ * Exit codes:
+ *   0 = not a dangerous command, or a warning-only match
+ *   2 = blocked (destructive command detected)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+const { resolveSessionPath } = require('../plan-build-run/bin/lib/core.cjs');
+
+// Commands that are outright blocked
+const BLOCK_PATTERNS = [
+  {
+    pattern: /\brm\s+(-[a-zA-Z]*r[a-zA-Z]*f[a-zA-Z]*|-[a-zA-Z]*f[a-zA-Z]*r[a-zA-Z]*)\s+.*\.planning\b/,
+    reason: 'rm -rf targeting .planning/ directory — this would destroy all project state.'
+  },
+  {
+    pattern: /\brm\s+(-[a-zA-Z]*r[a-zA-Z]*f[a-zA-Z]*|-[a-zA-Z]*f[a-zA-Z]*r[a-zA-Z]*)\s+.*\.planning[/\\]/,
+    reason: 'rm -rf targeting files inside .planning/ — this would destroy project state.'
+  },
+  {
+    pattern: /\bgit\s+reset\s+--hard\b/,
+    reason: 'git reset --hard discards all uncommitted changes. Use git stash or git checkout for specific files instead.'
+  },
+  {
+    pattern: /\bgit\s+push\s+.*(-f|--force)\b.*\b(main|master)\b/,
+    reason: 'Force-pushing to main/master can destroy shared history. This is almost never what you want.'
+  },
+  {
+    pattern: /\bgit\s+push\s+.*\b(main|master)\b.*(-f|--force)\b/,
+    reason: 'Force-pushing to main/master can destroy shared history. This is almost never what you want.'
+  },
+  {
+    pattern: /\bgit\s+clean\s+(-[a-zA-Z]*f[a-zA-Z]*d|-[a-zA-Z]*d[a-zA-Z]*f)\b/,
+    reason: 'git clean -fd removes untracked files including .planning/ contents. Use specific file paths instead.'
+  }
+];
+
+// Commands that produce warnings but are not blocked
+const WARN_PATTERNS = [
+  {
+    pattern: /\bgit\s+checkout\s+--\s+\.\s*$/,
+    message: 'git checkout -- . discards ALL unstaged changes. Consider targeting specific files.'
+  },
+  {
+    pattern: /\bgit\s+push\s+.*(-f|--force)\b/,
+    message: 'Force-pushing can overwrite remote history. Ensure this is intentional.'
+  }
+];
+
+/**
+ * Check a parsed hook data object for dangerous commands.
+ * Returns { output, exitCode } if the command should be blocked/warned, or null if allowed.
+ * Used by pre-bash-dispatch.js for consolidated hook execution.
+ */
+function checkDangerous(data) {
+  const command = data.tool_input?.command || '';
+
+  // Skip empty commands
+  if (!command.trim()) {
+    return null;
+  }
+
+  // Check block patterns
+  for (const { pattern, reason } of BLOCK_PATTERNS) {
+    if (pattern.test(command)) {
+      logHook('check-dangerous-commands', 'PreToolUse', 'block', {
+        command: command.substring(0, 200),
+        reason
+      });
+      return {
+        output: {
+          decision: 'block',
+          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
+      };
+    }
+  }
+
+  // Check warn patterns
+  for (const { pattern, message } of WARN_PATTERNS) {
+    if (pattern.test(command)) {
+      logHook('check-dangerous-commands', 'PreToolUse', 'warn', {
+        command: command.substring(0, 200),
+        warning: message
+      });
+      return {
+        output: {
+          additionalContext: `Warning: ${message}`
+        },
+        exitCode: 0
+      };
+    }
+  }
+
+  // Skill-specific checks
+  const sessionId = data.session_id || null;
+  const skillResult = checkSkillSpecificBash(command, sessionId);
+  if (skillResult) return skillResult;
+
+  // No match — allow
+  return null;
+}
+
+/**
+ * Skill-specific bash command checks.
+ * Currently: statusline skill cannot use sed/awk/perl on JSON files.
+ */
+function checkSkillSpecificBash(command, sessionId) {
+  const planningDir = path.join(process.cwd(), '.planning');
+  const skillFile = sessionId
+    ? resolveSessionPath(planningDir, '.active-skill', sessionId)
+    : path.join(planningDir, '.active-skill');
+
+  let activeSkill = null;
+  try {
+    activeSkill = fs.readFileSync(skillFile, 'utf8').trim();
+  } catch (_e) {
+    return null;
+  }
+
+  if (activeSkill !== 'statusline') return null;
+
+  // Block sed/awk/perl targeting .json files
+  const jsonManipPattern = /\b(sed|awk|perl)\b.*\.json/;
+  const echoRedirectPattern = /echo\s.*>\s*.*\.json/;
+
+  if (jsonManipPattern.test(command) || echoRedirectPattern.test(command)) {
+    logHook('check-dangerous-commands', 'PreToolUse', 'block', {
+      command: command.substring(0, 200),
+      reason: 'JSON shell manipulation during statusline'
+    });
+    return {
+      output: {
+        decision: 'block',
+        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
+    };
+  }
+
+  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 = checkDangerous(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);
+    }
+  });
+}
+
+module.exports = { BLOCK_PATTERNS, WARN_PATTERNS, checkDangerous };
+if (require.main === module || process.argv[1] === __filename) { main(); }

package/hooks/dist/check-doc-sprawl.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+
+/**
+ * PreToolUse check: Blocks creation of new .md/.txt documentation files
+ * outside a known allowlist, preventing doc sprawl during builds.
+ *
+ * Opt-in via .planning/config.json: { "hooks": { "blockDocSprawl": true } }
+ *
+ * Allowlist:
+ *   - README.md, CLAUDE.md, CONTRIBUTING.md, CHANGELOG.md, LICENSE.md, LICENSE, LICENSE.txt
+ *   - Any file under .planning/, .claude/, node_modules/, .git/
+ *   - Any file that already exists (edits to existing docs are always allowed)
+ *
+ * Called by pre-write-dispatch.js — not wired directly in hooks.json.
+ *
+ * Exit codes (when standalone):
+ *   0 = pass (allowed)
+ *   2 = block (not on allowlist)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+
+const ALLOWED_DOC_BASENAMES = new Set([
+  'readme.md',
+  'claude.md',
+  'contributing.md',
+  'changelog.md',
+  'license.md',
+  'license',
+  'license.txt',
+]);
+
+const ALLOWED_DIR_SEGMENTS = [
+  '.planning',
+  '.claude',
+  'node_modules',
+  '.git',
+];
+
+const DOC_EXTENSIONS = new Set(['.md', '.txt']);
+
+/**
+ * Check if a Write operation would create a disallowed documentation file.
+ * @param {Object} data - Parsed hook input (tool_input, etc.)
+ * @param {string} [cwd] - Working directory override (defaults to process.cwd())
+ * @returns {null|{exitCode: number, output: Object}} null if allowed, block result otherwise
+ */
+function checkDocSprawl(data, cwd) {
+  const filePath = data.tool_input?.file_path || data.tool_input?.path || '';
+  if (!filePath) return null;
+
+  const ext = path.extname(filePath).toLowerCase();
+  if (!DOC_EXTENSIONS.has(ext)) return null;
+
+  // Only block NEW file creation — existing docs can always be edited
+  if (fs.existsSync(filePath)) return null;
+
+  // Check config — disabled by default
+  const effectiveCwd = cwd || process.cwd();
+  if (!isBlockDocSprawlEnabled(effectiveCwd)) return null;
+
+  // Check basename allowlist
+  const basename = path.basename(filePath).toLowerCase();
+  if (ALLOWED_DOC_BASENAMES.has(basename)) return null;
+
+  // Check if file is in an allowed directory
+  const normalized = filePath.replace(/\\/g, '/');
+  for (const seg of ALLOWED_DIR_SEGMENTS) {
+    if (normalized.includes(`/${seg}/`)) return null;
+  }
+
+  logHook('check-doc-sprawl', 'PreToolUse', 'block', {
+    file: path.basename(filePath),
+    ext
+  });
+
+  return {
+    exitCode: 2,
+    output: {
+      decision: 'block',
+      reason: `[Doc Sprawl] Blocked creation of ${path.basename(filePath)}. ` +
+        'Only known docs (README.md, CLAUDE.md, CONTRIBUTING.md, CHANGELOG.md, LICENSE.md) ' +
+        'and .planning/ files are allowed when blockDocSprawl is enabled. ' +
+        'Add content to an existing file instead, or disable hooks.blockDocSprawl in config.'
+    }
+  };
+}
+
+function isBlockDocSprawlEnabled(cwd) {
+  try {
+    const configPath = path.join(cwd, '.planning', 'config.json');
+    if (!fs.existsSync(configPath)) return false;
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    return !!config.hooks?.blockDocSprawl;
+  } catch (_e) {
+    return false;
+  }
+}
+
+module.exports = { checkDocSprawl, isBlockDocSprawlEnabled, ALLOWED_DOC_BASENAMES, ALLOWED_DIR_SEGMENTS, DOC_EXTENSIONS };

package/hooks/dist/check-phase-boundary.js

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+
+// PreToolUse hook (Write|Edit): Warns or blocks when editing files
+// outside the current active phase.
+//
+// Reads STATE.md for current phase number. If the file being written
+// is under .planning/phases/NN-<slug>/ and NN does not match the
+// current phase, issues a warning or blocks depending on config.
+//
+// Config: safety.enforce_phase_boundaries
+//   - true  = block cross-phase writes (exit 2)
+//   - false = warn only (default)
+//   - absent = warn only
+//
+// Files outside .planning/phases/ are always allowed (source code,
+// config files, etc.).
+//
+// Exit codes:
+//   0 = allowed or not applicable
+//   2 = blocked (only when enforce_phase_boundaries is true)
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+const { logEvent } = require('./event-logger');
+
+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 filePath = data.tool_input?.file_path || data.tool_input?.path || '';
+
+      if (!filePath) {
+        process.exit(0);
+      }
+
+      const cwd = process.cwd();
+      const planningDir = path.join(cwd, '.planning');
+
+      // Check if the file is under .planning/phases/ using marker matching
+      // instead of absolute path comparison (avoids macOS /var -> /private/var symlink issues)
+      const normalizedPath = filePath.replace(/\\/g, '/');
+      const phasesMarker = '.planning/phases/';
+      const markerIdx = normalizedPath.indexOf(phasesMarker);
+
+      if (markerIdx === -1) {
+        process.exit(0);
+      }
+
+      // Extract phase number from path after the marker
+      // Path pattern: .planning/phases/NN-slug/...
+      const afterMarker = normalizedPath.substring(markerIdx + phasesMarker.length);
+      const phaseMatch = afterMarker.match(/^(\d+)-/);
+      if (!phaseMatch) {
+        process.exit(0);
+      }
+      const filePhase = parseInt(phaseMatch[1], 10);
+
+      // Get current phase from STATE.md
+      const stateFile = path.join(planningDir, 'STATE.md');
+      if (!fs.existsSync(stateFile)) {
+        process.exit(0);
+      }
+
+      const state = fs.readFileSync(stateFile, 'utf8');
+      const currentPhaseMatch = state.match(/Phase:\s*(\d+)\s+of\s+\d+/);
+      if (!currentPhaseMatch) {
+        process.exit(0);
+      }
+      const currentPhase = parseInt(currentPhaseMatch[1], 10);
+
+      // Same phase — always allowed
+      if (filePhase === currentPhase) {
+        process.exit(0);
+      }
+
+      // Cross-phase write detected — check config
+      const enforce = getEnforceSetting(planningDir);
+
+      logHook('check-phase-boundary', 'PreToolUse', enforce ? 'block' : 'warn', {
+        filePhase,
+        currentPhase,
+        file: path.basename(filePath)
+      });
+      logEvent('workflow', 'phase-boundary', {
+        filePhase,
+        currentPhase,
+        file: path.basename(filePath),
+        action: enforce ? 'block' : 'warn'
+      });
+
+      if (enforce) {
+        const output = {
+          decision: 'block',
+          reason: `Cross-phase write blocked: editing phase ${filePhase} file but current phase is ${currentPhase}.\n\nFile: ${filePath}\n\nIf this is intentional, either:\n  1. Update STATE.md to reflect the correct phase\n  2. Set safety.enforce_phase_boundaries: false in config.json`
+        };
+        process.stdout.write(JSON.stringify(output));
+        process.exit(2);
+      } else {
+        const output = {
+          additionalContext: `[Advisory] Cross-phase edit: modifying phase ${filePhase} file while current phase is ${currentPhase}. If unintentional: check STATE.md to confirm correct phase. If intentional (e.g. backfilling docs): no action needed. To suppress: set safety.enforce_phase_boundaries: false in config.json.`
+        };
+        process.stdout.write(JSON.stringify(output));
+      }
+
+      process.exit(0);
+    } catch (_e) {
+      // Don't block on errors
+      process.exit(0);
+    }
+  });
+}
+
+function getEnforceSetting(planningDir) {
+  const configFile = path.join(planningDir, 'config.json');
+  if (!fs.existsSync(configFile)) return false;
+
+  try {
+    const config = JSON.parse(fs.readFileSync(configFile, 'utf8'));
+    return !!(config.safety && config.safety.enforce_phase_boundaries);
+  } catch (_e) {
+    return false;
+  }
+}
+
+/**
+ * Core boundary check logic for use by dispatchers.
+ * @param {Object} data - Parsed hook input (tool_input, etc.)
+ * @returns {null|{exitCode: number, output: Object}} null if pass, result otherwise
+ */
+function checkBoundary(data) {
+  const filePath = data.tool_input?.file_path || data.tool_input?.path || '';
+  if (!filePath) return null;
+
+  const cwd = process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+
+  const normalizedPath = filePath.replace(/\\/g, '/');
+  const phasesMarker = '.planning/phases/';
+  const markerIdx = normalizedPath.indexOf(phasesMarker);
+  if (markerIdx === -1) return null;
+
+  const afterMarker = normalizedPath.substring(markerIdx + phasesMarker.length);
+  const phaseMatch = afterMarker.match(/^(\d+)-/);
+  if (!phaseMatch) return null;
+  const filePhase = parseInt(phaseMatch[1], 10);
+
+  const stateFile = path.join(planningDir, 'STATE.md');
+  if (!fs.existsSync(stateFile)) return null;
+
+  const state = fs.readFileSync(stateFile, 'utf8');
+  const currentPhaseMatch = state.match(/Phase:\s*(\d+)\s+of\s+\d+/);
+  if (!currentPhaseMatch) return null;
+  const currentPhase = parseInt(currentPhaseMatch[1], 10);
+
+  if (filePhase === currentPhase) return null;
+
+  const enforce = getEnforceSetting(planningDir);
+
+  logHook('check-phase-boundary', 'PreToolUse', enforce ? 'block' : 'warn', {
+    filePhase, currentPhase, file: path.basename(filePath)
+  });
+  logEvent('workflow', 'phase-boundary', {
+    filePhase, currentPhase, file: path.basename(filePath), action: enforce ? 'block' : 'warn'
+  });
+
+  if (enforce) {
+    return {
+      exitCode: 2,
+      output: {
+        decision: 'block',
+        reason: `Cross-phase write blocked: editing phase ${filePhase} file but current phase is ${currentPhase}.\n\nFile: ${filePath}\n\nIf this is intentional, either:\n  1. Update STATE.md to reflect the correct phase\n  2. Set safety.enforce_phase_boundaries: false in config.json`
+      }
+    };
+  }
+
+  return {
+    exitCode: 0,
+    output: {
+      additionalContext: `[Advisory] Cross-phase edit: modifying phase ${filePhase} file while current phase is ${currentPhase}. If unintentional: check STATE.md to confirm correct phase. If intentional (e.g. backfilling docs): no action needed. To suppress: set safety.enforce_phase_boundaries: false in config.json.`
+    }
+  };
+}
+
+module.exports = { getEnforceSetting, checkBoundary };
+if (require.main === module || process.argv[1] === __filename) { main(); }