@payconductor/houndsman 0.11.0 → 0.13.0

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

package/src/core/changed-scope.ts

@@ -0,0 +1,207 @@
+/**
+ * Escopo do diff (engine) — o que esta revisão realmente alterou.
+ *
+ * Traduz os hunks do diff (`-U0`) em faixas de linhas revisáveis por arquivo e,
+ * quando o AST está disponível, no menor símbolo folha que contém cada âncora.
+ * É a fonte única usada pelo brief e pela pré-análise para evitar
+ * achados em código pré-existente.
+ *
+ * Fail-open: sem AST (grammar ausente/`--no-ast`/binário) o escopo cai nos
+ * hunks; sem patch, o arquivo fica sem faixas.
+ */
+
+import { changedAnchors } from "./ast/diff";
+import type { AstAnalysis, AstSymbol, AstSymbolKind } from "./ast/types";
+import type { DiffSource } from "./diff-source";
+
+/** Intervalo de linhas (1-based, inclusivo). */
+export type LineRange = { start: number; end: number };
+
+/** Símbolo alterado (o menor símbolo folha que contém uma âncora). */
+export type ChangedSymbol = {
+	name: string;
+	kind: AstSymbolKind;
+	startLine: number;
+	endLine: number;
+};
+
+/** Origem do escopo: AST (símbolos) ou hunks (fallback determinístico). */
+export type ChangedScopeSource = "ast" | "hunks";
+
+/** Escopo de um arquivo alterado. */
+export type FileChangedScope = {
+	/** Faixas revisáveis (símbolos alterados + âncoras soltas), ordenadas. */
+	ranges: LineRange[];
+	/** Símbolos folha tocados pelas âncoras. */
+	symbols: ChangedSymbol[];
+	source: ChangedScopeSource;
+};
+
+/** Escopo do diff: caminho do arquivo → faixas revisáveis. */
+export type ChangedScope = Record<string, FileChangedScope>;
+
+/** Entrada mínima do builder (status do `git diff --name-status`). */
+export type ScopeEntry = { path: string; status: string };
+
+export type BuildChangedScopeInput = {
+	entries: readonly ScopeEntry[];
+	/** Patch por arquivo (idealmente `git diff -U0`, sem truncar). */
+	diff: DiffSource;
+	/** Análises da versão atual (`null`/ausente → fallback nos hunks). */
+	ast?: ReadonlyMap<string, AstAnalysis>;
+};
+
+/** Espécies que representam containers: não expandem sozinhas o escopo. */
+const CONTAINER_KINDS: ReadonlySet<AstSymbolKind> = new Set([
+	"class",
+	"interface",
+	"enum",
+]);
+
+/** Tamanho do intervalo de um símbolo (menor = mais específico). */
+function span(symbol: AstSymbol): number {
+	return symbol.endLine - symbol.startLine;
+}
+
+/** Menor símbolo folha que contém a linha (containers são ignorados). */
+function leafAt(symbols: readonly AstSymbol[], line: number): AstSymbol | undefined {
+	let best: AstSymbol | undefined;
+	for (const symbol of symbols) {
+		if (CONTAINER_KINDS.has(symbol.kind)) continue;
+		if (line < symbol.startLine || line > symbol.endLine) continue;
+		if (!best || span(symbol) < span(best)) best = symbol;
+	}
+	return best;
+}
+
+/** Converte um símbolo AST no shape do escopo. */
+function toChangedSymbol(symbol: AstSymbol): ChangedSymbol {
+	return {
+		name: symbol.name,
+		kind: symbol.kind,
+		startLine: symbol.startLine,
+		endLine: symbol.endLine,
+	};
+}
+
+/** Deduplica símbolos por identidade e posição, mantendo a ordem de leitura. */
+function uniqueSymbols(symbols: readonly AstSymbol[]): ChangedSymbol[] {
+	const seen = new Set<string>();
+	const result: ChangedSymbol[] = [];
+	for (const symbol of symbols) {
+		const key = `${symbol.kind}:${symbol.name}:${symbol.startLine}:${symbol.endLine}`;
+		if (seen.has(key)) continue;
+		seen.add(key);
+		result.push(toChangedSymbol(symbol));
+	}
+	return result.sort((a, b) => a.startLine - b.startLine || a.endLine - b.endLine);
+}
+
+/** `true` se a linha está dentro de alguma faixa. */
+export function isLineInScope(scope: ChangedScope, file: string, line: number): boolean {
+	const entry = scope[file];
+	if (!entry) return false;
+	return entry.ranges.some((range) => line >= range.start && line <= range.end);
+}
+
+/** Une intervalos sobrepostos/adjacentes (ordem estável por início). */
+export function mergeRanges(ranges: readonly LineRange[]): LineRange[] {
+	const sorted = [...ranges]
+		.filter((range) => range.end >= range.start)
+		.sort((a, b) => a.start - b.start || a.end - b.end);
+	const merged: LineRange[] = [];
+	for (const range of sorted) {
+		const last = merged.at(-1);
+		if (last && range.start <= last.end + 1) {
+			last.end = Math.max(last.end, range.end);
+			continue;
+		}
+		merged.push({ ...range });
+	}
+	return merged;
+}
+
+/**
+ * Escopo por arquivo alterado. Arquivos deletados/renomeados sem hunks ficam
+ * com faixas vazias (não há código atual para ancorar finding).
+ */
+export function buildChangedScope(input: BuildChangedScopeInput): ChangedScope {
+	const scope: ChangedScope = {};
+
+	for (const entry of input.entries) {
+		if (entry.status === "deleted") continue;
+		const analysis = input.ast?.get(entry.path);
+		if (analysis?.deleted) continue;
+
+		const patch = input.diff.byFile.get(entry.path) ?? "";
+		const { added, deletedAt } = changedAnchors(patch);
+		const anchors = new Set<number>([...added, ...deletedAt]);
+		const source: ChangedScopeSource = analysis ? "ast" : "hunks";
+
+		const touched: AstSymbol[] = [];
+		if (analysis) {
+			for (const line of anchors) {
+				const symbol = leafAt(analysis.facts.symbols, line);
+				if (symbol) touched.push(symbol);
+			}
+		}
+		const symbols = uniqueSymbols(touched);
+
+		// Âncoras fora de símbolo folha (imports, topo do módulo, cabeçalho de
+		// classe) continuam revisáveis como faixas avulsas.
+		const covered = (line: number): boolean =>
+			symbols.some((symbol) => line >= symbol.startLine && line <= symbol.endLine);
+		const loose = [...anchors].filter((line) => !covered(line));
+
+		scope[entry.path] = {
+			ranges: mergeRanges([
+				...symbols.map((symbol) => ({
+					start: symbol.startLine,
+					end: symbol.endLine,
+				})),
+				...loose.map((line) => ({ start: line, end: line })),
+			]),
+			symbols,
+			source,
+		};
+	}
+
+	return scope;
+}
+
+/** Totais do escopo (mensagens, tool e testes). */
+export function summarizeScope(scope: ChangedScope): {
+	files: number;
+	ranges: number;
+	symbols: number;
+} {
+	let ranges = 0;
+	let symbols = 0;
+	for (const entry of Object.values(scope)) {
+		ranges += entry.ranges.length;
+		symbols += entry.symbols.length;
+	}
+	return { files: Object.keys(scope).length, ranges, symbols };
+}
+
+/** Faixas em texto compacto (`10-14, 22`) para prompts e briefs. */
+export function formatRanges(ranges: readonly LineRange[], max = 8): string {
+	if (ranges.length === 0) return "sem linhas alteradas";
+	const shown = ranges
+		.slice(0, max)
+		.map((range) =>
+			range.start === range.end ? `${range.start}` : `${range.start}-${range.end}`,
+		);
+	const rest = ranges.length > max ? ` (+${ranges.length - max})` : "";
+	return `${shown.join(", ")}${rest}`;
+}
+
+/** Símbolos em texto compacto (`` `foo` (10-40)``) para prompts e briefs. */
+export function formatSymbols(symbols: readonly ChangedSymbol[], max = 6): string {
+	if (symbols.length === 0) return "";
+	const shown = symbols
+		.slice(0, max)
+		.map((symbol) => `\`${symbol.name}\` (${symbol.startLine}-${symbol.endLine})`);
+	const rest = symbols.length > max ? ` (+${symbols.length - max})` : "";
+	return `${shown.join(", ")}${rest}`;
+}

