oxe-cc 0.3.3 → 0.3.5

package/oxe/workflows/execute.md

@@ -1,28 +1,36 @@
-# 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.
-
-Se existir apenas **`.oxe/QUICK.md`** (fluxo quick), tratar os **Passos** numerados como lista única “onda 1” em vez de tarefas T1…Tn.
-</objective>
-
-<context>
-- 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.
-</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, ficheiros prováveis, comando **Verificar** associado (do PLAN ou do QUICK).
-4. Após o utilizador confirmar que a onda foi implementada (ou após aplicares as mudanças tu mesmo), atualizar **`.oxe/STATE.md`**:
-   - Secção ou bullets: **Última onda executada**, **Tarefas concluídas** (Tn ou números dos passos).
-   - Próximo passo: continuar próxima onda, `oxe:verify`, ou `oxe:plan` se o plano ficou obsoleto.
-5. Se o PLAN tiver várias ondas, repetir execute por onda sob pedido; não apagar tarefas do PLAN.
-</process>
-
-<success_criteria>
-- [ ] Onda ou bloco de passos está explícito antes de “implementar”.
-- [ ] `STATE.md` regista progresso (Tn ou passos) e próximo passo.
-- [ ] Verificação alinhada ao bloco **Verificar** do PLAN ou QUICK.
-</success_criteria>
+# 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.
+
+Se existir apenas **`.oxe/QUICK.md`** (fluxo quick), tratar os **Passos** numerados como lista única “onda 1” em vez de tarefas T1…Tn.
+</objective>
+
+<context>
+- 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.
+</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:
+   ```markdown
+   ## Checklist — Onda N (OXE)
+   - [ ] Pré-requisitos da onda conferidos (dependências T* atendidas)
+   - [ ] Implementação da onda concluída
+   - [ ] Comando **Verificar** desta onda 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.
+</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.
+- [ ] Verificação alinhada ao bloco **Verificar** do PLAN ou QUICK.
+</success_criteria>

package/oxe/workflows/help.md

@@ -1,54 +1,88 @@
 # OXE — Workflow: help
 
 <objective>
-Apresentar o fluxo OXE (scan → spec → plan → execução → verify), o modo **quick**, o passo **execute**, e como invocar no **Cursor** e no **GitHub Copilot**. Mencionar CLI `oxe-cc` (instalar, `doctor`, `init-oxe`).
+Apresentar o fluxo OXE (scan → spec → plan → execução → verify), o modo **quick**, o passo **execute**, e como invocar no **Cursor** e no **GitHub Copilot**. Mencionar o CLI `oxe-cc` (instalar, `doctor`, `status`, `init-oxe`, `uninstall`, `update`) e, em linha, o **SDK** npm (`require('oxe-cc')`) para CI.
 </objective>
 
 <context>
-OXE é um fluxo **spec-driven** com artefatos em `.oxe/` no repositório alvo. Menos comandos que GSD; mesmo espírito de context engineering (ficheiros pequenos por etapa).
+OXE é um fluxo **spec-driven** com artefatos em `.oxe/` no projeto alvo. **Poucos comandos slash** em relação a fluxos de planeamento mais pesados; *context engineering* com arquivos pequenos por etapa. Instruções do Copilot no VS Code ficam em **`~/.copilot/`** após `npx oxe-cc` (bloco mesclado em `copilot-instructions.md` + **prompt files** em `~/.copilot/prompts/`), não em `.github/` dentro do repo alvo.
+
+No **projeto**, os passos canónicos estão em **`.oxe/workflows/*.md`** (layout mínimo) ou **`oxe/workflows/*.md`** (layout clássico com `--global`); no **pacote npm**, os modelos vivem em **`oxe/workflows/*.md`**.
 </context>
 
 <output>
 ## Cursor
 
-Slash commands: `/oxe-scan`, `/oxe-spec`, `/oxe-discuss`, `/oxe-plan`, `/oxe-verify`, `/oxe-next`, `/oxe-quick`, `/oxe-execute`, `/oxe-help` (definidos em `.cursor/commands/`).
+Slash commands: `/oxe-scan`, `/oxe-spec`, `/oxe-discuss`, `/oxe-plan`, `/oxe-verify`, `/oxe-next`, `/oxe-quick`, `/oxe-execute`, `/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` (ou `.oxe/workflows/review-pr.md`) em contexto.
 
-## GitHub Copilot (VS Code / IDE)
+## GitHub Copilot (VS Code)
 
-1. **Instruções do repositório:** `.github/copilot-instructions.md` (ativas no chat quando o repositório está em contexto).
-2. **Prompt files:** no chat, escrever `/` e escolher **`oxe-scan`**, **`oxe-spec`**, **`oxe-discuss`**, **`oxe-plan`**, **`oxe-verify`**, **`oxe-next`**, **`oxe-quick`**, **`oxe-execute`**, **`oxe-help`**, **`oxe-review-pr`** (revisão: URL `github.com/.../pull/N`, branches ou SHAs). Requer `chat.promptFiles`: true.
+1. **Instruções do usuário:** arquivo **`~/.copilot/copilot-instructions.md`** (conteúdo mesclado pelo instalador; contém o bloco OXE entre marcadores).
+2. **Prompt files:** em **`~/.copilot/prompts/`** (ex.: `oxe-scan.prompt.md`). No chat, `/` e escolha **`oxe-scan`**, **`oxe-spec`**, etc. Requer `"chat.promptFiles": true` (exemplo em `.vscode/settings.json` do repo com layout `--global`).
+3. **`/oxe-review-pr`** — revisão de PR/diff (prompt na pasta do usuário; fluxo em `review-pr.md`).
 
 ## Fluxo completo
 
-1. **scan** — após clonar ou quando o repo mudar muito.
-2. **spec** — descrever o que se quer.
-3. **discuss** (opcional) — perguntas objetivas antes do plano; recomendado se `discuss_before_plan` em `.oxe/config.json`.
-4. **plan** — plano executável + verificação por tarefa.
+1. **scan** — após clonar ou quando o repositório mudar muito.
+2. **spec** — descrever o que se quer (critérios com IDs **A1**, **A2**…).
+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.
 5. **execute** (opcional) — onda a onda com base no PLAN (ou passos do QUICK).
 6. Implementar mudanças no agente/editor.
-7. **verify** — validar antes de merge/PR (inclui rascunho de commit / checklist PR se configurado).
-8. **next** — retomar trabalho.
+7. **verify** — validar tarefas **e** critérios SPEC antes de merge/PR.
+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).
 
 ## Modo rápido (quick)
 
-- **`/oxe-quick`**: cria `.oxe/QUICK.md` (passos curtos + verificar) sem SPEC/PLAN longos. Promover a spec/plan se o trabalho crescer (muitos ficheiros, API pública, segurança).
+- **`/oxe-quick`**: cria `.oxe/QUICK.md` (passos curtos + verificar) sem SPEC/PLAN longos. **Promova** para spec/plan se o trabalho crescer (muitos arquivos, API pública, segurança) — ver workflow `quick.md`.
 
 ## CLI (terminal)
 
-- **`npx oxe-cc`** — instala `oxe/`, Cursor, Copilot, etc.; por omissão cria **`.oxe/`** mínimo (`STATE.md` a partir do template) se ainda não existir.
-- **`oxe-cc doctor`** — verifica Node, workflows, JSON válido em `.oxe/config.json`, mapa codebase após scan (lista o que falta).
-- **`oxe-cc init-oxe`** — só inicializa `.oxe/` (STATE + `config.json` + pasta `codebase/`), sem reinstalar o resto.
-- **`oxe-cc --no-init-oxe`** — instala workflows sem criar `.oxe/`.
+- **`npx oxe-cc`** ou **`npx oxe-cc install`** — mesma instalação (alias explícito).
+- Instala workflows em `.oxe/` (layout mínimo) ou `oxe/` + `.oxe/` com **`--global`**; integrações em `~/.cursor`, `~/.copilot`, `~/.claude` (e mais destinos com **`--copilot-cli`** / **`--all-agents`**).
+- **`oxe-cc doctor`** — Node, workflows do pacote vs projeto, `config.json`, mapas do codebase, **coerência STATE vs arquivos**, scan antigo (`scan_max_age_days`), seções SPEC, ondas do PLAN, **avisos** não bloqueantes sobre estrutura dos `.md` de workflow (ex.: `<objective>`, critérios de sucesso).
+- **`oxe-cc status`** — coerência `.oxe/` + **um** próximo passo (espelha `next.md`).
+- **`oxe-cc init-oxe`** — só bootstrap `.oxe/` (STATE, config, codebase).
+- **`oxe-cc uninstall`** — remove integrações no HOME e, por omissão, pastas de workflows no repo (`--ide-only` só HOME).
+- **`oxe-cc update` / `npx oxe-cc@latest --force`** — atualizar ficheiros OXE no projeto.
+
+**CI / sem perguntas:** `OXE_NO_PROMPT=1` — layout mínimo e integrações padrão no HOME, salvo flags (`--global`, `--cursor`, …). Se existir **`.oxe/config.json`** com bloco **`install`** (perfil, `repo_layout`), aplica-se quando **não** há flags IDE explícitas; para ignorar: **`--no-install-config`**. Detalhes: `oxe/templates/CONFIG.md`.
+
+**Flags úteis (resumo):** `--force` / `-f`, `--dry-run`, `--all` / `-a` (Cursor+Copilot), `--oxe-only`, `--no-init-oxe`, `--global` / `--local`, `--copilot-cli`, `--all-agents`, `--vscode` (com `--global`), `--no-global-cli` / `-l`, `--config-dir` / `-c` (uma IDE de cada vez), `--dir <pasta>`. Ajuda completa: `oxe-cc --help`.
+
+**WSL:** usar Node instalado **no** WSL; o instalador recusa Node do Windows dentro do WSL.
+
+## 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`**.
+
+## Variáveis de ambiente (referência)
+
+| Variável | Uso |
+|----------|-----|
+| `OXE_NO_PROMPT` | `1` / `true`: sem menus interativos |
+| `OXE_NO_BANNER` | `1` / `true`: sem banner no CLI |
+| `CURSOR_CONFIG_DIR` | Base Cursor (default `~/.cursor`) |
+| `COPILOT_CONFIG_DIR` / `COPILOT_HOME` | Base Copilot |
+| `CLAUDE_CONFIG_DIR` | Base `~/.claude` |
+| `XDG_CONFIG_HOME` | OpenCode e outros (multi-agente) |
+| `CODEX_HOME` | Prompts Codex em instalação multi-agente |
 
 ## 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`
+- `.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)
+- Templates: `oxe/templates/` (ou `.oxe/templates/` em layout aninhado, conforme instalação)
+
+## Para autores (mantenedores)
+
+- Guia de autoria dos workflows: **`oxe/templates/WORKFLOW_AUTHORING.md`** (no pacote) ou **`.oxe/templates/WORKFLOW_AUTHORING.md`** após instalação em layout aninhado.
+- Revisão guiada de um ficheiro de workflow contra esse guia: workflow **`workflow-authoring.md`** (mesma pasta que os outros passos).
 
-## Gatilhos naturais (Copilot / chat)
+## Gatilhos em linguagem natural
 
-Quando o utilizador disser “oxe scan”, “oxe quick”, “executar onda OXE”, “revisar PR”, “diff entre branches”, etc., seguir o workflow correspondente em `oxe/workflows/*.md`.
+Quando o usuário disser “oxe scan”, “oxe quick”, “executar onda OXE”, “revisar PR”, “rever um workflow OXE” / “alinhar ao guia de autoria”, etc., siga o workflow correspondente em `oxe/workflows/*.md` ou `.oxe/workflows/*.md` (autoria: `workflow-authoring.md`).
 
-**Nota:** **`oxe-review-pr`** não tem homólogo em `.cursor/commands/`; no Cursor podes pedir em linguagem natural seguindo `oxe/workflows/review-pr.md` ou abrir o mesmo ficheiro como contexto.
+**GitHub Copilot CLI:** com `oxe-cc --copilot-cli`, use **agent skills** em **`~/.copilot/skills/`** — invoque **`/oxe`** (entrada, mesmo conteúdo que help) ou **`/oxe-scan`**, **`/oxe-plan`**, etc. Após instalar ou atualizar: **`/skills reload`** (ou reinicie o `copilot`). A pasta **`~/.copilot/commands/`** é só cópia legado; o CLI oficial não a usa como slash commands.
 
-**Copilot CLI (experimental):** `oxe-cc --copilot-cli` copia os mesmos Markdown de `.cursor/commands/` para **`.claude/commands/`** — para testar **`/oxe-scan`**, etc., conforme a versão do GitHub Copilot CLI.
+**Multi-agente:** `npx oxe-cc --all-agents` (ou opção **6** no instalador) replica os mesmos fluxos para **OpenCode** (`~/.config/opencode/commands` + `~/.opencode/commands`), **Gemini CLI** (`~/.gemini/commands` — `/oxe`, `/oxe:scan`, …; use **`/commands reload`**), **Codex** (`~/.agents/skills` + `~/.codex/prompts` com `/prompts:oxe-*`), **Windsurf** (`~/.codeium/windsurf/global_workflows` — `/oxe-scan`), **Google Antigravity** (`~/.gemini/antigravity/skills`), além de **Claude** (`~/.claude/commands`) e o já descrito Copilot.
 </output>

package/oxe/workflows/next.md

@@ -1,22 +1,36 @@
 # OXE — Workflow: next
 
 <objective>
-Inspecionar `.oxe/STATE.md` e a existência de `SPEC.md`, `PLAN.md`, `QUICK.md`, `VERIFY.md` e `.oxe/codebase/` para recomendar **um** próximo passo OXE e uma frase de justificativa.
+Inspecionar `.oxe/STATE.md` e a existência de `SPEC.md`, `PLAN.md`, `QUICK.md`, `VERIFY.md` e `.oxe/codebase/` para recomendar **exatamente um** próximo passo OXE e **uma** frase de justificativa — sem lista de alternativas equiparáveis.
 </objective>
 
+<context>
+- O usuário pode rodar **`npx oxe-cc status`** no terminal para a mesma lógica resumida.
+- Se houver empate aparente (ex.: poderia ser spec ou quick), preferir **spec** quando já existir mapa de codebase; preferir **quick** só se o usuário deixar explícito que é correção mínima.
+</context>
+
 <process>
-1. Se `.oxe/` ou `STATE.md` não existir → recomendar **scan** ou `oxe-cc init-oxe` / primeiro **scan** e oferecer criar `.oxe` a partir de `oxe/templates/STATE.md`.
-2. Se não houver `.oxe/codebase/*.md` (e o trabalho não for só um quick isolado) → **scan**.
-3. Se `STATE.md` indicar fase `quick_active` ou existir `QUICK.md` sem PLAN → recomendar **execute** (se ainda há passos) ou **verify** depois de implementar; se o trabalho cresceu → **spec**.
-4. Se não houver `SPEC.md` e não estiveres em modo quick intencional → **spec** (ou **quick** se o utilizador quiser só um fix pequeno).
-5. Se houver SPEC mas não PLAN → se `.oxe/config.json` tiver `discuss_before_plan: true` e faltar **`.oxe/DISCUSS.md`** (ou estiver incompleto) → **discuss**; senão → **plan**.
-6. Se PLAN (ou QUICK) existe, há implementação pendente e ainda não verificaste → **execute** opcionalmente, depois **verify**.
-7. Se VERIFY ausente ou desatualizado após mudanças → **verify**.
-8. Se VERIFY passou → sugerir PR/commit ou novo **spec** / **quick** para próxima tarefa.
+1. Se `.oxe/` ou `STATE.md` não existir → **único** passo: **scan** (ou `oxe-cc init-oxe` seguido de scan).
+2. Se não houver `.oxe/codebase/*.md` completos (sete mapas) e o trabalho **não** for só um quick isolado → **scan**.
+3. Se fase `quick_active` ou existir `QUICK.md` **sem** `PLAN.md` → **execute** (se há passos pendentes); se o trabalho cresceu (muitos arquivos, contrato público, segurança) → **spec** como passo único de promoção.
+4. Se não houver `SPEC.md` e não for quick intencional declarado → **spec** (passo único).
+5. Se houver SPEC mas não PLAN → se `.oxe/config.json` tiver `discuss_before_plan: true` e faltar **`.oxe/DISCUSS.md`** com decisões → **discuss**; senão → **plan**.
+6. Se PLAN existe, **VERIFY.md** ainda **não** existe ou está claramente antes da implementação atual → **execute** (onda atual).
+7. Se PLAN existe e VERIFY falta após implementação declarada → **verify**.
+8. Se VERIFY indica falha ou gaps não resolvidos → **plan** (replanejamento) como passo único, com referência a `SUMMARY.md`.
+9. Se VERIFY OK e estado coerente → **spec** ou **quick** para **próxima** entrega, ou mensagem “fluxo da feature atual concluído”.
 
-Responder em formato fixo:
+**Saída obrigatória (só isto, nesta ordem):**
 
-- **Próximo passo:** `scan` | `spec` | `discuss` | `plan` | `quick` | `execute` | `verify` (Cursor: `/oxe-discuss`, …; `oxe:discuss`, …)
-- **Por quê:** …
-- **Artefatos em jogo:** (lista curta)
+- **Próximo passo:** um único entre `scan` | `spec` | `discuss` | `plan` | `quick` | `execute` | `verify`
+- **Comando:** o slash correspondente (ex.: `/oxe-scan`) **ou** `npx oxe-cc status` para conferir de novo
+- **Por quê:** uma frase
+- **Artefatos em jogo:** lista curta (máx. 4 itens)
 </process>
+
+<success_criteria>
+- [ ] Foi indicado **exatamente um** próximo passo entre os valores canónicos (`scan`, `spec`, `discuss`, `plan`, `quick`, `execute`, `verify`) ou mensagem explícita de fluxo concluído.
+- [ ] A justificativa é **uma** frase; não há lista equiparável de alternativas como “próximo passo”.
+- [ ] O comando sugerido corresponde ao passo (slash `/oxe-*` ou `npx oxe-cc status` quando aplicável).
+- [ ] **Artefatos em jogo** tem no máximo quatro itens e são caminhos ou nomes reais em `.oxe/`.
+</success_criteria>

package/oxe/workflows/plan.md

@@ -3,20 +3,21 @@
 <objective>
 Produzir **`.oxe/PLAN.md`**: tarefas **pequenas**, **ondas** (paralelizáveis vs sequenciais), e **cada tarefa com bloco de verificação** (comando de teste e/ou checklist manual).
 
-Base: `.oxe/SPEC.md` + `.oxe/codebase/*` + código quando necessário (Grep/Read pontual).
+Base: `.oxe/SPEC.md` (critérios com IDs **A1**, **A2**, …) + `.oxe/codebase/*` + código quando necessário (Grep/Read pontual).
 
-Se o utilizador pedir **--replan** (ou replanejamento implícito após `verify_failed`):
+Se o usuário pedir **--replan** (ou replanejamento implícito após `verify_failed`):
 - Ler **`.oxe/VERIFY.md`** (gaps e falhas), **`.oxe/SUMMARY.md`** se existir, e o **PLAN.md** atual.
-- Preservar tarefas já concluídas ou renumerar com nota no **Replanejamento**; não apagar histórico útil do ficheiro — deslocar para a secção **Replanejamento** e reescrever a secção **Tarefas** conforme necessário.
-- Se **SUMMARY.md** não existir, criar a partir de `oxe/templates/SUMMARY.template.md` só para registar o contexto do replan (ou append se já existir).
+- Preservar tarefas já concluídas ou renumerar com nota em **Replanejamento**; não apagar histórico útil — deslocar para a seção **Replanejamento** e reescrever **Tarefas** conforme necessário.
+- Se **SUMMARY.md** não existir, criar a partir de `oxe/templates/SUMMARY.template.md` para registrar o contexto do replan (ou dar append se já existir).
 </objective>
 
 <context>
-- Não inventar APIs inexistentes: cruzar com **STRUCTURE.md**, **INTEGRATIONS.md** e ficheiros reais; respeitar **CONCERNS.md** (evitar agravar dívida conhecida sem tarefa explícita).
-- Se existir **`.oxe/DISCUSS.md`**, alinhar tarefas às decisões registadas.
+- 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/DISCUSS.md`**, alinhar tarefas às decisões registradas.
 - Se existir **`.oxe/config.json`** com `default_verify_command` não vazio, usar como fallback quando a SPEC não indicar comando.
+- Se existir **`plan_max_tasks_per_wave` > 0** na config, **não** colocar mais tarefas do que esse número na mesma **Onda**; dividir em mais ondas.
 - Tamanho alvo: cada tarefa cabe em **um** contexto de agente focado.
-- Id das tarefas: `T1`, `T2`, … estáveis para referência em verify.
+- IDs das tarefas: `T1`, `T2`, … estáveis para referência no verify.
 </context>
 
 <format_plan>
@@ -31,22 +32,22 @@ Cada tarefa em PLAN.md deve seguir:
 - **Verificar:**
   - Comando: `...` (ex.: npm test, pytest, mvn test)
   - Manual: (opcional) passos breves
-- **Aceite vinculado:** (números dos critérios na SPEC)
+- **Aceite vinculado:** A1, A2 (IDs exatos da tabela de critérios da SPEC)
 ```
 </format_plan>
 
 <process>
 1. Ler `.oxe/SPEC.md` (obrigatório). Se faltar, pedir **spec** primeiro.
-2. Se `.oxe/config.json` tiver `discuss_before_plan: true` e **não** existir `.oxe/DISCUSS.md` com decisões fechadas, pedir **discuss** antes de planear.
+2. Se `.oxe/config.json` tiver `discuss_before_plan: true` e **não** existir `.oxe/DISCUSS.md` com decisões fechadas, pedir **discuss** antes de planejar.
 3. Ler `.oxe/codebase/*.md` (incl. CONVENTIONS / CONCERNS) e inspecionar pontos de entrada se a spec exigir.
-4. Escrever ou atualizar `.oxe/PLAN.md` usando `oxe/templates/PLAN.template.md` como cabeçalho; em **--replan**, preencher a secção **Replanejamento** (data, motivo, lições de VERIFY/SUMMARY, tarefas removidas/alteradas).
-5. Definir ondas: onda 1 = tarefas sem dependência entre si; onda seguinte = dependentes.
-6. Atualizar `.oxe/STATE.md`: fase `plan_ready`, próximo passo executar PLAN depois **verify** (ou **execute**).
+4. Escrever ou atualizar `.oxe/PLAN.md` usando `oxe/templates/PLAN.template.md` como cabeçalho; em **--replan**, preencher a seção **Replanejamento** (data, motivo, lições de VERIFY/SUMMARY, tarefas removidas/alteradas).
+5. Definir ondas: onda 1 = tarefas sem dependência entre si; onda seguinte = dependentes; respeitar `plan_max_tasks_per_wave` se configurado.
+6. Atualizar `.oxe/STATE.md`: fase `plan_ready`, próximo passo `oxe:execute` (implementar ondas) e depois `oxe:verify`.
 7. Listar no chat: ondas, contagem de tarefas, comando de teste guarda-chuva se houver.
 </process>
 
 <success_criteria>
 - [ ] Cada tarefa tem seção **Verificar** com comando ou checklist explícito.
 - [ ] Dependências entre tarefas estão explícitas.
-- [ ] Critérios da SPEC mapeados para tarefas ou marcados como gap.
+- [ ] Cada critério da SPEC (IDs **A***) está mapeado em **Aceite vinculado** de alguma tarefa ou explicitamente marcado como gap no plano.
 </success_criteria>

package/oxe/workflows/quick.md

@@ -1,32 +1,45 @@
-# OXE — Workflow: quick
-
-<objective>
-Registar trabalho **rápido a médio** sem SPEC/PLAN completos: objetivo claro, passos curtos e uma verificação. Saída principal: **`.oxe/QUICK.md`** + atualização de **`.oxe/STATE.md`**.
-
-Usar quando: correção pontual, refactor local, uma feature pequena, ou protótipo que **não** justifica critérios de aceite longos.
-
-**Promover para fluxo completo** (spec → plan) se: tocar em **mais de ~8 ficheiros**, alterar **contrato público** (API, schema, eventos), ou houver **risco de segurança/dados**.
-</objective>
-
-<context>
-- Ler `.oxe/STATE.md` e, se existirem, `OVERVIEW.md` e `STACK.md` em `.oxe/codebase/` para não contradizer o repo.
-- Não apagar `SPEC.md` / `PLAN.md` se existirem; este fluxo é paralelo ou temporário.
-</context>
-
-<process>
-1. Garantir `.oxe/` (usar `oxe/templates/STATE.md` só se `STATE.md` não existir).
-2. Criar ou substituir **`.oxe/QUICK.md`** com:
-   - **Objetivo** — uma frase.
-   - **Contexto** — 2–5 bullets (ficheiros/pastas já vistos).
-   - **Passos** — lista numerada, **máximo 10** passos acionáveis.
-   - **Verificar** — pelo menos um: comando de terminal (ex. `npm test`) **ou** checklist manual explícito.
-   - **Promover para spec/plan?** — sim/não + critério (uma linha).
-3. Atualizar **`.oxe/STATE.md`**: fase `quick_active`, próximo passo `oxe:execute` ou implementação manual + `oxe:verify` (se usares plano completo depois, volta a `oxe:spec`).
-4. Responder no chat com resumo em ≤8 linhas e o comando de verificação escolhido.
-</process>
-
-<success_criteria>
-- [ ] `.oxe/QUICK.md` existe com passos e bloco **Verificar**.
-- [ ] `STATE.md` reflete fase `quick_active` e próximo passo coerente.
-- [ ] Fica explícito quando **não** usar quick (promoção a spec/plan).
-</success_criteria>
+# OXE — Workflow: quick
+
+<objective>
+Registrar trabalho **rápido a médio** sem SPEC/PLAN completos: objetivo claro, passos curtos e uma verificação. Saída principal: **`.oxe/QUICK.md`** + atualização de **`.oxe/STATE.md`**.
+
+Usar quando: correção pontual, refactor local, uma feature pequena, ou protótipo que **não** justifica critérios de aceite longos.
+</objective>
+
+<context>
+- Ler `.oxe/STATE.md` e, se existirem, `OVERVIEW.md` e `STACK.md` em `.oxe/codebase/` para não contradizer o repo.
+- Não apagar `SPEC.md` / `PLAN.md` se existirem; este fluxo é paralelo ou temporário.
+</context>
+
+## Quando promover para spec + plan (obrigatório declarar no QUICK.md)
+
+Promova **nesta sessão ou na próxima** se **qualquer** condição for verdadeira:
+
+- Mais de **~8 arquivos** tocados ou previstos.
+- Mudança de **contrato público** (API HTTP, schema de dados exposto, eventos, SDK).
+- **Segurança**, **dados pessoais**, **auth** ou **conformidade** envolvidos.
+- O próprio quick ficar com **mais de 10 passos** — dividir ou passar a SPEC.
+
+No final de **`.oxe/QUICK.md`**, mantenha a linha:
+
+- **Promover para spec/plan?** `sim` | `não` + **uma linha** com o critério que aplicou.
+
+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).
+2. Criar ou substituir **`.oxe/QUICK.md`** com:
+   - **Objetivo** — uma frase.
+   - **Contexto** — 2–5 bullets (arquivos/pastas já vistos).
+   - **Passos** — lista numerada, **máximo 10** passos acionáveis.
+   - **Verificar** — pelo menos um: comando de terminal (ex.: `npm test`) **ou** checklist manual explícito.
+   - **Promover para spec/plan?** — conforme seção acima.
+3. Atualizar **`.oxe/STATE.md`**: fase `quick_active`, próximo passo `oxe:execute` ou implementação manual + `oxe:verify`.
+4. Responder no chat com resumo em ≤8 linhas e o comando de verificação escolhido; se promover = sim, destacar **`/oxe-spec`** como próximo passo lógico.
+</process>
+
+<success_criteria>
+- [ ] `.oxe/QUICK.md` existe com passos e bloco **Verificar**.
+- [ ] `STATE.md` reflete fase `quick_active` e próximo passo coerente.
+- [ ] Fica explícito quando **promover** para spec/plan (regra acima + campo no arquivo).
+</success_criteria>

package/oxe/workflows/review-pr.md

@@ -6,40 +6,40 @@ Rever alterações como num pull request: **URL do GitHub** (`…/pull/<n>`), **
 
 <context>
 - **Base** e **head** são nomes de branch, tags ou SHAs (ex.: `main` e `feature/foo`).
-- **URL de PR no GitHub** — O utilizador pode colar o link da PR (ex.: `https://github.com/org/repo/pull/10` ou atalho `org/repo#10`). O número da PR é o segmento depois de `/pull/`.
+- **URL de PR no GitHub** — O usuário pode colar o link (ex.: `https://github.com/org/repo/pull/10` ou atalho `org/repo#10`). O número da PR é o segmento depois de `/pull/`.
 - Em Git, o diff “estilo PR” (só o que a branch introduz) usa o **merge base**: `git diff base...head` (três pontos).
-- Diff literal entre pontas: `git diff base..head` (dois pontos) — útil quando o utilizador pede explicitamente.
-- Este passo é **opcional** no fluxo OXE; não atualiza `STATE.md` com fases canónicas, salvo o utilizador pedir registo do resultado em disco.
+- Diff literal entre pontas: `git diff base..head` (dois pontos) — útil quando o usuário pede explicitamente.
+- Este passo é **opcional** no fluxo OXE; não atualiza `STATE.md` com fases canônicas, salvo se o usuário pedir registro do resultado em disco.
 </context>
 
 <process>
 1. **Resolver entrada**
-   - **URL ou `#` de PR** — Se a mensagem contiver um URL `github.com/.../pull/<n>` (com ou sem `https://`, com sufixo `/files` ou `/commits`) ou texto `owner/repo#n`, extrair `<n>` (e opcionalmente `owner/repo` para confirmar que o clone local é o mesmo repositório).
+   - **URL ou `#` de PR** — Se a mensagem contiver URL `github.com/.../pull/<n>` (com ou sem `https://`, com sufixo `/files` ou `/commits`) ou texto `owner/repo#n`, extrair `<n>` (e opcionalmente `owner/repo` para confirmar que o clone local é o mesmo repositório).
    - **Refs explícitas** — Caso contrário, tratar como base/head: se faltar um dos dois, inferir base = `main` ou `master` (o que existir) e head = branch atual (`git rev-parse --abbrev-ref HEAD`), ou pedir clarificação.
 2. **Obter diff (com URL / número de PR)** — Ordem de preferência quando o cwd é o repositório certo:
    - **GitHub CLI:** `gh pr diff <n>` (ou `gh pr diff <n> --patch`). Se `gh` não estiver disponível ou falhar auth, tentar Git puro.
    - **Git fetch ref da PR:** `git fetch origin pull/<n>/head:oxe-pr-<n>` (ajustar `origin` se o remoto tiver outro nome). Descobrir branch base com `gh pr view <n> --json baseRefName -q .baseRefName` ou assumir `main`/`master`; depois `git diff origin/<base>...oxe-pr-<n>` ou `git diff <base>...oxe-pr-<n>` após `fetch` da base.
-   - **Sem terminal / outro repo:** Pedir ao utilizador que cole o diff da aba “Files changed” no GitHub ou o output de `gh pr diff <n>` corrido localmente no repo certo.
+   - **Sem terminal / outro repo:** Pedir ao usuário que cole o diff da aba “Files changed” no GitHub ou o output de `gh pr diff <n>` rodado localmente no repo certo.
 3. **Obter diff (só branches / SHAs)** — Preferir terminal quando disponível:
    - `git fetch` (se fizer sentido e o ambiente permitir rede).
    - `git merge-base base head` (opcional, para confirmar ancestral comum).
    - `git diff base...head` (revisão tipo PR).
    - `git log base..head --oneline -n 30` (contexto de commits).
-   Se o sandbox bloquear Git, pedir ao utilizador que cole o output de `git diff base...head` ou use o diff da UI do GitHub/GitLab.
+   Se o sandbox bloquear Git, pedir ao usuário que cole o output de `git diff base...head` ou use o diff da UI do GitHub/GitLab.
    Se o diff já foi obtido no passo 2 (URL da PR), **não** repetir este passo.
 4. **Ler contexto do projeto** — Se existirem, usar trechos relevantes de `.oxe/codebase/CONVENTIONS.md`, `STACK.md`, `OVERVIEW.md` e, se aplicável, `.oxe/SPEC.md` / `.oxe/PLAN.md` para alinhar expectativas (sem assumir que o PR cobre só OXE).
 5. **Analisar** — Estruturar a resposta com:
    - **Resumo** — O que muda em 3–6 frases.
-   - **Ficheiros / áreas** — Agrupar por domínio (API, UI, config, etc.).
-   - **Riscos** — Regressões, breaking changes, segurança (inputs, segredos, auth), performance óbvia, migrações.
-   - **Testes** — O que deveria ser coberto ou correr localmente (comandos sugeridos se conhecidos do repo).
+   - **Arquivos / áreas** — Agrupar por domínio (API, UI, config, etc.).
+   - **Riscos** — Regressões, breaking changes, segurança (inputs, segredos, auth), desempenho óbvio, migrações.
+   - **Testes** — O que deveria ser coberto ou rodar localmente (comandos sugeridos se conhecidos do repo).
    - **Checklist PR** — Título sugerido, descrição curta, breaking changes, rollback.
-6. **Opcional em disco** — Se o utilizador pedir registo: criar ou atualizar **`.oxe/PR-REVIEW.md`** com data, URL ou refs (base/head), resumo, achados e próximos passos (formato Markdown legível).
+6. **Opcional em disco** — Se o usuário pedir registro: criar ou atualizar **`.oxe/PR-REVIEW.md`** com data, URL ou refs (base/head), resumo, achados e próximos passos (Markdown legível).
 </process>
 
-<success>
+<success_criteria>
 - [ ] URL da PR ou par base/head está explícito na resposta (ou foi pedida clarificação).
 - [ ] A análise baseia-se no diff (terminal ou colado), não só em suposições.
-- [ ] Há secção de riscos e de testes/verificação sugerida.
+- [ ] Há seção de riscos e de testes/verificação sugerida.
 - [ ] Nenhum segredo ou credencial é repetido na análise; redigir se aparecerem no diff.
-</success>
+</success_criteria>

package/oxe/workflows/scan.md

@@ -1,36 +1,38 @@
 # OXE — Workflow: scan
 
 <objective>
-Analisar o codebase e produzir documentação **estruturada e enxuta** em `.oxe/codebase/`, atualizando `.oxe/STATE.md`. Cada documento deve ser navegável por humanos e por agentes sem carregar o repo inteiro no contexto.
+Analisar o codebase e produzir documentação **estruturada e enxuta** em `.oxe/codebase/`, atualizando `.oxe/STATE.md`. Cada documento deve ser navegável por humanos e por agentes sem carregar o repositório inteiro no contexto.
 
-**Foco opcional:** se o utilizador indicar uma área (ex. `api`, `auth`), priorizar essa pasta ou módulo nos mapeamentos.
+**Foco opcional:** se o usuário indicar uma área (ex.: `api`, `auth`), priorizar essa pasta ou módulo nos mapeamentos.
+
+Se **`.oxe/config.json`** tiver `scan_focus_globs` ou `scan_ignore_globs`, **priorizar** os caminhos do foco e **reduzir detalhe** nas áreas ignoradas (ainda assim mencionar que existem).
 </objective>
 
 <context>
 - Diretório de saída: **`.oxe/`** na raiz do projeto (não `.planning/`).
 - Se `.oxe/` não existir, criar.
-- Carregar `oxe/templates/STATE.md` como base se `STATE.md` ainda não existir; caso exista, preservar histórico útil e atualizar seção **Último scan** e **Fase**.
-- Se existir **`.oxe/config.json`**, respeitar preferências (ex. comandos por defeito documentados em `oxe/templates/CONFIG.md`); não sobrescrever o ficheiro no scan.
-- Não apagar `SPEC.md` / `PLAN.md` se já existirem — apenas atualizar codebase.
+- Carregar `oxe/templates/STATE.md` (ou `.oxe` relativo aos workflows instalados) como base se `STATE.md` ainda não existir; se existir, preservar histórico útil e atualizar **Último scan** (campo **Data:** em formato ISO **YYYY-MM-DD** quando possível, para o `oxe-cc doctor` calcular scan antigo) e **Fase**.
+- Se existir **`.oxe/config.json`**, respeitar preferências documentadas em `oxe/templates/CONFIG.md`; **não** sobrescrever o arquivo no scan.
+- Não apagar `SPEC.md` / `PLAN.md` se já existirem — apenas atualizar o codebase.
 </context>
 
 <process>
 1. Garantir pastas `.oxe/` e `.oxe/codebase/`.
-2. Inventariar o repo (Glob/Grep): linguagens, manifests (`package.json`, `pom.xml`, `go.mod`, etc.), pastas principais.
+2. Inventariar o repo (Glob/Grep): linguagens, manifests (`package.json`, `pom.xml`, `go.mod`, etc.), pastas principais — aplicando foco/ignore da config se houver.
 3. Produzir **sete** arquivos em `.oxe/codebase/` (paralelize subagentes quando disponível):
    - **OVERVIEW.md** — propósito aparente do projeto, módulos de alto nível, fluxo principal (5–15 tópicos).
    - **STACK.md** — runtime, frameworks, build, versões relevantes, dependências críticas.
    - **STRUCTURE.md** — árvore lógica (não listar mil arquivos): entrypoints, `src/` por domínio, onde ficam testes e configs.
    - **TESTING.md** — como rodar testes/lint/format (comandos exatos), frameworks de teste, pastas `*test*`, CI se houver.
-   - **INTEGRATIONS.md** — APIs externas, bases de dados, auth, filas, segredos (nomes de env **sem valores**), webhooks. Se não houver integrações, escrever explicitamente *Não detetado* com uma linha de contexto.
+   - **INTEGRATIONS.md** — APIs externas, bancos, auth, filas, segredos (nomes de env **sem valores**), webhooks. Se não houver integrações, escrever explicitamente *Não detectado* com uma linha de contexto.
    - **CONVENTIONS.md** — estilo de código (naming, formatação, imports), padrões de erros/logging, organização de módulos; **prescreve** o que seguir em novas alterações (com paths em backticks).
-   - **CONCERNS.md** — dívida técnica, áreas frágeis, riscos de segurança/performance, dependências sensíveis; cada item com impacto breve e **ficheiros** referenciados.
-4. Atualizar **`.oxe/STATE.md`**: data do scan, fase sugerida `scan_complete`, próximo passo recomendado `oxe:spec` ou `oxe:plan` se já houver SPEC.
+   - **CONCERNS.md** — dívida técnica, áreas frágeis, riscos de segurança/desempenho, dependências sensíveis; cada item com impacto breve e **arquivos** referenciados.
+4. Atualizar **`.oxe/STATE.md`**: **Data** do scan (ISO), fase sugerida `scan_complete`, próximo passo `oxe:spec` ou `oxe:plan` se já houver SPEC.
 5. Resumir em 5–10 linhas no chat: o que foi escrito e o próximo passo sugerido.
 </process>
 
 <success_criteria>
-- [ ] `.oxe/codebase/OVERVIEW.md`, `STACK.md`, `STRUCTURE.md`, `TESTING.md`, `INTEGRATIONS.md`, `CONVENTIONS.md`, `CONCERNS.md` existem e têm conteúdo útil.
-- [ ] `.oxe/STATE.md` reflete último scan e próximo passo.
+- [ ] Os sete arquivos em `.oxe/codebase/` existem e têm conteúdo útil.
+- [ ] `.oxe/STATE.md` reflete último scan (com **Data** preenchida quando possível) e próximo passo.
 - [ ] Comandos de teste em TESTING.md foram validados ou marcados como “não verificado” se o ambiente não permitir rodar.
 </success_criteria>

package/oxe/workflows/spec.md

@@ -1,11 +1,11 @@
 # OXE — Workflow: spec
 
 <objective>
-Registrar a intenção do utilizador em **`.oxe/SPEC.md`**: escopo, critérios de aceite mensuráveis, não-objetivos e suposições. A spec deve ser o contrato antes do plano.
+Registrar a intenção do usuário em **`.oxe/SPEC.md`**: escopo, **critérios de aceite com IDs estáveis (A1, A2, …)** e coluna **Como verificar**, não objetivos e suposições. A spec é o contrato antes do plano.
 
-Para trabalho **muito pequeno**, o utilizador pode preferir **`oxe:quick`** (`.oxe/QUICK.md`) em vez deste fluxo — não bloqueies: se pedirem explicitamente quick, redireciona.
+Para trabalho **muito pequeno**, o usuário pode preferir **`oxe:quick`** (`.oxe/QUICK.md`) em vez deste fluxo — não bloqueie: se pedirem explicitamente quick, redirecione.
 
-Se **`.oxe/config.json`** tiver `discuss_before_plan: true`, mencionar no fim da resposta que o próximo passo recomendado é **`oxe:discuss`** antes do plano.
+Se **`.oxe/config.json`** tiver `discuss_before_plan: true`, mencionar no fim que o próximo passo recomendado é **`oxe:discuss`** antes do plano.
 
 Entrada: texto livre na mensagem ou caminho `@arquivo.md` / anexo para incorporar PRD/notas.
 </objective>
@@ -14,24 +14,25 @@ Entrada: texto livre na mensagem ou caminho `@arquivo.md` / anexo para incorpora
 **Pré-requisito:** preferencialmente **scan** já executado. Se não existir scan, mencionar na spec que o mapa está pendente.
 
 Leia `.oxe/STATE.md` e, se existirem, trechos relevantes de `.oxe/codebase/OVERVIEW.md` e `STACK.md` para não contradizer o projeto real.
+
+Use o template **`oxe/templates/SPEC.template.md`**: tabela **Critérios de aceite** com colunas **ID | Critério | Como verificar**.
 </context>
 
 <process>
-1. Resolver entrada: se começar com `@`, ler ficheiro; senão usar o texto da conversa.
-2. Criar ou atualizar **`.oxe/SPEC.md`** usando `oxe/templates/SPEC.template.md` como esqueleto (substituir placeholders).
-3. Incluir seções obrigatórias:
+1. Resolver entrada: se começar com `@`, ler arquivo; senão usar o texto da conversa.
+2. Criar ou atualizar **`.oxe/SPEC.md`** usando `oxe/templates/SPEC.template.md` como esqueleto.
+3. Garantir seções:
    - **Objetivo** — uma frase clara.
-   - **Escopo** — bullet in / out.
-   - **Critérios de aceite** — verificáveis (Given/When/Then ou checklist numerado).
-   - **Não-objetivos** — o que não será feito.
-   - **Suposições e riscos** — dependências técnicas ou de produto.
-   - **Referências** — paths/arquivos tocados se já conhecidos.
-4. Atualizar **`.oxe/STATE.md`**: fase `spec_ready`, próximo passo `oxe:plan`.
+   - **Escopo** — bullets dentro / fora.
+   - **Critérios de aceite** — tabela com IDs **A1**, **A2**, … (testáveis).
+   - **Suposições e riscos**.
+   - **Referências** — paths se conhecidos.
+4. Atualizar **`.oxe/STATE.md`**: fase `spec_ready`, próximo passo `oxe:discuss` ou `oxe:plan` conforme `discuss_before_plan`.
 5. Responder com resumo da spec e no máximo 3 perguntas objetivas se algo crítico estiver ambíguo.
 </process>
 
 <success_criteria>
-- [ ] `.oxe/SPEC.md` existe e critérios de aceite são testáveis ou observáveis.
+- [ ] `.oxe/SPEC.md` existe e cada critério tem ID **A*** e forma de verificar.
 - [ ] `STATE.md` atualizado.
-- [ ] Ambiguidades críticas foram perguntadas ou registradas como suposição explícita.
+- [ ] Ambiguidades críticas foram perguntas ou registradas como suposição explícita.
 </success_criteria>