@spec-wave/cli 0.20.0 → 0.23.0

package/src/commands/order.mjs

@@ -1,24 +1,176 @@
-// Ordena as Stories de uma Feature pelas dependências (topológica, Kahn —
+// Ordena as Stories pelas dependências (topológica, Kahn —
 // ver orderStories em src/lib/dependencies.mjs). As dependências vêm de duas
 // fontes, mescladas: a linha "Depende de: #N" no corpo da Story e a relação
 // nativa blocked_by do GitHub.
 //
+// Dependência para FORA da Feature não entra na ordenação (não há como saber
+// onde a Story de outra Feature entra nesta sequência), mas é EXIBIDA: era lida,
+// descartada em silêncio por orderStories e ignorada de novo no aviso de
+// fora-de-ordem. Quem montava o mapa de trabalho de dois devs tinha que
+// reconstruir isso à mão, lendo os decomposition.md.
+//
+// Dois escopos: `order <feature>` (uma Feature) e `order` sem argumento — o
+// mapa de TODAS as Features com trabalho no board, onde as dependências entre
+// Features deixam de ser "externas" e entram no mesmo grafo.
+//
 // Comando LOCAL — rodado pelo dev no terminal. owner/repo vêm da env
 // GITHUB_REPOSITORY quando existir, senão do .spec-wave.json (gravado pelo init).
 import * as p from '@clack/prompts';
 import chalk from 'chalk';
 import { resolveToken } from '../api/auth.mjs';
 import { getIssue, listBlockedBy } from '../api/github-rest.mjs';
-import { addProjectItem, listSubIssues, getItemSingleSelectValue } from '../api/github-graphql.mjs';
+import {
+  addProjectItem, listSubIssues, getItemSingleSelectValue, listProjectItems,
+} from '../api/github-graphql.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
 import { parseDependencies, orderStories } from '../lib/dependencies.mjs';
-import { loadProjectConfig, resolveField } from '../lib/board.mjs';
+import {
+  loadProjectConfig, resolveField, indexBoardItems, selectOpenFeatures,
+} from '../lib/board.mjs';
 import { resolveRepoContext } from '../lib/project-root.mjs';
 import { CONFIG_FILE, STAGE_ORDER, STAGE_DEVELOPMENT, STAGE_DONE } from '../config.mjs';
 
