@spec-wave/cli 0.14.0 → 0.16.0

package/src/templates/skill/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: spec-wave
 description: "Use when the user wants to set up a spec-driven GitHub workflow, create a Feature issue, generate spec.md or plan.md, decompose a Feature into Stories/Tasks, write RFC documentation, or audit and fix a Pull Request. Implements the RFC-001 workflow with GitHub Projects v2, labels, and AI-powered GitHub Actions."
-argument-hint: "[info|setup|update|doctor|issue|feature|spec|plan|ready|decompose|order|implement|task|story|move|uninstall|rfc|fix-pr] [target]"
+argument-hint: "[info|setup|update|doctor|issue|feature|spec|plan|ready|decompose|order|implement|task|story|move|uninstall|rfc|bug|triage|fix-pr] [target]"
 user-invocable: true
 allowed-tools:
   - Bash(npx @spec-wave/cli@latest *)
@@ -76,7 +76,7 @@ Exceção: se o usuário pedir explicitamente para revisar ou melhorar um docume
 ## Fluxo Kanban
 
 ```
-📥 Backlog → 🎯 Priorizado → 📋 Spec → 📋 Plan → ✅ Ready
+📥 Backlog → 🐞 Triagem → 🎯 Priorizado → 📋 Spec → 📋 Plan → ✅ Ready
 → 🚧 Desenvolvimento → 👀 Code Review
 → 🧪 QA → 📋 Homologação → 🚀 Deploy → 🎉 Done
 ```
@@ -90,7 +90,7 @@ Essa é a sequência completa, mas **cada tipo de artefato percorre só um trech
 | **Story** | **✅ Ready** (criada pelo `decompose-apply`) | 🚧 Desenvolvimento → 👀 Code Review → 🧪 QA → 📋 Homologação → 🎉 Done | **Nunca nasce em 📥 Backlog.** |
 | **Task** | **✅ Ready** (criada pelo `decompose-apply`) | 🚧 Desenvolvimento → 🎉 Done | **Não** passa por Code Review, QA nem Homologação — só `task start` e `task done`. |
 | **RFC** | 📥 Backlog | decompõe direto em **Tasks** (que nascem em ✅ Ready) | Não usa spec/plan. |
-| **Bug** | 📥 Backlog | 🚧 Desenvolvimento → 🎉 Done | Ao aprovar, vai direto para Done (não passa por Homologação). |
+| **Bug** | **🐞 Triagem** (reportado) ou **✅ Ready** (achado em QA/Homologação/review) | ✅ Ready → 🚧 Desenvolvimento → 👀 Code Review → 🧪 QA → 🚀 Deploy → 🎉 Done | Não passa por 🎯 Priorizado, 📋 Spec, 📋 Plan nem 📋 Homologação. Bug **P0** nasce direto em ✅ Ready — a triagem é confirmada depois. |
 | **Spike** | 📥 Backlog | **movido só à mão pelo usuário** | Nunca avance a Etapa de um Spike por conta própria. |
 
 **Regra da Etapa:** a Etapa **só avança, nunca retrocede**. O campo **Status** (Todo / In Progress / Done) mede o progresso *dentro* da Etapa e reinicia a cada avanço. Prefira sempre os comandos da CLI (`move`, `task start|done`, `story review`) a mutações manuais no board — eles embutem essas regras.
@@ -101,12 +101,14 @@ Labels de gatilho:
 - `spec-wave:ready` → dispara `validate.yml` → valida ambos os arquivos
 - `spec-wave:decompose` → dispara `decompose.yml` → gera (ou **re-critica**) o **rascunho** em `decomposition.md`. **Não cria issue nenhuma.**
 - `spec-wave:decompose-apply` → dispara o mesmo workflow em modo aplicação → cria as Stories e Tasks **a partir do rascunho revisado**
+- `spec-wave:bug` → dispara `generate-bug.yml` → gera `docs/bugs/<slug>/bug.md` (só para issues `[BUG]`)
 
 Labels de **estado** (gravadas pelas automações — **não** são gatilhos, não as adicione por conta própria):
 - `spec-wave:decompose-ready` → o rascunho da decomposição passou pela crítica e espera **revisão humana**; aplique `spec-wave:decompose-apply` para criar as issues
 - `spec-wave:critique-failed` → a crítica adversarial apontou contradições **graves**; **bloqueia** o `spec-wave:ready` até ser removida (veja *Crítica adversarial* abaixo)
 - `spec-wave:needs-human` → a crítica reprovou N vezes seguidas (default 3); **para o fluxo** até uma pessoa revisar e remover a label
 - `spec-wave:decomposed` → a Feature/RFC já foi decomposta; o `decompose` pula silenciosamente enquanto ela existir (veja *Guard de idempotência* abaixo)
+- `spec-wave:bug-approved` → o `bug.md` passou na validação das seis seções obrigatórias
 
 Label **modificadora** (esta você pode aplicar):
 - `spec-wave:model:<apelido>` → força um modelo específico **naquela execução**, resolvido por `ai.modelAliases` no `.spec-wave.json`. Serve para reprocessar um caso difícil num modelo mais forte sem editar a configuração do repositório inteiro. Duas dessas labels na mesma issue = ambíguo, nenhuma vale.
@@ -180,11 +182,19 @@ Mesmas flags do `issue` (exceto `--type`, fixo em `feature`). Mantido para o flu
 |------|------|-----------|
 | `--global` | flag | Verifica a skill no escopo do usuário (padrão: projeto). |
 | `--skip-skill` / `--skip-config` / `--skip-repo` | flag | Pula a categoria correspondente. |
+| `--branch [nome]` | flag/string | Envia os arquivos do repo como **Pull Request** numa branch, em **um único commit**, em vez de commitar direto na branch default. Sem valor, usa `spec-wave/update-v<versão>`. |
+| `--config-in-pr` / `--no-config-in-pr` | flag | Força incluir/excluir o `.spec-wave.json` do PR (o default decide sozinho — veja abaixo). |
 | `--dry-run` | flag | Mostra o que seria atualizado sem alterar nada. |
 | `--yes` | flag | Aplica sem pedir confirmação. |
 
 > Detecta e atualiza **somente o que divergiu** da versão atual da CLI: a **skill** instalada (por agente), o **`.spec-wave.json`** local (se versão/formato divergir) e os **workflows/labels** do repo (compara com os templates empacotados). Interativo por padrão (mostra o plano e confirma). É o atalho recomendado após atualizar a CLI.
 
+> **`--branch` (modo Pull Request).** Sem a flag, os arquivos do repo vão em **commits diretos na branch default** — o que falha no meio da execução em repositório com proteção de branch, deixando parte aplicada, e contorna a revisão. Com a flag, todos os arquivos vão em **um commit atômico** numa branch nova e um PR é aberto: se algo falhar antes da criação da branch, **nada** é alterado no repositório. É **idempotente** — rodar duas vezes não gera um segundo commit nem um segundo PR.
+>
+> Duas coisas **não** entram no PR, porque não são versionáveis: as **labels** (metadado do repositório — já valem na base, com ou sem merge) e a **skill** (arquivo em máquina local). O corpo do PR diz isso explicitamente a quem revisa.
+>
+> ⚠️ O modo PR exige **`pull_requests: write`** além de `contents: write` (ou o escopo `repo` num PAT classic). Sem essa permissão, a branch é criada e o PR falha — a mensagem oferece a URL de `compare` para abrir à mão.
+
 ### `@spec-wave/cli generate-plan` · `generate-spec` · `validate` · `decompose`
 | Flag | Tipo | Descrição |
 |------|------|-----------|
@@ -417,12 +427,16 @@ Traz tudo para a versão atual da CLI, atualizando **só o que mudou**: a skill
    npx @spec-wave/cli@latest update --dry-run
    ```
 2. Mostre ao usuário o resumo (skill / config / arquivos do repo / labels que divergiram). Se **nada** estiver desatualizado, informe que já está tudo na versão atual e encerre.
-3. Se o usuário aprovar, aplique:
+3. **Pergunte como os arquivos do repo devem sair** — e prefira o Pull Request:
    ```bash
-   npx @spec-wave/cli@latest update --yes
+   npx @spec-wave/cli@latest update --yes --branch     # 1 commit atômico + PR (recomendado)
+   npx @spec-wave/cli@latest update --yes              # commits diretos na branch default
    ```
    - Escopos podem ser limitados com `--skip-skill`, `--skip-config`, `--skip-repo`.
-   - Atualizações de **arquivos do repo** são commitadas no remoto; o **`.spec-wave.json`** é local (lembre o usuário de commitá-lo).
+   - **Com `--branch`:** os arquivos do repo vão em **um único commit** numa branch nova e um PR é aberto — nada é escrito na branch default. Passe o link do PR ao usuário e lembre que o merge é dele. Exige `pull_requests: write` no token.
+   - **Sem `--branch`:** cada arquivo é um commit direto na branch default. Em repositório com **proteção de branch** isso falha no meio e deixa parte aplicada — nesses casos use `--branch`.
+   - **Nos dois modos**, as **labels** são aplicadas direto na base (metadado do repositório, não versionável) e a **skill** é gravada em máquina local. Nenhuma das duas entra no PR.
+   - **`.spec-wave.json`:** com `--branch`, ele entra no PR se o repositório **já o versiona**; se não versiona, segue apenas local e o usuário precisa commitá-lo (ou use `--config-in-pr` para passar a versioná-lo). Sem `--branch`, é sempre só local.
 4. Se a skill foi atualizada, oriente recarregar/reiniciar o agente para pegar a nova versão.
 
 ---
@@ -650,7 +664,7 @@ Aciona o spec-kit para implementar uma **Feature** (todas as Stories pendentes,
    ```
    - Se o spec-kit **não** estiver configurado, o comando só monta o contexto e mostra como configurar (`specKit.command` / `SPEC_WAVE_IMPLEMENT_CMD`). Ajude o usuário a definir o template (placeholders: `{tasksFile} {specFile} {planFile} {issue} {type} {title}`).
    - Use `--feature-dir docs/features/<slug>` se a resolução automática da Feature falhar (a skill avisa com warning) e você quiser anexar `spec.md`/`plan.md` como contexto.
-6. **No modo Feature**, siga o contexto Story a Story, na ordem listada: para cada Story pendente, implemente as Tasks com `task start`/`task done`, depois commit + PR + `npx @spec-wave/cli@latest story review <n>`; só então passe à próxima Story. Se a issue **não** for Feature, Story nem Task (ex.: Bug, Spike, Epic), o comando recusa. Feature **sem Stories** → rode `/spec-wave decompose` primeiro. **Ciclo de dependências** → corrija as linhas `Depende de:` (veja `spec-wave order`).
+6. **No modo Feature**, siga o contexto Story a Story, na ordem listada: para cada Story pendente, implemente as Tasks com `task start`/`task done`, depois commit + PR + `npx @spec-wave/cli@latest story review <n>`; só então passe à próxima Story. **Bug** tem modo próprio (RFC-004): sem tasks e sem spec/plan, com quatro fases — reproduzir → causa raiz → fix mínimo → teste de regressão — e o `bug.md` entrando como hipótese a confirmar. Se a issue não for Feature, Story, Task nem Bug (ex.: Spike, Epic), o comando recusa. Feature **sem Stories** → rode `/spec-wave decompose` primeiro. **Ciclo de dependências** → corrija as linhas `Depende de:` (veja `spec-wave order`).
 7. Ao final (Tasks em **🎉 Done**, Story em **👀 Code Review**; a Feature só vai para Code Review quando a última Story concluir — no modo Feature, isso acontece dentro da mesma execução): confirme o resultado com o usuário e oriente a revisão dos PRs.
 
 ---
@@ -678,6 +692,54 @@ Crie um documento RFC seguindo a estrutura do RFC-001.
 
 ---
 
+### `/spec-wave bug <número-da-issue>`
+
+Gera o **`bug.md`** de um defeito: `docs/bugs/<slug>/bug.md`, com reprodução, causa raiz, escopo do fix e teste de regressão.
+
+> **Nunca escreva o `bug.md` à mão.** Aplique a label e deixe o Action gerar — é isso que garante o arquivo commitado e referenciado na issue.
+
+**Por que não spec/plan:** um Bug não gera especificação funcional nem plano técnico. Esses documentos pedem critérios de aceite, requisitos não-funcionais e plano de rollback — peso desproporcional para um defeito. O `bug.md` tem seis seções e uma finalidade: permitir que outra pessoa (ou o dev-agent) reproduza, entenda e corrija, com prova de que corrigiu.
+
+**Passos:**
+
+1. Confirme que a issue é do tipo **Bug** (para outros tipos o Action pula, remove a label e comenta).
+2. `gh issue edit <n> --add-label "spec-wave:bug"`
+3. Avise: o Action `generate-bug.yml` gera e commita o arquivo.
+4. Ofereça revisar **duas seções**: **Causa Raiz** e **Teste de Regressão**. São elas que decidem se a correção ataca o defeito ou o sintoma.
+5. Validar: `spec-wave:ready` → confere as seis seções e aplica `spec-wave:bug-approved`.
+
+**Seções obrigatórias** (o validador as compara byte a byte — não renomeie ao editar):
+`Reprodução` · `Esperado e Obtido` · `Impacto e Severidade` · `Causa Raiz` · `Escopo do Fix` · `Teste de Regressão`
+
+**Quando é obrigatório:** **P0** dispensa (o fix não espera documento); **P1** recomendado; **P2/P3** obrigatório antes de o bug entrar na fila técnica (✅ Ready).
+
+**Se a crítica reprovar** (`spec-wave:critique-failed`), os três alvos mais comuns são: a causa raiz não explica todos os sintomas relatados; o escopo do fix é maior que a causa (refatoração pegando carona); o teste de regressão passaria mesmo sem o fix.
+
+**Relato insuficiente** produz "Causa raiz não determinada" com hipóteses — isso é o comportamento correto, não falha. Leve as perguntas a quem reportou, acrescente as respostas **como comentário na issue** e reaplique `spec-wave:bug`: os comentários entram no próximo payload.
+
+---
+
+### `/spec-wave triage <accept|reject|duplicate> <número>`
+
+Desfecho da triagem de um Bug (RFC-004 §4.1) — o mesmo que a tela de Bugs do PM oferece, pelo terminal.
+
+```bash
+npx @spec-wave/cli@latest triage accept 42
+npx @spec-wave/cli@latest triage accept 42 --severity P1     # reclassifica ao aceitar
+npx @spec-wave/cli@latest triage reject 42 --reason "comportamento esperado"
+npx @spec-wave/cli@latest triage duplicate 42 --of 17
+```
+
+- **accept** → ✅ Ready, com a label `spec-wave:triaged`.
+- **reject** e **duplicate** → **fecham** a issue e **não mexem na Etapa**: ela nunca retrocede, e um bug rejeitado não avançou para lugar nenhum. Quem o tira das filas é o estado `closed`.
+- `duplicate` comenta **nas duas** issues — sem isso, quem acompanha a original não fica sabendo que há outro relato.
+
+**Portão de aceite:** **P2/P3** exigem o `bug.md` validado (`spec-wave:bug-approved`) antes da fila. **P0/P1** dispensam — esperar o documento custa mais que investigar durante a correção. E `spec-wave:critique-failed` ou `spec-wave:needs-human` bloqueiam **qualquer** severidade: aceitar um bug cujo documento foi reprovado é justamente o que o portão existe para evitar.
+
+Para criar um Bug: `npx @spec-wave/cli@latest bug --title "..." [--parent <n>] [--priority P2]`. Ele nasce em **🐞 Triagem** — ou direto em **✅ Ready** se for **P0**.
+
+---
+
 ### `/spec-wave fix-pr <número-do-pr>`
 
 Audita um Pull Request e corrige automaticamente os problemas encontrados — segurança, arquitetura, infraestrutura e qualidade de código. Cada fix vira um commit separado no branch do PR. Cada review comment recebe uma resposta com o hash do commit.

package/src/templates/workflows/generate-bug.yml

@@ -0,0 +1,36 @@
+name: Generate Bug
+
+on:
+  issues:
+    types: [labeled]
+
+concurrency:
+  group: spec-wave-generate-bug-${{ github.event.issue.number }}
+  cancel-in-progress: false
+
+jobs:
+  generate-bug:
+    if: >
+      github.event.label.name == 'spec-wave:bug' &&
+      contains(github.event.issue.title, '[BUG]')
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+
+      - name: Generate bug.md
+        run: npx @spec-wave/cli@{{CLI_VERSION}} generate-bug --issue-number ${{ github.event.issue.number }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
+          GITHUB_REPOSITORY: ${{ github.repository }}

package/src/templates/workflows/validate.yml

@@ -12,7 +12,8 @@ jobs:
   validate:
     if: >
       github.event.label.name == 'spec-wave:ready' &&
-      contains(github.event.issue.title, '[FEATURE]')
+      (contains(github.event.issue.title, '[FEATURE]') ||
+       contains(github.event.issue.title, '[BUG]'))
     runs-on: ubuntu-latest
     permissions:
       issues: write

package/src/ui/wizard.mjs

@@ -1,6 +1,9 @@
 import * as p from '@clack/prompts';
 import { execSync } from 'node:child_process';
-import { AI_PROVIDERS, getProvider, DEFAULT_PROVIDER, WORKFLOW_FILES, ISSUE_TEMPLATE_FILES } from '../config.mjs';
+import {
+  AI_PROVIDERS, getProvider, DEFAULT_PROVIDER, WORKFLOW_FILES, ISSUE_TEMPLATE_FILES,
+  STATUS_OPTIONS, CUSTOM_FIELDS, ALL_LABELS,
+} from '../config.mjs';
 
 export async function runWizard() {
   p.intro('spec-wave — configuração do fluxo spec-driven');
@@ -62,7 +65,7 @@ export async function runWizard() {
 
       confirm: ({ results }) =>
         p.confirm({
-          message: `Configurar ${results.repo} com GitHub Project "${results.projectTitle}"?\n  - 12 colunas kanban\n  - 5 campos customizados\n  - 15 labels\n  - ${WORKFLOW_FILES.length} workflows + ${ISSUE_TEMPLATE_FILES.length} issue templates`,
+          message: `Configurar ${results.repo} com GitHub Project "${results.projectTitle}"?\n  - ${STATUS_OPTIONS.length} colunas kanban\n  - ${CUSTOM_FIELDS.length} campos customizados\n  - ${ALL_LABELS.length} labels\n  - ${WORKFLOW_FILES.length} workflows + ${ISSUE_TEMPLATE_FILES.length} issue templates`,
           initialValue: true,
         }),
     },