@payconductor/houndsman 0.4.0 → 0.5.0

package/src/core/orchestrator.ts

@@ -30,6 +30,7 @@ import { ReviewScopeResolver, type RunClassification } from "./engine/review-sco
 import type { BudgetSelection, ClassificationResult } from "./file-classifier";
 import { buildStateFromFindings, fileReader } from "./findings-state";
 import { resolveSha } from "./git-revision";
+import { syncResolvedThreads } from "./github-review";
 import {
 	type JevCandidate,
 	type JevCandidatesFile,
@@ -39,12 +40,18 @@ import {
 	parseCandidates,
 	serializeCandidates,
 } from "./jev";
-import { displayPath, OUTPUT_FORMAT_PATH, REVIEW_FILE } from "./paths";
+import {
+	displayPath,
+	OUTPUT_FORMAT_PATH,
+	REVIEW_FILE,
+	REVIEW_RESUME_FILE,
+} from "./paths";
 import { currentBranch } from "./pr-context";
 import { ProjectConfig } from "./project-config";
 import { BriefRenderer } from "./renderers/brief-renderer";
 import { ManifestWriter } from "./renderers/manifest-writer";
 import { ReportRenderer } from "./renderers/report-renderer";
+import { renderReviewResume } from "./renderers/resume-renderer";
 import {
 	type ContextSummary,
 	type DomainReport,
@@ -312,19 +319,36 @@ export async function prepare(
 	if (opts.clean) ctx.work.cleanFindings();
 	ctx.storage.updateReview(ctx.review.id, { base: opts.base, head: opts.head });
 
+	// Marca o commit revisado e decide entre completo, incremental ou no-op.
+	const headSha = resolveSha(opts.head);
+	const previous = ctx.storage.readFindings(ctx.review.id);
+	const scope = new ReviewScopeResolver(opts, config).resolve(previous, headSha);
+
+	// Mesmo commit já revisado: preserva artefatos e triagem, sem re-revisar.
+	if (scope.kind === "noop") {
+		const status = ctx.storage.getReview(ctx.review.id)?.status ?? null;
+		// Ciclo em andamento continua válido (os findings já despachados devem
+		// ser finalizados); fora isso, o relatório anterior é a resposta final.
+		const pendingCycle = status === "reviewing";
+		if (!pendingCycle) {
+			writeRunStatus(ctx.storage, ctx.review.id, { status: "review_done" });
+		}
+		messages.push(
+			`Nenhuma alteração desde a última revisão (${shortSha(scope.reviewedFrom)}).`,
+			pendingCycle
+				? "Nada novo a preparar — o ciclo em andamento continua; rode `--finalize` quando os findings estiverem gravados."
+				: "Nada a revisar — o relatório anterior foi mantido. Use `--full` para re-revisar.",
+		);
+		return { messages };
+	}
+
 	// Marca o run como "revisando" (reinicia o ciclo) — a UI mostra o status.
 	writeRunStatus(ctx.storage, ctx.review.id, {
 		status: "reviewing",
 		resetStartedAt: true,
 	});
 
-	// Marca o commit revisado e decide entre review completo e incremental.
-	const headSha = resolveSha(opts.head);
-	const previous = ctx.storage.readFindings(ctx.review.id);
-	const { classification, diff } = new ReviewScopeResolver(opts, config).resolve(
-		previous,
-		headSha,
-	);
+	const { classification, diff } = scope;
 	ctx.storage.writeArtifact(ctx.review.id, {
 		name: "classification.json",
 		kind: "classification",
@@ -510,6 +534,27 @@ export function finalize(
 	config: HoundsmanConfig,
 	ctx: ReviewContext,
 ): FinalizeResult {
+	// `--finalize` só consolida um ciclo preparado (status `reviewing`). Sem esta
+	// guarda, um prepare no-op seguido de `--finalize` reescreveria o relatório
+	// anterior com a classificação antiga (perdendo os relatórios por domínio).
+	// O `ctx.review` é um snapshot: relê o status atual do storage.
+	const status = ctx.storage.getReview(ctx.review.id)?.status ?? null;
+	if (status !== "reviewing") {
+		const state = ctx.storage.readFindings(ctx.review.id);
+		const present = Object.values(state?.findings ?? {}).filter(
+			(finding) => finding.present,
+		);
+		return {
+			reportPath: ctx.storage.location(ctx.review.id),
+			blockers: present.filter((f) => f.severity === "blocking").length,
+			attention: present.filter((f) => f.severity === "attention").length,
+			messages: [
+				`Nada a finalizar: nenhum ciclo de revisão pendente (status: ${status ?? "sem status"}).`,
+				"Se nada mudou desde a última revisão, o relatório anterior foi mantido; use `--full` para re-revisar.",
+			],
+		};
+	}
+
 	const classification = readClassification(ctx);
 	const activeIds = Object.keys(classification.watchdogs);
 
@@ -546,12 +591,44 @@ export function finalize(
 		branch,
 		readFile: fileReader(process.cwd()),
 		previous: ctx.storage.readFindings(ctx.review.id),
+		reviewedPaths: new Set([
+			...reports.flatMap((report) => report.reviewedFiles),
+			// Arquivo deletado: o achado deixou de existir junto com ele.
+			...classification.deleted,
+		]),
 		now,
 		headSha: classification.headSha,
 		reviewed: classification.headSha
 			? { headSha: classification.headSha, at: now }
 			: undefined,
 	});
+
+	// Findings corrigidos entre revisões (ausentes + done) têm a conversa do PR
+	// resolvida automaticamente; as já resolvidas no GitHub são puladas. Só
+	// toca o `gh` quando há vínculo remoto pendente (fail-open).
+	const threadIds = Object.values(state.findings)
+		.filter(
+			(finding) =>
+				!finding.present &&
+				finding.execState === "done" &&
+				finding.github &&
+				finding.github.kind !== "comment" &&
+				!finding.github.resolvedAt,
+		)
+		.map((finding) => finding.id);
+	if (threadIds.length > 0) {
+		const sync = syncResolvedThreads({ state, ids: threadIds, now });
+		if (!sync.available) {
+			messages.push(`GitHub: threads não sincronizadas (${sync.reason}).`);
+		} else if (sync.checked > 0) {
+			const failures =
+				sync.failed.length > 0 ? `, ${sync.failed.length} falha(s)` : "";
+			messages.push(
+				`GitHub: ${sync.resolved.length} thread(s) resolvida(s), ${sync.skipped.length} já resolvida(s)/pulada(s)${failures}.`,
+			);
+		}
+	}
+
 	ctx.storage.writeFindings(ctx.review.id, state);
 	ctx.storage.updateReview(ctx.review.id, {
 		base: opts.base,
@@ -585,6 +662,19 @@ export function finalize(
 		kind: "review",
 		content: `${incrementalNote(classification)}${markdown}\n`,
 	});
+	// Resumo final para leitura humana — não participa de nenhuma etapa seguinte.
+	ctx.storage.writeArtifact(ctx.review.id, {
+		name: REVIEW_RESUME_FILE,
+		kind: "resume",
+		content: renderReviewResume({
+			branch,
+			date: now.slice(0, 10),
+			context,
+			classification,
+			findings: merged,
+			nameOf,
+		}),
+	});
 
 	const location = ctx.storage.location(ctx.review.id);
 	messages.push(

package/src/core/paths.ts

@@ -52,3 +52,6 @@ export const VERIFY_FILE = "verify.md";
 
 /** Relatório consolidado da review (artefato `review.md`). */
 export const REVIEW_FILE = "review.md";
+
+/** Resumo final da review (artefato `review-resume.md`) — leitura humana apenas. */
+export const REVIEW_RESUME_FILE = "review-resume.md";

package/src/core/renderers/resume-renderer.ts

@@ -0,0 +1,151 @@
+/**
+ * Resumo final da revisão (`review-resume.md`).
+ *
+ * Artefato somente-leitura para humanos: não entra em briefs, não é lido pelos
+ * watchdogs e não participa de nenhuma etapa seguinte. Une o contexto de
+ * negócio da PR aos números técnicos diretos da revisão, com limite de
+ * `RESUME_MAX_CHARS`.
+ */
+
+import type {
+	ContextSummary,
+	MergedFinding,
+	WatchdogNameResolver,
+} from "../report-builder";
+import { systemClock } from "../services/clock";
+
+/** Teto de caracteres do artefato (inclui cabeçalho e quebras de linha). */
+export const RESUME_MAX_CHARS = 2500;
+
+/** Dados de classificação usados no resumo. */
+export type ResumeClassification = {
+	files: Record<string, { status: string }>;
+	watchdogs: Record<string, string[]>;
+};
+
+export type ReviewResumeInput = {
+	branch: string;
+	/** `YYYY-MM-DD`; default: data corrente do sistema. */
+	date?: string;
+	context?: ContextSummary | null;
+	classification: ResumeClassification;
+	findings: readonly MergedFinding[];
+	nameOf?: WatchdogNameResolver;
+};
+
+const identityName: WatchdogNameResolver = (id) => id;
+
+const STATUS_BY_SEVERITY: Record<"blocking" | "attention" | "clean", string> = {
+	blocking: "❌ Mudanças necessárias",
+	attention: "⚠️ Aprovado com ressalvas",
+	clean: "✅ Aprovado",
+};
+
+/** Corta o texto em `max` caracteres, sinalizando com reticências. */
+function truncate(value: string, max: number): string {
+	const text = value.trim().replace(/\s+/g, " ");
+	return text.length <= max ? text : `${text.slice(0, max - 1).trimEnd()}…`;
+}
+
+function plural(count: number, singular: string, plural: string): string {
+	return `${count} ${count === 1 ? singular : plural}`;
+}
+
+/** Resumo de negócio: contexto da PR; sem ele, o alcance da branch. */
+function businessSection(input: ReviewResumeInput): string[] {
+	const context = input.context;
+	const hasContext =
+		context?.available === true &&
+		Boolean(
+			context.objective ||
+				context.motivation ||
+				(context.changeSummary && context.changeSummary.length > 0),
+		);
+	const lines = ["## Resumo de negócio", ""];
+
+	if (!hasContext) {
+		const domainCount = Object.keys(input.classification.watchdogs).length;
+		lines.push(
+			`A branch \`${input.branch}\` altera ${plural(
+				Object.keys(input.classification.files).length,
+				"arquivo",
+				"arquivos",
+			)} em ${plural(domainCount, "domínio", "domínios")} de revisão.`,
+			"Sem resumo de contexto da PR disponível.",
+			"",
+		);
+		return lines;
+	}
+
+	if (context.objective) lines.push(context.objective, "");
+	if (context.motivation) lines.push(`**Por quê:** ${context.motivation}`, "");
+	if (context.changeSummary && context.changeSummary.length > 0) {
+		for (const item of context.changeSummary.slice(0, 4)) {
+			lines.push(`- ${truncate(item, 180)}`);
+		}
+		lines.push("");
+	}
+	return lines;
+}
+
+/** Achados que exigem ação, em formato direto (máximo 5). */
+function technicalSection(
+	findings: readonly MergedFinding[],
+	nameOf: WatchdogNameResolver,
+): string[] {
+	const relevant = findings
+		.filter(
+			(finding) =>
+				finding.severity === "blocking" || finding.severity === "attention",
+		)
+		.slice(0, 5);
+	const lines = ["## Pontos técnicos", ""];
+	if (relevant.length === 0) {
+		lines.push("- Nenhum bloqueio ou ponto de atenção.", "");
+		return lines;
+	}
+	for (const finding of relevant) {
+		const location = finding.line ? `${finding.file}:${finding.line}` : finding.file;
+		const watchdogs = finding.watchdogs.map((id) => nameOf(id)).join(", ");
+		lines.push(
+			`- \`${location}\` — ${truncate(finding.message, 130)}${watchdogs ? ` _(${watchdogs})_` : ""}`,
+		);
+	}
+	lines.push("");
+	return lines;
+}
+
+/** Garante o teto de caracteres cortando em uma quebra de linha. */
+function clamp(markdown: string, max: number): string {
+	if (markdown.length <= max) return markdown;
+	const head = markdown.slice(0, max - 2);
+	const cut = head.lastIndexOf("\n");
+	return `${(cut > 0 ? head.slice(0, cut) : head).trimEnd()}\n…`;
+}
+
+/**
+ * Renderiza o resumo final. Determinístico e sem chamadas externas: o texto
+ * nasce do contexto já disponível e dos findings consolidados.
+ */
+export function renderReviewResume(input: ReviewResumeInput): string {
+	const nameOf = input.nameOf ?? identityName;
+	const blockers = input.findings.filter((f) => f.severity === "blocking").length;
+	const attention = input.findings.filter((f) => f.severity === "attention").length;
+	const status =
+		blockers > 0
+			? STATUS_BY_SEVERITY.blocking
+			: attention > 0
+				? STATUS_BY_SEVERITY.attention
+				: STATUS_BY_SEVERITY.clean;
+
+	const lines = [
+		`# Resumo da revisão — ${input.branch}`,
+		"",
+		`**Data:** ${input.date ?? systemClock().slice(0, 10)} · **Status:** ${status}`,
+		"",
+		...businessSection(input),
+		...technicalSection(input.findings, nameOf),
+	];
+
+	return clamp(`${lines.join("\n").trimEnd()}\n`, RESUME_MAX_CHARS);
+}

package/src/core/report-builder.ts

@@ -294,6 +294,7 @@ function renderConclusion(counts: Record<Severity, number>): string[] {
 		"",
 		`**Status:** ${status}`,
 		`**Resumo:** ${counts.blocking} violações bloqueantes, ${counts.attention} pontos de atenção, ${counts.suggestion} sugestões e ${counts.nit} nits.`,
+		"",
 	];
 }
 
@@ -453,6 +454,12 @@ export function renderReport(
 
 	if (context) lines.push(...renderContext(context));
 
+	// Sumário primeiro: quem lê o review.md vê domínios, cobertura e conclusão
+	// antes dos pontos específicos.
+	lines.push(...renderDomainIndex(domains));
+	lines.push(...renderCoverage(reports, coverage, nameOf));
+	lines.push(...renderConclusion(counts));
+
 	lines.push(...renderFindingsSections(merged, nameOf));
 
 	if (merged.length === 0) {
@@ -463,9 +470,5 @@ export function renderReport(
 		lines.push(...renderUnconfirmedCandidates(candidates, merged));
 	}
 
-	lines.push(...renderDomainIndex(domains));
-	lines.push(...renderCoverage(reports, coverage, nameOf));
-	lines.push(...renderConclusion(counts));
-
 	return lines.join("\n");
 }

package/src/core/run-status.ts

@@ -4,9 +4,9 @@
  * 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`. Timeout é
- * **display-only** (a UI compara `updatedAt` com o agora) — não é um status
- * persistido.
+ * Toda ação que muda o estado pinga o `updatedAt`. Execuções ativas têm um
+ * `heartbeatAt` próprio (renovado por `status ping` ou pela correção); a UI usa
+ * esse campo — não o `updatedAt` — para detectar timeout (display-only).
  */
 
 import type { FindingsStateFile } from "./findings-state";
@@ -24,6 +24,11 @@ export const RUN_STATUSES: readonly RunStatus[] = [
 	"fix_done",
 ];
 
+/** `true` para status de execução (recebem heartbeat e podem dar timeout). */
+export function isActiveRunStatus(status: RunStatus | null): boolean {
+	return status === "reviewing" || status === "fixing";
+}
+
 /** Lê o status atual (null se a review não existir). */
 export function readRunStatus(
 	storage: StorageProvider,
@@ -36,6 +41,11 @@ export type WriteRunStatusOptions = {
 	status: RunStatus;
 	/** Reinicia o `startedAt` — usado no início de uma nova revisão. */
 	resetStartedAt?: boolean;
+	/**
+	 * Marca a execução como viva agora. Implícito no início de um ciclo
+	 * (`resetStartedAt`); pings explícitos usam `touchRunStatus`.
+	 */
+	touch?: boolean;
 	now?: string;
 };
 
@@ -45,15 +55,35 @@ export function writeRunStatus(
 	reviewId: string,
 	options: WriteRunStatusOptions,
 ): ReviewRecord {
+	const now = options.now ?? systemClock();
+	const active = isActiveRunStatus(options.status);
+	const touch = options.touch ?? options.resetStartedAt ?? false;
 	const updated = storage.updateReview(reviewId, {
 		status: options.status,
 		resetStartedAt: options.resetStartedAt,
-		updatedAt: options.now ?? systemClock(),
+		heartbeatAt: active && touch ? now : undefined,
+		resetHeartbeat: !active,
+		updatedAt: now,
 	});
 	if (!updated) throw new Error(`Review '${reviewId}' não encontrada.`);
 	return updated;
 }
 
+/**
+ * Heartbeat explícito de uma execução em andamento (skill viva).
+ * Só age em `reviewing`/`fixing`; status terminal é devolvido sem alteração.
+ */
+export function touchRunStatus(
+	storage: StorageProvider,
+	reviewId: string,
+	now: string = systemClock(),
+): ReviewRecord {
+	const review = storage.getReview(reviewId);
+	if (!review) throw new Error(`Review '${reviewId}' não encontrada.`);
+	if (!isActiveRunStatus(review.status)) return review;
+	return storage.updateReview(reviewId, { heartbeatAt: now, updatedAt: now }) ?? review;
+}
+
 /**
  * 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;
@@ -87,7 +117,11 @@ export function pingFindingsStatus(
 	state: FindingsStateFile,
 ): ReviewRecord {
 	const previous = storage.getReview(reviewId)?.status ?? null;
+	const status = statusAfterFindingsChange(previous, state);
 	return writeRunStatus(storage, reviewId, {
-		status: statusAfterFindingsChange(previous, state),
+		status,
+		// Só a correção em andamento é uma execução: triagem/reviewing não
+		// devem renovar o heartbeat (era a origem do "timeout falso").
+		touch: status === "fixing",
 	});
 }

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

@@ -102,6 +102,8 @@ export class FileStorageProvider implements StorageProvider {
 		if (patch.status !== undefined) updated.status = patch.status;
 		if (patch.resetStartedAt) updated.startedAt = now;
 		else if (patch.startedAt !== undefined) updated.startedAt = patch.startedAt;
+		if (patch.resetHeartbeat) updated.heartbeatAt = undefined;
+		else if (patch.heartbeatAt !== undefined) updated.heartbeatAt = patch.heartbeatAt;
 		updated.updatedAt = patch.updatedAt ?? now;
 		return this.writeReview(updated);
 	}

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

@@ -30,6 +30,7 @@ export type ReviewRow = {
 	reviewed_at: string | null;
 	status: string | null;
 	started_at: string | null;
+	heartbeat_at: string | null;
 	created_at: string;
 	updated_at: string;
 };
@@ -96,6 +97,7 @@ export function reviewFromRow(row: ReviewRow): ReviewRecord {
 		reviewedAt: row.reviewed_at ?? undefined,
 		status: (row.status as ReviewRecord["status"]) ?? null,
 		startedAt: row.started_at ?? undefined,
+		heartbeatAt: row.heartbeat_at ?? undefined,
 		createdAt: row.created_at,
 		updatedAt: row.updated_at,
 	};

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

@@ -7,7 +7,7 @@
 
 import type { Database } from "bun:sqlite";
 
-export const SCHEMA_VERSION = 1;
+export const SCHEMA_VERSION = 2;
 
 const DDL = `
 CREATE TABLE IF NOT EXISTS reviews (
@@ -24,6 +24,7 @@ CREATE TABLE IF NOT EXISTS reviews (
 	reviewed_at TEXT,
 	status TEXT,
 	started_at TEXT,
+	heartbeat_at TEXT,
 	created_at TEXT NOT NULL,
 	updated_at TEXT NOT NULL,
 	UNIQUE(repo_key, branch)
@@ -103,6 +104,13 @@ export function migrate(db: Database, path: string): void {
 
 	db.transaction(() => {
 		db.exec(DDL);
+		// v2: heartbeat explícito da execução (bancos v1 não tinham a coluna).
+		const columns = db.query("PRAGMA table_info(reviews)").all() as {
+			name: string;
+		}[];
+		if (!columns.some((column) => column.name === "heartbeat_at")) {
+			db.exec("ALTER TABLE reviews ADD COLUMN heartbeat_at TEXT");
+		}
 		db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
 	})();
 }

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

@@ -33,7 +33,7 @@ import { migrate } from "./schema";
 
 /** Colunas mutáveis de review (camel → snake). */
 const REVIEW_PATCH_COLUMNS: Record<
-	Exclude<keyof ReviewPatch, "resetStartedAt">,
+	Exclude<keyof ReviewPatch, "resetStartedAt" | "resetHeartbeat">,
 	string
 > = {
 	branch: "branch",
@@ -45,6 +45,7 @@ const REVIEW_PATCH_COLUMNS: Record<
 	reviewedAt: "reviewed_at",
 	status: "status",
 	startedAt: "started_at",
+	heartbeatAt: "heartbeat_at",
 	updatedAt: "updated_at",
 };
 
@@ -159,6 +160,9 @@ export class SQLiteStorageProvider implements StorageProvider {
 			sets.push("started_at = ?");
 			params.push(now);
 		}
+		if (patch.resetHeartbeat) {
+			sets.push("heartbeat_at = NULL");
+		}
 		if (patch.updatedAt === undefined) {
 			sets.push("updated_at = ?");
 			params.push(now);

package/src/core/storage/types.ts

@@ -36,6 +36,11 @@ export type ReviewRecord = {
 	reviewedAt?: string;
 	status: ReviewStatus | null;
 	startedAt?: string;
+	/**
+	 * Último sinal de vida de uma execução ativa (`reviewing`/`fixing`).
+	 * Diferente de `updatedAt`: não muda com triagem/sync — só com a execução.
+	 */
+	heartbeatAt?: string;
 	createdAt: string;
 	updatedAt: string;
 };
@@ -53,11 +58,14 @@ export type ReviewPatch = Partial<
 		| "reviewedAt"
 		| "status"
 		| "startedAt"
+		| "heartbeatAt"
 		| "updatedAt"
 	>
 > & {
 	/** Reinicia o `startedAt` no início de um novo ciclo de revisão. */
 	resetStartedAt?: boolean;
+	/** Limpa o heartbeat (execução terminou). */
+	resetHeartbeat?: boolean;
 };
 
 /** Entrada de `getOrCreateReview`. */
@@ -81,6 +89,7 @@ export type ArtifactKind =
 	| "context-summary"
 	| "finding-report"
 	| "review"
+	| "resume"
 	| "domain-review"
 	| "verify"
 	| "other";

package/src/server/client/App.tsx

@@ -1,25 +1,31 @@
 /**
  * App: layout do servidor — sidebar de execuções, header fixo (abas segmentadas,
- * auto-refresh e reancoragem), KPIs, filtros e os painéis de findings/artefatos.
- * Concentra o estado e as chamadas à API.
+ * auto-refresh e reancoragem), KPIs, filtros e os painéis de resumo/findings/
+ * artefatos. Concentra o estado e as chamadas à API.
  */
 
 import { useCallback, useEffect, useMemo, useRef, useState } from "preact/hooks";
 import { ArtifactsPanel } from "./ArtifactsPanel";
 import { AutoRefresh } from "./AutoRefresh";
-import { api, computeSummary } from "./api";
-import { AUTO_REFRESH_MS, TAB_CAPTIONS } from "./constants";
 import { Filters, type FiltersState } from "./Filters";
 import { FindingsList } from "./FindingsList";
-import { Layers, ListIcon, Refresh, Send } from "./icons";
+import { FileText, Layers, ListIcon, Refresh, Send } from "./icons";
+import { ResumePanel } from "./ResumePanel";
 import { RunList } from "./RunList";
 import { SubmitModal } from "./SubmitModal";
 import { SummaryBar } from "./SummaryBar";
-import type { Finding, FindingsResponse, RunSummary } from "./types";
+import { api, computeSummary } from "./utils/api";
+import { AUTO_REFRESH_MS, TAB_CAPTIONS } from "./utils/constants";
+import type { Finding, FindingsResponse, RunSummary } from "./utils/types";
 
-type Tab = "findings" | "artifacts";
+type Tab = "resume" | "findings" | "artifacts";
 
 const TABS: { id: Tab; label: string; hint: string }[] = [
+	{
+		id: "resume",
+		label: "Resumo",
+		hint: "Visão principal da revisão: negócio, números e pontos técnicos",
+	},
 	{
 		id: "findings",
 		label: "Findings",
@@ -36,7 +42,7 @@ export function App() {
 	const [runs, setRuns] = useState<RunSummary[]>([]);
 	const [slug, setSlug] = useState<string | null>(null);
 	const [data, setData] = useState<FindingsResponse | null>(null);
-	const [tab, setTab] = useState<Tab>("findings");
+	const [tab, setTab] = useState<Tab>("resume");
 	const [filters, setFilters] = useState<FiltersState>({
 		query: "",
 		decision: "all",
@@ -200,7 +206,9 @@ export function App() {
 								class={`seg-btn${tab === item.id ? " active" : ""}`}
 								onClick={() => setTab(item.id)}
 							>
-								{item.id === "findings" ? (
+								{item.id === "resume" ? (
+									<FileText size={15} />
+								) : item.id === "findings" ? (
 									<ListIcon size={15} />
 								) : (
 									<Layers size={15} />
@@ -254,6 +262,15 @@ export function App() {
 					</div>
 					{error && <p class="error">{error}</p>}
 
+					{slug && tab === "resume" && data && (
+						<ResumePanel
+							slug={slug}
+							branch={branch}
+							findings={data.findings}
+							summary={summary}
+							onOpenArtifacts={() => setTab("artifacts")}
+						/>
+					)}
 					{slug && tab === "findings" && data && (
 						<>
 							<SummaryBar summary={summary} />

package/src/server/client/ArtifactsPanel.tsx

@@ -1,20 +1,23 @@
 /**
  * Painel de artefatos: lista todos os artefatos persistidos da run e renderiza
- * o conteúdo bruto. JSON ganha destaque de sintaxe; briefs e relatórios são
+ * o conteúdo bruto. JSON ganha destaque de sintaxe; markdown é renderizado com
+ * o mesmo parser/highlight do restante da UI. Briefs e relatórios ficam
  * auditáveis pela mesma navegação.
  */
 
 import { useEffect, useMemo, useState } from "preact/hooks";
-import { api } from "./api";
+import { MarkdownText } from "./MarkdownText";
+import { api } from "./utils/api";
 import {
 	ARTIFACT_KIND_LABELS,
 	describeArtifact,
 	displayArtifactName,
 	groupArtifacts,
 	isJsonArtifact,
-} from "./constants";
-import { formatJson, highlightJson } from "./json-highlight";
-import type { ArtifactMeta } from "./types";
+	isMarkdownArtifact,
+} from "./utils/constants";
+import { formatJson, highlightJson } from "./utils/json-highlight";
+import type { ArtifactMeta } from "./utils/types";
 
 /** Prefere o relatório consolidado; senão, o primeiro artefato disponível. */
 function pickDefault(items: ArtifactMeta[]): string {
@@ -149,6 +152,10 @@ export function ArtifactsPanel({ slug }: { slug: string }) {
 					) : selected ? (
 						isJsonArtifact(selected) ? (
 							<JsonView content={content} />
+						) : isMarkdownArtifact(selected) ? (
+							<div class="artifact-view artifact-markdown">
+								<MarkdownText text={content} />
+							</div>
 						) : (
 							<pre class="artifact-view">{content || "—"}</pre>
 						)

package/src/server/client/AutoRefresh.tsx

@@ -6,7 +6,7 @@
  */
 
 import { useEffect, useState } from "preact/hooks";
-import { formatElapsed } from "./format";
+import { formatElapsed } from "./utils/format";
 
 export function AutoRefresh({
 	lastSync,