oxe-cc 0.3.5 → 0.3.6

package/lib/sdk/index.cjs

@@ -197,6 +197,7 @@ module.exports = {
     phaseCoherenceWarnings: health.phaseCoherenceWarnings,
     specSectionWarnings: health.specSectionWarnings,
     planWaveWarningsFixed: health.planWaveWarningsFixed,
+    planTaskAceiteWarnings: health.planTaskAceiteWarnings,
     verifyGapsWithoutSummaryWarning: health.verifyGapsWithoutSummaryWarning,
     ALLOWED_CONFIG_KEYS: health.ALLOWED_CONFIG_KEYS,
     INSTALL_PROFILES: health.INSTALL_PROFILES,

package/oxe/templates/CONFIG.md

@@ -29,4 +29,16 @@ Use `npx oxe-cc --no-install-config` para ignorar este bloco numa instalação.
 
 Chaves desconhecidas são listadas como aviso no `doctor` / `status`. Valores em falta usam o mesmo significado que no template (omissões seguras).
 
+### Exemplo: repositório legado (COBOL / JCL / copybooks / VB6 / SQL)
+
+Para **scan** e **spec** orientarem o agente sem assumir Node/Java, use `scan_focus_globs` / `scan_ignore_globs` alinhados ao layout real (nomes `cpy` vs `copy` variam). Opcionalmente reforce secções da SPEC com `spec_required_sections`, por exemplo:
+
+- `"## Contratos de dados"`
+- `"## Fluxos batch"`
+- `"## Integrações desktop-DB"`
+
+Guia completo de análise e verificação nestes repos: [`oxe/workflows/references/legacy-brownfield.md`](../workflows/references/legacy-brownfield.md) (no pacote npm; após `npx oxe-cc`, cópia em `.oxe/workflows/references/`).
+
+**Layout opcional da pasta `docs/`** (índice por intenção, técnico/negócio, glossário, comparativos): [`DOCS_BROWNFIELD_LAYOUT.md`](DOCS_BROWNFIELD_LAYOUT.md).
+
 **Autoria de workflows:** ver [`WORKFLOW_AUTHORING.md`](WORKFLOW_AUTHORING.md) (mantenedores).

package/oxe/templates/DOCS_BROWNFIELD_LAYOUT.md

@@ -0,0 +1,55 @@
+# Layout sugerido — pasta `docs/` em repositórios brownfield
+
+> Template opcional (não faz parte do núcleo OXE em `.oxe/`). Copie ou adapte à raiz de `docs/` quando documentar sistemas legado (mainframe + cliente + integrações). Referência cruzada: `oxe/workflows/references/legacy-brownfield.md`.
+
+## Objetivo
+
+- Um **índice por intenção do leitor** (executivo, técnico, negócio, migração).
+- **Pares** técnico / negocial quando compliance ou PO precisam do mesmo fluxo em linguagens diferentes.
+- **Glossário e referência cruzada** separados de narrativa longa.
+- **Comparativos** explícitos para modernização (host vs baixa plataforma).
+
+## Estrutura de pastas (exemplo)
+
+| Caminho sugerido | Conteúdo |
+|------------------|----------|
+| `docs/README.md` | Como navegar; ligação ao índice geral. |
+| `docs/INDICE-GERAL.md` | Tabela **Objetivo → documento** (visão curta, wiki, fluxo X, glossário, VB6, etc.). |
+| `docs/<wiki|enciclopedia>/` | Documentação enciclopédica por camadas ou domínio (prefixos `00-`, `05-` opcionais). |
+| `docs/tecnico/` | Aprofundamento por tema (pipelines, jobs, tabelas). |
+| `docs/negocio/` | Pares dos documentos em `tecnico/` em linguagem de negócio. |
+| `docs/glossary/` | Glossário, dicionário de dados, matrizes de dependência, códigos de erro. |
+| `docs/baixa-plataforma/` ou `docs/desktop-client/` | Cliente legado (ex. VB6), SPs, integração com host, roadmap. |
+| `docs/<tema>/comparativo-detalhado/` | Tabelas **mainframe × cliente** por área funcional. |
+| `docs/<fluxo>/USn/` | Histórias de utilizador, anexos Mermaid, scripts de apoio (opcional). |
+
+Ajuste nomes ao produto; o importante é **papéis claros** e links relativos entre pares.
+
+## Taxonomia de plataforma (recomendado no texto)
+
+| Termo | Uso |
+|-------|-----|
+| **Alta plataforma** / host | Mainframe, JCL, COBOL, DB2 z/OS, schedulers. |
+| **Baixa plataforma** | Servidores distribuídos, middle-office, transferência de ficheiros, gateways. |
+| **Externo** | Reguladores, câmaras, mercado (ex. câmaras de clearing, bolsas). |
+
+Incluir esta secção em documentos de arquitetura ou em `INTEGRATIONS.md` do scan OXE quando aplicável.
+
+## Frontmatter YAML (opcional)
+
+```yaml
+---
+titulo: "Título curto"
+tipo: tecnico | negocio | indice | comparativo
+area: nome-do-dominio
+tags: [tag1, tag2]
+ultima_revisao: "YYYY-MM"
+---
+```
+
+Não é validado pelo `oxe-cc doctor`; serve para convenção humana e futuras ferramentas.
+
+## Ligação ao OXE
+
+- O **scan** deve, se existir `docs/` com `INDICE-GERAL.md` ou `README.md`, resumir esta estrutura em `.oxe/codebase/OVERVIEW.md` e `STRUCTURE.md` com link ao índice.
+- **SPEC/PLAN** de migração podem exigir entregáveis sob `docs/tecnico/` e `docs/negocio/` via critérios **A*** .

package/oxe/templates/SPEC.template.md

@@ -41,3 +41,21 @@ Use **IDs estáveis** (A1, A2, …) para o plano e o verify vincularem cada tare
 ## Referências no código
 
 - Caminhos / módulos: …
+
+---
+
+## Secções opcionais — brownfield / migração legado
+
+> Use quando o projeto for mainframe + desktop legado ou documentação de migração. Podem ser exigidas pelo `doctor` via `spec_required_sections` em `.oxe/config.json`. Ver `oxe/workflows/references/legacy-brownfield.md`.
+
+### Contratos de dados
+
+- Copybooks, tabelas, mensagens, layouts de ficheiro.
+
+### Fluxos batch
+
+- Cadeias JCL / jobs e programas associados.
+
+### Integrações desktop-DB
+
+- Cliente (ex. VB6) ↔ base de dados / stored procedures.

package/oxe/templates/WORKFLOW_AUTHORING.md

@@ -32,6 +32,8 @@ Mantenha tags **abertas e fechadas** explicitamente (evita ambiguidade para leit
 - Se um workflow ultrapassar **~400–500 linhas** ou repetir a mesma referência muitas vezes, extraia para:
   - `oxe/workflows/references/<nome>.md` (no pacote), ou
   - trechos reutilizáveis em `oxe/templates/` (ex.: [`SPEC.template.md`](SPEC.template.md), [`CONFIG.md`](CONFIG.md)).
+- Exemplo publicado: [`legacy-brownfield.md`](../workflows/references/legacy-brownfield.md) — COBOL, JCL, copybooks, VB6, SP; consumido por **scan**, **spec**, **plan**, **execute**, **verify**.
+- Template opcional de pasta `docs/` brownfield: [`DOCS_BROWNFIELD_LAYOUT.md`](DOCS_BROWNFIELD_LAYOUT.md) (copiado para `.oxe/templates/` na instalação).
 - O `SKILL.md` principal do passo deve permanecer o **mapa**: objetivo, contexto essencial, sequência, critérios de sucesso.
 
 ## 4. Comandos Cursor e prompts Copilot (frontmatter)

package/oxe/workflows/execute.md

@@ -9,6 +9,7 @@ Se existir apenas **`.oxe/QUICK.md`** (fluxo quick), tratar os **Passos** numera
 <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.
+- **Legado / brownfield:** entregáveis podem ser só documentação (`.md`, diagramas). Exigir pré-requisitos de ambiente (mainframe, IDE VB6) quando a tarefa depender disso — ver **`oxe/workflows/references/legacy-brownfield.md`**.
 </context>
 
 <process>

package/oxe/workflows/help.md

@@ -1,21 +1,23 @@
 # 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 o CLI `oxe-cc` (instalar, `doctor`, `status`, `init-oxe`, `uninstall`, `update`) e, em linha, o **SDK** npm (`require('oxe-cc')`) para CI.
+Apresentar o fluxo OXE (scan → spec → plan → execução → verify), o modo **quick**, o passo **execute**, e **como invocar em várias IDEs/CLIs** (Cursor e GitHub Copilot como referência principal; outras stacks na secção multi-agente). 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 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.
+OXE é um fluxo **spec-driven** com artefatos em `.oxe/` no projeto alvo — **o núcleo é o mesmo** em Cursor, Copilot, Claude, OpenCode, Gemini, Codex, Windsurf, Antigravity ou outra CLI suportada pelo instalador. **Poucos comandos** por ferramenta em relação a fluxos de planeamento mais pesados; *context engineering* com arquivos pequenos por etapa. **GitHub Copilot (VS Code)** usa **`~/.copilot/`** após `npx oxe-cc` (bloco mesclado em `copilot-instructions.md` + **prompt files** em `~/.copilot/prompts/`), não `.github/` dentro do repo alvo por padrão; outras ferramentas usam os respetivos homes (ver secção **Multi-agente** abaixo).
 
 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
+## Integrações principais (referência)
 
-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.
+### Cursor
 
-## GitHub Copilot (VS Code)
+Slash commands: `/oxe-scan`, `/oxe-spec`, `/oxe-discuss`, `/oxe-plan`, `/oxe-verify`, `/oxe-next`, `/oxe-quick`, `/oxe-execute`, `/oxe-update`, `/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)
 
 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`).
@@ -23,7 +25,7 @@ Slash commands: `/oxe-scan`, `/oxe-spec`, `/oxe-discuss`, `/oxe-plan`, `/oxe-ver
 
 ## Fluxo completo
 
-1. **scan** — após clonar ou quando o repositório mudar muito.
+1. **scan** — após clonar ou quando o repositório mudar muito. Repositórios **legado** (COBOL, JCL, copybooks, VB6, SQL procedures): o passo **scan** aplica `oxe/workflows/references/legacy-brownfield.md` quando esses sinais existirem — preencha `TESTING.md` com honestidade (sem `npm test` fictício) e use `scan_focus_globs` em `.oxe/config.json` (ver `oxe/templates/CONFIG.md`).
 2. **spec** — descrever o que se quer (critérios com IDs **A1**, **A2**…).
 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.
@@ -41,9 +43,12 @@ Slash commands: `/oxe-scan`, `/oxe-spec`, `/oxe-discuss`, `/oxe-plan`, `/oxe-ver
 - **`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 status`** — coerência `.oxe/` + **um** próximo passo (espelha `next.md`). Com **`--json`**, uma linha JSON (`nextStep`, `diagnostics`, …) para CI ou scripts.
 - **`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-update`** (Cursor; noutras ferramentas use o terminal no projeto) — workflow de atualização: verificar npm, correr `oxe-cc update`, `doctor`.
+- **`oxe-cc update --check`** — só comparar versão em execução com a `latest` no npm (sem instalar).
+- **`oxe-cc update --if-newer`** — só executa o `npx oxe-cc@latest` se houver versão mais nova no npm.
 - **`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`.
@@ -62,6 +67,7 @@ Quem integra em pipeline pode usar **`require('oxe-cc')`** (entrada `main` do pa
 |----------|-----|
 | `OXE_NO_PROMPT` | `1` / `true`: sem menus interativos |
 | `OXE_NO_BANNER` | `1` / `true`: sem banner no CLI |
+| `OXE_UPDATE_SKIP_REGISTRY` | `1` / `true`: não consultar npm em `update --check` / `--if-newer` (saída `2` ou skip) |
 | `CURSOR_CONFIG_DIR` | Base Cursor (default `~/.cursor`) |
 | `COPILOT_CONFIG_DIR` / `COPILOT_HOME` | Base Copilot |
 | `CLAUDE_CONFIG_DIR` | Base `~/.claude` |

package/oxe/workflows/plan.md

@@ -34,6 +34,10 @@ Cada tarefa em PLAN.md deve seguir:
   - Manual: (opcional) passos breves
 - **Aceite vinculado:** A1, A2 (IDs exatos da tabela de critérios da SPEC)
 ```
+
+**Projetos sem suíte de testes única (legado):** o bloco **Verificar** pode usar `Comando: —` e **Manual** com Grep, leitura de paths ou checklist — ver exemplos em **`oxe/workflows/references/legacy-brownfield.md`**. Todo critério **A*** da SPEC deve aparecer em **Aceite vinculado** de alguma tarefa ou como gap explícito.
+
+**Comparativo host ↔ cliente (migração / paridade):** pode-se dedicar tarefas a produzir ou atualizar uma **matriz Markdown** (classificações: equivalente / implementação diferente / só host / só cliente) com colunas de artefactos reais no repo — ver secção *Molde de comparativo* em **`oxe/workflows/references/legacy-brownfield.md`**. Cada **Tn** deve manter **Aceite vinculado** aos **A*** que essa matriz satisfaz.
 </format_plan>
 
 <process>

package/oxe/workflows/references/legacy-brownfield.md

@@ -0,0 +1,136 @@
+# Referência OXE — Repositórios legado (brownfield)
+
+Documento de apoio aos workflows **scan**, **spec**, **plan**, **execute** e **verify** quando o projeto **não** é uma aplicação web/Node típica: **mainframe** (COBOL, JCL, copybooks), **cliente desktop** (ex. VB6), **stored procedures** / DDL em SQL, e integrações por ficheiro ou fila.
+
+## 1. Deteção rápida (sinais no repo)
+
+| Sinal | Extensões / pastas comuns |
+|-------|---------------------------|
+| COBOL | `*.cbl`, `*.cob`, `*.cobol` |
+| JCL | `*.jcl`, `*.prc`, pasta `jcl/`, `proc/` |
+| Copybooks | `*.cpy`, pastas `cpy/`, `copy/`, `copylib/` |
+| Binder / load | `*.clb`, pastas `clb/` (quando existirem) |
+| VB6 / Win32 legado | `*.frm`, `*.vbp`, `*.bas`, `*.cls`, `*.ctl` |
+| SQL host | `*.sql`, pastas `sql/`, `DB_DDL/`, `stored_procedures/` |
+| Documentação já existente | `docs/`, `src/docs/`, `glossary/` com inventários |
+
+**Não assumir** nomes fixos: `cpy` vs `copy` vs `includes` é comum — o scan deve **descrever o que existe** em `STRUCTURE.md` e, se útil, sugerir `scan_focus_globs` em `.oxe/config.json`.
+
+## 2. Scan — o que preencher nos sete ficheiros
+
+### OVERVIEW
+
+- Fluxo de negócio em 5–15 tópicos (batch vs online vs desktop).
+- Referência explícita a documentação humana já no repo (índices, enciclopédias).
+
+### STACK
+
+- Runtime real (z/OS, IMS, CICS, DB2, etc.) **como inferido** dos fontes e docs — marcar quando for inferência.
+- VB6, ODBC/ADO, SQL Server/DB2 conforme aparecer em código ou comentários.
+
+### STRUCTURE
+
+- Árvore lógica: `jcl/` → programas → datasets/VSAM/DB2; copybooks e sinónimos de pasta; módulos VB6 por serviço/projeto.
+- Nota quando pastas esperadas (`cpy`, `clb`) **não** existirem mas equivalentes existirem (`copy/`).
+- **`docs/` rica:** se existir `docs/INDICE-GERAL.md`, `docs/README.md`, `docs/**/00-*INDICE*` ou enciclopédia por camadas, descrever o **papel de cada subpasta** (`tecnico/`, `negocio/`, `glossary/`, `baixa-plataforma/`, comparativos) e o caminho do índice mestre — não tratar `docs/` como “só Markdown”.
+
+### TESTING
+
+- Se não houver `npm test` / CI: declarar **honestamente** (*não detetado* ou *não verificado neste clone*).
+- Listar scripts locais (ex. análise JCL em Python/BAT) como verificação **opcional**, com caminho em backticks.
+
+### INTEGRATIONS
+
+- Sistemas externos (ex. troca de mensagens, CNAB, filas), **sem valores** de segredos.
+- Pontes **host ↔ desktop** (ficheiros, BD partilhada, serviços COM/XML).
+- **Taxonomia de plataforma** (quando fizer sentido): subsecção explícita **Alta plataforma** (host/mainframe), **Baixa plataforma** (distribuído, middle-office, cliente), **Externo** (reguladores, câmaras, mercado). Usar a mesma linguagem em OVERVIEW se o repo for híbrido.
+
+### CONVENTIONS
+
+- Prefixos de programas, convenções JCL (`JOB`, `EXEC PGM=`), padrões de copybook.
+
+### CONCERNS
+
+- Volume de fontes, EOL de VB6, ausência de testes automáticos, acoplamento DB2, gaps documentados no próprio repo.
+
+## 3. Config (`.oxe/config.json`)
+
+Sugerir ao utilizador padrões como (ajustar ao repo real):
+
+```json
+"scan_focus_globs": [
+  "jcl/**",
+  "**/*.jcl",
+  "cpy/**",
+  "copy/**",
+  "src/**/*.cbl",
+  "**/*.frm",
+  "**/*.vbp",
+  "**/DB_DDL/**/*.sql"
+],
+"scan_ignore_globs": [
+  ".mypy_cache/**",
+  "**/node_modules/**"
+]
+```
+
+Para specs de **documentação/migração**, `spec_required_sections` pode incluir cabeçalhos adicionais, por exemplo:
+
+- `## Contratos de dados` (copybooks, tabelas, mensagens)
+- `## Fluxos batch` (cadeias JCL / jobs)
+- `## Integrações desktop-DB` (VB6, procedures, ODBC)
+
+## 4. Spec — epicos úteis
+
+Dividir por **trilhas** comunicáveis:
+
+1. Batch: JCL → COBOL → ficheiros / DB2.
+2. Online: transações IMS/CICS (quando identificáveis).
+3. Desktop + SQL: ecrãs / módulos → procedures ou tabelas.
+
+Critérios **A*** devem ser verificáveis por: leitura de ficheiro, Grep, checklist humano, ou execução em ambiente (quando existir) — não exigir `npm test` se o projeto não tiver.
+
+## 5. Plan — bloco **Verificar** (legado)
+
+Quando não houver comando único de teste:
+
+```markdown
+- **Verificar:**
+  - Comando: `—` (projeto sem suíte única; ver Manual)
+  - Manual: Confirmar em `STRUCTURE.md` que cadeia X está referenciada; Grep `COPY NOMECOPY` nos `.cbl` listados; revisão humana do diagrama em `docs/...`
+```
+
+Mapear **cada** critério A* a pelo menos uma tarefa ou registar **gap** explícito no plano.
+
+### Molde de comparativo (migração host ↔ cliente)
+
+Para SPEC/PLAN de paridade ou modernização, um entregável útil é uma **matriz comparativa** (Markdown em `docs/` ou `.oxe/`). Classificar cada funcionalidade ou fluxo:
+
+| Classificação | Significado |
+|----------------|-------------|
+| Equivalente | Mesmo resultado; pode diferir batch vs online. |
+| Mesma função, implementação diferente | Comportamento alinhado; caminhos de código distintos. |
+| Só no host | Não reproduzido (ou não encontrado) no cliente. |
+| Só no cliente | Não reproduzido (ou não encontrado) no host. |
+
+Incluir colunas **Host (programa/job/tabela)** e **Cliente (form/SP/serviço)** com paths do repo. Vincular tarefas **Tn** aos critérios **A*** que exigem cobertura da matriz (ex. “todas as linhas da coluna X documentadas”).
+
+## 6. Execute
+
+- Ondas funcionam igual; reforçar **pré-requisitos** (acesso a mainframe, IDE VB6) quando a tarefa depender de ambiente fora do Git.
+- Se a “implementação” for só documentação/diagramas, o entregável são ficheiros `.md` (ou anexos) com caminhos nos **Arquivos prováveis**.
+
+## 7. Verify
+
+- Evidência válida: trecho de `Read`, resultado de `Grep`, confirmação de existência de ficheiros, checklist assinado no `VERIFY.md`.
+- Se um comando do PLAN falhar por ambiente ausente, registar **não executado aqui** e manter o comando para o utilizador — não marcar como “passou” sem evidência.
+
+## 8. Anti-patterns
+
+- Inventar nomes de transação CICS ou jobs não presentes no repo.
+- Tratar ausência de `package.json` como “projeto vazio”.
+- Omitir `TESTING.md` ou preencher com comandos genéricos que não se aplicam.
+
+## 9. Layout opcional da pasta `docs/`
+
+Modelo de pastas, índice por intenção, pares técnico/negócio e convenções de frontmatter YAML: **`oxe/templates/DOCS_BROWNFIELD_LAYOUT.md`** (no projeto instalado: `.oxe/templates/DOCS_BROWNFIELD_LAYOUT.md` quando copiado pelo `oxe-cc`).

package/oxe/workflows/scan.md

@@ -19,12 +19,14 @@ Se **`.oxe/config.json`** tiver `scan_focus_globs` ou `scan_ignore_globs`, **pri
 <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 — aplicando foco/ignore da config se houver.
+2b. **Legado / brownfield:** se o inventário revelar sinais de mainframe ou desktop legado (ex.: `*.cbl`, `*.jcl`, pastas `jcl/`, `cpy/` ou `copy/`, `*.cpy`, `*.frm` / `*.vbp`, volume de `*.sql` com procedures), aplicar **`oxe/workflows/references/legacy-brownfield.md`** ao preencher STACK, STRUCTURE, INTEGRATIONS, TESTING e CONCERNS — **sem** assumir Node/Java nem omitir TESTING.md quando não houver CI.
+2c. **`docs/` / `src/docs/` com documentação humana:** se existir pasta de documentação com índice (`docs/INDICE-GERAL.md`, `docs/README.md`, `**/00-*INDICE*.md`, ou enciclopédia por camadas), em **OVERVIEW** e **STRUCTURE** resumir o **papel das subpastas** (ex.: `tecnico/`, `negocio/`, `glossary/`, comparativos, baixa plataforma) e linkar o ficheiro índice em backticks. Em **INTEGRATIONS** (e se útil em OVERVIEW), quando o repo for híbrido host + distribuído + externos, incluir bullets **Alta plataforma**, **Baixa plataforma**, **Externo** conforme `legacy-brownfield.md`. Sugerir template opcional `oxe/templates/DOCS_BROWNFIELD_LAYOUT.md` ao utilizador se a árvore `docs/` estiver em crescimento.
 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).
+   - **OVERVIEW.md** — propósito aparente do projeto, módulos de alto nível, fluxo principal (5–15 tópicos); se houver índice em `docs/`, um tópico deve apontar para ele.
    - **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.
+   - **STRUCTURE.md** — árvore lógica (não listar mil arquivos): entrypoints, `src/` por domínio, onde ficam testes e configs; **e** papel de `docs/` ou `src/docs/` quando existirem.
    - **TESTING.md** — como rodar testes/lint/format (comandos exatos), frameworks de teste, pastas `*test*`, CI se houver.
-   - **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.
+   - **INTEGRATIONS.md** — APIs externas, bancos, auth, filas, segredos (nomes de env **sem valores**), webhooks; em sistemas legado híbridos, taxonomia alta/baixa/externo quando aplicável. 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/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.

package/oxe/workflows/spec.md

@@ -16,6 +16,8 @@ Entrada: texto livre na mensagem ou caminho `@arquivo.md` / anexo para incorpora
 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**.
+
+**Brownfield (COBOL, JCL, copybooks, VB6, SP):** quando o objetivo for documentar ou planear migração, ver **`oxe/workflows/references/legacy-brownfield.md`** — epicos por **trilha** (batch, online, desktop↔SQL), critérios **A*** verificáveis por Grep/leitura/checklist, e secções opcionais alinháveis a `spec_required_sections` em `.oxe/config.json` (ver `oxe/templates/CONFIG.md`).
 </context>
 
 <process>

package/oxe/workflows/update.md

@@ -0,0 +1,33 @@
+# OXE — Workflow: update
+
+<objective>
+Alinhar o projeto e integrações OXE à **versão mais recente** do pacote **oxe-cc** publicada no npm: verificar se há atualização, aplicar a reinstalação com `--force` quando fizer sentido e validar com **`oxe-cc doctor`**.
+</objective>
+
+<context>
+- Trabalhar na **raiz do repositório** do projeto (onde está `.oxe/` ou onde o utilizador instalou o OXE).
+- O CLI compara a **versão do binário em execução** com a tag **latest** no npm (não confundir com `node_modules/oxe-cc` se existir como dependência de app).
+- **`--force`** na reinstalação pode gerar backup de ficheiros alterados localmente em **`~/.oxe-cc/oxe-local-patches/`** (comportamento do instalador).
+- Para **só consultar** o registo sem instalar: `npx oxe-cc update --check` (saída `0` = já em dia ou mais novo, `1` = há versão mais nova no npm, `2` = erro ou `OXE_UPDATE_SKIP_REGISTRY`).
+- Para **só correr o npx se houver versão mais nova**: `npx oxe-cc update --if-newer` (sem rede ou com `OXE_UPDATE_SKIP_REGISTRY=1` termina com código `2` e **não** executa o npx).
+</context>
+
+<process>
+1. Na raiz do projeto, executar **`npx oxe-cc update --check`** (ou equivalente com `oxe-cc` no PATH). Relatar ao utilizador: versão em execução, `latest` no npm e se há atualização.
+2. Se o utilizador quiser atualizar (ou se `--check` indicou versão mais nova e pediu explícito), executar **`npx oxe-cc update`** na mesma raiz — opcionalmente **`npx oxe-cc update --if-newer`** para evitar npx quando já está na última. Repassar flags extra ao pacote novo se o utilizador pedir (ex.: `--cursor --global`).
+3. Após uma instalação bem-sucedida, executar **`npx oxe-cc doctor`** e resumir o resultado (OK vs avisos/erros).
+4. Se o utilizador usar **Copilot CLI / skills**, lembrar **`/skills reload`** (ou reinício) após mudanças nos ficheiros do HOME; no **Gemini CLI**, **`/commands reload`** quando aplicável.
+</process>
+
+<output>
+- Resumo do que foi executado (comandos e códigos de saída relevantes).
+- Se `--check` apenas: não propor `npx` sem confirmação do utilizador quando há versão nova.
+- Próximo passo sugerido: retomar o fluxo OXE (ex.: **`/oxe-scan`** se o projeto mudou muito) ou continuar a tarefa em curso.
+</output>
+
+<success_criteria>
+- [ ] Correram na raiz do projeto, nesta ordem quando aplicável: `npx oxe-cc update --check`; depois `npx oxe-cc update` ou `npx oxe-cc update --if-newer` (ou o utilizador recusou atualizar após o `--check`).
+- [ ] Após qualquer instalação concluída, correr `npx oxe-cc doctor` e reportar se passou ou que avisos/erros restam.
+- [ ] O resumo menciona versões ou resultado da consulta ao npm quando `--check` ou update foi usado.
+- [ ] Reload de skills/comandos externos (Copilot CLI, Gemini) foi lembrado quando relevante.
+</success_criteria>

package/oxe/workflows/verify.md

@@ -11,6 +11,7 @@ Se o usuário indicar uma tarefa (ex.: `T2`), focar só nela; caso contrário, p
 - Não destruir `PLAN.md`; registrar achados em `VERIFY.md`.
 - Ler **`.oxe/config.json`** se existir: `after_verify_draft_commit` e `after_verify_suggest_pr` controlam passos opcionais (se o arquivo não existir, use o mesmo padrão do `config.template.json`).
 - Os critérios na SPEC devem estar na tabela **Critérios de aceite** com colunas **ID** / **Critério** / **Como verificar**; o verify deve **cruzar cada ID** com evidência (arquivo, comando, trecho).
+- **Legado:** quando **Comando** for `—` ou inexistente, evidência válida inclui **Read/Grep**, existência de ficheiros referenciados e checklist manual — não marcar critério como passou sem evidência; se o ambiente host/desktop não estiver disponível, registar **não executado aqui** e próximo passo. Ver **`oxe/workflows/references/legacy-brownfield.md`**.
 </context>
 
 <process>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "oxe-cc",
-  "version": "0.3.5",
-  "description": "OXE — spec-driven workflows for Cursor and GitHub Copilot (install via npx)",
+  "version": "0.3.6",
+  "description": "OXE — spec-driven workflows in .oxe/; integrates with Cursor, GitHub Copilot, Claude, OpenCode, Gemini, Codex, Windsurf, Antigravity (npx)",
   "license": "GPL-3.0",
   "author": "",
   "homepage": "https://www.npmjs.com/package/oxe-cc",
@@ -16,8 +16,16 @@
     "cursor",
     "github-copilot",
     "copilot",
+    "claude",
+    "claude-code",
+    "opencode",
+    "gemini-cli",
+    "codex",
+    "windsurf",
+    "antigravity",
     "spec-driven",
     "context-engineering",
+    "ai-agents",
     "oxe"
   ],
   "engines": {
@@ -45,8 +53,8 @@
   ],
   "scripts": {
     "sync:cursor": "node scripts/sync-cursor-from-prompts.cjs",
-    "test": "node --test tests/install.test.cjs tests/oxe-project-health.test.cjs tests/oxe-sdk.test.cjs tests/oxe-manifest.test.cjs tests/oxe-agent-install.test.cjs tests/oxe-install-resolve-full.test.cjs tests/oxe-health-extended.test.cjs tests/oxe-workflows-edge.test.cjs tests/oxe-sdk-edge.test.cjs tests/oxe-cli-edge.test.cjs tests/oxe-scripts.test.cjs",
-    "test:coverage": "c8 --check-coverage --lines 82 --functions 90 --branches 58 --statements 82 npm test",
+    "test": "node --test tests/install.test.cjs tests/oxe-project-health.test.cjs tests/oxe-sdk.test.cjs tests/oxe-manifest.test.cjs tests/oxe-agent-install.test.cjs tests/oxe-install-resolve-full.test.cjs tests/oxe-health-extended.test.cjs tests/oxe-workflows-edge.test.cjs tests/oxe-sdk-edge.test.cjs tests/oxe-cli-edge.test.cjs tests/oxe-npm-version.test.cjs tests/oxe-scripts.test.cjs",
+    "test:coverage": "c8 --check-coverage --lines 82 --functions 85 --branches 58 --statements 82 npm test",
     "scan:assets": "node scripts/oxe-assets-scan.cjs",
     "prepublishOnly": "node scripts/sync-cursor-from-prompts.cjs && npm test && npm run scan:assets && node bin/oxe-cc.js --version"
   },
@@ -67,5 +75,8 @@
   },
   "devDependencies": {
     "c8": "^11.0.0"
+  },
+  "dependencies": {
+    "semver": "^7.7.4"
   }
 }