@spec-wave/cli 0.25.0 → 0.27.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
  */
@@ -44,11 +46,21 @@ export const STEPS = {
     types: ['Feature'], creates: false, ai: true,
   },
   validate: {
+    // `reads` DEPENDE DO TIPO: a validação de Feature abre spec.md e plan.md, a
+    // de Bug abre bug.md. Declarar `[]` aqui desarmava o G6 justamente para o
+    // passo que só lê do disco — um clone atrasado reprovava uma Feature cujo
+    // plan.md existia no remoto, removia `spec-wave:ready` e comentava a falha
+    // na issue. Dano a estado COMPARTILHADO por uma condição puramente local.
     trigger: LABEL_READY, cli: 'validate', writes: null, reads: [],
+    readsByType: { Feature: ['spec', 'plan'], Bug: ['bug'] },
     types: ['Feature', 'Bug'], creates: false, ai: false,
   },
   decompose: {
+    // O rascunho de Feature é montado a partir de spec.md + plan.md; o de RFC
+    // não usa nenhum dos dois. Com `[]` e o plan só no remoto, o decompose
+    // gerava o rascunho com o plano VAZIO — sem erro, só pior.
     trigger: LABEL_DECOMPOSE, cli: 'decompose', writes: 'decomposition', reads: [],
+    readsByType: { Feature: ['spec', 'plan'], RFC: [] },
     types: ['Feature', 'RFC'], creates: false, ai: true,
   },
   'decompose-apply': {
@@ -71,13 +83,60 @@ export const STEPS = {
   },
 };
 
+/**
+ * Documentos que um passo LÊ, para um tipo de item (função PURA).
+ *
+ * Existe porque dois passos leem coisas diferentes conforme o tipo — `validate`
+ * abre spec+plan numa Feature e bug.md num Bug — e o G6 precisa da lista CERTA:
+ * ele é o que impede o passo de rodar contra um clone atrasado. Uma lista
+ * subdeclarada não causa erro visível, causa o passo rodando com o arquivo
+ * errado (ou ausente), que é o modo de falha caro.
+ *
+ * @param {string} action nome da ação em STEPS
+ * @param {string|null} [type] tipo do work item
+ * @returns {string[]} documentos lidos
+ */
+export function stepReads(action, type) {
+  const step = STEPS[action];
+  if (!step) return [];
+  return step.readsByType?.[type] ?? step.reads;
+}
+
+/**
+ * Documentos que um passo TOCA (lê ou escreve), para um tipo (função PURA).
+ *
+ * É a lista que o G6, o aviso de "não deu para consultar o remoto" e a sonda do
+ * `run` precisam — os três erravam junto quando `reads` estava subdeclarado.
+ *
+ * @param {string} action
+ * @param {string|null} [type]
+ * @returns {string[]}
+ */
+export function stepDocs(action, type) {
+  return [STEPS[action]?.writes, ...stepReads(action, type)].filter(Boolean);
+}
+
+/**
+ * Documentos que um tipo usa (função PURA).
+ *
+ * O `run` precisa disto para sondar o remoto quando a decisão veio BLOQUEADA e
+ * o passo é `none` — aí não há `writes`/`reads` de onde tirar a lista, e é
+ * justamente o caso em que o G5 afirma "não está no clone nem no remoto".
+ *
+ * @param {string|null} [type]
+ * @returns {string[]}
+ */
+export function docsForType(type) {
+  return DOCS_BY_TYPE[type] || [];
+}
+
 /** Tipos que o `run` sabe conduzir. Story/Task/Epic/Spike não têm passo de documento. */
 export const RUNNABLE_TYPES = ['Feature', 'Bug', 'RFC'];
 
 const TRIGGERS = Object.values(STEPS).map(s => s.trigger).filter(Boolean);
 
 /** Documentos que cada tipo usa, na ordem em que o fluxo os produz. */
