@spec-wave/cli 0.14.0 → 0.16.0

package/src/commands/update.mjs

@@ -8,15 +8,21 @@ import { CONFIG_FILE, WORKFLOW_FILES, ISSUE_TEMPLATE_FILES, ALL_LABELS } from '.
 import { getProjectSnapshot } from '../api/github-graphql.mjs';
 import {
   getFileContent, upsertFile, listLabels, createLabel, updateLabel, deleteLabel,
+  getRepoDefaultBranch, compareBranches, commitFilesToBranch, ensurePullRequest,
 } from '../api/github-rest.mjs';
+import {
+  resolveBranchName, composePrTitle, composePrBody, buildCommitMessage,
+  decideConfigInPr, explainGitWriteError,
+} from '../lib/pr-branch.mjs';
 // MESMO readTemplate do init: resolve {{CLI_VERSION}} antes da comparação byte a
 // byte com o remoto. Se só o init resolvesse, todo update veria os workflows
 // como desatualizados para sempre.
 import { readTemplate } from '../lib/templates.mjs';
 import {
   TARGETS, SKILL_SOURCE, CLI_VERSION, parseSkill, renderContent,
-  mergeAgentsFile, resolveDest, isDetected, skillCopyReason,
+  mergeAgentsFile, resolveDest, isDetected, skillCopyReason, versionBanner,
 } from './install-skill.mjs';
+import { planPluginSkillFiles } from '../lib/plugin-skills.mjs';
 import { findConfigPath } from '../lib/project-root.mjs';
 
 // Arquivos do repo gerenciados pela CLI (comparados com o template empacotado).
