@spec-wave/cli 0.28.0 → 0.30.0

package/src/plugin/skills/qa/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: spec-wave-qa
+description: "Use para a etapa 🧪 QA do spec-wave — gerar o plano de QA de uma Feature (label spec-wave:qa → qa-plan.md), revisá-lo, e EXECUTAR os cenários localmente com `spec-wave qa <issue>` (Feature, Story ou Bug). Verde move o board sozinho; vermelho abre um Bug por cenário reprovado. Gatilhos: 'rodar o QA', 'validar a feature 12', 'gerar o plano de QA', 'testar a story 34', 're-testar o cenário 2'."
+allowed-tools:
+  - Bash(npx @spec-wave/cli@latest qa *)
+  - Bash(npx @spec-wave/cli@latest generate-qa-plan *)
+  - Bash(npx @spec-wave/cli@latest doctor)
+  - Bash(gh issue *)
+  - Read
+  - Write
+  - Edit
+---
+
+# spec-wave qa — etapa 🧪 QA
+
+Duas metades, em ordem obrigatória:
+
+1. **Gerar o plano** (label + Action): `spec-wave:qa` na **Feature** → o Action gera `docs/features/<slug>/qa-plan.md`, valida, critica e aplica `spec-wave:qa-ready`.
+2. **Executar** (sempre local): `npx @spec-wave/cli@latest qa <issue>` roda os cenários contra o checkout e emite o veredito.
+
+**Nunca rode o `qa` sem a `spec-wave:qa-ready` na Feature** — o comando recusa, e o motivo é de desenho (D-QA3/D-QA4): o veredito **verde avança a Etapa sozinho, sem confirmação humana**, então o portão humano é a **revisão do plano**, antes de executar.
+
+## 0. Detecção de configuração (antes de qualquer coisa)
+
+Confirme que existe `.spec-wave.json` no repositório (senão → skill **setup**). Para executar de fato, o comando do executor precisa estar em `qa.command` no `.spec-wave.json` (ou na env `SPEC_WAVE_QA_CMD`, que tem precedência):
+
+```json
+{
+  "qa": {
+    "command": "claude -p \"Execute o QA descrito em {contextFile}\"",
+    "setup": "npm ci && npm run build",
+    "env": { "BASE_URL": "http://localhost:3000" },
+    "defaultBugPriority": "P2"
+  }
+}
+```
+
+Placeholders: `{contextFile} {qaPlanFile} {specFile} {issue} {type} {title}`. Sem `qa.command`, o comando monta o contexto, imprime como configurar e **não executa** — não é erro.
+
+## 1. Gerar o plano (Feature)
+
+```bash
+gh issue edit <feature> --add-label "spec-wave:qa"
+```
+
+- **Só em Feature** (D-QA1: o plano é por Feature, arquivo único, seções `## Cenário N — Story #X`). Numa Story o Action comenta apontando a Feature-pai; num Bug, não se aplica (ver §5).
+- Arquivo **ausente** → gera via IA e publica em Pull Request. Arquivo **presente** → valida + critica **COMO ESTÁ** (edições manuais são preservadas — mesma semântica do decompose). Para regerar do zero: apague o arquivo e reaplique a label.
+- Requer `spec.md` e `plan.md` já na base.
+- Desfechos: limpo → `spec-wave:qa-ready` + comentário com o resumo; grave → `spec-wave:critique-failed`; reprovas repetidas → `spec-wave:needs-human`.
+
+## 2. Revisar e editar o qa-plan.md (o portão humano)
+
+Leia o plano com o usuário ANTES de executar. Regras do arquivo:
+
+- A estrutura é só `## Cenário N — Story #X`; o corpo aceita markdown livre.
+- **A posição manda, não o número escrito** — inserir um cenário no meio sem renumerar funciona.
+- `Story #X` é obrigatório e precisa ser sub-issue da Feature.
+- `**Critério:**` e `**Esperado:**` são obrigatórios; `**Pré-condições:**` e `**Passos:**` opcionais.
+- Depois de editar, reaplique `spec-wave:qa` para uma nova crítica (o arquivo NÃO é regerado).
+
+> ⚠️ O slug vem do **título** da Feature. Renomeá-la depois da geração órfã o arquivo — o comando falha citando o slug órfão.
+
+## 3. Executar — SEMPRE `--dry-run` primeiro
+
+```bash
+npx @spec-wave/cli@latest qa <issue> --dry-run   # mostra cenários-alvo e o comando; ZERO escrita no GitHub
+npx @spec-wave/cli@latest qa <issue>             # executa de fato
+```
+
+Mostre ao usuário o contexto montado em `.spec-wave/qa-<n>.md` antes de rodar sem `--dry-run`.
+
+Alvos: `qa <feature>` roda todos os cenários das Stories ainda sem `qa-approved`; `qa <story>` só os daquela Story; `qa <bug>` o Teste de Regressão do `bug.md`; `--only <n[,m]>` filtra por número posicional.
+
+**PROIBIDO corrigir código durante a execução.** QA não conserta: cenário reprovado vira Bug, e alterar o código no meio invalida o veredito. Se você for o executor (via `qa.command`), siga as instruções do contexto à risca — um cenário por vez, evidência bruta, `blocked` (nunca `fail`) para o que não pôde rodar.
+
+## 4. Os três desfechos
+
+| Veredito | O que aconteceu | O que fazer |
+|---|---|---|
+| ✅ **verde** (todos pass) | `qa-approved` aplicada; Story → 📋 Homologação; Feature move quando TODAS as Stories liberarem; Bug → 🚀 Deploy | Nada — o board já andou. Se a Story tinha **Bug filho aberto**, ela NÃO avança (guarda dura): feche o Bug primeiro. |
+| ❌ **vermelho** (algum fail) | 1 Bug por cenário reprovado (filho da Story dona, ✅ Ready, `bug.md` commitado, `bug-approved` aplicada); item fica em 🧪 QA; exit 1 | Corrija os Bugs (skill **implement**) e re-teste (§6). |
+| ⚪ **inconclusivo** (blocked, sem fail) | Ambiente quebrado não é defeito: nada move, nenhum Bug; exit 1 | Destrave o ambiente (seed, serviço fora do ar) e rode de novo. |
+
+## 5. Bug — exceção documentada (§2.1 da spec)
+
+O QA de um **Bug** usa a seção `Teste de Regressão` do próprio `bug.md` (não há qa-plan). Verde move o Bug para **🚀 Deploy** (D-QA6 — Bug não passa por Homologação).
+
+E quando um cenário reprova, o `bug.md` do Bug novo **é escrito pelo comando, sem IA e sem a label `spec-wave:bug`** — exceção explícita à regra "nunca escreva o bug.md à mão": a reprodução, o esperado/obtido e o teste de regressão já existem e são determinísticos (são o cenário + a saída real). O arquivo é commitado e a `spec-wave:bug-approved` aplicada pelo próprio comando. **Não** aplique `spec-wave:bug` nesses Bugs — regeraria por IA um documento que registra uma execução observada.
+
+## 6. Ciclo de re-teste
+
+1. Fix do Bug (skill **implement**, PR, merge).
+2. Re-teste só o cenário: `npx @spec-wave/cli@latest qa <story> --only <cenário>`.
+3. O comando NÃO duplica Bug: se o cenário reprovar de novo, ele comenta no Bug existente (marcador `spec-wave:qa-origin`).
+4. Verde com o Bug ainda aberto não avança a Story — feche o Bug (o fix mergeado + regressão verde justificam) e rode o `qa` de novo.
+
+## Recusas que você vai encontrar (e o que significam)
+
+- Sem `.spec-wave.json` → rode a skill **setup**.
+- `spec-wave:qa` ainda na issue → geração em voo; aguarde o Action.
+- `critique-failed`/`needs-human` → portão humano da crítica; corrija o documento apontado.
+- Feature sem `qa-ready` → gere/critique o plano primeiro (§1).
+- Etapa **anterior** a 🧪 QA → o `qa` não promove item; quem move até QA é o merge (`spec-wave merge` / `run --pr`).
+- Etapa **posterior** → informa e sai 0 (a Etapa nunca retrocede).
+- Nenhum cenário casando com a Story → plano desatualizado (re-decompose criou Stories novas) ou Feature renomeada (slug órfão).

