@payconductor/houndsman 0.13.0 → 0.16.0

package/src/core/commands/compare.ts

@@ -0,0 +1,266 @@
+/**
+ * Comando `compare` (biblioteca) — compara duas runs da mesma branch.
+ *
+ * Resolve o par por slug (como na URL da UI) ou por `(branch, variante)`, lê os
+ * artefatos de cada review e grava `compare-<a>--<b>.md|.json` na run B.
+ */
+
+import {
+	buildComparison,
+	type ComparisonFinding,
+	comparisonToJson,
+	countBySeverity,
+	type ReviewSnapshot,
+	renderComparison,
+} from "../compare";
+import { currentBranch } from "../pr-context";
+import type { RepoIdentity, ReviewRecord, StorageProvider } from "../storage/types";
+import type { Severity } from "../types";
+
+/** Seleção do par A/B. */
+export type CompareOptions = {
+	/** Slugs prontos (como exibidos na UI). */
+	slugA?: string;
+	slugB?: string;
+	/** Identidade alternativa: branch + rótulos de variante. */
+	branch?: string;
+	variantA?: string;
+	variantB?: string;
+};
+
+/** Resultado do comando. */
+export type CompareResult = {
+	markdown: string;
+	json: string;
+	a: ReviewRecord;
+	b: ReviewRecord;
+	artifacts: { markdown: string; json: string };
+};
+
+type ManifestShape = {
+	watchdogs?: { files?: string[]; overflow?: number }[];
+	ai?: { model?: string };
+};
+
+type ReportShape = { durationMs?: number };
+type HuntShape = {
+	model?: string;
+	durationMs?: number;
+	businessScore?: number;
+	totals?: { totalTokens?: number; costUsd?: number };
+	watchdogs?: {
+		checks?: {
+			expected?: number;
+			verified?: number;
+			missing?: number;
+			gaps?: number;
+		};
+		coverage?: { reviewed?: number; skipped?: number; undeclared?: number };
+		checklist?: { costUsd?: number };
+		secondOpinion?: { costUsd?: number; findings?: number };
+	}[];
+};
+type AiUsageShape = { total?: { totalTokens?: number } };
+
+/** Agrega o diagnóstico do `hunt-report.json` (checklist + cobertura declarada). */
+function harnessOf(hunt: HuntShape): NonNullable<ReviewSnapshot["harness"]> {
+	const watchdogs = hunt.watchdogs ?? [];
+	const sum = (pick: (item: (typeof watchdogs)[number]) => number | undefined) =>
+		watchdogs.reduce((total, item) => total + (pick(item) ?? 0), 0);
+	return {
+		checksExpected: sum((item) => item.checks?.expected),
+		checksVerified: sum((item) => item.checks?.verified),
+		checksGaps: sum((item) => item.checks?.gaps),
+		reviewedFiles: sum((item) => item.coverage?.reviewed),
+		skippedFiles: sum((item) => item.coverage?.skipped),
+		undeclaredFiles: sum((item) => item.coverage?.undeclared),
+		businessScore: hunt.businessScore,
+		extraCostUsd:
+			sum((item) => item.checklist?.costUsd) +
+			sum((item) => item.secondOpinion?.costUsd),
+		secondOpinionFindings: sum((item) => item.secondOpinion?.findings),
+	};
+}
+
+/** Resolve a run pelo slug dentro do repositório. */
+function bySlug(
+	storage: StorageProvider,
+	repo: RepoIdentity,
+	slug: string,
+): ReviewRecord {
+	const review = storage
+		.listReviews(repo.key)
+		.find((candidate) => candidate.slug === slug);
+	if (!review) throw new Error(`Nenhuma run com slug '${slug}' neste repositório.`);
+	return review;
+}
+
+/** Resolve o par A/B (slug ou branch + variantes). */
+export function resolveComparePair(
+	storage: StorageProvider,
+	repo: RepoIdentity,
+	options: CompareOptions,
+): [ReviewRecord, ReviewRecord] {
+	if (options.slugA && options.slugB) {
+		return [
+			bySlug(storage, repo, options.slugA),
+			bySlug(storage, repo, options.slugB),
+		];
+	}
+	const branch = options.branch ?? currentBranch();
+	const variantB = options.variantB?.trim();
+	if (!variantB) {
+		throw new Error(
+			"Informe --b <variante> (ou passe dois slugs: `houndsman compare <a> <b>`).",
+		);
+	}
+	const a = storage.findReview(repo.key, branch, options.variantA);
+	const b = storage.findReview(repo.key, branch, variantB);
+	if (!a) {
+		throw new Error(
+			`Nenhuma revisão para '${branch}'${options.variantA ? ` (variante '${options.variantA}')` : ""}.`,
+		);
+	}
+	if (!b) throw new Error(`Nenhuma revisão para '${branch}' (variante '${variantB}').`);
+	return [a, b];
+}
+
+function readJson<T>(storage: StorageProvider, reviewId: string, name: string): T | null {
+	const artifact = storage.readArtifact(reviewId, name);
+	if (!artifact) return null;
+	try {
+		return JSON.parse(artifact.content) as T;
+	} catch {
+		return null;
+	}
+}
+
+/** Extrai o snapshot comparável de uma run. */
+function snapshotOf(
+	storage: StorageProvider,
+	review: ReviewRecord,
+	label: string,
+): ReviewSnapshot {
+	const state = storage.readFindings(review.id);
+	const findings: ComparisonFinding[] = Object.values(state?.findings ?? {})
+		.filter((finding) => finding.present)
+		.map((finding) => ({
+			fingerprint: finding.fingerprint,
+			rule: finding.rule,
+			severity: finding.severity,
+			file: finding.file,
+			line: finding.line ?? undefined,
+			message: finding.message,
+			watchdogs: finding.watchdogIds,
+		}));
+
+	const manifest = readJson<ManifestShape>(storage, review.id, "manifest.json");
+	const prepare = readJson<ReportShape>(storage, review.id, "prepare-report.json");
+	const hunt = readJson<HuntShape>(storage, review.id, "hunt-report.json");
+	const aiUsage = readJson<AiUsageShape>(storage, review.id, "ai-usage.json");
+
+	const started = review.startedAt ? Date.parse(review.startedAt) : Number.NaN;
+	const reviewed = review.reviewedAt ? Date.parse(review.reviewedAt) : Number.NaN;
+	const durationMs =
+		Number.isFinite(started) && Number.isFinite(reviewed) && reviewed >= started
+			? reviewed - started
+			: undefined;
+
+	const watchdogs = manifest?.watchdogs ?? [];
+	// Domínios se sobrepõem: conta arquivos únicos, não "slots" por watchdog.
+	const files = new Set<string>();
+	for (const watchdog of watchdogs) {
+		for (const file of watchdog.files ?? []) files.add(file);
+	}
+	return {
+		label,
+		slug: review.slug,
+		branch: review.branch,
+		variant: review.variant,
+		headSha: review.headSha ?? review.reviewedSha,
+		model: hunt?.model ?? manifest?.ai?.model,
+		findings,
+		bySeverity: countBySeverity(findings),
+		harness: hunt ? harnessOf(hunt) : undefined,
+		coverage: {
+			watchdogs: watchdogs.length,
+			files: files.size,
+			overflow: watchdogs.reduce(
+				(total, watchdog) => total + (watchdog.overflow ?? 0),
+				0,
+			),
+		},
+		durationMs,
+		prepareMs: prepare?.durationMs,
+		huntMs: hunt?.durationMs,
+		tokens: hunt?.totals?.totalTokens ?? aiUsage?.total?.totalTokens,
+		costUsd: hunt?.totals?.costUsd,
+	};
+}
+
+/** Executa a comparação e persiste o relatório na run B. */
+export function runCompare(
+	storage: StorageProvider,
+	repo: RepoIdentity,
+	options: CompareOptions,
+): CompareResult {
+	const [a, b] = resolveComparePair(storage, repo, options);
+	const comparison = buildComparison(
+		snapshotOf(storage, a, "A"),
+		snapshotOf(storage, b, "B"),
+	);
+	const markdown = renderComparison(comparison);
+	const json = comparisonToJson(comparison);
+	const base = `compare-${a.slug}--${b.slug}`;
+	storage.writeArtifact(b.id, {
+		name: `${base}.md`,
+		kind: "compare",
+		content: markdown,
+	});
+	storage.writeArtifact(b.id, {
+		name: `${base}.json`,
+		kind: "compare",
+		content: json,
+	});
+	return {
+		markdown,
+		json,
+		a,
+		b,
+		artifacts: { markdown: `${base}.md`, json: `${base}.json` },
+	};
+}
+
+/** Linha da listagem de variantes da branch. */
+export type CompareListItem = {
+	slug: string;
+	branch: string;
+	variant?: string;
+	status: ReviewRecord["status"];
+	findings: number;
+	bySeverity: Record<Severity, number>;
+	updatedAt: string;
+};
+
+/** Lista as runs do repositório (filtra por branch quando informado). */
+export function listRunsForCompare(
+	storage: StorageProvider,
+	repo: RepoIdentity,
+	branch?: string,
+): CompareListItem[] {
+	return storage
+		.listReviews(repo.key)
+		.filter((review) => !branch || review.branch === branch)
+		.map((review) => {
+			const snapshot = snapshotOf(storage, review, review.variant ?? "principal");
+			return {
+				slug: review.slug,
+				branch: review.branch,
+				variant: review.variant,
+				status: review.status,
+				findings: snapshot.findings.length,
+				bySeverity: snapshot.bySeverity,
+				updatedAt: review.updatedAt,
+			};
+		});
+}

