oxe-cc 1.3.0 → 1.4.1

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.3.0` · [package.json](package.json)
+**Versão:** `1.4.1` · [package.json](package.json)
 
 **Framework OXE — Orchestrated eXperience Engineering**
 
@@ -25,10 +25,10 @@ npx oxe-cc@latest
 
 OXE é o **Framework OXE — Orchestrated eXperience Engineering**: um framework de desenvolvimento assistido por IA orientado por artefatos, contexto em disco e execução verificável. Funciona identicamente em Cursor, GitHub Copilot, Claude Code, Gemini CLI, Windsurf e qualquer outro agente — o estado fica em `.oxe/` no seu projeto, não preso a nenhuma IDE.
 
-No momento atual, o OXE já opera em duas camadas complementares:
+No momento atual, o OXE opera em duas camadas complementares já prontas para publicação:
 
 - **framework de método** — `spec -> plan -> execute -> verify`, sessões, workstreams, lessons loop e contratos de raciocínio multi-runtime
-- **runtime enterprise incremental** — `ExecutionGraph`, `canonical_state`, context packs, evidence store, verification manifest, gates, policy, promotion e auditoria operacional
+- **runtime enterprise** — `ExecutionGraph`, `canonical_state`, context packs, evidence store, verification manifest, gates, policy, promotion, recovery e auditoria operacional
 
 Ele se apoia em três princípios:
 
@@ -76,6 +76,28 @@ Em termos práticos, o estado operacional real agora passa por:
 - `.oxe/execution/GATES.json`
 - `OXE-EVENTS.ndjson`
 
+Contrato estável desta release:
+
+- `execute` e `verify` são `runtime-first` quando `oxe-cc runtime` está disponível
+- `status`, `doctor`, dashboard e CLI de runtime leem o mesmo estado canónico
+- `multi-agent` é GA apenas com isolamento real (`git_worktree`); `inplace` não é backend válido para coordenação paralela
+- `pr_draft` é o alvo remoto estável de promotion nesta publicação
+
+→ [Guia por papel](docs/ROLES.md) — executor, reviewer, operador de gate, mantenedor do pacote
+
+---
+
+## Para times
+
+| Recurso | Link |
+|---------|------|
+| 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) |
+
 ---
 
 ## Modos de uso
@@ -382,6 +404,22 @@ Complexidade: S | M | L | XL
 
 Tarefas `XL` bloqueiam o gate sem sub-tarefas ou justificativa. `/oxe-obs` propaga automaticamente constraints para os R-IDs e Tns afetados.
 
+#### Iteração correta do plano
+
+Se o usuário quiser chamar `/oxe-plan` várias vezes até ficar satisfeito, o fluxo esperado é este:
+
+- **Mesmo escopo e mesma `SPEC.md`, mas quer refinar tarefas, ondas, dependências, riscos ou validação**: usar `/oxe-plan --replan`
+- **Mudou a estratégia técnica**: voltar para `/oxe-discuss` e depois `/oxe-plan --replan`
+- **Mudou requisitos, critérios, prioridades ou aceite**: voltar para `/oxe-spec` e depois `/oxe-plan`
+
+Regra prática:
+
+- `spec` muda o **que** será entregue
+- `discuss` muda o **como** ou o **porquê** da estratégia
+- `plan --replan` muda **como quebrar e executar** a mesma entrega
+
+Se já existir `PLAN.md` no escopo atual e o usuário chamar `/oxe-plan` de novo sem alterar a spec, o OXE deve tratar isso como **replan implícito**, preservando a seção **Replanejamento** e o histórico útil do plano anterior.
+
 ### Runtime operacional e checkpoints
 
 - `PLAN.md` continua estratégico.
@@ -402,19 +440,32 @@ oxe-cc status --full    # health + coverage matrix + readiness gate no terminal
 oxe-cc runtime status   # run ativo, cursor, onda atual
 oxe-cc runtime verify   # verify enterprise: suite + evidence + manifest + risk ledger
 oxe-cc runtime gates list
+oxe-cc runtime agents --json
 oxe-cc runtime promote --target pr_draft
 ```
 
