oxe-cc 0.6.5 → 0.7.0

package/oxe/workflows/next.md

@@ -4,12 +4,13 @@
 Inspecionar `.oxe/STATE.md` global, a sessão ativa quando existir, e a existência de `SPEC.md`, `PLAN.md`, `QUICK.md`, `VERIFY.md` e `.oxe/codebase/` para recomendar **exatamente um** próximo passo OXE e **uma** frase de justificativa — sem lista de alternativas equiparáveis.
 </objective>
 
-<context>
+<context>
 - O usuário pode rodar **`npx oxe-cc status`** no terminal para a mesma lógica resumida. **`npx oxe-cc status --hints`** (ou **`--json --hints`**) acrescenta lembretes **paralelos** (idade do scan/compact por config) — **não** altera o único passo canónico que este workflow deve devolver.
 - Resolver `active_session` conforme `oxe/workflows/references/session-path-resolution.md`. Com sessão ativa, preferir os artefatos da sessão antes de olhar a raiz legada.
-- Se houver empate aparente (ex.: poderia ser spec ou quick), preferir **spec** quando já existir mapa de codebase; preferir **quick** só se o usuário deixar explícito que é correção mínima.
-- **Blueprint plan-agent:** se **`.oxe/plan-agents.json`** tiver `lifecycle.status === "invalidated"`, o próximo passo **não** assume papéis desse JSON; continuar a raciocinar só com **PLAN.md** / **QUICK.md** / **VERIFY.md** e **STATE.md**. Se o utilizador quiser de novo agentes + mensagens, indicar **`/oxe-plan-agent`**.
-</context>
+- Se houver empate aparente (ex.: poderia ser spec ou quick), preferir **spec** quando já existir mapa de codebase; preferir **quick** só se o usuário deixar explícito que é correção mínima.
+- **Blueprint plan-agent:** se **`.oxe/plan-agents.json`** tiver `lifecycle.status === "invalidated"`, o próximo passo **não** assume papéis desse JSON; continuar a raciocinar só com **PLAN.md** / **QUICK.md** / **VERIFY.md** e **STATE.md**. Se o utilizador quiser de novo agentes + mensagens, indicar **`/oxe-plan-agent`**.
+- Priorizar sempre o passo que **reduz incerteza primeiro**. Se o plano existente não for o melhor plano atual ou estiver abaixo do limiar de confiança, o próximo passo não pode ser `execute`.
+</context>
 
 <process>
 1. Se `.oxe/` ou `STATE.md` não existir → **único** passo: **scan** (ou `oxe-cc init-oxe` seguido de scan).
@@ -20,10 +21,11 @@ Inspecionar `.oxe/STATE.md` global, a sessão ativa quando existir, e a existên
    - Senão → **execute** (há passos curtos a implementar).
 4. Se não houver `SPEC.md` no escopo resolvido e não for quick intencional declarado → **spec** (passo único).
 5. Se houver SPEC no escopo resolvido mas não PLAN → se `.oxe/config.json` tiver `discuss_before_plan: true` e faltar **`DISCUSS.md`** com decisões → **discuss**; senão → **plan**.
-6. Se PLAN existe, **VERIFY.md** ainda **não** existe ou está claramente antes da implementação atual → **execute** (onda atual).
-7. Se PLAN existe e VERIFY falta após implementação declarada → **verify**.
-8. Se VERIFY indica falha ou gaps não resolvidos → **plan** (replanejamento) como passo único, com referência a `SUMMARY.md`.
-9. Se VERIFY OK e estado coerente → **spec** ou **quick** para **próxima** entrega, ou mensagem “fluxo da feature atual concluído”.
+6. Se PLAN existe mas a seção **Autoavaliação do Plano** disser `Melhor plano atual: não`, ou a `Confiança` estiver abaixo do limiar configurado (padrão 70%), o próximo passo deve ser **plan** (replanejar) ou **discuss/research** se a própria autoavaliação indicar isso.
+7. Se PLAN existe, **VERIFY.md** ainda **não** existe ou está claramente antes da implementação atual → **execute** (onda atual).
+8. Se PLAN existe e VERIFY falta após implementação declarada → **verify**.
+9. Se VERIFY indica falha ou gaps não resolvidos → **plan** (replanejamento) como passo único, com referência a `SUMMARY.md`.
+10. Se VERIFY OK e estado coerente → **spec** ou **quick** para **próxima** entrega, ou mensagem “fluxo da feature atual concluído”.
 
 **Saída obrigatória (só isto, nesta ordem):**
 

package/oxe/workflows/obs.md

@@ -8,30 +8,32 @@ Registrar uma **observação contextual** em **`.oxe/OBSERVATIONS.md`** durante
 Entrada: texto livre com a observação (restrição, descoberta técnica, preferência, risco, decisão).
 </objective>
 
-<context>
+<context>
 - Pode ser chamado **a qualquer momento**: antes, durante ou após qualquer passo da trilha OXE.
 - Não interrompe o fluxo em curso — a observação é armazenada e incorporada na próxima oportunidade.
-- Se chamado **durante execute** (fase `executing` no STATE) com impacto `execute` ou `all`: oferecer opção de aplicar agora (pausar onda atual) ou continuar e aplicar na próxima rodada.
-- Ler **`.oxe/STATE.md`** para capturar o contexto automático (fase atual, tarefa ativa, workstream ativo).
-- Resolver `active_session` conforme `oxe/workflows/references/session-path-resolution.md`. Com sessão ativa, `OBSERVATIONS.md` vive em `.oxe/<active_session>/execution/`; sem sessão ativa, manter `.oxe/`.
-- Usar `oxe/templates/OBSERVATIONS.template.md` para criar o arquivo se ainda não existir.
-</context>
+- Se chamado **durante execute** (fase `executing` no STATE) com impacto `execute` ou `all`: classificar a severidade e responder adaptativamente — `blocking` interrompe a onda e requer resolução explícita; `adjustment` incorpora como restrição na onda atual sem bloquear; `info` aplica na próxima oportunidade.
+- Ler **`.oxe/STATE.md`** para capturar o contexto automático (fase atual, tarefa ativa, workstream ativo).
+- Resolver `active_session` conforme `oxe/workflows/references/session-path-resolution.md`. Com sessão ativa, `OBSERVATIONS.md` vive em `.oxe/<active_session>/execution/`; sem sessão ativa, manter `.oxe/`.
+- Usar `oxe/templates/OBSERVATIONS.template.md` para criar o arquivo se ainda não existir.
+</context>
 
 <format_observations_md>
