@spec-wave/cli 0.26.0 → 0.28.0

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,203 @@ 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 };
+}
+
+/**
+ * Permissões de PR declaradas nos workflows instalados (I/O — nunca lança).
+ *
+ * O job MAIS RESTRITIVO manda: basta um sem a permissão para o fluxo quebrar.
+ *
+ * @param {string} dir diretório `.github/workflows`
+ * @returns {Record<string, {contents?: string, pullRequests?: string}>}
+ */
+export function readWorkflowPrPermissions(dir) {
+  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
+    }
+    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;
+      }
+    }
+  }
+  return workflowPerms;
+}
+
+/**
+ * Coleta o contexto que `inspectPrPublishing` julga (I/O — nunca lança).
+ *
+ * Separado do check para o `preflight` poder fazer a MESMA pergunta sem
+ * reimplementá-la: as três consultas têm cada uma o seu motivo para falhar sem
+ * que isso signifique "está errado", e duplicar esse tratamento em dois comandos
+ * é como as duas respostas passam a divergir.
+ *
+ * @param {{token?: string, owner?: string, repo?: string, root?: string}} params
+ * @returns {Promise<{canCreatePr: boolean|null, workflowPerms: object,
+ *                    requiredChecks: string[]|null, prTokenPresent: boolean|null}>}
+ */
+export async function readPrPublishingContext({ token, owner, repo, root }) {
+  const workflowPerms = readWorkflowPrPermissions(path.join(root || process.cwd(), '.github', 'workflows'));
+
+  let canCreatePr = null;
+  let requiredChecks = null;
+  let prTokenPresent = null;
+  if (token && owner && repo) {
+    const octokit = makeOctokit(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
+    }
+  }
+  return { canCreatePr, workflowPerms, requiredChecks, prTokenPresent };
+}
+
+async function checkPrPublishing(ctx) {
+  const name = 'Publicação por Pull Request';
+  const cfg = ctx.cfg || {};
+  const contexto = await readPrPublishingContext({
+    token: ctx.token, owner: cfg.owner, repo: cfg.repo, root: ctx.root || ctx.cwd,
+  });
+
+  if (Object.keys(contexto.workflowPerms).length === 0) {
+    return { name, status: 'warn', detail: 'Workflows não encontrados — rode `init` ou `update`.' };
+  }
+
+  const { status, notes } = inspectPrPublishing(contexto);
+  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 +1278,7 @@ export async function doctor() {
     checkDecompositions,
     checkSpecKit,
     checkWorkflows,
+    checkPrPublishing,
     checkExecutionMode,
   ];
   const results = [];

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: