@spec-wave/cli 0.18.1 → 0.19.0

package/src/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "spec-wave",
   "displayName": "Spec Wave",
-  "version": "0.18.1",
+  "version": "0.19.0",
   "description": "Fluxo spec-driven no GitHub (RFC-001): Projects v2, labels de gatilho, spec/plan gerados por Action, decomposição em duas etapas e implementação orientada a Stories/Tasks.",
   "author": {
     "name": "Astratech",

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

@@ -43,6 +43,34 @@ npx @spec-wave/cli@latest move <n> <etapa> [--status <valor>]
 3. Se o comando recusar por Etapa já adiante, apenas informe a Etapa atual — não tente contornar via `gh api graphql`.
 4. Se recusar por ambiguidade, escolha entre as candidatas listadas e rode de novo.
 
+## Quando a automação errou: `repair-stage`
+
+`move` não retrocede — e isso vale inclusive quando quem errou foi a automação
+(uma corrida entre workflows já pôs Stories em `🎉 Done` no instante em que
+nasceram). Para esse caso existe um comando **separado**:
+
+```bash
+npx @spec-wave/cli@latest repair-stage <issues> <etapa> --yes --reason "<motivo>"
+```
+
+| Flag/Arg | Descrição |
+|----------|-----------|
+| `<issues>` | **Obrigatório.** Uma ou várias: `529` ou `529,530,531`. |
+| `<etapa>` | **Obrigatório.** A Etapa **correta** — pode ser anterior à atual. |
+| `--reason` | **Obrigatório.** Vai para o comentário de auditoria na issue. |
+| `--yes` | **Obrigatório.** Confirma o reparo. |
+| `--status` | Também corrige o Status. Default: não mexe. |
+| `--dry-run` | Mostra o que seria reparado, sem alterar nada. |
+
+**Nunca use este comando como atalho para o fluxo normal.** Ele existe para
+desfazer erro de automação, e cada uso deixa um comentário público na issue
+dizendo quem reparou, de onde para onde e por quê. Se o usuário pedir para
+"voltar o card", pergunte **por que** antes: se a resposta for "mudou o escopo"
+ou "o time decidiu revisar de novo", isso é fluxo, não reparo — e a resposta
+certa é conversar sobre a etapa correta, não retroceder o board.
+
+Antes de reparar, rode com `--dry-run` e mostre o resultado ao usuário.
+
 ## Quando preferir outra skill
 
 | Caso | Skill |
@@ -50,3 +78,4 @@ npx @spec-wave/cli@latest move <n> <etapa> [--status <valor>]
 | Task iniciando ou concluindo | **task** (`start` / `done`) |
 | Story indo para Code Review | **story** (`review`) |
 | Feature avançando após todas as Stories em review, ou indo para QA/Homologação/Deploy | **move** (esta) |
+| Desfazer Etapa errada gravada pela automação | **move** (esta), via `repair-stage` |

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

@@ -56,3 +56,16 @@ 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.

package/src/plugin/skills/spec/model-prompt.critique.md

@@ -0,0 +1,58 @@
+---
+name: critique-spec
+action: critique
+description: Critério da crítica adversarial da spec.md contra a issue de origem e as regras de negócio declaradas.
+tools: [Read, Glob, Grep]
+maxTurns: 20
+verifiers: 3
+lenses:
+  - "completude — algum comportamento pedido na issue não tem regra, fluxo nem critério de aceite?"
+  - "contradição interna — duas partes da spec decidem coisas incompatíveis sobre o mesmo caso?"
+  - "decisão fantasma — a spec afirma como algo funciona onde na verdade existe uma pergunta em aberto?"
+---
+
+# Crítica adversarial do spec.md
+
+Você audita a `spec.md` — a especificação FUNCIONAL, escrita antes do plano técnico. Seu papel é
+encontrar problemas, não elogiar.
+
+Diferente da crítica do plano, aqui não há um documento "de cima" contra o qual conferir linha a
+linha: a referência é a issue de origem, as regras de negócio citadas e a coerência da spec consigo
+mesma.
+
+## O que caracteriza um achado
+
+- **Requisito da issue sem cobertura** — comportamento pedido que não virou regra, fluxo nem
+  critério de aceite.
+- **Contradição interna** — duas seções decidindo diferente sobre o mesmo caso (o fluxo alternativo
+  faz X, o critério de aceite exige Y).
+- **Critério de aceite não verificável** — Gherkin sem dado observável, ou que depende de algo que a
+  spec não define.
+- **Decisão fantasma** — a spec afirma um comportamento onde havia uma pergunta em aberto. Se um
+  `[TODO: …]` foi respondido no texto sem que a decisão tenha sido tomada por quem podia tomá-la,
+  isso é achado: uma decisão inventada é pior que uma pendência visível.
+- **Persona ou regra órfã** — texto que não pertence a esta Feature (resíduo de outro documento).
+  Vale conferir se a spec fala de sistemas, telas ou perfis que a issue não menciona.
+- **Regra de negócio contradita** — a spec inverte uma restrição declarada (retenção de dados,
+  consentimento, limites, LGPD).
+
+<!-- requires-tools -->
+## Como verificar
+
+Você tem `Read`, `Glob` e `Grep`. A spec descreve comportamento, não código — mas quando ela afirma
+que "hoje o sistema faz X", isso é verificável: abra o repositório e confira. Afirmação sobre o
+estado atual que não se sustenta é achado.
+<!-- /requires-tools -->
+## Barra de rigor
+
+NÃO invente problemas. Uma spec pode legitimamente deixar pendências marcadas — `[TODO: …]`
+explícito é decisão adiada, não defeito. O defeito é a pendência que sumiu sem ter sido decidida.
+
+Ambiguidade que um implementador resolveria de duas formas diferentes é achado. Ambiguidade que
+qualquer leitor resolveria igual não é.
+
+## Consequência
+
+Um achado marcado como **grave** bloqueia o avanço até correção; um **menor** é reportado sem
+bloquear. Um achado grave custa o tempo de um humano — reserve-o para o que faria a implementação
+sair errada, não para preferência de redação.

package/src/setup/labels.mjs

@@ -1,5 +1,5 @@
 import { createLabel } from '../api/github-rest.mjs';
-import { ALL_LABELS } from '../config.mjs';
+import { allLabelsFor } from '../config.mjs';
 
 const DELAY_MS = 120;
 
@@ -7,11 +7,15 @@ function sleep(ms) {
   return new Promise(r => setTimeout(r, ms));
 }
 
-export async function setupLabels(token, owner, repo, spinner) {
-  for (let i = 0; i < ALL_LABELS.length; i++) {
-    const label = ALL_LABELS[i];
-    spinner.message(`Criando label ${i + 1}/${ALL_LABELS.length}: ${label.name}`);
+// `fileAi` traz as labels de modelo derivadas de `ai.modelAliases`. No `init` ele
+// vem vazio (o config ainda nem foi gravado) e o conjunto é só o do fluxo; quem
+// cria as de modelo depois é o `update`, que já lê o config do repo.
+export async function setupLabels(token, owner, repo, spinner, fileAi) {
+  const labels = allLabelsFor(fileAi);
+  for (let i = 0; i < labels.length; i++) {
+    const label = labels[i];
+    spinner.message(`Criando label ${i + 1}/${labels.length}: ${label.name}`);
     await createLabel(token, owner, repo, label);
-    if (i < ALL_LABELS.length - 1) await sleep(DELAY_MS);
+    if (i < labels.length - 1) await sleep(DELAY_MS);
   }
 }

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

@@ -4,13 +4,46 @@ on:
   pull_request:
     types: [opened, reopened]
 
+# Trava por PR: protege contra o mesmo PR ser processado duas vezes. A trava que
+# importa de verdade é a do job `move`, por ITEM — ver o comentário lá.
 concurrency:
   group: spec-wave-code-review-${{ github.event.pull_request.number }}
   cancel-in-progress: false
 
 jobs:
-  code-review:
+  # Descobre a Feature-alvo ANTES de tocar no board. Existe só para dar a chave
+  # de concurrency ao job seguinte: `concurrency` de workflow é avaliada no
+  # trigger, quando ainda não se sabe qual issue o PR implementa.
+  resolve:
     runs-on: ubuntu-latest
+    permissions:
+      issues: read
+      pull-requests: read
+      contents: read
+    outputs:
+      feature: ${{ steps.resolve.outputs.feature }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+      - id: resolve
+        run: npx @spec-wave/cli@{{CLI_VERSION}} code-review --pr-number ${{ github.event.pull_request.number }} --resolve-only
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_REPOSITORY: ${{ github.repository }}
+
+  move:
+    needs: resolve
+    # PR sem vínculo explícito não resolve Feature nenhuma — e não move nada.
+    if: 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
+    # corrida que fez duas Stories e duas Tasks nascerem concluídas.
+    concurrency:
+      group: spec-wave-item-${{ needs.resolve.outputs.feature }}
+      cancel-in-progress: false
     permissions:
       issues: write
       pull-requests: write

package/src/templates/workflows/decompose.yml

@@ -8,8 +8,19 @@ on:
 # 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.
+#
+# O namespace `spec-wave-item-<issue>` é COMPARTILHADO com o job `move` do
+# code-review.yml: os dois mexem na mesma subárvore, e rodar em paralelo foi o
+# que corrompeu a Etapa de sete itens (Stories/Tasks criadas no meio do run do
+# code-review nasceram em Done). Renomear este grupo sem renomear lá desfaz a
+# 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ê
+# o spec.md/plan.md do checkout — que uma geração concorrente estaria trocando
+# debaixo dele.
 concurrency:
-  group: spec-wave-decompose-${{ github.event.issue.number }}
+  group: spec-wave-item-${{ github.event.issue.number }}
   cancel-in-progress: false
 
 jobs:

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

@@ -4,8 +4,15 @@ on:
   issues:
     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.
 concurrency:
-  group: spec-wave-generate-bug-${{ github.event.issue.number }}
+  group: spec-wave-item-${{ github.event.issue.number }}
   cancel-in-progress: false
 
 jobs:

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

@@ -4,8 +4,23 @@ on:
   issues:
     types: [labeled]
 
+# 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).
+#  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.
 concurrency:
-  group: spec-wave-generate-plan-${{ github.event.issue.number }}
+  group: spec-wave-item-${{ github.event.issue.number }}
   cancel-in-progress: false
 
 jobs:

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

@@ -4,8 +4,23 @@ on:
   issues:
     types: [labeled]
 
+# 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).
+#  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.
 concurrency:
-  group: spec-wave-generate-spec-${{ github.event.issue.number }}
+  group: spec-wave-item-${{ github.event.issue.number }}
   cancel-in-progress: false
 
 jobs: