oxe-cc 0.3.8 → 0.5.0

package/oxe/templates/STATE.md

@@ -12,7 +12,7 @@
 ## Último compact (codebase + RESUME) (opcional)
 
 - **Data:** (**YYYY-MM-DD** — preenchido por **`/oxe-compact`**: refresh incremental dos mapas em `.oxe/codebase/` + `CODEBASE-DELTA.md` + `RESUME.md`)
-- **Notas:** (opcional; ex.: “só STRUCTURE e TESTING”)
+- **Notas:** (opcional; ex.: "só STRUCTURE e TESTING")
 
 ## Contexto do plano / quick (opcional)
 
@@ -37,9 +37,36 @@ _(O agente pode preencher após cada onda.)_
 - [ ] Onda N — implementação concluída
 - [ ] Onda N — **Verificar** executado ou agendado
 
+## Milestone ativo (opcional — `/oxe-milestone`)
+
+- **ID:** (ex.: M-01 — ou — se não houver milestone ativo)
+- **Nome:** (ex.: v1.0 — autenticação básica)
+- **Iniciado:** (YYYY-MM-DD)
+- **Progresso:** (N/M critérios verificados)
+
+## Último milestone encerrado (opcional)
+
+- **ID:** —
+- **Data de encerramento:** —
+- **Artefatos:** `.oxe/milestones/M-NN/`
+
+## Workstreams ativos (opcional — `/oxe-workstream`)
+
+- (nenhum ou lista de nomes: ex.: `feature-billing`, `bugfix-auth`)
+
+## Workstream ativo (contexto atual)
+
+- (nome do workstream ativo — ou — para pipeline principal)
+
+## Memory (sidecars de sessão) (opcional — `/oxe-memory`)
+
+Sidecars de memória persistente por agente/sessão. Armazenados em `.oxe/memory/`.
+
+- (nenhum ou lista: ex.: `architect-2025-01-15.md`, `researcher-auth-2025-01-14.md`)
+
 ## Decisões persistentes
 
-- (bullet: decisão → data)
+- (bullet: D-NN: decisão → data)
 
 ## Próximo passo sugerido
 

package/oxe/templates/config.template.json

