@payconductor/houndsman 0.0.0-stage → 0.1.1

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 + credencial Jev
+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');"
+```

package/src/skill/houndsman.md

@@ -0,0 +1,316 @@
+# houndsman — {{projectName}} (v1)
+
+> **Documento canônico do skill `/houndsman`.** Os `SKILL.md` de cada harness
+> (`.agents/skills/houndsman/` e `.claude/skills/houndsman/`) são apenas ponteiros para cá.
+
+Revisão de PR: classificação de arquivos → revisão paralela por domínio → consolidação.
+O motor é o CLI **`houndsman`**; as regras do projeto ficam em `houndsman.config.ts` + `houndsman/`.
+
+**Terminologia:** **houndsman** = orquestrador/treinador (CLI + motor); **watchdog** = cada agente
+especialista por domínio que audita o diff (antigo "revisor"); **review/revisão** = o processo;
+**Jev** = pré-análise opcional (Passo 1.5).
+
+## Quem executa o quê
+
+- **Você** só invoca o skill: `/houndsman`. Não precisa rodar nenhum script à mão.
+- **O skill** orquestra: executa o CLI `houndsman` e despacha os subagentes.
+- **O CLI** tem passos distintos, um comando cada:
+
+| Passo | Comando | Quem roda | Resultado |
+|---|---|---|---|
+| 0. Contexto | `houndsman context` | subagente | `context.json` + `context-brief.md` → `context-summary.json` |
+| 1. Preparar | `houndsman` | skill | `classification.json` + `candidates.json` + `briefs/` + `manifest.json` |
+| 2. Revisar | *(subagentes)* | skill (via `runSubagent`) | `findings/<watchdog>.json` (um por watchdog) |
+| 3. Finalizar | `houndsman --finalize` | skill | `review.md` |
+
+> Por que comandos separados? Entre o passo 1 e o 3 acontece trabalho de LLM (os subagentes).
+
+**Arquitetura:**
+
+- N watchdogs especializados por domínio de negócio.
+- **Cada watchdog declara o que revisa** (`classify` em `.houndsman/watchdogs/<id>.ts`:
+  `{ type?: "filename" | "content", value }` — `value` é sempre regex; `filename`
+  (padrão) casa o caminho, `content` casa o conteúdo do arquivo). Não há arquivo de
+  classificação à parte nem fallback: arquivo fora dos padrões fica `unclassified`.
+- **Fonte única de verdade do projeto:** `houndsman.config.ts` (`HoundsmanConfig`) +
+  `.houndsman/` (`watchdogs/<id>.ts`: regras + escopo + foco + `classify`;
+  `exclusions.ts`: filtros; `doc-mappings.ts`: docs).
+- **O motor genérico** vive no pacote `@payconductor/houndsman` (`core/` + `cli/`). O markdown
+  do skill vive em `src/skill/`.
+- **As regras refletem os padrões APLICADOS hoje** — não validar práticas que o projeto
+  não adota. Regra sem aplicação real no código gera falso positivo.
+- Cada watchdog recebe apenas seus arquivos relevantes (brief pronto) — nunca o diff completo.
+- Saída estruturada (JSON) por watchdog → consolidada e deduplicada automaticamente.
+
+## Quando Usar
+
+- Revisar PR antes de merge
+- Code review de feature branch
+- Validar mudanças antes de push
+
+---
+
+## Passo 0 — Contexto da PR (subagente)
+
+O contexto vem da **descrição da PR** via GitHub CLI (`gh`), quando disponível e logado.
+Um subagente executa o CLI e resume:
+
+```
+Você é o subagente de contexto do houndsman. Execute `houndsman context`;
+leia o `context-brief.md` indicado na saída; siga as instruções e grave
+`context-summary.json`. Retorne `objective`/`motivation`/`changeSummary` ou "indisponível".
+```
+
+- O CLI detecta `gh` (**ausente/sem login/sem PR** → grava `available:false` e sai com código 0).
+- O subagente resume em `context-summary.json`: `objective` (1 frase, ≤ 200 chars),
+  `motivation` (1 frase, ≤ 240 chars) e `changeSummary` (≤ 4 bullets, ≤ 160 chars cada),
+  em pt-BR e baseado **somente** no `context.json`. **Curto de propósito.**
+- Sem contexto → a revisão segue normalmente e a seção é omitida (registrado no `manifest.json`).
+
+---
+
+## Passo 1 — Preparar (skill executa)
+
+```bash
+houndsman --base main
+```
+
+Gera em `.houndsman/.runs/<branch-slug>/`:
+
+| Artefato | Conteúdo |
+|---|---|
+| `classification.json` | Watchdogs ativados por arquivo + status (A/M/D/R) + churn |
+| `candidates.json` | Indícios da pré-análise Jev (regra + arquivo + confiança) |
+| `briefs/<watchdog>.md` | Instruções prontas para cada subagente (arquivos por risco) |
+| `manifest.json` | Resumo: watchdogs, arquivos, deletados, status, contexto, Jev, orçamento |
+
+**Excluídos automaticamente:** lock files, `dist/`, `build/`, `.env*`, imagens, source
+maps (padrões do projeto em `.houndsman/exclusions.ts`).
+**Deletados:** não entram como conteúdo; vão para o brief de watchdogs com
+`breakingChange` como candidatos a **breaking change**.
+
+### Orçamento por brief (PRs grandes)
+
+O motor coleta o diff **uma única vez** (`git diff` + `git diff --numstat`) e classifica
+com **churn** (linhas adicionadas/removidas) por arquivo — o custo não cresce com o nº de
+arquivos da PR. Cada brief recebe no máximo `budgets.maxFilesPerBrief` arquivos (default 40),
+**priorizados pelo maior churn**:
+
+- O excedente vai para a seção **Fora do orçamento (NÃO revisar)** do brief e o watchdog deve
+  registrá-lo em `skipped` — a tabela de **Cobertura** mostra o que ficou de fora (nunca some
+  silenciosamente).
+- Isso mantém o contexto do subagente limitado mesmo num PR de 10k linhas com centenas de
+  arquivos num único domínio.
+- Ajuste em `houndsman.config.ts`: `budgets: { maxFilesPerBrief: 60 }` e
+  `concurrency: { jev: 8 }`. Valores não-positivos caem no default (o `doctor` avisa).
+
+### Pré-análise Jev (Passo 1.5, opcional)
+
+Se `TYPESAFE_API_KEY` estiver definida, cada arquivo é avaliado pelo modelo **Jev** contra
+as regras atômicas dos watchdogs. Respostas acima do limiar viram **candidatos** em
+`candidates.json` e entram no brief como *warm start* — o subagente **confirma ou refuta**.
+
+- **Não é achado**: candidatos não bloqueiam.
+- **Opcional**: sem chave / erro / timeout → `available:false`; a revisão segue idêntica.
+- Desativar: `houndsman --no-jev`.
+
+---
+
+## Passo 2 — Revisar (skill despacha os subagentes)
+
+Um subagente por brief. Despache em **ondas** (ex.: até 8 subagentes por bloco de tool
+calls) — evita estourar limites de taxa quando há muitos watchdogs. O prompt é o próprio brief:
+
+```
+Leia e execute o brief: .houndsman/.runs/<branch-slug>/briefs/<watchdog-id>.md
+Você é o watchdog <watchdog-id> do {{projectName}}.
+```
+
+Cada subagente grava `findings/<watchdog-id>.json` (schema `.houndsman/core/skill/OUTPUT-FORMAT.md`).
+Sem achados → `"findings": []` (arquivo obrigatório). Arquivos na seção **Fora do orçamento**
+não são lidos: registre-os em `skipped`.
+
+**NUNCA enviar:** `git diff` completo · histórico de commits · arquivos de outros domínios ·
+`AGENTS.md` completo (já está no contexto global).
+
+---
+
+## Passo 3 — Finalizar (skill executa)
+
+```bash
+houndsman --finalize
+```
+
+Falha com mensagem clara se faltar algum `findings/<watchdog>.json`. Quando todos existem:
+1. Valida o schema de cada JSON
+2. Deduplica achados por `(file, line, rule)` mesclando watchdogs sobrepostos
+3. Agrupa por severidade: ❌ blocking > ⚠️ attention > 💡 suggestion > 🔎 nit
+4. Grava `.houndsman/.runs/<branch-slug>/review.md` + tabela de cobertura
+5. Anexa os candidatos Jev não confirmados em `🔎 Candidatos não verificados` (não bloqueiam)
+6. Agrupa os achados **por arquivo** dentro de cada severidade (navegabilidade em PRs grandes)
+7. Grava um `review.<watchdog>.md` por watchdog com achados e indexa no `review.md`
+   (**Relatórios por domínio**) — mantém o relatório consolidado enxuto
+8. Grava `.houndsman/.runs/<branch-slug>/state.json` — a **triagem**: um `id` curto e um
+   `fingerprint` de conteúdo por finding (Passo 4), preservados entre execuções
+
+> Compatível com `classification.json` antigo: se faltar o churn, o orçamento não é aplicado.
+
+---
+
+## Passo 4 — Triagem (opcional)
+
+Cada finding recebe um `id` curto e um `fingerprint` de **conteúdo** no `--finalize`,
+gravados em `.houndsman/.runs/<branch-slug>/state.json`. A triagem é feita pela UI ou
+pelo agente — sem editar o JSON à mão. Duas dimensões independentes:
+
+- **decision:** `pending` · `execute` · `ignore` (+ `comment` opcional).
+- **execState:** `pending` · `in_progress` · `done` · `stale`.
+
+### UI local
+
+```bash
+houndsman server --open
+```
+
+Abre a UI (Bun.serve + Preact): lista as runs, triar os findings por severidade, comentar,
+marcar como feito e ler os artefatos (`manifest.json`, `classification.json`, `review.md`).
+Bind em `127.0.0.1` (ferramenta local, sem auth).
+
+### Auto-fix pelo agente
+
+```bash
+houndsman findings list --decision execute --json   # pendentes marcados p/ corrigir
+# ... o agente aplica as correções ...
+houndsman findings sync                             # reancora por conteúdo
+houndsman findings done <id>                        # confirma os concluídos
+```
+
+> **A linha não é a identidade.** O auto-fix desloca linhas; o motor reancora cada finding
+> pelo **conteúdo** (trecho + contexto) e não perde itens que se movem. Se a âncora some
+> (o trecho foi corrigido), o finding vira `done` automaticamente quando a decisão era
+> `execute`, ou `stale` caso contrário.
+> Ocorrências byte-idênticas (mesmo trecho E mesmo contexto) compartilham o id — são
+> tratadas como um grupo (`×N`); limitação conhecida.
+
+---
+
+## Estrutura do Relatório
+
+```markdown
+# Review — [branch]
+
+**Data:** YYYY-MM-DD
+**Watchdogs ativos:** [lista]
+**Achados:** N bloqueantes · N atenção · N sugestões · N nits
+
+## Contexto da PR
+**PR:** #123 Título — url
+**Branch:** `feature/x` → `main`
+**Objetivo:** ...
+**Resumo das alterações:**
+- ...
+
+## ❌ blocking
+### `src/routes/order-route.ts`
+- **<regra>** — `src/routes/order-route.ts:5` · _<watchdogs>_
+  <mensagem>
+  **Ação:** <ação>
+
+## 🔎 Candidatos não verificados (Jev)   ← se houver
+
+## Relatórios por domínio
+| Watchdog | Achados | Revisados | Relatório |
+|---|---|---|---|
+
+## Cobertura
+| Watchdog | Arquivos revisados | Findings |
+|---|---|---|
+
+## Conclusão
+**Status:** ✅ Aprovado / ⚠️ Aprovado com Ressalvas / ❌ Mudanças Necessárias
+```
+
+---
+
+## Fluxo Completo
+
+```
+houndsman context (gh)         ──►  context.json ──► subagente ──► context-summary.json
+        ↓
+git diff --name-status (base...head)
+        ↓
+[1] houndsman                  ──►  classification.json + candidates.json + briefs/ + manifest.json
+        ↓
+[2] N subagentes em paralelo   ──►  findings/<watchdog>.json
+        ↓
+[3] houndsman --finalize       ──►  review.md + state.json
+        ↓
+[4] triagem (UI ou agente)     ──►  state.json (decision/execState)
+```
+
+---
+
+## Invocação
+
+```
+/houndsman
+/houndsman feature/add-webhook-retry
+```
+
+Se a branch não for informada, detecta com `git branch --show-current`. Base do diff: `main`.
+
+**Comandos do CLI:**
+
+| Comando | Função |
+|---|---|
+| `houndsman context` | Passo 0 — contexto da PR via `gh` |
+| `houndsman` | Passo 1 — preparar (briefs + manifesto) |
+| `houndsman --finalize` | Passo 3 — gerar o relatório |
+| `houndsman watchdog <id>` | Contexto de um watchdog (`--json`, `--rules`) |
+| `houndsman findings <sub>` | Triagem dos findings (list/show/set/done/reset/sync/summary/path) |
+| `houndsman server` | UI local de triagem + leitura de artefatos (`--port`, `--host`, `--open`) |
+| `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 |
+| `houndsman test` | Suíte de testes da lib |
+
+---
+
+## Anti-padrões
+
+- ❌ Enviar git diff completo para qualquer watchdog
+- ❌ Ativar watchdogs sem arquivos no seu domínio
+- ❌ Revisar arquivos marcados como **Fora do orçamento** (registre-os em `skipped`)
+- ❌ Carregar documentação que o watchdog não precisa
+- ❌ Revisar arquivos gerados (lock files, builds, migrations)
+- ❌ Escrever markdown livre em vez do JSON de `OUTPUT-FORMAT.md`
+- ❌ Revisar arquivos `deleted` (não têm conteúdo) em vez de tratá-los como breaking change
+- ❌ Comentários genéricos ("código bom", "pode melhorar")
+- ❌ Sugestões de estilo triviais
+- ❌ Reescrever código completo — apenas apontar direção
+- ❌ Inventar objetivo/motivação da PR — o resumo vem **só** do `gh`; sem `gh`, omitir a seção
+
+---
+
+## Manutenção das Regras
+
+> Alterar qualquer regra (adicionar, ajustar severidade, remover, corrigir escopo) → usar o
+> skill **`houndsman-update`** (`src/skill/houndsman-update.md`).
+> Regra de ouro: só é regra o que o projeto **aplica hoje** — prove com evidência no código
+> (regra negativa com 0 ocorrências = seguida → **manter**).
+> Após qualquer alteração, rodar `houndsman doctor` + `houndsman test` + `ci:fix` + `ci:check`.
+
+---
+
+## Performance Esperada
+
+| Tamanho do PR | Watchdogs | Tempo |
+|---|---|---|
+| Pequeno (500 linhas) | 2-4 | ~30-60s |
+| Médio (5k linhas) | 4-7 | ~1-2 min |
+| Grande (50k linhas) | 7-10 | ~3-5 min |
+| Enorme (300k linhas) | 10-15 | ~5-8 min |
+
+> O custo de coleta é **constante** (2 execuções de `git`), independente do nº de arquivos.
+> Em PRs muito grandes, o limitante é o nº de subagentes (ondas) e o orçamento por brief —
+> não o diff. Ajuste `budgets.maxFilesPerBrief` para revisar mais/menos arquivos por domínio.