@spec-wave/cli 0.15.0 → 0.16.1

package/src/commands/refresh.mjs

@@ -4,20 +4,174 @@ import { readFileSync, writeFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 import { resolveToken } from '../api/auth.mjs';
-import { CONFIG_FILE } from '../config.mjs';
+import { CONFIG_FILE, STATUS_OPTIONS } from '../config.mjs';
 import { findConfigPath } from '../lib/project-root.mjs';
-import { getProjectSnapshot } from '../api/github-graphql.mjs';
+import { getProjectSnapshot, updateStatusField } from '../api/github-graphql.mjs';
 
 const __dir = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(path.join(__dir, '..', '..', 'package.json'), 'utf-8'));
 
+/**
+ * Plano de sincronização das opções do campo "Etapa" (função PURA).
+ *
+ * A operação é DELIBERADAMENTE aditiva: `ordered` contém tudo que já existe no
+ * board mais as etapas canônicas que faltam, cada uma na posição canônica. Nada
+ * é removido — nem coluna inventada, nem etapa descontinuada.
+ *
+ * ⚠️ E cada opção existente leva seu **id** junto. O contrato da API é o que
+ * torna isso obrigatório: `updateProjectV2Field` SUBSTITUI o conjunto de
+ * opções, e o que liga um item do board a uma opção é o ID — não o nome. Uma
+ * opção reenviada sem id é RECRIADA com id novo, e todo item que estava nela
+ * fica sem Etapa, em silêncio.
+ *
+ * A versão anterior preservava só o nome. No smoke test do RFC-004 isso apagou
+ * a Etapa de uma Feature que estava em 🎯 Priorizado, enquanto o comando
+ * relatava "nenhuma é removida" — verdade sobre os nomes, mentira sobre o
+ * board.
+ *
+ * @param {Record<string, string>} current opções hoje no board: nome → id
+ * @param {Array<{name: string, color: string}>} canonical STATUS_OPTIONS
+ * @returns {{ missing: string[], preserved: string[],
+ *             ordered: Array<{name: string, color: string, id?: string}> }}
+ */
+export function planStageSync(current, canonical) {
+  const atual = current || {};
+  const idDe = (name) => atual[name];
+  const canonicalNames = new Set(canonical.map(o => o.name));
+
+  const missing = canonical.filter(o => !idDe(o.name)).map(o => o.name);
+  // Colunas que o board tem e o fluxo canônico não conhece (inventadas ou
+  // descontinuadas). Vão para o fim, preservando a ordem relativa que tinham.
+  const preserved = Object.keys(atual).filter(name => !canonicalNames.has(name));
+
+  const ordered = [
+    ...canonical.map(o => {
+      const id = idDe(o.name);
+      return id ? { name: o.name, color: o.color, id } : { name: o.name, color: o.color };
+    }),
+    ...preserved.map(name => ({ name, color: 'GRAY', id: atual[name] })),
+  ];
+  return { missing, preserved, ordered };
+}
+
+/**
+ * Aplica o plano de `planStageSync` no campo "Etapa" do Project.
+ *
+ * Escreve só quando há etapa canônica faltando, e verifica o resultado relendo
+ * o Project: se alguma opção que existia antes sumiu, grita — é o único jeito
+ * de o usuário descobrir a tempo que itens perderam a Etapa.
+ *
+ * @returns {Promise<boolean>} true se o comando deve continuar
+ */
+async function syncStages(token, snapshot, options) {
+  const etapa = snapshot.fields?.['Etapa'];
+  if (!etapa?.id) {
+    p.log.error('Campo "Etapa" não encontrado no Project — nada a sincronizar.');
+    process.exitCode = 1;
+    return false;
+  }
+
+  // Mapa nome → id: é o id que preserva o vínculo dos itens com a opção.
+  const current = etapa.options || {};
+  const nomesAntes = Object.keys(current);
+  const { missing, preserved, ordered } = planStageSync(current, STATUS_OPTIONS);
+
+  if (missing.length === 0) {
+    p.log.success(`Campo "Etapa" já tem as ${STATUS_OPTIONS.length} etapas canônicas.`);
+    return true;
+  }
+
+  p.note(
+    `${chalk.green('+')} acrescentar: ${missing.join(', ')}\n` +
+    (preserved.length
+      ? `${chalk.dim('=')} preservar (fora do fluxo canônico): ${preserved.join(', ')}\n`
+      : '') +
+    `${chalk.dim('=')} preservar (canônicas já presentes): ${nomesAntes.length - preserved.length}\n\n` +
+    chalk.dim(`Resultado: ${ordered.length} opções. Nenhuma é removida.`),
+    'Plano para o campo "Etapa"'
+  );
+
+  if (options.dryRun) {
+    p.outro('Dry-run: nada foi enviado ao GitHub.');
+    return false;
+  }
+
+  if (!options.yes) {
+    const go = await p.confirm({
+      message: 'Reescrever as opções do campo "Etapa" com esse conjunto?',
+      initialValue: false,
+    });
+    if (p.isCancel(go) || !go) {
+      p.outro('Cancelado — nada foi alterado.');
+      return false;
+    }
+  }
+
+  const spinner = p.spinner();
+  spinner.start('Atualizando o campo "Etapa"...');
+  try {
+    await updateStatusField(token, etapa.id, ordered);
+  } catch (err) {
+    spinner.stop('');
+    p.log.error(`Falha ao atualizar o campo "Etapa": ${err.message}`);
+    process.exitCode = 1;
+    return false;
+  }
+
+  // Verificação pós-escrita: releitura, não confiança na mutação.
+  let after;
+  try {
+    after = await getProjectSnapshot(token, snapshot.id);
+  } catch (err) {
+    spinner.stop('');
+    p.log.warn(`Campo atualizado, mas a verificação falhou: ${err.message}`);
+    return true;
+  }
+  const depois = after?.fields?.['Etapa']?.options || {};
+  const now = Object.keys(depois);
+  const lost = nomesAntes.filter(name => !now.includes(name));
+  // A verificação que importa: o ID de cada opção preexistente tem que ser o
+  // MESMO. Conferir só o nome era o que deixava passar o pior desfecho — as 12
+  // opções presentes, todos os ids trocados, e o board inteiro sem Etapa.
+  const recriadas = nomesAntes.filter(name => depois[name] && depois[name] !== current[name]);
+  const stillMissing = STATUS_OPTIONS.map(o => o.name).filter(name => !now.includes(name));
+  spinner.stop(`Campo "Etapa" com ${now.length} opções.`);
+
+  if (lost.length > 0) {
+    p.log.error(
+      `Opções que existiam SUMIRAM: ${lost.join(', ')}. Os itens que estavam nelas ficaram ` +
+      'sem Etapa — recrie a coluna com o mesmo nome e reposicione os itens.'
+    );
+    process.exitCode = 1;
+    return false;
+  }
+  if (recriadas.length > 0) {
+    p.log.error(
+      `Opções RECRIADAS com id novo: ${recriadas.join(', ')}. Os itens que estavam nelas ` +
+      'perderam a Etapa — reposicione-os no board. Isto é um bug do comando, não do seu ' +
+      'Project: reporte com a saída acima.'
+    );
+    process.exitCode = 1;
+    return false;
+  }
+  if (stillMissing.length > 0) {
+    p.log.warn(`Etapas canônicas ainda ausentes: ${stillMissing.join(', ')}.`);
+    return true;
+  }
+  p.log.success(`Etapas acrescentadas: ${missing.join(', ')}.`);
+  return true;
+}
+
 // Re-consulta o GitHub Project e reescreve o .spec-wave.json local com os dados
 // atuais (id/number/url/title do Project, IDs do campo Etapa e das opções, e a
 // versão da CLI). Útil para repositórios inicializados antes do enriquecimento,
 // ou quando o Project foi renomeado/teve campos alterados.
 export async function refresh(options = {}) {
-  if (!options.config) {
-    p.log.error('Nada a fazer. Use `spec-wave refresh --config` para atualizar o .spec-wave.json.');
+  if (!options.config && !options.stages) {
+    p.log.error(
+      'Nada a fazer. Use `spec-wave refresh --config` para atualizar o .spec-wave.json, ' +
+      'ou `--stages` para acrescentar as colunas canônicas que faltam no campo "Etapa".'
+    );
     process.exitCode = 1;
     return;
   }
@@ -57,7 +211,7 @@ export async function refresh(options = {}) {
     return;
   }
 
-  p.intro(chalk.bold('spec-wave refresh --config'));
+  p.intro(chalk.bold(`spec-wave refresh${options.stages ? ' --stages' : ' --config'}`));
 
   const spinner = p.spinner();
   spinner.start('Consultando o GitHub Project...');
@@ -78,6 +232,18 @@ export async function refresh(options = {}) {
   }
   spinner.stop('Project consultado.');
 
+  if (options.stages) {
+    const ok = await syncStages(token, snapshot, options);
+    if (!ok) return;
+    // Depois de mexer no board, o .spec-wave.json guarda ids de opção velhos —
+    // relê o Project para que o resto do comando grave o estado novo.
+    snapshot = await getProjectSnapshot(token, projectId);
+    if (!options.config) {
+      p.outro('Campo "Etapa" sincronizado. Rode `spec-wave refresh --config` para atualizar o .spec-wave.json.');
+      return;
+    }
+  }
+
   // Remove campos legados (versões anteriores gravavam etapaFieldId/stageOptions soltos).
   const { etapaFieldId: _e, stageOptions: _s, ...projectRest } = config.project;
   const updated = {

package/src/commands/triage.mjs

@@ -0,0 +1,174 @@
+// Triagem de Bug pela CLI (RFC-004 §4.1) — o mesmo desfecho que a tela do PM
+// oferece, para quem trabalha no terminal ou automatiza.
+//
+// Três saídas, e nenhuma delas é "editar": aceitar (→ ✅ Ready), rejeitar
+// (fecha) e duplicar (fecha, apontando a original). Corrigir o relato é
+// conversa na issue.
+//
+// Rejeitar e duplicar NÃO mexem na Etapa: ela nunca retrocede, e um bug
+// rejeitado não avançou para lugar nenhum — quem o tira das filas é o estado
+// `closed` da issue.
+import * as p from '@clack/prompts';
+import chalk from 'chalk';
+import { resolveToken } from '../api/auth.mjs';
+import {
+  getIssue, addLabel, removeLabel, commentOnIssue, setIssueState,
+} from '../api/github-rest.mjs';
+import { detectIssueType } from '../lib/issue-type.mjs';
+import { loadProjectConfig, resolveField, advanceToStage } from '../lib/board.mjs';
+import { loadConfig } from '../lib/project-root.mjs';
+import { resolveTriageAction, canAcceptBug } from '../lib/bug-triage.mjs';
+import {
+  CONFIG_FILE, STAGE_READY, PROGRESS_TODO, PRIORITY_LABELS,
+  LABEL_TRIAGED, LABEL_DUPLICATE, LABEL_WONT_FIX, labelNames,
+} from '../config.mjs';
+
+const PRIORITIES = PRIORITY_LABELS.map(l => l.name);
+
+export async function triage({ action: actionArg, issue: issueArg, reason, of, severity }) {
+  const { action, error: actionError } = resolveTriageAction(actionArg);
+  if (actionError) {
+    p.log.error(actionError);
+    process.exitCode = 1;
+    return;
+  }
+
+  const issueNumber = parseInt(String(issueArg).replace('#', ''), 10);
+  if (!Number.isInteger(issueNumber) || issueNumber <= 0) {
+    p.log.error(`Issue inválida: "${issueArg}". Use o número da issue, ex.: 42 ou #42.`);
+    process.exitCode = 1;
+    return;
+  }
+  if (severity && !PRIORITIES.includes(severity)) {
+    p.log.error(`Severidade inválida: ${severity}. Use uma de: ${PRIORITIES.join(', ')}.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const [envOwner, envRepo] = (process.env.GITHUB_REPOSITORY || '').split('/');
+  const { config, root } = loadConfig();
+  const owner = envOwner || config?.owner;
+  const repo = envRepo || config?.repo;
+  if (!owner || !repo) {
+    p.log.error(
+      'Não foi possível determinar owner/repo.\n' +
+      `Rode dentro de um repositório com ${CONFIG_FILE} 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 triage ${action} #${issueNumber}`));
+
+  let issue;
+  try {
+    issue = await getIssue(token, owner, repo, issueNumber);
+  } catch (err) {
+    p.log.error(`Não foi possível ler a issue #${issueNumber}: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (detectIssueType(issue) !== 'Bug') {
+    p.log.error(`#${issueNumber} não é um Bug — a triagem só se aplica a defeitos.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const labels = labelNames(issue);
+  const severidadeAtual = severity || labels.find(n => PRIORITIES.includes(n)) || null;
+
+  if (action === 'accept') {
+    const { ok, error } = canAcceptBug({ severity: severidadeAtual, labels });
+    if (!ok) {
+      p.log.error(error);
+      process.exitCode = 1;
+      return;
+    }
+
+    // Reclassificação: troca a label em vez de acumular. Duas prioridades na
+    // mesma issue tornam a ordem da fila indefinida.
+    if (severity) {
+      for (const outra of PRIORITIES) {
+        if (outra !== severity) await removeLabel(token, owner, repo, issueNumber, outra).catch(() => {});
+      }
+      await addLabel(token, owner, repo, issueNumber, severity);
+      p.log.info(`Severidade → ${severity}.`);
+    }
+
+    await addLabel(token, owner, repo, issueNumber, LABEL_TRIAGED);
+    await commentOnIssue(token, owner, repo, issueNumber,
+      '**Triado:** aceito para a fila técnica.').catch(() => {});
+    await moveToReady({ token, issueNumber, issue, root });
+
+    p.outro(`${chalk.green('✓')} Bug #${issueNumber} aceito → ${STAGE_READY}.`);
+    return;
+  }
+
+  if (action === 'reject') {
+    if (!reason || !reason.trim()) {
+      p.log.error('Rejeitar exige --reason "<motivo>".');
+      process.exitCode = 1;
+      return;
+    }
+    await addLabel(token, owner, repo, issueNumber, LABEL_WONT_FIX);
+    await addLabel(token, owner, repo, issueNumber, LABEL_TRIAGED);
+    await commentOnIssue(token, owner, repo, issueNumber,
+      `**Rejeitado na triagem:** ${reason.trim()}`).catch(() => {});
+    await setIssueState(token, owner, repo, issueNumber, 'closed');
+    p.outro(`${chalk.green('✓')} Bug #${issueNumber} rejeitado e fechado.`);
+    return;
+  }
+
+  // duplicate
+  const original = parseInt(String(of || '').replace('#', ''), 10);
+  if (!Number.isInteger(original) || original <= 0) {
+    p.log.error('Marcar como duplicata exige --of <número da issue original>.');
+    process.exitCode = 1;
+    return;
+  }
+  if (original === issueNumber) {
+    p.log.error('Uma issue não pode ser duplicata de si mesma.');
+    process.exitCode = 1;
+    return;
+  }
+
+  await addLabel(token, owner, repo, issueNumber, LABEL_DUPLICATE);
+  await addLabel(token, owner, repo, issueNumber, LABEL_TRIAGED);
+  await commentOnIssue(token, owner, repo, issueNumber, `**Duplicata de #${original}.**`).catch(() => {});
+  // Comentar também na original: sem isso, quem acompanha #original não fica
+  // sabendo que há outro relato do mesmo defeito — e o contexto extra está lá.
+  await commentOnIssue(token, owner, repo, original,
+    `#${issueNumber} foi marcada como duplicata desta issue.`).catch(() => {});
+  await setIssueState(token, owner, repo, issueNumber, 'closed');
+
+  p.outro(`${chalk.green('✓')} Bug #${issueNumber} marcado como duplicata de #${original} e fechado.`);
+}
+
+async function moveToReady({ token, issueNumber, issue, root }) {
+  const { project, error } = loadProjectConfig({ cwd: root || process.cwd() });
+  if (error) {
+    p.log.warn(`${error} — board não atualizado.`);
+    return;
+  }
+  try {
+    const etapaField = await resolveField(token, project, 'Etapa').catch(() => null);
+    const statusField = await resolveField(token, project, 'Status').catch(() => null);
+    const moved = await advanceToStage(
+      token, project, etapaField, statusField, issue.node_id, STAGE_READY, PROGRESS_TODO);
+    if (!moved) {
+      p.log.info(`#${issueNumber} já está em ${STAGE_READY} ou etapa posterior — mantido.`);
+    }
+  } catch (err) {
+    p.log.warn(`Falha ao mover no board: ${err.message}`);
+  }
+}

package/src/commands/update.mjs

@@ -20,8 +20,9 @@ import {
 import { readTemplate } from '../lib/templates.mjs';
 import {
   TARGETS, SKILL_SOURCE, CLI_VERSION, parseSkill, renderContent,
-  mergeAgentsFile, resolveDest, isDetected, skillCopyReason,
+  mergeAgentsFile, resolveDest, isDetected, skillCopyReason, versionBanner,
 } from './install-skill.mjs';
+import { planPluginSkillFiles } from '../lib/plugin-skills.mjs';
 import { findConfigPath } from '../lib/project-root.mjs';
 
 // Arquivos do repo gerenciados pela CLI (comparados com o template empacotado).
@@ -39,15 +40,27 @@ function detectSkill(parsed, baseDir, isGlobal) {
     const dest = resolveDest(target, baseDir, isGlobal);
     if (!dest) continue;
     const reason = skillCopyReason(dest, parsed);
-    if (reason) {
-      jobs.push({ target, dest, desired: renderContent(dest.format, parsed, CLI_VERSION), reason });
+    if (!reason) continue;
+    // `skills-dir` (Codex) não tem um `desired` único: são N arquivos, um por
+    // skill do plugin. O plano é montado na hora de aplicar.
+    if (dest.format === 'skills-dir') {
+      jobs.push({ target, dest, reason });
+      continue;
     }
+    jobs.push({ target, dest, desired: renderContent(dest.format, parsed, CLI_VERSION), reason });
   }
   return jobs;
 }
 
 // Aplica a atualização de uma skill (grava o arquivo / faz merge no AGENTS.md).
 function applySkill(job) {
+  if (job.dest.format === 'skills-dir') {
+    for (const file of planPluginSkillFiles(job.dest.path, CLI_VERSION, versionBanner)) {
+      mkdirSync(path.dirname(file.path), { recursive: true });
+      writeFileSync(file.path, file.content, 'utf-8');
+    }
+    return;
+  }
   const content = job.dest.format === 'agents'
     ? mergeAgentsFile(job.dest.path, job.desired)
     : job.desired;

package/src/commands/validate.mjs

@@ -4,12 +4,81 @@ import { resolveToken } from '../api/auth.mjs';
 import { getIssue, removeLabel, addLabel, commentOnIssue } from '../api/github-rest.mjs';
 import { slugify } from '../lib/slugify.mjs';
 import {
-  CONFIG_FILE, LABEL_CRITIQUE_FAILED, LABEL_NEEDS_HUMAN,
-  REQUIRED_PLAN_SECTIONS, REQUIRED_SPEC_SECTIONS, labelNames,
+  CONFIG_FILE, LABEL_CRITIQUE_FAILED, LABEL_NEEDS_HUMAN, LABEL_BUG, LABEL_BUG_APPROVED,
+  REQUIRED_PLAN_SECTIONS, REQUIRED_SPEC_SECTIONS, REQUIRED_BUG_SECTIONS, labelNames,
 } from '../config.mjs';
 import { findIncompleteDocSigns } from '../lib/doc-completeness.mjs';
+import { bugDocPaths, findMissingSections } from '../lib/bug-doc.mjs';
+import { detectIssueType } from '../lib/issue-type.mjs';
 import { loadConfig } from '../lib/project-root.mjs';
 
+/**
+ * Validação do bug.md (RFC-004 §5).
+ *
+ * Mesma forma da validação de Feature — seções obrigatórias + sinais de
+ * documento truncado + portões humanos da crítica — com duas diferenças:
+ * um único arquivo, e a falha NÃO devolve o item para a etapa de spec (Bug não
+ * tem etapa de spec). Reaplicar `spec-wave:bug` é o caminho de retomada.
+ */
+async function validateBug({ token, owner, repo, issue, issueNumber, root }) {
+  const n = parseInt(issueNumber, 10);
+  const { fileRel, fileAbs } = bugDocPaths(issue.title, root);
+  const errors = [];
+
+  const names = labelNames(issue);
+  const critiqueFailed = names.includes(LABEL_CRITIQUE_FAILED);
+  const needsHuman = names.includes(LABEL_NEEDS_HUMAN);
+  if (critiqueFailed) {
+    errors.push(
+      '🔎 A crítica adversarial apontou contradições GRAVES no `bug.md` (veja o comentário na ' +
+      `issue). Corrija e remova a label \`${LABEL_CRITIQUE_FAILED}\`.`
+    );
+  }
+  if (needsHuman) {
+    errors.push(
+      `🛑 A crítica reprovou repetidas vezes e a label \`${LABEL_NEEDS_HUMAN}\` foi aplicada. ` +
+      'Uma pessoa precisa revisar o `bug.md` e remover a label.'
+    );
+  }
+
+  if (!existsSync(fileAbs)) {
+    errors.push(
+      `❌ \`bug.md\` não encontrado em \`${fileRel}\` — aplique \`${LABEL_BUG}\` para gerá-lo.`
+    );
+  } else {
+    const content = readFileSync(fileAbs, 'utf-8');
+    for (const section of findMissingSections(content, REQUIRED_BUG_SECTIONS)) {
+      errors.push(`❌ Seção obrigatória ausente no bug.md: **${section}**`);
+    }
+    for (const problem of findIncompleteDocSigns(content)) {
+      errors.push(`❌ \`bug.md\` parece incompleto: ${problem}`);
+    }
+  }
+
+  await removeLabel(token, owner, repo, n, 'spec-wave:ready');
+
+  if (errors.length > 0) {
+    await commentOnIssue(
+      token, owner, repo, n,
+      '⚠️ **Validação falhou — o bug.md não está pronto.**\n\n' +
+      errors.join('\n') +
+      `\n\nCorrija os problemas e adicione novamente a label \`spec-wave:ready\`.`
+    );
+    console.error('Validação falhou:', errors.join(', '));
+    process.exit(1);
+  }
+
+  await addLabel(token, owner, repo, n, LABEL_BUG_APPROVED);
+  await commentOnIssue(
+    token, owner, repo, n,
+    '✅ **bug.md validado.**\n\n' +
+    `📄 [\`${fileRel}\`](https://github.com/${owner}/${repo}/blob/main/${fileRel})\n\n` +
+    'As seis seções obrigatórias estão presentes — reprodução, causa raiz e teste de ' +
+    'regressão inclusive. O bug pode ser aceito na triagem.'
+  );
+  console.log('bug.md validado.');
+}
+
 export async function validate({ issueNumber }) {
   const token = await resolveToken();
   const [envOwner, envRepo] = (process.env.GITHUB_REPOSITORY || '').split('/');
@@ -25,6 +94,13 @@ export async function validate({ issueNumber }) {
   }
 
   const issue = await getIssue(token, owner, repo, parseInt(issueNumber, 10));
+
+  // Bug tem artefato próprio (bug.md) e caminho próprio de validação — não passa
+  // pelo par spec.md + plan.md, que é exclusivo de Feature.
+  if (detectIssueType(issue) === 'Bug') {
+    return await validateBug({ token, owner, repo, issue, issueNumber, root });
+  }
+
   const slug = slugify(issue.title);
   // Ancorado na RAIZ do repo, não no cwd: rodar de um subdiretório encontra o
   // config subindo na árvore e precisa encontrar os documentos no mesmo lugar.
@@ -57,10 +133,8 @@ export async function validate({ issueNumber }) {
     errors.push('❌ `plan.md` não encontrado em `' + `${featureRel}/plan.md` + '`');
   } else {
     const planContent = readFileSync(planPath, 'utf-8');
-    for (const section of REQUIRED_PLAN_SECTIONS) {
-      if (!planContent.includes(`# ${section}`)) {
-        errors.push(`❌ Seção obrigatória ausente no plan.md: **${section}**`);
-      }
+    for (const section of findMissingSections(planContent, REQUIRED_PLAN_SECTIONS)) {
+      errors.push(`❌ Seção obrigatória ausente no plan.md: **${section}**`);
     }
     for (const problem of findIncompleteDocSigns(planContent)) {
       errors.push(`❌ \`plan.md\` parece incompleto: ${problem}`);
@@ -73,10 +147,8 @@ export async function validate({ issueNumber }) {
     errors.push('❌ `spec.md` não encontrado em `' + `${featureRel}/spec.md` + '`');
   } else {
     const specContent = readFileSync(specPath, 'utf-8');
-    for (const section of REQUIRED_SPEC_SECTIONS) {
-      if (!specContent.includes(`# ${section}`)) {
-        errors.push(`❌ Seção obrigatória ausente no spec.md: **${section}**`);
-      }
+    for (const section of findMissingSections(specContent, REQUIRED_SPEC_SECTIONS)) {
+      errors.push(`❌ Seção obrigatória ausente no spec.md: **${section}**`);
     }
     // Seções presentes não garantem documento completo: um corte dentro da
     // última seção passa na checagem acima (foi o caso da EP2-F13).