oxe-cc 1.5.1 → 1.7.0

package/AGENTS.md

@@ -99,4 +99,4 @@ Os wrappers por runtime podem carregar metadata cognitiva (`oxe_reasoning_mode`,
 
 Para `execute` e `verify`, o comportamento atual esperado é **runtime-first**: se `oxe-cc runtime` estiver disponível, preferir `runtime compile/project/verify/gates` e tratar markdown como projeção derivada; se o runtime não puder ser executado, declarar `fallback legado` explicitamente.
 
-Para publicação, o gate local esperado passa por `oxe-cc doctor --release --write-manifest`. Essa verificação deve falhar se houver drift de versão, topo inválido no `CHANGELOG`, wrapper dirty após sync, runtime não compilado ou ausência dos relatórios `.oxe/release/*.json` exigidos pela release.
+Para publicação, o gate local esperado passa por `oxe-cc doctor --release --write-manifest`. Essa verificação deve falhar se houver drift de versão, topo inválido no `CHANGELOG`, ausência da árvore canónica `oxe/`, `workflow-runtime-contracts.json` inválido, wrapper dirty após sync, runtime não compilado ou ausência dos relatórios `.oxe/release/*.json` exigidos pela release.

package/CHANGELOG.md

@@ -4,6 +4,51 @@ Todas as versões seguem [Semantic Versioning](https://semver.org/). As mudança
 
 ---
 
+## [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
+
+- a árvore canónica `oxe/` foi restaurada como source of truth da release, incluindo `oxe/workflows/`, `oxe/workflows/references/`, `oxe/templates/` e `commands/oxe/` como superfície derivada sincronizada
+- `workflow-runtime-contracts.json` voltou a ser contrato obrigatório da release; `sync-runtime-metadata` agora falha fechado quando a fonte canónica ou o registry semântico estão ausentes/inválidos
+- `doctor --release` passou a bloquear explicitamente por topologia canónica ausente, contrato semântico inválido e drift entre workflows e wrappers
+
+### Package-vs-Workspace Health
+
+- `status`, `status --full`, dashboard e SDK agora distinguem `workspaceMode: product_package` de `workspaceMode: oxe_project`
+- no repositório do pacote, o próximo passo deixa de cair em `plan/replan` por ruído de manutenção e passa a apontar para `doctor --release --write-manifest`
+- `status --json` passou a expor `workspaceMode` e `releaseReadiness` como contrato estável da linha `1.6.0`
+
+### Multi-runtime Edge Hardening
+
+- a smoke matrix de release passou a validar a instalação do Codex de forma completa: prompts em `.codex/prompts/` e skills em `.agents/skills/oxe/`
+- documentação de instalação foi ajustada para separar `--local` (layout do repo) de `--ide-local` (escopo da integração), eliminando a ambiguidade operacional em runtimes como Codex
+
+### Validation
+
+- `node --test tests/oxe-project-health.test.cjs`
+- `node --test tests/oxe-cli-edge.test.cjs`
+- `npm test`
+- `npm run scan:assets`
+- `npm run release:doctor`
+
 ## [1.5.1] — 2026-04-22
 
 ### Rational Execution Readiness

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.5.1` · [package.json](package.json)
+**Versão:** `1.7.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.
+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.
 
 ---
 
@@ -522,19 +522,23 @@ 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 mínimo: só `.oxe/` (padrão) |
-| `--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.
+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>
@@ -568,10 +572,10 @@ node bin/oxe-cc.js --help
 |---------|-----------|
 | `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 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) |
-| `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 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 |

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) {
@@ -113,7 +116,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 +131,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 +582,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 +629,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-dashboard.cjs

@@ -162,6 +162,20 @@ function confidenceBand(confidence, threshold) {
 }
 
 function computeReadiness(ctx, threshold) {
+  if (ctx.workspaceMode === 'product_package' && ctx.releaseReadiness) {
+    const blockers = Array.isArray(ctx.releaseReadiness.blockers) ? ctx.releaseReadiness.blockers.slice() : [];
+    const warnings = Array.isArray(ctx.releaseReadiness.warnings) ? ctx.releaseReadiness.warnings.slice() : [];
+    return {
+      go: Boolean(ctx.releaseReadiness.ok),
+      decision: ctx.releaseReadiness.ok ? 'go' : 'no-go',
+      threshold: health.normalizePlanConfidenceThreshold(threshold),
+      confidence: ctx.plan && ctx.plan.selfEvaluation ? ctx.plan.selfEvaluation.confidence : null,
+      confidenceBand: confidenceBand(ctx.plan && ctx.plan.selfEvaluation ? ctx.plan.selfEvaluation.confidence : null, threshold),
+      checkpointPending: false,
+      blockers,
+      warnings,
+    };
+  }
   const normalizedThreshold = health.normalizePlanConfidenceThreshold(threshold);
   const blockers = [];
   const warnings = [...ctx.diagnostics.reviewWarnings, ...ctx.diagnostics.runtimeWarnings, ...ctx.diagnostics.planWarnings];
@@ -349,7 +363,7 @@ function loadDashboardContext(projectRoot, opts = {}) {
   const activeSession = opts.activeSession === undefined ? health.parseActiveSession(stateText) : opts.activeSession;
   const p = reviewPaths(projectRoot, activeSession || null);
   const rootScoped = reviewPaths(projectRoot, null);
-  const report = health.buildHealthReport(projectRoot);
+  const report = health.buildHealthReport(projectRoot);
   const specText = readScopedText(p.spec, rootScoped.spec);
   const planText = readScopedText(p.plan, rootScoped.plan);
   const verifyText = readScopedText(p.verify, rootScoped.verify);
@@ -373,9 +387,11 @@ function loadDashboardContext(projectRoot, opts = {}) {
   const sessions = parseSessionsIndex(sessionsRaw);
   const sessionPath = activeSession ? path.join(projectRoot, '.oxe', activeSession, 'SESSION.md') : null;
   const sessionRaw = sessionPath ? readTextIfExists(sessionPath) || '' : '';
-  const ctx = {
-    projectRoot: path.resolve(projectRoot),
-    activeSession: activeSession || null,
+  const ctx = {
+    projectRoot: path.resolve(projectRoot),
+    workspaceMode: report.workspaceMode || 'oxe_project',
+    releaseReadiness: report.releaseReadiness || null,
+    activeSession: activeSession || null,
     phase: report.phase || health.parseStatePhase(stateText),
     healthStatus: report.healthStatus,
     nextStep: report.next,
@@ -388,7 +404,7 @@ function loadDashboardContext(projectRoot, opts = {}) {
     activeRun: activeRunState,
     runtimeCanonical: activeRunState && activeRunState.canonical_state ? activeRunState.canonical_state : null,
     compiledGraph: activeRunState && activeRunState.compiled_graph ? activeRunState.compiled_graph : null,
-    enterprise: {
+    enterprise: {
       runtimeMode: report.runtimeMode || null,
       fallbackMode: report.fallbackMode || null,
       verificationSummary: report.verificationSummary || null,

package/bin/lib/oxe-project-health.cjs

@@ -746,6 +746,50 @@ function resolvedReadableOxePaths(target, activeSession) {
     summary: preferScoped('summary'),
   };
 }
+
+/**
+ * @param {string} target
+ * @returns {{ workspaceMode: 'product_package' | 'oxe_project', packageName: string | null, canonicalTreePresent: boolean, commandsTreePresent: boolean }}
+ */
+function detectWorkspaceMode(target) {
+  const packageJsonPath = path.join(target, 'package.json');
+  let packageName = null;
+  try {
+    if (fs.existsSync(packageJsonPath)) {
+      const parsed = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+      packageName = parsed && typeof parsed.name === 'string' ? parsed.name : null;
+    }
+  } catch {
+    packageName = null;
+  }
+  const canonicalTreePresent = fs.existsSync(path.join(target, 'oxe', 'workflows'));
+  const commandsTreePresent = fs.existsSync(path.join(target, 'commands', 'oxe'));
+  const packageRepo =
+    packageName === 'oxe-cc'
+    && fs.existsSync(path.join(target, 'bin', 'oxe-cc.js'))
+    && fs.existsSync(path.join(target, 'packages', 'runtime', 'package.json'))
+    && canonicalTreePresent;
+  return {
+    workspaceMode: packageRepo ? 'product_package' : 'oxe_project',
+    packageName,
+    canonicalTreePresent,
+    commandsTreePresent,
+  };
+}
+
+/**
+ * @param {'product_package' | 'oxe_project'} workspaceMode
+ * @param {string | null} phase
+ * @param {string | null} activeSession
+ * @param {Record<string, unknown> | null} activeRun
+ * @returns {boolean}
+ */
+function shouldSuppressExecutionWorkspaceGates(workspaceMode, phase, activeSession, activeRun) {
+  if (workspaceMode !== 'product_package') return false;
+  if (activeSession) return false;
+  if (activeRun && typeof activeRun === 'object') return false;
+  return !phase || phase === 'initial';
+}
 
 /**
  * @param {string} target
@@ -1841,16 +1885,19 @@ function planReviewWarnings(stateText, p) {
  * @param {{ discuss_before_plan?: boolean }} cfg
  */
 function suggestNextStep(target, cfg = {}) {
-  const base = oxePaths(target);
-  const stateText = fs.existsSync(base.state) ? fs.readFileSync(base.state, 'utf8') : '';
-  const p = resolvedReadableOxePaths(target, parseActiveSession(stateText));
-  const discussBefore = Boolean(cfg.discuss_before_plan);
+  const base = oxePaths(target);
+  const stateText = fs.existsSync(base.state) ? fs.readFileSync(base.state, 'utf8') : '';
+  const activeSession = parseActiveSession(stateText);
+  const p = resolvedReadableOxePaths(target, activeSession);
+  const discussBefore = Boolean(cfg.discuss_before_plan);
   const threshold = normalizePlanConfidenceThreshold(cfg.plan_confidence_threshold);
-  const has = (/** @type {string} */ f) => fs.existsSync(f);
-  const mapsComplete = EXPECTED_CODEBASE_MAPS.every((f) => has(path.join(p.codebase, f)));
-  const azureActive = azure.isAzureContextEnabled(target, cfg);
-
-  if (!has(p.oxe) || !has(p.state)) {
+  const has = (/** @type {string} */ f) => fs.existsSync(f);
+  const mapsComplete = EXPECTED_CODEBASE_MAPS.every((f) => has(path.join(p.codebase, f)));
+  const azureActive = azure.isAzureContextEnabled(target, cfg);
+  const activeRun = operational.readRunState(target, activeSession);
+  const workspaceInfo = detectWorkspaceMode(target);
+
+  if (!has(p.oxe) || !has(p.state)) {
     return {
       step: 'scan',
       cursorCmd: '/oxe-scan',
@@ -1858,10 +1905,27 @@ function suggestNextStep(target, cfg = {}) {
       artifacts: ['.oxe/'],
     };
   }
-
-  const phase = parseStatePhase(stateText);
-
-  if (!mapsComplete && !has(p.quick)) {
+
+  const phase = parseStatePhase(stateText);
+  if (shouldSuppressExecutionWorkspaceGates(workspaceInfo.workspaceMode, phase, activeSession, activeRun)) {
+    const release = require('./oxe-release.cjs');
+    const readiness = release.inspectReleaseReadiness(target, { packageRoot: target });
+    return {
+      step: 'doctor',
+      cursorCmd: 'oxe-cc doctor --release --write-manifest',
+      reason: readiness.ok
+        ? 'Repositório do pacote OXE detectado — o próximo passo operacional é validar/publicar a release, não replanejar um workspace de entrega.'
+        : `Repositório do pacote OXE detectado — trate primeiro os blockers de release (${readiness.blockers[0] || 'release readiness incompleta'}).`,
+      artifacts: [
+        '.oxe/release/release-manifest.json',
+        '.oxe/release/runtime-smoke-report.json',
+        '.oxe/release/recovery-fixture-report.json',
+        '.oxe/release/multi-agent-soak-report.json',
+      ],
+    };
+  }
+
+  if (!mapsComplete && !has(p.quick)) {
     return {
       step: 'scan',
       cursorCmd: '/oxe-scan',
@@ -2003,9 +2067,7 @@ function suggestNextStep(target, cfg = {}) {
       artifacts: ['.oxe/PLAN.md', '.oxe/PLAN-REVIEW.md', '.oxe/STATE.md'],
     };
   }
-
-  const activeRun = operational.readRunState(target, parseActiveSession(stateText));
-  if (activeRun && activeRun.status === 'waiting_approval') {
+  if (activeRun && activeRun.status === 'waiting_approval') {
     return {
       step: 'dashboard',
       cursorCmd: '/oxe-dashboard',
@@ -2102,7 +2164,7 @@ function suggestNextStep(target, cfg = {}) {
 /**
  * @param {string} target
  */
-function buildHealthReport(target) {
+function buildHealthReport(target) {
   const contextEngine = require('./oxe-context-engine.cjs');
   const runtimeSemantics = require('./oxe-runtime-semantics.cjs');
   const { config, path: cfgPath, parseError } = loadOxeConfigMerged(target);
@@ -2116,10 +2178,11 @@ function buildHealthReport(target) {
       stateText = '';
     }
   }
-  const activeSession = parseActiveSession(stateText);
+  const activeSession = parseActiveSession(stateText);
   const p = resolvedReadableOxePaths(target, activeSession);
-  const phase = parseStatePhase(stateText);
-  const scanDate = parseLastScanDate(stateText);
+  const phase = parseStatePhase(stateText);
+  const workspaceInfo = detectWorkspaceMode(target);
+  const scanDate = parseLastScanDate(stateText);
   const stale = isStaleScan(scanDate, Number(config.scan_max_age_days) || 0);
   const compactDate = parseLastCompactDate(stateText);
   const staleCompact = isStaleScan(compactDate, Number(config.compact_max_age_days) || 0);
@@ -2134,6 +2197,7 @@ function buildHealthReport(target) {
   const capabilityWarn = capabilityWarnings(p);
   const investigationWarn = investigationWarnings(p);
   const parsedPlanSelfEvaluation = parsePlanSelfEvaluation(p.plan);
+  const activeRun = operational.readRunState(target, activeSession);
   const executionRationality = rationality.buildExecutionRationality({
     plan: p.plan,
     planAgents: p.planAgents,
@@ -2143,18 +2207,25 @@ function buildHealthReport(target) {
     fixturePackJson: p.fixturePackJson,
     fixturePackMd: p.fixturePackMd,
   });
-  const planWarn = [
+  const suppressExecutionWorkspaceGates = shouldSuppressExecutionWorkspaceGates(
+    workspaceInfo.workspaceMode,
+    phase,
+    activeSession,
+    activeRun
+  );
+  const executionPlanWarn = [
     ...planWaveWarningsFixed(p.plan, Number(config.plan_max_tasks_per_wave) || 0),
     ...planTaskAceiteWarnings(p.plan),
     ...planSelfEvaluationWarningsFromInfo(parsedPlanSelfEvaluation, threshold),
     ...executionRationalityWarningsFromSummary(executionRationality),
     ...planAgentsWarnings(target),
   ];
+  const planWarn = suppressExecutionWorkspaceGates ? [] : executionPlanWarn;
   const sessionWarn = sessionWarnings(target, activeSession);
-  const installWarn = installationCompletenessWarnings(target);
-  const copilot = copilotIntegrationReport(target);
-  const copilotWarn = copilot.warnings;
-  const reviewWarn = planReviewWarnings(stateText, p);
+  const installWarn = installationCompletenessWarnings(target);
+  const copilot = copilotIntegrationReport(target);
+  const copilotWarn = copilot.warnings;
+  const reviewWarn = suppressExecutionWorkspaceGates ? [] : planReviewWarnings(stateText, p);
   const planSelfEvaluation = {
     ...parsedPlanSelfEvaluation,
     best_plan_current: parsedPlanSelfEvaluation.bestPlan === 'sim'
@@ -2165,7 +2236,9 @@ function buildHealthReport(target) {
     threshold,
     executable: hasExecutablePlanSelfEvaluation(parsedPlanSelfEvaluation, threshold),
   };
-  const activeRun = operational.readRunState(target, activeSession);
+  const releaseReadiness = workspaceInfo.workspaceMode === 'product_package'
+    ? require('./oxe-release.cjs').inspectReleaseReadiness(target, { packageRoot: target })
+    : null;
   const eventsSummary = operational.summarizeEvents(operational.readEvents(target, activeSession));
   const memoryLayers = operational.buildMemoryLayers(target, activeSession);
   const enterpriseRuntime = summarizeEnterpriseRuntime(target, activeRun, activeSession, config);
@@ -2312,7 +2385,7 @@ function buildHealthReport(target) {
   if (semanticsAudit.mismatches.length) {
     semanticsWarn.push(`${semanticsAudit.mismatches.length} wrapper(s) com drift semântico detectado.`);
   }
-  const semanticsDrift = {
+  const semanticsDrift = {
     ok: semanticsWarn.length === 0 && semanticsAudit.ok,
     contractVersion: runtimeSemantics.CONTRACT_VERSION,
     manifestPath: base.runtimeSemanticsManifest,
@@ -2334,15 +2407,16 @@ function buildHealthReport(target) {
       ),
     },
   };
-  const hardFailure = Boolean(parseError) || sessionWarn.some((w) => /não existe|sem SESSION\.md/i.test(w));
-  const warningCount =
-    phaseWarn.length +
-    runtimeWarn.length +
-    reviewWarn.length +
-    enterpriseRuntime.enterpriseWarnings.length +
-    specWarn.length +
-    planWarn.length +
-    capabilityWarn.length +
+  const hardFailure = Boolean(parseError) || sessionWarn.some((w) => /não existe|sem SESSION\.md/i.test(w));
+  const planWarningCount = suppressExecutionWorkspaceGates ? 0 : planWarn.length;
+  const warningCount =
+    phaseWarn.length +
+    runtimeWarn.length +
+    reviewWarn.length +
+    enterpriseRuntime.enterpriseWarnings.length +
+    specWarn.length +
+    planWarningCount +
+    capabilityWarn.length +
     investigationWarn.length +
     sessionWarn.length +
     installWarn.length +
@@ -2353,8 +2427,9 @@ function buildHealthReport(target) {
     (sumWarn ? 1 : 0);
   const healthStatus = hardFailure ? 'broken' : warningCount > 0 ? 'warning' : 'healthy';
 
-  return {
-    configPath: cfgPath,
+  return {
+    workspaceMode: workspaceInfo.workspaceMode,
+    configPath: cfgPath,
     configParseError: parseError,
     unknownConfigKeys: shape.unknownKeys,
     typeErrors: shape.typeErrors,
@@ -2427,8 +2502,9 @@ function buildHealthReport(target) {
       : null,
     contextPacks,
     contextQuality,
-    semanticsDrift,
-    packFreshness,
+    semanticsDrift,
+    releaseReadiness,
+    packFreshness,
     activeSummaryRefs,
     healthStatus,
     next,
@@ -2474,8 +2550,10 @@ module.exports = {
   phaseCoherenceWarnings,
   verifyGapsWithoutSummaryWarning,
   specSectionWarnings,
-  planWaveWarningsFixed,
-  planTaskAceiteWarnings,
+  planWaveWarningsFixed,
+  planTaskAceiteWarnings,
+  detectWorkspaceMode,
+  shouldSuppressExecutionWorkspaceGates,
   suggestNextStep,
   buildHealthReport,
   buildExecutionRationality: rationality.buildExecutionRationality,