@payconductor/houndsman 0.5.0 → 0.6.0

package/src/harness/investigation/evidence-verifier.ts

@@ -0,0 +1,129 @@
+/**
+ * Verificador de evidências (`EvidenceVerifier`).
+ *
+ * Confere arquivo/linha/snippet contra o working tree. Evidência inválida não
+ * sustenta finding: o draft é descartado (ou reancorado quando o snippet existe
+ * em outra linha).
+ */
+
+import { normalizeLine } from "../../core/finding-anchor";
+import type { AgentState } from "./agent-state";
+import type { Evidence, FindingDraft } from "./evidence";
+
+/** Resultado da verificação de uma evidência. */
+export type EvidenceVerdict = {
+	evidence: Evidence;
+	valid: boolean;
+	reason?: string;
+	/** Linhas corrigidas quando o snippet foi reancorado. */
+	startLine?: number;
+	endLine?: number;
+};
+
+/** Resultado da verificação de um draft. */
+export type DraftVerdict = {
+	draft: FindingDraft;
+	valid: boolean;
+	evidence: Evidence[];
+	reason?: string;
+};
+
+/** Verificador de evidências por conteúdo. */
+export class EvidenceVerifier {
+	private readonly allowedFiles: ReadonlySet<string>;
+	private readonly readFile: (path: string) => string | null;
+
+	constructor(options: {
+		allowedFiles: Iterable<string>;
+		readFile: (path: string) => string | null;
+	}) {
+		this.allowedFiles = new Set(options.allowedFiles);
+		this.readFile = options.readFile;
+	}
+
+	/** Verifica uma evidência (arquivo permitido + snippet localizado). */
+	verify(evidence: Evidence): EvidenceVerdict {
+		if (!this.allowedFiles.has(evidence.file)) {
+			return { evidence, valid: false, reason: "arquivo fora do domínio/impacto" };
+		}
+		const content = this.readFile(evidence.file);
+		if (content === null) {
+			return { evidence, valid: false, reason: "arquivo ausente" };
+		}
+		const lines = content.replace(/\r\n/g, "\n").split("\n");
+		const expected = evidence.snippet
+			.split("\n")
+			.map(normalizeLine)
+			.filter((line) => line.length > 0);
+		if (expected.length === 0) {
+			return { evidence, valid: false, reason: "snippet vazio" };
+		}
+
+		const start = Math.max(1, evidence.startLine);
+		const actual = lines
+			.slice(start - 1, start - 1 + expected.length)
+			.map(normalizeLine);
+		if (sameLines(actual, expected)) {
+			return {
+				evidence,
+				valid: true,
+				startLine: start,
+				endLine: start + expected.length - 1,
+			};
+		}
+
+		const relocated = lines.findIndex((_line, index) =>
+			sameLines(
+				lines.slice(index, index + expected.length).map(normalizeLine),
+				expected,
+			),
+		);
+		if (relocated >= 0) {
+			return {
+				evidence,
+				valid: true,
+				reason: "reancorado",
+				startLine: relocated + 1,
+				endLine: relocated + expected.length,
+			};
+		}
+		return { evidence, valid: false, reason: "snippet não encontrado no arquivo" };
+	}
+
+	/** Verifica um draft: precisa de ao menos uma evidência válida. */
+	verifyDraft(draft: FindingDraft, state: AgentState): DraftVerdict {
+		const evidence: Evidence[] = [];
+		const reasons: string[] = [];
+		for (const id of draft.evidenceIds) {
+			const item = state.getEvidence(id);
+			if (!item) {
+				reasons.push(`evidência '${id}' inexistente`);
+				continue;
+			}
+			const verdict = this.verify(item);
+			if (verdict.valid) {
+				evidence.push({
+					...item,
+					startLine: verdict.startLine ?? item.startLine,
+					endLine: verdict.endLine ?? item.endLine,
+				});
+			} else {
+				reasons.push(verdict.reason ?? "evidência inválida");
+			}
+		}
+		return {
+			draft,
+			valid: evidence.length > 0,
+			evidence,
+			...(evidence.length === 0
+				? { reason: reasons.join("; ") || "sem evidência" }
+				: {}),
+		};
+	}
+}
+
+/** Compara linhas normalizadas. */
+function sameLines(a: readonly string[], b: readonly string[]): boolean {
+	if (a.length !== b.length) return false;
+	return a.every((line, index) => line === b[index]);
+}

package/src/harness/investigation/evidence.ts

