@payconductor/houndsman 0.5.0 → 0.6.0

package/src/harness/tools/tool-middleware.ts

@@ -0,0 +1,105 @@
+/**
+ * Middleware de execução das tools.
+ *
+ * Cadeia: validação Zod → cache → budget → execução → limites → redaction →
+ * auditoria. Toda tool passa por aqui; nenhuma executa direto.
+ */
+
+import type { ToolResult } from "./agent-tool";
+import { limitText, TOOL_LIMITS } from "./result-limiter";
+import { redactSecrets, redactValue } from "./secret-redactor";
+import { ToolCache } from "./tool-cache";
+import { ToolBudgetError } from "./tool-call-budget";
+import type { ToolContext } from "./tool-context";
+import type { AgentStateName } from "./tool-policy";
+import type { RegisteredTool } from "./tool-registry";
+
+/** Executor com validação, cache, budget, limite e auditoria. */
+export class ToolMiddleware {
+	async run(
+		tool: RegisteredTool,
+		input: unknown,
+		context: ToolContext,
+		state: AgentStateName,
+	): Promise<ToolResult<unknown>> {
+		const parsed = tool.inputSchema.safeParse(input);
+		if (!parsed.success) {
+			return {
+				ok: false,
+				error: `input inválido para '${tool.metadata.name}': ${parsed.error.message}`,
+			};
+		}
+
+		const maxPerAgent = tool.metadata.maxCallsPerAgent;
+		if (
+			maxPerAgent !== undefined &&
+			context.state.callsOf(tool.metadata.name) >= maxPerAgent
+		) {
+			return {
+				ok: false,
+				error: `Limite de ${maxPerAgent} chamada(s) da tool '${tool.metadata.name}'.`,
+			};
+		}
+
+		const key = ToolCache.key(tool.metadata.name, parsed.data);
+		const cached = context.cache.get<ToolResult<unknown>>(key);
+		if (cached) return cached;
+
+		try {
+			context.budget.consume(tool.metadata.name);
+		} catch (error) {
+			return {
+				ok: false,
+				error: error instanceof ToolBudgetError ? error.message : String(error),
+			};
+		}
+
+		const started = performance.now();
+		try {
+			// Contravariância: a tool concreta aceita seu próprio input.
+			const result = (await tool.execute(
+				parsed.data as never,
+				context,
+			)) as ToolResult<unknown>;
+			const limited = limitResult(result);
+			const redacted = redactValue(limited);
+			context.cache.set(key, redacted, tool.metadata.cacheTtlMs ?? 60_000);
+			context.state.recordToolCall(tool.metadata.name);
+			const stored = (redacted.evidence ?? []).map(
+				(evidence) =>
+					context.state.getEvidence(evidence.id) ??
+					context.state.addEvidence(evidence),
+			);
+			if (stored.length > 0) redacted.evidence = stored;
+			context.logger.journal.recordToolCall(
+				tool.metadata.name,
+				state,
+				performance.now() - started,
+				redacted,
+			);
+			return redacted;
+		} catch (error) {
+			const message = redactSecrets(
+				error instanceof Error ? error.message : String(error),
+			);
+			context.logger.journal.recordToolCall(
+				tool.metadata.name,
+				state,
+				performance.now() - started,
+				{ ok: false, error: message },
+			);
+			return { ok: false, error: message };
+		}
+	}
+}
+
+/** Aplica tetos de texto ao resultado da tool. */
+function limitResult(result: ToolResult<unknown>): ToolResult<unknown> {
+	const copy: ToolResult<unknown> = { ...result };
+	if (typeof copy.data === "string") {
+		const limited = limitText(copy.data, TOOL_LIMITS.maxBytes);
+		copy.data = limited.text;
+		if (limited.truncated) copy.truncated = true;
+	}
+	return copy;
+}

package/src/harness/tools/tool-policy.ts

@@ -0,0 +1,51 @@
+/**
+ * Política de tools por estado do agente.
+ *
+ * O modelo só vê as tools permitidas no estado atual. Adicionar uma tool não
+ * exige alterar o agente — basta declarar capabilities compatíveis.
+ */
+
+import type { ToolCapability, ToolMetadata } from "./agent-tool";
+
+/** Estados da máquina de investigação. */
+export type AgentStateName = "ORIENT" | "PLAN" | "INVESTIGATE" | "VERIFY" | "CONCLUDE";
+
+/** Capabilities liberadas por estado. */
+const DEFAULT_POLICY: Record<AgentStateName, readonly ToolCapability[]> = {
+	ORIENT: ["read", "outline", "ast", "impact", "rules", "symbol"],
+	PLAN: ["rules", "symbol", "impact", "ast"],
+	INVESTIGATE: [
+		"read",
+		"search",
+		"outline",
+		"symbol",
+		"references",
+		"ast",
+		"impact",
+		"rules",
+		"tests",
+		"docs",
+	],
+	VERIFY: ["symbol", "references", "search", "read"],
+	CONCLUDE: [],
+};
+
+/** Política substituível. */
+export class ToolPolicy {
+	private readonly policy: Record<AgentStateName, readonly ToolCapability[]>;
+
+	constructor(policy: Partial<Record<AgentStateName, readonly ToolCapability[]>> = {}) {
+		this.policy = { ...DEFAULT_POLICY, ...policy };
+	}
+
+	/** Capabilities liberadas no estado. */
+	capabilities(state: AgentStateName): readonly ToolCapability[] {
+		return this.policy[state];
+	}
+
+	/** `true` se a tool pode ser usada no estado. */
+	allows(state: AgentStateName, metadata: ToolMetadata): boolean {
+		const allowed = this.policy[state];
+		return metadata.capabilities.some((capability) => allowed.includes(capability));
+	}
+}

package/src/harness/tools/tool-registry.ts

@@ -0,0 +1,112 @@
+/**
+ * Registro das tools do harness.
+ *
+ * Módulos registram tools; nomes duplicados falham no startup. O registry gera
+ * as descrições do prompt a partir do metadata (nunca hardcoded).
+ */
+
+import type { AiTool } from "../../core/ai";
+import type {
+	RegisterableTool,
+	ToolContext,
+	ToolMetadata,
+	ToolModule,
+	ToolRegistryLike,
+	ToolResult,
+} from "./agent-tool";
+import type { ToolMiddleware } from "./tool-middleware";
+import type { AgentStateName, ToolPolicy } from "./tool-policy";
+
+/** Tool registrada, com a forma type-erased aceita pelo middleware. */
+export type RegisteredTool = RegisterableTool;
+
+/** Registry de tools. */
+export class ToolRegistry implements ToolRegistryLike {
+	private readonly tools = new Map<string, RegisteredTool>();
+
+	/** Registra uma tool; nome duplicado é erro de configuração. */
+	registerTool(tool: RegisterableTool): void {
+		if (this.tools.has(tool.metadata.name)) {
+			throw new Error(`Tool duplicada: '${tool.metadata.name}'.`);
+		}
+		this.tools.set(tool.metadata.name, tool);
+	}
+
+	/** Registra um módulo (agrupa tools). */
+	registerModule(module: ToolModule): void {
+		module.register(this);
+	}
+
+	/** Tool por nome. */
+	get(name: string): RegisteredTool | undefined {
+		return this.tools.get(name);
+	}
+
+	/** Todas as tools (ordem de registro). */
+	list(): RegisteredTool[] {
+		return [...this.tools.values()];
+	}
+
+	/** Tools com uma capability. */
+	listByCapability(capability: string): RegisteredTool[] {
+		return this.list().filter((tool) =>
+			(tool.metadata.capabilities as readonly string[]).includes(capability),
+		);
+	}
+
+	/** Descrição compacta das tools permitidas (para o prompt). */
+	describeForPrompt(policy: ToolPolicy, state: AgentStateName): string {
+		return this.list()
+			.filter((tool) => policy.allows(state, tool.metadata))
+			.map(
+				(tool) =>
+					`- ${tool.metadata.name} (${tool.metadata.capabilities.join(", ")}): ${tool.metadata.description}`,
+			)
+			.join("\n");
+	}
+
+	/** Converte as tools permitidas no formato do modelo. */
+	toModelTools(
+		policy: ToolPolicy,
+		state: AgentStateName,
+		context: ToolContext,
+		middleware: ToolMiddleware,
+	): Record<string, AiTool> {
+		const entries = this.list()
+			.filter((tool) => policy.allows(state, tool.metadata))
+			.map((tool) => [
+				tool.metadata.name,
+				{
+					name: tool.metadata.name,
+					description: tool.metadata.description,
+					inputSchema: tool.inputSchema,
+					execute: async (input: unknown): Promise<string> => {
+						const result = await middleware.run(tool, input, context, state);
+						return JSON.stringify(result);
+					},
+				},
+			]);
+		return Object.fromEntries(entries);
+	}
+
+	/** Metadados registrados. */
+	metadata(): ToolMetadata[] {
+		return this.list().map((tool) => tool.metadata);
+	}
+
+	/** Executa uma tool com middleware (usado nos testes). */
+	execute(
+		name: string,
+		input: unknown,
+		context: ToolContext,
+		middleware: ToolMiddleware,
+		state: AgentStateName = "INVESTIGATE",
+	): Promise<ToolResult<unknown>> {
+		const tool = this.tools.get(name);
+		if (!tool)
+			return Promise.resolve({ ok: false, error: `tool desconhecida: ${name}` });
+		return middleware.run(tool, input, context, state) as Promise<
+			ToolResult<unknown>
+		>;
+	}
+}

