@payconductor/houndsman 0.13.0 → 0.14.0

package/src/core/engine/review-context.ts

@@ -0,0 +1,51 @@
+/**
+ * Contexto de uma run (engine) — storage + review + staging + raiz operacional.
+ *
+ * É criado uma vez por `ReviewSession` e injetado nas pipelines. Não existe
+ * contexto ambiente: duas runs concorrentes no mesmo processo mantêm contextos
+ * isolados (um singleton mutável trocaria root/git/storage entre `await`s).
+ */
+
+import { GitRepository } from "../services/git-repository";
+import { ProjectFiles } from "../services/project-files";
+import type { ReviewRecord, StorageProvider } from "../storage/types";
+import { ReviewWorkArea } from "../storage/work-area";
+
+/** Workspace onde os arquivos da review são lidos. */
+export type ReviewWorkspaceContext = {
+	/** Raiz operacional (worktree ou clone principal). */
+	root?: string;
+	/** Raiz do clone principal (identidade/config). */
+	mainRoot?: string;
+	git?: GitRepository;
+};
+
+/** Contexto de uma run: storage + review + staging + raiz operacional. */
+export type ReviewContext = {
+	storage: StorageProvider;
+	review: ReviewRecord;
+	work: ReviewWorkArea;
+	root: string;
+	mainRoot: string;
+	git: GitRepository;
+	/** Leitor relativo à raiz operacional (evita repetir `fileReader(root)`). */
+	files: ProjectFiles;
+};
+
+/** Cria o contexto de uma review existente. */
+export function reviewContext(
+	storage: StorageProvider,
+	review: ReviewRecord,
+	workspace: ReviewWorkspaceContext = {},
+): ReviewContext {
+	const root = workspace.root ?? process.cwd();
+	return {
+		storage,
+		review,
+		work: new ReviewWorkArea(review),
+		root,
+		mainRoot: workspace.mainRoot ?? root,
+		git: workspace.git ?? new GitRepository(),
+		files: new ProjectFiles(root),
+	};
+}

package/src/core/engine/review-options.ts

@@ -0,0 +1,47 @@
+/**
+ * Opções de uma run (flags do CLI já resolvidas).
+ *
+ * Fica fora do `orchestrator` para as pipelines importarem o tipo sem ciclo.
+ */
+
+export type ReviewOptions = {
+	base: string;
+	head: string;
+	branch?: string;
+	/**
+	 * Rótulo da variante A/B. Cada variante vira uma run própria
+	 * (`repoKey`, `branch`, `variant`) — permite comparar sem apagar a anterior.
+	 */
+	variant?: string;
+	finalize: boolean;
+	failOnBlocking: boolean;
+	clean: boolean;
+	noJev: boolean;
+	/** Desativa a análise estrutural (AST) nesta run. */
+	noAst: boolean;
+	/** Força review completo (ignora o modo incremental). */
+	full: boolean;
+	/** Desativa as features de IA do fluxo normal. */
+	noAi: boolean;
+	/** PR de origem (resolvida via `--pr`). */
+	pr?: number;
+	/** Worktree informado via flag (`--worktree`). */
+	worktree?: string;
+	/** Worktree resolvido (absoluto; ausente = clone principal). */
+	worktreePath?: string;
+};
+
+/** Valores default das opções (o CLI sobrepõe com as flags). */
+export function defaultOptions(): ReviewOptions {
+	return {
+		base: "main",
+		head: "HEAD",
+		finalize: false,
+		failOnBlocking: false,
+		clean: false,
+		noJev: false,
+		noAst: false,
+		full: false,
+		noAi: false,
+	};
+}

package/src/core/engine/review-scope.ts

@@ -52,6 +52,11 @@ export type ReviewScope =
 			kind: "review";
 			classification: RunClassification;
 			diff: DiffSource;
