oxe-cc 0.3.9 → 0.6.0

package/bin/banner.txt

@@ -15,4 +15,4 @@
 
 ══════════════════════════════════════════════════════
 
-                      v0.3.9
+                      v0.6.0

package/bin/lib/oxe-plugins.cjs

@@ -0,0 +1,226 @@
+'use strict';
+
+/**
+ * OXE Plugin System — carrega e executa plugins de `.oxe/plugins/`.
+ *
+ * Plugins são módulos CJS em `.oxe/plugins/*.cjs` que exportam hooks do ciclo de vida OXE.
+ * Cada hook é uma função assíncrona que recebe o contexto do evento.
+ *
+ * Hooks disponíveis:
+ *   - onBeforeScan(ctx)       — antes do workflow scan iniciar
+ *   - onAfterScan(ctx)        — após o scan produzir os 7 mapas
+ *   - onBeforeSpec(ctx)       — antes do workflow spec
+ *   - onAfterSpec(ctx)        — após SPEC.md ser gerado
+ *   - onBeforePlan(ctx)       — antes do workflow plan
+ *   - onAfterPlan(ctx)        — após PLAN.md ser gerado
+ *   - onPlanGenerated(ctx)    — alias de onAfterPlan
+ *   - onBeforeExecute(ctx)    — antes de iniciar uma onda
+ *   - onAfterExecute(ctx)     — após onda concluída
+ *   - onBeforeVerify(ctx)     — antes do workflow verify
+ *   - onAfterVerify(ctx)      — após VERIFY.md ser gerado
+ *   - onVerifyComplete(ctx)   — quando verify_complete
+ *   - onVerifyFailed(ctx)     — quando verify_failed
+ *   - onMilestoneNew(ctx)     — novo milestone criado
+ *   - onMilestoneComplete(ctx)— milestone encerrado
+ *   - onWorkstreamNew(ctx)    — novo workstream criado
+ *
+ * Exemplo de plugin (`.oxe/plugins/notify.cjs`):
+ * ```js
+ * module.exports = {
+ *   name: 'notify',
+ *   version: '1.0.0',
+ *   hooks: {
+ *     async onAfterVerify({ projectRoot, result }) {
+ *       if (result === 'verify_complete') {
+ *         console.log('[notify] Verificação concluída! 🎉');
+ *       }
+ *     },
+ *   },
+ * };
+ * ```
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * @typedef {{
+ *   name: string,
+ *   version?: string,
+ *   hooks: Record<string, (ctx: Record<string, unknown>) => Promise<void> | void>,
+ * }} OxePlugin
+ */
+
+/**
+ * Carrega todos os plugins de `.oxe/plugins/`.
+ *
+ * @param {string} projectRoot
+ * @returns {{ plugins: OxePlugin[], errors: Array<{ file: string, error: string }> }}
+ */
+function loadPlugins(projectRoot) {
+  const pluginsDir = path.join(projectRoot, '.oxe', 'plugins');
+  /** @type {OxePlugin[]} */
+  const plugins = [];
+  /** @type {Array<{ file: string, error: string }>} */
+  const errors = [];
+
+  if (!fs.existsSync(pluginsDir)) {
+    return { plugins, errors };
+  }
+
+  let files;
+  try {
+    files = fs.readdirSync(pluginsDir).filter((f) => f.endsWith('.cjs')).sort();
+  } catch (e) {
+    errors.push({ file: pluginsDir, error: String(e) });
+    return { plugins, errors };
+  }
+
+  for (const file of files) {
+    const fullPath = path.join(pluginsDir, file);
+    try {
+      // eslint-disable-next-line no-undef
+      const mod = require(fullPath);
+      if (!mod || typeof mod !== 'object') {
+        errors.push({ file, error: 'Plugin deve exportar um objeto' });
+        continue;
+      }
+      if (typeof mod.name !== 'string') {
+        errors.push({ file, error: 'Plugin deve exportar `name` (string)' });
+        continue;
+      }
+      if (!mod.hooks || typeof mod.hooks !== 'object') {
+        errors.push({ file, error: 'Plugin deve exportar `hooks` (objeto com funções)' });
+        continue;
+      }
+      plugins.push(mod);
+    } catch (e) {
+      errors.push({ file, error: String(e) });
+    }
+  }
+
+  return { plugins, errors };
+}
+
+/**
+ * Executa um hook específico em todos os plugins carregados.
+ * Erros em hooks individuais são capturados e não propagam.
+ *
+ * @param {OxePlugin[]} plugins
+ * @param {string} hookName
+ * @param {Record<string, unknown>} ctx
+ * @returns {Promise<Array<{ plugin: string, error: string }>>} erros de execução (não fatais)
+ */
+async function runHook(plugins, hookName, ctx) {
+  /** @type {Array<{ plugin: string, error: string }>} */
+  const hookErrors = [];
+  for (const plugin of plugins) {
+    const hook = plugin.hooks[hookName];
+    if (typeof hook !== 'function') continue;
+    try {
+      await hook(ctx);
+    } catch (e) {
+      hookErrors.push({ plugin: plugin.name, error: String(e) });
+    }
+  }
+  return hookErrors;
+}
+
+/**
+ * Valida a estrutura de todos os plugins em `.oxe/plugins/`.
+ *
+ * @param {string} projectRoot
+ * @returns {{ valid: boolean, issues: Array<{ file: string, issue: string }> }}
+ */
+function validatePlugins(projectRoot) {
+  const pluginsDir = path.join(projectRoot, '.oxe', 'plugins');
+  /** @type {Array<{ file: string, issue: string }>} */
+  const issues = [];
+
+  if (!fs.existsSync(pluginsDir)) {
+    return { valid: true, issues };
+  }
+
+  let files;
+  try {
+    files = fs.readdirSync(pluginsDir);
+  } catch {
+    return { valid: false, issues: [{ file: pluginsDir, issue: 'Não foi possível ler o diretório de plugins' }] };
+  }
+
+  const cjsFiles = files.filter((f) => f.endsWith('.cjs'));
+  const nonCjs = files.filter((f) => !f.endsWith('.cjs') && !f.startsWith('.') && f !== 'README.md');
+
+  for (const f of nonCjs) {
+    issues.push({ file: f, issue: 'Plugins devem ter extensão .cjs' });
+  }
+
+  const { errors } = loadPlugins(projectRoot);
+  for (const e of errors) {
+    issues.push({ file: e.file, issue: e.error });
+  }
+
+  if (cjsFiles.length > 20) {
+    issues.push({ file: pluginsDir, issue: `Muitos plugins (${cjsFiles.length}) — considere consolidar` });
+  }
+
+  return { valid: issues.length === 0, issues };
+}
+
+/**
+ * Cria o diretório de plugins com um README se não existir.
+ *
+ * @param {string} projectRoot
+ */
+function initPluginsDir(projectRoot) {
+  const pluginsDir = path.join(projectRoot, '.oxe', 'plugins');
+  if (!fs.existsSync(pluginsDir)) {
+    fs.mkdirSync(pluginsDir, { recursive: true });
+  }
+  const readme = path.join(pluginsDir, 'README.md');
+  if (!fs.existsSync(readme)) {
+    fs.writeFileSync(
+      readme,
+      `# .oxe/plugins/
+
+Coloque aqui plugins OXE em formato \`.cjs\`.
+
+## Estrutura mínima
+
+\`\`\`js
+// .oxe/plugins/meu-plugin.cjs
+module.exports = {
+  name: 'meu-plugin',
+  version: '1.0.0',
+  hooks: {
+    async onAfterVerify({ projectRoot, result }) {
+      // result: 'verify_complete' | 'verify_failed'
+      console.log('[meu-plugin] verify:', result);
+    },
+  },
+};
+\`\`\`
+
+## Hooks disponíveis
+
+- onBeforeScan, onAfterScan
+- onBeforeSpec, onAfterSpec
+- onBeforePlan, onAfterPlan, onPlanGenerated
+- onBeforeExecute, onAfterExecute
+- onBeforeVerify, onAfterVerify, onVerifyComplete, onVerifyFailed
+- onMilestoneNew, onMilestoneComplete
+- onWorkstreamNew
+
+Ver documentação completa: \`oxe/templates/PLUGINS.md\` (no pacote npm).
+`,
+      'utf8'
+    );
+  }
+}
+
+module.exports = {
+  loadPlugins,
+  runHook,
+  validatePlugins,
+  initPluginsDir,
+};

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

