@payconductor/houndsman 0.0.0-stage → 0.1.0

package/src/core/report-builder.ts

@@ -0,0 +1,357 @@
+/**
+ * Consolidação dos relatórios JSON dos watchdogs em um markdown (biblioteca).
+ *
+ * Entrypoint: `cli/review.ts` (via `core/orchestrator.ts`). Deduplica achados
+ * por (file, line, rule), agrupa por severidade e renderiza a tabela de cobertura.
+ *
+ * Schema dos watchdogs: asset `OUTPUT-FORMAT.md` (embarcado em `src/skill/`).
+ */
+
+import type { JevCandidate } from "./jev";
+import { SEVERITY_EMOJI, SEVERITY_ORDER, type Severity, severityRank } from "./types";
+
+/** Resolve o nome legível de um watchdog (default: identidade). */
+export type WatchdogNameResolver = (watchdogId: string) => string;
+
+const identityName: WatchdogNameResolver = (id) => id;
+
+export type Finding = {
+	rule: string;
+	severity: Severity;
+	file: string;
+	line?: number;
+	message: string;
+	action: string;
+	evidence?: string;
+};
+
+export type WatchdogReport = {
+	watchdogId: string;
+	reviewedFiles: string[];
+	skipped: string[];
+	findings: Finding[];
+};
+
+/** Achado deduplicado, com todos os watchdogs que o apontaram. */
+export type MergedFinding = Finding & {
+	watchdogs: string[];
+};
+
+/** Resumo do contexto da PR (objetivo/motivação/resumo das alterações), gravado pelo subagente. */
+export type ContextSummary = {
+	available: boolean;
+	source?: {
+		number?: number;
+		title?: string;
+		url?: string;
+		base?: string;
+		head?: string;
+	};
+	objective?: string;
+	motivation?: string;
+	changeSummary?: string[];
+};
+
+const VALID_SEVERITIES = new Set<string>(SEVERITY_ORDER);
+
+/**
+ * Limites do resumo da PR: mantém o relatório e os briefs enxutos — evita
+ * confundir o watchdog humano e estourar o contexto da IA watchdog.
+ */
+const CONTEXT_LIMITS = {
+	objective: 200,
+	motivation: 240,
+	changeSummaryItem: 160,
+	changeSummaryItems: 4,
+} as const;
+
+/** Corta `value` em `max` caracteres, sinalizando com reticências. */
+function truncate(value: string, max: number): string {
+	return value.length <= max ? value : `${value.slice(0, max - 1).trimEnd()}…`;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers exportados (testáveis)
+// ---------------------------------------------------------------------------
+
+/** `feature/add-webhook` → `feature-add-webhook`. */
+export function sanitizeBranch(branch: string): string {
+	return branch
+		.trim()
+		.replace(/[/\\]+/g, "-")
+		.replace(/[^a-zA-Z0-9._-]+/g, "-")
+		.replace(/^-+|-+$/g, "")
+		.toLowerCase();
+}
+
+function isFinding(value: unknown): value is Finding {
+	if (typeof value !== "object" || value === null) return false;
+	const f = value as Record<string, unknown>;
+	return (
+		typeof f.rule === "string" &&
+		typeof f.severity === "string" &&
+		VALID_SEVERITIES.has(f.severity) &&
+		typeof f.file === "string" &&
+		typeof f.message === "string" &&
+		typeof f.action === "string" &&
+		(f.line === undefined || typeof f.line === "number")
+	);
+}
+
+/** Valida e normaliza um relatório. Retorna null se inválido. */
+export function parseWatchdogReport(raw: unknown, source: string): WatchdogReport | null {
+	if (typeof raw !== "object" || raw === null) {
+		console.error(`[report-builder] ${source}: não é um objeto JSON`);
+		return null;
+	}
+	const obj = raw as Record<string, unknown>;
+	if (typeof obj.watchdogId !== "string") {
+		console.error(`[report-builder] ${source}: campo 'watchdogId' ausente`);
+		return null;
+	}
+	if (!Array.isArray(obj.findings)) {
+		console.error(`[report-builder] ${source}: campo 'findings' ausente`);
+		return null;
+	}
+
+	const findings = obj.findings.filter((f) => {
+		if (!isFinding(f)) {
+			console.error(`[report-builder] ${source}: finding inválido ignorado`);
+			return false;
+		}
+		return true;
+	});
+
+	return {
+		watchdogId: obj.watchdogId,
+		reviewedFiles: Array.isArray(obj.reviewedFiles)
+			? (obj.reviewedFiles as string[])
+			: [],
+		skipped: Array.isArray(obj.skipped) ? (obj.skipped as string[]) : [],
+		findings,
+	};
+}
+
+/**
+ * Valida/normaliza o `context-summary.json` do subagente de contexto.
+ * Retorna null se indisponível ou sem conteúdo útil — a seção é omitida.
+ * Aplica limites de tamanho: o resumo precisa ser curto para não confundir o
+ * watchdog humano nem estourar o contexto da IA watchdog (briefs + relatório).
+ */
+export function parseContextSummary(raw: unknown): ContextSummary | null {
+	if (typeof raw !== "object" || raw === null) return null;
+	const obj = raw as Record<string, unknown>;
+	if (obj.available !== true) return null;
+
+	const text = (value: unknown, max = Number.POSITIVE_INFINITY): string | undefined => {
+		const trimmed = typeof value === "string" ? value.trim() : "";
+		return trimmed.length > 0 ? truncate(trimmed, max) : undefined;
+	};
+	const objective = text(obj.objective, CONTEXT_LIMITS.objective);
+	const motivation = text(obj.motivation, CONTEXT_LIMITS.motivation);
+	const changeSummary = (Array.isArray(obj.changeSummary) ? obj.changeSummary : [])
+		.map((item) => text(item, CONTEXT_LIMITS.changeSummaryItem))
+		.filter((item): item is string => item !== undefined)
+		.slice(0, CONTEXT_LIMITS.changeSummaryItems);
+
+	if (!objective && !motivation && changeSummary.length === 0) return null;
+
+	const src = (obj.source ?? {}) as Record<string, unknown>;
+	const source = {
+		number: typeof src.number === "number" ? src.number : undefined,
+		title: text(src.title),
+		url: text(src.url),
+		base: text(src.base),
+		head: text(src.head),
+	};
+
+	return { available: true, source, objective, motivation, changeSummary };
+}
+
+/** Deduplica achados por (file, line, rule), mesclando atribuição de watchdogs. */
+export function dedupeFindings(reports: WatchdogReport[]): MergedFinding[] {
+	const map = new Map<string, MergedFinding>();
+	for (const report of reports) {
+		for (const finding of report.findings) {
+			const key = `${finding.file}|${finding.line ?? ""}|${finding.rule}`;
+			const existing = map.get(key);
+			if (existing) {
+				if (!existing.watchdogs.includes(report.watchdogId)) {
+					existing.watchdogs.push(report.watchdogId);
+				}
+				// Mantém a versão de maior severidade (severidade + detalhes)
+				if (severityRank(finding.severity) < severityRank(existing.severity)) {
+					existing.severity = finding.severity;
+					existing.message = finding.message;
+					existing.action = finding.action;
+					existing.evidence = finding.evidence ?? existing.evidence;
+				}
+				continue;
+			}
+			map.set(key, { ...finding, watchdogs: [report.watchdogId] });
+		}
+	}
+	return [...map.values()].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);
+	});
+}
+
+function watchdogName(nameOf: WatchdogNameResolver, id: string): string {
+	return nameOf(id);
+}
+
+function renderFinding(finding: MergedFinding, nameOf: WatchdogNameResolver): string[] {
+	const location = finding.line ? `${finding.file}:${finding.line}` : finding.file;
+	const watchdogs = finding.watchdogs.map((r) => watchdogName(nameOf, r)).join(", ");
+	const lines = [
+		`- **${finding.rule}** — \`${location}\` · _${watchdogs}_`,
+		`  ${finding.message}`,
+		`  **Ação:** ${finding.action}`,
+	];
+	if (finding.evidence) {
+		lines.push(`  **Evidência:** \`${finding.evidence}\``);
+	}
+	lines.push("");
+	return lines;
+}
+
+function renderCoverage(
+	reports: WatchdogReport[],
+	coverage: { classified?: Record<string, string[]> },
+	nameOf: WatchdogNameResolver,
+): string[] {
+	const lines = [
+		"## Cobertura",
+		"",
+		"| Watchdog | Arquivos revisados | Findings |",
+		"|---|---|---|",
+	];
+	for (const report of reports) {
+		const expected = coverage.classified?.[report.watchdogId];
+		const reviewed = new Set(report.reviewedFiles);
+		const pending = expected ? expected.filter((f) => !reviewed.has(f)) : [];
+		const reviewedLabel =
+			expected && pending.length > 0
+				? `${report.reviewedFiles.length}/${expected.length} (faltam ${pending.length})`
+				: `${report.reviewedFiles.length}`;
+		lines.push(
+			`| ${watchdogName(nameOf, report.watchdogId)} | ${reviewedLabel} | ${report.findings.length} |`,
+		);
+	}
+	lines.push("");
+	return lines;
+}
+
+/** Candidatos Jev não confirmados por nenhum watchdog — revisão manual, não bloqueiam. */
+function renderUnconfirmedCandidates(
+	candidates: JevCandidate[],
+	merged: MergedFinding[],
+): string[] {
+	const confirmed = new Set(merged.map((f) => `${f.file}|${f.rule}`));
+	const pending = candidates.filter((c) => !confirmed.has(`${c.file}|${c.rule}`));
+	if (pending.length === 0) return [];
+	const lines = [
+		"## 🔎 Candidatos não verificados (Jev)",
+		"",
+		"> Indícios automáticos que nenhum watchdog confirmou. Revise manualmente — não bloqueiam.",
+		"",
+	];
+	for (const c of pending) {
+		lines.push(
+			`- \`${c.file}\` · **${c.severity}** · confiança ${c.confidence.toFixed(2)} · _${c.watchdogId}_`,
+			`  ${c.rule}`,
+			"",
+		);
+	}
+	return lines;
+}
+
+function renderConclusion(counts: Record<Severity, number>): string[] {
+	const status =
+		counts.blocking > 0
+			? "❌ Mudanças Necessárias"
+			: counts.attention > 0
+				? "⚠️ Aprovado com Ressalvas"
+				: "✅ Aprovado";
+	return [
+		"## Conclusão",
+		"",
+		`**Status:** ${status}`,
+		`**Resumo:** ${counts.blocking} violações bloqueantes, ${counts.attention} pontos de atenção, ${counts.suggestion} sugestões e ${counts.nit} nits.`,
+	];
+}
+
+/** Seção de contexto da PR (Objetivo / Motivação / Resumo das alterações). */
+function renderContext(context: ContextSummary): string[] {
+	const lines = ["## Contexto da PR", ""];
+	const src = context.source;
+
+	const ref = [src?.number ? `#${src.number}` : "", src?.title ?? ""]
+		.filter(Boolean)
+		.join(" ");
+	if (ref) lines.push(`**PR:** ${ref}${src?.url ? ` — ${src.url}` : ""}`);
+	if (src?.head && src?.base)
+		lines.push(`**Branch:** \`${src.head}\` → \`${src.base}\``);
+	if (context.objective) lines.push(`**Objetivo:** ${context.objective}`);
+	if (context.motivation) lines.push(`**Motivação:** ${context.motivation}`);
+	if (context.changeSummary && context.changeSummary.length > 0) {
+		lines.push("", "**Resumo das alterações:**", "");
+		for (const item of context.changeSummary) lines.push(`- ${item}`);
+	}
+	lines.push("");
+	return lines;
+}
+
+export function renderReport(
+	branch: string,
+	reports: WatchdogReport[],
+	merged: MergedFinding[],
+	coverage: { classified?: Record<string, string[]> },
+	context?: ContextSummary | null,
+	candidates?: JevCandidate[],
+	nameOf: WatchdogNameResolver = identityName,
+): string {
+	const now = new Date().toISOString().slice(0, 10);
+	const counts = {
+		blocking: merged.filter((f) => f.severity === "blocking").length,
+		attention: merged.filter((f) => f.severity === "attention").length,
+		suggestion: merged.filter((f) => f.severity === "suggestion").length,
+		nit: merged.filter((f) => f.severity === "nit").length,
+	};
+
+	const lines: string[] = [
+		`# PR Review — ${branch}`,
+		"",
+		`**Data:** ${now}`,
+		`**Watchdogs ativos:** ${reports.map((r) => r.watchdogId).join(", ") || "—"}`,
+		`**Achados:** ${counts.blocking} bloqueantes · ${counts.attention} atenção · ${counts.suggestion} sugestões · ${counts.nit} nits`,
+		"",
+	];
+
+	if (context) lines.push(...renderContext(context));
+
+	for (const severity of SEVERITY_ORDER) {
+		const items = merged.filter((f) => f.severity === severity);
+		if (items.length === 0) continue;
+		lines.push(`## ${SEVERITY_EMOJI[severity]} ${severity}`, "");
+		for (const finding of items) {
+			lines.push(...renderFinding(finding, nameOf));
+		}
+	}
+
+	if (merged.length === 0) {
+		lines.push("Nenhum achado. ✅", "");
+	}
+
+	if (candidates && candidates.length > 0) {
+		lines.push(...renderUnconfirmedCandidates(candidates, merged));
+	}
+
+	lines.push(...renderCoverage(reports, coverage, nameOf));
+	lines.push(...renderConclusion(counts));
+
+	return lines.join("\n");
+}

