@spec-wave/cli 0.18.1 → 0.20.0

package/src/commands/repair-stage.mjs

@@ -0,0 +1,232 @@
+// Reparo de Etapa — a saída para quando a AUTOMAÇÃO erra.
+//
+// O fluxo normal é `move`, e nele a Etapa só avança: essa regra existe porque
+// board que retrocede sozinho vira board em que ninguém confia. Mas a automação
+// erra. Uma corrida entre o `decompose-apply` e o `code-review` pôs duas Stories
+// fundacionais e duas Tasks em 🎉 Done no instante em que nasceram, e o `move`
+// recusou desfazer — a única saída foi mutação GraphQL crua no campo do Project.
+//
+// Isso é pior que ter o comando: quem consegue montar a mutação à mão consegue
+// fazer qualquer coisa no board, sem confirmação e sem deixar rastro. Aqui o
+// preço é explícito e o registro é obrigatório:
+//
+//   • --yes e --reason são exigidos (sem os dois, recusa);
+//   • em terminal interativo, ainda pede a confirmação digitada;
+//   • cada reparo vira um comentário na issue dizendo quem, de onde e por quê.
+//
+// Não existe label nem workflow para isto de propósito: reparo é ato humano
+// deliberado, não automação.
+import * as p from '@clack/prompts';
+import chalk from 'chalk';
+import { resolveToken } from '../api/auth.mjs';
+import { getIssue, commentOnIssue } from '../api/github-rest.mjs';
+import { verifyTokenScopes } from '../api/auth.mjs';
+import { detectIssueType } from '../lib/issue-type.mjs';
+import { loadProjectConfig, resolveField, setItemStage, resolveStageName } from '../lib/board.mjs';
+import { loadConfig } from '../lib/project-root.mjs';
+import { resolveProgressName } from './move.mjs';
+import { CONFIG_FILE } from '../config.mjs';
+
+/**
+ * Lista de issues a reparar (função PURA).
+ *
+ * Aceita "529", "#529", "529,530" e "#529, #530" — o incidente que motivou o
+ * comando pegou sete itens de uma vez, e obrigar a sete invocações seria pedir
+ * para alguém desistir no meio.
+ *
+ * @param {string|number} input
+ * @returns {{ numbers: number[], error: string|null }}
+ */
+export function parseIssueList(input) {
+  const raw = String(input ?? '').split(',').map(s => s.trim()).filter(Boolean);
+  if (raw.length === 0) return { numbers: [], error: 'Informe ao menos uma issue (ex.: 529 ou 529,530).' };
+  const numbers = [];
+  for (const item of raw) {
+    const n = parseInt(item.replace('#', ''), 10);
+    if (!Number.isInteger(n) || n <= 0) {
+      return { numbers: [], error: `Issue inválida: "${item}". Use o número da issue, ex.: 529 ou #529.` };
+    }
+    if (!numbers.includes(n)) numbers.push(n);
+  }
+  return { numbers, error: null };
+}
+
+/**
+ * O reparo pode prosseguir? (função PURA — é a trava do comando).
+ *
+ * Recusa sem `--yes` OU sem `--reason` com conteúdo. A mensagem diz o comando
+ * completo: quem chegou aqui está consertando um estrago e não deve ter que
+ * caçar a sintaxe.
+ *
+ * @param {{ yes?: boolean, reason?: string }} options
+ * @returns {{ ok: boolean, error: string|null }}
+ */
+export function checkRepairGuards({ yes = false, reason = '' } = {}) {
+  const motivo = String(reason || '').trim();
+  if (!yes || !motivo) {
+    const faltando = [!yes ? '--yes' : null, !motivo ? '--reason "<motivo>"' : null].filter(Boolean);
+    return {
+      ok: false,
+      error:
+        `Reparo de Etapa exige ${faltando.join(' e ')}.\n` +
+        'A Etapa só avança no fluxo normal — reparar é exceção, e fica registrado na issue.\n' +
+        'Ex.: spec-wave repair-stage 529,530 ready --yes --reason "corrida do decompose-apply com o code-review"',
+    };
+  }
+  return { ok: true, error: null };
+}
+
+/**
+ * Comentário de auditoria do reparo (função PURA).
+ *
+ * Sem isto o reparo é indistinguível de uma mutação manual — e a razão de o
+ * comando existir é justamente deixar rastro.
+ */
+export function renderRepairComment({ from, to, status, reason, actor, version }) {
+  return [
+    '🛠️ **Etapa reparada manualmente** (`spec-wave repair-stage`)',
+    '',
+    `- **De:** ${from || '(sem etapa)'}`,
+    `- **Para:** ${to}${status ? ` · Status **${status}**` : ''}`,
+    `- **Por:** ${actor ? `@${actor}` : '(usuário do token)'}`,
+    `- **Motivo:** ${String(reason).trim()}`,
+    '',
+    `_A Etapa não retrocede pelo fluxo normal; este reparo foi explícito${version ? ` · spec-wave ${version}` : ''}._`,
+  ].join('\n');
+}
+
+export async function repairStage(issuesArg, stageArg, options = {}) {
+  const { numbers, error: listError } = parseIssueList(issuesArg);
+  if (listError) {
+    p.log.error(listError);
+    process.exitCode = 1;
+    return;
+  }
+
+  const { stage, error: stageError } = resolveStageName(stageArg);
+  if (stageError) {
+    p.log.error(stageError);
+    process.exitCode = 1;
+    return;
+  }
+
+  // Sem --status o Status não é tocado: no reparo, mexer no que não foi pedido
+  // é justamente o que se está consertando.
+  let status = null;
+  if (options.status !== undefined && options.status !== null && String(options.status).trim() !== '') {
+    const resolved = resolveProgressName(options.status);
+    if (resolved.error) {
+      p.log.error(resolved.error);
+      process.exitCode = 1;
+      return;
+    }
+    status = resolved.status;
+  }
+
+  const guards = checkRepairGuards(options);
+  if (!guards.ok && !options.dryRun) {
+    p.log.error(guards.error);
+    process.exitCode = 1;
+    return;
+  }
+
+  const [envOwner, envRepo] = (process.env.GITHUB_REPOSITORY || '').split('/');
+  const { config, root } = loadConfig();
+  const owner = envOwner || config?.owner;
+  const repo = envRepo || config?.repo;
+  if (!owner || !repo) {
+    p.log.error(
+      'Não foi possível determinar owner/repo.\n' +
+      `Rode dentro de um repositório com ${CONFIG_FILE} (\`spec-wave init\`) ou defina GITHUB_REPOSITORY=owner/repo.`
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  let token;
+  try {
+    token = await resolveToken();
+  } catch (err) {
+    p.log.error(err.message);
+    process.exitCode = 1;
+    return;
+  }
+
+  p.intro(chalk.bold(
+    `spec-wave repair-stage ${numbers.map(n => `#${n}`).join(', ')} → ${stage}${options.dryRun ? ' (dry-run)' : ''}`
+  ));
+
+  const { project, error: projectError } = loadProjectConfig({ cwd: root || process.cwd() });
+  if (projectError) {
+    p.log.error(`${projectError} — nada a reparar. Rode \`spec-wave init\` (ou \`spec-wave refresh --config\`).`);
+    process.exitCode = 1;
+    return;
+  }
+  const etapaField = await resolveField(token, project, 'Etapa').catch(() => null);
+  const statusField = status ? await resolveField(token, project, 'Status').catch(() => null) : null;
+
+  // Lê tudo ANTES de escrever qualquer coisa: reparo parcial por issue
+  // inexistente no meio da lista é o tipo de surpresa que ninguém quer aqui.
+  const alvos = [];
+  for (const n of numbers) {
+    try {
+      const issue = await getIssue(token, owner, repo, n);
+      alvos.push({ number: n, issue, type: detectIssueType(issue) });
+    } catch (err) {
+      p.log.error(`Não foi possível ler a issue #${n}: ${err.message}`);
+      process.exitCode = 1;
+      return;
+    }
+  }
+
+  for (const alvo of alvos) {
+    p.log.info(`#${alvo.number} ${alvo.type ? `(${alvo.type}) ` : ''}${alvo.issue.title}`);
+  }
+
+  if (options.dryRun) {
+    p.log.warn(
+      `Dry-run: ${alvos.length} item(ns) seriam movidos para "${stage}"` +
+      `${status ? ` / Status "${status}"` : ''}, com comentário de auditoria em cada issue.`
+    );
+    p.outro('Nada foi alterado.');
+    return;
+  }
+
+  // Confirmação digitada, além do --yes: em terminal, a chance de o comando ter
+  // vindo de um histórico ou de um copiar-colar é real.
+  if (process.stdin.isTTY) {
+    const esperado = `repair ${alvos.map(a => `#${a.number}`).join(' ')}`;
+    const digitado = await p.text({
+      message: `Confirme digitando: ${esperado}`,
+      placeholder: esperado,
+    });
+    if (p.isCancel(digitado) || String(digitado).trim() !== esperado) {
+      p.cancel('Reparo cancelado — nada foi alterado.');
+      process.exitCode = 1;
+      return;
+    }
+  }
+
+  // Login do token para o registro. Best-effort: falhar aqui não pode impedir o
+  // reparo, mas o comentário fica sem o "quem".
+  const actor = await verifyTokenScopes(token).then(i => i.login).catch(() => null);
+  const version = process.env.npm_package_version || null;
+
+  let reparados = 0;
+  for (const alvo of alvos) {
+    try {
+      const { from } = await setItemStage(
+        token, project, etapaField, statusField, alvo.issue.node_id, stage, status);
+      reparados += 1;
+      p.log.success(`#${alvo.number}: ${from || '(sem etapa)'} → ${chalk.bold(stage)}${status ? ` / ${status}` : ''}`);
+      await commentOnIssue(token, owner, repo, alvo.number, renderRepairComment({
+        from, to: stage, status, reason: options.reason, actor, version,
+      })).catch(err => p.log.warn(`#${alvo.number}: reparo aplicado, mas o registro falhou: ${err.message}`));
+    } catch (err) {
+      p.log.error(`#${alvo.number}: falha ao reparar — ${err.message}`);
+      process.exitCode = 1;
+    }
+  }
+
+  p.outro(`${chalk.green('✓')} ${reparados}/${alvos.length} item(ns) reparado(s) e registrado(s).`);
+}

package/src/commands/update.mjs

@@ -4,7 +4,7 @@ import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { homedir } from 'node:os';
 import path from 'node:path';
 import { resolveToken } from '../api/auth.mjs';
-import { CONFIG_FILE, WORKFLOW_FILES, ISSUE_TEMPLATE_FILES, ALL_LABELS } from '../config.mjs';
+import { CONFIG_FILE, WORKFLOW_FILES, ISSUE_TEMPLATE_FILES, ALL_LABELS, allLabelsFor } from '../config.mjs';
 import { getProjectSnapshot } from '../api/github-graphql.mjs';
 import {
   getFileContent, upsertFile, listLabels, createLabel, updateLabel, deleteLabel,
@@ -80,14 +80,22 @@ function applySkill(job) {
  * 0.13.0 mas ainda presente em todo repo inicializado com a 0.12.0. Só o
  * namespace `spec-wave:` é considerado: labels do time não são da nossa conta.
  *
+ * As labels de modelo (`spec-wave:model:<apelido>`) entram pelo `fileAi`: são
+ * derivadas de `ai.modelAliases`, e tratá-las como desconhecidas fazia o update
+ * APAGAR justamente o override de modelo por issue — o mecanismo que destrava
+ * uma Feature que não gera plano no modelo default. Passar o bloco `ai` também
+ * é o que faz o update CRIÁ-LAS, em vez de exigir `gh label create` à mão.
+ *
  * @param {Array<{name,color,description}>} existing labels do repo
+ * @param {object} [fileAi] bloco `ai` do .spec-wave.json
  * @returns {{ missing: object[], changed: object[], orphan: object[] }}
  */
-export function diffLabels(existing) {
+export function diffLabels(existing, fileAi) {
+  const wanted = allLabelsFor(fileAi);
   const byName = new Map((existing || []).map(l => [l.name, l]));
   const missing = [];
   const changed = [];
-  for (const label of ALL_LABELS) {
+  for (const label of wanted) {
     const cur = byName.get(label.name);
     if (!cur) {
       missing.push(label);
@@ -98,7 +106,7 @@ export function diffLabels(existing) {
       changed.push(label);
     }
   }
-  const known = new Set(ALL_LABELS.map(l => l.name));
+  const known = new Set(wanted.map(l => l.name));
   const orphan = (existing || []).filter(l => l.name?.startsWith('spec-wave:') && !known.has(l.name));
   return { missing, changed, orphan };
 }
@@ -266,7 +274,7 @@ export async function update(options = {}) {
           if (remote === null) repoFiles.push({ ...f, reason: 'ausente', local });
           else if (remote !== local) repoFiles.push({ ...f, reason: 'desatualizado', local });
         }
-        labelDiff = diffLabels(await listLabels(tk, owner, repo));
+        labelDiff = diffLabels(await listLabels(tk, owner, repo), config?.ai);
         repoChecked = true;
         s.stop('Repositório comparado.');
       } catch (err) {

package/src/config.mjs

@@ -372,6 +372,49 @@ export const TRIGGER_LABELS = [
 
 export const ALL_LABELS = [...TYPE_LABELS, ...PRIORITY_LABELS, ...TRIGGER_LABELS];
 
+/**
+ * Labels de override de modelo, derivadas de `ai.modelAliases` (função PURA).
+ *
+ * Estas NÃO cabem em ALL_LABELS: o conjunto depende do .spec-wave.json de cada
+ * repo. Tratá-las como estáticas produziu dois defeitos simétricos:
+ *
+ *  • o `update` (que remove toda `spec-wave:*` fora da lista conhecida) e o
+ *    `doctor` acusavam TODO alias configurado como label descontinuada, com o
+ *    conselho de apagá-la — apagar quebra o override de modelo por issue, que é
+ *    justamente o que destrava uma Feature que não gera plano no modelo default;
+ *  • o `init`/`update` nunca as criavam, então usar o mecanismo exigia
+ *    `gh label create` à mão, um por alias.
+ *
+ * É a mesma armadilha que já tinha apagado a `spec-wave:dev-agent` (ver
+ * LABEL_DEV_AGENT), com um agravante: ali bastou registrar a label na lista, e
+ * aqui a lista não pode ser fixa.
+ *
+ * @param {object} [modelAliases] bloco `ai.modelAliases` do .spec-wave.json
+ * @returns {Array<{name: string, color: string, description: string}>}
+ */
+export function modelLabels(modelAliases) {
+  if (!modelAliases || typeof modelAliases !== 'object') return [];
+  return Object.entries(modelAliases)
+    .filter(([alias, model]) => alias.trim() && typeof model === 'string' && model.trim())
+    .map(([alias, model]) => ({
+      name: `${MODEL_LABEL_PREFIX}${alias}`,
+      color: '5319E7',
+      description: `Gera esta issue com ${model.trim()}`,
+    }));
+}
+
+/**
+ * Labels do fluxo + as de modelo deste repo (função PURA).
+ *
+ * É este o conjunto que `update`, `doctor` e `init` devem usar — ALL_LABELS
+ * sozinha é incompleta em qualquer repo que configure `ai.modelAliases`.
+ *
+ * @param {object} [fileAi] bloco `ai` do .spec-wave.json
+ */
+export function allLabelsFor(fileAi) {
+  return [...ALL_LABELS, ...modelLabels(fileAi?.modelAliases)];
+}
+
 /**
  * Nomes das labels de uma issue (função PURA).
  *

package/src/lib/board.mjs

@@ -147,6 +147,50 @@ export async function advanceToStage(token, project, etapaField, statusField, no
   return true;
 }
 
+/**
+ * Escreve a Etapa IGNORANDO a regra de avanço — reparo, não fluxo.
+ *
+ * `advanceToStage` continua sendo o único caminho do fluxo, e continua sem
+ * escape hatch: a Etapa só avança. Esta função existe porque a automação erra —
+ * uma corrida entre o `decompose-apply` e o `code-review` já pôs duas Stories e
+ * duas Tasks em 🎉 Done no nascimento — e a única saída era mutação GraphQL
+ * crua: sem trava, sem confirmação e sem rastro. Um caminho com as três é
+ * melhor que a mão livre.
+ *
+ * Quem chama (`repair-stage`) é responsável pela confirmação e pelo registro na
+ * issue. Aqui só se escreve.
+ *
+ * @param {string} token token com scope project
+ * @param {object} project bloco project (precisa de .id)
+ * @param {{id,options}|null} etapaField campo "Etapa" (ver resolveField)
+ * @param {{id,options}|null} statusField campo nativo "Status"
+ * @param {string} nodeId node id da issue
+ * @param {string} targetStage etapa de destino (precisa existir em STAGE_ORDER)
+ * @param {string} [targetStatus] valor do Status; omitido = não mexe no Status
+ * @returns {Promise<{ from: string|null }>} etapa em que o item estava
+ */
+export async function setItemStage(token, project, etapaField, statusField, nodeId, targetStage, targetStatus) {
+  if (!etapaField?.id) throw new Error('Campo "Etapa" não encontrado no Project — nada a reparar.');
+  if (STAGE_ORDER.indexOf(targetStage) === -1) {
+    throw new Error(`Etapa "${targetStage}" não faz parte do fluxo (${STAGE_ORDER.join(' → ')}).`);
+  }
+  const optionId = etapaField.options?.[targetStage];
+  if (!optionId) {
+    throw new Error(
+      `A opção "${targetStage}" não existe no campo Etapa deste Project. ` +
+      'Rode `spec-wave refresh --config` para sincronizar os ids.'
+    );
+  }
+  const itemId = await addProjectItem(token, project.id, nodeId);
+  const from = await getItemSingleSelectValue(token, itemId, etapaField.id).catch(() => null);
+  await setItemSingleSelect(token, project.id, itemId, etapaField.id, optionId);
+  if (statusField?.id && targetStatus) {
+    const statusOption = statusField.options?.[targetStatus];
+    if (statusOption) await setItemSingleSelect(token, project.id, itemId, statusField.id, statusOption);
+  }
+  return { from };
+}
+
 /**
  * Define APENAS o Status nativo (Todo/In Progress/Done) de um item, sem tocar
  * na Etapa — usado para marcar progresso dentro da etapa atual.

package/src/lib/claude.mjs

@@ -6,7 +6,7 @@ import {
 } from '../config.mjs';
 import { lintLanguage } from './output-lint.mjs';
 import { runAgent } from '../agent/index.mjs';
-import { TruncatedOutputError, isTruncationReason } from '../agent/errors.mjs';
+import { TruncatedOutputError, MaxTurnsError, isTruncationReason } from '../agent/errors.mjs';
 import { computeCost } from './usage-report.mjs';
 import { findConfigPath } from './project-root.mjs';
 
@@ -17,12 +17,21 @@ import { findConfigPath } from './project-root.mjs';
 // branco. Ajustável por `ai.maxTokens` / `ai.maxTokensByAction`.
 export const DEFAULT_MAX_TOKENS = 32768;
 
-// Teto padrão POR AÇÃO, aplicado abaixo de `ai.maxTokens` na precedência. A
-// crítica devolve uma lista JSON de findings, muito menor que um spec/plan —
-// 8192 é folgado para ela. Antes esse valor era passado hard-coded pelo
-// critique.mjs, o que sobrepunha `ai.maxTokensByAction.critique` e tornava o
-// knob morto; aqui ele é só um DEFAULT, então a configuração volta a valer.
-export const MAX_TOKENS_BY_ACTION = { critique: 8192 };
+// Teto padrão POR AÇÃO, aplicado abaixo de `ai.maxTokens` na precedência.
+//
+// A crítica JÁ TEVE um default próprio de 8192, com o raciocínio de que a saída
+// (uma lista JSON de findings) é muito menor que um spec/plan. O raciocínio
+// estava certo sobre a SAÍDA e errado sobre o CUSTO: em modelo que raciocina por
+// padrão, o pensamento consome o mesmo teto antes de a primeira linha da
+// resposta sair. O corte vira TruncatedOutputError (os dois backends falham
+// alto, e isso está certo) — mas o efeito prático é a crítica não concluir numa
+// etapa cujo propósito é justamente barrar problema, e a rodada se perde.
+//
+// `max_tokens` é TETO, não consumo: deixar a crítica herdar DEFAULT_MAX_TOKENS
+// não encarece nada em modelo sem raciocínio, e é o que evita o corte no que
+// raciocina. A tabela fica aqui, vazia, para o caso de alguma ação futura
+// precisar mesmo de um default próprio.
+export const MAX_TOKENS_BY_ACTION = {};
 
 /**
  * Resolve o alias de modelo vindo de label (função PURA).
@@ -143,6 +152,27 @@ function resolveAi(action, { labels = [], modelOverride } = {}) {
   return resolveAiConfig({ env: process.env, fileAi: readFileAi(), action, labels, modelOverride });
 }
 
+/**
+ * Avisa quando a label de modelo existe na issue mas não resolve.
+ *
+ * `resolveModelLabel` já devolvia o erro, e NINGUÉM o lia: um apelido errado
+ * fazia a label ser ignorada em silêncio, a precedência caía para o modelo do
+ * .spec-wave.json e o run seguia com o modelo errado. Quem aplicou a label para
+ * reprocessar num modelo mais forte não tinha como perceber — o único sinal era
+ * o `origem:` da linha acima, que ninguém compara.
+ */
+function warnUnresolvedModelLabel(ai) {
+  const alias = ai.labelAlias;
+  if (!alias?.error) return;
+  const motivo = alias.error === 'ambíguo'
+    ? `há mais de uma label ${MODEL_LABEL_PREFIX}* na issue (${alias.alias})`
+    : `o apelido "${alias.alias}" não existe em ai.modelAliases do .spec-wave.json`;
+  console.warn(
+    `⚠️  Label de modelo IGNORADA: ${motivo}. ` +
+    `Seguindo com ${ai.model} (origem: ${ai.modelSource}).`
+  );
+}
+
 // Retry de falha transitória do provedor. Sem isto, um corpo cortado numa
 // geração de 90s derruba o Action inteiro e a issue fica sem spec — o custo de
 // esperar alguns segundos é irrisório perto de refazer o ciclo à mão.
@@ -186,7 +216,7 @@ export async function withRetry(label, fn, { attempts = RETRY_ATTEMPTS, baseMs =
 // `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 };
+export { TruncatedOutputError, MaxTurnsError, 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
@@ -247,6 +277,7 @@ export async function generateDocument(systemPrompt, userContent, opts = {}) {
     `temperature: ${sendTemperature ? temperature : 'n/a (removida neste modelo)'} · ` +
     `max_tokens: ${maxTokens}`
   );
+  warnUnresolvedModelLabel(ai);
 
   // Acumuladores de uso desta invocação (1 ou 2 chamadas, com o retry de lint).
   let inputTokens = 0;
@@ -262,6 +293,11 @@ export async function generateDocument(systemPrompt, userContent, opts = {}) {
       // repositório antes de escrever o documento. É o que os blocos
       // `requires-tools` dos model-prompt sempre descreveram.
       tools: opts.tools ?? ['Read', 'Glob', 'Grep'],
+      // Teto de turnos do PROMPT (frontmatter `maxTurns`, default
+      // DEFAULT_PROMPT_MAX_TURNS). Sem repassar aqui, o valor declarado no
+      // prompt nunca chegava ao motor e o MAX_TURNS dos backends prevalecia —
+      // um teto ficava documentado num lugar e vigorando em outro.
+      maxTurns: opts.maxTurns,
     };
     const { text, usage } = await withRetry(`Geração via ${ai.provider}`, () =>
       generateViaEngine(system, userContent, ai, callOpts));
@@ -362,6 +398,7 @@ export async function generateStructured(systemPrompt, userContent, opts = {}) {
     `Provider de IA: ${ai.provider} · modelo: ${ai.model} (origem: ${ai.modelSource}) · ` +
     `saída estruturada: ${schema.name}${strict ? ' (strict)' : ''} · max_tokens: ${maxTokens}`
   );
+  warnUnresolvedModelLabel(ai);
 
   const callOpts = {
     temperature: sendTemperature ? temperature : undefined,
@@ -451,7 +488,7 @@ export function extractOpenRouterUsage(usage) {
  * @returns {Promise<{text: string, json?: object, usage: object}>}
  */
 async function generateViaEngine(
-  systemPrompt, userContent, ai, { temperature, maxTokens, schema, strict, action, tools },
+  systemPrompt, userContent, ai, { temperature, maxTokens, maxTurns, schema, strict, action, tools },
 ) {
   const result = await runAgent(userContent, {
     provider: ai.provider,
@@ -463,6 +500,7 @@ async function generateViaEngine(
     userId: 'spec-wave',
     ...(tools ? { tools } : {}),
     ...(maxTokens ? { maxTokens } : {}),
+    ...(maxTurns ? { maxTurns } : {}),
     ...(temperature !== undefined ? { temperature } : {}),
     ...(schema
       ? { responseSchema: { ...schema, strict: strict === true } }
@@ -492,6 +530,18 @@ async function generateViaEngine(
 
   const text = stripReasoning(result.outputText || '');
   if (!text) {
+    // Teto de turnos tem causa e remédio próprios, e NÃO é transitório: o
+    // modelo gastou todos os turnos em tool calls sem nunca escrever o
+    // documento, e repetir reproduz isso. Ver MaxTurnsError.
+    if (result.resultSubtype === 'error_max_turns') {
+      throw new MaxTurnsError({
+        provider: ai.provider,
+        model: ai.model,
+        turns: result.numTurns,
+        action: action || null,
+        toolCalls: result.toolCalls || [],
+      });
+    }
     const err = new Error(
       `O provider ${ai.provider} retornou resposta sem texto ` +
       `(subtype=${result.resultSubtype}, turnos=${result.numTurns}).`