@payconductor/houndsman 0.3.0 → 0.4.0

package/README.md

@@ -74,8 +74,9 @@ No seu harness (Claude Code / agents), invoque o skill:
 /houndsman hunt
 ```
 
-O skill orquestra tudo e grava o relatório em `.houndsman/.runs/<branch-slug>/review.md`.
-Não precisa rodar nenhum script à mão.
+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.
 
 ---
 
@@ -86,9 +87,9 @@ Não precisa rodar nenhum script à mão.
    ├─ 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 + state.json
+   ├─ Passo 3  consolida em review.md + triagem no storage
    ├─ Passo 4  valida na UI (server) e marca os achados a executar
-   ├─ Passo 5  fix corrige o grupo atual → run.json (fix_done)
+   ├─ Passo 5  fix corrige o grupo atual → status fix_done
    └─ Passo 6  verify confere o que resolveu, sem re-revisar
 ```
 
@@ -111,7 +112,7 @@ O skill tem **4 capabilities**, todas em `/houndsman`:
 ## Triando os findings (opcional)
 
 Depois do `--finalize`, cada finding tem um `id` curto e um `fingerprint` de **conteúdo**
-no `.houndsman/.runs/<branch-slug>/state.json`. Você decide o que fazer com cada um — pela
+no storage global. Você decide o que fazer com cada um — pela
 **UI local** ou pelo **agente** (auto-fix) — sem abrir o JSON à mão:
 
 ```bash
@@ -136,12 +137,23 @@ bun run houndsman findings verify           # confere o que resolveu (barato, se
 > o review completo.
 
 > A identidade do finding é o **conteúdo** (fingerprint), não a linha: itens deslocados
-> pelo fix não se perdem. O estado é local e mora em `.runs/<slug>/state.json` (gitignored).
+> pelo fix não se perdem. O estado mora no storage global (`<HOUNDSMAN_HOME>/houndsman.db`).
 
 ---
 
 ## Mantendo a configuração
 
+- **Persistência** → por default, SQLite global em `<HOUNDSMAN_HOME>/houndsman.db`
+  (`HOUNDSMAN_HOME` sobrescreve o diretório de dados). Para voltar ao backend de arquivos,
+  troque só o provider — a interface `StorageProvider` é a mesma:
+
+  ```ts
+  export const houndsmanConfig = {
+    // ...
+    storage: { provider: "file", path: "./houndsman-runs" },
+  };
+  ```
+
 - **Alterar regras** → use a capability **`train`** (`/houndsman train`). Ela prova no código
   que o padrão existe (evidência) antes de editar e roda as validações.
 - **Atualizou a lib?** Sincronize os arquivos auto-gerados sem tocar nas suas regras:

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@payconductor/houndsman",
-	"version": "0.3.0",
+	"version": "0.4.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/context-command.ts

@@ -1,7 +1,7 @@
 /** Comando `context` — coleta o contexto da PR via `gh` (Passo 0). */
 
 import { runContextCommand } from "../../core/commands/context";
-import { relFromRoot } from "../../core/paths";
+import { displayPath } from "../../core/paths";
 import { ArgParser } from "../arg-parser";
 import type { CliContext, Command } from "./command";
 
@@ -11,10 +11,12 @@ export class ContextCommand implements Command {
 	async run(args: string[], context: CliContext): Promise<number> {
 		const engine = await context.engine();
 		const parser = ArgParser.from(args);
-		const { paths, context: pr } = runContextCommand(engine.config, {
-			branch: parser.value("--branch"),
-			dir: parser.value("--dir"),
-		});
+		const { paths, context: pr } = runContextCommand(
+			engine.config,
+			engine.storage,
+			engine.repo,
+			{ branch: parser.value("--branch") },
+		);
 
 		if (pr.available) {
 			const src = pr.source;
@@ -24,14 +26,14 @@ export class ContextCommand implements Command {
 			context.out(
 				`[houndsman] PR ${label} (${src?.head} → ${src?.base}), ${pr.stats?.files ?? 0} arquivo(s).`,
 			);
-			context.out(`[houndsman] contexto: ${relFromRoot(paths.context)}`);
-			context.out(`[houndsman] brief: ${relFromRoot(paths.brief)}`);
+			context.out(`[houndsman] contexto: ${displayPath(paths.context)}`);
+			context.out(`[houndsman] brief: ${displayPath(paths.brief)}`);
 			context.out(
-				`[houndsman] próximo passo: subagente resume em ${relFromRoot(paths.summary)}`,
+				`[houndsman] próximo passo: subagente resume em ${displayPath(paths.summary)}`,
 			);
 		} else {
 			context.out(`[houndsman] contexto indisponível (${pr.reason}): ${pr.detail}`);
-			context.out(`[houndsman] marcador: ${relFromRoot(paths.context)}`);
+			context.out(`[houndsman] marcador: ${displayPath(paths.context)}`);
 		}
 		return 0;
 	}

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

@@ -1,6 +1,7 @@
 /** Comando `doctor` (alias `check`) — valida config, ambiente e credencial Jev. */
 
 import { checkRegistry } from "../../core/registry-check";
+import { storageLocation } from "../../core/storage/paths";
 import type { CliContext, Command } from "./command";
 
 export class DoctorCommand implements Command {
@@ -28,6 +29,10 @@ export class DoctorCommand implements Command {
 		context.out("\n→ Ambiente:");
 		context.out(`  ${Bun.which("git") ? "✅" : "❌"} git`);
 		context.out(`  ${Bun.which("gh") ? "✅" : "⚠️ "} gh (opcional — contexto da PR)`);
+		context.out("\n→ Persistência:");
+		context.out(`  provider: ${engine.storage.kind}`);
+		context.out(`  ${storageLocation(engine.config)}`);
+		context.out(`  repo: ${engine.repo.key}`);
 		await this.reportJevCredential(context);
 		return 0;
 	}

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

@@ -16,10 +16,20 @@ export class FindingsCommand implements Command {
 		const sub = ArgParser.from(args).command();
 		const result =
 			sub === "verify"
-				? await runVerifyCommand(engine.config, args)
+				? await runVerifyCommand(engine.config, engine.storage, engine.repo, args)
 				: sub === "submit"
-					? await runSubmitCommand(engine.config, args)
-					: runFindingsCommand(engine.config, args);
+					? await runSubmitCommand(
+							engine.config,
+							engine.storage,
+							engine.repo,
+							args,
+						)
+					: runFindingsCommand(
+							engine.config,
+							engine.storage,
+							engine.repo,
+							args,
+						);
 
 		if (result.exitCode !== 0) context.err(result.output);
 		else context.out(result.output);

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

@@ -1,7 +1,6 @@
 /** Comando default — prepara ou finaliza a revisão. */
 
 import { parseReviewArgs } from "../../core/commands/review";
-import { resolveArtifactDir } from "../../core/config";
 import type { CliContext, Command } from "./command";
 
 export class ReviewCommand implements Command {
@@ -9,7 +8,7 @@ export class ReviewCommand implements Command {
 
 	async run(args: string[], context: CliContext): Promise<number> {
 		const engine = await context.engine();
-		const options = parseReviewArgs(args, resolveArtifactDir(engine.config));
+		const options = parseReviewArgs(args);
 		const result = await engine.session(options).run();
 
 		for (const message of result.messages) context.out(message);

package/src/cli/help.ts

@@ -18,8 +18,7 @@ Flags:
   --base <branch>     Base do diff (default: main)
   --head <ref>        Head do diff (default: HEAD)
   --branch <nome>     Branch alvo (default: detecta do git)
-  --dir <dir>         Diretório dos artefatos
-  --clean             Descarta findings anteriores
+  --clean             Descarta findings brutos do staging anterior
   --full              Força review completo (ignora o modo incremental)
   --no-jev            Desativa a pré-análise Jev
   --fail-on-blocking  Exit 1 se houver bloqueantes (com --finalize)
@@ -40,4 +39,9 @@ Flags de findings:
   --apply             (verify) Marca os resolvidos como done
   --fail-on-persisting (verify) Exit 1 se algum blocking persistir
   --include-sent      (submit) Reenvia findings já enviados à PR
-  --dry-run           (submit) Só a prévia do envio, sem postar`;
+  --dry-run           (submit) Só a prévia do envio, sem postar
+
+Persistência:
+  Runs, findings e artefatos ficam no storage global (SQLite em
+  <HOUNDSMAN_HOME>/houndsman.db). Use storage.provider: "file" na config para
+  voltar ao backend de arquivos. Nada é gravado em .houndsman/.runs.`;

package/src/cli/index.ts

@@ -22,8 +22,8 @@
  *   test                 Roda a suíte de testes da lib
  *   watchdog <id>        Contexto de um watchdog (`--rules`, `--json`)
  *
- * Flags: `--base <b>` · `--head <ref>` · `--branch <b>` · `--dir <d>` ·
- *   `--config <path>` · `--clean` · `--full` · `--no-jev` · `--fail-on-blocking`.
+ * Flags: `--base <b>` · `--head <ref>` · `--branch <b>` · `--config <path>` ·
+ *   `--clean` · `--full` · `--no-jev` · `--fail-on-blocking`.
  */
 
 import { loadConfig } from "../core/config-loader";

package/src/core/commands/context.ts

@@ -1,19 +1,20 @@
 /**
  * Subcomando `context` — coleta o contexto da PR via `gh` (Passo 0).
  *
- * Biblioteca: grava os artefatos e devolve os dados; o CLI faz o log/exit.
+ * Biblioteca: grava no staging da review + artefato no storage; o CLI faz o
+ * log/exit.
  */
 
-import { mkdirSync, writeFileSync } from "node:fs";
-import { type HoundsmanConfig, resolveArtifactDir } from "../config";
+import type { HoundsmanConfig } from "../config";
 import {
-	type ContextPaths,
 	collectPrContext,
-	contextPaths,
 	currentBranch,
 	type PrContextRaw,
 	renderContextBrief,
 } from "../pr-context";
+import { sanitizeBranch } from "../report-builder";
+import type { RepoIdentity, StorageProvider } from "../storage/types";
+import { type ContextPaths, ReviewWorkArea } from "../storage/work-area";
 
 export type ContextRunResult = {
 	paths: ContextPaths;
@@ -22,18 +23,33 @@ export type ContextRunResult = {
 
 /** Coleta a PR atual e grava `context.json` + `context-brief.md`. */
 export function runContextCommand(
-	config: HoundsmanConfig,
-	opts: { branch?: string; dir?: string } = {},
+	_config: HoundsmanConfig,
+	storage: StorageProvider,
+	repo: RepoIdentity,
+	opts: { branch?: string } = {},
 ): ContextRunResult {
 	const branch = opts.branch ?? currentBranch();
-	const dir = opts.dir ?? resolveArtifactDir(config);
-	const paths = contextPaths(dir, branch);
-
-	mkdirSync(paths.dir, { recursive: true });
+	const review = storage.getOrCreateReview({
+		repo,
+		branch,
+		slug: sanitizeBranch(branch),
+	});
+	const work = new ReviewWorkArea(review);
+	const paths = work.contextPaths;
 
 	const context = collectPrContext(branch);
-	writeFileSync(paths.context, `${JSON.stringify(context, null, 2)}\n`);
-	writeFileSync(paths.brief, `${renderContextBrief(context, branch, paths)}\n`);
+	const brief = renderContextBrief(context, branch, paths);
+	work.writeContext(context, brief);
+	storage.writeArtifact(review.id, {
+		name: "context.json",
+		kind: "context",
+		content: `${JSON.stringify(context, null, 2)}\n`,
+	});
+	storage.writeArtifact(review.id, {
+		name: "context-brief.md",
+		kind: "context-brief",
+		content: `${brief}\n`,
+	});
 
 	return { paths, context };
 }