@payconductor/houndsman 0.1.1 → 0.1.3

package/src/core/orchestrator.ts

@@ -22,15 +22,22 @@ import {
 	resolveJevConcurrency,
 	resolveMaxFilesPerBrief,
 } from "./config";
-import { collectDiff, type DiffSource } from "./diff-source";
+import { churnToRecord, collectDiff, type DiffSource } from "./diff-source";
 import { discoverDocs } from "./doc-discoverer";
 import {
 	type BudgetSelection,
 	type ClassificationResult,
+	classifyEntries,
 	classifyRange,
 	selectByBudget,
 } from "./file-classifier";
-import { buildStateFromFindings, FindingsStateStore, fileReader } from "./findings-state";
+import {
+	buildStateFromFindings,
+	type FindingsStateFile,
+	FindingsStateStore,
+	fileReader,
+} from "./findings-state";
+import { collectDiffSince, diffEntries, isAncestor, resolveSha } from "./git-revision";
 import {
 	type JevCandidate,
 	type JevCandidatesFile,
@@ -44,13 +51,15 @@ import {
 	type ContextSummary,
 	type DomainReport,
 	dedupeFindings,
+	type MergedFinding,
 	parseWatchdogReport,
 	renderDomainReport,
 	renderReport,
 	sanitizeBranch,
 	type WatchdogReport,
 } from "./report-builder";
-import type { WatchdogMeta } from "./types";
+import { writeRunStatus } from "./run-status";
+import { severityRank, type WatchdogMeta } from "./types";
 import { findWatchdog } from "./watchdog-registry";
 
 export type ReviewOptions = {
@@ -62,6 +71,8 @@ export type ReviewOptions = {
 	failOnBlocking: boolean;
 	clean: boolean;
 	noJev: boolean;
+	/** Força review completo (ignora o modo incremental). */
+	full: boolean;
 };
 
 /** Valores default das opções (o CLI sobrepõe com as flags). */
@@ -74,6 +85,7 @@ export function defaultOptions(artifactDir: string = ARTIFACT_DIR): ReviewOption
 		failOnBlocking: false,
 		clean: false,
 		noJev: false,
+		full: false,
 	};
 }
 
@@ -109,6 +121,142 @@ function prepareDirs(dirs: Paths, clean: boolean): void {
 	}
 }
 
