@payconductor/houndsman 0.1.0 → 0.1.1

package/src/server/client/SummaryBar.tsx

@@ -0,0 +1,21 @@
+/**
+ * Barra de resumo da triagem (total, presentes e contagens por decisão/execução).
+ */
+
+import { DECISION_LABELS, DECISIONS } from "./constants";
+import type { Summary } from "./types";
+
+export function SummaryBar({ summary }: { summary: Summary }) {
+	return (
+		<div class="summary-bar">
+			<span>Total: {summary.total}</span>
+			<span>Presentes: {summary.present}</span>
+			{DECISIONS.filter((decision) => decision !== "pending").map((decision) => (
+				<span key={decision}>
+					{DECISION_LABELS[decision]}: {summary.byDecision[decision] ?? 0}
+				</span>
+			))}
+			<span>Feitos: {summary.byExecState.done ?? 0}</span>
+		</div>
+	);
+}

package/src/server/client/api.ts

@@ -0,0 +1,37 @@
+/**
+ * Helpers de acesso à API local do servidor.
+ */
+
+import { DECISIONS, EXEC_STATES, SEVERITY_ORDER } from "./constants";
+import type { Decision, ExecState, Finding, Severity, Summary } from "./types";
+
+/** `fetch` JSON: lança com o corpo do erro quando a resposta não é 2xx. */
+export async function api<T>(path: string, init?: RequestInit): Promise<T> {
+	const res = await fetch(path, init);
+	if (!res.ok) throw new Error((await res.text()) || `HTTP ${res.status}`);
+	return (await res.json()) as T;
+}
+
+/** Recalcula o resumo a partir dos findings atuais (contadores vivos na UI). */
+export function computeSummary(findings: Finding[]): Summary {
+	const byDecision = Object.fromEntries(DECISIONS.map((d) => [d, 0])) as Record<
+		Decision,
+		number
+	>;
+	const byExecState = Object.fromEntries(EXEC_STATES.map((e) => [e, 0])) as Record<
+		ExecState,
+		number
+	>;
+	const bySeverity = Object.fromEntries(SEVERITY_ORDER.map((s) => [s, 0])) as Record<
+		Severity,
+		number
+	>;
+	let present = 0;
+	for (const finding of findings) {
+		if (finding.present) present++;
+		byDecision[finding.decision]++;
+		byExecState[finding.execState]++;
+		bySeverity[finding.severity]++;
+	}
+	return { total: findings.length, present, byDecision, byExecState, bySeverity };
+}

package/src/server/client/constants.ts

@@ -0,0 +1,63 @@
+/**
+ * Constantes de apresentação do cliente (labels, ordem, emojis).
+ */
+
+import type { Decision, ExecState, Severity } from "./types";
+
+export const SEVERITY_EMOJI: Record<Severity, string> = {
+	blocking: "❌",
+	attention: "⚠️",
+	suggestion: "💡",
+	nit: "🔎",
+};
+
+export const SEVERITY_ORDER: Severity[] = ["blocking", "attention", "suggestion", "nit"];
+
+export const DECISIONS: Decision[] = ["pending", "execute", "ignore"];
+
+export const DECISION_LABELS: Record<Decision, string> = {
+	pending: "Pendente",
+	execute: "Executar",
+	ignore: "Ignorar",
+};
+
+export const EXEC_STATES: ExecState[] = ["pending", "in_progress", "done", "stale"];
+
+export const EXEC_LABELS: Record<ExecState, string> = {
+	pending: "exec: pendente",
+	in_progress: "exec: em andamento",
+	done: "exec: feito",
+	stale: "exec: stale",
+};
+
+/** Artefatos que podem ser lidos na aba "Artefatos". */
+export const ARTIFACTS = [
+	"manifest.json",
+	"classification.json",
+	"candidates.json",
+	"context-summary.json",
+	"review.md",
+] as const;
+
+export type ArtifactName = (typeof ARTIFACTS)[number];
+
+/** Descrição de cada artefato (mostrada ao selecioná-lo na aba). */
+export const ARTIFACT_INFO: Record<ArtifactName, string> = {
+	"manifest.json":
+		"Resumo da execução: watchdogs ativos, arquivos, orçamento, churn, Jev e contexto da PR.",
+	"classification.json":
+		"Classificação do diff: watchdogs ativados por arquivo, status (A/M/D/R) e churn por arquivo.",
+	"candidates.json":
+		"Indícios da pré-análise Jev (regra + arquivo + confiança) — não são achados.",
+	"context-summary.json":
+		"Resumo da PR (objetivo, motivação e alterações) gerado no Passo 0.",
+	"review.md": "Relatório consolidado da revisão — o entregável.",
+};
+
+/** Legenda única de cada aba (explica o que a aba é; mostrada quando selecionada). */
+export const TAB_CAPTIONS = {
+	findings:
+		"Triagem dos achados da revisão: decida Executar, Ignorar ou deixe Pendente — o comentário orienta o auto-fix. Agente: houndsman findings list --decision pending --json · findings done <id>.",
+	artifacts:
+		"Artefatos brutos da run: manifesto, classificação, candidatos Jev, contexto da PR e o relatório consolidado (review.md).",
+} as const;

