oxe-cc 0.3.2 → 0.3.4

package/.github/copilot-instructions.md

@@ -1,15 +1,15 @@
 # OXE — fluxo spec-driven (Cursor + Copilot)
 
-Este repositório define o **OXE**: artefatos em `.oxe/` na raiz do projeto alvo e workflows em `oxe/workflows/*.md`.
+Este repositório (ou o pacote **oxe-cc** instalado) define o **OXE**: artefatos em **`.oxe/`** na raiz do projeto alvo e workflows em **`oxe/workflows/*.md`** ou **`.oxe/workflows/*.md`**, conforme a instalação.
 
 ## Quando aplicar
 
-Se o utilizador mencionar **OXE**, **oxe**, **/oxe-**, ou pedidos como “mapear o projeto”, “criar spec OXE”, “plano OXE com testes”, “verificar OXE”, trata como fluxo OXE e segue o ficheiro de workflow correspondente abaixo.
+Se o usuário mencionar **OXE**, **oxe**, **/oxe-**, ou pedidos como “mapear o projeto”, “criar spec OXE”, “plano OXE com testes”, “verificar OXE”, trate como fluxo OXE e siga o arquivo de workflow correspondente abaixo.
 
 ## Workflows (fonte única)
 
-| Passo | Ficheiro | Gatilhos naturais (exemplos) |
-|-------|----------|----------------------------|
+| Passo | Arquivo | Gatilhos naturais (exemplos) |
+|-------|---------|-------------------------------|
 | Scan | `oxe/workflows/scan.md` | “oxe scan”, “mapear o repo”, “atualizar codebase OXE” |
 | 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” |
@@ -18,21 +18,27 @@ Se o utilizador mencionar **OXE**, **oxe**, **/oxe-**, ou pedidos como “mapear
 | Execute | `oxe/workflows/execute.md` | “oxe execute”, “executar onda”, “onda 2 OXE” |
 | Verify | `oxe/workflows/verify.md` | “oxe verify”, “validar plano OXE”, “VERIFY.md” |
 | 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”, “code review OXE” *(prompt: `/oxe-review-pr`)* |
+| Review PR | `oxe/workflows/review-pr.md` | “revisar PR”, link `…/pull/10`, “diff entre branches” *(prompt: `/oxe-review-pr` no Copilot)* |
 | Help | `oxe/workflows/help.md` | “oxe help”, “como usar OXE” |
 
-**Regra:** lê o Markdown indicado e executa **todos** os passos e critérios de sucesso descritos nesse ficheiro. Não atalhes: cria ou atualiza os ficheiros em `.oxe/` conforme o workflow.
+**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.
+
+## Onde ficam as integrações (após `npx oxe-cc`)
+
+- **Cursor:** comandos em **`~/.cursor/commands/`** (slash `/oxe-*`).
+- **GitHub Copilot (VS Code):** instruções mescladas em **`~/.copilot/copilot-instructions.md`** (bloco OXE) e **prompt files** em **`~/.copilot/prompts/`** (`oxe-*.prompt.md`). **Não** espere `.github/prompts/` no repositório do projeto para o Copilot — o instalador usa a pasta do **usuário**, alinhado ao GSD.
+- **Copilot CLI (experimental):** com `oxe-cc --copilot-cli`, textos também em **`~/.claude/commands/`** e **`~/.copilot/commands/`** — depende da versão do CLI.
 
 ## 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`
-- Templates: `oxe/templates/`
+- Templates: `oxe/templates/` (ou `.oxe/templates/` em layout aninhado)
 
-## Cursor vs Copilot
+## CLI útil
 
-- **Cursor:** slash commands em `.cursor/commands/oxe-*.md` apontam para os mesmos workflows.
-- **Copilot:** prompt files em `.github/prompts/oxe-*.prompt.md`; cada um indica o workflow em `oxe/workflows/<passo>.md` na raiz do repo. **`oxe-review-pr`** existe só como prompt Copilot (não há slash command Cursor correspondente).
+- **`npx oxe-cc doctor`** — validação completa (workflows do pacote, `config.json`, mapas, coerência STATE).
+- **`npx oxe-cc status`** — um único próximo passo sugerido + coerência `.oxe/`.
 
-## Manutenção deste pacote (oxe-build)
+## Manutenção do pacote oxe-build
 
