@payconductor/houndsman 0.11.0 → 0.13.0

package/src/cli/help.ts

@@ -5,8 +5,12 @@ 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)
+  hunt [flags]        Harness local (maki): prepare → watchdogs via maki → finalize
+                      (a skill /houndsman hunt continua existindo p/ agentes externos)
+  hunt install        Baixa o maki fixado para <HOUNDSMAN_HOME>/tools/maki
+  hunt doctor         Diagnóstico do harness local (opcional, não falha sem maki)
+  hunt uninstall      Remove o binário gerenciado
   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)
   server              Sobe a UI local de triagem (--port, --host, --open, --editor)
@@ -30,11 +34,13 @@ 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 hunt (harness local):
+  --allow-partial     Finaliza mesmo se algum watchdog maki falhar
+  --no-context        Não coleta o contexto da PR via gh
+  --hunt-model <m>    Modelo do maki (provider/model-id)
+  --hunt-concurrency  Processos maki simultâneos
+  --hunt-timeout      Timeout por watchdog (ms)
+  --no-retry          Não repete saída inválida
 
 Flags de findings:
   --decision <d>      pending | execute | ignore
@@ -69,6 +75,8 @@ Persistência:
 
 Ambiente (o Bun carrega .env automaticamente):
   HOUNDSMAN_TYPE_SAFE_API_KEY   Pré-análise Jev (opcional)
-  HOUNDSMAN_DEEP_SEEK_API_KEY   IA (provider deepseek, opcional)
+  HOUNDSMAN_DEEP_SEEK_API_KEY   IA (provider deepseek, opcional; reusada pelo hunt)
   HOUNDSMAN_OPENAI_API_KEY     IA (provider openai, opcional)
-  HOUNDSMAN_ANTHROPIC_API_KEY  IA (provider anthropic, opcional)`;
+  HOUNDSMAN_ANTHROPIC_API_KEY  IA (provider anthropic, opcional)
+  HOUNDSMAN_MAKI_PATH          Binário do maki (harness local \`hunt\`)
+  HOUNDSMAN_MAKI_VERSION       Versão do maki a instalar (default: fixada no pacote)`;

package/src/cli/index.ts

@@ -15,6 +15,7 @@
  *   --finalize           Passo 3 — consolidar os findings em review.md
  *   context              Passo 0 — coletar o contexto da PR via `gh`
  *   findings <sub>       Triagem/correção dos findings (list/set/done/sync/batch/verify/submit/...)
+ *   hunt [flags]         Harness local (maki): prepare → watchdogs via maki → finalize
  *   status [ping]        Mostra o status da run; `ping` renova o heartbeat da execução
  *   server               Sobe a UI local de triagem (Bun.serve)
  *   setup                Cria a configuração inicial do projeto (config + skills)
@@ -30,7 +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 { formatDuration, logger } from "../core/logging";
 import { syncProjectLayerForRoot } from "../core/services/worktree-manager";
 import { ArgParser } from "./arg-parser";
 import type { CliContext } from "./commands/command";
@@ -90,14 +91,26 @@ export async function main(): Promise<void> {
 	}
 
 	let loaded: Awaited<ReturnType<typeof loadConfig>> | null = null;
+	// `--json` é contrato de máquina: nada de progresso no stdout.
+	const silentProgress = parser.has("--json");
 	const config = async (): Promise<HoundsmanConfig> => {
 		loaded ??= await (async () => {
+			const started = Date.now();
+			if (!silentProgress) logger.step("Carregando a configuração do projeto…");
 			// 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") });
+			const result = await loadConfig({ configPath: parser.value("--config") });
+			if (!silentProgress) {
+				logger.success(
+					`Configuração: ${result.config.projectName} · ` +
+						`${result.config.watchdogIds.length} watchdog(s) ` +
+						`(${formatDuration(Date.now() - started)})`,
+				);
+			}
+			return result;
 		})();
 		return loaded.config;
 	};

package/src/cli/progress.ts

@@ -0,0 +1,45 @@
+/**
+ * Progresso do CLI por etapa do prepare (apresentação).
+ *
+ * O core emite eventos (`PrepareProgressEvent`); aqui eles viram spinner/linha
+ * com a duração de cada fase — o `hunt` começa a dar sinal de vida antes do
+ * primeiro `Discovery:`.
+ */
+
+import { formatDuration, type LoggerLike, PhaseReporter } from "../core/logging";
+import type { PrepareProgress, PrepareStage } from "../core/orchestrator";
+
+/** Texto de cada etapa (início no gerúndio, fim no particípio). */
+export const PREPARE_STAGE_TEXT: Record<PrepareStage, { start: string; done: string }> = {
+	diff: { start: "Lendo o diff da revisão", done: "Diff lido" },
+	ast: { start: "Analisando a AST dos arquivos alterados", done: "AST analisada" },
+	classify: {
+		start: "Classificando os arquivos por watchdog",
+		done: "Classificação concluída",
+	},
+	impact: { start: "Medindo o impacto nos importadores", done: "Impacto calculado" },
+	jev: { start: "Pré-analisando o diff (Jev/IA)", done: "Pré-análise concluída" },
+	context: { start: "Resumindo o contexto da PR", done: "Contexto resumido" },
+	technical: {
+		start: "Consolidando os pontos técnicos",
+		done: "Pontos técnicos prontos",
+	},
+	"ai-plans": { start: "Planejando os briefs com IA", done: "Planos de brief prontos" },
+	briefs: { start: "Gerando os briefs", done: "Briefs gerados" },
+	manifest: { start: "Gravando o manifesto da revisão", done: "Manifesto gravado" },
+};
+
+/** Cria o callback de progresso do prepare ligado ao logger do CLI. */
+export function prepareProgress(logger: LoggerLike): PrepareProgress {
+	const reporter = new PhaseReporter(logger);
+	return (event) => {
+		const text = PREPARE_STAGE_TEXT[event.stage];
+		if (event.type === "start") reporter.begin(event.stage, text.start);
+		else reporter.end(event.stage, text.done, event.durationMs);
+	};
+}
+
+/** Log de um passo concluído com a duração (usado fora do prepare). */
+export function stepDone(logger: LoggerLike, message: string, startedMs: number): void {
+	logger.success(`${message} (${formatDuration(Date.now() - startedMs)})`);
+}

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>;
@@ -46,6 +31,43 @@ function numberOrZero(value: unknown): number {
 	return typeof value === "number" && Number.isFinite(value) ? value : 0;
 }
 
+/**
+ * Silencia o emissor default de avisos do AI SDK.
+ *
+ * O default usa `process.emitWarning` — com stack trace — a cada chamada, o que
+ * polui o stderr do CLI. Os avisos continuam disponíveis no resultado da
+ * chamada (`ModelResponse.warnings`). Um chamador que queira o comportamento
+ * original basta definir `AI_SDK_LOG_WARNINGS` antes de usar o SDK.
+ */
+function installWarningSink(): void {
+	if (globalThis.AI_SDK_LOG_WARNINGS === undefined) {
+		globalThis.AI_SDK_LOG_WARNINGS = () => {};
+	}
+}
+
+installWarningSink();
+
+/** Normaliza um aviso do provider em texto legível (puro). */
+export function formatSdkWarning(raw: unknown): string {
+	const warning = (raw ?? {}) as Record<string, unknown>;
+	const label = [warning.type, warning.feature, warning.setting]
+		.filter((value): value is string => typeof value === "string" && value !== "")
+		.join(": ");
+	const detail =
+		typeof warning.details === "string"
+			? warning.details
+			: typeof warning.message === "string"
+				? warning.message
+				: "";
+	const head = label || "aviso";
+	return detail ? `${head} — ${detail}` : head;
+}
+
+/** Lista de avisos do provider em texto (puro). */
+export function formatSdkWarnings(raw: unknown): string[] {
+	return Array.isArray(raw) ? raw.map(formatSdkWarning) : [];
+}
+
 /** Argumentos aceitos por `generateText` (inclui `providerOptions` do SDK). */
 type GenerateTextArgs = Parameters<typeof generateText>[0];
 
@@ -61,9 +83,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 +95,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 }) }
 			: {}),
@@ -105,11 +123,12 @@ export class AiSdkModelProvider implements ModelProvider {
 			const output = request.outputSchema
 				? (result.output as T)
 				: ((result.text ?? "") as unknown as T);
+			const warnings = formatSdkWarnings(result.warnings);
 			return {
 				output,
 				usage: mapUsage(result.usage),
-				steps: result.steps?.length ?? 1,
 				finishReason: result.finishReason ?? "unknown",
+				...(warnings.length > 0 ? { warnings } : {}),
 			};
 		} catch (error) {
 			if (error instanceof Error && error.name === "AbortError") {

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

@@ -10,7 +10,12 @@ export type {
 	TextRequest,
 } from "./ai-client";
 export { AiClient } from "./ai-client";
-export { AiSdkModelProvider, mapUsage } from "./ai-sdk-model-provider";
+export {
+	AiSdkModelProvider,
+	formatSdkWarning,
+	formatSdkWarnings,
+	mapUsage,
+} from "./ai-sdk-model-provider";
 export {
 	AiBudgetError,
 	AiConfigurationError,
@@ -28,7 +33,6 @@ export {
 	type AiCandidate,
 	type AiClassification,
 	type AiVerdict,
-	type AiWatchdogReport,
 	type BriefPlan,
 	BriefPlanSchema,
 	CandidateSchema,
@@ -39,11 +43,9 @@ export {
 	type TechnicalSummaryPlan,
 	TechnicalSummarySchema,
 	VerifySchema,
-	WatchdogReportSchema,
 } from "./schemas";
 export {
 	type AiResult,
-	type AiTool,
 	type AiUsage,
 	addUsage,
 	emptyUsage,

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/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,8 +49,9 @@ export type ModelRequest<T> = {
 export type ModelResponse<T> = {
 	output: T;
 	usage: AiUsage;
-	steps: number;
 	finishReason: string;
+	/** Avisos do provider já normalizados em texto (ex.: modo de compatibilidade). */
+	warnings?: string[];
 };
 
 /** Provider de modelo (adaptador do AI SDK ou fake nos testes). */

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);