@spec-wave/cli 0.12.0 → 0.14.0

package/src/lib/critique.mjs

@@ -1,34 +1,75 @@
-// Crítica adversarial dos artefatos gerados por IA (plan e stories).
+// Crítica adversarial dos artefatos gerados por IA (plan e decomposição).
 //
-// Um segundo passe de IA, com papel de revisor cético, audita o documento
+// Um segundo passe de IA, com papel de revisor cético, audita o artefato
 // recém-gerado contra a spec/regras de negócio/tech_context e classifica cada
 // contradição como GRAVE ou MENOR. Findings graves aplicam a label
-// `spec-wave:critique-failed`, que bloqueia o `spec-wave:ready` até correção.
+// `spec-wave:critique-failed`, que bloqueia o avanço até correção.
 //
-// Contrato: a crítica NUNCA deve derrubar o fluxo principal — parse tolerante
-// a JSON sujo, e falhas de API são tratadas pelo chamador como não-fatais.
+// A saída é ESTRUTURADA e validada por schema. A versão anterior parseava JSON
+// "tolerante" e, quando não conseguia, emitia a resposta bruta truncada como um
+// finding MENOR — foi assim que um achado grave foi rebaixado e o JSON cru
+// vazou dentro da seção "⚠️ Menores" de um comentário. Pior ainda: um payload
+// com o campo `description` em vez de `text` era filtrado para lista vazia e
+// renderizava "✅ nenhuma contradição", transformando um grave em passe
+// silencioso. Agora um payload fora do contrato LANÇA.
+//
+// Contrato com os chamadores: erros PROPAGAM. Cada comando decide o que fazer —
+// o generate-plan segue (o plan já foi commitado, o humano precisa dele para
+// corrigir); o decompose aborta, porque criar work items com o portão
+// comprovadamente não executado é exatamente o que se quer evitar.
+
+import { generateStructured } from './claude.mjs';
+import {
+  LABEL_CRITIQUE_FAILED, LABEL_NEEDS_HUMAN, DEFAULT_MAX_CRITIQUE_ATTEMPTS, labelNames,
+} from '../config.mjs';
+
+// Severidades aceitas — enum FECHADO. O teste de prefixo /^grave/i sobre texto
+// livre que existia aqui aceitava "gravíssimo" e rebaixava "critical"/"high"
+// para menor sem avisar ninguém.
+export const CRITIQUE_SEVERITIES = ['grave', 'menor'];
+const SEVERITY_SET = new Set(CRITIQUE_SEVERITIES);
+
+// Teto de sanidade: uma crítica com centenas de findings é sinal de modelo em
+// loop, não de documento ruim — e o comentário estouraria o limite do GitHub.
+const MAX_FINDINGS = 50;
+
+// Findings são texto gerado por IA que vai para dentro de uma lista markdown, no
+// mesmo corpo do marcador HTML de tentativa. Sem teto, um finding longo empurra
+// o comentário para o limite de 65536 caracteres do GitHub.
+const MAX_FINDING_CHARS = 800;
 
-import { generateDocument } from './claude.mjs';
-import { LABEL_CRITIQUE_FAILED } from '../config.mjs';
+export const CRITIQUE_TOOL_NAME = 'registrar_findings';
 
-// Tamanho máximo da resposta bruta preservada no fallback de parse.
-const RAW_FALLBACK_MAX = 400;
+// Rótulo do artefato auditado, por contexto — usado no cabeçalho do comentário.
+const KIND_LABEL = { plan: 'plan.md', stories: 'decomposition.md' };
 
 // Redação específica por tipo de auditoria. 'plan' audita o plan.md contra a
-// spec; 'stories' audita as stories propostas contra spec + plan.
+// spec; 'stories' audita a decomposição proposta contra spec + plan.
 const KIND_FOCUS = {
   plan:
     'Audite o plan.md contra o spec.md, as regras de negócio e o tech_context fornecidos. ' +
     'Procure decisões técnicas que contradizem ou ignoram requisitos da spec e ' +
     'tecnologias/serviços fora do tech_context.',
   stories:
-    'Audite as Stories propostas (JSON) contra o spec.md e o plan.md fornecidos. ' +
-    'Procure stories que contradizem, invertem ou ignoram requisitos da spec ou ' +
-    'decisões do plan, e critérios de aceite incompatíveis com as regras de negócio.',
+    'Audite a decomposição proposta (documento Markdown com Stories e suas Tasks) contra o ' +
+    'spec.md e o plan.md fornecidos. Procure Stories que contradizem, invertem ou ignoram ' +
+    'requisitos da spec ou decisões do plan, critérios de aceite incompatíveis com as regras ' +
+    'de negócio, e Tasks que não sustentam a Story a que pertencem.',
 };
 
