@spec-wave/cli 0.6.0 → 0.7.0

package/src/commands/task.mjs

@@ -0,0 +1,183 @@
+// Gerencia uma Task no board: start (Etapa "🚧 Desenvolvimento" + Status
+// "In Progress") | done (Etapa "🎉 Done" + Status "Done").
+//
+// Comando LOCAL — rodado pelo dev no terminal. owner/repo vêm da env
+// GITHUB_REPOSITORY quando existir, senão do .spec-wave.json (gravado pelo init).
+//
+// Regras do board embutidas (ver config.mjs):
+//  • Etapa nunca retrocede (advanceToStage devolve false nesse caso);
+//  • uma única Task com Status "In Progress" por vez dentro da mesma Story
+//    (regra pura canStartTask, testada em test/board-rules.test.mjs).
+import * as p from '@clack/prompts';
+import chalk from 'chalk';
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { resolveToken } from '../api/auth.mjs';
+import { getIssue } from '../api/github-rest.mjs';
+import { addProjectItem, getIssueParent, listSubIssues, getItemSingleSelectValue } from '../api/github-graphql.mjs';
+import { detectIssueType } from '../lib/issue-type.mjs';
+import { loadProjectConfig, resolveField, advanceToStage, setItemStatus } from '../lib/board.mjs';
+import {
+  CONFIG_FILE, STAGE_DEVELOPMENT, STAGE_DONE,
+  PROGRESS_IN_PROGRESS, PROGRESS_DONE,
+} from '../config.mjs';
+
+/**
+ * Regra PURA: pode iniciar uma Task? Só se NENHUMA task irmã (mesma Story)
+ * estiver com Status "In Progress". Irmãs com status desconhecido (null/
+ * undefined) NÃO bloqueiam — falha de leitura não pode travar o fluxo.
+ *
+ * @param {{ siblings: Array<{ number: number, status: string|null }> }} input
+ * @returns {{ ok: boolean, blocker: number|null }} blocker = number da irmã
+ *          em andamento, quando houver
+ */
+export function canStartTask({ siblings } = {}) {
+  const busy = (siblings || []).find(s => s && s.status === PROGRESS_IN_PROGRESS);
+  return busy ? { ok: false, blocker: busy.number } : { ok: true, blocker: null };
+}
+
+// Resolve owner/repo: env GITHUB_REPOSITORY (padrão dos comandos de Action) com
+// fallback no .spec-wave.json — comandos locais rodam sem essa env.
+function resolveRepoContext() {
+  const [envOwner, envRepo] = (process.env.GITHUB_REPOSITORY || '').split('/');
+  let cfg = {};
+  const cfgPath = path.join(process.cwd(), CONFIG_FILE);
+  try { if (existsSync(cfgPath)) cfg = JSON.parse(readFileSync(cfgPath, 'utf-8')); } catch {}
+  return { owner: envOwner || cfg.owner, repo: envRepo || cfg.repo };
+}
+
+export async function task({ action, issue: issueArg }) {
+  if (action !== 'start' && action !== 'done') {
+    p.log.error(
+      `Ação desconhecida: "${action}".\n` +
+      'Uso: spec-wave task <start|done> <número> — ex.: spec-wave task start 12'
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const issueNumber = parseInt(String(issueArg).replace('#', ''), 10);
+  if (!Number.isInteger(issueNumber) || issueNumber <= 0) {
+    p.log.error(`Issue inválida: "${issueArg}". Use o número da issue, ex.: 12 ou #12.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const { owner, repo } = resolveRepoContext();
+  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 task ${action} #${issueNumber}`));
+
+  // 1. Lê a issue e valida o tipo.
+  let issue;
+  try {
+    issue = await getIssue(token, owner, repo, issueNumber);
+  } catch (err) {
+    p.log.error(`Não foi possível ler a issue #${issueNumber}: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+  const type = detectIssueType(issue);
+  if (type !== 'Task') {
+    p.log.error(
+      `\`spec-wave task\` só aceita issues do tipo Task. ` +
+      `Issue #${issueNumber} é do tipo ${type || 'desconhecido'} (${issue.title}).`
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  // 2. Project do .spec-wave.json — sem ele não há board para atualizar.
+  const { project, error: projectError } = loadProjectConfig();
+  if (projectError) {
+    p.log.error(`${projectError} — board não atualizado. Rode \`spec-wave init\` (ou \`spec-wave refresh --config\`).`);
+    process.exitCode = 1;
+    return;
+  }
+  const etapaField = await resolveField(token, project, 'Etapa').catch(() => null);
+  const statusField = await resolveField(token, project, 'Status').catch(() => null);
+
+  // 3. start: garante que nenhuma task irmã (mesma Story) está In Progress.
+  if (action === 'start') {
+    const parent = await getIssueParent(token, issue.node_id).catch(() => null);
+    const parentIsStory = parent && detectIssueType({ title: parent.title }) === 'Story';
+    if (!statusField?.id) {
+      p.log.warn('Campo "Status" não encontrado no Project — verificação de task em andamento pulada.');
+    } else if (!parentIsStory) {
+      p.log.warn(`Task #${issueNumber} sem Story-pai — verificação de tasks irmãs pulada.`);
+    } else {
+      const subs = await listSubIssues(token, parent.nodeId).catch(() => []);
+      const siblingTasks = subs.filter(s =>
+        s.number !== issueNumber && detectIssueType({ title: s.title, labels: s.labels }) === 'Task'
+      );
+      // Status de cada irmã; falha de leitura → status desconhecido (não bloqueia).
+      const siblings = await Promise.all(siblingTasks.map(async (s) => {
+        try {
+          const itemId = await addProjectItem(token, project.id, s.nodeId);
+          const status = await getItemSingleSelectValue(token, itemId, statusField.id);
+          return { number: s.number, title: s.title, status };
+        } catch {
+          return { number: s.number, title: s.title, status: null };
+        }
+      }));
+      const { ok, blocker } = canStartTask({ siblings });
+      if (!ok) {
+        const b = siblings.find(s => s.number === blocker);
+        p.log.error(
+          `já existe task em andamento: #${blocker} «${b?.title || ''}» — ` +
+          `finalize com \`spec-wave task done ${blocker}\` antes de iniciar outra`
+        );
+        process.exitCode = 1;
+        return;
+      }
+    }
+  }
+
+  // 4. Move no board. start → Desenvolvimento/In Progress; done → Done/Done.
+  const target = action === 'start'
+    ? { stage: STAGE_DEVELOPMENT, status: PROGRESS_IN_PROGRESS }
+    : { stage: STAGE_DONE, status: PROGRESS_DONE };
+
+  let moved;
+  try {
+    moved = await advanceToStage(token, project, etapaField, statusField, issue.node_id, target.stage, target.status);
+  } catch (err) {
+    p.log.error(`Falha ao atualizar o board: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (moved) {
+    p.log.success(`Task #${issueNumber} → Etapa ${chalk.bold(target.stage)} / Status ${chalk.bold(target.status)}.`);
+  } else {
+    // Etapa já está no destino ou adiante (nunca retrocede) — só garante o Status.
+    try {
+      await setItemStatus(token, project, statusField, issue.node_id, target.status);
+      p.log.info(`Etapa já à frente — apenas Status ajustado para ${chalk.bold(target.status)}.`);
+    } catch (err) {
+      p.log.warn(`Etapa já à frente, mas falhou ao ajustar o Status: ${err.message}`);
+    }
+  }
+
+  p.outro(
+    action === 'start'
+      ? `${chalk.green('✓')} Task #${issueNumber} em andamento. Ao concluir: spec-wave task done ${issueNumber}`
+      : `${chalk.green('✓')} Task #${issueNumber} concluída no board.`
+  );
+}

package/src/commands/validate.mjs

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { resolveToken } from '../api/auth.mjs';
 import { getIssue, removeLabel, addLabel, commentOnIssue } from '../api/github-rest.mjs';
 import { slugify } from '../lib/slugify.mjs';
-import { CONFIG_FILE, REQUIRED_PLAN_SECTIONS, REQUIRED_SPEC_SECTIONS } from '../config.mjs';
+import { CONFIG_FILE, LABEL_CRITIQUE_FAILED, REQUIRED_PLAN_SECTIONS, REQUIRED_SPEC_SECTIONS } from '../config.mjs';
 
 export async function validate({ issueNumber }) {
   const token = await resolveToken();
@@ -27,6 +27,17 @@ export async function validate({ issueNumber }) {
 
   const errors = [];
 
+  // Bloqueio da crítica adversarial: enquanto a label critique-failed estiver
+  // na issue, o ready não é liberado — a correção dos documentos é manual.
+  const labelNames = (issue.labels || []).map((l) => (typeof l === 'string' ? l : l.name));
+  const critiqueFailed = labelNames.includes(LABEL_CRITIQUE_FAILED);
+  if (critiqueFailed) {
+    errors.push(
+      '🔎 A crítica adversarial apontou contradições GRAVES (veja o comentário na issue). ' +
+      `Corrija os documentos e remova a label \`${LABEL_CRITIQUE_FAILED}\` para liberar o ready.`
+    );
+  }
+
   // Check plan.md
   const planPath = `${featureDir}/plan.md`;
   if (!existsSync(planPath)) {
@@ -63,8 +74,14 @@ export async function validate({ issueNumber }) {
       errors.join('\n') +
       `\n\nCorreija os problemas e adicione novamente a label \`spec-wave:ready\`.`
     );
-    // Send back to spec stage
-    await addLabel(token, owner, repo, parseInt(issueNumber, 10), 'spec-wave:spec');
+    // Quando a ÚNICA falha é a da crítica adversarial, os documentos existem e
+    // estão estruturalmente válidos — só precisam de correção manual. Nesse
+    // caso NÃO devolvemos a feature para a etapa de spec (spec-wave:spec).
+    const onlyCritiqueFailed = critiqueFailed && errors.length === 1;
+    if (!onlyCritiqueFailed) {
+      // Send back to spec stage
+      await addLabel(token, owner, repo, parseInt(issueNumber, 10), 'spec-wave:spec');
+    }
     console.error('Validação falhou:', errors.join(', '));
     process.exit(1);
   }

package/src/config.mjs

@@ -32,6 +32,16 @@ export const AI_PROVIDERS = [
 
 export const DEFAULT_PROVIDER = 'anthropic';
 
+// Ações de IA que podem ter modelo próprio no .spec-wave.json (bloco
+// `ai.models`, ex.: { "critique": "claude-opus-4-1" }). Resolvidas em runtime
+// por resolveAiConfig() em src/lib/claude.mjs.
+export const AI_ACTIONS = ['spec', 'plan', 'decompose', 'critique'];
+
+// Idioma-alvo de todos os documentos gerados por IA (spec/plan/decompose/critique).
+// Usado pelo lint de saída (src/lib/output-lint.mjs) para detectar vazamento
+// de caracteres de outros alfabetos.
+export const TARGET_LANGUAGE = 'pt-BR';
+
 export function getProvider(value) {
   return AI_PROVIDERS.find(p => p.value === value);
 }
@@ -131,6 +141,27 @@ export const WORK_ITEM_TYPES = CUSTOM_FIELDS
   .find(f => f.name === 'Work Item Type')
   .options.map(o => o.name);
 
+// Tipos cujo estágio no board é gerenciado MANUALMENTE: as automações (Actions
+// code-review/qa e o fluxo do implement) NUNCA avançam a Etapa desses itens —
+// o usuário os move à mão. Spike é uma investigação cujo avanço é decisão humana.
+export const MANUAL_STAGE_TYPES = ['Spike'];
+export function isManualStageType(type) {
+  return MANUAL_STAGE_TYPES.includes(type);
+}
+
+// Tipos que NÃO geram spec.md/plan.md (não passam pelo fluxo funcional de Feature).
+export const SPEC_PLAN_EXCLUDED_TYPES = ['Spike', 'RFC', 'Bug'];
+export function allowsSpecPlan(type) {
+  return !SPEC_PLAN_EXCLUDED_TYPES.includes(type);
+}
+
+// Tipos que podem ser decompostos e o que geram:
+//  • Feature → Stories (+ Tasks)   • RFC → Tasks (diretamente, sem Stories)
+export const DECOMPOSE_TARGETS = {
+  Feature: 'stories',
+  RFC: 'tasks',
+};
+
 export const TYPE_LABELS = [
   { name: '[INITIATIVE]', color: 'C5DEF5', description: 'Agrupamento estratégico de Epics' },
   { name: '[EPIC]',    color: '7B61FF', description: 'Objetivo estratégico'  },
@@ -149,12 +180,18 @@ export const PRIORITY_LABELS = [
   { name: 'P3', color: 'EDEDED', description: 'Baixa'    },
 ];
 
+// Labels de estado gravadas pelas automações (não são gatilhos do usuário).
+export const LABEL_CRITIQUE_FAILED = 'spec-wave:critique-failed';
+export const LABEL_DECOMPOSED = 'spec-wave:decomposed';
+
 export const TRIGGER_LABELS = [
   { name: 'spec-wave:spec',          color: 'BFD4F2', description: 'Gerar spec.md via GitHub Action'      },
   { name: 'spec-wave:plan',          color: 'BFD4F2', description: 'Gerar plan.md via GitHub Action'      },
   { name: 'spec-wave:ready',         color: '0E8A16', description: 'Validar spec+plan e mover para Ready'  },
   { name: 'spec-wave:plan-approved', color: '0E8A16', description: 'Spec+plan validados com sucesso'       },
   { name: 'spec-wave:decompose',     color: 'BFD4F2', description: 'Decompor em Stories e Tasks'          },
+  { name: LABEL_CRITIQUE_FAILED,     color: 'B60205', description: 'Crítica adversarial apontou contradições graves' },
+  { name: LABEL_DECOMPOSED,          color: 'EDEDED', description: 'Feature já decomposta em Stories e Tasks' },
 ];
 
 export const ALL_LABELS = [...TYPE_LABELS, ...PRIORITY_LABELS, ...TRIGGER_LABELS];

package/src/lib/board.mjs

@@ -0,0 +1,106 @@
+// Helpers compartilhados de manipulação do board (GitHub Projects v2).
+// Extraídos de code-review.mjs/qa.mjs para uso também pelos comandos de CLI
+// (task/story/order). Ver a distinção Etapa × Status em config.mjs.
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { addProjectItem, setItemSingleSelect, getSingleSelectField, getItemSingleSelectValue } from '../api/github-graphql.mjs';
+import { CONFIG_FILE, STAGE_ORDER } from '../config.mjs';
+
+/**
+ * Carrega o bloco `project` do .spec-wave.json do diretório atual.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.cwd=process.cwd()] diretório onde procurar o config
+ * @returns {{ project: object|null, error: string|null }} project = bloco com
+ *          id/fields; error = motivo legível quando project é null (compõe os
+ *          avisos "… — board não atualizado." dos chamadores).
+ */
+export function loadProjectConfig({ cwd = process.cwd() } = {}) {
+  const configPath = path.join(cwd, CONFIG_FILE);
+  if (!existsSync(configPath)) {
+    return { project: null, error: `${CONFIG_FILE} não encontrado` };
+  }
+  let project;
+  try {
+    project = JSON.parse(readFileSync(configPath, 'utf-8')).project || {};
+  } catch (err) {
+    return { project: null, error: `${CONFIG_FILE} corrompido (${err.message})` };
+  }
+  if (!project.id) {
+    return { project: null, error: `Project não configurado em ${CONFIG_FILE}` };
+  }
+  return { project, error: null };
+}
+
+/**
+ * Resolve um campo SINGLE_SELECT do Project pelo nome: usa os IDs gravados no
+ * .spec-wave.json (bloco `fields`, ou o formato legado etapaFieldId/
+ * stageOptions para "Etapa") e cai na API GraphQL como fallback.
+ *
+ * @param {string} token
+ * @param {object} project bloco project do .spec-wave.json (precisa de .id)
+ * @param {string} name nome do campo (ex.: 'Etapa', 'Status')
+ * @returns {Promise<{ id: string, options: Record<string,string> }|null>}
+ */
+export async function resolveField(token, project, name) {
+  if (project.fields?.[name]) return project.fields[name];
+  if (name === 'Etapa' && project.etapaFieldId) {
+    return { id: project.etapaFieldId, options: project.stageOptions || {} };
+  }
+  return await getSingleSelectField(token, project.id, name);
+}
+
+/**
+ * Avança um item do board para `targetStage` (Etapa) e define o Status para
+ * `targetStatus`. Uma issue só AVANÇA: se já estiver em `targetStage` ou em uma
+ * etapa posterior (pela ordem canônica STAGE_ORDER), não é tocada.
+ *
+ * @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 nome da etapa de destino
+ * @param {string} targetStatus valor do Status (Todo/In Progress/Done)
+ * @returns {Promise<boolean>} true se avançou; false se já estava adiante
+ */
+export async function advanceToStage(token, project, etapaField, statusField, nodeId, targetStage, targetStatus) {
+  const itemId = await addProjectItem(token, project.id, nodeId);
+
+  if (etapaField?.id && targetStage) {
+    // Nunca retroceder: compara a etapa atual com a de destino na ordem canônica.
+    const current = await getItemSingleSelectValue(token, itemId, etapaField.id).catch(() => null);
+    const curIdx = current ? STAGE_ORDER.indexOf(current) : -1;
+    const tgtIdx = STAGE_ORDER.indexOf(targetStage);
+    if (curIdx !== -1 && tgtIdx !== -1 && curIdx >= tgtIdx) {
+      return false; // já está nessa etapa ou adiante — não retrocede
+    }
+    const optionId = etapaField.options?.[targetStage];
+    if (optionId) await setItemSingleSelect(token, project.id, itemId, etapaField.id, optionId);
+  }
+  if (statusField?.id && targetStatus) {
+    const optionId = statusField.options?.[targetStatus];
+    if (optionId) await setItemSingleSelect(token, project.id, itemId, statusField.id, optionId);
+  }
+  return true;
+}
+
+/**
+ * Define APENAS o Status nativo (Todo/In Progress/Done) de um item, sem tocar
+ * na Etapa — usado para marcar progresso dentro da etapa atual.
+ *
+ * @param {string} token token com scope project
+ * @param {object} project bloco project (precisa de .id)
+ * @param {{id,options}|null} statusField campo nativo "Status"
+ * @param {string} nodeId node id da issue
+ * @param {string} status valor de destino (Todo/In Progress/Done)
+ * @returns {Promise<boolean>} true se definiu; false se campo/opção ausentes
+ */
+export async function setItemStatus(token, project, statusField, nodeId, status) {
+  if (!statusField?.id) return false;
+  const optionId = statusField.options?.[status];
+  if (!optionId) return false;
+  const itemId = await addProjectItem(token, project.id, nodeId);
+  await setItemSingleSelect(token, project.id, itemId, statusField.id, optionId);
+  return true;
+}

package/src/lib/claude.mjs

@@ -2,11 +2,37 @@ import Anthropic from '@anthropic-ai/sdk';
 import { readFileSync, existsSync } from 'node:fs';
 import path from 'node:path';
 import { CONFIG_FILE, getProvider, DEFAULT_PROVIDER } from '../config.mjs';
+import { lintLanguage } from './output-lint.mjs';
+
+/**
+ * Resolve provider/modelo de IA (função PURA — testável sem process.env nem fs).
+ *
+ * Precedência do modelo: env.SPEC_WAVE_MODEL → fileAi.models[action] →
+ * fileAi.model → default do provider. Provider: env.SPEC_WAVE_PROVIDER →
+ * fileAi.provider → default. Assim uma ação específica (ex.: critique) pode
+ * usar modelo próprio via bloco `ai.models` do .spec-wave.json.
+ *
+ * @param {object} params
+ * @param {object} [params.env] objeto tipo process.env
+ * @param {object} [params.fileAi] bloco `ai` do .spec-wave.json
+ * @param {string} [params.action] ação de IA (ver AI_ACTIONS em config.mjs)
+ * @returns {{ provider: string, model: string, secret: string }}
+ */
+export function resolveAiConfig({ env = {}, fileAi = {}, action } = {}) {
+  const provider = (env.SPEC_WAVE_PROVIDER || fileAi.provider || DEFAULT_PROVIDER).toLowerCase();
+  const meta = getProvider(provider) || getProvider(DEFAULT_PROVIDER);
+  const model = env.SPEC_WAVE_MODEL
+    || (action && fileAi.models?.[action])
+    || fileAi.model
+    || meta.defaultModel;
+  return { provider: meta.value, model, secret: meta.secret };
+}
 
 // Resolve o provider/modelo de IA a partir do .spec-wave.json (gravado pelo init
 // e versionado no repo) com precedência para variáveis de ambiente — assim os
 // workflows usam exatamente o que foi escolhido no init, sem depender de flags.
-function resolveAi() {
+// Wrapper fino: lê o arquivo e delega a decisão à resolveAiConfig (pura).
+function resolveAi(action) {
   let fileAi = {};
   try {
     const configPath = path.join(process.cwd(), CONFIG_FILE);
@@ -16,28 +42,62 @@ function resolveAi() {
   } catch {
     // config ausente/corrompido → cai nos defaults/env
   }
-
-  const provider = (process.env.SPEC_WAVE_PROVIDER || fileAi.provider || DEFAULT_PROVIDER).toLowerCase();
-  const meta = getProvider(provider) || getProvider(DEFAULT_PROVIDER);
-  const model = process.env.SPEC_WAVE_MODEL || fileAi.model || meta.defaultModel;
-  return { provider: meta.value, model, secret: meta.secret };
+  return resolveAiConfig({ env: process.env, fileAi, action });
 }
 
 // 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.
+//
+// opts:
+//  • action: ação de IA ('spec'|'plan'|'decompose'|'critique') — permite modelo
+//    por ação via `ai.models` do .spec-wave.json;
+//  • lint: { lang } — após gerar, roda lintLanguage no resultado; se reprovar,
+//    RE-GERA uma única vez com instrução de idioma reforçada; se reprovar de
+//    novo, segue com o conteúdo e reporta os findings;
+//  • withReport: true → retorna { content, lintFindings, retried } em vez da
+//    string (o retorno string é mantido para os chamadores existentes).
 export async function generateDocument(systemPrompt, userContent, opts = {}) {
-  const ai = resolveAi();
+  const ai = resolveAi(opts.action);
   const temperature = opts.temperature ?? 0.2;
   // Modelos de reasoning (ex.: deepseek-r1) consomem tokens "pensando" antes da
   // resposta, então o teto precisa ser maior para o plano não vir truncado.
   const maxTokens = opts.maxTokens ?? 8192;
   console.log(`Provider de IA: ${ai.provider} · modelo: ${ai.model} · temperature: ${temperature} · max_tokens: ${maxTokens}`);
 
-  const raw = ai.provider === 'openrouter'
-    ? await generateWithOpenRouter(systemPrompt, userContent, ai, temperature, maxTokens)
-    : await generateWithAnthropic(systemPrompt, userContent, ai, temperature, maxTokens);
+  const generate = async (system) => {
+    const raw = ai.provider === 'openrouter'
+      ? await generateWithOpenRouter(system, userContent, ai, temperature, maxTokens)
+      : await generateWithAnthropic(system, userContent, ai, temperature, maxTokens);
+    return stripOuterFence(raw);
+  };
+
+  let content = await generate(systemPrompt);
+  let lintFindings = [];
+  let retried = false;
+
+  if (opts.lint) {
+    const lang = opts.lint.lang || 'pt-BR';
+    const allowlist = opts.lint.allowlist || [];
+    let result = lintLanguage(content, { lang, allowlist });
+    if (!result.ok) {
+      // Uma única nova tentativa, com a instrução de idioma reforçada no system
+      // prompt — cobre o caso de modelos que vazam caracteres CJK/cirílicos.
+      retried = true;
+      console.warn(`Lint de idioma reprovou a saída (${result.findings.length} ocorrência(s)) — re-gerando com instrução reforçada.`);
+      const reinforced = systemPrompt +
+        `\n\nIMPORTANTE: responda exclusivamente em ${lang}. ` +
+        'Não use caracteres de outros alfabetos (CJK, cirílico, árabe, tailandês).';
+      content = await generate(reinforced);
+      result = lintLanguage(content, { lang, allowlist });
+      if (!result.ok) {
+        // Segue com o conteúdo mesmo assim; o chamador decide o que fazer.
+        console.warn(`Lint de idioma reprovou novamente (${result.findings.length} ocorrência(s)) — seguindo com o conteúdo gerado.`);
+        lintFindings = result.findings;
+      }
+    }
+  }
 
-  return stripOuterFence(raw);
+  return opts.withReport ? { content, lintFindings, retried } : content;
 }
 
 // Remove blocos de raciocínio que alguns modelos (ex.: deepseek-r1) embutem no