@spec-wave/cli 0.6.0 → 0.7.1

package/src/lib/usage-report.mjs

@@ -0,0 +1,167 @@
+// Telemetria de uso de IA (tokens/custo por chamada) → comentário único
+// acumulado na issue da Feature.
+//
+// Cada invocação de generateDocument gera UMA entrada { at, action, provider,
+// model, inputTokens, outputTokens, cost }. O recordUsage acumula as entradas
+// num comentário markdown identificado pelo USAGE_MARKER: parse do comentário
+// existente → concat com as novas → re-render → update (ou create).
+//
+// Contrato: registrar uso NUNCA derruba o fluxo principal — recordUsage é
+// best-effort e engole qualquer erro com um console.warn.
+
+import { listIssueComments, updateComment, commentOnIssue } from '../api/github-rest.mjs';
+
+// Marcador HTML invisível que identifica o comentário de uso na issue.
+export const USAGE_MARKER = '<!-- spec-wave:usage -->';
+
+// Teto de linhas de dados na tabela — ao exceder, descarta as mais antigas
+// (o comentário não pode crescer sem limite em Features longevas).
+const MAX_ROWS = 100;
+
+/**
+ * Calcula o custo em USD a partir da tabela de preços (função PURA — testável).
+ *
+ * `pricing` vem do bloco `ai.pricing` do .spec-wave.json, no formato
+ * `{ [model]: { input, output } }` em USD por 1M de tokens. Sem pricing ou sem
+ * o modelo na tabela → null (custo desconhecido, nunca chuta).
+ *
+ * @param {object} params
+ * @param {string} params.model modelo usado na chamada
+ * @param {number} params.inputTokens tokens de entrada
+ * @param {number} params.outputTokens tokens de saída
+ * @param {object|null} [params.pricing] tabela de preços por modelo
+ * @returns {number|null} custo em USD, ou null se desconhecido
+ */
+export function computeCost({ model, inputTokens, outputTokens, pricing } = {}) {
+  const price = pricing?.[model];
+  if (!price || typeof price.input !== 'number' || typeof price.output !== 'number') {
+    return null;
+  }
+  return ((inputTokens || 0) * price.input + (outputTokens || 0) * price.output) / 1_000_000;
+}
+
+// ISO timestamp → "YYYY-MM-DD HH:mm" em UTC (formato da coluna Data).
+function formatAt(at) {
+  const date = new Date(at);
+  if (Number.isNaN(date.getTime())) return String(at || '');
+  return date.toISOString().slice(0, 16).replace('T', ' ');
+}
+
+// Custo → "$X.XXXX"; null (desconhecido) → travessão.
+function formatCost(cost) {
+  return typeof cost === 'number' ? `$${cost.toFixed(4)}` : '—';
+}
+
+/**
+ * Interpreta o comentário de uso de volta para entries (função PURA — round-trip
+ * do renderUsageComment). Linhas de header, separador e Total são ignoradas.
+ * `at` é reconstruído como `YYYY-MM-DDTHH:mm:00.000Z` (segundos zerados).
+ *
+ * @param {string} body corpo do comentário
+ * @returns {Array<object>|null} entries, ou null se sem marcador ou tabela irreconhecível
+ */
+export function parseUsageComment(body) {
+  const text = body || '';
+  if (!text.includes(USAGE_MARKER)) return null;
+
+  const entries = [];
+  let sawHeader = false;
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('|')) continue;
+    const cells = trimmed.split('|').slice(1, -1).map(c => c.trim());
+    if (cells.length !== 6) continue;
+    if (cells[0] === 'Data (UTC)') { sawHeader = true; continue; } // header
+    if (/^:?-{3,}:?$/.test(cells[0])) continue;                    // separador
+    if (cells[0].includes('Total')) continue;                      // linha Total
+
+    const dateMatch = cells[0].match(/^(\d{4}-\d{2}-\d{2}) (\d{2}:\d{2})$/);
+    const inputTokens = Number.parseInt(cells[3], 10);
+    const outputTokens = Number.parseInt(cells[4], 10);
+    if (!dateMatch || Number.isNaN(inputTokens) || Number.isNaN(outputTokens)) continue;
+
+    const costMatch = cells[5].match(/^\$(\d+(?:\.\d+)?)$/);
+    entries.push({
+      at: `${dateMatch[1]}T${dateMatch[2]}:00.000Z`,
+      action: cells[1],
+      model: cells[2],
+      inputTokens,
+      outputTokens,
+      cost: costMatch ? Number.parseFloat(costMatch[1]) : null,
+    });
+  }
+
+  // Marcador presente mas tabela irreconhecível (sem header ou sem nenhuma
+  // linha de dados válida) → null: o chamador recomeça só com as novas entradas.
+  if (!sawHeader || entries.length === 0) return null;
+  return entries;
+}
+
+/**
+ * Renderiza as entries como comentário markdown (função PURA — testável).
+ *
+ * Cap de MAX_ROWS linhas de dados (descarta as mais antigas). A linha Total
+ * soma os tokens de todas as linhas exibidas e só os custos conhecidos —
+ * custos indisponíveis (—) ficam fora do total.
+ *
+ * @param {Array<object>} entries entradas de uso
+ * @returns {string} corpo markdown do comentário
+ */
+export function renderUsageComment(entries) {
+  const rows = (entries || []).slice(-MAX_ROWS);
+
+  const totalIn = rows.reduce((sum, e) => sum + (e.inputTokens || 0), 0);
+  const totalOut = rows.reduce((sum, e) => sum + (e.outputTokens || 0), 0);
+  const known = rows.filter(e => typeof e.cost === 'number');
+  const totalCost = known.length > 0
+    ? formatCost(known.reduce((sum, e) => sum + e.cost, 0))
+    : '—';
+
+  return [
+    USAGE_MARKER,
+    '📊 **Uso de IA (spec-wave)**',
+    '',
+    '| Data (UTC) | Ação | Modelo | Tokens in | Tokens out | Custo (USD) |',
+    '| --- | --- | --- | ---: | ---: | ---: |',
+    ...rows.map(e =>
+      `| ${formatAt(e.at)} | ${e.action} | ${e.model} | ${e.inputTokens} | ${e.outputTokens} | ${formatCost(e.cost)} |`
+    ),
+    `| **Total** | | | **${totalIn}** | **${totalOut}** | **${totalCost}** |`,
+    '',
+    '_Custos indisponíveis (—) não entram no total. Atualizado automaticamente pelo spec-wave._',
+  ].join('\n');
+}
+
+/**
+ * Registra as entries no comentário de uso da issue (impura, best-effort).
+ *
+ * Acha o comentário com USAGE_MARKER, faz parse das entradas antigas, concatena
+ * as novas e atualiza (ou cria, se não existir). Qualquer erro vira só um
+ * console.warn — telemetria nunca derruba o fluxo principal.
+ *
+ * @param {object} params
+ * @param {string} params.token token do GitHub
+ * @param {string} params.owner dono do repo
+ * @param {string} params.repo nome do repo
+ * @param {number} params.issueNumber número da issue
+ * @param {Array<object>} params.entries novas entradas de uso
+ */
+export async function recordUsage({ token, owner, repo, issueNumber, entries } = {}) {
+  if (!Array.isArray(entries) || entries.length === 0) return;
+  try {
+    const comments = await listIssueComments(token, owner, repo, issueNumber);
+    const existing = comments.find(c => (c.body || '').includes(USAGE_MARKER));
+
+    // Comentário antigo irreconhecível → recomeça só com as novas entradas.
+    const previous = existing ? parseUsageComment(existing.body) : null;
+    const body = renderUsageComment([...(previous || []), ...entries]);
+
+    if (existing?.id) {
+      await updateComment(token, owner, repo, existing.id, body);
+    } else {
+      await commentOnIssue(token, owner, repo, issueNumber, body);
+    }
+  } catch (err) {
+    console.warn('Não foi possível registrar uso de IA:', err.message);
+  }
+}