@@ -34,15 +40,27 @@ function detectSkill(parsed, baseDir, isGlobal) {
     const dest = resolveDest(target, baseDir, isGlobal);
     if (!dest) continue;
     const reason = skillCopyReason(dest, parsed);
-    if (reason) {
-      jobs.push({ target, dest, desired: renderContent(dest.format, parsed, CLI_VERSION), reason });
+    if (!reason) continue;
+    // `skills-dir` (Codex) não tem um `desired` único: são N arquivos, um por
+    // skill do plugin. O plano é montado na hora de aplicar.
+    if (dest.format === 'skills-dir') {
+      jobs.push({ target, dest, reason });
+      continue;
     }
+    jobs.push({ target, dest, desired: renderContent(dest.format, parsed, CLI_VERSION), reason });
   }
   return jobs;
 }
 
 // Aplica a atualização de uma skill (grava o arquivo / faz merge no AGENTS.md).
 function applySkill(job) {
+  if (job.dest.format === 'skills-dir') {
+    for (const file of planPluginSkillFiles(job.dest.path, CLI_VERSION, versionBanner)) {
+      mkdirSync(path.dirname(file.path), { recursive: true });
+      writeFileSync(file.path, file.content, 'utf-8');
+    }
+    return;
+  }
   const content = job.dest.format === 'agents'
     ? mergeAgentsFile(job.dest.path, job.desired)
     : job.desired;
@@ -85,12 +103,102 @@ export function diffLabels(existing) {
   return { missing, changed, orphan };
 }
 
+/**
+ * Regenera o conteúdo do .spec-wave.json a partir do Project remoto SEM GRAVAR.
+ *
+ * A geração foi separada da gravação porque no modo --branch esse conteúdo pode
+ * precisar entrar na árvore do commit — e a árvore é montada antes de QUALQUER
+ * escrita, para que uma falha no caminho não deixe nada aplicado, nem local nem
+ * remoto.
+ *
+ * @returns {Promise<{ content: string|null, error: string|null }>}
+ */
+async function buildConfigContent(token, config) {
+  const snapshot = await getProjectSnapshot(token, config.project.id);
+  if (!snapshot) return { content: null, error: 'Project não encontrado' };
+  const { etapaFieldId: _e, stageOptions: _s, ...projectRest } = config.project;
+  const updated = {
+    ...config,
+    version: CLI_VERSION,
+    project: {
+      ...projectRest,
+      title: snapshot.title,
+      url: snapshot.url,
+      id: snapshot.id,
+      number: snapshot.number,
+      fields: snapshot.fields,
+    },
+    refreshedAt: new Date().toISOString(),
+  };
+  // MESMA serialização do init (2 espaços + \n final): este texto é comparado
+  // byte a byte com o remoto em decideConfigInPr, e um \n de diferença faria o
+  // config entrar no PR em toda execução.
+  return { content: `${JSON.stringify(updated, null, 2)}\n`, error: null };
+}
+
+/**
+ * Aplica o diff de labels direto na base.
+ *
+ * Label NUNCA entra num PR: é metadado do repositório, não arquivo versionado —
+ * não existe forma de propor a mudança para revisão.
+ *
+ * @returns {Promise<{created: string[], updated: string[], removed: string[]}>}
+ *          só o que REALMENTE passou — é o que o corpo do PR vai afirmar a quem
+ *          revisa, e ele não pode prometer o que falhou.
+ */
+async function applyLabels(token, owner, repo, labelDiff) {
+  const done = { created: [], updated: [], removed: [] };
+  for (const label of labelDiff.missing) {
+    try {
+      await createLabel(token, owner, repo, label);
+      done.created.push(label.name);
+      p.log.success(`Label criada: ${label.name}`);
+    } catch (err) {
+      p.log.error(`Falha ao criar label ${label.name}: ${err.message}`);
+    }
+  }
+  for (const label of labelDiff.changed) {
+    try {
+      await updateLabel(token, owner, repo, label);
+      done.updated.push(label.name);
+      p.log.success(`Label atualizada: ${label.name}`);
+    } catch (err) {
+      p.log.error(`Falha ao atualizar label ${label.name}: ${err.message}`);
+    }
+  }
+  for (const label of labelDiff.orphan) {
+    try {
+      await deleteLabel(token, owner, repo, label.name);
+      done.removed.push(label.name);
+      p.log.success(`Label descontinuada removida: ${label.name}`);
+    } catch (err) {
+      p.log.error(`Falha ao remover label ${label.name}: ${err.message}`);
+    }
+  }
+  return done;
+}
+
 export async function update(options = {}) {
   p.intro(chalk.bold(`spec-wave update (CLI v${CLI_VERSION})`));
 
   const isGlobal = !!options.global;
   const baseDir = isGlobal ? homedir() : process.cwd();
 
+  // --branch: valida o nome ANTES de qualquer rede. Descobrir um espaço no nome
+  // só no createRef, depois de meia dúzia de requisições, é o pior desperdício
+  // possível — e a mensagem crua da API não aponta a causa.
+  const prRequested = options.branch !== undefined && options.branch !== false;
+  let branch = null;
+  if (prRequested) {
+    const r = resolveBranchName(options.branch, { version: CLI_VERSION });
+    if (r.error) {
+      p.log.error(r.error);
+      p.cancel('Update cancelado.');
+      return;
+    }
+    branch = r.branch;
+  }
+
   // ---------- Detecção ----------
   // 1) Skill (por agente detectado).
   const parsed = parseSkill(readFileSync(SKILL_SOURCE, 'utf-8'));
@@ -99,9 +207,11 @@ export async function update(options = {}) {
   // 2) Config + repo dependem do .spec-wave.json local do repo atual.
   const configPath = findConfigPath();
   let config = null;
+  let rawConfig = null; // texto cru: comparado com o remoto em decideConfigInPr
   if (configPath) {
     try {
-      config = JSON.parse(readFileSync(configPath, 'utf-8'));
+      rawConfig = readFileSync(configPath, 'utf-8');
+      config = JSON.parse(rawConfig);
     } catch (err) {
       p.log.warn(`${CONFIG_FILE} corrompido (${err.message}); pulando config/repo.`);
     }
@@ -136,6 +246,8 @@ export async function update(options = {}) {
   }
 
   // 2b) Arquivos do repo e labels divergentes (exige token + rede).
+  const owner = config?.owner;
+  const repo = config?.repo;
   let repoFiles = [];
   let labelDiff = { missing: [], changed: [], orphan: [] };
   let repoChecked = false;
@@ -147,7 +259,6 @@ export async function update(options = {}) {
       s.stop('');
       p.log.warn(`Sem token do GitHub (${tokenError?.message ?? 'indisponível'}); pulando verificação do repo.`);
     } else {
-      const { owner, repo } = config;
       try {
         for (const f of REPO_FILES) {
           const remote = await getFileContent(tk, owner, repo, f.repoPath);
@@ -165,9 +276,67 @@ export async function update(options = {}) {
     }
   }
 
+  // 2c) Modo PR: base remota, estado do config na base e situação da branch.
+  // TUDO leitura — precisa acontecer aqui porque o resumo e o --dry-run já
+  // mostram a branch, a base e se o config vai no PR.
+  let prMode = prRequested && doRepo && repoChecked;
+  let base = null;
+  let remoteConfigRaw = null;
+  let branchExists = false;
+  if (prMode) {
+    const tk = await getToken();
+    try {
+      base = await getRepoDefaultBranch(tk, owner, repo);
+      if (branch === base) {
+        p.log.error(
+          `--branch "${branch}" é a própria branch default do repositório; ` +
+          'um Pull Request precisa de uma branch diferente da base.'
+        );
+        p.cancel('Update cancelado.');
+        return;
+      }
+      remoteConfigRaw = await getFileContent(tk, owner, repo, CONFIG_FILE, base);
+      const status = await compareBranches(tk, owner, repo, base, branch);
+      branchExists = status !== null;
+      if (status === 'behind' || status === 'identical') {
+        // Não fazemos force-push: só avisamos. Empilhar um commit numa branch já
+        // mergeada funciona, mas o diff do PR pode reexibir arquivos que já estão
+        // na base (caso do squash merge).
+        p.log.warn(
+          `A branch "${branch}" já existe e não tem nenhum commit além de "${base}" ` +
+          '(provavelmente de um PR já mergeado). O commit novo seria empilhado nela — ' +
+          'use `--branch <outro-nome>` para começar do zero.'
+        );
+      }
+    } catch (err) {
+      p.log.warn(
+        `Não foi possível preparar o modo PR: ${err.message} — ` +
+        'os arquivos seguiriam por commit direto.'
+      );
+      prMode = false;
+    }
+  }
+
+  // Decisão preliminar sobre o config. O conteúdo regenerado ainda não existe;
+  // `willRegenerate` cobre isso, porque o regenerado SEMPRE difere do remoto
+  // (refreshedAt muda a cada execução). Na aplicação a decisão é recalculada com
+  // o conteúdo real.
+  const configDecision = prMode && doConfig
+    ? decideConfigInPr({
+        remote: remoteConfigRaw,
+        desired: rawConfig,
+        willRegenerate: !!configStale?.canApply,
+        force: options.configInPr,
+      })
+    : { included: false, reason: '' };
+
   // ---------- Resumo ----------
   const labelTotal = labelDiff.missing.length + labelDiff.changed.length + labelDiff.orphan.length;
-  const total = skillJobs.length + (configStale ? 1 : 0) + repoFiles.length + labelTotal;
+  // Config em dia pela versão, mas divergente do que está na base: antes isso dava
+  // "tudo atualizado" e o repositório ficava com um config velho indefinidamente.
+  const configOnlyPr = configDecision.included && !configStale;
+  const total = skillJobs.length + (configStale ? 1 : 0) + repoFiles.length + labelTotal
+    + (configOnlyPr ? 1 : 0);
 
   if (total === 0) {
     p.log.success('Tudo já está atualizado para a versão atual da CLI.');
@@ -186,11 +355,22 @@ export async function update(options = {}) {
       (configStale.canApply ? '' : chalk.dim(' (sem project.id — rode `init` sem --skip-project)')));
   }
   if (repoFiles.length) {
-    lines.push(chalk.bold('Arquivos do repo:'));
+    lines.push(prMode
+      ? chalk.bold(`Arquivos do repo → Pull Request (${branch} → ${base}):`)
+      : chalk.bold('Arquivos do repo:'));
     for (const f of repoFiles) lines.push(`  ${chalk.yellow('↻')} ${f.repoPath} (${f.reason})`);
   }
+  if (prMode && configDecision.included) {
+    if (!repoFiles.length) lines.push(chalk.bold(`Pull Request (${branch} → ${base}):`));
+    lines.push(`  ${chalk.yellow('↻')} ${CONFIG_FILE} (${configDecision.reason})`);
+  }
+  if (prMode && doConfig && !configDecision.included && configDecision.reason) {
+    lines.push(chalk.dim(`  · ${CONFIG_FILE} fora do PR — ${configDecision.reason}`));
+  }
   if (labelTotal) {
-    lines.push(chalk.bold('Labels:'));
+    lines.push(prMode
+      ? chalk.bold(`Labels (direto em ${base} — metadado do repo, não versionável):`)
+      : chalk.bold('Labels:'));
     if (labelDiff.missing.length) lines.push(`  ${chalk.yellow('+')} criar: ${labelDiff.missing.map(l => l.name).join(', ')}`);
     if (labelDiff.changed.length) lines.push(`  ${chalk.yellow('↻')} atualizar: ${labelDiff.changed.map(l => l.name).join(', ')}`);
     if (labelDiff.orphan.length) {
@@ -199,13 +379,48 @@ export async function update(options = {}) {
   }
   p.note(lines.join('\n'), `${total} item(ns) desatualizado(s)`);
 
+  // --branch sem efeito: melhor dizer POR QUE do que criar uma branch inútil.
+  const prHasPayload = prMode && (repoFiles.length > 0 || configDecision.included);
+  if (prRequested && options.skipRepo) {
+    p.log.warn(
+      '--branch ignorado junto com --skip-repo: o Pull Request existe justamente para ' +
+      'levar os arquivos do repo.'
+    );
+  } else if (prRequested && !prMode) {
+    p.log.warn(
+      '--branch ignorado: sem token, sem owner/repo no .spec-wave.json ou a comparação com ' +
+      'o repositório falhou — não há como abrir o Pull Request.'
+    );
+  } else if (prMode && !prHasPayload) {
+    p.log.warn(
+      '--branch sem efeito: nenhum arquivo do repositório para enviar (as mudanças são ' +
+      'locais e/ou de labels). Nenhuma branch será criada.'
+    );
+  }
+
   if (options.dryRun) {
+    if (prHasPayload) {
+      const n = repoFiles.length + (configDecision.included ? 1 : 0);
+      p.note(
+        `Branch:    ${branch}${branchExists ? ' (já existe — o commit seria empilhado nela)' : ' (seria criada)'}\n` +
+        `Base:      ${base}\n` +
+        `Título:    ${composePrTitle({ version: CLI_VERSION })}\n` +
+        `Arquivos:  ${n} em 1 commit único\n\n` +
+        'Nada foi criado: nem branch, nem commit, nem Pull Request.',
+        'Dry-run: modo Pull Request'
+      );
+    }
     p.outro('Dry-run: nada foi alterado.');
     return;
   }
 
   if (!options.yes) {
-    const ok = await p.confirm({ message: `Aplicar as ${total} atualização(ões)?`, initialValue: true });
+    const ok = await p.confirm({
+      message: prHasPayload
+        ? `Aplicar as ${total} atualização(ões) e abrir um Pull Request em "${branch}"?`
+        : `Aplicar as ${total} atualização(ões)?`,
+      initialValue: true,
+    });
     if (p.isCancel(ok) || !ok) {
       p.cancel('Update cancelado.');
       return;
@@ -213,6 +428,14 @@ export async function update(options = {}) {
   }
 
   // ---------- Aplicação ----------
+  // Ordem: skill (local) → config GERADO em memória → labels (sempre direto) →
+  // arquivos do repo (PR ou commits diretos) → gravação local do config.
+  //
+  // As labels vêm ANTES dos arquivos porque o corpo do PR precisa dizer quais
+  // labels JÁ mudaram na base — é a única coisa que o update faz e o diff do PR
+  // não mostra. (Isso muda a ordem dos logs também no modo direto; os dois blocos
+  // são independentes.)
+
   // Skill
   for (const job of skillJobs) {
     try {
@@ -223,7 +446,8 @@ export async function update(options = {}) {
     }
   }
 
-  // Config (.spec-wave.json) — reconsulta o Project e reescreve local.
+  // Config (.spec-wave.json) — regenera o conteúdo, ainda sem tocar o disco.
+  let configContent = null;
   if (configStale) {
     if (!configStale.canApply) {
       p.log.warn(`${CONFIG_FILE}: sem project.id — pulei. Rode \`npx @spec-wave/cli@latest init\` (sem --skip-project).`);
@@ -233,83 +457,149 @@ export async function update(options = {}) {
         p.log.warn(`${CONFIG_FILE}: sem token — pulei. (${tokenError?.message ?? ''})`);
       } else {
         const s = p.spinner();
-        s.start('Atualizando .spec-wave.json...');
+        s.start('Consultando o Project para atualizar o .spec-wave.json...');
         try {
-          const snapshot = await getProjectSnapshot(tk, config.project.id);
-          if (!snapshot) throw new Error('Project não encontrado');
-          const { etapaFieldId: _e, stageOptions: _s, ...projectRest } = config.project;
-          const updated = {
-            ...config,
-            version: CLI_VERSION,
-            project: {
-              ...projectRest,
-              title: snapshot.title,
-              url: snapshot.url,
-              id: snapshot.id,
-              number: snapshot.number,
-              fields: snapshot.fields,
-            },
-            refreshedAt: new Date().toISOString(),
-          };
-          writeFileSync(configPath, JSON.stringify(updated, null, 2) + '\n');
-          s.stop(`${CONFIG_FILE} atualizado (v${CLI_VERSION}).`);
+          const { content, error } = await buildConfigContent(tk, config);
+          if (error) throw new Error(error);
+          configContent = content;
+          s.stop(`${CONFIG_FILE} regenerado (v${CLI_VERSION}).`);
         } catch (err) {
           s.stop('');
-          p.log.error(`Falha ao atualizar ${CONFIG_FILE}: ${err.message}`);
+          p.log.error(`Falha ao regerar ${CONFIG_FILE}: ${err.message}`);
         }
       }
     }
   }
 
-  // Arquivos do repo
-  if (repoFiles.length) {
-    const tk = await getToken();
-    const { owner, repo } = config;
-    for (const f of repoFiles) {
-      try {
-        await upsertFile(tk, owner, repo, f.repoPath, f.local, `chore: update ${path.basename(f.repoPath)} [spec-wave]`);
-        p.log.success(`Arquivo atualizado no repo: ${f.repoPath}`);
-      } catch (err) {
-        p.log.error(`Falha ao atualizar ${f.repoPath}: ${err.message}`);
-      }
+  // Recalcula a decisão com o conteúdo REAL (a preliminar usava willRegenerate).
+  const finalConfigDecision = prMode && doConfig
+    ? decideConfigInPr({
+        remote: remoteConfigRaw,
+        desired: configContent ?? rawConfig,
+        force: options.configInPr,
+      })
+    : { included: false, reason: '' };
+
+  // Gravação local do config, feita UMA vez só. No modo PR com o config a bordo
+  // ela é adiada para depois do commit remoto: assim uma falha no envio não deixa
+  // o arquivo local adiantado em relação ao repositório.
+  let configFlushed = false;
+  const flushConfig = () => {
+    if (configFlushed || !configContent) return;
+    try {
+      writeFileSync(configPath, configContent);
+      configFlushed = true;
+      p.log.success(`${CONFIG_FILE} atualizado localmente (v${CLI_VERSION}).`);
+    } catch (err) {
+      p.log.error(`Falha ao gravar ${CONFIG_FILE}: ${err.message}`);
     }
-  }
+  };
+  if (!finalConfigDecision.included) flushConfig();
 
-  // Labels
+  // Labels — sempre direto na base (metadado do repo, não versionável).
+  let labelResult = { created: [], updated: [], removed: [] };
   if (labelTotal) {
+    labelResult = await applyLabels(await getToken(), owner, repo, labelDiff);
+  }
+
+  // Arquivos do repo
+  let prUrl = null;
+  if (prMode) {
     const tk = await getToken();
-    const { owner, repo } = config;
-    for (const label of labelDiff.missing) {
+    const treeFiles = [
+      ...repoFiles.map(f => ({ path: f.repoPath, reason: f.reason, content: f.local })),
+      ...(finalConfigDecision.included
+        ? [{
+            path: CONFIG_FILE,
+            reason: finalConfigDecision.reason,
+            content: configContent ?? rawConfig,
+          }]
+        : []),
+    ];
+    if (!treeFiles.length) {
+      p.log.warn('Nada para enviar em um Pull Request: nenhum arquivo do repositório mudou.');
+    } else {
+      const s = p.spinner();
+      s.start(`Enviando ${treeFiles.length} arquivo(s) em um único commit para "${branch}"...`);
+      let commitOk = false;
       try {
-        await createLabel(tk, owner, repo, label);
-        p.log.success(`Label criada: ${label.name}`);
+        const res = await commitFilesToBranch(tk, owner, repo, {
+          branch,
+          base,
+          files: treeFiles.map(f => ({ path: f.path, content: f.content })),
+          message: buildCommitMessage({ version: CLI_VERSION, files: treeFiles }),
+        });
+        commitOk = true;
+        s.stop(res.unchanged
+          ? `"${branch}" já contém estas alterações — nenhum commit novo.`
+          : `Commit ${res.commitSha.slice(0, 7)} enviado para "${branch}" (${treeFiles.length} arquivo(s)).`);
       } catch (err) {
-        p.log.error(`Falha ao criar label ${label.name}: ${err.message}`);
+        s.stop('');
+        p.log.error(`Falha ao enviar os arquivos para "${branch}": ${explainGitWriteError(err)}`);
       }
-    }
-    for (const label of labelDiff.changed) {
-      try {
-        await updateLabel(tk, owner, repo, label);
-        p.log.success(`Label atualizada: ${label.name}`);
-      } catch (err) {
-        p.log.error(`Falha ao atualizar label ${label.name}: ${err.message}`);
+
+      // O PR fica num try SEPARADO: a falha aqui não invalida o commit, e a
+      // mensagem precisa dizer que a branch existe. Um token com "Contents:
+      // write" pode não ter "Pull requests: write" — permissão NOVA neste modo.
+      if (commitOk) {
+        try {
+          const pr = await ensurePullRequest(tk, owner, repo, {
+            branch,
+            base,
+            title: composePrTitle({ version: CLI_VERSION }),
+            body: composePrBody({
+              version: CLI_VERSION,
+              base,
+              branch,
+              files: treeFiles,
+              config: doConfig ? finalConfigDecision : null,
+              labels: labelResult,
+              skill: skillJobs.map(j => j.target.name),
+            }),
+          });
+          if (!pr) {
+            p.log.warn(
+              `A branch "${branch}" está em dia com "${base}" e não há PR aberto para ela — ` +
+              'nada a revisar.'
+            );
+          } else {
+            prUrl = pr.url;
+            p.log.success(pr.created
+              ? `Pull Request aberto: #${pr.number} — ${pr.url}`
+              : `Pull Request já aberto para "${branch}": #${pr.number} — ${pr.url}`);
+          }
+          flushConfig();
+        } catch (err) {
+          p.log.error(`Commit enviado, mas não foi possível abrir o PR: ${explainGitWriteError(err)}`);
+          p.log.info(
+            'Abra manualmente: ' +
+            `https://github.com/${owner}/${repo}/compare/${base}...${encodeURIComponent(branch)}?expand=1`
+          );
+        }
       }
     }
-    for (const label of labelDiff.orphan) {
+  } else if (repoFiles.length) {
+    const tk = await getToken();
+    for (const f of repoFiles) {
       try {
-        await deleteLabel(tk, owner, repo, label.name);
-        p.log.success(`Label descontinuada removida: ${label.name}`);
+        await upsertFile(tk, owner, repo, f.repoPath, f.local, `chore: update ${path.basename(f.repoPath)} [spec-wave]`);
+        p.log.success(`Arquivo atualizado no repo: ${f.repoPath}`);
       } catch (err) {
-        p.log.error(`Falha ao remover label ${label.name}: ${err.message}`);
+        p.log.error(`Falha ao atualizar ${f.repoPath}: ${err.message}`);
       }
     }
   }
 
-  const committedRepo = repoFiles.length > 0;
+  const configPending = configFlushed && !finalConfigDecision.included;
   p.outro(
     'Update concluído.' +
     (skillJobs.length ? ' Recarregue o agente para pegar a skill nova.' : '') +
-    (configStale?.canApply ? ` Faça commit do ${CONFIG_FILE}.` : '') +
-    (committedRepo ? ' Arquivos do repo foram commitados no remoto.' : '')
+    (prUrl ? ` Revise e faça o merge do Pull Request: ${prUrl}` : '') +
+    (!prMode && repoFiles.length ? ' Arquivos do repo foram commitados no remoto.' : '') +
+    (configPending ? ` Faça commit do ${CONFIG_FILE}.` : '') +
+    (finalConfigDecision.included
+      ? ` O ${CONFIG_FILE} local ficou igual ao do PR — depois do merge, descarte a cópia ` +
+        `local com \`git checkout -- ${CONFIG_FILE}\`.`
+      : '')
   );
 }

package/src/commands/validate.mjs

@@ -4,12 +4,81 @@ import { resolveToken } from '../api/auth.mjs';
 import { getIssue, removeLabel, addLabel, commentOnIssue } from '../api/github-rest.mjs';
 import { slugify } from '../lib/slugify.mjs';
 import {
-  CONFIG_FILE, LABEL_CRITIQUE_FAILED, LABEL_NEEDS_HUMAN,
-  REQUIRED_PLAN_SECTIONS, REQUIRED_SPEC_SECTIONS, labelNames,
+  CONFIG_FILE, LABEL_CRITIQUE_FAILED, LABEL_NEEDS_HUMAN, LABEL_BUG, LABEL_BUG_APPROVED,
+  REQUIRED_PLAN_SECTIONS, REQUIRED_SPEC_SECTIONS, REQUIRED_BUG_SECTIONS, labelNames,
 } from '../config.mjs';
 import { findIncompleteDocSigns } from '../lib/doc-completeness.mjs';
+import { bugDocPaths, findMissingSections } from '../lib/bug-doc.mjs';
+import { detectIssueType } from '../lib/issue-type.mjs';
 import { loadConfig } from '../lib/project-root.mjs';
 
+/**
+ * Validação do bug.md (RFC-004 §5).
+ *
+ * Mesma forma da validação de Feature — seções obrigatórias + sinais de
+ * documento truncado + portões humanos da crítica — com duas diferenças:
+ * um único arquivo, e a falha NÃO devolve o item para a etapa de spec (Bug não
+ * tem etapa de spec). Reaplicar `spec-wave:bug` é o caminho de retomada.
+ */
+async function validateBug({ token, owner, repo, issue, issueNumber, root }) {
+  const n = parseInt(issueNumber, 10);
+  const { fileRel, fileAbs } = bugDocPaths(issue.title, root);
+  const errors = [];
+
+  const names = labelNames(issue);
+  const critiqueFailed = names.includes(LABEL_CRITIQUE_FAILED);
+  const needsHuman = names.includes(LABEL_NEEDS_HUMAN);
+  if (critiqueFailed) {
+    errors.push(
+      '🔎 A crítica adversarial apontou contradições GRAVES no `bug.md` (veja o comentário na ' +
+      `issue). Corrija e remova a label \`${LABEL_CRITIQUE_FAILED}\`.`
+    );
+  }
+  if (needsHuman) {
+    errors.push(
+      `🛑 A crítica reprovou repetidas vezes e a label \`${LABEL_NEEDS_HUMAN}\` foi aplicada. ` +
+      'Uma pessoa precisa revisar o `bug.md` e remover a label.'
+    );
+  }
+
+  if (!existsSync(fileAbs)) {
+    errors.push(
+      `❌ \`bug.md\` não encontrado em \`${fileRel}\` — aplique \`${LABEL_BUG}\` para gerá-lo.`
+    );
+  } else {
+    const content = readFileSync(fileAbs, 'utf-8');
+    for (const section of findMissingSections(content, REQUIRED_BUG_SECTIONS)) {
+      errors.push(`❌ Seção obrigatória ausente no bug.md: **${section}**`);
+    }
+    for (const problem of findIncompleteDocSigns(content)) {
+      errors.push(`❌ \`bug.md\` parece incompleto: ${problem}`);
+    }
+  }
+
+  await removeLabel(token, owner, repo, n, 'spec-wave:ready');
+
+  if (errors.length > 0) {
+    await commentOnIssue(
+      token, owner, repo, n,
+      '⚠️ **Validação falhou — o bug.md não está pronto.**\n\n' +
+      errors.join('\n') +
+      `\n\nCorrija os problemas e adicione novamente a label \`spec-wave:ready\`.`
+    );
+    console.error('Validação falhou:', errors.join(', '));
+    process.exit(1);
+  }
+
+  await addLabel(token, owner, repo, n, LABEL_BUG_APPROVED);
+  await commentOnIssue(
+    token, owner, repo, n,
+    '✅ **bug.md validado.**\n\n' +
+    `📄 [\`${fileRel}\`](https://github.com/${owner}/${repo}/blob/main/${fileRel})\n\n` +
+    'As seis seções obrigatórias estão presentes — reprodução, causa raiz e teste de ' +
+    'regressão inclusive. O bug pode ser aceito na triagem.'
+  );
+  console.log('bug.md validado.');
+}
+
 export async function validate({ issueNumber }) {
   const token = await resolveToken();
   const [envOwner, envRepo] = (process.env.GITHUB_REPOSITORY || '').split('/');
@@ -25,6 +94,13 @@ export async function validate({ issueNumber }) {
   }
 
   const issue = await getIssue(token, owner, repo, parseInt(issueNumber, 10));
+
+  // Bug tem artefato próprio (bug.md) e caminho próprio de validação — não passa
+  // pelo par spec.md + plan.md, que é exclusivo de Feature.
+  if (detectIssueType(issue) === 'Bug') {
+    return await validateBug({ token, owner, repo, issue, issueNumber, root });
+  }
+
   const slug = slugify(issue.title);
   // Ancorado na RAIZ do repo, não no cwd: rodar de um subdiretório encontra o
   // config subindo na árvore e precisa encontrar os documentos no mesmo lugar.
@@ -57,10 +133,8 @@ export async function validate({ issueNumber }) {
     errors.push('❌ `plan.md` não encontrado em `' + `${featureRel}/plan.md` + '`');
   } else {
     const planContent = readFileSync(planPath, 'utf-8');
-    for (const section of REQUIRED_PLAN_SECTIONS) {
-      if (!planContent.includes(`# ${section}`)) {
-        errors.push(`❌ Seção obrigatória ausente no plan.md: **${section}**`);
-      }
+    for (const section of findMissingSections(planContent, REQUIRED_PLAN_SECTIONS)) {
+      errors.push(`❌ Seção obrigatória ausente no plan.md: **${section}**`);
     }
     for (const problem of findIncompleteDocSigns(planContent)) {
       errors.push(`❌ \`plan.md\` parece incompleto: ${problem}`);
@@ -73,10 +147,8 @@ export async function validate({ issueNumber }) {
     errors.push('❌ `spec.md` não encontrado em `' + `${featureRel}/spec.md` + '`');
   } else {
     const specContent = readFileSync(specPath, 'utf-8');
-    for (const section of REQUIRED_SPEC_SECTIONS) {
-      if (!specContent.includes(`# ${section}`)) {
-        errors.push(`❌ Seção obrigatória ausente no spec.md: **${section}**`);
-      }
+    for (const section of findMissingSections(specContent, REQUIRED_SPEC_SECTIONS)) {
+      errors.push(`❌ Seção obrigatória ausente no spec.md: **${section}**`);
     }
     // Seções presentes não garantem documento completo: um corte dentro da
     // última seção passa na checagem acima (foi o caso da EP2-F13).