oxe-cc 0.3.9 → 0.6.0

package/oxe/workflows/execute.md

@@ -1,47 +1,152 @@
 # OXE — Workflow: execute
 
 <objective>
-Guiar a **implementação por ondas** com base em **`.oxe/PLAN.md`**, atualizando **`.oxe/STATE.md`** com progresso (tarefas Tn). Não substitui o editor: estrutura o trabalho e confirma pré-requisitos antes de cada onda.
+Guiar a **implementação** de um plano OXE com dois modos possíveis:
 
-Se existir apenas **`.oxe/QUICK.md`** (fluxo quick), tratar os **Passos** numerados como lista única “onda 1” em vez de tarefas T1…Tn.
+**Modo Solo (padrão):** seguir `.oxe/PLAN.md` onda a onda sem `plan-agents.json`. O agente implementa diretamente cada tarefa Tn da onda atual, roda a verificação e avança. Não exige nenhum artefato além do PLAN.md.
+
+**Modo com Agentes (extensão):** quando existe `.oxe/plan-agents.json` válido (schema 2, lifecycle ativo, runId alinhado ao STATE), adotar roles e personas por agente conforme o blueprint.
+
+**Seleção de execução (redução de requisições):** quando o plano tem 2+ ondas, o usuário escolhe entre Completo (1 sessão), Por onda (N sessões) ou Por tarefa (N tarefas). A escolha é feita **uma vez** no início.
+
+Se existir apenas **`.oxe/QUICK.md`**: tratar passos numerados como onda única (modo sempre Completo).
 </objective>
 
+<modo_solo>
+## Modo Solo — Execução direta do PLAN.md
+
+O modo padrão. Funciona sem `plan-agents.json`. O agente lê PLAN.md, segue as tarefas Tn na ordem das ondas, implementa e verifica.
+
+**Checklist de onda (solo):**
+```markdown
+## Checklist — Onda N (OXE Solo)
+- [ ] Dependências da onda conferidas (Tk de ondas anteriores concluídos)
+- [ ] Tarefas da onda implementadas
+- [ ] Comando **Verificar** de cada tarefa executado (ou agendado)
+- [ ] STATE.md atualizado com progresso
+```
+
+**Ao fechar todas as ondas:** sugerir `/oxe-verify` para validação completa contra SPEC.
+</modo_solo>
+
+<execution_mode_selection>
+## Seleção de Modo de Execução
+
+**Quando aplicar:** ao início do execute, se PLAN.md tiver **2 ou mais ondas**. Apresentar UMA VEZ e armazenar a escolha em STATE.md para não perguntar novamente nas rodadas seguintes.
+
+**Não aplicar** quando: QUICK.md (sempre Completo), PLAN.md com 1 onda (executar diretamente).
+
+**Apresentar ao usuário:**
+
+```
+Este plano tem [N] tarefas em [X] ondas. Como quer executar?
+
+  A) Completo   → todas as [X] ondas nesta sessão
+                  ✓ 1 requisição/sessão (ideal: Copilot, Claude, Gemini)
+                  ✓ O agente vê todo o contexto e pode otimizar entre tarefas
+                  ⚠ Verificação inline — sem pausa entre ondas
+
+  B) Por onda   → onda 1/[X] agora, você verifica e chama de novo para continuar
+                  ✓ Validação entre ondas reduz risco de retrabalho
+                  ✗ [X] sessões (uma por onda)
+
+  C) Por tarefa → T1 agora, você confirma, depois T2...
+                  ✓ Máximo controle
+                  ✗ [N] sessões (uma por tarefa)
+```
+
+**Modo A — Completo:**
+- Executar onda 1 → verificar → onda 2 → verificar → … → última onda
+- A cada onda: executar o comando `**Verificar:**` de cada tarefa inline
+- Atualizar STATE.md progressivamente (não esperar o final)
+- Ao terminar: suário recebe sumário completo + sugestão de `/oxe-verify`
+
+**Modo B — Por onda (padrão quando sem escolha):**
+- Executar onda atual → apresentar checklist → parar
+- Informar: "Onda N/X concluída. Chame `/oxe-execute` novamente para a Onda N+1."
+
+**Modo C — Por tarefa:**
+- Executar próxima tarefa pendente → parar
+- Informar: "T[n] concluída. Chame `/oxe-execute` novamente para T[n+1]."
+
+**Persistir escolha:** registrar em STATE.md: `execute_mode: completo | por_onda | por_tarefa`. Se STATE já tiver o campo, não perguntar novamente — usar o modo armazenado.
+</execution_mode_selection>
+
+<failure_mode>
+## Modo de falha inline (Verificar falha durante execute)
+
+Quando o comando `**Verificar:**` de uma tarefa `Tn` falha, **não parar silenciosamente**. Executar este ciclo inline sem exigir que o usuário chame `/oxe-debug` separadamente:
+
+1. **Diagnóstico rápido:** listar 2-3 hipóteses de causa baseadas no output de erro.
+2. **Fix mais provável:** aplicar o fix para a hipótese #1.
+3. **Re-verificar:** rodar o `Verificar` novamente.
+4. Se passou: continuar onda normalmente; registrar na onda que houve 1 iteração de fix.
+5. Se falhou novamente (2ª tentativa): aplicar hipótese #2 e tentar 1 vez mais.
+6. Se falhou após 2 tentativas: **pausar** — exibir as hipóteses testadas, evidências coletadas, e sugerir `/oxe-forensics` com contexto completo. Registrar em STATE.md: `execute_blocked: Tn | motivo`.
+
+**Auto-loop no Modo B:** se `execute_mode: por_onda` e `loop_max` > 1 em STATE.md, o ciclo de retry roda automaticamente até `loop_max` tentativas antes de escalar para forensics.
+</failure_mode>
+
 <context>
-- **Blueprint plan-agent (schema 2):** Só adoptar **`role` / `scope`** de **`.oxe/plan-agents.json`** quando **todas** se verificam:
-  1. `lifecycle.status` ∈ `{ pending_execute, executing }` (não usar se `closed` ou `invalidated`).
-  2. **`runId`** no JSON coincide com **`run_id`** na secção **Blueprint de agentes (sessão)** do **`.oxe/STATE.md`** (se `STATE` não tiver secção, tratar como mismatch e **não** usar persona do blueprint até alinhar ou rerodar **`/oxe-plan-agent`**).
-  3. O pedido do utilizador mapeia para pelo menos uma tarefa **`Tn`** presente no **`.oxe/PLAN.md`** (ou explícita na onda em curso). Se o pedido for **fora** do conjunto de tarefas do plano: responder **sem** persona do blueprint; sugerir **`/oxe-plan`**, **`/oxe-plan-agent`** ou **`/oxe-quick`**; só actualizar `lifecycle` para `invalidated` com `invalidatedBy: out_of_scope` se o utilizador **confirmar** explicitamente.
-- **Transição `pending_execute` → `executing`:** na **primeira** mensagem deste workflow que avança uma onda com blueprint válido, actualizar **`plan-agents.json`** → `lifecycle: { "status": "executing", "since": "<ISO>" }` e espelhar em **`STATE.md`** (**lifecycle_status** / **run_id**).
-- **Protocolo agente → agente:** entre ondas ou agentes dependentes, escrever mensagens em **`.oxe/plan-agent-messages/`** conforme **`oxe/workflows/references/plan-agent-chat-protocol.md`** (ficheiros imutáveis com `runId` no frontmatter). Antes de um agente destinatário trabalhar, ler mensagens dirigidas a esse `id` (ou `broadcast`) com o mesmo `runId`.
-- Se existir **`.oxe/plan-agents.json`** e as condições acima se cumprirem, usar o blueprint como **roteiro de execução por agente**: para cada **onda** em `execution.waves`, listar os **agentes** (papel, `scope`, `inputs` sugeridos) e as **`taskIds`** correspondentes no **PLAN.md**; tarefas da mesma onda do PLAN que caem no mesmo agente podem ser feitas no mesmo contexto focado. O **comando Verificar** e as dependências **`Tk`** continuam a vir **só** do `PLAN.md` (fonte de verdade OXE).
-- **Schema 1 / legado** (sem `lifecycle`): pode usar o JSON apenas como **roteiro suave** (lista de agentes/ondas), **sem** garantir exclusividade nem protocolo estrito até **`/oxe-plan-agent`** regerar schema 2.
-- Se **PLAN.md** não existir mas **QUICK.md** existir, seguir **QUICK.md** neste workflow (passos = trabalho da sessão).
-- Se nem PLAN nem QUICK existir, recomendar `oxe:plan` ou `oxe:quick` primeiro.
-- **Legado / brownfield:** entregáveis podem ser só documentação (`.md`, diagramas). Exigir pré-requisitos de ambiente (mainframe, IDE VB6) quando a tarefa depender disso — ver **`oxe/workflows/references/legacy-brownfield.md`**.
-- **Rotina compact/checkpoint (opcional):** antes de uma onda **experimental** ou refactor que mude muito o layout, **`/oxe-checkpoint`** com slug (ex.: `antes-refactor-modulo-x`) ajuda a retomar. Depois de ondas que mudem **stack** ou **árvore** do projeto, lembrar **`/oxe-compact`** para não deixar `.oxe/codebase/` desatualizado face ao código — **não** substitui o checklist da onda nem o **Verificar** do PLAN.
+**Observações pendentes:** verificar `.oxe/OBSERVATIONS.md` no início de cada onda. Se houver entradas `pendente` com impacto `execute` ou `all`, incorporar no trabalho da onda atual e marcá-las `incorporada → execute (data)`.
+
+**Quick-agents (lean PDDA):** se existir **`.oxe/quick-agents.json`** com `status: active` e a execução for baseada em **`QUICK.md`** (não há PLAN.md), adotar o `role` e `persona` de cada agente para os `steps[]` atribuídos. Ao concluir todos os steps, marcar `quick-agents.json` → `status: done` e sugerir `/oxe-verify`.
+
+**Model hints (blueprint com agentes):** ao apresentar a atribuição de cada agente no início da onda, exibir `model_hint` se presente:
+```
+Agente: agent-auth — "Especialista em JWT"  [modelo: powerful]
+Tarefas: T1, T2
+```
+Se `model_hint` estiver ausente, não exibir a linha. O usuário pode configurar o modelo no IDE antes de iniciar aquele agente.
+
+**Blueprint plan-agent (Modo com Agentes):** adotar `role`/`scope` de **`.oxe/plan-agents.json`** SOMENTE quando:
+1. `lifecycle.status` ∈ `{ pending_execute, executing }` (não usar se `closed` ou `invalidated`).
+2. **`runId`** no JSON coincide com **`run_id`** no STATE.md (secção Blueprint de agentes).
+3. O pedido mapeia para pelo menos uma tarefa **`Tn`** no **`PLAN.md`**.
+
+Se condições não atendidas: responder sem persona; sugerir `/oxe-plan-agent` para novo blueprint.
+
+**Transição `pending_execute` → `executing`:** na primeira onda com blueprint válido, atualizar `plan-agents.json` → `lifecycle: { "status": "executing", "since": "<ISO>" }` e espelhar em STATE.md.
+
+**Protocolo agente → agente (blueprint):** mensagens em `.oxe/plan-agent-messages/` conforme `oxe/workflows/references/plan-agent-chat-protocol.md`.
+
+**Se PLAN.md não existir mas QUICK.md existir:** seguir QUICK.md — passos = onda única, sempre Modo Completo.
+
+**Se nem PLAN nem QUICK existir:** recomendar `oxe:plan` ou `oxe:quick` primeiro.
+
+**Legado / brownfield:** entregáveis podem ser só documentação. Ver **`oxe/workflows/references/legacy-brownfield.md`**.
+
+**Rotina compact/checkpoint:** antes de onda experimental ou refactor grande, `/oxe-checkpoint` com slug ajuda a retomar. Após ondas que mudem stack ou árvore, lembrar `/oxe-compact`.
 </context>
 
 <process>
