@payconductor/houndsman 0.3.0 → 0.5.0

package/src/core/commands/scaffold.ts

@@ -5,7 +5,7 @@
  * **do usuário**:
  *
  *   .houndsman/
- *   ├── .gitignore          AUTO — ignora core/ e .runs/ (gerados/temporários)
+ *   ├── .gitignore          AUTO — ignora core/ (gerado)
  *   ├── core/types.ts       AUTO — snapshot dos tipos + helpers
  *   ├── core/skill/*.md     AUTO — docs do skill (com {{projectName}} resolvido)
  *   ├── watchdogs/*.ts      USUÁRIO
@@ -16,13 +16,7 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, join } from "node:path";
 import { SKILL_DIR, SKILL_FILE } from "../assets";
-import {
-	ARTIFACT_DIR,
-	CORE_DIR,
-	CORE_SKILL_DIR,
-	OUTPUT_FORMAT_PATH,
-	PROJECT_DIR,
-} from "../paths";
+import { CORE_DIR, CORE_SKILL_DIR, OUTPUT_FORMAT_PATH, PROJECT_DIR } from "../paths";
 
 export type Harness = "agents" | "claude";
 
@@ -87,9 +81,9 @@ import type { HoundsmanConfig } from "./${CORE_DIR}/types";
 /**
  * Configuração do houndsman para ${projectName}.
  *
- * Caminhos são resolvidos pela camada: artefatos em ${ARTIFACT_DIR} e schema de
- * output em ${OUTPUT_FORMAT_PATH}. 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 ${OUTPUT_FORMAT_PATH}. Ajuste
+ * watchdogs, exclusões e mapeamentos de docs conforme o projeto.
  */
 export const houndsmanConfig = {
 	projectName: "${projectName}",
@@ -182,10 +176,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[];
@@ -267,10 +267,9 @@ export function isExcluded(filePath: string): boolean {
 const DOC_MAPPINGS_TEMPLATE = `/**
  * 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
 `;
 
 const PROJECT_GITIGNORE = `# Diretórios gerados pelo houndsman — \`core/\` é regenerado por \`houndsman update\`

package/src/core/commands/status.ts

@@ -0,0 +1,63 @@
+/**
+ * Status da run (biblioteca) — leitura e heartbeat para a UI.
+ *
+ * `status ping` é o sinal de vida de uma skill em execução (revisão ou
+ * correção). O heartbeat é separado de `updatedAt`: triagem/sync atualizam o
+ * segundo, mas não fingem que existe uma execução em andamento.
+ */
+
+import { currentBranch } from "../pr-context";
+import { type RunStatus, touchRunStatus } from "../run-status";
+import type { RepoIdentity, ReviewRecord, StorageProvider } from "../storage/types";
+
+export type StatusResult = {
+	branch: string;
+	status: RunStatus | null;
+	startedAt?: string;
+	heartbeatAt?: string;
+	updatedAt: string;
+};
+
+function toResult(review: ReviewRecord): StatusResult {
+	return {
+		branch: review.branch,
+		status: review.status,
+		startedAt: review.startedAt,
+		heartbeatAt: review.heartbeatAt,
+		updatedAt: review.updatedAt,
+	};
+}
+
+/** Resolve a review da branch (explícita ou a atual do git). */
+function findReview(
+	storage: StorageProvider,
+	repo: RepoIdentity,
+	branch?: string,
+): ReviewRecord {
+	const target = branch ?? currentBranch();
+	const review = storage.findReview(repo.key, target);
+	if (!review) {
+		throw new Error(`Nenhuma revisão para '${target}'.`);
+	}
+	return review;
+}
+
+/** Lê o status atual da run. */
+export function readStatus(
+	storage: StorageProvider,
+	repo: RepoIdentity,
+	branch?: string,
+): StatusResult {
+	return toResult(findReview(storage, repo, branch));
+}
+
+/** Renova o heartbeat de uma execução ativa (`reviewing`/`fixing`). */
+export function pingStatus(
+	storage: StorageProvider,
+	repo: RepoIdentity,
+	branch?: string,
+	now?: string,
+): StatusResult {
+	const review = findReview(storage, repo, branch);
+	return toResult(touchRunStatus(storage, review.id, now));
+}

package/src/core/config.ts

@@ -27,6 +27,20 @@ export type HoundsmanConcurrency = {
 	jev?: number;
 };
 
+/** Backend de persistência (reviews, findings e artefatos). */
+export type HoundsmanStorage = {
+	/**
+	 * Provider de storage (default: `sqlite`). `file` mantém o formato antigo
+	 * em arquivos, mas sob o diretório global do houndsman.
+	 */
+	provider?: "sqlite" | "file";
+	/**
+	 * Caminho do banco (sqlite) ou raiz das runs (file). Default:
+	 * `<HOUNDSMAN_HOME>/houndsman.db` / `<HOUNDSMAN_HOME>/runs`.
+	 */
+	path?: string;
+};
+
 /**
  * Configuração completa do motor de revisão para um projeto.
  *
@@ -35,8 +49,8 @@ export type HoundsmanConcurrency = {
 export type HoundsmanConfig<TId extends string = string> = {
 	/** Nome legível do projeto (usado em prompts e docs). */
 	projectName: string;
-	/** Diretório dos artefatos (default: `ARTIFACT_DIR` da camada). */
-	artifactDir?: string;
+	/** Persistência das runs e artefatos (default: SQLite global). */
+	storage?: HoundsmanStorage;
 	/**
 	 * Ids dos watchdogs — **derivados** das chaves de `watchdogs` por
 	 * `defineHoundsmanConfig` (não informar manualmente).
@@ -72,11 +86,6 @@ export function defineHoundsmanConfig<TId extends string>(
 	return { ...input, watchdogIds: Object.keys(input.watchdogs) as TId[] };
 }
 
-/** Diretório dos artefatos — o valor do projeto ou o default da camada. */
-export function resolveArtifactDir(config: HoundsmanConfig): string {
-	return new ProjectConfig(config).artifactDir;
-}
-
 /**
  * Teto de arquivos por brief. Valor ausente/não-positivo cai no default —
  * mantém o contexto do subagente limitado em PRs grandes.

package/src/core/engine/houndsman-engine.ts

@@ -13,6 +13,9 @@ import { FileClassifier } from "../services/file-classifier";
 import { FixBatchBuilder } from "../services/fix-batch-builder";
 import { GitRepository } from "../services/git-repository";
 import { Verifier } from "../services/verifier";
+import { createStorage } from "../storage/factory";
+import { resolveRepoIdentity } from "../storage/repo-identity";
+import type { RepoIdentity, StorageProvider } from "../storage/types";
 import { ReviewSession } from "./review-session";
 
 /** Colaboradores injetáveis (testes/CLI). */
@@ -21,6 +24,8 @@ export type EngineDeps = {
 	classifier?: FileClassifier;
 	verifier?: Verifier;
 	fixBatch?: FixBatchBuilder;
+	storage?: StorageProvider;
+	repo?: RepoIdentity;
 };
 
 /** Composition root do motor. */
@@ -30,6 +35,8 @@ export class HoundsmanEngine {
 	readonly classifier: FileClassifier;
 	readonly verifier: Verifier;
 	readonly fixBatch: FixBatchBuilder;
+	readonly storage: StorageProvider;
+	readonly repo: RepoIdentity;
 
 	constructor(raw: HoundsmanConfig, deps: EngineDeps = {}) {
 		this.project = new ProjectConfig(raw);
@@ -37,6 +44,8 @@ export class HoundsmanEngine {
 		this.classifier = deps.classifier ?? new FileClassifier(raw);
 		this.verifier = deps.verifier ?? new Verifier();
 		this.fixBatch = deps.fixBatch ?? new FixBatchBuilder();
+		this.storage = deps.storage ?? createStorage(raw);
+		this.repo = deps.repo ?? resolveRepoIdentity(this.git);
 	}
 
 	/** Configuração crua (contrato do consumidor). */
@@ -46,6 +55,11 @@ export class HoundsmanEngine {
 
 	/** Abre uma sessão de revisão (prepare/finalize). */
 	session(options: ReviewOptions): ReviewSession {
-		return ReviewSession.from(this.config, options);
+		return ReviewSession.from(this.config, options, this.storage, this.repo);
+	}
+
+	/** Libera o provider (fecha o SQLite e faz checkpoint do WAL). */
+	close(): void {
+		this.storage.close();
 	}
 }

package/src/core/engine/review-scope.ts

@@ -34,12 +34,21 @@ export type RunClassification = ClassificationResult & {
 	carryover?: MergedFinding[];
 };
 
-/** Resultado da resolução de escopo. */
-export type ReviewScope = {
-	classification: RunClassification;
-	diff: DiffSource;
-	reviewedFrom?: string;
-};
+/** Resultado da resolução de escopo: revisar ou nada a fazer. */
+export type ReviewScope =
+	| {
+			/** O `HEAD` é o mesmo commit já revisado — não há o que re-revisar. */
+			kind: "noop";
+			headSha: string;
+			/** Commit já coberto pelo review anterior. */
+			reviewedFrom: string;
+	  }
+	| {
+			kind: "review";
+			classification: RunClassification;
+			diff: DiffSource;
+			reviewedFrom?: string;
+	  };
 
 /** Decide entre review completo e incremental. */
 export class ReviewScopeResolver {
@@ -52,20 +61,29 @@ export class ReviewScopeResolver {
 	}
 
 	/**
+	 * No-op quando o `HEAD` é exatamente o commit já revisado (sem
+	 * `--full`/`--clean`): re-revisar a PR inteira seria desperdício, e o
+	 * relatório anterior continua válido.
+	 *
 	 * Incremental só quando há um `reviewed.headSha` anterior, o `HEAD` atual o
 	 * sucede (sem rebase) e não veio `--full`/`--clean`.
 	 */
 	resolve(previous: FindingsStateFile | null, headSha: string): ReviewScope {
 		const prevSha = previous?.reviewed?.headSha;
+
+		if (!this.options.full && !this.options.clean && prevSha === headSha) {
+			return { kind: "noop", headSha, reviewedFrom: headSha };
+		}
+
 		if (
 			this.options.full ||
 			this.options.clean ||
 			!prevSha ||
-			prevSha === headSha ||
 			!isAncestor(prevSha, headSha)
 		) {
 			const diff = collectDiff(this.options.base, this.options.head);
 			return {
+				kind: "review",
 				diff,
 				classification: {
 					...this.classifier
@@ -90,6 +108,6 @@ export class ReviewScopeResolver {
 			reviewedFrom: prevSha,
 			carryover: buildCarryover(previous, changedPaths),
 		};
-		return { classification, diff, reviewedFrom: prevSha };
+		return { kind: "review", classification, diff, reviewedFrom: prevSha };
 	}
 }

package/src/core/engine/review-session.ts

@@ -1,5 +1,5 @@
 /**
- * Sessão de uma run (engine) — amarra opções, branch e layout.
+ * Sessão de uma run (engine) — amarra opções, branch, storage e staging.
  *
  * É o ponto de entrada do `prepare`/`finalize` para o CLI e para o engine.
  */
@@ -10,38 +10,66 @@ import {
 	finalize,
 	type PrepareResult,
 	prepare,
+	type ReviewContext,
 	type ReviewOptions,
 	resolveBranch,
+	reviewContext,
 } from "../orchestrator";
-import { RunLayout } from "../run-layout";
+import { sanitizeBranch } from "../report-builder";
+import type { RepoIdentity, StorageProvider } from "../storage/types";
 
 /** Uma revisão em andamento (prepare ou finalize). */
 export class ReviewSession {
 	readonly config: HoundsmanConfig;
 	readonly options: ReviewOptions;
 	readonly branch: string;
-	readonly layout: RunLayout;
+	readonly context: ReviewContext;
 
-	constructor(config: HoundsmanConfig, options: ReviewOptions, branch: string) {
+	constructor(
+		config: HoundsmanConfig,
+		options: ReviewOptions,
+		branch: string,
+		storage: StorageProvider,
+		repo: RepoIdentity,
+	) {
 		this.config = config;
 		this.options = options;
 		this.branch = branch;
-		this.layout = new RunLayout(options.dir, branch);
+		const review = options.finalize
+			? storage.findReview(repo.key, branch)
+			: storage.getOrCreateReview({
+					repo,
+					branch,
+					slug: sanitizeBranch(branch),
+					base: options.base,
+					head: options.head,
+				});
+		if (!review) {
+			throw new Error(
+				`Nenhuma revisão para '${branch}'. Rode \`houndsman\` (preparar) primeiro.`,
+			);
+		}
+		this.context = reviewContext(storage, review);
 	}
 
 	/** Resolve a branch (opção explícita ou a atual do git). */
