oxe-cc 0.6.5 → 0.6.6

package/oxe/templates/config.template.json

@@ -2,8 +2,9 @@
   "_comment": "OXE config — copie para .oxe/config.json no seu projeto. Remova esta linha.",
   "profile": "balanced",
   "discuss_before_plan": false,
-  "verification_depth": "standard",
-  "security_in_verify": false,
+  "verification_depth": "standard",
+  "plan_confidence_threshold": 70,
+  "security_in_verify": false,
   "after_verify_suggest_pr": true,
   "after_verify_draft_commit": true,
   "after_verify_suggest_uat": false,

package/oxe/workflows/ask.md

@@ -0,0 +1,62 @@
+# OXE — Workflow: ask
+
+<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>
+
+<context>
+- Resolver `active_session` via `oxe/workflows/references/session-path-resolution.md`.
+- Ler sempre `.oxe/STATE.md` global primeiro.
+- Com sessão ativa, priorizar artefatos em `.oxe/<active_session>/...` antes do modo legado.
+- Usar `.oxe/codebase/` como mapa do repositório, não como substituto dos artefatos da trilha.
+- Se a pergunta estiver ambígua, responder em modo “situação atual + próximos riscos + melhor próxima ação”.
+</context>
+
+<process>
+1. Ler `.oxe/STATE.md` global e determinar se há `active_session`.
+2. Se houver sessão ativa, ler nesta ordem:
+   - `SESSION.md`
+   - `spec/SPEC.md`, `spec/ROADMAP.md`, `spec/DISCUSS.md`, `spec/UI-SPEC.md` se existirem
+   - `plan/PLAN.md`, `plan/QUICK.md`, `plan/plan-agents.json`, `plan/quick-agents.json` se existirem
+   - `execution/STATE.md`, `execution/OBSERVATIONS.md`, `execution/DEBUG.md`, `execution/FORENSICS.md`, `execution/SUMMARY.md` se existirem
+   - `verification/VERIFY.md`, `verification/VALIDATION-GAPS.md`, `verification/SECURITY.md`, `verification/UI-REVIEW.md` se existirem
+3. Sem sessão ativa, ler o equivalente legado na raiz `.oxe/`.
+4. Em ambos os casos, ler também:
+   - `.oxe/codebase/OVERVIEW.md`
+   - `.oxe/codebase/STACK.md`
+   - `.oxe/codebase/CONCERNS.md`
+   - `.oxe/global/LESSONS.md` se existir, com fallback para `.oxe/LESSONS.md`
+   - `.oxe/SESSIONS.md` se a pergunta mencionar sessões, histórico ou retomada
+5. Responder à pergunta do utilizador com base em evidência explícita dos artefatos lidos.
+6. Se faltar artefato crítico para responder com segurança, dizer exatamente o que falta e qual comando OXE fecha essa lacuna.
+
+## Modo diagnóstico padrão
+
+Se o utilizador só disser algo genérico como “o que está acontecendo?”, “qual a situação?” ou “me contextualize”, responder com:
+
+- **Situação atual**
+- **Escopo ativo**
+- **Artefatos relevantes**
+- **Riscos ou lacunas**
+- **Próximo passo recomendado**
+
+## Regras de robustez
+
+- Não assumir que `doctor` ou `status` sejam session-aware; eles não substituem a leitura direta dos artefatos da sessão.
+- Se houver conflito entre `.oxe/STATE.md` global e `execution/STATE.md` da sessão, explicitar o conflito.
+- Se `VERIFY.md` existir e contradizer o estado declarado, priorizar a evidência do `VERIFY.md` e mencionar a incoerência.
+- Se o mapa `.oxe/codebase/` estiver ausente ou incompleto, dizer isso explicitamente antes de extrapolar sobre o repositório.
+</process>
+
+<output>
+- Resposta direta à pergunta do utilizador
+- Referência curta aos artefatos usados
+- Quando necessário, um único próximo passo OXE
+</output>
+
+<success_criteria>
+- [ ] A resposta parte de `.oxe/STATE.md` global e resolve corretamente a sessão ativa quando existir.
+- [ ] O contexto da sessão ativa tem precedência sobre artefatos legados.
+- [ ] Conflitos ou lacunas entre artefatos são explicitados.
+- [ ] A saída responde à pergunta sem inventar estado que não esteja nos arquivos.
+</success_criteria>

package/oxe/workflows/execute.md

@@ -89,7 +89,9 @@ Quando o comando `**Verificar:**` de uma tarefa `Tn` falha, **não parar silenci
 **Auto-loop no Modo B:** se `execute_mode: por_onda` e `loop_max` > 1 em STATE.md, o ciclo de retry roda automaticamente até `loop_max` tentativas antes de escalar para forensics.
 </failure_mode>
 
-<context>
+<context>
+**Contrato de robustez:** seguir `oxe/workflows/references/flow-robustness-contract.md`. Antes de executar, validar os artefatos obrigatórios e o gate do plano.
+
 **Observações pendentes:** verificar `OBSERVATIONS.md` do escopo resolvido no início de cada onda. Se houver entradas `pendente` com impacto `execute` ou `all`, incorporar no trabalho da onda atual e marcá-las `incorporada → execute (data)`.
 
 **Quick-agents (lean PDDA):** se existir **`quick-agents.json`** do escopo resolvido com `status: active` e a execução for baseada em **`QUICK.md`** (não há PLAN.md), adotar o `role` e `persona` de cada agente para os `steps[]` atribuídos. Ao concluir todos os steps, marcar `quick-agents.json` → `status: done` e sugerir `/oxe-verify`.
@@ -121,26 +123,31 @@ Se condições não atendidas: responder sem persona; sugerir `/oxe-plan-agent`
 **Rotina compact/checkpoint:** antes de onda experimental ou refactor grande, `/oxe-checkpoint` com slug ajuda a retomar. Após ondas que mudem stack ou árvore, lembrar `/oxe-compact`.
 </context>
 
-<process>
+<process>
 1. Ler **`.oxe/STATE.md`** global para resolver `active_session`, depois ler **`PLAN.md`** (se existir) e **`QUICK.md`** do escopo resolvido.
