oxe-cc 0.3.6 → 0.3.7

package/.cursor/commands/oxe-checkpoint.md

@@ -0,0 +1,9 @@
+---
+description: "OXE — Checkpoint nomeado (.oxe/checkpoints/ + índice)"
+---
+
+Executa o workflow **OXE checkpoint** no repositório atual. Lê e aplica **integralmente**:
+
+`oxe/workflows/checkpoint.md`
+
+O **primeiro** argumento deve ser o **slug** (ex. `pre-migracao-api`); o resto é nota livre.

package/.cursor/commands/oxe-compact.md

@@ -0,0 +1,9 @@
+---
+description: "OXE — refresh .oxe/codebase vs repo + CODEBASE-DELTA + RESUME"
+---
+
+Executa o workflow **OXE compact** no repositório atual. Lê e aplica **integralmente**:
+
+`oxe/workflows/compact.md`
+
+Atualiza os **sete** mapas em **`.oxe/codebase/`** (incremental ou bootstrap como scan), gera **`.oxe/CODEBASE-DELTA.md`** e **`.oxe/RESUME.md`**. Texto extra do utilizador: foco ou decisões/bloqueios a incluir no RESUME.

package/.cursor/commands/oxe-debug.md

@@ -0,0 +1,9 @@
+---
+description: "OXE — Debug técnico durante execute (DEBUG.md, hipótese/evidência)"
+---
+
+Executa o workflow **OXE debug** no repositório atual. Lê e aplica **integralmente**:
+
+`oxe/workflows/debug.md`
+
+Usa o texto adicional desta mensagem como sintoma, **Tn** do PLAN se souber, ou saída de erro.

package/.cursor/commands/oxe-forensics.md

@@ -0,0 +1,9 @@
+---
+description: "OXE — Diagnóstico pós-falha (FORENSICS.md + reingresso scan/plan/execute)"
+---
+
+Executa o workflow **OXE forensics** no repositório atual. Lê e aplica **integralmente**:
+
+`oxe/workflows/forensics.md`
+
+Usa o texto adicional desta mensagem como contexto do sintoma (falha de verify, doctor, estado incoerente).

package/.cursor/commands/oxe-plan-agent.md

@@ -0,0 +1,9 @@
+---
+description: "OXE — PLAN.md + plan-agents.json (plano orientado a agentes / ondas)"
+---
+
+Executa o workflow **OXE plan-agent**. Lê e aplica **integralmente**:
+
+`oxe/workflows/plan-agent.md` (na raiz do repositório em contexto)
+
+Se o utilizador pedir replanejamento, trata como **`--replan`** conforme o workflow.

package/.cursor/commands/oxe-research.md

@@ -0,0 +1,9 @@
+---
+description: "OXE — Pesquisa exploratória (.oxe/research/ + índice RESEARCH.md)"
+---
+
+Executa o workflow **OXE research** no repositório atual. Lê e aplica **integralmente**:
+
+`oxe/workflows/research.md`
+
+Usa o texto adicional desta mensagem como âmbito (paths, perguntas, spike, mapa de sistema, engenharia reversa ou modernização).

package/.cursor/commands/oxe-route.md

@@ -0,0 +1,9 @@
+---
+description: "OXE — Router: um pedido em linguagem natural → um comando/workflow"
+---
+
+Executa o workflow **OXE route** no repositório atual. Lê e aplica **integralmente**:
+
+`oxe/workflows/route.md`
+
+Usa o texto adicional desta mensagem como intenção a classificar (tabela Router em `help.md`).

package/.cursor/commands/oxe-ui-review.md

@@ -0,0 +1,9 @@
+---
+description: "OXE — Auditoria UI (UI-REVIEW.md) face ao UI-SPEC"
+---
+
+Executa o workflow **OXE ui-review** no repositório atual. Lê e aplica **integralmente**:
+
+`oxe/workflows/ui-review.md`
+
+Usa o texto adicional desta mensagem como ficheiros ou tarefas a rever.

package/.cursor/commands/oxe-ui-spec.md

@@ -0,0 +1,9 @@
+---
+description: "OXE — Contrato UI (UI-SPEC.md) a partir da SPEC"
+---
+
+Executa o workflow **OXE ui-spec** no repositório atual. Lê e aplica **integralmente**:
+
+`oxe/workflows/ui-spec.md`
+
+Usa o texto adicional desta mensagem como foco de ecrãs ou componentes, se houver.

package/.cursor/commands/oxe-validate-gaps.md

@@ -0,0 +1,9 @@
+---
+description: "OXE — Gaps de cobertura pós-verify (VALIDATION-GAPS.md)"
+---
+
+Executa o workflow **OXE validate-gaps** no repositório atual. Lê e aplica **integralmente**:
+
+`oxe/workflows/validate-gaps.md`
+
+Requer `VERIFY.md` e `PLAN.md` já existentes. Texto adicional: foco opcional em tarefa **Tn** ou critério **A***.

package/.github/copilot-instructions.md

@@ -14,18 +14,28 @@ Se o usuário mencionar **OXE**, **oxe**, **/oxe-**, ou pedidos como “mapear o
 | Spec | `oxe/workflows/spec.md` | “oxe spec”, “escrever SPEC.md”, “requisitos OXE” |
 | Discuss | `oxe/workflows/discuss.md` | “oxe discuss”, “perguntas antes do plano”, “DISCUSS.md” |
 | Plan | `oxe/workflows/plan.md` | “oxe plan”, “PLAN.md”, “plano com testes por tarefa”, “replan” |
+| Plan (agentes) | `oxe/workflows/plan-agent.md` | “plan agent”, “plan-agents.json”, “subagentes”, “ondas por agente”, blueprint de execução *(prompt: `/oxe-plan-agent`)* |
 | Quick | `oxe/workflows/quick.md` | “oxe quick”, “fix rápido OXE”, “QUICK.md” |
 | Execute | `oxe/workflows/execute.md` | “oxe execute”, “executar onda”, “onda 2 OXE” |
 | Verify | `oxe/workflows/verify.md` | “oxe verify”, “validar plano OXE”, “VERIFY.md” |
+| Validate gaps | `oxe/workflows/validate-gaps.md` | “validate gaps”, “Nyquist-lite”, “cobertura de critérios” após verify *(prompt: `/oxe-validate-gaps`)* |
 | Next | `oxe/workflows/next.md` | “oxe next”, “próximo passo OXE” |
 | Review PR | `oxe/workflows/review-pr.md` | “revisar PR”, link `…/pull/10`, “diff entre branches” *(prompt Copilot: `/oxe-review-pr`)* |
 | Help | `oxe/workflows/help.md` | “oxe help”, “como usar OXE” |
 | Update | `oxe/workflows/update.md` | “oxe update”, “atualizar oxe-cc”, “há versão nova no npm” *(prompt: `/oxe-update`)* |