-O `status --full` mostra em ANSI: readiness do ciclo, autoavaliação do plano, health lógico, contexto, gates pendentes, verify enterprise, quotas, audit trail e promotion state.
+O `status --full` mostra em ANSI: readiness do ciclo, autoavaliação do plano, health lógico, contexto, gates pendentes, verify enterprise, quotas, audit trail, recovery state, multi-agent e promotion state.
 
 ### Dashboard web — opt-in para revisões de equipe
 
-- `oxe-cc dashboard` sobe uma interface web local em `localhost` para revisar o plano antes da execução — indicado para apresentações ou revisões em equipe, não para uso diário.
+- `oxe-cc dashboard` sobe uma interface web local em `localhost` para revisar o plano antes da execução — indicado para apresentações, operação de gates e revisões em equipe, não para substituir o terminal no dia a dia.
 - A UI lê os artefatos OXE reais; ela não substitui `PLAN.md`, `STATE.md` ou `VERIFY.md`.
-- A visão inclui ciclo principal, mapa de artefatos, active run, trace log, trilha de ondas, handoffs, checkpoints, agentes, evidências, gates, quotas, audit summary e promotion state sem criar uma segunda fonte de verdade.
-- `oxe-cc runtime <start|pause|resume|replay|status|compile|verify|project|ci|promote|recover|gates>` controla explicitamente `ACTIVE-RUN.json`, `runs/`, `GATES.json`, manifests de verify e `OXE-EVENTS.ndjson` no mesmo contrato consumido pelo dashboard.
+- A visão inclui ciclo principal, mapa de artefatos, active run, trace log, trilha de ondas, handoffs, checkpoints, agentes, evidências, gates, quotas, audit summary, recovery state e promotion state sem criar uma segunda fonte de verdade.
+- `oxe-cc runtime <start|pause|resume|replay|status|compile|verify|project|ci|promote|recover|gates|agents>` controla explicitamente `ACTIVE-RUN.json`, `runs/`, `GATES.json`, manifests de verify, artefatos de recovery, `multi-agent-state.json` e `OXE-EVENTS.ndjson` no mesmo contrato consumido pelo dashboard.
 - A aprovação visual persiste em `plan_review_status` no `STATE.md`, em `PLAN-REVIEW.md` e em `plan-review-comments.json`.
 
+### Critérios de publicação desta release
+
+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`
+- `node bin/oxe-cc.js status --full`
+
+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.
+
 ### `/oxe-retro` — loop de aprendizado
 
 ```
@@ -511,18 +562,19 @@ node bin/oxe-cc.js --help
 | `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 status` | Próximo passo sugerido + saúde lógica do fluxo |
 | `oxe-cc status --full` | Coverage matrix + readiness gate + active run no terminal (ANSI) |
