@payconductor/houndsman 0.13.0 → 0.16.0

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

@@ -23,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";
@@ -33,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

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],
 		};
 	}