@payconductor/houndsman 0.2.0 → 0.4.0

package/src/core/commands/review.ts

@@ -4,49 +4,31 @@
  * Biblioteca: NÃO usa `process.argv`/`process.exit` (o CLI decide o exit code).
  */
 
+import { ArgParser } from "../arg-parser";
 import { defaultOptions, type ReviewOptions } from "../orchestrator";
-import { ARTIFACT_DIR } from "../paths";
 
-const VALUE_FLAGS = new Set(["--base", "--head", "--branch", "--dir"]);
-const BOOLEAN_FLAGS = new Set([
-	"--finalize",
-	"--report-only",
-	"--fail-on-blocking",
-	"--clean",
-	"--no-jev",
-	"--full",
-]);
+/** Converte argv (sem o subcomando) nas opções de prepare/finalize. */
+export function parseReviewArgs(args: string[]): ReviewOptions {
+	const parser = ArgParser.from(args);
+	if (parser.has("--dir")) {
+		throw new Error(
+			"--dir foi removido; configure `storage` no houndsman.config.ts.",
+		);
+	}
+	const opts = defaultOptions();
 
-function applyValue(opts: ReviewOptions, flag: string, value: string | undefined): void {
-	if (!value) return;
-	if (flag === "--base") opts.base = value;
-	else if (flag === "--head") opts.head = value;
-	else if (flag === "--branch") opts.branch = value;
-	else if (flag === "--dir") opts.dir = value;
-}
+	const base = parser.value("--base");
+	const head = parser.value("--head");
+	const branch = parser.value("--branch");
+	if (base) opts.base = base;
+	if (head) opts.head = head;
+	if (branch) opts.branch = branch;
 
-function applyBoolean(opts: ReviewOptions, flag: string): void {
-	if (flag === "--finalize" || flag === "--report-only") opts.finalize = true;
-	else if (flag === "--fail-on-blocking") opts.failOnBlocking = true;
-	else if (flag === "--clean") opts.clean = true;
-	else if (flag === "--no-jev") opts.noJev = true;
-	else if (flag === "--full") opts.full = true;
-}
+	if (parser.has("--finalize") || parser.has("--report-only")) opts.finalize = true;
+	if (parser.has("--fail-on-blocking")) opts.failOnBlocking = true;
+	if (parser.has("--clean")) opts.clean = true;
+	if (parser.has("--no-jev")) opts.noJev = true;
+	if (parser.has("--full")) opts.full = true;
 
-/** Converte argv (sem o subcomando) nas opções de prepare/finalize. */
-export function parseReviewArgs(
-	args: string[],
-	artifactDir: string = ARTIFACT_DIR,
-): ReviewOptions {
-	const opts = defaultOptions(artifactDir);
-	for (let i = 0; i < args.length; i++) {
-		const arg = args[i];
-		if (VALUE_FLAGS.has(arg)) {
-			applyValue(opts, arg, args[i + 1]);
-			i++;
-		} else if (BOOLEAN_FLAGS.has(arg)) {
-			applyBoolean(opts, arg);
-		}
-	}
 	return opts;
 }

package/src/core/commands/scaffold.ts

@@ -5,7 +5,7 @@
  * **do usuário**:
  *
  *   .houndsman/
- *   ├── .gitignore          AUTO — ignora core/ e .runs/ (gerados/temporários)
+ *   ├── .gitignore          AUTO — ignora core/ (gerado)
  *   ├── core/types.ts       AUTO — snapshot dos tipos + helpers
  *   ├── core/skill/*.md     AUTO — docs do skill (com {{projectName}} resolvido)
  *   ├── watchdogs/*.ts      USUÁRIO
@@ -16,13 +16,7 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, join } from "node:path";
 import { SKILL_DIR, SKILL_FILE } from "../assets";
-import {
-	ARTIFACT_DIR,
-	CORE_DIR,
-	CORE_SKILL_DIR,
-	OUTPUT_FORMAT_PATH,
-	PROJECT_DIR,
-} from "../paths";
+import { CORE_DIR, CORE_SKILL_DIR, OUTPUT_FORMAT_PATH, PROJECT_DIR } from "../paths";
 
 export type Harness = "agents" | "claude";
 
@@ -87,9 +81,9 @@ import type { HoundsmanConfig } from "./${CORE_DIR}/types";
 /**
  * Configuração do houndsman para ${projectName}.
  *
- * Caminhos são resolvidos pela camada: artefatos em ${ARTIFACT_DIR} e schema de
- * output em ${OUTPUT_FORMAT_PATH}. Ajuste watchdogs, exclusões e mapeamentos de
- * docs conforme o projeto.
+ * Runs, findings e artefatos vivem no storage global (SQLite por default) —
+ * fora do projeto. O schema de output fica em ${OUTPUT_FORMAT_PATH}. Ajuste
+ * watchdogs, exclusões e mapeamentos de docs conforme o projeto.
  */
 export const houndsmanConfig = {
 	projectName: "${projectName}",
@@ -182,10 +176,16 @@ export type HoundsmanConcurrency = {
 	jev?: number;
 };
 
+/** Backend de persistência (reviews, findings e artefatos). */
+export type HoundsmanStorage = {
+	provider?: "sqlite" | "file";
+	path?: string;
+};
+
 /** Contrato de configuração do motor. */
 export type HoundsmanConfig<TId extends string = string> = {
 	projectName: string;
-	artifactDir?: string;
+	storage?: HoundsmanStorage;
 	watchdogIds?: readonly TId[];
 	watchdogs: Record<TId, WatchdogDefinition>;
 	exclusions: readonly RegExp[];
@@ -267,10 +267,9 @@ export function isExcluded(filePath: string): boolean {
 const DOC_MAPPINGS_TEMPLATE = `/**
  * Mapeamento de padrões nos paths → documentação relevante.
  * Consumido pelo motor via \`HoundsmanConfig.docMappings\`.
- */
-export const DOC_MAPPINGS: readonly (readonly [RegExp, readonly string[]])[] = [
-	[/^src\\//, ["AGENTS.md"]],
-];
+ */\`core/\` é regenerado por \`houndsman update\`.
+# Runs, findings e artefatos vivem no storage global (fora do projeto).
+core
 `;
 
 const PROJECT_GITIGNORE = `# Diretórios gerados pelo houndsman — \`core/\` é regenerado por \`houndsman update\`
@@ -280,83 +279,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,
 		);
 	}
+}
 
-	for (const harness of ctx.harnesses) writeHarnessPointers(ctx, harness);
+class HarnessPointerTemplate implements ScaffoldTemplate {
+	private readonly harness: 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 = {
@@ -35,6 +27,20 @@ export type HoundsmanConcurrency = {
 	jev?: number;
 };
 
+/** Backend de persistência (reviews, findings e artefatos). */
+export type HoundsmanStorage = {
+	/**
+	 * Provider de storage (default: `sqlite`). `file` mantém o formato antigo
+	 * em arquivos, mas sob o diretório global do houndsman.
+	 */
+	provider?: "sqlite" | "file";
+	/**
+	 * Caminho do banco (sqlite) ou raiz das runs (file). Default:
+	 * `<HOUNDSMAN_HOME>/houndsman.db` / `<HOUNDSMAN_HOME>/runs`.
+	 */
+	path?: string;
+};
+
 /**
  * Configuração completa do motor de revisão para um projeto.
  *
@@ -43,8 +49,8 @@ export type HoundsmanConcurrency = {
 export type HoundsmanConfig<TId extends string = string> = {
 	/** Nome legível do projeto (usado em prompts e docs). */
 	projectName: string;
-	/** Diretório dos artefatos (default: `ARTIFACT_DIR` da camada). */
-	artifactDir?: string;
+	/** Persistência das runs e artefatos (default: SQLite global). */
+	storage?: HoundsmanStorage;
 	/**
 	 * Ids dos watchdogs — **derivados** das chaves de `watchdogs` por
 	 * `defineHoundsmanConfig` (não informar manualmente).
@@ -80,22 +86,15 @@ export function defineHoundsmanConfig<TId extends string>(
 	return { ...input, watchdogIds: Object.keys(input.watchdogs) as TId[] };
 }
 
-/** Diretório dos artefatos — o valor do projeto ou o default da camada. */
-export function resolveArtifactDir(config: HoundsmanConfig): string {
-	return config.artifactDir ?? ARTIFACT_DIR;
-}
-
 /**
  * Teto de arquivos por brief. Valor ausente/não-positivo cai no default —
  * 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;
 }