@payconductor/houndsman 0.3.0 → 0.5.0

package/README.md

@@ -26,8 +26,8 @@ diferente das PRs. O motor só coordena a caçada — as regras são problema se
 
 - **Bun** — runtime obrigatório.
 - **git** — o diff usa `git diff <base>...<head>`.
-- Opcionais: **`gh`** (contexto da PR) e **`TYPESAFE_API_KEY`** (pré-análise Jev). A revisão
-  funciona normalmente sem eles; o `houndsman doctor` valida a credencial Jev quando presente.
+- **gh** (Opcional) — Obtém contexto da PR e dispara comentários para o GitHub
+- **`TYPESAFE_API_KEY`** (Opcional) — Env a ser informada na raiz, usada em pré-analise com JEV
 
 ### 2. Instale o CLI (global)
 
@@ -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,62 +87,49 @@ 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
 ```
 
 O skill tem **4 capabilities**, todas em `/houndsman`:
 
-- **`hunt`** — revisa a PR (default: `/houndsman` = `/houndsman hunt`).
+- **`hunt`** — revisa a PR.
 - **`train`** — mantém/atualiza as regras dos watchdogs.
-- **`fix`** — corrige os findings marcados (`/houndsman fix`).
-- **`verify`** — confere se as violações foram resolvidas (`/houndsman verify`), sem re-revisar.
+- **`fix`** — corrige os findings marcados.
+- **`verify`** — confere se as violações foram resolvidas, sem re-revisar.
 
-- Revisão normal: `/houndsman` ou `/houndsman hunt` (a branch é detectada; base default `main`).
 - Revisar outra branch: `/houndsman hunt feature/minha-branch`.
-- Validar e triar na UI: `houndsman server --open` — marque os achados a executar (`execute`).
-- Manual (sem skill): `houndsman context` → `houndsman --base main` → *(subagentes)* →
-  `houndsman --finalize`.
-- CI: `houndsman --finalize --fail-on-blocking` (exit 1 se houver bloqueantes).
+- Validar na UI: `houndsman server --open` — marque os findings a executar (`execute`).
 
 ---
 
-## Triando os findings (opcional)
+## Validando 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
-**UI local** ou pelo **agente** (auto-fix) — sem abrir o JSON à mão:
+Você decide o que fazer com cada finding pela **UI local**, informando se quer `Executar` ou `Ignorar`
 
 ```bash
 bun run houndsman server --open     # UI: triar, comentar, marcar feito, ler artefatos
 ```
 
-- **decision:** `pending` · `execute` · `ignore` (+ comentário).
-- **execState:** `pending` · `in_progress` · `done` · `stale`.
-
-**Auto-fix pelo agente** — as linhas mudam depois do fix, e o motor reancora por conteúdo:
-
-```bash
-bun run houndsman findings batch --json     # grupo atual (agrupamento automático) + outros
-# ... o agente corrige apenas esse grupo ...
-bun run houndsman findings sync             # reancora por conteúdo
-bun run houndsman findings done <id>
-bun run houndsman findings verify           # confere o que resolveu (barato, sem re-revisar)
-```
-
-> A partir da 2ª revisão o `hunt` é **incremental**: revisa só os arquivos que mudaram desde
-> o último `--finalize` e **carrega** os findings dos arquivos inalterados. `--full` força
-> 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).
+> A partir da 2ª revisão o `hunt` é **incremental**: revisa apenas os arquivos que mudaram desde
+> a última revisão. `--full` força o review completo.
 
 ---
 
 ## Mantendo a configuração
 
+- **Persistência** → por default, SQLite global em `<HOUNDSMAN_HOME>/houndsman.db`
+  (`HOUNDSMAN_HOME` sobrescreve o diretório de dados). Caso queira storage base em arquivos, na config, troque provider para `file`:
+
+  ```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:
@@ -153,8 +141,6 @@ bun run houndsman findings verify           # confere o que resolveu (barato, se
 
   O `update` reescreve **só** `.houndsman/core/**` e `.houndsman/.gitignore`. Seus arquivos
   (`watchdogs/`, `exclusions.ts`, `doc-mappings.ts`, `houndsman.config.ts`) nunca são tocados.