-export async function order({ feature: featureArg }) {
+/**
+ * Rótulo curto de uma Feature para a coluna do mapa (função PURA).
+ */
+export function featureLabel(feature) {
+  const titulo = String(feature?.title || '').replace(/^\s*\[FEATURE\]\s*/i, '').trim();
+  const curto = titulo.length > 28 ? `${titulo.slice(0, 27)}…` : titulo;
+  return `#${feature?.number} ${curto}`.trim();
+}
+
+/**
+ * O mapa de execução de várias Features (função PURA).
+ *
+ * Uma ordem SÓ, não uma lista por Feature: é isso que responde "o que os dois
+ * devs pegam agora" — a pergunta que obrigava a abrir nove decomposition.md e
+ * reconstruir o grafo à mão. A coluna da Feature vem junto porque, num grafo de
+ * várias, saber a que Feature cada Story pertence é metade da informação.
+ *
+ * @param {object} params
+ * @param {number[]} params.sorted ordem topológica (números de Story)
+ * @param {Map<number, {title:string, dependsOn:number[]}>} params.byNumber
+ * @param {Map<number, object>} params.featureOf Story → Feature dona
+ * @param {Map<number, string|null>} params.stageOf Story → Etapa
+ * @returns {string}
+ */
+export function renderBoardOrder({ sorted, byNumber, featureOf, stageOf }) {
+  return (sorted || []).map((n, i) => {
+    const s = byNumber.get(n);
+    const etapa = stageOf.get(n) || '—';
+    const deps = (s?.dependsOn || []).filter(d => byNumber.has(d));
+    const dep = deps.length > 0 ? `  ← depende de ${deps.map(d => `#${d}`).join(', ')}` : '';
+    return `${String(i + 1).padStart(2)}. #${n} ${s?.title || ''}\n` +
+      `    ${featureLabel(featureOf.get(n))} · Etapa: ${etapa}${dep}`;
+  }).join('\n');
+}
+
+/**
+ * `spec-wave order` sem argumento: o grafo de TODAS as Features com trabalho.
+ *
+ * Fonte do conjunto é o BOARD, não os arquivos — `decomposition.md` registra o
+ * que foi proposto, a issue é o que existe. Uma query paginada de itens do
+ * project resolve Etapa e tipo de todo mundo de uma vez, no lugar do laço de
+ * duas chamadas por Story que o modo de uma Feature ainda usa.
+ */
+async function orderBoard({ token, owner, repo }) {
+  const { project, error: projectError } = loadProjectConfig();
+  if (projectError) {
+    p.log.error(
+      `${projectError} — sem board não há como saber quais Features têm trabalho. ` +
+      'Use `spec-wave order <feature>` para ordenar uma Feature específica.'
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  let itens;
+  try {
+    itens = await listProjectItems(token, project.id);
+  } catch (err) {
+    p.log.error(`Não foi possível ler os itens do Project: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+  const indice = indexBoardItems(itens);
+  const features = selectOpenFeatures(itens);
+  if (features.length === 0) {
+    p.log.info(`Nenhuma Feature aberta fora de "${STAGE_DONE}" no board — nada a ordenar.`);
+    p.outro('Nada a fazer.');
+    return;
+  }
+
+  const enriched = [];
+  const featureOf = new Map();
+  const stageOf = new Map();
+  const semStories = [];
+  for (const feature of features) {
+    const subs = await listSubIssues(token, feature.nodeId).catch(() => []);
+    const stories = subs.filter(sub =>
+      detectIssueType({ title: sub.title, labels: sub.labels }) === 'Story');
+    if (stories.length === 0) { semStories.push(feature); continue; }
+    for (const story of stories) {
+      // Story concluída não entra: o mapa é do que falta fazer.
+      if (indice.get(story.number)?.fields?.Etapa === STAGE_DONE) continue;
+      const fromBody = parseDependencies(story.body);
+      const fromBlockedBy = (await listBlockedBy(token, owner, repo, story.number).catch(() => []))
+        .map(b => b.number);
+      enriched.push({
+        number: story.number,
+        title: story.title,
+        dependsOn: [...new Set([...fromBody, ...fromBlockedBy])],
+      });
+      featureOf.set(story.number, feature);
+      stageOf.set(story.number, indice.get(story.number)?.fields?.Etapa || null);
+    }
+  }
+
+  if (enriched.length === 0) {
+    p.log.info(`${features.length} Feature(s) aberta(s), nenhuma com Story pendente.`);
+    p.outro('Nada a fazer.');
+    return;
+  }
+
+  const byNumber = new Map(enriched.map(s => [s.number, s]));
+  const { order: sorted, cycle, external } = orderStories(
+    enriched.map(({ number, dependsOn }) => ({ number, dependsOn })));
+
+  if (cycle.length > 0) {
+    p.log.warn(
+      chalk.yellow.bold('⚠ CICLO DE DEPENDÊNCIAS detectado!') + '\n' +
+      `Stories envolvidas (ou bloqueadas pelo ciclo): ${cycle.map(n => `#${n}`).join(', ')}.\n` +
+      'Elas ficaram fora da ordem abaixo. Num grafo de várias Features o ciclo pode ' +
+      'ATRAVESSAR a fronteira delas — confira as linhas "Depende de" dos dois lados.'
+    );
+  }
+
+  p.note(
+    renderBoardOrder({ sorted, byNumber, featureOf, stageOf }),
+    `Ordem de execução — ${sorted.length} Story(ies) de ${features.length} Feature(s)`
+  );
+
+  // Aqui "fora do conjunto" não é mais "de outra Feature" (essas agora estão
+  // DENTRO): é Story já concluída, Feature em Done ou issue de outro board.
+  if (external.size > 0) {
+    const linhas = [...external.entries()].map(([n, deps]) =>
+      `  #${n} ← ${deps.map(d => `#${d}`).join(', ')}`);
+    p.note(
+      linhas.join('\n'),
+      'Dependências fora do conjunto (concluídas, de Feature em Done ou de outro board)'
+    );
+  }
+
+  if (semStories.length > 0) {
+    p.log.info(`Sem Stories (ainda não decompostas): ${semStories.map(f => `#${f.number}`).join(', ')}.`);
+  }
+  p.outro(`${chalk.green('✓')} ${sorted.length} de ${enriched.length} story(ies) ordenada(s).`);
+}
+
+export async function order({ feature: featureArg } = {}) {
+  const semArgumento = featureArg === undefined || featureArg === null
+    || String(featureArg).trim() === '';
   const featureNumber = parseInt(String(featureArg).replace('#', ''), 10);
-  if (!Number.isInteger(featureNumber) || featureNumber <= 0) {
+  if (!semArgumento && (!Number.isInteger(featureNumber) || featureNumber <= 0)) {
     p.log.error(`Feature inválida: "${featureArg}". Use o número da issue, ex.: 12 ou #12.`);
     process.exitCode = 1;
     return;
@@ -43,6 +195,11 @@ export async function order({ feature: featureArg }) {
     return;
   }
 
+  if (semArgumento) {
+    p.intro(chalk.bold('spec-wave order — todas as Features com trabalho'));
+    return await orderBoard({ token, owner, repo });
+  }
+
   p.intro(chalk.bold(`spec-wave order #${featureNumber}`));
 
   // 1. Lê a Feature e valida o tipo.
@@ -116,7 +273,19 @@ export async function order({ feature: featureArg }) {
 
   // 5. Ordenação topológica (nunca lança; ciclo vem em `cycle`).
   const byNumber = new Map(enriched.map(s => [s.number, s]));
-  const { order: sorted, cycle } = orderStories(enriched.map(({ number, dependsOn }) => ({ number, dependsOn })));
+  const { order: sorted, cycle, external } = orderStories(
+    enriched.map(({ number, dependsOn }) => ({ number, dependsOn })));
+
+  // Uma leitura por issue externa DISTINTA — o estado dela é o que diz se o
+  // bloqueio ainda vale.
+  const foraDoConjunto = [...new Set([...external.values()].flat())];
+  const externasInfo = new Map();
+  await Promise.all(foraDoConjunto.map(async (n) => {
+    const issue = await getIssue(token, owner, repo, n).catch(() => null);
+    externasInfo.set(n, issue
+      ? { title: issue.title, state: issue.state, aberta: issue.state === 'open' }
+      : { title: '(não foi possível ler)', state: null, aberta: true });
+  }));
 
   if (cycle.length > 0) {
     p.log.warn(
@@ -136,6 +305,18 @@ export async function order({ feature: featureArg }) {
   };
   p.note(sorted.map(line).join('\n'), `Ordem de execução das Stories da Feature #${featureNumber}`);
 
+  if (external.size > 0) {
+    const linhas = [...external.entries()].map(([n, deps]) => {
+      const detalhe = deps.map(d => {
+        const info = externasInfo.get(d);
+        const marca = info?.aberta ? chalk.yellow('aberta') : chalk.green('fechada');
+        return `#${d} (${marca}) ${info?.title || ''}`.trim();
+      }).join('\n      ');
+      return `  #${n} ${byNumber.get(n)?.title || ''}\n    ← ${detalhe}`;
+    });
+    p.note(linhas.join('\n'), 'Bloqueadas por fora desta Feature');
+  }
+
   // 6. Aviso final: dependente já em Desenvolvimento+ com dependência não-Done.
   const devIdx = STAGE_ORDER.indexOf(STAGE_DEVELOPMENT);
   const outOfOrder = [];
@@ -144,7 +325,19 @@ export async function order({ feature: featureArg }) {
     const idx = stage ? STAGE_ORDER.indexOf(stage) : -1;
     if (idx === -1 || idx < devIdx) continue; // ainda não chegou em Desenvolvimento
     for (const d of s.dependsOn) {
-      if (!byNumber.has(d)) continue; // dependência externa ao conjunto — sem Etapa conhecida
+      if (!byNumber.has(d)) {
+        // Externa: não tem Etapa neste conjunto, mas tem ESTADO — e uma issue
+        // aberta bloqueando quem já está em Desenvolvimento é a mesma falha que
+        // o aviso abaixo denuncia, só que atravessando a fronteira.
+        const info = externasInfo.get(d);
+        if (info?.aberta) {
+          outOfOrder.push(
+            `#${s.number} já está em "${stage}", mas depende de #${d}, de outra Feature, ` +
+            'que continua ABERTA.'
+          );
+        }
+        continue;
+      }
       const depStage = stageOf.get(d);
       if (depStage !== STAGE_DONE) {
         outOfOrder.push(

package/src/commands/qa.mjs

@@ -73,6 +73,9 @@ export async function qa({ prNumber }) {
 
   const etapaField = await resolveField(projectToken, project, 'Etapa').catch(() => null);
   const statusField = await resolveField(projectToken, project, 'Status').catch(() => null);
+  // Repara o Work Item Type vazio de passagem (o apply nunca o escreveu).
+  // Só preenche o vazio e nunca derruba o movimento — ver ensureWorkItemType.
+  const typeField = await resolveField(projectToken, project, 'Work Item Type').catch(() => null);
 
   const seen = new Set();
   const updated = [];
@@ -86,7 +89,8 @@ export async function qa({ prNumber }) {
       seen.add(issue.number);
       try {
         const moved = await advanceToStage(
-          projectToken, project, etapaField, statusField, issue.node_id, QA_STAGE, TODO_STATUS);
+          projectToken, project, etapaField, statusField, issue.node_id, QA_STAGE, TODO_STATUS,
+          { typeField, itemType: 'Bug' });
         if (moved) {
           updated.push(`#${issue.number} ${issue.title} (bug)`);
           console.log(`Bug #${issue.number} → "${QA_STAGE}" / Status "${TODO_STATUS}".`);
@@ -104,7 +108,9 @@ export async function qa({ prNumber }) {
     seen.add(feature.number);
     try {
       // Avança para "🧪 QA" e reinicia o Status em "Todo" (nunca retrocede).
-      const moved = await advanceToStage(projectToken, project, etapaField, statusField, feature.node_id, QA_STAGE, TODO_STATUS);
+      const moved = await advanceToStage(
+        projectToken, project, etapaField, statusField, feature.node_id, QA_STAGE, TODO_STATUS,
+        { typeField, itemType: 'Feature' });
       if (moved) {
         updated.push(`#${feature.number} ${feature.title}`);
         console.log(`Feature #${feature.number} → "${QA_STAGE}" / Status "${TODO_STATUS}".`);

package/src/commands/repair-stage.mjs

@@ -164,6 +164,10 @@ export async function repairStage(issuesArg, stageArg, options = {}) {
   }
   const etapaField = await resolveField(token, project, 'Etapa').catch(() => null);
   const statusField = status ? await resolveField(token, project, 'Status').catch(() => null) : null;
+  // Reparar a Etapa e deixar o item sem tipo seria consertar metade: os mesmos
+  // itens que perderam a Etapa nasceram do apply, que também não escrevia o
+  // Work Item Type. Só preenche o vazio (ver ensureWorkItemType).
+  const typeField = await resolveField(token, project, 'Work Item Type').catch(() => null);
 
   // Lê tudo ANTES de escrever qualquer coisa: reparo parcial por issue
   // inexistente no meio da lista é o tipo de surpresa que ninguém quer aqui.
@@ -216,7 +220,8 @@ export async function repairStage(issuesArg, stageArg, options = {}) {
   for (const alvo of alvos) {
     try {
       const { from } = await setItemStage(
-        token, project, etapaField, statusField, alvo.issue.node_id, stage, status);
+        token, project, etapaField, statusField, alvo.issue.node_id, stage, status,
+        { typeField, itemType: alvo.type });
       reparados += 1;
       p.log.success(`#${alvo.number}: ${from || '(sem etapa)'} → ${chalk.bold(stage)}${status ? ` / ${status}` : ''}`);
       await commentOnIssue(token, owner, repo, alvo.number, renderRepairComment({

package/src/commands/story.mjs

@@ -81,11 +81,16 @@ export async function story({ action, issue: issueArg }) {
   }
   const etapaField = await resolveField(token, project, 'Etapa').catch(() => null);
   const statusField = await resolveField(token, project, 'Status').catch(() => null);
+  // Repara o Work Item Type vazio de passagem (o apply nunca o escreveu).
+  // Só preenche o vazio e nunca derruba o movimento — ver ensureWorkItemType.
+  const typeField = await resolveField(token, project, 'Work Item Type').catch(() => null);
 
   // 3. Avança para Code Review (Status reinicia em Todo ao trocar de etapa).
   let moved;
   try {
-    moved = await advanceToStage(token, project, etapaField, statusField, issue.node_id, STAGE_CODE_REVIEW, PROGRESS_TODO);
+    moved = await advanceToStage(
+      token, project, etapaField, statusField, issue.node_id, STAGE_CODE_REVIEW, PROGRESS_TODO,
+      { typeField, itemType: type });
   } catch (err) {
     p.log.error(`Falha ao atualizar o board: ${err.message}`);
     process.exitCode = 1;

package/src/commands/task.mjs

@@ -102,6 +102,9 @@ export async function task({ action, issue: issueArg }) {
   }
   const etapaField = await resolveField(token, project, 'Etapa').catch(() => null);
   const statusField = await resolveField(token, project, 'Status').catch(() => null);
+  // Repara o Work Item Type vazio de passagem (o apply nunca o escreveu).
+  // Só preenche o vazio e nunca derruba o movimento — ver ensureWorkItemType.
+  const typeField = await resolveField(token, project, 'Work Item Type').catch(() => null);
 
   // 3. start: garante que nenhuma task irmã (mesma Story) está In Progress.
   if (action === 'start') {
@@ -146,7 +149,9 @@ export async function task({ action, issue: issueArg }) {
 
   let moved;
   try {
-    moved = await advanceToStage(token, project, etapaField, statusField, issue.node_id, target.stage, target.status);
+    moved = await advanceToStage(
+      token, project, etapaField, statusField, issue.node_id, target.stage, target.status,
+      { typeField, itemType: type });
   } catch (err) {
     p.log.error(`Falha ao atualizar o board: ${err.message}`);
     process.exitCode = 1;

package/src/commands/triage.mjs

@@ -163,8 +163,11 @@ async function moveToReady({ token, issueNumber, issue, root }) {
   try {
     const etapaField = await resolveField(token, project, 'Etapa').catch(() => null);
     const statusField = await resolveField(token, project, 'Status').catch(() => null);
+    // Triagem só trata Bug — o tipo aqui é certeza, não inferência de título.
+    const typeField = await resolveField(token, project, 'Work Item Type').catch(() => null);
     const moved = await advanceToStage(
-      token, project, etapaField, statusField, issue.node_id, STAGE_READY, PROGRESS_TODO);
+      token, project, etapaField, statusField, issue.node_id, STAGE_READY, PROGRESS_TODO,
+      { typeField, itemType: 'Bug' });
     if (!moved) {
       p.log.info(`#${issueNumber} já está em ${STAGE_READY} ou etapa posterior — mantido.`);
     }

package/src/commands/validate.mjs

@@ -8,7 +8,7 @@ import {
   REQUIRED_PLAN_SECTIONS, REQUIRED_SPEC_SECTIONS, REQUIRED_BUG_SECTIONS, labelNames,
 } from '../config.mjs';
 import { findIncompleteDocSigns } from '../lib/doc-completeness.mjs';
-import { bugDocPaths, findMissingSections } from '../lib/bug-doc.mjs';
+import { bugDocPaths, describeMissingSections } from '../lib/bug-doc.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
 import { loadConfig } from '../lib/project-root.mjs';
 
@@ -47,8 +47,8 @@ async function validateBug({ token, owner, repo, issue, issueNumber, root }) {
     );
   } else {
     const content = readFileSync(fileAbs, 'utf-8');
-    for (const section of findMissingSections(content, REQUIRED_BUG_SECTIONS)) {
-      errors.push(`❌ Seção obrigatória ausente no bug.md: **${section}**`);
+    for (const faltante of describeMissingSections(content, REQUIRED_BUG_SECTIONS)) {
+      errors.push(renderMissingSection('bug.md', faltante));
     }
     for (const problem of findIncompleteDocSigns(content)) {
       errors.push(`❌ \`bug.md\` parece incompleto: ${problem}`);
@@ -79,6 +79,22 @@ async function validateBug({ token, owner, repo, issue, issueNumber, root }) {
   console.log('bug.md validado.');
 }
 
+/**
+ * Linha de erro de seção ausente (função PURA).
+ *
+ * Dizer só o que falta obriga o humano a comparar título a título; dizer o que
+ * EXISTE no lugar resolve em segundos o caso real (um "# Rollout e
+ * Monitoramento" onde se esperava "# Rollback e Monitoramento", com o conteúdo
+ * certo embaixo).
+ */
+export function renderMissingSection(doc, { section, found }) {
+  const base = `❌ Seção obrigatória ausente no ${doc}: **${section}**`;
+  return found
+    ? `${base} — encontrei \`# ${found}\`, esperava \`# ${section}\`. ` +
+      'Se o conteúdo é o certo, basta renomear o título.'
+    : base;
+}
+
 export async function validate({ issueNumber }) {
   const token = await resolveToken();
   const [envOwner, envRepo] = (process.env.GITHUB_REPOSITORY || '').split('/');
@@ -133,8 +149,8 @@ export async function validate({ issueNumber }) {
     errors.push('❌ `plan.md` não encontrado em `' + `${featureRel}/plan.md` + '`');
   } else {
     const planContent = readFileSync(planPath, 'utf-8');
-    for (const section of findMissingSections(planContent, REQUIRED_PLAN_SECTIONS)) {
-      errors.push(`❌ Seção obrigatória ausente no plan.md: **${section}**`);
+    for (const faltante of describeMissingSections(planContent, REQUIRED_PLAN_SECTIONS)) {
+      errors.push(renderMissingSection('plan.md', faltante));
     }
     for (const problem of findIncompleteDocSigns(planContent)) {
       errors.push(`❌ \`plan.md\` parece incompleto: ${problem}`);
@@ -147,8 +163,8 @@ export async function validate({ issueNumber }) {
     errors.push('❌ `spec.md` não encontrado em `' + `${featureRel}/spec.md` + '`');
   } else {
     const specContent = readFileSync(specPath, 'utf-8');
-    for (const section of findMissingSections(specContent, REQUIRED_SPEC_SECTIONS)) {
-      errors.push(`❌ Seção obrigatória ausente no spec.md: **${section}**`);
+    for (const faltante of describeMissingSections(specContent, REQUIRED_SPEC_SECTIONS)) {
+      errors.push(renderMissingSection('spec.md', faltante));
     }
     // Seções presentes não garantem documento completo: um corte dentro da
     // última seção passa na checagem acima (foi o caso da EP2-F13).
@@ -165,18 +181,23 @@ export async function validate({ issueNumber }) {
       token, owner, repo, parseInt(issueNumber, 10),
       `⚠️ **Validação falhou — Feature não está pronta.**\n\n` +
       errors.join('\n') +
-      `\n\nCorreija os problemas e adicione novamente a label \`spec-wave:ready\`.`
+      `\n\nCorrija os problemas e adicione novamente a label \`spec-wave:ready\`.` +
+      `\n\nSe os documentos precisam mesmo ser REGERADOS (e não só corrigidos), aplique ` +
+      `você a label \`spec-wave:spec\` — ela **sobrescreve** o \`spec.md\`, inclusive o que ` +
+      'foi revisado à mão.'
     );
-    // Quando as ÚNICAS falhas são os portões humanos (crítica grave / revisão
-    // exigida), os documentos existem e estão estruturalmente válidos — só
-    // precisam de correção manual. Nesse caso NÃO devolvemos a feature para a
-    // etapa de spec (spec-wave:spec).
-    const humanGates = (critiqueFailed ? 1 : 0) + (needsHuman ? 1 : 0);
-    const onlyHumanGates = humanGates > 0 && errors.length === humanGates;
-    if (!onlyHumanGates) {
-      // Send back to spec stage
-      await addLabel(token, owner, repo, parseInt(issueNumber, 10), 'spec-wave:spec');
-    }
+    // A reprova NÃO aplica mais `spec-wave:spec` sozinha.
+    //
+    // `spec-wave:spec` é label de GATILHO: aplicá-la manda o generate-spec
+    // sobrescrever o spec.md. Uma reprova por título trocado ("# Rollout" onde
+    // se esperava "# Rollback", com o conteúdo certo embaixo) apagaria uma spec
+    // revisada à mão por causa de uma palavra. Isso não aconteceu até hoje por
+    // um acidente: o GitHub não dispara `labeled` para eventos do GITHUB_TOKEN,
+    // então a label ficava inerte. Quem trocasse por um PAT — o que a própria
+    // documentação sugere para alcançar Projects de organização — perderia o
+    // documento sem nunca ter pedido isso.
+    //
+    // Regenerar é decisão humana, e o comentário acima diz como e o que custa.
     console.error('Validação falhou:', errors.join(', '));
     process.exit(1);
   }

package/src/config.mjs

@@ -43,6 +43,44 @@ export const AI_ACTIONS = ['spec', 'plan', 'decompose', 'critique', 'bug'];
 // repositório inteiro. Resolvido por resolveModelLabel() em src/lib/claude.mjs.
 export const MODEL_LABEL_PREFIX = 'spec-wave:model:';
 
+// Apelidos de modelo SUGERIDOS pelo `doctor` quando o repo não tem
+// `ai.modelAliases` (ou tem só parte deles). São os mesmos que o repo do
+// spec-wave usa: um por família de modelo, para que a label
+// `spec-wave:model:<apelido>` cubra "roda de novo num modelo mais forte" sem
+// obrigar cada projeto a inventar a própria nomenclatura.
+//
+// O mapa é POR PROVIDER porque o formato do id não é o mesmo: a OpenRouter usa
+// slug com "/" (anthropic/claude-opus-5) e a API da Anthropic usa o id nu
+// (claude-opus-5). Sugerir o formato errado geraria exatamente o aviso de
+// "apelido com formato incompatível" que o doctor emite na linha seguinte.
+export const RECOMMENDED_MODEL_ALIASES = {
+  openrouter: {
+    opus: 'anthropic/claude-opus-5',
+    sonnet: 'anthropic/claude-sonnet-5',
+    haiku: 'anthropic/claude-haiku-4.5',
+    glm: 'z-ai/glm-5.2',
+    'kimi-k3': 'moonshotai/kimi-k3',
+    'gpt-sol': 'openai/gpt-5.6-sol',
+    'gpt-luna': 'openai/gpt-5.6-luna',
+  },
+  // Só os modelos da própria Anthropic — os demais não existem nessa API.
+  anthropic: {
+    opus: 'claude-opus-5',
+    sonnet: 'claude-sonnet-5',
+    haiku: 'claude-haiku-4-5',
+  },
+};
+
+/**
+ * Apelidos recomendados para um provider (função PURA).
+ *
+ * @param {string} [provider] valor de `ai.provider`
+ * @returns {Record<string,string>}
+ */
+export function recommendedModelAliases(provider) {
+  return RECOMMENDED_MODEL_ALIASES[provider] || RECOMMENDED_MODEL_ALIASES[DEFAULT_PROVIDER];
+}
+
 // Quantas críticas seguidas podem reprovar a mesma issue antes de exigir revisão
 // humana. Na última tentativa a IA NÃO é chamada: o fluxo aplica
 // `spec-wave:needs-human` e para. Ajustável por `ai.maxCritiqueAttempts`.
@@ -334,6 +372,12 @@ export const LABEL_CRITIQUE_FAILED = 'spec-wave:critique-failed';
 export const LABEL_DECOMPOSED = 'spec-wave:decomposed';
 export const LABEL_DECOMPOSE_READY = 'spec-wave:decompose-ready';
 export const LABEL_NEEDS_HUMAN = 'spec-wave:needs-human';
+// Selo de que spec+plan passaram pelo `validate`. É o que distingue uma Feature
+// pronta de uma que só foi movida à mão para ✅ Ready.
+export const LABEL_PLAN_APPROVED = 'spec-wave:plan-approved';
+// Gatilhos que REGERAM documento: presentes na issue, indicam etapa pendente.
+export const LABEL_SPEC = 'spec-wave:spec';
+export const LABEL_PLAN = 'spec-wave:plan';
 // Achado GRAVE que o Tech Leader aceitou como risco conhecido. Fica na issue
 // depois que a crítica passa: sem ela, o risco aceito some da vista assim que a
 // rodada seguinte roda limpa, e ninguém mais sabe que houve uma decisão.
@@ -344,11 +388,11 @@ export const LABEL_RISK_ACCEPTED = 'spec-wave:risk-accepted';
 export const LABEL_CRITIQUE = 'spec-wave:critique';
 
 export const TRIGGER_LABELS = [
-  { name: 'spec-wave:spec',          color: 'BFD4F2', description: 'Gerar spec.md via GitHub Action'      },
-  { name: 'spec-wave:plan',          color: 'BFD4F2', description: 'Gerar plan.md via GitHub Action'      },
+  { name: LABEL_SPEC,                color: 'BFD4F2', description: 'Gerar spec.md via GitHub Action'      },
+  { name: LABEL_PLAN,                color: 'BFD4F2', description: 'Gerar plan.md via GitHub Action'      },
   { name: LABEL_CRITIQUE,            color: 'BFD4F2', description: 'Re-criticar o plan.md COMO ESTÁ, sem regerar' },
   { name: 'spec-wave:ready',         color: '0E8A16', description: 'Validar spec+plan e mover para Ready'  },
-  { name: 'spec-wave:plan-approved', color: '0E8A16', description: 'Spec+plan validados com sucesso'       },
+  { name: LABEL_PLAN_APPROVED,       color: '0E8A16', description: 'Spec+plan validados com sucesso'       },
   { name: LABEL_DECOMPOSE,           color: 'BFD4F2', description: 'Gerar/re-criticar o rascunho da decomposição (decomposition.md)' },
   { name: LABEL_DECOMPOSE_APPLY,     color: 'BFD4F2', description: 'Aplicar o decomposition.md revisado: criar Stories e Tasks' },
   { name: LABEL_DEV_AGENT,           color: '5319E7', description: 'Enfileira a issue para o dev-agent autônomo' },