oxe-cc 0.6.0 → 0.6.4

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

@@ -1,50 +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>
+# 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/quick.md

@@ -140,7 +140,7 @@ No final de **`.oxe/QUICK.md`**, mantenha a linha:
 Se **sim**, o próximo passo recomendado no chat é **`/oxe-spec`** (depois discuss/plan conforme config).
 
 <process>
-1. Garantir `.oxe/` (usar template de STATE só se `STATE.md` não existir).
+1. Garantir `.oxe/` (usar template de STATE só se `STATE.md` não existir). Verificar **`.oxe/OBSERVATIONS.md`** — se houver entradas `pendente` com impacto `all`, registrar como restrições nos **Passos** ou no **Contexto** do QUICK.md antes de finalizar; marcar as OBS como `incorporada → quick (data)`.
 2. Avaliar se PDDA lean se aplica (ver `<plan_driven_dynamic_agents_lean>` — domínios distintos, 5+ passos, ou flag `--agents`).
 3. Criar ou substituir **`.oxe/QUICK.md`** com:
    - **Objetivo** — uma frase. *(Esta é a minispec: restringe o escopo de todos os agentes e passos.)*

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

@@ -1,61 +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>
+# 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

@@ -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.
@@ -103,4 +104,6 @@ O preenchimento da checklist é responsabilidade do **usuário** (não do agente
 - [ ] SUMMARY.md atualizado quando houver falha ou gaps relevantes.
 - [ ] Se passou: seções **Rascunho de commit** e **Checklist PR** presentes em VERIFY.md, salvo se desativadas na config.
 - [ ] Se existiu DISCUSS.md: tabela de Fidelidade de decisões preenchida sem divergências não documentadas.
+- [ ] Se `verification_depth: "thorough"` em config: `.oxe/VALIDATION-GAPS.md` produzido como parte deste verify.
+- [ ] Se `security_in_verify: true` em config: `.oxe/SECURITY.md` produzido; achados P0 resolvidos ou `verify_failed` registrado.
 </success_criteria>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oxe-cc",
-  "version": "0.6.0",
+  "version": "0.6.4",
   "description": "OXE — spec-driven workflows in .oxe/; integrates with Cursor, GitHub Copilot, Claude, OpenCode, Gemini, Codex, Windsurf, Antigravity (npx)",
   "license": "GPL-3.0",
   "author": "",
@@ -54,7 +54,7 @@
   ],
   "scripts": {
     "sync:cursor": "node scripts/sync-cursor-from-prompts.cjs",
-    "test": "node --test tests/install.test.cjs tests/oxe-project-health.test.cjs tests/oxe-sdk.test.cjs tests/oxe-manifest.test.cjs tests/oxe-agent-install.test.cjs tests/oxe-install-resolve-full.test.cjs tests/oxe-health-extended.test.cjs tests/oxe-workflows-edge.test.cjs tests/oxe-sdk-edge.test.cjs tests/oxe-cli-edge.test.cjs tests/oxe-npm-version.test.cjs tests/oxe-scripts.test.cjs",
+    "test": "node --test tests/install.test.cjs tests/oxe-project-health.test.cjs tests/oxe-sdk.test.cjs tests/oxe-manifest.test.cjs tests/oxe-agent-install.test.cjs tests/oxe-install-resolve-full.test.cjs tests/oxe-health-extended.test.cjs tests/oxe-workflows-edge.test.cjs tests/oxe-sdk-edge.test.cjs tests/oxe-cli-edge.test.cjs tests/oxe-npm-version.test.cjs tests/oxe-scripts.test.cjs tests/oxe-retro-health.test.cjs",
     "test:coverage": "c8 --check-coverage --lines 82 --functions 85 --branches 58 --statements 82 npm test",
     "scan:assets": "node scripts/oxe-assets-scan.cjs",
     "prepublishOnly": "node scripts/sync-cursor-from-prompts.cjs && npm test && npm run scan:assets && node bin/oxe-cc.js --version"