package/src/server/client/index.tsx

@@ -0,0 +1,12 @@
+/**
+ * Entry do cliente (Preact): monta o `<App />` no `#app`.
+ *
+ * Bundle gerado em memória por `Bun.build` (`client-build.ts`). Os componentes
+ * vivem em arquivos irmãos nesta pasta (`App.tsx`, `RunList.tsx`, ...).
+ */
+
+import { render } from "preact";
+import { App } from "./App";
+
+const root = document.getElementById("app");
+if (root) render(<App />, root);

package/src/server/client/types.ts

@@ -0,0 +1,48 @@
+/**
+ * Tipos compartilhados do cliente (espelham `src/core/findings-state.ts`).
+ *
+ * São um espelho minimalista do contrato da API — evita importar o núcleo
+ * (Node) no bundle do navegador.
+ */
+
+export type Severity = "blocking" | "attention" | "suggestion" | "nit";
+export type Decision = "pending" | "execute" | "ignore";
+export type ExecState = "pending" | "in_progress" | "done" | "stale";
+
+export type Finding = {
+	id: string;
+	rule: string;
+	severity: Severity;
+	file: string;
+	line: number | null;
+	message: string;
+	action: string;
+	evidence?: string;
+	count: number;
+	present: boolean;
+	decision: Decision;
+	comment?: string;
+	execState: ExecState;
+	watchdogIds: string[];
+};
+
+export type Summary = {
+	total: number;
+	present: number;
+	byDecision: Record<Decision, number>;
+	byExecState: Record<ExecState, number>;
+	bySeverity: Record<Severity, number>;
+};
+
+export type RunSummary = {
+	slug: string;
+	branch: string;
+	updatedAt?: string;
+	summary: Summary;
+};
+
+export type FindingsResponse = {
+	branch: string;
+	findings: Finding[];
+	summary: Summary;
+};

package/src/server/client-build.ts

@@ -0,0 +1,47 @@
+/**
+ * Empacota o cliente Preact em memória (Bun.build) — sem build step no pacote.
+ *
+ * Sem cache por padrão: o bundle é refeito quando algum arquivo do cliente muda
+ * (comparação por mtime), então editar a UI não exige reiniciar o servidor. O
+ * navegador também não cacheia (`cache-control: no-store` + `?v=` na URL).
+ */
+
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+let cached: string | null = null;
+let cachedStamp = -1;
+
+/** Maior mtime entre os arquivos do cliente (recursivo). */
+function sourceStamp(dir: string): number {
+	let stamp = 0;
+	for (const entry of readdirSync(dir, { withFileTypes: true })) {
+		const full = join(dir, entry.name);
+		stamp = Math.max(
+			stamp,
+			entry.isDirectory() ? sourceStamp(full) : statSync(full).mtimeMs,
+		);
+	}
+	return stamp;
+}
+
+/** Bundle ESM do cliente (target browser). Lança se o build falhar. */
+export async function buildClientBundle(): Promise<string> {
+	const sourceDir = join(import.meta.dir, "client");
+	const stamp = sourceStamp(sourceDir);
+	if (cached !== null && stamp === cachedStamp) return cached;
+
+	const result = await Bun.build({
+		entrypoints: [join(sourceDir, "index.tsx")],
+		target: "browser",
+		format: "esm",
+		jsx: { runtime: "automatic", importSource: "preact" },
+	});
+	if (!result.success || result.outputs.length === 0) {
+		const details = (result.logs ?? []).map((log) => log.message).join("\n");
+		throw new Error(`Falha ao empacotar o cliente do houndsman.\n${details}`);
+	}
+	cached = await result.outputs[0].text();
+	cachedStamp = stamp;
+	return cached;
+}

