@spec-wave/cli 0.12.0 → 0.14.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|issue|feature|spec|plan|ready|decompose|order|implement|task|story|uninstall|rfc|fix-pr] [target]"
+argument-hint: "[info|setup|update|doctor|issue|feature|spec|plan|ready|decompose|order|implement|task|story|move|uninstall|rfc|fix-pr] [target]"
 user-invocable: true
 allowed-tools:
   - Bash(npx @spec-wave/cli@latest *)
@@ -87,33 +87,29 @@ Essa é a sequência completa, mas **cada tipo de artefato percorre só um trech
 |----------|----------|----------|-------------|
 | **Initiative / Epic** | 📥 Backlog | — | Agrupadores. Não têm fluxo próprio; acompanham os filhos. |
 | **Feature** | 📥 Backlog | 🎯 Priorizado → 📋 Spec → 📋 Plan → ✅ Ready → 🚧 Desenvolvimento → 👀 Code Review → 🧪 QA → 📋 Homologação → 🚀 Deploy → 🎉 Done | Fica parada em **✅ Ready** esperando um dev assumir — é ali que ela aparece na fila do TL. Só avança para 👀 Code Review quando **TODAS** as suas Stories já estiverem lá. |
-| **Story** | **✅ Ready** (criada pelo `decompose`) | 🚧 Desenvolvimento → 👀 Code Review → 🧪 QA → 📋 Homologação → 🎉 Done | **Nunca nasce em 📥 Backlog.** |
-| **Task** | **✅ Ready** (criada pelo `decompose`) | 🚧 Desenvolvimento → 🎉 Done | **Não** passa por Code Review, QA nem Homologação — só `task start` e `task done`. |
+| **Story** | **✅ Ready** (criada pelo `decompose-apply`) | 🚧 Desenvolvimento → 👀 Code Review → 🧪 QA → 📋 Homologação → 🎉 Done | **Nunca nasce em 📥 Backlog.** |
+| **Task** | **✅ Ready** (criada pelo `decompose-apply`) | 🚧 Desenvolvimento → 🎉 Done | **Não** passa por Code Review, QA nem Homologação — só `task start` e `task done`. |
 | **RFC** | 📥 Backlog | decompõe direto em **Tasks** (que nascem em ✅ Ready) | Não usa spec/plan. |
 | **Bug** | 📥 Backlog | 🚧 Desenvolvimento → 🎉 Done | Ao aprovar, vai direto para Done (não passa por Homologação). |
 | **Spike** | 📥 Backlog | **movido só à mão pelo usuário** | Nunca avance a Etapa de um Spike por conta própria. |
 
-**Regra da Etapa:** a Etapa **só avança, nunca retrocede**. O campo **Status** (Todo / In Progress / Done) mede o progresso *dentro* da Etapa e reinicia a cada avanço. Prefira sempre os comandos da CLI (`task start|done`, `story review`) a mutações manuais no board — eles embutem essas regras.
+**Regra da Etapa:** a Etapa **só avança, nunca retrocede**. O campo **Status** (Todo / In Progress / Done) mede o progresso *dentro* da Etapa e reinicia a cada avanço. Prefira sempre os comandos da CLI (`move`, `task start|done`, `story review`) a mutações manuais no board — eles embutem essas regras.
 
 Labels de gatilho:
 - `spec-wave:spec` → dispara `generate-spec.yml` → gera `spec.md` (especificação funcional, primeiro)
 - `spec-wave:plan` → dispara `generate-plan.yml` → gera `plan.md` (plano técnico, a partir da spec)
 - `spec-wave:ready` → dispara `validate.yml` → valida ambos os arquivos
-- `spec-wave:decompose` → dispara `decompose.yml` → gera Stories e Tasks
+- `spec-wave:decompose` → dispara `decompose.yml` → gera (ou **re-critica**) o **rascunho** em `decomposition.md`. **Não cria issue nenhuma.**
+- `spec-wave:decompose-apply` → dispara o mesmo workflow em modo aplicação → cria as Stories e Tasks **a partir do rascunho revisado**
 
 Labels de **estado** (gravadas pelas automações — **não** são gatilhos, não as adicione por conta própria):
-- `spec-wave:critique-failed` → a crítica adversarial apontou contradições **graves** nos documentos; **bloqueia** o `spec-wave:ready` até ser removida (veja *Crítica adversarial* abaixo)
+- `spec-wave:decompose-ready` → o rascunho da decomposição passou pela crítica e espera **revisão humana**; aplique `spec-wave:decompose-apply` para criar as issues
+- `spec-wave:critique-failed` → a crítica adversarial apontou contradições **graves**; **bloqueia** o `spec-wave:ready` até ser removida (veja *Crítica adversarial* abaixo)
+- `spec-wave:needs-human` → a crítica reprovou N vezes seguidas (default 3); **para o fluxo** até uma pessoa revisar e remover a label
 - `spec-wave:decomposed` → a Feature/RFC já foi decomposta; o `decompose` pula silenciosamente enquanto ela existir (veja *Guard de idempotência* abaixo)
 
