oxe-cc 0.5.0 → 0.6.2

package/oxe/workflows/plan-agent.md

@@ -22,7 +22,7 @@ Se o utilizador pedir **`--replan`**: aplicar a mesma lógica de replanejamento
   - **`sequential`** — uma onda por agente (ondas com um único id cada) ou execução estritamente ordenada.
   - **`parallel_per_wave`** — dentro de cada onda, agentes sem dependência mútua podem correr em paralelo; ondas são sequenciais.
   - **`hybrid`** — ondas sequenciais; dentro da onda, paralelo quando `dependencies` já satisfeitas (é o caso mais comum).
-- **Schema:** **`oxePlanAgentsSchema: 2`** obrigatório nas novas gerações; incluir **`runId`** (string opaca única, ex. `oxe-{ISO8601}-{6 hex aleatórios}`) e **`lifecycle`**: `{ "status": "pending_execute", "since": "<ISO>" }`. Blueprints com schema **1** (legado) não aplicam exclusividade estrita até serem regerados.
+- **Schema:** **`oxePlanAgentsSchema: 3`** obrigatório nas novas gerações (schema **2** = sem `model_hint`; schema **1** = legado sem `runId`/`lifecycle`). Incluir **`runId`** (string opaca única, ex. `oxe-{ISO8601}-{6 hex aleatórios}`) e **`lifecycle`**: `{ "status": "pending_execute", "since": "<ISO>" }`. Blueprints com schema **2** continuam válidos; schema **1** não aplica exclusividade estrita até serem regerados.
 - Modelo JSON: ver **`oxe/templates/plan-agents.template.json`** e **`oxe/schemas/plan-agents.schema.json`**.
 </context>
 
