@payconductor/houndsman 0.5.0 → 0.7.0

package/src/core/brief.ts

@@ -5,6 +5,7 @@
  * específico do domínio vive nas regras do watchdog (`rules`).
  */
 
+import type { AstDelta } from "./ast/types";
 import {
 	type Rule,
 	SEVERITY_EMOJI,
@@ -117,6 +118,141 @@ function deletedSection(args: WatchdogRenderArgs, def: WatchdogDefinition): stri
 	];
 }
 
+/** Escapa um valor para uso em code-span (evita quebrar o markdown). */
+function inlineCode(value: string): string {
+	return `\`${value.replace(/`/g, "'")}\``;
+}
+
+/** Trunca um texto longo (assinatura) para o brief. */
+function shorten(value: string, max = 120): string {
+	const normalized = value.replace(/\s+/g, " ").trim();
+	return normalized.length > max ? `${normalized.slice(0, max - 1)}…` : normalized;
+}
+
+/** Linhas de um delta estrutural (compactas e determinísticas). */
+function deltaLines(delta: AstDelta): string[] {
+	const lines: string[] = [];
+	for (const symbol of delta.addedSymbols.slice(0, 4)) {
+		lines.push(`+ ${inlineCode(symbol.name)} (${symbol.kind})`);
+	}
+	for (const symbol of delta.removedSymbols.slice(0, 4)) {
+		lines.push(`− ${inlineCode(symbol.name)} (${symbol.kind})`);
+	}
+	for (const symbol of delta.modifiedSymbols.slice(0, 4)) {
+		lines.push(`~ ${inlineCode(symbol.name)} (${symbol.kind})`);
+	}
+	for (const change of delta.changedSignatures.slice(0, 3)) {
+		lines.push(
+			`assinatura ${inlineCode(change.name)}: ${inlineCode(shorten(change.before) || "—")} → ${inlineCode(shorten(change.after) || "—")}`,
+		);
+	}
+	if (delta.addedImports.length > 0) {
+		lines.push(
+			`imports + ${delta.addedImports.slice(0, 4).map(inlineCode).join(", ")}`,
+		);
+	}
+	if (delta.removedImports.length > 0) {
+		lines.push(
+			`imports − ${delta.removedImports.slice(0, 4).map(inlineCode).join(", ")}`,
+		);
+	}
+	return lines;
+}
+
+/**
+ * Plano de revisão sugerido por IA — complementa (nunca substitui) as regras.
+ */
+function aiPlanSection(args: WatchdogRenderArgs): string[] {
+	const plan = args.aiPlan;
+	if (!plan) return [];
+	const focus = plan.focus ?? [];
+	const questions = plan.questions ?? [];
+	const risks = plan.risks ?? [];
+	const logic = plan.logic ?? [];
+	const domain = plan.domain ?? [];
+	if (
+		focus.length === 0 &&
+		questions.length === 0 &&
+		risks.length === 0 &&
+		logic.length === 0 &&
+		domain.length === 0
+	) {
+		return [];
+	}
+	const lines = [
+		"## Plano de revisão (IA) — sugestão",
+		"",
+		"> Sugestão automática para orientar a leitura. **Não** substitui as regras",
+		"> do watchdog nem dispensa confirmar cada violação no código.",
+		"",
+	];
+	if (focus.length > 0) {
+		lines.push("**Foco de leitura:**", "");
+		for (const item of focus.slice(0, 5)) lines.push(`- ${item}`);
+		lines.push("");
+	}
+	if (questions.length > 0) {
+		lines.push("**Perguntas de verificação:**", "");
+		for (const item of questions.slice(0, 3)) lines.push(`- ${item}`);
+		lines.push("");
+	}
+	if (risks.length > 0) {
+		lines.push("**Riscos prováveis:**", "");
+		for (const item of risks.slice(0, 3)) lines.push(`- ${item}`);
+		lines.push("");
+	}
+	if (logic.length > 0) {
+		lines.push("**Consistência lógica:**", "");
+		for (const item of logic.slice(0, 3)) lines.push(`- ${item}`);
+		lines.push("");
+	}
+	if (domain.length > 0) {
+		lines.push("**Domínio de negócio:**", "");
+		for (const item of domain.slice(0, 3)) lines.push(`- ${item}`);
+		lines.push("");
+	}
+	return lines;
+}
+
+/**
+ * Estrutura/delta dos arquivos do watchdog (AST). É um mapa para orientar a
+ * leitura — o watchdog confirma no código e não trata como achado.
+ */
+function astSection(args: WatchdogRenderArgs): string[] {
+	const entries = args.ast ?? [];
+	if (entries.length === 0) return [];
+	const lines: string[] = [
+		"## Estrutura (AST)",
+		"",
+		"> Delta estrutural dos arquivos do seu domínio. Use como mapa para",
+		"> priorizar a leitura; **não** é achado por si só.",
+		"",
+	];
+	let rendered = 0;
+	for (const entry of entries) {
+		const parts = deltaLines(entry.delta);
+		if (entry.importers && entry.importers.length > 0) {
+			parts.push(
+				`impacto: ${entry.importers.slice(0, 5).map(inlineCode).join(", ")}` +
+					(entry.importers.length > 5
+						? ` (+${entry.importers.length - 5})`
+						: ""),
+			);
+		}
+		if (parts.length === 0) continue;
+		lines.push(
+			`### ${inlineCode(entry.file)}`,
+			"",
+			...parts.map((part) => `- ${part}`),
+			"",
+		);
+		rendered++;
+		if (rendered >= 12) break;
+	}
+	if (rendered === 0) return [];
+	return lines;
+}
+
 /**
  * Render padrão do brief de um watchdog (ordem estável).
  * `def` é a definição do próprio watchdog (evita ciclo com o registry).
@@ -139,6 +275,8 @@ export function defaultRenderBrief(
 
 	if (args.context) lines.push(...renderBriefContext(args.context));
 
+	lines.push(...aiPlanSection(args));
+	lines.push(...astSection(args));
 	lines.push(...optionalList("Prioridade de leitura", def.reviewFocus));
 	lines.push(
 		"## Regras (por severidade)",

package/src/core/commands/findings.ts

@@ -10,7 +10,10 @@
  * com o UUID interno no banco.
  */
 
