@payconductor/houndsman 0.12.0 → 0.14.0

package/src/server/client/FindingCard.tsx

@@ -157,7 +157,7 @@ export function FindingCard({
 					</span>
 				)}
 				{!finding.present && (
-					<span class="tag" title="Não aparece no último relatório consolidado">
+					<span class="tag" title="Não aparece na última revisão">
 						ausente
 					</span>
 				)}
@@ -206,6 +206,26 @@ export function FindingCard({
 				<div class="card-body">
 					<div class="meta-row">{finding.rule}</div>
 
+					{finding.scenario && (
+						<div class="action-block">
+							<Sparkles size={16} class="action-icon" />
+							<div class="action-text">
+								<span class="action-label">Cenário:</span>
+								<MarkdownText text={finding.scenario} />
+							</div>
+						</div>
+					)}
+
+					{finding.impact && (
+						<div class="action-block">
+							<Sparkles size={16} class="action-icon" />
+							<div class="action-text">
+								<span class="action-label">Impacto:</span>
+								<MarkdownText text={finding.impact} />
+							</div>
+						</div>
+					)}
+
 					<div class="action-block">
 						<Sparkles size={16} class="action-icon" />
 						<div class="action-text">

package/src/server/client/RunsSection.tsx

@@ -30,6 +30,11 @@ function RunItem({
 			<span class="run-top">
 				<BranchIcon size={14} class="run-icon" />
 				<span class="run-branch">{run.branch}</span>
+				{run.variant ? (
+					<span class="run-variant" title="Variante A/B">
+						{run.variant}
+					</span>
+				) : null}
 			</span>
 			<span class="run-meta">
 				<span class="run-when">

package/src/server/client/utils/constants.ts

@@ -83,13 +83,13 @@ export function describeRunStatus(
 
 /** Ordem canônica dos tipos de artefato na lista da UI. */
 const KIND_ORDER: ArtifactKind[] = [
-	"review",
+	"compare",
 	"resume",
 	"technical",
-	"domain-review",
 	"verify",
 	"brief",
 	"manifest",
+	"prepare",
 	"classification",
 	"candidates",
 	"ast",
@@ -100,6 +100,8 @@ const KIND_ORDER: ArtifactKind[] = [
 	"context",
 	"context-brief",
 	"context-summary",
+	"business",
+	"business-brief",
 	"finding-report",
 	"other",
 ];
@@ -107,12 +109,12 @@ const KIND_ORDER: ArtifactKind[] = [
 /** Grupo visual de cada tipo (relatórios, briefs, núcleo, contexto…). */
 const GROUP_BY_KIND: Record<ArtifactKind, { key: string; label: string; order: number }> =
 	{
-		review: { key: "report", label: "Relatórios", order: 0 },
+		compare: { key: "report", label: "Relatórios", order: 0 },
 		resume: { key: "report", label: "Relatórios", order: 0 },
 		technical: { key: "core", label: "Núcleo da revisão", order: 3 },
-		"domain-review": { key: "report", label: "Relatórios", order: 0 },
 		verify: { key: "verify", label: "Verificação", order: 1 },
 		brief: { key: "brief", label: "Briefs (auditoria)", order: 2 },
+		prepare: { key: "core", label: "Núcleo da revisão", order: 3 },
 		manifest: { key: "core", label: "Núcleo da revisão", order: 3 },
 		classification: { key: "core", label: "Núcleo da revisão", order: 3 },
 		candidates: { key: "core", label: "Núcleo da revisão", order: 3 },
@@ -124,17 +126,19 @@ const GROUP_BY_KIND: Record<ArtifactKind, { key: string; label: string; order: n
 		context: { key: "context", label: "Contexto da PR", order: 5 },
 		"context-brief": { key: "context", label: "Contexto da PR", order: 5 },
 		"context-summary": { key: "context", label: "Contexto da PR", order: 5 },
+		business: { key: "business", label: "Intenção da PR", order: 5 },
+		"business-brief": { key: "business", label: "Intenção da PR", order: 5 },
 		"finding-report": { key: "other", label: "Outros", order: 6 },
 		other: { key: "other", label: "Outros", order: 6 },
 	};
 
 /** Rótulo curto do tipo (badge do item). */
 export const ARTIFACT_KIND_LABELS: Record<ArtifactKind, string> = {
-	review: "relatório",
+	compare: "comparação",
 	resume: "resumo",
 	technical: "pontos técnicos",
-	"domain-review": "domínio",
 	verify: "verify",
+	prepare: "prepare",
 	brief: "brief",
 	manifest: "manifesto",
 	classification: "classificação",
@@ -147,6 +151,8 @@ export const ARTIFACT_KIND_LABELS: Record<ArtifactKind, string> = {
 	context: "contexto",
 	"context-brief": "brief ctx",
 	"context-summary": "resumo ctx",
+	business: "intenção",
+	"business-brief": "brief intenção",
 	"finding-report": "findings",
 	other: "outro",
 };
@@ -161,16 +167,16 @@ export function displayArtifactName(meta: ArtifactMeta): string {
 /** Descrição curta do artefato (cabeçalho do painel). */
 export function describeArtifact(meta: ArtifactMeta): string {
 	switch (meta.kind) {
-		case "review":
-			return "Relatório consolidado da revisão — o entregável.";
+		case "compare":
+			return "Comparação A/B entre duas runs: achados novos/sumidos, cobertura, tempo e tokens.";
 		case "resume":
-			return "Resumo final da revisão: visão de negócio e estrutura técnica (leitura humana).";
+			return "Resumo final: negócio, pontos técnicos, cobertura por domínio e conclusão.";
 		case "technical":
 			return "Destaques estruturais da mudança (módulos, contratos, dependências) usados no resumo final.";
-		case "domain-review":
-			return "Relatório isolado do domínio: achados daquele watchdog.";
 		case "verify":
 			return "Resultado do `findings verify` (resolvidos, persistentes e incertos).";
+		case "prepare":
+			return "Duração por etapa do prepare e uso de IA (diagnóstico de performance).";
 		case "brief":
 			return "Instruções enviadas ao subagente (auditoria do prompt).";
 		case "manifest":
@@ -189,6 +195,10 @@ export function describeArtifact(meta: ArtifactMeta): string {
 			return "Brief do subagente que resume o contexto da PR.";
 		case "context-summary":
 			return "Resumo da PR (objetivo, motivação e alterações) gerado no Passo 0.";
+		case "business":
+			return "Modelo de intenção da PR: o que ela deve entregar (fluxos, invariantes, contratos e estados).";
+		case "business-brief":
+			return "Brief do passo de intenção (subagente na skill / pré-passe maki).";
 		default:
 			return meta.name;
 	}

package/src/server/client/utils/markdown.ts

@@ -240,7 +240,7 @@ export function sectionBlocks(text: string, title: string): MarkdownBlock[] {
 const FILE_EXTENSION =
 	/\.(?:[cm]?[jt]sx?|json|md|ya?ml|toml|css|scss|html?|py|go|rs|java|kt|cs|php|rb|sh|sql|txt|lock)$/i;
 
-/** Caminho/arquivo dentro de um texto corrido (`src/foo.ts`, `review.md`). */
+/** Caminho/arquivo dentro de um texto corrido (`src/foo.ts`, `manifest.json`). */
 const PATH_TOKEN =
 	/(?:[\w.-]+[\\/])*[\w-]+\.(?:[cm]?[jt]sx?|json|md|ya?ml|toml|css|scss|html?|py|go|rs|java|kt|cs|php|rb|sh|sql|txt|lock)\b/g;
 

package/src/server/client/utils/types.ts

@@ -32,6 +32,14 @@ export type Finding = {
 	message: string;
 	action: string;
 	evidence?: string;
+	/** Gatilho concreto do gap (fora de regra). */
+	scenario?: string;
+	/** Consequência observável do gap. */
+	impact?: string;
+	/** Confiança do revisor (0–1). */
+	confidence?: number;
+	/** Origem do achado: regra, lógica ou domínio. */
+	basis?: "rule" | "logic" | "domain";
 	count: number;
 	present: boolean;
 	decision: Decision;
@@ -59,17 +67,19 @@ export type ArtifactKind =
 	| "context"
 	| "context-brief"
 	| "context-summary"
+	| "business"
+	| "business-brief"
 	| "finding-report"
-	| "review"
 	| "resume"
 	| "technical"
-	| "domain-review"
 	| "verify"
 	| "ast"
 	| "ast-impact"
 	| "ai"
 	| "ai-usage"
 	| "ai-brief"
+	| "prepare"
+	| "compare"
 	| "other";
 
 /** Metadados de artefato retornados pela API (sem conteúdo). */
@@ -83,6 +93,8 @@ export type ArtifactMeta = {
 export type RunSummary = {
 	slug: string;
 	branch: string;
+	/** Variante A/B (ausente = run principal da branch). */
+	variant?: string;
 	/** Worktree onde a run foi executada (ausente = clone principal). */
 	worktreePath?: string;
 	prNumber?: number;

package/src/server/run-repository.ts

@@ -48,6 +48,8 @@ import { fetchPrComments, type PrCommentsResponse } from "./pr-comments";
 export type RunListItem = {
 	slug: string;
 	branch: string;
+	/** Variante A/B (ausente = run principal da branch). */
+	variant?: string;
 	/** Worktree onde a run foi executada (ausente = clone principal). */
 	worktreePath?: string;
 	/** PR revisada (quando iniciada via `--pr`). */
@@ -63,6 +65,8 @@ export type RunListItem = {
 export type RunDetail = {
 	slug: string;
 	branch: string;
+	/** Variante A/B (ausente = run principal da branch). */
+	variant?: string;
 	/** Worktree onde a run foi executada (ausente = clone principal). */
 	worktreePath?: string;
 	/** PR revisada (quando iniciada via `--pr`). */
@@ -129,6 +133,7 @@ export class RunRepository {
 		return this.storage.listReviews(this.repo.key).map((review) => {
 			const state = this.storage.readFindings(review.id);
 			return {
+				variant: review.variant,
 				slug: review.slug,
 				branch: review.branch,
 				worktreePath: review.worktreePath,
@@ -144,11 +149,11 @@ export class RunRepository {
 
 	/** Mapa branch → slug das runs (usado para casar PRs com execuções). */
 	branchIndex(): Map<string, string> {
-		return new Map(
-			this.storage
-				.listReviews(this.repo.key)
-				.map((review) => [review.branch, review.slug]),
-		);
+		const index = new Map<string, string>();
+		for (const review of this.reviewsForBranchLinks()) {
+			if (!index.has(review.branch)) index.set(review.branch, review.slug);
+		}
+		return index;
 	}
 
 	/** Mapa branch → run + worktree (sidebar de PRs). */
@@ -156,15 +161,30 @@ export class RunRepository {
 		string,
 		{ slug: string; worktreePath?: string; prNumber?: number }
 	> {
-		return new Map(
-			this.storage.listReviews(this.repo.key).map((review) => [
-				review.branch,
-				{
-					slug: review.slug,
-					worktreePath: review.worktreePath,
-					prNumber: review.prNumber,
-				},
-			]),
+		const index = new Map<
+			string,
+			{ slug: string; worktreePath?: string; prNumber?: number }
+		>();
+		for (const review of this.reviewsForBranchLinks()) {
+			if (index.has(review.branch)) continue;
+			index.set(review.branch, {
+				slug: review.slug,
+				worktreePath: review.worktreePath,
+				prNumber: review.prNumber,
+			});
+		}
+		return index;
+	}
+
+	/**
+	 * Runs ordenadas para links de PR: a principal da branch primeiro (uma
+	 * variante A/B não deve "roubar" o atalho da PR), depois as mais recentes.
+	 */
+	private reviewsForBranchLinks(): ReviewRecord[] {
+		return [...this.storage.listReviews(this.repo.key)].sort(
+			(a, b) =>
+				Number(Boolean(a.variant)) - Number(Boolean(b.variant)) ||
+				b.updatedAt.localeCompare(a.updatedAt),
 		);
 	}
 
@@ -180,6 +200,7 @@ export class RunRepository {
 		}>(review, "classification.json");
 		return {
 			slug: review.slug,
+			variant: review.variant,
 			branch: review.branch,
 			worktreePath: review.worktreePath,
 			prNumber: review.prNumber,

package/src/server/styles.css

@@ -77,6 +77,8 @@ body.resizing-sidebar { cursor:col-resize; user-select:none; }
 .run-icon { flex:none; margin-top:2px; color:var(--muted-2); }
 .run.active .run-icon { color:var(--accent); }
 .run-branch { font-size:12.5px; font-weight:600; line-height:1.35; word-break:break-word; }
+.run-variant { flex:none; align-self:flex-start; padding:1px 6px; border-radius:999px; font-family:var(--font-mono);
+  font-size:9.5px; color:var(--accent); background:var(--accent-soft); border:1px solid var(--accent-line); }
 .run-meta { display:flex; align-items:center; gap:10px; font-family:var(--font-mono); font-size:10.5px; color:var(--muted); }
 .run-when { display:inline-flex; align-items:center; gap:6px; }
 .run-count { margin-left:auto; color:var(--muted-2); }

package/src/skill/OUTPUT-FORMAT.md

@@ -1,7 +1,8 @@
 # Formato de Saída dos Watchdogs
 
 Todo watchdog DEVE gravar **um arquivo JSON** com seus achados. O `report-builder.ts`
-consolida os JSONs no artefato `review.md` do storage global.
+valida e deduplica os JSONs; o `--finalize` grava a triagem no storage e o
+`review-resume.md` com a cobertura por domínio.
 
 > **Não** escrever markdown livre no chat. O único output consumido pelo pipeline é o JSON.
 
@@ -33,7 +34,11 @@ staging global da review:
       "line": 5,
       "message": "Arquivo de rota importa `db` e executa query inline.",
       "action": "Mover a query para o service correspondente.",
-      "evidence": "import { db } from '../db'"
+      "evidence": "import { db } from '../db'",
+      "scenario": "request autenticada em /orders executa a query na rota",
+      "impact": "acoplamento e bypass das regras do service",
+      "confidence": 0.9,
+      "basis": "logic"
     }
   ]
 }
@@ -44,7 +49,7 @@ staging global da review:
 | Campo | Tipo | Obrigatório | Descrição |
 |---|---|---|---|
 | `watchdogId` | string | ✅ | Id do watchdog (deve casar com uma chave de `.houndsman/watchdogs/index.ts`) |
-| `reviewedFiles` | string[] | ✅ | Arquivos efetivamente inspecionados |
+| `reviewedFiles` | string[] | ✅ | Arquivos **do seu domínio** efetivamente revisados (subconjunto de `## Arquivos do seu domínio`; não inclua chamadores/importadores nem arquivos de outros domínios) |
 | `skipped` | string[] | ✅ | Arquivos do domínio que NÃO foram lidos + motivo |
 | `findings` | object[] | ✅ | Achados (vazio se nada encontrado) |
 | `findings[].rule` | string | ✅ | Regra violada (conforme o brief do watchdog) |
@@ -54,6 +59,10 @@ staging global da review:
 | `findings[].message` | string | ✅ | O que está errado (curto, específico) |
 | `findings[].action` | string | ✅ | O que fazer |
 | `findings[].evidence` | string | — | Trecho que comprova o achado |
+| `findings[].scenario` | string | — | Gatilho concreto que expõe o gap (ex.: "renovação de assinatura Pix sem split") |
+| `findings[].impact` | string | — | Consequência observável (ex.: "cobrança recriada sem o split configurado") |
+| `findings[].confidence` | number | — | Confiança do revisor (0–1) |
+| `findings[].basis` | `"rule" \| "logic" \| "domain"` | — | Origem do achado; inferida pelo prefixo `Lógica:`/`Domínio:` |
 
 ## Severidade
 
@@ -68,7 +77,14 @@ staging global da review:
 
 - Sem achados → `"findings": []` (arquivo **obrigatório**).
 - Um achado por regra violada; não agrupar regras diferentes.
+- **Teto de 20 achados por watchdog.** Se houver mais, mantenha os de maior severidade e
+  agrupe ocorrências idênticas (mesmo trecho + mesma regra) em um único item. O JSON precisa
+  caber inteiro — relatório cortado perde achados.
+- `reviewedFiles ∪ skipped` deve cobrir **todo** o escopo do brief. O que não foi revisado
+  entra em `skipped` com o motivo (`budget`, `truncated`, `fora do fluxo`).
 - `file:line` sempre que possível; `evidence` quando o achado não é óbvio.
+- **Trecho truncado** (`… [trecho truncado]`): sem abrir o arquivo para ver o restante, não
+  afirme violação sobre ele — reduza a `confidence` ou não reporte.
 - **Escopo do diff:** a `line` deve cair dentro das faixas listadas em
   *Escopo do diff (símbolos alterados)* no brief. Código fora delas é contexto — não é
   achado desta revisão. Se a alteração quebra código não alterado, ancore o finding na
@@ -76,14 +92,24 @@ staging global da review:
 - Achado **sem linha** só quando for inerente à alteração (vira comentário de arquivo).
 - Não inventar achados — se não houver violação, o array fica vazio.
 
-## Findings emergentes (opt-in)
+## Findings emergentes (obrigatórios no `general`)
 
-Quando o watchdog declara `allowEmergentFindings: true`, você pode reportar falhas de
-**lógica** ou **domínio** que não correspondem a uma regra explícita usando os prefixos
-reservados:
+O watchdog `general` (id reservado, sempre ativo) **deve** reportar gaps de lógica e domínio
+que não correspondem a uma regra explícita, usando os prefixos reservados:
 
 - `Lógica: <descrição>` — nome/contrato vs comportamento, fluxos, estados, bordas.
-- `Domínio: <descrição>` — transições, idempotência, invariantes, arredondamento, timezone.
+- `Domínio: <descrição>` — transições, idempotência, invariantes, arredondamento, timezone,
+  paridade de capacidade, propagação de credencial.
 
-Esses findings continuam exigindo `evidence` e têm severidade máxima `attention`. Sem o
-opt-in, todo finding precisa citar uma regra existente.
+Demonstre o gap em três partes:
+
+1. `scenario` — o gatilho concreto (ex.: "`AsaasSplit` recebe `RenewAutomaticPix`").
+2. `message` — o comportamento observado e o invariante/regra violado.
+3. `evidence` — o trecho que comprova.
+
+**Severidade:** fora de regra, `blocking` só é aceito com `scenario` **e** `evidence`. Sem os
+dois, o motor rebaixa para `attention` (e registra um aviso). Regras explícitas mantêm a
+severidade declarada pelo watchdog.
+
+Os demais watchdogs podem usar os mesmos prefixos apenas quando declararem
+`allowEmergentFindings: true`.

package/src/skill/README.md

@@ -14,6 +14,16 @@ Um único skill (`/houndsman`), quatro capabilities (detalhadas em `hunt.md`, `t
 | `fix` | Correção dos findings marcados como `execute`. |
 | `verify` | Confere se as violações foram resolvidas, sem re-revisar a PR. |
 
+## Dois caminhos para o `hunt`
+
+| Caminho | Quem usa | Requisitos |
+|---|---|---|
+| Skill `/houndsman hunt` | agente externo (Copilot/Claude/etc.) | nenhum |
+| CLI `houndsman hunt` | operador/CI, sem agente | `houndsman hunt install` |
+
+Os dois usam o mesmo `prepare`/`finalize`, o mesmo staging e o mesmo schema de findings.
+O CLI só substitui o despacho manual dos subagentes por processos maki headless.
+
 ## Terminologia
 
 - **houndsman** — o orquestrador/treinador (CLI + motor).
@@ -35,24 +45,29 @@ Um único skill (`/houndsman`), quatro capabilities (detalhadas em `hunt.md`, `t
 
 | Passo | Comando | Quem roda | Resultado |
 |---|---|---|---|
-| 0. Contexto | `bun run houndsman context` | subagente | `context.json` + `context-brief.md` → `context-summary.json` |
-| 1. Preparar | `bun run houndsman` | skill | `classification.json` + `candidates.json` + `briefs/` + `manifest.json` |
-| 2. Revisar | *(subagentes)* | skill | `findings/<watchdog>.json` (um por watchdog) |
-| 3. Finalizar | `bun run houndsman --finalize` | skill | `review.md` |
-
-> **Alvo = PR** (ex.: “revise a PR 456”): troque os passos por `houndsman context --pr 456`,
-> `houndsman --pr 456` e `houndsman --pr 456 --finalize`. O prepare cria um **worktree**
-> detached em `<repo>/.houndsman/worktrees/<repo>/<branch>`; os briefs trazem
-> `**Worktree:**` e os subagentes devem ler essa árvore (nunca o clone principal).
+| 0. Contexto | `houndsman --pr` (via `gh`) | prepare | `context.json` + `context-brief.md` → `context-summary.json` (IA; sem IA, subagente) |
+| 1. Preparar | `bun run houndsman` | skill | `classification.json` + `candidates.json` + `business-summary.json` + `briefs/` + `manifest.json` |
+| 1.5. Intenção | *(subagente)* | skill, só sem IA | `business-summary.json` enriquecido (só quando não veio da IA) |
+| 2. Revisar | *(subagentes)* | skill | `findings/<watchdog>.json` (inclui o `general`, sempre ativo) |
+| 3. Finalizar | `bun run houndsman --finalize` | skill | `review-resume.md` + triagem no storage |
+
+> **Alvo = PR** (ex.: “revise a PR 456”): use `houndsman --pr 456` e
+> `houndsman --pr 456 --finalize`. O prepare coleta o contexto via `gh`, cria um **worktree**
+> detached em `<repo>/.houndsman/worktrees/<repo>/<branch>` e resume o contexto com IA;
+> os briefs trazem `**Worktree:**` e os subagentes devem ler essa árvore (nunca o clone
+> principal). Despache os briefs em paralelo (mesmo bloco de tool calls).
 
 ## Comandos
 
 | Comando | Função |
 |---|---|
-| `houndsman context` | Passo 0 — contexto da PR via `gh` (`--pr <n>`/`--worktree <path>`) |
+| `houndsman context` | Contexto da PR via `gh` (`--pr <n>`/`--worktree <path>`) — o prepare já coleta com `--pr` |
 | `houndsman` | Passo 1 — preparar (gera os briefs) |
 | `houndsman --pr <n>` | Passo 1 em worktree dedicado (revisões paralelas) |
-| `houndsman --finalize` | Passo 3 — gerar o relatório (`--pr <n>` reusa o worktree) |
+| `houndsman --finalize` | Passo 3 — gravar a triagem e o resumo final (`--pr <n>` reusa o worktree) |
+| `houndsman hunt [--pr <n>]` | Harness local opcional (maki): prepare → watchdogs → finalize |
+| `houndsman compare` | Compara duas runs/variantes (`--list`, `--a`, `--b` ou dois slugs) |
+| `houndsman hunt install` | Baixa o maki fixado para `<HOUNDSMAN_HOME>/tools/maki` |
 | `houndsman worktree <ação>` | `list`/`add`/`remove`/`prune`/`path` dos worktrees |
 | `houndsman watchdog <id>` | Contexto de um watchdog (`--json`, `--rules`) |
 | `houndsman findings <sub>` | Triagem/correção dos findings (`list`/`set`/`done`/`sync`/`batch`/`verify`/...) |
@@ -78,9 +93,10 @@ Runs, findings e artefatos vivem no **storage global** (SQLite em `<HOUNDSMAN_HO
 | 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 |
-| `manifest.json` | Resumo (watchdogs, arquivos, deletados, contexto, orçamento, churn) |
+| `business-summary.json` / `business-brief.md` | Modelo de intenção da PR e o brief do passo |
+| `manifest.json` | Resumo (watchdogs, arquivos, deletados, contexto, intenção, 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 |
+| `review-resume.md` | Resumo final: negócio, pontos técnicos, cobertura por domínio e conclusão |
 | `verify.md` | Relatório do `findings verify` |
 | `context.json` / `context-brief.md` / `context-summary.json` | Contexto da PR |
 
@@ -109,7 +125,7 @@ src/
 │   ├── paths.ts             # layout fixo da camada (.houndsman/) + relFromRoot
 │   ├── types.ts             # Severity, Rule, WatchdogDefinition, defineWatchdog
 │   ├── watchdog-registry.ts # getWatchdog/findWatchdog/getWatchdogContext(config)
-│   ├── orchestrator.ts      # preparar/finalizar
+│   ├── orchestrator.ts      # fachada: preparar/finalizar (pipelines em engine/)
 │   ├── brief.ts             # defaultRenderBrief + PROCEDURE
 │   ├── pr-context.ts        # contexto da PR via gh
 │   ├── file-classifier.ts   # classificação (via `classify` dos watchdogs) + churn

package/src/skill/SETUP.md

@@ -76,6 +76,25 @@ Depois do setup, invoque o skill `/houndsman` no seu harness:
 | `/houndsman train` | Adicionar/ajustar/remover regras dos watchdogs. |
 | `/houndsman fix` | Corrigir os findings marcados como `execute`. |
 
+## Harness local (opcional) — `houndsman hunt`
+
+Quem não quer rodar a skill dentro de um agente externo pode executar a revisão 100% pelo
+CLI. O maki é instalado sob demanda, fora do projeto, e reaproveita a credencial já existente:
+
+```bash
+houndsman hunt install      # baixa o maki fixado (sha256) em <HOUNDSMAN_HOME>/tools/maki
+houndsman hunt doctor       # binário, modelo e credencial (opcional; não falha sem maki)
+houndsman hunt --pr 456     # prepare → maki (um processo por brief) → finalize
+```
+
+- A skill `/houndsman hunt` continua sendo o caminho canônico e não depende do maki.
+- `HOUNDSMAN_MAKI_PATH` aponta um binário já instalado; `HOUNDSMAN_MAKI_VERSION` troca a
+  versão baixada.
+- Config opcional em `houndsman.config.ts`: `hunt: { model?, concurrency?, timeoutMs?,
+  retries?, binaryPath?, enabled? }`.
+- Se algum watchdog falhar, o comando **não finaliza** (preserva o staging); use
+  `--allow-partial` para finalizar com findings vazios registrados em `skipped`.
+
 ## Contrato do motor (`HoundsmanConfig`)
 
 Definido em `src/core/config.ts` (pacote) e espelhado em `.houndsman/core/types.ts` (gerado):
@@ -87,10 +106,12 @@ Definido em `src/core/config.ts` (pacote) e espelhado em `.houndsman/core/types.
 | `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. |
+| `priorities` | **Opcional** — prioridade por caminho `[{ pattern: RegExp, bonus?: number, maxRiskFromChurn?: number }]`. Risco = `min(churn, maxRiskFromChurn) + bonus`: `bonus` promove caminho crítico e o teto impede que superchurn de caminho de baixa criticidade escale. A primeira regra que casar vence. Ordena o orçamento, o rateio do diff e o recorte do `general`. Sem config: churn puro. |
 | `alwaysIncludeDocs` | Docs sempre presentes nos briefs (default `["AGENTS.md"]`). |
 | `budgets` | **Opcional** — teto de arquivos por brief (`maxFilesPerBrief`, default `40`); o excedente vira "fora do orçamento" (registrar em `skipped`). |
 | `concurrency` | **Opcional** — chamadas Jev simultâneas (`jev`, default `5`). |
 | `ast` | **Opcional** — AST determinístico para TS/JS (`enabled`, `maxFileBytes`, `maxImpactFiles`, `languages`, `aliases`). Default: ligado; falhas são fail-open. |
+| `hunt` | **Opcional** — harness local (`model`, `concurrency`, `timeoutMs`, `retries`, `binaryPath`, `enabled`). Só afeta `houndsman hunt`; a skill não depende. |
 
 > O motor **não contém** ids, paths ou regras do projeto — tudo chega por `HoundsmanConfig`,
 > carregado em runtime a partir de `houndsman.config.ts` (ou `--config <path>`).
@@ -103,7 +124,7 @@ houndsman/
 └── src/
     ├── index.ts              # API pública (defineWatchdog, defineHoundsmanConfig, tipos)
     ├── cli/index.ts          # CLI único — bin `houndsman`
-    ├── core/                 # bibliotecas genéricas (config, orchestrator, brief, jev/, …)
+    ├── core/                 # bibliotecas genéricas (config, orchestrator, brief, jev/, hunt/, …)
     ├── skill/*.md            # assets markdown (embarcados no pacote)
     └── tests/                # suíte da lib (project-agnóstica, "project fake")
 ```

package/src/skill/SKILL.md

@@ -14,6 +14,11 @@ consolida tudo num relatório. O motor é o CLI **`houndsman`**; as regras do pr
 **Terminologia:** **houndsman** = orquestrador/treinador (CLI + motor) · **watchdog** = agente
 especialista por domínio · **finding** = um achado da revisão · **Jev** = pré-análise opcional.
 
+> **Duas etapas são obrigatórias em toda revisão:** o **modelo de intenção**
+> (`business-summary.json`) e o revisor de fluxo **`general`** (id reservado, sempre ativo).
+> O modelo vem da IA no prepare quando há chave; sem chave, um subagente (Passo 1.5) ou o
+> pré-passe maki o produz. Nenhum dos dois é configurável pelo usuário.
+
 ## Capabilities
 
 | Capability | Objetivo | Documento |
@@ -38,6 +43,10 @@ especialista por domínio · **finding** = um achado da revisão · **Jev** = pr
 Um argumento extra é o alvo da capability. Escolha a capability pelo que o usuário quer,
 leia o documento correspondente em `.houndsman/core/skill/<capability>.md` e siga-o.
 
+> **Harness local (opcional):** para rodar sem agente externo, o operador pode instalar o
+> maki (`houndsman hunt install`) e usar `houndsman hunt --pr 456`. Isso não muda esta
+> skill: se você é o agente, siga o fluxo normal e não rode `houndsman hunt`.
+
 ### Alvo da revisão (PR × branch)
 
 Interprete o alvo em linguagem natural **antes** de rodar o CLI:
@@ -56,12 +65,16 @@ Interprete o alvo em linguagem natural **antes** de rodar o CLI:
 Sequência para uma PR (ex.: 456):
 
 ```bash
-houndsman context --pr 456
-houndsman --pr 456                 # cria/reusa o worktree e imprime o caminho
-# despache os briefs (cada um traz **Worktree:** <path>)
+houndsman --pr 456                 # cria/reusa o worktree, coleta o contexto e prepara
+# despache os briefs em paralelo (cada um traz **Worktree:** <path>)
 houndsman --pr 456 --finalize
 ```
 
+- O contexto da PR é coletado pelo próprio prepare (via `gh`); com IA ligada ele também é
+  resumido ali — não gaste um subagente nisso. Desative com `--no-context`.
+- Para comparar duas execuções, use `--variant <label>` em cada uma e depois
+  `houndsman compare --branch <head> --a <a> --b <b>` (ou `compare --list`).
+
 - O worktree vive em `<repo>/.houndsman/worktrees/<repo>/<branch>` (detached no commit da PR)
   e é reutilizado nas próximas execuções da mesma branch. Ele fica **dentro do workspace**
   (e o staging também) para o agente ler/executar sem prompts de permissão.
@@ -79,4 +92,4 @@ houndsman --pr 456 --finalize
 - `.houndsman/core/skill/OUTPUT-FORMAT.md` — schema do JSON de saída dos watchdogs.
 - `.houndsman/core/skill/AUDIT-PROTOCOL.md` — taxonomia da auditoria de regras (Modo B do `train`).
 - `.houndsman/core/skill/SETUP.md` · `.houndsman/core/skill/README.md` — configuração e visão geral.
-- `.houndsman/core/skill/example-review.md` — exemplo de relatório.
+- `.houndsman/core/skill/example-resume.md` — exemplo do resumo final.

package/src/skill/example-resume.md

@@ -0,0 +1,43 @@
+# Resumo da revisão — feature/add-webhook-retry
+
+**Data:** 2026-04-20 · **Status:** ❌ Mudanças Necessárias
+
+## Resumo de negócio
+
+Tornar o envio de webhooks resiliente a falhas temporárias do destinatário, sem perda de
+eventos e sem reenvio manual.
+
+**Invariantes:**
+- Todo evento entregue tem no máximo uma tentativa `in_flight` por destinatário.
+- O retry nunca duplica o `eventId` já aceito pelo integrador.
+
+**Fluxos (2):**
+- **Retry de webhook** — disparo: resposta não-2xx/timeout — esperado: reagendamento com
+  backoff exponencial e registro da tentativa.
+
+## Pontos técnicos
+
+- **Contratos** — `WebhookRetryPolicy`, `RetryAttempt` (`src/webhooks/types.ts`).
+- **Implementações** — `WebhookDispatcher` (`src/webhooks/dispatcher.ts`).
+- **Novas dependências** — `p-retry`.
+
+## Cobertura por domínio
+
+| Domínio | Achados | Revisados | Faltam |
+|---|---|---|---|
+| Arquitetura Backend | 2 | 3/3 | — |
+| Pagamentos & Integrações | 1 | 4/4 | — |
+| Acquirer Integrations | 2 | 3/4 | 1 |
+
+## Candidatos não verificados (1)
+
+> Indícios da pré-análise que nenhum watchdog confirmou. Não bloqueiam.
+
+- `src/webhooks/queue.ts` · attention · Fila sem limite de tentativas.
+
+## Conclusão
+
+**Resumo:** 2 bloqueantes · 1 atenção · 1 sugestões · 1 nits.
+
+> Achados individuais (com `id` de triagem) vivem na UI (`Findings`) e em
+> `houndsman findings list --json` — o resumo não os duplica.