-Label **modificadora** — `spec-wave:force`: sozinha **não dispara nada**; adicionada **junto** de uma label de gatilho, manda o comando **re-executar a etapa ignorando os guards**. É **consumida** (removida) pelo run que a leu, então vale para uma execução só. Adicione-a **antes ou junto** do gatilho, nunca depois (o evento do gatilho já teria disparado):
-```bash
-gh issue edit <n> --add-label "spec-wave:force" --add-label "spec-wave:decompose"
-```
-Efeito por comando:
-- **spec** e **plan** → geram a **próxima versão** em vez de sobrescrever: `spec.md` (v1) → `spec-v2.md` → `spec-v3.md`… As versões anteriores ficam intactas e a **maior versão passa a ser o documento atual** (veja *Documentos versionados*).
-- **decompose** → ignora o guard e **fecha as sub-issues da decomposição anterior** antes de gerar as novas (veja *Guard de idempotência*).
-
-Sem a label, `spec`/`plan` **sobrescrevem o documento atual** (comportamento de sempre).
+Label **modificadora** (esta você pode aplicar):
+- `spec-wave:model:<apelido>` → força um modelo específico **naquela execução**, resolvido por `ai.modelAliases` no `.spec-wave.json`. Serve para reprocessar um caso difícil num modelo mais forte sem editar a configuração do repositório inteiro. Duas dessas labels na mesma issue = ambíguo, nenhuma vale.
 
 A etapa **🚧 Desenvolvimento** é coberta pelo comando **local** `npx @spec-wave/cli@latest implement <número>` (não é uma label/Action): lê uma **Feature** (todas as Stories pendentes, em ordem de dependência), uma Story ou uma Task e aciona o spec-kit para implementar. Veja `/spec-wave implement`.
 
@@ -193,7 +189,7 @@ Mesmas flags do `issue` (exceto `--type`, fixo em `feature`). Mantido para o flu
 | Flag | Tipo | Descrição |
 |------|------|-----------|
 | `--issue-number <n>` | string (obrigatório) | Número da issue no GitHub. |
-| `--force` | flag | Re-executa a etapa ignorando os guards. No fluxo por label o equivalente é a label `spec-wave:force` (a linha de comando do workflow é fixa) — prefira a label. |
+| `--apply` | flag (só `decompose`) | Cria as issues a partir do `decomposition.md` revisado. **Sem** a flag, o `decompose` apenas gera/critica o rascunho e não cria nada. |
 
 > ⚠️ Esses quatro comandos são executados pelos **GitHub Actions** (disparados por labels), **não** pela skill diretamente. Veja a *Regra fundamental*: para gerar plan/spec/decompor, adicione a **label** correspondente — não rode o comando à mão (a não ser para debug local).
 >
@@ -206,12 +202,12 @@ Mesmas flags do `issue` (exceto `--type`, fixo em `feature`). Mantido para o flu
 |----------|------|-----------|
 | `<issue>` | string (obrigatório) | Número da issue (Feature, Story ou Task), ex.: `12` ou `#12`. Argumento posicional. |
 | `--feature-dir <path>` | string | Caminho `docs/features/<slug>` para anexar `spec.md`/`plan.md` como contexto (sobrescreve a resolução automática). |
-| `--dry-run` | flag | Monta o contexto e imprime o comando do spec-kit **sem executar**. |
+| `--dry-run` | flag | Monta o contexto e imprime o comando do spec-kit **sem executar** e **sem escrever nada no GitHub** (não move cards, não adiciona itens ao Project). |
 
 > Diferente dos quatro acima, `implement` roda **localmente** (lê `.spec-wave.json`, como `issue`), não por Action. Detecta o tipo da issue: **Feature** → lista as Stories (sub-issues), **ordena topologicamente pelas dependências** (`Depende de:` + *blocked by*), **pula** as já em 👀 Code Review+ (listadas no contexto como "não tocar") e monta **um único** contexto com todas as pendentes (cada uma com suas Tasks), acionando o spec-kit **uma vez** com `{issue}/{type}/{title}` da Feature — **ciclo de dependências entre Stories pendentes aborta o comando (exit 1)**; **Story** → coleta todas as Tasks (sub-issues) e aciona o spec-kit uma única vez; **Task** → só aquela task. Monta o contexto em `.spec-wave/implement-<n>.md` e chama o comando configurado em `specKit.command` (no `.spec-wave.json`) ou na env `SPEC_WAVE_IMPLEMENT_CMD`. Placeholders disponíveis no template: `{tasksFile} {specFile} {planFile} {issue} {type} {title}`. Se nada estiver configurado, ele apenas monta o contexto e mostra como configurar (não executa). O contexto inclui os **comentários da issue**, um **digest do código recente** e um **aviso de dependências pendentes** quando a issue depende (linha `Depende de: #N` ou relação nativa *blocked by*) de outra que ainda não foi concluída — nesse caso, confirme com o usuário antes de seguir. Inclui também instruções para o agente implementar as Tasks **sequencialmente, uma por vez** (nunca duas com Status "In Progress" ao mesmo tempo): cada Task usa o **Status** (In Progress) *dentro* da Etapa 🚧 Desenvolvimento e, **ao concluir, avança para a Etapa 🎉 Done com Status Done**. **Ao concluir toda a Story**: fazer o commit, abrir o PR e **avançar a Etapa da Story para 👀 Code Review** (Status → Todo) — as Tasks já estão em 🎉 Done. A **Feature só avança** para Code Review quando **TODAS as suas Stories** já estiverem em Code Review — enquanto houver Story pendente, a Feature fica em 🚧 Desenvolvimento. Etapa só avança (nunca volta); Status mede o progresso dentro da etapa.
 
 ### `@spec-wave/cli doctor` — preflight de auth e configuração (comando LOCAL)
