@payconductor/houndsman 0.13.0 → 0.14.0

package/src/core/ai/prompts/brief.ts

@@ -6,6 +6,8 @@
  */
 
 import type { AstFileBrief } from "../../ast/types";
+import { type BusinessSummary, renderBusinessLines } from "../../business-summary";
+import type { ChangedScope } from "../../changed-scope";
 import type { ChurnMap, Rule, WatchdogRenderContext } from "../../types";
 import { buildSystem } from "./base";
 
@@ -21,6 +23,12 @@ export type BriefPromptInput = {
 	context?: WatchdogRenderContext | null;
 	ast?: readonly AstFileBrief[];
 	docs?: readonly string[];
+	/** Modelo de intenção da PR (contrato esperado). */
+	business?: BusinessSummary | null;
+	/** Trechos alterados — a única fonte real para verificar lógica. */
+	snippets?: readonly { file: string; snippet: string }[];
+	/** Faixas revisáveis por arquivo. */
+	changedScope?: ChangedScope;
 };
 
 /** Instruções de sistema do enriquecimento. */
@@ -29,11 +37,13 @@ export function briefInstructions(): string {
 		"Você é um revisor sênior que prepara um plano de leitura para um watchdog (revisor) especializado.",
 		[
 			"As regras fornecidas são o PISO da revisão, não o teto.",
-			"Além delas, procure riscos de consistência lógica: nome/contrato vs comportamento (ex.: `fazA` que faz `fazB`), fluxos incompletos, estados inválidos, off-by-one e bordas.",
-			"Procure também riscos do domínio de negócio: transições de estado, idempotência, arredondamento, timezone, autorização e invariantes implícitas.",
-			"Sugira foco de leitura (até 5), perguntas de verificação (até 3), riscos (até 3), verificações de lógica (até 3) e de domínio (até 3).",
+			"Derive cada verificação dos trechos alterados fornecidos — não apenas do nome do arquivo.",
+			"Toda verificação cita arquivo e, quando possível, símbolo; sem âncora, não sugira.",
+			"Além das regras, procure riscos de consistência lógica: nome/contrato vs comportamento (ex.: `fazA` que faz `fazB`), fluxos incompletos, estados inválidos, off-by-one e bordas.",
+			"Procure também riscos do domínio de negócio: transições de estado, idempotência, arredondamento, timezone, autorização, paridade de capacidade e invariantes implícitas.",
+			"Sugira foco de leitura (até 5), perguntas (até 3), riscos (até 3), verificações de lógica (até 4) e de domínio (até 4).",
 			"Sugira verificações, nunca afirme violação; não crie regra nova nem invente arquivo, linha ou achado.",
-			"Se uma suspeita não couber em nenhuma regra, coloque-a em `logic`/`domain` como pergunta de verificação.",
+			"Se uma suspeita não couber em nenhuma regra, coloque-a em `logic`/`domain` como verificação ancorada.",
 			"Não repita o texto literal das regras; o brief já as contém.",
 		],
 	);
@@ -62,6 +72,15 @@ export function briefPrompt(input: BriefPromptInput): string {
 			lines.push(`Motivação: ${input.context.motivation}`);
 		for (const item of input.context.changeSummary ?? []) lines.push(`- ${item}`);
 	}
+	if (input.business) {
+		const business = renderBusinessLines(input.business, {
+			flows: 8,
+			invariants: 8,
+			contracts: 8,
+			states: 4,
+		});
+		if (business.length > 0) lines.push("", "## Modelo de intenção", ...business);
+	}
 	if (input.ast && input.ast.length > 0) {
 		lines.push("", "## Estrutura (AST)");
 		for (const entry of input.ast) {
@@ -71,15 +90,22 @@ export function briefPrompt(input: BriefPromptInput): string {
 			);
 		}
 	}
+	if (input.snippets && input.snippets.length > 0) {
+		lines.push("", "## Trechos alterados (diff)");
+		for (const item of input.snippets.slice(0, 12)) {
+			lines.push(`### ${item.file}`, "```diff", item.snippet.trimEnd(), "```");
+		}
+	}
 	if (input.docs && input.docs.length > 0) {
 		lines.push("", "## Docs disponíveis", ...input.docs.map((doc) => `- ${doc}`));
 	}
 	lines.push(
 		"",
 		"## Revisão além das regras",
-		"As regras são o piso. Aponte verificações de consistência lógica e de domínio",
-		"que mereçam inspeção mesmo sem regra explícita (nome vs comportamento, estados,",
-		"transições, idempotência, bordas). Sugira verificações; não afirme violações.",
+		"As regras são o piso. Aponte verificações de lógica e domínio ancoradas nos",
+		"trechos alterados (nome vs comportamento, estados, transições, idempotência,",
+		"paridade de capacidade, credencial, bordas). Sugira verificações; não afirme",
+		"violações.",
 		"",
 		"Produza o plano de revisão em JSON (focus, questions, risks, logic, domain).",
 	);

package/src/core/ai/prompts/business.ts

@@ -0,0 +1,76 @@
+/**
+ * Prompt do modelo de intenção (`AiBusinessSummarizer`) e das hipóteses
+ * (`AiBusinessAnalyzer`).
+ *
+ * Os dois derivam **do diff**, nunca da prosa da PR. O primeiro descreve o
+ * contrato esperado; o segundo aponta suspeitas para o revisor `general`
+ * confirmar ou refutar (nunca viram achado sozinhas).
+ */
+
+import { buildSystem, clip, OUTPUT_LANGUAGE_RULE } from "./base";
+
+/** Instruções do resumo de negócio. */
+export function businessInstructions(): string {
+	return buildSystem(
+		"Você reconstrói a intenção de uma Pull Request a partir do diff real.",
+		[
+			OUTPUT_LANGUAGE_RULE,
+			"Descreva o comportamento que a PR promete entregar, não a estrutura do código.",
+			"Derive do diff fornecido: fluxos, invariantes, contratos e estados.",
+			"Paridade de capacidade é prioridade: se um lado declara feature/método/evento, verifique se o outro lado o honra.",
+			"Fluxos de ciclo de vida contam: criação, renovação, cancelamento, retry, webhook e erro.",
+			"Registre o que não estiver claro em `openQuestions`; não invente.",
+			"NÃO produza achados, severidade, arquivo:linha ou recomendação de correção.",
+			"Seja específico e curto: nomes de fluxo/contrato citam símbolos e arquivos reais.",
+		],
+	);
+}
+
+/** Prompt do usuário com o payload compactado. */
+export function businessPrompt(payload: unknown): string {
+	return [
+		"Reconstrua a intenção da PR abaixo.",
+		"",
+		"```json",
+		clip(JSON.stringify(payload), 24_000),
+		"```",
+		"",
+		"Produza o modelo de intenção em JSON.",
+	].join("\n");
+}
+
+/** Instruções das hipóteses de lógica/domínio. */
+export function businessAnalysisInstructions(): string {
+	return buildSystem(
+		"Você aponta suspeitas de gap de lógica/domínio para um revisor confirmar.",
+		[
+			OUTPUT_LANGUAGE_RULE,
+			"Use o modelo de intenção e os trechos alterados fornecidos.",
+			"Cada hipótese precisa citar um arquivo do escopo e uma afirmação concreta.",
+			"Prefira gaps de fluxo: caminho incompleto, capacidade declarada e não honrada, credencial/contexto divergente, estado sem tratamento, identificador trocado.",
+			"Confiança calibrada (0–1); abaixo de 0.5 não vale reportar.",
+			'`kind: "domain"` para invariantes/fluxo de negócio; `kind: "logic"` para nome/contrato vs comportamento.',
+			"NÃO invente arquivos e NÃO produza severidade — isto não é um achado.",
+			"No máximo 12 hipóteses.",
+		],
+	);
+}
+
+/** Prompt do usuário com intenção + trechos alterados. */
+export function businessAnalysisPrompt(business: unknown, payload: unknown): string {
+	return [
+		"## Modelo de intenção",
+		"",
+		"```json",
+		clip(JSON.stringify(business), 8_000),
+		"```",
+		"",
+		"## Diff compactado",
+		"",
+		"```json",
+		clip(JSON.stringify(payload), 16_000),
+		"```",
+		"",
+		"Produza as hipóteses em JSON.",
+	].join("\n");
+}

