@spec-wave/cli 0.26.0 → 0.27.0

package/src/commands/validate.mjs

@@ -1,5 +1,3 @@
-import { existsSync, readFileSync } from 'node:fs';
-import path from 'node:path';
 import { resolveToken } from '../api/auth.mjs';
 import { getIssue, removeLabel, addLabel, commentOnIssue } from '../api/github-rest.mjs';
 import { slugify } from '../lib/slugify.mjs';
@@ -14,6 +12,48 @@ import { detectIssueType } from '../lib/issue-type.mjs';
 import { loadConfig } from '../lib/project-root.mjs';
 import { executionMode } from '../lib/flow-run.mjs';
 import { docBlobUrl } from '../lib/repo-links.mjs';
+import { loadArtifact } from '../lib/doc-source.mjs';
+import { awaitingMergeBlock } from '../lib/artifact-pr.mjs';
+import { isAwaitingMerge } from '../lib/doc-source.mjs';
+import { getRepoDefaultBranch } from '../api/github-rest.mjs';
+
+/**
+ * Aborto por documento ainda em Pull Request.
+ *
+ * Este é o portão mais importante do `validate`, e existe por um motivo
+ * assimétrico: a reprova NÃO é inócua. Ela remove `spec-wave:ready` (o gatilho,
+ * que `issues: [labeled]` não redispara sozinho) e comenta a falha na issue —
+ * ou seja, danifica estado COMPARTILHADO. Fazer isso porque o documento está num
+ * PR não mergeado seria reprovar por uma condição que não é do documento.
+ *
+ * É exatamente o incidente que o comentário do `readsByType` em
+ * lib/next-step.mjs já registra ter acontecido antes, com clone desatualizado.
+ *
+ * Aborta ANTES do removeLabel: a label fica, e reaplicá-la depois do merge
+ * simplesmente funciona.
+ */
+async function abortIfPendingPr({ token, owner, repo, n, docs }) {
+  const pendentes = docs.filter(d => isAwaitingMerge(d.state));
+  if (pendentes.length === 0) return null;
+
+  // Cada documento carrega o SEU desbloqueio: um está esperando merge, outro
+  // esperando alguém abrir o PR. Um texto único ("faça o merge do PR") mandaria
+  // metade dos casos procurar uma tela que não existe.
+  const blocos = pendentes.map(d => awaitingMergeBlock({
+    pathRel: d.pathRel, state: d.state, pr: d.pr, branch: d.ref,
+  }));
+  const linhas = blocos.map(b => `- ${b.message}\n  ${b.unblock}`);
+
+  await commentOnIssue(token, owner, repo, n,
+    '⏸️ **Validação adiada — documento ainda não está na branch base.**\n\n' +
+    `${linhas.join('\n')}\n\n` +
+    'Resolvido isso, reaplique `spec-wave:ready` — a label foi **mantida** na issue, ' +
+    'e nada foi reprovado.'
+  ).catch(() => {});
+
+  console.error(`Validação adiada: ${pendentes.map(d => d.pathRel).join(', ')} fora da base.`);
+  return { ok: false, errors: linhas, awaitingMerge: true };
+}
 
 /**
  * Validação do bug.md (RFC-004 §5).
@@ -23,11 +63,19 @@ import { docBlobUrl } from '../lib/repo-links.mjs';
  * um único arquivo, e a falha NÃO devolve o item para a etapa de spec (Bug não
  * tem etapa de spec). Reaplicar `spec-wave:bug` é o caminho de retomada.
  */