-Sem flags. Roda um checklist de diagnóstico no repositório atual: 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. owner, `.spec-wave.json` (campos e sincronia com o Project real), acesso ao repositório, configuração de IA (provider/modelo/`ai.models`/teto de saída + secrets do Actions), **spec-kit** (`specKit.command` / env `SPEC_WAVE_IMPLEMENT_CMD` — se ausente, avisa e sugere exemplos por agente: Claude Code, opencode, Codex, Copilot CLI, Kiro CLI, Qwen Code) e presença dos workflows.
+Sem flags. Roda um checklist de diagnóstico no repositório atual: 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. owner, `.spec-wave.json` (campos 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 + 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, avisa e sugere exemplos por agente: Claude Code, opencode, Codex, Copilot CLI, Kiro CLI, Qwen Code) e os workflows (presença + **versão da CLI fixada**, não `@latest`).
 
 > Saída: `✓` ok, `✗` problema confirmado, `!` não verificável (best-effort — falha de rede nunca derruba o doctor). **Exit 1** se houver algum `✗`. **Quando rodar:** no início de uma sessão de trabalho, ou sempre que aparecer um erro estranho (ex.: **404 ao criar issues** — causa típica: token sem acesso ao repo/org, que o doctor aponta). É o primeiro passo de troubleshooting — prefira-o a depurar `gh api` na mão.
 
@@ -238,43 +234,88 @@ Sem flags. Roda um checklist de diagnóstico no repositório atual: token GitHub
 
 > Avança a Story para a Etapa **👀 Code Review** com Status **Todo** (o Status reinicia ao trocar de etapa). Mesma regra do `task`: a **Etapa nunca retrocede** — se a Story já estiver em Code Review ou adiante, o comando apenas informa a Etapa atual. Use no fim do `implement` de uma Story, em vez de mutações GraphQL manuais.
 
+### `@spec-wave/cli move <n> <etapa>` — move QUALQUER item do board (comando LOCAL)
+| Flag/Arg | Tipo | Descrição |
+|----------|------|-----------|
+| `<n>` | string (obrigatório) | Número da issue, ex.: `8` ou `#8`. |
+| `<etapa>` | string (obrigatório) | Etapa de destino, com ou sem emoji, sem acento e em qualquer caixa: `"code review"`, `"Homologação"`, `"🎉 Done"`. |
+| `--status <valor>` | string | Valor do campo Status no destino: `Todo`, `In Progress` ou `Done` (default: `Todo`). |
+
+> Serve para **Feature, Story, Task, Bug e RFC** — é o comando a usar quando `story review` e `task start|done` não cobrem o movimento desejado (ex.: mover uma **Feature** para Homologação). Embute as mesmas guardas: a **Etapa nunca retrocede** (se o item já estiver adiante, o comando informa a Etapa atual e não faz nada) e **Spike** é recusado (sua Etapa é movida à mão). Um nome de etapa ambíguo (`"p"` casa com Priorizado e Plan) é recusado listando as candidatas.
+>
+> **Prefira `move` a `gh api graphql` manual.** Não existe escape hatch para retroceder — isso é a regra do fluxo, não uma limitação.
+
 ---
 
-## Crítica adversarial, idempotência e dependências (v0.7)
+## Crítica adversarial, decomposição em duas etapas e dependências
 
 ### Crítica adversarial (comentário 🔎)
 
-Após o `generate-plan` e **antes** da criação de issues no `decompose`, um segundo agente de IA critica os documentos procurando contradições, lacunas e riscos. O resultado vira um comentário **🔎 Crítica adversarial (spec-wave)** na issue.
+Depois do `generate-plan` e **antes** de qualquer issue ser criada no `decompose`, um segundo agente de IA audita o artefato procurando contradições com a spec, o plan e o `tech_context`. O resultado vira um comentário **🔎 Crítica adversarial (spec-wave)** na issue, com cabeçalho informando a **tentativa** e o **modelo** usados.
+
+A saída da crítica é **estruturada e validada por schema**: `severity` só aceita `grave` ou `menor`, e um payload fora do contrato **falha alto** em vez de virar um finding menor com JSON cru dentro. Se a crítica não conclui, ela **não** é registrada como aprovada.
+
+**A remediação depende de ONDE a crítica reprovou — são superfícies diferentes:**
 
