oxe-cc 0.6.0 → 0.6.2

package/.cursor/commands/oxe-retro.md

@@ -0,0 +1,11 @@
+---
+description: "OXE — Retrospectiva de ciclo: 3–5 lições prescritivas em .oxe/LESSONS.md para ciclos futuros"
+---
+
+OXE — Retrospectiva de ciclo: 3–5 lições prescritivas em .oxe/LESSONS.md para ciclos futuros
+
+Executa o workflow **OXE retro** no repositório atual. Lê e aplica **integralmente**:
+
+`oxe/workflows/retro.md`
+
+Lê VERIFY.md, FORENSICS.md, SUMMARY.md. `$ARGUMENTS` = contexto extra opcional.

package/.github/prompts/oxe-retro.prompt.md

@@ -0,0 +1,12 @@
+---
+name: oxe-retro
+agent: agent
+description: OXE — Retrospectiva de ciclo: 3–5 lições prescritivas em .oxe/LESSONS.md para ciclos futuros
+argument-hint: "[opcional: contexto extra sobre o ciclo — o que foi mais difícil, o que surpreendeu]"
+---
+
+Executa o workflow **OXE retro** no repositório atual. Lê e aplica **integralmente**:
+
+`oxe/workflows/retro.md`
+
+Lê VERIFY.md, FORENSICS.md, SUMMARY.md. `$ARGUMENTS` = contexto extra opcional.

package/README.md

@@ -7,7 +7,7 @@
 [![npm](https://img.shields.io/npm/v/oxe-cc.svg?style=flat-square)](https://www.npmjs.com/package/oxe-cc)
 [![license](https://img.shields.io/npm/l/oxe-cc.svg?style=flat-square)](LICENSE)
 
-**Versão:** `0.6.0` · [package.json](package.json)
+**Versão:** `0.6.2` · [package.json](package.json)
 
 ```bash
 npx oxe-cc@latest
@@ -51,12 +51,14 @@ Tudo o mais é ativado automaticamente por contexto ou existe como escape hatch.
 ```
 /oxe-obs (qualquer momento)
      ↓
-/oxe-scan → /oxe-spec → /oxe-plan ──────────→ /oxe-execute → /oxe-verify
-                              ↓
-                         /oxe-quick (trabalho pequeno)
+/oxe-scan → /oxe-spec → /oxe-plan ──────────→ /oxe-execute → /oxe-verify → /oxe-retro
+                              ↓                                                  ↓
+                         /oxe-quick (trabalho pequeno)                    .oxe/LESSONS.md
+                                                                               ↓
+                                                                    (alimenta o próximo ciclo)
 ```
 
-Cada passo lê o anterior como contexto e escreve seu artefato em `.oxe/`. Nenhum passo depende de você re-explicar o que já foi decidido.
+Cada passo lê o anterior como contexto e escreve seu artefato em `.oxe/`. Nenhum passo depende de você re-explicar o que já foi decidido. Os erros do ciclo anterior não se repetem.
 
 ---
 
@@ -66,9 +68,14 @@ Cada passo lê o anterior como contexto e escreve seu artefato em `.oxe/`. Nenhu
 |---------|----------------------|
 | `/oxe` | Sem input → próximo passo. Com texto → roteamento. Com "help" → 8 comandos. |
 | `/oxe-scan` | Se `.oxe/codebase/` já existe → modo refresh automático. `--full` força scan completo. |
-| `/oxe-plan` | 3+ domínios → sugere `--agents`. Com `--agents` → gera blueprint com `model_hint` por agente. |
-| `/oxe-execute` | Verificar falha → diagnóstico inline (2-3 hipóteses + fix). Sem precisar chamar `/oxe-debug`. |
-| `/oxe-verify` | `verification_depth: "thorough"` → gaps automático. `security_in_verify: true` → OWASP automático. |
+| `/oxe-spec` | **Auto-reflexão semântica** antes da aprovação: detecta contradições, critérios vagos, escopo creep e conflitos com stack — sem requisição extra. Lê `LESSONS.md` para não repetir erros do ciclo anterior. |
+| `/oxe-plan` | **Test-first:** `Verificar` vem antes de `Implementar` em cada tarefa. `Complexidade: S/M/L/XL` — tarefas XL bloqueiam o gate sem sub-tarefas. Com `--agents`: `model_hint` por agente orienta qual tier de modelo usar (schema v3). |
+| `/oxe-execute` | Verificar falha → diagnóstico inline (2-3 hipóteses + fix). Sem precisar chamar `/oxe-debug`. Exibe `model_hint` ao iniciar cada agente do blueprint. |
+| `/oxe-verify` | Até 6 camadas por config: audit + critérios + decisões + UAT + gaps (`verification_depth: thorough`) + OWASP (`security_in_verify: true`). Sugere `/oxe-retro` ao concluir. |
+| `/oxe-retro` | Sintetiza 3–5 lições prescritivas em `LESSONS.md` — consumidas automaticamente pelo próximo spec/plan. |
+| `/oxe-research` | **Thinking depth:** classifica `surface` / `standard` / `deep` e recomenda raciocínio estendido para reverse engineering e arquitetura complexa. |
+| `/oxe-loop` | Retry iterativo de onda: executa → verifica → diagnostica (2-3 hipóteses) → corrige → repete até `max` tentativas; escala para `/oxe-forensics` se esgotar. |
+| `/oxe-security` | Auditoria OWASP Top 10 filtrada pelo stack. Achados P0/P1/P2 vinculados a tarefas existentes. Integrado ao verify via `security_in_verify: true`. |
 | `/oxe-project` | `milestone` + `workstream` + `checkpoint` em um único comando. |
 
 ---
@@ -85,8 +92,9 @@ Cada passo lê o anterior como contexto e escreve seu artefato em `.oxe/`. Nenhu
 | `/oxe-plan` | Plano por ondas. `--agents` ativa blueprint com `model_hint` por agente | `.oxe/PLAN.md` [+ `plan-agents.json`] |
 | `/oxe-execute` | Execução A/B/C com debug inline automático em falhas | `.oxe/STATE.md` |
 | `/oxe-verify` | Até 6 camadas por config: audit + critérios + decisões + UAT + gaps + segurança | `.oxe/VERIFY.md` |
-| `/oxe-obs` | Registra observação → auto-incorporada nos próximos workflows | `.oxe/OBSERVATIONS.md` |
+| `/oxe-obs` | Registra observação → propaga automaticamente para R-IDs e Tns afetados → auto-incorporada | `.oxe/OBSERVATIONS.md` |
 | `/oxe-quick` | Lean: objetivo → passos → agentes opcionais → verify | `.oxe/QUICK.md` |
+| `/oxe-retro` | Retrospectiva: 3–5 lições prescritivas → alimenta spec/plan do próximo ciclo | `.oxe/LESSONS.md` |
 | `/oxe-project` | Unifica: `milestone`, `workstream`, `checkpoint` | vários |
 
 ### Escape hatches (não precisam ser decorados)
@@ -124,13 +132,16 @@ Cada passo lê o anterior como contexto e escreve seu artefato em `.oxe/`. Nenhu
 └── workstreams/      ← trilhas paralelas de desenvolvimento
 ```
 
-### `/oxe-spec` — spec em 5 fases, máx 3 rodadas de perguntas
+### `/oxe-spec` — spec em 5 fases com auto-reflexão semântica
 
 1. **Perguntas** — blocos de 3-5 por rodada, máximo 3 rodadas
 2. **Pesquisa** — proposta inline na Fase 2 (sem sair do spec)
 3. **Requisitos** — tabela R-ID com v1/v2/fora e critérios A*
 4. **Roteiro** — fases de entrega → `.oxe/ROADMAP.md`
-5. **Aprovação** → instrui `/oxe-plan` ou `/oxe-plan --agents`
+5. **Auto-reflexão** *(automática, sem requisição extra)* — detecta contradições, critérios vagos, escopo creep, conflitos com stack. Corrige antes de apresentar ao usuário.
+6. **Aprovação** → instrui `/oxe-plan` ou `/oxe-plan --agents`
+
+A spec lê `.oxe/LESSONS.md` antes de iniciar — lições do ciclo anterior informam as perguntas e os critérios.
 
 ### `/oxe-execute` — economia de requisições com debug automático
 
@@ -150,6 +161,31 @@ Se uma tarefa falha: diagnóstico inline automático (2-3 hipóteses → fix →
 
 O próximo `/oxe-plan`, `/oxe-spec` ou `/oxe-execute` incorpora automaticamente — sem prompt extra.
 
+### `/oxe-plan` — test-first com complexidade explícita
+
+Cada tarefa usa a ordem **Verificar → Implementar** (test-first):
+```
+Verificar: como saberei que está pronto?   ← definido PRIMEIRO
+Implementar: o mínimo para passar o Verificar
+Complexidade: S | M | L | XL
+```
+
+Tarefas `XL` bloqueam o gate sem sub-tarefas ou justificativa. `/oxe-obs` propaga automaticamente constraints para os R-IDs e Tns afetados.
+
+### `/oxe-retro` — loop de aprendizado
+
+```
+/oxe-verify completo
+     ↓
+/oxe-retro → 3–5 lições prescritivas → .oxe/LESSONS.md
+                                              ↓
+                              /oxe-spec (próximo ciclo lê LESSONS)
+                              /oxe-plan (próximo ciclo lê LESSONS)
+```
+
+Lições não são diário — são instruções para o próximo ciclo. Exemplo:
+> "Tarefas com integração de terceiros: `Complexidade: L` mínimo + `Verificar` com mock fallback"
+
 ### Plan-Driven Dynamic Agents — agentes por demanda
 
 Com `/oxe-plan --agents` (ou sugerido quando 3+ domínios detectados):

package/bin/banner.txt

@@ -15,4 +15,4 @@
 
 ══════════════════════════════════════════════════════
 
-                      v0.6.0
+                      v0.6.2

package/commands/oxe/retro.md

@@ -0,0 +1,16 @@
+---
+name: oxe:retro
+description: OXE — Retrospectiva de ciclo: sintetiza lições prescritivas em .oxe/LESSONS.md (alimenta ciclos futuros automaticamente)
+argument-hint: "[opcional: contexto sobre o ciclo]"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Task
+---
+
+**Workflow canônico:** `oxe/workflows/retro.md`
+
+Execute integralmente esse ficheiro. Lê VERIFY.md, FORENSICS.md, SUMMARY.md para sintetizar 3–5 lições prescritivas. `$ARGUMENTS` = contexto extra opcional.

package/oxe/templates/LESSONS.template.md

@@ -0,0 +1,43 @@
+---
+oxe_doc: lessons
+updated: YYYY-MM-DD
+---
+
+# Lições Aprendidas OXE
+
+<!-- Consumido automaticamente por /oxe-spec, /oxe-plan, /oxe-execute, /oxe-verify -->
+<!-- Cada entrada é PRESCRITIVA: diz o que fazer diferente, não apenas o que aconteceu -->
+
+| Ciclo | Data | Tipo | Lição (resumo) | Aplicar em | Status |
+|-------|------|------|----------------|------------|--------|
+| C-01 | YYYY-MM-DD | plan | Tarefas de integração requerem Complexidade L mínimo | /oxe-plan | ativo |
+
+---
+
+### C-01 — YYYY-MM-DD
+
+**Fonte:** VERIFY.md (gaps) + FORENSICS.md (causa raiz)
+
+---
+
+**L-01** · Tipo: `plan`
+**Lição:** Tarefas que integram APIs de terceiros devem ter `Complexidade: L` mínimo e `Verificar` com mock como fallback quando API estiver indisponível.
+**Raiz do problema:** T4 foi marcada `M` mas envolveu 3 serviços externos — estorou 2 ondas.
+**Aplicar em:** `/oxe-plan` — ao planejar tarefas com `INTEGRATIONS.md` externos, elevar complexidade automaticamente.
+**Status:** ativo
+
+---
+
+**L-02** · Tipo: `spec`
+**Lição:** Critérios A* que envolvem "performance" devem incluir métrica mensurável (ex.: "< 200ms p95 em carga de 100 req/s") desde a Fase 3.
+**Raiz do problema:** A3 dizia "resposta rápida" — verify não conseguiu evidência objetiva.
+**Aplicar em:** `/oxe-spec` Fase 3 — ao criar critérios de performance, pedir métrica específica antes de aprovar o requisito.
+**Status:** ativo
+
+---
+
+**L-03** · Tipo: `process`
+**Lição:** Quando o plano tem 3+ domínios distintos, sempre usar `/oxe-plan --agents`. Solo em 3+ domínios gera tarefas com contexto insuficiente.
+**Raiz do problema:** plano solo com auth + API + UI causou tarefas que misturavam contexto de 2 domínios.
+**Aplicar em:** `/oxe-plan` — gate de sugestão de `--agents` já existe; reforçar como obrigatório para 3+.
+**Status:** ativo

package/oxe/templates/PLAN.template.md

@@ -39,10 +39,11 @@ inputs: []
 - **Arquivos prováveis:** `…`
 - **Depende de:** —
 - **Onda:** 1
-- **Implementação:** …
+- **Complexidade:** S
 - **Verificar:**
   - Comando: `…`
   - Manual: (opcional) …
+- **Implementar:** o mínimo para fazer a verificação acima passar.
 - **Aceite vinculado:** A1, A2 (IDs da tabela de critérios em SPEC.md)
 
 ---

package/oxe/workflows/help.md

@@ -74,7 +74,8 @@ Com **`compact_max_age_days`** em `.oxe/config.json` (ver `oxe/templates/CONFIG.
 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.
-6. **→ próximo passo** — `/oxe` sugere automaticamente o que fazer agora (nova feature, milestone, ou revisar gaps).
+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.
 
 **Escape hatches (não precisam ser decorados — aparecem quando necessários):**
 

package/oxe/workflows/obs.md

@@ -31,6 +31,8 @@ Arquivo: **`.oxe/OBSERVATIONS.md`**
 
 ### OBS-001 — 2026-04-04 | execute/T3
 **Impacto:** spec, plan
+**Afeta (spec):** R3, R5
+**Afeta (plan):** T4, T7
 **Status:** pendente
 
 JWT expiration deve ser configurável via `JWT_EXPIRES_IN` env var, não hardcoded 7d.
@@ -59,6 +61,11 @@ API deve retornar mensagens de erro em português do Brasil.
 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 `.oxe/OBSERVATIONS.md` 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 **`.oxe/OBSERVATIONS.md`**:
    - Adicionar linha na tabela de índice.
    - Adicionar seção `### OBS-NNN` com contexto, impacto, status e texto.

package/oxe/workflows/oxe.md

@@ -81,7 +81,7 @@ Apresentar de forma concisa:
 ```
 /oxe-obs (qualquer momento)
      ↓
-/oxe-scan → /oxe-spec → /oxe-plan → /oxe-execute → /oxe-verify
+/oxe-scan → /oxe-spec → /oxe-plan → /oxe-execute → /oxe-verify → /oxe-retro
                                   ↓
                            /oxe-quick (trabalho pequeno)
 ```

package/oxe/workflows/plan-agent.md

@@ -76,9 +76,9 @@ Raiz do ficheiro **`.oxe/plan-agents.json`**:
 
 | Campo | Obrigatório | Significado |
 |-------|-------------|-------------|
-| `oxePlanAgentsSchema` | sim | **2** nas gerações atuais ( **1** = legado sem `runId`/`lifecycle` obrigatórios). |
-| `runId` | sim (schema 2) | Identidade da sessão do blueprint; nova em cada plan-agent / replan. |
-| `lifecycle` | sim (schema 2) | `status`: `pending_execute` \| `executing` \| `closed` \| `invalidated`; `since` ISO; opcional `invalidatedReason`, `invalidatedBy` (`quick` \| `out_of_scope` \| `new_plan` \| `manual`). |
+| `oxePlanAgentsSchema` | sim | **3** nas gerações atuais ( **2** = sem `model_hint`; **1** = legado sem `runId`/`lifecycle` obrigatórios). |
+| `runId` | sim (schema ≥ 2) | Identidade da sessão do blueprint; nova em cada plan-agent / replan. |
+| `lifecycle` | sim (schema ≥ 2) | `status`: `pending_execute` \| `executing` \| `closed` \| `invalidated`; `since` ISO; opcional `invalidatedReason`, `invalidatedBy` (`quick` \| `out_of_scope` \| `new_plan` \| `manual`). |
 | `goal` | sim | Frase curta alinhada ao objetivo da entrega (eco da SPEC). |
 | `specRef` | não | Referência livre (ex.: path `.oxe/SPEC.md` ou nota de versão). |
 | `agents` | sim | Lista de objetos agente (ver abaixo). |
@@ -133,7 +133,7 @@ Resumo obrigatório no chat: `Gate plan-agent: OK` ou `Gate plan-agent: corrigid
 
 <success_criteria>
 - [ ] `PLAN.md` existe e passa o gate de **`plan.md`**.
-- [ ] `plan-agents.json` existe com schema **2**, `runId`, `lifecycle`, e passa **`<plan_agent_quality_gate>`**.
+- [ ] `plan-agents.json` existe com schema **3**, `runId`, `lifecycle`, `model_hint` por agente (ou omitido), e passa **`<plan_agent_quality_gate>`**.
 - [ ] Cada tarefa `Tn` aparece em **exatamente um** `taskIds`.
 - [ ] `execution.waves` reflete dependências entre agentes sem ciclos.
 - [ ] `.oxe/plan-agent-messages/README.md` presente.

package/oxe/workflows/plan.md

@@ -13,6 +13,8 @@ Se o usuário pedir **--replan** (ou replanejamento implícito após `verify_fai
 
 <context>
 - Se existir **`.oxe/OBSERVATIONS.md`** 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/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: ... -->`.
+- **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 **`.oxe/UI-SPEC.md`**, as tarefas de UI devem referenciar secções do UI-SPEC no texto de **Implementação** ou **Verificar**.
@@ -27,22 +29,33 @@ Se o usuário pedir **--replan** (ou replanejamento implícito após `verify_fai
 </context>
 
 <format_plan>
-Cada tarefa em PLAN.md deve seguir:
+Cada tarefa em PLAN.md deve seguir a ordem abaixo — **Verificar vem ANTES de Implementar** (test-first):
 
 ```markdown
 ### Tn — título curto
 - **Arquivos prováveis:** `...`
 - **Depende de:** Tk ou —
 - **Onda:** 1 | 2 | …
-- **Implementação:** 1–3 frases do que fazer.
+- **Complexidade:** S | M | L | XL
 - **Verificar:**
   - Comando: `...` (ex.: npm test, pytest, mvn test)
   - Manual: (opcional) passos breves
+- **Implementar:** o mínimo para fazer a verificação acima passar (1–3 frases).
 - **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} -->
+<!-- oxe-task: {"id":"Tn","wave":1,"type":"feature","files":[],"done":false,"complexity":"S"} -->
 ```
 
+**Escala de Complexidade:**
+| Valor | Esforço estimado | Sinal de alerta |
+|-------|-----------------|-----------------|
+| `S` | < 30 min, 1–2 arquivos | — |
+| `M` | < 2h, 2–5 arquivos | — |
+| `L` | < 1 dia, múltiplos componentes | Verificar que Verificar é específico |
+| `XL` | > 1 dia, impacto arquitetural | **Gate: deve ser quebrada em sub-tarefas ou ter justificativa** |
+
+**Princípio test-first:** escreva o `Verificar` antes de escrever o `Implementar`. A pergunta é: "Como saberei que está pronto?" — a resposta define o target; `Implementar` é o caminho mínimo até esse target.
+
 **Projetos sem suíte de testes única (legado):** o bloco **Verificar** pode usar `Comando: —` e **Manual** com Grep, leitura de paths ou checklist — ver exemplos em **`oxe/workflows/references/legacy-brownfield.md`**. Todo critério **A*** da SPEC deve aparecer em **Aceite vinculado** de alguma tarefa ou como gap explícito.
 
 **Comparativo host ↔ cliente (migração / paridade):** pode-se dedicar tarefas a produzir ou atualizar uma **matriz Markdown** (classificações: equivalente / implementação diferente / só host / só cliente) com colunas de artefactos reais no repo — ver secção *Molde de comparativo* em **`oxe/workflows/references/legacy-brownfield.md`**. Cada **Tn** deve manter **Aceite vinculado** aos **A*** que essa matriz satisfaz.
@@ -56,8 +69,10 @@ Antes de finalizar a resposta ao utilizador, o agente **deve** percorrer este ga
 3. **Cobertura A*:** todos os IDs da tabela de critérios em `.oxe/SPEC.md` 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 `.oxe/UI-SPEC.md`, toda tarefa cuja **Implementação** ou **Verificar** toque UI (paths como `*.tsx`, `components/`, ou palavras-chave front, ou pedido explícito do utilizador) deve citar **secção § do UI-SPEC** ou path explícito.
-7. **Fidelidade de decisões:** se existir `.oxe/DISCUSS.md` com IDs **D-NN**, cada decisão com impacto técnico deve aparecer em **Decisão vinculada:** de alguma tarefa, ou ter nota explícita de gap (fora do escopo desta entrega). Sem cobertura para D-NN técnico = falha do gate.
+6. **UI-SPEC:** se existir `.oxe/UI-SPEC.md`, 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 `.oxe/DISCUSS.md` com IDs **D-NN**, 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`.
 

package/oxe/workflows/retro.md

@@ -0,0 +1,62 @@
+# OXE — Workflow: retro (retrospectiva de ciclo)
+
+<objective>
+Sintetizar os aprendizados de um ciclo completo (spec → verify) em **`.oxe/LESSONS.md`** — um arquivo prescritivo e cumulativo que alimenta automaticamente ciclos futuros.
+
+**Princípio:** lições não são diário — são instruções para o próximo ciclo. Cada entrada diz COMO agir diferente, não apenas o que aconteceu.
+
+Pode ser chamado:
+- Após `/oxe-verify` (ciclo normal completo)
+- Após `/oxe-verify` com falha e replanejamento (ciclo com retrabalho)
+- A qualquer momento para capturar aprendizados antes que se percam
+</objective>
+
+<context>
+- **Pré-requisito preferível:** `.oxe/VERIFY.md` existente. Sem ele, a retro é baseada em STATE.md e relato do usuário.
+- **Artefato:** `.oxe/LESSONS.md` — append-only por padrão; nunca apagar entradas anteriores, apenas mudar `Status` para `resolvido`.
+- **Consumidores:** `/oxe-spec` (lições tipo `spec`), `/oxe-plan` (lições tipo `plan`), `/oxe-scan` (lições tipo `process`), `/oxe-execute` (lições tipo `execute`).
+- **Ciclo ID:** sequencial `C-01`, `C-02`, … (continuar do último em LESSONS.md).
+- Template: `oxe/templates/LESSONS.template.md`.
+</context>
+
+<taxonomy>
+## Taxonomia de tipos de lição
+
+| Tipo | Quando usar | Consumido por |
+|------|-------------|---------------|
+| `spec` | Problemas na definição de requisitos ou critérios A* | `/oxe-spec` Fase 1/3 |
+| `plan` | Problemas de granularidade, ondas, verificações | `/oxe-plan` |
+| `execute` | Padrões de falha na implementação, hipóteses erradas | `/oxe-execute` |
+| `verify` | Critérios vagos, evidências insuficientes, camadas puladas | `/oxe-verify` |
+| `process` | Escolha errada de workflow (quick vs spec, solo vs agents) | `/oxe-scan`, qualquer entry |
+| `agents` | Problemas de orquestração, runId, dependências de agente | `/oxe-plan-agent`, `/oxe-execute` |
+
+**Formato de lição (prescritivo, não descritivo):**
+- ❌ "A tarefa T4 demorou muito" (descritivo — não ajuda no próximo ciclo)
+- ✅ "Tarefas com integração de terceiros devem ter Complexidade L mínimo + Verificar com mock fallback" (prescritivo — o próximo plan pode aplicar)
+</taxonomy>
+
+<process>
+1. Ler **`.oxe/VERIFY.md`** se existir: identificar tarefas que falharam, critérios A* sem evidência, gaps documentados.
+2. Ler **`.oxe/FORENSICS.md`** se existir: capturar causa raiz de falhas de execução.
+3. Ler **`.oxe/SUMMARY.md`** se existir: capturar contexto de replans e decisões forçadas.
+4. Ler **`.oxe/STATE.md`**: capturar número de ondas, execute_mode usado, se houve loop, se houve escalação para forensics.
+5. Sintetizar **3–5 lições prescritivas** (não mais — qualidade sobre quantidade):
+   - Cada lição responde: "O que o próximo ciclo deve fazer diferente?"
+   - Formato: **Lição** (o que fazer) + **Raiz** (por que isso aconteceu) + **Tipo** + **Aplicar em**
+6. Determinar o próximo **ciclo ID** (C-NN) lendo `.oxe/LESSONS.md` existente ou começando em C-01.
+7. Criar ou atualizar **`.oxe/LESSONS.md`** usando `oxe/templates/LESSONS.template.md`:
+   - Adicionar linha na tabela de índice (mais recente primeiro).
+   - Adicionar seção `### C-NN` com as lições sintetizadas.
+   - **Nunca apagar** entradas anteriores — só mudar `Status: resolvido` se a lição foi superada.
+8. Atualizar **`.oxe/STATE.md`**: campo `last_retro: YYYY-MM-DD`.
+9. Responder no chat: ID do ciclo (C-NN), número de lições registradas, lição mais crítica em 1 frase, sugestão do próximo ciclo (`/oxe-scan` ou `/oxe-spec`).
+</process>
+
+<success_criteria>
+- [ ] `.oxe/LESSONS.md` existe com entrada C-NN na tabela e seção de detalhe.
+- [ ] Cada lição é prescritiva (diz o que fazer) não descritiva (não é só o que aconteceu).
+- [ ] 3–5 lições por ciclo — não um dump completo de eventos.
+- [ ] `STATE.md` tem `last_retro` atualizado.
+- [ ] Entradas anteriores preservadas; apenas `Status` pode mudar.
+</success_criteria>

package/oxe/workflows/spec.md

@@ -20,6 +20,7 @@ Ler no início:
 - `.oxe/STATE.md` — fase atual, decisões, workstream ativo
 - `.oxe/codebase/OVERVIEW.md` e `STACK.md` se existirem — não contradizer o repo
 - **`.oxe/OBSERVATIONS.md`** — se houver entradas `pendente` com impacto `spec` ou `all`, incorporá-las na Fase 3 (Requisitos) e marcá-las `incorporada → spec (data)` após uso
+- **`.oxe/LESSONS.md`** — se existir, ler entradas com `Aplicar em: spec` e status `ativo`. Usar como restrições explícitas ou alertas durante a Fase 1 (perguntas) e Fase 3 (requisitos). Exemplo: se uma lição diz "perguntar explicitamente sobre integração com X", adicionar essa pergunta no Bloco B da Fase 1.
 
 **Brownfield (COBOL, JCL, copybooks, VB6, SP):** quando o objetivo for documentar ou planear migração, ver **`oxe/workflows/references/legacy-brownfield.md`** — épicos por trilha, critérios A* verificáveis por Grep/leitura/checklist.
 
@@ -137,6 +138,30 @@ spec_ref: .oxe/SPEC.md
 ```
 </fase_4_roteiro>
 
+<auto_reflexao>
+## Auto-reflexão semântica (executa automaticamente antes da Fase 5)
+
+**Objetivo:** o agente critica a própria spec antes de apresentá-la ao usuário. Sem requisição extra — é um passe interno de qualidade semântica.
+
+Percorrer esta lista de verificação:
+
+| # | Verificação | Ação se falhar |
+|---|-------------|----------------|
+| 1 | **Contradições:** algum requisito v1 contradiz diretamente uma resposta da Fase 1? (ex.: usuário disse "sem auth" mas R4 implica sessões) | Voltar à Fase 3 e corrigir o requisito |
+| 2 | **Verificabilidade:** todo critério A* tem "Como verificar" executável sem acesso ao ambiente de produção do usuário? | Refinar para verificação possível no CI/agente ou marcar "verificação manual necessária" |
+| 3 | **Escopo creep:** algum requisito v1 foi adicionado que NÃO emergiu da Fase 1 nem da Fase 2? | Mover para v2 ou justificar inclusão em v1 |
+| 4 | **Conflito com stack:** algum requisito v1 pressupõe tecnologia ou capacidade que `STACK.md` indica ausente? (ex.: requer WebSocket mas stack usa REST puro) | Marcar como suposição explícita ou remover |
+| 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>
+
 <fase_5_aprovacao>
 ## Fase 5 — Aprovação e próximo passo
 
@@ -176,6 +201,7 @@ spec_ref: .oxe/SPEC.md
    - Frontmatter YAML (`oxe_doc: spec`, `status`, `updated`, `inputs`)
    - Objetivo, Escopo (dentro/fora), Critérios de aceite (tabela A*), Suposições e riscos, Referências
    - Preservar chaves existentes se SPEC.md já existir; atualizar `updated:`
+6b. **Auto-reflexão:** executar integralmente o bloco `<auto_reflexao>` antes de avançar. Corrigir a spec conforme necessário. Não apresentar a lista de verificação ao usuário — apenas a spec corrigida.
 7. **Fase 5 — Aprovação:** apresentar resumo, aguardar aprovação do roteiro, redirecionar.
 8. Atualizar **`.oxe/STATE.md`**: `phase: spec_ready`, próximo passo.
 9. Marcar OBS incorporadas em `.oxe/OBSERVATIONS.md` se houver pendentes de impacto `spec`.

package/oxe/workflows/verify.md

@@ -87,8 +87,9 @@ O preenchimento da checklist é responsabilidade do **usuário** (não do agente
    - **Checklist UAT** (Camada 4).
    - **Gaps** — o que falhou e sugestão de correção; se não houver, escrever `Nenhum gap restante`.
 6. Atualizar **`.oxe/STATE.md`**: `verify_complete` ou `verify_failed` + próximo passo (replan, corrigir ou publicar).
-6b. **Blueprint plan-agent:** se **todas** as verificações relevantes **passaram**, existir **`.oxe/plan-agents.json`** com `oxePlanAgentsSchema === 2` e `lifecycle.status === "executing"` (ou `pending_execute`), actualizar o JSON: `lifecycle: { "status": "closed", "since": "<ISO>" }` e espelhar em **`STATE.md`** (**lifecycle_status** → `closed`). Não fechar como `closed` se `verify_failed` ou gaps por resolver.
+6b. **Blueprint plan-agent:** se **todas** as verificações relevantes **passaram**, existir **`.oxe/plan-agents.json`** com `oxePlanAgentsSchema >= 2` e `lifecycle.status === "executing"` (ou `pending_execute`), actualizar o JSON: `lifecycle: { "status": "closed", "since": "<ISO>" }` e espelhar em **`STATE.md`** (**lifecycle_status** → `closed`). Não fechar como `closed` se `verify_failed` ou gaps por resolver.
 7. Acrescentar entrada em **`.oxe/SUMMARY.md`** (sessão): se não existir, criar a partir de **`oxe/templates/SUMMARY.template.md`**. **Obrigatório** quando `verify_failed` ou quando a seção **Gaps** tiver itens.
+7b. **Retrospectiva (pós-verify):** se `verify_complete`, sugerir **`/oxe-retro`** para capturar aprendizados do ciclo em `.oxe/LESSONS.md`. Especialmente importante quando: houve replanejamento (`--replan`), houve falhas em execute que precisaram de debug, critérios A* foram ajustados durante o ciclo, ou o ciclo durou mais de 2 ondas. Retro antes do próximo spec garante que lições orientem o próximo ciclo.
 7b. **Camada 5 — Validate-gaps automático:** se `verification_depth: "thorough"` em `.oxe/config.json`, executar a lógica de `oxe/workflows/validate-gaps.md` e adicionar seção **Gaps de Cobertura** ao VERIFY.md (mesmo conteúdo de VALIDATION-GAPS.md). Também escrever `.oxe/VALIDATION-GAPS.md` separado.
 7c. **Camada 6 — Security automático:** se `security_in_verify: true` em `.oxe/config.json`, executar a lógica de `oxe/workflows/security.md` e adicionar seção **Auditoria de Segurança** ao VERIFY.md. Também escrever `.oxe/SECURITY.md` separado. Achados P0 bloqueiam o `verify_complete` — registrar `verify_failed` até P0s serem resolvidos.
 8. **Só se todas as verificações relevantes passarem:** se `after_verify_draft_commit` não for `false`: acrescentar em **VERIFY.md** a seção **Rascunho de commit** — mensagem convencional (ex.: `feat:` / `fix:`) + bullets alinhados aos critérios **A*** e decisões **D-NN**; **não** incluir segredos.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oxe-cc",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "OXE — spec-driven workflows in .oxe/; integrates with Cursor, GitHub Copilot, Claude, OpenCode, Gemini, Codex, Windsurf, Antigravity (npx)",
   "license": "GPL-3.0",
   "author": "",