-2. Verificar **`OBSERVATIONS.md`** do escopo resolvido — incorporar pendentes de impacto `execute` ou `all` antes de iniciar.
-3. **Seleção de modo** (apenas se PLAN.md com 2+ ondas e `execute_mode` não definido em STATE): se o argumento já for `A`, `B` ou `C`, usá-lo diretamente; senão apresentar opções A/B/C e aguardar escolha; registrar em STATE.md.
-4. Identificar **onda ou bloco atual**: no PLAN, todas as tarefas da mesma onda sem dependências pendentes; no QUICK, passos ainda não marcados como feitos.
-5. Listar no chat: tarefas/passos desta onda, arquivos prováveis, comando **Verificar** de cada tarefa.
-6. **Implementar** conforme o modo escolhido:
-   - **Modo Completo:** executar todas as ondas em sequência com verificação inline entre ondas; sumarizar ao final.
-   - **Modo Por onda:** executar onda atual, apresentar checklist, parar.
-   - **Modo Por tarefa:** executar próxima tarefa pendente, parar.
-7. Após cada onda concluída, incluir checklist:
-   ```markdown
-   ## Checklist — Onda N (OXE)
-   - [ ] Pré-requisitos da onda conferidos (dependências Tk atendidas)
-   - [ ] Implementação da onda concluída
-   - [ ] Comando Verificar de cada tarefa executado (ou agendado)
-   ```
-8. Atualizar **`.oxe/STATE.md`** global com progresso resumido e, com sessão ativa, escrever o detalhe operacional em `execution/STATE.md`.
-9. Marcar OBS incorporadas como `incorporada → execute (data)` em `OBSERVATIONS.md` do escopo resolvido.
-</process>
+2. Se existir `PLAN.md`, validar a seção `## Autoavaliação do Plano` antes de qualquer implementação:
+   - `Melhor plano atual` deve ser `sim`;
+   - `Confiança` deve existir em `0–100%`;
+   - se `.oxe/config.json` definir `plan_confidence_threshold`, usar esse limiar; senão, usar `70%`;
+   - se a confiança estiver abaixo do limiar, **não executar**. Registrar o bloqueio e orientar redução de incerteza (`/oxe-discuss`, `/oxe-research` ou `/oxe-plan --replan`).
+3. Verificar **`OBSERVATIONS.md`** do escopo resolvido — incorporar pendentes de impacto `execute` ou `all` antes de iniciar.
+4. **Seleção de modo** (apenas se PLAN.md com 2+ ondas e `execute_mode` não definido em STATE): se o argumento já for `A`, `B` ou `C`, usá-lo diretamente; senão apresentar opções A/B/C e aguardar escolha; registrar em STATE.md.
+5. Identificar **onda ou bloco atual**: no PLAN, todas as tarefas da mesma onda sem dependências pendentes; no QUICK, passos ainda não marcados como feitos.
+6. Listar no chat: tarefas/passos desta onda, arquivos prováveis, comando **Verificar** de cada tarefa.
+7. **Implementar** conforme o modo escolhido:
+   - **Modo Completo:** executar todas as ondas em sequência com verificação inline entre ondas; sumarizar ao final.
+   - **Modo Por onda:** executar onda atual, apresentar checklist, parar.
+   - **Modo Por tarefa:** executar próxima tarefa pendente, parar.
+8. Após cada onda concluída, incluir checklist:
+   ```markdown
+   ## Checklist — Onda N (OXE)
+   - [ ] Pré-requisitos da onda conferidos (dependências Tk atendidas)
+   - [ ] Implementação da onda concluída
+   - [ ] Comando Verificar de cada tarefa executado (ou agendado)
+   ```
+9. Atualizar **`.oxe/STATE.md`** global com progresso resumido e, com sessão ativa, escrever o detalhe operacional em `execution/STATE.md`.
+10. Marcar OBS incorporadas como `incorporada → execute (data)` em `OBSERVATIONS.md` do escopo resolvido.
+</process>
 
 <success_criteria>
 - [ ] Modo de execução foi selecionado (ou herdado do STATE) antes de implementar.

package/oxe/workflows/help.md

@@ -11,11 +11,12 @@ No **projeto**, os passos canónicos estão em **`.oxe/workflows/*.md`** (layout
 </context>
 
 <output>
-## Os 8 comandos essenciais
+## Comandos principais
 
 ```
-/oxe              → onde estou / o que faço / help (entrada universal)
-/oxe-obs          → registrei algo importante — incorporado automaticamente nos próximos passos
+/oxe              → onde estou / o que faço / help (entrada universal)
+/oxe-ask          → entender a situação atual com leitura robusta de STATE + sessão + artefatos
+/oxe-obs          → registrei algo importante — incorporado automaticamente nos próximos passos
 /oxe-quick        → tarefa pequena, sem cerimônia (com agentes lean quando necessário)
 /oxe-session      → criar, alternar, retomar, fechar ou migrar sessões OXE
 /oxe-scan         → mapeia o projeto (ou atualiza o mapa se já existir)
@@ -34,7 +35,7 @@ Tudo o mais é ativado automaticamente por contexto, por config, ou existe como
 - `active_session` em `.oxe/STATE.md` define a sessão ativa com path relativo completo (`sessions/sNNN-slug`).
 - Com sessão ativa, workflows de spec/plan/execute/verify e suportes ligados à trilha escrevem em `.oxe/<active_session>/...`.
 - Permanecem globais: `.oxe/STATE.md`, `.oxe/config.json`, `.oxe/codebase/`, `.oxe/SESSIONS.md`, `.oxe/global/LESSONS.md`, `.oxe/global/MILESTONES.md`.
-- Nesta versão, o suporte é **workflows only**: `oxe-cc status` / `doctor` ainda não são session-aware.
+- `oxe-cc status` / `doctor` devem refletir a sessão ativa, a autoavaliação do plano e a saúde lógica do fluxo.
 
 ### `/oxe-session`
 
@@ -89,8 +90,8 @@ Com **`compact_max_age_days`** em `.oxe/config.json` (ver `oxe/templates/CONFIG.
 1. **scan** — após clonar ou quando o codebase mudar. **Inteligente:** se `.oxe/codebase/` já existir, opera em modo refresh (incremental) automaticamente — sem precisar chamar `/oxe-compact` separadamente. Use `--full` para forçar scan completo. Repositórios **legado** (COBOL, JCL, VB6): aplica `legacy-brownfield.md` automaticamente.
 2. **spec** — fluxo em **5 fases**: perguntas (máx 3 rodadas) → pesquisa (proposta inline na Fase 2, sem sair do spec) → requisitos R-ID (v1/v2/fora) → roteiro (`.oxe/ROADMAP.md`) → aprovação. Se `discuss_before_plan: true` na config, o próximo passo após aprovação é `oxe:discuss` antes de plan.
 3. **plan** — plano executável + **Verificar** por tarefa. Se 3+ domínios distintos, **sugere automaticamente** blueprint de agentes (`/oxe-plan --agents`). Sem `--agents`: solo. Com `--agents`: gera também `plan-agents.json` (schema 3 com `model_hint`).
-4. **execute** — modo selecionado 1 vez: **A) Completo** (1 sessão), **B) Por onda**, **C) Por tarefa**. Se Verificar falhar inline: diagnóstico automático (2-3 hipóteses + fix), sem precisar chamar `/oxe-debug` separadamente. Escalação para `/oxe-forensics` só se esgotar tentativas.
-5. **verify** — até **6 camadas** por config: auditoria pré-exec, tarefas + critérios A*, fidelidade D-NN, UAT, **gaps de cobertura** (camada 5 — `verification_depth: "thorough"`), **segurança OWASP** (camada 6 — `security_in_verify: true`). Sem comandos extras.
+4. **execute** — modo selecionado 1 vez: **A) Completo** (1 sessão), **B) Por onda**, **C) Por tarefa**. Antes de executar, validar a **Autoavaliação do Plano**: se `Melhor plano atual: não` ou a confiança estiver abaixo do limiar, o fluxo deve replanear em vez de implementar. Se Verificar falhar inline: diagnóstico automático (2-3 hipóteses + fix), sem precisar chamar `/oxe-debug` separadamente. Escalação para `/oxe-forensics` só se esgotar tentativas.
+5. **verify** — até **6 camadas** por config: auditoria pré-exec, tarefas + critérios A*, fidelidade D-NN, **calibração do plano**, UAT, **gaps de cobertura** (camada 5 — `verification_depth: "thorough"`), **segurança OWASP** (camada 6 — `security_in_verify: true`). Sem comandos extras.
 6. **retro** *(opcional, recomendado após verify_complete)* — `/oxe-retro` sintetiza 3–5 lições prescritivas em `.oxe/LESSONS.md`. Cada lição diz **o que fazer diferente** no próximo ciclo — consumida automaticamente pelo próximo spec/plan.
 7. **→ próximo ciclo** — spec/plan do próximo ciclo lê LESSONS.md automaticamente. Os erros do ciclo anterior não se repetem.
 
