@spec-wave/cli 0.30.0 → 0.33.0

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

@@ -11,13 +11,28 @@ allowed-tools:
 Comando **local**:
 
 ```bash
-npx @spec-wave/cli@latest order <feature>   # uma Feature
-npx @spec-wave/cli@latest order             # o mapa de todas as Features com trabalho
+npx @spec-wave/cli@latest order <feature>            # uma Feature
+npx @spec-wave/cli@latest order                      # o mapa de todas as Features com trabalho
+npx @spec-wave/cli@latest order --milestone v04      # só as Features da milestone
+npx @spec-wave/cli@latest order --json               # contrato estável p/ scripts e agentes
+npx @spec-wave/cli@latest order <feature> --sync     # blocked_by da API → doc + dependency-map.json
 ```
 
-| Arg | Descrição |
+| Arg/Flag | Descrição |
 |-----|-----------|
 | `<feature>` | Número da issue da **Feature**, ex.: `12` ou `#12`. Posicional, **opcional**. |
+| `--milestone <ref>` | Filtra o mapa sem argumento pelas Features da milestone (número ou título). |
+| `--json` | Saída JSON estável (sem ANSI) — **prefira-a para consumo programático**, em vez de parsear o texto. |
+| `--remote` | Une também o blocked_by da API (1 chamada por Story) — pega arestas criadas SÓ pela UI. |
+| `--refresh` | Ignora o cache local e reconsulta a API. |
+| `--sync` | Reescreve as linhas `Depende de:` do decomposition.md e regenera o `dependency-map.json` a partir do estado VIVO (body ∪ blocked_by), com commit local. |
+
+**De onde vem a informação (e por que é barato):** as arestas saem de fontes **locais** — o
+`docs/features/<slug>/dependency-map.json` (escrito pelo `decompose --apply`), o
+`decomposition.md` aplicado e as linhas `Depende de:` do corpo — zero chamada por Story. A
+Etapa vem de **um** snapshot do board, cacheado por `cache.ttlSec` (default 600s; env
+`SPEC_WAVE_CACHE_TTL`; `0` desliga) com a idade sempre impressa. Um `blocked_by` criado só
+pela UI não está nas fontes locais: a saída avisa, e `--remote`/`--sync` o incluem.
 
 **Sem argumento**, o conjunto vem do **board** (não dos arquivos): todas as Features abertas fora de 🎉 Done, com as Stories de todas num **grafo só** e a Feature de cada uma ao lado. É o modo para responder "por onde os devs pegam agora" quando o trabalho está espalhado por várias Features — nesse escopo, dependência entre Features deixa de ser "externa" e entra na ordenação.
 
@@ -25,7 +40,7 @@ npx @spec-wave/cli@latest order             # o mapa de todas as Features com tr
 
 ## O que a saída traz
 
-- As Stories da Feature em **ordem topológica** pelas dependências — a linha `Depende de: #N` no corpo **mesclada** com a relação nativa *blocked by* do GitHub
+- As Stories da Feature em **ordem topológica** pelas dependências — dependency-map.json ∪ decomposition.md ∪ linha `Depende de: #N` do corpo (e, com `--remote`, a relação nativa *blocked by*)
 - A **Etapa atual** de cada Story no board
 - Avisos de **ciclo de dependência** — essas Stories ficam **fora da ordem**; corrija as linhas `Depende de:`
 - Avisos de **dependência fora de ordem** — Story já em 🚧 Desenvolvimento ou além dependendo de outra que não está em 🎉 Done (no modo de uma Feature, também quando a bloqueadora é de **outra** Feature e continua aberta)
@@ -38,4 +53,5 @@ npx @spec-wave/cli@latest order             # o mapa de todas as Features com tr
 2. Apresente a ordem ao usuário, marcando o que já está concluído e o que está pendente.
 3. **Se houver ciclo**, isso é bloqueante para a skill **implement** no modo Feature (o comando aborta com exit 1). Ajude a quebrar o ciclo editando as linhas `Depende de:` nos corpos das Stories.
 4. **Se houver dependência fora de ordem**, aponte o risco ao usuário antes de seguir.
-5. Com a ordem clara, siga para a skill **implement**.
+5. Se o usuário criou/removeu `blocked_by` **pela UI do GitHub**, rode `order <feature> --sync` para gravar isso nos artefatos — as consultas seguintes voltam a ser locais.
+6. Com a ordem clara, siga para a skill **implement**.

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

@@ -71,7 +71,9 @@ Mostre ao usuário o contexto montado em `.spec-wave/qa-<n>.md` antes de rodar s
 
 Alvos: `qa <feature>` roda todos os cenários das Stories ainda sem `qa-approved`; `qa <story>` só os daquela Story; `qa <bug>` o Teste de Regressão do `bug.md`; `--only <n[,m]>` filtra por número posicional.
 
