kenaz 0.0.0-stage → 0.3.2

package/core/.specialist/tools/phase-gate.test.js

@@ -0,0 +1,85 @@
+'use strict';
+// phase-gate gate-shape tests (restored TASK_2340 after the Kuzu removal dropped the pulse/predicted_symbols/thalamus gates).
+// Everything runs against a temp --project-path; charts for the temp project land in the git-ignored .specialist/sessions/projects/.
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const proj = fs.mkdtempSync(path.join(os.tmpdir(), 'pg2340-'));
+fs.mkdirSync(path.join(proj, '.kenaz', 'specialist'), { recursive: true });
+process.argv.push('--project-path=' + proj); // read at module load by phase-gate
+const pg = require('./phase-gate');
+
+const coreRoot = path.resolve(__dirname, '../..');
+const taskId = 'TASK_PG2340_' + process.pid;
+const taskDir = path.join(coreRoot, '.kenaz', 'tasks', 'active');
+const taskFile = path.join(taskDir, taskId + '.yaml');
+
+// enterPhase/exitPhase print JSON; keep test output clean.
+function quiet(fn) {
+  const log = console.log;
+  console.log = () => {};
+  try { return fn(); } finally { console.log = log; }
+}
+
+// enterPhase touches lesson_guards.yaml (injection bookkeeping); restore it so the suite leaves the tree clean.
+const guardsFile = path.join(coreRoot, '.specialist', 'Ansuz', 'guards', 'lesson_guards.yaml');
+const guardsBefore = fs.existsSync(guardsFile) ? fs.readFileSync(guardsFile) : null;
+
+test.before(() => {
+  fs.mkdirSync(taskDir, { recursive: true });
+  fs.writeFileSync(taskFile, `id: ${taskId}\ntitle: pg test\nscope_paths:\n  - .specialist/tools/phase-gate.js\n`);
+});
+test.after(() => {
+  if (guardsBefore) fs.writeFileSync(guardsFile, guardsBefore);
+  fs.rmSync(taskFile, { force: true });
+  try { fs.rmdirSync(taskDir); } catch { /* not empty or absent: leave tracked dirs alone */ }
+  fs.rmSync(proj, { recursive: true, force: true });
+  const sessions = path.join(coreRoot, '.specialist', 'sessions', 'projects');
+  if (fs.existsSync(sessions)) {
+    for (const d of fs.readdirSync(sessions)) {
+      if (d.startsWith(path.basename(proj).toLowerCase())) fs.rmSync(path.join(sessions, d), { recursive: true, force: true });
+    }
+  }
+});
+
+test('the task fixture really declares scope_paths', () => {
+  assert.deepEqual(pg.readTaskScopePaths(taskId), ['.specialist/tools/phase-gate.js']);
+});
+
+test('checklists no longer ask for removed tools (preamble, thalamus, pulse, search)', () => {
+  const all = JSON.stringify(pg.PHASE_CHECKLISTS);
+  for (const gone of ['synapse_preamble', 'preamble_loaded', 'Tier 2b', 'thalamus', 'synapse_pulse', 'synapse_search', 'synapse_impact']) {
+    assert.equal(all.includes(gone), false, gone);
+  }
+  assert.ok(pg.PHASE_CHECKLISTS[0].some(i => i.includes('cortex_recall')));
+  assert.ok(pg.PHASE_CHECKLISTS[2].some(i => i.includes('kenaz_lsp_callers')));
+  assert.equal(JSON.stringify(pg.PHASE_CHECKLISTS).toLowerCase().includes('muninn'), false);
+});
+
+test('Phase 8 exit rule no longer requires predicted_symbols', () => {
+  assert.equal(pg.PHASE_EXIT_RULES[8], undefined);
+  assert.deepEqual(pg.PHASE_EXIT_RULES[1].required, ['recall_executed', 'ddx_hypotheses']);
+  assert.deepEqual(pg.PHASE_EXIT_RULES[9].required, ['cognitive_checkpoint']);
+});
+
+test('Phase 3 enter is not blocked by a missing pulse log even when the task declares scope_paths', () => {
+  const r = quiet(() => pg.enterPhase(3, taskId));
+  assert.equal(r.blocked, false);
+  assert.equal(r.block_reason, null);
+  assert.equal(JSON.stringify(r.warnings).includes('pulse'), false);
+});
+
+test('Phase 8 enter no longer reports muninn / valence output', () => {
+  const r = quiet(() => pg.enterPhase(8, taskId));
+  assert.equal(r.blocked, false);
+  assert.equal('valence' in r, false);
+  assert.equal('muninn' in r, false);
+});
+
+test('Phase 8 exit passes with scope_paths and no predicted_symbols', () => {
+  const r = quiet(() => pg.exitPhase(8, taskId, {}));
+  assert.notEqual(r.blocked, true);
+});

