@spec-wave/cli 0.30.0 → 0.33.0

package/src/templates/skill/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: spec-wave
 description: "Use when the user wants to set up a spec-driven GitHub workflow, create a Feature issue, generate spec.md or plan.md, decompose a Feature into Stories/Tasks, write RFC documentation, or audit and fix a Pull Request. Implements the RFC-001 workflow with GitHub Projects v2, labels, and AI-powered GitHub Actions."
-argument-hint: "[info|setup|update|doctor|preflight|audit|issue|feature|spec|plan|ready|decompose|order|implement|merge|qa|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|qa-lead|task|story|move|uninstall|rfc|bug|triage|fix-pr] [target]"
 user-invocable: true
 allowed-tools:
   - Bash(npx @spec-wave/cli@latest *)
@@ -22,6 +22,10 @@ allowed-tools:
   - Agent
 ---
 
+<!-- GERADO por scripts/generate-skill.mjs a partir de core.md + src/plugin/skills/*/SKILL.md.
+     NÃO edite este arquivo à mão: edite o core.md (visão de conjunto) ou a skill do
+     comando no plugin, e rode `npm run skill:gen`. -->
+
 # spec-wave Skill
 
 Este skill guia o usuário pelo fluxo spec-driven definido no RFC-001.
@@ -256,9 +260,14 @@ Sem flags. Roda um checklist de diagnóstico no repositório atual: token GitHub
 ### `@spec-wave/cli order <feature>` — ordem de execução das Stories (comando LOCAL)
 | Flag/Arg | Tipo | Descrição |
 |----------|------|-----------|
-| `<feature>` | string (obrigatório) | Número da issue da **Feature**, ex.: `12` ou `#12`. Argumento posicional. |
+| `<feature>` | string (opcional) | Número da issue da **Feature**, ex.: `12` ou `#12`. Omitido: o mapa de todas as Features com trabalho. |
+| `--milestone <ref>` | string | No mapa sem argumento: só as Features da milestone (número ou título). |
+| `--json` | boolean | Saída JSON **estável** (sem ANSI) — o formato para agentes/scripts consumirem a ordem. |
+| `--remote` | boolean | Une também o blocked_by da API (1 chamada por Story) — pega arestas criadas SÓ pela UI. |
+| `--refresh` | boolean | Ignora o cache local e reconsulta a API. |
+| `--sync` | boolean | Grava as dependências VIVAS (body + blocked_by) de volta no `decomposition.md` e regenera o `dependency-map.json`, com commit local escopado. |
 
-> **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.
+> **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, com a Etapa atual de cada uma no board. As **arestas** vêm de fontes LOCAIS — `dependency-map.json` (escrito pelo `decompose --apply`), `decomposition.md` aplicado e linha `Depende de: #N` do corpo — **zero chamada de API por Story**; `--remote` acrescenta o *blocked by* nativo. A **Etapa** vem de um snapshot único do board, cacheado por `cache.ttlSec` do `.spec-wave.json` (default 600s; env `SPEC_WAVE_CACHE_TTL`; `0` desliga), com a idade impressa quando servido do cache. 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 |
@@ -297,6 +306,19 @@ Sem flags. Roda um checklist de diagnóstico no repositório atual: token GitHub
 
 > **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 qa-lead <plan|run|report> <milestone>` — orquestra o QA de uma TRILHA (comando LOCAL)
+| Flag/Arg | Tipo | Descrição |
+|----------|------|-----------|
+| `<acao>` | string (obrigatório) | `plan` (prepara os planos e PARA no portão humano), `run` (executa o ciclo em containers paralelos) ou `report` (reimprime um ciclo já gravado). |
+| `<milestone>` | string (obrigatório) | Milestone da trilha, por **número ou título** — trilha = milestone (D-QAL1). |
+| `--watch` | boolean | No `plan`: acompanha os planos disparados até resolverem (teto `qa.lead.planWaitTimeoutMin`; estourar relata as pendentes e sai 1). |
+| `--only <features>` | string | No `run`: sub-trilha explícita, ex.: `--only 318,320` (decisão humana declarada, não relaxamento do portão). |
+| `--max-cycles <n>` | string | No `run`: teto de ciclos (default: `qa.lead.maxCycles`, 3). |
+| `--cycle <n>` | string | No `report`: qual ciclo imprimir (default: o último). |
+| `--dry-run` | boolean | Classifica/planeja e imprime — **nenhuma label, zero container, zero escrita**. |
+
+> Duas fases separadas (D-QAL2): o `plan` aplica `spec-wave:qa` nas Features sem plano e **para** — o humano revisa os `qa-plan.md`; o `run` só inicia com a trilha inteira em `qa-ready` (recusa listando as pendentes). O `run` faz preflight global, despacha até `qa.lead.maxParallel` containers (um ambiente isolado por Feature — `qa.lead.container.image` obrigatória), coleta os comentários de veredito e grava `docs/qa/<slug-milestone>/cycle-<n>/{report.md,report.json}` + um **bloco delimitado** na descrição do milestone (substituído a cada ciclo, preservando as Release Notes). Ciclo N+1 só se um Bug fechou ou um bloqueio caiu (D-QAL7); teto de 3 ciclos. O Lead **não** aplica label de estado, **não** move card e **não** abre issue — toda mutação de board é do `qa` dentro dos containers.
+
 ### `@spec-wave/cli task <start|done> <n>` — transições de Task no board (comando LOCAL)
 | Flag/Arg | Tipo | Descrição |
 |----------|------|-----------|
@@ -472,186 +494,351 @@ O `validate` também recusa documento com sinal objetivo de corte (bloco de cód
 
 ## Sub-comandos
 
-### `/spec-wave info`
+### `/spec-wave info` — status de configuração
+
+> **Quando usar:** Use quando o usuário perguntar se o repositório atual já está configurado com spec-wave, qual GitHub Project está vinculado, qual versão da CLI foi usada no init, ou se a skill instalada está atualizada. Gatilhos: 'o spec-wave está configurado aqui?', 'qual o board deste repo?', 'status do spec-wave'. Para um diagnóstico completo de auth e workflows use a skill doctor.
+
+Mostra se o repositório atual foi configurado e valida a skill instalada.
+
+| Flag | Descrição |
+|------|-----------|
+| `--json` | Saída JSON (`{"initialized":bool, ..., "skill":{...}}`) para parsing programático. |
+
+#### Passos
+
+1. Execute:
+   ```bash
+   npx @spec-wave/cli@latest info
+   ```
+
+2. **Se inicializado**, apresente ao usuário os dados do `.spec-wave.json`: `owner/repo`, `project.title` + `project.url`, `version` da CLI e `initializedAt`.
+
+3. **Se NÃO inicializado**, pergunte: "Este repositório ainda não foi configurado com o spec-wave. Quer rodar o `init` agora?"
+   - Sim → use a skill **setup**.
+   - Não → encerre sem alterar nada.
 
-Mostra se o repositório atual já foi configurado com o spec-wave.
+4. **Se a saída indicar skill pendente** (aviso "Skill pendente de instalação/atualização" ou, no `--json`, `skill.installNeeded: true`), ofereça resolver:
+   - skill `ausente` → `npx @spec-wave/cli@latest install-skill`
+   - skill `desatualizada` → `npx @spec-wave/cli@latest update` (skill **update**)
 
-**Passos:**
-1. Execute: `npx @spec-wave/cli@latest info`
-2. **Se o repositório estiver inicializado**, o comando mostra os dados do `.spec-wave.json` (owner/repo, project, versão da CLI, data). Apresente essas informações ao usuário.
-3. **Se NÃO estiver inicializado**, pergunte ao usuário: "Este repositório ainda não foi configurado com o spec-wave. Quer rodar o `init` agora?"
-   - Se sim → siga o fluxo de `/spec-wave setup`.
-   - Se não → encerre sem alterar nada.
-4. **Se a saída indicar skill pendente** (aviso "Skill pendente de instalação/atualização" ou, no `--json`, `skill.installNeeded: true`), pergunte ao usuário se quer instalar/atualizar agora: skill `ausente` → `npx @spec-wave/cli@latest install-skill`; skill `desatualizada` → `npx @spec-wave/cli@latest update` (atualiza tudo que ficou para trás). Lembre-o de recarregar o agente depois.
+   Lembre de recarregar o agente depois.
+
+5. Se a `version` do arquivo divergir de `npx @spec-wave/cli@latest --version`, sugira `npx @spec-wave/cli@latest refresh --config` (reescreve o `.spec-wave.json` com os dados atuais do Project) ou a skill **update**.
+
+#### O que o comando valida além do arquivo
+
+Para cada agente de código detectado no diretório, compara a cópia instalada da skill com a versão empacotada na CLI — uma cópia **global** atualizada também conta. No `--json`, o campo `skill` traz `{agentsDetected, installNeeded, pending:[{agent, reason, path}]}`.
 
 ---
 
-### `/spec-wave update`
+### `/spec-wave setup` — configura o repositório
+
+> **Quando usar:** Use quando o usuário quiser configurar o spec-wave num repositório GitHub pela primeira vez — criar o GitHub Project (Projects v2), as labels de gatilho, os workflows de Action, os issue templates e o .spec-wave.json. Gatilhos: 'configurar spec-wave', 'inicializar spec-wave', 'rodar o init', 'setup do board'. Não use para atualizar uma instalação existente (skill update) nem para diagnosticar (skill doctor).
+
+Você dirige o `init` **com flags**. Nunca rode `npx @spec-wave/cli@latest init` sem `--repo`: sem ele a CLI abre um wizard interativo (`@clack/prompts`) que você **não consegue dirigir**.
+
+#### Flags do `init`
+
+| Flag | Tipo | Descrição |
+|------|------|-----------|
+| `--repo <owner/repo>` | string | Repositório alvo. **Passe SEMPRE.** |
+| `--project-title <title>` | string | Nome do Project. Default: `<repo> — Spec Wave`. |
+| `--provider <provider>` | string | `anthropic` ou `openrouter`. |
+| `--model <model>` | string | Modelo dos workflows (ex.: `anthropic/claude-3.7-sonnet`). |
+| `--skip-project` | flag | Pula a criação do Project (re-rodar quando já existe). |
+| `--skip-labels` | flag | Pula as labels. |
+| `--skip-files` | flag | Pula workflows + issue templates. |
+| `--dry-run` | flag | Simula sem alterar nada. |
 
-Traz tudo para a versão atual da CLI, atualizando **só o que mudou**: a skill instalada, o `.spec-wave.json` local e os workflows/labels do repo.
+#### Passos
 
-**Passos:**
-1. **Sempre comece com `--dry-run`** para inspecionar o que está desatualizado sem alterar nada:
+1. **Já configurado?** Leia `.spec-wave.json` (Read) ou rode `npx @spec-wave/cli@latest info`. Se existir, mostre `project.url` e `version` e **confirme com o usuário** antes de reconfigurar.
+
+2. **Descubra o repositório alvo:**
    ```bash
-   npx @spec-wave/cli@latest update --dry-run
+   gh repo view --json nameWithOwner -q .nameWithOwner
+   ```
+   Confirme com o usuário. Sem remote, pergunte o `owner/repo`.
+
+3. **Título do Project:** ofereça o default `<repo> — Spec Wave` e aceite-o se não houver preferência.
+
+4. **Cheque o auth:** `gh auth status`. Faltando os escopos `project,repo,workflow`, oriente o usuário a rodar **ele mesmo** (comando interativo — sugira o prefixo `!`):
    ```
-2. Mostre ao usuário o resumo (skill / config / arquivos do repo / labels que divergiram). Se **nada** estiver desatualizado, informe que já está tudo na versão atual e encerre.
-3. **Pergunte como os arquivos do repo devem sair** — e prefira o Pull Request:
+   !gh auth refresh --scopes project,repo,workflow
+   ```
+
+5. **(Opcional) Pré-visualize:**
    ```bash
-   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
+   npx @spec-wave/cli@latest init --repo <owner/repo> --dry-run
    ```
-   - 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 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.
+
+6. **Execute:**
+   ```bash
+   npx @spec-wave/cli@latest init --repo <owner/repo> --project-title "<título>"
+   ```
+   Use `--skip-project` / `--skip-labels` / `--skip-files` **apenas** para re-rodar uma fase que falhou antes.
+
+7. O `init` cria o Project, as labels, os workflows, um **scaffold de `.github/config/tech_context.yml`** (só se ainda não existir) e grava o `.spec-wave.json`. Oriente o usuário a fazer `git pull` para trazer os arquivos ao checkout local.
+
+8. **Adapte o `tech_context.yml`** — o scaffold vem com dados de exemplo e a qualidade do `plan.md` depende dele. Ofereça ajustá-lo agora; o passo a passo está na seção **Tech Context** deste documento.
+
+9. **Secret de IA:** instrua a adicionar em Settings → Secrets → Actions a credencial do provider escolhido: `ANTHROPIC_API_KEY` (Anthropic), `CLAUDE_CODE_OAUTH_TOKEN` (assinatura Claude Pro/Max — gere com `claude setup-token`) ou `OPENROUTER_API_KEY` (OpenRouter).
+
+10. **Próximo passo:** criar a primeira Feature — skill **issue**.
+
+#### Depois
+
+Rode a skill **doctor** para confirmar auth, escopos, config de IA e workflows antes de começar a trabalhar.
 
 ---
 
-### `/spec-wave setup`
+### `/spec-wave update` — traz tudo para a versão atual
+
+> **Quando usar:** Use depois de atualizar a CLI @spec-wave/cli, ou quando a skill instalada, o .spec-wave.json e os workflows/labels do repositório ficaram para trás da versão atual. Detecta e atualiza SÓ o que divergiu. Gatilhos: 'atualizar spec-wave', 'a skill está desatualizada', 'os workflows estão velhos', 'update do spec-wave'. Para configurar do zero use a skill setup; para remover, uninstall.
+
+Atualiza **somente o que divergiu** da versão da CLI: a **skill** instalada (por agente), o **`.spec-wave.json`** local e os **workflows/labels** do repositório.
 
-Configura o spec-wave no repositório. Você dirige o `init` com flags — **nunca rode `npx @spec-wave/cli@latest init` sem `--repo`** (abre o wizard interativo que você não controla).
+| Flag | Descrição |
+|------|-----------|
+| `--global` | Verifica a skill no escopo do usuário (padrão: projeto). |
+| `--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. |
 
-**Passos:**
-1. **Já configurado?** Leia `.spec-wave.json` (ou rode `npx @spec-wave/cli@latest info`). Se existir, avise (mostre `project.url` e `version`) e confirme com o usuário antes de reconfigurar.
-2. **Descubra o repositório alvo** (parâmetro `--repo`): rode `gh repo view --json nameWithOwner -q .nameWithOwner` para obter `owner/repo` do repo atual. Confirme com o usuário; se não houver remote, pergunte o `owner/repo`.
-3. **Pergunte o título do Project** (parâmetro `--project-title`). Ofereça o default `<repo> — Spec Wave` e aceite-o se o usuário não tiver preferência.
-4. **Cheque o auth:** `gh auth status`. Se faltarem os escopos `project,repo,workflow`, oriente o usuário a rodar ele mesmo `gh auth refresh --scopes project,repo,workflow` (comando interativo — o usuário executa, não você).
-5. **(Opcional) Pré-visualize** antes de aplicar: `npx @spec-wave/cli@latest init --repo <owner/repo> --dry-run`.
-6. **Execute com os parâmetros coletados:**
+#### Passos
+
+1. **Sempre comece com `--dry-run`:**
    ```bash
-   npx @spec-wave/cli@latest init --repo <owner/repo> --project-title "<título>"
+   npx @spec-wave/cli@latest update --dry-run
+   ```
+
+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 — e **prefira o Pull Request**:
+   ```bash
+   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
    ```
-   Use `--skip-project` / `--skip-labels` / `--skip-files` **apenas** para re-rodar uma fase específica que falhou antes.
-7. O `init` cria o Project, as labels, os workflows, um **scaffold de `.github/config/tech_context.yml`** (só se ainda não existir) e grava `.spec-wave.json`. Oriente o usuário a fazer `git pull` para trazer os arquivos ao checkout local.
-8. **Adapte o `tech_context.yml`**: o scaffold vem com dados de exemplo. Ofereça ajustá-lo à stack real do repo seguindo a seção **Tech Context** (perto do comando `/spec-wave plan`) — isso melhora muito a qualidade do `plan.md`.
-9. Instrua o usuário a adicionar a credencial de IA como secret no repositório (Settings → Secrets → Actions): `ANTHROPIC_API_KEY` (Anthropic), `CLAUDE_CODE_OAUTH_TOKEN` (assinatura Claude Pro/Max — gere com `claude setup-token`) ou `OPENROUTER_API_KEY` (OpenRouter), conforme o provider escolhido no `init`.
+   Limite o escopo com `--skip-skill`, `--skip-config` ou `--skip-repo` se o usuário só quiser parte.
+
+4. **Onde cada coisa aterrissa:**
+   - **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.
+
+#### Por que isso é necessário
+
+A skill instalada é uma **cópia estática** — ela não acompanha o `npx @spec-wave/cli@latest` sozinha. Se o banner de versão no topo do arquivo instalado for menor que `npx @spec-wave/cli@latest --version` (ou estiver ausente), está desatualizada.
+
+Para atualizar **só a skill**, sem tocar em config e repo:
+
+```bash
+npx @spec-wave/cli@latest install-skill --force
+```
+
+---
+
+### `/spec-wave doctor` — preflight de auth e configuração
+
+> **Quando usar:** Use como PRIMEIRO passo de troubleshooting do spec-wave: erro 404 ao criar issues, comando falhando sem motivo claro, board com colunas estranhas, Action que não roda, dúvida sobre token/escopos ou sobre qual modelo de IA está configurado. Também no início de uma sessão de trabalho. Gatilhos: 'spec-wave está com erro', 'não consigo criar issue', 'diagnosticar spec-wave', 'rodar o doctor'. Prefira esta skill a depurar gh api na mão.
+
+Comando **local**, sem flags:
+
+```bash
+npx @spec-wave/cli@latest doctor
+```
+
+#### O que ele checa
+
+- **Token GitHub** e a fonte dele; **escopos** (`repo`, `project`, `workflow`), com degradação para checks funcionais em fine-grained PATs
+- **Conta ativa do `gh`** vs. o owner do repositório
+- **`.spec-wave.json`**: campos presentes e sincronia com o Project real
+- **Acesso ao repositório**
+- **Configuração de IA**: provider, modelo, `ai.models`, escalada da crítica, apelidos de modelo, teto de saída e os secrets do Actions
+- **Higiene do board e das labels**: colunas fora do fluxo canônico, labels `spec-wave:*` descontinuadas ou ausentes
+- **spec-kit**: `specKit.command` / env `SPEC_WAVE_IMPLEMENT_CMD` — se ausente, sugere exemplos por agente (Claude Code, opencode, Codex, Copilot CLI, Kiro CLI, Qwen Code)
+- **Workflows**: presença + **versão da CLI fixada** (não `@latest`)
+
+#### Como ler a saída
+
+| Símbolo | Significado |
+|---------|-------------|
+| `✓` | ok |
+| `✗` | problema confirmado |
+| `!` | não verificável (best-effort — falha de rede nunca derruba o doctor) |
+
+**Exit 1** se houver algum `✗`.
+
+#### Passos
+
+1. Rode o comando.
+2. Para cada `✗`, explique a causa ao usuário e proponha a correção concreta:
+   - escopo faltando → o usuário roda `!gh auth refresh --scopes project,repo,workflow` (interativo, ele executa)
+   - `.spec-wave.json` dessincronizado → `npx @spec-wave/cli@latest refresh --config`
+   - workflows/labels divergentes → skill **update**
+   - secret de IA ausente → Settings → Secrets → Actions (`ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN` ou `OPENROUTER_API_KEY`, conforme o provider)
+   - modo de execução divergente (config diz `local` e a variável `SPEC_WAVE_EXECUTION` não está setada, ou vice-versa) → `npx @spec-wave/cli@latest mode local|actions` — veja a skill **run**
+   - `specKit.command` ausente → configure antes de usar a skill **implement**
+3. Trate `!` como "não deu para verificar", não como falha.
+4. Se tudo passar e o problema original persistir, aí sim investigue a superfície específica (Action, issue, board).
+
+> **404 ao criar issues** é o caso clássico: quase sempre token sem acesso ao repo/org — e o doctor aponta exatamente isso.
 
 ---
 
-### `/spec-wave issue <tipo> <descrição>` · `/spec-wave initiative <descrição>` · `/spec-wave feature <descrição>`
+### `/spec-wave issue` — cria um work item no board
+
+> **Quando usar:** Use para criar um work item tipado no spec-wave — Initiative, Epic, Feature, Bug, Spike ou RFC — já adicionado ao GitHub Project com Etapa, Work Item Type e Area. Gatilhos: 'criar uma feature', 'nova initiative', 'abrir um epic', 'registrar um bug no board', 'criar issue do spec-wave'. NÃO use para Story ou Task (nascem do decompose — skill decompose) e nunca use gh issue create.
+
+Faz tudo de uma vez: cria a issue com a label de tipo, vincula ao parent como **sub-issue** nativa do GitHub, adiciona ao Project e define os campos **Etapa**, **Work Item Type**, **Area** e — só se informada — **Priority**. Grava `Parent: #N` no corpo.
+
+> **Nunca use `gh issue create`.** Ele não adiciona ao board nem vincula o parent: a issue fica sem Etapa e some de todas as telas da UI.
+
+**Contexto:** leia `.spec-wave.json` (Read) para confirmar que o repo está configurado. Ausente → skill **setup**.
+
+#### Flags
+
+| Flag | Tipo | Descrição |
+|------|------|-----------|
+| `--title <title>` | **obrigatório** | Título **sem** o prefixo de tipo — a CLI adiciona (`[FEATURE]`, `[STORY]`…). |
+| `--type <type>` | string | `initiative`, `epic`, `feature`, `story`, `task`, `bug`, `spike`, `rfc`. Default: `feature`. |
+| `--parent <n>` | string | Número da issue pai — cria como sub-issue dela. |
+| `--body <text>` | string | Descrição. |
+| `--priority <p>` | string | **Opcional.** `P0`–`P3`. **Omita** se o usuário não pediu. |
+| `--area <area>` | string | `Frontend`, `Backend`, `Mobile`, `Infra`, `DevOps`, `Data`. |
+
+Atalhos: `initiative` (raiz, sem `--parent`) e `feature` — mesmas flags, `--type` fixo.
+
+#### Hierarquia
 
-Crie um work item tipado (Initiative/Epic/Feature/Story/Task/...) já adicionado ao board, opcionalmente como sub-issue de um parent. A Etapa inicial é **📥 Backlog** — correta para Initiative, Epic, Feature, RFC, Bug e Spike. **Story e Task não devem ser criadas por aqui** (nascem do `decompose`, em ✅ Ready — veja a *Regra fundamental*).
+`Initiative → Epic → Feature → Story → Task`. Use `--parent <n>` para pendurar no nível acima.
 
-**Hierarquia típica:** Initiative → Epic → Feature → Story → Task. A **Initiative** é o nó raiz e agrupa Epics. Use `--parent <n>` para criar como sub-issue do nível acima (ex.: um Epic filho de uma Initiative, ou uma Story filha de uma Feature). O GitHub mostra o parent na issue filha e vice-versa; a CLI ainda grava `Parent: #N` no corpo.
+#### Passos
 
-> **Spike é movido manualmente:** o spec-wave **nunca** avança a Etapa de um Spike automaticamente (nem no `implement`, nem nas Actions de Code Review/QA). O Spike entra no board em 📥 Backlog e o **usuário** o move à mão pelas etapas. Não mova a Etapa de um Spike por conta própria — a não ser que o usuário peça explicitamente.
+1. **Colete com o usuário:** tipo, título (sem prefixo), descrição e o número da issue **pai**, se houver.
 
-**Passos:**
-1. Pergunte ao usuário: tipo (initiative/epic/feature/story/task/...), título (sem prefixo), descrição e se há uma issue **pai** (número). **Prioridade e área são opcionais**: só as inclua se o usuário pedir explicitamente. **Nunca atribua uma prioridade por conta própria** — se o usuário não informou, **omita `--priority`** e a prioridade fica `null` (sem prioridade) no board.
-2. Execute o comando com os parâmetros coletados (inclua **apenas** as flags que o usuário forneceu):
+   > **Prioridade e área são opcionais.** Só inclua se o usuário pedir explicitamente. **Nunca atribua uma prioridade por conta própria** — omitindo `--priority`, a prioridade fica `null` (sem prioridade) no board.
+
+2. **Execute** com **apenas** as flags que o usuário forneceu:
    ```bash
    npx @spec-wave/cli@latest issue \
      --type "<tipo>" \
      --title "<título>" \
      --body "<descrição>" \
-     --area "<área>" \            # opcional — omita se o usuário não informou
-     --priority "<prioridade>" \  # opcional — só se o usuário pediu; caso contrário OMITA (prioridade fica null)
+     --area "<área>" \            # opcional
+     --priority "<prioridade>" \  # opcional — se o usuário não pediu, OMITA
      --parent "<número-do-pai>"   # opcional
    ```
-   Para Features, pode usar o atalho `npx @spec-wave/cli@latest feature --title ...` (equivale a `--type feature`).
-   A CLI cria a issue (label de tipo — e de prioridade **apenas se `--priority` for informado**), vincula como sub-issue do parent, adiciona ao Project e define Etapa = 📥 Backlog + Work Item Type + Area (+ Priority só se informada). **Não use `gh issue create`** (não adiciona ao board nem vincula o parent).
-   **Se o tipo for `story` ou `task`**, avise o usuário que o caminho normal é o `decompose` e, se ele confirmar mesmo assim, avance a Etapa para ✅ Ready depois de criar — senão o item fica invisível na UI.
-3. Informe o número criado e o vínculo com o pai (se houver).
-4. Para Features: "Quando quiser iniciar, mova para **📋 Spec** e use `/spec-wave spec <número>` para gerar a especificação funcional (o plano técnico vem depois)".
+   Para Features, o atalho `npx @spec-wave/cli@latest feature --title ...` equivale a `--type feature`.
 
----
+3. Informe o número criado e o vínculo com o pai.
+
+4. Para Features, aponte o próximo passo: mover para **📋 Spec** e usar a skill **spec** para gerar a especificação funcional (o plano técnico vem depois).
+
+#### Cuidados por tipo
 
-### `/spec-wave uninstall`
+⚠️ **A Etapa inicial é sempre 📥 Backlog, para qualquer `--type`.** Correto para Initiative, Epic, Feature, RFC, Bug e Spike.
 
-Remove a configuração do spec-wave do repositório (labels, arquivos `.github`, `.spec-wave.json`). **Não apaga o GitHub Project.**
+**Story e Task:** está errado para elas — pertencem a ✅ Ready. O caminho normal é a skill **decompose**. Se o usuário insistir numa Story/Task avulsa: crie **com `--parent <n>`** e, logo em seguida, avance para ✅ Ready (skill **move**), explicando por que o passo extra é necessário — senão o item fica invisível na UI.
 
-**Passos:**
-1. Confirme com o usuário que ele quer remover (a ação remove labels e faz commits removendo os workflows).
-2. Mostre antes o que será removido com `npx @spec-wave/cli@latest uninstall --dry-run`.
-3. Execute `npx @spec-wave/cli@latest uninstall` (a CLI pede confirmação; use `--yes` só se o usuário já confirmou).
-4. Lembre o usuário de excluir o **GitHub Project** manualmente, se desejar — a CLI não o apaga de propósito.
+**Spike:** entra em 📥 Backlog e o **usuário** o move à mão pelas etapas. Nunca avance a Etapa de um Spike por conta própria.
 
 ---
 
-### `/spec-wave spec <número-da-issue>`
+### `/spec-wave spec` — especificação funcional (1º documento)
 
-Inicia a geração da **especificação funcional** para uma Feature. É o **primeiro** passo do ciclo de documentos (antes do plano técnico).
+> **Quando usar:** Use para iniciar a geração da especificação funcional (spec.md) de uma Feature do spec-wave — o PRIMEIRO documento do ciclo, antes do plano técnico. Aplica a label spec-wave:spec e deixa o GitHub Action gerar o arquivo e abrir um Pull Request. Gatilhos: 'gerar a spec da feature 12', 'criar especificação funcional', 'rodar o spec-wave:spec'. Só vale para Features — Spike, RFC e Bug não usam spec.
 
-> **Apenas Features.** spec/plan **não** são gerados para **Spike, RFC ou Bug** — se a label for adicionada a um desses, o Action pula a geração, remove a label e comenta. Não use `/spec-wave spec|plan` nesses tipos.
+> **Regra fundamental: nunca escreva o `spec.md` à mão.** Quem gera é o spec-wave — pelo Action ou pela CLI local. É isso que garante que o arquivo chegue à main por Pull Request e seja referenciado na issue. Exceção: revisar/melhorar um `spec.md` já gerado (aí sim use Edit).
 
-**Passos:**
-1. Confirme que a issue é uma **Feature** (spec/plan não se aplicam a Spike/RFC/Bug).
-2. Adicione a label de gatilho:
+#### Dois modos, mesmo resultado
+
+| Modo | Como acionar | Quando |
+|------|--------------|--------|
+| **Action** | aplicar a label `spec-wave:spec` | fluxo assíncrono; roda no CI, você acompanha pela issue |
+| **Local** | `npx @spec-wave/cli@latest generate-spec --issue-number <n>` | você quer o documento **agora**, nesta sessão, e iterar em cima dele |
+
+O modo é detectado pelo ambiente — fora do Actions, a CLI roda em modo local automaticamente. Os dois geram o arquivo, abrem um **Pull Request** com ele, comentam na issue e removem a label de gatilho. **Pergunte ao usuário qual ele quer** se não estiver claro; na dúvida numa sessão interativa, prefira o local (o resultado aparece em segundos, em vez de exigir acompanhar o Action).
+
+> Local exige a credencial de IA no seu ambiente (`OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY` ou o login do Claude Code, se o provider for `claude-oauth`) e um `.spec-wave.json` no repositório. Para conduzir o fluxo inteiro sem gastar minutos de Actions, veja a skill **run**.
+
+**Contexto:** leia `.spec-wave.json` (Read). Ausente → skill **setup**.
+
+#### Passos
+
+1. **Confirme que a issue é uma Feature.**
+
+   > **Apenas Features.** Para **Spike, RFC e Bug** o Action **pula** a geração, remove a label e comenta. Não use esta skill nesses tipos.
+
+2. **Escolha o modo** (veja a tabela acima) e acione:
+
+   **Local** — resultado nesta sessão:
+   ```bash
+   npx @spec-wave/cli@latest generate-spec --issue-number <número>
+   ```
+   O comando imprime `Modo de execução: local`, gera e abre o Pull Request. Nada é gravado no seu clone — o documento vive no PR até o merge.
+
+   **Action** — assíncrono:
    ```bash
    gh issue edit <número> --add-label "spec-wave:spec"
    ```
-3. Informe: "Label `spec-wave:spec` adicionada. O GitHub Action `generate-spec.yml` irá gerar o `spec.md` automaticamente."
-4. Após a conclusão, ofereça revisar o spec.md gerado em `docs/features/<slug>/spec.md`.
-5. Próximo passo: gerar o plano técnico — mova para **📋 Plan** e use `/spec-wave plan <número>`.
+   Informe: "Label `spec-wave:spec` adicionada. O Action `generate-spec.yml` vai gerar o `spec.md`. Acompanhe em Actions → Generate Spec."
+
+4. Quando concluir, ofereça revisar o arquivo em `docs/features/<slug>/spec.md`. O slug vem do título: `[FEATURE] Cadastro de Pedidos com PIX` → `cadastro-de-pedidos-com-pix`.
+
+5. **Próximo passo:** o plano técnico — mova para **📋 Plan** e use a skill **plan**.
+
+#### Se falhar
+
+- **Comentário 🔎 de crítica com `spec-wave:critique-failed`** → corrija o `spec.md` (ou o corpo da issue que o embasa), commite, remova a label e reaplique o gatilho.
+- **Erro de teto de tokens** → a geração **falha e nada é gravado** (um documento cortado no meio valeria menos que documento nenhum). Aumente `ai.maxTokens` no `.spec-wave.json` ou reduza o corpo da issue; depois re-aplique a label.
+- Para reprocessar num modelo mais forte só nesta issue, aplique também `spec-wave:model:<apelido>` (o apelido precisa existir em `ai.modelAliases`).
 
 ---
 
-### `/spec-wave plan <número-da-issue>`
+### `/spec-wave plan` — plano técnico (2º documento)
 
-Inicia a geração do **plano técnico** para uma Feature, derivado da especificação. É o **segundo** passo (a spec deve existir antes).
+> **Quando usar:** Use para iniciar a geração do plano técnico (plan.md) de uma Feature do spec-wave — o SEGUNDO documento, derivado da spec.md. Aplica a label spec-wave:plan e deixa o GitHub Action gerar. Também cobre a criação e manutenção do .github/config/tech_context.yml, de que a qualidade do plano depende. Gatilhos: 'gerar o plano técnico', 'criar o plan.md da feature 12', 'configurar o tech_context'. Só vale para Features.
 
-O plano técnico segue o schema do RFC-002 §3.2: **Estratégia Técnica** (com Matriz de Rastreabilidade), **Detalhamento da Implementação**, **Segurança e Conformidade**, **Estratégia de Testes** e **Rollback e Monitoramento**. O agente usa o `tech_context` do repositório (`.github/config/tech_context.yml` + versões de pacote e migrations recentes) para embasar o plano e usar APENAS as tecnologias declaradas. Para desvios pontuais, adicione uma seção `## Tech Override` no corpo da issue (RFC-002 §4.3).
+> **Regra fundamental: nunca escreva o `plan.md` à mão.** Quem gera é o spec-wave — pelo Action ou pela CLI local. Exceção: revisar/melhorar um plano já gerado.
 
-**Passos:**
-1. Verifique se `spec.md` já existe em `docs/features/<slug>/` (o plano usa a especificação funcional como contexto). Se não existir, gere a spec primeiro com `/spec-wave spec <número>`.
-2. **Garanta o `tech_context`** (a qualidade do plano depende disso). Verifique se `.github/config/tech_context.yml` existe no repo (use Read). **Se não existir, ajude a criar AGORA** seguindo a seção **Tech Context** abaixo (logo após este comando) — e garanta que esteja **commitado e pushado** antes de adicionar a label (o Action lê o arquivo do repositório, não do seu disco local).
-3. Adicione a label de gatilho:
-   ```bash
-   gh issue edit <número> --add-label "spec-wave:plan"
-   ```
-4. Informe: "Label `spec-wave:plan` adicionada. O GitHub Action `generate-plan.yml` irá gerar o `plan.md` automaticamente. Acompanhe em: Actions → Generate Plan."
-5. Após a conclusão (cheque comentários na issue ou aguarde confirmação do usuário), ofereça revisar o plan.md gerado em `docs/features/<slug>/plan.md`.
-6. Próximo passo: validar a Feature — mova para **✅ Ready** e use `/spec-wave ready <número>`.
+**Dois modos, mesmo resultado.** `npx @spec-wave/cli@latest generate-plan --issue-number <n>` roda **agora**, nesta sessão; a label `spec-wave:plan` roda no Action. O modo é detectado pelo ambiente. Ambos geram, abrem um **Pull Request**, criticam e comentam na issue. Local exige a chave de IA no seu ambiente. Veja a skill **spec** para a tabela completa.
 
----
+**Contexto:** leia `.spec-wave.json` (Read). Ausente → skill **setup**.
 
-### Tech Context (`.github/config/tech_context.yml`)
+O plano segue o schema do **RFC-002 §3.2**: **Estratégia Técnica** (com Matriz de Rastreabilidade), **Detalhamento da Implementação**, **Segurança e Conformidade**, **Estratégia de Testes** e **Rollback e Monitoramento**. O agente usa o `tech_context` do repositório (`.github/config/tech_context.yml` + versões de pacote e migrations recentes) para embasar o plano e usar **APENAS** as tecnologias declaradas.
 
-Fonte de verdade estática da stack do sistema (RFC-002 §4). O `generate-plan` lê este arquivo para embasar o plano técnico e usar **APENAS** as tecnologias/serviços nele declarados — sem ele, o plano fica genérico e pode inventar APIs inexistentes. O `npx @spec-wave/cli@latest init` gera um **scaffold de exemplo** que **deve ser adaptado** à stack real. Use este fluxo quando o arquivo estiver ausente ou desatualizado.
+#### Passos
 
-**Como ajudar a criar (quando não existir):**
+1. **A spec existe?** Verifique `docs/features/<slug>/spec.md` — o plano usa a especificação funcional como contexto. Se não existir, gere a spec primeiro (skill **spec**).
 
-1. **Confirme a ausência:** tente `Read .github/config/tech_context.yml`. Se já existir, apenas confirme com o usuário se reflete a stack atual e pule para o fim.
-2. **Detecte a stack** lendo os arquivos do repositório (use Read; não invente):
-   - `package.json` → backend/frontend e libs (ex.: `@nestjs/core`, `next`, `react`, `@prisma/client`, `express`).
-   - `pom.xml` / `build.gradle` (Java), `requirements.txt` / `pyproject.toml` (Python), `go.mod` (Go).
-   - `prisma/schema.prisma` ou pasta `migrations/` → tabelas e colunas para `database_schemas`.
-   - `Dockerfile` / `docker-compose.yml` / charts Helm → `infra`.
-   - Procure papéis/roles (enum de RBAC) no código para `security.rbac_roles`.
-3. **Rascunhe** o YAML seguindo EXATAMENTE este schema (preencha só o que conseguir confirmar; deixe `# TODO` no que faltar — não invente):
-   ```yaml
-   system_info:
-     name: "<nome do sistema>"
-     stack:
-       backend: "<ex.: Node.js (NestJS v11)>"
-       frontend: "<ex.: Next.js 16 (React 19)>"
-       database: "<ex.: PostgreSQL (Prisma 5)>"
-       infra: "<ex.: Docker / Kubernetes>"
-     architecture: "<ex.: Monorepo Nx / Microservices>"
-   security:
-     auth_protocol: "<ex.: JWT>"
-     rbac_roles: ["ADMIN", "..."]
-   database_schemas:
-     - table: "<tabela>"
-       columns: "<col1, col2, ...>"
-   existing_services:
-     - name: "<serviço>"
-       endpoint: "<caminho>"
-       auth: "<ex.: JWT, mTLS>"
-   internal_libraries:
-     - "<lib interna>"
-   ```
-4. **Mostre o rascunho ao usuário e peça confirmação/ajustes** antes de gravar (ele conhece serviços internos e roles que o código pode não revelar).
-5. **Grave** com Write em `.github/config/tech_context.yml`.
-6. **Oriente a commitar e pushar** antes de seguir (o Action lê do repo). Sugira ao usuário rodar, via prefixo `!`:
+2. **Garanta o `tech_context`.** Verifique se `.github/config/tech_context.yml` existe (Read). **Se não existir, ajude a criar AGORA** — o passo a passo está na seção **Tech Context** deste documento. Garanta que esteja **commitado e pushado** antes de aplicar a label: o Action lê o arquivo do repositório, não do seu disco local.
+
+3. **Acione**, no modo escolhido:
    ```bash
-   !git add .github/config/tech_context.yml && git commit -m "chore: tech_context.yml [spec-wave]" && git push
+   # local — resultado nesta sessão
+   npx @spec-wave/cli@latest generate-plan --issue-number <número>
+   # ou Action — assíncrono
+   gh issue edit <número> --add-label "spec-wave:plan"
    ```
 
-**Desvios pontuais:** para uma Feature específica usar algo fora do padrão (ex.: "usar DynamoDB só aqui"), oriente a adicionar uma seção `## Tech Override` no corpo da issue, com um bloco YAML que será mesclado (deep-merge) sobre o `tech_context.yml`:
+4. Informe: "Label `spec-wave:plan` adicionada. O Action `generate-plan.yml` vai gerar o `plan.md`. Acompanhe em Actions → Generate Plan."
+
+5. Quando concluir, ofereça revisar `docs/features/<slug>/plan.md`.
+
+6. **Próximo passo:** validar a Feature — mova para **✅ Ready** e use a skill **ready**.
+
+#### Desvios pontuais (`## Tech Override`)
+
+Para uma Feature específica usar algo fora do padrão, oriente a adicionar no **corpo da issue** uma seção com um bloco YAML que será mesclado (deep-merge) sobre o `tech_context.yml`:
 
 ````markdown
 ## Tech Override
@@ -662,283 +849,742 @@ system_info:
 ```
 ````
 
+#### Se falhar
+
+Depois do `generate-plan` roda a **crítica adversarial**, que vira um comentário 🔎 na issue. Se ela apontar findings **graves**, a issue recebe `spec-wave:critique-failed` — corrija o **`plan.md`** (ou a `spec.md` que o embasa), commite, remova a label e reaplique `spec-wave:ready`. Detalhes na skill **workflow**.
+
+#### Criticar sem regerar
+
+Corrigir o documento à mão **não é desvio** — é o que o fluxo pede quando a crítica reprova. Para rodar a crítica de novo sobre o texto corrigido, **nunca** reaplique `spec-wave:plan`: ele regenera o `plan.md` do zero e descarta a correção.
+
+| Situação | Comando |
+|----------|---------|
+| Quero a crítica oficial de novo, na issue | label `spec-wave:critique` (ou `critique --issue-number <n>`) |
+| Quero só saber como está, enquanto edito | `npx @spec-wave/cli@latest critique --file docs/features/<slug>/plan.md` |
+
+O `--file` **não** comenta na issue, **não** aplica label e **não** consome tentativa da crítica — é consulta, não portão. Aceita `spec.md`, `plan.md`, `decomposition.md` e `bug.md` (o tipo sai do nome do arquivo; use `--kind` para forçar). Com `--fail-on-grave` ele sai com código 1, para usar em script.
+
+Um finding **grave** só bloqueia se vier com citação literal do trecho e não se auto-refutar; os que não passam nesse teste aparecem como **↘️ Rebaixados** no comentário, com o motivo — visíveis, mas sem travar o fluxo.
+
 ---
 
-### `/spec-wave ready <número-da-issue>`
+### `/spec-wave ready` — valida spec + plan
+
+> **Quando usar:** Use para validar que spec.md e plan.md de uma Feature do spec-wave estão completos e ela pode avançar para ✅ Ready. Aplica a label spec-wave:ready, que dispara o Action validate.yml. Gatilhos: 'validar a feature 12', 'a spec e o plano estão prontos?', 'mover para Ready'. Também explica os portões humanos critique-failed e needs-human, que bloqueiam a validação.
+
+Verifica se `spec.md` e `plan.md` contêm todas as seções obrigatórias e se não há sinal de truncamento.
 
-Valida que spec.md e plan.md estão completos e a Feature pode avançar.
+**Contexto:** leia `.spec-wave.json` (Read). Ausente → skill **setup**.
 
-**Passos:**
-1. Adicione a label de validação:
+#### Passos
+
+1. **Cheque os portões humanos ANTES de aplicar a label.** Se a issue tiver `spec-wave:critique-failed` ou `spec-wave:needs-human`, a validação **falha de imediato** — veja *Portões humanos* abaixo e resolva primeiro.
+
+2. Adicione a label:
    ```bash
    gh issue edit <número> --add-label "spec-wave:ready"
    ```
-2. Informe: "Validação iniciada. O workflow verificará se spec.md e plan.md contêm todas as seções obrigatórias."
-3. Se a validação falhar, o workflow comentará os problemas na issue e **não aplicará label de gatilho nenhuma**. Informe o usuário para corrigir e reaplicar `spec-wave:ready`. Falha por título de seção vem com "encontrei X, esperava Y" — renomear resolve. `spec-wave:spec` só se o documento precisar ser REGERADO: ela **sobrescreve** o `spec.md` revisado.
-4. **Se a issue tiver `spec-wave:critique-failed` ou `spec-wave:needs-human`**, a validação falha de imediato — são portões humanos: a crítica apontou contradições graves (comentário 🔎 na issue) ou esgotou as tentativas. Nesses casos a Feature **não** é devolvida para a etapa de spec; siga o fluxo da seção *Crítica adversarial* (corrigir a superfície certa → remover a label → re-aplicar `spec-wave:ready`).
-5. Se passar, oriente: "Feature validada! Mova o card para **✅ Ready** e use `/spec-wave decompose <número>` para gerar o **rascunho** das Stories (nada é criado ainda)."
+
+3. Informe: "Validação iniciada. O workflow verifica se `spec.md` e `plan.md` contêm todas as seções obrigatórias."
+
+4. **Se a validação falhar por conteúdo**, o workflow comenta os problemas na issue e **não aplica nenhuma label de gatilho**. Oriente o usuário a corrigir e reaplicar `spec-wave:ready`. Quando o problema é só o título de uma seção, o comentário já diz qual título encontrou e qual esperava — renomear resolve. Só sugira `spec-wave:spec` se o documento precisar mesmo ser REGERADO: essa label **sobrescreve** o `spec.md`, inclusive o que foi revisado à mão.
+
+5. **Se passar:** "Feature validada! Mova o card para **✅ Ready** e use a skill **decompose** para gerar o **rascunho** das Stories — nada é criado ainda."
+
+#### Portões humanos
+
+Estas labels **bloqueiam** a validação e **não** devolvem a Feature para a etapa de spec:
+
+| Label | O que aconteceu | Como sair |
+|-------|-----------------|-----------|
+| `spec-wave:critique-failed` | A crítica adversarial apontou contradições **graves** (comentário 🔎 na issue) | Corrija a superfície certa, commite, remova a label, reaplique `spec-wave:ready` |
+| `spec-wave:needs-human` | A crítica reprovou N vezes seguidas (default 3) e o fluxo parou | Uma pessoa revisa e remove **as duas** labels à mão |
+
+> **Qual superfície corrigir?** Se a crítica reprovou depois do `generate-plan`, corrija o **`plan.md`** (ou a `spec.md` que o embasa). Se reprovou no `decompose`, corrija o **`decomposition.md`** — os achados citam `Story N` / `Task N.M`, que são títulos daquele arquivo. Detalhes na skill **workflow**.
+
+#### Rede de segurança contra truncamento
+
+O `validate` também recusa documento com sinal objetivo de corte — bloco de código não fechado, parêntese aberto na última linha. Vale para documento editado à mão ou gerado por versão antiga da CLI.
 
 ---
 
-### `/spec-wave decompose <número-da-issue>`
+### `/spec-wave decompose` — decomposição em duas etapas
+
+> **Quando usar:** Use para quebrar uma Feature em Stories+Tasks, ou um RFC em Tasks, no spec-wave. São DUAS etapas com um rascunho revisável no meio: spec-wave:decompose gera/critica o decomposition.md sem criar nada, e spec-wave:decompose-apply cria as issues a partir do rascunho aprovado. Gatilhos: 'decompor a feature 12', 'gerar as stories', 'quebrar em tasks', 'aplicar a decomposição', 'o decompose falhou na crítica'. Também cobre re-decompose e o guard de idempotência.
+
+Aplica-se a **dois tipos**:
+
+- **Feature** → **Stories** (cada uma com suas **Tasks**), a partir de `spec.md` + `plan.md`
+- **RFC** → **Tasks diretamente** (sem Stories), a partir da descrição
+
+Para qualquer outro tipo (Spike, Bug, Story, Task…) o Action **recusa** e comenta.
+
+**Contexto:** leia `.spec-wave.json` (Read). Ausente → skill **setup**.
+
+#### O modelo mental
+
+```
+spec-wave:decompose
+  ├─ decomposition.md ausente  → gera via IA → abre Pull Request → critica
+  └─ decomposition.md presente → critica o arquivo COMO ESTÁ (preserva suas edições)
+       ├─ grave  → +critique-failed, comentário citando Story N / Task N.M, exit 1
+       └─ limpo  → +decompose-ready, comentário "revise e aplique"
+
+spec-wave:decompose-apply
+  └─ lê decomposition.md → cria Stories/Tasks → board → +decomposed
+     (sem nova crítica: aplicar a label É a aprovação humana)
+```
 
-Decompõe em **duas etapas**, com um rascunho revisável no meio (veja *Decomposição em duas etapas*). Aplica-se a **dois tipos**:
-- **Feature** → **Stories** (cada uma com suas **Tasks**), a partir de `spec.md` + `plan.md`.
-- **RFC** → **Tasks diretamente** (sem Stories), a partir da descrição do RFC.
+#### Passos
 
-Para qualquer outro tipo (Spike, Bug, Story, Task, …) o Action **recusa** e comenta.
+1. **Pré-requisito.** Feature: confirme que está em **✅ Ready** (spec e plan validados — skill **ready**). RFC: basta a descrição estar completa.
 
-**Passos:**
-1. Para **Feature**: confirme que está em **✅ Ready** (spec.md e plan.md validados). Para **RFC**: basta a descrição estar completa (RFC não usa spec/plan).
-2. **Etapa 1 — gerar o rascunho:**
+2. **Etapa 1 — gerar o rascunho**, no modo que preferir (mesmo resultado; o modo é detectado pelo ambiente):
    ```bash
+   # local — resultado nesta sessão
+   npx @spec-wave/cli@latest decompose --issue-number <número>
+   # ou Action — assíncrono
    gh issue edit <número> --add-label "spec-wave:decompose"
    ```
    Informe: "Rascunho iniciado — vai abrir um Pull Request com o `decomposition.md` e passar pela crítica. **Nenhuma issue é criada nesta etapa.**"
-3. Quando o Action terminar, leia o comentário na issue:
-   - **`spec-wave:decompose-ready`** → o rascunho passou pela crítica. **Leia o `decomposition.md`** e mostre ao usuário o que será criado (Stories, Tasks, dependências). Ofereça editar o arquivo antes de aplicar.
-   - **`spec-wave:critique-failed`** → o Action **falhou (exit 1)** e nada foi criado. Os achados citam `Story N` / `Task N.M` do `decomposition.md`. **Corrija esse arquivo** (não o `plan.md`) no Pull Request e reaplique `spec-wave:decompose` — o arquivo é criticado como está, sem ser regerado.
-   - **`spec-wave:needs-human`** → a crítica esgotou as tentativas. Pare e envolva o usuário: as duas labels precisam sair à mão.
-4. **Etapa 2 — aplicar o rascunho aprovado** (só depois da revisão):
+
+3. **Leia o resultado** quando o Action terminar:
+
+   | Label resultante | O que fazer |
+   |------------------|-------------|
+   | `spec-wave:decompose-ready` | Passou na crítica. **Leia o `decomposition.md`** e mostre ao usuário o que será criado (Stories, Tasks, dependências). Ofereça editar antes de aplicar. |
+   | `spec-wave:critique-failed` | O Action **falhou (exit 1)** e nada foi criado. Os achados citam `Story N` / `Task N.M`. **Corrija o `decomposition.md`** — não o `plan.md` — **no Pull Request** e reaplique `spec-wave:decompose` (o arquivo é criticado como está, sem ser regerado, venha ele do PR ou da base). |
+   | `spec-wave:needs-human` | A crítica esgotou as tentativas. **Pare** e envolva o usuário: as duas labels precisam sair à mão. |
+
+4. **Etapa 2 — aplicar o rascunho aprovado**, só depois da revisão:
    ```bash
+   # local
+   npx @spec-wave/cli@latest decompose --issue-number <número> --apply
+   # ou Action
    gh issue edit <número> --add-label "spec-wave:decompose-apply"
    ```
    Aplicar essa label **é** a aprovação humana — não há nova crítica.
-5. Após a aplicação, as issues filhas aparecem como comentário na issue pai. A issue pai e as Stories/Tasks criadas entram no board na Etapa **✅ Ready** (Status Todo; a Etapa nunca retrocede — itens já adiante não são tocados). As Stories trazem a linha `Depende de: #N` (+ relação *blocked by*) — use `npx @spec-wave/cli@latest order <número>` para ver a ordem de execução. Se a issue pai tiver **milestone**, as filhas nascem nele; sem milestone no pai, nascem sem.
-6. A issue recebe a label `spec-wave:decomposed` (guard de idempotência): rodar de novo **não** duplica as issues. Para forçar um re-decompose, siga a seção *Guard de idempotência*.
 
-> **Nunca pule a etapa 1** aplicando `spec-wave:decompose-apply` direto: sem `decomposition.md` o Action falha pedindo o rascunho.
+5. Após a aplicação, as issues filhas aparecem como comentário na issue pai. Pai e filhas entram no board em **✅ Ready** (Status Todo; a Etapa nunca retrocede — itens já adiante não são tocados). As Stories trazem `Depende de: #N` — use a skill **order** para ver a ordem de execução. Se a issue pai tiver **milestone**, as filhas nascem nele (a entrega da Story pertence à release da Feature); sem milestone no pai, nascem sem.
+
+6. A issue recebe `spec-wave:decomposed` (guard de idempotência): rodar de novo **não** duplica as issues.
+
+> **Nunca pule a etapa 1** aplicando `spec-wave:decompose-apply` direto — sem `decomposition.md` o Action falha pedindo o rascunho.
+
+#### O arquivo `decomposition.md`
+
+Fica em `docs/features/<slug>/decomposition.md` (Feature) ou `docs/rfcs/<slug>/decomposition.md` (RFC):
+
+```markdown
+# Decomposição — [FEATURE] Cadastro de Pedidos
+<!-- spec-wave:decomposition v1 issue=360 kind=stories -->
+
+## Story 1 — visualizar meus pedidos
+
+**User story:** Como cliente, quero visualizar meus pedidos, para acompanhar entregas
+**Depende de:** —
+
+Descrição complementar (contexto, critérios de aceite).
+
+### Task 1.1 — criar endpoint GET /pedidos
+
+Corpo técnico.
+```
+
+**Ao editar à mão:**
+
+- a **posição** manda, não o número escrito — inserir uma Story no meio sem renumerar funciona
+- `**Depende de:**` aceita **irmãs** (`Story 1, Story 3`, 1-based, só para trás — apontar para si mesma ou para frente é **erro**, não filtro silencioso) e **issues de outras Features** (`#412`, que precisam JÁ existir); as duas formas convivem na mesma linha (`Story 1, #412`), e `—` significa nenhuma
+- o corpo aceita markdown livre (`## Backend`, cercas de código) — só `## Story N` e `### Task N.M` são estrutura
+- **para gerar outro rascunho do zero:** feche o Pull Request e apague a branch `spec-wave/<n>-decompose` (ou apague o arquivo, se já foi mergeado) e reaplique `spec-wave:decompose`
+
+> ⚠️ O slug vem do **título**. Renomear a Feature entre o rascunho e o apply muda o diretório e órfã o `decomposition.md` — o apply reclama que não achou o rascunho.
+
+#### Guard de idempotência (`spec-wave:decomposed`)
+
+O evento `labeled` pode redisparar (re-add da label, retry de runner). Para não duplicar issues, o `decompose` **pula** quando a issue já tem `spec-wave:decomposed` **ou** já tem sub-issues do tipo-alvo (`[STORY]` para Feature, `[TASK]` para RFC). A label é gravada ao **aplicar**. Os workflows ainda usam `concurrency` por issue.
+
+A `spec-wave:decompose-ready` **não** entra nesse guard — é estado de rascunho pendente, não de decomposição feita.
+
+**Para forçar um re-decompose:**
+
+```bash
+gh issue edit <n> --remove-label "spec-wave:decomposed"
+```
+Depois **apague/feche as sub-issues antigas** (senão a detecção por sub-issues pula de novo), apague o `decomposition.md` se quiser um rascunho novo, e re-adicione `spec-wave:decompose`.
+
+#### Dependências entre Stories
+
+O `decompose` grava `Depende de: #N, #M` no corpo das Stories e cria a relação nativa *blocked by* — para irmãs e para as issues de outras Features referenciadas com `#N` no rascunho (a issue precisa existir: o apply reprova o rascunho ANTES de criar qualquer coisa se não conseguir lê-la). Isso alimenta as skills **order** e **implement**. **Não apague essa linha** ao editar o corpo de uma Story; para mudar dependências, edite a linha (e/ou a relação *blocked by*).
 
 ---
 
-### `/spec-wave implement <número-da-issue>`
+### `/spec-wave implement` — etapa 🚧 Desenvolvimento
+
+> **Quando usar:** Use para implementar trabalho do spec-wave na etapa 🚧 Desenvolvimento — uma Feature inteira (todas as Stories pendentes, em ordem de dependência), uma Story (todas as suas Tasks) ou uma Task isolada. Monta o contexto e aciona o spec-kit; se não houver spec-kit configurado, você mesmo implementa seguindo o contexto. Gatilhos: 'implementar a feature 12', 'começar a story 34', 'fazer a task 56', 'rodar o implement'. Comando LOCAL — não usa label nem Action.
+
+Comando **local** (lê o `.spec-wave.json`, como o `issue`), **não** disparado por label/Action.
+
+| Flag/Arg | Descrição |
+|----------|-----------|
+| `<issue>` | **Obrigatório**, posicional. Número da Feature, Story ou Task (`12` ou `#12`). |
+| `--feature-dir <path>` | Caminho `docs/features/<slug>` para anexar `spec.md`/`plan.md` (sobrescreve a resolução automática). |
+| `--dry-run` | Monta o contexto e imprime o comando **sem executar** e **sem escrever nada no GitHub**. |
+
+**Pré-requisitos:** `.spec-wave.json` presente (senão → skill **setup**) e a issue ser Feature, Story ou Task. Para executar de fato, o spec-kit precisa estar configurado em `specKit.command` (no `.spec-wave.json`) ou na env `SPEC_WAVE_IMPLEMENT_CMD`.
 
-Aciona o spec-kit para implementar uma **Feature** (todas as Stories pendentes, em ordem de dependência), uma **Story** (todas as suas Tasks) ou uma **Task** isolada. Comando **local** (etapa 🚧 Desenvolvimento) — não usa label/Action.
+#### Como o comando se comporta por tipo
 
-**Pré-requisitos:** o repositório atual precisa estar inicializado (`.spec-wave.json` presente) e a issue deve ser do tipo Feature, Story ou Task. Para executar de fato (fora do `--dry-run`), o spec-kit precisa estar configurado via `specKit.command` no `.spec-wave.json` ou a env `SPEC_WAVE_IMPLEMENT_CMD`.
+| Tipo | Comportamento |
+|------|---------------|
+| **Feature** | Lista as Stories (sub-issues), **ordena topologicamente** pelas dependências, **pula as já em 👀 Code Review ou além** (listadas no contexto como "não tocar") e monta **um único** contexto com todas as pendentes, cada uma com suas Tasks. Aciona o spec-kit **uma vez**. |
+| **Story** | Coleta todas as Tasks (sub-issues) e aciona o spec-kit uma única vez. |
+| **Task** | Só aquela task. |
 
-**Modo Feature:** o comando avalia as Stories da Feature — ordena topologicamente pelas dependências (`Depende de:` + *blocked by*), consulta a Etapa de cada uma no board e **pula as já implementadas** (👀 Code Review ou além). O contexto único (`.spec-wave/implement-<feature>.md`) traz as pendentes em ordem, cada uma com suas Tasks. **Ciclo de dependências entre Stories pendentes → o comando aborta** (corrija as linhas `Depende de:`; use `npx @spec-wave/cli@latest order <feature>` para visualizar). Story pendente sem Tasks → aborta pedindo decomposição. Todas implementadas → encerra sem acionar o spec-kit.
+**Abortos no modo Feature:** ciclo de dependências entre Stories pendentes → **exit 1** (corrija as linhas `Depende de:`; veja a skill **order**). Story pendente **sem Tasks** → aborta pedindo decomposição. Todas implementadas → encerra sem acionar o spec-kit.
 
-**Passos:**
-1. Confirme que há `.spec-wave.json` no repo (senão, oriente `/spec-wave setup`).
-2. **Sempre comece com `--dry-run`** para inspecionar o que será feito — detecção do tipo, lista de Tasks coletadas (Story) ou a ordem/puladas/ciclos das Stories (Feature) e o comando do spec-kit que seria executado:
+**Bug** → modo próprio (RFC-004): sem tasks e sem spec/plan, o contexto impõe quatro fases — reproduzir → causa raiz → fix mínimo → teste de regressão. O `bug.md`, quando existe, entra como **hipótese a confirmar** (foi escrito por IA sem executar código), não como fato. O Bug vai sozinho para 👀 Code Review ao abrir o PR: não arrasta a Feature-pai.
+
+Outros tipos (Spike, Epic) → o comando **recusa**.
+
+#### Passos
+
+1. Confirme que há `.spec-wave.json` no repo.
+
+2. **Sempre comece com `--dry-run`:**
    ```bash
    npx @spec-wave/cli@latest implement <número> --dry-run
    ```
-3. Mostre ao usuário o contexto montado em `.spec-wave/implement-<número>.md` e o comando. Esse arquivo contém as **instruções de execução sequencial**: implemente as Tasks **uma por vez** — mova a task para **🚧 Desenvolvimento** só ao iniciá-la e para **🎉 Done** ao concluí-la, antes de passar para a próxima. **Nunca** coloque várias tasks em "in progress" ao mesmo tempo.
-4. **Se você (agente) for implementar diretamente** (sem `specKit.command`): siga o contexto task por task. Para cada task: `npx @spec-wave/cli@latest task start <n>` ao iniciar (Etapa 🚧 Desenvolvimento + Status In Progress) e `npx @spec-wave/cli@latest task done <n>` ao concluir (Etapa 🎉 Done + Status Done) — **prefira esses comandos a mutações GraphQL/`gh` manuais**: eles embutem as regras do board (Etapa nunca retrocede; uma task In Progress por vez). Se o contexto trouxer **aviso de dependência pendente** (a issue depende de outra não concluída), confirme com o usuário antes de seguir. **Ao concluir toda a Story**: faça o commit, abra o PR e mova a Story com `npx @spec-wave/cli@latest story review <n>` (Etapa 👀 Code Review, Status → Todo) — as Tasks já estão em 🎉 Done. A **Feature só avança** quando **TODAS as suas Stories** já estiverem em Code Review — se houver Story pendente, deixe a Feature em 🚧 Desenvolvimento. Lembre: Etapa só avança (nunca volta); Status é o progresso dentro da etapa.
-5. Se o usuário aprovar e o spec-kit estiver configurado, rode sem `--dry-run`:
+   Inspecione: detecção do tipo, Tasks coletadas (Story) ou ordem/puladas/ciclos (Feature), e o comando do spec-kit que seria executado.
+
+3. Mostre ao usuário o contexto montado em `.spec-wave/implement-<número>.md`. Ele inclui os comentários da issue, um **digest do código recente**, um **aviso de dependências pendentes** quando aplicável, e as instruções de execução sequencial.
+
+4. **Se o spec-kit estiver configurado** e o usuário aprovar, rode sem `--dry-run`:
    ```bash
    npx @spec-wave/cli@latest implement <número>
    ```
-   - 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. **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.
+   Se **não** estiver configurado, o comando só monta o contexto e mostra como configurar. Ajude a definir o template — placeholders disponíveis: `{tasksFile} {specFile} {planFile} {issue} {type} {title}`.
+
+   Use `--feature-dir docs/features/<slug>` se a resolução automática falhar e você quiser anexar `spec.md`/`plan.md`.
+
+5. **Se você (agente) for implementar diretamente**, siga o protocolo abaixo.
+
+6. Ao final, confirme o resultado com o usuário e oriente a revisão dos PRs.
+
+#### Protocolo de execução (obrigatório)
+
+**Uma Task por vez.** Nunca deixe duas Tasks com Status "In Progress" ao mesmo tempo.
+
+Para cada Task, **prefira os comandos da CLI a mutações GraphQL/`gh` manuais** — eles embutem as regras do board (Etapa nunca retrocede; uma Task In Progress por vez):
+
+```bash
+npx @spec-wave/cli@latest task start <n>   # Etapa 🚧 Desenvolvimento + Status In Progress
+# ... implementa ...
+npx @spec-wave/cli@latest task done <n>    # Etapa 🎉 Done + Status Done
+```
+
+**Ao concluir toda a Story:** faça o commit, abra o PR e mova a Story:
+
+```bash
+npx @spec-wave/cli@latest story review <n>  # Etapa 👀 Code Review, Status Todo
+```
+
+**A Feature só avança** para 👀 Code Review quando **TODAS** as suas Stories já estiverem lá. Enquanto houver Story pendente, deixe a Feature em 🚧 Desenvolvimento. No modo Feature isso acontece dentro da mesma execução.
+
+**No modo Feature**, siga o contexto Story a Story, **na ordem listada**: implemente as Tasks, depois commit + PR + `story review`; só então passe à próxima Story.
+
+> **Aviso de dependência pendente** no contexto (a issue depende de outra não concluída, via `Depende de: #N` ou *blocked by*) → **confirme com o usuário** antes de seguir fora de ordem.
+
+Lembre: a **Etapa só avança**, nunca volta; o **Status** mede o progresso dentro da etapa.
+
+#### Quando não dá para implementar
+
+| Situação | Saída |
+|----------|-------|
+| Feature **sem Stories** | Rode a skill **decompose** primeiro |
+| **Ciclo de dependências** | Corrija as linhas `Depende de:` — veja a skill **order** |
+| Issue é Spike/Epic | O comando recusa; use a skill **move** para mexer no board |
+| Bug sem `bug.md` | Segue assim mesmo, com aviso — a investigação inteira fica com o executor. Para gerar o documento antes, use a skill **bug**. |
+
+---
+
+### `/spec-wave qa` — etapa 🧪 QA
+
+> **Quando usar:** 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'.
+
+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 a skill **qa-executor** e as instruções do contexto à risca — um cenário por vez, evidência bruta, `blocked` (nunca `fail`) com o `blockedReason` do enum para o que não pôde rodar.
+
+Para validar uma **trilha inteira** (todas as Features de um milestone, em containers paralelos), use a skill **qa-lead** — o `qa` continua sendo a unidade que ela orquestra.
+
+#### 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).
 
 ---
 
-### `/spec-wave rfc <tópico>`
-
-Crie um documento RFC seguindo a estrutura do RFC-001.
-
-**Passos:**
-1. Entreviste o usuário sobre: objetivo, problema atual, solução proposta, princípios, stakeholders afetados
-2. Escreva o RFC em português com as seções:
-   - 1. Objetivo
-   - 2. Princípios
-   - 3. Papéis e Responsabilidades
-   - 4. Estrutura de Trabalho
-   - 5. Fluxo de Trabalho
-   - 6. Automação
-   - 7. Métricas
-   - 8. Riscos e Mitigações
-3. Salve em `rfc/rfc-<slug-do-tópico>.md` usando o Write tool
-4. Crie uma issue de RFC:
+### `/spec-wave bug` — o documento do defeito
+
+> **Quando usar:** Use para gerar o bug.md de um defeito do spec-wave — reprodução, causa raiz, escopo do fix e teste de regressão. Aplica a label spec-wave:bug e deixa o GitHub Action gerar o arquivo em docs/bugs/<slug>/ e abrir um Pull Request. Gatilhos: 'gerar o bug.md da issue 42', 'documentar a causa raiz do bug', 'rodar o spec-wave:bug'. Só vale para issues do tipo Bug — Feature usa spec/plan.
+
+> **Regra fundamental: nunca escreva o `bug.md` você mesmo.** Aplique a label e deixe o Action gerar — é isso que garante que o arquivo chegue à main por Pull Request e seja referenciado na issue. Exceção: revisar/melhorar um `bug.md` já gerado (aí sim use Edit no arquivo local).
+
+**Contexto:** leia `.spec-wave.json` (Read). Ausente → skill **setup**.
+
+#### Por que existe
+
+Um Bug **não** gera `spec.md` + `plan.md`. Esses documentos pedem visão geral funcional, critérios de aceite, requisitos não-funcionais e plano de rollback — peso desproporcional para um defeito.
+
+O `bug.md` tem seis seções e uma finalidade: permitir que outra pessoa (ou o dev-agent) **reproduza, entenda e corrija** o defeito, com prova de que corrigiu.
+
+#### Passos
+
+1. **Confirme que a issue é do tipo Bug.**
+
+   > **Apenas Bug.** Para qualquer outro tipo o Action **pula** a geração, remove a label e comenta.
+
+2. Adicione a label de gatilho:
    ```bash
-   gh issue create --title "[RFC] <título>" --label "[RFC]"
+   gh issue edit <número> --add-label "spec-wave:bug"
    ```
 
----
+3. Informe ao usuário: "Label `spec-wave:bug` adicionada. O Action `generate-bug.yml` vai gerar o `bug.md` automaticamente. Acompanhe em Actions → Generate Bug."
 
-### `/spec-wave bug <número-da-issue>`
+4. Quando concluir, ofereça revisar `docs/bugs/<slug>/bug.md`. O slug vem do título: `[BUG] Duplicidade de pedidos no PIX` → `duplicidade-de-pedidos-no-pix`.
 
-Gera o **`bug.md`** de um defeito: `docs/bugs/<slug>/bug.md`, com reprodução, causa raiz, escopo do fix e teste de regressão.
+   Concentre a revisão em **duas seções**: **Causa Raiz** e **Teste de Regressão**. São elas que decidem se a correção ataca o defeito ou o sintoma — o resto do documento é contexto.
 
-> **Nunca escreva o `bug.md` à mão.** Aplique a label e deixe o Action gerar — é isso que garante o arquivo commitado e referenciado na issue.
+5. **Validar:** aplique `spec-wave:ready`. O Action confere as seis seções obrigatórias e aplica `spec-wave:bug-approved`.
 
-**Por que não spec/plan:** um Bug não gera especificação funcional nem plano técnico. Esses documentos pedem critérios de aceite, requisitos não-funcionais e plano de rollback — peso desproporcional para um defeito. O `bug.md` tem seis seções e uma finalidade: permitir que outra pessoa (ou o dev-agent) reproduza, entenda e corrija, com prova de que corrigiu.
+#### Quando é obrigatório
 
-**Passos:**
+| Severidade | `bug.md` |
+|---|---|
+| **P0** | Opcional — o fix não espera documento. Documente depois, se valer. |
+| **P1** | Recomendado. |
+| **P2 / P3** | **Obrigatório** antes de o bug entrar na fila técnica (✅ Ready). |
 
-1. Confirme que a issue é do tipo **Bug** (para outros tipos o Action pula, remove a label e comenta).
-2. `gh issue edit <n> --add-label "spec-wave:bug"`
-3. Avise: o Action `generate-bug.yml` gera o arquivo e abre um Pull Request com ele.
-4. Ofereça revisar **duas seções**: **Causa Raiz** e **Teste de Regressão**. São elas que decidem se a correção ataca o defeito ou o sintoma.
-5. Validar: `spec-wave:ready` → confere as seis seções e aplica `spec-wave:bug-approved`.
+#### As seis seções
 
-**Seções obrigatórias** (o validador as compara byte a byte — não renomeie ao editar):
 `Reprodução` · `Esperado e Obtido` · `Impacto e Severidade` · `Causa Raiz` · `Escopo do Fix` · `Teste de Regressão`
 
-**Quando é obrigatório:** **P0** dispensa (o fix não espera documento); **P1** recomendado; **P2/P3** obrigatório antes de o bug entrar na fila técnica (✅ Ready).
+O validador procura estes títulos byte a byte — se alguém renomear uma seção ao editar o arquivo, o `spec-wave:ready` reprova.
 
-**Se a crítica reprovar** (`spec-wave:critique-failed`), os três alvos mais comuns são: a causa raiz não explica todos os sintomas relatados; o escopo do fix é maior que a causa (refatoração pegando carona); o teste de regressão passaria mesmo sem o fix.
+#### Se falhar
 
-**Relato insuficiente** produz "Causa raiz não determinada" com hipóteses — isso é o comportamento correto, não falha. Leve as perguntas a quem reportou, acrescente as respostas **como comentário na issue** e reaplique `spec-wave:bug`: os comentários entram no próximo payload.
+- **Comentário 🔎 de crítica com `spec-wave:critique-failed`** → a crítica adversarial achou problema grave. Os três alvos mais comuns: a causa raiz não explica todos os sintomas relatados; o escopo do fix é maior que a causa (refatoração pegando carona); o teste de regressão passaria mesmo sem o fix. Corrija o `bug.md`, commite, remova a label e reaplique `spec-wave:bug`.
+- **`spec-wave:needs-human`** → a crítica reprovou N vezes seguidas e o fluxo está **parado**. Uma pessoa precisa revisar e remover a label.
+- **Relato insuficiente** → o `bug.md` sai com "Causa raiz não determinada" e uma lista de hipóteses. Isso é comportamento correto, não falha: leve as perguntas a quem reportou, acrescente as respostas como comentário na issue e reaplique `spec-wave:bug` — os comentários entram no próximo payload.
+- Para reprocessar num modelo mais forte só nesta issue, aplique também `spec-wave:model:<apelido>` (o apelido precisa existir em `ai.modelAliases`).
 
 ---
 
-### `/spec-wave triage <accept|reject|duplicate> <número>`
+### `/spec-wave triage` — o desfecho da triagem
 
-Desfecho da triagem de um Bug (RFC-004 §4.1) — o mesmo que a tela de Bugs do PM oferece, pelo terminal.
+> **Quando usar:** Use para dar o desfecho da triagem de um Bug do spec-wave: aceitar para a fila técnica, rejeitar, ou marcar como duplicata. Gatilhos: 'aceitar o bug 42', 'rejeitar esse bug', 'marcar como duplicata da 17', 'triar os bugs'. Só vale para issues do tipo Bug.
+
+A triagem decide **uma** coisa: isto vira trabalho, e com que urgência? Daí as três saídas — e nenhuma delas ser "editar". Corrigir o relato é conversa na issue.
 
 ```bash
 npx @spec-wave/cli@latest triage accept 42
-npx @spec-wave/cli@latest triage accept 42 --severity P1     # reclassifica ao aceitar
-npx @spec-wave/cli@latest triage reject 42 --reason "comportamento esperado"
+npx @spec-wave/cli@latest triage accept 42 --severity P1
+npx @spec-wave/cli@latest triage reject 42 --reason "comportamento esperado, documentado em X"
 npx @spec-wave/cli@latest triage duplicate 42 --of 17
 ```
 
-- **accept** → ✅ Ready, com a label `spec-wave:triaged`.
-- **reject** e **duplicate** → **fecham** a issue e **não mexem na Etapa**: ela nunca retrocede, e um bug rejeitado não avançou para lugar nenhum. Quem o tira das filas é o estado `closed`.
-- `duplicate` comenta **nas duas** issues — sem isso, quem acompanha a original não fica sabendo que há outro relato.
+| Ação | Efeito |
+|---|---|
+| `accept` | → **✅ Ready** (fila técnica), label `spec-wave:triaged`. `--severity` reclassifica **trocando** a label, nunca acumulando. |
+| `reject` | Fecha a issue com `spec-wave:wont-fix`. **`--reason` é obrigatório.** |
+| `duplicate` | Fecha com `spec-wave:duplicate` e comenta **nas duas** issues. **`--of` é obrigatório.** |
 
-**Portão de aceite:** **P2/P3** exigem o `bug.md` validado (`spec-wave:bug-approved`) antes da fila. **P0/P1** dispensam — esperar o documento custa mais que investigar durante a correção. E `spec-wave:critique-failed` ou `spec-wave:needs-human` bloqueiam **qualquer** severidade: aceitar um bug cujo documento foi reprovado é justamente o que o portão existe para evitar.
+> `reject` e `duplicate` **não mexem na Etapa**. Ela nunca retrocede, e um bug rejeitado não avançou para lugar nenhum — quem o tira das filas é o estado `closed` da issue.
 
-Para criar um Bug: `npx @spec-wave/cli@latest bug --title "..." [--parent <n>] [--priority P2]`. Ele nasce em **🐞 Triagem** — ou direto em **✅ Ready** se for **P0**.
+#### O portão de aceite
 
----
+| Severidade | Exige `bug.md` validado? |
+|---|---|
+| **P0 / P1** | Não — esperar o documento custa mais que investigar durante a correção. |
+| **P2 / P3** | **Sim** (`spec-wave:bug-approved`). Um bug sem causa raiz investigada empurra a investigação para o dev, e é aí que "corrigir o sintoma" acontece. |
 
-### `/spec-wave qa <número-da-issue>`
+`spec-wave:critique-failed` e `spec-wave:needs-human` bloqueiam **qualquer** severidade, P0 inclusive: aceitar um bug cujo documento foi reprovado é exatamente o que o portão existe para evitar.
 
-A etapa **🧪 QA**: plano por Feature + execução local com veredito. Duas metades, nesta ordem obrigatória:
+#### Se o aceite for recusado
 
-**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`.
+O comando diz qual portão barrou. Os caminhos:
+
+- **Falta o `bug.md`** → skill **bug** (aplica `spec-wave:bug`), depois `spec-wave:ready` para validar. Ou `--severity P1`, se for de fato urgente — mas isso é reclassificar o defeito, não contornar o portão.
+- **`spec-wave:critique-failed`** → corrija o `bug.md`, commite, remova a label.
+- **`spec-wave:needs-human`** → uma pessoa precisa revisar antes de remover.
+
+#### Criar um Bug
 
-**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
+npx @spec-wave/cli@latest bug --title "Duplicidade de pedidos no PIX" --parent 17 --priority P2
 ```
-- 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.
+Nasce em **🐞 Triagem** — ou direto em **✅ Ready** se for **P0**.
 
 ---
 
-### `/spec-wave fix-pr <número-do-pr>`
+### `/spec-wave rfc` — documento de processo
 
-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.
+> **Quando usar:** Use para escrever um documento RFC de processo seguindo a estrutura do RFC-001 do spec-wave e registrá-lo como issue no board. Gatilhos: 'escrever um RFC', 'documentar esse processo como RFC', 'criar um RFC sobre X'. RFC não usa spec nem plan — depois de escrito, ele decompõe direto em Tasks (skill decompose).
 
-**Pré-requisitos:** `.spec-wave.json` deve existir (para resolver `owner/repo`). Token com permissão de push no branch do PR.
+RFCs são escritos em **português do Brasil** e vivem em `rfc/`.
 
-**Passos:**
+**Contexto:** leia `.spec-wave.json` (Read). Ausente → skill **setup**. Se já existirem RFCs em `rfc/`, leia um deles antes de escrever — o estilo da equipe vence este template.
 
-1. **Resolver contexto**
-   - Leia `.spec-wave.json` para obter `owner` e `repo`.
-   - Confirme o número do PR com o usuário se não vier como argumento.
+#### Passos
 
-2. **Coletar dados do PR**
-   ```bash
-   gh pr view <número> --json number,title,headRefName,body,changedFiles
-   gh pr diff <número>
-   gh api repos/<owner>/<repo>/pulls/<número>/comments
-   gh api repos/<owner>/<repo>/pulls/<número>/reviews
-   ```
-   - Liste todos os arquivos alterados.
-   - Colete todos os review comments (inline) e reviews gerais.
+1. **Entreviste o usuário** sobre: objetivo, problema atual, solução proposta, princípios, stakeholders afetados. Não invente contexto organizacional.
 
-3. **Fazer checkout no branch do PR**
+2. **Escreva o RFC** com estas seções:
+
+   1. Objetivo
+   2. Princípios
+   3. Papéis e Responsabilidades
+   4. Estrutura de Trabalho
+   5. Fluxo de Trabalho
+   6. Automação
+   7. Métricas
+   8. Riscos e Mitigações
+
+3. **Salve** com Write em `rfc/rfc-<slug-do-tópico>.md`.
+
+4. **Crie a issue de RFC no board** — use a CLI, não `gh issue create` (que não adiciona ao Project):
    ```bash
-   gh pr checkout <número>
+   npx @spec-wave/cli@latest issue --type rfc \
+     --title "<título sem prefixo>" \
+     --body "<resumo + link para rfc/rfc-<slug>.md>"
    ```
+   A issue nasce em **📥 Backlog**.
 
-4. **Varredura de problemas** — para cada categoria abaixo, leia os arquivos alterados e identifique issues:
+5. **Próximo passo:** um RFC **não** usa `spec.md` nem `plan.md`. Quando a descrição estiver completa, ele decompõe **direto em Tasks** — use a skill **decompose**, que grava o rascunho em `docs/rfcs/<slug>/decomposition.md`.
 
-   | Categoria | O que procurar |
-   |-----------|----------------|
-   | **Segurança** | Credenciais hardcoded, secrets/API keys expostas, configs inseguras, injeção SQL/XSS |
-   | **Arquitetura** | Dependências circulares, exports faltando, wiring incompleto, violações de camada |
-   | **Infraestrutura** | OIDC mal configurado, IAM permissivo demais, Dockerfile sem usuário não-root, state remoto ausente |
-   | **Qualidade** | sync-over-async, validação ausente, operações não idempotentes, error handling ausente |
+#### Cuidados
 
-   Se não houver review comments manuais, use o agente `caveman:cavecrew-reviewer` para detecção automatizada:
-   ```
-   Agent(caveman:cavecrew-reviewer) → diff do PR + arquivos alterados
-   ```
+- Peça confirmação do rascunho antes de gravar: o usuário conhece papéis, times e restrições que o repositório não revela.
+- Se o repositório já tiver um RFC sobre o mesmo assunto, proponha **emendar** o existente em vez de criar um concorrente.
 
-5. **Para cada problema encontrado:**
-   a. Leia o(s) arquivo(s) afetado(s) com Read
-   b. Aplique o fix com Edit
-   c. Faça commit separado:
-      ```bash
-      git add <arquivo>
-      git commit -m "fix: <problema> (issue #<N>)
+---
 
-      <causa raiz>
+### `/spec-wave fix-pr` — auditoria e correção de PR
 
-      Solution: <descrição do fix>"
-      ```
-   d. Push ao branch do PR:
-      ```bash
-      git push
-      ```
+> **Quando usar:** Use para auditar um Pull Request e corrigir os problemas encontrados — segurança, arquitetura, infraestrutura e qualidade — gerando um commit separado por fix, respondendo cada review comment com o hash do commit e postando um sumário no PR. Gatilhos: 'auditar o PR 42', 'corrigir os comentários de review', 'fix-pr 42', 'resolver os apontamentos do PR'.
 
-6. **Responder aos review comments** — para cada comment inline do PR:
-   ```bash
-   gh api repos/<owner>/<repo>/pulls/<número>/comments/<comment-id>/replies \
-     -f body="✅ **FIXED** — commit **<HASH>**
+Cada fix vira um **commit separado** no branch do PR. Cada review comment recebe uma **resposta com o hash do commit**.
 
-   \`\`\`<linguagem>
-   <trecho corrigido>
-   \`\`\`
+**Pré-requisitos:** `.spec-wave.json` deve existir (para resolver `owner/repo`). Token com permissão de push no branch do PR.
 
-   <explicação do fix>"
-   ```
+#### Passos
+
+##### 1. Resolver contexto
+
+Leia `.spec-wave.json` para obter `owner` e `repo`. Confirme o número do PR com o usuário se não vier como argumento.
 
-7. **Comentário de sumário no PR**
+##### 2. Coletar dados do PR
+
+```bash
+gh pr view <número> --json number,title,headRefName,body,changedFiles
+gh pr diff <número>
+gh api repos/<owner>/<repo>/pulls/<número>/comments
+gh api repos/<owner>/<repo>/pulls/<número>/reviews
+```
+
+Liste todos os arquivos alterados e colete os review comments (inline) e reviews gerais.
+
+##### 3. Checkout do branch
+
+```bash
+gh pr checkout <número>
+```
+
+##### 4. Varredura de problemas
+
+Para cada categoria, leia os arquivos alterados e identifique issues:
+
+| Categoria | O que procurar |
+|-----------|----------------|
+| **Segurança** | Credenciais hardcoded, secrets/API keys expostas, configs inseguras, injeção SQL/XSS |
+| **Arquitetura** | Dependências circulares, exports faltando, wiring incompleto, violações de camada |
+| **Infraestrutura** | OIDC mal configurado, IAM permissivo demais, Dockerfile sem usuário não-root, state remoto ausente |
+| **Qualidade** | sync-over-async, validação ausente, operações não idempotentes, error handling ausente |
+
+Se não houver review comments manuais, use um agente de review para detecção automatizada sobre o diff + arquivos alterados.
+
+##### 5. Corrigir, um commit por problema
+
+Para cada problema: leia o arquivo (Read), aplique o fix (Edit), e commite isoladamente:
+
+```bash
+git add <arquivo>
+git commit -m "fix: <problema> (issue #<N>)
+
+<causa raiz>
+
+Solution: <descrição do fix>"
+git push
+```
+
+##### 6. Responder aos review comments
+
+Para cada comment inline:
+
+```bash
+gh api repos/<owner>/<repo>/pulls/<número>/comments/<comment-id>/replies \
+  -f body="✅ **FIXED** — commit **<HASH>**
+
+\`\`\`<linguagem>
+<trecho corrigido>
+\`\`\`
+
+<explicação do fix>"
+```
+
+##### 7. Sumário no PR
+
+```bash
+gh pr comment <número> --body "<sumário>"
+```
+
+Formato:
+
+```markdown
+## 🔍 PR Audit — Spec Wave
+
+### Problemas encontrados e corrigidos
+
+| # | Severidade | Categoria | Problema | Commit |
+|---|-----------|-----------|---------|--------|
+| 1 | 🔴 Critical | Segurança | Credencial hardcoded em config.js | abc1234 |
+| 2 | 🟡 Medium | Qualidade | Operação não idempotente em createOrder | def5678 |
+
+### Commits criados
+- `abc1234` fix: credencial hardcoded removida (issue #1)
+- `def5678` fix: idempotency key adicionada em createOrder (issue #2)
+
+**Total:** <N> problema(s) encontrado(s) e corrigido(s).
+```
+
+#### Severidade
+
+| Nível | Critério |
+|-------|----------|
+| 🔴 Critical | Segurança, dados expostos, falha em produção |
+| 🟠 High | Bug que afeta usuários, arquitetura quebrada |
+| 🟡 Medium | Qualidade, manutenibilidade, performance |
+| 🔵 Low | Estilo, naming, comentários |
+
+#### Output esperado
+
+- Lista de issues (severidade + impacto)
+- Lista de commits criados (hash + mensagem)
+- Confirmação das replies postadas nos review comments
+- Estado final do PR
+
+> Reporte fielmente: se um problema foi encontrado mas **não** corrigido (fora de escopo, exige decisão do usuário), diga isso explicitamente no sumário em vez de omitir.
+
+---
+
+### `/spec-wave uninstall` — remove a configuração
+
+> **Quando usar:** Use quando o usuário quiser remover a configuração do spec-wave de um repositório: labels, arquivos .github (workflows e issue templates) e o .spec-wave.json. Gatilhos: 'remover o spec-wave', 'desinstalar spec-wave deste repo', 'limpar as labels do spec-wave'. O GitHub Project NUNCA é apagado — o usuário decide isso à mão.
+
+Remove labels + arquivos `.github` + `.spec-wave.json`. **NUNCA apaga o GitHub Project** — isso preserva o histórico do board de propósito.
+
+| Flag | Descrição |
+|------|-----------|
+| `--repo <owner/repo>` | Repositório. Default: lê do `.spec-wave.json`. |
+| `--skip-labels` | Não remove as labels. |
+| `--skip-files` | Não remove os arquivos `.github`. |
+| `--keep-config` | Mantém o `.spec-wave.json` local. |
+| `--dry-run` | Mostra o que seria removido sem alterar nada. |
+| `--yes` | Não pede confirmação. |
+
+#### Passos
+
+1. **Confirme com o usuário.** A ação remove labels e faz **commits removendo os workflows** do repositório remoto. Deixe claro que issues e o Project permanecem.
+
+2. **Mostre antes o que será removido:**
    ```bash
-   gh pr comment <número> --body "<sumário>"
+   npx @spec-wave/cli@latest uninstall --dry-run
    ```
-   Formato do sumário:
+
+3. Execute:
+   ```bash
+   npx @spec-wave/cli@latest uninstall
    ```
-   ## 🔍 PR Audit — Spec Wave
+   A CLI pede confirmação própria. Use `--yes` **apenas** se o usuário já confirmou explicitamente.
+
+4. **Lembre o usuário** de excluir o **GitHub Project** manualmente, se desejar — a CLI não o apaga.
 
-   ### Problemas encontrados e corrigidos
+#### Observações
 
-   | # | Severidade | Categoria | Problema | Commit |
-   |---|-----------|-----------|---------|--------|
-   | 1 | 🔴 Critical | Segurança | Credencial hardcoded em config.js | abc1234 |
-   | 2 | 🟡 Medium | Qualidade | Operação não idempotente em createOrder | def5678 |
+- Remover as labels não desfaz o histórico das issues; elas continuam no board com suas Etapas.
+- Os documentos gerados em `docs/features/` e `docs/rfcs/` **não** são removidos.
+- Para apenas atualizar uma instalação existente (em vez de removê-la), use a skill **update**.
 
-   ### Commits criados
-   - `abc1234` fix: credencial hardcoded removida (issue #1)
-   - `def5678` fix: idempotency key adicionada em createOrder (issue #2)
+---
 
-   **Total:** <N> problema(s) encontrado(s) e corrigido(s).
+### Outras skills (fluxos e utilitários)
+
+Cada uma existe como skill dedicada do plugin (`/spec-wave:<nome>`) — e os
+utilitários de board estão flag a flag na *Referência da CLI* acima. Rode
+`npx @spec-wave/cli@latest <comando> --help` para os parâmetros.
+
+- **`workflow`** — 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).
+- **`preparar-feature`** — Use para conduzir uma Feature do spec-wave pelo trecho que vai da spec pronta até ✅ Ready com as Stories e Tasks criadas no board: gera o plan.md, trata a crítica adversarial, valida, move a etapa, decompõe e confere o resultado. Gatilhos: 'gerar o plano', 'preparar a feature 12', 'deixar pronta para o dev', 'levar até ready', 'decompor a feature', 'roda o plan da #12'. Use mesmo quando o usuário nomear só um passo — os passos têm armadilhas encadeadas que só fazem sentido tratadas juntas. Para as specs de uma milestone inteira use preparar-specs; para um passo isolado e sem supervisão, as skills plan, ready ou decompose.
+- **`preparar-specs`** — 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).
+- **`audit`** — Use para auditar as specs de uma milestone COMO CONJUNTO, depois de geradas: dependência que ninguém cria, bloqueante em milestone posterior, ciclo entre Features, sobreposição com código já existente — e, com --critique, contradições semânticas entre as specs. Gatilhos: 'audita as specs da v06', 'as dependências da milestone fecham?', 'tem contradição entre as specs?', 'roda a auditoria antes dos planos'. NÃO use para criticar um documento de uma Feature — isso é o passo critique do fluxo normal.
+- **`order`** — Use para descobrir em que ordem as Stories de uma Feature do spec-wave devem ser implementadas, segundo as dependências declaradas (Depende de: #N e a relação nativa blocked by). Também detecta ciclos de dependência e Stories fora de ordem. Gatilhos: 'qual story implementar primeiro', 'ordem das stories da feature 12', 'tem ciclo de dependência?'. Use antes da skill implement.
+- **`merge`** — Use para mergear os PRs empilhados das Stories de uma Feature do spec-wave, na ordem das dependências, movendo o board até 🧪 QA. Gatilhos: 'mergeia os PRs da feature 12', 'integra as stories', 'os PRs estão revisados, pode mergear', 'qual a ordem de merge?'. Use DEPOIS da revisão humana (PRs marcados como prontos). NÃO mergeie PRs de pilha à mão com --delete-branch — é o que fecha o PR dependente.
+- **`run`** — Use para conduzir o fluxo do spec-wave LOCALMENTE, sem gastar minutos de GitHub Actions: `spec-wave run <issue>` executa nesta máquina o passo que a label dispararia (spec, plan, crítica, validate, decompose, apply) e `spec-wave mode local|actions` alterna entre os dois mundos. Gatilhos: 'rodar o spec-wave local', 'qual o próximo passo da issue 12', 'sem gastar Actions', 'desligar os workflows', 'trocar para execução local'.
+- **`qa-lead`** — Use para orquestrar o QA de uma TRILHA inteira (milestone) do spec-wave — preparar os planos de todas as Features (`qa-lead plan`), executar o ciclo com containers paralelos (`qa-lead run`) e consultar relatórios de ciclo (`qa-lead report`). Gatilhos: 'rodar o QA do milestone', 'QA da release', 'trilha de QA', 'relatório de QA do ciclo'.
+- **`qa-executor`** — Use quando você for o agente EXECUTOR de QA do spec-wave — acionado via `qa.command` com um contexto `.spec-wave/qa-<n>.md`. Executa os cenários um a um, registra evidência bruta e grava o veredito em `.spec-wave/qa-result-<n>.json`. NUNCA corrige código nem escreve no GitHub. Gatilhos: 'execute o QA descrito em', contexto de QA do spec-wave, arquivo qa-<n>.md.
+- **`task`** — Use para iniciar ou concluir uma Task do spec-wave no board: task start move para 🚧 Desenvolvimento com Status In Progress, task done move para 🎉 Done. Gatilhos: 'comecei a task 56', 'terminei a task 56', 'marcar task como feita'. Prefira sempre este comando a mexer no board via GraphQL ou gh — ele embute a regra de uma única Task In Progress por Story.
+- **`story`** — Use para mandar uma Story do spec-wave para 👀 Code Review depois de implementar todas as suas Tasks e abrir o PR. Gatilhos: 'terminei a story 34', 'mandar a story para review', 'story pronta para code review'. Prefira este comando a mutações GraphQL manuais no board.
+- **`move`** — Use para mover qualquer item do board spec-wave — Feature, Story, Task, Bug ou RFC — para uma Etapa, quando task start|done e story review não cobrem o movimento (ex.: mover uma Feature para Homologação ou Deploy). Gatilhos: 'mover a feature 12 para homologação', 'passar para deploy', 'avançar o card'. Prefira este comando a gh api graphql manual: a Etapa nunca retrocede, e isso é regra do fluxo, não limitação.
+
+---
+
+## Tech Context (`.github/config/tech_context.yml`)
+
+Fonte de verdade estática da stack do sistema (RFC-002 §4). O `generate-plan` lê este arquivo para embasar o plano técnico e usar **APENAS** as tecnologias/serviços nele declarados — sem ele, o plano fica genérico e pode inventar APIs inexistentes. O `npx @spec-wave/cli@latest init` gera um **scaffold de exemplo** que **deve ser adaptado** à stack real. Use este fluxo quando o arquivo estiver ausente ou desatualizado.
+
+**Como ajudar a criar (quando não existir):**
+
+1. **Confirme a ausência:** tente `Read .github/config/tech_context.yml`. Se já existir, apenas confirme com o usuário se reflete a stack atual e pule para o fim.
+2. **Detecte a stack** lendo os arquivos do repositório (use Read; não invente):
+   - `package.json` → backend/frontend e libs (ex.: `@nestjs/core`, `next`, `react`, `@prisma/client`, `express`).
+   - `pom.xml` / `build.gradle` (Java), `requirements.txt` / `pyproject.toml` (Python), `go.mod` (Go).
+   - `prisma/schema.prisma` ou pasta `migrations/` → tabelas e colunas para `database_schemas`.
+   - `Dockerfile` / `docker-compose.yml` / charts Helm → `infra`.
+   - Procure papéis/roles (enum de RBAC) no código para `security.rbac_roles`.
+3. **Rascunhe** o YAML seguindo EXATAMENTE este schema (preencha só o que conseguir confirmar; deixe `# TODO` no que faltar — não invente):
+   ```yaml
+   system_info:
+     name: "<nome do sistema>"
+     stack:
+       backend: "<ex.: Node.js (NestJS v11)>"
+       frontend: "<ex.: Next.js 16 (React 19)>"
+       database: "<ex.: PostgreSQL (Prisma 5)>"
+       infra: "<ex.: Docker / Kubernetes>"
+     architecture: "<ex.: Monorepo Nx / Microservices>"
+   security:
+     auth_protocol: "<ex.: JWT>"
+     rbac_roles: ["ADMIN", "..."]
+   database_schemas:
+     - table: "<tabela>"
+       columns: "<col1, col2, ...>"
+   existing_services:
+     - name: "<serviço>"
+       endpoint: "<caminho>"
+       auth: "<ex.: JWT, mTLS>"
+   internal_libraries:
+     - "<lib interna>"
+   ```
+4. **Mostre o rascunho ao usuário e peça confirmação/ajustes** antes de gravar (ele conhece serviços internos e roles que o código pode não revelar).
+5. **Grave** com Write em `.github/config/tech_context.yml`.
+6. **Oriente a commitar e pushar** antes de seguir (o Action lê do repo). Sugira ao usuário rodar, via prefixo `!`:
+   ```bash
+   !git add .github/config/tech_context.yml && git commit -m "chore: tech_context.yml [spec-wave]" && git push
    ```
 
-**Output esperado:**
-- Lista de issues (severidade + impacto)
-- Lista de commits criados (hash + mensagem)
-- Confirmação de replies postadas nos review comments
-- Estado final do PR
+**Desvios pontuais:** para uma Feature específica usar algo fora do padrão (ex.: "usar DynamoDB só aqui"), oriente a adicionar uma seção `## Tech Override` no corpo da issue, com um bloco YAML que será mesclado (deep-merge) sobre o `tech_context.yml`:
 
-**Severidade:**
-- 🔴 Critical — segurança, dados expostos, falha em produção
-- 🟠 High — bug que afeta usuários, arquitetura quebrada
-- 🟡 Medium — qualidade, manutenibilidade, performance
-- 🔵 Low — estilo, naming, comentários
+````markdown
+## Tech Override
+```yaml
+system_info:
+  stack:
+    database: "DynamoDB"
+```
+````
 
 ---
 
@@ -957,9 +1603,18 @@ docs/
                             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>`
+      dependency-map.json ← grafo de dependências das Stories PRÉ-COMPUTADO,
+                            escrito pelo decompose --apply e atualizado por
+                            `order --sync`. É o que deixa order/implement/merge
+                            consultarem a ordem sem pagar a API por Story
   rfcs/
     <slug-do-rfc>/
       decomposition.md   ← mesmo papel, com "## Task N" (RFC não usa spec/plan)
+  qa/
+    <slug-da-milestone>/
+      cycle-<n>/
+        report.md        ← relatório do ciclo N da trilha de QA (qa-lead run)
+        report.json      ← o mesmo ciclo, no schema protocol/qa-trail-report.v1.json
 ```
 
 O slug é gerado a partir do título da issue: `[FEATURE] Cadastro de Pedidos com PIX` → `cadastro-de-pedidos-com-pix`