+| Forensics | `oxe/workflows/forensics.md` | “oxe forensics”, “preso após verify”, “doctor falhou”, incoerência STATE/VERIFY *(prompt: `/oxe-forensics`)* |
+| Debug | `oxe/workflows/debug.md` | “oxe debug”, teste vermelho, stack trace durante implementação *(prompt: `/oxe-debug`)* |
+| Route | `oxe/workflows/route.md` | “que comando OXE uso”, desambiguar intenção *(prompt: `/oxe-route`)* |
+| Research | `oxe/workflows/research.md` | “oxe research”, mapa de sistema, spike, engenharia reversa, modernização *(prompt: `/oxe-research`)* |
+| Compact | `oxe/workflows/compact.md` | “oxe compact”, refresh `.oxe/codebase/` vs repo + `CODEBASE-DELTA.md` + `RESUME.md` *(prompt: `/oxe-compact`)* |
+| Checkpoint | `oxe/workflows/checkpoint.md` | “oxe checkpoint”, snapshot de sessão `.oxe/checkpoints/` *(prompt: `/oxe-checkpoint`)* |
+| UI spec | `oxe/workflows/ui-spec.md` | “UI-SPEC”, contrato de interface após spec *(prompt: `/oxe-ui-spec`)* |
+| UI review | `oxe/workflows/ui-review.md` | “auditoria UI”, UI-REVIEW *(prompt: `/oxe-ui-review`)* |
 | Autoria de workflow | `oxe/workflows/workflow-authoring.md` | “rever workflow OXE”, “revisar `oxe/workflows/foo.md` contra o guia”, alinhar passo ao `WORKFLOW_AUTHORING.md` |
 
 **Regra:** leia o Markdown indicado e execute **todos** os passos e critérios de sucesso descritos nesse arquivo. Não atalhe: crie ou atualize os arquivos em `.oxe/` conforme o workflow.
 
-**Cursor:** há slash `/oxe-*` para scan…help e **`/oxe-update`** em `~/.cursor/commands/`; **não** há comando slash dedicado a review-pr no Cursor — use linguagem natural + `oxe/workflows/review-pr.md` em contexto.
+**Cursor:** há slash `/oxe-*` para scan…help, **`/oxe-update`**, **`/oxe-forensics`**, **`/oxe-debug`**, **`/oxe-route`**, **`/oxe-research`**, **`/oxe-validate-gaps`**, **`/oxe-compact`**, **`/oxe-checkpoint`**, **`/oxe-ui-spec`**, **`/oxe-ui-review`** em `~/.cursor/commands/` (gerados a partir de `.github/prompts/` com `npm run sync:cursor` no pacote); **não** há comando slash dedicado a review-pr no Cursor — use linguagem natural + `oxe/workflows/review-pr.md` em contexto.
 
 ## Onde ficam as integrações (após `npx oxe-cc`)
 
@@ -36,20 +46,20 @@ Se o usuário mencionar **OXE**, **oxe**, **/oxe-**, ou pedidos como “mapear o
 
 ## Configuração do projeto
 
-- **`.oxe/config.json`**: fluxo (`discuss_before_plan`, `scan_max_age_days`, `spec_required_sections`, …) e opcionalmente **`install`** (perfil e layout quando o utilizador corre o instalador **sem** flags IDE explícitas). Referência: `oxe/templates/CONFIG.md`. Para ignorar o bloco `install` numa corrida: **`--no-install-config`**.
+- **`.oxe/config.json`**: fluxo (`discuss_before_plan`, `scan_max_age_days`, `compact_max_age_days`, `spec_required_sections`, …) e opcionalmente **`install`** (perfil e layout quando o utilizador corre o instalador **sem** flags IDE explícitas). Referência: `oxe/templates/CONFIG.md`. Para ignorar o bloco `install` numa corrida: **`--no-install-config`**.
 - **Legado / brownfield** (COBOL, JCL, copybooks, VB6, SQL procedures): seguir também `oxe/workflows/references/legacy-brownfield.md` quando o repo ou o pedido indicar mainframe ou desktop legado — scan preenche os sete ficheiros sem assumir Node; plan/verify aceitam evidência por Grep/leitura/checklist.
 - Sem TTY (CI): **`OXE_NO_PROMPT=1`** — padrões de layout/integração; o ficheiro `install` em `config.json` aplica-se se existir e as flags não sobrepuserem.
 
 ## Artefatos
 
-- `.oxe/STATE.md`, `.oxe/config.json` (opcional), `.oxe/codebase/*.md`, `.oxe/SPEC.md`, `.oxe/DISCUSS.md` (opcional), `.oxe/PLAN.md`, `.oxe/VERIFY.md`, `.oxe/QUICK.md`, `.oxe/SUMMARY.md` (opcional)
+- `.oxe/STATE.md`, `.oxe/config.json` (opcional), `.oxe/codebase/*.md`, `.oxe/SPEC.md`, `.oxe/DISCUSS.md` (opcional), `.oxe/PLAN.md`, `.oxe/plan-agents.json` (opcional, blueprint plan-agent; schema 2 com `runId` + `lifecycle`; **`/oxe-quick`** invalida), `.oxe/plan-agent-messages/` (opcional, handoffs agente→agente; ver `oxe/workflows/references/plan-agent-chat-protocol.md`), `.oxe/VERIFY.md`, `.oxe/QUICK.md`, `.oxe/SUMMARY.md` (opcional), `.oxe/NOTES.md`, `.oxe/RESUME.md`, `.oxe/CODEBASE-DELTA.md`, `.oxe/CHECKPOINTS.md`, `.oxe/checkpoints/*.md`, `.oxe/RESEARCH.md`, `.oxe/research/*.md`, `.oxe/VALIDATION-GAPS.md`, `.oxe/FORENSICS.md`, `.oxe/DEBUG.md`, `.oxe/UI-SPEC.md`, `.oxe/UI-REVIEW.md` (opcionais conforme trilha)
 - Templates: `oxe/templates/` (ou `.oxe/templates/` em layout aninhado)
 
 ## CLI e SDK
 
 - **`npx oxe-cc`** ou **`npx oxe-cc install`** — instalação (equivalentes).
 - **`npx oxe-cc doctor`** — validação completa (Node, workflows do pacote vs projeto, JSON, coerência STATE, regras SPEC/PLAN, **avisos** não bloqueantes sobre estrutura dos `.md` de workflow quando aplicável).
-- **`npx oxe-cc status`** — mais leve: coerência `.oxe/` + **um** próximo passo (não exige o mesmo rigor de workflows que o `doctor`). **`status --json`**: saída máquina-legível para CI (`nextStep`, `diagnostics`, …).
+- **`npx oxe-cc status`** — mais leve: coerência `.oxe/` + **um** próximo passo (não exige o mesmo rigor de workflows que o `doctor`). **`status --json`**: saída máquina-legível para CI (`nextStep`, `diagnostics`, `staleScan`, `staleCompact`, …). **`status --hints`**: lembretes de rotina (scan/compact antigos quando configurado); com **`--json --hints`** inclui o array **`hints`**.
 - **`npx oxe-cc init-oxe`**, **`uninstall`**, **`update`** — ver `oxe-cc --help` ou README do pacote.
 - **SDK (Node):** `require('oxe-cc')` expõe `runDoctorChecks`, `health`, `workflows`, `install`, `manifest`, `agents` — útil para CI (`lib/sdk/README.md`, `lib/sdk/index.d.ts`).
 

