@payconductor/houndsman 0.12.0 → 0.14.0

package/src/cli/index.ts

@@ -12,9 +12,10 @@
  *
  * Comandos:
  *   (default)            Passo 1 — preparar (classificação + briefs + manifesto)
- *   --finalize           Passo 3 — consolidar os findings em review.md
+ *   --finalize           Passo 3 — consolidar os findings no resumo final
  *   context              Passo 0 — coletar o contexto da PR via `gh`
  *   findings <sub>       Triagem/correção dos findings (list/set/done/sync/batch/verify/submit/...)
+ *   hunt [flags]         Harness local (maki): prepare → watchdogs via maki → finalize
  *   status [ping]        Mostra o status da run; `ping` renova o heartbeat da execução
  *   server               Sobe a UI local de triagem (Bun.serve)
  *   setup                Cria a configuração inicial do projeto (config + skills)
@@ -30,14 +31,16 @@
 import type { HoundsmanConfig } from "../core/config";
 import { loadConfig } from "../core/config-loader";
 import { HoundsmanEngine } from "../core/engine/houndsman-engine";
-import { logger } from "../core/logging";
+import { formatDuration, logger } from "../core/logging";
 import { syncProjectLayerForRoot } from "../core/services/worktree-manager";
 import { ArgParser } from "./arg-parser";
 import type { CliContext } from "./commands/command";
+import { CompareCommand } from "./commands/compare-command";
 import { ContextCommand } from "./commands/context-command";
 import { DoctorCommand } from "./commands/doctor-command";
 import { FindingsCommand } from "./commands/findings-command";
 import { HelpCommand } from "./commands/help-command";
+import { HuntCommand } from "./commands/hunt-command";
 import { CommandRegistry } from "./commands/registry";
 import { ReviewCommand } from "./commands/review-command";
 import { ServerCommand } from "./commands/server-command";
@@ -57,7 +60,9 @@ function buildRegistry(): CommandRegistry {
 	return new CommandRegistry()
 		.register(new ReviewCommand(), { fallback: true })
 		.register(new HelpCommand())
+		.register(new HuntCommand())
 		.register(new ContextCommand())
+		.register(new CompareCommand())
 		.register(new FindingsCommand())
 		.register(new StatusCommand())
 		.register(new WatchdogCommand())
@@ -88,14 +93,26 @@ export async function main(): Promise<void> {
 	}
 
 	let loaded: Awaited<ReturnType<typeof loadConfig>> | null = null;
+	// `--json` é contrato de máquina: nada de progresso no stdout.
+	const silentProgress = parser.has("--json");
 	const config = async (): Promise<HoundsmanConfig> => {
 		loaded ??= await (async () => {
+			const started = Date.now();
+			if (!silentProgress) logger.step("Carregando a configuração do projeto…");
 			// Rodando dentro de um worktree, a camada gerada (`.houndsman/core`)
 			// não existe (é ignorada pelo git). Repõe a partir do clone principal
 			// antes de importar a config — sem isso os watchdogs não resolvem
 			// `../core/types`. No clone principal é no-op.
 			syncProjectLayerForRoot(process.cwd());
-			return loadConfig({ configPath: parser.value("--config") });
+			const result = await loadConfig({ configPath: parser.value("--config") });
+			if (!silentProgress) {
+				logger.success(
+					`Configuração: ${result.config.projectName} · ` +
+						`${result.config.watchdogIds.length} watchdog(s) ` +
+						`(${formatDuration(Date.now() - started)})`,
+				);
+			}
+			return result;
 		})();
 		return loaded.config;
 	};

package/src/cli/progress.ts

@@ -0,0 +1,50 @@
+/**
+ * Progresso do CLI por etapa do prepare (apresentação).
+ *
+ * O core emite eventos (`PrepareProgressEvent`); aqui eles viram spinner/linha
+ * com a duração de cada fase — o `hunt` começa a dar sinal de vida antes do
+ * primeiro `Discovery:`.
+ */
+
+import { formatDuration, type LoggerLike, ParallelPhaseReporter } from "../core/logging";
+import type { PrepareProgress, PrepareStage } from "../core/orchestrator";
+
+/** Texto de cada etapa (início no gerúndio, fim no particípio). */
+export const PREPARE_STAGE_TEXT: Record<PrepareStage, { start: string; done: string }> = {
+	diff: { start: "Lendo o diff da revisão", done: "Diff lido" },
+	ast: { start: "Analisando a AST dos arquivos alterados", done: "AST analisada" },
+	classify: {
+		start: "Classificando os arquivos por watchdog",
+		done: "Classificação concluída",
+	},
+	impact: { start: "Medindo o impacto nos importadores", done: "Impacto calculado" },
+	jev: { start: "Pré-analisando o diff (Jev/IA)", done: "Pré-análise concluída" },
+	context: { start: "Resumindo o contexto da PR", done: "Contexto resumido" },
+	business: {
+		start: "Reconstruindo a intenção da PR",
+		done: "Intenção reconstruída",
+	},
+	technical: {
+		start: "Consolidando os pontos técnicos",
+		done: "Pontos técnicos prontos",
+	},
+	"ai-plans": { start: "Planejando os briefs com IA", done: "Planos de brief prontos" },
+	briefs: { start: "Gerando os briefs", done: "Briefs gerados" },
+	manifest: { start: "Gravando o manifesto da revisão", done: "Manifesto gravado" },
+};
+
+/** Cria o callback de progresso do prepare ligado ao logger do CLI. */
+export function prepareProgress(logger: LoggerLike): PrepareProgress {
+	// O prepare roda etapas em paralelo; o reporter aceita fases concorrentes.
+	const reporter = new ParallelPhaseReporter(logger);
+	return (event) => {
+		const text = PREPARE_STAGE_TEXT[event.stage];
+		if (event.type === "start") reporter.begin(event.stage, text.start);
+		else reporter.end(event.stage, text.done, event.durationMs);
+	};
+}
+
+/** Log de um passo concluído com a duração (usado fora do prepare). */
+export function stepDone(logger: LoggerLike, message: string, startedMs: number): void {
+	logger.success(`${message} (${formatDuration(Date.now() - startedMs)})`);
+}

package/src/core/ai/ai-client.ts

@@ -10,6 +10,7 @@ import type { AiProviderOptions } from "../config";
 import type { ProjectConfig } from "../project-config";
 import { AiConfigurationError, errorMessage } from "./errors";
 import { ModelFactory } from "./model-factory";
+import { LEAN_PROVIDER_OPTIONS } from "./provider-capabilities";
 import type { AiResult, AiUsage, ModelProvider, ModelRequest } from "./types";
 import { AiUsageBudget } from "./usage-budget";
 import { AiUsageRecorder } from "./usage-recorder";
@@ -109,7 +110,13 @@ export class AiClient {
 	): Promise<AiResult<T>> {
 		return this.run(
 			feature,
-			{ ...request, outputSchema: request.outputSchema },
+			{
+				...request,
+				outputSchema: request.outputSchema,
+				providerOptions:
+					request.providerOptions ??
+					leanProviderOptions(this.project.aiProviderOptions),
+			},
 			model,
 		);
 	}
@@ -183,6 +190,7 @@ export class AiClient {
 			return { ok: false, error: errorMessage(error) };
 		}
 
+		const startedAt = Date.now();
 		try {
 			const provider = await this.requireProvider(model);
 			const response = await provider.generate({
@@ -193,6 +201,17 @@ export class AiClient {
 				),
 				signal: combineSignals(request.signal, this.project.aiTimeoutMs),
 			});
+			// Objeto truncado não é resultado parcial útil: sem o JSON completo a
+			// feature inteira caía silenciosamente no fallback. Registra e falha.
+			if (request.outputSchema && response.finishReason === "length") {
+				const error = `Resposta truncada (finishReason=length; maxOutputTokens=${request.maxOutputTokens ?? "sem teto"}).`;
+				this.recorder.recordFailure(feature, provider.modelId, {
+					durationMs: Date.now() - startedAt,
+					error,
+					finishReason: response.finishReason,
+				});
+				return { ok: false, error };
+			}
 			this.budget.record(response.usage);
 			this.recorder.record(feature, provider.modelId, response.usage);
 			return {
@@ -202,7 +221,12 @@ export class AiClient {
 				model: provider.modelId,
 			};
 		} catch (error) {
-			return { ok: false, error: errorMessage(error) };
+			const message = errorMessage(error);
+			this.recorder.recordFailure(feature, model ?? this.modelId, {
+				durationMs: Date.now() - startedAt,
+				error: message,
+			});
+			return { ok: false, error: message };
 		}
 	}
 }
@@ -221,6 +245,18 @@ function mergeProviderOptions(
 	return merged;
 }
 
+/**
+ * Opções enxutas para objetos estruturados: thinking desligado, salvo quando o
+ * projeto já configurou `thinking` explicitamente — aí a config manda.
+ */
+function leanProviderOptions(
+	base: AiProviderOptions | undefined,
+): AiProviderOptions | undefined {
+	const configured = base?.deepseek;
+	if (configured && "thinking" in configured) return undefined;
+	return LEAN_PROVIDER_OPTIONS;
+}
+
 /** Combina o sinal do chamador com o timeout configurado. */
 function combineSignals(
 	signal: AbortSignal | undefined,

package/src/core/ai/ai-sdk-model-provider.ts

@@ -31,6 +31,43 @@ function numberOrZero(value: unknown): number {
 	return typeof value === "number" && Number.isFinite(value) ? value : 0;
 }
 
+/**
+ * Silencia o emissor default de avisos do AI SDK.
+ *
+ * O default usa `process.emitWarning` — com stack trace — a cada chamada, o que
+ * polui o stderr do CLI. Os avisos continuam disponíveis no resultado da
+ * chamada (`ModelResponse.warnings`). Um chamador que queira o comportamento
+ * original basta definir `AI_SDK_LOG_WARNINGS` antes de usar o SDK.
+ */
+function installWarningSink(): void {
+	if (globalThis.AI_SDK_LOG_WARNINGS === undefined) {
+		globalThis.AI_SDK_LOG_WARNINGS = () => {};
+	}
+}
+
+installWarningSink();
+
+/** Normaliza um aviso do provider em texto legível (puro). */
+export function formatSdkWarning(raw: unknown): string {
+	const warning = (raw ?? {}) as Record<string, unknown>;
+	const label = [warning.type, warning.feature, warning.setting]
+		.filter((value): value is string => typeof value === "string" && value !== "")
+		.join(": ");
+	const detail =
+		typeof warning.details === "string"
+			? warning.details
+			: typeof warning.message === "string"
+				? warning.message
+				: "";
+	const head = label || "aviso";
+	return detail ? `${head} — ${detail}` : head;
+}
+
+/** Lista de avisos do provider em texto (puro). */
+export function formatSdkWarnings(raw: unknown): string[] {
+	return Array.isArray(raw) ? raw.map(formatSdkWarning) : [];
+}
+
 /** Argumentos aceitos por `generateText` (inclui `providerOptions` do SDK). */
 type GenerateTextArgs = Parameters<typeof generateText>[0];
 
@@ -86,10 +123,12 @@ export class AiSdkModelProvider implements ModelProvider {
 			const output = request.outputSchema
 				? (result.output as T)
 				: ((result.text ?? "") as unknown as T);
+			const warnings = formatSdkWarnings(result.warnings);
 			return {
 				output,
 				usage: mapUsage(result.usage),
 				finishReason: result.finishReason ?? "unknown",
+				...(warnings.length > 0 ? { warnings } : {}),
 			};
 		} catch (error) {
 			if (error instanceof Error && error.name === "AbortError") {

package/src/core/ai/features/brief-enricher.ts

@@ -27,7 +27,7 @@ export class AiBriefEnricher {
 				instructions: briefInstructions(),
 				prompt: briefPrompt(input),
 				outputSchema: BriefPlanSchema,
-				maxOutputTokens: 700,
+				maxOutputTokens: 1_400,
 			},
 			this.client.projectConfig.aiModelFor(input.watchdogId),
 		);

package/src/core/ai/features/business-analyzer.ts

@@ -0,0 +1,61 @@
+/**
+ * Hipóteses de lógica/domínio via IA (`AiBusinessAnalyzer`).
+ *
+ * Produz **candidatos** para o revisor `general` confirmar ou refutar — nunca
+ * achados. Serve para dar cobertura a PRs maiores que o orçamento do brief.
+ */
+
+import { GENERAL_WATCHDOG_ID } from "../../builtins";
+import type { BusinessInput, BusinessSummary } from "../../business-summary";
+import { buildBusinessPromptPayload } from "../../business-summary";
+import type { JevCandidate } from "../../jev";
+import type { AiClient } from "../ai-client";
+import {
+	businessAnalysisInstructions,
+	businessAnalysisPrompt,
+} from "../prompts/business";
+import { BusinessHypothesesSchema, type BusinessHypothesis } from "../schemas";
+
+/** Confiança mínima para a hipótese virar candidato. */
+const MIN_CONFIDENCE = 0.5;
+
+/** Gera hipóteses de fluxo para o watchdog `general`. */
+export class AiBusinessAnalyzer {
+	constructor(private readonly client: AiClient) {}
+
+	/** `true` quando a feature está ligada e há IA disponível. */
+	get enabled(): boolean {
+		return this.client.available && this.client.features.business;
+	}
+
+	/** Candidatos validados contra os arquivos do escopo. */
+	async analyze(input: {
+		business: BusinessSummary;
+		payload: BusinessInput;
+	}): Promise<JevCandidate[]> {
+		if (!this.enabled) return [];
+		const files = new Set(Object.keys(input.payload.classification.files));
+		const result = await this.client.generateObject<{
+			hypotheses: BusinessHypothesis[];
+		}>("business-analysis", {
+			instructions: businessAnalysisInstructions(),
+			prompt: businessAnalysisPrompt(
+				input.business,
+				buildBusinessPromptPayload(input.payload),
+			),
+			outputSchema: BusinessHypothesesSchema,
+			maxOutputTokens: 1_600,
+		});
+		if (!result.ok) return [];
+		return result.output.hypotheses
+			.filter((item) => files.has(item.file) && item.confidence >= MIN_CONFIDENCE)
+			.map((item, index) => ({
+				watchdogId: GENERAL_WATCHDOG_ID,
+				rule: `${item.kind === "domain" ? "Domínio" : "Lógica"}: ${item.statement}`,
+				severity: "attention" as const,
+				file: item.file,
+				confidence: item.confidence,
+				questionKey: `business-${index}`,
+			}));
+	}
+}

package/src/core/ai/features/business-summarizer.ts

@@ -0,0 +1,44 @@
+/**
+ * Modelo de intenção via IA (`AiBusinessSummarizer`).
+ *
+ * Fail-open: sem IA/chave/feature a feature fica desligada e o prepare mantém o
+ * modelo determinístico. A saída é validada por schema — nada de texto solto.
+ */
+
+import {
+	type BusinessInput,
+	type BusinessSummary,
+	buildBusinessPromptPayload,
+	parseBusinessSummary,
+} from "../../business-summary";
+import type { AiClient } from "../ai-client";
+import { businessInstructions, businessPrompt } from "../prompts/business";
+import { type BusinessSummaryPlan, BusinessSummarySchema } from "../schemas";
+
+/** Reconstrói a intenção da PR a partir do diff. */
+export class AiBusinessSummarizer {
+	constructor(private readonly client: AiClient) {}
+
+	/** `true` quando a feature está ligada e há IA disponível. */
+	get enabled(): boolean {
+		return this.client.available && this.client.features.business;
+	}
+
+	/** Falha-aberto: sem IA ou saída inválida → `null`. */
+	async summarize(input: BusinessInput): Promise<BusinessSummary | null> {
+		if (!this.enabled) return null;
+		const result = await this.client.generateObject<BusinessSummaryPlan>("business", {
+			instructions: businessInstructions(),
+			prompt: businessPrompt(buildBusinessPromptPayload(input)),
+			outputSchema: BusinessSummarySchema,
+			// Schema permite 12 fluxos/12 contratos: 1.400 truncava com thinking ligado.
+			maxOutputTokens: 2_000,
+		});
+		if (!result.ok) return null;
+		return parseBusinessSummary(
+			{ ...result.output, source: "ai", headSha: input.headSha },
+			"ai",
+			input.headSha,
+		);
+	}
+}

package/src/core/ai/index.ts

@@ -10,7 +10,12 @@ export type {
 	TextRequest,
 } from "./ai-client";
 export { AiClient } from "./ai-client";
-export { AiSdkModelProvider, mapUsage } from "./ai-sdk-model-provider";
+export {
+	AiSdkModelProvider,
+	formatSdkWarning,
+	formatSdkWarnings,
+	mapUsage,
+} from "./ai-sdk-model-provider";
 export {
 	AiBudgetError,
 	AiConfigurationError,
@@ -18,6 +23,8 @@ export {
 	errorMessage,
 } from "./errors";
 export { AiBriefEnricher } from "./features/brief-enricher";
+export { AiBusinessAnalyzer } from "./features/business-analyzer";
+export { AiBusinessSummarizer } from "./features/business-summarizer";
 export { AiClassifier } from "./features/classifier";
 export { AiContextSummarizer } from "./features/context-summarizer";
 export { AiPreAnalyzer } from "./features/pre-analyzer";
@@ -28,8 +35,14 @@ export {
 	type AiCandidate,
 	type AiClassification,
 	type AiVerdict,
+	type BriefCheck,
+	BriefCheckSchema,
 	type BriefPlan,
 	BriefPlanSchema,
+	BusinessHypothesesSchema,
+	type BusinessHypothesis,
+	type BusinessSummaryPlan,
+	BusinessSummarySchema,
 	CandidateSchema,
 	ClassificationSchema,
 	type ContextSummaryPlan,

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