@spec-wave/cli 0.26.0 → 0.28.0

package/src/lib/flow-run.mjs

@@ -9,26 +9,17 @@
 // O modo é detectado pelo ambiente (`GITHUB_ACTIONS`), não por flag: um
 // comando com dois nomes para a mesma coisa envelhece mal.
 //
-// **O comportamento é deliberadamente IDÊNTICO nos dois modos** — gera, commita,
-// dá pull --rebase, faz push, comenta na issue e avança a Etapa. O board é a
-// fonte de verdade do RFC-001 independentemente de onde a geração rodou; um modo
-// local que não sincronizasse o board deixaria o próximo passo do fluxo cego.
+// **O comportamento é IDÊNTICO nos dois modos** — gera, publica em Pull Request,
+// comenta na issue e avança a Etapa. O board é a fonte de verdade do RFC-001
+// independentemente de onde a geração rodou.
 //
-// Duas diferenças existem, e as duas são de SEGURANÇA, não de resultado:
-//
-//  1. IDENTIDADE DO GIT. O Action roda `git config user.email "spec-wave[bot]"`
-//     sem `--global`, o que grava em `.git/config`. Num runner descartável isso
-//     é inócuo; no seu clone, mudaria o autor de TODOS os seus commits futuros
-//     naquele repositório. Localmente a sua identidade é preservada.
-//  2. FALHA DE PUSH. No Action, não conseguir publicar é falha do job. Local, o
-//     arquivo já está gerado e commitado — perder isso porque o remoto andou
-//     seria pior que avisar e deixar você resolver o push. Antes de chegar
-//     nessa bifurcação, os dois modos repetem pull+push enquanto a rejeição for
-//     disputa com outro run — ver §publicação concorrente.
+// Este módulo já carregou as DUAS exceções que sobravam dessa promessa
+// (identidade do git e falha de push), junto com o commit direto na branch
+// default, o laço de pull+rebase+push e a classificação de corrida. Nada disso
+// existe mais: a publicação passou a ser via API, em branch própria por
+// documento, e mora em lib/artifact-publish.mjs. As duas exceções eram
+// consequência de mexer em git local — some a causa, somem elas.
 
-import { execSync } from 'node:child_process';
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
-import path from 'node:path';
 import { resolveRepoContext } from './project-root.mjs';
 import { CONFIG_FILE } from '../config.mjs';
 
@@ -72,203 +63,3 @@ export function resolveFlowContext({ cwd = process.cwd(), command = 'este comand
   }
   return { owner, repo, root, config, mode };
 }