package/.github/prompts/oxe-checkpoint.prompt.md

@@ -0,0 +1,12 @@
+---
+name: oxe-checkpoint
+agent: agent
+description: OXE — Checkpoint nomeado (.oxe/checkpoints/ + índice)
+argument-hint: "<slug> [nota breve]"
+---
+
+Executa o workflow **OXE checkpoint** no repositório atual. Lê e aplica **integralmente**:
+
+`oxe/workflows/checkpoint.md`
+
+O **primeiro** argumento deve ser o **slug** (ex. `pre-migracao-api`); o resto é nota livre.

package/.github/prompts/oxe-compact.prompt.md

@@ -0,0 +1,11 @@
+---
+name: oxe-compact
+mode: agent
+description: OXE — refresh .oxe/codebase vs repo + CODEBASE-DELTA + RESUME
+---
+
+Executa o workflow **OXE compact** no repositório atual. Lê e aplica **integralmente**:
+
+`oxe/workflows/compact.md`
+
+Atualiza os **sete** mapas em **`.oxe/codebase/`** (incremental ou bootstrap como scan), gera **`.oxe/CODEBASE-DELTA.md`** e **`.oxe/RESUME.md`**. Texto extra do utilizador: foco ou decisões/bloqueios a incluir no RESUME.

package/.github/prompts/oxe-debug.prompt.md

@@ -0,0 +1,12 @@
+---
+name: oxe-debug
+agent: agent
+description: OXE — Debug técnico durante execute (DEBUG.md, hipótese/evidência)
+argument-hint: "[Tn opcional, stack ou comando que falhou]"
+---
+
+Executa o workflow **OXE debug** no repositório atual. Lê e aplica **integralmente**:
+
+`oxe/workflows/debug.md`
+
+Usa o texto adicional desta mensagem como sintoma, **Tn** do PLAN se souber, ou saída de erro.

package/.github/prompts/oxe-forensics.prompt.md

@@ -0,0 +1,12 @@
+---
+name: oxe-forensics
+agent: agent
+description: OXE — Diagnóstico pós-falha (FORENSICS.md + reingresso scan/plan/execute)
+argument-hint: "[contexto opcional do sintoma]"
+---
+
+Executa o workflow **OXE forensics** no repositório atual. Lê e aplica **integralmente**:
+
+`oxe/workflows/forensics.md`
+
+Usa o texto adicional desta mensagem como contexto do sintoma (falha de verify, doctor, estado incoerente).

package/.github/prompts/oxe-plan-agent.prompt.md

@@ -0,0 +1,10 @@
+---
+name: oxe-plan-agent
+description: "OXE — PLAN.md + plan-agents.json (plano orientado a agentes / ondas)"
+---
+
+Executa o workflow **OXE plan-agent**. Lê e aplica **integralmente**:
+
+`oxe/workflows/plan-agent.md` (na raiz do repositório em contexto)
+
+Se o utilizador pedir replanejamento, trata como **`--replan`** conforme o workflow.

package/.github/prompts/oxe-research.prompt.md

@@ -0,0 +1,12 @@
+---
+name: oxe-research
+agent: agent
+description: OXE — Pesquisa exploratória (.oxe/research/ + índice RESEARCH.md)
+argument-hint: "[âmbito, ex. módulo auth, mapa sistema, reversa]"
+---
+
+Executa o workflow **OXE research** no repositório atual. Lê e aplica **integralmente**:
+
+`oxe/workflows/research.md`
+
+Usa o texto adicional desta mensagem como âmbito (paths, perguntas, spike, mapa de sistema, engenharia reversa ou modernização).

package/.github/prompts/oxe-route.prompt.md

@@ -0,0 +1,12 @@
+---
+name: oxe-route
+agent: agent
+description: OXE — Router: um pedido em linguagem natural → um comando/workflow
+argument-hint: "[frase do utilizador]"
+---
+
+Executa o workflow **OXE route** no repositório atual. Lê e aplica **integralmente**:
+
+`oxe/workflows/route.md`
+
+Usa o texto adicional desta mensagem como intenção a classificar (tabela Router em `help.md`).

package/.github/prompts/oxe-ui-review.prompt.md

@@ -0,0 +1,12 @@
+---
+name: oxe-ui-review
+agent: agent
+description: OXE — Auditoria UI (UI-REVIEW.md) face ao UI-SPEC
+argument-hint: "[paths ou Tn opcional]"
+---
+
+Executa o workflow **OXE ui-review** no repositório atual. Lê e aplica **integralmente**:
+
+`oxe/workflows/ui-review.md`
+
+Usa o texto adicional desta mensagem como ficheiros ou tarefas a rever.

package/.github/prompts/oxe-ui-spec.prompt.md

@@ -0,0 +1,12 @@
+---
+name: oxe-ui-spec
+agent: agent
+description: OXE — Contrato UI (UI-SPEC.md) a partir da SPEC
+argument-hint: "[âmbito UI opcional]"
+---
+
+Executa o workflow **OXE ui-spec** no repositório atual. Lê e aplica **integralmente**:
+
+`oxe/workflows/ui-spec.md`
+
+Usa o texto adicional desta mensagem como foco de ecrãs ou componentes, se houver.

package/.github/prompts/oxe-validate-gaps.prompt.md

@@ -0,0 +1,12 @@
+---
+name: oxe-validate-gaps
+agent: agent
+description: OXE — Gaps de cobertura pós-verify (VALIDATION-GAPS.md)
+argument-hint: "[opcional: foco Tn ou A*]"
+---
+
+Executa o workflow **OXE validate-gaps** no repositório atual. Lê e aplica **integralmente**:
+
+`oxe/workflows/validate-gaps.md`
+
+Requer `VERIFY.md` e `PLAN.md` já existentes. Texto adicional: foco opcional em tarefa **Tn** ou critério **A***.

package/AGENTS.md

@@ -7,7 +7,7 @@ Este repositório empacota o fluxo **OXE** (spec-driven, artefatos em `.oxe/`).
 - **Instruções do repositório:** [.github/copilot-instructions.md](.github/copilot-instructions.md) — aplicadas automaticamente no **GitHub Copilot Chat** quando o repo está em contexto (outras ferramentas usam os seus próprios homes após `oxe-cc install`).
 - **CLI:** `oxe-cc` instala assets e bootstrap (`.oxe/STATE.md`, `config.json`, `codebase/`); `oxe-cc doctor` valida workflows, JSON de config, coerência STATE vs artefatos e regras opcionais de SPEC/PLAN; `oxe-cc status` mostra coerência `.oxe/` e **um** próximo passo; `oxe-cc init-oxe` só inicializa `.oxe/`.
 - **SDK:** `require('oxe-cc')` expõe `runDoctorChecks`, `health`, `workflows`, `install`, `manifest`, `agents` — ver [lib/sdk/README.md](lib/sdk/README.md).