package/src/core/ai/provider-capabilities.ts

@@ -43,3 +43,15 @@ export function temperatureApplies(
 	if (provider !== "deepseek") return true;
 	return !deepSeekThinkingEnabled(modelId, providerOptions);
 }
+
+/**
+ * Opções para tarefas estruturadas curtas (resumo, plano, classificação).
+ *
+ * O thinking do DeepSeek V4 consome o teto de saída e dominava a latência: a
+ * resposta JSON truncava (`finishReason: "length"`) e a feature caía no
+ * fallback sem produzir nada. Desligar o raciocínio nessas chamadas mantém o
+ * schema e corta a latência. Providers não-DeepSeek ignoram a chave.
+ */
+export const LEAN_PROVIDER_OPTIONS: AiProviderOptions = {
+	deepseek: { thinking: { type: "disabled" } },
+};

package/src/core/ai/schemas.ts

@@ -43,18 +43,86 @@ export const TechnicalSummarySchema = z.object({
 });
 export type TechnicalSummaryPlan = z.infer<typeof TechnicalSummarySchema>;
 
+/** Verificação sugerida — sempre ancorada em arquivo/símbolo quando possível. */
+export const BriefCheckSchema = z.object({
+	statement: z.string().min(1).max(240),
+	file: z.string().max(200).optional(),
+	symbol: z.string().max(120).optional(),
+	/** Invariante que a verificação protege (`domain`). */
+	invariant: z.string().max(200).optional(),
+});
+export type BriefCheck = z.infer<typeof BriefCheckSchema>;
+
 /** Plano de revisão sugerido por IA para um brief. */
 export const BriefPlanSchema = z.object({
 	focus: z.array(z.string()).max(5).default([]),
 	questions: z.array(z.string()).max(3).default([]),
 	risks: z.array(z.string()).max(3).default([]),
 	/** Verificações de consistência lógica (fora das regras explícitas). */
-	logic: z.array(z.string()).max(3).default([]),
+	logic: z.array(BriefCheckSchema).max(4).default([]),
 	/** Riscos do domínio de negócio (fora das regras explícitas). */
-	domain: z.array(z.string()).max(3).default([]),
+	domain: z.array(BriefCheckSchema).max(4).default([]),
 });
 export type BriefPlan = z.infer<typeof BriefPlanSchema>;
 