package/src/server/index.ts

@@ -0,0 +1,365 @@
+/**
+ * Servidor local do houndsman (`Bun.serve`) — UI de triagem + artefatos.
+ *
+ * Serve um SPA Preact (bundle em memória) + uma API JSON sobre o `state.json`
+ * das runs em `.houndsman/.runs/`. Sem dependências além do Bun e do Preact.
+ * Bind padrão em `127.0.0.1` — ferramenta local, sem autenticação.
+ */
+
+import { join } from "node:path";
+import { mediaPath } from "../core/assets";
+import { type HoundsmanConfig, resolveArtifactDir } from "../core/config";
+import {
+	applyFindingUpdate,
+	buildStateFromRunDir,
+	emptyState,
+	type FindingDecision,
+	type FindingExecState,
+	type FindingsFilter,
+	type FindingsStateFile,
+	FindingsStateStore,
+	type FindingUpdate,
+	fileReader,
+	filterFindings,
+	reorder,
+	type SyncResult,
+	summarize,
+	syncState,
+} from "../core/findings-state";
+import { STATE_FILE } from "../core/paths";
+import type { Severity } from "../core/types";
+import { listRunSlugs, readRunFile, readRunJson, runDirForSlug } from "./artifacts";
+import { buildClientBundle } from "./client-build";
+
+type BunServer = ReturnType<typeof Bun.serve>;
+
+// ---------------------------------------------------------------------------
+// Helpers de resposta
+// ---------------------------------------------------------------------------
+
+function json(data: unknown, status = 200): Response {
+	return new Response(JSON.stringify(data), {
+		status,
+		headers: { "content-type": "application/json; charset=utf-8" },
+	});
+}
+
+function text(body: string, contentType: string, status = 200): Response {
+	return new Response(body, { status, headers: { "content-type": contentType } });
+}
+
+/** Resposta sem cache — o servidor é local; o navegador sempre pega a versão nova. */
+function noStore(body: string, contentType: string): Response {
+	return new Response(body, {
+		headers: {
+			"content-type": contentType,
+			"cache-control": "no-store, no-cache, must-revalidate",
+		},
+	});
+}
+
+function notFound(detail = "não encontrado"): Response {
+	return json({ error: detail }, 404);
+}
+
+// ---------------------------------------------------------------------------
+// Estado / dados
+// ---------------------------------------------------------------------------
+
+function buildForRun(dir: string, slug: string): FindingsStateFile | null {
+	const manifest = readRunJson<{ branch?: string }>(dir, "manifest.json");
+	return buildStateFromRunDir(dir, manifest?.branch ?? slug, fileReader(process.cwd()));
+}
+
+/**
+ * Lê o estado da run. Se ausente, reconstrói dos artefatos e PERSISTE — os ids
+ * são aleatórios, então precisam ser estáveis entre requisições.
+ */
+function loadState(dir: string, slug: string): FindingsStateFile {
+	const store = new FindingsStateStore(join(dir, STATE_FILE), slug);
+	const existing = store.read();
+	if (existing) return existing;
+	const built = buildForRun(dir, slug);
+	if (built) {
+		store.write(built);
+		return built;
+	}
+	return emptyState(slug);
+}
+
+function listRuns(artifactDir: string): unknown[] {
+	return listRunSlugs(artifactDir).map((slug) => {
+		const dir = join(artifactDir, slug);
+		const state = loadState(dir, slug);
+		const manifest = readRunJson<{ branch?: string; generatedAt?: string }>(
+			dir,
+			"manifest.json",
+		);
+		return {
+			slug,
+			branch: state.branch || manifest?.branch || slug,
+			updatedAt: state.updatedAt,
+			summary: summarize(state),
+		};
+	});
+}
+
+function runDetail(dir: string, slug: string): unknown {
+	const state = loadState(dir, slug);
+	const classification = readRunJson<{
+		watchdogs?: Record<string, string[]>;
+		unclassified?: string[];
+		deleted?: string[];
+	}>(dir, "classification.json");
+	return {
+		slug,
+		branch: state.branch || slug,
+		manifest: readRunJson(dir, "manifest.json"),
+		summary: summarize(state),
+		watchdogs: Object.keys(classification?.watchdogs ?? {}),
+		unclassified: classification?.unclassified ?? [],
+		deleted: classification?.deleted ?? [],
+	};
+}
+
+function findingsFor(dir: string, slug: string, params: URLSearchParams): unknown {
+	const state = loadState(dir, slug);
+	const filter: FindingsFilter = {
+		decision: (params.get("decision") as FindingDecision) || undefined,
+		execState: (params.get("exec") as FindingExecState) || undefined,
+		severity: (params.get("severity") as Severity) || undefined,
+		watchdog: params.get("watchdog") || undefined,
+		file: params.get("file") || undefined,
+		includeAbsent: params.get("all") === "1",
+	};
+	return {
+		branch: state.branch,
+		findings: filterFindings(state, filter),
+		summary: summarize(state),
+	};
+}
+
+async function updateFinding(
+	dir: string,
+	slug: string,
+	id: string,
+	request: Request,
+): Promise<Response> {
+	const body = (await request.json().catch(() => ({}))) as FindingUpdate;
+	const store = new FindingsStateStore(join(dir, STATE_FILE), slug);
+	const state = store.read() ?? buildForRun(dir, slug) ?? emptyState(slug);
+	const finding = state.findings[id];
+	if (!finding) return notFound(`finding '${id}' não encontrado`);
+	applyFindingUpdate(finding, body);
+	reorder(state);
+	store.write(state);
+	return json({ finding });
+}
+
+function syncRun(dir: string, slug: string): Response {
+	const store = new FindingsStateStore(join(dir, STATE_FILE), slug);
+	const state = store.read() ?? buildForRun(dir, slug) ?? emptyState(slug);
+	const result: SyncResult = syncState(state, fileReader(process.cwd()));
+	store.write(state);
+	return json({ result, summary: summarize(state) });
+}
+
+function serveArtifact(dir: string, name: string): Response {
+	if (!/\.(json|md)$/i.test(name)) return notFound("tipo de artefato não servido");
+	const content = readRunFile(dir, name);
+	if (content === null) return notFound(`artefato '${name}' não encontrado`);
+	const type = name.toLowerCase().endsWith(".json")
+		? "application/json; charset=utf-8"
+		: "text/markdown; charset=utf-8";
+	return text(content, type);
+}
+
+// ---------------------------------------------------------------------------
+// Rotas
+// ---------------------------------------------------------------------------
+
+const API_RUN = /^\/api\/runs\/([^/]+)(\/.*)?$/;
+const LOGO_FILE = "logo.png";
+
+/** Serve a logo do pacote (`assets/logo.png`). */
+async function serveLogo(): Promise<Response> {
+	const file = Bun.file(mediaPath(LOGO_FILE));
+	if (!(await file.exists())) return notFound("logo não encontrada");
+	return new Response(file, {
+		headers: { "cache-control": "no-store" },
+	});
+}
+
+async function route(request: Request, artifactDir: string): Promise<Response> {
+	const url = new URL(request.url);
+	const path = url.pathname;
+
+	if (path === "/" || path === "/index.html") {
+		return noStore(renderShell(), "text/html; charset=utf-8");
+	}
+	if (path === "/assets/app.js") {
+		return noStore(await buildClientBundle(), "text/javascript; charset=utf-8");
+	}
+	if (path === `/assets/${LOGO_FILE}`) return serveLogo();
+	if (path === "/api/health") return json({ ok: true });
+
+	if (path === "/api/runs" && request.method === "GET") {
+		return json({ runs: listRuns(artifactDir) });
+	}
+
+	const match = path.match(API_RUN);
+	if (!match) return notFound();
+	const slug = decodeURIComponent(match[1]);
+	const rest = match[2] ?? "";
+	const dir = runDirForSlug(artifactDir, slug);
+	if (!dir) return notFound(`run '${slug}' não encontrada`);
+
+	if (rest === "" || rest === "/") return json(runDetail(dir, slug));
+
+	if (rest === "/findings" && request.method === "GET") {
+		return json(findingsFor(dir, slug, url.searchParams));
+	}
+	if (rest === "/sync" && request.method === "POST") return syncRun(dir, slug);
+
+	const findingMatch = rest.match(/^\/findings\/([^/]+)$/);
+	if (findingMatch) {
+		const id = decodeURIComponent(findingMatch[1]);
+		if (request.method === "GET") {
+			const state = loadState(dir, slug);
+			const finding = state.findings[id];
+			return finding
+				? json({ finding })
+				: notFound(`finding '${id}' não encontrado`);
+		}
+		if (request.method === "PATCH" || request.method === "POST") {
+			return updateFinding(dir, slug, id, request);
+		}
+	}
+
+	const artifactMatch = rest.match(/^\/artifacts\/(.+)$/);
+	if (artifactMatch && request.method === "GET") {
+		return serveArtifact(dir, decodeURIComponent(artifactMatch[1]));
+	}
+
+	return notFound();
+}
+
+/** Cria o handler de requisições (testável sem abrir porta). */
+export function createRequestHandler(
+	config: HoundsmanConfig,
+): (request: Request) => Promise<Response> {
+	const artifactDir = resolveArtifactDir(config);
+	return async (request) => {
+		try {
+			return await route(request, artifactDir);
+		} catch (error) {
+			return json(
+				{ error: error instanceof Error ? error.message : String(error) },
+				500,
+			);
+		}
+	};
+}
+
+export type ServerOptions = {
+	config: HoundsmanConfig;
+	port?: number;
+	host?: string;
+};
+
+/** Sobe o servidor e devolve a instância + URL. */
+export function startServer(options: ServerOptions): { server: BunServer; url: string } {
+	const host = options.host ?? "127.0.0.1";
+	const port = options.port ?? 7331;
+	const server = Bun.serve({
+		hostname: host,
+		port,
+		fetch: createRequestHandler(options.config),
+	});
+	return { server, url: `http://${host}:${server.port}` };
+}
+
+// ---------------------------------------------------------------------------
+// Shell (HTML + CSS)
+// ---------------------------------------------------------------------------
+
+const STYLES = `
+:root { color-scheme: dark; --bg:#161616; --panel:#1e1e1e; --border:#2f2f2f; --fg:#e6e6e6; --muted:#9aa0a6; --accent:#4c8dff; }
+* { box-sizing: border-box; }
+body { margin:0; font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif; background:var(--bg); color:var(--fg); }
+code, pre { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
+.app { display:flex; min-height:100vh; }
+.sidebar { width:240px; border-right:1px solid var(--border); background:var(--panel); padding:16px; }
+.brand { display:flex; align-items:center; gap:10px; margin-bottom:10px; }
+.brand .logo { width:40px; height:40px; object-fit:contain; border-radius:8px; background:#111; border:1px solid var(--border); }
+.sidebar h1 { font-size:16px; margin:0; }
+.sub { color:var(--muted); font-size:12px; margin:2px 0 12px; }
+.brand .sub { margin:0; }
+.runs { display:flex; flex-direction:column; gap:4px; }
+.run { text-align:left; background:transparent; border:1px solid transparent; border-radius:6px; color:var(--fg); padding:8px; cursor:pointer; display:flex; flex-direction:column; gap:2px; }
+.run:hover { background:#262626; }
+.run.active { border-color:var(--accent); background:#22304d; }
+.run-branch { font-weight:600; font-size:13px; }
+.run-meta { color:var(--muted); font-size:11px; }
+.main { flex:1; padding:16px 20px; max-width:980px; }
+.topbar { display:flex; justify-content:space-between; align-items:center; margin-bottom:12px; }
+.tabs { display:flex; gap:6px; flex-wrap:wrap; }
+.btn { background:#262626; color:var(--fg); border:1px solid var(--border); border-radius:6px; padding:5px 10px; font-size:12px; cursor:pointer; }
+.btn:hover { border-color:var(--accent); }
+.btn.active { background:#22304d; border-color:var(--accent); }
+.btn:disabled { opacity:.5; cursor:not-allowed; }
+.summary-bar { display:flex; gap:14px; flex-wrap:wrap; color:var(--muted); font-size:12px; border:1px solid var(--border); border-radius:6px; padding:8px 10px; margin-bottom:10px; }
+.filters { display:flex; gap:8px; flex-wrap:wrap; margin-bottom:10px; }
+.filters input[type=text], .filters input:not([type]), .filters select { background:#1b1b1b; color:var(--fg); border:1px solid var(--border); border-radius:6px; padding:6px 8px; font-size:12px; }
+.filters input:not([type]) { min-width:240px; }
+.toggle { color:var(--muted); font-size:12px; display:flex; align-items:center; gap:6px; }
+.caption { color:var(--muted); font-size:12px; line-height:1.5; margin:0 0 12px; }
+.caption code { background:#242424; padding:1px 5px; border-radius:4px; }
+.sev-group h2 { font-size:13px; text-transform:uppercase; letter-spacing:.04em; color:var(--muted); }
+.sev-group h2 .n { color:#666; }
+.card { background:var(--panel); border:1px solid var(--border); border-left:3px solid var(--border); border-radius:8px; padding:12px 14px; margin-bottom:10px; }
+.card.sev-blocking { border-left-color:#e5484d; }
+.card.sev-attention { border-left-color:#e3a008; }
+.card.sev-suggestion { border-left-color:#4c8dff; }
+.card.sev-nit { border-left-color:#666; }
+.card.absent { opacity:.55; }
+.card-head { display:flex; align-items:center; gap:10px; font-size:12px; color:var(--muted); }
+.card-head .loc { color:var(--fg); }
+.card-head .spacer { flex:1; }
+.card-head .id { color:#7c7c7c; }
+.rule { font-size:14px; margin:8px 0 4px; }
+.msg { margin:2px 0; font-size:13px; }
+.action { margin:2px 0; font-size:13px; color:#cfcfcf; }
+.evidence { background:#111; border:1px solid var(--border); border-radius:6px; padding:8px; font-size:12px; overflow:auto; }
+.card-foot { display:flex; gap:12px; color:var(--muted); font-size:11px; margin:6px 0; }
+.decisions { display:flex; gap:6px; flex-wrap:wrap; margin:6px 0; }
+.dec-execute.active { background:#153b21; border-color:#2ea043; }
+.dec-ignore.active { background:#3a2323; border-color:#e5484d; }
+.comment-row textarea { width:100%; min-height:44px; background:#1b1b1b; color:var(--fg); border:1px solid var(--border); border-radius:6px; padding:6px 8px; font-size:12px; }
+.comment-actions { display:flex; gap:6px; margin-top:6px; }
+.btn.done.active { background:#153b21; border-color:#2ea043; }
+.artifacts .tabs { margin-bottom:10px; }
+.artifact-desc { color:var(--muted); font-size:12px; line-height:1.5; margin:0 0 10px; }
+.artifact-view { background:#111; border:1px solid var(--border); border-radius:6px; padding:12px; font-size:12px; overflow:auto; max-height:70vh; }
+.error { color:#ff7b72; font-size:13px; }
+.empty { color:var(--muted); font-size:13px; }
+`;
+
+/** Id de build por processo — muda a URL do bundle a cada reinício do servidor. */
+const BUILD_ID = Date.now().toString(36);
+
+function renderShell(): string {
+	return `<!doctype html>
+<html lang="pt-BR">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>Houndsman — Revisões</title>
+<style>${STYLES}</style>
+</head>
+<body>
+<div id="app"></div>
+<script type="module" src="/assets/app.js?v=${BUILD_ID}"></script>
+</body>
+</html>`;
+}