package/core/.specialist/tools/phase9-policy.test.js

@@ -0,0 +1,109 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const yaml = require('js-yaml');
+
+// Policy-consistency regression checks only. Reading this YAML does not execute
+// Forseti, verify a task's evidence, or enforce runtime phase/task transitions.
+const policyPath = path.join(__dirname, '../../dev/archive/ansuz/legacy/phases/phase_9.yaml');
+const policy = yaml.load(fs.readFileSync(policyPath, 'utf8'));
+
+function validatePolicy(candidate) {
+  const failures = [];
+  const requireText = (value, patterns, label) => {
+    if (typeof value !== 'string' || patterns.some(pattern => !pattern.test(value))) {
+      failures.push(label);
+    }
+  };
+  const verdict = candidate.forseti_verification?.verdict_handling || {};
+  requireText(verdict.on_PARTIAL, [/UNVERIFIED/, /required/i, /passing evidence/i, /only when/i, /optional/i],
+    'PARTIAL requires evidence for required criteria and only optional skips');
+  requireText(verdict.on_UNVERIFIED, [/on_success|Phase 10/i, /not|never|禁止|不可|不得/i],
+    'Forseti UNVERIFIED must not advance to success');
+
+  const minimal = candidate.minimal_verification || {};
+  const checks = minimal.checks || {};
+  requireText(checks.rust_project, [/cargo check/], 'retain Rust verification');
+  requireText(checks.typescript_project, [/\.tsx?\b/, /typecheck|tsc --noEmit/i], 'retain TypeScript verification');
+  requireText(checks.javascript_project, [/\.js\b/, /\.cjs\b/, /\.mjs\b/, /runner/i, /behavior/i, /UNVERIFIED/],
+    'JavaScript requires behavior checks, with missing evidence UNVERIFIED');
+  requireText(checks.documentation_only, [/consistency|acceptance/i, /parse/i, /executable/i],
+    'documentation-only changes still verify acceptance');
+  requireText(checks.fallback, [/UNVERIFIED/, /executable/i],
+    'unsupported executable artifacts must not silently skip verification');
+  requireText(minimal.on_UNVERIFIED, [/on_success|Phase 10/i, /\bno\b|not|never|禁止|不可|不得/i],
+    'minimal UNVERIFIED must not advance to success');
+
+  const steps = candidate.forseti_verification?.fix_loop?.steps || {};
+  if (Object.hasOwn(steps, '4_complete_original')) {
+    failures.push('remove premature original-completion step');
+  }
+  requireText(steps['4_preserve_original'], [/active|blocked|open/i, /original/i, /verif/i, /rerun/i],
+    'FIX preserves original task until verification');
+  // Reject executable completion commands in either failure-handling route.
+  // This deliberately does not inspect on_success, where completion belongs.
+  const failureRoutes = [steps['4_preserve_original'],
+    candidate.on_failure?.actions?.create_fix_and_dispatch];
+  for (const route of failureRoutes) {
+    if (typeof route !== 'string' || /task-api\.js[^\r\n]*\bcomplete\b|^\s*(?:\[--project-path[^\r\n]*\]\s*)?complete\s+TASK_/im.test(route)) {
+      failures.push('failure route must not command original task completion');
+    }
+  }
+  return failures;
+}
+
+function clonePolicy() {
+  return JSON.parse(JSON.stringify(policy));
+}
+
+test('Phase 9 YAML policy retains evidence gates and original-task ownership', () => {
+  assert.equal(policy.phase, 9);
+  assert.deepEqual(validatePolicy(policy), []);
+});
+
+test('policy validator rejects legacy unconditional PARTIAL success', () => {
+  const candidate = clonePolicy();
+  candidate.forseti_verification.verdict_handling.on_PARTIAL =
+    'PARTIAL is graceful degradation; proceed directly to on_success.';
+  assert.ok(validatePolicy(candidate).some(message => message.startsWith('PARTIAL')));
+});
+
+test('policy validator rejects missing JavaScript behavior verification', () => {
+  const candidate = clonePolicy();
+  delete candidate.minimal_verification.checks.javascript_project;
+  assert.ok(validatePolicy(candidate).some(message => message.startsWith('JavaScript')));
+});
+
+test('policy validator rejects syntax-only JavaScript verification', () => {
+  const candidate = clonePolicy();
+  candidate.minimal_verification.checks.javascript_project =
+    'For .js .cjs .mjs run node --check. Missing syntax evidence is UNVERIFIED.';
+  assert.ok(validatePolicy(candidate).some(message => message.startsWith('JavaScript')));
+});
+
+test('policy validator rejects premature original completion in Forseti FIX loop', () => {
+  const candidate = clonePolicy();
+  delete candidate.forseti_verification.fix_loop.steps['4_preserve_original'];
+  candidate.forseti_verification.fix_loop.steps['4_complete_original'] =
+    'node {CORE}/.collaboration/core/task-api.js complete TASK_XXX';
+  assert.ok(validatePolicy(candidate).some(message => message.includes('premature original')));
+});
+
+test('policy validator rejects premature original completion in fallback failure route', () => {
+  const candidate = clonePolicy();
+  candidate.on_failure.actions.create_fix_and_dispatch =
+    'node {CORE}/.collaboration/core/task-api.js complete TASK_XXX';
+  assert.ok(validatePolicy(candidate).some(message => message.includes('failure route')));
+});
+
+test('policy validator rejects missing UNVERIFIED handling and unsupported-artifact skips', () => {
+  const candidate = clonePolicy();
+  delete candidate.forseti_verification.verdict_handling.on_UNVERIFIED;
+  delete candidate.minimal_verification.on_UNVERIFIED;
+  candidate.minimal_verification.checks.fallback = 'SKIPPED: no compilable artifacts';
+  const failures = validatePolicy(candidate);
+  assert.ok(failures.some(message => message.startsWith('Forseti UNVERIFIED')));
+  assert.ok(failures.some(message => message.startsWith('minimal UNVERIFIED')));
+  assert.ok(failures.some(message => message.startsWith('unsupported executable')));
+});

