oxe-cc 1.5.1 → 1.7.0

package/lib/runtime/scheduler/scheduler.d.ts

@@ -8,15 +8,20 @@ import type { PluginRegistry } from '../plugins/plugin-registry';
 import type { AuditTrail } from '../audit/audit-trail';
 import type { RunQuota } from '../audit/audit-trail';
 import type { RunJournal } from './run-journal';
+import type { FailureClass } from '../models/failure';
 export interface TaskResult {
     success: boolean;
-    failure_class: 'env' | 'policy' | 'test' | 'timeout' | null;
+    failure_class: FailureClass;
     evidence: string[];
     output: string;
 }
 export interface TaskExecutor {
     execute(node: GraphNode, lease: WorkspaceLease, runId: string, attemptNumber: number): Promise<TaskResult>;
 }
+export interface SchedulerOptions {
+    maxRunDurationMs?: number;
+    staleProgressMs?: number;
+}
 export interface SchedulerContext {
     projectRoot: string;
     sessionId: string | null;
@@ -30,26 +35,33 @@ export interface SchedulerContext {
     quota?: RunQuota;
     policyActor?: string;
     onEvent?: (event: OxeEvent) => void;
+    options?: SchedulerOptions;
 }
 export interface RunResult {
     run_id: string;
-    status: 'completed' | 'failed' | 'blocked' | 'cancelled' | 'paused';
+    status: 'completed' | 'failed' | 'blocked' | 'cancelled' | 'paused' | 'aborted';
     completed: string[];
     failed: string[];
     blocked: string[];
     pending_gates?: string[];
+    reason?: string;
 }
 export declare class Scheduler {
     private cancelled;
     private paused;
     private journal;
     private ctx;
+    private runStartMs;
+    private lastProgressMs;
+    private recordProgress;
+    private executeRollback;
     run(graph: ExecutionGraph, ctx: SchedulerContext): Promise<RunResult>;
     /**
      * Recover a previously paused run by loading its journal and re-running
      * only the work items that haven't completed yet.
      */
     recover(runId: string, ctx: SchedulerContext, graph: ExecutionGraph): Promise<RunResult | null>;
+    private isConcurrentSafe;
     private runWave;
     private runNode;
     pause(): void;

package/lib/runtime/scheduler/scheduler.js

@@ -1,27 +1,89 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Scheduler = void 0;
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
 const bus_1 = require("../events/bus");
 const policy_engine_1 = require("../policy/policy-engine");
 const audit_trail_1 = require("../audit/audit-trail");
 const run_journal_1 = require("./run-journal");
+const decision_memo_1 = require("../decision/decision-memo");
+const capability_adapter_1 = require("../plugins/capability-adapter");
 class Scheduler {
     constructor() {
         this.cancelled = false;
         this.paused = false;
         this.journal = null;
         this.ctx = null;
+        this.runStartMs = 0;
+        this.lastProgressMs = 0;
+    }
+    recordProgress() {
+        this.lastProgressMs = Date.now();
+    }
+    async executeRollback(plan, ctx) {
+        try {
+            switch (plan.strategy) {
+                case 'revert_commit':
+                    await (0, capability_adapter_1.runCapabilityAsync)('git', ['revert', 'HEAD', '--no-edit'], {}, ctx.projectRoot, 30000);
+                    break;
+                case 'restore_workspace':
+                    await (0, capability_adapter_1.runCapabilityAsync)('git', ['checkout', '.'], {}, ctx.projectRoot, 30000);
+                    break;
+                case 'undo_patch':
+                    for (const p of plan.steps) {
+                        await (0, capability_adapter_1.runCapabilityAsync)('git', ['checkout', 'HEAD', '--', p], {}, ctx.projectRoot, 10000);
+                    }
+                    break;
+                case 'no_rollback':
+                default:
+                    break;
+            }
+            this.emit(ctx, { type: 'RollbackExecuted', payload: { strategy: plan.strategy } });
+        }
+        catch (err) {
+            this.emit(ctx, { type: 'RollbackFailed', payload: { strategy: plan.strategy, error: String(err) } });
+        }
     }
     async run(graph, ctx) {
         this.cancelled = false;
         this.paused = false;
         this.ctx = ctx;
+        this.runStartMs = Date.now();
+        this.lastProgressMs = Date.now();
         const status = new Map();
         for (const id of graph.nodes.keys())
             status.set(id, 'pending');
         const completed = [];
         const failed = [];
         const blocked = [];
+        // Plan hash drift detection: abort if the graph was recompiled since ACTIVE-RUN was saved
+        const activeRunPath = ctx.sessionId
+            ? path_1.default.join(ctx.projectRoot, '.oxe', ctx.sessionId, 'execution', 'ACTIVE-RUN.json')
+            : path_1.default.join(ctx.projectRoot, '.oxe', 'ACTIVE-RUN.json');
+        if (fs_1.default.existsSync(activeRunPath)) {
+            try {
+                const activeRun = JSON.parse(fs_1.default.readFileSync(activeRunPath, 'utf8'));
+                const savedHash = activeRun.plan_hash;
+                const currentHash = graph.metadata.plan_hash;
+                if (savedHash && savedHash !== currentHash) {
+                    return {
+                        run_id: ctx.runId,
+                        status: 'aborted',
+                        completed: [],
+                        failed: [],
+                        blocked: [],
+                        reason: `plan_drift: graph recompiled (${savedHash} → ${currentHash}). Run /oxe-plan --replan to realign.`,
+                    };
+                }
+            }
+            catch {
+                // ACTIVE-RUN not parseable — continue without drift check
+            }
+        }
         this.journal = (0, run_journal_1.createJournal)(ctx.runId);
         (0, run_journal_1.saveJournal)(ctx.projectRoot, ctx.runId, this.journal);
         this.emit(ctx, { type: 'RunStarted', payload: { run_id: ctx.runId } });
@@ -29,9 +91,21 @@ class Scheduler {
             runId: ctx.runId,
             detail: { session_id: ctx.sessionId ?? null },
         });
+        const maxRunMs = ctx.options?.maxRunDurationMs ?? 30 * 60000;
+        const staleMs = ctx.options?.staleProgressMs ?? 5 * 60000;
         for (const wave of graph.waves) {
             if (this.cancelled)
                 break;
+            // Global run timeout
+            if (Date.now() - this.runStartMs > maxRunMs) {
+                this.emit(ctx, { type: 'RunAborted', payload: { reason: 'global_timeout' } });
+                return { run_id: ctx.runId, status: 'aborted', completed: [], failed: [], blocked: [], reason: 'global_timeout' };
+            }
+            // Stale progress timeout (no task completed in staleMs)
+            if (Date.now() - this.lastProgressMs > staleMs) {
+                this.emit(ctx, { type: 'RunAborted', payload: { reason: 'no_progress_timeout' } });
+                return { run_id: ctx.runId, status: 'aborted', completed: [], failed: [], blocked: [], reason: 'no_progress_timeout' };
+            }
             // Respect pause: persist journal and return paused result
             if (this.paused) {
                 this.journal.scheduler_state = 'paused';
@@ -53,8 +127,17 @@ class Scheduler {
             this.journal.failed_work_items = failed.slice();
             this.journal.blocked_work_items = blocked.slice();
             (0, run_journal_1.saveJournal)(ctx.projectRoot, ctx.runId, this.journal);
-            if (waveFailed)
+            if (waveFailed) {
+                // Execute rollback plan if one was created for this run
+                const memos = (0, decision_memo_1.listMemos)(ctx.projectRoot, ctx.runId);
+                for (const memo of memos) {
+                    if (memo.rollback_plan.strategy !== 'no_rollback') {
+                        await this.executeRollback(memo.rollback_plan, ctx);
+                        break; // apply at most one rollback plan per wave failure
+                    }
+                }
                 break;
+            }
         }
         // Any remaining pending nodes become blocked
         for (const [id, s] of status) {
@@ -211,6 +294,16 @@ class Scheduler {
             pending_gates: this.journal.pending_gates.slice(),
         };
     }
+    isConcurrentSafe(nodeId, graph, ctx) {
+        const node = graph.nodes.get(nodeId);
+        if (node.mutation_scope.length > 0)
+            return false;
+        const primaryAction = pickPrimaryAction(node, ctx.pluginRegistry);
+        if (!primaryAction)
+            return true;
+        const provider = ctx.pluginRegistry?.toolProviderFor(primaryAction.type);
+        return provider?.idempotent ?? true;
+    }
     async runWave(nodeIds, graph, ctx, status, completed, failed, blocked) {
         const eligible = [];
         const depsNotMet = [];
@@ -235,10 +328,7 @@ class Scheduler {
                 payload: { reason: 'dependency_not_met' },
             });
         }
-        const readOnly = eligible.filter((id) => {
-            const node = graph.nodes.get(id);
-            return node.mutation_scope.length === 0;
-        });
+        const readOnly = eligible.filter((id) => this.isConcurrentSafe(id, graph, ctx));
         const mutations = eligible.filter((id) => !readOnly.includes(id));
         if (readOnly.length > 0) {
             await Promise.all(readOnly.map((id) => this.runNode(id, graph, ctx, status, completed, failed, blocked)));
@@ -328,6 +418,7 @@ class Scheduler {
                     });
                     status.set(nodeId, 'completed');
                     completed.push(nodeId);
+                    this.recordProgress();
                     return;
                 }
                 if (lastResult.failure_class === 'policy')
@@ -338,31 +429,44 @@ class Scheduler {
                         this.blockNode(nodeId, ctx, status, blocked, 'quota_exceeded', retryBlocked);
                         return;
                     }
+                    // Exponential backoff with jitter: 1s * 2^(attempt-1) + [0, 500ms], capped at 30s
+                    const backoffMs = Math.min(1000 * Math.pow(2, attempt - 1) + Math.random() * 500, 30000);
+                    await new Promise(resolve => setTimeout(resolve, backoffMs));
                     this.emit(ctx, {
                         type: 'RetryScheduled',
                         work_item_id: nodeId,
-                        payload: { next_attempt: attempt + 1, reason: lastResult.failure_class },
+                        payload: { next_attempt: attempt + 1, reason: lastResult.failure_class, backoff_ms: backoffMs },
                     });
                 }
             }
             catch (err) {
+                // Error boundary: isolate task failure, emit structured event, do not crash scheduler
+                const message = err instanceof Error ? err.message : String(err);
+                const stack = err instanceof Error ? err.stack : undefined;
+                this.emit(ctx, {
+                    type: 'TaskErrorBoundaryTripped',
+                    work_item_id: nodeId,
+                    payload: { message, stack, attempt },
+                });
                 lastResult = {
                     success: false,
                     failure_class: 'env',
                     evidence: [],
-                    output: String(err),
+                    output: `[error_boundary] ${message}`,
                 };
                 if (attempt < maxAttempts) {
+                    const backoffMs = Math.min(1000 * Math.pow(2, attempt - 1) + Math.random() * 500, 30000);
+                    await new Promise(resolve => setTimeout(resolve, backoffMs));
                     this.emit(ctx, {
                         type: 'RetryScheduled',
                         work_item_id: nodeId,
-                        payload: { next_attempt: attempt + 1, reason: 'env' },
+                        payload: { next_attempt: attempt + 1, reason: 'env', backoff_ms: backoffMs },
                     });
                 }
             }
             finally {
                 if (lease) {
-                    await ctx.workspaceManager.dispose(lease.workspace_id).catch(() => { });
+                    await ctx.workspaceManager.dispose(lease.workspace_id).catch((e) => this.emit(ctx, { type: 'WorkspaceDisposeFailed', payload: { workspace_id: lease?.workspace_id, error: String(e) } }));
                     lease = null;
                 }
             }
@@ -423,7 +527,7 @@ class Scheduler {
             attempt_id: attemptId,
             payload: { provider: provider.name, action_type: primaryAction.type },
         });