-Arquivo: **`OBSERVATIONS.md`** no escopo resolvido da sessão
+Arquivo: **`OBSERVATIONS.md`** no escopo resolvido da sessão
 
 ```markdown
 # Observações OXE
 
-| ID | Data | Contexto | Impacto | Status |
-|----|------|----------|---------|--------|
-| OBS-001 | 2026-04-04 | execute/T3 | spec, plan | pendente |
-| OBS-002 | 2026-04-04 | pós-spec | execute | incorporada → execute (2026-04-04) |
+| ID | Data | Contexto | Impacto | Severidade | Status |
+|----|------|----------|---------|------------|--------|
+| OBS-001 | 2026-04-04 | execute/T3 | spec, plan | adjustment | pendente |
+| OBS-002 | 2026-04-04 | pós-spec | execute | info | incorporada → execute (2026-04-04) |
 
 ---
 
 ### OBS-001 — 2026-04-04 | execute/T3
 **Impacto:** spec, plan
+**Severidade:** adjustment
+**Tipo:** new_constraint
 **Afeta (spec):** R3, R5
 **Afeta (plan):** T4, T7
 **Status:** pendente
@@ -42,6 +44,7 @@ JWT expiration deve ser configurável via `JWT_EXPIRES_IN` env var, não hardcod
 
 ### OBS-002 — 2026-04-04 | pós-spec
 **Impacto:** execute
+**Severidade:** info
 **Status:** incorporada → execute (2026-04-04)
 
 API deve retornar mensagens de erro em português do Brasil.
@@ -65,27 +68,71 @@ Se ambíguo, usar `all` (princípio de maior abrangência).
 - `execute` — afeta a implementação da tarefa atual ou próxima
 - `all` — afeta múltiplas camadas
 
+**Severidade:** classificar automaticamente com base no conteúdo:
+
+| Texto menciona | Severidade |
+|----------------|------------|
+| Coverage %, threshold, CI falhou, pipeline, Actions, test failed, falha no build | `blocking` |
+| Erro técnico, exception, versão incompatível, dependência ausente, requisito incompatível | `blocking` |
+| "não pode", "proibido", "exige", novo requisito que afeta tarefas em andamento | `adjustment` |
+| Preferência, restrição técnica, descoberta que exige ajuste em tarefas existentes | `adjustment` |
+| Contexto adicional, observação informativa, descoberta sem impacto imediato | `info` |
+
+Se ambíguo entre `blocking` e `adjustment`, usar `blocking` (princípio de segurança).
+
+**Tipo:** classificar automaticamente (campo omitido quando nenhum padrão se aplica):
+
+| Texto menciona | Tipo |
+|----------------|------|
+| Coverage, threshold, Actions, CI, pipeline, test pass/fail, build falhou | `ci_failure` |
+| "não pode", "proibido", "exige", "requisito" | `new_constraint` |
+| Erro, exception, versão incompatível, dependência, module not found | `technical_blocker` |
+
+**CI-evidência** (somente quando `Tipo: ci_failure`): extrair e registrar na seção `### OBS-NNN`:
+```
+**CI-evidência:**
+  coverage_pct: 87
+  coverage_threshold: 90
+  failing_files: [src/auth.ts, src/utils.ts]
+  ci_run_url: https://github.com/...
+  failing_tests: [nome do teste]
+```
+Campos não encontrados no texto são omitidos. Esta evidência é consumida por `/oxe-verify` como fonte para critérios A* de qualidade.
+
 **Status lifecycle:** `pendente` → `incorporada → <workflow> (YYYY-MM-DD)`
 </format_observations_md>
 
 <process>
 1. Ler **`.oxe/STATE.md`**: capturar `phase`, `last_task` ou tarefa ativa na onda, `active_workstream`.
-2. Determinar o **próximo ID** (OBS-NNN): contar entradas existentes em `OBSERVATIONS.md` do escopo resolvido ou começar em OBS-001.
+2. Determinar o **próximo ID** (OBS-NNN): contar entradas existentes em `OBSERVATIONS.md` do escopo resolvido ou começar em OBS-001.
 3. Classificar o **impacto** automaticamente com base no texto; se ambíguo, usar `all`.
 3b. **Propagação automática de constraints:**
    - Se existir **`.oxe/SPEC.md`**: ler a tabela de requisitos (R-ID) e critérios (A*) e identificar quais são diretamente afetados pelo texto da observação. Registrar em `**Afeta (spec):**`.
    - Se existir **`.oxe/PLAN.md`**: ler as tarefas (Tn) e identificar quais podem precisar de ajuste no campo `Verificar` ou `Implementar`. Registrar em `**Afeta (plan):**`.
    - Se nenhum R-ID ou Tn identificável: registrar `**Afeta:** (a cruzar na próxima incorporação)`.
    - Esta propagação é automática e não requer input do usuário.
-4. Criar ou atualizar **`OBSERVATIONS.md`** no escopo resolvido:
+3c. Classificar a **severidade** automaticamente usando a tabela de `<format_observations_md>`. Registrar como campo `**Severidade:**` na seção `### OBS-NNN` e na coluna da tabela de índice. Se ambíguo entre `blocking` e `adjustment`, usar `blocking`.
+3d. Classificar o **tipo** automaticamente (se identificável). Se `Tipo: ci_failure`, extrair evidências estruturadas do texto (`coverage_pct`, `coverage_threshold`, `failing_files`, `ci_run_url`, `failing_tests`) e registrar como `**CI-evidência:**` na seção `### OBS-NNN`. Omitir campos não encontrados.
+4. Criar ou atualizar **`OBSERVATIONS.md`** no escopo resolvido:
    - Adicionar linha na tabela de índice.
    - Adicionar seção `### OBS-NNN` com contexto, impacto, status e texto.
-5. Avaliar **urgência**:
+5. Avaliar **urgência** e responder adaptativamente:
    - Se `phase` ∈ `{ executing, quick_active }` **e** impacto ∈ `{ execute, all }`:
-     - Apresentar ao usuário: "Observação registrada. Deseja aplicar agora (pausar onda atual) ou continuar e incorporar na próxima rodada?"
-     - Se pausar: sugerir revisão do bloco `**Verificar:**` da tarefa ativa e ajuste inline.
-     - Se continuar: confirmar que será incorporado no início da próxima onda.
-   - Em qualquer outro caso: confirmar registro e mencionar quando será incorporado.
+     - **Se `Severidade: blocking`:**
+       1. Identificar tarefas do PLAN que tocam os arquivos/áreas afetados (campo `**Afeta (plan):**`)
+       2. Propor micro-ajustes alinhados ao plano: sub-tarefas dentro das tarefas existentes — não adicionar escopo novo
+       3. Apresentar três opções ao usuário:
+          - **A) Ajuste inline:** adicionar sub-tarefas à tarefa atual e retomar execução imediatamente
+          - **B) Micro-replan:** pausar onda, atualizar PLAN.md com as sub-tarefas, retomar após confirmação
+          - **C) Registrar apenas:** incorporar na próxima rodada sem interromper a onda atual
+       4. Seja qual opção for escolhida: se `ACTIVE-RUN.json` existir, registrar `blocker_info: { obs_id, severity, type, affected_tasks }` e emitir evento em `OXE-EVENTS.ndjson` (tipo `obs_blocking`)
+     - **Se `Severidade: adjustment`:**
+       - Apresentar ao usuário: "Observação registrada (ajuste). Incorporar na onda atual ou na próxima?"
+       - Se onda atual: incorporar imediatamente nas tarefas afetadas como restrição ou nota de implementação
+       - Se próxima onda: confirmar que será incorporado automaticamente no início da próxima onda
+     - **Se `Severidade: info`** (ou sem campo Severidade):
+       - Confirmar registro; mencionar que será incorporado quando o workflow relevante for chamado
+   - Em qualquer outro caso (fora de executing/quick_active): confirmar registro e mencionar quando será incorporado.
 6. Atualizar **`.oxe/STATE.md`**: adicionar ou atualizar campo `obs_pendentes: true` (remover ou marcar `false` quando todos os OBS estiverem `incorporada`).
 7. Responder no chat com: ID atribuído (OBS-NNN), impacto classificado, próximo passo sugerido (qual workflow incorporará a observação).
 </process>
