@payconductor/houndsman 0.1.0 → 0.1.3

package/src/skill/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: houndsman
+description: 'Revisa Pull Requests com watchdogs especializados por domínio de negócio e mantém essas regras alinhadas ao projeto. Use para revisar/code review de PR, atualizar as regras de revisão dos watchdogs e corrigir/verificar os findings da revisão. Capabilities: `hunt` (revisar a PR), `train` (atualizar regras), `fix` (corrigir achados), `verify` (violações resolvidas?).'
+argument-hint: 'Capability: hunt | train | fix | verify (default: hunt)'
+---
+
+# houndsman — {{projectName}}
+
+O **houndsman** revisa Pull Requests com **watchdogs** — agentes especialistas por domínio de
+negócio. Cada watchdog audita a parte do diff que é sua e grava **findings** (achados); o motor
+consolida tudo num relatório. O motor é o CLI **`houndsman`**; as regras do projeto vivem em
+`houndsman.config.ts` + `.houndsman/`.
+
+**Terminologia:** **houndsman** = orquestrador/treinador (CLI + motor) · **watchdog** = agente
+especialista por domínio · **finding** = um achado da revisão · **Jev** = pré-análise opcional.
+
+## Capabilities
+
+| Capability | Objetivo | Documento |
+|---|---|---|
+| **`hunt`** | Revisar uma Pull Request e produzir o relatório de achados. | `.houndsman/core/skill/hunt.md` |
+| **`train`** | Manter as regras dos watchdogs alinhadas ao que o projeto aplica. | `.houndsman/core/skill/train.md` |
+| **`fix`** | Corrigir os achados de uma revisão já finalizada. | `.houndsman/core/skill/fix.md` |
+| **`verify`** | Conferir se as violações foram resolvidas, sem re-revisar a PR. | `.houndsman/core/skill/verify.md` |
+
+## Invocação
+
+```
+/houndsman              → hunt (default)
+/houndsman hunt         → revisar a Pull Request
+/houndsman train        → atualizar as regras dos watchdogs
+/houndsman fix          → corrigir os findings
+/houndsman verify       → conferir se as violações foram resolvidas
+```
+
+Um argumento extra é o alvo da capability (ex.: `/houndsman hunt feature/minha-branch`).
+Escolha a capability pelo que o usuário quer, leia o documento correspondente em
+`.houndsman/core/skill/<capability>.md` e siga-o.
+
+> **Depois de revisar (`hunt`), valide na UI:** `bun run houndsman server --open` — revise os
+> achados e marque os que devem ser executados (`execute`) antes de rodar `fix`.
+
+## Referências
+
+- `.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.

package/src/skill/fix.md

@@ -0,0 +1,206 @@
+# houndsman — {{projectName}} · `fix` (correção dos findings)
+
+> **Documento canônico da capability `fix`.** O entry point do skill é o `SKILL.md`
+> (`.agents/skills/houndsman/SKILL.md` e `.claude/skills/houndsman/SKILL.md`).
+
+Corrige os achados de uma revisão **já finalizada** (`hunt`): lê a triagem, aplica as
+correções marcadas e mantém o estado de triagem em dia — **sem editar o `state.json` à mão**.
+
+Invocação: `/houndsman fix`. Não revisa nem altera regras; consome o que o `hunt` produziu.
+
+**Quando usar:**
+
+- Depois de `/houndsman` (ou `houndsman --finalize`), para corrigir os achados.
+- O usuário marcou achados como `execute` na UI (`bun run houndsman server --open`) ou via
+  `findings set <id> --decision execute`.
+- "Corrija os findings", "aplica as correções", "resolve os bloqueantes".
+
+> **Pré-requisito:** existe `.houndsman/.runs/<branch-slug>/state.json` da run atual
+> (gerado no `--finalize`). Se não existir, a revisão não foi finalizada — rode o `hunt` antes.
+> A triagem (`execute`) é feita na UI (`bun run houndsman server --open`) ou via `findings set`,
+> e é o que alimenta a fila de correção.
+
+---
+
+## Modelo de triagem
+
+Cada finding tem duas dimensões independentes (ver `findings-state.ts`):
+
+- **decision:** `pending` · `execute` · `ignore` (+ `comment` opcional).
+- **execState:** `pending` · `in_progress` · `done` · `stale`.
+
+`fix` atua **somente** sobre `decision: execute`. Achados `pending` (ainda não triados) e
+`ignore` (descartados) ficam intocados — não "conserte" o que o usuário não pediu.
+
+> **A linha de um finding não é a identidade.** A identidade é o **fingerprint** de conteúdo
+> (arquivo + regra + âncora). As correções deslocam linhas; o motor reancora pelo conteúdo.
+> Ocorrências byte-idênticas (mesmo trecho E mesmo contexto) compartilham o id — tratadas
+> como um grupo (`×N`); corrigir uma resolve o grupo.
+
+---
+
+## Procedimento (incremental — nunca de uma vez)
+
+Em PRs grandes há muitos achados. **Nunca** carregue a fila inteira: o `batch` entrega um
+**grupo coeso, já paginado**, e a fila avança sozinha conforme você conclui os itens.
+
+```
+repita:
+  1. findings summary --json        # contagem barata da fila
+  2. fila vazia? → fim
+  3. findings batch --json          # grupo atual + outros grupos (sem parâmetros)
+  4. corrigir APENAS o grupo atual
+  5. findings sync                  # reancora por conteúdo (uma vez)
+  6. findings done <ids> | set --decision pending --comment <motivo>
+até a fila esvaziar
+```
+
+### 1. Medir a fila
+
+```bash
+bun run houndsman findings summary --json
+```
+
+`byDecision.execute` (menos os `done`) é o tamanho da fila. Se for `0`, acabou.
+
+### 2. Pegar o lote (contexto para correção)
+
+```bash
+bun run houndsman findings batch --json
+```
+
+O `batch` decide sozinho o **melhor agrupamento** para a run atual (por arquivo, por regra ou
+por watchdog) e devolve:
+
+- o **grupo atual** (paginado) — a unidade de trabalho;
+- a lista dos **outros grupos disponíveis**;
+- os totais (`fila`, `retornados`, `grupos`).
+
+Sem parâmetros, ele devolve **o primeiro grupo**. Como a fila exclui o que já está `done`,
+cada chamada após progresso traz **o próximo grupo naturalmente** — não há contador para
+gerenciar.
+
+Flags (use só quando precisar — o mínimo de decisão):
+
+| Flag | Quando usar |
+|---|---|
+| `--severity blocking` | Só os bloqueantes (ex.: "quero corrigir apenas os bloqueantes"). |
+| `--group <key>` | Focar um grupo específico (a key aparece em "outros grupos"). |
+| `--offset <n>` | Paginar dentro de um grupo grande. Raramente necessário. |
+| `--include-done` | Auditar/rever itens já concluídos. |
+
+### 3. Corrigir apenas o grupo atual
+
+Para cada finding do grupo: abra o arquivo, leia o trecho ancorado (`line` é cache; confirme
+pelo conteúdo) e aplique a **correção mínima** que satisfaz a `rule`, seguindo a **`action`** e
+a `evidence`. Respeite o padrão que o watchdog cobra — não introduza um novo anti-padrão para
+"calar" o finding. Marque antes: `findings set <id> --exec in_progress`.
+
+**Contexto grande? Use um subagente** (ver abaixo) para o grupo — um grupo por vez.
+
+### 4. Reancorar o estado
+
+```bash
+bun run houndsman findings sync
+```
+
+O `sync` reancora cada finding por **conteúdo** (trecho + contexto) e reporta `ok` / `moved` /
+`stale`: âncora corrigida → vira `done` (quando a decisão era `execute`); âncora sumida de
+outro modo → `stale` (revisar).
+
+### 5. Confirmar ou devolver
+
+Antes de fechar, confirme com o `verify` (barato): ele diz o que **resolveu** (`resolved`), o que
+**persiste** e o que ficou **incerto** — sem re-revisar a PR. Com `--apply`, os `resolved` viram
+`done` automaticamente.
+
+```bash
+bun run houndsman findings verify            # relatório (não altera o estado)
+bun run houndsman findings verify --apply     # marca os resolvidos como done
+bun run houndsman findings done <id...>              # corrigidos (manual)
+bun run houndsman findings set <id> --decision pending --comment "<motivo / falta>"  # não corrigidos
+```
+
+Não deixe achado `execute` no limbo. `--decision ignore` só quando o achado for aceito como
+não-aplicável.
+
+### 6. Repetir
+
+Volte ao passo 1. A fila encolhe a cada volta; o `batch` traz o próximo grupo sem `--offset`.
+
+---
+
+## Perguntas de decisão ao usuário
+
+Pergunte (ferramenta de perguntas do harness) **antes** de corrigir quando o achado for:
+
+- ambíguo ou com **múltiplas correções válidas**;
+- uma mudança de **produto/arquitetura** (não é "só código");
+- conflitante com outro achado/grupo.
+
+Apresente o achado (`rule`, `message`, `action`, `evidence`) e as opções. Com a resposta,
+registre-a: `findings set <id> --comment "<decisão>"`. Sem resposta, devolva à fila com
+`--decision pending --comment "Aguardando decisão: …"` — **nunca "chute"**.
+
+---
+
+## Subagentes — contexto, não velocidade
+
+Subagente serve para **isolar contexto**, não para paralelizar. Regras:
+
+- **Um grupo por vez, em sequência.** Não dispare uma onda paralela: grupos podem editar o
+  mesmo arquivo, arquivos relacionados, imports ou código gerado — correções concorrentes
+  colidem.
+- O subagente recebe **só** o grupo atual (findings + arquivo) e devolve um resumo compacto
+  (ids corrigidos / não corrigidos + motivo). Assim o agente principal não carrega o arquivo.
+- A escrita do `state.json` fica **centralizada no agente principal**: o subagente apenas
+  lê/edita; `sync` / `done` / `set` são do orquestrador. Nada de `findings` dentro do subagente.
+- Grupos pequenos (1–2 findings) o próprio agente corrige inline.
+
+Prompt do subagente (modelo):
+
+```
+Corrija APENAS os findings abaixo, sem tocar em mais nada. Aplique a correção mínima que
+satisfaz cada `rule`, seguindo `action`/`evidence`. Não rode comandos `findings`.
+Retorne: id → corrigido/não corrigido + 1 linha de motivo.
+
+Arquivo: <file>
+- <id> [<severity>] <rule> (linha <line>) — <message>
+  Ação: <action>
+  Evidência: `<evidence>`
+```
+
+---
+
+## Verificação
+
+- `bun run houndsman findings summary` → os corrigidos saíram de `execute`/`in_progress`.
+- `bun run houndsman findings sync` → sem `stale` inesperado.
+- `bun run houndsman findings verify` → o que **resolveu** / **persiste** / ficou **incerto**
+  (sem re-revisar). Use `--apply` para marcar os `resolved` como `done`.
+- Rode o build/testes do **projeto consumidor** (não o houndsman) depois das correções.
+- Se a mudança for grande, reexecute o `hunt` para uma segunda passada:
+
+  ```bash
+  bun run houndsman --base main
+  # ... subagentes ...
+  bun run houndsman --finalize
+  ```
+
+  > O `--finalize` preserva os ids/fingerprints entre execuções (reancoragem por conteúdo);
+  > use `--clean` só quando quiser descartar a triagem anterior.
+
+---
+
+## Anti-padrões
+
+- ❌ Carregar a fila inteira de uma vez (`findings list` sem filtro) — use `findings batch`.
+- ❌ Corrigir vários grupos em paralelo (subagentes simultâneos sobre arquivos que se relacionam).
+- ❌ Editar `.houndsman/.runs/<slug>/state.json` à mão — use os comandos `findings`.
+- ❌ Corrigir findings `pending` ou `ignore` sem o usuário marcar `execute`.
+- ❌ Chavear por `(file, line)` — a confiança é o **fingerprint** de conteúdo.
+- ❌ Correção cosmética para "sumir" com o finding sem atender a `rule`.
+- ❌ Reescrever o arquivo inteiro — correção mínima e localizada.
+- ❌ Inventar mudança de produto/arquitetura para fechar um achado ambíguo — pergunte.
+- ❌ Marcar `done` sem ter aplicado a correção (o `sync` reancora; o achado volta).
+- ❌ Reexecutar o `hunt` inteiro só para conferir o fix — use `findings verify`.

package/src/skill/{houndsman.md → hunt.md}

@@ -1,18 +1,18 @@
-# houndsman — {{projectName}} (v1)
+# houndsman — {{projectName}} · `hunt` (revisão de PR)
 
-> **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á.
+> **Documento canônico da capability `hunt`.** O entry point do skill é o `SKILL.md`
+> (`.agents/skills/houndsman/SKILL.md` e `.claude/skills/houndsman/SKILL.md`).
 
 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/`.
+Invocação: `/houndsman` (default) ou `/houndsman hunt`. 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).
+**Quando usar:** revisar PR antes de merge · code review de feature branch · validar
+mudanças antes de push.
 
 ## Quem executa o quê
 
-- **Você** só invoca o skill: `/houndsman`. Não precisa rodar nenhum script à mão.
+- **Você** só invoca o skill: `/houndsman [hunt]`. 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:
 
@@ -21,9 +21,10 @@ especialista por domínio que audita o diff (antigo "revisor"); **review/revisã
 | 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` |
+| 3. Finalizar | `houndsman --finalize` | skill | `review.md` + `state.json` + `run.json` |
 
 > Por que comandos separados? Entre o passo 1 e o 3 acontece trabalho de LLM (os subagentes).
+> Depois do passo 3, a correção dos achados é a capability **`fix`** — ver `fix.md`.
 
 **Arquitetura:**
 
@@ -42,12 +43,6 @@ especialista por domínio que audita o diff (antigo "revisor"); **review/revisã
 - 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)
@@ -79,16 +74,31 @@ Gera em `.houndsman/.runs/<branch-slug>/`:
 
 | Artefato | Conteúdo |
 |---|---|
-| `classification.json` | Watchdogs ativados por arquivo + status (A/M/D/R) |
+| `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 |
-| `manifest.json` | Resumo: watchdogs, arquivos, deletados, status, contexto, Jev |
+| `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
@@ -96,14 +106,29 @@ as regras atômicas dos watchdogs. Respostas acima do limiar viram **candidatos*
 `candidates.json` e entram no brief como *warm start* — o subagente **confirma ou refuta**.
 
 - **Não é achado**: candidatos não bloqueiam.
-- **Falha-aberto**: sem chave / erro / timeout → `available:false`; a revisão segue idêntica.
+- **Opcional**: sem chave / erro / timeout → `available:false`; a revisão segue idêntica.
 - Desativar: `houndsman --no-jev`.
 
+### Review incremental (da 2ª revisão em diante)
+
+Cada `--finalize` grava o **commit revisado** (`reviewed.headSha` no `state.json`). No prepare
+seguinte, se o `HEAD` descende desse commit (sem rebase), o motor revisa **só o delta** — os
+arquivos alterados desde a última revisão — e **carrega** os findings dos arquivos inalterados
+(carry-over), sem re-revisá-los. O `manifest.json` traz o bloco `incremental` (`from`,
+`changedFiles`, `carried`) e o `review.md` abre com um aviso.
+
+- Sem mudanças desde a última revisão → **no-op** (nada a revisar; o estado é preservado).
+- Rebase/force-push (histórico reescrito) → cai automaticamente no **review completo**.
+- Forçar completo: `houndsman --full` (ou `--clean`, que também descarta a triagem anterior).
+
+> Custo: o LLM só é gasto nos arquivos que mudaram desde a última revisão — não na PR inteira.
+
 ---
 
 ## Passo 2 — Revisar (skill despacha os subagentes)
 
-Um subagente por brief, todos no mesmo bloco de tool calls. O prompt é o próprio brief:
+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
@@ -111,7 +136,8 @@ 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).
+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).
@@ -130,6 +156,14 @@ Falha com mensagem clara se faltar algum `findings/<watchdog>.json`. Quando todo
 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, preservados entre execuções
+
+Após finalizar, corrija os achados com a capability **`fix`** (`fix.md`): a UI ou os
+comandos `findings` levam do achado à correção.
 
 ---
 
@@ -150,10 +184,17 @@ Falha com mensagem clara se faltar algum `findings/<watchdog>.json`. Quando todo
 - ...
 
 ## ❌ blocking
-- **<regra>** — `arquivo:linha` · _<watchdogs>_
+### `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 |
 |---|---|---|
@@ -175,7 +216,11 @@ git diff --name-status (base...head)
         ↓
 [2] N subagentes em paralelo   ──►  findings/<watchdog>.json
         ↓
-[3] houndsman --finalize       ──►  review.md
+[3] houndsman --finalize       ──►  review.md + state.json + run.json (review_done)
+        ↓
+[4] server (UI)                ──►  validar a revisão + marcar decision: execute
+        ↓
+[5] fix                        ──►  correções + state.json/run.json (fix_done)
 ```
 
 ---
@@ -184,23 +229,23 @@ git diff --name-status (base...head)
 
 ```
 /houndsman
-/houndsman feature/add-webhook-retry
+/houndsman hunt
+/houndsman hunt feature/add-webhook-retry
 ```
 
 Se a branch não for informada, detecta com `git branch --show-current`. Base do diff: `main`.
 
-**Comandos do CLI:**
+**Comandos do CLI usados no `hunt`:**
 
 | Comando | Função |
 |---|---|
 | `houndsman context` | Passo 0 — contexto da PR via `gh` |
-| `houndsman` | Passo 1 — preparar (briefs + manifesto) |
+| `houndsman` | Passo 1 — preparar (briefs + manifesto; incremental quando possível) |
 | `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` | Suíte de testes da lib |
+
+Flags do review: `--base` · `--head` · `--branch` · `--dir` · `--clean` · `--full` (força
+completo) · `--no-jev` · `--fail-on-blocking` (com `--finalize`).
 
 ---
 
@@ -208,6 +253,7 @@ Se a branch não for informada, detecta com `git branch --show-current`. Base do
 
 - ❌ 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`