package/src/plugin/skills/qa/model-prompt.critique.md

@@ -0,0 +1,44 @@
+---
+name: critique-qa-plan
+action: critique
+description: Critério da crítica adversarial do qa-plan.md contra spec, plan e decomposição, antes da liberação para execução.
+tools: [Read, Glob, Grep]
+maxTurns: 20
+lenses:
+  - "cobertura — algum critério de aceite da spec ficou sem cenário correspondente?"
+  - "vacuidade — algum cenário passaria mesmo sem a implementação, ou tem esperado não observável?"
+  - "fidelidade — algum cenário testa implementação em vez de comportamento, ou contradiz a spec?"
+---
+
+# Crítica adversarial do plano de QA
+
+Você audita o `qa-plan.md` proposto contra o `spec.md`, o `plan.md` e a decomposição. Seu papel é encontrar problemas, não elogiar.
+
+Este portão importa mais que os outros: o veredito **verde da execução avança a Etapa sozinho, sem confirmação humana** (D-QA3). Um plano fraco aprovado aqui vira aprovação automática de trabalho não validado.
+
+## O que caracteriza um achado GRAVE
+
+- **Critério de aceite da spec sem cenário correspondente** — a lacuna faz a Feature ser aprovada sem aquele comportamento ter sido validado.
+- **Cenário que passaria SEM a implementação** — ex.: "a página carrega", "o comando não dá erro" num fluxo que existia antes da Feature. É o mesmo vício já caçado no bug.md: um teste que não falharia não valida nada.
+- **Resultado esperado não observável** — "verificar se funciona", "conferir se está correto", "validar o comportamento". Esperado sem critério objetivo torna o veredito arbitrário.
+- **Cenário que testa implementação em vez de comportamento** — "a classe PedidoService existe", "a função retorna um array" — em vez do que o usuário/consumidor observa.
+- **Cenário que contradiz a spec** — esperado que inverte uma regra de negócio explícita.
+- **Cenário atribuído à Story errada** — o comportamento validado pertence a outra Story da decomposição (a reprova abriria o Bug no lugar errado).
+
+## O que é MENOR
+
+Pré-condições vagas mas completáveis, passos que poderiam ser mais concretos, ordem subótima, redundância parcial entre cenários.
+
+<!-- requires-tools -->
+## Como verificar
+
+Você tem `Read`, `Glob` e `Grep`. Confira os passos contra o repositório real: a rota citada existe? O comando citado existe? Um plano cujos passos apontam para o que não existe produziria só `blocked` — e isso é um achado.
+<!-- /requires-tools -->
+
+## Barra de rigor
+
+NÃO invente problemas. Um plano enxuto que cobre os critérios de aceite com esperados observáveis é um resultado legítimo e frequente — diga isso. O inverso também vale: "não consegui confirmar" não é aprovação.
+
+## Consequência
+
+Um achado **grave** aplica `spec-wave:critique-failed` e o plano NÃO é liberado (`spec-wave:qa-ready` não é aplicada): nenhuma execução de QA roda até a correção. Um achado **menor** é comentado e o plano segue. Reserve o grave para o que tornaria o verde automático enganoso.

package/src/plugin/skills/qa/model-prompt.md

@@ -0,0 +1,68 @@
+---
+name: qa-plan
+action: qa
+description: Gera o plano de QA (qa-plan.md) de uma Feature a partir dos critérios de aceite da spec, com um ou mais cenários por Story.
+tools: [Read, Glob, Grep]
+maxTurns: 30
+---
+
+# Plano de QA de uma Feature
+
+Você é um analista de QA experiente. A partir da Feature fornecida (spec.md, plan.md e a lista de Stories reais), escreva o **qa-plan.md**: os cenários de validação funcional que um executor vai rodar contra o checkout, um por critério de aceite relevante.
+
+## Entrada
+
+O payload JSON traz:
+
+- `feature` — número e título da issue da Feature
+- `stories` — as Stories REAIS (número da issue, título, corpo). **Todo cenário pertence a exatamente uma destas Stories, pelo número.**
+- `spec` — o conteúdo de `spec.md` (critérios de aceite, fluxos, regras de negócio)
+- `plan` — o conteúdo de `plan.md` (estratégia técnica — útil para saber COMO exercitar: endpoints, comandos, telas)
+
+## Formato de saída (obrigatório)
+
+Responda APENAS com o documento markdown, neste formato exato:
+
+```markdown
+# Plano de QA — [FEATURE] Título da Feature
+<!-- spec-wave:qa-plan v1 issue=NUMERO_DA_FEATURE -->
+
+## Cenário 1 — Story #412
+
+**Critério:** AC-2 — cliente vê apenas os próprios pedidos
+**Pré-condições:** dois usuários autenticáveis, cada um com ao menos um pedido
+**Passos:**
+1. Autenticar como usuário A
+2. `GET /pedidos`
+**Esperado:** resposta 200 contendo somente pedidos de A; nenhum pedido de B
+
+## Cenário 2 — Story #412
+...
+```
+
+Regras do formato:
+
+- O título de cada seção é `## Cenário N — Story #X`, onde `#X` é o número REAL de uma Story da lista `stories`. **Nunca invente números de issue.**
+- `**Critério:**` e `**Esperado:**` são obrigatórios em todo cenário. `**Pré-condições:**` e `**Passos:**` são opcionais, mas quase sempre necessários.
+- **Toda Story da lista precisa de ao menos um cenário** — uma Story sem cenário reprova o plano na validação determinística.
+- Escreva em português (pt-BR).
+
+## O que faz um cenário BOM
+
+- **Deriva de um critério de aceite da spec** — cite-o no campo `**Critério:**` (ex.: "AC-3 — pedido cancelado não aparece na listagem"). Todo critério de aceite relevante da spec deve ter um cenário correspondente.
+- **Resultado esperado OBSERVÁVEL**: um status HTTP, uma saída de comando, um registro no banco, um texto na tela. "Verificar se funciona" e "conferir se está correto" não são resultados — são a ausência de um.
+- **Falharia sem a implementação**: um cenário que passaria num checkout sem a Feature não valida nada. Pense: "se ninguém tivesse implementado isso, este cenário quebraria?"
+- **Testa COMPORTAMENTO, não implementação**: valide o que o usuário/consumidor observa, não a existência de uma classe ou o nome de uma função.
+- **Executável por alguém sem contexto**: passos concretos (comandos, URLs, payloads), pré-condições explícitas (dados de teste, usuários, estado inicial).
+
+<!-- requires-tools -->
+## Exploração antes de escrever
+
+Você tem `Read`, `Glob` e `Grep` no repositório. Use-os para ancorar os passos no que existe de verdade: os endpoints reais (rotas registradas), os comandos reais (scripts do package.json, Makefile), os seeds/fixtures disponíveis. Um passo `GET /api/pedidos` só vale se essa rota existe com esse nome. Não gaste mais do que o necessário: explore o suficiente para os passos serem executáveis, e então escreva o documento completo.
+<!-- /requires-tools -->
+
+## O que NÃO fazer
+
+- Não inventar suíte de testes automatizada: o plano descreve validação funcional executável contra o checkout, não `describe/it`.
+- Não cobrir requisitos não-funcionais genéricos (performance, segurança) a menos que a spec traga critério de aceite explícito e testável sobre eles.
+- Não duplicar o mesmo critério em vários cenários — um cenário por comportamento distinto.

package/src/templates/config/tech_context.yml

@@ -40,3 +40,16 @@ existing_services:
 internal_libraries:
   - "shared-logger"
   - "db-client (TypeORM)"
+
+# Decisões de modelagem de recursos COMPARTILHADOS entre features (opcional).
+#
+# `criada_por:` é obrigatório em cada entrada: a Feature que cria o recurso
+# (ex.: "FT-01.7" ou "#42"), ou o literal SEM DONO enquanto ninguém o criar.
+# "Não existe feature para editar esses valores" escrito em prosa fica meses
+# sem ninguém agir; SEM DONO aparece no `spec-wave audit` como pendência de
+# checklist antes de planejar a milestone.
+#
+# decisoes_de_modelagem:
+#   - recurso: "custo_canal"
+#     decisao: "Tabela própria; valores editados por ADMIN, consumidos por 4 features"
+#     criada_por: "SEM DONO"

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|bug|triage|fix-pr] [target]"
+argument-hint: "[info|setup|update|doctor|preflight|audit|issue|feature|spec|plan|ready|decompose|order|implement|merge|qa|task|story|move|uninstall|rfc|bug|triage|fix-pr] [target]"
 user-invocable: true
 allowed-tools:
   - Bash(npx @spec-wave/cli@latest *)
@@ -77,7 +77,7 @@ npx @spec-wave/cli@latest mode                 # estado atual dos dois lados do
 npx @spec-wave/cli@latest mode local           # desarma os workflows
 npx @spec-wave/cli@latest run <issue> --dry-run  # explica o próximo passo sem executar
 npx @spec-wave/cli@latest run <issue>          # executa
