@spec-wave/cli 0.15.0 → 0.16.1

package/src/commands/code-review.mjs

@@ -52,16 +52,40 @@ async function resolveFeatureIssue(token, owner, repo, issueNumber) {
 // tipo porque cada um tem destino próprio: Tasks → Done, Stories → Code Review,
 // Feature → Code Review (só quando todas as Stories estiverem prontas). Retorna
 // { feature:{number,nodeId,title}|null, stories:Map, tasks:Map }.
+/**
+ * Como o PR trata uma issue referenciada, pelo tipo (função PURA).
+ *
+ *  'bug'    → unidade de review PRÓPRIA: move o Bug e NÃO toca na Feature-pai.
+ *             Um defeito em review não deve arrastar a Feature inteira para
+ *             Code Review — ela pode ter Stories ainda em desenvolvimento.
+ *  'unit'   → Feature/Story/Task: sobe pela cadeia até a Feature (fluxo atual).
+ *  'ignore' → Spike, RFC, Epic e desconhecidos.
+ *
+ * @param {string|null} type
+ * @returns {'bug'|'unit'|'ignore'}
+ */
+export function classifyReviewTarget(type) {
+  if (type === 'Bug') return 'bug';
+  if (type === 'Feature' || type === 'Story' || type === 'Task') return 'unit';
+  return 'ignore';
+}
+
 async function collectReviewUnit(token, owner, repo, issueNumber) {
   const stories = new Map();
   const tasks = new Map();
+  const bugs = new Map();
   const addStory = (n, nodeId, title) => { if (n && nodeId && !stories.has(n)) stories.set(n, { nodeId, title }); };
   const addTask = (n, nodeId, title) => { if (n && nodeId && !tasks.has(n)) tasks.set(n, { nodeId, title }); };
 
   let issue;
-  try { issue = await getIssue(token, owner, repo, issueNumber); } catch { return { feature: null, stories, tasks }; }
+  try { issue = await getIssue(token, owner, repo, issueNumber); } catch { return { feature: null, stories, tasks, bugs }; }
   const type = detectIssueType(issue);
-  if (type !== 'Feature' && type !== 'Story' && type !== 'Task') return { feature: null, stories, tasks };
+  const kind = classifyReviewTarget(type);
+  if (kind === 'ignore') return { feature: null, stories, tasks, bugs };
+  if (kind === 'bug') {
+    bugs.set(issue.number, { nodeId: issue.node_id, title: issue.title });
+    return { feature: null, stories, tasks, bugs };
+  }
 
   const featureIssue = await resolveFeatureIssue(token, owner, repo, issueNumber);
   const feature = featureIssue
@@ -93,7 +117,7 @@ async function collectReviewUnit(token, owner, repo, issueNumber) {
       for (const t of tks) { if (isManual(t)) continue; addTask(t.number, t.nodeId, t.title); }
     }
   }
-  return { feature, stories, tasks };
+  return { feature, stories, tasks, bugs };
 }
 
 // A Feature só avança quando TODAS as suas Stories já estiverem em Code Review
@@ -155,7 +179,7 @@ export async function codeReview({ prNumber }) {
   // Stories → 👀 Code Review; Feature → Code Review só quando TODAS as suas
   // Stories já estiverem em Code Review.
   for (const num of issueNums) {
-    const { feature, stories, tasks } = await collectReviewUnit(token, owner, repo, num);
+    const { feature, stories, tasks, bugs } = await collectReviewUnit(token, owner, repo, num);
 
     // Tasks → Done (Status Done).
     for (const [n, info] of tasks) {
@@ -191,6 +215,23 @@ export async function codeReview({ prNumber }) {
       }
     }
 
+    // Bugs → Code Review, sem Feature-pai envolvida.
+    for (const [n, info] of bugs) {
+      if (seen.has(n)) continue;
+      seen.add(n);
+      try {
+        const moved = await advanceToStage(projectToken, project, etapaField, statusField, info.nodeId, CODE_REVIEW_STAGE, TODO_STATUS);
+        if (moved) {
+          updated.push(`#${n} ${info.title} → ${CODE_REVIEW_STAGE}`);
+          console.log(`Bug #${n} → "${CODE_REVIEW_STAGE}" / Status "${TODO_STATUS}".`);
+        } else {
+          console.log(`Bug #${n} já está em "${CODE_REVIEW_STAGE}" ou etapa posterior — mantido (não retrocede).`);
+        }
+      } catch (err) {
+        console.warn(`Falha ao atualizar #${n}: ${err.message}`);
+      }
+    }
+
     // Feature: só avança se todas as suas Stories já estão em Code Review+.
     if (feature && !featuresChecked.has(feature.number)) {
       featuresChecked.add(feature.number);

package/src/commands/decompose.mjs

@@ -33,6 +33,8 @@ import { lintLanguage } from '../lib/output-lint.mjs';
 import { slugify } from '../lib/slugify.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
 import { loadConfig } from '../lib/project-root.mjs';
+import { resolveFlowContext, commitGenerated } from '../lib/flow-run.mjs';
+import { loadPrompt, toolFreeSystemPrompt } from '../lib/prompt-loader.mjs';
 import {
   renderDecompositionDoc, parseDecompositionDoc, DECOMPOSITION_FILE,
 } from '../lib/decomposition-doc.mjs';
@@ -193,74 +195,24 @@ function formatItemsLintWarning(texts) {
   return `\n\n⚠️ possíveis artefatos de idioma nos itens gerados: ${excerpts}`;
 }
 
-// Grava e commita o rascunho — mesmo padrão do generate-plan (o workflow roda
-// com contents: write e checkout com token).
-function commitFile(filePath, content, message) {
-  mkdirSync(path.dirname(filePath), { recursive: true });
-  writeFileSync(filePath, content, 'utf-8');
-  const git = (cmd) => execSync(cmd, { stdio: 'inherit' });
-  git('git config user.email "spec-wave[bot]@github.com"');
-  git('git config user.name "spec-wave[bot]"');
-  git(`git add "${filePath}"`);
-  git(`git commit -m "${message}"`);
-  git('git pull --rebase');
-  git('git push');
+// 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 });
+  if (published.warning) console.warn(`⚠️  ${published.warning}`);
 }
 
-const FEATURE_SYSTEM_PROMPT = `Você é um Tech Lead experiente em decomposição de trabalho ágil.
-A partir da Feature fornecida (com spec.md e plan.md), gere uma lista de Stories e Tasks.
-
-Responda APENAS com JSON válido neste formato:
-{
-  "stories": [
-    {
-      "title": "Título curto da story (apenas a parte 'quero', sem prefixo)",
-      "userStory": "Como <perfil>, quero <objetivo>, para <benefício>",
-      "body": "Descrição complementar da story com contexto e critérios de aceite relevantes",
-      "dependsOn": [0],
-      "tasks": [
-        {
-          "title": "Título técnico curto da task (sem prefixo)",
-          "body": "Descrição técnica detalhada"
-        }
-      ]
-    }
-  ]
-}
-
-Regras:
-- "title" deve ser CURTO (máx. ~60 caracteres): apenas a parte "quero" da user story, sem o "Como" nem o "para", e sem prefixo. Ex.: "visualizar meus repositórios em layout responsivo"
-- "userStory" deve trazer a user story completa no formato "Como <perfil>, quero <objetivo>, para <benefício>"
-- "body" é texto complementar (contexto, critérios de aceite); não repita o título
-- Cada Story deve ter 2–5 Tasks associadas
-- Tasks devem ser atividades técnicas concretas, com "title" curto e "body" detalhado
-- Gere entre 3 e 7 Stories por Feature
-- Ordene as stories na sequência de implementação — a ORDEM da lista importa
-- "dependsOn" (opcional): índices 0-based das stories ANTERIORES na lista das quais esta story depende. Referencie apenas índices menores que o da própria story. Use [] quando a story puder ser feita em paralelo (sem dependências); se omitido, assume-se dependência da story anterior (sequencial)`;
-
-const RFC_SYSTEM_PROMPT = `Você é um Tech Lead experiente. A partir do RFC fornecido (proposta técnica/de processo), gere a lista de Tasks técnicas concretas necessárias para implementá-lo.
-
-Responda APENAS com JSON válido neste formato:
-{
-  "tasks": [
-    {
-      "title": "Título técnico curto da task (sem prefixo)",
-      "body": "Descrição técnica detalhada (o que fazer, áreas/arquivos afetados, critério de pronto)"
-    }
-  ]
-}
-
-Regras:
-- "title" CURTO (máx. ~60 caracteres), sem prefixo.
-- "body" detalhado e acionável.
-- Gere entre 3 e 10 Tasks concretas que, juntas, cubram o RFC.`;
+// Os prompts vivem em `src/plugin/skills/decompose/model-prompt.{feature,rfc}.md`
+// (sobrescrevíveis em `.spec-wave/prompts/decompose.feature.md`). O contrato JSON é o
+// `json.shape` do frontmatter — quem parseia a saída e quem instrui o modelo
+// passam a ler a MESMA declaração, em vez de duas cópias que podiam divergir.
 
 // ---------------------------------------------------------------------------
 // Etapa 1: rascunho (label spec-wave:decompose)
 // ---------------------------------------------------------------------------
 
 async function draftDecomposition(ctx) {
-  const { token, owner, repo, issue, issueNumber, type, labels, usage, docDir, docPath, docRel } = ctx;
+  const { token, owner, repo, issue, issueNumber, type, labels, usage, root, runMode, docDir, docPath, docRel } = ctx;
   const number = parseInt(issueNumber, 10);
   const kind = DECOMPOSE_TARGETS[type]; // Feature → 'stories'; RFC → 'tasks'
   const blobUrl = `https://github.com/${owner}/${repo}/blob/main/${docRel}`;
@@ -292,8 +244,12 @@ async function draftDecomposition(ctx) {
           `\n## plan.md\n${planContent || '(plan.md não encontrado)'}`,
         ].join('\n');
 
+    const decomposePrompt = loadPrompt(
+      type === 'RFC' ? 'decompose/rfc' : 'decompose/feature',
+      { cwd: root },
+    );
     const generated = parseModelJson(await generateDocument(
-      type === 'RFC' ? RFC_SYSTEM_PROMPT : FEATURE_SYSTEM_PROMPT,
+      toolFreeSystemPrompt(decomposePrompt),
       userContent,
       { action: 'decompose', labels, usage }
     ));
@@ -305,7 +261,7 @@ async function draftDecomposition(ctx) {
       stories: generated.stories || [],
       tasks: generated.tasks || [],
     });
-    commitFile(docPath, markdown, `docs: rascunho de decomposição de ${docRel} [spec-wave]`);
+    commitFile(docPath, markdown, `docs: rascunho de decomposição de ${docRel} [spec-wave]`, runMode);
     console.log(`Rascunho commitado em ${docRel}.`);
   }
 
@@ -627,15 +583,9 @@ export async function decompose({ issueNumber, apply = false }) {
   // PROJECT_TOKEN deve ter scope "project" para atualizar GitHub Projects v2.
   // Fallback para GITHUB_TOKEN (só funciona em repos pessoais sem org restrictions).
   const projectToken = process.env.PROJECT_TOKEN || token;
-  const [owner, repo] = (process.env.GITHUB_REPOSITORY || '').split('/');
-
-  if (!owner || !repo) {
-    throw new Error(
-      'GITHUB_REPOSITORY env var não definida.\n' +
-      'Este comando roda no GitHub Actions. Para testar localmente:\n' +
-      '  GITHUB_REPOSITORY=owner/repo spec-wave decompose --issue-number 1'
-    );
-  }
+  // Roda nos dois modos: no Action (disparado por label) e na sessão local.
+  const { owner, repo, mode: runMode } = resolveFlowContext({ command: 'decompose' });
+  console.log(`Modo de execução: ${runMode}`);
 
   const number = parseInt(issueNumber, 10);
   const issue = await getIssue(token, owner, repo, number);
@@ -707,7 +657,7 @@ export async function decompose({ issueNumber, apply = false }) {
   const usageEntries = [];
   const ctx = {
     token, projectToken, owner, repo, issue, issueNumber, type, labels, comments,
-    root, docDir, docPath, docRel: `${docRel}/${DECOMPOSITION_FILE}`,
+    root, runMode, docDir, docPath, docRel: `${docRel}/${DECOMPOSITION_FILE}`,
     escalationModel: config?.ai?.escalationModel || null,
     maxCritiqueAttempts:
       Number.isInteger(config?.ai?.maxCritiqueAttempts) && config.ai.maxCritiqueAttempts > 0

package/src/commands/dev-agent.mjs

@@ -19,7 +19,7 @@ import {
 import { homedir, tmpdir } from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { CONFIG_FILE } from '../config.mjs';
+import { CONFIG_FILE, LABEL_DEV_AGENT } from '../config.mjs';
 import { findConfigPath } from '../lib/project-root.mjs';
 
 const __dir = path.dirname(fileURLToPath(import.meta.url));
@@ -82,7 +82,7 @@ export function renderAgentConfig({ owner, repo }) {
 # Schema completo: https://github.com/${AGENT_REPO}#configuração
 
 repo = "${owner}/${repo}"
-queue_label = "spec-wave:dev-agent"
+queue_label = "${LABEL_DEV_AGENT}"
 
 # Defaults do agente (descomente para ajustar):
 #poll_interval_secs = 60       # consulta à fila quando ocioso
@@ -412,7 +412,7 @@ async function finishSetup({ cfg, home, binPath, configPath, options, configActi
   p.outro(
     `${chalk.green('✓')} Agente pronto.\n` +
     `  Rodar agora:  ${chalk.cyan('spec-wave dev-agent --run')}\n` +
-    '  Enfileirar:   aplique a label spec-wave:dev-agent numa issue [FEATURE] já decomposta.'
+    `  Enfileirar:   aplique a label ${LABEL_DEV_AGENT} numa issue [FEATURE] já decomposta.`
   );
 }
 

package/src/commands/doctor.mjs

@@ -12,7 +12,8 @@ import { resolveToken, verifyTokenScopes } from '../api/auth.mjs';
 import { getProjectSnapshot } from '../api/github-graphql.mjs';
 import {
   CONFIG_FILE, WORKFLOW_FILES, getProvider, DEFAULT_PROVIDER, STATUS_OPTIONS,
-  ALL_LABELS, LABEL_NEEDS_HUMAN, MODEL_LABEL_PREFIX, DEFAULT_MAX_CRITIQUE_ATTEMPTS,
+  RETIRED_STAGES, ALL_LABELS, LABEL_NEEDS_HUMAN, MODEL_LABEL_PREFIX,
+  DEFAULT_MAX_CRITIQUE_ATTEMPTS, STAGE_TRACKS,
 } from '../config.mjs';
 import { findConfigPath } from '../lib/project-root.mjs';
 import {
@@ -284,7 +285,12 @@ async function checkConfig(ctx) {
 export function inspectBoardHygiene({ boardStages = null, repoLabels = null } = {}) {
   const canonical = STATUS_OPTIONS.map(s => s.name);
   const known = new Set(canonical);
-  const unknownStages = boardStages ? boardStages.filter(s => !known.has(s)) : [];
+  const retired = new Map(RETIRED_STAGES.map(s => [s.name, s]));
+  const foreign = boardStages ? boardStages.filter(s => !known.has(s)) : [];
+  // Uma etapa aposentada também é "fora do fluxo", mas a orientação ao usuário
+  // é diferente da de uma coluna inventada — por isso saem em listas separadas.
+  const retiredStages = foreign.filter(s => retired.has(s)).map(s => retired.get(s));
+  const unknownStages = foreign.filter(s => !retired.has(s));
   const missingStages = boardStages ? canonical.filter(s => !boardStages.includes(s)) : [];
 
   const knownLabels = new Set(ALL_LABELS.map(l => l.name));
@@ -294,7 +300,29 @@ export function inspectBoardHygiene({ boardStages = null, repoLabels = null } =
   const missingLabels = repoLabels
     ? ALL_LABELS.map(l => l.name).filter(n => !repoLabels.includes(n))
     : [];
-  return { unknownStages, missingStages, orphanLabels, missingLabels };
+  return { unknownStages, retiredStages, missingStages, orphanLabels, missingLabels };
+}
+
+/**
+ * O board comporta a trilha do Bug? (função PURA)
+ *
+ * Um Bug percorre 🐞 Triagem → ✅ Ready → … → 🚀 Deploy → 🎉 Done (RFC-004 §4).
+ * Se o board não tem alguma dessas colunas, o item não tem onde parar: o campo
+ * "Etapa" só aceita as opções que existem, então a escrita falha em silêncio e
+ * o bug fica sem etapa — invisível em toda tela que filtra por etapa.
+ *
+ * Só reporta quando há Bug aberto: um board sem bugs não precisa da trilha.
+ *
+ * @param {object} params
+ * @param {string[]|null} [params.boardStages] opções do campo Etapa
+ * @param {number} [params.openBugCount] bugs abertos no repositório
+ * @returns {{ missingTrackStages: string[] }}
+ */
+export function inspectBugTrack({ boardStages = null, openBugCount = 0 } = {}) {
+  if (!boardStages || openBugCount <= 0) return { missingTrackStages: [] };
+  return {
+    missingTrackStages: STAGE_TRACKS.Bug.filter(s => !boardStages.includes(s)),
+  };
 }
 
 async function checkBoardHygiene(ctx) {
@@ -315,6 +343,7 @@ async function checkBoardHygiene(ctx) {
   }
 
   let repoLabels = null;
+  let openBugCount = 0;
   if (ctx.token && cfg.owner && cfg.repo) {
     try {
       const res = await makeOctokit(ctx.token)
@@ -323,9 +352,17 @@ async function checkBoardHygiene(ctx) {
     } catch {
       // labels não verificáveis agora — segue só com o board
     }
+    try {
+      const bugs = await makeOctokit(ctx.token).paginate('GET /repos/{owner}/{repo}/issues', {
+        owner: cfg.owner, repo: cfg.repo, labels: '[BUG]', state: 'open', per_page: 100,
+      });
+      openBugCount = bugs.filter(i => !i.pull_request).length;
+    } catch {
+      // sem acesso às issues — o check da trilha do Bug fica de fora
+    }
   }
 
-  const { unknownStages, missingStages, orphanLabels, missingLabels } =
+  const { unknownStages, retiredStages, missingStages, orphanLabels, missingLabels } =
     inspectBoardHygiene({ boardStages, repoLabels });
 
   const notes = [];
@@ -343,10 +380,32 @@ async function checkBoardHygiene(ctx) {
       'Mova os itens para uma etapa do fluxo e remova a coluna.'
     );
   }
+  for (const stage of retiredStages) {
+    status = 'warn';
+    notes.push(
+      `Etapa descontinuada ainda no board: ${stage.name} (removida do fluxo na v${stage.removedIn}). ` +
+      `Mova os itens dela para ${stage.replacedBy} e apague a coluna nas configurações do campo ` +
+      '"Etapa"; depois rode `refresh --config` para tirar o id do .spec-wave.json.'
+    );
+  }
   if (missingStages.length > 0) {
     status = 'warn';
-    notes.push(`Etapas do RFC-001 ausentes no board: ${missingStages.join(', ')} — rode \`refresh\`.`);
+    notes.push(
+      `Etapas do RFC-001 ausentes no board: ${missingStages.join(', ')} — rode ` +
+      '`refresh --stages --dry-run` para ver o plano, ou crie a coluna à mão nas configurações ' +
+      'do campo "Etapa" e rode `refresh --config`.'
+    );
+  }
+  const { missingTrackStages } = inspectBugTrack({ boardStages, openBugCount });
+  if (missingTrackStages.length > 0) {
+    status = 'warn';
+    notes.push(
+      `${openBugCount} Bug(s) aberto(s), mas o board não tem: ${missingTrackStages.join(', ')}. ` +
+      'Um Bug movido para uma etapa inexistente fica SEM Etapa e some das telas — ' +
+      'rode `refresh --stages`.'
+    );
   }
+
   if (repoLabels) {
     if (orphanLabels.length > 0) {
       status = 'warn';
@@ -504,10 +563,22 @@ async function checkAi(ctx) {
     );
   } else {
     notes.push(
-      `Saída estruturada da crítica: ${provider.value === 'anthropic' ? 'tool call forçado' : 'response_format json_schema'} ` +
+      `Saída estruturada da crítica: tool call forçado (${provider.value}) ` +
       `· strict=${supportsStrictSchema(critiqueModel) ? 'sim' : 'não'} neste modelo.`
     );
   }
+  // O backend anthropic não chama a API — sobe o Claude Code CLI como
+  // subprocesso, que não existe no runner dos workflows (só há setup-node).
+  if (provider.value === 'anthropic') {
+    problems.push(
+      'O provider `anthropic` NÃO roda nos GitHub Actions: ele sobe o Claude Code CLI como ' +
+      'subprocesso, ausente no runner. As Actions de spec/plan/decompose vão falhar. ' +
+      'Troque para `"provider": "openrouter"` no .spec-wave.json (e adicione o secret ' +
+      'OPENROUTER_API_KEY), ou instale o Claude Code no workflow e defina ' +
+      'SPEC_WAVE_ALLOW_ANTHROPIC_IN_CI=1. Localmente o anthropic funciona.'
+    );
+  }
+
   if (process.env[provider.secret]) {
     notes.push(`${provider.secret} presente no ambiente local.`);
   } else {

package/src/commands/generate-bug.mjs

@@ -0,0 +1,195 @@
+// Gera o bug.md (RFC-004 §5) — espelho do generate-spec, com três diferenças
+// que vêm da natureza do artefato:
+//
+//  1. O relato mora nos COMENTÁRIOS, não só no corpo. Nas origens "reprovação
+//     de QA" e "suporte", o corpo da issue é uma linha e o que descreve o
+//     defeito vem depois, em comentário. Por isso eles entram no payload.
+//  2. A crítica adversarial recebe o relato original junto do documento: a
+//     pergunta que ela responde é se a causa raiz proposta explica OS SINTOMAS
+//     RELATADOS — sem o relato, ela só avalia coerência interna.
+//  3. Escreve em docs/bugs/<slug>/, fora de docs/features/.
+import { execSync } from 'node:child_process';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { resolveToken } from '../api/auth.mjs';
+import {
+  getIssue, removeLabel, addLabel, commentOnIssue, listIssueComments,
+} from '../api/github-rest.mjs';
+import { generateDocument } from '../lib/claude.mjs';
+import { recordUsage } from '../lib/usage-report.mjs';
+import { loadConfig } from '../lib/project-root.mjs';
+import { loadPrompt, toolFreeSystemPrompt } from '../lib/prompt-loader.mjs';
+import { detectIssueType } from '../lib/issue-type.mjs';
+import { bugDocPaths } from '../lib/bug-doc.mjs';
+import {
+  runCritique, resolveCritiqueAttempt, renderNeedsHumanComment,
+} from '../lib/critique.mjs';
+import {
+  LABEL_BUG, LABEL_CRITIQUE_FAILED, LABEL_NEEDS_HUMAN, REQUIRED_BUG_SECTIONS,
+  TARGET_LANGUAGE, DEFAULT_MAX_CRITIQUE_ATTEMPTS, labelNames,
+} from '../config.mjs';
+
+// Relato = corpo + comentários humanos, na ordem cronológica. Comentários do
+// próprio spec-wave são ruído aqui (críticas anteriores, relatórios de uso):
+// realimentá-los faria o modelo auditar a si mesmo em vez do defeito.
+function buildReport(issue, comments) {
+  const parts = [`### Descrição da issue\n\n${issue.body || '(sem descrição)'}`];
+  const humanos = (comments || []).filter(c => !isSpecWaveComment(c.body));
+  for (const c of humanos) {
+    const autor = c.user?.login || 'desconhecido';
+    parts.push(`### Comentário de @${autor}\n\n${c.body}`);
+  }
+  return parts.join('\n\n');
+}
+
+function isSpecWaveComment(body) {
+  const t = String(body || '');
+  return t.includes('<!-- spec-wave:') || t.includes('**(spec-wave)**') || t.includes('(spec-wave)');
+}
+
+export async function generateBug({ issueNumber }) {
+  const token = await resolveToken();
+  const [owner, repo] = (process.env.GITHUB_REPOSITORY || '').split('/');
+  const { root } = loadConfig();
+  const n = parseInt(issueNumber, 10);
+
+  if (!owner || !repo) {
+    throw new Error(
+      'GITHUB_REPOSITORY env var não definida.\n' +
+      'Este comando roda no GitHub Actions. Para testar localmente:\n' +
+      '  GITHUB_REPOSITORY=owner/repo spec-wave generate-bug --issue-number 1'
+    );
+  }
+
+  console.log(`Buscando issue #${n}...`);
+  const issue = await getIssue(token, owner, repo, n);
+
+  // Guarda invertida em relação ao generate-spec: aqui só Bug passa.
+  const type = detectIssueType(issue);
+  if (type !== 'Bug') {
+    console.log(`Issue #${n} é ${type}: bug.md é gerado só para Bug.`);
+    await removeLabel(token, owner, repo, n, LABEL_BUG);
+    await commentOnIssue(
+      token, owner, repo, n,
+      `ℹ️ **bug.md não gerado:** o tipo **${type}** não usa esse artefato. ` +
+      'Nenhum arquivo foi criado.'
+    ).catch(() => {});
+    return;
+  }
+
+  const issueLabels = labelNames(issue);
+  if (issueLabels.includes(LABEL_NEEDS_HUMAN)) {
+    console.log(`Issue #${n} está com ${LABEL_NEEDS_HUMAN}: geração bloqueada.`);
+    await removeLabel(token, owner, repo, n, LABEL_BUG);
+    return;
+  }
+
+  const { slug, dirRel, fileRel, dirAbs, fileAbs } = bugDocPaths(issue.title, root);
+
+  const comments = await listIssueComments(token, owner, repo, n).catch(() => []);
+  const report = buildReport(issue, comments);
+
+  const payload = {
+    metadata: {
+      bug_title: issue.title,
+      labels: issueLabels,
+      required_sections: REQUIRED_BUG_SECTIONS,
+    },
+    report: { raw: report },
+  };
+  const userContent =
+    `Gere o bug.md a partir deste payload JSON:\n\n${JSON.stringify(payload, null, 2)}`;
+
+  const usageEntries = [];
+  try {
+    console.log(`Gerando bug.md para: ${issue.title}`);
+    const systemPrompt = toolFreeSystemPrompt(loadPrompt('bug', { cwd: root }));
+    const { content } = await generateDocument(systemPrompt, userContent, {
+      action: 'bug',
+      labels: issueLabels,
+      lint: { lang: TARGET_LANGUAGE },
+      withReport: true,
+      usage: usageEntries,
+    });
+
+    mkdirSync(dirAbs, { recursive: true });
+    writeFileSync(fileAbs, content, 'utf-8');
+
+    const git = (cmd) => execSync(cmd, { stdio: 'inherit' });
+    git('git config user.email "spec-wave[bot]@github.com"');
+    git('git config user.name "spec-wave[bot]"');
+    git(`git add "${fileAbs}"`);
+    git(`git commit -m "docs: generate bug.md for ${slug} [spec-wave]"`);
+    git('git pull --rebase');
+    git('git push');
+
+    await removeLabel(token, owner, repo, n, LABEL_BUG);
+
+    // Crítica adversarial: NÃO fatal. Um bug.md gerado e criticado como grave
+    // ainda é melhor que nenhum — o portão é a label, verificada na triagem.
+    const critique = await critiqueBugDoc({
+      token, owner, repo, issueNumber: n, issue,
+      bugDoc: content, report, labels: issueLabels, cwd: root, usage: usageEntries,
+    });
+
+    await commentOnIssue(
+      token, owner, repo, n,
+      '🐞 **bug.md gerado automaticamente!**\n\n' +
+      `📄 Arquivo: [\`${fileRel}\`](https://github.com/${owner}/${repo}/blob/main/${fileRel})\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' +
+      `\`\`\`\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})`);
+  } 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.
+    await removeLabel(token, owner, repo, n, LABEL_BUG).catch(() => {});
+    await commentOnIssue(
+      token, owner, repo, n,
+      '❌ **Falha ao gerar o bug.md**\n\n' +
+      `\`\`\`\n${err.message}\n\`\`\`\n\n` +
+      `A label \`${LABEL_BUG}\` foi removida para destravar o gatilho — ` +
+      'adicione-a de novo para tentar outra vez.'
+    ).catch(() => {});
+    throw err;
+  } finally {
+    await recordUsage({ token, owner, repo, issueNumber: n, entries: usageEntries });
+  }
+}
+
+// Roda a crítica e reflete o veredito em labels/comentário. Best-effort: uma
+// falha da crítica não invalida o documento já commitado.
+async function critiqueBugDoc({
+  token, owner, repo, issueNumber, issue, bugDoc, report, labels, cwd, usage,
+}) {
+  try {
+    const comments = await listIssueComments(token, owner, repo, issueNumber).catch(() => []);
+    const { attempt, blocked } = resolveCritiqueAttempt({
+      comments, labels, kind: 'bug', maxAttempts: DEFAULT_MAX_CRITIQUE_ATTEMPTS,
+    });
+
+    if (blocked) {
+      await addLabel(token, owner, repo, issueNumber, LABEL_NEEDS_HUMAN);
+      await commentOnIssue(
+        token, owner, repo, issueNumber,
+        renderNeedsHumanComment({ kind: 'bug', maxAttempts: DEFAULT_MAX_CRITIQUE_ATTEMPTS })
+      );
+      return { blocked: true };
+    }
+
+    const result = await runCritique({
+      kind: 'bug', bugDoc, bugReport: report, attempt, labels, usage, cwd,
+    });
+    await commentOnIssue(token, owner, repo, issueNumber, result.markdown);
+    if (result.grave) {
+      await addLabel(token, owner, repo, issueNumber, LABEL_CRITIQUE_FAILED);
+      return { blocked: true };
+    }
+    return { blocked: false };
+  } catch (err) {
+    console.error(`Crítica do bug.md falhou (não fatal): ${err.message}`);
+    return { blocked: false };
+  }
+}