package/src/core/types.ts

@@ -0,0 +1,137 @@
+/**
+ * Tipos e constantes genéricas do motor de revisão (houndsman).
+ *
+ * Sem dependência do projeto: os ids de watchdog são derivados do
+ * `HoundsmanConfig` injetado pelo consumidor. `Severity` é a escala de achados;
+ * `Rule` e `WatchdogMeta` descrevem as regras consumidas pela renderização.
+ */
+
+import type { JevRuleSpec } from "./jev/jev-types";
+
+/** Severidade de um achado. `blocking` bloqueia o merge. */
+export type Severity = "blocking" | "attention" | "suggestion" | "nit";
+
+/** Ordem canônica de severidade (mais grave primeiro). */
+export const SEVERITY_ORDER: readonly Severity[] = [
+	"blocking",
+	"attention",
+	"suggestion",
+	"nit",
+];
+
+/** Emoji associado a cada severidade. */
+export const SEVERITY_EMOJI: Record<Severity, string> = {
+	blocking: "❌",
+	attention: "⚠️",
+	suggestion: "💡",
+	nit: "🔎",
+};
+
+/**
+ * Regra do watchdog: severidade + texto. O texto declara a polaridade de forma
+ * explícita — `Promover:` (algo que DEVE acontecer) ou `Evitar:`/`Não`/`Nunca`
+ * (algo que NÃO DEVE acontecer).
+ *
+ * `jev` (opcional) é a spec de pré-análise: quando presente, a regra vira uma
+ * pergunta tipada enviada ao modelo no Passo 1.5.
+ */
+export type Rule = {
+	severity: Severity;
+	text: string;
+	jev?: JevRuleSpec;
+};
+
+/**
+ * Entrada de classificação: como o watchdog casa um arquivo alterado.
+ *
+ * `value` é sempre um padrão (regex, estilo grep — fonte sem barras).
+ *
+ * - `filename` (padrão) → padrão aplicado ao caminho do arquivo.
+ * - `content`           → padrão aplicado ao conteúdo do arquivo.
+ */
+export type ClassifyRule = {
+	type?: "filename" | "content";
+	value: string;
+};
+
+export type WatchdogMeta = {
+	/** Nome legível do watchdog */
+	name: string;
+	/** Escopo de atuação (quais arquivos/pastas revisa) */
+	scope: string;
+	/** Arquivos que este watchdog cobre (classificação). */
+	classify?: readonly ClassifyRule[];
+	/** Regras do watchdog (texto com polaridade explícita: `Promover:`/`Evitar:`). */
+	rules: readonly Rule[];
+	/** Arquivos de documentação de contexto (caminhos relativos à raiz) */
+	contextFiles: string[];
+};
+
+/** Status de um arquivo alterado (git `--name-status`). */
+export type FileStatus =
+	| "added"
+	| "modified"
+	| "deleted"
+	| "renamed"
+	| "copied"
+	| "unknown";
+
+/** Status por arquivo, conforme o `classification.json`. */
+export type FileStatusMap = Record<string, { status: FileStatus; oldPath?: string }>;
+
+/** Contexto da PR injetado no brief (estrutural — sem dependência de runtime). */
+export type WatchdogRenderContext = {
+	objective?: string;
+	motivation?: string;
+	changeSummary?: string[];
+};
+
+/** Candidato pré-analisado (Jev) exibido no brief. */
+export type WatchdogRenderCandidate = {
+	file: string;
+	severity: Severity;
+	confidence: number;
+	rule: string;
+};
+
+/** Dados que o renderer do brief recebe (sem dependência de runtime do jev/cli). */
+export type WatchdogRenderArgs = {
+	watchdogId: string;
+	files: readonly string[];
+	statuses: FileStatusMap;
+	deleted: readonly string[];
+	branch: string;
+	outputPath: string;
+	outputFormatPath: string;
+	docs: readonly string[];
+	context?: WatchdogRenderContext | null;
+	candidates?: readonly WatchdogRenderCandidate[];
+};
+
+/** Definição completa de um watchdog — 1 por arquivo em `project/watchdogs/`. */
+export type WatchdogDefinition = WatchdogMeta & {
+	/** Id do watchdog (deve casar com a chave em `WATCHDOG_DEFINITIONS`). */
+	id: string;
+	/** Uma frase sobre o propósito (ex-`Objetivo` do .md). */
+	description: string;
+	/** Watchdog deve checar breaking change em arquivos deletados do seu domínio. */
+	breakingChange?: boolean;
+	/** Prioridade de arquivos/paths (ex-`O Que Revisar`). Opcional. */
+	reviewFocus?: readonly string[];
+	/** O que NUNCA carregar/enviar (ex-`NÃO carregar`). Opcional. */
+	exclude?: readonly string[];
+	/** Render customizado do brief; se omitido usa `defaultRenderBrief`.
+	 *  Recebe a própria definição (`def`) para reutilizar `defaultRenderBrief`
+	 *  sem criar dependência de runtime `registry → core`. */
+	renderBrief?: (args: WatchdogRenderArgs, def: WatchdogDefinition) => string[];
+};
+
+/** Helper de autoria: tipa o objeto do watchdog (id contra `WatchdogId`). */
+export function defineWatchdog(def: WatchdogDefinition): WatchdogDefinition {
+	return def;
+}
+
+/** Índice numérico da severidade (menor = mais grave). */
+export function severityRank(severity: Severity): number {
+	return SEVERITY_ORDER.indexOf(severity);
+}