package/src/core/commands/context.ts

@@ -12,7 +12,7 @@ import {
 	type PrContextRaw,
 	renderContextBrief,
 } from "../pr-context";
-import { sanitizeBranch } from "../report-builder";
+import { reviewSlug } from "../report-builder";
 import type { RepoIdentity, StorageProvider } from "../storage/types";
 import { type ContextPaths, ReviewWorkArea } from "../storage/work-area";
 
@@ -28,6 +28,8 @@ export function runContextCommand(
 	repo: RepoIdentity,
 	opts: {
 		branch?: string;
+		/** Variante A/B da run (ausente = principal). */
+		variant?: string;
 		/** Worktree onde a review roda (persistido na review). */
 		worktreePath?: string;
 		/** PR de origem (persistida na review). */
@@ -35,10 +37,12 @@ export function runContextCommand(
 	} = {},
 ): ContextRunResult {
 	const branch = opts.branch ?? currentBranch();
+	const variant = opts.variant?.trim() || undefined;
 	const review = storage.getOrCreateReview({
 		repo,
 		branch,
-		slug: sanitizeBranch(branch),
+		variant,
+		slug: reviewSlug(branch, variant),
 		worktreePath: opts.worktreePath,
 		prNumber: opts.prNumber,
 	});

package/src/core/commands/findings.ts

@@ -14,6 +14,7 @@ import { existsSync } from "node:fs";
 import { AiClient } from "../ai/ai-client";
 import { AiVerifier } from "../ai/features/verifier";
 import { type HoundsmanConfig, resolveJevConcurrency } from "../config";
+import { type ReviewContext, reviewContext } from "../engine/review-context";
 import { ENV_NAMES } from "../env";
 import {
 	applyFindingUpdate,
@@ -25,7 +26,6 @@ import {
 	type FindingsFilter,
 	type FindingsStateFile,
 	type FindingUpdate,
-	fileReader,
 	filterFindings,
 	reorder,
 	resolveFindingId,
@@ -51,9 +51,9 @@ import { VerifyPresenter } from "../renderers/verify-presenter";
 import { pingFindingsStatus } from "../run-status";
 import { systemClock } from "../services/clock";
 import { FixBatchBuilder } from "../services/fix-batch-builder";
+import type { GitRepository } from "../services/git-repository";
 import { Verifier } from "../services/verifier";
-import type { RepoIdentity, ReviewRecord, StorageProvider } from "../storage/types";
-import { ReviewWorkArea } from "../storage/work-area";
+import type { RepoIdentity, StorageProvider } from "../storage/types";
 import { SEVERITY_ORDER, type Severity } from "../types";
 
 export type FindingsCommandResult = {
@@ -68,6 +68,7 @@ const VALUE_FLAGS = new Set([
 	"--severity",
 	"--file",
 	"--branch",
+	"--variant",
 	"--limit",
 	"--comment",
 	"--by",
@@ -108,13 +109,11 @@ function parseArgs(args: string[]): ParsedArgs {
 	return parsed;
 }
 
-/** Contexto de uma review (storage + registro + staging + raiz). */
-type CommandContext = {
-	storage: StorageProvider;
-	review: ReviewRecord;
-	work: ReviewWorkArea;
-	/** Worktree da review quando existir; senão, a raiz do repositório. */
-	root: string;
+/** Opções de resolução do contexto (o CLI passa root/git do engine). */
+export type FindingsContextOptions = {
+	/** Raiz operacional (default: cwd de quem chamou). */
+	root?: string;
+	git?: GitRepository;
 };
 
 /** Resolve a review da branch atual (explícita ou via git). */
@@ -122,22 +121,25 @@ function openContext(
 	storage: StorageProvider,
 	repo: RepoIdentity,
 	parsed: ParsedArgs,
-): CommandContext {
+	options: FindingsContextOptions = {},
+): ReviewContext {
 	const branch = parsed.values["--branch"] ?? currentBranch();
-	const review = storage.findReview(repo.key, branch);
+	const variant = parsed.values["--variant"]?.trim() || undefined;
+	const review = storage.findReview(repo.key, branch, variant);
 	if (!review) {
 		throw new Error(
-			`Nenhuma revisão para '${branch}'. Rode \`houndsman --finalize\` primeiro.`,
+			`Nenhuma revisão para '${branch}'${variant ? ` (variante '${variant}')` : ""}. Rode \`houndsman --finalize\` primeiro.`,
 		);
 	}
 	const worktree = review.worktreePath;
 	// Sem worktree, mantém a raiz onde o comando foi invocado (comportamento histórico).
-	const root = worktree && existsSync(worktree) ? worktree : process.cwd();
-	return { storage, review, work: new ReviewWorkArea(review), root };
+	const root =
+		worktree && existsSync(worktree) ? worktree : (options.root ?? process.cwd());
+	return reviewContext(storage, review, { root, git: options.git });
 }
 
 /** Lê o estado de triagem; lança se a review ainda não tem findings. */
-function loadState(ctx: CommandContext): FindingsStateFile {
+function loadState(ctx: ReviewContext): FindingsStateFile {
 	const state = ctx.storage.readFindings(ctx.review.id);
 	if (!state) {
 		throw new Error(
@@ -149,7 +151,7 @@ function loadState(ctx: CommandContext): FindingsStateFile {
 
 /** Lê-modifica-grava o estado, atualizando `updatedAt` e a ordem. */
 function mutateState(
-	ctx: CommandContext,
+	ctx: ReviewContext,
 	mutator: (state: FindingsStateFile) => void,
 ): FindingsStateFile {
 	const state = loadState(ctx);
@@ -221,7 +223,7 @@ function filterFrom(parsed: ParsedArgs): FindingsFilter {
 }
 
 /** Faz ping no status da review (derivado do estado atual) após uma mutação. */
-function pingStatus(ctx: CommandContext, state: FindingsStateFile): void {
+function pingStatus(ctx: ReviewContext, state: FindingsStateFile): void {
 	pingFindingsStatus(ctx.storage, ctx.review.id, state);
 }
 
@@ -230,7 +232,7 @@ function pingStatus(ctx: CommandContext, state: FindingsStateFile): void {
  * Fail-open (`gh` ausente/sem PR ⇒ só a mensagem). Devolve a linha para o
  * output ou `null` quando não há vínculo remoto pendente.
  */
-function syncThreadsOutput(ctx: CommandContext, ids: readonly string[]): string | null {
+function syncThreadsOutput(ctx: ReviewContext, ids: readonly string[]): string | null {
 	if (ids.length === 0) return null;
 	const state = loadState(ctx);
 	const outcome = syncResolvedThreads({ state, ids });
@@ -246,7 +248,7 @@ function syncThreadsOutput(ctx: CommandContext, ids: readonly string[]): string
 
 /** Aplica uma atualização a um finding e persiste. */
 function updateOne(
-	ctx: CommandContext,
+	ctx: ReviewContext,
 	input: string,
 	update: FindingUpdate,
 ): FindingState {
@@ -261,7 +263,7 @@ function updateOne(
 
 /** Aplica a mesma atualização a vários ids (done/reset). */
 function updateMany(
-	ctx: CommandContext,
+	ctx: ReviewContext,
 	inputs: string[],
 	update: FindingUpdate,
 ): FindingState[] {
@@ -281,10 +283,11 @@ export function runFindingsCommand(
 	storage: StorageProvider,
 	repo: RepoIdentity,
 	args: string[],
+	options: FindingsContextOptions = {},
 ): FindingsCommandResult {
 	try {
 		const parsed = parseArgs(args);
-		return execute(config, storage, repo, parsed);
+		return execute(config, storage, repo, parsed, options);
 	} catch (error) {
 		return {
 			output: error instanceof Error ? error.message : String(error),
@@ -298,8 +301,9 @@ function execute(
 	storage: StorageProvider,
 	repo: RepoIdentity,
 	parsed: ParsedArgs,
+	options: FindingsContextOptions,
 ): FindingsCommandResult {
-	const ctx = openContext(storage, repo, parsed);
+	const ctx = openContext(storage, repo, parsed, options);
 	switch (parsed.sub ?? "list") {
 		case "list": {
 			const state = loadState(ctx);
@@ -386,7 +390,7 @@ function execute(
 		}
 		case "sync": {
 			const state = loadState(ctx);
-			const result = syncState(state, fileReader(ctx.root));
+			const result = syncState(state, ctx.files.reader());
 			ctx.storage.writeFindings(ctx.review.id, state);
 			pingStatus(ctx, state);
 			const output = parsed.bools.has("--json")
@@ -483,10 +487,11 @@ export async function runVerifyCommand(
 	storage: StorageProvider,
 	repo: RepoIdentity,
 	args: string[],
+	options: FindingsContextOptions = {},
 ): Promise<FindingsCommandResult> {
 	try {
 		const parsed = parseArgs(args);
-		return await executeVerify(config, storage, repo, parsed);
+		return await executeVerify(config, storage, repo, parsed, options);
 	} catch (error) {
 		return {
 			output: error instanceof Error ? error.message : String(error),
@@ -514,8 +519,9 @@ async function executeVerify(
 	storage: StorageProvider,
 	repo: RepoIdentity,
 	parsed: ParsedArgs,
+	options: FindingsContextOptions,
 ): Promise<FindingsCommandResult> {
-	const ctx = openContext(storage, repo, parsed);
+	const ctx = openContext(storage, repo, parsed, options);
 	const state = loadState(ctx);
 
 	// Lazy: `../jev` (axios) só entra no caminho do verify.
@@ -523,7 +529,7 @@ async function executeVerify(
 	const { JevCandidatesStore, JevClient, JevVerifier } = await import("../jev");
 
 	const findings = verifier.select(state, filterFrom(parsed));
-	const entries = verifier.verifyLocal(findings, fileReader(ctx.root));
+	const entries = verifier.verifyLocal(findings, ctx.files.reader());
 
 	// Tier 1 — Jev só nos ambíguos (fail-open: sem chave/erro mantém o provisório).
 	let jevChecked = 0;
@@ -571,7 +577,7 @@ async function executeVerify(
 		} else if (!aiVerifier.enabled) {
 			aiReason = "feature ai.features.verify desligada";
 		} else {
-			const readFile = fileReader(ctx.root);
+			const readFile = ctx.files.reader();
 			const byId = new Map(findings.map((finding) => [finding.id, finding]));
 			const confidence = await aiVerifier.verify({
 				findings: stillAmbiguous.map((entry) => ({
@@ -748,10 +754,11 @@ export async function runSubmitCommand(
 	storage: StorageProvider,
 	repo: RepoIdentity,
 	args: string[],
+	options: FindingsContextOptions = {},
 ): Promise<FindingsCommandResult> {
 	try {
 		const parsed = parseArgs(args);
-		return await executeSubmit(config, storage, repo, parsed);
+		return await executeSubmit(config, storage, repo, parsed, options);
 	} catch (error) {
 		return {
 			output: error instanceof Error ? error.message : String(error),
@@ -765,8 +772,9 @@ async function executeSubmit(
 	storage: StorageProvider,
 	repo: RepoIdentity,
 	parsed: ParsedArgs,
+	options: FindingsContextOptions,
 ): Promise<FindingsCommandResult> {
-	const ctx = openContext(storage, repo, parsed);
+	const ctx = openContext(storage, repo, parsed, options);
 	const state = loadState(ctx);
 	const selection = submitSelection(parsed);
 	const target = resolvePrTarget(defaultGhRunner, state.branch);

package/src/core/commands/golden.ts

@@ -0,0 +1,176 @@
+/**
+ * Comando `golden` (biblioteca) — avalia runs contra defeitos congelados.
+ *
+ * A contagem de findings de duas variantes nunca é comparável: cada execução
+ * amostra pontos diferentes do mesmo diff. Com um golden set (arquivo do
+ * consumidor), a comparação vira recall/precisão sobre os defeitos que já
+ * foram confirmados no código.
+ */
+
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import {
+	commitMatches,
+	type GoldenFinding,
+	type GoldenRunScore,
+	type GoldenSet,
+	goldenToJson,
+	parseGoldenSet,
+	renderGoldenReport,
+	scoreGolden,
+} from "../golden";
+import { normalizePath } from "../hunt/review-checks";
+import { currentBranch } from "../pr-context";
+import type { RepoIdentity, ReviewRecord, StorageProvider } from "../storage/types";
+
+/** Seleção das runs a avaliar. */
+export type GoldenOptions = {
+	/** Caminho do arquivo de golden set. */
+	file: string;
+	/** Branch alvo (default: a atual). */
+	branch?: string;
+	/** Rótulo da variante; ausente = todas as runs da branch. */
+	variant?: string;
+	/** Slug explícito (vence `variant`). */
+	slug?: string;
+};
+
+/** Resultado do comando. */
+export type GoldenResult = {
+	markdown: string;
+	json: string;
+	set: GoldenSet;
+	runs: GoldenRunScore[];
+	/** Run onde o relatório foi gravado (a mais recente avaliada). */
+	target: ReviewRecord;
+	artifacts?: { markdown: string; json: string };
+};
+
+/** Lê e valida o arquivo de golden set. */
+export function loadGoldenSet(file: string): {
+	set: GoldenSet;
+	warnings: string[];
+} {
+	let content: string;
+	try {
+		content = readFileSync(resolve(file), "utf8");
+	} catch (error) {
+		throw new Error(
+			`Golden set ilegível: ${error instanceof Error ? error.message : String(error)}`,
+		);
+	}
+	let raw: unknown;
+	try {
+		raw = JSON.parse(content);
+	} catch {
+		throw new Error(`Golden set não é JSON válido: ${file}`);
+	}
+	const parsed = parseGoldenSet(raw);
+	if (!parsed.set) {
+		throw new Error(
+			`Golden set inválido (${file}): ${parsed.warnings.join(" ")}`.trim(),
+		);
+	}
+	return { set: parsed.set, warnings: parsed.warnings };
+}
+
+/** Findings presentes de uma run, no formato da avaliação. */
+export function goldenFindingsOf(
+	storage: StorageProvider,
+	review: ReviewRecord,
+): GoldenFinding[] {
+	const state = storage.readFindings(review.id);
+	return Object.values(state?.findings ?? {})
+		.filter((finding) => finding.present)
+		.map((finding) => ({
+			fingerprint: finding.fingerprint,
+			file: normalizePath(finding.file),
+			line: finding.line ?? undefined,
+			rule: finding.rule,
+			severity: finding.severity,
+			message: finding.message,
+			evidence: finding.evidence,
+			watchdogs: finding.watchdogIds,
+		}));
+}
+
+/** Runs alvo: slug > variante > todas as da branch. */
+function selectReviews(
+	storage: StorageProvider,
+	repo: RepoIdentity,
+	options: GoldenOptions,
+): ReviewRecord[] {
+	const reviews = storage.listReviews(repo.key);
+	if (options.slug) {
+		const found = reviews.find((review) => review.slug === options.slug);
+		if (!found) {
+			throw new Error(`Nenhuma run com slug '${options.slug}' neste repositório.`);
+		}
+		return [found];
+	}
+
+	const branch = options.branch ?? currentBranch();
+	const ofBranch = reviews.filter((review) => review.branch === branch);
+	const variant = options.variant?.trim();
+	const selected = variant
+		? ofBranch.filter((review) => review.variant === variant)
+		: ofBranch;
+	if (selected.length === 0) {
+		throw new Error(
+			`Nenhuma revisão para '${branch}'${variant ? ` (variante '${variant}')` : ""}.`,
+		);
+	}
+	return selected;
+}
+
+/** Rótulo curto da run (`otimizado-4` ou `principal`). */
+function labelOf(review: ReviewRecord): string {
+	return review.variant?.trim() || "principal";
+}
+
+/** Executa a avaliação e grava o relatório na run mais recente selecionada. */
+export function runGolden(
+	storage: StorageProvider,
+	repo: RepoIdentity,
+	options: GoldenOptions,
+): GoldenResult {
+	const { set } = loadGoldenSet(options.file);
+	const reviews = selectReviews(storage, repo, options);
+	const runs: GoldenRunScore[] = reviews.map((review) => {
+		const findings = goldenFindingsOf(storage, review);
+		const commit = review.headSha ?? review.reviewedSha;
+		return {
+			slug: review.slug,
+			label: labelOf(review),
+			variant: review.variant,
+			scope: review.branch,
+			commit,
+			commitMismatch: !commitMatches(set.commit, commit),
+			findings: findings.length,
+			score: scoreGolden(set, findings),
+		};
+	});
+
+	const markdown = renderGoldenReport(set, runs);
+	const json = goldenToJson(set, runs);
+	const target = reviews[0];
+	const base = `golden-${target.slug}`;
+	storage.writeArtifact(target.id, {
+		name: `${base}.md`,
+		kind: "golden",
+		content: markdown,
+	});
+	storage.writeArtifact(target.id, {
+		name: `${base}.json`,
+		kind: "golden",
+		content: json,
+	});
+	return {
+		markdown,
+		json,
+		set,
+		runs,
+		target,
+		artifacts: { markdown: `${base}.md`, json: `${base}.json` },
+	};
+}