@payconductor/houndsman 0.12.0 → 0.14.0

package/src/core/ai/types.ts

@@ -50,6 +50,8 @@ export type ModelResponse<T> = {
 	output: T;
 	usage: AiUsage;
 	finishReason: string;
+	/** Avisos do provider já normalizados em texto (ex.: modo de compatibilidade). */
+	warnings?: string[];
 };
 
 /** Provider de modelo (adaptador do AI SDK ou fake nos testes). */

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;

package/src/core/builtins.ts

@@ -0,0 +1,108 @@
+/**
+ * Watchdogs embutidos do motor.
+ *
+ * Diferente dos watchdogs do consumidor, estes existem por padrão e não podem
+ * ser desligados: são parte do fluxo de revisão. O `general` audita a lógica e o
+ * domínio do diff inteiro (visão de fluxo, não de arquivo), usando o modelo de
+ * intenção (`business-summary.json`) como contrato esperado.
+ */
+
+import { defineWatchdog, type WatchdogDefinition } from "./types";
+
+/** Id reservado do revisor de lógica/domínio. */
+export const GENERAL_WATCHDOG_ID = "general";
+
+/**
+ * Revisor de fluxo: recebe todos os arquivos alterados e procura gaps de
+ * negócio (fluxo incompleto, capacidade não honrada, credencial divergente,
+ * estado sem tratamento, identificador trocado, idempotência ausente).
+ *
+ * As regras são o **piso**; findings fora delas usam `Lógica:`/`Domínio:`
+ * (`allowEmergentFindings`). Severidade `blocking` só é aceita com cenário +
+ * evidência (normalizado no `report-builder`).
+ */
+export const generalWatchdog: WatchdogDefinition = defineWatchdog({
+	id: GENERAL_WATCHDOG_ID,
+	name: "Lógica e domínio (fluxo)",
+	description:
+		"Audita o fluxo alterado ponta a ponta: intenção, invariantes, estados, capacidades e credenciais.",
+	scope: "Todos os arquivos alterados (visão de fluxo, independente de domínio)",
+	classify: [],
+	fallback: false,
+	allowEmergentFindings: true,
+	// Deletados não têm conteúdo para ler: entram como breaking change no brief.
+	breakingChange: true,
+	reviewFocus: [
+		"Reconstrua o modelo de intenção (business-summary.json) antes de julgar o código.",
+		"Rastreie cada símbolo alterado até seus chamadores, adapters e tipos compartilhados.",
+		"Verifique paridade de capacidade: feature declarada, método exposto, evento/webhook e lista de métodos.",
+		"Verifique propagação de credencial/conta/contexto em toda a cadeia (auth, token, split, subconta).",
+		"Percorra o ciclo de vida completo dos fluxos tocados: criação, renovação, cancelamento, retry e erro.",
+		"Confirme o identificador persistido contra a entidade que o contrato espera.",
+		"Só reporte gap com gatilho concreto, comportamento observado e invariante/regra violada.",
+	],
+	rules: [
+		{
+			severity: "attention",
+			text: "Promover: todo fluxo alterado tem caminho completo (criação, renovação, cancelamento) e o caminho de erro chega a um estado tratado.",
+		},
+		{
+			severity: "attention",
+			text: "Promover: toda capacidade declarada (feature, método, evento, webhook) existe e é honrada em todos os lados do contrato.",
+		},
+		{
+			severity: "attention",
+			text: "Promover: a credencial, conta e contexto de execução são os mesmos em toda a cadeia alterada (autenticação, token, split, subconta).",
+		},
+		{
+			severity: "attention",
+			text: "Promover: transições de estado e efeitos colaterais do domínio são explícitos, ordenados e idempotentes.",
+		},
+		{
+			severity: "suggestion",
+			text: "Promover: o identificador persistido corresponde à entidade que o contrato espera (cobrança, autorização, pedido, assinatura).",
+		},
+	],
+	contextFiles: [],
+});
+
+/** Watchdogs embutidos, por id. */
+export const BUILTIN_WATCHDOGS: Readonly<Record<string, WatchdogDefinition>> = {
+	[GENERAL_WATCHDOG_ID]: generalWatchdog,
+};
+
+/** Definição embutida de um id (ou null). */
+export function builtinWatchdog(id: string): WatchdogDefinition | null {
+	return BUILTIN_WATCHDOGS[id] ?? null;
+}
+
+/**
+ * Mescla a definição do consumidor com o piso embutido do `general`.
+ *
+ * O consumidor pode ajustar nome/escopo/docs/regras, mas não pode remover a
+ * auditoria de lógica nem os findings emergentes.
+ */
+export function mergeGeneralWatchdog(
+	configured: WatchdogDefinition | undefined,
+): WatchdogDefinition {
+	if (!configured || configured.id !== GENERAL_WATCHDOG_ID) return generalWatchdog;
+	const rules = [...configured.rules];
+	for (const rule of generalWatchdog.rules) {
+		if (!rules.some((item) => item.text === rule.text)) rules.push(rule);
+	}
+	return {
+		...generalWatchdog,
+		name: configured.name || generalWatchdog.name,
+		description: configured.description || generalWatchdog.description,
+		scope: configured.scope || generalWatchdog.scope,
+		reviewFocus: [
+			...(configured.reviewFocus ?? []),
+			...(generalWatchdog.reviewFocus ?? []),
+		],
+		exclude: configured.exclude,
+		contextFiles: configured.contextFiles,
+		rules,
+		allowEmergentFindings: true,
+		fallback: false,
+	};
+}