@spec-wave/cli 0.20.0 → 0.23.0

package/bin/spec-wave.mjs

@@ -263,8 +263,8 @@ program
 
 program
   .command('order')
-  .description('Ordena as Stories de uma Feature pelas dependências (topológica)')
-  .argument('<feature>', 'Número da issue da Feature, ex.: 12 ou #12')
+  .description('Ordena as Stories pelas dependências (topológica). Sem argumento, o mapa de todas as Features com trabalho')
+  .argument('[feature]', 'Número da issue da Feature, ex.: 12 ou #12. Omitido: todas as Features abertas fora de 🎉 Done')
   .action(async (feature) => {
     const { order } = await import('../src/commands/order.mjs');
     await order({ feature }).catch(err => { console.error(err.message); process.exit(1); });

package/package.json

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

package/src/agent/anthropic-agent.mjs

@@ -25,7 +25,7 @@
 import path from 'node:path';
 import { withTrace, startObservation, updateSpan, endObservation } from './tracing.mjs';
 import { ENV_FILE_PATTERN } from './tools.mjs';
-import { summarizeToolCalls } from './errors.mjs';
+import { summarizeToolCalls, toolSignature } from './errors.mjs';
 import { TruncatedOutputError } from './errors.mjs';
 
 const DEFAULT_TOOLS = ['Read', 'Glob', 'Grep'];
@@ -72,6 +72,7 @@ export async function runAnthropicAgent(prompt, options) {
     // Simétrico ao backend openrouter: sem isto, um run que estoura o teto de
     // turnos não deixa registro do que o modelo esteve fazendo.
     toolCalls: [],
+    toolSignatures: [],
   };
   const quiet = options.quiet !== false;
 
@@ -159,6 +160,7 @@ export async function runAnthropicAgent(prompt, options) {
               }
 
               runResult.toolCalls.push(input.tool_name);
+              runResult.toolSignatures.push(toolSignature(input.tool_name, input.tool_input));
               if (options.verbose) {
                 console.log(`\n[Tool] ${input.tool_name}(${JSON.stringify(input.tool_input)})`);
               }

package/src/agent/errors.mjs

@@ -45,34 +45,80 @@ export class TruncatedOutputError extends Error {
   }
 }
 
+/**
+ * Assinatura de uma tool call: nome + ALVO (função PURA).
+ *
+ * `Read×59` não distingue "leu 59 arquivos diferentes" de "leu o mesmo arquivo
+ * 59 vezes", e essas duas situações pedem remédios opostos. O alvo é o que
+ * separa as duas, e é o único dado do input que entra aqui — nada de conteúdo.
+ */
+export function toolSignature(name, input) {
+  const alvo = input && typeof input === 'object'
+    ? input.file_path ?? input.path ?? input.pattern ?? input.query ?? input.command ?? null
+    : null;
+  return alvo ? `${name}:${String(alvo)}` : String(name);
+}
+
+/**
+ * O modelo estava EXPLORANDO (e não preso num loop)? (função PURA)
+ *
+ * Explorar = chamadas majoritariamente distintas: leu muitos arquivos, varreu
+ * muitos padrões e o orçamento acabou antes de escrever. Isso VARIA entre
+ * execuções — repetir a mesma requisição costuma passar. Loop degenerado é o
+ * contrário: a mesma chamada repetida, que repetir só encarece.
+ *
+ * Amostra pequena não sustenta nenhuma das duas conclusões, e o default é o
+ * conservador (não repetir).
+ */
+export function looksLikeExploration(signatures = []) {
+  if (!Array.isArray(signatures) || signatures.length < 4) return false;
+  const distintas = new Set(signatures).size;
+  return distintas / signatures.length >= 0.5;
+}
+
 // Teto de turnos esgotado: o modelo respondeu com tool calls em TODOS os turnos
-// e nunca produziu o documento. Como o truncamento acima, NÃO é transitório —
-// repetir a mesma requisição dá a mesma perambulação, só que mais cara.
+// e nunca produziu o documento.
+//
+// NÃO é uma falha só, são duas, e a distinção é o que decide se repetir vale:
+//
+//  • LOOP DEGENERADO (a mesma chamada de novo e de novo) é determinístico —
+//    repetir custou 55 minutos de Action num caso real: três tentativas de 25
+//    turnos (4min → 19min → 32min) para a mesma falha, que devia ter aparecido
+//    na primeira. Aqui não se repete: troca-se o modelo ou sobe-se o teto.
 //
-// Marcá-lo como transitório custou 55 minutos de Action num caso real: três
-// tentativas de 25 turnos (4min → 19min → 32min) para a mesma falha
-// determinística, que devia ter aparecido na primeira.
+//  • EXPLORAÇÃO (chamadas distintas: Read×59 em 59 arquivos, Glob×20) é
+//    VARIÂNCIA, não limite estrutural — o orçamento acabou antes de escrever.
+//    Tratar isso como determinístico mandava trocar de modelo por nada: em
+//    quatro ocorrências reais, três reaplicações da MESMA label no MESMO modelo
+//    passaram na segunda tentativa, uma delas depois de um run de 20min46s que
+//    uma repetição de ~2min teria evitado.
 export class MaxTurnsError extends Error {
-  constructor({ provider, model, turns, action, toolCalls = [] }) {
-    // O que o modelo ficou fazendo é a informação que decide o remédio: muitas
-    // leituras distintas sugerem teto baixo; a mesma chamada repetida é loop
-    // degenerado, e aí subir o teto só encarece.
+  constructor({ provider, model, turns, action, toolCalls = [], toolSignatures = [] }) {
     const resumo = toolCalls.length > 0
       ? ` Ferramentas mais chamadas: ${summarizeToolCalls(toolCalls)}.`
       : '';
+    const exploracao = looksLikeExploration(toolSignatures);
+    const remedio = exploracao
+      ? 'As chamadas são majoritariamente DISTINTAS — o modelo gastou o orçamento explorando, ' +
+        'o que varia entre execuções. Uma repetição costuma bastar (a CLI já faz UMA, ' +
+        'automaticamente); se insistir, suba `maxTurns` no prompt em vez de trocar o modelo.'
+      : 'As chamadas se REPETEM — é loop degenerado, e repetir reproduz a mesma perambulação ' +
+        'mais cara. Troque o modelo (por `ai.models` ou pela label ' +
+        '`spec-wave:model:<apelido>`) ou suba o teto de turnos.';
     super(
       `O modelo esgotou o teto de ${turns} turnos sem produzir o documento ` +
       `(${provider} · ${model}${action ? ` · ação=${action}` : ''}): respondeu com chamadas de ` +
-      `ferramenta em todos eles.${resumo} ` +
-      'Repetir não ajuda — o erro é determinístico. Ou o modelo não fecha o loop de ' +
-      'ferramentas nesta tarefa (troque-o, por `ai.models` ou pela label ' +
-      '`spec-wave:model:<apelido>`), ou a exploração precisa de mais turnos.'
+      `ferramenta em todos eles.${resumo} ${remedio}`
     );
     this.name = 'MaxTurnsError';
     this.maxTurns = true;
+    // Quem decide o retry (lib/claude.mjs) lê esta flag — a classificação mora
+    // aqui, junto dos dados que a sustentam.
+    this.exploration = exploracao;
     this.turns = turns;
     this.action = action || null;
     this.toolCalls = toolCalls;
+    this.toolSignatures = toolSignatures;
   }
 }
 

package/src/agent/openrouter-agent.mjs

@@ -22,7 +22,7 @@ import {
   toolDefinitionsFor,
 } from './tools.mjs';
 import { withTrace, startObservation, updateSpan, endObservation } from './tracing.mjs';
-import { TruncatedOutputError, isTruncationReason, summarizeToolCalls } from './errors.mjs';
+import { TruncatedOutputError, isTruncationReason, summarizeToolCalls, toolSignature } from './errors.mjs';
 
 const DEFAULT_BASE_URL = 'https://openrouter.ai/api/v1';
 const DEFAULT_TOOLS = ['Read', 'Glob', 'Grep'];
@@ -184,6 +184,7 @@ export async function runOpenRouterAgent(prompt, options) {
     // turnos sem escrever nada, o log não dizia no que ele se perdeu, e o
     // diagnóstico exigiu reconstruir o run à mão.
     toolCalls: [],
+    toolSignatures: [],
   };
   const quiet = options.quiet !== false;
 
@@ -333,6 +334,9 @@ export async function runOpenRouterAgent(prompt, options) {
             }
 
             runResult.toolCalls.push(call.function.name);
+            // Assinatura (nome + alvo) separa exploração de loop degenerado —
+            // é o que decide se o teto de turnos merece uma repetição.
+            runResult.toolSignatures.push(toolSignature(call.function.name, parsedInput));
             if (options.verbose) console.log(`\n[Tool] ${call.function.name}(${call.function.arguments})`);
 
             const observation = startObservation(

package/src/api/github-graphql.mjs

@@ -179,17 +179,137 @@ 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 } } } }
+      }
+    }
+  `, { 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);
+}
+
+/**
+ * Todos os itens do Project, com os campos SINGLE_SELECT resolvidos por NOME.
+ *
+ * Uma query paginada no lugar de duas chamadas POR ITEM
+ * (`addProjectItem` + `getItemSingleSelectValue`), que é como o `order` lia a
+ * Etapa de cada Story. Com nove Features na tela isso passava de cem chamadas
+ * para montar um mapa que cabe em duas.
+ *
+ * Só itens cujo conteúdo é Issue entram (draft e PR ficam de fora).
+ *
+ * @returns {Promise<Array<{number, title, state, nodeId, itemId, fields: Record<string,string>}>>}
+ */
+export async function listProjectItems(token, projectId) {
+  const client = makeClient(token);
+  const itens = [];
+  let after = null;
+  do {
+    const result = await client(`
+      query ProjectItems($id: ID!, $after: String) {
+        node(id: $id) {
+          ... on ProjectV2 {
+            items(first: 100, after: $after) {
+              pageInfo { hasNextPage endCursor }
+              nodes {
+                id
+                fieldValues(first: 20) {
+                  nodes {
+                    ... on ProjectV2ItemFieldSingleSelectValue {
+                      name
+                      field { ... on ProjectV2SingleSelectField { name } }
+                    }
+                  }
+                }
+                content { ... on Issue { number title state id } }
+              }
+            }
+          }
+        }
+      }
+    `, { id: projectId, after });
+    const page = result.node?.items;
+    for (const node of page?.nodes || []) {
+      const issue = node?.content;
+      if (!issue?.number) continue;
+      const fields = {};
+      for (const fv of node.fieldValues?.nodes || []) {
+        const nome = fv?.field?.name;
+        if (nome && fv.name) fields[nome] = fv.name;
       }
+      itens.push({
+        number: issue.number,
+        title: issue.title,
+        state: issue.state,
+        nodeId: issue.id,
+        itemId: node.id,
+        fields,
+      });
     }
-  `, { projectId, contentId });
-  return result.addProjectV2ItemById.item.id;
+    after = page?.pageInfo?.hasNextPage ? page.pageInfo.endCursor : null;
+  } while (after);
+  return itens;
 }
 
 // Cria a relação de sub-issue nativa do GitHub (parent → child). Ambos os IDs

package/src/api/github-rest.mjs

@@ -281,9 +281,16 @@ export async function ensurePullRequest(
 
 // `id` é o database id da issue — exigido pela API de dependências
 // (blocked_by), que não aceita number nem node id.
-export async function createIssue(token, owner, repo, title, body, labels) {
+//
+// `milestone` é o NÚMERO do milestone no repo (não o título nem o node id) e só
+// entra no payload quando existe: a API rejeita `milestone: null` com 422 em vez
+// de tratar como "sem milestone".
+export async function createIssue(token, owner, repo, title, body, labels, { milestone } = {}) {
   const octokit = makeOctokit(token);
-  const res = await octokit.rest.issues.create({ owner, repo, title, body, labels });
+  const res = await octokit.rest.issues.create({
+    owner, repo, title, body, labels,
+    ...(milestone ? { milestone } : {}),
+  });
   return { number: res.data.number, nodeId: res.data.node_id, url: res.data.html_url, id: res.data.id };
 }
 

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).`);