@spec-wave/cli 0.21.0 → 0.24.0

package/src/commands/validate.mjs

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

package/src/config.mjs

@@ -11,17 +11,36 @@ export const PORTAL_URL = 'https://spec-wave.astratech.net.br';
 // O provider e o modelo escolhidos no `init` são persistidos em .spec-wave.json
 // (bloco `ai`) e lidos em runtime por src/lib/claude.mjs. Cada provider declara
 // o secret do GitHub Actions de onde a chave é lida.
+//
+// `value` é o que o usuário escolhe; `backend` é QUEM executa (src/agent/).
+// Os dois não coincidem: `anthropic` e `claude-oauth` rodam no mesmo backend e
+// diferem só na credencial — chave de API por token vs. token da assinatura.
+// Separar os campos evita que cada consumidor tenha que decorar essa relação.
 export const AI_PROVIDERS = [
   {
     value: 'anthropic',
+    backend: 'anthropic',
     label: 'Anthropic (API direta)',
     hint: 'Usa o secret ANTHROPIC_API_KEY',
     secret: 'ANTHROPIC_API_KEY',
     defaultModel: 'claude-sonnet-4-6',
     modelHint: 'ex.: claude-sonnet-4-6, claude-opus-4-1',
   },
+  {
+    // Mesmo backend do `anthropic`, credencial diferente: o token da assinatura
+    // Claude Pro/Max (`claude setup-token`), com escopo só de inferência. O
+    // consumo sai do limite do plano, não de crédito por token.
+    value: 'claude-oauth',
+    backend: 'anthropic',
+    label: 'Claude (assinatura Pro/Max via OAuth)',
+    hint: 'Usa o secret CLAUDE_CODE_OAUTH_TOKEN — gere com `claude setup-token`',
+    secret: 'CLAUDE_CODE_OAUTH_TOKEN',
+    defaultModel: 'claude-sonnet-4-6',
+    modelHint: 'ex.: claude-sonnet-4-6, claude-opus-4-1',
+  },
   {
     value: 'openrouter',
+    backend: 'openrouter',
     label: 'OpenRouter (multi-modelo)',
     hint: 'Usa o secret OPENROUTER_API_KEY',
     secret: 'OPENROUTER_API_KEY',
@@ -49,10 +68,12 @@ export const MODEL_LABEL_PREFIX = 'spec-wave:model:';
 // `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.
+// O mapa é POR BACKEND, não por provider, porque o que ele distingue é o
+// formato do id: a OpenRouter usa slug com "/" (anthropic/claude-opus-5) e a
+// 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. `anthropic` e `claude-oauth` compartilham o mesmo mapa
+// porque compartilham o backend.
 export const RECOMMENDED_MODEL_ALIASES = {
   openrouter: {
     opus: 'anthropic/claude-opus-5',
@@ -78,7 +99,17 @@ export const RECOMMENDED_MODEL_ALIASES = {
  * @returns {Record<string,string>}
  */
 export function recommendedModelAliases(provider) {
-  return RECOMMENDED_MODEL_ALIASES[provider] || RECOMMENDED_MODEL_ALIASES[DEFAULT_PROVIDER];
+  return RECOMMENDED_MODEL_ALIASES[providerBackend(provider)];
+}
+
+/**
+ * Backend que executa um provider (função PURA).
+ *
+ * @param {string} [value] valor de `ai.provider`
+ * @returns {'anthropic'|'openrouter'}
+ */
+export function providerBackend(value) {
+  return (getProvider(value) || getProvider(DEFAULT_PROVIDER)).backend;
 }
 
 // Quantas críticas seguidas podem reprovar a mesma issue antes de exigir revisão
@@ -372,6 +403,12 @@ export const LABEL_CRITIQUE_FAILED = 'spec-wave:critique-failed';
 export const LABEL_DECOMPOSED = 'spec-wave:decomposed';
 export const LABEL_DECOMPOSE_READY = 'spec-wave:decompose-ready';
 export const LABEL_NEEDS_HUMAN = 'spec-wave:needs-human';
+// Selo de que spec+plan passaram pelo `validate`. É o que distingue uma Feature
+// pronta de uma que só foi movida à mão para ✅ Ready.
+export const LABEL_PLAN_APPROVED = 'spec-wave:plan-approved';
+// Gatilhos que REGERAM documento: presentes na issue, indicam etapa pendente.
+export const LABEL_SPEC = 'spec-wave:spec';
+export const LABEL_PLAN = 'spec-wave:plan';
 // Achado GRAVE que o Tech Leader aceitou como risco conhecido. Fica na issue
 // depois que a crítica passa: sem ela, o risco aceito some da vista assim que a
 // rodada seguinte roda limpa, e ninguém mais sabe que houve uma decisão.
@@ -382,11 +419,11 @@ export const LABEL_RISK_ACCEPTED = 'spec-wave:risk-accepted';
 export const LABEL_CRITIQUE = 'spec-wave:critique';
 
 export const TRIGGER_LABELS = [
-  { name: 'spec-wave:spec',          color: 'BFD4F2', description: 'Gerar spec.md via GitHub Action'      },
-  { name: 'spec-wave:plan',          color: 'BFD4F2', description: 'Gerar plan.md via GitHub Action'      },
+  { name: LABEL_SPEC,                color: 'BFD4F2', description: 'Gerar spec.md via GitHub Action'      },
+  { name: LABEL_PLAN,                color: 'BFD4F2', description: 'Gerar plan.md via GitHub Action'      },
   { name: LABEL_CRITIQUE,            color: 'BFD4F2', description: 'Re-criticar o plan.md COMO ESTÁ, sem regerar' },
   { name: 'spec-wave:ready',         color: '0E8A16', description: 'Validar spec+plan e mover para Ready'  },
-  { name: 'spec-wave:plan-approved', color: '0E8A16', description: 'Spec+plan validados com sucesso'       },
+  { name: LABEL_PLAN_APPROVED,       color: '0E8A16', description: 'Spec+plan validados com sucesso'       },
   { name: LABEL_DECOMPOSE,           color: 'BFD4F2', description: 'Gerar/re-criticar o rascunho da decomposição (decomposition.md)' },
   { name: LABEL_DECOMPOSE_APPLY,     color: 'BFD4F2', description: 'Aplicar o decomposition.md revisado: criar Stories e Tasks' },
   { name: LABEL_DEV_AGENT,           color: '5319E7', description: 'Enfileira a issue para o dev-agent autônomo' },

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, WORK_ITEM_TYPES } 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,39 @@ 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).
  *

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

@@ -109,6 +109,9 @@ export function resolveAiConfig({ env = {}, fileAi = {}, action, labels = [], mo
 
   return {
     provider: meta.value,
+    // Quem executa. `anthropic` e `claude-oauth` caem no mesmo backend e
+    // diferem só na credencial — src/agent/ nunca vê essa distinção.
+    backend: meta.backend,
     model: rawModel.trim(),
     modelSource,
     labelAlias,
@@ -193,6 +196,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 +218,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);
     }
@@ -343,7 +362,7 @@ export async function generateDocument(systemPrompt, userContent, opts = {}) {
 // Extraída do generateDocument para o generateStructured usar a mesma contagem.
 function recordUsageEntry(opts, ai, { inputTokens, outputTokens, cost }) {
   if (!Array.isArray(opts.usage)) return;
-  const finalCost = cost === null && ai.provider === 'anthropic'
+  const finalCost = cost === null && ai.backend === 'anthropic'
     ? computeCost({ model: ai.model, inputTokens, outputTokens, pricing: ai.pricing })
     : cost;
   opts.usage.push({
@@ -491,7 +510,7 @@ async function generateViaEngine(
   systemPrompt, userContent, ai, { temperature, maxTokens, maxTurns, schema, strict, action, tools },
 ) {
   const result = await runAgent(userContent, {
-    provider: ai.provider,
+    provider: ai.backend,
     model: ai.model,
     systemPromptAppend: systemPrompt,
     // Sessão/usuário alimentam o agrupamento das traces no Langfuse. Sem
@@ -520,7 +539,14 @@ async function generateViaEngine(
     if (result.structured === null || result.structured === undefined) {
       const err = new Error(
         `O modelo ${ai.model} não devolveu a saída estruturada "${schema.name}" ` +
-        `(subtype=${result.resultSubtype}).`
+        `(subtype=${result.resultSubtype}).` +
+        (result.resultSubtype === 'error_max_structured_output_retries'
+          // Subtype só do backend anthropic: o CLI repetiu o turno e a saída
+          // nunca bateu com o schema. Repetir tende a resolver; se insistir, o
+          // modelo é que não dá conta do contrato.
+          ? ' O Claude Code esgotou as tentativas de casar a resposta com o schema —' +
+            ' se repetir, aponte `ai.models.critique` para um modelo mais forte.'
+          : '')
       );
       err.transient = true; // repetir a mesma requisição costuma resolver
       throw err;
@@ -530,9 +556,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 +566,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/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "spec-wave",
   "displayName": "Spec Wave",
-  "version": "0.21.0",
+  "version": "0.24.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*).