oxe-cc 0.6.0 → 0.6.4

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

@@ -0,0 +1,11 @@
+---
+description: "OXE — Retrospectiva de ciclo: 3–5 lições prescritivas em .oxe/LESSONS.md para ciclos futuros"
+---
+
+OXE — Retrospectiva de ciclo: 3–5 lições prescritivas em .oxe/LESSONS.md para ciclos futuros
+
+Executa o workflow **OXE retro** no repositório atual. Lê e aplica **integralmente**:
+
+`oxe/workflows/retro.md`
+
+Lê VERIFY.md, FORENSICS.md, SUMMARY.md. `$ARGUMENTS` = contexto extra opcional.

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

@@ -1,12 +1,12 @@
----
-name: oxe-loop
-agent: agent
-description: OXE — Loop iterativo por onda com retries automáticos e diagnóstico inline
-argument-hint: "onda <N> [max:<tentativas>]"
----
-
-Executa o workflow **OXE loop** no repositório atual. Lê e aplica **integralmente**:
-
-`oxe/workflows/loop.md`
-
-`$ARGUMENTS` = onda alvo e máximo de tentativas (ex.: `onda 2 max:5`). Pré-requisito: `.oxe/PLAN.md`.
+---
+name: oxe-loop
+agent: agent
+description: OXE — Loop iterativo por onda com retries automáticos e diagnóstico inline
+argument-hint: "onda <N> [max:<tentativas>]"
+---
+
+Executa o workflow **OXE loop** no repositório atual. Lê e aplica **integralmente**:
+
+`oxe/workflows/loop.md`
+
+`$ARGUMENTS` = onda alvo e máximo de tentativas (ex.: `onda 2 max:5`). Pré-requisito: `.oxe/PLAN.md`.

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

@@ -1,12 +1,12 @@
----
-name: oxe-project
-agent: agent
-description: OXE — Gestão de projeto unificada: milestone, workstream e checkpoint
-argument-hint: "milestone new <nome> | workstream switch <nome> | checkpoint [slug]"
----
-
-Executa o workflow **OXE project** no repositório atual. Lê e aplica **integralmente**:
-
-`oxe/workflows/project.md`
-
-`$ARGUMENTS` = subcomando: `milestone new|complete|status|audit`, `workstream new|switch|list|close <nome>`, `checkpoint [slug]`, ou vazio para status atual.
+---
+name: oxe-project
+agent: agent
+description: OXE — Gestão de projeto unificada: milestone, workstream e checkpoint
+argument-hint: "milestone new <nome> | workstream switch <nome> | checkpoint [slug]"
+---
+
+Executa o workflow **OXE project** no repositório atual. Lê e aplica **integralmente**:
+
+`oxe/workflows/project.md`
+
+`$ARGUMENTS` = subcomando: `milestone new|complete|status|audit`, `workstream new|switch|list|close <nome>`, `checkpoint [slug]`, ou vazio para status atual.

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

@@ -0,0 +1,12 @@
+---
+name: oxe-retro
+agent: agent
+description: OXE — Retrospectiva de ciclo: 3–5 lições prescritivas em .oxe/LESSONS.md para ciclos futuros
+argument-hint: "[opcional: contexto extra sobre o ciclo — o que foi mais difícil, o que surpreendeu]"
+---
+
+Executa o workflow **OXE retro** no repositório atual. Lê e aplica **integralmente**:
+
+`oxe/workflows/retro.md`
+
+Lê VERIFY.md, FORENSICS.md, SUMMARY.md. `$ARGUMENTS` = contexto extra opcional.

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

