@payconductor/houndsman 0.8.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@payconductor/houndsman",
-	"version": "0.8.0",
+	"version": "0.10.0",
 	"description": "Orquestrador de revisão de Pull Requests: classifica o diff, despacha watchdogs especializados por domínio e consolida o relatório.",
 	"type": "module",
 	"license": "MIT",

package/src/core/ai/ai-client.ts

@@ -7,6 +7,7 @@
  */
 
 import type { ZodType } from "zod";
+import type { AiProviderOptions } from "../config";
 import type { ProjectConfig } from "../project-config";
 import { AiConfigurationError, errorMessage } from "./errors";
 import { ModelFactory } from "./model-factory";
@@ -33,6 +34,8 @@ export type ObjectRequest<T> = {
 	maxSteps?: number;
 	maxOutputTokens?: number;
 	temperature?: number;
+	/** Opções do AI SDK por provider (mescladas com a config do projeto). */
+	providerOptions?: AiProviderOptions;
 	signal?: AbortSignal;
 };
 
@@ -188,6 +191,10 @@ export class AiClient {
 			const provider = await this.requireProvider(model);
 			const response = await provider.generate({
 				...request,
+				providerOptions: mergeProviderOptions(
+					this.project.aiProviderOptions,
+					request.providerOptions,
+				),
 				signal: combineSignals(request.signal, this.project.aiTimeoutMs),
 			});
 			this.budget.record(response.usage);
@@ -204,6 +211,20 @@ export class AiClient {
 	}
 }
 
+/** Mescla opções por provider (o override do chamador vence chave a chave). */
+function mergeProviderOptions(
+	base: AiProviderOptions | undefined,
+	override: AiProviderOptions | undefined,
+): AiProviderOptions | undefined {
+	if (!base) return override;
+	if (!override) return base;
+	const merged: AiProviderOptions = { ...base };
+	for (const [provider, values] of Object.entries(override)) {
+		merged[provider] = { ...base[provider], ...values };
+	}
+	return merged;
+}
+
 /** Combina o sinal do chamador com o timeout configurado. */
 function combineSignals(
 	signal: AbortSignal | undefined,

package/src/core/ai/ai-sdk-model-provider.ts

@@ -10,6 +10,7 @@ import type { LanguageModel, ToolSet } from "ai";
 import { generateText, Output, stepCountIs, tool } from "ai";
 import type { AiProviderKind } from "../config";
 import { AiProviderError } from "./errors";
+import { temperatureApplies } from "./provider-capabilities";
 import {
 	type AiTool,
 	type AiUsage,
@@ -45,6 +46,47 @@ function numberOrZero(value: unknown): number {
 	return typeof value === "number" && Number.isFinite(value) ? value : 0;
 }
 
+/** Argumentos aceitos por `generateText` (inclui `providerOptions` do SDK). */
+type GenerateTextArgs = Parameters<typeof generateText>[0];
+
+/**
+ * Argumentos de `generateText` derivados do pedido (puro — testável sem rede).
+ *
+ * `temperature` só é enviada quando o provider de fato a aplica: em thinking
+ * mode (DeepSeek V4 default) o AI SDK a descarta e emite warning por chamada.
+ */
+export function buildGenerateTextArgs<T>(
+	model: LanguageModel,
+	request: ModelRequest<T>,
+	provider: AiProviderKind,
+	modelId: string,
+) {
+	const tools = request.tools ? toToolSet(request.tools) : undefined;
+	const hasTools = tools !== undefined && Object.keys(tools).length > 0;
+	const maxSteps = request.maxSteps ?? 1;
+	const providerOptions = request.providerOptions
+		? (request.providerOptions as GenerateTextArgs["providerOptions"])
+		: undefined;
+	const temperature =
+		request.temperature !== undefined &&
+		temperatureApplies(provider, modelId, request.providerOptions)
+			? request.temperature
+			: undefined;
+	return {
+		model,
+		system: request.instructions,
+		prompt: request.prompt,
+		...(hasTools ? { tools, stopWhen: stepCountIs(maxSteps) } : {}),
+		...(request.outputSchema
+			? { output: Output.object({ schema: request.outputSchema }) }
+			: {}),
+		...(request.maxOutputTokens ? { maxOutputTokens: request.maxOutputTokens } : {}),
+		...(providerOptions ? { providerOptions } : {}),
+		...(temperature !== undefined ? { temperature } : {}),
+		maxRetries: 0,
+	};
+}
+
 /** Provider de modelo apoiado no AI SDK. */
 export class AiSdkModelProvider implements ModelProvider {
 	constructor(
@@ -54,27 +96,10 @@ export class AiSdkModelProvider implements ModelProvider {
 	) {}
 
 	async generate<T>(request: ModelRequest<T>): Promise<ModelResponse<T>> {
-		const tools = request.tools ? toToolSet(request.tools) : undefined;
-		const hasTools = tools !== undefined && Object.keys(tools).length > 0;
-		const maxSteps = request.maxSteps ?? 1;
-
 		try {
 			const result = await generateText({
-				model: this.model,
-				system: request.instructions,
-				prompt: request.prompt,
-				...(hasTools ? { tools, stopWhen: stepCountIs(maxSteps) } : {}),
-				...(request.outputSchema
-					? { output: Output.object({ schema: request.outputSchema }) }
-					: {}),
-				...(request.maxOutputTokens
-					? { maxOutputTokens: request.maxOutputTokens }
-					: {}),
-				...(request.temperature !== undefined
-					? { temperature: request.temperature }
-					: {}),
+				...buildGenerateTextArgs(this.model, request, this.name, this.modelId),
 				...(request.signal ? { abortSignal: request.signal } : {}),
-				maxRetries: 0,
 			});
 
 			const output = request.outputSchema

package/src/core/ai/features/technical-summarizer.ts

@@ -0,0 +1,43 @@
+/**
+ * Pontos técnicos estruturais via IA (fallback ao builder determinístico).
+ */
+
+import {
+	buildTechnicalPromptPayload,
+	parseTechnicalSummary,
+	type TechnicalPromptInput,
+	type TechnicalSummary,
+} from "../../technical-summary";
+import type { AiClient } from "../ai-client";
+import { technicalInstructions, technicalPrompt } from "../prompts/technical";
+import { type TechnicalSummaryPlan, TechnicalSummarySchema } from "../schemas";
+
+/** Resume a estrutura da mudança em destaques curtos. */
+export class AiTechnicalSummarizer {
+	constructor(private readonly client: AiClient) {}
+
+	/** `true` quando a feature está ligada e há IA disponível. */
+	get enabled(): boolean {
+		return this.client.available && this.client.features.technical;
+	}
+
+	/** Falha-aberto: sem IA ou saída inválida → `null`. */
+	async summarize(input: TechnicalPromptInput): Promise<TechnicalSummary | null> {
+		if (!this.enabled) return null;
+		const result = await this.client.generateObject<TechnicalSummaryPlan>(
+			"technical",
+			{
+				instructions: technicalInstructions(),
+				prompt: technicalPrompt(buildTechnicalPromptPayload(input)),
+				outputSchema: TechnicalSummarySchema,
+				maxSteps: 1,
+			},
+		);
+		if (!result.ok) return null;
+		return parseTechnicalSummary({
+			...result.output,
+			source: "ai",
+			headSha: input.headSha,
+		});
+	}
+}

package/src/core/ai/index.ts

@@ -2,7 +2,7 @@
  * Barrel da camada de IA (`core/ai`).
  */
 
-export type { AiProviderKind } from "../config";
+export type { AiProviderKind, AiProviderOptions } from "../config";
 export type {
 	AiClientOptions,
 	AiCredentialCheck,
@@ -21,6 +21,7 @@ export { AiBriefEnricher } from "./features/brief-enricher";
 export { AiClassifier } from "./features/classifier";
 export { AiContextSummarizer } from "./features/context-summarizer";
 export { AiPreAnalyzer } from "./features/pre-analyzer";
+export { AiTechnicalSummarizer } from "./features/technical-summarizer";
 export { AiVerifier } from "./features/verifier";
 export { hasProviderCredential, ModelFactory } from "./model-factory";
 export {
@@ -35,6 +36,8 @@ export {
 	type ContextSummaryPlan,
 	ContextSummarySchema,
 	SeveritySchema,
+	type TechnicalSummaryPlan,
+	TechnicalSummarySchema,
 	VerifySchema,
 	WatchdogReportSchema,
 } from "./schemas";

package/src/core/ai/prompts/context.ts

@@ -9,9 +9,9 @@ export function contextInstructions(): string {
 	return buildSystem(
 		"Você resume o contexto de uma Pull Request para revisores técnicos.",
 		[
-			"Objetivo em uma frase (máx. 200 caracteres).",
-			"Motivação em uma frase (máx. 240 caracteres).",
-			"Resumo das alterações em até 4 bullets (máx. 160 caracteres cada).",
+			"Objetivo em até 2 frases (máx. 400 caracteres).",
+			"Motivação em até 3 frases (máx. 480 caracteres), com o problema e o impacto esperado.",
+			"Resumo das alterações em até 6 bullets (máx. 240 caracteres cada), focado em comportamento, fluxos e impacto.",
 			"Não invente informação ausente do contexto.",
 		],
 	);

package/src/core/ai/prompts/technical.ts

@@ -0,0 +1,30 @@
+/**
+ * Prompt dos pontos técnicos estruturais (`AiTechnicalSummarizer`).
+ */
+
+import { buildSystem, clip } from "./base";
+
+/** Instruções de sistema dos pontos técnicos. */
+export function technicalInstructions(): string {
+	return buildSystem(
+		"Você descreve a estrutura técnica de uma Pull Request para revisores.",
+		[
+			"Foque em arquitetura e contratos: novos módulos/services, interfaces, providers, repositories, camadas, exports, dependências e impacto.",
+			"NÃO avalie qualidade, NÃO liste achados, bugs ou riscos de revisão.",
+			"NÃO repita a motivação de negócio: isso pertence ao resumo de negócio.",
+			"Use no máximo 6 destaques; `area` é um rótulo curto e `detail` cita paths/símbolos concretos.",
+			"Não invente módulos, símbolos ou dependências ausentes dos dados.",
+		],
+	);
+}
+
+/** Prompt do usuário com o payload estrutural já compactado. */
+export function technicalPrompt(payload: unknown): string {
+	return [
+		"Descreva os pontos técnicos estruturais da mudança abaixo.",
+		"",
+		"```json",
+		clip(JSON.stringify(payload), 14_000),
+		"```",
+	].join("\n");
+}

package/src/core/ai/provider-capabilities.ts

@@ -0,0 +1,45 @@
+/**
+ * Capacidades do provider de IA (puro).
+ *
+ * O AI SDK descarta `temperature`/`topP` e emite warning a cada chamada quando
+ * o DeepSeek opera em thinking mode — que é o default nos modelos V4. Enviar o
+ * parâmetro nesse caso não tem efeito: o adapter o omite.
+ */
+
+import type { AiProviderKind, AiProviderOptions } from "../config";
+
+/** `true` quando o modelo DeepSeek usa thinking sem `providerOptions`. */
+function isDeepSeekV4Model(modelId: string): boolean {
+	return !/(^|[/.])deepseek-(?:chat|reasoner|v[1-3](?:\.\d+)?)(?=[-/:.]|$)/.test(
+		modelId,
+	);
+}
+
+/**
+ * `true` quando o DeepSeek vai operar em thinking mode.
+ *
+ * Espelha a resolução do `@ai-sdk/deepseek`: `thinking.type` explícito manda;
+ * sem ele, V4 (e o alias `deepseek-reasoner`) ligam thinking.
+ */
+export function deepSeekThinkingEnabled(
+	modelId: string,
+	providerOptions: AiProviderOptions | undefined,
+): boolean {
+	const thinking = providerOptions?.deepseek?.thinking as
+		| Record<string, unknown>
+		| undefined;
+	const type = thinking?.type;
+	if (type === "disabled") return false;
+	if (type === "enabled" || type === "adaptive") return true;
+	return modelId === "deepseek-reasoner" || isDeepSeekV4Model(modelId);
+}
+
+/** `true` quando `temperature` chega ao provider (não é descartada). */
+export function temperatureApplies(
+	provider: AiProviderKind,
+	modelId: string,
+	providerOptions?: AiProviderOptions,
+): boolean {
+	if (provider !== "deepseek") return true;
+	return !deepSeekThinkingEnabled(modelId, providerOptions);
+}

package/src/core/ai/schemas.ts

@@ -22,12 +22,28 @@ export const ContextSummarySchema = z.object({
 			head: z.string().optional(),
 		})
 		.optional(),
-	objective: z.string().max(200).optional(),
-	motivation: z.string().max(240).optional(),
-	changeSummary: z.array(z.string().max(160)).max(4).optional(),
+	objective: z.string().max(400).optional(),
+	motivation: z.string().max(480).optional(),
+	changeSummary: z.array(z.string().max(240)).max(6).optional(),
 });
 export type ContextSummaryPlan = z.infer<typeof ContextSummarySchema>;
 
+/** Pontos técnicos estruturais do resumo final (`technical-summary.json`). */
+export const TechnicalSummarySchema = z.object({
+	/** Parágrafo curto de abertura (opcional). */
+	overview: z.string().max(600).optional(),
+	highlights: z
+		.array(
+			z.object({
+				area: z.string().min(1).max(80),
+				detail: z.string().min(1).max(400),
+			}),
+		)
+		.max(8)
+		.default([]),
+});
+export type TechnicalSummaryPlan = z.infer<typeof TechnicalSummarySchema>;
+
 /** Plano de revisão sugerido por IA para um brief. */
 export const BriefPlanSchema = z.object({
 	focus: z.array(z.string()).max(5).default([]),

package/src/core/ai/types.ts

@@ -6,7 +6,7 @@
  */
 
 import type { ZodType, ZodTypeAny } from "zod";
-import type { AiProviderKind } from "../config";
+import type { AiProviderKind, AiProviderOptions } from "../config";
 
 /** Uso de tokens de uma chamada (ou acumulado de uma review). */
 export type AiUsage = {
@@ -52,6 +52,8 @@ export type ModelRequest<T> = {
 	maxSteps?: number;
 	maxOutputTokens?: number;
 	temperature?: number;
+	/** Opções do AI SDK por provider (repassadas ao SDK sem interpretação). */
+	providerOptions?: AiProviderOptions;
 	signal?: AbortSignal;
 };
 

package/src/core/brief.ts

@@ -27,15 +27,36 @@ export const PROCEDURE: readonly string[] = [
 	'5. **CONCLUDE** — grave o JSON no caminho de output, com `reviewedFiles` preenchido. Sem achados → `"findings": []` (arquivo obrigatório). Não escreva markdown livre.',
 ];
 
+/** Limites do contexto injetado em cada brief (o resumo final é maior). */
+const BRIEF_CONTEXT_LIMITS = {
+	objective: 200,
+	motivation: 240,
+	changeSummaryItem: 160,
+	changeSummaryItems: 4,
+} as const;
+
 /** Bloco de contexto da PR, injetado no brief de cada watchdog. */
 export function renderBriefContext(context: WatchdogRenderContext): string[] {
 	const lines = ["## Contexto da PR", ""];
-	if (context.objective) lines.push(`**Objetivo:** ${context.objective}`);
-	if (context.motivation) lines.push(`**Motivação:** ${context.motivation}`);
-	const changeSummary = context.changeSummary ?? [];
+	if (context.objective) {
+		lines.push(
+			`**Objetivo:** ${shorten(context.objective, BRIEF_CONTEXT_LIMITS.objective)}`,
+		);
+	}
+	if (context.motivation) {
+		lines.push(
+			`**Motivação:** ${shorten(context.motivation, BRIEF_CONTEXT_LIMITS.motivation)}`,
+		);
+	}
+	const changeSummary = (context.changeSummary ?? []).slice(
+		0,
+		BRIEF_CONTEXT_LIMITS.changeSummaryItems,
+	);
 	if (changeSummary.length > 0) {
 		lines.push("", "**Resumo das alterações:**", "");
-		for (const item of changeSummary) lines.push(`- ${item}`);
+		for (const item of changeSummary) {
+			lines.push(`- ${shorten(item, BRIEF_CONTEXT_LIMITS.changeSummaryItem)}`);
+		}
 	}
 	lines.push("");
 	return lines;

package/src/core/commands/scaffold.ts

@@ -219,10 +219,14 @@ export type HoundsmanAst = {
 /** Providers suportados pela camada de IA. */
 export type AiProviderKind = "deepseek" | "openai" | "anthropic";
 
+/** Opções do AI SDK por provider (repassadas sem interpretação). */
+export type AiProviderOptions = Record<string, Record<string, unknown>>;
+
 /** Features de IA do fluxo normal (todas fail-open). */
 export type HoundsmanAiFeatures = {
 	context?: boolean;
 	brief?: boolean;
+	technical?: boolean;
 	classification?: boolean;
 	preAnalysis?: boolean;
 	verify?: boolean;
@@ -245,6 +249,7 @@ export type HoundsmanAi = {
 	maxSteps?: number;
 	maxOutputTokens?: number;
 	temperature?: number;
+	providerOptions?: AiProviderOptions;
 	timeoutMs?: number;
 	maxCallsPerReview?: number;
 	maxTokensPerReview?: number;

package/src/core/config.ts

@@ -57,12 +57,23 @@ export type HoundsmanConcurrency = {
 /** Providers suportados pela camada de IA. */
 export type AiProviderKind = "deepseek" | "openai" | "anthropic";
 
+/**
+ * Opções do AI SDK indexadas pelo id do provider
+ * (`{ deepseek: { thinking: { type: "disabled" } } }`).
+ *
+ * O motor não interpreta o conteúdo: só repassa. Use para controlar
+ * thinking/reasoning sem acoplar a config a um provider específico.
+ */
+export type AiProviderOptions = Record<string, Record<string, unknown>>;
+
 /** 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;
+	/** Gera os pontos técnicos estruturais do resumo final. */
+	technical?: boolean;
 	/** Classifica arquivos que nenhum watchdog casou. */
 	classification?: boolean;
 	/** Gera candidatos de pré-análise (substitui o Jev quando disponível). */
@@ -94,8 +105,13 @@ export type HoundsmanAi = {
 	maxSteps?: number;
 	/** Teto de tokens de saída por chamada. */
 	maxOutputTokens?: number;
-	/** Temperatura (default: 0). */
+	/**
+	 * Temperatura (default: 0). Ignorada quando o provider usa thinking
+	 * (DeepSeek V4 liga thinking por default) — nesse caso o motor não a envia.
+	 */
 	temperature?: number;
+	/** Opções do AI SDK por provider (repassadas sem interpretação). */
+	providerOptions?: AiProviderOptions;
 	/** Timeout por chamada em ms (default: 120_000). */
 	timeoutMs?: number;
 	/** Teto de chamadas por review (default: 40). */

package/src/core/git-runner.ts

@@ -24,8 +24,15 @@ export type GitRunner = (args: string[]) => GitResult;
  * certo. Sem `cwd`, herda o diretório do processo (default).
  */
 export function createGitRunner(cwd?: string): GitRunner {
+	// `core.longpaths` evita "Filename too long" no checkout de worktrees
+	// dentro de caminhos fundos (MAX_PATH do Windows). O `-c` é propagado aos
+	// subprocessos do git via GIT_CONFIG_PARAMETERS.
+	const config =
+		process.platform === "win32"
+			? ["-c", "core.quotepath=false", "-c", "core.longpaths=true"]
+			: ["-c", "core.quotepath=false"];
 	return (args) => {
-		const result = Bun.spawnSync(["git", "-c", "core.quotepath=false", ...args], {
+		const result = Bun.spawnSync(["git", ...config, ...args], {
 			cwd,
 			stdout: "pipe",
 			stderr: "pipe",

package/src/core/orchestrator.ts

@@ -23,6 +23,7 @@ import { AiBriefEnricher } from "./ai/features/brief-enricher";
 import { AiClassifier } from "./ai/features/classifier";
 import { AiContextSummarizer } from "./ai/features/context-summarizer";
 import { AiPreAnalyzer } from "./ai/features/pre-analyzer";
+import { AiTechnicalSummarizer } from "./ai/features/technical-summarizer";
 import type { BriefPlan } from "./ai/schemas";
 import { assetPath, OUTPUT_FORMAT_FILE } from "./assets";
 import type { AstService } from "./ast/service";
@@ -56,6 +57,7 @@ import {
 	OUTPUT_FORMAT_PATH,
 	REVIEW_FILE,
 	REVIEW_RESUME_FILE,
+	TECHNICAL_SUMMARY_FILE,
 } from "./paths";
 import { ProjectConfig } from "./project-config";
 import { BriefRenderer } from "./renderers/brief-renderer";
@@ -79,6 +81,11 @@ import { systemClock } from "./services/clock";
 import { GitRepository } from "./services/git-repository";
 import type { ReviewRecord, StorageProvider } from "./storage/types";
 import { ReviewWorkArea } from "./storage/work-area";
+import {
+	buildTechnicalSummary,
+	parseTechnicalSummary,
+	type TechnicalSummary,
+} from "./technical-summary";
 import type { WatchdogMeta } from "./types";
 import { findWatchdog } from "./watchdog-registry";
 
@@ -483,6 +490,50 @@ async function resolveContextSummary(
 	return summary;
 }
 
+/**
+ * Pontos técnicos estruturais: IA quando disponível e, sempre, um fallback
+ * determinístico a partir da classificação/AST. Persistido para auditoria —
+ * o `finalize` apenas o consome.
+ */
+async function resolveTechnicalSummary(
+	ctx: ReviewContext,
+	ai: AiClient | undefined,
+	opts: ReviewOptions,
+	input: {
+		branch: string;
+		classification: RunClassification;
+		context: ContextSummary | null;
+		ast?: ReadonlyMap<string, AstAnalysis>;
+		impact?: AstImpact;
+		domains: readonly string[];
+	},
+): Promise<TechnicalSummary> {
+	const fallback = buildTechnicalSummary({
+		classification: input.classification,
+		ast: input.ast,
+		impact: input.impact,
+		headSha: input.classification.headSha,
+	});
+	const summary =
+		ai && !opts.noAi
+			? ((await new AiTechnicalSummarizer(ai).summarize({
+					branch: input.branch,
+					context: input.context,
+					classification: input.classification,
+					ast: input.ast,
+					impact: input.impact,
+					headSha: input.classification.headSha,
+					domains: input.domains,
+				})) ?? fallback)
+			: fallback;
+	ctx.storage.writeArtifact(ctx.review.id, {
+		name: TECHNICAL_SUMMARY_FILE,
+		kind: "technical",
+		content: `${JSON.stringify(summary, null, 2)}\n`,
+	});
+	return summary;
+}
+
 /**
  * Planos de revisão por watchdog (uma chamada por brief, concorrência
  * limitada). Sem IA/chave/feature, devolve mapa vazio e o brief fica igual.
@@ -574,13 +625,30 @@ export async function prepare(
 		return { messages };
 	}
 
+	const { classification, diff } = scope;
+
+	// Run recém-criada e sem nenhum arquivo alterado: não persiste uma "run
+	// vazia" na lista. Acontece quando o comando roda no clone principal sem
+	// `--pr`/`--worktree` (ex.: `houndsman` na `main` logo após revisar uma PR).
+	// Run com artefatos anteriores (contexto, revisão) continua existindo.
+	if (Object.keys(classification.files).length === 0) {
+		const fresh = ctx.storage.listArtifacts(ctx.review.id).length === 0;
+		if (fresh) {
+			ctx.work.clean();
+			ctx.storage.deleteReview(ctx.review.id);
+			messages.push(
+				`Nenhuma alteração entre ${opts.base}...${opts.head} — nenhuma run criada.`,
+			);
+			return { messages };
+		}
+	}
+
 	// Marca o run como "revisando" (reinicia o ciclo) — a UI mostra o status.
 	writeRunStatus(ctx.storage, ctx.review.id, {
 		status: "reviewing",
 		resetStartedAt: true,
 	});
 
-	const { classification, diff } = scope;
 	await applyAiClassification(classification, config, ai, opts);
 	ctx.storage.writeArtifact(ctx.review.id, {
 		name: "classification.json",
@@ -645,6 +713,14 @@ export async function prepare(
 
 	persistContext(ctx);
 	const context = await resolveContextSummary(ctx, ai, opts);
+	await resolveTechnicalSummary(ctx, ai, opts, {
+		branch,
+		classification,
+		context,
+		ast: astAnalyses,
+		impact: astImpact,
+		domains: activeIds.map((id) => findWatchdog(config, id)?.name ?? id),
+	});
 
 	const manifestAst: ManifestAst | undefined = astAnalyses
 		? {
@@ -853,6 +929,40 @@ function readPersistedContextSummary(ctx: ReviewContext): ContextSummary | null
 	}
 }
 
+/** JSON persistido, ou `null` quando ausente/inválido. */
+function readArtifactJson<T>(ctx: ReviewContext, name: string): T | null {
+	const artifact = ctx.storage.readArtifact(ctx.review.id, name);
+	if (!artifact) return null;
+	try {
+		return JSON.parse(artifact.content) as T;
+	} catch {
+		return null;
+	}
+}
+
+/** Pontos técnicos persistidos pelo `prepare`; `null` quando ausentes. */
+function readPersistedTechnicalSummary(ctx: ReviewContext): TechnicalSummary | null {
+	const raw = readArtifactJson<unknown>(ctx, TECHNICAL_SUMMARY_FILE);
+	return raw ? parseTechnicalSummary(raw) : null;
+}
+
+/** Fallback para runs antigas: reconstrói os destaques dos artefatos de AST. */
+function buildTechnicalFallback(
+	ctx: ReviewContext,
+	classification: RunClassification,
+): TechnicalSummary {
+	const ast = readArtifactJson<{ files?: Record<string, AstAnalysis> }>(
+		ctx,
+		"ast-summary.json",
+	);
+	return buildTechnicalSummary({
+		classification,
+		ast: ast?.files ? new Map(Object.entries(ast.files)) : undefined,
+		impact: readArtifactJson<AstImpact>(ctx, "ast-impact.json") ?? undefined,
+		headSha: classification.headSha,
+	});
+}
+
 /**
  * Grava um `review.<watchdog>.md` por watchdog com achados e devolve o índice.
  * Mantém o `review.md` consolidado navegável em PRs grandes (centenas de achados).
@@ -1028,6 +1138,8 @@ export function finalize(
 
 	persistContext(ctx);
 	const context = ctx.work.readContextSummary() ?? readPersistedContextSummary(ctx);
+	const technical =
+		readPersistedTechnicalSummary(ctx) ?? buildTechnicalFallback(ctx, classification);
 	const nameOf = (id: string): string => findWatchdog(config, id)?.name ?? id;
 	const domains = writeDomainReports(
 		ctx,
@@ -1061,7 +1173,7 @@ export function finalize(
 			context,
 			classification,
 			findings: merged,
-			nameOf,
+			technical,
 		}),
 	});
 

package/src/core/paths.ts

@@ -55,3 +55,6 @@ export const REVIEW_FILE = "review.md";
 
 /** Resumo final da review (artefato `review-resume.md`) — leitura humana apenas. */
 export const REVIEW_RESUME_FILE = "review-resume.md";
+
+/** Pontos técnicos estruturais usados no resumo final (`technical-summary.json`). */
+export const TECHNICAL_SUMMARY_FILE = "technical-summary.json";