@spec-wave/cli 0.29.0 → 0.32.0

package/src/lib/git-retry.mjs

@@ -0,0 +1,82 @@
+// Push com `pull --rebase` + retry — spec-qa-lead §3.2.
+//
+// O `qa` commita o bug.md no checkout e PUBLICA: com o `qa-lead` despachando N
+// containers em paralelo, um commit que fica só no container morre com ele — e
+// dois containers reprovando ao mesmo tempo fazem o segundo push ser rejeitado.
+// O retry cobre exatamente a rejeição de corrida (`non-fast-forward`,
+// `cannot lock ref`); recusa DELIBERADA do remoto (GH006/branch protegida,
+// auth) falha na primeira, porque repetir uma recusa de política só multiplica
+// o custo — a mesma divisão do isTransientProviderError do lado da IA.
+
+import { execFileSync } from 'node:child_process';
+import { setTimeout as sleep } from 'node:timers/promises';
+
+/** Tentativas de pull+push antes de desistir (teto da spec: 5). */
+export const PUSH_MAX_ATTEMPTS = 5;
+
+// Rejeições que significam "outro push chegou antes" — repetir resolve.
+const TRANSIENT_RE = /non-fast-forward|cannot lock ref|fetch first|failed to push some refs|cannot rebase onto multiple branches|shallow update not allowed/i;
+
+// Recusas de política/credencial — repetir NUNCA resolve.
+const PERMANENT_RE = /GH006|protected branch|permission denied|authentication|403|could not read Username|denied to|no upstream branch|not a git repository|could not resolve host|unable to access/i;
+
+/**
+ * A rejeição de push parece uma corrida perdida? (função PURA)
+ *
+ * Na dúvida (mensagem que não casa com nenhum padrão), transitória: o custo de
+ * uma tentativa a mais é segundos; o de desistir cedo é perder um Bug cujo
+ * cenário já foi pago.
+ *
+ * @param {string} stderr saída de erro do git
+ * @returns {boolean}
+ */
+export function isTransientPushRejection(stderr) {
+  const text = String(stderr || '');
+  if (PERMANENT_RE.test(text)) return false;
+  if (TRANSIENT_RE.test(text)) return true;
+  return true;
+}
+
+function git(cwd, args) {
+  // stderr capturado de propósito: a classificação transitória/permanente
+  // depende de LER a rejeição — `stdio: 'inherit'` a jogaria no terminal.
+  return execFileSync('git', args, { cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] });
+}
+
+/**
+ * `pull --rebase` + `push`, repetindo enquanto a rejeição for de corrida.
+ *
+ * Backoff linear com jitter (1s, 2s, 3s…): os perdedores da corrida se
+ * espalham em vez de colidirem de novo no mesmo instante.
+ *
+ * @param {object} params
+ * @param {string} params.cwd raiz do checkout
+ * @param {number} [params.attempts]
+ * @param {(ms: number) => Promise<void>} [params.delay] injetável nos testes
+ * @returns {Promise<{ ok: boolean, attempts: number, error: string|null }>}
+ */
+export async function pushWithRebase({ cwd, attempts = PUSH_MAX_ATTEMPTS, delay = sleep } = {}) {
+  let lastError = null;
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    try {
+      try {
+        git(cwd, ['pull', '--rebase', '--autostash']);
+      } catch (err) {
+        // Sem upstream configurado o pull falha, mas o push ainda pode passar
+        // (primeiro push da branch) — deixa o push decidir.
+        lastError = String(err.stderr || err.message || err);
+      }
+      git(cwd, ['push']);
+      return { ok: true, attempts: attempt, error: null };
+    } catch (err) {
+      lastError = String(err.stderr || err.message || err);
+      if (!isTransientPushRejection(lastError)) {
+        return { ok: false, attempts: attempt, error: lastError.trim() };
+      }
+      if (attempt < attempts) {
+        await delay(attempt * 1000 + Math.floor(Math.random() * 500));
+      }
+    }
+  }
+  return { ok: false, attempts, error: (lastError || 'push rejeitado').trim() };
+}

