oxe-cc 1.10.0 → 1.11.0

package/bin/lib/oxe-operational.cjs

@@ -86,6 +86,19 @@ function createExecutionContext(projectRoot, activeSession, options = {}) {
   const gateManager = (runtime && typeof runtime.GateManager === 'function')
     ? new runtime.GateManager(projectRoot, activeSession || null, runId)
     : null;
+  // Auto-wire PolicyEngine from .oxe/config.json runtime.policy when not explicitly injected
+  let policyEngine = options.policyEngine || null;
+  if (!policyEngine && runtime && typeof runtime.PolicyEngine === 'function') {
+    try {
+      const cfgPath = path.join(projectRoot, '.oxe', 'config.json');
+      if (fs.existsSync(cfgPath)) {
+        const cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
+        if (cfg.runtime && cfg.runtime.policy && typeof cfg.runtime.policy === 'object') {
+          policyEngine = runtime.PolicyEngine.fromConfig(cfg.runtime.policy);
+        }
+      }
+    } catch {}
+  }
   return {
     projectRoot,
     sessionId: activeSession || null,
@@ -93,7 +106,7 @@ function createExecutionContext(projectRoot, activeSession, options = {}) {
     executor: options.executor || null,
     workspaceManager: options.workspaceManager || null,
     gateManager,
-    policyEngine: options.policyEngine || null,
+    policyEngine,
     policyActor: options.policyActor || 'runtime',
     quota: options.quota || null,
     pluginRegistry: options.pluginRegistry || null,
@@ -104,6 +117,44 @@ function createExecutionContext(projectRoot, activeSession, options = {}) {
   };
 }
 
+/**
+ * Persists LLM provider config to .oxe/config.json under runtime.provider.
+ * @param {string} projectRoot
+ * @param {{ baseUrl?: string, model?: string, apiKeyEnv?: string, maxTurns?: number }} providerConfig
+ */
+function saveRuntimeProviderConfig(projectRoot, providerConfig) {
+  const configPath = path.join(projectRoot, '.oxe', 'config.json');
+  let cfg = {};
+  try { cfg = JSON.parse(fs.readFileSync(configPath, 'utf8')); } catch {}
+  if (!cfg.runtime || typeof cfg.runtime !== 'object') cfg.runtime = {};
+  cfg.runtime.provider = {
+    baseUrl: providerConfig.baseUrl || 'https://api.anthropic.com/v1',
+    model: providerConfig.model || 'claude-sonnet-4-6',
+  };
+  if (providerConfig.apiKeyEnv) cfg.runtime.provider.apiKeyEnv = providerConfig.apiKeyEnv;
+  if (providerConfig.maxTurns != null) cfg.runtime.provider.maxTurns = providerConfig.maxTurns;
+  const oxeDir = path.join(projectRoot, '.oxe');
+  if (!fs.existsSync(oxeDir)) fs.mkdirSync(oxeDir, { recursive: true });
+  fs.writeFileSync(configPath, JSON.stringify(cfg, null, 2) + '\n', 'utf8');
+  return cfg.runtime.provider;
+}
+
+/**
+ * Reads persisted LLM provider config from .oxe/config.json runtime.provider.
+ * @param {string} projectRoot
+ * @returns {{ baseUrl?: string, model?: string, apiKeyEnv?: string, maxTurns?: number } | null}
+ */
+function loadRuntimeProviderConfig(projectRoot) {
+  try {
+    const cfg = JSON.parse(fs.readFileSync(path.join(projectRoot, '.oxe', 'config.json'), 'utf8'));
+    return (cfg.runtime && cfg.runtime.provider && typeof cfg.runtime.provider === 'object')
+      ? cfg.runtime.provider
+      : null;
+  } catch {
+    return null;
+  }
+}
+
 function buildRuntimePluginRegistry(projectRoot) {
   const runtime = loadRuntimeModule();
   if (!runtime || typeof runtime.PluginRegistry !== 'function') return null;
@@ -535,6 +586,37 @@ function compileExecutionGraphFromArtifacts(projectRoot, activeSession, options
   if (lintHints.length) validationErrors.push(...lintHints);
 
   const compiledGraph = runtime.toSerializable(graph);
+
+  // Gap B: enrich node verify.command from SPEC criteria howToVerify when linked via acceptance_refs.
+  // Extracts commands from backtick patterns (e.g. "Run `npm test`") and appends to existing command
+  // or sets as command when none exists. Only runs when spec has criteria.
+  if (parsedSpec.criteria && parsedSpec.criteria.length > 0 && compiledGraph.nodes) {
+    const criteriaMap = new Map(parsedSpec.criteria.map(c => [c.id, c]));
+    const nodeList = Array.isArray(compiledGraph.nodes)
+      ? compiledGraph.nodes
+      : Object.values(compiledGraph.nodes);
+    for (const node of nodeList) {
+      if (!node || !node.verify) continue;
+      const refs = Array.isArray(node.verify.acceptance_refs) ? node.verify.acceptance_refs : [];
+      const criteriaCommands = [];
+      for (const ref of refs) {
+        const criterion = criteriaMap.get(ref);
+        if (criterion && criterion.howToVerify) {
+          const cmdMatch = criterion.howToVerify.match(/`([^`]+)`/);
+          if (cmdMatch) criteriaCommands.push(cmdMatch[1].trim());
+        }
+      }
+      if (criteriaCommands.length === 0) continue;
+      const unique = [...new Set(criteriaCommands)];
+      if (node.verify.command) {
+        const extra = unique.filter(c => !node.verify.command.includes(c));
+        if (extra.length > 0) node.verify.command += ' && ' + extra.join(' && ');
+      } else {
+        node.verify.command = unique.join(' && ');
+      }
+    }
+  }
+
   const current = options.runState || readRunState(projectRoot, activeSession) || {};
   const runId = current.run_id || makeRunId();
   const next = writeRunState(projectRoot, activeSession, {
@@ -722,52 +804,52 @@ async function resolveRuntimeGate(projectRoot, activeSession, options = {}) {
   };
 }
 
-  // Gap 5: route execution to MultiAgentCoordinator when plan-agents.json exists
-function buildRuntimeExecutePreflight(projectRoot, activeSession, runState) {
-    const health = loadProjectHealth();
-    const blockers = [];
-    const warnings = [];
-    let report = null;
-    if (health && typeof health.buildHealthReport === 'function') {
-      report = health.buildHealthReport(projectRoot);
-      if (report.planSelfEvaluation && report.planSelfEvaluation.executable === false) {
-        const confidence = report.planSelfEvaluation.confidence;
-        const threshold = report.planConfidenceThreshold || 90;
-        blockers.push(`plan_confidence:${confidence == null ? 'missing' : `${confidence}%`}<=${threshold}%`);
-      }
-      if (report.executionRationality && report.executionRationality.applicable && !report.executionRationalityReady) {
-        const gaps = Array.isArray(report.criticalExecutionGaps) ? report.criticalExecutionGaps : [];
-        blockers.push(`execution_rationality:${gaps[0] || 'not_ready'}`);
-      }
-      if (report.fallbackMode && report.fallbackMode !== 'none') {
-        warnings.push(`fallback_mode:${report.fallbackMode}`);
-      }
-    } else {
-      warnings.push('health_report_unavailable');
-    }
-    const runId = runState && runState.run_id ? runState.run_id : null;
-    const queue = readRuntimeGates(projectRoot, activeSession, { runId });
-    if (queue.pending.length > 0) {
-      blockers.push(`pending_gates:${queue.pending.length}`);
-    }
-    return {
-      ok: blockers.length === 0,
-      blockers,
-      warnings,
-      runId,
-      gateQueue: {
-        pending: queue.pending.length,
-        stale: queue.staleCount || 0,
-      },
-      confidence: report && report.planSelfEvaluation ? report.planSelfEvaluation.confidence : null,
-      confidenceThreshold: report ? report.planConfidenceThreshold || 90 : 90,
-      executionRationalityReady: report ? Boolean(report.executionRationalityReady) : false,
-    };
-  }
-
-  async function runRuntimeExecute(projectRoot, activeSession, options = {}) {
-    const runtime = loadRuntimeModule();
-    if (!runtime) throw new Error('Runtime package não está disponível. Rode npm run build:runtime.');
+  // Gap 5: route execution to MultiAgentCoordinator when plan-agents.json exists
+function buildRuntimeExecutePreflight(projectRoot, activeSession, runState) {
+    const health = loadProjectHealth();
+    const blockers = [];
+    const warnings = [];
+    let report = null;
+    if (health && typeof health.buildHealthReport === 'function') {
+      report = health.buildHealthReport(projectRoot);
+      if (report.planSelfEvaluation && report.planSelfEvaluation.executable === false) {
+        const confidence = report.planSelfEvaluation.confidence;
+        const threshold = report.planConfidenceThreshold || 90;
+        blockers.push(`plan_confidence:${confidence == null ? 'missing' : `${confidence}%`}<=${threshold}%`);
+      }
+      if (report.executionRationality && report.executionRationality.applicable && !report.executionRationalityReady) {
+        const gaps = Array.isArray(report.criticalExecutionGaps) ? report.criticalExecutionGaps : [];
+        blockers.push(`execution_rationality:${gaps[0] || 'not_ready'}`);
+      }
+      if (report.fallbackMode && report.fallbackMode !== 'none') {
+        warnings.push(`fallback_mode:${report.fallbackMode}`);
+      }
+    } else {
+      warnings.push('health_report_unavailable');
+    }
+    const runId = runState && runState.run_id ? runState.run_id : null;
+    const queue = readRuntimeGates(projectRoot, activeSession, { runId });
+    if (queue.pending.length > 0) {
+      blockers.push(`pending_gates:${queue.pending.length}`);
+    }
+    return {
+      ok: blockers.length === 0,
+      blockers,
+      warnings,
+      runId,
+      gateQueue: {
+        pending: queue.pending.length,
+        stale: queue.staleCount || 0,
+      },
+      confidence: report && report.planSelfEvaluation ? report.planSelfEvaluation.confidence : null,
+      confidenceThreshold: report ? report.planConfidenceThreshold || 90 : 90,
+      executionRationalityReady: report ? Boolean(report.executionRationalityReady) : false,
+    };
+  }
+
+  async function runRuntimeExecute(projectRoot, activeSession, options = {}) {
+    const runtime = loadRuntimeModule();
+    if (!runtime) throw new Error('Runtime package não está disponível. Rode npm run build:runtime.');
   const parsers = loadSdkParsers();
   if (!parsers) throw new Error('SDK parsers não disponíveis.');
 
@@ -787,50 +869,52 @@ function buildRuntimeExecutePreflight(projectRoot, activeSession, runState) {
 
   // Resolve compiled graph from run state or compile on demand
   let current = options.runState || readRunState(projectRoot, activeSession);
-    if (!current || !current.compiled_graph) {
-      current = compileExecutionGraphFromArtifacts(projectRoot, activeSession, { runState: current }).run;
-    }
-    if (!current || !current.compiled_graph) {
-      throw new Error('Nenhum grafo compilado encontrado. Execute oxe-cc runtime compile primeiro.');
-    }
-    const preflight = buildRuntimeExecutePreflight(projectRoot, activeSession, current);
-    if (!preflight.ok && !options.skipPreflight) {
-      const reason = preflight.blockers[0] || 'runtime_execute_preflight_failed';
-      appendEvent(projectRoot, activeSession, {
-        type: 'WorkItemBlocked',
-        run_id: current.run_id,
-        payload: {
-          reason: 'runtime_execute_preflight_failed',
-          blockers: preflight.blockers,
-        },
-      });
-      return {
-        mode: 'preflight',
-        agentPlan: null,
-        result: {
-          run_id: current.run_id,
-          status: 'blocked',
-          completed: [],
-          failed: [],
-          blocked: ['runtime_execute_preflight'],
-          reason,
-        },
-        run: current,
-        preflight,
-      };
-    }
-    const graph = runtime.fromSerializable
-      ? runtime.fromSerializable(current.compiled_graph)
-      : current.compiled_graph;
-
-  // Detect plan-agents.json (session path takes priority over root)
+    if (!current || !current.compiled_graph) {
+      current = compileExecutionGraphFromArtifacts(projectRoot, activeSession, { runState: current }).run;
+    }
+    if (!current || !current.compiled_graph) {
+      throw new Error('Nenhum grafo compilado encontrado. Execute oxe-cc runtime compile primeiro.');
+    }
+    const preflight = buildRuntimeExecutePreflight(projectRoot, activeSession, current);
+    if (!preflight.ok && !options.skipPreflight) {
+      const reason = preflight.blockers[0] || 'runtime_execute_preflight_failed';
+      appendEvent(projectRoot, activeSession, {
+        type: 'WorkItemBlocked',
+        run_id: current.run_id,
+        payload: {
+          reason: 'runtime_execute_preflight_failed',
+          blockers: preflight.blockers,
+        },
+      });
+      return {
+        mode: 'preflight',
+        agentPlan: null,
+        result: {
+          run_id: current.run_id,
+          status: 'blocked',
+          completed: [],
+          failed: [],
+          blocked: ['runtime_execute_preflight'],
+          reason,
+        },
+        run: current,
+        preflight,
+      };
+    }
+    const graph = runtime.fromSerializable
+      ? runtime.fromSerializable(current.compiled_graph)
+      : current.compiled_graph;
+
+  // Detect plan-agents.json: explicit override > session path > root path
   const rootAgentPlan = path.join(projectRoot, '.oxe', 'plan-agents.json');
   const sessAgentPlan = activeSession
     ? path.join(projectRoot, '.oxe', activeSession, 'plan', 'plan-agents.json')
     : null;
-  const agentPlanPath = (sessAgentPlan && fs.existsSync(sessAgentPlan))
-    ? sessAgentPlan
-    : (fs.existsSync(rootAgentPlan) ? rootAgentPlan : null);
+  const agentPlanPath = (options.agentsPlanPath && fs.existsSync(options.agentsPlanPath))
+    ? options.agentsPlanPath
+    : (sessAgentPlan && fs.existsSync(sessAgentPlan))
+      ? sessAgentPlan
+      : (fs.existsSync(rootAgentPlan) ? rootAgentPlan : null);
 
   // Build ctx with GateManager (Gap 1)
   const ctx = createExecutionContext(projectRoot, activeSession, {
@@ -848,40 +932,40 @@ function buildRuntimeExecutePreflight(projectRoot, activeSession, runState) {
   // Gap 5: multi-agent path if plan-agents.json exists
   if (agentPlanPath) {
     let agentPlan;
-    try {
-      agentPlan = JSON.parse(fs.readFileSync(agentPlanPath, 'utf8'));
-    } catch (err) {
-      throw new Error(`plan-agents.json inválido: ${err.message}`);
-    }
-    const planErrors = validateMultiAgentPlan(agentPlan);
-    if (planErrors.length > 0) {
-      throw new Error(`plan-agents.json inválido: ${planErrors.join('; ')}`);
-    }
-    if (typeof runtime.MultiAgentCoordinator !== 'function') {
-      throw new Error('Runtime não exporta MultiAgentCoordinator. Verifique a versão do runtime.');
-    }
-    if (typeof runtime.GitWorktreeManager !== 'function' && !options.workspaceManager) {
-      throw new Error('Runtime não exporta GitWorktreeManager. Multi-agent real exige backend git_worktree.');
-    }
-    const agents = agentPlan.agents.map((spec) => ({
-      id: spec.id,
-      executor: options.executorFactory ? options.executorFactory(spec) : (options.executor || executor),
-      workspaceManager: options.workspaceManager || new runtime.GitWorktreeManager(projectRoot),
-      assignedTaskIds: Array.isArray(spec.tasks) ? spec.tasks : [],
-    }));
+    try {
+      agentPlan = JSON.parse(fs.readFileSync(agentPlanPath, 'utf8'));
+    } catch (err) {
+      throw new Error(`plan-agents.json inválido: ${err.message}`);
+    }
+    const planErrors = validateMultiAgentPlan(agentPlan);
+    if (planErrors.length > 0) {
+      throw new Error(`plan-agents.json inválido: ${planErrors.join('; ')}`);
+    }
+    if (typeof runtime.MultiAgentCoordinator !== 'function') {
+      throw new Error('Runtime não exporta MultiAgentCoordinator. Verifique a versão do runtime.');
+    }
+    if (typeof runtime.GitWorktreeManager !== 'function' && !options.workspaceManager) {
+      throw new Error('Runtime não exporta GitWorktreeManager. Multi-agent real exige backend git_worktree.');
+    }
+    const agents = agentPlan.agents.map((spec) => ({
+      id: spec.id,
+      executor: options.executorFactory ? options.executorFactory(spec) : (options.executor || executor),
+      workspaceManager: options.workspaceManager || new runtime.GitWorktreeManager(projectRoot),
+      assignedTaskIds: Array.isArray(spec.tasks) ? spec.tasks : [],
+    }));
     const coordinator = new runtime.MultiAgentCoordinator();
     const result = await coordinator.run(graph, {
       mode: agentPlan.mode || 'parallel',
       agents,
       projectRoot,
       sessionId: activeSession || null,
-      runId: current.run_id,
-      heartbeatTimeoutMs: options.heartbeatTimeoutMs ?? 120000,
-      applyWorkspaceMerges: true,
-      onEvent: ctx.onEvent,
-    });
-      return { mode: agentPlan.mode || 'parallel', agentPlan, result, run: current, preflight };
-    }
+      runId: current.run_id,
+      heartbeatTimeoutMs: options.heartbeatTimeoutMs ?? 120000,
+      applyWorkspaceMerges: true,
+      onEvent: ctx.onEvent,
+    });
+      return { mode: agentPlan.mode || 'parallel', agentPlan, result, run: current, preflight };
+    }
 
   // Single-agent fallback
   if (typeof runtime.Scheduler !== 'function') {
@@ -889,8 +973,8 @@ function buildRuntimeExecutePreflight(projectRoot, activeSession, runState) {
   }
   const scheduler = new runtime.Scheduler();
   const result = await scheduler.run(graph, ctx);
-    return { mode: 'single', agentPlan: null, result, run: current, preflight };
-  }
+    return { mode: 'single', agentPlan: null, result, run: current, preflight };
+  }
 
 function readRuntimeMultiAgentStatus(projectRoot, activeSession, options = {}) {
   const runtime = loadRuntimeModule();
@@ -905,49 +989,49 @@ function readRuntimeMultiAgentStatus(projectRoot, activeSession, options = {}) {
       workspaceIsolationEnforced: false,
       agents: [],
       ownership: [],
-      orphanReassignments: [],
-      handoffs: [],
-      arbitrationResults: [],
-      workspaceMergeReport: null,
-      worktrees: [],
-      mergeBlockers: [],
-      mergeReadiness: null,
-      arbitrationRequired: false,
-      health: 'unknown',
-      nextAction: 'Execute ou compile uma run antes de inspecionar status multi-agent.',
-      summary: null,
-    };
-  }
+      orphanReassignments: [],
+      handoffs: [],
+      arbitrationResults: [],
+      workspaceMergeReport: null,
+      worktrees: [],
+      mergeBlockers: [],
+      mergeReadiness: null,
+      arbitrationRequired: false,
+      health: 'unknown',
+      nextAction: 'Execute ou compile uma run antes de inspecionar status multi-agent.',
+      summary: null,
+    };
+  }
   const runDir = path.join(projectRoot, '.oxe', 'runs', runId);
   const statePath = path.join(runDir, 'multi-agent-state.json');
-  const summaryPath = path.join(runDir, 'multi-agent-summary.json');
-  const handoffsPath = path.join(runDir, 'handoffs.json');
-  const arbitrationPath = path.join(runDir, 'arbitration-results.json');
-  const workspaceMergePath = path.join(runDir, 'workspace-merge-report.json');
+  const summaryPath = path.join(runDir, 'multi-agent-summary.json');
+  const handoffsPath = path.join(runDir, 'handoffs.json');
+  const arbitrationPath = path.join(runDir, 'arbitration-results.json');
+  const workspaceMergePath = path.join(runDir, 'workspace-merge-report.json');
   const state = runtime && typeof runtime.loadMultiAgentState === 'function'
     ? runtime.loadMultiAgentState(projectRoot, runId)
     : readJsonIfExists(statePath);
-  const summary = runtime && typeof runtime.loadMultiAgentSummary === 'function'
-    ? runtime.loadMultiAgentSummary(projectRoot, runId)
-    : readJsonIfExists(summaryPath);
-  const workspaceMergeReport = runtime && typeof runtime.loadWorkspaceMergeReport === 'function'
-    ? runtime.loadWorkspaceMergeReport(projectRoot, runId)
-    : readJsonIfExists(workspaceMergePath);
-  const handoffs = readJsonIfExists(handoffsPath);
-  const arbitrationResults = readJsonIfExists(arbitrationPath);
-  const mergeBlockers = workspaceMergeReport && Array.isArray(workspaceMergeReport.blockers) ? workspaceMergeReport.blockers : [];
-  const mergeReadiness = workspaceMergeReport && workspaceMergeReport.merge_readiness ? workspaceMergeReport.merge_readiness : null;
-  let nextAction = null;
-  if (!state) {
-    nextAction = 'Execute runtime com plan-agents.json válido para materializar o estado multi-agent.';
-  } else if (mergeBlockers.length > 0) {
-    nextAction = 'Resolva os merge blockers do workspace antes de promover ou aplicar novos resultados.';
-  } else if (mergeReadiness === 'partial') {
-    nextAction = 'Conclua verify/evidence pós-merge ou aplique os worktrees pendentes antes de fechar a run.';
-  } else if (mergeReadiness === 'ready') {
-    nextAction = 'Multi-agent merge pronto; avance para runtime verify ou promotion conforme o ciclo.';
-  }
-  return {
+  const summary = runtime && typeof runtime.loadMultiAgentSummary === 'function'
+    ? runtime.loadMultiAgentSummary(projectRoot, runId)
+    : readJsonIfExists(summaryPath);
+  const workspaceMergeReport = runtime && typeof runtime.loadWorkspaceMergeReport === 'function'
+    ? runtime.loadWorkspaceMergeReport(projectRoot, runId)
+    : readJsonIfExists(workspaceMergePath);
+  const handoffs = readJsonIfExists(handoffsPath);
+  const arbitrationResults = readJsonIfExists(arbitrationPath);
+  const mergeBlockers = workspaceMergeReport && Array.isArray(workspaceMergeReport.blockers) ? workspaceMergeReport.blockers : [];
+  const mergeReadiness = workspaceMergeReport && workspaceMergeReport.merge_readiness ? workspaceMergeReport.merge_readiness : null;
+  let nextAction = null;
+  if (!state) {
+    nextAction = 'Execute runtime com plan-agents.json válido para materializar o estado multi-agent.';
+  } else if (mergeBlockers.length > 0) {
+    nextAction = 'Resolva os merge blockers do workspace antes de promover ou aplicar novos resultados.';
+  } else if (mergeReadiness === 'partial') {
+    nextAction = 'Conclua verify/evidence pós-merge ou aplique os worktrees pendentes antes de fechar a run.';
+  } else if (mergeReadiness === 'ready') {
+    nextAction = 'Multi-agent merge pronto; avance para runtime verify ou promotion conforme o ciclo.';
+  }
+  return {
     path: statePath,
     enabled: Boolean(state),
     runId,
@@ -956,44 +1040,44 @@ function readRuntimeMultiAgentStatus(projectRoot, activeSession, options = {}) {
     agents: state && Array.isArray(state.agent_results) ? state.agent_results : [],
     ownership: state && Array.isArray(state.ownership) ? state.ownership : [],
     orphanReassignments: state && Array.isArray(state.orphan_reassignments) ? state.orphan_reassignments : [],
-    handoffs: Array.isArray(handoffs) ? handoffs : [],
-    arbitrationResults: Array.isArray(arbitrationResults) ? arbitrationResults : [],
-    workspaceMergeReport: workspaceMergeReport || null,
-    worktrees: workspaceMergeReport && Array.isArray(workspaceMergeReport.records) ? workspaceMergeReport.records : [],
-    mergeBlockers,
-    mergeReadiness,
-    arbitrationRequired: Boolean(workspaceMergeReport && workspaceMergeReport.arbitration_required),
-    health: summary && summary.health ? summary.health : (mergeBlockers.length > 0 ? 'degraded' : 'unknown'),
-    nextAction,
-    summary: summary || null,
-  };
-}
-
-function validateMultiAgentPlan(agentPlan) {
-  const errors = [];
-  const allowedModes = new Set(['parallel', 'competitive', 'cooperative']);
-  const mode = agentPlan && agentPlan.mode ? String(agentPlan.mode) : 'parallel';
-  if (!allowedModes.has(mode)) errors.push(`mode inválido: ${mode}`);
-  if (!Array.isArray(agentPlan && agentPlan.agents) || agentPlan.agents.length === 0) {
-    errors.push('campo "agents" vazio ou ausente');
-    return errors;
-  }
-  const schemaVersion = Number(agentPlan.schema_version || agentPlan.schema || 0);
-  const seen = new Set();
-  for (const [idx, spec] of agentPlan.agents.entries()) {
-    const id = spec && spec.id ? String(spec.id) : '';
-    if (!id) errors.push(`agents[${idx}].id ausente`);
-    if (id && seen.has(id)) errors.push(`agent duplicado: ${id}`);
-    if (id) seen.add(id);
-    if (schemaVersion >= 3 && !spec.persona) errors.push(`${id || `agents[${idx}]`}.persona ausente`);
-    if (schemaVersion >= 3 && !spec.model_hint) errors.push(`${id || `agents[${idx}]`}.model_hint ausente`);
-    if (spec.tasks != null && !Array.isArray(spec.tasks)) errors.push(`${id || `agents[${idx}]`}.tasks deve ser array`);
-  }
-  if ((mode === 'competitive' || mode === 'cooperative') && agentPlan.agents.length < 2) {
-    errors.push(`${mode} exige pelo menos 2 agentes`);
-  }
-  return errors;
-}
+    handoffs: Array.isArray(handoffs) ? handoffs : [],
+    arbitrationResults: Array.isArray(arbitrationResults) ? arbitrationResults : [],
+    workspaceMergeReport: workspaceMergeReport || null,
+    worktrees: workspaceMergeReport && Array.isArray(workspaceMergeReport.records) ? workspaceMergeReport.records : [],
+    mergeBlockers,
+    mergeReadiness,
+    arbitrationRequired: Boolean(workspaceMergeReport && workspaceMergeReport.arbitration_required),
+    health: summary && summary.health ? summary.health : (mergeBlockers.length > 0 ? 'degraded' : 'unknown'),
+    nextAction,
+    summary: summary || null,
+  };
+}
+
+function validateMultiAgentPlan(agentPlan) {
+  const errors = [];
+  const allowedModes = new Set(['parallel', 'competitive', 'cooperative']);
+  const mode = agentPlan && agentPlan.mode ? String(agentPlan.mode) : 'parallel';
+  if (!allowedModes.has(mode)) errors.push(`mode inválido: ${mode}`);
+  if (!Array.isArray(agentPlan && agentPlan.agents) || agentPlan.agents.length === 0) {
+    errors.push('campo "agents" vazio ou ausente');
+    return errors;
+  }
+  const schemaVersion = Number(agentPlan.schema_version || agentPlan.schema || 0);
+  const seen = new Set();
+  for (const [idx, spec] of agentPlan.agents.entries()) {
+    const id = spec && spec.id ? String(spec.id) : '';
+    if (!id) errors.push(`agents[${idx}].id ausente`);
+    if (id && seen.has(id)) errors.push(`agent duplicado: ${id}`);
+    if (id) seen.add(id);
+    if (schemaVersion >= 3 && !spec.persona) errors.push(`${id || `agents[${idx}]`}.persona ausente`);
+    if (schemaVersion >= 3 && !spec.model_hint) errors.push(`${id || `agents[${idx}]`}.model_hint ausente`);
+    if (spec.tasks != null && !Array.isArray(spec.tasks)) errors.push(`${id || `agents[${idx}]`}.tasks deve ser array`);
+  }
+  if ((mode === 'competitive' || mode === 'cooperative') && agentPlan.agents.length < 2) {
+    errors.push(`${mode} exige pelo menos 2 agentes`);
+  }
+  return errors;
+}
 
 function loadRuntimeVerificationArtifacts(projectRoot, runState) {
   const runtime = loadRuntimeModule();
@@ -1019,7 +1103,7 @@ function loadRuntimeVerificationArtifacts(projectRoot, runState) {
   return { manifest, residualRisks, evidenceCoverage };
 }
 
-function countVerificationEvidenceRefs(runState, verificationArtifacts) {
+function countVerificationEvidenceRefs(runState, verificationArtifacts) {
   if (verificationArtifacts && verificationArtifacts.manifest && Array.isArray(verificationArtifacts.manifest.checks)) {
     return verificationArtifacts.manifest.checks.reduce((sum, check) => {
       return sum + (Array.isArray(check.evidence_refs) ? check.evidence_refs.length : 0);
@@ -1031,26 +1115,26 @@ function countVerificationEvidenceRefs(runState, verificationArtifacts) {
     }, 0);
   }
   return 0;
-}
-
-function detectOrphanWorktrees(projectRoot, runId) {
-  const workspacesDir = path.join(projectRoot, '.oxe', 'workspaces');
-  if (!fs.existsSync(workspacesDir)) return [];
-  const active = new Set();
-  const mergeReport = readJsonIfExists(path.join(projectRoot, '.oxe', 'runs', runId, 'workspace-merge-report.json'));
-  for (const record of (mergeReport && Array.isArray(mergeReport.records) ? mergeReport.records : [])) {
-    if (record && record.workspace_id) active.add(String(record.workspace_id));
-  }
-  return fs.readdirSync(workspacesDir, { withFileTypes: true })
-    .filter((entry) => entry.isDirectory())
-    .map((entry) => entry.name)
-    .filter((name) => !active.has(name))
-    .map((name) => ({
-      workspace_id: name,
-      path: path.join(workspacesDir, name),
-      next_action: 'inspecione o worktree órfão; depois remova com git worktree remove --force se não houver diffs úteis',
-    }));
-}
+}
+
+function detectOrphanWorktrees(projectRoot, runId) {
+  const workspacesDir = path.join(projectRoot, '.oxe', 'workspaces');
+  if (!fs.existsSync(workspacesDir)) return [];
+  const active = new Set();
+  const mergeReport = readJsonIfExists(path.join(projectRoot, '.oxe', 'runs', runId, 'workspace-merge-report.json'));
+  for (const record of (mergeReport && Array.isArray(mergeReport.records) ? mergeReport.records : [])) {
+    if (record && record.workspace_id) active.add(String(record.workspace_id));
+  }
+  return fs.readdirSync(workspacesDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .filter((name) => !active.has(name))
+    .map((name) => ({
+      workspace_id: name,
+      path: path.join(workspacesDir, name),
+      next_action: 'inspecione o worktree órfão; depois remova com git worktree remove --force se não houver diffs úteis',
+    }));
+}
 
 function buildRuntimeModeStatus(runState) {
   if (!runState) {
@@ -1222,17 +1306,17 @@ function writeRecoverySummaryMarkdown(projectRoot, activeSession, runState, reco
     '',
     '## Work items órfãos',
     '',
-    ...(Array.isArray(recoverySummary.orphan_work_items) && recoverySummary.orphan_work_items.length
-      ? recoverySummary.orphan_work_items.map((item) => `- ${item}`)
-      : ['- Nenhum']),
-    '',
-    '## Worktrees órfãos',
-    '',
-    ...(Array.isArray(recoverySummary.orphan_worktrees) && recoverySummary.orphan_worktrees.length
-      ? recoverySummary.orphan_worktrees.map((item) => `- ${item.workspace_id} · ${item.next_action}`)
-      : ['- Nenhum']),
-    '',
-    '## Tentativas incompletas',
+    ...(Array.isArray(recoverySummary.orphan_work_items) && recoverySummary.orphan_work_items.length
+      ? recoverySummary.orphan_work_items.map((item) => `- ${item}`)
+      : ['- Nenhum']),
+    '',
+    '## Worktrees órfãos',
+    '',
+    ...(Array.isArray(recoverySummary.orphan_worktrees) && recoverySummary.orphan_worktrees.length
+      ? recoverySummary.orphan_worktrees.map((item) => `- ${item.workspace_id} · ${item.next_action}`)
+      : ['- Nenhum']),
+    '',
+    '## Tentativas incompletas',
     '',
     ...(recoverySummary.consistency && Array.isArray(recoverySummary.consistency.incomplete_attempts) && recoverySummary.consistency.incomplete_attempts.length
       ? recoverySummary.consistency.incomplete_attempts.map((item) => `- ${item.work_item_id} · ${item.attempt_id || 'attempt'} · ${item.outcome || 'unknown'}`)
@@ -1337,6 +1421,94 @@ async function runRuntimeVerify(projectRoot, activeSession, options = {}) {
   };
 }
 
+// Marks SPEC.md checklist items as [x] when the run is completed.
+// Finds **DoD Wave N:** blocks and numbered checklist sections (e.g. "21.1 MVP"),
+// marks unchecked items only within sections whose waves are fully completed.
+function applySpecChecklistSync(specPath, canonicalLive, compiledGraph) {
+  if (!canonicalLive || (canonicalLive.run && canonicalLive.run.status !== 'completed')) return;
+  if (!specPath || !fs.existsSync(specPath)) return;
+
+  const completedIds = new Set(
+    canonicalLive.completedWorkItems instanceof Set
+      ? [...canonicalLive.completedWorkItems]
+      : Array.isArray(canonicalLive.completedWorkItems)
+        ? canonicalLive.completedWorkItems
+        : []
+  );
+  if (completedIds.size === 0) return;
+
+  const waves = Array.isArray(compiledGraph && compiledGraph.waves) ? compiledGraph.waves : [];
+
+  // Which wave numbers are fully completed (all node_ids in completedIds)?
+  const completedWaveNums = new Set();
+  for (const wave of waves) {
+    if (Array.isArray(wave.node_ids) && wave.node_ids.length > 0 &&
+        wave.node_ids.every(id => completedIds.has(id))) {
+      completedWaveNums.add(wave.wave_number);
+    }
+  }
+
+  // Are ALL waves completed? (run is complete = yes, since status === 'completed')
+  const allWavesDone = waves.length === 0 || waves.every(w =>
+    Array.isArray(w.node_ids) && w.node_ids.every(id => completedIds.has(id))
+  );
+
+  const lines = fs.readFileSync(specPath, 'utf8').split('\n');
+  let changed = false;
+
+  // Tracking state: which section type are we marking?
+  // 'none' | 'dod_wave' | 'checklist_mvp' | 'checklist_full'
+  let markMode = 'none';
+
+  const result = lines.map((line, i) => {
+    // Detect DoD Wave block header: **DoD Wave N:** or **DoD Wave N:** (with optional emoji/text)
+    const dodMatch = line.match(/\*\*DoD Wave\s+(\d+):/i);
+    if (dodMatch) {
+      const waveNum = parseInt(dodMatch[1], 10);
+      markMode = completedWaveNums.has(waveNum) ? 'dod_wave' : 'none';
+      return line;
+    }
+
+    // Detect numbered checklist section headers (e.g. "### 21.1 MVP", "### 21.2 v1.0.0")
+    const checklistMatch = line.match(/^#{2,4}\s+\d+\.\d+\s+(.+)/i);
+    if (checklistMatch) {
+      const sectionTitle = checklistMatch[1].toLowerCase();
+      // MVP / v0.x.x → mark when run is fully complete (pre-release milestones)
+      // v1.0.0 or any X.Y.Z ≥ 1.0.0 → never auto-mark (requires explicit human sign-off)
+      if (/mvp|v?0\.\d+\.\d+/i.test(sectionTitle) && allWavesDone) {
+        markMode = 'checklist_mvp';
+      } else {
+        markMode = 'none';
+      }
+      return line;
+    }
+
+    // Exit section on any top-level heading (##, ###) that isn't a checklist header
+    if (/^#{1,3}\s/.test(line) && !checklistMatch) {
+      markMode = 'none';
+      return line;
+    }
+
+    // Exit DoD section on **Limite técnico or **Condição para replanejar etc.
+    if (markMode === 'dod_wave' && /^\*\*(?:Limite|Condição|Nota|Atenção|Warning)/.test(line)) {
+      markMode = 'none';
+      return line;
+    }
+
+    // Mark unchecked items in active section
+    if (markMode !== 'none' && /^- \[ \]/.test(line)) {
+      changed = true;
+      return line.replace(/^- \[ \]/, '- [x]');
+    }
+
+    return line;
+  });
+
+  if (changed) {
+    fs.writeFileSync(specPath, result.join('\n'), 'utf8');
+  }
+}
+
 function projectRuntimeArtifacts(projectRoot, activeSession, options = {}) {
   const runtime = loadRuntimeModule();
   if (!runtime || typeof runtime.ProjectionEngine !== 'function' || typeof runtime.fromSerializable !== 'function') {
@@ -1406,6 +1578,8 @@ function projectRuntimeArtifacts(projectRoot, activeSession, options = {}) {
     fs.writeFileSync(path.join(op.executionRoot, 'COMMIT-SUMMARY.md'), projections.commitSummary + '\n', 'utf8');
     fs.writeFileSync(path.join(op.executionRoot, 'PROMOTION-SUMMARY.md'), projections.promotionSummary + '\n', 'utf8');
     fs.writeFileSync(path.join(op.executionRoot, 'PR-SUMMARY.md'), projections.prSummary + '\n', 'utf8');
+    // Sync SPEC.md checklist: mark completed wave DoD sections and MVP checklist when run closes
+    applySpecChecklistSync(paths.spec, canonicalLive, current.compiled_graph);
   }
   const next = writeRunState(projectRoot, activeSession, {
     ...current,
@@ -1595,14 +1769,14 @@ function recoverRuntimeState(projectRoot, activeSession, options = {}) {
     journal,
     verificationArtifacts
   );
-  const recoverySummary = {
-    recovered_at: new Date().toISOString(),
-    journal_state: journal.scheduler_state,
-    orphan_work_items: orphanWorkItems,
-    orphan_worktrees: detectOrphanWorktrees(projectRoot, current.run_id),
-    pending_gates: readRuntimeGates(projectRoot, activeSession, { runId: current.run_id }).pending.map((gate) => gate.gate_id),
-    consistency,
-  };
+  const recoverySummary = {
+    recovered_at: new Date().toISOString(),
+    journal_state: journal.scheduler_state,
+    orphan_work_items: orphanWorkItems,
+    orphan_worktrees: detectOrphanWorktrees(projectRoot, current.run_id),
+    pending_gates: readRuntimeGates(projectRoot, activeSession, { runId: current.run_id }).pending.map((gate) => gate.gate_id),
+    consistency,
+  };
   const runDir = path.join(projectRoot, '.oxe', 'runs', current.run_id);
   ensureDir(runDir);
   const recoverySummaryPath = path.join(runDir, 'recovery-summary.json');
@@ -2484,9 +2658,11 @@ module.exports = {
   buildRecoveryConsistency,
   readRuntimeGates,
   resolveRuntimeGate,
-  createExecutionContext,
-  buildRuntimeExecutePreflight,
-  runRuntimeExecute,
+  createExecutionContext,
+  saveRuntimeProviderConfig,
+  loadRuntimeProviderConfig,
+  buildRuntimeExecutePreflight,
+  runRuntimeExecute,
   runRuntimeVerify,
   projectRuntimeArtifacts,
   runRuntimeCiChecks,
@@ -2496,4 +2672,5 @@ module.exports = {
   replayEvents,
   replayRuntimeState,
   readRuntimeMultiAgentStatus,
+  applySpecChecklistSync,
 };