@@ -55,14 +55,30 @@ Se já existir `.oxe/plan-agents.json` com status não-terminal (`pending_execut
 Seguir **integralmente** o bloco **`<format_plan>`** e **`<plan_quality_gate>`** do ficheiro **`oxe/workflows/plan.md`** ao escrever `.oxe/PLAN.md` (incluindo gate antes de fechar).
 </format_plan_md>
 
+<model_hints>
+## Model Hints por Agente (schema v3, opcional)
+
+Cada agente pode declarar `model_hint` para orientar qual tier de modelo usar:
+
+| Valor | Quando usar |
+|-------|-------------|
+| `"powerful"` | Agentes de análise, arquitetura, pesquisa, decisões de design |
+| `"balanced"` | Agentes de implementação de features, integração, refactor |
+| `"fast"` | Agentes de review, testes, lint, validação, tarefas repetitivas |
+
+**Regra de uso:** quando o `plan-agents.json` tiver `model_hint`, o **`execute.md`** exibe a sugestão ao apresentar a atribuição do agente — permitindo ao usuário configurar o modelo antes de iniciar aquele agente.
+
+`model_hint` é opcional: omitir significa "sem preferência" (executa com o modelo padrão da sessão).
+</model_hints>
+
 <format_plan_agents_json>
 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). |
@@ -80,6 +96,7 @@ Cada **agente**:
 | `dependencies` | não | Lista de **`id`** de outros agentes que devem concluir antes (grafo entre agentes). |
 | `inputs` | não | Caminhos ou nomes de artefactos a carregar no contexto (ex.: `.oxe/STATE.md`, `.oxe/SPEC.md`). |
 | `outputs` | não | Paths ou padrões de ficheiros esperados (orientação; o código real vem do PLAN). |
+| `model_hint` | não | Tier de modelo sugerido: `"fast"` \| `"balanced"` \| `"powerful"`. Ver `<model_hints>`. |
 
 **Personas disponíveis:** `executor`, `planner`, `verifier`, `researcher`, `debugger`, `architect`, `ui-specialist`, `db-specialist`. Ver `oxe/personas/README.md` para descrição de cada uma. Personas customizadas do projeto ficam em `.oxe/personas/`.
 
@@ -89,7 +106,7 @@ Cada **agente**:
 <plan_agent_quality_gate>
 Antes de finalizar, validar **em conjunto** `PLAN.md` + `plan-agents.json`:
 
-1. **Schema:** JSON válido; `oxePlanAgentsSchema === 2`; presentes **`runId`** e **`lifecycle`** com `status: pending_execute` e `since` ISO; todos os `id` de agente únicos.
+1. **Schema:** JSON válido; `oxePlanAgentsSchema ∈ {2, 3}` (3 para novos blueprints); presentes **`runId`** e **`lifecycle`** com `status: pending_execute` e `since` ISO; todos os `id` de agente únicos. Se schema 3: `model_hint` de cada agente é `"fast"`, `"balanced"`, `"powerful"` ou ausente.
 2. **Cobertura de tarefas:** a união dos `taskIds` de todos os agentes é **igual** ao conjunto de `### Tn` presentes no `PLAN.md` (sem tarefa órfã nem tarefa duplicada entre agentes).
 3. **Dependências de agente:** só referenciam `id` existentes; **sem ciclos**; se o agente A depende de B, então **onda(B) < onda(A)** em `execution.waves` (primeira aparição do id define a onda).
 4. **Ondas:** cada `id` em `agents` aparece **exatamente uma vez** no total das `waves`; ordem das ondas reflete dependências e alinha com **Onda:** do `PLAN.md` (tarefas na mesma onda do PLAN podem mapear para agentes na mesma wave se não houver dependência agente-a-agente).
@@ -107,7 +124,7 @@ Resumo obrigatório no chat: `Gate plan-agent: OK` ou `Gate plan-agent: corrigid
 2. Conceber **agentes** e **ondas** (grafo por dependências de domínio); depois derivar **tarefas `Tn`** com o formato habitual do PLAN (uma tarefa continua a ser a unidade de **Verificar** e **Aceite vinculado**).
 3. Escrever **`.oxe/PLAN.md`** (cabeçalho YAML como em `oxe/templates/PLAN.template.md`; em **--replan**, secção Replanejamento).
 4. Gerar **`runId`** novo e **`lifecycle`**: `{ "status": "pending_execute", "since": "<ISO agora>" }`.
-5. Escrever **`.oxe/plan-agents.json`** a partir de **`oxe/templates/plan-agents.template.json`**, com **`oxePlanAgentsSchema: 2`**, `goal`, `agents`, `execution`, `runId`, `lifecycle`.
+5. Escrever **`.oxe/plan-agents.json`** a partir de **`oxe/templates/plan-agents.template.json`**, com **`oxePlanAgentsSchema: 3`**, `goal`, `agents` (incluindo `model_hint` por agente conforme `<model_hints>`), `execution`, `runId`, `lifecycle`.
 6. Criar **`.oxe/plan-agent-messages/`** e **`.oxe/plan-agent-messages/README.md`** a partir de **`oxe/templates/plan-agent-messages-README.template.md`**.
 7. Atualizar **`.oxe/STATE.md`**: fase `plan_ready`, próximo passo `oxe:execute`; preencher **Blueprint de agentes (sessão)** — `run_id` (= `runId`), `lifecycle_status` (= `pending_execute`), **última onda** — (ou `—`).
 8. Aplicar **`<plan_agent_quality_gate>`**; corrigir até passar.
@@ -116,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`.
 
@@ -73,7 +88,8 @@ Resumo obrigatório no chat: `Gate do plano: OK` ou `Gate do plano: corrigido (N
 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`: fase `plan_ready`, próximo passo `oxe:execute` (implementar ondas) e depois `oxe:verify`.
-9. Listar no chat: resultado do gate (OK ou corrigido), ondas, contagem de tarefas, comando de teste guarda-chuva se houver.
+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>
 
 <success_criteria>

package/oxe/workflows/project.md

@@ -0,0 +1,50 @@
+# OXE — Workflow: project (gestão de projeto)
+
+<objective>
+Ponto de entrada unificado para as três operações de gestão de projeto OXE:
+
+- **milestone** — marcos de entrega (M-NN): `new`, `complete`, `status`, `audit`
+- **workstream** — trilhas paralelas: `new <nome>`, `switch <nome>`, `list`, `close <nome>`
+- **checkpoint** — snapshot nomeado de sessão: `[slug]`
+
+Detecta a operação pelo primeiro token do input e delega ao workflow canônico correspondente.
+</objective>
+
+<context>
+- Este workflow é um **dispatcher**: lê o input, identifica a operação e executa o workflow correto.
+- Workflows canônicos: `oxe/workflows/milestone.md`, `oxe/workflows/workstream.md`, `oxe/workflows/checkpoint.md`.
+- Se o input for ambíguo, apresentar as 3 operações disponíveis e pedir escolha.
+- Sem input: mostrar o estado atual de milestones e workstreams ativos lendo `STATE.md`, `MILESTONES.md` e `CHECKPOINTS.md`.
+</context>
+
+<dispatch_table>
+| Input começa com | Delega para | Exemplos |
+|------------------|-------------|---------|
+| `milestone new ...` | `milestone.md` + subcomando `new` | `/oxe-project milestone new v1.0` |
+| `milestone complete` | `milestone.md` + subcomando `complete` | `/oxe-project milestone complete` |
+| `milestone status` | `milestone.md` + subcomando `status` | `/oxe-project milestone status` |
+| `milestone audit` | `milestone.md` + subcomando `audit` | `/oxe-project milestone audit` |
+| `workstream new <nome>` | `workstream.md` + subcomando `new` | `/oxe-project workstream new auth` |
+| `workstream switch <nome>` | `workstream.md` + subcomando `switch` | `/oxe-project workstream switch auth` |
+| `workstream list` | `workstream.md` + subcomando `list` | `/oxe-project workstream list` |
+| `workstream close <nome>` | `workstream.md` + subcomando `close` | `/oxe-project workstream close auth` |
+| `checkpoint [slug]` | `checkpoint.md` | `/oxe-project checkpoint pre-refactor` |
+| *(sem input)* | Status atual | `/oxe-project` |
+</dispatch_table>
+
+<process>
+1. Ler o input do usuário (texto após o comando).
+2. Identificar o primeiro token:
+   - `milestone` → carregar e executar `oxe/workflows/milestone.md` passando o restante como subcomando.
+   - `workstream` → carregar e executar `oxe/workflows/workstream.md` passando o restante como subcomando.
+   - `checkpoint` → carregar e executar `oxe/workflows/checkpoint.md` passando o slug (se houver).
+   - *(vazio)* → ler `STATE.md`, `MILESTONES.md` (se existir) e listar: milestone ativo (M-NN / nenhum), workstreams abertos, último checkpoint. Sugerir próxima operação.
+   - *(ambíguo)* → listar as 3 operações disponíveis com exemplos de uso.
+3. Executar o workflow delegado integralmente.
+</process>
+
+<success_criteria>
+- [ ] O workflow correto foi executado com base no input.
+- [ ] Sem input: STATUS atual de milestone ativo, workstreams e último checkpoint mostrado.
+- [ ] Input ambíguo: máximo 3 opções apresentadas com exemplos, não listas longas.
+</success_criteria>

package/oxe/workflows/research.md

@@ -16,6 +16,22 @@ Não substitui **SPEC** nem **PLAN**; alimenta decisões que depois entram na SP
 - Segurança: não gravar segredos nem valores de variáveis de ambiente.
 </context>
 
+<thinking_depth>
+## Profundidade de Raciocínio
+
+Antes de iniciar a pesquisa, classificar o tipo de investigação e calibrar a profundidade:
+
+| Tipo | Indicadores | Abordagem |
+|------|-------------|-----------|
+| `surface` | Coletar fatos, comparar 2-3 opções conhecidas, confirmar API | Pesquisa padrão — fontes diretas, resposta objetiva |
+| `standard` | Análise de trade-offs, integração de sistemas, avaliação de bibliotecas | Evidências múltiplas, prós/contras explícitos, referências cruzadas |
+| `deep` | Reverse engineering de sistema existente, design de arquitetura nova, migração complexa, brownfield | **Extended thinking recomendado** se o modelo suportar — ativar raciocínio estendido antes de produzir a nota |
+
+Anotar `thinking_depth: surface | standard | deep` no frontmatter da nota de pesquisa gerada.
+
+**Quando `deep`:** instrua o modelo (explicitamente se necessário) a "raciocinar em profundidade antes de escrever a nota" — explorando hipóteses, descartando alternativas, mapeando incertezas antes de consolidar evidências.
+</thinking_depth>
+
 <process>
 1. Garantir pastas `.oxe/` e `.oxe/research/`.
 2. Escolher `YYYY-MM-DD-<slug>.md` único; se colisão, acrescentar sufixo ao slug (ex. `-b`).

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

@@ -18,6 +18,20 @@ Se **`.oxe/config.json`** tiver `scan_focus_globs` ou `scan_ignore_globs`, **pri
 
 </context>
 
+<mode_detection>
+## Detecção automática de modo: bootstrap vs refresh
+
+Antes de iniciar, verificar se `.oxe/codebase/` já existe com os sete mapas:
+
+- **Modo bootstrap** (padrão quando codebase/ não existe ou está incompleto): produzir os sete arquivos do zero. Comportamento descrito no `<process>` abaixo.
+- **Modo refresh** (quando codebase/ existe e tem os sete mapas): executar a lógica de `oxe/workflows/compact.md` — comparar mapas existentes ao repo atual, atualizar incrementalmente, produzir `CODEBASE-DELTA.md` e `RESUME.md`. **Não refazer do zero.**
+
+Flag `--full`: forçar modo bootstrap mesmo se codebase/ existir.
+Flag `--refresh`: forçar modo refresh.
+
+**Sem flag:** automático por contexto. Se os mapas existem e o último scan foi há menos de `scan_max_age_days` (config), sugerir refresh mas perguntar ao usuário antes de executar o scan completo.
+</mode_detection>
+
 <process>
 1. Garantir pastas `.oxe/` e `.oxe/codebase/`.
 2. Inventariar o repo (Glob/Grep): linguagens, manifests (`package.json`, `pom.xml`, `go.mod`, etc.), pastas principais — aplicando foco/ignore da config se houver.

package/oxe/workflows/security.md

@@ -0,0 +1,61 @@
+# OXE — Workflow: security (auditoria de segurança)
+
+<objective>
+Produzir **`.oxe/SECURITY.md`**: auditoria de segurança do repositório focada nas categorias OWASP Top 10 **relevantes** ao stack do projeto. Complementa **`validate-gaps`** (cobertura de testes) com uma camada de segurança aplicativa.
+
+Pode ser chamado standalone ou como Camada 5 do **`verify.md`** quando `config.json` tiver `"security_in_verify": true`.
+
+Não substitui ferramentas de análise estática (SAST) — identifica padrões de risco no código e na configuração a partir do contexto disponível no repositório.
+</objective>
+
+<context>
+- **Fonte de stack:** `.oxe/codebase/STACK.md` determina quais categorias OWASP são pertinentes (ex.: app sem DB descarta A03:Injection-SQL; API sem auth descarta A07:Authentication).
+- **Fontes de código:** `.oxe/codebase/STRUCTURE.md`, `.oxe/codebase/CONCERNS.md`, `.oxe/codebase/INTEGRATIONS.md` orientam quais arquivos focar.
+- **Severidade:** P0 = crítico (exploração provável, impacto direto), P1 = alto (requer mitigação antes do próximo deploy), P2 = médio (risco aceitável com compensação documentada).
+- **Saída de tarefas:** recomendações vinculadas a `Tn` existentes no PLAN.md (se disponível) ou como sugestões de novas tarefas `T_new`.
+- **Integração com verify:** se `security_in_verify: true` em `.oxe/config.json`, o workflow `verify.md` inclui referência a este output como Camada 5. O `security.md` continua sendo o workflow canônico.
+- **Não alterar código:** apenas auditar e registrar achados. Nenhum arquivo de código é modificado.
+</context>
+
+<owasp_scope>
+## Mapeamento OWASP → Stack
+
+Antes de auditar, determinar quais categorias se aplicam lendo `STACK.md` e `INTEGRATIONS.md`:
+
+| Categoria OWASP | Aplicável quando |
+|-----------------|-----------------|
+| A01 — Broken Access Control | App com autenticação/autorização ou rotas protegidas |
+| A02 — Cryptographic Failures | Dados sensíveis em trânsito ou em repouso; senhas; tokens |
+| A03 — Injection | DB queries, shell commands, parsers de entrada, templates |
+| A04 — Insecure Design | Ausência de modelagem de ameaças; fluxos de negócio sem validação |
+| A05 — Security Misconfiguration | Config de servidor, CORS, headers HTTP, variáveis de ambiente |
+| A06 — Vulnerable Components | Dependências com CVEs conhecidos; versões sem suporte |
+| A07 — Authentication Failures | Login, sessão, JWT, OAuth, tokens de reset |
+| A08 — Software Integrity | Supply chain; checksums; CI/CD sem verificação |
+| A09 — Logging & Monitoring | Ausência de logs de eventos críticos; dados sensíveis em logs |
+| A10 — SSRF | Requisições a URLs controladas pelo usuário; fetch/proxy interno |
+
+**Selecionar apenas as categorias aplicáveis** ao stack identificado. Listar explicitamente as ignoradas e o motivo.
+</owasp_scope>
+
+<process>
+1. Ler `.oxe/codebase/STACK.md`, `.oxe/codebase/STRUCTURE.md`, `.oxe/codebase/INTEGRATIONS.md`, `.oxe/codebase/CONCERNS.md`.
+2. Selecionar categorias OWASP aplicáveis ao stack (ver `<owasp_scope>`); registrar as descartadas.
+3. Para cada categoria aplicável:
+   a. Identificar **arquivos críticos** (auth, input handlers, DB queries, configs, env, deps).
+   b. Ler os arquivos relevantes (Glob, Grep, Read) procurando padrões de risco.
+   c. Registrar achados com: localização (`path:linha`), padrão encontrado, severidade (P0/P1/P2), recomendação.
+4. Ler `.oxe/PLAN.md` se existir — vincular achados P0/P1 a tarefas `Tn` existentes quando possível, ou criar sugestão `T_new`.
+5. Escrever `.oxe/SECURITY.md` a partir de `oxe/templates/SECURITY.template.md`.
+6. Atualizar `.oxe/STATE.md`: nota de segurança (ex.: `security_audit: YYYY-MM-DD | P0:N | P1:N | P2:N`).
+7. Responder no chat: total de achados por severidade, arquivos mais críticos identificados, próximo passo (P0 presentes → bloquear deploy; apenas P2 → ação opcional).
+</process>
+
+<success_criteria>
+- [ ] `.oxe/SECURITY.md` existe com categorias OWASP selecionadas e justificativa de descarte.
+- [ ] Cada achado tem: localização, padrão, severidade, recomendação.
+- [ ] Categorias sem achados registradas como "nenhum achado nesta categoria".
+- [ ] Achados P0/P1 vinculados a `Tn` existente ou sugestão `T_new`.
+- [ ] Nenhum arquivo de código foi modificado.
+- [ ] STATE.md tem linha `security_audit` com data e contagem de achados.
+</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

@@ -21,8 +21,9 @@ Se o usuário indicar uma tarefa (ex.: `T2`), focar só nela nas camadas 1–2;
 - **Legado:** quando **Comando** for `—` ou inexistente, evidência válida inclui **Read/Grep**, existência de ficheiros referenciados e checklist manual — não marcar critério como passou sem evidência; se o ambiente host/desktop não estiver disponível, registar **não executado aqui** e próximo passo. Ver **`oxe/workflows/references/legacy-brownfield.md`**.
 - **Debug:** investigação técnica de falhas **durante** a implementação segue **`oxe/workflows/debug.md`** (`/oxe-debug`). Resolver um bug com debug **não** dispensa este passo — após correções, **ainda** é necessário **`verify`** para fechar a trilha face à SPEC/PLAN.
 - **UI:** se existirem `.oxe/UI-SPEC.md` / `.oxe/UI-REVIEW.md`, incorporar na evidência quando os critérios **A*** ou tarefas **Tn** tocarem interface.
-- **Pós-verify (opcional):** para auditoria de **cobertura** e gaps de verificabilidade, **`oxe:validate-gaps`** → `.oxe/VALIDATION-GAPS.md` (ver **`oxe/workflows/validate-gaps.md`**). Com `verification_depth: "thorough"`, sugerir proativamente.
-- **Rotina compact/checkpoint (opcional):** se esta entrega alterou **estrutura**, **stack** ou **pastas** de forma relevante, sugira **`/oxe-compact`** para alinhar `.oxe/codebase/` ao repo. Após **verify** com sucesso, um **`/oxe-checkpoint`** com slug curto pode marcar estado estável.
+- **Camada 5 — Validate-gaps (automático quando `verification_depth: "thorough"`):** após as 4 camadas, se `verification_depth: "thorough"` em `.oxe/config.json`, executar automaticamente a lógica de `oxe/workflows/validate-gaps.md` e produzir `.oxe/VALIDATION-GAPS.md` como parte deste verify. Não requer comando separado.
+- **Camada 6 — Security (automático quando `security_in_verify: true`):** se `security_in_verify: true` em `.oxe/config.json`, executar automaticamente a lógica de `oxe/workflows/security.md` e produzir `.oxe/SECURITY.md` como parte deste verify. Não requer comando separado.
+- **Rotina compact/checkpoint (opcional):** se esta entrega alterou **estrutura**, **stack** ou **pastas** de forma relevante, `/oxe-scan` em modo refresh alinha `.oxe/codebase/` ao repo. Após **verify** com sucesso, `/oxe-project checkpoint` com slug curto pode marcar estado estável.
 </context>
 
 <camada_1_pre_exec_audit>
@@ -86,8 +87,11 @@ 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.
 9. **Só se passou:** se `after_verify_suggest_pr` não for `false`: acrescentar **Checklist PR** — branch base, título sugerido, screenshots se UI, links a SPEC/PLAN/DISCUSS, testes executados.
 </process>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oxe-cc",
-  "version": "0.5.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": "",