package/src/core/watchdog-registry.ts

@@ -0,0 +1,43 @@
+/**
+ * Acesso tipado aos watchdogs de um `HoundsmanConfig` (biblioteca).
+ *
+ * Substitui o antigo barrel `registry/`. O motor não conhece ids concretos —
+ * tudo chega via `config`.
+ */
+
+import type { HoundsmanConfig } from "./config";
+import type { WatchdogDefinition } from "./types";
+
+/** Acesso tipado a um watchdog do projeto (id string em runtime). */
+export function getWatchdog<TId extends string>(
+	config: HoundsmanConfig<TId>,
+	watchdogId: string,
+): WatchdogDefinition {
+	return config.watchdogs[watchdogId as TId];
+}
+
+/** Busca null-safe por id string (runtime). */
+export function findWatchdog<TId extends string>(
+	config: HoundsmanConfig<TId>,
+	watchdogId: string,
+): WatchdogDefinition | null {
+	return config.watchdogs[watchdogId as TId] ?? null;
+}
+
+/** Contexto "essencial" do watchdog — SEM regras (docs/UI/inspeção). */
+export function getWatchdogContext<TId extends string>(
+	config: HoundsmanConfig<TId>,
+	watchdogId: string,
+) {
+	const { id, name, description, scope, reviewFocus, exclude, contextFiles } =
+		getWatchdog(config, watchdogId);
+	return {
+		id,
+		name,
+		description,
+		scope,
+		reviewFocus,
+		exclude,
+		contextFiles,
+	};
+}

package/src/index.ts

@@ -0,0 +1,56 @@
+/**
+ * API pública do `houndsman`.
+ *
+ * O consumidor importa daqui para definir a configuração do projeto
+ * (`houndsman.config.ts`): watchdogs, tipos e helpers de autoria.
+ */
+
+export { assetPath, OUTPUT_FORMAT_FILE } from "./core/assets";
+export { defaultRenderBrief, PROCEDURE, renderBrief } from "./core/brief";
+export type { HoundsmanConfig, HoundsmanConfigInput } from "./core/config";
+export { DEFAULT_ALWAYS_INCLUDE_DOCS, defineHoundsmanConfig } from "./core/config";
+export type { LoadedConfig } from "./core/config-loader";
+export {
+	CONFIG_FILE_CANDIDATES,
+	loadConfig,
+	resolveConfigPath,
+} from "./core/config-loader";
+export {
+	classifyEntries,
+	classifyRange,
+	isExcludedPath,
+	matchWatchdogs,
+	parseEntries,
+} from "./core/file-classifier";
+export {
+	ARTIFACT_DIR,
+	CORE_DIR,
+	CORE_SKILL_DIR,
+	OUTPUT_FORMAT_PATH,
+	PROJECT_DIR,
+	relFromRoot,
+} from "./core/paths";
+export { checkRegistry } from "./core/registry-check";
+export type {
+	ClassifyRule,
+	FileStatus,
+	FileStatusMap,
+	Rule,
+	Severity,
+	WatchdogDefinition,
+	WatchdogMeta,
+	WatchdogRenderArgs,
+	WatchdogRenderCandidate,
+	WatchdogRenderContext,
+} from "./core/types";
+export {
+	defineWatchdog,
+	SEVERITY_EMOJI,
+	SEVERITY_ORDER,
+	severityRank,
+} from "./core/types";
+export {
+	findWatchdog,
+	getWatchdog,
+	getWatchdogContext,
+} from "./core/watchdog-registry";

package/src/skill/AUDIT-PROTOCOL.md

@@ -0,0 +1,96 @@
+# Protocolo de Auditoria dos Watchdogs — houndsman
+
+Referência do Modo B do skill `houndsman-update`. Objetivo: garantir que as regras dos
+watchdogs validam **apenas padrões que o projeto aplica hoje**. Regras "utópicas" (não
+aplicadas em nenhuma parte do código) devem ser **removidas**, não apenas rebaixadas.
+
+---
+
+## Entradas
+
+1. `.houndsman/watchdogs/<id>.ts` — `WATCHDOG_DEFINITIONS[<id>]` é a fonte única de verdade:
+   `description`, `scope`, `rules` (severidade + texto), `classify`, `contextFiles`,
+   `reviewFocus`, `exclude`.
+2. `src/core/brief.ts` (no motor) — `PROCEDURE` (passos de revisão compartilhados).
+3. Ground truth (padrões reais do projeto):
+   - Documentos de convenção do projeto (ex.: `AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`).
+   - Documentação de arquitetura/domínio do projeto.
+   - Código-fonte real do domínio (fonte final da verdade).
+
+## Regra de ouro
+
+> Só é regra o que o projeto **aplica hoje** — mas como provar depende da **polaridade**:
+>
+> - Regra **afirmativa** (`Promover:`): a **ausência** do padrão no código prova que ele **não é
+>   aplicado** → `UTOPIAN` (remover/rebaixar). Não inferir intenção aspiracional.
+> - Regra **negativa** (`Evitar:`, `Não`, `Nunca`): a **ausência** do anti-padrão prova que a regra
+>   **é seguida** → `ALIGNED` (**manter**). Nunca remover uma regra negativa por "0 ocorrências".
+
+Use regra **geral e reutilizável** (padrão do domínio), nunca regra de negócio pontual amarrada a
+uma classe/use-case — isso é papel de teste automatizado.
+
+Use `grep_search`/`file_search`/`read_file` para **provar** cada veredito. Nunca
+classifique sem evidência (caminho de arquivo, linha, ou "0 ocorrências via grep X").
+
+## Taxonomia de veredito
+
+| Veredito | Significado | Ação proposta |
+|---|---|---|
+| `ALIGNED` | Padrão documentado E aplicado no código (regra negativa: anti-padrão **ausente**) | Manter |
+| `UTOPIAN` | Regra **afirmativa** cujo padrão não existe em lugar nenhum hoje | **Remover** |
+| `OUTDATED` | Já foi aplicado, mas o código mudou | Remover ou reescrever |
+| `MISCALIBRATED` | Regra válida, mas severidade errada | Ajustar severidade |
+| `DEAD-PATH` | `scope`/`contextFiles`/`classify` apontam para caminho/arquivo inexistente | Corrigir ou remover |
+
+## Formato do relatório
+
+Gravar `.houndsman-audit/<watchdog-id>.md`:
+
+```markdown
+# Auditoria — <Nome do watchdog> (`<watchdog-id>`)
+
+## Ground truth do domínio
+- Padrões reais observados (com caminhos de arquivo).
+- Caminhos reais do domínio (confirmar existência).
+
+## Veredito por regra
+
+| # | Severidade atual | Polaridade | Regra | Veredito | Evidência | Ação proposta |
+|---|---|---|---|---|---|---|
+| 1 | blocking | afirmativa | <texto da regra> | UTOPIAN | 0 matches em `src/...` | Remover |
+| 2 | attention | negativa | <texto da regra> | ALIGNED | 0 ocorrências do anti-padrão | Manter |
+| ... |
+
+## Correções de metadados
+- `scope`: ...
+- `contextFiles`: ...
+
+## Protocolo (procedimento)
+- Ajustes no `PROCEDURE` compartilhado (`src/core/brief.ts`) ou no `reviewFocus`/`exclude` do watchdog.
+
+## Resumo
+- Total de regras: N · ALIGNED: N · UTOPIAN: N · OUTDATED: N · MISCALIBRATED: N · DEAD-PATH: N
+- Regras a remover: ...
+- Regras a corrigir: ...
+```
+
+## Consolidação
+
+- Um relatório consolidado em `.houndsman-audit/audit-summary.md`.
+- Agrupar **temas transversais** (ex.: a mesma regra aparecia em 2 watchdogs).
+- Resolver conflitos: uma regra duplicada entre watchdogs deve viver no watchdog dono do domínio.
+
+## Disparo dos subagentes
+
+- 1 subagente por watchdog; despachar em ondas paralelas (ex.: 8 + 7).
+- Prompt mínimo:
+
+  > Você é um auditor do skill `houndsman` do {{projectName}}. Leia e siga
+  > `.houndsman/core/skill/AUDIT-PROTOCOL.md`. Watchdog alvo: `<watchdog-id>`. Audite CADA regra de
+  > `WATCHDOG_DEFINITIONS["<watchdog-id>"]` contra o código/docs reais, provando cada veredito.
+  > Grave `.houndsman-audit/<watchdog-id>.md`. Retorne: contagem por veredito,
+  > regras a REMOVER e a CORRIGIR. Não altere outros arquivos.
+
+## Idioma
+
+Relatórios em português. Código e identificadores em inglês. Seja sucinto.