@payconductor/houndsman 0.0.0-stage → 0.1.1

package/src/skill/AUDIT-PROTOCOL.md

@@ -0,0 +1,96 @@
+# Protocolo de Auditoria dos Watchdogs — houndsman
+
+Referência do Modo B do skill `houndsman-update`. Objetivo: garantir que as regras dos
+watchdogs validam **apenas padrões que o projeto aplica hoje**. Regras "utópicas" (não
+aplicadas em nenhuma parte do código) devem ser **removidas**, não apenas rebaixadas.
+
+---
+
+## Entradas
+
+1. `.houndsman/watchdogs/<id>.ts` — `WATCHDOG_DEFINITIONS[<id>]` é a fonte única de verdade:
+   `description`, `scope`, `rules` (severidade + texto), `classify`, `contextFiles`,
+   `reviewFocus`, `exclude`.
+2. `src/core/brief.ts` (no motor) — `PROCEDURE` (passos de revisão compartilhados).
+3. Ground truth (padrões reais do projeto):
+   - Documentos de convenção do projeto (ex.: `AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`).
+   - Documentação de arquitetura/domínio do projeto.
+   - Código-fonte real do domínio (fonte final da verdade).
+
+## Regra de ouro
+
+> Só é regra o que o projeto **aplica hoje** — mas como provar depende da **polaridade**:
+>
+> - Regra **afirmativa** (`Promover:`): a **ausência** do padrão no código prova que ele **não é
+>   aplicado** → `UTOPIAN` (remover/rebaixar). Não inferir intenção aspiracional.
+> - Regra **negativa** (`Evitar:`, `Não`, `Nunca`): a **ausência** do anti-padrão prova que a regra
+>   **é seguida** → `ALIGNED` (**manter**). Nunca remover uma regra negativa por "0 ocorrências".
+
+Use regra **geral e reutilizável** (padrão do domínio), nunca regra de negócio pontual amarrada a
+uma classe/use-case — isso é papel de teste automatizado.
+
+Use `grep_search`/`file_search`/`read_file` para **provar** cada veredito. Nunca
+classifique sem evidência (caminho de arquivo, linha, ou "0 ocorrências via grep X").
+
+## Taxonomia de veredito
+
+| Veredito | Significado | Ação proposta |
+|---|---|---|
+| `ALIGNED` | Padrão documentado E aplicado no código (regra negativa: anti-padrão **ausente**) | Manter |
+| `UTOPIAN` | Regra **afirmativa** cujo padrão não existe em lugar nenhum hoje | **Remover** |
+| `OUTDATED` | Já foi aplicado, mas o código mudou | Remover ou reescrever |
+| `MISCALIBRATED` | Regra válida, mas severidade errada | Ajustar severidade |
+| `DEAD-PATH` | `scope`/`contextFiles`/`classify` apontam para caminho/arquivo inexistente | Corrigir ou remover |
+
+## Formato do relatório
+
+Gravar `.houndsman-audit/<watchdog-id>.md`:
+
+```markdown
+# Auditoria — <Nome do watchdog> (`<watchdog-id>`)
+
+## Ground truth do domínio
+- Padrões reais observados (com caminhos de arquivo).
+- Caminhos reais do domínio (confirmar existência).
+
+## Veredito por regra
+
+| # | Severidade atual | Polaridade | Regra | Veredito | Evidência | Ação proposta |
+|---|---|---|---|---|---|---|
+| 1 | blocking | afirmativa | <texto da regra> | UTOPIAN | 0 matches em `src/...` | Remover |
+| 2 | attention | negativa | <texto da regra> | ALIGNED | 0 ocorrências do anti-padrão | Manter |
+| ... |
+
+## Correções de metadados
+- `scope`: ...
+- `contextFiles`: ...
+
+## Protocolo (procedimento)
+- Ajustes no `PROCEDURE` compartilhado (`src/core/brief.ts`) ou no `reviewFocus`/`exclude` do watchdog.
+
+## Resumo
+- Total de regras: N · ALIGNED: N · UTOPIAN: N · OUTDATED: N · MISCALIBRATED: N · DEAD-PATH: N
+- Regras a remover: ...
+- Regras a corrigir: ...
+```
+
+## Consolidação
+
+- Um relatório consolidado em `.houndsman-audit/audit-summary.md`.
+- Agrupar **temas transversais** (ex.: a mesma regra aparecia em 2 watchdogs).
+- Resolver conflitos: uma regra duplicada entre watchdogs deve viver no watchdog dono do domínio.
+
+## Disparo dos subagentes
+
+- 1 subagente por watchdog; despachar em ondas paralelas (ex.: 8 + 7).
+- Prompt mínimo:
+
+  > Você é um auditor do skill `houndsman` do {{projectName}}. Leia e siga
+  > `.houndsman/core/skill/AUDIT-PROTOCOL.md`. Watchdog alvo: `<watchdog-id>`. Audite CADA regra de
+  > `WATCHDOG_DEFINITIONS["<watchdog-id>"]` contra o código/docs reais, provando cada veredito.
+  > Grave `.houndsman-audit/<watchdog-id>.md`. Retorne: contagem por veredito,
+  > regras a REMOVER e a CORRIGIR. Não altere outros arquivos.
+
+## Idioma
+
+Relatórios em português. Código e identificadores em inglês. Seja sucinto.

