@spec-wave/cli 0.27.0 → 0.28.0

package/package.json

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

package/src/api/github-rest.mjs

@@ -294,6 +294,33 @@ export async function createIssue(token, owner, repo, title, body, labels, { mil
   return { number: res.data.number, nodeId: res.data.node_id, url: res.data.html_url, id: res.data.id };
 }
 
+// Milestones do repositório (abertas e fechadas).
+//
+// O usuário fala o TÍTULO da milestone ("v06"), a API de issues filtra pelo
+// NÚMERO. A tradução mora aqui — e a lista completa também serve para a
+// mensagem de erro: "milestone não encontrada" sem dizer quais existem manda o
+// usuário adivinhar entre nome errado e API fora do ar.
+export async function listMilestones(token, owner, repo) {
+  const octokit = makeOctokit(token);
+  return await octokit.paginate(octokit.rest.issues.listMilestones, {
+    owner, repo, state: 'all', per_page: 100,
+  });
+}
+
+// Issues de uma milestone (pelo NÚMERO dela), abertas e fechadas.
+//
+// `state: 'all'` de propósito: uma Feature fechada continua contando para o
+// inventário — o que muda é que ela não entra na lista do que gerar.
+export async function listIssuesByMilestone(token, owner, repo, milestoneNumber) {
+  const octokit = makeOctokit(token);
+  const issues = await octokit.paginate(octokit.rest.issues.listForRepo, {
+    owner, repo, milestone: String(milestoneNumber), state: 'all', per_page: 100,
+  });
+  // `listForRepo` devolve Pull Requests junto — eles são issues para a API, e
+  // não para o fluxo.
+  return issues.filter(i => !i.pull_request);
+}
+
 export async function getIssue(token, owner, repo, issueNumber) {
   const octokit = makeOctokit(token);
   const res = await octokit.rest.issues.get({ owner, repo, issue_number: issueNumber });

package/src/cli.mjs

@@ -162,6 +162,16 @@ export function buildProgram() {
       await run(issue, options).catch(err => { console.error(err.message); process.exit(1); });
     });
 
+  program
+    .command('preflight')
+    .description('Confere, antes de gerar, tudo que decide uma rodada de specs de uma milestone')
+    .requiredOption('--milestone <nome>', 'Título da milestone a inventariar')
+    .option('--json', 'Imprime o relatório em JSON')
+    .action(async (options) => {
+      const { preflight } = await import('./commands/preflight.mjs');
+      await preflight(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)')
@@ -188,6 +198,8 @@ export function buildProgram() {
     .option('--branch [nome]', 'Envia os arquivos do repo como Pull Request numa branch, em um único commit (sem valor: spec-wave/update-v<versão>)')
     .option('--config-in-pr', 'Força incluir o .spec-wave.json no Pull Request')
     .option('--no-config-in-pr', 'Força manter o .spec-wave.json fora do Pull Request')
+    .option('--skill-in-pr', 'Força incluir a skill dos agentes no Pull Request')
+    .option('--no-skill-in-pr', 'Força manter a skill dos agentes fora do Pull Request')
     .option('--dry-run', 'Mostra o que seria atualizado sem alterar nada')
     .option('--yes', 'Aplica sem pedir confirmação')
     .action(async (options) => {

package/src/commands/doctor.mjs

@@ -1083,10 +1083,15 @@ export function inspectPrPublishing({
   return { status, notes };
 }
 
-async function checkPrPublishing(ctx) {
-  const name = 'Publicação por Pull Request';
-  const dir = path.join(ctx.root || ctx.cwd, '.github', 'workflows');
-
+/**
+ * Permissões de PR declaradas nos workflows instalados (I/O — nunca lança).
+ *
+ * O job MAIS RESTRITIVO manda: basta um sem a permissão para o fluxo quebrar.
+ *
+ * @param {string} dir diretório `.github/workflows`
+ * @returns {Record<string, {contents?: string, pullRequests?: string}>}
+ */
+export function readWorkflowPrPermissions(dir) {
   const workflowPerms = {};
   for (const file of ARTIFACT_WORKFLOW_FILES) {
     const caminho = path.join(dir, file);
@@ -1097,7 +1102,6 @@ async function checkPrPublishing(ctx) {
     } catch {
       continue; // YAML ilegível é problema de outro check
     }
-    // O job mais restritivo manda: basta um sem a permissão para o fluxo quebrar.
     for (const job of Object.values(wf?.jobs || {})) {
       const atual = workflowPerms[file];
       const perm = {
@@ -1109,20 +1113,29 @@ async function checkPrPublishing(ctx) {
       }
     }
   }
+  return workflowPerms;
+}
 
-  if (Object.keys(workflowPerms).length === 0) {
-    return { name, status: 'warn', detail: 'Workflows não encontrados — rode `init` ou `update`.' };
-  }
-
-  const cfg = ctx.cfg || {};
-  const owner = cfg.owner;
-  const repo = cfg.repo;
+/**
+ * Coleta o contexto que `inspectPrPublishing` julga (I/O — nunca lança).
+ *
+ * Separado do check para o `preflight` poder fazer a MESMA pergunta sem
+ * reimplementá-la: as três consultas têm cada uma o seu motivo para falhar sem
+ * que isso signifique "está errado", e duplicar esse tratamento em dois comandos
+ * é como as duas respostas passam a divergir.
+ *
+ * @param {{token?: string, owner?: string, repo?: string, root?: string}} params
+ * @returns {Promise<{canCreatePr: boolean|null, workflowPerms: object,
+ *                    requiredChecks: string[]|null, prTokenPresent: boolean|null}>}
+ */
+export async function readPrPublishingContext({ token, owner, repo, root }) {
+  const workflowPerms = readWorkflowPrPermissions(path.join(root || process.cwd(), '.github', 'workflows'));
 
   let canCreatePr = null;
   let requiredChecks = null;
   let prTokenPresent = null;
-  if (ctx.token && owner && repo) {
-    const octokit = makeOctokit(ctx.token);
+  if (token && owner && repo) {
+    const octokit = makeOctokit(token);
     try {
       const res = await octokit.request('GET /repos/{owner}/{repo}/actions/secrets',
         { owner, repo });
@@ -1146,10 +1159,21 @@ async function checkPrPublishing(ctx) {
       requiredChecks = null; // sem proteção (404) ou sem permissão — nos dois casos, não afirmar
     }
   }
+  return { canCreatePr, workflowPerms, requiredChecks, prTokenPresent };
+}
 
-  const { status, notes } = inspectPrPublishing({
-    canCreatePr, workflowPerms, requiredChecks, prTokenPresent,
+async function checkPrPublishing(ctx) {
+  const name = 'Publicação por Pull Request';
+  const cfg = ctx.cfg || {};
+  const contexto = await readPrPublishingContext({
+    token: ctx.token, owner: cfg.owner, repo: cfg.repo, root: ctx.root || ctx.cwd,
   });
+
+  if (Object.keys(contexto.workflowPerms).length === 0) {
+    return { name, status: 'warn', detail: 'Workflows não encontrados — rode `init` ou `update`.' };
+  }
+
+  const { status, notes } = inspectPrPublishing(contexto);
   return { name, status, detail: notes.join('\n  ') };
 }
 

package/src/commands/implement.mjs

@@ -215,7 +215,12 @@ function buildContext({
     lines.push('');
     lines.push(`3. **Ao concluir TODA a Story** (todas as Tasks na Etapa ${STAGE_DONE}):`);
     lines.push('   1. Faça o **commit** de todas as mudanças da implementação.');
-    lines.push(`   2. Abra o **Pull Request** da Story #${issue.number}.`);
+    // Draft de propósito: numa pilha de Stories (um PR baseado no anterior),
+    // cada rebase em cascata dispararia o CI inteiro em PRs que ninguém vai
+    // mergear naquele estado. Rascunho não mergeia (o GitHub bloqueia) e o
+    // required check continua valendo: quem revisa marca o PR como pronto, o
+    // `ready_for_review` dispara o CI, e só então o merge destrava.
+    lines.push(`   2. Abra o **Pull Request** da Story #${issue.number} **como rascunho** (\`gh pr create --draft\`) — o CI não roda em rascunho; quem revisa marca o PR como pronto e é aí que os checks disparam.`);
     lines.push(
       `   3. **Avance a Etapa da Story #${issue.number} para ${STAGE_CODE_REVIEW}** ` +
       `(reinicie o Status para ${PROGRESS_TODO}). As Tasks já estão em ${STAGE_DONE}.`
@@ -398,7 +403,7 @@ export function buildFeatureContext({
   lines.push(`   1. **Ao começar:** Status da Task → **${PROGRESS_IN_PROGRESS}** (a Etapa continua ${STAGE_DEVELOPMENT}).`);
   lines.push('   2. **Implemente** a Task por completo.');
   lines.push(`   3. **Ao concluir:** **avance a Task para a Etapa ${STAGE_DONE}** com Status **${PROGRESS_DONE}**.`);
-  lines.push(`3. **Ao concluir TODAS as Tasks da Story:** faça o **commit**, abra o **Pull Request** da Story e **avance a Etapa da Story para ${STAGE_CODE_REVIEW}** (Status ${PROGRESS_TODO}).`);
+  lines.push(`3. **Ao concluir TODAS as Tasks da Story:** faça o **commit**, abra o **Pull Request** da Story **como rascunho** (\`gh pr create --draft\` — o CI não roda em rascunho; quem revisa marca o PR como pronto e os checks disparam) e **avance a Etapa da Story para ${STAGE_CODE_REVIEW}** (Status ${PROGRESS_TODO}).`);
   lines.push('4. Só então inicie a próxima Story.');
   lines.push('');
   lines.push(

package/src/commands/install-skill.mjs

@@ -141,18 +141,28 @@ export function renderContent(format, parsed, version) {
   }
 }
 
-// Insere/atualiza o bloco spec-wave num arquivo compartilhado (AGENTS.md),
-// preservando o restante do conteúdo. Idempotente via marcadores.
-export function mergeAgentsFile(destPath, block) {
-  const existing = existsSync(destPath) ? readFileSync(destPath, 'utf-8') : '';
+// Insere/atualiza o bloco spec-wave num texto de arquivo compartilhado
+// (AGENTS.md), preservando o restante do conteúdo. Idempotente via marcadores.
+//
+// Versão PURA, separada da que lê o disco porque o modo `--branch` do update
+// precisa mesclar o bloco no conteúdo da BASE, não no do arquivo local: o
+// AGENTS.md do desenvolvedor pode ter edições ainda não commitadas, e arrastá-las
+// para dentro do Pull Request seria enviar o que ninguém pediu para revisar.
+export function mergeAgentsContent(existing, block) {
+  const atual = existing || '';
   const blockRe = new RegExp(
     `${escapeRe(BLOCK_START)}[\\s\\S]*?${escapeRe(BLOCK_END)}\\n?`,
   );
-  if (blockRe.test(existing)) {
-    return existing.replace(blockRe, block);
+  if (blockRe.test(atual)) {
+    return atual.replace(blockRe, block);
   }
-  if (existing.trim() === '') return block;
-  return `${existing.trimEnd()}\n\n${block}`;
+  if (atual.trim() === '') return block;
+  return `${atual.trimEnd()}\n\n${block}`;
+}
+
+// Mesmo merge, lendo o arquivo de destino do disco.
+export function mergeAgentsFile(destPath, block) {
+  return mergeAgentsContent(existsSync(destPath) ? readFileSync(destPath, 'utf-8') : '', block);
 }
 
 function escapeRe(s) {

package/src/commands/preflight.mjs

@@ -0,0 +1,322 @@
+// Preflight de uma rodada de geração de specs por milestone.
+//
+// Existe porque **cada geração paga um modelo**: descobrir na sétima Feature que
+// a credencial estava errada custa sete gerações. Este comando levanta de uma
+// vez tudo que decide a estratégia da rodada e tudo que costuma fazê-la falhar
+// no fim — antes de gerar qualquer coisa.
+//
+// Ele NÃO é um segundo `doctor`. As verificações de ambiente reaproveitam os
+// mesmos inspetores puros que o doctor usa (`describeModeState`,
+// `inspectPrPublishing`); o que é novo aqui é o **inventário da milestone**:
+// quais Features existem, e onde está o `spec.md` de cada uma.
+//
+// E "onde está" é a parte que não dá para improvisar com `existsSync`. Um
+// documento recém-gerado vive numa branch `spec-wave/<n>-spec` que ninguém
+// mergeou: quem procura só no disco o declara ausente e manda gerar de novo —
+// pagando o modelo pela segunda vez pelo mesmo documento. Por isso o estado sai
+// de `artifactStates`, que enxerga as quatro camadas.
+
+import * as p from '@clack/prompts';
+import chalk from 'chalk';
+
+import { resolveToken } from '../api/auth.mjs';
+import {
+  getRepoDefaultBranch, getRepoVariable, listMilestones, listIssuesByMilestone,
+} from '../api/github-rest.mjs';
+import { CONFIG_FILE } from '../config.mjs';
+import { inspectPrPublishing, readPrPublishingContext } from './doctor.mjs';
+import { configuredMode, describeModeState, EXECUTION_VARIABLE } from '../lib/execution-mode.mjs';
+import { detectIssueType } from '../lib/issue-type.mjs';
+import { isAwaitingMerge, artifactStates } from '../lib/doc-source.mjs';
+import { featureDocPaths } from '../lib/doc-paths.mjs';
+import { STEPS } from '../lib/next-step.mjs';
+import { loadConfig } from '../lib/project-root.mjs';
+import { unguardedWorkflows } from './mode.mjs';
+
+const TRIGGER_LABELS = Object.values(STEPS).map(s => s.trigger).filter(Boolean);
+
+/**
+ * O inventário da milestone (função PURA — é onde mora a decisão).
+ *
+ * Separa as Features em quatro destinos porque cada um pede uma ação diferente,
+ * e confundi-los é caro nos dois sentidos: tratar `pending-pr` como ausente
+ * regera um documento já pago e ainda descarta a revisão em curso; tratar
+ * `unknown` (falha de rede) como pronto pula uma Feature que ninguém escreveu.
+ *
+ * @param {object} [a]
+ * @param {Array<{number:number,title:string,state?:string,labels?:Array}>} [a.issues]
+ *        issues da milestone, como a API devolve (de qualquer tipo)
+ * @param {Record<number, {state: string, pr: object|null}>} [a.specStates]
+ *        estado do `spec.md` por número de issue
+ * @returns {{ features: object[], gerar: object[], prontas: object[],
+ *             aguardandoMerge: object[], indefinidas: object[], fechadas: object[],
+ *             gatilhosPendentes: Array<{number:number,labels:string[]}> }}
+ */
+export function inspectMilestone({ issues = [], specStates = {} } = {}) {
+  const features = (issues || [])
+    .filter(i => detectIssueType(i) === 'Feature')
+    .map(i => {
+      const { state = 'unknown', pr = null } = specStates[i.number] || {};
+      return {
+        number: i.number,
+        title: i.title,
+        closed: i.state === 'closed',
+        spec: state,
+        pr,
+        labels: (i.labels || []).map(l => (typeof l === 'string' ? l : l?.name)).filter(Boolean),
+      };
+    })
+    .sort((a, b) => a.number - b.number);
+
+  const abertas = features.filter(f => !f.closed);
+  return {
+    features,
+    fechadas: features.filter(f => f.closed),
+    gerar: abertas.filter(f => f.spec === 'missing'),
+    prontas: abertas.filter(f => f.spec === 'local' || f.spec === 'remote'),
+    aguardandoMerge: abertas.filter(f => isAwaitingMerge(f.spec)),
+    indefinidas: abertas.filter(f => f.spec === 'unknown'),
+    // Label de gatilho grudada significa Action em execução — ou uma que falhou e
+    // a deixou para trás. Nos dois casos o `run` se recusa a executar (portão
+    // `trigger-pending`), então a rodada travaria Feature a Feature.
+    gatilhosPendentes: features
+      .map(f => ({ number: f.number, labels: f.labels.filter(l => TRIGGER_LABELS.includes(l)) }))
+      .filter(f => f.labels.length > 0),
+  };
+}
+
+/**
+ * Resolve o título da milestone para o número que a API de issues aceita (PURA).
+ *
+ * Casamento exato primeiro; sem ele, um único casamento sem diferenciar
+ * maiúsculas. Ambíguo é erro, não escolha silenciosa: gerar as specs da
+ * milestone errada custa uma geração por Feature.
+ *
+ * @param {Array<{number:number,title:string,state?:string}>} milestones
+ * @param {string} titulo
+ * @returns {{ milestone: object|null, error: string|null }}
+ */
+export function resolveMilestone(milestones = [], titulo = '') {
+  const alvo = String(titulo || '').trim();
+  const lista = () => (milestones.length
+    ? milestones.map(m => `"${m.title}"`).join(', ')
+    : '(o repositório não tem milestone nenhuma)');
+
+  if (!alvo) return { milestone: null, error: `Milestone não informada. Existem: ${lista()}.` };
+
+  const exata = milestones.find(m => m.title === alvo);
+  if (exata) return { milestone: exata, error: null };
+
+  const caseInsensitive = milestones.filter(m => m.title.toLowerCase() === alvo.toLowerCase());
+  if (caseInsensitive.length === 1) return { milestone: caseInsensitive[0], error: null };
+  if (caseInsensitive.length > 1) {
+    return { milestone: null, error: `Milestone "${alvo}" é ambígua entre ${lista()}.` };
+  }
+  return { milestone: null, error: `Milestone "${alvo}" não existe. Existem: ${lista()}.` };
+}
+
+/**
+ * Veredito final da rodada (função PURA).
+ *
+ * `bloqueios` impedem gerar; `avisos` não. A distinção é a razão de o comando
+ * existir: sair 1 por algo que não impede a geração faria o usuário aprender a
+ * ignorar o preflight, que é o mesmo que não o ter.
+ *
+ * @returns {{ status: 'ok'|'aviso'|'bloqueio', bloqueios: string[], avisos: string[] }}
+ */
+export function inspectPreflight({
+  tokenOk = true, modo = null, publicacao = null, inventario = null,
+} = {}) {
+  const bloqueios = [];
+  const avisos = [];
+
+  if (!tokenOk) bloqueios.push('Sem token utilizável para este repositório.');
+
+  if (modo?.status === 'problem') bloqueios.push(modo.summary);
+  else if (modo?.status === 'warn') avisos.push(modo.summary);
+
+  // A publicação por PR é o desfecho de TODA geração: sem ela o documento é
+  // gerado, o commit criado e nenhum PR aparece — a falha mais cara do fluxo,
+  // porque o modelo já foi pago quando ela acontece.
+  if (publicacao?.status === 'fail') bloqueios.push(...publicacao.notes);
+  else if (publicacao?.status === 'warn') avisos.push(...publicacao.notes);
+
+  if (inventario) {
+    if (inventario.features.length === 0) {
+      bloqueios.push('Nenhuma Feature [FEATURE] nesta milestone.');
+    } else if (inventario.gerar.length === 0) {
+      avisos.push('Nenhuma Feature pendente: todas já têm spec.md.');
+    }
+    if (inventario.gatilhosPendentes.length > 0) {
+      avisos.push(
+        `${inventario.gatilhosPendentes.length} issue(s) com label de gatilho pendente — ` +
+        'o `run` se recusa a executar nelas até a label sair.'
+      );
+    }
+    if (inventario.aguardandoMerge.length > 0) {
+      avisos.push(
+        `${inventario.aguardandoMerge.length} spec(s) já geradas aguardando merge — ` +
+        'NÃO as gere de novo: o documento existe e regerá-lo descarta a revisão.'
+      );
+    }
+    if (inventario.indefinidas.length > 0) {
+      avisos.push(
+        `${inventario.indefinidas.length} Feature(s) com estado indeterminado (falha de rede) — ` +
+        'confirme antes de gerar, para não pagar duas vezes.'
+      );
+    }
+  }
+
+  if (bloqueios.length) return { status: 'bloqueio', bloqueios, avisos };
+  if (avisos.length) return { status: 'aviso', bloqueios, avisos };
+  return { status: 'ok', bloqueios, avisos };
+}
+
+const MARCA = { local: '✓ no disco', remote: '✓ na base', 'pending-pr': '⏳ em PR aberto', 'branch-only': '⚠ em branch sem PR', missing: '· gerar', unknown: '? indeterminado' };
+
+export async function preflight({ milestone: milestoneArg, json = false } = {}) {
+  const saida = { milestone: null, modo: null, publicacao: null, inventario: null, veredito: null };
+  const falhar = (msg) => {
+    if (json) console.log(JSON.stringify({ ...saida, erro: msg }, null, 2));
+    else p.log.error(msg);
+    process.exitCode = 1;
+  };
+
+  if (!json) p.intro(chalk.bold('spec-wave preflight'));
+
+  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('Consultando o repositório...');
+
+  let base;
+  try {
+    base = await getRepoDefaultBranch(token, owner, repo);
+  } catch (err) {
+    s?.stop('');
+    return falhar(`Não foi possível ler o repositório ${owner}/${repo}: ${err.message}`);
+  }
+
+  // --- Modo de execução: config × variável (o mesmo par que o doctor confere).
+  let variable;
+  try {
+    variable = await getRepoVariable(token, owner, repo, EXECUTION_VARIABLE);
+  } catch {
+    variable = undefined; // exige admin — "não deu para ler" não é "ausente"
+  }
+  const modo = describeModeState({
+    configured: configuredMode(config),
+    variable,
+    unguardedWorkflows: unguardedWorkflows(root),
+  });
+
+  // --- Publicação por Pull Request: é o desfecho de toda geração.
+  const publicacao = inspectPrPublishing(
+    await readPrPublishingContext({ token, owner, repo, root })
+  );
+
+  // --- Inventário da milestone.
+  let milestones;
+  try {
+    milestones = await listMilestones(token, owner, repo);
+  } catch (err) {
+    s?.stop('');
+    return falhar(`Não foi possível listar as milestones: ${err.message}`);
+  }
+  const { milestone, error: msError } = resolveMilestone(milestones, milestoneArg);
+  if (msError) {
+    s?.stop('');
+    return falhar(msError);
+  }
+
+  let issues;
+  try {
+    issues = await listIssuesByMilestone(token, owner, repo, milestone.number);
+  } catch (err) {
+    s?.stop('');
+    return falhar(`Não foi possível listar as issues da milestone "${milestone.title}": ${err.message}`);
+  }
+
+  // O estado do spec.md de cada Feature, nas quatro camadas. Uma issue por vez:
+  // são até 3 requisições cada, e disparar tudo de uma vez numa milestone de 20
+  // Features é o caminho mais curto para o rate limit secundário.
+  const featureIssues = issues.filter(i => detectIssueType(i) === 'Feature');
+  const specStates = {};
+  for (const issue of featureIssues) {
+    const docs = featureDocPaths(root, issue, 'Feature');
+    const estados = await artifactStates({
+      token, owner, repo, root, base,
+      issueNumber: issue.number,
+      docs: [{ doc: 'spec', pathRel: docs.spec.rel }],
+    });
+    specStates[issue.number] = estados.spec;
+  }
+
+  const inventario = inspectMilestone({ issues, specStates });
+  const veredito = inspectPreflight({ tokenOk: true, modo, publicacao, inventario });
+  s?.stop(`Milestone "${milestone.title}": ${inventario.features.length} Feature(s).`);
+
+  Object.assign(saida, {
+    milestone: { title: milestone.title, number: milestone.number, base },
+    modo: { configured: configuredMode(config), variable: variable ?? null, status: modo.status, summary: modo.summary },
+    publicacao: { status: publicacao.status, notes: publicacao.notes },
+    inventario,
+    veredito,
+  });
+
+  if (json) {
+    console.log(JSON.stringify(saida, null, 2));
+    if (veredito.status === 'bloqueio') process.exitCode = 1;
+    return saida;
+  }
+
+  // ---------- Relatório ----------
+  const linhas = [];
+  linhas.push(`${chalk.bold('Repositório:')} ${owner}/${repo} (base: ${base})`);
+  linhas.push(`${chalk.bold('Modo:')} config=${configuredMode(config)} · variável=${variable ?? '<ausente>'}`);
+  linhas.push(`   ${modo.summary}`);
+  linhas.push(`${chalk.bold('Publicação por PR:')} ${publicacao.status}`);
+  for (const nota of publicacao.notes) linhas.push(`   ${nota}`);
+  p.note(linhas.join('\n'), 'Ambiente');
+
+  const inv = [];
+  for (const f of inventario.features) {
+    const marca = f.closed ? '× fechada' : (MARCA[f.spec] || f.spec);
+    const pr = f.pr ? chalk.dim(` PR #${f.pr.number}`) : '';
+    inv.push(`  ${marca.padEnd(20)} #${f.number} ${f.title.slice(0, 60)}${pr}`);
+  }
+  if (inventario.gatilhosPendentes.length) {
+    inv.push('');
+    inv.push(chalk.yellow('  Labels de gatilho pendentes (remova antes de gerar):'));
+    for (const g of inventario.gatilhosPendentes) inv.push(`    #${g.number}: ${g.labels.join(', ')}`);
+  }
+  p.note(inv.join('\n'), `Milestone "${milestone.title}" — ${inventario.gerar.length} a gerar`);
+
+  for (const a of veredito.avisos) p.log.warn(a);
+  for (const b of veredito.bloqueios) p.log.error(b);
+
+  if (veredito.status === 'bloqueio') {
+    p.outro(`${veredito.bloqueios.length} bloqueio(s). Resolva antes de gerar.`);
+    process.exitCode = 1;
+    return saida;
+  }
+  p.outro(
+    inventario.gerar.length
+      ? `Preflight ok. Confirme a lista com o usuário antes de gerar ${inventario.gerar.length} spec(s).`
+      : 'Preflight ok. Nada a gerar.'
+  );
+  return saida;
+}