@spec-wave/cli 0.28.0 → 0.30.0

package/src/lib/qa-exec.mjs

@@ -0,0 +1,314 @@
+// 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));
+}
+
+/**
+ * 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`.');
+  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.');
+
+  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');
+}

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 };
+}