-1. Ler `.oxe/STATE.md`, `PLAN.md` (se existir) e `QUICK.md` (se PLAN não existir).
-2. Identificar **onda atual** (ou próxima): no PLAN, todas as tarefas da mesma **Onda** sem dependências pendentes; no QUICK, os passos ainda não marcados como feitos (se STATE não indicar, assumir desde o início).
-3. Listar no chat: tarefas/passos desta onda, arquivos prováveis, comando **Verificar** associado (do PLAN ou do QUICK).
-4. Incluir no final da mensagem (ou pedir atualização no `STATE.md`) um bloco **Checklist da onda** em Markdown, para o usuário ou o agente marcar:
+1. Ler **`.oxe/STATE.md`**, **`PLAN.md`** (se existir) e **`QUICK.md`** (se PLAN não existir).
+2. Verificar **`.oxe/OBSERVATIONS.md`** — incorporar pendentes de impacto `execute` ou `all` antes de iniciar.
+3. **Seleção de modo** (apenas se PLAN.md com 2+ ondas e `execute_mode` não definido em STATE): apresentar opções A/B/C e aguardar escolha; registrar em STATE.md.
+4. Identificar **onda ou bloco atual**: no PLAN, todas as tarefas da mesma onda sem dependências pendentes; no QUICK, passos ainda não marcados como feitos.
+5. Listar no chat: tarefas/passos desta onda, arquivos prováveis, comando **Verificar** de cada tarefa.
+6. **Implementar** conforme o modo escolhido:
+   - **Modo Completo:** executar todas as ondas em sequência com verificação inline entre ondas; sumarizar ao final.
+   - **Modo Por onda:** executar onda atual, apresentar checklist, parar.
+   - **Modo Por tarefa:** executar próxima tarefa pendente, parar.
+7. Após cada onda concluída, incluir checklist:
    ```markdown
    ## Checklist — Onda N (OXE)
-   - [ ] Pré-requisitos da onda conferidos (dependências T* atendidas)
+   - [ ] Pré-requisitos da onda conferidos (dependências Tk atendidas)
    - [ ] Implementação da onda concluída
-   - [ ] Comando **Verificar** desta onda executado (ou agendado)
+   - [ ] Comando Verificar de cada tarefa executado (ou agendado)
    ```
-5. Após o usuário confirmar que a onda foi implementada (ou após você aplicar as mudanças), atualizar **`.oxe/STATE.md`**:
-   - Marcar no checklist acima (ou em bullets) **Última onda executada**, **Tarefas concluídas** (Tn ou números dos passos).
-   - Próximo passo: continuar próxima onda, `oxe:verify` (se todas as ondas terminadas), ou `oxe:plan` se o plano ficou obsoleto.
-6. Se o PLAN tiver várias ondas, repetir execute por onda sob pedido; não apagar tarefas do PLAN.
+8. Atualizar **`.oxe/STATE.md`**: última onda executada, tarefas concluídas (Tn), próximo passo.
+9. Marcar OBS incorporadas como `incorporada → execute (data)` em `.oxe/OBSERVATIONS.md`.
 </process>
 
 <success_criteria>
-- [ ] Onda ou bloco de passos está explícito antes de “implementar”.
-- [ ] Checklist da onda foi apresentado ou refletido no `STATE.md`.
-- [ ] `STATE.md` registra progresso (Tn ou passos) e próximo passo.
+- [ ] Modo de execução foi selecionado (ou herdado do STATE) antes de implementar.
+- [ ] Onda ou bloco de passos explicitado antes de "implementar".
+- [ ] Checklist da onda apresentado ou refletido no STATE.md.
+- [ ] STATE.md registra progresso (Tn ou passos) e próximo passo.
 - [ ] Verificação alinhada ao bloco **Verificar** do PLAN ou QUICK.
-- [ ] Com blueprint schema 2 válido: não adoptar persona do JSON para pedidos fora das `Tn`; `runId` alinhado entre JSON e STATE; handoffs escritos quando o protocolo exige (**`references/plan-agent-chat-protocol.md`**).
+- [ ] OBS pendentes de impacto `execute` incorporadas no início da onda.
+- [ ] Com quick-agents ativos: cada agente trabalha só em seus `steps[]`; ao concluir, `quick-agents.json` → `done`.
+- [ ] Com blueprint schema 2 válido: não adotar persona para pedidos fora das `Tn`; `runId` alinhado entre JSON e STATE; handoffs escritos quando protocolo exige.
 </success_criteria>

package/oxe/workflows/help.md

