@spec-wave/cli 0.28.0 → 0.29.0

package/src/templates/config/tech_context.yml

@@ -40,3 +40,16 @@ existing_services:
 internal_libraries:
   - "shared-logger"
   - "db-client (TypeORM)"
+
+# Decisões de modelagem de recursos COMPARTILHADOS entre features (opcional).
+#
+# `criada_por:` é obrigatório em cada entrada: a Feature que cria o recurso
+# (ex.: "FT-01.7" ou "#42"), ou o literal SEM DONO enquanto ninguém o criar.
+# "Não existe feature para editar esses valores" escrito em prosa fica meses
+# sem ninguém agir; SEM DONO aparece no `spec-wave audit` como pendência de
+# checklist antes de planejar a milestone.
+#
+# decisoes_de_modelagem:
+#   - recurso: "custo_canal"
+#     decisao: "Tabela própria; valores editados por ADMIN, consumidos por 4 features"
+#     criada_por: "SEM DONO"

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|move|uninstall|rfc|bug|triage|fix-pr] [target]"
+argument-hint: "[info|setup|update|doctor|preflight|audit|issue|feature|spec|plan|ready|decompose|order|implement|merge|task|story|move|uninstall|rfc|bug|triage|fix-pr] [target]"
 user-invocable: true
 allowed-tools:
   - Bash(npx @spec-wave/cli@latest *)
@@ -77,7 +77,7 @@ npx @spec-wave/cli@latest mode                 # estado atual dos dois lados do
 npx @spec-wave/cli@latest mode local           # desarma os workflows
 npx @spec-wave/cli@latest run <issue> --dry-run  # explica o próximo passo sem executar
 npx @spec-wave/cli@latest run <issue>          # executa
-npx @spec-wave/cli@latest run --pr <n>         # code-review (+ qa, se houver aprovação)
+npx @spec-wave/cli@latest run --pr <n>         # code-review (+ qa, se aprovado OU mergeado)
 ```
 
 O `run` decide o passo pelo estado da issue (documentos existentes + labels), respeita os portões humanos (`needs-human`, `critique-failed`), recusa rodar com uma label de gatilho pendente e **exige `--apply`** para o `decompose-apply`, que cria issues. Sempre mostre o `--dry-run` ao usuário antes de executar.
@@ -253,7 +253,33 @@ Sem flags. Roda um checklist de diagnóstico no repositório atual: token GitHub
 |----------|------|-----------|
 | `<feature>` | string (obrigatório) | Número da issue da **Feature**, ex.: `12` ou `#12`. Argumento posicional. |
 
-> **Sem argumento**, monta o mapa de TODAS as Features abertas fora de 🎉 Done num grafo só (conjunto vindo do board), com a Feature de cada Story ao lado — nesse escopo a dependência entre Features entra na ordenação. Com `<feature>`, lista as Stories da Feature em **ordem topológica** pelas dependências (linha `Depende de: #N` no corpo + relação nativa *blocked by*, mescladas), com a Etapa atual de cada uma no board. Dependências para **fora da Feature** não entram na ordenação (não há como saber onde a Story de outra Feature entra nesta sequência), mas aparecem em **"Bloqueadas por fora desta Feature"**, com o estado de cada bloqueadora. Avisa sobre **ciclos de dependência** (essas Stories ficam fora da ordem — corrija as linhas `Depende de`) e sobre **dependências fora de ordem** (Story já em Desenvolvimento+ dependendo de outra que não está Done). Use antes de escolher qual Story implementar.
+> **Sem argumento**, monta o mapa de TODAS as Features abertas fora de 🎉 Done num grafo só (conjunto vindo do board), com a Feature de cada Story ao lado — nesse escopo a dependência entre Features entra na ordenação. Com `<feature>`, lista as Stories da Feature em **ordem topológica** pelas dependências (linha `Depende de: #N` no corpo + relação nativa *blocked by*, mescladas), com a Etapa atual de cada uma no board. Dependências para **fora da Feature** não entram na ordenação (não há como saber onde a Story de outra Feature entra nesta sequência), mas aparecem em **"Bloqueadas por fora desta Feature"**, com o estado de cada bloqueadora. Avisa sobre **ciclos de dependência** (essas Stories ficam fora da ordem — corrija as linhas `Depende de`), sobre **dependências fora de ordem** (Story já em Desenvolvimento+ dependendo de outra que não está Done) e sobre **milestone divergente** (Story sem milestone ou em milestone diferente do da Feature — órfã de toda visão de release; sem milestone na Feature, nada é comparado). Use antes de escolher qual Story implementar, e logo após o `decompose --apply` como detector do pós-apply.
+
+### `@spec-wave/cli preflight --milestone <nome>` — confere tudo ANTES de gerar as specs (comando LOCAL)
+| Flag/Arg | Tipo | Descrição |
+|----------|------|-----------|
+| `--milestone <nome>` | string (obrigatório) | Título da milestone a inventariar. |
+| `--json` | boolean | O relatório em JSON, para ramificar. |
+
+> Um comando reporta: token utilizável, modo de execução (config × variável do repositório), publicação por PR, e as Features da milestone com o **estado do `spec.md` de cada uma** (na base, no disco, em PR aberto, em branch sem PR, a gerar). Existe porque **cada geração paga um modelo**: um erro de configuração descoberto na sétima Feature custa sete gerações — e regenerar um documento que já vive num PR descarta a revisão em curso. Sai com código 1 quando há bloqueio. Rode SEMPRE antes de uma rodada de specs por milestone.
+
+### `@spec-wave/cli audit --milestone <nome>` — cruza as specs da milestone como CONJUNTO (comando LOCAL)
+| Flag/Arg | Tipo | Descrição |
+|----------|------|-----------|
+| `--milestone <nome>` | string (obrigatório) | Título da milestone a auditar. |
+| `--critique` | boolean | Roda também a **crítica adversarial de conjunto** — UMA chamada de modelo sobre todas as specs juntas, procurando contradição ENTRE documentos. |
+| `--json` | boolean | O relatório em JSON (com `critica.markdown` pronto para comentar nas issues). |
+
+> A crítica normal audita cada documento contra os insumos da **mesma** Feature; este comando olha o que só existe **no par**: dependência circular entre Features, bloqueante em milestone **posterior** à de quem depende dela, referência a issue inexistente (materiais — exit 1), dependência que nenhuma Feature cria ("recurso sem dono"), sobreposição do slug com código existente e decisão de modelagem com `criada_por: SEM DONO` no `tech_context.yml` (avisos heurísticos — **confira antes de reportar**). Rode depois que as specs existirem (PR aberto também conta), antes de gerar os planos. Achado material é decisão de PO: comente nas issues **dos dois lados**.
+
+### `@spec-wave/cli merge <feature>` — mergeia os PRs empilhados das Stories (comando LOCAL)
+| Flag/Arg | Tipo | Descrição |
+|----------|------|-----------|
+| `<feature>` | string (obrigatório) | Número da issue da **Feature**, ex.: `12` ou `#12`. |
+| `--yes` | boolean | Executa os merges. **Sem ela, só mostra o plano** (fila na ordem, retargets, avisos). |
+| `--keep-branches` | boolean | Não apaga as branches das Stories após o merge. |
+
+> O `implement` empilha os PRs (cada um baseado no anterior) e o merge da pilha é **ordem-dependente**: `--delete-branch` no primeiro PR fecha o segundo. Este comando encapsula a sequência segura — para cada PR na ordem topológica das Stories: reaponta a base para a default, mergeia com **merge commit**, atualiza o board (**merge move até 🧪 QA**) e **só no fim** apaga as branches. **PR em rascunho bloqueia o plano inteiro** (marcar pronto é a revisão humana — o comando não pula isso). Rodar de novo **retoma**: PR mergeado sai do plano. Use após a revisão, em vez de mergear à mão com `gh`.
 
 ### `@spec-wave/cli task <start|done> <n>` — transições de Task no board (comando LOCAL)
 | Flag/Arg | Tipo | Descrição |
@@ -692,7 +718,7 @@ Aciona o spec-kit para implementar uma **Feature** (todas as Stories pendentes,
    - Se o spec-kit **não** estiver configurado, o comando só monta o contexto e mostra como configurar (`specKit.command` / `SPEC_WAVE_IMPLEMENT_CMD`). Ajude o usuário a definir o template (placeholders: `{tasksFile} {specFile} {planFile} {issue} {type} {title}`).
    - Use `--feature-dir docs/features/<slug>` se a resolução automática da Feature falhar (a skill avisa com warning) e você quiser anexar `spec.md`/`plan.md` como contexto.
 6. **No modo Feature**, siga o contexto Story a Story, na ordem listada: para cada Story pendente, implemente as Tasks com `task start`/`task done`, depois commit + PR + `npx @spec-wave/cli@latest story review <n>`; só então passe à próxima Story. **Bug** tem modo próprio (RFC-004): sem tasks e sem spec/plan, com quatro fases — reproduzir → causa raiz → fix mínimo → teste de regressão — e o `bug.md` entrando como hipótese a confirmar. Se a issue não for Feature, Story, Task nem Bug (ex.: Spike, Epic), o comando recusa. Feature **sem Stories** → rode `/spec-wave decompose` primeiro. **Ciclo de dependências** → corrija as linhas `Depende de:` (veja `spec-wave order`).
-7. Ao final (Tasks em **🎉 Done**, Story em **👀 Code Review**; a Feature só vai para Code Review quando a última Story concluir — no modo Feature, isso acontece dentro da mesma execução): confirme o resultado com o usuário e oriente a revisão dos PRs.
+7. Ao final (Tasks em **🎉 Done**, Story em **👀 Code Review**; a Feature só vai para Code Review quando a última Story concluir — no modo Feature, isso acontece dentro da mesma execução): confirme o resultado com o usuário e oriente a revisão dos PRs. **Avise que os PRs estão empilhados** e que o merge é ordem-dependente: depois da revisão (PRs marcados prontos), o caminho é `npx @spec-wave/cli@latest merge <feature>` — nunca `gh pr merge --delete-branch` à mão em PR de pilha.
 
 ---
 

package/src/templates/workflows/qa.yml

@@ -1,8 +1,14 @@
 name: QA
 
+# Dois gatilhos, um destino: aprovação formal OU merge movem a Feature para
+# 🧪 QA. O de merge existe porque o autor não consegue aprovar o próprio PR —
+# num fluxo solo, QA por aprovação nunca aconteceria — e porque homologação de
+# verdade começa com o código integrado. Espelha o `run --pr` do modo local.
 on:
   pull_request_review:
     types: [submitted]
+  pull_request:
+    types: [closed]
 
 concurrency:
   group: spec-wave-qa-${{ github.event.pull_request.number }}
@@ -25,10 +31,12 @@ jobs:
     # 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.
+    # A última linha aceita os dois eventos: review aprovada (pull_request_review)
+    # ou PR fechado COM merge (pull_request closed — fechado sem merge não conta).
     if: >
       vars.SPEC_WAVE_EXECUTION != 'local' &&
       !startsWith(github.event.pull_request.head.ref, 'spec-wave/') &&
-      github.event.review.state == 'approved'
+      (github.event.review.state == 'approved' || github.event.pull_request.merged == true)
     runs-on: ubuntu-latest
     permissions:
       issues: write