package/src/harness/tools/tool-result.ts

@@ -0,0 +1,15 @@
+/**
+ * Resultado padrão de uma tool (reexport de contrato).
+ */
+
+export type { ToolResult } from "./agent-tool";
+
+/** Resultado de sucesso. */
+export function ok<T>(data: T, extra: Record<string, unknown> = {}) {
+	return { ok: true as const, data, ...extra };
+}
+
+/** Resultado de erro estruturado. */
+export function fail(error: string) {
+	return { ok: false as const, error };
+}

package/src/harness/tools/toolbox.ts

@@ -0,0 +1,36 @@
+/**
+ * Visão de tools por agente (registry + policy + middleware).
+ *
+ * O agente pede `toModelTools(state)` e recebe apenas o que pode usar naquele
+ * estado, já com cache/budget/redaction aplicados.
+ */
+
+import type { AiTool } from "../../core/ai";
+import type { ToolContext } from "./tool-context";
+import type { ToolMiddleware } from "./tool-middleware";
+import type { AgentStateName, ToolPolicy } from "./tool-policy";
+import type { ToolRegistry } from "./tool-registry";
+
+/** Fachada por agente. */
+export class Toolbox {
+	constructor(
+		readonly registry: ToolRegistry,
+		readonly policy: ToolPolicy,
+		readonly middleware: ToolMiddleware,
+	) {}
+
+	/** Tools permitidas no estado, no formato do modelo. */
+	toModelTools(state: AgentStateName, context: ToolContext): Record<string, AiTool> {
+		return this.registry.toModelTools(this.policy, state, context, this.middleware);
+	}
+
+	/** Descrição das tools permitidas (prompt). */
+	describe(state: AgentStateName): string {
+		return this.registry.describeForPrompt(this.policy, state);
+	}
+
+	/** Executa uma tool fora do modelo (testes/uso determinístico). */
+	execute(name: string, input: unknown, context: ToolContext, state: AgentStateName) {
+		return this.registry.execute(name, input, context, this.middleware, state);
+	}
+}

package/src/harness/validation/finding-validator.ts

@@ -0,0 +1,119 @@
+/**
+ * Validação final do relatório de um watchdog.
+ *
+ * Descarta findings que citam regra inexistente, arquivo fora do domínio/impacto,
+ * overflow (não lido) ou linha inválida. `reviewedFiles` só aceita arquivos
+ * existentes; overflow entra em `skipped`.
+ */
+
+import { readFileSync } from "node:fs";
+import type { WatchdogReport } from "../../core/report-builder";
+import { emergentText, isEmergentRule } from "../../core/rule-text";
+import { SEVERITY_ORDER, type Severity } from "../../core/types";
+import { capSeverity } from "../investigation/finding-critic";
+
+/** Contexto de validação. */
+export type ValidationContext = {
+	watchdogId: string;
+	knownRules: ReadonlySet<string>;
+	allowedFiles: ReadonlySet<string>;
+	overflow: ReadonlySet<string>;
+	readFile: (path: string) => string | null;
+	/** Aceita findings `Lógica:`/`Domínio:` fora das regras. */
+	allowEmergentFindings?: boolean;
+};
+
+/** Resultado da validação. */
+export type ValidationResult = {
+	report: WatchdogReport;
+	dropped: { finding: string; reason: string }[];
+};
+
+const SEVERITIES = new Set<string>(SEVERITY_ORDER);
+
+/** Validador de relatórios. */
+export class FindingValidator {
+	private readonly context: ValidationContext;
+
+	constructor(context: ValidationContext) {
+		this.context = context;
+	}
+
+	/** Valida/normaliza o relatório. */
+	validate(report: WatchdogReport): ValidationResult {
+		const dropped: { finding: string; reason: string }[] = [];
+		const findings = report.findings
+			.filter((finding) => {
+				const reason = this.reasonToDrop(finding);
+				if (!reason) return true;
+				dropped.push({
+					finding: `${finding.file}:${finding.line ?? "?"}`,
+					reason,
+				});
+				return false;
+			})
+			.map((finding) =>
+				isEmergentRule(finding.rule)
+					? {
+							...finding,
+							severity: capSeverity(finding.severity, "attention"),
+						}
+					: finding,
+			);
+
+		const reviewedFiles = report.reviewedFiles
+			.filter((file) => this.context.allowedFiles.has(file))
+			.filter((file) => this.context.readFile(file) !== null);
+
+		const skipped = new Set(report.skipped);
+		for (const file of this.context.overflow) skipped.add(`${file} (budget)`);
+
+		return {
+			report: {
+				watchdogId: this.context.watchdogId,
+				reviewedFiles: [...new Set(reviewedFiles)],
+				skipped: [...skipped],
+				findings,
+			},
+			dropped,
+		};
+	}
+
+	/** Motivo para descartar (ou `null` se válido). */
+	private reasonToDrop(finding: {
+		rule: string;
+		severity: Severity;
+		file: string;
+		line?: number;
+	}): string | null {
+		if (isEmergentRule(finding.rule)) {
+			if (!this.context.allowEmergentFindings)
+				return "finding emergente desabilitado";
+			if (!emergentText(finding.rule)) return "finding emergente sem descrição";
+		} else if (!this.context.knownRules.has(finding.rule.trim())) {
+			return "regra inexistente";
+		}
+		if (!SEVERITIES.has(finding.severity)) return "severidade inválida";
+		if (this.context.overflow.has(finding.file)) return "arquivo fora do orçamento";
+		if (!this.context.allowedFiles.has(finding.file))
+			return "arquivo fora do domínio";
+		const content = this.context.readFile(finding.file);
+		if (content === null) return "arquivo ausente";
+		if (finding.line !== undefined) {
+			const total = content.split("\n").length;
+			if (finding.line < 1 || finding.line > total) return "linha fora do arquivo";
+		}
+		return null;
+	}
+}
+
+/** Leitor de arquivos padrão (UTF-8; `null` se ausente). */
+export function defaultFileReader(root: string): (path: string) => string | null {
+	return (path: string) => {
+		try {
+			return readFileSync(`${root}/${path}`, "utf8");
+		} catch {
+			return null;
+		}
+	};
+}

package/src/index.ts

@@ -5,13 +5,53 @@
  * (`houndsman.config.ts`): watchdogs, tipos e helpers de autoria.
  */
 
+export type {
+	AiResult,
+	AiTool,
+	AiUsage,
+	ModelProvider,
+	ModelRequest,
+	ModelResponse,
+} from "./core/ai";
+export {
+	AiBriefEnricher,
+	AiClassifier,
+	AiClient,
+	AiContextSummarizer,
+	AiPreAnalyzer,
+	AiUsageBudget,
+	AiUsageRecorder,
+	AiVerifier,
+	ModelFactory,
+} from "./core/ai";
 export { ArgParser } from "./core/arg-parser";
 export { assetPath, OUTPUT_FORMAT_FILE } from "./core/assets";
