@spec-wave/cli 0.15.0 → 0.16.0

package/src/lib/bug-context.mjs

@@ -0,0 +1,160 @@
+// Contexto de implementação de um Bug (RFC-004 §7.1) — puro, testável.
+//
+// A diferença para o contexto de Story não é o formato, é a ORDEM DO TRABALHO.
+// Uma Story tem tasks a executar; um Bug tem um defeito a entender antes de
+// tocar em qualquer coisa. Por isso o contexto impõe quatro fases —
+// reproduzir → causa raiz → fix mínimo → teste de regressão — e a primeira
+// entrega é um teste que FALHA.
+//
+// A ordem existe porque a alternativa é o modo de falha clássico da correção
+// assistida: o executor lê o sintoma, encontra o lugar onde ele se manifesta,
+// remenda ali, e o defeito reaparece na próxima entrada.
+
+import { STAGE_DEVELOPMENT, STAGE_CODE_REVIEW, PROGRESS_IN_PROGRESS } from '../config.mjs';
+
+/**
+ * Monta o markdown do contexto de um Bug (função PURA).
+ *
+ * @param {object} params
+ * @param {{number:number,title:string,body?:string}} params.bug
+ * @param {string|null} [params.bugDoc] conteúdo de docs/bugs/<slug>/bug.md
+ * @param {{number:number,title:string,kind:string}|null} [params.parent]
+ * @param {Array} [params.comments] grupos de comentários (mesmo shape do implement)
+ * @param {string|null} [params.codeDigest]
+ * @param {string[]} [params.blockedByWarnings]
+ * @param {string|null} [params.severity] P0–P3
+ * @returns {string}
+ */
+export function buildBugContext({
+  bug, bugDoc = null, parent = null, comments = [], codeDigest = null,
+  blockedByWarnings = [], severity = null,
+}) {
+  const lines = [];
+  lines.push(`# Contexto de correção — Bug #${bug.number}`);
+  lines.push('');
+  lines.push(`**Bug:** ${bug.title}`);
+  if (severity) lines.push(`**Severidade:** ${severity}`);
+  if (parent) {
+    lines.push(`**Item afetado:** ${parent.kind} #${parent.number} — ${parent.title}`);
+  }
+
+  if (bug.body && bug.body.trim()) {
+    lines.push('');
+    lines.push('## Relato original');
+    lines.push('');
+    lines.push(bug.body.trim());
+  }
+
+  if (blockedByWarnings.length > 0) {
+    lines.push('');
+    lines.push('## ⚠️ Dependências declaradas');
+    for (const w of blockedByWarnings) lines.push(`- ${w}`);
+  }
+
+  lines.push('');
+  lines.push('## Como corrigir (quatro fases, nesta ordem)');
+  lines.push('');
+  lines.push(
+    '> **Não comece pelo fix.** O modo de falha desta tarefa é encontrar o lugar onde o ' +
+    'sintoma aparece, remendar ali, e o defeito voltar na próxima entrada. As fases 1 e 2 ' +
+    'existem para impedir isso.'
+  );
+  lines.push('');
+  lines.push('### 1. Reproduzir');
+  lines.push('');
+  lines.push(
+    'Escreva um teste que **falha** por causa deste defeito, seguindo os passos de reprodução. ' +
+    'Rode-o e confirme que falha **pelo motivo certo** — um teste que falha por erro de ' +
+    'digitação no próprio teste não reproduz nada. Se não conseguir reproduzir, **pare e ' +
+    'reporte**: sem reprodução não há como provar que a correção funcionou.'
+  );
+  lines.push('');
+  lines.push('### 2. Causa raiz');
+  lines.push('');
+  lines.push(
+    'Investigue até a **origem**, não até o lugar onde o erro se manifesta. Um valor nulo ' +
+    'que estoura numa função raramente nasceu ali. Cite arquivo e função. Se o `bug.md` já ' +
+    'traz uma causa raiz, **confirme-a contra o código** antes de aceitar — ela foi escrita ' +
+    'por outro modelo, sem executar nada.'
+  );
+  lines.push('');
+  lines.push('### 3. Fix mínimo');
+  lines.push('');
+  lines.push(
+    'Corrija a causa raiz e **apenas ela**. Um bug é o convite mais comum para refatoração ' +
+    'oportunista: se você vir outros problemas no caminho, **anote-os no comentário final ' +
+    'em vez de corrigi-los** — cada mudança extra aumenta o risco de uma correção que ' +
+    'precisava ser cirúrgica.'
+  );
+  lines.push('');
+  lines.push('### 4. Teste de regressão');
+  lines.push('');
+  lines.push(
+    'O teste da fase 1 agora **passa**. Garanta que ele fica no repositório e que **falharia ' +
+    'de novo** se o fix fosse revertido — essa é a única prova de que ele testa o defeito, e ' +
+    'não outra coisa. Rode a suíte inteira: um fix que quebra outro teste não está pronto.'
+  );
+
+  lines.push('');
+  lines.push('## Ao terminar');
+  lines.push('');
+  lines.push(
+    `1. Commit com a **causa raiz** na mensagem: \`fix: <o que estava errado> (#${bug.number})\`, ` +
+    'e o corpo explicando a origem — não o sintoma.'
+  );
+  lines.push(`2. Abra o Pull Request com \`Fixes #${bug.number}\` no corpo.`);
+  lines.push(
+    `3. O board move sozinho: o Bug sai de **${STAGE_DEVELOPMENT}** (${PROGRESS_IN_PROGRESS}) ` +
+    `para **${STAGE_CODE_REVIEW}** quando o PR abre. Não mova à mão.`
+  );
+
+  if (bugDoc && bugDoc.trim()) {
+    lines.push('');
+    lines.push('---');
+    lines.push('');
+    lines.push('## bug.md — investigação já registrada');
+    lines.push('');
+    lines.push(
+      '> Escrito por IA **sem executar código**. Trate a causa raiz como hipótese a confirmar, ' +
+      'não como fato.'
+    );
+    lines.push('');
+    lines.push(bugDoc.trim());
+  } else {
+    lines.push('');
+    lines.push('---');
+    lines.push('');
+    lines.push(
+      '> **Sem `bug.md`.** A investigação inteira é sua: o relato acima e os comentários são ' +
+      'tudo o que existe.'
+    );
+  }
+
+  if (comments && comments.length > 0) {
+    lines.push('');
+    lines.push('## Comentários da issue');
+    lines.push('');
+    lines.push(
+      '> É onde costuma estar o que faltava no relato original — passos extras, ambiente, ' +
+      'e o retorno de quem reportou. Em conflito, o comentário mais recente prevalece.'
+    );
+    for (const group of comments) {
+      for (const c of group.items || []) {
+        lines.push('');
+        lines.push(`**${c.author || 'desconhecido'}** (${c.createdAt}):`);
+        lines.push('');
+        lines.push(String(c.body || '').trim());
+      }
+    }
+  }
+
+  if (codeDigest) {
+    lines.push('');
+    lines.push('## Digest do código');
+    lines.push('');
+    lines.push(codeDigest);
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}

package/src/lib/bug-doc.mjs

@@ -0,0 +1,51 @@
+// Caminhos e checagem estrutural do bug.md — o artefato do Bug (RFC-004 §5).
+//
+// Fica fora de docs/features/ de propósito: um Bug NÃO é uma Feature e não gera
+// spec.md/plan.md. Manter os dois na mesma pasta faria o `validate` e o
+// `resolveFeaturePaths` da UI tropeçarem num diretório sem os arquivos que
+// esperam.
+//
+// Decisão em função pura, I/O no comando — nada aqui toca o filesystem.
+import path from 'node:path';
+import { slugify } from './slugify.mjs';
+
+/**
+ * Caminhos do bug.md a partir do título da issue (função PURA).
+ *
+ * Devolve o relativo (links, mensagem de commit) e o absoluto ancorado na raiz
+ * do repositório (fs) — o config é procurado subindo na árvore, e os documentos
+ * moram junto dele.
+ *
+ * @param {string} title título da issue (com ou sem o prefixo [BUG])
+ * @param {string} [root] raiz do repositório; ausente = process.cwd()
+ * @returns {{ slug: string, dirRel: string, fileRel: string, dirAbs: string, fileAbs: string }}
+ */
+export function bugDocPaths(title, root = null) {
+  const slug = slugify(title);
+  const dirRel = `docs/bugs/${slug}`;
+  const fileRel = `${dirRel}/bug.md`;
+  const base = root || process.cwd();
+  return {
+    slug,
+    dirRel,
+    fileRel,
+    dirAbs: path.resolve(base, dirRel),
+    fileAbs: path.resolve(base, fileRel),
+  };
+}
+
+/**
+ * Seções obrigatórias ausentes de um documento (função PURA).
+ *
+ * Extraída da duplicação que existia em validate.mjs (um laço idêntico para
+ * spec.md e outro para plan.md). Casa por `# <seção>`, o que aceita qualquer
+ * nível de heading (`##`, `###`) — a checagem é de PRESENÇA, não de hierarquia.
+ *
+ * @param {string} content conteúdo do documento
+ * @param {string[]} sections títulos obrigatórios
+ * @returns {string[]} os que faltam, na ordem declarada
+ */
+export function findMissingSections(content, sections) {
+  const text = String(content || '');
+  return (sections || []).filter(section => !text.includes(`# ${section}`));
+}

package/src/lib/bug-triage.mjs

@@ -0,0 +1,81 @@
+// Decisões da triagem de Bug (RFC-004 §4.1) — puras, testáveis, sem I/O.
+//
+// O portão que estas funções guardam: P2/P3 só entram na fila técnica com o
+// bug.md aprovado. A razão não é burocracia — é que um bug sem causa raiz
+// investigada consome o tempo do dev na investigação que a triagem deveria ter
+// feito, e é aí que "corrigir o sintoma" acontece. P0/P1 são exceção porque
+// esperar o documento custa mais que investigar durante a correção.
+
+import { LABEL_BUG_APPROVED, LABEL_NEEDS_HUMAN, LABEL_CRITIQUE_FAILED } from '../config.mjs';
+
+export const TRIAGE_ACTIONS = ['accept', 'reject', 'duplicate'];
+
+// Severidades que dispensam o bug.md antes da fila.
+const SEVERITY_WITHOUT_DOC = ['P0', 'P1'];
+
+/**
+ * Resolve a ação de triagem informada (função PURA).
+ *
+ * Mesmo contrato de resolveStageName/resolveProgressName: devolve
+ * `{action, error}` em vez de lançar.
+ *
+ * @param {string} input
+ * @returns {{ action: string|null, error: string|null }}
+ */
+export function resolveTriageAction(input) {
+  const key = String(input ?? '').trim().toLowerCase();
+  if (!key) {
+    return { action: null, error: `Informe a ação: ${TRIAGE_ACTIONS.join(', ')}.` };
+  }
+  const match = TRIAGE_ACTIONS.find(a => a === key);
+  return match
+    ? { action: match, error: null }
+    : {
+        action: null,
+        error: `Ação "${input}" não existe. Use uma de: ${TRIAGE_ACTIONS.join(', ')}.`,
+      };
+}
+
+/**
+ * O bug pode ser aceito na fila técnica? (função PURA)
+ *
+ * @param {object} params
+ * @param {string|null} params.severity P0–P3
+ * @param {string[]} params.labels labels da issue
+ * @returns {{ ok: boolean, error: string|null }}
+ */
+export function canAcceptBug({ severity = null, labels = [] } = {}) {
+  const names = labels || [];
+
+  // Portões humanos da crítica valem para qualquer severidade: aceitar um bug
+  // cujo documento foi reprovado é justamente o que o portão existe para evitar.
+  if (names.includes(LABEL_NEEDS_HUMAN)) {
+    return {
+      ok: false,
+      error:
+        `A crítica reprovou repetidas vezes e \`${LABEL_NEEDS_HUMAN}\` está aplicada. ` +
+        'Revise o bug.md e remova a label antes de aceitar.',
+    };
+  }
+  if (names.includes(LABEL_CRITIQUE_FAILED)) {
+    return {
+      ok: false,
+      error:
+        `A crítica adversarial apontou problemas graves (\`${LABEL_CRITIQUE_FAILED}\`). ` +
+        'Corrija o bug.md e remova a label antes de aceitar.',
+    };
+  }
+
+  if (SEVERITY_WITHOUT_DOC.includes(severity)) return { ok: true, error: null };
+
+  if (!names.includes(LABEL_BUG_APPROVED)) {
+    return {
+      ok: false,
+      error:
+        `Bug ${severity || 'sem severidade'} exige o bug.md validado antes da fila técnica. ` +
+        'Aplique `spec-wave:bug` para gerá-lo e `spec-wave:ready` para validá-lo — ' +
+        'ou reclassifique a severidade com --severity se for urgente.',
+    };
+  }
+  return { ok: true, error: null };
+}

package/src/lib/claude.mjs

@@ -5,6 +5,8 @@ import {
   DEFAULT_MAX_CRITIQUE_ATTEMPTS, labelNames,
 } from '../config.mjs';
 import { lintLanguage } from './output-lint.mjs';
+import { runAgent } from '../agent/index.mjs';
+import { TruncatedOutputError, isTruncationReason } from '../agent/errors.mjs';
 import { computeCost } from './usage-report.mjs';
 import { findConfigPath } from './project-root.mjs';
 
@@ -180,33 +182,11 @@ export async function withRetry(label, fn, { attempts = RETRY_ATTEMPTS, baseMs =
   throw lastErr;
 }
 
-// Truncamento: os dois provedores dizem explicitamente que cortaram a saída no
-// teto de tokens — OpenRouter (formato OpenAI) em `choices[0].finish_reason`,
-// 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;
-  }
-}
+// `TruncatedOutputError` e `isTruncationReason` saíram daqui para
+// `agent/errors.mjs` quando os backends portados passaram a precisar deles.
+// Re-exportados para não quebrar os 5 consumidores e os testes que importam
+// deste módulo.
+export { TruncatedOutputError, isTruncationReason };
 
 // Os parâmetros de sampling foram REMOVIDOS a partir do Claude Opus 4.7 (vale
 // para 4.8 e 5, Sonnet 5, Fable 5 e Mythos 5): enviar temperature/top_p/top_k
@@ -234,67 +214,11 @@ export function supportsStrictSchema(model) {
   return MODELS_WITH_STRICT_SCHEMA.test(model || '');
 }
 
-/**
- * Corpo EXATO de `client.messages.create` (função PURA — testável sem HTTP).
- *
- * Com `schema`, força a ferramenta via tool_choice: o modelo não tem como
- * responder em texto livre, que é o que produzia JSON sujo na crítica.
- * `disable_parallel_tool_use` garante no máximo um bloco tool_use.
- */
-export function buildAnthropicRequest({
-  ai, systemPrompt, userContent, temperature, maxTokens, schema, strict,
-}) {
-  return {
-    model: ai.model,
-    max_tokens: maxTokens,
-    // Omitida nos modelos que removeram sampling (Opus 4.7+, Sonnet 5, Fable 5):
-    // enviá-la devolve 400.
-    ...(temperature === undefined ? {} : { temperature }),
-    messages: [{ role: 'user', content: userContent }],
-    system: systemPrompt,
-    ...(schema ? {
-      tools: [{
-        name: schema.name,
-        description: schema.description,
-        input_schema: schema.jsonSchema,
-        ...(strict ? { strict: true } : {}),
-      }],
-      tool_choice: { type: 'tool', name: schema.name, disable_parallel_tool_use: true },
-    } : {}),
-  };
-}
+// `buildAnthropicRequest` e `buildOpenRouterBody` foram REMOVIDOS: quem monta
+// a requisição agora é o motor (`src/agent/`). No backend openrouter isso é
+// `buildChatCompletionBody`; no anthropic, o subprocesso do Claude Code monta
+// a própria — este processo não fala com a API da Anthropic.
 
-/**
- * Corpo EXATO do POST da OpenRouter (função PURA — testável sem HTTP).
- *
- * `provider.require_parameters` é obrigatório junto do response_format: sem ele o
- * roteador escolhe endpoints que IGNORAM o schema e devolvem prosa, e o erro só
- * apareceria no JSON.parse, três retries depois. Com ele, a recusa é imediata e
- * a mensagem diz o que trocar.
- */
-export function buildOpenRouterBody({
-  ai, systemPrompt, userContent, temperature, maxTokens, schema,
-}) {
-  return {
-    model: ai.model,
-    max_tokens: maxTokens,
-    // Omitida nos modelos que removeram sampling (Opus 4.7+, Sonnet 5, Fable 5).
-    ...(temperature === undefined ? {} : { temperature }),
-    messages: [
-      { role: 'system', content: systemPrompt },
-      { role: 'user', content: userContent },
-    ],
-    // Pede o bloco `usage` completo na resposta (inclui `cost` em USD).
-    usage: { include: true },
-    ...(schema ? {
-      response_format: {
-        type: 'json_schema',
-        json_schema: { name: schema.name, strict: true, schema: schema.jsonSchema },
-      },
-      provider: { require_parameters: true },
-    } : {}),
-  };
-}
 
 // temperature padrão 0.2 (RFC-002 §5): "Determinism over Creativity". Pode ser
 // sobrescrita por chamada via opts, mas o default cobre spec/plan/decompose.
@@ -333,11 +257,14 @@ export async function generateDocument(systemPrompt, userContent, opts = {}) {
     const callOpts = {
       temperature: sendTemperature ? temperature : undefined,
       maxTokens,
+      action: opts.action,
+      // É aqui que o motor paga por si: o modelo passa a poder LER o
+      // repositório antes de escrever o documento. É o que os blocos
+      // `requires-tools` dos model-prompt sempre descreveram.
+      tools: opts.tools ?? ['Read', 'Glob', 'Grep'],
     };
     const { text, usage } = await withRetry(`Geração via ${ai.provider}`, () =>
-      ai.provider === 'openrouter'
-        ? generateWithOpenRouter(system, userContent, ai, callOpts)
-        : generateWithAnthropic(system, userContent, ai, callOpts));
+      generateViaEngine(system, userContent, ai, callOpts));
     inputTokens += usage.inputTokens;
     outputTokens += usage.outputTokens;
     if (typeof usage.cost === 'number') cost = (cost ?? 0) + usage.cost;
@@ -441,14 +368,13 @@ export async function generateStructured(systemPrompt, userContent, opts = {}) {
     maxTokens,
     schema,
     strict,
+    action: opts.action,
   };
 
   // A validação roda DENTRO do retry de propósito: um payload fora do schema é
   // marcado como transitório, e repetir a mesma requisição costuma resolver.
   const { value, usage } = await withRetry(`Geração estruturada via ${ai.provider}`, async () => {
-    const res = ai.provider === 'openrouter'
-      ? await generateWithOpenRouter(systemPrompt, userContent, ai, callOpts)
-      : await generateWithAnthropic(systemPrompt, userContent, ai, callOpts);
+    const res = await generateViaEngine(systemPrompt, userContent, ai, callOpts);
     return { value: schema.validate ? schema.validate(res.json) : res.json, usage: res.usage };
   }, opts.retry);
 
@@ -506,181 +432,72 @@ export function extractOpenRouterUsage(usage) {
   };
 }
 
-async function generateWithAnthropic(
-  systemPrompt, userContent, ai, { temperature, maxTokens, schema, strict }
+/**
+ * Ponte para o motor do agente (`src/agent/`).
+ *
+ * Substitui as duas funções que falavam com a API diretamente
+ * (`generateWithAnthropic` / `generateWithOpenRouter`). O motor foi portado do
+ * agent-cli e traz o que o caminho direto não tinha: loop agêntico com
+ * Read/Glob/Grep de verdade e instrumentação Langfuse.
+ *
+ * Tudo o que já estava CERTO neste módulo continua acima desta linha —
+ * resolução de modelo por ação/label, retry, lint de idioma, contagem de uso.
+ * O motor cuida da chamada; este arquivo segue dono da política.
+ *
+ * O prompt do sistema vira `systemPromptAppend` de propósito: no backend
+ * anthropic ele é ANEXADO ao preset `claude_code`, preservando a competência de
+ * uso de tools do harness em vez de substituí-la.
+ *
+ * @returns {Promise<{text: string, json?: object, usage: object}>}
+ */
+async function generateViaEngine(
+  systemPrompt, userContent, ai, { temperature, maxTokens, schema, strict, action, tools },
 ) {
-  const apiKey = process.env.ANTHROPIC_API_KEY;
-  if (!apiKey) {
-    throw new Error(
-      'ANTHROPIC_API_KEY not set.\n' +
-      'Add it as a GitHub Actions secret or set it in your environment.'
-    );
-  }
+  const result = await runAgent(userContent, {
+    provider: ai.provider,
+    model: ai.model,
+    systemPromptAppend: systemPrompt,
+    // Sessão/usuário alimentam o agrupamento das traces no Langfuse. Sem
+    // telemetria configurada nada disso sai do processo.
+    sessionId: `spec-wave-${action || 'run'}`,
+    userId: 'spec-wave',
+    ...(tools ? { tools } : {}),
+    ...(maxTokens ? { maxTokens } : {}),
+    ...(temperature !== undefined ? { temperature } : {}),
+    ...(schema
+      ? { responseSchema: { ...schema, strict: strict === true } }
+      : {}),
+    ...(action ? { action, extraTags: [action] } : {}),
+    cwd: ai.cwd ?? process.cwd(),
+    quiet: true,
+  });
 
-  const client = new Anthropic({ apiKey });
-  const message = await client.messages.create(buildAnthropicRequest({
-    ai, systemPrompt, userContent, temperature, maxTokens, schema, strict,
-  }));
-
-  // A resposta nem sempre começa com um bloco de texto (recusa, resposta vazia):
-  // `content[0].text` cru virava TypeError com mensagem inútil.
-  const text = (message.content || [])
-    .filter((block) => block.type === 'text')
-    .map((block) => block.text)
-    .join('');
-  // Com tool_choice forçado a resposta traz um bloco tool_use e NENHUM bloco de
-  // texto — daí a necessidade do branch dedicado antes da checagem de texto vazio.
-  const tool = (message.content || [])
-    .find((block) => block.type === 'tool_use' && block.name === schema?.name);
-
-  if (message.stop_reason === 'refusal') {
-    throw new Error(
-      `A Anthropic recusou a requisição (stop_reason=refusal` +
-      `${message.stop_details?.category ? `, categoria=${message.stop_details.category}` : ''}). ` +
-      'Revise o conteúdo da issue de origem.'
-    );
-  }
-  if (message.stop_reason === 'model_context_window_exceeded') {
-    // Estouro na ENTRADA — subir max_tokens não resolve; o que precisa encolher
-    // é a issue/contexto enviado.
-    throw new Error(
-      `Contexto de entrada excedido (${ai.model}). Reduza o tamanho da issue de origem ` +
-      'ou do tech_context antes de repetir.'
-    );
-  }
-  if (isTruncationReason(message.stop_reason)) {
-    throw new TruncatedOutputError({
-      provider: 'anthropic',
-      model: ai.model,
-      maxTokens,
-      reason: message.stop_reason,
-      // Sob tool call forçado não há bloco de texto: medir `text.length` diria
-      // sempre "~0 caracteres antes do corte".
-      chars: schema ? JSON.stringify(tool?.input ?? '').length : text.length,
-    });
-  }
+  const usage = {
+    inputTokens: result.usage?.inputTokens ?? 0,
+    outputTokens: result.usage?.outputTokens ?? 0,
+    cost: result.costUsd,
+  };
 
-  // ATENÇÃO: este branch precisa vir ANTES da checagem de `!text` — uma resposta
-  // com tool call forçado não tem bloco de texto, e cair no `!text` faria toda
-  // crítica queimar os 3 retries com a mensagem errada.
   if (schema) {
-    if (!tool || typeof tool.input !== 'object' || tool.input === null) {
+    if (result.structured === null || result.structured === undefined) {
       const err = new Error(
-        `A Anthropic não devolveu a ferramenta \`${schema.name}\` ` +
-        `(stop_reason=${message.stop_reason}). Conteúdo: ${text.slice(0, 200) || '(vazio)'}`
+        `O modelo ${ai.model} não devolveu a saída estruturada "${schema.name}" ` +
+        `(subtype=${result.resultSubtype}).`
       );
-      err.transient = true; // ferramenta forçada: repetir a requisição costuma resolver
+      err.transient = true; // repetir a mesma requisição costuma resolver
       throw err;
     }
-    return {
-      text: JSON.stringify(tool.input),
-      json: tool.input,
-      usage: extractAnthropicUsage(message.usage),
-    };
+    return { text: result.outputText, json: result.structured, usage };
   }
 
+  const text = stripReasoning(result.outputText || '');
   if (!text) {
     const err = new Error(
-      `A Anthropic retornou resposta sem texto (stop_reason=${message.stop_reason}).`
-    );
-    err.transient = true;
-    throw err;
-  }
-
-  return { text, usage: extractAnthropicUsage(message.usage) };
-}
-
-async function generateWithOpenRouter(
-  systemPrompt, userContent, ai, { temperature, maxTokens, schema }
-) {
-  const apiKey = process.env.OPENROUTER_API_KEY;
-  if (!apiKey) {
-    throw new Error(
-      'OPENROUTER_API_KEY not set.\n' +
-      'Add it as a GitHub Actions secret or set it in your environment.'
-    );
-  }
-
-  const res = await fetch('https://openrouter.ai/api/v1/chat/completions', {
-    method: 'POST',
-    headers: {
-      Authorization: `Bearer ${apiKey}`,
-      'Content-Type': 'application/json',
-      'HTTP-Referer': 'https://github.com/moacsjr/spec-wave',
-      'X-Title': 'spec-wave',
-    },
-    body: JSON.stringify(buildOpenRouterBody({
-      ai, systemPrompt, userContent, temperature, maxTokens, schema,
-    })),
-  });
-
-  if (!res.ok) {
-    const body = await res.text();
-    const err = new Error(
-      `OpenRouter API ${res.status}: ${body}` +
-      // require_parameters faz o roteador recusar quando nenhum provedor do modelo
-      // implementa response_format — erro de CONFIGURAÇÃO, não de rede.
-      (schema && (res.status === 404 || res.status === 400)
-        ? `\nNenhum provedor de ${ai.model} suporta response_format/json_schema. ` +
-          'Aponte `ai.models.critique` no .spec-wave.json para um modelo com saída estruturada.'
-        : '')
-    );
-    err.status = res.status;
-    throw err;
-  }
-
-  // Um 200 com corpo vazio ou cortado acontece em gerações longas. `res.json()`
-  // cru lançaria "Unexpected end of JSON input" — mensagem que não diz nada a
-  // quem está olhando o board. Lê como texto, reporta o que veio e marca como
-  // transitória para o retry pegar.
-  const raw = await res.text();
-  let data;
-  try {
-    data = JSON.parse(raw);
-  } catch {
-    const err = new Error(
-      `OpenRouter devolveu ${res.status} com corpo inválido (${raw.length} bytes): ` +
-      `${raw.slice(0, 200) || '(vazio)'}`
+      `O provider ${ai.provider} retornou resposta sem texto ` +
+      `(subtype=${result.resultSubtype}, turnos=${result.numTurns}).`
     );
     err.transient = true;
     throw err;
   }
-
-  const choice = data?.choices?.[0];
-  const content = stripReasoning(choice?.message?.content || '');
-
-  // finish_reason='length' = cortado no teto. Checado ANTES do conteúdo vazio:
-  // um corte durante o raciocínio devolve texto vazio, e "resposta vazia" (que
-  // é tratada como transitória) esconderia a causa real por trás de 3 retries.
-  if (isTruncationReason(choice?.finish_reason)) {
-    throw new TruncatedOutputError({
-      provider: 'openrouter',
-      model: ai.model,
-      maxTokens,
-      // native_finish_reason preserva o motivo cru do provedor upstream.
-      reason: `${choice.finish_reason}${choice.native_finish_reason ? `/${choice.native_finish_reason}` : ''}`,
-      chars: content.length,
-    });
-  }
-  if (!content) {
-    const err = new Error(`OpenRouter retornou resposta vazia: ${JSON.stringify(data)}`);
-    err.transient = true;
-    throw err;
-  }
-
-  if (schema) {
-    const raw = stripOuterFence(content);
-    try {
-      return { text: raw, json: JSON.parse(raw), usage: extractOpenRouterUsage(data.usage) };
-    } catch {
-      const err = new Error(
-        `O modelo ${ai.model} ignorou response_format e devolveu texto não-JSON ` +
-        `(${raw.length} bytes): ${raw.slice(0, 200)}`
-      );
-      err.transient = true; // ≠ truncamento: repetir pode dar certo
-      throw err;
-    }
-  }
-
-  return { text: content, usage: extractOpenRouterUsage(data.usage) };
+  return { text, usage };
 }