-const DOCS_BY_TYPE = {
+export const DOCS_BY_TYPE = {
   Feature: ['spec', 'plan', 'decomposition'],
   RFC: ['decomposition'],
   Bug: ['bug'],
@@ -154,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
@@ -163,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 };
@@ -228,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);
@@ -242,9 +322,9 @@ 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.
-  for (const doc of [step.writes, ...step.reads].filter(Boolean)) {
+  // 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,
         block('stale-checkout',
@@ -285,8 +365,7 @@ export function nextStep({
         'Confirme com `--yes` se é isso mesmo.'));
   }
 
-  const incertos = [step.writes, ...step.reads]
-    .filter(Boolean)
+  const incertos = stepDocs(action, type)
     .filter(doc => docState(docs, doc) === 'unknown');
   const aviso = incertos.length > 0
     ? ` (não foi possível consultar o remoto por ${incertos.map(pathOf).join(', ')} — ` +

package/src/lib/pr-branch.mjs

@@ -251,6 +251,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.25.0",
+  "version": "0.27.0",
   "description": "Fluxo spec-driven no GitHub (RFC-001): Projects v2, labels de gatilho, spec/plan gerados por Action, decomposição em duas etapas e implementação orientada a Stories/Tasks.",
   "author": {
     "name": "Astratech",

package/src/plugin/skills/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**.
 

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

@@ -26,7 +26,7 @@ npx @spec-wave/cli@latest mode actions    # volta tudo para o CI
    npx @spec-wave/cli@latest run <issue> --dry-run
    ```
 2. Mostre ao usuário o passo, o motivo e o comando que rodaria. **Só então** execute sem a flag.
-3. `--json` devolve a mesma decisão em JSON, quando você precisar ramificar programaticamente.
+3. `--json` devolve a decisão em JSON, quando você precisar ramificar programaticamente. É **um** documento: o desfecho no topo (`action`, `command`, `blocked`) e a sequência inteira em `steps` — útil com `--max-steps`.
 
 ## O que o `run` decide sozinho
 
@@ -50,13 +50,15 @@ O comando **explica e para**, saindo com código 2. Não force sem entender:
 - **`trigger-pending`** — há label de gatilho na issue: um Action está em voo (ou falhou deixando-a). Rodar por cima duplicaria documento e comentário. `--force` fura, quando você tem certeza.
 - **`needs-human` / `critique-failed`** — portões humanos da crítica. O caminho é corrigir o documento e remover a label; para o `critique-failed` o passo de retomada é **re-criticar**, nunca regerar.
 - **`stale-checkout`** — o documento existe no repositório e não no seu clone. `git pull` e repita; seguir sobrescreveria o que já foi publicado.
+- **`pr-pending`** — o documento foi gerado e está num **Pull Request ainda não mergeado**. Revise o PR (edite ali mesmo, se precisar) e faça o merge; o passo seguinte lê o documento da branch base. Rodar por cima regeraria o arquivo, descartando a revisão e pagando a IA de novo.
+- **`branch-without-pr`** — o documento foi commitado numa branch `spec-wave/*` e **nenhum PR foi aberto** para ela. Quase sempre a abertura do PR falhou: opção *"Allow GitHub Actions to create and approve pull requests"* desligada, ou secret `GH_PR_TOKEN` ausente. Rode `spec-wave doctor`, corrija e abra o PR — reaplicar o gatilho **regera** o documento.
 - **`needs-confirmation`** — o passo cria issues (`decompose-apply`) ou gasta IA repetindo a crítica de um rascunho existente. Revise antes e confirme com `--apply` / `--yes`.
 - **`inconsistent-state`** — as labels afirmam um documento que não existe. Quase sempre o título da issue mudou depois de gerar (o slug vira outro diretório).
 
 ## Regras que o `run` respeita — e você também
 
 - **Nunca aplique label de gatilho no modo local.** Ela dispararia o Action e o passo aconteceria duas vezes. O `run` não aplica nenhuma.
-- **Um passo por invocação.** `--max-steps <n>` encadeia, mas cada passo de IA custa dinheiro — encadeie só quando o usuário pedir.
+- **Um passo por invocação.** `--max-steps <n>` encadeia, mas cada passo de IA custa dinheiro — encadeie só quando o usuário pedir. Na prática o encadeamento agora para sozinho: cada documento vai para um Pull Request, e o passo seguinte depende do merge.
 - A **Regra fundamental** continua valendo: nunca escreva `spec.md`/`plan.md`/`decomposition.md` à mão. Quem gera é a CLI, aqui como no Action.
 
 ## `mode` — o interruptor

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

@@ -1,6 +1,6 @@
 ---
 name: spec-wave-spec
-description: "Use para iniciar a geração da especificação funcional (spec.md) de uma Feature do spec-wave — o PRIMEIRO documento do ciclo, antes do plano técnico. Aplica a label spec-wave:spec e deixa o GitHub Action gerar e commitar o arquivo. Gatilhos: 'gerar a spec da feature 12', 'criar especificação funcional', 'rodar o spec-wave:spec'. Só vale para Features — Spike, RFC e Bug não usam spec."
+description: "Use para iniciar a geração da especificação funcional (spec.md) de uma Feature do spec-wave — o PRIMEIRO documento do ciclo, antes do plano técnico. Aplica a label spec-wave:spec e deixa o GitHub Action gerar o arquivo e abrir um Pull Request. Gatilhos: 'gerar a spec da feature 12', 'criar especificação funcional', 'rodar o spec-wave:spec'. Só vale para Features — Spike, RFC e Bug não usam spec."
 allowed-tools:
   - Bash(gh issue *)
   - Bash(npx @spec-wave/cli@latest *)
@@ -9,7 +9,7 @@ allowed-tools:
 
 # spec-wave spec — especificação funcional (1º documento)
 
-> **Regra fundamental: nunca escreva o `spec.md` à mão.** Quem gera é o spec-wave — pelo Action ou pela CLI local. É isso que garante que o arquivo seja commitado e referenciado na issue. Exceção: revisar/melhorar um `spec.md` já gerado (aí sim use Edit).
+> **Regra fundamental: nunca escreva o `spec.md` à mão.** Quem gera é o spec-wave — pelo Action ou pela CLI local. É isso que garante que o arquivo chegue à main por Pull Request e seja referenciado na issue. Exceção: revisar/melhorar um `spec.md` já gerado (aí sim use Edit).
 
 ## Dois modos, mesmo resultado
 
@@ -18,7 +18,7 @@ allowed-tools:
 | **Action** | aplicar a label `spec-wave:spec` | fluxo assíncrono; roda no CI, você acompanha pela issue |
 | **Local** | `npx @spec-wave/cli@latest generate-spec --issue-number <n>` | você quer o documento **agora**, nesta sessão, e iterar em cima dele |
 
-O modo é detectado pelo ambiente — fora do Actions, a CLI roda em modo local automaticamente. Os dois geram o arquivo, commitam, dão push, comentam na issue e removem a label de gatilho. **Pergunte ao usuário qual ele quer** se não estiver claro; na dúvida numa sessão interativa, prefira o local (o resultado aparece em segundos, em vez de exigir acompanhar o Action).
+O modo é detectado pelo ambiente — fora do Actions, a CLI roda em modo local automaticamente. Os dois geram o arquivo, abrem um **Pull Request** com ele, comentam na issue e removem a label de gatilho. **Pergunte ao usuário qual ele quer** se não estiver claro; na dúvida numa sessão interativa, prefira o local (o resultado aparece em segundos, em vez de exigir acompanhar o Action).
 
 > Local exige a credencial de IA no seu ambiente (`OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY` ou o login do Claude Code, se o provider for `claude-oauth`) e um `.spec-wave.json` no repositório. Para conduzir o fluxo inteiro sem gastar minutos de Actions, veja a skill **run**.
 
@@ -36,7 +36,7 @@ O modo é detectado pelo ambiente — fora do Actions, a CLI roda em modo local
    ```bash
    npx @spec-wave/cli@latest generate-spec --issue-number <número>
    ```
-   O comando imprime `Modo de execução: local`, gera, commita e faz push.
+   O comando imprime `Modo de execução: local`, gera e abre o Pull Request. Nada é gravado no seu clone — o documento vive no PR até o merge.
 
    **Action** — assíncrono:
    ```bash

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

@@ -31,7 +31,7 @@ Toda a CLI é invocada como `npx @spec-wave/cli@latest <comando>`.
    - **Action:** aplique a label de gatilho (`spec-wave:spec`, `spec-wave:plan`, `spec-wave:decompose`);
    - **Local:** `npx @spec-wave/cli@latest generate-spec|generate-plan|decompose --issue-number <n>` na sua sessão.
 
-   O modo é detectado pelo ambiente (`GITHUB_ACTIONS`), sem flag. Os dois geram, commitam, fazem push, comentam na issue e sincronizam o board — o board é a fonte de verdade independentemente de onde rodou. Local exige a chave de IA no seu ambiente e um `.spec-wave.json`. Exceção à regra: revisar/melhorar um documento já gerado.
+   O modo é detectado pelo ambiente (`GITHUB_ACTIONS`), sem flag. Os dois geram, abrem um **Pull Request** com o documento, comentam na issue e sincronizam o board — o board é a fonte de verdade independentemente de onde rodou. Local exige a chave de IA no seu ambiente e um `.spec-wave.json`. Exceção à regra: revisar/melhorar um documento já gerado.
 2. **Nunca crie Story ou Task avulsa.** Elas nascem do `decompose`, já em **✅ Ready** e vinculadas ao pai. Criadas à mão caem em 📥 Backlog e **não aparecem em tela nenhuma** da UI (o inbox do PM lista Features, a tela do Dev lê 🚧 Desenvolvimento, a fila do TL lê ✅ Ready).
 3. **Nunca use `gh issue create`** para work items — não adiciona ao Project, a issue fica sem Etapa e some das telas. Use `npx @spec-wave/cli@latest issue`.
 4. **A Etapa só avança, nunca retrocede.** O campo **Status** (Todo / In Progress / Done) mede o progresso *dentro* da Etapa e reinicia a cada avanço. Prefira `move`, `task start|done` e `story review` a mutações GraphQL manuais — os comandos embutem essas regras.
@@ -88,7 +88,7 @@ Depois do `generate-plan` e **antes** de qualquer issue nascer no `decompose`, u
 | Reprovou depois de | O que corrigir | Como retomar |
 |--------------------|----------------|--------------|
 | `generate-plan` | `plan.md` (ou a `spec.md` que o embasa) | corrija/regere → remova `critique-failed` → reaplique `spec-wave:ready` |
-| `decompose` | **`decomposition.md`** — os achados citam `Story N` / `Task N.M`, títulos **desse arquivo** | edite e commite → remova `critique-failed` → reaplique `spec-wave:decompose` (critica o arquivo como está, sem regerar) |
+| `decompose` | **`decomposition.md`** — os achados citam `Story N` / `Task N.M`, títulos **desse arquivo** | edite no Pull Request → remova `critique-failed` → reaplique `spec-wave:decompose` (critica o arquivo como está, sem regerar) |
 
 > ⚠️ No `decompose` os achados são sobre as **Stories propostas**, não sobre o `plan.md`. Corrigir o plan não muda o rascunho já gravado.