@@ -1,12 +1,12 @@
----
-name: oxe-security
-agent: agent
-description: OXE — Auditoria de segurança OWASP (.oxe/SECURITY.md): P0/P1/P2 vinculados ao stack
-argument-hint: "[opcional: categoria OWASP, módulo ou arquivo de foco]"
----
-
-Executa o workflow **OXE security** no repositório atual. Lê e aplica **integralmente**:
-
-`oxe/workflows/security.md`
-
-Lê `.oxe/codebase/STACK.md` para determinar categorias OWASP aplicáveis. `$ARGUMENTS` = foco opcional.
+---
+name: oxe-security
+agent: agent
+description: OXE — Auditoria de segurança OWASP (.oxe/SECURITY.md): P0/P1/P2 vinculados ao stack
+argument-hint: "[opcional: categoria OWASP, módulo ou arquivo de foco]"
+---
+
+Executa o workflow **OXE security** no repositório atual. Lê e aplica **integralmente**:
+
+`oxe/workflows/security.md`
+
+Lê `.oxe/codebase/STACK.md` para determinar categorias OWASP aplicáveis. `$ARGUMENTS` = foco opcional.

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

@@ -1,12 +1,12 @@
----
-name: oxe
-agent: agent
-description: OXE — Entrada universal: próximo passo / roteamento / help dos 8 comandos essenciais
-argument-hint: "[contexto em linguagem natural | 'help' | vazio para próximo passo]"
----
-
-Executa o workflow **OXE** (entrada universal) no repositório atual. Lê e aplica **integralmente**:
-
-`oxe/workflows/oxe.md`
-
-`$ARGUMENTS`: vazio → próximo passo; texto → roteamento; "help" → 8 comandos essenciais.
+---
+name: oxe
+agent: agent
+description: OXE — Entrada universal: próximo passo / roteamento / help dos 8 comandos essenciais
+argument-hint: "[contexto em linguagem natural | 'help' | vazio para próximo passo]"
+---
+
+Executa o workflow **OXE** (entrada universal) no repositório atual. Lê e aplica **integralmente**:
+
+`oxe/workflows/oxe.md`
+
+`$ARGUMENTS`: vazio → próximo passo; texto → roteamento; "help" → 8 comandos essenciais.

package/AGENTS.md

@@ -2,13 +2,80 @@
 
 Este repositório empacota o fluxo **OXE** (spec-driven, artefatos em `.oxe/`). O núcleo é agnóstico; o **`oxe-cc`** integra com **várias IDEs e CLIs** (Cursor e GitHub Copilot como caminho padrão conhecido, mais Claude, OpenCode, Gemini, Codex, Windsurf, Antigravity quando instalado com **`--all-agents`** ou flags granulares).
 
-- **npm:** o nome do pacote é **`oxe-cc`** (`npx oxe-cc@latest` quando estiver publicado; se `npm view oxe-cc` der 404, usar `npm link` a partir deste repo ou `node bin/oxe-cc.js`).
-- **Workflows canónicos:** [oxe/workflows/](oxe/workflows/) — editar aqui primeiro; todas as integrações apontam para estes ficheiros (inclui `quick.md`, `execute.md`). Referência **legado / brownfield:** [oxe/workflows/references/legacy-brownfield.md](oxe/workflows/references/legacy-brownfield.md) (COBOL, JCL, copybooks, VB6, SP).
-- **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/`.
+- **npm:** `npx oxe-cc@latest` · pacote `oxe-cc` · [README.md](README.md)
+- **Workflows canónicos:** [oxe/workflows/](oxe/workflows/) — editar aqui primeiro; todas as integrações apontam para estes ficheiros. Referência **legado / brownfield:** [oxe/workflows/references/legacy-brownfield.md](oxe/workflows/references/legacy-brownfield.md).
+- **CLI:** `oxe-cc install | doctor | status | init-oxe | update | uninstall` — ver [README.md](README.md#cli-oxe-cc).
 - **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-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`.
 