@@ -1,10 +1,15 @@
 {
+  "_comment": "OXE config — copie para .oxe/config.json no seu projeto. Remova esta linha.",
+  "profile": "balanced",
   "discuss_before_plan": false,
+  "verification_depth": "standard",
   "after_verify_suggest_pr": true,
   "after_verify_draft_commit": true,
+  "after_verify_suggest_uat": false,
   "default_verify_command": "",
   "scan_max_age_days": 0,
   "compact_max_age_days": 0,
+  "scale_adaptive": true,
   "scan_focus_globs": [],
   "scan_ignore_globs": [],
   "spec_required_sections": [],

package/oxe/templates/plan-agent-messages-README.template.md

@@ -6,4 +6,4 @@ Esta pasta guarda handoffs entre agentes do blueprint **`.oxe/plan-agents.json`*
 - O campo **`runId`** no frontmatter deve coincidir com o de `plan-agents.json`
 - Não editar mensagens depois de criadas; invalidação do blueprint (`lifecycle.invalidated`) encerra novos envios
 
-Gerado por **`/oxe-plan-agent`**. Limpar ou arquivar manualmente ao iniciar um blueprint novo se desejar histórico isolado.
+Gerado por **`/oxe-plan-agent`**. Após **`/oxe-verify`** com sucesso e blueprint **`closed`**, o fluxo OXE **recomenda** mover este conteúdo para **`.oxe/archive/plan-agent-runs/<runId>/messages/`** (ver **`oxe/workflows/references/plan-agent-chat-protocol.md`**). Antes de um **replan** com novo `runId`, arquivar o run anterior se quiser preservar handoffs.

package/oxe/templates/quick-agents.template.json

@@ -0,0 +1,24 @@
+{
+  "oxeQuickAgentsSchema": 1,
+  "quickId": "quick-YYYY-MM-DD-substituir-por-6hex",
+  "quickRef": ".oxe/QUICK.md",
+  "status": "active",
+  "since": "YYYY-MM-DDTHH:mm:ssZ",
+  "_comment": "Agentes derivados dos passos do QUICK.md. Plan-Driven Dynamic Agents (lean): criados para esta demanda, invalidados ao promover para spec/plan ou iniciar novo quick.",
+  "agents": [
+    {
+      "id": "agent-dominio-a",
+      "role": "Papel específico para ESTA demanda (não genérico)",
+      "persona": "executor",
+      "steps": [1, 2, 3],
+      "focus": "Uma frase sobre o foco deste agente nos steps atribuídos"
+    },
+    {
+      "id": "agent-dominio-b",
+      "role": "Papel específico para ESTA demanda (não genérico)",
+      "persona": "executor",
+      "steps": [4, 5],
+      "focus": "Uma frase sobre o foco deste agente nos steps atribuídos"
+    }
+  ]
+}

package/oxe/workflows/discuss.md

@@ -8,10 +8,22 @@ Usar quando: SPEC existe mas há ambiguidade, risco técnico, ou `discuss_before
 
 <context>
 - Ler `.oxe/SPEC.md`, `.oxe/STATE.md` e trechos relevantes de `.oxe/codebase/OVERVIEW.md` / `STACK.md`.
+- Se existir **`.oxe/OBSERVATIONS.md`** com entradas `pendente` de impacto `spec`, `plan` ou `all`, carregá-las como contexto adicional para as perguntas e decisões; marcá-las `incorporada → discuss (data)` após uso.
 - Se existir **`.oxe/NOTES.md`**, rever bullets em aberto: promover para perguntas/decisões em `DISCUSS.md` ou marcar como *descartado* / *adiado* com uma linha de justificativa.
 - Se `.oxe/config.json` existir e `discuss_before_plan` for `true`, tratar este passo como **recomendado** antes de `oxe:plan`.
 </context>
 
+<decision_ids>
+Toda decisão fechada em `DISCUSS.md` recebe um **ID estável** com prefixo `D-` e número sequencial: **D-01**, **D-02**, …
+
+Regras:
+1. O ID é atribuído **quando a decisão é registrada** (não quando a pergunta é feita).
+2. IDs não são reutilizados — se uma decisão for revertida, registrar a reversão com novo ID (`D-05: Revertendo D-02 — novo comportamento X`) e marcar D-02 como `*(revertida por D-05)*`.
+3. `PLAN.md` deve referenciar os IDs nas tarefas (campo **Decisão vinculada:** `D-01, D-03`).
+4. `VERIFY.md` deve cruzar os IDs na seção **Fidelidade de decisões**.
+5. O ID é o vínculo de rastreabilidade discuss → plan → verify.
+</decision_ids>
+
 <process>
 1. Se não existir `.oxe/SPEC.md`, pedir **spec** primeiro (ou **quick** se for trabalho trivial).
 2. Se existir **`.oxe/NOTES.md`**, rever bullets em aberto e decidir o que entra em **Perguntas** ou **Decisões** (ou marcar *descartado* / *adiado* com justificativa curta).
@@ -19,16 +31,47 @@ Usar quando: SPEC existe mas há ambiguidade, risco técnico, ou `discuss_before
 4. Criar ou atualizar **`.oxe/DISCUSS.md`** com estrutura fixa:
    - **Contexto** — 2–4 bullets do que já se sabe da SPEC.
    - **Perguntas** — numeradas; para cada uma: resposta (se o usuário já respondeu na mensagem) ou `_(pendente)_`.
-   - **Decisões** — bullets com decisão + data (só as já fechadas).
-   - **Implicações para o plano** — bullets (ex.: “migrations necessárias”, “feature flag”).
+   - **Decisões** — tabela com colunas **ID** / **Decisão** / **Data** / **Impacto no plano** (só as já fechadas). Atribuir IDs **D-01**, **D-02**, … em sequência.
+   - **Implicações para o plano** — bullets (ex.: "migrations necessárias", "feature flag").
 5. Se ainda houver perguntas **pendentes** críticas, listá-las no chat (máx. 7) e parar até resposta; depois atualizar DISCUSS.md.
-6. Atualizar **`.oxe/STATE.md`**: fase `discuss_complete`, próximo passo `oxe:plan`.
-7. Resumo no chat em ≤8 linhas.
+6. Atualizar **`.oxe/STATE.md`**: fase `discuss_complete`, próximo passo `oxe:plan`. Registrar os IDs de decisão na seção **Decisões persistentes** do STATE (ex.: `D-01: escolheu JWT — 2025-01-15`).
+7. Resumo no chat em ≤8 linhas, listando decisões com seus IDs.
 </process>
 
+<discuss_md_format>
+```markdown
+---
+oxe_doc: discuss
+status: (open | closed)
+updated: YYYY-MM-DD
+---
+
+# OXE — Discuss
+
+## Contexto
+- …
+
+## Perguntas
+
+1. **[pergunta]**
+   - Resposta: … / _(pendente)_
+
+## Decisões
+
+| ID   | Decisão                          | Data       | Impacto no plano                      |
+|------|----------------------------------|------------|---------------------------------------|
+| D-01 | (decisão clara e acionável)      | YYYY-MM-DD | (como afeta tarefas / arquivos)       |
+| D-02 | …                                | …          | …                                     |
+
+## Implicações para o plano
+- …
+```
+</discuss_md_format>
+
 <success_criteria>
 - [ ] `.oxe/DISCUSS.md` existe com perguntas e decisões alinhadas à SPEC.
+- [ ] Cada decisão fechada tem ID único **D-NN** na tabela de Decisões.
 - [ ] Se existir `.oxe/NOTES.md`, as entradas relevantes foram tratadas (promovidas, descartadas ou adiadas com nota).
 - [ ] Nenhuma ambiguidade crítica ficou sem registro (como pendente ou suposição explícita na SPEC).
-- [ ] `STATE.md` indica próximo passo **plan**.
+- [ ] `STATE.md` indica próximo passo **plan** e lista IDs de decisão em **Decisões persistentes**.
 </success_criteria>

package/oxe/workflows/execute.md

@@ -1,47 +1,130 @@
 # 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>
+
 <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`.
+
+**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

@@ -15,7 +15,7 @@ No **projeto**, os passos canónicos estão em **`.oxe/workflows/*.md`** (layout
 
 ### 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: `/oxe-scan`, `/oxe-spec`, `/oxe-discuss`, `/oxe-plan`, `/oxe-plan-agent`, `/oxe-verify`, `/oxe-next`, `/oxe-quick`, `/oxe-execute`, `/oxe-obs`, `/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`, `/oxe-milestone`, `/oxe-workstream` (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.
 
 ### GitHub Copilot (VS Code)
 
@@ -49,17 +49,18 @@ Com **`compact_max_age_days`** em `.oxe/config.json` (ver `oxe/templates/CONFIG.
 
 ## Fluxo completo
 
+0. **obs** *(qualquer momento)* — `/oxe-obs` registra uma observação contextual em `.oxe/OBSERVATIONS.md`; incorporada automaticamente no próximo spec/plan/execute sem re-explicar (ver seção **Observações** abaixo).
 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.
+2. **spec** — fluxo em **5 fases**: perguntas (máx 3 rodadas) → pesquisa (opcional) → requisitos R-ID (v1/v2/fora) → roteiro (`.oxe/ROADMAP.md`) → aprovação → instrui plan ou plan-agent.
+2b. **research** (opcional, pode ser proposto pela Fase 2 do spec) — notas datadas em `.oxe/research/` + índice `.oxe/RESEARCH.md`; spikes, mapa de sistema, engenharia reversa, modernização.
+3. **discuss** (opcional) — decisões com IDs D-NN antes do plano; recomendado se `discuss_before_plan` em `.oxe/config.json`. Incorpora OBS pendentes de impacto spec/plan.
+4. **plan** — plano executável + **Verificar** por tarefa, ligado aos critérios A* da SPEC. Incorpora OBS pendentes de impacto plan.
+4b. **plan-agent** (opcional) — igual ao **plan** + **`.oxe/plan-agents.json`** (schema **2**: `runId` **novo** por demanda, `lifecycle`). Agentes criados especificamente para ESTE plano — sem reuso entre demandas. `/oxe-quick` invalida o blueprint.
+5. **execute** — seleção de modo ao iniciar: **A) Completo** (1 sessão/requisição), **B) Por onda** (N sessões), **C) Por tarefa** (controle máximo). Incorpora OBS pendentes de impacto execute.
 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).
+7. **verify** — 4 camadas: auditoria pré-exec, tarefas + critérios A*, fidelidade D-NN, UAT checklist.
+7b. **validate-gaps** (opcional) — após verify, auditoria de cobertura em `.oxe/VALIDATION-GAPS.md`.
+8. **next** — retomar trabalho; no terminal: **`npx oxe-cc status`** sugere um único próximo passo.
 
 **Recuperação e meta (mesma trilha, outra camada):**
 
@@ -77,9 +78,21 @@ Com **`compact_max_age_days`** em `.oxe/config.json` (ver `oxe/templates/CONFIG.
 - **`/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 +127,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 +206,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/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>