-- Findings **graves** → o Action aplica a label **`spec-wave:critique-failed`**, que **bloqueia o `spec-wave:ready`** (o `validate` falha enquanto ela existir).
-- **Fluxo de resolução:** (1) leia o comentário 🔎 na issue; (2) corrija `spec.md`/`plan.md` (regenere com as labels ou edite e commite); (3) remova a label: `gh issue edit <n> --remove-label "spec-wave:critique-failed"`; (4) re-aplique `spec-wave:ready` para validar de novo.
-- Findings leves não bloqueiam — trate-os como revisão de qualidade.
+| Reprovou depois de | O que corrigir | Como retomar |
+|--------------------|----------------|--------------|
+| `generate-plan` | `plan.md` (ou a `spec.md` que o embasa) | corrija/regere → remova `spec-wave:critique-failed` → reaplique `spec-wave:ready` |
+| `decompose` (rascunho) | **`decomposition.md`** — os achados citam **`Story N`** e **`Task N.M`**, que são os títulos desse arquivo | edite o arquivo e commite → remova `spec-wave:critique-failed` → reaplique `spec-wave:decompose` (ele **critica o arquivo como está**, sem regerar) |
 
-### Documentos versionados (`spec-v2.md`, `plan-v3.md`…)
+> ⚠️ No contexto do `decompose`, os achados são sobre as **Stories propostas**, não sobre o `plan.md`. Corrigir o plan não influencia o rascunho já gravado — edite o `decomposition.md` diretamente. Foi exatamente essa confusão que fazia o ciclo não convergir.
 
-A primeira geração escreve `spec.md` e `plan.md` — a **v1**. Cada regeração **forçada** (label `spec-wave:force`) grava a **próxima versão** ao lado, sem tocar nas anteriores:
+- Findings **graves** no `decompose` → **nenhuma Story/Task é criada** e o Action **falha (exit 1)**, com a label `spec-wave:critique-failed`. Um pipeline bloqueado nunca fica verde.
+- Findings **menores** não bloqueiam — trate-os como revisão de qualidade.
+- **Escalada:** na tentativa 2 a crítica roda em `ai.escalationModel` (se configurado). Ao atingir `ai.maxCritiqueAttempts` (default 3), o fluxo aplica **`spec-wave:needs-human`**, comenta e **para** — sem chamar a IA de novo. Para retomar: corrija os documentos e remova **as duas** labels (`spec-wave:needs-human` e `spec-wave:critique-failed`).
+- Uma crítica **limpa** remove a `spec-wave:critique-failed` automaticamente e zera o contador de tentativas.
+
+### Decomposição em duas etapas (`decomposition.md`)
+
+O `decompose` **não cria issues direto**. São dois passos, com um artefato revisável no meio:
 
 ```
-docs/features/<slug>/
-  spec.md       ← v1
-  spec-v2.md    ← 1ª regeração forçada
-  spec-v3.md    ← 2ª regeração forçada  ⬅ spec ATUAL
-  plan.md       ⬅ plano ATUAL (spec e plan versionam independente)
+spec-wave:decompose
+  ├─ decomposition.md ausente  → gera via IA → commita → 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)
 ```
 
-**A maior versão é sempre o documento atual** — é ela que o `generate-plan` usa como contexto, que o `validate` valida, que o `decompose` lê e que o `implement` anexa. Uma regeração **sem** force sobrescreve essa versão atual (não volta para o `spec.md` original).
+O arquivo fica em **`docs/features/<slug>/decomposition.md`** (Feature) ou **`docs/rfcs/<slug>/decomposition.md`** (RFC). Formato:
 