@@ -107,7 +154,10 @@ Qualquer workflow que leia `.oxe/OBSERVATIONS.md` deve:
 <success_criteria>
 - [ ] `.oxe/OBSERVATIONS.md` existe com entrada OBS-NNN na tabela e seção de detalhe.
 - [ ] Impacto classificado corretamente (spec | plan | execute | all).
+- [ ] Severidade classificada corretamente (info | adjustment | blocking); campo presente na tabela e na seção `### OBS-NNN`.
+- [ ] Tipo detectado e registrado quando padrão identificável; `CI-evidência` extraída se `Tipo: ci_failure`.
 - [ ] `STATE.md` tem `obs_pendentes: true`.
-- [ ] Se urgência execute: usuário foi consultado sobre pausar ou continuar.
-- [ ] Resposta no chat inclui ID, impacto e próximo passo de incorporação.
+- [ ] Se `Severidade: blocking` durante executing: opções A/B/C apresentadas ao usuário; `ACTIVE-RUN.json` atualizado com `blocker_info` se existir.
+- [ ] Se `Severidade: adjustment` durante executing: usuário consultado sobre incorporar na onda atual ou na próxima.
+- [ ] Resposta no chat inclui ID, impacto, severidade e próximo passo de incorporação.
 </success_criteria>

package/oxe/workflows/plan-agent.md

@@ -3,7 +3,7 @@
 <objective>
 Produzir **dois artefactos alinhados**:
 
-1. **`.oxe/PLAN.md`** — mesmo contrato que o workflow **`plan.md`** (tarefas `Tn`, **Onda**, **Depende de**, **Verificar**, **Aceite vinculado**), para **`/oxe-execute`**, **`/oxe-verify`** e gates OXE existentes.
+1. **`.oxe/PLAN.md`** — mesmo contrato que o workflow **`plan.md`** (tarefas `Tn`, **Onda**, **Depende de**, **Verificar**, **Aceite vinculado**, **Autoavaliação do Plano** com rubrica e confiança determinística), para **`/oxe-execute`**, **`/oxe-verify`** e gates OXE existentes.
 2. **`.oxe/plan-agents.json`** — **blueprint de execução**: objetivo, **agentes** (papéis, âmbito, entradas/saídas esperadas, dependências entre agentes), **estratégia em ondas** (`execution.waves`), **`runId`** e **`lifecycle`** (schema **2**).
 
 O plano **não** é só uma lista de tarefas: cada agente é um **pacote de contexto** (o que ler, o que produzir, que `Tn` cobre). A execução real continua a ser feita pelo utilizador ou por subagentes da IDE, guiados por este blueprint e pelo `PLAN.md`.
@@ -15,6 +15,7 @@ Se o utilizador pedir **`--replan`**: aplicar a mesma lógica de replanejamento
 
 <context>
 - Resolver `active_session` conforme `oxe/workflows/references/session-path-resolution.md`. Com sessão ativa, `PLAN.md`, `plan-agents.json` e `plan-agent-messages/` vivem em `.oxe/<active_session>/plan/`; sem sessão ativa, manter `.oxe/`.
+- O `plan-agent` herda integralmente o contrato `oxe/workflows/references/flow-robustness-contract.md`. Não pode emitir percentuais concorrentes por agente; a confiança final do plano é única e visível no `PLAN.md`.
 - **Pré-requisitos** iguais a **`plan.md`**: `.oxe/SPEC.md` obrigatória; `discuss_before_plan` + `DISCUSS.md` quando configurado; consumir **NOTES**, **UI-SPEC**, **DISCUSS**, **RESEARCH**, **CODEBASE-DELTA** / **RESUME**, **config.json** (`plan_max_tasks_per_wave`, `default_verify_command`) como em **`plan.md`**.
 - **Fonte de verdade das tarefas:** `PLAN.md`. O JSON referencia tarefas via **`taskIds`** em cada agente — **não** duplicar o texto de **Verificar** no JSON; copiar só paths/resumo curto em **`outputs`** quando útil para routing.
 - **Agentes ≠ ferramentas externas fixas:** `role` e `scope` descrevem o **comportamento esperado** de um contexto focado (ex.: “Backend Auth Specialist”), não um binário. Quem executa pode ser um único modelo com instruções diferentes por onda.

package/oxe/workflows/plan.md

@@ -3,25 +3,28 @@
 <objective>
 Produzir **`.oxe/PLAN.md`**: tarefas **pequenas**, **ondas** (paralelizáveis vs sequenciais), e **cada tarefa com bloco de verificação** (comando de teste e/ou checklist manual).
 
-Base: `SPEC.md` do escopo resolvido da sessão (critérios com IDs **A1**, **A2**, …) + `.oxe/codebase/*` + código quando necessário (Grep/Read pontual).
+Base: `SPEC.md` do escopo resolvido da sessão (critérios com IDs **A1**, **A2**, …) + `.oxe/codebase/*` + código quando necessário (Grep/Read pontual).
 
 Se o usuário pedir **--replan** (ou replanejamento implícito após `verify_failed`):
-- Ler `VERIFY.md` e `SUMMARY.md` do escopo resolvido, e o `PLAN.md` atual.
+- Ler `VERIFY.md` e `SUMMARY.md` do escopo resolvido, e o `PLAN.md` atual.
 - Preservar tarefas já concluídas ou renumerar com nota em **Replanejamento**; não apagar histórico útil — deslocar para a seção **Replanejamento** e reescrever **Tarefas** conforme necessário.
 - Se **SUMMARY.md** não existir, criar a partir de `oxe/templates/SUMMARY.template.md` para registrar o contexto do replan (ou dar append se já existir).
 </objective>
 
