@spec-wave/cli 0.21.0 → 0.23.0

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.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."
 

package/src/templates/skill/SKILL.md

@@ -227,7 +227,7 @@ Sem flags. Roda um checklist de diagnóstico no repositório atual: token GitHub
 |----------|------|-----------|
 | `<feature>` | string (obrigatório) | Número da issue da **Feature**, ex.: `12` ou `#12`. Argumento posicional. |
 
-> Lista as Stories da Feature em **ordem topológica** pelas dependências (linha `Depende de: #N` no corpo + relação nativa *blocked by*, mescladas), com a Etapa atual de cada uma no board. Avisa sobre **ciclos de dependência** (essas Stories ficam fora da ordem — corrija as linhas `Depende de`) e sobre **dependências fora de ordem** (Story já em Desenvolvimento+ dependendo de outra que não está Done). Use antes de escolher qual Story implementar.
+> **Sem argumento**, monta o mapa de TODAS as Features abertas fora de 🎉 Done num grafo só (conjunto vindo do board), com a Feature de cada Story ao lado — nesse escopo a dependência entre Features entra na ordenação. Com `<feature>`, lista as Stories da Feature em **ordem topológica** pelas dependências (linha `Depende de: #N` no corpo + relação nativa *blocked by*, mescladas), com a Etapa atual de cada uma no board. Dependências para **fora da Feature** não entram na ordenação (não há como saber onde a Story de outra Feature entra nesta sequência), mas aparecem em **"Bloqueadas por fora desta Feature"**, com o estado de cada bloqueadora. Avisa sobre **ciclos de dependência** (essas Stories ficam fora da ordem — corrija as linhas `Depende de`) e sobre **dependências fora de ordem** (Story já em Desenvolvimento+ dependendo de outra que não está Done). Use antes de escolher qual Story implementar.
 
 ### `@spec-wave/cli task <start|done> <n>` — transições de Task no board (comando LOCAL)
 | Flag/Arg | Tipo | Descrição |
@@ -316,7 +316,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`.
 
@@ -606,7 +606,7 @@ Valida que spec.md e plan.md estão completos e a Feature pode avançar.
    gh issue edit <número> --add-label "spec-wave:ready"
    ```
 2. Informe: "Validação iniciada. O workflow verificará se spec.md e plan.md contêm todas as seções obrigatórias."
-3. Se a validação falhar, o workflow comentará os problemas na issue e adicionará automaticamente `spec-wave:spec`. Informe o usuário para corrigir e tentar novamente.
+3. Se a validação falhar, o workflow comentará os problemas na issue e **não aplicará label de gatilho nenhuma**. Informe o usuário para corrigir e reaplicar `spec-wave:ready`. Falha por título de seção vem com "encontrei X, esperava Y" — renomear resolve. `spec-wave:spec` só se o documento precisar ser REGERADO: ela **sobrescreve** o `spec.md` revisado.
 4. **Se a issue tiver `spec-wave:critique-failed` ou `spec-wave:needs-human`**, a validação falha de imediato — são portões humanos: a crítica apontou contradições graves (comentário 🔎 na issue) ou esgotou as tentativas. Nesses casos a Feature **não** é devolvida para a etapa de spec; siga o fluxo da seção *Crítica adversarial* (corrigir a superfície certa → remover a label → re-aplicar `spec-wave:ready`).
 5. Se passar, oriente: "Feature validada! Mova o card para **✅ Ready** e use `/spec-wave decompose <número>` para gerar o **rascunho** das Stories (nada é criado ainda)."
 
@@ -636,7 +636,7 @@ Para qualquer outro tipo (Spike, Bug, Story, Task, …) o Action **recusa** e co
    gh issue edit <número> --add-label "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. A issue pai e as Stories/Tasks criadas entram no board na Etapa **✅ Ready** (Status Todo; a Etapa nunca retrocede — itens já adiante não são tocados). As Stories trazem a linha `Depende de: #N` (+ relação *blocked by*) — use `npx @spec-wave/cli@latest order <número>` para ver a ordem de execução.
+5. Após a aplicação, as issues filhas aparecem como comentário na issue pai. A issue pai e as Stories/Tasks criadas entram no board na Etapa **✅ Ready** (Status Todo; a Etapa nunca retrocede — itens já adiante não são tocados). As Stories trazem a linha `Depende de: #N` (+ relação *blocked by*) — use `npx @spec-wave/cli@latest order <número>` para ver a ordem de execução. Se a issue pai tiver **milestone**, as filhas nascem nele; sem milestone no pai, nascem sem.
 6. A issue recebe a label `spec-wave:decomposed` (guard de idempotência): rodar de novo **não** duplica as issues. Para forçar um re-decompose, siga a seção *Guard de idempotência*.
 
 > **Nunca pule a etapa 1** aplicando `spec-wave:decompose-apply` direto: sem `decomposition.md` o Action falha pedindo o rascunho.