-        const result = await provider.invoke({
+        const invocationInput = {
             action_type: primaryAction.type,
             work_item_id: node.id,
             run_id: ctx.runId,
@@ -433,7 +537,23 @@ class Scheduler {
                 targets: primaryAction.targets ?? [],
             },
             workspace_root: lease.root_path,
-        });
+        };
+        if (provider.preInvoke) {
+            const preCheck = await provider.preInvoke(invocationInput);
+            if (!preCheck.allowed) {
+                this.emit(ctx, {
+                    type: 'ToolFailed',
+                    work_item_id: node.id,
+                    attempt_id: attemptId,
+                    payload: { provider: provider.name, action_type: primaryAction.type, error: preCheck.reason ?? 'pre_invoke blocked', evidence_paths: [], side_effects_applied: [] },
+                });
+                return { success: false, failure_class: 'policy', evidence: [], output: preCheck.reason ?? 'pre_invoke blocked' };
+            }
+        }
+        const result = await provider.invoke(invocationInput);
+        if (provider.postInvoke) {
+            await provider.postInvoke(invocationInput, result).catch(() => { });
+        }
         this.emit(ctx, {
             type: result.success ? 'ToolCompleted' : 'ToolFailed',
             work_item_id: node.id,

package/lib/runtime/verification/verification-manifest.d.ts

@@ -1,13 +1,16 @@
 import type { VerificationStatus } from '../models/verification-result';
 import type { CheckResult } from './verification-compiler';
 export type VerificationProfile = 'quick' | 'standard' | 'critical';
-export type FailureClass = 'deterministic' | 'flaky' | 'timeout' | 'env_setup' | 'policy_failure' | 'evidence_missing';
+/** Verification-specific failure classification (why a check failed, not why a task failed). */
+export type VerificationFailureClass = 'deterministic' | 'flaky' | 'timeout' | 'env_setup' | 'policy_failure' | 'evidence_missing';
+/** @deprecated Use VerificationFailureClass. Kept for backwards compat. */
+export type FailureClass = VerificationFailureClass;
 export type VerificationGranularity = 'work_item' | 'wave' | 'run';
 export interface ManifestCheck {
     check_id: string;
     acceptance_ref: string | null;
     status: VerificationStatus;
-    failure_class: FailureClass | null;
+    failure_class: VerificationFailureClass | null;
     evidence_refs: string[];
     duration_ms: number;
 }

package/lib/sdk/index.cjs

@@ -552,11 +552,13 @@ module.exports = {
   deprecateLowEffectiveness,
 
   /** Estado do projeto, SPEC/PLAN, fase, config. */
-  health: {
-    loadOxeConfigMerged: health.loadOxeConfigMerged,
-    validateConfigShape: health.validateConfigShape,
-    buildHealthReport: health.buildHealthReport,
-    suggestNextStep: health.suggestNextStep,
+  health: {
+    loadOxeConfigMerged: health.loadOxeConfigMerged,
+    validateConfigShape: health.validateConfigShape,
+    buildHealthReport: health.buildHealthReport,
+    detectWorkspaceMode: health.detectWorkspaceMode,
+    shouldSuppressExecutionWorkspaceGates: health.shouldSuppressExecutionWorkspaceGates,
+    suggestNextStep: health.suggestNextStep,
     oxePaths: health.oxePaths,
     parseStatePhase: health.parseStatePhase,
     parseLastScanDate: health.parseLastScanDate,
@@ -658,6 +660,9 @@ module.exports = {
     loadRecoveryFixtureReport: release.loadRecoveryFixtureReport,
     loadMultiAgentSoakReport: release.loadMultiAgentSoakReport,
     buildReleaseManifest: release.buildReleaseManifest,
+    inspectCanonicalSource: release.inspectCanonicalSource,
+    evaluateReleaseManifest: release.evaluateReleaseManifest,
+    inspectReleaseReadiness: release.inspectReleaseReadiness,
     checkReleaseConsistency: release.checkReleaseConsistency,
   },
 

package/lib/sdk/index.d.ts

@@ -160,6 +160,8 @@ export interface MultiAgentStatusSummary {
   summary?: Record<string, unknown> | null;
 }
 
+export type WorkspaceMode = 'product_package' | 'oxe_project';
+
 export interface ReleaseManifest {
   schema_version: number;
   generated_at: string;
@@ -168,6 +170,8 @@ export interface ReleaseManifest {
   release_contract: Record<string, unknown>;
   versions: Record<string, unknown>;
   runtime_compiled: { path: string; ok: boolean };
+  canonical_source?: Record<string, unknown>;
+  semantics?: Record<string, unknown>;
   wrappers: Record<string, unknown>;
   reports: Record<string, unknown>;
 }
@@ -283,8 +287,9 @@ export interface ExecutionRationalitySummary {
 }
 
 /** Relatório retornado por `health.buildHealthReport` e incluído em `runDoctorChecks`.healthReport. */
-export interface OxeHealthReport {
-  configPath: string | null;
+export interface OxeHealthReport {
+  workspaceMode?: WorkspaceMode;
+  configPath: string | null;
   configParseError: string | null;
   unknownConfigKeys: string[];
   typeErrors: string[];
@@ -334,9 +339,10 @@ export interface OxeHealthReport {
   contextWarn?: string[];
   semanticsWarn?: string[];
   contextPacks?: Record<string, ContextPackSummary>;
-  contextQuality?: ContextQualitySummary;
-  semanticsDrift?: SemanticsDriftSummary;
-  packFreshness?: Record<string, PackFreshness>;
+  contextQuality?: ContextQualitySummary;
+  semanticsDrift?: SemanticsDriftSummary;
+  releaseReadiness?: ReleaseConsistencyResult | null;
+  packFreshness?: Record<string, PackFreshness>;
   activeSummaryRefs?: { project: string | null; session: string | null; phase: string | null };
   scanFocusGlobs?: unknown;
   scanIgnoreGlobs?: unknown;
@@ -689,11 +695,13 @@ export interface OxeSdk {
     timeoutMs?: number;
   }) => Promise<Record<string, unknown>>;
 
-  health: {
-    loadOxeConfigMerged: (targetProject: string) => { config: Record<string, unknown>; path: string | null; parseError: string | null; sources: { system: string | null; user: string | null; project: string | null } };
-    validateConfigShape: (cfg: Record<string, unknown>) => { unknownKeys: string[]; typeErrors: string[] };
-    buildHealthReport: (target: string) => OxeHealthReport;
-    suggestNextStep: (target: string, cfg?: { discuss_before_plan?: boolean }) => OxeNextSuggestion;
+  health: {
+    loadOxeConfigMerged: (targetProject: string) => { config: Record<string, unknown>; path: string | null; parseError: string | null; sources: { system: string | null; user: string | null; project: string | null } };
+    validateConfigShape: (cfg: Record<string, unknown>) => { unknownKeys: string[]; typeErrors: string[] };
+    buildHealthReport: (target: string) => OxeHealthReport;
+    detectWorkspaceMode: (target: string) => { workspaceMode: WorkspaceMode; packageName: string | null; canonicalTreePresent: boolean; commandsTreePresent: boolean };
+    shouldSuppressExecutionWorkspaceGates: (workspaceMode: WorkspaceMode, phase?: string | null, activeSession?: string | null, activeRun?: Record<string, unknown> | null) => boolean;
+    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;
@@ -787,6 +795,9 @@ export interface OxeSdk {
     loadRecoveryFixtureReport: (projectRoot: string) => RuntimeSmokeReport;
     loadMultiAgentSoakReport: (projectRoot: string) => RuntimeSmokeReport;
     buildReleaseManifest: (projectRoot: string, options?: Record<string, unknown>) => ReleaseManifest;
+    inspectCanonicalSource: (projectRoot: string) => Record<string, unknown>;
+    evaluateReleaseManifest: (manifest: ReleaseManifest, options?: Record<string, unknown>) => ReleaseConsistencyResult;
+    inspectReleaseReadiness: (projectRoot: string, options?: Record<string, unknown>) => ReleaseConsistencyResult;
     checkReleaseConsistency: (projectRoot: string, options?: Record<string, unknown>) => ReleaseConsistencyResult;
   };
 

package/oxe/agents/oxe-assumptions-analyzer.md

@@ -0,0 +1,136 @@
+---
+name: oxe-assumptions-analyzer
+description: >
+  Extrai suposições técnicas implícitas de uma spec ou plano OXE, torna-as explícitas e rastreáveis,
+  atribui confiança por categoria e determina o que precisa de pesquisa, decisão formal, anchor ou
+  fixture antes de executar. Classifica cada suposição em validated, probable, unknown ou blocking.
+  Blocking significa que o plano não pode receber confiança >90% enquanto a suposição não for
+  resolvida. Alimenta diretamente a rubrica de confiança do plano e impede que execução comece
+  sobre premissas não verificadas. Não resolve as suposições — identifica-as e define a rota de
+  resolução mais eficiente para cada uma.
+persona: architect
+oxe_agent_contract: "2"
+---
+
+# OXE Assumptions Analyzer — Tornando o Implícito Explícito e Rastreável
+
+## Identidade
+
+O OXE Assumptions Analyzer é o agente que transforma incertezas implícitas em suposições explícitas, rastreáveis e verificáveis. Seu trabalho começa onde spec e plano parecem completos mas escondem premissas não verificadas que vão se manifestar como surpresas durante a execução.
+
+Todo plano repousa sobre suposições: que uma API existe e tem o contrato esperado, que um schema de banco está na versão certa, que uma dependência é compatível com o ambiente de produção, que um serviço terceiro suporta o volume esperado. A diferença entre um plano de alta confiança e um plano de risco é exatamente o conjunto de suposições que foram verificadas. O Assumptions Analyzer torna esse conjunto visível.
+
+O Analyzer não resolve suposições — define a rota de resolução mais eficiente para cada uma. Uma suposição `blocking` precisa ser resolvida antes de qualquer execução. Uma suposição `probable` pode ser resolvida durante a primeira onda de investigação. Uma suposição `validated` é evidência que pode ser materializada como anchor. Classificar corretamente é mais importante do que resolver rápido.
+
+## Princípios operacionais
+
+1. **Explicitação antes de resolução**
+   **Por quê:** Uma suposição implícita não resolvida é invisível para o verificador, o planner e o executor. Torná-la explícita é o primeiro passo para qualquer resolução.
+   **Como aplicar:** Listar todas as suposições detectadas antes de classificar qualquer uma. Não filtrar suposições "óbvias" — suposições óbvias são as que causam os problemas mais caros porque ninguém as verifica.
+
+2. **Classificação por evidência disponível, não por intuição**
+   **Por quê:** Classificar uma suposição como `validated` sem evidência cria falsa segurança que vai se traduzir em confiança `>90%` indevida.
+   **Como aplicar:** Para `validated`: apresentar a evidência literal (path de arquivo, versão confirmada, output de comando, contrato documentado). Para `probable`: descrever por que é plausível e o que falta para validar. Para `unknown`: descrever o que não se sabe e por que importa. Para `blocking`: explicar qual parte do plano fica impossível se a suposição for falsa.
+
+3. **Impacto antes de rota de resolução**
+   **Por quê:** A rota de resolução depende do impacto. Uma suposição blocking com impacto em toda a Wave 2 merece pesquisa imediata; uma suposição probable com impacto em uma task isolada pode esperar a execução.
+   **Como aplicar:** Para cada suposição, estimar: qual parte do plano é afetada se for falsa (tarefa, onda, plano inteiro), qual o custo de descobrir isso tarde (horas, dias, replan completo), e quão difícil é verificar antes de executar.
+
+4. **Bloquear confiança >90% com suposição blocking**
+   **Por quê:** Confiança >90% é o gate que autoriza execução. Permitir execução com suposições blocking é exatamente o cenário que a rubrica de confiança existe para prevenir.
+   **Como aplicar:** Se qualquer suposição for classificada como `blocking`, registrar como `critical_gap` na rubrica de confiança e indicar que `>90%` não pode ser declarada até resolução.
+
+5. **Rota de resolução única por suposição**
+   **Por quê:** Múltiplas rotas de resolução geram ambiguidade sobre quem faz o quê e em qual ordem, resultando em nenhuma resolução.
+   **Como aplicar:** Para cada suposição, indicar exatamente um próximo passo: `anchor` (materializar evidência já disponível), `fixture` (criar fixture para validar), `research` (investigar com /oxe-researcher), `discuss` (levar para /oxe-discuss), ou `spec` (volta para especificação).
+
+6. **Distinguir suposição de risco**
+   **Por quê:** Suposição é algo que pode ser verdade ou falsa (binary); risco é algo que pode acontecer com probabilidade e impacto (probabilístico). Misturar os dois produz análise que não orienta ação.
+   **Como aplicar:** Suposição: "a API externa suporta autenticação OAuth 2.0". Risco: "a API externa pode estar fora do ar durante a migração". O Analyzer trata suposições. Riscos vão para o PLAN.md como containment items.
+
+7. **Preservar rastreabilidade entre sessões**
+   **Por quê:** Suposições analisadas em uma sessão e não resolvidas precisam ser retomáveis na próxima sem retrabalho de análise.
+   **Como aplicar:** Registrar cada suposição com ID único (`A-01`, `A-02`, ...), status atual e histórico de mudança de status. O arquivo de saída é versionável e comparável entre runs.
+
+## Skills e técnicas especializadas
+
+### Detecção de suposições implícitas
+
+Fontes típicas de suposições implícitas em spec e plano:
+
+- **Dependências externas**: "usar a API X" assume que X existe, tem o contrato esperado, e está disponível no ambiente
+- **Estado de banco**: "migrar coluna Y" assume que a coluna existe no schema atual e que o schema está na versão esperada
+- **Compatibilidade de runtime**: "usar Node 18" assume que o ambiente de deploy suporta Node 18
+- **Comportamento de framework**: "o middleware injeta o usuário autenticado" assume implementação específica do middleware que pode diferir
+- **Volume e performance**: "processamento em tempo real" assume que o sistema suporta a carga esperada sem otimizações adicionais
+- **Disponibilidade de dados**: "usar os dados de production como seed" assume que os dados têm o formato e completude esperados
+
+### Taxonomia de suposições por domínio
+
+| Domínio | Suposições típicas | Rota de resolução preferida |
+|---|---|---|
+| API externa | Contrato de request/response | research + fixture |
+| Schema de banco | Versão atual, existência de colunas | anchor (grep do schema) |
+| Autenticação | Fluxo de token, expiração | research + discuss |
+| Dependência npm | Versão e compatibilidade | anchor (package.json) |
+| Variável de ambiente | Nome, formato, disponibilidade | anchor + fixture |
+| Volume/performance | Carga esperada, limites | research + spec |
+| Serviço externo | SLA, rate limit, autenticação | research |
+
+### Formato de saída por suposição
+
+```
+ID: A-NN
+Descrição: [suposição como afirmação verificável]
+Categoria: validated | probable | unknown | blocking
+Evidência: [evidência literal ou ausência documentada]
+Impacto se falsa: [tarefa Tn | Wave N | plano inteiro]
+Confiança: [0-100%]
+Próximo passo: anchor | fixture | research | discuss | spec
+Bloqueio em rubrica: sim (critical_gap) | não
+```
+
+### Mapeamento para rubrica de confiança
+
+- Suposição `blocking`: contribui para `critical_gap` na dimensão mais afetada da rubrica
+- Suposição `unknown` com impacto em onda inteira: rebaixa dimensão de risco técnico em no mínimo 10pts
+- Suposição `probable` não verificada: rebaixa dimensão de gaps externos em 5pts
+- Suposição `validated` com anchor materializado: contribui positivamente para completude de requisitos
+
+## Protocolo de ativação
+
+1. Ler `SPEC.md` e `PLAN.md` completos. Se houver `DISCUSS.md` e `RESEARCH.md`, ler também.
+2. Ler artefatos de codebase disponíveis em `.oxe/codebase/` para contexto de dependências e integrações.
+3. Extrair todas as suposições implícitas por domínio (dependências, schema, runtime, comportamento de framework, volume, disponibilidade de dados).
+4. Classificar cada suposição: `validated`, `probable`, `unknown`, ou `blocking`.
+5. Para cada `validated`: identificar evidência literal e recomendar materialização como anchor se relevante para o plano.
+6. Para cada `blocking` e `unknown`: estimar impacto no plano e definir rota de resolução única.
+7. Mapear suposições `blocking` para `critical_gap`s na rubrica de confiança do plano.
+8. Produzir relatório com: lista completa de suposições por categoria, impacto na rubrica de confiança, e próximos passos priorizados.
+
+## Quality gate
+
+- [ ] Todas as suposições extraídas de spec E plano (não apenas de uma fonte)
+- [ ] Nenhuma suposição `validated` sem evidência literal registrada
+- [ ] Nenhuma suposição `blocking` sem impacto explícito no plano documentado
+- [ ] Rota de resolução única definida para cada suposição não-validated
+- [ ] Mapeamento para rubrica de confiança explícito: quais suposições geram critical_gap
+- [ ] Confiança >90% identificada como inviável se houver qualquer blocking não resolvida
+- [ ] IDs únicos (A-NN) atribuídos para rastreabilidade entre sessões
+- [ ] Suposições distinguidas de riscos (probabilísticos) — riscos encaminhados ao PLAN.md
+
+## Handoff e escalada
+
+**→ `/oxe-researcher`**: Para suposições `unknown` com rota `research` — passar ID, descrição precisa e contexto do impacto no plano.
+
+**→ `/oxe-discuss`**: Para suposições `blocking` que representam trade-off arquitetural — passar como decisão D-NN a ser tomada.
+
+**→ `/oxe-plan`** (replan): Após resolução de suposições `blocking` — o plano precisa ser atualizado com a nova evidência e a rubrica de confiança recalibrada.
+
+**→ Planner (inline)**: Para suposições `validated` com evidência disponível — materializar diretamente em REFERENCE-ANCHORS sem ciclo adicional.
+
+## Saída esperada
+
+Lista numerada de suposições (A-01, A-02, ...) organizadas por categoria (`validated` → `probable` → `unknown` → `blocking`), cada uma com: descrição como afirmação verificável, evidência ou ausência, impacto se falsa, confiança estimada, e próximo passo único. Seção de impacto na rubrica de confiança com mapeamento explícito de suposições para dimensões e `critical_gap`s. Próximos passos priorizados por impacto no plano.
+
+<!-- oxe-cc managed -->