+// A decomposição virou arquivo revisável (decomposition.md): um finding só é
+// acionável se disser ONDE está o problema. Os títulos "## Story N" e
+// "### Task N.M" são a âncora estável — sem isso o humano relê o documento
+// inteiro tentando adivinhar a que Story o achado se refere.
+const ANCHOR_RULE = `Cada finding DEVE citar, no campo "anchor", o trecho auditado:
+- "Story N" para um problema na Story N (ex.: "Story 3");
+- "Task N.M" para um problema na Task M da Story N (ex.: "Task 3.2");
+- "geral" quando o problema for da decomposição como um todo (ex.: requisito da spec que nenhuma Story cobre).
+Use EXATAMENTE os números que aparecem nos títulos "## Story N — ..." e "### Task N.M — ..." do documento.`;
+
 function buildSystemPrompt(kind) {
   const focus = KIND_FOCUS[kind] || KIND_FOCUS.plan;
+  const anchor = kind === 'stories' ? `\n\n${ANCHOR_RULE}` : '';
   return `Você é um revisor técnico CÉTICO e adversarial. Seu papel é encontrar problemas, não elogiar.
 
 ${focus}
@@ -39,126 +80,385 @@ Liste:
 - violações de restrições explícitas (ex.: minimização de dados LGPD, limites de retenção, campos proibidos);
 - itens que contradizem ou ignoram a spec.
 
-Classifique cada finding:
+Classifique cada finding no campo "severity", usando EXATAMENTE um destes dois valores:
 - "grave": contradiz um requisito ou regra explícita — causaria implementação errada;
 - "menor": inconsistência, omissão ou ambiguidade que merece atenção mas não inverte requisito.
 
 NÃO invente problemas: se os documentos estiverem consistentes, retorne a lista vazia.
-Escreva os findings em português (pt-BR).
+Escreva os findings em português (pt-BR), em uma frase objetiva cada.${anchor}
 
-Responda APENAS com JSON neste formato, sem texto adicional:
-{"findings": [{"severity": "grave"|"menor", "text": "..."}]}`;
+Registre o resultado chamando a ferramenta \`${CRITIQUE_TOOL_NAME}\`. Nunca responda em texto livre.
+Se os documentos estiverem consistentes, chame-a com "findings": [].`;
+}
+
+function critiqueJsonSchema(kind) {
+  const properties = {
+    severity: {
+      type: 'string',
+      enum: CRITIQUE_SEVERITIES,
+      description:
+        '"grave" contradiz um requisito/regra explícita; ' +
+        '"menor" é inconsistência, omissão ou ambiguidade.',
+    },
+    text: {
+      type: 'string',
+      description: 'Descrição do finding em português (pt-BR), em uma única frase objetiva.',
+    },
+  };
+  const required = ['severity', 'text'];
+  if (kind === 'stories') {
+    properties.anchor = {
+      type: 'string',
+      description: 'Âncora do trecho auditado: "Story N", "Task N.M" ou "geral".',
+    };
+    required.push('anchor');
+  }
+  return {
+    type: 'object',
+    properties: {
+      findings: {
+        type: 'array',
+        description:
+          'Contradições encontradas. Vazia quando os documentos estão consistentes.',
+        items: { type: 'object', properties, required, additionalProperties: false },
+      },
+    },
+    required: ['findings'],
+    additionalProperties: false,
+  };
 }
 
 /**
- * Interpreta a resposta do modelo crítico (função PURA — testável).
+ * Payload da crítica fora do schema.
  *
- * Tolerante a JSON sujo: fences de código, texto ao redor do objeto e
- * severities em maiúsculas/variantes ("GRAVE", "Grave"). Qualquer severity que
- * não comece com "grave" vira "menor". Se nada parseável for encontrado,
- * retorna a resposta bruta (truncada) como um único finding menor — a crítica
- * nunca deve explodir.
+ * `transient: true` de propósito: repetir a MESMA requisição pode devolver um
+ * payload correto (ao contrário de truncamento, onde repetir dá o mesmo corte),
+ * então a validação roda dentro do retry do generateStructured. Depois das
+ * tentativas o erro sobe — nunca virando um finding de texto bruto.
+ */
+export class CritiqueSchemaError extends Error {
+  constructor(detail) {
+    super(`A crítica devolveu um payload fora do schema: ${detail}`);
+    this.name = 'CritiqueSchemaError';
+    this.transient = true;
+  }
+}
+
+function describe(value) {
+  if (value === undefined) return 'undefined';
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return `um array de ${value.length} item(ns)`;
+  return typeof value === 'object' ? 'um objeto' : `${typeof value} (${JSON.stringify(value).slice(0, 60)})`;
+}
+
+const ANCHOR_RE = /^(story|task)[ \t]*(\d+(?:\.\d+)?)$/i;
+
+/**
+ * Normaliza a âncora de um finding (função PURA).
  *
- * @param {string} text resposta bruta do modelo
- * @returns {{ grave: boolean, findings: Array<{ severity: 'grave'|'menor', text: string }> }}
+ * Aceita "Story 3", "story3", "TASK 3.2". Qualquer outra coisa — inclusive
+ * "geral" — vira ausência de âncora: melhor não citar do que citar errado e
+ * mandar o humano para o trecho errado do documento.
+ *
+ * @param {*} value valor cru do campo `anchor`
+ * @returns {string} âncora normalizada, ou '' quando não há
  */