-npx @spec-wave/cli@latest run --pr <n>         # code-review (+ qa, se houver aprovação)
+npx @spec-wave/cli@latest run --pr <n>         # code-review (+ qa, se aprovado OU mergeado)
 ```
 
 O `run` decide o passo pelo estado da issue (documentos existentes + labels), respeita os portões humanos (`needs-human`, `critique-failed`), recusa rodar com uma label de gatilho pendente e **exige `--apply`** para o `decompose-apply`, que cria issues. Sempre mostre o `--dry-run` ao usuário antes de executar.
@@ -126,6 +126,7 @@ Labels de gatilho:
 - `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]`)
+- `spec-wave:qa` → dispara `generate-qa-plan.yml` → gera (ou **re-critica COMO ESTÁ**) o plano de QA em `docs/features/<slug>/qa-plan.md`. **Só em Feature** (o plano é por Feature; numa Story o Action aponta a Feature-pai). A **execução** é sempre local: `npx @spec-wave/cli@latest qa <issue>`.
 
 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
@@ -133,12 +134,16 @@ Labels de **estado** (gravadas pelas automações — **não** são gatilhos, n
 - `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
+- `spec-wave:qa-ready` → o `qa-plan.md` passou na validação + crítica e espera **revisão humana** — é o pré-requisito de `qa <issue>` (o veredito verde avança a Etapa sozinho, então o portão humano é a revisão do plano). ⚠️ Não confunda com `spec-wave:ready` (gatilho da validação de spec/plan).
+- `spec-wave:qa-approved` → a execução do QA passou. Aplicada na Story (e na Feature, quando todas as Stories passarem).
 
 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.
 
 A etapa **🚧 Desenvolvimento** é coberta pelo comando **local** `npx @spec-wave/cli@latest implement <número>` (não é uma label/Action): lê uma **Feature** (todas as Stories pendentes, em ordem de dependência), uma Story ou uma Task e aciona o spec-kit para implementar. Veja `/spec-wave implement`.
 
+A etapa **🧪 QA** tem artefato e comando próprios: a label `spec-wave:qa` gera o `qa-plan.md` (validado + criticado → `spec-wave:qa-ready`), e a **execução é sempre local** — `npx @spec-wave/cli@latest qa <issue>` roda os cenários contra o checkout. Verde: `qa-approved` + Story → 📋 Homologação (Bug → 🚀 Deploy, sem Homologação). Vermelho: **um Bug por cenário reprovado**, já com `bug.md` commitado. Inconclusivo (`blocked` sem `fail`): nada move, nenhum Bug. Veja `/spec-wave qa`.
+
 ---
 
 ## Referência da CLI (conheça os parâmetros ANTES de executar)
@@ -253,7 +258,44 @@ Sem flags. Roda um checklist de diagnóstico no repositório atual: token GitHub
 |----------|------|-----------|
 | `<feature>` | string (obrigatório) | Número da issue da **Feature**, ex.: `12` ou `#12`. Argumento posicional. |
 
