@payconductor/houndsman 0.5.0 → 0.7.0

package/src/harness/investigation/investigation-planner.ts

@@ -0,0 +1,118 @@
+/**
+ * Planejador determinístico da investigação.
+ *
+ * Converte `RuleAnalysis[]` em tarefas priorizadas (severidade + confiança +
+ * impacto). Uma estratégia diferente pode ser injetada sem tocar no agente.
+ */
+
+import { severityRank } from "../../core/types";
+import type { ToolCapability } from "../tools/agent-tool";
+import type {
+	InvestigationPlan,
+	InvestigationStrategy,
+	InvestigationTask,
+} from "./investigation-task";
+import type { RuleAnalysis } from "./rule-analyzer";
+
+/** Contexto mínimo do planejamento. */
+export type PlannerContext = {
+	watchdogId: string;
+	files: readonly string[];
+	symbols: readonly string[];
+	/** Arquivos impactados (reverse deps) do diff. */
+	impacted?: readonly string[];
+};
+
+/** Planejador default. */
+export class InvestigationPlanner implements InvestigationStrategy {
+	plan(context: PlannerContext, rules: readonly RuleAnalysis[]): InvestigationPlan {
+		const tasks: InvestigationTask[] = [];
+		const allFiles = [...new Set([...context.files, ...(context.impacted ?? [])])];
+		let estimatedToolCalls = 0;
+
+		rules.forEach((analysis, index) => {
+			const symbols = analysis.signals
+				.filter((signal) => signal.kind === "symbol")
+				.map((signal) => signal.value);
+			const matchedFiles = filesFor(analysis, context.files);
+			const files = matchedFiles.length > 0 ? matchedFiles : [...context.files];
+			const capabilities = capabilitiesFor(analysis);
+			estimatedToolCalls +=
+				analysis.checks.length + (capabilities.length > 0 ? 1 : 0);
+			tasks.push({
+				id: `rule-${index}`,
+				rule: analysis.rule,
+				severity: analysis.severity,
+				kind: "rule-evidence",
+				files,
+				symbols: [...new Set([...symbols, ...context.symbols])].slice(0, 10),
+				capabilities,
+				priority: priorityOf(analysis, index),
+				status: "pending",
+			});
+		});
+
+		if (context.impacted && context.impacted.length > 0) {
+			tasks.push({
+				id: "impact",
+				rule: "impacto das alterações",
+				severity: "attention",
+				kind: "symbol-impact",
+				files: [...context.impacted],
+				symbols: [...context.symbols],
+				capabilities: ["impact", "references"],
+				priority: 5,
+				status: "pending",
+			});
+			estimatedToolCalls += 1;
+		}
+
+		tasks.sort((a, b) => a.priority - b.priority);
+		return { tasks, totalFiles: allFiles.length, estimatedToolCalls };
+	}
+}
+
+/** Arquivos da tarefa filtrados por `hints.paths` (regex) quando presentes. */
+function filesFor(analysis: RuleAnalysis, files: readonly string[]): string[] {
+	const patterns = analysis.signals
+		.filter((signal) => signal.kind === "path")
+		.map((signal) => signal.value);
+	if (patterns.length === 0) return [...files];
+	const matchers = patterns.flatMap((pattern) => {
+		try {
+			const regex = new RegExp(pattern);
+			return [(file: string) => regex.test(file)];
+		} catch {
+			return [(file: string) => file.includes(pattern)];
+		}
+	});
+	return files.filter((file) => matchers.some((match) => match(file)));
+}
+
+/** Capabilities sugeridas pela categoria/sinais da regra. */
+function capabilitiesFor(analysis: RuleAnalysis): ToolCapability[] {
+	const capabilities = new Set<ToolCapability>(["read", "search"]);
+	const kinds = new Set(analysis.signals.map((signal) => signal.kind));
+	if (kinds.has("symbol")) {
+		capabilities.add("symbol");
+		capabilities.add("references");
+	}
+	if (kinds.has("import") || kinds.has("path")) capabilities.add("search");
+	if (analysis.category === "architecture" || analysis.category === "data") {
+		capabilities.add("impact");
+	}
+	if (analysis.category === "tests") capabilities.add("tests");
+	if (analysis.category === "security") capabilities.add("references");
+	for (const check of analysis.checks) {
+		if (check.tool === "symbol_context") capabilities.add("symbol");
+		if (check.tool === "find_references") capabilities.add("references");
+	}
+	return [...capabilities];
+}
+
+/** Prioridade (menor = investigar antes). */
+function priorityOf(analysis: RuleAnalysis, index: number): number {
+	const confidencePenalty =
+		analysis.confidence === "high" ? 0 : analysis.confidence === "medium" ? 2 : 4;
+	return severityRank(analysis.severity) * 10 + confidencePenalty + index * 0.01;
+}