+			/**
+			 * Patch `-U0` sem truncar (path → hunks). É o insumo dos briefs: cada
+			 * watchdog recebe os trechos alterados em vez de reler arquivos inteiros.
+			 */
+			patch: Map<string, string>;
 			reviewedFrom?: string;
 			/** Fatos/delta por arquivo alterado (quando o AST está habilitado). */
 			ast?: Map<string, AstAnalysis>;
@@ -144,6 +149,7 @@ export class ReviewScopeResolver {
 			return {
 				kind: "review",
 				diff,
+				patch: scopeDiff.byFile,
 				ast,
 				classification: {
 					...result,
@@ -192,7 +198,14 @@ export class ReviewScopeResolver {
 				ast,
 			}),
 		};
-		return { kind: "review", classification, diff, reviewedFrom: prevSha, ast };
+		return {
+			kind: "review",
+			classification,
+			diff,
+			patch: scopeDiff.byFile,
+			reviewedFrom: prevSha,
+			ast,
+		};
 	}
 
 	/**

package/src/core/engine/review-session.ts

@@ -20,7 +20,7 @@ import {
 	resolveBranch,
 	reviewContext,
 } from "../orchestrator";
-import { sanitizeBranch } from "../report-builder";
+import { reviewSlug } from "../report-builder";
 import { GitRepository } from "../services/git-repository";
 import type { RepoIdentity, StorageProvider } from "../storage/types";
 
@@ -48,12 +48,14 @@ export class ReviewSession {
 		this.branch = branch;
 		this.ast = ast;
 		this.ai = ai;
+		const variant = options.variant?.trim() || undefined;
 		const review = options.finalize
-			? storage.findReview(repo.key, branch)
+			? storage.findReview(repo.key, branch, variant)
 			: storage.getOrCreateReview({
 					repo,
 					branch,
-					slug: sanitizeBranch(branch),
+					variant,
+					slug: reviewSlug(branch, variant),
 					base: options.base,
 					head: options.head,
 					worktreePath: options.worktreePath,
@@ -61,7 +63,7 @@ export class ReviewSession {
 				});
 		if (!review) {
 			throw new Error(
-				`Nenhuma revisão para '${branch}'. Rode \`houndsman\` (preparar) primeiro.`,
+				`Nenhuma revisão para '${branch}'${variant ? ` (variante '${variant}')` : ""}. Rode \`houndsman\` (preparar) primeiro.`,
 			);
 		}
 		// Um prepare no clone principal invalida um worktree usado antes; o finalize
@@ -106,20 +108,16 @@ export class ReviewSession {
 
 	/** Passo 1 — preparar. */
 	prepare(onProgress?: PrepareProgress): Promise<PrepareResult> {
-		return prepare(
-			this.options,
-			this.branch,
-			this.config,
-			this.context,
-			this.ast,
-			this.ai,
+		return prepare(this.context, this.config, this.options, {
+			ast: this.ast,
+			ai: this.ai,
 			onProgress,
-		);
+		});
 	}
 
 	/** Passo 3 — finalizar. */
 	finalize(): FinalizeResult {
-		return finalize(this.options, this.branch, this.config, this.context);
+		return finalize(this.context, this.config, this.options);
 	}
 
 	/** Executa o passo escolhido em `--finalize`. */

package/src/core/engine/run-artifacts.ts

@@ -0,0 +1,196 @@
+/**
+ * Artefatos persistidos de uma run (engine) — leitura/escrita tipada.
+ *
+ * Concentra `classification`, `candidates`, `manifest`, resumos e contexto para
+ * que as pipelines não repitam `storage.readArtifact(...)`.
+ */
+
+import type { AstAnalysis, AstImpact } from "../ast/types";
+import { GENERAL_WATCHDOG_ID } from "../builtins";
+import { type BusinessSummary, parseBusinessSummary } from "../business-summary";
+import type { HoundsmanConfig } from "../config";
+import { type JevCandidatesFile, JevCandidatesStore, parseCandidates } from "../jev";
+import {
+	BUSINESS_BRIEF_FILE,
+	BUSINESS_SUMMARY_FILE,
+	TECHNICAL_SUMMARY_FILE,
+} from "../paths";
+import type {
+	ManifestAi,
+	ManifestAst,
+	ManifestBusiness,
+} from "../renderers/manifest-writer";
+import { type ContextSummary, parseContextSummary } from "../report-builder";
+import type { ReviewRecord, StorageProvider } from "../storage/types";
+import type { ReviewWorkArea } from "../storage/work-area";
+import {
+	buildTechnicalSummary,
+	parseTechnicalSummary,
+	type TechnicalSummary,
+} from "../technical-summary";
+import type { RunClassification } from "./review-scope";
+
+/** Acesso tipado aos artefatos de uma review. */
+export class RunArtifacts {
+	constructor(
+		private readonly storage: StorageProvider,
+		private readonly review: ReviewRecord,
+		private readonly work: ReviewWorkArea,
+	) {}
+
+	/** JSON persistido, ou `null` quando ausente/inválido. */
+	json<T>(name: string): T | null {
+		const artifact = this.storage.readArtifact(this.review.id, name);
+		if (!artifact) return null;
+		try {
+			return JSON.parse(artifact.content) as T;
+		} catch {
+			return null;
+		}
+	}
+
+	/** Reaproveita `ast`/`ai`/`business` do manifesto anterior. */
+	manifestExtras(): {
+		ast?: ManifestAst;
+		ai?: ManifestAi;
+		business?: ManifestBusiness;
+	} {
+		const artifact = this.storage.readArtifact(this.review.id, "manifest.json");
+		if (!artifact) return {};
+		try {
+			const parsed = JSON.parse(artifact.content) as {
+				ast?: ManifestAst;
+				ai?: ManifestAi;
+				business?: ManifestBusiness;
+			};
+			return {
+				ast: parsed.ast,
+				ai: parsed.ai,
+				business: parsed.business ?? undefined,
+			};
+		} catch {
+			return {};
+		}
+	}
+
+	/** Lê o `classification.json` persistido pelo prepare (lança se ausente). */
+	classification(): RunClassification {
+		const artifact = this.storage.readArtifact(this.review.id, "classification.json");
+		if (!artifact) {
+			throw new Error(
+				`Não encontrei a classificação da review. Rode \`bun run houndsman\` (preparar) primeiro.`,
+			);
+		}
+		return JSON.parse(artifact.content) as RunClassification;
+	}
+
+	/** Lê os candidatos Jev persistidos (unavailable se ausente/inválido). */
+	candidates(config: HoundsmanConfig): JevCandidatesFile {
+		const artifact = this.storage.readArtifact(this.review.id, "candidates.json");
+		if (!artifact) return JevCandidatesStore.unavailable("candidates.json ausente");
+		try {
+			return (
+				parseCandidates(JSON.parse(artifact.content), [
+					...config.watchdogIds,
+					GENERAL_WATCHDOG_ID,
+				]) ?? JevCandidatesStore.unavailable("candidates.json inválido")
+			);
+		} catch {
+			return JevCandidatesStore.unavailable("candidates.json inválido");
+		}
+	}
+
+	/** Resumo do contexto persistido (usado quando o staging já foi limpo). */
+	contextSummary(): ContextSummary | null {
+		const artifact = this.storage.readArtifact(
+			this.review.id,
+			"context-summary.json",
+		);
+		if (!artifact) return null;
+		try {
+			return parseContextSummary(JSON.parse(artifact.content));
+		} catch {
+			return null;
+		}
+	}
+
+	/** Modelo de intenção persistido pelo prepare/revisor; `null` quando ausente. */
+	businessSummary(): BusinessSummary | null {
+		const raw = this.json<unknown>(BUSINESS_SUMMARY_FILE);
+		return raw ? parseBusinessSummary(raw) : null;
+	}
+
+	/** Pontos técnicos persistidos pelo `prepare`; `null` quando ausentes. */
+	technicalSummary(): TechnicalSummary | null {
+		const raw = this.json<unknown>(TECHNICAL_SUMMARY_FILE);
+		return raw ? parseTechnicalSummary(raw) : null;
+	}
+
+	/** Fallback para runs antigas: reconstrói os destaques dos artefatos de AST. */
+	technicalFallback(classification: RunClassification): TechnicalSummary {
+		const ast = this.json<{ files?: Record<string, AstAnalysis> }>(
+			"ast-summary.json",
+		);
+		return buildTechnicalSummary({
+			classification,
+			ast: ast?.files ? new Map(Object.entries(ast.files)) : undefined,
+			impact: this.json<AstImpact>("ast-impact.json") ?? undefined,
+			headSha: classification.headSha,
+		});
+	}
+
+	/** Persiste o contexto da PR (bruto + resumo) como artefatos, quando existirem. */
+	persistContext(): void {
+		const raw = this.work.readContextRaw();
+		if (raw !== null) {
+			this.storage.writeArtifact(this.review.id, {
+				name: "context.json",
+				kind: "context",
+				content: raw,
+			});
+		}
+		const summary = this.work.readContextSummaryRaw();
+		if (summary !== null) {
+			this.storage.writeArtifact(this.review.id, {
+				name: "context-summary.json",
+				kind: "context-summary",
+				content: summary,
+			});
+		}
+		const brief = this.work.readContextBriefRaw();
+		if (brief !== null) {
+			this.storage.writeArtifact(this.review.id, {
+				name: "context-brief.md",
+				kind: "context-brief",
+				content: brief,
+			});
+		}
+	}
+
+	/**
+	 * Persiste o `business-summary.json` final: o revisor `general` pode ter
+	 * reescrito o modelo no staging durante a revisão.
+	 */
+	persistBusiness(): BusinessSummary | null {
+		const raw = this.work.readBusinessSummaryRaw();
+		if (raw === null) return this.businessSummary();
+		this.storage.writeArtifact(this.review.id, {
+			name: BUSINESS_SUMMARY_FILE,
+			kind: "business",
+			content: raw.endsWith("\n") ? raw : `${raw}\n`,
+		});
+		const brief = this.work.readBusinessBriefRaw();
+		if (brief !== null) {
+			this.storage.writeArtifact(this.review.id, {
+				name: BUSINESS_BRIEF_FILE,
+				kind: "business-brief",
+				content: brief.endsWith("\n") ? brief : `${brief}\n`,
+			});
+		}
+		try {
+			return parseBusinessSummary(JSON.parse(raw), "reviewer");
+		} catch {
+			return this.businessSummary();
+		}
+	}
+}

package/src/core/engine/run-format.ts

@@ -0,0 +1,4 @@
+/** SHA curto para logs (7 chars, como o git). */
+export function shortSha(sha: string): string {
+	return sha.slice(0, 7);
+}

package/src/core/findings-state.ts

@@ -18,7 +18,7 @@ import {
 	locateAnchor,
 	reanchor,
 } from "./finding-anchor";
-import { type MergedFinding, sanitizeBranch } from "./report-builder";
+import { type FindingBasis, type MergedFinding, sanitizeBranch } from "./report-builder";
 import { systemClock } from "./services/clock";
 import { type FileReader, ProjectFiles } from "./services/project-files";
 import { SEVERITY_ORDER, type Severity, severityRank } from "./types";
@@ -101,6 +101,14 @@ export type FindingState = {
 	message: string;
 	action: string;
 	evidence?: string;
+	/** Gatilho concreto do gap (fora de regra). */
+	scenario?: string;
+	/** Consequência observável do gap. */
+	impact?: string;
+	/** Confiança do revisor (0–1). */
+	confidence?: number;
+	/** Origem do achado: regra, lógica ou domínio. */
+	basis?: FindingBasis;
 	anchor: FindingAnchor | null;
 	/** Commit em que o achado foi observado (base do diff focado do verify). */
 	foundAtSha?: string;
@@ -370,6 +378,10 @@ export function buildStateFromFindings(
 			message: finding.message,
 			action: finding.action,
 			evidence: finding.evidence,
+			scenario: finding.scenario,
+			impact: finding.impact,
+			confidence: finding.confidence,
+			basis: finding.basis,
 			anchor,
 			// Carry-over preserva o `foundAtSha` original; novos/re-reportados usam o head atual.
 			foundAtSha: finding.foundAtSha ?? options.headSha ?? prev?.foundAtSha,

package/src/core/github-review.ts

@@ -225,9 +225,10 @@ export function buildCommentBody(finding: FindingState): string {
 		`${SEVERITY_EMOJI[finding.severity]} **${finding.rule}** · _${finding.severity}_`,
 		"",
 		finding.message,
-		"",
-		`**Ação:** ${finding.action}`,
 	];
+	if (finding.scenario) lines.push("", `**Cenário:** ${finding.scenario}`);
+	if (finding.impact) lines.push("", `**Impacto:** ${finding.impact}`);
+	lines.push("", `**Ação:** ${finding.action}`);
 	if (finding.evidence) lines.push("", "```", finding.evidence, "```");
 	lines.push("", "_— houndsman_");
 	return lines.join("\n");
@@ -247,6 +248,8 @@ export function renderGeneralBody(findings: readonly FindingState[]): string {
 			`- ${SEVERITY_EMOJI[finding.severity]} **${finding.severity}** \`${location}\` — ${finding.rule}`,
 			`  ${finding.message}`,
 		);
+		if (finding.scenario) lines.push(`  **Cenário:** ${finding.scenario}`);
+		if (finding.impact) lines.push(`  **Impacto:** ${finding.impact}`);
 	}
 	return lines.join("\n");
 }

package/src/core/hunt/hunt-runner.ts

@@ -8,9 +8,12 @@
  */
 
 import { readFileSync } from "node:fs";
+import { GENERAL_WATCHDOG_ID } from "../builtins";
+import { type BusinessSummary, parseBusinessSummary } from "../business-summary";
 import { parseWatchdogReport } from "../report-builder";
 import { systemClock } from "../services/clock";
 import type { ReviewWorkArea } from "../storage/work-area";
+import { renderHuntIntentPrompt, renderIntentRetrySuffix } from "./maki-intent-prompt";
 import { renderHuntPrompt, renderRetrySuffix } from "./maki-prompt";
 import {
 	extractJsonObject,
@@ -22,6 +25,12 @@ import { mapPool } from "./pool";
 
 /** Evento de progresso (CLI loga; core não escreve saída). */
 export type HuntEvent =
+	| {
+			type: "intent";
+			status: "start" | "done" | "skipped" | "failed";
+			source?: BusinessSummary["source"];
+			error?: string;
+	  }
 	| { type: "start"; watchdogId: string }
 	| {
 			type: "retry";
@@ -78,6 +87,8 @@ export type HuntReport = {
 	version: 1;
 	engine: "maki";
 	model: string;
+	/** Fonte do modelo de intenção usado na revisão. */
+	business?: BusinessSummary["source"];
 	startedAt: string;
 	finishedAt: string;
 	durationMs: number;
@@ -114,6 +125,9 @@ export class HuntRunner {
 	async run(activeIds: readonly string[]): Promise<HuntReport> {
 		const startedAt = systemClock();
 		const startedMs = Date.now();
+		// Intenção primeiro: o revisor `general` e os demais watchdogs leem o
+		// mesmo `business-summary.json` do staging.
+		const business = await this.runIntent();
 		const watchdogs = await mapPool(activeIds, this.options.concurrency, (id) =>
 			this.runOne(id),
 		);
@@ -122,6 +136,7 @@ export class HuntRunner {
 			version: 1,
 			engine: "maki",
 			model: this.options.model,
+			business,
 			startedAt,
 			finishedAt,
 			durationMs: Date.now() - startedMs,
@@ -130,6 +145,69 @@ export class HuntRunner {
 		};
 	}
 
+	/**
+	 * Pré-passe de intenção (IA embutida). Pula quando o prepare já gerou o
+	 * modelo com IA; falha mantém o determinístico (fail-open).
+	 */
+	private async runIntent(): Promise<BusinessSummary["source"] | undefined> {
+		const existing = this.options.work.readBusinessSummary();
+		if (existing?.source === "ai") {
+			this.emit({ type: "intent", status: "skipped", source: "ai" });
+			return "ai";
+		}
+
+		let brief: string;
+		try {
+			brief = readFileSync(this.options.work.businessPaths.brief, "utf8");
+		} catch {
+			return existing?.source;
+		}
+
+		this.emit({ type: "intent", status: "start" });
+		const basePrompt = renderHuntIntentPrompt({
+			projectName: this.options.projectName,
+			brief,
+		});
+		let lastError = "";
+		for (let attempt = 0; attempt <= this.options.retries; attempt++) {
+			const prompt =
+				attempt === 0
+					? basePrompt
+					: `${basePrompt}\n${renderIntentRetrySuffix(lastError)}`;
+			const result = await this.options.runner.run({
+				prompt,
+				cwd: this.options.root,
+				model: this.options.model,
+				apiKeyEnv: this.options.apiKeyEnv,
+				apiKey: this.options.apiKey,
+				timeoutMs: this.options.timeoutMs,
+			});
+			if (!result.ok) {
+				lastError = result.error;
+				continue;
+			}
+			const raw = extractJsonObject(result.text);
+			if (raw === null) {
+				lastError = "a resposta final não contém um objeto JSON.";
+				continue;
+			}
+			const summary = parseBusinessSummary(
+				{ ...raw, source: "reviewer" },
+				"reviewer",
+			);
+			if (!summary) {
+				lastError = "JSON fora do schema do modelo de intenção.";
+				continue;
+			}
+			this.options.work.writeBusinessSummary(summary);
+			this.emit({ type: "intent", status: "done", source: "reviewer" });
+			return "reviewer";
+		}
+
+		this.emit({ type: "intent", status: "failed", error: lastError });
+		return existing?.source ?? "deterministic";
+	}
+
 	private async runOne(watchdogId: string): Promise<HuntWatchdogResult> {
 		const briefPath = this.options.work.briefFile(watchdogId);
 		let brief: string;
@@ -202,6 +280,18 @@ export class HuntRunner {
 				continue;
 			}
 
+			// O revisor de fluxo devolve o modelo de intenção no JSON (maki não escreve).
+			if (watchdogId === GENERAL_WATCHDOG_ID) {
+				const summary = (raw as Record<string, unknown>).businessSummary;
+				if (typeof summary === "object" && summary !== null) {
+					const parsed = parseBusinessSummary(
+						{ ...(summary as Record<string, unknown>), source: "reviewer" },
+						"reviewer",
+					);
+					if (parsed) this.options.work.writeBusinessSummary(parsed);
+				}
+			}
+
 			this.options.work.writeFinding(
 				watchdogId,
 				`${JSON.stringify(report, null, 2)}\n`,

package/src/core/hunt/index.ts

@@ -32,6 +32,8 @@ export {
 	resolveMakiBinary,
 	uninstallMaki,
 } from "./maki-install";
+export type { HuntIntentPromptInput } from "./maki-intent-prompt";
+export { renderHuntIntentPrompt, renderIntentRetrySuffix } from "./maki-intent-prompt";
 export type { MakiModel } from "./maki-model";
 export {
 	houndsmanKeyEnvFor,

package/src/core/hunt/maki-intent-prompt.ts

@@ -0,0 +1,50 @@
+/**
+ * Prompt do pré-passe de intenção no harness local (`houndsman hunt`).
+ *
+ * Executado antes dos watchdogs, com a IA embutida (maki). O output é o mesmo
+ * `business-summary.json` que a skill grava via subagente.
+ */
+
+import { BUSINESS_SUMMARY_SCHEMA } from "../business-summary";
+
+/** Dados do prompt de intenção. */
+export type HuntIntentPromptInput = {
+	projectName: string;
+	/** Conteúdo de `business-brief.md` (já traz o modelo determinístico). */
+	brief: string;
+};
+
+/** Monta o prompt do passo de intenção. */
+export function renderHuntIntentPrompt(input: HuntIntentPromptInput): string {
+	return [
+		`Você é o passo de intenção da PR do projeto ${input.projectName}.`,
+		"Leia o brief abaixo e devolva **apenas** o JSON do modelo de intenção.",
+		"",
+		"## Contrato do harness local",
+		"",
+		"- Use apenas leitura e busca; **não escreva arquivos** e não rode comandos.",
+		"- Ignore a instrução do brief sobre gravar `outputPath`: o houndsman grava por você.",
+		"- Responda **somente** com um objeto JSON válido (sem markdown, sem texto antes/depois).",
+		'- Inclua `"source": "reviewer"`.',
+		"- Não produza achados, severidade nem recomendações.",
+		"",
+		"### Schema",
+		"",
+		BUSINESS_SUMMARY_SCHEMA,
+		"",
+		"## Brief",
+		"",
+		input.brief.trim(),
+	].join("\n");
+}
+
+/** Sufixo corretivo das retentativas do passo de intenção. */
+export function renderIntentRetrySuffix(error: string): string {
+	return [
+		"",
+		"## Correção obrigatória",
+		"",
+		`A resposta anterior foi rejeitada: ${error}`,
+		"Responda APENAS com o objeto JSON do modelo de intenção, sem markdown.",
+	].join("\n");
+}

package/src/core/hunt/maki-prompt.ts

@@ -7,6 +7,8 @@
  * não altera o brief usado pela skill `/houndsman hunt`.
  */
 
+import { GENERAL_WATCHDOG_ID } from "../builtins";
+
 /** Dados do prompt de um watchdog. */
 export type HuntPromptInput = {
 	projectName: string;
@@ -29,7 +31,11 @@ function outputSchema(watchdogId: string): string {
       "line": 123,
       "message": "o que está errado",
       "action": "o que fazer",
-      "evidence": "trecho que comprova"
+      "evidence": "trecho que comprova",
+      "scenario": "gatilho concreto que expõe o gap (fora de regra)",
+      "impact": "consequência observável",
+      "confidence": 0.8,
+      "basis": "rule | logic | domain"
     }
   ]
 }`;
@@ -48,6 +54,12 @@ export function renderHuntPrompt(input: HuntPromptInput): string {
 		"- Responda **somente** com um objeto JSON válido (sem markdown, sem texto antes/depois).",
 		"- `watchdogId` deve ser exatamente o id acima; use `findings: []` quando não houver achado.",
 		"- `line` deve estar dentro do escopo do diff descrito no brief.",
+		'- Fora de regra, use `basis: "logic" | "domain"`, com `scenario` + `evidence`; sem os dois a severidade máxima é `attention`.',
+		...(input.watchdogId === GENERAL_WATCHDOG_ID
+			? [
+					'- Este é o revisor de fluxo: inclua `businessSummary` (modelo de intenção reconstruído, `source: "reviewer"`) no JSON.',
+				]
+			: []),
 		"",
 		"### Schema",
 		"",