-Ao alterar comportamento OXE, edita primeiro `oxe/workflows/*.md`; mantém comandos Cursor e prompts Copilot alinhados com essa pasta.
+Ao alterar comportamento OXE, edite primeiro **`oxe/workflows/*.md`**; mantenha comandos Cursor e prompts Copilot alinhados a essa pasta.

package/AGENTS.md

@@ -5,7 +5,8 @@ Este repositório empacota o fluxo **OXE** (spec-driven, artefatos em `.oxe/`).
 - **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`).
 - **Instruções do repositório:** [.github/copilot-instructions.md](.github/copilot-instructions.md) — aplicadas automaticamente no Copilot Chat quando o repo está em contexto.
 - **Workflows canónicos:** [oxe/workflows/](oxe/workflows/) — editar aqui primeiro; Cursor e Copilot apontam para estes ficheiros (inclui `quick.md`, `execute.md`).
-- **CLI:** `oxe-cc` instala assets e bootstrap (`.oxe/STATE.md`, `config.json`, `codebase/`); `oxe-cc doctor` valida workflows, JSON de config e mapa scan; `oxe-cc init-oxe` só inicializa `.oxe/`.
+- **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/`.
 - **Prompt files (Copilot / VS Code):** [.github/prompts/*.prompt.md](.github/prompts/) — invocar com `/` no chat (ex. `/oxe-scan`, `/oxe-review-pr` para diff tipo PR) após `chat.promptFiles` estar ativo.
+- **Copilot CLI (experimental):** `oxe-cc --copilot-cli` → `.claude/commands/oxe-*.md` para testar `/oxe-scan` no terminal.
 
 Quando o utilizador pedir uma etapa OXE por linguagem natural, segue o ficheiro `oxe/workflows/<passo>.md` correspondente sem atalhar passos.

package/README.md

@@ -4,7 +4,7 @@
   <img src="assets/readme-banner.svg" alt="OXE" width="920" />
 </p>
 
-**Fluxo spec-driven e context engineering para [Cursor](https://cursor.com) e [GitHub Copilot](https://github.com/features/copilot) — inspirado na ideia do [GSD](https://github.com/gsd-build/get-shit-done), com **menos comandos** e foco em **`.oxe/`** + **`oxe/workflows/`**.**
+**Fluxo spec-driven e context engineering para [Cursor](https://cursor.com) e [GitHub Copilot](https://github.com/features/copilot) — inspirado no [GSD](https://github.com/gsd-build/get-shit-done), com **menos comandos** e foco em **`.oxe/`** (workflows em **`.oxe/workflows/`** por padrão, ou **`oxe/workflows/`** com `--global`). Textos do CLI e resumos pós-comando estão em **português (Brasil)**.**
 
 [![npm](https://img.shields.io/npm/v/oxe-cc.svg?style=flat-square)](https://www.npmjs.com/package/oxe-cc)
 [![license](https://img.shields.io/npm/l/oxe-cc.svg?style=flat-square)](LICENSE)
@@ -13,7 +13,7 @@
 npx oxe-cc@latest
 ```
 
-**Manter atualizado:** `npx oxe-cc@latest --force` (na raiz do projeto).
+**Manter atualizado:** `npx oxe-cc@latest --force` ou `npx oxe-cc update` (na raiz do projeto). Com **`--force`**, alterações locais em arquivos rastreados geram backup em **`~/.oxe-cc/oxe-local-patches/`** (estilo GSD).
 
 [Para quem é](#para-quem-é) · [Começar](#começar) · [Como funciona](#como-funciona) · [Modo rápido](#modo-rápido) · [Porque funciona](#porque-funciona) · [Comandos](#comandos) · [Configuração](#configuração) · [Problemas](#resolução-de-problemas)
 
@@ -25,7 +25,7 @@ npx oxe-cc@latest
 
 Para quem quer **descrever o que quer e ver isso construído de forma consistente** — **sem** simular uma organização enorme de processos em cima do repositório.
 
-OXE é **enxuto**: não há dezenas de slash commands nem instalador multi-runtime. Há **um CLI** que copia ficheiros para o projeto, **workflows em Markdown** que o agente segue, e **estado em disco** para a sessão principal não “inchada” com tudo o que já foi decidido.
+OXE é **enxuto**: não há dezenas de slash commands. Há **um CLI** que deixa o repositório **só com `.oxe/`** (layout **padrão**) ou **`oxe/` + `.oxe/`** com **`--global`**, e instala integrações em **`~/.cursor`**, **`~/.copilot`** e **`~/.claude`** — **workflows em Markdown** e **estado em disco** para a sessão não ficar **sobrecarregada** com tudo o que já foi decidido.
 
 ---
 
@@ -33,43 +33,64 @@ OXE é **enxuto**: não há dezenas de slash commands nem instalador multi-runti
 
 **Requisito:** [Node.js 18+](https://nodejs.org/).
 
-Na **raiz do repositório** do teu projeto:
+Na **raiz do repositório** do seu projeto:
 
 ```bash
 npx oxe-cc@latest
 ```
 
-Isto copia, entre outros: **`oxe/`** (workflows + templates), **`.cursor/`** (slash commands), **`.github/`** (instruções Copilot + prompt files), **`commands/oxe/`** (atalhos estilo `oxe:*` para outros clientes), **`AGENTS.md`**, e cria um **`.oxe/`** mínimo (`STATE.md`, `config.json` a partir de template, pasta `codebase/`) — salvo flags como `--no-init-oxe`.
+Em **terminal interativo**, o instalador pergunta em dois passos (como no **GSD**): (1) **onde integrar** o OXE (Cursor, Copilot, só núcleo com `.oxe/`, etc.); (2) **layout no repositório** — **clássico** (`oxe/` na raiz + `.oxe/`, com opcional `commands/oxe/`, `AGENTS.md`) ou **mínimo** (**só `.oxe/`**, com **`.oxe/workflows/`** e templates). **Cursor, Copilot e CLI** usam **sempre** as pastas do **usuário** (`~/.cursor`, `~/.copilot`, `~/.claude`); **não** são criados `.cursor` / `.github` / `.claude` dentro do repo. Com layout clássico e **`--vscode`**, **`.vscode/`** fica no projeto.
+
+Ao terminar, o CLI mostra um **resumo do que foi criado ou atualizado** e **próximos passos sugeridos** (por exemplo `npx oxe-cc doctor`, `/oxe-scan`), no mesmo espírito do GSD.
+
+Sem TTY (CI), o **layout mínimo** (só `.oxe/`) e integrações no **HOME** são o padrão. Use **`--global`** para também ter **`oxe/`** na raiz. Flags: **`--cursor`**, **`--copilot`**, **`--oxe-only`**, **`OXE_NO_PROMPT=1`**, etc.
+
+No fim, em modo interativo, pergunta se você quer instalar o **`oxe-cc` globalmente** (`npm install -g`) ou continuar só com **`npx`**. Em CI ou scripts use **`--no-global-cli`** / **`-l`**, ou defina **`OXE_NO_PROMPT=1`**. Para instalar o CLI sem pergunta: **`--global-cli`** / **`-g`**.
+
+**GitHub Copilot CLI (experimental):** **`--copilot-cli`** copia os mesmos comandos para **`~/.claude/commands/`** e **`~/.copilot/commands/`** (não para o repositório). Na raiz do repo: `npx oxe-cc@latest --force --copilot --copilot-cli`. Depois teste **`/oxe-scan`** na sessão do CLI. O suporte depende da versão; veja [discussão no copilot-cli](https://github.com/github/copilot-cli/issues/1113).
 
 **Confirmar instalação no agente**
 
-| Onde | O que correr |
+| Onde | O que executar |
 |------|----------------|
 | **Cursor** | `/oxe-help` |
 | **Copilot** (VS Code) | `/oxe-help` no chat, se [prompt files](https://code.visualstudio.com/docs/copilot/customization/prompt-files) estiverem ativos (`"chat.promptFiles": true` — exemplo em [`.vscode/settings.json`](.vscode/settings.json)) |
 
-> **Nota:** O Copilot usa **instruções do repositório** (`.github/copilot-instructions.md`) **e** os ficheiros em `.github/prompts/*.prompt.md`. Sem prompt files, ainda podes pedir em linguagem natural (“executa o workflow OXE scan”) com o repo em contexto.
+> **Nota:** Instruções e prompt files do Copilot ficam em **`~/.copilot/`** (alinhado ao GSD), não em `.github/` no repo. **`oxe-cc doctor`** aceita workflows em **`.oxe/workflows/`** ou **`oxe/workflows/`**. Sem prompt files, você ainda pode pedir em linguagem natural com o repositório em contexto.
 
-**Sem pacote no npm** (`npm view oxe-cc version` → 404): clone este repo, `npm link` na pasta **oxe-build**, `npm link oxe-cc` no teu projeto, e corre `oxe-cc`. Alternativa: `node /caminho/oxe-build/bin/oxe-cc.js`.
+**Sem pacote no npm** (`npm view oxe-cc version` → 404): clone este repo, `npm link` na pasta **oxe-build**, `npm link oxe-cc` no seu projeto e execute `oxe-cc`. Alternativa: `node /caminho/oxe-build/bin/oxe-cc.js`.
 
 <details>
 <summary><strong>Instalação: flags úteis (CI, ou só parte do pacote)</strong></summary>
 
 | Flag | Efeito |
 |------|--------|
-| `--force` / `-f` | Sobrescreve ficheiros já existentes (**obrigatório** para atualizar cópias antigas) |
+| `--force` / `-f` | Sobrescreve arquivos já existentes (**obrigatório** para atualizar cópias antigas) |
 | `--dry-run` | Lista ações sem escrever |
 | `--cursor` / `--copilot` | Instala só uma das stacks |
-| `--oxe-only` | Só a pasta `oxe/` (workflows) |
-| `--no-init-oxe` | Não cria `.oxe/` no fim |
-| `--vscode` | Copia `.vscode/settings.json` de exemplo |
+| `--oxe-only` | Só workflows + templates dentro de **`.oxe/`** (sem integrações IDE) |
+| `--no-init-oxe` | Não executa o bootstrap de `STATE.md` / `config.json` / `codebase/` (mantém `.oxe/workflows` se copiados) |
+| `--global` | Layout **clássico**: **`oxe/`** na raiz do repo + **`.oxe/`**; IDE em `~/.cursor`, `~/.copilot`, `~/.claude` |
+| `--local` | Layout **mínimo** (padrão): **só `.oxe/`** com **`.oxe/workflows/`**; IDE nas mesmas pastas do usuário |
+| `--global-cli` / `-g` | Após copiar: `npm install -g oxe-cc@versão` (sem pergunta) |
+| `--no-global-cli` / `-l` | Não pergunta nem instala o CLI global (útil em CI) |
+| `--copilot-cli` | Copia comandos OXE para **`~/.claude/commands/`** e **`~/.copilot/commands/`** |
+| `--vscode` | Copia `.vscode/settings.json` (só com layout **`--global`**) |
 | `--no-commands` | Omite `commands/oxe/` |
 | `--no-agents` | Omite `AGENTS.md` |
 | `--dir <pasta>` ou argumento posicional | Destino em vez do diretório atual |
 
 **Global:** `npm install -g oxe-cc`.
 
-**Subcomandos:** `oxe-cc doctor` (valida Node, workflows, `.oxe/`), `oxe-cc init-oxe` (só bootstrap `.oxe/`).
+**Subcomandos**
+
+| Comando | Função |
+|---------|--------|
+| `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`) |
+| `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 (útil para atualizar tudo de uma vez) |
 
 </details>
 
@@ -83,7 +104,7 @@ npm test
 node bin/oxe-cc.js --help
 ```
 
-Para testar no teu app: `npm link` aqui, depois `npm link oxe-cc` no projeto alvo.
+Para testar no seu app: `npm link` aqui, depois `npm link oxe-cc` no projeto alvo.
 
 </details>
 
@@ -91,33 +112,33 @@ Para testar no teu app: `npm link` aqui, depois `npm link oxe-cc` no projeto alv
 
 ## Como funciona
 
-**Já tens código?** Começa por **`/oxe-scan`**. Gera mapas em **`.oxe/codebase/`** (stack, estrutura, testes, convenções, etc.). Assim o **spec** e o **plan** alinham com o repo real — à semelhança de correres *map-codebase* antes do roadmap no GSD.
+**Já tem código no repositório?** Comece por **`/oxe-scan`**. Isso gera mapas em **`.oxe/codebase/`** (stack, estrutura, testes, convenções, etc.). Assim o **spec** e o **plan** alinham com o repo real — no mesmo espírito de rodar *map-codebase* antes do roadmap no GSD.
 
 ### 1. Mapear — `/oxe-scan`
 
-Inventaria o projeto e preenche **`.oxe/codebase/*.md`**, atualiza **`.oxe/STATE.md`**. Podes indicar foco opcional (ex. “só API”).
+Inventaria o projeto e preenche **`.oxe/codebase/*.md`**, atualiza **`.oxe/STATE.md`**. Você pode indicar foco opcional (ex.: “só API”).
 
 ### 2. Especificar — `/oxe-spec`
 
-Produz ou atualiza **`.oxe/SPEC.md`**: objetivo, escopo, critérios de aceite, riscos. Isto é o contrato antes do plano.
+Produz ou atualiza **`.oxe/SPEC.md`**: objetivo, escopo, critérios de aceite, riscos. Isso é o contrato antes do plano.
 
 ### 3. Discutir *(opcional)* — `/oxe-discuss`
 
-Captura decisões de implementação (UI, API, tom, edge cases) em **`.oxe/DISCUSS.md`**, para o plano não “adivinhar” o que preferes. Útil quando `discuss_before_plan` está ativo em `.oxe/config.json`. Saltar = defaults razoáveis; usar = mais próximo da tua visão.
+Captura decisões de implementação (UI, API, tom, edge cases) em **`.oxe/DISCUSS.md`**, para o plano não “adivinhar” o que você prefere. Útil quando `discuss_before_plan` está ativo em `.oxe/config.json`. **Pular** este passo = defaults razoáveis; **usar** = mais próximo da sua visão.
 
 ### 4. Planear — `/oxe-plan`
 
-Gera **`.oxe/PLAN.md`**: tarefas **atómicas**, **ondas** (paralelo vs sequencial), e bloco **Verificar** (comando de teste ou checklist) **por tarefa**. Ideia: cada tarefa cabe num contexto de agente focado, com verificação explícita — mesmo espírito dos planos XML pequenos do GSD, em Markdown.
+Gera **`.oxe/PLAN.md`**: tarefas **atômicas**, **ondas** (paralelo vs sequencial), e bloco **Verificar** (comando de teste ou checklist) **por tarefa**. Ideia: cada tarefa cabe num contexto de agente focado, com verificação explícita — mesmo espírito dos planos XML pequenos do GSD, em Markdown.
 
-Ondas em resumo: tarefas **independentes** na mesma onda podem correr em paralelo; **dependentes** vão para ondas posteriores (como no diagrama de *waves* do GSD, só que com menos cerimónia).
+Ondas em resumo: tarefas **independentes** na mesma onda podem **rodar** em paralelo; **dependentes** vão para ondas posteriores (como no diagrama de *waves* do GSD, só que com menos cerimônia).
 
 ### 5. Executar — implementação + `/oxe-execute` *(opcional)*
 
-Implementas no editor ou deixas o agente seguir **`/oxe-execute`** sobre o plano (ou QUICK). O OXE não impõe subagentes nem commits atómicos por tarefa como o GSD; isso fica ao teu fluxo Git.
+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 como o GSD; isso fica a cargo do **seu** fluxo com Git.
 
 ### 6. Verificar — `/oxe-verify`
 
-Cruza **SPEC** + **PLAN** com o código; escreve **`.oxe/VERIFY.md`**. Se algo falhar, corrigis ou replanejas (`/oxe-plan` com lógica de replanejamento descrita no workflow).
+Cruza **SPEC** + **PLAN** com o código; escreve **`.oxe/VERIFY.md`**. Se algo falhar, corrija ou replaneje (`/oxe-plan` com lógica de replanejamento descrita no workflow).
 
 ### 7. Seguir em frente — `/oxe-next` e ciclo
 
@@ -127,17 +148,17 @@ Para a **próxima** feature ou fase: de novo **spec → plan → …** ou **`/ox
 
 ## Modo rápido
 
-Para trabalho **adhoc** sem roadmap completo — equivalente conceptual ao **`/gsd:quick`**:
+Para trabalho **ad hoc** sem roadmap completo — equivalente **conceitual** ao **`/gsd:quick`**:
 
-**`/oxe-quick`** gera **`.oxe/QUICK.md`** com passos curtos e verificação. Depois podes 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. Depois você pode usar **`/oxe-execute`** em cima disso ou implementar direto e fechar com **`/oxe-verify`**.
 
-Se o trabalho crescer, **promove** para spec + plan completos.
+Se o trabalho crescer, **promova** para spec + plan completos.
 
 ---
 
 ## Porque funciona
 
-**Context engineering:** o agente não precisa de “lembrar” tudo na janela principal — o que importa está em ficheiros **pequenos e por etapa**.
+**Context engineering:** o agente não precisa de “lembrar” tudo na janela principal — o que importa está em arquivos **pequenos e por etapa**.
 
 | Artefato | Função |
 |----------|--------|
@@ -145,12 +166,12 @@ Se o trabalho crescer, **promove** para spec + plan completos.
 | `.oxe/codebase/*.md` | Mapa do repo após scan |
 | `.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.md` | Tarefas atômicas + **Verificar** por item |
 | `.oxe/QUICK.md` | Modo rápido |
 | `.oxe/VERIFY.md` | Resultado das verificações |
 | `oxe/workflows/*.md` | **Fonte única** dos passos (Cursor e Copilot só delegam aqui) |
 
-**Formato:** planos em Markdown com secções fixas (incl. verificação), legíveis por humanos e por modelos — sem XML obrigatório, mas com a mesma ideia de *precise instructions + verify*.
+**Formato:** planos em Markdown com seções fixas (incl. verificação), legíveis por humanos e por modelos — sem XML obrigatório, mas com a mesma ideia de *precise instructions + verify*.
 
 ---
 
@@ -179,7 +200,7 @@ Se o trabalho crescer, **promove** para spec + plan completos.
 
 | Prompt | O que faz |
 |--------|-----------|
-| `/oxe-review-pr` | Segue `oxe/workflows/review-pr.md`: diff estilo PR (`git diff base...head`, `gh pr diff <n>`, ou fetch `pull/<n>/head`), riscos, testes e checklist. Podes colar o **link da PR** (ex. `https://github.com/org/repo/pull/10`) ou indicar `main` e `feature/x`. **Não** há slash command em `.cursor/commands/`; no Cursor podes pedir o mesmo em linguagem natural com o workflow em contexto. |
+| `/oxe-review-pr` | Segue `oxe/workflows/review-pr.md`: diff estilo PR (`git diff base...head`, `gh pr diff <n>`, ou fetch `pull/<n>/head`), riscos, testes e checklist. Você pode colar o **link da PR** (ex.: `https://github.com/org/repo/pull/10`) ou indicar `main` e `feature/x`. **Não** há slash command em `.cursor/commands/`; no Cursor você pode pedir o mesmo em linguagem natural com o workflow em contexto. |
 
 ### Outros clientes
 
@@ -189,7 +210,7 @@ Em **Claude Code** (ou ferramentas que leem `commands/oxe/`), os mesmos passos e
 
 ## Configuração
 
-Preferências do projeto em **`.oxe/config.json`** (criado no bootstrap a partir de `oxe/templates/config.template.json`). Chaves e comportamento: [`oxe/templates/CONFIG.md`](oxe/templates/CONFIG.md) (ex.: `discuss_before_plan`, texto pós-verify, comando de teste por defeito).
+Preferências do projeto em **`.oxe/config.json`** (criado no bootstrap a partir de `oxe/templates/config.template.json`). Chaves e comportamento: [`oxe/templates/CONFIG.md`](oxe/templates/CONFIG.md) (ex.: `discuss_before_plan`, texto pós-verify, comando de teste padrão).
 
 ---
 
@@ -197,20 +218,21 @@ Preferências do projeto em **`.oxe/config.json`** (criado no bootstrap a partir
 
 | Situação | O que tentar |
 |----------|----------------|
-| Comandos não aparecem no Cursor | Confirma que `.cursor/commands/` existe; reinicia o Cursor |
-| Prompts `/oxe-*` não aparecem no Copilot | Ativa `"chat.promptFiles": true`; confirma `.github/prompts/*.prompt.md` |
-| **`ETARGET`** / versão não encontrada no `npx` | `npm cache clean --force`, `npx clear-npx-cache`, ou fixa versão: `npx oxe-cc@0.3.0`. Verifica `npm config get registry` |
-| **404** no `npm view oxe-cc` | Pacote com outro nome (scope) ou ainda não publicado — usa `npm link` ou `node …/bin/oxe-cc.js` |
-| Ficheiros não atualizam | Reinstala com **`--force`** |
+| Comandos não aparecem no Cursor | Confirme que `~/.cursor/commands/` (ou a pasta configurada) existe; reinicie o Cursor |
+| Prompts `/oxe-*` não aparecem no Copilot | Ative `"chat.promptFiles": true`; confirme prompts em **`~/.copilot/prompts/`** (o OXE não coloca `.github/` no repo para o Copilot) |
+| Slash `/oxe-*` no **Copilot CLI** | Instale com **`--copilot-cli`** (`~/.claude/commands` e `~/.copilot/commands`); comportamento ainda experimental |
+| **`ETARGET`** / versão não encontrada no `npx` | `npm cache clean --force`, `npx clear-npx-cache`, ou fixe a versão: `npx oxe-cc@0.3.0`. Verifique `npm config get registry` |
+| **404** no `npm view oxe-cc` | Pacote com outro nome (scope) ou ainda não publicado — use `npm link` ou `node …/bin/oxe-cc.js` |
+| Arquivos não atualizam | Reinstale com **`--force`** (com backup local se você tiver editado arquivos rastreados) |
 
 **Ajuda no terminal:** `oxe-cc --help`. **Diagnóstico:** `oxe-cc doctor`.
 
-**Banner no CLI:** [`bin/banner.txt`](bin/banner.txt) (`{version}`). `OXE_NO_BANNER=1` desliga; `NO_COLOR` remove cores.
+**Banner no CLI:** [`bin/banner.txt`](bin/banner.txt) (`{version}`). `OXE_NO_BANNER=1` desativa o banner; `NO_COLOR` remove cores.
 
 <details>
 <summary><strong>Publicar no npm (mantenedores)</strong></summary>
 
-Sobe `version` em `package.json`, `npm login` (2FA se exigido), `npm publish --access public`. O `prepublishOnly` corre testes e `scan:assets`.
+Incremente `version` em `package.json`, rode `npm login` (2FA se exigido) e `npm publish --access public`. O script `prepublishOnly` **executa** os testes e o `scan:assets`.
 
 </details>
 
@@ -221,7 +243,7 @@ Sobe `version` em `package.json`, `npm login` (2FA se exigido), `npm publish --a
 |---------|--------|
 | `assets/readme-banner.svg` | Banner deste README |
 | `bin/oxe-cc.js`, `bin/banner.txt` | CLI |
-| `oxe/workflows/` | Workflows canónicos |
+| `oxe/workflows/` | Workflows canônicos |
 | `oxe/templates/` | Modelos e CONFIG |
 | `.cursor/`, `.github/` | Cursor e Copilot |
 | `commands/oxe/` | `oxe:*` para outros runtimes |

package/assets/readme-banner.svg

@@ -1,18 +1,19 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="920" height="200" viewBox="0 0 920 200" role="img" aria-label="OXE  spec-driven workflows">
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="920" height="200" viewBox="0 0 920 200" role="img" aria-label="OXE spec-driven workflows">
   <defs>
     <linearGradient id="oxe-bg" x1="0%" y1="0%" x2="100%" y2="100%">
-      <stop offset="0%" style="stop-color:#0d1117"/>
-      <stop offset="50%" style="stop-color:#161b22"/>
-      <stop offset="100%" style="stop-color:#21262d"/>
+      <stop offset="0%" stop-color="#0d1117"/>
+      <stop offset="50%" stop-color="#161b22"/>
+      <stop offset="100%" stop-color="#21262d"/>
     </linearGradient>
     <linearGradient id="oxe-accent" x1="0%" y1="0%" x2="100%" y2="0%">
-      <stop offset="0%" style="stop-color:#58a6ff"/>
-      <stop offset="100%" style="stop-color:#79c0ff"/>
+      <stop offset="0%" stop-color="#58a6ff"/>
+      <stop offset="100%" stop-color="#79c0ff"/>
     </linearGradient>
   </defs>
   <rect width="920" height="200" rx="16" fill="url(#oxe-bg)"/>
   <rect x="2" y="2" width="916" height="196" rx="14" fill="none" stroke="url(#oxe-accent)" stroke-width="2" opacity="0.45"/>
-  <text x="460" y="100" text-anchor="middle" font-family="ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" font-size="72" font-weight="800" fill="url(#oxe-accent)" letter-spacing="0.12em">OXE</text>
-  <text x="460" y="138" text-anchor="middle" font-family="ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" font-size="17" fill="#8b949e">Fluxo spec-driven � Cursor &amp; GitHub Copilot � CLI npm</text>
-  <text x="460" y="168" text-anchor="middle" font-family="ui-monospace, SFMono-Regular, Consolas, monospace" font-size="13" fill="#6e7681">npx oxe-cc@latest</text>
+  <text x="460" y="100" text-anchor="middle" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,sans-serif" font-size="72" font-weight="800" fill="url(#oxe-accent)" letter-spacing="0.12em">OXE</text>
+  <text x="460" y="138" text-anchor="middle" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,sans-serif" font-size="17" fill="#8b949e">Fluxo spec-driven &#xb7; Cursor &amp; GitHub Copilot &#xb7; CLI npm</text>
+  <text x="460" y="168" text-anchor="middle" font-family="ui-monospace,SFMono-Regular,Consolas,monospace" font-size="13" fill="#6e7681">npx oxe-cc@latest</text>
 </svg>

package/bin/banner.txt

@@ -15,4 +15,4 @@
 
 ══════════════════════════════════════════════════════
 
-                      v0.3.1
+                      v0.3.3

package/bin/lib/oxe-manifest.cjs

@@ -0,0 +1,117 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const MANIFEST_DIR = '.oxe-cc';
+const MANIFEST_FILE = 'manifest.json';
+const PATCHES_DIR = 'oxe-local-patches';
+
+function manifestPath(home) {
+  return path.join(home, MANIFEST_DIR, MANIFEST_FILE);
+}
+
+function sha256File(filePath) {
+  return crypto.createHash('sha256').update(fs.readFileSync(filePath)).digest('hex');
+}
+
+/**
+ * @param {string} home
+ * @returns {Record<string, string>}
+ */
+function loadFileManifest(home) {
+  const p = manifestPath(home);
+  if (!fs.existsSync(p)) return {};
+  try {
+    const j = JSON.parse(fs.readFileSync(p, 'utf8'));
+    return j && typeof j.files === 'object' ? j.files : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * @param {string} home
+ * @param {Record<string, string>} files absPath -> sha256
+ * @param {string} version
+ */
+function writeFileManifest(home, files, version) {
+  const dir = path.join(home, MANIFEST_DIR);
+  fs.mkdirSync(dir, { recursive: true });
+  const payload = {
+    version,
+    updated_at: new Date().toISOString(),
+    files,
+  };
+  fs.writeFileSync(manifestPath(home), JSON.stringify(payload, null, 2) + '\n', 'utf8');
+}
+
+/**
+ * GSD-style: before overwriting with --force, backup files that diverged from last manifest.
+ * @param {string} home
+ * @param {Record<string, string>} prevManifest
+ * @param {{ dryRun: boolean, force: boolean }} opts
+ * @param {{ yellow: string, cyan: string, dim: string, reset: string }} colors
+ * @returns {string[]} modified paths
+ */
+function backupModifiedFromManifest(home, prevManifest, opts, colors) {
+  const { yellow, cyan, dim, reset } = colors;
+  if (!opts.force || opts.dryRun) return [];
+  const modified = [];
+  for (const [absPath, oldHash] of Object.entries(prevManifest)) {
+    if (!fs.existsSync(absPath)) continue;
+    let now;
+    try {
+      now = sha256File(absPath);
+    } catch {
+      continue;
+    }
+    if (now !== oldHash) modified.push(absPath);
+  }
+  if (modified.length === 0) return [];
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const patchesRoot = path.join(home, MANIFEST_DIR, PATCHES_DIR, stamp);
+  for (const absPath of modified) {
+    const rel = path.basename(absPath);
+    const dest = path.join(patchesRoot, rel.replace(/[^a-zA-Z0-9._-]+/g, '_'));
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(absPath, dest);
+  }
+  const meta = { backed_up_at: new Date().toISOString(), files: modified };
+  fs.writeFileSync(path.join(patchesRoot, 'backup-meta.json'), JSON.stringify(meta, null, 2) + '\n', 'utf8');
+  console.log(
+    `  ${yellow}i${reset}  ${modified.length} arquivo(s) OXE alterado(s) localmente — backup em ${cyan}${path.relative(home, patchesRoot)}${reset}`
+  );
+  for (const f of modified) console.log(`     ${dim}${f}${reset}`);
+  return modified;
+}
+
+/**
+ * @param {string} dir
+ * @param {(f: string) => boolean} filter
+ */
+function collectFilesRecursive(dir, filter) {
+  /** @type {string[]} */
+  const out = [];
+  if (!fs.existsSync(dir)) return out;
+  const walk = (d) => {
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      const p = path.join(d, e.name);
+      if (e.isDirectory()) walk(p);
+      else if (filter(e.name)) out.push(p);
+    }
+  };
+  walk(dir);
+  return out;
+}
+
+module.exports = {
+  loadFileManifest,
+  writeFileManifest,
+  backupModifiedFromManifest,
+  collectFilesRecursive,
+  sha256File,
+  MANIFEST_DIR,
+  PATCHES_DIR,
+};