@spec-wave/cli 0.26.0 → 0.27.0

package/src/lib/doc-source.mjs

@@ -0,0 +1,162 @@
+// De ONDE vem o conteúdo de um documento do fluxo.
+//
+// Enquanto os artefatos eram commitados na branch default, "o documento existe"
+// e "o arquivo está no checkout" eram a mesma pergunta, e todo mundo respondia
+// com `existsSync`. Com a publicação por Pull Request deixam de ser: um
+// documento recém-gerado vive numa branch que ninguém mergeou ainda.
+//
+// Ignorar essa diferença não dá erro — dá coisa pior, em silêncio:
+//
+//  • o `decompose` REGENERA um rascunho que um humano já editou (a invariante
+//    "um rascunho existente nunca é regenerado" é literalmente um `existsSync`);
+//  • o `validate` REPROVA por arquivo ausente e consome a label de gatilho;
+//  • o `generate-plan` gera o plano com o placeholder no lugar da spec.
+//
+// Por isso a resolução é uma só, em camadas, e todo leitor passa por aqui.
+//
+// I/O com dependências INJETADAS: é o que permite testar as quatro camadas sem
+// mock de HTTP, que a suíte não tem.
+
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { getFileContent, findOpenPR } from '../api/github-rest.mjs';
+import { artifactBranch } from './artifact-pr.mjs';
+
+/**
+ * @typedef {'local'|'remote'|'pending-pr'|'branch-only'|'missing'|'unknown'} DocState
+ */
+
+/**
+ * Estados em que o documento EXISTE mas ainda não chegou à branch base (PURA).
+ *
+ * Os dois significam a mesma coisa para quem depende do documento — o passo
+ * seguinte não pode rodar — e coisas diferentes para quem precisa destravar:
+ * `pending-pr` espera revisão e merge; `branch-only` espera alguém abrir o PR.
+ *
+ * Existe como predicado, e não como comparação solta, porque a lista é
+ * consultada em seis lugares (validate, generate-plan, decompose, apply,
+ * next-step, run) e um deles esquecido é uma porta aberta: foi assim que o
+ * `--apply` quase criou issues a partir de um rascunho que ninguém revisou.
+ *
+ * @param {DocState} state
+ * @returns {boolean}
+ */
+export function isAwaitingMerge(state) {
+  return state === 'pending-pr' || state === 'branch-only';
+}
+
+/**
+ * Onde está o documento, e o seu conteúdo (I/O — NUNCA lança).
+ *
+ * A ordem das camadas é deliberada:
+ *
+ *  1. **disco** (`local`) — o que o usuário tem à mão vence; é o que ele está
+ *     editando, e é também o caso do runner logo após o checkout.
+ *  2. **branch base** (`remote`) — mantém exatamente o significado que o G6 do
+ *     next-step já dava a este estado: publicado, mas não no seu clone.
+ *  3. **branch do artefato** — e só então se há PR: com PR aberto, `pending-pr`;
+ *     sem PR, `branch-only`. A ordem é essa porque perguntar pelo PR primeiro
+ *     tornava invisível o documento cujo commit passou e cujo PR falhou (403 de
+ *     organização, GH_PR_TOKEN errado): ele era reportado como inexistente, e a
+ *     execução seguinte REGERAVA, pagando a IA de novo. Consultar a branch antes
+ *     não custa chamada nenhuma — são duas requisições nos dois desfechos.
+ *  4. nada (`missing`); falha de rede em qualquer consulta → `unknown`.
+ *
+ * `unknown` nunca vira bloqueio: ficar offline não pode travar o fluxo. Quem
+ * decide o que fazer com cada estado é o chamador.
+ *
+ * @param {object} params
+ * @param {string} params.token
+ * @param {string} params.owner
+ * @param {string} params.repo
+ * @param {string|null} params.root raiz do repositório (para o caminho absoluto)
+ * @param {string} params.pathRel caminho do documento no repositório
+ * @param {string} params.doc chave de ARTIFACT_DOCS
+ * @param {number|string} params.issueNumber
+ * @param {string|null} [params.base] branch base (null = deixa a API escolher)
+ * @param {object} [params.deps] injeção para teste
+ * @returns {Promise<{content: string|null, state: DocState, ref: string|null,
+ *                    pr: {number: number, url: string}|null}>}
+ */
+export async function loadArtifact({
+  token, owner, repo, root, pathRel, doc, issueNumber, base = null, deps = {},
+}) {
+  const api = { getFileContent, findOpenPR, ...deps };
+
+  const abs = path.resolve(root || process.cwd(), pathRel);
+  if (existsSync(abs)) {
+    return { content: readFileSync(abs, 'utf-8'), state: 'local', ref: null, pr: null };
+  }
+
+  // Sem token não há como consultar nada — mas "não consegui olhar" não é "não
+  // existe": afirmar `missing` aqui faria o chamador regerar por cima.
+  if (!token || !owner || !repo) {
+    return { content: null, state: 'unknown', ref: null, pr: null };
+  }
+
+  let naBase;
+  try {
+    naBase = await api.getFileContent(token, owner, repo, pathRel, base || undefined);
+  } catch {
+    return { content: null, state: 'unknown', ref: null, pr: null };
+  }
+  if (naBase != null) {
+    return { content: naBase, state: 'remote', ref: base, pr: null };
+  }
+
+  let branch;
+  try {
+    branch = artifactBranch({ issueNumber, doc });
+  } catch {
+    // Documento sem branch de artefato (ou número inválido): não há onde olhar.
+    return { content: null, state: 'missing', ref: null, pr: null };
+  }
+
+  let naBranch;
+  try {
+    naBranch = await api.getFileContent(token, owner, repo, pathRel, branch);
+  } catch {
+    return { content: null, state: 'unknown', ref: null, pr: null };
+  }
+  // Branch inexistente e arquivo ausente dão o mesmo 404, e é o mesmo desfecho.
+  if (naBranch == null) return { content: null, state: 'missing', ref: null, pr: null };
+
+  // O PR só importa depois de saber que o documento está lá — e o que ele decide
+  // é o REMÉDIO, não a existência.
+  let pr;
+  try {
+    pr = await api.findOpenPR(token, owner, repo, branch);
+  } catch {
+    // O documento existe; não saber se há PR não pode rebaixá-lo a inexistente,
+    // que é o estado que autoriza regerar por cima.
+    return { content: naBranch, state: 'branch-only', ref: branch, pr: null };
+  }
+
+  return pr
+    ? { content: naBranch, state: 'pending-pr', ref: branch, pr: { number: pr.number, url: pr.url } }
+    : { content: naBranch, state: 'branch-only', ref: branch, pr: null };
+}
+
+/**
+ * Estado de VÁRIOS documentos de uma issue (I/O — nunca lança).
+ *
+ * Devolve o mapa que `nextStep` consome, sem o conteúdo: quem decide o próximo
+ * passo não precisa carregar três documentos inteiros na memória.
+ *
+ * @param {object} params
+ * @param {Array<{doc: string, pathRel: string}>} params.docs
+ * @returns {Promise<Record<string, {state: DocState, pr: object|null}>>}
+ */
+export async function artifactStates({
+  token, owner, repo, root, docs = [], issueNumber, base = null, deps = {},
+}) {
+  const out = {};
+  for (const { doc, pathRel } of docs) {
+    const { state, pr } = await loadArtifact({
+      token, owner, repo, root, pathRel, doc, issueNumber, base, deps,
+    });
+    out[doc] = { state, pr };
+  }
+  return out;
+}

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

@@ -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.26.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

@@ -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