package/src/harness/investigation/investigation-task.ts

@@ -0,0 +1,10 @@
+/**
+ * Tipos de tarefa/plano — reexportados de `evidence.ts` para evitar ciclos.
+ */
+
+export type {
+	InvestigationPlan,
+	InvestigationStrategy,
+	InvestigationTask,
+	InvestigationTaskKind,
+} from "./evidence";

package/src/harness/investigation/review-journal.ts

@@ -0,0 +1,87 @@
+/**
+ * Diário da investigação (`harness-transcript.json`).
+ *
+ * Registra estados, chamadas de tool, evidências, decisões do crítico e
+ * truncamentos — sem prompt, resposta ou segredo.
+ */
+
+import type { ToolResult } from "../tools/tool-result";
+
+/** Registro de uma chamada de tool. */
+export type ToolCallRecord = {
+	tool: string;
+	state: string;
+	durationMs: number;
+	ok: boolean;
+	truncated: boolean;
+	error?: string;
+};
+
+/** Transição de estado do agente. */
+export type StateTransition = {
+	from: string;
+	to: string;
+	at: string;
+};
+
+/** Diário de um agente. */
+export class ReviewJournal {
+	readonly toolCalls: ToolCallRecord[] = [];
+	readonly transitions: StateTransition[] = [];
+	readonly notes: string[] = [];
+	private readonly startedAt = Date.now();
+
+	/** Registra uma chamada concluída. */
+	recordToolCall(
+		tool: string,
+		state: string,
+		durationMs: number,
+		result: ToolResult<unknown>,
+	): void {
+		this.toolCalls.push({
+			tool,
+			state,
+			durationMs: Math.round(durationMs),
+			ok: result.ok,
+			truncated: result.truncated === true,
+			...(result.error ? { error: result.error } : {}),
+		});
+	}
+
+	/** Registra uma transição de estado. */
+	transition(from: string, to: string): void {
+		this.transitions.push({ from, to, at: new Date().toISOString() });
+	}
+
+	/** Nota livre (hipótese, decisão, motivo de skip). */
+	note(message: string): void {
+		this.notes.push(message);
+	}
+
+	/** Métricas agregadas por tool. */
+	metrics(): Record<string, { calls: number; errors: number; durationMs: number }> {
+		const metrics: Record<
+			string,
+			{ calls: number; errors: number; durationMs: number }
+		> = {};
+		for (const call of this.toolCalls) {
+			const entry = metrics[call.tool] ?? { calls: 0, errors: 0, durationMs: 0 };
+			entry.calls++;
+			if (!call.ok) entry.errors++;
+			entry.durationMs += call.durationMs;
+			metrics[call.tool] = entry;
+		}
+		return metrics;
+	}
+
+	/** Snapshot serializável. */
+	toJSON(): Record<string, unknown> {
+		return {
+			elapsedMs: Date.now() - this.startedAt,
+			toolCalls: this.toolCalls,
+			transitions: this.transitions,
+			notes: this.notes,
+			metrics: this.metrics(),
+		};
+	}
+}

package/src/harness/investigation/rule-analyzer.ts

