@spec-wave/cli 0.32.0 → 0.34.0

package/src/templates/skill/SKILL.md

@@ -650,20 +650,24 @@ npx @spec-wave/cli@latest install-skill --force
 
 > **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:
+Comando **local**:
 
 ```bash
 npx @spec-wave/cli@latest doctor
+npx @spec-wave/cli@latest doctor --deep   # confere também as Tasks de cada decomposição
 ```
 
 #### O que ele checa
 
-- **Token GitHub** e a fonte dele; **escopos** (`repo`, `project`, `workflow`), com degradação para checks funcionais em fine-grained PATs
+- **Token GitHub** e a fonte dele
+- **Cota da API (GraphQL)**: pontos restantes e horário do reset — medido de graça (a consulta não custa pontos) e usado pelos checks abaixo para decidir se cabem no orçamento
+- **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
+- **Decomposições aplicadas**: `decomposition.md` × issues reais. Por padrão confere só até o nível de Story (1 chamada por Feature); `--deep` desce até as Tasks (1 chamada a mais por Story) — mais completo, mais caro. Se a cota estiver baixa, o check é pulado com a causa explícita em vez de estourar em silêncio.
 - **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`)
 
@@ -1030,6 +1034,7 @@ Comando **local** (lê o `.spec-wave.json`, como o `issue`), **não** disparado
 | `<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**. |
+| `--verify-commits` | Depois de executar, confere se os commits recentes trazem o trailer `Spec-Wave-Story`/`Spec-Wave-Tasks` (rastro verificável, não depende do assunto do commit). Best-effort — nunca bloqueia. |
 
 **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`.
 
@@ -1083,15 +1088,20 @@ npx @spec-wave/cli@latest task start <n>   # Etapa 🚧 Desenvolvimento + Status
 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:
+**Ao concluir toda a Story:** faça o commit e mova a Story. O **assunto** do commit é livre (o que você achar mais claro), mas o **rodapé** precisa trazer o rastro exato que o contexto montado dita — `Spec-Wave-Story: #<n>` e `Spec-Wave-Tasks: #<n>, #<n>...` — copiado literalmente, sem alterar as chaves. É esse rodapé, não o assunto, que `--verify-commits` e o `merge` conferem:
 
 ```bash
 npx @spec-wave/cli@latest story review <n>  # Etapa 👀 Code Review, Status Todo
 ```
 
+Se abre PR e onde faz push depende do **modo de entrega** — o contexto montado já diz qual é (não adivinhe pelo tipo de issue):
+
+- **`pr-stack`** (fluxo manual padrão): abra o **Pull Request da Story como rascunho** (`gh pr create --draft`) antes de mover a Story. Numa Feature com várias Stories os PRs ficam **empilhados** (cada um baseado no anterior) — o merge é ordem-dependente; use `spec-wave merge <feature>`, nunca `--delete-branch` manual num PR da pilha.
+- **`agent`** (rodando sob o `dev-agent`): **NÃO crie branch, NÃO abra PR** — faça só o commit e o push no branch atual. O daemon mantém um único branch (`agent/issue-<n>`) e é ele quem abre o PR ao final, para a Feature inteira. Abrir um PR por Story aqui cria um branch lateral (`agent/issue-<n>-story-<m>`) cujo trabalho não entra no PR do agente.
+
 **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.
+**No modo Feature**, siga o contexto Story a Story, **na ordem listada**: implemente as Tasks, depois commit (+ PR só em modo `pr-stack`) + `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.