+// ---------------------------------------------------------------------------
+// Escopo da revisão (completo vs incremental)
+// ---------------------------------------------------------------------------
+
+/** Classificação enriquecida gravada no `classification.json` (modo + revisão + carry-over). */
+type RunClassification = ClassificationResult & {
+	/** Commit revisado (head do diff). */
+	headSha?: string;
+	/** Modo do prepare: completo ou incremental (delta desde a última revisão). */
+	mode: "full" | "incremental";
+	/** Commit da última revisão (só no incremental). */
+	reviewedFrom?: string;
+	/** Findings preservados do review anterior (arquivos inalterados). */
+	carryover?: MergedFinding[];
+};
+
+/** SHA curto para logs (7 chars, como o git). */
+function shortSha(sha: string): string {
+	return sha.slice(0, 7);
+}
+
+/** Chave de dedupe de finding: `(file, line, rule)` — igual ao `dedupeFindings`. */
+function findingKey(finding: Pick<MergedFinding, "file" | "line" | "rule">): string {
+	return `${finding.file}|${finding.line ?? ""}|${finding.rule}`;
+}
+
+/** Aviso no topo do `review.md` quando a revisão foi incremental (senão vazio). */
+function incrementalNote(classification: RunClassification): string {
+	if (classification.mode !== "incremental" || !classification.reviewedFrom) return "";
+	const carried = classification.carryover?.length ?? 0;
+	return (
+		`> **Revisão incremental** — desde \`${shortSha(classification.reviewedFrom)}\`; ` +
+		`${Object.keys(classification.files).length} arquivo(s) alterado(s), ` +
+		`${carried} finding(s) carregado(s) do review anterior.\n\n`
+	);
+}
+
+/**
+ * Findings do review anterior em arquivos inalterados — carregados sem
+ * re-revisão (carry-over). Preserva o `foundAtSha` para o diff focado do verify.
+ */
+function buildCarryover(
+	previous: FindingsStateFile | null,
+	changedPaths: Set<string>,
+): MergedFinding[] {
+	if (!previous) return [];
+	return Object.values(previous.findings)
+		.filter((finding) => finding.present && !changedPaths.has(finding.file))
+		.map((finding) => ({
+			id: finding.id,
+			rule: finding.rule,
+			severity: finding.severity,
+			file: finding.file,
+			line: finding.line ?? undefined,
+			message: finding.message,
+			action: finding.action,
+			evidence: finding.evidence,
+			foundAtSha: finding.foundAtSha,
+			watchdogs: [...finding.watchdogIds],
+		}));
+}
+
+/** Une os findings re-reportados com os carry-over (preserva ids do estado anterior). */
+function mergeCarryover(
+	merged: MergedFinding[],
+	carryover: readonly MergedFinding[],
+): MergedFinding[] {
+	const byKey = new Map(merged.map((finding) => [findingKey(finding), finding]));
+	for (const carried of carryover) {
+		const existing = byKey.get(findingKey(carried));
+		if (existing) {
+			for (const watchdog of carried.watchdogs) {
+				if (!existing.watchdogs.includes(watchdog))
+					existing.watchdogs.push(watchdog);
+			}
+			continue;
+		}
+		byKey.set(findingKey(carried), carried);
+		merged.push(carried);
+	}
+	merged.sort((a, b) => {
+		const bySeverity = severityRank(a.severity) - severityRank(b.severity);
+		if (bySeverity !== 0) return bySeverity;
+		if (a.file !== b.file) return a.file.localeCompare(b.file);
+		return (a.line ?? 0) - (b.line ?? 0);
+	});
+	return merged;
+}
+
+/**
+ * Decide entre review completo e incremental. Incremental só quando há um
+ * `reviewed.headSha` anterior, o `HEAD` atual o sucede (sem rebase) e não veio
+ * `--full`/`--clean`. Reconstrói só o delta `prevSha..headSha` e carrega os
+ * findings de arquivos inalterados do estado anterior.
+ */
+function resolveReviewScope(
+	opts: ReviewOptions,
+	previous: FindingsStateFile | null,
+	headSha: string,
+	config: HoundsmanConfig,
+): { classification: RunClassification; diff: DiffSource; reviewedFrom?: string } {
+	const prevSha = previous?.reviewed?.headSha;
+	if (
+		opts.full ||
+		opts.clean ||
+		!prevSha ||
+		prevSha === headSha ||
+		!isAncestor(prevSha, headSha)
+	) {
+		const diff = collectDiff(opts.base, opts.head);
+		return {
+			diff,
+			classification: {
+				...classifyRange(opts.base, opts.head, config, diff),
+				headSha,
+				mode: "full",
+			},
+		};
+	}
+
+	const range = `${prevSha}..${headSha}`;
+	const diff = collectDiffSince(prevSha, headSha);
+	const entries = diffEntries(range);
+	const changedPaths = new Set(entries.map((entry) => entry.path));
+	const classification: RunClassification = {
+		...classifyEntries(entries, config, churnToRecord(diff.churn)),
+		base: prevSha,
+		head: opts.head,
+		headSha,
+		mode: "incremental",
+		reviewedFrom: prevSha,
+		carryover: buildCarryover(previous, changedPaths),
+	};
+	return { classification, diff, reviewedFrom: prevSha };
+}
+
 // ---------------------------------------------------------------------------
 // Findings
 // ---------------------------------------------------------------------------