-Ao mostrar os documentos ao usuário, use a versão atual; ofereça as anteriores só se ele quiser comparar. Nunca renomeie nem apague versões antigas por conta própria — elas são o histórico da Feature.
+```markdown
+# Decomposição — [FEATURE] Cadastro de Pedidos
+<!-- spec-wave:decomposition v1 issue=360 kind=stories -->
 
-### Guard de idempotência do decompose (`spec-wave:decomposed`)
+## Story 1 — visualizar meus pedidos
 
-O evento `labeled` pode redisparar (re-add da label, retry de runner). Para não duplicar Stories/Tasks, o `decompose` **pula** quando a issue já tem a label **`spec-wave:decomposed`** ou já tem sub-issues do tipo-alvo (`[STORY]` para Feature, `[TASK]` para RFC). Ao concluir com sucesso, o Action grava a label. Os workflows ainda usam `concurrency` por issue para serializar runs simultâneos.
+**User story:** Como cliente, quero visualizar meus pedidos, para acompanhar entregas
+**Depende de:** —
 
-**Para forçar um re-decompose**, adicione a label `spec-wave:force` junto com o gatilho:
-```bash
-gh issue edit <n> --add-label "spec-wave:force" --add-label "spec-wave:decompose"
+Descrição complementar (contexto, critérios de aceite).
+
+### Task 1.1 — criar endpoint GET /pedidos
+
+Corpo técnico.
 ```
-O comando então: (1) ignora os dois guards; (2) **fecha** as sub-issues abertas do tipo-alvo da decomposição anterior **e os filhos delas** (as Tasks de cada Story), comentando na issue o que foi fechado; (3) gera a nova decomposição. **É destrutivo** — se alguma Story já tiver saído de ✅ Ready, o comentário destaca quais, para você conferir se descartou trabalho em andamento. Confirme com o usuário antes de acionar em Features com desenvolvimento em curso.
+
+**Ao editar à mão:**
+- a **posição** manda, não o número escrito — inserir uma Story no meio sem renumerar funciona;
+- `**Depende de:**` usa referências **1-based** (`Story 1, Story 3`) ou `—`; apontar para si mesma ou para frente é **erro**, não filtro silencioso;
+- 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:** apague o arquivo e reaplique `spec-wave:decompose`.
+
+### Guard de idempotência do decompose (`spec-wave:decomposed`)
+
+O evento `labeled` pode redisparar (re-add da label, retry de runner). Para não duplicar Stories/Tasks, o `decompose` **pula** quando a issue já tem a label **`spec-wave:decomposed`** ou já tem sub-issues do tipo-alvo (`[STORY]` para Feature, `[TASK]` para RFC). O Action grava a label ao **aplicar** a decomposição. Os workflows ainda usam `concurrency` por issue para serializar runs simultâneos.
+
+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:** remova a label (`gh issue edit <n> --remove-label "spec-wave:decomposed"`), **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 (`Depende de: #N`)
 
@@ -297,12 +338,37 @@ Cada ação de IA (`spec`, `plan`, `decompose`, `critique`) pode usar um modelo
     "models": {
       "plan": "claude-opus-4-1",
       "critique": "claude-opus-4-1"
+    },
+    "escalationModel": "claude-opus-5",
+    "maxCritiqueAttempts": 3,
+    "modelAliases": {
+      "opus": "claude-opus-5",
+      "haiku": "claude-haiku-4-5"
     }
   }
 }
 ```
 
-Edite o bloco `ai` no `.spec-wave.json` (e commite) — o `doctor` mostra o provider, o modelo e os overrides de `ai.models` resolvidos.
+- `escalationModel` → modelo usado a partir da **segunda** tentativa da crítica.
+- `maxCritiqueAttempts` → quantas reprovas seguidas antes de exigir revisão humana (`spec-wave:needs-human`).
+- `modelAliases` → apelidos para a label **`spec-wave:model:<apelido>`**.
+
+**Precedência do modelo:** `SPEC_WAVE_MODEL` (env) → label `spec-wave:model:<apelido>` → escalada automática da crítica → `ai.models[ação]` → `ai.model` → default do provider.
+
+Edite o bloco `ai` no `.spec-wave.json` (e commite) — o `doctor` mostra o provider, o modelo, os apelidos, a escalada e os overrides resolvidos.
+
+### Override de modelo numa execução (`spec-wave:model:<apelido>`)
+
+Para reprocessar **uma issue difícil** num modelo mais forte sem editar a configuração do repositório inteiro:
+
+```bash
+# 1. Garanta o apelido em ai.modelAliases (uma vez, commitado)
+# 2. Aplique a label na issue e redispare o gatilho
+gh issue edit 360 --add-label "spec-wave:model:opus"
+gh issue edit 360 --add-label "spec-wave:decompose"
+```
+
+A label vale só para as execuções daquela issue e **vence a escalada automática** (é decisão humana explícita). Apelido desconhecido é ignorado com aviso; duas labels dessas na mesma issue = ambíguo, nenhuma vale.
 
 ### Teto de saída (`ai.maxTokens`) e truncamento
 
@@ -436,11 +502,7 @@ Inicia a geração da **especificação funcional** para uma Feature. É o **pri
    ```
 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. **Para regerar** (a spec já existe e o usuário quer outra versão): adicione `spec-wave:force` junto com o gatilho — o Action grava a **próxima versão** (`spec-v2.md`, `spec-v3.md`…) e preserva as anteriores; a nova passa a ser a spec atual. Sem o force, a versão atual é **sobrescrita** (edições manuais se perdem) — avise antes de acionar assim.
