@payconductor/houndsman 0.13.0 → 0.16.0

package/README.md

@@ -15,6 +15,11 @@ agente especialista por domínio que audita o diff · **review/revisão** = o pr
 **Jev** = pré-análise opcional. O vocabulário completo (brief, findings, manifest, budget,
 overflow, churn, candidato…) está em [`docs/GLOSSARY.md`](docs/GLOSSARY.md).
 
+> Toda revisão tem duas etapas fixas: um **modelo de intenção** da PR
+> (`business-summary.json`) e o revisor de fluxo **`general`**. Nenhum dos dois é
+> configurável — o primeiro enriquece os briefs; o segundo procura gaps de lógica/domínio,
+> não só violações de regra.
+
 ---
 
 ## Como iniciar
@@ -128,7 +133,7 @@ mostra o worktree ativo de cada PR e permite criá-lo pela sidebar.
    ├─ Passo 0  contexto da PR (gh, opcional)
    ├─ Passo 1  classifica o diff → briefs por watchdog (incremental quando possível)
    ├─ Passo 2  N subagentes revisam em paralelo
-   ├─ Passo 3  consolida em review.md + triagem no storage
+   ├─ Passo 3  grava o resumo final (review-resume.md) + triagem no storage
    ├─ Passo 4  valida na UI (server) e marca os achados a executar
    ├─ Passo 5  fix corrige o grupo atual → status fix_done
    └─ Passo 6  verify confere o que resolveu, sem re-revisar

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@payconductor/houndsman",
-	"version": "0.13.0",
+	"version": "0.16.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/cli/commands/compare-command.ts

@@ -0,0 +1,112 @@
+/**
+ * Comando `compare` — teste A/B entre duas runs (por slug ou branch+variantes).
+ *
+ * Exemplo:
+ *   houndsman compare --branch feature/x --a baseline --b otimizado
+ *   houndsman compare feature-x--baseline-1a2b3c feature-x--otimizado-9f8e7d
+ */
+
+import { listRunsForCompare, runCompare } from "../../core/commands/compare";
+import { ArgParser } from "../arg-parser";
+import type { CliContext, Command } from "./command";
+
+/** Flags com valor (não entram nos positionais). */
+const VALUE_FLAGS = new Set(["--branch", "--a", "--b", "--config"]);
+
+export const COMPARE_HELP = `Uso: houndsman compare [<slugA> <slugB>] [flags]
+
+Compara duas runs da mesma branch e grava o relatório na run B.
+
+Flags:
+  --branch <nome>   Branch alvo (default: a atual do git)
+  --a <variante>    Rótulo A (default: run principal)
+  --b <variante>    Rótulo B (obrigatório sem slugs)
+  --list            Lista as runs/variantes com contagem por severidade
+  --json            Saída JSON (sem markdown)
+
+Exemplos:
+  houndsman compare --branch feature/x --a baseline --b otimizado
+  houndsman compare feature-x--baseline-1a2b3c feature-x--otimizado-9f8e7d
+  houndsman compare --list --branch feature/x`;
+
+/** Argumentos posicionais (ignora flags com valor). */
+function positionals(args: readonly string[]): string[] {
+	const result: string[] = [];
+	for (let index = 0; index < args.length; index++) {
+		const arg = args[index];
+		if (arg.startsWith("--")) {
+			if (VALUE_FLAGS.has(arg)) index++;
+			continue;
+		}
+		result.push(arg);
+	}
+	return result;
+}
+
+export class CompareCommand implements Command {
+	readonly name = "compare";
+
+	async run(args: string[], context: CliContext): Promise<number> {
+		const parser = ArgParser.from(args);
+		if (parser.has("--help") || parser.has("-h")) {
+			context.out(COMPARE_HELP);
+			return 0;
+		}
+
+		const engine = await context.engine();
+		const branch = parser.value("--branch");
+
+		if (parser.has("--list")) {
+			const runs = listRunsForCompare(engine.storage, engine.repo, branch);
+			if (runs.length === 0) {
+				context.out("Nenhuma run encontrada.");
+				engine.close();
+				return 0;
+			}
+			context.logger.table([
+				["slug", "variante", "findings", "blocking", "attention", "atualizada"],
+				...runs.map((run) => [
+					run.slug,
+					run.variant ?? "(principal)",
+					String(run.findings),
+					String(run.bySeverity.blocking),
+					String(run.bySeverity.attention),
+					run.updatedAt,
+				]),
+			]);
+			engine.close();
+			return 0;
+		}
+
+		const [slugA, slugB] = positionals(args);
+		if (slugA && !slugB) {
+			context.err(
+				"Passe dois slugs (`houndsman compare <a> <b>`) ou use --b <variante>.",
+			);
+			return 1;
+		}
+		try {
+			const result = runCompare(engine.storage, engine.repo, {
+				slugA,
+				slugB,
+				branch,
+				variantA: parser.value("--a"),
+				variantB: parser.value("--b"),
+			});
+			if (parser.has("--json")) {
+				context.out(result.json.trimEnd());
+			} else {
+				context.out(result.markdown.trimEnd());
+				context.logger.success(
+					`Comparação salva em ${result.artifacts.markdown} (run ${result.b.slug}).`,
+				);
+			}
+			return 0;
+		} catch (error) {
+			context.err(error instanceof Error ? error.message : String(error));
+			return 1;
+		} finally {
+			engine.close();
+		}
+	}
+}

