@spec-wave/cli 0.26.0 → 0.28.0

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 ` +

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;
+}