@spec-wave/cli 0.26.0 → 0.28.0

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: