@spec-wave/cli 0.27.0 → 0.29.0

package/src/plugin/skills/preparar-specs/reference/armadilhas.md

@@ -0,0 +1,209 @@
+# Armadilhas operacionais deste fluxo
+
+Cada item aqui custou uma investigação real. A causa vem junto porque o sintoma, sozinho,
+costuma apontar para o lugar errado.
+
+## Índice
+
+1. Token do `gh` inválido no ambiente
+2. `gh issue edit --add-label` falha com 503
+3. A API do GitHub devolve 503 intermitente
+4. Working tree compartilhado com outros agentes
+5. Label de gatilho grudada impede o retry
+6. `spec-wave:spec` sobrescreve spec revisada
+7. `spec-wave update` reescreve os workflows
+8. Runs `skipped` são normais — não são falha
+9. `conclusion` vazia não é conclusão
+10. Geração leva minutos — não rode em primeiro plano
+11. Run interrompido deixa lock órfão
+12. O documento foi gerado e o PR não nasceu
+
+---
+
+## 1. Token do `gh` inválido no ambiente
+
+**Sintoma:** `gh` falha com erro de autenticação, ou enxerga o repositório errado.
+
+**Causa:** a variável `GH_TOKEN` do ambiente pode estar inválida ou pertencer a uma conta
+sem acesso à organização, enquanto o keyring tem a conta certa.
+
+**Como resolver:** exporte o token da conta correta antes dos comandos:
+
+```bash
+export GH_TOKEN=$(env -u GH_TOKEN gh auth token -u <conta-com-acesso>)
+```
+
+O `env -u GH_TOKEN` é necessário porque o `gh auth token` também consulta a variável
+inválida se ela estiver setada.
+
+A CLI tem a saída própria dela para o mesmo problema, que não depende do shell:
+`spec-wave --account <login> <comando>`, ou `"github": { "account": "<login>" }` no
+`.spec-wave.json`. Fora do CI, a conta declarada vence a variável de ambiente.
+
+## 2. `gh issue edit --add-label` falha com 503
+
+**Sintoma:** o comando falha repetidamente, e parece que o gatilho não existe.
+
+**Causa:** esse subcomando passa pelo GraphQL, que pode estar degradado enquanto o REST
+funciona normalmente.
+
+**Alternativa que funciona:**
+
+```bash
+gh api -X POST repos/<owner>/<repo>/issues/<n>/labels -f "labels[]=spec-wave:spec"
+```
+
+## 3. A API do GitHub devolve 503 intermitente
+
+**Sintoma:** comandos falham de forma aleatória e passam na tentativa seguinte.
+
+**Como lidar:** envolva as chamadas em retry (3–5 tentativas com pausa) e **verifique o
+resultado real**, não o código de saída isolado. Um `gh` que devolve string vazia sem erro
+é indistinguível de "não encontrei nada" se você não conferir.
+
+## 4. Working tree compartilhado com outros agentes
+
+**Sintoma:** arquivos modificados que você não criou; branch diferente da esperada.
+
+**Causa:** outros processos (dev-agents, outras sessões) usam o mesmo checkout e trocam de
+branch sem aviso.
+
+**Regra:** nunca `checkout`, `stash` ou `reset` sem antes conferir `git branch --show-current`
+e `git status --short`. A geração em si não disputa o checkout — ela publica por API, sem
+tocar em disco —, mas tudo que você fizer à mão disputa.
+
+Se precisar mesmo de uma branch checada — por exemplo, para editar arquivos de um PR já
+aberto — use um worktree temporário fora do repositório, e remova depois:
+
+```bash
+git worktree add /tmp/<dir> <branch>
+# ... edições, commit, push ...
+git worktree remove --force /tmp/<dir> && git worktree prune
+```
+
+## 5. Label de gatilho grudada impede o retry
+
+**Sintoma:** reaplicar a label não dispara nada; ou o `run` local recusa executar com
+`⛔ trigger-pending`.
+
+**Causa:** o evento `issues: [labeled]` não redispara com a label já presente, e o `run`
+recusa rodar com gatilho pendente — a label significa "Action em execução", ou uma que
+falhou e a deixou para trás.
+
+**Como resolver:** remover e reaplicar. No modo local, onde nenhuma Action está rodando, a
+label é resíduo: **remova-a em vez de usar `--force`**, para a issue não mentir sobre o
+estado.
+
+```bash
+gh api -X DELETE "repos/<owner>/<repo>/issues/<n>/labels/spec-wave:spec"
+```
+
+Nem sempre a label fica: em algumas falhas a CLI a remove sozinha no início do run.
+Confira issue a issue em vez de supor — o `preflight` já lista as pendentes.
+
+## 6. `spec-wave:spec` sobrescreve spec revisada
+
+A label **regenera** o documento do zero. Se a spec já foi revisada, editada à mão ou
+corrigida, reaplicar joga tudo fora para consertar o que muitas vezes é uma frase.
+
+Para correção pontual em documento já gerado, a edição direta é permitida **quando o
+usuário pede explicitamente** — e só nesse caso. Edite no PR: as edições são preservadas.
+
+## 7. `spec-wave update` reescreve os workflows
+
+O `update` compara os workflows com os templates da CLI e sobrescreve os divergentes. Toda
+customização local neles é perdida no bump, silenciosamente, e o sintoma só aparece na
+próxima geração.
+
+Se o repositório tem workflows customizados de propósito, rode `update --skip-repo`, ou
+reaplique a customização antes de commitar o bump. Confirme depois:
+
+```bash
+git show origin/main:.github/workflows/generate-spec.yml | grep <marca-da-customizacao>
+```
+
+## 8. Runs `skipped` são normais — não são falha
+
+O evento `issues: [labeled]` dispara **todos** os workflows que escutam labels; cada um se
+filtra pelo próprio `if:`. Ver `generate-plan` e `decompose` como `skipped` depois de
+aplicar `spec-wave:spec` é o comportamento correto, não um problema.
+
+O mesmo vale para o repositório em modo `local`: todo job carrega
+`if: vars.SPEC_WAVE_EXECUTION != 'local'`, então o run aparece verde e `skipped`, sem erro
+e sem documento. Se você aplicou uma label e nada aconteceu, confira o modo antes de
+procurar defeito: `npx @spec-wave/cli@latest mode`.
+
+Ao procurar o run que interessa, filtre pelo workflow **e** pelo título da issue.
+
+## 9. `conclusion` vazia não é conclusão
+
+O `gh run list` devolve `conclusion` como **string vazia** — não `null` — enquanto o run
+está em andamento. Um filtro `select(.conclusion != null)` deixa passar runs que ainda
+estão rodando, e você conclui cedo demais que tudo terminou.
+
+Filtre por `.status == "completed"` **e** `conclusion` não-vazia.
+
+## 10. Geração leva minutos — não rode em primeiro plano
+
+Uma spec é uma chamada de modelo gerando um documento longo: leva minutos. Rodar no
+primeiro plano de uma ferramenta com timeout curto faz o comando morrer no meio — e o custo
+já foi pago.
+
+Rode em background, ou com timeout generoso (10 min por Feature). Numa milestone grande em
+modo local isso passa de uma hora em série; combine com o usuário antes de começar.
+
+## 11. Run interrompido deixa lock órfão
+
+**Sintoma:** `Já existe um 'spec-wave run' para <n> (pid NNNN, desde ...)` e a geração é
+recusada, mesmo não havendo nada rodando.
+
+**Causa:** o `run` grava `.git/spec-wave/run-<n>.lock` para impedir duas execuções na mesma
+issue. Um run morto por timeout ou Ctrl-C não tem chance de limpar o próprio lock.
+
+**Como resolver — confirmando antes:** o lock guarda o pid, então dá para verificar se o
+processo realmente morreu em vez de apagar no escuro:
+
+```bash
+cat .git/spec-wave/run-<n>.lock          # {"pid":NNNN,"startedAt":"..."}
+ps -p NNNN >/dev/null && echo VIVO || echo morto
+rm .git/spec-wave/run-<n>.lock           # só se morto
+```
+
+O cuidado importa quando você rodou várias Features: pode haver um lock órfão e outro de um
+run **em andamento** ao lado. Apagar o lock errado põe dois `run` na mesma issue.
+
+A boa notícia é que a interrupção em si é limpa — o documento não é publicado pela metade.
+Confirme com a ausência de PR novo antes de rerodar.
+
+## 12. O documento foi gerado e o PR não nasceu
+
+**Sintoma:** o passo termina, o commit existe na branch `spec-wave/<n>-<doc>` — e nenhum PR
+aparece. O documento fica numa branch que ninguém está olhando, e a próxima execução, se
+ninguém perceber, **regera por cima**.
+
+**Causa:** a publicação precisa de `pull-requests: write` **e** de a organização permitir
+que Actions abram PRs. A segunda parte é a traiçoeira: *"Allow GitHub Actions to create and
+approve pull requests"* (Settings → Actions → General) vem desligada por padrão em muitas
+organizações, e o erro não se parece com falta de permissão.
+
+**Como resolver:** ligar a opção, ou definir um PAT no secret `GH_PR_TOKEN`. O `preflight`
+e o `doctor` verificam os dois; o estado `⚠ em branch sem PR` no inventário é exatamente
+este caso.
+
+Não se aplica ao modo `local`, onde o token é o seu.
+
+---
+
+## Nota histórica: o regime anterior à 0.27.0
+
+Até a 0.26.0 a geração publicava com `commit` + `pull --rebase` + `push` **na branch
+default**, a partir do checkout. Duas armadilhas vinham daí e **não valem mais**:
+
+- **push rejeitado com `GH013`** em repositório que exige PR — a falha vinha *depois* de o
+  modelo ter gerado o documento, e o conteúdo se perdia com o runner;
+- **working tree sujo quebrava toda geração local**, porque qualquer arquivo modificado
+  travava o `pull --rebase`.
+
+Hoje a publicação é por API, em branch própria por documento, sem tocar no checkout. Se o
+`preflight` apontar uma CLI antiga fixada nos workflows, as duas voltam a valer — e a
+saída é `npx @spec-wave/cli@latest update --branch`.

package/src/plugin/skills/preparar-specs/reference/revisao.md

@@ -0,0 +1,110 @@
+# Fase 3 — revisão de conteúdo
+
+O gerador escreve cada spec isoladamente, a partir do corpo de uma issue. Ele é bom nisso:
+as seções vêm completas, os requisitos rastreados, os fluxos coerentes **dentro** do
+documento. O que ele estruturalmente não consegue ver é a relação entre os documentos —
+porque, quando escreveu o primeiro, os outros não existiam.
+
+É exatamente aí que moram os problemas que custam caro depois. Por isso a regra desta fase:
+**leia as specs como conjunto, não uma a uma.**
+
+## Como ler
+
+Leia todas na íntegra antes de julgar qualquer uma. Ao ler a quinta, você reconhece na
+primeira uma contradição que era invisível quando ela era o único documento.
+
+Vale montar, enquanto lê, um mapa mental de três coisas:
+
+- **regras compartilhadas** — um teto, uma ordem de prioridade, uma janela de tempo que
+  aparece em mais de uma feature;
+- **quem depende de quem** — e em que direção cada spec declara a dependência;
+- **afirmações sobre o mundo** — "tal feature ainda não existe", "isso é feito por X".
+
+As três classes de problema abaixo saem desse mapa.
+
+## Classe 1 — contradição entre specs
+
+Duas features descrevem a mesma regra de formas que não fecham: contagens diferentes,
+prioridades diferentes, a mesma janela de tempo medida a partir de marcos diferentes.
+
+Isso é grave porque cada spec, sozinha, parece certa. O erro só existe no par — e vira dois
+comportamentos incompatíveis em produção, descobertos na integração.
+
+Ao encontrar, verifique qual das duas está alinhada com a fonte normativa (o corpo da issue,
+o documento de requisitos) antes de propor a correção. Frequentemente uma está certa e a
+outra derivou.
+
+## Classe 2 — dependência que não fecha
+
+Três formatos, todos vistos de verdade:
+
+**Aponta para algo que não existe.** A feature A declara que seu componente vive na feature
+B, e a spec de B não menciona esse componente em lugar nenhum. Alguém vai descobrir isso na
+implementação, quando já for caro.
+
+**Direção invertida ou circular.** A declara depender de B enquanto B declara depender de A.
+Uma spec bem gerada às vezes corrige isso sozinha e **documenta a correção** — quando vir
+uma nota dessas, confira se a outra ponta concorda.
+
+**Inversão de sequenciamento entre milestones.** A dependência bloqueante está numa
+milestone que vence *depois* da que depende dela. Não é erro de spec — é erro de
+planejamento que só aparece quando se olha as datas junto com as dependências. Levante
+sempre, porque ninguém mais vai olhar para os dois ao mesmo tempo.
+
+**Como verificar de forma barata:** `spec-wave audit --milestone <nome>` cruza as
+seções de Dependências de todas as specs e acusa ciclo, inversão de milestone,
+referência sem alvo e sobreposição com código (Fase 3.5 da skill). O que sobra
+para o olho é a parte semântica: a outra ponta concorda com a direção e o
+escopo do que foi declarado?
+
+## Classe 3 — afirmação que a própria rodada tornou falsa
+
+Esta é sutil e específica de gerar várias specs de uma vez: a spec gerada às 10h afirma
+"tal feature ainda não possui spec" e às 10h20 essa spec passa a existir — gerada pela
+mesma rodada.
+
+**Cuidado ao corrigir:** a mesma frase costuma aparecer várias vezes no documento, sobre
+alvos diferentes, e só algumas ficaram obsoletas. Verifique alvo por alvo antes de editar.
+Corrigir por padrão de texto transforma afirmação verdadeira em falsa.
+
+E note *como* corrigir: quando a afirmação obsoleta era a **justificativa** de um TODO, a
+pergunta não desaparece — ela muda de razão. Reescreva a justificativa apontando onde a
+questão vive agora, em vez de apagar a frase e deixar o TODO sem explicação.
+
+## Também procure
+
+- **Sobreposição com feature já entregue.** Se uma spec descreve algo que uma feature
+  fechada já faz, há risco de duplicar comportamento em produção. Confira o estado da issue
+  antiga — "fechada" muda a conversa de "coordenar" para "não quebrar o que existe".
+- **Regra que contradiz outra regra da mesma spec.** Raro, mas acontece quando uma regra é
+  categórica ("nunca expor dado individual") e outra define um recorte fino o bastante para
+  violá-la na prática. Vale destacar: costuma ser o achado de maior severidade.
+- **Parâmetro declarado como "definido previamente" que ninguém definiu.** Limiares, prazos,
+  número de tentativas. Individualmente parecem detalhe; juntos costumam ser uma decisão só,
+  sem dono.
+
+## Como classificar o que encontrou
+
+**Achado material** — muda o desenho de uma feature, ou tem risco em produção. Vai como
+comentário na issue correspondente, contendo: a regra que o originou (citada), por que não
+se resolve no `plan`, e a decisão necessária. Se o achado tem dois lados (duas features
+discordando), comente **nos dois**, apontando um para o outro — quem abrir só uma issue
+precisa enxergar o quadro inteiro.
+
+**Lacuna paramétrica** — falta um número. Não bloqueia o `plan`. Agrupe por tema no
+relatório final: doze lacunas espalhadas costumam ser seis decisões, e uma lista de doze
+itens soltos não é acionável.
+
+O teste para separar as duas: *se ninguém decidir isso, o que acontece?* Se a resposta é
+"implementam errado" ou "duas partes se comportam de formas incompatíveis", é material. Se
+é "implementam com um valor provisório e ajustam depois", é paramétrico.
+
+## O que não fazer
+
+Não reescreva a spec para consertar o que encontrou. A spec é registro do que foi gerado a
+partir da fonte normativa; a correção de regra é decisão do PO, e o lugar dela é a issue.
+Editar o documento direto faz a decisão parecer tomada — e ninguém consegue rastrear quem
+a tomou.
+
+A exceção é o erro factual puro (Classe 3), que não é decisão de ninguém — e, mesmo aí,
+só com pedido explícito do usuário.

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

@@ -16,6 +16,9 @@ Atualiza **somente o que divergiu** da versão da CLI: a **skill** instalada (po
 | `--skip-skill` | Não verifica/atualiza a skill instalada. |
 | `--skip-config` | Não verifica/atualiza o `.spec-wave.json`. |
 | `--skip-repo` | Não verifica/atualiza workflows e labels do repo. |
+| `--branch [nome]` | Envia os arquivos do repo como **Pull Request** numa branch, em um único commit (sem valor: `spec-wave/update-v<versão>`). |
+| `--config-in-pr` / `--no-config-in-pr` | Força incluir/excluir o `.spec-wave.json` do PR. |
+| `--skill-in-pr` / `--no-skill-in-pr` | Força incluir/excluir a skill dos agentes do PR. |
 | `--dry-run` | Mostra o que seria atualizado sem alterar nada. |
 | `--yes` | Aplica sem pedir confirmação. |
 
@@ -28,15 +31,18 @@ Atualiza **somente o que divergiu** da versão da CLI: a **skill** instalada (po
 
 2. Mostre ao usuário o resumo por categoria (skill / config / arquivos do repo / labels). Se **nada** divergiu, informe que já está tudo na versão atual e encerre.
 
-3. Com a aprovação, aplique:
+3. Com a aprovação, aplique — 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
    ```
    Limite o escopo com `--skip-skill`, `--skip-config` ou `--skip-repo` se o usuário só quiser parte.
 
 4. **Onde cada coisa aterrissa:**
-   - **arquivos do repo** (workflows, labels) → commitados no remoto pelo comando
-   - **`.spec-wave.json`** → arquivo **local**; lembre o usuário de commitá-lo
+   - **workflows e templates de issue** → no PR (com `--branch`) ou commitados direto na branch default
+   - **labels** → sempre direto na base: são metadado do repositório, não há como versioná-las
+   - **`.spec-wave.json` e a skill** → o comando **consulta a base** e vai pelo mesmo caminho do arquivo: se o repositório já versiona aquele caminho, a atualização entra no PR; se não versiona, fica só local e o usuário precisa commitá-la. Force com `--config-in-pr` / `--skill-in-pr` se o projeto quiser passar a versionar.
+   - a skill é gravada em disco nos dois casos — é a cópia que o agente carrega
 
 5. Se a skill foi atualizada, oriente a **recarregar/reiniciar o agente** para pegar a nova versão.
 

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

@@ -1,6 +1,6 @@
 ---
 name: spec-wave-workflow
-description: "Use quando a pergunta for sobre o fluxo spec-wave como um todo — qual é a próxima etapa de uma issue, o que cada coluna do Kanban significa, quais labels disparam quais Actions, como funciona a crítica adversarial, ou quando o usuário pedir spec-wave sem dizer qual comando. É o mapa do processo RFC-001; para executar uma ação específica, use a skill do comando correspondente (setup, issue, spec, plan, ready, decompose, implement, order, task, story, move, doctor, update, info, uninstall, rfc, fix-pr)."
+description: "Use quando a pergunta for sobre o fluxo spec-wave como um todo — qual é a próxima etapa de uma issue, o que cada coluna do Kanban significa, quais labels disparam quais Actions, como funciona a crítica adversarial, ou quando o usuário pedir spec-wave sem dizer qual comando. É o mapa do processo RFC-001; para executar uma ação específica, use a skill do comando correspondente (setup, issue, spec, plan, ready, decompose, run, bug, triage, implement, order, task, story, move, doctor, update, info, uninstall, rfc, fix-pr); para conduzir um trecho inteiro do fluxo de uma vez, preparar-feature (uma Feature até Ready) ou preparar-specs (as specs de uma milestone)."
 allowed-tools:
   - Bash(npx @spec-wave/cli@latest *)
   - Bash(gh issue *)
@@ -148,6 +148,11 @@ O slug vem do **título**: `[FEATURE] Cadastro de Pedidos com PIX` → `cadastro
 | gerar o plano técnico | `plan` |
 | validar spec+plan | `ready` |
 | quebrar em Stories/Tasks | `decompose` |
+| levar uma Feature da spec até ✅ Ready, de ponta a ponta | `preparar-feature` |
+| gerar as specs de uma milestone inteira | `preparar-specs` |
+| rodar o fluxo localmente / desarmar os workflows | `run` |
+| registrar ou corrigir um Bug | `bug` |
+| triar um Bug | `triage` |
 | implementar | `implement` |
 | ver ordem das Stories | `order` |
 | mover Task | `task` |

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|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.
@@ -208,6 +208,7 @@ Mesmas flags do `issue` (exceto `--type`, fixo em `feature`). Mantido para o flu
 | `--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). |
+| `--skill-in-pr` / `--no-skill-in-pr` | flag | Força incluir/excluir a **skill dos agentes** 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. |
 
@@ -215,7 +216,9 @@ Mesmas flags do `issue` (exceto `--type`, fixo em `feature`). Mantido para o flu
 
 > **`--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.
+> As **labels** nunca entram no PR: são metadado do repositório, não há como versioná-las — já valem na base, com ou sem o merge. O corpo do PR diz isso a quem revisa.
+>
+> A **skill** e o **`.spec-wave.json`** seguem a mesma regra, e ela é **verificada, não presumida**: o comando pergunta à base se aquele arquivo já é versionado. Se for (repos que commitam `.claude/skills/spec-wave/SKILL.md`, `.agents/skills/`, `AGENTS.md`, `.cursor/rules/…`), a atualização entra no PR junto com os workflows; se não for, fica só na máquina local. Passar a versionar (ou deixar de versionar) é decisão do projeto — use `--skill-in-pr` / `--no-skill-in-pr` para forçar.
 >
 > ⚠️ 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.
 
@@ -250,7 +253,33 @@ 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 task <start|done> <n>` — transições de Task no board (comando LOCAL)
 | Flag/Arg | Tipo | Descrição |
@@ -459,8 +488,8 @@ Traz tudo para a versão atual da CLI, atualizando **só o que mudou**: a skill
    - Escopos podem ser limitados com `--skip-skill`, `--skip-config`, `--skip-repo`.
    - **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.
+   - **Nos dois modos**, as **labels** são aplicadas direto na base (metadado do repositório, não versionável) e nunca entram no PR.
+   - **`.spec-wave.json` e skill:** com `--branch`, cada um entra no PR se o repositório **já o versiona** (o comando consulta a base, arquivo a arquivo); se não versiona, segue apenas local e o usuário precisa commitá-lo — ou use `--config-in-pr` / `--skill-in-pr` para passar a versioná-lo. Sem `--branch`, os dois são sempre só locais. A skill é gravada em disco de qualquer forma, para o agente já pegar a versão nova.
 4. Se a skill foi atualizada, oriente recarregar/reiniciar o agente para pegar a nova versão.
 
 ---
@@ -689,7 +718,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.
 
 ---
 

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