-- **Prompt files (Copilot / VS Code):** [.github/prompts/*.prompt.md](.github/prompts/) — invocar com `/` no chat (ex. `/oxe-scan`, `/oxe-update`, `/oxe-review-pr` para diff tipo PR) após `chat.promptFiles` estar ativo.
+- **Prompt files (Copilot / VS Code):** [.github/prompts/*.prompt.md](.github/prompts/) — invocar com `/` no chat (ex. `/oxe-scan`, `/oxe-plan-agent`, `/oxe-forensics`, `/oxe-debug`, `/oxe-route`, `/oxe-research`, `/oxe-validate-gaps`, `/oxe-compact`, `/oxe-checkpoint`, `/oxe-ui-spec`, `/oxe-ui-review`, `/oxe-update`, `/oxe-review-pr` para diff tipo PR) após `chat.promptFiles` estar ativo. Cursor: `npm run sync:cursor` gera `.cursor/commands/` a partir destes prompts.
 - **Copilot CLI:** `oxe-cc --copilot-cli` → skills em **`~/.copilot/skills/`** (`/oxe`, `/oxe-scan`, …); após instalar use **`/skills reload`**. Cópia extra em `~/.claude/commands/` para compatibilidade.
 - **Multi-agente:** `oxe-cc --all-agents` replica comandos/skills nos homes de **OpenCode**, **Gemini**, **Codex**, **Windsurf**, **Antigravity** (além de Cursor, Copilot, Claude); ver `README.md` e `bin/lib/oxe-agent-install.cjs`.
 

package/README.md

@@ -55,7 +55,7 @@ No fim, em modo interativo, pergunta se você quer instalar o **`oxe-cc` globalm
 
 **GitHub Copilot CLI:** o CLI **não** trata `~/.copilot/commands/` como slash commands (isso é legado estilo Claude/Cursor). Com **`--copilot-cli`**, o OXE instala **agent skills** em **`~/.copilot/skills/`** (ex.: `oxe-scan/SKILL.md`, `oxe/SKILL.md`), invocáveis como **`/oxe-scan`**, **`/oxe`** (entrada = mesmo fluxo que `/oxe-help`), etc. Depois de instalar ou atualizar, use **`/skills reload`** ou reinicie o `copilot`. Mantém-se também cópia para **`~/.claude/commands/`** e **`~/.copilot/commands/`** para ferramentas que ainda leiam essa pasta. Se usar **`COPILOT_HOME`**, o `oxe-cc` grava skills nesse diretório (alinhado ao CLI oficial).
 
-**Multi-agente (`--all-agents`):** instalação **paralela** nos homes canónicos de cada ferramenta — **Cursor** e **Copilot** (como no padrão), **Claude Code** (`~/.claude/commands`), **OpenCode** (`$XDG_CONFIG_HOME/opencode/commands` e `~/.opencode/commands`), **Gemini CLI** (`~/.gemini/commands`: `/oxe`, `/oxe:scan` — depois **`/commands reload`**), **Codex** (`~/.agents/skills` + prompts em **`~/.codex/prompts`** como `/prompts:oxe-*`), **Windsurf** (`~/.codeium/windsurf/global_workflows`, workflows `/oxe-scan`), **Antigravity** (`~/.gemini/antigravity/skills`). No menu interativo, opção **6**. O núcleo do fluxo continua em **`.oxe/`** (SPEC/PLAN/VERIFY); não há `PROJECT.md` nem `research/` impostos pelo OXE.
+**Multi-agente (`--all-agents`):** instalação **paralela** nos homes canónicos de cada ferramenta — **Cursor** e **Copilot** (como no padrão), **Claude Code** (`~/.claude/commands`), **OpenCode** (`$XDG_CONFIG_HOME/opencode/commands` e `~/.opencode/commands`), **Gemini CLI** (`~/.gemini/commands`: `/oxe`, `/oxe:scan` — depois **`/commands reload`**), **Codex** (`~/.agents/skills` + prompts em **`~/.codex/prompts`** como `/prompts:oxe-*`), **Windsurf** (`~/.codeium/windsurf/global_workflows`, workflows `/oxe-scan`), **Antigravity** (`~/.gemini/antigravity/skills`). No menu interativo, opção **6**. O núcleo do fluxo continua em **`.oxe/`** (SPEC/PLAN/VERIFY e artefactos opcionais). O passo **research** (`research.md`, `.oxe/research/`, `RESEARCH.md`) é **opcional** e não faz parte da trilha mínima scan → spec → plan → execute → verify.
 
 **Confirmar instalação no agente**
 
@@ -102,8 +102,8 @@ No fim, em modo interativo, pergunta se você quer instalar o **`oxe-cc` globalm
 | Comando | Função |
 |---------|--------|
 | `oxe-cc` ou `oxe-cc install` | Instalação predefinida (mesmo comportamento; `install` é alias explícito) |
-| `oxe-cc doctor` | Valida Node, workflows do pacote, `.oxe/`, coerência STATE vs arquivos, scan antigo (`scan_max_age_days`), seções da SPEC, ondas do PLAN |
-| `oxe-cc status` | Leve: coerência `.oxe/` + **um** próximo passo sugerido (espelha o workflow `next`; não exige o conjunto completo de workflows como o `doctor`). **`--json`**: uma linha JSON com `nextStep`, `diagnostics`, etc., para CI ou scripts |
+| `oxe-cc doctor` | Valida Node, workflows do pacote, `.oxe/`, coerência STATE vs arquivos, scan/compact antigos (`scan_max_age_days`, `compact_max_age_days`), seções da SPEC, ondas do PLAN |
+| `oxe-cc status` | Leve: coerência `.oxe/` + **um** próximo passo sugerido (espelha o workflow `next`; não exige o conjunto completo de workflows como o `doctor`). **`--json`**: uma linha JSON com `nextStep`, `diagnostics`, `staleCompact`, etc. **`--hints`**: lembretes de rotina (scan/compact por idade). |
 | `oxe-cc init-oxe` | Só o bootstrap `.oxe/` (STATE, config, codebase) |
 | `oxe-cc uninstall` | Remove integrações OXE em `~/.cursor`, `~/.copilot`, `~/.claude` e pastas de workflows no repo (`--ide-only` só no HOME) |
 | `oxe-cc update` | Executa `npx oxe-cc@latest --force` na pasta do projeto; **`--check`** só consulta o npm; **`--if-newer`** evita o npx quando já está na última |
@@ -165,6 +165,8 @@ Gera **`.oxe/PLAN.md`**: tarefas **atômicas**, **ondas** (paralelo vs sequencia
 
 Ondas em resumo: tarefas **independentes** na mesma onda podem **rodar** em paralelo; **dependentes** vão para ondas posteriores (organização por ondas, com pouca cerimônia).
 
+**Variante plan-agent:** **`/oxe-plan-agent`** gera o mesmo **`.oxe/PLAN.md`** (com **Verificar** e **Aceite** por tarefa) **e** **`.oxe/plan-agents.json`** (schema **2**: `runId`, `lifecycle`): papéis (`role`), âmbito (`scope`), `inputs`/`outputs` sugeridos, dependências entre **agentes** e **`execution.waves`**. Handoffs entre agentes seguem **`oxe/workflows/references/plan-agent-chat-protocol.md`** (ficheiros em **`.oxe/plan-agent-messages/`**). Os papéis do blueprint são **exclusivos** da trilha **execute** desse plano (alinhados ao `runId` no **STATE**); **`/oxe-quick`** **invalida** o blueprint; trabalho fora das tarefas do **PLAN** não deve reutilizar essas personas.
+
 ### 5. Executar — implementação + `/oxe-execute` *(opcional)*
 
 Implemente no editor ou deixe o agente seguir **`/oxe-execute`** sobre o plano (ou QUICK). O OXE não impõe subagentes nem commits atômicos por tarefa; isso fica a cargo do **seu** fluxo com Git.
@@ -183,9 +185,9 @@ Para a **próxima** feature ou fase: de novo **spec → plan → …** ou **`/ox
 
 Para trabalho **ad hoc** sem roadmap completo:
 
-**`/oxe-quick`** gera **`.oxe/QUICK.md`** com passos curtos e verificação. Depois você pode usar **`/oxe-execute`** em cima disso ou implementar direto e fechar com **`/oxe-verify`**.
+**`/oxe-quick`** gera **`.oxe/QUICK.md`** com passos curtos e verificação. **Perfil fast:** objetivo numa frase, no máximo **10** passos — ver `oxe/workflows/quick.md`. Depois você pode usar **`/oxe-execute`** em cima disso ou implementar direto e fechar com **`/oxe-verify`**. Se existir um blueprint **`plan-agents.json`** (schema 2) ainda activo, o quick **invalida** esse blueprint (não reutiliza os agentes definidos para o plano).
 
-Se o trabalho crescer, **promova** para spec + plan completos.
+Se o trabalho crescer, **promova** para spec + plan completos (mesmos gatilhos: muitos ficheiros, API pública, segurança, etc.).
 
 ---
 
@@ -200,7 +202,11 @@ Se o trabalho crescer, **promova** para spec + plan completos.
 | `.oxe/SPEC.md` | O que entregar e como saber que está certo |
 | `.oxe/DISCUSS.md` | Preferências antes do plano *(opcional)* |
 | `.oxe/PLAN.md` | Tarefas atômicas + **Verificar** por item |
+| `.oxe/plan-agents.json` | Blueprint opcional (agentes + ondas) após **`/oxe-plan-agent`** |
 | `.oxe/QUICK.md` | Modo rápido |
+| `.oxe/NOTES.md` | Fila leve antes de discuss/plan *(opcional)* |
+| `.oxe/FORENSICS.md` / `.oxe/DEBUG.md` | Recuperação e debug *(opcional)* |
+| `.oxe/UI-SPEC.md` / `.oxe/UI-REVIEW.md` | Contrato e revisão UI *(opcional)* |
 | `.oxe/VERIFY.md` | Resultado das verificações |
 | `.oxe/SUMMARY.md` | Resumo para replanejamento *(opcional)* |
 | `oxe/workflows/*.md` ou `.oxe/workflows/*.md` | **Fonte única** dos passos no **projeto** após instalar (no **pacote** npm, os modelos vivem em `oxe/workflows/`) |
@@ -221,12 +227,22 @@ Slash commands (Cursor: `~/.cursor/commands/` após instalar) e prompt files (Co
 | `/oxe-spec` | [`spec.md`](oxe/workflows/spec.md) |
 | `/oxe-discuss` | [`discuss.md`](oxe/workflows/discuss.md) |
 | `/oxe-plan` | [`plan.md`](oxe/workflows/plan.md) |
+| `/oxe-plan-agent` | [`plan-agent.md`](oxe/workflows/plan-agent.md) |
 | `/oxe-quick` | [`quick.md`](oxe/workflows/quick.md) |
 | `/oxe-execute` | [`execute.md`](oxe/workflows/execute.md) |
 | `/oxe-verify` | [`verify.md`](oxe/workflows/verify.md) |
 | `/oxe-next` | [`next.md`](oxe/workflows/next.md) |
 | `/oxe-help` | [`help.md`](oxe/workflows/help.md) |
 | `/oxe-update` | [`update.md`](oxe/workflows/update.md) |
+| `/oxe-forensics` | [`forensics.md`](oxe/workflows/forensics.md) |
+| `/oxe-debug` | [`debug.md`](oxe/workflows/debug.md) |
+| `/oxe-route` | [`route.md`](oxe/workflows/route.md) |
+| `/oxe-research` | [`research.md`](oxe/workflows/research.md) |
+| `/oxe-validate-gaps` | [`validate-gaps.md`](oxe/workflows/validate-gaps.md) |
+| `/oxe-compact` | [`compact.md`](oxe/workflows/compact.md) |
+| `/oxe-checkpoint` | [`checkpoint.md`](oxe/workflows/checkpoint.md) |
+| `/oxe-ui-spec` | [`ui-spec.md`](oxe/workflows/ui-spec.md) |
+| `/oxe-ui-review` | [`ui-review.md`](oxe/workflows/ui-review.md) |
 | `/oxe-review-pr` *(prompt Copilot; ver nota abaixo)* | [`review-pr.md`](oxe/workflows/review-pr.md) |
 | *(mantenedores)* `workflow-authoring` em linguagem natural | [`workflow-authoring.md`](oxe/workflows/workflow-authoring.md) |
 
@@ -248,6 +264,14 @@ Slash commands (Cursor: `~/.cursor/commands/` após instalar) e prompt files (Co
 - **Limite:** Não implementa código; o plano e o verify é que amarram tarefas aos **A*** .
 - **Workflow:** [`oxe/workflows/spec.md`](oxe/workflows/spec.md)
 
+#### `/oxe-research`
+
+- **O que faz:** Cria uma **nota datada** em `.oxe/research/YYYY-MM-DD-<slug>.md` e atualiza **`.oxe/RESEARCH.md`** (índice/histórico); spikes, mapa de sistema, engenharia reversa, hipóteses de modernização ou qualquer exploração com evidência antes do plano.
+- **Artefatos:** `.oxe/research/*.md`, `.oxe/RESEARCH.md`, `.oxe/STATE.md` se útil.
+- **Quando usar:** Incerteza técnica ou de âmbito; sistemas grandes por progressive disclosure (várias sessões); opcional após **spec** e antes de **plan**.
+- **Limite:** Não substitui SPEC/PLAN; não sobrescreve notas antigas sem pedido explícito.
+- **Workflow:** [`oxe/workflows/research.md`](oxe/workflows/research.md)
+
 #### `/oxe-discuss`
 
 - **O que faz:** Regista perguntas, respostas e decisões em `.oxe/DISCUSS.md` (máx. 7 perguntas enxutas) antes do plano, alinhado à SPEC.
@@ -264,6 +288,22 @@ Slash commands (Cursor: `~/.cursor/commands/` após instalar) e prompt files (Co
 - **Limite:** Não executa as tarefas — isso é **execute** + o teu Git.
 - **Workflow:** [`oxe/workflows/plan.md`](oxe/workflows/plan.md)
 
+#### `/oxe-plan-agent`
+
+- **O que faz:** Igual ao plano OXE em **tarefas verificáveis** (`PLAN.md`), mais **`.oxe/plan-agents.json`** (schema **2**: `runId`, `lifecycle`): define **agentes** (papel, âmbito, `taskIds`, dependências, entradas/saídas sugeridas) e **`execution.waves`**. Cria **`.oxe/plan-agent-messages/`** (README + mensagens conforme [`references/plan-agent-chat-protocol.md`](oxe/workflows/references/plan-agent-chat-protocol.md)). Inclui gate de coerência entre JSON e `Tn`.
+- **Artefatos:** `.oxe/PLAN.md`, `.oxe/plan-agents.json`, `.oxe/plan-agent-messages/`, `.oxe/STATE.md` (`plan_ready` + secção blueprint).
+- **Quando usar:** Equipas que querem **roteiro explícito por “subagente”**, handoffs escritos entre ondas, ou ondas paralelas por domínio sem perder **Verificar** por tarefa.
+- **Limite:** Papéis do blueprint são **só** para **`/oxe-execute`** alinhado ao `PLAN.md` e `runId`; **`/oxe-quick`** invalida o blueprint; pedidos fora do plano não devem reutilizar essas personas.
+- **Workflow:** [`oxe/workflows/plan-agent.md`](oxe/workflows/plan-agent.md) · modelo JSON: [`oxe/templates/plan-agents.template.json`](oxe/templates/plan-agents.template.json) · schema: [`oxe/schemas/plan-agents.schema.json`](oxe/schemas/plan-agents.schema.json)
+
+#### `/oxe-ui-spec`
+
+- **O que faz:** Gera ou atualiza **`.oxe/UI-SPEC.md`**: contrato de UI/UX derivado da **SPEC** (âmbito, estados, acessibilidade, breakpoints, tokens quando aplicável).
+- **Artefatos:** `.oxe/UI-SPEC.md`, `.oxe/STATE.md` (nota de fase / próximo passo conforme o workflow).
+- **Quando usar:** Depois de **spec** e **antes** (ou em paralelo cognitivo) do **plan**, para entregas com interface; o **plan** pode referenciar secções do UI-SPEC nas tarefas de front.
+- **Limite:** Só faz sentido se houver UI; projetos só API/backend podem ignorar este passo. Não substitui a SPEC.
+- **Workflow:** [`oxe/workflows/ui-spec.md`](oxe/workflows/ui-spec.md)
+
 #### `/oxe-quick`
 
 - **O que faz:** Fluxo curto com `.oxe/QUICK.md` (passos numerados + verificar) para trabalho pontual sem SPEC/PLAN longos.
@@ -274,12 +314,20 @@ Slash commands (Cursor: `~/.cursor/commands/` após instalar) e prompt files (Co
 
 #### `/oxe-execute`
 
-- **O que faz:** Guia a implementação **onda a onda** com base em `PLAN.md` (ou passos de `QUICK.md`), com checklist explícito e atualização de `.oxe/STATE.md` (progresso Tn / ondas).
+- **O que faz:** Guia a implementação **onda a onda** com base em `PLAN.md` (ou passos de `QUICK.md`), com checklist explícito e atualização de `.oxe/STATE.md` (progresso Tn / ondas). Com blueprint **válido** (`lifecycle` + `runId` alinhado ao STATE), aplica papéis do JSON só às tarefas do plano e regista handoffs em **`.oxe/plan-agent-messages/`** quando agentes dependem uns dos outros.
 - **Artefatos:** Código/docs que implementas; `.oxe/STATE.md` (checklist de onda).
 - **Quando usar:** Durante a execução do plano ou do QUICK, para não saltar pré-requisitos nem verificações da onda.
 - **Limite:** Não faz commits nem impõe subagentes — fica a teu critério de equipa.
 - **Workflow:** [`oxe/workflows/execute.md`](oxe/workflows/execute.md)
 
+#### `/oxe-ui-review`
+
+- **O que faz:** Produz **`.oxe/UI-REVIEW.md`**: auditoria da implementação face ao **UI-SPEC** (checklist, bloqueios P0/P1, sugestões), tipicamente após trabalho de front e **antes** ou como entrada para o **verify** global.
+- **Artefatos:** `.oxe/UI-REVIEW.md`, `.oxe/STATE.md` se útil.
+- **Quando usar:** Depois de implementar ecrãs/componentes cobertos pelo UI-SPEC; se não existir `UI-SPEC.md`, o workflow pede **ui-spec** primeiro ou regista revisão *ad hoc* (menos ideal).
+- **Limite:** Não substitui **`/oxe-verify`** — o verify continua a cruzar SPEC, PLAN, evidência técnica e, quando existir, UI-REVIEW.
+- **Workflow:** [`oxe/workflows/ui-review.md`](oxe/workflows/ui-review.md)
+
 #### `/oxe-verify`
 
 - **O que faz:** Corre ou orienta verificação: comandos do PLAN, confronto de **cada** critério **A*** da SPEC com evidência, registo em `.oxe/VERIFY.md`; opcionalmente rascunho de commit e checklist de PR conforme `.oxe/config.json`.
@@ -288,6 +336,56 @@ Slash commands (Cursor: `~/.cursor/commands/` após instalar) e prompt files (Co
 - **Limite:** Sandbox pode impedir comandos — regista “não executado aqui” e deixa o comando para correres localmente.
 - **Workflow:** [`oxe/workflows/verify.md`](oxe/workflows/verify.md)
 
+#### `/oxe-validate-gaps`
+
+- **O que faz:** Auditoria **complementar** pós-verify: cruza PLAN + VERIFY (+ SPEC), lista gaps de cobertura/evidência em **`.oxe/VALIDATION-GAPS.md`** e sugere tarefas em texto (Nyquist-lite).
+- **Artefatos:** `.oxe/VALIDATION-GAPS.md`, opcionalmente `STATE.md`.
+- **Quando usar:** Depois de **`/oxe-verify`** (passou ou falhou), para fechar dívida de testes ou evidência fraca.
+- **Limite:** Não altera `PLAN.md` por defeito nem substitui um novo verify após correções.
+- **Workflow:** [`oxe/workflows/validate-gaps.md`](oxe/workflows/validate-gaps.md)
+
+#### `/oxe-compact`
+
+- **O que faz:** **Rotina de projeto inteiro:** compara **`.oxe/codebase/*.md`** ao repositório **atual**, **atualiza** os sete mapas (incrementalmente se já existirem; geração completa alinhada a **`scan.md`** se faltar base), escreve **`.oxe/CODEBASE-DELTA.md`** (o que mudou na documentação face à versão anterior) e **`.oxe/RESUME.md`** (trilha OXE + ligação ao delta). **Independente** de limites de chat ou de qualquer comando de “compact” de IDE.
+- **Artefatos:** `.oxe/codebase/*.md`, `.oxe/CODEBASE-DELTA.md`, `.oxe/RESUME.md`; bloco opcional **Último compact** em `STATE.md`.
+- **Quando usar:** Fim de sprint, após refactors grandes, quando o mapa OXE “cheira” a desatualizado, ou em cadência que a equipa definir — **sem** substituir um **`/oxe-scan`** completo logo após clonar ou quando tudo mudou de raiz.
+- **Limite:** Não substitui SPEC/PLAN/VERIFY. Para **marco de sessão** nomeado, usar **`/oxe-checkpoint`**.
+- **Workflow:** [`oxe/workflows/compact.md`](oxe/workflows/compact.md)
+
+#### `/oxe-checkpoint`
+
+- **O que faz:** **Snapshot de sessão / trilha:** cria **`.oxe/checkpoints/YYYY-MM-DD-HHmm-<slug>.md`** com frontmatter (`linked` para artefactos) e atualiza **`.oxe/CHECKPOINTS.md`** (índice, mais recente primeiro).
+- **Artefatos:** `.oxe/checkpoints/*.md`, `.oxe/CHECKPOINTS.md`.
+- **Quando usar:** Antes de mudanças arriscadas, troca de ramo mental, ou fim de dia — marco **nomeado** sem apagar contratos. Contrasta com **`/oxe-compact`**, que atualiza o **mapa do projeto inteiro** (`codebase/` + delta + RESUME).
+- **Limite:** Não é `git commit`; não altera SPEC/PLAN por defeito; **não** substitui o refresh de `codebase/` do compact.
+- **Workflow:** [`oxe/workflows/checkpoint.md`](oxe/workflows/checkpoint.md)
+
+**Momentos chave (rotina):** antes de spike ou branch longa → checkpoint; após migração de stack ou fim de feature/PR → compact; fim de dia a meio trabalho → checkpoint. Tabela completa e `compact_max_age_days` em [`oxe/workflows/help.md`](oxe/workflows/help.md) (secção *Momentos chave*).
+
+#### `/oxe-forensics`
+
+- **O que faz:** Diagnóstico **pós-falha** ou incoerência (verify falhou, `doctor` em erro, STATE vs artefatos); escreve **`.oxe/FORENSICS.md`** com linha do tempo, hipótese de causa e **um** próximo passo canónico: **scan**, **plan** ou **execute** (nunca “fim” sem reentrada na trilha).
+- **Artefatos:** `.oxe/FORENSICS.md`, opcionalmente linha em `STATE.md`.
+- **Quando usar:** Preso após várias tentativas, drift de workflows, PLAN vs VERIFY inconsistente.
+- **Limite:** Recomenda; não apaga SPEC/PLAN sem decisão explícita tua.
+- **Workflow:** [`oxe/workflows/forensics.md`](oxe/workflows/forensics.md)
+
+#### `/oxe-debug`
+
+- **O que faz:** Ciclo **hipótese → experiência → evidência** durante o **execute** (teste vermelho, stack, regressão); regista sessões em **`.oxe/DEBUG.md`**, ligadas a **Tn** quando existir.
+- **Artefatos:** `.oxe/DEBUG.md` (append por sessão datada).
+- **Quando usar:** Dificuldade **técnica** no meio do plano; se o problema for requisito ambíguo, preferir **`/oxe-discuss`** e depois **plan**.
+- **Limite:** Corrigir com debug **não** dispensa **`/oxe-verify`** para fechar a trilha.
+- **Workflow:** [`oxe/workflows/debug.md`](oxe/workflows/debug.md)
+
+#### `/oxe-route`
+
+- **O que faz:** Meta-only: mapeia linguagem natural → **exatamente um** comando/workflow (tabela em **help**); não gera SPEC nem PLAN.
+- **Artefatos:** Nenhum obrigatório.
+- **Quando usar:** “Que comando OXE uso para…?” sem quereres escolher à mão.
+- **Limite:** Só orientação; a execução é o passo apontado (`/oxe-scan`, `/oxe-forensics`, etc.).
+- **Workflow:** [`oxe/workflows/route.md`](oxe/workflows/route.md)
+
 #### `/oxe-next`
 
 - **O que faz:** Sugere o **único** próximo passo lógico com base nos artefactos `.oxe/` (equivalente conceptual ao que o terminal faz com `npx oxe-cc status`, sem validar o pacote de workflows completo).
@@ -342,9 +440,10 @@ Comandos no terminal na **raiz do projeto** (ou `--dir`). Útil em CI, scripts e
 | Subcomando | Poder principal |
 |------------|-----------------|
 | `oxe-cc` / `oxe-cc install` | Copia **workflows** e **templates** para `.oxe/` (layout mínimo) ou `oxe/` + `.oxe/` (`--global`), e instala integrações IDE/CLI conforme flags (`--cursor`, `--copilot`, `--all-agents`, …). |
-| `oxe-cc doctor` | Validação **completa**: versão Node, diff workflows **pacote npm ↔ projeto**, parse de `.oxe/config.json`, coerência de **STATE** com arquivos esperados, scan antigo (`scan_max_age_days`), seções obrigatórias da SPEC, ondas do PLAN, avisos de estrutura dos `.md` de workflow, e **planWarn** (inclui tarefas **Tn** sem `**Aceite vinculado:**`). |
+| `oxe-cc doctor` | Validação **completa**: versão Node, diff workflows **pacote npm ↔ projeto**, parse de `.oxe/config.json`, coerência de **STATE** com arquivos esperados, scan/compact antigos (`scan_max_age_days`, `compact_max_age_days`), seções obrigatórias da SPEC, ondas do PLAN, avisos de estrutura dos `.md` de workflow, e **planWarn** (inclui tarefas **Tn** sem `**Aceite vinculado:**`). |
 | `oxe-cc status` | Diagnóstico **mais leve**: mesma leitura de saúde `.oxe/` + config + **um único** próximo passo sugerido (`suggestNextStep`) — não exige o mesmo conjunto de checks pesados do `doctor` sobre o pacote. |
-| `oxe-cc status --json` | Igual ao `status`, mas imprime **uma linha JSON** (`oxeStatusSchema`, `nextStep`, `cursorCmd`, `reason`, `artifacts`, `phase`, `diagnostics.*`) para pipelines e agentes automáticos. Sem banner quando `--json`. |
+| `oxe-cc status --json` | Igual ao `status`, mas imprime **uma linha JSON** (`oxeStatusSchema: 2`, `nextStep`, `cursorCmd`, `reason`, `artifacts`, `phase`, `scanDate`, `staleScan`, `compactDate`, `staleCompact`, `diagnostics.*`) para pipelines e agentes automáticos. Sem banner quando `--json`. |
+| `oxe-cc status --hints` | Agrega lembretes de rotina (idade do scan e do compact quando configurados). Com **`--json --hints`**, inclui o array **`hints`**. |
 | `oxe-cc init-oxe` | Apenas **bootstrap** de `.oxe/STATE.md`, `.oxe/config.json` e pasta `.oxe/codebase/` — sem reinstalar integrações nas tuas pastas home. |
 | `oxe-cc update` | Corre `npx oxe-cc@latest --force` no projeto (ou equivalente) para alinhar workflows/templates; **`--check`** só compara versão no npm; **`--if-newer`** evita o npx se já estiveres na última. |
 | `oxe-cc uninstall` | Por omissão remove integrações em `~/.cursor`, `~/.copilot`, … **e** pastas de workflows no projeto (`.oxe/workflows`, `oxe/`, `commands/oxe`, …). **`--ide-only`** não remove workflows no repo (só integrações no HOME). **`--ide-local`** também remove integrações OXE **dentro** do repositório (`.cursor`, `.github`, `.claude`, `.copilot`, …). |
@@ -355,7 +454,7 @@ Comandos no terminal na **raiz do projeto** (ou `--dir`). Útil em CI, scripts e
 
 ## Configuração
 
-Preferências do projeto em **`.oxe/config.json`** (criado no bootstrap a partir de `oxe/templates/config.template.json`). Inclui opções de fluxo (`discuss_before_plan`, `scan_max_age_days`, `spec_required_sections`, …) e, opcionalmente, o bloco **`install`** (perfil de integração e layout do repo quando corres o instalador sem flags IDE). Referência completa: [`oxe/templates/CONFIG.md`](oxe/templates/CONFIG.md).
+Preferências do projeto em **`.oxe/config.json`** (criado no bootstrap a partir de `oxe/templates/config.template.json`). Inclui opções de fluxo (`discuss_before_plan`, `scan_max_age_days`, `compact_max_age_days`, `spec_required_sections`, …) e, opcionalmente, o bloco **`install`** (perfil de integração e layout do repo quando corres o instalador sem flags IDE). Referência completa: [`oxe/templates/CONFIG.md`](oxe/templates/CONFIG.md). Hooks Git opt-in: [`oxe/templates/GIT_HOOKS_OXE.md`](oxe/templates/GIT_HOOKS_OXE.md).
 
 Repositórios **legado** (COBOL, JCL, copybooks, VB6, stored procedures): os workflows **scan**, **spec**, **plan**, **execute** e **verify** delegam padrões de análise e verificação em [`.oxe/workflows/references/legacy-brownfield.md`](oxe/workflows/references/legacy-brownfield.md) após `npx oxe-cc` (no pacote fonte: [`oxe/workflows/references/legacy-brownfield.md`](oxe/workflows/references/legacy-brownfield.md)).
 

package/bin/lib/oxe-project-health.cjs

@@ -10,6 +10,7 @@ const ALLOWED_CONFIG_KEYS = [
   'after_verify_draft_commit',
   'default_verify_command',
   'scan_max_age_days',
+  'compact_max_age_days',
   'scan_focus_globs',
   'scan_ignore_globs',
   'spec_required_sections',
@@ -46,6 +47,7 @@ function loadOxeConfigMerged(targetProject) {
     after_verify_draft_commit: true,
     default_verify_command: '',
     scan_max_age_days: 0,
+    compact_max_age_days: 0,
     scan_focus_globs: [],
     scan_ignore_globs: [],
     spec_required_sections: [],
@@ -112,6 +114,9 @@ function validateConfigShape(cfg) {
   if (cfg.scan_max_age_days != null && typeof cfg.scan_max_age_days !== 'number') {
     typeErrors.push('scan_max_age_days deve ser número (use 0 para desligar aviso de scan antigo)');
   }
+  if (cfg.compact_max_age_days != null && typeof cfg.compact_max_age_days !== 'number') {
+    typeErrors.push('compact_max_age_days deve ser número (use 0 para desligar aviso de compact antigo)');
+  }
   if (cfg.plan_max_tasks_per_wave != null && typeof cfg.plan_max_tasks_per_wave !== 'number') {
     typeErrors.push('plan_max_tasks_per_wave deve ser número (use 0 para desligar)');
   }
@@ -158,6 +163,29 @@ function parseLastScanDate(stateText) {
   return null;
 }
 
+/**
+ * Data do último `/oxe-compact` em STATE.md (secção **Último compact**).
+ * @param {string} stateText
+ * @returns {Date | null}
+ */
+function parseLastCompactDate(stateText) {
+  const sec = stateText.match(/##\s*Último compact[^\n]*\s*([\s\S]*?)(?=\n## |\n#[^\#]|$)/im);
+  if (!sec) return null;
+  const dm = sec[1].match(/\*\*Data:\*\*\s*(.+)/i);
+  if (!dm) return null;
+  let raw = dm[1].trim();
+  if (/^\([^)]*\)$/.test(raw) || /placeholder|legível|YYYY-MM-DD/i.test(raw)) return null;
+  if (raw.startsWith('(')) return null;
+  const iso = Date.parse(raw);
+  if (!Number.isNaN(iso)) return new Date(iso);
+  const br = raw.match(/^(\d{1,2})\/(\d{1,2})\/(\d{4})/);
+  if (br) {
+    const d = new Date(parseInt(br[3], 10), parseInt(br[2], 10) - 1, parseInt(br[1], 10));
+    return Number.isNaN(d.getTime()) ? null : d;
+  }
+  return null;
+}
+
 /**
  * @param {Date | null} scanDate
  * @param {number} maxAgeDays 0 = desligado
@@ -442,6 +470,8 @@ function buildHealthReport(target) {
   const phase = parseStatePhase(stateText);
   const scanDate = parseLastScanDate(stateText);
   const stale = isStaleScan(scanDate, Number(config.scan_max_age_days) || 0);
+  const compactDate = parseLastCompactDate(stateText);
+  const staleCompact = isStaleScan(compactDate, Number(config.compact_max_age_days) || 0);
   const phaseWarn = phase ? phaseCoherenceWarnings(phase, p) : [];
   const sumWarn = verifyGapsWithoutSummaryWarning(p.verify, p.summary);
   const specReq = Array.isArray(config.spec_required_sections) ? config.spec_required_sections : [];
@@ -460,6 +490,8 @@ function buildHealthReport(target) {
     phase,
     scanDate,
     stale,
+    compactDate,
+    staleCompact,
     phaseWarn,
     summaryGapWarn: sumWarn,
     specWarn,
@@ -480,6 +512,7 @@ module.exports = {
   validateConfigShape,
   parseStatePhase,
   parseLastScanDate,
+  parseLastCompactDate,
   isStaleScan,
   phaseCoherenceWarnings,
   verifyGapsWithoutSummaryWarning,