-| `oxe-cc status --json` | Mesmo, em JSON (schema v5), com `healthStatus`, `activeSession`, `planSelfEvaluation`, `contextPacks`, `contextQuality`, `semanticsDrift`, `verificationSummary`, `residualRiskSummary`, `evidenceCoverage`, `pendingGates`, `policyDecisionSummary`, `quotaSummary`, `auditSummary` e `promotionSummary` |
+| `oxe-cc status --json` | Mesmo, em JSON (schema v5), com `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 |
 | `oxe-cc init-oxe` | Bootstrap do `.oxe/` (STATE, config, codebase/, context/, install/) |
 | `oxe-cc dashboard` | Interface web local para revisão, comentários e aprovação do plano (inclui aba Context com quality score e drift semântico) |
-| `oxe-cc runtime <status\|start\|pause\|resume\|replay\|compile\|verify\|project\|ci\|promote\|recover\|gates>` | Controla o runtime enterprise: run ativo, grafo compilado, verify executável, gates, promoção remota, recovery e tracing operacional |
-| `oxe-cc runtime replay [--run <id>] [--from <event-id>] [--wave <n>] [--write]` | Timeline de eventos com deltas; `--write` gera `REPLAY-SESSION.md` |
+| `oxe-cc runtime <status\|start\|pause\|resume\|replay\|compile\|verify\|project\|ci\|promote\|recover\|gates\|agents>` | Controla o runtime enterprise: run ativo, grafo compilado, verify executável, gates, promoção remota, recovery, multi-agent e tracing operacional |
+| `oxe-cc runtime replay [--run <id>] [--from <event-id>] [--wave <n>] [--write] [--json]` | Timeline operacional estruturada; `--write` gera `REPLAY-SESSION.md` com divergências e deltas |
 | `oxe-cc runtime verify` | Executa `compileVerification + executeSuite + EvidenceStore + manifest + residual risk + projections` para a run ativa |
-| `oxe-cc runtime gates <list\|show\|resolve>` | Lista, inspeciona e resolve gates operacionais persistidos |
-| `oxe-cc runtime promote --target <pr_draft\|branch_push>` | Promoção remota explícita, separada de `ship`, governada por verify, gates, risk e coverage |
-| `oxe-cc runtime recover` | Reidrata journal, gates, policy decisions, evidence refs e estado canónico da run ativa |
+| `oxe-cc runtime gates <list\|show\|resolve>` | Lista, inspeciona e resolve gates operacionais persistidos; `list` aceita `--run`, `--status`, `--scope`, `--task` e `--json` |
+| `oxe-cc runtime agents status [--run <id>] [--json]` | Inspeciona ownership, handoffs, heartbeats, timeouts e failover multi-agent |
+| `oxe-cc runtime promote --target pr_draft` | Promoção remota explícita, separada de `ship`, governada por verify, gates, risk e coverage; `pr_draft` é o alvo estável desta release |
+| `oxe-cc runtime recover [--run <id>] [--json]` | Reidrata journal, gates, policy decisions, evidence refs, verification artifacts e estado canónico da run |
 | `oxe-cc capabilities <list\|install\|remove\|update>` | Mantém o catálogo nativo de capabilities em `.oxe/` |
 | `oxe-cc plugins <list\|install\|remove>` | Gerencia plugins de lifecycle; `install npm:<pkg>` instala em `.oxe/plugins/_npm/` |
 | `oxe-cc uninstall` | Remove integrações OXE do HOME e do repo |
@@ -607,4 +659,4 @@ TypeScript: [`lib/sdk/index.d.ts`](lib/sdk/index.d.ts) · Docs: [`lib/sdk/README
 
 ## Licença
 
-[GPL-3.0](LICENSE)
+[MIT](LICENSE)

package/bin/banner.txt

@@ -7,11 +7,11 @@
 
 ══════════════════════════════════════════════════════
 
-        🌵 OXE CLI · Spec-driven workflow
-        "Do jeito nordestino de fazer software"
-
-        ⚙️  Context Engineering
-        🤖  Multi-IDE · Cursor · Copilot · +CLIs
+        🌵 OXE CLI · Runtime Enterprise
+        "Spec-driven workflow com estado canónico"
+
+        ⚙️  Context Engineering · Evidence-first Verify
+        🤖  Multi-IDE · Copilot · Cursor · +CLIs
 
 ══════════════════════════════════════════════════════
 

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

@@ -13,8 +13,13 @@ const path = require('path');
 const os = require('os');
 const runtimeSemantics = require('./oxe-runtime-semantics.cjs');
 
