oxe-cc 1.6.0 → 1.7.0

package/oxe/templates/FIXTURE-PACK.template.json

@@ -21,14 +21,21 @@
           "summary": "deve concluir sem erro e persistir o artefato esperado"
         }
       ],
-      "expected_checks": [
-        "npm test -- example"
-      ],
-      "critical_fields": [
-        "id",
-        "status"
-      ],
-      "critical_gaps": []
-    }
-  ]
-}
+      "expected_checks": [
+        "npm test -- example"
+      ],
+      "negative_cases": [
+        {
+          "summary": "entrada inválida deve falhar de forma controlada",
+          "expected": "erro classificado, sem mutação parcial"
+        }
+      ],
+      "critical_fields": [
+        "id",
+        "status"
+      ],
+      "source_anchor": "RA-01",
+      "critical_gaps": []
+    }
+  ]
+}

package/oxe/templates/FIXTURE-PACK.template.md

@@ -2,10 +2,11 @@
 
 > Fixtures mínimos para reduzir improviso em parsing, integração, transformação, migração e builders.
 
-## Status
-
-- **Status:** ready | not_ready | not_applicable
-- **Critical gaps abertos:** nenhum | listar
+## Status
+
+- **Status:** ready | not_ready | not_applicable
+- **Critical gaps abertos:** nenhum | listar
+- **Cobertura de tarefas de risco:** N/N
 
 ## Fixtures
 
@@ -13,9 +14,17 @@
 
 - **Task:** T1
 - **Status:** ready | missing | not_applicable
-- **Inputs:** payload, arquivo exemplo, query, blob ou mensagem
-- **Expected outputs:** linha, evento, arquivo, rowset, status etc.
-- **Expected checks:** `...`
-- **Campos críticos / offsets:** ...
-- **Smoke command:** `...`
-- **Critical gaps:** nenhum | listar
+- **Inputs:** payload, arquivo exemplo, query, blob ou mensagem
+- **Expected outputs:** linha, evento, arquivo, rowset, status etc.
+- **Expected checks:** `...`
+- **Campos críticos / offsets:** ...
+- **Smoke command:** `...`
+- **Negative cases:** input inválido, erro esperado, limite ou regressão principal
+- **Source anchor:** RA-01 | not_applicable
+- **Critical gaps:** nenhum | listar
+
+## Regras
+
+- Parser, layout posicional, integração externa, fila, migração, transformação e builder exigem fixture `ready`.
+- Docs-only pode usar `not_applicable`, mas precisa declarar o motivo.
+- Fixture inventada sem anchor ou sem expected output não sustenta execução.

package/oxe/templates/IMPLEMENTATION-PACK.template.json

@@ -12,8 +12,10 @@
       "exact_paths": [
         "src/example.ts"
       ],
-      "write_set": "closed",
-      "symbols": [
+      "write_set": "closed",
+      "mutation_scope": "code",
+      "risk": "medium",
+      "symbols": [
         {
           "kind": "function",
           "name": "exampleHandler",
@@ -21,7 +23,7 @@
           "signature": "(input: ExampleInput) => ExampleOutput"
         }
       ],
-      "contracts": [
+      "contracts": [
         {
           "name": "example-contract",
           "input_shape": "ExampleInput",
@@ -33,7 +35,20 @@
             "mutar schema fora do write set"
           ]
         }
-      ],
+      ],
+      "required_imports": [
+        {
+          "module": "src/example.ts",
+          "symbol": "ExampleInput",
+          "reason": "tipo de entrada do contrato"
+        }
+      ],
+      "implementation_sequence": [
+        "confirmar símbolo e contrato no path alvo",
+        "implementar menor delta",
+        "rodar expected checks",
+        "registrar evidência"
+      ],
       "snippets": [
         {
           "source_ref": "not_applicable",
@@ -42,11 +57,12 @@
           "status": "not_applicable"
         }
       ],
-      "expected_checks": [
-        "npm test -- example"
-      ],
-      "requires_fixture": false,
-      "critical_gaps": []
-    }
+      "expected_checks": [
+        "npm test -- example"
+      ],
+      "requires_fixture": false,
+      "rollback_or_containment": "not_applicable",
+      "critical_gaps": []
+    }
   ]
 }

package/oxe/templates/IMPLEMENTATION-PACK.template.md

