@spec-wave/cli 0.28.0 → 0.30.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spec-wave/cli",
-  "version": "0.28.0",
+  "version": "0.30.0",
   "description": "Setup spec-driven GitHub workflow with Projects v2, labels, issue templates, and AI-powered Actions",
   "type": "module",
   "bin": {

package/src/api/github-graphql.mjs

@@ -343,6 +343,7 @@ export async function listSubIssues(token, issueNodeId) {
               createdAt
               state
               stateReason
+              milestone { number title }
               labels(first: 20) { nodes { name } }
             }
           }
@@ -363,10 +364,46 @@ export async function listSubIssues(token, issueNodeId) {
     // distinguir "entregue" de "descartada no rescopo".
     state: (n.state || '').toLowerCase() || null,
     stateReason: (n.stateReason || '').toLowerCase() || null,
+    // O `order` compara com o milestone do pai: sub-issue sem milestone (ou em
+    // outro) é tão invisível numa visão de release quanto Etapa vazia no board.
+    milestone: n.milestone ? { number: n.milestone.number, title: n.milestone.title } : null,
     labels: (n.labels?.nodes || []).map(l => l.name),
   }));
 }
 
+/**
+ * Os PRs que o GitHub reconhece como fechadores DESTA issue — o inverso de
+ * listLinkedIssuesForPR, pela mesma fonte de vínculo (`Closes #N` + UI). É como
+ * o `merge` descobre o PR de cada Story sem depender de convenção de nome de
+ * branch. `includeClosedPrs` de propósito: PR já mergeado é o que diz que a
+ * Story está entregue.
+ *
+ * @returns {Promise<Array<{number, state, merged, isDraft, baseRefName, headRefName}>>}
+ */
+export async function listIssuePullRequests(token, issueNodeId) {
+  const client = makeClient(token);
+  const result = await client(`
+    query IssuePRs($id: ID!) {
+      node(id: $id) {
+        ... on Issue {
+          closedByPullRequestsReferences(first: 20, includeClosedPrs: true) {
+            nodes { number state merged isDraft baseRefName headRefName }
+          }
+        }
+      }
+    }
+  `, { id: issueNodeId });
+  const nodes = result.node?.closedByPullRequestsReferences?.nodes || [];
+  return nodes.map(n => ({
+    number: n.number,
+    state: (n.state || '').toLowerCase(), // open | closed | merged
+    merged: Boolean(n.merged),
+    isDraft: Boolean(n.isDraft),
+    baseRefName: n.baseRefName || null,
+    headRefName: n.headRefName || null,
+  }));
+}
+
 /**
  * Issues que o GitHub reconhece como fechadas por este PR
  * (`Closes #N` e o vínculo feito pela UI). É a MESMA lista que fecha as issues

package/src/api/github-rest.mjs

@@ -511,6 +511,27 @@ export async function getFileContent(token, owner, repo, path, ref) {
   }
 }
 
+// Reaponta a BASE de um PR aberto. Usado pelo `merge` numa pilha de Stories:
+// depois que o PR anterior mergeia, o dependente é reapontado para a default
+// ANTES de qualquer branch ser apagada — apagar primeiro foi o que fechou um
+// PR empilhado sem volta.
+export async function updatePRBase(token, owner, repo, prNumber, base) {
+  const octokit = makeOctokit(token);
+  await octokit.rest.pulls.update({ owner, repo, pull_number: prNumber, base });
+}
+
+// Mergeia um PR. `merge` (commit de merge) é o método da pilha de Stories:
+// squash reescreveria o merge-base dos dependentes e o retarget deixaria de
+// ser limpo. O GitHub recusa (405) draft, check obrigatório pendente e
+// conflito — o chamador decide o que fazer com a fila.
+export async function mergePR(token, owner, repo, prNumber, { method = 'merge' } = {}) {
+  const octokit = makeOctokit(token);
+  const res = await octokit.rest.pulls.merge({
+    owner, repo, pull_number: prNumber, merge_method: method,
+  });
+  return { merged: Boolean(res.data.merged), sha: res.data.sha || null };
+}
+
 export async function listPullRequestReviews(token, owner, repo, prNumber) {
   const octokit = makeOctokit(token);
   return await octokit.paginate(octokit.rest.pulls.listReviews, {

package/src/cli.mjs

@@ -147,11 +147,11 @@ export function buildProgram() {
     .command('run')
     .description('Executa LOCALMENTE o próximo passo do fluxo (o que a label dispararia no Actions)')
     .argument('[issue]', 'Número da issue (Feature, Bug ou RFC)')
-    .option('--pr <n>', 'Modo PR: decide entre code-review e qa pelo estado das reviews')
+    .option('--pr <n>', 'Modo PR: decide entre code-review e qa pelo estado das reviews e do merge')
     .option('--dry-run', 'Decide e explica sem executar nada')
     .option('--yes', 'Confirma o passo que exige confirmação')
     .option('--apply', 'Autoriza especificamente o decompose-apply (erra se o passo pendente for outro)')
-    .option('--step <nome>', 'Força um passo: spec | plan | critique | validate | decompose | decompose-apply | bug')
+    .option('--step <nome>', 'Força um passo: spec | plan | critique | validate | decompose | decompose-apply | bug | qa-plan')
     .option('--max-steps <n>', 'Encadeia até N passos (padrão: 1)', '1')
     .option('--force', 'Ignora o portão de label de gatilho pendente')
     .option('--no-remote-check', 'Não consulta o remoto pelos documentos ausentes (offline)')
@@ -172,6 +172,17 @@ export function buildProgram() {
       await preflight(options).catch(err => { console.error(err.message); process.exit(1); });
     });
 
+  program
+    .command('audit')
+    .description('Cruza as specs de uma milestone: dependência órfã, bloqueante em milestone posterior, sobreposição com código')
+    .requiredOption('--milestone <nome>', 'Título da milestone a auditar')
+    .option('--critique', 'Roda também a crítica adversarial de conjunto (uma chamada de modelo por milestone)')
+    .option('--json', 'Imprime o relatório em JSON')
+    .action(async (options) => {
+      const { audit } = await import('./commands/audit.mjs');
+      await audit(options).catch(err => { console.error(err.message); process.exit(1); });
+    });
+
   program
     .command('mode')
     .description('Mostra ou alterna o modo de execução: `actions` (workflows) ou `local` (esta máquina)')
@@ -309,11 +320,40 @@ export function buildProgram() {
 
   program
     .command('qa')
-    .description('Move Feature para QA ao aprovar um PR (usado pelo GitHub Action)')
-    .requiredOption('--pr-number <n>', 'Número do Pull Request')
+    .description('Executa o plano de QA de uma issue (Feature/Story/Bug) localmente; com --pr-number, move a Feature para QA (usado pelo GitHub Action)')
+    .argument('[issue]', 'Número da issue (Feature, Story ou Bug), ex.: 12 ou #12')
+    .option('--pr-number <n>', 'Modo Action: move a Feature/Bug do PR aprovado ou mergeado para 🧪 QA')
+    .option('--only <n[,m]>', 'Executa só o(s) cenário(s) indicado(s) — número POSICIONAL no plano')
+    .option('--severity <p>', 'Severidade dos Bugs abertos na reprova: P0, P1, P2 ou P3 (default: qa.defaultBugPriority ou P2)')
+    .option('--dry-run', 'Monta o contexto e imprime cenários e comando — ZERO escrita no GitHub')
+    .action(async (issueArg, options) => {
+      // Dois modos, mutuamente exclusivos: `--pr-number` é a transição Code
+      // Review → 🧪 QA (Action); o argumento posicional é a EXECUÇÃO do plano.
+      if (issueArg && options.prNumber) {
+        console.error('Use OU `qa <issue>` (executa o plano) OU `qa --pr-number <n>` (move o board) — nunca os dois.');
+        process.exit(1);
+      }
+      if (!issueArg && !options.prNumber) {
+        console.error('Informe a issue (`spec-wave qa <issue>`) ou o PR (`spec-wave qa --pr-number <n>`).');
+        process.exit(1);
+      }
+      if (options.prNumber) {
+        const { qa } = await import('./commands/qa.mjs');
+        await qa(options).catch(err => { console.error(err.message); process.exit(1); });
+        return;
+      }
+      const { qaRun } = await import('./commands/qa-run.mjs');
+      await qaRun({ issue: issueArg, ...options })
+        .catch(err => { console.error(err.message); process.exit(1); });
+    });
+
+  program
+    .command('generate-qa-plan')
+    .description('Gera (ou re-critica) o plano de QA de uma Feature em qa-plan.md — roda no GitHub Action ou localmente')
+    .requiredOption('--issue-number <n>', 'Número da issue no GitHub')
     .action(async (options) => {
-      const { qa } = await import('./commands/qa.mjs');
-      await qa(options).catch(err => { console.error(err.message); process.exit(1); });
+      const { generateQaPlan } = await import('./commands/generate-qa-plan.mjs');
+      await generateQaPlan(options).catch(err => { console.error(err.message); process.exit(1); });
     });
 
   program
@@ -336,6 +376,18 @@ export function buildProgram() {
       await order({ feature }).catch(err => { console.error(err.message); process.exit(1); });
     });
 
+  program
+    .command('merge')
+    .description('Mergeia os PRs empilhados das Stories de uma Feature na ordem topológica e move o board até QA')
+    .argument('<feature>', 'Número da issue da Feature, ex.: 12 ou #12')
+    .option('--yes', 'Executa os merges (sem isso, só mostra o plano)')
+    .option('--dry-run', 'Mostra o plano e sai')
+    .option('--keep-branches', 'Não apaga as branches das Stories depois do merge')
+    .action(async (feature, options) => {
+      const { merge } = await import('./commands/merge.mjs');
+      await merge({ feature, ...options }).catch(err => { console.error(err.message); process.exit(1); });
+    });
+
   program
     .command('task')
     .description('Gerencia uma Task no board: start (Status "In Progress") ou done (Done)')
@@ -408,5 +460,20 @@ export function buildProgram() {
       await doctor().catch(err => { console.error(err.message); process.exit(1); });
     });
 
+  // O mapa por tema no fim do --help: 29 comandos em lista plana dizem O QUE
+  // cada um faz, mas não POR ONDE começar nem em que ordem o fluxo anda.
+  program.addHelpText('after', `
+Fluxo típico (cada tema, na ordem):
+  configurar     init · doctor · mode <actions|local> · update
+  especificar    preflight --milestone → specs (label ou run) → audit --milestone [--critique]
+  planejar       run <issue> (plan → critique → validate) → move <n> ready
+  decompor       run <issue> (decompose → --apply) → order <feature>
+  implementar    implement <issue> · task start/done · story review
+  entregar       merge <feature> (PRs empilhados, na ordem) · run --pr <n> (board até QA)
+  validar (QA)   label spec-wave:qa (gera qa-plan.md) → qa <issue> [--only n] (executa e dá o veredito)
+  acompanhar     info · order · move · repair-stage
+
+Docs: https://astratech-net-br.github.io/spec-wave-cli/  ·  spec-wave <comando> --help`);
+
   return program;
 }

package/src/commands/audit.mjs

@@ -0,0 +1,280 @@
+// Auditoria de dependências de uma milestone — o passo entre "as specs estão
+// mergeadas" e "vamos gerar os planos".
+//
+// A crítica adversarial roda por Feature; este comando cruza as specs COMO
+// CONJUNTO e responde as três perguntas que hoje só apareciam se alguém lesse
+// as dez juntas: alguma dependência declarada não é criada por ninguém? Alguma
+// bloqueante vive em milestone posterior à de quem depende dela? Alguma spec
+// descreve o que já existe em código?
+//
+// Toda a decisão mora em `lib/spec-audit.mjs` (puro); aqui é só coleta: as
+// Features de todas as milestones (o catálogo do que uma spec pode citar), o
+// conteúdo da spec de cada Feature-alvo nas quatro camadas (loadArtifact — uma
+// spec em PR aberto também é auditável), e a lista de arquivos do repositório
+// para a heurística de código.
+//
+// Comando LOCAL, fora da tabela STEPS de propósito: ele é por milestone, não
+// por issue — não há label que o dispare nem lugar para ela no fluxo.
+
+import * as p from '@clack/prompts';
+import chalk from 'chalk';
+import { readdirSync } from 'node:fs';
+import path from 'node:path';
+
+import { resolveToken } from '../api/auth.mjs';
+import {
+  getIssue, getRepoDefaultBranch, listMilestones, listIssuesByMilestone,
+} from '../api/github-rest.mjs';
+import { CONFIG_FILE } from '../config.mjs';
+import { detectIssueType } from '../lib/issue-type.mjs';
+import { featureDocPaths } from '../lib/doc-paths.mjs';
+import { loadArtifact } from '../lib/doc-source.mjs';
+import { loadConfig } from '../lib/project-root.mjs';
+import { runCritique } from '../lib/critique.mjs';
+import { slugify } from '../lib/slugify.mjs';
+import { loadStaticTechContext, TECH_CONTEXT_PATH } from '../lib/tech-context.mjs';
+import {
+  auditMilestone, auditVerdict, dependencySection, issueRefs,
+} from '../lib/spec-audit.mjs';
+import { resolveMilestone } from './preflight.mjs';
+
+// A heurística de código procura componente/rota, não texto: docs/ casaria com
+// o próprio slug da spec, e um README citando a feature não é implementação.
+const IGNORED_DIRS = new Set([
+  'node_modules', 'dist', 'build', 'coverage', 'vendor', 'target', 'tmp', 'docs',
+]);
+const IGNORED_EXTS = new Set(['.md', '.txt', '.lock', '.log', '.svg', '.png', '.jpg']);
+const MAX_FILES = 20000;
+
+/**
+ * Caminhos relativos dos arquivos do repositório (I/O — nunca lança).
+ * Profundidade e volume limitados: é insumo de heurística, não um índice.
+ */
+export function listRepoFiles(root, { maxFiles = MAX_FILES, maxDepth = 8 } = {}) {
+  const out = [];
+  const walk = (dir, depth) => {
+    if (depth > maxDepth || out.length >= maxFiles) return;
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (out.length >= maxFiles) return;
+      if (e.name.startsWith('.') || IGNORED_DIRS.has(e.name)) continue;
+      const abs = path.join(dir, e.name);
+      if (e.isDirectory()) walk(abs, depth + 1);
+      else if (e.isFile() && !IGNORED_EXTS.has(path.extname(e.name).toLowerCase())) {
+        out.push(path.relative(root, abs));
+      }
+    }
+  };
+  walk(root, 0);
+  return out;
+}
+
+export async function audit({ milestone: milestoneArg, critique = false, json = false } = {}) {
+  const falhar = (msg) => {
+    if (json) console.log(JSON.stringify({ erro: msg }, null, 2));
+    else p.log.error(msg);
+    process.exitCode = 1;
+  };
+
+  if (!json) p.intro(chalk.bold('spec-wave audit — dependências da milestone'));
+
+  const { config, root, error: configError } = loadConfig();
+  if (configError || !config?.owner || !config?.repo) {
+    return falhar(`${configError || `${CONFIG_FILE} sem owner/repo`} — rode \`spec-wave init\` antes.`);
+  }
+  const { owner, repo } = config;
+
+  let token;
+  try {
+    token = await resolveToken();
+  } catch (err) {
+    return falhar(`Sem token utilizável para ${owner}/${repo}: ${err.message}`);
+  }
+
+  const s = json ? null : p.spinner();
+  s?.start('Montando o catálogo de Features...');
+
+  let base;
+  let milestones;
+  try {
+    base = await getRepoDefaultBranch(token, owner, repo);
+    milestones = await listMilestones(token, owner, repo);
+  } catch (err) {
+    s?.stop('');
+    return falhar(`Não foi possível ler o repositório ${owner}/${repo}: ${err.message}`);
+  }
+  const { milestone, error: msError } = resolveMilestone(milestones, milestoneArg);
+  if (msError) {
+    s?.stop('');
+    return falhar(msError);
+  }
+
+  // O catálogo vem de TODAS as milestones: a inversão de sequenciamento é
+  // exatamente uma dependência que resolve para FORA da milestone-alvo.
+  const catalog = [];
+  let targetIssues = [];
+  try {
+    for (const m of milestones) {
+      const issues = await listIssuesByMilestone(token, owner, repo, m.number);
+      if (m.number === milestone.number) targetIssues = issues;
+      for (const i of issues) {
+        if (detectIssueType(i) !== 'Feature') continue;
+        catalog.push({
+          number: i.number,
+          title: i.title,
+          slug: slugify(i.title),
+          closed: i.state === 'closed',
+          milestone: { number: m.number, title: m.title, due_on: m.due_on ?? null },
+        });
+      }
+    }
+  } catch (err) {
+    s?.stop('');
+    return falhar(`Não foi possível listar as issues por milestone: ${err.message}`);
+  }
+
+  // A spec de cada Feature-alvo, nas quatro camadas (disco, base, branch, PR) —
+  // em série pelo mesmo motivo do preflight: rate limit secundário.
+  const features = [];
+  for (const issue of targetIssues) {
+    if (detectIssueType(issue) !== 'Feature' || issue.state === 'closed') continue;
+    const docs = featureDocPaths(root, issue, 'Feature');
+    const { content } = await loadArtifact({
+      token, owner, repo, root, base,
+      pathRel: docs.spec.rel, doc: 'spec', issueNumber: issue.number,
+    });
+    features.push({
+      number: issue.number,
+      title: issue.title,
+      slug: slugify(issue.title),
+      milestone: { number: milestone.number, title: milestone.title, due_on: milestone.due_on ?? null },
+      spec: content,
+    });
+  }
+
+  if (features.length === 0) {
+    s?.stop('');
+    return falhar(`Nenhuma Feature aberta na milestone "${milestone.title}".`);
+  }
+
+  // Referências `#N` que o catálogo não conhece: issue sem milestone, Story de
+  // outra Feature, ou número que não existe. A API é quem diferencia.
+  const conhecidas = new Set(catalog.map(f => f.number));
+  const desconhecidas = new Set();
+  for (const f of features) {
+    const section = f.spec ? dependencySection(f.spec) : null;
+    for (const n of issueRefs(section || '')) {
+      if (!conhecidas.has(n)) desconhecidas.add(n);
+    }
+  }
+  const missingRefs = [];
+  for (const n of desconhecidas) {
+    const issue = await getIssue(token, owner, repo, n).catch(() => null);
+    if (!issue) { missingRefs.push(n); continue; }
+    catalog.push({
+      number: issue.number,
+      title: issue.title,
+      slug: slugify(issue.title),
+      closed: issue.state === 'closed',
+      milestone: issue.milestone
+        ? { number: issue.milestone.number, title: issue.milestone.title, due_on: issue.milestone.due_on ?? null }
+        : null,
+    });
+  }
+
+  // As decisões de modelagem do tech_context entram na auditoria: recurso
+  // compartilhado com `criada_por: SEM DONO` é pendência de planejamento, não
+  // nota perdida num YAML. Falha de parse é aviso — o arquivo é do usuário.
+  const { context: techContext, error: techError } = loadStaticTechContext(root);
+  if (techError && !json) {
+    p.log.warn(`${TECH_CONTEXT_PATH} não parseou (${techError}) — decisões de modelagem fora da auditoria.`);
+  }
+
+  const resultado = auditMilestone({
+    features, catalog, missingRefs, files: listRepoFiles(root), techContext,
+  });
+  const veredito = auditVerdict(resultado);
+  s?.stop(`Milestone "${milestone.title}": ${features.length} Feature(s) auditada(s).`);
+
+  // A crítica de conjunto: UMA chamada de modelo sobre todas as specs juntas,
+  // atrás do que o determinístico não pega — a mesma regra contada de dois
+  // jeitos. Grave é material (é contradição entre requisitos, por definição);
+  // e falhar aqui falha o comando: quem pediu --critique não pode receber um
+  // "ok" que só cobriu a metade barata.
+  let critica = null;
+  if (critique) {
+    const comSpec = features.filter(f => f.spec);
+    if (comSpec.length < 2) {
+      veredito.avisos.push(
+        `Crítica de conjunto não rodou: ${comSpec.length} spec(s) disponível(is) — conjunto de um não tem par.`
+      );
+    } else {
+      const sc = json ? null : p.spinner();
+      sc?.start(`Crítica de conjunto sobre ${comSpec.length} specs...`);
+      try {
+        critica = await runCritique({
+          kind: 'conjunto',
+          specs: comSpec.map(f => ({ number: f.number, title: f.title, content: f.spec })),
+          cwd: root,
+          standalone: true,
+        });
+      } catch (err) {
+        sc?.stop('');
+        return falhar(`A crítica de conjunto falhou: ${err.message}`);
+      }
+      sc?.stop(`Crítica de conjunto: ${critica.findings.length} finding(s) (modelo ${critica.model}).`);
+      for (const f of critica.findings) {
+        const onde = (f.features || []).map(n => `#${n}`).join(' × ');
+        const linha = `crítica de conjunto${onde ? ` [${onde}]` : ''}: ${f.text}`;
+        if (f.severity === 'grave') veredito.materiais.push(linha);
+        else veredito.avisos.push(linha);
+      }
+      if (veredito.materiais.length) veredito.status = 'problema';
+      else if (veredito.avisos.length) veredito.status = 'aviso';
+    }
+  }
+
+  const saida = {
+    milestone: { title: milestone.title, number: milestone.number },
+    features: features.map(f => ({ number: f.number, title: f.title, temSpec: !!f.spec })),
+    auditoria: resultado,
+    // `markdown` é o comentário pronto para a issue — quem posta (nas DUAS
+    // pontas de cada finding) é o agente que dirige o comando, não a CLI.
+    critica: critica
+      ? { model: critica.model, findings: critica.findings, markdown: critica.markdown }
+      : null,
+    veredito,
+  };
+
+  if (json) {
+    console.log(JSON.stringify(saida, null, 2));
+    if (veredito.status === 'problema') process.exitCode = 1;
+    return saida;
+  }
+
+  const grafoLinhas = resultado.grafo.map(g => {
+    const deps = g.dependsOn.length ? ` ← depende de ${g.dependsOn.map(d => `#${d}`).join(', ')}` : '';
+    return `  #${g.number}${deps}`;
+  });
+  if (grafoLinhas.length) {
+    p.note(grafoLinhas.join('\n'), 'Dependências entre Features (extraídas das specs)');
+  }
+
+  for (const a of veredito.avisos) p.log.warn(a);
+  for (const m of veredito.materiais) p.log.error(m);
+
+  if (veredito.status === 'problema') {
+    p.outro(`${veredito.materiais.length} achado(s) material(is). Decida antes de gerar os planos.`);
+    process.exitCode = 1;
+    return saida;
+  }
+  p.outro(veredito.status === 'aviso'
+    ? 'Nada material — confira os avisos antes de seguir.'
+    : 'Dependências da milestone fecham. Siga para os planos.');
+  return saida;
+}

package/src/commands/doctor.mjs

@@ -13,15 +13,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,
   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 +954,84 @@ 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));
+}
+
+// QA (rfc/spec-qa-skill.md): executor configurado + Features em 🧪 QA com plano.
+// 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 e planos das Features em 🧪 QA)';
+  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.`);
+      }
+    } 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).');
+  }
+
+  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 +1357,7 @@ export async function doctor() {
     checkAi,
     checkDecompositions,
     checkSpecKit,
+    checkQa,
     checkWorkflows,
     checkPrPublishing,
     checkExecutionMode,