-> **Sem argumento**, monta o mapa de TODAS as Features abertas fora de 🎉 Done num grafo só (conjunto vindo do board), com a Feature de cada Story ao lado — nesse escopo a dependência entre Features entra na ordenação. Com `<feature>`, lista as Stories da Feature em **ordem topológica** pelas dependências (linha `Depende de: #N` no corpo + relação nativa *blocked by*, mescladas), com a Etapa atual de cada uma no board. Dependências para **fora da Feature** não entram na ordenação (não há como saber onde a Story de outra Feature entra nesta sequência), mas aparecem em **"Bloqueadas por fora desta Feature"**, com o estado de cada bloqueadora. Avisa sobre **ciclos de dependência** (essas Stories ficam fora da ordem — corrija as linhas `Depende de`) e sobre **dependências fora de ordem** (Story já em Desenvolvimento+ dependendo de outra que não está Done). Use antes de escolher qual Story implementar.
+> **Sem argumento**, monta o mapa de TODAS as Features abertas fora de 🎉 Done num grafo só (conjunto vindo do board), com a Feature de cada Story ao lado — nesse escopo a dependência entre Features entra na ordenação. Com `<feature>`, lista as Stories da Feature em **ordem topológica** pelas dependências (linha `Depende de: #N` no corpo + relação nativa *blocked by*, mescladas), com a Etapa atual de cada uma no board. Dependências para **fora da Feature** não entram na ordenação (não há como saber onde a Story de outra Feature entra nesta sequência), mas aparecem em **"Bloqueadas por fora desta Feature"**, com o estado de cada bloqueadora. Avisa sobre **ciclos de dependência** (essas Stories ficam fora da ordem — corrija as linhas `Depende de`), sobre **dependências fora de ordem** (Story já em Desenvolvimento+ dependendo de outra que não está Done) e sobre **milestone divergente** (Story sem milestone ou em milestone diferente do da Feature — órfã de toda visão de release; sem milestone na Feature, nada é comparado). Use antes de escolher qual Story implementar, e logo após o `decompose --apply` como detector do pós-apply.
+
+### `@spec-wave/cli preflight --milestone <nome>` — confere tudo ANTES de gerar as specs (comando LOCAL)
+| Flag/Arg | Tipo | Descrição |
+|----------|------|-----------|
+| `--milestone <nome>` | string (obrigatório) | Título da milestone a inventariar. |
+| `--json` | boolean | O relatório em JSON, para ramificar. |
+
+> Um comando reporta: token utilizável, modo de execução (config × variável do repositório), publicação por PR, e as Features da milestone com o **estado do `spec.md` de cada uma** (na base, no disco, em PR aberto, em branch sem PR, a gerar). Existe porque **cada geração paga um modelo**: um erro de configuração descoberto na sétima Feature custa sete gerações — e regenerar um documento que já vive num PR descarta a revisão em curso. Sai com código 1 quando há bloqueio. Rode SEMPRE antes de uma rodada de specs por milestone.
+
+### `@spec-wave/cli audit --milestone <nome>` — cruza as specs da milestone como CONJUNTO (comando LOCAL)
+| Flag/Arg | Tipo | Descrição |
+|----------|------|-----------|
+| `--milestone <nome>` | string (obrigatório) | Título da milestone a auditar. |
+| `--critique` | boolean | Roda também a **crítica adversarial de conjunto** — UMA chamada de modelo sobre todas as specs juntas, procurando contradição ENTRE documentos. |
+| `--json` | boolean | O relatório em JSON (com `critica.markdown` pronto para comentar nas issues). |
+
+> A crítica normal audita cada documento contra os insumos da **mesma** Feature; este comando olha o que só existe **no par**: dependência circular entre Features, bloqueante em milestone **posterior** à de quem depende dela, referência a issue inexistente (materiais — exit 1), dependência que nenhuma Feature cria ("recurso sem dono"), sobreposição do slug com código existente e decisão de modelagem com `criada_por: SEM DONO` no `tech_context.yml` (avisos heurísticos — **confira antes de reportar**). Rode depois que as specs existirem (PR aberto também conta), antes de gerar os planos. Achado material é decisão de PO: comente nas issues **dos dois lados**.
+
+### `@spec-wave/cli merge <feature>` — mergeia os PRs empilhados das Stories (comando LOCAL)
+| Flag/Arg | Tipo | Descrição |
+|----------|------|-----------|
+| `<feature>` | string (obrigatório) | Número da issue da **Feature**, ex.: `12` ou `#12`. |
+| `--yes` | boolean | Executa os merges. **Sem ela, só mostra o plano** (fila na ordem, retargets, avisos). |
+| `--keep-branches` | boolean | Não apaga as branches das Stories após o merge. |
+
+> O `implement` empilha os PRs (cada um baseado no anterior) e o merge da pilha é **ordem-dependente**: `--delete-branch` no primeiro PR fecha o segundo. Este comando encapsula a sequência segura — para cada PR na ordem topológica das Stories: reaponta a base para a default, mergeia com **merge commit**, atualiza o board (**merge move até 🧪 QA**) e **só no fim** apaga as branches. **PR em rascunho bloqueia o plano inteiro** (marcar pronto é a revisão humana — o comando não pula isso). Rodar de novo **retoma**: PR mergeado sai do plano. Use após a revisão, em vez de mergear à mão com `gh`.
+
+### `@spec-wave/cli qa <issue>` — executa o plano de QA localmente (e `qa --pr-number <n>` no Action)
+| Flag/Arg | Tipo | Descrição |
+|----------|------|-----------|
+| `<issue>` | string | Número da **Feature** (todos os cenários das Stories ainda sem `qa-approved`), **Story** (os cenários dela) ou **Bug** (a seção `Teste de Regressão` do `bug.md`). |
+| `--only <n[,m]>` | string | Só o(s) cenário(s) indicado(s) — número **posicional** no plano. O restante herda o veredito do último relatório. |
+| `--severity <p>` | string | Severidade dos Bugs abertos na reprova: `P0`–`P3` (default: `qa.defaultBugPriority` ou `P2`). |
+| `--dry-run` | boolean | Monta o contexto e imprime cenários + comando. **Zero escrita no GitHub.** |
+| `--pr-number <n>` | string | Modo Action (mutuamente exclusivo com `<issue>`): move a Feature/Bug do PR aprovado/mergeado para 🧪 QA. |
+
+> **Pré-requisitos:** Feature dona do plano com `spec-wave:qa-ready` (portão humano — D-QA4), item já em 🧪 QA (o comando **não promove**; Etapa posterior = informa e sai 0), executor em `qa.command` no `.spec-wave.json` (ou `SPEC_WAVE_QA_CMD`) — sem ele, só monta o contexto. **Sempre `--dry-run` primeiro.** Desfechos: verde → `qa-approved` + Story para 📋 Homologação (Bug → 🚀 Deploy; Feature quando TODAS as Stories liberarem; **Bug filho aberto segura a Story mesmo verde**); vermelho → 1 Bug por cenário reprovado (filho da Story, ✅ Ready, `bug.md` determinístico commitado — exceção documentada à regra do `spec-wave:bug`), exit 1; `blocked` sem `fail` → inconclusivo: nada move, nenhum Bug, exit 1. Re-teste após o fix: `qa <story> --only <cenário>` (não duplica Bug — comenta no existente).
 
 ### `@spec-wave/cli task <start|done> <n>` — transições de Task no board (comando LOCAL)
 | Flag/Arg | Tipo | Descrição |
@@ -692,7 +734,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. **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.
+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. **Avise que os PRs estão empilhados** e que o merge é ordem-dependente: depois da revisão (PRs marcados prontos), o caminho é `npx @spec-wave/cli@latest merge <feature>` — nunca `gh pr merge --delete-branch` à mão em PR de pilha.
 
 ---
 
@@ -767,6 +809,33 @@ Para criar um Bug: `npx @spec-wave/cli@latest bug --title "..." [--parent <n>] [
 
 ---
 
+### `/spec-wave qa <número-da-issue>`
+
+A etapa **🧪 QA**: plano por Feature + execução local com veredito. Duas metades, nesta ordem obrigatória:
+
+**1. Gerar/criticar o plano (Feature):**
+```bash
+gh issue edit <feature> --add-label "spec-wave:qa"
+```
+- Arquivo ausente → gera `docs/features/<slug>/qa-plan.md` via IA (publicado em PR). Arquivo presente → valida + critica **COMO ESTÁ** (edições manuais preservadas). Regerar do zero = apagar o arquivo e reaplicar.
+- Requer `spec.md` + `plan.md` na base. Limpo → `spec-wave:qa-ready`; grave → `critique-failed`.
+- **Só em Feature** — numa Story o Action comenta apontando a Feature-pai; Bug usa o `Teste de Regressão` do `bug.md`.
+
+**2. Revisar o plano e executar (sempre local, SEMPRE `--dry-run` primeiro):**
+```bash
+npx @spec-wave/cli@latest qa <issue> --dry-run   # cenários-alvo + comando; zero escrita no GitHub
+npx @spec-wave/cli@latest qa <issue>             # executa e dá o veredito
+```
+- A revisão do plano é o **portão humano** (D-QA4): sem `qa-ready` na Feature o comando recusa — porque o verde avança a Etapa **sozinho** (D-QA3).
+- Regras de edição do plano: seções `## Cenário N — Story #X` (posição manda, não o número escrito), `**Critério:**`/`**Esperado:**` obrigatórios.
+- Desfechos: **verde** → `qa-approved`, Story → 📋 Homologação, Bug → 🚀 Deploy (D-QA6), Feature quando TODAS as Stories liberarem; Bug filho aberto **segura** a Story mesmo verde. **Vermelho** → 1 Bug por cenário reprovado (filho da Story, ✅ Ready, milestone herdado) com `bug.md` **determinístico commitado pelo comando e `bug-approved` aplicada** — exceção explícita à Regra fundamental: reprodução, esperado/obtido e regressão são a execução observada, e regenerar por IA só alucina; **não** aplique `spec-wave:bug` nesses Bugs. **Inconclusivo** (`blocked` sem `fail`) → nada move, nenhum Bug, exit 1.
+- Re-teste após o fix: `npx @spec-wave/cli@latest qa <story> --only <cenário>` — não duplica Bug (comenta no existente).
+- **PROIBIDO corrigir código durante a execução** — QA não conserta; alterar o código invalida o veredito.
+
+Sem `qa.command` no `.spec-wave.json` (nem `SPEC_WAVE_QA_CMD`), o comando monta o contexto em `.spec-wave/qa-<n>.md` e orienta — configure como no `specKit.command` do implement.
+
+---
+
 ### `/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.
@@ -884,6 +953,10 @@ docs/
       decomposition.md   ← rascunho gerado quando spec-wave:decompose é adicionado (3º).
                             REVISÁVEL e EDITÁVEL à mão; as issues só nascem com
                             spec-wave:decompose-apply