-Quando o utilizador pedir uma etapa OXE por linguagem natural, segue o ficheiro `oxe/workflows/<passo>.md` correspondente sem atalhar passos.
+---
+
+## Os 8 comandos essenciais
+
+```
+/oxe              → onde estou / o que faço / help
+/oxe-obs          → registrei algo importante (incorporado automaticamente)
+/oxe-quick        → tarefa pequena, sem cerimônia
+/oxe-scan         → mapeia o projeto (ou atualiza se já mapeado)
+/oxe-spec         → nova feature: perguntas → requisitos → roteiro
+/oxe-plan         → tarefas por onda (--agents para multi-agente)
+/oxe-execute      → implementar (A: 1 sessão | B: por onda | C: por tarefa)
+/oxe-verify       → validar (camadas 5+6 opcionais via config)
+```
+
+## Escape hatches (aparecem quando necessários)
+
+```
+/oxe-retro        → retrospectiva: 3–5 lições → .oxe/LESSONS.md
+/oxe-forensics    → diagnóstico de falha persistente ou estado corrompido
+/oxe-debug        → diagnóstico técnico inline (integrado ao execute)
+/oxe-loop         → retry iterativo de onda até verify passar
+/oxe-security     → auditoria OWASP Top 10 filtrada pelo stack
+/oxe-research     → spike, mapa de sistema, engenharia reversa
+/oxe-validate-gaps → auditoria de cobertura de testes
+/oxe-discuss      → decisões D-NN antes do plano (discuss_before_plan: true)
+/oxe-route        → traduz linguagem natural → comando OXE
+/oxe-compact      → refresh do mapa de codebase
+/oxe-checkpoint   → snapshot nomeado de sessão
+/oxe-ui-spec      → contrato UI/UX derivado da SPEC
+/oxe-ui-review    → auditoria de implementação UI
+/oxe-review-pr    → revisão de PR/diff
+/oxe-project      → milestone + workstream + checkpoint em um comando
+/oxe-update       → atualiza workflows para a versão mais recente
+```
+
+## Profiles de execução (`profile` em `.oxe/config.json`)
+
+| Profile | `discuss_before_plan` | `verification_depth` | `after_verify_suggest_uat` | `scan_max_age_days` |
+|---------|-----------------------|---------------------|---------------------------|---------------------|
+| `balanced` (padrão) | false | standard | false | 0 |
+| `strict` | true | thorough | true | 14 |
+| `fast` | false | quick | false | 0 |
+| `legacy` | true | thorough | true | 0 |
+
+Keys explícitas no `config.json` **prevalecem** sobre os valores do profile.
+
+## Plan-Driven Dynamic Agents (PDDA)
+
+Com `/oxe-plan --agents` (ou sugerido quando 3+ domínios detectados):
+- `runId` único por demanda — nunca reutilizado entre planos
+- `role` específico ao domínio desta entrega (não genérico)
+- `model_hint` por agente: `"fast"` / `"balanced"` / `"powerful"` (schema v3)
+- `persona` por agente: `executor`, `planner`, `verifier`, `researcher`, `debugger`, `architect`, `ui-specialist`, `db-specialist`
+- Execute exibe o `model_hint` ao iniciar cada agente para o usuário configurar o modelo
+
+Blueprints em `.oxe/plan-agents.json` (schema 3). Protocolo inter-agente: `oxe/workflows/references/plan-agent-chat-protocol.md`.
+
+## Personas de agentes (`oxe/personas/`)
+
+8 personas builtin: `executor`, `planner`, `verifier`, `researcher`, `debugger`, `architect`, `ui-specialist`, `db-specialist`. Personas customizadas do projeto ficam em `.oxe/personas/`.
+
+## Integrações IDE
+
+- **Cursor:** slash commands em `~/.cursor/commands/` (gerados por `npm run sync:cursor`)
+- **GitHub Copilot (VS Code):** prompt files em `~/.copilot/prompts/` + `copilot-instructions.md`
+- **Claude Code:** commands em `~/.claude/commands/`
+- **OpenCode / Gemini / Codex / Windsurf / Antigravity:** via `oxe-cc --all-agents`
+
+## Instruções para agentes de IA
+
+Quando o utilizador pedir uma etapa OXE por linguagem natural, seguir o ficheiro `oxe/workflows/<passo>.md` correspondente **sem atalhar passos**. Ler os artefatos em `.oxe/` antes de qualquer ação — nunca partir de suposições sobre o estado do projeto.

