@payconductor/houndsman 0.2.0 → 0.4.0

package/src/core/commands/findings.ts

@@ -1,24 +1,18 @@
 /**
  * Subcomando `findings` — triagem dos findings da revisão (biblioteca).
  *
- * Lê/grava o `state.json` da run (`findings-state.ts`). Devolve o texto pronto
- * (markdown ou JSON) + exit code; o CLI decide o log/exit. O agente do usuário
- * usa `list`/`set`/`done` (e `batch` para lotes de correção) para interagir sem abrir o JSON à mão.
+ * Lê/grava o estado de triagem no storage (SQLite por default). Devolve o texto
+ * pronto (markdown ou JSON) + exit code; o CLI decide o log/exit. O agente do
+ * usuário usa `list`/`set`/`done` (e `batch` para lotes de correção) para
+ * interagir sem abrir o banco à mão.
  *
- * Se o `state.json` não existir, é re-construído a partir de
- * `findings/*.json` + `classification.json` (não exige `--finalize`).
+ * Ids aceitam prefixo único (exato primeiro) — útil porque o id curto convive
+ * com o UUID interno no banco.
  */
 
-import { writeFileSync } from "node:fs";
-import { join } from "node:path";
-import {
-	type HoundsmanConfig,
-	resolveArtifactDir,
-	resolveJevConcurrency,
-} from "../config";
+import { type HoundsmanConfig, resolveJevConcurrency } from "../config";
 import {
 	applyFindingUpdate,
-	buildStateFromRunDir,
 	FINDING_DECISIONS,
 	FINDING_EXEC_STATES,
 	type FindingDecision,
@@ -26,16 +20,14 @@ import {
 	type FindingState,
 	type FindingsFilter,
 	type FindingsStateFile,
-	FindingsStateStore,
-	type FindingsSummary,
 	type FindingUpdate,
 	fileReader,
 	filterFindings,
-	runDir,
+	reorder,
+	resolveFindingId,
 	summarize,
 	syncState,
 } from "../findings-state";
-import { buildFixBatch, type FixBatchResult } from "../fix-batch";
 import {
 	buildSubmitPreview,
 	defaultGhRunner,
@@ -45,13 +37,18 @@ import {
 	type SubmitSelection,
 	submitFindings,
 } from "../github-review";
-import { relFromRoot, VERIFY_FILE } from "../paths";
+import { VERIFY_FILE } from "../paths";
 import { currentBranch } from "../pr-context";
+import { BatchPresenter } from "../renderers/batch-presenter";
+import { FindingsPresenter } from "../renderers/findings-presenter";
+import { VerifyPresenter } from "../renderers/verify-presenter";
 import { pingFindingsStatus } from "../run-status";
-import { SEVERITY_EMOJI, SEVERITY_ORDER, type Severity } from "../types";
-// Tipos são apagados no transpile (custo zero). Os **valores** de `../verify` e de
-// `../jev` (axios) entram por import dinâmico — só o subcomando `verify` os usa.
-import type { VerifyEntry, VerifyStatus, VerifySummary } from "../verify";
+import { systemClock } from "../services/clock";
+import { FixBatchBuilder } from "../services/fix-batch-builder";
+import { Verifier } from "../services/verifier";
+import type { RepoIdentity, ReviewRecord, StorageProvider } from "../storage/types";
+import { ReviewWorkArea } from "../storage/work-area";
+import { SEVERITY_ORDER, type Severity } from "../types";
 
 export type FindingsCommandResult = {
 	output: string;
@@ -65,7 +62,6 @@ const VALUE_FLAGS = new Set([
 	"--severity",
 	"--file",
 	"--branch",
-	"--dir",
 	"--limit",
 	"--comment",
 	"--by",
@@ -85,6 +81,11 @@ function parseArgs(args: string[]): ParsedArgs {
 	const parsed: ParsedArgs = { positionals: [], values: {}, bools: new Set() };
 	for (let i = 0; i < args.length; i++) {
 		const arg = args[i];
+		if (arg === "--dir") {
+			throw new Error(
+				"--dir foi removido; configure `storage` no houndsman.config.ts.",
+			);
+		}
 		if (arg.startsWith("--")) {
 			if (VALUE_FLAGS.has(arg)) {
 				const value = args[i + 1];
@@ -101,123 +102,76 @@ function parseArgs(args: string[]): ParsedArgs {
 	return parsed;
 }
 
-/** Diretório da run + branch resolvida. */
-function resolveDir(
-	config: HoundsmanConfig,
-	parsed: ParsedArgs,
-): { dir: string; branch: string } {
-	return {
-		dir: parsed.values["--dir"] ?? resolveArtifactDir(config),
-		branch: parsed.values["--branch"] ?? currentBranch(),
-	};
-}
+/** Contexto de uma review (storage + registro + staging). */
+type CommandContext = {
+	storage: StorageProvider;
+	review: ReviewRecord;
+	work: ReviewWorkArea;
+};
 
-/** Lê o estado da run; reconstrói dos findings se ausente. Lança se impossível. */
-function loadState(config: HoundsmanConfig, parsed: ParsedArgs): FindingsStateFile {
-	const { dir, branch } = resolveDir(config, parsed);
-	const store = FindingsStateStore.at(dir, branch);
-	const existing = store.read();
-	if (existing) return existing;
-
-	const built = buildStateFromRunDir(
-		runDir(dir, branch),
-		branch,
-		fileReader(process.cwd()),
-	);
-	if (!built) {
+/** Resolve a review da branch atual (explícita ou via git). */
+function openContext(
+	storage: StorageProvider,
+	repo: RepoIdentity,
+	parsed: ParsedArgs,
+): CommandContext {
+	const branch = parsed.values["--branch"] ?? currentBranch();
+	const review = storage.findReview(repo.key, branch);
+	if (!review) {
 		throw new Error(
-			`Nenhum estado de triagem para '${branch}'. Rode \`houndsman --finalize\` primeiro.`,
+			`Nenhuma revisão para '${branch}'. Rode \`houndsman --finalize\` primeiro.`,
 		);
 	}
-	store.write(built);
-	return built;
+	return { storage, review, work: new ReviewWorkArea(review) };
 }
 
-// ---------------------------------------------------------------------------
-// Render
-// ---------------------------------------------------------------------------
-
-function decisionLabel(decision: FindingDecision): string {
-	return decision;
+/** Lê o estado de triagem; lança se a review ainda não tem findings. */
+function loadState(ctx: CommandContext): FindingsStateFile {
+	const state = ctx.storage.readFindings(ctx.review.id);
+	if (!state) {
+		throw new Error(
+			`Nenhum estado de triagem para '${ctx.review.branch}'. Rode \`houndsman --finalize\` primeiro.`,
+		);
+	}
+	return state;
 }
 
-/** Uma linha compacta por finding (uso no agente). */
-function renderFindingLine(finding: FindingState): string[] {
-	const emoji = SEVERITY_EMOJI[finding.severity];
-	const location = finding.line ? `${finding.file}:${finding.line}` : finding.file;
-	const flags = `${decisionLabel(finding.decision)}/${finding.execState}`;
-	const count = finding.count > 1 ? ` ×${finding.count}` : "";
-	const lines = [
-		`- \`${finding.id}\` ${emoji} **${finding.severity}** \`${location}\` — ${finding.rule}${count}`,
-		`  ${finding.message}`,
-		`  _${flags}_ · watchdogs: ${finding.watchdogIds.join(", ") || "—"}`,
-	];
-	if (finding.comment) lines.push(`  **Comentário:** ${finding.comment}`);
-	return lines;
+/** Lê-modifica-grava o estado, atualizando `updatedAt` e a ordem. */
+function mutateState(
+	ctx: CommandContext,
+	mutator: (state: FindingsStateFile) => void,
+): FindingsStateFile {
+	const state = loadState(ctx);
+	mutator(state);
+	state.updatedAt = systemClock();
+	reorder(state);
+	ctx.storage.writeFindings(ctx.review.id, state);
+	return state;
 }
 
-function renderList(state: FindingsStateFile, findings: FindingState[]): string {
-	if (findings.length === 0) return "Nenhum finding para o filtro informado.";
-	const lines = [`# Findings — ${state.branch} (${findings.length})`, ""];
-	for (const finding of findings) lines.push(...renderFindingLine(finding));
-	return lines.join("\n");
+/** Resolve um id (exato ou prefixo único), lançando erro explicativo. */
+function requireFindingId(state: FindingsStateFile, input: string): string {
+	const resolution = resolveFindingId(state, input);
+	if (resolution.status === "found") return resolution.id;
+	if (resolution.status === "ambiguous") {
+		throw new Error(
+			`Id '${input}' ambíguo — candidatos: ${resolution.matches.join(", ")}.`,
+		);
+	}
+	throw new Error(`Finding '${input}' não encontrado.`);
 }
 
-function renderSummary(state: FindingsStateFile, summary: FindingsSummary): string {
-	const decisions = FINDING_DECISIONS.map((d) => `${d} ${summary.byDecision[d]}`).join(
-		" · ",
-	);
-	const exec = FINDING_EXEC_STATES.map((e) => `${e} ${summary.byExecState[e]}`).join(
-		" · ",
-	);
-	const severities = SEVERITY_ORDER.map((s) => `${s} ${summary.bySeverity[s]}`).join(
-		" · ",
-	);
-	return [
-		`# Triagem — ${state.branch}`,
-		"",
-		`Total: ${summary.total} (presentes: ${summary.present})`,
-		`Decisões: ${decisions}`,
-		`Execução: ${exec}`,
-		`Severidade: ${severities}`,
-	].join("\n");
-}
+// ---------------------------------------------------------------------------
+// Apresentação
+// ---------------------------------------------------------------------------
 
-/** Mix de severidade compacto (ex.: `❌1 ⚠️2`). */
-function severityBreakdown(bySeverity: Record<Severity, number>): string {
-	return SEVERITY_ORDER.filter((severity) => bySeverity[severity] > 0)
-		.map((severity) => `${SEVERITY_EMOJI[severity]}${bySeverity[severity]}`)
-		.join(" ");
-}
+const presenters = {
+	findings: new FindingsPresenter(),
+	batch: new BatchPresenter(),
+	verify: new VerifyPresenter(),
+};
 
-/** Render do lote de correção: grupo atual paginado + outros grupos. */
-function renderBatch(result: FixBatchResult): string {
-	const { dimension, current, others, totals } = result;
-	if (totals.queue === 0) return "Nenhum finding pendente de correção.";
-
-	const lines = [
-		`# Lote de correção — agrupado por ${dimension} (${totals.groups} grupo(s))`,
-		"",
-		`## Grupo atual — ${current.key} (${current.total} finding(s), mostrando ${current.returned})`,
-	];
-	for (const finding of current.findings) lines.push(...renderFindingLine(finding));
-	if (current.remaining > 0) {
-		lines.push("", `_… +${current.remaining} neste grupo (use \`--offset\`)._`);
-	}
-	if (others.length > 0) {
-		lines.push("", "## Outros grupos disponíveis");
-		for (const group of others) {
-			lines.push(
-				`- ${group.key} — ${group.count} (${severityBreakdown(group.bySeverity)})`,
-			);
-		}
-	}
-	lines.push(
-		"",
-		`fila: ${totals.queue} · retornados: ${totals.returned} · grupos: ${totals.groups}`,
-	);
-	return lines.join("\n");
-}
+const fixBatchBuilder = new FixBatchBuilder();
 
 // ---------------------------------------------------------------------------
 // Execução
@@ -255,64 +209,52 @@ function filterFrom(parsed: ParsedArgs): FindingsFilter {
 	};
 }
 
-/** Faz ping no `run.json` (status derivado do estado atual) após uma mutação. */
-function pingStatus(config: HoundsmanConfig, parsed: ParsedArgs): void {
-	const { dir, branch } = resolveDir(config, parsed);
-	const state = FindingsStateStore.at(dir, branch).read();
-	if (state) pingFindingsStatus(runDir(dir, branch), state);
+/** Faz ping no status da review (derivado do estado atual) após uma mutação. */
+function pingStatus(ctx: CommandContext, state: FindingsStateFile): void {
+	pingFindingsStatus(ctx.storage, ctx.review.id, state);
 }
 
 /** Aplica uma atualização a um finding e persiste. */
 function updateOne(
-	config: HoundsmanConfig,
-	parsed: ParsedArgs,
-	id: string,
+	ctx: CommandContext,
+	input: string,
 	update: FindingUpdate,
 ): FindingState {
-	const { dir, branch } = resolveDir(config, parsed);
-	const store = FindingsStateStore.at(dir, branch);
 	let updated: FindingState | undefined;
-	store.update((state) => {
-		const finding = state.findings[id];
-		if (!finding) return;
-		updated = applyFindingUpdate(finding, update);
+	mutateState(ctx, (state) => {
+		const id = requireFindingId(state, input);
+		updated = applyFindingUpdate(state.findings[id], update);
 	});
-	if (!updated) throw new Error(`Finding '${id}' não encontrado.`);
+	if (!updated) throw new Error(`Finding '${input}' não encontrado.`);
 	return updated;
 }
 
 /** Aplica a mesma atualização a vários ids (done/reset). */
 function updateMany(
-	config: HoundsmanConfig,
-	parsed: ParsedArgs,
-	ids: string[],
+	ctx: CommandContext,
+	inputs: string[],
 	update: FindingUpdate,
 ): FindingState[] {
-	const { dir, branch } = resolveDir(config, parsed);
-	const store = FindingsStateStore.at(dir, branch);
 	const updated: FindingState[] = [];
-	store.update((state) => {
+	mutateState(ctx, (state) => {
+		const ids = inputs.map((input) => requireFindingId(state, input));
 		for (const id of ids) {
-			const finding = state.findings[id];
-			if (!finding) continue;
-			updated.push(applyFindingUpdate(finding, update));
+			updated.push(applyFindingUpdate(state.findings[id], update));
 		}
 	});
-	const missing = ids.filter((id) => !updated.some((f) => f.id === id));
-	if (missing.length > 0) {
-		throw new Error(`Findings não encontrados: ${missing.join(", ")}.`);
-	}
 	return updated;
 }
 
 /** Executa um subcomando de `findings` e devolve o texto + exit code. */
 export function runFindingsCommand(
 	config: HoundsmanConfig,
+	storage: StorageProvider,
+	repo: RepoIdentity,
 	args: string[],
 ): FindingsCommandResult {
-	const parsed = parseArgs(args);
 	try {
-		return execute(config, parsed);
+		const parsed = parseArgs(args);
+		return execute(config, storage, repo, parsed);
 	} catch (error) {
 		return {
 			output: error instanceof Error ? error.message : String(error),
@@ -321,10 +263,16 @@ export function runFindingsCommand(
 	}
 }
 
-function execute(config: HoundsmanConfig, parsed: ParsedArgs): FindingsCommandResult {
+function execute(
+	_config: HoundsmanConfig,
+	storage: StorageProvider,
+	repo: RepoIdentity,
+	parsed: ParsedArgs,
+): FindingsCommandResult {
+	const ctx = openContext(storage, repo, parsed);
 	switch (parsed.sub ?? "list") {
 		case "list": {
-			const state = loadState(config, parsed);
+			const state = loadState(ctx);
 			const filtered = filterFindings(state, filterFrom(parsed));
 			const limit = Number(parsed.values["--limit"]);
 			const findings =
@@ -332,34 +280,35 @@ function execute(config: HoundsmanConfig, parsed: ParsedArgs): FindingsCommandRe
 			return {
 				output: parsed.bools.has("--json")
 					? JSON.stringify(findings, null, 2)
-					: renderList(state, findings),
+					: presenters.findings.list(state, findings),
 				exitCode: 0,
 			};
 		}
 		case "show": {
-			const state = loadState(config, parsed);
-			const id = parsed.positionals[0];
-			if (!id) throw new Error("Informe o id: houndsman findings show <id>");
+			const state = loadState(ctx);
+			const input = parsed.positionals[0];
+			if (!input) throw new Error("Informe o id: houndsman findings show <id>");
+			const id = requireFindingId(state, input);
 			const finding = state.findings[id];
-			if (!finding) throw new Error(`Finding '${id}' não encontrado.`);
 			return {
 				output: parsed.bools.has("--json")
 					? JSON.stringify(finding, null, 2)
-					: renderList(state, [finding]),
+					: presenters.findings.list(state, [finding]),
 				exitCode: 0,
 			};
 		}
 		case "set": {
-			const id = parsed.positionals[0];
-			if (!id) throw new Error("Informe o id: houndsman findings set <id> [flags]");
+			const input = parsed.positionals[0];
+			if (!input)
+				throw new Error("Informe o id: houndsman findings set <id> [flags]");
 			const update = updateFrom(parsed);
 			if (!hasUpdate(update)) {
 				throw new Error(
 					"Nada para atualizar (use --decision, --exec ou --comment).",
 				);
 			}
-			const finding = updateOne(config, parsed, id, update);
-			pingStatus(config, parsed);
+			const finding = updateOne(ctx, input, update);
+			pingStatus(ctx, loadState(ctx));
 			return {
 				output: parsed.bools.has("--json")
 					? JSON.stringify(finding, null, 2)
@@ -369,8 +318,8 @@ function execute(config: HoundsmanConfig, parsed: ParsedArgs): FindingsCommandRe
 		}
 		case "done": {
 			const ids = requireIds(parsed, "done");
-			const updated = updateMany(config, parsed, ids, { execState: "done" });
-			pingStatus(config, parsed);
+			const updated = updateMany(ctx, ids, { execState: "done" });
+			pingStatus(ctx, loadState(ctx));
 			return {
 				output: `Marcados como done: ${updated.map((f) => f.id).join(", ")}.`,
 				exitCode: 0,
@@ -378,28 +327,26 @@ function execute(config: HoundsmanConfig, parsed: ParsedArgs): FindingsCommandRe
 		}
 		case "reset": {
 			const ids = requireIds(parsed, "reset");
-			const updated = updateMany(config, parsed, ids, {
+			const updated = updateMany(ctx, ids, {
 				decision: "pending",
 				execState: "pending",
 				comment: "",
 			});
-			pingStatus(config, parsed);
+			pingStatus(ctx, loadState(ctx));
 			return {
 				output: `Triagem reiniciada: ${updated.map((f) => f.id).join(", ")}.`,
 				exitCode: 0,
 			};
 		}
 		case "sync": {
-			const { dir, branch } = resolveDir(config, parsed);
-			const store = FindingsStateStore.at(dir, branch);
-			const state = loadState(config, parsed);
+			const state = loadState(ctx);
 			const result = syncState(state, fileReader(process.cwd()));
-			store.write(state);
-			pingStatus(config, parsed);
+			ctx.storage.writeFindings(ctx.review.id, state);
+			pingStatus(ctx, state);
 			const output = parsed.bools.has("--json")
 				? JSON.stringify(result, null, 2)
 				: [
-						`Sync — ${branch}: ${result.ok} ok, ${result.moved.length} movido(s), ${result.stale.length} stale.`,
+						`Sync — ${ctx.review.branch}: ${result.ok} ok, ${result.moved.length} movido(s), ${result.stale.length} stale.`,
 						result.moved.length > 0
 							? `Movidos: ${result.moved.join(", ")}`
 							: "",
@@ -412,25 +359,26 @@ function execute(config: HoundsmanConfig, parsed: ParsedArgs): FindingsCommandRe
 			return { output, exitCode: 0 };
 		}
 		case "summary": {
-			const state = loadState(config, parsed);
+			const state = loadState(ctx);
 			const summary = summarize(state);
 			return {
 				output: parsed.bools.has("--json")
 					? JSON.stringify(summary, null, 2)
-					: renderSummary(state, summary),
+					: presenters.findings.summary(state, summary),
 				exitCode: 0,
 			};
 		}
 		case "path": {
-			const { dir, branch } = resolveDir(config, parsed);
-			const path = FindingsStateStore.at(dir, branch).filePath;
-			return { output: relFromRoot(path), exitCode: 0 };
+			return {
+				output: ctx.storage.location(ctx.review.id),
+				exitCode: 0,
+			};
 		}
 		case "batch": {
-			const state = loadState(config, parsed);
+			const state = loadState(ctx);
 			const severity = parsed.values["--severity"];
 			const offset = Number(parsed.values["--offset"]);
-			const result = buildFixBatch(state, {
+			const result = fixBatchBuilder.build(state, {
 				severity: severity ? (severity as Severity) : undefined,
 				includeDone: parsed.bools.has("--include-done"),
 				offset: Number.isFinite(offset) ? offset : undefined,
@@ -439,7 +387,7 @@ function execute(config: HoundsmanConfig, parsed: ParsedArgs): FindingsCommandRe
 			return {
 				output: parsed.bools.has("--json")
 					? JSON.stringify(result, null, 2)
-					: renderBatch(result),
+					: presenters.batch.render(result),
 				exitCode: 0,
 			};
 		}
@@ -479,43 +427,6 @@ function requireIds(parsed: ParsedArgs, sub: string): string[] {
 // verify — as violações foram resolvidas? (sem re-revisar a PR)
 // ---------------------------------------------------------------------------
 
-/** Rótulo curto de cada status de verificação. */
-const VERIFY_LABEL: Record<VerifyStatus, string> = {
-	resolved: "✅ resolvido",
-	persisting: "❌ persiste",
-	uncertain: "⚠️ incerto",
-	"file-missing": "🗑️ arquivo ausente",
-};
-
-/** Render da verificação: contagem por status + uma linha por finding. */
-function renderVerify(
-	state: FindingsStateFile,
-	entries: VerifyEntry[],
-	summary: VerifySummary,
-	meta: { jevChecked: number; jevReason?: string },
-): string {
-	if (entries.length === 0) return "Nenhum finding para verificar.";
-	const lines = [
-		`# Verificação — ${state.branch} (${entries.length})`,
-		"",
-		`Resolvidos: ${summary.resolved} · Persistem: ${summary.persisting} · Incertos: ${summary.uncertain} · Arquivo ausente: ${summary["file-missing"]}`,
-	];
-	if (meta.jevChecked > 0) lines.push(`Confirmados por Jev: ${meta.jevChecked}.`);
-	else if (meta.jevReason) lines.push(`Jev: pulado (${meta.jevReason}).`);
-	lines.push("");
-	for (const entry of entries) {
-		const location = entry.line ? `${entry.file}:${entry.line}` : entry.file;
-		const via =
-			entry.basis === "jev" ? ` · Jev ${(entry.confidence ?? 0).toFixed(2)}` : "";
-		lines.push(
-			`- \`${entry.id}\` ${VERIFY_LABEL[entry.status]} — **${entry.severity}** \`${location}\` — ${entry.rule}${via}`,
-			`  ${entry.message}`,
-		);
-		if (entry.detail) lines.push(`  _${entry.detail}_`);
-	}
-	return lines.join("\n");
-}
-
 /**
  * Subcomando `findings verify` — checa se as violações foram resolvidas, sem
  * re-revisar a PR. Tier local (grátis) + confirmação Jev dos casos ambíguos
@@ -523,11 +434,13 @@ function renderVerify(
  */
 export async function runVerifyCommand(
 	config: HoundsmanConfig,
+	storage: StorageProvider,
+	repo: RepoIdentity,
 	args: string[],
 ): Promise<FindingsCommandResult> {
-	const parsed = parseArgs(args);
 	try {
-		return await executeVerify(config, parsed);
+		const parsed = parseArgs(args);
+		return await executeVerify(config, storage, repo, parsed);
 	} catch (error) {
 		return {
 			output: error instanceof Error ? error.message : String(error),
@@ -538,34 +451,33 @@ export async function runVerifyCommand(
 
 async function executeVerify(
 	config: HoundsmanConfig,
+	storage: StorageProvider,
+	repo: RepoIdentity,
 	parsed: ParsedArgs,
 ): Promise<FindingsCommandResult> {
-	const { dir, branch } = resolveDir(config, parsed);
-	const store = FindingsStateStore.at(dir, branch);
-	const state = loadState(config, parsed);
+	const ctx = openContext(storage, repo, parsed);
+	const state = loadState(ctx);
 
-	// Lazy: `../verify` (leve) e `../jev` (axios) só entram no caminho do verify.
-	const [
-		{ selectVerifiable, verifyLocal, summarizeVerify, applyJev, applyResolutions },
-		{ JevCandidatesStore, JevClient, JevVerifier },
-	] = await Promise.all([import("../verify"), import("../jev")]);
+	// Lazy: `../jev` (axios) só entra no caminho do verify.
+	const verifier = new Verifier();
+	const { JevCandidatesStore, JevClient, JevVerifier } = await import("../jev");
 
-	const findings = selectVerifiable(state, filterFrom(parsed));
-	const entries = verifyLocal(findings, fileReader(process.cwd()));
+	const findings = verifier.select(state, filterFrom(parsed));
+	const entries = verifier.verifyLocal(findings, fileReader(process.cwd()));
 
 	// Tier 1 — Jev só nos ambíguos (fail-open: sem chave/erro mantém o provisório).
 	let jevChecked = 0;
 	let jevReason: string | undefined;
 	const ambiguous = entries.filter((entry) => entry.ambiguous);
 	if (ambiguous.length > 0) {
-		const verifier = new JevVerifier(new JevClient());
+		const jevVerifier = new JevVerifier(new JevClient());
 		if (parsed.bools.has("--no-jev")) {
 			jevReason = "desativado (--no-jev)";
-		} else if (!verifier.isConfigured()) {
+		} else if (!jevVerifier.isConfigured()) {
 			jevReason = "TYPESAFE_API_KEY não configurada";
 		} else {
 			const byId = new Map(findings.map((finding) => [finding.id, finding]));
-			const outcome = await verifier.verify(
+			const outcome = await jevVerifier.verify(
 				ambiguous.map((entry) => ({
 					id: entry.id,
 					file: entry.file,
@@ -577,37 +489,48 @@ async function executeVerify(
 					concurrency: resolveJevConcurrency(config),
 				},
 			);
-			applyJev(entries, outcome.confidence, JevCandidatesStore.THRESHOLD);
+			verifier.applyJev(entries, outcome.confidence, JevCandidatesStore.THRESHOLD);
 			jevChecked = outcome.checked;
 			jevReason = outcome.reason;
 		}
 	}
 
-	const summary = summarizeVerify(entries);
-	const reportPath = join(runDir(dir, branch), VERIFY_FILE);
-	writeFileSync(
-		reportPath,
-		`${renderVerify(state, entries, summary, { jevChecked, jevReason })}\n`,
-	);
+	const summary = verifier.summarize(entries);
+	const location = ctx.storage.location(ctx.review.id);
+	ctx.storage.writeArtifact(ctx.review.id, {
+		name: VERIFY_FILE,
+		kind: "verify",
+		content: `${presenters.verify.render(state, entries, summary, { jevChecked, jevReason })}\n`,
+	});
 
 	let applied: string[] = [];
 	if (parsed.bools.has("--apply")) {
-		store.update((current) => {
-			applied = applyResolutions(current, entries);
+		const current = mutateState(ctx, (draft) => {
+			applied = verifier.applyResolutions(draft, entries);
 		});
-		pingStatus(config, parsed);
+		pingStatus(ctx, current);
 	}
 
 	const output = parsed.bools.has("--json")
 		? JSON.stringify(
-				{ branch, summary, jevChecked, jevReason, applied, entries },
+				{
+					branch: ctx.review.branch,
+					summary,
+					jevChecked,
+					jevReason,
+					applied,
+					entries,
+				},
 				null,
 				2,
 			)
 		: [
-				renderVerify(state, entries, summary, { jevChecked, jevReason }),
+				presenters.verify.render(state, entries, summary, {
+					jevChecked,
+					jevReason,
+				}),
 				"",
-				`Relatório: ${relFromRoot(reportPath)}`,
+				`Relatório: ${location} (${VERIFY_FILE})`,
 				parsed.bools.has("--apply")
 					? `Aplicados (done): ${applied.length > 0 ? applied.join(", ") : "—"}.`
 					: "",
@@ -697,11 +620,13 @@ function renderSubmitOutcome(outcome: SubmitOutcome, json: boolean): string {
  */
 export async function runSubmitCommand(
 	config: HoundsmanConfig,
+	storage: StorageProvider,
+	repo: RepoIdentity,
 	args: string[],
 ): Promise<FindingsCommandResult> {
-	const parsed = parseArgs(args);
 	try {
-		return await executeSubmit(config, parsed);
+		const parsed = parseArgs(args);
+		return await executeSubmit(config, storage, repo, parsed);
 	} catch (error) {
 		return {
 			output: error instanceof Error ? error.message : String(error),
@@ -711,10 +636,13 @@ export async function runSubmitCommand(
 }
 
 async function executeSubmit(
-	config: HoundsmanConfig,
+	_config: HoundsmanConfig,
+	storage: StorageProvider,
+	repo: RepoIdentity,
 	parsed: ParsedArgs,
 ): Promise<FindingsCommandResult> {
-	const state = loadState(config, parsed);
+	const ctx = openContext(storage, repo, parsed);
+	const state = loadState(ctx);
 	const selection = submitSelection(parsed);
 	const target = resolvePrTarget(defaultGhRunner, state.branch);
 	const preview = buildSubmitPreview(state, target, selection);
@@ -731,11 +659,8 @@ async function executeSubmit(
 		runner: defaultGhRunner,
 		selection,
 	});
-	FindingsStateStore.at(
-		parsed.values["--dir"] ?? resolveArtifactDir(config),
-		state.branch,
-	).write(state);
-	pingStatus(config, parsed);
+	ctx.storage.writeFindings(ctx.review.id, state);
+	pingStatus(ctx, state);
 
 	return {
 		output: renderSubmitOutcome(outcome, json),