@spec-wave/cli 0.15.0 → 0.16.1

package/src/config.mjs

@@ -35,7 +35,7 @@ export const DEFAULT_PROVIDER = 'anthropic';
 // Ações de IA que podem ter modelo próprio no .spec-wave.json (bloco
 // `ai.models`, ex.: { "critique": "claude-opus-4-1" }). Resolvidas em runtime
 // por resolveAiConfig() em src/lib/claude.mjs.
-export const AI_ACTIONS = ['spec', 'plan', 'decompose', 'critique'];
+export const AI_ACTIONS = ['spec', 'plan', 'decompose', 'critique', 'bug'];
 
 // Override de modelo POR EXECUÇÃO: a label `spec-wave:model:<apelido>` na issue
 // aponta para uma entrada de `ai.modelAliases` do .spec-wave.json. Serve para
@@ -59,6 +59,12 @@ export function getProvider(value) {
 
 export const STATUS_OPTIONS = [
   { name: '📥 Backlog',          color: 'GRAY'   },
+  // 🐞 Triagem é a porta de entrada do Bug reportado (RFC-004 §4). Entra AQUI, e
+  // não no fim da lista, porque shouldAdvanceStage compara índices RELATIVOS em
+  // STAGE_ORDER: inserir no meio preserva a validade de todo par (atual, destino)
+  // que já funcionava, enquanto pôr no fim tornaria "Triagem → qualquer coisa"
+  // um retrocesso e travaria o fluxo inteiro do Bug.
+  { name: '🐞 Triagem',          color: 'RED'    },
   { name: '🎯 Priorizado',       color: 'BLUE'   },
   { name: '📋 Spec',             color: 'YELLOW' },
   { name: '📋 Plan',             color: 'YELLOW' },
@@ -77,14 +83,74 @@ export const STATUS_OPTIONS = [
 //  • "Status" (campo nativo: Todo/In Progress/Done): o PROGRESSO dentro da etapa
 //    atual. Ao avançar de etapa, o Status reinicia em "Todo".
 
+// Etapas que JÁ FORAM canônicas e saíram do fluxo. Um board antigo ainda as
+// tem como opção do campo Etapa, e o `.spec-wave.json` gerado na época ainda
+// guarda o id delas. São reportadas pelo doctor à parte das colunas criadas à
+// mão, porque a orientação é outra: aqui a coluna não deve ser adaptada, deve
+// ser esvaziada e removida.
+export const RETIRED_STAGES = [
+  { name: '📋 Backlog Técnico', removedIn: '0.10.0', replacedBy: '✅ Ready' },
+];
+
 // Etapas (campo Etapa) referenciadas pelo fluxo de implementação.
+export const STAGE_TRIAGE = STATUS_OPTIONS.find(s => s.name.includes('Triagem')).name;
 export const STAGE_READY = STATUS_OPTIONS.find(s => s.name.includes('Ready')).name;
 export const STAGE_DEVELOPMENT = STATUS_OPTIONS.find(s => s.name.includes('Desenvolvimento')).name;
 export const STAGE_CODE_REVIEW = STATUS_OPTIONS.find(s => s.name.includes('Code Review')).name;
+export const STAGE_QA = STATUS_OPTIONS.find(s => s.name.includes('QA')).name;
+export const STAGE_UAT = STATUS_OPTIONS.find(s => s.name.includes('Homologação')).name;
+export const STAGE_DEPLOY = STATUS_OPTIONS.find(s => s.name.includes('Deploy')).name;
 export const STAGE_DONE = STATUS_OPTIONS.find(s => s.name.includes('Done')).name;
 // Ordem canônica das etapas — usada para garantir que uma issue só AVANÇA.
 export const STAGE_ORDER = STATUS_OPTIONS.map(s => s.name);
 
+// Trilha de cada tipo de work item: as etapas que ele DE FATO percorre, na
+// ordem (RFC-001 §4, RFC-004 §4). É documentação executável, não regra dura — a
+// única regra dura do board continua sendo shouldAdvanceStage ("só avança").
+// isStageInTrack serve para AVISAR quem move um item para fora da trilha dele
+// (ex.: um Bug para 📋 Homologação), não para bloquear: bloquear exigiria que
+// todo chamador de advanceToStage soubesse o tipo do item, e dois deles não
+// sabem. Um tipo ausente daqui não tem trilha declarada e nunca gera aviso.
+export const STAGE_TRACKS = {
+  Feature: STAGE_ORDER.filter(s => s !== STAGE_TRIAGE),
+  Story:   [STAGE_READY, STAGE_DEVELOPMENT, STAGE_CODE_REVIEW, STAGE_QA, STAGE_UAT, STAGE_DONE],
+  Task:    [STAGE_READY, STAGE_DEVELOPMENT, STAGE_DONE],
+  Bug:     [STAGE_TRIAGE, STAGE_READY, STAGE_DEVELOPMENT, STAGE_CODE_REVIEW, STAGE_QA, STAGE_DEPLOY, STAGE_DONE],
+  RFC:     [STATUS_OPTIONS[0].name, STAGE_READY, STAGE_DEVELOPMENT, STAGE_DONE],
+};
+
+/**
+ * A etapa em que um item NASCE (função PURA).
+ *
+ * Quase todo tipo nasce em 📥 Backlog. O Bug é a exceção: nasce em 🐞 Triagem,
+ * porque um defeito reportado precisa ser confirmado antes de virar fila. A
+ * exceção da exceção é o Bug P0 — a urgência inverte a ordem, ele nasce em
+ * ✅ Ready e a triagem é confirmada depois (RFC-004 §4.3).
+ *
+ * @param {string} type tipo do work item ('Feature', 'Bug', …)
+ * @param {string|null} [severity] prioridade, quando já conhecida ('P0'…'P3')
+ * @returns {string} nome da etapa inicial
+ */
+export function initialStageForType(type, severity = null) {
+  if (type !== 'Bug') return STATUS_OPTIONS[0].name;
+  return severity === 'P0' ? STAGE_READY : STAGE_TRIAGE;
+}
+
+/**
+ * A etapa pertence à trilha declarada do tipo? (função PURA)
+ *
+ * Tipo sem trilha declarada devolve `true` — a ausência de trilha não é motivo
+ * para avisar nada.
+ *
+ * @param {string} type tipo do work item
+ * @param {string} stage nome da etapa
+ * @returns {boolean}
+ */
+export function isStageInTrack(type, stage) {
+  const track = STAGE_TRACKS[type];
+  return track ? track.includes(stage) : true;
+}
+
 // Valores do campo nativo "Status" (progresso dentro da etapa).
 export const PROGRESS_TODO = 'Todo';
 export const PROGRESS_IN_PROGRESS = 'In Progress';
@@ -199,6 +265,70 @@ export const PRIORITY_LABELS = [
 export const LABEL_DECOMPOSE = 'spec-wave:decompose';
 export const LABEL_DECOMPOSE_APPLY = 'spec-wave:decompose-apply';
 
+// Label de gatilho da fila do dev-agent (o daemon `spec-wave-agent`): aplicá-la
+// numa issue coloca a issue na fila que o agente consulta com `gh issue list`.
+// Precisa estar registrada aqui porque `update` remove TODA label `spec-wave:*`
+// que não esteja em ALL_LABELS — sem esta entrada, um `spec-wave update` de
+// rotina apagava a label da fila e desligava o agente sem aviso.
+export const LABEL_DEV_AGENT = 'spec-wave:dev-agent';
+
+// Gatilho e estado do bug.md (RFC-004 §5). O bug.md é o artefato do Bug — leve
+// por decisão: um defeito não gera spec.md + plan.md.
+export const LABEL_BUG = 'spec-wave:bug';
+export const LABEL_BUG_APPROVED = 'spec-wave:bug-approved';
+
+// Desfecho da triagem do PM (RFC-004 §4.1). São mutuamente exclusivas: um bug
+// triado foi aceito, rejeitado ou marcado como duplicata.
+export const LABEL_TRIAGED = 'spec-wave:triaged';
+export const LABEL_DUPLICATE = 'spec-wave:duplicate';
+export const LABEL_WONT_FIX = 'spec-wave:wont-fix';
+
+// Regressão pós-deploy (origem d): defeito aberto contra uma release entregue.
+export const LABEL_REGRESSION = 'spec-wave:regression';
+
+// Origem do defeito — as quatro portas de entrada do RFC-004 §4.2, detalhadas
+// em seis rótulos. É o que torna possível medir DE ONDE vêm os bugs, e portanto
+// qual portão do processo está deixando passar.
+//
+// Vive em label, não em campo do Projects v2, porque SnapshotItem.labels já
+// chega ao client sem mudança nenhuma de contrato — um campo novo exigiria
+// mexer em toSnapshotItem, no ProjectConfig e no refresh de todo repo.
+export const BUG_ORIGINS = ['qa', 'uat', 'support', 'dev', 'review', 'regression'];
+export const BUG_ORIGIN_PREFIX = 'spec-wave:origin:';
+
+const BUG_ORIGIN_DESCRIPTIONS = {
+  qa: 'Bug encontrado na reprovação de QA',
+  uat: 'Bug encontrado na reprovação da Homologação',
+  support: 'Bug reportado por suporte ou usuário em produção',
+  dev: 'Bug encontrado pelo dev durante o desenvolvimento',
+  review: 'Bug encontrado no Code Review',
+  regression: 'Regressão detectada após o deploy',
+};
+
+/**
+ * Label de origem a partir do identificador (função PURA).
+ *
+ * @param {string} origin um de BUG_ORIGINS
+ * @returns {string|null} a label, ou null se a origem não existir
+ */
+export function bugOriginLabel(origin) {
+  return BUG_ORIGINS.includes(origin) ? `${BUG_ORIGIN_PREFIX}${origin}` : null;
+}
+
+/**
+ * Origem a partir das labels de uma issue (função PURA).
+ *
+ * @param {object|Array} issueOrLabels issue ou array de labels
+ * @returns {string|null} a origem, ou null quando não há
+ */
+export function bugOriginFromLabels(issueOrLabels) {
+  const found = labelNames(issueOrLabels)
+    .find(n => n.startsWith(BUG_ORIGIN_PREFIX));
+  if (!found) return null;
+  const origin = found.slice(BUG_ORIGIN_PREFIX.length);
+  return BUG_ORIGINS.includes(origin) ? origin : null;
+}
+
 // Labels de estado gravadas pelas automações (não são gatilhos do usuário).
 export const LABEL_CRITIQUE_FAILED = 'spec-wave:critique-failed';
 export const LABEL_DECOMPOSED = 'spec-wave:decomposed';
@@ -212,6 +342,18 @@ export const TRIGGER_LABELS = [
   { name: 'spec-wave:plan-approved', color: '0E8A16', description: 'Spec+plan validados com sucesso'       },
   { name: LABEL_DECOMPOSE,           color: 'BFD4F2', description: 'Gerar/re-criticar o rascunho da decomposição (decomposition.md)' },
   { name: LABEL_DECOMPOSE_APPLY,     color: 'BFD4F2', description: 'Aplicar o decomposition.md revisado: criar Stories e Tasks' },
+  { name: LABEL_DEV_AGENT,           color: '5319E7', description: 'Enfileira a issue para o dev-agent autônomo' },
+  { name: LABEL_BUG,                 color: 'BFD4F2', description: 'Gerar bug.md via GitHub Action' },
+  { name: LABEL_BUG_APPROVED,        color: '0E8A16', description: 'bug.md validado (reprodução, causa raiz e teste de regressão)' },
+  { name: LABEL_TRIAGED,             color: '0E8A16', description: 'Bug triado pelo PM (severidade, origem e pai definidos)' },
+  { name: LABEL_DUPLICATE,           color: 'EDEDED', description: 'Duplicata de outra issue (o corpo aponta qual)' },
+  { name: LABEL_WONT_FIX,            color: 'EDEDED', description: 'Rejeitado na triagem — não será corrigido' },
+  { name: LABEL_REGRESSION,          color: 'B60205', description: 'Regressão detectada após o deploy' },
+  ...BUG_ORIGINS.map(o => ({
+    name: `${BUG_ORIGIN_PREFIX}${o}`,
+    color: 'D93F0B',
+    description: BUG_ORIGIN_DESCRIPTIONS[o],
+  })),
   { name: LABEL_DECOMPOSE_READY,     color: '0E8A16', description: 'Rascunho de decomposição pronto para revisão humana' },
   { name: LABEL_CRITIQUE_FAILED,     color: 'B60205', description: 'Crítica adversarial apontou contradições graves' },
   { name: LABEL_NEEDS_HUMAN,         color: 'B60205', description: 'Crítica reprovou N vezes seguidas — precisa de revisão humana' },
@@ -236,6 +378,7 @@ export function labelNames(issueOrLabels) {
 }
 
 export const WORKFLOW_FILES = [
+  'generate-bug.yml',
   'generate-plan.yml',
   'generate-spec.yml',
   'validate.yml',
@@ -255,6 +398,21 @@ export const REQUIRED_SPEC_SECTIONS = [
   'Requisitos Não-Funcionais',
 ];
 
+// Seções obrigatórias do bug.md (RFC-004 §5). Deliberadamente seis, e leves: o
+// que o corretor precisa saber para reproduzir, achar a causa e provar o fix.
+//
+// ⚠️ validate compara com `content.includes('# ' + secao)` — byte a byte. Nada
+// de caractere exótico aqui (ex.: '×' U+00D7), e o prompt do generate-bug lê
+// ESTA constante para emitir exatamente estes títulos.
+export const REQUIRED_BUG_SECTIONS = [
+  'Reprodução',
+  'Esperado e Obtido',
+  'Impacto e Severidade',
+  'Causa Raiz',
+  'Escopo do Fix',
+  'Teste de Regressão',
+];
+
 export const REQUIRED_PLAN_SECTIONS = [
   'Estratégia Técnica',
   'Detalhamento da Implementação',

package/src/lib/bug-context.mjs

@@ -0,0 +1,160 @@
+// Contexto de implementação de um Bug (RFC-004 §7.1) — puro, testável.
+//
+// A diferença para o contexto de Story não é o formato, é a ORDEM DO TRABALHO.
+// Uma Story tem tasks a executar; um Bug tem um defeito a entender antes de
+// tocar em qualquer coisa. Por isso o contexto impõe quatro fases —
+// reproduzir → causa raiz → fix mínimo → teste de regressão — e a primeira
+// entrega é um teste que FALHA.
+//
+// A ordem existe porque a alternativa é o modo de falha clássico da correção
+// assistida: o executor lê o sintoma, encontra o lugar onde ele se manifesta,
+// remenda ali, e o defeito reaparece na próxima entrada.
+
+import { STAGE_DEVELOPMENT, STAGE_CODE_REVIEW, PROGRESS_IN_PROGRESS } from '../config.mjs';
+
+/**
+ * Monta o markdown do contexto de um Bug (função PURA).
+ *
+ * @param {object} params
+ * @param {{number:number,title:string,body?:string}} params.bug
+ * @param {string|null} [params.bugDoc] conteúdo de docs/bugs/<slug>/bug.md
+ * @param {{number:number,title:string,kind:string}|null} [params.parent]
+ * @param {Array} [params.comments] grupos de comentários (mesmo shape do implement)
+ * @param {string|null} [params.codeDigest]
+ * @param {string[]} [params.blockedByWarnings]
+ * @param {string|null} [params.severity] P0–P3
+ * @returns {string}
+ */
+export function buildBugContext({
+  bug, bugDoc = null, parent = null, comments = [], codeDigest = null,
+  blockedByWarnings = [], severity = null,
+}) {
+  const lines = [];
+  lines.push(`# Contexto de correção — Bug #${bug.number}`);
+  lines.push('');
+  lines.push(`**Bug:** ${bug.title}`);
+  if (severity) lines.push(`**Severidade:** ${severity}`);
+  if (parent) {
+    lines.push(`**Item afetado:** ${parent.kind} #${parent.number} — ${parent.title}`);
+  }
+
+  if (bug.body && bug.body.trim()) {
+    lines.push('');
+    lines.push('## Relato original');
+    lines.push('');
+    lines.push(bug.body.trim());
+  }
+
+  if (blockedByWarnings.length > 0) {
+    lines.push('');
+    lines.push('## ⚠️ Dependências declaradas');
+    for (const w of blockedByWarnings) lines.push(`- ${w}`);
+  }
+
+  lines.push('');
+  lines.push('## Como corrigir (quatro fases, nesta ordem)');
+  lines.push('');
+  lines.push(
+    '> **Não comece pelo fix.** O modo de falha desta tarefa é encontrar o lugar onde o ' +
+    'sintoma aparece, remendar ali, e o defeito voltar na próxima entrada. As fases 1 e 2 ' +
+    'existem para impedir isso.'
+  );
+  lines.push('');
+  lines.push('### 1. Reproduzir');
+  lines.push('');
+  lines.push(
+    'Escreva um teste que **falha** por causa deste defeito, seguindo os passos de reprodução. ' +
+    'Rode-o e confirme que falha **pelo motivo certo** — um teste que falha por erro de ' +
+    'digitação no próprio teste não reproduz nada. Se não conseguir reproduzir, **pare e ' +
+    'reporte**: sem reprodução não há como provar que a correção funcionou.'
+  );
+  lines.push('');
+  lines.push('### 2. Causa raiz');
+  lines.push('');
+  lines.push(
+    'Investigue até a **origem**, não até o lugar onde o erro se manifesta. Um valor nulo ' +
+    'que estoura numa função raramente nasceu ali. Cite arquivo e função. Se o `bug.md` já ' +
+    'traz uma causa raiz, **confirme-a contra o código** antes de aceitar — ela foi escrita ' +
+    'por outro modelo, sem executar nada.'
+  );
+  lines.push('');
+  lines.push('### 3. Fix mínimo');
+  lines.push('');
+  lines.push(
+    'Corrija a causa raiz e **apenas ela**. Um bug é o convite mais comum para refatoração ' +
+    'oportunista: se você vir outros problemas no caminho, **anote-os no comentário final ' +
+    'em vez de corrigi-los** — cada mudança extra aumenta o risco de uma correção que ' +
+    'precisava ser cirúrgica.'
+  );
+  lines.push('');
+  lines.push('### 4. Teste de regressão');
+  lines.push('');
+  lines.push(
+    'O teste da fase 1 agora **passa**. Garanta que ele fica no repositório e que **falharia ' +
+    'de novo** se o fix fosse revertido — essa é a única prova de que ele testa o defeito, e ' +
+    'não outra coisa. Rode a suíte inteira: um fix que quebra outro teste não está pronto.'
+  );
+
+  lines.push('');
+  lines.push('## Ao terminar');
+  lines.push('');
+  lines.push(
+    `1. Commit com a **causa raiz** na mensagem: \`fix: <o que estava errado> (#${bug.number})\`, ` +
+    'e o corpo explicando a origem — não o sintoma.'
+  );
+  lines.push(`2. Abra o Pull Request com \`Fixes #${bug.number}\` no corpo.`);
+  lines.push(
+    `3. O board move sozinho: o Bug sai de **${STAGE_DEVELOPMENT}** (${PROGRESS_IN_PROGRESS}) ` +
+    `para **${STAGE_CODE_REVIEW}** quando o PR abre. Não mova à mão.`
+  );
+
+  if (bugDoc && bugDoc.trim()) {
+    lines.push('');
+    lines.push('---');
+    lines.push('');
+    lines.push('## bug.md — investigação já registrada');
+    lines.push('');
+    lines.push(
+      '> Escrito por IA **sem executar código**. Trate a causa raiz como hipótese a confirmar, ' +
+      'não como fato.'
+    );
+    lines.push('');
+    lines.push(bugDoc.trim());
+  } else {
+    lines.push('');
+    lines.push('---');
+    lines.push('');
+    lines.push(
+      '> **Sem `bug.md`.** A investigação inteira é sua: o relato acima e os comentários são ' +
+      'tudo o que existe.'
+    );
+  }
+
+  if (comments && comments.length > 0) {
+    lines.push('');
+    lines.push('## Comentários da issue');
+    lines.push('');
+    lines.push(
+      '> É onde costuma estar o que faltava no relato original — passos extras, ambiente, ' +
+      'e o retorno de quem reportou. Em conflito, o comentário mais recente prevalece.'
+    );
+    for (const group of comments) {
+      for (const c of group.items || []) {
+        lines.push('');
+        lines.push(`**${c.author || 'desconhecido'}** (${c.createdAt}):`);
+        lines.push('');
+        lines.push(String(c.body || '').trim());
+      }
+    }
+  }
+
+  if (codeDigest) {
+    lines.push('');
+    lines.push('## Digest do código');
+    lines.push('');
+    lines.push(codeDigest);
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}

package/src/lib/bug-doc.mjs

@@ -0,0 +1,51 @@
+// Caminhos e checagem estrutural do bug.md — o artefato do Bug (RFC-004 §5).
+//
+// Fica fora de docs/features/ de propósito: um Bug NÃO é uma Feature e não gera
+// spec.md/plan.md. Manter os dois na mesma pasta faria o `validate` e o
+// `resolveFeaturePaths` da UI tropeçarem num diretório sem os arquivos que
+// esperam.
+//
+// Decisão em função pura, I/O no comando — nada aqui toca o filesystem.
+import path from 'node:path';
+import { slugify } from './slugify.mjs';
+
+/**
+ * Caminhos do bug.md a partir do título da issue (função PURA).
+ *
+ * Devolve o relativo (links, mensagem de commit) e o absoluto ancorado na raiz
+ * do repositório (fs) — o config é procurado subindo na árvore, e os documentos
+ * moram junto dele.
+ *
+ * @param {string} title título da issue (com ou sem o prefixo [BUG])
+ * @param {string} [root] raiz do repositório; ausente = process.cwd()
+ * @returns {{ slug: string, dirRel: string, fileRel: string, dirAbs: string, fileAbs: string }}
+ */
+export function bugDocPaths(title, root = null) {
+  const slug = slugify(title);
+  const dirRel = `docs/bugs/${slug}`;
+  const fileRel = `${dirRel}/bug.md`;
+  const base = root || process.cwd();
+  return {
+    slug,
+    dirRel,
+    fileRel,
+    dirAbs: path.resolve(base, dirRel),
+    fileAbs: path.resolve(base, fileRel),
+  };
+}
+
+/**
+ * Seções obrigatórias ausentes de um documento (função PURA).
+ *
+ * Extraída da duplicação que existia em validate.mjs (um laço idêntico para
+ * spec.md e outro para plan.md). Casa por `# <seção>`, o que aceita qualquer
+ * nível de heading (`##`, `###`) — a checagem é de PRESENÇA, não de hierarquia.
+ *
+ * @param {string} content conteúdo do documento
+ * @param {string[]} sections títulos obrigatórios
+ * @returns {string[]} os que faltam, na ordem declarada
+ */
+export function findMissingSections(content, sections) {
+  const text = String(content || '');
+  return (sections || []).filter(section => !text.includes(`# ${section}`));
+}

package/src/lib/bug-triage.mjs

@@ -0,0 +1,81 @@
+// Decisões da triagem de Bug (RFC-004 §4.1) — puras, testáveis, sem I/O.
+//
+// O portão que estas funções guardam: P2/P3 só entram na fila técnica com o
+// bug.md aprovado. A razão não é burocracia — é que um bug sem causa raiz
+// investigada consome o tempo do dev na investigação que a triagem deveria ter
+// feito, e é aí que "corrigir o sintoma" acontece. P0/P1 são exceção porque
+// esperar o documento custa mais que investigar durante a correção.
+
+import { LABEL_BUG_APPROVED, LABEL_NEEDS_HUMAN, LABEL_CRITIQUE_FAILED } from '../config.mjs';
+
+export const TRIAGE_ACTIONS = ['accept', 'reject', 'duplicate'];
+
+// Severidades que dispensam o bug.md antes da fila.
+const SEVERITY_WITHOUT_DOC = ['P0', 'P1'];
+
+/**
+ * Resolve a ação de triagem informada (função PURA).
+ *
+ * Mesmo contrato de resolveStageName/resolveProgressName: devolve
+ * `{action, error}` em vez de lançar.
+ *
+ * @param {string} input
+ * @returns {{ action: string|null, error: string|null }}
+ */
+export function resolveTriageAction(input) {
+  const key = String(input ?? '').trim().toLowerCase();
+  if (!key) {
+    return { action: null, error: `Informe a ação: ${TRIAGE_ACTIONS.join(', ')}.` };
+  }
+  const match = TRIAGE_ACTIONS.find(a => a === key);
+  return match
+    ? { action: match, error: null }
+    : {
+        action: null,
+        error: `Ação "${input}" não existe. Use uma de: ${TRIAGE_ACTIONS.join(', ')}.`,
+      };
+}
+
+/**
+ * O bug pode ser aceito na fila técnica? (função PURA)
+ *
+ * @param {object} params
+ * @param {string|null} params.severity P0–P3
+ * @param {string[]} params.labels labels da issue
+ * @returns {{ ok: boolean, error: string|null }}
+ */
+export function canAcceptBug({ severity = null, labels = [] } = {}) {
+  const names = labels || [];
+
+  // Portões humanos da crítica valem para qualquer severidade: aceitar um bug
+  // cujo documento foi reprovado é justamente o que o portão existe para evitar.
+  if (names.includes(LABEL_NEEDS_HUMAN)) {
+    return {
+      ok: false,
+      error:
+        `A crítica reprovou repetidas vezes e \`${LABEL_NEEDS_HUMAN}\` está aplicada. ` +
+        'Revise o bug.md e remova a label antes de aceitar.',
+    };
+  }
+  if (names.includes(LABEL_CRITIQUE_FAILED)) {
+    return {
+      ok: false,
+      error:
+        `A crítica adversarial apontou problemas graves (\`${LABEL_CRITIQUE_FAILED}\`). ` +
+        'Corrija o bug.md e remova a label antes de aceitar.',
+    };
+  }
+
+  if (SEVERITY_WITHOUT_DOC.includes(severity)) return { ok: true, error: null };
+
+  if (!names.includes(LABEL_BUG_APPROVED)) {
+    return {
+      ok: false,
+      error:
+        `Bug ${severity || 'sem severidade'} exige o bug.md validado antes da fila técnica. ` +
+        'Aplique `spec-wave:bug` para gerá-lo e `spec-wave:ready` para validá-lo — ' +
+        'ou reclassifique a severidade com --severity se for urgente.',
+    };
+  }
+  return { ok: true, error: null };
+}