@payconductor/houndsman 0.13.0 → 0.14.0

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
 		);
 	}
 

package/src/core/storage/sqlite/mappers.ts

@@ -22,6 +22,7 @@ export type ReviewRow = {
 	repo_root: string;
 	repo_remote: string | null;
 	branch: string;
+	variant: string;
 	slug: string;
 	base: string | null;
 	head: string | null;
@@ -50,6 +51,10 @@ export type FindingRow = {
 	message: string;
 	action: string;
 	evidence: string | null;
+	scenario: string | null;
+	impact: string | null;
+	confidence: number | null;
+	basis: string | null;
 	anchor: string | null;
 	found_at_sha: string | null;
 	count: number;
@@ -91,6 +96,7 @@ export function reviewFromRow(row: ReviewRow): ReviewRecord {
 		repoRoot: row.repo_root,
 		repoRemote: row.repo_remote ?? undefined,
 		branch: row.branch,
+		variant: row.variant || undefined,
 		slug: row.slug,
 		base: row.base ?? undefined,
 		head: row.head ?? undefined,
@@ -129,6 +135,10 @@ export function findingFromRow(row: FindingRow, history: HistoryRow[]): FindingS
 		message: row.message,
 		action: row.action,
 		evidence: row.evidence ?? undefined,
+		scenario: row.scenario ?? undefined,
+		impact: row.impact ?? undefined,
+		confidence: row.confidence === null ? undefined : Number(row.confidence),
+		basis: (row.basis as FindingState["basis"]) ?? undefined,
 		anchor: parseJson<FindingAnchor>(row.anchor) ?? null,
 		foundAtSha: row.found_at_sha ?? undefined,
 		count: Number(row.count),

package/src/core/storage/sqlite/schema.ts

@@ -7,7 +7,7 @@
 
 import type { Database } from "bun:sqlite";
 
-export const SCHEMA_VERSION = 3;
+export const SCHEMA_VERSION = 5;
 
 const DDL = `
 CREATE TABLE IF NOT EXISTS reviews (
@@ -16,6 +16,7 @@ CREATE TABLE IF NOT EXISTS reviews (
 	repo_root TEXT NOT NULL,
 	repo_remote TEXT,
 	branch TEXT NOT NULL,
+	variant TEXT NOT NULL DEFAULT '',
 	slug TEXT NOT NULL,
 	base TEXT,
 	head TEXT,
@@ -29,7 +30,7 @@ CREATE TABLE IF NOT EXISTS reviews (
 	pr_number INTEGER,
 	created_at TEXT NOT NULL,
 	updated_at TEXT NOT NULL,
-	UNIQUE(repo_key, branch)
+	UNIQUE(repo_key, branch, variant)
 );
 
 CREATE INDEX IF NOT EXISTS idx_reviews_repo_updated
@@ -48,6 +49,10 @@ CREATE TABLE IF NOT EXISTS findings (
 	message TEXT NOT NULL,
 	action TEXT NOT NULL,
 	evidence TEXT,
+	scenario TEXT,
+	impact TEXT,
+	confidence REAL,
+	basis TEXT,
 	anchor TEXT,
 	found_at_sha TEXT,
 	count INTEGER NOT NULL DEFAULT 1,
@@ -93,7 +98,6 @@ CREATE INDEX IF NOT EXISTS idx_artifacts_review ON artifacts(review_id);
 
 /** Aplica pragmas e cria o schema quando necessário. */
 export function migrate(db: Database, path: string): void {
-	db.exec("PRAGMA foreign_keys = ON;");
 	db.exec("PRAGMA busy_timeout = 5000;");
 	db.exec("PRAGMA synchronous = NORMAL;");
 	if (path !== ":memory:") db.exec("PRAGMA journal_mode = WAL;");
@@ -102,25 +106,102 @@ export function migrate(db: Database, path: string): void {
 		user_version?: number;
 	} | null;
 	const version = Number(row?.user_version ?? 0);
-	if (version >= SCHEMA_VERSION) return;
+	if (version >= SCHEMA_VERSION) {
+		db.exec("PRAGMA foreign_keys = ON;");
+		return;
+	}
 
-	db.transaction(() => {
-		db.exec(DDL);
-		// v2: heartbeat explícito da execução (bancos v1 não tinham a coluna).
-		// v3: worktree/pr da revisão (revisões paralelas).
-		const columns = db.query("PRAGMA table_info(reviews)").all() as {
-			name: string;
-		}[];
-		const missing: [string, string][] = [
-			["heartbeat_at", "TEXT"],
-			["worktree_path", "TEXT"],
-			["pr_number", "INTEGER"],
-		];
-		for (const [name, type] of missing) {
-			if (!columns.some((column) => column.name === name)) {
-				db.exec(`ALTER TABLE reviews ADD COLUMN ${name} ${type}`);
-			}
-		}
-		db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
-	})();
+	// O rebuild de `reviews` (v5) troca a chave única e precisa de FKs desligadas:
+	// com elas ligadas, `DROP TABLE reviews` cascatearia e apagaria os filhos.
+	db.exec("PRAGMA foreign_keys = OFF;");
+	try {
+		db.transaction(() => {
+			db.exec(DDL);
+			// v2: heartbeat explícito da execução; v3: worktree/pr da revisão;
+			// v4: cenário/impacto/confiança/origem do finding.
+			const addMissing = (table: string, columns: [string, string][]): void => {
+				const info = db.query(`PRAGMA table_info(${table})`).all() as {
+					name: string;
+				}[];
+				for (const [name, type] of columns) {
+					if (!info.some((column) => column.name === name)) {
+						db.exec(`ALTER TABLE ${table} ADD COLUMN ${name} ${type}`);
+					}
+				}
+			};
+			addMissing("reviews", [
+				["heartbeat_at", "TEXT"],
+				["worktree_path", "TEXT"],
+				["pr_number", "INTEGER"],
+			]);
+			addMissing("findings", [
+				["scenario", "TEXT"],
+				["impact", "TEXT"],
+				["confidence", "REAL"],
+				["basis", "TEXT"],
+			]);
+			// v5: variante A/B na identidade da review.
+			rebuildReviewsWithVariant(db);
+			db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
+		})();
+	} finally {
+		db.exec("PRAGMA foreign_keys = ON;");
+	}
+	const violations = db.query("PRAGMA foreign_key_check").all();
+	if (violations.length > 0) {
+		throw new Error(
+			`Migração do banco deixou ${violations.length} referência(s) inválida(s).`,
+		);
+	}
+}
+
+/**
+ * v5 — adiciona `variant` e troca `UNIQUE(repo_key, branch)` por
+ * `UNIQUE(repo_key, branch, variant)`.
+ *
+ * SQLite não remove constraint inline: recria a tabela preservando os ids (as
+ * FKs dos filhos continuam válidas) e recria o índice.
+ */
+function rebuildReviewsWithVariant(db: Database): void {
+	const columns = db.query("PRAGMA table_info(reviews)").all() as {
+		name: string;
+	}[];
+	if (columns.some((column) => column.name === "variant")) return;
+
+	db.exec(`
+CREATE TABLE reviews_v5 (
+	id TEXT PRIMARY KEY,
+	repo_key TEXT NOT NULL,
+	repo_root TEXT NOT NULL,
+	repo_remote TEXT,
+	branch TEXT NOT NULL,
+	variant TEXT NOT NULL DEFAULT '',
+	slug TEXT NOT NULL,
+	base TEXT,
+	head TEXT,
+	head_sha TEXT,
+	reviewed_sha TEXT,
+	reviewed_at TEXT,
+	status TEXT,
+	started_at TEXT,
+	heartbeat_at TEXT,
+	worktree_path TEXT,
+	pr_number INTEGER,
+	created_at TEXT NOT NULL,
+	updated_at TEXT NOT NULL,
+	UNIQUE(repo_key, branch, variant)
+);
+INSERT INTO reviews_v5
+	(id, repo_key, repo_root, repo_remote, branch, variant, slug, base, head,
+	 head_sha, reviewed_sha, reviewed_at, status, started_at, heartbeat_at,
+	 worktree_path, pr_number, created_at, updated_at)
+SELECT id, repo_key, repo_root, repo_remote, branch, '', slug, base, head,
+	 head_sha, reviewed_sha, reviewed_at, status, started_at, heartbeat_at,
+	 worktree_path, pr_number, created_at, updated_at
+FROM reviews;
+DROP TABLE reviews;
+ALTER TABLE reviews_v5 RENAME TO reviews;
+CREATE INDEX IF NOT EXISTS idx_reviews_repo_updated
+	ON reviews(repo_key, updated_at DESC);
+`);
 }