@@ -6,31 +6,43 @@
 
 - **Status:** ready | not_ready | not_applicable
 - **Critical gaps abertos:** nenhum | listar
-- **Fonte:** `PLAN.md` + código real + anchors locais
+- **Fonte:** `PLAN.md` + código real + anchors locais
+- **Regra de confiança:** se qualquer tarefa mutável estiver `ready: false`, o plano não pode sustentar `Confiança > 90%`.
 
 ## Tarefas
 
 ### T1 — (título)
 
-- **Mode:** mutating | docs_only | external | not_applicable
-- **Ready:** true | false
-- **Exact paths:** `src/...`, `config/...`
-- **Write set:** closed | external | not_applicable
-- **Symbols alvo:**
-  - `kind:name(path)` — assinatura ou shape esperado
-- **Contracts:**
-  - **Nome:** (ex.: payload parser)
-  - **Entrada:** ...
-  - **Saída:** ...
-  - **Invariants:** ...
-  - **Not allowed:** ...
-- **Expected checks:**
-  - `...`
-- **Requires fixture:** true | false
-- **Snippet/base local:** path ou `not_applicable`
-- **Critical gaps:** nenhum | listar
+- **Mode:** mutating | docs_only | external | not_applicable
+- **Ready:** true | false
+- **Exact paths:** `src/...`, `config/...`
+- **Write set:** closed | external | not_applicable
+- **Mutation scope:** code | config | schema | migration | infra | docs
+- **Risk:** low | medium | high | critical
+- **Symbols alvo:**
+  - `kind:name(path)` — assinatura ou shape esperado
+- **Imports/dependências obrigatórias:**
+  - `module` / `type` / `provider`
+- **Contracts:**
+  - **Nome:** (ex.: payload parser)
+  - **Entrada:** ...
+  - **Saída:** ...
+  - **Invariants:** ...
+  - **Not allowed:** ...
+- **Sequência mínima:**
+  1. Confirmar símbolo e contrato no path alvo.
+  2. Implementar o menor delta.
+  3. Rodar o check da tarefa.
+  4. Registrar evidência.
+- **Expected checks:**
+  - `...`
+- **Requires fixture:** true | false
+- **Snippet/base local:** path ou `not_applicable`
+- **Rollback/contensão:** comando, diff reversível, feature flag, checkpoint ou `not_applicable`
+- **Critical gaps:** nenhum | listar
 
 ## Observações
 
-- Use caminhos exatos; não usar `...`.
-- Tarefa mutável sem `symbols`, `contracts`, `write_set: closed` e `expected_checks` não deve sustentar confiança `> 90%`.
+- Use caminhos exatos; não usar `...`.
+- Tarefa mutável sem `symbols`, `contracts`, `write_set: closed` e `expected_checks` não deve sustentar confiança `> 90%`.
+- Tarefa L/XL ou integração externa precisa de sequência mínima, rollback/contensão e fixture ou justificativa explícita.

package/oxe/templates/PLAN.template.md

@@ -2,8 +2,18 @@
 oxe_doc: plan
 status: draft
 updated: YYYY-MM-DD
-inputs: []
----
+inputs: []
+spec_version: ""
+plan_confidence_threshold: 90
+goal_backward_verification: required
+rationality_gate: required
+risk_level: low | medium | high | critical
+autonomous: false
+must_haves: []
+dependencies: []
+checkpoints: []
+evidence_expectation: manifest | command | manual | mixed
+---
 
 <!--
   Metadados OXE. Manter --- antes do primeiro #. Atualize `updated` a cada revisão significativa.
@@ -21,20 +31,23 @@ inputs: []
 - **Tarefas:** (número)
 - **Artefatos racionais:** `IMPLEMENTATION-PACK`, `REFERENCE-ANCHORS`, `FIXTURE-PACK`
 
-## Autoavaliação do Plano
-
-- **Melhor plano atual:** sim
-- **Confiança:** 92%
-- **Base da confiança:**
-  - Completude dos requisitos: 23/25
+## Autoavaliação do Plano
+
+- **Melhor plano atual:** sim
+- **Confiança:** 92%
+- **Limiar para execute:** > 90%
+- **Resultado do gate racional:** ready | not_ready
+- **Base da confiança:**
+  - Completude dos requisitos: 23/25
   - Dependências conhecidas: 14/15
   - Risco técnico: 18/20
   - Impacto no código existente: 14/15
   - Clareza da validação / testes: 14/15
   - Lacunas externas / decisões pendentes: 9/10
