@spec-wave/cli 0.29.0 → 0.30.0

package/src/lib/qa-plan-doc.mjs

@@ -0,0 +1,340 @@
+// Plano de QA (docs/features/<slug>/qa-plan.md) — módulo PURO, sem I/O.
+//
+// A etapa 🧪 QA era a única do fluxo sem artefato: a validação funcional era
+// manual e não deixava rastro. O qa-plan.md fecha esse buraco — um arquivo por
+// FEATURE (D-QA1), derivado dos critérios de aceite da spec.md, com uma seção
+// `## Cenário N — Story #X` por cenário. O comando `qa <n>` executa esses
+// cenários e o veredito verde/vermelho move o board ou abre Bugs.
+//
+// As regras de parsing ESPELHAM as do decomposition.md de propósito (mesmo
+// fenceScanner, mesma regra "a posição manda, não o número escrito"): quem já
+// edita um, sabe editar o outro.
+//
+// Gramática (v1):
+//
+//   # Plano de QA — <título da Feature>
+//   <!-- spec-wave:qa-plan v1 issue=360 -->
+//
+//   ## Cenário 1 — Story #412
+//
+//   **Critério:** AC-2 — cliente vê apenas os próprios pedidos
+//   **Pré-condições:** dois usuários autenticáveis
+//   **Passos:**
+//   1. Autenticar como usuário A
+//   2. `GET /pedidos`
+//   **Esperado:** resposta 200 contendo somente pedidos de A
+//
+// `**Critério:**` e `**Esperado:**` são obrigatórios; `**Pré-condições:**` e
+// `**Passos:**` são opcionais. O corpo aceita markdown livre.
+
+import { fenceScanner } from './decomposition-doc.mjs';
+import { findIncompleteDocSigns } from './doc-completeness.mjs';
+
+/** Nome do arquivo dentro do diretório da feature. */
+export const QA_PLAN_FILE = 'qa-plan.md';
+
+// Versão do formato, gravada no marcador. Versão MAIOR que a conhecida faz o
+// parse falhar pedindo update da CLI — nunca interpretar errado em silêncio.
+export const QA_PLAN_VERSION = 1;
+
+// Só esta forma é estrutura; "## Detalhes" no corpo de um cenário não é seção.
+// `Story #X` é obrigatório no título — cenário sem dono não tem para quem
+// abrir Bug na reprova.
+const SCENARIO_RE = /^##[ \t]+Cen[aá]rio[ \t]+(\d+)[ \t]*(?:[—–:-][ \t]*)?(?:Story[ \t]*#(\d+))?[ \t]*(.*)$/i;
+const H1_RE = /^#[ \t]+(.*)$/;
+const MARKER_RE = /^<!--[ \t]*spec-wave:qa-plan[ \t]+(.*?)-->[ \t]*$/i;
+
+// Campos da gramática. Valem em qualquer ponto do corpo do cenário (não só no
+// primeiro bloco): o exemplo canônico intercala `**Passos:**` multi-linha entre
+// eles, e restringir ao primeiro bloco quebraria o formato que o próprio
+// gerador emite.
+const FIELD_RE = /^\*\*(Crit[eé]rio|Pr[eé]-?condi[çc][oõ]es|Passos|Esperado):?\*\*:?[ \t]*(.*)$/i;
+
+function invalid(reason) {
+  return new Error(`qa-plan.md inválido: ${reason}.`);
+}
+
+function flatten(value) {
+  return String(value ?? '').replace(/\s+/g, ' ').trim();
+}
+
+function trimBlankEdges(lines) {
+  const out = [...lines];
+  while (out.length && !out[0].trim()) out.shift();
+  while (out.length && !out[out.length - 1].trim()) out.pop();
+  return out;
+}
+
+// Canoniza o nome do campo (sem acento/caixa) para a chave do objeto.
+function fieldKey(raw) {
+  const norm = String(raw).normalize('NFD').replace(/[̀-ͯ]/g, '').toLowerCase();
+  if (norm.startsWith('criterio')) return 'criterio';
+  if (norm.startsWith('pre')) return 'precondicoes';
+  if (norm === 'passos') return 'passos';
+  return 'esperado';
+}
+
+function parseMarker(attrs) {
+  const text = String(attrs || '');
+  const version = /(?:^|\s)v(\d+)(?:\s|$)/.exec(text);
+  const issue = /\bissue=(\d+)\b/.exec(text);
+  return {
+    version: version ? parseInt(version[1], 10) : QA_PLAN_VERSION,
+    issueNumber: issue ? parseInt(issue[1], 10) : null,
+  };
+}
+
+// "# Plano de QA — X" → "X".
+function stripDocTitle(raw) {
+  const text = flatten(raw);
+  const m = /^Plano de QA(?:[ \t]*[—–:-][ \t]*(.*))?$/i.exec(text);
+  return m ? (m[1] || '').trim() : text;
+}
+
+/**
+ * Interpreta o qa-plan.md (função PURA — testável).
+ *
+ * A numeração ESCRITA é ignorada: a posição manda. Inserir um cenário no meio
+ * sem renumerar funciona — a âncora `Cenário N` sai da posição, e o render
+ * devolve a numeração corrigida no ciclo seguinte.
+ *
+ * `Story #X` ausente no título é ERRO de parse (o campo é obrigatório na
+ * gramática); referência a issue que não é sub-issue da Feature é erro de
+ * VALIDAÇÃO (validateQaPlan) — o parser não conhece a árvore de issues.
+ *
+ * @param {string} markdown conteúdo do arquivo
+ * @param {object} [opts]
+ * @param {boolean} [opts.requireMarker] default true; false para conteúdo
+ *        recém-gerado pelo modelo, que ganha o marcador no render canônico
+ * @returns {{version:number, issueNumber:number|null, title:string,
+ *            scenarios: Array<{anchor:string, numero:number, story:number,
+ *            criterio:string, precondicoes:string, passos:string,
+ *            esperado:string, body:string}>}}
+ */
+export function parseQaPlanDoc(markdown, { requireMarker = true } = {}) {
+  const text = String(markdown ?? '').replace(/\r\n?/g, '\n');
+  if (!text.trim()) throw invalid('o arquivo está vazio');
+
+  const scan = fenceScanner();
+  const sections = [];
+  let current = null;
+  let marker = null;
+  let title = '';
+  let sawH1 = false;
+
+  for (const line of text.split('\n')) {
+    if (!scan.inFence(line)) {
+      const m = SCENARIO_RE.exec(line);
+      if (m) {
+        current = { num: m[1], story: m[2] ? parseInt(m[2], 10) : null, rest: m[3] || '', lines: [] };
+        sections.push(current);
+        continue;
+      }
+      if (!current) {
+        const mk = MARKER_RE.exec(line.trim());
+        if (mk && !marker) {
+          marker = parseMarker(mk[1]);
+          continue;
+        }
+        const h1 = H1_RE.exec(line);
+        if (h1 && !sawH1) {
+          title = stripDocTitle(h1[1]);
+          sawH1 = true;
+          continue;
+        }
+      }
+    }
+    if (current) current.lines.push(line);
+  }
+
+  if (scan.isOpen()) {
+    throw invalid(
+      'há um bloco de código (```) aberto e nunca fechado — feche-o para que os ' +
+      'títulos seguintes voltem a ser reconhecidos'
+    );
+  }
+  if (!marker && requireMarker) {
+    throw invalid(
+      `não encontrei o marcador \`<!-- spec-wave:qa-plan v${QA_PLAN_VERSION} … -->\` — ` +
+      'o arquivo não parece um qa-plan.md do spec-wave'
+    );
+  }
+  if (marker && marker.version > QA_PLAN_VERSION) {
+    throw invalid(
+      `está no formato v${marker.version} e esta CLI entende até v${QA_PLAN_VERSION} — ` +
+      'atualize o @spec-wave/cli'
+    );
+  }
+  if (sections.length === 0) {
+    throw invalid('não encontrei nenhum cenário ("## Cenário 1 — Story #<n>")');
+  }
+
+  const scenarios = sections.map((s, i) => {
+    const anchor = `Cenário ${i + 1}`;
+    if (!s.story) {
+      throw invalid(
+        `${anchor} está sem a Story dona — o título precisa ser ` +
+        `"## Cenário N — Story #<issue>" (encontrei "## Cenário ${s.num}${s.rest ? ` — ${s.rest}` : ''}")`
+      );
+    }
+    const fields = { criterio: '', precondicoes: '', passos: '', esperado: '' };
+    // `Passos` é o único campo multi-linha: acumula até o próximo campo.
+    let collecting = null;
+    const fieldScan = fenceScanner();
+    for (const line of s.lines) {
+      const inFence = fieldScan.inFence(line);
+      const f = inFence ? null : FIELD_RE.exec(line);
+      if (f) {
+        const key = fieldKey(f[1]);
+        fields[key] = (f[2] || '').trim();
+        collecting = key === 'passos' ? 'passos' : null;
+        continue;
+      }
+      if (collecting === 'passos' && line.trim()) {
+        fields.passos = fields.passos ? `${fields.passos}\n${line}` : line;
+      } else if (collecting && !line.trim()) {
+        collecting = null;
+      }
+    }
+    return {
+      anchor,
+      numero: i + 1,
+      story: s.story,
+      criterio: fields.criterio,
+      precondicoes: fields.precondicoes,
+      passos: fields.passos,
+      esperado: fields.esperado,
+      body: trimBlankEdges(s.lines).join('\n'),
+    };
+  });
+
+  return {
+    version: marker?.version ?? QA_PLAN_VERSION,
+    issueNumber: marker?.issueNumber ?? null,
+    title,
+    scenarios,
+  };
+}
+
+/**
+ * Renderiza o qa-plan.md CANÔNICO (função PURA).
+ *
+ * Numeração recalculada por posição e marcador sempre presente — é por isso que
+ * o conteúdo recém-gerado pelo modelo passa por parse + render antes de ser
+ * publicado: o arquivo nasce parseável mesmo que o modelo tenha errado a
+ * numeração ou omitido o marcador.
+ *
+ * @param {object} model
+ * @param {string} [model.title] título da Feature (H1)
+ * @param {number|null} [model.issueNumber]
+ * @param {Array<{story:number, body:string}>} [model.scenarios]
+ * @returns {string} markdown terminado em \n
+ */
+export function renderQaPlanDoc({ title = '', issueNumber = null, scenarios = [] } = {}) {
+  const attrs = [`v${QA_PLAN_VERSION}`];
+  const issue = Number(issueNumber);
+  if (Number.isInteger(issue) && issue > 0) attrs.push(`issue=${issue}`);
+
+  const head = flatten(title) ? `# Plano de QA — ${flatten(title)}` : '# Plano de QA';
+  const blocks = [`${head}\n<!-- spec-wave:qa-plan ${attrs.join(' ')} -->`];
+
+  scenarios.forEach((s, i) => {
+    blocks.push(`## Cenário ${i + 1} — Story #${s.story}`);
+    const body = trimBlankEdges(String(s.body ?? '').replace(/\r\n?/g, '\n').split('\n')).join('\n');
+    if (body) blocks.push(body);
+  });
+
+  return `${blocks.join('\n\n')}\n`;
+}
+
+/**
+ * Validação DETERMINÍSTICA do plano, antes da crítica (função PURA).
+ *
+ * Barata e mais confiável que a IA para o que é checável sem julgamento:
+ *  1. toda Story sub-issue da Feature tem ≥ 1 cenário;
+ *  2. todo `Story #X` referenciado é sub-issue real da Feature;
+ *  3. todo cenário tem `**Critério:**` e `**Esperado:**` não vazios;
+ *  4. nenhum sinal objetivo de truncamento (mesmo helper do `validate`).
+ *
+ * Falha aqui evita gastar uma chamada de crítica com um arquivo quebrado.
+ *
+ * @param {object} params
+ * @param {ReturnType<typeof parseQaPlanDoc>} params.doc plano parseado
+ * @param {Array<{number:number, title?:string, state?:string|null,
+ *         stateReason?:string|null}>} params.stories Stories sub-issues da Feature
+ * @param {string} [params.content] markdown bruto (para os sinais de truncamento)
+ * @returns {string[]} erros em pt-BR (vazio = plano válido)
+ */
+export function validateQaPlan({ doc, stories = [], content = '' } = {}) {
+  const errors = [];
+  const byNumber = new Map(stories.map(s => [s.number, s]));
+
+  for (const s of doc?.scenarios || []) {
+    if (!byNumber.has(s.story)) {
+      errors.push(
+        `${s.anchor} referencia a Story #${s.story}, que não é sub-issue desta Feature — ` +
+        'corrija o número (ou o plano está desatualizado em relação à decomposição).'
+      );
+    }
+    if (!s.criterio) {
+      errors.push(`${s.anchor} está sem \`**Critério:**\` — todo cenário precisa dizer QUAL critério de aceite valida.`);
+    }
+    if (!s.esperado) {
+      errors.push(`${s.anchor} está sem \`**Esperado:**\` — sem resultado esperado não há como dar veredito.`);
+    }
+  }
+
+  // Story descartada no rescopo não precisa de cenário; as demais, sim.
+  const covered = new Set((doc?.scenarios || []).map(s => s.story));
+  for (const story of stories) {
+    const descartada = story.state === 'closed' && story.stateReason === 'not_planned';
+    if (!descartada && !covered.has(story.number)) {
+      errors.push(
+        `A Story #${story.number}${story.title ? ` (${story.title})` : ''} não tem nenhum cenário — ` +
+        'toda Story da Feature precisa de ao menos um.'
+      );
+    }
+  }
+
+  for (const problem of findIncompleteDocSigns(content || '')) {
+    errors.push(`O arquivo parece incompleto: ${problem}`);
+  }
+
+  return errors;
+}
+
+/**
+ * Cenários-alvo de uma execução (função PURA).
+ *
+ * `qa <feature>` → todos cujas Stories ainda não têm `qa-approved`;
+ * `qa <story>`   → só os daquela Story;
+ * `--only`       → filtra por número POSICIONAL (coerente com o parser).
+ *
+ * @param {object} params
+ * @param {ReturnType<typeof parseQaPlanDoc>} params.doc
+ * @param {number|null} [params.story] limita à Story (modo `qa <story>`)
+ * @param {number[]} [params.approvedStories] Stories com `spec-wave:qa-approved`
+ * @param {number[]|null} [params.only] números de cenário do `--only`
+ * @returns {{ targets: Array, skippedApproved: Array, unknownOnly: number[] }}
+ */
+export function resolveTargetScenarios({ doc, story = null, approvedStories = [], only = null } = {}) {
+  const approved = new Set(approvedStories);
+  let targets = doc?.scenarios || [];
+  let skippedApproved = [];
+
+  if (story != null) {
+    targets = targets.filter(s => s.story === story);
+  } else {
+    skippedApproved = targets.filter(s => approved.has(s.story));
+    targets = targets.filter(s => !approved.has(s.story));
+  }
+
+  let unknownOnly = [];
+  if (Array.isArray(only) && only.length > 0) {
+    const wanted = new Set(only);
+    unknownOnly = only.filter(n => !targets.some(s => s.numero === n));
+    targets = targets.filter(s => wanted.has(s.numero));
+  }
+
+  return { targets, skippedApproved, unknownOnly };
+}

