@spec-wave/cli 0.28.0 → 0.29.0

package/src/commands/merge.mjs

@@ -0,0 +1,292 @@
+// Mergeia os PRs empilhados das Stories de uma Feature, na ordem topológica —
+// o passo final do fluxo, que até aqui era inteiramente manual e frágil.
+//
+// O implement empilha de propósito (cada Story revisável sozinha, diff limpo),
+// mas a pilha torna o merge ordem-dependente: `--delete-branch` no primeiro PR
+// já fechou o segundo sem volta. A sequência segura, que este comando encapsula:
+//
+//   para cada PR, na ordem das dependências:
+//     1. reaponta a base para a default (o anterior já mergeou; com merge
+//        commit o retarget é limpo — por isso o método é `merge`, não squash)
+//     2. mergeia
+//     3. atualiza o board (code-review + qa — merge move até 🧪 QA)
+//   e SÓ NO FIM apaga as branches, quando nenhum PR aberto depende delas.
+//
+// PR em rascunho BLOQUEIA o plano inteiro: marcar pronto é o ato de revisão
+// humana (e o que dispara o CI) — mergear rascunho por cima seria pular a única
+// aprovação que o fluxo tem. Falha no meio para a fila e explica: os merges já
+// feitos ficam, rodar de novo retoma de onde parou (PR mergeado sai do plano).
+import * as p from '@clack/prompts';
+import chalk from 'chalk';
+
+import { resolveToken } from '../api/auth.mjs';
+import {
+  getIssue, getPR, getRepoDefaultBranch, updatePRBase, mergePR, deleteBranch, listBlockedBy,
+} from '../api/github-rest.mjs';
+import { listSubIssues, listIssuePullRequests } from '../api/github-graphql.mjs';
+import { detectIssueType } from '../lib/issue-type.mjs';
+import { parseDependencies, orderStories } from '../lib/dependencies.mjs';
+import { resolveRepoContext } from '../lib/project-root.mjs';
+import { CONFIG_FILE } from '../config.mjs';
+import { acquireLock, releaseLock } from './run.mjs';
+import { codeReview } from './code-review.mjs';
+import { qa } from './qa.mjs';
+
+/**
+ * O plano de merge (função PURA — é onde mora toda a decisão).
+ *
+ * Separa cada Story em um destino: `fila` (PR aberto, pronto, entra na ordem),
+ * `concluidas` (PR já mergeado — é o que torna rodar de novo uma RETOMADA),
+ * `bloqueios` (rascunho, mais de um PR aberto — parar antes de mergear
+ * qualquer coisa, porque merge parcial de uma pilha é o pior estado) e
+ * `avisos` (Story sem PR nenhum — fica de fora, mas quem depende dela pode
+ * carregar commits que não existem na base).
+ *
+ * @param {object} params
+ * @param {number[]} params.sorted ordem topológica (números de Story)
+ * @param {Map<number, {title: string}>} params.byNumber
+ * @param {Map<number, Array<{number, state, merged, isDraft, baseRefName, headRefName}>>} params.prsByStory
+ * @param {string} params.defaultBranch
+ * @returns {{ fila: Array<{story:number, pr:object}>, concluidas: Array<{story:number, pr:object}>,
+ *             semPr: number[], bloqueios: string[], avisos: string[] }}
+ */
+export function planMerge({ sorted = [], byNumber = new Map(), prsByStory = new Map(), defaultBranch } = {}) {
+  const fila = [];
+  const concluidas = [];
+  const semPr = [];
+  const bloqueios = [];
+  const avisos = [];
+  const headsNoPlano = new Set();
+
+  for (const story of sorted) {
+    const prs = prsByStory.get(story) || [];
+    const mergeados = prs.filter(pr => pr.merged);
+    const abertos = prs.filter(pr => pr.state === 'open');
+
+    if (mergeados.length > 0 && abertos.length === 0) {
+      concluidas.push({ story, pr: mergeados[0] });
+      continue;
+    }
+    if (abertos.length === 0) {
+      semPr.push(story);
+      continue;
+    }
+    if (abertos.length > 1) {
+      bloqueios.push(
+        `Story #${story} tem ${abertos.length} PRs abertos (${abertos.map(x => `#${x.number}`).join(', ')}) — ` +
+        'ambíguo; feche o que não vale antes de mergear.'
+      );
+      continue;
+    }
+    const pr = abertos[0];
+    if (pr.isDraft) {
+      bloqueios.push(
+        `PR #${pr.number} (Story #${story}) está em RASCUNHO. Marcar pronto é a revisão humana ` +
+        'e o que dispara o CI — revise e marque pronto antes de mergear.'
+      );
+      continue;
+    }
+    // Base que não é a default nem a head de alguém que mergeia antes: ou a
+    // pilha está fora de ordem, ou aponta para algo que este plano não conhece.
+    if (pr.baseRefName !== defaultBranch && !headsNoPlano.has(pr.baseRefName)) {
+      avisos.push(
+        `PR #${pr.number} (Story #${story}) tem base "${pr.baseRefName}", que não é a default ` +
+        'nem a branch de um PR anterior da fila — confira a pilha antes de confirmar.'
+      );
+    }
+    headsNoPlano.add(pr.headRefName);
+    fila.push({ story, pr });
+  }
+
+  if (semPr.length > 0) {
+    avisos.push(
+      `Story(ies) sem PR: ${semPr.map(n => `#${n}`).join(', ')} — ficam de fora; ` +
+      'se um PR da fila depender do código delas, o merge vai levar esse código junto.'
+    );
+  }
+
+  return { fila, concluidas, semPr, bloqueios, avisos };
+}
+
+export async function merge({ feature: featureArg, yes = false, dryRun = false, keepBranches = false } = {}) {
+  if (process.env.GITHUB_ACTIONS === 'true') {
+    p.log.error('`spec-wave merge` é um comando local — dentro do Actions o merge é decisão humana.');
+    process.exitCode = 1;
+    return;
+  }
+
+  const featureNumber = parseInt(String(featureArg).replace('#', ''), 10);
+  if (!Number.isInteger(featureNumber) || featureNumber <= 0) {
+    p.log.error(`Feature inválida: "${featureArg}". Use o número da issue, ex.: 12 ou #12.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const { owner, repo, root } = resolveRepoContext();
+  if (!owner || !repo) {
+    p.log.error(
+      'Não foi possível determinar owner/repo.\n' +
+      `Rode dentro de um repositório com ${CONFIG_FILE} (\`spec-wave init\`) ou defina GITHUB_REPOSITORY=owner/repo.`
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  let token;
+  try {
+    token = await resolveToken();
+  } catch (err) {
+    p.log.error(err.message);
+    process.exitCode = 1;
+    return;
+  }
+
+  p.intro(chalk.bold(`spec-wave merge #${featureNumber}`));
+  const s = p.spinner();
+  s.start('Montando o plano de merge...');
+
+  let featureIssue;
+  let defaultBranch;
+  try {
+    featureIssue = await getIssue(token, owner, repo, featureNumber);
+    defaultBranch = await getRepoDefaultBranch(token, owner, repo);
+  } catch (err) {
+    s.stop('');
+    p.log.error(`Não foi possível ler ${owner}/${repo}#${featureNumber}: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+  if (detectIssueType(featureIssue) !== 'Feature') {
+    s.stop('');
+    p.log.error(`\`spec-wave merge\` só aceita Features. Issue #${featureNumber} é ${detectIssueType(featureIssue) || 'de tipo desconhecido'}.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  // As Stories e a ordem — as mesmas fontes do `order`.
+  let subs;
+  try {
+    subs = await listSubIssues(token, featureIssue.node_id);
+  } catch (err) {
+    s.stop('');
+    p.log.error(`Não foi possível listar as sub-issues: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+  const stories = subs.filter(x => detectIssueType({ title: x.title, labels: x.labels }) === 'Story');
+  if (stories.length === 0) {
+    s.stop('');
+    p.log.info(`Feature #${featureNumber} não tem Stories — nada a mergear.`);
+    p.outro('Nada a fazer.');
+    return;
+  }
+
+  const enriched = await Promise.all(stories.map(async (st) => {
+    const fromBody = parseDependencies(st.body);
+    const fromBlockedBy = (await listBlockedBy(token, owner, repo, st.number).catch(() => []))
+      .map(b => b.number);
+    return { number: st.number, title: st.title, nodeId: st.nodeId, dependsOn: [...new Set([...fromBody, ...fromBlockedBy])] };
+  }));
+  const byNumber = new Map(enriched.map(x => [x.number, x]));
+  const { order: sorted, cycle } = orderStories(
+    enriched.map(({ number, dependsOn }) => ({ number, dependsOn })));
+  if (cycle.length > 0) {
+    s.stop('');
+    p.log.error(
+      `Ciclo de dependências entre Stories (${cycle.map(n => `#${n}`).join(', ')}) — ` +
+      'não existe ordem de merge. Corrija as linhas "Depende de" e rode de novo.'
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const prsByStory = new Map();
+  for (const story of sorted) {
+    prsByStory.set(story, await listIssuePullRequests(token, byNumber.get(story).nodeId).catch(() => []));
+  }
+
+  const plano = planMerge({ sorted, byNumber, prsByStory, defaultBranch });
+  s.stop(`${plano.fila.length} PR(s) a mergear · ${plano.concluidas.length} já mergeado(s).`);
+
+  const linha = ({ story, pr }) => {
+    const retarget = pr.baseRefName !== defaultBranch ? `  ${chalk.dim(`base ${pr.baseRefName} → ${defaultBranch}`)}` : '';
+    return `  PR #${pr.number} · Story #${story} ${byNumber.get(story)?.title || ''}${retarget}`;
+  };
+  if (plano.fila.length > 0) {
+    p.note(plano.fila.map(linha).join('\n'), `Ordem de merge (base: ${defaultBranch}, método: merge commit)`);
+  }
+  for (const a of plano.avisos) p.log.warn(a);
+  for (const b of plano.bloqueios) p.log.error(b);
+
+  if (plano.bloqueios.length > 0) {
+    p.outro('Bloqueado — merge parcial de pilha é o pior estado; resolva e rode de novo.');
+    process.exitCode = 1;
+    return;
+  }
+  if (plano.fila.length === 0) {
+    p.outro(plano.concluidas.length > 0 ? 'Tudo já mergeado.' : 'Nenhum PR aberto para mergear.');
+    return;
+  }
+  if (dryRun || !yes) {
+    p.outro(dryRun ? 'Dry-run: nada foi mergeado.' : 'Confirme com `--yes` para mergear nesta ordem.');
+    return;
+  }
+
+  // ---------- Execução ----------
+  const lock = acquireLock(root, `merge-${featureNumber}`);
+  const mergedHeads = [];
+  try {
+    for (const { story, pr } of plano.fila) {
+      // Estado fresco: a fila pode ter envelhecido entre o plano e este ponto.
+      const atual = await getPR(token, owner, repo, pr.number);
+      if (atual.merged_at) {
+        p.log.info(`PR #${pr.number} já estava mergeado — seguindo.`);
+        continue;
+      }
+      if (atual.base?.ref !== defaultBranch) {
+        p.log.step(`PR #${pr.number}: base ${atual.base?.ref} → ${defaultBranch}`);
+        await updatePRBase(token, owner, repo, pr.number, defaultBranch);
+      }
+      try {
+        await mergePR(token, owner, repo, pr.number, { method: 'merge' });
+      } catch (err) {
+        // 405 = draft/check pendente/conflito. Parar AQUI preserva a ordem: os
+        // dependentes continuam com branch e PR intactos, e rodar de novo retoma.
+        p.log.error(
+          `Merge do PR #${pr.number} (Story #${story}) recusado: ${err.message}\n` +
+          'Nada depois dele foi mergeado. Resolva (checks, conflito) e rode o comando de novo — ' +
+          'os já mergeados saem do plano sozinhos.'
+        );
+        process.exitCode = 1;
+        return;
+      }
+      p.log.success(`PR #${pr.number} mergeado (Story #${story}).`);
+      mergedHeads.push(pr.headRefName);
+
+      // Board: merge move até 🧪 QA. Falha aqui não desfaz merge — avisa e segue.
+      try {
+        await codeReview({ prNumber: String(pr.number) });
+        await qa({ prNumber: String(pr.number) });
+      } catch (err) {
+        p.log.warn(`Board não atualizado para o PR #${pr.number}: ${err.message} — rode \`spec-wave run --pr ${pr.number}\` depois.`);
+      }
+    }
+
+    // Branches só no FIM, quando nenhum PR aberto depende delas — apagar antes
+    // do retarget do dependente foi o que fechou um PR empilhado sem volta.
+    if (!keepBranches) {
+      for (const head of mergedHeads) {
+        if (!head) continue;
+        await deleteBranch(token, owner, repo, head).catch(err =>
+          p.log.warn(`Branch ${head} não apagada: ${err.message}`));
+      }
+    }
+  } finally {
+    releaseLock(lock);
+  }
+
+  p.outro(
+    `${chalk.green('✓')} ${mergedHeads.length} PR(s) mergeado(s) na ordem` +
+    (keepBranches ? ' (branches mantidas).' : ', branches apagadas.')
+  );
+}

package/src/commands/move.mjs

@@ -191,6 +191,14 @@ export async function move({ issue: issueArg, stage: stageArg, status: statusArg
   // mesmo quando a Etapa não avança — ver ensureWorkItemType.
   const typeField = await resolveField(token, project, 'Work Item Type').catch(() => null);
 
+  // A Etapa de PARTIDA, lida antes de escrever: a mensagem de sucesso imprime a
+  // transição real ("✅ Ready → 🧪 QA"), não a intenção do comando.
+  const lerEtapa = async () => {
+    const itemId = await addProjectItem(token, project.id, issue.node_id);
+    return etapaField?.id ? await getItemSingleSelectValue(token, itemId, etapaField.id) : null;
+  };
+  const antes = await lerEtapa().catch(() => null);
+
   let moved;
   try {
     moved = await advanceToStage(
@@ -203,24 +211,31 @@ export async function move({ issue: issueArg, stage: stageArg, status: statusArg
   }
 
   if (moved) {
+    // Confirmação por leitura — era o usuário quem tinha que "confirmar lendo o
+    // board de volta"; agora o comando lê, e uma escrita que não pegou vira
+    // erro visível em vez de ✅ mentiroso.
+    const depois = await lerEtapa().catch(() => null);
+    if (depois !== null && depois !== stage) {
+      p.log.error(
+        `A escrita não confirmou: o board ainda mostra ${chalk.bold(depois)} ` +
+        `(esperado ${chalk.bold(stage)}). Verifique permissões do token no Project.`
+      );
+      process.exitCode = 1;
+      return;
+    }
+    const confirmada = depois !== null;
     p.log.success(
-      `${type || 'Issue'} #${issueNumber} → Etapa ${chalk.bold(stage)} / Status ${chalk.bold(status)}.`
+      `${type || 'Issue'} #${issueNumber}: ${chalk.bold(antes || '—')} → ${chalk.bold(stage)}` +
+      ` / Status ${chalk.bold(status)}` +
+      (confirmada ? ' (confirmado por leitura do board)' : ' (leitura de confirmação falhou — confira o board)')
     );
     p.outro(`${chalk.green('✓')} ${issue.title}`);
     return;
   }
 
   // false = já está nessa Etapa ou adiante (ou numa coluna fora da ordem
-  // canônica). A Etapa NUNCA retrocede — lê a atual só para informar.
-  let current = null;
-  if (etapaField?.id) {
-    try {
-      const itemId = await addProjectItem(token, project.id, issue.node_id);
-      current = await getItemSingleSelectValue(token, itemId, etapaField.id);
-    } catch {
-      // sem leitura da Etapa — segue com o aviso genérico
-    }
-  }
+  // canônica). A Etapa NUNCA retrocede — informa a atual, já lida antes.
+  const current = antes ?? await lerEtapa().catch(() => null);
   p.log.info(
     `#${issueNumber} não foi movida: a Etapa nunca retrocede, e ela já está em ` +
     `${chalk.bold(current || `"${stage}" ou etapa posterior`)}.`

package/src/commands/order.mjs

@@ -39,6 +39,37 @@ export function featureLabel(feature) {
   return `#${feature?.number} ${curto}`.trim();
 }
 
+/**
+ * Divergências de milestone entre a Feature e suas Stories (função PURA).
+ *
+ * O `order` é o detector do pós-apply, e até aqui ele só checava a Etapa
+ * (`Etapa: —`). Milestone tem o mesmo modo de falha: o apply herda a do pai
+ * (resolveInheritedMilestone), mas issues criadas antes dessa herança — ou com
+ * ela falhando — nascem sem milestone, invisíveis em qualquer visão de release,
+ * e ninguém percebe porque o passo sai verde. Foi assim que ~230 issues
+ * nasceram órfãs.
+ *
+ * Feature sem milestone não gera aviso: não há referência de comparação, e o
+ * repositório pode simplesmente não usar milestones.
+ *
+ * @param {{number?: number, title?: string}|null} featureMilestone
+ * @param {Array<{number: number, milestone?: {number: number, title: string}|null}>} stories
+ * @returns {string[]} uma linha de aviso por Story divergente
+ */
+export function milestoneMismatches(featureMilestone, stories = []) {
+  if (!Number.isInteger(featureMilestone?.number)) return [];
+  const ref = featureMilestone.title || `#${featureMilestone.number}`;
+  const out = [];
+  for (const s of stories) {
+    if (!Number.isInteger(s?.milestone?.number)) {
+      out.push(`#${s.number} está SEM milestone — a Feature está em "${ref}".`);
+    } else if (s.milestone.number !== featureMilestone.number) {
+      out.push(`#${s.number} está em "${s.milestone.title || `#${s.milestone.number}`}", mas a Feature está em "${ref}".`);
+    }
+  }
+  return out;
+}
+
 /**
  * O mapa de execução de várias Features (função PURA).
  *
@@ -350,5 +381,16 @@ export async function order({ feature: featureArg } = {}) {
     p.log.warn('Dependências fora de ordem:\n' + outOfOrder.map(w => `  • ${w}`).join('\n'));
   }
 
+  // 7. Milestone das Stories contra a da Feature — a outra órfã do pós-apply.
+  const milestoneWarns = milestoneMismatches(featureIssue.milestone, stories);
+  if (milestoneWarns.length > 0) {
+    p.log.warn(
+      chalk.yellow.bold('⚠ Milestone divergente da Feature:') + '\n' +
+      milestoneWarns.map(w => `  • ${w}`).join('\n') + '\n' +
+      'Story fora do milestone da Feature some de toda visão de release. ' +
+      'Corrija na issue (gh issue edit <n> --milestone "<título>").'
+    );
+  }
+
   p.outro(`${chalk.green('✓')} ${sorted.length} de ${enriched.length} story(ies) ordenada(s).`);
 }

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 */ }
@@ -348,7 +348,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/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)',
 };
 
 // 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',
 };
 
 // A decomposição virou arquivo revisável (decomposition.md): um finding só é
@@ -62,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.`;
 
+// 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 +90,8 @@ 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 === 'conjunto' ? `\n\n${FEATURES_RULE}` : '';
 
   const contract = `## Contrato de saída
 
@@ -134,6 +146,17 @@ function critiqueJsonSchema(kind) {
     };
     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: {
@@ -245,10 +268,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 +304,7 @@ export function validateCritiquePayload(payload) {
     return {
       severity,
       ...(anchor ? { anchor } : {}),
+      ...(features ? { features } : {}),
       ...(quote ? { quote } : {}),
       text: item.text.trim(),
     };
@@ -721,6 +758,12 @@ 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._'),
+  // 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 +825,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 +838,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 +858,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 +880,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 +897,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, 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
@@ -898,7 +953,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, bugDoc, techContextYaml]
+      .filter(Boolean),
   );
   const grave = findings.some(f => f.severity === 'grave');
   const rebaixados = findings.filter(f => f.downgraded).length;

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