@spec-wave/cli 0.27.0 → 0.28.0

package/src/plugin/skills/preparar-feature/reference/critica.md

@@ -0,0 +1,88 @@
+# A crítica adversarial na prática
+
+O que este arquivo acrescenta ao fluxo: a crítica **não é um veredito**, é uma amostra. Tratá-la
+como veredito produz os dois erros caros — aceitar um documento defeituoso porque a passada veio
+limpa, e reescrever lógica correta porque um finding disse para reescrever.
+
+## A crítica é não-determinística
+
+Passadas sucessivas sobre o **mesmo arquivo** dão vereditos diferentes. Três passadas medidas sobre
+o mesmo `plan.md`, sem editar nada entre a primeira e a segunda além da correção que a primeira
+pediu:
+
+| Passada | Achados |
+|---|---|
+| 1 | 1 menor — um refetch disparado por posição quando o item já vinha no payload |
+| 2 | 2 menores — a correção da passada 1 tinha ficado **pela metade** (uma seção corrigida, outra não, o plano contradizendo a si mesmo) + uma regra descrita de duas formas |
+| 3 | 2 menores, ambos novos — do tipo "o plano não explica X", não mais contradição |
+
+Em outra Feature, duas passadas sobre o mesmo arquivo e o mesmo modelo deram
+`✅ Nenhuma contradição encontrada` e depois `1 GRAVE` — e o defeito já estava lá na primeira.
+
+**Leia "nenhuma contradição encontrada" como *um revisor não achou nada nesta passada*.**
+
+### Três consequências práticas
+
+1. **Reaplique a crítica depois de editar**, mesmo com veredito `limpa`. Foi a segunda passada que
+   pegou a correção incompleta, e custa um minuto.
+2. **Findings "menores" podem ser substantivos.** O primeiro do exemplo era um round-trip
+   desperdiçado no caso mais comum — não bloqueava o `ready`, mas era defeito real.
+3. **Saiba parar.** Quando os achados viram "o plano não explica X" em vez de "o plano se
+   contradiz", o retorno virou marginal. Corrija o que você mesmo introduziu e siga.
+
+## Antes de corrigir, confira o finding contra o arquivo
+
+A crítica produz os dois tipos de erro, e eles pedem respostas opostas.
+
+**Falso positivo.** O padrão já observado: o texto do finding termina em "não é contradição real" e
+a severidade sai `grave` mesmo assim. Aí o ajuste é tornar o documento **mais explícito no ponto
+citado**, não reescrever a lógica. Reescrever a lógica de um plano correto por causa de um finding
+mal calibrado é o pior desfecho disponível: custa a revisão e introduz o defeito que não existia.
+
+**Defeito real.** Também já observado: o plano dizia duas vezes "esta feature não cria tabela nem
+coluna (RN15)" e trazia um `CREATE TABLE` com uma coluna de texto livre, violando de quebra uma
+decisão registrada no `tech_context`. Nenhuma leitura superficial pegaria — as duas afirmações
+estavam a páginas de distância.
+
+**Cite o trecho do arquivo que confirma ou refuta o finding.** É o que distingue "corrigi o que a
+IA mandou" de "verifiquei e o problema existe", e é o que o usuário precisa para julgar a sua
+correção sem reler o documento inteiro.
+
+## Qual superfície corrigir
+
+O achado cita âncoras, e a âncora diz onde corrigir:
+
+| O achado cita | Corrija |
+|---|---|
+| seções do plano técnico | `plan.md` |
+| `Story N` / `Task N.M` | `decomposition.md` — são títulos daquele arquivo |
+
+Confundir as duas trava o ciclo: você corrige o documento errado, recritica, e o mesmo achado volta.
+
+**Mas verifique se o defeito nasce acima.** Um achado que aponta uma `Task` pode ter a causa no
+`plan.md`. Corrigir só o rascunho deixa os dois divergentes, e a próxima geração traz o defeito de
+volta. A regra: se o achado descreve uma **decisão técnica**, corrija nos dois; se descreve um
+**recorte de escopo**, o rascunho basta.
+
+## Recriticar sem regerar
+
+```bash
+npx @spec-wave/cli@latest run <n> --yes --step critique
+```
+
+**Nunca `--step plan` para isso.** Ele regera o documento do zero e descarta a correção — é o erro
+que faz o ciclo não convergir, porque cada rodada recomeça do mesmo lugar.
+
+Existe também `critique --file <caminho>`, que é **consulta**: não comenta na issue, não aplica
+label e não consome tentativa. Útil para conferir uma correção antes de gastar o portão.
+
+## Quando a crítica esgota
+
+Depois de N reprovas seguidas (3, por padrão) o fluxo aplica `spec-wave:needs-human` e para.
+
+Isso não é um erro a contornar — é o fluxo dizendo que a correção automática não está convergindo.
+Pare e envolva o usuário. A label sai à mão, e sair dela sem resolver a causa só adia o mesmo
+impasse para a próxima passada.
+
+O mesmo vale para `spec-wave:critique-failed`: o caminho de retomada é **corrigir o documento e
+recriticar**, nunca regerar.

