kenaz 0.3.18 → 0.3.20

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

@@ -1,85 +0,0 @@
-'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') || i.includes('synapse_')));
-  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, ['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/precompute-runner.js

@@ -1,444 +0,0 @@
-#!/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,
-};