package/src/setup/files.mjs

@@ -2,6 +2,7 @@ import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 import { upsertFile, getFileContent, isRepoInitialized } from '../api/github-rest.mjs';
+import { WORKFLOW_FILES } from '../config.mjs';
 
 const __dir = path.dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_DIR = path.join(__dir, '..', 'templates');
@@ -22,6 +23,8 @@ export async function setupFiles(token, owner, repo, spinner) {
     );
   }
 
+  // Workflows vêm de WORKFLOW_FILES (config.mjs, fonte única) — adicionar um
+  // workflow novo lá basta para o init (e o update) instalarem.
   const filesToCreate = [
     {
       path: '.github/ISSUE_TEMPLATE/plan-template.md',
@@ -33,26 +36,11 @@ export async function setupFiles(token, owner, repo, spinner) {
       content: readTemplate('issue', 'spec-template.md'),
       message: 'chore: add spec.md issue template [spec-wave]',
     },
-    {
-      path: '.github/workflows/generate-plan.yml',
-      content: readTemplate('workflows', 'generate-plan.yml'),
-      message: 'chore: add generate-plan workflow [spec-wave]',
-    },
-    {
-      path: '.github/workflows/generate-spec.yml',
-      content: readTemplate('workflows', 'generate-spec.yml'),
-      message: 'chore: add generate-spec workflow [spec-wave]',
-    },
-    {
-      path: '.github/workflows/validate.yml',
-      content: readTemplate('workflows', 'validate.yml'),
-      message: 'chore: add validate workflow [spec-wave]',
-    },
-    {
-      path: '.github/workflows/decompose.yml',
-      content: readTemplate('workflows', 'decompose.yml'),
-      message: 'chore: add decompose workflow [spec-wave]',
-    },
+    ...WORKFLOW_FILES.map((file) => ({
+      path: `.github/workflows/${file}`,
+      content: readTemplate('workflows', file),
+      message: `chore: add ${file.replace(/\.yml$/, '')} workflow [spec-wave]`,
+    })),
   ];
 
   for (let i = 0; i < filesToCreate.length; i++) {

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|issue|feature|spec|plan|ready|decompose|implement|uninstall|rfc|fix-pr] [target]"
+argument-hint: "[info|setup|update|doctor|issue|feature|spec|plan|ready|decompose|order|implement|task|story|uninstall|rfc|fix-pr] [target]"
 user-invocable: true
 allowed-tools:
   - Bash(npx @spec-wave/cli *)
@@ -82,6 +82,10 @@ Labels de gatilho:
 - `spec-wave:ready` → dispara `validate.yml` → valida ambos os arquivos
 - `spec-wave:decompose` → dispara `decompose.yml` → gera Stories e Tasks
 
+Labels de **estado** (gravadas pelas automações — **não** são gatilhos, não as adicione por conta própria):
+- `spec-wave:critique-failed` → a crítica adversarial apontou contradições **graves** nos documentos; **bloqueia** o `spec-wave:ready` até ser removida (veja *Crítica adversarial* abaixo)
+- `spec-wave:decomposed` → a Feature/RFC já foi decomposta; o `decompose` pula silenciosamente enquanto ela existir (veja *Guard de idempotência* abaixo)
+
 A etapa **🚧 Desenvolvimento** é coberta pelo comando **local** `npx @spec-wave/cli implement <número>` (não é uma label/Action): lê uma Story ou Task e aciona o spec-kit para implementar. Veja `/spec-wave implement`.
 
 ---
@@ -158,6 +162,10 @@ Mesmas flags do `issue` (exceto `--type`, fixo em `feature`). Mantido para o flu
 | `--issue-number <n>` | string (obrigatório) | Número da issue no GitHub. |
 
 > ⚠️ Esses quatro comandos são executados pelos **GitHub Actions** (disparados por labels), **não** pela skill diretamente. Veja a *Regra fundamental*: para gerar plan/spec/decompor, adicione a **label** correspondente — não rode o comando à mão (a não ser para debug local).
+>
+> **Por tipo de issue:**
+> - `generate-spec` / `generate-plan` → **apenas Features**. Para **Spike, RFC e Bug** a geração é **pulada** (o Action remove a label e comenta) — esses tipos não usam spec/plan.
+> - `decompose` → **Feature** (gera Stories + Tasks) e **RFC** (gera **Tasks** diretamente, sem Stories). Para outros tipos, o Action recusa.
 
 ### `@spec-wave/cli implement` — aciona o spec-kit para uma Story ou Task (comando LOCAL)
 | Flag/Arg | Tipo | Descrição |
@@ -166,7 +174,80 @@ Mesmas flags do `issue` (exceto `--type`, fixo em `feature`). Mantido para o flu
 | `--feature-dir <path>` | string | Caminho `docs/features/<slug>` para anexar `spec.md`/`plan.md` como contexto (sobrescreve a resolução automática). |
 | `--dry-run` | flag | Monta o contexto e imprime o comando do spec-kit **sem executar**. |
 
-> Diferente dos quatro acima, `implement` roda **localmente** (lê `.spec-wave.json`, como `issue`), não por Action. Detecta o tipo da issue: **Story** → coleta todas as Tasks (sub-issues) e aciona o spec-kit uma única vez; **Task** → só aquela task. Monta o contexto em `.spec-wave/implement-<n>.md` e chama o comando configurado em `specKit.command` (no `.spec-wave.json`) ou na env `SPEC_WAVE_IMPLEMENT_CMD`. Placeholders disponíveis no template: `{tasksFile} {specFile} {planFile} {issue} {type} {title}`. Se nada estiver configurado, ele apenas monta o contexto e mostra como configurar (não executa). O contexto inclui instruções para o agente implementar as Tasks **sequencialmente, uma por vez** (nunca duas com Status "In Progress" ao mesmo tempo): cada Task usa o **Status** (In Progress) *dentro* da Etapa 🚧 Desenvolvimento e, **ao concluir, avança para a Etapa 🎉 Done com Status Done**. **Ao concluir toda a Story**: fazer o commit, abrir o PR e **avançar a Etapa da Story para 👀 Code Review** (Status → Todo) — as Tasks já estão em 🎉 Done. A **Feature só avança** para Code Review quando **TODAS as suas Stories** já estiverem em Code Review — enquanto houver Story pendente, a Feature fica em 🚧 Desenvolvimento. Etapa só avança (nunca volta); Status mede o progresso dentro da etapa.
+> Diferente dos quatro acima, `implement` roda **localmente** (lê `.spec-wave.json`, como `issue`), não por Action. Detecta o tipo da issue: **Story** → coleta todas as Tasks (sub-issues) e aciona o spec-kit uma única vez; **Task** → só aquela task. Monta o contexto em `.spec-wave/implement-<n>.md` e chama o comando configurado em `specKit.command` (no `.spec-wave.json`) ou na env `SPEC_WAVE_IMPLEMENT_CMD`. Placeholders disponíveis no template: `{tasksFile} {specFile} {planFile} {issue} {type} {title}`. Se nada estiver configurado, ele apenas monta o contexto e mostra como configurar (não executa). O contexto inclui os **comentários da issue**, um **digest do código recente** e um **aviso de dependências pendentes** quando a issue depende (linha `Depende de: #N` ou relação nativa *blocked by*) de outra que ainda não foi concluída — nesse caso, confirme com o usuário antes de seguir. Inclui também instruções para o agente implementar as Tasks **sequencialmente, uma por vez** (nunca duas com Status "In Progress" ao mesmo tempo): cada Task usa o **Status** (In Progress) *dentro* da Etapa 🚧 Desenvolvimento e, **ao concluir, avança para a Etapa 🎉 Done com Status Done**. **Ao concluir toda a Story**: fazer o commit, abrir o PR e **avançar a Etapa da Story para 👀 Code Review** (Status → Todo) — as Tasks já estão em 🎉 Done. A **Feature só avança** para Code Review quando **TODAS as suas Stories** já estiverem em Code Review — enquanto houver Story pendente, a Feature fica em 🚧 Desenvolvimento. Etapa só avança (nunca volta); Status mede o progresso dentro da etapa.
+
+### `@spec-wave/cli doctor` — preflight de auth e configuração (comando LOCAL)
+Sem flags. Roda um checklist de diagnóstico no repositório atual: token GitHub (e a fonte dele), escopos (`repo`, `project`, `workflow` — com degradação para checks funcionais em fine-grained PATs), conta ativa do `gh` vs. owner, `.spec-wave.json` (campos e sincronia com o Project real), acesso ao repositório, configuração de IA (provider/modelo/`ai.models` + secrets do Actions) e presença dos workflows.
+
+> Saída: `✓` ok, `✗` problema confirmado, `!` não verificável (best-effort — falha de rede nunca derruba o doctor). **Exit 1** se houver algum `✗`. **Quando rodar:** no início de uma sessão de trabalho, ou sempre que aparecer um erro estranho (ex.: **404 ao criar issues** — causa típica: token sem acesso ao repo/org, que o doctor aponta). É o primeiro passo de troubleshooting — prefira-o a depurar `gh api` na mão.
+
+### `@spec-wave/cli order <feature>` — ordem de execução das Stories (comando LOCAL)
+| Flag/Arg | Tipo | Descrição |
+|----------|------|-----------|
+| `<feature>` | string (obrigatório) | Número da issue da **Feature**, ex.: `12` ou `#12`. Argumento posicional. |
+
+> 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. 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.
+
+### `@spec-wave/cli task <start|done> <n>` — transições de Task no board (comando LOCAL)
+| Flag/Arg | Tipo | Descrição |
+|----------|------|-----------|
+| `<action>` | string (obrigatório) | `start` (Etapa 🚧 Desenvolvimento + Status In Progress) ou `done` (Etapa 🎉 Done + Status Done). |
+| `<n>` | string (obrigatório) | Número da issue da **Task**, ex.: `12` ou `#12`. |
+
+> **Prefira este comando a mexer no board via GraphQL/`gh` manual** — ele embute as regras do fluxo: a **Etapa nunca retrocede** (se já estiver adiante, só o Status é ajustado) e **uma única Task "In Progress" por vez** dentro da mesma Story (`start` recusa, apontando a Task em andamento, se houver outra irmã em In Progress).
+
+### `@spec-wave/cli story review <n>` — move a Story para Code Review (comando LOCAL)
+| Flag/Arg | Tipo | Descrição |
+|----------|------|-----------|
+| `<action>` | string (obrigatório) | `review` (única ação hoje). |
+| `<n>` | string (obrigatório) | Número da issue da **Story**, ex.: `12` ou `#12`. |
+
+> Avança a Story para a Etapa **👀 Code Review** com Status **Todo** (o Status reinicia ao trocar de etapa). Mesma regra do `task`: a **Etapa nunca retrocede** — se a Story já estiver em Code Review ou adiante, o comando apenas informa a Etapa atual. Use no fim do `implement` de uma Story, em vez de mutações GraphQL manuais.
+
+---
+
+## Crítica adversarial, idempotência e dependências (v0.7)
+
+### Crítica adversarial (comentário 🔎)
+
+Após o `generate-plan` e **antes** da criação de issues no `decompose`, um segundo agente de IA critica os documentos procurando contradições, lacunas e riscos. O resultado vira um comentário **🔎 Crítica adversarial (spec-wave)** na issue.
+
+- Findings **graves** → o Action aplica a label **`spec-wave:critique-failed`**, que **bloqueia o `spec-wave:ready`** (o `validate` falha enquanto ela existir).
+- **Fluxo de resolução:** (1) leia o comentário 🔎 na issue; (2) corrija `spec.md`/`plan.md` (regenere com as labels ou edite e commite); (3) remova a label: `gh issue edit <n> --remove-label "spec-wave:critique-failed"`; (4) re-aplique `spec-wave:ready` para validar de novo.
+- Findings leves não bloqueiam — trate-os como revisão de qualidade.
+
+### Guard de idempotência do decompose (`spec-wave:decomposed`)
+
+O evento `labeled` pode redisparar (re-add da label, retry de runner). Para não duplicar Stories/Tasks, o `decompose` **pula** quando a issue já tem a label **`spec-wave:decomposed`** ou já tem sub-issues do tipo-alvo (`[STORY]` para Feature, `[TASK]` para RFC). Ao concluir com sucesso, o Action grava a label. Os workflows ainda usam `concurrency` por issue para serializar runs simultâneos.
+
+**Para forçar um re-decompose:** remova a label (`gh issue edit <n> --remove-label "spec-wave:decomposed"`), **apague/feche as sub-issues antigas** (senão a detecção por sub-issues pula de novo) e re-adicione `spec-wave:decompose`.
+
+### Dependências entre Stories (`Depende de: #N`)
+
+O `decompose` grava nas Stories geradas uma linha **`Depende de: #N, #M`** no corpo e cria a relação nativa *blocked by* do GitHub. Essas dependências alimentam:
+- `spec-wave order <feature>` → ordem topológica de execução;
+- `spec-wave implement <n>` → **aviso** no contexto quando uma dependência ainda não está concluída (confirme com o usuário antes de implementar fora de ordem).
+
+Não apague a linha `Depende de:` ao editar o corpo de uma Story; para mudar dependências, edite a linha (e/ou a relação *blocked by*).
+
+### Modelo de IA por ação (`ai.models` no `.spec-wave.json`)
+
+Cada ação de IA (`spec`, `plan`, `decompose`, `critique`) pode usar um modelo próprio, com fallback em `ai.model` e depois no default do provider:
+
+```json
+{
+  "ai": {
+    "provider": "anthropic",
+    "model": "claude-sonnet-4-6",
+    "models": {
+      "plan": "claude-opus-4-1",
+      "critique": "claude-opus-4-1"
+    }
+  }
+}
+```
+
+Edite o bloco `ai` no `.spec-wave.json` (e commite) — o `doctor` mostra o provider, o modelo e os overrides de `ai.models` resolvidos.
 
 ---
 
@@ -232,6 +313,8 @@ Crie um work item tipado (Initiative/Epic/Feature/Story/Task/...) já adicionado
 
 **Hierarquia típica:** Initiative → Epic → Feature → Story → Task. A **Initiative** é o nó raiz e agrupa Epics. Use `--parent <n>` para criar como sub-issue do nível acima (ex.: um Epic filho de uma Initiative, ou uma Story filha de uma Feature). O GitHub mostra o parent na issue filha e vice-versa; a CLI ainda grava `Parent: #N` no corpo.
 
+> **Spike é movido manualmente:** o spec-wave **nunca** avança a Etapa de um Spike automaticamente (nem no `implement`, nem nas Actions de Code Review/QA). O Spike entra no board em 📥 Backlog e o **usuário** o move à mão pelas etapas. Não mova a Etapa de um Spike por conta própria — a não ser que o usuário peça explicitamente.
+
 **Passos:**
 1. Pergunte ao usuário: tipo (initiative/epic/feature/story/task/...), título (sem prefixo), descrição e se há uma issue **pai** (número). **Prioridade e área são opcionais**: só as inclua se o usuário pedir explicitamente. **Nunca atribua uma prioridade por conta própria** — se o usuário não informou, **omita `--priority`** e a prioridade fica `null` (sem prioridade) no board.
 2. Execute o comando com os parâmetros coletados (inclua **apenas** as flags que o usuário forneceu):
@@ -267,14 +350,17 @@ Remove a configuração do spec-wave do repositório (labels, arquivos `.github`
 
 Inicia a geração da **especificação funcional** para uma Feature. É o **primeiro** passo do ciclo de documentos (antes do plano técnico).
 
+> **Apenas Features.** spec/plan **não** são gerados para **Spike, RFC ou Bug** — se a label for adicionada a um desses, o Action pula a geração, remove a label e comenta. Não use `/spec-wave spec|plan` nesses tipos.
+
 **Passos:**
-1. Adicione a label de gatilho:
+1. Confirme que a issue é uma **Feature** (spec/plan não se aplicam a Spike/RFC/Bug).
+2. Adicione a label de gatilho:
    ```bash
    gh issue edit <número> --add-label "spec-wave:spec"
    ```
-2. Informe: "Label `spec-wave:spec` adicionada. O GitHub Action `generate-spec.yml` irá gerar o `spec.md` automaticamente."
-3. Após a conclusão, ofereça revisar o spec.md gerado em `docs/features/<slug>/spec.md`.
-4. Próximo passo: gerar o plano técnico — mova para **📋 Plan** e use `/spec-wave plan <número>`.
+3. Informe: "Label `spec-wave:spec` adicionada. O GitHub Action `generate-spec.yml` irá gerar o `spec.md` automaticamente."
+4. Após a conclusão, ofereça revisar o spec.md gerado em `docs/features/<slug>/spec.md`.
+5. Próximo passo: gerar o plano técnico — mova para **📋 Plan** e use `/spec-wave plan <número>`.
 
 ---
 
@@ -364,22 +450,28 @@ Valida que spec.md e plan.md estão completos e a Feature pode avançar.
    ```
 2. Informe: "Validação iniciada. O workflow verificará se spec.md e plan.md contêm todas as seções obrigatórias."
 3. Se a validação falhar, o workflow comentará os problemas na issue e adicionará automaticamente `spec-wave:spec`. Informe o usuário para corrigir e tentar novamente.
-4. Se passar, oriente: "Feature validada! Mova o card para **✅ Ready** e depois para **📋 Backlog Técnico** para iniciar a decomposição."
+4. **Se a issue tiver a label `spec-wave:critique-failed`**, a validação falha de imediato: a crítica adversarial apontou contradições graves (comentário 🔎 na issue). Siga o fluxo de resolução da seção *Crítica adversarial*: corrigir os documentos → remover a label → re-aplicar `spec-wave:ready`.
+5. Se passar, oriente: "Feature validada! Mova o card para **✅ Ready** e depois para **📋 Backlog Técnico** para iniciar a decomposição."
 
 ---
 
 ### `/spec-wave decompose <número-da-issue>`
 
-Decompõe uma Feature em Stories e Tasks automaticamente.
+Decompõe automaticamente. Aplica-se a **dois tipos**:
+- **Feature** → gera **Stories** (cada uma com suas **Tasks**), a partir de `spec.md` + `plan.md`.
+- **RFC** → gera **Tasks diretamente** (sem Stories), a partir da descrição do RFC.
+
+Para qualquer outro tipo (Spike, Bug, Story, Task, …) o Action **recusa** e comenta.
 
 **Passos:**
-1. Confirme que a Feature está em **✅ Ready** (spec.md e plan.md validados)
+1. Para **Feature**: confirme que está em **✅ Ready** (spec.md e plan.md validados). Para **RFC**: basta a descrição estar completa (RFC não usa spec/plan).
 2. Adicione a label de decomposição:
    ```bash
    gh issue edit <número> --add-label "spec-wave:decompose"
    ```
-3. Informe: "Decomposição iniciada. O workflow gerará Stories e Tasks baseados em spec.md e plan.md."
-4. Após a conclusão, as issues filhas aparecerão como comentário na Feature pai.
+3. Informe: "Decomposição iniciada — Feature gera Stories+Tasks; RFC gera Tasks."
+4. Após a conclusão, as issues filhas aparecerão como comentário na issue pai, junto com o comentário 🔎 da crítica adversarial. As Stories geradas trazem a linha `Depende de: #N` (+ relação *blocked by*) — use `npx @spec-wave/cli order <número>` para ver a ordem de execução.
+5. A issue recebe a label `spec-wave:decomposed` (guard de idempotência): rodar de novo **não** duplica as issues. Para forçar um re-decompose, siga a seção *Guard de idempotência*.
 
 ---
 
@@ -396,7 +488,7 @@ Aciona o spec-kit para implementar uma **Story** (todas as suas Tasks) ou uma **
    npx @spec-wave/cli implement <número> --dry-run
    ```
 3. Mostre ao usuário o contexto montado em `.spec-wave/implement-<número>.md` e o comando. Esse arquivo contém as **instruções de execução sequencial**: implemente as Tasks **uma por vez** — mova a task para **🚧 Desenvolvimento** só ao iniciá-la e para **🎉 Done** ao concluí-la, antes de passar para a próxima. **Nunca** coloque várias tasks em "in progress" ao mesmo tempo.
-4. **Se você (agente) for implementar diretamente** (sem `specKit.command`): siga o contexto task por task. Para cada task: Status → In Progress *dentro* da Etapa 🚧 Desenvolvimento e, **ao concluir, avance a task para a Etapa 🎉 Done com Status Done**. Atualize os campos via `gh`. **Ao concluir toda a Story**: faça o commit, abra o PR e **avance a Etapa da Story para 👀 Code Review** (Status → Todo) — as Tasks já estão em 🎉 Done. A **Feature só avança** quando **TODAS as suas Stories** já estiverem em Code Review — se houver Story pendente, deixe a Feature em 🚧 Desenvolvimento. Lembre: Etapa só avança (nunca volta); Status é o progresso dentro da etapa.
+4. **Se você (agente) for implementar diretamente** (sem `specKit.command`): siga o contexto task por task. Para cada task: `npx @spec-wave/cli task start <n>` ao iniciar (Etapa 🚧 Desenvolvimento + Status In Progress) e `npx @spec-wave/cli task done <n>` ao concluir (Etapa 🎉 Done + Status Done) — **prefira esses comandos a mutações GraphQL/`gh` manuais**: eles embutem as regras do board (Etapa nunca retrocede; uma task In Progress por vez). Se o contexto trouxer **aviso de dependência pendente** (a issue depende de outra não concluída), confirme com o usuário antes de seguir. **Ao concluir toda a Story**: faça o commit, abra o PR e mova a Story com `npx @spec-wave/cli story review <n>` (Etapa 👀 Code Review, Status → Todo) — as Tasks já estão em 🎉 Done. A **Feature só avança** quando **TODAS as suas Stories** já estiverem em Code Review — se houver Story pendente, deixe a Feature em 🚧 Desenvolvimento. Lembre: Etapa só avança (nunca volta); Status é o progresso dentro da etapa.
 5. Se o usuário aprovar e o spec-kit estiver configurado, rode sem `--dry-run`:
    ```bash
    npx @spec-wave/cli implement <número>

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

@@ -4,6 +4,10 @@ on:
   pull_request:
     types: [opened, reopened]
 
+concurrency:
+  group: spec-wave-code-review-${{ github.event.pull_request.number }}
+  cancel-in-progress: false
+
 jobs:
   code-review:
     runs-on: ubuntu-latest

package/src/templates/workflows/decompose.yml

@@ -4,6 +4,13 @@ on:
   issues:
     types: [labeled]
 
+# O evento `labeled` pode redisparar (re-add da label, retry de runner):
+# o concurrency serializa runs da mesma issue e o guard de idempotência
+# (label spec-wave:decomposed) descarta o run enfileirado.
+concurrency:
+  group: spec-wave-decompose-${{ github.event.issue.number }}
+  cancel-in-progress: false
+
 jobs:
   decompose:
     if: >

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

@@ -4,6 +4,10 @@ on:
   issues:
     types: [labeled]
 
+concurrency:
+  group: spec-wave-generate-plan-${{ github.event.issue.number }}
+  cancel-in-progress: false
+
 jobs:
   generate-plan:
     if: >

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

@@ -4,6 +4,10 @@ on:
   issues:
     types: [labeled]
 
+concurrency:
+  group: spec-wave-generate-spec-${{ github.event.issue.number }}
+  cancel-in-progress: false
+
 jobs:
   generate-spec:
     if: >

package/src/templates/workflows/qa.yml

@@ -4,6 +4,10 @@ on:
   pull_request_review:
     types: [submitted]
 
+concurrency:
+  group: spec-wave-qa-${{ github.event.pull_request.number }}
+  cancel-in-progress: false
+
 jobs:
   qa:
     if: github.event.review.state == 'approved'

package/src/templates/workflows/validate.yml

@@ -4,6 +4,10 @@ on:
   issues:
     types: [labeled]
 
+concurrency:
+  group: spec-wave-validate-${{ github.event.issue.number }}
+  cancel-in-progress: false
+
 jobs:
   validate:
     if: >

package/src/ui/wizard.mjs

@@ -1,6 +1,6 @@
 import * as p from '@clack/prompts';
 import { execSync } from 'node:child_process';
-import { AI_PROVIDERS, getProvider, DEFAULT_PROVIDER } from '../config.mjs';
+import { AI_PROVIDERS, getProvider, DEFAULT_PROVIDER, WORKFLOW_FILES, ISSUE_TEMPLATE_FILES } from '../config.mjs';
 
 export async function runWizard() {
   p.intro('spec-wave — configuração do fluxo spec-driven');
@@ -62,7 +62,7 @@ export async function runWizard() {
 
       confirm: ({ results }) =>
         p.confirm({
-          message: `Configurar ${results.repo} com GitHub Project "${results.projectTitle}"?\n  - 12 colunas kanban\n  - 5 campos customizados\n  - 15 labels\n  - 4 workflows + 2 issue templates`,
+          message: `Configurar ${results.repo} com GitHub Project "${results.projectTitle}"?\n  - 12 colunas kanban\n  - 5 campos customizados\n  - 15 labels\n  - ${WORKFLOW_FILES.length} workflows + ${ISSUE_TEMPLATE_FILES.length} issue templates`,
           initialValue: true,
         }),
     },