@payconductor/houndsman 0.13.0 → 0.16.0

package/src/core/severity.ts

@@ -0,0 +1,245 @@
+/**
+ * Severidade determinística (biblioteca) — a regra manda, não a opinião do watchdog.
+ *
+ * Finding de regra (`basis: "rule"`) usa a severidade declarada em `Rule.severity`;
+ * finding emergente (`Lógica:`/`Domínio:`) usa a tabela fixa de `impactClass`. O valor
+ * emitido só prevalece quando não há como resolver (paráfrase sem casamento, relatório
+ * legado sem `impactClass`) — fail-open. Toda divergência é contabilizada para o
+ * finalize avisar e para o `compare` provar a estabilidade entre runs.
+ */
+
+import { type Finding, inferBasis, type WatchdogReport } from "./report-builder";
+import { type Rule, type Severity, severityRank } from "./types";
+
+/** Classe de impacto de um finding emergente — define a severidade fora de regra. */
+export type ImpactClass = "flow-break" | "contract-drift" | "degradation" | "cosmetic";
+
+/** Classes válidas, da mais para a menos grave. */
+export const IMPACT_CLASSES: readonly ImpactClass[] = [
+	"flow-break",
+	"contract-drift",
+	"degradation",
+	"cosmetic",
+];
+
+/** Tabela fixa `impactClass` → severidade. */
+export const SEVERITY_BY_IMPACT: Record<ImpactClass, Severity> = {
+	"flow-break": "blocking",
+	"contract-drift": "attention",
+	degradation: "suggestion",
+	cosmetic: "nit",
+};
+
+const IMPACT_SET = new Set<string>(IMPACT_CLASSES);
+
+/** Tamanho mínimo para casar uma regra com o trecho citado pelo watchdog. */
+const MIN_FRAGMENT_CHARS = 24;
+
+/** `true` quando `value` é uma classe de impacto conhecida. */
+export function isImpactClass(value: unknown): value is ImpactClass {
+	return typeof value === "string" && IMPACT_SET.has(value);
+}
+
+/**
+ * Texto canônico da regra para casar `findings[].rule` com `rules[].text`.
+ *
+ * O brief imprime `- ❌ **blocking** — Promover: …`; o watchdog às vezes copia a
+ * linha inteira, às vezes só o trecho. A normalização remove markdown, emoji,
+ * bullet e o prefixo de severidade antes de comparar.
+ */
+export function normalizeRuleText(text: string): string {
+	return text
+		.normalize("NFC")
+		.replace(/[`*_]/g, "")
+		.replace(/\p{Extended_Pictographic}|\uFE0F/gu, "")
+		.replace(/\s+/g, " ")
+		.trim()
+		.toLowerCase()
+		.replace(/^[-•]\s*/u, "")
+		.replace(/^(blocking|attention|suggestion|nit)\s*[—–-]\s*/u, "")
+		.replace(/[.:;]+$/u, "")
+		.trim();
+}
+
+/** Regra declarada correspondente a um texto de finding. */
+export type DeclaredSeverity = { rule: Rule; severity: Severity };
+
+/**
+ * Resolve a regra declarada que corresponde ao texto reportado.
+ *
+ * Exato primeiro; depois contenção (o modelo citou a regra inteira ou um trecho
+ * com pelo menos `MIN_FRAGMENT_CHARS`). Empate entre watchdogs fica com a regra
+ * mais grave — determinístico e coerente com o dedupe.
+ */
+export function resolveDeclaredSeverity(
+	ruleText: string,
+	rules: readonly Rule[],
+): DeclaredSeverity | null {
+	const needle = normalizeRuleText(ruleText);
+	if (!needle) return null;
+
+	const candidates = rules.map((rule) => ({
+		rule,
+		text: normalizeRuleText(rule.text),
+	}));
+	const exact = candidates.filter((item) => item.text === needle);
+	const matches =
+		exact.length > 0
+			? exact
+			: candidates.filter((item) => isFragment(needle, item.text));
+	if (matches.length === 0) return null;
+
+	let best = matches[0].rule;
+	for (const item of matches) {
+		if (severityRank(item.rule.severity) < severityRank(best.severity)) {
+			best = item.rule;
+		}
+	}
+	return { rule: best, severity: best.severity };
+}
+
+/** Contenção nos dois sentidos, exigindo fragmento longo o bastante. */
+function isFragment(a: string, b: string): boolean {
+	if (a.length < MIN_FRAGMENT_CHARS || b.length < MIN_FRAGMENT_CHARS) return false;
+	return a.includes(b) || b.includes(a);
+}
+
+/** De onde veio a severidade aplicada. */
+export type SeveritySource = "rule" | "impact";
+
+/** Divergência entre o valor emitido e o resolvido (para aviso no finalize). */
+export type SeverityDivergence = {
+	watchdogId: string;
+	file: string;
+	rule: string;
+	emitted: Severity;
+	resolved: Severity;
+	source: SeveritySource;
+};
+
+/** Resultado da ancoragem sobre os relatórios de uma run. */
+export type SeverityAnchoring = {
+	reports: WatchdogReport[];
+	/** Findings de regra cujo texto casou com uma regra declarada. */
+	anchored: number;
+	/** Findings emergentes com `impactClass` válido. */
+	classified: number;
+	/** Findings de regra sem casamento (severidade emitida mantida). */
+	unmatched: number;
+	diverged: SeverityDivergence[];
+};
+
+type Resolution = { severity: Severity; source: SeveritySource };
+
+/** Severidade declarada pelo motor (null = manter a emitida). */
+function resolveSeverity(finding: Finding, rules: readonly Rule[]): Resolution | null {
+	if ((finding.basis ?? inferBasis(finding.rule)) !== "rule") {
+		const impact = finding.impactClass;
+		if (!isImpactClass(impact)) return null;
+		return { severity: SEVERITY_BY_IMPACT[impact], source: "impact" };
+	}
+	const declared = resolveDeclaredSeverity(finding.rule, rules);
+	return declared ? { severity: declared.severity, source: "rule" } : null;
+}
+
+/**
+ * Gate de prova: fora de regra, `blocking` exige gatilho + evidência.
+ *
+ * `normalizeFinding` já aplica isso na leitura do relatório; a checagem aqui
+ * cobre chamadas com findings construídos em memória (harness/testes).
+ */
+function provenSeverity(finding: Finding, resolution: Resolution): Severity {
+	if (resolution.source !== "impact" || resolution.severity !== "blocking") {
+		return resolution.severity;
+	}
+	const proven = Boolean(finding.scenario?.trim() && finding.evidence?.trim());
+	return proven ? "blocking" : "attention";
+}
+
+/**
+ * Ancora a severidade de todos os relatórios (função pura — devolve novos objetos).
+ * `rules` é a união das regras de todos os watchdogs ativos (inclui o piso do `general`).
+ */
+export function anchorReports(
+	reports: readonly WatchdogReport[],
+	rules: readonly Rule[],
+): SeverityAnchoring {
+	const anchoring: SeverityAnchoring = {
+		reports: [],
+		anchored: 0,
+		classified: 0,
+		unmatched: 0,
+		diverged: [],
+	};
+
+	for (const report of reports) {
+		const findings = report.findings.map((finding) => {
+			const resolution = resolveSeverity(finding, rules);
+			if (!resolution) {
+				if ((finding.basis ?? inferBasis(finding.rule)) === "rule") {
+					anchoring.unmatched++;
+				}
+				return finding;
+			}
+
+			if (resolution.source === "rule") anchoring.anchored++;
+			else anchoring.classified++;
+
+			const severity = provenSeverity(finding, resolution);
+			if (severity === finding.severity) return finding;
+
+			anchoring.diverged.push({
+				watchdogId: report.watchdogId,
+				file: finding.file,
+				rule: finding.rule,
+				emitted: finding.severity,
+				resolved: severity,
+				source: resolution.source,
+			});
+			return { ...finding, severity };
+		});
+		anchoring.reports.push({ ...report, findings });
+	}
+
+	return anchoring;
+}
+
+/** Texto curto do finding nas mensagens do finalize. */
+function describe(divergence: SeverityDivergence, max = 72): string {
+	const text =
+		divergence.rule.length <= max
+			? divergence.rule
+			: `${divergence.rule.slice(0, max - 1).trimEnd()}…`;
+	return `· ${divergence.watchdogId} \`${divergence.file}\` — ${divergence.emitted} → ${divergence.resolved} (${divergence.source === "rule" ? "regra" : "impacto"}): ${text}`;
+}
+
+/**
+ * Mensagens de resumo da ancoragem (vazias quando nada foi resolvido nem corrigido).
+ * `limit` controla quantos exemplos de divergência aparecem.
+ */
+export function severityAnchoringMessages(
+	anchoring: SeverityAnchoring,
+	limit = 3,
+): string[] {
+	const messages: string[] = [];
+	if (anchoring.anchored > 0 || anchoring.classified > 0) {
+		const parts = [
+			anchoring.anchored > 0 ? `${anchoring.anchored} pela regra` : "",
+			anchoring.classified > 0 ? `${anchoring.classified} pelo impacto` : "",
+		].filter(Boolean);
+		const corrected =
+			anchoring.diverged.length > 0
+				? ` — ${anchoring.diverged.length} divergência(s) corrigida(s).`
+				: ".";
+		messages.push(`Severidade: ${parts.join(", ")}${corrected}`);
+	}
+	for (const divergence of anchoring.diverged.slice(0, limit)) {
+		messages.push(describe(divergence));
+	}
+	if (anchoring.unmatched > 0) {
+		messages.push(
+			`Severidade: ${anchoring.unmatched} finding(s) de regra sem casamento com as regras declaradas (valor emitido mantido).`,
+		);
+	}
+	return messages;
+}

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

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

@@ -69,7 +69,7 @@ export class SQLiteStorageProvider 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) {
 			// O repo pode ter sido movido; a identidade continua a mesma.
 			const moved =
@@ -102,6 +102,7 @@ export class SQLiteStorageProvider 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,
@@ -113,15 +114,16 @@ export class SQLiteStorageProvider implements StorageProvider {
 		};
 		this.db.run(
 			`INSERT INTO reviews
-				(id, repo_key, repo_root, repo_remote, branch, slug, base, head,
+				(id, repo_key, repo_root, repo_remote, branch, variant, slug, base, head,
 				 worktree_path, pr_number, created_at, updated_at)
-			 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+			 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
 			[
 				record.id,
 				record.repoKey,
 				record.repoRoot,
 				record.repoRemote ?? null,
 				record.branch,
+				record.variant ?? "",
 				record.slug,
 				record.base ?? null,
 				record.head ?? null,
@@ -134,10 +136,12 @@ export class SQLiteStorageProvider implements StorageProvider {
 		return record;
 	}
 
-	findReview(repoKey: string, branch: string): ReviewRecord | null {
+	findReview(repoKey: string, branch: string, variant?: string): ReviewRecord | null {
 		const row = this.db
-			.query("SELECT * FROM reviews WHERE repo_key = ? AND branch = ?")
-			.get(repoKey, branch) as ReviewRow | null;
+			.query(
+				"SELECT * FROM reviews WHERE repo_key = ? AND branch = ? AND variant = ?",
+			)
+			.get(repoKey, branch, variant?.trim() ?? "") as ReviewRow | null;
 		return row ? reviewFromRow(row) : null;
 	}
 
@@ -253,9 +257,10 @@ export class SQLiteStorageProvider implements StorageProvider {
 		const upsert = this.db.query(
 			`INSERT INTO findings
 				(id, review_id, short_id, fingerprint, watchdog_ids, rule, severity,
-				 file, line, message, action, evidence, anchor, found_at_sha, count,
-				 present, decision, comment, exec_state, github, created_at, updated_at)
-			 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+				 file, line, message, action, evidence, scenario, impact, confidence, basis,
+				 anchor, found_at_sha, count, present, decision, comment, exec_state, github,
+				 created_at, updated_at)
+			 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
 			 ON CONFLICT(id) DO UPDATE SET
 				short_id = excluded.short_id,
 				fingerprint = excluded.fingerprint,
@@ -267,6 +272,10 @@ export class SQLiteStorageProvider implements StorageProvider {
 				message = excluded.message,
 				action = excluded.action,
 				evidence = excluded.evidence,
+				scenario = excluded.scenario,
+				impact = excluded.impact,
+				confidence = excluded.confidence,
+				basis = excluded.basis,
 				anchor = excluded.anchor,
 				found_at_sha = excluded.found_at_sha,
 				count = excluded.count,
@@ -325,6 +334,10 @@ export class SQLiteStorageProvider implements StorageProvider {
 					finding.message,
 					finding.action,
 					finding.evidence ?? null,
+					finding.scenario ?? null,
+					finding.impact ?? null,
+					finding.confidence ?? null,
+					finding.basis ?? null,
 					finding.anchor ? JSON.stringify(finding.anchor) : null,
 					finding.foundAtSha ?? null,
 					finding.count,

package/src/core/storage/types.ts

@@ -28,6 +28,13 @@ export type ReviewRecord = {
 	repoRoot: string;
 	repoRemote?: string;
 	branch: string;
+	/**
+	 * Rótulo da variante A/B (ausente = run principal da branch).
+	 *
+	 * Faz parte da identidade junto com `(repoKey, branch)`: permite rodar a
+	 * mesma PR com dois experimentos sem apagar a revisão anterior.
+	 */
+	variant?: string;
 	slug: string;
 	base?: string;
 	head?: string;
@@ -81,6 +88,8 @@ export type CreateReviewInput = {
 	repo: RepoIdentity;
 	branch: string;
 	slug: string;
+	/** Variante A/B (ausente = run principal da branch). */
+	variant?: string;
 	base?: string;
 	head?: string;
 	/** Worktree onde a revisão roda (ausente = clone principal). */
@@ -99,11 +108,11 @@ export type ArtifactKind =
 	| "context"
 	| "context-brief"
 	| "context-summary"
+	| "business"
+	| "business-brief"
 	| "finding-report"
-	| "review"
 	| "resume"
 	| "technical"
-	| "domain-review"
 	| "verify"
 	| "ast"
 	| "ast-impact"
@@ -111,6 +120,9 @@ export type ArtifactKind =
 	| "ai-usage"
 	| "ai-brief"
 	| "hunt"
+	| "prepare"
+	| "compare"
+	| "golden"
 	| "other";
 
 /** Artefato persistido de uma review. */
@@ -142,9 +154,10 @@ export type WriteArtifactInput = {
 export interface StorageProvider {
 	readonly kind: "sqlite" | "file";
 
-	/** Recupera ou cria a review de uma branch (identidade = repo + branch). */
+	/** Busca por identidade `(repo, branch, variante)`; variante ausente = principal. */
+	findReview(repoKey: string, branch: string, variant?: string): ReviewRecord | null;
+	/** Run da branch + variante (cria quando não existe). */
 	getOrCreateReview(input: CreateReviewInput): ReviewRecord;
-	findReview(repoKey: string, branch: string): ReviewRecord | null;
 	getReview(id: string): ReviewRecord | null;
 	/** Reviews do repositório (mais recentes primeiro); sem chave = todas. */
 	listReviews(repoKey?: string): ReviewRecord[];