package/src/lib/net-cache.mjs

@@ -0,0 +1,142 @@
+// Cache local de leituras do GitHub (I/O fino — as decisões de frescor são
+// puras, em lib/dependency-map.mjs).
+//
+// Vive em `<root>/.spec-wave/cache/` — o diretório de scratch já gitignored:
+// cache é POR CLONE, nunca commitado (o que é commitável é o
+// dependency-map.json, que não expira). Regras que não se negociam:
+//
+//  • best-effort nos dois sentidos: ler cache corrompido devolve null (e
+//    apaga), gravar NUNCA lança — cache indisponível vira refetch, não erro;
+//  • só SUCESSO entra: um `.catch(() => [])` de rede não pode virar uma lista
+//    vazia cacheada por 10 minutos — o dado errado com cara de fresco é pior
+//    que a chamada repetida que o cache existe para evitar;
+//  • entrada de outro owner/repo (worktree, config trocado) é ignorada;
+//  • mutação nunca lê cache e sempre INVALIDA o que tocou.
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+export const CACHE_VERSION = 1;
+
+/** Default do TTL: 10 minutos — cobre um encadeamento order → implement → merge. */
+export const DEFAULT_CACHE_TTL_SEC = 600;
+
+const CACHE_DIR = ['.spec-wave', 'cache'];
+
+/** Caminho absoluto de uma entrada. */
+export function cachePath(root, key) {
+  return path.join(root || process.cwd(), ...CACHE_DIR, `${sanitizeKey(key)}.json`);
+}
+
+// A chave vira nome de arquivo: nada de separadores de caminho.
+function sanitizeKey(key) {
+  return String(key).replace(/[^A-Za-z0-9._-]/g, '_');
+}
+
+/**
+ * TTL efetivo do cache (função PURA).
+ *
+ * Precedência: env `SPEC_WAVE_CACHE_TTL` (segundos; `0` desliga) →
+ * `cache.ttlSec` do .spec-wave.json → 600.
+ *
+ * @param {object|null} config o .spec-wave.json
+ * @param {object} [env]
+ * @returns {number} segundos (0 = desligado)
+ */
+export function resolveCacheTtl(config, env = process.env) {
+  const fromEnv = env?.SPEC_WAVE_CACHE_TTL;
+  if (fromEnv !== undefined && fromEnv !== '') {
+    const n = Number(fromEnv);
+    if (Number.isFinite(n) && n >= 0) return n;
+  }
+  const fromConfig = config?.cache?.ttlSec;
+  if (Number.isFinite(fromConfig) && fromConfig >= 0) return fromConfig;
+  return DEFAULT_CACHE_TTL_SEC;
+}
+
+/**
+ * Lê uma entrada do cache. `null` em qualquer defeito: ausente, JSON inválido,
+ * versão desconhecida, owner/repo (ou extra, ex.: projectId) divergentes.
+ *
+ * @param {string} root raiz do projeto
+ * @param {string} key
+ * @param {{owner?:string, repo?:string, [k:string]: *}} [expect] campos que a
+ *        entrada precisa bater para valer neste contexto
+ * @returns {{ kind:string, fetchedAt:string, data:* }|null}
+ */
+export function readCacheEntry(root, key, expect = {}) {
+  const file = cachePath(root, key);
+  let entry;
+  try {
+    entry = JSON.parse(readFileSync(file, 'utf-8'));
+  } catch {
+    // Corrompida não volta a atrapalhar: apaga best-effort.
+    try { rmSync(file, { force: true }); } catch { /* melhor esforço */ }
+    return null;
+  }
+  if (entry?.v !== CACHE_VERSION || typeof entry.fetchedAt !== 'string') return null;
+  for (const [field, expected] of Object.entries(expect)) {
+    if (expected != null && entry[field] !== expected) return null;
+  }
+  return entry;
+}
+
+/**
+ * Grava uma entrada. NUNCA lança — disco cheio/sem permissão vira no-op.
+ *
+ * @param {string} root
+ * @param {string} key
+ * @param {string} kind ex.: 'board-items'
+ * @param {*} data resultado de uma chamada BEM-SUCEDIDA
+ * @param {object} [extra] campos de contexto (owner, repo, projectId…)
+ * @returns {boolean} true se gravou
+ */
+export function writeCacheEntry(root, key, kind, data, extra = {}) {
+  try {
+    const dir = path.join(root || process.cwd(), ...CACHE_DIR);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(cachePath(root, key), `${JSON.stringify({
+      v: CACHE_VERSION,
+      kind,
+      key: sanitizeKey(key),
+      fetchedAt: new Date().toISOString(),
+      ...extra,
+      data,
+    })}\n`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Remove entradas por chave exata ou prefixo (`'blockedby-*'`). Best-effort.
+ *
+ * Chamada após qualquer ESCRITA que invalide a leitura cacheada — mover board,
+ * mergear, criar issues.
+ *
+ * @param {string} root
+ * @param {...string} keysOrPrefixes
+ */
+export function invalidateCache(root, ...keysOrPrefixes) {
+  const dir = path.join(root || process.cwd(), ...CACHE_DIR);
+  if (!existsSync(dir)) return;
+  let files;
+  try {
+    files = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const spec of keysOrPrefixes) {
+    const raw = String(spec);
+    const isPrefix = raw.endsWith('*');
+    const base = sanitizeKey(isPrefix ? raw.slice(0, -1) : raw);
+    for (const file of files) {
+      const name = file.replace(/\.json$/, '');
+      const hit = isPrefix ? name.startsWith(base) : name === base;
+      if (hit) {
+        try { rmSync(path.join(dir, file), { force: true }); } catch { /* melhor esforço */ }
+      }
+    }
+  }
+}

package/src/lib/next-step.mjs

@@ -17,7 +17,7 @@ import {
   LABEL_SPEC, LABEL_PLAN, LABEL_CRITIQUE, LABEL_DECOMPOSE, LABEL_DECOMPOSE_APPLY,
   LABEL_DECOMPOSE_READY, LABEL_DECOMPOSED, LABEL_BUG, LABEL_BUG_APPROVED,
   LABEL_CRITIQUE_FAILED, LABEL_NEEDS_HUMAN, LABEL_PLAN_APPROVED, LABEL_TRIAGED,
-  LABEL_DUPLICATE, LABEL_WONT_FIX, LABEL_READY, labelNames,
+  LABEL_DUPLICATE, LABEL_WONT_FIX, LABEL_READY, LABEL_QA, LABEL_QA_READY, labelNames,
 } from '../config.mjs';
 import { awaitingMergeBlock } from './artifact-pr.mjs';
 import { isAwaitingMerge } from './doc-source.mjs';
@@ -71,6 +71,15 @@ export const STEPS = {
     trigger: LABEL_BUG, cli: 'generate-bug', writes: 'bug', reads: [],
     types: ['Bug'], creates: false, ai: true,
   },
+  // Fora do pipeline linear de propósito (a geração do plano de QA acontece com
+  // a Feature já implementada, não antes do decompose) — o run só chega aqui
+  // por `--step qa-plan`. A entrada existe pela paridade: `spec-wave:qa` é
+  // label de gatilho de workflow, e toda label de gatilho precisa de EXATAMENTE
+  // uma ação (é o teste de paridade que impede os dois modos de divergirem).
+  'generate-qa-plan': {
+    trigger: LABEL_QA, cli: 'generate-qa-plan', writes: 'qa-plan', reads: ['spec', 'plan'],
+    types: ['Feature'], creates: false, ai: true,
+  },
   // Sem gatilho por label: são decisões humanas, listadas aqui para o `run`
   // saber dizer qual é o próximo movimento em vez de só "nada pendente".
   triage: {
@@ -137,13 +146,14 @@ const TRIGGERS = Object.values(STEPS).map(s => s.trigger).filter(Boolean);
 
 /** Documentos que cada tipo usa, na ordem em que o fluxo os produz. */
 export const DOCS_BY_TYPE = {
-  Feature: ['spec', 'plan', 'decomposition'],
+  Feature: ['spec', 'plan', 'decomposition', 'qa-plan'],
   RFC: ['decomposition'],
   Bug: ['bug'],
 };
 
 const DEFAULT_DOC_PATHS = {
   spec: 'spec.md', plan: 'plan.md', decomposition: 'decomposition.md', bug: 'bug.md',
+  'qa-plan': 'qa-plan.md',
 };
 
 function stepCommand(action, { issueNumber }) {
@@ -184,7 +194,7 @@ function block(code, message, unblock) {
 export function resolveForcedStep(step, { type }) {
   const alias = {
     spec: 'generate-spec', plan: 'generate-plan', bug: 'generate-bug',
-    ready: 'validate', apply: 'decompose-apply',
+    ready: 'validate', apply: 'decompose-apply', 'qa-plan': 'generate-qa-plan',
   };
   const action = alias[step] || step;
   if (!STEPS[action] || STEPS[action].manual) {
@@ -279,6 +289,7 @@ export function nextStep({
   // muda o slug (e o diretório); clone velho não tem o arquivo.
   const claims = [
     [LABEL_PLAN_APPROVED, 'plan'], [LABEL_DECOMPOSED, 'decomposition'], [LABEL_BUG_APPROVED, 'bug'],
+    [LABEL_QA_READY, 'qa-plan'],
   ];
   for (const [label, doc] of claims) {
     if (has(label) && docsOfType.includes(doc) && docState(docs, doc) === 'missing') {
@@ -411,6 +422,7 @@ function pipelineReason(action, { pathOf }) {
     case 'decompose': return `O rascunho \`${pathOf('decomposition')}\` ainda não existe.`;
     case 'decompose-apply': return 'O rascunho foi aprovado pela crítica e espera revisão humana.';
     case 'generate-bug': return `\`${pathOf('bug')}\` ainda não existe.`;
+    case 'generate-qa-plan': return `Gera (ou re-critica) o plano de QA em \`${pathOf('qa-plan')}\`.`;
     default: return 'Próximo passo do fluxo.';
   }
 }

package/src/lib/qa-exec.mjs

@@ -0,0 +1,335 @@
+// Decisões PURAS da execução local do QA (`spec-wave qa <n>`).
+//
+// O comando (commands/qa-run.mjs) coleta o estado — issue, labels, Etapa,
+// plano, resultados — e as decisões moram aqui, testáveis sem rede: quem pode
+// executar (portões do D-QA4), qual o desfecho, e o que entra no contexto que o
+// executor recebe.
+
+import {
+  STAGE_ORDER, STAGE_QA, STAGE_UAT, STAGE_DEPLOY,
+  LABEL_QA, LABEL_QA_READY, LABEL_QA_APPROVED, LABEL_CRITIQUE_FAILED, LABEL_NEEDS_HUMAN,
+  labelNames,
+} from '../config.mjs';
+
+/** Tipos que passam pela execução de QA (spec §3). */
+export const QA_RUNNABLE_TYPES = ['Feature', 'Story', 'Bug'];
+
+/**
+ * Portões de execução (função PURA) — a tabela de recusas do spec §6.2.
+ *
+ * @param {object} params
+ * @param {string|null} params.type tipo canônico da issue-alvo
+ * @param {Array<string|{name:string}>} [params.labels] labels da issue-alvo
+ * @param {Array<string|{name:string}>|null} [params.featureLabels] labels da
+ *        Feature dona do plano (a própria issue quando o alvo é a Feature;
+ *        null quando o alvo é Bug — Bug não passa pelo portão do plano)
+ * @param {string|null} [params.stage] Etapa atual no board (null = não lida)
+ * @returns {{ ok: boolean, exitZero?: boolean, code?: string, message?: string }}
+ */
+export function qaExecutionGate({ type, labels = [], featureLabels = null, stage = null } = {}) {
+  if (!type || !QA_RUNNABLE_TYPES.includes(type)) {
+    return {
+      ok: false,
+      code: 'unsupported-type',
+      message:
+        `O \`qa\` executa Feature, Story ou Bug — esta issue é **${type || 'de tipo desconhecido'}**. ` +
+        (type === 'Task'
+          ? 'Task não passa por QA (vai de 🚧 Desenvolvimento direto a 🎉 Done).'
+          : type === 'Spike'
+            ? 'A Etapa de um Spike é movida só à mão.'
+            : 'RFC, Epic e Initiative não têm validação funcional própria.'),
+    };
+  }
+
+  const names = new Set(labelNames(labels));
+  const featureNames = featureLabels === null ? null : new Set(labelNames(featureLabels));
+
+  // Geração em voo: a label de gatilho ainda está na issue (ou na Feature dona
+  // do plano) — rodar agora executaria um plano que está sendo (re)gerado.
+  if (names.has(LABEL_QA) || featureNames?.has(LABEL_QA)) {
+    return {
+      ok: false,
+      code: 'trigger-pending',
+      message:
+        `A label \`${LABEL_QA}\` ainda está pendente — a geração/crítica do plano está em voo ` +
+        '(ou falhou deixando a label). Aguarde o run terminar, ou remova a label e reaplique.',
+    };
+  }
+
+  // Portão humano da crítica — na Feature dona do plano (Feature/Story) ou na
+  // própria issue (Bug, cuja crítica é a do bug.md).
+  for (const conjunto of [featureNames, names].filter(Boolean)) {
+    for (const label of [LABEL_NEEDS_HUMAN, LABEL_CRITIQUE_FAILED]) {
+      if (conjunto.has(label)) {
+        return {
+          ok: false,
+          code: 'human-gate',
+          message:
+            `A label \`${label}\` está aplicada — a crítica adversarial parou o fluxo. ` +
+            'Corrija o documento apontado no comentário 🔎, remova a label e tente de novo.',
+        };
+      }
+    }
+  }
+
+  // D-QA4: como o verde avança a Etapa sozinho, o portão humano é a REVISÃO DO
+  // PLANO — sem `qa-ready` na Feature, nada roda. Não vale para Bug: o "plano"
+  // dele é a seção Teste de Regressão do bug.md.
+  if (type !== 'Bug' && featureNames !== null && !featureNames.has(LABEL_QA_READY)) {
+    return {
+      ok: false,
+      code: 'plan-not-ready',
+      message:
+        `A Feature dona do plano não tem \`${LABEL_QA_READY}\` — este é o **portão humano** do QA ` +
+        '(D-QA4): o veredito verde avança a Etapa sozinho, então o plano precisa ter passado na ' +
+        `validação + crítica antes. Aplique \`${LABEL_QA}\` na Feature para gerar/criticar o plano.`,
+    };
+  }
+
+  // Etapa: o `qa` não promove item para QA, e a Etapa nunca retrocede.
+  if (stage) {
+    const cur = STAGE_ORDER.indexOf(stage);
+    const qaIdx = STAGE_ORDER.indexOf(STAGE_QA);
+    if (cur !== -1 && cur < qaIdx) {
+      return {
+        ok: false,
+        code: 'stage-before-qa',
+        message:
+          `A issue está em **${stage}**, antes de **${STAGE_QA}** — o \`qa\` não promove item ` +
+          'para QA. Quem move até lá é o merge do PR (`spec-wave merge` / `run --pr`).',
+      };
+    }
+    if (cur !== -1 && cur > qaIdx) {
+      return {
+        ok: true,
+        exitZero: true,
+        code: 'stage-after-qa',
+        message:
+          `A issue já está em **${stage}**, depois de **${STAGE_QA}** — a Etapa nunca retrocede, ` +
+          'nada a executar.',
+      };
+    }
+  }
+
+  return { ok: true };
+}
+
+/**
+ * Para onde o item vai no verde (função PURA).
+ *
+ * Story → 📋 Homologação (aprovação humana de negócio segue existindo);
+ * Bug → 🚀 Deploy (D-QA6: Bug não passa por Homologação);
+ * Feature → 📋 Homologação, mas só quando todas as Stories liberarem (o
+ * chamador decide o "quando" — aqui só o destino).
+ *
+ * @param {string} type
+ * @returns {string} nome da Etapa de destino
+ */
+export function greenTargetStage(type) {
+  return type === 'Bug' ? STAGE_DEPLOY : STAGE_UAT;
+}
+
+/**
+ * A Story pode avançar no verde? (função PURA)
+ *
+ * Guarda DURA do verde: Bug filho ABERTO segura a Story mesmo com todos os
+ * cenários passando — sem isso, um `--only` reaprovaria prematuramente uma
+ * Story cujo defeito ainda não foi corrigido.
+ *
+ * @param {object} params
+ * @param {Array<{number:number, state?:string|null, type?:string|null}>} [params.children]
+ *        sub-issues da Story (o chamador já detectou o tipo de cada uma)
+ * @returns {{ ok: boolean, openBugs: number[] }}
+ */
+export function storyCanAdvance({ children = [] } = {}) {
+  const openBugs = children
+    .filter(c => c.type === 'Bug' && c.state !== 'closed')
+    .map(c => c.number);
+  return { ok: openBugs.length === 0, openBugs };
+}
+
+/**
+ * A Feature pode avançar para 📋 Homologação? (função PURA)
+ *
+ * Mesma regra do Code Review: TODAS as Stories precisam ter `qa-approved` ou já
+ * estar em Homologação+ na ordem canônica. Etapa desconhecida conta como
+ * pendente — na dúvida, a Feature não avança.
+ *
+ * @param {Array<{number:number, labels?:Array, stage?:string|null}>} stories
+ * @returns {{ ok: boolean, pending: number[] }}
+ */
+export function featureCanAdvanceQa(stories = []) {
+  const uatIdx = STAGE_ORDER.indexOf(STAGE_UAT);
+  const pending = stories
+    .filter((s) => {
+      if (labelNames(s.labels || []).includes(LABEL_QA_APPROVED)) return false;
+      const idx = s.stage ? STAGE_ORDER.indexOf(s.stage) : -1;
+      return idx < uatIdx || idx === -1;
+    })
+    .map(s => s.number);
+  return { ok: pending.length === 0, pending };
+}
+
+/**
+ * Extrai a seção "Teste de Regressão" de um bug.md (função PURA).
+ *
+ * É o "plano de QA" de um Bug (spec §3): o cenário único que o `qa <bug>`
+ * executa. Aceita qualquer nível de heading, mesma tolerância do validate.
+ *
+ * @param {string} content bug.md
+ * @returns {string|null} corpo da seção, ou null se ausente/vazia
+ */
+export function extractRegressionSection(content) {
+  const text = String(content ?? '').replace(/\r\n?/g, '\n');
+  const lines = text.split('\n');
+  const start = lines.findIndex(l => /^#{1,6}[ \t]+Teste de Regressão[ \t]*$/i.test(l));
+  if (start === -1) return null;
+  const startLevel = (lines[start].match(/^#+/) || ['#'])[0].length;
+  const body = [];
+  for (let i = start + 1; i < lines.length; i++) {
+    const h = lines[i].match(/^(#{1,6})[ \t]+/);
+    if (h && h[1].length <= startLevel) break;
+    body.push(lines[i]);
+  }
+  const trimmed = body.join('\n').trim();
+  return trimmed || null;
+}
+
+// Substitui os placeholders do comando configurado (mesma regra do implement).
+export function renderQaCommand(template, vars) {
+  return String(template).replace(/\{(\w+)\}/g, (m, key) => (key in vars ? vars[key] : m));
+}
+
+/**
+ * Ambiente entregue ao executor (função PURA) — spec-qa-lead §3.1.
+ *
+ * A env do PROCESSO tem precedência sobre `qa.env`, chave a chave. O motivo é o
+ * paralelismo do `qa-lead`: `qa.env` é versionado com o valor da execução
+ * manual (`BASE_URL: http://localhost:3000`), e N containers simultâneos
+ * precisam cada um do SEU endereço — o Lead injeta o valor real na sessão, sem
+ * placeholder no arquivo (a variação é de runtime, não de configuração).
+ *
+ * @param {Record<string,string>} [configEnv] bloco `qa.env` do .spec-wave.json
+ * @param {Record<string,string>} [processEnv] env do processo (vence)
+ * @returns {Record<string,string>}
+ */
+export function qaProcessEnv(configEnv = {}, processEnv = {}) {
+  return { ...(configEnv || {}), ...(processEnv || {}) };
+}
+
+/**
+ * Monta o contexto entregue ao executor (função PURA).
+ *
+ * As instruções de execução são OBRIGATÓRIAS (spec §6.2): um cenário por vez,
+ * evidência bruta, proibição de corrigir código, `blocked` ≠ `fail` — e o
+ * contrato do arquivo de resultados, que é como o veredito volta para a CLI.
+ *
+ * @param {object} params
+ * @param {string} params.type
+ * @param {{number:number, title:string}} params.issue
+ * @param {string|null} [params.stage]
+ * @param {Array} params.scenarios cenários-alvo, em ordem
+ * @param {string|null} [params.specRel] caminho do spec.md (ponteiro)
+ * @param {string|null} [params.qaPlanRel] caminho do qa-plan.md
+ * @param {Array<{issueNumber:number, kind:string, total:number, items:Array}>} [params.comments]
+ * @param {Array<{number:number, state:string, merged:boolean}>} [params.pullRequests]
+ * @param {string|null} [params.setup] `qa.setup` do .spec-wave.json
+ * @param {string} params.resultFile caminho do JSON de resultados
+ * @returns {string} markdown
+ */
+export function buildQaContext({
+  type, issue, stage = null, scenarios = [], specRel = null, qaPlanRel = null,
+  comments = [], pullRequests = [], setup = null, resultFile,
+} = {}) {
+  const lines = [];
+  lines.push(`# Contexto de QA — ${type} #${issue.number}`);
+  lines.push('');
+  lines.push(`**${type}:** ${issue.title}`);
+  if (stage) lines.push(`**Etapa atual no board:** ${stage}`);
+  if (specRel) lines.push(`**Especificação:** \`${specRel}\` (leia-a para entender os critérios de aceite)`);
+  if (qaPlanRel) lines.push(`**Plano de QA:** \`${qaPlanRel}\``);
+
+  lines.push('');
+  lines.push('## Instruções de execução (OBRIGATÓRIAS)');
+  lines.push('');
+  lines.push('- Execute **um cenário por vez**, na ordem em que aparecem abaixo.');
+  lines.push('- Registre a **evidência bruta** de cada cenário (comando executado, saída, código de status).');
+  lines.push('- **NÃO corrija código.** QA não conserta: cenário reprovado vira Bug. Alterar o código durante a execução **invalida o veredito**.');
+  lines.push('- Cenário que **não pôde ser executado** (ambiente quebrado, seed que falhou, dependência fora do ar) é `blocked`, **nunca** `fail` — `fail` falso cria um Bug falso e custa investigação de dev.');
+  lines.push('- **NÃO escreva no GitHub** (comentar, abrir issue, mover card) — o veredito volta pelo arquivo de resultados; quem escreve no GitHub é a CLI.');
+  lines.push('');
+  lines.push('### Como registrar o veredito');
+  lines.push('');
+  lines.push(`Ao terminar, grave o resultado em \`${resultFile}\` — é deste arquivo que a CLI lê o veredito:`);
+  lines.push('');
+  lines.push('```json');
+  lines.push(JSON.stringify({
+    scenarios: scenarios.slice(0, 1).map(s => ({
+      cenario: s.numero, verdict: 'pass | fail | blocked', evidencia: 'comando + saída + status',
+    })),
+  }, null, 2));
+  lines.push('```');
+  lines.push('');
+  lines.push('Um objeto por cenário-alvo, com o número POSICIONAL do cenário. Nenhum pode ser omitido — se abortar no meio, os cenários não alcançados entram como `blocked` (resultado parcial honesto vale mais que ausência de resultado). Regras duras (a CLI recusa o arquivo fora delas):');
+  lines.push('');
+  lines.push('- `fail` exige `evidencia` não vazia (ela vira o bug.md do Bug aberto);');
+  lines.push('- `blocked` exige `blockedReason`, um de: `ambiente` · `setup-falhou` · `massa-de-dados` · `dependencia-nao-entregue` · `bloqueado-por-bug` · `credencial` · `outro` (este exige `evidencia` com o motivo).');
+
+  if (setup) {
+    lines.push('');
+    lines.push('## Setup do ambiente (rode antes do primeiro cenário)');
+    lines.push('');
+    lines.push('```bash');
+    lines.push(setup);
+    lines.push('```');
+    lines.push('');
+    lines.push('Se o setup falhar, TODOS os cenários são `blocked` — registre a falha como evidência.');
+  }
+
+  lines.push('');
+  lines.push(`## Cenários a executar — NESTA ORDEM (${scenarios.length})`);
+  for (const s of scenarios) {
+    lines.push('');
+    lines.push(`### ${s.anchor} — Story #${s.story}`);
+    lines.push('');
+    lines.push(s.body || [
+      s.criterio ? `**Critério:** ${s.criterio}` : null,
+      s.precondicoes ? `**Pré-condições:** ${s.precondicoes}` : null,
+      s.passos ? `**Passos:**\n${s.passos}` : null,
+      s.esperado ? `**Esperado:** ${s.esperado}` : null,
+    ].filter(Boolean).join('\n'));
+  }
+
+  if (pullRequests.length > 0) {
+    lines.push('');
+    lines.push('## Pull Requests vinculados');
+    lines.push('');
+    for (const pr of pullRequests) {
+      lines.push(`- PR #${pr.number} — ${pr.merged ? 'mergeado' : pr.state}`);
+    }
+  }
+
+  if (comments.length > 0) {
+    lines.push('');
+    lines.push('## Comentários das issues (revisões e correções)');
+    lines.push('');
+    lines.push('> Em conflito com os documentos, o comentário mais recente prevalece.');
+    for (const group of comments) {
+      lines.push('');
+      lines.push(`### Comentários da ${group.kind} #${group.issueNumber}`);
+      if (group.total > group.items.length) {
+        lines.push('');
+        lines.push(`_(mostrando os ${group.items.length} mais recentes de ${group.total})_`);
+      }
+      for (const c of group.items) {
+        lines.push('');
+        lines.push(`**${c.author || c.user?.login || 'desconhecido'}** (${c.createdAt || c.created_at || ''}):`);
+        lines.push('');
+        lines.push(String(c.body || '').trim());
+      }
+    }
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}