@payconductor/houndsman 0.5.0 → 0.6.0

package/src/core/project-config.ts

@@ -6,9 +6,25 @@
  * O contrato do consumidor (`houndsman.config.ts`) não muda.
  */
 
-import type { HoundsmanConfig, HoundsmanStorage } from "./config";
+import type {
+	AiProviderKind,
+	HoundsmanAi,
+	HoundsmanAiFeatures,
+	HoundsmanAst,
+	HoundsmanConfig,
+	HoundsmanStorage,
+} from "./config";
 import {
+	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";
@@ -32,6 +48,26 @@ export class ProjectConfig<TId extends string = string> {
 		return this.raw.storage ?? {};
 	}
 
+	/** Config do AST (objeto vazio quando ausente). */
+	get ast(): HoundsmanAst {
+		return this.raw.ast ?? {};
+	}
+
+	/** AST habilitado (default: ligado; falhas de grammar são fail-open). */
+	get astEnabled(): boolean {
+		return this.ast.enabled !== false;
+	}
+
+	get astMaxFileBytes(): number {
+		const value = this.ast.maxFileBytes;
+		return value !== undefined && value > 0 ? value : DEFAULT_AST_MAX_FILE_BYTES;
+	}
+
+	get astMaxImpactFiles(): number {
+		const value = this.ast.maxImpactFiles;
+		return value !== undefined && value >= 0 ? value : DEFAULT_AST_MAX_IMPACT_FILES;
+	}
+
 	get maxFilesPerBrief(): number {
 		const value = this.raw.budgets?.maxFilesPerBrief;
 		return value !== undefined && value > 0 ? value : DEFAULT_MAX_FILES_PER_BRIEF;
@@ -53,4 +89,90 @@ export class ProjectConfig<TId extends string = string> {
 	get docMappings(): readonly (readonly [RegExp, readonly string[]])[] {
 		return this.raw.docMappings;
 	}
+
+	/** Config de IA (objeto vazio quando ausente). */
+	get ai(): HoundsmanAi {
+		return this.raw.ai ?? {};
+	}
+
+	/** IA habilitada (default: ligada; sem chave é fail-open). */
+	get aiEnabled(): boolean {
+		return this.ai.enabled !== false;
+	}
+
+	get aiProvider(): AiProviderKind {
+		return this.ai.provider ?? DEFAULT_AI_PROVIDER;
+	}
+
+	get aiModel(): string {
+		const value = this.ai.model?.trim();
+		return value && value.length > 0 ? value : DEFAULT_AI_MODEL;
+	}
+
+	get aiConcurrency(): number {
+		return positive(this.ai.concurrency, DEFAULT_AI_CONCURRENCY);
+	}
+
+	get aiMaxSteps(): number {
+		return positive(this.ai.maxSteps, DEFAULT_AI_MAX_STEPS);
+	}
+
+	get aiMaxOutputTokens(): number {
+		return positive(this.ai.maxOutputTokens, DEFAULT_AI_MAX_OUTPUT_TOKENS);
+	}
+
+	get aiTemperature(): number {
+		const value = this.ai.temperature;
+		return typeof value === "number" && Number.isFinite(value) ? value : 0;
+	}
+
+	get aiTimeoutMs(): number {
+		return positive(this.ai.timeoutMs, DEFAULT_AI_TIMEOUT_MS);
+	}
+
+	get aiMaxCallsPerReview(): number {
+		return positive(this.ai.maxCallsPerReview, DEFAULT_AI_MAX_CALLS_PER_REVIEW);
+	}
+
+	/** Teto de tokens por review (0/ausente = sem teto). */
+	get aiMaxTokensPerReview(): number | undefined {
+		const value = this.ai.maxTokensPerReview;
+		return value !== undefined && value > 0 ? value : undefined;
+	}
+
+	/** Features resolvidas com defaults (`context`/`brief` ligadas). */
+	get aiFeatures(): Required<HoundsmanAiFeatures> {
+		const features = this.ai.features ?? {};
+		return {
+			context: features.context !== false,
+			brief: features.brief !== false,
+			classification: features.classification === true,
+			preAnalysis: features.preAnalysis === true,
+			verify: features.verify === true,
+		};
+	}
+
+	/** Modelo efetivo de um watchdog (override por watchdog ou global). */
+	aiModelFor(watchdogId: string): string {
+		const override = this.ai.watchdogs?.[watchdogId]?.model?.trim();
+		return override && override.length > 0 ? override : this.aiModel;
+	}
+
+	/** Passos efetivos de um watchdog (override por watchdog ou global). */
+	aiMaxStepsFor(watchdogId: string): number {
+		return positive(this.ai.watchdogs?.[watchdogId]?.maxSteps, this.aiMaxSteps);
+	}
+
+	/** Tokens de saída efetivos de um watchdog. */
+	aiMaxOutputTokensFor(watchdogId: string): number {
+		return positive(
+			this.ai.watchdogs?.[watchdogId]?.maxOutputTokens,
+			this.aiMaxOutputTokens,
+		);
+	}
+}
+
+/** Inteiro positivo ou o default. */
+function positive(value: number | undefined, fallback: number): number {
+	return value !== undefined && Number.isFinite(value) && value > 0 ? value : fallback;
 }

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/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[] = [];