@spec-wave/cli 0.20.0 → 0.23.0

package/src/commands/decompose.mjs

@@ -49,9 +49,16 @@ import {
 
 // Adiciona a issue ao board na Etapa ✅ Ready / Status Todo. Best-effort; a
 // Etapa nunca retrocede (advanceToStage não toca itens já adiante).
-async function moveToReady(token, project, etapaField, statusField, nodeId) {
+//
+// `itemType` é o tipo do que ACABOU de ser criado ('Story'/'Task'/'Feature') —
+// aqui não há dúvida sobre ele, e sem essa passagem o Work Item Type das issues
+// nascidas do apply ficava vazio para sempre (ver ensureWorkItemType).
+async function moveToReady(token, project, fields, nodeId, itemType) {
   if (!project?.id) return;
-  await advanceToStage(token, project, etapaField, statusField, nodeId, STAGE_READY, PROGRESS_TODO);
+  await advanceToStage(
+    token, project, fields.etapaField, fields.statusField, nodeId, STAGE_READY, PROGRESS_TODO,
+    { typeField: fields.typeField, itemType },
+  );
 }
 
 /**
@@ -196,6 +203,25 @@ export function shouldSkipDecompose({ labels = [], subIssues = [], type } = {})
   return { skip: false, reason: '' };
 }
 
+/**
+ * Milestone que os filhos herdam do pai (função PURA — testável).
+ *
+ * Uma Story/Task nasce para entregar a Feature que a gerou: separá-las da release
+ * do pai faria a mesma entrega aparecer em dois grupos — e o milestone é o que o
+ * fluxo usa como release (é o milestone fechado que sinaliza o deploy). Mesma
+ * regra que a reprovação de QA já aplica ao registrar um bug filho.
+ *
+ * Devolve o NÚMERO (o que `createIssue` aceita) ou `undefined` quando o pai não
+ * tem milestone — aí não há release a herdar, e o filho nasce sem, como antes.
+ *
+ * @param {{ milestone?: { number?: number, title?: string } | null }} [issue]
+ * @returns {number|undefined}
+ */
+export function resolveInheritedMilestone(issue) {
+  const number = issue?.milestone?.number;
+  return Number.isInteger(number) && number > 0 ? number : undefined;
+}
+
 // Diretório do documento por tipo. Feature usa o mesmo docs/features/<slug> da
 // spec/plan; RFC ganha o seu, já que não passa por spec/plan.
 function resolveDocDir(root, issue, type) {
@@ -457,8 +483,8 @@ async function applyDecomposition(ctx) {
 
   // Campos do board só são resolvidos aqui: a etapa de rascunho não toca o board.
   // `strict`: no apply, board inalcançável ABORTA antes da primeira criação.
-  const { project, etapaField, statusField } = await resolveBoard(ctx, { strict: true });
-  const applyCtx = { ...ctx, project, etapaField, statusField };
+  const { project, etapaField, statusField, typeField } = await resolveBoard(ctx, { strict: true });
+  const applyCtx = { ...ctx, project, etapaField, statusField, typeField };
 
   // As falhas de board voltam em vez de subir na hora: a exceção precisa esperar
   // a contabilidade de labels abaixo. Lançar aqui deixaria o gatilho
@@ -495,7 +521,16 @@ async function applyDecomposition(ctx) {
 
   await addLabel(token, owner, repo, number, LABEL_DECOMPOSED)
     .catch(err => console.warn(`Falha ao aplicar a label ${LABEL_DECOMPOSED}: ${err.message}`));
-  await removeLabel(token, owner, repo, number, LABEL_DECOMPOSE_APPLY);
+  // Best-effort como as duas vizinhas: as issues já existem, e derrubar o run
+  // porque a REMOÇÃO de uma label falhou (404 de label já removida por um run
+  // concorrente, 5xx da API) transformava um apply concluído em vermelho — e o
+  // vermelho manda o humano reaplicar o gatilho, que é o caminho para duplicar
+  // dezenas de issues. A label que sobra é visível na issue e removível à mão.
+  await removeLabel(token, owner, repo, number, LABEL_DECOMPOSE_APPLY)
+    .catch(err => console.warn(
+      `Decomposição aplicada, mas a label ${LABEL_DECOMPOSE_APPLY} não pôde ser removida ` +
+      `(${err.message}). Remova-a à mão: gh issue edit ${number} --remove-label "${LABEL_DECOMPOSE_APPLY}".`
+    ));
   await removeLabel(token, owner, repo, number, LABEL_DECOMPOSE_READY).catch(() => {});
 
   // Por último, com as labels já consistentes: escrita de board incompleta
@@ -519,7 +554,10 @@ export function renderBoardFailures(failures) {
     `${linhas}\n\n` +
     `Motivo: \`${motivo}\`\n\n` +
     'Verifique o `GH_PROJECT_TOKEN` (scope `project` e acesso ao Project da organização) e ' +
-    'reposicione os itens com `npx @spec-wave/cli@latest repair-stage <issue>`.'
+    'reposicione os itens com `npx @spec-wave/cli@latest repair-stage <issue>`.\n\n' +
+    'O run termina em VERMELHO de propósito — a decomposição em si CONCLUIU. ' +
+    `Não reaplique \`${LABEL_DECOMPOSE_APPLY}\`: as issues acima já existem e o apply ` +
+    'recomeça do zero; o que falta é só a Etapa, e quem repara isso é o `repair-stage`.'
   );
 }
 
@@ -541,9 +579,59 @@ function failIfBoardIncomplete(failures) {
   throw err;
 }
 
+// Linha do comentário registrando o milestone herdado ('' quando não há).
+function milestoneLine(issue, milestone) {
+  if (!milestone) return '';
+  return `🏁 Milestone herdado do pai: **${issue.milestone?.title ?? `#${milestone}`}**.\n\n`;
+}
+
+/**
+ * Resolve as dependências externas do rascunho ANTES de criar qualquer issue.
+ *
+ * `#N` só entra no documento se a issue JÁ existe (fase 1 da proposta), e é
+ * aqui que isso é cobrado. Falhar cedo é a única opção honesta: descobrir no
+ * meio do laço que a #412 não existe deixaria metade das Stories criadas e a
+ * outra metade não — o estado que o apply inteiro foi desenhado para evitar.
+ *
+ * `addBlockedBy` exige o DATABASE id da bloqueadora (não aceita number nem node
+ * id), e é por isso que resolver custa uma leitura por issue distinta.
+ *
+ * @returns {Promise<Map<number, {number:number, id:number, title:string}>>}
+ */
+async function resolveExternalDeps({ token, owner, repo }, doc) {
+  const numeros = [...new Set(
+    (doc.stories || []).flatMap(s => s.dependsOnIssues || [])
+  )].sort((a, b) => a - b);
+  const resolvidas = new Map();
+  const faltando = [];
+  for (const n of numeros) {
+    try {
+      const issue = await getIssue(token, owner, repo, n);
+      resolvidas.set(n, { number: issue.number, id: issue.id, title: issue.title });
+    } catch (err) {
+      faltando.push(`#${n} (${err.status === 404 ? 'não existe' : err.message})`);
+    }
+  }
+  if (faltando.length > 0) {
+    throw new Error(
+      `o rascunho depende de issue(s) que não consegui ler: ${faltando.join(', ')}. ` +
+      'Em "**Depende de:**", `#N` precisa ser uma issue que JÁ existe — corrija o ' +
+      'decomposition.md (ou aplique antes a Feature que cria essa Story).'
+    );
+  }
+  return resolvidas;
+}
+
 async function createStoriesFromDoc(ctx, doc) {
-  const { token, projectToken, owner, repo, issue, issueNumber, project, etapaField, statusField, docRel } = ctx;
+  const { token, projectToken, owner, repo, issue, issueNumber, project, docRel } = ctx;
+  const fields = { etapaField: ctx.etapaField, statusField: ctx.statusField, typeField: ctx.typeField };
   const featureNodeId = issue.node_id;
+  // Herdado uma vez e reusado por todas as Stories e Tasks deste apply.
+  const milestone = resolveInheritedMilestone(issue);
+  if (milestone) console.log(`Milestone herdado da ${ctx.type}: ${issue.milestone?.title ?? `#${milestone}`}.`);
+  // Antes da primeira criação: rascunho que aponta para issue inexistente é
+  // erro de escrita, e o lugar de reprovar é aqui.
+  const externas = await resolveExternalDeps(ctx, doc);
   const created = [];
   const createdStories = []; // issues criadas, na ordem dos índices das stories
   const generatedTexts = []; // títulos+corpos para o lint de idioma final
@@ -560,12 +648,18 @@ async function createStoriesFromDoc(ctx, doc) {
       .filter(Boolean)
       .join('\n\n') || '_(sem descrição)_';
 
-    // dependsOn já vem validado pelo parser (0-based, só para trás).
-    const depIssues = story.dependsOn.map(idx => createdStories[idx]).filter(Boolean);
+    // Irmãs (índices já validados pelo parser, sempre para trás) + externas (já
+    // resolvidas acima). As duas viram a MESMA linha no corpo e a mesma relação
+    // blocked_by: para quem lê a issue, a fronteira da Feature não existe.
+    const depIssues = [
+      ...story.dependsOn.map(idx => createdStories[idx]),
+      ...(story.dependsOnIssues || []).map(n => externas.get(n)),
+    ].filter(Boolean);
     const depLine = formatDependencyLine(depIssues.map(d => d.number));
     if (depLine) storyBody += `\n\n${depLine}`;
 
-    const createdStory = await createIssue(token, owner, repo, storyTitle, storyBody, ['[STORY]']);
+    const createdStory = await createIssue(token, owner, repo, storyTitle, storyBody, ['[STORY]'], { milestone });
+    ctx.createdItems.push(createdStory.number);
     // Anota no doc em memória: é daqui que sai o `**Issue:** #N` gravado no
     // arquivo no fim do apply.
     story.issue = createdStory.number;
@@ -588,7 +682,7 @@ async function createStoriesFromDoc(ctx, doc) {
       console.warn(`  Story #${createdStory.number} criada, mas falhou ao vincular à Feature: ${err.message}`);
     }
     try {
-      await moveToReady(projectToken, project, etapaField, statusField, createdStory.nodeId);
+      await moveToReady(projectToken, project, fields, createdStory.nodeId, 'Story');
     } catch (err) {
       console.warn(`  Falha ao mover story #${createdStory.number} para "${STAGE_READY}": ${err.message}`);
       boardFailures.push({ number: createdStory.number, kind: 'Story', reason: err.message });
@@ -598,7 +692,8 @@ async function createStoriesFromDoc(ctx, doc) {
       console.log(`  Criando task: ${task.title}`);
       const taskTitle = `[TASK] ${task.title}`;
       const taskBody = `${task.body}\n\n_Story pai: ${createdStory.url}_`;
-      const createdTask = await createIssue(token, owner, repo, taskTitle, taskBody, ['[TASK]']);
+      const createdTask = await createIssue(token, owner, repo, taskTitle, taskBody, ['[TASK]'], { milestone });
+      ctx.createdItems.push(createdTask.number);
       task.issue = createdTask.number;
       generatedTexts.push(taskTitle, taskBody);
       try {
@@ -607,7 +702,7 @@ async function createStoriesFromDoc(ctx, doc) {
         console.warn(`    Task #${createdTask.number} criada, mas falhou ao vincular à Story: ${err.message}`);
       }
       try {
-        await moveToReady(projectToken, project, etapaField, statusField, createdTask.nodeId);
+        await moveToReady(projectToken, project, fields, createdTask.nodeId, 'Task');
       } catch (err) {
         console.warn(`    Falha ao mover task #${createdTask.number} para "${STAGE_READY}": ${err.message}`);
         boardFailures.push({ number: createdTask.number, kind: 'Task', reason: err.message });
@@ -616,8 +711,8 @@ async function createStoriesFromDoc(ctx, doc) {
   }
 
   try {
-    await moveToReady(projectToken, project, etapaField, statusField, featureNodeId);
-    if (project?.id && etapaField) console.log(`Feature movida para "${STAGE_READY}" no board.`);
+    await moveToReady(projectToken, project, fields, featureNodeId, ctx.type);
+    if (project?.id && fields.etapaField) console.log(`Feature movida para "${STAGE_READY}" no board.`);
   } catch (err) {
     console.warn(`Falha ao mover Feature para "${STAGE_READY}": ${err.message}`);
     boardFailures.push({ number: parseInt(issueNumber, 10), kind: 'Feature', reason: err.message });
@@ -630,6 +725,7 @@ async function createStoriesFromDoc(ctx, doc) {
   await commentOnIssue(token, owner, repo, parseInt(issueNumber, 10),
     `🔀 **Decomposição aplicada!**\n\n` +
     `A partir de \`${docRel}\` foram criados ${created.length} stories e suas tasks:\n\n${list}\n\n` +
+    milestoneLine(issue, milestone) +
     posicionamento +
     formatItemsLintWarning(generatedTexts)
   ).catch(err => console.warn(`Falha ao comentar a decomposição: ${err.message}`));
@@ -685,8 +781,11 @@ async function commentStoryOrder({ token, owner, repo, issueNumber, doc, created
 }
 
 async function createTasksFromDoc(ctx, doc) {
-  const { token, projectToken, owner, repo, issue, issueNumber, project, etapaField, statusField, docRel } = ctx;
+  const { token, projectToken, owner, repo, issue, issueNumber, project, docRel } = ctx;
+  const fields = { etapaField: ctx.etapaField, statusField: ctx.statusField, typeField: ctx.typeField };
   const parentNodeId = issue.node_id;
+  const milestone = resolveInheritedMilestone(issue);
+  if (milestone) console.log(`Milestone herdado do RFC: ${issue.milestone?.title ?? `#${milestone}`}.`);
   const created = [];
   const generatedTexts = [];
   const boardFailures = [];
@@ -695,7 +794,8 @@ async function createTasksFromDoc(ctx, doc) {
     console.log(`Criando task: ${task.title}`);
     const taskTitle = `[TASK] ${task.title}`;
     const taskBody = `${task.body}\n\n_RFC pai: ${issue.html_url || `#${issueNumber}`}_`;
-    const createdTask = await createIssue(token, owner, repo, taskTitle, taskBody, ['[TASK]']);
+    const createdTask = await createIssue(token, owner, repo, taskTitle, taskBody, ['[TASK]'], { milestone });
+    ctx.createdItems.push(createdTask.number);
     task.issue = createdTask.number;
     created.push({ title: taskTitle, url: createdTask.url });
     generatedTexts.push(taskTitle, taskBody);
@@ -706,7 +806,7 @@ async function createTasksFromDoc(ctx, doc) {
       console.warn(`  Task #${createdTask.number} criada, mas falhou ao vincular ao RFC: ${err.message}`);
     }
     try {
-      await moveToReady(projectToken, project, etapaField, statusField, createdTask.nodeId);
+      await moveToReady(projectToken, project, fields, createdTask.nodeId, 'Task');
     } catch (err) {
       console.warn(`  Falha ao mover task #${createdTask.number} para "${STAGE_READY}": ${err.message}`);
       boardFailures.push({ number: createdTask.number, kind: 'Task', reason: err.message });
@@ -720,6 +820,7 @@ async function createTasksFromDoc(ctx, doc) {
   await commentOnIssue(token, owner, repo, parseInt(issueNumber, 10),
     `🔀 **Decomposição do RFC aplicada!**\n\n` +
     `A partir de \`${docRel}\` foram criadas ${created.length} tasks:\n\n${list}\n\n` +
+    milestoneLine(issue, milestone) +
     posicionamento +
     formatItemsLintWarning(generatedTexts)
   ).catch(err => console.warn(`Falha ao comentar a decomposição: ${err.message}`));
@@ -757,6 +858,7 @@ async function resolveBoard({ projectToken, root }, { strict = false } = {}) {
 
   let etapaField = null;
   let statusField = null;
+  let typeField = null;
   if (project?.id) {
     try {
       etapaField = await resolveField(projectToken, project, 'Etapa');
@@ -770,14 +872,58 @@ async function resolveBoard({ projectToken, root }, { strict = false } = {}) {
       if (strict) throw new BoardUnreachableError(`campo Status não resolvido (${err.message})`);
       console.warn(`Não foi possível resolver campo Status do board: ${err.message}`);
     }
+    // NUNCA strict: o tipo é organização, não visibilidade. Um board sem o campo
+    // "Work Item Type" continua sendo um board válido — sem Etapa, não.
+    try {
+      typeField = await resolveField(projectToken, project, 'Work Item Type');
+    } catch (err) {
+      console.warn(`Não foi possível resolver campo Work Item Type do board: ${err.message}`);
+    }
   }
-  return { project, etapaField, statusField };
+  return { project, etapaField, statusField, typeField };
 }
 
 // ---------------------------------------------------------------------------
 // Entrada
 // ---------------------------------------------------------------------------
 
+/**
+ * Comentário de falha do apply (função PURA).
+ *
+ * O conselho depende de UMA coisa: já existe issue criada por este run?
+ *
+ *  • Não → o retry é seguro e é o que se quer: reaplique o gatilho.
+ *  • Sim → o apply recomeça do zero, e o único freio é o guard de idempotência
+ *    (label `spec-wave:decomposed` ou sub-issues do tipo-alvo). Se a falha foi
+ *    ANTES de a label ser aplicada e o vínculo de sub-issue também não pegou,
+ *    reaplicar duplica tudo o que a lista abaixo mostra. Mandar "adicione a
+ *    label de novo" nesse estado — que é o que este comentário fazia sempre —
+ *    é o conselho errado exatamente quando ele custa mais caro.
+ *
+ * @param {object} params
+ * @param {string} params.trigger label que disparou o run
+ * @param {string} params.message mensagem do erro
+ * @param {number[]} [params.createdItems] issues já criadas por este run
+ * @param {'apply'|'draft'} [params.mode]
+ */
+export function renderApplyFailureComment({ trigger, message, createdItems = [], mode = 'apply' }) {
+  const cabecalho =
+    `❌ **Falha no decompose (${mode === 'apply' ? 'aplicação' : 'rascunho'}).**\n\n` +
+    `\`\`\`\n${message}\n\`\`\`\n\n`;
+  if (createdItems.length === 0) {
+    return cabecalho +
+      `A label \`${trigger}\` foi removida para destravar o gatilho — ` +
+      'adicione-a de novo para tentar outra vez.';
+  }
+  const lista = createdItems.map(n => `#${n}`).join(', ');
+  return cabecalho +
+    `⚠️ **${createdItems.length} issue(s) JÁ foram criadas por este run:** ${lista}.\n\n` +
+    `A label \`${trigger}\` foi removida para destravar o gatilho, mas **não a reaplique sem ` +
+    'conferir**: o apply recomeça do zero e, se o guard de idempotência não tiver pegado ' +
+    `(label \`${LABEL_DECOMPOSED}\` ou sub-issues do tipo-alvo), essas issues são recriadas. ` +
+    'Complete o que falta à mão, ou apague as issues acima antes de tentar de novo.';
+}
+
 export async function decompose({ issueNumber, apply = false }) {
   const token = await resolveToken();
   // PROJECT_TOKEN deve ter scope "project" para atualizar GitHub Projects v2.
@@ -858,6 +1004,10 @@ export async function decompose({ issueNumber, apply = false }) {
   const ctx = {
     token, projectToken, owner, repo, issue, issueNumber, type, labels, comments,
     root, runMode, docDir, docPath, docRel: `${docRel}/${DECOMPOSITION_FILE}`,
+    // Números das issues já criadas por este run. Compartilhado por referência
+    // com o applyCtx: o catch externo precisa saber se houve criação para não
+    // aconselhar um retry que duplicaria itens.
+    createdItems: [],
     escalationModel: config?.ai?.escalationModel || null,
     maxCritiqueAttempts:
       Number.isInteger(config?.ai?.maxCritiqueAttempts) && config.ai.maxCritiqueAttempts > 0
@@ -874,10 +1024,9 @@ export async function decompose({ issueNumber, apply = false }) {
     if (!err.blocked) {
       await removeLabel(token, owner, repo, number, trigger).catch(() => {});
       await commentOnIssue(token, owner, repo, number,
-        `❌ **Falha no decompose (${mode === 'apply' ? 'aplicação' : 'rascunho'}).**\n\n` +
-        `\`\`\`\n${err.message}\n\`\`\`\n\n` +
-        `A label \`${trigger}\` foi removida para destravar o gatilho — ` +
-        'adicione-a de novo para tentar outra vez.'
+        renderApplyFailureComment({
+          trigger, message: err.message, createdItems: ctx.createdItems, mode,
+        })
       ).catch(() => {});
     }
     throw err;

package/src/commands/doctor.mjs

@@ -16,7 +16,8 @@ import { getProjectSnapshot, listSubIssues } from '../api/github-graphql.mjs';
 import {
   CONFIG_FILE, WORKFLOW_FILES, getProvider, DEFAULT_PROVIDER, STATUS_OPTIONS,
   RETIRED_STAGES, ALL_LABELS, allLabelsFor, LABEL_NEEDS_HUMAN, MODEL_LABEL_PREFIX,
-  DEFAULT_MAX_CRITIQUE_ATTEMPTS, STAGE_TRACKS, AI_ACTIONS,
+  DEFAULT_MAX_CRITIQUE_ATTEMPTS, STAGE_TRACKS, AI_ACTIONS, recommendedModelAliases,
+  modelLabels,
 } from '../config.mjs';
 import { findConfigPath } from '../lib/project-root.mjs';
 import {
@@ -284,7 +285,10 @@ async function checkConfig(ctx) {
  * @param {object} params
  * @param {string[]} [params.boardStages] opções reais de Etapa no project
  * @param {string[]} [params.repoLabels] nomes das labels do repo
- * @returns {{ unknownStages: string[], missingStages: string[], orphanLabels: string[], missingLabels: string[] }}
+ * @returns {{ unknownStages: string[], missingStages: string[], orphanLabels: string[],
+ *            missingLabels: string[], missingModelLabels: string[] }}
+ *          `missingLabels` traz só as do fluxo; as de modelo saem separadas
+ *          porque a orientação é outra (ver o uso em checkBoardHygiene).
  */
 /**
  * Os ids de opção do .spec-wave.json batem com os do Project? (função PURA)
@@ -314,6 +318,35 @@ export function inspectStageIds({ configOptions = null, boardOptions = null } =
   return { staleIds, checked: true };
 }
 
+/**
+ * O que falta em `ai.modelAliases` para chegar ao conjunto recomendado (função PURA).
+ *
+ * Sem apelido nenhum, a label `spec-wave:model:<apelido>` não resolve nada: o
+ * override por issue — o jeito de reprocessar UMA Feature difícil num modelo
+ * mais forte sem mexer na config do repo inteiro — fica inerte, e o doctor só
+ * dizia que estava inerte, sem dizer o que colar para destravá-lo.
+ *
+ * Sugere o MERGE (configurado + faltante), nunca a substituição: apelido já
+ * configurado pode estar em uso numa issue aberta, e mandar sobrescrever o
+ * bloco quebraria essa issue em silêncio.
+ *
+ * @param {object} params
+ * @param {string} [params.provider] valor de `ai.provider`
+ * @param {object|null} [params.aliases] bloco `ai.modelAliases` atual
+ * @returns {{ missing: Array<{alias: string, model: string}>, snippet: string }}
+ */
+export function suggestModelAliases({ provider = undefined, aliases = null } = {}) {
+  const recommended = recommendedModelAliases(provider);
+  const have = new Set(Object.keys(aliases || {}));
+  const missing = Object.entries(recommended)
+    .filter(([alias]) => !have.has(alias))
+    .map(([alias, model]) => ({ alias, model }));
+  if (missing.length === 0) return { missing, snippet: '' };
+  const merged = { ...(aliases || {}) };
+  for (const { alias, model } of missing) merged[alias] = model;
+  return { missing, snippet: `"modelAliases": ${JSON.stringify(merged, null, 2)}` };
+}
+
 export function inspectBoardHygiene({ boardStages = null, repoLabels = null, modelAliases = null } = {}) {
   const canonical = STATUS_OPTIONS.map(s => s.name);
   const known = new Set(canonical);
@@ -342,10 +375,18 @@ export function inspectBoardHygiene({ boardStages = null, repoLabels = null, mod
     ? repoLabels.filter(n => n.startsWith('spec-wave:') && !knownLabels.has(n)
         && (modelAliases !== null || !n.startsWith(MODEL_LABEL_PREFIX)))
     : [];
-  const missingLabels = repoLabels
-    ? wantedLabels.map(l => l.name).filter(n => !repoLabels.includes(n))
+  // Ausentes saem em duas listas: uma label do fluxo que falta é um repo
+  // desatualizado; uma `spec-wave:model:<apelido>` que falta é um apelido
+  // configurado que NINGUÉM consegue usar — a label não existe para ser aplicada
+  // na issue, então o override de modelo por execução está morto na origem.
+  const allMissing = repoLabels
+    ? wantedLabels.filter(l => !repoLabels.includes(l.name)).map(l => l.name)
     : [];
-  return { unknownStages, retiredStages, missingStages, orphanLabels, missingLabels };
+  const missingModelLabels = allMissing.filter(n => n.startsWith(MODEL_LABEL_PREFIX));
+  const missingLabels = allMissing.filter(n => !n.startsWith(MODEL_LABEL_PREFIX));
+  return {
+    unknownStages, retiredStages, missingStages, orphanLabels, missingLabels, missingModelLabels,
+  };
 }
 
 /**
@@ -407,7 +448,7 @@ async function checkBoardHygiene(ctx) {
     }
   }
 
-  const { unknownStages, retiredStages, missingStages, orphanLabels, missingLabels } =
+  const { unknownStages, retiredStages, missingStages, orphanLabels, missingLabels, missingModelLabels } =
     inspectBoardHygiene({ boardStages, repoLabels, modelAliases: cfg?.ai?.modelAliases ?? null });
 
   const notes = [];
@@ -481,8 +522,32 @@ async function checkBoardHygiene(ctx) {
       status = 'warn';
       notes.push(`Labels do fluxo ausentes no repo: ${missingLabels.join(', ')} — rode \`update\`.`);
     }
-    if (orphanLabels.length === 0 && missingLabels.length === 0) {
-      notes.push(`Labels: ${ALL_LABELS.length} do fluxo presentes, nenhuma descontinuada.`);
+    // Apelido configurado sem label é uma promessa que o repo não cumpre: a skill
+    // manda aplicar `spec-wave:model:<apelido>` na issue e o `gh issue edit` falha
+    // com "label not found" — ou, pior, cria a label sem cor nem descrição.
+    if (missingModelLabels.length > 0) {
+      status = 'warn';
+      const specs = modelLabels(cfg?.ai?.modelAliases);
+      const exemplo = specs.find(l => l.name === missingModelLabels[0]);
+      notes.push(
+        `Labels de modelo ausentes no repo: ${missingModelLabels.join(', ')} — o apelido está em ` +
+        '`ai.modelAliases`, mas a label não existe, então não há como aplicá-la numa issue e o ' +
+        'override de modelo por execução fica indisponível. Rode ' +
+        '`npx @spec-wave/cli@latest update` para criar todas' +
+        (exemplo
+          ? `, ou uma a uma: \`gh label create "${exemplo.name}" --color ${exemplo.color} ` +
+            `--description "${exemplo.description}"\`.`
+          : '.')
+      );
+    }
+    if (orphanLabels.length === 0 && missingLabels.length === 0 && missingModelLabels.length === 0) {
+      // Conta as de modelo à parte — dizer só "N do fluxo" omitia que as labels
+      // de apelido também foram conferidas.
+      const modelCount = modelLabels(cfg?.ai?.modelAliases).length;
+      notes.push(
+        `Labels: ${ALL_LABELS.length} do fluxo` +
+        `${modelCount > 0 ? ` + ${modelCount} de modelo` : ''} presentes, nenhuma descontinuada.`
+      );
     }
   } else {
     notes.push('Labels do repo não verificáveis agora (sem token ou sem acesso).');
@@ -595,11 +660,19 @@ async function checkAi(ctx) {
   const aliases = fileAi.modelAliases && Object.keys(fileAi.modelAliases).length > 0
     ? fileAi.modelAliases
     : null;
+  const suggestion = suggestModelAliases({ provider: provider.value, aliases });
+  // Onde colar e o que rodar depois: o bloco sozinho não cria as labels, e sem
+  // a label criada no repo o override continua sem existir para quem abre a issue.
+  const howTo = (
+    `Cole no bloco \`ai\` do ${CONFIG_FILE}, commite e rode ` +
+    '`npx @spec-wave/cli@latest update` para criar as labels correspondentes:'
+  );
   if (!aliases) {
     notes.push(
       `Apelidos de modelo: nenhum (\`ai.modelAliases\` ausente) — labels ` +
       `\`${MODEL_LABEL_PREFIX}<apelido>\` serão ignoradas.`
     );
+    notes.push(`Sugestão de apelidos para o provider ${provider.value}. ${howTo}\n${suggestion.snippet}`);
   } else {
     notes.push(
       `Apelidos de modelo (\`${MODEL_LABEL_PREFIX}<apelido>\`): ` +
@@ -616,6 +689,13 @@ async function checkAi(ctx) {
         `${wrongShape.map(([a, m]) => `${a}=${m}`).join(', ')}.`
       );
     }
+    if (suggestion.missing.length > 0) {
+      notes.push(
+        `Apelidos recomendados ainda não configurados: ` +
+        `${suggestion.missing.map(({ alias, model }) => `${alias}=${model}`).join(', ')}. ` +
+        `${howTo}\n${suggestion.snippet}`
+      );
+    }
   }
 
   // Saída estruturada da crítica: sem structured output confiável, a validação

package/src/commands/move.mjs

@@ -21,6 +21,8 @@ import { loadConfig } from '../lib/project-root.mjs';
 import {
   CONFIG_FILE, PROGRESS_TODO, PROGRESS_IN_PROGRESS, PROGRESS_DONE,
   isManualStageType, MANUAL_STAGE_TYPES, isStageInTrack, STAGE_TRACKS,
+  STAGE_READY, LABEL_PLAN_APPROVED, LABEL_SPEC, LABEL_PLAN, LABEL_CRITIQUE_FAILED,
+  LABEL_NEEDS_HUMAN, allowsSpecPlan, labelNames,
 } from '../config.mjs';
 
 const PROGRESS_VALUES = [PROGRESS_TODO, PROGRESS_IN_PROGRESS, PROGRESS_DONE];
@@ -49,6 +51,51 @@ export function resolveProgressName(input) {
       };
 }
 
+/**
+ * O que o board sabe e quem move à mão pode não saber (função PURA).
+ *
+ * `advanceToStage` já protege a ORDEM das etapas ("a Etapa nunca retrocede"),
+ * mas nada olhava os PORTÕES: mover uma Feature para ✅ Ready sem
+ * `spec-wave:plan-approved` põe na fila do time um item cuja validação não
+ * passou — e com `spec-wave:spec` ainda na issue, que é o rastro de uma reprova
+ * recente. Foi o que aconteceu com a #43.
+ *
+ * AVISA, não bloqueia: a decisão pode ser deliberada (documentos corrigidos à
+ * mão, validação que não se quer rodar de novo), e o comando existe justamente
+ * para os casos que o fluxo não cobre. O que não pode é ser silencioso.
+ *
+ * @param {object} params
+ * @param {string|null} params.type tipo do work item
+ * @param {string} params.stage etapa de destino
+ * @param {Array<string|{name:string}>} [params.labels] labels da issue
+ * @returns {string[]} avisos, na ordem de gravidade
+ */
+export function readinessWarnings({ type, stage, labels = [] } = {}) {
+  if (stage !== STAGE_READY) return [];
+  const nomes = labelNames(labels);
+  const avisos = [];
+
+  // Bug, RFC e Spike não passam por spec/plan — cobrar plan-approved deles
+  // seria inventar um portão que o fluxo não tem.
+  if (allowsSpecPlan(type) && !nomes.includes(LABEL_PLAN_APPROVED)) {
+    avisos.push(
+      `não tem \`${LABEL_PLAN_APPROVED}\`: spec+plan não passaram pelo \`validate\`. ` +
+      `Para validar, aplique \`spec-wave:ready\` na issue.`
+    );
+  }
+  for (const gatilho of [LABEL_SPEC, LABEL_PLAN]) {
+    if (nomes.includes(gatilho)) {
+      avisos.push(`ainda tem \`${gatilho}\` — há geração de documento pendente ou uma reprova recente.`);
+    }
+  }
+  for (const portao of [LABEL_CRITIQUE_FAILED, LABEL_NEEDS_HUMAN]) {
+    if (nomes.includes(portao)) {
+      avisos.push(`tem \`${portao}\` — a crítica reprovou e ninguém liberou.`);
+    }
+  }
+  return avisos;
+}
+
 export async function move({ issue: issueArg, stage: stageArg, status: statusArg }) {
   const issueNumber = parseInt(String(issueArg).replace('#', ''), 10);
   if (!Number.isInteger(issueNumber) || issueNumber <= 0) {
@@ -126,6 +173,11 @@ export async function move({ issue: issueArg, stage: stageArg, status: statusArg
     );
   }
 
+  // Portões do fluxo: aviso antes de escrever, com a issue já em mãos.
+  for (const aviso of readinessWarnings({ type, stage, labels: issue.labels })) {
+    p.log.warn(`#${issueNumber} ${aviso}`);
+  }
+
   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\`).`);
@@ -134,11 +186,16 @@ export async function move({ issue: issueArg, stage: stageArg, status: statusArg
   }
   const etapaField = await resolveField(token, project, 'Etapa').catch(() => null);
   const statusField = await resolveField(token, project, 'Status').catch(() => null);
+  // O `move` também REPARA o Work Item Type quando ele está vazio (o `apply` não
+  // o escrevia, então há board com dezenas de itens sem tipo). Só no vazio, e
+  // mesmo quando a Etapa não avança — ver ensureWorkItemType.
+  const typeField = await resolveField(token, project, 'Work Item Type').catch(() => null);
 
   let moved;
   try {
     moved = await advanceToStage(
-      token, project, etapaField, statusField, issue.node_id, stage, status);
+      token, project, etapaField, statusField, issue.node_id, stage, status,
+      { typeField, itemType: type });
   } catch (err) {
     p.log.error(`Falha ao atualizar o board: ${err.message}`);
     process.exitCode = 1;