@caoscompanybr/merlin 3.5.0

package/.merlin-core/core/orchestration/workflow-executor.js

@@ -0,0 +1,864 @@
+/**
+ * Workflow Executor -- Executes workflow phases with state tracking
+ *
+ * Loads workflow definitions from YAML, executes phases sequentially,
+ * evaluates quality gates between phases, and persists execution state
+ * for crash recovery and resume.
+ *
+ * Merlin Framework — Gestao Merlin v3.0.0
+ *
+ * @module core/orchestration/workflow-executor
+ * @version 3.0.0
+ */
+
+"use strict";
+
+const fs = require("fs");
+const fsPromises = require("fs").promises;
+const path = require("path");
+const { StepLoader } = require("./step-loader");
+const { ReflectCheckpointEngine } = require("./reflect-checkpoint");
+const { eventBus } = require("../events/event-bus");
+const { GuardrailEngine } = require("../execution/guardrail-engine");
+
+/**
+ * Workflow phase status
+ * @enum {string}
+ */
+const PhaseStatus = {
+  PENDING: "pending",
+  RUNNING: "running",
+  COMPLETED: "completed",
+  FAILED: "failed",
+  SKIPPED: "skipped",
+};
+
+/**
+ * Checkpoint decision options
+ * @enum {string}
+ */
+const CheckpointDecision = {
+  GO: "GO",
+  PAUSE: "PAUSE",
+  REVIEW: "REVIEW",
+  ABORT: "ABORT",
+};
+
+/**
+ * Default execution timeout (2 hours)
+ * @constant {number}
+ */
+const DEFAULT_TIMEOUT_MS = 7200000;
+
+/**
+ * WorkflowExecutor -- Executes workflow phases sequentially with gate checks.
+ */
+class WorkflowExecutor {
+  /**
+   * @param {string} projectRoot - Project root directory
+   * @param {Object} [options] - Executor options
+   * @param {boolean} [options.debug=false] - Enable debug logging
+   * @param {boolean} [options.saveState=true] - Persist state to disk
+   * @param {Object} [options.gateEvaluator] - Custom GateEvaluator instance
+   * @param {Object} [options.agentInvoker] - Custom AgentInvoker instance
+   * @param {Object} [options.approvalEngine] - Custom ApprovalEngine instance
+   * @param {Object} [options.reflectCheckpoint] - Custom ReflectCheckpointEngine instance
+   */
+  constructor(projectRoot, options = {}) {
+    this.projectRoot = projectRoot;
+    this.options = {
+      debug: false,
+      saveState: true,
+      ...options,
+    };
+
+    // Paths
+    this.workflowsDir = path.join(
+      projectRoot,
+      ".merlin-core",
+      "development",
+      "workflows",
+    );
+    this.stateDir = path.join(projectRoot, ".merlin", "workflow-state");
+
+    // Runtime state
+    this.workflow = null;
+    this.state = null;
+
+    // Optional injected dependencies
+    this.gateEvaluator = options.gateEvaluator || null;
+    this.agentInvoker = options.agentInvoker || null;
+    this.approvalEngine = options.approvalEngine || null;
+
+    // Reflect checkpoint engine (mandatory reflections at phase transitions)
+    this.reflectCheckpoint =
+      options.reflectCheckpoint ||
+      new ReflectCheckpointEngine({ debug: this.options.debug });
+
+    // v3.0.0 — GuardrailEngine wired into AgentInvoker
+    this.guardrailEngine =
+      options.guardrailEngine ||
+      new GuardrailEngine({ projectRoot, debug: this.options.debug });
+    if (this.agentInvoker && !this.agentInvoker.guardrailEngine) {
+      this.agentInvoker.guardrailEngine = this.guardrailEngine;
+    }
+
+    // Knowledge provider for Knowledge-First Check
+    this.thoughtsProvider = options.thoughtsProvider || null;
+
+    // Step-file loader for JIT phase loading (BMAD pattern)
+    this.stepLoader = new StepLoader(projectRoot, {
+      debug: this.options.debug,
+    });
+
+    // Phase change callbacks for observability
+    this._phaseChangeCallbacks = [];
+    this._agentSpawnCallbacks = [];
+  }
+
+  /**
+   * Register a callback for phase change events.
+   * @param {Function} callback - (phase, workflowId, agent) => void
+   */
+  onPhaseChange(callback) {
+    if (typeof callback === "function") {
+      this._phaseChangeCallbacks.push(callback);
+    }
+  }
+
+  /**
+   * Register a callback for agent spawn events.
+   * @param {Function} callback - (agent, task) => void
+   */
+  onAgentSpawn(callback) {
+    if (typeof callback === "function") {
+      this._agentSpawnCallbacks.push(callback);
+    }
+  }
+
+  /**
+   * Load a workflow definition from YAML.
+   *
+   * @param {string} workflowId - Workflow file name (without extension)
+   * @returns {Promise<Object>} Parsed workflow definition
+   */
+  async loadWorkflow(workflowId) {
+    const filePath = path.join(this.workflowsDir, `${workflowId}.yaml`);
+
+    if (!fs.existsSync(filePath)) {
+      throw new Error(`Workflow not found: ${filePath}`);
+    }
+
+    const content = await fsPromises.readFile(filePath, "utf8");
+
+    // Simple YAML-like parsing for the workflow structure.
+    // In production, use js-yaml or similar.
+    this.workflow = {
+      id: workflowId,
+      raw: content,
+      loadedAt: new Date().toISOString(),
+    };
+
+    this._log(`Loaded workflow: ${workflowId}`);
+    return this.workflow;
+  }
+
+  /**
+   * Execute a workflow end-to-end.
+   *
+   * Runs each phase sequentially, evaluates gates between phases,
+   * and persists state after each phase transition.
+   *
+   * @param {string} workflowId - Workflow to execute
+   * @param {Object} [context={}] - Initial execution context
+   * @returns {Promise<Object>} Execution result
+   */
+  async execute(workflowId, context = {}) {
+    // Load workflow if not already loaded
+    if (!this.workflow || this.workflow.id !== workflowId) {
+      await this.loadWorkflow(workflowId);
+    }
+
+    // Initialize or resume state
+    await this._initState(workflowId, context);
+
+    this._log(`Executing workflow: ${workflowId}`);
+    eventBus.publish("workflow", "started", {
+      workflowId,
+      phases: this.state.phases,
+    });
+
+    const phases = this.state.phases;
+    let continueExecution = true;
+
+    while (continueExecution && this.state.currentPhaseIndex < phases.length) {
+      const phaseId = phases[this.state.currentPhaseIndex];
+      const phaseResult = await this._executePhase(phaseId, context);
+
+      // Record result
+      this.state.phaseResults[phaseId] = phaseResult;
+      this.state.lastUpdated = new Date().toISOString();
+      this._emitPhaseCompleted(phaseId, phaseResult);
+
+      if (phaseResult.status === PhaseStatus.FAILED) {
+        this._log(`Phase ${phaseId} failed: ${phaseResult.error}`);
+        continueExecution = false;
+      } else if (phaseResult.status === PhaseStatus.COMPLETED) {
+        // Run reflect checkpoint before gate evaluation
+        const nextIndex = this.state.currentPhaseIndex + 1;
+        const nextPhaseId =
+          nextIndex < phases.length ? phases[nextIndex] : null;
+        let reflectionInput = {};
+
+        if (nextPhaseId) {
+          const transitionKey = `${phaseId}_to_${nextPhaseId}`;
+          reflectionInput = this.reflectCheckpoint.runCheckpoint(
+            transitionKey,
+            phaseResult,
+            context,
+          );
+          this._log(
+            `Reflection [${transitionKey}]: passed=${reflectionInput.reflectionPassed}, ` +
+              `score=${reflectionInput.reflectionScore?.toFixed(2) || "N/A"}`,
+          );
+        }
+
+        // Merge reflection data into phase result for gate evaluation
+        const enrichedResult = {
+          ...phaseResult,
+          gateInput: reflectionInput,
+        };
+
+        // Evaluate gate before advancing
+        const gateResult = await this._evaluateGate(phaseId, enrichedResult);
+
+        if (gateResult && gateResult.verdict === "blocked") {
+          this._log(`Gate blocked after ${phaseId}`);
+          continueExecution = false;
+        } else if (gateResult && gateResult.verdict === "needs_revision") {
+          this._log(`Gate needs revision after ${phaseId}`);
+          // Stay on same phase for retry
+        } else {
+          // Request phase transition approval before advancing
+          const approved = await this._requestPhaseTransitionApproval(
+            phaseId,
+            nextPhaseId,
+          );
+          if (approved) {
+            this.state.currentPhaseIndex++;
+          } else {
+            this._log(`Phase transition ${phaseId} → ${nextPhaseId} denied`);
+            continueExecution = false;
+          }
+        }
+      } else if (phaseResult.status === PhaseStatus.SKIPPED) {
+        this.state.currentPhaseIndex++;
+      }
+
+      await this._saveState();
+    }
+
+    const allCompleted = this.state.currentPhaseIndex >= phases.length;
+    eventBus.publish("workflow", allCompleted ? "completed" : "stopped", {
+      workflowId,
+      success: allCompleted,
+      phasesCompleted: this.state.currentPhaseIndex,
+      totalPhases: phases.length,
+    });
+
+    return {
+      success: allCompleted,
+      workflowId,
+      state: this.state,
+      phaseResults: this.state.phaseResults,
+    };
+  }
+
+  /**
+   * Execute a single workflow phase.
+   *
+   * @param {string} phaseId - Phase identifier
+   * @param {Object} context - Execution context
+   * @returns {Promise<Object>} Phase result
+   * @private
+   */
+  async _executePhase(phaseId, context) {
+    this._log(`Executing phase: ${phaseId}`);
+
+    // v3.0.0 — Constitution III enforcement: implementation requires prior phases
+    if (this._isImplementationPhase(phaseId)) {
+      const prerequisiteCheck = this._checkPrerequisitePhases(phaseId);
+      if (!prerequisiteCheck.passed) {
+        this._log(
+          `BLOCKED: ${phaseId} cannot proceed — ${prerequisiteCheck.reason}`,
+        );
+        return {
+          status: PhaseStatus.FAILED,
+          error: prerequisiteCheck.reason,
+          completedAt: new Date().toISOString(),
+          blockedBy: "constitution-iii",
+        };
+      }
+    }
+
+    // JIT step-file loading: if workflow has step_files, load only the current step
+    if (this.workflow && this.stepLoader.isManifestFormat(this.workflow.id)) {
+      const stepDef = this.stepLoader.loadStepByIndex(
+        this.workflow.id,
+        this.state.currentPhaseIndex,
+      );
+      if (stepDef) {
+        context.stepDefinition = stepDef;
+        this._log(`JIT loaded step: ${stepDef.name || stepDef.id}`);
+      }
+    }
+
+    // Emit phase change
+    this._emitPhaseChange(phaseId);
+
+    this.state.phaseResults[phaseId] = {
+      status: PhaseStatus.RUNNING,
+      startedAt: new Date().toISOString(),
+    };
+    await this._saveState();
+
+    // Knowledge-First Check: pre-load relevant knowledge before research phases
+    if (
+      this.thoughtsProvider &&
+      phaseId === "research" &&
+      context.taskDescription
+    ) {
+      const knowledge = this.thoughtsProvider.hasRelevantKnowledge(
+        context.taskDescription,
+      );
+      if (knowledge.found) {
+        context.existingKnowledge = knowledge.entries;
+        context.knowledgeNote =
+          "Existing knowledge found — verify and extend, don't re-research from scratch.";
+        this._log(
+          `Knowledge-First: ${knowledge.entries.length} relevant entries pre-loaded (confidence: ${knowledge.confidence.toFixed(2)})`,
+        );
+      }
+    }
+
+    try {
+      // If we have an agent invoker, use it
+      if (this.agentInvoker) {
+        const agent = context.phaseAgents?.[phaseId] || "merlin-master";
+        this._emitAgentSpawn(agent, phaseId);
+
+        const result = await this.agentInvoker.invokeAgent(
+          agent,
+          {
+            name: phaseId,
+            description: `Execute phase: ${phaseId}`,
+            type: "workflow-phase",
+          },
+          { ...context, currentPhase: phaseId },
+        );
+
+        return {
+          status: result.success ? PhaseStatus.COMPLETED : PhaseStatus.FAILED,
+          output: result.output,
+          error: result.error,
+          completedAt: new Date().toISOString(),
+        };
+      }
+
+      // Default: return completed (placeholder for production integration)
+      return {
+        status: PhaseStatus.COMPLETED,
+        output: { message: `Phase ${phaseId} completed` },
+        completedAt: new Date().toISOString(),
+      };
+    } catch (error) {
+      return {
+        status: PhaseStatus.FAILED,
+        error: error.message,
+        completedAt: new Date().toISOString(),
+      };
+    }
+  }
+
+  /**
+   * Evaluate quality gate after a phase completes.
+   *
+   * @param {string} phaseId - Completed phase ID
+   * @param {Object} output - Phase output
+   * @returns {Promise<Object|null>} Gate result or null if no gate
+   * @private
+   */
+  async _evaluateGate(phaseId, output) {
+    if (!this.gateEvaluator) return null;
+
+    // Build gate key from current and next phase
+    const nextIndex = this.state.currentPhaseIndex + 1;
+    if (nextIndex >= this.state.phases.length) return null;
+
+    const nextPhaseId = this.state.phases[nextIndex];
+    const gateKey = `${phaseId}_to_${nextPhaseId}`;
+
+    this._log(`Evaluating gate: ${gateKey}`);
+    return this.gateEvaluator.evaluate(gateKey, output);
+  }
+
+  /**
+   * Initialize or load execution state.
+   *
+   * @param {string} workflowId - Workflow ID
+   * @param {Object} context - Execution context
+   * @private
+   */
+  async _initState(workflowId, context) {
+    // Try to load existing state
+    const existingState = await this._loadState(workflowId);
+    if (existingState) {
+      this.state = existingState;
+      this._log(
+        `Resumed state for ${workflowId} at phase index ${this.state.currentPhaseIndex}`,
+      );
+      return;
+    }
+
+    // Create new state
+    this.state = {
+      workflowId,
+      phases: context.phases || [
+        "research",
+        "architecture",
+        "implementation",
+        "review",
+        "deployment",
+      ],
+      currentPhaseIndex: 0,
+      phaseResults: {},
+      startedAt: new Date().toISOString(),
+      lastUpdated: new Date().toISOString(),
+    };
+
+    await this._saveState();
+  }
+
+  /**
+   * Save execution state to disk.
+   * @private
+   */
+  async _saveState() {
+    if (!this.options.saveState || !this.state) return;
+
+    try {
+      await fsPromises.mkdir(this.stateDir, { recursive: true });
+      const statePath = path.join(
+        this.stateDir,
+        `${this.state.workflowId}-state.json`,
+      );
+      await fsPromises.writeFile(
+        statePath,
+        JSON.stringify(this.state, null, 2),
+        "utf8",
+      );
+    } catch (error) {
+      this._log(`Failed to save state: ${error.message}`);
+    }
+  }
+
+  /**
+   * Load execution state from disk.
+   *
+   * @param {string} workflowId - Workflow ID
+   * @returns {Promise<Object|null>} State or null
+   * @private
+   */
+  async _loadState(workflowId) {
+    try {
+      const statePath = path.join(this.stateDir, `${workflowId}-state.json`);
+      if (!fs.existsSync(statePath)) return null;
+
+      const content = await fsPromises.readFile(statePath, "utf8");
+      return JSON.parse(content);
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Advance to the next phase manually.
+   * @returns {string|null} New phase ID or null if at end
+   */
+  async advancePhase() {
+    if (!this.state) return null;
+    if (this.state.currentPhaseIndex >= this.state.phases.length - 1)
+      return null;
+
+    this.state.currentPhaseIndex++;
+    const newPhase = this.state.phases[this.state.currentPhaseIndex];
+    await this._saveState();
+    return newPhase;
+  }
+
+  /**
+   * Get the current phase ID.
+   * @returns {string|null}
+   */
+  getCurrentPhase() {
+    if (!this.state) return null;
+    return this.state.phases[this.state.currentPhaseIndex] || null;
+  }
+
+  /**
+   * Get execution progress summary.
+   * @returns {Object} Progress with completed, total, percentage
+   */
+  getProgress() {
+    if (!this.state) {
+      return { completed: 0, total: 0, percentage: 0, currentPhase: null };
+    }
+
+    const completed = Object.values(this.state.phaseResults).filter(
+      (r) => r.status === PhaseStatus.COMPLETED,
+    ).length;
+    const total = this.state.phases.length;
+
+    return {
+      completed,
+      total,
+      percentage: total > 0 ? Math.round((completed / total) * 100) : 0,
+      currentPhase: this.getCurrentPhase(),
+    };
+  }
+
+  /**
+   * Request approval for a phase transition via the ApprovalEngine.
+   *
+   * If no ApprovalEngine is configured, transitions are auto-approved.
+   * Uses MEDIUM stake (auto-approved in YOLO mode).
+   *
+   * @param {string} fromPhase - Completed phase
+   * @param {string|null} toPhase - Next phase (null if last)
+   * @returns {Promise<boolean>} Whether transition was approved
+   * @private
+   */
+  async _requestPhaseTransitionApproval(fromPhase, toPhase) {
+    if (!toPhase) return true; // No next phase — nothing to approve
+    if (!this.approvalEngine) return true; // No engine — auto-approve
+
+    try {
+      const result = await this.approvalEngine.requestApproval(
+        "workflow.phase_transition",
+        {
+          description: `Transition from "${fromPhase}" to "${toPhase}"`,
+          agent: "workflow-executor",
+          metadata: {
+            fromPhase,
+            toPhase,
+            workflowId: this.state?.workflowId,
+          },
+        },
+      );
+      return result.approved;
+    } catch (error) {
+      this._log(`Approval request failed: ${error.message} — auto-approving`);
+      return true;
+    }
+  }
+
+  /**
+   * Emit phase change to all registered callbacks and the EventBus.
+   * @param {string} phase - Phase ID
+   * @private
+   */
+  _emitPhaseChange(phase) {
+    const eventData = {
+      phase,
+      workflowId: this.state?.workflowId,
+      phaseIndex: this.state?.currentPhaseIndex,
+    };
+
+    // EventBus publish — enables agent hooks
+    eventBus.publish("workflow", "phase-started", eventData);
+
+    for (const cb of this._phaseChangeCallbacks) {
+      try {
+        cb(phase, this.state?.workflowId, null);
+      } catch (error) {
+        this._log(`Phase change callback error: ${error.message}`);
+      }
+    }
+  }
+
+  /**
+   * Emit phase completion to the EventBus.
+   * @param {string} phase - Phase ID
+   * @param {Object} result - Phase result
+   * @private
+   */
+  _emitPhaseCompleted(phase, result) {
+    eventBus.publish("workflow", "phase-completed", {
+      phase,
+      workflowId: this.state?.workflowId,
+      status: result.status,
+      phaseIndex: this.state?.currentPhaseIndex,
+    });
+  }
+
+  /**
+   * Emit agent spawn to all registered callbacks and the EventBus.
+   * @param {string} agent - Agent ID
+   * @param {string} task - Task description
+   * @private
+   */
+  _emitAgentSpawn(agent, task) {
+    // EventBus publish
+    eventBus.publish("agent", "spawned", {
+      agentId: agent,
+      task,
+      workflowId: this.state?.workflowId,
+    });
+
+    for (const cb of this._agentSpawnCallbacks) {
+      try {
+        cb(agent, task);
+      } catch (error) {
+        this._log(`Agent spawn callback error: ${error.message}`);
+      }
+    }
+  }
+
+  /**
+   * Debug logger.
+   * @param {string} message
+   * @private
+   */
+  /**
+   * Execute a fast-path pipeline.
+   *
+   * Skips research/plan phases, dispatches directly to a single agent
+   * with minimal quality checks. Used for TRIVIAL/SIMPLE tasks where
+   * the full Folloni funnel is overkill.
+   *
+   * @param {Object} task - Task descriptor
+   * @param {string} agentId - Pre-selected agent from MasterOrchestrator.route()
+   * @param {Object} [options]
+   * @param {string} [options.brevity] - Brevity level (terse|brief|standard)
+   * @returns {Promise<Object>} Execution result
+   */
+  async executeFastPath(task, agentId, options = {}) {
+    this._log(`Fast-path execution: ${task.id || "anon"} → ${agentId}`);
+
+    // v3.0.0 — Constitution III: fast-path CANNOT bypass plan requirement
+    // for implementation tasks. Only discussion, research, and trivial
+    // queries may use fast-path.
+    if (this._taskRequiresImplementation(task)) {
+      const plansDir = path.join(
+        this.projectRoot,
+        ".merlin-core",
+        "thoughts",
+        "shared",
+        "plans",
+      );
+      const hasPlans =
+        fs.existsSync(plansDir) &&
+        fs
+          .readdirSync(plansDir)
+          .some((f) => f.endsWith(".md") && !f.startsWith("."));
+
+      if (!hasPlans) {
+        this._log(
+          "BLOCKED: Fast-path cannot bypass plan requirement for implementation tasks",
+        );
+        return {
+          success: false,
+          error:
+            "BLOCKED by Constitution III (Spec-Driven Development): " +
+            "Implementation detected but no plan exists in thoughts/shared/plans/. " +
+            "Fast-path cannot bypass the Folloni Funnel for implementation. " +
+            "Run /research then /plan first.",
+          fastPath: true,
+          agentId,
+          blockedBy: "constitution-iii",
+        };
+      }
+    }
+
+    eventBus.publish("workflow", "fast-path-started", {
+      taskId: task.id,
+      agentId,
+      brevity: options.brevity,
+    });
+
+    try {
+      if (this.agentInvoker) {
+        const result = await this.agentInvoker.invokeAgent(
+          agentId,
+          {
+            name: task.id || "fast-path",
+            description: task.description,
+            type: "fast-path",
+          },
+          {
+            currentPhase: "implementation",
+            brevity: options.brevity || "standard",
+            ...options,
+          },
+        );
+
+        eventBus.publish("workflow", "fast-path-completed", {
+          taskId: task.id,
+          success: result.success,
+        });
+
+        return {
+          success: result.success,
+          output: result.output,
+          error: result.error,
+          fastPath: true,
+          agentId,
+        };
+      }
+
+      // No agent invoker — return placeholder
+      return {
+        success: true,
+        output: { message: `Fast-path completed for ${task.id}` },
+        fastPath: true,
+        agentId,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: error.message,
+        fastPath: true,
+        agentId,
+      };
+    }
+  }
+
+  /**
+   * Check if a phase is an implementation phase.
+   * @param {string} phaseId
+   * @returns {boolean}
+   * @private
+   */
+  _isImplementationPhase(phaseId) {
+    return ["implementation", "build", "develop", "coding"].includes(
+      phaseId.toLowerCase(),
+    );
+  }
+
+  /**
+   * Check if prerequisite phases completed before implementation.
+   * Constitution III: Research -> Plan -> Implement
+   *
+   * @param {string} phaseId - Current phase
+   * @returns {{passed: boolean, reason: string}}
+   * @private
+   */
+  _checkPrerequisitePhases(phaseId) {
+    if (!this.state || !this.state.phaseResults) {
+      return { passed: true, reason: "No state — skip check" };
+    }
+
+    const phases = this.state.phases;
+
+    // Check if research phase exists and completed
+    const researchPhase = phases.find((p) =>
+      ["research", "discovery", "analysis"].includes(p.toLowerCase()),
+    );
+    if (researchPhase) {
+      const researchResult = this.state.phaseResults[researchPhase];
+      if (!researchResult || researchResult.status !== PhaseStatus.COMPLETED) {
+        return {
+          passed: false,
+          reason:
+            `BLOCKED: "${researchPhase}" phase must complete before "${phaseId}". ` +
+            "Constitution III requires: Research -> Plan -> Implement.",
+        };
+      }
+    }
+
+    // Check if architecture/planning phase exists and completed
+    const planPhase = phases.find((p) =>
+      ["architecture", "planning", "design", "plan"].includes(p.toLowerCase()),
+    );
+    if (planPhase) {
+      const planResult = this.state.phaseResults[planPhase];
+      if (!planResult || planResult.status !== PhaseStatus.COMPLETED) {
+        return {
+          passed: false,
+          reason:
+            `BLOCKED: "${planPhase}" phase must complete before "${phaseId}". ` +
+            "Constitution III requires: Research -> Plan -> Implement.",
+        };
+      }
+    }
+
+    // Check that a plan file actually exists on disk
+    try {
+      const plansDir = path.join(
+        this.projectRoot,
+        ".merlin-core",
+        "thoughts",
+        "shared",
+        "plans",
+      );
+      if (fs.existsSync(plansDir)) {
+        const plans = fs
+          .readdirSync(plansDir)
+          .filter((f) => f.endsWith(".md") && !f.startsWith("."));
+        if (plans.length === 0) {
+          return {
+            passed: false,
+            reason:
+              "BLOCKED: No plan file found in thoughts/shared/plans/. " +
+              "A plan must exist on disk before implementation begins. " +
+              "Run /plan to create one.",
+          };
+        }
+      }
+    } catch {
+      // Non-critical — skip disk check if unreadable
+    }
+
+    return { passed: true, reason: "All prerequisites met" };
+  }
+
+  /**
+   * Check if a task involves implementation (code writing).
+   * Used to block fast-path for implementation without plans.
+   *
+   * @param {Object} task
+   * @returns {boolean}
+   * @private
+   */
+  _taskRequiresImplementation(task) {
+    const desc = (task.description || "").toLowerCase();
+    const taskType = (task.type || "").toLowerCase();
+
+    // Explicit implementation type
+    if (
+      ["implementation", "feature", "bugfix", "refactor", "build"].includes(
+        taskType,
+      )
+    ) {
+      return true;
+    }
+
+    // Implementation keywords in description
+    const implKeywords =
+      /\b(implement|build|create|develop|code|write|add feature|fix bug|refactor)\b/;
+    return implKeywords.test(desc);
+  }
+
+  _log(message) {
+    if (this.options.debug) {
+      console.log(`[WorkflowExecutor] ${message}`);
+    }
+  }
+}
+
+module.exports = {
+  WorkflowExecutor,
+  PhaseStatus,
+  CheckpointDecision,
+  DEFAULT_TIMEOUT_MS,
+};