-**PROIBIDO corrigir código durante a execução.** QA não conserta: cenário reprovado vira Bug, e alterar o código no meio invalida o veredito. Se você for o executor (via `qa.command`), siga as instruções do contexto à risca — um cenário por vez, evidência bruta, `blocked` (nunca `fail`) para o que não pôde rodar.
+**PROIBIDO corrigir código durante a execução.** QA não conserta: cenário reprovado vira Bug, e alterar o código no meio invalida o veredito. Se você for o executor (via `qa.command`), siga a skill **qa-executor** e as instruções do contexto à risca — um cenário por vez, evidência bruta, `blocked` (nunca `fail`) com o `blockedReason` do enum para o que não pôde rodar.
+
+Para validar uma **trilha inteira** (todas as Features de um milestone, em containers paralelos), use a skill **qa-lead** — o `qa` continua sendo a unidade que ela orquestra.
 
 ## 4. Os três desfechos
 

package/src/plugin/skills/qa-executor/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: spec-wave-qa-executor
+description: "Use quando você for o agente EXECUTOR de QA do spec-wave — acionado via `qa.command` com um contexto `.spec-wave/qa-<n>.md`. Executa os cenários um a um, registra evidência bruta e grava o veredito em `.spec-wave/qa-result-<n>.json`. NUNCA corrige código nem escreve no GitHub. Gatilhos: 'execute o QA descrito em', contexto de QA do spec-wave, arquivo qa-<n>.md."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+---
+
+# spec-wave qa-executor — o agente que executa os cenários
+
+Você foi acionado pelo `spec-wave qa <n>` (diretamente ou por um container do
+`qa-lead`). Seu trabalho é **executar cenários e registrar o que observou** — o
+veredito volta pelo **arquivo de resultados**, nunca por texto ou exit code.
+
+## O que ler
+
+1. O **contexto** (`.spec-wave/qa-<n>.md`, indicado no prompt): traz os cenários
+   a executar NESTA ORDEM, o setup do ambiente, o caminho do arquivo de
+   resultados e os comentários relevantes das issues.
+2. O **plano** (`docs/features/<slug>/qa-plan.md`) e a **spec**
+   (`docs/features/<slug>/spec.md`), apontados no contexto — leia-os para
+   entender os critérios de aceite antes do primeiro cenário.
+
+## Regras de execução (OBRIGATÓRIAS)
+
+1. **Um cenário por vez, na ordem do contexto.** Não paralelize, não pule.
+2. **Evidência bruta, sem paráfrase** — o comando executado, a saída relevante e
+   o código de status. A evidência de um `fail` vira o `bug.md` do Bug aberto:
+   "não funcionou" não reproduz nada; `500 — TypeError: cannot read 'id' of
+   undefined` reproduz.
+3. **PROIBIDO corrigir código.** QA não conserta. Alterar qualquer código
+   durante a execução **invalida o veredito de todos os cenários da corrida**,
+   inclusive os que já passaram.
+4. **PROIBIDO escrever no GitHub.** Não comente, não abra issue, não mova card —
+   isso é do comando `qa`, depois de ler seu resultado. Com o `qa-lead`, N
+   executores rodam em paralelo: dois agentes escrevendo no board é exatamente o
+   que esta regra impede.
+5. **`blocked` nunca é `fail`.** Cenário que não pôde ser executado
+   (pré-condição ausente, serviço fora, seed que falhou, dependência não
+   entregue) é `blocked` com o `blockedReason` do enum. Marcar como `fail` cria
+   um Bug falso e custa investigação de dev.
+
+## Como registrar o veredito
+
+Ao terminar (ou ao abortar no meio), grave `.spec-wave/qa-result-<n>.json` — o
+caminho exato está no contexto:
+
+```json
+{
+  "scenarios": [
+    { "cenario": 1, "verdict": "pass", "evidencia": "GET /pedidos → 200; 2 pedidos, ambos de A" },
+    { "cenario": 2, "verdict": "fail", "evidencia": "500 — TypeError: cannot read 'id' of undefined" },
+    { "cenario": 3, "verdict": "blocked", "blockedReason": "massa-de-dados",
+      "evidencia": "seed falhou: tabela `pedidos` inexistente" }
+  ]
+}
+```
+
+- **Um objeto por cenário-alvo**, com o número POSICIONAL. Nenhum pode ser
+  omitido: se você abortar no meio, os cenários não alcançados entram como
+  `blocked` — resultado parcial honesto vale mais que ausência de resultado.
+- `fail` **exige** `evidencia` não vazia.
+- `blocked` **exige** `blockedReason`, um de: `ambiente` · `setup-falhou` ·
+  `massa-de-dados` · `dependencia-nao-entregue` · `bloqueado-por-bug` ·
+  `credencial` · `outro` (este exige `evidencia` com o motivo em texto livre).
+- A CLI **recusa** o arquivo fora do contrato (schema em
+  `protocol/qa-result.v1.json` do pacote `@spec-wave/cli`) — e arquivo ausente é
+  falha alta: nada é aprovado nem reprovado sem ele.
+
+## Setup do ambiente
+
+Se o contexto trouxer uma seção de setup, rode-a **antes do primeiro cenário**.
+Se o setup falhar, TODOS os cenários são `blocked` com `blockedReason:
+setup-falhou` e a saída do erro como evidência — não tente "consertar o
+ambiente" mudando código.

package/src/plugin/skills/qa-lead/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: spec-wave-qa-lead
+description: "Use para orquestrar o QA de uma TRILHA inteira (milestone) do spec-wave — preparar os planos de todas as Features (`qa-lead plan`), executar o ciclo com containers paralelos (`qa-lead run`) e consultar relatórios de ciclo (`qa-lead report`). Gatilhos: 'rodar o QA do milestone', 'QA da release', 'trilha de QA', 'relatório de QA do ciclo'."
+allowed-tools:
+  - Bash(npx @spec-wave/cli@latest qa-lead *)
+  - Bash(npx @spec-wave/cli@latest qa *)
+  - Bash(npx @spec-wave/cli@latest doctor)
+  - Bash(gh issue *)
+  - Read
+---
+
+# spec-wave qa-lead — QA de trilha (milestone)
+
+O `qa` valida **uma** issue; o `qa-lead` percorre **todas as Features de um
+milestone** (trilha = milestone, D-QAL1), em duas fases com um portão humano no
+meio (D-QAL2). O Lead **não executa cenário, não abre Bug, não move card** —
+toda mutação de board continua no `qa`, que roda dentro dos containers.
+
+## Fase A — preparar os planos
+
+```bash
+npx @spec-wave/cli@latest qa-lead plan <milestone> --dry-run   # classifica sem aplicar nada
+npx @spec-wave/cli@latest qa-lead plan <milestone> [--watch]
+```
+
+Classifica cada Feature (pronta / portão humano / em voo / sem spec-plan) e
+aplica `spec-wave:qa` nas que precisam de plano. **PARA aqui** (D-QA4): o humano
+revisa os `qa-plan.md` e o Action aplica `qa-ready`. `--watch` acompanha até
+resolver (teto `qa.lead.planWaitTimeoutMin`). Exit 0 só com a trilha inteira
+pronta.
+
+- Feature com `critique-failed`/`needs-human` é **portão humano**: o Lead nunca
+  aplica gatilho nela — corrija o documento apontado no comentário 🔎 primeiro.
+
+## Fase B — executar o ciclo
+
+```bash
+npx @spec-wave/cli@latest qa-lead run <milestone> --dry-run    # plano de despacho, zero container
+npx @spec-wave/cli@latest qa-lead run <milestone> [--only 318,320] [--max-cycles 3]
+```
+
+- **Portão:** toda Feature em 🧪 QA precisa de `qa-ready`, senão recusa listando
+  as pendentes. Features em etapa anterior aparecem como `fora-do-ciclo`;
+  posteriores, `ja-aprovada` — contabilizadas, sem bloquear.
+- **Preflight global** antes de qualquer container (backend, imagem,
+  credenciais, disco). Falha → ciclo `ciclo-abortado` com relatório emitido.
+- **Despacho:** até `qa.lead.maxParallel` containers, um ambiente isolado por
+  Feature (D-QAL3), rodando `qa <feature>`. Timeout mata o container e a
+  Feature vira `execucao-abortada` (nunca lida como verde).
+- **Ciclos:** o N+1 só existe se um Bug fechou ou um bloqueio caiu desde o N
+  (D-QAL7); retestes usam `qa <story> --only <cenários>`. Teto de 3 ciclos.
+
+Configuração no `.spec-wave.json` (defaults entre parênteses):
+
+```json
+{
+  "qa": {
+    "lead": {
+      "maxParallel": 4, "maxCycles": 3, "featureTimeoutMin": 45,
+      "pollIntervalSec": 30, "planWaitTimeoutMin": 20,
+      "container": { "image": "ghcr.io/acme/qa-runner:1.4", "env": { "NODE_ENV": "test" } }
+    }
+  }
+}
+```
+
+`container.image` é **obrigatória** para a fase B. Valor vazio em
+`container.env` significa "vem do ambiente do Lead". Backend: `docker`
+(default) ou `sandbox` (follow-up — ainda sem API de sessão).
+
+## Relatórios
+
+```bash
+npx @spec-wave/cli@latest qa-lead report <milestone> [--cycle <n>]
+```
+
+Cada ciclo grava `docs/qa/<slug-milestone>/cycle-<n>/{report.md,report.json}`
+(schema em `protocol/qa-trail-report.v1.json`) e atualiza um **bloco delimitado**
+na descrição do milestone — substituído a cada ciclo, preservando o resto da
+descrição (Release Notes moram no mesmo campo).
+
+## O que o Lead escreve (e NADA além)
+
+1. a label de gatilho `spec-wave:qa` (fase A);
+2. `docs/qa/<slug>/cycle-<n>/{report.md,report.json}`;
+3. o bloco delimitado na descrição do milestone.
+
+Etapa, `qa-approved`, Bugs e comentários de veredito são do `qa`. Se algo mais
+precisar mudar no board, use as skills **qa** ou **move** — nunca por fora.