package/src/plugin/skills/preparar-specs/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: spec-wave-preparar-specs
+description: "Use para gerar o spec.md de TODAS as Features de uma milestone de uma vez: confere o ambiente antes de gastar modelo, gera, valida a estrutura, revisa o conjunto procurando contradições ENTRE as specs, mergeia os PRs e move as issues para 📋 Spec. Gatilhos: 'gera as specs da v06', 'roda os specs da milestone X', 'quero todas as features da v05.2 especificadas', 'gera as specs que faltam', 'quais features estão sem spec?', 'preciso das specs prontas antes de gerar os planos'. NÃO use para uma Feature isolada — aí é a skill spec (um passo) ou preparar-feature (a Feature inteira, até Ready)."
+allowed-tools:
+  - Bash(npx @spec-wave/cli@latest *)
+  - Bash(gh issue *)
+  - Bash(gh pr *)
+  - Bash(gh run *)
+  - Bash(gh api *)
+  - Bash(git *)
+  - Read
+  - Glob
+  - Grep
+---
+
+# Specs de uma milestone inteira
+
+Levar todas as Features de uma milestone de "sem spec" até "spec revisada e mergeada na base, issue em 📋 Spec". São seis fases e a ordem importa: cada uma existe para que a seguinte não desperdice trabalho caro.
+
+O custo real aqui não é tempo — é que **cada geração paga um modelo**. Um erro de configuração descoberto na sétima Feature custa sete gerações. Por isso a Fase 0 existe, e por isso a Fase 1 para na primeira falha em vez de seguir em frente.
+
+**Contexto:** leia `.spec-wave.json` (Read). Ausente → skill **setup**.
+
+## Fase 0 — Preflight (nunca pule)
+
+```bash
+npx @spec-wave/cli@latest preflight --milestone <nome>
+```
+
+Um comando reporta: token utilizável, modo de execução (config × variável do repositório), se a publicação por Pull Request funciona, as Features da milestone com o estado do `spec.md` de cada uma, e labels de gatilho grudadas. Sai com código 1 se houver bloqueio. `--json` devolve o mesmo relatório para você ramificar.
+
+**Leia a coluna de estado de cada Feature antes de agir** — ela não é `existe`/`não existe`:
+
+| Estado | O que significa | O que fazer |
+|---|---|---|
+| `· gerar` | não existe em lugar nenhum | entra na rodada |
+| `✓ na base` / `✓ no disco` | já mergeada | não gerar |
+| `⏳ em PR aberto` | gerada, aguardando revisão/merge | **não gerar** — regerar descarta a revisão e paga o modelo de novo |
+| `⚠ em branch sem PR` | commit passou, PR não nasceu | abrir o PR; ver `reference/armadilhas.md` |
+| `? indeterminado` | a consulta falhou | confirmar antes, para não pagar duas vezes |
+
+Se qualquer bloqueio aparecer, **resolva antes de gerar**. As causas estão em `reference/armadilhas.md`; leia esse arquivo agora se for a primeira vez que você roda esta skill neste repositório.
+
+Confirme **duas** coisas com o usuário antes de começar — é a última chance barata de descobrir que a milestone errada foi escolhida, e a única de decidir onde a rodada roda:
+
+1. **a lista de Features** que serão geradas;
+2. **o modo de execução** — `actions` ou `local`. O preflight diz qual está configurado hoje; isso é o *default* da pergunta, não a resposta. Os custos dos dois são diferentes o bastante (Fase 1) para a escolha ser dele, não sua.
+
+## Fase 1 — Gerar
+
+**O modo de execução decide como acionar** — e ele é o que o usuário respondeu na Fase 0, não o que o preflight encontrou configurado:
+
+| Modo | Como acionar | O que custa |
+|---|---|---|
+| `actions` | aplicar a label `spec-wave:spec` | minutos de GitHub Actions; roda em paralelo e não prende a máquina |
+| `local` | `npx @spec-wave/cli@latest run <issue>`, com `--dry-run` antes | nenhum minuto de CI; alguns minutos por Feature, mas a máquina fica ocupada |
+
+**Se a resposta diferir do que está configurado, troque o modo antes de gerar** — não tente acionar "do outro jeito" por cima da configuração atual:
+
+```bash
+npx @spec-wave/cli@latest mode <actions|local>
+```
+
+Três consequências que impedem essa troca de ser um detalhe desta rodada — diga-as ao usuário **antes** de executar, porque duas delas sobrevivem à rodada:
+
+- **a escolha vale para todo mundo.** O `mode` escreve os dois lados do interruptor: o `.spec-wave.json` e a variável de repositório `SPEC_WAVE_EXECUTION`, que o `if:` de cada job avalia. Quem rodar o fluxo depois de você herda o modo que você deixou.
+- **a variável exige permissão de administração.** Sem ela o comando grava só o config e diz o que faltou — e os dois lados passam a divergir: você acha que desarmou os workflows, e eles continuam disparando.
+- **o `.spec-wave.json` fica modificado localmente.** Commite, senão quem clona o repositório (dev-agent, Actions) continua lendo o modo antigo.
+
+**No modo `local`, NÃO aplique label de gatilho.** O `run` não aplica nenhuma, e aplicá-la à mão põe a label e o `run` no mesmo passo da mesma Feature — o modelo é pago duas vezes.
+
+**Os dois modos fazem a mesma coisa:** geram o documento e o publicam **via API, em branch própria por Feature (`spec-wave/<issue>-spec`), abrindo um PR**. Nada é escrito no seu checkout — confirme com `git status` na primeira geração.
+
+Cada `run` termina dizendo em qual PR o documento saiu, e avisando que *o próximo passo do fluxo lê o documento da branch base* — ou seja, o merge é pré-requisito do `plan`, não um detalhe de arrumação.
+
+### Uma canária, depois em paralelo
+
+Nem tudo de uma vez, nem tudo em série:
+
+1. **Gere UMA sozinha e espere.** Ela custa uma geração e responde tudo que é sistêmico: credencial válida, permissão de publicar, modo correto, PR abrindo de fato. Um erro descoberto aqui custa 1 geração; descoberto na sétima, custa 7. **Se a canária falhar, não dispare mais nada.**
+2. **Passando a canária, o resto sai em até 4 trilhas simultâneas.**
+
+Paralelizar é seguro porque o lock da CLI é **por issue** (`.git/spec-wave/run-<n>.lock`) e a publicação é por API, em branch própria — issues diferentes nunca disputam nada.
+
+O teto de 4 não vem da CLI, vem do backend: no modo `local` quem gera é o agente desta máquina, e outras sessões podem estar usando o mesmo. Vale conferir com `pgrep -af "spec-wave run"` antes. Em `actions` nada disso se aplica: o paralelismo é do próprio GitHub.
+
+**Rode em background, nunca em primeiro plano.** Uma spec leva minutos; uma ferramenta com timeout curto mata o comando no meio — e o custo já foi pago.
+
+**Ao falhar, a pergunta é sempre a mesma:** *isto é específico desta Feature, ou vai acontecer com todas?* Leia o log (`gh run view <id> --log-failed | tail -40`) ou o erro da CLI antes de qualquer outra coisa. Onde a falha aconteceu já indica a resposta:
+
+- **Na canária** — trate como sistêmico até prova em contrário e **não dispare as trilhas**. Credencial, permissão, publicação e configuração falham assim.
+- **Numa trilha, com a canária tendo passado** — quase sempre pontual. As outras trilhas seguem; não as interrompa para investigar uma.
+
+**`error_max_turns` é o caso pontual mais comum** — o modelo gasta o teto de turnos explorando o repositório e não chega a escrever. A própria CLI classifica: se as chamadas de ferramenta são **distintas**, foi exploração (varia entre execuções) e **repetir no mesmo modelo costuma bastar**; se elas **se repetem**, é loop degenerado e repetir só paga a mesma perambulação de novo. Só nesse segundo caso entram trocar de modelo ou subir `maxTurns` — e essas são decisões do usuário, porque custam mais caro. O teto vive no frontmatter do prompt da CLI, não no `.spec-wave.json`.
+
+Diga ao usuário o que encontrou e o que recomenda, em vez de tentar contornar sozinho: várias saídas possíveis (mudar o modo, mexer em proteção de branch, trocar credencial) são decisões dele.
+
+## Fase 2 — Validar estrutura
+
+Barato e determinístico, então roda em todas antes da revisão cara.
+
+**Não use `spec-wave validate` aqui:** ele valida spec **e** plan juntos, e nesta altura o `plan.md` não existe — reprovaria toda Feature da milestone e ainda consumiria a label `spec-wave:ready`. A conferência desta fase é de leitura.
+
+O que olhar em cada spec:
+
+- as seções obrigatórias estão presentes e com o nome exato. O gerador escreve seis (`Visão Geral`, `Regras de Negócio`, `Fluxos`, `Critérios de Aceite`, `Dependências`, `Requisitos Não-Funcionais`) e o `validate` mais tarde vai exigir três delas **byte a byte** — `Visão Geral`, `Critérios de Aceite` e `Requisitos Não-Funcionais`. Título divergente ("encontrei X, esperava Y") se resolve renomeando, não regerando;
+- nenhum sinal de corte: bloco de código não fechado, parêntese aberto na última linha. Um documento truncado passa na conferência de seções e vale menos que documento nenhum;
+- conte os `[TODO: requer esclarecimento` de cada spec. O número não é defeito — é o mapa do que ficou em aberto, e vai para o relatório final.
+
+Se uma spec estiver estruturalmente quebrada, **não reaplique `spec-wave:spec` por reflexo**: essa label **sobrescreve** o arquivo. Se o documento já foi revisado ou editado, regenerar joga fora a revisão.
+
+## Fase 3 — Revisar conteúdo
+
+Aqui está a maior parte do valor, e é o que distingue esta skill de rodar sete comandos em sequência. Leia `reference/revisao.md` — ele traz o método e as classes de problema que aparecem de verdade, com exemplos reais.
+
+As specs ainda não estão na base neste ponto — cada uma vive na branch do seu PR. Leia direto de lá, sem checkout:
+
+```bash
+git fetch origin
+git show origin/spec-wave/<issue>-spec:docs/features/<slug>/spec.md
+```
+
+Em resumo: leia as specs **como conjunto**, não uma a uma. Problemas de spec isolada o gerador já evita bem; o que ele não consegue ver é a relação entre documentos — regra que duas features contam de formas diferentes, dependência circular, feature que aponta para um lugar que não existe, e afirmações que a própria rodada tornou falsas.
+
+Separe o que encontrar em duas classes, porque elas têm destinos diferentes:
+
+- **Achado material** — muda o desenho de alguma feature, ou tem risco em produção. Vai como comentário na issue, com a regra que o originou e a decisão necessária.
+- **Lacuna paramétrica** — falta um número, um prazo, um limiar. Não bloqueia; agrupe por tema no relatório final, porque doze delas costumam ser uma decisão só.
+
+## Fase 4 — Mergear os PRs
+
+A Fase 1 já abriu um PR por Feature; **não há nada a publicar**. O trabalho aqui é mergear os que a revisão aprovou.
+
+Isso reordena as fases de propósito: a revisão da Fase 3 acontece **antes** do merge, lendo o conteúdo direto das branches, e o merge passa a ser o registro de que a revisão terminou.
+
+Para cada PR: confira que o check obrigatório passou e mergeie. Um PR por Feature é bom para o histórico (cada spec rastreável à sua issue), então não tente consolidar num PR único — consolidar exigiria desfazer o que a ferramenta fez sozinha, sem ganho real.
+
+Achado material **não** bloqueia o merge. A spec registra o que foi gerado a partir da fonte normativa; o achado é decisão do PO e vive na issue. Segurar o merge só deixa a spec invisível para quem precisa dela — inclusive para o `plan`, que lê da branch base.
+
+Ao final, reconcilie o checkout com `git pull --rebase`.
+
+## Fase 5 — Mover o board
+
+Depois do merge, para cada Feature:
+
+```bash
+npx @spec-wave/cli@latest move <n> "📋 Spec"
+```
+
+Use o comando, não mutação manual no board — ele embute as regras do fluxo. E note que **a Etapa nunca retrocede**: uma vez movida, não volta por comando. Por isso este passo vem *depois* do merge, quando as specs de fato existem na base, e não antes.
+
+Confirme lendo o board de volta, não pela saída do comando.
+
+## Fase 6 — Relatório
+
+Entregue ao usuário, nesta ordem — do que exige decisão para o que é registro:
+
+1. **Achados materiais**, se houver, com link do comentário em cada issue. É o que ele precisa decidir antes de gerar planos.
+2. **Placar**: N/N specs na base, PRs mergeados, issues em 📋 Spec.
+3. **Tabela** por Feature: issue, nome, linhas, TODOs.
+4. **Lacunas paramétricas agrupadas por tema**, com a contagem.
+5. **O que ficou aberto** — dependências de features sem spec, inversões de sequenciamento entre milestones, dívida operacional.
+
+Um plano gerado sobre uma spec cuja regra vai mudar é retrabalho garantido. Se a Fase 3 produziu achados materiais, diga isso explicitamente ao recomendar o próximo passo.
+
+## Referências
+
+- `reference/armadilhas.md` — as armadilhas operacionais deste fluxo, cada uma com a causa e o sintoma. Leia antes da Fase 1 na primeira vez, e sempre que algo falhar de um jeito que não faz sentido.
+- `reference/revisao.md` — o método da Fase 3 e as classes de problema que aparecem de verdade, com exemplos reais.
+
+Depois desta skill, o passo natural de cada Feature é o plano técnico: skill **preparar-feature** (leva uma Feature de spec até ✅ Ready com Stories e Tasks) ou skill **plan** (só o `plan.md`).

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,107 @@
+# 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:** para cada dependência declarada, confira se o
+diretório/arquivo existe e se a outra ponta concorda com a direção e o escopo.
+
+## 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` |