@payconductor/houndsman 0.3.0 → 0.4.0

package/src/core/orchestrator.ts

@@ -5,17 +5,17 @@
  * Genérico: recebe o `HoundsmanConfig` por parâmetro (injeção explícita).
  * Entrypoints: `cli/index.ts` (`houndsman`). Aqui não há `process.argv`.
  *
- * Artefatos (em `opts.dir`, default `HoundsmanConfig.artifactDir/<branch-slug>/`):
- *   classification.json   watchdogs ativados por arquivo + status (A/M/D/R)
- *   candidates.json       candidatos da pré-análise Jev
- *   briefs/<id>.md        instruções prontas para cada sub-agente
- *   findings/<id>.json    saída dos sub-agentes (schema skill/OUTPUT-FORMAT.md)
- *   manifest.json         resumo do que foi ativado
- *   review.md             relatório final (gerado no finalize)
+ * Persistência:
+ *   storage               reviews/findings/artefatos (SQLite por default)
+ *   <home>/work/<review>  staging dos subagentes
+ *     briefs/<id>.md      instruções prontas para cada sub-agente
+ *     findings/<id>.json  saída dos sub-agentes (schema skill/OUTPUT-FORMAT.md)
+ *     context*.json/md    contexto da PR (Passo 0)
+ *
+ * Artefatos persistidos: classification, candidates, manifest, review.md,
+ * review.<watchdog>.md, context e context-summary.
  */
 
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
 import {
 	type HoundsmanConfig,
 	resolveJevConcurrency,
@@ -28,7 +28,7 @@ import { Watchdog } from "./domain/watchdog";
 import { mergeCarryover } from "./engine/carryover";
 import { ReviewScopeResolver, type RunClassification } from "./engine/review-scope";
 import type { BudgetSelection, ClassificationResult } from "./file-classifier";
-import { buildStateFromFindings, FindingsStateStore, fileReader } from "./findings-state";
+import { buildStateFromFindings, fileReader } from "./findings-state";
 import { resolveSha } from "./git-revision";
 import {
 	type JevCandidate,
@@ -36,9 +36,11 @@ import {
 	JevCandidatesStore,
 	JevClient,
 	JevDetector,
+	parseCandidates,
+	serializeCandidates,
 } from "./jev";
-import { ARTIFACT_DIR, OUTPUT_FORMAT_PATH, relFromRoot } from "./paths";
-import { currentBranch, readContextSummary } from "./pr-context";
+import { displayPath, OUTPUT_FORMAT_PATH, REVIEW_FILE } from "./paths";
+import { currentBranch } from "./pr-context";
 import { ProjectConfig } from "./project-config";
 import { BriefRenderer } from "./renderers/brief-renderer";
 import { ManifestWriter } from "./renderers/manifest-writer";
@@ -47,13 +49,14 @@ import {
 	type ContextSummary,
 	type DomainReport,
 	dedupeFindings,
-	parseWatchdogReport,
+	parseContextSummary,
 	sanitizeBranch,
 	type WatchdogReport,
 } from "./report-builder";
-import { RunLayout } from "./run-layout";
 import { writeRunStatus } from "./run-status";
 import { systemClock } from "./services/clock";
+import type { ReviewRecord, StorageProvider } from "./storage/types";
+import { ReviewWorkArea } from "./storage/work-area";
 import type { WatchdogMeta } from "./types";
 import { findWatchdog } from "./watchdog-registry";
 
@@ -61,7 +64,6 @@ export type ReviewOptions = {
 	base: string;
 	head: string;
 	branch?: string;
-	dir: string;
 	finalize: boolean;
 	failOnBlocking: boolean;
 	clean: boolean;
@@ -71,11 +73,10 @@ export type ReviewOptions = {
 };
 
 /** Valores default das opções (o CLI sobrepõe com as flags). */
-export function defaultOptions(artifactDir: string = ARTIFACT_DIR): ReviewOptions {
+export function defaultOptions(): ReviewOptions {
 	return {
 		base: "main",
 		head: "HEAD",
-		dir: artifactDir,
 		finalize: false,
 		failOnBlocking: false,
 		clean: false,
@@ -84,20 +85,19 @@ export function defaultOptions(artifactDir: string = ARTIFACT_DIR): ReviewOption
 	};
 }
 
-/** Layout de uma run (paths de briefs/findings/artefatos). */
-type Paths = RunLayout;
-
-function paths(opts: ReviewOptions, branch: string): Paths {
-	return new RunLayout(opts.dir, branch);
-}
+/** Contexto de uma run: storage + review + staging. */
+export type ReviewContext = {
+	storage: StorageProvider;
+	review: ReviewRecord;
+	work: ReviewWorkArea;
+};
 
-function prepareDirs(dirs: Paths, clean: boolean): void {
-	mkdirSync(dirs.briefsDir, { recursive: true });
-	mkdirSync(dirs.findingsDir, { recursive: true });
-	if (clean) {
-		rmSync(dirs.findingsDir, { recursive: true, force: true });
-		mkdirSync(dirs.findingsDir, { recursive: true });
-	}
+/** Cria o contexto de uma review existente. */
+export function reviewContext(
+	storage: StorageProvider,
+	review: ReviewRecord,
+): ReviewContext {
+	return { storage, review, work: new ReviewWorkArea(review) };
 }
 
 // ---------------------------------------------------------------------------
@@ -120,40 +120,6 @@ function incrementalNote(classification: RunClassification): string {
 	);
 }
 
-// ---------------------------------------------------------------------------
-// Findings
-// ---------------------------------------------------------------------------
-
-function readFindings(
-	findingsDir: string,
-	activeIds: string[],
-): { reports: WatchdogReport[]; pending: string[]; warnings: string[] } {
-	const reports: WatchdogReport[] = [];
-	const pending: string[] = [];
-	const warnings: string[] = [];
-	for (const id of activeIds) {
-		const path = join(findingsDir, `${id}.json`);
-		if (!existsSync(path)) {
-			pending.push(id);
-			continue;
-		}
-		try {
-			const raw = JSON.parse(readFileSync(path, "utf8"));
-			const report = parseWatchdogReport(raw, path, (message) =>
-				warnings.push(message),
-			);
-			if (report) reports.push(report);
-			else pending.push(id);
-		} catch (err) {
-			warnings.push(
-				`[houndsman] ${relFromRoot(path)} inválido: ${err instanceof Error ? err.message : err}`,
-			);
-			pending.push(id);
-		}
-	}
-	return { reports, pending, warnings };
-}
-
 // ---------------------------------------------------------------------------
 // Orçamento (triage de PRs grandes)
 // ---------------------------------------------------------------------------
@@ -169,7 +135,7 @@ function budgetFor(
 
 /** Grava o manifesto da run (delegado ao `ManifestWriter`). */
 function writeManifest(
-	layout: RunLayout,
+	ctx: ReviewContext,
 	config: HoundsmanConfig,
 	opts: ReviewOptions,
 	classification: RunClassification,
@@ -177,12 +143,13 @@ function writeManifest(
 	pending: string[],
 	jev: JevCandidatesFile,
 ): void {
-	new ManifestWriter(layout, new ProjectConfig(config), opts).write(
-		classification,
-		activeIds,
-		pending,
-		jev,
-	);
+	new ManifestWriter(
+		ctx.storage,
+		ctx.review,
+		ctx.work,
+		new ProjectConfig(config),
+		opts,
+	).write(classification, activeIds, pending, jev);
 }
 
 // ---------------------------------------------------------------------------
@@ -192,12 +159,13 @@ function writeManifest(
 function writeBriefs(
 	activeIds: string[],
 	classification: ClassificationResult,
-	dirs: Paths,
+	ctx: ReviewContext,
 	branch: string,
 	context: ContextSummary | null,
 	candidates: JevCandidate[],
 	config: HoundsmanConfig,
 ): void {
+	const work = ctx.work;
 	const docs = discoverDocs(Object.keys(classification.files), config);
 	const maxFilesPerBrief = resolveMaxFilesPerBrief(config);
 	const renderer = new BriefRenderer();
@@ -213,13 +181,20 @@ function writeBriefs(
 			overflow,
 			deleted: classification.deleted,
 			branch,
-			outputPath: relFromRoot(dirs.findingFile(id)),
+			outputPath: work.findingFile(id),
 			outputFormatPath: OUTPUT_FORMAT_PATH,
 			docs,
 			context,
 			candidates: candidates.filter((c) => c.watchdogId === id),
 		});
-		writeFileSync(dirs.briefFile(id), `${brief}\n`);
+		const content = `${brief}\n`;
+		work.writeBrief(id, content);
+		// Auditoria: o brief também fica no storage (o staging é limpo no finalize).
+		ctx.storage.writeArtifact(ctx.review.id, {
+			name: `briefs/${id}.md`,
+			kind: "brief",
+			content,
+		});
 	}
 }
 
@@ -234,13 +209,16 @@ function writeBriefs(
 async function resolveCandidates(
 	opts: ReviewOptions,
 	classification: ClassificationResult,
-	dirs: Paths,
+	ctx: ReviewContext,
 	config: HoundsmanConfig,
 	diff: DiffSource,
 ): Promise<JevCandidatesFile> {
-	const store = new JevCandidatesStore(dirs.candidatesFile, config.watchdogIds);
 	const save = (data: JevCandidatesFile): JevCandidatesFile => {
-		store.write(data);
+		ctx.storage.writeArtifact(ctx.review.id, {
+			name: "candidates.json",
+			kind: "candidates",
+			content: serializeCandidates(data),
+		});
 		return data;
 	};
 
@@ -295,7 +273,7 @@ function discoveryMessages(
 ): string[] {
 	const messages = [
 		`Discovery: ${activeIds.length} watchdog(s) ativado(s), ${Object.keys(classification.files).length} arquivo(s), ${classification.deleted.length} deletado(s).`,
-		`Briefs: ${relFromRoot(briefsDir)}/`,
+		`Briefs: ${displayPath(briefsDir)}/`,
 	];
 	for (const file of classification.deleted) {
 		messages.push(`Deletado (breaking change): ${file}`);
@@ -327,31 +305,37 @@ export async function prepare(
 	opts: ReviewOptions,
 	branch: string,
 	config: HoundsmanConfig,
-	dirs: Paths = paths(opts, branch),
+	ctx: ReviewContext,
 ): Promise<PrepareResult> {
 	const messages: string[] = [];
-	prepareDirs(dirs, opts.clean);
+	ctx.work.ensure();
+	if (opts.clean) ctx.work.cleanFindings();
+	ctx.storage.updateReview(ctx.review.id, { base: opts.base, head: opts.head });
 
 	// Marca o run como "revisando" (reinicia o ciclo) — a UI mostra o status.
-	writeRunStatus(dirs.outDir, { branch, status: "reviewing", resetStartedAt: true });
+	writeRunStatus(ctx.storage, ctx.review.id, {
+		status: "reviewing",
+		resetStartedAt: true,
+	});
 
 	// Marca o commit revisado e decide entre review completo e incremental.
 	const headSha = resolveSha(opts.head);
-	const previous = FindingsStateStore.at(opts.dir, branch).read();
+	const previous = ctx.storage.readFindings(ctx.review.id);
 	const { classification, diff } = new ReviewScopeResolver(opts, config).resolve(
 		previous,
 		headSha,
 	);
-	writeFileSync(
-		dirs.classificationFile,
-		`${JSON.stringify(classification, null, 2)}\n`,
-	);
+	ctx.storage.writeArtifact(ctx.review.id, {
+		name: "classification.json",
+		kind: "classification",
+		content: `${JSON.stringify(classification, null, 2)}\n`,
+	});
 
-	const jev = await resolveCandidates(opts, classification, dirs, config, diff);
+	const jev = await resolveCandidates(opts, classification, ctx, config, diff);
 
 	const activeIds = Object.keys(classification.watchdogs);
 	if (Object.keys(classification.files).length === 0) {
-		writeRunStatus(dirs.outDir, { branch, status: "review_done" });
+		writeRunStatus(ctx.storage, ctx.review.id, { status: "review_done" });
 		messages.push(
 			classification.mode === "incremental"
 				? `Nenhuma alteração desde a última revisão (${shortSha(classification.reviewedFrom ?? "")}).`
@@ -360,7 +344,7 @@ export async function prepare(
 		return { messages };
 	}
 	if (activeIds.length === 0) {
-		writeRunStatus(dirs.outDir, { branch, status: "review_done" });
+		writeRunStatus(ctx.storage, ctx.review.id, { status: "review_done" });
 		messages.push(
 			"Nenhum arquivo revisável (tudo excluído, deletado ou irrelevante).",
 		);
@@ -372,13 +356,14 @@ export async function prepare(
 		);
 	}
 
-	const context = readContextSummary(dirs.contextPaths.summary);
+	const context = ctx.work.readContextSummary() ?? readPersistedContextSummary(ctx);
+	persistContext(ctx);
 
-	writeBriefs(activeIds, classification, dirs, branch, context, jev.candidates, config);
-	writeManifest(dirs, config, opts, classification, activeIds, activeIds, jev);
+	writeBriefs(activeIds, classification, ctx, branch, context, jev.candidates, config);
+	writeManifest(ctx, config, opts, classification, activeIds, activeIds, jev);
 
 	messages.push(
-		...discoveryMessages(activeIds, classification, dirs.briefsDir),
+		...discoveryMessages(activeIds, classification, ctx.work.briefsDir),
 		...budgetMessage(classification, config),
 		...jevSummary(jev),
 	);
@@ -392,28 +377,78 @@ export async function prepare(
 	}
 
 	messages.push(
-		`\nPróximo passo: despachar os sub-agentes (um por brief em ${relFromRoot(dirs.briefsDir)}/).`,
+		`\nPróximo passo: despachar os sub-agentes (um por brief em ${displayPath(ctx.work.briefsDir)}/).`,
 		"Quando os findings estiverem gravados: bun run houndsman --finalize",
 	);
 
 	return { messages };
 }
+/** Persiste o contexto da PR (bruto + resumo) como artefatos, quando existirem. */
+function persistContext(ctx: ReviewContext): void {
+	const raw = ctx.work.readContextRaw();
+	if (raw !== null) {
+		ctx.storage.writeArtifact(ctx.review.id, {
+			name: "context.json",
+			kind: "context",
+			content: raw,
+		});
+	}
+	const summary = ctx.work.readContextSummaryRaw();
+	if (summary !== null) {
+		ctx.storage.writeArtifact(ctx.review.id, {
+			name: "context-summary.json",
+			kind: "context-summary",
+			content: summary,
+		});
+	}
+	const brief = ctx.work.readContextBriefRaw();
+	if (brief !== null) {
+		ctx.storage.writeArtifact(ctx.review.id, {
+			name: "context-brief.md",
+			kind: "context-brief",
+			content: brief,
+		});
+	}
+}
 
 // ---------------------------------------------------------------------------
 // Passo 2 — finalizar
 // ---------------------------------------------------------------------------
 
-/** Lê o classification.json gravado pelo passo de preparação (lança se ausente). */
-function readClassification(classificationPath: string): RunClassification {
-	if (!existsSync(classificationPath)) {
+/** Lê o `classification.json` persistido pelo prepare (lança se ausente). */
+function readClassification(ctx: ReviewContext): RunClassification {
+	const artifact = ctx.storage.readArtifact(ctx.review.id, "classification.json");
+	if (!artifact) {
 		throw new Error(
-			`Não encontrei ${relFromRoot(classificationPath)}. Rode \`bun run houndsman\` (preparar) primeiro.`,
+			`Não encontrei a classificação da review. Rode \`bun run houndsman\` (preparar) primeiro.`,
+		);
+	}
+	return JSON.parse(artifact.content) as RunClassification;
+}
+
+/** Lê os candidatos Jev persistidos (unavailable se ausente/inválido). */
+function readCandidates(ctx: ReviewContext, config: HoundsmanConfig): JevCandidatesFile {
+	const artifact = ctx.storage.readArtifact(ctx.review.id, "candidates.json");
+	if (!artifact) return JevCandidatesStore.unavailable("candidates.json ausente");
+	try {
+		return (
+			parseCandidates(JSON.parse(artifact.content), config.watchdogIds) ??
+			JevCandidatesStore.unavailable("candidates.json inválido")
 		);
+	} catch {
+		return JevCandidatesStore.unavailable("candidates.json inválido");
+	}
+}
+
+/** Resumo do contexto persistido (usado quando o staging já foi limpo). */
+function readPersistedContextSummary(ctx: ReviewContext): ContextSummary | null {
+	const artifact = ctx.storage.readArtifact(ctx.review.id, "context-summary.json");
+	if (!artifact) return null;
+	try {
+		return parseContextSummary(JSON.parse(artifact.content));
+	} catch {
+		return null;
 	}
-	const parsed = JSON.parse(
-		readFileSync(classificationPath, "utf8"),
-	) as RunClassification;
-	return parsed;
 }
 
 /**
@@ -421,7 +456,7 @@ function readClassification(classificationPath: string): RunClassification {
  * Mantém o `review.md` consolidado navegável em PRs grandes (centenas de achados).
  */
 function writeDomainReports(
-	layout: RunLayout,
+	ctx: ReviewContext,
 	branch: string,
 	reports: WatchdogReport[],
 	classification: ClassificationResult,
@@ -435,16 +470,17 @@ function writeDomainReports(
 		if (findings.length === 0) continue;
 		const file = `review.${sanitizeBranch(report.watchdogId)}.md`;
 		const expected = classification.watchdogs[report.watchdogId] ?? [];
-		writeFileSync(
-			layout.file(file),
-			`${renderer.renderDomain(
+		ctx.storage.writeArtifact(ctx.review.id, {
+			name: file,
+			kind: "domain-review",
+			content: `${renderer.renderDomain(
 				branch,
 				report,
 				findings,
 				expected.length,
 				context,
 			)}\n`,
-		);
+		});
 		domains.push({
 			id: report.watchdogId,
 			name: nameOf(report.watchdogId),
@@ -472,23 +508,21 @@ export function finalize(
 	opts: ReviewOptions,
 	branch: string,
 	config: HoundsmanConfig,
-	dirs: Paths = paths(opts, branch),
+	ctx: ReviewContext,
 ): FinalizeResult {
-	const classification = readClassification(dirs.classificationFile);
+	const classification = readClassification(ctx);
 	const activeIds = Object.keys(classification.watchdogs);
 
 	const messages: string[] = [];
-	const { reports, pending, warnings } = readFindings(dirs.findingsDir, activeIds);
+	const { reports, pending, warnings } = ctx.work.readFindings(activeIds);
 	messages.push(...warnings);
-	const jev =
-		new JevCandidatesStore(dirs.candidatesFile, config.watchdogIds).read() ??
-		JevCandidatesStore.unavailable("candidates.json ausente");
-	writeManifest(dirs, config, opts, classification, activeIds, pending, jev);
+	const jev = readCandidates(ctx, config);
+	writeManifest(ctx, config, opts, classification, activeIds, pending, jev);
 
 	if (pending.length > 0) {
 		throw new Error(
 			`Faltam ${pending.length}/${activeIds.length} findings: ${pending.join(", ")}.\n` +
-				`Cada watchdog deve gravar ${relFromRoot(dirs.findingsDir)}/<id>.json (schema ${OUTPUT_FORMAT_PATH}).`,
+				`Cada watchdog deve gravar ${displayPath(ctx.work.findingsDir)}/<id>.json (schema ${OUTPUT_FORMAT_PATH}).`,
 		);
 	}
 
@@ -508,27 +542,29 @@ export function finalize(
 	// anexa o `id` de cada finding aos itens do relatório. A linha é cache —
 	// recalculada por `houndsman findings sync` após edições. O commit revisado
 	// (`reviewed.headSha`) habilita o review incremental e o diff focado do verify.
-	const store = FindingsStateStore.at(opts.dir, branch);
 	const state = buildStateFromFindings(merged, {
 		branch,
 		readFile: fileReader(process.cwd()),
-		previous: store.read(),
+		previous: ctx.storage.readFindings(ctx.review.id),
 		now,
 		headSha: classification.headSha,
 		reviewed: classification.headSha
 			? { headSha: classification.headSha, at: now }
 			: undefined,
 	});
-	store.write(state);
-	messages.push(
-		`Triagem: ${relFromRoot(store.filePath)} — ${Object.keys(state.findings).length} finding(s).`,
-	);
-	writeRunStatus(dirs.outDir, { branch, status: "review_done" });
+	ctx.storage.writeFindings(ctx.review.id, state);
+	ctx.storage.updateReview(ctx.review.id, {
+		base: opts.base,
+		head: opts.head,
+		headSha: classification.headSha,
+	});
+	writeRunStatus(ctx.storage, ctx.review.id, { status: "review_done" });
 
-	const context = readContextSummary(dirs.contextPaths.summary);
+	persistContext(ctx);
+	const context = ctx.work.readContextSummary() ?? readPersistedContextSummary(ctx);
 	const nameOf = (id: string): string => findWatchdog(config, id)?.name ?? id;
 	const domains = writeDomainReports(
-		dirs,
+		ctx,
 		branch,
 		reports,
 		classification,
@@ -544,16 +580,27 @@ export function finalize(
 		jev.available ? jev.candidates : undefined,
 		domains,
 	);
-	const reportPath = dirs.reviewFile;
-	writeFileSync(reportPath, `${incrementalNote(classification)}${markdown}\n`);
+	ctx.storage.writeArtifact(ctx.review.id, {
+		name: REVIEW_FILE,
+		kind: "review",
+		content: `${incrementalNote(classification)}${markdown}\n`,
+	});
+
+	const location = ctx.storage.location(ctx.review.id);
+	messages.push(
+		`Triagem: ${location} — ${Object.keys(state.findings).length} finding(s).`,
+	);
 
 	const blockers = merged.filter((f) => f.severity === "blocking").length;
 	const attention = merged.filter((f) => f.severity === "attention").length;
 	messages.push(
-		`Relatório: ${relFromRoot(reportPath)} — ${blockers} bloqueante(s), ${attention} atenção.`,
+		`Relatório: ${location} — ${blockers} bloqueante(s), ${attention} atenção.`,
 	);
 
-	return { reportPath, blockers, attention, messages };
+	// O staging já cumpriu o papel (briefs/findings/contexto estão no storage).
+	ctx.work.clean();
+
+	return { reportPath: location, blockers, attention, messages };
 }
 
 /** Resolve a branch (opção explícita ou a atual do git). */

package/src/core/paths.ts

@@ -2,11 +2,13 @@
  * Caminhos do houndsman (biblioteca): raiz relativa para logs + layout fixo da
  * camada de projeto (`.houndsman/`).
  *
- * A camada gerada tem local fixo, então nada aqui é configurável pelo projeto:
- * o CLI deriva os artefatos e o schema de output destas constantes.
+ * A camada gerada tem local fixo, então nada aqui é configurável pelo projeto.
+ * Dados de execução (reviews/findings/artefatos) vivem no storage global; aqui
+ * ficam só os paths da camada e os nomes dos artefatos de staging.
  */
 
-import { relative } from "node:path";
+import { homedir } from "node:os";
+import { relative, sep } from "node:path";
 import { OUTPUT_FORMAT_FILE } from "./assets";
 
 /** Caminho relativo ao cwd, sempre com `/` (portável/legível em logs). */
@@ -14,6 +16,16 @@ export function relFromRoot(absPath: string): string {
 	return relative(process.cwd(), absPath).replace(/\\/g, "/");
 }
 
+/** Caminho legível para mensagens: `~/...` quando sob o home, senão absoluto. */
+export function displayPath(absPath: string): string {
+	const home = homedir();
+	if (absPath === home) return "~";
+	if (absPath.startsWith(`${home}${sep}`)) {
+		return `~${absPath.slice(home.length).replace(/\\/g, "/")}`;
+	}
+	return absPath.replace(/\\/g, "/");
+}
+
 /** Diretório da camada de projeto (regras + artefatos). */
 export const PROJECT_DIR = ".houndsman";
 
@@ -23,26 +35,20 @@ export const CORE_DIR = `${PROJECT_DIR}/core`;
 /** Skill canônico (markdown) dentro da camada gerada. */
 export const CORE_SKILL_DIR = `${CORE_DIR}/skill`;
 
-/** Artefatos da revisão (briefs, findings, review.md) — default de `artifactDir`. */
-export const ARTIFACT_DIR = `${PROJECT_DIR}/.runs`;
-
 /** Schema de output dos watchdogs, citado nos briefs. */
 export const OUTPUT_FORMAT_PATH = `${CORE_SKILL_DIR}/${OUTPUT_FORMAT_FILE}`;
 
-/** Estado de triagem dos findings, dentro da pasta da run (`<slug>/state.json`). */
-export const STATE_FILE = "state.json";
-
-/** Status da run (revisão/correção), dentro da pasta da run (`<slug>/run.json`). */
-export const RUN_STATUS_FILE = "run.json";
-
-/** Relatório da verificação de findings, dentro da pasta da run (`<slug>/verify.md`). */
-export const VERIFY_FILE = "verify.md";
-
-/** Contexto bruto da PR (`gh pr view`), dentro da pasta da run. */
+/** Contexto bruto da PR (`gh pr view`), no staging da review. */
 export const CONTEXT_FILE = "context.json";
 
-/** Resumo do contexto gravado pelo subagente, dentro da pasta da run. */
+/** Resumo do contexto gravado pelo subagente, no staging da review. */
 export const CONTEXT_SUMMARY_FILE = "context-summary.json";
 
 /** Brief do subagente que resume o contexto da PR. */
 export const CONTEXT_BRIEF_FILE = "context-brief.md";
+
+/** Relatório da verificação de findings (artefato `verify.md`). */
+export const VERIFY_FILE = "verify.md";
+
+/** Relatório consolidado da review (artefato `review.md`). */
+export const REVIEW_FILE = "review.md";

package/src/core/pr-context.ts

@@ -5,7 +5,7 @@
  * OPCIONAL: sem binário, sem login ou sem PR para a branch, grava
  * `context.json` com `{ available: false, reason }` e sai com código 0.
  *
- * Artefatos (em --dir, default .houndsman/.runs/<branch-slug>/):
+ * Artefatos no staging da review (`<HOUNDSMAN_HOME>/work/<reviewId>/`):
  *   context.json      payload bruto do `gh pr view` (ou marcador de indisponível)
  *   context-brief.md  instruções para o subagente resumir o contexto
  *
@@ -22,13 +22,19 @@ import {
 } from "./paths";
 import type { ContextSummary } from "./report-builder";
 import { parseContextSummary } from "./report-builder";
-import { type ContextPaths, RunLayout } from "./run-layout";
 import { systemClock } from "./services/clock";
 import { defaultGhRunner, GhClient, type GhRunner } from "./services/gh-client";
 import { GitRepository } from "./services/git-repository";
 
 export { CONTEXT_BRIEF_FILE, CONTEXT_FILE, CONTEXT_SUMMARY_FILE };
-export type { ContextPaths };
+
+/** Caminhos dos artefatos de contexto da PR (staging da review). */
+export type ContextPaths = {
+	dir: string;
+	context: string;
+	summary: string;
+	brief: string;
+};
 
 const GH_JSON_FIELDS =
 	"number,title,body,url,baseRefName,headRefName,author,commits,files";
@@ -60,8 +66,16 @@ export type PrContextRaw = {
 };
 
 /** Caminhos dos artefatos de contexto para uma branch. */
-export function contextPaths(dir: string, branch: string): ContextPaths {
-	return new RunLayout(dir, branch).contextPaths;
+export function contextFileNames(): {
+	context: string;
+	summary: string;
+	brief: string;
+} {
+	return {
+		context: CONTEXT_FILE,
+		summary: CONTEXT_SUMMARY_FILE,
+		brief: CONTEXT_BRIEF_FILE,
+	};
 }
 
 /** Detecta a branch atual; lança se não houver (o CLI decide o exit). */