@payconductor/houndsman 0.0.0-stage → 0.1.0

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,116 @@
+# 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.
+- **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 e o ambiente (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) |
+| `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 |
+| `manifest.json` | Resumo (watchdogs, arquivos, deletados, status, contexto) |
+| `findings/<watchdog>.json` | Saída dos sub-agentes (schema `OUTPUT-FORMAT.md`) |
+| `review.md` | Relatório final |
+
+## 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)
+│   ├── 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,99 @@
+# 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). Ambos são
+  **falha-aberto** — sem eles o pipeline segue normalmente.
+
+## 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 (git/gh/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"]`). |
+
+> 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.

package/src/skill/houndsman-update.md

@@ -0,0 +1,251 @@
+# Atualização de Lógicas do houndsman
+
+> **Documento canônico do skill `/houndsman-update`.** Os `SKILL.md` de cada harness
+> (`.agents/skills/houndsman-update/` e `.claude/skills/houndsman-update/`) são apenas ponteiros para cá.
+
+> **Propósito:** manter os watchdogs do skill `houndsman` alinhados ao que o
+> projeto **realmente aplica** — seja para adicionar/ajustar uma regra a pedido do
+> usuário, seja para uma auditoria geral após mudanças de padrão no código.
+
+Este skill é o **mantenedor** do `houndsman`. Ele não revisa PRs; ele atualiza as regras
+que o `houndsman` usa.
+
+---
+
+## Princípio Fundamental (Regra de Ouro)
+
+> Só é regra o que o projeto **aplica hoje**. Como provar depende da **polaridade** da regra
+> (ver Convenções de escrita, abaixo):
+>
+> - Regra **afirmativa** (`Promover:`): exige a **presença** de um padrão. Ele deve existir no
+>   código; se não existe em lugar nenhum, é `UTOPIAN` (remover/rebaixar).
+> - Regra **negativa** (`Evitar:`, `Não`, `Nunca`): exige a **ausência** de um anti-padrão.
+>   **Zero ocorrências = regra seguida** → **manter**. Nunca remover uma regra negativa só
+>   porque não há ocorrências.
+
+Toda regra nova ou alterada deve vir com **evidência**: `arquivo:linha` (regra afirmativa) ou
+`0 ocorrências via grep X` do anti-padrão (regra negativa). Regra sem evidência é rejeitada ou
+vira `suggestion` explicitamente aprovada pelo usuário.
+
+Ver `AUDIT-PROTOCOL.md` para a taxonomia completa.
+
+---
+
+## Convenções de escrita das regras
+
+Rubrica única — o texto da regra é renderizado **literalmente** no brief do subagente
+(`renderBrief` em `src/core/brief.ts`), então toda ambiguidade vira ruído na revisão.
+Toda regra (nova ou alterada) deve passar por **todos** os itens:
+
+> **Prefixo de polaridade (obrigatório).** Toda regra começa com o sentido do que se espera:
+> `Promover:` → algo que **DEVE** acontecer (a presença do padrão); `Evitar:` → algo que
+> **NÃO DEVE** acontecer (a ausência do anti-padrão); `Não` e `Nunca` no início são
+> equivalentes aceitos de `Evitar:`. Regra sem prefixo explícito é ambígua e o
+> `houndsman doctor` emite um aviso. O prefixo define **um único sentido** por regra —
+> ver *Unipolar* (item 8).
+
+1. **Sujeito explícito** — diz qual artefato é verificado; sem pronome órfão ("o antigo", "isso").
+2. **Condição inequívoca** — duas IAs chegam à mesma conclusão sobre o que é violação.
+3. **Critério concreto** — limite/prazo/lista explícito ou referência a símbolo real do código.
+4. **Geral e reutilizável** — descreve um padrão do **domínio**, não uma regra de negócio pontual
+   que só existe dentro de uma classe/use-case. Regra amarrada a um único ponto do código não é
+   replicável em outros contextos — isso é papel de **teste automatizado**, não do watchdog.
+   - ❌ `Promover: cálculo de taxa deve usar toDecimals` (o cálculo de taxa vive atrás de um único
+     use-case — a regra não se aplica em nenhum outro contexto).
+5. **Sem jargão abreviado ou vago** — sigla/termo/apelido deve estar definido ou ancorado num
+   símbolo/path real do código; nunca um apelido interno sem referência.
+   - ❌ `Evitar que o flow faça parte do grupo` (não se sabe o que é "flow" nem "grupo").
+6. **Sem qualificador vago** — proibido: "apenas por compatibilidade", "período de depreciação",
+   "conjunto real", "completos e corretos", "só faz sentido", "indefinidamente".
+7. **Polaridade explícita** — a regra começa com o sentido inequívoco:
+   - `Promover:` → algo que **DEVE** acontecer (ex.: `Promover: rotas validam a entrada com o schema do Elysia`).
+   - `Evitar:` → algo que **NÃO DEVE** acontecer; `Não` / `Nunca` no início são **equivalentes aceitos** de `Evitar:`.
+8. **Unipolar (um só sentido)** — a regra expressa **uma única direção**, a mesma do prefixo:
+   só afirmações de **promover** ou só afirmações de **evitar**. Não combine "faça X" **e**
+   "não faça Y" na mesma regra — são dois juízos independentes, com veredito e evidência
+   próprios. Regra que precisa dos dois sentidos **vira duas regras**: uma `Promover:` e
+   outra `Evitar:`.
+   - ❌ `Evitar: o handler valida a entrada e não acessa o banco direto` (afirmação + negação).
+   - ✅ `Promover: o handler valida a entrada com o schema do Elysia` **+**
+     `Evitar: o handler acessa o banco direto`.
+   - Exceção **aceitável**: quando os dois sentidos são **inseparáveis** (a negação é condição
+     direta da afirmação). Aí o prefixo lidera o sentido dominante e o outro entra como oração
+     subordinada — nunca como segundo juízo coordenado.
+9. **Escopo coerente** — a regra pertence ao domínio do watchdog.
+10. **Sem duplicata** — nenhuma regra repetida literalmente no mesmo watchdog.
+
+> O `houndsman doctor` emite um **aviso** (não bloqueante) para regra sem polaridade explícita
+> (`Promover:`, `Evitar:`, `Não` ou `Nunca`).
+
+---
+
+## Quando Usar
+
+- Usuário pede para **adicionar / alterar / remover** uma regra de revisão.
+- Um watchdog está gerando **falso positivo** (cobra padrão não aplicado).
+- O projeto mudou de padrão (ex.: passou a usar uma lib, mudou autenticação, etc.).
+- **Auditoria completa** dos watchdogs após revisão geral do código.
+- **Regra confusa/ambígua** (humano ou IA não entende) — ver Modo C.
+- O usuário invoca `/houndsman-update`.
+
+---
+
+## Arquivos que definem a revisão
+
+> A primeira parte é a **camada de projeto** (muda por consumidor); a segunda é o **motor**
+> (o pacote `@payconductor/houndsman`).
+
+| Arquivo | Papel |
+|---|---|
+| `.houndsman/watchdogs/<id>.ts` | **Fonte de verdade**: `defineWatchdog` com `rules` (severidade + texto), `scope`, `description`, `reviewFocus`, `exclude`, `breakingChange`, `contextFiles`, `classify` |
+| `.houndsman/watchdogs/index.ts` | `WATCHDOG_DEFINITIONS` — as **chaves definem os ids** (`WatchdogId`); `watchdogIds` é derivado |
+| `houndsman.config.ts` | `houndsmanConfig` do projeto — `projectName`, `artifactDir`, `watchdogs`, `exclusions`, `docMappings` (descoberto em runtime) |
+| `.houndsman/exclusions.ts` | `EXCLUSION_PATTERNS` + `isExcluded` |
+| `.houndsman/doc-mappings.ts` | `DOC_MAPPINGS` (path → docs) |
+| `.houndsman/core/types.ts` | Snapshot gerado dos tipos + helpers (autocontido) |
+| `src/core/types.ts` | Tipos genéricos: `Severity`, `Rule`, `WatchdogDefinition`, `defineWatchdog` |
+| `src/core/config.ts` | `HoundsmanConfig<TId>` + `defineHoundsmanConfig` (contrato do motor) |
+| `src/core/config-loader.ts` | Descoberta/carregamento de `houndsman.config.ts` |
+| `src/core/brief.ts` | Render do brief: `defaultRenderBrief` + `PROCEDURE` |
+| `src/core/registry-check.ts` | Validação anti-drift (config-driven) |
+| `src/skill/houndsman.md` | Orquestração + tabela de watchdogs |
+| `src/tests/**` | Suíte da lib (project-agnóstica; usa `fixtures/fake-project.ts`) |
+| `src/cli/index.ts` | **CLI único** — `houndsman [context, setup, doctor, test, watchdog, --finalize]` |
+
+> Todo o markdown canônico vive em `src/skill/` (fonte única). Os `SKILL.md` de cada harness
+> são apenas ponteiros — não duplicar conteúdo.
+
+---
+
+## Severidade
+
+| Severidade | Quando usar |
+|---|---|
+| `blocking` | Violação que quebra contrato, segurança ou integridade — e o projeto **já faz** do jeito certo em todos os lugares |
+| `attention` | Boa prática aplicada na maior parte do código, com exceções aceitáveis |
+| `suggestion` | Recomendação aplicada parcialmente; nunca bloqueia |
+| `nit` | Detalhe cosmético/observação; ruído, nunca bloqueia |
+
+> Severidade não é aspiração: se o projeto só aplica o padrão em 15/72 lugares, é `suggestion`.
+
+---
+
+## Pré-análise Jev (opcional)
+
+Regra que deve ser verificada automaticamente antes da revisão declara `jev`. É sempre um
+**objeto** com `kind` obrigatório — a presença de `jev` não é um liga/desliga do Jev:
+
+| Campo | Obrigatório | Uso |
+|---|---|---|
+| `kind` | ✅ | `noul` (a violação ocorre?), `choice` (opções) ou `score` (rubrica) |
+| `instructions` | — | Pergunta customizada; omitida, é derivada do texto da regra |
+| `criteria` | em `choice`/`score` | Objeto `{ valor: rótulo }` para `choice`; lista de rótulos para `score` |
+
+```ts
+{ severity: "blocking", text: "Import de TypeBox direto", jev: { kind: "noul" } }
+{ severity: "attention", text: "Repository com lógica", jev: { kind: "noul", instructions: "O repository tem lógica de negócio?" } }
+```
+
+Não anotar todas as regras: o Jev custa uma chamada por arquivo. Reservar para as regras
+verificáveis por leitura local. Candidatos não confirmados pelo watchdog **não bloqueiam**.
+
+---
+
+## Modo A — Ajuste pontual (pedido do usuário)
+
+1. **Interpretar o pedido** — extrair: qual regra, qual watchdog, adicionar/alterar/remover.
+2. **Identificar o watchdog** pelos paths de `classify` da camada de projeto. Em dúvida, perguntar.
+3. **Provar no código** (Regra de Ouro):
+   - `grep_search` pelo padrão real e pelo anti-padrão.
+   - Determinar a **polaridade**: afirmativa (`Promover:` → exige presença; ausência = `UTOPIAN`) ou
+     negativa (`Evitar:`/`Não`/`Nunca` → exige ausência; **0 ocorrências do anti-padrão = `ALIGNED`**).
+   - Classificar: `ALIGNED`, `UTOPIAN`, `OUTDATED`, `MISCALIBRATED` ou `DEAD-PATH`.
+   - Coletar a evidência (`file:line` afirmativa; `0 ocorrências via grep X` negativa).
+4. **Editar `.houndsman/watchdogs/<id>.ts`** (`WATCHDOG_DEFINITIONS[<id>]`):
+   - `rules`: uma entrada `{ severity, text }` por regra — o texto começa com `Promover:` (DEVE) ou
+     `Evitar:`/`Não`/`Nunca` (NÃO DEVE), conforme as Convenções de escrita.
+   - Regra que mistura afirmação e negação (dois sentidos) → dividir em **duas entradas** (*Unipolar*, item 8).
+   - `jev` (opcional): `{ kind: "noul" }`, com `instructions` e/ou `criteria` — ver seção acima.
+   - Ajustar `scope` / `description` / `reviewFocus` / `exclude` / `contextFiles` se necessário.
+   - Se a regra muda para outro domínio (paths), ajustar o `classify` do watchdog.
+5. **Watchdog novo?** criar `.houndsman/watchdogs/<id>.ts` e registrar em `.houndsman/watchdogs/index.ts` (o id é derivado das chaves).
+6. **Atualizar `src/skill/houndsman.md`/`README.md`** se escopo/regra visível mudou (no motor).
+7. **Atualizar a suíte da lib** se o comportamento do MOTOR mudou (a suíte é project-agnóstica).
+8. **Verificar** (seção abaixo).
+
+---
+
+## Modo B — Auditoria completa (revisão geral do código)
+
+Para alinhar **todos** os watchdogs de uma vez.
+
+1. **Fase 0 — Preparação.** Criar `.houndsman-audit/<slug>/` e copiar/adequar `AUDIT-PROTOCOL.md`.
+2. **Fase 1 — Auditoria por watchdog (subagentes, 1 por watchdog, em ondas paralelas).**
+   Cada subagente recebe: `WATCHDOG_DEFINITIONS[<id>]` + `src/core/brief.ts` (`PROCEDURE`) +
+   fontes ground-truth do projeto (ex.: `AGENTS.md`, docs de arquitetura) + código real.
+   Saída: `<slug>/<id>.md` com ground-truth do domínio + tabela regra × veredito × evidência × ação.
+3. **Fase 2 — Consolidação.** Merge em `audit-summary.md`; agrupar temas transversais; resolver
+   regras duplicadas entre watchdogs.
+4. **Fase 3 — Alinhamento com o usuário.** Apresentar remoções/correções borderline e obter
+   aprovação **antes** de editar (regra utópica → remover; parcial → `suggestion`).
+5. **Fase 4 — Aplicar.** Editar `.houndsman/watchdogs/*.ts` + `.houndsman/**` + `src/skill/**` + testes.
+6. **Fase 5 — Verificar** (seção abaixo).
+
+> Detalhes de taxonomia, formato de relatório e evidência: `AUDIT-PROTOCOL.md`.
+
+---
+
+## Modo C — Revisão de clareza das regras
+
+Alinha o **texto** das regras (não a semântica) para que humano e IA interpretem igual.
+As regras são renderizadas **literalmente** nos briefs dos subagentes (`renderBrief` em
+`src/core/brief.ts`) — o texto da regra é exatamente o que a IA lê.
+
+A rubrica é a seção **Convenções de escrita das regras** (acima). Toda regra deve passar por
+todos os itens — em especial: **geral/reutilizável** (não regra de negócio pontual),
+**sem jargão abreviado**, **polaridade explícita** (`Promover:` / `Evitar:`/`Não`/`Nunca`) e
+**unipolar** (um só sentido por regra — sem afirmar e negar no mesmo texto).
+
+### Passos
+
+1. Inventariar todas as regras (`rules`) dos watchdogs alvo.
+2. Marcar cada regra contra a rubrica; propor reescrita **preservando semântica e severidade**.
+   Regra que mistura os dois sentidos → **dividir** em afirmativa e negativa (*Unipolar*, item 8).
+3. Se for regra **afirmativa** ambígua **e não houver evidência de aplicação** no código,
+   tratá-la como `UTOPIAN`/`OUTDATED` (remover/rebaixar) conforme a Regra de Ouro.
+   Para regra **negativa**, a ausência de ocorrências é o **esperado** — não remover por isso.
+4. Aplicar em `.houndsman/watchdogs/<id>.ts`; corrigir duplicatas/sobreposições.
+5. Se o termo citado for do procedimento, ajustar `PROCEDURE`/`reviewFocus`/`exclude` em
+   `src/core/brief.ts` ou no watchdog.
+6. Conferir que o `renderBrief` continua renderizando o texto da regra (dry-run abaixo).
+7. Verificar (seção abaixo).
+
+---
+
+## Verificação (obrigatória)
+
+```bash
+bun run houndsman doctor     # config sem drift + ambiente
+bun run houndsman test       # suíte da lib (project-agnóstica)
+bun run ci:fix               # formatação/imports/lint (no repo da lib)
+bun run ci:check             # tipagem (no repo da lib)
+```
+
+Checklist final:
+
+- [ ] `bun run houndsman doctor` → sem problemas reportados.
+- [ ] `bun run houndsman test` → **0 fail**.
+- [ ] `ci:fix` + `ci:check` → exit 0 (warnings pré-existentes não contam).
+- [ ] `WATCHDOG_DEFINITIONS[<id>].id` bate com a chave e `description` não vazio.
+- [ ] `src/skill/houndsman.md` continua consistente com os watchdogs do projeto.
+- [ ] Toda regra nova/alterada tem **evidência** registrada no PR/relatório
+      (`file:line` se afirmativa; `0 ocorrências do anti-padrão` se negativa).
+- [ ] Nenhuma regra **negativa** foi removida por "0 ocorrências" (Regra de Ouro).
+- [ ] Brief de amostra não contém regra removida (dry-run abaixo).
+- [ ] Toda regra passa nas convenções de escrita (geral/reutilizável, sem jargão abreviado,
+      sem qualificador vago, com polaridade explícita e **unipolar**) — conferir via grep.
+
+```bash
+# Dry-run: gerar briefs e conferir ausência de regras removidas
+bun -e "import { renderBrief } from 'houndsman'; import { WATCHDOG_DEFINITIONS } from './.houndsman/watchdogs'; const base={files:['x.ts'],branch:'t',outputPath:'o.json',docs:[],statuses:{},deleted:[]}; for (const id of Object.keys(WATCHDOG_DEFINITIONS)) console.log(id, /verifySignature|circuit|saldo/i.test(renderBrief(WATCHDOG_DEFINITIONS[id],{...base,watchdogId:id})) ? 'FOUND' : 'OK');"
+```