package/src/lib/qa-report.mjs

@@ -0,0 +1,340 @@
+// Relatório de execução do QA — módulo PURO, sem I/O.
+//
+// O comentário de veredito é a FONTE DE ESTADO entre execuções: rodar com
+// `--only` lê o último relatório da issue para compor o estado acumulado dos
+// cenários que não rodaram desta vez. O marcador HTML da primeira linha é
+// CONTRATO com a UI do SpecWave — mudar o formato exige bump de versão
+// (`v1` → `v2`).
+
+import { createHash } from 'node:crypto';
+import { REQUIRED_BUG_SECTIONS } from '../config.mjs';
+
+export const QA_REPORT_VERSION = 1;
+
+/** Vereditos aceitos por cenário. */
+export const QA_VERDICTS = ['pass', 'fail', 'blocked'];
+
+export const QA_REPORT_MARKER_RE =
+  /<!--\s*spec-wave:qa-report\s+v(?<version>\d+)\s+issue=(?<issue>\d+)\s+run=(?<run>\d+)\s+verdict=(?<verdict>pass|fail|blocked)\s+planSha=(?<planSha>[0-9a-f]+)\s+headSha=(?<headSha>[0-9a-f?]+)\s*-->/g;
+
+// Origem de um Bug aberto por reprovação de QA — gravado no CORPO da issue do
+// Bug. É a chave da idempotência: re-executar o mesmo cenário reprovado não
+// abre um segundo Bug, comenta no que já existe.
+export const QA_ORIGIN_MARKER_RE =
+  /<!--\s*spec-wave:qa-origin\s+issue=(?<issue>\d+)\s+cenario=(?<cenario>\d+)\s*-->/;
+
+/** Monta o marcador do relatório (função PURA). */
+export function qaReportMarker({ issue, run, verdict, planSha, headSha }) {
+  return `<!-- spec-wave:qa-report v${QA_REPORT_VERSION} issue=${issue} run=${run} ` +
+    `verdict=${verdict} planSha=${planSha} headSha=${headSha || '?'} -->`;
+}
+
+/** Monta o marcador de origem de um Bug de QA (função PURA). */
+export function qaOriginMarker({ issue, cenario }) {
+  return `<!-- spec-wave:qa-origin issue=${issue} cenario=${cenario} -->`;
+}
+
+/**
+ * O corpo de um Bug aberto veio deste cenário? (função PURA)
+ *
+ * @param {string} body corpo da issue do Bug
+ * @param {{issue:number, cenario:number}} origem Story dona + número do cenário
+ * @returns {boolean}
+ */
+export function matchesQaOrigin(body, { issue, cenario }) {
+  const m = QA_ORIGIN_MARKER_RE.exec(String(body || ''));
+  if (!m) return false;
+  return parseInt(m.groups.issue, 10) === issue && parseInt(m.groups.cenario, 10) === cenario;
+}
+
+/** SHA curto (7 hex) do conteúdo do plano — vai no marcador do relatório. */
+export function shortSha(content) {
+  return createHash('sha1').update(String(content ?? ''), 'utf-8').digest('hex').slice(0, 7);
+}
+
+/**
+ * Veredito agregado da execução (função PURA).
+ *
+ * `fail` vence `blocked` de propósito: com um defeito confirmado, o desfecho é
+ * vermelho (abre Bug) mesmo que outro cenário tenha ficado bloqueado. `blocked`
+ * sem nenhum `fail` é INCONCLUSIVO — ambiente quebrado não é defeito de
+ * produto, então nada move e nenhum Bug nasce.
+ *
+ * @param {Array<{verdict:string}>} results
+ * @returns {'pass'|'fail'|'blocked'}
+ */
+export function aggregateVerdict(results = []) {
+  if (results.some(r => r.verdict === 'fail')) return 'fail';
+  if (results.some(r => r.verdict === 'blocked')) return 'blocked';
+  return 'pass';
+}
+
+/**
+ * Valida o payload de resultados escrito pelo executor (função PURA).
+ *
+ * O executor (o agente acionado por `qa.command`) grava um JSON com o veredito
+ * de cada cenário. Fora do contrato → erro nomeando o campo: um resultado
+ * ilegível não pode virar aprovação nem reprovação.
+ *
+ * @param {*} payload objeto lido do arquivo de resultados
+ * @param {number[]} expected números dos cenários que DEVIAM ter sido executados
+ * @returns {Array<{numero:number, verdict:'pass'|'fail'|'blocked', evidencia:string}>}
+ */
+export function validateQaResults(payload, expected = []) {
+  if (payload === null || typeof payload !== 'object' || !Array.isArray(payload.scenarios)) {
+    throw new Error('o arquivo de resultados deveria ser {"scenarios": [...]}.');
+  }
+  const out = new Map();
+  payload.scenarios.forEach((item, i) => {
+    const at = `scenarios[${i}]`;
+    const numero = Number(item?.cenario);
+    if (!Number.isInteger(numero) || numero <= 0) {
+      throw new Error(`${at}.cenario deveria ser o número posicional do cenário, veio ${JSON.stringify(item?.cenario)}.`);
+    }
+    const verdict = String(item?.verdict || '').toLowerCase();
+    if (!QA_VERDICTS.includes(verdict)) {
+      throw new Error(
+        `${at}.verdict = ${JSON.stringify(item?.verdict)} não é aceito ` +
+        `(aceitos, exatamente: ${QA_VERDICTS.join(' | ')}).`
+      );
+    }
+    out.set(numero, {
+      numero,
+      verdict,
+      evidencia: String(item?.evidencia ?? '').trim(),
+    });
+  });
+  const missing = expected.filter(n => !out.has(n));
+  if (missing.length > 0) {
+    throw new Error(
+      `faltou o veredito do(s) cenário(s) ${missing.join(', ')} — cenário que não pôde ` +
+      'ser executado deve vir como "blocked", nunca ser omitido.'
+    );
+  }
+  return expected.map(n => out.get(n));
+}
+
+/**
+ * Compõe o estado acumulado quando a execução foi parcial (`--only`) —
+ * função PURA.
+ *
+ * Cenários não executados nesta corrida herdam o veredito do ÚLTIMO relatório;
+ * sem relatório anterior, contam como pendentes (nunca como pass): a aprovação
+ * exige que todos os alvos tenham passado em ALGUMA corrida registrada.
+ *
+ * @param {object} params
+ * @param {Array<{numero:number, verdict:string, evidencia:string}>} params.executed
+ * @param {Map<number, {verdict:string}>} [params.previous] numero → resultado anterior
+ * @param {number[]} params.allNumbers todos os cenários do escopo
+ * @returns {{ combined: Array, pendingNumbers: number[] }}
+ */
+export function combineWithPrevious({ executed = [], previous = new Map(), allNumbers = [] } = {}) {
+  const executedBy = new Map(executed.map(r => [r.numero, r]));
+  const combined = [];
+  const pendingNumbers = [];
+  for (const n of allNumbers) {
+    if (executedBy.has(n)) {
+      combined.push({ ...executedBy.get(n), carried: false });
+      continue;
+    }
+    const prev = previous.get(n);
+    if (prev) {
+      combined.push({ numero: n, verdict: prev.verdict, evidencia: prev.evidencia || '(corrida anterior)', carried: true });
+    } else {
+      pendingNumbers.push(n);
+    }
+  }
+  return { combined, pendingNumbers };
+}
+
+const RESULTS_JSON_RE = /```json spec-wave:qa-results\s*\n([\s\S]*?)\n```/;
+
+/**
+ * Último relatório de QA de uma issue (função PURA).
+ *
+ * Lê os comentários em ordem cronológica; o mais recente vence. O estado por
+ * cenário sai do bloco JSON cercado — reparsear a tabela markdown seria frágil.
+ *
+ * @param {Array<{body?:string}>} comments comentários da issue, em ordem
+ * @returns {{ run: number, verdict: string|null, results: Map<number,object> }}
+ */
+export function parseLastQaReport(comments = []) {
+  let run = 0;
+  let verdict = null;
+  let results = new Map();
+  for (const comment of comments) {
+    const body = String(comment?.body || '');
+    QA_REPORT_MARKER_RE.lastIndex = 0;
+    const m = QA_REPORT_MARKER_RE.exec(body);
+    if (!m) continue;
+    run = Math.max(run, parseInt(m.groups.run, 10));
+    verdict = m.groups.verdict;
+    const bloco = body.match(RESULTS_JSON_RE);
+    if (!bloco) continue;
+    try {
+      const payload = JSON.parse(bloco[1]);
+      if (Array.isArray(payload?.scenarios)) {
+        results = new Map(payload.scenarios
+          .filter(s => Number.isInteger(s?.cenario))
+          .map(s => [s.cenario, { verdict: s.verdict, evidencia: s.evidencia || '' }]));
+      }
+    } catch { /* bloco ilegível não vira estado */ }
+  }
+  return { run, verdict, results };
+}
+
+const VERDICT_ICON = { pass: '✅ pass', fail: '❌ fail', blocked: '⚪ blocked' };
+
+// Evidência entra numa célula de tabela markdown: sem quebra de linha, sem pipe
+// e sem fechar o marcador HTML antes da hora.
+function sanitizeCell(text, max = 200) {
+  const clean = String(text ?? '')
+    .replace(/-->/g, '--‑>')
+    .replace(/\|/g, '\\|')
+    .replace(/\s+/g, ' ')
+    .trim();
+  return clean.length > max ? `${clean.slice(0, max)}…` : clean;
+}
+
+/**
+ * Monta o comentário de relatório de QA (função PURA).
+ *
+ * Primeira linha = marcador (contrato com a UI). O bloco JSON no fim é o que a
+ * próxima execução com `--only` lê para compor o estado acumulado.
+ *
+ * @param {object} params
+ * @param {number} params.issue issue onde o relatório será postado
+ * @param {string} params.scope ex.: "Story #412" ou "Feature #360"
+ * @param {number} params.run número desta execução (1ª, 2ª…)
+ * @param {'pass'|'fail'|'blocked'} params.verdict veredito agregado
+ * @param {string} params.planSha sha curto do qa-plan.md executado
+ * @param {string} [params.headSha] sha curto do HEAD do checkout
+ * @param {Array<{numero, verdict, evidencia, carried?}>} params.results
+ * @param {Array<{number:number, cenario:number, existing?:boolean}>} [params.bugs]
+ * @param {number[]} [params.pendingNumbers] cenários sem veredito em corrida parcial
+ * @param {string} [params.trailer] linha final livre (o que acontece a seguir)
+ * @returns {string} markdown
+ */
+export function renderQaReport({
+  issue, scope, run, verdict, planSha, headSha, results = [], bugs = [],
+  pendingNumbers = [], trailer = '',
+} = {}) {
+  const parts = [
+    qaReportMarker({ issue, run, verdict, planSha, headSha }),
+    '## 🧪 Relatório de QA (spec-wave)',
+    `**Escopo:** ${scope} · **Cenários:** ${results.length} · **Execução:** ${run}ª`,
+  ];
+
+  const linhas = ['| Cenário | Veredito | Evidência |', '|---|---|---|'];
+  for (const r of results) {
+    const carried = r.carried ? ' _(corrida anterior)_' : '';
+    linhas.push(`| ${r.numero} | ${VERDICT_ICON[r.verdict] || r.verdict} | ${sanitizeCell(r.evidencia)}${carried} |`);
+  }
+  parts.push(linhas.join('\n'));
+
+  if (pendingNumbers.length > 0) {
+    parts.push(
+      `⚠️ Cenário(s) ainda **sem veredito** em nenhuma corrida: ${pendingNumbers.join(', ')} — ` +
+      'a aprovação só sai quando todos tiverem passado.'
+    );
+  }
+  if (bugs.length > 0) {
+    parts.push(
+      '**Bugs abertos:** ' +
+      bugs.map(b => `#${b.number} (cenário ${b.cenario}${b.existing ? ', já existia' : ''})`).join(', ')
+    );
+  }
+  if (trailer) parts.push(trailer);
+
+  parts.push([
+    '```json spec-wave:qa-results',
+    JSON.stringify({
+      issue,
+      run,
+      verdict,
+      scenarios: results.map(r => ({
+        cenario: r.numero, verdict: r.verdict, evidencia: sanitizeCell(r.evidencia, 400),
+      })),
+    }, null, 2),
+    '```',
+  ].join('\n'));
+
+  return parts.join('\n\n');
+}
+
+/**
+ * bug.md DETERMINÍSTICO de um cenário reprovado (função PURA).
+ *
+ * Exceção documentada à regra "nunca escreva o bug.md à mão" (spec §2.1):
+ * quando o Bug nasce de um cenário de QA reprovado, a reprodução, o
+ * esperado/obtido e o teste de regressão JÁ EXISTEM e são determinísticos — são
+ * o próprio cenário e a saída real da execução. Regenerar por IA só
+ * introduziria alucinação sobre uma execução observada.
+ *
+ * Emite EXATAMENTE as seis seções de REQUIRED_BUG_SECTIONS (o validate compara
+ * byte a byte com `# <seção>`).
+ *
+ * @param {object} params
+ * @param {string} params.title título do Bug (sem o prefixo [BUG])
+ * @param {{anchor, numero, story, criterio, precondicoes, passos, esperado}} params.scenario
+ * @param {string} params.evidence evidência bruta da reprovação
+ * @param {string} params.severity P0–P3
+ * @param {string} [params.headSha] commit do checkout onde a reprova aconteceu
+ * @param {number|null} [params.featureNumber]
+ * @returns {string} markdown
+ */
+export function renderQaBugDoc({
+  title, scenario, evidence, severity, headSha = null, featureNumber = null,
+} = {}) {
+  const [
+    reproducao, esperadoObtido, impacto, causaRaiz, escopo, regressao,
+  ] = REQUIRED_BUG_SECTIONS;
+  const passos = scenario.passos
+    ? scenario.passos
+    : '_(o cenário não declara passos — ver o corpo do cenário no qa-plan.md)_';
+  const pre = scenario.precondicoes ? `**Pré-condições:** ${scenario.precondicoes}\n\n` : '';
+  return [
+    `# [BUG] ${title}`,
+    '',
+    `> Aberto automaticamente pela reprovação do **${scenario.anchor}** do plano de QA` +
+    `${featureNumber ? ` da Feature #${featureNumber}` : ''} (Story #${scenario.story})` +
+    `${headSha ? `, no commit \`${headSha}\`` : ''}. Conteúdo determinístico: cenário + saída real da execução.`,
+    '',
+    `## ${reproducao}`,
+    '',
+    pre + passos,
+    '',
+    `## ${esperadoObtido}`,
+    '',
+    `**Critério:** ${scenario.criterio || '—'}`,
+    '',
+    `**Esperado:** ${scenario.esperado || '—'}`,
+    '',
+    `**Obtido:** ${evidence || '(sem evidência registrada)'}`,
+    '',
+    `## ${impacto}`,
+    '',
+    `Severidade **${severity}**. O critério de aceite acima está descumprido na Story #${scenario.story} — ` +
+    'a Story não avança de 🧪 QA enquanto este Bug estiver aberto.',
+    '',
+    `## ${causaRaiz}`,
+    '',
+    '_A investigar durante a correção — este documento registra uma execução observada, ' +
+    'não uma hipótese de causa._',
+    '',
+    `## ${escopo}`,
+    '',
+    '_A definir na investigação. O fix precisa fazer o cenário abaixo passar sem alterar o critério de aceite._',
+    '',
+    `## ${regressao}`,
+    '',
+    `Re-executar o cenário reprovado após o fix:`,
+    '',
+    '```bash',
+    `npx @spec-wave/cli@latest qa ${scenario.story} --only ${scenario.numero}`,
+    '```',
+    '',
+    `O veredito precisa ser **pass** com o mesmo esperado: ${scenario.esperado || '—'}`,
+    '',
+  ].join('\n');
+}

package/src/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "spec-wave",
   "displayName": "Spec Wave",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "description": "Fluxo spec-driven no GitHub (RFC-001): Projects v2, labels de gatilho, spec/plan gerados por Action, decomposição em duas etapas e implementação orientada a Stories/Tasks.",
   "author": {
     "name": "Astratech",