@spec-wave/cli 0.20.0 → 0.23.0

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, STAGE_DONE } from '../config.mjs';
 import { loadConfig } from './project-root.mjs';
 
 /**
@@ -116,6 +116,78 @@ export function resolveStageName(input) {
   return { stage: null, error: `Etapa "${input}" não existe. Use uma destas: ${list()}.` };
 }
 
+/**
+ * Índice do board por número de issue (função PURA).
+ *
+ * @param {Array<{number:number}>} items saída de listProjectItems
+ * @returns {Map<number, object>}
+ */
+export function indexBoardItems(items) {
+  return new Map((items || []).filter(i => i?.number).map(i => [i.number, i]));
+}
+
+/**
+ * As Features que ainda têm trabalho (função PURA).
+ *
+ * "Ainda tem trabalho" = issue aberta e Etapa diferente de 🎉 Done. É este o
+ * conjunto do `order` sem argumento: o mapa de quem depende de quem quando o
+ * trabalho de uma onda inteira está espalhado por várias Features.
+ *
+ * O tipo sai do campo "Work Item Type", com FALLBACK no prefixo do título: o
+ * campo ficou vazio em todo item criado pelo apply até a v0.21.0, e um board com
+ * esse buraco não pode virar um mapa vazio em silêncio.
+ *
+ * @param {Array<object>} items saída de listProjectItems
+ * @returns {Array<object>} Features, em ordem crescente de número
+ */
+export function selectOpenFeatures(items) {
+  return (items || [])
+    .filter(i => i?.number
+      && String(i.state || '').toUpperCase() !== 'CLOSED'
+      && (i.fields?.['Work Item Type'] === 'Feature' || /^\s*\[FEATURE\]/i.test(i.title || ''))
+      && i.fields?.Etapa !== STAGE_DONE)
+    .sort((a, b) => a.number - b.number);
+}
+
+/**
+ * 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 +200,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 +247,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 +265,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/bug-doc.mjs

@@ -49,3 +49,74 @@ export function findMissingSections(content, sections) {
   const text = String(content || '');
   return (sections || []).filter(section => !text.includes(`# ${section}`));
 }
+
+/**
+ * Títulos presentes no documento (função PURA).
+ */
+export function listHeadings(content) {
+  return [...String(content || '').matchAll(/^#{1,6}[ \t]+(.+?)[ \t]*$/gm)].map(m => m[1].trim());
+}
+
+// Comparação tolerante: sem acento, sem pontuação, caixa única.
+function normalizeHeading(value) {
+  return String(value ?? '')
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .replace(/[^\p{Letter}\p{Number}]+/gu, ' ')
+    .trim()
+    .toLowerCase();
+}
+
+function bigrams(value) {
+  const s = normalizeHeading(value).replace(/ /g, '');
+  const out = new Set();
+  for (let i = 0; i < s.length - 1; i++) out.add(s.slice(i, i + 2));
+  return out;
+}
+
+/**
+ * Semelhança entre dois títulos, 0..1 (função PURA — coeficiente de Dice).
+ */
+export function headingSimilarity(a, b) {
+  const A = bigrams(a);
+  const B = bigrams(b);
+  if (A.size === 0 || B.size === 0) return normalizeHeading(a) === normalizeHeading(b) ? 1 : 0;
+  let comuns = 0;
+  for (const g of A) if (B.has(g)) comuns += 1;
+  return (2 * comuns) / (A.size + B.size);
+}
+
+// Abaixo disto são dois títulos diferentes, não um errado. "Rollout e
+// Monitoramento" × "Rollback e Monitoramento" fica bem acima; "Riscos" ×
+// "Rollback e Monitoramento", bem abaixo.
+const SIMILARIDADE_MINIMA = 0.6;
+
+/**
+ * O que falta E o que existe no lugar (função PURA).
+ *
+ * `findMissingSections` só sabe dizer o que não achou, e foi isso que fez uma
+ * Feature ser reprovada por ter escrito "# Rollout e Monitoramento" no lugar de
+ * "# Rollback e Monitoramento" — com todo o conteúdo certo embaixo. A mensagem
+ * dizia "seção ausente" e o humano tinha que caçar a diferença de uma palavra.
+ *
+ * Só sugere um título que NÃO satisfaz nenhuma seção obrigatória: senão o
+ * "Riscos" legítimo do documento vira sugestão para o "Rollback" que falta.
+ *
+ * @returns {Array<{section: string, found: string|null}>}
+ */
+export function describeMissingSections(content, sections) {
+  const faltando = findMissingSections(content, sections);
+  if (faltando.length === 0) return [];
+  const presentes = (sections || []).filter(s => !faltando.includes(s)).map(normalizeHeading);
+  const candidatos = listHeadings(content)
+    .filter(h => !presentes.includes(normalizeHeading(h)));
+  return faltando.map(section => {
+    let melhor = null;
+    let score = SIMILARIDADE_MINIMA;
+    for (const h of candidatos) {
+      const s = headingSimilarity(h, section);
+      if (s >= score) { score = s; melhor = h; }
+    }
+    return { section, found: melhor };
+  });
+}

package/src/lib/claude.mjs

@@ -193,6 +193,21 @@ export function isTransientProviderError(err) {
     .test(err.message || '');
 }
 
+/**
+ * O teto de turnos merece UMA repetição? (função PURA)
+ *
+ * Só quando o erro se classificou como exploração (ver MaxTurnsError): aí a
+ * falha é variância entre execuções, e a repetição costuma custar uma fração do
+ * run que falhou. Loop degenerado continua sem retry — repetir o determinístico
+ * foi o que custou 55 minutos de Action.
+ *
+ * UMA, e não `attempts`: o ganho observado está na segunda tentativa; da
+ * terceira em diante o padrão vira "gastar caro para confirmar o óbvio".
+ */
+export function shouldRetryMaxTurns(err) {
+  return Boolean(err?.maxTurns && err.exploration);
+}
+
 export async function withRetry(label, fn, { attempts = RETRY_ATTEMPTS, baseMs = RETRY_BASE_MS } = {}) {
   let lastErr;
   for (let attempt = 1; attempt <= attempts; attempt++) {
@@ -200,11 +215,12 @@ export async function withRetry(label, fn, { attempts = RETRY_ATTEMPTS, baseMs =
       return await fn();
     } catch (err) {
       lastErr = err;
-      if (attempt === attempts || !isTransientProviderError(err)) break;
+      const repeteTeto = attempt === 1 && shouldRetryMaxTurns(err);
+      if (attempt === attempts || (!isTransientProviderError(err) && !repeteTeto)) break;
       const delayMs = baseMs * 2 ** (attempt - 1); // 2s, 4s, 8s…
       console.warn(
-        `${label}: falha transitória na tentativa ${attempt}/${attempts} (${err.message}) — ` +
-        `repetindo em ${delayMs / 1000}s.`
+        `${label}: ${repeteTeto ? 'teto de turnos gasto explorando' : 'falha transitória'} na ` +
+        `tentativa ${attempt}/${attempts} (${err.message}) — repetindo em ${delayMs / 1000}s.`
       );
       await sleep(delayMs);
     }
@@ -530,9 +546,9 @@ async function generateViaEngine(
 
   const text = stripReasoning(result.outputText || '');
   if (!text) {
-    // Teto de turnos tem causa e remédio próprios, e NÃO é transitório: o
-    // modelo gastou todos os turnos em tool calls sem nunca escrever o
-    // documento, e repetir reproduz isso. Ver MaxTurnsError.
+    // Teto de turnos tem causa e remédio próprios. Só é repetível quando as
+    // tool calls foram de EXPLORAÇÃO (variância); loop degenerado não é.
+    // Quem classifica é o próprio erro. Ver MaxTurnsError.
     if (result.resultSubtype === 'error_max_turns') {
       throw new MaxTurnsError({
         provider: ai.provider,
@@ -540,6 +556,7 @@ async function generateViaEngine(
         turns: result.numTurns,
         action: action || null,
         toolCalls: result.toolCalls || [],
+        toolSignatures: result.toolSignatures || [],
       });
     }
     const err = new Error(

package/src/lib/decomposition-doc.mjs

@@ -20,7 +20,7 @@
 //   ## Story 1 — <título curto>
 //
 //   **User story:** Como <perfil>, quero <objetivo>, para <benefício>
-//   **Depende de:** Story 1, Story 2          (ou "—" para nenhuma)
+//   **Depende de:** Story 1, #412             (ou "—" para nenhuma)
 //
 //   <corpo livre, multi-linha>
 //
@@ -162,6 +162,16 @@ function normalizeDependsOn(dependsOn, index) {
     .sort((a, b) => a - b);
 }
 
+// Dependências para FORA da Feature: números de issue que já existem.
+//
+// A regra "só aponta para trás" NÃO se aplica a elas — ela existe para que a
+// ordem de criação do apply seja topologicamente válida, e uma issue que já
+// existe não é criada por este apply. O que vale aqui é ser inteiro positivo.
+function normalizeDependsOnIssues(list) {
+  if (!Array.isArray(list)) return [];
+  return [...new Set(list.filter(n => Number.isInteger(n) && n > 0))].sort((a, b) => a - b);
+}
+
 /**
  * Renderiza o decomposition.md (função PURA — testável).
  *
@@ -223,12 +233,16 @@ export function renderDecompositionDoc({
     (stories || []).forEach((story, i) => {
       blocks.push(`## Story ${i + 1} — ${flatten(story?.title) || '(sem título)'}`);
       const deps = normalizeDependsOn(story?.dependsOn, i);
+      // Irmãs primeiro (por índice), depois as externas (por número): a saída é
+      // canônica, então duas escritas do mesmo conteúdo dão o mesmo arquivo.
+      const externas = normalizeDependsOnIssues(story?.dependsOnIssues);
+      const refs = [...deps.map(d => `Story ${d + 1}`), ...externas.map(n => `#${n}`)];
       // As DUAS linhas de campo saem SEMPRE, seguidas de linha em branco: é essa
       // linha em branco que impede um corpo começando com "**Depende de:** …" de
       // ser confundido com o campo.
       const campos = [
         `**User story:** ${flatten(story?.userStory) || '—'}`,
-        `**Depende de:** ${deps.length ? deps.map(d => `Story ${d + 1}`).join(', ') : '—'}`,
+        `**Depende de:** ${refs.length ? refs.join(', ') : '—'}`,
       ];
       const linhaIssue = issueLine(story);
       if (linhaIssue) campos.push(linhaIssue);
@@ -276,28 +290,62 @@ function requireTitle(value, anchor) {
 // "Story 1, Story 3" → [0, 2]. Linha ausente ou "—" → []. Referência a si mesma
 // ou a uma story POSTERIOR é erro: num arquivo editado à mão, filtrar em
 // silêncio (como se fazia com o JSON do modelo) esconderia o engano do humano.
+// Só separadores e conjunções podem sobrar depois de extrair as referências.
+// Sem esta checagem, "**Depende de:** #12 no sistema legado" viraria "depende da
+// issue 12" e a prosa sumiria em silêncio — o erro que este parser existe para
+// não cometer.
+const DEPENDS_LEFTOVER_RE = /^[\s,;+&/–—-]*(?:\b(?:e|and)\b[\s,;+&/–—-]*)*$/i;
+
+/**
+ * Interpreta o valor de "**Depende de:**" (função PURA).
+ *
+ * Duas formas convivem na mesma linha, e cada uma diz uma coisa diferente:
+ *  • `Story N` — irmã, no MESMO documento, sempre para trás (é o que mantém a
+ *    ordem de criação do apply topologicamente válida);
+ *  • `#N` — issue que JÁ existe, de qualquer Feature. Sem ela, tudo que cruza a
+ *    fronteira da Feature vivia na prosa, e nenhuma automação enxergava.
+ *
+ * @returns {{ siblings: number[], issues: number[] }} siblings 0-based
+ */
 function parseDependsValue(raw, index, anchor) {
-  if (raw === null || raw === undefined) return [];
+  if (raw === null || raw === undefined) return { siblings: [], issues: [] };
   const value = raw.trim();
-  if (!value || EMPTY_VALUE_RE.test(value)) return [];
-  const matches = [...value.matchAll(/story[ \t]*(\d+)/gi)];
-  if (matches.length === 0) {
+  if (!value || EMPTY_VALUE_RE.test(value)) return { siblings: [], issues: [] };
+
+  const storyMatches = [...value.matchAll(/story[ \t]*(\d+)/gi)];
+  const issueMatches = [...value.matchAll(/#(\d+)/g)];
+  if (storyMatches.length === 0 && issueMatches.length === 0) {
+    throw invalid(
+      `não entendi "**Depende de:** ${value}" em ${anchor} — use "Story 1", "#412" ou "—"`
+    );
+  }
+  const resto = value
+    .replace(/story[ \t]*\d+/gi, '')
+    .replace(/#\d+/g, '');
+  if (!DEPENDS_LEFTOVER_RE.test(resto)) {
     throw invalid(
-      `não entendi "**Depende de:** ${value}" em ${anchor} — use "Story 1, Story 2" ou "—"`
+      `não entendi "**Depende de:** ${value}" em ${anchor} — sobrou "${resto.trim()}". ` +
+      'Use só referências ("Story 1, #412") ou "—"'
     );
   }
-  const out = [];
-  for (const m of matches) {
+
+  const siblings = [];
+  for (const m of storyMatches) {
     const n = parseInt(m[1], 10);
     if (n < 1 || n - 1 >= index) {
       throw invalid(
         `${anchor} depende de "Story ${n}", que não é uma Story anterior a ela — ` +
-        'dependências só apontam para trás'
+        'dependências entre irmãs só apontam para trás (para outra Feature, use "#<issue>")'
       );
     }
-    if (!out.includes(n - 1)) out.push(n - 1);
+    if (!siblings.includes(n - 1)) siblings.push(n - 1);
+  }
+  const issues = [];
+  for (const m of issueMatches) {
+    const n = parseInt(m[1], 10);
+    if (n > 0 && !issues.includes(n)) issues.push(n);
   }
-  return out.sort((a, b) => a - b);
+  return { siblings: siblings.sort((a, b) => a - b), issues: issues.sort((a, b) => a - b) };
 }
 
 // Tasks não têm campos de gramática além do título — só a linha `**Issue:** #N`
@@ -352,7 +400,8 @@ function splitStorySection(lines, anchor) {
  * Interpreta o decomposition.md (função PURA — testável).
  *
  * Devolve exatamente a shape que o loop de criação de issues consome
- * (`stories[].{title,userStory,body,dependsOn,tasks[]}`, com dependsOn 0-based),
+ * (`stories[].{title,userStory,body,dependsOn,dependsOnIssues,tasks[]}`, com
+ * dependsOn 0-based entre irmãs e dependsOnIssues em números de issue),
  * mais os metadados do marcador e a âncora estável de cada item ("Story 3",
  * "Task 3.2") — é a âncora que a crítica cita no comentário da issue.
  *
@@ -473,7 +522,10 @@ export function parseDecompositionDoc(markdown) {
         userStory,
         body,
         issue,
-        dependsOn: parseDependsValue(depends, doc.stories.length, anchor),
+        ...(() => {
+          const { siblings, issues } = parseDependsValue(depends, doc.stories.length, anchor);
+          return { dependsOn: siblings, dependsOnIssues: issues };
+        })(),
         tasks: [],
       });
       continue;

package/src/lib/dependencies.mjs

@@ -44,8 +44,14 @@ export function parseDependencies(body) {
 
 /**
  * Ordena Stories topologicamente pelas dependências (Kahn). Estável: entre as
- * Stories liberadas ao mesmo tempo, vence a de menor number. Dependências que
- * apontam para fora do conjunto (ex.: issue externa) são ignoradas.
+ * Stories liberadas ao mesmo tempo, vence a de menor number.
+ *
+ * Dependência para FORA do conjunto (uma Story de outra Feature) não participa
+ * da ordenação — sem ela no conjunto não há como saber onde entra —, mas deixou
+ * de ser DESCARTADA: volta em `external`, para o chamador mostrar quem está
+ * bloqueado por fora. Antes ela era lida, filtrada aqui e ignorada de novo no
+ * aviso de fora-de-ordem: o dado entrava e sumia sem nenhuma mensagem, que é
+ * pior do que não aceitá-lo.
  *
  * Contrato: NUNCA lança. Retorna sempre `{ order, cycle }`:
  *  • sem ciclo → order = todos os numbers em ordem de execução, cycle = [];
@@ -54,15 +60,19 @@ export function parseDependencies(body) {
  * O chamador decide se trata cycle.length > 0 como erro.
  *
  * @param {Array<{ number: number, dependsOn: number[] }>} stories
- * @returns {{ order: number[], cycle: number[] }}
+ * @returns {{ order: number[], cycle: number[], external: Map<number, number[]> }}
+ *          external: number da Story → dependências fora do conjunto
  */
 export function orderStories(stories) {
   const known = new Set(stories.map(s => s.number));
   // indegree = quantas dependências INTERNAS ainda não resolvidas.
   const indegree = new Map();
   const dependents = new Map(); // number → numbers que dependem dele
+  const external = new Map();
   for (const s of stories) {
     const deps = (s.dependsOn || []).filter(d => known.has(d) && d !== s.number);
+    const fora = (s.dependsOn || []).filter(d => !known.has(d) && d !== s.number);
+    if (fora.length > 0) external.set(s.number, fora.sort((a, b) => a - b));
     indegree.set(s.number, deps.length);
     for (const d of deps) {
       if (!dependents.has(d)) dependents.set(d, []);
@@ -88,7 +98,7 @@ export function orderStories(stories) {
     .filter(([, deg]) => deg > 0)
     .map(([n]) => n)
     .sort((a, b) => a - b);
-  return { order, cycle };
+  return { order, cycle, external };
 }
 
 /**

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.20.0",
+  "version": "0.23.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/plugin/skills/decompose/SKILL.md

@@ -64,7 +64,7 @@ spec-wave:decompose-apply
    ```
    Aplicar essa label **é** a aprovação humana — não há nova crítica.
 
-5. Após a aplicação, as issues filhas aparecem como comentário na issue pai. Pai e filhas entram no board em **✅ Ready** (Status Todo; a Etapa nunca retrocede — itens já adiante não são tocados). As Stories trazem `Depende de: #N` — use a skill **order** para ver a ordem de execução.
+5. Após a aplicação, as issues filhas aparecem como comentário na issue pai. Pai e filhas entram no board em **✅ Ready** (Status Todo; a Etapa nunca retrocede — itens já adiante não são tocados). As Stories trazem `Depende de: #N` — use a skill **order** para ver a ordem de execução. Se a issue pai tiver **milestone**, as filhas nascem nele (a entrega da Story pertence à release da Feature); sem milestone no pai, nascem sem.
 
 6. A issue recebe `spec-wave:decomposed` (guard de idempotência): rodar de novo **não** duplica as issues.
 
@@ -93,7 +93,7 @@ Corpo técnico.
 **Ao editar à mão:**
 
 - a **posição** manda, não o número escrito — inserir uma Story no meio sem renumerar funciona
-- `**Depende de:**` usa referências **1-based** (`Story 1, Story 3`) ou `—`; apontar para si mesma ou para frente é **erro**, não filtro silencioso
+- `**Depende de:**` aceita **irmãs** (`Story 1, Story 3`, 1-based, só para trás — apontar para si mesma ou para frente é **erro**, não filtro silencioso) e **issues de outras Features** (`#412`, que precisam JÁ existir); as duas formas convivem na mesma linha (`Story 1, #412`), e `—` significa nenhuma
 - o corpo aceita markdown livre (`## Backend`, cercas de código) — só `## Story N` e `### Task N.M` são estrutura
 - **para gerar outro rascunho do zero:** apague o arquivo e reaplique `spec-wave:decompose`
 
@@ -114,4 +114,4 @@ Depois **apague/feche as sub-issues antigas** (senão a detecção por sub-issue
 
 ## Dependências entre Stories
 
-O `decompose` grava `Depende de: #N, #M` no corpo das Stories e cria a relação nativa *blocked by*. Isso alimenta as skills **order** e **implement**. **Não apague essa linha** ao editar o corpo de uma Story; para mudar dependências, edite a linha (e/ou a relação *blocked by*).
+O `decompose` grava `Depende de: #N, #M` no corpo das Stories e cria a relação nativa *blocked by* — para irmãs e para as issues de outras Features referenciadas com `#N` no rascunho (a issue precisa existir: o apply reprova o rascunho ANTES de criar qualquer coisa se não conseguir lê-la). Isso alimenta as skills **order** e **implement**. **Não apague essa linha** ao editar o corpo de uma Story; para mudar dependências, edite a linha (e/ou a relação *blocked by*).

package/src/plugin/skills/order/SKILL.md

@@ -11,12 +11,15 @@ allowed-tools:
 Comando **local**:
 
 ```bash
-npx @spec-wave/cli@latest order <feature>
+npx @spec-wave/cli@latest order <feature>   # uma Feature
+npx @spec-wave/cli@latest order             # o mapa de todas as Features com trabalho
 ```
 
 | Arg | Descrição |
 |-----|-----------|
-| `<feature>` | Número da issue da **Feature**, ex.: `12` ou `#12`. Posicional, obrigatório. |
+| `<feature>` | Número da issue da **Feature**, ex.: `12` ou `#12`. Posicional, **opcional**. |
+
+**Sem argumento**, o conjunto vem do **board** (não dos arquivos): todas as Features abertas fora de 🎉 Done, com as Stories de todas num **grafo só** e a Feature de cada uma ao lado. É o modo para responder "por onde os devs pegam agora" quando o trabalho está espalhado por várias Features — nesse escopo, dependência entre Features deixa de ser "externa" e entra na ordenação.
 
 **Contexto:** leia `.spec-wave.json` (Read). Ausente → skill **setup**.
 
@@ -25,11 +28,12 @@ npx @spec-wave/cli@latest order <feature>
 - As Stories da Feature em **ordem topológica** pelas dependências — a linha `Depende de: #N` no corpo **mesclada** com a relação nativa *blocked by* do GitHub
 - A **Etapa atual** de cada Story no board
 - Avisos de **ciclo de dependência** — essas Stories ficam **fora da ordem**; corrija as linhas `Depende de:`
-- Avisos de **dependência fora de ordem** — Story já em 🚧 Desenvolvimento ou além dependendo de outra que não está em 🎉 Done
+- Avisos de **dependência fora de ordem** — Story já em 🚧 Desenvolvimento ou além dependendo de outra que não está em 🎉 Done (no modo de uma Feature, também quando a bloqueadora é de **outra** Feature e continua aberta)
+- **Bloqueadas por fora desta Feature** (modo de uma Feature) — dependências `#N` que não entram na ordenação porque a Story bloqueadora não está no conjunto, com o estado de cada uma. No modo sem argumento essa seção lista só o que ficou fora do board (Story concluída, Feature em Done, outro board)
 
 ## Passos
 
-1. Rode o comando para a Feature.
+1. Rode o comando para a Feature — ou **sem argumento** quando a pergunta for sobre a onda inteira, não sobre uma Feature.
 2. Apresente a ordem ao usuário, marcando o que já está concluído e o que está pendente.
 3. **Se houver ciclo**, isso é bloqueante para a skill **implement** no modo Feature (o comando aborta com exit 1). Ajude a quebrar o ciclo editando as linhas `Depende de:` nos corpos das Stories.
 4. **Se houver dependência fora de ordem**, aponte o risco ao usuário antes de seguir.

package/src/plugin/skills/ready/SKILL.md

@@ -24,7 +24,7 @@ Verifica se `spec.md` e `plan.md` contêm todas as seções obrigatórias e se n
 
 3. Informe: "Validação iniciada. O workflow verifica se `spec.md` e `plan.md` contêm todas as seções obrigatórias."
 
-4. **Se a validação falhar por conteúdo**, o workflow comenta os problemas na issue e adiciona automaticamente `spec-wave:spec`. Oriente o usuário a corrigir e tentar de novo.
+4. **Se a validação falhar por conteúdo**, o workflow comenta os problemas na issue e **não aplica nenhuma label de gatilho**. Oriente o usuário a corrigir e reaplicar `spec-wave:ready`. Quando o problema é só o título de uma seção, o comentário já diz qual título encontrou e qual esperava — renomear resolve. Só sugira `spec-wave:spec` se o documento precisar mesmo ser REGERADO: essa label **sobrescreve** o `spec.md`, inclusive o que foi revisado à mão.
 
 5. **Se passar:** "Feature validada! Mova o card para **✅ Ready** e use a skill **decompose** para gerar o **rascunho** das Stories — nada é criado ainda."