@spec-wave/cli 0.29.0 → 0.32.0

package/src/lib/story-graph.mjs

@@ -0,0 +1,256 @@
+// Carregamento do grafo de Stories e do snapshot do board — a CÓPIA ÚNICA do
+// laço que order/implement/merge/qa-lead mantinham cada um por si (e que
+// custava 1..3 chamadas POR STORY em cada comando).
+//
+// Fontes das ARESTAS, da mais barata para a mais cara:
+//  1. `docs/features/<slug>/dependency-map.json` — artefato COMMITADO, escrito
+//     pelo decompose --apply e atualizado pelo `order --sync`;
+//  2. `decomposition.md` aplicado (mesma informação, formato de prosa);
+//  3. linhas "Depende de: #N" do corpo das sub-issues — que o listSubIssues já
+//     devolve DE GRAÇA (zero chamada extra);
+//  4. `remote: true` → blocked_by nativo via API, 1 chamada por Story (cache
+//     `blockedby-*` com TTL). É a única fonte que enxerga aresta criada SÓ
+//     pela UI — por isso o merge --yes a exige fresca.
+// 1–3 são sempre UNIDAS (são grátis); a origem informada ao usuário diz o que
+// entrou.
+//
+// Etapa/estado vêm do snapshot (`listProjectItems`, 1 chamada paginada),
+// cacheado com TTL — NUNCA do par addProjectItem+getItemSingleSelectValue, que
+// além de custar 2 chamadas por item é MUTAÇÃO em caminho de leitura.
+
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { listSubIssues, listProjectItems } from '../api/github-graphql.mjs';
+import { listBlockedBy, getIssue } from '../api/github-rest.mjs';
+import { detectIssueType } from './issue-type.mjs';
+import { featureDocPaths } from './doc-paths.mjs';
+import { parseDecompositionDoc } from './decomposition-doc.mjs';
+import { parseDependencies } from './dependencies.mjs';
+import { indexBoardItems } from './board.mjs';
+import {
+  parseDependencyMap, storiesFromAppliedDoc, mergeDependencyEdges, isFresh,
+  DEPENDENCY_MAP_FILE,
+} from './dependency-map.mjs';
+import {
+  readCacheEntry, writeCacheEntry, DEFAULT_CACHE_TTL_SEC,
+} from './net-cache.mjs';
+
+/**
+ * Stories de uma Feature com as arestas resolvidas — fonte híbrida.
+ *
+ * @param {object} params
+ * @param {string} params.token
+ * @param {string} params.owner
+ * @param {string} params.repo
+ * @param {string} params.root raiz do projeto (docs/ e cache moram nela)
+ * @param {{number:number, nodeId?:string, node_id?:string, title:string}} params.feature
+ * @param {boolean} [params.remote] une também o blocked_by da API (S chamadas)
+ * @param {boolean} [params.refresh] ignora TODO cache na leitura (mas grava)
+ * @param {number} [params.ttlSec]
+ * @returns {Promise<{
+ *   stories: Array<{number, title, nodeId, body, state, stateReason, createdAt,
+ *                   milestone, labels, dependsOn:number[]}>,
+ *   allSubs: Array<object>,
+ *   origin: { edges: string, mapGeneratedAt: string|null, subsFrom: 'cache'|'api',
+ *             fetchedAt: string|null },
+ *   warnings: string[],
+ * }>}
+ */
+export async function loadFeatureStories({
+  token, owner, repo, root, feature, remote = false, refresh = false,
+  ttlSec = DEFAULT_CACHE_TTL_SEC,
+} = {}) {
+  const warnings = [];
+  const nodeId = feature.nodeId || feature.node_id;
+
+  // ── sub-issues (com body!) — cache subissues-<n> ───────────────────────────
+  const subsKey = `subissues-${feature.number}`;
+  const cached = refresh ? null : readCacheEntry(root, subsKey, { owner, repo });
+  let allSubs;
+  let subsFrom;
+  let fetchedAt;
+  if (cached && isFresh(cached, ttlSec)) {
+    allSubs = cached.data;
+    subsFrom = 'cache';
+    fetchedAt = cached.fetchedAt;
+  } else {
+    allSubs = await listSubIssues(token, nodeId);
+    subsFrom = 'api';
+    fetchedAt = new Date().toISOString();
+    writeCacheEntry(root, subsKey, 'sub-issues', allSubs, { owner, repo });
+  }
+  const storySubs = allSubs
+    .filter(s => detectIssueType({ title: s.title, labels: s.labels }) === 'Story');
+
+  // ── fontes de aresta locais (grátis — sempre unidas) ───────────────────────
+  const sources = [];
+  const parts = [];
+  let mapGeneratedAt = null;
+
+  const paths = root ? safeDocPaths(root, feature.title) : null;
+  if (paths) {
+    const mapAbs = path.join(root, paths['dependency-map'].rel);
+    if (existsSync(mapAbs)) {
+      try {
+        const parsed = parseDependencyMap(JSON.parse(readFileSync(mapAbs, 'utf-8')));
+        if (parsed.ok) {
+          sources.push(parsed.map.stories);
+          parts.push('map');
+          mapGeneratedAt = parsed.map.generatedAt || null;
+        } else {
+          warnings.push(`${DEPENDENCY_MAP_FILE} ignorado: ${parsed.reason} — regenere com \`order ${feature.number} --sync\`.`);
+        }
+      } catch {
+        warnings.push(`${DEPENDENCY_MAP_FILE} ilegível — regenere com \`order ${feature.number} --sync\`.`);
+      }
+    }
+    if (parts.length === 0) {
+      const docAbs = path.join(root, paths.decomposition.rel);
+      if (existsSync(docAbs)) {
+        try {
+          const converted = storiesFromAppliedDoc(parseDecompositionDoc(readFileSync(docAbs, 'utf-8')));
+          if (converted.ok) {
+            sources.push(converted.stories);
+            parts.push('doc');
+          }
+        } catch { /* doc ilegível → segue com o body */ }
+      }
+    }
+  }
+
+  // Body: as linhas "Depende de: #N" que o apply gravou (ou o humano editou).
+  sources.push(storySubs.map(s => ({ number: s.number, dependsOn: parseDependencies(s.body) })));
+  parts.push('body');
+
+  // ── blocked_by remoto (opcional — a única fonte com aresta só-da-UI) ───────
+  if (remote) {
+    const remoteEdges = [];
+    for (const s of storySubs) {
+      const key = `blockedby-${s.number}`;
+      const hit = refresh ? null : readCacheEntry(root, key, { owner, repo });
+      if (hit && isFresh(hit, ttlSec)) {
+        remoteEdges.push({ number: s.number, dependsOn: hit.data });
+        continue;
+      }
+      try {
+        const deps = (await listBlockedBy(token, owner, repo, s.number)).map(b => b.number);
+        remoteEdges.push({ number: s.number, dependsOn: deps });
+        writeCacheEntry(root, key, 'blocked-by', deps, { owner, repo });
+      } catch (err) {
+        // Falha de rede NÃO entra no cache e não derruba: as fontes locais
+        // seguem valendo — mas o usuário precisa saber que o remoto ficou fora.
+        warnings.push(`blocked_by de #${s.number} não consultável agora (${err.message}).`);
+      }
+    }
+    sources.push(remoteEdges);
+    parts.push('remote');
+  }
+
+  const edges = mergeDependencyEdges(...sources);
+  return {
+    stories: storySubs.map(s => ({ ...s, dependsOn: edges.get(s.number) || [] })),
+    allSubs,
+    origin: { edges: parts.join('+'), mapGeneratedAt, subsFrom, fetchedAt },
+    warnings,
+  };
+}
+
+/**
+ * Sub-issues de um item, com cache `subissues-<n>` (TTL).
+ *
+ * Para quem precisa dos filhos CRUS (ex.: as Tasks de uma Story no implement)
+ * sem o resto do grafo.
+ *
+ * @returns {Promise<{subs:Array, fromCache:boolean, fetchedAt:string}>}
+ */
+export async function cachedSubIssues({
+  token, owner, repo, root, parent, refresh = false, ttlSec = DEFAULT_CACHE_TTL_SEC,
+} = {}) {
+  const key = `subissues-${parent.number}`;
+  if (!refresh) {
+    const hit = readCacheEntry(root, key, { owner, repo });
+    if (hit && isFresh(hit, ttlSec)) return { subs: hit.data, fromCache: true, fetchedAt: hit.fetchedAt };
+  }
+  const subs = await listSubIssues(token, parent.nodeId || parent.node_id);
+  writeCacheEntry(root, key, 'sub-issues', subs, { owner, repo });
+  return { subs, fromCache: false, fetchedAt: new Date().toISOString() };
+}
+
+// featureDocPaths lança para título vazio/eslug inválido — aqui vira "sem docs".
+function safeDocPaths(root, title) {
+  try {
+    return featureDocPaths(root, { title }, 'Feature');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Snapshot do board (Etapa/estado/milestone de todos os itens) — 1 chamada
+ * paginada, cacheada com TTL.
+ *
+ * `fresh: true` = caminho de DECISÃO QUE ESCREVE (gates do implement, escopo do
+ * qa-lead run): ignora o cache na leitura, mas grava — o comando seguinte da
+ * sessão ganha o snapshot de graça.
+ *
+ * @param {object} params
+ * @param {string} params.token
+ * @param {{id:string}} params.project
+ * @param {string} params.root
+ * @param {boolean} [params.refresh] força reconsulta (flag do usuário)
+ * @param {boolean} [params.fresh] exige dado novo (decisão de escrita)
+ * @param {number} [params.ttlSec]
+ * @returns {Promise<{items:Array, index:Map<number,object>, fetchedAt:string, fromCache:boolean}>}
+ */
+export async function loadBoardSnapshot({
+  token, project, root, refresh = false, fresh = false, ttlSec = DEFAULT_CACHE_TTL_SEC,
+} = {}) {
+  const key = 'board-items';
+  if (!refresh && !fresh) {
+    const hit = readCacheEntry(root, key, { projectId: project.id });
+    if (hit && isFresh(hit, ttlSec)) {
+      return {
+        items: hit.data,
+        index: indexBoardItems(hit.data),
+        fetchedAt: hit.fetchedAt,
+        fromCache: true,
+      };
+    }
+  }
+  const items = await listProjectItems(token, project.id);
+  writeCacheEntry(root, key, 'board-items', items, { projectId: project.id });
+  return {
+    items,
+    index: indexBoardItems(items),
+    fetchedAt: new Date().toISOString(),
+    fromCache: false,
+  };
+}
+
+/**
+ * Estado (aberta/fechada, título) de uma issue externa — cache `issue-<n>`.
+ *
+ * Só para EXIBIÇÃO (a lista "Bloqueadas por fora" do order); decisão de escrita
+ * nunca passa por aqui.
+ *
+ * @returns {Promise<{title:string, state:string|null, aberta:boolean, fromCache:boolean}>}
+ */
+export async function externalIssueInfo({
+  token, owner, repo, root, number, refresh = false, ttlSec = DEFAULT_CACHE_TTL_SEC,
+} = {}) {
+  const key = `issue-${number}`;
+  if (!refresh) {
+    const hit = readCacheEntry(root, key, { owner, repo });
+    if (hit && isFresh(hit, ttlSec)) return { ...hit.data, fromCache: true };
+  }
+  const issue = await getIssue(token, owner, repo, number).catch(() => null);
+  if (!issue) {
+    // Falha não entra no cache: "não foi possível ler" com cara de fresco por
+    // 10 minutos esconderia uma issue que voltou a ser legível.
+    return { title: '(não foi possível ler)', state: null, aberta: true, fromCache: false };
+  }
+  const data = { title: issue.title, state: issue.state, aberta: issue.state === 'open' };
+  writeCacheEntry(root, key, 'issue', data, { owner, repo });
+  return { ...data, fromCache: false };
+}

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

@@ -1,7 +1,7 @@
 {
   "name": "spec-wave",
   "displayName": "Spec Wave",
-  "version": "0.29.0",
+  "version": "0.32.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/merge/SKILL.md

@@ -22,6 +22,7 @@ O `implement` empilha os PRs de propósito (cada Story revisável sozinha, diff
 ## O que saber antes de rodar
 
 - **Sem `--yes` nada é mergeado** — a saída é o plano: a fila na ordem, qual base será reapontada, o que já está mergeado.
+- O **plano** calcula a ordem pelas fontes locais (dependency-map.json/decomposition.md/corpo — barato); a **execução com `--yes` reconsulta tudo FRESCO da API**, incluindo o blocked_by nativo: merge de pilha é irreversível e não decide com cache.
 - **PR em rascunho bloqueia o plano inteiro.** Marcar pronto é a revisão humana (e o que dispara o CI) — revise e marque cada PR como pronto antes. O comando não faz isso por você, de propósito.
 - **Rodar de novo retoma.** PR mergeado sai do plano sozinho; uma falha no meio (check pendente, conflito) para a fila com as branches dos dependentes intactas.
 - Story **sem PR** vira aviso, não bloqueio — mas se um PR da fila depende do código dela, o merge leva esse código junto; confira antes de confirmar.

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

@@ -0,0 +1,107 @@
+---
+name: spec-wave-qa
+description: "Use para a etapa 🧪 QA do spec-wave — gerar o plano de QA de uma Feature (label spec-wave:qa → qa-plan.md), revisá-lo, e EXECUTAR os cenários localmente com `spec-wave qa <issue>` (Feature, Story ou Bug). Verde move o board sozinho; vermelho abre um Bug por cenário reprovado. Gatilhos: 'rodar o QA', 'validar a feature 12', 'gerar o plano de QA', 'testar a story 34', 're-testar o cenário 2'."
+allowed-tools:
+  - Bash(npx @spec-wave/cli@latest qa *)
+  - Bash(npx @spec-wave/cli@latest generate-qa-plan *)
+  - Bash(npx @spec-wave/cli@latest doctor)
+  - Bash(gh issue *)
+  - Read
+  - Write
+  - Edit
+---
+
+# spec-wave qa — etapa 🧪 QA
+
+Duas metades, em ordem obrigatória:
+
+1. **Gerar o plano** (label + Action): `spec-wave:qa` na **Feature** → o Action gera `docs/features/<slug>/qa-plan.md`, valida, critica e aplica `spec-wave:qa-ready`.
+2. **Executar** (sempre local): `npx @spec-wave/cli@latest qa <issue>` roda os cenários contra o checkout e emite o veredito.
+
+**Nunca rode o `qa` sem a `spec-wave:qa-ready` na Feature** — o comando recusa, e o motivo é de desenho (D-QA3/D-QA4): o veredito **verde avança a Etapa sozinho, sem confirmação humana**, então o portão humano é a **revisão do plano**, antes de executar.
+
+## 0. Detecção de configuração (antes de qualquer coisa)
+
+Confirme que existe `.spec-wave.json` no repositório (senão → skill **setup**). Para executar de fato, o comando do executor precisa estar em `qa.command` no `.spec-wave.json` (ou na env `SPEC_WAVE_QA_CMD`, que tem precedência):
+
+```json
+{
+  "qa": {
+    "command": "claude -p \"Execute o QA descrito em {contextFile}\"",
+    "setup": "npm ci && npm run build",
+    "env": { "BASE_URL": "http://localhost:3000" },
+    "defaultBugPriority": "P2"
+  }
+}
+```
+
+Placeholders: `{contextFile} {qaPlanFile} {specFile} {issue} {type} {title}`. Sem `qa.command`, o comando monta o contexto, imprime como configurar e **não executa** — não é erro.
+
+## 1. Gerar o plano (Feature)
+
+```bash
+gh issue edit <feature> --add-label "spec-wave:qa"
+```
+
+- **Só em Feature** (D-QA1: o plano é por Feature, arquivo único, seções `## Cenário N — Story #X`). Numa Story o Action comenta apontando a Feature-pai; num Bug, não se aplica (ver §5).
+- Arquivo **ausente** → gera via IA e publica em Pull Request. Arquivo **presente** → valida + critica **COMO ESTÁ** (edições manuais são preservadas — mesma semântica do decompose). Para regerar do zero: apague o arquivo e reaplique a label.
+- Requer `spec.md` e `plan.md` já na base.
+- Desfechos: limpo → `spec-wave:qa-ready` + comentário com o resumo; grave → `spec-wave:critique-failed`; reprovas repetidas → `spec-wave:needs-human`.
+
+## 2. Revisar e editar o qa-plan.md (o portão humano)
+
+Leia o plano com o usuário ANTES de executar. Regras do arquivo:
+
+- A estrutura é só `## Cenário N — Story #X`; o corpo aceita markdown livre.
+- **A posição manda, não o número escrito** — inserir um cenário no meio sem renumerar funciona.
+- `Story #X` é obrigatório e precisa ser sub-issue da Feature.
+- `**Critério:**` e `**Esperado:**` são obrigatórios; `**Pré-condições:**` e `**Passos:**` opcionais.
+- Depois de editar, reaplique `spec-wave:qa` para uma nova crítica (o arquivo NÃO é regerado).
+
+> ⚠️ O slug vem do **título** da Feature. Renomeá-la depois da geração órfã o arquivo — o comando falha citando o slug órfão.
+
+## 3. Executar — SEMPRE `--dry-run` primeiro
+
+```bash
+npx @spec-wave/cli@latest qa <issue> --dry-run   # mostra cenários-alvo e o comando; ZERO escrita no GitHub
+npx @spec-wave/cli@latest qa <issue>             # executa de fato
+```
+
+Mostre ao usuário o contexto montado em `.spec-wave/qa-<n>.md` antes de rodar sem `--dry-run`.
+
+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 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
+
+| Veredito | O que aconteceu | O que fazer |
+|---|---|---|
+| ✅ **verde** (todos pass) | `qa-approved` aplicada; Story → 📋 Homologação; Feature move quando TODAS as Stories liberarem; Bug → 🚀 Deploy | Nada — o board já andou. Se a Story tinha **Bug filho aberto**, ela NÃO avança (guarda dura): feche o Bug primeiro. |
+| ❌ **vermelho** (algum fail) | 1 Bug por cenário reprovado (filho da Story dona, ✅ Ready, `bug.md` commitado, `bug-approved` aplicada); item fica em 🧪 QA; exit 1 | Corrija os Bugs (skill **implement**) e re-teste (§6). |
+| ⚪ **inconclusivo** (blocked, sem fail) | Ambiente quebrado não é defeito: nada move, nenhum Bug; exit 1 | Destrave o ambiente (seed, serviço fora do ar) e rode de novo. |
+
+## 5. Bug — exceção documentada (§2.1 da spec)
+
+O QA de um **Bug** usa a seção `Teste de Regressão` do próprio `bug.md` (não há qa-plan). Verde move o Bug para **🚀 Deploy** (D-QA6 — Bug não passa por Homologação).
+
+E quando um cenário reprova, o `bug.md` do Bug novo **é escrito pelo comando, sem IA e sem a label `spec-wave:bug`** — exceção explícita à regra "nunca escreva o bug.md à mão": a reprodução, o esperado/obtido e o teste de regressão já existem e são determinísticos (são o cenário + a saída real). O arquivo é commitado e a `spec-wave:bug-approved` aplicada pelo próprio comando. **Não** aplique `spec-wave:bug` nesses Bugs — regeraria por IA um documento que registra uma execução observada.
+
+## 6. Ciclo de re-teste
+
+1. Fix do Bug (skill **implement**, PR, merge).
+2. Re-teste só o cenário: `npx @spec-wave/cli@latest qa <story> --only <cenário>`.
+3. O comando NÃO duplica Bug: se o cenário reprovar de novo, ele comenta no Bug existente (marcador `spec-wave:qa-origin`).
+4. Verde com o Bug ainda aberto não avança a Story — feche o Bug (o fix mergeado + regressão verde justificam) e rode o `qa` de novo.
+
+## Recusas que você vai encontrar (e o que significam)
+
+- Sem `.spec-wave.json` → rode a skill **setup**.
+- `spec-wave:qa` ainda na issue → geração em voo; aguarde o Action.
+- `critique-failed`/`needs-human` → portão humano da crítica; corrija o documento apontado.
+- Feature sem `qa-ready` → gere/critique o plano primeiro (§1).
+- Etapa **anterior** a 🧪 QA → o `qa` não promove item; quem move até QA é o merge (`spec-wave merge` / `run --pr`).
+- Etapa **posterior** → informa e sai 0 (a Etapa nunca retrocede).
+- Nenhum cenário casando com a Story → plano desatualizado (re-decompose criou Stories novas) ou Feature renomeada (slug órfão).

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

@@ -0,0 +1,44 @@
+---
+name: critique-qa-plan
+action: critique
+description: Critério da crítica adversarial do qa-plan.md contra spec, plan e decomposição, antes da liberação para execução.
+tools: [Read, Glob, Grep]
+maxTurns: 20
+lenses:
+  - "cobertura — algum critério de aceite da spec ficou sem cenário correspondente?"
+  - "vacuidade — algum cenário passaria mesmo sem a implementação, ou tem esperado não observável?"
+  - "fidelidade — algum cenário testa implementação em vez de comportamento, ou contradiz a spec?"
+---
+
+# Crítica adversarial do plano de QA
+
+Você audita o `qa-plan.md` proposto contra o `spec.md`, o `plan.md` e a decomposição. Seu papel é encontrar problemas, não elogiar.
+
+Este portão importa mais que os outros: o veredito **verde da execução avança a Etapa sozinho, sem confirmação humana** (D-QA3). Um plano fraco aprovado aqui vira aprovação automática de trabalho não validado.
+
+## O que caracteriza um achado GRAVE
+
+- **Critério de aceite da spec sem cenário correspondente** — a lacuna faz a Feature ser aprovada sem aquele comportamento ter sido validado.
+- **Cenário que passaria SEM a implementação** — ex.: "a página carrega", "o comando não dá erro" num fluxo que existia antes da Feature. É o mesmo vício já caçado no bug.md: um teste que não falharia não valida nada.
+- **Resultado esperado não observável** — "verificar se funciona", "conferir se está correto", "validar o comportamento". Esperado sem critério objetivo torna o veredito arbitrário.
+- **Cenário que testa implementação em vez de comportamento** — "a classe PedidoService existe", "a função retorna um array" — em vez do que o usuário/consumidor observa.
+- **Cenário que contradiz a spec** — esperado que inverte uma regra de negócio explícita.
+- **Cenário atribuído à Story errada** — o comportamento validado pertence a outra Story da decomposição (a reprova abriria o Bug no lugar errado).
+
+## O que é MENOR
+
+Pré-condições vagas mas completáveis, passos que poderiam ser mais concretos, ordem subótima, redundância parcial entre cenários.
+
+<!-- requires-tools -->
+## Como verificar
+
+Você tem `Read`, `Glob` e `Grep`. Confira os passos contra o repositório real: a rota citada existe? O comando citado existe? Um plano cujos passos apontam para o que não existe produziria só `blocked` — e isso é um achado.
+<!-- /requires-tools -->
+
+## Barra de rigor
+
+NÃO invente problemas. Um plano enxuto que cobre os critérios de aceite com esperados observáveis é um resultado legítimo e frequente — diga isso. O inverso também vale: "não consegui confirmar" não é aprovação.
+
+## Consequência
+
+Um achado **grave** aplica `spec-wave:critique-failed` e o plano NÃO é liberado (`spec-wave:qa-ready` não é aplicada): nenhuma execução de QA roda até a correção. Um achado **menor** é comentado e o plano segue. Reserve o grave para o que tornaria o verde automático enganoso.

package/src/plugin/skills/qa/model-prompt.md

@@ -0,0 +1,68 @@
+---
+name: qa-plan
+action: qa
+description: Gera o plano de QA (qa-plan.md) de uma Feature a partir dos critérios de aceite da spec, com um ou mais cenários por Story.
+tools: [Read, Glob, Grep]
+maxTurns: 30
+---
+
+# Plano de QA de uma Feature
+
+Você é um analista de QA experiente. A partir da Feature fornecida (spec.md, plan.md e a lista de Stories reais), escreva o **qa-plan.md**: os cenários de validação funcional que um executor vai rodar contra o checkout, um por critério de aceite relevante.
+
+## Entrada
+
+O payload JSON traz:
+
+- `feature` — número e título da issue da Feature
+- `stories` — as Stories REAIS (número da issue, título, corpo). **Todo cenário pertence a exatamente uma destas Stories, pelo número.**
+- `spec` — o conteúdo de `spec.md` (critérios de aceite, fluxos, regras de negócio)
+- `plan` — o conteúdo de `plan.md` (estratégia técnica — útil para saber COMO exercitar: endpoints, comandos, telas)
+
+## Formato de saída (obrigatório)
+
+Responda APENAS com o documento markdown, neste formato exato:
+
+```markdown
+# Plano de QA — [FEATURE] Título da Feature
+<!-- spec-wave:qa-plan v1 issue=NUMERO_DA_FEATURE -->
+
+## Cenário 1 — Story #412
+
+**Critério:** AC-2 — cliente vê apenas os próprios pedidos
+**Pré-condições:** dois usuários autenticáveis, cada um com ao menos um pedido
+**Passos:**
+1. Autenticar como usuário A
+2. `GET /pedidos`
+**Esperado:** resposta 200 contendo somente pedidos de A; nenhum pedido de B
+
+## Cenário 2 — Story #412
+...
+```
+
+Regras do formato:
+
+- O título de cada seção é `## Cenário N — Story #X`, onde `#X` é o número REAL de uma Story da lista `stories`. **Nunca invente números de issue.**
+- `**Critério:**` e `**Esperado:**` são obrigatórios em todo cenário. `**Pré-condições:**` e `**Passos:**` são opcionais, mas quase sempre necessários.
+- **Toda Story da lista precisa de ao menos um cenário** — uma Story sem cenário reprova o plano na validação determinística.
+- Escreva em português (pt-BR).
+
+## O que faz um cenário BOM
+
+- **Deriva de um critério de aceite da spec** — cite-o no campo `**Critério:**` (ex.: "AC-3 — pedido cancelado não aparece na listagem"). Todo critério de aceite relevante da spec deve ter um cenário correspondente.
+- **Resultado esperado OBSERVÁVEL**: um status HTTP, uma saída de comando, um registro no banco, um texto na tela. "Verificar se funciona" e "conferir se está correto" não são resultados — são a ausência de um.
+- **Falharia sem a implementação**: um cenário que passaria num checkout sem a Feature não valida nada. Pense: "se ninguém tivesse implementado isso, este cenário quebraria?"
+- **Testa COMPORTAMENTO, não implementação**: valide o que o usuário/consumidor observa, não a existência de uma classe ou o nome de uma função.
+- **Executável por alguém sem contexto**: passos concretos (comandos, URLs, payloads), pré-condições explícitas (dados de teste, usuários, estado inicial).
+
+<!-- requires-tools -->
+## Exploração antes de escrever
+
+Você tem `Read`, `Glob` e `Grep` no repositório. Use-os para ancorar os passos no que existe de verdade: os endpoints reais (rotas registradas), os comandos reais (scripts do package.json, Makefile), os seeds/fixtures disponíveis. Um passo `GET /api/pedidos` só vale se essa rota existe com esse nome. Não gaste mais do que o necessário: explore o suficiente para os passos serem executáveis, e então escreva o documento completo.
+<!-- /requires-tools -->
+
+## O que NÃO fazer
+
+- Não inventar suíte de testes automatizada: o plano descreve validação funcional executável contra o checkout, não `describe/it`.
+- Não cobrir requisitos não-funcionais genéricos (performance, segurança) a menos que a spec traga critério de aceite explícito e testável sobre eles.
+- Não duplicar o mesmo critério em vários cenários — um cenário por comportamento distinto.

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.