-- **Recomeçar a camada do zero** → `houndsman setup --force` (sobrescreve só os arquivos do
-  usuário; sem `--force` o `setup` é idempotente).
 
 ---
 

package/package.json

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

@@ -0,0 +1,46 @@
+/** Comando `status` — mostra o status da run ou renova o heartbeat (`status ping`). */
+
+import { pingStatus, readStatus } from "../../core/commands/status";
+import { ArgParser } from "../arg-parser";
+import type { CliContext, Command } from "./command";
+
+export class StatusCommand implements Command {
+	readonly name = "status";
+
+	async run(args: string[], context: CliContext): Promise<number> {
+		const parser = ArgParser.from(args);
+		const action = parser.command();
+		const branch = parser.value("--branch");
+
+		if (action && action !== "ping" && action !== "show") {
+			context.err(
+				`Ação desconhecida em 'status': '${action}'. Use 'status' ou 'status ping'.`,
+			);
+			return 1;
+		}
+
+		const engine = await context.engine();
+		const result =
+			action === "ping"
+				? pingStatus(engine.storage, engine.repo, branch)
+				: readStatus(engine.storage, engine.repo, branch);
+
+		if (action === "ping") {
+			context.out(
+				result.heartbeatAt
+					? `Heartbeat atualizado — ${result.branch} · ${result.status ?? "sem status"} · ${result.heartbeatAt}`
+					: `Sem execução ativa — ${result.branch} · ${result.status ?? "sem status"}.`,
+			);
+		} else {
+			context.out(
+				[
+					`Branch: ${result.branch}`,
+					`Status: ${result.status ?? "—"}`,
+					`Heartbeat: ${result.heartbeatAt ?? "—"}`,
+					`Atualizado: ${result.updatedAt}`,
+				].join("\n"),
+			);
+		}
+		return 0;
+	}
+}

package/src/cli/help.ts

@@ -6,6 +6,7 @@ Comandos:
   --finalize          Consolida os findings em review.md
   context             Coleta o contexto da PR via gh (Passo 0)
   findings <sub>      Triagem/correção dos findings (list · show · set · done · reset · sync · summary · batch · verify · submit · path)
+  status [ping]       Mostra o status da run (ping renova o heartbeat da execução)
   server              Sobe a UI local de triagem (--port, --host, --open)
   setup               Cria a configuração inicial do projeto (config + skills)
   update              Sincroniza os arquivos auto-gerados (.houndsman/core)
@@ -18,8 +19,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 +40,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

@@ -15,6 +15,7 @@
  *   --finalize           Passo 3 — consolidar os findings em review.md
  *   context              Passo 0 — coletar o contexto da PR via `gh`
  *   findings <sub>       Triagem/correção dos findings (list/set/done/sync/batch/verify/submit/...)
+ *   status [ping]        Mostra o status da run; `ping` renova o heartbeat da execução
  *   server               Sobe a UI local de triagem (Bun.serve)
  *   setup                Cria a configuração inicial do projeto (config + skills)
  *   update               Sincroniza os arquivos auto-gerados (.houndsman/core)
@@ -22,8 +23,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";
@@ -38,6 +39,7 @@ import { CommandRegistry } from "./commands/registry";
 import { ReviewCommand } from "./commands/review-command";
 import { ServerCommand } from "./commands/server-command";
 import { SetupCommand, TestCommand, UpdateCommand } from "./commands/setup-command";
+import { StatusCommand } from "./commands/status-command";
 import { WatchdogCommand } from "./commands/watchdog-command";
 import { HELP } from "./help";
 
@@ -53,6 +55,7 @@ function buildRegistry(): CommandRegistry {
 		.register(new HelpCommand())
 		.register(new ContextCommand())
 		.register(new FindingsCommand())
+		.register(new StatusCommand())
 		.register(new WatchdogCommand())
 		.register(new ServerCommand())
 		.register(new SetupCommand())

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