oxe-cc 1.0.0 → 1.2.1

package/lib/runtime/scheduler/scheduler.js

@@ -2,25 +2,47 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Scheduler = void 0;
 const bus_1 = require("../events/bus");
+const run_journal_1 = require("./run-journal");
 class Scheduler {
     constructor() {
         this.cancelled = false;
         this.paused = false;
+        this.journal = null;
+        this.ctx = null;
     }
     async run(graph, ctx) {
         this.cancelled = false;
         this.paused = false;
+        this.ctx = ctx;
         const status = new Map();
         for (const id of graph.nodes.keys())
             status.set(id, 'pending');
         const completed = [];
         const failed = [];
         const blocked = [];
+        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 } });
         for (const wave of graph.waves) {
             if (this.cancelled)
                 break;
+            // Respect pause: persist journal and return paused result
+            if (this.paused) {
+                this.journal.scheduler_state = 'paused';
+                this.journal.paused_at = new Date().toISOString();
+                this.journal.completed_work_items = completed.slice();
+                this.journal.failed_work_items = failed.slice();
+                this.journal.blocked_work_items = blocked.slice();
+                this.journal.partial_result = { run_id: ctx.runId, completed, failed, blocked };
+                (0, run_journal_1.saveJournal)(ctx.projectRoot, ctx.runId, this.journal);
+                return { run_id: ctx.runId, status: 'paused', completed, failed, blocked };
+            }
             const waveFailed = await this.runWave(wave.node_ids, graph, ctx, status, completed, failed, blocked);
+            // Sync journal after each wave
+            this.journal.completed_work_items = completed.slice();
+            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)
                 break;
         }
@@ -45,13 +67,104 @@ class Scheduler {
             type: 'RunCompleted',
             payload: { run_id: ctx.runId, status: finalStatus },
         });