-const OXE_MANAGED_HTML = '<!-- oxe-cc managed -->';
-const OXE_MANAGED_TOML = '# oxe-cc managed';
+const OXE_MANAGED_HTML = '<!-- oxe-cc managed -->';
+const OXE_MANAGED_TOML = '# oxe-cc managed';
+
+/** @param {string} name */
+function isOxeCommandMarkdownName(name) {
+  return (name === 'oxe.md' || name.startsWith('oxe-')) && name.endsWith('.md');
+}
 
 function expandTilde(p) {
   if (typeof p !== 'string') return p;
@@ -223,13 +228,13 @@ function installSkillTreeFromCursorCommands(cCmdSrc, skillsRoot, opts, pathRewri
  * Copia .md dos comandos Cursor para pastas OpenCode (markdown nativo).
  * @param {AgentInstallPaths} paths
  */
-function installOpenCodeCommands(cCmdSrc, paths, opts, pathRewriteNested, logOmitido, logWrite) {
-  if (!fs.existsSync(cCmdSrc)) return;
-  for (const destDir of paths.opencodeCommandDirs) {
-    for (const name of fs.readdirSync(cCmdSrc)) {
-      if (!name.startsWith('oxe-') || !name.endsWith('.md')) continue;
-      const src = path.join(cCmdSrc, name);
-      const dest = path.join(destDir, name);
+function installOpenCodeCommands(cCmdSrc, paths, opts, pathRewriteNested, logOmitido, logWrite) {
+  if (!fs.existsSync(cCmdSrc)) return;
+  for (const destDir of paths.opencodeCommandDirs) {
+    for (const name of fs.readdirSync(cCmdSrc)) {
+      if (!isOxeCommandMarkdownName(name)) continue;
+      const src = path.join(cCmdSrc, name);
+      const dest = path.join(destDir, name);
       if (opts.dryRun) {
         if (logWrite) logWrite(`opencode ${src} → ${dest}`);
         continue;
@@ -345,13 +350,13 @@ function installWindsurfGlobalWorkflows(cCmdSrc, paths, opts, pathRewriteNested,
  * Codex: prompts em ~/.codex/prompts ou ./.codex/prompts (local).
  * @param {AgentInstallPaths} paths
  */
-function installCodexPrompts(cCmdSrc, paths, opts, pathRewriteNested, logOmitido, logWrite) {
-  if (!fs.existsSync(cCmdSrc)) return;
-  const destDir = paths.codexPromptsDir;
-  for (const name of fs.readdirSync(cCmdSrc)) {
-    if (!name.startsWith('oxe-') || !name.endsWith('.md')) continue;
-    const src = path.join(cCmdSrc, name);
-    const dest = path.join(destDir, name);
+function installCodexPrompts(cCmdSrc, paths, opts, pathRewriteNested, logOmitido, logWrite) {
+  if (!fs.existsSync(cCmdSrc)) return;
+  const destDir = paths.codexPromptsDir;
+  for (const name of fs.readdirSync(cCmdSrc)) {
+    if (!isOxeCommandMarkdownName(name)) continue;
+    const src = path.join(cCmdSrc, name);
+    const dest = path.join(destDir, name);
     if (opts.dryRun) {
       if (logWrite) logWrite(`codex prompts ${src} → ${dest}`);
       continue;
@@ -385,8 +390,10 @@ function installCodexPrompts(cCmdSrc, paths, opts, pathRewriteNested, logOmitido
  * @param {{ dryRun: boolean }} u
  * @param {AgentInstallPaths} [paths] omissão = instalação global (HOME)
  */
-function cleanupMarkedUnifiedArtifacts(u, paths) {
-  const p = paths || buildAgentInstallPaths(true, process.cwd());
+function cleanupMarkedUnifiedArtifacts(u, paths) {
+  const p = paths || buildAgentInstallPaths(true, process.cwd());
+  const targets = u && typeof u === 'object' && u.targets && typeof u.targets === 'object' ? u.targets : null;
+  const shouldClean = (name) => !targets || targets[name] !== false;
 
   const unlinkQuiet = (filePath) => {
     if (!fs.existsSync(filePath)) return;
@@ -416,92 +423,104 @@ function cleanupMarkedUnifiedArtifacts(u, paths) {
     }
   };
 
-  for (const dir of p.opencodeCommandDirs) {
-    if (!fs.existsSync(dir)) continue;
-    for (const name of fs.readdirSync(dir)) {
-      if (!name.startsWith('oxe-') || !name.endsWith('.md')) continue;
-      const filePath = path.join(dir, name);
-      let txt = '';
-      try {
-        txt = fs.readFileSync(filePath, 'utf8');
-      } catch {
-        continue;
-      }
-      if (txt.includes(OXE_MANAGED_HTML)) unlinkQuiet(filePath);
-    }
-  }
-
-  const gBase = p.geminiCommandsBase;
-  const oxeToml = path.join(gBase, 'oxe.toml');
-  if (fs.existsSync(oxeToml)) {
-    try {
-      if (fs.readFileSync(oxeToml, 'utf8').includes(OXE_MANAGED_TOML)) unlinkQuiet(oxeToml);
-    } catch {
-      /* ignore */
-    }
-  }
-  const oxeSub = path.join(gBase, 'oxe');
-  if (fs.existsSync(oxeSub)) {
-    for (const name of fs.readdirSync(oxeSub)) {
-      if (!name.endsWith('.toml')) continue;
-      const filePath = path.join(oxeSub, name);
-      try {
-        if (fs.readFileSync(filePath, 'utf8').includes(OXE_MANAGED_TOML)) unlinkQuiet(filePath);
-      } catch {
-        /* ignore */
-      }
-    }
-    try {
-      if (!u.dryRun && fs.existsSync(oxeSub) && fs.readdirSync(oxeSub).length === 0) fs.rmdirSync(oxeSub);
-    } catch {
-      /* ignore */
-    }
-  }
-
-  const wfDir = p.windsurfWorkflowsDir;
-  if (fs.existsSync(wfDir)) {
-    for (const name of fs.readdirSync(wfDir)) {
-      if (name !== 'oxe.md' && !(name.startsWith('oxe-') && name.endsWith('.md'))) continue;
-      const filePath = path.join(wfDir, name);
-      try {
-        if (fs.readFileSync(filePath, 'utf8').includes(OXE_MANAGED_HTML)) unlinkQuiet(filePath);
-      } catch {
-        /* ignore */
-      }
-    }
-  }
-
-  const cpDir = p.codexPromptsDir;
-  if (fs.existsSync(cpDir)) {
-    for (const name of fs.readdirSync(cpDir)) {
-      if (!name.startsWith('oxe-') || !name.endsWith('.md')) continue;
-      const filePath = path.join(cpDir, name);
-      try {
-        if (fs.readFileSync(filePath, 'utf8').includes(OXE_MANAGED_HTML)) unlinkQuiet(filePath);
-      } catch {
-        /* ignore */
-      }
-    }
-  }
-
-  const agRoot = p.antigravitySkillsRoot;
-  if (fs.existsSync(agRoot)) {
-    for (const name of fs.readdirSync(agRoot, { withFileTypes: true })) {
-      if (!name.isDirectory()) continue;
-      if (!/^oxe($|-)/.test(name.name)) continue;
-      rmDirIfOxeSkill(path.join(agRoot, name.name));
-    }
-  }
-
-  const cxRoot = p.codexAgentsSkillsRoot;
-  if (fs.existsSync(cxRoot)) {
-    for (const name of fs.readdirSync(cxRoot, { withFileTypes: true })) {
-      if (!name.isDirectory()) continue;
-      if (!/^oxe($|-)/.test(name.name)) continue;
-      rmDirIfOxeSkill(path.join(cxRoot, name.name));
-    }
-  }
-}
+  if (shouldClean('opencode')) {
+    for (const dir of p.opencodeCommandDirs) {
+      if (!fs.existsSync(dir)) continue;
+      for (const name of fs.readdirSync(dir)) {
+        if (!isOxeCommandMarkdownName(name)) continue;
+        const filePath = path.join(dir, name);
+        let txt = '';
+        try {
+          txt = fs.readFileSync(filePath, 'utf8');
+        } catch {
+          continue;
+        }
+        if (txt.includes(OXE_MANAGED_HTML)) unlinkQuiet(filePath);
+      }
+    }
+  }
+
+  if (shouldClean('gemini')) {
+    const gBase = p.geminiCommandsBase;
+    const oxeToml = path.join(gBase, 'oxe.toml');
+    if (fs.existsSync(oxeToml)) {
+      try {
+        if (fs.readFileSync(oxeToml, 'utf8').includes(OXE_MANAGED_TOML)) unlinkQuiet(oxeToml);
+      } catch {
+        /* ignore */
+      }
+    }
+    const oxeSub = path.join(gBase, 'oxe');
+    if (fs.existsSync(oxeSub)) {
+      for (const name of fs.readdirSync(oxeSub)) {
+        if (!name.endsWith('.toml')) continue;
+        const filePath = path.join(oxeSub, name);
+        try {
+          if (fs.readFileSync(filePath, 'utf8').includes(OXE_MANAGED_TOML)) unlinkQuiet(filePath);
+        } catch {
+          /* ignore */
+        }
+      }
+      try {
+        if (!u.dryRun && fs.existsSync(oxeSub) && fs.readdirSync(oxeSub).length === 0) fs.rmdirSync(oxeSub);
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+
+  if (shouldClean('windsurf')) {
+    const wfDir = p.windsurfWorkflowsDir;
+    if (fs.existsSync(wfDir)) {
+      for (const name of fs.readdirSync(wfDir)) {
+        if (!isOxeCommandMarkdownName(name)) continue;
+        const filePath = path.join(wfDir, name);
+        try {
+          if (fs.readFileSync(filePath, 'utf8').includes(OXE_MANAGED_HTML)) unlinkQuiet(filePath);
+        } catch {
+          /* ignore */
+        }
+      }
+    }
+  }
+
+  if (shouldClean('codex')) {
+    const cpDir = p.codexPromptsDir;
+    if (fs.existsSync(cpDir)) {
+      for (const name of fs.readdirSync(cpDir)) {
+        if (!isOxeCommandMarkdownName(name)) continue;
+        const filePath = path.join(cpDir, 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)) {
+      for (const name of fs.readdirSync(agRoot, { withFileTypes: true })) {
+        if (!name.isDirectory()) continue;
+        if (!/^oxe($|-)/.test(name.name)) continue;
+        rmDirIfOxeSkill(path.join(agRoot, name.name));
+      }
+    }
+  }
+
+  if (shouldClean('codex')) {
+    const cxRoot = p.codexAgentsSkillsRoot;
+    if (fs.existsSync(cxRoot)) {
+      for (const name of fs.readdirSync(cxRoot, { withFileTypes: true })) {
+        if (!name.isDirectory()) continue;
+        if (!/^oxe($|-)/.test(name.name)) continue;
+        rmDirIfOxeSkill(path.join(cxRoot, name.name));
+      }
+    }
+  }
+}
 
 module.exports = {
   OXE_MANAGED_HTML,
@@ -520,6 +539,7 @@ module.exports = {
   geminiUserDir,
   codexAgentsSkillsRoot,
   codexPromptsDir,
-  antigravitySkillsRoot,
-  cleanupMarkedUnifiedArtifacts,
-};
+  antigravitySkillsRoot,
+  isOxeCommandMarkdownName,
+  cleanupMarkedUnifiedArtifacts,
+};

package/bin/lib/oxe-runtime-semantics.cjs

@@ -253,13 +253,23 @@ function humanizeValue(value) {
   return labels[key] || key.replace(/_/g, ' ');
 }
 
-function buildContextPackPaths(slug) {
-  return {
-    markdown: `.oxe/context/packs/${slug}.md`,
-    json: `.oxe/context/packs/${slug}.json`,
-    inspectCommand: `oxe-cc context inspect --workflow ${slug} --json`,
-  };
-}
+function buildContextPackPaths(slug) {
+  return {
+    markdown: `.oxe/context/packs/${slug}.md`,
+    json: `.oxe/context/packs/${slug}.json`,
+    inspectCommand: `oxe-cc context inspect --workflow ${slug} --json`,
+  };
+}
+
+function buildWorkflowResolutionBlock(slug) {
+  return [
+    '<!-- oxe-workflow-resolution:start -->',
+    '',
+    `**Resolução do workflow canónico:** a partir do CWD atual, subir diretórios até encontrar .oxe/workflows/${slug}.md ou oxe/workflows/${slug}.md. Ler e aplicar integralmente o primeiro ficheiro encontrado. Não assumir que o CWD já é a raiz do repositório. Se nenhum existir, reportar os paths tentados e parar.`,
+    '',
+    '<!-- oxe-workflow-resolution:end -->',
+  ].join('\n');
+}
 
 function buildReasoningContractBlock(meta, options = {}) {
   const includeReference = options.includeReference !== false;
@@ -336,13 +346,14 @@ function parseFrontmatterMap(raw) {
   return out;
 }
 
-function auditWrapperText(slug, raw) {
-  const frontmatter = parseFrontmatterMap(raw);
-  const expected = getRuntimeMetadataForSlug(slug);
-  const expectedPack = buildContextPackPaths(slug);
-  const issues = [];
-  for (const key of RUNTIME_METADATA_KEYS) {
-    if ((frontmatter[key] || '') !== (expected[key] || '')) {
+function auditWrapperText(slug, raw) {
+  const frontmatter = parseFrontmatterMap(raw);
+  const expected = getRuntimeMetadataForSlug(slug);
+  const expectedPack = buildContextPackPaths(slug);
+  const workflowResolution = buildWorkflowResolutionBlock(slug);
+  const issues = [];
+  for (const key of RUNTIME_METADATA_KEYS) {
+    if ((frontmatter[key] || '') !== (expected[key] || '')) {
       issues.push({ key, expected: expected[key] || '', actual: frontmatter[key] || '' });
     }
   }
@@ -355,11 +366,43 @@ function auditWrapperText(slug, raw) {
   if (!String(raw || '').includes(expectedPack.markdown) || !String(raw || '').includes(expectedPack.json)) {
     issues.push({ key: 'oxe_context_pack_entry', expected: `${expectedPack.markdown} + ${expectedPack.json}`, actual: 'missing' });
   }
-  if (!String(raw || '').includes('Regra pack-first')) {
-    issues.push({ key: 'oxe_pack_first_rule', expected: 'present', actual: 'missing' });
-  }
-  return {
-    slug,
+  if (!String(raw || '').includes('Regra pack-first')) {
+    issues.push({ key: 'oxe_pack_first_rule', expected: 'present', actual: 'missing' });
+  }
+  if (!String(raw || '').includes('<!-- oxe-workflow-resolution:start -->')) {
+    issues.push({ key: 'oxe_workflow_resolution_block', expected: 'present', actual: 'missing' });
+  } else {
+    if (!String(raw || '').includes(`.oxe/workflows/${slug}.md`) || !String(raw || '').includes(`oxe/workflows/${slug}.md`)) {
+      issues.push({
+        key: 'oxe_workflow_resolution_paths',
+        expected: workflowResolution,
+        actual: 'missing_path_reference',
+      });
+    }
+    if (!/subir diretórios até encontrar/i.test(String(raw || ''))) {
+      issues.push({
+        key: 'oxe_workflow_resolution_walkup',
+        expected: 'subir diretórios até encontrar',
+        actual: 'missing',
+      });
+    }
+  }
+  if (/\*\*Workflow can[óôo]nic[oa]:\*\*/i.test(String(raw || ''))) {
+    issues.push({
+      key: 'legacy_workflow_anchor',
+      expected: 'absent',
+      actual: 'present',
+    });
+  }
+  if (/raiz do projeto atual \(CWD\)|na raiz do repositório em contexto|na raiz do repositório em que estás a trabalhar/i.test(String(raw || ''))) {
+    issues.push({
+      key: 'legacy_fixed_root_instruction',
+      expected: 'absent',
+      actual: 'present',
+    });
+  }
+  return {
+    slug,
     frontmatter,
     expected,
     issues,
@@ -453,11 +496,12 @@ module.exports = {
   REQUIRED_CONTRACT_FIELDS,
   RUNTIME_METADATA_KEYS,
   auditRuntimeTargets,
-  auditWrapperText,
-  buildContextPackPaths,
-  buildContextTiers,
-  buildReasoningContractBlock,
-  computeSemanticsHash,
+  auditWrapperText,
+  buildContextPackPaths,
+  buildContextTiers,
+  buildReasoningContractBlock,
+  buildWorkflowResolutionBlock,
+  computeSemanticsHash,
   getAllWorkflowContracts,
   getRuntimeMetadataForSlug,
   getWorkflowContract,