package/src/core/commands/scaffold.ts

@@ -131,16 +131,6 @@ export type Rule = {
 	severity: Severity;
 	text: string;
 	jev?: JevRuleSpec;
-	hints?: RuleHints;
-};
-
-/** Sinais opcionais de uma regra (símbolos, imports, decorators, paths, checks). */
-export type RuleHints = {
-	symbols?: string[];
-	imports?: string[];
-	decorators?: string[];
-	paths?: string[];
-	checks?: string[];
 };
 
 /** Como o watchdog casa um arquivo alterado. \`value\` é sempre regex. */
@@ -235,20 +225,15 @@ export type HoundsmanAiFeatures = {
 /** Overrides de IA por watchdog. */
 export type HoundsmanAiWatchdog = {
 	model?: string;
-	maxSteps?: number;
-	maxOutputTokens?: number;
 };
 
-/** Configuração da camada de IA (briefs, contexto, classificação e hunt nativo). */
+/** Configuração da camada de IA (briefs, contexto, classificação, pré-análise, verify). */
 export type HoundsmanAi = {
 	enabled?: boolean;
 	provider?: AiProviderKind;
 	model?: string;
 	baseURL?: string;
 	concurrency?: number;
-	maxSteps?: number;
-	maxOutputTokens?: number;
-	temperature?: number;
 	providerOptions?: AiProviderOptions;
 	timeoutMs?: number;
 	maxCallsPerReview?: number;
@@ -257,6 +242,16 @@ export type HoundsmanAi = {
 	watchdogs?: Record<string, HoundsmanAiWatchdog>;
 };
 
+/** Harness local da capability \`hunt\` (\`houndsman hunt\`) — opcional. */
+export type HoundsmanHunt = {
+	enabled?: boolean;
+	model?: string;
+	concurrency?: number;
+	timeoutMs?: number;
+	retries?: number;
+	binaryPath?: string;
+};
+
 /** Contrato de configuração do motor. */
 export type HoundsmanConfig<TId extends string = string> = {
 	projectName: string;
@@ -270,6 +265,7 @@ export type HoundsmanConfig<TId extends string = string> = {
 	concurrency?: HoundsmanConcurrency;
 	ast?: HoundsmanAst;
 	ai?: HoundsmanAi;
+	hunt?: HoundsmanHunt;
 };
 
 /** Helper de autoria (identidade) — apenas tipagem. */
@@ -337,7 +333,6 @@ export const defaultWatchdog = defineWatchdog({
 		{
 			severity: "attention",
 			text: "Promover: nome, contrato e documentação do símbolo correspondem ao comportamento real.",
-			hints: { checks: ["symbol_context"] },
 		},
 		{
 			severity: "attention",
@@ -350,7 +345,6 @@ export const defaultWatchdog = defineWatchdog({
 		{
 			severity: "suggestion",
 			text: "Evitar: lógica de negócio duplicada ou divergente entre camadas.",
-			hints: { checks: ["find_references"] },
 		},
 		{
 			severity: "suggestion",

package/src/core/config.ts

@@ -13,15 +13,17 @@ import type { WatchdogDefinition } from "./types";
 export {
 	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_MAKI_VERSION,
 	DEFAULT_MAX_FILES_PER_BRIEF,
 } from "./defaults";
 
@@ -85,11 +87,9 @@ export type HoundsmanAiFeatures = {
 /** Overrides de IA por watchdog. */
 export type HoundsmanAiWatchdog = {
 	model?: string;
-	maxSteps?: number;
-	maxOutputTokens?: number;
 };
 
-/** Configuração da camada de IA (genérica; o harness nativo também a consome). */
+/** Configuração da camada de IA (briefs, contexto, classificação, pré-análise, verify). */
 export type HoundsmanAi = {
 	/** Liga a IA do fluxo normal (default: `true`; sem chave é fail-open). */
 	enabled?: boolean;
@@ -101,15 +101,6 @@ export type HoundsmanAi = {
 	baseURL?: string;
 	/** Chamadas simultâneas (default: 2). */
 	concurrency?: number;
-	/** Passos por agente (default: 12). */
-	maxSteps?: number;
-	/** Teto de tokens de saída por chamada. */
-	maxOutputTokens?: number;
-	/**
-	 * Temperatura (default: 0). Ignorada quando o provider usa thinking
-	 * (DeepSeek V4 liga thinking por default) — nesse caso o motor não a envia.
-	 */
-	temperature?: number;
 	/** Opções do AI SDK por provider (repassadas sem interpretação). */
 	providerOptions?: AiProviderOptions;
 	/** Timeout por chamada em ms (default: 120_000). */
@@ -135,6 +126,28 @@ export type HoundsmanWorktrees = {
 	location?: "home" | "workspace" | string;
 };
 
+/**
+ * Harness local da capability `hunt` (`houndsman hunt`) — opcional.
+ *
+ * Sem esta config, o comando usa defaults seguros: modelo derivado de `ai`,
+ * 4 processos simultâneos e timeout de 15 min por watchdog. A skill
+ * `/houndsman hunt` (harness externo) não depende deste bloco.
+ */
+export type HoundsmanHunt = {
+	/** Desliga o harness local sem desinstalar o binário (default: ligado). */
+	enabled?: boolean;
+	/** Modelo no formato do maki (`provider/model-id`). Default: derivado de `ai`. */
+	model?: string;
+	/** Processos maki simultâneos (default: 4). */
+	concurrency?: number;
+	/** Timeout por watchdog em ms (default: 900_000). */
+	timeoutMs?: number;
+	/** Tentativas extras quando a saída do watchdog é inválida (default: 1). */
+	retries?: number;
+	/** Caminho explícito do binário (`HOUNDSMAN_MAKI_PATH` tem precedência). */
+	binaryPath?: string;
+};
+
 /** Backend de persistência (reviews, findings e artefatos). */
 export type HoundsmanStorage = {
 	/**
@@ -180,8 +193,10 @@ export type HoundsmanConfig<TId extends string = string> = {
 	concurrency?: HoundsmanConcurrency;
 	/** AST determinístico (classificação estrutural, brief e impacto). */
 	ast?: HoundsmanAst;
-	/** Camada de IA (briefs, contexto, classificação e o harness nativo). */
+	/** Camada de IA (briefs, contexto, classificação, pré-análise e verify). */
 	ai?: HoundsmanAi;
+	/** Harness local da capability `hunt` (maki) — opcional. */
+	hunt?: HoundsmanHunt;
 };
 
 /** Entrada de `defineHoundsmanConfig` — `watchdogIds` é derivado, não informado. */

package/src/core/defaults.ts

@@ -41,14 +41,23 @@ export const DEFAULT_AI_MODEL = "deepseek-v4-pro";
 /** Concorrência default das chamadas de IA. */
 export const DEFAULT_AI_CONCURRENCY = 2;
 
-/** Passos default por agente (loop de tools + saída). */
-export const DEFAULT_AI_MAX_STEPS = 12;
-
 /** Timeout default de uma chamada de modelo (ms). */
 export const DEFAULT_AI_TIMEOUT_MS = 120_000;
 
 /** Teto default de chamadas de IA por review. */
 export const DEFAULT_AI_MAX_CALLS_PER_REVIEW = 40;
 
-/** Teto default de tokens de saída por chamada. */
-export const DEFAULT_AI_MAX_OUTPUT_TOKENS = 4096;
+/** Processos maki simultâneos no harness local (`houndsman hunt`). */
+export const DEFAULT_HUNT_CONCURRENCY = 4;
+
+/** Timeout default de um watchdog no harness local (15 min). */
+export const DEFAULT_HUNT_TIMEOUT_MS = 900_000;
+
+/** Retentativas default quando a saída do watchdog é inválida. */
+export const DEFAULT_HUNT_RETRIES = 1;
+
+/**
+ * Versão do maki fixada pelo houndsman. O binário é baixado por
+ * `houndsman hunt install`; `HOUNDSMAN_MAKI_VERSION` sobrescreve.
+ */
+export const DEFAULT_MAKI_VERSION = "0.6.5";