@payconductor/houndsman 0.10.0 → 0.12.0

package/README.md

@@ -28,7 +28,7 @@ diferente das PRs. O motor só coordena a caçada — as regras são problema se
 - **git** — o diff usa `git diff <base>...<head>`.
 - **gh** (Opcional) — Obtém contexto da PR e dispara comentários para o GitHub
 - **`HOUNDSMAN_TYPE_SAFE_API_KEY`** (opcional) — pré-análise Jev.
-- **`HOUNDSMAN_DEEP_SEEK_API_KEY`** (opcional) — IA própria do `hunt` nativo e das features de IA.
+- **`HOUNDSMAN_DEEP_SEEK_API_KEY`** (opcional) — features de IA (briefs, contexto, classificação, resumo técnico).
 - **`HOUNDSMAN_OPENAI_API_KEY`** / **`HOUNDSMAN_ANTHROPIC_API_KEY`** (opcional) — apenas se
   `ai.provider` for `openai`/`anthropic`.
 
@@ -74,7 +74,7 @@ bun run houndsman doctor
 
 ### 6. Rode a primeira revisão
 
-No seu harness (Claude Code / agents), invoque o skill:
+No seu agente (Claude Code / agents), invoque o skill:
 
 ```
 /houndsman hunt
@@ -84,28 +84,13 @@ O skill orquestra tudo e persiste o relatório no storage global (SQLite em
 `<HOUNDSMAN_HOME>/houndsman.db`); a UI lê os artefatos direto do storage. Não precisa rodar
 nenhum script à mão.
 
-### 7. Revisão nativa (opcional) — `houndsman hunt`
-
-Além do skill, o houndsman tem um **harness próprio**: o `hunt` roda o agente de revisão
-dentro do CLI, com tools read-only, investigação por evidência e a mesma saída `review.md`.
-
-```bash
-bun run houndsman hunt --dry-run     # inspeciona watchdogs/arquivos, sem IA
-HOUNDSMAN_DEEP_SEEK_API_KEY=... bun run houndsman hunt
-bun run houndsman hunt --resume      # preserva findings válidos do staging
-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)
+### 7. 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
@@ -153,7 +138,7 @@ Você decide o que fazer com cada finding pela **UI local**, informando se quer
 bun run houndsman server --open     # UI: triar, comentar, marcar feito, ler artefatos
 ```
 
-> A partir da 2ª revisão o `hunt` é **incremental**: revisa apenas os arquivos que mudaram desde
+> A partir da 2ª revisão o prepare é **incremental**: revisa apenas os arquivos que mudaram desde
 > a última revisão. `--full` força o review completo.
 
 ---

package/package.json

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

@@ -5,7 +5,6 @@ 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; --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)
   worktree <ação>     Lista/cria/remove worktrees de revisão (list · add · remove · prune · path)
@@ -30,12 +29,6 @@ Flags:
   --no-ai             Desativa as features de IA do fluxo normal
   --fail-on-blocking  Exit 1 se houver bloqueantes (com --finalize)
 
-Flags do hunt:
-  --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>
-
 Flags de findings:
   --decision <d>      pending | execute | ignore
   --exec <e>          pending | in_progress | done | stale

package/src/cli/index.ts

@@ -31,13 +31,13 @@ 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";
 import { DoctorCommand } from "./commands/doctor-command";
 import { FindingsCommand } from "./commands/findings-command";
 import { HelpCommand } from "./commands/help-command";
-import { HuntCommand } from "./commands/hunt-command";
 import { CommandRegistry } from "./commands/registry";
 import { ReviewCommand } from "./commands/review-command";
 import { ServerCommand } from "./commands/server-command";
@@ -57,7 +57,6 @@ function buildRegistry(): CommandRegistry {
 	return new CommandRegistry()
 		.register(new ReviewCommand(), { fallback: true })
 		.register(new HelpCommand())
-		.register(new HuntCommand())
 		.register(new ContextCommand())
 		.register(new FindingsCommand())
 		.register(new StatusCommand())
@@ -90,7 +89,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/ai-client.ts

@@ -2,8 +2,7 @@
  * Fachada de IA (`core/ai`) — fail-open, budget e uso.
  *
  * As features do core usam `generateObject`/`generateText` e tratam `ok:false`
- * como "sem IA": a revisão determinística segue idêntica. O harness nativo usa
- * `requireProvider` e falha com mensagem clara quando a IA não está configurada.
+ * como "sem IA": a revisão determinística segue idêntica.
  */
 
 import type { ZodType } from "zod";
@@ -11,7 +10,7 @@ import type { AiProviderOptions } from "../config";
 import type { ProjectConfig } from "../project-config";
 import { AiConfigurationError, errorMessage } from "./errors";
 import { ModelFactory } from "./model-factory";
-import type { AiResult, AiTool, AiUsage, ModelProvider, ModelRequest } from "./types";
+import type { AiResult, AiUsage, ModelProvider, ModelRequest } from "./types";
 import { AiUsageBudget } from "./usage-budget";
 import { AiUsageRecorder } from "./usage-recorder";
 
@@ -30,8 +29,6 @@ export type ObjectRequest<T> = {
 	instructions?: string;
 	prompt: string;
 	outputSchema: ZodType<T>;
-	tools?: Record<string, AiTool>;
-	maxSteps?: number;
 	maxOutputTokens?: number;
 	temperature?: number;
 	/** Opções do AI SDK por provider (mescladas com a config do projeto). */
@@ -93,7 +90,7 @@ export class AiClient {
 		return this.factory.isConfigured;
 	}
 
-	/** Provider obrigatório — usado pelo harness (falha clara sem IA). */
+	/** Provider obrigatório (lança quando a IA não está configurada). */
 	async requireProvider(model?: string): Promise<ModelProvider> {
 		if (this.override === null) {
 			throw new AiConfigurationError(
@@ -146,7 +143,6 @@ export class AiClient {
 		);
 		const result = await this.generateText("doctor-ping", {
 			prompt: "Responda apenas OK.",
-			maxSteps: 1,
 			maxOutputTokens: 4,
 			temperature: 0,
 			signal: AbortSignal.timeout(timeoutMs),

package/src/core/ai/ai-sdk-model-provider.ts

@@ -1,18 +1,16 @@
 /**
- * Adapter do AI SDK (`generateText` + `Output.object` + tools).
+ * Adapter do AI SDK (`generateText` + `Output.object`).
  *
  * O resto do motor depende só de `ModelProvider`; trocar de SDK é trocar este
- * arquivo. O loop de tools é do SDK (`stepCountIs`), com timeout/cancelamento
- * via `AbortSignal`.
+ * arquivo. Timeout/cancelamento vêm do `AbortSignal`.
  */
 
-import type { LanguageModel, ToolSet } from "ai";
-import { generateText, Output, stepCountIs, tool } from "ai";
+import type { LanguageModel } from "ai";
+import { generateText, Output } from "ai";
 import type { AiProviderKind } from "../config";
 import { AiProviderError } from "./errors";
 import { temperatureApplies } from "./provider-capabilities";
 import {
-	type AiTool,
 	type AiUsage,
 	emptyUsage,
 	type ModelProvider,
@@ -20,19 +18,6 @@ import {
 	type ModelResponse,
 } from "./types";
 
-/** Converte as tools do motor para o formato do AI SDK. */
-function toToolSet(tools: Record<string, AiTool>): ToolSet {
-	const entries = Object.entries(tools).map(([name, item]) => [
-		name,
-		tool({
-			description: item.description,
-			inputSchema: item.inputSchema,
-			execute: async (input: unknown) => item.execute(input),
-		}),
-	]);
-	return Object.fromEntries(entries) as ToolSet;
-}
-
 /** Mapeia o uso do SDK de forma defensiva (campos opcionais por provider). */
 export function mapUsage(raw: unknown): AiUsage {
 	const usage = (raw ?? {}) as Record<string, unknown>;
@@ -61,9 +46,6 @@ export function buildGenerateTextArgs<T>(
 	provider: AiProviderKind,
 	modelId: string,
 ) {
-	const tools = request.tools ? toToolSet(request.tools) : undefined;
-	const hasTools = tools !== undefined && Object.keys(tools).length > 0;
-	const maxSteps = request.maxSteps ?? 1;
 	const providerOptions = request.providerOptions
 		? (request.providerOptions as GenerateTextArgs["providerOptions"])
 		: undefined;
@@ -76,7 +58,6 @@ export function buildGenerateTextArgs<T>(
 		model,
 		system: request.instructions,
 		prompt: request.prompt,
-		...(hasTools ? { tools, stopWhen: stepCountIs(maxSteps) } : {}),
 		...(request.outputSchema
 			? { output: Output.object({ schema: request.outputSchema }) }
 			: {}),
@@ -108,7 +89,6 @@ export class AiSdkModelProvider implements ModelProvider {
 			return {
 				output,
 				usage: mapUsage(result.usage),
-				steps: result.steps?.length ?? 1,
 				finishReason: result.finishReason ?? "unknown",
 			};
 		} catch (error) {

package/src/core/ai/features/brief-enricher.ts

@@ -27,7 +27,6 @@ export class AiBriefEnricher {
 				instructions: briefInstructions(),
 				prompt: briefPrompt(input),
 				outputSchema: BriefPlanSchema,
-				maxSteps: 1,
 				maxOutputTokens: 700,
 			},
 			this.client.projectConfig.aiModelFor(input.watchdogId),

package/src/core/ai/features/classifier.ts

@@ -37,7 +37,6 @@ export class AiClassifier {
 				instructions: classificationInstructions(),
 				prompt: classificationPrompt({ files, watchdogs }),
 				outputSchema: ClassificationSchema,
-				maxSteps: 1,
 			},
 		);
 		if (!result.ok) return assignments;

package/src/core/ai/features/context-summarizer.ts

@@ -23,7 +23,6 @@ export class AiContextSummarizer {
 			instructions: contextInstructions(),
 			prompt: contextPrompt(raw),
 			outputSchema: ContextSummarySchema,
-			maxSteps: 1,
 		});
 		if (!result.ok) return null;
 		return parseContextSummary({ ...result.output, available: true });

package/src/core/ai/features/pre-analyzer.ts

@@ -32,7 +32,6 @@ export class AiPreAnalyzer {
 				instructions: preAnalysisInstructions(),
 				prompt: preAnalysisPrompt(input),
 				outputSchema: CandidateSchema,
-				maxSteps: 1,
 			},
 			this.client.projectConfig.aiModelFor(input.watchdogId),
 		);

package/src/core/ai/features/technical-summarizer.ts

@@ -30,7 +30,6 @@ export class AiTechnicalSummarizer {
 				instructions: technicalInstructions(),
 				prompt: technicalPrompt(buildTechnicalPromptPayload(input)),
 				outputSchema: TechnicalSummarySchema,
-				maxSteps: 1,
 			},
 		);
 		if (!result.ok) return null;

package/src/core/ai/features/verifier.ts

@@ -32,7 +32,6 @@ export class AiVerifier {
 				instructions: verifyInstructions(),
 				prompt: verifyPrompt(input),
 				outputSchema: VerifySchema,
-				maxSteps: 1,
 			},
 		);
 		if (!result.ok) return confidence;

package/src/core/ai/index.ts

@@ -28,7 +28,6 @@ export {
 	type AiCandidate,
 	type AiClassification,
 	type AiVerdict,
-	type AiWatchdogReport,
 	type BriefPlan,
 	BriefPlanSchema,
 	CandidateSchema,
@@ -39,11 +38,9 @@ export {
 	type TechnicalSummaryPlan,
 	TechnicalSummarySchema,
 	VerifySchema,
-	WatchdogReportSchema,
 } from "./schemas";
 export {
 	type AiResult,
-	type AiTool,
 	type AiUsage,
 	addUsage,
 	emptyUsage,

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/pre-analysis.ts

@@ -20,7 +20,8 @@ export function preAnalysisInstructions(): string {
 	return buildSystem(
 		"Você faz uma pré-análise de possíveis violações de regras em um diff.",
 		[
-			"Produza candidatos apenas quando houver indício concreto.",
+			"Produza candidatos apenas quando houver indício concreto no trecho alterado.",
+			"O trecho fornecido é o diff (linhas alteradas); código não alterado é apenas contexto.",
 			"Use o texto de uma das regras fornecidas.",
 			"Confiança calibrada entre 0 e 1; prefira valores baixos na dúvida.",
 			"Não invente arquivos.",
@@ -36,7 +37,7 @@ export function preAnalysisPrompt(input: PreAnalysisPromptInput): string {
 		"## Regras",
 		...input.rules.map((rule) => `- [${rule.severity}] ${rule.text}`),
 		"",
-		"## Arquivos e trechos",
+		"## Arquivos e trechos alterados (diff)",
 		...input.files.flatMap((item) => [
 			`### ${item.file}`,
 			"```",

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/ai/schemas.ts

@@ -1,8 +1,7 @@
 /**
  * Schemas Zod da camada de IA.
  *
- * Espelham os contratos existentes (`ContextSummary`, `WatchdogReport`) e os
- * planos das features. Todo schema é fechado por validação: saída inválida do
+ * Espelham os contratos existentes (`ContextSummary`) e os planos das features. Todo schema é fechado por validação: saída inválida do
  * modelo vira falha fail-open, nunca dado corrompido.
  */
 
@@ -89,27 +88,6 @@ export const CandidateSchema = z.object({
 });
 export type AiCandidate = z.infer<typeof CandidateSchema>["candidates"][number];
 
-/** Relatório de um watchdog (espelha `OUTPUT-FORMAT.md`). */
-export const WatchdogReportSchema = z.object({
-	watchdogId: z.string(),
-	reviewedFiles: z.array(z.string()).default([]),
-	skipped: z.array(z.string()).default([]),
-	findings: z
-		.array(
-			z.object({
-				rule: z.string(),
-				severity: SeveritySchema,
-				file: z.string(),
-				line: z.number().int().positive().optional(),
-				message: z.string(),
-				action: z.string(),
-				evidence: z.string().optional(),
-			}),
-		)
-		.default([]),
-});
-export type AiWatchdogReport = z.infer<typeof WatchdogReportSchema>;
-
 /** Veredito de verificação (confirma/refuta um finding ambíguo). */
 export const VerifySchema = z.object({
 	verdicts: z

package/src/core/ai/types.ts

@@ -1,11 +1,10 @@
 /**
  * Contratos genéricos da camada de IA (biblioteca).
  *
- * `core/ai` não conhece o harness: expõe modelo, uso, tools e resultado. O
- * harness nativo (`src/harness/`) consome estes contratos.
+ * Expõe modelo, uso e resultado; as features do core são as únicas consumidoras.
  */
 
-import type { ZodType, ZodTypeAny } from "zod";
+import type { ZodType } from "zod";
 import type { AiProviderKind, AiProviderOptions } from "../config";
 
 /** Uso de tokens de uma chamada (ou acumulado de uma review). */
@@ -31,25 +30,14 @@ export function addUsage(a: AiUsage, b: AiUsage): AiUsage {
 	};
 }
 
-/** Tool exposta ao modelo (execução já vinculada a um contexto). */
-export type AiTool = {
-	name: string;
-	description: string;
-	inputSchema: ZodTypeAny;
-	execute(input: unknown): Promise<string>;
-};
-
 /** Pedido de geração de modelo (texto ou objeto estruturado). */
 export type ModelRequest<T> = {
 	/** Instruções de sistema. */
 	instructions?: string;
 	/** Prompt do usuário. */
 	prompt: string;
-	/** Tools disponíveis para o loop do modelo. */
-	tools?: Record<string, AiTool>;
 	/** Schema de saída (quando ausente, a saída é texto). */
 	outputSchema?: ZodType<T>;
-	maxSteps?: number;
 	maxOutputTokens?: number;
 	temperature?: number;
 	/** Opções do AI SDK por provider (repassadas ao SDK sem interpretação). */
@@ -61,7 +49,6 @@ export type ModelRequest<T> = {
 export type ModelResponse<T> = {
 	output: T;
 	usage: AiUsage;
-	steps: number;
 	finishReason: string;
 };
 

package/src/core/ai/usage-budget.ts

@@ -2,7 +2,7 @@
  * Orçamento de IA por review (chamadas e tokens).
  *
  * O budget é consultado antes de cada chamada e atualizado com o uso real. Ao
- * estourar, o chamador decide parar (features do core) ou falhar (harness).
+ * estourar, o chamador decide parar a operação (features do core).
  */
 
 import { AiBudgetError } from "./errors";

package/src/core/ast/diff.ts

@@ -14,7 +14,7 @@ import type {
 	AstSymbol,
 } from "./types";
 
-/** Um hunk do patch, com as linhas novas adicionadas. */
+/** Um hunk do patch, com as linhas novas adicionadas e as âncoras de remoção. */
 export type AstHunk = {
 	oldStart: number;
 	oldLines: number;
@@ -22,6 +22,11 @@ export type AstHunk = {
 	newLines: number;
 	/** Linhas novas (1-based) introduzidas pelo hunk. */
 	addedLines: number[];
+	/**
+	 * Posições (1-based, no lado novo) onde linhas foram removidas. Uma remoção
+	 * pura não tem linha nova, mas marca o ponto do arquivo que ela alterou.
+	 */
+	deletedAt: number[];
 };
 
 /** Regex do cabeçalho de hunk (`@@ -a,b +c,d @@`). */
@@ -52,6 +57,7 @@ export function parseHunks(patch: string): AstHunk[] {
 				newStart: Number.parseInt(match[3], 10),
 				newLines: countOf(match[4]),
 				addedLines: [],
+				deletedAt: [],
 			};
 			newLine = current.newStart;
 			hunks.push(current);
@@ -68,7 +74,11 @@ export function parseHunks(patch: string): AstHunk[] {
 			newLine++;
 			continue;
 		}
-		if (line.startsWith("-")) continue;
+		if (line.startsWith("-")) {
+			// Remoção pura não consome linha nova: ancora no ponto atual do arquivo.
+			current.deletedAt.push(Math.max(1, newLine));
+			continue;
+		}
 		if (line.startsWith("\\")) continue;
 		if (line.startsWith(" ")) newLine++;
 	}
@@ -85,6 +95,31 @@ export function changedNewLines(patch: string): Set<number> {
 	return lines;
 }
 
+/** Âncoras de alteração do patch: adições e posições de remoção no lado novo. */
+export type ChangedAnchors = {
+	/** Linhas novas (1-based) adicionadas. */
+	added: Set<number>;
+	/** Posições (1-based, lado novo) onde houve remoção. */
+	deletedAt: Set<number>;
+};
+
+/** Extrai as âncoras de alteração de um patch (falha aberta: patch vazio → vazio). */
+export function changedAnchors(patch: string): ChangedAnchors {
+	const added = new Set<number>();
+	const deletedAt = new Set<number>();
+	for (const hunk of parseHunks(patch)) {
+		for (const line of hunk.addedLines) added.add(line);
+		for (const line of hunk.deletedAt) deletedAt.add(line);
+	}
+	return { added, deletedAt };
+}
+
+/** União das âncoras (adições + remoções) — o que a mudança tocou no arquivo. */
+export function changedAnchorLines(patch: string): Set<number> {
+	const { added, deletedAt } = changedAnchors(patch);
+	return new Set([...added, ...deletedAt]);
+}
+
 /** Chave estável de um símbolo (espécie + nome). */
 function symbolKey(symbol: AstSymbol): string {
 	return `${symbol.kind}:${symbol.name}`;

package/src/core/ast/service.ts

@@ -162,7 +162,7 @@ export class AstService {
 		return buildImpact(analyses, importersByFile);
 	}
 
-	/** Fatos estruturais do arquivo atual (usado pelas tools do harness). */
+	/** Fatos estruturais do arquivo atual (usado pelo motor e pelo server). */
 	async factsOf(filePath: string): Promise<AstFacts | null> {
 		if (!this.enabled) return null;
 		const content = this.readWorkingFile(filePath);

package/src/core/brief.ts

@@ -6,6 +6,7 @@
  */
 
 import type { AstDelta } from "./ast/types";
+import { formatRanges, formatSymbols } from "./changed-scope";
 import {
 	type Rule,
 	SEVERITY_EMOJI,
@@ -21,10 +22,10 @@ import {
  */
 export const PROCEDURE: readonly string[] = [
 	"1. **FILTER** — descarte o que não for do seu domínio (ver *Prioridade de leitura* e *Não carregar*).",
-	"2. **READ HEAD** — leia os arquivos seletivamente (primeiras ~30 linhas). NUNCA o diff completo.",
-	"3. **GREP** — use as regras críticas/anti-padrões como heurística para localizar violações.",
-	"4. **DEEP-READ** — aprofunde apenas os arquivos com suspeita de violação.",
-	'5. **CONCLUDE** — grave o JSON no caminho de output, com `reviewedFiles` preenchido. Sem achados → `"findings": []` (arquivo obrigatório). Não escreva markdown livre.',
+	"2. **READ SCOPE** — carregue apenas as faixas alteradas em *Escopo do diff*; o restante do arquivo é só contexto.",
+	"3. **GREP** — use as regras críticas/anti-padrões como heurística para localizar violações nas faixas alteradas.",
+	"4. **DEEP-READ** — aprofunde apenas as faixas com suspeita de violação dentro do escopo.",
+	'5. **CONCLUDE** — grave o JSON no caminho de output, com `reviewedFiles` preenchido e `line` dentro das faixas alteradas. Sem achados → `"findings": []` (arquivo obrigatório). Não escreva markdown livre.',
 ];
 
 /** Limites do contexto injetado em cada brief (o resumo final é maior). */
@@ -83,6 +84,52 @@ export function renderBriefCandidates(
 	return lines;
 }
 
+/**
+ * Escopo do diff — as únicas faixas que podem virar finding.
+ *
+ * Sem ele, o watchdog tende a revisar o arquivo inteiro e reportar problemas
+ * pré-existentes (fora do que a PR alterou).
+ */
+function changedScopeSection(args: WatchdogRenderArgs): string[] {
+	const scope = args.changedScope;
+	if (!scope) return [];
+	const files = args.files.filter((file) => scope[file]);
+	if (files.length === 0) return [];
+	const lines: string[] = [
+		"## Escopo do diff (símbolos alterados)",
+		"",
+		"> **Regra de escopo:** um finding só é válido quando a `line` está nas faixas",
+		"> abaixo. Código fora delas é contexto — use para entender o impacto, nunca",
+		"> como achado. Se a mudança quebra código não alterado, ancore o finding na",
+		"> linha alterada que causou o problema.",
+		"",
+	];
+	let rendered = 0;
+	for (const file of files) {
+		const entry = scope[file];
+		if (!entry) continue;
+		if (entry.ranges.length === 0) {
+			lines.push(
+				`- \`${file}\` — sem linhas alteradas (renomeado/binário): não reportar`,
+			);
+			rendered++;
+			if (rendered >= 40) break;
+			continue;
+		}
+		const fallback = entry.source === "hunks" ? " _(faixas do diff)_" : "";
+		lines.push(`- \`${file}\` — linhas ${formatRanges(entry.ranges)}${fallback}`);
+		const symbols = formatSymbols(entry.symbols);
+		if (symbols) lines.push(`  símbolos: ${symbols}`);
+		rendered++;
+		if (rendered >= 40) break;
+	}
+	if (files.length > rendered) {
+		lines.push(`- … +${files.length - rendered} arquivo(s)`);
+	}
+	lines.push("");
+	return lines;
+}
+
 /** Linha de lista em code-span: `- \`valor\``. */
 function codeItem(value: string): string {
 	return `- \`${value}\``;
@@ -293,7 +340,9 @@ export function defaultRenderBrief(
 	];
 
 	if (def.description) lines.push("## Objetivo", "", def.description, "");
-	lines.push("## Escopo", "", def.scope, "");
+	lines.push("## Escopo do domínio", "", def.scope, "");
+
+	lines.push(...changedScopeSection(args));
 
 	if (args.context) lines.push(...renderBriefContext(args.context));