@spec-wave/cli 0.27.0 → 0.29.0

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

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/commands/update.mjs

@@ -12,7 +12,7 @@ import {
 } from '../api/github-rest.mjs';
 import {
   resolveBranchName, composePrTitle, composePrBody, buildCommitMessage,
-  decideConfigInPr, explainGitWriteError,
+  decideConfigInPr, decideSkillInPr, composeConfigCleanupHint, explainGitWriteError,
 } from '../lib/pr-branch.mjs';
 // MESMO readTemplate do init: resolve {{CLI_VERSION}} antes da comparação byte a
 // byte com o remoto. Se só o init resolvesse, todo update veria os workflows
@@ -20,10 +20,11 @@ import {
 import { readTemplate } from '../lib/templates.mjs';
 import {
   TARGETS, SKILL_SOURCE, CLI_VERSION, parseSkill, renderContent,
-  mergeAgentsFile, resolveDest, isDetected, skillCopyReason, versionBanner,
+  mergeAgentsFile, mergeAgentsContent, resolveDest, isDetected, skillCopyReason, versionBanner,
 } from './install-skill.mjs';
 import { planPluginSkillFiles } from '../lib/plugin-skills.mjs';
 import { findConfigPath } from '../lib/project-root.mjs';
+import { currentGitBranch } from '../lib/repo-links.mjs';
 
 // Arquivos do repo gerenciados pela CLI (comparados com o template empacotado).
 const REPO_FILES = [
@@ -68,6 +69,41 @@ function applySkill(job) {
   writeFileSync(job.dest.path, content, 'utf-8');
 }
 
+/**
+ * Arquivos que uma atualização de skill grava, em caminhos RELATIVOS à raiz do
+ * repositório — a chave para perguntar à base se aquela cópia é versionada.
+ *
+ * Devolve [] quando o destino cai FORA da raiz, e é o que dispensa um caso
+ * especial para `--global`: `~/.claude/skills/...` e o `~/.gemini/AGENTS.md` do
+ * Antigravity jamais são conteúdo de repositório, e `path.relative` já diz isso.
+ *
+ * O formato `agents` (AGENTS.md) devolve `block` em vez de `content`: o conteúdo
+ * final depende do que existe na BASE — mesclar no arquivo local arrastaria para
+ * dentro do PR as edições não commitadas do desenvolvedor.
+ *
+ * @param {{dest: {path: string, format: string}, desired?: string}} job
+ * @param {string} repoRoot
+ * @returns {Array<{ relPath: string, content?: string, block?: string }>}
+ */
+export function skillRepoTargets(job, repoRoot) {
+  const items = job.dest.format === 'skills-dir'
+    ? planPluginSkillFiles(job.dest.path, CLI_VERSION, versionBanner)
+        .map(f => ({ absPath: f.path, content: f.content }))
+    : [{
+        absPath: job.dest.path,
+        ...(job.dest.format === 'agents' ? { block: job.desired } : { content: job.desired }),
+      }];
+
+  const out = [];
+  for (const { absPath, ...rest } of items) {
+    const rel = path.relative(repoRoot, absPath);
+    if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) continue;
+    // A API do GitHub fala POSIX; path.relative devolve no separador do SO.
+    out.push({ ...rest, relPath: rel.split(path.sep).join('/') });
+  }
+  return out;
+}
+
 /**
  * Compara ALL_LABELS com as labels do repo (função PURA — testável).
  *
@@ -325,6 +361,70 @@ export async function update(options = {}) {
     }
   }
 
+  // 2d) Skill: a BASE versiona alguma destas cópias?
+  //
+  // Até aqui o update gravava a skill em disco e o corpo do PR AFIRMAVA ao
+  // revisor que ela "não faz parte do repositório" — premissa fixa. Em repos que
+  // versionam `.claude/skills/spec-wave/SKILL.md` (ou `.agents/skills/`, ou o
+  // AGENTS.md) isso era falso duas vezes: sobrava um commit manual a cada bump, e
+  // até ele o repositório seguia distribuindo a skill da versão anterior para
+  // quem clonasse. A checagem é a MESMA do .spec-wave.json — perguntar à base —,
+  // e a política também: só entra no PR o que o projeto já versiona.
+  let skillPrFiles = [];        // [{ relPath, content, reason, agent }]
+  // agente → motivo da PRIMEIRA cópia incluída. É o motivo que o resumo mostra:
+  // dizer "versionada no repo" para uma cópia que entrou por `--skill-in-pr`
+  // seria repetir, em miniatura, a premissa que este código veio corrigir.
+  const skillPrAgents = new Map();
+  // `skillRepoTargets` já devolve vazio para o que mora fora da raiz, o que cobre
+  // o `--global` inteiro sem um caso especial: nada a perguntar, nada a gastar.
+  const skillCandidates = prMode
+    ? skillJobs
+        .map(job => ({ job, targets: skillRepoTargets(job, path.dirname(configPath)) }))
+        .filter(c => c.targets.length)
+    : [];
+  if (skillCandidates.length) {
+    const tk = await getToken();
+    const s = p.spinner();
+    s.start('Verificando se o repositório versiona a skill...');
+    try {
+      for (const { job, targets } of skillCandidates) {
+        // Em paralelo: o destino do Codex são 20+ arquivos, e um GET por vez
+        // transformaria a checagem na parte mais lenta do comando.
+        const remotes = await Promise.all(
+          targets.map(t => getFileContent(tk, owner, repo, t.relPath, base))
+        );
+        targets.forEach((t, i) => {
+          const remote = remotes[i];
+          const desired = t.block !== undefined
+            ? mergeAgentsContent(remote ?? '', t.block)
+            : t.content;
+          const d = decideSkillInPr({ remote, desired, force: options.skillInPr });
+          if (!d.included) return;
+          skillPrFiles.push({
+            relPath: t.relPath,
+            content: desired,
+            reason: remote == null ? 'ausente' : 'desatualizado',
+            agent: job.target.name,
+          });
+          if (!skillPrAgents.has(job.target.name)) skillPrAgents.set(job.target.name, d.reason);
+        });
+      }
+      s.stop(skillPrFiles.length
+        ? `Skill versionada no repositório: ${skillPrFiles.length} arquivo(s) vão no Pull Request.`
+        : 'A skill não é versionada neste repositório — segue apenas local.');
+    } catch (err) {
+      // Falhar aqui não pode custar o update inteiro: sem a resposta da base, a
+      // skill volta a ser só local — o comportamento anterior, agora explícito.
+      s.stop('');
+      p.log.warn(`Não foi possível checar a skill na base: ${err.message} — ela seguirá apenas local.`);
+      skillPrFiles = [];
+      skillPrAgents.clear();
+    }
+  }
+  const skillLocalAgents = skillJobs
+    .map(j => j.target.name)
+    .filter(n => !skillPrAgents.has(n));
+
   // Decisão preliminar sobre o config. O conteúdo regenerado ainda não existe;
   // `willRegenerate` cobre isso, porque o regenerado SEMPRE difere do remoto
   // (refreshedAt muda a cada execução). Na aplicação a decisão é recalculada com
@@ -355,21 +455,39 @@ export async function update(options = {}) {
   const lines = [];
   if (skillJobs.length) {
     lines.push(chalk.bold('Skill:'));
-    for (const j of skillJobs) lines.push(`  ${chalk.yellow('↻')} ${j.target.name} (${j.reason})\n     ${chalk.dim(j.dest.path)}`);
+    for (const j of skillJobs) {
+      const destino = skillPrAgents.has(j.target.name)
+        ? chalk.dim(` → vai no PR: ${skillPrAgents.get(j.target.name)}`)
+        : '';
+      lines.push(`  ${chalk.yellow('↻')} ${j.target.name} (${j.reason})${destino}\n     ${chalk.dim(j.dest.path)}`);
+    }
   }
   if (configStale) {
     lines.push(chalk.bold('Config local:'));
     lines.push(`  ${chalk.yellow('↻')} ${CONFIG_FILE} — ${configStale.reason}` +
       (configStale.canApply ? '' : chalk.dim(' (sem project.id — rode `init` sem --skip-project)')));
   }
+  // Cabeçalho ÚNICO no modo PR: workflows, skill e config viajam no mesmo commit,
+  // e três títulos para um commit só sugeriam três destinos diferentes.
+  let prHeaderShown = false;
+  const prHeader = () => {
+    if (prHeaderShown) return;
+    prHeaderShown = true;
+    lines.push(chalk.bold(`Pull Request (${branch} → ${base}):`));
+  };
   if (repoFiles.length) {
-    lines.push(prMode
-      ? chalk.bold(`Arquivos do repo → Pull Request (${branch} → ${base}):`)
-      : chalk.bold('Arquivos do repo:'));
+    if (prMode) prHeader();
+    else lines.push(chalk.bold('Arquivos do repo:'));
     for (const f of repoFiles) lines.push(`  ${chalk.yellow('↻')} ${f.repoPath} (${f.reason})`);
   }
+  if (skillPrFiles.length) {
+    prHeader();
+    for (const f of skillPrFiles) {
+      lines.push(`  ${chalk.yellow('↻')} ${f.relPath} (${f.reason} — skill ${f.agent})`);
+    }
+  }
   if (prMode && configDecision.included) {
-    if (!repoFiles.length) lines.push(chalk.bold(`Pull Request (${branch} → ${base}):`));
+    prHeader();
     lines.push(`  ${chalk.yellow('↻')} ${CONFIG_FILE} (${configDecision.reason})`);
   }
   if (prMode && doConfig && !configDecision.included && configDecision.reason) {
@@ -388,7 +506,8 @@ export async function update(options = {}) {
   p.note(lines.join('\n'), `${total} item(ns) desatualizado(s)`);
 
   // --branch sem efeito: melhor dizer POR QUE do que criar uma branch inútil.
-  const prHasPayload = prMode && (repoFiles.length > 0 || configDecision.included);
+  const prHasPayload = prMode
+    && (repoFiles.length > 0 || skillPrFiles.length > 0 || configDecision.included);
   if (prRequested && options.skipRepo) {
     p.log.warn(
       '--branch ignorado junto com --skip-repo: o Pull Request existe justamente para ' +
@@ -408,7 +527,7 @@ export async function update(options = {}) {
 
   if (options.dryRun) {
     if (prHasPayload) {
-      const n = repoFiles.length + (configDecision.included ? 1 : 0);
+      const n = repoFiles.length + skillPrFiles.length + (configDecision.included ? 1 : 0);
       p.note(
         `Branch:    ${branch}${branchExists ? ' (já existe — o commit seria empilhado nela)' : ' (seria criada)'}\n` +
         `Base:      ${base}\n` +
@@ -516,6 +635,11 @@ export async function update(options = {}) {
     const tk = await getToken();
     const treeFiles = [
       ...repoFiles.map(f => ({ path: f.repoPath, reason: f.reason, content: f.local })),
+      ...skillPrFiles.map(f => ({
+        path: f.relPath,
+        reason: `${f.reason} — skill ${f.agent}`,
+        content: f.content,
+      })),
       ...(finalConfigDecision.included
         ? [{
             path: CONFIG_FILE,
@@ -562,7 +686,7 @@ export async function update(options = {}) {
               files: treeFiles,
               config: doConfig ? finalConfigDecision : null,
               labels: labelResult,
-              skill: skillJobs.map(j => j.target.name),
+              skill: { inPr: [...skillPrAgents.keys()], local: skillLocalAgents },
             }),
           });
           if (!pr) {
@@ -605,9 +729,16 @@ export async function update(options = {}) {
     (prUrl ? ` Revise e faça o merge do Pull Request: ${prUrl}` : '') +
     (!prMode && repoFiles.length ? ' Arquivos do repo foram commitados no remoto.' : '') +
     (configPending ? ` COMMITE o ${CONFIG_FILE} — quem clona o repo (dev-agent, Actions) lê a versão commitada.` : '') +
+    // A dica de descarte depende da branch do CHECKOUT, não de premissa:
+    // `git checkout -- <arquivo>` restaura o que está no índice, e rodado de uma
+    // branch de trabalho reverte o arquivo para a versão ANTIGA dela — o oposto
+    // do que a mensagem promete.
     (finalConfigDecision.included
-      ? ` O ${CONFIG_FILE} local ficou igual ao do PR — depois do merge, descarte a cópia ` +
-        `local com \`git checkout -- ${CONFIG_FILE}\`.`
+      ? ` ${composeConfigCleanupHint({
+          file: CONFIG_FILE,
+          base,
+          current: currentGitBranch(path.dirname(configPath)),
+        })}`
       : '')
   );
 }

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