@@ -0,0 +1,110 @@
+/**
+ * Tipos de investigação (harness nativo).
+ *
+ * Uma revisão é uma investigação: regras viram tarefas, tarefas produzem
+ * evidências, e só drafts com evidência válida viram findings.
+ */
+
+import type { Severity } from "../../core/types";
+import type { ToolCapability } from "../tools/agent-tool";
+
+/** Tipo de tarefa investigável. */
+export type InvestigationTaskKind =
+	| "rule-evidence"
+	| "symbol-impact"
+	| "tests"
+	| "context";
+
+/** Tarefa de investigação derivada de uma regra. */
+export type InvestigationTask = {
+	id: string;
+	rule: string;
+	severity: Severity;
+	kind: InvestigationTaskKind;
+	files: string[];
+	symbols: string[];
+	capabilities: ToolCapability[];
+	/** Prioridade (menor = antes). */
+	priority: number;
+	status: "pending" | "in_progress" | "done" | "skipped";
+	reason?: string;
+};
+
+/** Plano completo de um agente. */
+export type InvestigationPlan = {
+	tasks: InvestigationTask[];
+	totalFiles: number;
+	estimatedToolCalls: number;
+};
+
+/** Estratégia substituível de planejamento. */
+export interface InvestigationStrategy {
+	plan(
+		context: {
+			watchdogId: string;
+			files: readonly string[];
+			symbols: readonly string[];
+		},
+		rules: readonly import("./rule-analyzer").RuleAnalysis[],
+	): InvestigationPlan;
+}
+
+/** Evidência coletada por uma tool. */
+export type EvidenceKind =
+	| "definition"
+	| "reference"
+	| "import"
+	| "diff"
+	| "test"
+	| "doc";
+
+/** Trecho de código/docs que sustenta uma conclusão. */
+export type Evidence = {
+	id: string;
+	file: string;
+	startLine: number;
+	endLine: number;
+	snippet: string;
+	kind: EvidenceKind;
+	sourceTool: string;
+	confidence: number;
+};
+
+/** Status de cobertura de uma regra. */
+export type RuleCoverageStatus = "checked" | "not_applicable" | "skipped";
+
+/** Cobertura de uma regra (toda regra precisa terminar aqui). */
+export type RuleCoverage = {
+	rule: string;
+	status: RuleCoverageStatus;
+	files: string[];
+	symbols: string[];
+	reason?: string;
+};
+
+/** Achado proposto pelo agente (ainda não é finding final). */
+export type FindingDraft = {
+	rule: string;
+	severity: Severity;
+	file: string;
+	line?: number;
+	message: string;
+	action: string;
+	evidenceIds: string[];
+	confidence: number;
+};
+
+/** Decisão do crítico sobre um draft. */
+export type CriticVerdict = "keep" | "drop" | "downgrade";
+
+/** Resultado do crítico. */
+export type CriticDecision = {
+	draft: FindingDraft;
+	verdict: CriticVerdict;
+	reason: string;
+};
+
+/** Gera o id de uma evidência (determinístico por ordem de coleta). */
+export function evidenceId(sequence: number): string {
+	return `ev-${String(sequence).padStart(3, "0")}`;
+}

package/src/harness/investigation/finding-critic.ts

@@ -0,0 +1,96 @@
+/**
+ * Crítico de findings (`FindingCritic`).
+ *
+ * Segunda passada com o objetivo de **refutar** cada draft. Regras:
+ *  - sem evidência válida → drop;
+ *  - regra inexistente → drop;
+ *  - confiança baixa → downgrade; muito baixa → drop;
+ *  - `blocking`/`attention` exigem crítica (determinística aqui; um crítico
+ *    por IA pode ser injetado no futuro).
+ */
+
+import { emergentText, isEmergentRule } from "../../core/rule-text";
+import { type Severity, severityRank } from "../../core/types";
+import type { AgentState } from "./agent-state";
+import type { CriticDecision, FindingDraft } from "./evidence";
+import type { EvidenceVerifier } from "./evidence-verifier";
+
+/** Regras válidas do watchdog (texto). */
+export type CriticOptions = {
+	knownRules: ReadonlySet<string>;
+	verifier: EvidenceVerifier;
+	/** Aceita findings `Lógica:`/`Domínio:` fora das regras. */
+	allowEmergentFindings?: boolean;
+};
+
+/** Crítico determinístico. */
+export class FindingCritic {
+	private readonly options: CriticOptions;
+
+	constructor(options: CriticOptions) {
+		this.options = options;
+	}
+
+	/** Avalia todos os drafts, na ordem. */
+	review(drafts: readonly FindingDraft[], state: AgentState): CriticDecision[] {
+		return drafts.map((draft) => this.reviewOne(draft, state));
+	}
+
+	/** Avalia um draft. */
+	reviewOne(draft: FindingDraft, state: AgentState): CriticDecision {
+		const known = this.options.knownRules.has(draft.rule.trim());
+		const emergent = isEmergentRule(draft.rule);
+		if (!known && !(emergent && this.options.allowEmergentFindings)) {
+			return {
+				draft,
+				verdict: "drop",
+				reason: emergent
+					? "finding emergente desabilitado no watchdog"
+					: "regra não existe no watchdog",
+			};
+		}
+		if (emergent && !emergentText(draft.rule)) {
+			return { draft, verdict: "drop", reason: "finding emergente sem descrição" };
+		}
+		const verdict = this.options.verifier.verifyDraft(draft, state);
+		if (!verdict.valid) {
+			return { draft, verdict: "drop", reason: verdict.reason ?? "sem evidência" };
+		}
+		if (draft.confidence < 0.4) {
+			return { draft, verdict: "drop", reason: "confiança abaixo de 0.4" };
+		}
+		const normalized = emergent
+			? { ...draft, severity: capSeverity(draft.severity, "attention") }
+			: draft;
+		if (
+			normalized.confidence < 0.7 &&
+			(normalized.severity === "blocking" || normalized.severity === "attention")
+		) {
+			return {
+				draft: normalized,
+				verdict: "downgrade",
+				reason: "confiança insuficiente para a severidade",
+			};
+		}
+		return { draft: normalized, verdict: "keep", reason: "evidência válida" };
+	}
+}
+
+/** Limita a severidade a um teto (rank menor = mais grave). */
+export function capSeverity(severity: Severity, max: Severity): Severity {
+	return severityRank(severity) < severityRank(max) ? max : severity;
+}
+
+/** Rebaixa uma severidade em um nível. */
+export function downgrade(severity: Severity): Severity {
+	switch (severity) {
+		case "blocking":
+			return "attention";
+		case "attention":
+			return "suggestion";
+		case "suggestion":
+			return "nit";
+		default:
+			return "nit";
+	}
+}

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(),
+		};
+	}
+}