@payconductor/houndsman 0.13.0 → 0.16.0

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,12 @@ 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",
+      "impactClass": "flow-break",
+      "confidence": 0.9,
+      "basis": "logic"
     }
   ]
 }
@@ -44,7 +50,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,9 +60,28 @@ 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[].impactClass` | `"flow-break" \| "contract-drift" \| "degradation" \| "cosmetic"` | emergente | Classe de impacto que define a severidade fora de regra |
+| `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
 
+A severidade é **derivada**, não escolhida pelo watchdog:
+
+| Origem do finding | Fonte da severidade |
+|---|---|
+| Regra do brief (`rule` copiada) | `severity` **declarada na regra** — outro valor é ignorado e corrigido pelo motor |
+| Emergente (`Lógica:`/`Domínio:`) | `impactClass`, pela tabela abaixo |
+
+| `impactClass` | Quando usar | Severidade |
+|---|---|---|
+| `flow-break` | o caminho não completa (criação/renovação/cancelamento) ou a capacidade declarada não é honrada | `blocking` (exige `scenario` + `evidence`) |
+| `contract-drift` | contrato, identificador ou estado divergente — mas o fluxo completa | `attention` |
+| `degradation` | funciona, mas com borda, erro, retry ou idempotência frágil | `suggestion` |
+| `cosmetic` | clareza, nome, detalhe cosmético | `nit` |
+
 | Severidade | Emoji | Bloqueia merge? |
 |---|---|---|
 | `blocking` | ❌ | Sim |
@@ -64,11 +89,21 @@ staging global da review:
 | `suggestion` | 💡 | Não |
 | `nit` | 🔎 | Não (detalhe/observação) |
 
+> Sem `impactClass` (relatório antigo), o motor mantém o valor emitido em `severity`.
+> Conflito de severidade numa mesma regra entre reviews deixa de existir: a regra é a fonte.
+
 ## Regras
 
 - 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 +111,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.
+
+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 **na regra**.
 
-Esses findings continuam exigindo `evidence` e têm severidade máxima `attention`. Sem o
-opt-in, todo finding precisa citar uma regra existente.
+Os demais watchdogs podem usar os mesmos prefixos apenas quando declararem
+`allowEmergentFindings: true`.

package/src/skill/README.md

@@ -45,25 +45,29 @@ 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 golden` | Avalia runs contra um golden set de defeitos (`recall`/`precisão`) |
 | `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 +94,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 +126,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.