@payconductor/houndsman 0.5.0 → 0.6.0

package/src/core/types.ts

@@ -6,6 +6,8 @@
  * `Rule` e `WatchdogMeta` descrevem as regras consumidas pela renderização.
  */
 
+import type { BriefPlan } from "./ai/schemas";
+import type { AstFileBrief } from "./ast/types";
 import type { JevRuleSpec } from "./jev/jev-types";
 
 /** Severidade de um achado. `blocking` bloqueia o merge. */
@@ -27,6 +29,19 @@ export const SEVERITY_EMOJI: Record<Severity, string> = {
 	nit: "🔎",
 };
 
+/**
+ * Sinais opcionais de uma regra: ajudam o `RuleAnalyzer` a transformar texto
+ * em checagens concretas (símbolos, imports, decorators, paths e tools).
+ */
+export type RuleHints = {
+	symbols?: string[];
+	imports?: string[];
+	decorators?: string[];
+	paths?: string[];
+	/** Nomes de tools sugeridos (ex.: `symbol_context`). */
+	checks?: string[];
+};
+
 /**
  * Regra do watchdog: severidade + texto. O texto declara a polaridade de forma
  * explícita — `Promover:` (algo que DEVE acontecer) ou `Evitar:`/`Não`/`Nunca`
@@ -39,6 +54,7 @@ export type Rule = {
 	severity: Severity;
 	text: string;
 	jev?: JevRuleSpec;
+	hints?: RuleHints;
 };
 
 /**
@@ -48,9 +64,15 @@ export type Rule = {
  *
  * - `filename` (padrão) → padrão aplicado ao caminho do arquivo.
  * - `content`           → padrão aplicado ao conteúdo do arquivo.
+ * - `symbol`            → padrão aplicado aos nomes de símbolos (AST).
+ * - `import`            → padrão aplicado às fontes/nomes de imports (AST).
+ * - `export`            → padrão aplicado aos nomes exportados (AST).
+ * - `decorator`         → padrão aplicado aos decorators (AST).
+ *
+ * Regras AST exigem grammar disponível; sem ela, a regra simplesmente não casa.
  */
 export type ClassifyRule = {
-	type?: "filename" | "content";
+	type?: "filename" | "content" | "symbol" | "import" | "export" | "decorator";
 	value: string;
 };
 
@@ -116,6 +138,10 @@ export type WatchdogRenderArgs = {
 	docs: readonly string[];
 	context?: WatchdogRenderContext | null;
 	candidates?: readonly WatchdogRenderCandidate[];
+	/** Estrutura/delta dos arquivos selecionados (AST). */
+	ast?: readonly AstFileBrief[];
+	/** Plano de revisão sugerido por IA (nunca substitui as regras). */
+	aiPlan?: BriefPlan;
 };
 
 /** Definição completa de um watchdog — 1 por arquivo em `project/watchdogs/`. */
