@spec-wave/cli 0.29.0 → 0.30.0

package/src/commands/run.mjs

@@ -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}`);
   }

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/critique.mjs

@@ -44,7 +44,7 @@ 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)',
+  conjunto: 'specs da milestone (conjunto)', qa: 'qa-plan.md',
 };
 
 // Prompt por tipo de auditoria. 'plan' audita o plan.md contra a spec;
@@ -53,7 +53,7 @@ const KIND_LABEL = {
 // 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',
+  conjunto: 'audit/critique', qa: 'qa/critique',
 };
 
 // A decomposição virou arquivo revisável (decomposition.md): um finding só é
@@ -66,6 +66,13 @@ 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.
@@ -91,6 +98,7 @@ visto à luz das outras). Use EXATAMENTE os números que aparecem nos títulos "
 function buildSystemPrompt(kind, cwd) {
   const prompt = loadPrompt(KIND_PROMPT[kind] || KIND_PROMPT.plan, ...(cwd ? [{ cwd }] : []));
   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
@@ -146,6 +154,13 @@ 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',
@@ -195,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á
@@ -210,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]}`;
 }
 
 /**
@@ -758,6 +775,11 @@ 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
@@ -897,7 +919,7 @@ export function renderCritiqueMarkdown({
  * @returns {Promise<{grave, findings, markdown, attempt, model}>}
  */
 export async function runCritique({
-  kind, spec, specs, 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,
 } = {}) {
@@ -917,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}`);
@@ -953,7 +982,7 @@ export async function runCritique({
   // sustenta não deve entrar no contador de tentativas nem bloquear o Action.
   const findings = downgradeUnsupportedFindings(
     report.value.findings,
-    [spec, ...(specs || []).map(s => s.content), plan, decomposition, bugDoc, techContextYaml]
+    [spec, ...(specs || []).map(s => s.content), plan, decomposition, qaPlan, bugDoc, techContextYaml]
       .filter(Boolean),
   );
   const grave = findings.some(f => f.severity === 'grave');

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/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');
+}