@payconductor/houndsman 0.11.0 → 0.13.0

package/src/core/orchestrator.ts

@@ -16,7 +16,7 @@
  * review.<watchdog>.md, context e context-summary.
  */
 
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { join } from "node:path";
 import type { AiClient } from "./ai/ai-client";
 import { AiBriefEnricher } from "./ai/features/brief-enricher";
@@ -28,6 +28,7 @@ import type { BriefPlan } from "./ai/schemas";
 import { assetPath, OUTPUT_FORMAT_FILE } from "./assets";
 import type { AstService } from "./ast/service";
 import type { AstAnalysis, AstFileBrief, AstImpact } from "./ast/types";
+import { summarizeScope } from "./changed-scope";
 import {
 	type HoundsmanConfig,
 	resolveJevConcurrency,
@@ -38,7 +39,11 @@ import { discoverDocs } from "./doc-discoverer";
 import { Classification } from "./domain/classification";
 import { Watchdog } from "./domain/watchdog";
 import { mergeCarryover } from "./engine/carryover";
-import { ReviewScopeResolver, type RunClassification } from "./engine/review-scope";
+import {
+	ReviewScopeResolver,
+	type RunClassification,
+	type ScopeProgress,
+} from "./engine/review-scope";
 import { ENV_NAMES } from "./env";
 import type { BudgetSelection, ClassificationResult } from "./file-classifier";
 import { buildStateFromFindings, fileReader } from "./findings-state";
@@ -101,7 +106,7 @@ export type ReviewOptions = {
 	noAst: boolean;
 	/** Força review completo (ignora o modo incremental). */
 	full: boolean;
-	/** Desativa as features de IA do fluxo normal (hunt não usa esta flag). */
+	/** Desativa as features de IA do fluxo normal. */
 	noAi: boolean;
 	/** PR de origem (resolvida via `--pr`). */
 	pr?: number;
@@ -231,7 +236,7 @@ function writeManifest(
 
 function writeBriefs(
 	activeIds: string[],
-	classification: ClassificationResult,
+	classification: RunClassification,
 	ctx: ReviewContext,
 	branch: string,
 	context: ContextSummary | null,
@@ -276,6 +281,7 @@ function writeBriefs(
 			candidates: candidates.filter((c) => c.watchdogId === id),
 			ast: astFiles,
 			aiPlan: aiPlans?.get(id),
+			changedScope: classification.changedScope,
 		});
 		const content = `${brief}\n`;
 		work.writeBrief(id, content);
@@ -322,7 +328,9 @@ async function resolveCandidates(
 				const def = findWatchdog(config, id);
 				if (!def) continue;
 				const inputs = files.slice(0, 5).flatMap((file) => {
-					const snippet = readSnippet(ctx.root, file);
+					// Só o trecho alterado: candidato fora do diff vira ruído de código
+					// pré-existente no brief do watchdog.
+					const snippet = diff.byFile.get(file);
 					return snippet ? [{ file, snippet }] : [];
 				});
 				candidates.push(
@@ -406,6 +414,16 @@ function discoveryMessages(
 	return messages;
 }
 
+/** Resumo do escopo — lembra que só as faixas alteradas são revisáveis. */
+function changedScopeMessage(classification: RunClassification): string[] {
+	const scope = classification.changedScope;
+	if (!scope) return [];
+	const totals = summarizeScope(scope);
+	return [
+		`Escopo: ${totals.files} arquivo(s), ${totals.symbols} símbolo(s) em ${totals.ranges} faixa(s) alterada(s).`,
+	];
+}
+
 /** Resumo do orçamento — só quando algum arquivo ficou de fora (PR grande). */
 function budgetMessage(
 	classification: ClassificationResult,
@@ -422,18 +440,85 @@ function budgetMessage(
 	];
 }
 
-/** Primeiras 80 linhas de um arquivo (pré-análise por IA; fail-open). */
-function readSnippet(root: string, file: string): string | null {
+/** Resultado do prepare — mensagens para o CLI imprimir. */
+export type PrepareResult = {
+	messages: string[];
+	/** Watchdogs ativos neste ciclo (vazio em no-op/sem arquivos). */
+	activeIds: string[];
+	/** Diretório dos briefs do ciclo (ausente quando não há briefs). */
+	briefsDir?: string;
+	/** Review do ciclo (ausente quando nada foi preparado). */
+	reviewId?: string;
+};
+
+/** Etapas do prepare reportadas ao CLI (o core não escreve saída). */
+export type PrepareStage =
+	| "diff"
+	| "ast"
+	| "classify"
+	| "impact"
+	| "jev"
+	| "context"
+	| "technical"
+	| "ai-plans"
+	| "briefs"
+	| "manifest";
+
+/** Evento de progresso de uma etapa do prepare. */
+export type PrepareProgressEvent =
+	| { type: "start"; stage: PrepareStage }
+	| { type: "done"; stage: PrepareStage; durationMs: number };
+
+/** Callback de progresso do prepare (falhas do callback são ignoradas). */
+export type PrepareProgress = (event: PrepareProgressEvent) => void;
+
+/** Encaminha o progresso do escopo como etapa do prepare. */
+function scopeProgress(onProgress?: PrepareProgress): ScopeProgress | undefined {
+	if (!onProgress) return undefined;
+	return (event) => emitProgress(onProgress, event);
+}
+
+/** Emite um evento de progresso sem deixar o callback derrubar a revisão. */
+function emitProgress(
+	onProgress: PrepareProgress | undefined,
+	event: PrepareProgressEvent,
+): void {
 	try {
-		const path = join(root, file);
-		return readFileSync(path, "utf8").split("\n").slice(0, 80).join("\n");
+		onProgress?.(event);
 	} catch {
-		return null;
+		// Progresso nunca derruba a revisão.
 	}
 }
 
-/** Resultado do prepare — mensagens para o CLI imprimir. */
-export type PrepareResult = { messages: string[] };
+/** Executa uma etapa reportando início/fim (sync ou async). */
+async function runStage<T>(
+	onProgress: PrepareProgress | undefined,
+	stage: PrepareStage,
+	run: () => Promise<T> | T,
+): Promise<T> {
+	if (!onProgress) return run();
+	const started = Date.now();
+	emitProgress(onProgress, { type: "start", stage });
+	try {
+		return await run();
+	} finally {
+		emitProgress(onProgress, {
+			type: "done",
+			stage,
+			durationMs: Date.now() - started,
+		});
+	}
+}
+
+/** Como `runStage`, mas só reporta quando a etapa realmente vai rodar. */
+async function runOptionalStage<T>(
+	onProgress: PrepareProgress | undefined,
+	enabled: boolean,
+	stage: PrepareStage,
+	run: () => Promise<T> | T,
+): Promise<T> {
+	return enabled ? runStage(onProgress, stage, run) : run();
+}
 
 /**
  * Classificação fallback por IA (opcional): atribui arquivos não classificados
@@ -591,6 +676,7 @@ export async function prepare(
 	ctx: ReviewContext,
 	ast?: AstService,
 	ai?: AiClient,
+	onProgress?: PrepareProgress,
 ): Promise<PrepareResult> {
 	const messages: string[] = [];
 	ctx.work.ensure();
@@ -605,6 +691,7 @@ export async function prepare(
 		config,
 		opts.noAst ? undefined : ast,
 		ctx.git,
+		scopeProgress(onProgress),
 	).resolve(previous, headSha);
 
 	// Mesmo commit já revisado: preserva artefatos e triagem, sem re-revisar.
@@ -622,7 +709,7 @@ export async function prepare(
 				? "Nada novo a preparar — o ciclo em andamento continua; rode `--finalize` quando os findings estiverem gravados."
 				: "Nada a revisar — o relatório anterior foi mantido. Use `--full` para re-revisar.",
 		);
-		return { messages };
+		return { messages, activeIds: [] };
 	}
 
 	const { classification, diff } = scope;
@@ -639,7 +726,7 @@ export async function prepare(
 			messages.push(
 				`Nenhuma alteração entre ${opts.base}...${opts.head} — nenhuma run criada.`,
 			);
-			return { messages };
+			return { messages, activeIds: [] };
 		}
 	}
 
@@ -657,7 +744,10 @@ export async function prepare(
 	});
 
 	const astAnalyses = scope.ast;
-	const astImpact = astAnalyses && ast ? await ast.impact(astAnalyses) : undefined;
+	const astImpact =
+		astAnalyses && ast
+			? await runStage(onProgress, "impact", () => ast.impact(astAnalyses))
+			: undefined;
 	if (astAnalyses && ast?.enabled) {
 		const summary = {
 			enabled: true,
@@ -686,7 +776,13 @@ export async function prepare(
 		}
 	}
 
-	const jev = await resolveCandidates(opts, classification, ctx, config, diff, ai);
+	const jevWillRun = Boolean(
+		(ai && !opts.noAi && new AiPreAnalyzer(ai).enabled) ||
+			(!opts.noJev && new JevClient().isConfigured()),
+	);
+	const jev = await runOptionalStage(onProgress, jevWillRun, "jev", () =>
+		resolveCandidates(opts, classification, ctx, config, diff, ai),
+	);
 
 	const activeIds = Object.keys(classification.watchdogs);
 	if (Object.keys(classification.files).length === 0) {
@@ -696,14 +792,14 @@ export async function prepare(
 				? `Nenhuma alteração desde a última revisão (${shortSha(classification.reviewedFrom ?? "")}).`
 				: `Nenhuma alteração entre ${opts.base}...${opts.head}.`,
 		);
-		return { messages };
+		return { messages, activeIds: [] };
 	}
 	if (activeIds.length === 0) {
 		writeRunStatus(ctx.storage, ctx.review.id, { status: "review_done" });
 		messages.push(
 			"Nenhum arquivo revisável (tudo excluído, deletado ou irrelevante).",
 		);
-		return { messages };
+		return { messages, activeIds: [] };
 	}
 	if (classification.mode === "incremental") {
 		messages.push(
@@ -712,15 +808,21 @@ export async function prepare(
 	}
 
 	persistContext(ctx);
-	const context = await resolveContextSummary(ctx, ai, opts);
-	await resolveTechnicalSummary(ctx, ai, opts, {
-		branch,
-		classification,
-		context,
-		ast: astAnalyses,
-		impact: astImpact,
-		domains: activeIds.map((id) => findWatchdog(config, id)?.name ?? id),
-	});
+	const aiContext = ai && !opts.noAi ? new AiContextSummarizer(ai).enabled : false;
+	const context = await runOptionalStage(onProgress, aiContext, "context", () =>
+		resolveContextSummary(ctx, ai, opts),
+	);
+	const aiTechnical = ai && !opts.noAi ? new AiTechnicalSummarizer(ai).enabled : false;
+	await runOptionalStage(onProgress, aiTechnical, "technical", () =>
+		resolveTechnicalSummary(ctx, ai, opts, {
+			branch,
+			classification,
+			context,
+			ast: astAnalyses,
+			impact: astImpact,
+			domains: activeIds.map((id) => findWatchdog(config, id)?.name ?? id),
+		}),
+	);
 
 	const manifestAst: ManifestAst | undefined = astAnalyses
 		? {
@@ -741,15 +843,18 @@ export async function prepare(
 			}
 		: undefined;
 
-	const aiPlans = await buildAiPlans(
-		activeIds,
-		classification,
-		config,
-		context,
-		astAnalyses,
-		astImpact,
-		ai,
-		opts,
+	const aiBriefs = ai && !opts.noAi ? new AiBriefEnricher(ai).enabled : false;
+	const aiPlans = await runOptionalStage(onProgress, aiBriefs, "ai-plans", () =>
+		buildAiPlans(
+			activeIds,
+			classification,
+			config,
+			context,
+			astAnalyses,
+			astImpact,
+			ai,
+			opts,
+		),
 	);
 	if (aiPlans.size > 0) {
 		ctx.storage.writeArtifact(ctx.review.id, {
@@ -779,33 +884,37 @@ export async function prepare(
 				}
 			: undefined;
 
-	writeBriefs(
-		activeIds,
-		classification,
-		ctx,
-		branch,
-		context,
-		jev.candidates,
-		config,
-		astAnalyses,
-		astImpact,
-		aiPlans,
+	await runStage(onProgress, "briefs", () =>
+		writeBriefs(
+			activeIds,
+			classification,
+			ctx,
+			branch,
+			context,
+			jev.candidates,
+			config,
+			astAnalyses,
+			astImpact,
+			aiPlans,
+		),
 	);
-	writeManifest(
-		ctx,
-		config,
-		opts,
-		classification,
-		activeIds,
-		activeIds,
-		jev,
-		manifestAst,
-		manifestAi,
+	await runStage(onProgress, "manifest", () =>
+		writeManifest(
+			ctx,
+			config,
+			opts,
+			classification,
+			activeIds,
+			activeIds,
+			jev,
+			manifestAst,
+			manifestAi,
+		),
 	);
-
 	messages.push(
 		...discoveryMessages(activeIds, classification, ctx.work.briefsDir),
 		...budgetMessage(classification, config),
+		...changedScopeMessage(classification),
 		...jevSummary(jev),
 	);
 	if (astAnalyses) {
@@ -841,7 +950,12 @@ export async function prepare(
 		"Quando os findings estiverem gravados: bun run houndsman --finalize",
 	);
 
-	return { messages };
+	return {
+		messages,
+		activeIds,
+		briefsDir: ctx.work.briefsDir,
+		reviewId: ctx.review.id,
+	};
 }
 /** Persiste o contexto da PR (bruto + resumo) como artefatos, quando existirem. */
 function persistContext(ctx: ReviewContext): void {

package/src/core/project-config.ts

@@ -13,20 +13,22 @@ import type {
 	HoundsmanAiFeatures,
 	HoundsmanAst,
 	HoundsmanConfig,
+	HoundsmanHunt,
 	HoundsmanStorage,
 	HoundsmanWorktrees,
 } from "./config";
 import {
 	DEFAULT_AI_CONCURRENCY,
 	DEFAULT_AI_MAX_CALLS_PER_REVIEW,
-	DEFAULT_AI_MAX_OUTPUT_TOKENS,
-	DEFAULT_AI_MAX_STEPS,
 	DEFAULT_AI_MODEL,
 	DEFAULT_AI_PROVIDER,
 	DEFAULT_AI_TIMEOUT_MS,
 	DEFAULT_ALWAYS_INCLUDE_DOCS,
 	DEFAULT_AST_MAX_FILE_BYTES,
 	DEFAULT_AST_MAX_IMPACT_FILES,
+	DEFAULT_HUNT_CONCURRENCY,
+	DEFAULT_HUNT_RETRIES,
+	DEFAULT_HUNT_TIMEOUT_MS,
 	DEFAULT_JEV_CONCURRENCY,
 	DEFAULT_MAX_FILES_PER_BRIEF,
 	DEFAULT_WORKTREES_LOCATION,
@@ -126,19 +128,6 @@ export class ProjectConfig<TId extends string = string> {
 		return positive(this.ai.concurrency, DEFAULT_AI_CONCURRENCY);
 	}
 
-	get aiMaxSteps(): number {
-		return positive(this.ai.maxSteps, DEFAULT_AI_MAX_STEPS);
-	}
-
-	get aiMaxOutputTokens(): number {
-		return positive(this.ai.maxOutputTokens, DEFAULT_AI_MAX_OUTPUT_TOKENS);
-	}
-
-	get aiTemperature(): number {
-		const value = this.ai.temperature;
-		return typeof value === "number" && Number.isFinite(value) ? value : 0;
-	}
-
 	/** Opções do AI SDK por provider (undefined quando ausentes/vazias). */
 	get aiProviderOptions(): AiProviderOptions | undefined {
 		const value = this.ai.providerOptions;
@@ -178,17 +167,38 @@ export class ProjectConfig<TId extends string = string> {
 		return override && override.length > 0 ? override : this.aiModel;
 	}
 
-	/** Passos efetivos de um watchdog (override por watchdog ou global). */
-	aiMaxStepsFor(watchdogId: string): number {
-		return positive(this.ai.watchdogs?.[watchdogId]?.maxSteps, this.aiMaxSteps);
+	/** Config do harness local (objeto vazio quando ausente). */
+	get hunt(): HoundsmanHunt {
+		return this.raw.hunt ?? {};
+	}
+
+	/** Harness local habilitado (default: ligado; sem binário é fail-closed no comando). */
+	get huntEnabled(): boolean {
+		return this.hunt.enabled !== false;
+	}
+
+	/** Processos maki simultâneos. */
+	get huntConcurrency(): number {
+		return positive(this.hunt.concurrency, DEFAULT_HUNT_CONCURRENCY);
+	}
+
+	/** Timeout por watchdog (ms). */
+	get huntTimeoutMs(): number {
+		return positive(this.hunt.timeoutMs, DEFAULT_HUNT_TIMEOUT_MS);
+	}
+
+	/** Retentativas extras (0 desliga; valores negativos caem no default). */
+	get huntRetries(): number {
+		const value = this.hunt.retries;
+		return value !== undefined && Number.isInteger(value) && value >= 0
+			? value
+			: DEFAULT_HUNT_RETRIES;
 	}
 
-	/** Tokens de saída efetivos de um watchdog. */
-	aiMaxOutputTokensFor(watchdogId: string): number {
-		return positive(
-			this.ai.watchdogs?.[watchdogId]?.maxOutputTokens,
-			this.aiMaxOutputTokens,
-		);
+	/** Modelo base do harness local (sem prefixo de provider). */
+	get huntModel(): string {
+		const value = this.hunt.model?.trim();
+		return value && value.length > 0 ? value : this.aiModel;
 	}
 }
 

package/src/core/registry-check.ts

@@ -282,12 +282,7 @@ function checkAiConfig(
 	if (ai.enabled !== false && ai.model !== undefined && !ai.model.trim()) {
 		warnings.push("ai.model vazio — usando o default.");
 	}
-	for (const key of [
-		"concurrency",
-		"maxSteps",
-		"maxOutputTokens",
-		"timeoutMs",
-	] as const) {
+	for (const key of ["concurrency", "timeoutMs"] as const) {
 		const value = ai[key];
 		if (value !== undefined && value <= 0) {
 			warnings.push(`ai.${key} = ${value} — não-positivo; usando o default.`);
@@ -303,15 +298,10 @@ function checkAiConfig(
 			`ai.maxTokensPerReview = ${ai.maxTokensPerReview} — negativo; sem teto.`,
 		);
 	}
-	for (const [id, override] of Object.entries(ai.watchdogs ?? {})) {
+	for (const id of Object.keys(ai.watchdogs ?? {})) {
 		if (!config.watchdogIds.includes(id)) {
 			warnings.push(`ai.watchdogs['${id}'] não corresponde a nenhum watchdog.`);
 		}
-		if (override.maxSteps !== undefined && override.maxSteps <= 0) {
-			warnings.push(
-				`ai.watchdogs['${id}'].maxSteps não-positivo — usando o default.`,
-			);
-		}
 	}
 
 	const provider = ai.provider ?? "deepseek";

package/src/core/rule-text.ts

@@ -1,14 +1,10 @@
 /**
- * Texto de regra (biblioteca) — fonte única de polaridade e prefixos reservados.
+ * Texto de regra (biblioteca) — fonte única dos prefixos de polaridade.
  *
- * `RuleAnalyzer`, `registry-check` e o harness usam as mesmas listas: evita
- * divergência entre “Promover/Evitar” no analyzer e as validações anti-drift.
- * Também define o vocabulário de findings emergentes (lógica/domínio).
+ * `registry-check` usa a mesma lista para validar que a regra declara
+ * “Promover/Evitar” explicitamente.
  */
 
-/** Intenção de uma regra. */
-export type RuleIntent = "promote" | "avoid";
-
 /** Palavras que abrem uma regra de “deve acontecer”. */
 export const PROMOTE_PREFIXES = [
 	"promover",
@@ -29,12 +25,6 @@ export const AVOID_PREFIXES = [
 	"jamais",
 ] as const;
 
-/** Conjunto normalizado (usado para remover polaridade das keywords). */
-export const POLARITY_WORDS: ReadonlySet<string> = new Set([
-	...PROMOTE_PREFIXES,
-	...AVOID_PREFIXES,
-]);
-
 /** Escapa um literal para uso em regex. */
 function escapeWord(word: string): string {
 	return word.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -48,50 +38,8 @@ function patternFor(words: readonly string[]): RegExp {
 const PROMOTE_PATTERN = patternFor(PROMOTE_PREFIXES);
 const AVOID_PATTERN = patternFor(AVOID_PREFIXES);
 
-/** Polaridade explícita; sem prefixo conhecido, assume `avoid`. */
-export function polarityOf(text: string): RuleIntent {
-	const normalized = text.trim().toLowerCase();
-	if (PROMOTE_PATTERN.test(normalized)) return "promote";
-	if (AVOID_PATTERN.test(normalized)) return "avoid";
-	return "avoid";
-}
-
 /** `true` quando a regra declara polaridade explícita. */
 export function hasExplicitPolarity(text: string): boolean {
 	const normalized = text.trim().toLowerCase();
 	return PROMOTE_PATTERN.test(normalized) || AVOID_PATTERN.test(normalized);
 }
-
-/** Prefixos reservados para findings emergentes (fora das regras explícitas). */
-export const EMERGENT_PREFIXES = {
-	logic: "Lógica:",
-	domain: "Domínio:",
-} as const;
-
-/** Espécie de finding emergente. */
-export type EmergentKind = keyof typeof EMERGENT_PREFIXES;
-
-/** Espécie de um finding emergente (`null` quando não é emergente). */
-export function emergentKind(rule: string): EmergentKind | null {
-	const normalized = rule.trim();
-	if (normalized.startsWith(EMERGENT_PREFIXES.logic)) return "logic";
-	if (normalized.startsWith(EMERGENT_PREFIXES.domain)) return "domain";
-	return null;
-}
-
-/** `true` quando a regra usa um prefixo emergente. */
-export function isEmergentRule(rule: string): boolean {
-	return emergentKind(rule) !== null;
-}
-
-/** Texto que sobra após o prefixo (vazio é inválido). */
-export function emergentText(rule: string): string {
-	const kind = emergentKind(rule);
-	if (!kind) return "";
-	return rule.trim().slice(EMERGENT_PREFIXES[kind].length).trim();
-}
-
-/** Monta o texto de um finding emergente. */
-export function emergentRule(kind: EmergentKind, text: string): string {
-	return `${EMERGENT_PREFIXES[kind]} ${text.trim()}`;
-}

package/src/core/services/git-repository.ts

@@ -138,6 +138,14 @@ export class GitRepository {
 		return parseNumstat(this.run(["diff", "--numstat", "-z", range]));
 	}
 
+	/**
+	 * Patch com contexto zero (`git diff -U0 range`), sem truncar por arquivo.
+	 * É compacto e exato nas linhas — base do escopo do diff e do delta AST.
+	 */
+	patchZeroContext(range: string): Map<string, string> {
+		return parseDiffIndex(this.run(["diff", "-U0", range]));
+	}
+
 	/** Patch por arquivo de um intervalo, opcionalmente restrito a `paths`. */
 	diffPatch(
 		range: string,

package/src/core/storage/types.ts

@@ -110,7 +110,7 @@ export type ArtifactKind =
 	| "ai"
 	| "ai-usage"
 	| "ai-brief"
-	| "harness-transcript"
+	| "hunt"
 	| "other";
 
 /** Artefato persistido de uma review. */

package/src/core/types.ts

@@ -8,6 +8,7 @@
 
 import type { BriefPlan } from "./ai/schemas";
 import type { AstFileBrief } from "./ast/types";
+import type { ChangedScope } from "./changed-scope";
 import type { JevRuleSpec } from "./jev/jev-types";
 
 /** Severidade de um achado. `blocking` bloqueia o merge. */
@@ -29,19 +30,6 @@ export const SEVERITY_EMOJI: Record<Severity, string> = {
 	nit: "🔎",
 };
 
-/**
- * Sinais opcionais de uma regra: ajudam o `RuleAnalyzer` a transformar texto
- * em checagens concretas (símbolos, imports, decorators, paths e tools).
- */
-export type RuleHints = {
-	symbols?: string[];
-	imports?: string[];
-	decorators?: string[];
-	paths?: string[];
-	/** Nomes de tools sugeridos (ex.: `symbol_context`). */
-	checks?: string[];
-};
-
 /**
  * Regra do watchdog: severidade + texto. O texto declara a polaridade de forma
  * explícita — `Promover:` (algo que DEVE acontecer) ou `Evitar:`/`Não`/`Nunca`
@@ -54,7 +42,6 @@ export type Rule = {
 	severity: Severity;
 	text: string;
 	jev?: JevRuleSpec;
-	hints?: RuleHints;
 };
 
 /**
@@ -144,6 +131,8 @@ export type WatchdogRenderArgs = {
 	ast?: readonly AstFileBrief[];
 	/** Plano de revisão sugerido por IA (nunca substitui as regras). */
 	aiPlan?: BriefPlan;
+	/** Escopo do diff por arquivo (símbolos alterados; hunks como fallback). */
+	changedScope?: ChangedScope;
 };
 
 /** Definição completa de um watchdog — 1 por arquivo em `project/watchdogs/`. */