@spec-wave/cli 0.26.0 → 0.27.0

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

@@ -31,7 +31,7 @@ Toda a CLI é invocada como `npx @spec-wave/cli@latest <comando>`.
    - **Action:** aplique a label de gatilho (`spec-wave:spec`, `spec-wave:plan`, `spec-wave:decompose`);
    - **Local:** `npx @spec-wave/cli@latest generate-spec|generate-plan|decompose --issue-number <n>` na sua sessão.
 
-   O modo é detectado pelo ambiente (`GITHUB_ACTIONS`), sem flag. Os dois geram, commitam, fazem push, comentam na issue e sincronizam o board — o board é a fonte de verdade independentemente de onde rodou. Local exige a chave de IA no seu ambiente e um `.spec-wave.json`. Exceção à regra: revisar/melhorar um documento já gerado.
+   O modo é detectado pelo ambiente (`GITHUB_ACTIONS`), sem flag. Os dois geram, abrem um **Pull Request** com o documento, comentam na issue e sincronizam o board — o board é a fonte de verdade independentemente de onde rodou. Local exige a chave de IA no seu ambiente e um `.spec-wave.json`. Exceção à regra: revisar/melhorar um documento já gerado.
 2. **Nunca crie Story ou Task avulsa.** Elas nascem do `decompose`, já em **✅ Ready** e vinculadas ao pai. Criadas à mão caem em 📥 Backlog e **não aparecem em tela nenhuma** da UI (o inbox do PM lista Features, a tela do Dev lê 🚧 Desenvolvimento, a fila do TL lê ✅ Ready).
 3. **Nunca use `gh issue create`** para work items — não adiciona ao Project, a issue fica sem Etapa e some das telas. Use `npx @spec-wave/cli@latest issue`.
 4. **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 `move`, `task start|done` e `story review` a mutações GraphQL manuais — os comandos embutem essas regras.
@@ -88,7 +88,7 @@ Depois do `generate-plan` e **antes** de qualquer issue nascer no `decompose`, u
 | Reprovou depois de | O que corrigir | Como retomar |
 |--------------------|----------------|--------------|
 | `generate-plan` | `plan.md` (ou a `spec.md` que o embasa) | corrija/regere → remova `critique-failed` → reaplique `spec-wave:ready` |
-| `decompose` | **`decomposition.md`** — os achados citam `Story N` / `Task N.M`, títulos **desse arquivo** | edite e commite → remova `critique-failed` → reaplique `spec-wave:decompose` (critica o arquivo como está, sem regerar) |
+| `decompose` | **`decomposition.md`** — os achados citam `Story N` / `Task N.M`, títulos **desse arquivo** | edite no Pull Request → remova `critique-failed` → reaplique `spec-wave:decompose` (critica o arquivo como está, sem regerar) |
 
 > ⚠️ No `decompose` os achados são sobre as **Stories propostas**, não sobre o `plan.md`. Corrigir o plan não muda o rascunho já gravado.
 

package/src/templates/skill/SKILL.md

@@ -86,7 +86,7 @@ O `run` decide o passo pelo estado da issue (documentos existentes + labels), re
 
 ## Regra fundamental
 
-**Nunca gere `spec.md` ou `plan.md` diretamente.** Acione o passo — a label (modo actions) ou o `run` (modo local) — e deixe o spec-wave gerar o arquivo. Isso garante que o arquivo seja commitado no repositório e referenciado na issue.
+**Nunca gere `spec.md` ou `plan.md` diretamente.** Acione o passo — a label (modo actions) ou o `run` (modo local) — e deixe o spec-wave gerar o arquivo. Isso garante que o arquivo chegue à main por **Pull Request** e seja referenciado na issue.
 
 Exceção: se o usuário pedir explicitamente para revisar ou melhorar um documento já gerado, use o Write tool para editar o arquivo local.
 