package/src/skill/OUTPUT-FORMAT.md

@@ -0,0 +1,70 @@
+# Formato de Saída dos Watchdogs
+
+Todo watchdog DEVE gravar **um arquivo JSON** com seus achados. O `report-builder.ts`
+consolida os JSONs em `.houndsman/.runs/<branch-slug>/review.md`.
+
+> **Não** escrever markdown livre no chat. O único output consumido pelo pipeline é o JSON.
+
+## Caminho do arquivo
+
+O caminho exato é informado no brief do watchdog (gerado por `houndsman`):
+
+```
+.houndsman/.runs/<branch-slug>/findings/<watchdogId>.json
+```
+
+- `<branch-slug>`: branch com `/` substituído por `-` (ex.: `feature/x` → `feature-x`).
+- `<watchdogId>`: id do watchdog (ex.: `backend-architecture`).
+
+## Schema
+
+```json
+{
+  "watchdogId": "backend-architecture",
+  "reviewedFiles": ["src/services/order/order-service.ts"],
+  "skipped": [],
+  "findings": [
+    {
+      "rule": "Route acessando db",
+      "severity": "blocking",
+      "file": "src/routes/order-route.ts",
+      "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'"
+    }
+  ]
+}
+```
+
+### Campos
+
+| 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 |
+| `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) |
+| `findings[].severity` | `"blocking" \| "attention" \| "suggestion" \| "nit"` | ✅ | Severidade |
+| `findings[].file` | string | ✅ | Caminho relativo à raiz |
+| `findings[].line` | number | — | Linha do achado |
+| `findings[].message` | string | ✅ | O que está errado (curto, específico) |
+| `findings[].action` | string | ✅ | O que fazer |
+| `findings[].evidence` | string | — | Trecho que comprova o achado |
+
+## Severidade
+
+| Severidade | Emoji | Bloqueia merge? |
+|---|---|---|
+| `blocking` | ❌ | Sim |
+| `attention` | ⚠️ | Não (requer atenção) |
+| `suggestion` | 💡 | Não |
+| `nit` | 🔎 | Não (detalhe/observação) |
+
+## Regras
+
+- Sem achados → `"findings": []` (arquivo **obrigatório**).
+- Um achado por regra violada; não agrupar regras diferentes.
+- `file:line` sempre que possível; `evidence` quando o achado não é óbvio.
+- Não inventar achados — se não houver violação, o array fica vazio.

package/src/skill/README.md

@@ -0,0 +1,124 @@
+# houndsman — skill
+
+Revisão automatizada de Pull Requests — CLI independente + camada de configuração do projeto.
+
+## Terminologia
+
+- **houndsman** — o orquestrador/treinador (CLI + motor).
+- **watchdog** — cada agente especialista por domínio que audita o diff.
+- **brief** — instruções prontas para um watchdog (o prompt do subagente).
+- **findings** — os achados que o subagente grava em JSON (único output consumido).
+- **candidato (Jev)** — indício automático; **não** é achado (o watchdog confirma ou refuta).
+- **churn** — linhas adicionadas/removidas por arquivo; usado para priorizar a leitura.
+- **budget / orçamento** — teto de arquivos por brief; o excedente ("fora do orçamento")
+  não é revisado, mas fica registrado em `skipped`.
+- **review/revisão** — o processo de revisão.
+
+## Quem executa o quê
+
+- **Você** só invoca o skill: `/houndsman`. Não roda script à mão.
+- **O skill** orquestra: executa o CLI `bun run houndsman` e despacha os subagentes.
+- **O CLI** tem passos distintos — um comando cada:
+
+| 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` |
+
+## Comandos
+
+| Comando | Função |
+|---|---|
+| `houndsman context` | Passo 0 — contexto da PR via `gh` |
+| `houndsman` | Passo 1 — preparar (gera os briefs) |
+| `houndsman --finalize` | Passo 3 — gerar o relatório |
+| `houndsman watchdog <id>` | Contexto de um watchdog (`--json`, `--rules`) |
+| `houndsman setup` | Cria a configuração inicial do projeto |
+| `houndsman update` | Sincroniza os arquivos auto-gerados (`.houndsman/core`) |
+| `houndsman doctor` | Valida a configuração, o ambiente e a credencial Jev (anti-drift) |
+| `houndsman test` | Roda a suíte de testes da lib |
+
+### Flags
+
+`--config <path>` · `--base <branch>` (default `main`) · `--head <ref>` (default `HEAD`) ·
+`--branch <nome>` · `--dir <dir>` · `--clean` · `--no-jev` · `--fail-on-blocking` (no `--finalize`).
+
+## Artefatos
+
+Tudo em `.houndsman/.runs/<branch-slug>/` (default do `artifactDir`, `.houndsman/.runs`):
+
+| Arquivo | Conteúdo |
+|---|---|
+| `classification.json` | Watchdogs ativados + status (A/M/D/R) + churn |
+| `candidates.json` | Candidatos da pré-análise Jev |
+| `context.json` | Payload bruto da PR via `gh` (ou marcador de indisponível) |
+| `context-summary.json` | Resumo do subagente (objetivo/motivação/alterações) |
+| `briefs/<watchdog>.md` | Instruções prontas para cada sub-agente (arquivos por risco) |
+| `manifest.json` | Resumo (watchdogs, arquivos, deletados, status, contexto, orçamento, churn) |
+| `findings/<watchdog>.json` | Saída dos sub-agentes (schema `OUTPUT-FORMAT.md`) |
+| `review.md` | Relatório final (achados agrupados por arquivo) |
+| `review.<watchdog>.md` | Relatório por domínio (só quando há achados) |
+
+## Estrutura
+
+### Pacote (motor)
+
+```
+src/
+├── index.ts             # API pública (defineWatchdog, defineHoundsmanConfig, tipos)
+├── cli/index.ts         # CLI ÚNICO (bin `houndsman`)
+├── core/                # bibliotecas genéricas
+│   ├── config.ts            # contrato HoundsmanConfig + defineHoundsmanConfig
+│   ├── config-loader.ts     # descoberta/carregamento de houndsman.config.ts
+│   ├── assets.ts            # assets embarcados (src/skill/) — usados para gerar a camada
+│   ├── 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
+│   ├── brief.ts             # defaultRenderBrief + PROCEDURE
+│   ├── pr-context.ts        # contexto da PR via gh
+│   ├── file-classifier.ts   # classificação (via `classify` dos watchdogs) + churn
+│   ├── diff-source.ts       # diff único (patch + --numstat) p/ churn/orçamento
+│   ├── doc-discoverer.ts    # descoberta de docs
+│   ├── report-builder.ts    # dedupe/render do relatório
+│   ├── registry-check.ts    # validações anti-drift (config-driven)
+│   ├── commands/            # context · review · watchdog · setup · update · test
+│   └── jev/                 # subsistema Jev (Passo 1.5)
+├── skill/*.md           # assets markdown (embarcados no pacote)
+└── tests/               # suíte da lib (project-agnóstica, "project fake")
+```
+
+### Projeto (consumidor — gerado por `houndsman setup`)
+
+```
+houndsman.config.ts           # HoundsmanConfig (dados; descoberto em runtime)
+.houndsman/
+├── .gitignore                # AUTO — ignora core/ e .runs/
+├── core/                     # AUTO — sincronizado por `houndsman update`
+│   ├── types.ts              # snapshot dos tipos + helpers (autocontido)
+│   └── skill/*.md            # documentação do skill
+├── watchdogs/                # USUÁRIO — 1 módulo .ts por watchdog
+│   └── index.ts              # WATCHDOG_DEFINITIONS + type WatchdogId
+├── exclusions.ts             # USUÁRIO
+└── doc-mappings.ts           # USUÁRIO
+```
+
+> Os `SKILL.md` em `.agents/skills/houndsman/` e `.claude/skills/houndsman/` são
+> ponteiros para `.houndsman/core/skill/houndsman.md`.
+
+## Manutenção
+
+> As regras devem refletir os padrões **aplicados hoje**. Antes de adicionar uma regra,
+> prove que o padrão existe no código (regra negativa: prove que o anti-padrão **não** existe).
+> Regras devem ser **gerais/reutilizáveis** no domínio e declarar a **polaridade** no texto
+> (`Promover:` = deve acontecer; `Evitar:`/`Não`/`Nunca` = não deve acontecer).
+
+1. Novas regras/watchdogs → editar `.houndsman/watchdogs/<id>.ts` (regras + escopo +
+   `classify`) ou `doc-mappings.ts`/`exclusions.ts`. Um watchdog novo exige só o módulo em
+   `.houndsman/watchdogs/<id>.ts` + entrada em `.houndsman/watchdogs/index.ts`.
+2. Rodar `bun run houndsman doctor` — valida a config (definições, classificação, specs Jev).
+
+> Para qualquer alteração de regra (pontual ou auditoria completa), use o skill
+> **`houndsman-update`**: `.houndsman/core/skill/houndsman-update.md`.

