oxe-cc 0.3.8 → 0.5.0

package/commands/oxe/obs.md

@@ -0,0 +1,16 @@
+---
+name: oxe:obs
+description: "Observação contextual — registra em .oxe/OBSERVATIONS.md, incorporada automaticamente no próximo spec/plan/execute sem re-explicar"
+argument-hint: "[observação: restrição, descoberta, preferência, risco ou decisão]"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Task
+---
+
+**Workflow canónico:** `oxe/workflows/obs.md`
+
+Execute integralmente esse ficheiro na raiz do repositório em que estás a trabalhar. Usa o texto em `$ARGUMENTS` como a observação a registrar.

package/commands/oxe/quick.md

@@ -1,16 +1,16 @@
----
-name: oxe:quick
-description: Modo rápido — .oxe/QUICK.md + STATE (sem SPEC/PLAN longos)
-argument-hint: "[objetivo]"
-allowed-tools:
-  - Read
-  - Bash
-  - Glob
-  - Grep
-  - Write
-  - Task
----
-
-**Workflow canónico:** `oxe/workflows/quick.md`
-
-Execute integralmente esse ficheiro na raiz do repositório em que estás a trabalhar. Usa o texto em `$ARGUMENTS` como objetivo e contexto.
+---
+name: oxe:quick
+description: "Modo rápido com Plan-Driven Dynamic Agents lean — minispec (objetivo) + mini-plano (passos) + agentes dinâmicos por domínio (opcional) + verificar"
+argument-hint: "[objetivo] [--agents]"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Task
+---
+
+**Workflow canónico:** `oxe/workflows/quick.md`
+
+Execute integralmente esse ficheiro na raiz do repositório em que estás a trabalhar. Usa o texto em `$ARGUMENTS` como objetivo e contexto.

package/commands/oxe/spec.md

@@ -1,7 +1,7 @@
 ---
 name: oxe:spec
-description: Transforma o pedido do usuário em SPEC.md (escopo, aceite, não-objetivos)
-argument-hint: "[texto do pedido ou @arquivo.md]"
+description: "Spec em 5 fases: perguntas → pesquisa → requisitos R-ID (v1/v2/fora) → roteiro ROADMAP.md → aprovação → plan"
+argument-hint: "[descrição da feature, ideia ou @arquivo.md com PRD]"
 allowed-tools:
   - Read
   - Write

package/commands/oxe/workstream.md

@@ -0,0 +1,16 @@
+---
+name: oxe:workstream
+description: "Trilhas paralelas — list, new <nome>, switch <nome>, status, close <nome> — artefatos independentes em .oxe/workstreams/<nome>/"
+argument-hint: "list | new <nome> | switch <nome> | status | close <nome>"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Task
+---
+
+**Workflow canónico:** `oxe/workflows/workstream.md`
+
+Execute integralmente esse ficheiro na raiz do repositório em que estás a trabalhar. Usa o texto em `$ARGUMENTS` como subcomando e contexto.

package/lib/sdk/index.cjs

@@ -12,6 +12,8 @@ const manifest = require('../../bin/lib/oxe-manifest.cjs');
 const workflows = require('../../bin/lib/oxe-workflows.cjs');
 const installResolve = require('../../bin/lib/oxe-install-resolve.cjs');
 const agentInstall = require('../../bin/lib/oxe-agent-install.cjs');
+const security = require('../../bin/lib/oxe-security.cjs');
+const plugins = require('../../bin/lib/oxe-plugins.cjs');
 
 const PACKAGE_ROOT = path.join(__dirname, '..', '..');
 
@@ -38,6 +40,224 @@ function readMinNode(packageRoot) {
   }
 }
 