-<context>
-- Resolver `active_session` conforme `oxe/workflows/references/session-path-resolution.md`. Com sessão ativa, o plano vive em `.oxe/<active_session>/plan/` e lê a spec em `.oxe/<active_session>/spec/`.
-- Se existir `OBSERVATIONS.md` do escopo resolvido com entradas `pendente` de impacto `plan` ou `all`, incorporar nas tarefas relevantes antes de finalizar o plano (ajustar implementação, verificação ou escopo de Tn) e marcar essas entradas como `incorporada → plan (data)`.
-- Se existir **`.oxe/global/LESSONS.md`**, ler entradas com `Aplicar em: /oxe-plan` e `Status: ativo`. Aplicar como restrições explícitas no planejamento: ajuste de complexidade de tarefas, padrões de verificação, escolha de modo solo vs agentes. Registrar aplicações como comentário no PLAN.md: `<!-- lição C-NN aplicada: ... -->`.
+<context>
+- Seguir `oxe/workflows/references/flow-robustness-contract.md` como contrato canónico de robustez. A ordem obrigatória é: ler artefatos, resolver sessão/paths, validar pré-condições, escrever o plano, autoavaliar o plano, registrar próximo passo único.
+- Resolver `active_session` conforme `oxe/workflows/references/session-path-resolution.md`. Com sessão ativa, o plano vive em `.oxe/<active_session>/plan/` e lê a spec em `.oxe/<active_session>/spec/`.
+- Quando existirem, ler `INVESTIGATIONS.md`, `RESEARCH.md`, `CAPABILITIES.md`, `memory/` do projeto e `CHECKPOINTS.md` para calibrar dependências, riscos, automações disponíveis e gates humanos necessários.
+- Se a SPEC ou artefatos do projeto mencionarem **Azure explicitamente** (Azure Service Bus, Azure SQL, Azure Event Grid, az CLI, ARM, subscription Azure, ou `.oxe/cloud/azure/` existir no projeto), **antes de detalhar tarefas**: (1) verificar `auth-status.json` — se `login_active: false` ou `subscription_id` ausente, registrar como **pré-condição bloqueante** no PLAN.md e sugerir `oxe-cc azure status` / `oxe-cc azure auth login`; (2) verificar staleness do inventário via `inventory.synced_at` — se stale além de `inventory_max_age_hours`, sugerir `oxe-cc azure sync` antes de executar; (3) se `vpn_required: true` no config, registrar como restrição explícita nas tarefas de mutação Azure. O plano deve vincular tarefas a recursos existentes em INVENTORY.md, SERVICEBUS.md, EVENTGRID.md ou SQL.md, ou declarar explicitamente os recursos Azure a criar com `oxe-cc azure <domínio> plan`. **SQL genérico, bancos on-prem ou outras nuvens não acionam este bloco.**
+- Se existir `OBSERVATIONS.md` do escopo resolvido com entradas `pendente` de impacto `plan` ou `all`, incorporar nas tarefas relevantes antes de finalizar o plano (ajustar implementação, verificação ou escopo de Tn) e marcar essas entradas como `incorporada → plan (data)`.
+- Se existir **`.oxe/global/LESSONS.md`**, ler entradas com `Aplicar em: /oxe-plan` e `Status: ativo`. **Priorizar entradas com `Frequência >= 2` ou `Impacto: alto`** — aplicar como restrições explícitas no planejamento: ajuste de complexidade de tarefas, padrões de verificação, escolha de modo solo vs agentes. Lições com `Frequência: 1` e `Impacto: baixo` são contexto secundário. Registrar aplicações como comentário no PLAN.md: `<!-- lição C-NN aplicada: ... -->`.
 - **LESSONS + OBS juntos:** se houver tanto LESSONS quanto OBS pendentes, LESSONS orientam o *como planejar* e OBS orientam o *o que incluir*. Não confundir os papéis.
 - Não inventar APIs inexistentes: cruzar com **STRUCTURE.md**, **INTEGRATIONS.md** e arquivos reais; respeitar **CONCERNS.md** (evitar agravar dívida conhecida sem tarefa explícita).
-- Se existir **`.oxe/NOTES.md`**, rever entradas em aberto: incorporar em tarefas (com **Aceite vinculado** quando aplicável) ou registar na secção **Replanejamento** / nota explícita *fora de âmbito desta trilha*.
-- Se existir `UI-SPEC.md` no escopo resolvido, as tarefas de UI devem referenciar secções do UI-SPEC no texto de **Implementação** ou **Verificar**.
-- Se existir `DISCUSS.md` no escopo resolvido, alinhar tarefas às decisões registradas. Referenciar IDs **D-NN** no campo **Decisão vinculada:** de cada tarefa impactada — se nenhuma decisão impactar a tarefa, omitir o campo. A rastreabilidade D-NN → Tn → verify é usada pela seção **Fidelidade de decisões** do verify.
-- Se existir `RESEARCH.md` e notas em `research/*.md` do escopo resolvido, ler o índice e as notas cujo **Tema** cruza o âmbito do plano (ou as mais recentes relevantes). Se o índice marcar **Estado** pendente em tópico bloqueante, pedir nova sessão **research** ou **discuss**, ou registar **suposição explícita** no PLAN antes de ondas que dependam dessa decisão.
-- Se existir `plan-agents.json` no escopo resolvido (gerado por **`/oxe-plan-agent`**), um **--replan** ou renumerar tarefas deve **atualizar o JSON em conjunto** com o `PLAN.md` (cobertura `taskIds`, ondas e dependências entre agentes) — ver **`oxe/workflows/plan-agent.md`**. Preferir **`/oxe-plan-agent --replan`** para regerar **`runId`**, **`lifecycle`** (`pending_execute`) e alinhar **STATE.md**; se só **`/oxe-plan`** for usado, ou o JSON fica manualmente sincronizado, ou marcar no JSON `lifecycle.invalidatedBy: new_plan` até novo plan-agent.
+- Se existir **`.oxe/NOTES.md`**, rever entradas em aberto: incorporar em tarefas (com **Aceite vinculado** quando aplicável) ou registar na secção **Replanejamento** / nota explícita *fora de âmbito desta trilha*. Se não existir e houver necessidade de registrar notas, criar a partir de `oxe/templates/NOTES.template.md`.
+- Se existir `UI-SPEC.md` no escopo resolvido, as tarefas de UI devem referenciar secções do UI-SPEC no texto de **Implementação** ou **Verificar**.
+- Se existir `DISCUSS.md` no escopo resolvido, alinhar tarefas às decisões registradas. Referenciar IDs **D-NN** no campo **Decisão vinculada:** de cada tarefa impactada — se nenhuma decisão impactar a tarefa, omitir o campo. A rastreabilidade D-NN → Tn → verify é usada pela seção **Fidelidade de decisões** do verify.
+- Se existir `RESEARCH.md` e notas em `research/*.md` do escopo resolvido, ler o índice e as notas cujo **Tema** cruza o âmbito do plano (ou as mais recentes relevantes). Se o índice marcar **Estado** pendente em tópico bloqueante, pedir nova sessão **research** ou **discuss**, ou registar **suposição explícita** no PLAN antes de ondas que dependam dessa decisão.
+- Se existir `plan-agents.json` no escopo resolvido (gerado por **`/oxe-plan-agent`**), um **--replan** ou renumerar tarefas deve **atualizar o JSON em conjunto** com o `PLAN.md` (cobertura `taskIds`, ondas e dependências entre agentes) — ver **`oxe/workflows/plan-agent.md`**. Preferir **`/oxe-plan-agent --replan`** para regerar **`runId`**, **`lifecycle`** (`pending_execute`) e alinhar **STATE.md**; se só **`/oxe-plan`** for usado, ou o JSON fica manualmente sincronizado, ou marcar no JSON `lifecycle.invalidatedBy: new_plan` até novo plan-agent.
 - Se existirem **`.oxe/CODEBASE-DELTA.md`** e/ou **`.oxe/RESUME.md`** (tipicamente após **`/oxe-compact`**), ler **antes** de detalhar tarefas: o delta resume o que mudou nos mapas face ao código; o RESUME ancora fase e trilha OXE — **não** substituem SPEC nem os sete ficheiros em `codebase/`.
 - Se existir **`.oxe/config.json`** com `default_verify_command` não vazio, usar como fallback quando a SPEC não indicar comando.
 - Se existir **`plan_max_tasks_per_wave` > 0** na config, **não** colocar mais tarefas do que esse número na mesma **Onda**; dividir em mais ondas.
