@payconductor/houndsman 0.12.0 → 0.14.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
@@ -28,9 +33,11 @@ diferente das PRs. O motor só coordena a caçada — as regras são problema se
 - **git** — o diff usa `git diff <base>...<head>`.
 - **gh** (Opcional) — Obtém contexto da PR e dispara comentários para o GitHub
 - **`HOUNDSMAN_TYPE_SAFE_API_KEY`** (opcional) — pré-análise Jev.
-- **`HOUNDSMAN_DEEP_SEEK_API_KEY`** (opcional) — features de IA (briefs, contexto, classificação, resumo técnico).
+- **`HOUNDSMAN_DEEP_SEEK_API_KEY`** (opcional) — features de IA (briefs, contexto, classificação, resumo técnico) e harness local `hunt`.
 - **`HOUNDSMAN_OPENAI_API_KEY`** / **`HOUNDSMAN_ANTHROPIC_API_KEY`** (opcional) — apenas se
   `ai.provider` for `openai`/`anthropic`.
+- **maki** (opcional) — só para o harness local `houndsman hunt`; a skill `/houndsman hunt`
+  não precisa dele. Instale com `houndsman hunt install`.
 
 > Coloque as chaves em um `.env` na raiz do projeto; o Bun carrega automaticamente.
 
@@ -84,6 +91,20 @@ O skill orquestra tudo e persiste o relatório no storage global (SQLite em
 `<HOUNDSMAN_HOME>/houndsman.db`); a UI lê os artefatos direto do storage. Não precisa rodar
 nenhum script à mão.
 
+#### Alternativa: rodar 100% pelo CLI (opcional)
+
+Quem não quer usar um agente externo pode executar a mesma revisão pelo terminal, com o
+maki como harness local. A instalação é única e fica fora do projeto:
+
+```bash
+houndsman hunt install        # baixa o maki fixado em <HOUNDSMAN_HOME>/tools/maki
+houndsman hunt doctor         # diagnóstico (não falha se o maki não existir)
+houndsman hunt --pr 456       # prepare → maki (1 processo por brief) → finalize
+```
+
+Os dois caminhos produzem os mesmos artefatos e usam o mesmo staging. A skill
+`/houndsman hunt` continua sendo o caminho canônico para agentes externos.
+
 ### 7. Várias PRs ao mesmo tempo (worktrees)
 
 Cada revisão pode rodar em um **worktree dedicado** (detached no commit da PR), sem
@@ -112,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.12.0",
+	"version": "0.14.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/doctor-command.ts

@@ -1,9 +1,11 @@
 /** Comando `doctor` (alias `check`) — valida config, ambiente e credenciais. */
 
+import { existsSync } from "node:fs";
 import type { AiClient } from "../../core/ai/ai-client";
 import { ArgParser } from "../../core/arg-parser";
 import type { AiProviderKind } from "../../core/config";
 import { ENV_NAMES, env } from "../../core/env";
+import { displayPath } from "../../core/paths";
 import { checkRegistry } from "../../core/registry-check";
 import { storageLocation } from "../../core/storage/paths";
 import type { CliContext, Command } from "./command";
@@ -66,6 +68,26 @@ export class DoctorCommand implements Command {
 		const ast = await engine.ast.check();
 		logger.bullet(`${ast.ok ? "✅" : "⚠️ "} AST: ${ast.detail}`);
 
+		// Harness local é opcional: a ausência do maki nunca falha o doctor.
+		const { makiSourceLabel, probeMakiVersion, resolveMakiBinary } = await import(
+			"../../core/hunt/maki-install"
+		);
+		const maki = resolveMakiBinary(engine.config.hunt?.binaryPath);
+		if (!maki) {
+			logger.bullet(
+				"⚠️  maki (hunt local): não instalado (opcional — `houndsman hunt install`).",
+			);
+		} else {
+			const exists = existsSync(maki.path);
+			const version = exists
+				? (maki.version ?? probeMakiVersion(maki.path))
+				: undefined;
+			logger.bullet(
+				`${exists ? "✅" : "❌"} maki (hunt local): ${displayPath(maki.path)} ` +
+					`(${makiSourceLabel(maki.source)}${version ? `, v${version}` : ""}).`,
+			);
+		}
+
 		const provider = engine.ai.projectConfig.aiProvider;
 		const key = keyFor(provider);
 		logger.bullet(

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