@@ -126,6 +152,16 @@ export type WatchdogDefinition = WatchdogMeta & {
 	description: string;
 	/** Watchdog deve checar breaking change em arquivos deletados do seu domínio. */
 	breakingChange?: boolean;
+	/**
+	 * Watchdog de último recurso: só assume arquivos que nenhum outro casou.
+	 * Útil para padrões gerais/lógica; `classify` é ignorado.
+	 */
+	fallback?: boolean;
+	/**
+	 * Permite findings emergentes (`Lógica:`/`Domínio:`) fora das regras
+	 * explícitas. Exige evidência e severidade máxima `attention`.
+	 */
+	allowEmergentFindings?: boolean;
 	/** Prioridade de arquivos/paths (ex-`O Que Revisar`). Opcional. */
 	reviewFocus?: readonly string[];
 	/** O que NUNCA carregar/enviar (ex-`NÃO carregar`). Opcional. */

package/src/core/verify.ts

@@ -25,8 +25,8 @@ import type { Severity } from "./types";
 /** Resultado da verificação de um finding. */
 export type VerifyStatus = "resolved" | "persisting" | "uncertain" | "file-missing";
 
-/** Mecanismo que decidiu o status (reancoragem local ou LLM). */
-export type VerifyBasis = "anchor" | "jev";
+/** Mecanismo que decidiu o status (reancoragem local, Jev ou IA). */
+export type VerifyBasis = "anchor" | "jev" | "ai";
 
 /** Valores canônicos de status (ordem de exibição). */
 export const VERIFY_STATUSES: readonly VerifyStatus[] = [
@@ -121,21 +121,24 @@ export function verifyLocal(
 }
 
 /**
- * Tier 1 — aplica a confirmação do Jev aos casos ambíguos.
+ * Tier 1 genérico — aplica confirmações externas (Jev ou IA) aos casos ambíguos.
  * `confidence[id] >= threshold` ⇒ a violação persiste; abaixo ⇒ resolvida.
  * Ids sem resposta mantêm o provisório local (fail-open). Devolve o nº aplicado.
+ *
+ * `basis` identifica a fonte da decisão (`jev` ou `ai`).
  */
-export function applyJev(
+export function applyConfidence(
 	entries: VerifyEntry[],
 	confidence: Map<string, number>,
 	threshold: number,
+	basis: VerifyBasis = "jev",
 ): number {
 	let applied = 0;
 	for (const entry of entries) {
 		if (!entry.ambiguous) continue;
 		const value = confidence.get(entry.id);
 		if (value === undefined) continue;
-		entry.basis = "jev";
+		entry.basis = basis;
 		entry.confidence = value;
 		entry.status = value >= threshold ? "persisting" : "resolved";
 		applied++;
@@ -143,6 +146,15 @@ export function applyJev(
 	return applied;
 }
 
+/** Compatibilidade: confirmação via Jev. */
+export function applyJev(
+	entries: VerifyEntry[],
+	confidence: Map<string, number>,
+	threshold: number,
+): number {
+	return applyConfidence(entries, confidence, threshold, "jev");
+}
+
 export type VerifySummary = Record<VerifyStatus, number>;
 
 /** Contagem por status. */

package/src/harness/README.md

@@ -0,0 +1,15 @@
+# `src/harness` — harness nativo do houndsman
+
+Este diretório é o **runtime de agentes do próprio houndsman** (`houndsman hunt`):
+tools read-only, investigação, máquina de estados e o agente revisor.
+
+> O **harness externo** (skill `/houndsman` para ClaudeCode/Copilot/agents) continua em
+> `src/skill/`. Os dois coexistem; o nativo é opt-in.
+
+Regras de dependência:
+
+- `harness/` pode importar `core/` (inclusive `core/ai`).
+- `core/` **nunca** importa `harness/`.
+- `cli/` importa ambos.
+
+Documentação detalhada: [`docs/HARNESS.md`](../../docs/HARNESS.md).

package/src/harness/agent/agent-context.ts

@@ -0,0 +1,33 @@
+/**
+ * Contexto de um agente de revisão (um watchdog).
+ */
+
+import type { AstAnalysis, AstImpact } from "../../core/ast/types";
+import type { DiffSource } from "../../core/diff-source";
+import type { Watchdog } from "../../core/domain/watchdog";
+import type { WatchdogRenderContext } from "../../core/types";
+import type { RuleAnalysis } from "../investigation/rule-analyzer";
+
+/** Dados imutáveis entregues ao agente. */
+export type AgentContext = {
+	watchdog: Watchdog;
+	projectName: string;
+	branch: string;
+	/** Arquivos do domínio (dentro do orçamento). */
+	files: readonly string[];
+	/** Arquivos do domínio fora do orçamento (não ler; registrar em skipped). */
+	overflow: readonly string[];
+	deleted: readonly string[];
+	docs: readonly string[];
+	context?: WatchdogRenderContext | null;
+	ast: ReadonlyMap<string, AstAnalysis>;
+	impact?: AstImpact;
+	/** Caminho de saída do findings (staging). */
+	outputPath: string;
+	maxSteps: number;
+	maxCalls: number;
+	repoRoot: string;
+	diff: DiffSource;
+	/** Análises determinísticas das regras do watchdog. */
+	rules: readonly RuleAnalysis[];
+};

package/src/harness/agent/agent-errors.ts

@@ -0,0 +1,30 @@
+/**
+ * Erros do harness nativo.
+ */
+
+/** Falha de configuração/execução do agente. */
+export class AgentError extends Error {
+	constructor(
+		message: string,
+		readonly watchdogId?: string,
+	) {
+		super(message);
+		this.name = "AgentError";
+	}
+}
+
+/** Orçamento de IA/tools esgotado durante a investigação. */
+export class AgentBudgetError extends AgentError {
+	constructor(message: string, watchdogId?: string) {
+		super(message, watchdogId);
+		this.name = "AgentBudgetError";
+	}
+}
+
+/** Saída do modelo inválida após as tentativas permitidas. */
+export class AgentOutputError extends AgentError {
+	constructor(message: string, watchdogId?: string) {
+		super(message, watchdogId);
+		this.name = "AgentOutputError";
+	}
+}

package/src/harness/agent/agent-factory.ts

@@ -0,0 +1,45 @@
+/**
+ * Factory de agentes — injeta provider, tools e limites resolvidos.
+ */
+
+import type { ModelProvider } from "../../core/ai";
+import type { AstService } from "../../core/ast/service";
+import type { HarnessConfig } from "../config/harness-config";
+import type { ToolPolicy } from "../tools/tool-policy";
+import type { ToolRegistry } from "../tools/tool-registry";
+import type { AgentContext } from "./agent-context";
+import type { AgentReporter } from "./agent-reporter";
+import { ReviewAgent } from "./review-agent";
+
+/** Dependências compartilhadas por todos os agentes. */
+export type AgentFactoryDeps = {
+	provider: ModelProvider;
+	registry: ToolRegistry;
+	policy?: ToolPolicy;
+	reporter: AgentReporter;
+	config: HarnessConfig;
+	ast: AstService;
+	readFile?: (path: string) => string | null;
+};
+
+/** Cria `ReviewAgent`s a partir do contexto de cada watchdog. */
+export class AgentFactory {
+	constructor(private readonly deps: AgentFactoryDeps) {}
+
+	/** Instancia um agente para o contexto. */
+	create(context: AgentContext): ReviewAgent {
+		const { config } = this.deps;
+		return new ReviewAgent({
+			context,
+			provider: this.deps.provider,
+			registry: this.deps.registry,
+			policy: this.deps.policy,
+			reporter: this.deps.reporter,
+			maxOutputTokens: config.maxOutputTokensFor(context.watchdog.id),
+			temperature: config.temperature,
+			timeoutMs: config.timeoutMs,
+			ast: this.deps.ast,
+			readFile: this.deps.readFile,
+		});
+	}
+}

package/src/harness/agent/agent-reporter.ts

@@ -0,0 +1,34 @@
+/**
+ * Reporter de progresso de um agente.
+ *
+ * O journal é sempre coletado (`harness-transcript.json`); o console é opcional.
+ */
+
+import type { LoggerLike } from "../../core/logging";
+import { ReviewJournal } from "../investigation/review-journal";
+
+/** Interface de progresso. */
+export interface AgentReporter {
+	readonly journal: ReviewJournal;
+	progress(message: string): void;
+}
+
+/** Reporter silencioso (testes). */
+export class SilentReporter implements AgentReporter {
+	readonly journal = new ReviewJournal();
+
+	progress(): void {
+		// intencionalmente silencioso
+	}
+}
+
+/** Reporter apoiado no logger único do CLI. */
+export class LoggerReporter implements AgentReporter {
+	readonly journal = new ReviewJournal();
+
+	constructor(private readonly logger: LoggerLike) {}
+
+	progress(message: string): void {
+		this.logger.progress(message);
+	}
+}

package/src/harness/agent/agent-result.ts

@@ -0,0 +1,16 @@
+/**
+ * Resultado de um agente (watchdog).
+ */
+
+import type { AiUsage } from "../../core/ai";
+import type { WatchdogReport } from "../../core/report-builder";
+
+/** Resultado da execução de um watchdog. */
+export type AgentResult = {
+	watchdogId: string;
+	status: "done" | "skipped" | "failed";
+	report?: WatchdogReport;
+	usage: AiUsage;
+	error?: string;
+	reason?: string;
+};

package/src/harness/agent/agent-runner.ts

@@ -0,0 +1,32 @@
+/**
+ * Executor de um agente — retry curto para falhas transitórias.
+ *
+ * 429/5xx/timeout são tentados uma vez mais; 4xx não. O resultado é sempre
+ * estruturado (`failed` com motivo), nunca uma exceção solta.
+ */
+
+import type { AgentContext } from "./agent-context";
+import type { AgentFactory } from "./agent-factory";
+import type { AgentResult } from "./agent-result";
+import type { ReviewAgentOutcome } from "./review-agent";
+
+/** Executor com retry. */
+export class AgentRunner {
+	constructor(private readonly factory: AgentFactory) {}
+
+	/** Executa um agente (com uma retentativa em falha transitória). */
+	async run(context: AgentContext): Promise<ReviewAgentOutcome> {
+		const first = await this.factory.create(context).run();
+		if (first.status !== "failed" || !isTransient(first.error)) return first;
+		const second = await this.factory.create(context).run();
+		return second;
+	}
+}
+
+/** Erro transitório (rate limit, 5xx, timeout). */
+function isTransient(message: string | undefined): boolean {
+	if (!message) return false;
+	return /429|5\d\d|timeout|temporar|ECONNRESET|ETIMEDOUT|abort/i.test(message);
+}
+
+export type { AgentResult };

package/src/harness/agent/agent-scheduler.ts

@@ -0,0 +1,37 @@
+/**
+ * Scheduler de agentes — concorrência limitada (default 2).
+ */
+
+import type { AgentContext } from "./agent-context";
+import type { AgentReporter } from "./agent-reporter";
+import type { AgentRunner } from "./agent-runner";
+import type { ReviewAgentOutcome } from "./review-agent";
+
+/** Executa agentes com concorrência limitada. */
+export class AgentScheduler {
+	constructor(
+		private readonly runner: AgentRunner,
+		private readonly concurrency: number,
+		private readonly reporter?: AgentReporter,
+	) {}
+
+	/** Executa todos os contextos e devolve os resultados na ordem original. */
+	async run(contexts: readonly AgentContext[]): Promise<ReviewAgentOutcome[]> {
+		const results = new Array<ReviewAgentOutcome>(contexts.length);
+		let cursor = 0;
+		const workers = Math.max(1, Math.min(this.concurrency, contexts.length));
+
+		const worker = async (): Promise<void> => {
+			while (cursor < contexts.length) {
+				const index = cursor++;
+				const context = contexts[index];
+				if (!context) return;
+				this.reporter?.progress(`[${context.watchdog.id}] investigando...`);
+				results[index] = await this.runner.run(context);
+			}
+		};
+
+		await Promise.all(Array.from({ length: workers }, () => worker()));
+		return results;
+	}
+}