@payconductor/houndsman 0.1.4 → 0.3.0

package/src/core/commands/scaffold.ts

@@ -280,83 +280,193 @@ core/
 `;
 
 // ---------------------------------------------------------------------------
-// Escrita
+// Templates (arquivo → conteúdo)
 // ---------------------------------------------------------------------------
 
-/** Escreve um arquivo do usuário somente se ausente (ou se `force`). */
-function writeUserFile(
-	ctx: ScaffoldContext,
-	relativePath: string,
-	content: string,
-): void {
-	const full = join(ctx.cwd, relativePath);
-	if (existsSync(full) && !ctx.force) {
-		ctx.skipped.push(relativePath);
-		return;
+/** Contexto de render de um template. */
+type TemplateContext = { projectName: string };
+
+/** Um arquivo da camada (caminho relativo + conteúdo). */
+interface ScaffoldTemplate {
+	readonly path: string;
+	render(context: TemplateContext): string;
+}
+
+class ConfigTemplate implements ScaffoldTemplate {
+	readonly path = "houndsman.config.ts";
+
+	render(context: TemplateContext): string {
+		return CONFIG_TEMPLATE(context.projectName);
 	}
-	mkdirSync(join(full, ".."), { recursive: true });
-	writeFileSync(full, content);
-	ctx.created.push(relativePath);
 }
 
-/** Escreve/sobrescreve um arquivo auto-gerado. */
-function writeGeneratedFile(
-	ctx: ScaffoldContext,
-	relativePath: string,
-	content: string,
-): void {
-	const full = join(ctx.cwd, relativePath);
-	mkdirSync(join(full, ".."), { recursive: true });
-	writeFileSync(full, content);
-	ctx.generated.push(relativePath);
+class WatchdogExampleTemplate implements ScaffoldTemplate {
+	readonly path = join(PROJECT_DIR, "watchdogs", "example.ts");
+
+	render(): string {
+		return WATCHDOG_EXAMPLE;
+	}
 }
 
-// ---------------------------------------------------------------------------
-// Camadas
-// ---------------------------------------------------------------------------
+class WatchdogsIndexTemplate implements ScaffoldTemplate {
+	readonly path = join(PROJECT_DIR, "watchdogs", "index.ts");
 
-/** Arquivos do usuário: config, watchdogs, exclusões e mapeamentos. */
-export function writeUserLayer(ctx: ScaffoldContext): void {
-	writeUserFile(ctx, "houndsman.config.ts", CONFIG_TEMPLATE(ctx.projectName));
-	writeUserFile(ctx, join(PROJECT_DIR, "watchdogs", "example.ts"), WATCHDOG_EXAMPLE);
-	writeUserFile(ctx, join(PROJECT_DIR, "watchdogs", "index.ts"), WATCHDOGS_INDEX);
-	writeUserFile(ctx, join(PROJECT_DIR, "exclusions.ts"), EXCLUSIONS_TEMPLATE);
-	writeUserFile(ctx, join(PROJECT_DIR, "doc-mappings.ts"), DOC_MAPPINGS_TEMPLATE);
+	render(): string {
+		return WATCHDOGS_INDEX;
+	}
 }
 
-/**
- * Arquivos auto-gerados: tipos, docs do skill, `.gitignore` (ignora `core/` e
- * `.runs/`) e o `SKILL.md` de cada harness. Sempre sobrescritos (é o alvo do
- * `update`).
- */
-export function syncGeneratedFiles(ctx: ScaffoldContext): void {
-	writeGeneratedFile(ctx, join(CORE_DIR, "types.ts"), TYPES_TEMPLATE);
-	writeGeneratedFile(ctx, join(PROJECT_DIR, ".gitignore"), PROJECT_GITIGNORE);
-
-	// Docs do skill vão para `.houndsman/core/skill/`. O `SKILL.md` é o entry point
-	// dos harnesses (escrito em `writeHarnessPointers`), não um doc da camada.
-	for (const name of readdirSync(SKILL_DIR)) {
-		if (!name.endsWith(".md") || name === SKILL_FILE) continue;
-		const raw = readFileSync(join(SKILL_DIR, name), "utf8");
-		writeGeneratedFile(
-			ctx,
-			join(CORE_SKILL_DIR, name),
-			raw.replaceAll("{{projectName}}", ctx.projectName),
+class ExclusionsTemplate implements ScaffoldTemplate {
+	readonly path = join(PROJECT_DIR, "exclusions.ts");
+
+	render(): string {
+		return EXCLUSIONS_TEMPLATE;
+	}
+}
+
+class DocMappingsTemplate implements ScaffoldTemplate {
+	readonly path = join(PROJECT_DIR, "doc-mappings.ts");
+
+	render(): string {
+		return DOC_MAPPINGS_TEMPLATE;
+	}
+}
+
+class TypesTemplate implements ScaffoldTemplate {
+	readonly path = join(CORE_DIR, "types.ts");
+
+	render(): string {
+		return TYPES_TEMPLATE;
+	}
+}
+
+class GitignoreTemplate implements ScaffoldTemplate {
+	readonly path = join(PROJECT_DIR, ".gitignore");
+
+	render(): string {
+		return PROJECT_GITIGNORE;
+	}
+}
+
+class SkillDocTemplate implements ScaffoldTemplate {
+	private readonly fileName: string;
+
+	constructor(fileName: string) {
+		this.fileName = fileName;
+	}
+
+	get path(): string {
+		return join(CORE_SKILL_DIR, this.fileName);
+	}
+
+	render(context: TemplateContext): string {
+		return readFileSync(join(SKILL_DIR, this.fileName), "utf8").replaceAll(
+			"{{projectName}}",
+			context.projectName,
 		);
 	}
+}
+
+class HarnessPointerTemplate implements ScaffoldTemplate {
+	private readonly harness: Harness;
 
-	for (const harness of ctx.harnesses) writeHarnessPointers(ctx, harness);
+	constructor(harness: Harness) {
+		this.harness = harness;
+	}
+
+	get path(): string {
+		return join(`.${this.harness}`, "skills", "houndsman", SKILL_FILE);
+	}
+
+	render(context: TemplateContext): string {
+		return readFileSync(join(SKILL_DIR, SKILL_FILE), "utf8").replaceAll(
+			"{{projectName}}",
+			context.projectName,
+		);
+	}
 }
 
-/**
- * Escreve o `SKILL.md` do harness a partir do asset base (`src/skill/SKILL.md`),
- * resolvendo `{{projectName}}`. O texto do skill vive no asset — não aqui.
- */
-function writeHarnessPointers(ctx: ScaffoldContext, harness: Harness): void {
-	const raw = readFileSync(join(SKILL_DIR, SKILL_FILE), "utf8");
-	writeGeneratedFile(
-		ctx,
-		join(`.${harness}`, "skills", "houndsman", SKILL_FILE),
-		raw.replaceAll("{{projectName}}", ctx.projectName),
-	);
+// ---------------------------------------------------------------------------
+// Scaffolder
+// ---------------------------------------------------------------------------
+
+/** Escreve as camadas do projeto (`setup`) e sincroniza os auto-gerados (`update`). */
+export class ProjectScaffolder {
+	private readonly ctx: ScaffoldContext;
+
+	constructor(ctx: ScaffoldContext) {
+		this.ctx = ctx;
+	}
+
+	/** Arquivos do usuário: config, watchdogs, exclusões e mapeamentos. */
+	writeUserLayer(): void {
+		const context = this.context();
+		const templates: ScaffoldTemplate[] = [
+			new ConfigTemplate(),
+			new WatchdogExampleTemplate(),
+			new WatchdogsIndexTemplate(),
+			new ExclusionsTemplate(),
+			new DocMappingsTemplate(),
+		];
+		for (const template of templates) this.writeUserFile(template, context);
+	}
+
+	/** Arquivos auto-gerados (sempre sobrescritos). */
+	syncGenerated(): void {
+		const context = this.context();
+		this.writeGeneratedFile(new TypesTemplate(), context);
+		this.writeGeneratedFile(new GitignoreTemplate(), context);
+
+		// Docs do skill vão para `.houndsman/core/skill/`. O `SKILL.md` é o entry
+		// point dos harnesses, não um doc da camada.
+		for (const name of readdirSync(SKILL_DIR)) {
+			if (!name.endsWith(".md") || name === SKILL_FILE) continue;
+			this.writeGeneratedFile(new SkillDocTemplate(name), context);
+		}
+
+		for (const harness of this.ctx.harnesses) {
+			this.writeGeneratedFile(new HarnessPointerTemplate(harness), context);
+		}
+	}
+
+	private context(): TemplateContext {
+		return { projectName: this.ctx.projectName };
+	}
+
+	/** Usuário: só escreve se ausente (ou `force`). */
+	private writeUserFile(template: ScaffoldTemplate, context: TemplateContext): void {
+		const full = join(this.ctx.cwd, template.path);
+		if (existsSync(full) && !this.ctx.force) {
+			this.ctx.skipped.push(template.path);
+			return;
+		}
+		mkdirSync(join(full, ".."), { recursive: true });
+		writeFileSync(full, template.render(context));
+		this.ctx.created.push(template.path);
+	}
+
+	/** Auto-gerado: sempre sobrescreve. */
+	private writeGeneratedFile(
+		template: ScaffoldTemplate,
+		context: TemplateContext,
+	): void {
+		const full = join(this.ctx.cwd, template.path);
+		mkdirSync(join(full, ".."), { recursive: true });
+		writeFileSync(full, template.render(context));
+		this.ctx.generated.push(template.path);
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Fachada (compatibilidade)
+// ---------------------------------------------------------------------------
+
+/** Arquivos do usuário (setup). */
+export function writeUserLayer(ctx: ScaffoldContext): void {
+	new ProjectScaffolder(ctx).writeUserLayer();
+}
+
+/** Arquivos auto-gerados (setup/update). */
+export function syncGeneratedFiles(ctx: ScaffoldContext): void {
+	new ProjectScaffolder(ctx).syncGenerated();
 }

package/src/core/commands/setup.ts

@@ -49,27 +49,32 @@ function ensurePackageScript(ctx: ScaffoldContext): void {
 	ctx.created.push("package.json#scripts.houndsman");
 }
 
-/** Cria a configuração inicial do projeto. */
-export async function runSetupCommand(options: SetupOptions): Promise<void> {
+/** Cria a configuração inicial do projeto. Devolve as mensagens do CLI. */
+export async function runSetupCommand(options: SetupOptions): Promise<string[]> {
 	const ctx = createScaffoldContext(
 		options.cwd,
 		options.args,
 		options.args.includes("--force"),
 	);
 
-	console.log(`→ Configurando houndsman em ${ctx.cwd} (projeto: ${ctx.projectName})`);
+	const messages = [
+		`→ Configurando houndsman em ${ctx.cwd} (projeto: ${ctx.projectName})`,
+	];
 
 	writeUserLayer(ctx);
 	syncGeneratedFiles(ctx);
 	ensurePackageScript(ctx);
 
-	for (const path of ctx.created) console.log(`  + ${path}`);
-	for (const path of ctx.skipped) console.log(`  = ${path} (mantido)`);
-	for (const path of ctx.generated) console.log(`  ~ ${path} (auto)`);
+	for (const path of ctx.created) messages.push(`  + ${path}`);
+	for (const path of ctx.skipped) messages.push(`  = ${path} (mantido)`);
+	for (const path of ctx.generated) messages.push(`  ~ ${path} (auto)`);
 
-	console.log("\nPróximos passos:");
-	console.log("  1. Ajuste `houndsman.config.ts` e `.houndsman/watchdogs/`.");
-	console.log("  2. Valide: bun run houndsman doctor");
-	console.log("  3. Prepare a revisão: bun run houndsman");
-	console.log("  ·  Sincronizar arquivos auto-gerados: bun run houndsman update");
+	messages.push(
+		"\nPróximos passos:",
+		"  1. Ajuste `houndsman.config.ts` e `.houndsman/watchdogs/`.",
+		"  2. Valide: bun run houndsman doctor",
+		"  3. Prepare a revisão: bun run houndsman",
+		"  ·  Sincronizar arquivos auto-gerados: bun run houndsman update",
+	);
+	return messages;
 }

package/src/core/commands/update.ts

@@ -13,18 +13,18 @@ export type UpdateOptions = {
 	args: string[];
 };
 
-/** Sincroniza os arquivos auto-gerados da camada de projeto. */
-export async function runUpdateCommand(options: UpdateOptions): Promise<void> {
+/** Sincroniza os arquivos auto-gerados da camada de projeto. Devolve mensagens. */
+export async function runUpdateCommand(options: UpdateOptions): Promise<string[]> {
 	const ctx = createScaffoldContext(options.cwd, options.args, false);
-
-	console.log(`→ Sincronizando arquivos auto-gerados em ${ctx.cwd}`);
+	const messages = [`→ Sincronizando arquivos auto-gerados em ${ctx.cwd}`];
 
 	syncGeneratedFiles(ctx);
 
-	for (const path of ctx.generated) console.log(`  ~ ${path} (auto)`);
+	for (const path of ctx.generated) messages.push(`  ~ ${path} (auto)`);
 
-	console.log("\nArquivos do usuário não foram tocados:");
-	console.log(
+	messages.push(
+		"\nArquivos do usuário não foram tocados:",
 		"  .houndsman/watchdogs/ · exclusions.ts · doc-mappings.ts · houndsman.config.ts",
 	);
+	return messages;
 }

package/src/core/commands/watchdog.ts

@@ -6,12 +6,7 @@
  */
 
 import type { HoundsmanConfig } from "../config";
-import {
-	type Rule,
-	SEVERITY_EMOJI,
-	severityRank,
-	type WatchdogDefinition,
-} from "../types";
+import { WatchdogPresenter } from "../renderers/watchdog-presenter";
 import { findWatchdog, getWatchdogContext } from "../watchdog-registry";
 
 export type WatchdogContextOptions = {
@@ -21,7 +16,7 @@ export type WatchdogContextOptions = {
 	json?: boolean;
 };
 
-type WatchdogContext = ReturnType<typeof getWatchdogContext>;
+const presenter = new WatchdogPresenter();
 
 /** Renderiza o contexto de um watchdog (markdown ou JSON). `null` se o id não existe. */
 export function renderWatchdogContext(
@@ -29,77 +24,10 @@ export function renderWatchdogContext(
 	id: string,
 	opts: WatchdogContextOptions = {},
 ): string | null {
-	const def = findWatchdog(config, id);
-	if (!def) return null;
-	const ctx = getWatchdogContext(config, def.id);
-	const withRules = opts.withRules ?? false;
-	return opts.json
-		? serializeWatchdogContext(ctx, def, withRules)
-		: renderWatchdogMarkdown(ctx, def, withRules);
-}
-
-/** Payload serializável (regras incluídas apenas com `withRules`). */
-function serializeWatchdogContext(
-	ctx: WatchdogContext,
-	def: WatchdogDefinition,
-	withRules: boolean,
-): string {
-	const payload = withRules ? { ...ctx, rules: def.rules } : { ...ctx };
-	return JSON.stringify(payload, null, 2);
-}
-
-/** Lista de itens em bloco `## <título>` (vazio se não houver itens). */
-function section(title: string, items: readonly string[] | undefined): string[] {
-	if (!items || items.length === 0) return [];
-	return [`## ${title}`, "", ...items.map((item) => `- ${item}`), ""];
-}
-
-/** Regras com emoji de severidade em bloco `## <título>`. */
-function ruleSection(title: string, rules: readonly Rule[]): string[] {
-	return [
-		`## ${title}`,
-		"",
-		...rules.map(
-			(rule) =>
-				`- ${SEVERITY_EMOJI[rule.severity]} **${rule.severity}** — ${rule.text}`,
-		),
-		"",
-	];
-}
-
-/** Render markdown legível do contexto do watchdog. */
-function renderWatchdogMarkdown(
-	ctx: WatchdogContext,
-	def: WatchdogDefinition,
-	withRules: boolean,
-): string {
-	const lines: string[] = [
-		`# ${ctx.name} (\`${ctx.id}\`)`,
-		"",
-		`**Descrição:** ${ctx.description}`,
-		`**Escopo:** ${ctx.scope}`,
-		"",
-	];
-
-	lines.push(...section("Prioridade de leitura", ctx.reviewFocus));
-	lines.push(...section("Não carregar", ctx.exclude));
-	lines.push(
-		...section(
-			"Docs de contexto",
-			ctx.contextFiles.map((doc) => `\`${doc}\``),
-		),
-	);
-
-	if (withRules) {
-		lines.push(
-			...ruleSection(
-				"Regras",
-				[...def.rules].sort(
-					(a, b) => severityRank(a.severity) - severityRank(b.severity),
-				),
-			),
-		);
-	}
-
-	return lines.join("\n").trimEnd();
+	const definition = findWatchdog(config, id);
+	if (!definition) return null;
+	return presenter.render(getWatchdogContext(config, definition.id), definition, {
+		withRules: opts.withRules ?? false,
+		json: opts.json ?? false,
+	});
 }

package/src/core/config.ts

@@ -6,22 +6,14 @@
  * (camada `houndsman/`) — único ponto de troca ao portar para outro repositório.
  */
 
-import { ARTIFACT_DIR } from "./paths";
+import { ProjectConfig } from "./project-config";
 import type { WatchdogDefinition } from "./types";
 
-/** Documentos sempre incluídos nos briefs (default). */
-export const DEFAULT_ALWAYS_INCLUDE_DOCS: readonly string[] = ["AGENTS.md"];
-
-/**
- * Teto default de arquivos por brief. Um PR grande (milhares de linhas) pode
- * concentrar centenas de arquivos em um único domínio; o teto mantém o contexto
- * do subagente limitado — o excedente vira "fora do orçamento" (cobertura
- * honesta), nunca some silenciosamente.
- */
-export const DEFAULT_MAX_FILES_PER_BRIEF = 40;
-
-/** Concorrência default das chamadas simultâneas ao Jev. */
-export const DEFAULT_JEV_CONCURRENCY = 5;
+export {
+	DEFAULT_ALWAYS_INCLUDE_DOCS,
+	DEFAULT_JEV_CONCURRENCY,
+	DEFAULT_MAX_FILES_PER_BRIEF,
+} from "./defaults";
 
 /** Limites de triage para PRs grandes. */
 export type HoundsmanBudgets = {
@@ -82,7 +74,7 @@ export function defineHoundsmanConfig<TId extends string>(
 
 /** Diretório dos artefatos — o valor do projeto ou o default da camada. */
 export function resolveArtifactDir(config: HoundsmanConfig): string {
-	return config.artifactDir ?? ARTIFACT_DIR;
+	return new ProjectConfig(config).artifactDir;
 }
 
 /**
@@ -90,12 +82,10 @@ export function resolveArtifactDir(config: HoundsmanConfig): string {
  * mantém o contexto do subagente limitado em PRs grandes.
  */
 export function resolveMaxFilesPerBrief(config: HoundsmanConfig): number {
-	const value = config.budgets?.maxFilesPerBrief;
-	return value !== undefined && value > 0 ? value : DEFAULT_MAX_FILES_PER_BRIEF;
+	return new ProjectConfig(config).maxFilesPerBrief;
 }
 
 /** Concorrência das chamadas Jev (valor ausente/não-positivo cai no default). */
 export function resolveJevConcurrency(config: HoundsmanConfig): number {
-	const value = config.concurrency?.jev;
-	return value !== undefined && value > 0 ? value : DEFAULT_JEV_CONCURRENCY;
+	return new ProjectConfig(config).jevConcurrency;
 }

package/src/core/defaults.ts

@@ -0,0 +1,20 @@
+/**
+ * Defaults do motor (biblioteca) — valores canônicos compartilhados.
+ *
+ * Vivem fora de `config.ts` para que `ProjectConfig` possa usá-los sem criar
+ * ciclo de importação com os adaptadores públicos.
+ */
+
+/** Documentos sempre incluídos nos briefs (default). */
+export const DEFAULT_ALWAYS_INCLUDE_DOCS: readonly string[] = ["AGENTS.md"];
+
+/**
+ * Teto default de arquivos por brief. Um PR grande (milhares de linhas) pode
+ * concentrar centenas de arquivos em um único domínio; o teto mantém o contexto
+ * do subagente limitado — o excedente vira "fora do orçamento" (cobertura
+ * honesta), nunca some silenciosamente.
+ */
+export const DEFAULT_MAX_FILES_PER_BRIEF = 40;
+
+/** Concorrência default das chamadas simultâneas ao Jev. */
+export const DEFAULT_JEV_CONCURRENCY = 5;

package/src/core/diff-source.ts

@@ -9,6 +9,7 @@
  * Jev) e por `classifyRange` (fallback standalone).
  */
 
+import { runGit } from "./git-runner";
 import type { ChurnMap, FileChurn } from "./types";
 
 export type DiffSource = {
@@ -26,19 +27,6 @@ export type CollectDiffOptions = {
 /** Teto default de caracteres por arquivo no patch (compartilhado com o git-revision). */
 export const DEFAULT_MAX_PER_FILE_CHARS = 8_000;
 
-/** Executa `git` com `core.quotepath=false` (paths literais) e devolve o stdout. */
-function runGit(args: string[]): string {
-	const result = Bun.spawnSync(["git", "-c", "core.quotepath=false", ...args], {
-		stdout: "pipe",
-		stderr: "pipe",
-	});
-	if (result.exitCode !== 0) {
-		const stderr = new TextDecoder().decode(result.stderr).trim();
-		throw new Error(`git ${args.join(" ")} falhou: ${stderr}`);
-	}
-	return new TextDecoder().decode(result.stdout);
-}
-
 /** Novo caminho do arquivo a partir do cabeçalho de um segmento do patch. */
 function extractPath(segment: string): string | undefined {
 	// Só o cabeçalho (antes do primeiro hunk) pode conter as linhas `---`/`+++` —

package/src/core/doc-discoverer.ts

@@ -6,28 +6,38 @@
  * (`project/doc-mappings.ts`) e chegam via `HoundsmanConfig`.
  */
 
-import { DEFAULT_ALWAYS_INCLUDE_DOCS, type HoundsmanConfig } from "./config";
+import type { HoundsmanConfig } from "./config";
+import { ProjectConfig } from "./project-config";
 
-/** Descobre docs relevantes com base nos paths + docs sempre incluídos. */
-export function discoverDocs(filePaths: string[], config: HoundsmanConfig): string[] {
-	const docs = new Set<string>();
+/** Descobre documentação relevante para um conjunto de arquivos alterados. */
+export class DocDiscoverer {
+	private readonly alwaysInclude: readonly string[];
+	private readonly mappings: readonly (readonly [RegExp, readonly string[]])[];
 
-	for (const doc of config.alwaysIncludeDocs ?? DEFAULT_ALWAYS_INCLUDE_DOCS) {
-		docs.add(doc);
+	constructor(config: HoundsmanConfig) {
+		const project = new ProjectConfig(config);
+		this.alwaysInclude = project.alwaysIncludeDocs;
+		this.mappings = project.docMappings;
 	}
 
-	for (const filePath of filePaths) {
-		const normalized = filePath.trim().toLowerCase();
-		if (!normalized) continue;
+	discover(filePaths: readonly string[]): string[] {
+		const docs = new Set<string>(this.alwaysInclude);
 
-		for (const [pattern, docPaths] of config.docMappings) {
-			if (pattern.test(normalized)) {
-				for (const docPath of docPaths) {
-					docs.add(docPath);
-				}
+		for (const filePath of filePaths) {
+			const normalized = filePath.trim().toLowerCase();
+			if (!normalized) continue;
+
+			for (const [pattern, docPaths] of this.mappings) {
+				if (!pattern.test(normalized)) continue;
+				for (const docPath of docPaths) docs.add(docPath);
 			}
 		}
+
+		return [...docs].sort();
 	}
+}
 
-	return [...docs].sort();
+/** Descobre docs relevantes com base nos paths + docs sempre incluídos. */
+export function discoverDocs(filePaths: string[], config: HoundsmanConfig): string[] {
+	return new DocDiscoverer(config).discover(filePaths);
 }

package/src/core/domain/budget.ts

@@ -0,0 +1,42 @@
+/**
+ * Orçamento por brief (domínio) — funções puras de triagem de PRs grandes.
+ *
+ * Separado de `file-classifier` para que `Classification` possa aplicar o
+ * orçamento sem depender do serviço de classificação.
+ */
+
+import type { ChurnMap } from "../types";
+
+/** Churn total (adições + remoções) de um arquivo; 0 quando ausente. */
+export function churnOf(filePath: string, churn: ChurnMap | undefined): number {
+	const entry = churn?.[filePath];
+	return entry ? entry.additions + entry.deletions : 0;
+}
+
+/** Ordena os arquivos por risco (churn desc; empate pelo caminho). */
+export function sortByRisk(files: readonly string[], churn?: ChurnMap): string[] {
+	return [...files].sort((a, b) => {
+		const delta = churnOf(b, churn) - churnOf(a, churn);
+		return delta !== 0 ? delta : a.localeCompare(b);
+	});
+}
+
+/** Resultado da aplicação do orçamento: o que revisar e o que ficou de fora. */
+export type BudgetSelection = { selected: string[]; overflow: string[] };
+
+/**
+ * Aplica o orçamento por brief: mantém os `maxFiles` de maior risco e devolve o
+ * restante em `overflow` (nunca descarta silenciosamente). `maxFiles` não-positivo
+ * ou não-finito desativa o orçamento.
+ */
+export function selectByBudget(
+	files: readonly string[],
+	churn: ChurnMap | undefined,
+	maxFiles: number,
+): BudgetSelection {
+	const ordered = sortByRisk(files, churn);
+	if (!Number.isFinite(maxFiles) || maxFiles <= 0 || ordered.length <= maxFiles) {
+		return { selected: ordered, overflow: [] };
+	}
+	return { selected: ordered.slice(0, maxFiles), overflow: ordered.slice(maxFiles) };
+}