@caoscompanybr/merlin 3.5.0

package/.merlin-core/core/execution/guardrail-engine.js

@@ -0,0 +1,745 @@
+/**
+ * Guardrail Engine -- 3-point agent execution guardrails
+ *
+ * Pre-execution validation, mid-execution monitoring, post-execution verification.
+ * Ensures agents operate within bounds and produce quality outputs.
+ *
+ * @module core/execution/guardrail-engine
+ * @version 3.0.0
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { EnvPreflight } = require("./env-preflight");
+const { SuccessVerifier } = require("./success-verifier");
+const { AttemptJournal } = require("./attempt-journal");
+// v3.3.1: single source of secret-detection patterns (shared with the certified-process pipeline)
+const { SECRET_PATTERNS } = require("../process/secret-scan");
+
+const KNOWN_AGENTS = [
+  "merlin-master",
+  "analyst",
+  "architect",
+  "dev",
+  "devops",
+  "pm",
+  "po",
+  "qa",
+  "sm",
+  "ux",
+  "data-engineer",
+  "researcher",
+  "scout",
+  "web-researcher",
+  "meta", // Meta-agent (System Optimizer)
+];
+
+/**
+ * Per-agent file restrictions.
+ * Agents with read_only cannot write. Agents with writable patterns
+ * can only modify files matching those globs.
+ * @constant
+ */
+const AGENT_FILE_RESTRICTIONS = {
+  scout: { readOnly: true },
+  researcher: { readOnly: true },
+  "web-researcher": { readOnly: true },
+  analyst: { writable: ["*.md", "thoughts/**"] },
+  architect: { writable: ["*.md", "thoughts/**"] },
+  pm: { writable: ["*.md", "thoughts/**"] },
+  po: { writable: ["*.md", "thoughts/**"] },
+  sm: { writable: ["*.md", "thoughts/**"] },
+  ux: {
+    writable: [
+      "*.md",
+      "*.css",
+      "*.scss",
+      "*.html",
+      "*.tsx",
+      "*.jsx",
+      "*.vue",
+      "*.svelte",
+    ],
+  },
+  dev: { writable: ["*"] },
+  devops: { writable: ["*"] },
+  qa: { writable: ["*.md", "*.test.*", "*.spec.*", "thoughts/**"] },
+  "data-engineer": { writable: ["*.sql", "*.py", "*.md", "thoughts/**"] },
+  "merlin-master": { writable: ["*"] },
+  meta: { writable: ["*.md", "thoughts/**", ".merlin-core/skills/**/*.md"] },
+};
+
+/**
+ * Protected files that require HIGH-stake approval to modify.
+ * CLAUDE.md is executable configuration — wrong paths poison every future session.
+ * @constant
+ */
+const PROTECTED_FILES = [
+  ".claude/CLAUDE.md",
+  ".claude/settings.json",
+  ".claude/rules/",
+];
+
+const MAX_OUTPUT_SIZE = 500000; // 500KB
+
+class GuardrailEngine {
+  /**
+   * @param {Object} [config]
+   * @param {string} [config.projectRoot]
+   * @param {number} [config.maxOutputSize]
+   * @param {number} [config.defaultTimeout=300000]
+   */
+  constructor(config = {}) {
+    this.projectRoot = config.projectRoot || process.cwd();
+    this.maxOutputSize = config.maxOutputSize || MAX_OUTPUT_SIZE;
+    this.defaultTimeout = config.defaultTimeout || 300000;
+
+    // v3.0.0 — Anti-retry-hell modules
+    this.envPreflight = new EnvPreflight({
+      projectRoot: this.projectRoot,
+      debug: config.debug,
+    });
+    this.successVerifier = new SuccessVerifier({
+      projectRoot: this.projectRoot,
+      debug: config.debug,
+    });
+    this.attemptJournal = new AttemptJournal({
+      debug: config.debug,
+    });
+  }
+
+  /**
+   * Pre-execution validation.
+   * Checks that the agent and task are valid before dispatch.
+   *
+   * @param {string} agentId - Agent identifier
+   * @param {Object} task - Task descriptor
+   * @returns {{passed: boolean, issues: Array<{type: string, message: string, severity: string}>}}
+   */
+  preCheck(agentId, task) {
+    const issues = [];
+
+    // 1. Agent exists
+    if (!agentId) {
+      issues.push({
+        type: "agent",
+        message: "No agent ID provided",
+        severity: "critical",
+      });
+    } else if (!KNOWN_AGENTS.includes(agentId)) {
+      issues.push({
+        type: "agent",
+        message: `Unknown agent: ${agentId}`,
+        severity: "high",
+      });
+    }
+
+    // 2. Task has required fields
+    if (!task) {
+      issues.push({
+        type: "task",
+        message: "No task provided",
+        severity: "critical",
+      });
+      return { passed: false, issues };
+    }
+
+    if (!task.id) {
+      issues.push({
+        type: "task",
+        message: "Task missing id field",
+        severity: "high",
+      });
+    }
+
+    if (!task.description) {
+      issues.push({
+        type: "task",
+        message: "Task missing description field",
+        severity: "medium",
+      });
+    }
+
+    // 3. File paths exist (if specified)
+    if (task.files && Array.isArray(task.files)) {
+      for (const file of task.files) {
+        const filePath = path.resolve(
+          path.isAbsolute(file) ? file : path.join(this.projectRoot, file),
+        );
+        // H10 fix: Prevent path traversal outside project root
+        if (!filePath.startsWith(path.resolve(this.projectRoot) + path.sep)) {
+          issues.push({
+            type: "file",
+            message: `Path traversal blocked: ${file}`,
+            severity: "critical",
+          });
+          continue;
+        }
+        if (!fs.existsSync(filePath)) {
+          issues.push({
+            type: "file",
+            message: `File not found: ${file}`,
+            severity: "medium",
+          });
+        }
+      }
+    }
+
+    // 4. File restriction check
+    if (agentId && task.files && Array.isArray(task.files)) {
+      const restriction = AGENT_FILE_RESTRICTIONS[agentId];
+      if (restriction) {
+        if (restriction.readOnly) {
+          issues.push({
+            type: "file_restriction",
+            message: `Agent "${agentId}" is read-only but task specifies files to modify`,
+            severity: "medium",
+          });
+        } else if (
+          restriction.writable &&
+          !restriction.writable.includes("*")
+        ) {
+          for (const file of task.files) {
+            if (!this._matchFileRestriction(file, restriction.writable)) {
+              issues.push({
+                type: "file_restriction",
+                message: `Agent "${agentId}" attempted write to "${file}" — restricted to [${restriction.writable.join(", ")}]`,
+                severity: "medium",
+              });
+            }
+          }
+        }
+      }
+    }
+
+    // 5. Protected file check — CLAUDE.md and .claude/ require HIGH approval
+    if (task.files && Array.isArray(task.files)) {
+      for (const file of task.files) {
+        const normalized = file.replace(/\\/g, "/").toLowerCase();
+        for (const pf of PROTECTED_FILES) {
+          if (normalized.includes(pf.toLowerCase())) {
+            issues.push({
+              type: "protected_file",
+              message:
+                `HIGH-STAKE: Modifying "${file}" requires explicit human approval. ` +
+                `CLAUDE.md is executable configuration — wrong paths poison every future session.`,
+              severity: "high",
+              action: "claude.md.modify",
+              file,
+            });
+          }
+        }
+      }
+    }
+
+    // 5b. Bulk deletion check (v2.11.1 — Constitution VII)
+    // Deletions of 50+ lines require explicit human approval
+    if (task.deletions) {
+      const totalDeleted = Array.isArray(task.deletions)
+        ? task.deletions.reduce((sum, d) => sum + (d.lines || 0), 0)
+        : task.deletions.lines || 0;
+
+      if (totalDeleted >= 50) {
+        issues.push({
+          type: "bulk_deletion",
+          message: `Bulk deletion detected: ${totalDeleted} lines will be removed. Requires explicit human approval (Constitution VII).`,
+          severity: "high",
+          action: "file.delete.bulk",
+          details: Array.isArray(task.deletions)
+            ? task.deletions
+            : [task.deletions],
+        });
+      }
+    }
+
+    // 5b. Directory deletion check (v2.11.1)
+    if (task.directoryDeletions && task.directoryDeletions.length > 0) {
+      issues.push({
+        type: "directory_deletion",
+        message: `Directory deletion detected: ${task.directoryDeletions.join(", ")}. Requires explicit human approval (Constitution VII).`,
+        severity: "high",
+        action: "file.delete.directory",
+        details: task.directoryDeletions,
+      });
+    }
+
+    // 6. Attempt journal check — block if approach is too similar to previous failure
+    if (task.id && task.approach) {
+      const approachCheck = this.attemptJournal.checkApproach(
+        task.id,
+        task.approach,
+      );
+      if (!approachCheck.allowed) {
+        issues.push({
+          type: "approach_blocked",
+          message: approachCheck.reason,
+          severity: "critical",
+          suggestions: approachCheck.suggestions,
+          similarAttempt: approachCheck.similarAttempt,
+        });
+      }
+    }
+
+    // 7. Must-escalate check — too many failed attempts
+    if (task.id && this.attemptJournal.mustEscalate(task.id)) {
+      issues.push({
+        type: "max_attempts_exceeded",
+        message: `Task ${task.id} has exceeded maximum retry attempts. Must escalate to human.`,
+        severity: "critical",
+        journal: this.attemptJournal.getSummary(task.id),
+      });
+    }
+
+    const hasCritical = issues.some((i) => i.severity === "critical");
+    return { passed: !hasCritical, issues };
+  }
+
+  /**
+   * Run environment preflight checks before execution.
+   * Call this BEFORE preCheck for environment validation.
+   *
+   * @param {Object} task - Task descriptor with optional outputPaths, requiredTools, apiEndpoints
+   * @returns {Promise<{passed: boolean, issues: Array}>}
+   */
+  async envPreflightCheck(task = {}) {
+    return this.envPreflight.run(task);
+  }
+
+  /**
+   * Mid-execution monitoring.
+   * Checks that the agent is operating within bounds during execution.
+   *
+   * @param {string} agentId - Agent identifier
+   * @param {Object} dispatchState - Current dispatch state
+   * @param {number} dispatchState.startTime - Dispatch start timestamp
+   * @param {number} [dispatchState.outputSize] - Current output size in bytes
+   * @param {string} [dispatchState.lastOutput] - Latest output fragment
+   * @returns {{passed: boolean, issues: Array, recommendation: string}}
+   */
+  midCheck(agentId, dispatchState) {
+    const issues = [];
+    let recommendation = "continue";
+
+    // 1. Elapsed time check
+    const elapsed = Date.now() - (dispatchState.startTime || Date.now());
+    const timeout = dispatchState.timeout || this.defaultTimeout;
+
+    if (elapsed > timeout * 0.9) {
+      issues.push({
+        type: "timeout",
+        message: `Agent ${agentId} at 90% timeout (${elapsed}ms / ${timeout}ms)`,
+        severity: "high",
+      });
+      recommendation = "warn";
+    }
+
+    if (elapsed > timeout) {
+      issues.push({
+        type: "timeout",
+        message: `Agent ${agentId} exceeded timeout`,
+        severity: "critical",
+      });
+      recommendation = "abort";
+    }
+
+    // 2. Output size check
+    if (
+      dispatchState.outputSize &&
+      dispatchState.outputSize > this.maxOutputSize
+    ) {
+      issues.push({
+        type: "output_size",
+        message: `Output exceeds ${this.maxOutputSize} bytes`,
+        severity: "high",
+      });
+      recommendation = "warn";
+    }
+
+    // 3. Error pattern detection
+    if (dispatchState.lastOutput) {
+      const errorPatterns = [
+        /FATAL ERROR/i,
+        /stack overflow/i,
+        /out of memory/i,
+        /SIGKILL/i,
+      ];
+      for (const pattern of errorPatterns) {
+        if (pattern.test(dispatchState.lastOutput)) {
+          issues.push({
+            type: "error_pattern",
+            message: `Detected error pattern: ${pattern.source}`,
+            severity: "critical",
+          });
+          recommendation = "abort";
+        }
+      }
+    }
+
+    return { passed: issues.length === 0, issues, recommendation };
+  }
+
+  /**
+   * Post-execution verification.
+   * Validates the result after agent completes.
+   *
+   * @param {string} agentId - Agent identifier
+   * @param {Object} result - Dispatch result
+   * @param {Object} task - Original task
+   * @returns {{passed: boolean, issues: Array, qualityScore: number}}
+   */
+  postCheck(agentId, result, task) {
+    const issues = [];
+    let qualityScore = 5.0;
+
+    // 1. Success check
+    if (!result || !result.success) {
+      issues.push({
+        type: "failure",
+        message: `Agent ${agentId} returned failure`,
+        severity: "high",
+      });
+      qualityScore -= 2.0;
+    }
+
+    // 2. Output non-empty
+    if (
+      !result.output ||
+      (typeof result.output === "string" && result.output.trim().length === 0)
+    ) {
+      issues.push({
+        type: "empty_output",
+        message: "Agent produced empty output",
+        severity: "high",
+      });
+      qualityScore -= 1.5;
+    }
+
+    // 3. Files modified match task.files (if applicable)
+    if (task.files && result.filesModified) {
+      const expected = new Set(task.files.map((f) => path.basename(f)));
+      const actual = new Set(result.filesModified.map((f) => path.basename(f)));
+      const missing = [...expected].filter((f) => !actual.has(f));
+
+      if (missing.length > 0) {
+        issues.push({
+          type: "missing_files",
+          message: `Expected files not modified: ${missing.join(", ")}`,
+          severity: "medium",
+        });
+        qualityScore -= 0.5;
+      }
+    }
+
+    // 4. Security check — no secrets in output
+    if (result.output && typeof result.output === "string") {
+      for (const pattern of SECRET_PATTERNS) {
+        pattern.lastIndex = 0;
+        if (pattern.test(result.output)) {
+          issues.push({
+            type: "secret_leak",
+            message: "Potential secret/credential detected in output",
+            severity: "critical",
+          });
+          qualityScore -= 3.0;
+        }
+      }
+    }
+
+    // 5. Objective completion check (Constitution VIII)
+    if (task.linked_objective && result.success) {
+      const objectives = task._sessionObjectives || [];
+      const obj = objectives.find((o) => o.id === task.linked_objective);
+      if (obj && obj.success_criteria) {
+        const output = (result.output || "").toLowerCase();
+        const unmet = obj.success_criteria.filter(
+          (c) => !output.includes(c.toLowerCase().split(" ")[0]),
+        );
+        if (unmet.length > 0) {
+          issues.push({
+            type: "objective_criteria_unmet",
+            message: `Task completed but ${unmet.length}/${obj.success_criteria.length} objective criteria may still need attention`,
+            severity: "medium",
+          });
+          qualityScore -= 0.5;
+        }
+      }
+    }
+
+    // 6. Learning detection — check for uncaptured learning signals
+    if (result.success && result.output && typeof result.output === "string") {
+      const learningSignals = this._detectLearningSignals(result.output);
+      if (learningSignals.length > 0) {
+        const hasLearningSection = /##\s*Learnings?/i.test(result.output);
+        if (!hasLearningSection) {
+          issues.push({
+            type: "uncaptured_learning",
+            message: `Detected ${learningSignals.length} learning signal(s) but no ## Learnings section in output: ${learningSignals.join(", ")}`,
+            severity: "low",
+          });
+        }
+      }
+    }
+
+    // 7. CLAUDE.md path validation — if agent modified CLAUDE.md, verify all referenced paths exist
+    if (result.filesModified && Array.isArray(result.filesModified)) {
+      const modifiedClaudeMd = result.filesModified.some((f) =>
+        f.toLowerCase().replace(/\\/g, "/").includes("claude.md"),
+      );
+      if (modifiedClaudeMd && result.output) {
+        const pathIssues = this._validateReferencedPaths(result.output);
+        if (pathIssues.length > 0) {
+          issues.push({
+            type: "claude_md_invalid_paths",
+            message:
+              `CLAUDE.md modified with ${pathIssues.length} invalid path(s): ${pathIssues.join(", ")}. ` +
+              `These paths do not exist on disk and will mislead future agents.`,
+            severity: "high",
+            paths: pathIssues,
+          });
+          qualityScore -= 2.0;
+        }
+      }
+    }
+
+    // 7b. Multi-signal success verification
+    const verification = this.successVerifier.verify(result, task);
+    if (!verification.verified) {
+      issues.push({
+        type: "multi_signal_failure",
+        message: `Success verification failed: only ${verification.passedCount}/${verification.totalCount} signals passed (need ${verification.minRequired})`,
+        severity: "high",
+        signals: verification.signals,
+        confidence: verification.confidence,
+      });
+      qualityScore -= 1.0;
+    }
+
+    // 8. Record attempt in journal (for future retry prevention)
+    if (task.id) {
+      const isSuccess =
+        !issues.some((i) => i.severity === "critical") && verification.verified;
+      this.attemptJournal.record(task.id, {
+        approach: task.approach || task.description || "unknown",
+        error: isSuccess ? null : issues.map((i) => i.message).join("; "),
+        rootCause: result?.rootCause || null,
+        learning: result?.learning || null,
+        success: isSuccess,
+        context: {
+          agentId,
+          qualityScore: Math.max(0, qualityScore),
+          signals: verification.signals?.map((s) => ({
+            type: s.type,
+            passed: s.passed,
+          })),
+        },
+      });
+
+      // Clear journal on success
+      if (isSuccess) {
+        this.attemptJournal.clear(task.id);
+      }
+    }
+
+    return {
+      passed: !issues.some((i) => i.severity === "critical"),
+      issues,
+      qualityScore: Math.max(0, qualityScore),
+      verification,
+    };
+  }
+
+  /**
+   * Detect learning-worthy signals in agent output.
+   *
+   * @param {string} output - Agent output text
+   * @returns {string[]} Detected signal descriptions
+   */
+  _detectLearningSignals(output) {
+    const signals = [];
+    const patterns = [
+      {
+        re: /(?:turns out|it turns out|discovered that|found that)\b/gi,
+        label: "discovery",
+      },
+      {
+        re: /(?:unexpected|surprisingly|counterintuitively)\b/gi,
+        label: "unexpected-behavior",
+      },
+      {
+        re: /(?:workaround|worked around|bypass|hack)\b/gi,
+        label: "workaround",
+      },
+      {
+        re: /(?:gotcha|pitfall|watch out|heads up|caveat)\b/gi,
+        label: "gotcha",
+      },
+      {
+        re: /(?:after (?:several|multiple|many|3\+?) (?:attempts|tries|retries))/gi,
+        label: "multi-step-debug",
+      },
+      {
+        re: /(?:root cause|the real issue|the actual problem)\b/gi,
+        label: "root-cause-found",
+      },
+    ];
+
+    for (const { re, label } of patterns) {
+      re.lastIndex = 0;
+      if (re.test(output)) {
+        signals.push(label);
+      }
+    }
+
+    return signals;
+  }
+
+  /**
+   * Validate paths referenced in CLAUDE.md content.
+   * Extracts directory/file paths from markdown and verifies they exist.
+   *
+   * @param {string} content - CLAUDE.md content or agent output containing paths
+   * @returns {string[]} Paths that don't exist on disk
+   * @private
+   */
+  _validateReferencedPaths(content) {
+    const invalidPaths = [];
+
+    // Match common path patterns in markdown: `path/to/file`, path/to/dir/
+    const pathPatterns = [
+      /`([a-zA-Z][\w./-]+\/[\w./-]+)`/g, // backtick-wrapped paths
+      /(?:^|\s)((?:src|lib|app|dist|public|\.merlin-core|\.claude|packages)\/[\w./-]+)/gm, // common project dirs
+    ];
+
+    const checked = new Set();
+    for (const re of pathPatterns) {
+      let match;
+      re.lastIndex = 0;
+      while ((match = re.exec(content)) !== null) {
+        const p = match[1];
+        if (checked.has(p) || p.length < 4 || p.length > 200) continue;
+        checked.add(p);
+
+        const fullPath = path.resolve(this.projectRoot, p);
+        // Only check paths that look like they're in the project
+        if (fullPath.startsWith(path.resolve(this.projectRoot))) {
+          if (!fs.existsSync(fullPath)) {
+            invalidPaths.push(p);
+          }
+        }
+      }
+    }
+
+    return invalidPaths;
+  }
+
+  /**
+   * Check if a file path matches any of the writable restriction patterns.
+   *
+   * @param {string} filePath - File path to check
+   * @param {string[]} patterns - Glob-like patterns (e.g., "*.md", "thoughts/**")
+   * @returns {boolean} True if file matches at least one pattern
+   * @private
+   */
+  _matchFileRestriction(filePath, patterns) {
+    const basename = path.basename(filePath);
+    for (const pattern of patterns) {
+      // Wildcard — matches everything
+      if (pattern === "*") return true;
+
+      // Extension glob: "*.md" or "*.test.*"
+      if (pattern.startsWith("*.")) {
+        const ext = pattern.substring(1); // ".md", ".test.*"
+        if (ext.endsWith(".*")) {
+          // Double extension pattern: "*.test.*"
+          const prefix = ext.slice(0, -2); // ".test"
+          if (basename.includes(prefix)) return true;
+        } else {
+          if (basename.endsWith(ext)) return true;
+        }
+      }
+
+      // Directory glob: "thoughts/**"
+      if (pattern.endsWith("/**")) {
+        const dirPrefix = pattern.slice(0, -3); // "thoughts"
+        if (
+          filePath.includes(dirPrefix + "/") ||
+          filePath.includes(dirPrefix + "\\")
+        )
+          return true;
+      }
+
+      // Nested glob: ".merlin-core/skills/**/*.md"
+      if (pattern.includes("**/")) {
+        const parts = pattern.split("**/");
+        const prefix = parts[0];
+        const suffix = parts[1] || "";
+        if (
+          filePath.includes(prefix) &&
+          (suffix === "" || basename.endsWith(suffix.replace("*", "")))
+        ) {
+          return true;
+        }
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Per-turn invariant check (Self-Correction Protocol).
+   * Validates that agent behavior follows expected invariants each turn.
+   *
+   * Invariants:
+   * - tools_used ⇒ status_update (if tools were used, agent should report status)
+   * - code_complete ⇒ test_run (if code was written, tests should be mentioned)
+   * - error_detected ⇒ retry_or_escalate (if error occurred, agent should react)
+   *
+   * @param {Object} turnData - Data from the current turn
+   * @param {string[]} [turnData.toolsUsed] - Tools invoked this turn
+   * @param {boolean} [turnData.codeWritten] - Whether code was written
+   * @param {boolean} [turnData.testRun] - Whether tests were executed
+   * @param {boolean} [turnData.statusReported] - Whether status was communicated
+   * @param {boolean} [turnData.errorDetected] - Whether an error was detected
+   * @param {boolean} [turnData.errorHandled] - Whether the error was addressed
+   * @returns {{passed: boolean, violations: Array<{invariant: string, message: string}>}}
+   */
+  turnCheck(turnData = {}) {
+    const violations = [];
+
+    // Invariant 1: tools_used ⇒ status_update
+    if (
+      turnData.toolsUsed &&
+      turnData.toolsUsed.length > 0 &&
+      !turnData.statusReported
+    ) {
+      violations.push({
+        invariant: "tools_used_status",
+        message: `Tools used (${turnData.toolsUsed.join(", ")}) but no status update reported`,
+      });
+    }
+
+    // Invariant 2: code_complete ⇒ test_run
+    if (turnData.codeWritten && !turnData.testRun) {
+      violations.push({
+        invariant: "code_complete_test",
+        message: "Code was written but tests were not run",
+      });
+    }
+
+    // Invariant 3: error_detected ⇒ retry_or_escalate
+    if (turnData.errorDetected && !turnData.errorHandled) {
+      violations.push({
+        invariant: "error_handling",
+        message: "Error detected but not handled (retry or escalate)",
+      });
+    }
+
+    return {
+      passed: violations.length === 0,
+      violations,
+    };
+  }
+}
+
+module.exports = { GuardrailEngine };