@spec-wave/cli 0.28.0 → 0.30.0

package/src/commands/run.mjs

@@ -81,7 +81,7 @@ export function lockPath(root, key) {
   return path.join(gitCommonDir(root), 'spec-wave', `run-${key}.lock`);
 }
 
-function acquireLock(root, key) {
+export function acquireLock(root, key) {
   const file = lockPath(root, key);
   mkdirSync(path.dirname(file), { recursive: true });
   const payload = JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() });
@@ -108,7 +108,7 @@ function acquireLock(root, key) {
   }
 }
 
-function releaseLock(file) {
+export function releaseLock(file) {
   try {
     if (file) unlinkSync(file);
   } catch { /* já removido */ }
@@ -137,7 +137,7 @@ function localDocStates(issue, type, root) {
   const paths = featureDocPaths(root, issue, type);
   const docs = {};
   const docPaths = {};
-  for (const nome of ['spec', 'plan', 'decomposition']) {
+  for (const nome of ['spec', 'plan', 'decomposition', 'qa-plan']) {
     docs[nome] = existsSync(paths[nome].abs) ? 'local' : 'missing';
     docPaths[nome] = paths[nome].rel;
   }
@@ -305,6 +305,10 @@ async function dispatch(action, { issueNumber }) {
       const { generateBug } = await import('./generate-bug.mjs');
       return await generateBug({ issueNumber });
     }
+    case 'generate-qa-plan': {
+      const { generateQaPlan } = await import('./generate-qa-plan.mjs');
+      return await generateQaPlan({ issueNumber });
+    }
     default:
       throw new Error(`Passo sem despacho: ${action}`);
   }
@@ -348,7 +352,8 @@ async function runForPr({ prNumber, dryRun, yes, only, json }) {
     process.exitCode = decision.blocked ? 2 : 0;
     return decision;
   }
-  if (verdict.changesRequestedAfterApproval && !yes) {
+  // Mergeado, o pedido de mudanças pré-merge já foi decidido por quem mergeou.
+  if (verdict.changesRequestedAfterApproval && !pr.merged_at && !yes) {
     console.log(chalk.yellow('\n⛔ needs-confirmation: há pedido de mudanças além da aprovação. Confirme com `--yes`.'));
     process.exitCode = 2;
     return decision;

package/src/config.mjs

@@ -54,7 +54,7 @@ export const DEFAULT_PROVIDER = 'anthropic';
 // Ações de IA que podem ter modelo próprio no .spec-wave.json (bloco
 // `ai.models`, ex.: { "critique": "claude-opus-4-1" }). Resolvidas em runtime
 // por resolveAiConfig() em src/lib/claude.mjs.
-export const AI_ACTIONS = ['spec', 'plan', 'decompose', 'critique', 'bug'];
+export const AI_ACTIONS = ['spec', 'plan', 'decompose', 'critique', 'bug', 'qa'];
 
 // Override de modelo POR EXECUÇÃO: a label `spec-wave:model:<apelido>` na issue
 // aponta para uma entrada de `ai.modelAliases` do .spec-wave.json. Serve para
@@ -346,6 +346,17 @@ export const LABEL_DEV_AGENT = 'spec-wave:dev-agent';
 export const LABEL_BUG = 'spec-wave:bug';
 export const LABEL_BUG_APPROVED = 'spec-wave:bug-approved';
 
+// Fluxo de QA (rfc/spec-qa-skill.md). O gatilho gera (ou re-critica) o
+// qa-plan.md; as duas de estado são gravadas pelas automações, nunca à mão.
+//
+// ⚠️ `spec-wave:qa-ready` NÃO é `spec-wave:ready`: a primeira é ESTADO do plano
+// de QA (passou na crítica, espera revisão humana — o portão do D-QA4); a
+// segunda é o GATILHO da validação de spec/plan. Nenhuma checagem pode usar
+// prefixo (`startsWith('spec-wave:ready')`) para distinguir as duas.
+export const LABEL_QA = 'spec-wave:qa';
+export const LABEL_QA_READY = 'spec-wave:qa-ready';
+export const LABEL_QA_APPROVED = 'spec-wave:qa-approved';
+
 // Desfecho da triagem do PM (RFC-004 §4.1). São mutuamente exclusivas: um bug
 // triado foi aceito, rejeitado ou marcado como duplicata.
 export const LABEL_TRIAGED = 'spec-wave:triaged';
@@ -432,6 +443,9 @@ export const TRIGGER_LABELS = [
   { name: LABEL_DEV_AGENT,           color: '5319E7', description: 'Enfileira a issue para o dev-agent autônomo' },
   { name: LABEL_BUG,                 color: 'BFD4F2', description: 'Gerar bug.md via GitHub Action' },
   { name: LABEL_BUG_APPROVED,        color: '0E8A16', description: 'bug.md validado (reprodução, causa raiz e teste de regressão)' },
+  { name: LABEL_QA,                  color: 'BFD4F2', description: 'Gerar/re-criticar o plano de QA (qa-plan.md) via GitHub Action' },
+  { name: LABEL_QA_READY,            color: '0E8A16', description: 'Plano de QA aprovado pela crítica — revise-o e rode `spec-wave qa <n>`' },
+  { name: LABEL_QA_APPROVED,         color: '0E8A16', description: 'Execução do QA passou em todos os cenários' },
   { name: LABEL_TRIAGED,             color: '0E8A16', description: 'Bug triado pelo PM (severidade, origem e pai definidos)' },
   { name: LABEL_DUPLICATE,           color: 'EDEDED', description: 'Duplicata de outra issue (o corpo aponta qual)' },
   { name: LABEL_WONT_FIX,            color: 'EDEDED', description: 'Rejeitado na triagem — não será corrigido' },
@@ -515,6 +529,7 @@ export const WORKFLOW_FILES = [
   'generate-spec.yml',
   'validate.yml',
   'decompose.yml',
+  'generate-qa-plan.yml',
   'code-review.yml',
   'qa.yml',
 ];
@@ -535,6 +550,7 @@ export const ARTIFACT_WORKFLOW_FILES = [
   'generate-plan.yml',
   'generate-bug.yml',
   'decompose.yml',
+  'generate-qa-plan.yml',
 ];
 
 export const ISSUE_TEMPLATE_FILES = [

package/src/lib/artifact-pr.mjs

@@ -34,6 +34,7 @@ export const ARTIFACT_DOCS = {
   bug: { suffix: 'bug', file: 'bug.md' },
   decomposition: { suffix: 'decompose', file: 'decomposition.md' },
   'decomposition-apply': { suffix: 'decompose-apply', file: 'decomposition.md' },
+  'qa-plan': { suffix: 'qa-plan', file: 'qa-plan.md' },
 };
 
 /** Nomes aceitos em `doc`, na ordem do fluxo. */
@@ -102,6 +103,7 @@ const DOC_LABEL = {
   bug: 'documento de bug',
   decomposition: 'rascunho de decomposição',
   'decomposition-apply': 'registro das issues criadas',
+  'qa-plan': 'plano de QA',
 };
 
 /**

package/src/lib/board.mjs

@@ -218,11 +218,27 @@ export async function advanceToStage(
     const current = await getItemSingleSelectValue(token, itemId, etapaField.id).catch(() => null);
     if (!shouldAdvanceStage(current, targetStage)) return false;
     const optionId = etapaField.options?.[targetStage];
-    if (optionId) await setItemSingleSelect(token, project.id, itemId, etapaField.id, optionId);
+    // Opção que não resolve é board divergente (coluna renomeada, init de outra
+    // versão) — pular a escrita e devolver true fazia o chamador imprimir ✅
+    // sem nada ter sido escrito. Melhor falhar nomeando o que faltou.
+    if (!optionId) {
+      throw new Error(
+        `A Etapa "${targetStage}" não existe no board (opções: ` +
+        `${Object.keys(etapaField.options || {}).join(', ') || 'nenhuma'}). ` +
+        'O board divergiu da config — rode `spec-wave refresh` ou renomeie a coluna de volta.'
+      );
+    }
+    await setItemSingleSelect(token, project.id, itemId, etapaField.id, optionId);
   }
   if (statusField?.id && targetStatus) {
     const optionId = statusField.options?.[targetStatus];
-    if (optionId) await setItemSingleSelect(token, project.id, itemId, statusField.id, optionId);
+    if (!optionId) {
+      throw new Error(
+        `O Status "${targetStatus}" não existe no board (opções: ` +
+        `${Object.keys(statusField.options || {}).join(', ') || 'nenhuma'}).`
+      );
+    }
+    await setItemSingleSelect(token, project.id, itemId, statusField.id, optionId);
   }
   return true;
 }

package/src/lib/critique.mjs

@@ -44,12 +44,16 @@ export const CRITIQUE_TOOL_NAME = 'registrar_findings';
 // Rótulo do artefato auditado, por contexto — usado no cabeçalho do comentário.
 const KIND_LABEL = {
   plan: 'plan.md', stories: 'decomposition.md', bug: 'bug.md', spec: 'spec.md',
+  conjunto: 'specs da milestone (conjunto)', qa: 'qa-plan.md',
 };
 
 // Prompt por tipo de auditoria. 'plan' audita o plan.md contra a spec;
-// 'stories' audita a decomposição proposta contra spec + plan.
+// 'stories' audita a decomposição proposta contra spec + plan; 'conjunto'
+// audita TODAS as specs de uma milestone entre si — é a única cujo objeto é a
+// relação entre documentos, não um documento.
 const KIND_PROMPT = {
   plan: 'plan/critique', stories: 'decompose/critique', bug: 'bug/critique', spec: 'spec/critique',
+  conjunto: 'audit/critique', qa: 'qa/critique',
 };
 
 // A decomposição virou arquivo revisável (decomposition.md): um finding só é
@@ -62,6 +66,20 @@ const ANCHOR_RULE = `Cada finding DEVE citar, no campo "anchor", o trecho audita
 - "geral" quando o problema for da decomposição como um todo (ex.: requisito da spec que nenhuma Story cobre).
 Use EXATAMENTE os números que aparecem nos títulos "## Story N — ..." e "### Task N.M — ..." do documento.`;
 
+// O qa-plan.md tem a mesma necessidade da decomposição: o finding precisa dizer
+// QUAL cenário está errado, e o título "## Cenário N" é a âncora estável.
+const QA_ANCHOR_RULE = `Cada finding DEVE citar, no campo "anchor", o trecho auditado:
+- "Cenário N" para um problema no Cenário N (ex.: "Cenário 3");
+- "geral" quando o problema for do plano como um todo (ex.: critério de aceite da spec que nenhum cenário cobre).
+Use EXATAMENTE os números que aparecem nos títulos "## Cenário N — Story #X" do documento.`;
+
+// No conjunto o achado vive ENTRE documentos: sem dizer quais, o leitor relê a
+// milestone inteira procurando o par. O campo é validado como array de números
+// de issue — é o equivalente da âncora "Story N" para este contexto.
+const FEATURES_RULE = `Cada finding DEVE listar, no campo "features", os números das issues das Features envolvidas
+(ex.: [412, 415] para uma contradição entre as duas; [412] quando o problema é de uma spec só,
+visto à luz das outras). Use EXATAMENTE os números que aparecem nos títulos "## spec.md — #N ..." fornecidos.`;
+
 /**
  * Monta o system prompt da crítica: corpo editável + contrato de máquina.
  *
@@ -79,7 +97,9 @@ Use EXATAMENTE os números que aparecem nos títulos "## Story N — ..." e "###
  */
 function buildSystemPrompt(kind, cwd) {
   const prompt = loadPrompt(KIND_PROMPT[kind] || KIND_PROMPT.plan, ...(cwd ? [{ cwd }] : []));
-  const anchor = kind === 'stories' ? `\n\n${ANCHOR_RULE}` : '';
+  const anchor = kind === 'stories' ? `\n\n${ANCHOR_RULE}`
+    : kind === 'qa' ? `\n\n${QA_ANCHOR_RULE}`
+    : kind === 'conjunto' ? `\n\n${FEATURES_RULE}` : '';
 
   const contract = `## Contrato de saída
 
@@ -134,6 +154,24 @@ function critiqueJsonSchema(kind) {
     };
     required.push('anchor');
   }
+  if (kind === 'qa') {
+    properties.anchor = {
+      type: 'string',
+      description: 'Âncora do trecho auditado: "Cenário N" ou "geral".',
+    };
+    required.push('anchor');
+  }
+  if (kind === 'conjunto') {
+    properties.features = {
+      type: 'array',
+      items: { type: 'integer' },
+      minItems: 1,
+      description:
+        'Números das issues das Features envolvidas no finding — os "#N" dos títulos ' +
+        '"## spec.md — #N ..." fornecidos.',
+    };
+    required.push('features');
+  }
   return {
     type: 'object',
     properties: {
@@ -172,14 +210,14 @@ function describe(value) {
   return typeof value === 'object' ? 'um objeto' : `${typeof value} (${JSON.stringify(value).slice(0, 60)})`;
 }
 
-const ANCHOR_RE = /^(story|task)[ \t]*(\d+(?:\.\d+)?)$/i;
+const ANCHOR_RE = /^(story|task|cen[aá]rio)[ \t]*(\d+(?:\.\d+)?)$/i;
 
 /**
  * Normaliza a âncora de um finding (função PURA).
  *
- * Aceita "Story 3", "story3", "TASK 3.2". Qualquer outra coisa — inclusive
- * "geral" — vira ausência de âncora: melhor não citar do que citar errado e
- * mandar o humano para o trecho errado do documento.
+ * Aceita "Story 3", "story3", "TASK 3.2", "Cenário 2" (com ou sem acento).
+ * Qualquer outra coisa — inclusive "geral" — vira ausência de âncora: melhor
+ * não citar do que citar errado e mandar o humano para o trecho errado.
  *
  * @param {*} value valor cru do campo `anchor`
  * @returns {string} âncora normalizada, ou '' quando não há
@@ -187,7 +225,9 @@ const ANCHOR_RE = /^(story|task)[ \t]*(\d+(?:\.\d+)?)$/i;
 export function normalizeAnchor(value) {
   const m = ANCHOR_RE.exec(String(value ?? '').trim());
   if (!m) return '';
-  return `${m[1].toLowerCase() === 'task' ? 'Task' : 'Story'} ${m[2]}`;
+  const kind = m[1].toLowerCase();
+  const nome = kind === 'task' ? 'Task' : kind === 'story' ? 'Story' : 'Cenário';
+  return `${nome} ${m[2]}`;
 }
 
 /**
@@ -245,10 +285,23 @@ export function validateCritiquePayload(payload) {
       );
     }
     const extra = itemKeys.filter(
-      k => k !== 'severity' && k !== 'text' && k !== 'anchor' && k !== 'quote');
+      k => k !== 'severity' && k !== 'text' && k !== 'anchor' && k !== 'quote' && k !== 'features');
     if (extra.length > 0) {
       throw new CritiqueSchemaError(`${at} tem campo(s) não reconhecido(s): ${extra.join(', ')}.`);
     }
+    // `features` (kind 'conjunto'): quais issues o finding atravessa. Fora do
+    // formato é erro de schema — a localização é a metade do valor do achado.
+    let features = null;
+    if ('features' in item) {
+      if (!Array.isArray(item.features)
+        || item.features.length === 0
+        || !item.features.every(n => Number.isInteger(n) && n > 0)) {
+        throw new CritiqueSchemaError(
+          `${at}.features deveria ser um array não-vazio de números de issue, veio ${describe(item.features)}.`
+        );
+      }
+      features = [...new Set(item.features)];
+    }
     // Normaliza só caixa e espaço — isso não é ambiguidade semântica. "GRAVE"
     // passa; "gravíssimo", "critical" e "high" NÃO.
     const severity = typeof item.severity === 'string' ? item.severity.trim().toLowerCase() : null;
@@ -268,6 +321,7 @@ export function validateCritiquePayload(payload) {
     return {
       severity,
       ...(anchor ? { anchor } : {}),
+      ...(features ? { features } : {}),
       ...(quote ? { quote } : {}),
       text: item.text.trim(),
     };
@@ -721,6 +775,17 @@ const KIND_TRAILER = {
       'até ser removida. Um bug com causa raiz errada produz correção errada — corrija o ' +
       '`bug.md` e reaplique `spec-wave:bug`.'
     : '_Findings menores não bloqueiam a triagem._'),
+  qa: (graves) => (graves
+    ? '⛔ Há findings **graves**: a label `spec-wave:critique-failed` impede o `qa run` ' +
+      'até ser removida. Corrija o `qa-plan.md` (as âncoras acima apontam para ele), ' +
+      'remova a label e reaplique `spec-wave:qa` para uma nova crítica.'
+    : '_Findings menores não bloqueiam a execução do QA._'),
+  // O conjunto roda fora do ciclo de tentativas e não aplica label: o achado é
+  // decisão de PO entre duas specs, e o destino dele é a issue das duas pontas.
+  conjunto: (graves) => (graves
+    ? '⛔ Há findings **graves** entre specs: comente nas issues DOS DOIS lados, apontando ' +
+      'uma para a outra, e resolva antes de gerar os planos — cada spec sozinha parece certa.'
+    : '_Nenhuma contradição entre as specs que exija decisão antes dos planos._'),
 };
 
 /**
@@ -782,8 +847,12 @@ export function renderCritiqueMarkdown({
     return parts.join('\n\n');
   }
 
+  // Localização do finding: a âncora ("Story N") ou, no conjunto, as Features
+  // que ele atravessa ("#412 × #415").
+  const onde = f => f.anchor
+    || (f.features?.length ? f.features.map(n => `#${n}`).join(' × ') : '');
   const bullets = list => list
-    .map(f => `- ${f.anchor ? `**${f.anchor}** — ` : ''}${sanitizeFindingText(f.text)}`)
+    .map(f => `- ${onde(f) ? `**${onde(f)}** — ` : ''}${sanitizeFindingText(f.text)}`)
     .join('\n');
   if (graves.length > 0) parts.push(`### ❌ Graves\n\n${bullets(graves)}`);
   if (menores.length > 0) parts.push(`### ⚠️ Menores\n\n${bullets(menores)}`);
@@ -791,7 +860,7 @@ export function renderCritiqueMarkdown({
     parts.push(
       '### ↘️ Rebaixados (vieram como graves, não bloqueiam)\n\n' +
       rebaixados
-        .map(f => `- ${f.anchor ? `**${f.anchor}** — ` : ''}${sanitizeFindingText(f.text)}\n` +
+        .map(f => `- ${onde(f) ? `**${onde(f)}** — ` : ''}${sanitizeFindingText(f.text)}\n` +
           `  - _Rebaixado: ${sanitizeFindingText(f.downgradeReason || 'não se sustenta como bloqueio')}._`)
         .join('\n') +
       '\n\n_Continuam valendo como observação. Se algum for mesmo grave, corrija o documento ' +
@@ -811,6 +880,7 @@ export function renderCritiqueMarkdown({
         fingerprint: findingFingerprint({ kind, anchor: f.anchor, text: f.text }),
         severity: f.severity,
         anchor: f.anchor || null,
+        ...(f.features?.length ? { features: f.features } : {}),
         text: sanitizeFindingText(f.text),
         ...(f.downgraded ? { downgradedFrom: f.downgraded, downgradeReason: f.downgradeReason } : {}),
       })),
@@ -832,8 +902,10 @@ export function renderCritiqueMarkdown({
  * chamador decidir entre seguir com aviso e abortar.
  *
  * @param {object} params
- * @param {'plan'|'stories'|'bug'} params.kind o que está sendo auditado
+ * @param {'plan'|'stories'|'bug'|'spec'|'conjunto'} params.kind o que está sendo auditado
  * @param {string} [params.spec] conteúdo do spec.md
+ * @param {Array<{number:number, title:string, content:string}>} [params.specs]
+ *        kind 'conjunto': TODAS as specs da milestone, uma seção por Feature
  * @param {string} [params.plan] conteúdo do plan.md
  * @param {string} [params.techContextYaml] tech_context serializado em YAML
  * @param {string} [params.decomposition] conteúdo do decomposition.md
@@ -847,12 +919,17 @@ export function renderCritiqueMarkdown({
  * @returns {Promise<{grave, findings, markdown, attempt, model}>}
  */
 export async function runCritique({
-  kind, spec, plan, techContextYaml, decomposition, bugDoc, bugReport,
+  kind, spec, specs, plan, techContextYaml, decomposition, qaPlan, bugDoc, bugReport,
   attempt = 1, maxAttempts = DEFAULT_MAX_CRITIQUE_ATTEMPTS,
   model, labels = [], usage, cwd, decisions = null, standalone = false,
 } = {}) {
   const sections = [];
   if (spec) sections.push(`## spec.md\n\n${spec}`);
+  // Conjunto: o título de cada seção carrega o "#N" que o campo `features` dos
+  // findings cita de volta — é o contrato de localização deste kind.
+  for (const s of specs || []) {
+    sections.push(`## spec.md — #${s.number} ${s.title}\n\n${s.content}`);
+  }
   if (plan) sections.push(`## plan.md\n\n${plan}`);
   if (techContextYaml) sections.push(`## tech_context\n\n\`\`\`yaml\n${techContextYaml}\n\`\`\``);
   // Cerca de QUATRO crases: o decomposition.md contém cercas de três, e uma
@@ -862,6 +939,13 @@ export async function runCritique({
       `## Decomposição proposta (decomposition.md)\n\n\`\`\`\`markdown\n${decomposition}\n\`\`\`\``
     );
   }
+  // Mesma cerca de quatro crases da decomposição, pelo mesmo motivo: o plano
+  // pode conter blocos de código de três.
+  if (qaPlan) {
+    sections.push(
+      `## Plano de QA auditado (qa-plan.md)\n\n\`\`\`\`markdown\n${qaPlan}\n\`\`\`\``
+    );
+  }
   // O relato é a fonte contra a qual o bug.md é auditado: a causa raiz proposta
   // tem que explicar OS SINTOMAS RELATADOS, não sintomas plausíveis quaisquer.
   if (bugReport) sections.push(`## Relato original (issue e comentários)\n\n${bugReport}`);
@@ -898,7 +982,8 @@ export async function runCritique({
   // sustenta não deve entrar no contador de tentativas nem bloquear o Action.
   const findings = downgradeUnsupportedFindings(
     report.value.findings,
-    [spec, plan, decomposition, bugDoc, techContextYaml].filter(Boolean),
+    [spec, ...(specs || []).map(s => s.content), plan, decomposition, qaPlan, bugDoc, techContextYaml]
+      .filter(Boolean),
   );
   const grave = findings.some(f => f.severity === 'grave');
   const rebaixados = findings.filter(f => f.downgraded).length;

package/src/lib/decomposition-doc.mjs

@@ -69,8 +69,12 @@ function invalid(reason) {
  * Regras do CommonMark que importam aqui: a cerca tem 3+ caracteres, o
  * fechamento usa o mesmo caractere e comprimento >= o da abertura, e uma cerca
  * de crase não aceita crase na info string.
+ *
+ * Exportado porque o qa-plan.md (lib/qa-plan-doc.mjs) espelha as MESMAS regras
+ * de parsing deste documento — duplicar o rastreador seria duas cópias para
+ * divergir.
  */
-function fenceScanner() {
+export function fenceScanner() {
   let open = null;
   return {
     // true quando a linha pertence a um bloco de código (abertura, conteúdo ou

package/src/lib/doc-paths.mjs

@@ -30,12 +30,12 @@ export function resolveDocDir(root, issue, type) {
 }
 
 /**
- * Caminhos dos três documentos de uma Feature/RFC (função PURA).
+ * Caminhos dos documentos de uma Feature/RFC (função PURA).
  *
  * @param {string|null} root
  * @param {{title?: string}} issue
  * @param {string|null} [type]
- * @returns {{slug, dirRel, dirAbs, spec, plan, decomposition}} cada documento com {rel, abs}
+ * @returns {{slug, dirRel, dirAbs, spec, plan, decomposition, 'qa-plan'}} cada documento com {rel, abs}
  */
 export function featureDocPaths(root, issue, type) {
   const { slug, rel, dir } = resolveDocDir(root, issue, type);
@@ -47,5 +47,8 @@ export function featureDocPaths(root, issue, type) {
     spec: doc('spec.md'),
     plan: doc('plan.md'),
     decomposition: doc('decomposition.md'),
+    // A chave leva o hífen do nome do documento (ARTIFACT_DOCS) de propósito:
+    // é o mesmo id que o resto do fluxo usa para este artefato.
+    'qa-plan': doc('qa-plan.md'),
   };
 }

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/pr-step.mjs

@@ -82,21 +82,26 @@ export function nextPrStep({
     return { steps: [], warnings, reason: 'PR fechado sem merge.', blocked: null };
   }
 
-  if (merged) warnings.push('PR já mergeado — o board é atualizado como se o review tivesse acabado agora.');
-  if (merged && !approved) warnings.push('Mergeado sem review aprovada: o `qa` não roda (o qa.yml também não rodaria).');
-  if (changesRequestedAfterApproval) {
+  // Merge move até 🧪 QA mesmo sem aprovação formal: o autor não consegue
+  // aprovar o próprio PR (fluxo solo nunca teria QA por construção), e QA de
+  // verdade começa com o código integrado. O qa.yml tem o mesmo gatilho de
+  // merge — os dois modos continuam idênticos.
+  if (merged) warnings.push('PR já mergeado — merge move até 🧪 QA, com ou sem aprovação formal.');
+  if (changesRequestedAfterApproval && !merged) {
     warnings.push('Há aprovação E pedido de mudanças: o Actions moveria assim mesmo — confirme com `--yes`.');
   }
 
-  let steps = approved ? ['code-review', 'qa'] : ['code-review'];
+  let steps = (approved || merged) ? ['code-review', 'qa'] : ['code-review'];
   if (only) steps = steps.filter(s => s === only);
 
   return {
     steps,
     warnings,
-    reason: approved
-      ? 'PR com review aprovada: board até 🧪 QA.'
-      : 'PR sem review aprovada: board até 👀 Code Review.',
+    reason: merged
+      ? 'PR mergeado: board até 🧪 QA.'
+      : approved
+        ? 'PR com review aprovada: board até 🧪 QA.'
+        : 'PR sem review aprovada: board até 👀 Code Review.',
     blocked: null,
   };
 }