oxe-cc 1.6.0 → 1.8.0

package/CHANGELOG.md

@@ -4,6 +4,67 @@ Todas as versões seguem [Semantic Versioning](https://semver.org/). As mudança
 
 ---
 
+## [1.8.0] — 2026-04-29
+
+### Autonomous Execution — 5 Critical Gaps Resolved
+
+Esta release eleva a autonomia do runtime de ~65% para ~85%+ em projetos de baixo a médio risco, tornando o OXE capaz de transformar um input bem estruturado em entrega verificada com mínima intervenção humana.
+
+#### Gap 1 — GateManager Wiring
+- `createExecutionContext()` exportada de `oxe-operational.cjs`: instancia `GateManager` real sempre que o runtime estiver disponível, eliminando o deadlock silencioso de `'gate-missing-manager'`
+- `scheduler.js`: warning explícito quando `ctx.gateManager` ausente em vez de falha silenciosa
+- Novo subcomando `oxe-cc runtime execute` com roteamento automático single-agent / multi-agent
+
+#### Gap 2 — Verificação Inline após cada tarefa
+- `Scheduler.verifyNode()`: executa o `verify.command` do nó logo após execução bem-sucedida, antes de emitir `WorkItemCompleted`
+- Falha de verificação → tarefa reentrada no loop de retry com `failure_class: 'verify'`
+- Falha de infraestrutura de verificação (comando inexistente, timeout) → não bloqueia progresso
+- Eventos `VerificationStarted` / `VerificationCompleted` emitidos por tarefa (reducer já existia)
+
+#### Gap 3 — Retry Inteligente com Contexto do Erro Anterior
+- `node-prompt-builder.js`: seção "Contexto da tentativa anterior" injetada automaticamente nas tentativas 2+ com stderr/output truncado em 2000 chars
+- `llm-task-executor.js`: aceita `options.previousError`; repassado para o prompt builder
+- `scheduler.js`: `lastError` rastreado e propagado entre tentativas via `executeNode(options)`
+
+#### Gap 4 — Sinal Autoritativo de Conclusão (`finish_task`)
+- Nova tool built-in `finish_task` (idempotente) registrada em `BUILT_IN_TOOLS` e `ALL_BUILT_IN_SCHEMAS`
+- `selectToolsForActions()`: `finish_task` injetada universalmente em todos os tipos de ação
+- `node-prompt-builder.js`: instrução explícita de chamar `finish_task` ao concluir
+- `llm-task-executor.js`: detecta chamada de `finish_task` → `completed_by: 'finish_task'`; turns esgotados sem `finish_task` → `success: false, failure_class: 'llm'`
+
+#### Gap 5 — MultiAgentCoordinator Wiring
+- `runRuntimeExecute()` exportada de `oxe-operational.cjs`: detecta `plan-agents.json` (sessão > raiz) e roteia para `MultiAgentCoordinator` (parallel/competitive/cooperative) ou `Scheduler` single-agent
+- `oxe-cc runtime execute`: novo subcomando CLI com output formatado e exit code em falhas
+
+#### Testes
+- 5 novos arquivos de teste cobrindo cada gap: `gap1-gate-manager`, `gap2-inline-verify`, `gap3-retry-context`, `gap4-finish-task`, `gap5-multi-agent`
+- Suite total: **543 testes passando**, 0 falhas
+
+### Validation
+
+- `node --test tests/*.cjs tests/*.test.js`
+- `node bin/oxe-cc.js --version`
+
+---
+
+## [1.7.0] — 2026-04-23
+
+### OXE-native Agent Catalog
+
+- adicionada a fonte canónica `oxe/agents/` com agentes especializados para plan, execute, verify, debug, research, codebase mapping, integração, validação e UI
+- o instalador multi-runtime agora distribui agentes OXE para Claude Code (`.claude/agents`) e Codex/Antigravity (`.agents/skills` / skills compatíveis), além dos comandos já existentes
+- uninstall e smoke matrix passaram a validar e remover os agentes gerados pelo OXE
+
+### Rational Execution Artifacts
+
+- templates de `PLAN`, `IMPLEMENTATION-PACK`, `REFERENCE-ANCHORS`, `FIXTURE-PACK` e `SUMMARY` foram endurecidos com contratos goal-backward, write-set, símbolos, sequência mínima, rollback, fixtures e evidência
+- `/oxe-plan`, `/oxe-execute`, `/oxe-verify`, `/oxe-debug`, `/oxe-forensics`, `/oxe-ui-spec` e `/oxe-ui-review` agora referenciam explicitamente os agentes e gates racionais compatíveis com runtime enterprise
+
+### Public Surface Hygiene
+
+- `scan:assets` agora bloqueia referências públicas a namespaces, paths e nomes de origem legada
+- criado `docs/CONTENT-MIGRATION-AUDIT.md` como trilha interna de incorporação, sem exposição nas superfícies instaladas
+
 ## [1.6.0] — 2026-04-23
 
 ### Product Reconciliation

package/README.md

@@ -7,7 +7,7 @@
 [![npm](https://img.shields.io/npm/v/oxe-cc.svg?style=flat-square)](https://www.npmjs.com/package/oxe-cc)
 [![license](https://img.shields.io/npm/l/oxe-cc.svg?style=flat-square)](LICENSE)
 
-**Versão:** `1.6.0` · [package.json](package.json)
+**Versão:** `1.8.0` · [package.json](package.json)
 
 **Framework OXE — Orchestrated eXperience Engineering**
 
@@ -52,7 +52,7 @@ O OXE agora distingue cinco famílias de raciocínio:
 - `review` — findings primeiro, severidade, evidência e risco residual
 - `status` — leitura curta do estado, recomendação única e motivo
 
-Essas regras vivem no núcleo canónico em `oxe/workflows/references/reasoning-*.md`, sobem para os workflows em `oxe/workflows/` e são renderizadas para cada runtime em `.github/prompts/`, `.cursor/commands/`, `commands/oxe/`, `.codex/prompts/` e skills multiagente. Nesta linha, `oxe/workflows/**` e `workflow-runtime-contracts.json` voltam a ser o contrato obrigatório da release; superfícies geradas permanecem derivadas e sincronizadas.
+Essas regras vivem no núcleo canónico em `oxe/workflows/references/reasoning-*.md`, sobem para os workflows em `oxe/workflows/` e são renderizadas para cada runtime em `.github/prompts/`, `.cursor/commands/`, `commands/oxe/`, `.codex/prompts/` e skills multiagente. Agentes especializados vivem em `oxe/agents/` e são instalados como agentes/skills OXE-native quando o runtime suporta esse conceito. Nesta linha, `oxe/workflows/**`, `oxe/agents/**` e `workflow-runtime-contracts.json` são contratos obrigatórios da release; superfícies geradas permanecem derivadas e sincronizadas.
 
 ---
 
@@ -94,10 +94,10 @@ Contrato estável desta release:
 | Primeiros 15 minutos | [QUICKSTART.md](QUICKSTART.md) |
 | Guia por papel (executor / reviewer / operador) | [docs/ROLES.md](docs/ROLES.md) |
 | Fluxo recomendado para times | [docs/TEAM-ADOPTION.md](docs/TEAM-ADOPTION.md) |
-| Exemplo completo reproduzível | [docs/WALKTHROUGH.md](docs/WALKTHROUGH.md) |
-| Incidentes e gates | [docs/INCIDENT-PLAYBOOK.md](docs/INCIDENT-PLAYBOOK.md) |
-| Suporte por runtime (Cursor, Copilot, Claude Code…) | [docs/RUNTIME-SMOKE-MATRIX.md](docs/RUNTIME-SMOKE-MATRIX.md) |
-| Release readiness e publicação | [docs/RELEASE-READINESS.md](docs/RELEASE-READINESS.md) |
+| Exemplo completo reproduzível | [docs/WALKTHROUGH.md](docs/WALKTHROUGH.md) |
+| Incidentes e gates | [docs/INCIDENT-PLAYBOOK.md](docs/INCIDENT-PLAYBOOK.md) |
+| Suporte por runtime (Cursor, Copilot, Claude Code…) | [docs/RUNTIME-SMOKE-MATRIX.md](docs/RUNTIME-SMOKE-MATRIX.md) |
+| Release readiness e publicação | [docs/RELEASE-READINESS.md](docs/RELEASE-READINESS.md) |
 
 ---
 
@@ -459,18 +459,18 @@ O `status --full` mostra em ANSI: readiness do ciclo, autoavaliação do plano,
 
 O pacote está pronto para uma publicação robusta quando estes sinais estiverem verdes no repositório da release:
 
-- `npm test`
-- `npm run scan:assets`
-- `npm run build:vscode-ext`
-- `node bin/oxe-cc.js doctor --release --write-manifest`
-- `node bin/oxe-cc.js status --full`
-
-Artefatos obrigatórios desta fase:
-
-- `.oxe/release/release-manifest.json`
-- `.oxe/release/runtime-smoke-report.json`
-- `.oxe/release/recovery-fixture-report.json`
-- `.oxe/release/multi-agent-soak-report.json`
+- `npm test`
+- `npm run scan:assets`
+- `npm run build:vscode-ext`
+- `node bin/oxe-cc.js doctor --release --write-manifest`
+- `node bin/oxe-cc.js status --full`
+
+Artefatos obrigatórios desta fase:
+
+- `.oxe/release/release-manifest.json`
+- `.oxe/release/runtime-smoke-report.json`
+- `.oxe/release/recovery-fixture-report.json`
+- `.oxe/release/multi-agent-soak-report.json`
 
 Não há outro bloqueador funcional do plano runtime core para esta publicação. O que sobra depois dela é evolução de ergonomia e expansão de targets, não correção estrutural do contrato atual.
 
@@ -522,22 +522,24 @@ npx oxe-cc@latest
 | Flag | Efeito |
 |------|--------|
 | `--cursor` / `--copilot` | Só uma das stacks da IDE |
-| `--copilot-cli` | Skills globais do Copilot CLI em `~/.copilot/skills/` |
-| `--all-agents` | Cursor + Copilot + Claude + OpenCode + Gemini + Codex + Windsurf + Antigravity |
-| `--global` | Layout clássico: `oxe/` na raiz + `.oxe/` |
-| `--local` | Layout do repositório: mínimo, só `.oxe/` (padrão). Não controla onde a integração da IDE é instalada. |
-| `--ide-local` | Instala a integração no próprio repositório (`.cursor/`, `.github/`, `.claude/`, `.codex/` etc.) |
-| `--ide-global` | Instala a integração no HOME do utilizador quando o runtime suportar esse escopo |
-| `--force` / `-f` | Sobrescreve arquivos existentes (use para atualizar) |
-| `--dry-run` | Lista ações sem escrever |
-| `--oxe-only` | Só workflows em `.oxe/`, sem integrações IDE |
-| `--no-global-cli` / `-l` | Não instala `oxe-cc` globalmente (útil em CI) |
+| `--copilot-cli` | Skills globais do Copilot CLI em `~/.copilot/skills/` |
+| `--all-agents` | Cursor + Copilot + Claude + OpenCode + Gemini + Codex + Windsurf + Antigravity |
+| `--global` | Layout clássico: `oxe/` na raiz + `.oxe/` |
+| `--local` | Layout do repositório: mínimo, só `.oxe/` (padrão). Não controla onde a integração da IDE é instalada. |
+| `--ide-local` | Instala a integração no próprio repositório (`.cursor/`, `.github/`, `.claude/`, `.codex/` etc.) |
+| `--ide-global` | Instala a integração no HOME do utilizador quando o runtime suportar esse escopo |
+| `--force` / `-f` | Sobrescreve arquivos existentes (use para atualizar) |
+| `--dry-run` | Lista ações sem escrever |
+| `--oxe-only` | Só workflows em `.oxe/`, sem integrações IDE |
+| `--no-global-cli` / `-l` | Não instala `oxe-cc` globalmente (útil em CI) |
 | `OXE_NO_PROMPT=1` | Modo não-interativo (CI) |
 
 </details>
 
 GitHub Copilot no VS Code é **workspace-first**: o OXE instala prompt files em `.github/prompts/*.prompt.md` e mescla instruções em `.github/copilot-instructions.md`. `~/.copilot/` fica reservado ao legado detectável e ao runtime do Copilot CLI.
 
+Claude Code recebe comandos em `.claude/commands` e agentes especializados em `.claude/agents`. Codex recebe prompts em `.codex/prompts` e skills OXE em `.agents/skills`, incluindo os agentes especializados derivados de `oxe/agents/`.
+
 <details>
 <summary><strong>Atualizar e desinstalar</strong></summary>
 
@@ -569,11 +571,11 @@ node bin/oxe-cc.js --help
 | Comando | O que faz |
 |---------|-----------|
 | `oxe-cc` / `oxe-cc install` | Instala workflows e integrações |
-| `oxe-cc doctor` | Diagnóstico completo: Node, workflows, config, bootstrap `.oxe/`, sessão ativa, autoavaliação do plano, saúde lógica (`healthy` \| `warning` \| `broken`), drift semântico multi-runtime e workflows sem contrato no registry |
-| `oxe-cc doctor --release --write-manifest` | Gate de publicação: valida árvore canónica `oxe/`, `workflow-runtime-contracts.json`, versões, topo do `CHANGELOG`, runtime compilado, wrapper sync e relatórios obrigatórios; persiste `release-manifest.json` |
-| `oxe-cc status` | Próximo passo sugerido + saúde lógica do fluxo |
-| `oxe-cc status --full` | Coverage matrix + readiness gate + active run no terminal (ANSI); em repositório do pacote, troca para release readiness em vez de plan readiness |
-| `oxe-cc status --json` | Mesmo, em JSON (schema v5), com `workspaceMode`, `releaseReadiness`, `healthStatus`, `activeSession`, `planSelfEvaluation`, `contextPacks`, `contextQuality`, `semanticsDrift`, `verificationSummary`, `residualRiskSummary`, `evidenceCoverage`, `pendingGates`, `policyDecisionSummary`, `quotaSummary`, `auditSummary`, `promotionSummary`, `runtimeMode`, `fallbackMode`, `gateQueue`, `policyCoverage`, `promotionReadiness`, `recoveryState`, `multiAgent` e `providerCatalog` |
+| `oxe-cc doctor` | Diagnóstico completo: Node, workflows, config, bootstrap `.oxe/`, sessão ativa, autoavaliação do plano, saúde lógica (`healthy` \| `warning` \| `broken`), drift semântico multi-runtime e workflows sem contrato no registry |
+| `oxe-cc doctor --release --write-manifest` | Gate de publicação: valida árvore canónica `oxe/`, `workflow-runtime-contracts.json`, versões, topo do `CHANGELOG`, runtime compilado, wrapper sync e relatórios obrigatórios; persiste `release-manifest.json` |
+| `oxe-cc status` | Próximo passo sugerido + saúde lógica do fluxo |
+| `oxe-cc status --full` | Coverage matrix + readiness gate + active run no terminal (ANSI); em repositório do pacote, troca para release readiness em vez de plan readiness |
+| `oxe-cc status --json` | Mesmo, em JSON (schema v5), com `workspaceMode`, `releaseReadiness`, `healthStatus`, `activeSession`, `planSelfEvaluation`, `contextPacks`, `contextQuality`, `semanticsDrift`, `verificationSummary`, `residualRiskSummary`, `evidenceCoverage`, `pendingGates`, `policyDecisionSummary`, `quotaSummary`, `auditSummary`, `promotionSummary`, `runtimeMode`, `fallbackMode`, `gateQueue`, `policyCoverage`, `promotionReadiness`, `recoveryState`, `multiAgent` e `providerCatalog` |
 | `oxe-cc context build [--workflow <slug>] [--tier <minimal\|standard\|full>]` | Gera context pack(s) em `.oxe/context/packs/` — seleção determinística de artefatos por contrato de workflow |
 | `oxe-cc context inspect [--workflow <slug>]` | Inspeciona um context pack existente ou resolve sob demanda (sem escrita); útil para diagnóstico antes de iniciar um passo |
 | `oxe-cc update` | Atualiza workflows para a versão mais recente |
@@ -601,7 +603,7 @@ Arquivo `.oxe/config.json`. Principais opções:
 |-------|--------|-----------|
 | `profile` | `"balanced"` | `strict` / `balanced` / `fast` / `legacy` |
 | `verification_depth` | `"standard"` | `"thorough"` ativa gaps automático no verify (Camada 5) |
-| `plan_confidence_threshold` | `90` | Limiar canónico para `execute` aceitar um `PLAN.md`; a confiança precisa ser **maior que** esse valor |
+| `plan_confidence_threshold` | `90` | Limiar canónico para `execute` aceitar um `PLAN.md`; a confiança precisa ser **maior que** esse valor |
 | `security_in_verify` | `false` | `true` ativa OWASP automático no verify (Camada 6) |
 | `discuss_before_plan` | `false` | Exige aprovação de decisões antes do plano |
 | `scale_adaptive` | `true` | Scan sugere o profile pelo tamanho do projeto |

package/bin/lib/oxe-agent-install.cjs

@@ -34,10 +34,11 @@ function expandTilde(p) {
  *   opencodeCommandDirs: string[],
  *   geminiCommandsBase: string,
  *   windsurfWorkflowsDir: string,
- *   codexPromptsDir: string,
- *   codexAgentsSkillsRoot: string,
- *   antigravitySkillsRoot: string,
- * }} AgentInstallPaths
+ *   codexPromptsDir: string,
+ *   codexAgentsSkillsRoot: string,
+ *   antigravitySkillsRoot: string,
+ *   claudeAgentsDir: string,
+ * }} AgentInstallPaths
  */
 
 /**
@@ -56,21 +57,23 @@ function buildAgentInstallPaths(ideGlobal, projectRoot) {
       opencodeCommandDirs: [path.join(xdg, 'opencode', 'commands'), path.join(home, '.opencode', 'commands')],
       geminiCommandsBase: path.join(home, '.gemini', 'commands'),
       windsurfWorkflowsDir: path.join(home, '.codeium', 'windsurf', 'global_workflows'),
-      codexPromptsDir: path.join(codexHome, 'prompts'),
-      codexAgentsSkillsRoot: path.join(home, '.agents', 'skills'),
-      antigravitySkillsRoot: path.join(home, '.gemini', 'antigravity', 'skills'),
-    };
-  }
+      codexPromptsDir: path.join(codexHome, 'prompts'),
+      codexAgentsSkillsRoot: path.join(home, '.agents', 'skills'),
+      antigravitySkillsRoot: path.join(home, '.gemini', 'antigravity', 'skills'),
+      claudeAgentsDir: path.join(home, '.claude', 'agents'),
+    };
+  }
   return {
     ideGlobal: false,
     opencodeCommandDirs: [path.join(root, '.opencode', 'commands')],
     geminiCommandsBase: path.join(root, '.gemini', 'commands'),
     windsurfWorkflowsDir: path.join(root, '.windsurf', 'global_workflows'),
-    codexPromptsDir: path.join(root, '.codex', 'prompts'),
-    codexAgentsSkillsRoot: path.join(root, '.agents', 'skills'),
-    antigravitySkillsRoot: path.join(root, '.gemini', 'antigravity', 'skills'),
-  };
-}
+    codexPromptsDir: path.join(root, '.codex', 'prompts'),
+    codexAgentsSkillsRoot: path.join(root, '.agents', 'skills'),
+    antigravitySkillsRoot: path.join(root, '.gemini', 'antigravity', 'skills'),
+    claudeAgentsDir: path.join(root, '.claude', 'agents'),
+  };
+}
 
 /** @param {string} content */
 function adjustWorkflowPathsForNestedLayout(content) {
@@ -92,14 +95,30 @@ function parseCursorCommandFrontmatter(text) {
   if (end === -1) {
     return { description: '', body: normalized.trim(), frontmatter: {} };
   }
-  const yamlBlock = normalized.slice(4, end);
-  const frontmatter = {};
-  let description = '';
-  for (const line of yamlBlock.split('\n')) {
-    const m = line.match(/^description:\s*(.+)$/);
-    if (m) {
-      description = m[1].trim().replace(/^["']|["']$/g, '');
-    }
+  const yamlBlock = normalized.slice(4, end);
+  const frontmatter = {};
+  let description = '';
+  const yamlLines = yamlBlock.split('\n');
+  for (let i = 0; i < yamlLines.length; i++) {
+    const line = yamlLines[i];
+    const foldedDescription = line.match(/^description:\s*[>|]\s*$/);
+    if (foldedDescription) {
+      const parts = [];
+      let j = i + 1;
+      while (j < yamlLines.length && /^\s+/.test(yamlLines[j])) {
+        const value = yamlLines[j].trim();
+        if (value) parts.push(value);
+        j += 1;
+      }
+      description = parts.join(' ').trim();
+      frontmatter.description = description;
+      i = j - 1;
+      continue;
+    }
+    const m = line.match(/^description:\s*(.+)$/);
+    if (m) {
+      description = m[1].trim().replace(/^["']|["']$/g, '');
+    }
     const kv = line.match(/^([A-Za-z0-9_-]+):\s*(.+)$/);
     if (kv) frontmatter[kv[1]] = kv[2].trim().replace(/^["']|["']$/g, '');
   }
@@ -113,7 +132,7 @@ function parseCursorCommandFrontmatter(text) {
  * @param {string} body
  * @param {Record<string, string>} [metadata]
  */
-function buildAgentSkillMarkdown(skillName, description, body, metadata) {
+function buildAgentSkillMarkdown(skillName, description, body, metadata) {
   const desc = description.trim() || `Comando OXE — ${skillName}`;
   const meta = metadata ? runtimeSemantics.pickRuntimeMetadata(metadata) : {};
   const metaLines = Object.keys(meta).length
@@ -128,11 +147,91 @@ function buildAgentSkillMarkdown(skillName, description, body, metadata) {
     `---\n\n` +
     `${OXE_MANAGED_HTML}\n\n` +
     `${body}\n`
-  );
-}
-
-/**
- * @returns {string[]}
+  );
+}
+
+/** @param {string} name */
+function isOxeAgentMarkdownName(name) {
+  return name.startsWith('oxe-') && name.endsWith('.md');
+}
+
+/**
+ * @param {string} text
+ * @returns {{ name: string, description: string, body: string, frontmatter: Record<string, string> }}
+ */
+function parseCanonicalAgentMarkdown(text) {
+  const parsed = parseCursorCommandFrontmatter(text);
+  return {
+    name: parsed.frontmatter.name || '',
+    description: parsed.description || parsed.frontmatter.description || '',
+    body: parsed.body,
+    frontmatter: parsed.frontmatter,
+  };
+}
+
+/**
+ * Instala agentes especializados OXE como markdown nativo para runtimes que suportam agentes.
+ * @param {string} agentsSrc
+ * @param {string} destDir
+ * @param {{ dryRun: boolean, force: boolean }} opts
+ * @param {(s: string) => void} [logOmitido]
+ * @param {(s: string) => void} [logWrite]
+ */
+function installCanonicalAgentMarkdowns(agentsSrc, destDir, opts, logOmitido, logWrite) {
+  if (!fs.existsSync(agentsSrc)) return;
+  for (const name of fs.readdirSync(agentsSrc)) {
+    if (!isOxeAgentMarkdownName(name)) continue;
+    const src = path.join(agentsSrc, name);
+    const dest = path.join(destDir, name);
+    if (opts.dryRun) {
+      if (logWrite) logWrite(`${src} → ${dest}`);
+      continue;
+    }
+    if (fs.existsSync(dest) && !opts.force) {
+      if (logOmitido) logOmitido(dest);
+      continue;
+    }
+    const raw = fs.readFileSync(src, 'utf8');
+    const out = raw.includes(OXE_MANAGED_HTML) ? raw : raw.replace(/\n?$/, `\n\n${OXE_MANAGED_HTML}\n`);
+    fs.mkdirSync(destDir, { recursive: true });
+    fs.writeFileSync(dest, out, 'utf8');
+  }
+}
+
+/**
+ * Instala agentes especializados OXE como skills Codex/Antigravity.
+ * @param {string} agentsSrc
+ * @param {string} skillsRoot
+ * @param {{ dryRun: boolean, force: boolean }} opts
+ * @param {(s: string) => void} [logOmitido]
+ * @param {(s: string) => void} [logWrite]
+ */
+function installCanonicalAgentSkills(agentsSrc, skillsRoot, opts, logOmitido, logWrite) {
+  if (!fs.existsSync(agentsSrc)) return;
+  for (const name of fs.readdirSync(agentsSrc)) {
+    if (!isOxeAgentMarkdownName(name)) continue;
+    const src = path.join(agentsSrc, name);
+    const raw = fs.readFileSync(src, 'utf8');
+    const parsed = parseCanonicalAgentMarkdown(raw);
+    const skillName = parsed.name || name.replace(/\.md$/i, '');
+    const md = buildAgentSkillMarkdown(skillName, parsed.description, parsed.body, parsed.frontmatter);
+    const destDir = path.join(skillsRoot, skillName);
+    const dest = path.join(destDir, 'SKILL.md');
+    if (opts.dryRun) {
+      if (logWrite) logWrite(`${src} → ${dest}`);
+      continue;
+    }
+    if (fs.existsSync(dest) && !opts.force) {
+      if (logOmitido) logOmitido(dest);
+      continue;
+    }
+    fs.mkdirSync(destDir, { recursive: true });
+    fs.writeFileSync(dest, md, 'utf8');
+  }
+}
+
+/**
+ * @returns {string[]}
  */
 function opencodeCommandDirs() {
   return buildAgentInstallPaths(true, process.cwd()).opencodeCommandDirs;
@@ -499,6 +598,21 @@ function cleanupMarkedUnifiedArtifacts(u, paths) {
     }
   }
 
+  if (shouldClean('claude')) {
+    const clAgents = p.claudeAgentsDir;
+    if (fs.existsSync(clAgents)) {
+      for (const name of fs.readdirSync(clAgents)) {
+        if (!isOxeAgentMarkdownName(name)) continue;
+        const filePath = path.join(clAgents, name);
+        try {
+          if (fs.readFileSync(filePath, 'utf8').includes(OXE_MANAGED_HTML)) unlinkQuiet(filePath);
+        } catch {
+          /* ignore */
+        }
+      }
+    }
+  }
+
   if (shouldClean('antigravity')) {
     const agRoot = p.antigravitySkillsRoot;
     if (fs.existsSync(agRoot)) {
@@ -531,15 +645,18 @@ module.exports = {
   buildAgentSkillMarkdown,
   installSkillTreeFromCursorCommands,
   installOpenCodeCommands,
-  installGeminiTomlCommands,
-  installWindsurfGlobalWorkflows,
-  installCodexPrompts,
-  opencodeCommandDirs,
+  installGeminiTomlCommands,
+  installWindsurfGlobalWorkflows,
+  installCodexPrompts,
+  installCanonicalAgentMarkdowns,
+  installCanonicalAgentSkills,
+  opencodeCommandDirs,
   windsurfGlobalWorkflowsDir,
   geminiUserDir,
   codexAgentsSkillsRoot,
   codexPromptsDir,
   antigravitySkillsRoot,
   isOxeCommandMarkdownName,
+  isOxeAgentMarkdownName,
   cleanupMarkedUnifiedArtifacts,
 };

package/bin/lib/oxe-operational.cjs

@@ -79,6 +79,31 @@ function loadRuntimeModule() {
   }
 }
 
+// Gap 1: factory that always wires GateManager into ctx
+function createExecutionContext(projectRoot, activeSession, options = {}) {
+  const runtime = loadRuntimeModule();
+  const runId = options.runId || makeRunId();
+  const gateManager = (runtime && typeof runtime.GateManager === 'function')
+    ? new runtime.GateManager(projectRoot, activeSession || null, runId)
+    : null;
+  return {
+    projectRoot,
+    sessionId: activeSession || null,
+    runId,
+    executor: options.executor || null,
+    workspaceManager: options.workspaceManager || null,
+    gateManager,
+    policyEngine: options.policyEngine || null,
+    policyActor: options.policyActor || 'runtime',
+    quota: options.quota || null,
+    pluginRegistry: options.pluginRegistry || null,
+    auditTrail: options.auditTrail || null,
+    evidenceStore: options.evidenceStore || null,
+    onEvent: options.onEvent || null,
+    options: options.schedulerOptions || {},
+  };
+}
+
 function buildRuntimePluginRegistry(projectRoot) {
   const runtime = loadRuntimeModule();
   if (!runtime || typeof runtime.PluginRegistry !== 'function') return null;
@@ -637,11 +662,91 @@ async function resolveRuntimeGate(projectRoot, activeSession, options = {}) {
   };
 }
 
-function readRuntimeMultiAgentStatus(projectRoot, activeSession, options = {}) {
-  const runtime = loadRuntimeModule();
-  const current = readRunState(projectRoot, activeSession);
-  const runId = options.runId || (current && current.run_id) || null;
-  if (!runId) {
+// Gap 5: route execution to MultiAgentCoordinator when plan-agents.json exists
+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.');
+
+  // 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 graph = runtime.fromSerializable
+    ? runtime.fromSerializable(current.compiled_graph)
+    : current.compiled_graph;
+
+  // Detect plan-agents.json (session path takes priority over root)
+  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);
+
+  // Build ctx with GateManager (Gap 1)
+  const ctx = createExecutionContext(projectRoot, activeSession, {
+    runId: current.run_id,
+    executor: options.executor || null,
+    workspaceManager: options.workspaceManager || null,
+    pluginRegistry: options.pluginRegistry || buildRuntimePluginRegistry(projectRoot),
+    schedulerOptions: options.schedulerOptions || {},
+    onEvent: (event) => appendEvent(projectRoot, activeSession, event),
+  });
+
+  // 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}`);
+    }
+    if (!Array.isArray(agentPlan.agents) || agentPlan.agents.length === 0) {
+      throw new Error('plan-agents.json não contém agentes válidos (campo "agents" vazio ou ausente).');
+    }
+    if (typeof runtime.MultiAgentCoordinator !== 'function') {
+      throw new Error('Runtime não exporta MultiAgentCoordinator. Verifique a versão do runtime.');
+    }
+    const agents = agentPlan.agents.map((spec) => ({
+      id: spec.id,
+      executor: options.executorFactory ? options.executorFactory(spec) : (options.executor || null),
+      workspaceManager: options.workspaceManager || null,
+      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,
+      onEvent: ctx.onEvent,
+    });
+    return { mode: agentPlan.mode || 'parallel', agentPlan, result, run: current };
+  }
+
+  // Single-agent fallback
+  if (typeof runtime.Scheduler !== 'function') {
+    throw new Error('Runtime não exporta Scheduler. Verifique a versão do runtime.');
+  }
+  const scheduler = new runtime.Scheduler();
+  const result = await scheduler.run(graph, ctx);
+  return { mode: 'single', agentPlan: null, result, run: current };
+}
+
+function readRuntimeMultiAgentStatus(projectRoot, activeSession, options = {}) {
+  const runtime = loadRuntimeModule();
+  const current = readRunState(projectRoot, activeSession);
+  const runId = options.runId || (current && current.run_id) || null;
+  if (!runId) {
     return {
       path: null,
       enabled: false,
@@ -649,40 +754,40 @@ function readRuntimeMultiAgentStatus(projectRoot, activeSession, options = {}) {
       mode: null,
       workspaceIsolationEnforced: false,
       agents: [],
-      ownership: [],
-      orphanReassignments: [],
-      handoffs: [],
-      arbitrationResults: [],
-      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 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 handoffs = readJsonIfExists(handoffsPath);
-  const arbitrationResults = readJsonIfExists(arbitrationPath);
-  return {
-    path: statePath,
-    enabled: Boolean(state),
+      ownership: [],
+      orphanReassignments: [],
+      handoffs: [],
+      arbitrationResults: [],
+      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 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 handoffs = readJsonIfExists(handoffsPath);
+  const arbitrationResults = readJsonIfExists(arbitrationPath);
+  return {
+    path: statePath,
+    enabled: Boolean(state),
     runId,
     mode: state && state.mode ? state.mode : null,
     workspaceIsolationEnforced: Boolean(state && state.workspace_isolation_enforced),
     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 : [],
-    summary: summary || null,
-  };
-}
+    orphanReassignments: state && Array.isArray(state.orphan_reassignments) ? state.orphan_reassignments : [],
+    handoffs: Array.isArray(handoffs) ? handoffs : [],
+    arbitrationResults: Array.isArray(arbitrationResults) ? arbitrationResults : [],
+    summary: summary || null,
+  };
+}
 
 function loadRuntimeVerificationArtifacts(projectRoot, runState) {
   const runtime = loadRuntimeModule();
@@ -2138,6 +2243,8 @@ module.exports = {
   buildRecoveryConsistency,
   readRuntimeGates,
   resolveRuntimeGate,
+  createExecutionContext,
+  runRuntimeExecute,
   runRuntimeVerify,
   projectRuntimeArtifacts,
   runRuntimeCiChecks,