-   ```bash
-   gh issue edit <número> --add-label "spec-wave:force" --add-label "spec-wave:spec"
-   ```
-6. Próximo passo: gerar o plano técnico — mova para **📋 Plan** e use `/spec-wave plan <número>`.
+5. Próximo passo: gerar o plano técnico — mova para **📋 Plan** e use `/spec-wave plan <número>`.
 
 ---
 
@@ -459,8 +521,7 @@ O plano técnico segue o schema do RFC-002 §3.2: **Estratégia Técnica** (com
    ```
 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. **Para regerar**: adicione `spec-wave:force` junto com `spec-wave:plan` — grava `plan-v2.md`, `plan-v3.md`… preservando as anteriores. Sem o force, o plano atual é sobrescrito (confirme antes).
-7. Próximo passo: validar a Feature — mova para **✅ Ready** e use `/spec-wave ready <número>`.
+6. Próximo passo: validar a Feature — mova para **✅ Ready** e use `/spec-wave ready <número>`.
 
 ---
 
@@ -531,28 +592,39 @@ Valida que spec.md e plan.md estão completos e a Feature pode avançar.
    ```
 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 adicionará automaticamente `spec-wave:spec`. Informe o usuário para corrigir e tentar novamente.
-4. **Se a issue tiver a label `spec-wave:critique-failed`**, a validação falha de imediato: a crítica adversarial apontou contradições graves (comentário 🔎 na issue). Siga o fluxo de resolução da seção *Crítica adversarial*: corrigir os documentos → 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 as Stories."
+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)."
 
 ---
 
 ### `/spec-wave decompose <número-da-issue>`
 
-Decompõe automaticamente. Aplica-se a **dois tipos**:
-- **Feature** → gera **Stories** (cada uma com suas **Tasks**), a partir de `spec.md` + `plan.md`.
-- **RFC** → gera **Tasks diretamente** (sem Stories), a partir da descrição do RFC.
+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.
 
 Para qualquer outro tipo (Spike, Bug, Story, Task, …) o Action **recusa** e comenta.
 
 **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. Adicione a label de decomposição:
+2. **Etapa 1 — gerar o rascunho:**
    ```bash
    gh issue edit <número> --add-label "spec-wave:decompose"
    ```
-3. Informe: "Decomposição iniciada — Feature gera Stories+Tasks; RFC gera Tasks."
-4. Após a conclusão, as issues filhas aparecerão como comentário na issue pai, junto com o comentário 🔎 da crítica adversarial. 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 geradas 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.
-5. A issue recebe a label `spec-wave:decomposed` (guard de idempotência): rodar de novo **não** duplica as issues. Para re-decompor, adicione `spec-wave:force` junto com o gatilho — isso **fecha** a decomposição anterior antes de gerar a nova (veja *Guard de idempotência*; confirme com o usuário, é destrutivo).
+   Informe: "Rascunho iniciado — vai commitar `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`), commite 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):
+   ```bash
+   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.
+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.
 
 ---
 
@@ -718,12 +790,16 @@ Audita um Pull Request e corrige automaticamente os problemas encontrados — se
 docs/
   features/
     <slug-da-feature>/
-      spec.md       ← gerado quando spec-wave:spec é adicionado (1º) = v1
-      spec-v2.md    ← regeração forçada (spec-wave:force); v1 preservada
-      plan.md       ← gerado quando spec-wave:plan é adicionado (2º, usa a spec ATUAL) = v1
-      plan-v2.md    ← regeração forçada do plano
+      spec.md            ← gerado quando spec-wave:spec é adicionado (1º)
+      plan.md            ← gerado quando spec-wave:plan é adicionado (2º, usa a spec)
+      decomposition.md   ← rascunho gerado quando spec-wave:decompose é adicionado (3º).
+                            REVISÁVEL e EDITÁVEL à mão; as issues só nascem com
+                            spec-wave:decompose-apply
+  rfcs/
+    <slug-do-rfc>/
+      decomposition.md   ← mesmo papel, com "## Task N" (RFC não usa spec/plan)
 ```
 
-A **maior versão de cada tipo é o documento atual** (aqui: `spec-v2.md` e `plan-v2.md`) — veja *Documentos versionados*.
-
 O slug é gerado a partir do título da issue: `[FEATURE] Cadastro de Pedidos com PIX` → `cadastro-de-pedidos-com-pix`
+
+> ⚠️ O slug vem do **título**. Renomear a Feature entre o rascunho e o apply muda o diretório e o `decomposition.md` antigo fica órfão — o apply reclama que não encontrou o rascunho.

package/src/templates/workflows/code-review.yml

@@ -24,7 +24,7 @@ jobs:
           node-version: '24'
 
       - name: Move Feature to Code Review
-        run: npx @spec-wave/cli@latest code-review --pr-number ${{ github.event.pull_request.number }}
+        run: npx @spec-wave/cli@{{CLI_VERSION}} code-review --pr-number ${{ github.event.pull_request.number }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           PROJECT_TOKEN: ${{ secrets.GH_PROJECT_TOKEN }}

package/src/templates/workflows/decompose.yml

@@ -4,8 +4,9 @@ on:
   issues:
     types: [labeled]
 
-# O evento `labeled` pode redisparar (re-add da label, retry de runner):
-# o concurrency serializa runs da mesma issue e o guard de idempotência
+# O evento `labeled` pode redisparar (re-add da label, retry de runner). O
+# concurrency serializa runs da mesma issue — inclusive um `decompose-apply`
+# enfileirado atrás de um `decompose` — e o guard de idempotência
 # (label spec-wave:decomposed) descarta o run enfileirado.
 concurrency:
   group: spec-wave-decompose-${{ github.event.issue.number }}
@@ -13,23 +14,36 @@ concurrency:
 
 jobs:
   decompose:
+    # Duas etapas, duas labels:
+    #  • spec-wave:decompose       → grava/re-critica docs/**/decomposition.md
+    #  • spec-wave:decompose-apply → cria as Stories/Tasks a partir do rascunho
+    # O `[RFC]` no título também dispara: o caminho RFC → Tasks existe na CLI
+    # desde sempre, mas era inalcançável porque o filtro exigia `[FEATURE]`.
     if: >
-      github.event.label.name == 'spec-wave:decompose' &&
-      contains(github.event.issue.title, '[FEATURE]')
+      (github.event.label.name == 'spec-wave:decompose' ||
+       github.event.label.name == 'spec-wave:decompose-apply') &&
+      (contains(github.event.issue.title, '[FEATURE]') ||
+       contains(github.event.issue.title, '[RFC]'))
     runs-on: ubuntu-latest
     permissions:
       issues: write
-      contents: read
+      # A etapa de rascunho commita docs/**/decomposition.md no branch default.
+      contents: write
 
     steps:
       - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
 
       - uses: actions/setup-node@v4
         with:
           node-version: '24'
 
       - name: Decompose into Stories and Tasks
-        run: npx @spec-wave/cli@latest decompose --issue-number ${{ github.event.issue.number }}
+        run: >
+          npx @spec-wave/cli@{{CLI_VERSION}} decompose
+          --issue-number ${{ github.event.issue.number }}
+          ${{ github.event.label.name == 'spec-wave:decompose-apply' && '--apply' || '' }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           PROJECT_TOKEN: ${{ secrets.GH_PROJECT_TOKEN }}

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

@@ -28,7 +28,7 @@ jobs:
           node-version: '24'
 
       - name: Generate plan.md
-        run: npx @spec-wave/cli@latest generate-plan --issue-number ${{ github.event.issue.number }}
+        run: npx @spec-wave/cli@{{CLI_VERSION}} generate-plan --issue-number ${{ github.event.issue.number }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

package/src/templates/workflows/generate-spec.yml

@@ -28,7 +28,7 @@ jobs:
           node-version: '24'
 
       - name: Generate spec.md
-        run: npx @spec-wave/cli@latest generate-spec --issue-number ${{ github.event.issue.number }}
+        run: npx @spec-wave/cli@{{CLI_VERSION}} generate-spec --issue-number ${{ github.event.issue.number }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

package/src/templates/workflows/qa.yml

@@ -25,7 +25,7 @@ jobs:
           node-version: '24'
 
       - name: Move Feature to QA
-        run: npx @spec-wave/cli@latest qa --pr-number ${{ github.event.pull_request.number }}
+        run: npx @spec-wave/cli@{{CLI_VERSION}} qa --pr-number ${{ github.event.pull_request.number }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           PROJECT_TOKEN: ${{ secrets.GH_PROJECT_TOKEN }}

package/src/templates/workflows/validate.yml

@@ -26,7 +26,7 @@ jobs:
           node-version: '24'
 
       - name: Validate spec and plan
-        run: npx @spec-wave/cli@latest validate --issue-number ${{ github.event.issue.number }}
+        run: npx @spec-wave/cli@{{CLI_VERSION}} validate --issue-number ${{ github.event.issue.number }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           GITHUB_REPOSITORY: ${{ github.repository }}

package/src/lib/feature-docs.mjs

@@ -1,89 +0,0 @@
-// Resolução dos documentos versionados de uma Feature (docs/features/<slug>/).
-//
-// A primeira geração escreve `spec.md`/`plan.md` (= v1). Cada regeração
-// FORÇADA (flag --force ou label spec-wave:force) cria a próxima versão em vez
-// de sobrescrever: `spec-v2.md`, `spec-v3.md`, … O documento ATUAL é sempre a
-// MAIOR versão — é ele que validate/generate-plan/decompose/implement leem, e
-// é ele que uma regeração sem force sobrescreve.
-import { existsSync, readdirSync } from 'node:fs';
-import path from 'node:path';
-
-/**
- * Versão de um arquivo de documento (função PURA).
- * `spec.md` → 1; `spec-v2.md` → 2. Outro nome → null.
- *
- * @param {string} filename nome do arquivo (sem diretório)
- * @param {string} base 'spec' ou 'plan'
- * @returns {number|null}
- */
-export function parseDocVersion(filename, base) {
-  const match = new RegExp(`^${base}(?:-v(\\d+))?\\.md$`).exec(String(filename ?? ''));
-  if (!match) return null;
-  return match[1] ? parseInt(match[1], 10) : 1;
-}
-
-/**
- * Documento ATUAL entre os arquivos dados: o de maior versão (função PURA).
- * Empate (raro: `spec.md` e `spec-v1.md` coexistindo) resolve pelo sufixado,
- * para o resultado ser determinístico.
- *
- * @param {string[]} filenames
- * @param {string} base 'spec' ou 'plan'
- * @returns {{ file: string, version: number }|null}
- */
-export function pickLatestDoc(filenames, base) {
-  const found = (filenames || [])
-    .map(file => ({ file, version: parseDocVersion(file, base), suffixed: /-v\d+\.md$/.test(file) }))
-    .filter(entry => entry.version !== null)
-    .sort((a, b) => (a.version - b.version) || (Number(a.suffixed) - Number(b.suffixed)));
-  if (found.length === 0) return null;
-  const { file, version } = found[found.length - 1];
-  return { file, version };
-}
-
-/**
- * Nome do arquivo da PRÓXIMA versão (função PURA): `spec.md` quando ainda não
- * há nenhum, `spec-v<N+1>.md` a partir da maior versão existente.
- *
- * @param {string[]} filenames
- * @param {string} base 'spec' ou 'plan'
- * @returns {string}
- */
-export function nextDocName(filenames, base) {
-  const latest = pickLatestDoc(filenames, base);
-  return latest ? `${base}-v${latest.version + 1}.md` : `${base}.md`;
-}
-
-// Nomes de arquivo do diretório da feature ([] se ele ainda não existe).
-function readDir(featureDir) {
-  return featureDir && existsSync(featureDir) ? readdirSync(featureDir) : [];
-}
-
-/**
- * Caminho do documento ATUAL (maior versão) — null se nenhum existe.
- *
- * @returns {{ path: string, version: number }|null}
- */
-export function resolveDoc(featureDir, base) {
-  const latest = pickLatestDoc(readDir(featureDir), base);
-  return latest ? { path: path.join(featureDir, latest.file), version: latest.version } : null;
-}
-
-/**
- * Caminho onde a geração deve escrever.
- * - `force: true`  → próxima versão (nunca sobrescreve nada);
- * - `force: false` → o documento atual (sobrescreve), ou `<base>.md` no 1º run.
- *
- * @returns {{ path: string, version: number, isNewVersion: boolean }}
- */
-export function resolveWritePath(featureDir, base, { force = false } = {}) {
-  const files = readDir(featureDir);
-  if (!force) {
-    const latest = pickLatestDoc(files, base);
-    return latest
-      ? { path: path.join(featureDir, latest.file), version: latest.version, isNewVersion: false }
-      : { path: path.join(featureDir, `${base}.md`), version: 1, isNewVersion: false };
-  }
-  const name = nextDocName(files, base);
-  return { path: path.join(featureDir, name), version: parseDocVersion(name, base), isNewVersion: true };
-}

package/src/lib/force.mjs

@@ -1,34 +0,0 @@
-// Detecção do modo "force" (re-executar a etapa ignorando os guards).
-//
-// Os comandos generate-spec/generate-plan/decompose rodam dentro de Actions
-// disparadas por label — a linha de comando do workflow é fixa e não tem como
-// receber uma flag. Por isso o force chega de duas formas equivalentes:
-//   • label `spec-wave:force` na issue (fluxo normal, pelo board);
-//   • flag `--force` (execução local/manual da CLI).
-// A label é CONSUMIDA pelo run que a leu (ver consumeForceLabel), senão ela
-// ficaria pendurada e forçaria silenciosamente todos os runs seguintes.
-import { LABEL_FORCE } from '../config.mjs';
-import { removeLabel } from '../api/github-rest.mjs';
-
-/**
- * Diz se a etapa deve ser re-executada ignorando os guards (função PURA).
- *
- * @param {object} [params]
- * @param {Array<string|{name: string}>} [params.labels] labels da issue
- * @param {boolean} [params.flag] valor da flag `--force` da CLI
- * @returns {boolean}
- */
-export function isForced({ labels = [], flag = false } = {}) {
-  if (flag) return true;
-  return (labels || [])
-    .map(l => (typeof l === 'string' ? l : l?.name))
-    .includes(LABEL_FORCE);
-}
-
-/**
- * Remove a label `spec-wave:force` da issue. Best-effort: nunca lança — deixar
- * de consumir a label é um incômodo, não um motivo para derrubar o comando.
- */
-export async function consumeForceLabel(token, owner, repo, issueNumber) {
-  await removeLabel(token, owner, repo, issueNumber, LABEL_FORCE).catch(() => {});
-}