@@ -132,14 +133,15 @@ Um único comando para: `milestone new|complete|status|audit`, `workstream new|s
 
 - **`npx oxe-cc`** ou **`npx oxe-cc install`** — mesma instalação (alias explícito).
 - Instala workflows em `.oxe/` (layout mínimo) ou `oxe/` + `.oxe/` com **`--global`**; integrações em `~/.cursor`, `~/.copilot`, `~/.claude` (e mais destinos com **`--copilot-cli`** / **`--all-agents`**).
-- **`oxe-cc doctor`** — Node, workflows do pacote vs projeto, `config.json`, mapas do codebase, **coerência STATE vs arquivos**, scan antigo (`scan_max_age_days`), compact antigo (`compact_max_age_days`), seções SPEC, ondas do PLAN, **avisos** não bloqueantes sobre estrutura dos `.md` de workflow (ex.: `<objective>`, critérios de sucesso).
-- **`oxe-cc status`** — coerência `.oxe/` + **um** próximo passo (espelha `next.md`). Com **`--json`**, uma linha JSON com **`oxeStatusSchema: 2`**, `nextStep`, `cursorCmd`, `reason`, `artifacts`, `phase`, `scanDate`, `staleScan`, `compactDate`, `staleCompact`, `diagnostics` (e com **`--json --hints`** também o array **`hints`**). Com **`--hints`** em modo texto, bloco **Lembretes (rotina OXE)** (scan/compact antigos quando `scan_max_age_days` / `compact_max_age_days` estão ativos em `config.json`).
-- **`oxe-cc init-oxe`** — só bootstrap `.oxe/` (STATE, config, codebase).
-- **`oxe-cc uninstall`** — remove integrações no HOME e, por omissão, pastas de workflows no repo (`--ide-only` só HOME).
-- **`/oxe-update`** (Cursor; noutras ferramentas use o terminal no projeto) — workflow de atualização: verificar npm, correr `oxe-cc update`, `doctor`.
-- **`oxe-cc update --check`** — só comparar versão em execução com a `latest` no npm (sem instalar).
-- **`oxe-cc update --if-newer`** — só executa o `npx oxe-cc@latest` se houver versão mais nova no npm.
-- **`oxe-cc update` / `npx oxe-cc@latest --force`** — atualizar ficheiros OXE no projeto.
+- **`oxe-cc doctor`** — Node, workflows do pacote vs projeto, `config.json`, bootstrap mínimo de `.oxe/`, mapas do codebase, **coerência STATE vs arquivos**, sessão ativa, autoavaliação do plano, scan antigo (`scan_max_age_days`), compact antigo (`compact_max_age_days`), seções SPEC, ondas do PLAN e **saúde lógica** (`healthy` | `warning` | `broken`).
+- **`oxe-cc status`** — coerência `.oxe/` + **um** próximo passo (espelha `next.md`). Com **`--json`**, uma linha JSON com `healthStatus`, `activeSession`, `planSelfEvaluation` e `diagnostics` completos além do próximo passo. Com **`--hints`** em modo texto, bloco **Lembretes (rotina OXE)** (scan/compact antigos quando `scan_max_age_days` / `compact_max_age_days` estão ativos em `config.json`).
+- **`oxe-cc init-oxe`** — só bootstrap `.oxe/` (STATE, config, codebase).
+- **`oxe-cc uninstall`** — remove integrações no HOME e, por omissão, pastas de workflows no repo (`--ide-only` só HOME).
+- **`oxe-cc uninstall --global-cli`** — além da limpeza dos artefatos OXE, executa `npm uninstall -g oxe-cc` para remover o binário global do PATH.
+- **`/oxe-update`** (Cursor; noutras ferramentas use o terminal no projeto) — workflow de atualização: verificar npm, correr `oxe-cc update`, `doctor`.
+- **`oxe-cc update --check`** — só comparar versão em execução com a `latest` no npm (sem instalar).
+- **`oxe-cc update --if-newer`** — só executa o `npx oxe-cc@latest` se houver versão mais nova no npm.
+- **`oxe-cc update` / `npx oxe-cc@latest --force`** — atualizar ficheiros OXE no projeto. Aceita flags extras como `--ide-local`, `--cursor`, `--copilot-cli`, `--global`, `--global-cli`.
 
 **CI / sem perguntas:** `OXE_NO_PROMPT=1` — layout mínimo e integrações padrão no HOME, salvo flags (`--global`, `--cursor`, …). Se existir **`.oxe/config.json`** com bloco **`install`** (perfil, `repo_layout`), aplica-se quando **não** há flags IDE explícitas; para ignorar: **`--no-install-config`**. Detalhes: `oxe/templates/CONFIG.md`.
 
@@ -153,8 +155,9 @@ Um pedido → **um** destino (sem gerar contrato). O agente aplica `route.md` ou
 
 | Se o utilizador disser (exemplos) | Comando / ação |
 |-----------------------------------|----------------|
-| Não sei que passo OXE sou / “o que faço agora?” | `/oxe-next` ou `npx oxe-cc status` |
-| Acabei de clonar / falta OXE no projeto | `npx oxe-cc@latest` (ou `oxe-cc`) na raiz do repo |
+| Não sei que passo OXE sou / “o que faço agora?” | `/oxe-next` ou `npx oxe-cc status` |
+| Quero entender rapidamente a situação real da trilha atual | `/oxe-ask [pergunta]` |
+| Acabei de clonar / falta OXE no projeto | `npx oxe-cc@latest` (ou `oxe-cc`) na raiz do repo |
 | Verify falhou várias vezes / doctor estranho / artefatos incoerentes | `/oxe-forensics` |
 | Teste ou erro técnico durante o trabalho (stack, flake) | `/oxe-debug` (com **Tn** se houver) |
 | Revisar diff / PR antes do merge | `oxe/workflows/review-pr.md` em contexto *(Copilot: `/oxe-review-pr`)* |

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/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

@@ -12,6 +12,7 @@ Se o usuário pedir **--replan** (ou replanejamento implícito após `verify_fai
 </objective>
 
 <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/`.
 - 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: ... -->`.