-
-// --- publicação concorrente -------------------------------------------------
-//
-// `pull --rebase` seguido de `push` NÃO é atômico. Entre os dois cabe o push de
-// outro run: dois `generate-spec` de issues DIFERENTES disparados juntos rodam
-// em paralelo (a `concurrency` dos workflows é por issue, e é por issue que ela
-// tem que ser — serializar o repositório inteiro mataria a vazão), terminam
-// juntos e disputam a ponta da branch. O perdedor levava non-fast-forward,
-// falhava o job e PERDIA o documento recém-gerado — com a chamada de IA já
-// paga. Repetir pull+push resolve: o rebase reaplica o commit sobre a ponta
-// nova e o segundo push passa.
-
-export const PUSH_ATTEMPTS = 5;
-const PUSH_BASE_MS = 500;
-
-// Rejeição por CORRIDA: o remoto andou, e reaplicar por cima resolve.
-const RACE_PATTERNS = /non-fast-forward|fetch first|Updates were rejected|cannot lock ref|failed to lock/i;
-
-// Recusa DELIBERADA do remoto. Compartilha a linha genérica "failed to push
-// some refs" com a corrida, então precisa ser testada ANTES: repetir aqui só
-// atrasa a mensagem que o usuário precisa ler. Mesma filosofia de
-// `isTransientProviderError` (lib/claude.mjs).
-const REFUSED_PATTERNS = /GH006|protected branch|pre-receive hook declined|permission to .* denied|403 Forbidden|Authentication failed|could not read Username|Repository not found/i;
-
-/**
- * A saída do git indica disputa pela ponta da branch? (função PURA)
- *
- * @param {string} output stdout+stderr do comando que falhou
- * @returns {boolean}
- */
-export function isRacePushError(output) {
-  const text = String(output || '');
-  if (!text) return false;
-  if (REFUSED_PATTERNS.test(text)) return false;
-  return RACE_PATTERNS.test(text);
-}
-
-/**
- * Espera antes da próxima tentativa (função PURA).
- *
- * Exponencial COM jitter: sem o jitter, dois runs que colidiram uma vez voltam
- * a colidir no mesmo instante — o backoff determinístico os mantém em fase.
- *
- * @param {number} attempt tentativa que acabou de falhar (1-based)
- * @param {object} [opts]
- * @param {number} [opts.baseMs]
- * @param {() => number} [opts.random] injetável para o teste
- * @returns {number} milissegundos
- */
-export function pushBackoffMs(attempt, { baseMs = PUSH_BASE_MS, random = Math.random } = {}) {
-  const teto = baseMs * 2 ** (attempt - 1); // 500ms, 1s, 2s, 4s…
-  return Math.round(teto * (1 + random()));  // [teto, 2*teto)
-}
-
-// Sleep BLOQUEANTE de propósito: `commitGenerated` é síncrona de ponta a ponta
-// (execSync), e um único `await` no meio obrigaria os três comandos chamadores
-// e a suíte inteira a virarem async para nada — nada mais roda nesta thread
-// enquanto o git trabalha.
-function sleepSync(ms) {
-  if (ms > 0) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-}
-
-/**
- * Roda um comando git capturando a saída, e a devolve anexada ao erro.
- *
- * Com `stdio: 'inherit'` o texto do git vai para o log mas NÃO chega ao
- * processo: `err.message` é só "Command failed: git push", e não dá para
- * distinguir corrida de branch protegida. Capturando, o log continua igual
- * (reemitimos) e a classificação passa a ser possível.
- */
-function gitCaptured(cmd) {
-  try {
-    const out = execSync(cmd, { stdio: ['ignore', 'pipe', 'pipe'] });
-    if (out?.length) process.stdout.write(out);
-    return;
-  } catch (err) {
-    const detail = [err.stdout, err.stderr].map(b => b?.toString() || '').join('').trim();
-    if (detail) process.stderr.write(`${detail}\n`);
-    const resumo = detail.split('\n').find(l => l.trim()) || err.message;
-    const erro = new Error(`${cmd} falhou: ${resumo}`);
-    erro.gitOutput = detail;
-    throw erro;
-  }
-}
-
-// Rebase interrompido (conflito, ou pull abortado no meio) deixa o repositório
-// EM rebase. No runner descartável tanto faz; no clone do usuário, sair assim
-// é deixar um estado que ele não pediu e talvez nem perceba.
-function abortRebaseIfAny() {
-  try {
-    const dir = execSync('git rev-parse --git-path rebase-merge', { stdio: 'pipe' }).toString().trim();
-    const dirApply = execSync('git rev-parse --git-path rebase-apply', { stdio: 'pipe' }).toString().trim();
-    if (!existsSync(dir) && !existsSync(dirApply)) return;
-    execSync('git rebase --abort', { stdio: 'pipe' });
-  } catch {
-    // Melhor esforço: se nem abortar dá, o erro original é o que importa.
-  }
-}
-
-/**
- * pull --rebase + push, repetindo enquanto a falha for disputa pela branch.
- *
- * @returns {{attempts: number}}
- * @throws o erro do git quando não é corrida, ou quando as tentativas acabam
- */
-function publishWithRetry({ attempts, baseMs }) {
-  for (let attempt = 1; ; attempt++) {
-    try {
-      gitCaptured('git pull --rebase');
-      gitCaptured('git push');
-      return { attempts: attempt };
-    } catch (err) {
-      abortRebaseIfAny();
-      if (attempt >= attempts || !isRacePushError(err.gitOutput || err.message)) throw err;
-      const espera = pushBackoffMs(attempt, { baseMs });
-      console.warn(
-        `Publicação disputada por outro run (tentativa ${attempt}/${attempts}) — ` +
-        `repetindo em ${(espera / 1000).toFixed(1)}s.`
-      );
-      sleepSync(espera);
-    }
-  }
-}
-
-/**
- * Grava um arquivo gerado e o publica: commit + pull --rebase + push.
- *
- * Era o mesmo bloco copiado em `generate-spec`, `generate-plan` e `decompose`,
- * com a identidade do bot embutida. Centralizado aqui para que a diferença
- * entre os modos exista num lugar só.
- *
- * O commit é escopado ao caminho (`git commit -- <arquivo>`): sem isso, qualquer
- * coisa que você já tivesse no index entraria junto no commit do spec-wave —
- * irrelevante num runner limpo, nada irrelevante no seu clone.
- *
- * @param {object} params
- * @param {string} params.filePath caminho absoluto do arquivo
- * @param {string} params.content
- * @param {string} params.message mensagem de commit
- * @param {'actions'|'local'} params.mode
- * @param {{attempts?: number, baseMs?: number}} [params.retry] ajuste do laço de
- *        publicação — existe para o teste não dormir o backoff real
- * @returns {{committed: boolean, pushed: boolean, warning: string|null}}
- */
-export function commitGenerated({ filePath, content, message, mode, retry = {} }) {
-  mkdirSync(path.dirname(filePath), { recursive: true });
-  writeFileSync(filePath, content, 'utf-8');
-
-  const git = (cmd, opts = {}) => execSync(cmd, { stdio: 'inherit', ...opts });
-  const gitQuiet = (cmd) => execSync(cmd, { stdio: 'pipe' }).toString().trim();
-
-  if (mode === 'actions') {
-    // Runner descartável: identidade do bot é o que se quer no histórico.
-    git('git config user.email "spec-wave[bot]@github.com"');
-    git('git config user.name "spec-wave[bot]"');
-  }
-
-  git(`git add "${filePath}"`);
-
-  // Nada mudou (regerar conteúdo idêntico) → `git commit` sairia 1 e derrubaria
-  // o comando depois de o trabalho estar feito.
-  let hasChanges = true;
-  try {
-    execSync(`git diff --cached --quiet -- "${filePath}"`, { stdio: 'pipe' });
-    hasChanges = false;
-  } catch {
-    hasChanges = true;
-  }
-  if (!hasChanges) {
-    return { committed: false, pushed: false, warning: 'conteúdo idêntico ao já versionado — nada a commitar' };
-  }
-
-  git(`git commit -m "${message}" -- "${filePath}"`);
-
-  try {
-    publishWithRetry({
-      attempts: retry.attempts ?? PUSH_ATTEMPTS,
-      baseMs: retry.baseMs ?? PUSH_BASE_MS,
-    });
-    return { committed: true, pushed: true, warning: null };
-  } catch (err) {
-    if (mode === 'actions') throw err;
-    // Local: o arquivo está gerado e commitado. Derrubar o comando aqui
-    // esconderia esse fato atrás de um erro de rede/divergência.
-    const branch = (() => {
-      try {
-        return gitQuiet('git rev-parse --abbrev-ref HEAD');
-      } catch {
-        return 'seu branch';
-      }
-    })();
-    return {
-      committed: true,
-      pushed: false,
-      warning:
-        `commit feito em ${branch}, mas o push falhou (${err.message.split('\n')[0]}). ` +
-        'O arquivo está salvo e versionado — publique quando resolver.',
-    };
-  }
-}

