@spec-wave/cli 0.14.0 → 0.16.0

package/src/api/github-rest.mjs

@@ -4,6 +4,15 @@ function makeOctokit(token) {
   return new Octokit({ auth: token });
 }
 
+// Para as consultas em que 404 é um RESULTADO ESPERADO ("a branch ainda não
+// existe", "não há o que comparar") e não um erro: o logger padrão do Octokit
+// imprime a linha `GET ... - 404` no stderr, que no meio de um spinner parece
+// falha. Mesmo padrão do doctor.mjs, onde 404/403 também são respostas válidas.
+const silentLog = { debug() {}, info() {}, warn() {}, error() {} };
+function makeQuietOctokit(token) {
+  return new Octokit({ auth: token, log: silentLog });
+}
+
 export async function getOwnerNodeId(token, owner) {
   const octokit = makeOctokit(token);
   try {
@@ -87,6 +96,189 @@ export async function upsertFile(token, owner, repo, path, content, message) {
   });
 }
 
+// ---------------------------------------------------------------------------
+// Git Data API — commit ATÔMICO + Pull Request
+//
+// O upsertFile acima faz UM COMMIT POR ARQUIVO direto na branch default: oito
+// arquivos = oito commits, e uma falha no quinto deixa o repositório num estado
+// intermediário que ninguém pediu. Aqui a árvore inteira é montada primeiro e só
+// então nascem o commit e a ref — antes da createRef/updateRef nada é
+// ALCANÇÁVEL (os objetos existem no banco, mas nenhuma ref aponta para eles),
+// então uma falha no meio não muda o repositório observável.
+//
+// Três pegadinhas da API, todas documentadas porque custam tempo de depuração:
+//  • createTree SEM `base_tree` produz uma árvore com SÓ os arquivos enviados —
+//    o commit resultante APAGA todo o resto do repositório, e a API responde 201.
+//  • getRef/getCommit/updateRef querem o ref SEM o prefixo `refs/`
+//    ('heads/main'); createRef quer COM ('refs/heads/x'). Trocar dá 404/422 sem
+//    explicação.
+//  • pulls.list exige `head` qualificado com o owner ('owner:branch'): sem o
+//    prefixo a API IGNORA o filtro e devolve todos os PRs abertos.
+// ---------------------------------------------------------------------------
+
+/**
+ * Lê a ponta de uma branch: sha do commit e sha da ÁRVORE desse commit.
+ *
+ * A árvore é o que interessa para o `base_tree` e para detectar "nada mudou":
+ * git é endereçado por conteúdo, então árvore igual = conteúdo igual, sem
+ * precisar pedir diff.
+ *
+ * @returns {Promise<{commitSha: string, treeSha: string}|null>} null quando a
+ *          branch não existe (404) — o chamador decide criar vs. atualizar a ref.
+ */
+export async function getBranchHead(token, owner, repo, branch) {
+  const octokit = makeQuietOctokit(token); // 404 = branch inexistente, não erro
+  let commitSha;
+  try {
+    const ref = await octokit.rest.git.getRef({ owner, repo, ref: `heads/${branch}` });
+    commitSha = ref.data.object.sha;
+  } catch (err) {
+    if (err.status === 404) return null;
+    throw err;
+  }
+  const commit = await octokit.rest.git.getCommit({ owner, repo, commit_sha: commitSha });
+  return { commitSha, treeSha: commit.data.tree.sha };
+}
+
+/**
+ * Compara `base...branch`.
+ *
+ * 'behind'/'identical' significa que a branch não tem nenhum commit que a base
+ * já não tenha — sinal típico de branch de um PR já mergeado com squash. Serve
+ * só para AVISAR antes de empilhar um commit numa branch obsoleta; nunca para
+ * decidir um force-push.
+ *
+ * @returns {Promise<'identical'|'ahead'|'behind'|'diverged'|null>} null se a
+ *          branch não existe ou a comparação falha (é só um aviso — não pode
+ *          derrubar o fluxo).
+ */
+export async function compareBranches(token, owner, repo, base, branch) {
+  const octokit = makeQuietOctokit(token); // 404 = branch inexistente, não erro
+  try {
+    const res = await octokit.rest.repos.compareCommitsWithBasehead({
+      owner, repo, basehead: `${base}...${branch}`,
+    });
+    return res.data.status;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Grava N arquivos em UM único commit numa branch (criando-a a partir de `base`
+ * quando ainda não existe).
+ *
+ * Idempotente de propósito: rodar `update --branch fix/x` duas vezes não gera um
+ * segundo commit. Quando a branch já existe o pai é a PONTA DELA — não a base —
+ * então a atualização da ref é sempre fast-forward e `force` fica em false (uma
+ * corrida com outro push falha em vez de sobrescrever trabalho alheio).
+ *
+ * Se a árvore montada tiver o MESMO sha da árvore do pai, nada mudou de fato e o
+ * commit é pulado: commit vazio num PR só confunde quem revisa.
+ *
+ * @param {object} opts
+ * @param {string} opts.branch branch de trabalho (head do PR)
+ * @param {string} opts.base branch de partida quando `branch` ainda não existe
+ * @param {Array<{path: string, content: string}>} opts.files conteúdo FINAL de cada arquivo
+ * @param {string} opts.message mensagem do commit único
+ * @returns {Promise<{branch, base, commitSha, createdBranch, unchanged, baseSha}>}
+ */
+export async function commitFilesToBranch(token, owner, repo, { branch, base, files, message }) {
+  const octokit = makeOctokit(token);
+  if (!files?.length) throw new Error('commitFilesToBranch: nenhum arquivo a enviar.');
+
+  const baseHead = await getBranchHead(token, owner, repo, base);
+  if (!baseHead) throw new Error(`Branch base "${base}" não encontrada em ${owner}/${repo}.`);
+
+  const head = await getBranchHead(token, owner, repo, branch);
+  const parent = head ?? baseHead;
+
+  // `content` inline: a própria API cria o blob, poupando um createBlob por
+  // arquivo. Vale só para texto UTF-8 — todos os nossos templates são.
+  // mode: 100644 = arquivo comum (100755 executável, 040000 subárvore).
+  const tree = await octokit.rest.git.createTree({
+    owner,
+    repo,
+    base_tree: parent.treeSha, // SEM isto o commit apagaria o repositório inteiro
+    tree: files.map(f => ({ path: f.path, mode: '100644', type: 'blob', content: f.content })),
+  });
+
+  if (tree.data.sha === parent.treeSha) {
+    return {
+      branch, base, commitSha: parent.commitSha,
+      createdBranch: false, unchanged: true, baseSha: baseHead.commitSha,
+    };
+  }
+
+  const commit = await octokit.rest.git.createCommit({
+    owner, repo, message, tree: tree.data.sha, parents: [parent.commitSha],
+  });
+
+  if (head) {
+    await octokit.rest.git.updateRef({
+      owner, repo, ref: `heads/${branch}`, sha: commit.data.sha, force: false,
+    });
+  } else {
+    await octokit.rest.git.createRef({
+      owner, repo, ref: `refs/heads/${branch}`, sha: commit.data.sha,
+    });
+  }
+
+  return {
+    branch, base, commitSha: commit.data.sha,
+    createdBranch: !head, unchanged: false, baseSha: baseHead.commitSha,
+  };
+}
+
+/**
+ * PR ABERTO cuja head é `branch` neste mesmo repositório.
+ *
+ * @returns {Promise<{number, url, title, base}|null>}
+ */
+export async function findOpenPR(token, owner, repo, branch) {
+  const octokit = makeOctokit(token);
+  const res = await octokit.rest.pulls.list({
+    owner, repo, state: 'open', head: `${owner}:${branch}`, per_page: 1,
+  });
+  const pr = res.data[0];
+  return pr
+    ? { number: pr.number, url: pr.html_url, title: pr.title, base: pr.base.ref }
+    : null;
+}
+
+/**
+ * Abre o PR da branch — ou devolve o que já está aberto para ela.
+ *
+ * Rodar o update duas vezes não pode virar dois PRs. O findOpenPR cobre o caso
+ * normal; o catch do 422 cobre a corrida e o "No commits between base and head"
+ * (branch sem nada novo em relação à base → não existe PR a abrir → null).
+ * Qualquer outro 422 propaga com a mensagem real da API, senão uma base inválida
+ * viraria um silencioso "nada a revisar".
+ *
+ * @returns {Promise<{number, url, created}|null>}
+ */
+export async function ensurePullRequest(
+  token, owner, repo, { branch, base, title, body, draft = false }
+) {
+  const octokit = makeOctokit(token);
+  const existing = await findOpenPR(token, owner, repo, branch);
+  if (existing) return { ...existing, created: false };
+  try {
+    const res = await octokit.rest.pulls.create({
+      owner, repo, title, body, head: branch, base, draft,
+    });
+    return { number: res.data.number, url: res.data.html_url, created: true };
+  } catch (err) {
+    if (err.status !== 422) throw err;
+    const again = await findOpenPR(token, owner, repo, branch);
+    if (again) return { ...again, created: false };
+    const detail = err.response?.data?.errors?.map(e => e.message).filter(Boolean).join('; ')
+      || err.message;
+    if (/No commits between/i.test(detail)) return null;
+    throw new Error(detail);
+  }
+}
+
 // `id` é o database id da issue — exigido pela API de dependências
 // (blocked_by), que não aceita number nem node id.
 export async function createIssue(token, owner, repo, title, body, labels) {
@@ -182,6 +374,14 @@ export async function updateComment(token, owner, repo, commentId, body) {
   });
 }
 
+// Fecha (ou reabre) uma issue. Usado pela triagem de Bug: rejeitar e marcar
+// como duplicata tiram o item das filas SEM mexer na Etapa — ela nunca
+// retrocede, e um bug rejeitado não avançou para lugar nenhum.
+export async function setIssueState(token, owner, repo, issueNumber, state) {
+  const octokit = makeOctokit(token);
+  await octokit.rest.issues.update({ owner, repo, issue_number: issueNumber, state });
+}
+
 // Marca uma issue como bloqueada por outra (relação nativa do GitHub).
 // `blockingIssueId` é o DATABASE id da issue bloqueadora (não o number nem o
 // node id — ver createIssue). Erros propagam: o chamador usa como fallback.
@@ -235,10 +435,14 @@ export async function getPR(token, owner, repo, prNumber) {
   return res.data;
 }
 
-export async function getFileContent(token, owner, repo, path) {
+// `ref` é opcional (compatível com os chamadores de 4 argumentos): o modo PR do
+// `update` precisa ler o .spec-wave.json na BASE, não no que a API escolher.
+export async function getFileContent(token, owner, repo, path, ref) {
   const octokit = makeOctokit(token);
   try {
-    const res = await octokit.rest.repos.getContent({ owner, repo, path });
+    const res = await octokit.rest.repos.getContent({
+      owner, repo, path, ...(ref ? { ref } : {}),
+    });
     return Buffer.from(res.data.content, 'base64').toString('utf-8');
   } catch (err) {
     if (err.status === 404) return null;

package/src/commands/bug.mjs

@@ -0,0 +1,8 @@
+import { issue } from './issue.mjs';
+
+// `bug` é um atalho de `issue --type bug`, no mesmo padrão de `feature` e
+// `initiative`. A etapa de nascimento (🐞 Triagem, ou ✅ Ready quando P0) é
+// decidida por initialStageForType — ver config.mjs.
+export async function bug(options) {
+  return issue({ ...options, type: 'bug' });
+}

package/src/commands/code-review.mjs

@@ -52,16 +52,40 @@ async function resolveFeatureIssue(token, owner, repo, issueNumber) {
 // tipo porque cada um tem destino próprio: Tasks → Done, Stories → Code Review,
 // Feature → Code Review (só quando todas as Stories estiverem prontas). Retorna
 // { feature:{number,nodeId,title}|null, stories:Map, tasks:Map }.
+/**
+ * Como o PR trata uma issue referenciada, pelo tipo (função PURA).
+ *
+ *  'bug'    → unidade de review PRÓPRIA: move o Bug e NÃO toca na Feature-pai.
+ *             Um defeito em review não deve arrastar a Feature inteira para
+ *             Code Review — ela pode ter Stories ainda em desenvolvimento.
+ *  'unit'   → Feature/Story/Task: sobe pela cadeia até a Feature (fluxo atual).
+ *  'ignore' → Spike, RFC, Epic e desconhecidos.
+ *
+ * @param {string|null} type
+ * @returns {'bug'|'unit'|'ignore'}
+ */
+export function classifyReviewTarget(type) {
+  if (type === 'Bug') return 'bug';
+  if (type === 'Feature' || type === 'Story' || type === 'Task') return 'unit';
+  return 'ignore';
+}
+
 async function collectReviewUnit(token, owner, repo, issueNumber) {
   const stories = new Map();
   const tasks = new Map();
+  const bugs = new Map();
   const addStory = (n, nodeId, title) => { if (n && nodeId && !stories.has(n)) stories.set(n, { nodeId, title }); };
   const addTask = (n, nodeId, title) => { if (n && nodeId && !tasks.has(n)) tasks.set(n, { nodeId, title }); };
 
   let issue;
-  try { issue = await getIssue(token, owner, repo, issueNumber); } catch { return { feature: null, stories, tasks }; }
+  try { issue = await getIssue(token, owner, repo, issueNumber); } catch { return { feature: null, stories, tasks, bugs }; }
   const type = detectIssueType(issue);
-  if (type !== 'Feature' && type !== 'Story' && type !== 'Task') return { feature: null, stories, tasks };
+  const kind = classifyReviewTarget(type);
+  if (kind === 'ignore') return { feature: null, stories, tasks, bugs };
+  if (kind === 'bug') {
+    bugs.set(issue.number, { nodeId: issue.node_id, title: issue.title });
+    return { feature: null, stories, tasks, bugs };
+  }
 
   const featureIssue = await resolveFeatureIssue(token, owner, repo, issueNumber);
   const feature = featureIssue
@@ -93,7 +117,7 @@ async function collectReviewUnit(token, owner, repo, issueNumber) {
       for (const t of tks) { if (isManual(t)) continue; addTask(t.number, t.nodeId, t.title); }
     }
   }
-  return { feature, stories, tasks };
+  return { feature, stories, tasks, bugs };
 }
 
 // A Feature só avança quando TODAS as suas Stories já estiverem em Code Review
@@ -155,7 +179,7 @@ export async function codeReview({ prNumber }) {
   // Stories → 👀 Code Review; Feature → Code Review só quando TODAS as suas
   // Stories já estiverem em Code Review.
   for (const num of issueNums) {
-    const { feature, stories, tasks } = await collectReviewUnit(token, owner, repo, num);
+    const { feature, stories, tasks, bugs } = await collectReviewUnit(token, owner, repo, num);
 
     // Tasks → Done (Status Done).
     for (const [n, info] of tasks) {
@@ -191,6 +215,23 @@ export async function codeReview({ prNumber }) {
       }
     }
 
+    // Bugs → Code Review, sem Feature-pai envolvida.
+    for (const [n, info] of bugs) {
+      if (seen.has(n)) continue;
+      seen.add(n);
+      try {
+        const moved = await advanceToStage(projectToken, project, etapaField, statusField, info.nodeId, CODE_REVIEW_STAGE, TODO_STATUS);
+        if (moved) {
+          updated.push(`#${n} ${info.title} → ${CODE_REVIEW_STAGE}`);
+          console.log(`Bug #${n} → "${CODE_REVIEW_STAGE}" / Status "${TODO_STATUS}".`);
+        } else {
+          console.log(`Bug #${n} já está em "${CODE_REVIEW_STAGE}" ou etapa posterior — mantido (não retrocede).`);
+        }
+      } catch (err) {
+        console.warn(`Falha ao atualizar #${n}: ${err.message}`);
+      }
+    }
+
     // Feature: só avança se todas as suas Stories já estão em Code Review+.
     if (feature && !featuresChecked.has(feature.number)) {
       featuresChecked.add(feature.number);

package/src/commands/decompose.mjs

@@ -33,6 +33,7 @@ import { lintLanguage } from '../lib/output-lint.mjs';
 import { slugify } from '../lib/slugify.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
 import { loadConfig } from '../lib/project-root.mjs';
+import { loadPrompt, toolFreeSystemPrompt } from '../lib/prompt-loader.mjs';
 import {
   renderDecompositionDoc, parseDecompositionDoc, DECOMPOSITION_FILE,
 } from '../lib/decomposition-doc.mjs';
@@ -207,60 +208,17 @@ function commitFile(filePath, content, message) {
   git('git push');
 }
 
-const FEATURE_SYSTEM_PROMPT = `Você é um Tech Lead experiente em decomposição de trabalho ágil.
-A partir da Feature fornecida (com spec.md e plan.md), gere uma lista de Stories e Tasks.
-
-Responda APENAS com JSON válido neste formato:
-{
-  "stories": [
-    {
-      "title": "Título curto da story (apenas a parte 'quero', sem prefixo)",
-      "userStory": "Como <perfil>, quero <objetivo>, para <benefício>",
-      "body": "Descrição complementar da story com contexto e critérios de aceite relevantes",
-      "dependsOn": [0],
-      "tasks": [
-        {
-          "title": "Título técnico curto da task (sem prefixo)",
-          "body": "Descrição técnica detalhada"
-        }
-      ]
-    }
-  ]
-}
-
-Regras:
-- "title" deve ser CURTO (máx. ~60 caracteres): apenas a parte "quero" da user story, sem o "Como" nem o "para", e sem prefixo. Ex.: "visualizar meus repositórios em layout responsivo"
-- "userStory" deve trazer a user story completa no formato "Como <perfil>, quero <objetivo>, para <benefício>"
-- "body" é texto complementar (contexto, critérios de aceite); não repita o título
-- Cada Story deve ter 2–5 Tasks associadas
-- Tasks devem ser atividades técnicas concretas, com "title" curto e "body" detalhado
-- Gere entre 3 e 7 Stories por Feature
-- Ordene as stories na sequência de implementação — a ORDEM da lista importa
-- "dependsOn" (opcional): índices 0-based das stories ANTERIORES na lista das quais esta story depende. Referencie apenas índices menores que o da própria story. Use [] quando a story puder ser feita em paralelo (sem dependências); se omitido, assume-se dependência da story anterior (sequencial)`;
-
-const RFC_SYSTEM_PROMPT = `Você é um Tech Lead experiente. A partir do RFC fornecido (proposta técnica/de processo), gere a lista de Tasks técnicas concretas necessárias para implementá-lo.
-
-Responda APENAS com JSON válido neste formato:
-{
-  "tasks": [
-    {
-      "title": "Título técnico curto da task (sem prefixo)",
-      "body": "Descrição técnica detalhada (o que fazer, áreas/arquivos afetados, critério de pronto)"
-    }
-  ]
-}
-
-Regras:
-- "title" CURTO (máx. ~60 caracteres), sem prefixo.
-- "body" detalhado e acionável.
-- Gere entre 3 e 10 Tasks concretas que, juntas, cubram o RFC.`;
+// Os prompts vivem em `src/plugin/skills/decompose/model-prompt.{feature,rfc}.md`
+// (sobrescrevíveis em `.spec-wave/prompts/decompose.feature.md`). O contrato JSON é o
+// `json.shape` do frontmatter — quem parseia a saída e quem instrui o modelo
+// passam a ler a MESMA declaração, em vez de duas cópias que podiam divergir.
 
 // ---------------------------------------------------------------------------
 // Etapa 1: rascunho (label spec-wave:decompose)
 // ---------------------------------------------------------------------------
 
 async function draftDecomposition(ctx) {
-  const { token, owner, repo, issue, issueNumber, type, labels, usage, docDir, docPath, docRel } = ctx;
+  const { token, owner, repo, issue, issueNumber, type, labels, usage, root, docDir, docPath, docRel } = ctx;
   const number = parseInt(issueNumber, 10);
   const kind = DECOMPOSE_TARGETS[type]; // Feature → 'stories'; RFC → 'tasks'
   const blobUrl = `https://github.com/${owner}/${repo}/blob/main/${docRel}`;
@@ -292,8 +250,12 @@ async function draftDecomposition(ctx) {
           `\n## plan.md\n${planContent || '(plan.md não encontrado)'}`,
         ].join('\n');
 
+    const decomposePrompt = loadPrompt(
+      type === 'RFC' ? 'decompose/rfc' : 'decompose/feature',
+      { cwd: root },
+    );
     const generated = parseModelJson(await generateDocument(
-      type === 'RFC' ? RFC_SYSTEM_PROMPT : FEATURE_SYSTEM_PROMPT,
+      toolFreeSystemPrompt(decomposePrompt),
       userContent,
       { action: 'decompose', labels, usage }
     ));

package/src/commands/dev-agent.mjs

@@ -19,7 +19,7 @@ import {
 import { homedir, tmpdir } from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { CONFIG_FILE } from '../config.mjs';
+import { CONFIG_FILE, LABEL_DEV_AGENT } from '../config.mjs';
 import { findConfigPath } from '../lib/project-root.mjs';
 
 const __dir = path.dirname(fileURLToPath(import.meta.url));
@@ -82,7 +82,7 @@ export function renderAgentConfig({ owner, repo }) {
 # Schema completo: https://github.com/${AGENT_REPO}#configuração
 
 repo = "${owner}/${repo}"
-queue_label = "spec-wave:dev-agent"
+queue_label = "${LABEL_DEV_AGENT}"
 
 # Defaults do agente (descomente para ajustar):
 #poll_interval_secs = 60       # consulta à fila quando ocioso
@@ -412,7 +412,7 @@ async function finishSetup({ cfg, home, binPath, configPath, options, configActi
   p.outro(
     `${chalk.green('✓')} Agente pronto.\n` +
     `  Rodar agora:  ${chalk.cyan('spec-wave dev-agent --run')}\n` +
-    '  Enfileirar:   aplique a label spec-wave:dev-agent numa issue [FEATURE] já decomposta.'
+    `  Enfileirar:   aplique a label ${LABEL_DEV_AGENT} numa issue [FEATURE] já decomposta.`
   );
 }
 

package/src/commands/doctor.mjs

@@ -12,7 +12,8 @@ import { resolveToken, verifyTokenScopes } from '../api/auth.mjs';
 import { getProjectSnapshot } from '../api/github-graphql.mjs';
 import {
   CONFIG_FILE, WORKFLOW_FILES, getProvider, DEFAULT_PROVIDER, STATUS_OPTIONS,
-  ALL_LABELS, LABEL_NEEDS_HUMAN, MODEL_LABEL_PREFIX, DEFAULT_MAX_CRITIQUE_ATTEMPTS,
+  RETIRED_STAGES, ALL_LABELS, LABEL_NEEDS_HUMAN, MODEL_LABEL_PREFIX,
+  DEFAULT_MAX_CRITIQUE_ATTEMPTS, STAGE_TRACKS,
 } from '../config.mjs';
 import { findConfigPath } from '../lib/project-root.mjs';
 import {
@@ -284,7 +285,12 @@ async function checkConfig(ctx) {
 export function inspectBoardHygiene({ boardStages = null, repoLabels = null } = {}) {
   const canonical = STATUS_OPTIONS.map(s => s.name);
   const known = new Set(canonical);
-  const unknownStages = boardStages ? boardStages.filter(s => !known.has(s)) : [];
+  const retired = new Map(RETIRED_STAGES.map(s => [s.name, s]));
+  const foreign = boardStages ? boardStages.filter(s => !known.has(s)) : [];
+  // Uma etapa aposentada também é "fora do fluxo", mas a orientação ao usuário
+  // é diferente da de uma coluna inventada — por isso saem em listas separadas.
+  const retiredStages = foreign.filter(s => retired.has(s)).map(s => retired.get(s));
+  const unknownStages = foreign.filter(s => !retired.has(s));
   const missingStages = boardStages ? canonical.filter(s => !boardStages.includes(s)) : [];
 
   const knownLabels = new Set(ALL_LABELS.map(l => l.name));
@@ -294,7 +300,29 @@ export function inspectBoardHygiene({ boardStages = null, repoLabels = null } =
   const missingLabels = repoLabels
     ? ALL_LABELS.map(l => l.name).filter(n => !repoLabels.includes(n))
     : [];
-  return { unknownStages, missingStages, orphanLabels, missingLabels };
+  return { unknownStages, retiredStages, missingStages, orphanLabels, missingLabels };
+}
+
+/**
+ * O board comporta a trilha do Bug? (função PURA)
+ *
+ * Um Bug percorre 🐞 Triagem → ✅ Ready → … → 🚀 Deploy → 🎉 Done (RFC-004 §4).
+ * Se o board não tem alguma dessas colunas, o item não tem onde parar: o campo
+ * "Etapa" só aceita as opções que existem, então a escrita falha em silêncio e
+ * o bug fica sem etapa — invisível em toda tela que filtra por etapa.
+ *
+ * Só reporta quando há Bug aberto: um board sem bugs não precisa da trilha.
+ *
+ * @param {object} params
+ * @param {string[]|null} [params.boardStages] opções do campo Etapa
+ * @param {number} [params.openBugCount] bugs abertos no repositório
+ * @returns {{ missingTrackStages: string[] }}
+ */
+export function inspectBugTrack({ boardStages = null, openBugCount = 0 } = {}) {
+  if (!boardStages || openBugCount <= 0) return { missingTrackStages: [] };
+  return {
+    missingTrackStages: STAGE_TRACKS.Bug.filter(s => !boardStages.includes(s)),
+  };
 }
 
 async function checkBoardHygiene(ctx) {
@@ -315,6 +343,7 @@ async function checkBoardHygiene(ctx) {
   }
 
   let repoLabels = null;
+  let openBugCount = 0;
   if (ctx.token && cfg.owner && cfg.repo) {
     try {
       const res = await makeOctokit(ctx.token)
@@ -323,9 +352,17 @@ async function checkBoardHygiene(ctx) {
     } catch {
       // labels não verificáveis agora — segue só com o board
     }
+    try {
+      const bugs = await makeOctokit(ctx.token).paginate('GET /repos/{owner}/{repo}/issues', {
+        owner: cfg.owner, repo: cfg.repo, labels: '[BUG]', state: 'open', per_page: 100,
+      });
+      openBugCount = bugs.filter(i => !i.pull_request).length;
+    } catch {
+      // sem acesso às issues — o check da trilha do Bug fica de fora
+    }
   }
 
-  const { unknownStages, missingStages, orphanLabels, missingLabels } =
+  const { unknownStages, retiredStages, missingStages, orphanLabels, missingLabels } =
     inspectBoardHygiene({ boardStages, repoLabels });
 
   const notes = [];
@@ -343,10 +380,32 @@ async function checkBoardHygiene(ctx) {
       'Mova os itens para uma etapa do fluxo e remova a coluna.'
     );
   }
+  for (const stage of retiredStages) {
+    status = 'warn';
+    notes.push(
+      `Etapa descontinuada ainda no board: ${stage.name} (removida do fluxo na v${stage.removedIn}). ` +
+      `Mova os itens dela para ${stage.replacedBy} e apague a coluna nas configurações do campo ` +
+      '"Etapa"; depois rode `refresh --config` para tirar o id do .spec-wave.json.'
+    );
+  }
   if (missingStages.length > 0) {
     status = 'warn';
-    notes.push(`Etapas do RFC-001 ausentes no board: ${missingStages.join(', ')} — rode \`refresh\`.`);
+    notes.push(
+      `Etapas do RFC-001 ausentes no board: ${missingStages.join(', ')} — rode ` +
+      '`refresh --stages --dry-run` para ver o plano, ou crie a coluna à mão nas configurações ' +
+      'do campo "Etapa" e rode `refresh --config`.'
+    );
+  }
+  const { missingTrackStages } = inspectBugTrack({ boardStages, openBugCount });
+  if (missingTrackStages.length > 0) {
+    status = 'warn';
+    notes.push(
+      `${openBugCount} Bug(s) aberto(s), mas o board não tem: ${missingTrackStages.join(', ')}. ` +
+      'Um Bug movido para uma etapa inexistente fica SEM Etapa e some das telas — ' +
+      'rode `refresh --stages`.'
+    );
   }
+
   if (repoLabels) {
     if (orphanLabels.length > 0) {
       status = 'warn';
@@ -504,10 +563,22 @@ async function checkAi(ctx) {
     );
   } else {
     notes.push(
-      `Saída estruturada da crítica: ${provider.value === 'anthropic' ? 'tool call forçado' : 'response_format json_schema'} ` +
+      `Saída estruturada da crítica: tool call forçado (${provider.value}) ` +
       `· strict=${supportsStrictSchema(critiqueModel) ? 'sim' : 'não'} neste modelo.`
     );
   }
+  // O backend anthropic não chama a API — sobe o Claude Code CLI como
+  // subprocesso, que não existe no runner dos workflows (só há setup-node).
+  if (provider.value === 'anthropic') {
+    problems.push(
+      'O provider `anthropic` NÃO roda nos GitHub Actions: ele sobe o Claude Code CLI como ' +
+      'subprocesso, ausente no runner. As Actions de spec/plan/decompose vão falhar. ' +
+      'Troque para `"provider": "openrouter"` no .spec-wave.json (e adicione o secret ' +
+      'OPENROUTER_API_KEY), ou instale o Claude Code no workflow e defina ' +
+      'SPEC_WAVE_ALLOW_ANTHROPIC_IN_CI=1. Localmente o anthropic funciona.'
+    );
+  }
+
   if (process.env[provider.secret]) {
     notes.push(`${provider.secret} presente no ambiente local.`);
   } else {