@payconductor/houndsman 0.13.0 → 0.16.0

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,63 @@ 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).
+ *
+ * O teto mínimo é o piso, não o valor fixo: um domínio com 37 arquivos não se
+ * revisa com 10 leituras (o `general` pulava 12 de 37 e perdia o rastreio de
+ * contrato). O tamanho do domínio define quantas leituras o brief concede.
+ */
+const EXPLORATION_BUDGET = {
+	general: { reads: 10, searches: 12, maxReads: 24, filesPerRead: 2 },
+	domain: { reads: 6, searches: 6, maxReads: 14, filesPerRead: 2 },
+} as const;
+
+/** Teto de leituras para o domínio (cresce com o nº de arquivos, até o máximo). */
+function readsFor(
+	budget: (typeof EXPLORATION_BUDGET)[keyof typeof EXPLORATION_BUDGET],
+	files: number,
+): number {
+	const needed = Math.ceil(files / budget.filesPerRead);
+	return Math.min(budget.maxReads, Math.max(budget.reads, needed));
+}
+
+/** 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;
+	const reads = readsFor(budget, args.files.length);
+	return [
+		"## Orçamento de exploração",
+		"",
+		`> O diff já está no brief. Limite **neste brief**: ${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,
@@ -135,11 +185,24 @@ function codeItem(value: string): string {
 	return `- \`${value}\``;
 }
 
-/** Linha de regra com emoji de severidade. */
-function ruleItem(rule: Rule): string {
-	return `- ${SEVERITY_EMOJI[rule.severity]} **${rule.severity}** — ${rule.text}`;
+/** Linha de regra com número e emoji de severidade (o número é a identidade no checklist). */
+function ruleItem(rule: Rule, index: number): string {
+	return `- ${index}. ${SEVERITY_EMOJI[rule.severity]} **${rule.severity}** — ${rule.text}`;
 }
 
+/**
+ * Contrato de severidade do output — a severidade é derivada, não escolhida.
+ *
+ * Finding de regra carrega a severidade declarada em `Rule.severity`; emergente
+ * carrega `impactClass`, mapeado em `core/severity.ts`. Isso impede o mesmo
+ * código de sair `blocking` numa review e `attention` na seguinte.
+ */
+export const SEVERITY_GUIDE: readonly string[] = [
+	"- **Finding de regra:** copie `rule` exatamente como no brief. A severidade é a **declarada na regra** — outro valor é ignorado e corrigido pelo motor.",
+	"- **Finding emergente** (`Lógica:`/`Domínio:`): preencha `impactClass` — `flow-break` (fluxo/capacidade não honrada), `contract-drift` (contrato/estado divergente), `degradation` (borda/erro frágil) ou `cosmetic`.",
+	"- `blocking` fora de regra continua exigindo `scenario` + `evidence`; sem os dois, o motor rebaixa para `attention`.",
+];
+
 /** Seção opcional (`## <título>` + itens) — vazia se não houver itens. */
 function optionalList(title: string, items: readonly string[] | undefined): string[] {
 	if (!items || items.length === 0) return [];
@@ -157,18 +220,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 +290,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 +471,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 +601,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));
@@ -354,9 +614,10 @@ export function defaultRenderBrief(
 		"",
 		...[...def.rules]
 			.sort((a, b) => severityRank(a.severity) - severityRank(b.severity))
-			.map(ruleItem),
+			.map((rule, index) => ruleItem(rule, index + 1)),
 		"",
 	);
+	lines.push("## Como declarar a severidade", "", ...SEVERITY_GUIDE, "");
 	lines.push(
 		"## Docs de contexto (carregar sob demanda)",
 		"",
@@ -378,6 +639,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,
+	};
+}