oxe-cc 0.3.8 → 0.5.0

package/oxe/workflows/verify.md

@@ -1,43 +1,103 @@
 # OXE — Workflow: verify
 
 <objective>
-Executar ou orientar verificação pós-implementação: rodar os comandos definidos no **PLAN.md**, confrontar **cada critério da SPEC** (IDs **A1**, **A2**, …) com o código e os testes, e registrar o resultado em **`.oxe/VERIFY.md`** (e atualizar **STATE**).
+Executar ou orientar verificação pós-implementação em **quatro camadas progressivas**:
 
-Se o usuário indicar uma tarefa (ex.: `T2`), focar só nela; caso contrário, percorrer todas as tarefas com blocos **Verificar**.
+1. **Auditoria de pré-execução** — verificar que o PLAN está íntegro antes de iniciar (gate de qualidade).
+2. **Verificação de tarefas e critérios** — rodar comandos do PLAN e cruzar cada critério da SPEC (IDs **A1**, **A2**, …) com evidência.
+3. **Fidelidade de decisões** — cruzar cada decisão **D-NN** do DISCUSS.md com a implementação.
+4. **UAT (Checklist de aceite)** — checklist manual para o usuário confirmar entregáveis.
+
+Resultado registrado em **`.oxe/VERIFY.md`** com atualização de **STATE**.
+
+Se o usuário indicar uma tarefa (ex.: `T2`), focar só nela nas camadas 1–2; as camadas 3–4 são sempre de escopo completo.
 </objective>
 
 <context>
-- Preferir rodar comandos reais no terminal quando o ambiente permitir; se o sandbox bloquear, marcar como “não executado aqui” e deixar o comando para o usuário.
+- Preferir rodar comandos reais no terminal quando o ambiente permitir; se o sandbox bloquear, marcar como "não executado aqui" e deixar o comando para o usuário.
 - 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`).
+- Ler **`.oxe/config.json`** se existir: `after_verify_draft_commit`, `after_verify_suggest_pr`, e `verification_depth` (`"standard"` por padrão; `"thorough"` ativa camadas 3–4 completas; `"quick"` pula camadas 3–4 e UAT).
 - 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`**.
 - **Debug:** investigação técnica de falhas **durante** a implementação segue **`oxe/workflows/debug.md`** (`/oxe-debug`). Resolver um bug com debug **não** dispensa este passo — após correções, **ainda** é necessário **`verify`** para fechar a trilha face à SPEC/PLAN.
 - **UI:** se existirem `.oxe/UI-SPEC.md` / `.oxe/UI-REVIEW.md`, incorporar na evidência quando os critérios **A*** ou tarefas **Tn** tocarem interface.
-- **Pós-verify (opcional):** para auditoria de **cobertura** e gaps de verificabilidade (sem substituir este passo), **`oxe:validate-gaps`** → `.oxe/VALIDATION-GAPS.md` (ver **`oxe/workflows/validate-gaps.md`**).
-- **Rotina compact/checkpoint (opcional):** se esta entrega alterou **estrutura**, **stack** ou **pastas** de forma relevante, sugira **`/oxe-compact`** para alinhar `.oxe/codebase/` ao repo (e `CODEBASE-DELTA.md` + `RESUME.md`). Após **verify** com sucesso e antes de abrir nova entrega grande, um **`/oxe-checkpoint`** com slug curto pode marcar estado estável — **não** faz parte dos critérios de sucesso abaixo.
+- **Pós-verify (opcional):** para auditoria de **cobertura** e gaps de verificabilidade, **`oxe:validate-gaps`** → `.oxe/VALIDATION-GAPS.md` (ver **`oxe/workflows/validate-gaps.md`**). Com `verification_depth: "thorough"`, sugerir proativamente.
+- **Rotina compact/checkpoint (opcional):** se esta entrega alterou **estrutura**, **stack** ou **pastas** de forma relevante, sugira **`/oxe-compact`** para alinhar `.oxe/codebase/` ao repo. Após **verify** com sucesso, um **`/oxe-checkpoint`** com slug curto pode marcar estado estável.
 </context>
 
