@payconductor/houndsman 0.14.0 → 0.16.0

package/src/core/hunt/hunt-runner.ts

@@ -8,13 +8,21 @@
  */
 
 import { readFileSync } from "node:fs";
+import { join } from "node:path";
 import { GENERAL_WATCHDOG_ID } from "../builtins";
 import { type BusinessSummary, parseBusinessSummary } from "../business-summary";
-import { parseWatchdogReport } from "../report-builder";
+import { parseWatchdogReport, type WatchdogReport } from "../report-builder";
 import { systemClock } from "../services/clock";
 import type { ReviewWorkArea } from "../storage/work-area";
 import { renderHuntIntentPrompt, renderIntentRetrySuffix } from "./maki-intent-prompt";
-import { renderHuntPrompt, renderRetrySuffix } from "./maki-prompt";
+import {
+	renderAdversarialPrompt,
+	renderBookkeepingPrompt,
+	renderChecklistSuffix,
+	renderHuntPrompt,
+	renderResumeSuffix,
+	renderRetrySuffix,
+} from "./maki-prompt";
 import {
 	extractJsonObject,
 	type MakiProcessRunner,
@@ -22,7 +30,28 @@ import {
 	type MakiUsage,
 } from "./maki-runner";
 import { mapPool } from "./pool";
-
+import {
+	type AtResolver,
+	briefDomainFiles,
+	briefRules,
+	businessScore,
+	type CheckCoverage,
+	chooseBusinessSummary,
+	expectedReviewItems,
+	mergeChecks,
+	mergeFindings,
+	mergeRuleChecks,
+	missingReviewItems,
+	missingRuleChecks,
+	normalizePath,
+	parseReviewChecks,
+	parseRuleChecks,
+	type ReviewCheck,
+	type RuleCheck,
+	summarizeChecks,
+	summarizeRuleChecks,
+	withInferredRule,
+} from "./review-checks";
 /** Evento de progresso (CLI loga; core não escreve saída). */
 export type HuntEvent =
 	| {
@@ -31,6 +60,21 @@ export type HuntEvent =
 			source?: BusinessSummary["source"];
 			error?: string;
 	  }
+	| {
+			type: "checklist";
+			watchdogId: string;
+			missing: number;
+			missingRules: number;
+			status: "start" | "done" | "failed";
+			error?: string;
+	  }
+	| {
+			type: "second-opinion";
+			watchdogId: string;
+			status: "start" | "done" | "failed";
+			findings?: number;
+			error?: string;
+	  }
 	| { type: "start"; watchdogId: string }
 	| {
 			type: "retry";
@@ -68,6 +112,39 @@ export type HuntWatchdogResult = {
 	costUsd?: number;
 	usage?: MakiUsage;
 	error?: string;
+	/** Cobertura do checklist de intenção (fluxos + invariantes). */
+	checks?: CheckCoverage;
+	/** Cobertura das regras declaradas no brief (numeradas). */
+	rules?: CheckCoverage;
+	/** Passada de checklist (custo marginal explícito). */
+	checklist?: {
+		status: "done" | "failed";
+		missing: number;
+		missingRules: number;
+		costUsd: number;
+		numTurns: number;
+	};
+	/** Resultado da passada adversarial do `general` (com custo marginal). */
+	secondOpinion?: {
+		status: "done" | "failed";
+		findings: number;
+		costUsd: number;
+		numTurns: number;
+		error?: string;
+	};
+	/** Cobertura declarada dos arquivos do domínio (`reviewedFiles` ∪ `skipped`). */
+	coverage?: {
+		total: number;
+		reviewed: number;
+		skipped: number;
+		undeclared: number;
+	};
+	/** Decisão sobre o modelo de intenção devolvido pelo `general`. */
+	business?: {
+		accepted: boolean;
+		source: BusinessSummary["source"];
+		score: number;
+	};
 };
 
 /** Agregados do relatório. */
@@ -89,6 +166,8 @@ export type HuntReport = {
 	model: string;
 	/** Fonte do modelo de intenção usado na revisão. */
 	business?: BusinessSummary["source"];
+	/** Pontuação do modelo de intenção efetivo (fluxos/invariantes/contratos). */
+	businessScore?: number;
 	startedAt: string;
 	finishedAt: string;
 	durationMs: number;
@@ -110,6 +189,16 @@ export type HuntRunnerOptions = {
 	concurrency: number;
 	timeoutMs: number;
 	retries: number;
+	/**
+	 * Passada extra por watchdog quando o checklist de intenção não foi coberto
+	 * (default: ligada). Desligue com `hunt.checklist: false`.
+	 */
+	checklist?: boolean;
+	/**
+	 * Passada adversarial do `general` (5 classes: credencial/estado, capacidade,
+	 * identificador, idempotência, contrato). Default: ligada.
+	 */
+	secondOpinion?: boolean;
 	runner: MakiProcessRunner;
 	onEvent?: (event: HuntEvent) => void;
 };
@@ -127,16 +216,21 @@ export class HuntRunner {
 		const startedMs = Date.now();
 		// Intenção primeiro: o revisor `general` e os demais watchdogs leem o
 		// mesmo `business-summary.json` do staging.
-		const business = await this.runIntent();
+		const businessSource = await this.runIntent();
+		// Snapshot único: o `general` pode devolver outro modelo no meio da onda;
+		// os demais watchdogs precisam do mesmo contrato do brief que receberam.
+		const businessModel = this.options.work.readBusinessSummary();
 		const watchdogs = await mapPool(activeIds, this.options.concurrency, (id) =>
-			this.runOne(id),
+			this.runOne(id, businessModel),
 		);
 		const finishedAt = systemClock();
+		const effective = this.options.work.readBusinessSummary();
 		return {
 			version: 1,
 			engine: "maki",
 			model: this.options.model,
-			business,
+			business: effective?.source ?? businessSource,
+			businessScore: effective ? businessScore(effective) : undefined,
 			startedAt,
 			finishedAt,
 			durationMs: Date.now() - startedMs,
@@ -199,7 +293,25 @@ export class HuntRunner {
 				lastError = "JSON fora do schema do modelo de intenção.";
 				continue;
 			}
-			this.options.work.writeBusinessSummary(summary);
+			// Modelo sem fluxo nem invariante não sustenta a revisão por
+			// invariantes: repete em vez de degradar os briefs.
+			if (
+				summary.flows.length === 0 &&
+				summary.invariants.length + summary.contracts.length < 2
+			) {
+				lastError =
+					"modelo de intenção sem fluxos e com menos de 2 invariantes/contratos.";
+				continue;
+			}
+			const decision = chooseBusinessSummary(
+				this.options.work.readBusinessSummary(),
+				summary,
+			);
+			if (!decision.accepted || !decision.summary) {
+				lastError = "modelo de intenção inferior ao já disponível.";
+				continue;
+			}
+			this.options.work.writeBusinessSummary(decision.summary);
 			this.emit({ type: "intent", status: "done", source: "reviewer" });
 			return "reviewer";
 		}
@@ -208,7 +320,10 @@ export class HuntRunner {
 		return existing?.source ?? "deterministic";
 	}
 
-	private async runOne(watchdogId: string): Promise<HuntWatchdogResult> {
+	private async runOne(
+		watchdogId: string,
+		business: BusinessSummary | null,
+	): Promise<HuntWatchdogResult> {
 		const briefPath = this.options.work.briefFile(watchdogId);
 		let brief: string;
 		try {
@@ -225,35 +340,305 @@ export class HuntRunner {
 			return failedResult(watchdogId, error, 0, { durationMs: 0 });
 		}
 
+		// Revisor de fluxo: a passada base NÃO faz bookkeeping. Ele carrega 37
+		// arquivos e um brief de ~60 KB; competir com `checks`/`rules` no mesmo JSON
+		// é o que fazia o `general` devolver 2 achados e 10/10 checks sem lastro.
+		const isGeneral = watchdogId === GENERAL_WATCHDOG_ID;
+		const requestBusiness = isGeneral && business?.source !== "ai";
 		const basePrompt = renderHuntPrompt({
 			projectName: this.options.projectName,
 			watchdogId,
 			brief,
+			bookkeeping: !isGeneral,
+			requestBusiness,
 		});
+		// Checklist derivado do brief: cada fluxo/invariante do modelo de intenção
+		// e cada regra numerada precisa de uma verificação declarada.
+		const expected = expectedReviewItems(brief, business, watchdogId);
+		const expectedRules = briefRules(brief);
+		// `at` só conta como prova quando aponta para arquivo/linha existentes.
+		const resolveAt = makeAtResolver(this.options.root);
 
 		this.emit({ type: "start", watchdogId });
 		let attempts = 0;
-		let lastError = "";
 		const accumulated: MakiRunMetrics = { durationMs: 0 };
 
+		const first = await this.executePass(watchdogId, basePrompt);
+		mergeMetrics(accumulated, first.metrics);
+		attempts += first.attempts;
+		if (!first.ok) {
+			this.emit({
+				type: "failed",
+				watchdogId,
+				error: first.error,
+				attempts,
+				metrics: accumulated,
+			});
+			return failedResult(watchdogId, first.error, attempts, accumulated);
+		}
+
+		let report = first.report;
+		let checks = first.checks;
+		let ruleChecks = first.ruleChecks;
+		let reviewerBusiness = first.reviewerBusiness;
+
+		let checklist: HuntWatchdogResult["checklist"];
+		if (isGeneral && this.options.checklist !== false) {
+			// Bookkeeping do revisor de fluxo: sessão nova, tarefa estreita e
+			// barata (só vereditos com `at` comprovado).
+			const costBefore = accumulated.costUsd ?? 0;
+			const turnsBefore = accumulated.numTurns ?? 0;
+			this.emit({
+				type: "checklist",
+				watchdogId,
+				missing: expected.length,
+				missingRules: expectedRules.length,
+				status: "start",
+			});
+			const verdicts = await this.executePass(
+				watchdogId,
+				renderBookkeepingPrompt({
+					projectName: this.options.projectName,
+					watchdogId,
+					brief,
+					items: expected,
+					ruleIds: expectedRules.map((rule) => rule.id),
+				}),
+			);
+			mergeMetrics(accumulated, verdicts.metrics);
+			attempts += verdicts.attempts;
+			if (verdicts.ok) {
+				// Só vereditos: achados desta passada seriam ruído de uma tarefa
+				// que não foi pedida (o prompt manda `findings: []`).
+				checks = mergeChecks(checks, verdicts.checks);
+				ruleChecks = mergeRuleChecks(ruleChecks, verdicts.ruleChecks);
+			}
+			checklist = {
+				status: verdicts.ok ? "done" : "failed",
+				missing: missingReviewItems(expected, checks).length,
+				missingRules: missingRuleChecks(expectedRules, ruleChecks).length,
+				costUsd: (accumulated.costUsd ?? 0) - costBefore,
+				numTurns: (accumulated.numTurns ?? 0) - turnsBefore,
+			};
+			this.emit({
+				type: "checklist",
+				watchdogId,
+				missing: checklist.missing,
+				missingRules: checklist.missingRules,
+				status: verdicts.ok ? "done" : "failed",
+				error: verdicts.ok ? undefined : verdicts.error,
+			});
+		}
+
+		const missing = missingReviewItems(expected, checks);
+		const missingRules = missingRuleChecks(expectedRules, ruleChecks);
+		if (
+			!isGeneral &&
+			this.options.checklist !== false &&
+			(missing.length > 0 || missingRules.length > 0)
+		) {
+			const costBefore = accumulated.costUsd ?? 0;
+			const turnsBefore = accumulated.numTurns ?? 0;
+			this.emit({
+				type: "checklist",
+				watchdogId,
+				missing: missing.length,
+				missingRules: missingRules.length,
+				status: "start",
+			});
+			const suffix = renderChecklistSuffix(missing, missingRules);
+			// Sessão já tem o brief e as evidências: só pedimos os vereditos.
+			const second = accumulated.sessionId
+				? await this.executePass(watchdogId, suffix, {
+						resume: accumulated.sessionId,
+					})
+				: await this.executePass(watchdogId, `${basePrompt}\n${suffix}`);
+			mergeMetrics(accumulated, second.metrics);
+			attempts += second.attempts;
+			if (second.ok) {
+				// A segunda passada não pode *perder* achados: une as duas.
+				report = mergeReport(report, second.report);
+				checks = mergeChecks(checks, second.checks);
+				ruleChecks = mergeRuleChecks(ruleChecks, second.ruleChecks);
+				reviewerBusiness = richerBusiness(
+					reviewerBusiness,
+					second.reviewerBusiness,
+				);
+				this.emit({
+					type: "checklist",
+					watchdogId,
+					missing: missingReviewItems(expected, checks).length,
+					missingRules: missingRuleChecks(expectedRules, ruleChecks).length,
+					status: "done",
+				});
+			} else {
+				this.emit({
+					type: "checklist",
+					watchdogId,
+					missing: missing.length,
+					missingRules: missingRules.length,
+					status: "failed",
+					error: second.error,
+				});
+			}
+			checklist = {
+				status: second.ok ? "done" : "failed",
+				missing: second.ok
+					? missingReviewItems(expected, checks).length
+					: missing.length,
+				missingRules: second.ok
+					? missingRuleChecks(expectedRules, ruleChecks).length
+					: missingRules.length,
+				costUsd: (accumulated.costUsd ?? 0) - costBefore,
+				numTurns: (accumulated.numTurns ?? 0) - turnsBefore,
+			};
+		}
+
+		let secondOpinion: HuntWatchdogResult["secondOpinion"];
+		if (this.options.secondOpinion !== false && isGeneral) {
+			const costBefore = accumulated.costUsd ?? 0;
+			const turnsBefore = accumulated.numTurns ?? 0;
+			this.emit({ type: "second-opinion", watchdogId, status: "start" });
+			// Sessão NOVA de propósito: retomar a sessão depois do checklist
+			// ancorava o modelo nas próprias conclusões (devolvia zero achados).
+			const opinion = await this.executePass(
+				watchdogId,
+				renderAdversarialPrompt({
+					projectName: this.options.projectName,
+					watchdogId,
+					brief,
+					candidates: report.findings.map((finding) => ({
+						rule: finding.rule,
+						severity: finding.severity,
+						file: finding.file,
+						line: finding.line,
+						message: finding.message,
+					})),
+				}),
+			);
+			mergeMetrics(accumulated, opinion.metrics);
+			attempts += opinion.attempts;
+			const costUsd = (accumulated.costUsd ?? 0) - costBefore;
+			const numTurns = (accumulated.numTurns ?? 0) - turnsBefore;
+			if (opinion.ok) {
+				const before = report.findings.length;
+				report = mergeReport(report, opinion.report);
+				checks = mergeChecks(checks, opinion.checks);
+				ruleChecks = mergeRuleChecks(ruleChecks, opinion.ruleChecks);
+				reviewerBusiness = richerBusiness(
+					reviewerBusiness,
+					opinion.reviewerBusiness,
+				);
+				secondOpinion = {
+					status: "done",
+					findings: report.findings.length - before,
+					costUsd,
+					numTurns,
+				};
+				this.emit({
+					type: "second-opinion",
+					watchdogId,
+					status: "done",
+					findings: secondOpinion.findings,
+				});
+			} else {
+				secondOpinion = {
+					status: "failed",
+					findings: 0,
+					costUsd,
+					numTurns,
+					error: opinion.error,
+				};
+				this.emit({
+					type: "second-opinion",
+					watchdogId,
+					status: "failed",
+					error: opinion.error,
+				});
+			}
+		}
+
+		const businessDecision = this.applyReviewerBusiness(watchdogId, reviewerBusiness);
+
+		// `rule` vazio quebra a identidade do finding na triagem; infere pelo
+		// prefixo do `basis` + primeira frase da mensagem.
+		report = withInferredRule(report);
+		this.options.work.writeFinding(
+			watchdogId,
+			`${JSON.stringify({ ...report, rules: ruleChecks, checks }, null, 2)}\n`,
+		);
+		const coverage = summarizeChecks(expected, checks, resolveAt);
+		const rulesCoverage = summarizeRuleChecks(expectedRules, ruleChecks, resolveAt);
+		const files = coverageOf(brief, report);
+		const done: HuntWatchdogResult = {
+			watchdogId,
+			status: "done",
+			findings: report.findings.length,
+			reviewedFiles: report.reviewedFiles.length,
+			attempts,
+			durationMs: accumulated.durationMs,
+			sessionId: accumulated.sessionId,
+			numTurns: accumulated.numTurns,
+			costUsd: accumulated.costUsd,
+			usage: accumulated.usage,
+			checks: coverage.expected > 0 ? coverage : undefined,
+			rules: rulesCoverage.expected > 0 ? rulesCoverage : undefined,
+			checklist,
+			secondOpinion,
+			coverage: files.total > 0 ? files : undefined,
+			business: businessDecision,
+		};
+		this.emit({
+			type: "done",
+			watchdogId,
+			findings: done.findings,
+			reviewedFiles: done.reviewedFiles,
+			attempts,
+			metrics: accumulated,
+		});
+		return done;
+	}
+
+	/** Uma passada do brief, com as retentativas de saída inválida. */
+	private async executePass(
+		watchdogId: string,
+		basePrompt: string,
+		options: { resume?: string } = {},
+	): Promise<PassOutcome> {
+		let attempts = 0;
+		let lastError = "";
+		/** A última tentativa chegou a produzir resposta? (permite retomar a sessão) */
+		let canResume = false;
+		const metrics: MakiRunMetrics = { durationMs: 0 };
+
 		while (attempts <= this.options.retries) {
 			attempts++;
+			const resume =
+				attempts === 1
+					? options.resume
+					: canResume
+						? metrics.sessionId
+						: undefined;
 			const prompt =
 				attempts === 1
 					? basePrompt
-					: `${basePrompt}\n${renderRetrySuffix(lastError)}`;
+					: resume
+						? renderResumeSuffix(lastError, watchdogId)
+						: `${basePrompt}\n${renderRetrySuffix(lastError)}`;
 			const result = await this.options.runner.run({
 				prompt,
 				cwd: this.options.root,
 				model: this.options.model,
 				apiKeyEnv: this.options.apiKeyEnv,
 				apiKey: this.options.apiKey,
+				resume,
 				timeoutMs: this.options.timeoutMs,
 			});
-			mergeMetrics(accumulated, result.metrics);
+			mergeMetrics(metrics, result.metrics);
 
 			if (!result.ok) {
 				lastError = result.error;
+				canResume = false;
 				this.emitRetry(watchdogId, attempts, lastError);
 				continue;
 			}
@@ -261,6 +646,7 @@ export class HuntRunner {
 			const raw = extractJsonObject(result.text);
 			if (raw === null) {
 				lastError = "a resposta final não contém um objeto JSON.";
+				canResume = true;
 				this.emitRetry(watchdogId, attempts, lastError);
 				continue;
 			}
@@ -271,57 +657,62 @@ export class HuntRunner {
 			);
 			if (!report) {
 				lastError = warnings[0] ?? "JSON fora do schema do watchdog.";
+				canResume = true;
 				this.emitRetry(watchdogId, attempts, lastError);
 				continue;
 			}
 			if (report.watchdogId !== watchdogId) {
 				lastError = `watchdogId '${report.watchdogId}' não corresponde a '${watchdogId}'.`;
+				canResume = true;
 				this.emitRetry(watchdogId, attempts, lastError);
 				continue;
 			}
 
-			// O revisor de fluxo devolve o modelo de intenção no JSON (maki não escreve).
-			if (watchdogId === GENERAL_WATCHDOG_ID) {
-				const summary = (raw as Record<string, unknown>).businessSummary;
-				if (typeof summary === "object" && summary !== null) {
-					const parsed = parseBusinessSummary(
-						{ ...(summary as Record<string, unknown>), source: "reviewer" },
-						"reviewer",
-					);
-					if (parsed) this.options.work.writeBusinessSummary(parsed);
-				}
-			}
-
-			this.options.work.writeFinding(
-				watchdogId,
-				`${JSON.stringify(report, null, 2)}\n`,
-			);
-			const done: HuntWatchdogResult = {
-				watchdogId,
-				status: "done",
-				findings: report.findings.length,
-				reviewedFiles: report.reviewedFiles.length,
+			return {
+				ok: true,
+				report,
+				checks: parseReviewChecks(raw),
+				ruleChecks: parseRuleChecks(raw),
+				// O revisor de fluxo devolve o modelo de intenção no JSON.
+				reviewerBusiness:
+					watchdogId === GENERAL_WATCHDOG_ID
+						? reviewerBusinessOf(raw)
+						: undefined,
 				attempts,
-				durationMs: accumulated.durationMs,
-				sessionId: accumulated.sessionId,
-				numTurns: accumulated.numTurns,
-				costUsd: accumulated.costUsd,
-				usage: accumulated.usage,
+				metrics,
 			};
-			this.emit({
-				type: "done",
-				watchdogId,
-				findings: done.findings,
-				reviewedFiles: done.reviewedFiles,
-				attempts,
-				metrics: accumulated,
-			});
-			return done;
 		}
 
-		const error = lastError || "falha desconhecida.";
-		this.emit({ type: "failed", watchdogId, error, attempts, metrics: accumulated });
-		return failedResult(watchdogId, error, attempts, accumulated);
+		return {
+			ok: false,
+			error: lastError || "falha desconhecida.",
+			attempts,
+			metrics,
+		};
+	}
+
+	/**
+	 * Aplica o modelo devolvido pelo `general` somente se ele for mais rico que
+	 * o já gravado — o revisor reconstrói a intenção sem ver o JSON inteiro e já
+	 * substituiu um modelo da IA (5 fluxos) por um resumo sem fluxos.
+	 */
+	private applyReviewerBusiness(
+		watchdogId: string,
+		incoming: BusinessSummary | undefined,
+	): HuntWatchdogResult["business"] {
+		if (watchdogId !== GENERAL_WATCHDOG_ID || !incoming) return undefined;
+		const decision = chooseBusinessSummary(
+			this.options.work.readBusinessSummary(),
+			incoming,
+		);
+		if (decision.accepted && decision.summary) {
+			this.options.work.writeBusinessSummary(decision.summary);
+		}
+		return {
+			accepted: decision.accepted,
+			source: decision.summary?.source ?? incoming.source,
+			score: businessScore(incoming),
+		};
 	}
 
 	private emit(event: HuntEvent): void {
@@ -345,6 +736,112 @@ export class HuntRunner {
 	}
 }
 
+/** Resultado de uma passada do brief (com retries internos). */
+type PassOutcome =
+	| {
+			ok: true;
+			report: WatchdogReport;
+			checks: ReviewCheck[];
+			ruleChecks: RuleCheck[];
+			reviewerBusiness?: BusinessSummary;
+			attempts: number;
+			metrics: MakiRunMetrics;
+	  }
+	| { ok: false; error: string; attempts: number; metrics: MakiRunMetrics };
+
+/** Modelo de intenção que o `general` devolve no JSON (se válido). */
+function reviewerBusinessOf(raw: unknown): BusinessSummary | undefined {
+	if (typeof raw !== "object" || raw === null) return undefined;
+	const summary = (raw as Record<string, unknown>).businessSummary;
+	if (typeof summary !== "object" || summary === null) return undefined;
+	return (
+		parseBusinessSummary(
+			{ ...(summary as Record<string, unknown>), source: "reviewer" },
+			"reviewer",
+		) ?? undefined
+	);
+}
+
+/** Une as duas passadas: achados por chave, cobertura declarada por união. */
+function mergeReport(first: WatchdogReport, second: WatchdogReport): WatchdogReport {
+	return {
+		watchdogId: first.watchdogId,
+		reviewedFiles: [...new Set([...first.reviewedFiles, ...second.reviewedFiles])],
+		skipped: [...new Set([...first.skipped, ...second.skipped])],
+		findings: mergeFindings(first.findings, second.findings),
+	};
+}
+
+/** Cobertura declarada dos arquivos do domínio do brief. */
+function coverageOf(
+	brief: string,
+	report: WatchdogReport,
+): { total: number; reviewed: number; skipped: number; undeclared: number } {
+	const domain = new Set(briefDomainFiles(brief));
+	if (domain.size === 0) return { total: 0, reviewed: 0, skipped: 0, undeclared: 0 };
+	const reviewed = new Set(
+		report.reviewedFiles.map(normalizePath).filter((file) => domain.has(file)),
+	).size;
+	const skipped = new Set(
+		report.skipped
+			.map(declaredPath)
+			.filter((file): file is string => file !== null && domain.has(file)),
+	).size;
+	return {
+		total: domain.size,
+		reviewed,
+		skipped,
+		undeclared: Math.max(0, domain.size - reviewed - skipped),
+	};
+}
+
+/** Primeiro caminho de arquivo citado numa entrada de `skipped` (ou null). */
+function declaredPath(entry: string): string | null {
+	const match = entry.match(/[\w./-]+\.[A-Za-z0-9]{1,5}/);
+	return match ? normalizePath(match[0]) : null;
+}
+
+/**
+ * Resolver de `at` contra o disco (cache por arquivo).
+ *
+ * O checklist é autoavaliado pelo modelo; sem checar o `at`, um `ok` inventado
+ * conta como cobertura. Aqui só vale se o arquivo existe na raiz da review e a
+ * linha cabe dentro dele. Caminho fora da raiz (`..`) nunca resolve.
+ */
+function makeAtResolver(root: string): AtResolver {
+	const cache = new Map<string, number | null>();
+	const lineCount = (file: string): number | null => {
+		const cached = cache.get(file);
+		if (cached !== undefined) return cached;
+		let total: number | null = null;
+		if (!file.split("/").includes("..")) {
+			try {
+				const content = readFileSync(join(root, file), "utf8");
+				total = content.split("\n").length;
+			} catch {
+				total = null;
+			}
+		}
+		cache.set(file, total);
+		return total;
+	};
+	return (file, line) => {
+		const total = lineCount(file);
+		if (total === null) return false;
+		return line === undefined || (line >= 1 && line <= total);
+	};
+}
+
+/** Modelo de intenção mais rico entre duas passadas. */
+function richerBusiness(
+	first: BusinessSummary | undefined,
+	second: BusinessSummary | undefined,
+): BusinessSummary | undefined {
+	if (!second) return first;
+	if (!first) return second;
+	return businessScore(second) > businessScore(first) ? second : first;
+}
+
 /** Soma métricas de várias tentativas no acumulado. */
 function mergeMetrics(target: MakiRunMetrics, source: MakiRunMetrics): void {
 	target.durationMs += source.durationMs;