@spec-wave/cli 0.29.0 → 0.32.0

package/src/commands/qa-run.mjs

@@ -0,0 +1,892 @@
+// Execução LOCAL do plano de QA — `spec-wave qa <issue>` (spec rfc/spec-qa-skill.md).
+//
+// D-QA2: a geração do plano é label + Action (generate-qa-plan); a EXECUÇÃO é
+// sempre local — QA de verdade roda contra um checkout. O comando monta o
+// contexto em `.spec-wave/qa-<n>.md`, aciona o executor configurado em
+// `qa.command` (mesmo padrão do `implement`/specKit) e lê o veredito do arquivo
+// de resultados que o executor grava.
+//
+// D-QA3/D-QA4: o veredito VERDE avança a Etapa sozinho — por isso o portão
+// humano fica antes, na revisão do plano (`spec-wave:qa-ready`), e os portões
+// de execução (lib/qa-exec.mjs) recusam tudo que tornaria o verde automático
+// perigoso.
+
+import { execSync } from 'node:child_process';
+import { existsSync, mkdirSync, writeFileSync, readFileSync, unlinkSync } from 'node:fs';
+import path from 'node:path';
+import chalk from 'chalk';
+
+import { resolveToken } from '../api/auth.mjs';
+import {
+  getIssue, createIssue, addLabel, commentOnIssue, listIssueComments,
+} from '../api/github-rest.mjs';
+import {
+  getIssueParent, listSubIssues, listIssuePullRequests, addSubIssue,
+  addProjectItem, getItemSingleSelectValue, setItemSingleSelect,
+} from '../api/github-graphql.mjs';
+import { detectIssueType } from '../lib/issue-type.mjs';
+import { loadConfig, findConfigPath } from '../lib/project-root.mjs';
+import { loadProjectConfig, resolveField, advanceToStage, setItemStatus } from '../lib/board.mjs';
+import { loadArtifact, isAwaitingMerge } from '../lib/doc-source.mjs';
+import { awaitingMergeBlock } from '../lib/artifact-pr.mjs';
+import { featureDocPaths, bugDocPaths } from '../lib/doc-paths.mjs';
+import { parseQaPlanDoc, resolveTargetScenarios } from '../lib/qa-plan-doc.mjs';
+import {
+  qaExecutionGate, greenTargetStage, storyCanAdvance, featureCanAdvanceQa,
+  extractRegressionSection, renderQaCommand, buildQaContext, qaProcessEnv,
+} from '../lib/qa-exec.mjs';
+import { pushWithRebase } from '../lib/git-retry.mjs';
+import {
+  aggregateVerdict, validateQaResults, combineWithPrevious, parseLastQaReport,
+  renderQaReport, renderQaBugDoc, qaOriginMarker, matchesQaOrigin, shortSha,
+} from '../lib/qa-report.mjs';
+import {
+  CONFIG_FILE, STAGE_QA, STAGE_UAT, STAGE_READY, PROGRESS_TODO, PROGRESS_IN_PROGRESS,
+  LABEL_QA_APPROVED, LABEL_BUG_APPROVED, PRIORITY_LABELS, bugOriginLabel, labelNames,
+} from '../config.mjs';
+
+const WORK_DIR = '.spec-wave';
+const MAX_COMMENTS = 15;
+const MAX_COMMENT_CHARS = 2000;
+const VALID_SEVERITIES = PRIORITY_LABELS.map(l => l.name);
+
+// Recusa "esperada": mensagem para o usuário, exit 1, sem stack trace.
+class QaRefusal extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'QaRefusal';
+  }
+}
+
+async function resolveParentFeature(token, startNodeId) {
+  let current = startNodeId;
+  for (let depth = 0; depth < 5 && current; depth++) {
+    const parent = await getIssueParent(token, current);
+    if (!parent) return null;
+    if (detectIssueType({ title: parent.title }) === 'Feature') return parent;
+    current = parent.nodeId;
+  }
+  return null;
+}
+
+// Campos do board, resolvidos uma vez. Best-effort: sem board, os movimentos
+// viram avisos (o veredito e o relatório não dependem dele).
+async function resolveBoard(root, projectToken) {
+  const { project, error } = loadProjectConfig({ cwd: root || process.cwd() });
+  if (error || !project?.id) {
+    return { project: null, error: error || 'Project não configurado', etapaField: null, statusField: null, typeField: null };
+  }
+  const etapaField = await resolveField(projectToken, project, 'Etapa').catch(() => null);
+  const statusField = await resolveField(projectToken, project, 'Status').catch(() => null);
+  const typeField = await resolveField(projectToken, project, 'Work Item Type').catch(() => null);
+  const priorityField = await resolveField(projectToken, project, 'Priority').catch(() => null);
+  return { project, error: null, etapaField, statusField, typeField, priorityField };
+}
+
+async function readStage(projectToken, board, nodeId) {
+  if (!board.project || !board.etapaField?.id) return null;
+  try {
+    const itemId = await addProjectItem(projectToken, board.project.id, nodeId);
+    return await getItemSingleSelectValue(projectToken, itemId, board.etapaField.id);
+  } catch {
+    return null;
+  }
+}
+
+function headShaOf(root) {
+  try {
+    return execSync('git rev-parse --short HEAD', {
+      cwd: root || process.cwd(), encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+// Commit LOCAL escopado ao arquivo — o `qa` roda no checkout do usuário, e o
+// bug.md de reprovação é conteúdo determinístico produzido aqui mesmo. Nunca
+// varre o index: `git commit -- <path>` só leva o que este comando escreveu.
+function commitLocalFile(root, fileRel, message) {
+  const cwd = root || process.cwd();
+  try {
+    execSync(`git add -- ${JSON.stringify(fileRel)}`, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+    execSync(`git commit -m ${JSON.stringify(message)} -- ${JSON.stringify(fileRel)}`, {
+      cwd, stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return true;
+  } catch (err) {
+    console.warn(chalk.yellow(
+      `⚠️  ${fileRel} escrito, mas o commit local falhou (${String(err.message).split('\n')[0]}) — ` +
+      'commite-o você mesmo.'
+    ));
+    return false;
+  }
+}
+
+function parseOnly(only) {
+  if (!only) return null;
+  const nums = String(only).split(',').map(s => parseInt(s.trim(), 10));
+  if (nums.some(n => !Number.isInteger(n) || n <= 0)) {
+    throw new QaRefusal(`--only inválido: "${only}". Use números de cenário, ex.: --only 2 ou --only 2,3.`);
+  }
+  return [...new Set(nums)];
+}
+
+async function trimmedComments(token, owner, repo, issueNumber, kind) {
+  const all = await listIssueComments(token, owner, repo, issueNumber).catch(() => []);
+  if (all.length === 0) return { all, groups: [] };
+  const items = all.slice(-MAX_COMMENTS).map(c => ({
+    author: c.user?.login,
+    createdAt: c.created_at,
+    body: c.body.length > MAX_COMMENT_CHARS ? `${c.body.slice(0, MAX_COMMENT_CHARS)}…[truncado]` : c.body,
+  }));
+  return { all, groups: [{ issueNumber, kind, total: all.length, items }] };
+}
+
+export async function qaRun({ issue: issueArg, only: onlyArg, severity: severityArg, dryRun = false }) {
+  const number = parseInt(String(issueArg).replace('#', ''), 10);
+  if (!Number.isInteger(number) || number <= 0) {
+    throw new QaRefusal(`Issue inválida: "${issueArg}". Use o número da issue, ex.: 12 ou #12.`);
+  }
+  const only = parseOnly(onlyArg);
+
+  // Guarda 1: sem .spec-wave.json não há repo configurado.
+  const configPath = findConfigPath();
+  if (!configPath) {
+    throw new QaRefusal(
+      `Repositório não inicializado (sem ${CONFIG_FILE}). ` +
+      'Rode `npx @spec-wave/cli@latest init` (ou a skill setup) primeiro.'
+    );
+  }
+  const { config, root } = loadConfig();
+  const { owner, repo } = config || {};
+  if (!owner || !repo) {
+    throw new QaRefusal(`${CONFIG_FILE} não contém owner/repo. Rode \`spec-wave init\` novamente.`);
+  }
+
+  const severity = severityArg || config?.qa?.defaultBugPriority || 'P2';
+  if (!VALID_SEVERITIES.includes(severity)) {
+    throw new QaRefusal(`Severidade inválida: "${severity}". Use uma de: ${VALID_SEVERITIES.join(', ')}.`);
+  }
+
+  const token = await resolveToken();
+  const projectToken = process.env.PROJECT_TOKEN || token;
+
+  const issue = await getIssue(token, owner, repo, number);
+  const type = detectIssueType(issue);
+
+  // ── Feature dona do plano (Feature/Story) ──────────────────────────────────
+  let feature = null; // { number, title, nodeId, labels, milestone }
+  if (type === 'Feature') {
+    feature = {
+      number, title: issue.title, nodeId: issue.node_id,
+      labels: labelNames(issue), milestone: issue.milestone || null,
+    };
+  } else if (type === 'Story') {
+    const parent = await resolveParentFeature(token, issue.node_id).catch(() => null);
+    if (!parent) {
+      throw new QaRefusal(
+        `A Story #${number} não tem Feature-pai — o plano de QA é por Feature (D-QA1), ` +
+        'e sem ela não há plano a executar. Vincule a Story como sub-issue de uma Feature.'
+      );
+    }
+    const parentIssue = await getIssue(token, owner, repo, parent.number);
+    feature = {
+      number: parent.number, title: parentIssue.title, nodeId: parentIssue.node_id,
+      labels: labelNames(parentIssue), milestone: parentIssue.milestone || null,
+    };
+  }
+
+  // ── Etapa no board. Pulada no dry-run: a leitura passa por addProjectItem,
+  // que é mutação, e o dry-run promete ZERO escrita no GitHub. ────────────────
+  const board = dryRun
+    ? { project: null, error: 'dry-run', etapaField: null, statusField: null, typeField: null }
+    : await resolveBoard(root, projectToken);
+  let stage = null;
+  if (!dryRun) {
+    if (board.error) console.warn(chalk.yellow(`⚠️  ${board.error} — Etapa não verificada e board não será atualizado.`));
+    else stage = await readStage(projectToken, board, issue.node_id);
+  } else {
+    console.log(chalk.dim('Dry-run: Etapa do board não consultada (a leitura adicionaria o item ao Project).'));
+  }
+
+  // ── Portões (lib/qa-exec.mjs — tabela do spec §6.2) ────────────────────────
+  const gate = qaExecutionGate({
+    type,
+    labels: labelNames(issue),
+    featureLabels: type === 'Bug' ? null : feature.labels,
+    stage,
+  });
+  if (!gate.ok) throw new QaRefusal(gate.message);
+  if (gate.exitZero) {
+    console.log(gate.message);
+    return { verdict: null, skipped: true };
+  }
+
+  // ── Cenários-alvo ──────────────────────────────────────────────────────────
+  let scenarios;         // todos os cenários do ESCOPO (antes do --only)
+  let targets;           // os que serão executados nesta corrida
+  let planContent;       // conteúdo cujo sha vai no marcador
+  let qaPlanRel = null;
+  let specRel = null;
+  let featureStories = []; // Stories da Feature (modo Feature — o verde as aprova uma a uma)
+
+  if (type === 'Bug') {
+    const { fileRel, fileAbs } = bugDocPaths(issue.title, root);
+    qaPlanRel = fileRel;
+    if (!existsSync(fileAbs)) {
+      const achado = await loadArtifact({
+        token, owner, repo, root, pathRel: fileRel, doc: 'bug', issueNumber: number,
+      }).catch(() => null);
+      if (achado && isAwaitingMerge(achado.state)) {
+        const b = awaitingMergeBlock({ pathRel: fileRel, state: achado.state, pr: achado.pr, branch: achado.ref });
+        throw new QaRefusal(`${b.message}\n${b.unblock}`);
+      }
+      if (achado?.state === 'remote') {
+        throw new QaRefusal(`\`${fileRel}\` existe no repositório mas não no seu clone — rode \`git pull\` e repita.`);
+      }
+      throw new QaRefusal(
+        `\`${fileRel}\` não encontrado. O slug vem do TÍTULO da issue: se o Bug foi renomeado ` +
+        `depois de gerar o bug.md, o diretório antigo ficou órfão — procure em docs/bugs/ e ` +
+        'renomeie o diretório para o slug atual (ou regenere com `spec-wave:bug`).'
+      );
+    }
+    planContent = readFileSync(fileAbs, 'utf-8');
+    const regressao = extractRegressionSection(planContent);
+    if (!regressao) {
+      throw new QaRefusal(
+        `O \`${fileRel}\` não tem a seção **Teste de Regressão** (ou ela está vazia) — ` +
+        'é ela que o `qa <bug>` executa. Complete a seção ou regenere o bug.md.'
+      );
+    }
+    scenarios = [{
+      anchor: 'Cenário 1', numero: 1, story: number,
+      criterio: `Teste de regressão do Bug #${number}`,
+      precondicoes: '', passos: '', esperado: 'O teste de regressão passa',
+      body: regressao,
+    }];
+    targets = only ? scenarios.filter(s => only.includes(s.numero)) : scenarios;
+    if (targets.length === 0) {
+      throw new QaRefusal(`--only ${onlyArg}: o Teste de Regressão de um Bug é o cenário 1.`);
+    }
+  } else {
+    const paths = featureDocPaths(root, { title: feature.title }, 'Feature');
+    qaPlanRel = paths['qa-plan'].rel;
+    specRel = paths.spec.rel;
+    const plano = await loadArtifact({
+      token, owner, repo, root, pathRel: qaPlanRel, doc: 'qa-plan', issueNumber: feature.number,
+    }).catch(() => null);
+    if (!plano || plano.content == null || plano.state === 'unknown') {
+      // `qa-ready` está na Feature (o portão passou), então o plano EXISTE em
+      // algum lugar — arquivo ausente aqui é quase sempre slug órfão.
+      throw new QaRefusal(
+        `\`${qaPlanRel}\` não encontrado, mas a Feature #${feature.number} tem \`spec-wave:qa-ready\` — ` +
+        'o plano foi gerado. O slug vem do TÍTULO: se a Feature foi renomeada depois da geração, ' +
+        'o diretório antigo ficou órfão. Procure o qa-plan.md em docs/features/ e renomeie o ' +
+        'diretório para o slug atual (ou apague-o e reaplique `spec-wave:qa`).'
+      );
+    }
+    if (isAwaitingMerge(plano.state)) {
+      const b = awaitingMergeBlock({ pathRel: qaPlanRel, state: plano.state, pr: plano.pr, branch: plano.ref });
+      throw new QaRefusal(
+        `${b.message}\n${b.unblock}\n` +
+        'O merge do PR é a revisão humana do plano — o `qa` só executa o que está na base.'
+      );
+    }
+    if (plano.state === 'remote') {
+      throw new QaRefusal(`\`${qaPlanRel}\` existe no repositório mas não no seu clone — rode \`git pull\` e repita.`);
+    }
+    planContent = plano.content;
+
+    let doc;
+    try {
+      doc = parseQaPlanDoc(planContent);
+    } catch (err) {
+      throw new QaRefusal(`${err.message}\nCorrija \`${qaPlanRel}\` (ou reaplique \`spec-wave:qa\` para re-criticar).`);
+    }
+    if (doc.issueNumber && doc.issueNumber !== feature.number) {
+      console.warn(chalk.yellow(
+        `⚠️  ${qaPlanRel} foi gerado para a issue #${doc.issueNumber}, não a #${feature.number} ` +
+        '(a Feature foi retitulada?). Seguindo com o arquivo encontrado.'
+      ));
+    }
+
+    // Stories já aprovadas saem do alvo no modo Feature.
+    let subStories = [];
+    try {
+      subStories = (await listSubIssues(token, feature.nodeId))
+        .filter(s => detectIssueType({ title: s.title, labels: s.labels }) === 'Story');
+    } catch (err) {
+      console.warn(chalk.yellow(`⚠️  Não foi possível listar as Stories da Feature: ${err.message}.`));
+    }
+    const approvedStories = subStories
+      .filter(s => (s.labels || []).includes(LABEL_QA_APPROVED))
+      .map(s => s.number);
+
+    const resolved = resolveTargetScenarios({
+      doc,
+      story: type === 'Story' ? number : null,
+      approvedStories,
+      only,
+    });
+    if (resolved.unknownOnly.length > 0) {
+      throw new QaRefusal(
+        `--only ${onlyArg}: cenário(s) ${resolved.unknownOnly.join(', ')} não existe(m) no escopo. ` +
+        `O plano tem ${doc.scenarios.length} cenário(s) — a numeração é POSICIONAL (a ordem do arquivo).`
+      );
+    }
+    // Escopo = cenários da corrida ANTES do --only; é sobre ele que a aprovação
+    // é decidida (cenário fora do --only herda o veredito do último relatório).
+    scenarios = resolveTargetScenarios({
+      doc, story: type === 'Story' ? number : null, approvedStories, only: null,
+    }).targets;
+    targets = resolved.targets;
+
+    if (scenarios.length === 0) {
+      if (type === 'Story') {
+        throw new QaRefusal(
+          `Nenhum cenário do plano casa com a Story #${number}. Ou o plano está DESATUALIZADO ` +
+          '(um re-decompose criou Stories novas — apague o qa-plan.md e reaplique `spec-wave:qa`), ' +
+          'ou a Feature foi renomeada e você está lendo um plano órfão de outro slug.'
+        );
+      }
+      console.log('Todas as Stories desta Feature já têm `spec-wave:qa-approved` — nada a executar.');
+      return { verdict: 'pass', skipped: true };
+    }
+    featureStories = subStories;
+  }
+
+  // ── Estado anterior (relatórios) e contexto ────────────────────────────────
+  const { all: allComments, groups: commentGroups } =
+    await trimmedComments(token, owner, repo, number, type);
+  const previous = parseLastQaReport(allComments);
+  const run = previous.run + 1;
+
+  const pullRequests = await listIssuePullRequests(token, issue.node_id).catch(() => []);
+
+  mkdirSync(path.join(root || process.cwd(), WORK_DIR), { recursive: true });
+  const contextFile = path.join(WORK_DIR, `qa-${number}.md`);
+  const resultFile = path.join(WORK_DIR, `qa-result-${number}.json`);
+  const contextAbs = path.join(root || process.cwd(), contextFile);
+  const resultAbs = path.join(root || process.cwd(), resultFile);
+
+  const context = buildQaContext({
+    type, issue: { number, title: issue.title }, stage,
+    scenarios: targets, specRel, qaPlanRel,
+    comments: commentGroups, pullRequests,
+    setup: config?.qa?.setup || null,
+    resultFile,
+  });
+  writeFileSync(contextAbs, context);
+  if (existsSync(resultAbs)) unlinkSync(resultAbs); // resultado velho não pode virar veredito novo
+
+  const template = process.env.SPEC_WAVE_QA_CMD || config?.qa?.command;
+  const vars = {
+    contextFile,
+    qaPlanFile: qaPlanRel || '',
+    specFile: specRel || '',
+    issue: String(number),
+    type,
+    title: issue.title,
+  };
+
+  console.log(`Contexto montado em ${chalk.cyan(contextFile)} (${targets.length} cenário(s) alvo).`);
+  for (const s of targets) {
+    console.log(`  - ${s.anchor} — Story #${s.story}${s.criterio ? `: ${s.criterio}` : ''}`);
+  }
+
+  if (dryRun) {
+    if (template) {
+      console.log(`\nComando que seria executado (--dry-run):\n  ${chalk.dim(renderQaCommand(template, vars))}`);
+    } else {
+      console.log(chalk.yellow('\nComando do QA não configurado — nada a executar (veja `spec-wave doctor`).'));
+    }
+    console.log(chalk.dim('\nDry-run: nada executado e ZERO escrita no GitHub.'));
+    return { verdict: null, dryRun: true };
+  }
+
+  if (!template) {
+    console.log(chalk.yellow('\nComando do QA não configurado.'));
+    console.log(
+      `Configure em ${CONFIG_FILE}:\n` +
+      '  "qa": { "command": "<comando do executor com placeholders>" }\n' +
+      'ou defina a env SPEC_WAVE_QA_CMD (ela tem precedência).\n\n' +
+      'Placeholders: {contextFile} {qaPlanFile} {specFile} {issue} {type} {title}. Exemplos:\n' +
+      '  Claude Code: claude -p "Execute o QA descrito em {contextFile}"\n' +
+      '  opencode:    opencode run "Execute o QA descrito em {contextFile}"\n' +
+      '  Codex:       codex exec "Execute o QA descrito em {contextFile}"\n\n' +
+      `Contexto pronto em ${contextFile} — acione o executor manualmente com esse arquivo.`
+    );
+    return { verdict: null, notConfigured: true };
+  }
+
+  const command = renderQaCommand(template, vars);
+  console.log(`\nExecutando: ${chalk.dim(command)}\n`);
+  let executorFailed = null;
+  try {
+    execSync(command, {
+      stdio: 'inherit',
+      cwd: root || process.cwd(),
+      // §3.1 da spec-qa-lead: a env do PROCESSO vence a `qa.env`, chave a chave
+      // — é assim que o `qa-lead` injeta o endereço real de cada container sem
+      // mexer no arquivo versionado.
+      env: qaProcessEnv(config?.qa?.env, process.env),
+    });
+  } catch (err) {
+    executorFailed = err;
+  }
+
+  // O veredito sai do ARQUIVO, não do exit code: um executor que achou `fail`
+  // pode sair não-zero e mesmo assim ter registrado tudo.
+  if (!existsSync(resultAbs)) {
+    process.exitCode = 1;
+    console.error(chalk.red(
+      `\nO executor terminou${executorFailed ? ' com erro' : ''} sem gravar ${resultFile} — ` +
+      'sem resultados não há veredito: nada foi movido, nenhum Bug criado, nenhum comentário postado. ' +
+      'Verifique a saída acima e rode de novo.'
+    ));
+    return { verdict: null, error: 'sem-resultados' };
+  }
+  let results;
+  try {
+    results = validateQaResults(
+      JSON.parse(readFileSync(resultAbs, 'utf-8')),
+      targets.map(t => t.numero),
+    );
+  } catch (err) {
+    process.exitCode = 1;
+    console.error(chalk.red(`\nResultados inválidos em ${resultFile}: ${err.message}`));
+    return { verdict: null, error: 'resultados-invalidos' };
+  }
+
+  // D-QAL5: plano que MUDOU durante a execução invalida a corrida — o veredito
+  // seria de cenários que já não são os do arquivo. A checagem é da CLI (re-lê
+  // o plano do disco), não do executor: não depende de cooperação de agente.
+  {
+    const planAbs = path.join(root || process.cwd(), qaPlanRel);
+    let planNow = null;
+    try {
+      planNow = readFileSync(planAbs, 'utf-8');
+    } catch { /* ausente agora — cai no erro abaixo */ }
+    if (planNow === null || shortSha(planNow) !== shortSha(planContent)) {
+      process.exitCode = 1;
+      console.error(chalk.red(
+        `\n\`${qaPlanRel}\` mudou durante a execução (planSha ${shortSha(planContent)} → ` +
+        `${planNow === null ? 'arquivo ausente' : shortSha(planNow)}) — o veredito seria de um plano ` +
+        'que não existe mais. Nada foi movido, nenhum Bug criado. Rode de novo com o plano estável.'
+      ));
+      return { verdict: null, error: 'plano-mudou' };
+    }
+  }
+
+  // ── Estado acumulado e veredito ────────────────────────────────────────────
+  const { combined, pendingNumbers } = combineWithPrevious({
+    executed: results,
+    previous: previous.results,
+    allNumbers: scenarios.map(s => s.numero),
+  });
+  let verdict = aggregateVerdict(combined);
+  const planSha = shortSha(planContent);
+  const headSha = headShaOf(root);
+  const byNumero = new Map(scenarios.map(s => [s.numero, s]));
+
+  console.log(`\nVeredito agregado: ${chalk.bold(verdict)} (${combined.length} cenário(s) no escopo, ${results.length} executado(s) agora).`);
+
+  const outcome = {
+    token, projectToken, owner, repo, root, config, board, issue, number, type, feature,
+    featureStories,
+  };
+
+  let bugs = [];
+  if (verdict === 'fail') {
+    // Reprovar o re-teste de um BUG não abre outro Bug: o vermelho significa
+    // que o fix não segurou — o defeito é o mesmo, e o registro é o relatório.
+    const failed = type === 'Bug' ? [] : results.filter(r => r.verdict === 'fail');
+    const opened = await openBugsForFailures({ ...outcome, failed, byNumero, severity, headSha, qaPlanRel });
+    bugs = opened.bugs;
+    // §3.2 da spec-qa-lead: NUNCA reporte `fail` sem o Bug correspondente. O
+    // push do bug.md rejeitado após o teto de retries degrada o cenário para
+    // `blocked`/`outro` — o defeito pode existir, mas sem o registro publicado
+    // ele viraria um vermelho sem Bug, que a próxima execução recriaria.
+    if (opened.pushFailures.length > 0) {
+      for (const pf of opened.pushFailures) {
+        const idx = combined.findIndex(r => r.numero === pf.numero && !r.carried);
+        if (idx !== -1) {
+          combined[idx] = {
+            ...combined[idx],
+            verdict: 'blocked',
+            blockedReason: 'outro',
+            evidencia: `commit do bug.md rejeitado: ${pf.error}`.slice(0, 400),
+          };
+        }
+      }
+      verdict = aggregateVerdict(combined);
+      console.log(chalk.yellow(
+        `Cenário(s) ${opened.pushFailures.map(f => f.numero).join(', ')} degradado(s) para ` +
+        `blocked/outro (push do bug.md rejeitado) — veredito recalculado: ${chalk.bold(verdict)}.`
+      ));
+    }
+  }
+
+  if (verdict === 'fail') {
+    await stayInQa(outcome);
+    await postReport({
+      ...outcome, run, verdict, planSha, headSha, combined, pendingNumbers, bugs,
+      trailer: type === 'Bug'
+        ? `❌ **O teste de regressão ainda reprova** — o fix não cobriu o defeito. O Bug permanece ` +
+          `em **${STAGE_QA}** (Status ${PROGRESS_IN_PROGRESS}); nenhum Bug novo foi aberto (é o mesmo defeito).`
+        : `O item permanece em **${STAGE_QA}** (Status ${PROGRESS_IN_PROGRESS}). Corrija o(s) Bug(s) e ` +
+          `re-teste com \`npx @spec-wave/cli@latest qa <story> --only <cenário>\`.`,
+    });
+    process.exitCode = 1;
+    return { verdict, bugs };
+  }
+
+  if (verdict === 'blocked') {
+    const blockedList = combined.filter(r => r.verdict === 'blocked').map(r => r.numero);
+    await postReport({
+      ...outcome, run, verdict, planSha, headSha, combined, pendingNumbers, bugs: [],
+      trailer:
+        `⚪ **Inconclusivo:** cenário(s) ${blockedList.join(', ')} bloqueado(s) e nenhum \`fail\`. ` +
+        'Ambiente quebrado não é defeito de produto: **nada foi movido e nenhum Bug foi criado**. ' +
+        'Destrave o ambiente e rode de novo.',
+    });
+    process.exitCode = 1;
+    return { verdict };
+  }
+
+  // verdict === 'pass'
+  if (pendingNumbers.length > 0) {
+    await postReport({
+      ...outcome, run, verdict, planSha, headSha, combined, pendingNumbers, bugs: [],
+      trailer:
+        'Todos os cenários executados passaram, mas ainda há cenário(s) **sem veredito em nenhuma ' +
+        'corrida** — a aprovação só sai quando todos tiverem passado. Rode os que faltam.',
+    });
+    process.exitCode = 1;
+    return { verdict, pendingNumbers };
+  }
+
+  const moved = await applyGreen({ ...outcome, combined, byNumero });
+  await postReport({
+    ...outcome, run, verdict, planSha, headSha, combined, pendingNumbers: [], bugs: [],
+    trailer: moved.trailer,
+  });
+  if (moved.blockedByBugs) process.exitCode = 1;
+  return { verdict, moved };
+}
+
+// ── Desfechos ────────────────────────────────────────────────────────────────
+
+async function postReport({
+  token, owner, repo, number, type, run, verdict, planSha, headSha,
+  combined, pendingNumbers, bugs, trailer,
+}) {
+  const markdown = renderQaReport({
+    issue: number,
+    scope: `${type} #${number}`,
+    run, verdict, planSha, headSha,
+    results: combined,
+    bugs,
+    pendingNumbers,
+    trailer,
+  });
+  await commentOnIssue(token, owner, repo, number, markdown)
+    .catch(err => console.warn(chalk.yellow(`⚠️  Falha ao comentar o relatório: ${err.message}`)));
+}
+
+async function stayInQa({ projectToken, board, issue }) {
+  if (!board.project || !board.statusField) return;
+  await setItemStatus(projectToken, board.project, board.statusField, issue.node_id, PROGRESS_IN_PROGRESS)
+    .catch(() => {});
+}
+
+// Vermelho: um Bug por cenário reprovado — filho da STORY dona do cenário
+// (nunca da Feature), com bug.md determinístico commitado E PUBLICADO (push com
+// retry — §3.2 da spec-qa-lead) e `bug-approved` aplicada (exceção documentada
+// — spec §2.1). O bug.md vai para o remoto ANTES de a issue nascer: rodando num
+// container do `qa-lead`, um commit que fica local morre com o container, e um
+// Bug sem bug.md quebra o guard de idempotência da próxima corrida.
+//
+// Devolve também `pushFailures`: cenários cujo bug.md não pôde ser publicado —
+// o chamador os degrada para `blocked`/`outro`, porque `fail` sem Bug é o
+// estado que a spec proíbe.
+async function openBugsForFailures({
+  token, projectToken, owner, repo, root, board,
+  failed, byNumero, severity, headSha, qaPlanRel, feature, type, number,
+}) {
+  const bugs = [];
+  const pushFailures = [];
+  for (const r of failed) {
+    const scenario = byNumero.get(r.numero);
+    if (!scenario) continue;
+    const storyNumber = scenario.story;
+
+    let story = null;
+    try {
+      story = await getIssue(token, owner, repo, storyNumber);
+    } catch (err) {
+      console.warn(chalk.yellow(`⚠️  Não consegui ler a Story #${storyNumber} (${err.message}) — Bug do cenário ${r.numero} NÃO criado.`));
+      pushFailures.push({ numero: r.numero, error: `Story #${storyNumber} ilegível: ${err.message}` });
+      continue;
+    }
+
+    // Idempotência: Bug filho ABERTO com o mesmo marcador de origem → comenta
+    // nele em vez de duplicar.
+    const children = await listSubIssues(token, story.node_id).catch(() => []);
+    const existing = children.find(c =>
+      detectIssueType({ title: c.title, labels: c.labels }) === 'Bug' &&
+      c.state !== 'closed' &&
+      matchesQaOrigin(c.body, { issue: storyNumber, cenario: scenario.numero }));
+    if (existing) {
+      console.log(`Cenário ${scenario.numero} já tem Bug aberto (#${existing.number}) — comentando nele.`);
+      await commentOnIssue(token, owner, repo, existing.number,
+        `🧪 **O cenário ${scenario.numero} da Story #${storyNumber} reprovou de novo** ` +
+        `(${headSha ? `commit \`${headSha}\`` : 'nova execução'}).\n\n` +
+        `**Evidência:** ${r.evidencia || '(sem evidência registrada)'}`
+      ).catch(() => {});
+      bugs.push({ number: existing.number, cenario: scenario.numero, existing: true });
+      continue;
+    }
+
+    const resumo = (scenario.criterio || `cenário ${scenario.numero} de QA reprovado`).slice(0, 120);
+    const title = `[BUG] ${resumo}`;
+    const bodyLines = [
+      qaOriginMarker({ issue: storyNumber, cenario: scenario.numero }),
+      '',
+      `**Parent:** #${storyNumber} — ${story.title}`,
+      '',
+      `Aberto automaticamente pela reprovação do **${scenario.anchor}** do plano de QA` +
+      (feature ? ` da Feature #${feature.number}` : '') +
+      (qaPlanRel ? ` (\`${qaPlanRel}\`)` : '') + '.',
+      '',
+      `**Critério:** ${scenario.criterio || '—'}`,
+      `**Esperado:** ${scenario.esperado || '—'}`,
+      `**Obtido:** ${r.evidencia || '(sem evidência registrada)'}`,
+    ];
+    const milestone = story.milestone?.number ?? undefined; // herda do pai (D5)
+    const labels = ['[BUG]', severity, bugOriginLabel('qa')].filter(Boolean);
+
+    // bug.md determinístico, escrito, commitado e PUBLICADO antes de a issue
+    // nascer (§3.2): se o push não segura nem com retry, o Bug NÃO é criado e o
+    // cenário será degradado para blocked/outro pelo chamador.
+    const { fileRel, fileAbs, dirAbs } = bugDocPaths(title, root);
+    try {
+      mkdirSync(dirAbs, { recursive: true });
+      writeFileSync(fileAbs, renderQaBugDoc({
+        title: resumo, scenario, evidence: r.evidencia, severity, headSha,
+        featureNumber: feature?.number ?? null,
+      }));
+    } catch (err) {
+      console.warn(chalk.yellow(`⚠️  Não consegui escrever ${fileRel}: ${err.message} — Bug do cenário ${scenario.numero} NÃO criado.`));
+      pushFailures.push({ numero: r.numero, error: `escrita do ${fileRel} falhou: ${err.message}` });
+      continue;
+    }
+    const committed = commitLocalFile(root, fileRel,
+      `docs: gera ${fileRel} (reprovação de QA, cenário ${scenario.numero} da Story #${storyNumber}) [spec-wave]`);
+    if (!committed) {
+      pushFailures.push({ numero: r.numero, error: `commit do ${fileRel} falhou` });
+      continue;
+    }
+    const push = await pushWithRebase({ cwd: root || process.cwd() });
+    if (!push.ok) {
+      console.warn(chalk.yellow(
+        `⚠️  Push do ${fileRel} rejeitado após ${push.attempts} tentativa(s): ` +
+        `${String(push.error).split('\n')[0]} — Bug do cenário ${scenario.numero} NÃO criado.`
+      ));
+      pushFailures.push({ numero: r.numero, error: String(push.error).split('\n')[0] });
+      continue;
+    }
+
+    let created;
+    try {
+      created = await createIssue(token, owner, repo, title, bodyLines.join('\n'), labels, { milestone });
+    } catch (err) {
+      console.warn(chalk.yellow(`⚠️  Falha ao criar o Bug do cenário ${scenario.numero}: ${err.message}`));
+      pushFailures.push({ numero: r.numero, error: `criação da issue falhou: ${err.message}` });
+      continue;
+    }
+    console.log(`Bug #${created.number} criado para o cenário ${scenario.numero} (filho da Story #${storyNumber}).`);
+
+    await addSubIssue(token, story.node_id, created.nodeId)
+      .catch(err => console.warn(chalk.yellow(`⚠️  Bug #${created.number} criado, mas não vinculado à Story: ${err.message}`)));
+
+    // Board: 🧪 QA achou → o Bug nasce em ✅ Ready (triagem já feita pela reprova).
+    if (board.project && board.etapaField) {
+      try {
+        await advanceToStage(
+          projectToken, board.project, board.etapaField, board.statusField,
+          created.nodeId, STAGE_READY, PROGRESS_TODO,
+          { typeField: board.typeField, itemType: 'Bug' });
+      } catch (err) {
+        console.warn(chalk.yellow(`⚠️  Bug #${created.number} sem Etapa no board: ${err.message} — repare com \`spec-wave repair-stage\`.`));
+      }
+      if (board.priorityField?.options?.[severity]) {
+        try {
+          const itemId = await addProjectItem(projectToken, board.project.id, created.nodeId);
+          await setItemSingleSelect(projectToken, board.project.id, itemId,
+            board.priorityField.id, board.priorityField.options[severity]);
+        } catch { /* prioridade no board é acessório */ }
+      }
+    }
+
+    // `bug-approved` direto: reprodução, esperado/obtido e regressão são a
+    // execução observada — regerar por IA só introduziria alucinação.
+    await addLabel(token, owner, repo, created.number, LABEL_BUG_APPROVED).catch(() => {});
+
+    await commentOnIssue(token, owner, repo, created.number,
+      `🧪 **Bug aberto pela reprovação de QA** — ${scenario.anchor} da Story #${storyNumber}.\n\n` +
+      `📄 \`${fileRel}\` foi escrito, commitado e publicado com as seis seções preenchidas a partir ` +
+      'do cenário e da saída real da execução (exceção documentada à regra do `spec-wave:bug` — ' +
+      'conteúdo determinístico de uma execução observada, sem IA).\n\n' +
+      `Após o fix, re-teste: \`npx @spec-wave/cli@latest qa ${storyNumber} --only ${scenario.numero}\``
+    ).catch(() => {});
+
+    bugs.push({ number: created.number, cenario: scenario.numero, existing: false });
+  }
+  return { bugs, pushFailures };
+}
+
+// Verde: aprova e move — Story → 📋 Homologação, Bug → 🚀 Deploy, Feature
+// quando todas as Stories liberarem. Guarda dura: Bug filho aberto segura tudo.
+async function applyGreen({
+  token, projectToken, owner, repo, board, issue, number, type, feature, combined, byNumero,
+  featureStories = [],
+}) {
+  const move = async (nodeId, targetStage, itemType) => {
+    if (!board.project || !board.etapaField) return false;
+    return await advanceToStage(
+      projectToken, board.project, board.etapaField, board.statusField,
+      nodeId, targetStage, PROGRESS_TODO,
+      { typeField: board.typeField, itemType });
+  };
+
+  if (type === 'Bug') {
+    await addLabel(token, owner, repo, number, LABEL_QA_APPROVED).catch(() => {});
+    const target = greenTargetStage('Bug');
+    try {
+      await move(issue.node_id, target, 'Bug');
+      console.log(`Bug #${number} → "${target}" (D-QA6: Bug não passa por Homologação).`);
+    } catch (err) {
+      console.warn(chalk.yellow(`⚠️  Falha ao mover o Bug no board: ${err.message}`));
+    }
+    return { trailer: `✅ Todos os cenários passaram. Bug segue para **${target}** (D-QA6 — sem Homologação).` };
+  }
+
+  if (type === 'Story') {
+    const children = (await listSubIssues(token, issue.node_id).catch(() => []))
+      .map(c => ({ ...c, type: detectIssueType({ title: c.title, labels: c.labels }) }));
+    const guard = storyCanAdvance({ children });
+    if (!guard.ok) {
+      console.log(chalk.yellow(`Story verde, mas com Bug(s) filho(s) aberto(s): ${guard.openBugs.map(n => `#${n}`).join(', ')} — não avança.`));
+      return {
+        blockedByBugs: true,
+        trailer:
+          `⛔ **Todos os cenários passaram, mas a Story NÃO avança:** há Bug(s) filho(s) ` +
+          `aberto(s) — ${guard.openBugs.map(n => `#${n}`).join(', ')}. Feche-os (fix + re-teste) ` +
+          'e rode o `qa` de novo.',
+      };
+    }
+    await addLabel(token, owner, repo, number, LABEL_QA_APPROVED).catch(() => {});
+    try {
+      await move(issue.node_id, STAGE_UAT, 'Story');
+      console.log(`Story #${number} → "${STAGE_UAT}" / Status "${PROGRESS_TODO}".`);
+    } catch (err) {
+      console.warn(chalk.yellow(`⚠️  Falha ao mover a Story no board: ${err.message}`));
+    }
+
+    // Última Story da Feature? Então a Feature avança na MESMA execução.
+    let featureAdvanced = false;
+    if (feature?.nodeId) {
+      featureAdvanced = await maybeAdvanceFeature({
+        token, projectToken, owner, repo, board, feature, justApproved: number, move,
+      });
+    }
+    return {
+      trailer:
+        `✅ Todos os cenários passaram — \`${LABEL_QA_APPROVED}\` aplicada e Story movida para ` +
+        `**${STAGE_UAT}** (aprovação humana de negócio).` +
+        (featureAdvanced ? `\n\nEsta era a última Story pendente: a **Feature #${feature.number} também avançou** para ${STAGE_UAT}.` : ''),
+    };
+  }
+
+  // Feature: aprova por Story (as que passaram todos os SEUS cenários) e então
+  // avalia a própria Feature. A Story de cada resultado vem do cenário do
+  // escopo (byNumero) — o resultado em si só carrega o número posicional.
+  const approvedNow = [];
+  for (const story of featureStories) {
+    if ((story.labels || []).includes(LABEL_QA_APPROVED)) continue;
+    const daStory = combined.filter(r => byNumero.get(r.numero)?.story === story.number);
+    if (daStory.length === 0) continue;
+    if (!daStory.every(r => r.verdict === 'pass')) continue;
+    const children = (await listSubIssues(token, story.nodeId).catch(() => []))
+      .map(c => ({ ...c, type: detectIssueType({ title: c.title, labels: c.labels }) }));
+    const guard = storyCanAdvance({ children });
+    if (!guard.ok) {
+      console.log(chalk.yellow(`Story #${story.number} verde, mas com Bug aberto (${guard.openBugs.map(n => `#${n}`).join(', ')}) — não avança.`));
+      continue;
+    }
+    await addLabel(token, owner, repo, story.number, LABEL_QA_APPROVED).catch(() => {});
+    try {
+      await move(story.nodeId, STAGE_UAT, 'Story');
+      console.log(`Story #${story.number} → "${STAGE_UAT}".`);
+    } catch (err) {
+      console.warn(chalk.yellow(`⚠️  Falha ao mover a Story #${story.number}: ${err.message}`));
+    }
+    approvedNow.push(story.number);
+  }
+
+  const featureAdvanced = await maybeAdvanceFeature({
+    token, projectToken, owner, repo, board, feature,
+    justApproved: approvedNow, move,
+  });
+  return {
+    trailer:
+      `✅ Todos os cenários do escopo passaram.` +
+      (approvedNow.length > 0 ? ` Stories aprovadas agora: ${approvedNow.map(n => `#${n}`).join(', ')}.` : '') +
+      (featureAdvanced
+        ? `\n\nTodas as Stories liberaram: a **Feature #${feature.number} avançou** para ${STAGE_UAT}.`
+        : ''),
+  };
+}
+
+// A Feature avança quando TODAS as Stories têm qa-approved ou já estão em
+// Homologação+ — mesma regra do Code Review (spec §6.3).
+async function maybeAdvanceFeature({ token, projectToken, owner, repo, board, feature, justApproved, move }) {
+  const aprovadas = new Set(Array.isArray(justApproved) ? justApproved : [justApproved]);
+  let stories = [];
+  try {
+    stories = (await listSubIssues(token, feature.nodeId))
+      .filter(s => detectIssueType({ title: s.title, labels: s.labels }) === 'Story');
+  } catch {
+    return false; // sem a lista, na dúvida a Feature não avança
+  }
+  const enriched = [];
+  for (const s of stories) {
+    const labels = aprovadas.has(s.number) ? [...(s.labels || []), LABEL_QA_APPROVED] : (s.labels || []);
+    let stage = null;
+    if (!labelNames(labels).includes(LABEL_QA_APPROVED) && board.project && board.etapaField) {
+      try {
+        const itemId = await addProjectItem(projectToken, board.project.id, s.nodeId);
+        stage = await getItemSingleSelectValue(projectToken, itemId, board.etapaField.id);
+      } catch { stage = null; }
+    }
+    enriched.push({ number: s.number, labels, stage });
+  }
+  const check = featureCanAdvanceQa(enriched);
+  if (!check.ok) {
+    if (check.pending.length > 0) {
+      console.log(`Feature #${feature.number} ainda não avança — Stories pendentes: ${check.pending.map(n => `#${n}`).join(', ')}.`);
+    }
+    return false;
+  }
+  await addLabel(token, owner, repo, feature.number, LABEL_QA_APPROVED).catch(() => {});
+  try {
+    await move(feature.nodeId, STAGE_UAT, 'Feature');
+    console.log(`Feature #${feature.number} → "${STAGE_UAT}".`);
+    return true;
+  } catch (err) {
+    console.warn(chalk.yellow(`⚠️  Falha ao mover a Feature #${feature.number}: ${err.message}`));
+    return false;
+  }
+}