@@ -0,0 +1,178 @@
+/**
+ * Análise determinística de regras (`RuleAnalyzer`).
+ *
+ * Transforma uma regra textual em polaridade, categoria, keywords, sinais e
+ * checks. É a base do planner e do `rule_signals` tool. Um analyzer por IA pode
+ * complementar regras ambíguas, mas o resultado continua validado.
+ */
+
+import { POLARITY_WORDS, polarityOf, type RuleIntent } from "../../core/rule-text";
+import type { Rule, Severity } from "../../core/types";
+import {
+	DefaultRuleCheckFactory,
+	HeuristicRuleSignalExtractor,
+	type RuleCheck,
+	type RuleCheckFactory,
+	type RuleSignal,
+	type RuleSignalExtractor,
+} from "./rule-signals";
+
+export { polarityOf, type RuleIntent } from "../../core/rule-text";
+
+/** Categoria da regra. */
+export type RuleCategory =
+	| "architecture"
+	| "security"
+	| "data"
+	| "tests"
+	| "performance"
+	| "style"
+	| "other";
+
+/** Regra analisada (entrada do planner). */
+export type RuleAnalysis = {
+	rule: string;
+	severity: Severity;
+	intent: RuleIntent;
+	category: RuleCategory;
+	keywords: string[];
+	signals: RuleSignal[];
+	checks: RuleCheck[];
+	confidence: "high" | "medium" | "low";
+};
+
+const GENERIC_STOPWORDS = [
+	"para",
+	"pelo",
+	"pela",
+	"como",
+	"ser",
+	"que",
+	"com",
+	"sem",
+	"uma",
+	"dos",
+	"das",
+	"nos",
+	"nas",
+	"por",
+	"usar",
+	"todo",
+	"toda",
+	"quando",
+	"onde",
+] as const;
+
+/** Stopwords + palavras de polaridade (fonte única em `core/rule-text`). */
+const STOPWORDS = new Set<string>([...GENERIC_STOPWORDS, ...POLARITY_WORDS]);
+
+const CATEGORY_HINTS: readonly [RuleCategory, readonly string[]][] = [
+	[
+		"security",
+		[
+			"segredo",
+			"senha",
+			"token",
+			"auth",
+			"sanit",
+			"injection",
+			"sql",
+			"cripto",
+			"permiss",
+		],
+	],
+	["data", ["banco", "database", "db", "query", "migration", "schema", "transa"]],
+	["tests", ["teste", "test", "spec", "cobertura", "mock", "fixture"]],
+	[
+		"performance",
+		["cache", "performance", "latência", "latencia", "n+1", "índice", "indice"],
+	],
+	[
+		"architecture",
+		[
+			"camada",
+			"arquitetura",
+			"rota",
+			"controller",
+			"service",
+			"domínio",
+			"dominio",
+			"depend",
+		],
+	],
+	["style", ["nome", "formata", "lint", "coment", "estilo", "padrão", "padrao"]],
+];
+
+/** Analisador determinístico. */
+export class RuleAnalyzer {
+	private readonly extractor: RuleSignalExtractor;
+	private readonly checks: RuleCheckFactory;
+
+	constructor(
+		extractor: RuleSignalExtractor = new HeuristicRuleSignalExtractor(),
+		checks: RuleCheckFactory = new DefaultRuleCheckFactory(),
+	) {
+		this.extractor = extractor;
+		this.checks = checks;
+	}
+
+	/** Analisa todas as regras (ordem estável). */
+	analyze(rules: readonly Rule[]): RuleAnalysis[] {
+		return rules.map((rule) => this.analyzeRule(rule));
+	}
+
+	/** Analisa uma regra. */
+	analyzeRule(rule: Rule): RuleAnalysis {
+		const intent = polarityOf(rule.text);
+		const signals = this.extractor.extract(rule);
+		const category = categoryOf(rule.text, signals);
+		const confidence = confidenceOf(rule, signals);
+		return {
+			rule: rule.text,
+			severity: rule.severity,
+			intent,
+			category,
+			keywords: keywordsOf(rule.text),
+			signals,
+			checks: this.checks.create(rule, signals),
+			confidence,
+		};
+	}
+}
+
+/** Categoria inferida por keywords e sinais. */
+export function categoryOf(text: string, signals: readonly RuleSignal[]): RuleCategory {
+	const haystack =
+		`${text} ${signals.map((signal) => signal.value).join(" ")}`.toLowerCase();
+	for (const [category, hints] of CATEGORY_HINTS) {
+		if (hints.some((hint) => haystack.includes(hint))) return category;
+	}
+	return "other";
+}
+
+/** Keywords normalizadas (sem stopwords, limitadas). */
+export function keywordsOf(text: string): string[] {
+	const words = text
+		.toLowerCase()
+		.replace(/[^\p{L}\p{N}+\-/]+/gu, " ")
+		.split(/\s+/)
+		.filter((word) => word.length >= 4 && !STOPWORDS.has(word));
+	return [...new Set(words)].slice(0, 12);
+}
+
+/** Confiança da análise (hints explícitos valem mais que heurística). */
+function confidenceOf(
+	rule: Rule,
+	signals: readonly RuleSignal[],
+): RuleAnalysis["confidence"] {
+	const hints = rule.hints;
+	const hintCount =
+		(hints?.symbols?.length ?? 0) +
+		(hints?.imports?.length ?? 0) +
+		(hints?.decorators?.length ?? 0) +
+		(hints?.paths?.length ?? 0) +
+		(hints?.checks?.length ?? 0);
+	if (hintCount > 0) return "high";
+	if (signals.length > 0) return "medium";
+	return "low";
+}