@@ -294,7 +294,7 @@ A saída da crítica é **estruturada e validada por schema**: `severity` só ac
 | Reprovou depois de | O que corrigir | Como retomar |
 |--------------------|----------------|--------------|
 | `generate-plan` | `plan.md` (ou a `spec.md` que o embasa) | corrija → remova `spec-wave:critique-failed` → reaplique **`spec-wave:critique`** (re-critica o arquivo como está). `spec-wave:ready` apenas valida, **não** re-critica; e `spec-wave:plan` **regera** o plano, descartando a correção. |
-| `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) |
+| `decompose` (rascunho) | **`decomposition.md`** — os achados citam **`Story N`** e **`Task N.M`**, que são os títulos desse arquivo | edite o arquivo **no Pull Request** → remova `spec-wave:critique-failed` → reaplique `spec-wave:decompose` (ele **critica o arquivo como está**, sem regerar) |
 
 > ⚠️ 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.
 
@@ -309,7 +309,7 @@ O `decompose` **não cria issues direto**. São dois passos, com um artefato rev
 
 ```
 spec-wave:decompose
-  ├─ decomposition.md ausente  → gera via IA → commita → critica
+  ├─ 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"
@@ -341,7 +341,7 @@ Corpo técnico.
 - 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:** apague o arquivo e reaplique `spec-wave:decompose`.
+- **para gerar outro rascunho do zero:** feche o Pull Request e apague a branch `spec-wave/<n>-decompose` (ou apague o arquivo, se já mergeado) e reaplique `spec-wave:decompose`.
 
 ### Guard de idempotência do decompose (`spec-wave:decomposed`)
 
@@ -649,10 +649,10 @@ Para qualquer outro tipo (Spike, Bug, Story, Task, …) o Action **recusa** e co
    ```bash
    gh issue edit <número> --add-label "spec-wave:decompose"
    ```
-   Informe: "Rascunho iniciado — vai commitar `decomposition.md` e passar pela crítica. **Nenhuma issue é criada nesta etapa.**"
+   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`), commite e reaplique `spec-wave:decompose` — o arquivo é criticado como está, sem ser regerado.
+   - **`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):
    ```bash
@@ -728,7 +728,7 @@ Gera o **`bug.md`** de um defeito: `docs/bugs/<slug>/bug.md`, com reprodução,
 
 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 e commita o arquivo.
+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`.
 

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

@@ -18,7 +18,15 @@ jobs:
     # Modo de execução: `spec-wave mode local` cria a variável de repositório
     # SPEC_WAVE_EXECUTION=local e este job passa a ser PULADO — run aparece como
     # skipped e job que não roda não é faturado. `mode actions` remove a variável.
-    if: vars.SPEC_WAVE_EXECUTION != 'local'
+    # PR de DOCUMENTO não é PR de implementação. O fluxo publica spec.md,
+    # plan.md, bug.md e decomposition.md em branches `spec-wave/*`, e deixar este
+    # workflow rodar em cima delas move o board por um PR que não implementa
+    # nada. Nos Actions um PR aberto pelo GITHUB_TOKEN não dispara workflow, mas
+    # um aberto no modo local (ou via GH_PR_TOKEN) dispara.
+    #
+    # A guarda cobre também `spec-wave/update-v*`, do `update --branch` — que
+    # tampouco implementa uma Story.
+    if: vars.SPEC_WAVE_EXECUTION != 'local' && !startsWith(github.event.pull_request.head.ref, 'spec-wave/')
     runs-on: ubuntu-latest
     permissions:
       issues: read
@@ -44,7 +52,10 @@ jobs:
   move:
     needs: resolve
     # PR sem vínculo explícito não resolve Feature nenhuma — e não move nada.
-    if: vars.SPEC_WAVE_EXECUTION != 'local' && needs.resolve.outputs.feature != ''
+    if: >
+      vars.SPEC_WAVE_EXECUTION != 'local' &&
+      !startsWith(github.event.pull_request.head.ref, 'spec-wave/') &&
+      needs.resolve.outputs.feature != ''
     runs-on: ubuntu-latest
     # MESMO namespace do decompose.yml: um `decompose-apply` em curso na Feature
     # segura este job na fila em vez de disputar a subárvore com ele. Foi essa

package/src/templates/workflows/critique.yml

@@ -35,7 +35,7 @@ jobs:
     permissions:
       issues: write
       # read: a crítica LÊ o plan.md do checkout e não escreve arquivo nenhum —
-      # ao contrário do generate-plan, que commita o documento gerado.
+      # ao contrário do generate-plan, que publica o documento gerado.
       contents: read
 
     steps:

package/src/templates/workflows/decompose.yml

@@ -16,7 +16,7 @@ on:
 # proteção.
 #
 # generate-spec, generate-plan e generate-bug usam o MESMO namespace por outro
-# motivo: os quatro commitam e empurram na branch default, e este aqui ainda lê
+# motivo: os quatro publicam documentos em branch própria + Pull Request, e este aqui ainda lê
 # o spec.md/plan.md do checkout — que uma geração concorrente estaria trocando
 # debaixo dele.
 concurrency:
@@ -56,8 +56,18 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       issues: write
-      # A etapa de rascunho commita docs/**/decomposition.md no branch default.
       contents: write
+      # `contents: write` continua necessário: o commit vai por Git Data API
+      # (createTree/createCommit/createRef), que é autorizada por ele. O que
+      # mudou foi o DESTINO — branch própria do documento, nunca a default.
+      #
+      # `pull-requests: write` é a permissão NOVA deste fluxo. Sem ela o commit
+      # é criado e o PR não, e o documento fica numa branch que ninguém vê.
+      #
+      # Atenção: o GITHUB_TOKEN só abre PR se "Allow GitHub Actions to create and
+      # approve pull requests" estiver ligado (Settings → Actions → General) —
+      # desligado por padrão em muitas organizações. `GH_PR_TOKEN` é a saída.
+      pull-requests: write
 
     steps:
       - uses: actions/checkout@v4
@@ -78,6 +88,7 @@ jobs:
           ${{ github.event.label.name == 'spec-wave:decompose-apply' && '--apply' || '' }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_PR_TOKEN: ${{ secrets.GH_PR_TOKEN }}
           PROJECT_TOKEN: ${{ secrets.GH_PROJECT_TOKEN }}
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
           CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}

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

@@ -5,12 +5,11 @@ on:
     types: [labeled]
 
 # Trava por ITEM, no mesmo namespace de generate-spec/plan/decompose e do job
-# `move` do code-review.yml. Este job GRAVA no repositório (commit + pull
-# --rebase + push na branch default) e escreve o relatório de uso no comentário
-# da issue com leitura-modificação-escrita; a trava impede que outro job do
-# spec-wave na MESMA issue faça as duas coisas ao mesmo tempo. Entre issues
-# diferentes a disputa é resolvida no laço de repetição de push do
-# lib/flow-run.mjs — serializar o repositório inteiro mataria a vazão.
+# `move` do code-review.yml. Este job PUBLICA um documento (branch própria +
+# Pull Request) e escreve o relatório de uso no comentário da issue com
+# leitura-modificação-escrita; a trava impede que outro job do spec-wave na
+# MESMA issue faça as duas coisas ao mesmo tempo. Entre issues diferentes não há
+# mais disputa: cada documento tem a sua branch.
 concurrency:
   # Um run que NÃO vai fazer nada não pode disputar este grupo.
   #
@@ -42,6 +41,17 @@ jobs:
     permissions:
       issues: write
       contents: write
+      # `contents: write` continua necessário: o commit vai por Git Data API
+      # (createTree/createCommit/createRef), que é autorizada por ele. O que
+      # mudou foi o DESTINO — branch própria do documento, nunca a default.
+      #
+      # `pull-requests: write` é a permissão NOVA deste fluxo. Sem ela o commit
+      # é criado e o PR não, e o documento fica numa branch que ninguém vê.
+      #
+      # Atenção: o GITHUB_TOKEN só abre PR se "Allow GitHub Actions to create and
+      # approve pull requests" estiver ligado (Settings → Actions → General) —
+      # desligado por padrão em muitas organizações. `GH_PR_TOKEN` é a saída.
+      pull-requests: write
 
     steps:
       - uses: actions/checkout@v4
@@ -59,6 +69,7 @@ jobs:
         run: spec-wave generate-bug --issue-number ${{ github.event.issue.number }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_PR_TOKEN: ${{ secrets.GH_PR_TOKEN }}
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
           CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
           OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}

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

@@ -7,18 +7,19 @@ on:
 # Trava por ITEM, no mesmo namespace do decompose.yml e do job `move` do
 # code-review.yml. Duas razões:
 #
-#  1. spec, plan e decompose GRAVAM no repositório (commit + pull --rebase +
-#     push na branch default). Em namespaces separados, aplicar `spec-wave:spec`
-#     e `spec-wave:plan` juntos na mesma Feature põe os dois para rodar em
-#     paralelo — e o plan lê o spec.md do checkout, então pode gerar o plano
-#     sem a spec, em silêncio (generate-plan.mjs:160-169).
+#  1. spec, plan e decompose PUBLICAM documentos (branch própria + Pull
+#     Request). Em namespaces separados, aplicar `spec-wave:spec` e
+#     `spec-wave:plan` juntos na mesma Feature põe os dois para rodar em
+#     paralelo — e o plan lê a spec, que ainda estaria num PR sem merge.
+#     Hoje isso é recusa explícita, não plano gerado sem spec; ainda assim,
+#     serializar evita queimar um run para descobrir isso.
 #  2. Os dois escrevem o relatório de uso no MESMO comentário da issue, com
 #     leitura-modificação-escrita (usage-report.mjs:152-160). Em paralelo, um
 #     sobrescreve o custo registrado pelo outro.
 #
 # Continua sendo por issue de propósito: serializar o repositório inteiro
-# mataria a vazão, e a disputa entre issues diferentes é resolvida onde ela
-# acontece — no laço de repetição de push do lib/flow-run.mjs.
+# mataria a vazão. A disputa ENTRE issues diferentes deixou de existir — cada
+# documento tem branch própria, e o commit vai por API.
 concurrency:
   # Um run que NÃO vai fazer nada não pode disputar este grupo.
   #
@@ -50,6 +51,17 @@ jobs:
     permissions:
       issues: write
       contents: write
+      # `contents: write` continua necessário: o commit vai por Git Data API
+      # (createTree/createCommit/createRef), que é autorizada por ele. O que
+      # mudou foi o DESTINO — branch própria do documento, nunca a default.
+      #
+      # `pull-requests: write` é a permissão NOVA deste fluxo. Sem ela o commit
+      # é criado e o PR não, e o documento fica numa branch que ninguém vê.
+      #
+      # Atenção: o GITHUB_TOKEN só abre PR se "Allow GitHub Actions to create and
+      # approve pull requests" estiver ligado (Settings → Actions → General) —
+      # desligado por padrão em muitas organizações. `GH_PR_TOKEN` é a saída.
+      pull-requests: write
 
     steps:
       - uses: actions/checkout@v4
@@ -67,6 +79,7 @@ jobs:
         run: spec-wave generate-plan --issue-number ${{ github.event.issue.number }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_PR_TOKEN: ${{ secrets.GH_PR_TOKEN }}
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
           CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
           OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}

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

@@ -7,18 +7,19 @@ on:
 # Trava por ITEM, no mesmo namespace do decompose.yml e do job `move` do
 # code-review.yml. Duas razões:
 #
-#  1. spec, plan e decompose GRAVAM no repositório (commit + pull --rebase +
-#     push na branch default). Em namespaces separados, aplicar `spec-wave:spec`
-#     e `spec-wave:plan` juntos na mesma Feature põe os dois para rodar em
-#     paralelo — e o plan lê o spec.md do checkout, então pode gerar o plano
-#     sem a spec, em silêncio (generate-plan.mjs:160-169).
+#  1. spec, plan e decompose PUBLICAM documentos (branch própria + Pull
+#     Request). Em namespaces separados, aplicar `spec-wave:spec` e
+#     `spec-wave:plan` juntos na mesma Feature põe os dois para rodar em
+#     paralelo — e o plan lê a spec, que ainda estaria num PR sem merge.
+#     Hoje isso é recusa explícita, não plano gerado sem spec; ainda assim,
+#     serializar evita queimar um run para descobrir isso.
 #  2. Os dois escrevem o relatório de uso no MESMO comentário da issue, com
 #     leitura-modificação-escrita (usage-report.mjs:152-160). Em paralelo, um
 #     sobrescreve o custo registrado pelo outro.
 #
 # Continua sendo por issue de propósito: serializar o repositório inteiro
-# mataria a vazão, e a disputa entre issues diferentes é resolvida onde ela
-# acontece — no laço de repetição de push do lib/flow-run.mjs.
+# mataria a vazão. A disputa ENTRE issues diferentes deixou de existir — cada
+# documento tem branch própria, e o commit vai por API.
 concurrency:
   # Um run que NÃO vai fazer nada não pode disputar este grupo.
   #
@@ -50,6 +51,17 @@ jobs:
     permissions:
       issues: write
       contents: write
+      # `contents: write` continua necessário: o commit vai por Git Data API
+      # (createTree/createCommit/createRef), que é autorizada por ele. O que
+      # mudou foi o DESTINO — branch própria do documento, nunca a default.
+      #
+      # `pull-requests: write` é a permissão NOVA deste fluxo. Sem ela o commit
+      # é criado e o PR não, e o documento fica numa branch que ninguém vê.
+      #
+      # Atenção: o GITHUB_TOKEN só abre PR se "Allow GitHub Actions to create and
+      # approve pull requests" estiver ligado (Settings → Actions → General) —
+      # desligado por padrão em muitas organizações. `GH_PR_TOKEN` é a saída.
+      pull-requests: write
 
     steps:
       - uses: actions/checkout@v4
@@ -67,6 +79,7 @@ jobs:
         run: spec-wave generate-spec --issue-number ${{ github.event.issue.number }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_PR_TOKEN: ${{ secrets.GH_PR_TOKEN }}
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
           CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
           OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}

package/src/templates/workflows/qa.yml

@@ -13,8 +13,21 @@ jobs:
     # Modo de execução: `spec-wave mode local` cria a variável de repositório
     # SPEC_WAVE_EXECUTION=local e este job passa a ser PULADO — run aparece como
     # skipped e job que não roda não é faturado. `mode actions` remove a variável.
+    # PR de DOCUMENTO não é PR de implementação. O fluxo publica spec.md,
+    # plan.md, bug.md e decomposition.md em branches `spec-wave/*`, e deixar este
+    # workflow rodar em cima delas move o board por um PR que não implementa
+    # nada. Nos Actions um PR aberto pelo GITHUB_TOKEN não dispara workflow, mas
+    # um aberto no modo local (ou via GH_PR_TOKEN) dispara.
+    #
+    # A guarda cobre também `spec-wave/update-v*`, do `update --branch` — que
+    # tampouco implementa uma Story.
+    #
+    # Aqui a guarda é INDISPENSÁVEL, não defensiva: `pull_request_review`
+    # dispara por uma aprovação HUMANA, independentemente de quem abriu o
+    # PR. Aprovar o PR da spec moveria a Feature para 🧪 QA.
     if: >
       vars.SPEC_WAVE_EXECUTION != 'local' &&
+      !startsWith(github.event.pull_request.head.ref, 'spec-wave/') &&
       github.event.review.state == 'approved'
     runs-on: ubuntu-latest
     permissions: