@payconductor/houndsman 0.6.0 → 0.8.0

package/README.md

@@ -98,6 +98,26 @@ bun run houndsman hunt --fail-on-blocking
 
 Detalhes (catálogo de tools, máquina de estados, custos e segurança): [`docs/HARNESS.md`](docs/HARNESS.md).
 
+### 8. Várias PRs ao mesmo tempo (worktrees)
+
+Cada revisão pode rodar em um **worktree dedicado** (detached no commit da PR), sem
+checkout no clone principal e sem bloquear a revisão das outras PRs:
+
+```bash
+houndsman --pr 123                 # cria/reusa o worktree e prepara os briefs
+houndsman hunt --pr 123            # revisão nativa no mesmo worktree
+houndsman --pr 123 --finalize      # consolida o relatório
+houndsman worktree list            # worktrees ativos
+houndsman worktree remove feature/x
+```
+
+Os worktrees ficam em `<repo>/.houndsman/worktrees/<repo>/<branch>` (ignorados pelo git) e
+são removidos manualmente (ou com `houndsman worktree prune`). Ficam **dentro do
+workspace** de propósito: agentes de codificação com permissão escopada à pasta aberta
+conseguem ler/executar sem pedir autorização. Para voltar ao diretório global, use
+`worktrees: { location: "home" }` no `houndsman.config.ts`. A UI (`houndsman server`)
+mostra o worktree ativo de cada PR e permite criá-lo pela sidebar.
+
 ---
 
 ## O fluxo de trabalho

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@payconductor/houndsman",
-	"version": "0.6.0",
+	"version": "0.8.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/commands/command.ts

@@ -5,14 +5,23 @@
  * exit code. O engine é carregado sob demanda (comandos sem projeto não pagam).
  */
 
+import type { HoundsmanConfig } from "../../core/config";
 import type { HoundsmanEngine } from "../../core/engine/houndsman-engine";
 import type { LoggerLike } from "../../core/logging";
 
+/** Raiz operacional pedida ao engine (worktree/clone principal). */
+export type EngineLoadOptions = {
+	root?: string;
+	mainRoot?: string;
+};
+
 /** Contexto de execução de um comando. */
 export type CliContext = {
 	cwd: string;
 	/** Carrega a config do projeto e devolve o engine (lazy). */
-	engine: () => Promise<HoundsmanEngine>;
+	engine: (options?: EngineLoadOptions) => Promise<HoundsmanEngine>;
+	/** Config do projeto (mesmo carregamento cacheado do engine). */
+	config: () => Promise<HoundsmanConfig>;
 	/** Logger único do CLI (cores/spinner/progresso). */
 	logger: LoggerLike;
 	/** @deprecated use `logger.info`. */

package/src/cli/commands/context-command.ts

@@ -1,6 +1,7 @@
 /** Comando `context` — coleta o contexto da PR via `gh` (Passo 0). */
 
 import { runContextCommand } from "../../core/commands/context";
+import { resolveReviewWorkspace } from "../../core/engine/review-workspace";
 import { displayPath } from "../../core/paths";
 import { ArgParser } from "../arg-parser";
 import type { CliContext, Command } from "./command";
@@ -9,13 +10,50 @@ export class ContextCommand implements Command {
 	readonly name = "context";
 
 	async run(args: string[], context: CliContext): Promise<number> {
-		const engine = await context.engine();
 		const parser = ArgParser.from(args);
+		const prFlag = parser.value("--pr");
+		const worktreeFlag = parser.value("--worktree");
+		const prNumber = prFlag ? Number.parseInt(prFlag, 10) : undefined;
+		if (prFlag && (!Number.isFinite(prNumber) || (prNumber ?? 0) <= 0)) {
+			context.err(`--pr inválido: '${prFlag}'.`);
+			return 1;
+		}
+		if (prNumber !== undefined && worktreeFlag !== undefined) {
+			context.err("Use --pr ou --worktree, não os dois.");
+			return 1;
+		}
+
+		const config = await context.config();
+		const workspace =
+			prNumber !== undefined || worktreeFlag !== undefined
+				? resolveReviewWorkspace(
+						{
+							cwd: context.cwd,
+							base: "main",
+							head: "HEAD",
+							branch: parser.value("--branch"),
+							pr: prNumber,
+							worktree: worktreeFlag,
+						},
+						{ worktreesLocation: config.worktrees?.location },
+					)
+				: undefined;
+		for (const message of workspace?.messages ?? []) context.out(message);
+
+		const engine = await context.engine(
+			workspace
+				? { root: workspace.root, mainRoot: workspace.mainRoot }
+				: undefined,
+		);
 		const { paths, context: pr } = runContextCommand(
 			engine.config,
 			engine.storage,
 			engine.repo,
-			{ branch: parser.value("--branch") },
+			{
+				branch: workspace?.branch ?? parser.value("--branch"),
+				worktreePath: workspace?.worktreePath,
+				prNumber: workspace?.prNumber,
+			},
 		);
 
 		if (pr.available) {

package/src/cli/commands/hunt-command.ts

@@ -1,5 +1,6 @@
 /** Comando `hunt` — revisão nativa com IA (harness próprio). */
 
+import { resolveReviewWorkspace } from "../../core/engine/review-workspace";
 import { HuntHarness } from "../../harness";
 import { parseHuntArgs } from "../../harness/hunt/hunt-options";
 import type { CliContext, Command } from "./command";
@@ -10,9 +11,34 @@ export class HuntCommand implements Command {
 
 	async run(args: string[], context: CliContext): Promise<number> {
 		const options = parseHuntArgs(args);
-		const engine = await context.engine();
+		const config = await context.config();
+		const workspace = resolveReviewWorkspace(
+			{
+				cwd: context.cwd,
+				base: options.base,
+				head: options.head,
+				branch: options.branch,
+				pr: options.pr,
+				worktree: options.worktree,
+			},
+			{ worktreesLocation: config.worktrees?.location },
+		);
+		for (const message of workspace.messages) context.logger.info(message);
+
+		const engine = await context.engine({
+			root: workspace.root,
+			mainRoot: workspace.mainRoot,
+		});
+		const resolved = {
+			...options,
+			branch: workspace.branch,
+			base: workspace.base,
+			head: workspace.head,
+			pr: workspace.prNumber,
+			worktreePath: workspace.worktreePath,
+		};
 		try {
-			const harness = await HuntHarness.from(engine, options, context.logger);
+			const harness = await HuntHarness.from(engine, resolved, context.logger);
 			const result = await harness.run();
 			for (const message of result.messages) context.logger.info(message);
 			if (result.status === "failed") return 1;

package/src/cli/commands/review-command.ts

@@ -1,15 +1,43 @@
 /** Comando default — prepara ou finaliza a revisão. */
 
 import { parseReviewArgs } from "../../core/commands/review";
+import { resolveReviewWorkspace } from "../../core/engine/review-workspace";
 import type { CliContext, Command } from "./command";
 
 export class ReviewCommand implements Command {
 	readonly name = "";
 
 	async run(args: string[], context: CliContext): Promise<number> {
-		const engine = await context.engine();
 		const options = parseReviewArgs(args);
-		const result = await engine.session(options).run();
+		const config = await context.config();
+		const workspace = resolveReviewWorkspace(
+			{
+				cwd: context.cwd,
+				base: options.base,
+				head: options.head,
+				branch: options.branch,
+				pr: options.pr,
+				worktree: options.worktree,
+			},
+			{ worktreesLocation: config.worktrees?.location },
+		);
+		for (const message of workspace.messages) context.out(message);
+
+		// Sem `--pr`/`--worktree`, o engine usa o workspace gravado da review
+		// (finalize após um prepare feito em worktree, por exemplo).
+		const explicit = options.pr !== undefined || options.worktree !== undefined;
+		const engine = await context.engine(
+			explicit ? { root: workspace.root, mainRoot: workspace.mainRoot } : undefined,
+		);
+		const resolved = {
+			...options,
+			branch: workspace.branch,
+			base: workspace.base,
+			head: workspace.head,
+			pr: workspace.prNumber,
+			worktreePath: workspace.worktreePath,
+		};
+		const result = await engine.session(resolved).run();
 
 		for (const message of result.messages) context.out(message);
 

package/src/cli/commands/server-command.ts

@@ -26,9 +26,15 @@ export class ServerCommand implements Command {
 		const parser = ArgParser.from(args);
 		const port = Number(parser.value("--port")) || 7331;
 		const host = parser.value("--host") ?? "127.0.0.1";
+		const editorPreference = parser.value("--editor");
 
 		const { startServer } = await import("../../server");
-		const { url } = startServer({ config: engine.config, port, host });
+		const { url } = startServer({
+			config: engine.config,
+			port,
+			host,
+			editorPreference,
+		});
 		context.out(`[houndsman] servidor em ${url}`);
 		context.out("[houndsman] Ctrl+C para encerrar.");
 		if (parser.has("--open")) openBrowser(url);

package/src/cli/commands/worktree-command.ts

@@ -0,0 +1,118 @@
+/**
+ * Comando `worktree` — gerencia os worktrees de revisão.
+ *
+ * `list` (default) · `add --pr <n>` · `add --branch <b> [--ref <r>]` ·
+ * `remove <branch|path> [--force]` · `prune` · `path <branch>`.
+ */
+
+import { resolveReviewWorkspace } from "../../core/engine/review-workspace";
+import { WorktreeManager } from "../../core/services/worktree-manager";
+import { resolveWorktreesRoot } from "../../core/storage/paths";
+import { ArgParser } from "../arg-parser";
+import type { CliContext, Command } from "./command";
+
+/** Executa a manutenção dos worktrees. */
+export class WorktreeCommand implements Command {
+	readonly name = "worktree";
+
+	async run(args: string[], context: CliContext): Promise<number> {
+		const parser = ArgParser.from(args);
+		const action = parser.command() ?? "list";
+		const config = await context.config();
+		const engine = await context.engine();
+		const manager = new WorktreeManager(engine.git, {
+			repoKey: engine.repo.key,
+			repoRoot: engine.mainRoot,
+			baseDir: resolveWorktreesRoot(config.worktrees?.location, engine.mainRoot),
+		});
+
+		switch (action) {
+			case "list": {
+				const entries = manager.managed();
+				if (entries.length === 0) {
+					context.out(`Nenhum worktree em ${manager.baseDir}.`);
+					return 0;
+				}
+				context.out(`Worktrees em ${manager.baseDir}:`);
+				for (const entry of entries) {
+					const branch = entry.branch
+						? entry.branch.replace(/^refs\/heads\//, "")
+						: "(detached)";
+					context.out(
+						`- ${branch} · ${entry.path}${entry.prunable ? " · órfão" : ""}`,
+					);
+				}
+				return 0;
+			}
+			case "add": {
+				const pr = parser.value("--pr");
+				if (pr) {
+					const number = Number.parseInt(pr, 10);
+					if (!Number.isFinite(number) || number <= 0) {
+						context.err(`--pr inválido: '${pr}'.`);
+						return 1;
+					}
+					const workspace = resolveReviewWorkspace(
+						{
+							cwd: context.cwd,
+							base: "main",
+							head: "HEAD",
+							pr: number,
+						},
+						{ worktreesLocation: config.worktrees?.location },
+					);
+					for (const message of workspace.messages) context.out(message);
+					context.out(workspace.worktreePath ?? workspace.root);
+					return 0;
+				}
+
+				const branch = parser.value("--branch");
+				if (!branch) {
+					context.err("Informe --pr <n> ou --branch <nome>.");
+					return 1;
+				}
+				const ref = parser.value("--ref") ?? branch;
+				const result = manager.ensure({ branch, ref });
+				context.out(
+					`${result.created ? "Criado" : "Reutilizado"}: ${result.path} @ ${result.head.slice(0, 7)}`,
+				);
+				return 0;
+			}
+			case "remove": {
+				const target = parser.positionals()[1] ?? parser.value("--branch");
+				if (!target) {
+					context.err("Informe a branch ou o caminho do worktree.");
+					return 1;
+				}
+				const result = manager.remove(target, { force: parser.has("--force") });
+				if (!result.removed) {
+					context.err(
+						`Worktree não removido: ${result.detail ?? "desconhecido"}.`,
+					);
+					return 1;
+				}
+				context.out(`Worktree removido: ${target}.`);
+				return 0;
+			}
+			case "prune": {
+				manager.prune();
+				context.out(`Worktrees órfãos removidos em ${manager.baseDir}.`);
+				return 0;
+			}
+			case "path": {
+				const branch = parser.positionals()[1] ?? parser.value("--branch");
+				if (!branch) {
+					context.err("Informe a branch.");
+					return 1;
+				}
+				context.out(manager.pathFor(branch));
+				return 0;
+			}
+			default:
+				context.err(
+					`Ação desconhecida em 'worktree': '${action}'. Use list, add, remove, prune ou path.`,
+				);
+				return 1;
+		}
+	}
+}

package/src/cli/help.ts

@@ -4,11 +4,12 @@ export 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)
+  context             Coleta o contexto da PR via gh (Passo 0; --pr/--worktree)
   hunt                Revisão nativa com IA (harness próprio): prepare + agentes + finalize
   findings <sub>      Triagem/correção dos findings (list · show · set · done · reset · sync · summary · batch · verify · submit · path)
   status [ping]       Mostra o status da run (ping renova o heartbeat da execução)
-  server              Sobe a UI local de triagem (--port, --host, --open)
+  worktree <ação>     Lista/cria/remove worktrees de revisão (list · add · remove · prune · path)
+  server              Sobe a UI local de triagem (--port, --host, --open, --editor)
   setup               Cria a configuração inicial do projeto (config + skills)
   update              Sincroniza os arquivos auto-gerados (.houndsman/core)
   doctor              Valida a configuração, o ambiente e a credencial Jev
@@ -20,6 +21,8 @@ Flags:
   --base <branch>     Base do diff (default: main)
   --head <ref>        Head do diff (default: HEAD)
   --branch <nome>     Branch alvo (default: detecta do git)
+  --pr <n>            Revisa a PR em um worktree dedicado (cria/reusa automaticamente)
+  --worktree <path>   Revisa em um worktree já existente
   --clean             Descarta findings brutos do staging anterior
   --full              Força review completo (ignora o modo incremental)
   --no-jev            Desativa a pré-análise Jev
@@ -28,7 +31,7 @@ Flags:
   --fail-on-blocking  Exit 1 se houver bloqueantes (com --finalize)
 
 Flags do hunt:
-  --base <b> · --head <ref> · --branch <nome> · --watchdog <id>
+  --base <b> · --head <ref> · --branch <nome> · --watchdog <id> · --pr <n> · --worktree <path>
   --full · --clean · --no-ast · --with-jev
   --resume · --allow-partial · --dry-run · --fail-on-blocking
   --max-calls <n> · --concurrency <n> · --provider <p> · --model <m>
@@ -52,6 +55,13 @@ Flags de findings:
   --dry-run           (submit) Só a prévia do envio, sem postar
   --no-ping           (doctor) Pula a validação de rede das credenciais
 
+Worktrees:
+  houndsman worktree list
+  houndsman worktree add --pr 123
+  houndsman worktree remove <branch> [--force]
+  Os worktrees ficam em <repo>/.houndsman/worktrees/<repo>/<branch> (detached).
+  Use worktrees.location: "home" na config para voltar ao HOUNDSMAN_HOME.
+
 Persistência:
   Runs, findings e artefatos ficam no storage global (SQLite em
   <HOUNDSMAN_HOME>/houndsman.db). Use storage.provider: "file" na config para

package/src/cli/index.ts

@@ -27,6 +27,7 @@
  *   `--clean` · `--full` · `--no-jev` · `--no-ast` · `--fail-on-blocking`.
  */
 
+import type { HoundsmanConfig } from "../core/config";
 import { loadConfig } from "../core/config-loader";
 import { HoundsmanEngine } from "../core/engine/houndsman-engine";
 import { logger } from "../core/logging";
@@ -43,6 +44,7 @@ import { ServerCommand } from "./commands/server-command";
 import { SetupCommand, TestCommand, UpdateCommand } from "./commands/setup-command";
 import { StatusCommand } from "./commands/status-command";
 import { WatchdogCommand } from "./commands/watchdog-command";
+import { WorktreeCommand } from "./commands/worktree-command";
 import { HELP } from "./help";
 
 // ---------------------------------------------------------------------------
@@ -60,6 +62,7 @@ function buildRegistry(): CommandRegistry {
 		.register(new FindingsCommand())
 		.register(new StatusCommand())
 		.register(new WatchdogCommand())
+		.register(new WorktreeCommand())
 		.register(new ServerCommand())
 		.register(new SetupCommand())
 		.register(new UpdateCommand())
@@ -85,16 +88,23 @@ export async function main(): Promise<void> {
 		process.exit(1);
 	}
 
+	let loaded: Awaited<ReturnType<typeof loadConfig>> | null = null;
+	const config = async (): Promise<HoundsmanConfig> => {
+		loaded ??= await loadConfig({ configPath: parser.value("--config") });
+		return loaded.config;
+	};
+
 	const context: CliContext = {
 		cwd: process.cwd(),
 		logger,
 		out: (message) => logger.info(message),
 		err: (message) => logger.error(message),
-		engine: async () => {
-			const { config } = await loadConfig({
-				configPath: parser.value("--config"),
+		config,
+		engine: async (options = {}) => {
+			return new HoundsmanEngine(await config(), {
+				root: options.root,
+				mainRoot: options.mainRoot,
 			});
-			return new HoundsmanEngine(config);
 		},
 	};
 

package/src/core/ast/service.ts

@@ -27,10 +27,15 @@ export class AstService {
 	private readonly git: GitRepository;
 	private readonly parser: AstParser;
 
-	constructor(config: HoundsmanConfig, git: GitRepository = new GitRepository()) {
+	constructor(
+		config: HoundsmanConfig,
+		git: GitRepository = new GitRepository(),
+		root: string = process.cwd(),
+	) {
 		this.project = new ProjectConfig(config);
 		this.git = git;
-		const layerGrammars = join(process.cwd(), CORE_DIR, "grammars");
+		// Camada do projeto (quando presente); sem ela o parser usa o wasm embarcado.
+		const layerGrammars = join(root, CORE_DIR, "grammars");
 		this.parser = new AstParser({
 			maxFileBytes: this.project.astMaxFileBytes,
 			languages: this.project.ast.languages,

package/src/core/brief.ts

@@ -265,6 +265,7 @@ export function defaultRenderBrief(
 		`# Brief — ${def.name} (\`${def.id}\`)`,
 		"",
 		`**Branch:** ${args.branch}`,
+		...(args.worktree ? [`**Worktree:** \`${args.worktree}\``] : []),
 		`**Output obrigatório:** \`${args.outputPath}\``,
 		`**Schema do output:** \`${args.outputFormatPath}\``,
 		"",

package/src/core/commands/context.ts

@@ -26,13 +26,21 @@ export function runContextCommand(
 	_config: HoundsmanConfig,
 	storage: StorageProvider,
 	repo: RepoIdentity,
-	opts: { branch?: string } = {},
+	opts: {
+		branch?: string;
+		/** Worktree onde a review roda (persistido na review). */
+		worktreePath?: string;
+		/** PR de origem (persistida na review). */
+		prNumber?: number;
+	} = {},
 ): ContextRunResult {
 	const branch = opts.branch ?? currentBranch();
 	const review = storage.getOrCreateReview({
 		repo,
 		branch,
 		slug: sanitizeBranch(branch),
+		worktreePath: opts.worktreePath,
+		prNumber: opts.prNumber,
 	});
 	const work = new ReviewWorkArea(review);
 	const paths = work.contextPaths;

package/src/core/commands/findings.ts

@@ -10,6 +10,7 @@
  * com o UUID interno no banco.
  */
 
+import { existsSync } from "node:fs";
 import { AiClient } from "../ai/ai-client";
 import { AiVerifier } from "../ai/features/verifier";
 import { type HoundsmanConfig, resolveJevConcurrency } from "../config";
@@ -107,11 +108,13 @@ function parseArgs(args: string[]): ParsedArgs {
 	return parsed;
 }
 
-/** Contexto de uma review (storage + registro + staging). */
+/** Contexto de uma review (storage + registro + staging + raiz). */
 type CommandContext = {
 	storage: StorageProvider;
 	review: ReviewRecord;
 	work: ReviewWorkArea;
+	/** Worktree da review quando existir; senão, a raiz do repositório. */
+	root: string;
 };
 
 /** Resolve a review da branch atual (explícita ou via git). */
@@ -127,7 +130,10 @@ function openContext(
 			`Nenhuma revisão para '${branch}'. Rode \`houndsman --finalize\` primeiro.`,
 		);
 	}
-	return { storage, review, work: new ReviewWorkArea(review) };
+	const worktree = review.worktreePath;
+	// Sem worktree, mantém a raiz onde o comando foi invocado (comportamento histórico).
+	const root = worktree && existsSync(worktree) ? worktree : process.cwd();
+	return { storage, review, work: new ReviewWorkArea(review), root };
 }
 
 /** Lê o estado de triagem; lança se a review ainda não tem findings. */
@@ -380,7 +386,7 @@ function execute(
 		}
 		case "sync": {
 			const state = loadState(ctx);
-			const result = syncState(state, fileReader(process.cwd()));
+			const result = syncState(state, fileReader(ctx.root));
 			ctx.storage.writeFindings(ctx.review.id, state);
 			pingStatus(ctx, state);
 			const output = parsed.bools.has("--json")
@@ -517,7 +523,7 @@ async function executeVerify(
 	const { JevCandidatesStore, JevClient, JevVerifier } = await import("../jev");
 
 	const findings = verifier.select(state, filterFrom(parsed));
-	const entries = verifier.verifyLocal(findings, fileReader(process.cwd()));
+	const entries = verifier.verifyLocal(findings, fileReader(ctx.root));
 
 	// Tier 1 — Jev só nos ambíguos (fail-open: sem chave/erro mantém o provisório).
 	let jevChecked = 0;
@@ -565,7 +571,7 @@ async function executeVerify(
 		} else if (!aiVerifier.enabled) {
 			aiReason = "feature ai.features.verify desligada";
 		} else {
-			const readFile = fileReader(process.cwd());
+			const readFile = fileReader(ctx.root);
 			const byId = new Map(findings.map((finding) => [finding.id, finding]));
 			const confidence = await aiVerifier.verify({
 				findings: stillAmbiguous.map((entry) => ({
@@ -657,18 +663,23 @@ function splitList(raw: string | undefined): string[] {
 		.filter(Boolean);
 }
 
-/** Seleção do envio a partir das flags (`--severity`, `--exec`, `--include-sent`). */
+/** Seleção do envio a partir das flags (`--severity`, `--decision`, `--exec`). */
 function submitSelection(parsed: ParsedArgs): SubmitSelection {
 	const severities = splitList(parsed.values["--severity"]).filter(
 		(value): value is Severity =>
 			(SEVERITY_ORDER as readonly string[]).includes(value),
 	);
+	const decisions = splitList(parsed.values["--decision"]).filter(
+		(value): value is FindingDecision =>
+			(FINDING_DECISIONS as readonly string[]).includes(value),
+	);
 	const execStates = splitList(parsed.values["--exec"]).filter(
 		(value): value is FindingExecState =>
 			(FINDING_EXEC_STATES as readonly string[]).includes(value),
 	);
 	return {
 		severities: severities.length > 0 ? severities : undefined,
+		decisions: decisions.length > 0 ? decisions : undefined,
 		execStates: execStates.length > 0 ? execStates : undefined,
 		includeSent: parsed.bools.has("--include-sent"),
 	};

package/src/core/commands/review.ts

@@ -20,9 +20,22 @@ export function parseReviewArgs(args: string[]): ReviewOptions {
 	const base = parser.value("--base");
 	const head = parser.value("--head");
 	const branch = parser.value("--branch");
+	const pr = parser.value("--pr");
+	const worktree = parser.value("--worktree");
 	if (base) opts.base = base;
 	if (head) opts.head = head;
 	if (branch) opts.branch = branch;
+	if (worktree) opts.worktree = worktree;
+	if (pr) {
+		const number = Number.parseInt(pr, 10);
+		if (!Number.isFinite(number) || number <= 0) {
+			throw new Error(`--pr inválido: '${pr}'.`);
+		}
+		opts.pr = number;
+	}
+	if (opts.pr !== undefined && opts.worktree !== undefined) {
+		throw new Error("Use --pr ou --worktree, não os dois.");
+	}
 
 	if (parser.has("--finalize") || parser.has("--report-only")) opts.finalize = true;
 	if (parser.has("--fail-on-blocking")) opts.failOnBlocking = true;

package/src/core/commands/scaffold.ts

@@ -398,10 +398,12 @@ const DOC_MAPPINGS_TEMPLATE = `/**
 export const DOC_MAPPINGS: readonly (readonly [RegExp, readonly string[]])[] = [];
 `;
 
-const PROJECT_GITIGNORE = `# Diretórios gerados pelo houndsman — \`core/\` é regenerado por \`houndsman update\`
-# e \`.runs/\` guarda os artefatos de revisão.
+const PROJECT_GITIGNORE = `# Diretórios gerados pelo houndsman — \`core/\` é regenerado por \`houndsman update\`.
+# \`work/\` e \`worktrees/\` são runtime de revisão (staging e worktrees).
 core/
 .runs/
+work/
+worktrees/
 `;
 
 // ---------------------------------------------------------------------------

package/src/core/config.ts

@@ -108,6 +108,17 @@ export type HoundsmanAi = {
 	watchdogs?: Record<string, HoundsmanAiWatchdog>;
 };
 
+/** Onde os worktrees de revisão são criados. */
+export type HoundsmanWorktrees = {
+	/**
+	 * `workspace` (default): `<repo>/.houndsman/worktrees` — dentro da pasta
+	 * aberta no editor, então agentes com permissão escopada ao workspace
+	 * conseguem ler/executar sem prompts. `home`: `<HOUNDSMAN_HOME>/worktrees`.
+	 * Qualquer outro valor é um caminho (absoluto ou relativo à raiz do repo).
+	 */
+	location?: "home" | "workspace" | string;
+};
+
 /** Backend de persistência (reviews, findings e artefatos). */
 export type HoundsmanStorage = {
 	/**
@@ -132,6 +143,8 @@ export type HoundsmanConfig<TId extends string = string> = {
 	projectName: string;
 	/** Persistência das runs e artefatos (default: SQLite global). */
 	storage?: HoundsmanStorage;
+	/** Localização dos worktrees de revisão (default: dentro do workspace). */
+	worktrees?: HoundsmanWorktrees;
 	/**
 	 * Ids dos watchdogs — **derivados** das chaves de `watchdogs` por
 	 * `defineHoundsmanConfig` (não informar manualmente).