@wazir-dev/cli 1.2.0 → 1.4.0

package/tooling/src/guards/guardrail-functions.js

@@ -0,0 +1,131 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function fileExistsAndNonEmpty(filePath) {
+  if (!fs.existsSync(filePath)) return false;
+  const stat = fs.statSync(filePath);
+  return stat.size > 0;
+}
+
+function result(passed, reason, missing = []) {
+  return { passed, reason, ...(missing.length > 0 ? { missing } : {}) };
+}
+
+// ---------------------------------------------------------------------------
+// Per-phase validators
+// ---------------------------------------------------------------------------
+
+const CLARIFY_ARTIFACTS = [
+  'clarified/clarification.md',
+  'clarified/spec-hardened.md',
+  'clarified/design.md',
+  'clarified/execution-plan.md',
+];
+
+/**
+ * Validates clarify phase produced all required artifacts.
+ */
+export function validateClarifyComplete(_state, runDir) {
+  const missing = [];
+  for (const relPath of CLARIFY_ARTIFACTS) {
+    const full = path.join(runDir, relPath);
+    if (!fileExistsAndNonEmpty(full)) {
+      missing.push(relPath);
+    }
+  }
+  if (missing.length > 0) {
+    return result(false, `Missing clarify artifacts: ${missing.join(', ')}`, missing);
+  }
+  return result(true, 'All clarify artifacts present and non-empty.');
+}
+
+/**
+ * Validates execute phase: at least one task artifact dir and verification proof.
+ */
+export function validateExecuteComplete(_state, runDir) {
+  const missing = [];
+  const artifactsDir = path.join(runDir, 'artifacts');
+
+  // Check for at least one task-NNN directory with content
+  const taskDirs = fs.existsSync(artifactsDir)
+    ? fs.readdirSync(artifactsDir).filter(d => d.startsWith('task-') && fs.statSync(path.join(artifactsDir, d)).isDirectory())
+    : [];
+
+  if (taskDirs.length === 0) {
+    missing.push('artifacts/task-NNN/ (no task artifacts found)');
+  }
+
+  // Check verification proof
+  const proofPath = path.join(artifactsDir, 'verification-proof.md');
+  if (!fileExistsAndNonEmpty(proofPath)) {
+    missing.push('artifacts/verification-proof.md');
+  }
+
+  if (missing.length > 0) {
+    return result(false, `Missing execute artifacts: ${missing.join(', ')}`, missing);
+  }
+  return result(true, `Execute complete: ${taskDirs.length} task(s) + verification proof.`);
+}
+
+/**
+ * Validates verify phase: proof exists and has substantive content.
+ */
+export function validateVerifyComplete(_state, runDir) {
+  const proofPath = path.join(runDir, 'artifacts', 'verification-proof.md');
+  if (!fileExistsAndNonEmpty(proofPath)) {
+    return result(false, 'Verification proof missing or empty.', ['artifacts/verification-proof.md']);
+  }
+
+  const content = fs.readFileSync(proofPath, 'utf8');
+  if (content.trim().length < 20) {
+    return result(false, 'Verification proof exists but has insufficient content.', ['artifacts/verification-proof.md']);
+  }
+
+  return result(true, 'Verification proof present with evidence.');
+}
+
+/**
+ * Validates review phase: verdict.json with a numeric score.
+ */
+export function validateReviewComplete(_state, runDir) {
+  const verdictPath = path.join(runDir, 'reviews', 'verdict.json');
+  if (!fs.existsSync(verdictPath)) {
+    return result(false, 'Review verdict missing.', ['reviews/verdict.json']);
+  }
+
+  try {
+    const verdict = JSON.parse(fs.readFileSync(verdictPath, 'utf8'));
+    if (typeof verdict.score !== 'number') {
+      return result(false, 'Review verdict has no numeric score.', ['reviews/verdict.json (missing score)']);
+    }
+    return result(true, `Review complete with score ${verdict.score}.`);
+  } catch {
+    return result(false, 'Review verdict is not valid JSON.', ['reviews/verdict.json']);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Dispatcher
+// ---------------------------------------------------------------------------
+
+const VALIDATORS = {
+  clarify: validateClarifyComplete,
+  execute: validateExecuteComplete,
+  verify: validateVerifyComplete,
+  review: validateReviewComplete,
+};
+
+/**
+ * Run the guardrail for a given phase.
+ */
+export function runGuardrail(phase, state, runDir) {
+  const validator = VALIDATORS[phase];
+  if (!validator) {
+    throw new Error(`Unknown phase for guardrail: ${phase}`);
+  }
+  return validator(state, runDir);
+}

package/tooling/src/guards/phase-prerequisite-guard.js

@@ -4,6 +4,64 @@ import path from 'node:path';
 import { readYamlFile } from '../loaders.js';
 import { getRunPaths, readPhaseExitEvents } from '../capture/store.js';
 
+/**
+ * Validates that every enabled workflow has a phase_exit event
+ * in the run's events.ndjson before the run can be marked complete.
+ *
+ * If a run-config with workflow_policy exists, only workflows with
+ * enabled: true are checked. Otherwise falls back to the manifest list.
+ */
+export function validateRunCompletion(runDir, manifestPath) {
+  const manifest = readYamlFile(manifestPath);
+  const declaredWorkflows = manifest.workflows ?? [];
+
+  if (declaredWorkflows.length === 0) {
+    return { complete: true, missing: [] };
+  }
+
+  // Filter to enabled workflows if run-config exists
+  const runConfigPath = path.join(runDir, 'run-config.yaml');
+  let enabledWorkflows = declaredWorkflows;
+  if (fs.existsSync(runConfigPath)) {
+    try {
+      const runConfig = readYamlFile(runConfigPath);
+      const policy = runConfig.workflow_policy;
+      if (policy && typeof policy === 'object') {
+        enabledWorkflows = declaredWorkflows.filter(w => {
+          const wPolicy = policy[w] ?? policy[w.replace(/_/g, '-')];
+          // If no policy entry, assume enabled; if entry exists, check enabled field
+          return wPolicy ? (wPolicy.enabled !== false) : true;
+        });
+      }
+    } catch {
+      // If run-config can't be read, fall back to full manifest list
+    }
+  }
+
+  const eventsPath = path.join(runDir, 'events.ndjson');
+  const completedWorkflows = new Set();
+
+  if (fs.existsSync(eventsPath)) {
+    const content = fs.readFileSync(eventsPath, 'utf8');
+    for (const line of content.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      try {
+        const event = JSON.parse(trimmed);
+        if (event.event === 'phase_exit' && event.status === 'completed' && event.phase) {
+          completedWorkflows.add(event.phase);
+        }
+      } catch {
+        // Skip malformed lines
+      }
+    }
+  }
+
+  const missing = enabledWorkflows.filter(w => !completedWorkflows.has(w));
+
+  return { complete: missing.length === 0, missing };
+}
+
 export function evaluateScopeCoverageGuard(payload) {
   const { input_item_count: inputCount, plan_task_count: planCount, user_approved_reduction: userApproved } = payload;
 
@@ -85,10 +143,42 @@ export function evaluatePhasePrerequisiteGuard(payload) {
   const requiredPhaseExits = prerequisites.required_phase_exits ?? [];
 
   const missingArtifacts = [];
+  const failedProofs = [];
   for (const artifact of requiredArtifacts) {
     const artifactPath = path.join(runPaths.runRoot, artifact);
     if (!fs.existsSync(artifactPath)) {
       missingArtifacts.push(artifact);
+      continue;
+    }
+
+    const basename = path.basename(artifact);
+
+    // Content validation for proof JSON files (e.g. proof-task-001.json, verification-proof.json)
+    if (basename.includes('proof') && basename.endsWith('.json')) {
+      try {
+        const content = fs.readFileSync(artifactPath, 'utf8');
+        const parsed = JSON.parse(content);
+        if (parsed.all_passed !== true) {
+          failedProofs.push(`${artifact}: all_passed is not true (got ${JSON.stringify(parsed.all_passed)})`);
+        }
+      } catch {
+        // Fail closed: malformed JSON blocks the phase
+        failedProofs.push(`${artifact}: malformed or unreadable JSON`);
+      }
+      continue;
+    }
+
+    // Content validation for verification-proof.md
+    if (basename === 'verification-proof.md') {
+      try {
+        const content = fs.readFileSync(artifactPath, 'utf8');
+        const lower = content.toLowerCase();
+        if (!lower.includes('status: pass') && !content.includes('PASS')) {
+          failedProofs.push(`${artifact}: does not contain "status: pass" or "PASS"`);
+        }
+      } catch {
+        failedProofs.push(`${artifact}: unreadable`);
+      }
     }
   }
 
@@ -100,10 +190,10 @@ export function evaluatePhasePrerequisiteGuard(payload) {
     }
   }
 
-  // OR-logic for resumed runs: if all artifacts exist, pass even without phase_exit events.
+  // OR-logic for resumed runs: if all artifacts exist and proofs pass, allow even without phase_exit events.
   // Artifacts are the hard evidence; phase_exits are supplementary.
-  // But if artifacts are missing, phase_exits alone are not sufficient.
-  if (missingArtifacts.length === 0) {
+  // But if artifacts are missing or proofs fail, phase_exits alone are not sufficient.
+  if (missingArtifacts.length === 0 && failedProofs.length === 0) {
     return {
       allowed: true,
       reason: `All prerequisite artifacts present for phase ${phase}.`,
@@ -114,6 +204,9 @@ export function evaluatePhasePrerequisiteGuard(payload) {
   if (missingArtifacts.length > 0) {
     reasons.push(`Missing artifacts: ${missingArtifacts.join(', ')}`);
   }
+  if (failedProofs.length > 0) {
+    reasons.push(`Failed proof validation: ${failedProofs.join('; ')}`);
+  }
   if (missingPhaseExits.length > 0) {
     reasons.push(`Missing phase exits: ${missingPhaseExits.join(', ')}`);
   }
@@ -122,6 +215,7 @@ export function evaluatePhasePrerequisiteGuard(payload) {
     allowed: false,
     reason: reasons.join('. '),
     missing_artifacts: missingArtifacts.length > 0 ? missingArtifacts : undefined,
+    failed_proofs: failedProofs.length > 0 ? failedProofs : undefined,
     missing_phase_exits: missingPhaseExits.length > 0 ? missingPhaseExits : undefined,
   };
 }

package/tooling/src/hooks/pretooluse-dispatcher.js

@@ -0,0 +1,300 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { readPipelineState } from '../state/pipeline-state.js';
+import { readYamlFile } from '../loaders.js';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const ALWAYS_ALLOWED_TOOLS = new Set([
+  'Read', 'Grep', 'Glob', 'Agent', 'Skill',
+  'TaskCreate', 'TaskUpdate', 'TaskList', 'TaskGet',
+]);
+
+const WRITE_BLOCKED_PHASES = new Set(['clarify', 'verify', 'review']);
+const GIT_BLOCKED_PHASES = new Set(['init', 'clarify', 'verify', 'review']);
+const UNRESTRICTED_PHASES = new Set(['init', 'execute', 'complete']);
+
+const GIT_MUTATING_PATTERNS = [
+  /^git\s+commit/,
+  /^git\s+push/,
+  /^git\s+merge/,
+  /^git\s+rebase/,
+  /^git\s+reset/,
+  /^git\s+checkout\s+--/,
+];
+
+const DEFAULT_ROUTING_MATRIX = {
+  large: ['npm test', 'vitest', 'jest', 'pytest', 'npm run build', 'tsc --noEmit', 'npm ls', 'pip list', 'eslint .', 'prettier --check .', 'tail -f'],
+  small: ['git status', 'git log', 'git branch', 'git rev-parse', 'ls', 'pwd', 'mkdir', 'cp', 'mv', 'rm', 'wazir doctor', 'wazir index', 'wazir capture', 'wazir validate', 'which', 'echo'],
+  ambiguous_heuristic: { pipe_detected: true, redirect_detected: true, verbose_binaries: ['find', 'rg', 'grep', 'awk', 'sed', 'curl'] },
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function isWazirPath(filePath) {
+  if (!filePath) return false;
+  return filePath.includes('.wazir/') || filePath.includes('/.wazir');
+}
+
+function isWazirCommand(command) {
+  if (!command) return false;
+  const trimmed = command.trim();
+  return trimmed.startsWith('wazir ') || trimmed === 'wazir';
+}
+
+function isGitMutating(command) {
+  if (!command) return false;
+  const trimmed = command.trim();
+  return GIT_MUTATING_PATTERNS.some(pattern => pattern.test(trimmed));
+}
+
+// ---------------------------------------------------------------------------
+// Protected path check
+// ---------------------------------------------------------------------------
+
+const APPROVED_FLOWS = new Set([
+  'host_export_regeneration',
+  'pipeline_integration',
+]);
+
+function checkProtectedPath(projectRoot, filePath, approvedFlow) {
+  if (!filePath || !projectRoot) return null;
+
+  let manifest;
+  try {
+    manifest = readYamlFile(path.join(projectRoot, 'wazir.manifest.yaml'));
+  } catch {
+    // If manifest can't be read, block writes defensively
+    return { decision: 'deny', reason: 'Cannot read manifest to check protected paths.' };
+  }
+
+  if (!manifest?.protected_paths) return null;
+
+  const absoluteTarget = path.isAbsolute(filePath)
+    ? path.resolve(filePath)
+    : path.resolve(projectRoot, filePath);
+  const relTarget = path.relative(projectRoot, absoluteTarget);
+
+  // Outside project = not protected
+  if (relTarget === '..' || relTarget.startsWith(`..${path.sep}`) || path.isAbsolute(relTarget)) {
+    return null;
+  }
+
+  const blocked = manifest.protected_paths.find(
+    (pp) => relTarget === pp || relTarget.startsWith(`${pp}${path.sep}`),
+  );
+
+  if (blocked) {
+    // Check approved flow override
+    if (APPROVED_FLOWS.has(approvedFlow)) {
+      return null; // approved flow may write protected paths
+    }
+    return { decision: 'deny', reason: `Protected path blocked: ${relTarget}` };
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Context-mode classification
+// ---------------------------------------------------------------------------
+
+function classifyCommand(cmd, matrix) {
+  if (!cmd) return { category: 'small', reason: 'empty command' };
+
+  if (cmd.includes('# wazir:context-mode')) return { category: 'large', reason: 'explicit marker' };
+
+  for (const pattern of matrix.large) {
+    if (cmd === pattern || cmd.startsWith(pattern + ' ') || cmd.startsWith(pattern + '\t')) {
+      return { category: 'large', reason: `matched pattern: ${pattern}` };
+    }
+  }
+
+  if (cmd.includes('# wazir:passthrough')) return { category: 'small', reason: 'passthrough marker' };
+
+  for (const pattern of matrix.small) {
+    if (cmd === pattern || cmd.startsWith(pattern + ' ') || cmd.startsWith(pattern + '\t')) {
+      return { category: 'small', reason: `matched pattern: ${pattern}` };
+    }
+  }
+
+  const heuristic = matrix.ambiguous_heuristic || {};
+  if (heuristic.pipe_detected && /(?<![\\])\|/.test(cmd)) {
+    return { category: 'ambiguous', reason: 'pipe detected' };
+  }
+  if (heuristic.redirect_detected && /(?<![\\])>/.test(cmd)) {
+    return { category: 'ambiguous', reason: 'redirect detected' };
+  }
+
+  const bin = cmd.split(/\s+/)[0] || '';
+  if (Array.isArray(heuristic.verbose_binaries) && heuristic.verbose_binaries.includes(bin)) {
+    return { category: 'ambiguous', reason: `verbose binary: ${bin}` };
+  }
+
+  return { category: 'small', reason: 'no pattern matched' };
+}
+
+// ---------------------------------------------------------------------------
+// Load routing matrix
+// ---------------------------------------------------------------------------
+
+function loadRoutingMatrix(projectRoot) {
+  try {
+    const matrixPath = path.join(projectRoot, 'hooks', 'routing-matrix.json');
+    return JSON.parse(fs.readFileSync(matrixPath, 'utf8'));
+  } catch {
+    return DEFAULT_ROUTING_MATRIX;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main evaluation — consolidates all three PreToolUse concerns
+// ---------------------------------------------------------------------------
+
+/**
+ * Consolidated PreToolUse dispatcher.
+ *
+ * Evaluation order:
+ * 1. Always-allowed tools (reads, task tools)
+ * 2. .wazir/ path writes (pipeline state)
+ * 3. wazir CLI commands
+ * 4. No state = allow all
+ * 5. Protected path check (manifest protected_paths)
+ * 6. Phase restriction check (write/git blocks)
+ * 7. Context-mode routing (Bash classification)
+ *
+ * @param {string} stateRoot   — pipeline state directory
+ * @param {string} projectRoot — project root directory
+ * @param {object} hookInput   — { tool, input }
+ * @returns {{ decision: 'allow'|'deny', reason?: string, routing_decision?: object }}
+ */
+export function evaluateDispatch(stateRoot, projectRoot, hookInput) {
+  const { tool, input = {} } = hookInput;
+
+  // 1. Always-allowed tools
+  if (ALWAYS_ALLOWED_TOOLS.has(tool)) {
+    return { decision: 'allow' };
+  }
+
+  // 2. .wazir/ path writes always allowed
+  if ((tool === 'Write' || tool === 'Edit') && isWazirPath(input.file_path)) {
+    return { decision: 'allow' };
+  }
+
+  // 3. wazir CLI commands always allowed
+  if (tool === 'Bash' && isWazirCommand(input.command)) {
+    return { decision: 'allow' };
+  }
+
+  // 4. Protected path check (Write/Edit only — always enforced regardless of phase)
+  if (tool === 'Write' || tool === 'Edit') {
+    const protectedResult = checkProtectedPath(projectRoot, input.file_path, input.approved_flow);
+    if (protectedResult) return protectedResult;
+  }
+
+  // 5. No state file = not a pipeline session = allow
+  let state;
+  try {
+    state = readPipelineState(stateRoot);
+  } catch {
+    return { decision: 'allow' };
+  }
+  if (!state || !state.current_phase) {
+    return { decision: 'allow' };
+  }
+
+  const phase = state.current_phase;
+
+  // 6. Unrestricted phases
+  if (UNRESTRICTED_PHASES.has(phase)) {
+    return addRoutingIfBash(tool, input, projectRoot);
+  }
+
+  // 7. Phase-based Write/Edit restriction
+  if ((tool === 'Write' || tool === 'Edit') && WRITE_BLOCKED_PHASES.has(phase)) {
+    return {
+      decision: 'deny',
+      reason: `Write/Edit blocked during "${phase}" phase. This phase is read-only for project files. Only .wazir/ writes are allowed.`,
+    };
+  }
+
+  // 8. Phase-based git mutation restriction
+  if (tool === 'Bash' && GIT_BLOCKED_PHASES.has(phase) && isGitMutating(input.command)) {
+    return {
+      decision: 'deny',
+      reason: `Git mutations (commit/push) blocked during "${phase}" phase. Git commits are only allowed during the execute phase.`,
+    };
+  }
+
+  // 9. Context-mode routing for Bash
+  return addRoutingIfBash(tool, input, projectRoot);
+}
+
+function isContextModeEnabled(projectRoot) {
+  const envVal = process.env.WAZIR_CONTEXT_MODE;
+  if (envVal !== undefined) return envVal === '1' || envVal === 'true';
+
+  try {
+    const manifestPath = path.join(projectRoot, 'wazir.manifest.yaml');
+    const manifestText = fs.readFileSync(manifestPath, 'utf8');
+    const match = manifestText.match(/context_mode:[\s\S]*?enabled_by_default:\s*(true|false)/);
+    if (match) return match[1] === 'true';
+  } catch { /* ignore */ }
+
+  return false;
+}
+
+function addRoutingIfBash(tool, input, projectRoot) {
+  if (tool === 'Bash') {
+    const matrix = loadRoutingMatrix(projectRoot);
+    const cmd = (input.command || '').trim();
+    const classification = classifyCommand(cmd, matrix);
+    const contextModeEnabled = isContextModeEnabled(projectRoot);
+
+    let route = 'passthrough';
+    if (contextModeEnabled && (classification.category === 'large' || classification.category === 'ambiguous')) {
+      route = 'context-mode';
+    }
+
+    const routing_decision = {
+      command: cmd,
+      category: classification.category,
+      reason: classification.reason,
+      route,
+      context_mode_enabled: contextModeEnabled,
+    };
+    return { decision: 'allow', routing_decision };
+  }
+  return { decision: 'allow' };
+}
+
+// ---------------------------------------------------------------------------
+// CLI entry point
+// ---------------------------------------------------------------------------
+
+const isDirectRun = process.argv[1] && import.meta.url.endsWith(process.argv[1].replace(/\\/g, '/'));
+
+if (isDirectRun) {
+  const stateRoot = process.argv[2] || process.env.WAZIR_STATE_ROOT;
+  const projectRoot = process.argv[3] || process.env.WAZIR_PROJECT_ROOT || process.cwd();
+
+  let hookInput = {};
+  try {
+    const stdin = fs.readFileSync(0, 'utf8').trim();
+    if (stdin) hookInput = JSON.parse(stdin);
+  } catch { /* no stdin */ }
+
+  if (!stateRoot) {
+    console.log(JSON.stringify({ decision: 'allow' }));
+    process.exit(0);
+  }
+
+  const result = evaluateDispatch(stateRoot, projectRoot, hookInput);
+  console.log(JSON.stringify(result));
+  process.exit(0);
+}