package/src/lib/next-step.mjs

@@ -19,9 +19,11 @@ import {
   LABEL_CRITIQUE_FAILED, LABEL_NEEDS_HUMAN, LABEL_PLAN_APPROVED, LABEL_TRIAGED,
   LABEL_DUPLICATE, LABEL_WONT_FIX, LABEL_READY, labelNames,
 } from '../config.mjs';
+import { awaitingMergeBlock } from './artifact-pr.mjs';
+import { isAwaitingMerge } from './doc-source.mjs';
 
 /**
- * @typedef {'local'|'remote'|'missing'|'unknown'} DocState
+ * @typedef {'local'|'remote'|'pending-pr'|'missing'|'unknown'} DocState
  * @typedef {'generate-spec'|'generate-plan'|'critique'|'validate'|'decompose'
  *          |'decompose-apply'|'generate-bug'|'triage'|'implement'|'none'} StepAction
  */
@@ -211,6 +213,8 @@ export function resolveForcedStep(step, { type }) {
  * @param {'open'|'closed'} [params.state]
  * @param {Array<string|{name:string}>} [params.labels]
  * @param {Record<string, DocState>} [params.docs] estado de spec/plan/decomposition/bug
+ * @param {Record<string, object>} [params.docPrs] PR aberto de cada documento em
+ *        `pending-pr` — só para a mensagem
  * @param {Record<string, string>} [params.docPaths] caminhos relativos (só para as mensagens)
  * @param {StepAction|null} [params.forcedStep] resultado de resolveForcedStep
  * @param {boolean} [params.confirmed] `--yes`/`--apply` já dados
@@ -220,7 +224,7 @@ export function resolveForcedStep(step, { type }) {
  *            blocked: null|{code: string, message: string, unblock: string}}}
  */
 export function nextStep({
-  type, issueNumber, state = 'open', labels = [], docs = {}, docPaths = {},
+  type, issueNumber, state = 'open', labels = [], docs = {}, docPaths = {}, docPrs = {},
   forcedStep = null, confirmed = false, boardReady = true, force = false,
 } = {}) {
   const params = { issueNumber };
@@ -285,6 +289,25 @@ export function nextStep({
     }
   }
 
+  // G5.5 — documento gerado e esperando merge. Precisa vir ANTES do
+  // `pipelineStep`: para ele, um documento que não está na base "não existe", e
+  // a resposta seria REGERAR — pagando a chamada de IA outra vez, a cada
+  // execução, e descartando o que o revisor já editou dentro do PR.
+  //
+  // Antes do `forcedStep` também, de propósito: `--step spec --yes` é
+  // exatamente o comando que alguém impaciente rodaria aqui, e ele passaria por
+  // cima da revisão em curso.
+  for (const doc of docsOfType) {
+    const estado = docState(docs, doc);
+    if (isAwaitingMerge(estado)) {
+      const info = docPrs[doc] || {};
+      return decided('none', `\`${pathOf(doc)}\` foi gerado e ainda não está na base.`, params,
+        awaitingMergeBlock({
+          pathRel: pathOf(doc), state: estado, pr: info.pr || null, branch: info.branch || null,
+        }));
+    }
+  }
+
   const action = forcedStep || pipelineStep({ type, docs, has });
   if (action === 'none') {
     return decided('none', nothingPendingReason({ type, has }), params);
@@ -299,8 +322,8 @@ export function nextStep({
         `Rode \`${stepCommand(action, params)}\` quando decidir.`));
   }
 
-  // G6 — documento que o passo lê ou escreve existe só no remoto. Gerar por cima
-  // levaria o `pull --rebase` do commit a brigar com o documento bom.
+  // G6 — documento que o passo lê ou escreve existe só na branch base. Gerar por
+  // cima publicaria um Pull Request que desfaz o documento bom.
   for (const doc of stepDocs(action, type)) {
     if (docState(docs, doc) === 'remote') {
       return decided(action, `\`${pathOf(doc)}\` existe no repositório mas não no seu clone.`, params,

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).
  *
@@ -251,6 +340,16 @@ export function explainGitWriteError(err) {
     case 401:
       return `${msg} — token inválido ou expirado.`;
     case 403:
+      // O GitHub Actions recusa a criação de PR com uma mensagem própria, e ela
+      // é a falha MAIS provável deste fluxo: a opção "Allow GitHub Actions to
+      // create and approve pull requests" vem desligada em muitas organizações.
+      // Sem este ramo, o usuário lê "permissão de escrita" e vai mexer em
+      // escopo de token, que não é o problema.
+      if (/not permitted to create or approve pull requests/i.test(msg)) {
+        return `${msg} — o GITHUB_TOKEN está proibido de abrir Pull Requests neste ` +
+          'repositório. Ligue Settings → Actions → General → "Allow GitHub Actions to ' +
+          'create and approve pull requests", ou forneça um PAT no secret `GH_PR_TOKEN`.';
+      }
       return `${msg} — o token não tem permissão de escrita. Precisa de "Contents: write" e ` +
         '"Pull requests: write" (fine-grained) ou do escopo `repo` (classic).';
     case 404:

package/src/lib/repo-links.mjs

@@ -26,7 +26,7 @@ export function blobUrl({ owner, repo, ref, pathRel }) {
  * Qual ref o link deve citar (função PURA).
  *
  * No Actions, `GITHUB_REF_NAME` é a branch do evento. Localmente, a branch
- * corrente é a que `commitGenerated` acabou de publicar. `main` é o último
+ * corrente é a que o usuário está usando. `main` é o último
  * recurso — o mesmo valor que estava hardcoded, então nunca piora.
  *
  * @param {object} params
@@ -71,9 +71,15 @@ export function currentGitBranch(cwd = process.cwd()) {
  * @param {'actions'|'local'} params.mode
  * @param {string|null} [params.root] raiz do repo (para ler a branch corrente)
  * @param {object|null} [params.config]
+ * @param {string|null} [params.ref] ref EXPLÍCITA, com precedência sobre tudo.
+ *   Com a publicação por Pull Request, quem gerou o documento sabe exatamente em
+ *   que branch ele está — e a inferência abaixo erraria: num evento
+ *   `issues: labeled` o `GITHUB_REF_NAME` é a branch DEFAULT, onde o documento
+ *   ainda não existe, então todo link nasceria 404 até o merge.
  * @returns {string}
  */
-export function docBlobUrl({ owner, repo, pathRel, mode, root = null, config = null }) {
+export function docBlobUrl({ owner, repo, pathRel, mode, root = null, config = null, ref: refExplicita = null }) {
+  if (refExplicita) return blobUrl({ owner, repo, ref: refExplicita, pathRel });
   const ref = resolveDocRef({
     mode,
     env: process.env,

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

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

@@ -1,6 +1,6 @@
 ---
 name: spec-wave-bug
-description: "Use para gerar o bug.md de um defeito do spec-wave — reprodução, causa raiz, escopo do fix e teste de regressão. Aplica a label spec-wave:bug e deixa o GitHub Action gerar e commitar o arquivo em docs/bugs/<slug>/. Gatilhos: 'gerar o bug.md da issue 42', 'documentar a causa raiz do bug', 'rodar o spec-wave:bug'. Só vale para issues do tipo Bug — Feature usa spec/plan."
+description: "Use para gerar o bug.md de um defeito do spec-wave — reprodução, causa raiz, escopo do fix e teste de regressão. Aplica a label spec-wave:bug e deixa o GitHub Action gerar o arquivo em docs/bugs/<slug>/ e abrir um Pull Request. Gatilhos: 'gerar o bug.md da issue 42', 'documentar a causa raiz do bug', 'rodar o spec-wave:bug'. Só vale para issues do tipo Bug — Feature usa spec/plan."
 allowed-tools:
   - Bash(gh issue *)
   - Bash(npx @spec-wave/cli@latest *)
@@ -9,7 +9,7 @@ allowed-tools:
 
 # spec-wave bug — o documento do defeito
 
-> **Regra fundamental: nunca escreva o `bug.md` você mesmo.** Aplique a label e deixe o Action gerar — é isso que garante que o arquivo seja commitado e referenciado na issue. Exceção: revisar/melhorar um `bug.md` já gerado (aí sim use Edit no arquivo local).
+> **Regra fundamental: nunca escreva o `bug.md` você mesmo.** Aplique a label e deixe o Action gerar — é isso que garante que o arquivo chegue à main por Pull Request e seja referenciado na issue. Exceção: revisar/melhorar um `bug.md` já gerado (aí sim use Edit no arquivo local).
 
 **Contexto:** leia `.spec-wave.json` (Read). Ausente → skill **setup**.
 

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

@@ -24,7 +24,7 @@ Para qualquer outro tipo (Spike, Bug, Story, Task…) o Action **recusa** e come
 
 ```
 spec-wave:decompose
-  ├─ decomposition.md ausente  → gera via IA → commita → critica
+  ├─ decomposition.md ausente  → gera via IA → abre Pull Request → critica
   └─ decomposition.md presente → critica o arquivo COMO ESTÁ (preserva suas edições)
        ├─ grave  → +critique-failed, comentário citando Story N / Task N.M, exit 1
        └─ limpo  → +decompose-ready, comentário "revise e aplique"
@@ -45,14 +45,14 @@ spec-wave:decompose-apply
    # ou Action — assíncrono
    gh issue edit <número> --add-label "spec-wave:decompose"
    ```
-   Informe: "Rascunho iniciado — vai commitar o `decomposition.md` e passar pela crítica. **Nenhuma issue é criada nesta etapa.**"
+   Informe: "Rascunho iniciado — vai abrir um Pull Request com o `decomposition.md` e passar pela crítica. **Nenhuma issue é criada nesta etapa.**"
 
 3. **Leia o resultado** quando o Action terminar:
 
    | Label resultante | O que fazer |
    |------------------|-------------|
    | `spec-wave:decompose-ready` | Passou na crítica. **Leia o `decomposition.md`** e mostre ao usuário o que será criado (Stories, Tasks, dependências). Ofereça editar antes de aplicar. |
-   | `spec-wave:critique-failed` | O Action **falhou (exit 1)** e nada foi criado. Os achados citam `Story N` / `Task N.M`. **Corrija o `decomposition.md`** — não o `plan.md` — commite e reaplique `spec-wave:decompose` (o arquivo é criticado como está, sem ser regerado). |
+   | `spec-wave:critique-failed` | O Action **falhou (exit 1)** e nada foi criado. Os achados citam `Story N` / `Task N.M`. **Corrija o `decomposition.md`** — não o `plan.md` — **no Pull Request** e reaplique `spec-wave:decompose` (o arquivo é criticado como está, sem ser regerado, venha ele do PR ou da base). |
    | `spec-wave:needs-human` | A crítica esgotou as tentativas. **Pare** e envolva o usuário: as duas labels precisam sair à mão. |
 
 4. **Etapa 2 — aplicar o rascunho aprovado**, só depois da revisão:
@@ -95,7 +95,7 @@ Corpo técnico.
 - a **posição** manda, não o número escrito — inserir uma Story no meio sem renumerar funciona
 - `**Depende de:**` aceita **irmãs** (`Story 1, Story 3`, 1-based, só para trás — apontar para si mesma ou para frente é **erro**, não filtro silencioso) e **issues de outras Features** (`#412`, que precisam JÁ existir); as duas formas convivem na mesma linha (`Story 1, #412`), e `—` significa nenhuma
 - o corpo aceita markdown livre (`## Backend`, cercas de código) — só `## Story N` e `### Task N.M` são estrutura
-- **para gerar outro rascunho do zero:** apague o arquivo e reaplique `spec-wave:decompose`
+- **para gerar outro rascunho do zero:** feche o Pull Request e apague a branch `spec-wave/<n>-decompose` (ou apague o arquivo, se já foi mergeado) e reaplique `spec-wave:decompose`
 
 > ⚠️ O slug vem do **título**. Renomear a Feature entre o rascunho e o apply muda o diretório e órfã o `decomposition.md` — o apply reclama que não achou o rascunho.
 

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

@@ -14,7 +14,7 @@ allowed-tools:
 
 > **Regra fundamental: nunca escreva o `plan.md` à mão.** Quem gera é o spec-wave — pelo Action ou pela CLI local. Exceção: revisar/melhorar um plano já gerado.
 
-**Dois modos, mesmo resultado.** `npx @spec-wave/cli@latest generate-plan --issue-number <n>` roda **agora**, nesta sessão; a label `spec-wave:plan` roda no Action. O modo é detectado pelo ambiente. Ambos geram, commitam, fazem push, criticam e comentam na issue. Local exige a chave de IA no seu ambiente. Veja a skill **spec** para a tabela completa.
+**Dois modos, mesmo resultado.** `npx @spec-wave/cli@latest generate-plan --issue-number <n>` roda **agora**, nesta sessão; a label `spec-wave:plan` roda no Action. O modo é detectado pelo ambiente. Ambos geram, abrem um **Pull Request**, criticam e comentam na issue. Local exige a chave de IA no seu ambiente. Veja a skill **spec** para a tabela completa.
 
 **Contexto:** leia `.spec-wave.json` (Read). Ausente → skill **setup**.