+/** Modelo de intenção da PR (`business-summary.json`). */
+export const BusinessSummarySchema = z.object({
+	intent: z.string().max(800).optional(),
+	flows: z
+		.array(
+			z.object({
+				name: z.string().min(1).max(120),
+				trigger: z.string().max(240).optional(),
+				expected: z.string().max(400).optional(),
+				files: z.array(z.string().max(200)).max(20).optional(),
+			}),
+		)
+		.max(12)
+		.default([]),
+	invariants: z.array(z.string().max(300)).max(12).default([]),
+	contracts: z
+		.array(
+			z.object({
+				name: z.string().min(1).max(120),
+				sides: z.array(z.string().max(160)).max(8).optional(),
+				expectation: z.string().max(400).optional(),
+			}),
+		)
+		.max(12)
+		.default([]),
+	states: z
+		.array(
+			z.object({
+				name: z.string().min(1).max(120),
+				transitions: z.array(z.string().max(200)).max(12).optional(),
+			}),
+		)
+		.max(8)
+		.default([]),
+	nonGoals: z.array(z.string().max(240)).max(8).optional(),
+	openQuestions: z.array(z.string().max(300)).max(8).optional(),
+});
+export type BusinessSummaryPlan = z.infer<typeof BusinessSummarySchema>;
+
+/** Hipóteses de lógica/domínio (candidatos, nunca achados). */
+export const BusinessHypothesesSchema = z.object({
+	hypotheses: z
+		.array(
+			z.object({
+				file: z.string().min(1),
+				kind: z.enum(["logic", "domain"]),
+				statement: z.string().min(1).max(300),
+				invariant: z.string().max(200).optional(),
+				confidence: z.number().min(0).max(1),
+			}),
+		)
+		.max(12)
+		.default([]),
+});
+export type BusinessHypothesis = z.infer<
+	typeof BusinessHypothesesSchema
+>["hypotheses"][number];
+
 /** Classificação de arquivos não classificados. */
 export const ClassificationSchema = z.object({
 	assignments: z

package/src/core/ai/usage-recorder.ts

@@ -17,17 +17,36 @@ export type AiUsageEntry = {
 	usage: AiUsage;
 };
 
+/** Chamada que falhou (timeout, truncamento, schema) — não consome tokens. */
+export type AiFailureEntry = {
+	feature: string;
+	model: string;
+	at: string;
+	durationMs: number;
+	finishReason?: string;
+	error: string;
+};
+
+/** Uso agregado + tentativas/falhas (vai para `prepare-report.json`). */
+export type AiUsageSummary = AiUsage & {
+	attempts: number;
+	failures: AiFailureEntry[];
+};
+
 /** Formato persistido em `ai-usage.json`. */
 export type AiUsageFile = {
 	provider: string;
 	model: string;
 	total: AiUsage;
+	attempts: number;
 	entries: AiUsageEntry[];
+	failures: AiFailureEntry[];
 };
 
 /** Acumulador de uso (em memória) com persistência opcional. */
 export class AiUsageRecorder {
 	private readonly entries: AiUsageEntry[] = [];
+	private readonly failed: AiFailureEntry[] = [];
 	private readonly provider: string;
 	private readonly model: string;
 
@@ -41,7 +60,23 @@ export class AiUsageRecorder {
 		this.entries.push({ feature, model, at: systemClock(), usage: { ...usage } });
 	}
 
-	/** Total agregado de todas as chamadas. */
+	/** Registra uma tentativa que falhou (fail-open: nunca derruba a revisão). */
+	recordFailure(
+		feature: string,
+		model: string,
+		detail: { durationMs: number; error: string; finishReason?: string },
+	): void {
+		this.failed.push({
+			feature,
+			model,
+			at: systemClock(),
+			durationMs: detail.durationMs,
+			error: detail.error,
+			...(detail.finishReason ? { finishReason: detail.finishReason } : {}),
+		});
+	}
+
+	/** Total agregado de todas as chamadas concluídas. */
 	get total(): AiUsage {
 		return this.entries.reduce(
 			(acc, entry) => addUsage(acc, entry.usage),
@@ -49,13 +84,30 @@ export class AiUsageRecorder {
 		);
 	}
 
+	/** Tentativas (sucesso + falha) — a métrica honesta de custo/latência. */
+	get attempts(): number {
+		return this.entries.length + this.failed.length;
+	}
+
+	/** Falhas registradas, na ordem em que ocorreram. */
+	get failures(): readonly AiFailureEntry[] {
+		return this.failed;
+	}
+
+	/** Resumo para o `prepare-report.json`. */
+	get summary(): AiUsageSummary {
+		return { ...this.total, attempts: this.attempts, failures: [...this.failed] };
+	}
+
 	/** Snapshot serializável. */
 	toJSON(): AiUsageFile {
 		return {
 			provider: this.provider,
 			model: this.model,
 			total: this.total,
+			attempts: this.attempts,
 			entries: [...this.entries],
+			failures: [...this.failed],
 		};
 	}
 

package/src/core/brief.ts

@@ -6,6 +6,8 @@
  */
 
 import type { AstDelta } from "./ast/types";
+import { GENERAL_WATCHDOG_ID } from "./builtins";
+import { type BusinessSummary, renderBusinessLines } from "./business-summary";
 import { formatRanges, formatSymbols } from "./changed-scope";
 import {
 	type Rule,
@@ -19,15 +21,49 @@ import {
 
 /**
  * Procedimento de revisão — compartilhado por todos os watchdogs.
+ *
+ * O eixo é intenção → escopo → rastreio → prova: as regras continuam sendo o
+ * piso, mas a revisão começa entendendo o que a mudança deve entregar.
  */
 export const PROCEDURE: readonly string[] = [
-	"1. **FILTER** — descarte o que não for do seu domínio (ver *Prioridade de leitura* e *Não carregar*).",
-	"2. **READ SCOPE** — carregue apenas as faixas alteradas em *Escopo do diff*; o restante do arquivo é só contexto.",
-	"3. **GREP** — use as regras críticas/anti-padrões como heurística para localizar violações nas faixas alteradas.",
-	"4. **DEEP-READ** — aprofunde apenas as faixas com suspeita de violação dentro do escopo.",
-	'5. **CONCLUDE** — grave o JSON no caminho de output, com `reviewedFiles` preenchido e `line` dentro das faixas alteradas. Sem achados → `"findings": []` (arquivo obrigatório). Não escreva markdown livre.',
+	"1. **RECONSTRUCT** — leia o recorte do *Modelo de intenção (negócio)* e diga para si mesmo o que a mudança DEVE entregar (fluxos, invariantes, contratos). Sem modelo, derive do contexto da PR.",
+	"2. **SCOPE** — os *Trechos alterados (diff)* já estão no brief: **não releia o arquivo inteiro** para vê-los. Trecho com o marcador `… [trecho truncado]` pode ser aberto, uma vez, para o restante.",
+	"3. **TRACE** — siga cada símbolo alterado até seus chamadores, adapters e tipos compartilhados **dentro do seu domínio** (use os importadores do AST), **dentro do orçamento de exploração** (seção acima). Priorize os arquivos de maior churn.",
+	"4. **GREP** — use as regras críticas/anti-padrões como heurística para localizar violações nas faixas alteradas, **dentro do orçamento**. Pare quando tiver a prova: repetir busca não aumenta certeza.",
+	"5. **PROVE** — para cada suspeita, descreva gatilho → comportamento observado → invariante/regra violada. Sem prova, não é achado. Trecho com o marcador de truncamento só sustenta achado depois de abrir o arquivo para ver o restante.",
+	'6. **CONCLUDE** — grave o JSON no caminho de output. `reviewedFiles` é um subconjunto de `## Arquivos do seu domínio` (só o que você revisou; **não** liste chamadores/importadores nem arquivos de outros domínios) e o que ficou de fora entra em `skipped` ("budget", "truncated" ou "fora do fluxo"). Máximo de 20 achados: priorize severidade e agrupe ocorrências idênticas. `line` dentro das faixas alteradas. Sem achados → `"findings": []` (arquivo obrigatório). Não escreva markdown livre.',
 ];
 
+/**
+ * Orçamento de exploração por brief.
+ *
+ * O diff já cobre o essencial; o resto é para chamador/contexto de um símbolo
+ * citado. Sem teto, o subagente entrava em loop de leitura e cada brief levava
+ * minutos — o `general` era o pior caso (PR inteira).
+ */
+const EXPLORATION_BUDGET = {
+	general: { reads: 10, searches: 10 },
+	domain: { reads: 6, searches: 6 },
+} as const;
+
+/** Seção com o teto de leituras/buscas do brief (visível para o modelo). */
+function explorationSection(args: WatchdogRenderArgs): string[] {
+	const budget =
+		args.watchdogId === GENERAL_WATCHDOG_ID
+			? EXPLORATION_BUDGET.general
+			: EXPLORATION_BUDGET.domain;
+	return [
+		"## Orçamento de exploração",
+		"",
+		`> O diff já está no brief. Limite **neste brief**: ${budget.reads} leitura(s) de arquivo`,
+		`> e ${budget.searches} busca(s) (grep).`,
+		"> Abra arquivo só para chamador/contexto de um símbolo citado nos trechos.",
+		"> Se a prova não estiver no brief nem nesse orçamento, **não é achado** —",
+		"> registre a dúvida no campo `action` do finding mais próximo ou descarte.",
+		"",
+	];
+}
+
 /** Limites do contexto injetado em cada brief (o resumo final é maior). */
 const BRIEF_CONTEXT_LIMITS = {
 	objective: 200,
@@ -157,18 +193,18 @@ function fileItems(args: WatchdogRenderArgs): string[] {
 }
 
 /**
- * Arquivos do domínio fora do orçamento (triage de PRs grandes): o watchdog NÃO
+ * Arquivos do domínio fora do recorte (orçamento ou fluxo): o watchdog NÃO
  * deve lê-los, mas precisa registrá-los em `skipped` — cobertura honesta.
  */
 function overflowSection(args: WatchdogRenderArgs): string[] {
 	const overflow = args.overflow ?? [];
 	if (overflow.length === 0) return [];
 	return [
-		"## Fora do orçamento (NÃO revisar)",
+		"## Fora do recorte (NÃO revisar)",
 		"",
-		`> ${overflow.length} arquivo(s) do seu domínio ficaram fora do orçamento`,
-		"> (menor churn). Não os leia: registre-os em `skipped` com o motivo",
-		'> "budget" para que a cobertura do relatório fique honesta.',
+		`> ${overflow.length} arquivo(s) do escopo ficaram fora do recorte`,
+		"> (orçamento ou prioridade de fluxo). Não os leia: registre-os em `skipped`",
+		"> com o motivo (`budget` ou `fora do fluxo`) para que a cobertura fique honesta.",
 		"",
 		...overflow.map(codeItem),
 		"",
@@ -227,6 +263,143 @@ function deltaLines(delta: AstDelta): string[] {
 	return lines;
 }
 
+/** Rótulo curto da fonte do modelo de intenção. */
+const BUSINESS_SOURCE_LABEL: Record<BusinessSummary["source"], string> = {
+	ai: "IA",
+	reviewer: "revisor de fluxo",
+	deterministic: "determinístico",
+};
+
+/**
+ * Recorte do modelo de intenção: só fluxos que tocam os arquivos do watchdog.
+ *
+ * O modelo é global; injetá-lo inteiro em cada brief fazia o subagente
+ * perseguir fluxos de outros domínios (mais leituras e buscas sem achado).
+ */
+function scopeBusinessToFiles(
+	business: BusinessSummary,
+	files: readonly string[],
+): BusinessSummary {
+	if (files.length === 0) return business;
+	// O modelo vem da IA e pode usar `./`, `\` ou caminho absoluto: normaliza
+	// antes de comparar para não perder um fluxo do próprio domínio.
+	const normalize = (value: string): string =>
+		value.replace(/\\/g, "/").replace(/^\.\//, "");
+	const own = new Set(files.map(normalize));
+	const flows = business.flows.filter(
+		(flow) =>
+			!flow.files ||
+			flow.files.length === 0 ||
+			flow.files.some((file) => own.has(normalize(file))),
+	);
+	if (flows.length === business.flows.length) return business;
+	return { ...business, flows };
+}
+
+/**
+ * Modelo de intenção da PR — o contrato esperado antes de julgar o código.
+ *
+ * Injetado em todos os briefs; o revisor `general` recebe o modelo completo, os
+ * watchdogs de domínio recebem só o recorte dos seus arquivos.
+ */
+function businessSection(args: WatchdogRenderArgs): string[] {
+	const business = args.business;
+	if (!business) return [];
+	const isGeneral = args.watchdogId === GENERAL_WATCHDOG_ID;
+	const scoped = isGeneral
+		? business
+		: { ...scopeBusinessToFiles(business, args.files), openQuestions: [] };
+	const omitted = business.flows.length - scoped.flows.length;
+	// O caminho canônico só interessa a quem reconstrói o modelo (`general`):
+	// nos demais, citá-lo induzia uma leitura extra do JSON completo.
+	const canonical =
+		args.businessSummaryPath && (isGeneral || args.flowReview)
+			? ` · \`${args.businessSummaryPath}\` (versão canônica no staging)`
+			: "";
+	const lines = [
+		"## Modelo de intenção (negócio)",
+		"",
+		`> Fonte: ${BUSINESS_SOURCE_LABEL[business.source]}${canonical}. Use para saber o que a mudança **deve** entregar; não é achado.`,
+		"",
+	];
+	if (!isGeneral) {
+		lines.push(
+			"> Recorte do seu domínio: fluxos/arquivos de outros domínios pertencem a outros watchdogs — não os investigue.",
+			...(omitted > 0
+				? [`> ${omitted} fluxo(s) fora do seu domínio foram omitidos.`]
+				: []),
+			"",
+		);
+	}
+	const rendered = renderBusinessLines(
+		scoped,
+		isGeneral
+			? { flows: 12, invariants: 12, contracts: 12, states: 8 }
+			: { flows: 3, invariants: 6, contracts: 2, states: 2 },
+	);
+	while (rendered[0] === "") rendered.shift();
+	lines.push(...rendered, "");
+	return lines;
+}
+
+/** Trechos alterados (diff) — todos os watchdogs recebem o patch do seu domínio. */
+function snippetsSection(args: WatchdogRenderArgs): string[] {
+	const snippets = args.snippets ?? [];
+	if (snippets.length === 0) return [];
+	const lines = [
+		"## Trechos alterados (diff)",
+		"",
+		"> Trechos já extraídos do diff (`-U0`, só linhas alteradas). Eles bastam",
+		"> para achar violações: **não abra os arquivos apenas para reler o que já",
+		"> está aqui**. Use o arquivo só para contexto adjacente ou chamadores.",
+		"",
+	];
+	for (const item of snippets) {
+		lines.push(
+			`### \`${item.file}\``,
+			"",
+			"```diff",
+			item.snippet.trimEnd(),
+			"```",
+			"",
+		);
+	}
+	return lines;
+}
+
+/**
+ * Obrigação de output do revisor de fluxo: ele reconstrói e persiste o modelo
+ * de intenção (ou devolve `businessSummary` no harness local).
+ */
+function flowReviewSection(args: WatchdogRenderArgs): string[] {
+	if (!args.flowReview) return [];
+	const output = args.businessSummaryPath ?? "business-summary.json";
+	return [
+		"## Obrigação de output (fluxo)",
+		"",
+		"1. **Recomece pelo modelo**: leia o diff e reconstrua intenção, fluxos, invariantes,",
+		"   contratos e estados. Se o modelo existente estiver incompleto, corrija-o.",
+		`2. **Persista** o modelo em \`${output}\` com \`source: "reviewer"\`.`,
+		"   No harness local (maki), devolva o mesmo objeto em `businessSummary` no JSON.",
+		"3. **Prove cada gap**: fora de regra, preencha `scenario` (gatilho concreto),",
+		"   `impact` (consequência observável) e `evidence` (trecho). Sem `scenario` + `evidence`,",
+		"   a severidade máxima é `attention`.",
+		"",
+	];
+}
+
+/** Linha de verificação (string legada ou objeto ancorado). */
+function checkItem(
+	item:
+		| string
+		| { statement: string; file?: string; symbol?: string; invariant?: string },
+): string {
+	if (typeof item === "string") return `- ${item}`;
+	const anchor = [item.file, item.symbol].filter(Boolean).join(" · ");
+	const invariant = item.invariant ? ` (invariante: ${item.invariant})` : "";
+	return `- ${item.statement}${anchor ? ` — \`${anchor}\`` : ""}${invariant}`;
+}
+
 /**
  * Plano de revisão sugerido por IA — complementa (nunca substitui) as regras.
  */
@@ -271,17 +444,72 @@ function aiPlanSection(args: WatchdogRenderArgs): string[] {
 	}
 	if (logic.length > 0) {
 		lines.push("**Consistência lógica:**", "");
-		for (const item of logic.slice(0, 3)) lines.push(`- ${item}`);
+		for (const item of logic.slice(0, 4)) lines.push(checkItem(item));
 		lines.push("");
 	}
 	if (domain.length > 0) {
 		lines.push("**Domínio de negócio:**", "");
-		for (const item of domain.slice(0, 3)) lines.push(`- ${item}`);
+		for (const item of domain.slice(0, 4)) lines.push(checkItem(item));
 		lines.push("");
 	}
 	return lines;
 }
 
+/**
+ * Micro-alterações iguais em muitos arquivos: mostra o padrão dominante e os
+ * outliers em vez de N diffs de uma linha.
+ */
+function propagationSection(args: WatchdogRenderArgs): string[] {
+	const cluster = args.propagation;
+	if (!cluster || cluster.files.length === 0) return [];
+	const sample = cluster.files.slice(0, 5).map(inlineCode).join(", ");
+	const rest = cluster.files.length > 5 ? ` (+${cluster.files.length - 5})` : "";
+	const lines = [
+		"## Propagação mecânica",
+		"",
+		`> ${cluster.files.length} arquivo(s) com a mesma micro-alteração (≤3 linhas).`,
+		"> Revise o padrão e os outliers; **não abra** os demais — registre-os em",
+		"> `skipped` com o motivo `propagação mecânica`.",
+		"",
+		"```diff",
+		...cluster.lines.map((line) => `+${line}`),
+		"```",
+		"",
+		`Arquivos: ${sample}${rest}`,
+		"",
+	];
+	if (cluster.outliers.length > 0) {
+		lines.push("**Outliers (revisar):**", "");
+		for (const outlier of cluster.outliers) {
+			lines.push(
+				`- ${inlineCode(outlier.file)}: \`${shorten(outlier.lines.join(" ⏎ "), 160)}\``,
+			);
+		}
+		lines.push("");
+	}
+	return lines;
+}
+
+/** Contratos alterados cujos importadores não aparecem no diff. */
+function propagationGapSection(args: WatchdogRenderArgs): string[] {
+	const gaps = args.propagationGaps ?? [];
+	if (gaps.length === 0) return [];
+	const lines = [
+		"## Possível propagação incompleta",
+		"",
+		"> Contratos alterados cujos importadores **não** aparecem no diff. Confirme",
+		"> se cada um precisa acompanhar a mudança antes de concluir.",
+		"",
+	];
+	for (const gap of gaps) {
+		lines.push(
+			`- ${inlineCode(gap.file)} → ${gap.importers.map(inlineCode).join(", ")}`,
+		);
+	}
+	lines.push("");
+	return lines;
+}
+
 /**
  * Estrutura/delta dos arquivos do watchdog (AST). É um mapa para orientar a
  * leitura — o watchdog confirma no código e não trata como achado.
@@ -346,6 +574,11 @@ export function defaultRenderBrief(
 
 	if (args.context) lines.push(...renderBriefContext(args.context));
 
+	lines.push(...businessSection(args));
+	lines.push(...snippetsSection(args));
+	lines.push(...propagationSection(args));
+	lines.push(...propagationGapSection(args));
+	lines.push(...flowReviewSection(args));
 	lines.push(...aiPlanSection(args));
 	lines.push(...astSection(args));
 	lines.push(...optionalList("Prioridade de leitura", def.reviewFocus));
@@ -378,6 +611,7 @@ export function defaultRenderBrief(
 
 	lines.push(...deletedSection(args, def));
 	lines.push(...optionalList("Não carregar", def.exclude));
+	lines.push(...explorationSection(args));
 	lines.push("## Procedimento", "", ...PROCEDURE);
 
 	return lines;