package/core/.specialist/tools/precompute-runner.js

@@ -0,0 +1,444 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Precompute Runner — TASK_1162
+ *
+ * Executes safe, read-only named functions before phase entry and embeds
+ * their output into blind-spot guard text. Eliminates "remember to check X"
+ * compliance friction by making the result already present in instructions.
+ *
+ * Security model:
+ *   - execFileSync with argv array (never execSync + shell) — prevents shell injection
+ *   - env: SAFE_ENV (PATH-only) — drops GIT_EXEC_PATH, LD_PRELOAD, etc.
+ *   - Per-parameter regex validation BEFORE any execFileSync call
+ *   - File paths resolved within project root and rejected on escape
+ *   - Whitelist: 5 named functions only — gitShowStat, gitDiffStat, grepCount, wcLines, fileExists
+ *
+ * Budget:
+ *   - 3s total per phase enter (TOTAL_BUDGET_MS)
+ *   - 1s per command (PER_CMD_TIMEOUT_MS, enforced by execFileSync timeout option)
+ *   - Per-guard output capped at 200 chars (PER_GUARD_CAP)
+ *   - Total output capped at 4096 bytes (TOTAL_CAP)
+ *
+ * Kill switch:
+ *   KENAZ_PRECOMPUTE_DISABLE=1 → skip all precompute, fall back to text-only guard
+ *
+ * Guard YAML precompute field format:
+ *   precompute:
+ *     cmd: "gitShowStat"        # one of 5 named functions
+ *     sha: "HEAD"               # gitShowStat / gitDiffStat param
+ *     sha1: "HEAD~1"            # gitDiffStat param
+ *     sha2: "HEAD"              # gitDiffStat param
+ *     pattern: "TODO"           # grepCount param (JS regex pattern)
+ *     file: "path/to/file"      # grepCount / wcLines param (project-relative)
+ *     path: "path/to/check"     # fileExists param (project-relative)
+ *     when: "always"            # "always" | "never" | taskData key name
+ *     template: "Result: {{result}}"  # {{result}} replaced with command output
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+// ── Constants ───────────────────────────────────────────────
+
+const TOTAL_BUDGET_MS   = 3000;  // total per phase enter
+const PER_CMD_TIMEOUT_MS = 1000; // execFileSync timeout per command
+const PER_GUARD_CAP     = 200;   // max chars per guard output (truncated with …)
+const TOTAL_CAP         = 4096;  // max total chars across all guards per phase
+const MAX_BUFFER        = 4096;  // execFileSync maxBuffer
+
+// SHA validation: 7–40 lowercase hex chars (git short or full SHA)
+const SHA_RE = /^[0-9a-f]{7,40}$/;
+
+// Minimal safe environment — only PATH so git can be located.
+// Drops GIT_EXEC_PATH, GIT_SSH, GIT_TEMPLATE_DIR, LD_PRELOAD, etc.
+const SAFE_ENV = { PATH: process.env.PATH || process.env.Path || '' };
+
+// ── Kill switch ─────────────────────────────────────────────
+
+/**
+ * Returns true if precompute is globally disabled via env var.
+ * Evaluated lazily so tests can set the env var before calling runPrecompute.
+ */
+function isDisabled() {
+  return process.env.KENAZ_PRECOMPUTE_DISABLE === '1';
+}
+
+// ── Parameter validators ────────────────────────────────────
+
+/**
+ * Validate a git SHA parameter.
+ * @param {string} sha
+ * @returns {string} validated sha
+ * @throws {Error} if invalid
+ */
+function validateSha(sha) {
+  if (typeof sha !== 'string' || !SHA_RE.test(sha)) {
+    throw new Error(`Invalid SHA "${sha}": must match /^[0-9a-f]{7,40}$/`);
+  }
+  return sha;
+}
+
+/**
+ * Resolve and validate a file path within project root.
+ * Rejects any path that escapes the project root (../ traversal).
+ * @param {string} filePath - relative or absolute path
+ * @param {string} projectRoot - absolute project root
+ * @returns {string} validated absolute path
+ * @throws {Error} if path escapes project root
+ */
+function resolveFilePath(filePath, projectRoot) {
+  if (typeof filePath !== 'string' || !filePath.trim()) {
+    throw new Error('File path must be a non-empty string');
+  }
+  const abs = path.isAbsolute(filePath)
+    ? filePath
+    : path.resolve(projectRoot, filePath);
+  const normalized = path.normalize(abs);
+  const rootNormalized = path.normalize(projectRoot);
+  // Must be within project root (starts with root + sep, or equals root)
+  if (normalized !== rootNormalized &&
+      !normalized.startsWith(rootNormalized + path.sep)) {
+    throw new Error(`Path escape rejected: "${filePath}" resolves outside project root`);
+  }
+  return normalized;
+}
+
+// ── Named Function Library ──────────────────────────────────
+//
+// Each function validates its parameters, then either executes a read-only
+// git command via execFileSync (argv array, never shell) or reads files
+// using Node's fs module (grepCount, wcLines, fileExists — cross-platform,
+// no shell dependency).
+
+/**
+ * Show stat for a single commit (files changed + insertions/deletions summary).
+ * @param {string} sha - 7–40 hex git SHA
+ * @param {string} projectRoot - absolute project root (cwd for git)
+ * @returns {string} trimmed stdout
+ */
+function gitShowStat(sha, projectRoot) {
+  validateSha(sha);
+  const result = execFileSync('git', ['show', '--stat', '--no-patch', sha], {
+    env: SAFE_ENV,
+    cwd: projectRoot,
+    timeout: PER_CMD_TIMEOUT_MS,
+    maxBuffer: MAX_BUFFER,
+    encoding: 'utf8',
+    windowsHide: true,
+  });
+  return result.trim();
+}
+
+/**
+ * Diff stat between two commits (files changed summary).
+ * @param {string} sha1 - base commit SHA
+ * @param {string} sha2 - head commit SHA
+ * @param {string} projectRoot - absolute project root
+ * @returns {string} trimmed stdout
+ */
+function gitDiffStat(sha1, sha2, projectRoot) {
+  validateSha(sha1);
+  validateSha(sha2);
+  const result = execFileSync('git', ['diff', '--stat', sha1, sha2], {
+    env: SAFE_ENV,
+    cwd: projectRoot,
+    timeout: PER_CMD_TIMEOUT_MS,
+    maxBuffer: MAX_BUFFER,
+    encoding: 'utf8',
+    windowsHide: true,
+  });
+  return result.trim();
+}
+
+/**
+ * Count lines matching a pattern in a file (pure Node — cross-platform).
+ * Uses JavaScript RegExp — no grep binary required on Windows.
+ * @param {string} pattern - JavaScript regex pattern string
+ * @param {string} filePath - project-relative or absolute path
+ * @param {string} projectRoot - absolute project root
+ * @returns {string} match count as string
+ */
+function grepCount(pattern, filePath, projectRoot) {
+  if (typeof pattern !== 'string') throw new Error('pattern must be a string');
+  const absPath = resolveFilePath(filePath, projectRoot);
+  // Validate pattern compiles (throws SyntaxError on invalid regex)
+  const re = new RegExp(pattern);
+  const content = fs.readFileSync(absPath, 'utf8');
+  const count = content.split('\n').filter(line => re.test(line)).length;
+  return String(count);
+}
+
+/**
+ * Count lines in a file (pure Node — cross-platform).
+ * @param {string} filePath - project-relative or absolute path
+ * @param {string} projectRoot - absolute project root
+ * @returns {string} line count as string
+ */
+function wcLines(filePath, projectRoot) {
+  const absPath = resolveFilePath(filePath, projectRoot);
+  const content = fs.readFileSync(absPath, 'utf8');
+  // Split on \n — consistent with wc -l semantics (count \n occurrences)
+  const count = content.split('\n').length - (content.endsWith('\n') ? 1 : 0);
+  return String(count);
+}
+
+/**
+ * Count commits between two refs: HEAD ahead of the given base ref.
+ * Used by L-004 to detect stale worktree base (e.g. ahead origin/main by N commits).
+ * @param {string} baseRef - base ref name (e.g. "origin/main", "main", "HEAD~10")
+ * @param {string} projectRoot - absolute project root
+ * @returns {string} "ahead {N} commits of {baseRef}" or "in sync with {baseRef}"
+ */
+function gitCommitsAhead(baseRef, projectRoot) {
+  // Only allow safe ref patterns: refs/, origin/x, local branch names, HEAD~N
+  if (!/^[a-zA-Z0-9_./~-]{1,80}$/.test(baseRef)) {
+    throw new Error(`Invalid baseRef "${baseRef}": must match /^[a-zA-Z0-9_./~-]{1,80}$/`);
+  }
+  let result;
+  try {
+    result = execFileSync('git', ['rev-list', '--count', `${baseRef}..HEAD`], {
+      env: SAFE_ENV,
+      cwd: projectRoot,
+      timeout: PER_CMD_TIMEOUT_MS,
+      maxBuffer: MAX_BUFFER,
+      encoding: 'utf8',
+      windowsHide: true,
+    });
+  } catch (e) {
+    return `(unknown — ${baseRef} unreachable)`;
+  }
+  const n = parseInt(result.trim(), 10);
+  if (!Number.isFinite(n)) return `(unknown count for ${baseRef})`;
+  if (n === 0) return `in sync with ${baseRef}`;
+  if (n > 50) return `⚠️ ahead ${n} commits of ${baseRef} — very stale base risk`;
+  if (n > 10) return `ahead ${n} commits of ${baseRef} — stale base possible`;
+  return `ahead ${n} commits of ${baseRef}`;
+}
+
+/**
+ * Show recent commits touching a file (last 5).
+ * Used by L-002 to surface what's recently changed in the file Ansuz is about to modify.
+ * @param {string} filePath - project-relative path
+ * @param {string} projectRoot - absolute project root
+ * @returns {string} compact log lines
+ */
+function gitLogShort(filePath, projectRoot) {
+  const absPath = resolveFilePath(filePath, projectRoot);
+  const relPath = path.relative(projectRoot, absPath);
+  // Reject path traversal — relPath must not start with ..
+  if (relPath.startsWith('..') || path.isAbsolute(relPath)) {
+    throw new Error(`Path escape detected: ${filePath}`);
+  }
+  const result = execFileSync('git', ['log', '--oneline', '-5', '--', relPath], {
+    env: SAFE_ENV,
+    cwd: projectRoot,
+    timeout: PER_CMD_TIMEOUT_MS,
+    maxBuffer: MAX_BUFFER,
+    encoding: 'utf8',
+    windowsHide: true,
+  });
+  const lines = result.trim().split('\n').filter(Boolean);
+  if (lines.length === 0) return `(no git history for ${relPath})`;
+  return `${relPath}: last ${lines.length} commits — ${lines[0].substring(0, 60)}`;
+}
+
+/**
+ * Check if a file exists within project root (pure Node — cross-platform).
+ * @param {string} filePath - project-relative or absolute path
+ * @param {string} projectRoot - absolute project root
+ * @returns {string} "true" or "false"
+ */
+function fileExists(filePath, projectRoot) {
+  let absPath;
+  try {
+    absPath = resolveFilePath(filePath, projectRoot);
+  } catch {
+    return 'false'; // invalid/escaped path → treat as not-found
+  }
+  return fs.existsSync(absPath) ? 'true' : 'false';
+}
+
+// ── Template Rendering ──────────────────────────────────────
+
+/**
+ * Render a template string, replacing {{result}} with the command output.
+ * Truncates to PER_GUARD_CAP chars with ellipsis if needed.
+ * @param {string} template
+ * @param {string} result - raw command output
+ * @returns {string} rendered and capped output
+ */
+function renderTemplate(template, result) {
+  const rendered = (template || '{{result}}').replace(/\{\{result\}\}/g, result);
+  if (rendered.length > PER_GUARD_CAP) {
+    return rendered.slice(0, PER_GUARD_CAP - 1) + '…';
+  }
+  return rendered;
+}
+
+// ── Single Guard Evaluator ──────────────────────────────────
+
+/**
+ * Evaluate a single guard's precompute field.
+ * Returns rendered string, or null if skipped (when=never or condition unmet).
+ *
+ * @param {object} guard - guard object with .precompute field
+ * @param {object} taskData - phase data for when-condition evaluation
+ * @param {string} projectRoot - absolute project root
+ * @returns {string|null} rendered output or null
+ */
+function evaluateGuard(guard, taskData, projectRoot) {
+  const pc = guard.precompute;
+  if (!pc || !pc.cmd) return null;
+
+  // Evaluate when condition
+  const when = (pc.when || 'always').trim();
+  if (when === 'never') return null;
+  if (when !== 'always') {
+    // Treat as a taskData key name — run only if taskData[when] is truthy
+    const safeData = taskData || {};
+    if (!safeData[when]) return null;
+  }
+
+  let rawResult;
+  try {
+    const cmd = pc.cmd;
+    switch (cmd) {
+      case 'gitShowStat':
+        rawResult = gitShowStat(pc.sha || 'HEAD', projectRoot);
+        break;
+
+      case 'gitDiffStat':
+        rawResult = gitDiffStat(pc.sha1 || 'HEAD~1', pc.sha2 || 'HEAD', projectRoot);
+        break;
+
+      case 'grepCount':
+        rawResult = grepCount(pc.pattern || '.', pc.file || '', projectRoot);
+        break;
+
+      case 'wcLines':
+        rawResult = wcLines(pc.file || '', projectRoot);
+        break;
+
+      case 'fileExists':
+        rawResult = fileExists(pc.path || pc.file || '', projectRoot);
+        break;
+
+      case 'gitCommitsAhead':
+        rawResult = gitCommitsAhead(pc.baseRef || pc.ref || 'origin/main', projectRoot);
+        break;
+
+      case 'gitLogShort':
+        rawResult = gitLogShort(pc.file || pc.path || '', projectRoot);
+        break;
+
+      default:
+        return `[precompute: unknown cmd "${String(cmd).slice(0, 40)}"]`;
+    }
+  } catch (e) {
+    // Surface error as result — guard still renders, just shows what went wrong
+    return `[precompute error: ${String(e.message).slice(0, 150)}]`;
+  }
+
+  return renderTemplate(pc.template || '{{result}}', rawResult);
+}
+
+// ── Batch Runner ────────────────────────────────────────────
+
+/**
+ * Run precompute for all guards that have a precompute field.
+ * Mutates each matching guard object by adding a `precompute_result` field.
+ *
+ * Budget enforcement:
+ *   - Skips remaining guards if TOTAL_BUDGET_MS exceeded
+ *   - Skips remaining guards if TOTAL_CAP bytes exceeded
+ *   - Per-command timeout enforced by execFileSync timeout option (1s)
+ *
+ * Note: Uses synchronous execution (execFileSync). Promise.all is used
+ * structurally for forward compatibility; true parallelism requires async
+ * fs/child_process APIs which can be introduced in a follow-up.
+ *
+ * @param {Array<object>} guards - guard objects from readBlindSpotGuards
+ * @param {object} taskData - current phase data (for when-condition evaluation)
+ * @param {string} projectRoot - absolute project root path
+ */
+function runPrecompute(guards, taskData, projectRoot) {
+  // Kill switch: skip all precompute
+  if (isDisabled()) {
+    return;
+  }
+
+  if (!Array.isArray(guards) || guards.length === 0) return;
+
+  const startMs = Date.now();
+  let totalOutput = 0;
+  let budgetExceeded = false;
+
+  for (const guard of guards) {
+    if (!guard.precompute) continue; // backward compat: guards without precompute unchanged
+
+    // Budget gate: check elapsed time
+    if (!budgetExceeded && (Date.now() - startMs) >= TOTAL_BUDGET_MS) {
+      budgetExceeded = true;
+      // Log warning to stderr (non-blocking — caller can inspect guard objects)
+      process.stderr.write('[precompute] WARN: total budget (3s) exceeded — remaining guards skipped\n');
+    }
+
+    if (budgetExceeded) {
+      guard.precompute_result = '[precompute: budget exceeded — skipped]';
+      continue;
+    }
+
+    // Total output cap gate
+    if (totalOutput >= TOTAL_CAP) {
+      guard.precompute_result = '[precompute: total output cap (4096 bytes) reached — skipped]';
+      continue;
+    }
+
+    const result = evaluateGuard(guard, taskData, projectRoot);
+
+    if (result !== null && result !== undefined) {
+      // Enforce total cap: trim result to fit remaining budget
+      const remaining = TOTAL_CAP - totalOutput;
+      if (result.length > remaining) {
+        guard.precompute_result = result.slice(0, remaining - 1) + '…';
+        totalOutput = TOTAL_CAP; // cap reached
+      } else {
+        guard.precompute_result = result;
+        totalOutput += result.length;
+      }
+    }
+  }
+}
+
+// ── Exports ─────────────────────────────────────────────────
+
+module.exports = {
+  // Primary API
+  runPrecompute,
+
+  // Named functions (exported for unit testing)
+  gitShowStat,
+  gitDiffStat,
+  grepCount,
+  wcLines,
+  fileExists,
+  gitCommitsAhead,
+  gitLogShort,
+
+  // Validators (exported for unit testing)
+  validateSha,
+  resolveFilePath,
+
+  // Helpers (exported for unit testing)
+  renderTemplate,
+  evaluateGuard,
+
+  // Constants (exported for unit testing)
+  TOTAL_BUDGET_MS,
+  PER_CMD_TIMEOUT_MS,
+  PER_GUARD_CAP,
+  TOTAL_CAP,
+};