+/**
+ * Faz parse de um PLAN.md e extrai tarefas estruturadas.
+ *
+ * @param {string} planMd - Conteúdo do PLAN.md (string).
+ * @returns {{
+ *   tasks: Array<{
+ *     id: string,
+ *     title: string,
+ *     wave: number | null,
+ *     dependsOn: string[],
+ *     files: string[],
+ *     verifyCommand: string | null,
+ *     aceite: string[],
+ *     decisions: string[],
+ *     done: boolean,
+ *     meta: Record<string, unknown> | null,
+ *   }>,
+ *   waves: Record<number, string[]>,
+ *   totalTasks: number,
+ * }}
+ */
+function parsePlan(planMd) {
+  const parts = planMd.split(/^###\s+(T\d+)\s*[—-]\s*/m);
+  /** @type {ReturnType<typeof parsePlan>['tasks']} */
+  const tasks = [];
+  /** @type {Record<number, string[]>} */
+  const waves = {};
+
+  for (let i = 1; i < parts.length; i += 2) {
+    const id = parts[i].trim();
+    const rest = (parts[i + 1] || '').split(/^###\s+T\d+/m)[0];
+    const titleMatch = rest.match(/^([^\n]+)/);
+    const title = titleMatch ? titleMatch[1].trim() : '';
+
+    const waveMatch = rest.match(/\*\*Onda:\*\*\s*(\d+)/i);
+    const wave = waveMatch ? parseInt(waveMatch[1], 10) : null;
+
+    const depsMatch = rest.match(/\*\*Depende\s+de:\*\*\s*([^\n]+)/i);
+    const dependsOn = depsMatch
+      ? depsMatch[1].split(/[,\s]+/).filter((s) => /^T\d+$/.test(s.trim()))
+      : [];
+
+    const filesMatch = rest.match(/\*\*Arquivos\s+prováveis:\*\*\s*([^\n]+)/i);
+    const files = filesMatch
+      ? filesMatch[1].match(/`([^`]+)`/g)?.map((s) => s.replace(/`/g, '')) || []
+      : [];
+
+    const verifyCmdMatch = rest.match(/Comando:\s*`([^`]+)`/i);
+    const verifyCommand = verifyCmdMatch ? verifyCmdMatch[1] : null;
+
+    const aceiteMatch = rest.match(/\*\*Aceite\s+vinculado:\*\*\s*([^\n]+)/i);
+    const aceite = aceiteMatch
+      ? aceiteMatch[1].match(/A\d+/g) || []
+      : [];
+
+    const decisionsMatch = rest.match(/\*\*Decisão\s+vinculada:\*\*\s*([^\n]+)/i);
+    const decisions = decisionsMatch
+      ? decisionsMatch[1].match(/D-\d+/g) || []
+      : [];
+
+    // Parse do metadado JSON em comentário HTML <!-- oxe-task: {...} -->
+    const metaMatch = rest.match(/<!--\s*oxe-task:\s*(\{[\s\S]*?\})\s*-->/);
+    let meta = null;
+    if (metaMatch) {
+      try {
+        meta = JSON.parse(metaMatch[1]);
+      } catch {
+        meta = null;
+      }
+    }
+
+    const done = meta?.done === true;
+
+    const task = { id, title, wave, dependsOn, files, verifyCommand, aceite, decisions, done, meta };
+    tasks.push(task);
+
+    if (wave != null) {
+      if (!waves[wave]) waves[wave] = [];
+      waves[wave].push(id);
+    }
+  }
+
+  return { tasks, waves, totalTasks: tasks.length };
+}
+
+/**
+ * Faz parse de um SPEC.md e extrai critérios de aceite.
+ *
+ * @param {string} specMd - Conteúdo do SPEC.md.
+ * @returns {{
+ *   objective: string | null,
+ *   criteria: Array<{ id: string, criterion: string, howToVerify: string }>,
+ *   requiredSections: string[],
+ * }}
+ */
+function parseSpec(specMd) {
+  // Objetivo
+  const objMatch = specMd.match(/##\s*Objetivo\s*\n+([\s\S]*?)(?=\n##\s|\n#[^\#]|$)/im);
+  const objective = objMatch ? objMatch[1].trim().split('\n')[0].trim() : null;
+
+  // Tabela de critérios
+  /** @type {Array<{ id: string, criterion: string, howToVerify: string }>} */
+  const criteria = [];
+  const tableMatch = specMd.match(/##\s*Critérios.*?aceite[\s\S]*?(\|[\s\S]*?)(?=\n##\s|\n#[^\#]|$)/im);
+  if (tableMatch) {
+    const rows = tableMatch[1].split('\n').filter((l) => l.startsWith('|'));
+    for (const row of rows) {
+      const cells = row.split('|').map((c) => c.trim()).filter(Boolean);
+      if (cells.length >= 2 && /^A\d+$/i.test(cells[0])) {
+        criteria.push({
+          id: cells[0],
+          criterion: cells[1] || '',
+          howToVerify: cells[2] || '',
+        });
+      }
+    }
+  }
+
+  // Seções presentes (para validação spec_required_sections)
+  const headings = [];
+  for (const m of specMd.matchAll(/^##\s+(.+)/gm)) {
+    headings.push(`## ${m[1].trim()}`);
+  }
+
+  return { objective, criteria, requiredSections: headings };
+}
+
+/**
+ * Faz parse do STATE.md e extrai fase, data do scan e próximo passo.
+ *
+ * @param {string} stateMd - Conteúdo do STATE.md.
+ * @returns {{
+ *   phase: string | null,
+ *   lastScanDate: string | null,
+ *   nextStep: string | null,
+ *   decisions: string[],
+ *   activeWorkstreams: string[],
+ *   activeMilestone: string | null,
+ * }}
+ */
+function parseState(stateMd) {
+  const phase = health.parseStatePhase(stateMd);
+
+  const scanDate = health.parseLastScanDate(stateMd);
+  const lastScanDate = scanDate ? scanDate.toISOString().split('T')[0] : null;
+
+  const nextStepMatch = stateMd.match(/##\s*Próximo passo sugerido\s*\n+([\s\S]*?)(?=\n##\s|\n#[^\#]|$)/im);
+  const nextStep = nextStepMatch ? nextStepMatch[1].trim().split('\n')[0].replace(/^[-*]\s*/, '').trim() : null;
+
+  // Decisões persistentes (seção opcional)
+  const decisionsMatch = stateMd.match(/##\s*Decisões persistentes\s*\n+([\s\S]*?)(?=\n##\s|\n#[^\#]|$)/im);
+  const decisions = decisionsMatch
+    ? decisionsMatch[1].match(/D-\d+[^)]*\)/g) || decisionsMatch[1].match(/D-\d+[^\n]*/g) || []
+    : [];
+
+  // Workstreams ativos (seção opcional)
+  const wsMatch = stateMd.match(/##\s*Workstreams ativos\s*\n+([\s\S]*?)(?=\n##\s|\n#[^\#]|$)/im);
+  const activeWorkstreams = wsMatch
+    ? wsMatch[1].match(/`([^`]+)`/g)?.map((s) => s.replace(/`/g, '')) || []
+    : [];
+
+  // Milestone ativo
+  const msMatch = stateMd.match(/##\s*Milestone ativo\s*\n+[^`]*`([^`]+)`/im);
+  const activeMilestone = msMatch ? msMatch[1] : null;
+
+  return { phase, lastScanDate, nextStep, decisions, activeWorkstreams, activeMilestone };
+}
+
+/**
+ * Valida fidelidade entre decisões do DISCUSS.md e tarefas do PLAN.md.
+ * Retorna gaps onde decisões D-NN não têm tarefa vinculada.
+ *
+ * @param {string} discussMd - Conteúdo do DISCUSS.md.
+ * @param {string} planMd - Conteúdo do PLAN.md.
+ * @returns {{
+ *   ok: boolean,
+ *   gaps: Array<{ decisionId: string, decision: string }>,
+ *   covered: Array<{ decisionId: string, taskIds: string[] }>,
+ * }}
+ */
+function validateDecisionFidelity(discussMd, planMd) {
+  // Extrair decisões da tabela D-NN
+  const decisionRows = [];
+  const tableMatch = discussMd.match(/##\s*Decisões[\s\S]*?(\|[\s\S]*?)(?=\n##\s|\n#[^\#]|$)/im);
+  if (tableMatch) {
+    const rows = tableMatch[1].split('\n').filter((l) => l.startsWith('|'));
+    for (const row of rows) {
+      const cells = row.split('|').map((c) => c.trim()).filter(Boolean);
+      if (cells.length >= 2 && /^D-\d+$/i.test(cells[0])) {
+        decisionRows.push({ id: cells[0], text: cells[1] || '' });
+      }
+    }
+  }
+
+  if (!decisionRows.length) return { ok: true, gaps: [], covered: [] };
+
+  const { tasks } = parsePlan(planMd);
+
+  /** @type {ReturnType<typeof validateDecisionFidelity>['gaps']} */
+  const gaps = [];
+  /** @type {ReturnType<typeof validateDecisionFidelity>['covered']} */
+  const covered = [];
+
+  for (const dec of decisionRows) {
+    // Ignorar decisões revertidas
+    if (/revertida/i.test(dec.text)) continue;
+
+    const tasksCovering = tasks.filter((t) => t.decisions.includes(dec.id));
+    if (tasksCovering.length === 0) {
+      gaps.push({ decisionId: dec.id, decision: dec.text });
+    } else {
+      covered.push({ decisionId: dec.id, taskIds: tasksCovering.map((t) => t.id) });
+    }
+  }
+
+  return { ok: gaps.length === 0, gaps, covered };
+}
+
 /**
  * Verificações alinhadas ao `oxe-cc doctor`, com resultado estruturado (CI / gateways).
  *
@@ -47,6 +267,7 @@ function readMinNode(packageRoot) {
  *   nodeMajor?: number,
  *   includeWorkflowLint?: boolean,
  *   workflowLintOptions?: { maxBytesSoft?: number },
+ *   includeSecurity?: boolean,
  * }} args
  * @returns {{
  *   ok: boolean,
@@ -60,6 +281,7 @@ function readMinNode(packageRoot) {
  *   validation: ReturnType<typeof health.validateConfigShape>,
  *   healthReport: ReturnType<typeof health.buildHealthReport>,
  *   workflowShape: ReturnType<typeof workflows.validateWorkflowShapes> | null,
+ *   securityReport: { secretFiles: string[], pluginsValid: boolean } | null,
  * }}
  */
 function runDoctorChecks(args) {
@@ -157,6 +379,39 @@ function runDoctorChecks(args) {
     }
   }
 
+  // Verificações de segurança (opcional, ativado por padrão)
+  let securityReport = null;
+  if (args.includeSecurity !== false) {
+    const secretFiles = security.scanDirForSecretFiles(projectRoot, { maxDepth: 3 });
+    if (secretFiles.length > 0) {
+      warnings.push({
+        code: 'SECURITY_SECRET_FILES',
+        message: `Arquivos com nomes sensíveis detectados: ${secretFiles.join(', ')}`,
+        detail: { files: secretFiles },
+      });
+    }
+
+    // Verificar plugins se existirem
+    const pluginsDir = path.join(projectRoot, '.oxe', 'plugins');
+    let pluginsValid = true;
+    if (fs.existsSync(pluginsDir)) {
+      const pluginFiles = fs.readdirSync(pluginsDir).filter((f) => f.endsWith('.cjs'));
+      for (const pf of pluginFiles) {
+        const pluginPath = path.join(pluginsDir, pf);
+        const safetyCheck = security.checkPathSafety(pluginPath, projectRoot);
+        if (!safetyCheck.safe) {
+          pluginsValid = false;
+          warnings.push({
+            code: 'SECURITY_PLUGIN_PATH',
+            message: `Plugin com caminho inseguro: ${pf} — ${safetyCheck.reason}`,
+          });
+        }
+      }
+    }
+
+    securityReport = { secretFiles, pluginsValid };
+  }
+
   return {
     ok: errors.length === 0,
     errors,
@@ -169,6 +424,7 @@ function runDoctorChecks(args) {
     validation,
     healthReport,
     workflowShape,
+    securityReport,
   };
 }
 
@@ -184,6 +440,12 @@ module.exports = {
   readPackageMeta,
   readMinNode,
 
+  /** Parsing de artefatos OXE (PLAN, SPEC, STATE). */
+  parsePlan,
+  parseSpec,
+  parseState,
+  validateDecisionFidelity,
+
   /** Estado do projeto, SPEC/PLAN, fase, config. */
   health: {
     loadOxeConfigMerged: health.loadOxeConfigMerged,
@@ -200,7 +462,10 @@ module.exports = {
     planWaveWarningsFixed: health.planWaveWarningsFixed,
     planTaskAceiteWarnings: health.planTaskAceiteWarnings,
     verifyGapsWithoutSummaryWarning: health.verifyGapsWithoutSummaryWarning,
+    expandExecutionProfile: health.expandExecutionProfile,
     ALLOWED_CONFIG_KEYS: health.ALLOWED_CONFIG_KEYS,
+    EXECUTION_PROFILES: health.EXECUTION_PROFILES,
+    VERIFICATION_DEPTHS: health.VERIFICATION_DEPTHS,
     INSTALL_PROFILES: health.INSTALL_PROFILES,
     INSTALL_REPO_LAYOUTS: health.INSTALL_REPO_LAYOUTS,
     INSTALL_OBJECT_KEYS: health.INSTALL_OBJECT_KEYS,
@@ -238,6 +503,25 @@ module.exports = {
     parseCursorCommandFrontmatter: agentInstall.parseCursorCommandFrontmatter,
   },
 
+  /** Segurança: validação de caminhos e detecção de segredos. */
+  security: {
+    checkPathSafety: security.checkPathSafety,
+    scanFileForSecrets: security.scanFileForSecrets,
+    scanDirForSecretFiles: security.scanDirForSecretFiles,
+    validatePlanPaths: security.validatePlanPaths,
+    DEFAULT_SECRET_PATTERNS: security.DEFAULT_SECRET_PATTERNS,
+    DEFAULT_SECRET_CONTENT_PATTERNS: security.DEFAULT_SECRET_CONTENT_PATTERNS,
+    DEFAULT_DENIED_PATH_PATTERNS: security.DEFAULT_DENIED_PATH_PATTERNS,
+  },
+
+  /** Plugin system — hooks de ciclo de vida em `.oxe/plugins/*.cjs`. */
+  plugins: {
+    loadPlugins: plugins.loadPlugins,
+    runHook: plugins.runHook,
+    validatePlugins: plugins.validatePlugins,
+    initPluginsDir: plugins.initPluginsDir,
+  },
+
   /** Um único objeto com verificações tipo `doctor` + relatório de saúde. */
   runDoctorChecks,
 };

package/lib/sdk/index.d.ts

@@ -65,6 +65,11 @@ export interface OxeHealthReport {
   scanIgnoreGlobs?: unknown;
 }
 
+export interface SecurityReport {
+  secretFiles: string[];
+  pluginsValid: boolean;
+}
+
 export interface DoctorChecksResult {
   ok: boolean;
   errors: DoctorIssue[];
@@ -81,6 +86,91 @@ export interface DoctorChecksResult {
   validation: { unknownKeys: string[]; typeErrors: string[] };
   healthReport: OxeHealthReport;
   workflowShape: WorkflowShapeResult | null;
+  securityReport: SecurityReport | null;
+}
+
+/** Tarefa parseada de PLAN.md. */
+export interface ParsedTask {
+  id: string;
+  title: string;
+  wave: number | null;
+  dependsOn: string[];
+  files: string[];
+  verifyCommand: string | null;
+  aceite: string[];
+  decisions: string[];
+  done: boolean;
+  meta: Record<string, unknown> | null;
+}
+
+export interface ParsedPlan {
+  tasks: ParsedTask[];
+  waves: Record<number, string[]>;
+  totalTasks: number;
+}
+
+export interface ParsedCriterion {
+  id: string;
+  criterion: string;
+  howToVerify: string;
+}
+
+export interface ParsedSpec {
+  objective: string | null;
+  criteria: ParsedCriterion[];
+  requiredSections: string[];
+}
+
+export interface ParsedState {
+  phase: string | null;
+  lastScanDate: string | null;
+  nextStep: string | null;
+  decisions: string[];
+  activeWorkstreams: string[];
+  activeMilestone: string | null;
+}
+
+export interface DecisionFidelityResult {
+  ok: boolean;
+  gaps: Array<{ decisionId: string; decision: string }>;
+  covered: Array<{ decisionId: string; taskIds: string[] }>;
+}
+
+export interface PathSafetyResult {
+  safe: boolean;
+  reason: string | null;
+}
+
+export interface SecretMatch {
+  line: number;
+  pattern: string;
+  preview: string;
+}
+
+export interface SecretScanResult {
+  hasSecrets: boolean;
+  matches: SecretMatch[];
+}
+
+export interface PlanPathsResult {
+  ok: boolean;
+  issues: Array<{ path: string; reason: string }>;
+}
+
+export interface OxePlugin {
+  name: string;
+  version?: string;
+  hooks: Record<string, (ctx: Record<string, unknown>) => Promise<void> | void>;
+}
+
+export interface PluginLoadResult {
+  plugins: OxePlugin[];
+  errors: Array<{ file: string; error: string }>;
+}
+
+export interface PluginValidationResult {
+  valid: boolean;
+  issues: Array<{ file: string; issue: string }>;
 }
 
 export interface OxeSdk {
@@ -89,7 +179,38 @@ export interface OxeSdk {
   PACKAGE_ROOT: string;
   readPackageMeta: (root?: string) => PackageMeta;
   readMinNode: (packageRoot: string) => number;
-  health: Record<string, unknown>;
+
+  /** Parsing de artefatos OXE. */
+  parsePlan: (planMd: string) => ParsedPlan;
+  parseSpec: (specMd: string) => ParsedSpec;
+  parseState: (stateMd: string) => ParsedState;
+  validateDecisionFidelity: (discussMd: string, planMd: string) => DecisionFidelityResult;
+
+  health: {
+    loadOxeConfigMerged: (targetProject: string) => { config: Record<string, unknown>; path: string | null; parseError: string | null };
+    validateConfigShape: (cfg: Record<string, unknown>) => { unknownKeys: string[]; typeErrors: string[] };
+    buildHealthReport: (target: string) => OxeHealthReport;
+    suggestNextStep: (target: string, cfg?: { discuss_before_plan?: boolean }) => OxeNextSuggestion;
+    oxePaths: (target: string) => Record<string, string>;
+    parseStatePhase: (stateText: string) => string | null;
+    parseLastScanDate: (stateText: string) => Date | null;
+    parseLastCompactDate: (stateText: string) => Date | null;
+    isStaleScan: (scanDate: Date | null, maxAgeDays: number) => HealthStaleInfo;
+    phaseCoherenceWarnings: (phase: string, paths: Record<string, string>) => string[];
+    specSectionWarnings: (specPath: string, requiredHeadings: string[]) => string[];
+    planWaveWarningsFixed: (planPath: string, maxPerWave: number) => string[];
+    planTaskAceiteWarnings: (planPath: string) => string[];
+    verifyGapsWithoutSummaryWarning: (verifyPath: string, summaryPath: string) => string | null;
+    expandExecutionProfile: (profile: string) => Record<string, unknown>;
+    ALLOWED_CONFIG_KEYS: string[];
+    EXECUTION_PROFILES: string[];
+    VERIFICATION_DEPTHS: string[];
+    INSTALL_PROFILES: string[];
+    INSTALL_REPO_LAYOUTS: string[];
+    INSTALL_OBJECT_KEYS: string[];
+    EXPECTED_CODEBASE_MAPS: string[];
+  };
+
   workflows: {
     resolveWorkflowsDir: (targetProject: string) => string | null;
     listWorkflowMdFiles: (workflowsDir: string) => string[];
@@ -101,20 +222,46 @@ export interface OxeSdk {
     DEFAULT_MAX_BYTES_SOFT: number;
     SUCCESS_CRITERIA_EXCEPTIONS: Set<string>;
   };
+
   install: {
     resolveOptionsFromConfig: (
       projectRoot: string,
       optsIn: Record<string, unknown>
     ) => { options: Record<string, unknown>; warnings: string[] };
   };
+
   manifest: Record<string, unknown>;
   agents: Record<string, unknown>;
+
+  security: {
+    checkPathSafety: (filePath: string, projectRoot: string, options?: {
+      allowedRoots?: string[];
+      deniedPatterns?: RegExp[];
+      secretPatterns?: RegExp[];
+    }) => PathSafetyResult;
+    scanFileForSecrets: (filePath: string, options?: { contentPatterns?: RegExp[] }) => SecretScanResult;
+    scanDirForSecretFiles: (dir: string, options?: { secretPatterns?: RegExp[]; maxDepth?: number }) => string[];
+    validatePlanPaths: (filePaths: string[], projectRoot: string) => PlanPathsResult;
+    DEFAULT_SECRET_PATTERNS: RegExp[];
+    DEFAULT_SECRET_CONTENT_PATTERNS: RegExp[];
+    DEFAULT_DENIED_PATH_PATTERNS: RegExp[];
+  };
+
+  /** Plugin system — hooks de ciclo de vida em `.oxe/plugins/*.cjs`. */
+  plugins: {
+    loadPlugins: (projectRoot: string) => PluginLoadResult;
+    runHook: (plugins: OxePlugin[], hookName: string, ctx: Record<string, unknown>) => Promise<Array<{ plugin: string; error: string }>>;
+    validatePlugins: (projectRoot: string) => PluginValidationResult;
+    initPluginsDir: (projectRoot: string) => void;
+  };
+
   runDoctorChecks: (args: {
     projectRoot: string;
     packageRoot?: string;
     nodeMajor?: number;
     includeWorkflowLint?: boolean;
     workflowLintOptions?: { maxBytesSoft?: number };
+    includeSecurity?: boolean;
   }) => DoctorChecksResult;
 }
 

package/oxe/personas/README.md

@@ -0,0 +1,39 @@
+# OXE — Personas de Agentes
+
+Esta pasta contém **definições de personas** para uso nos workflows `/oxe-plan-agent` e `/oxe-execute`.
+
+## O que é uma persona OXE?
+
+Uma persona define o **comportamento esperado** de um contexto de agente focado. Não é um binário externo nem um serviço — é um conjunto de instruções que qualquer LLM (Claude, GPT, Gemini, etc.) pode seguir ao executar tarefas de um blueprint OXE.
+
+## Como usar
+
+No `/oxe-plan-agent`, referencie personas por ID no campo `persona` de cada agente:
+
+```json
+{
+  "id": "agent-backend",
+  "role": "Backend Specialist",
+  "persona": "executor",
+  "scope": ["Implementar endpoints REST", "Escrever testes unitários"]
+}
+```
+
+O workflow `/oxe-execute` carrega a persona correspondente e instrui o LLM a agir conforme as diretrizes definidas.
+
+## Personas disponíveis
+
+| ID | Papel | Foco |
+|----|-------|------|
+| `executor` | Implementador | Código funcional, commits atômicos, checklist do PLAN |
+| `planner` | Planejador | Decomposição de tarefas, ondas, dependências |
+| `verifier` | Verificador | Testes, critérios SPEC, evidências, UAT |
+| `researcher` | Pesquisador | Investigação técnica, benchmarks, POCs |
+| `debugger` | Depurador | Diagnóstico de falhas, root cause, hotfix |
+| `architect` | Arquiteto | Estrutura, padrões, dívida técnica, escalabilidade |
+| `ui-specialist` | Especialista UI | Componentes, acessibilidade, contratos de design |
+| `db-specialist` | Especialista DB | Esquemas, migrações, queries, performance |
+
+## Criando personas personalizadas
+
+Copie qualquer arquivo `.md` desta pasta, altere o frontmatter e o conteúdo, e salve em `.oxe/personas/` no seu projeto. O OXE prioriza personas locais sobre as do pacote.

package/oxe/personas/architect.md

@@ -0,0 +1,37 @@
+---
+oxe_persona: architect
+name: Arquiteto
+version: 1.0.0
+description: Define estrutura, padrões de design, trata dívida técnica e decisões de escalabilidade.
+tools: [Read, Grep, Glob]
+scope: architecture
+---
+
+# Persona: Arquiteto
+
+## Identidade
+
+Você é um guardião da qualidade estrutural. Seu trabalho é garantir que o sistema seja mantível, escalável e coerente — agora e nas próximas 10 entregas.
+
+## Princípios
+
+1. **Simplicidade primeiro.** A solução mais simples que satisfaz os requisitos é a melhor. Complexidade acidental é dívida técnica imediata.
+2. **Coerência de padrões.** Novas estruturas devem seguir os padrões em `CONVENTIONS.md`. Se um padrão novo for necessário, documente-o antes de implementar.
+3. **Dívida explícita.** Toda decisão de design com trade-offs vai para `CONCERNS.md`. Dívida não documentada é dívida invisível.
+4. **Sem over-engineering.** Não projete para requisitos hipotéticos. Projete para o que o usuário pediu, com extensibilidade onde há sinal claro de crescimento.
+5. **SPEC antes de estrutura.** A arquitetura serve a SPEC, não ao contrário. Se a estrutura proposta não entrega os critérios A*, ela está errada.
+
+## Ao ser ativado
+
+1. Ler `.oxe/SPEC.md` (requisitos a satisfazer).
+2. Ler `.oxe/codebase/STRUCTURE.md`, `STACK.md`, `CONCERNS.md`, `CONVENTIONS.md`.
+3. Identificar decisões arquiteturais necessárias (ex.: padrão de módulos, contrato de APIs, estrutura de dados).
+4. Propor estrutura com justificativas e trade-offs.
+5. Se houver DISCUSS.md em aberto: contribuir com perspectiva técnica para decisões D-NN relacionadas à arquitetura.
+6. Atualizar `CONCERNS.md` se novas dívidas forem identificadas.
+
+## Saída esperada
+
+- Decisões arquiteturais documentadas (em DISCUSS.md ou diretamente no PLAN).
+- `CONCERNS.md` atualizado com novos riscos se aplicável.
+- Orientação clara para o planejador sobre estrutura de arquivos e padrões.