@payconductor/houndsman 0.2.0 → 0.4.0

package/src/server/run-repository.ts

@@ -0,0 +1,299 @@
+/**
+ * Repositório das runs (servidor) — leitura/escrita via storage.
+ *
+ * Escopa tudo ao repositório do cwd: a UI mostra só as runs do projeto atual.
+ * O slug continua sendo o branch-slug (estável nas URLs).
+ */
+
+import { resolve } from "node:path";
+import {
+	applyFindingUpdate,
+	emptyState,
+	type FindingDecision,
+	type FindingExecState,
+	type FindingState,
+	type FindingsFilter,
+	type FindingsStateFile,
+	type FindingsSummary,
+	type FindingUpdate,
+	fileReader,
+	filterFindings,
+	reorder,
+	resolveFindingId,
+	type SyncResult,
+	summarize,
+	syncState,
+} from "../core/findings-state";
+import {
+	buildSubmitPreview,
+	type GhRunner,
+	resolvePrTarget,
+	type SubmitSelection,
+	submitFindings,
+} from "../core/github-review";
+import { pingFindingsStatus } from "../core/run-status";
+import { systemClock } from "../core/services/clock";
+import type { RepoIdentity, ReviewRecord, StorageProvider } from "../core/storage/types";
+import type { Severity } from "../core/types";
+import { isSlug } from "./artifacts";
+
+/** Item da lista de execuções (sidebar) — já ordenado do mais recente ao antigo. */
+export type RunListItem = {
+	slug: string;
+	branch: string;
+	updatedAt?: string;
+	status: ReviewRecord["status"];
+	summary: FindingsSummary;
+};
+
+/** Detalhe de uma run (cabeçalho da UI). */
+export type RunDetail = {
+	slug: string;
+	branch: string;
+	status: ReviewRecord | null;
+	manifest: unknown;
+	summary: FindingsSummary;
+	watchdogs: string[];
+	unclassified: string[];
+	deleted: string[];
+};
+
+/** Resultado do envio dos findings à PR. */
+export type SubmitResult =
+	| { available: false; reason: string }
+	| { available: true; target: unknown; outcome: unknown };
+
+/** Metadados de um artefato (sem conteúdo) para a lista da UI. */
+export type ArtifactListItem = {
+	name: string;
+	kind: string;
+	contentType: string;
+	updatedAt: string;
+};
+
+/** Acesso às runs de um repositório. */
+export class RunRepository {
+	private readonly storage: StorageProvider;
+	private readonly repo: RepoIdentity;
+
+	constructor(storage: StorageProvider, repo: RepoIdentity) {
+		this.storage = storage;
+		this.repo = repo;
+	}
+
+	/** `true` se o slug aponta para uma run do repositório atual. */
+	exists(slug: string): boolean {
+		return this.findBySlug(slug) !== null;
+	}
+
+	/** Lista as runs com resumo (mais recentes primeiro). */
+	list(): RunListItem[] {
+		return this.storage.listReviews(this.repo.key).map((review) => {
+			const state = this.storage.readFindings(review.id);
+			return {
+				slug: review.slug,
+				branch: review.branch,
+				updatedAt: review.updatedAt,
+				status: review.status,
+				summary: summarize(state ?? emptyState(review.branch)),
+			};
+		});
+	}
+
+	/** Detalhe da run (null se o slug for inválido). */
+	detail(slug: string): RunDetail | null {
+		const review = this.findBySlug(slug);
+		if (!review) return null;
+		const state = this.loadState(review);
+		const classification = this.readArtifactJson<{
+			watchdogs?: Record<string, string[]>;
+			unclassified?: string[];
+			deleted?: string[];
+		}>(review, "classification.json");
+		return {
+			slug: review.slug,
+			branch: review.branch,
+			status: review,
+			manifest: this.readArtifactJson(review, "manifest.json"),
+			summary: summarize(state),
+			watchdogs: Object.keys(classification?.watchdogs ?? {}),
+			unclassified: classification?.unclassified ?? [],
+			deleted: classification?.deleted ?? [],
+		};
+	}
+
+	/** Aplica `VACUUM`/`optimize` no backend (chamado no start do server). */
+	maintain(): void {
+		this.storage.maintain();
+	}
+
+	/** Fecha o provider (shutdown do server). */
+	dispose(): void {
+		this.storage.close();
+	}
+
+	// -----------------------------------------------------------------------
+	// Internos
+	// -----------------------------------------------------------------------
+
+	private findBySlug(slug: string): ReviewRecord | null {
+		if (!isSlug(slug)) return null;
+		return (
+			this.storage
+				.listReviews(this.repo.key)
+				.find((review) => review.slug === slug) ?? null
+		);
+	}
+
+	private loadState(review: ReviewRecord): FindingsStateFile {
+		return this.storage.readFindings(review.id) ?? emptyState(review.branch);
+	}
+
+	private readArtifactJson<T>(review: ReviewRecord, name: string): T | null {
+		const artifact = this.storage.readArtifact(review.id, name);
+		if (!artifact) return null;
+		try {
+			return JSON.parse(artifact.content) as T;
+		} catch {
+			return null;
+		}
+	}
+
+	/** Findings filtrados + resumo (null se o slug for inválido). */
+	findings(
+		slug: string,
+		params: URLSearchParams,
+	): {
+		branch: string;
+		findings: (FindingState & { absFile: string })[];
+		summary: FindingsSummary;
+	} | null {
+		const review = this.findBySlug(slug);
+		if (!review) return null;
+		const state = this.loadState(review);
+		const filter: FindingsFilter = {
+			decision: (params.get("decision") as FindingDecision) || undefined,
+			execState: (params.get("exec") as FindingExecState) || undefined,
+			severity: (params.get("severity") as Severity) || undefined,
+			watchdog: params.get("watchdog") || undefined,
+			file: params.get("file") || undefined,
+			includeAbsent: params.get("all") === "1",
+		};
+		return {
+			branch: review.branch,
+			findings: filterFindings(state, filter).map((finding) =>
+				toClientFinding(finding, review),
+			),
+			summary: summarize(state),
+		};
+	}
+
+	/** Um finding (null se ausente/inválido). Aceita prefixo único do id. */
+	finding(slug: string, id: string): (FindingState & { absFile: string }) | null {
+		const review = this.findBySlug(slug);
+		if (!review) return null;
+		const state = this.loadState(review);
+		const resolution = resolveFindingId(state, id);
+		if (resolution.status !== "found") return null;
+		return toClientFinding(state.findings[resolution.id], review);
+	}
+
+	/** Aplica uma atualização a um finding (null se ausente/inválido). */
+	update(
+		slug: string,
+		id: string,
+		body: FindingUpdate,
+	): (FindingState & { absFile: string }) | null {
+		const review = this.findBySlug(slug);
+		if (!review) return null;
+		const state = this.loadState(review);
+		const resolution = resolveFindingId(state, id);
+		if (resolution.status !== "found") return null;
+		const finding = state.findings[resolution.id];
+		applyFindingUpdate(finding, body);
+		reorder(state);
+		state.updatedAt = systemClock();
+		this.storage.writeFindings(review.id, state);
+		pingFindingsStatus(this.storage, review.id, state);
+		return toClientFinding(finding, review);
+	}
+
+	/** Reancora os findings contra os arquivos atuais. */
+	sync(slug: string): {
+		result: SyncResult;
+		summary: FindingsSummary;
+	} | null {
+		const review = this.findBySlug(slug);
+		if (!review) return null;
+		const state = this.loadState(review);
+		const result = syncState(state, fileReader(process.cwd()));
+		this.storage.writeFindings(review.id, state);
+		pingFindingsStatus(this.storage, review.id, state);
+		return { result, summary: summarize(state) };
+	}
+
+	/** Prévia do envio da revisão (candidatos + disponibilidade da PR). */
+	submitPreview(slug: string, runner: GhRunner): unknown | null {
+		const review = this.findBySlug(slug);
+		if (!review) return null;
+		const state = this.loadState(review);
+		const target = resolvePrTarget(runner, review.branch);
+		return buildSubmitPreview(state, target);
+	}
+
+	/** Envia os findings selecionados à PR (fail-open). */
+	submit(
+		slug: string,
+		selection: SubmitSelection,
+		runner: GhRunner,
+	): SubmitResult | null {
+		const review = this.findBySlug(slug);
+		if (!review) return null;
+		const state = this.loadState(review);
+		const target = resolvePrTarget(runner, review.branch);
+		if (!target.ok) return { available: false, reason: target.reason };
+
+		const outcome = submitFindings({
+			state,
+			target: target.target,
+			runner,
+			selection,
+		});
+		this.storage.writeFindings(review.id, state);
+		pingFindingsStatus(this.storage, review.id, state);
+		return { available: true, target: target.target, outcome };
+	}
+
+	/** Lista os artefatos da run (sem conteúdo). */
+	artifacts(slug: string): ArtifactListItem[] | null {
+		const review = this.findBySlug(slug);
+		if (!review) return null;
+		return this.storage.listArtifacts(review.id).map((artifact) => ({
+			name: artifact.name,
+			kind: artifact.kind,
+			contentType: artifact.contentType,
+			updatedAt: artifact.updatedAt,
+		}));
+	}
+
+	/** Conteúdo de um artefato (`json`/`md`) da run (null se não servível). */
+	artifact(slug: string, name: string): { content: string; type: string } | null {
+		if (!/\.(json|md)$/i.test(name)) return null;
+		const review = this.findBySlug(slug);
+		if (!review) return null;
+		const artifact = this.storage.readArtifact(review.id, name);
+		if (!artifact) return null;
+		return { content: artifact.content, type: artifact.contentType };
+	}
+}
+
+/**
+ * Finding + caminho absoluto. O cliente monta o link `vscode://file/...` e não
+ * conhece o cwd do servidor — o caminho relativo do relatório não basta.
+ */
+function toClientFinding(
+	finding: FindingState,
+	review: ReviewRecord,
+): FindingState & { absFile: string } {
+	return { ...finding, absFile: resolve(review.repoRoot, finding.file) };
+}

