@spec-wave/cli 0.21.0 → 0.24.0

package/README.md

@@ -108,7 +108,7 @@ Arquivo em `.github/config/tech_context.yml` que descreve a stack tecnológica d
   ```bash
   gh auth refresh --scopes project,repo,workflow
   ```
-- Secret no repositório: `ANTHROPIC_API_KEY` ou `OPENROUTER_API_KEY` (Settings → Secrets → Actions)
+- Secret no repositório, conforme o provider: `ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN` (assinatura Claude Pro/Max) ou `OPENROUTER_API_KEY` (Settings → Secrets → Actions)
 - Para repositórios em organizações: criar PAT com escopo `project` e adicionar como secret `GH_PROJECT_TOKEN`
 
 ---
@@ -191,10 +191,10 @@ npx @spec-wave/cli@latest init --repo acme/loja --project-title "Loja — Spec W
 O `init` cria:
 - GitHub Project v2 com 12 colunas Kanban e campos personalizados (Work Item Type, Priority, Story Points, Area)
 - 20+ labels de tipo, prioridade e gatilho
-- 6 GitHub Actions workflows em `.github/workflows/`
+- 8 GitHub Actions workflows em `.github/workflows/`
 - `.spec-wave.json` com os IDs do Project
 
-Adicionar o secret de IA no GitHub: **Settings → Secrets → Actions → `ANTHROPIC_API_KEY`**.
+Adicionar o secret de IA no GitHub: **Settings → Secrets → Actions** — `ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN` ou `OPENROUTER_API_KEY`, conforme o provider escolhido no `init`.
 
 ---
 
@@ -408,14 +408,34 @@ Isso atualiza apenas os arquivos de workflow sem recriar o Project ou as labels.
 
 | Provider | Secret | Modelo padrão |
 |----------|--------|---------------|
-| Anthropic | `ANTHROPIC_API_KEY` | `claude-sonnet-4-6` |
-| OpenRouter | `OPENROUTER_API_KEY` | `anthropic/claude-3.7-sonnet` |
+| `anthropic` | `ANTHROPIC_API_KEY` | `claude-sonnet-4-6` |
+| `claude-oauth` | `CLAUDE_CODE_OAUTH_TOKEN` | `claude-sonnet-4-6` |
+| `openrouter` | `OPENROUTER_API_KEY` | `anthropic/claude-3.7-sonnet` |
 
 Configurar no `init`:
 ```bash
 npx @spec-wave/cli@latest init --repo owner/repo --provider openrouter --model anthropic/claude-3.7-sonnet
 ```
 
+### `claude-oauth` — rodar tudo pela assinatura Claude Pro/Max
+
+Mesmo motor do provider `anthropic`, credencial diferente: em vez de uma chave
+de API cobrada por token, o token da sua assinatura. Os cinco workflows de IA
+(spec, plan, bug, decompose, critique) rodam assim, inclusive nos GitHub Actions
+— o binário do Claude Code vem embarcado na CLI, então o runner não precisa de
+nada além do `setup-node` que os workflows já fazem.
+
+```bash
+claude setup-token          # gere o token (escopo só de inferência)
+# cole o valor em Settings → Secrets → Actions → CLAUDE_CODE_OAUTH_TOKEN
+
+npx @spec-wave/cli@latest init --repo owner/repo --provider claude-oauth
+# ou, num repo já configurado, troque "provider" no .spec-wave.json e rode `update`
+```
+
+O consumo passa a sair do limite do seu plano — sob rate limit da assinatura o
+job falha por indisponibilidade, não por erro de configuração.
+
 ---
 
 ## Licença

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.21.0",
+  "version": "0.24.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

@@ -6,10 +6,10 @@
 // e da execução das tools. Por isso não há dependência direta de
 // `@anthropic-ai/sdk` aqui — não reintroduza uma.
 //
-// Consequência operacional que vale lembrar: nos GitHub Actions do spec-wave o
-// runner tem `setup-node` e mais nada. Sem o Claude Code instalado, este
-// backend NÃO roda lá — os workflows usam o OpenRouter, que é `fetch` puro.
-// Este backend serve execução local, onde o Claude Code já existe.
+// Consequência operacional que vale lembrar: o binário vem EMBARCADO no SDK
+// (dependência opcional por plataforma), então `npm install -g @spec-wave/cli`
+// basta — inclusive no runner do GitHub Actions, que só tem `setup-node`. Quem
+// confere isso antes da primeira chamada é `assertBackendRunnable` em index.mjs.
 //
 // Tudo que o processo pai aprende chega por dois canais, e os dois viram
 // observações do Langfuse manualmente:
@@ -25,12 +25,24 @@
 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'];
 const MAX_TURNS = 25;
 
+// Variáveis de credencial cujo valor vazio deve ser tratado como AUSENTE.
+const CREDENTIAL_VARS = ['ANTHROPIC_API_KEY', 'CLAUDE_CODE_OAUTH_TOKEN'];
+
+/** Cópia do ambiente sem credenciais de valor vazio (função PURA). */
+export function withoutBlankCredentials(env) {
+  const copy = { ...env };
+  for (const key of CREDENTIAL_VARS) {
+    if (copy[key] !== undefined && String(copy[key]).trim() === '') delete copy[key];
+  }
+  return copy;
+}
+
 /** Base de comparação da allowlist: absoluto resolvido, minúsculo no win32. */
 function normalizeWritePath(p) {
   const resolved = path.resolve(p);
@@ -45,22 +57,24 @@ function normalizeWritePath(p) {
  * @returns {Promise<import('./run-types.mjs').AgentRunResult>}
  */
 export async function runAnthropicAgent(prompt, options) {
-  if (options.responseSchema) {
-    // O subprocesso não expõe tool_choice forçado, então não há como garantir
-    // a tool call única que a saída estruturada exige. Falhar aqui é melhor do
-    // que devolver texto livre que o chamador tentaria parsear "na tolerância"
-    // — foi exatamente esse caminho que rebaixava um finding grave a menor.
-    throw new Error(
-      'Saída estruturada não é suportada no backend anthropic (o subprocesso do ' +
-      'Claude Code não expõe tool_choice forçado). Use o provider openrouter para ' +
-      'ações com schema — hoje, a crítica adversarial.',
-    );
-  }
-
   const { query } = await import('@anthropic-ai/claude-agent-sdk');
 
-  const tools = options.tools ?? DEFAULT_TOOLS;
-  const toolMatcher = `^(${tools.join('|')})$`;
+  // Saída estruturada: `outputFormat` faz o CLI garantir um payload conforme o
+  // schema (ele mesmo repete o turno enquanto não bater) e devolvê-lo em
+  // `structured_output` no result. Não existe equivalente ao `strict` do
+  // OpenRouter aqui — a garantia é o loop de retry do CLI, não o tipo do
+  // endpoint; por isso `responseSchema.strict` é ignorado neste backend.
+  const schema = options.responseSchema ?? null;
+  // Com schema o modelo não explora nada: a resposta é UM payload. Misturar as
+  // duas coisas daria a saída de escape de "chamar Read de novo" em vez de
+  // fechar o contrato — mesma regra do backend openrouter.
+  //
+  // O que NÃO se copia de lá é o `maxTurns: 1`: aqui o turno extra é do próprio
+  // CLI refazendo a resposta até casar com o schema (um run que deu certo
+  // reportou 2 turnos). Apertar o teto trocaria esse retry por error_max_turns.
+  const tools = schema ? [] : (options.tools ?? DEFAULT_TOOLS);
+  // `^()$` casaria com nome vazio; sem tools, o matcher não pode casar nada.
+  const toolMatcher = tools.length > 0 ? `^(${tools.join('|')})$` : '(?!)';
   const allowedWritePaths = options.allowedWritePaths?.map(normalizeWritePath) ?? null;
   const runResult = {
     resultSubtype: null,
@@ -72,6 +86,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;
 
@@ -97,6 +112,7 @@ export async function runAnthropicAgent(prompt, options) {
       const queryOptions = {
         model: options.model,
         maxTurns: options.maxTurns ?? MAX_TURNS,
+        ...(schema ? { outputFormat: { type: 'json_schema', schema: schema.jsonSchema } } : {}),
         // `tools` restringe o que o modelo sequer VÊ; `allowedTools` é só a
         // lista de auto-aprovação sobre essa superfície. Sem `tools`, as ~31
         // tools do Claude Code aparecem e são apenas aprovadas/negadas por
@@ -122,7 +138,12 @@ export async function runAnthropicAgent(prompt, options) {
               ],
             }
           : {}),
-        env: { ...process.env },
+        // `env` SUBSTITUI o ambiente do subprocesso, então o spread é obrigatório
+        // (PATH, HOME). O saneamento existe porque `${{ secrets.X }}` de um
+        // secret inexistente injeta string VAZIA: um CLAUDE_CODE_OAUTH_TOKEN=""
+        // chegando ao CLI é ambiguidade gratuita entre "não configurado" e
+        // "configurado errado".
+        env: withoutBlankCredentials(process.env),
         // Desliga o carregamento de settings do filesystem (~/.claude,
         // .claude/settings.json) para o subprocesso não herdar hooks ou
         // permissões de fora deste `queryOptions`.
@@ -159,6 +180,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)})`);
               }
@@ -288,6 +310,7 @@ export async function runAnthropicAgent(prompt, options) {
             if (message.subtype === 'success') {
               output = message.result;
               runResult.outputText = message.result;
+              if (schema) runResult.structured = message.structured_output ?? null;
               if (!quiet && !printedAnyText && message.result.trim() !== '') {
                 console.log(`\nClaude: ${message.result}`);
               }

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/index.mjs

@@ -1,8 +1,12 @@
-// Registro de backends: transforma um provider num runner concreto.
+// Registro de backends: transforma um backend num runner concreto.
 // Porte de `agent-cli/src/workflow/backends.ts` + `src/lib.ts`.
 //
-// É o ÚNICO módulo que sabe que os dois backends existem, então um terceiro
-// provider significa mexer só aqui.
+// É o ÚNICO módulo que sabe que os dois backends existem, então um MOTOR novo
+// significa mexer só aqui. Um provider novo que reusa um motor existente
+// (`claude-oauth` sobre o backend anthropic) não passa por este arquivo — vive
+// inteiro em config.mjs.
+
+import { createRequire } from 'node:module';
 
 import { runAnthropicAgent } from './anthropic-agent.mjs';
 import { runOpenRouterAgent } from './openrouter-agent.mjs';
@@ -12,7 +16,13 @@ export { ENV_FILE_PATTERN, createToolContext, executeTool, toolDefinitionsFor, K
 export { initTelemetry, shutdownTelemetry, telemetryConfigured } from './telemetry.mjs';
 export { runAnthropicAgent, runOpenRouterAgent };
 
-export const PROVIDERS = ['anthropic', 'openrouter'];
+// Este módulo fala em BACKEND, não em provider: quem escolhe entre `anthropic`,
+// `claude-oauth` e `openrouter` é o config, e src/lib/claude.mjs traduz essa
+// escolha para o backend antes de chegar aqui. Assim um provider novo que reusa
+// um backend existente (foi o caso do claude-oauth) não encosta em src/agent/.
+export const BACKENDS = ['anthropic', 'openrouter'];
+/** @deprecated nome antigo de BACKENDS — mantido para não quebrar importadores. */
+export const PROVIDERS = BACKENDS;
 
 const RUNNERS = {
   anthropic: runAnthropicAgent,
@@ -20,16 +30,16 @@ const RUNNERS = {
 };
 
 /**
- * Runner do provider (função PURA).
+ * Runner do backend (função PURA).
  *
- * @param {'anthropic'|'openrouter'} provider
+ * @param {'anthropic'|'openrouter'} backend
  * @returns {(prompt: string, options: object) => Promise<object>}
  */
-export function runnerFor(provider) {
-  const runner = RUNNERS[provider];
+export function runnerFor(backend) {
+  const runner = RUNNERS[backend];
   if (!runner) {
     throw new Error(
-      `Provider desconhecido: "${provider}" (esperado um de: ${PROVIDERS.join(', ')}).`,
+      `Backend desconhecido: "${backend}" (esperado um de: ${BACKENDS.join(', ')}).`,
     );
   }
   return runner;
@@ -39,20 +49,31 @@ export function runnerFor(provider) {
  * Confere credenciais ANTES de qualquer chamada de modelo — um fluxo que morre
  * no meio por falta de chave já gastou dinheiro de verdade.
  *
- * O SDK aceita chave de API OU token OAuth do Claude Code; exigir só a chave
- * rejeitaria uma assinatura que funciona.
+ * A checagem é por BACKEND, e o backend anthropic aceita qualquer uma das duas
+ * credenciais: chave de API (provider `anthropic`) ou token da assinatura
+ * (provider `claude-oauth`). Quem exige a credencial CERTA para o provider
+ * escolhido é o `doctor`, que sabe qual dos dois o repo configurou.
+ *
+ * Fora do CI o backend anthropic passa mesmo sem nada no ambiente: quem está
+ * logado no Claude Code (`claude /login`) tem a credencial guardada pelo
+ * próprio CLI, não em variável, e barrar aí rejeitaria uma sessão que
+ * funciona. No Actions não existe login interativo, então lá a ausência
+ * continua sendo erro imediato.
  *
- * @param {'anthropic'|'openrouter'} provider
+ * @param {'anthropic'|'openrouter'} backend
  * @param {object} [env]
  */
-export function assertCredentials(provider, env = process.env) {
-  if (provider === 'anthropic' && !env.ANTHROPIC_API_KEY && !env.CLAUDE_CODE_OAUTH_TOKEN) {
+export function assertCredentials(backend, env = process.env) {
+  if (
+    backend === 'anthropic' && env.GITHUB_ACTIONS === 'true' &&
+    !env.ANTHROPIC_API_KEY && !env.CLAUDE_CODE_OAUTH_TOKEN
+  ) {
     throw new Error(
       'Faltam credenciais: defina ANTHROPIC_API_KEY ou CLAUDE_CODE_OAUTH_TOKEN ' +
       '(secret do repositório, em Settings → Secrets → Actions).',
     );
   }
-  if (provider === 'openrouter' && !env.OPENROUTER_API_KEY) {
+  if (backend === 'openrouter' && !env.OPENROUTER_API_KEY) {
     throw new Error(
       'Faltam credenciais: defina OPENROUTER_API_KEY ' +
       '(secret do repositório, em Settings → Secrets → Actions).',
@@ -60,49 +81,94 @@ export function assertCredentials(provider, env = process.env) {
   }
 }
 
+const requireFromHere = createRequire(import.meta.url);
+
+/**
+ * Pacotes que podem carregar o binário nativo do Claude Code nesta plataforma.
+ *
+ * No linux há duas variantes de libc e o npm instala só a que casa com o host;
+ * aceitar as duas evita um falso negativo em imagem musl (Alpine).
+ *
+ * @param {NodeJS.Platform} [platform]
+ * @param {string} [arch]
+ * @returns {string[]}
+ */
+export function nativeBinaryPackages(platform = process.platform, arch = process.arch) {
+  const base = `@anthropic-ai/claude-agent-sdk-${platform}-${arch}`;
+  return platform === 'linux' ? [base, `${base}-musl`] : [base];
+}
+
+/**
+ * O binário nativo do Claude Code está instalado?
+ *
+ * @param {(id: string) => string} [resolve] injetável para teste
+ * @returns {boolean}
+ */
+export function nativeBinaryAvailable(resolve = id => requireFromHere.resolve(id)) {
+  return nativeBinaryPackages().some(pkg => {
+    try {
+      resolve(`${pkg}/package.json`);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+}
+
 /**
- * O backend pode rodar NESTE ambiente? (função PURA)
+ * O backend pode rodar NESTE ambiente?
  *
  * O backend anthropic não chama a API: `query()` sobe o **Claude Code CLI como
- * processo filho**. Os workflows do spec-wave só têm `setup-node`, então lá o
- * subprocesso não existe — e a falha nativa é um ENOENT sem relação aparente
- * com configuração de IA. Falhar aqui, com o que ajustar, custa segundos em vez
- * de uma investigação.
+ * processo filho**. O que decide se isso funciona é a presença do binário — e
+ * ele vem EMBARCADO no `@anthropic-ai/claude-agent-sdk`, como dependência
+ * opcional por plataforma (`@anthropic-ai/claude-agent-sdk-linux-x64` e
+ * companhia). Ou seja: `npm install -g @spec-wave/cli` já o traz, inclusive no
+ * runner do GitHub Actions, que só tem `setup-node`.
+ *
+ * Isto já foi um bloqueio incondicional no Actions, escrito quando o SDK ainda
+ * exigia o Claude Code instalado à parte. Checar o binário em vez do ambiente
+ * cobre a falha de verdade — `npm install --omit=optional`, plataforma sem
+ * build publicado — e libera a assinatura (provider `claude-oauth`) no CI.
+ *
+ * Fora do alcance daqui: binário presente mas com a libc errada (musl num host
+ * glibc). Aí quem falha é o spawn, e a mensagem do próprio SDK já nomeia a causa.
  *
- * Escape hatch para quem instala o Claude Code no runner:
- * `SPEC_WAVE_ALLOW_ANTHROPIC_IN_CI=1`.
+ * `SPEC_WAVE_ALLOW_ANTHROPIC_IN_CI=1` segue aceito como bypass — hoje inútil,
+ * mas está em workflows de quem seguiu a orientação antiga.
  *
- * @param {'anthropic'|'openrouter'} provider
+ * @param {'anthropic'|'openrouter'} backend
  * @param {object} [env]
  */
-export function assertBackendRunnable(provider, env = process.env) {
-  if (provider !== 'anthropic') return;
-  if (env.GITHUB_ACTIONS !== 'true') return;
+export function assertBackendRunnable(backend, env = process.env) {
+  if (backend !== 'anthropic') return;
   if (env.SPEC_WAVE_ALLOW_ANTHROPIC_IN_CI) return;
+  if (nativeBinaryAvailable()) return;
   throw new Error(
-    'O provider `anthropic` não roda no GitHub Actions: ele não chama a API — sobe o ' +
-    'Claude Code CLI como subprocesso, que não existe no runner (só há setup-node).\n\n' +
+    'O backend `anthropic` sobe o Claude Code CLI como subprocesso, e o binário nativo ' +
+    `não está instalado (procurado em: ${nativeBinaryPackages().join(', ')}).\n\n` +
     'Saídas:\n' +
-    '  1. Troque para o OpenRouter no .spec-wave.json:  "ai": { "provider": "openrouter", ' +
-    '"model": "anthropic/claude-opus-4.8" }  e adicione o secret OPENROUTER_API_KEY;\n' +
-    '  2. ou instale o Claude Code no workflow e defina SPEC_WAVE_ALLOW_ANTHROPIC_IN_CI=1.\n\n' +
-    'Localmente o provider `anthropic` funciona normalmente.',
+    '  1. Reinstale o CLI SEM `--omit=optional` (o binário é uma dependência opcional ' +
+    'por plataforma do @anthropic-ai/claude-agent-sdk);\n' +
+    '  2. ou troque para o OpenRouter no .spec-wave.json:  "ai": { "provider": "openrouter", ' +
+    '"model": "anthropic/claude-opus-4.8" }  e adicione o secret OPENROUTER_API_KEY.',
   );
 }
 
 /**
- * Executa uma ação de IA no provider escolhido.
+ * Executa uma ação de IA no backend escolhido.
  *
  * É o ponto único por onde `lib/claude.mjs` fala com o motor: os dois backends
- * implementam o mesmo contrato, então quem chama nunca ramifica por provider.
+ * implementam o mesmo contrato, então quem chama nunca ramifica por backend.
+ * O campo continua se chamando `provider` por compatibilidade com o contrato do
+ * agent-cli de origem, mas o valor esperado é o BACKEND.
  *
  * @param {string} prompt conteúdo do usuário
  * @param {import('./run-types.mjs').AgentRunOptions & {provider: string}} options
  * @returns {Promise<import('./run-types.mjs').AgentRunResult>}
  */
 export async function runAgent(prompt, options) {
-  const { provider, ...rest } = options;
-  assertBackendRunnable(provider);
-  assertCredentials(provider);
-  return runnerFor(provider)(prompt, rest);
+  const { provider: backend, ...rest } = options;
+  assertBackendRunnable(backend);
+  assertCredentials(backend);
+  return runnerFor(backend)(prompt, rest);
 }

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

@@ -249,6 +249,69 @@ export function isAlreadyInProjectError(err) {
     || /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,
+      });
+    }
+    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
 // são node ids de Issue. Faz com que o filho exiba o pai e vice-versa na UI.
 export async function addSubIssue(token, parentIssueId, childIssueId) {

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 };
 }