package/src/cli/commands/context-command.ts

@@ -51,6 +51,7 @@ export class ContextCommand implements Command {
 			engine.repo,
 			{
 				branch: workspace?.branch ?? parser.value("--branch"),
+				variant: parser.value("--variant"),
 				worktreePath: workspace?.worktreePath,
 				prNumber: workspace?.prNumber,
 			},

package/src/cli/commands/findings-command.ts

@@ -14,21 +14,31 @@ export class FindingsCommand implements Command {
 	async run(args: string[], context: CliContext): Promise<number> {
 		const engine = await context.engine();
 		const sub = ArgParser.from(args).command();
+		// Raiz/git do engine: o comando nunca lê `process.cwd()` implicitamente.
+		const options = { root: engine.root, git: engine.git };
 		const result =
 			sub === "verify"
-				? await runVerifyCommand(engine.config, engine.storage, engine.repo, args)
+				? await runVerifyCommand(
+						engine.config,
+						engine.storage,
+						engine.repo,
+						args,
+						options,
+					)
 				: sub === "submit"
 					? await runSubmitCommand(
 							engine.config,
 							engine.storage,
 							engine.repo,
 							args,
+							options,
 						)
 					: runFindingsCommand(
 							engine.config,
 							engine.storage,
 							engine.repo,
 							args,
+							options,
 						);
 
 		if (result.exitCode !== 0) context.err(result.output);

package/src/cli/commands/golden-command.ts

@@ -0,0 +1,92 @@
+/**
+ * Comando `golden` — avalia as runs da branch contra defeitos congelados.
+ *
+ * Exemplo:
+ *   houndsman golden .houndsman/golden/asaas-split.json
+ *   houndsman golden .houndsman/golden/asaas-split.json --variant otimizado-4
+ */
+
+import { runGolden } from "../../core/commands/golden";
+import { ArgParser } from "../arg-parser";
+import type { CliContext, Command } from "./command";
+
+/** Flags com valor (não entram nos positionais). */
+const VALUE_FLAGS = new Set(["--branch", "--variant", "--slug", "--config"]);
+
+export const GOLDEN_HELP = `Uso: houndsman golden <arquivo.json> [flags]
+
+Avalia uma run (ou todas as variantes da branch) contra um golden set —
+defeitos já confirmados no código — e reporta recall/precisão.
+
+Flags:
+  --branch <nome>    Branch alvo (default: a atual do git)
+  --variant <rótulo> Avalia só uma variante
+  --slug <slug>      Avalia uma run específica
+  --json             Saída JSON (sem markdown)
+
+O relatório é gravado como \`golden-<slug>.md|json\` na run avaliada.
+
+Formato do arquivo:
+  { "version": 1, "title": "...", "commit": "abc1234",
+    "expected": [{ "id": "seller-api-key", "file": "src/a.ts",
+                   "line": 116, "tolerance": 30, "match": "sellerApiKey",
+                   "severity": "blocking", "note": "..." }] 1}
+
+Exemplos:
+  houndsman golden .houndsman/golden/asaas-split.json
+  houndsman golden .houndsman/golden/asaas-split.json --variant otimizado-5`;
+
+/** Primeiro argumento posicional (ignora flags com valor). */
+function positionalFile(args: readonly string[]): string | undefined {
+	for (let index = 0; index < args.length; index++) {
+		const arg = args[index];
+		if (arg.startsWith("--")) {
+			if (VALUE_FLAGS.has(arg)) index++;
+			continue;
+		}
+		return arg;
+	}
+	return undefined;
+}
+
+export class GoldenCommand implements Command {
+	readonly name = "golden";
+
+	async run(args: string[], context: CliContext): Promise<number> {
+		const parser = ArgParser.from(args);
+		if (parser.has("--help") || parser.has("-h")) {
+			context.logger.info(GOLDEN_HELP);
+			return 0;
+		}
+
+		const file = positionalFile(args);
+		if (!file) {
+			context.logger.info(GOLDEN_HELP);
+			return 1;
+		}
+
+		const engine = await context.engine();
+		try {
+			const result = runGolden(engine.storage, engine.repo, {
+				file,
+				branch: parser.value("--branch"),
+				variant: parser.value("--variant"),
+				slug: parser.value("--slug"),
+			});
+			if (parser.has("--json")) {
+				context.logger.info(result.json.trimEnd());
+			} else {
+				context.logger.info(result.markdown.trimEnd());
+				context.logger.success(
+					`Golden salvo em ${result.artifacts?.markdown} (run ${result.target.slug}).`,
+				);
+			}
+			return 0;
+		} catch (error) {
+			context.logger.error(error instanceof Error ? error.message : String(error));
+			return 1;
+		} finally {
+			engine.close();
+		}
+	}
+}

package/src/cli/commands/hunt-command.ts

@@ -26,7 +26,7 @@ import {
 	resolveMakiModel,
 } from "../../core/hunt/maki-model";
 import { SpawnMakiRunner } from "../../core/hunt/maki-runner";
-import { formatDuration, ProgressBoard } from "../../core/logging";
+import { formatDuration, type LoggerLike, ProgressBoard } from "../../core/logging";
 import { displayPath } from "../../core/paths";
 import { ProjectConfig } from "../../core/project-config";
 import { touchRunStatus } from "../../core/run-status";
@@ -49,6 +49,7 @@ Subcomandos:
 Flags:
   --pr <n>            Revisa a PR em worktree dedicado
   --branch <b>        Branch alvo
+  --variant <label>   Rótulo da variante A/B (runs separadas para a mesma branch)
   --worktree <path>   Worktree já existente
   --allow-partial     Finaliza mesmo se algum watchdog falhar (findings vazios)
   --no-context        Não coleta o contexto da PR via gh
@@ -56,6 +57,8 @@ Flags:
   --hunt-concurrency  Processos maki simultâneos
   --hunt-timeout      Timeout por watchdog (ms)
   --no-retry          Não repete saída inválida
+  --no-checklist      Sem a passada extra de fluxos/invariantes não verificados
+  --no-second-opinion Sem a passada adversarial do revisor de fluxo
   --fail-on-blocking  Exit 1 se houver bloqueantes
 
 Instalação:
@@ -180,6 +183,7 @@ export class HuntCommand implements Command {
 						engine.repo,
 						{
 							branch: workspace.branch,
+							variant: options.variant,
 							worktreePath: workspace.worktreePath,
 							prNumber: workspace.prNumber,
 						},
@@ -235,8 +239,12 @@ export class HuntCommand implements Command {
 				concurrency,
 				timeoutMs,
 				retries,
+				checklist: parser.has("--no-checklist") ? false : project.huntChecklist,
+				secondOpinion: parser.has("--no-second-opinion")
+					? false
+					: project.huntSecondOpinion,
 				runner: new SpawnMakiRunner(binary.path),
-				onEvent: (event) => this.logEvent(board, event),
+				onEvent: (event) => this.logEvent(board, event, context.logger),
 			});
 			// Runs longas não podem parecer “timeout” na UI: a skill pinga antes de
 			// cada onda; o CLI renova o heartbeat enquanto o maki trabalha.
@@ -265,6 +273,56 @@ export class HuntCommand implements Command {
 					`${report.totals.findings} finding(s), $${report.totals.costUsd.toFixed(4)}, ` +
 					`${Math.round(report.durationMs / 1000)}s.`,
 			);
+			const checklistCost = report.watchdogs.reduce(
+				(sum, watchdog) => sum + (watchdog.checklist?.costUsd ?? 0),
+				0,
+			);
+			const opinionCost = report.watchdogs.reduce(
+				(sum, watchdog) => sum + (watchdog.secondOpinion?.costUsd ?? 0),
+				0,
+			);
+			if (checklistCost + opinionCost > 0) {
+				context.logger.info(
+					`Passadas extras: checklist $${checklistCost.toFixed(4)} · ` +
+						`segunda opinião $${opinionCost.toFixed(4)}.`,
+				);
+			}
+			const unchecked = report.watchdogs.filter(
+				(watchdog) =>
+					(watchdog.checks?.missing ?? 0) + (watchdog.rules?.missing ?? 0) > 0,
+			);
+			if (unchecked.length > 0) {
+				context.logger.warn(
+					`Checklist de intenção/regras incompleto em ${unchecked.length} watchdog(s): ` +
+						unchecked
+							.map(
+								(watchdog) =>
+									`${watchdog.watchdogId} (itens ${watchdog.checks?.missing ?? 0}, regras ${watchdog.rules?.missing ?? 0})`,
+							)
+							.join(", "),
+				);
+			}
+			const businessReview = report.watchdogs.find(
+				(watchdog) => watchdog.business !== undefined,
+			)?.business;
+			if (businessReview && !businessReview.accepted) {
+				context.logger.info(
+					"Modelo de intenção devolvido pelo revisor foi descartado " +
+						`(inferior ao já gravado: ${report.business ?? "n/d"}).`,
+				);
+			}
+			const incomplete = report.watchdogs
+				.filter((watchdog) => (watchdog.coverage?.undeclared ?? 0) > 0)
+				.map(
+					(watchdog) =>
+						`${watchdog.watchdogId} ${watchdog.coverage?.reviewed ?? 0}/${watchdog.coverage?.total ?? 0}`,
+				);
+			if (incomplete.length > 0) {
+				context.logger.info(
+					`Cobertura declarada incompleta: ${incomplete.join(", ")} ` +
+						"(detalhe em `hunt-report.json`).",
+				);
+			}
 
 			const failed = report.watchdogs.filter(
 				(watchdog) => watchdog.status === "failed",
@@ -403,17 +461,60 @@ export class HuntCommand implements Command {
 			`harness: ${project.huntEnabled ? "ligado" : "desligado"} · ` +
 				`concorrência ${project.huntConcurrency} · ` +
 				`timeout ${Math.round(project.huntTimeoutMs / 1000)}s · ` +
-				`retries ${project.huntRetries}.`,
+				`retries ${project.huntRetries} · ` +
+				`checklist ${project.huntChecklist ? "on" : "off"} · ` +
+				`segunda opinião ${project.huntSecondOpinion ? "on" : "off"}.`,
 		);
 		return 0;
 	}
 
 	/** Log de progresso por watchdog. */
-	private logEvent(board: ProgressBoard, event: HuntEvent): void {
+	private logEvent(board: ProgressBoard, event: HuntEvent, logger: LoggerLike): void {
 		switch (event.type) {
+			case "intent":
+				if (event.status === "start") {
+					logger.step("Reconstruindo a intenção da PR (maki)…");
+				} else if (event.status === "done") {
+					logger.success(
+						`Intenção da PR reconstruída (${event.source ?? "reviewer"}).`,
+					);
+				} else if (event.status === "skipped") {
+					logger.info(`Intenção da PR já disponível (${event.source}).`);
+				} else {
+					logger.warn(
+						`Intenção da PR manteve o modelo determinístico: ${event.error ?? "falha"}`,
+					);
+				}
+				return;
 			case "start":
 				board.add(event.watchdogId, "revisando");
 				return;
+			case "checklist":
+				if (event.status === "start") {
+					logger.step(
+						`${event.watchdogId}: ${event.missing} item(s) e ${event.missingRules} regra(s) sem verificação — passada de checklist…`,
+					);
+				} else if (event.status === "failed") {
+					logger.warn(
+						`${event.watchdogId}: checklist falhou (${event.error ?? "erro"}); relatório da primeira passada mantido.`,
+					);
+				}
+				return;
+			case "second-opinion":
+				if (event.status === "start") {
+					logger.step(
+						`${event.watchdogId}: passada adversarial (credencial/estado, capacidade, identificador, idempotência, contrato)…`,
+					);
+				} else if (event.status === "done") {
+					logger.info(
+						`${event.watchdogId}: segunda opinião adicionou ${event.findings ?? 0} finding(s).`,
+					);
+				} else {
+					logger.warn(
+						`${event.watchdogId}: segunda opinião falhou (${event.error ?? "erro"}); relatório anterior mantido.`,
+					);
+				}
+				return;
 			case "retry":
 				board.retry(
 					event.watchdogId,

package/src/cli/commands/review-command.ts

@@ -1,5 +1,7 @@
 /** Comando default — prepara ou finaliza a revisão. */
 
+import { ArgParser } from "../../core/arg-parser";
+import { runContextCommand } from "../../core/commands/context";
 import { parseReviewArgs } from "../../core/commands/review";
 import { resolveReviewWorkspace } from "../../core/engine/review-workspace";
 import { displayPath } from "../../core/paths";
@@ -52,6 +54,42 @@ export class ReviewCommand implements Command {
 			pr: workspace.prNumber,
 			worktreePath: workspace.worktreePath,
 		};
+		// PR: coleta o contexto via `gh` aqui, como o `hunt` faz. Sem isso, a skill
+		// gastava um subagente só para rodar `houndsman context` antes do prepare.
+		if (
+			options.pr !== undefined &&
+			!options.finalize &&
+			!ArgParser.from(args).has("--no-context")
+		) {
+			const contextStarted = Date.now();
+			context.logger.step("Coletando o contexto da PR via gh…");
+			try {
+				const collected = runContextCommand(
+					engine.config,
+					engine.storage,
+					engine.repo,
+					{
+						branch: workspace.branch,
+						variant: options.variant,
+						worktreePath: workspace.worktreePath,
+						prNumber: workspace.prNumber,
+					},
+				);
+				stepDone(
+					context.logger,
+					collected.context.available
+						? "Contexto da PR coletado via gh"
+						: `Contexto da PR indisponível (${collected.context.reason})`,
+					contextStarted,
+				);
+			} catch (error) {
+				context.logger.warn(
+					`Contexto da PR indisponível: ${
+						error instanceof Error ? error.message : String(error)
+					}`,
+				);
+			}
+		}
 		if (options.finalize) context.logger.step("Consolidando os findings…");
 		const result = await engine
 			.session(resolved)

package/src/cli/commands/status-command.ts

@@ -11,6 +11,7 @@ export class StatusCommand implements Command {
 		const parser = ArgParser.from(args);
 		const action = parser.command();
 		const branch = parser.value("--branch");
+		const variant = parser.value("--variant");
 
 		if (action && action !== "ping" && action !== "show") {
 			context.err(
@@ -22,8 +23,8 @@ export class StatusCommand implements Command {
 		const engine = await context.engine();
 		const result =
 			action === "ping"
-				? pingStatus(engine.storage, engine.repo, branch)
-				: readStatus(engine.storage, engine.repo, branch);
+				? pingStatus(engine.storage, engine.repo, branch, variant)
+				: readStatus(engine.storage, engine.repo, branch, variant);
 
 		if (action === "ping") {
 			context.out(

package/src/cli/help.ts

@@ -3,8 +3,10 @@ export const HELP = `Uso: houndsman [comando] [flags]
 
 Comandos:
   (nenhum)            Prepara a revisão (classification + briefs + manifesto)
-  --finalize          Consolida os findings em review.md
+  --finalize          Consolida os findings e grava o resumo final
   context             Coleta o contexto da PR via gh (Passo 0; --pr/--worktree)
+  compare [a] [b]     Compara duas runs (A/B) por slug ou --branch/--a/--b
+  golden <arquivo>    Avalia as runs contra um golden set (recall/precisão)
   findings <sub>      Triagem/correção dos findings (list · show · set · done · reset · sync · summary · batch · verify · submit · path)
   hunt [flags]        Harness local (maki): prepare → watchdogs via maki → finalize
                       (a skill /houndsman hunt continua existindo p/ agentes externos)
@@ -25,6 +27,7 @@ Flags:
   --base <branch>     Base do diff (default: main)
   --head <ref>        Head do diff (default: HEAD)
   --branch <nome>     Branch alvo (default: detecta do git)
+  --variant <label>   Rótulo da variante A/B (runs separadas para a mesma branch)
   --pr <n>            Revisa a PR em um worktree dedicado (cria/reusa automaticamente)
   --worktree <path>   Revisa em um worktree já existente
   --clean             Descarta findings brutos do staging anterior
@@ -41,6 +44,8 @@ Flags de hunt (harness local):
   --hunt-concurrency  Processos maki simultâneos
   --hunt-timeout      Timeout por watchdog (ms)
   --no-retry          Não repete saída inválida
+  --no-checklist      Sem a passada extra de fluxos/invariantes não verificados
+  --no-second-opinion Sem a passada adversarial do revisor de fluxo
 
 Flags de findings:
   --decision <d>      pending | execute | ignore

package/src/cli/index.ts

@@ -12,7 +12,7 @@
  *
  * Comandos:
  *   (default)            Passo 1 — preparar (classificação + briefs + manifesto)
- *   --finalize           Passo 3 — consolidar os findings em review.md
+ *   --finalize           Passo 3 — consolidar os findings no resumo final
  *   context              Passo 0 — coletar o contexto da PR via `gh`
  *   findings <sub>       Triagem/correção dos findings (list/set/done/sync/batch/verify/submit/...)
  *   hunt [flags]         Harness local (maki): prepare → watchdogs via maki → finalize
@@ -35,9 +35,11 @@ import { formatDuration, logger } from "../core/logging";
 import { syncProjectLayerForRoot } from "../core/services/worktree-manager";
 import { ArgParser } from "./arg-parser";
 import type { CliContext } from "./commands/command";
+import { CompareCommand } from "./commands/compare-command";
 import { ContextCommand } from "./commands/context-command";
 import { DoctorCommand } from "./commands/doctor-command";
 import { FindingsCommand } from "./commands/findings-command";
+import { GoldenCommand } from "./commands/golden-command";
 import { HelpCommand } from "./commands/help-command";
 import { HuntCommand } from "./commands/hunt-command";
 import { CommandRegistry } from "./commands/registry";
@@ -61,6 +63,8 @@ function buildRegistry(): CommandRegistry {
 		.register(new HelpCommand())
 		.register(new HuntCommand())
 		.register(new ContextCommand())
+		.register(new CompareCommand())
+		.register(new GoldenCommand())
 		.register(new FindingsCommand())
 		.register(new StatusCommand())
 		.register(new WatchdogCommand())

package/src/cli/progress.ts

@@ -6,7 +6,7 @@
  * primeiro `Discovery:`.
  */
 
-import { formatDuration, type LoggerLike, PhaseReporter } from "../core/logging";
+import { formatDuration, type LoggerLike, ParallelPhaseReporter } from "../core/logging";
 import type { PrepareProgress, PrepareStage } from "../core/orchestrator";
 
 /** Texto de cada etapa (início no gerúndio, fim no particípio). */
@@ -20,6 +20,10 @@ export const PREPARE_STAGE_TEXT: Record<PrepareStage, { start: string; done: str
 	impact: { start: "Medindo o impacto nos importadores", done: "Impacto calculado" },
 	jev: { start: "Pré-analisando o diff (Jev/IA)", done: "Pré-análise concluída" },
 	context: { start: "Resumindo o contexto da PR", done: "Contexto resumido" },
+	business: {
+		start: "Reconstruindo a intenção da PR",
+		done: "Intenção reconstruída",
+	},
 	technical: {
 		start: "Consolidando os pontos técnicos",
 		done: "Pontos técnicos prontos",
@@ -31,7 +35,8 @@ export const PREPARE_STAGE_TEXT: Record<PrepareStage, { start: string; done: str
 
 /** Cria o callback de progresso do prepare ligado ao logger do CLI. */
 export function prepareProgress(logger: LoggerLike): PrepareProgress {
-	const reporter = new PhaseReporter(logger);
+	// O prepare roda etapas em paralelo; o reporter aceita fases concorrentes.
+	const reporter = new ParallelPhaseReporter(logger);
 	return (event) => {
 		const text = PREPARE_STAGE_TEXT[event.stage];
 		if (event.type === "start") reporter.begin(event.stage, text.start);

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

@@ -10,6 +10,7 @@ import type { AiProviderOptions } from "../config";
 import type { ProjectConfig } from "../project-config";
 import { AiConfigurationError, errorMessage } from "./errors";
 import { ModelFactory } from "./model-factory";
+import { LEAN_PROVIDER_OPTIONS } from "./provider-capabilities";
 import type { AiResult, AiUsage, ModelProvider, ModelRequest } from "./types";
 import { AiUsageBudget } from "./usage-budget";
 import { AiUsageRecorder } from "./usage-recorder";
@@ -109,7 +110,13 @@ export class AiClient {
 	): Promise<AiResult<T>> {
 		return this.run(
 			feature,
-			{ ...request, outputSchema: request.outputSchema },
+			{
+				...request,
+				outputSchema: request.outputSchema,
+				providerOptions:
+					request.providerOptions ??
+					leanProviderOptions(this.project.aiProviderOptions),
+			},
 			model,
 		);
 	}
@@ -183,6 +190,7 @@ export class AiClient {
 			return { ok: false, error: errorMessage(error) };
 		}
 
+		const startedAt = Date.now();
 		try {
 			const provider = await this.requireProvider(model);
 			const response = await provider.generate({
@@ -193,6 +201,17 @@ export class AiClient {
 				),
 				signal: combineSignals(request.signal, this.project.aiTimeoutMs),
 			});
+			// Objeto truncado não é resultado parcial útil: sem o JSON completo a
+			// feature inteira caía silenciosamente no fallback. Registra e falha.
+			if (request.outputSchema && response.finishReason === "length") {
+				const error = `Resposta truncada (finishReason=length; maxOutputTokens=${request.maxOutputTokens ?? "sem teto"}).`;
+				this.recorder.recordFailure(feature, provider.modelId, {
+					durationMs: Date.now() - startedAt,
+					error,
+					finishReason: response.finishReason,
+				});
+				return { ok: false, error };
+			}
 			this.budget.record(response.usage);
 			this.recorder.record(feature, provider.modelId, response.usage);
 			return {
@@ -202,7 +221,12 @@ export class AiClient {
 				model: provider.modelId,
 			};
 		} catch (error) {
-			return { ok: false, error: errorMessage(error) };
+			const message = errorMessage(error);
+			this.recorder.recordFailure(feature, model ?? this.modelId, {
+				durationMs: Date.now() - startedAt,
+				error: message,
+			});
+			return { ok: false, error: message };
 		}
 	}
 }
@@ -221,6 +245,18 @@ function mergeProviderOptions(
 	return merged;
 }
 
+/**
+ * Opções enxutas para objetos estruturados: thinking desligado, salvo quando o
+ * projeto já configurou `thinking` explicitamente — aí a config manda.
+ */
+function leanProviderOptions(
+	base: AiProviderOptions | undefined,
+): AiProviderOptions | undefined {
+	const configured = base?.deepseek;
+	if (configured && "thinking" in configured) return undefined;
+	return LEAN_PROVIDER_OPTIONS;
+}
+
 /** Combina o sinal do chamador com o timeout configurado. */
 function combineSignals(
 	signal: AbortSignal | undefined,