oxe-cc 1.5.1 → 1.7.0

package/bin/lib/oxe-release.cjs

@@ -5,6 +5,7 @@ const path = require('path');
 const { spawnSync } = require('child_process');
 
 const oxeManifest = require('./oxe-manifest.cjs');
+const runtimeSemantics = require('./oxe-runtime-semantics.cjs');
 
 const REQUIRED_RUNTIMES = [
   'cursor',
@@ -269,6 +270,8 @@ function loadRuntimeSmokeReport(projectRoot) {
       && item.oxe_present
       && item.workflow_resolution_ok
       && item.wrapper_drift_ok !== false
+      && item.extra_checks_ok !== false
+      && item.agent_checks_ok !== false
       && item.uninstall_ok
     );
   });
@@ -301,11 +304,42 @@ function readVersionSnapshot(projectRoot) {
   };
 }
 
+function inspectCanonicalSource(projectRoot) {
+  const workflowsDir = path.join(projectRoot, 'oxe', 'workflows');
+  const referencesDir = path.join(workflowsDir, 'references');
+  const contractsPath = path.join(referencesDir, 'workflow-runtime-contracts.json');
+  const commandsDir = path.join(projectRoot, 'commands', 'oxe');
+  const workflowFiles = fs.existsSync(workflowsDir)
+    ? fs.readdirSync(workflowsDir).filter((name) => name.endsWith('.md'))
+    : [];
+  const registryIssues = runtimeSemantics.validateWorkflowContractsRegistry();
+  return {
+    workflowsDir,
+    referencesDir,
+    contractsPath,
+    commandsDir,
+    workflowsPresent: fs.existsSync(workflowsDir),
+    referencesPresent: fs.existsSync(referencesDir),
+    commandsPresent: fs.existsSync(commandsDir),
+    contractsPresent: fs.existsSync(contractsPath),
+    workflowCount: workflowFiles.length,
+    contractVersion: runtimeSemantics.CONTRACT_VERSION,
+    registryIssues,
+    ok: fs.existsSync(workflowsDir)
+      && fs.existsSync(referencesDir)
+      && fs.existsSync(commandsDir)
+      && fs.existsSync(contractsPath)
+      && workflowFiles.length > 0
+      && registryIssues.length === 0,
+  };
+}
+
 function buildReleaseManifest(projectRoot, options = {}) {
   const packageRoot = path.resolve(options.packageRoot || projectRoot);
   const paths = releasePaths(projectRoot);
   const versions = readVersionSnapshot(projectRoot);
   const runtimeEntry = path.join(packageRoot, 'lib', 'runtime', 'index.js');
+  const canonicalSource = inspectCanonicalSource(projectRoot);
   const wrapperSync = options.skipWrapperSync ? {
     before: collectWrapperHashes(projectRoot),
     after: collectWrapperHashes(projectRoot),
@@ -313,6 +347,7 @@ function buildReleaseManifest(projectRoot, options = {}) {
     mismatches: [],
     ok: true,
   } : syncWrappers(projectRoot, packageRoot);
+  const semanticsAudit = runtimeSemantics.auditRuntimeTargets(projectRoot);
   const smoke = loadRuntimeSmokeReport(projectRoot);
   const recovery = loadRecoveryFixtureReport(projectRoot);
   const multiAgent = loadMultiAgentSoakReport(projectRoot);
@@ -332,6 +367,12 @@ function buildReleaseManifest(projectRoot, options = {}) {
       path: runtimeEntry,
       ok: fs.existsSync(runtimeEntry),
     },
+    canonical_source: canonicalSource,
+    semantics: {
+      contractVersion: runtimeSemantics.CONTRACT_VERSION,
+      registryPath: runtimeSemantics.CONTRACTS_PATH,
+      audit: semanticsAudit,
+    },
     wrappers: {
       hash_before_sync: wrapperSync.before,
       hash_after_sync: wrapperSync.after,
@@ -354,8 +395,8 @@ function buildReleaseManifest(projectRoot, options = {}) {
   return manifest;
 }
 
-function checkReleaseConsistency(projectRoot, options = {}) {
-  const manifest = buildReleaseManifest(projectRoot, options);
+function evaluateReleaseManifest(manifest, options = {}) {
+  const enforceSync = options.enforceSync !== false;
   const blockers = [];
   const warnings = [];
   const versions = manifest.versions;
@@ -378,10 +419,22 @@ function checkReleaseConsistency(projectRoot, options = {}) {
     if (!versions.changelog.date) blockers.push('CHANGELOG.md topo sem data');
     if (!versions.changelog.hasHighlights) blockers.push('CHANGELOG.md topo sem highlights');
   }
+  const canonical = manifest.canonical_source || {};
+  if (!canonical.ok) {
+    blockers.push('árvore canónica ausente ou inválida');
+  }
+  if (!canonical.workflowsPresent) blockers.push('oxe/workflows ausente');
+  if (!canonical.referencesPresent) blockers.push('oxe/workflows/references ausente');
+  if (!canonical.commandsPresent) blockers.push('commands/oxe ausente');
+  if (!canonical.contractsPresent) blockers.push('workflow-runtime-contracts.json ausente');
+  if (canonical.workflowCount === 0) blockers.push('oxe/workflows sem workflows canónicos');
+  if (Array.isArray(canonical.registryIssues) && canonical.registryIssues.length) {
+    blockers.push('workflow-runtime-contracts.json inválido');
+  }
   if (!manifest.runtime_compiled.ok) {
     blockers.push('runtime não compilado (lib/runtime/index.js ausente)');
   }
-  if (!manifest.wrappers.sync.ok) {
+  if (enforceSync && !manifest.wrappers.sync.ok) {
     if (manifest.wrappers.sync.scripts.some((entry) => !entry.ok)) {
       blockers.push('sync de wrappers falhou');
     }
@@ -389,6 +442,10 @@ function checkReleaseConsistency(projectRoot, options = {}) {
       blockers.push('wrappers ficam dirty após sync-runtime-metadata/sync:cursor');
     }
   }
+  const semanticsAudit = manifest.semantics && manifest.semantics.audit;
+  if (!semanticsAudit || semanticsAudit.ok !== true) {
+    blockers.push('drift semântico entre workflows e wrappers');
+  }
   if (!manifest.reports.runtime_smoke.present || !manifest.reports.runtime_smoke.ok) {
     blockers.push('runtime smoke matrix incompleta ou com falhas');
   }
@@ -406,10 +463,23 @@ function checkReleaseConsistency(projectRoot, options = {}) {
     blockers,
     warnings,
     manifest,
-    manifestPath: releasePaths(projectRoot).manifest,
+    manifestPath: releasePaths(manifest.project_root).manifest,
   };
 }
 
+function checkReleaseConsistency(projectRoot, options = {}) {
+  const manifest = buildReleaseManifest(projectRoot, options);
+  return evaluateReleaseManifest(manifest, { enforceSync: true });
+}
+
+function inspectReleaseReadiness(projectRoot, options = {}) {
+  const manifest = buildReleaseManifest(projectRoot, {
+    ...options,
+    skipWrapperSync: true,
+  });
+  return evaluateReleaseManifest(manifest, { enforceSync: false });
+}
+
 module.exports = {
   REQUIRED_RUNTIMES,
   WRAPPER_TARGETS,
@@ -419,5 +489,8 @@ module.exports = {
   loadRecoveryFixtureReport,
   loadMultiAgentSoakReport,
   buildReleaseManifest,
+  inspectCanonicalSource,
+  evaluateReleaseManifest,
+  inspectReleaseReadiness,
   checkReleaseConsistency,
 };

package/bin/oxe-cc.js

@@ -1668,10 +1668,11 @@ function runStatusFull(target) {
     sp = oxeHealth.scopedOxePaths(target, activeSession);
   }
 
-  printSection('OXE ▸ status --full');
-  console.log(`  ${c ? green : ''}Projeto:${c ? reset : ''} ${c ? cyan : ''}${target}${c ? reset : ''}`);
-  console.log(`  ${c ? green : ''}Sessão:${c ? reset : ''} ${c ? cyan : ''}${activeSession || 'modo legado'}${c ? reset : ''}`);
-  console.log(`  ${c ? green : ''}Fase:${c ? reset : ''} ${report.phase || '—'}`);
+  printSection('OXE ▸ status --full');
+  console.log(`  ${c ? green : ''}Projeto:${c ? reset : ''} ${c ? cyan : ''}${target}${c ? reset : ''}`);
+  console.log(`  ${c ? green : ''}Sessão:${c ? reset : ''} ${c ? cyan : ''}${activeSession || 'modo legado'}${c ? reset : ''}`);
+  console.log(`  ${c ? green : ''}Workspace mode:${c ? reset : ''} ${report.workspaceMode || 'oxe_project'}`);
+  console.log(`  ${c ? green : ''}Fase:${c ? reset : ''} ${report.phase || '—'}`);
 
   const healthColor = report.healthStatus === 'healthy' ? green : report.healthStatus === 'warning' ? yellow : red;
   console.log(`  ${c ? green : ''}Saúde:${c ? reset : ''} ${c ? healthColor : ''}${report.healthStatus}${c ? reset : ''}`);
@@ -1701,23 +1702,40 @@ function runStatusFull(target) {
   console.log(`  ${coverageCell(codebaseExists, 'codebase scan')}   ${coverageCell(specExists, 'SPEC.md')}   ${coverageCell(planExists, 'PLAN.md')}   ${coverageCell(verifyExists, 'VERIFY.md')}   ${coverageCell(lessonsExists, 'LESSONS.md')}`);
 
   // Readiness gate
-  const ready = specExists
-    && planExists
-    && report.executionRationalityReady
-    && !report.planWarn.length
-    && !report.runtimeWarn.length;
-  const gateColor = ready ? green : yellow;
-  console.log(`\n  ${c ? yellow : ''}Readiness gate${c ? reset : ''}`);
-  console.log(`  ${c ? gateColor : ''}${ready ? '✓ Pronto para executar' : '✗ Não pronto para executar'}${c ? reset : ''}`);
-  if (!specExists) console.log(`  ${c ? dim : ''}  • SPEC.md ausente — rode /oxe-spec${c ? reset : ''}`);
-  if (!planExists) console.log(`  ${c ? dim : ''}  • PLAN.md ausente — rode /oxe-plan${c ? reset : ''}`);
-  if (report.planWarn.length) {
-    for (const w of report.planWarn) {
-      console.log(`  ${c ? yellow : ''}  • ${w}${c ? reset : ''}`);
+  const packageMode = report.workspaceMode === 'product_package';
+  const ready = packageMode
+    ? Boolean(report.releaseReadiness && report.releaseReadiness.ok)
+    : specExists
+      && planExists
+      && report.executionRationalityReady
+      && !report.planWarn.length
+      && !report.runtimeWarn.length;
+  const gateColor = ready ? green : yellow;
+  console.log(`\n  ${c ? yellow : ''}Readiness gate${c ? reset : ''}`);
+  console.log(`  ${c ? gateColor : ''}${ready ? (packageMode ? '✓ Pronto para publicar' : '✓ Pronto para executar') : (packageMode ? '✗ Não pronto para publicar' : '✗ Não pronto para executar')}${c ? reset : ''}`);
+  if (packageMode) {
+    const releaseReadiness = report.releaseReadiness || { blockers: [], warnings: [] };
+    if (Array.isArray(releaseReadiness.blockers) && releaseReadiness.blockers.length) {
+      for (const blocker of releaseReadiness.blockers) {
+        console.log(`  ${c ? red : ''}  • ${blocker}${c ? reset : ''}`);
+      }
+    }
+    if (Array.isArray(releaseReadiness.warnings) && releaseReadiness.warnings.length) {
+      for (const warning of releaseReadiness.warnings) {
+        console.log(`  ${c ? yellow : ''}  • ${warning}${c ? reset : ''}`);
+      }
+    }
+  } else {
+    if (!specExists) console.log(`  ${c ? dim : ''}  • SPEC.md ausente — rode /oxe-spec${c ? reset : ''}`);
+    if (!planExists) console.log(`  ${c ? dim : ''}  • PLAN.md ausente — rode /oxe-plan${c ? reset : ''}`);
+    if (report.planWarn.length) {
+      for (const w of report.planWarn) {
+        console.log(`  ${c ? yellow : ''}  • ${w}${c ? reset : ''}`);
+      }
+    }
+    if (planExists) {
+      console.log(`  ${c ? dim : ''}  • Artefatos racionais:${c ? reset : ''} implementation=${report.implementationPackReady ? 'ok' : 'pendente'} · anchors=${report.referenceAnchorsReady ? 'ok' : 'pendente'} · fixtures=${report.fixturePackReady ? 'ok' : 'pendente'}`);
     }
-  }
-  if (planExists) {
-    console.log(`  ${c ? dim : ''}  • Artefatos racionais:${c ? reset : ''} implementation=${report.implementationPackReady ? 'ok' : 'pendente'} · anchors=${report.referenceAnchorsReady ? 'ok' : 'pendente'} · fixtures=${report.fixturePackReady ? 'ok' : 'pendente'}`);
   }
 
   // Active run summary
@@ -1804,7 +1822,7 @@ function runStatusFull(target) {
   }
 
   // Plan self-evaluation
-  if (report.planSelfEvaluation) {
+  if (!packageMode && report.planSelfEvaluation) {
     const pse = report.planSelfEvaluation;
     const threshold = report.planConfidenceThreshold || 90;
     console.log(`\n  ${c ? yellow : ''}Autoavaliação do plano${c ? reset : ''}`);
@@ -1840,11 +1858,13 @@ function runStatus(target, opts = {}) {
   const next = report.next;
 
   if (opts.json) {
-    /** @type {Record<string, unknown>} */
-    const payload = {
-      oxeStatusSchema: 5,
-      projectRoot: path.resolve(target),
-      nextStep: report.next.step,
+    /** @type {Record<string, unknown>} */
+    const payload = {
+      oxeStatusSchema: 5,
+      projectRoot: path.resolve(target),
+      workspaceMode: report.workspaceMode || 'oxe_project',
+      releaseReadiness: report.releaseReadiness || null,
+      nextStep: report.next.step,
       cursorCmd: report.next.cursorCmd,
       reason: report.next.reason,
       artifacts: report.next.artifacts,
@@ -1921,9 +1941,10 @@ function runStatus(target, opts = {}) {
     return;
   }
 
-  printSection('OXE ▸ status');
-  const c = useAnsiColors();
-  console.log(`  ${c ? green : ''}Projeto:${c ? reset : ''} ${c ? cyan : ''}${target}${c ? reset : ''}`);
+  printSection('OXE ▸ status');
+  const c = useAnsiColors();
+  console.log(`  ${c ? green : ''}Projeto:${c ? reset : ''} ${c ? cyan : ''}${target}${c ? reset : ''}`);
+  console.log(`  ${c ? dim : ''}Workspace mode:${c ? reset : ''} ${report.workspaceMode || 'oxe_project'}`);
 
   const wfTgt = oxeWorkflows.resolveWorkflowsDir(target);
   if (!wfTgt) {
@@ -1954,16 +1975,24 @@ function runStatus(target, opts = {}) {
   }
 
   // Explicit blockage diagnosis
-  const specMissing = !fs.existsSync(path.join(target, '.oxe', 'SPEC.md'));
-  const planMissing = !fs.existsSync(path.join(target, '.oxe', 'PLAN.md'));
-  const verifyMissing = !fs.existsSync(path.join(target, '.oxe', 'VERIFY.md'));
-  if (specMissing) {
-    console.log(`  ${c ? yellow : ''}⚠ Bloqueio:${c ? reset : ''} SPEC.md ausente — rode ${c ? cyan : ''}/oxe-spec${c ? reset : ''} antes de planejar`);
-  } else if (planMissing) {
-    console.log(`  ${c ? yellow : ''}⚠ Bloqueio:${c ? reset : ''} PLAN.md ausente — rode ${c ? cyan : ''}/oxe-plan${c ? reset : ''}`);
-  } else if (verifyMissing && !planMissing) {
-    console.log(`  ${c ? dim : ''}Obs.:${c ? reset : ''} VERIFY.md ainda não gerado — rode ${c ? cyan : ''}/oxe-verify${c ? reset : ''} após executar`);
-  }
+  const packageMode = report.workspaceMode === 'product_package';
+  const specMissing = !fs.existsSync(path.join(target, '.oxe', 'SPEC.md'));
+  const planMissing = !fs.existsSync(path.join(target, '.oxe', 'PLAN.md'));
+  const verifyMissing = !fs.existsSync(path.join(target, '.oxe', 'VERIFY.md'));
+  if (packageMode) {
+    const releaseReadiness = report.releaseReadiness || { ok: false, blockers: [], warnings: [] };
+    if (!releaseReadiness.ok && Array.isArray(releaseReadiness.blockers) && releaseReadiness.blockers.length) {
+      console.log(`  ${c ? yellow : ''}⚠ Release blockers:${c ? reset : ''} ${releaseReadiness.blockers[0]}`);
+    } else if (Array.isArray(releaseReadiness.warnings) && releaseReadiness.warnings.length) {
+      console.log(`  ${c ? dim : ''}Obs.:${c ? reset : ''} release warnings ativas — ${releaseReadiness.warnings[0]}`);
+    }
+  } else if (specMissing) {
+    console.log(`  ${c ? yellow : ''}⚠ Bloqueio:${c ? reset : ''} SPEC.md ausente — rode ${c ? cyan : ''}/oxe-spec${c ? reset : ''} antes de planejar`);
+  } else if (planMissing) {
+    console.log(`  ${c ? yellow : ''}⚠ Bloqueio:${c ? reset : ''} PLAN.md ausente — rode ${c ? cyan : ''}/oxe-plan${c ? reset : ''}`);
+  } else if (verifyMissing && !planMissing) {
+    console.log(`  ${c ? dim : ''}Obs.:${c ? reset : ''} VERIFY.md ainda não gerado — rode ${c ? cyan : ''}/oxe-verify${c ? reset : ''} após executar`);
+  }
 
   if (opts.hints) {
     console.log(`\n  ${c ? cyan : ''}Lembretes (rotina OXE)${reset}`);
@@ -2701,10 +2730,14 @@ function runInstall(opts) {
     copyDir(path.join(PKG_ROOT, 'oxe', 'templates'), path.join(nested, 'templates'), copyOpts, true);
     // Personas: copiar para .oxe/personas/ (não sobrescreve personalizações do projeto)
     const personasSrc = path.join(PKG_ROOT, 'oxe', 'personas');
-    if (fs.existsSync(personasSrc)) {
-      copyDir(personasSrc, path.join(nested, 'personas'), copyOpts, false);
-    }
-    // Schemas: copiar para .oxe/schemas/ (ex.: plan-agents.schema.json para validação local)
+    if (fs.existsSync(personasSrc)) {
+      copyDir(personasSrc, path.join(nested, 'personas'), copyOpts, false);
+    }
+    const agentsSrc = path.join(PKG_ROOT, 'oxe', 'agents');
+    if (fs.existsSync(agentsSrc)) {
+      copyDir(agentsSrc, path.join(nested, 'agents'), copyOpts, false);
+    }
+    // Schemas: copiar para .oxe/schemas/ (ex.: plan-agents.schema.json para validação local)
     const schemasSrc = path.join(PKG_ROOT, 'oxe', 'schemas');
     if (fs.existsSync(schemasSrc)) {
       copyDir(schemasSrc, path.join(nested, 'schemas'), copyOpts, false);
@@ -2719,10 +2752,11 @@ function runInstall(opts) {
     if (fs.existsSync(cRules)) copyDir(cRules, path.join(cursorBase, 'rules'), copyOpts, idePathRewrite);
   }
 
-  const doAgentClis = opts.copilotCli || opts.allAgents;
-  if (doAgentClis) {
-    const cCmd = path.join(PKG_ROOT, '.cursor', 'commands');
-    const clBase = installClaudeBase(opts);
+  const doAgentClis = opts.copilotCli || opts.allAgents;
+  if (doAgentClis) {
+    const cCmd = path.join(PKG_ROOT, '.cursor', 'commands');
+    const canonicalAgents = path.join(PKG_ROOT, 'oxe', 'agents');
+    const clBase = installClaudeBase(opts);
     const cpHome = installCopilotCliHome(opts);
     const clDest = path.join(clBase, 'commands');
     const cpCmdDest = path.join(cpHome, 'commands');
@@ -2731,16 +2765,24 @@ function runInstall(opts) {
       console.log(
         `  ${c ? green : ''}cli${c ? reset : ''}   ${c ? dim : ''}Claude/Copilot: skills em${c ? reset : ''} ${c ? cyan : ''}${cpSkills}${c ? reset : ''} ${c ? dim : ''}(/oxe, /oxe-scan, …); comandos .md:${c ? reset : ''} ${c ? cyan : ''}${clDest}${c ? reset : ''} ${c ? dim : ''}+${c ? reset : ''} ${c ? cyan : ''}${cpCmdDest}${c ? reset : ''}`
       );
-      installOxeCopilotCliSkills(cCmd, cpHome, copyOpts, idePathRewrite);
-      copyDir(cCmd, clDest, copyOpts, idePathRewrite);
-      copyDir(cCmd, cpCmdDest, copyOpts, idePathRewrite);
-    } else {
+      installOxeCopilotCliSkills(cCmd, cpHome, copyOpts, idePathRewrite);
+      copyDir(cCmd, clDest, copyOpts, idePathRewrite);
+      copyDir(cCmd, cpCmdDest, copyOpts, idePathRewrite);
+      if (fs.existsSync(canonicalAgents)) {
+        oxeAgentInstall.installCanonicalAgentMarkdowns(
+          canonicalAgents,
+          agentPaths.claudeAgentsDir,
+          copyOpts
+        );
+      }
+    } else {
       console.warn(`${yellow}aviso:${reset} pasta ausente ${cCmd} — ignorando comandos CLI`);
     }
   }
 
-  const cCmdAgents = path.join(PKG_ROOT, '.cursor', 'commands');
-  if (fs.existsSync(cCmdAgents) && (opts.allAgents || anyGranularAgent(opts))) {
+  const cCmdAgents = path.join(PKG_ROOT, '.cursor', 'commands');
+  const canonicalAgents = path.join(PKG_ROOT, 'oxe', 'agents');
+  if (fs.existsSync(cCmdAgents) && (opts.allAgents || anyGranularAgent(opts))) {
     const logO = (d) => console.log(`${dim}omitido${reset} ${d} (já existe — use --force)`);
     const logW = (msg) => console.log(`${dim}agents${reset}  ${msg}`);
     console.log(
@@ -2758,27 +2800,41 @@ function runInstall(opts) {
     if (opts.agentCodex || opts.allAgents) {
       oxeAgentInstall.installCodexPrompts(cCmdAgents, agentPaths, copyOpts, idePathRewrite, logO, logW);
     }
-    if (opts.agentAntigravity || opts.allAgents) {
-      oxeAgentInstall.installSkillTreeFromCursorCommands(
+    if (opts.agentAntigravity || opts.allAgents) {
+      oxeAgentInstall.installSkillTreeFromCursorCommands(
         cCmdAgents,
         agentPaths.antigravitySkillsRoot,
         copyOpts,
         idePathRewrite,
         logO,
-        logW
-      );
-    }
-    if (opts.agentCodex || opts.allAgents) {
-      oxeAgentInstall.installSkillTreeFromCursorCommands(
+        logW
+      );
+      oxeAgentInstall.installCanonicalAgentSkills(
+        canonicalAgents,
+        agentPaths.antigravitySkillsRoot,
+        copyOpts,
+        logO,
+        logW
+      );
+    }
+    if (opts.agentCodex || opts.allAgents) {
+      oxeAgentInstall.installSkillTreeFromCursorCommands(
         cCmdAgents,
         agentPaths.codexAgentsSkillsRoot,
         copyOpts,
         idePathRewrite,
         logO,
-        logW
-      );
-    }
-  }
+        logW
+      );
+      oxeAgentInstall.installCanonicalAgentSkills(
+        canonicalAgents,
+        agentPaths.codexAgentsSkillsRoot,
+        copyOpts,
+        logO,
+        logW
+      );
+    }
+  }
 
   if (opts.copilot) {
     const gh = path.join(PKG_ROOT, '.github');
@@ -2868,10 +2924,11 @@ function runInstall(opts) {
       addTracked(copilotPromptsDirPath(opts), (n) => n.startsWith('oxe-'));
       trackFile(copilotWorkspaceManifestPath(opts));
     }
-    trackFile(runtimeSemanticsManifestPath(opts));
-    if (opts.copilotCli || opts.allAgents) {
-      addTracked(path.join(installClaudeBase(opts), 'commands'), (n) => oxeAgentInstall.isOxeCommandMarkdownName(n));
-      addTracked(path.join(cpCliHome, 'commands'), (n) => oxeAgentInstall.isOxeCommandMarkdownName(n));
+    trackFile(runtimeSemanticsManifestPath(opts));
+    if (opts.copilotCli || opts.allAgents) {
+      addTracked(path.join(installClaudeBase(opts), 'commands'), (n) => oxeAgentInstall.isOxeCommandMarkdownName(n));
+      addTracked(agentPaths.claudeAgentsDir, (n) => oxeAgentInstall.isOxeAgentMarkdownName(n));
+      addTracked(path.join(cpCliHome, 'commands'), (n) => oxeAgentInstall.isOxeCommandMarkdownName(n));
       const skRoot = path.join(cpCliHome, 'skills');
       if (fs.existsSync(skRoot)) {
         for (const sub of fs.readdirSync(skRoot, { withFileTypes: true })) {
@@ -3007,8 +3064,8 @@ function uninstallLocalIdeFromProject(u, removedPaths) {
     track(manifest);
   }
 
-  if (u.copilotCli || u.allAgents) {
-    for (const base of [path.join(proj, '.claude'), path.join(proj, '.copilot')]) {
+  if (u.copilotCli || u.allAgents) {
+    for (const base of [path.join(proj, '.claude'), path.join(proj, '.copilot')]) {
       const cmdDir = path.join(base, 'commands');
       if (!fs.existsSync(cmdDir)) continue;
       for (const name of fs.readdirSync(cmdDir)) {
@@ -3017,9 +3074,19 @@ function uninstallLocalIdeFromProject(u, removedPaths) {
           unlinkQuiet(p, u);
           track(p);
         }
-      }
-    }
-    const skillsRoot = path.join(proj, '.copilot', 'skills');
+      }
+    }
+    const claudeAgentsDir = path.join(proj, '.claude', 'agents');
+    if (fs.existsSync(claudeAgentsDir)) {
+      for (const name of fs.readdirSync(claudeAgentsDir)) {
+        if (oxeAgentInstall.isOxeAgentMarkdownName(name)) {
+          const p = path.join(claudeAgentsDir, name);
+          unlinkQuiet(p, u);
+          track(p);
+        }
+      }
+    }
+    const skillsRoot = path.join(proj, '.copilot', 'skills');
     if (fs.existsSync(skillsRoot)) {
       for (const ent of fs.readdirSync(skillsRoot, { withFileTypes: true })) {
         if (!ent.isDirectory() || !/^oxe($|-)/.test(ent.name)) continue;
@@ -3342,8 +3409,8 @@ function runUninstall(u) {
     cleanupLegacyCopilotVsCode(ideOpts, u, removedPaths);
   }
 
-  if (u.copilotCli) {
-    for (const base of [claudeUserDir(ideOpts), copilotUserDir(ideOpts)]) {
+  if (u.copilotCli) {
+    for (const base of [claudeUserDir(ideOpts), copilotUserDir(ideOpts)]) {
       const cmdDir = path.join(base, 'commands');
       if (!fs.existsSync(cmdDir)) continue;
       for (const name of fs.readdirSync(cmdDir)) {
@@ -3352,9 +3419,19 @@ function runUninstall(u) {
           unlinkQuiet(p, u);
           removedPaths.push(p);
         }
-      }
-    }
-    const skillsRoot = path.join(copilotUserDir(ideOpts), 'skills');
+      }
+    }
+    const claudeAgentsDir = path.join(claudeUserDir(ideOpts), 'agents');
+    if (fs.existsSync(claudeAgentsDir)) {
+      for (const name of fs.readdirSync(claudeAgentsDir)) {
+        if (oxeAgentInstall.isOxeAgentMarkdownName(name)) {
+          const p = path.join(claudeAgentsDir, name);
+          unlinkQuiet(p, u);
+          removedPaths.push(p);
+        }
+      }
+    }
+    const skillsRoot = path.join(copilotUserDir(ideOpts), 'skills');
     if (fs.existsSync(skillsRoot)) {
       for (const ent of fs.readdirSync(skillsRoot, { withFileTypes: true })) {
         if (!ent.isDirectory() || !/^oxe($|-)/.test(ent.name)) continue;

package/commands/oxe/debug.md

@@ -1,6 +1,11 @@
 ---
 name: oxe:debug
-description: "[DEPRECATED v1.1.0] Incorporado por /oxe-execute. Use: /oxe-execute --debug"
+description: >
+  Diagnóstica falhas com metodologia RCA: hipóteses explícitas → evidência → reprodução controlada
+  → causa raiz → hotfix mínimo. Não corrige sintomas — rasteia até a causa raiz antes de propor
+  qualquer mudança. Documenta o diagnóstico completo em DEBUG.md (sintoma, hipóteses testadas,
+  root cause, hotfix aplicado, evidência de resolução). Após o hotfix, orienta execução de
+  /oxe-verify para confirmar que os critérios A* afetados ainda passam.
 argument-hint: "[Tn ou erro/stack]"
 allowed-tools:
   - Read

package/commands/oxe/discuss.md

@@ -1,7 +1,12 @@
 ---
 name: oxe:discuss
-description: Perguntas objetivas antes do plano — .oxe/DISCUSS.md
-argument-hint: "[contexto ou respostas]"
+description: >
+  Conduz sessão estruturada de resolução de decisões técnicas antes do planejamento. Identifica
+  trade-offs relevantes, apresenta alternativas com critérios objetivos, registra a decisão
+  escolhida com motivo e impacto em DISCUSS.md como D-NN. Cada D-NN fechado aqui é vinculado a
+  tarefas Tn no PLAN.md e verificado pelo Verificador após execução. Usar quando: `discuss_before_plan`
+  está ativo no config, há decisão arquitetural aberta, ou o Arquiteto sinalizou bloqueio.
+argument-hint: "[decisão a tomar | contexto do trade-off | D-NN a reabrir]"
 allowed-tools:
   - Read
   - Bash

package/commands/oxe/execute.md

@@ -1,7 +1,12 @@
 ---
 name: oxe:execute
-description: "Executar plano A/B/C. Flags: --note (obs), --debug, --deep-diagnosis, --checkpoint '<nome>', --iterative"
-argument-hint: "[A|B|C | --note 'texto' | --debug | --deep-diagnosis | --checkpoint '<nome>' | --iterative]"
+description: >
+  Executa as tarefas do PLAN.md onda por onda, com write set mínimo e verificação obrigatória
+  antes de avançar. Compila o grafo de execução via LlmTaskExecutor, respeita dependências entre
+  tarefas, particiona tools idempotentes (paralelas) e mutáveis (seriais), e registra evidência
+  auditável por Tn. Modo --debug ativa diagnóstico de falha inline. --checkpoint '<nome>' cria
+  ponto de restauração antes de ondas de alto risco.
+argument-hint: "[onda|Tn | --debug | --deep-diagnosis | --checkpoint '<nome>' | --note 'texto' | --iterative]"
 allowed-tools:
   - Read
   - Bash

package/commands/oxe/plan-agent.md

@@ -1,7 +1,12 @@
 ---
 name: oxe:plan-agent
-description: Gera PLAN.md e plan-agents.json (blueprint de agentes e ondas)
-argument-hint: "[--replan se já existe PLAN.md]"
+description: >
+  Gera PLAN.md e plan-agents.json — blueprint de execução multi-agente com ondas paralelas.
+  Cada agente recebe persona (executor, db-specialist, ui-specialist, etc.), escopo de tarefas,
+  dependências entre agentes e lifecycle state rastreável. Ideal para planos com 3+ domínios
+  distintos (backend, frontend, banco) onde paralelismo real de agentes é possível. --replan
+  regenera o runId, preserva tarefas concluídas e alinha STATE.md.
+argument-hint: "[--replan | <contexto adicional de domínios>]"
 allowed-tools:
   - Read
   - Write

package/commands/oxe/plan.md

@@ -1,7 +1,12 @@
 ---
 name: oxe:plan
-description: Gera PLAN.md a partir da SPEC com tarefas atômicas e verificação por item
-argument-hint: "[--replan se já existe PLAN.md]"
+description: >
+  Decompõe os critérios A* da SPEC em tarefas GraphNode com mutation_scope explícito, action_type
+  correto e verify command determinístico. Projeta ondas que maximizam paralelismo respeitando
+  dependências e mutation_scope disjunto. Aplica rubrica de confiança em 6 dimensões e quality gate
+  de 19 itens. Gera IMPLEMENTATION-PACK, REFERENCE-ANCHORS e FIXTURE-PACK junto com o PLAN.md.
+  --replan preserva histórico e atualiza tarefas sem apagar o trabalho anterior.
+argument-hint: "[--replan | --agents (gera blueprint de agentes junto)]"
 allowed-tools:
   - Read
   - Write

package/commands/oxe/scan.md

@@ -1,6 +1,11 @@
 ---
 name: oxe:scan
-description: "[DEPRECATED v1.1.0] Incorporado por /oxe-spec. Use: /oxe-spec --refresh (incremental) ou /oxe-spec --full (completo)"
+description: >
+  Analisa o codebase e produz os sete documentos em .oxe/codebase/ (OVERVIEW, STACK, STRUCTURE,
+  TESTING, INTEGRATIONS, CONVENTIONS, CONCERNS). Detecta padrão arquitetural dominante, domínios
+  funcionais e sugere profile scale-adaptive. Modo bootstrap (do zero) ou refresh (incremental).
+  Cada documento passa por gate de qualidade com critérios e anti-padrões por tipo. O mapa
+  resultante alimenta spec, plan e o contexto do LlmTaskExecutor.
 argument-hint: "[área opcional, ex. auth, api]"
 allowed-tools:
   - Read

package/commands/oxe/spec.md

@@ -1,6 +1,11 @@
 ---
 name: oxe:spec
-description: "Spec em 5 fases. Flags: --refresh (scan incremental), --full (scan completo), --research (spike), --ui (gera UI-SPEC)"
+description: >
+  Conduz as 5 fases do processo de especificação: perguntas (blocos coesos por domínio), pesquisa
+  (investigação de incertezas técnicas), requisitos (tabela R-ID com v1/v2/fora e critérios A*
+  verificáveis), elevação de robustez (checklist de segurança por domínio AUTH/API/DB/FRONTEND/FILE),
+  e aprovação com roteiro ROADMAP.md. Flags: --refresh (atualiza codebase/ antes), --full (scan
+  completo), --research (Fase 2 explícita), --ui (gera UI-SPEC.md ao final).
 argument-hint: "[descrição da feature | --refresh | --full | --research | --ui]"
 allowed-tools:
   - Read

package/commands/oxe/verify.md

@@ -1,6 +1,11 @@
 ---
 name: oxe:verify
-description: "Valida e fecha o ciclo (retro automática). Flags: --gaps, --security, --ui, --pr, --diff, --skip-retro"
+description: >
+  Audita a implementação em quatro camadas: pré-execução (ambiente e commits), por tarefa Tn
+  (verify command de cada task), por critério A* (cobertura completa da SPEC), e fidelidade de
+  decisões D-NN. Produz VERIFY.md com evidência observável por critério, classifica findings por
+  severidade, gera checklist UAT para validação humana, e fecha o ciclo com retro automática.
+  --security adiciona auditoria de segurança baseline. --gaps foca em A* sem cobertura.
 argument-hint: "[Tn | --gaps | --security | --ui | --pr | --diff branchA...branchB | --skip-retro]"
 allowed-tools:
   - Read