@@ -11,11 +11,30 @@ No **projeto**, os passos canónicos estão em **`.oxe/workflows/*.md`** (layout
 </context>
 
 <output>
+## Os 8 comandos essenciais
+
+```
+/oxe              → onde estou / o que faço / help (entrada universal)
+/oxe-obs          → registrei algo importante — incorporado automaticamente nos próximos passos
+/oxe-quick        → tarefa pequena, sem cerimônia (com agentes lean quando necessário)
+/oxe-scan         → mapeia o projeto (ou atualiza o mapa se já existir)
+/oxe-spec         → nova feature: perguntas → pesquisa → requisitos → roteiro → aprovação
+/oxe-plan         → tarefas por onda (--agents para blueprint multi-agente)
+/oxe-execute      → implementar (A: 1 sessão | B: por onda | C: por tarefa)
+/oxe-verify       → validar (camadas 5+6 opcionais via config: gaps + segurança)
+```
+
+Tudo o mais é ativado automaticamente por contexto, por config, ou existe como escape hatch.
+
+---
+
 ## Integrações principais (referência)
 
 ### Cursor
 
-Slash commands: `/oxe-scan`, `/oxe-spec`, `/oxe-discuss`, `/oxe-plan`, `/oxe-plan-agent`, `/oxe-verify`, `/oxe-next`, `/oxe-quick`, `/oxe-execute`, `/oxe-update`, `/oxe-help`, `/oxe-forensics`, `/oxe-debug`, `/oxe-route`, `/oxe-research`, `/oxe-validate-gaps`, `/oxe-compact`, `/oxe-checkpoint`, `/oxe-ui-spec`, `/oxe-ui-review` (instalados em `~/.cursor/commands/` pelo `oxe-cc` após `npm run sync:cursor` no pacote ou cópia equivalente). **Review de PR:** no Cursor não há slash dedicado — peça em linguagem natural seguindo `oxe/workflows/review-pr.md` (ou `.oxe/workflows/review-pr.md`) em contexto.
+Slash commands essenciais: `/oxe`, `/oxe-obs`, `/oxe-quick`, `/oxe-scan`, `/oxe-spec`, `/oxe-plan`, `/oxe-execute`, `/oxe-verify`
+
+Slash commands completos: `/oxe-discuss`, `/oxe-plan-agent`, `/oxe-project`, `/oxe-loop`, `/oxe-security`, `/oxe-update`, `/oxe-forensics`, `/oxe-debug`, `/oxe-route`, `/oxe-research`, `/oxe-validate-gaps`, `/oxe-compact`, `/oxe-checkpoint`, `/oxe-ui-spec`, `/oxe-ui-review`, `/oxe-milestone`, `/oxe-workstream`, `/oxe-next`, `/oxe-help` (instalados em `~/.cursor/commands/` pelo `oxe-cc`). **Review de PR:** no Cursor não há slash dedicado — peça em linguagem natural seguindo `oxe/workflows/review-pr.md` em contexto.
 
 ### GitHub Copilot (VS Code)
 
@@ -49,37 +68,47 @@ Com **`compact_max_age_days`** em `.oxe/config.json` (ver `oxe/templates/CONFIG.
 
 ## Fluxo completo
 
-1. **scan** — após clonar ou quando o repositório mudar muito. Repositórios **legado** (COBOL, JCL, copybooks, VB6, SQL procedures): o passo **scan** aplica `oxe/workflows/references/legacy-brownfield.md` quando esses sinais existirem — preencha `TESTING.md` com honestidade (sem `npm test` fictício) e use `scan_focus_globs` em `.oxe/config.json` (ver `oxe/templates/CONFIG.md`).
-2. **spec** — descrever o que se quer (critérios com IDs **A1**, **A2**…).
-2b. **research** (opcional) — notas datadas em `.oxe/research/` + índice `.oxe/RESEARCH.md`; spikes, mapa de sistema, engenharia reversa, hipóteses de modernização, ou qualquer exploração antes do plano (ver `research.md`).
-3. **discuss** (opcional) — decisões antes do plano; recomendado se `discuss_before_plan` em `.oxe/config.json`.
-4. **plan** — plano executável + **Verificar** por tarefa, ligado aos critérios da SPEC.
-4b. **plan-agent** (opcional) — igual ao **plan** + **`.oxe/plan-agents.json`** (schema **2**: `runId`, `lifecycle`) e pasta **`.oxe/plan-agent-messages/`** para handoffs entre agentes do blueprint (**`oxe/workflows/references/plan-agent-chat-protocol.md`**). Os papéis (`role` / `scope`) são **exclusivos** da trilha **PLAN + `/oxe-execute`** com esse `runId`; **`/oxe-quick`** invalida o blueprint (`lifecycle.invalidated`).
-5. **execute** (opcional) — onda a onda com base no PLAN (ou passos do QUICK); com blueprint válido, seguir protocolo de mensagens entre ondas/agentes dependentes.
-6. Implementar mudanças no agente/editor.
-7. **verify** — validar tarefas **e** critérios SPEC antes de merge/PR.
-7b. **validate-gaps** (opcional) — após verify, auditoria de cobertura em `.oxe/VALIDATION-GAPS.md` (gaps de teste/evidência; sugestões de tarefas em texto; ver `validate-gaps.md`).
-8. **next** — retomar trabalho; no terminal: **`npx oxe-cc status`** sugere um único próximo passo (mais leve que **`doctor`**, que valida também workflows do pacote e regras estritas).
+0. **obs** *(qualquer momento)* — `/oxe-obs` registra uma observação contextual; incorporada automaticamente no próximo spec/plan/execute sem re-explicar.
+1. **scan** — após clonar ou quando o codebase mudar. **Inteligente:** se `.oxe/codebase/` já existir, opera em modo refresh (incremental) automaticamente — sem precisar chamar `/oxe-compact` separadamente. Use `--full` para forçar scan completo. Repositórios **legado** (COBOL, JCL, VB6): aplica `legacy-brownfield.md` automaticamente.
+2. **spec** — fluxo em **5 fases**: perguntas (máx 3 rodadas) → pesquisa (proposta inline na Fase 2, sem sair do spec) → requisitos R-ID (v1/v2/fora) → roteiro (`.oxe/ROADMAP.md`) → aprovação. Se `discuss_before_plan: true` na config, o próximo passo após aprovação é `oxe:discuss` antes de plan.
+3. **plan** — plano executável + **Verificar** por tarefa. Se 3+ domínios distintos, **sugere automaticamente** blueprint de agentes (`/oxe-plan --agents`). Sem `--agents`: solo. Com `--agents`: gera também `plan-agents.json` (schema 3 com `model_hint`).
+4. **execute** — modo selecionado 1 vez: **A) Completo** (1 sessão), **B) Por onda**, **C) Por tarefa**. Se Verificar falhar inline: diagnóstico automático (2-3 hipóteses + fix), sem precisar chamar `/oxe-debug` separadamente. Escalação para `/oxe-forensics` só se esgotar tentativas.
+5. **verify** — até **6 camadas** por config: auditoria pré-exec, tarefas + critérios A*, fidelidade D-NN, UAT, **gaps de cobertura** (camada 5 — `verification_depth: "thorough"`), **segurança OWASP** (camada 6 — `security_in_verify: true`). Sem comandos extras.
+6. **→ próximo passo** — `/oxe` sugere automaticamente o que fazer agora (nova feature, milestone, ou revisar gaps).
 
-**Recuperação e meta (mesma trilha, outra camada):**
+**Escape hatches (não precisam ser decorados — aparecem quando necessários):**
 
-- **`/oxe-forensics`** — após `verify` falhar, `doctor` em falta ou estado incoerente; escreve `.oxe/FORENSICS.md` e recomenda **um** reingresso: `scan`, `plan` ou `execute` (ver `forensics.md`).
-- **`/oxe-debug`** — durante **`execute`**, para sintomas técnicos (teste vermelho, stack); escreve `.oxe/DEBUG.md`; **não** substitui `verify` após corrigir (ver `debug.md`).
-- **`/oxe-route`** — desambigua pedido em linguagem natural → **um** workflow/comando; não gera SPEC/PLAN (ver `route.md` e tabela **Router** abaixo).
+- **`/oxe-forensics`** — sugerido automaticamente pelo execute/verify quando falha persiste. Diagnóstico pós-falha + 1 caminho de reentrada.
+- **`/oxe-debug`** — diagnóstico técnico inline durante execute (já integrado ao execute; disponível standalone para controle explícito).
+- **`/oxe-loop`** — iteração até verify passar (disponível standalone; integrado ao Modo B do execute via `loop_max`).
+- **`/oxe-research`** — notas datadas em `.oxe/research/` para spikes, mapas de sistema, engenharia reversa.
+- **`/oxe-route`** — traduz linguagem natural → comando. Equivalente a `/oxe [texto]`.
+- **`/oxe-compact`** — refresh explícito do codebase. Equivalente a `/oxe-scan` sem `--full`.
 
-**Contexto em disco (opcional):**
+**Gestão de projeto (`/oxe-project`):**
 
-- **`/oxe-compact`** — **refresh do projeto**: compara **`.oxe/codebase/*.md`** ao repositório atual, **atualiza** os sete mapas (incremental ou bootstrap como `scan.md` se faltar base), escreve **`.oxe/CODEBASE-DELTA.md`** (o que mudou na documentação) e **`.oxe/RESUME.md`** (trilha OXE + ponte para o delta). Rotina de desenvolvimento; **não** está ligado a limites de chat ou a ferramentas específicas (ver `compact.md`). *Exemplo:* scan mapeou **Angular 17**; após migração implementada para **21**, o compact **corrige** `STACK.md`/testes/convenções face ao repo — intenção: **documentação OXE = código atual**, não refazer scan completo só por bump de major.
-- **`/oxe-checkpoint`** — **snapshot de sessão**: **`.oxe/checkpoints/…md`** + **`.oxe/CHECKPOINTS.md`**; marco nomeado sem apagar SPEC/PLAN (ver `checkpoint.md`).
+Um único comando para: `milestone new|complete|status|audit`, `workstream new|switch|list|close <nome>`, `checkpoint [slug]`. Sem argumento: mostra status atual.
 
 **Vertical UI (opcional, mesma trilha):**
 
 - **`/oxe-ui-spec`** — após **spec**, contrato `.oxe/UI-SPEC.md` antes ou para alimentar o **plan** (ver `ui-spec.md`).
 - **`/oxe-ui-review`** — após implementação UI, auditoria `.oxe/UI-REVIEW.md` antes ou como entrada para **verify** (ver `ui-review.md`).
 
-## Modo rápido (quick)
+## Modo rápido (quick) com Plan-Driven Dynamic Agents lean
 
-- **`/oxe-quick`**: cria `.oxe/QUICK.md` (passos curtos + verificar) sem SPEC/PLAN longos. **Perfil fast:** objetivo numa frase, ≤10 passos — ver secção **Perfil fast** em `quick.md`. **Promova** para spec/plan se o trabalho crescer (muitos arquivos, API pública, segurança) — mesmos gatilhos no workflow. Se existir **`.oxe/plan-agents.json`** (schema 2) ainda activo, o quick **invalida** o blueprint — não reutilizar esses agentes neste fluxo; para novo roteiro com agentes, **`/oxe-plan-agent`**.
+- **`/oxe-quick`**: cria `.oxe/QUICK.md` (passos curtos + verificar) sem SPEC/PLAN longos, integrando o conceito de **Plan-Driven Dynamic Agents (lean)**:
+
+  | Princípio | Como se manifesta no Quick |
+  |-----------|---------------------------|
+  | **Spec-Driven Design** | `## Objetivo` é a minispec — restringe o escopo de todos os agentes e passos |
+  | **Spec-Driven Development** | `## Passos` é o mini-plano — os agentes são derivados dos passos, não os definem |
+  | **Plan-Driven Dynamic Agents** | Agentes criados **a partir dos passos**, para **esta demanda**, invalidados ao terminar |
+
+  **Quando ativar agentes:** tarefa com 2+ domínios distintos (ex.: backend + frontend), 5+ passos que agrupam naturalmente, ou flag `--agents`. Máx. 3 agentes — se precisar de mais, promover para `/oxe-plan-agent`.
+
+  **Artefatos com agentes:** além de `.oxe/QUICK.md` (com seção `## Agentes dinâmicos`), cria **`.oxe/quick-agents.json`** (schema lean; `status: active` → `done` após verify). Sem handoff de mensagens entre agentes (lean — sem `.oxe/plan-agent-messages/`).
+
+  **Perfil fast (sem agentes):** objetivo numa frase, ≤10 passos, verificação. **Promova** para spec/plan se o trabalho crescer (muitos arquivos, API pública, segurança, ou > 3 domínios). Se existir **`.oxe/plan-agents.json`** (schema 2) ainda activo, o quick **invalida** o blueprint — não reutilizar esses agentes neste fluxo; para novo roteiro com agentes, **`/oxe-plan-agent`**.
 
 ## CLI (terminal)
 
@@ -114,18 +143,69 @@ Um pedido → **um** destino (sem gerar contrato). O agente aplica `route.md` ou
 | O que é OXE / lista de passos | `/oxe-help` |
 | Dúvida entre dois comandos sem contexto claro | `/oxe-route` |
 | Pesquisa técnica, spike, mapa de sistema grande, engenharia reversa, modernização antes do plano | `/oxe-research` |
+| Quero registrar uma observação (restrição, descoberta, preferência) durante ou fora de execução | `/oxe-obs [texto]` |
+| Quero executar todo o plano de uma vez (1 sessão) | `/oxe-execute` → escolher opção A (Completo) |
+| Quero executar onda por onda com verificação entre ondas | `/oxe-execute` → escolher opção B (Por onda) |
 | Gaps de cobertura de verificação / Nyquist-lite após verify | `/oxe-validate-gaps` |
 | Mapa OXE desatualizado / quero sincronizar codebase com o código sem scan completo | `/oxe-compact` |
 | Quero gravar um marco nomeado da sessão (antes de experimento grande) | `/oxe-checkpoint` + slug |
 | Plano com **blueprint de agentes** (JSON + mesmo PLAN.md) / subagentes por onda | `/oxe-plan-agent` |
+| Criar marco de entrega / versão / milestone | `/oxe-milestone new [nome]` |
+| Verificar se o milestone está pronto para fechar | `/oxe-milestone audit` |
+| Trabalho paralelo em trilhas separadas / feature branch OXE | `/oxe-workstream new <nome>` |
+| Alternar entre trilhas de desenvolvimento | `/oxe-workstream switch <nome>` |
+
+## Observações Contextuais (`/oxe-obs`)
+
+**Princípio:** *observation-without-re-explaining* — registre uma observação em 1 request; ela é incorporada automaticamente nos workflows seguintes sem precisar re-explicar.
+
+```
+/oxe-obs JWT expiration deve ser via env var JWT_EXPIRES_IN, não hardcoded
+```
+
+- **Quando usar:** durante execute (descoberta técnica), após scan (restrição identificada), após spec (ajuste de escopo), a qualquer momento
+- **Impacto:** classificado automaticamente em `spec` | `plan` | `execute` | `all`
+- **Auto-incorporação:** o próximo `/oxe-spec` (Fase 3), `/oxe-plan`, `/oxe-discuss` ou `/oxe-execute` lê `.oxe/OBSERVATIONS.md` e aplica observações pendentes sem prompt extra
+- **Urgência execute:** se chamado durante `executing` com impacto execute, oferece pausar onda atual ou continuar
 
 ## Notas pré-trilha (opcional)
 
 - Ficheiro **`.oxe/NOTES.md`**: bullets `YYYY-MM-DD — …` como fila leve (**não** substitui SPEC). Em **`/oxe-discuss`**, **`/oxe-plan`** e **`/oxe-plan-agent`**, consumir ou marcar descartado/adiado.
 
+## Milestones e Workstreams
+
+- **`/oxe-milestone new [nome]`** — iniciar marco de entrega (M-01, M-02, …); registrado em `.oxe/MILESTONES.md`.
+- **`/oxe-milestone complete`** — fechar milestone ativo, arquivar artefatos em `.oxe/milestones/M-NN/`.
+- **`/oxe-milestone status`** / **`/oxe-milestone audit`** — progresso e Definition of Done.
+- **`/oxe-workstream new <nome>`** — trilha paralela em `.oxe/workstreams/<nome>/`.
+- **`/oxe-workstream switch <nome>`** — definir workstream ativo; workflows operam nos artefatos dessa trilha.
+- **`/oxe-workstream list`** / **`/oxe-workstream close <nome>`** — gerenciar trilhas.
+
+## Personas de agentes
+
+Arquivos em `oxe/personas/` (ou `.oxe/personas/` após instalação) definem comportamentos de agentes para uso com `/oxe-plan-agent`. Personas builtin: `executor`, `planner`, `verifier`, `researcher`, `debugger`, `architect`, `ui-specialist`, `db-specialist`. Personas customizadas do projeto ficam em `.oxe/personas/`.
+
+## Profiles de execução
+
+O campo `profile` em `.oxe/config.json` expande automaticamente múltiplas keys:
+- **`balanced`** (padrão): cerimônia moderada, verificação standard.
+- **`strict`**: discuss obrigatório, verificação 4 camadas, UAT, aviso de scan antigo.
+- **`fast`**: sem discuss, verificação quick, sem UAT.
+- **`legacy`**: discuss obrigatório, verificação thorough, sem comando de test assumido.
+
 ## SDK (API programática)
 
-Quem integra em pipeline pode usar **`require('oxe-cc')`** (entrada `main` do pacote): por exemplo **`runDoctorChecks({ projectRoot })`** para passo de gate em CI; também `health`, `workflows`, `install.resolveOptionsFromConfig`, `manifest`, `agents`. Ver **`lib/sdk/README.md`** e **`lib/sdk/index.d.ts`**.
+Quem integra em pipeline pode usar **`require('oxe-cc')`** (entrada `main` do pacote):
+- **`runDoctorChecks({ projectRoot })`** — gate em CI.
+- **`parsePlan(planMd)`** — extrai tarefas, ondas, decisões e metadata de PLAN.md.
+- **`parseSpec(specMd)`** — extrai critérios A* e seções obrigatórias.
+- **`parseState(stateMd)`** — extrai fase, scan date, workstreams, milestone ativo.
+- **`validateDecisionFidelity(discussMd, planMd)`** — verifica cobertura de decisões D-NN.
+- **`security.checkPathSafety(path, root)`** — valida caminhos contra path traversal e segredos.
+- **`plugins.loadPlugins(projectRoot)`** / **`plugins.runHook(plugins, hook, ctx)`** — plugin lifecycle.
+- **`health.expandExecutionProfile(profile)`** — expande profile em keys individuais.
+
+Ver **`lib/sdk/README.md`** e **`lib/sdk/index.d.ts`**.
 
 ## Variáveis de ambiente (referência)
 
@@ -142,8 +222,9 @@ Quem integra em pipeline pode usar **`require('oxe-cc')`** (entrada `main` do pa
 
 ## Artefatos
 
-- `.oxe/STATE.md`, `.oxe/config.json` (opcional), `.oxe/codebase/*`, `.oxe/SPEC.md`, `.oxe/DISCUSS.md` (opcional), `.oxe/PLAN.md`, `.oxe/VERIFY.md`, `.oxe/QUICK.md`, `.oxe/SUMMARY.md` (opcional), `.oxe/NOTES.md` (opcional, fila), `.oxe/RESUME.md` (opcional, trilha + ponte para delta), `.oxe/CODEBASE-DELTA.md` (opcional, último refresh documentado do codebase), `.oxe/CHECKPOINTS.md` (opcional, índice), `.oxe/checkpoints/*.md` (opcional, marcos de sessão), `.oxe/RESEARCH.md` (opcional, índice de pesquisa), `.oxe/research/*.md` (opcional, notas datadas), `.oxe/VALIDATION-GAPS.md` (opcional, pós-verify), `.oxe/FORENSICS.md` (opcional, recuperação), `.oxe/DEBUG.md` (opcional, sessões de debug), `.oxe/UI-SPEC.md` / `.oxe/UI-REVIEW.md` (opcional, front-end)
-- Templates: `oxe/templates/` (ou `.oxe/templates/` em layout aninhado, conforme instalação). Hooks Git **opt-in** (lembretes não bloqueantes): `oxe/templates/GIT_HOOKS_OXE.md`.
+- `.oxe/STATE.md`, `.oxe/config.json` (opcional), `.oxe/codebase/*`, `.oxe/SPEC.md`, `.oxe/DISCUSS.md` (opcional, com IDs D-NN), `.oxe/PLAN.md`, `.oxe/VERIFY.md`, `.oxe/QUICK.md`, `.oxe/SUMMARY.md` (opcional), `.oxe/NOTES.md` (opcional, fila), `.oxe/RESUME.md` (opcional, trilha + ponte para delta), `.oxe/CODEBASE-DELTA.md` (opcional, último refresh documentado do codebase), `.oxe/CHECKPOINTS.md` (opcional, índice), `.oxe/checkpoints/*.md` (opcional, marcos de sessão), `.oxe/RESEARCH.md` (opcional, índice de pesquisa), `.oxe/research/*.md` (opcional, notas datadas), `.oxe/VALIDATION-GAPS.md` (opcional, pós-verify), `.oxe/FORENSICS.md` (opcional, recuperação), `.oxe/DEBUG.md` (opcional, sessões de debug), `.oxe/UI-SPEC.md` / `.oxe/UI-REVIEW.md` (opcional, front-end)
+- **Novos artefatos:** `.oxe/MILESTONES.md` (marcos de entrega), `.oxe/milestones/M-NN/` (artefatos arquivados), `.oxe/workstreams/<nome>/` (trilhas paralelas), `.oxe/personas/*.md` (personas de agentes customizadas), `.oxe/plugins/*.cjs` (plugins de lifecycle), `.oxe/memory/*.md` (sidecars de memória por sessão).
+- Templates: `oxe/templates/` (ou `.oxe/templates/` em layout aninhado, conforme instalação). Hooks Git **opt-in** (lembretes não bloqueantes): `oxe/templates/GIT_HOOKS_OXE.md`. Plugin system: `oxe/templates/PLUGINS.md`.
 
 ## Para autores (mantenedores)
 

package/oxe/workflows/loop.md

@@ -0,0 +1,57 @@
+# OXE — Workflow: loop (execução iterativa até verificação passar)
+
+<objective>
+Executar uma **onda do PLAN.md** em ciclo iterativo até que a verificação inline passe ou o limite de tentativas seja atingido. Complementa o **Modo B** (por onda) do **`execute.md`** com retries automáticos e diagnóstico inline de falhas.
+
+Quando verify falha, não interrompe — diagnostica (2-3 hipóteses), corrige, tenta de novo. Escala para **`/oxe-forensics`** apenas quando esgota as tentativas.
+</objective>
+
+<context>
+- **Pré-requisito:** `.oxe/PLAN.md` existente com pelo menos 1 onda; `STATE.md` com fase ≥ `plan_ready`.
+- **Máximo de iterações:** padrão = 3; configurável via argumento `max:<N>` (ex.: `/oxe-loop onda 2 max:5`). Nunca exceder 10.
+- **Artefato:** não cria novos arquivos — atualiza `STATE.md` com campos `loop_*` e registra cada iteração como bloco inline no chat.
+- **Escalação:** se esgotou tentativas e ainda falhou → registrar estado em STATE.md + sugerir `/oxe-forensics` com contexto das hipóteses já tentadas.
+- **Não substitui** `/oxe-verify` global (4 camadas): o loop faz verificação **inline por onda** (comando `**Verificar:**` de cada Tn); o verify completo deve ser chamado ao final de todas as ondas.
+</context>
+
+<loop_state>
+## Campos em STATE.md durante o loop
+
+```yaml
+loop_onda: 2              # número da onda sendo executada
+loop_iteracao: 2/3        # tentativa atual / máximo
+loop_status: retrying     # retrying | passed | escalated
+loop_hipoteses: ["H1: ...", "H2: ..."]  # hipóteses da última falha
+```
+
+Limpar campos `loop_*` ao concluir com `passed` (ou manter `escalated` se escalou para forensics).
+</loop_state>
+
+<process>
+1. Ler `.oxe/STATE.md` e `.oxe/PLAN.md`. Identificar a onda alvo (argumento do usuário ou próxima onda pendente em STATE).
+2. Registrar em STATE.md: `loop_onda: N`, `loop_iteracao: 1/<max>`, `loop_status: retrying`.
+3. **Iteração:**
+   a. Listar tarefas da onda N com seus comandos `**Verificar:**`.
+   b. Implementar todas as tarefas da onda (seguindo `execute.md` `<modo_solo>`).
+   c. Executar os comandos `Verificar` de cada `Tn`.
+   d. **Se todos passaram:** registrar `loop_status: passed`; limpar campos `loop_*`; atualizar STATE.md com onda concluída; informar usuário e sugerir próxima onda ou `/oxe-verify`.
+   e. **Se algum falhou:**
+      - Listar 2-3 hipóteses de causa (baseado no erro/output da verificação).
+      - Registrar `loop_hipoteses` em STATE.md.
+      - Incrementar iteração: `loop_iteracao: K+1/<max>`.
+      - Se `K+1 > max`: ir para passo 4 (escalação).
+      - Senão: aplicar fix para a hipótese mais provável → voltar a `c`.
+4. **Escalação (tentativas esgotadas):**
+   - Registrar `loop_status: escalated` em STATE.md.
+   - Exibir no chat: tentativas realizadas, hipóteses testadas, evidência de cada falha.
+   - Sugerir `/oxe-forensics` com contexto: "onda N falhou após <max> tentativas — hipóteses testadas: H1, H2, H3".
+</process>
+
+<success_criteria>
+- [ ] STATE.md tem campos `loop_*` atualizados a cada iteração.
+- [ ] Cada falha gera 2-3 hipóteses registradas antes de tentar fix.
+- [ ] Ao passar: campos `loop_*` limpos; onda marcada como concluída em STATE.md.
+- [ ] Ao esgotar: `loop_status: escalated` + sugestão de `/oxe-forensics` com contexto completo.
+- [ ] Nunca excede `max` iterações configurado.
+- [ ] Não altera `.oxe/PLAN.md` (só implementa o que já está planejado).
+</success_criteria>

package/oxe/workflows/milestone.md

@@ -0,0 +1,96 @@
+# OXE — Workflow: milestone
+
+<objective>
+Gerenciar **marcos de entrega** do projeto: registrar versões entregues, arquivar fases concluídas e preparar o contexto para a próxima iteração.
+
+Subcomandos:
+- `/oxe-milestone new [nome]` — iniciar novo milestone.
+- `/oxe-milestone complete` — fechar milestone ativo, arquivar artefatos, preparar próxima iteração.
+- `/oxe-milestone status` — exibir progresso do milestone ativo.
+- `/oxe-milestone audit` — verificar se o milestone atingiu sua definição de pronto.
+</objective>
+
+<context>
+- Milestone ≠ Checkpoint. **Checkpoint** (`/oxe-checkpoint`) é um snapshot de sessão — restaurável a qualquer momento. **Milestone** é uma entrega — marcador de versão com artefatos arquivados e critérios de pronto validados.
+- Milestones são rastreados em **`.oxe/MILESTONES.md`** (índice) e cada entrega tem uma entrada com status, data e links aos artefatos.
+- O milestone ativo é registrado no **STATE.md** na seção **Milestone ativo**.
+- Um milestone é considerado **pronto** quando:
+  1. Todos os critérios A* da SPEC estão com `verify_complete` no STATE.
+  2. VERIFY.md não tem gaps abertos.
+  3. Checklist UAT foi preenchido pelo usuário (se aplicável).
+  4. Rascunho de commit ou PR foi gerado.
+</context>
+
+<process_new>
+**`/oxe-milestone new [nome]`**
+
+1. Verificar se há milestone ativo em STATE.md. Se houver, alertar e pedir confirmação antes de criar novo.
+2. Gerar ID sequencial: **M-01**, **M-02**, …
+3. Criar entrada em **`.oxe/MILESTONES.md`**:
+   ```markdown
+   ## M-01 — [nome] (ativo)
+   - **Status:** ativo
+   - **Iniciado:** YYYY-MM-DD
+   - **SPEC:** `.oxe/SPEC.md` (versão atual)
+   - **Critérios:** A1, A2, … (lista dos IDs da SPEC)
+   - **Entregável:** (descrever o que será entregue)
+   ```
+4. Atualizar **STATE.md**: seção **Milestone ativo** com ID e nome.
+5. Confirmar no chat: `Milestone M-01 iniciado — próximo passo: /oxe-spec (ou /oxe-plan se SPEC já existir)`.
+</process_new>
+
+<process_complete>
+**`/oxe-milestone complete`**
+
+Pré-requisitos (verificar antes de executar):
+- [ ] STATE.md indica `verify_complete`.
+- [ ] VERIFY.md não tem gaps abertos.
+- [ ] Checklist UAT preenchido (se aplicável).
+
+Se pré-requisitos não forem satisfeitos: listar os que faltam e pausar. Com `--force`: documentar pré-requisitos não satisfeitos e continuar com aviso.
+
+Passos:
+1. Arquivar artefatos do milestone:
+   - Copiar `.oxe/SPEC.md` → `.oxe/milestones/M-NN/SPEC.md`
+   - Copiar `.oxe/PLAN.md` → `.oxe/milestones/M-NN/PLAN.md`
+   - Copiar `.oxe/VERIFY.md` → `.oxe/milestones/M-NN/VERIFY.md`
+   - Copiar `.oxe/DISCUSS.md` → `.oxe/milestones/M-NN/DISCUSS.md` (se existir)
+   - Criar `.oxe/milestones/M-NN/MILESTONE.md` com resumo da entrega.
+2. Atualizar **`.oxe/MILESTONES.md`**: marcar milestone como `entregue`, adicionar data de encerramento e links aos artefatos arquivados.
+3. Atualizar **STATE.md**: limpar seção **Milestone ativo**, registrar **Último milestone** com ID e data.
+4. Sugerir próximo milestone ou nova spec: `Milestone M-NN concluído. Próximos passos: /oxe-milestone new v2 | /oxe-spec | /oxe-checkpoint`.
+</process_complete>
+
+<process_status>
+**`/oxe-milestone status`**
+
+1. Ler STATE.md para identificar milestone ativo (ID e nome).
+2. Ler MILESTONES.md para detalhes.
+3. Ler SPEC.md para listar critérios A* e seu status (verificado / pendente).
+4. Ler VERIFY.md (se existir) para gaps abertos.
+5. Exibir no chat:
+   - Milestone ativo: ID, nome, data de início.
+   - Progresso: N/M critérios verificados.
+   - Gaps abertos: lista ou "nenhum".
+   - Próximo passo sugerido.
+</process_status>
+
+<process_audit>
+**`/oxe-milestone audit`**
+
+Verificar definição de pronto (Definition of Done):
+1. [ ] `verify_complete` no STATE.
+2. [ ] VERIFY.md sem gaps.
+3. [ ] Checklist UAT preenchido (ou ausente se inaplicável).
+4. [ ] Rascunho de commit ou PR gerado.
+5. [ ] Artefatos do milestone existem (SPEC, PLAN, VERIFY).
+
+Resultado: `Milestone M-NN: PRONTO` ou lista de itens pendentes.
+</process_audit>
+
+<success_criteria>
+- [ ] `.oxe/MILESTONES.md` existe e tem entrada para o milestone ativo.
+- [ ] STATE.md indica milestone ativo (ID e nome).
+- [ ] Ao completar: artefatos arquivados em `.oxe/milestones/M-NN/`.
+- [ ] Ao completar: MILESTONES.md atualizado com status `entregue` e data.
+</success_criteria>