@payconductor/houndsman 0.13.0 → 0.14.0

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

@@ -45,25 +45,28 @@ O CLI só substitui o despacho manual dos subagentes por processos maki headless
 
 | 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`) |
@@ -90,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 |
 
@@ -121,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

@@ -106,6 +106,7 @@ 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`). |

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 |
@@ -60,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.
@@ -83,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.