@@ -221,11 +267,11 @@ Se a branch não for informada, detecta com `git branch --show-current`. Base do
 
 ## Manutenção das Regras
 
-> Alterar qualquer regra (adicionar, ajustar severidade, remover, corrigir escopo) → usar o
-> skill **`houndsman-update`** (`src/skill/houndsman-update.md`).
+> Alterar qualquer regra (adicionar, ajustar severidade, remover, corrigir escopo) → capability
+> **`train`** (`/houndsman train`, doc `train.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` (anti-drift) + `houndsman test` + `ci:fix` + `ci:check`.
+> Após qualquer alteração, rodar `houndsman doctor` + `houndsman test` + `ci:fix` + `ci`.
 
 ---
 
@@ -237,3 +283,7 @@ Se a branch não for informada, detecta com `git branch --show-current`. Base do
 | 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.

package/src/skill/{houndsman-update.md → train.md}

@@ -1,14 +1,14 @@
-# Atualização de Lógicas do houndsman
+# houndsman — {{projectName}} · `train` (atualização de regras)
 
-> **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á.
+> **Documento canônico da capability `train`.** O entry point do skill é o `SKILL.md`
+> (`.agents/skills/houndsman/SKILL.md` e `.claude/skills/houndsman/SKILL.md`).
 
 > **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.
+Invocação: `/houndsman train`. Esta capability é a **mantenedora** do `houndsman`.
+Ela não revisa PRs (isso é `hunt`); ela atualiza as regras que o `houndsman` usa.
 
 ---
 
@@ -86,7 +86,7 @@ Toda regra (nova ou alterada) deve passar por **todos** os itens:
 - 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`.
+- O usuário invoca `/houndsman train`.
 
 ---
 
@@ -108,7 +108,7 @@ Toda regra (nova ou alterada) deve passar por **todos** os itens:
 | `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/skill/hunt.md` | Orquestração da revisão (capability `hunt`) |
 | `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]` |
 
@@ -169,7 +169,7 @@ verificáveis por leitura local. Candidatos não confirmados pelo watchdog **nã
    - 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).
+6. **Atualizar `src/skill/hunt.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).
 
