@payconductor/houndsman 0.3.0 → 0.4.0

package/src/skill/hunt.md

@@ -21,7 +21,7 @@ mudanças antes de push.
 | 0. Contexto | `houndsman context` | subagente | `context.json` + `context-brief.md` → `context-summary.json` |
 | 1. Preparar | `houndsman` | skill | `classification.json` + `candidates.json` + `briefs/` + `manifest.json` |
 | 2. Revisar | *(subagentes)* | skill (via `runSubagent`) | `findings/<watchdog>.json` (um por watchdog) |
-| 3. Finalizar | `houndsman --finalize` | skill | `review.md` + `state.json` + `run.json` |
+| 3. Finalizar | `houndsman --finalize` | skill | `review.md` + triagem/status no storage |
 
 > Por que comandos separados? Entre o passo 1 e o 3 acontece trabalho de LLM (os subagentes).
 > Depois do passo 3, a correção dos achados é a capability **`fix`** — ver `fix.md`.
@@ -70,14 +70,19 @@ leia o `context-brief.md` indicado na saída; siga as instruções e grave
 houndsman --base main
 ```
 
-Gera em `.houndsman/.runs/<branch-slug>/`:
+Grava os artefatos no **storage global** (SQLite em `<HOUNDSMAN_HOME>/houndsman.db`) e o
+staging dos subagentes em `<HOUNDSMAN_HOME>/work/<reviewId>/`:
 
 | Artefato | Conteúdo |
 |---|---|
-| `classification.json` | Watchdogs ativados por arquivo + status (A/M/D/R) + churn |
-| `candidates.json` | Indícios da pré-análise Jev (regra + arquivo + confiança) |
-| `briefs/<watchdog>.md` | Instruções prontas para cada subagente (arquivos por risco) |
-| `manifest.json` | Resumo: watchdogs, arquivos, deletados, status, contexto, Jev, orçamento |
+| `classification.json` | Watchdogs ativados por arquivo + status (A/M/D/R) + churn (storage) |
+| `candidates.json` | Indícios da pré-análise Jev (regra + arquivo + confiança) (storage) |
+| `briefs/<watchdog>.md` | Instruções prontas para cada subagente (staging + storage, para auditoria) |
+| `manifest.json` | Resumo: watchdogs, arquivos, deletados, status, contexto, Jev, orçamento (storage) |
+
+> O prepare imprime o caminho absoluto do diretório de briefs e cada brief traz o
+> `outputPath` do JSON que o subagente deve gravar. Briefs e contexto também ficam
+> persistidos no storage para auditoria; o staging é limpo após o `--finalize`.
 
 **Excluídos automaticamente:** lock files, `dist/`, `build/`, `.env*`, imagens, source
 maps (padrões do projeto em `.houndsman/exclusions.ts`).
@@ -111,7 +116,7 @@ as regras atômicas dos watchdogs. Respostas acima do limiar viram **candidatos*
 
 ### Review incremental (da 2ª revisão em diante)
 
-Cada `--finalize` grava o **commit revisado** (`reviewed.headSha` no `state.json`). No prepare
+Cada `--finalize` grava o **commit revisado** (`reviewedSha` da review no storage). No prepare
 seguinte, se o `HEAD` descende desse commit (sem rebase), o motor revisa **só o delta** — os
 arquivos alterados desde a última revisão — e **carrega** os findings dos arquivos inalterados
 (carry-over), sem re-revisá-los. O `manifest.json` traz o bloco `incremental` (`from`,
@@ -131,11 +136,11 @@ Um subagente por brief. Despache em **ondas** (ex.: até 8 subagentes por bloco
 calls) — evita estourar limites de taxa quando há muitos watchdogs. O prompt é o próprio brief:
 
 ```
-Leia e execute o brief: .houndsman/.runs/<branch-slug>/briefs/<watchdog-id>.md
+Leia e execute o brief: <caminho absoluto impresso pelo prepare>/briefs/<watchdog-id>.md
 Você é o watchdog <watchdog-id> do {{projectName}}.
 ```
 
-Cada subagente grava `findings/<watchdog-id>.json` (schema `.houndsman/core/skill/OUTPUT-FORMAT.md`).
+Cada subagente grava o `outputPath` indicado no brief (schema `.houndsman/core/skill/OUTPUT-FORMAT.md`).
 Sem achados → `"findings": []` (arquivo obrigatório). Arquivos na seção **Fora do orçamento**
 não são lidos: registre-os em `skipped`.
 
@@ -150,17 +155,17 @@ não são lidos: registre-os em `skipped`.
 houndsman --finalize
 ```
 
-Falha com mensagem clara se faltar algum `findings/<watchdog>.json`. Quando todos existem:
+Falha com mensagem clara se faltar algum `findings/<watchdog>.json` no staging. Quando todos existem:
 1. Valida o schema de cada JSON
 2. Deduplica achados por `(file, line, rule)` mesclando watchdogs sobrepostos
 3. Agrupa por severidade: ❌ blocking > ⚠️ attention > 💡 suggestion > 🔎 nit
-4. Grava `.houndsman/.runs/<branch-slug>/review.md` + tabela de cobertura
+4. Grava o artefato `review.md` no storage + tabela de cobertura
 5. Anexa os candidatos Jev não confirmados em `🔎 Candidatos não verificados` (não bloqueiam)
 6. Agrupa os achados **por arquivo** dentro de cada severidade (navegabilidade em PRs grandes)
 7. Grava um `review.<watchdog>.md` por watchdog com achados e indexa no `review.md`
    (**Relatórios por domínio**) — mantém o relatório consolidado enxuto
-8. Grava `.houndsman/.runs/<branch-slug>/state.json` — a **triagem**: um `id` curto e um
-   `fingerprint` de conteúdo por finding, preservados entre execuções
+8. Persiste a **triagem** no storage — um `id` curto e um `fingerprint` de conteúdo por
+   finding, preservados entre execuções
 
 Após finalizar, corrija os achados com a capability **`fix`** (`fix.md`): a UI ou os
 comandos `findings` levam do achado à correção.
@@ -212,15 +217,15 @@ houndsman context (gh)         ──►  context.json ──► subagente ─
         ↓
 git diff --name-status (base...head)
         ↓
-[1] houndsman                  ──►  classification.json + candidates.json + briefs/ + manifest.json
+[1] houndsman                  ──►  storage (classification/candidates/manifest) + briefs/ no staging
         ↓
-[2] N subagentes em paralelo   ──►  findings/<watchdog>.json
+[2] N subagentes em paralelo   ──►  findings/<watchdog>.json no staging
         ↓
-[3] houndsman --finalize       ──►  review.md + state.json + run.json (review_done)
+[3] houndsman --finalize       ──►  review.md + triagem no storage (review_done)
         ↓
 [4] server (UI)                ──►  validar a revisão + marcar decision: execute
         ↓