-export function parseCritiqueResponse(text) {
-  const raw = (text || '').trim();
-
-  // Candidatos a JSON, do mais provável ao mais permissivo: conteúdo de fence
-  // de código, resposta inteira, primeiro objeto {...} encontrado no texto.
-  const candidates = [];
-  const fence = raw.match(/```[a-zA-Z]*\s*\n?([\s\S]*?)```/);
-  if (fence) candidates.push(fence[1]);
-  candidates.push(raw);
-  const obj = raw.match(/\{[\s\S]*\}/);
-  if (obj) candidates.push(obj[0]);
-
-  for (const candidate of candidates) {
-    let parsed;
-    try {
-      parsed = JSON.parse(candidate.trim());
-    } catch {
-      continue; // tenta o próximo candidato
-    }
-    const list = Array.isArray(parsed?.findings) ? parsed.findings
-      : Array.isArray(parsed) ? parsed
-      : null;
-    if (!list) continue;
-    const findings = list
-      .filter(f => f && typeof f.text === 'string' && f.text.trim())
-      .map(f => ({
-        severity: /^grave/i.test(String(f.severity || '').trim()) ? 'grave' : 'menor',
-        text: f.text.trim(),
-      }));
-    return { grave: findings.some(f => f.severity === 'grave'), findings };
+export function normalizeAnchor(value) {
+  const m = ANCHOR_RE.exec(String(value ?? '').trim());
+  if (!m) return '';
+  return `${m[1].toLowerCase() === 'task' ? 'Task' : 'Story'} ${m[2]}`;
+}
+
+/**
+ * Valida o payload da crítica contra o schema (função PURA — testável).
+ *
+ * LANÇA CritiqueSchemaError nomeando o campo ofensor. Nunca "conserta" nem
+ * rebaixa: um finding grave mal formatado vira erro, não um menor silencioso.
+ *
+ * @param {*} payload objeto devolvido pelo modelo
+ * @returns {{ grave: boolean, findings: Array<{severity:'grave'|'menor', anchor?:string, text:string}> }}
+ */
+export function validateCritiquePayload(payload) {
+  if (payload === null || typeof payload !== 'object' || Array.isArray(payload)) {
+    throw new CritiqueSchemaError(
+      `o topo deveria ser um objeto {"findings": [...]}, veio ${describe(payload)}.`
+    );
+  }
+  const keys = Object.keys(payload);
+  if (!('findings' in payload)) {
+    throw new CritiqueSchemaError(
+      `chave obrigatória "findings" ausente no topo ` +
+      `(chaves recebidas: ${keys.join(', ') || 'nenhuma'}).`
+    );
+  }
+  const unknown = keys.filter(k => k !== 'findings');
+  if (unknown.length > 0) {
+    throw new CritiqueSchemaError(`chave(s) não reconhecida(s) no topo: ${unknown.join(', ')}.`);
+  }
+  if (!Array.isArray(payload.findings)) {
+    throw new CritiqueSchemaError(
+      `"findings" deveria ser um array, veio ${describe(payload.findings)}.`
+    );
   }
+  if (payload.findings.length > MAX_FINDINGS) {
+    throw new CritiqueSchemaError(
+      `"findings" trouxe ${payload.findings.length} itens (máximo ${MAX_FINDINGS}).`
+    );
+  }
+
+  const findings = payload.findings.map((item, i) => {
+    const at = `findings[${i}]`;
+    if (item === null || typeof item !== 'object' || Array.isArray(item)) {
+      throw new CritiqueSchemaError(`${at} deveria ser um objeto, veio ${describe(item)}.`);
+    }
+    const itemKeys = Object.keys(item);
+    if (!('severity' in item)) {
+      throw new CritiqueSchemaError(
+        `${at}.severity ausente (chaves recebidas: ${itemKeys.join(', ') || 'nenhuma'}).`
+      );
+    }
+    if (!('text' in item)) {
+      throw new CritiqueSchemaError(
+        `${at}.text ausente (chaves recebidas: ${itemKeys.join(', ') || 'nenhuma'}). ` +
+        'O campo com a descrição do finding DEVE se chamar "text".'
+      );
+    }
+    const extra = itemKeys.filter(k => k !== 'severity' && k !== 'text' && k !== 'anchor');
+    if (extra.length > 0) {
+      throw new CritiqueSchemaError(`${at} tem campo(s) não reconhecido(s): ${extra.join(', ')}.`);
+    }
+    // Normaliza só caixa e espaço — isso não é ambiguidade semântica. "GRAVE"
+    // passa; "gravíssimo", "critical" e "high" NÃO.
+    const severity = typeof item.severity === 'string' ? item.severity.trim().toLowerCase() : null;
+    if (!severity || !SEVERITY_SET.has(severity)) {
+      throw new CritiqueSchemaError(
+        `${at}.severity = ${JSON.stringify(item.severity)} não é um valor aceito ` +
+        `(aceitos, exatamente: ${CRITIQUE_SEVERITIES.map(s => `"${s}"`).join(' | ')}).`
+      );
+    }
+    if (typeof item.text !== 'string' || !item.text.trim()) {
+      throw new CritiqueSchemaError(
+        `${at}.text deveria ser uma string não-vazia, veio ${describe(item.text)}.`
+      );
+    }
+    const anchor = normalizeAnchor(item.anchor);
+    return { severity, ...(anchor ? { anchor } : {}), text: item.text.trim() };
+  });
 
-  // Fallback: resposta não-parseável → finding menor com a resposta bruta.
-  if (!raw) return { grave: false, findings: [] };
-  const truncated = raw.length > RAW_FALLBACK_MAX ? `${raw.slice(0, RAW_FALLBACK_MAX)}…` : raw;
-  return { grave: false, findings: [{ severity: 'menor', text: truncated }] };
+  return { grave: findings.some(f => f.severity === 'grave'), findings };
 }
 
-// Monta o comentário de issue a partir dos findings classificados.
-function renderMarkdown(findings) {
-  const header = '🔎 **Crítica adversarial (spec-wave)**';
-  if (findings.length === 0) {
-    return `${header}\n\n✅ crítica não encontrou contradições.`;
+// ---------------------------------------------------------------------------
+// Marcador de tentativa e contador
+// ---------------------------------------------------------------------------
+
+// Marcador HTML invisível na primeira linha de cada comentário de crítica, mesma
+// técnica do `spec-wave:usage`. É a partir dele que o contador de tentativas é
+// derivado, sem precisar ler o timeline de eventos da issue.
+export const CRITIQUE_MARKER_RE =
+  /<!--\s*spec-wave:critique\s+kind=(?<kind>[a-z]+)\s+attempt=(?<attempt>\d+)\s+verdict=(?<verdict>grave|limpa)\s*-->/g;
+
+/** Monta o marcador de uma tentativa (função PURA). */
+export function critiqueMarker({ kind, attempt, verdict }) {
+  return `<!-- spec-wave:critique kind=${kind} attempt=${attempt} verdict=${verdict} -->`;
+}
+
+/**
+ * Quantas reprovas consecutivas desta crítica já existem na issue (função PURA).
+ *
+ * O contador zera em DOIS pontos:
+ *  1. crítica limpa (verdict=limpa) — os documentos foram corrigidos e o ciclo
+ *     recomeça;
+ *  2. ausência de `spec-wave:critique-failed` na issue AGORA — um humano removeu
+ *     a label (ou nunca houve reprova), o que é decisão explícita de recomeçar.
+ *
+ * @param {object} params
+ * @param {Array<{body?:string}>} [params.comments] comentários em ordem cronológica
+ * @param {Array<string|{name:string}>} [params.labels] labels atuais da issue
+ * @param {'plan'|'stories'} params.kind críticas de plan e de stories contam separado
+ * @param {number} [params.maxAttempts]
+ * @returns {{ attempt: number, previous: number, blocked: boolean }}
+ *   attempt = a tentativa que ESTÁ para rodar; blocked = teto atingido, o
+ *   chamador aplica `spec-wave:needs-human` e aborta SEM chamar a IA.
+ */
+export function resolveCritiqueAttempt({
+  comments = [], labels = [], kind, maxAttempts = DEFAULT_MAX_CRITIQUE_ATTEMPTS,
+} = {}) {
+  const names = labelNames(labels);
+  if (names.includes(LABEL_NEEDS_HUMAN)) return { attempt: 0, previous: 0, blocked: true };
+  if (!names.includes(LABEL_CRITIQUE_FAILED)) return { attempt: 1, previous: 0, blocked: false };
+
+  let previous = 0;
+  for (const comment of comments) {
+    for (const m of String(comment?.body || '').matchAll(CRITIQUE_MARKER_RE)) {
+      if (m.groups.kind !== kind) continue;
+      previous = m.groups.verdict === 'limpa' ? 0 : previous + 1;
+    }
   }
+  const attempt = previous + 1;
+  return { attempt, previous, blocked: attempt >= maxAttempts };
+}
+
+/**
+ * Comentário de esgotamento das tentativas (função PURA).
+ *
+ * Sem marcador de tentativa de propósito: este comentário não deve ser contado
+ * como uma reprova a mais.
+ */
+export function renderNeedsHumanComment({
+  kind = 'plan', attempt = 0, maxAttempts = DEFAULT_MAX_CRITIQUE_ATTEMPTS, escalationModel = null,
+} = {}) {
+  return [
+    `🛑 **Crítica adversarial esgotou as tentativas** ` +
+    `(${attempt || maxAttempts}/${maxAttempts} — ${KIND_LABEL[kind] || KIND_LABEL.plan}).`,
+    'As reprovas anteriores estão nos comentários acima' +
+    (escalationModel ? ` (a última rodou no modelo de escalação \`${escalationModel}\`).` : '.'),
+    `A label \`${LABEL_NEEDS_HUMAN}\` foi aplicada e o fluxo está **parado**: nenhuma nova ` +
+    'crítica nem decomposição roda enquanto ela existir.',
+    `Para retomar: corrija os documentos, remova \`${LABEL_NEEDS_HUMAN}\` e ` +
+    `\`${LABEL_CRITIQUE_FAILED}\`, e reaplique a label de gatilho.`,
+  ].join('\n\n');
+}
+
+// ---------------------------------------------------------------------------
+// Renderização do comentário
+// ---------------------------------------------------------------------------
 
+// A remediação é DIFERENTE por contexto e a versão anterior falava sempre em
+// `spec-wave:ready` — instrução errada no decompose, onde a Feature já passou por
+// ele e o que precisa de correção é o rascunho da decomposição.
+const KIND_TRAILER = {
+  plan: (graves) => (graves
+    ? `⛔ Há findings **graves**: a label \`${LABEL_CRITIQUE_FAILED}\` bloqueia o ` +
+      '`spec-wave:ready` até ser removida. Corrija o `plan.md` (ou a `spec.md`) e ' +
+      'reaplique `spec-wave:plan`.'
+    : '_Findings menores não bloqueiam o `spec-wave:ready`._'),
+  stories: (graves) => (graves
+    ? '⛔ Há findings **graves**: **nenhuma Story/Task foi criada**. Corrija o ' +
+      `\`decomposition.md\` (as âncoras acima apontam para ele), remova a label ` +
+      `\`${LABEL_CRITIQUE_FAILED}\` e reaplique \`spec-wave:decompose\` para uma nova crítica.`
+    : '_Findings menores não bloqueiam a decomposição._'),
+};
+
+/**
+ * Sanitiza o texto de um finding (função PURA).
+ *
+ * Um finding é texto gerado por IA que entra numa lista markdown compartilhando o
+ * corpo do comentário com o marcador HTML de tentativa. Sem sanitizar: uma quebra
+ * de linha parte o item da lista, uma cerca ``` engole o resto do comentário, e um
+ * `-->` fecha o marcador antes da hora — corrompendo o contador de tentativas.
+ */
+export function sanitizeFindingText(text) {
+  const clean = String(text ?? '')
+    // ‑ (non-breaking hyphen) e ​ (zero-width space) mantêm a leitura
+    // e desarmam a sintaxe.
+    .replace(/<!--/g, '<!‑-')
+    .replace(/-->/g, '--‑>')
+    .replace(/```/g, '`​``')
+    .replace(/\s+/g, ' ')
+    .replace(/^[-*+>#\s]+/, '')
+    .trim();
+  return clean.length > MAX_FINDING_CHARS ? `${clean.slice(0, MAX_FINDING_CHARS)}…` : clean;
+}
+
+/**
+ * Monta o comentário da crítica (função PURA — testável).
+ *
+ * Primeira linha = marcador de tentativa. O texto de fecho depende do CONTEXTO
+ * (`kind`), porque a remediação é diferente: no plan é destravar o
+ * `spec-wave:ready`; no decompose é que nenhuma Story foi criada.
+ */
+export function renderCritiqueMarkdown({
+  kind = 'plan', findings = [], attempt = 1,
+  maxAttempts = DEFAULT_MAX_CRITIQUE_ATTEMPTS, model = '',
+} = {}) {
   const graves = findings.filter(f => f.severity === 'grave');
   const menores = findings.filter(f => f.severity === 'menor');
-  const parts = [header];
-  if (graves.length > 0) {
-    parts.push(`### ❌ Graves\n\n${graves.map(f => `- ${f.text}`).join('\n')}`);
-  }
-  if (menores.length > 0) {
-    parts.push(`### ⚠️ Menores\n\n${menores.map(f => `- ${f.text}`).join('\n')}`);
+  const parts = [
+    critiqueMarker({ kind, attempt, verdict: graves.length > 0 ? 'grave' : 'limpa' }),
+    `🔎 **Crítica adversarial (spec-wave)** — ${KIND_LABEL[kind] || KIND_LABEL.plan} · ` +
+    `tentativa ${attempt}/${maxAttempts}${model ? ` · modelo \`${model}\`` : ''}`,
+  ];
+
+  if (findings.length === 0) {
+    parts.push('✅ Nenhuma contradição encontrada.');
+    return parts.join('\n\n');
   }
-  parts.push(graves.length > 0
-    ? `⛔ Há findings **graves**: a label \`${LABEL_CRITIQUE_FAILED}\` bloqueia o ` +
-      `\`spec-wave:ready\` até ser removida após a correção dos pontos acima.`
-    : `_Findings menores não bloqueiam o fluxo. Se houvesse graves, a label ` +
-      `\`${LABEL_CRITIQUE_FAILED}\` bloquearia o \`spec-wave:ready\` até ser removida após correção._`);
+
+  const bullets = list => list
+    .map(f => `- ${f.anchor ? `**${f.anchor}** — ` : ''}${sanitizeFindingText(f.text)}`)
+    .join('\n');
+  if (graves.length > 0) parts.push(`### ❌ Graves\n\n${bullets(graves)}`);
+  if (menores.length > 0) parts.push(`### ⚠️ Menores\n\n${bullets(menores)}`);
+  parts.push((KIND_TRAILER[kind] || KIND_TRAILER.plan)(graves.length > 0));
   return parts.join('\n\n');
 }
 
+// ---------------------------------------------------------------------------
+// Execução
+// ---------------------------------------------------------------------------
+
 /**
  * Roda a crítica adversarial sobre os artefatos fornecidos.
  *
- * Seções ausentes (spec/plan/tech_context/stories) são simplesmente omitidas
- * do prompt. Erros de API PROPAGAM — o chamador deve tratar com try/catch e
- * seguir o fluxo principal (crítica indisponível não é fatal).
+ * Seções ausentes (spec/plan/tech_context/decomposition) são omitidas do prompt.
+ * Erros PROPAGAM — inclusive CritiqueSchemaError depois dos retries. Cabe ao
+ * chamador decidir entre seguir com aviso e abortar.
  *
  * @param {object} params
  * @param {'plan'|'stories'} params.kind o que está sendo auditado
  * @param {string} [params.spec] conteúdo do spec.md
  * @param {string} [params.plan] conteúdo do plan.md
  * @param {string} [params.techContextYaml] tech_context serializado em YAML
- * @param {object[]} [params.stories] stories propostas (antes da criação)
- * @param {object[]} [params.usage] coletor de uso de IA (repassado ao generateDocument)
- * @returns {Promise<{ grave: boolean, findings: Array<{ severity: string, text: string }>, markdown: string }>}
+ * @param {string} [params.decomposition] conteúdo do decomposition.md
+ * @param {number} [params.attempt] tentativa em curso (cabeçalho e marcador)
+ * @param {number} [params.maxAttempts]
+ * @param {string} [params.model] modelo imposto (escalada); undefined = cadeia normal
+ * @param {Array} [params.labels] labels da issue (override por label)
+ * @param {object[]} [params.usage] coletor de uso de IA
+ * @returns {Promise<{grave, findings, markdown, attempt, model}>}
  */
-export async function runCritique({ kind, spec, plan, techContextYaml, stories, usage } = {}) {
+export async function runCritique({
+  kind, spec, plan, techContextYaml, decomposition,
+  attempt = 1, maxAttempts = DEFAULT_MAX_CRITIQUE_ATTEMPTS,
+  model, labels = [], usage,
+} = {}) {
   const sections = [];
   if (spec) sections.push(`## spec.md\n\n${spec}`);
   if (plan) sections.push(`## plan.md\n\n${plan}`);
   if (techContextYaml) sections.push(`## tech_context\n\n\`\`\`yaml\n${techContextYaml}\n\`\`\``);
-  if (stories) sections.push(`## Stories propostas (JSON)\n\n\`\`\`json\n${JSON.stringify(stories, null, 2)}\n\`\`\``);
+  // Cerca de QUATRO crases: o decomposition.md contém cercas de três, e uma
+  // cerca de três aqui terminaria no primeiro bloco de código do documento.
+  if (decomposition) {
+    sections.push(
+      `## Decomposição proposta (decomposition.md)\n\n\`\`\`\`markdown\n${decomposition}\n\`\`\`\``
+    );
+  }
   const userContent = sections.join('\n\n') || '(nenhum documento fornecido)';
 
-  const raw = await generateDocument(buildSystemPrompt(kind), userContent, {
+  const report = await generateStructured(buildSystemPrompt(kind), userContent, {
     action: 'critique',
     temperature: 0,
-    // Teto próprio: a crítica devolve uma lista JSON de findings, bem menor que
-    // um spec/plan. 4096 ficava justo quando os dois documentos são longos e o
-    // JSON vinha cortado — o parse falhava sem dizer por quê. Com a detecção de
-    // truncamento o corte agora é explícito, e a folga evita chegar nele.
-    maxTokens: 8192,
+    schema: {
+      name: CRITIQUE_TOOL_NAME,
+      description:
+        'Registra o resultado da crítica adversarial. Use SEMPRE esta ferramenta — ' +
+        'nunca responda em texto livre. Lista vazia significa "nenhuma contradição".',
+      jsonSchema: critiqueJsonSchema(kind),
+      validate: validateCritiquePayload,
+    },
+    model,
+    labels,
     usage,
+    withReport: true,
   });
 
-  const { grave, findings } = parseCritiqueResponse(raw);
-  return { grave, findings, markdown: renderMarkdown(findings) };
+  const { grave, findings } = report.value;
+  return {
+    grave,
+    findings,
+    attempt,
+    model: report.model,
+    markdown: renderCritiqueMarkdown({ kind, findings, attempt, maxAttempts, model: report.model }),
+  };
 }