package/src/skill/README.md

@@ -6,6 +6,12 @@ Revisão automatizada de Pull Requests — CLI independente + camada de configur
 
 - **houndsman** — o orquestrador/treinador (CLI + motor).
 - **watchdog** — cada agente especialista por domínio que audita o diff.
+- **brief** — instruções prontas para um watchdog (o prompt do subagente).
+- **findings** — os achados que o subagente grava em JSON (único output consumido).
+- **candidato (Jev)** — indício automático; **não** é achado (o watchdog confirma ou refuta).
+- **churn** — linhas adicionadas/removidas por arquivo; usado para priorizar a leitura.
+- **budget / orçamento** — teto de arquivos por brief; o excedente ("fora do orçamento")
+  não é revisado, mas fica registrado em `skipped`.
 - **review/revisão** — o processo de revisão.
 
 ## Quem executa o quê
@@ -31,7 +37,7 @@ Revisão automatizada de Pull Requests — CLI independente + camada de configur
 | `houndsman watchdog <id>` | Contexto de um watchdog (`--json`, `--rules`) |
 | `houndsman setup` | Cria a configuração inicial do projeto |
 | `houndsman update` | Sincroniza os arquivos auto-gerados (`.houndsman/core`) |
-| `houndsman doctor` | Valida a configuração e o ambiente (anti-drift) |
+| `houndsman doctor` | Valida a configuração, o ambiente e a credencial Jev (anti-drift) |
 | `houndsman test` | Roda a suíte de testes da lib |
 
 ### Flags