package/src/skill/OUTPUT-FORMAT.md

@@ -1,20 +1,22 @@
 # Formato de Saída dos Watchdogs
 
 Todo watchdog DEVE gravar **um arquivo JSON** com seus achados. O `report-builder.ts`
-consolida os JSONs em `.houndsman/.runs/<branch-slug>/review.md`.
+consolida os JSONs no artefato `review.md` do storage global.
 
 > **Não** escrever markdown livre no chat. O único output consumido pelo pipeline é o JSON.
 
 ## Caminho do arquivo
 
-O caminho exato é informado no brief do watchdog (gerado por `houndsman`):
+O caminho exato é informado no brief do watchdog (gerado por `houndsman`). Ele aponta para o
+staging global da review:
 
 ```
-.houndsman/.runs/<branch-slug>/findings/<watchdogId>.json
+<HOUNDSMAN_HOME>/work/<reviewId>/findings/<watchdogId>.json
 ```
 
-- `<branch-slug>`: branch com `/` substituído por `-` (ex.: `feature/x` → `feature-x`).
+- `<reviewId>`: UUID da review (estável entre prepare/finalize).
 - `<watchdogId>`: id do watchdog (ex.: `backend-architecture`).
+- Use exatamente o `outputPath` do brief — não invente caminhos.
 
 ## Schema
 

