@payconductor/houndsman 0.12.0 → 0.14.0

package/src/core/renderers/resume-renderer.ts

@@ -7,12 +7,25 @@
  * `RESUME_MAX_CHARS`.
  */
 
+import { type BusinessSummary, renderBusinessLines } from "../business-summary";
+import type { JevCandidate } from "../jev";
 import type { ContextSummary, MergedFinding } from "../report-builder";
 import { systemClock } from "../services/clock";
 import type { TechnicalSummary } from "../technical-summary";
 
-/** Teto de caracteres do artefato (inclui cabeçalho e quebras de linha). */
-export const RESUME_MAX_CHARS = 5000;
+/**
+ * Teto de caracteres do artefato (inclui cabeçalho e quebras de linha).
+ *
+ * As tabelas e a conclusão têm orçamento reservado — só o texto narrativo
+ * (negócio/técnico) é cortado quando o resumo cresce.
+ */
+export const RESUME_MAX_CHARS = 8000;
+
+/** Fração do orçamento narrativo destinada ao resumo de negócio. */
+const BUSINESS_SHARE = 0.6;
+
+/** Piso do orçamento narrativo mesmo em PRs com muitos domínios. */
+const MIN_NARRATIVE_CHARS = 1200;
 
 /** Dados de classificação usados no resumo. */
 export type ResumeClassification = {
@@ -20,15 +33,34 @@ export type ResumeClassification = {
 	watchdogs: Record<string, string[]>;
 };
 
+/** Cobertura de um domínio (watchdog) na revisão. */
+export type ResumeDomain = {
+	id: string;
+	name: string;
+	findings: number;
+	reviewedFiles: number;
+	expectedFiles: number;
+	/** Arquivos do escopo declarados em `skipped` (não revisados por decisão). */
+	skippedFiles?: number;
+};
+
 export type ReviewResumeInput = {
 	branch: string;
 	/** `YYYY-MM-DD`; default: data corrente do sistema. */
 	date?: string;
 	context?: ContextSummary | null;
+	/** Modelo de intenção da PR (negócio). */
+	business?: BusinessSummary | null;
 	classification: ResumeClassification;
 	findings: readonly MergedFinding[];
 	/** Pontos técnicos estruturais (não achados). */
 	technical?: TechnicalSummary | null;
+	/** Cobertura por domínio (arquivos revisados × esperados). */
+	domains?: readonly ResumeDomain[];
+	/** Candidatos da pré-análise que nenhum watchdog confirmou. */
+	candidates?: readonly JevCandidate[];
+	/** Aviso opcional no topo (ex.: revisão incremental). */
+	note?: string;
 };
 
 const STATUS_BY_SEVERITY: Record<"blocking" | "attention" | "clean", string> = {
@@ -47,8 +79,28 @@ function plural(count: number, singular: string, plural: string): string {
 	return `${count} ${count === 1 ? singular : plural}`;
 }
 
-/** Resumo de negócio: contexto da PR; sem ele, o alcance da branch. */
+/** Resumo de negócio: modelo de intenção; sem ele, contexto da PR/branch. */
 function businessSection(input: ReviewResumeInput): string[] {
+	const lines = ["## Resumo de negócio", ""];
+	const business = input.business;
+
+	if (
+		business &&
+		(business.intent || business.flows.length > 0 || business.invariants.length > 0)
+	) {
+		if (business.intent) lines.push(business.intent, "");
+		else if (input.context?.objective) lines.push(input.context.objective, "");
+		const rendered = renderBusinessLines(business).filter(
+			(line) => !line.startsWith("**Intenção:**"),
+		);
+		while (rendered[0] === "") rendered.shift();
+		if (rendered.length > 0) lines.push(...rendered, "");
+		if (input.context?.motivation) {
+			lines.push(`**Por quê:** ${truncate(input.context.motivation, 480)}`, "");
+		}
+		return lines;
+	}
+
 	const context = input.context;
 	const hasContext =
 		context?.available === true &&
@@ -57,7 +109,6 @@ function businessSection(input: ReviewResumeInput): string[] {
 				context.motivation ||
 				(context.changeSummary && context.changeSummary.length > 0),
 		);
-	const lines = ["## Resumo de negócio", ""];
 
 	if (!hasContext) {
 		const domainCount = Object.keys(input.classification.watchdogs).length;
@@ -107,9 +158,78 @@ function clamp(markdown: string, max: number): string {
 	return `${(cut > 0 ? head.slice(0, cut) : head).trimEnd()}\n…`;
 }
 
+/** Conclusão com os totais por severidade. */
+function conclusionSection(findings: readonly MergedFinding[]): string[] {
+	const counts = {
+		blocking: findings.filter((f) => f.severity === "blocking").length,
+		attention: findings.filter((f) => f.severity === "attention").length,
+		suggestion: findings.filter((f) => f.severity === "suggestion").length,
+		nit: findings.filter((f) => f.severity === "nit").length,
+	};
+	return [
+		"## Conclusão",
+		"",
+		`**Resumo:** ${counts.blocking} bloqueantes · ${counts.attention} atenção · ${counts.suggestion} sugestões · ${counts.nit} nits.`,
+		"",
+	];
+}
+
+/** Cobertura por domínio: revisados, declarados fora do recorte e lacunas. */
+function coverageSection(domains: readonly ResumeDomain[]): string[] {
+	if (domains.length === 0) return [];
+	const lines = [
+		"## Cobertura por domínio",
+		"",
+		"| Domínio | Achados | Revisados | Fora do recorte | Faltam |",
+		"|---|---|---|---|---|",
+	];
+	for (const domain of domains) {
+		const skipped = domain.skippedFiles ?? 0;
+		const missing = Math.max(
+			0,
+			domain.expectedFiles - domain.reviewedFiles - skipped,
+		);
+		lines.push(
+			`| ${domain.name} | ${domain.findings} | ${domain.reviewedFiles}/${domain.expectedFiles} | ${skipped > 0 ? skipped : "—"} | ${missing > 0 ? missing : "—"} |`,
+		);
+	}
+	lines.push(
+		"",
+		"> `Faltam` = arquivos do escopo sem revisão e sem declaração em `skipped`.",
+		"",
+	);
+	return lines;
+}
+
+/** Candidatos da pré-análise que nenhum watchdog confirmou (não bloqueiam). */
+function candidatesSection(
+	candidates: readonly JevCandidate[],
+	findings: readonly MergedFinding[],
+): string[] {
+	if (candidates.length === 0) return [];
+	const confirmed = new Set(findings.map((f) => `${f.file}|${f.rule}`));
+	const pending = candidates.filter((c) => !confirmed.has(`${c.file}|${c.rule}`));
+	if (pending.length === 0) return [];
+	const lines = [
+		`## Candidatos não verificados (${pending.length})`,
+		"",
+		"> Indícios da pré-análise que nenhum watchdog confirmou. Não bloqueiam.",
+		"",
+	];
+	for (const candidate of pending.slice(0, 8)) {
+		lines.push(
+			`- \`${candidate.file}\` · ${candidate.severity} · ${truncate(candidate.rule, 160)}`,
+		);
+	}
+	if (pending.length > 8) lines.push(`- … +${pending.length - 8}`);
+	lines.push("");
+	return lines;
+}
+
 /**
  * Renderiza o resumo final. Determinístico e sem chamadas externas: o texto
- * nasce do contexto já disponível e dos pontos técnicos persistidos.
+ * nasce do contexto já disponível, do modelo de intenção, dos pontos técnicos
+ * e da cobertura por domínio. `review-resume.md` é o único artefato humano.
  */
 export function renderReviewResume(input: ReviewResumeInput): string {
 	const blockers = input.findings.filter((f) => f.severity === "blocking").length;
@@ -121,14 +241,34 @@ export function renderReviewResume(input: ReviewResumeInput): string {
 				? STATUS_BY_SEVERITY.attention
 				: STATUS_BY_SEVERITY.clean;
 
-	const lines = [
+	const header = [
 		`# Resumo da revisão — ${input.branch}`,
 		"",
 		`**Data:** ${input.date ?? systemClock().slice(0, 10)} · **Status:** ${status}`,
-		"",
-		...businessSection(input),
-		...technicalSection(input.technical),
-	];
+		...(input.note?.trim() ? ["", input.note.trim()] : []),
+	].join("\n");
+
+	const coverage = coverageSection(input.domains ?? []).join("\n");
+	const candidates = candidatesSection(input.candidates ?? [], input.findings).join(
+		"\n",
+	);
+	const conclusion = conclusionSection(input.findings).join("\n");
+
+	// Tabelas e conclusão primeiro: o que sobra é o orçamento do texto narrativo.
+	const reserved = [header, coverage, candidates, conclusion]
+		.filter((part) => part.length > 0)
+		.join("\n\n").length;
+	const budget = Math.max(MIN_NARRATIVE_CHARS, RESUME_MAX_CHARS - reserved);
+	const businessMax = Math.floor(budget * BUSINESS_SHARE);
+	const business = clamp(businessSection(input).join("\n"), businessMax);
+	const technical = clamp(
+		technicalSection(input.technical).join("\n"),
+		budget - businessMax,
+	);
 
-	return clamp(`${lines.join("\n").trimEnd()}\n`, RESUME_MAX_CHARS);
+	const body = [header, business, technical, coverage, candidates, conclusion]
+		.map((part) => part.trim())
+		.filter((part) => part.length > 0)
+		.join("\n\n");
+	return `${body}\n`;
 }

package/src/core/report-builder.ts

@@ -1,20 +1,16 @@
 /**
- * Consolidação dos relatórios JSON dos watchdogs em um markdown (biblioteca).
+ * Relatórios JSON dos watchdogs: tipos, validação, normalização e dedupe.
  *
- * Entrypoint: `cli/review.ts` (via `core/orchestrator.ts`). Deduplica achados
- * por (file, line, rule), agrupa por severidade e renderiza a tabela de cobertura.
+ * Entrypoint: `cli/review.ts` (via `core/orchestrator.ts`). A renderização do
+ * resumo final vive em `core/renderers/resume-renderer.ts`.
  *
  * Schema dos watchdogs: asset `OUTPUT-FORMAT.md` (embarcado em `src/skill/`).
  */
 
-import type { JevCandidate } from "./jev";
-import { systemClock } from "./services/clock";
-import { SEVERITY_EMOJI, SEVERITY_ORDER, type Severity, severityRank } from "./types";
+import { SEVERITY_ORDER, type Severity, severityRank } from "./types";
 
-/** Resolve o nome legível de um watchdog (default: identidade). */
-export type WatchdogNameResolver = (watchdogId: string) => string;
-
-const identityName: WatchdogNameResolver = (id) => id;
+/** Origem do finding: regra explícita, consistência lógica ou domínio. */
+export type FindingBasis = "rule" | "logic" | "domain";
 
 export type Finding = {
 	/** Id curto do finding (preenchido no `--finalize`; usado pela triagem). */
@@ -26,6 +22,14 @@ export type Finding = {
 	message: string;
 	action: string;
 	evidence?: string;
+	/** Gatilho concreto que expõe o gap (obrigatório para `blocking` fora de regra). */
+	scenario?: string;
+	/** Consequência observável do gap. */
+	impact?: string;
+	/** Confiança do revisor (0–1). */
+	confidence?: number;
+	/** Origem do achado; inferida pelo prefixo `Lógica:`/`Domínio:` quando ausente. */
+	basis?: FindingBasis;
 	/**
 	 * Commit em que o achado foi observado (interno). Preenchido nos carry-over
 	 * do review incremental — preserva a referência para a verificação (verify).
@@ -92,6 +96,39 @@ export function sanitizeBranch(branch: string): string {
 		.toLowerCase();
 }
 
+/** Normaliza o rótulo de uma variante A/B (`baseline` → `baseline`). */
+export function sanitizeVariant(variant: string): string {
+	return variant
+		.trim()
+		.replace(/[^a-zA-Z0-9._-]+/g, "-")
+		.replace(/^-+|-+$/g, "")
+		.toLowerCase()
+		.slice(0, 32);
+}
+
+/** Hash curto e estável (FNV-1a) para desambiguar slugs de variantes. */
+function shortHash(value: string): string {
+	let hash = 2166136261;
+	for (let index = 0; index < value.length; index++) {
+		hash ^= value.charCodeAt(index);
+		hash = Math.imul(hash, 16777619);
+	}
+	return (hash >>> 0).toString(16).padStart(6, "0").slice(0, 6);
+}
+
+/**
+ * Slug da run (diretório do backend de arquivos e URL da UI).
+ *
+ * Run principal: slug da branch. Variante A/B: `branch--variante-<hash>` — o
+ * hash garante unicidade mesmo quando dois rótulos sanitizam para o mesmo texto.
+ */
+export function reviewSlug(branch: string, variant?: string): string {
+	const base = sanitizeBranch(branch);
+	const label = variant?.trim() ? sanitizeVariant(variant) : "";
+	if (!label) return base;
+	return `${base}--${label}-${shortHash(`${branch}\u0000${variant?.trim() ?? ""}`)}`;
+}
+
 function isFinding(value: unknown): value is Finding {
 	if (typeof value !== "object" || value === null) return false;
 	const f = value as Record<string, unknown>;
@@ -102,10 +139,54 @@ function isFinding(value: unknown): value is Finding {
 		typeof f.file === "string" &&
 		typeof f.message === "string" &&
 		typeof f.action === "string" &&
-		(f.line === undefined || typeof f.line === "number")
+		(f.line === undefined || typeof f.line === "number") &&
+		(f.scenario === undefined || typeof f.scenario === "string") &&
+		(f.impact === undefined || typeof f.impact === "string") &&
+		(f.confidence === undefined || typeof f.confidence === "number") &&
+		(f.basis === undefined ||
+			f.basis === "rule" ||
+			f.basis === "logic" ||
+			f.basis === "domain")
 	);
 }
 
+/** Infere a origem do finding pelo prefixo reservado da regra. */
+export function inferBasis(rule: string): FindingBasis {
+	const text = rule.trim().toLowerCase();
+	if (text.startsWith("lógica:") || text.startsWith("logica:")) return "logic";
+	if (text.startsWith("domínio:") || text.startsWith("dominio:")) return "domain";
+	return "rule";
+}
+
+/**
+ * Normaliza um finding e aplica a política de severidade: fora de regra,
+ * `blocking` exige `scenario` + `evidence`; sem os dois, rebaixa para
+ * `attention`. A regra explícita mantém a severidade declarada pelo watchdog.
+ */
+export function normalizeFinding(
+	finding: Finding,
+	onWarn: (message: string) => void = () => {},
+): Finding {
+	const basis = finding.basis ?? inferBasis(finding.rule);
+	const confidence =
+		finding.confidence === undefined
+			? undefined
+			: Math.min(1, Math.max(0, finding.confidence));
+	const normalized: Finding = { ...finding, basis, confidence };
+	if (basis !== "rule" && normalized.severity === "blocking") {
+		const proven = Boolean(
+			normalized.scenario?.trim() && normalized.evidence?.trim(),
+		);
+		if (!proven) {
+			normalized.severity = "attention";
+			onWarn(
+				`[report-builder] ${finding.file}: finding ${basis} sem cenário+evidência rebaixado para attention.`,
+			);
+		}
+	}
+	return normalized;
+}
+
 /** Valida e normaliza um relatório. Retorna null se inválido. */
 export function parseWatchdogReport(
 	raw: unknown,
@@ -126,13 +207,14 @@ export function parseWatchdogReport(
 		return null;
 	}
 
-	const findings = obj.findings.filter((f) => {
-		if (!isFinding(f)) {
+	const findings: Finding[] = [];
+	for (const item of obj.findings) {
+		if (!isFinding(item)) {
 			onError(`[report-builder] ${source}: finding inválido ignorado`);
-			return false;
+			continue;
 		}
-		return true;
-	});
+		findings.push(normalizeFinding(item, onError));
+	}
 
 	return {
 		watchdogId: obj.watchdogId,
@@ -198,6 +280,16 @@ export function dedupeFindings(reports: WatchdogReport[]): MergedFinding[] {
 					existing.action = finding.action;
 					existing.evidence = finding.evidence ?? existing.evidence;
 				}
+				// Cenário/impacto/confiança nunca se perdem no merge.
+				existing.scenario = existing.scenario ?? finding.scenario;
+				existing.impact = existing.impact ?? finding.impact;
+				if (finding.confidence !== undefined) {
+					existing.confidence = Math.max(
+						existing.confidence ?? 0,
+						finding.confidence,
+					);
+				}
+				existing.basis = existing.basis ?? finding.basis;
 				continue;
 			}
 			map.set(key, { ...finding, watchdogs: [report.watchdogId] });
@@ -210,265 +302,3 @@ export function dedupeFindings(reports: WatchdogReport[]): MergedFinding[] {
 		return (a.line ?? 0) - (b.line ?? 0);
 	});
 }
-
-function watchdogName(nameOf: WatchdogNameResolver, id: string): string {
-	return nameOf(id);
-}
-
-function renderFinding(finding: MergedFinding, nameOf: WatchdogNameResolver): string[] {
-	const location = finding.line ? `${finding.file}:${finding.line}` : finding.file;
-	const watchdogs = finding.watchdogs.map((r) => watchdogName(nameOf, r)).join(", ");
-	const id = finding.id ? ` · \`${finding.id}\`` : "";
-	const lines = [
-		`- **${finding.rule}** — \`${location}\` · _${watchdogs}_${id}`,
-		`  ${finding.message}`,
-		`  **Ação:** ${finding.action}`,
-	];
-	if (finding.evidence) {
-		lines.push(`  **Evidência:** \`${finding.evidence}\``);
-	}
-	lines.push("");
-	return lines;
-}
-
-function renderCoverage(
-	reports: WatchdogReport[],
-	coverage: { classified?: Record<string, string[]> },
-	nameOf: WatchdogNameResolver,
-): string[] {
-	const lines = [
-		"## Cobertura",
-		"",
-		"| Watchdog | Arquivos revisados | Findings |",
-		"|---|---|---|",
-	];
-	for (const report of reports) {
-		const expected = coverage.classified?.[report.watchdogId];
-		const reviewed = new Set(report.reviewedFiles);
-		const pending = expected ? expected.filter((f) => !reviewed.has(f)) : [];
-		const reviewedLabel =
-			expected && pending.length > 0
-				? `${report.reviewedFiles.length}/${expected.length} (faltam ${pending.length})`
-				: `${report.reviewedFiles.length}`;
-		lines.push(
-			`| ${watchdogName(nameOf, report.watchdogId)} | ${reviewedLabel} | ${report.findings.length} |`,
-		);
-	}
-	lines.push("");
-	return lines;
-}
-
-/** Candidatos Jev não confirmados por nenhum watchdog — revisão manual, não bloqueiam. */
-function renderUnconfirmedCandidates(
-	candidates: JevCandidate[],
-	merged: MergedFinding[],
-): string[] {
-	const confirmed = new Set(merged.map((f) => `${f.file}|${f.rule}`));
-	const pending = candidates.filter((c) => !confirmed.has(`${c.file}|${c.rule}`));
-	if (pending.length === 0) return [];
-	const lines = [
-		"## 🔎 Candidatos não verificados (Jev)",
-		"",
-		"> Indícios automáticos que nenhum watchdog confirmou. Revise manualmente — não bloqueiam.",
-		"",
-	];
-	for (const c of pending) {
-		lines.push(
-			`- \`${c.file}\` · **${c.severity}** · confiança ${c.confidence.toFixed(2)} · _${c.watchdogId}_`,
-			`  ${c.rule}`,
-			"",
-		);
-	}
-	return lines;
-}
-
-function renderConclusion(counts: Record<Severity, number>): string[] {
-	const status =
-		counts.blocking > 0
-			? "❌ Mudanças Necessárias"
-			: counts.attention > 0
-				? "⚠️ Aprovado com Ressalvas"
-				: "✅ Aprovado";
-	return [
-		"## Conclusão",
-		"",
-		`**Status:** ${status}`,
-		`**Resumo:** ${counts.blocking} violações bloqueantes, ${counts.attention} pontos de atenção, ${counts.suggestion} sugestões e ${counts.nit} nits.`,
-		"",
-	];
-}
-
-/**
- * Agrupa os achados por arquivo (navegabilidade em PRs grandes) e renderiza cada
- * bloco. O `merged` já vem ordenado por severidade/arquivo/linha.
- */
-function renderFindingsByFile(
-	findings: readonly MergedFinding[],
-	nameOf: WatchdogNameResolver,
-): string[] {
-	const byFile = new Map<string, MergedFinding[]>();
-	for (const finding of findings) {
-		const list = byFile.get(finding.file);
-		if (list) list.push(finding);
-		else byFile.set(finding.file, [finding]);
-	}
-
-	const lines: string[] = [];
-	for (const [file, items] of byFile) {
-		lines.push(`### \`${file}\``, "");
-		for (const item of items) lines.push(...renderFinding(item, nameOf));
-	}
-	return lines;
-}
-
-/** Seções por severidade (❌ > ⚠️ > 💡 > 🔎), com achados agrupados por arquivo. */
-function renderFindingsSections(
-	merged: readonly MergedFinding[],
-	nameOf: WatchdogNameResolver,
-): string[] {
-	const lines: string[] = [];
-	for (const severity of SEVERITY_ORDER) {
-		const items = merged.filter((f) => f.severity === severity);
-		if (items.length === 0) continue;
-		lines.push(`## ${SEVERITY_EMOJI[severity]} ${severity}`, "");
-		lines.push(...renderFindingsByFile(items, nameOf));
-	}
-	return lines;
-}
-
-/** Relatório de domínio gravado à parte (um por watchdog com achados). */
-export type DomainReport = {
-	id: string;
-	name: string;
-	/** Nome do arquivo do relatório (relativo ao diretório de artefatos). */
-	file: string;
-	findings: number;
-	reviewedFiles: number;
-	expectedFiles: number;
-};
-
-/** Índice dos relatórios por domínio (seção do `review.md` consolidado). */
-function renderDomainIndex(domains: readonly DomainReport[]): string[] {
-	if (domains.length === 0) return [];
-	const lines = [
-		"## Relatórios por domínio",
-		"",
-		"| Watchdog | Achados | Revisados | Relatório |",
-		"|---|---|---|---|",
-	];
-	for (const domain of domains) {
-		lines.push(
-			`| ${domain.name} | ${domain.findings} | ${domain.reviewedFiles}/${domain.expectedFiles} | [\`${domain.file}\`](${domain.file}) |`,
-		);
-	}
-	lines.push("");
-	return lines;
-}
-
-/**
- * Relatório isolado de um watchdog — mantém o `review.md` enxuto em PRs grandes.
- */
-export function renderDomainReport(
-	branch: string,
-	report: WatchdogReport,
-	merged: MergedFinding[],
-	expectedFiles: number,
-	context?: ContextSummary | null,
-	nameOf: WatchdogNameResolver = identityName,
-): string {
-	const now = systemClock().slice(0, 10);
-	const name = watchdogName(nameOf, report.watchdogId);
-	const lines: string[] = [
-		`# Review — ${name} (\`${report.watchdogId}\`) — ${branch}`,
-		"",
-		`**Data:** ${now}`,
-		`**Arquivos revisados:** ${report.reviewedFiles.length}/${expectedFiles}`,
-		`**Achados:** ${merged.length}`,
-		"",
-	];
-
-	if (context?.available) lines.push(...renderContext(context));
-
-	lines.push(...renderFindingsSections(merged, nameOf));
-	if (merged.length === 0) lines.push("Nenhum achado. ✅", "");
-
-	if (report.skipped.length > 0) {
-		lines.push(
-			"## Não revisados",
-			"",
-			...report.skipped.map((item) => `- \`${item}\``),
-			"",
-		);
-	}
-
-	return lines.join("\n");
-}
-
-/** Seção de contexto da PR (Objetivo / Motivação / Resumo das alterações). */
-function renderContext(context: ContextSummary): string[] {
-	const lines = ["## Contexto da PR", ""];
-	const src = context.source;
-
-	const ref = [src?.number ? `#${src.number}` : "", src?.title ?? ""]
-		.filter(Boolean)
-		.join(" ");
-	if (ref) lines.push(`**PR:** ${ref}${src?.url ? ` — ${src.url}` : ""}`);
-	if (src?.head && src?.base)
-		lines.push(`**Branch:** \`${src.head}\` → \`${src.base}\``);
-	if (context.objective) lines.push(`**Objetivo:** ${context.objective}`);
-	if (context.motivation) lines.push(`**Motivação:** ${context.motivation}`);
-	if (context.changeSummary && context.changeSummary.length > 0) {
-		lines.push("", "**Resumo das alterações:**", "");
-		for (const item of context.changeSummary) lines.push(`- ${item}`);
-	}
-	lines.push("");
-	return lines;
-}
-
-export function renderReport(
-	branch: string,
-	reports: WatchdogReport[],
-	merged: MergedFinding[],
-	coverage: { classified?: Record<string, string[]> },
-	context?: ContextSummary | null,
-	candidates?: JevCandidate[],
-	nameOf: WatchdogNameResolver = identityName,
-	domains: readonly DomainReport[] = [],
-): string {
-	const now = systemClock().slice(0, 10);
-	const counts = {
-		blocking: merged.filter((f) => f.severity === "blocking").length,
-		attention: merged.filter((f) => f.severity === "attention").length,
-		suggestion: merged.filter((f) => f.severity === "suggestion").length,
-		nit: merged.filter((f) => f.severity === "nit").length,
-	};
-
-	const lines: string[] = [
-		`# PR Review — ${branch}`,
-		"",
-		`**Data:** ${now}`,
-		`**Watchdogs ativos:** ${reports.map((r) => r.watchdogId).join(", ") || "—"}`,
-		`**Achados:** ${counts.blocking} bloqueantes · ${counts.attention} atenção · ${counts.suggestion} sugestões · ${counts.nit} nits`,
-		"",
-	];
-
-	if (context) lines.push(...renderContext(context));
-
-	// Sumário primeiro: quem lê o review.md vê domínios, cobertura e conclusão
-	// antes dos pontos específicos.
-	lines.push(...renderDomainIndex(domains));
-	lines.push(...renderCoverage(reports, coverage, nameOf));
-	lines.push(...renderConclusion(counts));
-
-	lines.push(...renderFindingsSections(merged, nameOf));
-
-	if (merged.length === 0) {
-		lines.push("Nenhum achado. ✅", "");
-	}
-
-	if (candidates && candidates.length > 0) {
-		lines.push(...renderUnconfirmedCandidates(candidates, merged));
-	}
-
-	return lines.join("\n");
-}

package/src/core/storage/file/file-storage.ts

@@ -39,7 +39,7 @@ export class FileStorageProvider implements StorageProvider {
 	// -----------------------------------------------------------------------
 
 	getOrCreateReview(input: CreateReviewInput): ReviewRecord {
-		const existing = this.findReview(input.repo.key, input.branch);
+		const existing = this.findReview(input.repo.key, input.branch, input.variant);
 		if (existing) {
 			if (
 				existing.repoRoot !== input.repo.root ||
@@ -66,6 +66,7 @@ export class FileStorageProvider implements StorageProvider {
 			repoRoot: input.repo.root,
 			repoRemote: input.repo.remote,
 			branch: input.branch,
+			variant: input.variant?.trim() || undefined,
 			slug: input.slug,
 			base: input.base,
 			head: input.head,
@@ -78,9 +79,12 @@ export class FileStorageProvider implements StorageProvider {
 		return this.writeReview(record);
 	}
 
-	findReview(repoKey: string, branch: string): ReviewRecord | null {
+	findReview(repoKey: string, branch: string, variant?: string): ReviewRecord | null {
+		const label = variant?.trim() ?? "";
 		return (
-			this.readReviews(repoKey).find((review) => review.branch === branch) ?? null
+			this.readReviews(repoKey).find(
+				(review) => review.branch === branch && (review.variant ?? "") === label,
+			) ?? null
 		);
 	}