package/src/harness/investigation/rule-signals.ts

@@ -0,0 +1,110 @@
+/**
+ * Extração determinística de sinais de uma regra em linguagem natural.
+ *
+ * Cada extrator é substituível (`RuleSignalExtractor`); o default usa `hints`
+ * + termos em backticks + identificadores. Nunca chama IA.
+ */
+
+import type { Rule } from "../../core/types";
+
+/** Sinal concreto sugerido por uma regra. */
+export type RuleSignal = {
+	kind: "symbol" | "import" | "decorator" | "path" | "grep" | "ast";
+	value: string;
+	rationale?: string;
+};
+
+/** Contrato de um extrator de sinais. */
+export interface RuleSignalExtractor {
+	extract(rule: Rule): RuleSignal[];
+}
+
+/** Extrai sinais dos `hints`, backticks e identificadores em CamelCase. */
+export class HeuristicRuleSignalExtractor implements RuleSignalExtractor {
+	extract(rule: Rule): RuleSignal[] {
+		const signals: RuleSignal[] = [];
+		const seen = new Set<string>();
+		const push = (kind: RuleSignal["kind"], value: string, rationale?: string) => {
+			const key = `${kind}:${value}`;
+			if (!value.trim() || seen.has(key)) return;
+			seen.add(key);
+			signals.push({ kind, value, ...(rationale ? { rationale } : {}) });
+		};
+
+		const hints = rule.hints ?? {};
+		for (const item of hints.symbols ?? []) push("symbol", item, "hint");
+		for (const item of hints.imports ?? []) push("import", item, "hint");
+		for (const item of hints.decorators ?? []) push("decorator", item, "hint");
+		for (const item of hints.paths ?? []) push("path", item, "hint");
+
+		for (const match of rule.text.matchAll(/`([^`]{2,80})`/g)) {
+			const value = match[1]?.trim();
+			if (value) push(classifyLiteral(value), value, "texto da regra");
+		}
+		for (const match of rule.text.matchAll(/\b([A-Z][a-zA-Z0-9]{2,})\b/g)) {
+			push("symbol", match[1] ?? "", "identificador");
+		}
+		return signals;
+	}
+}
+
+/** Classifica um literal em backticks (import, path, símbolo). */
+function classifyLiteral(value: string): RuleSignal["kind"] {
+	if (value.startsWith("@") || value.includes("/")) {
+		return value.includes("/") && !value.includes("@") ? "path" : "import";
+	}
+	if (/^[A-Z][a-zA-Z0-9]*$/.test(value)) return "symbol";
+	return "grep";
+}
+
+/** Gera checks concretos para uma regra. */
+export interface RuleCheckFactory {
+	create(rule: Rule, signals: readonly RuleSignal[]): RuleCheck[];
+}
+
+/** Check que prova/refuta uma regra usando uma tool. */
+export type RuleCheck = {
+	id: string;
+	description: string;
+	tool: string;
+	input: unknown;
+	required: boolean;
+};
+
+/** Checks default por presença de sinais. */
+export class DefaultRuleCheckFactory implements RuleCheckFactory {
+	create(rule: Rule, signals: readonly RuleSignal[]): RuleCheck[] {
+		const checks: RuleCheck[] = [];
+		const explicit = rule.hints?.checks ?? [];
+		explicit.forEach((tool, index) => {
+			checks.push({
+				id: `${index}:${tool}`,
+				description: `Executar ${tool} para a regra`,
+				tool,
+				input: {},
+				required: true,
+			});
+		});
+		const symbols = signals.filter((signal) => signal.kind === "symbol");
+		if (symbols.length > 0 && explicit.length === 0) {
+			checks.push({
+				id: "symbol-context",
+				description: `Inspecionar o contexto de ${symbols[0]?.value}`,
+				tool: "symbol_context",
+				input: { symbol: symbols[0]?.value },
+				required: false,
+			});
+		}
+		const imports = signals.filter((signal) => signal.kind === "import");
+		if (imports.length > 0) {
+			checks.push({
+				id: "find-references",
+				description: `Procurar usos de ${imports[0]?.value}`,
+				tool: "find_references",
+				input: { symbol: imports[0]?.value },
+				required: false,
+			});
+		}
+		return checks;
+	}
+}

package/src/harness/prompts/agent-schemas.ts

@@ -0,0 +1,57 @@
+/**
+ * Schemas das saídas intermediárias da máquina de estados.
+ */
+
+import { z } from "zod";
+import { SeveritySchema } from "../../core/ai/schemas";
+
+/** ORIENT: hipóteses iniciais. */
+export const OrientOutputSchema = z.object({
+	hypotheses: z.array(z.string()).max(8).default([]),
+});
+export type OrientOutput = z.infer<typeof OrientOutputSchema>;
+
+/** PLAN: tarefas escolhidas do plano determinístico. */
+export const PlanOutputSchema = z.object({
+	taskIds: z.array(z.string()).default([]),
+});
+export type PlanOutput = z.infer<typeof PlanOutputSchema>;
+
+/** INVESTIGATE: drafts + cobertura. */
+export const FindingDraftSchema = z.object({
+	rule: z.string(),
+	severity: SeveritySchema,
+	file: z.string(),
+	line: z.number().int().positive().optional(),
+	message: z.string(),
+	action: z.string(),
+	evidenceIds: z.array(z.string()).default([]),
+	confidence: z.number().min(0).max(1).default(0.6),
+});
+
+export const CoverageOutputSchema = z.object({
+	rule: z.string(),
+	status: z.enum(["checked", "not_applicable", "skipped"]),
+	reason: z.string().optional(),
+});
+
+export const InvestigateOutputSchema = z.object({
+	findingDrafts: z.array(FindingDraftSchema).default([]),
+	coverage: z.array(CoverageOutputSchema).default([]),
+});
+export type InvestigateOutput = z.infer<typeof InvestigateOutputSchema>;
+
+/** VERIFY: decisão do crítico (opcional; determinístico por default). */
+export const CriticOutputSchema = z.object({
+	decisions: z
+		.array(
+			z.object({
+				rule: z.string(),
+				file: z.string(),
+				verdict: z.enum(["keep", "drop", "downgrade"]),
+				reason: z.string().optional(),
+			}),
+		)
+		.default([]),
+});
+export type CriticOutput = z.infer<typeof CriticOutputSchema>;

package/src/harness/prompts/reviewer-prompt-builder.ts

@@ -0,0 +1,101 @@
+/**
+ * System prompt do revisor (harness nativo).
+ *
+ * Ordem estável: papel, regras, escopo, procedimento, contrato e segurança.
+ * Descrições de tools vêm do `ToolRegistry` (nunca hardcoded).
+ */
+
+import { buildSystem } from "../../core/ai/prompts/base";
+import { OUTPUT_FORMAT_PATH } from "../../core/paths";
+import type { AgentContext } from "../agent/agent-context";
+
+/** System prompt do agente. */
+export function buildReviewerSystem(
+	context: AgentContext,
+	toolDescriptions: string,
+): string {
+	const rules = context.watchdog.rules.map(
+		(rule) => `- [${rule.severity}] ${rule.text}`,
+	);
+	return buildSystem(
+		`Você é um revisor sênior de ${context.projectName}, especialista no domínio '${context.watchdog.name}'.`,
+		[
+			"Você investiga o diff com tools read-only e só conclui com evidência.",
+			"Nunca invente achado, arquivo, linha ou regra.",
+			"Toda regra deve terminar com cobertura (checked, not_applicable ou skipped).",
+			"blocking/attention exigem evidência rastreável.",
+			context.watchdog.definition.allowEmergentFindings
+				? "Findings emergentes de lógica/domínio usam `Lógica:`/`Domínio:`, exigem evidência e severidade máxima attention."
+				: "Todo finding deve citar uma regra existente do watchdog.",
+			"",
+			"## Regras do watchdog",
+			...rules,
+			"",
+			"## Escopo",
+			context.watchdog.scope,
+			"",
+			"## Procedimento",
+			"1. ORIENT — entenda regras, diff, AST e impacto.",
+			"2. PLAN — escolha as tarefas priorizadas.",
+			"3. INVESTIGATE — use tools para coletar evidências; refute hipóteses.",
+			"4. VERIFY — cada draft precisa de evidência válida.",
+			"5. CONCLUDE — produza o relatório.",
+			"",
+			"## Tools disponíveis",
+			toolDescriptions,
+			"",
+			"## Contrato de saída",
+			`O relatório final segue ${OUTPUT_FORMAT_PATH}.`,
+			"Em INVESTIGATE produza JSON com findingDrafts e coverage.",
+		],
+	);
+}
+
+/** Prompt do usuário (contexto compactado; nunca arquivo inteiro). */
+export function buildReviewerUser(context: AgentContext): string {
+	const lines = [
+		`Branch: ${context.branch}`,
+		`Watchdog: ${context.watchdog.name} (${context.watchdog.id})`,
+		`Arquivos do domínio (${context.files.length}):`,
+		...context.files.slice(0, 40).map((file) => `- ${file}`),
+	];
+	if (context.overflow.length > 0) {
+		lines.push(
+			"",
+			`Fora do orçamento (${context.overflow.length}) — NÃO ler; registrar em skipped:`,
+			...context.overflow.slice(0, 40).map((file) => `- ${file}`),
+		);
+	}
+	if (context.deleted.length > 0) {
+		lines.push("", "Deletados:", ...context.deleted.map((file) => `- ${file}`));
+	}
+	if (context.context) {
+		lines.push("", "## Contexto da PR");
+		if (context.context.objective)
+			lines.push(`Objetivo: ${context.context.objective}`);
+		if (context.context.motivation)
+			lines.push(`Motivação: ${context.context.motivation}`);
+		for (const item of context.context.changeSummary ?? []) lines.push(`- ${item}`);
+	}
+	if (context.ast.size > 0) {
+		lines.push("", "## Estrutura (AST)");
+		for (const [file, analysis] of context.ast) {
+			if (!analysis.delta) continue;
+			const delta = analysis.delta;
+			lines.push(
+				`- ${file}: +${delta.addedSymbols.length} −${delta.removedSymbols.length} ~${delta.modifiedSymbols.length}`,
+			);
+		}
+	}
+	if (context.impact && context.impact.affectedFiles.length > 0) {
+		lines.push(
+			"",
+			`Impacto: ${context.impact.affectedFiles.length} arquivo(s) importam o diff.`,
+			...context.impact.affectedFiles.slice(0, 20).map((file) => `- ${file}`),
+		);
+	}
+	if (context.docs.length > 0) {
+		lines.push("", "Docs de contexto:", ...context.docs.map((doc) => `- ${doc}`));
+	}
+	return lines.join("\n");
+}

package/src/harness/prompts/states/conclude-prompt.ts

@@ -0,0 +1,16 @@
+/**
+ * Prompt do estado CONCLUDE (documentação do contrato).
+ *
+ * A conclusão do harness é determinística (bits de evidência/coverage); este
+ * texto existe para manter o contrato explícito e servir a um futuro modo
+ * "conclude por modelo".
+ */
+
+/** Instruções de conclusão. */
+export function concludePrompt(): string {
+	return [
+		"Conclua com base apenas nos drafts sobreviventes ao VERIFY.",
+		"Não adicione achados novos.",
+		"Toda regra sem achado deve constar como coverage checked/not_applicable/skipped.",
+	].join("\n");
+}