package/src/skill/README.md

@@ -57,26 +57,33 @@ Um único skill (`/houndsman`), quatro capabilities (detalhadas em `hunt.md`, `t
 ### Flags
 
 `--config <path>` · `--base <branch>` (default `main`) · `--head <ref>` (default `HEAD`) ·
-`--branch <nome>` · `--dir <dir>` · `--clean` · `--full` · `--no-jev` · `--fail-on-blocking` (no `--finalize`).
+`--branch <nome>` · `--clean` · `--full` · `--no-jev` · `--fail-on-blocking` (no `--finalize`).
 
 ## Artefatos
 
-Tudo em `.houndsman/.runs/<branch-slug>/` (default do `artifactDir`, `.houndsman/.runs`):
+Runs, findings e artefatos vivem no **storage global** (SQLite em `<HOUNDSMAN_HOME>/houndsman.db`):
 
-| Arquivo | Conteúdo |
+| Item | Conteúdo |
 |---|---|
+| review | Repo (`origin` normalizado), branch, slug, base/head, commit revisado, status e timestamps |
+| findings | Decisão/execução + fingerprint + âncora + histórico + vínculo com o GitHub |
 | `classification.json` | Watchdogs ativados + status (A/M/D/R) + churn |
 | `candidates.json` | Candidatos da pré-análise Jev |
-| `context.json` | Payload bruto da PR via `gh` (ou marcador de indisponível) |
-| `context-summary.json` | Resumo do subagente (objetivo/motivação/alterações) |
+| `manifest.json` | Resumo (watchdogs, arquivos, deletados, contexto, orçamento, churn) |
+| `briefs/<watchdog>.md` | Brief enviado a cada sub-agente (auditoria) |
+| `review.md` / `review.<watchdog>.md` | Relatório consolidado e por domínio |
+| `verify.md` | Relatório do `findings verify` |
+| `context.json` / `context-brief.md` / `context-summary.json` | Contexto da PR |
+
+O **staging dos subagentes** fica em `<HOUNDSMAN_HOME>/work/<reviewId>/` e é limpo após o
+`--finalize`. Briefs e contexto também são persistidos como artefatos (acima); apenas os
+findings brutos existem só no staging:
+
+| Arquivo | Conteúdo |
+|---|---|
 | `briefs/<watchdog>.md` | Instruções prontas para cada sub-agente (arquivos por risco) |
-| `manifest.json` | Resumo (watchdogs, arquivos, deletados, status, contexto, orçamento, churn) |
 | `findings/<watchdog>.json` | Saída dos sub-agentes (schema `OUTPUT-FORMAT.md`) |
-| `review.md` | Relatório final (achados agrupados por arquivo) |
-| `review.<watchdog>.md` | Relatório por domínio (só quando há achados) |
-| `state.json` | Estado de triagem dos findings (decisão/execução + fingerprint + commit revisado) |
-| `run.json` | Status do run (`reviewing`/`review_done`/`fixing`/`fix_done`) + timestamps |
-| `verify.md` | Relatório do `findings verify` (resolvidos/persistem/incertos) |
+| `context.json` / `context-brief.md` / `context-summary.json` | Contexto da PR |
 
 ## Estrutura
 
@@ -101,10 +108,11 @@ src/
 │   ├── doc-discoverer.ts    # descoberta de docs
 │   ├── report-builder.ts    # dedupe/render do relatório
 │   ├── finding-anchor.ts    # âncora/fingerprint de conteúdo + reancoragem
-│   ├── findings-state.ts    # estado de triagem (state.json) + store atômico
+│   ├── findings-state.ts    # estado de triagem + funções puras
 │   ├── git-revision.ts      # refs/ancestralidade + arquivo por commit + diff por intervalo
 │   ├── verify.ts            # verificação de findings (tier local + Jev)
-│   ├── run-status.ts        # run.json (reviewing/review_done/fixing/fix_done)
+│   ├── run-status.ts        # status da review (reviewing/review_done/fixing/fix_done)
+│   ├── storage/            # StorageProvider (SQLite default + arquivos) + staging
 │   ├── fix-batch.ts         # agrupamento/paginação do lote (findings batch)
 │   ├── registry-check.ts    # validações anti-drift (config-driven)
 │   ├── commands/            # context · review · watchdog · setup · update · test
@@ -118,7 +126,7 @@ src/
 ```
 houndsman.config.ts           # HoundsmanConfig (dados; descoberto em runtime)
 .houndsman/
-├── .gitignore                # AUTO — ignora core/ e .runs/
+├── .gitignore                # AUTO — ignora core/ (nada de execução fica no projeto)
 ├── core/                     # AUTO — sincronizado por `houndsman update`
 │   ├── types.ts              # snapshot dos tipos + helpers (autocontido)
 │   └── skill/*.md            # documentação do skill

package/src/skill/SETUP.md

@@ -38,12 +38,12 @@ A camada separa o que é **auto-gerado** do que é **do usuário**:
 | `.houndsman/doc-mappings.ts` | usuário | path → documentação de contexto |
 | `.houndsman/core/types.ts` | **auto** | Snapshot dos tipos + helpers (tipagem sem install) |
 | `.houndsman/core/skill/*.md` | **auto** | Documentação do skill |
-| `.houndsman/.gitignore` | **auto** | Ignora `core/` e `.runs/` (gerados/temporários) |
+| `.houndsman/.gitignore` | **auto** | Ignora `core/` (gerado) |
 | `.agents/skills/houndsman/SKILL.md` etc. | **auto** | `SKILL.md` do skill `/houndsman` (capabilities `hunt`/`train`/`fix`) por harness |
 
 Além disso, adiciona o script `"houndsman": "houndsman"` ao `package.json` — assim
-`bun run houndsman [...]` funciona na raiz do projeto. Os artefatos ficam em
-`.houndsman/.runs/<branch-slug>/` (auto-ignorados).
+`bun run houndsman [...]` funciona na raiz do projeto. Runs, findings e artefatos ficam no
+storage global (`<HOUNDSMAN_HOME>/houndsman.db`) — fora do projeto.
 
 Flags: `--name <projeto>` · `--harness agents,claude|both|none` · `--force` (sobrescreve só os
 arquivos do usuário). É **idempotente** — arquivos do usuário existentes são mantidos.
@@ -80,7 +80,7 @@ Definido em `src/core/config.ts` (pacote) e espelhado em `.houndsman/core/types.
 | Campo | Descrição |
 |---|---|
 | `projectName` | Nome legível (prompts/docs). |
-| `artifactDir` | **Opcional** — onde gravar os artefatos (default `.houndsman/.runs`). |
+| `storage` | **Opcional** — `{ provider: "sqlite" \| "file", path? }`. Default: SQLite em `<HOUNDSMAN_HOME>/houndsman.db`. |
 | `watchdogs` | Definições dos watchdogs (incluem `classify`); os **ids são derivados** das chaves. |
 | `exclusions` | Arquivos que nunca entram na revisão. |
 | `docMappings` | Path → documentação de contexto. |

package/src/skill/fix.md

@@ -4,7 +4,7 @@
 > (`.agents/skills/houndsman/SKILL.md` e `.claude/skills/houndsman/SKILL.md`).
 
 Corrige os achados de uma revisão **já finalizada** (`hunt`): lê a triagem, aplica as
-correções marcadas e mantém o estado de triagem em dia — **sem editar o `state.json` à mão**.
+correções marcadas e mantém o estado de triagem em dia — **sem editar o banco à mão**.
 
 Invocação: `/houndsman fix`. Não revisa nem altera regras; consome o que o `hunt` produziu.
 
@@ -15,8 +15,8 @@ Invocação: `/houndsman fix`. Não revisa nem altera regras; consome o que o `h
   `findings set <id> --decision execute`.
 - "Corrija os findings", "aplica as correções", "resolve os bloqueantes".
 
-> **Pré-requisito:** existe `.houndsman/.runs/<branch-slug>/state.json` da run atual
-> (gerado no `--finalize`). Se não existir, a revisão não foi finalizada — rode o `hunt` antes.
+> **Pré-requisito:** existe uma review com findings no storage global (gerada no
+> `--finalize`). Se não existir, a revisão não foi finalizada — rode o `hunt` antes.
 > A triagem (`execute`) é feita na UI (`bun run houndsman server --open`) ou via `findings set`,
 > e é o que alimenta a fila de correção.
 
@@ -153,7 +153,7 @@ Subagente serve para **isolar contexto**, não para paralelizar. Regras:
   colidem.
 - O subagente recebe **só** o grupo atual (findings + arquivo) e devolve um resumo compacto
   (ids corrigidos / não corrigidos + motivo). Assim o agente principal não carrega o arquivo.
-- A escrita do `state.json` fica **centralizada no agente principal**: o subagente apenas
+- A escrita da triagem fica **centralizada no agente principal**: o subagente apenas
   lê/edita; `sync` / `done` / `set` são do orquestrador. Nada de `findings` dentro do subagente.
 - Grupos pequenos (1–2 findings) o próprio agente corrige inline.
 
@@ -196,7 +196,7 @@ Arquivo: <file>
 
 - ❌ Carregar a fila inteira de uma vez (`findings list` sem filtro) — use `findings batch`.
 - ❌ Corrigir vários grupos em paralelo (subagentes simultâneos sobre arquivos que se relacionam).
-- ❌ Editar `.houndsman/.runs/<slug>/state.json` à mão — use os comandos `findings`.
+- ❌ Editar o banco/storage à mão — use os comandos `findings`.
 - ❌ Corrigir findings `pending` ou `ignore` sem o usuário marcar `execute`.
 - ❌ Chavear por `(file, line)` — a confiança é o **fingerprint** de conteúdo.
 - ❌ Correção cosmética para "sumir" com o finding sem atender a `rule`.

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.