@spec-wave/cli 0.19.0 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spec-wave/cli",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "Setup spec-driven GitHub workflow with Projects v2, labels, issue templates, and AI-powered Actions",
   "type": "module",
   "bin": {

package/src/api/github-graphql.mjs

@@ -179,17 +179,74 @@ export async function getProjectSnapshot(token, projectId) {
   };
 }
 
-// Adiciona uma issue/PR (pelo node id do conteúdo) ao Project. Retorna o id do item criado.
-export async function addProjectItem(token, projectId, contentId) {
+/**
+ * O item deste conteúdo que JÁ está no project (função de rede, sem mutação).
+ *
+ * Vai pelo conteúdo (`node(contentId).projectItems`), não pelos itens do
+ * project: um board com milhares de itens paginaria por todos eles para achar
+ * um; uma issue está em poucos projects.
+ *
+ * @returns {Promise<string|null>} id do item, ou null se não estiver no project
+ */
+export async function findProjectItem(token, projectId, contentId) {
   const client = makeClient(token);
   const result = await client(`
-    mutation AddItem($projectId: ID!, $contentId: ID!) {
-      addProjectV2ItemById(input: { projectId: $projectId, contentId: $contentId }) {
-        item { id }
+    query FindItem($contentId: ID!) {
+      node(id: $contentId) {
+        ... on Issue        { projectItems(first: 50) { nodes { id project { id } } } }
+        ... on PullRequest  { projectItems(first: 50) { nodes { id project { id } } } }
       }
     }
-  `, { projectId, contentId });
-  return result.addProjectV2ItemById.item.id;
+  `, { contentId });
+  const nodes = result?.node?.projectItems?.nodes || [];
+  return nodes.find(n => n?.project?.id === projectId)?.id ?? null;
+}
+
+/**
+ * Adiciona uma issue/PR (pelo node id do conteúdo) ao Project e devolve o id do
+ * item. IDEMPOTENTE: item já presente devolve o id existente.
+ *
+ * `addProjectV2ItemById` é documentado como idempotente, mas na prática responde
+ * `Content already exists in this project` quando o item entrou por outro
+ * caminho entre a leitura e a escrita — a automação nativa "auto-add" do
+ * project, ou um run concorrente do próprio spec-wave. Como esta é a PRIMEIRA
+ * chamada de advanceToStage(), o erro abortava tudo o que vinha depois: o item
+ * ficava no board com o Status que a automação do project escreve e SEM Etapa —
+ * exatamente o estado que some de todas as telas (caso da #281). Traduzir o erro
+ * numa busca pelo item existente é o que torna a escrita seguinte possível.
+ */
+export async function addProjectItem(token, projectId, contentId) {
+  const client = makeClient(token);
+  try {
+    const result = await client(`
+      mutation AddItem($projectId: ID!, $contentId: ID!) {
+        addProjectV2ItemById(input: { projectId: $projectId, contentId: $contentId }) {
+          item { id }
+        }
+      }
+    `, { projectId, contentId });
+    return result.addProjectV2ItemById.item.id;
+  } catch (err) {
+    if (!isAlreadyInProjectError(err)) throw err;
+    const existing = await findProjectItem(token, projectId, contentId);
+    // Sem item correspondente, o erro não era duplicidade — devolvê-lo é mais
+    // honesto que um null que estouraria adiante como "field id inválido".
+    if (!existing) throw err;
+    return existing;
+  }
+}
+
+/**
+ * O erro é "esse conteúdo já está no project"? (função PURA)
+ *
+ * A mensagem vem de fora e pode mudar; o teste é por substring e não por
+ * igualdade justamente por isso. Errar para o lado de NÃO reconhecer só
+ * restaura o comportamento antigo (o erro sobe).
+ */
+export function isAlreadyInProjectError(err) {
+  const msg = String(err?.message || '');
+  return /already exists in this project/i.test(msg)
+    || /content already exists/i.test(msg);
 }
 
 // Cria a relação de sub-issue nativa do GitHub (parent → child). Ambos os IDs

package/src/commands/code-review.mjs

@@ -282,6 +282,9 @@ export async function codeReview({ prNumber, resolveOnly = false }) {
   // Resolve campos uma vez, reutiliza em todas as Features.
   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 = [];
@@ -312,7 +315,9 @@ export async function codeReview({ prNumber, resolveOnly = false }) {
       if (seen.has(n)) continue;
       seen.add(n);
       try {
-        const moved = await advanceToStage(projectToken, project, etapaField, statusField, info.nodeId, DONE_STAGE, DONE_STATUS);
+        const moved = await advanceToStage(
+          projectToken, project, etapaField, statusField, info.nodeId, DONE_STAGE, DONE_STATUS,
+          { typeField, itemType: 'Task' });
         if (moved) {
           updated.push(`#${n} ${info.title} → ${DONE_STAGE}`);
           console.log(`#${n} → "${DONE_STAGE}" / Status "${DONE_STATUS}".`);
@@ -329,7 +334,9 @@ export async function codeReview({ prNumber, resolveOnly = false }) {
       if (seen.has(n)) continue;
       seen.add(n);
       try {
-        const moved = await advanceToStage(projectToken, project, etapaField, statusField, info.nodeId, CODE_REVIEW_STAGE, TODO_STATUS);
+        const moved = await advanceToStage(
+          projectToken, project, etapaField, statusField, info.nodeId, CODE_REVIEW_STAGE, TODO_STATUS,
+          { typeField, itemType: 'Story' });
         if (moved) {
           updated.push(`#${n} ${info.title} → ${CODE_REVIEW_STAGE}`);
           console.log(`#${n} → "${CODE_REVIEW_STAGE}" / Status "${TODO_STATUS}".`);
@@ -346,7 +353,9 @@ export async function codeReview({ prNumber, resolveOnly = false }) {
       if (seen.has(n)) continue;
       seen.add(n);
       try {
-        const moved = await advanceToStage(projectToken, project, etapaField, statusField, info.nodeId, CODE_REVIEW_STAGE, TODO_STATUS);
+        const moved = await advanceToStage(
+          projectToken, project, etapaField, statusField, info.nodeId, CODE_REVIEW_STAGE, TODO_STATUS,
+          { typeField, itemType: 'Bug' });
         if (moved) {
           updated.push(`#${n} ${info.title} → ${CODE_REVIEW_STAGE}`);
           console.log(`Bug #${n} → "${CODE_REVIEW_STAGE}" / Status "${TODO_STATUS}".`);
@@ -367,7 +376,9 @@ export async function codeReview({ prNumber, resolveOnly = false }) {
           console.log(`Feature #${feature.number} mantida em desenvolvimento — ainda há Stories pendentes (fora de "${CODE_REVIEW_STAGE}").`);
         } else if (!seen.has(feature.number)) {
           seen.add(feature.number);
-          const moved = await advanceToStage(projectToken, project, etapaField, statusField, feature.nodeId, CODE_REVIEW_STAGE, TODO_STATUS);
+          const moved = await advanceToStage(
+            projectToken, project, etapaField, statusField, feature.nodeId, CODE_REVIEW_STAGE, TODO_STATUS,
+            { typeField, itemType: 'Feature' });
           if (moved) {
             updated.push(`#${feature.number} ${feature.title} (Feature) → ${CODE_REVIEW_STAGE}`);
             console.log(`Feature #${feature.number} → "${CODE_REVIEW_STAGE}" (todas as Stories concluídas).`);

package/src/commands/decompose.mjs

@@ -31,7 +31,7 @@ import {
   parseCritiqueDecisions, applyCritiqueDecisions, renderRiskAcceptedComment,
 } from '../lib/critique.mjs';
 import { recordUsage } from '../lib/usage-report.mjs';
-import { formatDependencyLine } from '../lib/dependencies.mjs';
+import { formatDependencyLine, orderStories, renderOrderComment } from '../lib/dependencies.mjs';
 import { lintLanguage } from '../lib/output-lint.mjs';
 import { slugify } from '../lib/slugify.mjs';
 import { detectIssueType } from '../lib/issue-type.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 },
+  );
 }
 
 /**
@@ -457,8 +464,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 +502,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 +535,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`.'
   );
 }
 
@@ -542,7 +561,8 @@ function failIfBoardIncomplete(failures) {
 }
 
 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;
   const created = [];
   const createdStories = []; // issues criadas, na ordem dos índices das stories
@@ -566,6 +586,7 @@ async function createStoriesFromDoc(ctx, doc) {
     if (depLine) storyBody += `\n\n${depLine}`;
 
     const createdStory = await createIssue(token, owner, repo, storyTitle, storyBody, ['[STORY]']);
+    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 +609,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 });
@@ -599,6 +620,7 @@ async function createStoriesFromDoc(ctx, doc) {
       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]']);
+      ctx.createdItems.push(createdTask.number);
       task.issue = createdTask.number;
       generatedTexts.push(taskTitle, taskBody);
       try {
@@ -607,7 +629,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 +638,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 });
@@ -633,12 +655,60 @@ async function createStoriesFromDoc(ctx, doc) {
     posicionamento +
     formatItemsLintWarning(generatedTexts)
   ).catch(err => console.warn(`Falha ao comentar a decomposição: ${err.message}`));
+
+  await commentStoryOrder({ token, owner, repo, issueNumber, doc, createdStories });
+
   console.log(`Decomposição aplicada: ${created.length} stories criadas.`);
   return boardFailures;
 }
 
+/**
+ * Publica a ordem de execução das Stories como um segundo comentário.
+ *
+ * Os dados saem do que ACABOU de ser criado — `createdStories` (índice → issue)
+ * e `doc.stories[i].dependsOn` (0-based, já validado pelo parser). Não consulta
+ * o board: reconstruir isso pela API custaria ~4 chamadas por Story para chegar
+ * ao que já está em memória, e a Etapa é ✅ Ready por construção — se não fosse,
+ * `failIfBoardIncomplete` já teria derrubado o run.
+ *
+ * BEST-EFFORT, como o comentário que o antecede: a decomposição está feita e
+ * paga, e falhar ao comentar não pode desfazê-la nem mascarar o que deu certo.
+ */
+async function commentStoryOrder({ token, owner, repo, issueNumber, doc, createdStories }) {
+  try {
+    const stories = doc.stories
+      .map((story, i) => {
+        const criada = createdStories[i];
+        if (!criada) return null; // criação falhou no meio: não inventa a Story
+        return {
+          number: criada.number,
+          title: story.title,
+          // dependsOn vem 0-based (índice no doc) e vira número de issue.
+          dependsOn: (story.dependsOn || [])
+            .map(idx => createdStories[idx]?.number)
+            .filter(Boolean),
+        };
+      })
+      .filter(Boolean);
+
+    if (stories.length === 0) return;
+
+    const byNumber = new Map(stories.map(s => [s.number, s]));
+    const { order: sorted, cycle } = orderStories(
+      stories.map(({ number, dependsOn }) => ({ number, dependsOn }))
+    );
+
+    await commentOnIssue(token, owner, repo, parseInt(issueNumber, 10),
+      renderOrderComment({ sorted, cycle, byNumber }));
+    console.log(`Ordem de execução comentada: ${sorted.length} story(ies).`);
+  } catch (err) {
+    console.warn(`Falha ao comentar a ordem de execução: ${err.message}`);
+  }
+}
+
 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 created = [];
   const generatedTexts = [];
@@ -649,6 +719,7 @@ async function createTasksFromDoc(ctx, doc) {
     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]']);
+    ctx.createdItems.push(createdTask.number);
     task.issue = createdTask.number;
     created.push({ title: taskTitle, url: createdTask.url });
     generatedTexts.push(taskTitle, taskBody);
@@ -659,7 +730,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 });
@@ -710,6 +781,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');
@@ -723,14 +795,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.
@@ -811,6 +927,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
@@ -827,10 +947,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

@@ -134,11 +134,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;

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/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`.

package/src/lib/board.mjs

@@ -2,7 +2,7 @@
 // Extraídos de code-review.mjs/qa.mjs para uso também pelos comandos de CLI
 // (task/story/order). Ver a distinção Etapa × Status em config.mjs.
 import { addProjectItem, setItemSingleSelect, getSingleSelectField, getItemSingleSelectValue } from '../api/github-graphql.mjs';
-import { CONFIG_FILE, STAGE_ORDER, STATUS_OPTIONS } from '../config.mjs';
+import { CONFIG_FILE, STAGE_ORDER, STATUS_OPTIONS, WORK_ITEM_TYPES } from '../config.mjs';
 import { loadConfig } from './project-root.mjs';
 
 /**
@@ -116,6 +116,45 @@ export function resolveStageName(input) {
   return { stage: null, error: `Etapa "${input}" não existe. Use uma destas: ${list()}.` };
 }
 
+/**
+ * Preenche o "Work Item Type" do item quando ele está VAZIO (best-effort).
+ *
+ * O campo existe no board desde o `init`, mas só o comando `issue` o escrevia:
+ * toda issue nascida do `decompose --apply` (dezenas por Feature) e todo item
+ * que entrou no board por outro caminho ficavam com o tipo em branco, e as
+ * telas que agrupam por Work Item Type os perdiam. Não é configuração faltando:
+ * os mesmos ids, project e token escrevem o campo sem falha quando alguém o faz
+ * à mão. O `move` também não o reparava, então nem passar pelo fluxo corrigia.
+ *
+ * Escreve só no vazio, de propósito: o tipo do título ("[STORY] …") é uma
+ * inferência, e sobrescrever um valor que um humano ajustou no board seria
+ * trocar um dado bom por um palpite. Por isso também roda ANTES do guard de
+ * avanço de Etapa — item já adiante não avança, mas continua merecendo o reparo.
+ *
+ * Nunca lança: campo ausente, opção inexistente ou falha de rede viram `false`.
+ * O tipo é informação de organização; derrubar por causa dele um comando que
+ * moveu a Etapa seria trocar o essencial pelo acessório.
+ *
+ * @returns {Promise<boolean>} true se escreveu o campo agora
+ */
+export async function ensureWorkItemType(token, project, typeField, itemId, itemType) {
+  if (!typeField?.id || !itemType) return false;
+  if (!WORK_ITEM_TYPES.includes(itemType)) return false;
+  const optionId = typeField.options?.[itemType];
+  if (!optionId) return false;
+  try {
+    const current = await getItemSingleSelectValue(token, itemId, typeField.id);
+    if (current) return false; // já tem tipo — nunca sobrescreve
+    await setItemSingleSelect(token, project.id, itemId, typeField.id, optionId);
+    return true;
+  } catch (err) {
+    // Avisa em vez de calar: foi o silêncio que deixou 120 itens sem tipo por
+    // seis features seguidas sem ninguém perceber.
+    console.warn(`Work Item Type "${itemType}" não pôde ser escrito: ${err.message}`);
+    return false;
+  }
+}
+
 /**
  * Avança um item do board para `targetStage` (Etapa) e define o Status para
  * `targetStatus`. Uma issue só AVANÇA: se já estiver em `targetStage` ou em uma
@@ -128,10 +167,18 @@ export function resolveStageName(input) {
  * @param {string} nodeId node id da issue
  * @param {string} targetStage nome da etapa de destino
  * @param {string} targetStatus valor do Status (Todo/In Progress/Done)
+ * @param {object} [opts]
+ * @param {{id,options}|null} [opts.typeField] campo "Work Item Type" (ver resolveField)
+ * @param {string} [opts.itemType] tipo do item ('Story', 'Task', …) — escrito
+ *        apenas se o campo estiver vazio (ver ensureWorkItemType)
  * @returns {Promise<boolean>} true se avançou; false se já estava adiante
  */
-export async function advanceToStage(token, project, etapaField, statusField, nodeId, targetStage, targetStatus) {
+export async function advanceToStage(
+  token, project, etapaField, statusField, nodeId, targetStage, targetStatus, opts = {}
+) {
   const itemId = await addProjectItem(token, project.id, nodeId);
+  // Antes do guard de avanço: item que não avança também precisa do reparo.
+  await ensureWorkItemType(token, project, opts.typeField, itemId, opts.itemType);
 
   if (etapaField?.id && targetStage) {
     // Nunca retroceder — a decisão vive em shouldAdvanceStage (pura, testada).
@@ -167,9 +214,12 @@ export async function advanceToStage(token, project, etapaField, statusField, no
  * @param {string} nodeId node id da issue
  * @param {string} targetStage etapa de destino (precisa existir em STAGE_ORDER)
  * @param {string} [targetStatus] valor do Status; omitido = não mexe no Status
+ * @param {object} [opts] mesmo `{ typeField, itemType }` de advanceToStage
  * @returns {Promise<{ from: string|null }>} etapa em que o item estava
  */
-export async function setItemStage(token, project, etapaField, statusField, nodeId, targetStage, targetStatus) {
+export async function setItemStage(
+  token, project, etapaField, statusField, nodeId, targetStage, targetStatus, opts = {}
+) {
   if (!etapaField?.id) throw new Error('Campo "Etapa" não encontrado no Project — nada a reparar.');
   if (STAGE_ORDER.indexOf(targetStage) === -1) {
     throw new Error(`Etapa "${targetStage}" não faz parte do fluxo (${STAGE_ORDER.join(' → ')}).`);
@@ -182,6 +232,7 @@ export async function setItemStage(token, project, etapaField, statusField, node
     );
   }
   const itemId = await addProjectItem(token, project.id, nodeId);
+  await ensureWorkItemType(token, project, opts.typeField, itemId, opts.itemType);
   const from = await getItemSingleSelectValue(token, itemId, etapaField.id).catch(() => null);
   await setItemSingleSelect(token, project.id, itemId, etapaField.id, optionId);
   if (statusField?.id && targetStatus) {

package/src/lib/dependencies.mjs

@@ -90,3 +90,52 @@ export function orderStories(stories) {
     .sort((a, b) => a - b);
   return { order, cycle };
 }
+
+/**
+ * Comentário com a ordem de execução das Stories (função PURA).
+ *
+ * A decomposição já comentava a lista das Stories criadas, mas na ordem de
+ * criação e sem dizer o que depende de quê — para saber por onde começar, o dev
+ * tinha de rodar `spec-wave order` no terminal. A informação existia fora da
+ * issue, que é onde o time olha.
+ *
+ * Sobre a expectativa: como `normalizeDependsOn` só aceita dependências para
+ * trás, a ordem de criação já é topologicamente válida e `orderStories` devolve
+ * a mesma sequência. O ganho aqui não é reordenar — é tornar a cadeia visível,
+ * com os números clicáveis. Passar por `orderStories` mesmo assim mantém uma só
+ * definição de "ordem de execução" (a que o comando `order` usa) e dá a
+ * detecção de ciclo de graça.
+ *
+ * @param {object} params
+ * @param {number[]} params.sorted números das Stories em ordem topológica
+ * @param {number[]} [params.cycle] Stories que ficaram fora da ordem (ciclo)
+ * @param {Map<number,{title: string, dependsOn: number[]}>} params.byNumber
+ * @returns {string} markdown
+ */
+export function renderOrderComment({ sorted, cycle = [], byNumber }) {
+  const linha = (n, i) => {
+    const s = byNumber.get(n);
+    const deps = s?.dependsOn?.length > 0
+      ? ` — depende de ${s.dependsOn.map(d => `#${d}`).join(', ')}`
+      : '';
+    return `${i + 1}. #${n} ${s?.title ?? ''}${deps}`.trimEnd();
+  };
+
+  const partes = [
+    '📋 **Ordem de execução das Stories**',
+    sorted.map(linha).join('\n'),
+  ];
+
+  // Espelha o aviso que o comando `order` dá no terminal. Estruturalmente o
+  // parser impede ciclo (dependência só para trás), mas se a validação relaxar,
+  // silenciar aqui esconderia Stories do comentário — e ninguém perceberia.
+  if (cycle.length > 0) {
+    partes.push(
+      `⚠️ **Ciclo de dependências:** ${cycle.map(n => `#${n}`).join(', ')} ` +
+      'ficaram FORA da ordem acima. Corrija as linhas "Depende de" (ou as relações ' +
+      'blocked_by) dessas issues.'
+    );
+  }
+
+  return partes.join('\n\n');
+}

package/src/lib/implement-board.mjs

@@ -22,8 +22,8 @@ import {
  *           story?:   {nodeId:string,number:number}|null,
  *           bug?:     {nodeId:string,number:number}|null,
  *           tasks?:   Array<{nodeId?:string,number:number}> }} refs
- * @returns {Array<{nodeId:string, label:string, stage:string, status:string,
- *                  statusFallback:boolean}>}
+ * @returns {Array<{nodeId:string, label:string, type:string, stage:string,
+ *                  status:string, statusFallback:boolean}>}
  *   statusFallback: se a Etapa já estiver adiante (advanceToStage devolve
  *   false), ainda assim alinhar o Status — usado nos movimentos de início
  *   (ex.: Feature já em Desenvolvimento volta a mostrar In Progress).
@@ -37,37 +37,37 @@ export function planBoardMoves(phase, {
   const moves = [];
   if (phase === 'start') {
     if (feature?.nodeId) {
-      moves.push({ nodeId: feature.nodeId, label: `Feature #${feature.number}`,
+      moves.push({ nodeId: feature.nodeId, label: `Feature #${feature.number}`, type: 'Feature',
                    stage: STAGE_DEVELOPMENT, status: PROGRESS_IN_PROGRESS, statusFallback: true });
     }
     if (story?.nodeId) {
-      moves.push({ nodeId: story.nodeId, label: `Story #${story.number}`,
+      moves.push({ nodeId: story.nodeId, label: `Story #${story.number}`, type: 'Story',
                    stage: STAGE_DEVELOPMENT, status: PROGRESS_IN_PROGRESS, statusFallback: true });
     }
     // Bug é folha e não tem Feature-pai a arrastar: um defeito em correção não
     // deve puxar a Feature inteira de volta para Desenvolvimento.
     if (bug?.nodeId) {
-      moves.push({ nodeId: bug.nodeId, label: `Bug #${bug.number}`,
+      moves.push({ nodeId: bug.nodeId, label: `Bug #${bug.number}`, type: 'Bug',
                    stage: STAGE_DEVELOPMENT, status: PROGRESS_IN_PROGRESS, statusFallback: true });
     }
     for (const t of tasks) {
       if (!t?.nodeId) continue;
-      moves.push({ nodeId: t.nodeId, label: `Task #${t.number}`,
+      moves.push({ nodeId: t.nodeId, label: `Task #${t.number}`, type: 'Task',
                    stage: STAGE_DEVELOPMENT, status: tasksStartStatus,
                    statusFallback: tasksStartStatus === PROGRESS_IN_PROGRESS });
     }
   } else if (phase === 'success') {
     for (const t of tasks) {
       if (!t?.nodeId) continue;
-      moves.push({ nodeId: t.nodeId, label: `Task #${t.number}`,
+      moves.push({ nodeId: t.nodeId, label: `Task #${t.number}`, type: 'Task',
                    stage: STAGE_DONE, status: PROGRESS_DONE, statusFallback: false });
     }
     if (story?.nodeId) {
-      moves.push({ nodeId: story.nodeId, label: `Story #${story.number}`,
+      moves.push({ nodeId: story.nodeId, label: `Story #${story.number}`, type: 'Story',
                    stage: STAGE_CODE_REVIEW, status: PROGRESS_TODO, statusFallback: false });
     }
     if (bug?.nodeId) {
-      moves.push({ nodeId: bug.nodeId, label: `Bug #${bug.number}`,
+      moves.push({ nodeId: bug.nodeId, label: `Bug #${bug.number}`, type: 'Bug',
                    stage: STAGE_CODE_REVIEW, status: PROGRESS_TODO, statusFallback: false });
     }
     // Feature: só o modo Feature passa `feature` aqui, e só depois de TODAS as
@@ -77,7 +77,7 @@ export function planBoardMoves(phase, {
     // num branch único e não abre PR), a Feature ficava presa em
     // Desenvolvimento com todas as Stories já em Code Review.
     if (feature?.nodeId) {
-      moves.push({ nodeId: feature.nodeId, label: `Feature #${feature.number}`,
+      moves.push({ nodeId: feature.nodeId, label: `Feature #${feature.number}`, type: 'Feature',
                    stage: STAGE_CODE_REVIEW, status: PROGRESS_TODO, statusFallback: false });
     }
   }
@@ -113,6 +113,9 @@ export async function applyBoardMoves({
     const projectToken = process.env.PROJECT_TOKEN || token;
     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 tipo de cada movimento é
+    // conhecido por construção (planBoardMoves). Ver ensureWorkItemType.
+    const typeField = await resolveField(projectToken, project, 'Work Item Type').catch(() => null);
     if (!etapaField?.id) {
       log.warn('board: campo Etapa não resolvido — Etapas não atualizadas.');
       return;
@@ -120,7 +123,8 @@ export async function applyBoardMoves({
     for (const m of moves) {
       try {
         const advanced = await advanceToStage(
-          projectToken, project, etapaField, statusField, m.nodeId, m.stage, m.status);
+          projectToken, project, etapaField, statusField, m.nodeId, m.stage, m.status,
+          { typeField, itemType: m.type });
         if (advanced) {
           log.info(`board: ${m.label} → ${m.stage} (${m.status})`);
         } else if (m.statusFallback && statusField?.id) {

package/src/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "spec-wave",
   "displayName": "Spec Wave",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "Fluxo spec-driven no GitHub (RFC-001): Projects v2, labels de gatilho, spec/plan gerados por Action, decomposição em duas etapas e implementação orientada a Stories/Tasks.",
   "author": {
     "name": "Astratech",

package/src/templates/workflows/code-review.yml

@@ -27,8 +27,12 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: '24'
+
+      - name: Instala a CLI
+        run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
+
       - id: resolve
-        run: npx @spec-wave/cli@{{CLI_VERSION}} code-review --pr-number ${{ github.event.pull_request.number }} --resolve-only
+        run: spec-wave code-review --pr-number ${{ github.event.pull_request.number }} --resolve-only
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           GITHUB_REPOSITORY: ${{ github.repository }}
@@ -56,8 +60,11 @@ jobs:
         with:
           node-version: '24'
 
+      - name: Instala a CLI
+        run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
+
       - name: Move Feature to Code Review
-        run: npx @spec-wave/cli@{{CLI_VERSION}} code-review --pr-number ${{ github.event.pull_request.number }}
+        run: spec-wave code-review --pr-number ${{ github.event.pull_request.number }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           PROJECT_TOKEN: ${{ secrets.GH_PROJECT_TOKEN }}

package/src/templates/workflows/critique.yml

@@ -5,7 +5,21 @@ on:
     types: [labeled]
 
 concurrency:
-  group: spec-wave-critique-${{ github.event.issue.number }}
+  # Um run que NÃO vai fazer nada não pode disputar este grupo.
+  #
+  # `issues: [labeled]` dispara para QUALQUER label — prioridade, tipo,
+  # `spec-wave:model:*`. O job é filtrado pelo `if:` e termina skipped, mas o RUN
+  # entra na fila de concurrency do mesmo jeito, e com `cancel-in-progress: false`
+  # o GitHub cancela o run que já estava PENDENTE para pôr o novo no lugar. Foi
+  # assim que um decompose enfileirado atrás de um generate-plan morreu cancelado
+  # em 1 segundo por causa de uma label sem relação nenhuma — a label de gatilho
+  # fica na issue, `labeled` não redispara com ela aplicada, e o fluxo trava sem
+  # nenhum sinal. Rotular o run inútil com um grupo único (`github.run_id`) o tira
+  # da fila sem afrouxar a serialização de quem realmente vai rodar.
+  group: >-
+    ${{ github.event.label.name == 'spec-wave:critique'
+    && format('spec-wave-critique-{0}', github.event.issue.number)
+    || format('spec-wave-noop-{0}', github.run_id) }}
   cancel-in-progress: false
 
 jobs:
@@ -29,8 +43,11 @@ jobs:
         with:
           node-version: '24'
 
+      - name: Instala a CLI
+        run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
+
       - name: Critique plan.md as-is
-        run: npx @spec-wave/cli@{{CLI_VERSION}} critique --issue-number ${{ github.event.issue.number }}
+        run: spec-wave critique --issue-number ${{ github.event.issue.number }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

package/src/templates/workflows/decompose.yml

@@ -20,7 +20,21 @@ on:
 # o spec.md/plan.md do checkout — que uma geração concorrente estaria trocando
 # debaixo dele.
 concurrency:
-  group: spec-wave-item-${{ github.event.issue.number }}
+  # Um run que NÃO vai fazer nada não pode disputar este grupo.
+  #
+  # `issues: [labeled]` dispara para QUALQUER label — prioridade, tipo,
+  # `spec-wave:model:*`. O job é filtrado pelo `if:` e termina skipped, mas o RUN
+  # entra na fila de concurrency do mesmo jeito, e com `cancel-in-progress: false`
+  # o GitHub cancela o run que já estava PENDENTE para pôr o novo no lugar. Foi
+  # assim que um decompose enfileirado atrás de um generate-plan morreu cancelado
+  # em 1 segundo por causa de uma label sem relação nenhuma — a label de gatilho
+  # fica na issue, `labeled` não redispara com ela aplicada, e o fluxo trava sem
+  # nenhum sinal. Rotular o run inútil com um grupo único (`github.run_id`) o tira
+  # da fila sem afrouxar a serialização de quem realmente vai rodar.
+  group: >-
+    ${{ (github.event.label.name == 'spec-wave:decompose' || github.event.label.name == 'spec-wave:decompose-apply')
+    && format('spec-wave-item-{0}', github.event.issue.number)
+    || format('spec-wave-noop-{0}', github.run_id) }}
   cancel-in-progress: false
 
 jobs:
@@ -50,9 +64,12 @@ jobs:
         with:
           node-version: '24'
 
+      - name: Instala a CLI
+        run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
+
       - name: Decompose into Stories and Tasks
         run: >
-          npx @spec-wave/cli@{{CLI_VERSION}} decompose
+          spec-wave decompose
           --issue-number ${{ github.event.issue.number }}
           ${{ github.event.label.name == 'spec-wave:decompose-apply' && '--apply' || '' }}
         env:

package/src/templates/workflows/generate-bug.yml

@@ -12,7 +12,21 @@ on:
 # diferentes a disputa é resolvida no laço de repetição de push do
 # lib/flow-run.mjs — serializar o repositório inteiro mataria a vazão.
 concurrency:
-  group: spec-wave-item-${{ github.event.issue.number }}
+  # Um run que NÃO vai fazer nada não pode disputar este grupo.
+  #
+  # `issues: [labeled]` dispara para QUALQUER label — prioridade, tipo,
+  # `spec-wave:model:*`. O job é filtrado pelo `if:` e termina skipped, mas o RUN
+  # entra na fila de concurrency do mesmo jeito, e com `cancel-in-progress: false`
+  # o GitHub cancela o run que já estava PENDENTE para pôr o novo no lugar. Foi
+  # assim que um decompose enfileirado atrás de um generate-plan morreu cancelado
+  # em 1 segundo por causa de uma label sem relação nenhuma — a label de gatilho
+  # fica na issue, `labeled` não redispara com ela aplicada, e o fluxo trava sem
+  # nenhum sinal. Rotular o run inútil com um grupo único (`github.run_id`) o tira
+  # da fila sem afrouxar a serialização de quem realmente vai rodar.
+  group: >-
+    ${{ github.event.label.name == 'spec-wave:bug'
+    && format('spec-wave-item-{0}', github.event.issue.number)
+    || format('spec-wave-noop-{0}', github.run_id) }}
   cancel-in-progress: false
 
 jobs:
@@ -34,8 +48,11 @@ jobs:
         with:
           node-version: '24'
 
+      - name: Instala a CLI
+        run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
+
       - name: Generate bug.md
-        run: npx @spec-wave/cli@{{CLI_VERSION}} generate-bug --issue-number ${{ github.event.issue.number }}
+        run: spec-wave generate-bug --issue-number ${{ github.event.issue.number }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

package/src/templates/workflows/generate-plan.yml

@@ -20,7 +20,21 @@ on:
 # mataria a vazão, e a disputa entre issues diferentes é resolvida onde ela
 # acontece — no laço de repetição de push do lib/flow-run.mjs.
 concurrency:
-  group: spec-wave-item-${{ github.event.issue.number }}
+  # Um run que NÃO vai fazer nada não pode disputar este grupo.
+  #
+  # `issues: [labeled]` dispara para QUALQUER label — prioridade, tipo,
+  # `spec-wave:model:*`. O job é filtrado pelo `if:` e termina skipped, mas o RUN
+  # entra na fila de concurrency do mesmo jeito, e com `cancel-in-progress: false`
+  # o GitHub cancela o run que já estava PENDENTE para pôr o novo no lugar. Foi
+  # assim que um decompose enfileirado atrás de um generate-plan morreu cancelado
+  # em 1 segundo por causa de uma label sem relação nenhuma — a label de gatilho
+  # fica na issue, `labeled` não redispara com ela aplicada, e o fluxo trava sem
+  # nenhum sinal. Rotular o run inútil com um grupo único (`github.run_id`) o tira
+  # da fila sem afrouxar a serialização de quem realmente vai rodar.
+  group: >-
+    ${{ github.event.label.name == 'spec-wave:plan'
+    && format('spec-wave-item-{0}', github.event.issue.number)
+    || format('spec-wave-noop-{0}', github.run_id) }}
   cancel-in-progress: false
 
 jobs:
@@ -42,8 +56,11 @@ jobs:
         with:
           node-version: '24'
 
+      - name: Instala a CLI
+        run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
+
       - name: Generate plan.md
-        run: npx @spec-wave/cli@{{CLI_VERSION}} generate-plan --issue-number ${{ github.event.issue.number }}
+        run: spec-wave generate-plan --issue-number ${{ github.event.issue.number }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

package/src/templates/workflows/generate-spec.yml

@@ -20,7 +20,21 @@ on:
 # mataria a vazão, e a disputa entre issues diferentes é resolvida onde ela
 # acontece — no laço de repetição de push do lib/flow-run.mjs.
 concurrency:
-  group: spec-wave-item-${{ github.event.issue.number }}
+  # Um run que NÃO vai fazer nada não pode disputar este grupo.
+  #
+  # `issues: [labeled]` dispara para QUALQUER label — prioridade, tipo,
+  # `spec-wave:model:*`. O job é filtrado pelo `if:` e termina skipped, mas o RUN
+  # entra na fila de concurrency do mesmo jeito, e com `cancel-in-progress: false`
+  # o GitHub cancela o run que já estava PENDENTE para pôr o novo no lugar. Foi
+  # assim que um decompose enfileirado atrás de um generate-plan morreu cancelado
+  # em 1 segundo por causa de uma label sem relação nenhuma — a label de gatilho
+  # fica na issue, `labeled` não redispara com ela aplicada, e o fluxo trava sem
+  # nenhum sinal. Rotular o run inútil com um grupo único (`github.run_id`) o tira
+  # da fila sem afrouxar a serialização de quem realmente vai rodar.
+  group: >-
+    ${{ github.event.label.name == 'spec-wave:spec'
+    && format('spec-wave-item-{0}', github.event.issue.number)
+    || format('spec-wave-noop-{0}', github.run_id) }}
   cancel-in-progress: false
 
 jobs:
@@ -42,8 +56,11 @@ jobs:
         with:
           node-version: '24'
 
+      - name: Instala a CLI
+        run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
+
       - name: Generate spec.md
-        run: npx @spec-wave/cli@{{CLI_VERSION}} generate-spec --issue-number ${{ github.event.issue.number }}
+        run: spec-wave generate-spec --issue-number ${{ github.event.issue.number }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

package/src/templates/workflows/qa.yml

@@ -24,8 +24,12 @@ jobs:
         with:
           node-version: '24'
 
+      - name: Instala a CLI
+        run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
+
+
       - name: Move Feature to QA
-        run: npx @spec-wave/cli@{{CLI_VERSION}} qa --pr-number ${{ github.event.pull_request.number }}
+        run: spec-wave qa --pr-number ${{ github.event.pull_request.number }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           PROJECT_TOKEN: ${{ secrets.GH_PROJECT_TOKEN }}

package/src/templates/workflows/validate.yml

@@ -5,7 +5,21 @@ on:
     types: [labeled]
 
 concurrency:
-  group: spec-wave-validate-${{ github.event.issue.number }}
+  # Um run que NÃO vai fazer nada não pode disputar este grupo.
+  #
+  # `issues: [labeled]` dispara para QUALQUER label — prioridade, tipo,
+  # `spec-wave:model:*`. O job é filtrado pelo `if:` e termina skipped, mas o RUN
+  # entra na fila de concurrency do mesmo jeito, e com `cancel-in-progress: false`
+  # o GitHub cancela o run que já estava PENDENTE para pôr o novo no lugar. Foi
+  # assim que um decompose enfileirado atrás de um generate-plan morreu cancelado
+  # em 1 segundo por causa de uma label sem relação nenhuma — a label de gatilho
+  # fica na issue, `labeled` não redispara com ela aplicada, e o fluxo trava sem
+  # nenhum sinal. Rotular o run inútil com um grupo único (`github.run_id`) o tira
+  # da fila sem afrouxar a serialização de quem realmente vai rodar.
+  group: >-
+    ${{ github.event.label.name == 'spec-wave:ready'
+    && format('spec-wave-validate-{0}', github.event.issue.number)
+    || format('spec-wave-noop-{0}', github.run_id) }}
   cancel-in-progress: false
 
 jobs:
@@ -26,8 +40,11 @@ jobs:
         with:
           node-version: '24'
 
+      - name: Instala a CLI
+        run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
+
       - name: Validate spec and plan
-        run: npx @spec-wave/cli@{{CLI_VERSION}} validate --issue-number ${{ github.event.issue.number }}
+        run: spec-wave validate --issue-number ${{ github.event.issue.number }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           GITHUB_REPOSITORY: ${{ github.repository }}