@@ -30,7 +31,7 @@ Se o usuário pedir **--replan** (ou replanejamento implícito após `verify_fai
 </context>
 
 <format_plan>
-Cada tarefa em PLAN.md deve seguir a ordem abaixo — **Verificar vem ANTES de Implementar** (test-first):
+Cada tarefa em PLAN.md deve seguir a ordem abaixo — **Verificar vem ANTES de Implementar** (test-first):
 
 ```markdown
 ### Tn — título curto
@@ -45,10 +46,44 @@ Cada tarefa em PLAN.md deve seguir a ordem abaixo — **Verificar vem ANTES de I
 - **Aceite vinculado:** A1, A2 (IDs exatos da tabela de critérios da SPEC)
 - **Decisão vinculada:** D-01, D-02 (IDs de `.oxe/DISCUSS.md` — omitir se não houver DISCUSS)
 <!-- oxe-task: {"id":"Tn","wave":1,"type":"feature","files":[],"done":false,"complexity":"S"} -->
-```
-
-**Escala de Complexidade:**
-| Valor | Esforço estimado | Sinal de alerta |
+```
+
+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
+
+**Escala de Complexidade:**
+| Valor | Esforço estimado | Sinal de alerta |
 |-------|-----------------|-----------------|
 | `S` | < 30 min, 1–2 arquivos | — |
 | `M` | < 2h, 2–5 arquivos | — |
@@ -72,12 +107,16 @@ Antes de finalizar a resposta ao utilizador, o agente **deve** percorrer este ga
 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.
-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.
-
-Se após correções estruturais persistir ambiguidade de produto: **uma** frase recomendando `oxe:discuss` ou `oxe:spec`.
-
-Resumo obrigatório no chat: `Gate do plano: OK` ou `Gate do plano: corrigido (N problemas)`.
+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.
+
+Se após correções estruturais persistir ambiguidade de produto: **uma** frase recomendando `oxe:discuss` ou `oxe:spec`.
+
+Resumo obrigatório no chat: `Gate do plano: OK` ou `Gate do plano: corrigido (N problemas)`.
 </plan_quality_gate>
 
 <process>
@@ -86,12 +125,13 @@ Resumo obrigatório no chat: `Gate do plano: OK` ou `Gate do plano: corrigido (N
 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).
-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.
-</process>
+6. Definir ondas: onda 1 = tarefas sem dependência entre si; onda seguinte = dependentes; respeitar `plan_max_tasks_per_wave` se configurado.
+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.

package/oxe/workflows/quick.md

@@ -9,6 +9,7 @@ Usar quando: correção pontual, refactor local, feature pequena ou protótipo q
 </objective>
 
 <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.
@@ -120,7 +121,8 @@ Uso **sem** novo slash: é o mesmo `/oxe-quick` com redação mínima.
 - **Passos** — lista numerada, **máximo 10**; cada passo acionável numa linha.
 - **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).
+- **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.
 
@@ -149,7 +151,8 @@ Se **sim**, o próximo passo recomendado no chat é **`/oxe-spec`** (depois disc
    - **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.
+   - **Promover para spec/plan?** — conforme seção acima.
+   - **Plano formal existente?** — `não`; usar `sim` apenas se este quick estiver ancorado a um `PLAN.md` já aprovado no mesmo escopo.
 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>"`.

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/spec.md

@@ -16,6 +16,8 @@ Se **`.oxe/config.json`** tiver `discuss_before_plan: true`: mencionar no final
 <context>
 **Pré-requisito preferível:** scan executado. Se não existir, mencionar na spec que o mapa está pendente.
 
+**Contrato de robustez:** seguir `oxe/workflows/references/flow-robustness-contract.md`. Antes de escrever, resolver artefatos obrigatórios, validar pré-condições e só então produzir a spec. O output desta fase deve deixar evidência estruturada suficiente para o `plan` decidir se o plano é realmente o melhor disponível.
+
 **Resolução de sessão:** antes de ler ou escrever artefatos desta trilha, resolver `active_session` em `.oxe/STATE.md` conforme `oxe/workflows/references/session-path-resolution.md`. Com sessão ativa:
 - `SPEC.md`, `ROADMAP.md` e `DISCUSS.md` vivem em `.oxe/<active_session>/spec/`
 - `OBSERVATIONS.md`, `RESEARCH.md` e `research/` seguem o escopo da sessão
@@ -160,13 +162,19 @@ Percorrer esta lista de verificação:
 | 5 | **Critérios vagos:** algum A* usa linguagem não-mensurável ("deve ser rápido", "interface amigável") sem métrica? | Refinar: "resposta < 200ms p95", "WCAG 2.1 AA" |
 | 6 | **Dependências implícitas:** algum requisito v1 pressupõe que outro requisito (v2 ou fora) já esteja implementado? | Tornar dependência explícita ou reordenar versioning |
 
-**Resultado obrigatório antes de avançar:**
-- **0 problemas** → avançar para Fase 5 normalmente.
-- **1–2 problemas** → corrigir inline na spec, anotar o que foi ajustado em 1 linha.
-- **3+ problemas** → apresentar lista ao usuário com a Fase 3 revisada (não reiniciar do zero).
-
-O resultado desta reflexão é **invisível ao usuário** — é trabalho interno do agente. Somente os ajustes feitos aparecem na spec final.
-</auto_reflexao>
+**Resultado obrigatório antes de avançar:**
+- **0 problemas** → avançar para Fase 5 normalmente.
+- **1–2 problemas** → corrigir inline na spec, anotar o que foi ajustado em 1 linha.
+- **3+ problemas** → apresentar lista ao usuário com a Fase 3 revisada (não reiniciar do zero).
+
+O resultado desta reflexão é **invisível ao usuário** — é trabalho interno do agente. Somente os ajustes feitos aparecem na spec final.
+
+**Saída estruturada obrigatória para o plan:** após esta reflexão, a SPEC final deve deixar explícitos:
+- requisitos estáveis;
+- ambiguidades restantes;
+- conflitos resolvidos ou ainda abertos;
+- evidências faltantes que podem reduzir a confiança do plano.
+</auto_reflexao>
 
 <fase_5_aprovacao>
 ## Fase 5 — Aprovação e próximo passo