@spec-wave/cli 0.29.0 → 0.32.0

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.