@payconductor/houndsman 0.1.1 → 0.1.4

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)
@@ -114,6 +109,20 @@ as regras atômicas dos watchdogs. Respostas acima do limiar viram **candidatos*
 - **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)
@@ -151,46 +160,10 @@ Falha com mensagem clara se faltar algum `findings/<watchdog>.json`. Quando todo
 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
+   `fingerprint` de conteúdo por finding, 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.
+Após finalizar, corrija os achados com a capability **`fix`** (`fix.md`): a UI ou os
+comandos `findings` levam do achado à correção.
 
 ---
 
@@ -243,9 +216,11 @@ git diff --name-status (base...head)
         ↓
 [2] N subagentes em paralelo   ──►  findings/<watchdog>.json
         ↓
-[3] houndsman --finalize       ──►  review.md + state.json
+[3] houndsman --finalize       ──►  review.md + state.json + run.json (review_done)
         ↓
-[4] triagem (UI ou agente)     ──►  state.json (decision/execState)
+[4] server (UI)                ──►  validar a revisão + marcar decision: execute
+        ↓
+[5] fix                        ──►  correções + state.json/run.json (fix_done)
 ```
 
 ---
@@ -254,25 +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 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 |
+
+Flags do review: `--base` · `--head` · `--branch` · `--dir` · `--clean` · `--full` (força
+completo) · `--no-jev` · `--fail-on-blocking` (com `--finalize`).
 
 ---
 
@@ -294,11 +267,12 @@ 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` + `houndsman test` + `ci:fix` + `ci:check`.
+> Após qualquer alteração, rodar `houndsman doctor`. (`houndsman test` e `ci:fix`/`ci` são
+> comandos da **lib**, não do projeto consumidor.)
 
 ---
 

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.
 
 ---
 
@@ -72,10 +72,29 @@ Toda regra (nova ou alterada) deve passar por **todos** os itens:
      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.
+10. **Sem duplicata** — nenhuma regra repetida (texto normalizado) no mesmo watchdog.
+11. **Lugar único** — a regra vive **apenas** em `rules`. Nunca repita o texto (nem o anti-padrão)
+    em `reviewFocus`, `contextFiles`, `scope`, `description` ou `exclude`.
 
 > O `houndsman doctor` emite um **aviso** (não bloqueante) para regra sem polaridade explícita
-> (`Promover:`, `Evitar:`, `Não` ou `Nunca`).
+> (`Promover:`, `Evitar:`, `Não` ou `Nunca`), para regra duplicada e para texto de regra que
+> vazou para `reviewFocus`/`contextFiles`/`exclude`.
+
+### Onde cada coisa vive (não duplique a regra)
+
+Cada informação tem o seu campo — não espelhe a regra em vários lugares:
+
+| O que você quer expressar | Campo | Observação |
+|---|---|---|
+| A **regra** (o que DEVE/NÃO DEVE acontecer) | `rules[]` | Único lugar da regra: `{ severity, text, jev? }`. |
+| **Quais arquivos** o watchdog cobre | `classify` | Regex de path (ou de conteúdo). |
+| **Que arquivos** olhar primeiro | `reviewFocus` | **Paths/áreas** do código — não texto de regra. |
+| **Que docs** consultar | `contextFiles` | Caminhos de **documentação** — não regra nem código. |
+| O que **nunca** carregar | `exclude` | Paths a ignorar. |
+| O **território** em prosa | `scope` / `description` | Contexto do domínio, não regra. |
+
+> A regra aparece **uma única vez** no arquivo — em `rules`. Repeti-la em
+> `reviewFocus`/`contextFiles`/`scope`/`description`/`exclude` só cria ruído no brief do subagente.
 
 ---
 
@@ -86,7 +105,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 +127,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]` |
 
@@ -166,10 +185,12 @@ verificáveis por leitura local. Candidatos não confirmados pelo watchdog **nã
      `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.
+   - **A regra vai só em `rules`** — não a repita em `reviewFocus`/`contextFiles`/`scope`/
+     `description`/`exclude`. Só toque nesses campos se o **domínio/paths** mudou (ver
+     *Onde cada coisa vive*), nunca para reafirmar a regra.
    - 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).
 
@@ -226,24 +247,24 @@ todos os itens — em especial: **geral/reutilizável** (não regra de negócio
 
 ```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)
 ```
 
+> `bun run houndsman test`, `bun run ci:fix` e `bun run ci` são comandos para **manter a lib** do
+> houndsman (repo do pacote) — não para quem só usa o houndsman no projeto.
+
 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.
+- [ ] `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).
 - [ ] 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.
+- [ ] O texto de cada regra aparece **exatamente uma vez** no arquivo (só em `rules`) — nada em
+      `reviewFocus`/`contextFiles`/`scope`/`description`/`exclude`.
 
 ```bash
 # Dry-run: gerar briefs e conferir ausência de regras removidas

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.