@spec-wave/cli 0.28.0 → 0.30.0

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

package/src/commands/implement.mjs

@@ -412,6 +412,18 @@ export function buildFeatureContext({
     `Enquanto houver Story pendente, a Feature permanece em ${STAGE_DEVELOPMENT}.`
   );
   lines.push('');
+  // O trecho pós-implementação era o único do fluxo inteiramente manual — e o
+  // merge de PRs empilhados é ordem-dependente (apagar a branch do primeiro já
+  // fechou o segundo). O contexto termina apontando o comando que encapsula a
+  // sequência segura, em vez de deixar a mecânica por conta de quem mergeia.
+  lines.push(
+    '**Ao terminar, informe no relatório final:** os PRs ficam **empilhados** (cada um baseado no anterior) — ' +
+    'o merge é **ordem-dependente**. Depois da revisão humana (marcar cada PR como pronto), o merge é ' +
+    `\`npx @spec-wave/cli@latest merge ${feature.number}\`: ele mergeia na ordem das dependências, ` +
+    'reaponta as bases, move o board até 🧪 QA e só apaga as branches no fim. ' +
+    '**NUNCA** mergeie um PR da pilha com `--delete-branch` à mão — apagar a branch antes de reapontar o dependente fecha o PR seguinte.'
+  );
+  lines.push('');
   lines.push(boardRuleBlockquote());
 
   if (skipped.length > 0) {