@spec-wave/cli 0.26.0 → 0.27.0

package/src/commands/generate-bug.mjs

@@ -18,8 +18,9 @@ import { recordUsage } from '../lib/usage-report.mjs';
 import { loadPrompt, systemPromptWithTools } from '../lib/prompt-loader.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
 import { bugDocPaths } from '../lib/bug-doc.mjs';
-import { commitGenerated, resolveFlowContext } from '../lib/flow-run.mjs';
-import { docBlobUrl } from '../lib/repo-links.mjs';
+import { resolveFlowContext } from '../lib/flow-run.mjs';
+import { publishArtifact } from '../lib/artifact-publish.mjs';
+import { renderPrLine } from '../lib/artifact-pr.mjs';
 import {
   runCritique, resolveCritiqueAttempt, renderNeedsHumanComment,
 } from '../lib/critique.mjs';
@@ -77,7 +78,7 @@ export async function generateBug({ issueNumber }) {
     return;
   }
 
-  const { slug, dirRel, fileRel, fileAbs } = bugDocPaths(issue.title, root);
+  const { fileRel } = bugDocPaths(issue.title, root);
 
   const comments = await listIssueComments(token, owner, repo, n).catch(() => []);
   const report = buildReport(issue, comments);
@@ -111,16 +112,19 @@ export async function generateBug({ issueNumber }) {
     // ver lib/unwrap-doc.mjs. O que vai para o repositório é o documento.
     const content = unwrapGeneratedDoc(bruto);
 
-    // Publica pelo mesmo caminho do generate-spec/plan/decompose: commit
-    // escopado ao arquivo, identidade do bot só no runner e repetição quando
-    // outro run rouba a ponta da branch. O bloco de git solto que existia aqui
-    // não tinha nada disso — em particular, o `git commit` sem `-- <arquivo>`
-    // varria para dentro do commit qualquer coisa que estivesse no index.
-    const published = commitGenerated({
-      filePath: fileAbs,
+    // Publica pelo mesmo caminho do generate-spec/plan/decompose: branch própria
+    // do documento, commit único e Pull Request. O bloco de git solto que
+    // existia aqui commitava direto na branch default sem sequer escopar o
+    // commit ao arquivo — varria para dentro qualquer coisa no index.
+    const published = await publishArtifact({
+      token, owner, repo,
+      doc: 'bug',
+      issueNumber: n,
+      issueTitle: issue.title,
+      issueUrl: issue.html_url,
+      pathRel: fileRel,
       content,
-      message: `docs: generate bug.md for ${slug} [spec-wave]`,
-      mode,
+      nextLabel: 'spec-wave:ready',
     });
     if (published.warning) console.warn(`⚠️  ${published.warning}`);
 
@@ -136,14 +140,16 @@ export async function generateBug({ issueNumber }) {
     await commentOnIssue(
       token, owner, repo, n,
       '🐞 **bug.md gerado automaticamente!**\n\n' +
-      `📄 Arquivo: [\`${fileRel}\`](${docBlobUrl({ owner, repo, pathRel: fileRel, mode, root, config })})\n\n` +
-      'Revise a **causa raiz** e o **teste de regressão** — são as duas seções que decidem se ' +
-      'a correção ataca o defeito ou o sintoma. Quando estiver pronto, valide com:\n' +
+      `📄 Arquivo: [\`${fileRel}\`](${published.blobUrl})\n\n` +
+      `${renderPrLine(published)}\n\n` +
+      'Revise a **causa raiz** e o **teste de regressão** no Pull Request — são as duas seções ' +
+      'que decidem se a correção ataca o defeito ou o sintoma. Depois do merge, valide com:\n' +
       `\`\`\`\ngh issue edit ${n} --add-label "spec-wave:ready"\n\`\`\`` +
       (critique?.blocked ? '\n\n⛔ A crítica adversarial encontrou problemas graves (acima).' : '')
     );
 
-    console.log(`bug.md criado em: ${fileRel} (dir: ${dirRel})`);
+    console.log(`bug.md publicado em ${published.branch} (${fileRel}).`);
+    return { pr: published.pr, branch: published.branch };
   } catch (err) {
     // Mesmo motivo do generate-spec: sem remover a label, re-aplicá-la não
     // emite evento e a issue vira beco sem saída.

package/src/commands/generate-plan.mjs

@@ -2,13 +2,13 @@ import path from 'node:path';
 import { readFileSync, existsSync } from 'node:fs';
 import { resolveToken } from '../api/auth.mjs';
 import {
-  getIssue, removeLabel, addLabel, commentOnIssue, listIssueComments,
+  getIssue, removeLabel, addLabel, commentOnIssue, listIssueComments, getRepoDefaultBranch,
 } from '../api/github-rest.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
 import {
   allowsSpecPlan, SPEC_PLAN_EXCLUDED_TYPES, TARGET_LANGUAGE,
   LABEL_CRITIQUE, LABEL_CRITIQUE_FAILED, LABEL_NEEDS_HUMAN, LABEL_RISK_ACCEPTED,
-  DEFAULT_MAX_CRITIQUE_ATTEMPTS, labelNames,
+  LABEL_SPEC, DEFAULT_MAX_CRITIQUE_ATTEMPTS, labelNames,
 } from '../config.mjs';
 import { generateDocument } from '../lib/claude.mjs';
 import { unwrapGeneratedDoc } from '../lib/unwrap-doc.mjs';
@@ -18,9 +18,11 @@ import {
 } from '../lib/critique.mjs';
 import { recordUsage } from '../lib/usage-report.mjs';
 import { slugify } from '../lib/slugify.mjs';
-import { resolveFromRoot } from '../lib/project-root.mjs';
-import { resolveFlowContext, commitGenerated } from '../lib/flow-run.mjs';
-import { docBlobUrl } from '../lib/repo-links.mjs';
+import { resolveFlowContext } from '../lib/flow-run.mjs';
+import { publishArtifact } from '../lib/artifact-publish.mjs';
+import { loadArtifact } from '../lib/doc-source.mjs';
+import { awaitingMergeBlock, renderPrLine } from '../lib/artifact-pr.mjs';
+import { isAwaitingMerge } from '../lib/doc-source.mjs';
 import { buildTechContext } from '../lib/tech-context.mjs';
 import { loadPrompt, systemPromptWithTools } from '../lib/prompt-loader.mjs';
 
@@ -155,13 +157,39 @@ export async function generatePlan({ issueNumber }) {
   // Caminho RELATIVO para links/commit; ABSOLUTO ancorado na raiz para o fs — o
   // config é procurado subindo na árvore, e os documentos moram junto dele.
   const featureRel = `docs/features/${slug}`;
-  const featureDir = resolveFromRoot(root, featureRel);
-  const filePath = path.join(featureDir, 'plan.md');
   const fileRel = `${featureRel}/plan.md`;
 
-  // Read existing spec.md if available (spec é gerada antes do plano)
-  const specPath = path.join(featureDir, 'spec.md');
-  const specContent = existsSync(specPath) ? readFileSync(specPath, 'utf-8') : null;
+  // A spec é a ENTRADA do plano, e agora ela pode estar em três lugares: no
+  // clone, na branch base, ou num Pull Request que ninguém mergeou ainda.
+  const specRel = `${featureRel}/spec.md`;
+  const base = await getRepoDefaultBranch(token, owner, repo).catch(() => null);
+  const spec = await loadArtifact({
+    token, owner, repo, root, pathRel: specRel, doc: 'spec',
+    issueNumber: parseInt(issueNumber, 10), base,
+  });
+
+  // Portão duro. Este comando TOLERAVA a spec ausente e seguia com um
+  // placeholder no payload — o que, com a publicação por Pull Request, viraria o
+  // modo de falha caro: PR da spec aberto, plano gerado sobre o vazio, nenhum
+  // erro. Degradar em silêncio custa uma chamada de IA e produz um documento que
+  // parece bom. Recusar custa uma label.
+  if (isAwaitingMerge(spec.state) || spec.content == null) {
+    const n = parseInt(issueNumber, 10);
+    const motivo = isAwaitingMerge(spec.state)
+      ? awaitingMergeBlock({ pathRel: specRel, state: spec.state, pr: spec.pr, branch: spec.ref })
+      : {
+          message: `\`${specRel}\` não existe — o plano depende da spec.`,
+          unblock: `Aplique \`${LABEL_SPEC}\` para gerar a spec primeiro.`,
+        };
+    await removeLabel(token, owner, repo, n, 'spec-wave:plan').catch(() => {});
+    await commentOnIssue(token, owner, repo, n,
+      `⏸️ **plan.md não gerado:** ${motivo.message}\n\n${motivo.unblock}\n\n` +
+      'Gerar o plano sem a spec produziria um documento plausível e errado, ' +
+      'com a chamada de IA já paga.'
+    ).catch(() => {});
+    throw new Error(motivo.message);
+  }
+  const specContent = spec.content;
 
   // Tech context (RFC-002 §4): estático + dinâmico + override do corpo da issue.
   const tech = buildTechContext({ issueBody: issue.body || '' });
@@ -199,11 +227,16 @@ export async function generatePlan({ issueNumber }) {
     // ver lib/unwrap-doc.mjs. O que vai para o repositório é o documento.
     const content = unwrapGeneratedDoc(bruto);
 
-    const published = commitGenerated({
-      filePath,
+    const published = await publishArtifact({
+      token, owner, repo,
+      doc: 'plan',
+      issueNumber: parseInt(issueNumber, 10),
+      issueTitle: issue.title,
+      issueUrl: issue.html_url,
+      pathRel: fileRel,
       content,
-      message: `docs: generate plan.md for ${slug} [spec-wave]`,
-      mode,
+      base,
+      nextLabel: 'spec-wave:ready',
     });
     if (published.warning) console.warn(`⚠️  ${published.warning}`);
 
@@ -214,8 +247,9 @@ export async function generatePlan({ issueNumber }) {
     await commentOnIssue(
       token, owner, repo, parseInt(issueNumber, 10),
       `📋 **plan.md gerado automaticamente!**\n\n` +
-      `📄 Arquivo: [\`${fileRel}\`](${docBlobUrl({ owner, repo, pathRel: fileRel, mode, root, config })})\n\n` +
-      `Revise o plano e, quando estiver pronto, valide a Feature: mova o card para **✅ Ready** ou use:\n` +
+      `📄 Arquivo: [\`${fileRel}\`](${published.blobUrl})\n\n` +
+      `${renderPrLine(published)}\n\n` +
+      `Revise o plano **no Pull Request** e faça o merge. Depois, valide a Feature: mova o card para **✅ Ready** ou use:\n` +
       `\`\`\`\ngh issue edit ${issueNumber} --add-label "spec-wave:ready"\n\`\`\`` +
       formatLintWarning(lintFindings)
     );
@@ -229,7 +263,8 @@ export async function generatePlan({ issueNumber }) {
       labels: issueLabels, config, usage: usageEntries,
     });
 
-    console.log(`plan.md criado em: ${fileRel}`);
+    console.log(`plan.md publicado em ${published.branch} (${fileRel}).`);
+    return { pr: published.pr, branch: published.branch };
   } catch (err) {
     // Mesmo beco sem saída do generate-spec: o gatilho é `issues: [labeled]`,
     // então com a label ainda aplicada re-adicioná-la não dispara nada. Remove
@@ -361,9 +396,20 @@ export async function critique({ issueNumber, file, kind, failOnGrave = false })
     return;
   }
 
-  const featureDir = resolveFromRoot(root, `docs/features/${slugify(issue.title)}`);
-  const planPath = path.join(featureDir, 'plan.md');
-  if (!existsSync(planPath)) {
+  const featureRel = `docs/features/${slugify(issue.title)}`;
+  const planRel = `${featureRel}/plan.md`;
+  const specRel = `${featureRel}/spec.md`;
+  const base = await getRepoDefaultBranch(token, owner, repo).catch(() => null);
+  const ler = (doc, pathRel) => loadArtifact({
+    token, owner, repo, root, pathRel, doc, issueNumber: n, base,
+  });
+
+  // Este é o caminho de RECUPERAÇÃO do `critique-failed`: o revisor corrige o
+  // plano e pede outra crítica. Com a publicação por Pull Request, o plano que
+  // ele acabou de corrigir está na branch do PR — ler só o disco responderia
+  // "nada a criticar" e removeria o gatilho, fechando a única saída do ciclo.
+  const plan = await ler('plan', planRel);
+  if (plan.content == null) {
     console.log('plan.md ainda não existe — gere o plano antes de criticá-lo.');
     await removeLabel(token, owner, repo, n, LABEL_CRITIQUE).catch(() => {});
     await commentOnIssue(token, owner, repo, n,
@@ -371,13 +417,16 @@ export async function critique({ issueNumber, file, kind, failOnGrave = false })
       'Aplique `spec-wave:plan` para gerá-lo.').catch(() => {});
     return;
   }
-  const specPath = path.join(featureDir, 'spec.md');
+  if (plan.state === 'pending-pr') {
+    console.log(`Criticando o plan.md do PR #${plan.pr?.number} (ainda não mergeado).`);
+  }
+  const spec = await ler('spec', specRel);
 
   const issueLabels = labelNames(issue.labels || []);
   await critiquePlan({
     token, owner, repo, issueNumber: n,
-    spec: existsSync(specPath) ? readFileSync(specPath, 'utf-8') : null,
-    plan: readFileSync(planPath, 'utf-8'),
+    spec: spec.content,
+    plan: plan.content,
     techContextYaml: buildTechContext({ issueBody: issue.body || '' }).yaml,
     labels: issueLabels, config, usage: [],
   });

package/src/commands/generate-spec.mjs

@@ -1,13 +1,12 @@
-import path from 'node:path';
 import { resolveToken } from '../api/auth.mjs';
 import { getIssue, removeLabel, commentOnIssue } from '../api/github-rest.mjs';
 import { generateDocument } from '../lib/claude.mjs';
 import { unwrapGeneratedDoc } from '../lib/unwrap-doc.mjs';
 import { recordUsage } from '../lib/usage-report.mjs';
 import { slugify } from '../lib/slugify.mjs';
-import { resolveFromRoot } from '../lib/project-root.mjs';
-import { resolveFlowContext, commitGenerated } from '../lib/flow-run.mjs';
-import { docBlobUrl } from '../lib/repo-links.mjs';
+import { resolveFlowContext } from '../lib/flow-run.mjs';
+import { publishArtifact } from '../lib/artifact-publish.mjs';
+import { renderPrLine } from '../lib/artifact-pr.mjs';
 import { loadPrompt, systemPromptWithTools } from '../lib/prompt-loader.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
 import {
@@ -56,11 +55,9 @@ export async function generateSpec({ issueNumber }) {
   }
 
   const slug = slugify(issue.title);
-  // Caminho RELATIVO para links/commit; ABSOLUTO ancorado na raiz para o fs — o
-  // config é procurado subindo na árvore, e os documentos moram junto dele.
+  // Só o caminho RELATIVO: a publicação é via API, e nada é gravado no working
+  // tree — ver o cabeçalho de lib/artifact-publish.mjs.
   const featureRel = `docs/features/${slug}`;
-  const featureDir = resolveFromRoot(root, featureRel);
-  const filePath = path.join(featureDir, 'spec.md');
   const fileRel = `${featureRel}/spec.md`;
 
   // Payload estruturado (RFC-002 §5.1): metadata + entrada de negócio.
@@ -96,11 +93,15 @@ export async function generateSpec({ issueNumber }) {
     // ver lib/unwrap-doc.mjs. O que vai para o repositório é o documento.
     const content = unwrapGeneratedDoc(bruto);
 
-    const published = commitGenerated({
-      filePath,
+    const published = await publishArtifact({
+      token, owner, repo,
+      doc: 'spec',
+      issueNumber: parseInt(issueNumber, 10),
+      issueTitle: issue.title,
+      issueUrl: issue.html_url,
+      pathRel: fileRel,
       content,
-      message: `docs: generate spec.md for ${slug} [spec-wave]`,
-      mode,
+      nextLabel: 'spec-wave:plan',
     });
     if (published.warning) console.warn(`⚠️  ${published.warning}`);
 
@@ -111,13 +112,16 @@ export async function generateSpec({ issueNumber }) {
     await commentOnIssue(
       token, owner, repo, parseInt(issueNumber, 10),
       `📋 **spec.md gerado automaticamente!**\n\n` +
-      `📄 Arquivo: [\`${fileRel}\`](${docBlobUrl({ owner, repo, pathRel: fileRel, mode, root })})\n\n` +
-      `Revise a especificação e, quando estiver pronto, gere o plano técnico: mova o card para **📋 Plan** ou use:\n` +
+      `📄 Arquivo: [\`${fileRel}\`](${published.blobUrl})\n\n` +
+      `${renderPrLine(published)}\n\n` +
+      `Revise a especificação **no Pull Request** e faça o merge. Depois, gere o plano técnico: mova o card para **📋 Plan** ou use:\n` +
       `\`\`\`\ngh issue edit ${issueNumber} --add-label "spec-wave:plan"\n\`\`\`` +
       formatLintWarning(lintFindings)
     );
 
-    console.log(`spec.md criado em: ${fileRel}`);
+    console.log(`spec.md publicado em ${published.branch} (${fileRel}).`);
+    // Devolvido para o `run` saber que o próximo passo depende de um merge.
+    return { pr: published.pr, branch: published.branch };
   } catch (err) {
     // Sem isto a label de gatilho fica aplicada — e como o workflow dispara em
     // `issues: [labeled]`, re-adicionar uma label já presente não emite evento:

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');
@@ -463,12 +490,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 +650,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 +860,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/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;
       }