package/src/skill/SETUP.md

@@ -0,0 +1,101 @@
+# Setup — usar o houndsman no seu projeto
+
+O **houndsman** é um CLI instalado **globalmente**. A camada de configuração que ele gera
+no seu projeto é **autocontida** — não exige nenhuma dependência local do pacote.
+
+## Pré-requisitos
+
+- **Bun** — o CLI e o motor usam a runtime Bun (execução de TS, `Bun.spawnSync`).
+- **git** — o diff usa `git diff <base>...<head> --name-status`.
+- Opcional: **`gh`** (contexto da PR) e **`TYPESAFE_API_KEY`** (pré-análise Jev). O pipeline
+  segue normalmente sem eles.
+
+## Instalação (global)
+
+```bash
+bun add -g @payconductor/houndsman
+```
+
+O comando `houndsman` fica disponível em qualquer diretório.
+
+## Configuração
+
+Na raiz do seu projeto:
+
+```bash
+bun run houndsman setup
+```
+
+Isso cria:
+
+A camada separa o que é **auto-gerado** do que é **do usuário**:
+
+| Caminho | Dono | O que é |
+|---|---|---|
+| `houndsman.config.ts` | usuário | Configuração — um objeto de dados (sem imports do pacote) |
+| `.houndsman/watchdogs/example.ts` + `index.ts` | usuário | Comece com **1 watchdog de exemplo** |
+| `.houndsman/exclusions.ts` | usuário | Arquivos que nunca entram na revisão |
+| `.houndsman/doc-mappings.ts` | usuário | path → documentação de contexto |
+| `.houndsman/core/types.ts` | **auto** | Snapshot dos tipos + helpers (tipagem sem install) |
+| `.houndsman/core/skill/*.md` | **auto** | Documentação do skill |
+| `.houndsman/.gitignore` | **auto** | Ignora `core/` e `.runs/` (gerados/temporários) |
+| `.agents/skills/houndsman/SKILL.md` etc. | **auto** | Ponteiros de skill dos harnesses |
+
+Além disso, adiciona o script `"houndsman": "houndsman"` ao `package.json` — assim
+`bun run houndsman [...]` funciona na raiz do projeto. Os artefatos ficam em
+`.houndsman/.runs/<branch-slug>/` (auto-ignorados).
+
+Flags: `--name <projeto>` · `--harness agents,claude|both|none` · `--force` (sobrescreve só os
+arquivos do usuário). É **idempotente** — arquivos do usuário existentes são mantidos.
+
+## Atualizar (auto-gerados)
+
+Depois de atualizar a lib, sincronize os arquivos auto-gerados **sem tocar** nas suas regras:
+
+```bash
+bun run houndsman update      # reescreve .houndsman/core/** e .houndsman/.gitignore
+```
+
+## Verificar
+
+```bash
+bun run houndsman doctor         # valida config + ambiente + credencial Jev
+bun run houndsman test           # suíte da lib (project-agnóstica)
+bun run houndsman --base main    # prepara briefs do diff atual
+```
+
+## Contrato do motor (`HoundsmanConfig`)
+
+Definido em `src/core/config.ts` (pacote) e espelhado em `.houndsman/core/types.ts` (gerado):
+
+| Campo | Descrição |
+|---|---|
+| `projectName` | Nome legível (prompts/docs). |
+| `artifactDir` | **Opcional** — onde gravar os artefatos (default `.houndsman/.runs`). |
+| `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. |
+| `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`). |
+
+> 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>`).
+
+## Estrutura do pacote (motor)
+
+```
+houndsman/
+├── package.json
+└── src/
+    ├── index.ts              # API pública (defineWatchdog, defineHoundsmanConfig, tipos)
+    ├── cli/index.ts          # CLI único — bin `houndsman`
+    ├── core/                 # bibliotecas genéricas (config, orchestrator, brief, jev/, …)
+    ├── skill/*.md            # assets markdown (embarcados no pacote)
+    └── tests/                # suíte da lib (project-agnóstica, "project fake")
+```
+
+## Desenvolvimento da lib
+
+- Scripts: `bun run test`, `bun run typecheck`, `bun run ci`.
+- O motor é 100% agnóstico ao consumidor: nenhuma regra, path ou nome de projeto vive aqui.