@@ -45,14 +51,15 @@ Tudo em `.houndsman/.runs/<branch-slug>/` (default do `artifactDir`, `.houndsman
 
 | Arquivo | Conteúdo |
 |---|---|
-| `classification.json` | Watchdogs ativados + status (A/M/D/R) |
+| `classification.json` | Watchdogs ativados + status (A/M/D/R) + churn |
 | `candidates.json` | Candidatos da pré-análise Jev |
 | `context.json` | Payload bruto da PR via `gh` (ou marcador de indisponível) |
 | `context-summary.json` | Resumo do subagente (objetivo/motivação/alterações) |
-| `briefs/<watchdog>.md` | Instruções prontas para cada sub-agente |
-| `manifest.json` | Resumo (watchdogs, arquivos, deletados, status, contexto) |
+| `briefs/<watchdog>.md` | Instruções prontas para cada sub-agente (arquivos por risco) |
+| `manifest.json` | Resumo (watchdogs, arquivos, deletados, status, contexto, orçamento, churn) |
 | `findings/<watchdog>.json` | Saída dos sub-agentes (schema `OUTPUT-FORMAT.md`) |
-| `review.md` | Relatório final |
+| `review.md` | Relatório final (achados agrupados por arquivo) |
+| `review.<watchdog>.md` | Relatório por domínio (só quando há achados) |
 
 ## Estrutura
 
@@ -72,7 +79,8 @@ src/
 │   ├── orchestrator.ts      # preparar/finalizar
 │   ├── brief.ts             # defaultRenderBrief + PROCEDURE
 │   ├── pr-context.ts        # contexto da PR via gh
-│   ├── file-classifier.ts   # classificação (via `classify` dos watchdogs)
+│   ├── file-classifier.ts   # classificação (via `classify` dos watchdogs) + churn
+│   ├── diff-source.ts       # diff único (patch + --numstat) p/ churn/orçamento
 │   ├── doc-discoverer.ts    # descoberta de docs
 │   ├── report-builder.ts    # dedupe/render do relatório
 │   ├── registry-check.ts    # validações anti-drift (config-driven)

package/src/skill/SETUP.md

@@ -7,8 +7,8 @@ no seu projeto é **autocontida** — não exige nenhuma dependência local do p
 
 - **Bun** — o CLI e o motor usam a runtime Bun (execução de TS, `Bun.spawnSync`).
 - **git** — o diff usa `git diff <base>...<head> --name-status`.
-- Opcional: **`gh`** (contexto da PR) e **`TYPESAFE_API_KEY`** (pré-análise Jev). Ambos são
-  **falha-aberto** — sem eles o pipeline segue normalmente.
+- Opcional: **`gh`** (contexto da PR) e **`TYPESAFE_API_KEY`** (pré-análise Jev). O pipeline
+  segue normalmente sem eles.
 
 ## Instalação (global)
 
@@ -59,7 +59,7 @@ bun run houndsman update      # reescreve .houndsman/core/** e .houndsman/.gitig
 ## Verificar
 
 ```bash
-bun run houndsman doctor         # valida config + ambiente (git/gh/Jev)
+bun run houndsman doctor         # valida config + ambiente + credencial Jev
 bun run houndsman test           # suíte da lib (project-agnóstica)
 bun run houndsman --base main    # prepara briefs do diff atual
 ```
@@ -76,6 +76,8 @@ Definido em `src/core/config.ts` (pacote) e espelhado em `.houndsman/core/types.
 | `exclusions` | Arquivos que nunca entram na revisão. |
 | `docMappings` | Path → documentação de contexto. |
 | `alwaysIncludeDocs` | Docs sempre presentes nos briefs (default `["AGENTS.md"]`). |
+| `budgets` | **Opcional** — teto de arquivos por brief (`maxFilesPerBrief`, default `40`); o excedente vira "fora do orçamento" (registrar em `skipped`). |
+| `concurrency` | **Opcional** — chamadas Jev simultâneas (`jev`, default `5`). |
 
 > O motor **não contém** ids, paths ou regras do projeto — tudo chega por `HoundsmanConfig`,
 > carregado em runtime a partir de `houndsman.config.ts` (ou `--config <path>`).