@payconductor/houndsman 0.5.0 → 0.7.0

package/src/core/registry-check.ts

@@ -6,8 +6,10 @@
  */
 
 import type { HoundsmanConfig } from "./config";
+import { env } from "./env";
 import { JevQuestionFactory } from "./jev";
 import { renderReport, sanitizeBranch } from "./report-builder";
+import { hasExplicitPolarity } from "./rule-text";
 import type { WatchdogMeta } from "./types";
 
 /** `id` da definição bate com a chave; `description` não vazio. */
@@ -27,17 +29,56 @@ function checkDefinitions(config: HoundsmanConfig, problems: string[]): void {
 	}
 }
 
-/** Todo watchdog precisa declarar ao menos um arquivo em `classify`. */
+/** Todo watchdog precisa declarar ao menos um arquivo em `classify` (fallback isento). */
 function checkClassification(config: HoundsmanConfig, problems: string[]): void {
 	for (const id of config.watchdogIds) {
 		const def = config.watchdogs[id];
 		if (!def) continue;
+		if (def.fallback) continue;
 		if (!def.classify || def.classify.length === 0) {
 			problems.push(`Watchdog '${id}' não declara nenhum padrão em 'classify'`);
 		}
 	}
 }
 
+/** Fallback: no máximo um; `classify` é ignorado; precisa de regras. */
+function checkFallbacks(config: HoundsmanConfig, warnings: string[]): void {
+	const fallbacks = config.watchdogIds.filter(
+		(id) => config.watchdogs[id]?.fallback === true,
+	);
+	if (fallbacks.length > 1) {
+		warnings.push(
+			`Mais de um watchdog fallback (${fallbacks.join(", ")}); o primeiro declarado vence.`,
+		);
+	}
+	for (const id of fallbacks) {
+		const def = config.watchdogs[id];
+		if (!def) continue;
+		if (def.classify && def.classify.length > 0) {
+			warnings.push(`watchdogs['${id}'] é fallback — 'classify' é ignorado.`);
+		}
+		if (def.rules.length === 0) {
+			warnings.push(`Watchdog fallback '${id}' não declara nenhuma regra.`);
+		}
+	}
+}
+
+/** Findings emergentes exigem ao menos uma regra de lógica/domínio como piso. */
+function checkEmergent(config: HoundsmanConfig, warnings: string[]): void {
+	for (const id of config.watchdogIds) {
+		const def = config.watchdogs[id];
+		if (!def?.allowEmergentFindings) continue;
+		const hasGeneric = def.rules.some((rule) =>
+			/l[oó]gica|dom[ií]nio/i.test(rule.text),
+		);
+		if (!hasGeneric) {
+			warnings.push(
+				`watchdogs['${id}'].allowEmergentFindings sem regra de lógica/domínio — o piso fica implícito.`,
+			);
+		}
+	}
+}
+
 /** Smoke test dos helpers críticos de renderização. */
 function checkRendering(config: HoundsmanConfig, problems: string[]): void {
 	if (sanitizeBranch("feature/x") !== "feature-x") {
@@ -106,9 +147,6 @@ function checkJevSpecs(config: HoundsmanConfig, problems: string[]): number {
 	return generated;
 }
 
-/** Prefixos de polaridade aceitos no texto da regra (§ Convenções de escrita). */
-const POLARITY_PREFIX = /^(promover|evitar|não|nao|nunca)\b/i;
-
 /**
  * Aviso **não bloqueante** para regra sem polaridade explícita: o texto deve
  * começar com `Promover:` (DEVE acontecer) ou `Evitar:`/`Não`/`Nunca` (NÃO DEVE).
@@ -119,7 +157,7 @@ function checkRulePolarity(config: HoundsmanConfig, warnings: string[]): void {
 		if (!def) continue;
 		def.rules.forEach((rule, index) => {
 			const text = rule.text.trim();
-			if (!text || POLARITY_PREFIX.test(text)) return;
+			if (!text || hasExplicitPolarity(text)) return;
 			warnings.push(
 				`Regra sem polaridade explícita em ${id} (rule-${index}): ${rule.text}`,
 			);
@@ -169,7 +207,7 @@ function checkMetadataPrecision(config: HoundsmanConfig, warnings: string[]): vo
 			const items = def[field];
 			if (!items) continue;
 			items.forEach((item, index) => {
-				if (!POLARITY_PREFIX.test(item.trim())) return;
+				if (!hasExplicitPolarity(item)) return;
 				warnings.push(
 					`Texto de regra em ${id}.${field}[${index}] — a regra vive só em 'rules': ${item}`,
 				);
@@ -192,6 +230,106 @@ function checkBudgets(config: HoundsmanConfig, warnings: string[]): void {
 	}
 }
 
+/** Valida a configuração do AST (a disponibilidade das grammars é checada no doctor). */
+function checkAstConfig(
+	config: HoundsmanConfig,
+	problems: string[],
+	warnings: string[],
+): void {
+	const ast = config.ast;
+	if (!ast) return;
+
+	if (ast.maxFileBytes !== undefined && ast.maxFileBytes <= 0) {
+		warnings.push(
+			`ast.maxFileBytes = ${ast.maxFileBytes} — não-positivo; usando o default.`,
+		);
+	}
+	if (ast.maxImpactFiles !== undefined && ast.maxImpactFiles < 0) {
+		warnings.push(
+			`ast.maxImpactFiles = ${ast.maxImpactFiles} — negativo; impacto será desabilitado.`,
+		);
+	}
+	const valid = new Set(["typescript", "tsx", "javascript"]);
+	for (const [extension, language] of Object.entries(ast.languages ?? {})) {
+		if (!valid.has(language)) {
+			problems.push(
+				`ast.languages['${extension}'] = '${language}' (esperado typescript|tsx|javascript)`,
+			);
+		}
+	}
+	for (const [alias, target] of Object.entries(ast.aliases ?? {})) {
+		if (!alias.trim() || !target.trim()) {
+			warnings.push(`ast.aliases['${alias}'] vazio — alias ignorado.`);
+		}
+	}
+}
+
+/** Valida a configuração de IA (sem exigir chave — fail-open). */
+function checkAiConfig(
+	config: HoundsmanConfig,
+	problems: string[],
+	warnings: string[],
+): void {
+	const ai = config.ai;
+	if (!ai) return;
+
+	const validProviders = new Set(["deepseek", "openai", "anthropic"]);
+	if (ai.provider !== undefined && !validProviders.has(ai.provider)) {
+		problems.push(
+			`ai.provider = '${ai.provider}' (esperado deepseek|openai|anthropic)`,
+		);
+	}
+	if (ai.enabled !== false && ai.model !== undefined && !ai.model.trim()) {
+		warnings.push("ai.model vazio — usando o default.");
+	}
+	for (const key of [
+		"concurrency",
+		"maxSteps",
+		"maxOutputTokens",
+		"timeoutMs",
+	] as const) {
+		const value = ai[key];
+		if (value !== undefined && value <= 0) {
+			warnings.push(`ai.${key} = ${value} — não-positivo; usando o default.`);
+		}
+	}
+	if (ai.maxCallsPerReview !== undefined && ai.maxCallsPerReview <= 0) {
+		warnings.push(
+			`ai.maxCallsPerReview = ${ai.maxCallsPerReview} — não-positivo; usando o default.`,
+		);
+	}
+	if (ai.maxTokensPerReview !== undefined && ai.maxTokensPerReview < 0) {
+		warnings.push(
+			`ai.maxTokensPerReview = ${ai.maxTokensPerReview} — negativo; sem teto.`,
+		);
+	}
+	for (const [id, override] of Object.entries(ai.watchdogs ?? {})) {
+		if (!config.watchdogIds.includes(id)) {
+			warnings.push(`ai.watchdogs['${id}'] não corresponde a nenhum watchdog.`);
+		}
+		if (override.maxSteps !== undefined && override.maxSteps <= 0) {
+			warnings.push(
+				`ai.watchdogs['${id}'].maxSteps não-positivo — usando o default.`,
+			);
+		}
+	}
+
+	const provider = ai.provider ?? "deepseek";
+	if (validProviders.has(provider) && ai.enabled !== false) {
+		const credential =
+			provider === "deepseek"
+				? env.deepSeekApiKey
+				: provider === "openai"
+					? env.openAiApiKey
+					: env.anthropicApiKey;
+		if (!credential) {
+			warnings.push(
+				`ai.provider '${provider}' sem credencial — features de IA ficam fail-open.`,
+			);
+		}
+	}
+}
+
 export function checkRegistry(config: HoundsmanConfig): {
 	problems: string[];
 	warnings: string[];
@@ -202,11 +340,15 @@ export function checkRegistry(config: HoundsmanConfig): {
 
 	checkDefinitions(config, problems);
 	checkClassification(config, problems);
+	checkFallbacks(config, warnings);
+	checkEmergent(config, warnings);
 	checkRendering(config, problems);
 	checkRulePolarity(config, warnings);
 	checkRuleDuplication(config, warnings);
 	checkMetadataPrecision(config, warnings);
 	checkBudgets(config, warnings);
+	checkAstConfig(config, problems, warnings);
+	checkAiConfig(config, problems, warnings);
 	const jevQuestions = checkJevSpecs(config, problems);
 
 	return { problems, warnings, jevQuestions };

package/src/core/renderers/manifest-writer.ts

@@ -6,6 +6,7 @@
  * findings apontam para o staging da review.
  */
 
+import type { AiUsage } from "../ai/types";
 import { Classification } from "../domain/classification";
 import type { ClassificationResult } from "../file-classifier";
 import type { JevCandidatesFile } from "../jev";
@@ -22,6 +23,27 @@ export type ManifestOptions = {
 	head: string;
 };
 
+/** Resumo do AST no manifesto. */
+export type ManifestAst = {
+	enabled: boolean;
+	languages: string[];
+	files: number;
+	impact: {
+		affectedFiles: number;
+		importers: number;
+		exportedChanges: number;
+	};
+};
+
+/** Resumo da IA no manifesto (só quando a IA foi usada). */
+export type ManifestAi = {
+	enabled: boolean;
+	provider: string;
+	model: string;
+	briefPlans: number;
+	usage: AiUsage;
+};
+
 /** Classificação enriquecida gravada pelo prepare (modo + incremental). */
 export type ManifestClassification = ClassificationResult & {
 	headSha?: string;
@@ -57,6 +79,8 @@ export class ManifestWriter {
 		activeIds: string[],
 		pending: string[],
 		jev: JevCandidatesFile,
+		ast?: ManifestAst,
+		ai?: ManifestAi,
 	): void {
 		const view = Classification.from(classification);
 		const maxFilesPerBrief = this.project.maxFilesPerBrief;
@@ -65,9 +89,11 @@ export class ManifestWriter {
 		const watchdogs = activeIds.map((id) => {
 			const selection = view.budgetFor(id, maxFilesPerBrief);
 			filesOverBudget += selection.overflow.length;
+			const domain = this.project.watchdogs.find(id);
 			return {
 				id,
 				name: this.project.watchdogs.nameOf(id),
+				...(domain?.definition.fallback ? { fallback: true } : {}),
 				files: selection.selected,
 				overflow: selection.overflow.length,
 				brief: this.work.briefFile(id),
@@ -109,6 +135,13 @@ export class ManifestWriter {
 						skipped: jev.skipped?.length ?? 0,
 					}
 				: { available: false, reason: jev.reason },
+			ast: ast ?? {
+				enabled: false,
+				languages: [],
+				files: 0,
+				impact: { affectedFiles: 0, importers: 0, exportedChanges: 0 },
+			},
+			ai,
 			deleted: classification.deleted,
 			unclassified: classification.unclassified,
 			excludedCount: classification.excludedCount,

package/src/core/rule-text.ts

@@ -0,0 +1,97 @@
+/**
+ * Texto de regra (biblioteca) — fonte única de polaridade e prefixos reservados.
+ *
+ * `RuleAnalyzer`, `registry-check` e o harness usam as mesmas listas: evita
+ * divergência entre “Promover/Evitar” no analyzer e as validações anti-drift.
+ * Também define o vocabulário de findings emergentes (lógica/domínio).
+ */
+
+/** Intenção de uma regra. */
+export type RuleIntent = "promote" | "avoid";
+
+/** Palavras que abrem uma regra de “deve acontecer”. */
+export const PROMOTE_PREFIXES = [
+	"promover",
+	"deve",
+	"dever",
+	"use",
+	"prefira",
+	"sempre",
+] as const;
+
+/** Palavras que abrem uma regra de “não deve acontecer”. */
+export const AVOID_PREFIXES = [
+	"evitar",
+	"não",
+	"nao",
+	"nunca",
+	"proibido",
+	"jamais",
+] as const;
+
+/** Conjunto normalizado (usado para remover polaridade das keywords). */
+export const POLARITY_WORDS: ReadonlySet<string> = new Set([
+	...PROMOTE_PREFIXES,
+	...AVOID_PREFIXES,
+]);
+
+/** Escapa um literal para uso em regex. */
+function escapeWord(word: string): string {
+	return word.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** Regex ancorada derivada das listas (sem repetir as palavras). */
+function patternFor(words: readonly string[]): RegExp {
+	return new RegExp(`^(${words.map(escapeWord).join("|")})\\b`);
+}
+
+const PROMOTE_PATTERN = patternFor(PROMOTE_PREFIXES);
+const AVOID_PATTERN = patternFor(AVOID_PREFIXES);
+
+/** Polaridade explícita; sem prefixo conhecido, assume `avoid`. */
+export function polarityOf(text: string): RuleIntent {
+	const normalized = text.trim().toLowerCase();
+	if (PROMOTE_PATTERN.test(normalized)) return "promote";
+	if (AVOID_PATTERN.test(normalized)) return "avoid";
+	return "avoid";
+}
+
+/** `true` quando a regra declara polaridade explícita. */
+export function hasExplicitPolarity(text: string): boolean {
+	const normalized = text.trim().toLowerCase();
+	return PROMOTE_PATTERN.test(normalized) || AVOID_PATTERN.test(normalized);
+}
+
+/** Prefixos reservados para findings emergentes (fora das regras explícitas). */
+export const EMERGENT_PREFIXES = {
+	logic: "Lógica:",
+	domain: "Domínio:",
+} as const;
+
+/** Espécie de finding emergente. */
+export type EmergentKind = keyof typeof EMERGENT_PREFIXES;
+
+/** Espécie de um finding emergente (`null` quando não é emergente). */
+export function emergentKind(rule: string): EmergentKind | null {
+	const normalized = rule.trim();
+	if (normalized.startsWith(EMERGENT_PREFIXES.logic)) return "logic";
+	if (normalized.startsWith(EMERGENT_PREFIXES.domain)) return "domain";
+	return null;
+}
+
+/** `true` quando a regra usa um prefixo emergente. */
+export function isEmergentRule(rule: string): boolean {
+	return emergentKind(rule) !== null;
+}
+
+/** Texto que sobra após o prefixo (vazio é inválido). */
+export function emergentText(rule: string): string {
+	const kind = emergentKind(rule);
+	if (!kind) return "";
+	return rule.trim().slice(EMERGENT_PREFIXES[kind].length).trim();
+}
+
+/** Monta o texto de um finding emergente. */
+export function emergentRule(kind: EmergentKind, text: string): string {
+	return `${EMERGENT_PREFIXES[kind]} ${text.trim()}`;
+}

package/src/core/services/file-classifier.ts

@@ -5,6 +5,7 @@
  * pública e os testes; a classe devolve `Classification` (domínio).
  */
 
+import type { AstFacts } from "../ast/types";
 import type { HoundsmanConfig } from "../config";
 import type { DiffSource } from "../diff-source";
 import { Classification } from "../domain/classification";
@@ -23,12 +24,18 @@ export class FileClassifier {
 	classify(
 		entries: ReturnType<typeof parseEntries>,
 		churn: ChurnMap = {},
+		astFacts?: ReadonlyMap<string, AstFacts>,
 	): Classification {
-		return new Classification(classifyEntries(entries, this.config, churn));
+		return new Classification(classifyEntries(entries, this.config, churn, astFacts));
 	}
 
 	/** Executa o diff e classifica os arquivos entre `base` e `head`. */
-	classifyRange(base: string, head: string, diff?: DiffSource): Classification {
-		return new Classification(classifyRange(base, head, this.config, diff));
+	classifyRange(
+		base: string,
+		head: string,
+		diff?: DiffSource,
+		astFacts?: ReadonlyMap<string, AstFacts>,
+	): Classification {
+		return new Classification(classifyRange(base, head, this.config, diff, astFacts));
 	}
 }

package/src/core/services/gh-client.ts

@@ -10,29 +10,45 @@ export type GhResult = { ok: boolean; code: number; stdout: string; stderr: stri
 /** Executa o `gh` e devolve o resultado cru (sem lançar). */
 export type GhRunner = (args: string[]) => GhResult;
 
-/** Runner padrão: `gh` a partir do cwd; ausência do binário → `ok:false`. */
-export const defaultGhRunner: GhRunner = (args) => {
-	try {
-		const result = Bun.spawnSync(["gh", ...args], {
-			stdout: "pipe",
-			stderr: "pipe",
-		});
-		const code = result.exitCode ?? 1;
-		return {
-			ok: code === 0,
-			code,
-			stdout: new TextDecoder().decode(result.stdout).trim(),
-			stderr: new TextDecoder().decode(result.stderr).trim(),
-		};
-	} catch (error) {
-		return {
-			ok: false,
-			code: 127,
-			stdout: "",
-			stderr: error instanceof Error ? error.message : String(error),
-		};
+/** Mensagem curta para um erro do `gh` (sem expor o stderr inteiro). */
+export function describeGhError(result: GhResult): string {
+	if (result.code === 127 || /not found|ENOENT/i.test(result.stderr)) {
+		return "gh não instalado.";
 	}
-};
+	const last = result.stderr.split("\n").filter(Boolean).pop() ?? "";
+	if (/auth|login|logged/i.test(last)) return `gh sem autenticação (${last}).`;
+	return last || `gh saiu com código ${result.code}.`;
+}
+
+/** Cria um runner do `gh` com diretório de trabalho fixo. */
+export function createGhRunner(cwd?: string): GhRunner {
+	return (args) => {
+		try {
+			const result = Bun.spawnSync(["gh", ...args], {
+				cwd,
+				stdout: "pipe",
+				stderr: "pipe",
+			});
+			const code = result.exitCode ?? 1;
+			return {
+				ok: code === 0,
+				code,
+				stdout: new TextDecoder().decode(result.stdout).trim(),
+				stderr: new TextDecoder().decode(result.stderr).trim(),
+			};
+		} catch (error) {
+			return {
+				ok: false,
+				code: 127,
+				stdout: "",
+				stderr: error instanceof Error ? error.message : String(error),
+			};
+		}
+	};
+}
+
+/** Runner padrão: `gh` a partir do cwd; ausência do binário → `ok:false`. */
+export const defaultGhRunner: GhRunner = createGhRunner();
 
 /** Superfície OO sobre o runner injetável. */
 export class GhClient {

package/src/core/services/verifier.ts

@@ -12,10 +12,11 @@ import type {
 	FindingsStateFile,
 } from "../findings-state";
 import {
-	applyJev,
+	applyConfidence,
 	applyResolutions,
 	selectVerifiable,
 	summarizeVerify,
+	type VerifyBasis,
 	type VerifyEntry,
 	type VerifySummary,
 	verifyLocal,
@@ -33,13 +34,23 @@ export class Verifier {
 		return verifyLocal(findings, readFile);
 	}
 
-	/** Tier 1 — aplica a confirmação do Jev aos casos ambíguos. */
+	/** Tier 1 — aplica confirmações externas (Jev ou IA) aos casos ambíguos. */
+	applyConfidence(
+		entries: VerifyEntry[],
+		confidence: Map<string, number>,
+		threshold: number,
+		basis: VerifyBasis = "jev",
+	): number {
+		return applyConfidence(entries, confidence, threshold, basis);
+	}
+
+	/** Compatibilidade: confirmação via Jev. */
 	applyJev(
 		entries: VerifyEntry[],
 		confidence: Map<string, number>,
 		threshold: number,
 	): number {
-		return applyJev(entries, confidence, threshold);
+		return applyConfidence(entries, confidence, threshold, "jev");
 	}
 
 	/** Contagem por status. */

package/src/core/storage/paths.ts

@@ -9,17 +9,18 @@
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import type { HoundsmanConfig } from "../config";
+import { ENV_NAMES, env } from "../env";
 
-export const HOUNDSMAN_HOME_ENV = "HOUNDSMAN_HOME";
+export const HOUNDSMAN_HOME_ENV = ENV_NAMES.home;
 
 /** Diretório-base global do houndsman. */
 export function houndsmanHome(): string {
-	const override = process.env[HOUNDSMAN_HOME_ENV];
-	if (override && override.trim().length > 0) return resolve(override);
+	const override = env.home;
+	if (override) return resolve(override);
 
 	const home = homedir();
 	if (process.platform === "win32") {
-		const local = process.env.LOCALAPPDATA;
+		const local = env.localAppData;
 		return join(
 			local && local.length > 0 ? local : join(home, "AppData", "Local"),
 			"houndsman",
@@ -28,7 +29,7 @@ export function houndsmanHome(): string {
 	if (process.platform === "darwin") {
 		return join(home, "Library", "Application Support", "houndsman");
 	}
-	const xdg = process.env.XDG_DATA_HOME;
+	const xdg = env.xdgDataHome;
 	return join(xdg && xdg.length > 0 ? xdg : join(home, ".local", "share"), "houndsman");
 }
 

package/src/core/storage/types.ts

@@ -92,6 +92,12 @@ export type ArtifactKind =
 	| "resume"
 	| "domain-review"
 	| "verify"
+	| "ast"
+	| "ast-impact"
+	| "ai"
+	| "ai-usage"
+	| "ai-brief"
+	| "harness-transcript"
 	| "other";
 
 /** Artefato persistido de uma review. */

package/src/core/storage/work-area.ts

@@ -106,12 +106,24 @@ export class ReviewWorkArea {
 		writeFileSync(this.briefFile(id), content);
 	}
 
+	/** Grava o relatório JSON de um watchdog (staging dos subagentes). */
+	writeFinding(id: string, content: string): void {
+		mkdirSync(this.findingsDir, { recursive: true });
+		writeFileSync(this.findingFile(id), content);
+	}
+
 	writeContext(context: unknown, brief: string): void {
 		mkdirSync(this.root, { recursive: true });
 		writeFileSync(this.contextPaths.context, `${JSON.stringify(context, null, 2)}\n`);
 		writeFileSync(this.contextPaths.brief, `${brief}\n`);
 	}
 
+	/** Grava o resumo do contexto (gerado pelo subagente ou pela IA). */
+	writeContextSummary(summary: unknown): void {
+		mkdirSync(this.root, { recursive: true });
+		writeFileSync(this.contextPaths.summary, `${JSON.stringify(summary, null, 2)}\n`);
+	}
+
 	/** Finds brutos gravados pelos subagentes (um JSON por watchdog). */
 	readFindings(activeIds: string[]): FindingsIngest {
 		const reports: WatchdogReport[] = [];

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. */