@@ -8,6 +8,7 @@ const ALLOWED_CONFIG_KEYS = [
   'discuss_before_plan',
   'after_verify_suggest_pr',
   'after_verify_draft_commit',
+  'after_verify_suggest_uat',
   'default_verify_command',
   'scan_max_age_days',
   'compact_max_age_days',
@@ -15,9 +16,26 @@ const ALLOWED_CONFIG_KEYS = [
   'scan_ignore_globs',
   'spec_required_sections',
   'plan_max_tasks_per_wave',
+  'profile',
+  'verification_depth',
   'install',
+  'plugins',
+  'workstreams',
+  'milestones',
+  'scale_adaptive',
 ];
 
+/**
+ * Profiles de execução OXE que controlam rigor do workflow.
+ * Expansão de keys: profile 'strict' liga discuss_before_plan, verification_depth thorough, etc.
+ */
+const EXECUTION_PROFILES = ['strict', 'balanced', 'fast', 'legacy'];
+
+/**
+ * Profundidade de verificação.
+ */
+const VERIFICATION_DEPTHS = ['standard', 'thorough', 'quick'];
+
 /** Perfis de integração lidos de `.oxe/config.json` → `install.profile` (CLI explícita prevalece). */
 const INSTALL_PROFILES = ['recommended', 'cursor', 'copilot', 'core', 'cli', 'all_agents'];
 
@@ -37,6 +55,57 @@ const EXPECTED_CODEBASE_MAPS = [
   'CONCERNS.md',
 ];
 
+/**
+ * @param {string} targetProject
+ */
+/**
+ * Expande um profile de execução nas suas keys individuais.
+ * Keys explícitas no config prevalecem sobre o profile.
+ * @param {string} profile
+ * @returns {Record<string, unknown>}
+ */
+function expandExecutionProfile(profile) {
+  const profiles = {
+    strict: {
+      discuss_before_plan: true,
+      verification_depth: 'thorough',
+      after_verify_suggest_uat: true,
+      after_verify_suggest_pr: true,
+      after_verify_draft_commit: true,
+      scan_max_age_days: 14,
+      compact_max_age_days: 30,
+    },
+    balanced: {
+      discuss_before_plan: false,
+      verification_depth: 'standard',
+      after_verify_suggest_uat: false,
+      after_verify_suggest_pr: true,
+      after_verify_draft_commit: true,
+      scan_max_age_days: 0,
+      compact_max_age_days: 0,
+    },
+    fast: {
+      discuss_before_plan: false,
+      verification_depth: 'quick',
+      after_verify_suggest_uat: false,
+      after_verify_suggest_pr: false,
+      after_verify_draft_commit: true,
+      scan_max_age_days: 0,
+      compact_max_age_days: 0,
+    },
+    legacy: {
+      discuss_before_plan: true,
+      verification_depth: 'thorough',
+      after_verify_suggest_uat: true,
+      after_verify_suggest_pr: false,
+      after_verify_draft_commit: false,
+      scan_max_age_days: 0,
+      compact_max_age_days: 0,
+    },
+  };
+  return profiles[profile] || {};
+}
+
 /**
  * @param {string} targetProject
  */
@@ -45,6 +114,8 @@ function loadOxeConfigMerged(targetProject) {
     discuss_before_plan: false,
     after_verify_suggest_pr: true,
     after_verify_draft_commit: true,
+    after_verify_suggest_uat: false,
+    verification_depth: 'standard',
     default_verify_command: '',
     scan_max_age_days: 0,
     compact_max_age_days: 0,
@@ -59,7 +130,9 @@ function loadOxeConfigMerged(targetProject) {
     const raw = fs.readFileSync(p, 'utf8');
     const j = JSON.parse(raw);
     if (!j || typeof j !== 'object' || Array.isArray(j)) return { config: defaults, path: p, parseError: 'não é um objeto' };
-    return { config: { ...defaults, ...j }, path: p, parseError: null };
+    // Expandir profile antes de mesclar com o config explícito (keys explícitas prevalecem)
+    const profileExpansion = (typeof j.profile === 'string') ? expandExecutionProfile(j.profile) : {};
+    return { config: { ...defaults, ...profileExpansion, ...j }, path: p, parseError: null };
   } catch (e) {
     return { config: defaults, path: p, parseError: e.message };
   }
@@ -129,6 +202,26 @@ function validateConfigShape(cfg) {
   if (cfg.spec_required_sections != null && !Array.isArray(cfg.spec_required_sections)) {
     typeErrors.push('spec_required_sections deve ser array de strings (cabeçalhos ## …)');
   }
+  if (cfg.profile != null) {
+    if (typeof cfg.profile !== 'string') {
+      typeErrors.push('profile deve ser string');
+    } else if (!EXECUTION_PROFILES.includes(cfg.profile)) {
+      typeErrors.push(`profile deve ser um de: ${EXECUTION_PROFILES.join(', ')}`);
+    }
+  }
+  if (cfg.verification_depth != null) {
+    if (typeof cfg.verification_depth !== 'string') {
+      typeErrors.push('verification_depth deve ser string');
+    } else if (!VERIFICATION_DEPTHS.includes(cfg.verification_depth)) {
+      typeErrors.push(`verification_depth deve ser um de: ${VERIFICATION_DEPTHS.join(', ')}`);
+    }
+  }
+  if (cfg.after_verify_suggest_uat != null && typeof cfg.after_verify_suggest_uat !== 'boolean') {
+    typeErrors.push('after_verify_suggest_uat deve ser boolean');
+  }
+  if (cfg.scale_adaptive != null && typeof cfg.scale_adaptive !== 'boolean') {
+    typeErrors.push('scale_adaptive deve ser boolean');
+  }
   return { unknownKeys, typeErrors };
 }
 
@@ -504,10 +597,13 @@ function buildHealthReport(target) {
 
 module.exports = {
   ALLOWED_CONFIG_KEYS,
+  EXECUTION_PROFILES,
+  VERIFICATION_DEPTHS,
   INSTALL_PROFILES,
   INSTALL_REPO_LAYOUTS,
   INSTALL_OBJECT_KEYS,
   EXPECTED_CODEBASE_MAPS,
+  expandExecutionProfile,
   loadOxeConfigMerged,
   validateConfigShape,
   parseStatePhase,

package/bin/lib/oxe-security.cjs

@@ -0,0 +1,225 @@
+'use strict';
+
+/**
+ * OXE Security — validação de caminhos e detecção de padrões sensíveis.
+ * Usado pelo SDK e opcionalmente pelos workflows via `oxe-cc doctor`.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Padrões de arquivos sensíveis que não devem aparecer em commits ou outputs.
+ * @type {RegExp[]}
+ */
+const DEFAULT_SECRET_PATTERNS = [
+  /\.env(\.\w+)?$/i,
+  /secrets?\.(json|yaml|yml|toml|ini)$/i,
+  /credentials?\.(json|yaml|yml)$/i,
+  /\.pem$/i,
+  /\.key$/i,
+  /id_(rsa|ecdsa|ed25519)(\.pub)?$/i,
+  /\.pfx$/i,
+  /\.p12$/i,
+  /serviceAccountKey\.json$/i,
+  /firebase-adminsdk.*\.json$/i,
+  /aws-credentials/i,
+  /\.npmrc$/i,
+  /\.netrc$/i,
+  /htpasswd/i,
+  /vault[_-]token/i,
+];
+
+/**
+ * Padrões de conteúdo que indicam segredos inline.
+ * @type {RegExp[]}
+ */
+const DEFAULT_SECRET_CONTENT_PATTERNS = [
+  /(?:password|passwd|secret|token|api[_-]?key|access[_-]?key|private[_-]?key)\s*[:=]\s*["']?[^\s"']{8,}/i,
+  /(?:BEGIN\s+(?:RSA|EC|OPENSSH|PGP)\s+PRIVATE\s+KEY)/i,
+  /(?:AKIA|ASIA)[A-Z0-9]{16}/,  // AWS access key
+  /eyJ[a-zA-Z0-9_-]+\.eyJ[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+/,  // JWT
+  /ghp_[a-zA-Z0-9]{36}/,  // GitHub Personal Access Token
+  /ghs_[a-zA-Z0-9]{36}/,  // GitHub App Token
+  /glpat-[a-zA-Z0-9\-_]{20}/,  // GitLab PAT
+];
+
+/**
+ * Caminhos sempre negados (nunca devem ser lidos/escritos por workflows).
+ * @type {RegExp[]}
+ */
+const DEFAULT_DENIED_PATH_PATTERNS = [
+  /node_modules[/\\]/,
+  /\.git[/\\]/,
+  /dist[/\\]/,
+  /build[/\\]/,
+  /coverage[/\\]/,
+  /\.cache[/\\]/,
+];
+
+/**
+ * Verifica se um caminho é seguro para uso em workflows.
+ *
+ * @param {string} filePath - Caminho a verificar (absoluto ou relativo ao projeto).
+ * @param {string} projectRoot - Raiz do projeto.
+ * @param {{
+ *   allowedRoots?: string[],
+ *   deniedPatterns?: RegExp[],
+ *   secretPatterns?: RegExp[],
+ * }} [options]
+ * @returns {{ safe: boolean, reason: string | null }}
+ */
+function checkPathSafety(filePath, projectRoot, options = {}) {
+  const deniedPatterns = options.deniedPatterns || DEFAULT_DENIED_PATH_PATTERNS;
+  const secretPatterns = options.secretPatterns || DEFAULT_SECRET_PATTERNS;
+
+  const resolved = path.isAbsolute(filePath)
+    ? path.normalize(filePath)
+    : path.normalize(path.join(projectRoot, filePath));
+
+  // Verifica path traversal
+  const normalizedRoot = path.normalize(projectRoot);
+  if (!resolved.startsWith(normalizedRoot)) {
+    return {
+      safe: false,
+      reason: `Path traversal detectado: "${filePath}" sai da raiz do projeto`,
+    };
+  }
+
+  // Verifica padrões negados
+  const relative = path.relative(normalizedRoot, resolved);
+  for (const pattern of deniedPatterns) {
+    if (pattern.test(relative)) {
+      return {
+        safe: false,
+        reason: `Caminho em área negada (${pattern}): "${relative}"`,
+      };
+    }
+  }
+
+  // Verifica padrões de segredos por nome de arquivo
+  const basename = path.basename(resolved);
+  for (const pattern of secretPatterns) {
+    if (pattern.test(basename)) {
+      return {
+        safe: false,
+        reason: `Nome de arquivo indica segredo (${pattern}): "${basename}"`,
+      };
+    }
+  }
+
+  return { safe: true, reason: null };
+}
+
+/**
+ * Escaneia um arquivo em busca de padrões de segredos inline.
+ *
+ * @param {string} filePath - Caminho absoluto ao arquivo.
+ * @param {{ contentPatterns?: RegExp[] }} [options]
+ * @returns {{ hasSecrets: boolean, matches: Array<{ line: number, pattern: string, preview: string }> }}
+ */
+function scanFileForSecrets(filePath, options = {}) {
+  const contentPatterns = options.contentPatterns || DEFAULT_SECRET_CONTENT_PATTERNS;
+
+  if (!fs.existsSync(filePath)) {
+    return { hasSecrets: false, matches: [] };
+  }
+
+  let content;
+  try {
+    content = fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return { hasSecrets: false, matches: [] };
+  }
+
+  /** @type {Array<{ line: number, pattern: string, preview: string }>} */
+  const matches = [];
+  const lines = content.split('\n');
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    for (const pattern of contentPatterns) {
+      if (pattern.test(line)) {
+        matches.push({
+          line: i + 1,
+          pattern: pattern.toString(),
+          preview: line.trim().slice(0, 80) + (line.trim().length > 80 ? '…' : ''),
+        });
+        break; // Um match por linha é suficiente
+      }
+    }
+  }
+
+  return { hasSecrets: matches.length > 0, matches };
+}
+
+/**
+ * Escaneia um diretório em busca de arquivos com nomes de segredos.
+ *
+ * @param {string} dir - Diretório a escanear.
+ * @param {{ secretPatterns?: RegExp[], maxDepth?: number }} [options]
+ * @returns {string[]} Lista de caminhos relativos com problemas.
+ */
+function scanDirForSecretFiles(dir, options = {}) {
+  const secretPatterns = options.secretPatterns || DEFAULT_SECRET_PATTERNS;
+  const maxDepth = options.maxDepth ?? 4;
+  /** @type {string[]} */
+  const found = [];
+
+  function walk(current, depth) {
+    if (depth > maxDepth) return;
+    let entries;
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name.startsWith('.') && depth > 0) continue;
+      if (entry.name === 'node_modules' || entry.name === '.git') continue;
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        walk(full, depth + 1);
+      } else {
+        for (const pattern of secretPatterns) {
+          if (pattern.test(entry.name)) {
+            found.push(path.relative(dir, full));
+            break;
+          }
+        }
+      }
+    }
+  }
+
+  walk(dir, 0);
+  return found;
+}
+
+/**
+ * Valida que um conjunto de caminhos (do PLAN.md) são seguros.
+ *
+ * @param {string[]} filePaths
+ * @param {string} projectRoot
+ * @returns {{ ok: boolean, issues: Array<{ path: string, reason: string }> }}
+ */
+function validatePlanPaths(filePaths, projectRoot) {
+  /** @type {Array<{ path: string, reason: string }>} */
+  const issues = [];
+  for (const fp of filePaths) {
+    const check = checkPathSafety(fp, projectRoot);
+    if (!check.safe) {
+      issues.push({ path: fp, reason: check.reason || 'caminho inseguro' });
+    }
+  }
+  return { ok: issues.length === 0, issues };
+}
+
+module.exports = {
+  checkPathSafety,
+  scanFileForSecrets,
+  scanDirForSecretFiles,
+  validatePlanPaths,
+  DEFAULT_SECRET_PATTERNS,
+  DEFAULT_SECRET_CONTENT_PATTERNS,
+  DEFAULT_DENIED_PATH_PATTERNS,
+};

package/bin/oxe-cc.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 /**
  * OXE — CLI em pt-BR: instala workflows no projeto, bootstrap `.oxe/`, doctor, uninstall, update.
  * Uso: npx oxe-cc, doctor, status, init-oxe, uninstall, update (ver --help).
@@ -1048,6 +1048,30 @@ function bootstrapOxe(target, opts) {
     }
   }
 
+  // Criar estruturas opcionais: plugins/, workstreams/, memory/
+  const pluginsDir = path.join(oxeDir, 'plugins');
+  if (!fs.existsSync(pluginsDir)) {
+    ensureDir(pluginsDir);
+    const pluginsReadme = path.join(PKG_ROOT, 'oxe', 'templates', 'PLUGINS.md');
+    if (fs.existsSync(pluginsReadme)) {
+      const destPluginsReadme = path.join(pluginsDir, 'README.md');
+      if (!fs.existsSync(destPluginsReadme)) {
+        copyFile(pluginsReadme, destPluginsReadme, { dryRun: false });
+        console.log(`${green}init${reset}  ${destPluginsReadme}`);
+      }
+    }
+  }
+
+  const workstreamsDir = path.join(oxeDir, 'workstreams');
+  if (!fs.existsSync(workstreamsDir)) {
+    ensureDir(workstreamsDir);
+  }
+
+  const memoryDir = path.join(oxeDir, 'memory');
+  if (!fs.existsSync(memoryDir)) {
+    ensureDir(memoryDir);
+  }
+
   ensureGitignoreIgnoresOxeDir(target, { dryRun: false });
 }
 
@@ -1596,6 +1620,11 @@ function runInstall(opts) {
     const nested = path.join(target, '.oxe');
     copyDir(path.join(PKG_ROOT, 'oxe', 'workflows'), path.join(nested, 'workflows'), copyOpts, true);
     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);
+    }
   }
 
   const cursorBase = installCursorBase(opts);

package/commands/oxe/execute.md

@@ -1,16 +1,16 @@
----
-name: oxe:execute
-description: Executar onda do PLAN.md ou passos do QUICK.md
-argument-hint: "[opcional: onda ou Tn]"
-allowed-tools:
-  - Read
-  - Bash
-  - Glob
-  - Grep
-  - Write
-  - Task
----
-
-**Workflow canónico:** `oxe/workflows/execute.md`
-
-Execute integralmente esse ficheiro na raiz do repositório em que estás a trabalhar. Usa `$ARGUMENTS` como foco (onda, tarefa, confirmação).
+---
+name: oxe:execute
+description: "Executar plano (solo ou com agentes): escolha Completo (1 sessão) | Por onda | Por tarefa — controle explícito de requisições"
+argument-hint: "[A=completo | B=por-onda | C=por-tarefa | onda N | Tn]"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Task
+---
+
+**Workflow canónico:** `oxe/workflows/execute.md`
+
+Execute integralmente esse ficheiro na raiz do repositório em que estás a trabalhar. Usa `$ARGUMENTS` como foco (onda, tarefa, confirmação).