@spec-wave/cli 0.26.0 → 0.28.0

package/src/commands/implement.mjs

@@ -13,6 +13,7 @@ import { listSubIssues, getIssueParent, addProjectItem, getItemSingleSelectValue
 import { detectIssueType } from '../lib/issue-type.mjs';
 import { bugDocPaths } from '../lib/bug-doc.mjs';
 import { missingDocMessage, existsOnRemote } from '../lib/doc-availability.mjs';
+import { loadArtifact } from '../lib/doc-source.mjs';
 import { buildBugContext } from '../lib/bug-context.mjs';
 import { slugify } from '../lib/slugify.mjs';
 import { parseDependencies, orderStories, formatDependencyLine } from '../lib/dependencies.mjs';
@@ -45,6 +46,32 @@ async function resolveFeature(token, startNodeId) {
   return null;
 }
 
+/**
+ * Onde está o documento que não veio no clone — incluindo Pull Request aberto.
+ *
+ * `existsOnRemote` sozinho consulta só a branch base, então um documento
+ * recém-gerado (que vive na branch do PR até alguém mergear) era reportado como
+ * "não existe no repositório". Mentira cara: manda o executor refazer do zero um
+ * trabalho que está pronto, esperando revisão.
+ *
+ * Best-effort como a sonda que substitui: nunca lança, nunca bloqueia.
+ */
+async function probeMissingDoc({ token, owner, repo, root, pathRel, doc, issueNumber, fallback }) {
+  if (issueNumber) {
+    const achado = await loadArtifact({ token, owner, repo, root, pathRel, doc, issueNumber })
+      .catch(() => null);
+    if (achado?.state === 'pending-pr' || achado?.state === 'branch-only') {
+      return missingDocMessage({
+        pathRel, onRemote: false, fallback, pr: achado.pr, branch: achado.ref,
+      });
+    }
+    if (achado?.state === 'remote') return missingDocMessage({ pathRel, onRemote: true, fallback });
+    if (achado?.state === 'missing') return missingDocMessage({ pathRel, onRemote: false, fallback });
+  }
+  const onRemote = await existsOnRemote({ getFileContent, token, owner, repo, pathRel });
+  return missingDocMessage({ pathRel, onRemote, fallback });
+}
+
 // Lê spec.md/plan.md de um docs/features/<slug> se existirem.
 function readSpecPlan(featureDir) {
   const specPath = path.join(featureDir, 'spec.md');
@@ -188,7 +215,12 @@ function buildContext({
     lines.push('');
     lines.push(`3. **Ao concluir TODA a Story** (todas as Tasks na Etapa ${STAGE_DONE}):`);
     lines.push('   1. Faça o **commit** de todas as mudanças da implementação.');
-    lines.push(`   2. Abra o **Pull Request** da Story #${issue.number}.`);
+    // Draft de propósito: numa pilha de Stories (um PR baseado no anterior),
+    // cada rebase em cascata dispararia o CI inteiro em PRs que ninguém vai
+    // mergear naquele estado. Rascunho não mergeia (o GitHub bloqueia) e o
+    // required check continua valendo: quem revisa marca o PR como pronto, o
+    // `ready_for_review` dispara o CI, e só então o merge destrava.
+    lines.push(`   2. Abra o **Pull Request** da Story #${issue.number} **como rascunho** (\`gh pr create --draft\`) — o CI não roda em rascunho; quem revisa marca o PR como pronto e é aí que os checks disparam.`);
     lines.push(
       `   3. **Avance a Etapa da Story #${issue.number} para ${STAGE_CODE_REVIEW}** ` +
       `(reinicie o Status para ${PROGRESS_TODO}). As Tasks já estão em ${STAGE_DONE}.`
@@ -371,7 +403,7 @@ export function buildFeatureContext({
   lines.push(`   1. **Ao começar:** Status da Task → **${PROGRESS_IN_PROGRESS}** (a Etapa continua ${STAGE_DEVELOPMENT}).`);
   lines.push('   2. **Implemente** a Task por completo.');
   lines.push(`   3. **Ao concluir:** **avance a Task para a Etapa ${STAGE_DONE}** com Status **${PROGRESS_DONE}**.`);
-  lines.push(`3. **Ao concluir TODAS as Tasks da Story:** faça o **commit**, abra o **Pull Request** da Story e **avance a Etapa da Story para ${STAGE_CODE_REVIEW}** (Status ${PROGRESS_TODO}).`);
+  lines.push(`3. **Ao concluir TODAS as Tasks da Story:** faça o **commit**, abra o **Pull Request** da Story **como rascunho** (\`gh pr create --draft\` — o CI não roda em rascunho; quem revisa marca o PR como pronto e os checks disparam) e **avance a Etapa da Story para ${STAGE_CODE_REVIEW}** (Status ${PROGRESS_TODO}).`);
   lines.push('4. Só então inicie a próxima Story.');
   lines.push('');
   lines.push(
@@ -463,12 +495,9 @@ async function implementBug({ token, owner, repo, config, bug, dryRun, repoRoot
     bugDoc = readFileSync(fileAbs, 'utf-8');
     p.log.info(`bug.md encontrado em ${chalk.cyan(fileRel)}.`);
   } else {
-    const onRemote = await existsOnRemote({
-      getFileContent, token, owner, repo, pathRel: fileRel,
-    });
-    p.log.warn(missingDocMessage({
-      pathRel: fileRel,
-      onRemote,
+    p.log.warn(await probeMissingDoc({
+      token, owner, repo, root: repoRoot,
+      pathRel: fileRel, doc: 'bug', issueNumber: bug.number,
       fallback: 'o contexto assume a investigação inteira.',
     }));
   }
@@ -626,12 +655,9 @@ async function implementFeature({ token, owner, repo, config, feature, featureDi
     specPlan = readSpecPlan(featureDir);
   } else {
     const specRel = `docs/features/${slugify(feature.title)}/spec.md`;
-    const onRemote = await existsOnRemote({
-      getFileContent, token, owner, repo, pathRel: specRel,
-    });
-    p.log.warn(missingDocMessage({
-      pathRel: specRel,
-      onRemote,
+    p.log.warn(await probeMissingDoc({
+      token, owner, repo, root: repoRoot,
+      pathRel: specRel, doc: 'spec', issueNumber: feature.number,
       fallback: 'seguindo só com as Stories.',
     }));
   }
@@ -839,14 +865,13 @@ export async function implement({ issue: issueArg, featureDir: featureDirOpt, dr
     const specRel = feature?.title
       ? `docs/features/${slugify(feature.title)}/spec.md`
       : featureDir;
-    const onRemote = feature?.title
-      ? await existsOnRemote({ getFileContent, token, owner, repo, pathRel: specRel })
-      : null;
-    p.log.warn(missingDocMessage({
-      pathRel: specRel,
-      onRemote,
-      fallback: 'seguindo só com as tasks.',
-    }));
+    p.log.warn(feature?.title
+      ? await probeMissingDoc({
+          token, owner, repo, root: repoRoot,
+          pathRel: specRel, doc: 'spec', issueNumber: feature?.number,
+          fallback: 'seguindo só com as tasks.',
+        })
+      : missingDocMessage({ pathRel: specRel, onRemote: null, fallback: 'seguindo só com as tasks.' }));
   } else {
     p.log.warn('Não foi possível resolver a Feature; seguindo só com as tasks (use --feature-dir).');
   }

package/src/commands/install-skill.mjs

@@ -141,18 +141,28 @@ export function renderContent(format, parsed, version) {
   }
 }
 
-// Insere/atualiza o bloco spec-wave num arquivo compartilhado (AGENTS.md),
-// preservando o restante do conteúdo. Idempotente via marcadores.
-export function mergeAgentsFile(destPath, block) {
-  const existing = existsSync(destPath) ? readFileSync(destPath, 'utf-8') : '';
+// Insere/atualiza o bloco spec-wave num texto de arquivo compartilhado
+// (AGENTS.md), preservando o restante do conteúdo. Idempotente via marcadores.
+//
+// Versão PURA, separada da que lê o disco porque o modo `--branch` do update
+// precisa mesclar o bloco no conteúdo da BASE, não no do arquivo local: o
+// AGENTS.md do desenvolvedor pode ter edições ainda não commitadas, e arrastá-las
+// para dentro do Pull Request seria enviar o que ninguém pediu para revisar.
+export function mergeAgentsContent(existing, block) {
+  const atual = existing || '';
   const blockRe = new RegExp(
     `${escapeRe(BLOCK_START)}[\\s\\S]*?${escapeRe(BLOCK_END)}\\n?`,
   );
-  if (blockRe.test(existing)) {
-    return existing.replace(blockRe, block);
+  if (blockRe.test(atual)) {
+    return atual.replace(blockRe, block);
   }
-  if (existing.trim() === '') return block;
-  return `${existing.trimEnd()}\n\n${block}`;
+  if (atual.trim() === '') return block;
+  return `${atual.trimEnd()}\n\n${block}`;
+}
+
+// Mesmo merge, lendo o arquivo de destino do disco.
+export function mergeAgentsFile(destPath, block) {
+  return mergeAgentsContent(existsSync(destPath) ? readFileSync(destPath, 'utf-8') : '', block);
 }
 
 function escapeRe(s) {

package/src/commands/preflight.mjs

@@ -0,0 +1,322 @@
+// Preflight de uma rodada de geração de specs por milestone.
+//
+// Existe porque **cada geração paga um modelo**: descobrir na sétima Feature que
+// a credencial estava errada custa sete gerações. Este comando levanta de uma
+// vez tudo que decide a estratégia da rodada e tudo que costuma fazê-la falhar
+// no fim — antes de gerar qualquer coisa.
+//
+// Ele NÃO é um segundo `doctor`. As verificações de ambiente reaproveitam os
+// mesmos inspetores puros que o doctor usa (`describeModeState`,
+// `inspectPrPublishing`); o que é novo aqui é o **inventário da milestone**:
+// quais Features existem, e onde está o `spec.md` de cada uma.
+//
+// E "onde está" é a parte que não dá para improvisar com `existsSync`. Um
+// documento recém-gerado vive numa branch `spec-wave/<n>-spec` que ninguém
+// mergeou: quem procura só no disco o declara ausente e manda gerar de novo —
+// pagando o modelo pela segunda vez pelo mesmo documento. Por isso o estado sai
+// de `artifactStates`, que enxerga as quatro camadas.
+
+import * as p from '@clack/prompts';
+import chalk from 'chalk';
+
+import { resolveToken } from '../api/auth.mjs';
+import {
+  getRepoDefaultBranch, getRepoVariable, listMilestones, listIssuesByMilestone,
+} from '../api/github-rest.mjs';
+import { CONFIG_FILE } from '../config.mjs';
+import { inspectPrPublishing, readPrPublishingContext } from './doctor.mjs';
+import { configuredMode, describeModeState, EXECUTION_VARIABLE } from '../lib/execution-mode.mjs';
+import { detectIssueType } from '../lib/issue-type.mjs';
+import { isAwaitingMerge, artifactStates } from '../lib/doc-source.mjs';
+import { featureDocPaths } from '../lib/doc-paths.mjs';
+import { STEPS } from '../lib/next-step.mjs';
+import { loadConfig } from '../lib/project-root.mjs';
+import { unguardedWorkflows } from './mode.mjs';
+
+const TRIGGER_LABELS = Object.values(STEPS).map(s => s.trigger).filter(Boolean);
+
+/**
+ * O inventário da milestone (função PURA — é onde mora a decisão).
+ *
+ * Separa as Features em quatro destinos porque cada um pede uma ação diferente,
+ * e confundi-los é caro nos dois sentidos: tratar `pending-pr` como ausente
+ * regera um documento já pago e ainda descarta a revisão em curso; tratar
+ * `unknown` (falha de rede) como pronto pula uma Feature que ninguém escreveu.
+ *
+ * @param {object} [a]
+ * @param {Array<{number:number,title:string,state?:string,labels?:Array}>} [a.issues]
+ *        issues da milestone, como a API devolve (de qualquer tipo)
+ * @param {Record<number, {state: string, pr: object|null}>} [a.specStates]
+ *        estado do `spec.md` por número de issue
+ * @returns {{ features: object[], gerar: object[], prontas: object[],
+ *             aguardandoMerge: object[], indefinidas: object[], fechadas: object[],
+ *             gatilhosPendentes: Array<{number:number,labels:string[]}> }}
+ */
+export function inspectMilestone({ issues = [], specStates = {} } = {}) {
+  const features = (issues || [])
+    .filter(i => detectIssueType(i) === 'Feature')
+    .map(i => {
+      const { state = 'unknown', pr = null } = specStates[i.number] || {};
+      return {
+        number: i.number,
+        title: i.title,
+        closed: i.state === 'closed',
+        spec: state,
+        pr,
+        labels: (i.labels || []).map(l => (typeof l === 'string' ? l : l?.name)).filter(Boolean),
+      };
+    })
+    .sort((a, b) => a.number - b.number);
+
+  const abertas = features.filter(f => !f.closed);
+  return {
+    features,
+    fechadas: features.filter(f => f.closed),
+    gerar: abertas.filter(f => f.spec === 'missing'),
+    prontas: abertas.filter(f => f.spec === 'local' || f.spec === 'remote'),
+    aguardandoMerge: abertas.filter(f => isAwaitingMerge(f.spec)),
+    indefinidas: abertas.filter(f => f.spec === 'unknown'),
+    // Label de gatilho grudada significa Action em execução — ou uma que falhou e
+    // a deixou para trás. Nos dois casos o `run` se recusa a executar (portão
+    // `trigger-pending`), então a rodada travaria Feature a Feature.
+    gatilhosPendentes: features
+      .map(f => ({ number: f.number, labels: f.labels.filter(l => TRIGGER_LABELS.includes(l)) }))
+      .filter(f => f.labels.length > 0),
+  };
+}
+
+/**
+ * Resolve o título da milestone para o número que a API de issues aceita (PURA).
+ *
+ * Casamento exato primeiro; sem ele, um único casamento sem diferenciar
+ * maiúsculas. Ambíguo é erro, não escolha silenciosa: gerar as specs da
+ * milestone errada custa uma geração por Feature.
+ *
+ * @param {Array<{number:number,title:string,state?:string}>} milestones
+ * @param {string} titulo
+ * @returns {{ milestone: object|null, error: string|null }}
+ */
+export function resolveMilestone(milestones = [], titulo = '') {
+  const alvo = String(titulo || '').trim();
+  const lista = () => (milestones.length
+    ? milestones.map(m => `"${m.title}"`).join(', ')
+    : '(o repositório não tem milestone nenhuma)');
+
+  if (!alvo) return { milestone: null, error: `Milestone não informada. Existem: ${lista()}.` };
+
+  const exata = milestones.find(m => m.title === alvo);
+  if (exata) return { milestone: exata, error: null };
+
+  const caseInsensitive = milestones.filter(m => m.title.toLowerCase() === alvo.toLowerCase());
+  if (caseInsensitive.length === 1) return { milestone: caseInsensitive[0], error: null };
+  if (caseInsensitive.length > 1) {
+    return { milestone: null, error: `Milestone "${alvo}" é ambígua entre ${lista()}.` };
+  }
+  return { milestone: null, error: `Milestone "${alvo}" não existe. Existem: ${lista()}.` };
+}
+
+/**
+ * Veredito final da rodada (função PURA).
+ *
+ * `bloqueios` impedem gerar; `avisos` não. A distinção é a razão de o comando
+ * existir: sair 1 por algo que não impede a geração faria o usuário aprender a
+ * ignorar o preflight, que é o mesmo que não o ter.
+ *
+ * @returns {{ status: 'ok'|'aviso'|'bloqueio', bloqueios: string[], avisos: string[] }}
+ */
+export function inspectPreflight({
+  tokenOk = true, modo = null, publicacao = null, inventario = null,
+} = {}) {
+  const bloqueios = [];
+  const avisos = [];
+
+  if (!tokenOk) bloqueios.push('Sem token utilizável para este repositório.');
+
+  if (modo?.status === 'problem') bloqueios.push(modo.summary);
+  else if (modo?.status === 'warn') avisos.push(modo.summary);
+
+  // A publicação por PR é o desfecho de TODA geração: sem ela o documento é
+  // gerado, o commit criado e nenhum PR aparece — a falha mais cara do fluxo,
+  // porque o modelo já foi pago quando ela acontece.
+  if (publicacao?.status === 'fail') bloqueios.push(...publicacao.notes);
+  else if (publicacao?.status === 'warn') avisos.push(...publicacao.notes);
+
+  if (inventario) {
+    if (inventario.features.length === 0) {
+      bloqueios.push('Nenhuma Feature [FEATURE] nesta milestone.');
+    } else if (inventario.gerar.length === 0) {
+      avisos.push('Nenhuma Feature pendente: todas já têm spec.md.');
+    }
+    if (inventario.gatilhosPendentes.length > 0) {
+      avisos.push(
+        `${inventario.gatilhosPendentes.length} issue(s) com label de gatilho pendente — ` +
+        'o `run` se recusa a executar nelas até a label sair.'
+      );
+    }
+    if (inventario.aguardandoMerge.length > 0) {
+      avisos.push(
+        `${inventario.aguardandoMerge.length} spec(s) já geradas aguardando merge — ` +
+        'NÃO as gere de novo: o documento existe e regerá-lo descarta a revisão.'
+      );
+    }
+    if (inventario.indefinidas.length > 0) {
+      avisos.push(
+        `${inventario.indefinidas.length} Feature(s) com estado indeterminado (falha de rede) — ` +
+        'confirme antes de gerar, para não pagar duas vezes.'
+      );
+    }
+  }
+
+  if (bloqueios.length) return { status: 'bloqueio', bloqueios, avisos };
+  if (avisos.length) return { status: 'aviso', bloqueios, avisos };
+  return { status: 'ok', bloqueios, avisos };
+}
+
+const MARCA = { local: '✓ no disco', remote: '✓ na base', 'pending-pr': '⏳ em PR aberto', 'branch-only': '⚠ em branch sem PR', missing: '· gerar', unknown: '? indeterminado' };
+
+export async function preflight({ milestone: milestoneArg, json = false } = {}) {
+  const saida = { milestone: null, modo: null, publicacao: null, inventario: null, veredito: null };
+  const falhar = (msg) => {
+    if (json) console.log(JSON.stringify({ ...saida, erro: msg }, null, 2));
+    else p.log.error(msg);
+    process.exitCode = 1;
+  };
+
+  if (!json) p.intro(chalk.bold('spec-wave preflight'));
+
+  const { config, root, error: configError } = loadConfig();
+  if (configError || !config?.owner || !config?.repo) {
+    return falhar(
+      `${configError || `${CONFIG_FILE} sem owner/repo`} — rode \`spec-wave init\` antes.`
+    );
+  }
+  const { owner, repo } = config;
+
+  let token;
+  try {
+    token = await resolveToken();
+  } catch (err) {
+    return falhar(`Sem token utilizável para ${owner}/${repo}: ${err.message}`);
+  }
+
+  const s = json ? null : p.spinner();
+  s?.start('Consultando o repositório...');
+
+  let base;
+  try {
+    base = await getRepoDefaultBranch(token, owner, repo);
+  } catch (err) {
+    s?.stop('');
+    return falhar(`Não foi possível ler o repositório ${owner}/${repo}: ${err.message}`);
+  }
+
+  // --- Modo de execução: config × variável (o mesmo par que o doctor confere).
+  let variable;
+  try {
+    variable = await getRepoVariable(token, owner, repo, EXECUTION_VARIABLE);
+  } catch {
+    variable = undefined; // exige admin — "não deu para ler" não é "ausente"
+  }
+  const modo = describeModeState({
+    configured: configuredMode(config),
+    variable,
+    unguardedWorkflows: unguardedWorkflows(root),
+  });
+
+  // --- Publicação por Pull Request: é o desfecho de toda geração.
+  const publicacao = inspectPrPublishing(
+    await readPrPublishingContext({ token, owner, repo, root })
+  );
+
+  // --- Inventário da milestone.
+  let milestones;
+  try {
+    milestones = await listMilestones(token, owner, repo);
+  } catch (err) {
+    s?.stop('');
+    return falhar(`Não foi possível listar as milestones: ${err.message}`);
+  }
+  const { milestone, error: msError } = resolveMilestone(milestones, milestoneArg);
+  if (msError) {
+    s?.stop('');
+    return falhar(msError);
+  }
+
+  let issues;
+  try {
+    issues = await listIssuesByMilestone(token, owner, repo, milestone.number);
+  } catch (err) {
+    s?.stop('');
+    return falhar(`Não foi possível listar as issues da milestone "${milestone.title}": ${err.message}`);
+  }
+
+  // O estado do spec.md de cada Feature, nas quatro camadas. Uma issue por vez:
+  // são até 3 requisições cada, e disparar tudo de uma vez numa milestone de 20
+  // Features é o caminho mais curto para o rate limit secundário.
+  const featureIssues = issues.filter(i => detectIssueType(i) === 'Feature');
+  const specStates = {};
+  for (const issue of featureIssues) {
+    const docs = featureDocPaths(root, issue, 'Feature');
+    const estados = await artifactStates({
+      token, owner, repo, root, base,
+      issueNumber: issue.number,
+      docs: [{ doc: 'spec', pathRel: docs.spec.rel }],
+    });
+    specStates[issue.number] = estados.spec;
+  }
+
+  const inventario = inspectMilestone({ issues, specStates });
+  const veredito = inspectPreflight({ tokenOk: true, modo, publicacao, inventario });
+  s?.stop(`Milestone "${milestone.title}": ${inventario.features.length} Feature(s).`);
+
+  Object.assign(saida, {
+    milestone: { title: milestone.title, number: milestone.number, base },
+    modo: { configured: configuredMode(config), variable: variable ?? null, status: modo.status, summary: modo.summary },
+    publicacao: { status: publicacao.status, notes: publicacao.notes },
+    inventario,
+    veredito,
+  });
+
+  if (json) {
+    console.log(JSON.stringify(saida, null, 2));
+    if (veredito.status === 'bloqueio') process.exitCode = 1;
+    return saida;
+  }
+
+  // ---------- Relatório ----------
+  const linhas = [];
+  linhas.push(`${chalk.bold('Repositório:')} ${owner}/${repo} (base: ${base})`);
+  linhas.push(`${chalk.bold('Modo:')} config=${configuredMode(config)} · variável=${variable ?? '<ausente>'}`);
+  linhas.push(`   ${modo.summary}`);
+  linhas.push(`${chalk.bold('Publicação por PR:')} ${publicacao.status}`);
+  for (const nota of publicacao.notes) linhas.push(`   ${nota}`);
+  p.note(linhas.join('\n'), 'Ambiente');
+
+  const inv = [];
+  for (const f of inventario.features) {
+    const marca = f.closed ? '× fechada' : (MARCA[f.spec] || f.spec);
+    const pr = f.pr ? chalk.dim(` PR #${f.pr.number}`) : '';
+    inv.push(`  ${marca.padEnd(20)} #${f.number} ${f.title.slice(0, 60)}${pr}`);
+  }
+  if (inventario.gatilhosPendentes.length) {
+    inv.push('');
+    inv.push(chalk.yellow('  Labels de gatilho pendentes (remova antes de gerar):'));
+    for (const g of inventario.gatilhosPendentes) inv.push(`    #${g.number}: ${g.labels.join(', ')}`);
+  }
+  p.note(inv.join('\n'), `Milestone "${milestone.title}" — ${inventario.gerar.length} a gerar`);
+
+  for (const a of veredito.avisos) p.log.warn(a);
+  for (const b of veredito.bloqueios) p.log.error(b);
+
+  if (veredito.status === 'bloqueio') {
+    p.outro(`${veredito.bloqueios.length} bloqueio(s). Resolva antes de gerar.`);
+    process.exitCode = 1;
+    return saida;
+  }
+  p.outro(
+    inventario.gerar.length
+      ? `Preflight ok. Confirme a lista com o usuário antes de gerar ${inventario.gerar.length} spec(s).`
+      : 'Preflight ok. Nada a gerar.'
+  );
+  return saida;
+}

package/src/commands/run.mjs

@@ -20,9 +20,9 @@ import path from 'node:path';
 import chalk from 'chalk';
 
 import { resolveToken } from '../api/auth.mjs';
-import { getIssue, getPR, getFileContent, listPullRequestReviews } from '../api/github-rest.mjs';
+import { getIssue, getPR, listPullRequestReviews } from '../api/github-rest.mjs';
 import { loadProjectConfig } from '../lib/board.mjs';
-import { existsOnRemote } from '../lib/doc-availability.mjs';
+import { loadArtifact } from '../lib/doc-source.mjs';
 import { featureDocPaths, bugDocPaths } from '../lib/doc-paths.mjs';
 import { isActionsRun, resolveFlowContext } from '../lib/flow-run.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
@@ -114,19 +114,6 @@ function releaseLock(file) {
   } catch { /* já removido */ }
 }
 
-// Commits locais ainda não publicados: gerar o próximo documento por cima de um
-// anterior que ficou só no clone é execução parcial disfarçada de sucesso.
-function unpushedCommits(root) {
-  try {
-    const out = execSync('git rev-list --count @{u}..HEAD', {
-      cwd: root || process.cwd(), encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'],
-    }).trim();
-    return Number.parseInt(out, 10) || 0;
-  } catch {
-    return 0; // sem upstream configurado: não dá para afirmar nada
-  }
-}
-
 function assertNotInActions() {
   if (!isActionsRun()) return;
   throw new Error(
@@ -189,18 +176,42 @@ export function docsToProbe(decision, type) {
   return stepDocs(decision.action, type);
 }
 
-async function probeRemote({ alvos, docs, docPaths, token, owner, repo }) {
-  if (alvos.length === 0) return docs;
+/**
+ * Resolve o estado remoto dos documentos que faltam no clone.
+ *
+ * Duas camadas, não uma: além da branch base, o documento pode estar num Pull
+ * Request ainda não mergeado — é onde ele NASCE agora. Sem essa segunda camada,
+ * o `run` concluiria "não existe" e regeraria a spec a cada execução até alguém
+ * mergear, pagando a IA de novo toda vez e descartando as edições do revisor.
+ *
+ * `doc` do resolvedor usa 'decomposition' com o mesmo nome do fluxo, então o
+ * mapeamento é direto.
+ */
+async function probeRemote({ alvos, docs, docPaths, token, owner, repo, root, issueNumber }) {
+  if (alvos.length === 0) return { docs, docPrs: {} };
 
   const atualizado = { ...docs };
+  const docPrs = {};
   for (const doc of alvos) {
-    const onRemote = await existsOnRemote({
-      getFileContent, token, owner, repo, pathRel: docPaths[doc],
-    });
-    if (onRemote === true) atualizado[doc] = 'remote';
-    else if (onRemote === null) atualizado[doc] = 'unknown';
+    const achado = await loadArtifact({
+      token, owner, repo, root, pathRel: docPaths[doc], doc, issueNumber,
+    }).catch(() => null);
+
+    if (!achado) {
+      atualizado[doc] = 'unknown';
+      continue;
+    }
+    // 'local' aqui só aconteceria se o arquivo tivesse aparecido no meio da
+    // execução; manter o estado que a sonda local já apurou é mais previsível.
+    if (achado.state === 'local') continue;
+    atualizado[doc] = achado.state;
+    // Guarda PR e branch: o bloqueio de `branch-only` cita a branch, porque não
+    // há PR nenhum a citar.
+    if (achado.state === 'pending-pr' || achado.state === 'branch-only') {
+      docPrs[doc] = { pr: achado.pr || null, branch: achado.ref || null };
+    }
   }
-  return atualizado;
+  return { docs: atualizado, docPrs };
 }
 
 // ---------------------------------------------------------------------------
@@ -432,8 +443,10 @@ export async function run(issueArg, options = {}) {
       if (remoteCheck) {
         const alvos = docsToProbe(decision, type).filter(doc => docs[doc] === 'missing');
         if (alvos.length > 0) {
-          const docsRemotos = await probeRemote({ alvos, docs, docPaths, token, owner, repo });
-          decision = nextStep({ ...entrada, docs: docsRemotos });
+          const sondado = await probeRemote({
+            alvos, docs, docPaths, token, owner, repo, root, issueNumber,
+          });
+          decision = nextStep({ ...entrada, docs: sondado.docs, docPrs: sondado.docPrs });
         }
       }
       ultimaDecisao = decision;
@@ -470,11 +483,19 @@ export async function run(issueArg, options = {}) {
         break;
       }
 
-      const pendentes = unpushedCommits(root);
-      if (pendentes > 0) {
-        console.warn(chalk.yellow(
-          `\n⚠️  ${pendentes} commit(s) ainda não publicado(s). O próximo passo leria um documento ` +
-          'que só existe no seu clone — publique antes de continuar.'
+      // O passo publicou um documento em Pull Request? Então o próximo depende do
+      // merge, e encadear agora só produziria um bloqueio `pr-pending` uma volta
+      // depois — com uma mensagem menos direta e uma consulta à API a mais.
+      //
+      // Substitui o antigo guard de commits não publicados, que ficou
+      // permanentemente em zero: a publicação deixou de passar por git local.
+      const publicado = resultado?.pr || resultado?.published?.pr;
+      if (publicado?.number) {
+        console.log(chalk.yellow(
+          `\n⏸️  O documento foi publicado no PR #${publicado.number}` +
+          `${publicado.url ? ` (${publicado.url})` : ''}.\n` +
+          '   O próximo passo do fluxo lê esse documento da branch base — ' +
+          'revise e faça o merge para continuar.'
         ));
         break;
       }