@payconductor/houndsman 0.10.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@payconductor/houndsman",
-	"version": "0.10.0",
+	"version": "0.11.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",

package/src/cli/index.ts

@@ -31,6 +31,7 @@ import type { HoundsmanConfig } from "../core/config";
 import { loadConfig } from "../core/config-loader";
 import { HoundsmanEngine } from "../core/engine/houndsman-engine";
 import { logger } from "../core/logging";
+import { syncProjectLayerForRoot } from "../core/services/worktree-manager";
 import { ArgParser } from "./arg-parser";
 import type { CliContext } from "./commands/command";
 import { ContextCommand } from "./commands/context-command";
@@ -90,7 +91,14 @@ export async function main(): Promise<void> {
 
 	let loaded: Awaited<ReturnType<typeof loadConfig>> | null = null;
 	const config = async (): Promise<HoundsmanConfig> => {
-		loaded ??= await loadConfig({ configPath: parser.value("--config") });
+		loaded ??= await (async () => {
+			// Rodando dentro de um worktree, a camada gerada (`.houndsman/core`)
+			// não existe (é ignorada pelo git). Repõe a partir do clone principal
+			// antes de importar a config — sem isso os watchdogs não resolvem
+			// `../core/types`. No clone principal é no-op.
+			syncProjectLayerForRoot(process.cwd());
+			return loadConfig({ configPath: parser.value("--config") });
+		})();
 		return loaded.config;
 	};
 

package/src/core/ai/prompts/base.ts

@@ -14,6 +14,13 @@ export const UNTRUSTED_DATA_RULES: readonly string[] = [
 	"Responda apenas no formato estruturado pedido.",
 ];
 
+/**
+ * Idioma da saída textual. Nomes próprios, paths, símbolos e comandos ficam
+ * como estão — só a prosa é traduzida.
+ */
+export const OUTPUT_LANGUAGE_RULE =
+	"Escreva todo o texto em português do Brasil (pt-BR), mesmo que o contexto, o diff ou os nomes de arquivos estejam em inglês.";
+
 /** Monta um system prompt estável (papel + regras). */
 export function buildSystem(role: string, extra: readonly string[] = []): string {
 	return [

package/src/core/ai/prompts/context.ts

@@ -2,13 +2,14 @@
  * Prompt do resumo de contexto da PR (`AiContextSummarizer`).
  */
 
-import { buildSystem, clip } from "./base";
+import { buildSystem, clip, OUTPUT_LANGUAGE_RULE } from "./base";
 
 /** Instruções de sistema do resumo. */
 export function contextInstructions(): string {
 	return buildSystem(
 		"Você resume o contexto de uma Pull Request para revisores técnicos.",
 		[
+			OUTPUT_LANGUAGE_RULE,
 			"Objetivo em até 2 frases (máx. 400 caracteres).",
 			"Motivação em até 3 frases (máx. 480 caracteres), com o problema e o impacto esperado.",
 			"Resumo das alterações em até 6 bullets (máx. 240 caracteres cada), focado em comportamento, fluxos e impacto.",

package/src/core/ai/prompts/technical.ts

@@ -2,13 +2,14 @@
  * Prompt dos pontos técnicos estruturais (`AiTechnicalSummarizer`).
  */
 
-import { buildSystem, clip } from "./base";
+import { buildSystem, clip, OUTPUT_LANGUAGE_RULE } from "./base";
 
 /** Instruções de sistema dos pontos técnicos. */
 export function technicalInstructions(): string {
 	return buildSystem(
 		"Você descreve a estrutura técnica de uma Pull Request para revisores.",
 		[
+			OUTPUT_LANGUAGE_RULE,
 			"Foque em arquitetura e contratos: novos módulos/services, interfaces, providers, repositories, camadas, exports, dependências e impacto.",
 			"NÃO avalie qualidade, NÃO liste achados, bugs ou riscos de revisão.",
 			"NÃO repita a motivação de negócio: isso pertence ao resumo de negócio.",

package/src/core/config-loader.ts

@@ -31,6 +31,12 @@ export type LoadedConfig<TId extends string = string> = {
 	path: string;
 };
 
+/** Forma do módulo de config (default ou export nomeado). */
+type ConfigModule<TId extends string> = {
+	default?: HoundsmanConfig<TId>;
+	houndsmanConfig?: HoundsmanConfig<TId>;
+};
+
 /** Primeiro arquivo de config existente no diretório (ou `null`). */
 export function resolveConfigPath(cwd: string = process.cwd()): string | null {
 	for (const name of CONFIG_FILE_CANDIDATES) {
@@ -61,10 +67,18 @@ export async function loadConfig<TId extends string = string>(
 		throw new Error(MISSING_CONFIG_HINT);
 	}
 
-	const module = (await import(pathToFileURL(path).href)) as {
-		default?: HoundsmanConfig<TId>;
-		houndsmanConfig?: HoundsmanConfig<TId>;
-	};
+	let module: ConfigModule<TId>;
+	try {
+		module = (await import(pathToFileURL(path).href)) as ConfigModule<TId>;
+	} catch (error) {
+		const detail = error instanceof Error ? error.message : String(error);
+		// Causa comum: camada gerada ausente (`.houndsman/core`), importada pelos
+		// watchdogs como `../core/types` — típico de worktree ainda não sincronizado.
+		throw new Error(
+			`Falha ao carregar ${path}: ${detail}\n` +
+				"A camada gerada (`.houndsman/core`) existe? Rode `houndsman update` na raiz do projeto.",
+		);
+	}
 	const config = module.default ?? module.houndsmanConfig;
 
 	if (!config) {

package/src/core/engine/review-workspace.ts

@@ -11,7 +11,7 @@ import { createGitRunner } from "../git-runner";
 import { createGhRunner, type GhRunner } from "../services/gh-client";
 import { GitRepository } from "../services/git-repository";
 import { PrResolver } from "../services/pr-resolver";
-import { WorktreeManager } from "../services/worktree-manager";
+import { syncProjectLayer, WorktreeManager } from "../services/worktree-manager";
 import { resolveWorktreesRoot } from "../storage/paths";
 import { resolveRepoIdentity } from "../storage/repo-identity";
 import type { RepoIdentity } from "../storage/types";
@@ -105,9 +105,13 @@ export function resolveReviewWorkspace(
 				`Worktree '${root}' está em detached HEAD. Informe --branch <nome>.`,
 			);
 		}
+		// A camada gerada não vem no checkout; sem ela os comandos no worktree
+		// não carregam a config (`../core/types`).
+		const explicitMainRoot = mainRootOf(git, repo.root);
+		syncProjectLayer(explicitMainRoot, root);
 		return {
 			root,
-			mainRoot: mainRootOf(git, repo.root),
+			mainRoot: explicitMainRoot,
 			repo,
 			git,
 			branch,

package/src/core/services/worktree-manager.ts

@@ -10,12 +10,17 @@
  * truncado porque o checkout de uma PR herda a profundidade dos arquivos do
  * projeto, e o Windows (MAX_PATH = 260) estoura "Filename too long" com
  * repo+branch longos. O hash mantém o nome determinístico e único.
+ *
+ * Cada worktree recebe o espelho da camada gerada (`.houndsman/core`) do clone
+ * principal — o checkout não traz arquivos ignorados e, sem ela, a config do
+ * projeto não importa (`../core/types`).
  */
 
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { createGitRunner } from "../git-runner";
+import { CORE_DIR } from "../paths";
 import { sanitizeBranch } from "../report-builder";
 import { worktreesRoot } from "../storage/paths";
 import { GitRepository } from "./git-repository";
@@ -59,7 +64,7 @@ export type RemoveWorktreeResult = {
 /** Opções do gerenciador. */
 export type WorktreeManagerOptions = {
 	repoKey: string;
-	/** Raiz do clone principal. */
+	/** Raiz do clone principal (fonte da camada gerada espelhada). */
 	repoRoot: string;
 	/**
 	 * Raiz onde os diretórios por repositório são criados.
@@ -112,6 +117,54 @@ function isInside(root: string, path: string): boolean {
 	return rel === "" || (!rel.startsWith("..") && !rel.split(sep).includes(".."));
 }
 
+/** Raiz do clone principal a partir do diretório git comum (ou `null`). */
+function mainRootOf(git: GitRepository): string | null {
+	const common = git.gitCommonDir();
+	if (!common) return null;
+	const gitDir = resolve(common);
+	return basename(gitDir).toLowerCase() === ".git" ? dirname(gitDir) : null;
+}
+
+/**
+ * Espelha a camada gerada (`.houndsman/core`) do clone principal no worktree.
+ *
+ * O checkout de uma PR só traz arquivos versionados e `core/` é gerado (e
+ * ignorado pelo git). Sem ele, qualquer comando dentro do worktree falha ao
+ * importar `../core/types` a partir dos watchdogs. Fail-open: nunca bloqueia
+ * a revisão.
+ */
+export function syncProjectLayer(mainRoot: string, worktreeRoot: string): boolean {
+	const source = join(mainRoot, CORE_DIR);
+	const dest = join(worktreeRoot, CORE_DIR);
+	if (normalizePath(source) === normalizePath(dest)) return false;
+	if (!existsSync(source)) return false;
+	try {
+		mkdirSync(dirname(dest), { recursive: true });
+		cpSync(source, dest, { recursive: true, force: true });
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Auto-reparo para comandos executados **dentro** de um worktree: repõe a
+ * camada gerada a partir do clone principal quando ela não existe ali. No
+ * clone principal (camada presente) é no-op. Fail-open.
+ */
+export function syncProjectLayerForRoot(root: string): boolean {
+	try {
+		const git = new GitRepository(createGitRunner(root));
+		const gitRoot = git.rootPath();
+		if (!gitRoot || existsSync(join(gitRoot, CORE_DIR))) return false;
+		const mainRoot = mainRootOf(git);
+		if (!mainRoot) return false;
+		return syncProjectLayer(mainRoot, gitRoot);
+	} catch {
+		return false;
+	}
+}
+
 /** Fatia a saída de `git worktree list --porcelain` em entradas. */
 export function parseWorktreeList(raw: string): WorktreeEntry[] {
 	const entries: WorktreeEntry[] = [];
@@ -150,11 +203,13 @@ export function parseWorktreeList(raw: string): WorktreeEntry[] {
 export class WorktreeManager {
 	private readonly git: GitRepository;
 	private readonly repoKey: string;
+	private readonly repoRoot: string;
 	private readonly rootDir: string;
 
 	constructor(git: GitRepository, options: WorktreeManagerOptions) {
 		this.git = git;
 		this.repoKey = options.repoKey;
+		this.repoRoot = options.repoRoot;
 		this.rootDir = join(
 			options.baseDir ?? worktreesRoot(),
 			repoSlug(options.repoKey),
@@ -214,6 +269,7 @@ export class WorktreeManager {
 
 		if (existing) {
 			if (existing.head === target) {
+				syncProjectLayer(this.repoRoot, path);
 				return { path, head: target, created: false, reused: true };
 			}
 			const checkout = new GitRepository(createGitRunner(path)).tryRun([
@@ -222,6 +278,7 @@ export class WorktreeManager {
 				target,
 			]);
 			if (checkout.ok) {
+				syncProjectLayer(this.repoRoot, path);
 				return { path, head: target, created: false, reused: true };
 			}
 			// Worktree quebrado/inacessível: remove e recria do zero.
@@ -251,6 +308,8 @@ export class WorktreeManager {
 				);
 			}
 		}
+		// A camada gerada é ignorada pelo git e não vem no checkout da PR.
+		syncProjectLayer(this.repoRoot, path);
 		return { path, head: target, created: true, reused: false };
 	}
 

package/src/tests/ai-features.test.ts

@@ -11,6 +11,8 @@ import { AiPreAnalyzer } from "../core/ai/features/pre-analyzer";
 import { AiTechnicalSummarizer } from "../core/ai/features/technical-summarizer";
 import { AiVerifier } from "../core/ai/features/verifier";
 import { briefInstructions, briefPrompt } from "../core/ai/prompts/brief";
+import { contextInstructions } from "../core/ai/prompts/context";
+import { technicalInstructions } from "../core/ai/prompts/technical";
 import { renderBrief } from "../core/brief";
 import { ProjectConfig } from "../core/project-config";
 import { FakeModelProvider } from "./fixtures/fake-model-provider";
@@ -217,3 +219,12 @@ describe("AiPreAnalyzer", () => {
 		).toEqual([]);
 	});
 });
+
+describe("idioma dos resumos", () => {
+	test("prompts de contexto e pontos técnicos exigem pt-BR", () => {
+		for (const instructions of [contextInstructions(), technicalInstructions()]) {
+			expect(instructions).toContain("português do Brasil");
+			expect(instructions).toContain("pt-BR");
+		}
+	});
+});

package/src/tests/worktree.test.ts

@@ -24,7 +24,12 @@ import { createGitRunner } from "../core/git-runner";
 import { defaultOptions } from "../core/orchestrator";
 import type { GhRunner } from "../core/services/gh-client";
 import { GitRepository } from "../core/services/git-repository";
-import { parseWorktreeList, WorktreeManager } from "../core/services/worktree-manager";
+import {
+	parseWorktreeList,
+	syncProjectLayer,
+	syncProjectLayerForRoot,
+	WorktreeManager,
+} from "../core/services/worktree-manager";
 import { SQLiteStorageProvider } from "../core/storage/sqlite/sqlite-storage";
 import { parseHuntArgs } from "../harness/hunt/hunt-options";
 import { fakeHoundsmanConfig } from "./fixtures/fake-project";
@@ -186,6 +191,71 @@ describe("nomes de diretório do worktree", () => {
 	});
 });
 
+describe("camada gerada no worktree", () => {
+	test("espelha `.houndsman/core` do clone principal e ignora origem ausente", () => {
+		const sandbox = makeSandbox();
+		try {
+			const worktree = join(sandbox.root, "wt-layer");
+			mkdirSync(worktree, { recursive: true });
+			mkdirSync(join(sandbox.repo, ".houndsman", "core"), { recursive: true });
+			writeFileSync(
+				join(sandbox.repo, ".houndsman", "core", "types.ts"),
+				"export {};\n",
+			);
+
+			expect(syncProjectLayer(sandbox.repo, worktree)).toBe(true);
+			expect(existsSync(join(worktree, ".houndsman", "core", "types.ts"))).toBe(
+				true,
+			);
+
+			// Sem camada na origem: no-op (fail-open).
+			const empty = join(sandbox.root, "empty");
+			mkdirSync(empty, { recursive: true });
+			expect(syncProjectLayer(empty, worktree)).toBe(false);
+		} finally {
+			sandbox.cleanup();
+		}
+	});
+
+	test("ensure copia a camada e o auto-reparo repõe num worktree existente", () => {
+		const sandbox = makeSandbox();
+		try {
+			mkdirSync(join(sandbox.repo, ".houndsman", "core"), { recursive: true });
+			writeFileSync(
+				join(sandbox.repo, ".houndsman", "core", "types.ts"),
+				"export {};\n",
+			);
+			const manager = new WorktreeManager(
+				new GitRepository(createGitRunner(sandbox.repo)),
+				{
+					repoKey: "path:fake",
+					repoRoot: sandbox.repo,
+					baseDir: sandbox.home,
+				},
+			);
+
+			const ensured = manager.ensure({
+				branch: "feature",
+				ref: sandbox.featureSha,
+			});
+			const layer = join(ensured.path, ".houndsman", "core", "types.ts");
+			expect(existsSync(layer)).toBe(true);
+
+			// Comando rodando no worktree (sem `--pr`) também se auto-repara.
+			rmSync(join(ensured.path, ".houndsman", "core"), {
+				recursive: true,
+				force: true,
+			});
+			expect(syncProjectLayerForRoot(ensured.path)).toBe(true);
+			expect(existsSync(layer)).toBe(true);
+
+			manager.remove("feature");
+		} finally {
+			sandbox.cleanup();
+		}
+	}, 20_000);
+});
+
 describe("WorktreeManager", () => {
 	test("cria detached, reusa o mesmo commit e remove", () => {
 		const sandbox = makeSandbox();