-- **Principais incertezas:** (0–3 bullets)
-- **Alternativas descartadas:** (1–2 linhas)
-- **Condição para replanejar:** (critério objetivo)
+- **Principais incertezas:** (0–3 bullets)
+- **Alternativas descartadas:** (1–2 linhas)
+- **Condição para replanejar:** (critério objetivo)
+- **Bloqueadores de execução:** nenhum | listar gaps críticos
 
 <confidence_vector cycle="C-NN" generated_at="YYYY-MM-DDTHH:MM:SSZ">
   <dim name="requirements"   score="0.92" weight="25" note="completude dos requisitos" />
@@ -71,12 +84,26 @@ inputs: []
 
 - (ex.: branch base, feature flags, migrations)
 
-## Artefatos racionais de execução
-
-- **IMPLEMENTATION-PACK:** `ready | not_ready | not_applicable`
-- **REFERENCE-ANCHORS:** `ready | not_ready | not_applicable`
-- **FIXTURE-PACK:** `ready | not_ready | not_applicable`
-- **Critical gaps abertos:** (nenhum | listar IDs/causas)
+## Artefatos racionais de execução
+
+- **IMPLEMENTATION-PACK:** `ready | not_ready | not_applicable`
+- **REFERENCE-ANCHORS:** `ready | not_ready | not_applicable`
+- **FIXTURE-PACK:** `ready | not_ready | not_applicable`
+- **Critical gaps abertos:** (nenhum | listar IDs/causas)
+
+### Contrato goal-backward
+
+| Critério | Evidência esperada | Tarefa(s) | Risco se falhar |
+|----------|--------------------|-----------|-----------------|
+| A1 | comando, arquivo, fixture ou UAT | T1 | high |
+
+### Must-haves de execução
+
+- Nenhuma tarefa mutável com path ambíguo.
+- Nenhum símbolo alvo indefinido.
+- Nenhuma referência crítica não materializada.
+- Nenhuma tarefa de parsing/integração/transformação sem fixture ou justificativa `not_applicable`.
+- Nenhum checkpoint humano pendente antes de side effect crítico.
 
 ## Replanejamento
 
@@ -88,19 +115,23 @@ inputs: []
 
 ## Tarefas
 
-### T1 — (título)
-
-- **Arquivos prováveis:** `…`
-- **Depende de:** —
-- **Onda:** 1
-- **Complexidade:** S
-- **Verificar:**
-  - Comando: `…`
-  - Manual: (opcional) …
-- **Implementar:** o mínimo para fazer a verificação acima passar.
-- **Aceite vinculado:** A1, A2 (IDs da tabela de critérios em SPEC.md)
-- **Contrato racional:** ver `IMPLEMENTATION-PACK.json` (task `T1`)
-
----
+### T1 — (título)
+
+- **Arquivos alvo:** `src/exato.ts`
+- **Depende de:** —
+- **Onda:** 1
+- **Complexidade:** S
+- **Risco:** low | medium | high | critical
+- **Evidência de entrada:** SPEC A1 | DISCUSS D-01 | RESEARCH RA-01 | codebase path
+- **Checkpoint:** nenhum | CHK-01
+- **Verificar:**
+  - Comando: `…`
+  - Manual: (opcional) …
+- **Implementar:** o mínimo para fazer a verificação acima passar.
+- **Aceite vinculado:** A1, A2 (IDs da tabela de critérios em SPEC.md)
+- **Contrato racional:** ver `IMPLEMENTATION-PACK.json` (task `T1`)
+- **Rollback/contensão:** obrigatório para risco high/critical; `not_applicable` se low/medium.
+
+---
 
 _(Adicione T2, T3, … conforme o comando oxe:plan.)_

package/oxe/templates/REFERENCE-ANCHORS.template.md

@@ -3,22 +3,26 @@
 > Materialização de referências críticas usadas pelo plano. Toda referência externa, predecessor, layout ou contrato que sustente uma tarefa deve virar âncora reproduzível aqui.
 
 <reference_anchors version="1" ready="false" status="not_ready">
-  <anchor
+  <anchor
     id="RA-01"
     task="T1"
     critical="true"
     status="resolved"
     source_type="local"
-    path=".oxe/investigations/externals/exemplo.txt"
-    source_ref="external-ref: exemplo">
-    <relevance>Por que esta referência sustenta a tarefa.</relevance>
-    <action>copy | adapt | consult</action>
-    <summary>Resumo semântico curto do trecho relevante ou do contrato.</summary>
-  </anchor>
-</reference_anchors>
+    path=".oxe/investigations/externals/exemplo.txt"
+    snippet_ref="lines 10-30"
+    source_ref="external-ref: exemplo">
+    <relevance>Por que esta referência sustenta a tarefa.</relevance>
+    <action>copy | adapt | consult</action>
+    <summary>Resumo semântico curto do trecho relevante ou do contrato.</summary>
+    <critical_fields>IDs, colunas, offsets, eventos ou contratos que não podem ser improvisados.</critical_fields>
+  </anchor>
+</reference_anchors>
 
 ## Regras
 
 - Se não houver referência aplicável, usar `<reference_anchors ... status="not_applicable" ready="true">`.
-- `critical="true"` exige `status="resolved"` antes do execute.
-- `path` deve ser reproduzível no workspace ou materializado em `.oxe/investigations/externals/`.
+- `critical="true"` exige `status="resolved"` antes do execute.
+- `path` deve ser reproduzível no workspace ou materializado em `.oxe/investigations/externals/`.
+- Referência solta em texto não é evidência. Se o path/range/snippet não puder ser materializado, marcar `status="missing"` e derrubar readiness.
+- Anchors podem ser locais, externos materializados, predecessor interno, contrato público, fixture ou decisão registrada.

package/oxe/templates/SUMMARY.template.md

@@ -1,20 +1,50 @@
-# OXE — Resumo de sessão
-
-> Usado por **verify** (append) e por **plan --replan** para contexto incremental. Podes criar manualmente a partir deste template.
-
-## Sessão
-
-- **Data:** (ISO ou legível)
-- **Spec / plano:** (referência breve a `.oxe/SPEC.md` / `.oxe/PLAN.md`)
-
-## Feito nesta sessão
-
-- …
-
-## Decisões / notas
-
-- …
-
-## Pendente ou follow-up
-
-- …
+# OXE — Resumo de sessão
+
+> Usado por **execute**, **verify** e **plan --replan** para contexto incremental, evidência e retomada.
+
+## Sessão
+
+- **Data:** (ISO ou legível)
+- **Run:** ...
+- **Spec / plano:** (referência breve a `.oxe/SPEC.md` / `.oxe/PLAN.md`)
+- **Modo:** completo | por_onda | por_tarefa | runtime
+
+## Performance
+
+- **Ondas concluídas:** N/N
+- **Tarefas concluídas:** N/N
+- **Retries:** N
+- **Checkpoints:** aprovados N | pendentes N | waived N
+
+## Feito nesta sessão
+
+- …
+
+## Arquivos criados/modificados
+
+| Path | Motivo | Tarefa |
+|------|--------|--------|
+| `src/example.ts` | implementação do contrato | T1 |
+
+## Decisões / desvios
+
+- **Decisões aplicadas:** D-01, D-02
+- **Desvios do plano:** nenhum | listar com motivo, impacto e evidência
+- **Fixes inline:** nenhum | listar hipótese e comando de verificação
+
+## Evidências
+
+- **Manifest:** `verification-manifest.json` | not_available
+- **Coverage:** `evidence-coverage.json` | not_available
+- **Residual risk:** `residual-risk-ledger.json` | not_available
+- **Comandos executados:** ...
+
+## Pendente ou follow-up
+
+- …
+
+## Next Step Readiness
+
+- **Próximo passo recomendado:** `/oxe-verify` | `/oxe-plan --replan` | `/oxe-execute`
+- **Bloqueadores:** nenhum | listar
+- **Risco residual:** low | medium | high | critical

package/oxe/workflows/debug.md

@@ -15,17 +15,19 @@ Diferente de **`verify`**, que audita **aceite** contra SPEC/PLAN. Depois de est
 - 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.
+- Artefato: **`DEBUG.md`** no escopo correto — ficheiro único com **sessões** datadas (append); não dispersar em vários ficheiros sem convenção.
+- Agente especializado: quando disponível, usar `oxe-debugger` para conduzir hipótese, reprodução mínima, evidência, eliminados e handoff retomável. O agente não deve declarar entrega aprovada; após correção, a trilha volta para `execute` e depois `verify`.
 </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:
-   - **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).
+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).
+   - **Eliminados** — hipóteses descartadas e evidência.
+   - **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**

package/oxe/workflows/execute.md

@@ -124,12 +124,14 @@ Quando o comando `**Verificar:**` de uma tarefa `Tn` falha, **não parar silenci
 
 **Context pack prioritário:** antes de abrir o conjunto amplo de artefatos, resolver `.oxe/context/packs/execute.md` e `.oxe/context/packs/execute.json` como entrada principal do passo. Se o pack estiver fresco/coerente, usar `read_order` e `selected_artifacts` para limitar o reconhecimento inicial à onda/tarefa atual. Se estiver stale, ausente ou com lacunas críticas, fazer fallback explícito para leitura direta e registrar isso no runtime ou no resumo da execução.
 
-**Artefatos racionais obrigatórios:** quando a execução vier de `PLAN.md`, ler antes da primeira mutação:
-- `IMPLEMENTATION-PACK.md` / `IMPLEMENTATION-PACK.json`
-- `REFERENCE-ANCHORS.md`
-- `FIXTURE-PACK.md` / `FIXTURE-PACK.json`
-
-O `execute` é **pack-first**, não apenas `plan-first`. Esses artefatos existem para impedir improviso de paths, interfaces, referências externas e fixtures. Se estiverem ausentes, inconsistentes ou com `critical_gap`, a execução deve bloquear e devolver para replanejamento.
+**Artefatos racionais obrigatórios:** quando a execução vier de `PLAN.md`, ler antes da primeira mutação:
+- `IMPLEMENTATION-PACK.md` / `IMPLEMENTATION-PACK.json`
+- `REFERENCE-ANCHORS.md`
+- `FIXTURE-PACK.md` / `FIXTURE-PACK.json`
+
+O `execute` é **pack-first**, não apenas `plan-first`. Esses artefatos existem para impedir improviso de paths, interfaces, referências externas e fixtures. Se estiverem ausentes, inconsistentes ou com `critical_gap`, a execução deve bloquear e devolver para replanejamento.
+
+**Agente executor especializado:** quando um runtime suportar agentes OXE, o papel esperado é `oxe-executor`. Para ondas com UI, debug, integração ou validação pesada, consultar os agentes especializados correspondentes, mas manter o estado operacional em `.oxe/` e no runtime.
 
 **Runtime operacional:** usar `EXECUTION-RUNTIME.md` do escopo resolvido como artefato tático da execução. Ele deve refletir agentes ativos, onda atual, handoffs, evidências, retries, checkpoints pendentes e tarefas bloqueadas. O `PLAN.md` continua estratégico; o runtime regista a operação do ciclo.
 
@@ -195,11 +197,12 @@ Se condições não atendidas: responder sem persona; sugerir `/oxe-plan-agent`
    - o bloco `<confidence_vector>` deve existir e ser coerente com a confiança declarada;
    - se `.oxe/config.json` definir `plan_confidence_threshold`, usar esse limiar respeitando o piso canónico de `90%`; senão, usar `90%`;
    - se a confiança não superar o limiar (`<=`) ou se a autoavaliação estiver incompleta, **não executar**. Registrar o bloqueio e orientar redução de incerteza (`/oxe-discuss`, `/oxe-research` ou `/oxe-plan --replan`).
-2a. Antes da primeira mutação, validar os artefatos racionais do plano:
+2a. Antes da primeira mutação, validar os artefatos racionais do plano:
    - `IMPLEMENTATION-PACK.json` deve existir, estar `ready`, cobrir cada `Tn` mutável e usar `exact_paths` sem `...`, `symbols`, `contracts`, `write_set: "closed"` e `expected_checks`;
    - `REFERENCE-ANCHORS.md` deve existir e manter todas as âncoras críticas em `status: resolved`;
    - `FIXTURE-PACK.json` deve existir, estar `ready` e cobrir tarefas de parser/layout/integração/transformação/fila/migração/builder;
