@spec-wave/cli 0.15.0 → 0.16.0

package/src/commands/triage.mjs

@@ -0,0 +1,174 @@
+// Triagem de Bug pela CLI (RFC-004 §4.1) — o mesmo desfecho que a tela do PM
+// oferece, para quem trabalha no terminal ou automatiza.
+//
+// Três saídas, e nenhuma delas é "editar": aceitar (→ ✅ Ready), rejeitar
+// (fecha) e duplicar (fecha, apontando a original). Corrigir o relato é
+// conversa na issue.
+//
+// Rejeitar e duplicar NÃO mexem na Etapa: ela nunca retrocede, e um bug
+// rejeitado não avançou para lugar nenhum — quem o tira das filas é o estado
+// `closed` da issue.
+import * as p from '@clack/prompts';
+import chalk from 'chalk';
+import { resolveToken } from '../api/auth.mjs';
+import {
+  getIssue, addLabel, removeLabel, commentOnIssue, setIssueState,
+} from '../api/github-rest.mjs';
+import { detectIssueType } from '../lib/issue-type.mjs';
+import { loadProjectConfig, resolveField, advanceToStage } from '../lib/board.mjs';
+import { loadConfig } from '../lib/project-root.mjs';
+import { resolveTriageAction, canAcceptBug } from '../lib/bug-triage.mjs';
+import {
+  CONFIG_FILE, STAGE_READY, PROGRESS_TODO, PRIORITY_LABELS,
+  LABEL_TRIAGED, LABEL_DUPLICATE, LABEL_WONT_FIX, labelNames,
+} from '../config.mjs';
+
+const PRIORITIES = PRIORITY_LABELS.map(l => l.name);
+
+export async function triage({ action: actionArg, issue: issueArg, reason, of, severity }) {
+  const { action, error: actionError } = resolveTriageAction(actionArg);
+  if (actionError) {
+    p.log.error(actionError);
+    process.exitCode = 1;
+    return;
+  }
+
+  const issueNumber = parseInt(String(issueArg).replace('#', ''), 10);
+  if (!Number.isInteger(issueNumber) || issueNumber <= 0) {
+    p.log.error(`Issue inválida: "${issueArg}". Use o número da issue, ex.: 42 ou #42.`);
+    process.exitCode = 1;
+    return;
+  }
+  if (severity && !PRIORITIES.includes(severity)) {
+    p.log.error(`Severidade inválida: ${severity}. Use uma de: ${PRIORITIES.join(', ')}.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const [envOwner, envRepo] = (process.env.GITHUB_REPOSITORY || '').split('/');
+  const { config, root } = loadConfig();
+  const owner = envOwner || config?.owner;
+  const repo = envRepo || config?.repo;
+  if (!owner || !repo) {
+    p.log.error(
+      'Não foi possível determinar owner/repo.\n' +
+      `Rode dentro de um repositório com ${CONFIG_FILE} ou defina GITHUB_REPOSITORY=owner/repo.`
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  let token;
+  try {
+    token = await resolveToken();
+  } catch (err) {
+    p.log.error(err.message);
+    process.exitCode = 1;
+    return;
+  }
+
+  p.intro(chalk.bold(`spec-wave triage ${action} #${issueNumber}`));
+
+  let issue;
+  try {
+    issue = await getIssue(token, owner, repo, issueNumber);
+  } catch (err) {
+    p.log.error(`Não foi possível ler a issue #${issueNumber}: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (detectIssueType(issue) !== 'Bug') {
+    p.log.error(`#${issueNumber} não é um Bug — a triagem só se aplica a defeitos.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const labels = labelNames(issue);
+  const severidadeAtual = severity || labels.find(n => PRIORITIES.includes(n)) || null;
+
+  if (action === 'accept') {
+    const { ok, error } = canAcceptBug({ severity: severidadeAtual, labels });
+    if (!ok) {
+      p.log.error(error);
+      process.exitCode = 1;
+      return;
+    }
+
+    // Reclassificação: troca a label em vez de acumular. Duas prioridades na
+    // mesma issue tornam a ordem da fila indefinida.
+    if (severity) {
+      for (const outra of PRIORITIES) {
+        if (outra !== severity) await removeLabel(token, owner, repo, issueNumber, outra).catch(() => {});
+      }
+      await addLabel(token, owner, repo, issueNumber, severity);
+      p.log.info(`Severidade → ${severity}.`);
+    }
+
+    await addLabel(token, owner, repo, issueNumber, LABEL_TRIAGED);
+    await commentOnIssue(token, owner, repo, issueNumber,
+      '**Triado:** aceito para a fila técnica.').catch(() => {});
+    await moveToReady({ token, issueNumber, issue, root });
+
+    p.outro(`${chalk.green('✓')} Bug #${issueNumber} aceito → ${STAGE_READY}.`);
+    return;
+  }
+
+  if (action === 'reject') {
+    if (!reason || !reason.trim()) {
+      p.log.error('Rejeitar exige --reason "<motivo>".');
+      process.exitCode = 1;
+      return;
+    }
+    await addLabel(token, owner, repo, issueNumber, LABEL_WONT_FIX);
+    await addLabel(token, owner, repo, issueNumber, LABEL_TRIAGED);
+    await commentOnIssue(token, owner, repo, issueNumber,
+      `**Rejeitado na triagem:** ${reason.trim()}`).catch(() => {});
+    await setIssueState(token, owner, repo, issueNumber, 'closed');
+    p.outro(`${chalk.green('✓')} Bug #${issueNumber} rejeitado e fechado.`);
+    return;
+  }
+
+  // duplicate
+  const original = parseInt(String(of || '').replace('#', ''), 10);
+  if (!Number.isInteger(original) || original <= 0) {
+    p.log.error('Marcar como duplicata exige --of <número da issue original>.');
+    process.exitCode = 1;
+    return;
+  }
+  if (original === issueNumber) {
+    p.log.error('Uma issue não pode ser duplicata de si mesma.');
+    process.exitCode = 1;
+    return;
+  }
+
+  await addLabel(token, owner, repo, issueNumber, LABEL_DUPLICATE);
+  await addLabel(token, owner, repo, issueNumber, LABEL_TRIAGED);
+  await commentOnIssue(token, owner, repo, issueNumber, `**Duplicata de #${original}.**`).catch(() => {});
+  // Comentar também na original: sem isso, quem acompanha #original não fica
+  // sabendo que há outro relato do mesmo defeito — e o contexto extra está lá.
+  await commentOnIssue(token, owner, repo, original,
+    `#${issueNumber} foi marcada como duplicata desta issue.`).catch(() => {});
+  await setIssueState(token, owner, repo, issueNumber, 'closed');
+
+  p.outro(`${chalk.green('✓')} Bug #${issueNumber} marcado como duplicata de #${original} e fechado.`);
+}
+
+async function moveToReady({ token, issueNumber, issue, root }) {
+  const { project, error } = loadProjectConfig({ cwd: root || process.cwd() });
+  if (error) {
+    p.log.warn(`${error} — board não atualizado.`);
+    return;
+  }
+  try {
+    const etapaField = await resolveField(token, project, 'Etapa').catch(() => null);
+    const statusField = await resolveField(token, project, 'Status').catch(() => null);
+    const moved = await advanceToStage(
+      token, project, etapaField, statusField, issue.node_id, STAGE_READY, PROGRESS_TODO);
+    if (!moved) {
+      p.log.info(`#${issueNumber} já está em ${STAGE_READY} ou etapa posterior — mantido.`);
+    }
+  } catch (err) {
+    p.log.warn(`Falha ao mover no board: ${err.message}`);
+  }
+}

package/src/commands/update.mjs

@@ -20,8 +20,9 @@ import {
 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).
@@ -39,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;

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).

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',