@spec-wave/cli 0.29.0 → 0.32.0

package/src/commands/doctor.mjs

@@ -5,6 +5,7 @@
 import { execSync } from 'node:child_process';
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import * as p from '@clack/prompts';
 import chalk from 'chalk';
 import { Octokit } from '@octokit/rest';
@@ -13,15 +14,17 @@ import {
   resolveToken, verifyTokenScopes, describeTokenSource, activeGhAccount,
   tokenMismatchWarning, parseActiveAccount,
 } from '../api/auth.mjs';
-import { getProjectSnapshot, listSubIssues } from '../api/github-graphql.mjs';
+import { getProjectSnapshot, listSubIssues, listProjectItems } from '../api/github-graphql.mjs';
 import { getRepoVariable } from '../api/github-rest.mjs';
 import {
   CONFIG_FILE, WORKFLOW_FILES, ARTIFACT_WORKFLOW_FILES, getProvider, DEFAULT_PROVIDER,
   AI_PROVIDERS, STATUS_OPTIONS,
-  RETIRED_STAGES, ALL_LABELS, allLabelsFor, LABEL_NEEDS_HUMAN, MODEL_LABEL_PREFIX,
+  RETIRED_STAGES, ALL_LABELS, allLabelsFor, LABEL_NEEDS_HUMAN, LABEL_QA_READY, MODEL_LABEL_PREFIX,
   DEFAULT_MAX_CRITIQUE_ATTEMPTS, STAGE_TRACKS, AI_ACTIONS, recommendedModelAliases,
-  modelLabels,
+  modelLabels, STAGE_QA,
 } from '../config.mjs';
+import { slugify } from '../lib/slugify.mjs';
+import { QA_PLAN_FILE } from '../lib/qa-plan-doc.mjs';
 import { findConfigPath } from '../lib/project-root.mjs';
 import { configuredMode, describeModeState, EXECUTION_VARIABLE } from '../lib/execution-mode.mjs';
 import { unguardedWorkflows } from './mode.mjs';
@@ -952,6 +955,182 @@ export function checkSpecKit(ctx) {
   };
 }
 
+/**
+ * Features em 🧪 QA sem qa-plan.md no disco (função PURA — testável sem rede).
+ *
+ * Uma Feature parada em QA sem plano é validação manual sem rastro — o buraco
+ * que o fluxo de QA existe para fechar. Só aviso: gerar o plano é um passo, não
+ * um defeito de configuração.
+ *
+ * @param {object} params
+ * @param {Array<{number, title, state, fields}>} [params.items] itens do board
+ * @param {(rel: string) => boolean} params.exists sonda de existência no disco
+ * @returns {Array<{number: number, rel: string}>}
+ */
+export function featuresInQaWithoutPlan({ items = [], exists = () => false } = {}) {
+  return items
+    .filter(i => i?.number
+      && String(i.state || '').toUpperCase() !== 'CLOSED'
+      && (i.fields?.['Work Item Type'] === 'Feature' || /^\s*\[FEATURE\]/i.test(i.title || ''))
+      && i.fields?.Etapa === STAGE_QA)
+    .map(i => ({ number: i.number, rel: `docs/features/${slugify(i.title || '')}/${QA_PLAN_FILE}` }))
+    .filter(f => !exists(f.rel));
+}
+
+/**
+ * Checks do bloco `qa.lead` (função PURA — rfc/spec-qa-lead.md §6.6).
+ *
+ * `container.image` ausente é "!" e não "✗" de propósito: sem ela a fase A
+ * (`qa-lead plan`) funciona inteira — só a fase B recusa, orientando.
+ *
+ * @param {object} params
+ * @param {object|null} [params.lead] bloco `qa.lead` do .spec-wave.json
+ * @param {boolean|null} [params.dockerOk] docker acessível (null = não sondado)
+ * @param {boolean} [params.schemasOk] protocol/*.json presentes e legíveis
+ * @returns {{ warn: boolean, notes: string[] }}
+ */
+export function inspectQaLead({ lead = null, dockerOk = null, schemasOk = true } = {}) {
+  const notes = [];
+  let warn = false;
+  const backend = lead?.backend === 'sandbox' ? 'sandbox' : 'docker';
+  const image = lead?.container?.image;
+
+  if (!image) {
+    warn = true;
+    notes.push(
+      'qa-lead: `qa.lead.container.image` ausente — a fase B (`qa-lead run`) vai recusar. ' +
+      'A fase A (`qa-lead plan`) funciona sem ela.'
+    );
+  } else {
+    notes.push(`qa-lead: backend ${backend} · imagem ${image}.`);
+  }
+  if (backend === 'sandbox') {
+    warn = true;
+    notes.push(
+      'qa-lead: backend `sandbox` ainda não tem implementação (a API de sessão do ' +
+      'spec-wave-sandbox não existe) — use `docker`.'
+    );
+  } else if (dockerOk === false) {
+    warn = true;
+    notes.push('qa-lead: docker não acessível nesta máquina — a fase B não vai conseguir despachar containers.');
+  }
+  if (!schemasOk) {
+    warn = true;
+    notes.push(
+      'qa-lead: schemas do protocol/ (qa-result.v1.json / qa-trail-report.v1.json) ausentes ou ' +
+      'ilegíveis na instalação da CLI — reinstale o pacote.'
+    );
+  }
+  return { warn, notes };
+}
+
+// QA (rfc/spec-qa-skill.md + rfc/spec-qa-lead.md): executor configurado,
+// Features em 🧪 QA com plano, e a configuração do orquestrador de trilha.
+// As labels novas e o workflow generate-qa-plan.yml são cobertos pelos checks
+// existentes (higiene de labels e workflows), que leem as listas do config.mjs.
+async function checkQa(ctx) {
+  const name = 'QA (qa.command, planos das Features em 🧪 QA e qa-lead)';
+  const notes = [];
+  let status = 'ok';
+
+  const fromEnv = process.env.SPEC_WAVE_QA_CMD;
+  const fromConfig = ctx.cfg?.qa?.command;
+  if (fromEnv) {
+    notes.push(`Executor definido via env SPEC_WAVE_QA_CMD${fromConfig ? ' (sobrepõe o qa.command do config)' : ''}: ${fromEnv}`);
+  } else if (fromConfig) {
+    notes.push(`Executor definido no ${CONFIG_FILE}: ${fromConfig}`);
+  } else {
+    // "!" e não "✗" de propósito: sem executor o `qa` ainda monta o contexto e
+    // orienta — é configuração pendente, não ambiente quebrado.
+    status = 'warn';
+    notes.push(
+      'Nenhum executor configurado — `qa <issue>` só monta o contexto, sem executar os cenários.\n' +
+      `Defina "qa": { "command": "..." } no ${CONFIG_FILE} (ou a env SPEC_WAVE_QA_CMD).\n` +
+      'Placeholders: {contextFile} {qaPlanFile} {specFile} {issue} {type} {title}. Exemplos por agente:\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' +
+      '  Copilot CLI: copilot -p "Execute o QA descrito em {contextFile}" --allow-all-tools'
+    );
+  }
+
+  if (ctx.token && ctx.cfg?.project?.id && ctx.root) {
+    try {
+      const items = await listProjectItems(ctx.token, ctx.cfg.project.id);
+      const semPlano = featuresInQaWithoutPlan({
+        items,
+        exists: rel => existsSync(path.join(ctx.root, rel)),
+      });
+      if (semPlano.length > 0) {
+        status = 'warn';
+        notes.push(
+          `Feature(s) em ${STAGE_QA} sem qa-plan.md no clone: ` +
+          semPlano.map(f => `#${f.number} (${f.rel})`).join(', ') +
+          ' — gere com a label `spec-wave:qa` (ou rode `git pull` se o plano já foi mergeado).'
+        );
+      } else {
+        notes.push(`Nenhuma Feature em ${STAGE_QA} sem plano de QA.`);
+      }
+
+      // Trilha travada no portão da fase B (spec-qa-lead §6.6): Feature em
+      // 🧪 QA sem `qa-ready` faz o `qa-lead run` do milestone dela recusar.
+      const emQa = items.filter(i => i?.number
+        && String(i.state || '').toUpperCase() !== 'CLOSED'
+        && (i.fields?.['Work Item Type'] === 'Feature' || /^\s*\[FEATURE\]/i.test(i.title || ''))
+        && i.fields?.Etapa === STAGE_QA);
+      const semReady = [];
+      for (const item of emQa) {
+        const issue = await makeOctokit(ctx.token).rest.issues
+          .get({ owner: ctx.cfg.owner, repo: ctx.cfg.repo, issue_number: item.number })
+          .catch(() => null);
+        if (!issue) continue;
+        const labels = (issue.data.labels || []).map(l => (typeof l === 'string' ? l : l.name));
+        if (!labels.includes(LABEL_QA_READY)) {
+          semReady.push({ number: item.number, milestone: issue.data.milestone?.title || '(sem milestone)' });
+        }
+      }
+      if (semReady.length > 0) {
+        status = 'warn';
+        notes.push(
+          `Feature(s) em ${STAGE_QA} sem \`${LABEL_QA_READY}\`: ` +
+          semReady.map(f => `#${f.number} [${f.milestone}]`).join(', ') +
+          ' — o `qa-lead run` desses milestones vai recusar; rode `qa-lead plan` e revise os planos.'
+        );
+      }
+    } catch (err) {
+      notes.push(`Features em ${STAGE_QA} não verificáveis agora: ${err.message}`);
+    }
+  } else {
+    notes.push('Features em 🧪 QA não verificadas (sem token, project ou raiz do repo).');
+  }
+
+  // Orquestrador de trilha (spec-qa-lead §6.6).
+  const lead = ctx.cfg?.qa?.lead || null;
+  let dockerOk = null;
+  if (lead?.container?.image && lead?.backend !== 'sandbox') {
+    try {
+      execSync('docker info', { stdio: ['ignore', 'pipe', 'pipe'] });
+      dockerOk = true;
+    } catch {
+      dockerOk = false;
+    }
+  }
+  const protocolDir = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'protocol');
+  const schemasOk = ['qa-result.v1.json', 'qa-trail-report.v1.json'].every((file) => {
+    try {
+      JSON.parse(readFileSync(path.join(protocolDir, file), 'utf-8'));
+      return true;
+    } catch {
+      return false;
+    }
+  });
+  const leadCheck = inspectQaLead({ lead, dockerOk, schemasOk });
+  if (leadCheck.warn) status = status === 'fail' ? 'fail' : 'warn';
+  notes.push(...leadCheck.notes);
+
+  return { name, status, detail: notes.join('\n') };
+}
+
 // Modo de execução: o config e a variável do repositório precisam concordar.
 // Discordar não é detalhe — é o usuário achando que desligou os workflows e
 // continuando a pagar minutos (ou o contrário: tudo pulado e nada rodando).