-async function validateBug({ token, owner, repo, issue, issueNumber, root }) {
+async function validateBug({ token, owner, repo, issue, issueNumber, root, base }) {
   const n = parseInt(issueNumber, 10);
-  const { fileRel, fileAbs } = bugDocPaths(issue.title, root);
+  const { fileRel } = bugDocPaths(issue.title, root);
   const errors = [];
 
+  const bug = await loadArtifact({
+    token, owner, repo, root, pathRel: fileRel, doc: 'bug', issueNumber: n, base,
+  });
+  const adiado = await abortIfPendingPr({
+    token, owner, repo, n, docs: [{ ...bug, pathRel: fileRel }],
+  });
+  if (adiado) return adiado;
+
   const names = labelNames(issue);
   const critiqueFailed = names.includes(LABEL_CRITIQUE_FAILED);
   const needsHuman = names.includes(LABEL_NEEDS_HUMAN);
@@ -44,12 +92,12 @@ async function validateBug({ token, owner, repo, issue, issueNumber, root }) {
     );
   }
 
-  if (!existsSync(fileAbs)) {
+  if (bug.content == null) {
     errors.push(
       `❌ \`bug.md\` não encontrado em \`${fileRel}\` — aplique \`${LABEL_BUG}\` para gerá-lo.`
     );
   } else {
-    const content = readFileSync(fileAbs, 'utf-8');
+    const content = bug.content;
     for (const faltante of describeMissingSections(content, REQUIRED_BUG_SECTIONS)) {
       errors.push(renderMissingSection('bug.md', faltante));
     }
@@ -124,19 +172,23 @@ export async function validate({ issueNumber }) {
     );
   }
 
-  const issue = await getIssue(token, owner, repo, parseInt(issueNumber, 10));
+  const n = parseInt(issueNumber, 10);
+  const issue = await getIssue(token, owner, repo, n);
+
+  // Branch base para a leitura em camadas. Best-effort: sem ela o resolvedor cai
+  // no default da API, que é a mesma branch.
+  const base = await getRepoDefaultBranch(token, owner, repo).catch(() => null);
 
   // Bug tem artefato próprio (bug.md) e caminho próprio de validação — não passa
   // pelo par spec.md + plan.md, que é exclusivo de Feature.
   if (detectIssueType(issue) === 'Bug') {
-    return await validateBug({ token, owner, repo, issue, issueNumber, root });
+    return await validateBug({ token, owner, repo, issue, issueNumber, root, base });
   }
 
   const slug = slugify(issue.title);
   // Ancorado na RAIZ do repo, não no cwd: rodar de um subdiretório encontra o
   // config subindo na árvore e precisa encontrar os documentos no mesmo lugar.
   const featureRel = `docs/features/${slug}`;
-  const featureDir = path.resolve(root || process.cwd(), featureRel);
 
   const errors = [];
 
@@ -158,12 +210,28 @@ export async function validate({ issueNumber }) {
     );
   }
 
+  // Os dois documentos vêm do resolvedor em camadas (disco → base → PR aberto):
+  // ler só o disco reprovaria uma Feature cujo plan.md está publicado, o que
+  // custa a label de gatilho e um comentário de falha na issue.
+  const planRel = `${featureRel}/plan.md`;
+  const specRel = `${featureRel}/spec.md`;
+  const ler = (doc, pathRel) => loadArtifact({
+    token, owner, repo, root, pathRel, doc, issueNumber: n, base,
+  });
+  const plan = await ler('plan', planRel);
+  const spec = await ler('spec', specRel);
+
+  const adiado = await abortIfPendingPr({
+    token, owner, repo, n,
+    docs: [{ ...plan, pathRel: planRel }, { ...spec, pathRel: specRel }],
+  });
+  if (adiado) return adiado;
+
   // Check plan.md
-  const planPath = path.join(featureDir, 'plan.md');
-  if (!existsSync(planPath)) {
-    errors.push('❌ `plan.md` não encontrado em `' + `${featureRel}/plan.md` + '`');
+  if (plan.content == null) {
+    errors.push('❌ `plan.md` não encontrado em `' + planRel + '`');
   } else {
-    const planContent = readFileSync(planPath, 'utf-8');
+    const planContent = plan.content;
     for (const faltante of describeMissingSections(planContent, REQUIRED_PLAN_SECTIONS)) {
       errors.push(renderMissingSection('plan.md', faltante));
     }
@@ -173,11 +241,10 @@ export async function validate({ issueNumber }) {
   }
 
   // Check spec.md
-  const specPath = path.join(featureDir, 'spec.md');
-  if (!existsSync(specPath)) {
-    errors.push('❌ `spec.md` não encontrado em `' + `${featureRel}/spec.md` + '`');
+  if (spec.content == null) {
+    errors.push('❌ `spec.md` não encontrado em `' + specRel + '`');
   } else {
-    const specContent = readFileSync(specPath, 'utf-8');
+    const specContent = spec.content;
     for (const faltante of describeMissingSections(specContent, REQUIRED_SPEC_SECTIONS)) {
       errors.push(renderMissingSection('spec.md', faltante));
     }

package/src/config.mjs

@@ -519,6 +519,24 @@ export const WORKFLOW_FILES = [
   'qa.yml',
 ];
 
+/**
+ * Workflows que PUBLICAM um documento gerado (branch própria + Pull Request).
+ *
+ * Lista explícita de propósito. O teste que verifica permissões selecionava os
+ * workflows por `content.includes('contents: write')` — um predicado que passa
+ * VACUAMENTE se o marcador sumir do YAML: nenhum arquivo é selecionado, o laço
+ * não roda, e o teste fica verde justamente no cenário que ele deveria pegar.
+ *
+ * Estes quatro precisam de `contents: write` (o commit vai por Git Data API) E
+ * de `pull-requests: write` (sem ela o commit existe e o PR não).
+ */
+export const ARTIFACT_WORKFLOW_FILES = [
+  'generate-spec.yml',
+  'generate-plan.yml',
+  'generate-bug.yml',
+  'decompose.yml',
+];
+
 export const ISSUE_TEMPLATE_FILES = [
   'plan-template.md',
   'spec-template.md',

package/src/lib/artifact-pr.mjs

@@ -0,0 +1,272 @@
+// Regras PURAS da publicação de artefatos por Pull Request.
+//
+// Os documentos gerados (spec.md, plan.md, bug.md, decomposition.md) iam para a
+// branch default por commit direto. Em repositório com proteção de branch isso
+// nem chega a rodar — `flow-run.mjs` classificava a recusa (GH006) como
+// definitiva e o fluxo morria com a chamada de IA já paga. E, mesmo sem
+// proteção, contornava a revisão que todo o resto do processo tem.
+//
+// Um PR por DOCUMENTO, não por issue: cada documento é revisado e mergeado
+// isoladamente, e o passo seguinte só roda com o anterior na base. É a mesma
+// política do `update --branch` (ver lib/pr-branch.mjs), aplicada ao fluxo.
+//
+// Tudo aqui é puro de propósito, pelo mesmo motivo do pr-branch.mjs: a suíte não
+// tem infraestrutura de mock de HTTP, então as DECISÕES (nome da branch, o que o
+// PR conta a quem revisa) ficam separadas das chamadas de rede, que moram em
+// api/github-rest.mjs.
+
+import { resolveBranchName } from './pr-branch.mjs';
+
+/** Prefixo de toda branch criada pelo spec-wave — inclusive as do `update --branch`. */
+export const ARTIFACT_BRANCH_PREFIX = 'spec-wave/';
+
+/**
+ * Documento → sufixo da branch e nome de exibição.
+ *
+ * `decomposition-apply` é um documento à parte de propósito: o `--apply`
+ * reescreve o decomposition.md anotado com as issues criadas, e essa anotação
+ * NÃO pode ir para a branch do rascunho — mutar um PR que alguém está revisando
+ * é o desfecho mais surpreendente disponível aqui.
+ */
+export const ARTIFACT_DOCS = {
+  spec: { suffix: 'spec', file: 'spec.md' },
+  plan: { suffix: 'plan', file: 'plan.md' },
+  bug: { suffix: 'bug', file: 'bug.md' },
+  decomposition: { suffix: 'decompose', file: 'decomposition.md' },
+  'decomposition-apply': { suffix: 'decompose-apply', file: 'decomposition.md' },
+};
+
+/** Nomes aceitos em `doc`, na ordem do fluxo. */
+export const ARTIFACT_DOC_NAMES = Object.keys(ARTIFACT_DOCS);
+
+function docSpec(doc) {
+  const spec = ARTIFACT_DOCS[doc];
+  if (!spec) {
+    throw new Error(
+      `Documento desconhecido: "${doc}". Use um de: ${ARTIFACT_DOC_NAMES.join(', ')}.`
+    );
+  }
+  return spec;
+}
+
+/**
+ * Branch do artefato (função PURA).
+ *
+ * Deliberadamente SEM timestamp e SEM slug do título: rodar o mesmo passo duas
+ * vezes tem que reaproveitar o mesmo PR, não espalhar uma branch por tentativa.
+ * O par (issue, documento) já identifica o trabalho de forma única — e o slug
+ * mudaria se alguém renomeasse a issue no meio, deixando um PR órfão.
+ *
+ * @param {object} params
+ * @param {number|string} params.issueNumber
+ * @param {string} params.doc chave de ARTIFACT_DOCS
+ * @returns {string}
+ */
+export function artifactBranch({ issueNumber, doc }) {
+  const { suffix } = docSpec(doc);
+  // Estrito de propósito: `parseInt` transformaria 1.5 em 1 e "42abc" em 42, ou
+  // seja, publicaria numa branch de OUTRA issue sem nenhum sinal. O número vem
+  // de argumento de CLI e de payload de evento — os dois chegam como texto.
+  const bruto = String(issueNumber ?? '').trim();
+  if (!/^\d+$/.test(bruto) || Number.parseInt(bruto, 10) <= 0) {
+    throw new Error(`Número de issue inválido para a branch do artefato: "${issueNumber}".`);
+  }
+  const n = Number.parseInt(bruto, 10);
+  const branch = `${ARTIFACT_BRANCH_PREFIX}${n}-${suffix}`;
+  // Passa pela mesma validação do `update --branch`: o nome é montado aqui, mas
+  // validá-lo é barato e protege contra um sufixo novo entrar quebrado.
+  const { error } = resolveBranchName(branch);
+  if (error) throw new Error(error);
+  return branch;
+}
+
+/**
+ * A branch é de uma publicação do spec-wave? (função PURA)
+ *
+ * Usado pela guarda do code-review.yml e do qa.yml: um PR de documento não é um
+ * PR de implementação, e deixar os dois workflows rodarem em cima dele move o
+ * board por engano. Cobre também as branches do `update --branch`
+ * (`spec-wave/update-v*`), o que é desejável — elas também não implementam nada.
+ *
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function isArtifactBranch(name) {
+  return String(name || '').startsWith(ARTIFACT_BRANCH_PREFIX);
+}
+
+// Rótulo humano de cada documento, para título e corpo do PR.
+const DOC_LABEL = {
+  spec: 'especificação funcional',
+  plan: 'plano técnico',
+  bug: 'documento de bug',
+  decomposition: 'rascunho de decomposição',
+  'decomposition-apply': 'registro das issues criadas',
+};
+
+/**
+ * Título do PR — e assunto do commit único (função PURA).
+ *
+ * A mesma frase nos dois lugares: no modo PR existe um commit só, e ver textos
+ * diferentes para a mesma mudança na lista de commits e no título do PR só gera
+ * dúvida. Mesmo critério do composePrTitle do update (lib/pr-branch.mjs).
+ *
+ * Sem `#N` no título de propósito — ver a nota sobre vínculo em
+ * `composeArtifactPrBody`.
+ *
+ * @returns {string}
+ */
+export function composeArtifactPrTitle({ doc, issueNumber, issueTitle = '' } = {}) {
+  docSpec(doc);
+  const n = Number.parseInt(issueNumber, 10);
+  const titulo = String(issueTitle).trim();
+  const alvo = titulo ? `${titulo} (issue ${n})` : `issue ${n}`;
+  return `docs(spec-wave): ${DOC_LABEL[doc]} de ${alvo}`;
+}
+
+/**
+ * Mensagem do commit ÚNICO da branch (função PURA).
+ *
+ * @returns {string}
+ */
+export function artifactCommitMessage({ doc, issueNumber, pathRel } = {}) {
+  docSpec(doc);
+  const n = Number.parseInt(issueNumber, 10);
+  const acao = doc === 'decomposition-apply'
+    ? 'registra as issues criadas em'
+    : 'gera';
+  return `docs: ${acao} ${pathRel} (issue ${n}) [spec-wave]\n`;
+}
+
+/**
+ * Corpo do PR (função PURA).
+ *
+ * **A issue é referenciada SÓ pela URL completa.** Não é preciosismo: o
+ * `code-review` extrai o vínculo do corpo do PR e MOVE O BOARD a partir dele
+ * (`extractIssueNumbers`, commands/code-review.mjs). São duas regexes:
+ *
+ *  • `EXPLICIT_LINK_RE` exige um verbo (`closes|fixes|resolves|implements`);
+ *  • `ANY_MENTION_RE`, ativa sob `codeReview.linkMode: "any-mention"`, casa
+ *    `#N` CRU — então um inocente "issue #42" já bastaria.
+ *
+ * E o próprio GitHub fecha a issue sozinho diante de `Closes #N`, independente
+ * das nossas regexes. A URL completa não casa com nenhuma das duas e não aciona
+ * o fechamento automático: um PR de documentação não fecha a Feature nem a move
+ * de coluna. A guarda de branch no code-review.yml/qa.yml é a segunda linha;
+ * esta é a primeira.
+ *
+ * @param {object} params
+ * @param {string} params.doc
+ * @param {string} params.issueUrl URL completa da issue (nunca "#N")
+ * @param {string} [params.issueTitle]
+ * @param {string} params.pathRel caminho do documento no repositório
+ * @param {string} params.base branch de destino
+ * @param {string} params.branch branch do PR
+ * @param {string} [params.nextLabel] label que destrava o passo seguinte
+ * @returns {string} markdown
+ */
+export function composeArtifactPrBody({
+  doc, issueUrl = '', issueTitle = '', pathRel = '', base = '?', branch = '?', nextLabel = null,
+} = {}) {
+  docSpec(doc);
+  const l = [];
+  l.push(`Documento gerado pelo spec-wave: **${DOC_LABEL[doc]}**.`);
+  l.push('');
+  l.push(`- Arquivo: \`${pathRel}\``);
+  l.push(`- Issue: ${issueUrl}${issueTitle ? ` — ${issueTitle}` : ''}`);
+  l.push(`- Base: \`${base}\` · Branch: \`${branch}\``);
+  l.push('');
+  l.push('## Como revisar');
+  l.push('');
+  l.push(
+    'Edite o arquivo **neste PR** se precisar corrigir — as edições são ' +
+    'preservadas. Regerar o documento por cima descartaria a revisão.'
+  );
+  if (nextLabel) {
+    l.push('');
+    l.push(
+      `O passo seguinte do fluxo (\`${nextLabel}\`) lê este documento da branch ` +
+      `\`${base}\`, então ele só roda **depois do merge** deste PR.`
+    );
+  }
+  l.push('');
+  l.push('---');
+  l.push(
+    '_A issue é citada por URL, sem `#número` e sem palavra de fechamento, de ' +
+    'propósito: assim este PR não fecha a issue nem move o board._'
+  );
+  return `${l.join('\n')}\n`;
+}
+
+/**
+ * Bloqueio "o documento existe, mas ainda não chegou à base" (função PURA).
+ *
+ * Mesmo formato dos bloqueios de lib/next-step.mjs: `{code, message, unblock}`.
+ * Sem isto, o `run` veria "o documento não está na base" e REGERARIA — pagando
+ * a IA de novo a cada execução até alguém mergear.
+ *
+ * Dois casos, com remédios diferentes — e é por isso que não são um só:
+ *
+ *  • `pending-pr`: há PR aberto. Revisar e mergear.
+ *  • `branch-only`: o commit passou e o PR NÃO foi aberto. Acontece quando a
+ *    organização proíbe o Actions de criar PRs ou o `GH_PR_TOKEN` está errado —
+ *    ou quando alguém fechou o PR sem mergear. Mandar "faça o merge do PR" aqui
+ *    seria mandar procurar uma tela que não existe.
+ *
+ * @param {object} params
+ * @param {string} params.pathRel
+ * @param {string} [params.state] estado devolvido por `loadArtifact`
+ * @param {{number: number|string, url?: string}|null} [params.pr]
+ * @param {string|null} [params.branch]
+ * @returns {{code: 'pr-pending'|'branch-without-pr', message: string, unblock: string}}
+ */
+export function awaitingMergeBlock({ pathRel, state = 'pending-pr', pr = null, branch = null } = {}) {
+  // Sem caminho, o texto vira "`undefined` foi commitado" — mensagem de erro que
+  // acusa a ferramenta em vez de orientar quem lê.
+  const alvo = pathRel ? `\`${pathRel}\`` : 'O documento';
+  if (state === 'branch-only' || !pr?.number) {
+    const onde = branch ? `\`${branch}\`` : 'uma branch do spec-wave';
+    return {
+      code: 'branch-without-pr',
+      message:
+        `${alvo} foi commitado em ${onde}, mas nenhum Pull Request está aberto ` +
+        'para ela — na branch base o documento não está.',
+      unblock:
+        `Abra o PR de ${onde} para a branch base e faça o merge. Se o PR falhou ao ser ` +
+        'aberto pelo Actions, rode `spec-wave doctor`: quase sempre é a opção "Allow ' +
+        'GitHub Actions to create and approve pull requests" desligada, ou o secret ' +
+        '`GH_PR_TOKEN` ausente. Reaplicar o gatilho REGERA o documento.',
+    };
+  }
+  return {
+    code: 'pr-pending',
+    message:
+      `${alvo} existe no PR #${pr.number}, que ainda não foi mergeado — ` +
+      'na branch base ele não está.',
+    unblock:
+      `Revise e faça o merge do PR #${pr.number}${pr.url ? ` (${pr.url})` : ''}. ` +
+      'Gerar de novo por cima descartaria o que foi revisado.',
+  };
+}
+
+/**
+ * Linha do comentário da issue que aponta o Pull Request (função PURA).
+ *
+ * Três desfechos possíveis, e os três precisam ser distinguíveis por quem lê a
+ * issue — dizer "PR aberto" quando não houve PR nenhum manda a pessoa procurar
+ * uma tela que não existe.
+ *
+ * @param {{pr: object|null, branch: string, unchanged: boolean}} published
+ * @returns {string}
+ */
+export function renderPrLine({ pr = null, branch = '?', unchanged = false } = {}) {
+  if (pr?.number) {
+    return pr.created === false
+      ? `🔀 Pull Request **atualizado**: #${pr.number} — ${pr.url}`
+      : `🔀 Pull Request: #${pr.number} — ${pr.url}`;
+  }
+  if (unchanged) {
+    return `♻️ O conteúdo gerado é idêntico ao já publicado em \`${branch}\` — nenhum commit novo.`;
+  }
+  return `⚠️ Commit enviado para \`${branch}\`, mas o Pull Request não pôde ser aberto — veja o log do run.`;
+}

package/src/lib/artifact-publish.mjs

@@ -0,0 +1,169 @@
+// Publicação de um documento gerado: branch + commit único + Pull Request.
+//
+// Substitui o `commitGenerated` do lib/flow-run.mjs, que commitava direto na
+// branch default. Em repositório com proteção de branch aquilo nem rodava — a
+// recusa (GH006) era classificada como definitiva e o job morria com a chamada
+// de IA já paga; e, sem proteção, contornava a revisão que todo o resto do
+// fluxo tem.
+//
+// **Por que via API e não via git local.** Os três motivos são independentes:
+//
+//  1. Roda igual nos dois modos. O runner tem checkout; o clone do usuário tem o
+//     trabalho DELE. Criar branch, commitar e voltar no clone alheio é uma
+//     coreografia que falha com working tree suja — e o `flow-run` já carregava
+//     duas exceções (identidade do git, falha de push) só por mexer em git local.
+//  2. Some a corrida de publicação. Cada documento tem branch própria, o pai do
+//     commit é a ponta dela, e `updateRef` é fast-forward. O laço de pull+push
+//     com backoff deixa de ser necessário.
+//  3. Commit da Git Data API vem verificado, o que satisfaz ruleset que exige
+//     assinatura — coisa que o git do runner não conseguiria.
+//
+// O preço: nada é gravado no working tree. É deliberado. Gravar sem commitar
+// deixaria no clone um arquivo que o usuário não pediu e que colide no `git pull`
+// depois do merge — justamente porque o merge pode trazer as edições do revisor.
+
+import {
+  getRepoDefaultBranch, compareBranches, findOpenPR, commitFilesToBranch,
+  ensurePullRequest, deleteBranch,
+} from '../api/github-rest.mjs';
+import { resolveBranchName, explainGitWriteError } from './pr-branch.mjs';
+import {
+  artifactBranch, composeArtifactPrTitle, composeArtifactPrBody, artifactCommitMessage,
+} from './artifact-pr.mjs';
+import { blobUrl } from './repo-links.mjs';
+
+/**
+ * Token usado para abrir o PR.
+ *
+ * Nos Actions o `GITHUB_TOKEN` só abre Pull Request se a opção "Allow GitHub
+ * Actions to create and approve pull requests" estiver ligada — desligada por
+ * padrão em muitas organizações. `GH_PR_TOKEN` é a saída sem depender de uma
+ * configuração de organização que nem todo time controla.
+ *
+ * Mesmo formato do `PROJECT_TOKEN` (commands/qa.mjs, code-review.mjs): variável
+ * específica com fallback para o token da execução.
+ */
+export function resolvePrToken(token, env = process.env) {
+  return env.SPEC_WAVE_PR_TOKEN || env.GH_PR_TOKEN || token;
+}
+
+/**
+ * A branch é resquício de um PR já mergeado? (função PURA)
+ *
+ * `identical`/`behind` significam que ela não tem NADA que a base já não tenha.
+ * Com PR aberto isso é normal (acabou de ser criada, ou o merge está em curso) e
+ * mexer nela seria mutar revisão alheia. Sem PR aberto, é lixo de um merge com
+ * squash: empilhar o próximo commit ali produziria um PR que reintroduz estado
+ * antigo, porque a ponta não é ancestral da base.
+ *
+ * @param {'identical'|'ahead'|'behind'|'diverged'|null} status
+ * @param {object|null} openPr
+ * @returns {boolean}
+ */
+export function isStaleArtifactBranch(status, openPr) {
+  if (openPr) return false;
+  return status === 'identical' || status === 'behind';
+}
+
+/**
+ * Publica o documento e devolve o PR.
+ *
+ * @param {object} params
+ * @param {string} params.token
+ * @param {string} params.owner
+ * @param {string} params.repo
+ * @param {string} params.doc chave de ARTIFACT_DOCS
+ * @param {number|string} params.issueNumber
+ * @param {string} [params.issueTitle]
+ * @param {string} [params.issueUrl] URL da issue (NUNCA "#N" — ver artifact-pr.mjs)
+ * @param {string} params.pathRel caminho do documento no repositório
+ * @param {string} params.content conteúdo FINAL do documento
+ * @param {string|null} [params.base] branch de destino (null = default do repo)
+ * @param {string|null} [params.nextLabel] label do passo seguinte, para o corpo do PR
+ * @param {object} [params.deps] injeção para teste
+ * @returns {Promise<{branch, base, commitSha, unchanged, pr, blobUrl, warning}>}
+ */
+export async function publishArtifact({
+  token, owner, repo, doc, issueNumber, issueTitle = '', issueUrl = '',
+  pathRel, content, base = null, nextLabel = null, deps = {},
+}) {
+  const api = {
+    getRepoDefaultBranch, compareBranches, findOpenPR, commitFilesToBranch,
+    ensurePullRequest, deleteBranch, ...deps,
+  };
+
+  const branch = artifactBranch({ issueNumber, doc });
+  const { error: branchError } = resolveBranchName(branch);
+  if (branchError) throw new Error(branchError);
+
+  const alvo = base || await api.getRepoDefaultBranch(token, owner, repo);
+  if (branch === alvo) {
+    throw new Error(
+      `A branch do artefato ("${branch}") é a própria base — publicar nela seria ` +
+      'exatamente o commit direto que este fluxo existe para evitar.'
+    );
+  }
+
+  // Branch obsoleta ANTES de commitar: depois já seria tarde, o commit teria um
+  // pai errado.
+  const [status, prAberto] = await Promise.all([
+    api.compareBranches(token, owner, repo, alvo, branch),
+    api.findOpenPR(token, owner, repo, branch).catch(() => null),
+  ]);
+  if (isStaleArtifactBranch(status, prAberto)) {
+    console.warn(
+      `Branch "${branch}" sobrou de um merge anterior e não tem PR aberto — ` +
+      'recriando a partir da base.'
+    );
+    await api.deleteBranch(token, owner, repo, branch).catch(() => {});
+  }
+
+  let commit;
+  try {
+    commit = await api.commitFilesToBranch(token, owner, repo, {
+      branch,
+      base: alvo,
+      files: [{ path: pathRel, content }],
+      message: artifactCommitMessage({ doc, issueNumber, pathRel }),
+    });
+  } catch (err) {
+    throw new Error(`Falha ao publicar ${pathRel} em "${branch}": ${explainGitWriteError(err)}`);
+  }
+
+  // O PR fica num try SEPARADO, pelo mesmo motivo do `update --branch`: um token
+  // com "Contents: write" pode não ter "Pull requests: write", e essa falha não
+  // invalida o commit — a mensagem precisa dizer que a branch existe.
+  let pr = null;
+  let warning = null;
+  try {
+    pr = await api.ensurePullRequest(resolvePrToken(token), owner, repo, {
+      branch,
+      base: alvo,
+      title: composeArtifactPrTitle({ doc, issueNumber, issueTitle }),
+      body: composeArtifactPrBody({
+        doc, issueUrl, issueTitle, pathRel, base: alvo, branch, nextLabel,
+      }),
+    });
+    if (!pr && !commit.unchanged) {
+      warning =
+        `A branch "${branch}" não tem nada novo em relação a "${alvo}" e não há PR ` +
+        'aberto para ela — nada a revisar.';
+    }
+  } catch (err) {
+    warning =
+      `Commit ${commit.commitSha?.slice(0, 7)} enviado para "${branch}", mas o Pull Request ` +
+      `não pôde ser aberto: ${explainGitWriteError(err)}. ` +
+      `Abra manualmente: https://github.com/${owner}/${repo}/compare/` +
+      `${alvo}...${encodeURIComponent(branch)}?expand=1`;
+  }
+
+  return {
+    branch,
+    base: alvo,
+    commitSha: commit.commitSha,
+    unchanged: commit.unchanged,
+    pr,
+    blobUrl: blobUrl({ owner, repo, ref: branch, pathRel }),
+    warning,
+  };
+}

package/src/lib/doc-availability.mjs

@@ -19,9 +19,31 @@
  * @param {boolean|null} params.onRemote true = existe no remoto; false = não
  *   existe; null = não foi possível consultar (sem token/rede)
  * @param {string} params.fallback o que o comando fará sem o documento
+ * @param {string|null} [params.branch] branch do artefato quando NÃO há PR aberto
+ * @param {{number: number|string, url?: string}|null} [params.pr] PR ABERTO que
+ *   contém o documento — a publicação por Pull Request criou este quarto caso, e
+ *   sem ele a mensagem afirma "não existe no repositório" sobre um documento que
+ *   está gerado e esperando revisão. Mentira cara: manda o executor refazer o
+ *   trabalho do zero.
  * @returns {string}
  */
-export function missingDocMessage({ pathRel, onRemote, fallback }) {
+export function missingDocMessage({ pathRel, onRemote, fallback, pr = null, branch = null }) {
+  if (pr?.number) {
+    return (
+      `${pathRel} está no PR #${pr.number}, ainda NÃO mergeado` +
+      `${pr.url ? ` (${pr.url})` : ''} — revise e faça o merge, ou rode ` +
+      `\`gh pr checkout ${pr.number}\`. Seguir agora ignoraria o documento já gerado.`
+    );
+  }
+  // Commit publicado, PR não aberto. Sem este ramo a mensagem cairia no "não
+  // existe no repositório" — e o documento está lá, numa branch.
+  if (branch) {
+    return (
+      `${pathRel} está na branch \`${branch}\`, sem Pull Request aberto e fora da base — ` +
+      `rode \`git fetch origin ${branch} && git checkout ${branch}\` para vê-lo. ` +
+      'Seguir agora ignoraria o documento já gerado.'
+    );
+  }
   if (onRemote === true) {
     return (
       `${pathRel} existe no repositório mas NÃO no seu clone — rode \`git pull\` e ` +