@@ -157,7 +305,7 @@ function writeManifest(
 	outDir: string,
 	opts: ReviewOptions,
 	branch: string,
-	classification: ClassificationResult,
+	classification: RunClassification,
 	activeIds: string[],
 	pending: string[],
 	jev: JevCandidatesFile,
@@ -184,10 +332,19 @@ function writeManifest(
 		slug: sanitizeBranch(branch),
 		base: opts.base,
 		head: opts.head,
+		headSha: classification.headSha,
 		generatedAt: new Date().toISOString(),
 		outputFormat: OUTPUT_FORMAT_PATH,
 		budget: { maxFilesPerBrief, filesOverBudget },
 		churn: churnTotals(classification),
+		incremental:
+			classification.mode === "incremental"
+				? {
+						from: classification.reviewedFrom,
+						changedFiles: Object.keys(classification.files).length,
+						carried: classification.carryover?.length ?? 0,
+					}
+				: undefined,
 		watchdogs,
 		context: contextManifest(opts, branch),
 		jev: jev.available
@@ -388,9 +545,13 @@ export async function prepare(
 ): Promise<void> {
 	prepareDirs(dirs, opts.clean);
 
-	// Um único diff para toda a execução (churn + patch) — antes: 1 spawn por arquivo.
-	const diff = collectDiff(opts.base, opts.head);
-	const classification = classifyRange(opts.base, opts.head, config, diff);
+	// Marca o run como "revisando" (reinicia o ciclo) — a UI mostra o status.
+	writeRunStatus(dirs.outDir, { branch, status: "reviewing", resetStartedAt: true });
+
+	// Marca o commit revisado e decide entre review completo e incremental.
+	const headSha = resolveSha(opts.head);
+	const previous = FindingsStateStore.at(opts.dir, branch).read();
+	const { classification, diff } = resolveReviewScope(opts, previous, headSha, config);
 	writeFileSync(
 		join(dirs.outDir, "classification.json"),
 		`${JSON.stringify(classification, null, 2)}\n`,
@@ -400,13 +561,24 @@ export async function prepare(
 
 	const activeIds = Object.keys(classification.watchdogs);
 	if (Object.keys(classification.files).length === 0) {
-		console.log(`Nenhuma alteração entre ${opts.base}...${opts.head}.`);
+		writeRunStatus(dirs.outDir, { branch, status: "review_done" });
+		console.log(
+			classification.mode === "incremental"
+				? `Nenhuma alteração desde a última revisão (${shortSha(classification.reviewedFrom ?? "")}).`
+				: `Nenhuma alteração entre ${opts.base}...${opts.head}.`,
+		);
 		return;
 	}
 	if (activeIds.length === 0) {
+		writeRunStatus(dirs.outDir, { branch, status: "review_done" });
 		console.log("Nenhum arquivo revisável (tudo excluído, deletado ou irrelevante).");
 		return;
 	}
+	if (classification.mode === "incremental") {
+		console.log(
+			`Modo incremental: ${Object.keys(classification.files).length} arquivo(s) alterado(s) desde ${shortSha(classification.reviewedFrom ?? "")}; ${classification.carryover?.length ?? 0} finding(s) carregado(s) do review anterior.`,
+		);
+	}
 
 	const context = readContextSummary(contextPaths(opts.dir, branch).summary);
 
@@ -444,7 +616,7 @@ export async function prepare(
 // ---------------------------------------------------------------------------
 
 /** Lê o classification.json gravado pelo passo de preparação (lança se ausente). */
-function readClassification(classificationPath: string): ClassificationResult {
+function readClassification(classificationPath: string): RunClassification {
 	if (!existsSync(classificationPath)) {
 		throw new Error(
 			`Não encontrei ${relFromRoot(classificationPath)}. Rode \`bun run houndsman\` (preparar) primeiro.`,
@@ -452,9 +624,7 @@ function readClassification(classificationPath: string): ClassificationResult {
 	}
 	const parsed = JSON.parse(
 		readFileSync(classificationPath, "utf8"),
-	) as ClassificationResult;
-	// Compatível com classification.json gerado antes do churn existir.
-	parsed.churn ??= {};
+	) as RunClassification;
 	return parsed;
 }
 
@@ -542,21 +712,38 @@ export function finalize(
 		);
 	}
 
-	const merged = dedupeFindings(reports);
+	const now = new Date().toISOString();
+	// Findings re-reportados neste ciclo + carry-over (arquivos inalterados).
+	const merged = mergeCarryover(
+		dedupeFindings(reports),
+		classification.carryover ?? [],
+	);
+	if (classification.mode === "incremental") {
+		console.log(
+			`Carry-over: ${classification.carryover?.length ?? 0} finding(s) preservado(s) de ${shortSha(classification.reviewedFrom ?? "")}.`,
+		);
+	}
 
 	// Estado de triagem: preserva o que já existia (casando por fingerprint) e
 	// anexa o `id` de cada finding aos itens do relatório. A linha é cache —
-	// recalculada por `houndsman findings sync` após edições.
+	// recalculada por `houndsman findings sync` após edições. O commit revisado
+	// (`reviewed.headSha`) habilita o review incremental e o diff focado do verify.
 	const store = FindingsStateStore.at(opts.dir, branch);
 	const state = buildStateFromFindings(merged, {
 		branch,
 		readFile: fileReader(process.cwd()),
 		previous: store.read(),
+		now,
+		headSha: classification.headSha,
+		reviewed: classification.headSha
+			? { headSha: classification.headSha, at: now }
+			: undefined,
 	});
 	store.write(state);
 	console.log(
 		`Triagem: ${relFromRoot(store.filePath)} — ${Object.keys(state.findings).length} finding(s).`,
 	);
+	writeRunStatus(dirs.outDir, { branch, status: "review_done" });
 
 	const context = readContextSummary(contextPaths(opts.dir, branch).summary);
 	const nameOf = (id: string): string => findWatchdog(config, id)?.name ?? id;
@@ -579,7 +766,7 @@ export function finalize(
 		domains,
 	);
 	const reportPath = join(dirs.outDir, "review.md");
-	writeFileSync(reportPath, `${markdown}\n`);
+	writeFileSync(reportPath, `${incrementalNote(classification)}${markdown}\n`);
 
 	const blockers = merged.filter((f) => f.severity === "blocking").length;
 	const attention = merged.filter((f) => f.severity === "attention").length;

package/src/core/paths.ts

@@ -31,3 +31,9 @@ export const OUTPUT_FORMAT_PATH = `${CORE_SKILL_DIR}/${OUTPUT_FORMAT_FILE}`;
 
 /** Estado de triagem dos findings, dentro da pasta da run (`<slug>/state.json`). */
 export const STATE_FILE = "state.json";
+
+/** Status da run (revisão/correção), dentro da pasta da run (`<slug>/run.json`). */
+export const RUN_STATUS_FILE = "run.json";
+
+/** Relatório da verificação de findings, dentro da pasta da run (`<slug>/verify.md`). */
+export const VERIFY_FILE = "verify.md";

package/src/core/report-builder.ts

@@ -25,6 +25,11 @@ export type Finding = {
 	message: string;
 	action: string;
 	evidence?: string;
+	/**
+	 * Commit em que o achado foi observado (interno). Preenchido nos carry-over
+	 * do review incremental — preserva a referência para a verificação (verify).
+	 */
+	foundAtSha?: string;
 };
 
 export type WatchdogReport = {

package/src/core/run-status.ts

@@ -0,0 +1,123 @@
+/**
+ * Status do run (biblioteca) — persistido em `.houndsman/.runs/<slug>/run.json`.
+ *
+ * Diz à UI em que pé está uma run: `reviewing` (revisando) → `review_done`
+ * (revisão finalizada) → `fixing` (corrigindo) → `fix_done` (correção finalizada).
+ *
+ * Toda ação que muda o estado faz um **ping** no `updatedAt`, mantendo o arquivo
+ * "quente". Timeout é **display-only** (a UI compara `updatedAt` com o agora) —
+ * não é um status persistido.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { FindingsStateFile } from "./findings-state";
+import { RUN_STATUS_FILE } from "./paths";
+import { sanitizeBranch } from "./report-builder";
+
+/** Estados de execução de uma run (persistidos). */
+export type RunStatus = "reviewing" | "review_done" | "fixing" | "fix_done";
+
+/** Valores canônicos de status (ordem de exibição/lifecycle). */
+export const RUN_STATUSES: readonly RunStatus[] = [
+	"reviewing",
+	"review_done",
+	"fixing",
+	"fix_done",
+];
+
+export const RUN_STATUS_VERSION = 1;
+
+/** Conteúdo do `run.json`. */
+export type RunStatusFile = {
+	version: 1;
+	slug: string;
+	branch: string;
+	status: RunStatus;
+	/** Início do ciclo de revisão atual (reiniciado a cada `prepare`). */
+	startedAt: string;
+	/** Última ação importante (ping). */
+	updatedAt: string;
+};
+
+/** Caminho do `run.json` dentro da pasta da run. */
+export function runStatusPath(runDir: string): string {
+	return join(runDir, RUN_STATUS_FILE);
+}
+
+/** Lê o `run.json` da run (null se ausente/inválido). */
+export function readRunStatus(runDir: string): RunStatusFile | null {
+	const path = runStatusPath(runDir);
+	if (!existsSync(path)) return null;
+	try {
+		return JSON.parse(readFileSync(path, "utf8")) as RunStatusFile;
+	} catch {
+		return null;
+	}
+}
+
+export type WriteRunStatusOptions = {
+	branch: string;
+	status: RunStatus;
+	/** Reinicia o `startedAt` — usado no início de uma nova revisão. */
+	resetStartedAt?: boolean;
+	now?: string;
+};
+
+/** Grava/atualiza o `run.json` (ping no `updatedAt`). */
+export function writeRunStatus(
+	runDir: string,
+	options: WriteRunStatusOptions,
+): RunStatusFile {
+	const now = options.now ?? new Date().toISOString();
+	const previous = readRunStatus(runDir);
+	const file: RunStatusFile = {
+		version: RUN_STATUS_VERSION,
+		slug: sanitizeBranch(options.branch),
+		branch: options.branch,
+		status: options.status,
+		startedAt: options.resetStartedAt ? now : (previous?.startedAt ?? now),
+		updatedAt: now,
+	};
+	mkdirSync(runDir, { recursive: true });
+	writeFileSync(runStatusPath(runDir), `${JSON.stringify(file, null, 2)}\n`);
+	return file;
+}
+
+/**
+ * Deriva o status após uma mudança nos findings (triagem/correção).
+ * `fixing` exige correção em andamento (`in_progress`) ou retomada de um fix;
+ * `fix_done` quando o fix começou e a fila (`execute` não `done`) esvaziou.
+ */
+export function statusAfterFindingsChange(
+	previous: RunStatus | null,
+	state: FindingsStateFile,
+): RunStatus {
+	const findings = Object.values(state.findings);
+	const active = findings.filter((finding) => finding.present);
+
+	if (active.some((finding) => finding.execState === "in_progress")) return "fixing";
+
+	const queueRemaining = active.some(
+		(finding) => finding.decision === "execute" && finding.execState !== "done",
+	);
+	const anyDone = active.some(
+		(finding) => finding.decision === "execute" && finding.execState === "done",
+	);
+	const fixStarted = previous === "fixing" || previous === "fix_done" || anyDone;
+	if (fixStarted) return queueRemaining ? "fixing" : "fix_done";
+
+	return previous ?? "review_done";
+}
+
+/** Ping: deriva o status da mudança nos findings e grava o `run.json`. */
+export function pingFindingsStatus(
+	runDir: string,
+	state: FindingsStateFile,
+): RunStatusFile {
+	const previous = readRunStatus(runDir)?.status ?? null;
+	return writeRunStatus(runDir, {
+		branch: state.branch,
+		status: statusAfterFindingsChange(previous, state),
+	});
+}

package/src/core/verify.ts

@@ -0,0 +1,175 @@
+/**
+ * Verificação de findings (biblioteca) — "as violações foram resolvidas?".
+ *
+ * Checagem barata, **sem re-revisar a PR**:
+ *  - Tier 0 (local, grátis): reancora a âncora de conteúdo contra o working tree.
+ *  - Tier 1 (Jev, opcional): confirma/refuta os casos ambíguos (âncora sumida ou
+ *    inexistente) via LLM, sobre um diff focado do arquivo (`jev-verify.ts`).
+ *
+ * `verifyLocal` é puro (recebe o leitor de arquivos); o comando renderiza e, com
+ * `--apply`, persiste `resolved` → `execState: done`.
+ */
+
+import { reanchor } from "./finding-anchor";
+import {
+	applyFindingUpdate,
+	type FileReader,
+	type FindingState,
+	type FindingsFilter,
+	type FindingsStateFile,
+	filterFindings,
+} from "./findings-state";
+import type { Severity } from "./types";
+
+/** Resultado da verificação de um finding. */
+export type VerifyStatus = "resolved" | "persisting" | "uncertain" | "file-missing";
+
+/** Mecanismo que decidiu o status (reancoragem local ou LLM). */
+export type VerifyBasis = "anchor" | "jev";
+
+/** Valores canônicos de status (ordem de exibição). */
+export const VERIFY_STATUSES: readonly VerifyStatus[] = [
+	"resolved",
+	"persisting",
+	"uncertain",
+	"file-missing",
+];
+
+/** Um finding verificado. */
+export type VerifyEntry = {
+	id: string;
+	file: string;
+	rule: string;
+	severity: Severity;
+	message: string;
+	line: number | null;
+	status: VerifyStatus;
+	basis: VerifyBasis;
+	/** Confiança do Jev (0–1) quando `basis: "jev"`. */
+	confidence?: number;
+	detail?: string;
+	/** Ambíguo no tier local — candidato à confirmação do Jev. */
+	ambiguous: boolean;
+};
+
+/** Fila de verificação: presentes, excluindo `ignore` (descartados pelo usuário). */
+export function selectVerifiable(
+	state: FindingsStateFile,
+	filter: FindingsFilter = {},
+): FindingState[] {
+	return filterFindings(state, filter).filter(
+		(finding) => finding.decision !== "ignore",
+	);
+}
+
+/**
+ * Tier 0 — checagem local por conteúdo. Marca `ambiguous: true` quando a âncora
+ * sumiu (corrigida ou trecho reescrito) ou não existe; nesses casos o Jev pode
+ * confirmar. Âncora presente (`ok`/`moved`) ⇒ `persisting`, definitivo.
+ */
+export function verifyLocal(
+	findings: readonly FindingState[],
+	readFile: FileReader,
+): VerifyEntry[] {
+	return findings.map((finding) => {
+		const base = {
+			id: finding.id,
+			file: finding.file,
+			rule: finding.rule,
+			severity: finding.severity,
+			message: finding.message,
+			line: finding.line,
+		};
+		const content = readFile(finding.file);
+		if (content === null) {
+			return {
+				...base,
+				status: "file-missing" as const,
+				basis: "anchor" as const,
+				ambiguous: false,
+				detail: "arquivo ausente no working tree",
+			};
+		}
+		if (!finding.anchor) {
+			return {
+				...base,
+				status: "uncertain" as const,
+				basis: "anchor" as const,
+				ambiguous: true,
+				detail: "finding sem âncora de conteúdo",
+			};
+		}
+		const { status } = reanchor(content, finding.anchor, finding.line);
+		if (status === "stale") {
+			return {
+				...base,
+				status: "resolved" as const,
+				basis: "anchor" as const,
+				ambiguous: true,
+				detail: "âncora ausente (trecho corrigido?)",
+			};
+		}
+		return {
+			...base,
+			status: "persisting" as const,
+			basis: "anchor" as const,
+			ambiguous: false,
+			detail: status === "moved" ? "âncora deslocada" : undefined,
+		};
+	});
+}
+
+/**
+ * Tier 1 — aplica a confirmação do Jev aos casos ambíguos.
+ * `confidence[id] >= threshold` ⇒ a violação persiste; abaixo ⇒ resolvida.
+ * Ids sem resposta mantêm o provisório local (fail-open). Devolve o nº aplicado.
+ */
+export function applyJev(
+	entries: VerifyEntry[],
+	confidence: Map<string, number>,
+	threshold: number,
+): number {
+	let applied = 0;
+	for (const entry of entries) {
+		if (!entry.ambiguous) continue;
+		const value = confidence.get(entry.id);
+		if (value === undefined) continue;
+		entry.basis = "jev";
+		entry.confidence = value;
+		entry.status = value >= threshold ? "persisting" : "resolved";
+		applied++;
+	}
+	return applied;
+}
+
+export type VerifySummary = Record<VerifyStatus, number>;
+
+/** Contagem por status. */
+export function summarizeVerify(entries: readonly VerifyEntry[]): VerifySummary {
+	const summary = Object.fromEntries(
+		VERIFY_STATUSES.map((status) => [status, 0]),
+	) as VerifySummary;
+	for (const entry of entries) summary[entry.status]++;
+	return summary;
+}
+
+/**
+ * Persiste os `resolved` como `done` (acao `verify`). Devolve os ids alterados.
+ * Muta o estado em memória (o caller persiste).
+ */
+export function applyResolutions(
+	state: FindingsStateFile,
+	entries: readonly VerifyEntry[],
+	now: string = new Date().toISOString(),
+): string[] {
+	const changed: string[] = [];
+	for (const entry of entries) {
+		if (entry.status !== "resolved") continue;
+		const finding = state.findings[entry.id];
+		if (!finding || finding.execState === "done") continue;
+		applyFindingUpdate(finding, { execState: "done", by: "verify" }, now);
+		changed.push(finding.id);
+	}
+	if (changed.length > 0) state.updatedAt = now;
+	return changed;
+}

package/src/core/watchdog-registry.ts

@@ -1,8 +1,7 @@
 /**
  * Acesso tipado aos watchdogs de um `HoundsmanConfig` (biblioteca).
  *
- * Substitui o antigo barrel `registry/`. O motor não conhece ids concretos —
- * tudo chega via `config`.
+ * O motor não conhece ids concretos — tudo chega via `config`.
  */
 
 import type { HoundsmanConfig } from "./config";

package/src/index.ts

@@ -8,7 +8,7 @@
 export { assetPath, OUTPUT_FORMAT_FILE } from "./core/assets";
 export { defaultRenderBrief, PROCEDURE, renderBrief } from "./core/brief";
 export type { FindingsCommandResult } from "./core/commands/findings";
-export { runFindingsCommand } from "./core/commands/findings";
+export { runFindingsCommand, runVerifyCommand } from "./core/commands/findings";
 export type {
 	HoundsmanBudgets,
 	HoundsmanConcurrency,

package/src/server/artifacts.ts

@@ -11,6 +11,7 @@ import { isAbsolute, join, relative, resolve } from "node:path";
 const RUN_MARKERS = [
 	"manifest.json",
 	"state.json",
+	"run.json",
 	"classification.json",
 	"review.md",
 ] as const;