@@ -1277,6 +1456,7 @@ export async function doctor() {
     checkAi,
     checkDecompositions,
     checkSpecKit,
+    checkQa,
     checkWorkflows,
     checkPrPublishing,
     checkExecutionMode,

package/src/commands/generate-qa-plan.mjs

@@ -0,0 +1,421 @@
+// Gera (ou re-critica) o plano de QA — docs/features/<slug>/qa-plan.md.
+//
+// Espelho do rascunho do decompose, com a mesma semântica de preservação:
+// arquivo AUSENTE → gera via IA, publica em PR e critica; arquivo PRESENTE →
+// valida + critica COMO ESTÁ, sem regerar (edições manuais são o esperado, não
+// a exceção). Para gerar outro do zero: apagar o arquivo e reaplicar
+// `spec-wave:qa`.
+//
+// A ordem interna importa (spec §6.1): a validação DETERMINÍSTICA roda ANTES da
+// crítica — é barata e pega o que não precisa de julgamento (Story descoberta,
+// referência a issue que não é sub-issue, campo obrigatório vazio, truncamento).
+// Só um plano estruturalmente válido gasta uma chamada de crítica.
+
+import { resolveToken } from '../api/auth.mjs';
+import {
+  getIssue, removeLabel, addLabel, commentOnIssue, listIssueComments, getRepoDefaultBranch,
+} from '../api/github-rest.mjs';
+import { getIssueParent, listSubIssues } from '../api/github-graphql.mjs';
+import { detectIssueType } from '../lib/issue-type.mjs';
+import { generateDocument } from '../lib/claude.mjs';
+import { unwrapGeneratedDoc } from '../lib/unwrap-doc.mjs';
+import {
+  runCritique, resolveCritiqueAttempt, renderNeedsHumanComment,
+  parseCritiqueDecisions, applyCritiqueDecisions, renderRiskAcceptedComment,
+} from '../lib/critique.mjs';
+import { recordUsage } from '../lib/usage-report.mjs';
+import { resolveDocDir } from '../lib/doc-paths.mjs';
+import { docBlobUrl } from '../lib/repo-links.mjs';
+import { loadConfig } from '../lib/project-root.mjs';
+import { resolveFlowContext } from '../lib/flow-run.mjs';
+import { publishArtifact } from '../lib/artifact-publish.mjs';
+import { loadArtifact, isAwaitingMerge } from '../lib/doc-source.mjs';
+import { awaitingMergeBlock, renderPrLine } from '../lib/artifact-pr.mjs';
+import { loadPrompt, systemPromptWithTools } from '../lib/prompt-loader.mjs';
+import { buildTechContext } from '../lib/tech-context.mjs';
+import {
+  QA_PLAN_FILE, parseQaPlanDoc, renderQaPlanDoc, validateQaPlan,
+} from '../lib/qa-plan-doc.mjs';
+import {
+  LABEL_QA, LABEL_QA_READY, LABEL_CRITIQUE_FAILED, LABEL_NEEDS_HUMAN,
+  LABEL_RISK_ACCEPTED, DEFAULT_MAX_CRITIQUE_ATTEMPTS, TARGET_LANGUAGE, labelNames,
+} from '../config.mjs';
+
+/**
+ * Parada por decisão do fluxo: o comentário já foi postado; o erro precisa
+ * propagar para o Action ficar vermelho — mesmo contrato do decompose.
+ */
+class QaPlanBlockedError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'QaPlanBlockedError';
+    this.blocked = true;
+  }
+}
+
+// Sobe a cadeia de pais até achar a Feature (mesma mecânica do implement).
+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;
+}
+
+export async function generateQaPlan({ issueNumber }) {
+  const token = await resolveToken();
+  const { owner, repo, mode: runMode } = resolveFlowContext({ command: 'generate-qa-plan' });
+  console.log(`Modo de execução: ${runMode}`);
+
+  const number = parseInt(issueNumber, 10);
+  const issue = await getIssue(token, owner, repo, number);
+  const type = detectIssueType(issue);
+  const labels = labelNames(issue);
+
+  // ── Escopo por tipo (spec §3): o plano é POR FEATURE, arquivo único ────────
+  if (type !== 'Feature') {
+    console.log(`Issue #${number} é ${type || 'desconhecido'} — qa-plan é gerado só para Feature.`);
+    await removeLabel(token, owner, repo, number, LABEL_QA).catch(() => {});
+    if (type === 'Story') {
+      const feature = await resolveParentFeature(token, issue.node_id).catch(() => null);
+      await commentOnIssue(token, owner, repo, number,
+        `ℹ️ **O plano de QA é por Feature, não por Story** (D-QA1). ` +
+        (feature
+          ? `Aplique \`${LABEL_QA}\` na Feature-pai **#${feature.number}** — o plano dela ` +
+            `cobre esta Story com seções \`## Cenário N — Story #${number}\`.`
+          : 'Não encontrei a Feature-pai desta Story — vincule-a como sub-issue de uma Feature e ' +
+            `aplique \`${LABEL_QA}\` lá.`) +
+        `\n\nPara **executar** os cenários desta Story: \`npx @spec-wave/cli@latest qa ${number}\`.`
+      ).catch(() => {});
+    } else if (type === 'Bug') {
+      await commentOnIssue(token, owner, repo, number,
+        `ℹ️ **Bug não gera plano de QA:** o QA de um Bug usa a seção ` +
+        '`Teste de Regressão` do próprio `bug.md`. ' +
+        `Execute direto: \`npx @spec-wave/cli@latest qa ${number}\`.`
+      ).catch(() => {});
+    } else {
+      await commentOnIssue(token, owner, repo, number,
+        `ℹ️ **qa-plan não se aplica a ${type || 'este tipo'}.** ` +
+        'O plano de QA é gerado para **Features** (um arquivo, com cenários por Story).'
+      ).catch(() => {});
+    }
+    return;
+  }
+
+  // ── Portões humanos (spec §6.1 passo 2): falha imediata, com remediação ────
+  for (const [label, remedio] of [
+    [LABEL_NEEDS_HUMAN, 'revise os documentos e remova a label (e a `spec-wave:critique-failed`, se houver)'],
+    [LABEL_CRITIQUE_FAILED, 'corrija o documento apontado no comentário 🔎 e remova a label'],
+  ]) {
+    if (labels.includes(label)) {
+      await removeLabel(token, owner, repo, number, LABEL_QA).catch(() => {});
+      await commentOnIssue(token, owner, repo, number,
+        `⏸️ **generate-qa-plan parado:** a issue tem a label \`${label}\` — ${remedio}, ` +
+        `e reaplique \`${LABEL_QA}\`.`
+      ).catch(() => {});
+      throw new QaPlanBlockedError(`portão humano pendente: ${label}`);
+    }
+  }
+
+  const { config, root } = loadConfig();
+  const { rel: dirRel } = resolveDocDir(root, issue, type);
+  const docRel = `${dirRel}/${QA_PLAN_FILE}`;
+  const base = await getRepoDefaultBranch(token, owner, repo).catch(() => null);
+
+  const ler = (doc, pathRel) => loadArtifact({
+    token, owner, repo, root, pathRel, doc, issueNumber: number, base,
+  });
+
+  // ── spec.md e plan.md são a matéria-prima (spec §6.1 passo 3) ──────────────
+  const spec = await ler('spec', `${dirRel}/spec.md`);
+  const plan = await ler('plan', `${dirRel}/plan.md`);
+  for (const [nome, doc] of [['spec.md', spec], ['plan.md', plan]]) {
+    if (isAwaitingMerge(doc.state)) {
+      const bloqueio = awaitingMergeBlock({
+        pathRel: `${dirRel}/${nome}`, state: doc.state, pr: doc.pr, branch: doc.ref,
+      });
+      await removeLabel(token, owner, repo, number, LABEL_QA).catch(() => {});
+      await commentOnIssue(token, owner, repo, number,
+        `⏸️ **generate-qa-plan parado:** ${bloqueio.message}\n\n${bloqueio.unblock}\n\n` +
+        `Reaplique \`${LABEL_QA}\` depois do merge.`
+      ).catch(() => {});
+      throw new QaPlanBlockedError(bloqueio.message);
+    }
+  }
+  const ausentes = [['spec.md', spec], ['plan.md', plan]]
+    .filter(([, doc]) => doc.content == null).map(([nome]) => nome);
+  if (ausentes.length > 0) {
+    console.log(`Documentos ausentes: ${ausentes.join(', ')} — nada gerado.`);
+    await removeLabel(token, owner, repo, number, LABEL_QA).catch(() => {});
+    await commentOnIssue(token, owner, repo, number,
+      `ℹ️ **Plano de QA não gerado:** falta ${ausentes.map(a => `\`${a}\``).join(' e ')} em \`${dirRel}/\`. ` +
+      'O plano deriva dos critérios de aceite da spec — gere e valide spec/plan primeiro, ' +
+      `depois reaplique \`${LABEL_QA}\`.`
+    ).catch(() => {});
+    return;
+  }
+
+  // ── Stories da Feature: o plano mapeia cenário → Story real ────────────────
+  let subIssues = [];
+  try {
+    subIssues = await listSubIssues(token, issue.node_id);
+  } catch (err) {
+    // Sem a árvore não há como validar as referências `Story #X` — e um plano
+    // publicado sem essa checagem é o que a validação determinística existe
+    // para impedir.
+    await removeLabel(token, owner, repo, number, LABEL_QA).catch(() => {});
+    await commentOnIssue(token, owner, repo, number,
+      `❌ **generate-qa-plan falhou:** não consegui listar as sub-issues da Feature ` +
+      `(${err.message}). Reaplique \`${LABEL_QA}\` para tentar de novo.`
+    ).catch(() => {});
+    throw new QaPlanBlockedError(`sub-issues não legíveis: ${err.message}`);
+  }
+  const stories = subIssues.filter(s => detectIssueType({ title: s.title, labels: s.labels }) === 'Story');
+  if (stories.length === 0) {
+    console.log('Feature sem Stories — nada a planejar.');
+    await removeLabel(token, owner, repo, number, LABEL_QA).catch(() => {});
+    await commentOnIssue(token, owner, repo, number,
+      'ℹ️ **Plano de QA não gerado:** a Feature não tem Stories (sub-issues). ' +
+      `Decomponha primeiro (\`spec-wave:decompose\`) e reaplique \`${LABEL_QA}\`.`
+    ).catch(() => {});
+    return;
+  }
+
+  const usageEntries = [];
+  try {
+    await runDraftOrCritique({
+      token, owner, repo, issue, number, labels, config, root, runMode,
+      dirRel, docRel, base, spec, plan, stories, usage: usageEntries, ler,
+    });
+  } catch (err) {
+    if (!err.blocked) {
+      await removeLabel(token, owner, repo, number, LABEL_QA).catch(() => {});
+      await commentOnIssue(token, owner, repo, number,
+        '❌ **Falha ao gerar o plano de QA**\n\n' +
+        `\`\`\`\n${err.message}\n\`\`\`\n\n` +
+        `A label \`${LABEL_QA}\` foi removida para destravar o gatilho — ` +
+        'adicione-a de novo para tentar outra vez.'
+      ).catch(() => {});
+    }
+    throw err;
+  } finally {
+    await recordUsage({ token, owner, repo, issueNumber: number, entries: usageEntries });
+  }
+}
+
+async function runDraftOrCritique(ctx) {
+  const {
+    token, owner, repo, issue, number, labels, config, root, runMode,
+    dirRel, docRel, base, spec, plan, stories, usage, ler,
+  } = ctx;
+
+  // Plano existente é preservado COMO ESTÁ — inclusive o que vive num PR ainda
+  // não mergeado (é lá que o revisor edita). Mesma invariante do decompose.
+  const existente = await ler('qa-plan', docRel);
+
+  let markdown;
+  let publicado = null;
+  if (existente.content != null) {
+    const onde = existente.state === 'pending-pr'
+      ? `no PR #${existente.pr?.number} (ainda não mergeado)`
+      : existente.state === 'branch-only'
+        ? `na branch ${existente.ref} (sem PR aberto)`
+        : docRel;
+    console.log(`Plano encontrado ${onde} — validando e criticando o arquivo como está (sem regerar).`);
+    markdown = existente.content;
+    if (isAwaitingMerge(existente.state)) {
+      publicado = { pr: existente.pr, branch: existente.ref, unchanged: true };
+    }
+  } else {
+    console.log(`Gerando plano de QA para: ${issue.title}`);
+    const payload = {
+      feature: { number, title: issue.title },
+      stories: stories.map(s => ({ number: s.number, title: s.title, body: s.body || '' })),
+      spec: spec.content,
+      plan: plan.content,
+    };
+    const userContent =
+      'Gere o qa-plan.md a partir deste payload JSON. Os números de Story dos títulos ' +
+      '"## Cenário N — Story #X" DEVEM sair da lista `stories` abaixo — nunca invente números.\n\n' +
+      JSON.stringify(payload, null, 2);
+
+    const qaPrompt = loadPrompt('qa', { cwd: root });
+    const { content: bruto } = await generateDocument(
+      systemPromptWithTools(qaPrompt),
+      userContent,
+      {
+        action: 'qa', maxTurns: qaPrompt.maxTurns, labels, usage,
+        lint: { lang: TARGET_LANGUAGE }, withReport: true,
+      }
+    );
+
+    // parse + render canônico: o arquivo nasce com marcador, numeração por
+    // posição e H1 — mesmo que o modelo tenha errado qualquer um dos três.
+    let gerado;
+    try {
+      gerado = parseQaPlanDoc(unwrapGeneratedDoc(bruto), { requireMarker: false });
+    } catch (err) {
+      throw new Error(`o modelo devolveu um plano fora do formato: ${err.message}`);
+    }
+    markdown = renderQaPlanDoc({
+      title: issue.title,
+      issueNumber: number,
+      scenarios: gerado.scenarios.map(s => ({ story: s.story, body: s.body })),
+    });
+    publicado = await publishArtifact({
+      token, owner, repo, doc: 'qa-plan',
+      issueNumber: number, issueTitle: issue.title, issueUrl: issue.html_url,
+      pathRel: docRel, content: markdown, base,
+    });
+    if (publicado.warning) console.warn(`⚠️  ${publicado.warning}`);
+    console.log(`Plano publicado em ${publicado.branch} (${docRel}).`);
+  }
+
+  const refDoDocumento = publicado?.branch || existente.ref || undefined;
+  const blobUrl = docBlobUrl({
+    owner, repo, pathRel: docRel, mode: runMode, root, ref: refDoDocumento,
+  });
+
+  // ── Estrutura antes de qualquer gasto: parse do arquivo como está ──────────
+  let doc;
+  try {
+    doc = parseQaPlanDoc(markdown);
+  } catch (err) {
+    await commentOnIssue(token, owner, repo, number,
+      `❌ **Não consegui ler o plano de QA.**\n\n` +
+      `\`\`\`\n${err.message}\n\`\`\`\n\n` +
+      `Corrija [\`${docRel}\`](${blobUrl}) e reaplique \`${LABEL_QA}\`. ` +
+      'Para começar de novo do zero, apague o arquivo.'
+    ).catch(() => {});
+    await removeLabel(token, owner, repo, number, LABEL_QA).catch(() => {});
+    throw new QaPlanBlockedError(err.message);
+  }
+
+  // ── Validação determinística (spec §6.1 passo 5) — antes da crítica ────────
+  const errosDeterministicos = validateQaPlan({ doc, stories, content: markdown });
+  if (errosDeterministicos.length > 0) {
+    console.log(`Validação determinística reprovou: ${errosDeterministicos.length} problema(s) — crítica não executada.`);
+    await commentOnIssue(token, owner, repo, number,
+      '⚠️ **Plano de QA reprovado na validação determinística** (a crítica adversarial ' +
+      'nem chegou a rodar — nada de IA foi gasto):\n\n' +
+      errosDeterministicos.map(e => `- ${e}`).join('\n') +
+      `\n\nCorrija [\`${docRel}\`](${blobUrl}) e reaplique \`${LABEL_QA}\`.`
+    ).catch(() => {});
+    await removeLabel(token, owner, repo, number, LABEL_QA).catch(() => {});
+    throw new QaPlanBlockedError(
+      `validação determinística reprovou o plano: ${errosDeterministicos[0]}`
+    );
+  }
+  console.log(`Plano válido: ${doc.scenarios.length} cenário(s) cobrindo ${stories.length} Story(ies).`);
+
+  // ── Crítica adversarial (kind 'qa') — mesma máquina de tentativas ──────────
+  const comments = await listIssueComments(token, owner, repo, number).catch(err => {
+    console.warn(`Não foi possível listar comentários: ${err.message} — contador de tentativas em 1.`);
+    return [];
+  });
+  const maxAttempts = Number.isInteger(config?.ai?.maxCritiqueAttempts) && config.ai.maxCritiqueAttempts > 0
+    ? config.ai.maxCritiqueAttempts
+    : DEFAULT_MAX_CRITIQUE_ATTEMPTS;
+  const escalationModel = config?.ai?.escalationModel || null;
+  const { attempt, blocked } = resolveCritiqueAttempt({ comments, labels, kind: 'qa', maxAttempts });
+  const decisions = parseCritiqueDecisions(comments, 'qa');
+
+  if (blocked) {
+    console.log(`Teto de ${maxAttempts} tentativas de crítica atingido — exigindo revisão humana.`);
+    await commentOnIssue(token, owner, repo, number,
+      renderNeedsHumanComment({ kind: 'qa', attempt, maxAttempts, escalationModel })).catch(() => {});
+    await addLabel(token, owner, repo, number, LABEL_NEEDS_HUMAN);
+    await removeLabel(token, owner, repo, number, LABEL_QA);
+    throw new QaPlanBlockedError(
+      `A crítica reprovou ${maxAttempts - 1}x seguidas. Label ${LABEL_NEEDS_HUMAN} aplicada.`
+    );
+  }
+
+  const model = attempt > 1 ? (escalationModel || undefined) : undefined;
+  if (model) console.log(`Tentativa ${attempt}: escalando a crítica para ${model}.`);
+
+  // Contexto da crítica (spec §6.1 passo 6): spec, plan, decomposition e
+  // tech_context — os documentos contra os quais o plano precisa se sustentar.
+  const decomposition = await ler('decomposition', `${dirRel}/decomposition.md`).catch(() => null);
+  const techContextYaml = buildTechContext({ issueBody: issue.body || '', cwd: root || process.cwd() }).yaml;
+
+  let critique;
+  try {
+    critique = await runCritique({
+      kind: 'qa',
+      spec: spec.content,
+      plan: plan.content,
+      decomposition: decomposition?.content || undefined,
+      techContextYaml,
+      qaPlan: markdown,
+      decisions,
+      attempt, maxAttempts, model, labels, usage, cwd: root || undefined,
+    });
+  } catch (err) {
+    // O verde do QA é automático (D-QA3), então o portão do plano não pode ser
+    // pulado: sem crítica não há `qa-ready`, e o run fica vermelho.
+    await commentOnIssue(token, owner, repo, number,
+      `❌ **A crítica adversarial do plano de QA não concluiu.**\n\n` +
+      `\`\`\`\n${err.message}\n\`\`\`\n\n` +
+      `O plano está em [\`${docRel}\`](${blobUrl}), mas **sem crítica não há liberação** — ` +
+      `o verde do QA avança o board sozinho, e este é o portão. Reaplique \`${LABEL_QA}\`.`
+    ).catch(() => {});
+    await removeLabel(token, owner, repo, number, LABEL_QA).catch(() => {});
+    throw new QaPlanBlockedError(`Crítica adversarial não concluiu: ${err.message}`);
+  }
+
+  await commentOnIssue(token, owner, repo, number, critique.markdown)
+    .catch(err => console.warn(`Falha ao comentar a crítica: ${err.message}`));
+
+  const { blocking, accepted } = applyCritiqueDecisions(critique.findings, decisions, 'qa');
+  if (accepted.length > 0) {
+    await addLabel(token, owner, repo, number, LABEL_RISK_ACCEPTED).catch(() => {});
+    await commentOnIssue(token, owner, repo, number,
+      renderRiskAcceptedComment({ kind: 'qa', accepted })).catch(() => {});
+  }
+  if (blocking.length > 0) {
+    console.log(`Crítica apontou ${blocking.length} finding(s) GRAVE(s) sem decisão.`);
+    await addLabel(token, owner, repo, number, LABEL_CRITIQUE_FAILED);
+    await removeLabel(token, owner, repo, number, LABEL_QA_READY).catch(() => {});
+    await removeLabel(token, owner, repo, number, LABEL_QA);
+    throw new QaPlanBlockedError(
+      `A crítica adversarial apontou findings graves no plano (tentativa ${attempt}). ` +
+      `Corrija ${docRel} e reaplique ${LABEL_QA}.`
+    );
+  }
+  await removeLabel(token, owner, repo, number, LABEL_CRITIQUE_FAILED).catch(() => {});
+
+  // ── Liberação: qa-ready = passou na validação + crítica, espera humano ─────
+  await addLabel(token, owner, repo, number, LABEL_QA_READY);
+  await removeLabel(token, owner, repo, number, LABEL_QA);
+
+  const porStory = new Map();
+  for (const s of doc.scenarios) porStory.set(s.story, (porStory.get(s.story) || 0) + 1);
+  const resumo = [...porStory.entries()]
+    .map(([story, n]) => `- Story #${story}: ${n} cenário(s)`)
+    .join('\n');
+
+  const pr = publicado?.pr;
+  const revisao = pr?.number
+    ? `${renderPrLine(publicado)}\n\n**Revise o plano no PR** (edite o que precisar — as edições ` +
+      'são preservadas) e faça o merge. '
+    : '**Revise o plano** (edite o que precisar — as edições são preservadas). ';
+
+  await commentOnIssue(token, owner, repo, number,
+    `🧪 **Plano de QA pronto para revisão humana** (${doc.scenarios.length} cenário(s)).\n\n` +
+    `📄 Arquivo: [\`${docRel}\`](${blobUrl})\n\n${resumo}\n\n` +
+    'A crítica adversarial não encontrou problemas graves e a label ' +
+    `\`${LABEL_QA_READY}\` foi aplicada — **ela é o portão humano**: o veredito verde da ` +
+    'execução avança a Etapa sozinho, então revise os cenários ANTES de rodar.\n\n' +
+    revisao +
+    'Depois execute localmente:\n' +
+    `\`\`\`\nnpx @spec-wave/cli@latest qa ${number} --dry-run\nnpx @spec-wave/cli@latest qa ${number}\n\`\`\`\n` +
+    `Para uma nova crítica depois de editar, reaplique \`${LABEL_QA}\` — o arquivo é ` +
+    'criticado como está, sem ser regerado. Para gerar outro do zero, apague o arquivo.'
+  ).catch(err => console.warn(`Falha ao comentar a liberação: ${err.message}`));
+  console.log(`Plano de QA liberado para revisão (${doc.scenarios.length} cenário(s)).`);
+  return { pr: pr || null };
+}