+import { AiClient } from "../ai/ai-client";
+import { AiVerifier } from "../ai/features/verifier";
 import { type HoundsmanConfig, resolveJevConcurrency } from "../config";
+import { ENV_NAMES } from "../env";
 import {
 	applyFindingUpdate,
 	FINDING_DECISIONS,
@@ -40,6 +43,7 @@ import {
 } from "../github-review";
 import { VERIFY_FILE } from "../paths";
 import { currentBranch } from "../pr-context";
+import { ProjectConfig } from "../project-config";
 import { BatchPresenter } from "../renderers/batch-presenter";
 import { FindingsPresenter } from "../renderers/findings-presenter";
 import { VerifyPresenter } from "../renderers/verify-presenter";
@@ -485,6 +489,20 @@ export async function runVerifyCommand(
 	}
 }
 
+/** Trecho de ~20 linhas ao redor do finding (entrada da verificação por IA). */
+function snippetsAround(content: string | null, line: number | null): string {
+	if (!content) return "(arquivo indisponível)";
+	const lines = content.replace(/\r\n/g, "\n").split("\n");
+	const center = line && line > 0 ? line : 1;
+	const start = Math.max(1, center - 10);
+	const end = Math.min(lines.length, center + 10);
+	return lines
+		.slice(start - 1, end)
+		.map((text, index) => `${start + index}: ${text}`)
+		.join("\n")
+		.slice(0, 4_000);
+}
+
 async function executeVerify(
 	config: HoundsmanConfig,
 	storage: StorageProvider,
@@ -510,7 +528,7 @@ async function executeVerify(
 		if (parsed.bools.has("--no-jev")) {
 			jevReason = "desativado (--no-jev)";
 		} else if (!jevVerifier.isConfigured()) {
-			jevReason = "TYPESAFE_API_KEY não configurada";
+			jevReason = `${ENV_NAMES.typeSafeApiKey} não configurada`;
 		} else {
 			const byId = new Map(findings.map((finding) => [finding.id, finding]));
 			const outcome = await jevVerifier.verify(
@@ -531,6 +549,44 @@ async function executeVerify(
 		}
 	}
 
+	// Tier 2 — IA opcional para os ambíguos que o Jev não respondeu.
+	let aiChecked = 0;
+	let aiReason: string | undefined;
+	const stillAmbiguous = entries.filter(
+		(entry) => entry.ambiguous && entry.basis === "anchor",
+	);
+	if (stillAmbiguous.length > 0) {
+		const client = new AiClient({ project: new ProjectConfig(config) });
+		const aiVerifier = new AiVerifier(client);
+		if (parsed.bools.has("--no-ai")) {
+			aiReason = "desativado (--no-ai)";
+		} else if (!client.available) {
+			aiReason = "IA não configurada";
+		} else if (!aiVerifier.enabled) {
+			aiReason = "feature ai.features.verify desligada";
+		} else {
+			const readFile = fileReader(process.cwd());
+			const byId = new Map(findings.map((finding) => [finding.id, finding]));
+			const confidence = await aiVerifier.verify({
+				findings: stillAmbiguous.map((entry) => ({
+					id: entry.id,
+					rule: entry.rule,
+					file: entry.file,
+					line: entry.line,
+					message: byId.get(entry.id)?.message ?? entry.message,
+					snippets: snippetsAround(readFile(entry.file), entry.line),
+				})),
+			});
+			aiChecked = verifier.applyConfidence(
+				entries,
+				confidence,
+				JevCandidatesStore.THRESHOLD,
+				"ai",
+			);
+			aiReason = `${aiChecked} caso(s) confirmado(s) pela IA`;
+		}
+	}
+
 	const summary = verifier.summarize(entries);
 	const location = ctx.storage.location(ctx.review.id);
 	ctx.storage.writeArtifact(ctx.review.id, {
@@ -557,6 +613,8 @@ async function executeVerify(
 					summary,
 					jevChecked,
 					jevReason,
+					aiChecked,
+					aiReason,
 					applied,
 					entries,
 				},
@@ -599,18 +657,23 @@ function splitList(raw: string | undefined): string[] {
 		.filter(Boolean);
 }
 
-/** Seleção do envio a partir das flags (`--severity`, `--exec`, `--include-sent`). */
+/** Seleção do envio a partir das flags (`--severity`, `--decision`, `--exec`). */
 function submitSelection(parsed: ParsedArgs): SubmitSelection {
 	const severities = splitList(parsed.values["--severity"]).filter(
 		(value): value is Severity =>
 			(SEVERITY_ORDER as readonly string[]).includes(value),
 	);
+	const decisions = splitList(parsed.values["--decision"]).filter(
+		(value): value is FindingDecision =>
+			(FINDING_DECISIONS as readonly string[]).includes(value),
+	);
 	const execStates = splitList(parsed.values["--exec"]).filter(
 		(value): value is FindingExecState =>
 			(FINDING_EXEC_STATES as readonly string[]).includes(value),
 	);
 	return {
 		severities: severities.length > 0 ? severities : undefined,
+		decisions: decisions.length > 0 ? decisions : undefined,
 		execStates: execStates.length > 0 ? execStates : undefined,
 		includeSent: parsed.bools.has("--include-sent"),
 	};

package/src/core/commands/review.ts

@@ -28,7 +28,9 @@ export function parseReviewArgs(args: string[]): ReviewOptions {
 	if (parser.has("--fail-on-blocking")) opts.failOnBlocking = true;
 	if (parser.has("--clean")) opts.clean = true;
 	if (parser.has("--no-jev")) opts.noJev = true;
+	if (parser.has("--no-ast")) opts.noAst = true;
 	if (parser.has("--full")) opts.full = true;
+	if (parser.has("--no-ai")) opts.noAi = true;
 
 	return opts;
 }

package/src/core/commands/scaffold.ts

@@ -8,14 +8,22 @@
  *   ├── .gitignore          AUTO — ignora core/ (gerado)
  *   ├── core/types.ts       AUTO — snapshot dos tipos + helpers
  *   ├── core/skill/*.md     AUTO — docs do skill (com {{projectName}} resolvido)
+ *   ├── core/grammars/*.wasm AUTO — runtime + grammars do AST
  *   ├── watchdogs/*.ts      USUÁRIO
  *   ├── doc-mappings.ts     USUÁRIO
  *   └── exclusions.ts       USUÁRIO
  */
 
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import {
+	copyFileSync,
+	existsSync,
+	mkdirSync,
+	readdirSync,
+	readFileSync,
+	writeFileSync,
+} from "node:fs";
 import { basename, join } from "node:path";
-import { SKILL_DIR, SKILL_FILE } from "../assets";
+import { GRAMMAR_FILES, grammarPath, SKILL_DIR, SKILL_FILE } from "../assets";
 import { CORE_DIR, CORE_SKILL_DIR, OUTPUT_FORMAT_PATH, PROJECT_DIR } from "../paths";
 
 export type Harness = "agents" | "claude";
@@ -123,11 +131,21 @@ 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. */
 export type ClassifyRule = {
-	type?: "filename" | "content";
+	type?: "filename" | "content" | "symbol" | "import" | "export" | "decorator";
 	value: string;
 };
 
@@ -144,6 +162,10 @@ export type WatchdogDefinition = WatchdogMeta & {
 	id: string;
 	description: string;
 	breakingChange?: boolean;
+	/** Só assume arquivos que nenhum outro watchdog casou. */
+	fallback?: boolean;
+	/** Permite findings emergentes (Lógica:/Domínio:) fora das regras. */
+	allowEmergentFindings?: boolean;
 	reviewFocus?: readonly string[];
 	exclude?: readonly string[];
 };
@@ -182,6 +204,54 @@ export type HoundsmanStorage = {
 	path?: string;
 };
 
+/** Linguagens suportadas pelo AST na primeira fase. */
+export type AstLanguage = "typescript" | "tsx" | "javascript";
+
+/** Configuração do AST determinístico (classificação estrutural, brief e impacto). */
+export type HoundsmanAst = {
+	enabled?: boolean;
+	maxFileBytes?: number;
+	maxImpactFiles?: number;
+	languages?: Record<string, AstLanguage>;
+	aliases?: Record<string, string>;
+};
+
+/** Providers suportados pela camada de IA. */
+export type AiProviderKind = "deepseek" | "openai" | "anthropic";
+
+/** Features de IA do fluxo normal (todas fail-open). */
+export type HoundsmanAiFeatures = {
+	context?: boolean;
+	brief?: boolean;
+	classification?: boolean;
+	preAnalysis?: boolean;
+	verify?: boolean;
+};
+
+/** 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). */
+export type HoundsmanAi = {
+	enabled?: boolean;
+	provider?: AiProviderKind;
+	model?: string;
+	baseURL?: string;
+	concurrency?: number;
+	maxSteps?: number;
+	maxOutputTokens?: number;
+	temperature?: number;
+	timeoutMs?: number;
+	maxCallsPerReview?: number;
+	maxTokensPerReview?: number;
+	features?: HoundsmanAiFeatures;
+	watchdogs?: Record<string, HoundsmanAiWatchdog>;
+};
+
 /** Contrato de configuração do motor. */
 export type HoundsmanConfig<TId extends string = string> = {
 	projectName: string;
@@ -193,6 +263,8 @@ export type HoundsmanConfig<TId extends string = string> = {
 	alwaysIncludeDocs?: readonly string[];
 	budgets?: HoundsmanBudgets;
 	concurrency?: HoundsmanConcurrency;
+	ast?: HoundsmanAst;
+	ai?: HoundsmanAi;
 };
 
 /** Helper de autoria (identidade) — apenas tipagem. */
@@ -212,7 +284,8 @@ const WATCHDOG_EXAMPLE = `import { defineWatchdog } from "../core/types";
 
 /**
  * Watchdog de exemplo — substitua pelas regras reais do projeto.
- * Um watchdog declara seus arquivos via \`classify\` (regex de path ou conteúdo).
+ * Um watchdog declara seus arquivos via \`classify\` (regex de path, conteúdo ou
+ * fatos AST: \`symbol\`/\`import\`/\`export\`/\`decorator\`).
  * O texto de cada regra começa com a polaridade: \`Promover:\` (DEVE acontecer)
  * ou \`Evitar:\`/\`Não\`/\`Nunca\` (NÃO DEVE acontecer).
  */
@@ -220,8 +293,8 @@ export const exampleWatchdog = defineWatchdog({
 	id: "example",
 	name: "Exemplo",
 	description: "Watchdog de exemplo — descreva o propósito em uma frase.",
-	scope: "Todo o repositório (ajuste o escopo)",
-	classify: [{ value: "^src/" }],
+	scope: "src/example/** (ajuste o escopo)",
+	classify: [{ value: "^src/example/" }],
 	rules: [
 		{
 			severity: "attention",
@@ -237,13 +310,65 @@ export const exampleWatchdog = defineWatchdog({
 });
 `;
 
-const WATCHDOGS_INDEX = `import { exampleWatchdog } from "./example";
+const DEFAULT_WATCHDOG = `import { defineWatchdog } from "../core/types";
+
+/**
+ * Watchdog de padrões gerais e lógica (fallback).
+ *
+ * Só assume arquivos que nenhum outro watchdog casou. Cobre consistência
+ * lógica, invariantes de domínio e defeitos genéricos que não pertencem a um
+ * domínio específico. Findings fora das regras abaixo podem ser reportados com
+ * os prefixos reservados "Lógica:" e "Domínio:" (opt-in abaixo).
+ */
+export const defaultWatchdog = defineWatchdog({
+	id: "default",
+	name: "Padrões gerais e lógica",
+	description:
+		"Cobre arquivos sem domínio específico: consistência lógica, domínio e defeitos genéricos.",
+	scope: "Arquivos não classificados por outros watchdogs",
+	fallback: true,
+	allowEmergentFindings: true,
+	rules: [
+		{
+			severity: "attention",
+			text: "Promover: nome, contrato e documentação do símbolo correspondem ao comportamento real.",
+			hints: { checks: ["symbol_context"] },
+		},
+		{
+			severity: "attention",
+			text: "Evitar: engolir erros/exceções sem propagar, logar ou tratar.",
+		},
+		{
+			severity: "attention",
+			text: "Promover: transições de estado e efeitos colaterais do domínio são explícitos, ordenados e idempotentes.",
+		},
+		{
+			severity: "suggestion",
+			text: "Evitar: lógica de negócio duplicada ou divergente entre camadas.",
+			hints: { checks: ["find_references"] },
+		},
+		{
+			severity: "suggestion",
+			text: "Promover: casos de borda do domínio (vazio, zero, negativo, timezone, arredondamento) são tratados.",
+		},
+		{
+			severity: "suggestion",
+			text: "Promover: a lógica do domínio respeita as invariantes e contratos documentados.",
+		},
+	],
+	contextFiles: ["AGENTS.md"],
+});
+`;
+
+const WATCHDOGS_INDEX = `import { defaultWatchdog } from "./default";
+import { exampleWatchdog } from "./example";
 
 /**
  * Definições dos watchdogs — as chaves definem o union \`WatchdogId\`.
  * Adicionar um watchdog = criar \`<id>.ts\` e registrá-lo aqui.
  */
 export const WATCHDOG_DEFINITIONS = {
+	default: defaultWatchdog,
 	example: exampleWatchdog,
 };
 
@@ -267,9 +392,10 @@ export function isExcluded(filePath: string): boolean {
 const DOC_MAPPINGS_TEMPLATE = `/**
  * Mapeamento de padrões nos paths → documentação relevante.
  * Consumido pelo motor via \`HoundsmanConfig.docMappings\`.
- */\`core/\` é regenerado por \`houndsman update\`.
-# Runs, findings e artefatos vivem no storage global (fora do projeto).
-core
+ *
+ * Exemplo: [/^src\\//, ["README.md"]]
+ */
+export const DOC_MAPPINGS: readonly (readonly [RegExp, readonly string[]])[] = [];
 `;
 
 const PROJECT_GITIGNORE = `# Diretórios gerados pelo houndsman — \`core/\` é regenerado por \`houndsman update\`
@@ -307,6 +433,14 @@ class WatchdogExampleTemplate implements ScaffoldTemplate {
 	}
 }
 
+class DefaultWatchdogTemplate implements ScaffoldTemplate {
+	readonly path = join(PROJECT_DIR, "watchdogs", "default.ts");
+
+	render(): string {
+		return DEFAULT_WATCHDOG;
+	}
+}
+
 class WatchdogsIndexTemplate implements ScaffoldTemplate {
 	readonly path = join(PROJECT_DIR, "watchdogs", "index.ts");
 
@@ -402,6 +536,7 @@ export class ProjectScaffolder {
 		const context = this.context();
 		const templates: ScaffoldTemplate[] = [
 			new ConfigTemplate(),
+			new DefaultWatchdogTemplate(),
 			new WatchdogExampleTemplate(),
 			new WatchdogsIndexTemplate(),
 			new ExclusionsTemplate(),
@@ -415,6 +550,7 @@ export class ProjectScaffolder {
 		const context = this.context();
 		this.writeGeneratedFile(new TypesTemplate(), context);
 		this.writeGeneratedFile(new GitignoreTemplate(), context);
+		this.syncGrammars();
 
 		// Docs do skill vão para `.houndsman/core/skill/`. O `SKILL.md` é o entry
 		// point dos harnesses, não um doc da camada.
@@ -428,6 +564,19 @@ export class ProjectScaffolder {
 		}
 	}
 
+	/**
+	 * Copia as grammars wasm para a camada. O consumidor não precisa rodar nada:
+	 * `setup` e `update` sincronizam os binários junto dos demais auto-gerados.
+	 */
+	private syncGrammars(): void {
+		const directory = join(this.ctx.cwd, CORE_DIR, "grammars");
+		mkdirSync(directory, { recursive: true });
+		for (const name of GRAMMAR_FILES) {
+			copyFileSync(grammarPath(name), join(directory, name));
+		}
+		this.ctx.generated.push(join(CORE_DIR, "grammars", "*.wasm"));
+	}
+
 	private context(): TemplateContext {
 		return { projectName: this.ctx.projectName };
 	}

package/src/core/commands/update.ts

@@ -1,9 +1,11 @@
 /**
  * Subcomando `update` — sincroniza os arquivos **auto-gerados** da camada `.houndsman/`.
  *
- * Reescreve `core/types.ts`, `core/skill/*.md`, `.houndsman/.gitignore` e os
- * ponteiros de skill dos harnesses. Nunca toca nos arquivos do usuário
- * (`watchdogs/`, `doc-mappings.ts`, `exclusions.ts`, `houndsman.config.ts`).
+ * Reescreve `core/types.ts`, `core/skill/*.md`, `core/grammars/*.wasm`,
+ * `.houndsman/.gitignore` e os ponteiros de skill dos harnesses. Nunca toca nos
+ * arquivos do usuário (`watchdogs/`, `doc-mappings.ts`, `exclusions.ts`,
+ * `houndsman.config.ts`). As grammars do AST são sincronizadas aqui — o
+ * consumidor não precisa rodar nenhum comando extra.
  */
 
 import { createScaffoldContext, syncGeneratedFiles } from "./scaffold";

package/src/core/config.ts

@@ -6,11 +6,21 @@
  * (camada `houndsman/`) — único ponto de troca ao portar para outro repositório.
  */
 
+import type { AstLanguage } from "./ast/types";
 import { ProjectConfig } from "./project-config";
 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_JEV_CONCURRENCY,
 	DEFAULT_MAX_FILES_PER_BRIEF,
 } from "./defaults";
@@ -21,12 +31,83 @@ export type HoundsmanBudgets = {
 	maxFilesPerBrief?: number;
 };
 
+/** Configuração do subsistema AST (determinístico, sem LLM). */
+export type HoundsmanAst = {
+	/**
+	 * Liga/desliga o AST (default: `true`). Com grammars ausentes ou ABI
+	 * incompatível, o motor segue sem AST (fail-open).
+	 */
+	enabled?: boolean;
+	/** Teto de bytes por arquivo (default: 512_000). */
+	maxFileBytes?: number;
+	/** Teto de arquivos candidatos na análise de impacto (default: 200). */
+	maxImpactFiles?: number;
+	/** Override de extensão → linguagem (`".vue": "typescript"`). */
+	languages?: Record<string, AstLanguage>;
+	/** Aliases de import (`"@/": "src/"`). */
+	aliases?: Record<string, string>;
+};
+
 /** Concorrência das fases paralelas internas. */
 export type HoundsmanConcurrency = {
 	/** Chamadas Jev simultâneas (default: 5). */
 	jev?: number;
 };
 
+/** Providers suportados pela camada de IA. */
+export type AiProviderKind = "deepseek" | "openai" | "anthropic";
+
+/** Features de IA do fluxo determinístico (todas fail-open). */
+export type HoundsmanAiFeatures = {
+	/** Resume o contexto da PR (`context-summary`) quando o subagente não gerou. */
+	context?: boolean;
+	/** Enriquece os briefs com um plano de revisão sugerido. */
+	brief?: boolean;
+	/** Classifica arquivos que nenhum watchdog casou. */
+	classification?: boolean;
+	/** Gera candidatos de pré-análise (substitui o Jev quando disponível). */
+	preAnalysis?: boolean;
+	/** Confirma/refuta findings ambíguos no `verify`. */
+	verify?: boolean;
+};
+
+/** 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). */
+export type HoundsmanAi = {
+	/** Liga a IA do fluxo normal (default: `true`; sem chave é fail-open). */
+	enabled?: boolean;
+	/** Provider de modelo (default: `deepseek`). */
+	provider?: AiProviderKind;
+	/** Modelo (default em `defaults.ts`). */
+	model?: string;
+	/** Base URL customizada do provider. */
+	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). */
+	temperature?: number;
+	/** Timeout por chamada em ms (default: 120_000). */
+	timeoutMs?: number;
+	/** Teto de chamadas por review (default: 40). */
+	maxCallsPerReview?: number;
+	/** Teto de tokens por review. */
+	maxTokensPerReview?: number;
+	/** Features do fluxo normal. */
+	features?: HoundsmanAiFeatures;
+	/** Overrides por watchdog. */
+	watchdogs?: Record<string, HoundsmanAiWatchdog>;
+};
+
 /** Backend de persistência (reviews, findings e artefatos). */
 export type HoundsmanStorage = {
 	/**
@@ -68,6 +149,10 @@ export type HoundsmanConfig<TId extends string = string> = {
 	budgets?: HoundsmanBudgets;
 	/** Concorrência das fases paralelas internas. */
 	concurrency?: HoundsmanConcurrency;
+	/** AST determinístico (classificação estrutural, brief e impacto). */
+	ast?: HoundsmanAst;
+	/** Camada de IA (briefs, contexto, classificação e o harness nativo). */
+	ai?: HoundsmanAi;
 };
 
 /** Entrada de `defineHoundsmanConfig` — `watchdogIds` é derivado, não informado. */