@spec-wave/cli 0.15.0 → 0.16.0

package/src/commands/implement.mjs

@@ -6,11 +6,13 @@ import path from 'node:path';
 import { resolveToken } from '../api/auth.mjs';
 import {
   CONFIG_FILE, STAGE_DEVELOPMENT, STAGE_CODE_REVIEW, STAGE_DONE, STAGE_ORDER,
-  PROGRESS_TODO, PROGRESS_IN_PROGRESS, PROGRESS_DONE,
+  PROGRESS_TODO, PROGRESS_IN_PROGRESS, PROGRESS_DONE, labelNames,
 } from '../config.mjs';
 import { getIssue, listIssueComments, listBlockedBy } from '../api/github-rest.mjs';
 import { listSubIssues, getIssueParent, addProjectItem, getItemSingleSelectValue } from '../api/github-graphql.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
+import { bugDocPaths } from '../lib/bug-doc.mjs';
+import { buildBugContext } from '../lib/bug-context.mjs';
 import { slugify } from '../lib/slugify.mjs';
 import { parseDependencies, orderStories, formatDependencyLine } from '../lib/dependencies.mjs';
 import { loadProjectConfig, resolveField } from '../lib/board.mjs';
@@ -360,6 +362,102 @@ function renderCommand(template, vars) {
 // Modo Feature: avalia as Stories da Feature (dependências + Etapa no board),
 // pula as já implementadas (Code Review+) e monta UM contexto único com todas
 // as pendentes em ordem topológica — spec-kit acionado uma vez.
+/**
+ * Modo Bug (RFC-004 §7.1): sem tasks, sem spec/plan, sem Feature-pai a arrastar.
+ *
+ * O bug.md, quando existe, entra como HIPÓTESE — foi escrito por IA sem
+ * executar código, e o contexto diz isso explicitamente ao executor. Quando não
+ * existe (o caso do P0, que dispensa o documento), o contexto assume a
+ * investigação inteira.
+ */
+async function implementBug({ token, owner, repo, config, bug, dryRun, repoRoot }) {
+  const issueNumber = bug.number;
+  const severity = (labelNames(bug).find(n => /^P[0-3]$/.test(n))) || null;
+
+  // Item afetado (best-effort): dá ao executor o contexto do que quebrou. O pai
+  // de um Bug pode ser Feature OU Story — o tipo vem do prefixo do título.
+  let parent = null;
+  try {
+    const p0 = await getIssueParent(token, bug.node_id);
+    if (p0?.number) {
+      parent = { number: p0.number, title: p0.title, kind: detectIssueType(p0) || 'Item' };
+    }
+  } catch {
+    // sem pai legível — bug órfão é caso previsto (reporte de suporte)
+  }
+
+  // bug.md do repositório, se já foi gerado.
+  const { fileAbs, fileRel } = bugDocPaths(bug.title, repoRoot);
+  let bugDoc = null;
+  if (existsSync(fileAbs)) {
+    bugDoc = readFileSync(fileAbs, 'utf-8');
+    p.log.info(`bug.md encontrado em ${chalk.cyan(fileRel)}.`);
+  } else {
+    p.log.warn(`Sem bug.md em ${fileRel} — o contexto assume a investigação inteira.`);
+  }
+
+  // Board: Bug → Desenvolvimento (In Progress). Não move a Feature-pai.
+  await applyBoardMoves({
+    token,
+    moves: planBoardMoves('start', { bug: { nodeId: bug.node_id, number: issueNumber } }),
+    cwd: repoRoot || process.cwd(),
+    dryRun,
+  });
+
+  const comments = [];
+  const all = await listIssueComments(token, owner, repo, issueNumber).catch(() => []);
+  if (all.length > 0) {
+    const items = all.slice(-MAX_COMMENTS_PER_ISSUE).map(c => ({
+      ...c,
+      body: c.body.length > MAX_COMMENT_CHARS
+        ? `${c.body.slice(0, MAX_COMMENT_CHARS)}…[truncado]`
+        : c.body,
+    }));
+    comments.push({ issueNumber, kind: 'Bug', total: all.length, items });
+  }
+
+  let codeDigest = null;
+  try {
+    codeDigest = await buildCodeDigest({ sinceIso: bug.created_at || null, paths: [] });
+  } catch {
+    codeDigest = null;
+  }
+
+  const blockedByWarnings = [];
+  try {
+    const blocked = await listBlockedBy(token, owner, repo, issueNumber).catch(() => []);
+    for (const b of blocked) {
+      if (b?.state !== 'closed') blockedByWarnings.push(`#${b.number} — ${b.title}`);
+    }
+  } catch {
+    // dependências não legíveis — segue
+  }
+
+  const context = buildBugContext({
+    bug: { number: issueNumber, title: bug.title, body: bug.body || '' },
+    bugDoc, parent, comments, codeDigest, blockedByWarnings, severity,
+  });
+
+  await writeContextAndRunSpecKit({
+    config,
+    issueNumber,
+    type: 'Bug',
+    title: bug.title,
+    specPlan: { spec: null, plan: null, specPath: null, planPath: null },
+    context,
+    dryRun,
+    outroSuccess: `Bug #${issueNumber} corrigido — abra o PR com \`Fixes #${issueNumber}\`.`,
+    onSuccess: async () => {
+      await applyBoardMoves({
+        token,
+        moves: planBoardMoves('success', { bug: { nodeId: bug.node_id, number: issueNumber } }),
+        cwd: repoRoot || process.cwd(),
+        dryRun,
+      });
+    },
+  });
+}
+
 async function implementFeature({ token, owner, repo, config, feature, featureDirOpt, dryRun, repoRoot }) {
   // F1. Stories (sub-issues) da Feature.
   const subs = await listSubIssues(token, feature.node_id).catch(() => []);
@@ -630,9 +728,14 @@ export async function implement({ issue: issueArg, featureDir: featureDirOpt, dr
     // Modo Feature: Stories pendentes em ordem de dependência, contexto único.
     await implementFeature({ token, owner, repo, config, feature: issue, featureDirOpt, dryRun, repoRoot });
     return;
+  } else if (type === 'Bug') {
+    // Modo Bug: sem tasks e sem spec/plan — o trabalho é investigar antes de
+    // corrigir, e o contexto impõe essa ordem.
+    await implementBug({ token, owner, repo, config, bug: issue, dryRun, repoRoot });
+    return;
   } else {
     p.log.error(
-      `implement só aceita Feature, Story ou Task. Issue #${issueNumber} é do tipo ${type || 'desconhecido'}.`
+      `implement aceita Feature, Story, Task ou Bug. Issue #${issueNumber} é do tipo ${type || 'desconhecido'}.`
     );
     process.exitCode = 1;
     return;

package/src/commands/init.mjs

@@ -9,7 +9,7 @@ import { setupProject } from '../setup/project.mjs';
 import { setupLabels } from '../setup/labels.mjs';
 import { setupFiles } from '../setup/files.mjs';
 import { getFileContent } from '../api/github-rest.mjs';
-import { CONFIG_FILE, AI_PROVIDERS, getProvider, DEFAULT_PROVIDER, PORTAL_URL, WORKFLOW_FILES, ISSUE_TEMPLATE_FILES } from '../config.mjs';
+import { CONFIG_FILE, AI_PROVIDERS, getProvider, DEFAULT_PROVIDER, PORTAL_URL, WORKFLOW_FILES, ISSUE_TEMPLATE_FILES, STATUS_OPTIONS, ALL_LABELS } from '../config.mjs';
 
 const __dir = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(path.join(__dir, '..', '..', 'package.json'), 'utf-8'));
@@ -143,7 +143,7 @@ export async function init(options) {
     labelSpinner.start('Criando labels...');
     try {
       await setupLabels(token, owner, repo, labelSpinner);
-      labelSpinner.stop('Labels criadas (16 labels)');
+      labelSpinner.stop(`Labels criadas (${ALL_LABELS.length} labels)`);
     } catch (err) {
       labelSpinner.stop('');
       p.log.error(`Erro ao criar labels: ${err.message}`);
@@ -204,7 +204,7 @@ export async function init(options) {
   }
 
   p.note(
-    'As 12 colunas do RFC-001 foram criadas no campo "Etapa".\n' +
+    `As ${STATUS_OPTIONS.length} colunas do RFC-001 foram criadas no campo "Etapa".\n` +
     'Para usá-las como colunas do board:\n' +
     '  1. Abra o projeto no GitHub\n' +
     '  2. Clique em "..." → "Settings" da view de Board\n' +

package/src/commands/install-skill.mjs

@@ -1,10 +1,11 @@
 import * as p from '@clack/prompts';
 import chalk from 'chalk';
-import yaml from 'js-yaml';
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 import path from 'node:path';
+import { parseSkill } from '../lib/skill-file.mjs';
+import { listPluginSkills, planPluginSkillFiles } from '../lib/plugin-skills.mjs';
 
 const __dir = path.dirname(fileURLToPath(import.meta.url));
 // Fonte única da skill, publicada via "files": ["src"] no package.json.
@@ -33,6 +34,17 @@ export const TARGETS = [
     project: '.claude/skills/spec-wave/SKILL.md',
     global: '.claude/skills/spec-wave/SKILL.md',
   },
+  {
+    key: 'codex',
+    name: 'Codex CLI',
+    // Codex não tem conceito de plugin: ele varre diretórios de skills. Então o
+    // MESMO conteúdo do plugin é copiado skill a skill para `.agents/skills`,
+    // que é o caminho que o Codex lê no repo (e `~/.agents/skills` no usuário).
+    format: 'skills-dir',
+    detect: ['.codex', '.agents'],
+    project: path.join('.agents', 'skills'),
+    global: path.join('.agents', 'skills'),
+  },
   {
     key: 'opencode',
     name: 'opencode',
@@ -86,22 +98,14 @@ export const TARGETS = [
 
 const TARGET_BY_KEY = new Map(TARGETS.map((t) => [t.key, t]));
 
-// Separa o frontmatter YAML do corpo do SKILL.md. Retorna { meta, body }.
-export function parseSkill(raw) {
-  const match = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
-  if (!match) return { meta: {}, frontmatter: '', body: raw.trim() };
-  let meta = {};
-  try {
-    meta = yaml.load(match[1]) || {};
-  } catch {
-    meta = {};
-  }
-  return { meta, frontmatter: match[1], body: match[2].trim() };
-}
+// Separa o frontmatter YAML do corpo do SKILL.md. Implementação em
+// `lib/skill-file.mjs` (compartilhada com o loader das skills de IA);
+// re-exportada aqui porque `update.mjs` e os testes a importam deste módulo.
+export { parseSkill };
 
 // Banner de versão inserido no topo do corpo da skill instalada. O agente lê
 // esta linha e, se `npx @spec-wave/cli@latest --version` for maior, orienta reinstalar.
-function versionBanner(version) {
+export function versionBanner(version) {
   return (
     `> ⚙️ **spec-wave skill v${version}** — esta skill é uma cópia estática. ` +
     'Se `npx @spec-wave/cli@latest --version` indicar uma versão maior, ela está ' +
@@ -182,6 +186,20 @@ export function isDetected(target, baseDir) {
 // 'ausente' | 'bloco ausente' | 'desatualizada' — ou null se está em dia com a
 // versão empacotada na CLI. Compartilhado entre `update` e `info`.
 export function skillCopyReason(dest, parsed) {
+  // `skills-dir` não é um arquivo só: o destino é um diretório com uma pasta
+  // por skill. Diretório inteiro ausente conta como 'ausente'; qualquer arquivo
+  // faltando ou divergente conta como 'desatualizada' (é o mesmo remédio —
+  // reinstalar —, então não vale distinguir os dois casos).
+  if (dest.format === 'skills-dir') {
+    if (!existsSync(dest.path)) return 'ausente';
+    const files = planPluginSkillFiles(dest.path, CLI_VERSION, versionBanner);
+    if (!files.length) return null;
+    const stale = files.some(
+      (f) => !existsSync(f.path) || readFileSync(f.path, 'utf-8') !== f.content,
+    );
+    return stale ? 'desatualizada' : null;
+  }
+
   const desired = renderContent(dest.format, parsed, CLI_VERSION);
   const existing = existsSync(dest.path) ? readFileSync(dest.path, 'utf-8') : null;
   if (existing === null) return 'ausente';
@@ -312,7 +330,12 @@ export async function installSkill(options = {}) {
   if (options.dryRun) {
     p.note(
       jobs
-        .map((j) => `${chalk.dim(j.target.name.padEnd(20))} ${j.dest.path}  ${chalk.dim(`(${j.dest.format})`)}`)
+        .map((j) => {
+          const head = `${chalk.dim(j.target.name.padEnd(20))} ${j.dest.path}  ${chalk.dim(`(${j.dest.format})`)}`;
+          if (j.dest.format !== 'skills-dir') return head;
+          const names = listPluginSkills().map((s) => s.name);
+          return `${head}\n${chalk.dim(`  ${names.length} skills: ${names.join(', ')}`)}`;
+        })
         .join('\n'),
       `Dry-run — nada será gravado (escopo: ${scopeLabel})`,
     );
@@ -323,6 +346,34 @@ export async function installSkill(options = {}) {
   // 4) Gravar cada destino.
   const written = [];
   for (const { target, dest } of jobs) {
+    // `skills-dir` grava N arquivos (uma pasta por skill do plugin) em vez de
+    // um. Sobrescrever aqui é seguro sem confirmar por arquivo: o destino é um
+    // diretório inteiro do spec-wave, não um arquivo que o usuário mantém.
+    if (dest.format === 'skills-dir') {
+      const files = planPluginSkillFiles(dest.path, pkg.version, versionBanner);
+      if (!files.length) {
+        p.log.error(`${target.name}: nenhuma skill encontrada no plugin empacotado — pulado.`);
+        continue;
+      }
+      if (existsSync(dest.path) && !options.force && !options.yes) {
+        const ok = await p.confirm({
+          message: `${target.name}: ${dest.path} já existe. Sobrescrever as skills do spec-wave?`,
+          initialValue: true,
+        });
+        if (p.isCancel(ok) || !ok) {
+          p.log.info(`${target.name}: mantido (não sobrescrito).`);
+          continue;
+        }
+      }
+      for (const file of files) {
+        mkdirSync(path.dirname(file.path), { recursive: true });
+        writeFileSync(file.path, file.content, 'utf-8');
+      }
+      const count = new Set(files.map((f) => f.skill)).size;
+      written.push({ target, dest, count });
+      continue;
+    }
+
     const content =
       dest.format === 'agents'
         ? mergeAgentsFile(dest.path, renderContent('agents', parsed, pkg.version))
@@ -352,7 +403,12 @@ export async function installSkill(options = {}) {
   }
 
   p.note(
-    written.map((w) => `${chalk.green('✓')} ${chalk.bold(w.target.name)}\n  ${chalk.dim(w.dest.path)}`).join('\n'),
+    written
+      .map((w) => {
+        const suffix = w.count ? chalk.dim(`  (${w.count} skills)`) : '';
+        return `${chalk.green('✓')} ${chalk.bold(w.target.name)}${suffix}\n  ${chalk.dim(w.dest.path)}`;
+      })
+      .join('\n'),
     `Skill v${pkg.version} instalada (escopo: ${scopeLabel})`,
   );
   p.outro(

package/src/commands/issue.mjs

@@ -2,13 +2,11 @@ import * as p from '@clack/prompts';
 import chalk from 'chalk';
 import { readFileSync } from 'node:fs';
 import { resolveToken } from '../api/auth.mjs';
-import { CONFIG_FILE, STATUS_OPTIONS, PRIORITY_LABELS, WORK_ITEM_TYPES } from '../config.mjs';
+import { CONFIG_FILE, PRIORITY_LABELS, WORK_ITEM_TYPES, initialStageForType } from '../config.mjs';
 import { findConfigPath } from '../lib/project-root.mjs';
 import { createIssue, getIssue } from '../api/github-rest.mjs';
 import { addProjectItem, setItemSingleSelect, getSingleSelectField, addSubIssue } from '../api/github-graphql.mjs';
 
-// Etapa inicial de todo work item recém-criado (📥 Backlog).
-const INITIAL_STAGE = STATUS_OPTIONS[0].name;
 const VALID_PRIORITIES = PRIORITY_LABELS.map(l => l.name);
 
 // Resolve o tipo informado (case-insensitive) para o nome canônico (ex.: "Feature").
@@ -160,18 +158,22 @@ export async function issue(options) {
     return;
   }
 
+  // Etapa de nascimento: Backlog para quase todo tipo, 🐞 Triagem para Bug
+  // (✅ Ready quando o Bug já nasce P0). Ver initialStageForType.
+  const initialStage = initialStageForType(type, options.priority || null);
+
   const boardSpinner = p.spinner();
   boardSpinner.start('Adicionando ao Project...');
   try {
     const itemId = await addProjectItem(token, project.id, created.nodeId);
 
-    const stageOk = await setField(token, project, itemId, 'Etapa', INITIAL_STAGE);
+    const stageOk = await setField(token, project, itemId, 'Etapa', initialStage);
     const typeOk = await setField(token, project, itemId, 'Work Item Type', type);
     if (options.priority) await setField(token, project, itemId, 'Priority', options.priority);
     if (options.area) await setField(token, project, itemId, 'Area', options.area);
 
-    boardSpinner.stop(`Adicionada ao Project${stageOk ? ` em "${INITIAL_STAGE}"` : ''}.`);
-    if (!stageOk) p.log.warn(`Não foi possível definir a Etapa "${INITIAL_STAGE}" (campo não encontrado).`);
+    boardSpinner.stop(`Adicionada ao Project${stageOk ? ` em "${initialStage}"` : ''}.`);
+    if (!stageOk) p.log.warn(`Não foi possível definir a Etapa "${initialStage}" (campo não encontrado).`);
     if (!typeOk) p.log.warn(`Não foi possível definir o Work Item Type "${type}" (campo não encontrado).`);
   } catch (err) {
     boardSpinner.stop('');
@@ -185,7 +187,7 @@ export async function issue(options) {
     Epic: `Próximo: crie Features sob este Epic com \`spec-wave feature --parent ${created.number} --title "..."\`.`,
   };
   p.outro(
-    `${chalk.green('✓')} ${type} #${created.number} criado em "${INITIAL_STAGE}"${parentLine}.\n` +
+    `${chalk.green('✓')} ${type} #${created.number} criado em "${initialStage}"${parentLine}.\n` +
     `  ${hints[type] || ''}`
   );
 }

package/src/commands/move.mjs

@@ -20,7 +20,7 @@ import { loadProjectConfig, resolveField, advanceToStage, resolveStageName } fro
 import { loadConfig } from '../lib/project-root.mjs';
 import {
   CONFIG_FILE, PROGRESS_TODO, PROGRESS_IN_PROGRESS, PROGRESS_DONE,
-  isManualStageType, MANUAL_STAGE_TYPES,
+  isManualStageType, MANUAL_STAGE_TYPES, isStageInTrack, STAGE_TRACKS,
 } from '../config.mjs';
 
 const PROGRESS_VALUES = [PROGRESS_TODO, PROGRESS_IN_PROGRESS, PROGRESS_DONE];
@@ -116,6 +116,16 @@ export async function move({ issue: issueArg, stage: stageArg, status: statusArg
     return;
   }
 
+  // Aviso, não bloqueio: a trilha por tipo é convenção (RFC-004 §7.1); a regra
+  // dura continua sendo "a Etapa só avança". Um caso legítimo fora da trilha
+  // (um Bug que o time decidiu homologar) não deve exigir escape hatch.
+  if (type && !isStageInTrack(type, stage)) {
+    p.log.warn(
+      `${type} normalmente não passa por ${stage} — a trilha do tipo é: ` +
+      `${STAGE_TRACKS[type].join(' → ')}.`
+    );
+  }
+
   const { project, error: projectError } = loadProjectConfig({ cwd: root || process.cwd() });
   if (projectError) {
     p.log.error(`${projectError} — board não atualizado. Rode \`spec-wave init\` (ou \`spec-wave refresh --config\`).`);

package/src/commands/qa.mjs

@@ -78,6 +78,27 @@ export async function qa({ prNumber }) {
   const updated = [];
 
   for (const num of issueNums) {
+    // Bug é unidade própria: vai para 🧪 QA sozinho, sem arrastar a Feature-pai
+    // (que pode ter Stories ainda em desenvolvimento).
+    const issue = await getIssue(token, owner, repo, num).catch(() => null);
+    if (issue && detectIssueType(issue) === 'Bug') {
+      if (seen.has(issue.number)) continue;
+      seen.add(issue.number);
+      try {
+        const moved = await advanceToStage(
+          projectToken, project, etapaField, statusField, issue.node_id, QA_STAGE, TODO_STATUS);
+        if (moved) {
+          updated.push(`#${issue.number} ${issue.title} (bug)`);
+          console.log(`Bug #${issue.number} → "${QA_STAGE}" / Status "${TODO_STATUS}".`);
+        } else {
+          console.log(`Bug #${issue.number} já está em "${QA_STAGE}" ou etapa posterior — mantido.`);
+        }
+      } catch (err) {
+        console.warn(`Falha ao atualizar Bug #${issue.number}: ${err.message}`);
+      }
+      continue;
+    }
+
     const feature = await resolveFeatureIssue(token, owner, repo, num);
     if (!feature || seen.has(feature.number)) continue;
     seen.add(feature.number);
@@ -99,10 +120,10 @@ export async function qa({ prNumber }) {
     await commentOnIssue(
       token, owner, repo, parseInt(prNumber, 10),
       `🧪 **PR aprovado — QA iniciado**\n\n` +
-      `Feature(s) movida(s) para **${QA_STAGE}**:\n\n` +
+      `Item(ns) movido(s) para **${QA_STAGE}**:\n\n` +
       updated.map(f => `- ${f}`).join('\n')
     ).catch(() => {});
   }
 
-  console.log(`qa: ${updated.length} feature(s) atualizada(s).`);
+  console.log(`qa: ${updated.length} item(ns) atualizado(s).`);
 }

package/src/commands/refresh.mjs

@@ -4,20 +4,148 @@ 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.
+ *
+ * O motivo é o contrato da API: `updateProjectV2Field` SUBSTITUI o conjunto de
+ * opções do single-select, e a preservação do valor de cada item do board
+ * depende de a opção continuar existindo com o mesmo nome. Uma opção que some
+ * leva junto a Etapa de todo item que estava nela — silenciosamente. Remover
+ * coluna continua sendo trabalho manual, feito com os itens já esvaziados.
+ *
+ * @param {string[]} current nomes das opções hoje no board, na ordem atual
+ * @param {Array<{name: string, color: string}>} canonical STATUS_OPTIONS
+ * @returns {{ missing: string[], preserved: string[], ordered: Array<{name: string, color: string}> }}
+ */
+export function planStageSync(current, canonical) {
+  const have = new Set(current || []);
+  const canonicalNames = new Set(canonical.map(o => o.name));
+
+  const missing = canonical.filter(o => !have.has(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 = (current || []).filter(name => !canonicalNames.has(name));
+
+  const ordered = [
+    ...canonical.map(o => ({ name: o.name, color: o.color })),
+    ...preserved.map(name => ({ name, color: 'GRAY' })),
+  ];
+  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;
+  }
+
+  const current = Object.keys(etapa.options || {});
+  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): ${current.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 now = Object.keys(after?.fields?.['Etapa']?.options || {});
+  const lost = current.filter(name => !now.includes(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 (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 +185,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 +206,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 = {