@spec-wave/cli 0.27.0 → 0.28.0

package/src/commands/update.mjs

@@ -12,7 +12,7 @@ import {
 } from '../api/github-rest.mjs';
 import {
   resolveBranchName, composePrTitle, composePrBody, buildCommitMessage,
-  decideConfigInPr, explainGitWriteError,
+  decideConfigInPr, decideSkillInPr, composeConfigCleanupHint, explainGitWriteError,
 } from '../lib/pr-branch.mjs';
 // MESMO readTemplate do init: resolve {{CLI_VERSION}} antes da comparação byte a
 // byte com o remoto. Se só o init resolvesse, todo update veria os workflows
@@ -20,10 +20,11 @@ import {
 import { readTemplate } from '../lib/templates.mjs';
 import {
   TARGETS, SKILL_SOURCE, CLI_VERSION, parseSkill, renderContent,
-  mergeAgentsFile, resolveDest, isDetected, skillCopyReason, versionBanner,
+  mergeAgentsFile, mergeAgentsContent, resolveDest, isDetected, skillCopyReason, versionBanner,
 } from './install-skill.mjs';
 import { planPluginSkillFiles } from '../lib/plugin-skills.mjs';
 import { findConfigPath } from '../lib/project-root.mjs';
+import { currentGitBranch } from '../lib/repo-links.mjs';
 
 // Arquivos do repo gerenciados pela CLI (comparados com o template empacotado).
 const REPO_FILES = [
@@ -68,6 +69,41 @@ function applySkill(job) {
   writeFileSync(job.dest.path, content, 'utf-8');
 }
 
+/**
+ * Arquivos que uma atualização de skill grava, em caminhos RELATIVOS à raiz do
+ * repositório — a chave para perguntar à base se aquela cópia é versionada.
+ *
+ * Devolve [] quando o destino cai FORA da raiz, e é o que dispensa um caso
+ * especial para `--global`: `~/.claude/skills/...` e o `~/.gemini/AGENTS.md` do
+ * Antigravity jamais são conteúdo de repositório, e `path.relative` já diz isso.
+ *
+ * O formato `agents` (AGENTS.md) devolve `block` em vez de `content`: o conteúdo
+ * final depende do que existe na BASE — mesclar no arquivo local arrastaria para
+ * dentro do PR as edições não commitadas do desenvolvedor.
+ *
+ * @param {{dest: {path: string, format: string}, desired?: string}} job
+ * @param {string} repoRoot
+ * @returns {Array<{ relPath: string, content?: string, block?: string }>}
+ */
+export function skillRepoTargets(job, repoRoot) {
+  const items = job.dest.format === 'skills-dir'
+    ? planPluginSkillFiles(job.dest.path, CLI_VERSION, versionBanner)
+        .map(f => ({ absPath: f.path, content: f.content }))
+    : [{
+        absPath: job.dest.path,
+        ...(job.dest.format === 'agents' ? { block: job.desired } : { content: job.desired }),
+      }];
+
+  const out = [];
+  for (const { absPath, ...rest } of items) {
+    const rel = path.relative(repoRoot, absPath);
+    if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) continue;
+    // A API do GitHub fala POSIX; path.relative devolve no separador do SO.
+    out.push({ ...rest, relPath: rel.split(path.sep).join('/') });
+  }
+  return out;
+}
+
 /**
  * Compara ALL_LABELS com as labels do repo (função PURA — testável).
  *
@@ -325,6 +361,70 @@ export async function update(options = {}) {
     }
   }
 
+  // 2d) Skill: a BASE versiona alguma destas cópias?
+  //
+  // Até aqui o update gravava a skill em disco e o corpo do PR AFIRMAVA ao
+  // revisor que ela "não faz parte do repositório" — premissa fixa. Em repos que
+  // versionam `.claude/skills/spec-wave/SKILL.md` (ou `.agents/skills/`, ou o
+  // AGENTS.md) isso era falso duas vezes: sobrava um commit manual a cada bump, e
+  // até ele o repositório seguia distribuindo a skill da versão anterior para
+  // quem clonasse. A checagem é a MESMA do .spec-wave.json — perguntar à base —,
+  // e a política também: só entra no PR o que o projeto já versiona.
+  let skillPrFiles = [];        // [{ relPath, content, reason, agent }]
+  // agente → motivo da PRIMEIRA cópia incluída. É o motivo que o resumo mostra:
+  // dizer "versionada no repo" para uma cópia que entrou por `--skill-in-pr`
+  // seria repetir, em miniatura, a premissa que este código veio corrigir.
+  const skillPrAgents = new Map();
+  // `skillRepoTargets` já devolve vazio para o que mora fora da raiz, o que cobre
+  // o `--global` inteiro sem um caso especial: nada a perguntar, nada a gastar.
+  const skillCandidates = prMode
+    ? skillJobs
+        .map(job => ({ job, targets: skillRepoTargets(job, path.dirname(configPath)) }))
+        .filter(c => c.targets.length)
+    : [];
+  if (skillCandidates.length) {
+    const tk = await getToken();
+    const s = p.spinner();
+    s.start('Verificando se o repositório versiona a skill...');
+    try {
+      for (const { job, targets } of skillCandidates) {
+        // Em paralelo: o destino do Codex são 20+ arquivos, e um GET por vez
+        // transformaria a checagem na parte mais lenta do comando.
+        const remotes = await Promise.all(
+          targets.map(t => getFileContent(tk, owner, repo, t.relPath, base))
+        );
+        targets.forEach((t, i) => {
+          const remote = remotes[i];
+          const desired = t.block !== undefined
+            ? mergeAgentsContent(remote ?? '', t.block)
+            : t.content;
+          const d = decideSkillInPr({ remote, desired, force: options.skillInPr });
+          if (!d.included) return;
+          skillPrFiles.push({
+            relPath: t.relPath,
+            content: desired,
+            reason: remote == null ? 'ausente' : 'desatualizado',
+            agent: job.target.name,
+          });
+          if (!skillPrAgents.has(job.target.name)) skillPrAgents.set(job.target.name, d.reason);
+        });
+      }
+      s.stop(skillPrFiles.length
+        ? `Skill versionada no repositório: ${skillPrFiles.length} arquivo(s) vão no Pull Request.`
+        : 'A skill não é versionada neste repositório — segue apenas local.');
+    } catch (err) {
+      // Falhar aqui não pode custar o update inteiro: sem a resposta da base, a
+      // skill volta a ser só local — o comportamento anterior, agora explícito.
+      s.stop('');
+      p.log.warn(`Não foi possível checar a skill na base: ${err.message} — ela seguirá apenas local.`);
+      skillPrFiles = [];
+      skillPrAgents.clear();
+    }
+  }
+  const skillLocalAgents = skillJobs
+    .map(j => j.target.name)
+    .filter(n => !skillPrAgents.has(n));
+
   // Decisão preliminar sobre o config. O conteúdo regenerado ainda não existe;
   // `willRegenerate` cobre isso, porque o regenerado SEMPRE difere do remoto
   // (refreshedAt muda a cada execução). Na aplicação a decisão é recalculada com
@@ -355,21 +455,39 @@ export async function update(options = {}) {
   const lines = [];
   if (skillJobs.length) {
     lines.push(chalk.bold('Skill:'));
-    for (const j of skillJobs) lines.push(`  ${chalk.yellow('↻')} ${j.target.name} (${j.reason})\n     ${chalk.dim(j.dest.path)}`);
+    for (const j of skillJobs) {
+      const destino = skillPrAgents.has(j.target.name)
+        ? chalk.dim(` → vai no PR: ${skillPrAgents.get(j.target.name)}`)
+        : '';
+      lines.push(`  ${chalk.yellow('↻')} ${j.target.name} (${j.reason})${destino}\n     ${chalk.dim(j.dest.path)}`);
+    }
   }
   if (configStale) {
     lines.push(chalk.bold('Config local:'));
     lines.push(`  ${chalk.yellow('↻')} ${CONFIG_FILE} — ${configStale.reason}` +
       (configStale.canApply ? '' : chalk.dim(' (sem project.id — rode `init` sem --skip-project)')));
   }
+  // Cabeçalho ÚNICO no modo PR: workflows, skill e config viajam no mesmo commit,
+  // e três títulos para um commit só sugeriam três destinos diferentes.
+  let prHeaderShown = false;
+  const prHeader = () => {
+    if (prHeaderShown) return;
+    prHeaderShown = true;
+    lines.push(chalk.bold(`Pull Request (${branch} → ${base}):`));
+  };
   if (repoFiles.length) {
-    lines.push(prMode
-      ? chalk.bold(`Arquivos do repo → Pull Request (${branch} → ${base}):`)
-      : chalk.bold('Arquivos do repo:'));
+    if (prMode) prHeader();
+    else lines.push(chalk.bold('Arquivos do repo:'));
     for (const f of repoFiles) lines.push(`  ${chalk.yellow('↻')} ${f.repoPath} (${f.reason})`);
   }
+  if (skillPrFiles.length) {
+    prHeader();
+    for (const f of skillPrFiles) {
+      lines.push(`  ${chalk.yellow('↻')} ${f.relPath} (${f.reason} — skill ${f.agent})`);
+    }
+  }
   if (prMode && configDecision.included) {
-    if (!repoFiles.length) lines.push(chalk.bold(`Pull Request (${branch} → ${base}):`));
+    prHeader();
     lines.push(`  ${chalk.yellow('↻')} ${CONFIG_FILE} (${configDecision.reason})`);
   }
   if (prMode && doConfig && !configDecision.included && configDecision.reason) {
@@ -388,7 +506,8 @@ export async function update(options = {}) {
   p.note(lines.join('\n'), `${total} item(ns) desatualizado(s)`);
 
   // --branch sem efeito: melhor dizer POR QUE do que criar uma branch inútil.
-  const prHasPayload = prMode && (repoFiles.length > 0 || configDecision.included);
+  const prHasPayload = prMode
+    && (repoFiles.length > 0 || skillPrFiles.length > 0 || configDecision.included);
   if (prRequested && options.skipRepo) {
     p.log.warn(
       '--branch ignorado junto com --skip-repo: o Pull Request existe justamente para ' +
@@ -408,7 +527,7 @@ export async function update(options = {}) {
 
   if (options.dryRun) {
     if (prHasPayload) {
-      const n = repoFiles.length + (configDecision.included ? 1 : 0);
+      const n = repoFiles.length + skillPrFiles.length + (configDecision.included ? 1 : 0);
       p.note(
         `Branch:    ${branch}${branchExists ? ' (já existe — o commit seria empilhado nela)' : ' (seria criada)'}\n` +
         `Base:      ${base}\n` +
@@ -516,6 +635,11 @@ export async function update(options = {}) {
     const tk = await getToken();
     const treeFiles = [
       ...repoFiles.map(f => ({ path: f.repoPath, reason: f.reason, content: f.local })),
+      ...skillPrFiles.map(f => ({
+        path: f.relPath,
+        reason: `${f.reason} — skill ${f.agent}`,
+        content: f.content,
+      })),
       ...(finalConfigDecision.included
         ? [{
             path: CONFIG_FILE,
@@ -562,7 +686,7 @@ export async function update(options = {}) {
               files: treeFiles,
               config: doConfig ? finalConfigDecision : null,
               labels: labelResult,
-              skill: skillJobs.map(j => j.target.name),
+              skill: { inPr: [...skillPrAgents.keys()], local: skillLocalAgents },
             }),
           });
           if (!pr) {
@@ -605,9 +729,16 @@ export async function update(options = {}) {
     (prUrl ? ` Revise e faça o merge do Pull Request: ${prUrl}` : '') +
     (!prMode && repoFiles.length ? ' Arquivos do repo foram commitados no remoto.' : '') +
     (configPending ? ` COMMITE o ${CONFIG_FILE} — quem clona o repo (dev-agent, Actions) lê a versão commitada.` : '') +
+    // A dica de descarte depende da branch do CHECKOUT, não de premissa:
+    // `git checkout -- <arquivo>` restaura o que está no índice, e rodado de uma
+    // branch de trabalho reverte o arquivo para a versão ANTIGA dela — o oposto
+    // do que a mensagem promete.
     (finalConfigDecision.included
-      ? ` O ${CONFIG_FILE} local ficou igual ao do PR — depois do merge, descarte a cópia ` +
-        `local com \`git checkout -- ${CONFIG_FILE}\`.`
+      ? ` ${composeConfigCleanupHint({
+          file: CONFIG_FILE,
+          base,
+          current: currentGitBranch(path.dirname(configPath)),
+        })}`
       : '')
   );
 }

package/src/lib/pr-branch.mjs

@@ -130,7 +130,11 @@ export function buildCommitMessage({ version = CLI_VERSION, files = [] } = {}) {
  * @param {{created: string[], updated: string[], removed: string[]}|null} [a.labels]
  *        labels EFETIVAMENTE aplicadas (não o diff detectado — o corpo não pode
  *        prometer o que falhou)
- * @param {string[]} [a.skill] nomes dos agentes cuja skill foi atualizada localmente
+ * @param {string[]|{inPr?: string[], local?: string[]}} [a.skill] agentes cuja
+ *        skill foi atualizada: `inPr` os que entraram no commit (a cópia da skill
+ *        É versionada na base) e `local` os que ficaram só na máquina. Um array
+ *        simples é lido como `local` — a forma antiga, de quando a skill nunca
+ *        entrava no PR.
  * @returns {string} markdown
  */
 export function composePrBody({
@@ -173,14 +177,31 @@ export function composePrBody({
     if (labels.removed.length) l.push(`- removidas (descontinuadas): ${labels.removed.map(n => `\`${n}\``).join(', ')}`);
   }
 
-  if (skill.length) {
+  // A skill não é mais declarada "fora do repositório" por premissa: quem chama
+  // consultou a base arquivo a arquivo (decideSkillInPr) e diz aqui o que
+  // realmente aconteceu. Afirmar "não faz parte do repositório" para um repo que
+  // versiona `.claude/skills/spec-wave/SKILL.md` mandava o revisor aprovar um PR
+  // incompleto — e deixava o repositório distribuindo a skill da versão anterior.
+  const skillInPr = Array.isArray(skill) ? [] : (skill?.inPr ?? []);
+  const skillLocal = Array.isArray(skill) ? skill : (skill?.local ?? []);
+  if (skillInPr.length || skillLocal.length) {
     l.push('');
-    l.push('## Skill dos agentes — fora deste PR');
+    l.push('## Skill dos agentes');
     l.push('');
-    l.push(
-      `Atualizada localmente em: ${skill.map(n => `\`${n}\``).join(', ')}. ` +
-      'Não faz parte do repositório.'
-    );
+    if (skillInPr.length) {
+      l.push(
+        `Incluída neste PR, nos arquivos listados acima: ${skillInPr.map(n => `\`${n}\``).join(', ')}. ` +
+        `Esta cópia da skill é conteúdo do repositório — o merge em \`${base}\` é o que a ` +
+        'entrega a quem clonar.'
+      );
+    }
+    if (skillLocal.length) {
+      if (skillInPr.length) l.push('');
+      l.push(
+        `Atualizada só na máquina local: ${skillLocal.map(n => `\`${n}\``).join(', ')}. ` +
+        'Esta cópia não é versionada no repositório e não faz parte deste PR.'
+      );
+    }
   }
 
   l.push('');
@@ -235,6 +256,74 @@ export function decideConfigInPr({ remote, desired, willRegenerate = false, forc
   return { included: true, reason: 'versionado na base e divergente do local' };
 }
 
+/**
+ * Uma cópia da skill entra no PR? (função PURA)
+ *
+ * MESMA regra do .spec-wave.json, pelo mesmo motivo: onde o arquivo mora é
+ * decisão do projeto, e o update não pode mudá-la sozinho — nem passando a
+ * versionar o que ninguém commitou, nem deixando de atualizar o que o repositório
+ * já distribui. A diferença é que aqui não existe `willRegenerate`: o conteúdo
+ * desejado da skill é renderizado do pacote e já está pronto na hora de decidir.
+ *
+ * Vale por ARQUIVO, não por agente: o destino do Codex (`.agents/skills/`) são 20+
+ * arquivos, e nada garante que o repositório versione todos.
+ *
+ * @param {object} [a]
+ * @param {string|null|undefined} [a.remote] conteúdo do arquivo na base (null/undefined = não versionado)
+ * @param {string|null} [a.desired] conteúdo que a instalação local grava
+ * @param {boolean|undefined} [a.force] undefined | true (--skill-in-pr) | false (--no-skill-in-pr)
+ * @returns {{ included: boolean, reason: string }}
+ */
+export function decideSkillInPr({ remote, desired, force } = {}) {
+  const versioned = remote !== null && remote !== undefined;
+  if (force === false) return { included: false, reason: '--no-skill-in-pr' };
+  if (!desired) return { included: false, reason: 'sem conteúdo local para enviar' };
+  if (force === true) {
+    return versioned
+      ? { included: true, reason: '--skill-in-pr' }
+      : { included: true, reason: '--skill-in-pr (passa a versionar a skill)' };
+  }
+  if (!versioned) {
+    return {
+      included: false,
+      reason: 'não está versionada na base, segue apenas local ' +
+        '(use --skill-in-pr para versioná-la)',
+    };
+  }
+  if (remote === desired) return { included: false, reason: 'já idêntica na base' };
+  return { included: true, reason: 'versionada na base e divergente do local' };
+}
+
+/**
+ * Dica para descartar a cópia local de um arquivo que também foi no PR (PURA).
+ *
+ * `git checkout -- <arquivo>` restaura a versão do ÍNDICE, isto é, a do HEAD da
+ * branch que está no checkout. Ele só descarta uma cópia redundante quando o
+ * clone está na base; rodado de uma branch de trabalho, faz o oposto do que a
+ * mensagem promete — reverte o arquivo para a versão antiga daquela branch. A
+ * dica, portanto, depende da branch corrente, que a CLI já sabe consultar.
+ *
+ * @param {object} [a]
+ * @param {string} [a.file] caminho do arquivo, relativo à raiz
+ * @param {string} [a.base] branch base do Pull Request
+ * @param {string|null} [a.current] branch do clone local (null = detached/fora de git)
+ * @returns {string} frase única, para o `outro` do comando
+ */
+export function composeConfigCleanupHint({ file = CONFIG_FILE, base = 'main', current = null } = {}) {
+  const cabeca = `O ${file} local ficou igual ao do PR`;
+  if (current === base) {
+    return `${cabeca} — depois do merge, descarte a cópia local com ` +
+      `\`git checkout -- ${file}\` antes do \`git pull\`.`;
+  }
+  const onde = current
+    ? `o checkout está em "${current}", e \`git checkout -- ${file}\` ali restauraria a ` +
+      'versão antiga dessa branch'
+    : `o checkout não está numa branch, e \`git checkout -- ${file}\` ali restauraria a ` +
+      'versão antiga do HEAD atual';
+  return `${cabeca} — ${onde}. Depois do merge, descarte a cópia local na base: ` +
+    `\`git switch ${base} && git checkout -- ${file}\`.`;
+}
+
 /**
  * Traduz o erro cru da Git Data API para uma dica acionável (função PURA).
  *

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

@@ -1,7 +1,7 @@
 {
   "name": "spec-wave",
   "displayName": "Spec Wave",
-  "version": "0.27.0",
+  "version": "0.28.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/README.md

@@ -18,6 +18,11 @@ carrega só a sua instrução.
 | `plan` | Gera `plan.md` (2º documento) + `tech_context.yml` |
 | `ready` | Valida spec + plan |
 | `decompose` | Rascunho revisável → Stories/Tasks |
+| `preparar-feature` | Orquestra: da spec até ✅ Ready, com Stories e Tasks criadas |
+| `preparar-specs` | Orquestra: as specs de uma milestone inteira |
+| `run` | Executa o próximo passo localmente (`run`/`mode`) |
+| `bug` | Fluxo do Bug: `bug.md`, triagem, correção |
+| `triage` | Tria um Bug: accept / reject / duplicate |
 | `order` | Ordem topológica das Stories |
 | `implement` | Etapa 🚧 Desenvolvimento |
 | `task` | `start` / `done` de uma Task |

package/src/plugin/skills/preparar-feature/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: spec-wave-preparar-feature
+description: "Use para conduzir uma Feature do spec-wave pelo trecho que vai da spec pronta até ✅ Ready com as Stories e Tasks criadas no board: gera o plan.md, trata a crítica adversarial, valida, move a etapa, decompõe e confere o resultado. Gatilhos: 'gerar o plano', 'preparar a feature 12', 'deixar pronta para o dev', 'levar até ready', 'decompor a feature', 'roda o plan da #12'. Use mesmo quando o usuário nomear só um passo — os passos têm armadilhas encadeadas que só fazem sentido tratadas juntas. Para as specs de uma milestone inteira use preparar-specs; para um passo isolado e sem supervisão, as skills plan, ready ou decompose."
+allowed-tools:
+  - Bash(npx @spec-wave/cli@latest *)
+  - Bash(gh issue *)
+  - Bash(gh pr *)
+  - Bash(gh api *)
+  - Bash(git *)
+  - Read
+  - Edit
+  - Glob
+  - Grep
+---
+
+# Preparar Feature — de `spec.md` até ✅ Ready
+
+Conduz uma issue `[FEATURE]` pelo trecho do fluxo que vai da spec pronta até as Stories e Tasks criadas e visíveis no board.
+
+O valor desta skill não está em executar os passos — isso é fácil. Está em **saber o que verificar depois de cada um**. O fluxo tem pontos onde ele para em silêncio, e cada um já custou horas quando passou despercebido. Se você seguir só a sequência feliz, vai reportar sucesso sobre um estado quebrado.
+
+**Contexto:** leia `.spec-wave.json` (Read). Ausente → skill **setup**.
+
+## O ciclo, e por que ele não é uma sequência de comandos
+
+Cada passo publica o documento num **Pull Request próprio** (`spec-wave/<issue>-<doc>`), e o passo seguinte **lê da branch base**. O merge não é arrumação — é pré-requisito:
+
+```
+run --dry-run  →  run --yes  →  PR do documento  →  revisar  →  merge  →  git pull  →  próximo passo
+```
+
+Pular o merge não dá erro confuso: o `run` para e explica (`⛔ pr-pending`). Mas se você tentar contornar com `--step`, aí sim regenera por cima da revisão em curso e paga o modelo de novo.
+
+**Nada é gravado no seu checkout.** Não crie branch para "trabalhar nela", não commite documento à mão, não abra PR no fim — a CLI já faz tudo isso, uma vez por documento.
+
+## Modos de supervisão
+
+O padrão **para nos dois portões de julgamento** e pede aprovação: depois da crítica do plano, e antes do `decompose-apply`. Foi exatamente ali que a supervisão humana pegou defeitos reais — um plano que afirmava "esta feature não cria tabela" e trazia um `CREATE TABLE` logo abaixo, e uma task de E2E numa Story que não declarava depender do backend. A crítica automática passou pelos dois.
+
+Se o usuário pedir para você analisar e corrigir sozinho, siga — mas **leia cada artefato mesmo assim**. Não parar não é o mesmo que não olhar: corrija, siga, e registre no relatório final o que mudou e por quê.
+
+## Antes de começar
+
+Verifique tudo isto e **pare com um diagnóstico** se algo falhar:
+
+```bash
+npx @spec-wave/cli@latest --version                          # >= 0.27.0
+npx @spec-wave/cli@latest mode                               # actions ou local?
+gh issue view <n> --json labels,title -q '{t:.title,l:[.labels[].name]}'
+npx @spec-wave/cli@latest doctor
+```
+
+**O modo decide como você aciona cada passo**, e os dois são legítimos:
+
+| Modo | Aciona com | Observação |
+|---|---|---|
+| `actions` | a label (`spec-wave:plan`, `:ready`, `:decompose`…) | roda no CI |
+| `local` | `npx @spec-wave/cli@latest run <n>` | **não aplique label**: dispararia o Action e o passo rodaria duas vezes |
+
+Se o repositório está em `local`, aplicar uma label não gera nada — o job é pulado pelo `if: vars.SPEC_WAVE_EXECUTION != 'local'` e o run aparece verde e `skipped`, sem erro e sem documento. É o sintoma mais silencioso do fluxo. O caminho contrário também engana: em `actions`, o `run` não recusa, apenas avisa.
+
+Pare também se houver `spec-wave:critique-failed` ou `spec-wave:needs-human` — são portões humanos abertos de uma rodada anterior, e avançar por cima deles descarta a razão pela qual alguém parou.
+
+O slug vem do título da issue. Confirme olhando `docs/features/`, não deduza.
+
+### Onde começar depende do que já existe
+
+Não assuma que a Feature chega do zero — outra pessoa pode ter avançado antes de você. O `run --dry-run` responde isso sozinho, e é sempre o primeiro comando:
+
+```bash
+npx @spec-wave/cli@latest run <n> --dry-run
+```
+
+Ele diz o passo pendente e o motivo, olhando o disco, a branch base **e** as branches de artefato. **Se `plan.md` já existe, nunca force `--step plan`** — ele regera o documento do zero e descarta o que houver, inclusive revisão manual. Para corrigir um plano existente, `--step critique`.
+
+Leia também o último comentário 🔎 da issue; o marcador `<!-- spec-wave:critique kind=plan verdict=limpa -->` no topo diz o veredito sem você ter que interpretar o texto:
+
+```bash
+gh issue view <n> --comments --json comments -q '.comments[-1].body' | head -20
+```
+
+Um caso que o marcador revela: um `plan.md` gerado por um backend sem suporte a saída estruturada sai completo, mas a crítica aborta — e o comentário registra que o documento **não foi auditado**. Plano nunca auditado indo para `ready` é o sucesso aparente sobre estado não verificado que esta skill existe para evitar.
+
+### Os portões do `run`
+
+O `run` explica e para, saindo com código 2. Não force sem entender:
+
+| Portão | O que significa |
+|---|---|
+| `trigger-pending` | label de gatilho na issue. Em modo local ela é resíduo: **remova-a** em vez de usar `--force`, para a issue não mentir sobre o estado |
+| `pr-pending` | o documento está num PR aberto. Revise e mergeie — regerar descarta a revisão |
+| `branch-without-pr` | o commit passou e o PR não nasceu. Rode `doctor`: quase sempre é a opção de organização ou o `GH_PR_TOKEN` |
+| `stale-checkout` | o documento já está publicado na base e não no seu clone. `git pull` |
+| `needs-confirmation` | o passo cria issues. Revise o rascunho e confirme com `--apply` |
+| `inconsistent-state` | uma label afirma um documento que não existe — o título mudou depois de gerar? |
+
+### O modelo
+
+Para forçar um modelo num passo, aplique `spec-wave:model:<apelido>` — os apelidos válidos são os de `ai.modelAliases` no `.spec-wave.json`, e só esses. Um apelido que aponta para um modelo que o provider configurado não serve falha no passo, não na label.
+
+Confirme no log que o override pegou: `modelo: ... (origem: label)`.
+
+> **Uma lição que sobrevive à troca de provider:** quando um passo estoura o teto de turnos sem gerar nada, **troque o modelo antes de mexer no contexto**. Enxugar o `tech_context` em 14% não destravou nada, porque a entrada eram ~20k tokens; trocar o modelo entregou plano + crítica em minutos.
+
+---
+
+## 1 · Gerar o plano
+
+```bash
+npx @spec-wave/cli@latest run <n> --dry-run
+npx @spec-wave/cli@latest run <n> --yes
+```
+
+O `generate-plan` já critica o resultado ao final, no mesmo passo. O documento sai num PR.
+
+Antes deste passo, garanta que `.github/config/tech_context.yml` está **commitado e na base** — o passo lê o arquivo do repositório, não do seu disco.
+
+---
+
+## 2 · Tratar a crítica adversarial
+
+**Leia `reference/critica.md` antes de corrigir qualquer coisa.** Ele traz o que a crítica erra, como distinguir falso positivo de defeito real, e quando parar de iterar — é a parte desta skill que mais economiza tempo.
+
+O essencial:
+
+- **Confira o finding contra o arquivo antes de corrigir.** Cite o trecho que confirma ou refuta. É o que distingue "corrigi o que a IA mandou" de "verifiquei e o problema existe".
+- **Reaplique a crítica depois de editar**, mesmo com veredito `limpa` — ela é não-determinística, e a segunda passada costuma pegar a correção incompleta.
+- **Corrigir o documento à mão não é desvio** — é o que o fluxo pede quando a crítica reprova. Edite **no PR**, onde as edições são preservadas.
+
+Para recriticar sem regerar:
+
+```bash
+npx @spec-wave/cli@latest run <n> --yes --step critique
+```
+
+**`--step critique`, nunca `--step plan`.** O segundo regera o plano do zero e joga fora a correção — é o erro que faz o ciclo não convergir.
+
+Se aparecer `spec-wave:needs-human`, a crítica esgotou as tentativas. Pare e envolva o usuário — a label precisa sair à mão.
+
+**Mergeie o PR do plano antes de seguir.** O `validate` lê da base.
+
+---
+
+## 3 · Validar
+
+```bash
+npx @spec-wave/cli@latest run <n> --yes    # validate
+```
+
+Roda em segundos e **não usa IA**. Confere as seções obrigatórias de `spec.md` e `plan.md` e aplica `spec-wave:plan-approved`.
+
+### O validate NÃO move a etapa
+
+Primeiro ponto de parada silenciosa: a Feature passa na validação e **continua na etapa em que estava** — invisível na fila do TL, que lê `✅ Ready`. Nada no fluxo a move; o selo `plan-approved` é uma label, não uma coluna.
+
+```bash
+npx @spec-wave/cli@latest move <n> "ready"
+```
+
+Confirme depois lendo o board — a etapa nunca retrocede, então é melhor ver o estado do que supor.
+
+---
+
+## 4 · Decompor — o rascunho
+
+```bash
+npx @spec-wave/cli@latest run <n> --yes    # decompose
+```
+
+Gera `docs/features/<slug>/decomposition.md` e o critica. **Nenhuma issue é criada nesta etapa** — é de propósito, para haver um artefato revisável antes do irreversível.
+
+**Leia o rascunho e revise de verdade.** A crítica olha contradição com spec/plan; ela **não olha coerência do grafo de dependências**. O que vale conferir:
+
+- as linhas `**Depende de:**` refletem o que cada Story realmente precisa;
+- **nenhuma task de teste depende de coisa que a Story dela não declara** — já apareceu uma task pedindo E2E numa Story que declarava depender só da fundação; pelo grafo, ela rodaria antes de o backend existir e falharia;
+- identificadores com a grafia do domínio e sem acento, se essa for a convenção do repositório;
+- **nada contradiz as correções que você fez no `plan.md`** — isso precisa ser verificado, não presumido.
+
+Ao apresentar, mostre o grafo de dependências e a contagem de Stories/Tasks — é o que permite ao usuário julgar em segundos.
+
+Para corrigir, edite o `decomposition.md` **no PR** e reaplique `--step decompose`: o arquivo é criticado **como está**, não regerado. Recritique depois de editar mesmo que a passada anterior tenha vindo limpa.
+
+Se reprovar aqui, a superfície a corrigir é o **`decomposition.md`** — os achados citam `Story N` / `Task N.M`, que são títulos daquele arquivo. Confundir com o `plan.md` trava o ciclo.
+
+**Mas verifique se o defeito nasce no plano.** Já aconteceu de um achado apontar a `Task 4.1` com a causa no `plan.md`. Corrigir só o rascunho deixaria os dois divergentes, e a próxima geração traria o defeito de volta. Quando o achado descrever uma decisão técnica (e não um recorte de escopo), corrija nos dois.
+
+**Pare aqui e peça aprovação**, salvo instrução explícita em contrário. E mergeie o PR do rascunho: o apply lê da base.
+
+---
+
+## 5 · Aplicar
+
+```bash
+npx @spec-wave/cli@latest run <n> --yes --apply
+```
+
+**Isto é a aprovação humana** — não há nova crítica depois. É o passo mais caro de reverter: cria dezenas de issues, e desfazer exige fechar todas e remover `spec-wave:decomposed` à mão.
+
+### Sempre rode o detector depois
+
+```bash
+npx @spec-wave/cli@latest order <n>
+```
+
+Se aparecer **`Etapa: —`** nas Stories, o apply falhou no board **e saiu com sucesso** — o passo fica verde. As issues nascem sem etapa nenhuma, que é pior que Backlog: invisíveis em toda tela que filtra por etapa. A causa conhecida é o `GH_PROJECT_TOKEN` sem permissão de Projects na organização; o log mostra `Could not resolve to a node with the global id of 'PVT_...'`.
+
+O `order` só enxerga **Stories**. Confira as **Tasks por amostragem**, nas duas pontas da faixa de numeração criada.
+
+**Reparo**, uma issue por vez (cobre Etapa + Status, não o Work Item Type):
+
+```bash
+npx @spec-wave/cli@latest move <numero> "ready"
+```
+
+---
+
+## Relatório final
+
+Termine com o estado real, não com "concluído". O usuário precisa saber se pode mandar alguém pegar a Feature:
+
+```
+## <Feature> (#N) — <etapa atual>
+
+<grafo de dependências das Stories, com os números criados>
+
+| | |
+|---|---|
+| Documentos | spec.md · plan.md · decomposition.md |
+| Sub-issues | N Stories + M Tasks, todas em <etapa> |
+| PRs        | <os PRs de documento, e se foram mergeados> |
+
+### Correções aplicadas
+<o que você mudou no plan.md ou no decomposition.md, e por quê>
+
+### O que ainda bloqueia a implementação
+<ver abaixo>
+```
+
+### Verifique antes de dizer "pronta para o dev"
+
+Três coisas que o fluxo não checa e que já impediram a implementação de começar:
+
+1. **`specKit.command` configurado** no `.spec-wave.json` (ou a env `SPEC_WAVE_IMPLEMENT_CMD`). Sem isso o `implement` monta o contexto e para, sem acionar agente nenhum — o agente lê `.spec-wave/implement-<n>.md` e implementa direto. O `spec-wave dev-agent` **exige** essa configuração. O `doctor` reporta.
+2. **As dependências externas existem.** O `order` só enxerga as Stories filhas — ele não sabe que a spec declarou *outra Feature* como bloqueante. Leia a seção Dependências da `spec.md` e cheque se aquelas Features têm ao menos spec. Já aconteceu de duas bloqueantes não terem nem spec: as Stories de UI escreviam em arquivos de um wizard inexistente, enquanto as de backend podiam começar. Diga quais Stories dão para pegar hoje e quais não.
+3. **O `GH_PROJECT_TOKEN` funciona**, senão `code-review.yml` e `qa.yml` também vão falhar em mover cards durante a implementação, provavelmente em silêncio. O `doctor` verifica a **presença** do secret, nunca a validade — um token presente e sem permissão passa despercebido.