+<camada_1_pre_exec_audit>
+**Camada 1 — Auditoria de pré-execução** (roda *antes* de iniciar os comandos de verify)
+
+Verificar que o PLAN.md está apto para verificação:
+1. Toda tarefa `### Tn` tem bloco **Verificar** com pelo menos Comando ou Manual.
+2. Todo **Aceite vinculado** referencia IDs que existem na tabela de SPEC.md (`A1`, `A2`, …).
+3. Se houver `.oxe/DISCUSS.md`, toda decisão técnica com ID **D-NN** aparece em **Decisão vinculada:** de alguma tarefa (ou nota explícita de gap no PLAN).
+4. Não há dependências `Tk` inválidas (ID inexistente no PLAN).
+
+Se auditoria falhar: registrar na seção **Auditoria de pré-execução** do VERIFY.md os itens com problema e **pausar** — pedir correção do PLAN antes de continuar. Se o usuário forçar continuar com `--skip-audit`, documentar e prosseguir com aviso.
+</camada_1_pre_exec_audit>
+
+<camada_2_tarefas_e_criterios>
+**Camada 2 — Verificação de tarefas e critérios SPEC**
+
+Para cada tarefa relevante, executar **Verificar: Comando** do PLAN (ou subconjunto se foco Tn). Para **cada ID de critério** usado na SPEC (A1, A2, …), registrar se passou com evidência (Read/Grep, saída de teste resumida).
+</camada_2_tarefas_e_criterios>
+
+<camada_3_fidelidade_decisoes>
+**Camada 3 — Fidelidade de decisões** (ativa se existir `.oxe/DISCUSS.md` com IDs D-NN)
+
+Para cada decisão na tabela de DISCUSS.md:
+1. Localizar a(s) tarefa(s) que referenciam esse ID em **Decisão vinculada:**.
+2. Verificar que a implementação reflete a decisão (Grep/Read dos arquivos da tarefa).
+3. Registrar na tabela **Fidelidade de decisões** do VERIFY.md: ID | Decisão (resumo) | Tarefa(s) | Implementado? | Evidência.
+
+Se uma decisão D-NN não tem tarefa vinculada **e** não há nota de gap no PLAN: marcar como `divergência` e adicionar ao bloco **Gaps**.
+</camada_3_fidelidade_decisoes>
+
+<camada_4_uat>
+**Camada 4 — UAT (User Acceptance Testing)** (ativa se `after_verify_suggest_uat` não for `false` na config)
+
+Gerar uma **Checklist UAT** no VERIFY.md com passos manuais derivados dos critérios de aceite. Formato:
+
+```markdown
+## Checklist UAT (aceite manual)
+
+Para cada critério da SPEC que exige validação manual:
+- [ ] A1: (descrição do passo a executar pelo usuário, em linguagem simples)
+- [ ] A2: …
+
+**Instruções:** execute os itens acima no ambiente real e marque ✓. Se algum falhar, abra um item em Gaps abaixo.
+```
+
+O preenchimento da checklist é responsabilidade do **usuário** (não do agente de IA).
+</camada_4_uat>
+
 <process>
-1. Ler `.oxe/SPEC.md`, `.oxe/PLAN.md`, `.oxe/STATE.md`.
-2. Para cada tarefa relevante, executar **Verificar: Comando** do PLAN (ou subconjunto se foco Tn).
-3. Para **cada ID de critério** usado na SPEC (A1, A2, …), registrar se passou, com evidência (Read/Grep, saída de teste resumida).
-4. Escrever **`.oxe/VERIFY.md`** com:
+1. **Camada 1 — Auditoria de pré-execução:** checar integridade do PLAN.md e DISCUSS.md conforme `<camada_1_pre_exec_audit>`. Documentar resultado.
+2. Ler `.oxe/SPEC.md`, `.oxe/PLAN.md`, `.oxe/STATE.md`.
+3. **Camada 2:** Para cada tarefa relevante, executar **Verificar: Comando** do PLAN (ou subconjunto se foco Tn). Para **cada ID de critério** da SPEC (A1, A2, …), registrar se passou com evidência.
+4. **Camada 3:** Se existir `.oxe/DISCUSS.md` com IDs D-NN, executar **Fidelidade de decisões** conforme `<camada_3_fidelidade_decisoes>`.
+5. Escrever **`.oxe/VERIFY.md`** com:
    - Data, ambiente (SO / versão do Node se relevante).
+   - **Seção — Auditoria de pré-execução:** resultado da Camada 1.
    - **Tabela — Tarefas:** Tarefa (Tn) | Verificação (comando/checklist) | Passou? | Notas.
    - **Tabela — Critérios SPEC:** ID (A1…) | Critério (resumo) | Evidência | Passou? | Notas.
-   - **Gaps** — o que falhou e sugestão de correção (pode virar novas entradas no PLAN); se não houver, escrever explicitamente `Nenhum gap restante` ou equivalente.
-5. Atualizar **`.oxe/STATE.md`**: `verify_complete` ou `verify_failed` + próximo passo (replan, corrigir ou publicar).
-5b. **Blueprint plan-agent:** se **todas** as verificações relevantes **passaram**, existir **`.oxe/plan-agents.json`** com `oxePlanAgentsSchema === 2` e `lifecycle.status === "executing"` (ou `pending_execute` se ainda não houve execute formal mas a trilha fechou aqui), actualizar o JSON: `lifecycle: { "status": "closed", "since": "<ISO>" }` e espelhar em **`STATE.md`** (**lifecycle_status** → `closed`). Não fechar como `closed` se `verify_failed` ou gaps por resolver.
-6. Acrescentar entrada em **`.oxe/SUMMARY.md`** (sessão): se não existir, criar a partir de **`oxe/templates/SUMMARY.template.md`**. **Obrigatório** quando `verify_failed` ou quando a seção **Gaps** tiver itens — isso alimenta o replanejamento.
-7. **Só se todas as verificações relevantes passarem:** se `after_verify_draft_commit` não for `false`: acrescentar em **VERIFY.md** a seção **Rascunho de commit** — mensagem convencional (ex.: `feat:` / `fix:`) + bullets alinhados aos critérios **A***; **não** incluir segredos.
-8. **Só se passou:** se `after_verify_suggest_pr` não for `false`: acrescentar **Checklist PR** — branch base, título sugerido, screenshots se UI, links a SPEC/PLAN, testes executados.
+   - **Tabela — Fidelidade de decisões** (se DISCUSS.md existir): ID | Decisão | Tarefa(s) | Implementado? | Evidência.
+   - **Checklist UAT** (Camada 4).
+   - **Gaps** — o que falhou e sugestão de correção; se não houver, escrever `Nenhum gap restante`.
+6. Atualizar **`.oxe/STATE.md`**: `verify_complete` ou `verify_failed` + próximo passo (replan, corrigir ou publicar).
+6b. **Blueprint plan-agent:** se **todas** as verificações relevantes **passaram**, existir **`.oxe/plan-agents.json`** com `oxePlanAgentsSchema === 2` e `lifecycle.status === "executing"` (ou `pending_execute`), actualizar o JSON: `lifecycle: { "status": "closed", "since": "<ISO>" }` e espelhar em **`STATE.md`** (**lifecycle_status** → `closed`). Não fechar como `closed` se `verify_failed` ou gaps por resolver.
+7. Acrescentar entrada em **`.oxe/SUMMARY.md`** (sessão): se não existir, criar a partir de **`oxe/templates/SUMMARY.template.md`**. **Obrigatório** quando `verify_failed` ou quando a seção **Gaps** tiver itens.
+8. **Só se todas as verificações relevantes passarem:** se `after_verify_draft_commit` não for `false`: acrescentar em **VERIFY.md** a seção **Rascunho de commit** — mensagem convencional (ex.: `feat:` / `fix:`) + bullets alinhados aos critérios **A*** e decisões **D-NN**; **não** incluir segredos.
+9. **Só se passou:** se `after_verify_suggest_pr` não for `false`: acrescentar **Checklist PR** — branch base, título sugerido, screenshots se UI, links a SPEC/PLAN/DISCUSS, testes executados.
 </process>
 
 <success_criteria>
-- [ ] VERIFY.md reflete o que foi de fato verificado (tarefas **e** critérios SPEC por ID).
+- [ ] VERIFY.md contém as quatro seções: Auditoria de pré-execução, Tabela de tarefas, Tabela de critérios SPEC, Fidelidade de decisões (quando aplicável), Checklist UAT.
+- [ ] Auditoria de pré-execução passou ou divergências foram documentadas.
 - [ ] Falhas têm próximo passo claro (qual tarefa replanejar ou qual arquivo corrigir); se falhou, próximo passo inclui **plan** com replanejamento ou correção direta.
 - [ ] STATE.md atualizado.
 - [ ] SUMMARY.md atualizado quando houver falha ou gaps relevantes.
 - [ ] Se passou: seções **Rascunho de commit** e **Checklist PR** presentes em VERIFY.md, salvo se desativadas na config.
+- [ ] Se existiu DISCUSS.md: tabela de Fidelidade de decisões preenchida sem divergências não documentadas.
 </success_criteria>

package/oxe/workflows/workstream.md

@@ -0,0 +1,96 @@
+# OXE — Workflow: workstream
+
+<objective>
+Gerenciar **trilhas de desenvolvimento paralelas** dentro do mesmo projeto. Cada workstream tem seu próprio ciclo SPEC → PLAN → EXECUTE → VERIFY independente, sem interferir no pipeline principal.
+
+Subcomandos:
+- `/oxe-workstream list` — listar workstreams ativos.
+- `/oxe-workstream new <nome>` — criar novo workstream.
+- `/oxe-workstream switch <nome>` — definir workstream ativo no contexto atual.
+- `/oxe-workstream status [nome]` — exibir status de um workstream.
+- `/oxe-workstream close <nome>` — fechar workstream e mesclar contexto ao pipeline principal.
+</objective>
+
+<context>
+**Por que workstreams?**
+
+O pipeline OXE padrão (`.oxe/SPEC.md`, `PLAN.md`, etc.) é linear — uma entrega por vez. Workstreams permitem:
+- Desenvolvimento de features paralelas sem sobrescrever artefatos.
+- Trabalho em `bugfix/auth` e `feature/billing` simultaneamente.
+- Times menores trabalhando em trilhas independentes com contextos separados.
+
+**Estrutura no disco:**
+```
+.oxe/
+  workstreams/
+    <nome>/
+      SPEC.md
+      PLAN.md
+      VERIFY.md
+      DISCUSS.md      (opcional)
+      STATE.md        (estado local da trilha)
+      config.json     (herda do config principal; pode sobrescrever keys)
+```
+
+**Compatibilidade:**
+- O pipeline principal (`.oxe/SPEC.md`, `.oxe/PLAN.md`, etc.) continua funcionando normalmente.
+- Workstreams **não** substituem o pipeline principal — são adicionais.
+- `oxe-cc doctor` e `oxe-cc status` reportam cada workstream separadamente quando `--workstream=<nome>` for passado.
+- A seção **Workstreams ativos** do STATE.md principal lista os workstreams em andamento.
+</context>
+
+<process_list>
+**`/oxe-workstream list`**
+
+1. Ler `.oxe/workstreams/` — listar subpastas.
+2. Para cada workstream, ler seu `STATE.md` local (fase e próximo passo).
+3. Exibir tabela no chat: Nome | Fase | Próximo passo | Última atividade.
+</process_list>
+
+<process_new>
+**`/oxe-workstream new <nome>`**
+
+1. Validar que `<nome>` é um slug seguro (letras, números, hífens — sem espaços ou caracteres especiais).
+2. Criar `.oxe/workstreams/<nome>/STATE.md` a partir de `oxe/templates/STATE.md`.
+3. Criar `.oxe/workstreams/<nome>/config.json` vazio (herda do config principal).
+4. Atualizar **STATE.md principal**: adicionar `<nome>` na seção **Workstreams ativos**.
+5. Confirmar no chat: `Workstream '<nome>' criado. Próximo passo: /oxe-spec (no contexto do workstream)`.
+
+**Convenção:** para operar em um workstream, prefixar os artefatos com `--workstream=<nome>` ou ativar com `/oxe-workstream switch <nome>`.
+</process_new>
+
+<process_switch>
+**`/oxe-workstream switch <nome>`**
+
+1. Verificar que `.oxe/workstreams/<nome>/` existe.
+2. Atualizar STATE.md principal: seção **Workstream ativo** com nome.
+3. Confirmar no chat: `Workstream ativo: <nome>. Artefatos em .oxe/workstreams/<nome>/`.
+
+Após ativar, os workflows `/oxe-spec`, `/oxe-plan`, `/oxe-execute`, `/oxe-verify` operam nos artefatos do workstream ativo em vez dos artefatos raiz.
+</process_switch>
+
+<process_status>
+**`/oxe-workstream status [nome]`**
+
+1. Se `nome` omitido: usar workstream ativo do STATE.md.
+2. Ler `.oxe/workstreams/<nome>/STATE.md` — fase e próximo passo.
+3. Ler SPEC, PLAN, VERIFY do workstream (se existirem).
+4. Exibir resumo: fase, critérios, gaps, próximo passo.
+</process_status>
+
+<process_close>
+**`/oxe-workstream close <nome>`**
+
+1. Verificar que o workstream está com `verify_complete` no seu STATE.md local.
+2. Se não estiver: alertar e pedir confirmação com `--force`.
+3. Mover (ou arquivar) `.oxe/workstreams/<nome>/` → `.oxe/workstreams/closed/<nome>-YYYY-MM-DD/`.
+4. Atualizar STATE.md principal: remover `<nome>` de **Workstreams ativos**, registrar em **Workstreams encerrados**.
+5. Confirmar no chat: `Workstream '<nome>' encerrado. Artefatos em .oxe/workstreams/closed/`.
+</process_close>
+
+<success_criteria>
+- [ ] `.oxe/workstreams/<nome>/` existe com STATE.md local.
+- [ ] STATE.md principal lista workstream na seção **Workstreams ativos**.
+- [ ] Workflows OXE operam no workstream ativo quando configurado.
+- [ ] Ao encerrar: artefatos arquivados e STATE principal atualizado.
+</success_criteria>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oxe-cc",
-  "version": "0.3.8",
+  "version": "0.5.0",
   "description": "OXE — spec-driven workflows in .oxe/; integrates with Cursor, GitHub Copilot, Claude, OpenCode, Gemini, Codex, Windsurf, Antigravity (npx)",
   "license": "GPL-3.0",
   "author": "",
@@ -49,7 +49,8 @@
     ".github",
     "commands",
     "AGENTS.md",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "sync:cursor": "node scripts/sync-cursor-from-prompts.cjs",