-	static from(config: HoundsmanConfig, options: ReviewOptions): ReviewSession {
-		return new ReviewSession(config, options, resolveBranch(options));
+	static from(
+		config: HoundsmanConfig,
+		options: ReviewOptions,
+		storage: StorageProvider,
+		repo: RepoIdentity,
+	): ReviewSession {
+		return new ReviewSession(config, options, resolveBranch(options), storage, repo);
 	}
 
 	/** Passo 1 — preparar. */
 	prepare(): Promise<PrepareResult> {
-		return prepare(this.options, this.branch, this.config, this.layout);
+		return prepare(this.options, this.branch, this.config, this.context);
 	}
 
 	/** Passo 3 — finalizar. */
 	finalize(): FinalizeResult {
-		return finalize(this.options, this.branch, this.config, this.layout);
+		return finalize(this.options, this.branch, this.config, this.context);
 	}
 
 	/** Executa o passo escolhido em `--finalize`. */

package/src/core/findings-state.ts

@@ -1,18 +1,16 @@
 /**
  * Estado de triagem dos findings (biblioteca).
  *
- * Persistido em `.houndsman/.runs/<slug>/state.json` (local — coberto pelo
- * `.gitignore` gerado, que ignora `.runs/`). Cada finding tem um `id` curto e um
- * `fingerprint` de conteúdo: nas re-execuções do `--finalize` o estado é
- * preservado casando por fingerprint.
+ * O dump (`state.json`) é um detalhe do provider de arquivos; no SQLite o
+ * estado é reconstruído de `findings` + `finding_history`. Cada finding tem um
+ * `id` curto e um `fingerprint` de conteúdo: nas re-execuções do `--finalize`
+ * o estado é preservado casando por fingerprint.
  *
  * A `line` é cache — `syncState` a recalcula após edições (auto-fix) e marca
  * `stale` quando a âncora some.
  */
 
 import { randomUUID } from "node:crypto";
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
 import {
 	buildAnchor,
 	type FindingAnchor,
@@ -20,14 +18,7 @@ import {
 	locateAnchor,
 	reanchor,
 } from "./finding-anchor";
-import {
-	dedupeFindings,
-	type MergedFinding,
-	parseWatchdogReport,
-	sanitizeBranch,
-	type WatchdogReport,
-} from "./report-builder";
-import { RunLayout } from "./run-layout";
+import { type MergedFinding, sanitizeBranch } from "./report-builder";
 import { systemClock } from "./services/clock";
 import { type FileReader, ProjectFiles } from "./services/project-files";
 import { SEVERITY_ORDER, type Severity, severityRank } from "./types";
@@ -85,6 +76,10 @@ export type GitHubLink = {
 	pr: number;
 	/** Quando foi enviado (ISO). */
 	at: string;
+	/** Node ID da thread de revisão (GraphQL) — base para resolver a conversa. */
+	threadId?: string;
+	/** Quando a thread foi marcada como resolvida no GitHub (ISO). */
+	resolvedAt?: string;
 };
 
 /** Marco da revisão que originou o estado: commit revisado + quando. */
@@ -142,16 +137,6 @@ export const FINDINGS_STATE_VERSION = 2;
 // Caminhos
 // ---------------------------------------------------------------------------
 
-/** Diretório de artefatos da run (branch-slug). */
-export function runDir(artifactDir: string, branch: string): string {
-	return new RunLayout(artifactDir, branch).outDir;
-}
-
-/** Caminho do `state.json` da run. */
-export function stateFile(artifactDir: string, branch: string): string {
-	return new RunLayout(artifactDir, branch).stateFile;
-}
-
 /** Leitor padrão a partir do cwd (null se ausente/ilegível). */
 export function fileReader(cwd: string): FileReader {
 	return new ProjectFiles(cwd).reader();
@@ -264,6 +249,32 @@ export function filterFindings(
 		.sort(compareFindings);
 }
 
+/** Resultado da resolução de um id (completo ou prefixo único). */
+export type FindingIdResolution =
+	| { status: "found"; id: string }
+	| { status: "ambiguous"; matches: string[] }
+	| { status: "missing" };
+
+/**
+ * Resolve um id de finding: exato primeiro, depois prefixo único.
+ * Ambíguo devolve os candidatos para a mensagem de erro.
+ */
+export function resolveFindingId(
+	state: FindingsStateFile,
+	input: string,
+): FindingIdResolution {
+	const needle = input.trim();
+	if (needle.length === 0) return { status: "missing" };
+	if (state.findings[needle]) return { status: "found", id: needle };
+
+	const matches = Object.keys(state.findings).filter((id) =>
+		id.toLowerCase().startsWith(needle.toLowerCase()),
+	);
+	if (matches.length === 1) return { status: "found", id: matches[0] };
+	if (matches.length > 1) return { status: "ambiguous", matches };
+	return { status: "missing" };
+}
+
 // ---------------------------------------------------------------------------
 // Construção (finalize)
 // ---------------------------------------------------------------------------
@@ -276,6 +287,12 @@ export type BuildStateOptions = {
 	reviewed?: FindingsReviewed;
 	/** SHA usado para carimbar `foundAtSha` de findings novos/re-reportados. */
 	headSha?: string;
+	/**
+	 * Arquivos efetivamente revisados neste ciclo (união de `reviewedFiles`).
+	 * Quando presente, só findings ausentes desses arquivos viram `done` — o que
+	 * ficou fora do orçamento/skipped não pode ser dado como resolvido.
+	 */
+	reviewedPaths?: ReadonlySet<string>;
 	now?: string;
 };
 
@@ -296,14 +313,21 @@ export function buildStateFromFindings(
 
 	const result: Record<string, FindingState> = {};
 	// 1. Preserva o estado anterior (marca como ausente até provar o contrário).
+	const reviewedPaths = options.reviewedPaths;
 	for (const prev of Object.values(previous?.findings ?? {})) {
+		// Ausente do novo relatório ⇒ corrigido manualmente entre revisões (ou
+		// some junto com o trecho): vira `done`. `ignore` é decisão explícita de
+		// não corrigir — preserva o estado original. Arquivo fora da revisão
+		// (orçamento/skipped) também preserva: ausência não prova resolução.
+		const wasReviewed = !reviewedPaths || reviewedPaths.has(prev.file);
+		const resolvedByReview =
+			wasReviewed && prev.present && prev.decision !== "ignore";
+		const queuedAndGone =
+			wasReviewed && prev.decision === "execute" && prev.execState === "pending";
 		result[prev.id] = {
 			...prev,
 			present: false,
-			execState:
-				prev.execState === "pending" && prev.decision === "execute"
-					? "done"
-					: prev.execState,
+			execState: resolvedByReview || queuedAndGone ? "done" : prev.execState,
 			updatedAt: now,
 		};
 	}
@@ -377,47 +401,6 @@ export function buildStateFromFindings(
 	return state;
 }
 
-/**
- * Reconstrói o estado a partir dos artefatos da run (`classification.json` +
- * `findings/<id>.json`), sem exigir `--finalize`. Devolve null se não houver
- * findings gravados.
- */
-export function buildStateFromRunDir(
-	outDir: string,
-	branch: string,
-	readFile: FileReader,
-): FindingsStateFile | null {
-	const classificationPath = join(outDir, "classification.json");
-	if (!existsSync(classificationPath)) return null;
-
-	let activeIds: string[] = [];
-	try {
-		const classification = JSON.parse(readFileSync(classificationPath, "utf8")) as {
-			watchdogs?: Record<string, string[]>;
-		};
-		activeIds = Object.keys(classification.watchdogs ?? {});
-	} catch {
-		return null;
-	}
-
-	const reports: WatchdogReport[] = [];
-	for (const id of activeIds) {
-		const path = join(outDir, "findings", `${id}.json`);
-		if (!existsSync(path)) continue;
-		try {
-			const report = parseWatchdogReport(
-				JSON.parse(readFileSync(path, "utf8")),
-				path,
-			);
-			if (report) reports.push(report);
-		} catch {
-			// Ignora findings ilegíveis — reconstrução best-effort.
-		}
-	}
-	if (reports.length === 0) return null;
-
-	return buildStateFromFindings(dedupeFindings(reports), { branch, readFile });
-}
 // ---------------------------------------------------------------------------
 
 export type FindingUpdate = {
@@ -574,7 +557,7 @@ export class Finding {
 	}
 }
 
-/** Coleção de triagem de uma run — superfície OO sobre o `state.json`. */
+/** Coleção de triagem de uma run — superfície OO sobre o dump persistido. */
 export class FindingsState {
 	readonly file: FindingsStateFile;
 
@@ -671,11 +654,6 @@ export class FindingsRepository {
 		this.branch = branch;
 	}
 
-	/** Repository para a run de uma branch. */
-	static at(artifactDir: string, branch: string): FindingsRepository {
-		return new FindingsRepository(stateFile(artifactDir, branch), branch);
-	}
-
 	get filePath(): string {
 		return this.path;
 	}