+export { computeDelta, emptyDelta, parseHunks } from "./core/ast/diff";
+export { buildImpact, resolveImport } from "./core/ast/impact";
+export { AstParser, languageForPath } from "./core/ast/parser";
+export { AstService } from "./core/ast/service";
+export type {
+	AstAnalysis,
+	AstDelta,
+	AstEntry,
+	AstExport,
+	AstFacts,
+	AstFileBrief,
+	AstImpact,
+	AstImport,
+	AstLanguage,
+	AstSymbol,
+	AstSymbolKind,
+} from "./core/ast/types";
 export { defaultRenderBrief, PROCEDURE, renderBrief } from "./core/brief";
 export type { FindingsCommandResult } from "./core/commands/findings";
 export { runFindingsCommand, runVerifyCommand } from "./core/commands/findings";
 export { ProjectScaffolder } from "./core/commands/scaffold";
 export type {
+	AiProviderKind,
+	HoundsmanAi,
+	HoundsmanAiFeatures,
+	HoundsmanAst,
 	HoundsmanBudgets,
 	HoundsmanConcurrency,
 	HoundsmanConfig,
@@ -20,6 +60,8 @@ export type {
 } from "./core/config";
 export {
 	DEFAULT_ALWAYS_INCLUDE_DOCS,
+	DEFAULT_AST_MAX_FILE_BYTES,
+	DEFAULT_AST_MAX_IMPACT_FILES,
 	DEFAULT_JEV_CONCURRENCY,
 	DEFAULT_MAX_FILES_PER_BRIEF,
 	defineHoundsmanConfig,
@@ -47,6 +89,8 @@ export { buildCarryover, mergeCarryover } from "./core/engine/carryover";
 export { HoundsmanEngine } from "./core/engine/houndsman-engine";
 export { ReviewScopeResolver } from "./core/engine/review-scope";
 export { ReviewSession } from "./core/engine/review-session";
+export type { HoundsmanEnv } from "./core/env";
+export { ENV_NAMES, env, readEnv } from "./core/env";
 export {
 	churnOf,
 	classifyEntries,
@@ -159,6 +203,7 @@ export type {
 	FileStatus,
 	FileStatusMap,
 	Rule,
+	RuleHints,
 	Severity,
 	WatchdogDefinition,
 	WatchdogMeta,
@@ -172,6 +217,7 @@ export {
 	SEVERITY_ORDER,
 	severityRank,
 } from "./core/types";
+export { applyConfidence, applyJev, summarizeVerify, verifyLocal } from "./core/verify";
 export {
 	findWatchdog,
 	getWatchdog,

package/src/server/client/utils/constants.ts

@@ -91,6 +91,12 @@ const KIND_ORDER: ArtifactKind[] = [
 	"manifest",
 	"classification",
 	"candidates",
+	"ast",
+	"ast-impact",
+	"ai",
+	"ai-usage",
+	"ai-brief",
+	"harness-transcript",
 	"context",
 	"context-brief",
 	"context-summary",
@@ -109,11 +115,17 @@ const GROUP_BY_KIND: Record<ArtifactKind, { key: string; label: string; order: n
 		manifest: { key: "core", label: "Núcleo da revisão", order: 3 },
 		classification: { key: "core", label: "Núcleo da revisão", order: 3 },
 		candidates: { key: "core", label: "Núcleo da revisão", order: 3 },
-		context: { key: "context", label: "Contexto da PR", order: 4 },
-		"context-brief": { key: "context", label: "Contexto da PR", order: 4 },
-		"context-summary": { key: "context", label: "Contexto da PR", order: 4 },
-		"finding-report": { key: "other", label: "Outros", order: 5 },
-		other: { key: "other", label: "Outros", order: 5 },
+		ast: { key: "core", label: "Núcleo da revisão", order: 3 },
+		"ast-impact": { key: "core", label: "Núcleo da revisão", order: 3 },
+		ai: { key: "ai", label: "IA e harness", order: 4 },
+		"ai-usage": { key: "ai", label: "IA e harness", order: 4 },
+		"ai-brief": { key: "ai", label: "IA e harness", order: 4 },
+		"harness-transcript": { key: "ai", label: "IA e harness", order: 4 },
+		context: { key: "context", label: "Contexto da PR", order: 5 },
+		"context-brief": { key: "context", label: "Contexto da PR", order: 5 },
+		"context-summary": { key: "context", label: "Contexto da PR", order: 5 },
+		"finding-report": { key: "other", label: "Outros", order: 6 },
+		other: { key: "other", label: "Outros", order: 6 },
 	};
 
 /** Rótulo curto do tipo (badge do item). */
@@ -126,6 +138,12 @@ export const ARTIFACT_KIND_LABELS: Record<ArtifactKind, string> = {
 	manifest: "manifesto",
 	classification: "classificação",
 	candidates: "jev",
+	ast: "ast",
+	"ast-impact": "impacto",
+	ai: "ia",
+	"ai-usage": "uso ia",
+	"ai-brief": "plano ia",
+	"harness-transcript": "transcript",
 	context: "contexto",
 	"context-brief": "brief ctx",
 	"context-summary": "resumo ctx",
@@ -159,6 +177,10 @@ export function describeArtifact(meta: ArtifactMeta): string {
 			return "Classificação do diff: watchdogs ativados por arquivo, status (A/M/D/R) e churn.";
 		case "candidates":
 			return "Indícios da pré-análise Jev (regra + arquivo + confiança) — não são achados.";
+		case "ast":
+			return "Fatos estruturais e delta por arquivo (símbolos, imports, exports e assinaturas).";
+		case "ast-impact":
+			return "Impacto reverso: arquivos que importam os alterados e exports públicos modificados.";
 		case "context":
 			return "Payload bruto da PR coletado via `gh` (ou marcador de indisponível).";
 		case "context-brief":

package/src/server/client/utils/types.ts

@@ -64,6 +64,12 @@ export type ArtifactKind =
 	| "resume"
 	| "domain-review"
 	| "verify"
+	| "ast"
+	| "ast-impact"
+	| "ai"
+	| "ai-usage"
+	| "ai-brief"
+	| "harness-transcript"
 	| "other";
 
 /** Metadados de artefato retornados pela API (sem conteúdo). */

package/src/server/index.ts

@@ -14,6 +14,7 @@ import {
 	type GhRunner,
 	type SubmitSelection,
 } from "../core/github-review";
+import { logger } from "../core/logging";
 import { createStorage } from "../core/storage/factory";
 import { resolveRepoIdentity } from "../core/storage/repo-identity";
 import type { RepoIdentity, StorageProvider } from "../core/storage/types";
@@ -190,8 +191,8 @@ export class HoundsmanServer {
 		try {
 			this.runs.maintain();
 		} catch (error) {
-			console.warn(
-				`[houndsman] VACUUM falhou (seguindo sem compactar): ${
+			logger.warn(
+				`VACUUM falhou (seguindo sem compactar): ${
 					error instanceof Error ? error.message : String(error)
 				}`,
 			);

package/src/skill/OUTPUT-FORMAT.md

@@ -70,3 +70,15 @@ staging global da review:
 - Um achado por regra violada; não agrupar regras diferentes.
 - `file:line` sempre que possível; `evidence` quando o achado não é óbvio.
 - Não inventar achados — se não houver violação, o array fica vazio.
+
+## Findings emergentes (opt-in)
+
+Quando o watchdog declara `allowEmergentFindings: true`, você pode reportar falhas de
+**lógica** ou **domínio** que não correspondem a uma regra explícita usando os prefixos
+reservados:
+
+- `Lógica: <descrição>` — nome/contrato vs comportamento, fluxos, estados, bordas.
+- `Domínio: <descrição>` — transições, idempotência, invariantes, arredondamento, timezone.
+
+Esses findings continuam exigindo `evidence` e têm severidade máxima `attention`. Sem o
+opt-in, todo finding precisa citar uma regra existente.

package/src/skill/SETUP.md

@@ -7,8 +7,11 @@ no seu projeto é **autocontida** — não exige nenhuma dependência local do p
 
 - **Bun** — o CLI e o motor usam a runtime Bun (execução de TS, `Bun.spawnSync`).
 - **git** — o diff usa `git diff <base>...<head> --name-status`.
-- Opcional: **`gh`** (contexto da PR) e **`TYPESAFE_API_KEY`** (pré-análise Jev). O pipeline
-  segue normalmente sem eles.
+- **gh** (Opcional) — Obtém contexto da PR e dispara comentários para o GitHub
+- **`HOUNDSMAN_TYPE_SAFE_API_KEY`** (opcional) — pré-análise Jev.
+- **`HOUNDSMAN_DEEP_SEEK_API_KEY`** (opcional) — IA própria do `hunt` nativo e das features de IA.
+- **`HOUNDSMAN_OPENAI_API_KEY`** / **`HOUNDSMAN_ANTHROPIC_API_KEY`** (opcional) — apenas se
+  `ai.provider` for `openai`/`anthropic`.
 
 ## Instalação (global)
 
@@ -87,6 +90,7 @@ Definido em `src/core/config.ts` (pacote) e espelhado em `.houndsman/core/types.
 | `alwaysIncludeDocs` | Docs sempre presentes nos briefs (default `["AGENTS.md"]`). |
 | `budgets` | **Opcional** — teto de arquivos por brief (`maxFilesPerBrief`, default `40`); o excedente vira "fora do orçamento" (registrar em `skipped`). |
 | `concurrency` | **Opcional** — chamadas Jev simultâneas (`jev`, default `5`). |
+| `ast` | **Opcional** — AST determinístico para TS/JS (`enabled`, `maxFileBytes`, `maxImpactFiles`, `languages`, `aliases`). Default: ligado; falhas são fail-open. |
 
 > O motor **não contém** ids, paths ou regras do projeto — tudo chega por `HoundsmanConfig`,
 > carregado em runtime a partir de `houndsman.config.ts` (ou `--config <path>`).