package/CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog — OXE CLI (`oxe-cc`)
+
+Todas as versões seguem [Semantic Versioning](https://semver.org/). As mudanças mais recentes aparecem primeiro.
+
+---
+
+## [0.6.3] — 2026-04-04
+
+### Corrigido
+- `security_in_verify` agora é reconhecido como chave válida em `.oxe/config.json` (não mais rejeitado pelo doctor como "unknown key")
+- `plan-agents.schema.json`: enum atualizado de `[1, 2]` para `[2, 3]`; campos `persona` e `model_hint` adicionados ao schema dos agentes
+
+### Adicionado
+- **`/oxe-retro` sugerido automaticamente** pelo `oxe-cc status` quando `phase: verify_complete` e `.oxe/LESSONS.md` ainda não existe
+- **`health.parseLastRetroDate(stateText)`** — parseia campo `last_retro: YYYY-MM-DD` do STATE.md
+- **`health.isStaleLessons(retroDate, maxDays)`** — detecta se LESSONS.md está desatualizado (par de `isStaleScan`)
+- **`health.planAgentsWarnings(target)`** — avisa sobre schema 1 (legado) e `model_hint` inválido em `plan-agents.json`
+- **`parseState()`** retorna novo campo `lastRetroDate: string | null`
+- `OxeHealthReport` inclui `retroDate: Date | null`
+- `config.template.json` inclui `security_in_verify: false` por padrão
+- `plan-agents.template.json` inclui campo `persona` no agente-exemplo
+- Melhorias de workflow: `obs.md` (tabela de classificação de impacto), `verify.md` (success_criteria camadas 5+6), `next.md` (flag de promoção QUICK→spec), `quick.md` (incorporação de OBSERVATIONS), `plan.md` (nota de replan + plan-agents sync)
+- `AGENTS.md` atualizado para v0.6.x
+
+### Tipos TypeScript
+- `ParsedState` inclui `lastRetroDate: string | null`
+- `OxeHealthReport` inclui `retroDate: Date | null`
+- `health.*` expõe `parseLastRetroDate`, `isStaleLessons`, `planAgentsWarnings`
+
+---
+
+## [0.6.2] — 2026-04-04
+
+### Adicionado
+- **`/oxe-retro`** — workflow de retrospectiva de ciclo; sintetiza 3–5 lições prescritivas em `.oxe/LESSONS.md`
+- `oxe/templates/LESSONS.template.md`
+- Correções de consistência de schema (plan-agent.md, verify.md): referências atualizadas para schema v3
+
+### Alterado
+- README: tabela "Como cada comando fica mais inteligente" expandida com loop, security, research thinking_depth, model_hint
+- Cadeia de help (`oxe.md`) atualizada para incluir `/oxe-retro` após verify
+
+---
+
+## [0.6.1] — 2026-04-04
+
+### Adicionado
+- **`/oxe-security`** — auditoria OWASP Top 10 filtrada pelo stack; produz `.oxe/SECURITY.md` com achados P0/P1/P2
+- **`/oxe-loop`** — execução iterativa de onda com retries automáticos e diagnóstico inline
+- **Model hints** em `plan-agents.json` schema v3: campo `model_hint` (`fast | balanced | powerful`) por agente
+- **Thinking depth** em `/oxe-research`: classificação `surface | standard | deep` com raciocínio estendido para `deep`
+- Integração automática de security no verify via `security_in_verify: true` (Camada 6)
+- `oxe/templates/SECURITY.template.md`
+
+---
+
+## [0.6.0] — 2026-04-04
+
+### Adicionado
+- Workflow `/oxe-project` unificando `milestone`, `workstream`, `checkpoint`
+- `/oxe-obs` com propagação automática para R-IDs e Tns afetados
+- Auto-reflexão semântica em `/oxe-spec` (Fase 4b): detecta contradições e escopo creep antes da aprovação
+- Modo de execução A/B/C em `/oxe-execute` (Completo / Por onda / Por tarefa)
+- Debug inline automático em falhas de execute
+- 4 profiles de execução: `balanced`, `strict`, `fast`, `legacy`
+- Sistema de personas para agentes (`oxe/personas/`)
+- Plugin lifecycle (`.oxe/plugins/*.cjs`)
+- `scale_adaptive`: scan sugere profile pelo tamanho do projeto
+
+---
+
+## [0.5.0] — anterior
+
+Versões anteriores não documentadas neste arquivo.