@@ -47,6 +50,45 @@ Cada tarefa em PLAN.md deve seguir a ordem abaixo — **Verificar vem ANTES de I
 <!-- oxe-task: {"id":"Tn","wave":1,"type":"feature","files":[],"done":false,"complexity":"S"} -->
 ```
 
+Depois do resumo e antes das tarefas, o `PLAN.md` deve conter também:
+
+```markdown
+## Autoavaliação do Plano
+- **Melhor plano atual:** sim | não
+- **Confiança:** 0–100%
+- **Base da confiança:**
+  - Completude dos requisitos: NN/25
+  - Dependências conhecidas: NN/15
+  - Risco técnico: NN/20
+  - Impacto no código existente: NN/15
+  - Clareza da validação / testes: NN/15
+  - Lacunas externas / decisões pendentes: NN/10
+- **Principais incertezas:** ...
+- **Alternativas descartadas:** ...
+- **Condição para replanejar:** ...
+```
+
+**Rubrica fixa de confiança (determinística):**
+| Dimensão | Peso |
+|----------|------|
+| Completude dos requisitos | 25 |
+| Dependências conhecidas | 15 |
+| Risco técnico | 20 |
+| Impacto no código existente | 15 |
+| Clareza da validação / testes | 15 |
+| Lacunas externas / decisões pendentes | 10 |
+
+**Faixas semânticas obrigatórias:**
+- `85–100%` → pronto para executar
+- `70–84%` → executável com risco controlado
+- `50–69%` → precisa refino antes de execução
+- `<50%` → não executar
+
+**Entradas obrigatórias da confiança:**
+- usar as incertezas estruturadas da SPEC e as investigações concluídas como base direta da rubrica;
+- se o plano depender de capability nativa, investigação ainda não feita ou checkpoint humano antes de side effect crítico, isso deve aparecer explicitamente em tarefas, riscos e autoavaliação.
+- se o plano depender de mutação Azure, incluir checkpoint formal antes de `apply`, mencionar a capability Azure correspondente e ligar a evidência esperada em `.oxe/cloud/azure/operations/`.
+
 **Escala de Complexidade:**
 | Valor | Esforço estimado | Sinal de alerta |
 |-------|-----------------|-----------------|
@@ -67,13 +109,18 @@ Antes de finalizar a resposta ao utilizador, o agente **deve** percorrer este ga
 
 1. **Depende de:** em cada `### Tn`, apenas IDs `Tk` que existem no mesmo ficheiro, ou `—`.
 2. **Ciclos:** não há cadeia circular óbvia (ex.: T2→T3→T2); se houver, quebrar dependência ou onda.
-3. **Cobertura A*:** todos os IDs da tabela de critérios em `SPEC.md` do escopo resolvido aparecem em **Aceite vinculado:** de alguma tarefa, ou há nota explícita de **gap** no PLAN (fora de âmbito / adiado) por ID.
+3. **Cobertura A*:** todos os IDs da tabela de critérios em `SPEC.md` do escopo resolvido aparecem em **Aceite vinculado:** de alguma tarefa, ou há nota explícita de **gap** no PLAN (fora de âmbito / adiado) por ID.
 4. **Ondas:** cada número de **Onda:** usado tem pelo menos uma tarefa; sem ondas vazias.
 5. **`plan_max_tasks_per_wave`:** se `.oxe/config.json` tiver valor **> 0**, contar tarefas por **Onda**; nenhuma onda excede o limite.
-6. **UI-SPEC:** se existir `UI-SPEC.md` no escopo resolvido, toda tarefa cuja **Implementar** ou **Verificar** toque UI deve citar **secção § do UI-SPEC** ou path explícito.
-7. **Fidelidade de decisões:** se existir `DISCUSS.md` com IDs **D-NN** no escopo resolvido, cada decisão com impacto técnico deve aparecer em **Decisão vinculada:** de alguma tarefa, ou ter nota explícita de gap. Sem cobertura para D-NN técnico = falha do gate.
+6. **UI-SPEC:** se existir `UI-SPEC.md` no escopo resolvido, toda tarefa cuja **Implementar** ou **Verificar** toque UI deve citar **secção § do UI-SPEC** ou path explícito.
+7. **Fidelidade de decisões:** se existir `DISCUSS.md` com IDs **D-NN** no escopo resolvido, cada decisão com impacto técnico deve aparecer em **Decisão vinculada:** de alguma tarefa, ou ter nota explícita de gap. Sem cobertura para D-NN técnico = falha do gate.
 8. **Complexidade XL:** toda tarefa com `Complexidade: XL` deve ter sub-tarefas explícitas (ex.: T3.1, T3.2 — como bullets dentro da tarefa) **ou** justificativa na tarefa explicando por que não pode ser quebrada. Tarefa XL sem sub-tarefas e sem justificativa = falha do gate.
 9. **Test-first:** em toda tarefa, `Verificar` deve preceder `Implementar` no texto. Se a ordem estiver invertida, corrigir antes de finalizar.
+10. **Autoavaliação presente:** o `PLAN.md` contém `## Autoavaliação do Plano`, `Melhor plano atual`, `Confiança`, rubrica completa e `Condição para replanejar`.
+11. **Calibração de execução:** se `Melhor plano atual: não` ou `Confiança < limiar configurado`, o plano não pode recomendar execução direta; deve recomendar refino, discuss ou research.
+12. **Rastreabilidade de evidência:** cada tarefa deve ter entrada observável de origem na SPEC, no codebase, em DISCUSS, OBS, RESEARCH ou LESSONS; tarefa sem evidência de entrada explícita = falha do gate.
+13. **Mudanças de risco:** tarefas com risco relevante (migração, auth, schema, contrato público, segurança) devem incluir contenção, rollback, fallback ou verificação reforçada.
+14. **Cobertura R-ID:** se `SPEC.md` contiver tabela de requisitos com IDs `R-NN` e status `v1`/`v2`, cada R-ID em escopo deve ter ao menos um critério A* mapeado em **Aceite vinculado:** de alguma tarefa — rastrear `R-NN → A* → Tn`. R-IDs com `v1`/`v2` sem nenhuma tarefa associada = falha do gate; documentar como gap explícito quando intencional (ex.: `<!-- R-03: adiado para próximo ciclo -->`).
 
 Se após correções estruturais persistir ambiguidade de produto: **uma** frase recomendando `oxe:discuss` ou `oxe:spec`.
 
