@payconductor/houndsman 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Houndsman contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,195 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# houndsman
+
+Orquestrador de revisão de Pull Requests. Classifica o diff, despacha **watchdogs**
+especializados por domínio (um subagente por watchdog) e consolida os achados em um
+relatório único.
+
+> Review de PR no piloto automático: alguém aprova no "LGTM" sem ler, um `catch {}` engole
+> o erro e ninguém nota. Sexta às 18h a produção cobra a conta — e aí todo mundo lembra
+> daquela linha.
+
+![houndsman](assets/houndsman.png)
+
+**Terminologia:** **houndsman** = orquestrador/treinador (CLI + motor) · **watchdog** = cada
+agente especialista por domínio que audita o diff · **review/revisão** = o processo ·
+**Jev** = pré-análise opcional.
+
+---
+
+## Como iniciar
+
+Você monta o **seu time de cães de caça** (os watchdogs), cada um farejando um domínio
+diferente das PRs. O motor só coordena a caçada — as regras são problema seu.
+
+### 1. Pré-requisitos
+
+- **Bun** — runtime obrigatório.
+- **git** — o diff usa `git diff <base>...<head>`.
+- Opcionais, ambos **falha-aberto**: **`gh`** (contexto da PR) e **`TYPESAFE_API_KEY`**
+  (pré-análise Jev). Sem eles, a revisão roda igual.
+
+### 2. Instale o CLI (global)
+
+```bash
+bun add -g @payconductor/houndsman
+```
+
+### 3. Configure o projeto (uma vez)
+
+Na raiz do projeto:
+
+```bash
+bun run houndsman setup
+```
+
+Cria a camada `.houndsman/`, que é **autocontida** (não instala nada no seu projeto):
+
+| Caminho | Dono | O que é |
+|---|---|---|
+| `houndsman.config.ts` | você | Configuração do projeto (um objeto de dados) |
+| `.houndsman/watchdogs/` | você | Suas regras — começa com **1 watchdog de exemplo** |
+| `.houndsman/exclusions.ts` | você | Arquivos que nunca entram na revisão |
+| `.houndsman/doc-mappings.ts` | você | path → documentação de contexto |
+| `.houndsman/core/**` | auto | Tipos + docs do skill (sincronizados por `houndsman update`) |
+| `.agents/` · `.claude/` | auto | Ponteiros de skill dos harnesses |
+| `package.json` | — | Adiciona o script `"houndsman"` |
+
+> **Não existe "modo completo".** O `setup` já cria a camada inicial com um watchdog de
+> exemplo — troque o exemplo pelas regras reais do seu projeto (ou use `/houndsman-update`).
+
+### 4. Escreva suas regras
+
+Edite `.houndsman/watchdogs/` — veja [Escrevendo boas regras](#escrevendo-boas-regras).
+
+### 5. Valide
+
+```bash
+bun run houndsman doctor
+```
+
+### 6. Rode a primeira revisão
+
+No seu harness (Claude Code / agents), invoque o skill:
+
+```
+/houndsman
+```
+
+O skill orquestra tudo e grava o relatório em `.houndsman/.runs/<branch-slug>/review.md`.
+Não precisa rodar nenhum script à mão.
+
+---
+
+## O fluxo de trabalho
+
+```
+/houndsman
+   ├─ Passo 0  contexto da PR (gh, opcional)
+   ├─ Passo 1  classifica o diff → briefs por watchdog
+   ├─ Passo 2  N subagentes revisam em paralelo
+   └─ Passo 3  consolida em review.md
+```
+
+- Revisão normal: só `/houndsman` (a branch é detectada; base default `main`).
+- Revisar outra branch: `/houndsman feature/minha-branch`.
+- Manual (sem skill): `houndsman context` → `houndsman --base main` → *(subagentes)* →
+  `houndsman --finalize`.
+- CI: `houndsman --finalize --fail-on-blocking` (exit 1 se houver bloqueantes).
+
+---
+
+## Mantendo a configuração
+
+- **Alterar regras** → use o skill **`/houndsman-update`**. Ele prova no código que o padrão
+  existe (evidência) antes de editar e roda as validações.
+- **Atualizou a lib?** Sincronize os arquivos auto-gerados sem tocar nas suas regras:
+
+  ```bash
+  bun run houndsman update
+  bun run houndsman doctor
+  ```
+
+  O `update` reescreve **só** `.houndsman/core/**` e `.houndsman/.gitignore`. Seus arquivos
+  (`watchdogs/`, `exclusions.ts`, `doc-mappings.ts`, `houndsman.config.ts`) nunca são tocados.
+- **Recomeçar a camada do zero** → `houndsman setup --force` (sobrescreve só os arquivos do
+  usuário; sem `--force` o `setup` é idempotente).
+
+---
+
+## Avançado
+
+### Comandos do dia a dia
+
+| Comando | Função |
+|---|---|
+| `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 context` | Passo 0 — contexto da PR via `gh` |
+| `houndsman --base main` | Passo 1 — prepara os briefs |
+| `houndsman --finalize` | Passo 3 — gera o relatório |
+| `houndsman watchdog <id>` | Contexto de um watchdog (`--rules`, `--json`) |
+
+Flags: `--base <branch>` (default `main`) · `--head <ref>` (default `HEAD`) ·
+`--branch <nome>` · `--dir <dir>` · `--config <path>` · `--clean` · `--no-jev` ·
+`--fail-on-blocking` (com `--finalize`).
+
+### Escrevendo boas regras
+
+O texto da regra é renderizado **literalmente** no brief do subagente — ambiguidade vira
+ruído na revisão. Toda regra começa com um **prefixo de polaridade**:
+
+- `Promover:` → algo que **DEVE** acontecer (o padrão precisa existir no código).
+- `Evitar:` → algo que **NÃO DEVE** acontecer. `Não` e `Nunca` no início são equivalentes.
+
+Boas práticas:
+
+1. **Só regra que o projeto aplica hoje** — prove com evidência (`arquivo:linha` para
+   afirmativas; `0 ocorrências via grep` do anti-padrão para negativas). Regra afirmativa sem
+   aplicação real gera falso positivo.
+2. **Geral e reutilizável** — descreva um padrão do domínio, não uma regra de negócio
+   amarrada a uma única classe/use-case (isso é papel de teste automatizado).
+3. **Condição inequívoca e critério concreto** — duas IAs chegam à mesma conclusão; use
+   limite/lista explícita ou símbolo real do código.
+4. **Sem jargão vago nem qualificador vazio** — nada de "o antigo", "isso", "apenas por
+   compatibilidade".
+5. **Declare o `classify`** do watchdog — regex de path (`filename`) ou de conteúdo
+   (`content`) para o motor achar os arquivos do domínio.
+6. **Prefira editar via `/houndsman-update`** — ele aplica a rubrica completa e roda as
+   verificações (`doctor`, `test`).
+
+> `houndsman doctor` emite um aviso (não bloqueante) para regra sem prefixo de polaridade.
+
+Exemplo:
+
+```ts
+{ severity: "blocking",  text: "Evitar: handler de webhook processa o payload antes de validar a assinatura do provider." }
+{ severity: "attention", text: "Promover: rotas validam a entrada com o schema do domínio." }
+```
+
+### Estrutura gerada por `setup`
+
+```
+houndsman.config.ts
+.houndsman/
+├── .gitignore            # AUTO
+├── core/                 # AUTO — sincronizado por `update`
+│   ├── types.ts
+│   └── skill/*.md
+├── watchdogs/            # você — 1 módulo .ts por watchdog
+│   └── index.ts
+├── exclusions.ts         # você
+└── doc-mappings.ts       # você
+```
+
+Os artefatos de cada review ficam em `.houndsman/.runs/<branch-slug>/` (auto-ignorados).
+
+---
+
+## Documentação
+
+- **`docs/CONTRIBUTING.md`** — arquitetura, fluxos internos, princípios e desenvolvimento da
+  lib (para quem vai contribuir).
+- `src/skill/SETUP.md` — referência de configuração passo a passo.
+- `src/skill/houndsman.md` — orquestração do skill `/houndsman`.
+- `src/skill/houndsman-update.md` — manutenção das regras dos watchdogs.

package/package.json

@@ -1,6 +1,64 @@
 {
-  "name": "@payconductor/houndsman",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@payconductor/houndsman",
+	"version": "0.1.0",
+	"description": "Orquestrador de revisão de Pull Requests: classifica o diff, despacha watchdogs especializados por domínio e consolida o relatório.",
+	"type": "module",
+	"license": "MIT",
+	"bin": {
+		"houndsman": "./src/cli/index.ts"
+	},
+	"exports": {
+		".": "./src/index.ts"
+	},
+	"files": [
+		"src",
+		"assets",
+		"README.md",
+		"LICENSE"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/payconductor-ai/houndsman.git"
+	},
+	"bugs": {
+		"url": "https://github.com/payconductor-ai/houndsman/issues"
+	},
+	"homepage": "https://github.com/payconductor-ai/houndsman#readme",
+	"author": "PayConductor",
+	"keywords": [
+		"pull-request",
+		"code-review",
+		"cli",
+		"bun",
+		"ai-agents",
+		"orchestrator"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"engines": {
+		"bun": ">=1.1.0"
+	},
+	"scripts": {
+		"houndsman": "bun run ./src/cli/index.ts",
+		"build": "bun build ./src/cli/index.ts --target bun --outdir dist",
+		"test": "bun test ./src/tests",
+		"typecheck": "tsc -b",
+		"lint": "biome check .",
+		"format": "biome format --write .",
+		"ci": "biome ci . && tsc -b",
+		"ci:check": "biome check",
+		"ci:check:fix": "biome check --fix",
+		"ci:fix": "bun run ci:check:fix && bun run ci:format:fix",
+		"ci:format": "biome format",
+		"ci:format:fix": "biome format --fix"
+	},
+	"dependencies": {
+		"axios": "^1.12.2"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.2.4",
+		"bun-types": "^1.3.14",
+		"typescript": "^7.0.2"
+	}
+}

package/src/cli/index.ts

@@ -0,0 +1,210 @@
+#!/usr/bin/env bun
+
+/**
+ * Entrypoint único do `houndsman` — `houndsman [comando]`.
+ *
+ * Carrega a configuração do projeto (`HoundsmanConfig`) em runtime (a partir do
+ * cwd) e orquestra funções/classes de `core/`. Não importa nenhum caminho do
+ * projeto consumidor estaticamente.
+ *
+ * Comandos:
+ *   (default)            Passo 1 — preparar (classificação + briefs + manifesto)
+ *   --finalize           Passo 3 — consolidar os findings em review.md
+ *   context              Passo 0 — coletar o contexto da PR via `gh`
+ *   setup                Cria a configuração inicial do projeto (config + skills)
+ *   update               Sincroniza os arquivos auto-gerados (.houndsman/core)
+ *   doctor               Valida a configuração e o ambiente (anti-drift)
+ *   test                 Roda a suíte de testes da lib
+ *   watchdog <id>        Contexto de um watchdog (`--rules`, `--json`)
+ *
+ * Flags: `--base <b>` · `--head <ref>` · `--branch <b>` · `--dir <d>` ·
+ *   `--config <path>` · `--clean` · `--no-jev` · `--fail-on-blocking`.
+ */
+
+import { runContextCommand } from "../core/commands/context";
+import { parseReviewArgs } from "../core/commands/review";
+import { runSetupCommand } from "../core/commands/setup";
+import { runLibTests } from "../core/commands/test";
+import { runUpdateCommand } from "../core/commands/update";
+import { renderWatchdogContext } from "../core/commands/watchdog";
+import { type HoundsmanConfig, resolveArtifactDir } from "../core/config";
+import { loadConfig } from "../core/config-loader";
+import { finalize, prepare, resolveBranch } from "../core/orchestrator";
+import { relFromRoot } from "../core/paths";
+import { checkRegistry } from "../core/registry-check";
+
+const HELP = `Uso: houndsman [comando] [flags]
+
+Comandos:
+  (nenhum)            Prepara a revisão (classification + briefs + manifesto)
+  --finalize          Consolida os findings em review.md
+  context             Coleta o contexto da PR via gh (Passo 0)
+  setup               Cria a configuração inicial do projeto (config + skills)
+  update              Sincroniza os arquivos auto-gerados (.houndsman/core)
+  doctor              Valida a configuração e o ambiente (anti-drift)
+  test                Roda a suíte de testes da lib
+  watchdog <id>       Contexto de um watchdog (--rules, --json)
+
+Flags:
+  --config <path>     Caminho do houndsman.config.* (default: detecta no cwd)
+  --base <branch>     Base do diff (default: main)
+  --head <ref>        Head do diff (default: HEAD)
+  --branch <nome>     Branch alvo (default: detecta do git)
+  --dir <dir>         Diretório dos artefatos
+  --clean             Descarta findings anteriores
+  --no-jev            Desativa a pré-análise Jev
+  --fail-on-blocking  Exit 1 se houver bloqueantes (com --finalize)`;
+
+function readFlag(args: string[], flag: string): string | undefined {
+	const index = args.indexOf(flag);
+	return index >= 0 ? args[index + 1] : undefined;
+}
+
+/** Passo 0 — contexto da PR via `gh`. */
+function runContext(config: HoundsmanConfig, args: string[]): void {
+	const { paths, context } = runContextCommand(config, {
+		branch: readFlag(args, "--branch"),
+		dir: readFlag(args, "--dir"),
+	});
+
+	if (context.available) {
+		const src = context.source;
+		const label = [src?.number ? `#${src.number}` : "", src?.title ?? ""]
+			.filter(Boolean)
+			.join(" ");
+		console.log(
+			`[houndsman] PR ${label} (${src?.head} → ${src?.base}), ${context.stats?.files ?? 0} arquivo(s).`,
+		);
+		console.log(`[houndsman] contexto: ${relFromRoot(paths.context)}`);
+		console.log(`[houndsman] brief: ${relFromRoot(paths.brief)}`);
+		console.log(
+			`[houndsman] próximo passo: subagente resume em ${relFromRoot(paths.summary)}`,
+		);
+	} else {
+		console.log(
+			`[houndsman] contexto indisponível (${context.reason}): ${context.detail}`,
+		);
+		console.log(`[houndsman] marcador: ${relFromRoot(paths.context)}`);
+	}
+}
+
+/** Valida a configuração do projeto e o ambiente (anti-drift). */
+function runDoctor(config: HoundsmanConfig): void {
+	console.log("→ Validando configuração do projeto...");
+	const { problems, warnings, jevQuestions } = checkRegistry(config);
+
+	if (problems.length > 0) {
+		console.error("\n❌ Problemas na configuração de revisão:\n");
+		for (const problem of problems) console.error(`  - ${problem}`);
+		process.exit(1);
+	}
+	console.log(
+		`  ✅ ${config.watchdogIds.length} watchdogs, ${jevQuestions} pergunta(s) Jev.`,
+	);
+
+	if (warnings.length > 0) {
+		console.log(`\n⚠️  ${warnings.length} aviso(s) (não bloqueantes):`);
+		for (const warning of warnings) console.log(`  - ${warning}`);
+	}
+
+	console.log("\n→ Ambiente:");
+	console.log(`  ${Bun.which("git") ? "✅" : "❌"} git`);
+	console.log(`  ${Bun.which("gh") ? "✅" : "⚠️ "} gh (opcional — contexto da PR)`);
+	console.log(
+		`  ${process.env.TYPESAFE_API_KEY ? "✅" : "⚠️ "} TYPESAFE_API_KEY (opcional — pré-análise Jev)`,
+	);
+}
+
+/** Contexto de um watchdog. */
+function runWatchdog(config: HoundsmanConfig, args: string[]): void {
+	const id = args.find((arg) => !arg.startsWith("-"));
+
+	if (!id || renderWatchdogContext(config, id) === null) {
+		console.error(
+			id
+				? `Watchdog '${id}' não existe.`
+				: "Informe o id do watchdog: houndsman watchdog <id>",
+		);
+		console.error(`Ids válidos: ${config.watchdogIds.join(", ")}`);
+		process.exit(1);
+	}
+
+	console.log(
+		renderWatchdogContext(config, id, {
+			withRules: args.includes("--rules"),
+			json: args.includes("--json"),
+		}),
+	);
+}
+
+/** Passo 1/3 — preparar ou finalizar. */
+async function runReview(config: HoundsmanConfig, args: string[]): Promise<void> {
+	const opts = parseReviewArgs(args, resolveArtifactDir(config));
+	const branch = resolveBranch(opts);
+
+	if (opts.finalize) {
+		const result = finalize(opts, branch, config);
+		if (opts.failOnBlocking && result.blockers > 0) process.exit(1);
+	} else {
+		await prepare(opts, branch, config);
+	}
+}
+
+/**
+ * Executa um subcomando. `--config` sobrepõe a descoberta automática.
+ * Comandos que não precisam de projeto (`test`, `setup`) são tratados antes do load.
+ */
+export async function main(): Promise<void> {
+	const argv = process.argv.slice(2);
+	const first = argv[0];
+	const command = first && !first.startsWith("-") ? first : undefined;
+	const rest = command ? argv.slice(1) : argv;
+
+	if (command === "test") {
+		process.exit(runLibTests());
+	}
+	if (command === "setup") {
+		await runSetupCommand({ cwd: process.cwd(), args: rest });
+		return;
+	}
+	if (command === "update") {
+		await runUpdateCommand({ cwd: process.cwd(), args: rest });
+		return;
+	}
+
+	if (command === "help") {
+		console.info(HELP);
+		return;
+	}
+
+	const { config } = await loadConfig({
+		configPath: readFlag(argv, "--config"),
+	});
+
+	switch (command) {
+		case "context":
+			runContext(config, rest);
+			return;
+		case "doctor":
+		case "check":
+			runDoctor(config);
+			return;
+		case "watchdog":
+			runWatchdog(config, rest);
+			return;
+		case undefined:
+			await runReview(config, rest);
+			return;
+		default:
+			console.error(`Subcomando desconhecido: '${command}'.\n`);
+			console.error(HELP);
+			process.exit(1);
+	}
+}
+
+if (import.meta.main) {
+	await main().catch((error) => {
+		console.error(error instanceof Error ? error.message : String(error));
+		process.exit(1);
+	});
+}

package/src/core/assets.ts

@@ -0,0 +1,20 @@
+/**
+ * Resolução dos assets embarcados no pacote (`src/skill/`) — biblioteca.
+ *
+ * Usados para **gerar** a camada de projeto (`houndsman setup`/`update`), não
+ * para resolver caminhos em runtime. Derivados da localização do módulo — não
+ * do cwd.
+ */
+
+import { join } from "node:path";
+
+/** Diretório de assets markdown embarcados no pacote. */
+export const SKILL_DIR = join(import.meta.dir, "..", "skill");
+
+/** Nome do arquivo de schema de output dos watchdogs. */
+export const OUTPUT_FORMAT_FILE = "OUTPUT-FORMAT.md";
+
+/** Caminho absoluto de um asset embarcado em `src/skill/`. */
+export function assetPath(fileName: string): string {
+	return join(SKILL_DIR, fileName);
+}

package/src/core/brief.ts

@@ -0,0 +1,162 @@
+/**
+ * Renderização do brief de um watchdog (biblioteca) — `defaultRenderBrief`.
+ *
+ * O procedimento (`PROCEDURE`) é compartilhado por todos os watchdogs; o que era
+ * protocolo específico vive nas regras do watchdog (`rules`).
+ */
+
+import {
+	type Rule,
+	SEVERITY_EMOJI,
+	severityRank,
+	type WatchdogDefinition,
+	type WatchdogRenderArgs,
+	type WatchdogRenderCandidate,
+	type WatchdogRenderContext,
+} from "./types";
+
+/**
+ * Procedimento de revisão — compartilhado por todos os watchdogs.
+ * Substitui o antigo protocolo genérico de 5 passos + o ponteiro `PROTOCOL_GLOB`.
+ */
+export const PROCEDURE: readonly string[] = [
+	"1. **FILTER** — descarte o que não for do seu domínio (ver *Prioridade de leitura* e *Não carregar*).",
+	"2. **READ HEAD** — leia os arquivos seletivamente (primeiras ~30 linhas). NUNCA o diff completo.",
+	"3. **GREP** — use as regras críticas/anti-padrões como heurística para localizar violações.",
+	"4. **DEEP-READ** — aprofunde apenas os arquivos com suspeita de violação.",
+	'5. **CONCLUDE** — grave o JSON no caminho de output, com `reviewedFiles` preenchido. Sem achados → `"findings": []` (arquivo obrigatório). Não escreva markdown livre.',
+];
+
+/** Bloco de contexto da PR, injetado no brief de cada watchdog. */
+export function renderBriefContext(context: WatchdogRenderContext): string[] {
+	const lines = ["## Contexto da PR", ""];
+	if (context.objective) lines.push(`**Objetivo:** ${context.objective}`);
+	if (context.motivation) lines.push(`**Motivação:** ${context.motivation}`);
+	const changeSummary = context.changeSummary ?? [];
+	if (changeSummary.length > 0) {
+		lines.push("", "**Resumo das alterações:**", "");
+		for (const item of changeSummary) lines.push(`- ${item}`);
+	}
+	lines.push("");
+	return lines;
+}
+
+/** Seção de candidatos pré-analisados (Jev) — o watchdog confirma ou refuta. */
+export function renderBriefCandidates(
+	candidates: readonly WatchdogRenderCandidate[],
+): string[] {
+	const lines = [
+		"## Candidatos pré-analisados (Jev) — confirme ou refute",
+		"",
+		"> Indícios automáticos com confiança calibrada. **NÃO** são achados:",
+		"> confirme (virando finding, com a `rule` abaixo) ou ignore se for falso positivo.",
+		"",
+	];
+	for (const candidate of candidates) {
+		lines.push(
+			`- [ ] \`${candidate.file}\` · **${candidate.severity}** · confiança ${candidate.confidence.toFixed(2)}`,
+			`  Regra: ${candidate.rule}`,
+		);
+	}
+	lines.push("");
+	return lines;
+}
+
+/** Linha de lista em code-span: `- \`valor\``. */
+function codeItem(value: string): string {
+	return `- \`${value}\``;
+}
+
+/** Linha de regra com emoji de severidade. */
+function ruleItem(rule: Rule): string {
+	return `- ${SEVERITY_EMOJI[rule.severity]} **${rule.severity}** — ${rule.text}`;
+}
+
+/** Seção opcional (`## <título>` + itens) — vazia se não houver itens. */
+function optionalList(title: string, items: readonly string[] | undefined): string[] {
+	if (!items || items.length === 0) return [];
+	return [`## ${title}`, "", ...items.map((item) => `- ${item}`), ""];
+}
+
+/** Lista de arquivos do domínio com status. */
+function fileItems(args: WatchdogRenderArgs): string[] {
+	return args.files.map((file) => {
+		const status = args.statuses[file]?.status ?? "modified";
+		return `- \`${file}\` (${status})`;
+	});
+}
+
+/** Seção de deletados (breaking change) — só p/ watchdogs com `breakingChange`. */
+function deletedSection(args: WatchdogRenderArgs, def: WatchdogDefinition): string[] {
+	if (!def.breakingChange || args.deleted.length === 0) return [];
+	return [
+		"## Deletados — checar breaking change",
+		"",
+		...args.deleted.map(codeItem),
+		"",
+	];
+}
+
+/**
+ * Render padrão do brief de um watchdog (ordem estável).
+ * `def` é a definição do próprio watchdog (evita ciclo com o registry).
+ */
+export function defaultRenderBrief(
+	args: WatchdogRenderArgs,
+	def: WatchdogDefinition,
+): string[] {
+	const lines: string[] = [
+		`# Brief — ${def.name} (\`${def.id}\`)`,
+		"",
+		`**Branch:** ${args.branch}`,
+		`**Output obrigatório:** \`${args.outputPath}\``,
+		`**Schema do output:** \`${args.outputFormatPath}\``,
+		"",
+	];
+
+	if (def.description) lines.push("## Objetivo", "", def.description, "");
+	lines.push("## Escopo", "", def.scope, "");
+
+	if (args.context) lines.push(...renderBriefContext(args.context));
+
+	lines.push(...optionalList("Prioridade de leitura", def.reviewFocus));
+	lines.push(
+		"## Regras (por severidade)",
+		"",
+		...[...def.rules]
+			.sort((a, b) => severityRank(a.severity) - severityRank(b.severity))
+			.map(ruleItem),
+		"",
+	);
+	lines.push(
+		"## Docs de contexto (carregar sob demanda)",
+		"",
+		...args.docs.map(codeItem),
+		"",
+	);
+	lines.push(
+		`## Arquivos do seu domínio (${args.files.length})`,
+		"",
+		...fileItems(args),
+		"",
+	);
+
+	if (args.candidates && args.candidates.length > 0) {
+		lines.push(...renderBriefCandidates(args.candidates));
+	}
+
+	lines.push(...deletedSection(args, def));
+	lines.push(...optionalList("Não carregar", def.exclude));
+	lines.push("## Procedimento", "", ...PROCEDURE);
+
+	return lines;
+}
+
+/**
+ * Renderiza o brief via hook custom (`def.renderBrief`) ou o padrão.
+ * Passa a própria definição para que o hook possa reutilizar o render padrão.
+ */
+export function renderBrief(def: WatchdogDefinition, args: WatchdogRenderArgs): string {
+	const render = def.renderBrief ?? defaultRenderBrief;
+	return render(args, def).join("\n");
+}