@@ -225,19 +225,19 @@ todos os itens — em especial: **geral/reutilizável** (não regra de negócio
 ## Verificação (obrigatória)
 
 ```bash
-bun run houndsman doctor     # config sem drift + ambiente
+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)
+bun run ci                   # 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).
+- [ ] `ci:fix` + `ci` → 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.
+- [ ] `src/skill/hunt.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).

package/src/skill/verify.md

@@ -0,0 +1,70 @@
+# houndsman — {{projectName}} · `verify` (violações resolvidas?)
+
+> **Documento canônico da capability `verify`.** O entry point do skill é o `SKILL.md`
+> (`.agents/skills/houndsman/SKILL.md` e `.claude/skills/houndsman/SKILL.md`).
+
+Confere se os findings de uma revisão **já finalizada** foram resolvidos — **sem re-revisar a
+PR**. Invocação: `/houndsman verify`. Consome o `state.json` do `hunt`; não revisa nem altera
+regras.
+
+**Quando usar:**
+
+- Depois de corrigir achados (`fix`), para confirmar que as violações sumiram.
+- As violações foram resolvidas? · confere se ainda está lá · valida o fix.
+
+> **Pré-requisito:** existe `.houndsman/.runs/<branch-slug>/state.json` (gerado no `--finalize`).
+
+---
+
+## Como funciona (2 tiers)
+
+1. **Tier local (grátis, determinístico).** Para cada finding presente, reancora a âncora de
+   conteúdo contra o working tree (`core/finding-anchor.ts`):
+   - **âncora presente** (`ok`/`moved`) → **persiste** (a violação ainda está lá);
+   - **âncora sumida** (`stale`) → provável **resolvido** — mas o trecho pode ter sido reescrito;
+   - **arquivo ausente** → fora da verificação (deletado/movido).
+
+2. **Tier Jev (opcional, só nos ambíguos).** Com `TYPESAFE_API_KEY`, os casos `stale` / sem
+   âncora são confirmados pelo LLM sobre um **diff focado** do arquivo (`foundAtSha..HEAD`), uma
+   pergunta `noul` por finding. Falha-aberto: sem chave/erro → vale o resultado local.
+
+**Custo:** ~0 LLM quando o tier local decide; 1 chamada por arquivo ambíguo — nunca uma revisão
+completa.
+
+---
+
+## Procedimento
+
+```bash
+bun run houndsman findings verify            # relatório (não altera o estado)
+bun run houndsman findings verify --json     # saída estruturada
+bun run houndsman findings verify --apply    # marca os resolvidos como done (ping no run.json)
+```
+
+- Sem `--apply`: **só relatório** (grava `verify.md` na pasta da run). Nada muda no `state.json`.
+- Com `--apply`: os findings com status **`resolved`** viram `execState: done` (histórico
+  `by: "verify"`). `persisting` e `uncertain` **não** são tocados.
+
+Filtros (como no `findings list`): `--severity`, `--watchdog`, `--file`, `--decision`. `--all`
+inclui ausentes. `--no-jev` desliga o tier LLM. `--fail-on-persisting` sai com código 1 se algum
+`blocking` persistir (útil em CI).
+
+---
+
+## Status possíveis
+
+| Status | Significado | `--apply`? |
+|---|---|---|
+| `resolved` | Violação não encontrada (âncora sumida; confirmada pelo Jev quando há chave). | ✅ vira `done` |
+| `persisting` | Âncora ainda presente — a violação continua. | ❌ |
+| `uncertain` | Sem âncora e sem confirmação do Jev (ou Jev indisponível). | ❌ |
+| `file-missing` | Arquivo não está no working tree (deletado/movido). | ❌ |
+
+---
+
+## Anti-padrões
+
+- ❌ Reexecutar o `hunt` inteiro só para conferir se um fix funcionou — use o `verify`.
+- ❌ Esperar que o `verify` marque `done` sem `--apply` (sem a flag, nada muda no estado).
+- ❌ Tratar `persisting` como resolvido — a âncora ainda está no arquivo.
+- ❌ Esperar verificação 100% pelo LLM — o tier local resolve a maioria de graça.