+      qa-plan.md         ← plano de QA gerado quando spec-wave:qa é adicionado (4º,
+                            com a Feature já em 🧪 QA). Um cenário por critério de
+                            aceite, seções "## Cenário N — Story #X"; executado
+                            localmente por `spec-wave qa <issue>`
   rfcs/
     <slug-do-rfc>/
       decomposition.md   ← mesmo papel, com "## Task N" (RFC não usa spec/plan)

package/src/templates/workflows/generate-qa-plan.yml

@@ -0,0 +1,64 @@
+name: Generate QA Plan
+
+on:
+  issues:
+    types: [labeled]
+
+# Mesmo desenho do decompose.yml: `labeled` dispara para QUALQUER label, então o
+# run que não vai fazer nada ganha um grupo único (`spec-wave-noop-<run_id>`) e
+# não disputa a fila — com `cancel-in-progress: false`, um run inútil na fila
+# cancelaria o que estava PENDENTE (ver o comentário longo no decompose.yml).
+#
+# O namespace `spec-wave-item-<issue>` é COMPARTILHADO com decompose.yml,
+# generate-spec/plan/bug e o job `move` do code-review.yml: este workflow também
+# publica documento em branch própria + Pull Request, e lê spec.md/plan.md que
+# uma geração concorrente estaria trocando.
+concurrency:
+  group: >-
+    ${{ github.event.label.name == 'spec-wave:qa'
+    && format('spec-wave-item-{0}', github.event.issue.number)
+    || format('spec-wave-noop-{0}', github.run_id) }}
+  cancel-in-progress: false
+
+jobs:
+  generate-qa-plan:
+    # `spec-wave:qa` numa Feature gera (ou re-critica) o qa-plan.md. O comando
+    # trata sozinho os outros tipos (Story → aponta a Feature-pai; Bug → usa o
+    # Teste de Regressão do bug.md), então o filtro de título fica amplo de
+    # propósito — o `if:` só corta o ruído de labels sem relação.
+    # Modo de execução: `spec-wave mode local` cria a variável de repositório
+    # SPEC_WAVE_EXECUTION=local e este job passa a ser PULADO.
+    if: >
+      vars.SPEC_WAVE_EXECUTION != 'local' &&
+      github.event.label.name == 'spec-wave:qa'
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      # O commit do qa-plan.md vai por Git Data API (contents: write) para uma
+      # branch própria (`spec-wave/<n>-qa-plan`), nunca a default; sem
+      # `pull-requests: write` o commit existe e o PR não.
+      contents: write
+      pull-requests: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+
+      - name: Instala a CLI
+        run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
+
+      - name: Generate QA plan
+        run: spec-wave generate-qa-plan --issue-number ${{ github.event.issue.number }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_PR_TOKEN: ${{ secrets.GH_PR_TOKEN }}
+          PROJECT_TOKEN: ${{ secrets.GH_PROJECT_TOKEN }}
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
+          GITHUB_REPOSITORY: ${{ github.repository }}

package/src/templates/workflows/qa.yml

@@ -1,8 +1,14 @@
 name: QA
 
+# Dois gatilhos, um destino: aprovação formal OU merge movem a Feature para
+# 🧪 QA. O de merge existe porque o autor não consegue aprovar o próprio PR —
+# num fluxo solo, QA por aprovação nunca aconteceria — e porque homologação de
+# verdade começa com o código integrado. Espelha o `run --pr` do modo local.
 on:
   pull_request_review:
     types: [submitted]
+  pull_request:
+    types: [closed]
 
 concurrency:
   group: spec-wave-qa-${{ github.event.pull_request.number }}
@@ -25,10 +31,12 @@ jobs:
     # Aqui a guarda é INDISPENSÁVEL, não defensiva: `pull_request_review`
     # dispara por uma aprovação HUMANA, independentemente de quem abriu o
     # PR. Aprovar o PR da spec moveria a Feature para 🧪 QA.
+    # A última linha aceita os dois eventos: review aprovada (pull_request_review)
+    # ou PR fechado COM merge (pull_request closed — fechado sem merge não conta).
     if: >
       vars.SPEC_WAVE_EXECUTION != 'local' &&
       !startsWith(github.event.pull_request.head.ref, 'spec-wave/') &&
-      github.event.review.state == 'approved'
+      (github.event.review.state == 'approved' || github.event.pull_request.merged == true)
     runs-on: ubuntu-latest
     permissions:
       issues: write