@payconductor/houndsman 0.4.0 → 0.6.0

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/run-status.ts

@@ -4,9 +4,9 @@
  * Diz à UI em que pé está uma run: `reviewing` (revisando) → `review_done`
  * (revisão finalizada) → `fixing` (corrigindo) → `fix_done` (correção finalizada).
  *
- * Toda ação que muda o estado faz um **ping** no `updatedAt`. Timeout é
- * **display-only** (a UI compara `updatedAt` com o agora) — não é um status
- * persistido.
+ * Toda ação que muda o estado pinga o `updatedAt`. Execuções ativas têm um
+ * `heartbeatAt` próprio (renovado por `status ping` ou pela correção); a UI usa
+ * esse campo — não o `updatedAt` — para detectar timeout (display-only).
  */
 
 import type { FindingsStateFile } from "./findings-state";
@@ -24,6 +24,11 @@ export const RUN_STATUSES: readonly RunStatus[] = [
 	"fix_done",
 ];
 
+/** `true` para status de execução (recebem heartbeat e podem dar timeout). */
+export function isActiveRunStatus(status: RunStatus | null): boolean {
+	return status === "reviewing" || status === "fixing";
+}
+
 /** Lê o status atual (null se a review não existir). */
 export function readRunStatus(
 	storage: StorageProvider,
@@ -36,6 +41,11 @@ export type WriteRunStatusOptions = {
 	status: RunStatus;
 	/** Reinicia o `startedAt` — usado no início de uma nova revisão. */
 	resetStartedAt?: boolean;
+	/**
+	 * Marca a execução como viva agora. Implícito no início de um ciclo
+	 * (`resetStartedAt`); pings explícitos usam `touchRunStatus`.
+	 */
+	touch?: boolean;
 	now?: string;
 };
 
@@ -45,15 +55,35 @@ export function writeRunStatus(
 	reviewId: string,
 	options: WriteRunStatusOptions,
 ): ReviewRecord {
+	const now = options.now ?? systemClock();
+	const active = isActiveRunStatus(options.status);
+	const touch = options.touch ?? options.resetStartedAt ?? false;
 	const updated = storage.updateReview(reviewId, {
 		status: options.status,
 		resetStartedAt: options.resetStartedAt,
-		updatedAt: options.now ?? systemClock(),
+		heartbeatAt: active && touch ? now : undefined,
+		resetHeartbeat: !active,
+		updatedAt: now,
 	});
 	if (!updated) throw new Error(`Review '${reviewId}' não encontrada.`);
 	return updated;
 }
 
+/**
+ * Heartbeat explícito de uma execução em andamento (skill viva).
+ * Só age em `reviewing`/`fixing`; status terminal é devolvido sem alteração.
+ */
+export function touchRunStatus(
+	storage: StorageProvider,
+	reviewId: string,
+	now: string = systemClock(),
+): ReviewRecord {
+	const review = storage.getReview(reviewId);
+	if (!review) throw new Error(`Review '${reviewId}' não encontrada.`);
+	if (!isActiveRunStatus(review.status)) return review;
+	return storage.updateReview(reviewId, { heartbeatAt: now, updatedAt: now }) ?? review;
+}
+
 /**
  * Deriva o status após uma mudança nos findings (triagem/correção).
  * `fixing` exige correção em andamento (`in_progress`) ou retomada de um fix;
@@ -87,7 +117,11 @@ export function pingFindingsStatus(
 	state: FindingsStateFile,
 ): ReviewRecord {
 	const previous = storage.getReview(reviewId)?.status ?? null;
+	const status = statusAfterFindingsChange(previous, state);
 	return writeRunStatus(storage, reviewId, {
-		status: statusAfterFindingsChange(previous, state),
+		status,
+		// Só a correção em andamento é uma execução: triagem/reviewing não
+		// devem renovar o heartbeat (era a origem do "timeout falso").
+		touch: status === "fixing",
 	});
 }

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/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/file/file-storage.ts

@@ -102,6 +102,8 @@ export class FileStorageProvider implements StorageProvider {
 		if (patch.status !== undefined) updated.status = patch.status;
 		if (patch.resetStartedAt) updated.startedAt = now;
 		else if (patch.startedAt !== undefined) updated.startedAt = patch.startedAt;
+		if (patch.resetHeartbeat) updated.heartbeatAt = undefined;
+		else if (patch.heartbeatAt !== undefined) updated.heartbeatAt = patch.heartbeatAt;
 		updated.updatedAt = patch.updatedAt ?? now;
 		return this.writeReview(updated);
 	}

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/sqlite/mappers.ts

@@ -30,6 +30,7 @@ export type ReviewRow = {
 	reviewed_at: string | null;
 	status: string | null;
 	started_at: string | null;
+	heartbeat_at: string | null;
 	created_at: string;
 	updated_at: string;
 };
@@ -96,6 +97,7 @@ export function reviewFromRow(row: ReviewRow): ReviewRecord {
 		reviewedAt: row.reviewed_at ?? undefined,
 		status: (row.status as ReviewRecord["status"]) ?? null,
 		startedAt: row.started_at ?? undefined,
+		heartbeatAt: row.heartbeat_at ?? undefined,
 		createdAt: row.created_at,
 		updatedAt: row.updated_at,
 	};

package/src/core/storage/sqlite/schema.ts

@@ -7,7 +7,7 @@
 
 import type { Database } from "bun:sqlite";
 
-export const SCHEMA_VERSION = 1;
+export const SCHEMA_VERSION = 2;
 
 const DDL = `
 CREATE TABLE IF NOT EXISTS reviews (
@@ -24,6 +24,7 @@ CREATE TABLE IF NOT EXISTS reviews (
 	reviewed_at TEXT,
 	status TEXT,
 	started_at TEXT,
+	heartbeat_at TEXT,
 	created_at TEXT NOT NULL,
 	updated_at TEXT NOT NULL,
 	UNIQUE(repo_key, branch)
@@ -103,6 +104,13 @@ export function migrate(db: Database, path: string): void {
 
 	db.transaction(() => {
 		db.exec(DDL);
+		// v2: heartbeat explícito da execução (bancos v1 não tinham a coluna).
+		const columns = db.query("PRAGMA table_info(reviews)").all() as {
+			name: string;
+		}[];
+		if (!columns.some((column) => column.name === "heartbeat_at")) {
+			db.exec("ALTER TABLE reviews ADD COLUMN heartbeat_at TEXT");
+		}
 		db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
 	})();
 }

package/src/core/storage/sqlite/sqlite-storage.ts

@@ -33,7 +33,7 @@ import { migrate } from "./schema";
 
 /** Colunas mutáveis de review (camel → snake). */
 const REVIEW_PATCH_COLUMNS: Record<
-	Exclude<keyof ReviewPatch, "resetStartedAt">,
+	Exclude<keyof ReviewPatch, "resetStartedAt" | "resetHeartbeat">,
 	string
 > = {
 	branch: "branch",
@@ -45,6 +45,7 @@ const REVIEW_PATCH_COLUMNS: Record<
 	reviewedAt: "reviewed_at",
 	status: "status",
 	startedAt: "started_at",
+	heartbeatAt: "heartbeat_at",
 	updatedAt: "updated_at",
 };
 
@@ -159,6 +160,9 @@ export class SQLiteStorageProvider implements StorageProvider {
 			sets.push("started_at = ?");
 			params.push(now);
 		}
+		if (patch.resetHeartbeat) {
+			sets.push("heartbeat_at = NULL");
+		}
 		if (patch.updatedAt === undefined) {
 			sets.push("updated_at = ?");
 			params.push(now);

package/src/core/storage/types.ts

@@ -36,6 +36,11 @@ export type ReviewRecord = {
 	reviewedAt?: string;
 	status: ReviewStatus | null;
 	startedAt?: string;
+	/**
+	 * Último sinal de vida de uma execução ativa (`reviewing`/`fixing`).
+	 * Diferente de `updatedAt`: não muda com triagem/sync — só com a execução.
+	 */
+	heartbeatAt?: string;
 	createdAt: string;
 	updatedAt: string;
 };
@@ -53,11 +58,14 @@ export type ReviewPatch = Partial<
 		| "reviewedAt"
 		| "status"
 		| "startedAt"
+		| "heartbeatAt"
 		| "updatedAt"
 	>
 > & {
 	/** Reinicia o `startedAt` no início de um novo ciclo de revisão. */
 	resetStartedAt?: boolean;
+	/** Limpa o heartbeat (execução terminou). */
+	resetHeartbeat?: boolean;
 };
 
 /** Entrada de `getOrCreateReview`. */
@@ -81,8 +89,15 @@ export type ArtifactKind =
 	| "context-summary"
 	| "finding-report"
 	| "review"
+	| "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. */

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";
+	}
+}