@payconductor/houndsman 0.7.0 → 0.10.0

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

@@ -0,0 +1,204 @@
+/**
+ * Resolução do workspace de uma revisão (engine).
+ *
+ * Decide onde a revisão roda: clone principal, worktree explícito (`--worktree`)
+ * ou worktree criado/reusado para uma PR (`--pr`). Devolve a raiz operacional,
+ * a raiz do clone principal (identidade/config) e as refs do diff.
+ */
+
+import { basename, dirname, resolve } from "node:path";
+import { createGitRunner } from "../git-runner";
+import { createGhRunner, type GhRunner } from "../services/gh-client";
+import { GitRepository } from "../services/git-repository";
+import { PrResolver } from "../services/pr-resolver";
+import { WorktreeManager } from "../services/worktree-manager";
+import { resolveWorktreesRoot } from "../storage/paths";
+import { resolveRepoIdentity } from "../storage/repo-identity";
+import type { RepoIdentity } from "../storage/types";
+
+/** Pedido de resolução (flags do CLI). */
+export type WorkspaceRequest = {
+	cwd: string;
+	base: string;
+	head: string;
+	branch?: string;
+	/** Número da PR (`--pr`). */
+	pr?: number;
+	/** Worktree já existente (`--worktree`). */
+	worktree?: string;
+};
+
+/** Dependências injetáveis (testes). */
+export type WorkspaceDeps = {
+	ghRunner?: GhRunner;
+	/** `config.worktrees.location` (default: `workspace`). */
+	worktreesLocation?: string;
+	/** Override explícito da raiz de worktrees (testes). */
+	worktreesRoot?: string;
+};
+
+/** Workspace resolvido para a revisão. */
+export type ResolvedWorkspace = {
+	/** Onde os arquivos e o git da revisão são lidos. */
+	root: string;
+	/** Clone principal (identidade estável + camada/config). */
+	mainRoot: string;
+	repo: RepoIdentity;
+	git: GitRepository;
+	branch: string;
+	base: string;
+	head: string;
+	prNumber?: number;
+	worktreePath?: string;
+	/** Avisos para o CLI (fetch parcial, reuso etc.). */
+	messages: string[];
+};
+
+/**
+ * Raiz do clone principal a partir de um worktree linkado.
+ * `--git-common-dir` aponta para `<main>/.git`; qualquer outro formato usa `fallback`.
+ */
+export function mainRootOf(git: GitRepository, fallback: string): string {
+	const common = git.gitCommonDir();
+	if (!common) return fallback;
+	const normalized = common.replace(/[\\/]+$/, "");
+	return basename(normalized).toLowerCase() === ".git" ? dirname(normalized) : fallback;
+}
+
+/** Cria um repositório git enraizado em `root`. */
+function repoAt(root: string): GitRepository {
+	return new GitRepository(createGitRunner(root));
+}
+
+/** Compara paths levando em conta o filesystem (Windows é case-insensitive). */
+function samePath(a: string, b: string): boolean {
+	const norm = (path: string): string => {
+		const absolute = resolve(path).replace(/[\\/]+$/, "");
+		return process.platform === "win32" ? absolute.toLowerCase() : absolute;
+	};
+	return norm(a) === norm(b);
+}
+
+/** Resolve o workspace efetivo da revisão. */
+export function resolveReviewWorkspace(
+	request: WorkspaceRequest,
+	deps: WorkspaceDeps = {},
+): ResolvedWorkspace {
+	const messages: string[] = [];
+	const cwdGit = repoAt(request.cwd);
+	const cwdRoot = resolve(cwdGit.rootPath() ?? request.cwd);
+	const mainRoot = resolve(mainRootOf(cwdGit, cwdRoot));
+	const mainGit = repoAt(mainRoot);
+
+	// Worktree explícito: a revisão roda onde o usuário mandou.
+	if (request.worktree) {
+		const path = resolve(request.cwd, request.worktree);
+		const git = repoAt(path);
+		const root = git.rootPath();
+		if (!root) {
+			throw new Error(`'${path}' não é um worktree/repositório git válido.`);
+		}
+		const repo = resolveRepoIdentity(git, root);
+		const branch = request.branch ?? git.currentBranch();
+		if (!branch) {
+			throw new Error(
+				`Worktree '${root}' está em detached HEAD. Informe --branch <nome>.`,
+			);
+		}
+		return {
+			root,
+			mainRoot: mainRootOf(git, repo.root),
+			repo,
+			git,
+			branch,
+			base: request.base,
+			head: request.head,
+			worktreePath: root,
+			messages,
+		};
+	}
+
+	// PR: cria/reusa o worktree detached no commit da PR.
+	if (request.pr !== undefined) {
+		const repo = resolveRepoIdentity(mainGit, mainRoot);
+		const resolver = new PrResolver(
+			deps.ghRunner ?? createGhRunner(mainRoot),
+			mainGit,
+		);
+		const resolved = resolver.resolve(request.pr);
+		if (!resolved.ok) {
+			throw new Error(
+				`Não foi possível resolver a PR #${request.pr}: ${resolved.detail}`,
+			);
+		}
+		const { pr } = resolved;
+		const refs = resolver.prepareRefs(pr);
+		if (refs.warning) messages.push(`GitHub: ${refs.warning}`);
+
+		const manager = new WorktreeManager(mainGit, {
+			repoKey: repo.key,
+			repoRoot: mainRoot,
+			baseDir:
+				deps.worktreesRoot ??
+				resolveWorktreesRoot(deps.worktreesLocation, mainRoot),
+		});
+		const worktree = manager.ensure({ branch: pr.headRefName, ref: refs.head });
+		const worktreePath = resolve(worktree.path);
+		messages.push(
+			`Worktree ${worktree.created ? "criado" : "reutilizado"}: ${worktreePath}`,
+			`PR #${pr.number} — ${pr.headRefName} → ${pr.baseRefName} @ ${refs.head.slice(0, 7)}.`,
+		);
+
+		return {
+			root: worktreePath,
+			mainRoot,
+			repo,
+			git: repoAt(worktreePath),
+			branch: pr.headRefName,
+			base: refs.base,
+			head: refs.head,
+			prNumber: pr.number,
+			worktreePath,
+			messages,
+		};
+	}
+
+	// Já estamos dentro de um worktree: ele é a raiz operacional.
+	const repo = resolveRepoIdentity(mainGit, mainRoot);
+	if (!samePath(cwdRoot, mainRoot)) {
+		const branch = request.branch ?? cwdGit.currentBranch();
+		if (!branch) {
+			throw new Error(
+				`Worktree '${cwdRoot}' está em detached HEAD. Informe --branch <nome>.`,
+			);
+		}
+		messages.push(`Usando o worktree atual: ${cwdRoot}`);
+		return {
+			root: cwdRoot,
+			mainRoot,
+			repo,
+			git: cwdGit,
+			branch,
+			base: request.base,
+			head: request.head,
+			worktreePath: cwdRoot,
+			messages,
+		};
+	}
+
+	// Clone principal.
+	const branch = request.branch ?? mainGit.currentBranch();
+	if (!branch) {
+		throw new Error("Não foi possível detectar a branch. Use --branch <nome>.");
+	}
+	return {
+		root: mainRoot,
+		mainRoot,
+		repo,
+		git: mainGit,
+		branch,
+		base: request.base,
+		head: request.head,
+		messages,
+	};
+}

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/jev/jev-detector.ts

@@ -9,6 +9,7 @@
  */
 
 import { readFileSync } from "node:fs";
+import { join } from "node:path";
 import { collectDiff, type DiffSource } from "../diff-source";
 import type { ClassificationResult } from "../file-classifier";
 import type { WatchdogMeta } from "../types";
@@ -47,11 +48,18 @@ export class JevDetector {
 
 	private readonly client: JevClient;
 	private readonly questions: JevQuestionFactory;
+	/** Raiz dos arquivos (worktree ou clone principal). */
+	private readonly root: string;
 
 	/** Construtor que recebe o cliente e o registry de watchdogs (injeção). */
-	constructor(client: JevClient, registry: Record<string, WatchdogMeta>) {
+	constructor(
+		client: JevClient,
+		registry: Record<string, WatchdogMeta>,
+		root: string = process.cwd(),
+	) {
 		this.client = client;
 		this.questions = new JevQuestionFactory(registry);
+		this.root = root;
 	}
 
 	/** Roda a pré-análise e devolve os candidatos (ordenados por confiança desc). */
@@ -157,7 +165,7 @@ export class JevDetector {
 
 	private readHeader(filePath: string): string {
 		try {
-			return readFileSync(filePath, "utf8")
+			return readFileSync(join(this.root, filePath), "utf8")
 				.split("\n")
 				.slice(0, JevDetector.HEADER_LINES)
 				.join("\n");

package/src/core/orchestrator.ts

@@ -16,13 +16,16 @@
  * review.<watchdog>.md, context e context-summary.
  */
 
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import type { AiClient } from "./ai/ai-client";
 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";
 import type { AstAnalysis, AstFileBrief, AstImpact } from "./ast/types";
 import {
@@ -39,7 +42,6 @@ import { ReviewScopeResolver, type RunClassification } from "./engine/review-sco
 import { ENV_NAMES } from "./env";
 import type { BudgetSelection, ClassificationResult } from "./file-classifier";
 import { buildStateFromFindings, fileReader } from "./findings-state";
-import { resolveSha } from "./git-revision";
 import { syncResolvedThreads } from "./github-review";
 import {
 	type JevCandidate,
@@ -55,8 +57,8 @@ import {
 	OUTPUT_FORMAT_PATH,
 	REVIEW_FILE,
 	REVIEW_RESUME_FILE,
+	TECHNICAL_SUMMARY_FILE,
 } from "./paths";
-import { currentBranch } from "./pr-context";
 import { ProjectConfig } from "./project-config";
 import { BriefRenderer } from "./renderers/brief-renderer";
 import {
@@ -76,8 +78,14 @@ import {
 } from "./report-builder";
 import { writeRunStatus } from "./run-status";
 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";
 
@@ -95,6 +103,12 @@ export type ReviewOptions = {
 	full: boolean;
 	/** Desativa as features de IA do fluxo normal (hunt não usa esta flag). */
 	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). */
@@ -112,19 +126,49 @@ export function defaultOptions(): ReviewOptions {
 	};
 }
 
-/** Contexto de uma run: storage + review + staging. */
+/** 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;
 };
 
 /** Cria o contexto de uma review existente. */
 export function reviewContext(
 	storage: StorageProvider,
 	review: ReviewRecord,
+	workspace: ReviewWorkspaceContext = {},
 ): ReviewContext {
-	return { storage, review, work: new ReviewWorkArea(review) };
+	const root = workspace.root ?? process.cwd();
+	return {
+		storage,
+		review,
+		work: new ReviewWorkArea(review),
+		root,
+		mainRoot: workspace.mainRoot ?? root,
+		git: workspace.git ?? new GitRepository(),
+	};
+}
+
+/**
+ * Schema do output: relativo à raiz da review quando a camada existe; no
+ * worktree sem camada, cai para o asset embarcado (caminho absoluto legível).
+ */
+function outputFormatPathFor(ctx: ReviewContext): string {
+	if (existsSync(join(ctx.root, OUTPUT_FORMAT_PATH))) return OUTPUT_FORMAT_PATH;
+	return ctx.review.worktreePath ? assetPath(OUTPUT_FORMAT_FILE) : OUTPUT_FORMAT_PATH;
 }
 
 // ---------------------------------------------------------------------------
@@ -225,7 +269,8 @@ function writeBriefs(
 			deleted: classification.deleted,
 			branch,
 			outputPath: work.findingFile(id),
-			outputFormatPath: OUTPUT_FORMAT_PATH,
+			outputFormatPath: outputFormatPathFor(ctx),
+			worktree: ctx.review.worktreePath,
 			docs,
 			context,
 			candidates: candidates.filter((c) => c.watchdogId === id),
@@ -277,7 +322,7 @@ async function resolveCandidates(
 				const def = findWatchdog(config, id);
 				if (!def) continue;
 				const inputs = files.slice(0, 5).flatMap((file) => {
-					const snippet = readSnippet(file);
+					const snippet = readSnippet(ctx.root, file);
 					return snippet ? [{ file, snippet }] : [];
 				});
 				candidates.push(
@@ -314,6 +359,7 @@ async function resolveCandidates(
 		const detector = new JevDetector(
 			client,
 			config.watchdogs as Record<string, WatchdogMeta>,
+			ctx.root,
 		);
 		const result = await detector.detect(classification, opts.base, opts.head, {
 			diff,
@@ -377,9 +423,10 @@ function budgetMessage(
 }
 
 /** Primeiras 80 linhas de um arquivo (pré-análise por IA; fail-open). */
-function readSnippet(file: string): string | null {
+function readSnippet(root: string, file: string): string | null {
 	try {
-		return readFileSync(file, "utf8").split("\n").slice(0, 80).join("\n");
+		const path = join(root, file);
+		return readFileSync(path, "utf8").split("\n").slice(0, 80).join("\n");
 	} catch {
 		return null;
 	}
@@ -443,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.
@@ -507,12 +598,13 @@ export async function prepare(
 	ctx.storage.updateReview(ctx.review.id, { base: opts.base, head: opts.head });
 
 	// Marca o commit revisado e decide entre completo, incremental ou no-op.
-	const headSha = resolveSha(opts.head);
+	const headSha = ctx.git.resolveSha(opts.head);
 	const previous = ctx.storage.readFindings(ctx.review.id);
 	const scope = await new ReviewScopeResolver(
 		opts,
 		config,
 		opts.noAst ? undefined : ast,
+		ctx.git,
 	).resolve(previous, headSha);
 
 	// Mesmo commit já revisado: preserva artefatos e triagem, sem re-revisar.
@@ -533,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",
@@ -604,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
 		? {
@@ -812,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).
@@ -937,7 +1088,7 @@ export function finalize(
 	// (`reviewed.headSha`) habilita o review incremental e o diff focado do verify.
 	const state = buildStateFromFindings(merged, {
 		branch,
-		readFile: fileReader(process.cwd()),
+		readFile: fileReader(ctx.root),
 		previous: ctx.storage.readFindings(ctx.review.id),
 		reviewedPaths: new Set([
 			...reports.flatMap((report) => report.reviewedFiles),
@@ -987,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,
@@ -1020,7 +1173,7 @@ export function finalize(
 			context,
 			classification,
 			findings: merged,
-			nameOf,
+			technical,
 		}),
 	});
 
@@ -1042,6 +1195,14 @@ export function finalize(
 }
 
 /** Resolve a branch (opção explícita ou a atual do git). */
-export function resolveBranch(opts: ReviewOptions): string {
-	return opts.branch ?? currentBranch();
+export function resolveBranch(
+	opts: ReviewOptions,
+	git: GitRepository = new GitRepository(),
+): string {
+	if (opts.branch) return opts.branch;
+	const branch = git.currentBranch();
+	if (!branch) {
+		throw new Error("Não foi possível detectar a branch. Use --branch <nome>.");
+	}
+	return branch;
 }

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

package/src/core/pr-context.ts

@@ -229,13 +229,17 @@ export function renderContextBrief(
 
 	lines.push("## Regras", "");
 	lines.push(
-		"- **Seja curto** — o resumo abre o relatório e entra em **todos** os briefs.",
+		"- O resumo abre o relatório e o resumo final; nos briefs ele é recortado.",
 	);
 	lines.push("- Baseie-se **somente** no `context.json` — não invente intenção.");
-	lines.push("- `objective`: 1 frase (≤ 200 caracteres) sobre o que a PR entrega.");
-	lines.push("- `motivation`: 1 frase (≤ 240 caracteres) sobre o porquê.");
 	lines.push(
-		"- `changeSummary`: no máximo 4 bullets (≤ 160 caracteres cada), focados em comportamento — não liste arquivos.",
+		"- `objective`: até 2 frases (≤ 400 caracteres) sobre o que a PR entrega.",
+	);
+	lines.push(
+		"- `motivation`: até 3 frases (≤ 480 caracteres) sobre o porquê e o impacto.",
+	);
+	lines.push(
+		"- `changeSummary`: no máximo 6 bullets (≤ 240 caracteres cada), focados em comportamento — não liste arquivos.",
 	);
 	lines.push(
 		"- NÃO copie a descrição da PR: sintetize. Copie `source` do contexto bruto.",
@@ -253,7 +257,8 @@ const CONTEXT_SUMMARY_TEMPLATE = {
 		base: "main",
 		head: "feature/x",
 	},
-	objective: "O que a PR entrega, em 1 frase.",
-	motivation: "Por que a mudança é necessária, em 1-2 frases.",
+	objective: "O que a PR entrega, em 1-2 frases.",
+	motivation:
+		"Por que a mudança é necessária, com o problema e o impacto (até 3 frases).",
 	changeSummary: ["Bullet de comportamento 1", "Bullet de comportamento 2"],
 };