package/src/skill/example-review.md

@@ -0,0 +1,58 @@
+# PR Review — feature/add-webhook-retry
+
+**Data:** 2026-04-20
+**Watchdogs ativos:** api-contracts, backend-architecture, payments-integrations, acquirer-integrations
+**Achados:** 2 bloqueantes · 1 atenção · 1 sugestões · 1 nit
+
+## Contexto da PR
+**PR:** #482 Adicionar retry de webhooks — https://github.com/org/repo/pull/482
+**Branch:** `feature/add-webhook-retry` → `main`
+**Objetivo:** Tornar o envio de webhooks resiliente a falhas temporárias do destinatário.
+**Motivação:** Webhooks com falha exigiam reenvio manual e causavam perda de eventos em integradores.
+**Resumo das alterações:**
+- Nova fila de retry para webhooks que falharam.
+- Novo endpoint interno para reprocessar eventos manualmente.
+- Registro de tentativas no handler de envio.
+
+## ❌ blocking
+
+- **Webhook handler sem verifySignature** — `server/src/services/integrations/acquirer/webhook/handle-charge-event.ts:15` · _Acquirer Integrations, Pagamentos & Integrações_
+  Payload processado antes de validar a assinatura do provider.
+  **Ação:** Validar `verifyWebhookSignature(payload, signature, secret)` antes de qualquer efeito.
+  **Evidência:** `const event = JSON.parse(body)`
+
+- **Promise não aguardada** — `server/src/services/webhook/webhook-retry-service.ts:92` · _Pagamentos & Integrações_
+  `updateWebhookStatus(id, 'failed')` sem `await` — status pode não persistir antes do retorno.
+  **Ação:** Adicionar `await`.
+
+## ⚠️ attention
+
+- **Retry sem backoff** — `server/src/services/webhook/webhook-retry-service.ts:55` · _Acquirer Integrations_
+  Retry com intervalo fixo de 1s.
+  **Ação:** Usar exponential backoff com jitter.
+
+## 💡 suggestion
+
+- **Complexidade** — `server/src/services/webhook/webhook-retry-service.ts:45-78` · _Arquitetura Backend_
+  `retryWithBackoff` com 6 níveis de indentação.
+  **Ação:** Extrair `calculateBackoffDelay(attempt, config)` e usar early returns.
+
+## 🔎 nit
+
+- **Ordem de membros** — `server/src/services/webhook/webhook-retry-service.ts:12` · _Arquitetura Backend_
+  Campo privado declarado antes do construtor público.
+  **Ação:** Reordenar membros (públicos primeiro).
+
+## Cobertura
+
+| Watchdog | Arquivos revisados | Findings |
+|---|---|---|
+| API & Contratos | 2 | 0 |
+| Arquitetura Backend | 3 | 1 |
+| Pagamentos & Integrações | 4 | 2 |
+| Acquirer Integrations | 3/4 (faltam 1) | 2 |
+
+## Conclusão
+
+**Status:** ❌ Mudanças Necessárias
+**Resumo:** 2 violações bloqueantes, 1 ponto de atenção, 1 sugestão.