@spec-wave/cli 0.26.0 → 0.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spec-wave/cli",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "Setup spec-driven GitHub workflow with Projects v2, labels, issue templates, and AI-powered Actions",
   "type": "module",
   "bin": {

package/src/api/github-rest.mjs

@@ -311,6 +311,31 @@ export async function deleteLabel(token, owner, repo, name) {
   }
 }
 
+/**
+ * Apaga a ref de uma branch.
+ *
+ * Existe para UM caso, e só ele: a branch de artefato que sobrou de um PR
+ * mergeado com squash. Nesse merge a ponta da branch não é ancestral da base, e
+ * empilhar o próximo commit nela produziria um PR que reintroduz estado antigo.
+ * Sem PR aberto e sem commits à frente da base, a branch não guarda nada — pode
+ * ser recriada a partir da base.
+ *
+ * NUNCA use isto para resolver conflito: apagar uma branch com PR aberto
+ * descartaria revisão humana.
+ *
+ * @returns {Promise<boolean>} false quando a branch já não existia
+ */
+export async function deleteBranch(token, owner, repo, branch) {
+  const octokit = makeQuietOctokit(token); // 404 = já não existe, não é erro
+  try {
+    await octokit.rest.git.deleteRef({ owner, repo, ref: `heads/${branch}` });
+    return true;
+  } catch (err) {
+    if (err.status === 404 || err.status === 422) return false;
+    throw err;
+  }
+}
+
 export async function deleteFile(token, owner, repo, filePath, message) {
   const octokit = makeOctokit(token);
   let sha;

package/src/commands/decompose.mjs

@@ -17,11 +17,10 @@
 // edições humanas. Para regerar do zero, apague o arquivo.
 
 import { execSync } from 'node:child_process';
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
-import path from 'node:path';
 import { resolveToken } from '../api/auth.mjs';
 import {
   getIssue, createIssue, removeLabel, addLabel, commentOnIssue, addBlockedBy, listIssueComments,
+  getRepoDefaultBranch,
 } from '../api/github-rest.mjs';
 import { addSubIssue, listSubIssues, getProjectSnapshot } from '../api/github-graphql.mjs';
 import { loadProjectConfig, resolveField, advanceToStage } from '../lib/board.mjs';
@@ -37,7 +36,11 @@ import { resolveDocDir } from '../lib/doc-paths.mjs';
 import { docBlobUrl } from '../lib/repo-links.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
 import { loadConfig } from '../lib/project-root.mjs';
-import { resolveFlowContext, commitGenerated } from '../lib/flow-run.mjs';
+import { resolveFlowContext } from '../lib/flow-run.mjs';
+import { publishArtifact } from '../lib/artifact-publish.mjs';
+import { loadArtifact } from '../lib/doc-source.mjs';
+import { awaitingMergeBlock } from '../lib/artifact-pr.mjs';
+import { isAwaitingMerge } from '../lib/doc-source.mjs';
 import { loadPrompt, systemPromptWithTools } from '../lib/prompt-loader.mjs';
 import {
   renderDecompositionDoc, parseDecompositionDoc, DECOMPOSITION_FILE,
@@ -246,11 +249,26 @@ function formatItemsLintWarning(texts) {
   return `\n\n⚠️ possíveis artefatos de idioma nos itens gerados: ${excerpts}`;
 }
 
-// Grava e commita o rascunho. O modo (actions|local) decide identidade do git e
-// o que fazer com falha de push — ver `lib/flow-run.mjs`.
-function commitFile(filePath, content, message, mode) {
-  const published = commitGenerated({ filePath, content, message, mode });
+/**
+ * Publica o documento em branch própria + Pull Request — ver lib/artifact-publish.mjs.
+ *
+ * ASSÍNCRONA, e todo chamador precisa de `await`. O `apply` chama isto dentro de
+ * um `try/catch` cuja única função é degradar a falha em aviso (as issues já
+ * existem; derrubar o run aqui mandaria o humano reaplicar o gatilho e duplicar
+ * dezenas de itens). Sem o `await`, a promise rejeitada não é capturada por esse
+ * catch: o aviso some e vira unhandled rejection.
+ */
+async function publishFile(ctx, { doc, pathRel, content, nextLabel = null }) {
+  const { token, owner, repo, issue, issueNumber, base } = ctx;
+  const published = await publishArtifact({
+    token, owner, repo, doc,
+    issueNumber: parseInt(issueNumber, 10),
+    issueTitle: issue?.title || '',
+    issueUrl: issue?.html_url || '',
+    pathRel, content, base, nextLabel,
+  });
   if (published.warning) console.warn(`⚠️  ${published.warning}`);
+  return published;
 }
 
 // Os prompts vivem em `src/plugin/skills/decompose/model-prompt.{feature,rfc}.md`
@@ -263,23 +281,67 @@ function commitFile(filePath, content, message, mode) {
 // ---------------------------------------------------------------------------
 
 async function draftDecomposition(ctx) {
-  const { token, owner, repo, issue, issueNumber, type, labels, usage, root, runMode, docDir, docPath, docRel } = ctx;
+  const {
+    token, owner, repo, issue, issueNumber, type, labels, usage, root, runMode,
+    docRel, dirRel, base,
+  } = ctx;
   const number = parseInt(issueNumber, 10);
   const kind = DECOMPOSE_TARGETS[type]; // Feature → 'stories'; RFC → 'tasks'
-  const blobUrl = docBlobUrl({ owner, repo, pathRel: docRel, mode: runMode, root });
 
-  const specPath = path.join(docDir, 'spec.md');
-  const planPath = path.join(docDir, 'plan.md');
-  const specContent = existsSync(specPath) ? readFileSync(specPath, 'utf-8') : null;
-  const planContent = existsSync(planPath) ? readFileSync(planPath, 'utf-8') : null;
+  const ler = (doc, pathRel) => loadArtifact({
+    token, owner, repo, root, pathRel, doc, issueNumber: number, base,
+  });
+
+  // spec e plan alimentam o rascunho de Feature. Um deles preso num PR não
+  // mergeado com leitura ingênua viraria "(spec.md não encontrado)" no payload:
+  // rascunho gerado sobre o vazio, sem erro nenhum. Recusar é mais barato.
+  const spec = type === 'RFC' ? null : await ler('spec', `${dirRel}/spec.md`);
+  const plan = type === 'RFC' ? null : await ler('plan', `${dirRel}/plan.md`);
+  for (const [nome, doc] of [['spec.md', spec], ['plan.md', plan]]) {
+    if (doc && isAwaitingMerge(doc.state)) {
+      const bloqueio = awaitingMergeBlock({
+        pathRel: `${dirRel}/${nome}`, state: doc.state, pr: doc.pr, branch: doc.ref,
+      });
+      await removeLabel(token, owner, repo, number, LABEL_DECOMPOSE).catch(() => {});
+      await commentOnIssue(token, owner, repo, number,
+        `⏸️ **decompose parado:** ${bloqueio.message}\n\n${bloqueio.unblock}\n\n` +
+        `Reaplique \`${LABEL_DECOMPOSE}\` depois do merge.`
+      ).catch(() => {});
+      throw new DecomposeBlockedError(bloqueio.message);
+    }
+  }
+  const specContent = spec?.content ?? null;
+  const planContent = plan?.content ?? null;
 
   // Rascunho existente é preservado COMO ESTÁ: o humano corrige o arquivo e
   // re-aplica a label para uma nova crítica. Regenerar aqui apagaria a correção
   // — é justamente o que fazia o ciclo não convergir.
+  //
+  // Com a publicação por Pull Request, "existente" deixou de ser `existsSync`: o
+  // rascunho que o revisor está editando mora na branch do PR. Ler só o disco
+  // aqui INVERTERIA a invariante — regeneraria por cima da revisão, e ainda
+  // pagaria a IA de novo.
+  const rascunho = await ler('decomposition', docRel);
+
   let markdown;
-  if (existsSync(docPath)) {
-    console.log(`Rascunho encontrado em ${docRel} — criticando o arquivo como está (sem regerar).`);
-    markdown = readFileSync(docPath, 'utf-8');
+  let publicado = null;
+  if (rascunho.content != null) {
+    const onde = rascunho.state === 'pending-pr'
+      ? `no PR #${rascunho.pr?.number} (ainda não mergeado)`
+      : rascunho.state === 'branch-only'
+        ? `na branch ${rascunho.ref} (sem PR aberto)`
+        : docRel;
+    console.log(`Rascunho encontrado ${onde} — criticando o arquivo como está (sem regerar).`);
+    markdown = rascunho.content;
+    // O PR que já existe é o mesmo lugar onde o revisor vai corrigir: o
+    // comentário de fecho precisa apontá-lo, senão a re-crítica sai sem link e a
+    // pessoa fica procurando onde editar.
+    if (isAwaitingMerge(rascunho.state)) {
+      // `branch-only` entra aqui de propósito: republicar reaproveita a branch e
+      // TENTA abrir o PR de novo — é o caminho de recuperação quando a abertura
+      // falhou antes. O conteúdo é o do revisor, não um regerado.
+      publicado = { pr: rascunho.pr, branch: rascunho.ref, unchanged: true };
+    }
   } else {
     console.log(`Gerando rascunho de decomposição para ${type}: ${issue.title}`);
     const userContent = type === 'RFC'
@@ -312,10 +374,22 @@ async function draftDecomposition(ctx) {
       stories: generated.stories || [],
       tasks: generated.tasks || [],
     });
-    commitFile(docPath, markdown, `docs: rascunho de decomposição de ${docRel} [spec-wave]`, runMode);
-    console.log(`Rascunho commitado em ${docRel}.`);
+    publicado = await publishFile(ctx, {
+      doc: 'decomposition', pathRel: docRel, content: markdown,
+      nextLabel: LABEL_DECOMPOSE_APPLY,
+    });
+    console.log(`Rascunho publicado em ${publicado.branch} (${docRel}).`);
   }
 
+  // O link só pode ser montado DEPOIS de saber onde o documento está: na branch
+  // do PR recém-aberto, na do PR que já existia, ou na base. Inferir a ref pelo
+  // ambiente (o que o docBlobUrl faz por padrão) daria a branch default num
+  // evento `issues: labeled` — e lá o arquivo ainda não está.
+  const refDoDocumento = publicado?.branch || rascunho.ref || undefined;
+  const blobUrl = docBlobUrl({
+    owner, repo, pathRel: docRel, mode: runMode, root, ref: refDoDocumento,
+  });
+
   // Valida a estrutura ANTES de gastar tokens com a crítica: um arquivo quebrado
   // por edição humana precisa de mensagem clara, não de uma crítica sobre nada.
   let doc;
@@ -338,7 +412,7 @@ async function draftDecomposition(ctx) {
 
   // O RFC não tem spec/plan para auditar contra — a crítica não teria referência.
   if (kind !== 'stories') {
-    await finishDraft(ctx, { doc, blobUrl, itemCount, critiqued: false });
+    return await finishDraft(ctx, { doc, blobUrl, itemCount, critiqued: false, publicado });
     return;
   }
 
@@ -422,26 +496,41 @@ async function draftDecomposition(ctx) {
   // Crítica limpa: remove o bloqueio anterior, que também zera o contador de
   // tentativas na próxima rodada (ver resolveCritiqueAttempt).
   await removeLabel(token, owner, repo, number, LABEL_CRITIQUE_FAILED).catch(() => {});
-  await finishDraft(ctx, { doc, blobUrl, itemCount, critiqued: true });
+  return await finishDraft(ctx, { doc, blobUrl, itemCount, critiqued: true, publicado });
 }
 
 // Fecho comum do rascunho aprovado: libera para revisão humana e o apply.
-async function finishDraft({ token, owner, repo, issueNumber, docRel }, { blobUrl, itemCount, critiqued }) {
+async function finishDraft(
+  { token, owner, repo, issueNumber, docRel }, { blobUrl, itemCount, critiqued, publicado }
+) {
   const number = parseInt(issueNumber, 10);
   await addLabel(token, owner, repo, number, LABEL_DECOMPOSE_READY);
   await removeLabel(token, owner, repo, number, LABEL_DECOMPOSE);
+
+  // O apply LÊ o rascunho da branch base, então ele só roda depois do merge —
+  // dizer "crie as issues agora" sem essa ressalva manda o humano num passo que
+  // vai ser recusado.
+  const pr = publicado?.pr;
+  const revisao = pr?.number
+    ? `🔀 Pull Request: #${pr.number} — ${pr.url}\n\n` +
+      '**Nada foi criado ainda.** Revise (e edite, se quiser) o arquivo **no PR**, ' +
+      'faça o merge e então crie as issues:\n'
+    : '**Nada foi criado ainda.** Revise (e edite, se quiser) o arquivo e então crie as issues:\n';
+
   await commentOnIssue(token, owner, repo, number,
     `📝 **Rascunho de decomposição pronto para revisão** (${itemCount}).\n\n` +
     `📄 Arquivo: [\`${docRel}\`](${blobUrl})\n\n` +
     (critiqued
       ? 'A crítica adversarial não encontrou contradições graves. '
       : '') +
-    `**Nada foi criado ainda.** Revise (e edite, se quiser) o arquivo e então crie as issues:\n` +
+    revisao +
     `\`\`\`\ngh issue edit ${issueNumber} --add-label "${LABEL_DECOMPOSE_APPLY}"\n\`\`\`\n` +
     `Se preferir uma nova crítica depois de editar, reaplique \`${LABEL_DECOMPOSE}\` — ` +
-    'o arquivo é criticado como está, sem ser regerado. Para gerar outro do zero, apague-o.'
+    'o arquivo é criticado como está, sem ser regerado. Para gerar outro do zero, ' +
+    'feche o PR e apague a branch.'
   ).catch(err => console.warn(`Falha ao comentar o rascunho: ${err.message}`));
   console.log(`Rascunho liberado para revisão: ${itemCount}.`);
+  return { pr: pr || null };
 }
 
 // ---------------------------------------------------------------------------
@@ -449,14 +538,38 @@ async function finishDraft({ token, owner, repo, issueNumber, docRel }, { blobUr
 // ---------------------------------------------------------------------------
 
 async function applyDecomposition(ctx) {
-  const { token, owner, repo, issueNumber, docPath, docRel } = ctx;
+  const { token, owner, repo, issueNumber, docRel, root, base } = ctx;
   const number = parseInt(issueNumber, 10);
 
-  if (!existsSync(docPath)) {
+  const rascunho = await loadArtifact({
+    token, owner, repo, root, pathRel: docRel,
+    doc: 'decomposition', issueNumber: number, base,
+  });
+
+  // Rascunho ainda em Pull Request é recusa DURA, não aviso: aplicar criaria
+  // dezenas de issues a partir de um documento que ninguém aprovou, e o próprio
+  // arquivo passaria a afirmar `applied=<data>` enquanto o revisor ainda decide.
+  // O merge do PR É a aprovação humana.
+  // Vale para os DOIS estados fora da base. Cobrir só `pending-pr` deixaria o
+  // apply criar dezenas de issues a partir de um rascunho que está numa branch
+  // sem PR — ou seja, que ninguém teve como revisar.
+  if (isAwaitingMerge(rascunho.state)) {
+    const bloqueio = awaitingMergeBlock({
+      pathRel: docRel, state: rascunho.state, pr: rascunho.pr, branch: rascunho.ref,
+    });
+    await commentOnIssue(token, owner, repo, number,
+      `⏸️ **decompose-apply parado:** ${bloqueio.message}\n\n${bloqueio.unblock}\n\n` +
+      `Nenhuma issue foi criada. Reaplique \`${LABEL_DECOMPOSE_APPLY}\` depois do merge.`
+    ).catch(() => {});
+    await removeLabel(token, owner, repo, number, LABEL_DECOMPOSE_APPLY).catch(() => {});
+    throw new DecomposeBlockedError(bloqueio.message);
+  }
+
+  if (rascunho.content == null) {
     await commentOnIssue(token, owner, repo, number,
       `❌ **Não há rascunho de decomposição para aplicar.**\n\n` +
       `Esperava encontrar \`${docRel}\`. Gere o rascunho primeiro:\n` +
-      `\`\`\`\ngh issue edit ${issueNumber} --add-label "${LABEL_DECOMPOSE}"\n\`\`\``
+      `\`\`\`\ngh issue edit ${issueNumber} --add-label "${LABEL_DECOMPOSE}"\n\`\`\`\n`
     ).catch(() => {});
     await removeLabel(token, owner, repo, number, LABEL_DECOMPOSE_APPLY).catch(() => {});
     throw new DecomposeBlockedError(`${docRel} não encontrado — aplique ${LABEL_DECOMPOSE} primeiro.`);
@@ -464,7 +577,7 @@ async function applyDecomposition(ctx) {
 
   let doc;
   try {
-    doc = parseDecompositionDoc(readFileSync(docPath, 'utf-8'));
+    doc = parseDecompositionDoc(rascunho.content);
   } catch (err) {
     await commentOnIssue(token, owner, repo, number,
       `❌ **Não consegui ler o rascunho da decomposição.**\n\n` +
@@ -508,14 +621,19 @@ async function applyDecomposition(ctx) {
   // Depois da criação de propósito: se este commit falhar, as issues já existem
   // e o pior caso é o comportamento anterior (arquivo sem anotação), avisado no
   // log. O contrário — anotar antes e falhar na criação — inventaria issues.
+  //
+  // Vai para uma branch PRÓPRIA (`spec-wave/<n>-decompose-apply`), nunca por cima
+  // da branch do rascunho: aquela já foi mergeada (é pré-condição do apply), e
+  // reabri-la produziria um PR reintroduzindo estado antigo.
   try {
-    commitFile(
-      docPath,
-      renderDecompositionDoc({ ...doc, appliedAt: new Date().toISOString() }),
-      `docs: registra as issues criadas em ${docRel} [spec-wave]`,
-      ctx.runMode,
-    );
-    console.log(`${docRel} anotado com as issues criadas.`);
+    const anotado = await publishFile(ctx, {
+      doc: 'decomposition-apply',
+      pathRel: docRel,
+      content: renderDecompositionDoc({ ...doc, appliedAt: new Date().toISOString() }),
+    });
+    console.log(anotado.pr?.number
+      ? `${docRel} anotado com as issues criadas — PR #${anotado.pr.number}.`
+      : `${docRel} anotado com as issues criadas em ${anotado.branch}.`);
   } catch (err) {
     console.warn(
       `⚠️  Issues criadas, mas ${docRel} não foi anotado (${err.message}). ` +
@@ -992,8 +1110,12 @@ export async function decompose({ issueNumber, apply }) {
 
   // Config do repo: raiz para os caminhos de documento e escalada da crítica.
   const { config, root } = loadConfig();
-  const { rel: docRel, dir: docDir } = resolveDocDir(root, issue, type);
-  const docPath = path.join(docDir, DECOMPOSITION_FILE);
+  const { rel: docRel } = resolveDocDir(root, issue, type);
+
+  // Branch base: é dela que os documentos são lidos quando não estão no clone, e
+  // é contra ela que o PR do rascunho é aberto. Best-effort — sem ela a leitura
+  // cai para o default da API, que é o mesmo lugar.
+  const base = await getRepoDefaultBranch(token, owner, repo).catch(() => null);
 
   // Comentários só são necessários no rascunho (contador de tentativas).
   let comments = [];
@@ -1010,7 +1132,9 @@ export async function decompose({ issueNumber, apply }) {
   const usageEntries = [];
   const ctx = {
     token, projectToken, owner, repo, issue, issueNumber, type, labels, comments,
-    root, runMode, docDir, docPath, docRel: `${docRel}/${DECOMPOSITION_FILE}`,
+    root, runMode, docRel: `${docRel}/${DECOMPOSITION_FILE}`,
+    dirRel: docRel,
+    base,
     // Números das issues já criadas por este run. Compartilhado por referência
     // com o applyCtx: o catch externo precisa saber se houve criação para não
     // aconselhar um retry que duplicaria itens.
@@ -1024,8 +1148,11 @@ export async function decompose({ issueNumber, apply }) {
   };
 
   try {
-    if (mode === 'apply') await applyDecomposition(ctx);
-    else await draftDecomposition(ctx);
+    // O desfecho volta ao chamador (o `run` usa o PR para parar a cadeia: o passo
+    // seguinte lê o documento da base, então depende do merge).
+    return mode === 'apply'
+      ? await applyDecomposition(ctx)
+      : await draftDecomposition(ctx);
   } catch (err) {
     // Paradas por decisão do fluxo já comentaram na issue; erros inesperados não.
     if (!err.blocked) {

package/src/commands/doctor.mjs

@@ -8,6 +8,7 @@ import path from 'node:path';
 import * as p from '@clack/prompts';
 import chalk from 'chalk';
 import { Octokit } from '@octokit/rest';
+import yaml from 'js-yaml';
 import {
   resolveToken, verifyTokenScopes, describeTokenSource, activeGhAccount,
   tokenMismatchWarning, parseActiveAccount,
@@ -15,7 +16,8 @@ import {
 import { getProjectSnapshot, listSubIssues } from '../api/github-graphql.mjs';
 import { getRepoVariable } from '../api/github-rest.mjs';
 import {
-  CONFIG_FILE, WORKFLOW_FILES, getProvider, DEFAULT_PROVIDER, AI_PROVIDERS, STATUS_OPTIONS,
+  CONFIG_FILE, WORKFLOW_FILES, ARTIFACT_WORKFLOW_FILES, getProvider, DEFAULT_PROVIDER,
+  AI_PROVIDERS, STATUS_OPTIONS,
   RETIRED_STAGES, ALL_LABELS, allLabelsFor, LABEL_NEEDS_HUMAN, MODEL_LABEL_PREFIX,
   DEFAULT_MAX_CRITIQUE_ATTEMPTS, STAGE_TRACKS, AI_ACTIONS, recommendedModelAliases,
   modelLabels,
@@ -903,10 +905,21 @@ async function checkDecompositions(ctx) {
     );
   }
 
+  // Esta checagem lê o DISCO de propósito: ela audita registro consolidado, e um
+  // rascunho ainda em Pull Request não é registro. A consequência a declarar é
+  // que rascunhos não mergeados ficam FORA da conferência de deriva — não é
+  // omissão, é o recorte; mas quem lê o relatório precisa saber.
+  const nota = 'Rascunhos ainda em Pull Request não entram nesta conferência — ' +
+    'só o que está na branch base é registro.';
+
   if (aplicados === 0) {
-    return { name, status: 'ok', detail: `${arquivos.length} rascunho(s) ainda não aplicado(s) — nada a conferir.` };
+    return {
+      name,
+      status: 'ok',
+      detail: `${arquivos.length} rascunho(s) ainda não aplicado(s) — nada a conferir. ${nota}`,
+    };
   }
-  return { name, status, detail: notes.join('\n') };
+  return { name, status, detail: [...notes, nota].join('\n') };
 }
 
 export function checkSpecKit(ctx) {
@@ -967,6 +980,179 @@ async function checkExecutionMode(ctx) {
   return { name, status, detail: [estado.summary, ...estado.notes, ...estado.fixes].join('\n') };
 }
 
+/**
+ * Veredito sobre a capacidade de publicar documentos por Pull Request (função PURA).
+ *
+ * Três coisas precisam ser verdade, e as três falham de formas diferentes:
+ *
+ *  • **Permissões no YAML.** Sem `pull-requests: write`, o commit é criado e o PR
+ *    não — o documento fica numa branch que ninguém vê. Sem `contents: write`, a
+ *    Git Data API responde 403 e nada é publicado.
+ *  • **O Actions pode abrir PR.** "Allow GitHub Actions to create and approve
+ *    pull requests" vem DESLIGADO em muitas organizações, e é a falha mais
+ *    provável deste fluxo. Warn e não fail: a consulta exige `administration:
+ *    read`, que o GITHUB_TOKEN não tem, então "não consegui ver" é comum e não
+ *    pode virar vermelho.
+ *  • **Status checks obrigatórios na branch default.** Este é FAIL, e o motivo é
+ *    contraintuitivo: PR aberto pelo GITHUB_TOKEN não dispara workflow nenhum,
+ *    logo o check obrigatório nunca sai de "expected" e NENHUM PR de documento
+ *    fica mergeável. O fluxo trava no primeiro passo, sem erro visível em lugar
+ *    nenhum — a issue simplesmente para.
+ *
+ * @param {object} params
+ * @param {boolean|null} [params.canCreatePr] null = não foi possível consultar
+ * @param {Record<string, {contents?: string, pullRequests?: string}>} [params.workflowPerms]
+ * @param {string[]|null} [params.requiredChecks] null = não foi possível consultar
+ * @param {boolean|null} [params.prTokenPresent] o secret alternativo existe no repo
+ * @param {string} [params.prTokenSecret] nome do secret alternativo
+ * @returns {{status: 'ok'|'warn'|'fail', notes: string[]}}
+ */
+export function inspectPrPublishing({
+  canCreatePr = null, workflowPerms = {}, requiredChecks = null,
+  prTokenPresent = null, prTokenSecret = 'GH_PR_TOKEN',
+} = {}) {
+  const notes = [];
+  let status = 'ok';
+  const piora = (novo) => {
+    if (novo === 'fail' || status === 'fail') status = 'fail';
+    else if (novo === 'warn') status = 'warn';
+  };
+
+  const semPr = Object.entries(workflowPerms)
+    .filter(([, perm]) => perm?.pullRequests !== 'write').map(([f]) => f);
+  const semContents = Object.entries(workflowPerms)
+    .filter(([, perm]) => perm?.contents !== 'write').map(([f]) => f);
+
+  if (semPr.length > 0) {
+    piora('fail');
+    notes.push(
+      `Sem \`pull-requests: write\`: ${semPr.join(', ')}. O commit é criado e o Pull ` +
+      'Request não — o documento fica numa branch que ninguém vê. Rode `update`.'
+    );
+  }
+  if (semContents.length > 0) {
+    piora('fail');
+    notes.push(
+      `Sem \`contents: write\`: ${semContents.join(', ')}. O commit vai por Git Data API, ` +
+      'que é autorizada por essa permissão. Rode `update`.'
+    );
+  }
+
+  if (canCreatePr === false && !prTokenPresent) {
+    piora('warn');
+    notes.push(
+      'O GitHub Actions está proibido de criar Pull Requests neste repositório. ' +
+      'Ligue Settings → Actions → General → "Allow GitHub Actions to create and approve ' +
+      `pull requests", ou defina o secret \`${prTokenSecret}\` com um PAT.`
+    );
+  } else if (canCreatePr === false) {
+    // Mitigado: o PR é aberto com o PAT, não com o GITHUB_TOKEN. Continuar
+    // pedindo a configuração que a pessoa ACABOU de fazer é o jeito mais rápido
+    // de ensinar que o doctor pode ser ignorado.
+    notes.push(
+      `O Actions não pode abrir PR com o GITHUB_TOKEN, mas \`${prTokenSecret}\` está ` +
+      'definido e é ele que será usado — só o NOME é verificável daqui, não o valor ' +
+      'nem as permissões.'
+    );
+  } else if (canCreatePr === null) {
+    notes.push(
+      'Não foi possível verificar se o Actions pode criar Pull Requests (a consulta ' +
+      'exige `administration: read`). Se a publicação falhar com 403, é aqui.'
+    );
+  }
+
+  if (requiredChecks?.length && !prTokenPresent) {
+    piora('fail');
+    notes.push(
+      `A branch default exige status check(s) obrigatório(s): ${requiredChecks.join(', ')}. ` +
+      'Pull Request aberto pelo GITHUB_TOKEN NÃO dispara workflow, então esses checks ' +
+      'nunca ficam verdes e nenhum PR de documento se torna mergeável — o fluxo trava no ' +
+      `primeiro passo. Use um PAT no secret \`${prTokenSecret}\` (PR aberto por PAT dispara ` +
+      'os workflows), ou dispense os checks para as branches `spec-wave/*`.'
+    );
+  } else if (requiredChecks?.length) {
+    notes.push(
+      `A branch default exige ${requiredChecks.join(', ')}; como o PR é aberto por ` +
+      `\`${prTokenSecret}\`, os workflows disparam e os checks podem ficar verdes.`
+    );
+  }
+
+  if (status === 'ok' && notes.length === 0) {
+    notes.push('Os workflows podem publicar documentos por Pull Request.');
+  }
+  return { status, notes };
+}
+
+async function checkPrPublishing(ctx) {
+  const name = 'Publicação por Pull Request';
+  const dir = path.join(ctx.root || ctx.cwd, '.github', 'workflows');
+
+  const workflowPerms = {};
+  for (const file of ARTIFACT_WORKFLOW_FILES) {
+    const caminho = path.join(dir, file);
+    if (!existsSync(caminho)) continue; // ausência já é reportada por checkWorkflows
+    let wf;
+    try {
+      wf = yaml.load(readFileSync(caminho, 'utf-8'));
+    } catch {
+      continue; // YAML ilegível é problema de outro check
+    }
+    // O job mais restritivo manda: basta um sem a permissão para o fluxo quebrar.
+    for (const job of Object.values(wf?.jobs || {})) {
+      const atual = workflowPerms[file];
+      const perm = {
+        contents: job?.permissions?.contents,
+        pullRequests: job?.permissions?.['pull-requests'],
+      };
+      if (!atual || perm.pullRequests !== 'write' || perm.contents !== 'write') {
+        workflowPerms[file] = perm;
+      }
+    }
+  }
+
+  if (Object.keys(workflowPerms).length === 0) {
+    return { name, status: 'warn', detail: 'Workflows não encontrados — rode `init` ou `update`.' };
+  }
+
+  const cfg = ctx.cfg || {};
+  const owner = cfg.owner;
+  const repo = cfg.repo;
+
+  let canCreatePr = null;
+  let requiredChecks = null;
+  let prTokenPresent = null;
+  if (ctx.token && owner && repo) {
+    const octokit = makeOctokit(ctx.token);
+    try {
+      const res = await octokit.request('GET /repos/{owner}/{repo}/actions/secrets',
+        { owner, repo });
+      prTokenPresent = (res.data.secrets || []).some(sec => sec.name === 'GH_PR_TOKEN');
+    } catch {
+      prTokenPresent = null; // sem permissão de ler secrets — não afirmar ausência
+    }
+    try {
+      const res = await octokit.request('GET /repos/{owner}/{repo}/actions/permissions/workflow',
+        { owner, repo });
+      canCreatePr = res.data?.can_approve_pull_request_reviews ?? null;
+    } catch {
+      canCreatePr = null; // exige administration:read — ausência é comum, não é erro
+    }
+    try {
+      const info = await octokit.rest.repos.get({ owner, repo });
+      const branch = info.data.default_branch;
+      const prot = await octokit.rest.repos.getBranchProtection({ owner, repo, branch });
+      requiredChecks = prot.data?.required_status_checks?.contexts || [];
+    } catch {
+      requiredChecks = null; // sem proteção (404) ou sem permissão — nos dois casos, não afirmar
+    }
+  }
+
+  const { status, notes } = inspectPrPublishing({
+    canCreatePr, workflowPerms, requiredChecks, prTokenPresent,
+  });
+  return { name, status, detail: notes.join('\n  ') };
+}
+
 async function checkWorkflows(ctx) {
   const name = 'Workflows do Actions';
   // Ancorado na raiz do projeto, não no cwd: rodar o doctor de um subdiretório
@@ -1068,6 +1254,7 @@ export async function doctor() {
     checkDecompositions,
     checkSpecKit,
     checkWorkflows,
+    checkPrPublishing,
     checkExecutionMode,
   ];
   const results = [];