+        this.journal.scheduler_state = this.cancelled ? 'cancelled' : 'completed';
+        this.journal.completed_work_items = completed.slice();
+        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);
+        return { run_id: ctx.runId, status: finalStatus, completed, failed, blocked };
+    }
+    /**
+     * Recover a previously paused run by loading its journal and re-running
+     * only the work items that haven't completed yet.
+     */
+    async recover(runId, ctx, graph) {
+        const journal = (0, run_journal_1.loadJournal)(ctx.projectRoot, runId);
+        if (!journal || journal.scheduler_state !== 'paused')
+            return null;
+        // Restore state from journal
+        this.cancelled = false;
+        this.paused = false;
+        this.ctx = ctx;
+        this.journal = { ...journal, scheduler_state: 'running', paused_at: null };
+        const restoredCompleted = new Set(journal.completed_work_items);
+        const restoredFailed = new Set(journal.failed_work_items);
+        const restoredBlocked = new Set(journal.blocked_work_items);
+        const status = new Map();
+        for (const id of graph.nodes.keys()) {
+            if (restoredCompleted.has(id))
+                status.set(id, 'completed');
+            else if (restoredFailed.has(id))
+                status.set(id, 'failed');
+            else if (restoredBlocked.has(id))
+                status.set(id, 'blocked');
+            else
+                status.set(id, 'pending');
+        }
+        const completed = [...restoredCompleted];
+        const failed = [...restoredFailed];
+        const blocked = [...restoredBlocked];
+        (0, run_journal_1.saveJournal)(ctx.projectRoot, runId, this.journal);
+        this.emit(ctx, { type: 'RunStarted', payload: { run_id: ctx.runId, recovered: true } });
+        for (const wave of graph.waves) {
+            if (this.cancelled)
+                break;
+            if (this.paused) {
+                this.journal.scheduler_state = 'paused';
+                this.journal.paused_at = new Date().toISOString();
+                this.journal.completed_work_items = completed.slice();
+                this.journal.failed_work_items = failed.slice();
+                this.journal.blocked_work_items = blocked.slice();
+                this.journal.partial_result = { run_id: ctx.runId, completed, failed, blocked };
+                (0, run_journal_1.saveJournal)(ctx.projectRoot, ctx.runId, this.journal);
+                return { run_id: ctx.runId, status: 'paused', completed, failed, blocked };
+            }
+            // Skip waves fully completed
+            const allDone = wave.node_ids.every((id) => restoredCompleted.has(id) || restoredFailed.has(id) || restoredBlocked.has(id));
+            if (allDone)
+                continue;
+            const waveFailed = await this.runWave(wave.node_ids, graph, ctx, status, completed, failed, blocked);
+            this.journal.completed_work_items = completed.slice();
+            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)
+                break;
+        }
+        for (const [id, s] of status) {
+            if (s === 'pending') {
+                status.set(id, 'blocked');
+                blocked.push(id);
+                this.emit(ctx, {
+                    type: 'WorkItemBlocked',
+                    work_item_id: id,
+                    payload: { reason: 'upstream_wave_failed' },
+                });
+            }
+        }
+        const finalStatus = this.cancelled
+            ? 'cancelled'
+            : failed.length > 0
+                ? 'failed'
+                : 'completed';
+        this.emit(ctx, {
+            type: 'RunCompleted',
+            payload: { run_id: ctx.runId, status: finalStatus, recovered: true },
+        });
+        this.journal.scheduler_state = this.cancelled ? 'cancelled' : 'completed';
+        this.journal.completed_work_items = completed.slice();
+        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);
+        (0, run_journal_1.deleteJournal)(ctx.projectRoot, ctx.runId);
         return { run_id: ctx.runId, status: finalStatus, completed, failed, blocked };
     }
     async runWave(nodeIds, graph, ctx, status, completed, failed, blocked) {
-        // Partition: eligible vs blocked-by-dep
         const eligible = [];
         const depsNotMet = [];
         for (const id of nodeIds) {
+            if (status.get(id) === 'completed')
+                continue; // already done in recovery
             const node = graph.nodes.get(id);
             const depsMet = node.depends_on.every((dep) => status.get(dep) === 'completed');
             if (depsMet) {
@@ -61,7 +174,6 @@ class Scheduler {
                 depsNotMet.push(id);
             }
         }
-        // Nodes whose deps weren't met in this wave → blocked
         for (const id of depsNotMet) {
             status.set(id, 'blocked');
             blocked.push(id);
@@ -71,17 +183,14 @@ class Scheduler {
                 payload: { reason: 'dependency_not_met' },
             });
         }
-        // Separate read-only (no mutation_scope) from mutation nodes
         const readOnly = eligible.filter((id) => {
             const node = graph.nodes.get(id);
             return node.mutation_scope.length === 0;
         });
         const mutations = eligible.filter((id) => !readOnly.includes(id));
-        // Run read-only nodes in parallel
         if (readOnly.length > 0) {
             await Promise.all(readOnly.map((id) => this.runNode(id, graph, ctx, status, completed, failed)));
         }
-        // Run mutation nodes sequentially to avoid scope conflicts
         for (const id of mutations) {
             if (this.cancelled)
                 break;
@@ -134,7 +243,6 @@ class Scheduler {
                     completed.push(nodeId);
                     return;
                 }
-                // Policy failures never retry
                 if (lastResult.failure_class === 'policy')
                     break;
                 if (attempt < maxAttempts) {
@@ -167,7 +275,6 @@ class Scheduler {
                 }
             }
         }
-        // All attempts exhausted
         this.emit(ctx, {
             type: 'WorkItemBlocked',
             work_item_id: nodeId,
@@ -178,12 +285,33 @@ class Scheduler {
     }
     pause() {
         this.paused = true;
+        if (this.journal && this.ctx) {
+            this.journal.scheduler_state = 'paused';
+            this.journal.paused_at = new Date().toISOString();
+            (0, run_journal_1.saveJournal)(this.ctx.projectRoot, this.ctx.runId, this.journal);
+        }
     }
     resume() {
         this.paused = false;
+        if (this.journal && this.ctx) {
+            this.journal.scheduler_state = 'running';
+            this.journal.paused_at = null;
+            (0, run_journal_1.saveJournal)(this.ctx.projectRoot, this.ctx.runId, this.journal);
+        }
     }
     cancel() {
         this.cancelled = true;
+        if (this.journal && this.ctx) {
+            this.journal.cancelled = true;
+            this.journal.scheduler_state = 'cancelled';
+            (0, run_journal_1.saveJournal)(this.ctx.projectRoot, this.ctx.runId, this.journal);
+        }
+    }
+    getJournal() {
+        return this.journal;
+    }
+    static loadJournal(projectRoot, runId) {
+        return (0, run_journal_1.loadJournal)(projectRoot, runId);
     }
     emit(ctx, input) {
         const event = (0, bus_1.appendEvent)(ctx.projectRoot, ctx.sessionId, {

package/lib/runtime/verification/index.d.ts

@@ -1 +1,2 @@
 export * from './verification-compiler';
+export * from './verification-manifest';

package/lib/runtime/verification/index.js

@@ -15,3 +15,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./verification-compiler"), exports);
+__exportStar(require("./verification-manifest"), exports);

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

@@ -0,0 +1,58 @@
+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';
+export type VerificationGranularity = 'work_item' | 'wave' | 'run';
+export interface ManifestCheck {
+    check_id: string;
+    acceptance_ref: string | null;
+    status: VerificationStatus;
+    failure_class: FailureClass | null;
+    evidence_refs: string[];
+    duration_ms: number;
+}
+export interface VerificationManifest {
+    manifest_id: string;
+    run_id: string;
+    work_item_id: string | null;
+    wave: number | null;
+    granularity: VerificationGranularity;
+    profile: VerificationProfile;
+    compiled_at: string;
+    checks: ManifestCheck[];
+    summary: {
+        total: number;
+        pass: number;
+        fail: number;
+        skip: number;
+        error: number;
+        all_passed: boolean;
+    };
+}
+export interface ResidualRisk {
+    risk_id: string;
+    work_item_id: string | null;
+    check_id: string | null;
+    failure_class: FailureClass;
+    description: string;
+    severity: 'low' | 'medium' | 'high' | 'critical';
+    mitigation: string | null;
+}
+export interface ResidualRiskLedger {
+    run_id: string;
+    generated_at: string;
+    risks: ResidualRisk[];
+}
+export declare function classifyFailure(result: CheckResult): FailureClass | null;
+export declare function buildManifest(runId: string, results: CheckResult[], options?: {
+    workItemId?: string;
+    wave?: number;
+    granularity?: VerificationGranularity;
+    profile?: VerificationProfile;
+    evidenceRefs?: Map<string, string[]>;
+}): VerificationManifest;
+export declare function buildRiskLedger(runId: string, manifest: VerificationManifest): ResidualRiskLedger;
+export declare function saveManifest(projectRoot: string, runId: string, manifest: VerificationManifest): void;
+export declare function loadManifest(projectRoot: string, runId: string): VerificationManifest | null;
+export declare function saveRiskLedger(projectRoot: string, runId: string, ledger: ResidualRiskLedger): void;
+export declare function loadRiskLedger(projectRoot: string, runId: string): ResidualRiskLedger | null;

package/lib/runtime/verification/verification-manifest.js

@@ -0,0 +1,129 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyFailure = classifyFailure;
+exports.buildManifest = buildManifest;
+exports.buildRiskLedger = buildRiskLedger;
+exports.saveManifest = saveManifest;
+exports.loadManifest = loadManifest;
+exports.saveRiskLedger = saveRiskLedger;
+exports.loadRiskLedger = loadRiskLedger;
+const crypto_1 = __importDefault(require("crypto"));
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+const PROFILE_REQUIRED_CHECKS = {
+    quick: ['deterministic'],
+    standard: ['deterministic', 'policy_failure'],
+    critical: ['deterministic', 'policy_failure', 'evidence_missing', 'flaky'],
+};
+function classifyFailure(result) {
+    if (result.status === 'pass' || result.status === 'skip')
+        return null;
+    if (result.error && (result.error.toLowerCase().includes('timeout') || result.error.toLowerCase().includes('timed out')))
+        return 'timeout';
+    if (result.exit_code === null && result.error)
+        return 'env_setup';
+    if (result.stderr.toLowerCase().includes('policy') || result.stderr.toLowerCase().includes('denied')) {
+        return 'policy_failure';
+    }
+    if (result.exit_code !== 0 && result.stderr === '' && result.stdout === '')
+        return 'evidence_missing';
+    // Default: non-deterministic signals (no reliable exit code pattern)
+    return 'deterministic';
+}
+function buildManifest(runId, results, options = {}) {
+    const profile = options.profile ?? 'standard';
+    const granularity = options.granularity ?? 'run';
+    const evidenceRefs = options.evidenceRefs ?? new Map();
+    const checks = results.map((r) => ({
+        check_id: r.check_id,
+        acceptance_ref: r.acceptance_ref,
+        status: r.status,
+        failure_class: classifyFailure(r),
+        evidence_refs: evidenceRefs.get(r.check_id) ?? [],
+        duration_ms: r.duration_ms,
+    }));
+    const summary = {
+        total: checks.length,
+        pass: checks.filter((c) => c.status === 'pass').length,
+        fail: checks.filter((c) => c.status === 'fail').length,
+        skip: checks.filter((c) => c.status === 'skip').length,
+        error: checks.filter((c) => c.status === 'error').length,
+        all_passed: checks.every((c) => c.status === 'pass' || c.status === 'skip'),
+    };
+    return {
+        manifest_id: `vm-${crypto_1.default.randomBytes(4).toString('hex')}`,
+        run_id: runId,
+        work_item_id: options.workItemId ?? null,
+        wave: options.wave ?? null,
+        granularity,
+        profile,
+        compiled_at: new Date().toISOString(),
+        checks,
+        summary,
+    };
+}
+function buildRiskLedger(runId, manifest) {
+    const risks = [];
+    for (const check of manifest.checks) {
+        if (check.status === 'pass' || check.status === 'skip')
+            continue;
+        if (!check.failure_class)
+            continue;
+        const required = PROFILE_REQUIRED_CHECKS[manifest.profile];
+        if (!required.includes(check.failure_class))
+            continue;
+        risks.push({
+            risk_id: `risk-${crypto_1.default.randomBytes(3).toString('hex')}`,
+            work_item_id: manifest.work_item_id,
+            check_id: check.check_id,
+            failure_class: check.failure_class,
+            description: `Check ${check.check_id} ${check.status}: ${check.failure_class}`,
+            severity: check.failure_class === 'policy_failure' || check.failure_class === 'deterministic'
+                ? 'high'
+                : check.failure_class === 'evidence_missing'
+                    ? 'medium'
+                    : 'low',
+            mitigation: null,
+        });
+    }
+    return {
+        run_id: runId,
+        generated_at: new Date().toISOString(),
+        risks,
+    };
+}
+function saveManifest(projectRoot, runId, manifest) {
+    const p = path_1.default.join(projectRoot, '.oxe', 'runs', runId, 'verification-manifest.json');
+    fs_1.default.mkdirSync(path_1.default.dirname(p), { recursive: true });
+    fs_1.default.writeFileSync(p, JSON.stringify(manifest, null, 2), 'utf8');
+}
+function loadManifest(projectRoot, runId) {
+    const p = path_1.default.join(projectRoot, '.oxe', 'runs', runId, 'verification-manifest.json');
+    if (!fs_1.default.existsSync(p))
+        return null;
+    try {
+        return JSON.parse(fs_1.default.readFileSync(p, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function saveRiskLedger(projectRoot, runId, ledger) {
+    const p = path_1.default.join(projectRoot, '.oxe', 'runs', runId, 'residual-risks.json');
+    fs_1.default.mkdirSync(path_1.default.dirname(p), { recursive: true });
+    fs_1.default.writeFileSync(p, JSON.stringify(ledger, null, 2), 'utf8');
+}
+function loadRiskLedger(projectRoot, runId) {
+    const p = path_1.default.join(projectRoot, '.oxe', 'runs', runId, 'residual-risks.json');
+    if (!fs_1.default.existsSync(p))
+        return null;
+    try {
+        return JSON.parse(fs_1.default.readFileSync(p, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}

package/oxe/workflows/ask.md

@@ -1,5 +1,9 @@
 # OXE — Workflow: ask
 
+> **[DEPRECATED v1.1.0]** Este comando foi incorporado por `/oxe`.
+> Use: `/oxe "sua pergunta"` ou simplesmente `/oxe` para o próximo passo.
+> Este alias continuará funcionando nesta versão por compatibilidade.
+
 <objective>
 Responder perguntas sobre a situação atual do trabalho OXE com máxima robustez, usando o contexto real do repositório, a sessão ativa quando existir, e os artefatos mais recentes da trilha.
 </objective>

package/oxe/workflows/checkpoint.md

@@ -1,7 +1,11 @@
 # OXE — Workflow: checkpoint
 
+> **[DEPRECATED v1.1.0]** Este comando foi incorporado por `/oxe-execute`.
+> Use: `/oxe-execute --checkpoint "<nome>"` para criar snapshot nomeado da sessão.
+> Este alias continuará funcionando nesta versão por compatibilidade.
+
 <objective>
-Criar um **marco nomeado em disco** em `checkpoints/YYYY-MM-DD-HHmm-<slug>.md` do escopo resolvido e atualizar `CHECKPOINTS.md` correspondente (índice): **snapshot da sessão / trilha corrente** para pausar e retomar sem apagar SPEC/PLAN.
+Criar um **marco nomeado em disco** em `checkpoints/YYYY-MM-DD-HHmm-<slug>.md` do escopo resolvido e atualizar `CHECKPOINTS.md` correspondente (índice): **snapshot da sessão / trilha corrente** para pausar e retomar sem apagar SPEC/PLAN.
 
 **Não** duplica o papel de `git commit` nem de `verify`; é **registo explícito** para humanos e agentes. Para **atualizar o mapa do projeto inteiro** e alinhar `.oxe/codebase/` ao código, usar **`compact.md`** (`/oxe-compact`), não este passo.
 </objective>
@@ -9,25 +13,25 @@ Criar um **marco nomeado em disco** em `checkpoints/YYYY-MM-DD-HHmm-<slug>.md` d
 <context>
 - **Checkpoint vs compact** e **momentos chave** da rotina: tabelas canónicas em **`help.md`** (secções *Checkpoint vs compact* e *Momentos chave*) — evitar divergência; este ficheiro descreve só a execução do checkpoint.
 
-- Entrada: texto do utilizador = **slug** e/ou **nota** (ex.: `antes-refactor-auth` + “estado estável, falta T4”).
-- Nome do ficheiro: **`YYYY-MM-DD-HHmm-<slug-kebab>.md`** (hora 24h local ou UTC — documentar na nota se misturar fusos).
-- Frontmatter YAML no checkpoint (ver `oxe/templates/CHECKPOINT.template.md`): `created`, `slug`, `linked` (lista de paths relativos à raiz do repo, tipicamente `.oxe/STATE.md`, `.oxe/SPEC.md`, …).
-- Resolver `active_session` conforme `oxe/workflows/references/session-path-resolution.md`. Com sessão ativa, checkpoints vivem em `.oxe/<active_session>/checkpoints/`; sem sessão ativa, usar `.oxe/checkpoints/`.
-- **Índice** `CHECKPOINTS.md` do mesmo escopo: tabela **mais recente primeiro** com colunas **Data** | **Ficheiro** | **Slug** | **Nota (1 linha)**.
+- Entrada: texto do utilizador = **slug** e/ou **nota** (ex.: `antes-refactor-auth` + “estado estável, falta T4”).
+- Nome do ficheiro: **`YYYY-MM-DD-HHmm-<slug-kebab>.md`** (hora 24h local ou UTC — documentar na nota se misturar fusos).
+- Frontmatter YAML no checkpoint (ver `oxe/templates/CHECKPOINT.template.md`): `created`, `slug`, `linked` (lista de paths relativos à raiz do repo, tipicamente `.oxe/STATE.md`, `.oxe/SPEC.md`, …).
+- Resolver `active_session` conforme `oxe/workflows/references/session-path-resolution.md`. Com sessão ativa, checkpoints vivem em `.oxe/<active_session>/checkpoints/`; sem sessão ativa, usar `.oxe/checkpoints/`.
+- **Índice** `CHECKPOINTS.md` do mesmo escopo: tabela **mais recente primeiro** com colunas **Data** | **Ficheiro** | **Slug** | **Nota (1 linha)**.
 - Não mover nem apagar artefactos canónicos; o checkpoint é **documento adicional**.
 </context>
 
 <process>
-1. Garantir pasta `checkpoints/` do escopo resolvido.
+1. Garantir pasta `checkpoints/` do escopo resolvido.
 2. Normalizar slug a partir dos argumentos do utilizador (kebab-case, ASCII; se vazio, usar `checkpoint`).
 3. Escolher nome único; se colisão, acrescentar sufixo `-b`, `-c`, …
 4. Escrever o ficheiro de checkpoint a partir do template: preencher frontmatter `linked` com os `.oxe/*.md` relevantes que **existem**; corpo com nota do utilizador e **snapshot** (trecho de STATE, uma linha de objetivo SPEC, resumo PLAN).
-5. Se `CHECKPOINTS.md` do escopo resolvido não existir, criar com título `# OXE — Índice de checkpoints` e tabela com cabeçalho; senão, **inserir linha no topo** da tabela.
+5. Se `CHECKPOINTS.md` do escopo resolvido não existir, criar com título `# OXE — Índice de checkpoints` e tabela com cabeçalho; senão, **inserir linha no topo** da tabela.
 6. Responder no chat: caminho do ficheiro novo + como usar na retomada (ler checkpoint + `linked` + próximo `oxe:*`).
 </process>
 
 <success_criteria>
-- [ ] Novo ficheiro em `checkpoints/` do escopo correto com frontmatter e corpo úteis.
-- [ ] `CHECKPOINTS.md` do mesmo escopo atualizado com entrada correspondente.
+- [ ] Novo ficheiro em `checkpoints/` do escopo correto com frontmatter e corpo úteis.
+- [ ] `CHECKPOINTS.md` do mesmo escopo atualizado com entrada correspondente.
 - [ ] SPEC/PLAN/VERIFY intocados salvo o utilizador pedir outra coisa explicitamente.
 </success_criteria>

package/oxe/workflows/debug.md

@@ -1,37 +1,41 @@
 # OXE — Workflow: debug
 
+> **[DEPRECATED v1.1.0]** Este comando foi incorporado por `/oxe-execute`.
+> Use: `/oxe-execute --debug` para ativar diagnóstico técnico explícito.
+> Este alias continuará funcionando nesta versão por compatibilidade.
+
 <objective>
 Orientar **investigação técnica** de um sintoma (teste a falhar, erro em runtime, flake, regressão) **durante** a execução de tarefas do `PLAN.md` ou passos do `QUICK.md`: ciclo **hipótese → experiência mínima → evidência → próximo passo**.
 
 Diferente de **`verify`**, que audita **aceite** contra SPEC/PLAN. Depois de estabilizar com debug, a trilha continua com **`execute`** e, no fecho, **`verify`**.
 </objective>
 
-<context>
-- Aplicar `oxe/workflows/references/reasoning-execution.md`. O debug deve partir de evidência real, testar hipóteses pequenas e fechar com próximo passo único.
-- Pré-requisito: sintoma reproduzível ou descrição clara (mensagem de erro, Tn em falha).
-- Preferir ancorar ao identificador de tarefa **`Tn`** do `PLAN.md` do escopo resolvido quando existir.
-- Resolver `active_session` conforme `oxe/workflows/references/session-path-resolution.md`. Com sessão ativa, usar `.oxe/<active_session>/execution/DEBUG.md`; sem sessão ativa, usar `.oxe/DEBUG.md`.
-- Artefato: **`DEBUG.md`** no escopo correto — ficheiro único com **sessões** datadas (append); não dispersar em vários ficheiros sem convenção.
+<context>
+- Aplicar `oxe/workflows/references/reasoning-execution.md`. O debug deve partir de evidência real, testar hipóteses pequenas e fechar com próximo passo único.
+- Pré-requisito: sintoma reproduzível ou descrição clara (mensagem de erro, Tn em falha).
+- Preferir ancorar ao identificador de tarefa **`Tn`** do `PLAN.md` do escopo resolvido quando existir.
+- Resolver `active_session` conforme `oxe/workflows/references/session-path-resolution.md`. Com sessão ativa, usar `.oxe/<active_session>/execution/DEBUG.md`; sem sessão ativa, usar `.oxe/DEBUG.md`.
+- Artefato: **`DEBUG.md`** no escopo correto — ficheiro único com **sessões** datadas (append); não dispersar em vários ficheiros sem convenção.
 </context>
 
 <process>
-1. Ler `PLAN.md` do escopo resolvido e `.oxe/STATE.md`; se o foco for uma tarefa, localizar **Tn** e o bloco **Verificar**.
-2. Registar em **`DEBUG.md`** do escopo resolvido uma nova sessão:
+1. Ler `PLAN.md` do escopo resolvido e `.oxe/STATE.md`; se o foco for uma tarefa, localizar **Tn** e o bloco **Verificar**.
+2. Registar em **`DEBUG.md`** do escopo resolvido uma nova sessão:
    - **Data** / **Sintoma** (com stack ou comando que falhou).
    - **Hipóteses** (ordenadas por plausibilidade).
    - **Experiências** — o que foi tentado e resultado (uma linha cada).
    - **Evidência atual** — ficheiros, linhas, conclusão parcial.
    - **Próximo passo:** `execute` (continuar correção) | `discuss` (decisão técnica em grupo) | `spec` ou `plan` (requisito ambíguo ou impossível como escrito).
 3. Se a causa for **requisito errado**, documentar em DEBUG e recomendar **`/oxe-spec`** ou **`/oxe-plan`** (e opcionalmente **`/oxe-discuss`**).
-4. Resumo no chat em ≤8 linhas, nesta ordem:
-   - **Contexto lido**
-   - **Hipótese principal**
-   - **Evidência atual**
-   - **Próximo passo**
-</process>
+4. Resumo no chat em ≤8 linhas, nesta ordem:
+   - **Contexto lido**
+   - **Hipótese principal**
+   - **Evidência atual**
+   - **Próximo passo**
+</process>
 
 <success_criteria>
-- [ ] `DEBUG.md` no escopo correto contém sessão datada com sintoma e **Próximo passo** explícito.
+- [ ] `DEBUG.md` no escopo correto contém sessão datada com sintoma e **Próximo passo** explícito.
 - [ ] Quando aplicável, a sessão referencia **Tn** do PLAN.
 - [ ] Não se confunde com verify: não se declara “entrega aprovada” só com debug.
 </success_criteria>

package/oxe/workflows/execute.md

@@ -1,8 +1,36 @@
 # OXE — Workflow: execute
 
 <objective>
-Guiar a **implementação** de um plano OXE com dois modos possíveis:
+Guiar a **implementação** de um plano OXE com dois modos possíveis.
 
+**Flags suportadas:**
+- `--note "texto"` — registrar observação contextual em `OBSERVATIONS.md` antes de iniciar a execução (equivalente a `/oxe-obs`). Pode ser usado com qualquer outro argumento.
+- `--debug` — ativar diagnóstico técnico explícito ao primeiro sinal de falha em vez de esperar 2 tentativas (equivalente a `/oxe-debug`). Fornece stack trace detalhado, hipóteses e fix.
+- `--deep-diagnosis` — iniciar diretamente em modo de diagnóstico pós-falha persistente (equivalente a `/oxe-forensics`). Usar quando a execução já falhou repetidamente e o estado está corrompido ou inconsistente.
+- `--checkpoint "<nome>"` — criar snapshot nomeado do estado da sessão antes de iniciar ou após concluir (equivalente a `/oxe-checkpoint`). Útil antes de experimentos ou ondas arriscadas.
+- `--iterative` — ativar modo B com loop automático até verify passar, com retry controlado por `loop_max` (equivalente a `/oxe-loop`).
+
+**Nota de compatibilidade v1.1.0:** `/oxe-obs`, `/oxe-debug`, `/oxe-forensics`, `/oxe-checkpoint` e `/oxe-loop` foram incorporados por este comando. Esses comandos legados continuam funcionando mas exibem aviso de migração.
+
+</objective>
+
+<flags_processing>
+## Processamento de flags (executar antes do step 1)
+
+Ao receber qualquer argumento, verificar flags antes de iniciar o fluxo principal:
+
+1. **`--note "texto"`**: escrever entrada em `OBSERVATIONS.md` do escopo resolvido com status `pendente`, impacto `execute`, severidade `info`. Marcar como `incorporada → execute (data)` imediatamente após registrar. Continuar com o fluxo normal.
+
+2. **`--checkpoint "<nome>"`**: executar a lógica de `oxe/workflows/checkpoint.md` com o slug fornecido antes de iniciar a onda. Reportar confirmação do snapshot. Continuar.
+
+3. **`--deep-diagnosis`**: saltar diretamente para o fluxo de `oxe/workflows/forensics.md` com o contexto atual do `EXECUTION-RUNTIME.md` e `STATE.md`. Não iniciar nova onda sem resolução explícita.
+
+4. **`--debug`**: ajustar `<failure_mode>` para acionar diagnóstico imediato na primeira falha (sem 2 tentativas antes). Reportar hipóteses, evidências e fix com mais detalhe.
+
+5. **`--iterative`**: registrar em STATE.md: `execute_mode: por_onda` e `loop_max: 3` (ou o valor de config). Informar ao usuário que o modo iterativo está ativo.
+</flags_processing>
+
+<execution_modes>
 **Modo Solo (padrão):** seguir `PLAN.md` do escopo resolvido da sessão onda a onda sem `plan-agents.json`. O agente implementa diretamente cada tarefa Tn da onda atual, roda a verificação e avança. Não exige nenhum artefato além do PLAN.md.
 
 **Modo com Agentes (extensão):** quando existe `plan-agents.json` válido no escopo resolvido (schema 2+, lifecycle ativo, runId alinhado ao STATE), adotar roles e personas por agente conforme o blueprint.
@@ -10,7 +38,7 @@ Guiar a **implementação** de um plano OXE com dois modos possíveis:
 **Seleção de execução (redução de requisições):** quando o plano tem 2+ ondas, o usuário escolhe entre Completo (1 sessão), Por onda (N sessões) ou Por tarefa (N tarefas). A escolha é feita **uma vez** no início.
 
 Se existir apenas **`QUICK.md`** no escopo resolvido: tratar passos numerados como onda única (modo sempre Completo).
-</objective>
+</execution_modes>
 
 <modo_solo>
 ## Modo Solo — Execução direta do PLAN.md

package/oxe/workflows/forensics.md

@@ -1,14 +1,18 @@
 # OXE — Workflow: forensics
 
+> **[DEPRECATED v1.1.0]** Este comando foi incorporado por `/oxe-execute`.
+> Use: `/oxe-execute --deep-diagnosis` para diagnóstico pós-falha persistente.
+> Este alias continuará funcionando nesta versão por compatibilidade.
+
 <objective>
 Diagnosticar **incidentes de fluxo** após falha ou incoerência entre artefatos `.oxe/`, Git e saída de `oxe-cc doctor`: produzir **`FORENSICS.md`** no escopo resolvido com linha do tempo, hipótese de causa e **exatamente um** próximo passo canónico OXE (`scan`, `plan` ou `execute` — incluindo ações como reinstalar workflows ou correr verify como parte do movimento **execute**).
 
 Não reescrever `SPEC.md` nem apagar `PLAN.md`; apenas **recomendar** o reingresso na trilha.
 </objective>
 
-<context>
-- Aplicar `oxe/workflows/references/reasoning-execution.md` para montar a linha do tempo e `oxe/workflows/references/reasoning-status.md` para devolver um único reingresso recomendado.
-- Usar quando: `VERIFY.md` com falhas ou gaps não explicados, `oxe-cc doctor` com **FALHA**, `STATE.md` contradiz ficheiros presentes (ex.: “onda concluída” sem `VERIFY.md`), ou o utilizador indica estar **preso** após várias tentativas de replan.
+<context>
+- Aplicar `oxe/workflows/references/reasoning-execution.md` para montar a linha do tempo e `oxe/workflows/references/reasoning-status.md` para devolver um único reingresso recomendado.
+- Usar quando: `VERIFY.md` com falhas ou gaps não explicados, `oxe-cc doctor` com **FALHA**, `STATE.md` contradiz ficheiros presentes (ex.: “onda concluída” sem `VERIFY.md`), ou o utilizador indica estar **preso** após várias tentativas de replan.
 - Resolver `active_session` conforme `oxe/workflows/references/session-path-resolution.md`; ler `.oxe/STATE.md` global e os artefatos de sessão (`VERIFY.md`, `PLAN.md`, `SPEC.md`, `QUICK.md`) no escopo resolvido.
 - **Git é opcional:** em sandbox sem Git ou sem permissão de terminal, **não** falhar o workflow; registar em `FORENSICS.md` que Git não foi avaliado.
 - Opcional: saída resumida de `npx oxe-cc doctor` no diretório do projeto.
@@ -33,12 +37,12 @@ Não reescrever `SPEC.md` nem apagar `PLAN.md`; apenas **recomendar** o reingres
    - **Próximo passo OXE recomendado:** **um único** valor entre `scan` | `plan` | `execute` e o **comando** correspondente (`/oxe-scan`, `/oxe-plan`, `/oxe-execute` ou `npx oxe-cc@latest` / `npx oxe-cc doctor` quando a causa for tooling).
    - **Justificativa** — uma frase que liga evidência ao passo escolhido.
 4. Atualizar **`.oxe/STATE.md`** global com uma linha opcional sob decisões ou contexto: referência a `FORENSICS.md` e fase sugerida (ex.: `forensics_complete` → próximo conforme passo recomendado).
-5. Responder no chat em ≤8 linhas, nesta ordem:
-   - **Leitura atual**
-   - **Hipótese de causa**
-   - **Próximo passo**
-   - **Motivo**
-</process>
+5. Responder no chat em ≤8 linhas, nesta ordem:
+   - **Leitura atual**
+   - **Hipótese de causa**
+   - **Próximo passo**
+   - **Motivo**
+</process>
 
 <success_criteria>
 - [ ] `FORENSICS.md` existe no escopo correto com **Próximo passo OXE recomendado** igual a **um** entre `scan`, `plan`, `execute`.