-   - se algum pack tiver `critical_gap`, **não executar**. Registrar o bloqueio explicitamente em `EXECUTION-RUNTIME.md` / `STATE.md` e recomendar um único próximo passo: normalmente `/oxe-plan --replan`.
+   - se algum pack tiver `critical_gap`, **não executar**. Registrar o bloqueio explicitamente em `EXECUTION-RUNTIME.md` / `STATE.md` e recomendar um único próximo passo: normalmente `/oxe-plan --replan`.
+   - se uma tarefa mutável usar path com `...`, símbolo indefinido, write-set aberto ou fixture obrigatória ausente, bloquear a tarefa mesmo que o `PLAN.md` pareça completo.
 3. Antes da primeira mudança, verificar `CHECKPOINTS.md` e `EXECUTION-RUNTIME.md` do escopo resolvido:
    - se houver checkpoint `pending_approval` que se aplique à onda atual, **não avançar**;
    - inicializar ou atualizar o runtime com onda atual, status, agentes ativos, handoffs e evidências esperadas.

package/oxe/workflows/forensics.md

@@ -16,7 +16,8 @@ Não reescrever `SPEC.md` nem apagar `PLAN.md`; apenas **recomendar** o reingres
 - 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.
-- Se o sintoma for **mapa OXE desatualizado** (ex.: `STACK.md` / estrutura em `.oxe/codebase/` claramente atrás do repo) sem workflows em falta, a **Hipótese de causa** ou a **Justificativa** pode mencionar **`/oxe-compact`** como ação complementar **depois** de escolhido o passo canónico — o próximo passo OXE recomendado continua a ser **um** entre `scan` | `plan` | `execute`.
+- Se o sintoma for **mapa OXE desatualizado** (ex.: `STACK.md` / estrutura em `.oxe/codebase/` claramente atrás do repo) sem workflows em falta, a **Hipótese de causa** ou a **Justificativa** pode mencionar **`/oxe-compact`** como ação complementar **depois** de escolhido o passo canónico — o próximo passo OXE recomendado continua a ser **um** entre `scan` | `plan` | `execute`.
+- Agentes úteis: `oxe-debugger` para falha técnica, `oxe-integration-checker` para divergência entre ondas/artefatos, `oxe-validation-auditor` para evidence gaps e `oxe-codebase-mapper` quando o mapa estiver obsoleto.
 
 **Git (opcional)** — se o agente puder correr terminal **ou** o utilizador colar saída, preferir recolher:
 
@@ -32,8 +33,9 @@ Não reescrever `SPEC.md` nem apagar `PLAN.md`; apenas **recomendar** o reingres
 2. Recolher evidência: STATE, VERIFY, PLAN, SPEC, QUICK (trechos relevantes), saída de **doctor** se disponível, e **Git (opcional)** conforme bloco no context (se indisponível, seguir sem Git). Se `OXE-EVENTS.ndjson` existir no escopo resolvido, correr `npx oxe-cc runtime replay --write` para gerar **`REPLAY-SESSION.md`** — timeline completa da execução com deltas entre eventos; incluir achados relevantes na seção **Linha do tempo** do `FORENSICS.md`.
 3. Redigir **`FORENSICS.md`** no escopo resolvido com secções fixas:
    - **Data** (ISO) e **Sintoma** (1–3 frases).
-   - **Linha do tempo** — bullets curtos (o que se tentou, ordem aproximada); **incorporar** commits/datas e ficheiros mais tocados quando houver evidência Git; se Git não foi avaliado, linha explícita: *Git não avaliado (ambiente/indisponível)*.
-   - **Hipótese de causa** — uma ou duas hipóteses ranqueadas (ex.: plano desalinhado, mapa desatualizado, workflows em falta, implementação incompleta); usar padrões Git (ficheiros repetidos, working tree suja) quando útil.
+   - **Linha do tempo** — bullets curtos (o que se tentou, ordem aproximada); **incorporar** commits/datas e ficheiros mais tocados quando houver evidência Git; se Git não foi avaliado, linha explícita: *Git não avaliado (ambiente/indisponível)*.
+   - **Divergências de consistência** — diferenças entre `ACTIVE-RUN.json`, run file, eventos, gates, policy decisions, VERIFY e STATE quando existirem.
+   - **Hipótese de causa** — uma ou duas hipóteses ranqueadas (ex.: plano desalinhado, mapa desatualizado, workflows em falta, implementação incompleta); usar padrões Git (ficheiros repetidos, working tree suja) quando útil.
    - **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).