@payconductor/houndsman 0.13.0 → 0.16.0

package/src/core/paths.ts

@@ -47,12 +47,15 @@ export const CONTEXT_SUMMARY_FILE = "context-summary.json";
 /** Brief do subagente que resume o contexto da PR. */
 export const CONTEXT_BRIEF_FILE = "context-brief.md";
 
+/** Modelo de intenção da PR (negócio) — insumo obrigatório do revisor `general`. */
+export const BUSINESS_SUMMARY_FILE = "business-summary.json";
+
+/** Brief do passo de intenção (subagente na skill / pré-passe no hunt). */
+export const BUSINESS_BRIEF_FILE = "business-brief.md";
+
 /** Relatório da verificação de findings (artefato `verify.md`). */
 export const VERIFY_FILE = "verify.md";
 
-/** Relatório consolidado da review (artefato `review.md`). */
-export const REVIEW_FILE = "review.md";
-
 /** Resumo final da review (artefato `review-resume.md`) — leitura humana apenas. */
 export const REVIEW_RESUME_FILE = "review-resume.md";
 

package/src/core/pr-context.ts

@@ -203,7 +203,7 @@ export function renderContextBrief(
 
 	lines.push("## Objetivo", "");
 	lines.push(
-		"Resumir a PR para abrir o relatório de revisão em **Objetivo**,",
+		"Resumir a PR para abrir o resumo final em **Objetivo**,",
 		"**Motivação** e **Resumo das alterações** (pt-BR).",
 		"",
 	);
@@ -228,9 +228,7 @@ export function renderContextBrief(
 	lines.push("```", "");
 
 	lines.push("## Regras", "");
-	lines.push(
-		"- O resumo abre o relatório e o resumo final; nos briefs ele é recortado.",
-	);
+	lines.push("- O resumo abre o resumo final; nos briefs ele é recortado.");
 	lines.push("- Baseie-se **somente** no `context.json` — não invente intenção.");
 	lines.push(
 		"- `objective`: até 2 frases (≤ 400 caracteres) sobre o que a PR entrega.",

package/src/core/prepare-report.ts

@@ -0,0 +1,61 @@
+/**
+ * Relatório de duração do `prepare` (artefato `prepare-report.json`).
+ *
+ * O CLI já imprime cada etapa; o artefato permite comparar runs (antes/depois
+ * de tuning) sem poluir o `manifest.json`, que é determinístico nos snapshots.
+ */
+
+import type { AiUsage } from "./ai/types";
+import type { PrepareStage } from "./orchestrator";
+
+/** Duração de uma etapa do prepare. */
+export type PrepareStageTiming = {
+	stage: PrepareStage;
+	durationMs: number;
+};
+
+/** Chamada de IA que falhou (timeout, truncamento, schema inválido). */
+export type PrepareAiFailure = {
+	feature: string;
+	model: string;
+	durationMs: number;
+	error: string;
+	finishReason?: string;
+};
+
+/** Uso de IA do prepare: tokens das chamadas boas + tentativas/falhas. */
+export type PrepareAiReport = AiUsage & {
+	attempts: number;
+	failures: readonly PrepareAiFailure[];
+};
+
+/** Entrada do relatório. */
+export type PrepareReportInput = {
+	/** Início do prepare (ISO). */
+	startedAt: string;
+	durationMs: number;
+	stages: readonly PrepareStageTiming[];
+	/** Uso agregado de IA e falhas (quando configurada). */
+	ai?: PrepareAiReport;
+};
+
+/** Monta o objeto persistido. */
+export function buildPrepareReport(input: PrepareReportInput) {
+	return {
+		version: 1 as const,
+		startedAt: input.startedAt,
+		durationMs: input.durationMs,
+		stages: input.stages.map((item) => ({ ...item })),
+		ai: input.ai
+			? {
+					...input.ai,
+					failures: input.ai.failures.map((failure) => ({ ...failure })),
+				}
+			: null,
+	};
+}
+
+/** Serializa o relatório (JSON indentado + newline). */
+export function renderPrepareReport(input: PrepareReportInput): string {
+	return `${JSON.stringify(buildPrepareReport(input), null, 2)}\n`;
+}

package/src/core/project-config.ts

@@ -14,6 +14,7 @@ import type {
 	HoundsmanAst,
 	HoundsmanConfig,
 	HoundsmanHunt,
+	HoundsmanPriority,
 	HoundsmanStorage,
 	HoundsmanWorktrees,
 } from "./config";
@@ -105,6 +106,11 @@ export class ProjectConfig<TId extends string = string> {
 		return this.raw.docMappings;
 	}
 
+	/** Prioridade por caminho (vazio = churn puro, comportamento antigo). */
+	get priorities(): readonly HoundsmanPriority[] {
+		return this.raw.priorities ?? [];
+	}
+
 	/** Config de IA (objeto vazio quando ausente). */
 	get ai(): HoundsmanAi {
 		return this.raw.ai ?? {};
@@ -148,11 +154,12 @@ export class ProjectConfig<TId extends string = string> {
 		return value !== undefined && value > 0 ? value : undefined;
 	}
 
-	/** Features resolvidas com defaults (`context`/`brief`/`technical` ligadas). */
+	/** Features resolvidas com defaults (`context`/`business`/`brief`/`technical` ligadas). */
 	get aiFeatures(): Required<HoundsmanAiFeatures> {
 		const features = this.ai.features ?? {};
 		return {
 			context: features.context !== false,
+			business: features.business !== false,
 			brief: features.brief !== false,
 			technical: features.technical !== false,
 			classification: features.classification === true,
@@ -200,6 +207,16 @@ export class ProjectConfig<TId extends string = string> {
 		const value = this.hunt.model?.trim();
 		return value && value.length > 0 ? value : this.aiModel;
 	}
+
+	/** Passada de checklist do harness (default: ligada). */
+	get huntChecklist(): boolean {
+		return this.hunt.checklist !== false;
+	}
+
+	/** Passada adversarial do `general` (default: ligada). */
+	get huntSecondOpinion(): boolean {
+		return this.hunt.secondOpinion !== false;
+	}
 }
 
 /** Inteiro positivo ou o default. */

package/src/core/propagation.ts

@@ -0,0 +1,127 @@
+/**
+ * Propagação mecânica — detecção determinística de mudanças em massa.
+ *
+ * Cenário típico: um contrato ganha um parâmetro obrigatório e N arquivos
+ * adicionam a mesma linha. Revisar N diffs de uma linha é desperdício; o risco
+ * está no padrão (um representante) e nos outliers (quem fugiu do padrão).
+ *
+ * Tudo aqui é função pura sobre dados já coletados no prepare (patch `-U0`,
+ * churn, delta/impacto do AST) — não há leitura extra de git nem chamada de IA.
+ */
+
+import type { AstAnalysis, AstImpact } from "./ast/types";
+import { churnOf } from "./domain/budget";
+import type { ChurnMap, PropagationCluster, PropagationGap } from "./types";
+
+/** Acima disso o arquivo não é "micro-alteração". */
+export const PROPAGATION_MAX_CHURN = 3;
+
+/** Mínimo de arquivos com o mesmo padrão para virar cluster. */
+export const PROPAGATION_MIN_FILES = 5;
+
+/** Teto de arquivos examinados (proteção para PRs gigantes). */
+export const PROPAGATION_MAX_FILES = 500;
+
+/** Outliers listados no brief (os demais são contados). */
+export const PROPAGATION_MAX_OUTLIERS = 8;
+
+/** Importadores listados por contrato no brief. */
+export const PROPAGATION_MAX_IMPORTERS = 10;
+
+/** Linhas adicionadas do patch (sem cabeçalho), normalizadas. */
+export function addedLines(patch: string | undefined): string[] {
+	if (!patch) return [];
+	const lines: string[] = [];
+	for (const raw of patch.split(/\r?\n/)) {
+		if (!raw.startsWith("+") || raw.startsWith("+++")) continue;
+		const normalized = raw.slice(1).trim().replace(/\s+/g, " ");
+		if (normalized.length > 0) lines.push(normalized);
+	}
+	return lines;
+}
+
+/**
+ * Detecta o padrão dominante entre micro-alterações.
+ *
+ * Agrupa por linha adicionada **exata** (só normaliza espaços): agrupar por
+ * identificador esconderia justamente o outlier que precisa de revisão. Sem
+ * grupo dominante, devolve `null` e o brief segue como antes.
+ */
+export function detectPropagation(
+	files: readonly string[],
+	patch: ReadonlyMap<string, string> | undefined,
+	churn?: ChurnMap,
+): PropagationCluster | null {
+	if (!patch) return null;
+	const micro: { file: string; lines: string[] }[] = [];
+	for (const file of files.slice(0, PROPAGATION_MAX_FILES)) {
+		if (churnOf(file, churn) > PROPAGATION_MAX_CHURN) continue;
+		const lines = addedLines(patch.get(file));
+		if (lines.length === 0) continue;
+		micro.push({ file, lines });
+	}
+	if (micro.length < PROPAGATION_MIN_FILES) return null;
+
+	const groups = new Map<string, { file: string; lines: string[] }[]>();
+	for (const entry of micro) {
+		const key = entry.lines.join("\n");
+		const list = groups.get(key);
+		if (list) list.push(entry);
+		else groups.set(key, [entry]);
+	}
+	const [patternKey, members] =
+		[...groups.entries()].sort(
+			(a, b) => b[1].length - a[1].length || a[0].localeCompare(b[0]),
+		)[0] ?? [];
+	if (!members || members.length < PROPAGATION_MIN_FILES) return null;
+
+	const dominant = new Set(members.map((entry) => entry.file));
+	const outliers = micro
+		.filter((entry) => !dominant.has(entry.file))
+		.slice(0, PROPAGATION_MAX_OUTLIERS);
+	return {
+		lines: (patternKey ?? "").split("\n"),
+		files: members.map((entry) => entry.file),
+		outliers,
+	};
+}
+
+/** `true` quando o delta mexeu em um contrato exportado (assinatura/export). */
+function changesExportedContract(analysis: AstAnalysis | undefined): boolean {
+	const delta = analysis?.delta;
+	if (!delta) return false;
+	if (delta.changedExports.length > 0) return true;
+	if (delta.changedSignatures.some((change) => change.exported)) return true;
+	return delta.modifiedSymbols.some(
+		(symbol) =>
+			symbol.exported &&
+			(symbol.kind === "interface" ||
+				symbol.kind === "type" ||
+				symbol.kind === "enum" ||
+				symbol.kind === "class"),
+	);
+}
+
+/**
+ * Contratos alterados com importadores que **não** aparecem no diff.
+ *
+ * É o cheque de "atualizaram 100 e esqueceram 3": o impacto reverso do AST já
+ * lista quem importa o arquivo; quem não está no diff vira suspeito no brief.
+ */
+export function detectPropagationGaps(
+	files: readonly string[],
+	ast: ReadonlyMap<string, AstAnalysis> | undefined,
+	impact: AstImpact | undefined,
+	changedFiles: ReadonlySet<string>,
+): PropagationGap[] {
+	if (!ast || !impact) return [];
+	const gaps: PropagationGap[] = [];
+	for (const file of files) {
+		if (!changesExportedContract(ast.get(file))) continue;
+		const importers = [...new Set(impact.importers[file] ?? [])]
+			.filter((importer) => !changedFiles.has(importer))
+			.slice(0, PROPAGATION_MAX_IMPORTERS);
+		if (importers.length > 0) gaps.push({ file, importers });
+	}
+	return gaps;
+}

package/src/core/registry-check.ts

@@ -5,12 +5,15 @@
  * `HoundsmanConfig` — não há caminhos de arquivo do projeto na config.
  */
 
+import { GENERAL_WATCHDOG_ID } from "./builtins";
 import type { HoundsmanConfig } from "./config";
 import { env } from "./env";
 import { JevQuestionFactory } from "./jev";
-import { renderReport, sanitizeBranch } from "./report-builder";
+import { renderReviewResume } from "./renderers/resume-renderer";
+import { sanitizeBranch } from "./report-builder";
 import { hasExplicitPolarity } from "./rule-text";
-import type { WatchdogMeta } from "./types";
+import { normalizeRuleText } from "./severity";
+import type { Severity, WatchdogMeta } from "./types";
 
 /** `id` da definição bate com a chave; `description` não vazio. */
 function checkDefinitions(config: HoundsmanConfig, problems: string[]): void {
@@ -63,6 +66,15 @@ function checkFallbacks(config: HoundsmanConfig, warnings: string[]): void {
 	}
 }
 
+/** O id `general` é reservado: o motor sempre injeta o revisor de fluxo. */
+function checkReservedIds(config: HoundsmanConfig, warnings: string[]): void {
+	if (config.watchdogIds.includes(GENERAL_WATCHDOG_ID)) {
+		warnings.push(
+			`watchdogs['${GENERAL_WATCHDOG_ID}'] usa um id reservado — os metadados são mesclados ao piso de lógica do motor.`,
+		);
+	}
+}
+
 /** Findings emergentes exigem ao menos uma regra de lógica/domínio como piso. */
 function checkEmergent(config: HoundsmanConfig, warnings: string[]): void {
 	for (const id of config.watchdogIds) {
@@ -79,35 +91,61 @@ function checkEmergent(config: HoundsmanConfig, warnings: string[]): void {
 	}
 }
 
+/**
+ * Prioridades por caminho: RegExp, valores finitos (`bonus` ≥ 0, teto > 0) e ao
+ * menos um efeito — uma regra sem `bonus` nem `maxRiskFromChurn` é inócua.
+ */
+function checkPriorities(config: HoundsmanConfig, problems: string[]): void {
+	for (const [index, rule] of (config.priorities ?? []).entries()) {
+		if (!(rule.pattern instanceof RegExp)) {
+			problems.push(`priorities[${index}].pattern precisa ser uma RegExp`);
+		}
+		if (
+			rule.bonus !== undefined &&
+			(!Number.isFinite(rule.bonus) || rule.bonus < 0)
+		) {
+			problems.push(`priorities[${index}].bonus precisa ser número ≥ 0`);
+		}
+		if (
+			rule.maxRiskFromChurn !== undefined &&
+			(!Number.isFinite(rule.maxRiskFromChurn) || rule.maxRiskFromChurn <= 0)
+		) {
+			problems.push(`priorities[${index}].maxRiskFromChurn precisa ser número > 0`);
+		}
+		if (rule.bonus === undefined && rule.maxRiskFromChurn === undefined) {
+			problems.push(
+				`priorities[${index}] não tem bonus nem maxRiskFromChurn (regra inócua)`,
+			);
+		}
+	}
+}
+
 /** Smoke test dos helpers críticos de renderização. */
-function checkRendering(config: HoundsmanConfig, problems: string[]): void {
+function checkRendering(problems: string[]): void {
 	if (sanitizeBranch("feature/x") !== "feature-x") {
 		problems.push("sanitizeBranch não está normalizando branches");
 	}
-	const sampleId = config.watchdogIds[0] ?? "watchdog";
-	const report = {
-		watchdogId: sampleId,
-		reviewedFiles: [],
-		skipped: [],
+	const base = { branch: "main", date: "2026-01-01" } as const;
+	const empty = renderReviewResume({
+		...base,
+		classification: { files: {}, watchdogs: {} },
 		findings: [],
-	};
-	const md = renderReport("main", [report], [], {});
-	if (!md.includes("✅ Aprovado")) {
-		problems.push("renderReport não marcou status aprovado sem achados");
+	});
+	if (!empty.includes("✅ Aprovado")) {
+		problems.push("renderReviewResume não marcou status aprovado sem achados");
 	}
-	const withContext = renderReport(
-		"main",
-		[report],
-		[],
-		{},
-		{
+	const withContext = renderReviewResume({
+		...base,
+		classification: { files: {}, watchdogs: {} },
+		findings: [],
+		context: {
 			available: true,
 			objective: "Entregar X",
 			changeSummary: ["Faz A"],
 		},
-	);
-	if (!withContext.includes("## Contexto da PR")) {
-		problems.push("renderReport não incluiu a seção de contexto");
+	});
+	if (!withContext.includes("Entregar X")) {
+		problems.push("renderReviewResume não incluiu o contexto da PR");
 	}
 }
 
@@ -165,11 +203,6 @@ function checkRulePolarity(config: HoundsmanConfig, warnings: string[]): void {
 	}
 }
 
-/** Normaliza o texto da regra para detectar duplicatas (case/espaços). */
-function normalizeRuleText(text: string): string {
-	return text.trim().toLowerCase().replace(/\s+/g, " ");
-}
-
 /**
  * Aviso para regra repetida (texto normalizado) no mesmo watchdog — a regra deve
  * existir uma única vez em `rules` (§ Convenções de escrita, item 10).
@@ -191,6 +224,33 @@ function checkRuleDuplication(config: HoundsmanConfig, warnings: string[]): void
 	}
 }
 
+/**
+ * Aviso quando o mesmo texto de regra aparece em watchdogs diferentes com
+ * severidades diferentes: a ancoragem usaria a mais grave e o resultado
+ * dependeria de qual watchdog reportou.
+ */
+function checkRuleSeverityConflicts(config: HoundsmanConfig, warnings: string[]): void {
+	const byText = new Map<string, { id: string; severity: Severity }[]>();
+	for (const id of config.watchdogIds) {
+		const def = config.watchdogs[id];
+		if (!def) continue;
+		for (const rule of def.rules) {
+			const key = normalizeRuleText(rule.text);
+			if (!key) continue;
+			const entries = byText.get(key) ?? [];
+			entries.push({ id, severity: rule.severity });
+			byText.set(key, entries);
+		}
+	}
+	for (const entries of byText.values()) {
+		if (entries.length < 2) continue;
+		const severities = new Set(entries.map((entry) => entry.severity));
+		if (severities.size < 2) continue;
+		const detail = entries.map((entry) => `${entry.id}=${entry.severity}`).join(", ");
+		warnings.push(`Regra com severidades divergentes entre watchdogs: ${detail}.`);
+	}
+}
+
 /** Campos de metadados que NÃO devem conter texto de regra. */
 const RULE_BEARING_FIELDS = ["reviewFocus", "contextFiles", "exclude"] as const;
 
@@ -331,12 +391,15 @@ export function checkRegistry(config: HoundsmanConfig): {
 	checkDefinitions(config, problems);
 	checkClassification(config, problems);
 	checkFallbacks(config, warnings);
+	checkReservedIds(config, warnings);
 	checkEmergent(config, warnings);
-	checkRendering(config, problems);
+	checkRendering(problems);
 	checkRulePolarity(config, warnings);
 	checkRuleDuplication(config, warnings);
+	checkRuleSeverityConflicts(config, warnings);
 	checkMetadataPrecision(config, warnings);
 	checkBudgets(config, warnings);
+	checkPriorities(config, problems);
 	checkAstConfig(config, problems, warnings);
 	checkAiConfig(config, problems, warnings);
 	const jevQuestions = checkJevSpecs(config, problems);

package/src/core/renderers/manifest-writer.ts

@@ -7,6 +7,7 @@
  */
 
 import type { AiUsage } from "../ai/types";
+import type { BusinessSummary } from "../business-summary";
 import { Classification } from "../domain/classification";
 import type { ClassificationResult } from "../file-classifier";
 import type { JevCandidatesFile } from "../jev";
@@ -44,6 +45,16 @@ export type ManifestAi = {
 	usage: AiUsage;
 };
 
+/** Resumo do modelo de intenção no manifesto. */
+export type ManifestBusiness = {
+	source: BusinessSummary["source"];
+	model?: string;
+	flows: number;
+	invariants: number;
+	contracts: number;
+	states: number;
+};
+
 /** Classificação enriquecida gravada pelo prepare (modo + incremental). */
 export type ManifestClassification = ClassificationResult & {
 	headSha?: string;
@@ -81,6 +92,7 @@ export class ManifestWriter {
 		jev: JevCandidatesFile,
 		ast?: ManifestAst,
 		ai?: ManifestAi,
+		business?: ManifestBusiness,
 	): void {
 		const view = Classification.from(classification);
 		const maxFilesPerBrief = this.project.maxFilesPerBrief;
@@ -125,6 +137,7 @@ export class ManifestWriter {
 			context: summary
 				? { summarized: true, source: summary.source ?? null }
 				: { summarized: false, source: null },
+			business: business ?? null,
 			jev: jev.available
 				? {
 						available: true,