@payconductor/houndsman 0.3.0 → 0.4.0

package/src/server/run-repository.ts

@@ -1,28 +1,25 @@
 /**
- * Repositório das runs (servidor) — leitura/escrita dos artefatos e estado.
+ * Repositório das runs (servidor) — leitura/escrita via storage.
  *
- * Concentra o acesso a disco usado pelas rotas: lista de runs, detalhe,
- * findings, sync, envio à PR e artefatos. A validação de slug (path traversal)
- * continua em `artifacts.ts`.
+ * 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 { join, resolve } from "node:path";
-import { type HoundsmanConfig, resolveArtifactDir } from "../core/config";
+import { resolve } from "node:path";
 import {
 	applyFindingUpdate,
-	buildStateFromRunDir,
 	emptyState,
 	type FindingDecision,
 	type FindingExecState,
 	type FindingState,
 	type FindingsFilter,
-	FindingsRepository,
 	type FindingsStateFile,
 	type FindingsSummary,
 	type FindingUpdate,
 	fileReader,
 	filterFindings,
 	reorder,
+	resolveFindingId,
 	type SyncResult,
 	summarize,
 	syncState,
@@ -34,22 +31,18 @@ import {
 	type SubmitSelection,
 	submitFindings,
 } from "../core/github-review";
-import { STATE_FILE } from "../core/paths";
-import {
-	pingFindingsStatus,
-	type RunStatus,
-	type RunStatusFile,
-	readRunStatus,
-} from "../core/run-status";
+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 { listRunSlugs, readRunFile, readRunJson, runDirForSlug } from "./artifacts";
+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: RunStatus | null;
+	status: ReviewRecord["status"];
 	summary: FindingsSummary;
 };
 
@@ -57,7 +50,7 @@ export type RunListItem = {
 export type RunDetail = {
 	slug: string;
 	branch: string;
-	status: RunStatusFile | null;
+	status: ReviewRecord | null;
 	manifest: unknown;
 	summary: FindingsSummary;
 	watchdogs: string[];
@@ -70,63 +63,58 @@ export type SubmitResult =
 	| { available: false; reason: string }
 	| { available: true; target: unknown; outcome: unknown };
 
-/** Acesso às runs de um diretório de artefatos. */
-export class RunRepository {
-	private readonly artifactDir: string;
+/** Metadados de um artefato (sem conteúdo) para a lista da UI. */
+export type ArtifactListItem = {
+	name: string;
+	kind: string;
+	contentType: string;
+	updatedAt: string;
+};
 
-	constructor(artifactDir: string) {
-		this.artifactDir = artifactDir;
-	}
+/** Acesso às runs de um repositório. */
+export class RunRepository {
+	private readonly storage: StorageProvider;
+	private readonly repo: RepoIdentity;
 
-	static fromConfig(config: HoundsmanConfig): RunRepository {
-		return new RunRepository(resolveArtifactDir(config));
+	constructor(storage: StorageProvider, repo: RepoIdentity) {
+		this.storage = storage;
+		this.repo = repo;
 	}
 
-	/** `true` se o slug aponta para uma run válida. */
+	/** `true` se o slug aponta para uma run do repositório atual. */
 	exists(slug: string): boolean {
-		return runDirForSlug(this.artifactDir, slug) !== null;
+		return this.findBySlug(slug) !== null;
 	}
 
 	/** Lista as runs com resumo (mais recentes primeiro). */
 	list(): RunListItem[] {
-		return (
-			listRunSlugs(this.artifactDir)
-				.map((slug) => {
-					const dir = join(this.artifactDir, slug);
-					const state = this.loadState(dir, slug);
-					const manifest = readRunJson<{
-						branch?: string;
-						generatedAt?: string;
-					}>(dir, "manifest.json");
-					const status = readRunStatus(dir);
-					return {
-						slug,
-						branch: state.branch || manifest?.branch || slug,
-						updatedAt: status?.updatedAt ?? state.updatedAt,
-						status: status?.status ?? null,
-						summary: summarize(state),
-					};
-				})
-				// Mais recentes primeiro (ISO 8601 compara lexicograficamente).
-				.sort((a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? ""))
-		);
+		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 dir = runDirForSlug(this.artifactDir, slug);
-		if (!dir) return null;
-		const state = this.loadState(dir, slug);
-		const classification = readRunJson<{
+		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[];
-		}>(dir, "classification.json");
+		}>(review, "classification.json");
 		return {
-			slug,
-			branch: state.branch || slug,
-			status: readRunStatus(dir),
-			manifest: readRunJson(dir, "manifest.json"),
+			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 ?? [],
@@ -134,6 +122,43 @@ export class RunRepository {
 		};
 	}
 
+	/** 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,
@@ -143,9 +168,9 @@ export class RunRepository {
 		findings: (FindingState & { absFile: string })[];
 		summary: FindingsSummary;
 	} | null {
-		const dir = runDirForSlug(this.artifactDir, slug);
-		if (!dir) return null;
-		const state = this.loadState(dir, slug);
+		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,
@@ -155,18 +180,22 @@ export class RunRepository {
 			includeAbsent: params.get("all") === "1",
 		};
 		return {
-			branch: state.branch,
-			findings: filterFindings(state, filter).map(toClientFinding),
+			branch: review.branch,
+			findings: filterFindings(state, filter).map((finding) =>
+				toClientFinding(finding, review),
+			),
 			summary: summarize(state),
 		};
 	}
 
-	/** Um finding (null se ausente/inválido). */
+	/** Um finding (null se ausente/inválido). Aceita prefixo único do id. */
 	finding(slug: string, id: string): (FindingState & { absFile: string }) | null {
-		const dir = runDirForSlug(this.artifactDir, slug);
-		if (!dir) return null;
-		const finding = this.loadState(dir, slug).findings[id];
-		return finding ? toClientFinding(finding) : 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). */
@@ -175,17 +204,18 @@ export class RunRepository {
 		id: string,
 		body: FindingUpdate,
 	): (FindingState & { absFile: string }) | null {
-		const dir = runDirForSlug(this.artifactDir, slug);
-		if (!dir) return null;
-		const store = this.store(dir, slug);
-		const state = store.read() ?? this.buildForRun(dir, slug) ?? emptyState(slug);
-		const finding = state.findings[id];
-		if (!finding) return 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);
-		store.write(state);
-		pingFindingsStatus(dir, state);
-		return toClientFinding(finding);
+		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. */
@@ -193,22 +223,21 @@ export class RunRepository {
 		result: SyncResult;
 		summary: FindingsSummary;
 	} | null {
-		const dir = runDirForSlug(this.artifactDir, slug);
-		if (!dir) return null;
-		const store = this.store(dir, slug);
-		const state = store.read() ?? this.buildForRun(dir, slug) ?? emptyState(slug);
+		const review = this.findBySlug(slug);
+		if (!review) return null;
+		const state = this.loadState(review);
 		const result = syncState(state, fileReader(process.cwd()));
-		store.write(state);
-		pingFindingsStatus(dir, state);
+		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 dir = runDirForSlug(this.artifactDir, slug);
-		if (!dir) return null;
-		const state = this.loadState(dir, slug);
-		const target = resolvePrTarget(runner, state.branch || slug);
+		const review = this.findBySlug(slug);
+		if (!review) return null;
+		const state = this.loadState(review);
+		const target = resolvePrTarget(runner, review.branch);
 		return buildSubmitPreview(state, target);
 	}
 
@@ -218,10 +247,10 @@ export class RunRepository {
 		selection: SubmitSelection,
 		runner: GhRunner,
 	): SubmitResult | null {
-		const dir = runDirForSlug(this.artifactDir, slug);
-		if (!dir) return null;
-		const state = this.loadState(dir, slug);
-		const target = resolvePrTarget(runner, state.branch || slug);
+		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({
@@ -230,55 +259,31 @@ export class RunRepository {
 			runner,
 			selection,
 		});
-		this.store(dir, slug).write(state);
-		pingFindingsStatus(dir, state);
+		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 dir = runDirForSlug(this.artifactDir, slug);
-		if (!dir) return null;
-		const content = readRunFile(dir, name);
-		if (content === null) return null;
-		const type = name.toLowerCase().endsWith(".json")
-			? "application/json; charset=utf-8"
-			: "text/markdown; charset=utf-8";
-		return { content, type };
-	}
-
-	// -----------------------------------------------------------------------
-	// Internos
-	// -----------------------------------------------------------------------
-
-	private store(dir: string, slug: string): FindingsRepository {
-		return new FindingsRepository(join(dir, STATE_FILE), slug);
-	}
-
-	private buildForRun(dir: string, slug: string): FindingsStateFile | null {
-		const manifest = readRunJson<{ branch?: string }>(dir, "manifest.json");
-		return buildStateFromRunDir(
-			dir,
-			manifest?.branch ?? slug,
-			fileReader(process.cwd()),
-		);
-	}
-
-	/**
-	 * Lê o estado da run. Se ausente, reconstrói dos artefatos e PERSISTE — os ids
-	 * são aleatórios, então precisam ser estáveis entre requisições.
-	 */
-	private loadState(dir: string, slug: string): FindingsStateFile {
-		const store = this.store(dir, slug);
-		const existing = store.read();
-		if (existing) return existing;
-		const built = this.buildForRun(dir, slug);
-		if (built) {
-			store.write(built);
-			return built;
-		}
-		return emptyState(slug);
+		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 };
 	}
 }
 
@@ -286,6 +291,9 @@ export class RunRepository {
  * 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): FindingState & { absFile: string } {
-	return { ...finding, absFile: resolve(process.cwd(), finding.file) };
+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`.