@spec-wave/cli 0.15.0 → 0.16.1

package/README.md

@@ -22,6 +22,7 @@ O resultado é um board Kanban no GitHub Projects v2 que avança automaticamente
 
 ```
 📥 Backlog
+  → 🐞 Triagem       ← só Bug reportado (RFC-004)
   → 🎯 Priorizado
   → 📋 Spec          ← label spec-wave:spec → Action gera spec.md
   → 📋 Plan          ← label spec-wave:plan → Action gera plan.md

package/bin/spec-wave.mjs

@@ -42,6 +42,9 @@ program
   .command('refresh')
   .description('Atualiza o .spec-wave.json local com os dados atuais do GitHub Project')
   .option('--config', 'Re-consulta o Project e reescreve o .spec-wave.json')
+  .option('--stages', 'Acrescenta ao campo "Etapa" as colunas canônicas que faltam (nunca remove)')
+  .option('--dry-run', 'Com --stages: mostra o que seria enviado e não escreve nada')
+  .option('--yes', 'Com --stages: não pede confirmação')
   .action(async (options) => {
     const { refresh } = await import('../src/commands/refresh.mjs');
     await refresh(options).catch(err => { console.error(err.message); process.exit(1); });
@@ -86,6 +89,33 @@ program
     await feature(options).catch(err => { console.error(err.message); process.exit(1); });
   });
 
+program
+  .command('bug')
+  .description('Cria um Bug (atalho de `issue --type bug`) — nasce em 🐞 Triagem, ou ✅ Ready se P0')
+  .requiredOption('--title <title>', 'Título (sem o prefixo [BUG])')
+  .option('--parent <n>', 'Feature ou Story afetada (cria como sub-issue dela)')
+  .option('--body <text>', 'Descrição: passos, esperado e obtido')
+  .option('--priority <p>', 'Severidade: P0, P1, P2 ou P3')
+  .option('--area <area>', 'Área: Frontend, Backend, Mobile, Infra, DevOps ou Data')
+  .action(async (options) => {
+    const { bug } = await import('../src/commands/bug.mjs');
+    await bug(options).catch(err => { console.error(err.message); process.exit(1); });
+  });
+
+program
+  .command('triage')
+  .description('Tria um Bug: accept (→ ✅ Ready), reject (fecha) ou duplicate (fecha)')
+  .argument('<action>', 'accept | reject | duplicate')
+  .argument('<issue>', 'Número da issue do Bug')
+  .option('--reason <texto>', 'Motivo da rejeição (obrigatório em reject)')
+  .option('--of <n>', 'Número da issue original (obrigatório em duplicate)')
+  .option('--severity <p>', 'Reclassifica a severidade ao aceitar: P0–P3')
+  .action(async (action, issue, options) => {
+    const { triage } = await import('../src/commands/triage.mjs');
+    await triage({ action, issue, ...options })
+      .catch(err => { console.error(err.message); process.exit(1); });
+  });
+
 program
   .command('update')
   .description('Detecta o que está desatualizado (skill, .spec-wave.json, workflows/labels do repo) e atualiza só o que mudou')
@@ -105,7 +135,7 @@ program
 
 program
   .command('install-skill')
-  .description('Instala a skill spec-wave no(s) agente(s) detectado(s): Claude Code, Cursor, opencode, Cline, Kilo, Antigravity, AGENTS.md')
+  .description('Instala a skill spec-wave no(s) agente(s) detectado(s): Claude Code, Codex, Cursor, opencode, Cline, Kilo, Antigravity, AGENTS.md')
   .option('--agent <names>', 'Agente(s) alvo, separados por vírgula (pula a detecção)')
   .option('--all', 'Instala em todos os agentes detectados')
   .option('--global', 'Instala no escopo do usuário (padrão: projeto)')
@@ -133,7 +163,7 @@ program
 
 program
   .command('generate-plan')
-  .description('Gera plan.md para uma Feature (usado pelo GitHub Action)')
+  .description('Gera plan.md para uma Feature — roda no GitHub Action ou localmente')
   .requiredOption('--issue-number <n>', 'Número da issue no GitHub')
   .action(async (options) => {
     const { generatePlan } = await import('../src/commands/generate-plan.mjs');
@@ -142,16 +172,25 @@ program
 
 program
   .command('generate-spec')
-  .description('Gera spec.md para uma Feature (usado pelo GitHub Action)')
+  .description('Gera spec.md para uma Feature — roda no GitHub Action ou localmente')
   .requiredOption('--issue-number <n>', 'Número da issue no GitHub')
   .action(async (options) => {
     const { generateSpec } = await import('../src/commands/generate-spec.mjs');
     await generateSpec(options).catch(err => { console.error(err.message); process.exit(1); });
   });
 
+program
+  .command('generate-bug')
+  .description('Gera bug.md para um Bug (usado pelo GitHub Action)')
+  .requiredOption('--issue-number <n>', 'Número da issue no GitHub')
+  .action(async (options) => {
+    const { generateBug } = await import('../src/commands/generate-bug.mjs');
+    await generateBug(options).catch(err => { console.error(err.message); process.exit(1); });
+  });
+
 program
   .command('validate')
-  .description('Valida spec.md e plan.md de uma Feature (usado pelo GitHub Action)')
+  .description('Valida os documentos de uma issue: spec.md+plan.md de Feature, bug.md de Bug (usado pelo GitHub Action)')
   .requiredOption('--issue-number <n>', 'Número da issue no GitHub')
   .action(async (options) => {
     const { validate } = await import('../src/commands/validate.mjs');
@@ -160,7 +199,7 @@ program
 
 program
   .command('decompose')
-  .description('Gera o rascunho da decomposição em decomposition.md; com --apply, cria as Stories/Tasks a partir do rascunho revisado (usado pelo GitHub Action)')
+  .description('Gera o rascunho da decomposição em decomposition.md; com --apply, cria as Stories/Tasks a partir do rascunho revisado — roda no Action ou localmente')
   .requiredOption('--issue-number <n>', 'Número da issue no GitHub')
   .option('--apply', 'Aplica o decomposition.md já revisado: cria as issues (sem esta flag, apenas gera/critica o rascunho)')
   .action(async (options) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spec-wave/cli",
-  "version": "0.15.0",
+  "version": "0.16.1",
   "description": "Setup spec-driven GitHub workflow with Projects v2, labels, issue templates, and AI-powered Actions",
   "type": "module",
   "bin": {
@@ -20,12 +20,18 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.36.3",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.220",
     "@clack/prompts": "^0.9.1",
+    "@langfuse/otel": "^5.9.1",
+    "@langfuse/tracing": "^5.9.1",
     "@octokit/graphql": "^9.0.1",
     "@octokit/rest": "^22.0.0",
+    "@opentelemetry/sdk-node": "^0.221.0",
     "chalk": "^5.4.1",
     "commander": "^13.1.0",
     "js-yaml": "^4.1.0"
+  },
+  "overrides": {
+    "@hono/node-server": "^2.0.5"
   }
 }

package/src/agent/anthropic-agent.mjs

@@ -0,0 +1,337 @@
+// Backend anthropic: `query()` do Claude Agent SDK. Porte de
+// `agent-cli/src/agent.ts`.
+//
+// FATO CENTRAL: este processo NUNCA chama a API da Anthropic. `query()` sobe o
+// **Claude Code CLI como processo filho**, e é ele que é dono do loop do modelo
+// 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.
+//
+// Tudo que o processo pai aprende chega por dois canais, e os dois viram
+// observações do Langfuse manualmente:
+//
+//  1. HOOKS — `PreToolUse` abre uma observação `tool-<nome>` (indexada por
+//     `tool_use_id`), `PostToolUse` a fecha com a saída, `PostToolUseFailure` a
+//     fecha como erro. Uma varredura no `finally` fecha o que ficou órfão.
+//  2. STREAM DE MENSAGENS — mensagens do assistente acumulam em UMA generation
+//     por id de mensagem da API (um turno pode emitir várias com o mesmo id:
+//     tool calls paralelas, recuperação de thinking, fallback de recusa). Um id
+//     novo encerra todas as anteriores.
+
+import path from 'node:path';
+import { withTrace, startObservation, updateSpan, endObservation } from './tracing.mjs';
+import { ENV_FILE_PATTERN } from './tools.mjs';
+import { TruncatedOutputError } from './errors.mjs';
+
+const DEFAULT_TOOLS = ['Read', 'Glob', 'Grep'];
+const MAX_TURNS = 25;
+
+/** Base de comparação da allowlist: absoluto resolvido, minúsculo no win32. */
+function normalizeWritePath(p) {
+  const resolved = path.resolve(p);
+  return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+
+/**
+ * Roda o agente pelo Claude Agent SDK.
+ *
+ * @param {string} prompt
+ * @param {import('./run-types.mjs').AgentRunOptions} options
+ * @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('|')})$`;
+  const allowedWritePaths = options.allowedWritePaths?.map(normalizeWritePath) ?? null;
+  const runResult = {
+    resultSubtype: null,
+    outputText: '',
+    costUsd: null,
+    numTurns: 0,
+    structured: null,
+    usage: { inputTokens: 0, outputTokens: 0 },
+  };
+  const quiet = options.quiet !== false;
+
+  await withTrace(
+    {
+      name: options.traceName ?? 'agent-execution',
+      sessionId: options.sessionId,
+      userId: options.userId,
+      tags: ['spec-wave', 'agent', 'anthropic', ...(options.extraTags ?? [])],
+      metadata: { model: options.model, provider: 'anthropic' },
+      nested: options.nested === true,
+    },
+    async span => {
+      updateSpan(span, { input: prompt });
+
+      const toolObservations = new Map();
+      const generations = new Map();
+      let printedAnyText = false;
+      let sawResult = false;
+      let isFirstTurn = true;
+      let lastStopReason = null;
+
+      const queryOptions = {
+        model: options.model,
+        maxTurns: options.maxTurns ?? MAX_TURNS,
+        // `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
+        // chamada.
+        tools,
+        allowedTools: tools,
+        ...(options.systemPromptAppend !== undefined
+          ? {
+              systemPrompt: {
+                type: 'preset',
+                preset: 'claude_code',
+                append: options.systemPromptAppend,
+              },
+            }
+          : {}),
+        ...(options.maxTokens ? { maxTokens: options.maxTokens } : {}),
+        permissionMode: 'dontAsk',
+        cwd: options.cwd ?? process.cwd(),
+        ...(options.allowedWritePaths?.length
+          ? {
+              additionalDirectories: [
+                ...new Set(options.allowedWritePaths.map(p => path.dirname(path.resolve(p)))),
+              ],
+            }
+          : {}),
+        env: { ...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`.
+        settingSources: [],
+        hooks: {
+          PreToolUse: [{
+            matcher: toolMatcher,
+            hooks: [async (input, toolUseID) => {
+              const id = toolUseID ?? input.tool_use_id;
+              const filePath = input.tool_input?.file_path;
+
+              if (typeof filePath === 'string' && ENV_FILE_PATTERN.test(filePath)) {
+                return {
+                  hookSpecificOutput: {
+                    hookEventName: 'PreToolUse',
+                    permissionDecision: 'deny',
+                    permissionDecisionReason: 'Access to .env files is blocked',
+                  },
+                };
+              }
+
+              if (
+                allowedWritePaths !== null &&
+                input.tool_name === 'Write' &&
+                (typeof filePath !== 'string' || !allowedWritePaths.includes(normalizeWritePath(filePath)))
+              ) {
+                return {
+                  hookSpecificOutput: {
+                    hookEventName: 'PreToolUse',
+                    permissionDecision: 'deny',
+                    permissionDecisionReason: `Writes are allowed only to: ${(options.allowedWritePaths ?? []).join(', ')}`,
+                  },
+                };
+              }
+
+              if (options.verbose) {
+                console.log(`\n[Tool] ${input.tool_name}(${JSON.stringify(input.tool_input)})`);
+              }
+              if (id) {
+                toolObservations.set(
+                  id,
+                  startObservation(span, `tool-${input.tool_name}`, { input: input.tool_input }, 'tool'),
+                );
+              }
+              return {};
+            }],
+          }],
+          PostToolUse: [{
+            matcher: toolMatcher,
+            hooks: [async (input, toolUseID) => {
+              const id = toolUseID ?? input.tool_use_id;
+              const obs = id ? toolObservations.get(id) : undefined;
+              if (obs) {
+                updateSpan(obs, { output: input.tool_response });
+                endObservation(obs);
+                toolObservations.delete(id);
+              }
+              return {};
+            }],
+          }],
+          PostToolUseFailure: [{
+            matcher: toolMatcher,
+            hooks: [async (input, toolUseID) => {
+              const id = toolUseID ?? input.tool_use_id;
+              const obs = id ? toolObservations.get(id) : undefined;
+              if (obs) {
+                updateSpan(obs, { output: `[tool failed] ${input.error}`, level: 'ERROR' });
+                endObservation(obs);
+                toolObservations.delete(id);
+              }
+              return {};
+            }],
+          }],
+        },
+      };
+
+      try {
+        for await (const message of query({ prompt, options: queryOptions })) {
+          if (message.type === 'system') {
+            if (message.subtype === 'init' && options.verbose) {
+              console.log(`[Agent] Claude Code session ${message.session_id} started`);
+            }
+            continue;
+          }
+
+          if (message.type === 'assistant') {
+            const apiMessage = message.message;
+            lastStopReason = apiMessage.stop_reason ?? lastStopReason;
+            for (const block of apiMessage.content) {
+              if (block.type === 'text' && block.text.trim() !== '') {
+                if (!quiet) console.log(`\nClaude: ${block.text}`);
+                printedAnyText = true;
+              }
+            }
+
+            const usage = apiMessage.usage;
+            runResult.usage.inputTokens += usage?.input_tokens ?? 0;
+            runResult.usage.outputTokens += usage?.output_tokens ?? 0;
+
+            let entry = generations.get(apiMessage.id);
+            if (!entry) {
+              // Id novo = turno novo. Encerra as generations abertas agora, em
+              // vez de esperar a varredura do finally, para que a duração de
+              // cada uma reflita o próprio turno e não o run inteiro.
+              for (const prev of generations.values()) endObservation(prev.gen);
+              generations.clear();
+
+              const gen = startObservation(
+                span,
+                'generate-response',
+                { model: apiMessage.model, ...(isFirstTurn ? { input: prompt } : {}) },
+                'generation',
+              );
+              isFirstTurn = false;
+              entry = { gen, textParts: [], toolCalls: [] };
+              generations.set(apiMessage.id, entry);
+            }
+
+            const text = apiMessage.content
+              .filter(block => block.type === 'text')
+              .map(block => block.text)
+              .join('\n');
+            if (text !== '') entry.textParts.push(text);
+            for (const block of apiMessage.content) {
+              if (block.type === 'tool_use') {
+                entry.toolCalls.push({ id: block.id, name: block.name, input: block.input });
+              }
+            }
+
+            const joinedText = entry.textParts.join('\n');
+            updateSpan(entry.gen, {
+              output: entry.toolCalls.length > 0
+                ? {
+                    role: 'assistant',
+                    content: joinedText,
+                    tool_calls: entry.toolCalls.map(call => ({
+                      id: call.id,
+                      type: 'function',
+                      function: { name: call.name, arguments: JSON.stringify(call.input) },
+                    })),
+                  }
+                : joinedText,
+              usageDetails: {
+                input: usage?.input_tokens ?? 0,
+                output: usage?.output_tokens ?? 0,
+                cache_read_input_tokens: usage?.cache_read_input_tokens ?? 0,
+                cache_creation_input_tokens: usage?.cache_creation_input_tokens ?? 0,
+              },
+            });
+            if (options.verbose) {
+              console.log(`[Usage] in=${usage?.input_tokens ?? 0} out=${usage?.output_tokens ?? 0}`);
+            }
+            continue;
+          }
+
+          if (message.type === 'result') {
+            sawResult = true;
+            runResult.resultSubtype = message.subtype;
+            runResult.costUsd = message.total_cost_usd;
+            runResult.numTurns = message.num_turns;
+            let output;
+            if (message.subtype === 'success') {
+              output = message.result;
+              runResult.outputText = message.result;
+              if (!quiet && !printedAnyText && message.result.trim() !== '') {
+                console.log(`\nClaude: ${message.result}`);
+              }
+            } else {
+              output = `[${message.subtype}]`;
+              console.warn(`\n[Agent] Run ended without success: ${message.subtype}`);
+            }
+            updateSpan(span, {
+              output,
+              metadata: {
+                total_cost_usd: message.total_cost_usd,
+                num_turns: message.num_turns,
+                claude_code_session_id: message.session_id,
+                permission_denials: message.permission_denials?.length ?? 0,
+              },
+            });
+            if (!quiet) {
+              console.log(`\n[Cost] $${message.total_cost_usd.toFixed(4)} across ${message.num_turns} turn(s)`);
+            }
+          }
+        }
+      } finally {
+        for (const obs of toolObservations.values()) {
+          updateSpan(obs, { output: '[no PostToolUse received]' });
+          endObservation(obs);
+        }
+        toolObservations.clear();
+        for (const entry of generations.values()) endObservation(entry.gen);
+        generations.clear();
+        if (!sawResult) {
+          updateSpan(span, { output: '[stream ended without a result message]' });
+        }
+      }
+
+      // O corte só é detectável DEPOIS do stream: o `stop_reason` chega na
+      // mensagem do assistente, e o resultado vem em seguida. Verificar aqui
+      // ainda cumpre a garantia que importa — o erro sobe antes de qualquer
+      // gravação, porque quem grava é o comando, não este backend.
+      if (lastStopReason === 'max_tokens') {
+        throw new TruncatedOutputError({
+          provider: 'anthropic',
+          model: options.model,
+          maxTokens: options.maxTokens ?? null,
+          reason: lastStopReason,
+          chars: runResult.outputText.length,
+        });
+      }
+    },
+  );
+
+  return runResult;
+}

package/src/agent/errors.mjs

@@ -0,0 +1,33 @@
+// Erros e sinais compartilhados entre o motor do agente e o adaptador
+// `lib/claude.mjs`.
+//
+// Vieram de `lib/claude.mjs`; foram movidos para cá quando os backends
+// portados do agent-cli passaram a precisar deles, para não haver duas
+// definições de "saída truncada" divergindo em silêncio.
+
+// A OpenRouter sinaliza corte em `choices[0].finish_reason`, a Anthropic em
+// `message.stop_reason`. Ignorar esse campo é o que produzia um documento
+// cortado no meio de uma frase, commitado como se estivesse completo.
+const TRUNCATION_REASONS = new Set(['length', 'max_tokens']);
+
+/** Motivo de parada indica saída cortada no teto de tokens? (função PURA) */
+export function isTruncationReason(reason) {
+  return TRUNCATION_REASONS.has(reason);
+}
+
+// Repetir a MESMA requisição depois de truncar dá o mesmo corte — só sobe o
+// custo. Por isso NÃO é marcado como transitório: o erro sobe, o Action falha
+// visível, destrava a label e comenta na issue o que ajustar.
+export class TruncatedOutputError extends Error {
+  constructor({ provider, model, maxTokens, reason, chars }) {
+    super(
+      `Saída truncada pelo teto de tokens (${provider} · ${model} · max_tokens=${maxTokens} · ` +
+      `motivo=${reason}). Foram gerados ~${chars} caracteres antes do corte. ` +
+      'Aumente `ai.maxTokens` (ou `ai.maxTokensByAction`) no .spec-wave.json, ou reduza o ' +
+      'tamanho da issue de origem. O documento NÃO foi gravado — um documento cortado ' +
+      'passaria na validação de seções e valeria menos que nenhum.'
+    );
+    this.name = 'TruncatedOutputError';
+    this.truncated = true;
+  }
+}

package/src/agent/index.mjs

@@ -0,0 +1,108 @@
+// Registro de backends: transforma um provider 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.
+
+import { runAnthropicAgent } from './anthropic-agent.mjs';
+import { runOpenRouterAgent } from './openrouter-agent.mjs';
+
+export { TruncatedOutputError, isTruncationReason } from './errors.mjs';
+export { ENV_FILE_PATTERN, createToolContext, executeTool, toolDefinitionsFor, KNOWN_TOOL_NAMES } from './tools.mjs';
+export { initTelemetry, shutdownTelemetry, telemetryConfigured } from './telemetry.mjs';
+export { runAnthropicAgent, runOpenRouterAgent };
+
+export const PROVIDERS = ['anthropic', 'openrouter'];
+
+const RUNNERS = {
+  anthropic: runAnthropicAgent,
+  openrouter: runOpenRouterAgent,
+};
+
+/**
+ * Runner do provider (função PURA).
+ *
+ * @param {'anthropic'|'openrouter'} provider
+ * @returns {(prompt: string, options: object) => Promise<object>}
+ */
+export function runnerFor(provider) {
+  const runner = RUNNERS[provider];
+  if (!runner) {
+    throw new Error(
+      `Provider desconhecido: "${provider}" (esperado um de: ${PROVIDERS.join(', ')}).`,
+    );
+  }
+  return runner;
+}
+
+/**
+ * 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.
+ *
+ * @param {'anthropic'|'openrouter'} provider
+ * @param {object} [env]
+ */
+export function assertCredentials(provider, env = process.env) {
+  if (provider === 'anthropic' && !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) {
+    throw new Error(
+      'Faltam credenciais: defina OPENROUTER_API_KEY ' +
+      '(secret do repositório, em Settings → Secrets → Actions).',
+    );
+  }
+}
+
+/**
+ * O backend pode rodar NESTE ambiente? (função PURA)
+ *
+ * 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.
+ *
+ * Escape hatch para quem instala o Claude Code no runner:
+ * `SPEC_WAVE_ALLOW_ANTHROPIC_IN_CI=1`.
+ *
+ * @param {'anthropic'|'openrouter'} provider
+ * @param {object} [env]
+ */
+export function assertBackendRunnable(provider, env = process.env) {
+  if (provider !== 'anthropic') return;
+  if (env.GITHUB_ACTIONS !== 'true') return;
+  if (env.SPEC_WAVE_ALLOW_ANTHROPIC_IN_CI) 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' +
+    '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.',
+  );
+}
+
+/**
+ * Executa uma ação de IA no provider 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.
+ *
+ * @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);
+}