-[5] fix                        ──►  correções + state.json/run.json (fix_done)
+[5] fix                        ──►  correções + triagem/status no storage (fix_done)
 ```
 
 ---
@@ -244,9 +249,13 @@ Se a branch não for informada, detecta com `git branch --show-current`. Base do
 | `houndsman --finalize` | Passo 3 — gerar o relatório |
 | `houndsman watchdog <id>` | Contexto de um watchdog (`--json`, `--rules`) |
 
-Flags do review: `--base` · `--head` · `--branch` · `--dir` · `--clean` · `--full` (força
+Flags do review: `--base` · `--head` · `--branch` · `--clean` · `--full` (força
 completo) · `--no-jev` · `--fail-on-blocking` (com `--finalize`).
 
+> Persistência: SQLite global em `<HOUNDSMAN_HOME>/houndsman.db`. O staging dos subagentes
+> (`briefs/`, `findings/`, contexto) vive em `<HOUNDSMAN_HOME>/work/<reviewId>/` e é limpo
+> depois do `--finalize`.
+
 ---
 
 ## Anti-padrões

package/src/skill/train.md

@@ -118,7 +118,7 @@ Cada informação tem o seu campo — não espelhe a regra em vários lugares:
 |---|---|
 | `.houndsman/watchdogs/<id>.ts` | **Fonte de verdade**: `defineWatchdog` com `rules` (severidade + texto), `scope`, `description`, `reviewFocus`, `exclude`, `breakingChange`, `contextFiles`, `classify` |
 | `.houndsman/watchdogs/index.ts` | `WATCHDOG_DEFINITIONS` — as **chaves definem os ids** (`WatchdogId`); `watchdogIds` é derivado |
-| `houndsman.config.ts` | `houndsmanConfig` do projeto — `projectName`, `artifactDir`, `watchdogs`, `exclusions`, `docMappings` (descoberto em runtime) |
+| `houndsman.config.ts` | `houndsmanConfig` do projeto — `projectName`, `storage`, `watchdogs`, `exclusions`, `docMappings` (descoberto em runtime) |
 | `.houndsman/exclusions.ts` | `EXCLUSION_PATTERNS` + `isExcluded` |
 | `.houndsman/doc-mappings.ts` | `DOC_MAPPINGS` (path → docs) |
 | `.houndsman/core/types.ts` | Snapshot gerado dos tipos + helpers (autocontido) |

package/src/skill/verify.md

@@ -4,15 +4,15 @@
 > (`.agents/skills/houndsman/SKILL.md` e `.claude/skills/houndsman/SKILL.md`).
 
 Confere se os findings de uma revisão **já finalizada** foram resolvidos — **sem re-revisar a
-PR**. Invocação: `/houndsman verify`. Consome o `state.json` do `hunt`; não revisa nem altera
-regras.
+PR**. Invocação: `/houndsman verify`. Consome a triagem persistida pelo `hunt`; não revisa nem
+altera regras.
 
 **Quando usar:**
 
 - Depois de corrigir achados (`fix`), para confirmar que as violações sumiram.
 - As violações foram resolvidas? · confere se ainda está lá · valida o fix.
 
-> **Pré-requisito:** existe `.houndsman/.runs/<branch-slug>/state.json` (gerado no `--finalize`).
+> **Pré-requisito:** existe uma review com findings persistidos (gerada no `--finalize`).
 
 ---
 
@@ -38,10 +38,10 @@ completa.
 ```bash
 bun run houndsman findings verify            # relatório (não altera o estado)
 bun run houndsman findings verify --json     # saída estruturada
-bun run houndsman findings verify --apply    # marca os resolvidos como done (ping no run.json)
+bun run houndsman findings verify --apply    # marca os resolvidos como done (ping no status)
 ```
 
-- Sem `--apply`: **só relatório** (grava `verify.md` na pasta da run). Nada muda no `state.json`.
+- Sem `--apply`: **só relatório** (grava o artefato `verify.md` no storage). Nada muda na triagem.
 - Com `--apply`: os findings com status **`resolved`** viram `execState: done` (histórico
   `by: "verify"`). `persisting` e `uncertain` **não** são tocados.
 

package/src/tests/__snapshots__/baseline.test.ts.snap

@@ -4,7 +4,7 @@ exports[`baseline — brief defaultRenderBrief (contexto, churn, overflow, candi
 "# Brief — Alpha (\`alpha\`)
 
 **Branch:** feature/x
-**Output obrigatório:** \`.houndsman/.runs/feature-x/findings/alpha.json\`
+**Output obrigatório:** \`/workspace/work/review-x/findings/alpha.json\`
 **Schema do output:** \`.houndsman/core/skill/OUTPUT-FORMAT.md\`
 
 ## Objetivo
@@ -382,10 +382,16 @@ export type HoundsmanConcurrency = {
 	jev?: number;
 };
 
+/** Backend de persistência (reviews, findings e artefatos). */
+export type HoundsmanStorage = {
+	provider?: "sqlite" | "file";
+	path?: string;
+};
+
 /** Contrato de configuração do motor. */
 export type HoundsmanConfig<TId extends string = string> = {
 	projectName: string;
-	artifactDir?: string;
+	storage?: HoundsmanStorage;
 	watchdogIds?: readonly TId[];
 	watchdogs: Record<TId, WatchdogDefinition>;
 	exclusions: readonly RegExp[];
@@ -412,10 +418,9 @@ export function defineHoundsmanConfig<TId extends string>(
 "/**
  * Mapeamento de padrões nos paths → documentação relevante.
  * Consumido pelo motor via \`HoundsmanConfig.docMappings\`.
- */
-export const DOC_MAPPINGS: readonly (readonly [RegExp, readonly string[]])[] = [
-	[/^src\\//, ["AGENTS.md"]],
-];
+ */\`core/\` é regenerado por \`houndsman update\`.
+# Runs, findings e artefatos vivem no storage global (fora do projeto).
+core
 "
 ,
   ".houndsman/exclusions.ts": 
@@ -486,9 +491,9 @@ import type { HoundsmanConfig } from "./.houndsman/core/types";
 /**
  * Configuração do houndsman para acme.
  *
- * Caminhos são resolvidos pela camada: artefatos em .houndsman/.runs e schema de
- * output em .houndsman/core/skill/OUTPUT-FORMAT.md. Ajuste watchdogs, exclusões e mapeamentos de
- * docs conforme o projeto.
+ * Runs, findings e artefatos vivem no storage global (SQLite por default) —
+ * fora do projeto. O schema de output fica em .houndsman/core/skill/OUTPUT-FORMAT.md. Ajuste
+ * watchdogs, exclusões e mapeamentos de docs conforme o projeto.
  */
 export const houndsmanConfig = {
 	projectName: "acme",
@@ -511,15 +516,15 @@ exports[`baseline — camada gerada setup gera os mesmos arquivos e conteúdos 3
   },
   {
     "file": ".houndsman/core/skill/OUTPUT-FORMAT.md",
-    "sha256": "3c6f261de0ca6d31",
+    "sha256": "06aedccd5688aaa8",
   },
   {
     "file": ".houndsman/core/skill/README.md",
-    "sha256": "7cc26ec5e1917a62",
+    "sha256": "0c1514669d044033",
   },
   {
     "file": ".houndsman/core/skill/SETUP.md",
-    "sha256": "5d6a4b56b1033970",
+    "sha256": "7ce23b97d9609ac2",
   },
   {
     "file": ".houndsman/core/skill/example-review.md",
@@ -527,31 +532,31 @@ exports[`baseline — camada gerada setup gera os mesmos arquivos e conteúdos 3
   },
   {
     "file": ".houndsman/core/skill/fix.md",
-    "sha256": "f16c0383ad1767fb",
+    "sha256": "9f10b2d846dc7db5",
   },
   {
     "file": ".houndsman/core/skill/hunt.md",
-    "sha256": "7e7d7e5535381b9b",
+    "sha256": "c47a24c6c36c1c03",
   },
   {
     "file": ".houndsman/core/skill/train.md",
-    "sha256": "564a1fd38d8e4836",
+    "sha256": "d774215c68d15159",
   },
   {
     "file": ".houndsman/core/skill/verify.md",
-    "sha256": "f8fcf8e12b142482",
+    "sha256": "7ae6e1ca8bf0a868",
   },
 ]
 `;
 
 exports[`baseline — artefatos de prepare/finalize gera classification, brief, manifest, review e state 1`] = `
 "Discovery: 1 watchdog(s) ativado(s), 3 arquivo(s), 1 deletado(s).
-Briefs: .houndsman/.runs/main/briefs/
+Briefs: <cwd>/.home/work/<uuid>/briefs/
 Deletado (breaking change): src/alpha/old.ts
 Jev: pulado (desativado (--no-jev)).
 Sem contexto da PR (rode \`bun run houndsman context\` antes, se houver PR).
 
-Próximo passo: despachar os sub-agentes (um por brief em .houndsman/.runs/main/briefs/).
+Próximo passo: despachar os sub-agentes (um por brief em <cwd>/.home/work/<uuid>/briefs/).
 Quando os findings estiverem gravados: bun run houndsman --finalize"
 `;
 
@@ -631,8 +636,8 @@ exports[`baseline — artefatos de prepare/finalize gera classification, brief,
         "src/alpha/b.ts"
       ],
       "overflow": 0,
-      "brief": ".houndsman/.runs/main/briefs/alpha.md",
-      "findings": ".houndsman/.runs/main/findings/alpha.json",
+      "brief": "<cwd>\\\\.home\\\\work\\\\<uuid>\\\\briefs\\\\alpha.md",
+      "findings": "<cwd>\\\\.home\\\\work\\\\<uuid>\\\\findings\\\\alpha.json",
       "status": "pending"
     }
   ],
@@ -657,7 +662,7 @@ exports[`baseline — artefatos de prepare/finalize gera classification, brief,
 "# Brief — Alpha (\`alpha\`)
 
 **Branch:** main
-**Output obrigatório:** \`.houndsman/.runs/main/findings/alpha.json\`
+**Output obrigatório:** \`<cwd>\\.home\\work\\<uuid>\\findings\\alpha.json\`
 **Schema do output:** \`.houndsman/core/skill/OUTPUT-FORMAT.md\`
 
 ## Objetivo
@@ -697,8 +702,8 @@ src/alpha/**
 `;
 
 exports[`baseline — artefatos de prepare/finalize gera classification, brief, manifest, review e state 2`] = `
-"Triagem: .houndsman/.runs/main/state.json — 1 finding(s).
-Relatório: .houndsman/.runs/main/review.md — 1 bloqueante(s), 0 atenção."
+"Triagem: sqlite:<cwd>\\houndsman.db#<uuid> — 1 finding(s).
+Relatório: sqlite:<cwd>\\houndsman.db#<uuid> — 1 bloqueante(s), 0 atenção."
 `;
 
 exports[`baseline — artefatos de prepare/finalize gera classification, brief, manifest, review e state: review.md 1`] = `
@@ -764,10 +769,6 @@ exports[`baseline — artefatos de prepare/finalize gera classification, brief,
   "order": [
     "<id>"
   ],
-  "reviewed": {
-    "headSha": "<sha>",
-    "at": "<timestamp>"
-  },
   "findings": {
     "<id>": {
       "id": "<id>",
@@ -796,19 +797,29 @@ exports[`baseline — artefatos de prepare/finalize gera classification, brief,
       "updatedAt": "<timestamp>",
       "history": []
     }
+  },
+  "reviewed": {
+    "headSha": "<sha>",
+    "at": "<timestamp>"
   }
-}
-"
+}"
 `;
 
 exports[`baseline — artefatos de prepare/finalize gera classification, brief, manifest, review e state: run.json 1`] = `
 "{
-  "version": 1,
-  "slug": "main",
+  "id": "<uuid>",
+  "repoKey": "path:<cwd>",
+  "repoRoot": "<cwd>",
   "branch": "main",
+  "slug": "main",
+  "base": "<sha>",
+  "head": "HEAD",
+  "headSha": "<sha>",
+  "reviewedSha": "<sha>",
+  "reviewedAt": "<timestamp>",
   "status": "review_done",
   "startedAt": "<timestamp>",
+  "createdAt": "<timestamp>",
   "updatedAt": "<timestamp>"
-}
-"
+}"
 `;

package/src/tests/baseline.test.ts

@@ -26,13 +26,16 @@ import {
 	writeUserLayer,
 } from "../core/commands/scaffold";
 import { defineHoundsmanConfig } from "../core/config";
-import { defaultOptions, finalize, prepare } from "../core/orchestrator";
+import { defaultOptions, finalize, prepare, reviewContext } from "../core/orchestrator";
+import { displayPath } from "../core/paths";
 import {
 	type MergedFinding,
 	renderDomainReport,
 	renderReport,
 	type WatchdogReport,
 } from "../core/report-builder";
+import { resolveRepoIdentity } from "../core/storage/repo-identity";
+import { SQLiteStorageProvider } from "../core/storage/sqlite/sqlite-storage";
 import { defineWatchdog } from "../core/types";
 import * as facade from "../index";
 
@@ -56,7 +59,6 @@ const baselineWatchdog = defineWatchdog({
 
 const baselineConfig = defineHoundsmanConfig({
 	projectName: "Baseline",
-	artifactDir: ".houndsman/.runs",
 	watchdogs: { alpha: baselineWatchdog },
 	exclusions: [/^dist\//],
 	docMappings: [[/^src\//, ["README.md"]]],
@@ -75,6 +77,10 @@ function normalizeArtifacts(text: string): string {
 			'"$1": "<timestamp>"',
 		)
 		.replace(/"\d{4}-\d{2}-\d{2}T[^"]*"/g, '"<timestamp>"')
+		.replace(
+			/\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/g,
+			"<uuid>",
+		)
 		.replace(/\b[0-9a-f]{40}\b/g, "<sha>")
 		.replace(/\b[0-9a-f]{16}\b/g, "<fingerprint>")
 		.replace(/\b[0-9a-f]{10}\b/g, "<id>")
@@ -128,7 +134,7 @@ describe("baseline — brief", () => {
 			overflow: ["src/alpha/c.ts"],
 			deleted: ["src/alpha/old.ts"],
 			branch: "feature/x",
-			outputPath: ".houndsman/.runs/feature-x/findings/alpha.json",
+			outputPath: "/workspace/work/review-x/findings/alpha.json",
 			outputFormatPath: ".houndsman/core/skill/OUTPUT-FORMAT.md",
 			docs: ["AGENTS.md", "README.md"],
 			context: {
@@ -317,6 +323,8 @@ describe("baseline — artefatos de prepare/finalize", () => {
 	test("gera classification, brief, manifest, review e state", async () => {
 		const cwd = mkdtempSync(join(tmpdir(), "houndsman-baseline-run-"));
 		const originalCwd = process.cwd();
+		const originalHome = process.env.HOUNDSMAN_HOME;
+		let storage: SQLiteStorageProvider | null = null;
 
 		try {
 			git(cwd, ["init", "-b", "main"]);
@@ -343,30 +351,58 @@ describe("baseline — artefatos de prepare/finalize", () => {
 			git(cwd, ["commit", "-m", "change"]);
 
 			const opts = {
-				...defaultOptions(".houndsman/.runs"),
+				...defaultOptions(),
 				base,
 				head: "HEAD",
 				noJev: true,
 			};
 
+			process.env.HOUNDSMAN_HOME = join(cwd, ".home");
 			process.chdir(cwd);
 
-			const prepared = await prepare(opts, "main", baselineConfig);
-			expect(normalizeArtifacts(prepared.messages.join("\n"))).toMatchSnapshot();
-
-			const runDir = join(cwd, ".houndsman", ".runs", "main");
-			for (const file of [
-				"classification.json",
-				"manifest.json",
-				"briefs/alpha.md",
-			]) {
-				expect(
-					normalizeArtifacts(readFileSync(join(runDir, file), "utf8")),
-				).toMatchSnapshot(file);
+			const config = {
+				...baselineConfig,
+				storage: {
+					provider: "sqlite" as const,
+					path: join(cwd, "houndsman.db"),
+				},
+			};
+			storage = new SQLiteStorageProvider(join(cwd, "houndsman.db"));
+			const repo = resolveRepoIdentity();
+			const review = storage.getOrCreateReview({
+				repo,
+				branch: "main",
+				slug: "main",
+			});
+			const ctx = reviewContext(storage, review);
+			const homeDisplay = displayPath(cwd);
+			const escapedCwd = cwd.replace(/\\/g, "\\\\");
+			const normalize = (text: string): string =>
+				normalizeArtifacts(
+					text
+						.replaceAll(escapedCwd, "<cwd>")
+						.replaceAll(cwd, "<cwd>")
+						.replaceAll(cwd.replace(/\\/g, "/"), "<cwd>")
+						.replaceAll(cwd.replace(/\\/g, "/").toLowerCase(), "<cwd>")
+						.replaceAll(homeDisplay, "<cwd>"),
+				);
+
+			const prepared = await prepare(opts, "main", config, ctx);
+			expect(normalize(prepared.messages.join("\n"))).toMatchSnapshot();
+
+			for (const name of ["classification.json", "manifest.json"]) {
+				const artifact = storage.readArtifact(review.id, name);
+				expect(normalize(artifact?.content ?? "")).toMatchSnapshot(name);
 			}
+			const workBrief = readFileSync(ctx.work.briefFile("alpha"), "utf8");
+			const briefArtifact = storage.readArtifact(review.id, "briefs/alpha.md");
+			expect(briefArtifact?.content).toBe(workBrief);
+			expect(normalize(briefArtifact?.content ?? "")).toMatchSnapshot(
+				"briefs/alpha.md",
+			);
 
 			writeFileSync(
-				join(runDir, "findings", "alpha.json"),
+				ctx.work.findingFile("alpha"),
 				`${JSON.stringify(
 					{
 						watchdogId: "alpha",
@@ -389,21 +425,24 @@ describe("baseline — artefatos de prepare/finalize", () => {
 				)}\n`,
 			);
 
-			const finalized = finalize(opts, "main", baselineConfig);
-			expect(normalizeArtifacts(finalized.messages.join("\n"))).toMatchSnapshot();
-
-			for (const file of [
-				"review.md",
-				"review.alpha.md",
-				"state.json",
-				"run.json",
-			]) {
-				expect(
-					normalizeArtifacts(readFileSync(join(runDir, file), "utf8")),
-				).toMatchSnapshot(file);
+			const finalized = finalize(opts, "main", config, ctx);
+			expect(normalize(finalized.messages.join("\n"))).toMatchSnapshot();
+
+			for (const name of ["review.md", "review.alpha.md"]) {
+				const artifact = storage.readArtifact(review.id, name);
+				expect(normalize(artifact?.content ?? "")).toMatchSnapshot(name);
 			}
+			expect(
+				normalize(JSON.stringify(storage.readFindings(review.id), null, 2)),
+			).toMatchSnapshot("state.json");
+			expect(
+				normalize(JSON.stringify(storage.getReview(review.id), null, 2)),
+			).toMatchSnapshot("run.json");
 		} finally {
+			storage?.close();
 			process.chdir(originalCwd);
+			if (originalHome === undefined) delete process.env.HOUNDSMAN_HOME;
+			else process.env.HOUNDSMAN_HOME = originalHome;
 			rmSync(cwd, { recursive: true, force: true });
 		}
 	}, 30_000);
@@ -433,12 +472,19 @@ const REQUIRED_EXPORTS = [
 	"GitRepository",
 	"ProjectConfig",
 	"ProjectFiles",
-	"RunLayout",
 	"Watchdog",
 	"WatchdogRegistry",
 	"systemClock",
 	"HoundsmanServer",
 	"HoundsmanEngine",
+	"ReviewWorkArea",
+	"SQLiteStorageProvider",
+	"FileStorageProvider",
+	"createStorage",
+	"createMemoryStorage",
+	"resolveRepoIdentity",
+	"buildRepoIdentity",
+	"normalizeRemote",
 	"ReviewSession",
 	"ReviewScopeResolver",
 	"buildCarryover",
@@ -447,7 +493,6 @@ const REQUIRED_EXPORTS = [
 	"ArgParser",
 	"ProjectScaffolder",
 	"FixBatchBuilder",
-	"Verifier",
 	"BriefRenderer",
 	"ReportRenderer",
 	"ManifestWriter",
@@ -455,7 +500,6 @@ const REQUIRED_EXPORTS = [
 	"assetPath",
 	"buildAnchor",
 	"buildStateFromFindings",
-	"buildStateFromRunDir",
 	"checkRegistry",
 	"churnOf",
 	"classifyEntries",
@@ -492,14 +536,12 @@ const REQUIRED_EXPORTS = [
 	"resolveConfigPath",
 	"resolveJevConcurrency",
 	"resolveMaxFilesPerBrief",
-	"runDir",
 	"runFindingsCommand",
 	"runVerifyCommand",
 	"selectByBudget",
 	"severityRank",
 	"sortByRisk",
 	"startServer",
-	"stateFile",
 	"summarize",
 	"syncState",
 ] as const;

package/src/tests/cli.test.ts

@@ -7,9 +7,13 @@
  */
 
 import { describe, expect, test } from "bun:test";
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { buildStateFromFindings, fileReader } from "../core/findings-state";
+import { dedupeFindings, parseWatchdogReport } from "../core/report-builder";
+import { buildRepoIdentity } from "../core/storage/repo-identity";
+import { SQLiteStorageProvider } from "../core/storage/sqlite/sqlite-storage";
 
 /** Caminho do executável do CLI (TS, rodado pelo Bun). */
 const CLI = join(import.meta.dir, "..", "cli", "index.ts");
@@ -17,6 +21,7 @@ const CLI = join(import.meta.dir, "..", "cli", "index.ts");
 /** Config mínima, como objeto literal (o `loadConfig` deriva `watchdogIds`). */
 const CONFIG = `export default {
 	projectName: "Smoke",
+	storage: { provider: "sqlite", path: "./houndsman.db" },
 	watchdogs: {
 		alpha: {
 			id: "alpha",
@@ -33,22 +38,18 @@ const CONFIG = `export default {
 };
 `;
 
-type Project = { cwd: string; artifacts: string; cleanup: () => void };
+type Project = { cwd: string; cleanup: () => void };
 
-/** Projeto temporário: config + uma run com um finding. */
+/** Projeto temporário: config + banco com uma run e um finding. */
 function makeProject(): Project {
 	const cwd = mkdtempSync(join(tmpdir(), "houndsman-cli-"));
-	const artifacts = join(cwd, ".houndsman", ".runs");
-	const runDir = join(artifacts, "main");
-	mkdirSync(join(runDir, "findings"), { recursive: true });
 	writeFileSync(join(cwd, "houndsman.config.ts"), CONFIG);
-	writeFileSync(
-		join(runDir, "classification.json"),
-		JSON.stringify({ watchdogs: { alpha: ["src/a.ts"] } }),
-	);
-	writeFileSync(
-		join(runDir, "findings", "alpha.json"),
-		JSON.stringify({
+
+	const storage = new SQLiteStorageProvider(join(cwd, "houndsman.db"));
+	const repo = buildRepoIdentity(null, cwd);
+	const review = storage.getOrCreateReview({ repo, branch: "main", slug: "main" });
+	const report = parseWatchdogReport(
+		{
 			watchdogId: "alpha",
 			reviewedFiles: ["src/a.ts"],
 			skipped: [],
@@ -62,11 +63,22 @@ function makeProject(): Project {
 					action: "tipar",
 				},
 			],
-		}),
+		},
+		"alpha.json",
 	);
+	if (report) {
+		storage.writeFindings(
+			review.id,
+			buildStateFromFindings(dedupeFindings([report]), {
+				branch: "main",
+				readFile: fileReader(cwd),
+			}),
+		);
+	}
+	storage.close();
+
 	return {
 		cwd,
-		artifacts,
 		cleanup: () => rmSync(cwd, { recursive: true, force: true }),
 	};
 }
@@ -112,8 +124,6 @@ describe("cli smoke — imports dinâmicos", () => {
 				"findings",
 				"summary",
 				"--json",
-				"--dir",
-				project.artifacts,
 				"--branch",
 				"main",
 			]);
@@ -132,8 +142,6 @@ describe("cli smoke — imports dinâmicos", () => {
 				"submit",
 				"--dry-run",
 				"--json",
-				"--dir",
-				project.artifacts,
 				"--branch",
 				"main",
 			]);
@@ -160,6 +168,19 @@ describe("cli smoke — imports dinâmicos", () => {
 		try {
 			const result = runCli(project.cwd, ["context", "--branch", "main"]);
 			expect(result.code).toBe(0);
+
+			// Auditoria: o brief do contexto fica persistido mesmo sem PR.
+			const storage = new SQLiteStorageProvider(join(project.cwd, "houndsman.db"));
+			try {
+				const repo = buildRepoIdentity(null, project.cwd);
+				const review = storage.findReview(repo.key, "main");
+				expect(review).not.toBeNull();
+				expect(
+					storage.readArtifact(review?.id ?? "", "context-brief.md")?.kind,
+				).toBe("context-brief");
+			} finally {
+				storage.close();
+			}
 		} finally {
 			project.cleanup();
 		}