@@ -81,20 +128,22 @@ Resumo obrigatório no chat: `Gate do plano: OK` ou `Gate do plano: corrigido (N
 </plan_quality_gate>
 
 <process>
-1. Resolver `active_session` e ler `SPEC.md` do escopo correto (obrigatório). Se faltar, pedir **spec** primeiro.
-2. Se `.oxe/config.json` tiver `discuss_before_plan: true` e **não** existir `DISCUSS.md` no escopo resolvido com decisões fechadas, pedir **discuss** antes de planejar.
+1. Resolver `active_session` e ler `SPEC.md` do escopo correto (obrigatório). Se faltar, pedir **spec** primeiro.
+2. Se `.oxe/config.json` tiver `discuss_before_plan: true` e **não** existir `DISCUSS.md` no escopo resolvido com decisões fechadas, pedir **discuss** antes de planejar.
 3. Se existir **`.oxe/NOTES.md`**, consumir ou explicitamente adiar cada bullet relevante (ver **context**).
 4. Ler `.oxe/codebase/*.md` (incl. CONVENTIONS / CONCERNS) e inspecionar pontos de entrada se a spec exigir.
-5. Escrever ou atualizar `PLAN.md` no escopo resolvido usando `oxe/templates/PLAN.template.md` como cabeçalho; **preservar** YAML inicial (`oxe_doc: plan`, `status`, `inputs`) se já existir e **atualizar** `updated:` (ISO); em **--replan**, preencher a seção **Replanejamento** (data, motivo, lições de VERIFY/SUMMARY, tarefas removidas/alteradas).
+5. Escrever ou atualizar `PLAN.md` no escopo resolvido usando `oxe/templates/PLAN.template.md` como cabeçalho; **preservar** YAML inicial (`oxe_doc: plan`, `status`, `inputs`) se já existir e **atualizar** `updated:` (ISO); em **--replan**, preencher a seção **Replanejamento** (data, motivo, lições de VERIFY/SUMMARY, tarefas removidas/alteradas).
 6. Definir ondas: onda 1 = tarefas sem dependência entre si; onda seguinte = dependentes; respeitar `plan_max_tasks_per_wave` se configurado.
-7. Aplicar integralmente o bloco **`<plan_quality_gate>`** acima ao `PLAN.md` em disco; corrigir o ficheiro até passar ou documentar gaps explícitos.
-8. Atualizar `.oxe/STATE.md` global: fase `plan_ready`, próximo passo `oxe:execute` (implementar ondas) e depois `oxe:verify`.
-9. **Sugestão de agentes (inteligente):** após o gate passar, verificar se o plano tem 3+ domínios distintos (ex.: backend + frontend + DB, ou auth + notificações + UI). Se sim, sugerir proativamente: "Este plano tem N domínios distintos. Quer gerar um blueprint de agentes com `/oxe-plan --agents`?" — não executar automaticamente, apenas oferecer. Se o usuário incluiu `--agents` no input original, executar imediatamente a lógica de `oxe/workflows/plan-agent.md`.
-10. Listar no chat: resultado do gate (OK ou corrigido), ondas, contagem de tarefas, comando de teste guarda-chuva se houver.
+7. Preencher `## Autoavaliação do Plano` com a rubrica fixa. A confiança é a soma ponderada das seis dimensões; não inventar percentagem sem justificar os pontos.
+8. Aplicar integralmente o bloco **`<plan_quality_gate>`** acima ao `PLAN.md` em disco; corrigir o ficheiro até passar ou documentar gaps explícitos.
+9. Atualizar `.oxe/STATE.md` global: fase `plan_ready`, próximo passo `oxe:execute` apenas se `Melhor plano atual: sim` e a confiança estiver no limiar executável; caso contrário, próximo passo deve reduzir incerteza (`oxe:discuss`, `oxe:research` ou replanejamento).
+10. **Sugestão de agentes (inteligente):** após o gate passar, verificar se o plano tem 3+ domínios distintos (ex.: backend + frontend + DB, ou auth + notificações + UI). Se sim, sugerir proativamente: "Este plano tem N domínios distintos. Quer gerar um blueprint de agentes com `/oxe-plan --agents`?" — não executar automaticamente, apenas oferecer. Se o usuário incluiu `--agents` no input original, executar imediatamente a lógica de `oxe/workflows/plan-agent.md`.
+11. Listar no chat: resultado do gate (OK ou corrigido), ondas, contagem de tarefas, comando de teste guarda-chuva se houver, melhor-plano-atual e confiança.
 </process>
 
 <success_criteria>
 - [ ] Cada tarefa tem seção **Verificar** com comando ou checklist explícito.
 - [ ] Dependências entre tarefas estão explícitas.
 - [ ] Cada critério da SPEC (IDs **A***) está mapeado em **Aceite vinculado** de alguma tarefa ou explicitamente marcado como gap no plano.
+- [ ] Cada R-ID `v1`/`v2` do SPEC tem ao menos um A* coberto por alguma tarefa, ou gap documentado (gate 14).
 </success_criteria>

package/oxe/workflows/quick.md

@@ -8,9 +8,10 @@ Quando o trabalho envolve **2 ou mais domínios distintos** (ex.: backend + fron
 Usar quando: correção pontual, refactor local, feature pequena ou protótipo que **não** justifica critérios de aceite completos.
 </objective>
 
-<context>
-- Resolver `active_session` conforme `oxe/workflows/references/session-path-resolution.md`. Com sessão ativa, `QUICK.md` e `quick-agents.json` vivem em `.oxe/<active_session>/plan/`; sem sessão ativa, manter `.oxe/`.
-- Ler `.oxe/STATE.md` e, se existirem, `OVERVIEW.md` e `STACK.md` em `.oxe/codebase/` para não contradizer o repo.
+<context>
+- Seguir `oxe/workflows/references/flow-robustness-contract.md`. Quick continua leve, mas não pode fingir que existe plano formal quando ele não existe.
+- Resolver `active_session` conforme `oxe/workflows/references/session-path-resolution.md`. Com sessão ativa, `QUICK.md` e `quick-agents.json` vivem em `.oxe/<active_session>/plan/`; sem sessão ativa, manter `.oxe/`.
+- Ler `.oxe/STATE.md` e, se existirem, `OVERVIEW.md` e `STACK.md` em `.oxe/codebase/` para não contradizer o repo.
 - Não apagar `SPEC.md` / `PLAN.md` se existirem; este fluxo é paralelo ou temporário.
 - **Blueprint plan-agent:** este fluxo **não** reutiliza papéis (`role` / `scope`) de **`.oxe/plan-agents.json`**. Se existir `plan-agents.json` com **`oxePlanAgentsSchema: 2`** e `lifecycle.status` **não** for já `invalidated`, **invalidar** o blueprint após criar/substituir **`QUICK.md`**: `lifecycle: { "status": "invalidated", "since": "<ISO>", "invalidatedBy": "quick", "invalidatedReason": "oxe-quick substitui trilha focada do blueprint" }`. Actualizar **`.oxe/STATE.md`** — secção **Blueprint de agentes (sessão)**: **lifecycle_status** → `invalidated`, nota "invalidado por quick". Não escrever novas mensagens em **`.oxe/plan-agent-messages/`** para o `runId` invalidado.
 - **Quick-agents anterior:** se existir **`.oxe/quick-agents.json`** com `status` diferente de `done` ou `invalidated`, invalidá-lo antes de criar o novo (`status: "invalidated", "since": "<ISO>", "reason": "novo quick iniciado"`).
@@ -121,6 +122,7 @@ Uso **sem** novo slash: é o mesmo `/oxe-quick` com redação mínima.
 - **Verificar** — um comando de terminal **ou** checklist manual explícito.
 - **Agentes dinâmicos** — seção opcional quando PDDA estiver ativo (ver acima).
 - **Promover para spec/plan?** — preencher sempre; se qualquer gatilho abaixo for verdadeiro, resposta **sim** e parar de acumular trabalho no QUICK — passar a **`/oxe-spec`** (e depois discuss/plan conforme config).
+- **Confiança formal do plano:** se ainda não houver `PLAN.md`, declarar explicitamente no QUICK que **não houve plano formal**; não inventar percentagem de confiança aqui.
 
 O perfil fast **não** é uma segunda trilha: continua sujeito à mesma promoção obrigatória quando o trabalho deixa de ser trivial.
 
@@ -141,16 +143,19 @@ No final de **`.oxe/QUICK.md`**, mantenha a linha:
 Se **sim**, o próximo passo recomendado no chat é **`/oxe-spec`** (depois discuss/plan conforme config).
 
 <process>
-1. Garantir `.oxe/` (usar template de STATE só se `STATE.md` não existir). Verificar `OBSERVATIONS.md` do escopo resolvido — se houver entradas `pendente` com impacto `all`, registrar como restrições nos **Passos** ou no **Contexto** do QUICK.md antes de finalizar; marcar as OBS como `incorporada → quick (data)`.
+0. **Git safety check (pré-execução):** antes de criar ou substituir QUICK.md, verificar `git status` do projeto (se `.git` existir). Se houver mudanças não commitadas **não relacionadas** ao objetivo deste quick, alertar: *"Existem mudanças não commitadas. Quer commitar antes de começar este quick?"* — não bloquear a execução, apenas perguntar. Prosseguir se o usuário confirmar ou se não houver git.
+1. Garantir `.oxe/` (usar template de STATE só se `STATE.md` não existir). Verificar `OBSERVATIONS.md` do escopo resolvido — se houver entradas `pendente` com impacto `all`, registrar como restrições nos **Passos** ou no **Contexto** do QUICK.md antes de finalizar; marcar as OBS como `incorporada → quick (data)`.
 2. Avaliar se PDDA lean se aplica (ver `<plan_driven_dynamic_agents_lean>` — domínios distintos, 5+ passos, ou flag `--agents`).
-3. Criar ou substituir **`QUICK.md`** no escopo resolvido com:
+3. Criar ou substituir **`QUICK.md`** no escopo resolvido com:
    - **Objetivo** — uma frase. *(Esta é a minispec: restringe o escopo de todos os agentes e passos.)*
    - **Contexto** — 2–5 bullets (arquivos/pastas já vistos).
    - **Passos** — lista numerada, **máximo 10** passos acionáveis; se PDDA ativo, anotar `<!-- agente: id -->` em cada passo.
    - **Agentes dinâmicos** *(somente se PDDA ativo)* — tabela com ID, papel, steps, persona.
    - **Verificar** — pelo menos um: comando de terminal (ex.: `npm test`) **ou** checklist manual explícito. *(Este é o critério de aceite da minispec.)*
    - **Promover para spec/plan?** — conforme seção acima.
-4. Se PDDA ativo, criar **`quick-agents.json`** no escopo resolvido usando `oxe/templates/quick-agents.template.json`:
+   - **Plano formal existente?** — `não`; usar `sim` apenas se este quick estiver ancorado a um `PLAN.md` já aprovado no mesmo escopo.
+   - **Scope check (inline):** durante a implementação, ao fim de cada passo, verificar se algum critério de promoção foi atingido (>8 arquivos, contrato público, segurança, >10 passos). Se sim, pausar e apresentar: *"O escopo deste quick cresceu: [critério atingido]. Recomendar promoção para /oxe-spec. Continuar mesmo assim?"*
+4. Se PDDA ativo, criar **`quick-agents.json`** no escopo resolvido usando `oxe/templates/quick-agents.template.json`:
    - Gerar `quickId` novo (`quick-<YYYY-MM-DD>-<6hex>`).
    - `status: "active"`, `since: "<ISO agora>"`.
    - Preencher `agents[]` derivando de cada grupo de passos do QUICK.md.
@@ -158,12 +163,15 @@ Se **sim**, o próximo passo recomendado no chat é **`/oxe-spec`** (depois disc
 6. Se existir **`.oxe/quick-agents.json`** anterior com `status` não-terminal, invalidá-lo (ver **context**).
 7. Atualizar **`.oxe/STATE.md`**: fase `quick_active`, próximo passo `oxe:execute` ou implementação manual + `oxe:verify`; se PDDA ativo, registrar `quick_agents_status: active` e `quick_id: <quickId>`.
 8. Responder no chat com resumo em ≤10 linhas: objetivo, passos, agentes (se PDDA ativo), verificação; se promover = sim, destacar **`/oxe-spec`** como próximo passo lógico; se blueprint plan-agent foi invalidado, mencionar **`/oxe-plan-agent`** para novo roteiro.
+9. **Sugestão de commit (pós-verify bem-sucedido):** após o bloco **Verificar** passar, sugerir ao usuário: *"Quick concluído. Commitar? `git add -p && git commit -m 'quick: <objetivo em uma linha>'`"* — apenas sugerir, não executar automaticamente.
 </process>
 
 <success_criteria>
 - [ ] `.oxe/QUICK.md` existe com objetivo (minispec), passos (mini-plano) e bloco **Verificar** (critério de aceite).
 - [ ] `STATE.md` reflete fase `quick_active` e próximo passo coerente.
 - [ ] Fica explícito quando **promover** para spec/plan (regra acima + campo no arquivo).
+- [ ] Scope creep gate verificado ao fim de cada passo; se critério atingido, pausa apresentada ao usuário.
+- [ ] Após verify bem-sucedido, sugestão de commit apresentada (não executada automaticamente).
 - [ ] Se havia blueprint schema 2 activo, `plan-agents.json` e `STATE.md` reflectem **`invalidated`** por quick.
 - [ ] Se PDDA ativo: `quick-agents.json` existe com `status: active`, `quickId` único, agentes com `role` específico à demanda, `steps` alinhados aos passos do QUICK.md; seção `## Agentes dinâmicos` presente no QUICK.md.
 - [ ] Se PDDA ativo: máximo 3 agentes; se mais necessário, QUICK.md declara `Promover para spec/plan?: sim` com razão "necessita > 3 agentes".

package/oxe/workflows/references/adaptive-discovery.md

@@ -0,0 +1,27 @@
+# OXE — Descoberta Adaptativa
+
+<objective>
+Reduzir ambiguidade antes da escrita de `SPEC.md` e melhorar a qualidade do plano. Esta referência orienta `spec` e `ask`.
+</objective>
+
+## Regras
+
+- Classificar a demanda o mais cedo possível: `feature`, `bugfix`, `refactor`, `research`, `ops`, `mixed`.
+- Modular as perguntas pelo tipo de demanda e pelo risco.
+- Limitar rodadas; consolidar entendimento antes de escrever artefatos.
+- Registrar incertezas estruturadas, não apenas em texto solto.
+
+## Blocos mínimos
+
+- **Objetivo final**
+- **Impacto / público**
+- **Restrições técnicas**
+- **Riscos e casos extremos**
+- **Evidência faltante**
+
+## Saída esperada
+
+- resumo de entendimento;
+- demanda classificada;
+- incertezas remanescentes;
+- recomendação de próximo passo compatível com o risco.

package/oxe/workflows/references/flow-robustness-contract.md

@@ -0,0 +1,80 @@
+# OXE — Contrato de Robustez do Fluxo
+
+<objective>
+Definir um contrato canónico para reduzir alucinação estrutural no OXE. Este ficheiro é consumido por `spec`, `plan`, `quick`, `execute`, `verify`, `next`, `status` e `doctor`.
+</objective>
+
+## Ordem determinística do fluxo
+
+Todo passo OXE deve seguir esta ordem, sem saltar etapas:
+
+1. Ler os artefatos obrigatórios do estado atual.
+2. Resolver `active_session` e os paths do escopo.
+3. Validar pré-condições mínimas antes de prosseguir.
+4. Produzir a saída principal do passo.
+5. Executar autoavaliação ou gate de qualidade do próprio passo.
+6. Registrar um próximo passo único.
+
+## Invariantes mínimos
+
+Todo workflow deve declarar com clareza:
+
+- quais artefatos lê;
+- quais artefatos escreve;
+- quais invariantes valida antes de operar;
+- qual fallback legado é permitido quando não há sessão ativa.
+
+## Proibição de saltos sem evidência
+
+- `plan` não deve avançar sem `SPEC.md` válido.
+- `execute` não deve avançar sem `PLAN.md` ou `QUICK.md` válido no escopo resolvido.
+- `verify` não deve avançar sem evidência mínima de execução ou de artefatos resultantes.
+- `next` não deve sugerir um passo que viole os gates acima.
+
+## Contrato de autoavaliação do plano
+
+Todo `PLAN.md` deve conter uma seção visível `## Autoavaliação do Plano` com:
+
+- `Melhor plano atual:` `sim` ou `não`
+- `Confiança:` `0–100%`
+- `Base da confiança:` rubrica fixa, não narrativa livre
+- `Principais incertezas:` lista curta
+- `Alternativas descartadas:` resumo curto
+- `Condição para replanejar:` critério objetivo
+
+### Rubrica obrigatória
+
+| Dimensão | Peso |
+|----------|------|
+| Completude dos requisitos | 25 |
+| Dependências conhecidas | 15 |
+| Risco técnico | 20 |
+| Impacto no código existente | 15 |
+| Clareza da validação / testes | 15 |
+| Lacunas externas / decisões pendentes | 10 |
+
+**Total:** 100 pontos
+
+### Faixas semânticas
+
+- `85–100%` → pronto para executar
+- `70–84%` → executável com risco controlado
+- `50–69%` → precisa refino antes de execução
+- `<50%` → não executar
+
+## Calibração pós-execução
+
+`verify` deve comparar o resultado real com a autoavaliação do plano:
+
+- confiança alta + falha precoce = erro de calibração do plano;
+- confiança baixa + falha em risco previsto = autoavaliação aderente;
+- confiança alta + sucesso consistente = plano calibrado;
+- confiança baixa + sucesso amplo = plano conservador demais.
+
+## Uso por `status` e `doctor`
+
+`status` e `doctor` devem refletir a saúde lógica do fluxo com categorias determinísticas:
+
+- `healthy` — sem bloqueio lógico conhecido;
+- `warning` — fluxo operável, mas com gaps ou drift relevante;
+- `broken` — artefato crítico ausente, incoerência severa ou gate indispensável falhado.

package/oxe/workflows/research.md

@@ -6,16 +6,19 @@ Produzir **notas de pesquisa rastreáveis** em `research/YYYY-MM-DD-<slug>.md` d
 Não substitui **SPEC** nem **PLAN**; alimenta decisões que depois entram na SPEC ou no PLAN.
 </objective>
 
-<context>
+<context>
 - Resolver `active_session` conforme `oxe/workflows/references/session-path-resolution.md`. Com sessão ativa, research vive em `.oxe/<active_session>/research/`; sem sessão ativa, usar `.oxe/research/`.
+- Tratar pesquisa como **investigação estruturada**, não como nota solta. Cada investigação deve ter objetivo, fontes, modo, profundidade, conclusões e impacto na trilha.
 - **Uma sessão = um ficheiro novo** em `research/`; não sobrescrever notas antigas salvo correção explícita do utilizador.
 - Nome do ficheiro: **`YYYY-MM-DD-<slug-kebab>.md`** (data ISO do dia acordado na mensagem ou data atual; slug único, curto, ASCII preferível).
 - **Índice:** `RESEARCH.md` do mesmo escopo deve conter tabela **Histórico** (mais recente primeiro) com colunas: **Data** | **Ficheiro** (`research/...`) | **Tema / âmbito** | **Tipo** (ex.: spike, mapa-sistema, reversa, modernização, decisão) | **Estado** (decidido / pendente / parcial) | **Resumo** (uma linha). Opcional: bloco **Última sessão** no topo com link para a nota mais recente.
 - Preferir **`.oxe/SPEC.md`** existente; se o pedido for mapear/reverter **antes** de spec, criar a nota mesmo assim com **Contexto** a declarar ausência de SPEC e próximo passo `oxe:spec`.
 - **Progressive disclosure:** sistemas grandes → profundidade por área; várias sessões/notas datadas em vez de um único ficheiro enorme.
-- Template: **`oxe/templates/RESEARCH.template.md`**.
-- Segurança: não gravar segredos nem valores de variáveis de ambiente.
-</context>
+- Template: **`oxe/templates/RESEARCH.template.md`**.
+- Ler `INVESTIGATIONS.md` e investigações anteriores do escopo resolvido antes de abrir nova pesquisa sobre o mesmo assunto.
+- Ler `.oxe/CAPABILITIES.md` quando a investigação depender de capability local, script ou conector já existente.
+- Segurança: não gravar segredos nem valores de variáveis de ambiente.
+</context>
 
 <thinking_depth>
 ## Profundidade de Raciocínio
@@ -36,12 +39,13 @@ Anotar `thinking_depth: surface | standard | deep` no frontmatter da nota de pes
 <process>
 1. Garantir pastas `.oxe/` e `research/` do escopo resolvido.
 2. Escolher `YYYY-MM-DD-<slug>.md` único; se colisão, acrescentar sufixo ao slug (ex. `-b`).
-3. Criar a nota a partir de `RESEARCH.template.md`: preencher secções **base**; preencher secções de **reforço** ou marcar **N/A** com justificação curta quando o âmbito for sistema grande, reversa ou modernização.
+3. Criar a nota a partir de `RESEARCH.template.md`: preencher secções **base**; preencher secções de **reforço** ou marcar **N/A** com justificação curta quando o âmbito for sistema grande, reversa ou modernização.
 4. Se `RESEARCH.md` do escopo resolvido não existir, criá-lo com título `# OXE — Índice de pesquisa`, parágrafo introdutório, secção **Histórico** com cabeçalho de tabela e primeira linha.
 5. Se já existir, **atualizar** `RESEARCH.md` do escopo resolvido: nova linha no topo da tabela **Histórico** (mais recente primeiro); opcionalmente atualizar **Última sessão** com link para o ficheiro novo.
-6. Ler **`.oxe/SPEC.md`**, **`.oxe/codebase/*`** e código alvo (Glob/Grep/Read) conforme âmbito.
-7. Atualizar **`.oxe/STATE.md`**: nota de fase / próximo passo típico `oxe:plan`, ou `oxe:spec` se faltar contrato, ou `oxe:ui-spec` se o foco for UI antes do plano.
-8. Responder no chat em 5–10 linhas: caminho da nota nova, confirmação de atualização do índice, próximo passo OXE.
+6. Atualizar `INVESTIGATIONS.md` do escopo resolvido com objetivo, fontes, modo, profundidade, conclusão e impacto na trilha. Se não existir, criá-lo.
+7. Ler **`.oxe/SPEC.md`**, **`.oxe/codebase/*`** e código alvo (Glob/Grep/Read) conforme âmbito.
+8. Atualizar **`.oxe/STATE.md`**: nota de fase / próximo passo típico `oxe:plan`, ou `oxe:spec` se faltar contrato, ou `oxe:ui-spec` se o foco for UI antes do plano.
+9. Responder no chat em 5–10 linhas: caminho da nota nova, confirmação de atualização do índice, próximo passo OXE.
 </process>
 
 <success_criteria>