@payconductor/houndsman 0.1.1 → 0.1.3

package/src/server/client/RunList.tsx

@@ -2,6 +2,7 @@
  * Sidebar: logo do houndsman + lista de runs (branch e nº de findings).
  */
 
+import { describeRunStatus } from "./constants";
 import type { RunSummary } from "./types";
 
 export function RunList({
@@ -24,19 +25,27 @@ export function RunList({
 			</div>
 			<nav class="runs">
 				{runs.length === 0 && <p class="empty">Nenhuma run encontrada.</p>}
-				{runs.map((run) => (
-					<button
-						type="button"
-						title={`Abrir a run da branch ${run.branch}`}
-						class={`run${run.slug === slug ? " active" : ""}`}
-						onClick={() => onSelect(run.slug)}
-					>
-						<span class="run-branch">{run.branch}</span>
-						<span class="run-meta">
-							{run.summary.present}/{run.summary.total} presentes
-						</span>
-					</button>
-				))}
+				{runs.map((run) => {
+					const status = describeRunStatus(run);
+					return (
+						<button
+							type="button"
+							title={`Abrir a run da branch ${run.branch}`}
+							class={`run${run.slug === slug ? " active" : ""}`}
+							onClick={() => onSelect(run.slug)}
+						>
+							<span class="run-branch">{run.branch}</span>
+							<span class="run-meta">
+								{run.summary.present}/{run.summary.total} presentes
+							</span>
+							{status && (
+								<span class={`run-status status-${status.kind}`}>
+									{status.label}
+								</span>
+							)}
+						</button>
+					);
+				})}
 			</nav>
 		</aside>
 	);

package/src/server/client/constants.ts

@@ -2,7 +2,7 @@
  * Constantes de apresentação do cliente (labels, ordem, emojis).
  */
 
-import type { Decision, ExecState, Severity } from "./types";
+import type { Decision, ExecState, RunStatus, RunSummary, Severity } from "./types";
 
 export const SEVERITY_EMOJI: Record<Severity, string> = {
 	blocking: "❌",
@@ -30,6 +30,37 @@ export const EXEC_LABELS: Record<ExecState, string> = {
 	stale: "exec: stale",
 };
 
+export const RUN_STATUS_LABELS: Record<RunStatus, string> = {
+	reviewing: "Revisando",
+	review_done: "Revisão pronta",
+	fixing: "Corrigindo",
+	fix_done: "Correção pronta",
+};
+
+/** Limiar de inatividade para exibir timeout (display-only; não é status). */
+export const STATUS_TIMEOUT_MS = 10 * 60 * 1000;
+
+export type RunStatusView = { kind: string; label: string; timeout: boolean };
+
+/** View do status de uma run — label; vira timeout quando ativo e sem ping recente. */
+export function describeRunStatus(
+	run: RunSummary,
+	now: number = Date.now(),
+): RunStatusView | null {
+	const status = run.status;
+	if (!status) return null;
+	const active = status === "reviewing" || status === "fixing";
+	const updated = run.updatedAt ? Date.parse(run.updatedAt) : Number.NaN;
+	if (active && Number.isFinite(updated) && now - updated > STATUS_TIMEOUT_MS) {
+		return {
+			kind: "timeout",
+			label: status === "reviewing" ? "Timeout na revisão" : "Timeout na correção",
+			timeout: true,
+		};
+	}
+	return { kind: status, label: RUN_STATUS_LABELS[status], timeout: false };
+}
+
 /** Artefatos que podem ser lidos na aba "Artefatos". */
 export const ARTIFACTS = [
 	"manifest.json",

package/src/server/client/types.ts

@@ -9,6 +9,9 @@ export type Severity = "blocking" | "attention" | "suggestion" | "nit";
 export type Decision = "pending" | "execute" | "ignore";
 export type ExecState = "pending" | "in_progress" | "done" | "stale";
 
+/** Estados de execução de uma run (espelham `core/run-status.ts`). */
+export type RunStatus = "reviewing" | "review_done" | "fixing" | "fix_done";
+
 export type Finding = {
 	id: string;
 	rule: string;
@@ -38,6 +41,7 @@ export type RunSummary = {
 	slug: string;
 	branch: string;
 	updatedAt?: string;
+	status?: RunStatus | null;
 	summary: Summary;
 };
 

package/src/server/index.ts

@@ -27,6 +27,7 @@ import {
 	syncState,
 } from "../core/findings-state";
 import { STATE_FILE } from "../core/paths";
+import { pingFindingsStatus, readRunStatus } from "../core/run-status";
 import type { Severity } from "../core/types";
 import { listRunSlugs, readRunFile, readRunJson, runDirForSlug } from "./artifacts";
 import { buildClientBundle } from "./client-build";
@@ -95,10 +96,12 @@ function listRuns(artifactDir: string): unknown[] {
 			dir,
 			"manifest.json",
 		);
+		const status = readRunStatus(dir);
 		return {
 			slug,
 			branch: state.branch || manifest?.branch || slug,
-			updatedAt: state.updatedAt,
+			updatedAt: status?.updatedAt ?? state.updatedAt,
+			status: status?.status ?? null,
 			summary: summarize(state),
 		};
 	});
@@ -114,6 +117,7 @@ function runDetail(dir: string, slug: string): unknown {
 	return {
 		slug,
 		branch: state.branch || slug,
+		status: readRunStatus(dir),
 		manifest: readRunJson(dir, "manifest.json"),
 		summary: summarize(state),
 		watchdogs: Object.keys(classification?.watchdogs ?? {}),
@@ -153,6 +157,7 @@ async function updateFinding(
 	applyFindingUpdate(finding, body);
 	reorder(state);
 	store.write(state);
+	pingFindingsStatus(dir, state);
 	return json({ finding });
 }
 
@@ -161,6 +166,7 @@ function syncRun(dir: string, slug: string): Response {
 	const state = store.read() ?? buildForRun(dir, slug) ?? emptyState(slug);
 	const result: SyncResult = syncState(state, fileReader(process.cwd()));
 	store.write(state);
+	pingFindingsStatus(dir, state);
 	return json({ result, summary: summarize(state) });
 }
 
@@ -301,6 +307,11 @@ code, pre { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospac
 .run.active { border-color:var(--accent); background:#22304d; }
 .run-branch { font-weight:600; font-size:13px; }
 .run-meta { color:var(--muted); font-size:11px; }
+.run-status { font-size:10px; text-transform:uppercase; letter-spacing:.04em; color:var(--muted); }
+.status-reviewing, .status-fixing { color:#e3a008; }
+.status-review_done { color:#4c8dff; }
+.status-fix_done { color:#3fb950; }
+.status-timeout { color:#e5484d; }
 .main { flex:1; padding:16px 20px; max-width:980px; }
 .topbar { display:flex; justify-content:space-between; align-items:center; margin-bottom:12px; }
 .tabs { display:flex; gap:6px; flex-wrap:wrap; }

package/src/skill/AUDIT-PROTOCOL.md

@@ -1,7 +1,7 @@
 # Protocolo de Auditoria dos Watchdogs — houndsman
 
-Referência do Modo B do skill `houndsman-update`. Objetivo: garantir que as regras dos
-watchdogs validam **apenas padrões que o projeto aplica hoje**. Regras "utópicas" (não
+Referência do Modo B da capability `train` (skill `/houndsman`). Objetivo: garantir que as
+regras dos watchdogs validam **apenas padrões que o projeto aplica hoje**. Regras "utópicas" (não
 aplicadas em nenhuma parte do código) devem ser **removidas**, não apenas rebaixadas.
 
 ---

package/src/skill/README.md

@@ -2,6 +2,18 @@
 
 Revisão automatizada de Pull Requests — CLI independente + camada de configuração do projeto.
 
+## Capabilities
+
+Um único skill (`/houndsman`), quatro capabilities (detalhadas em `hunt.md`, `train.md`,
+`fix.md`, `verify.md`):
+
+| Capability | O que faz |
+|---|---|
+| `hunt` | Revisão de PR (Passos 0–3; incremental quando possível). |
+| `train` | Manutenção das regras dos watchdogs. |
+| `fix` | Correção dos findings marcados como `execute`. |
+| `verify` | Confere se as violações foram resolvidas, sem re-revisar a PR. |
+
 ## Terminologia
 
 - **houndsman** — o orquestrador/treinador (CLI + motor).
@@ -35,6 +47,8 @@ Revisão automatizada de Pull Requests — CLI independente + camada de configur
 | `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 findings <sub>` | Triagem/correção dos findings (`list`/`set`/`done`/`sync`/`batch`/`verify`/...) |
+| `houndsman server` | UI local de triagem (Bun.serve + Preact) |
 | `houndsman setup` | Cria a configuração inicial do projeto |
 | `houndsman update` | Sincroniza os arquivos auto-gerados (`.houndsman/core`) |
 | `houndsman doctor` | Valida a configuração, o ambiente e a credencial Jev (anti-drift) |
@@ -43,7 +57,7 @@ Revisão automatizada de Pull Requests — CLI independente + camada de configur
 ### Flags
 
 `--config <path>` · `--base <branch>` (default `main`) · `--head <ref>` (default `HEAD`) ·
-`--branch <nome>` · `--dir <dir>` · `--clean` · `--no-jev` · `--fail-on-blocking` (no `--finalize`).
+`--branch <nome>` · `--dir <dir>` · `--clean` · `--full` · `--no-jev` · `--fail-on-blocking` (no `--finalize`).
 
 ## Artefatos
 
@@ -60,6 +74,9 @@ Tudo em `.houndsman/.runs/<branch-slug>/` (default do `artifactDir`, `.houndsman
 | `findings/<watchdog>.json` | Saída dos sub-agentes (schema `OUTPUT-FORMAT.md`) |
 | `review.md` | Relatório final (achados agrupados por arquivo) |
 | `review.<watchdog>.md` | Relatório por domínio (só quando há achados) |
+| `state.json` | Estado de triagem dos findings (decisão/execução + fingerprint + commit revisado) |
+| `run.json` | Status do run (`reviewing`/`review_done`/`fixing`/`fix_done`) + timestamps |
+| `verify.md` | Relatório do `findings verify` (resolvidos/persistem/incertos) |
 
 ## Estrutura
 
@@ -83,6 +100,12 @@ src/
 │   ├── diff-source.ts       # diff único (patch + --numstat) p/ churn/orçamento
 │   ├── doc-discoverer.ts    # descoberta de docs
 │   ├── report-builder.ts    # dedupe/render do relatório
+│   ├── finding-anchor.ts    # âncora/fingerprint de conteúdo + reancoragem
+│   ├── findings-state.ts    # estado de triagem (state.json) + store atômico
+│   ├── git-revision.ts      # refs/ancestralidade + arquivo por commit + diff por intervalo
+│   ├── verify.ts            # verificação de findings (tier local + Jev)
+│   ├── run-status.ts        # run.json (reviewing/review_done/fixing/fix_done)
+│   ├── fix-batch.ts         # agrupamento/paginação do lote (findings batch)
 │   ├── registry-check.ts    # validações anti-drift (config-driven)
 │   ├── commands/            # context · review · watchdog · setup · update · test
 │   └── jev/                 # subsistema Jev (Passo 1.5)
@@ -105,8 +128,9 @@ houndsman.config.ts           # HoundsmanConfig (dados; descoberto em runtime)
 └── 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`.
+> O `SKILL.md` do skill (`.agents/skills/houndsman/SKILL.md` e
+> `.claude/skills/houndsman/SKILL.md`) é gerado a partir de `src/skill/SKILL.md`
+> pelo `houndsman setup`/`update` (com `{{projectName}}` resolvido).
 
 ## Manutenção
 
@@ -120,5 +144,5 @@ houndsman.config.ts           # HoundsmanConfig (dados; descoberto em runtime)
    `.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`.
+> Para qualquer alteração de regra (pontual ou auditoria completa), use a capability
+> **`train`**: `/houndsman train` → `.houndsman/core/skill/train.md`.

package/src/skill/SETUP.md

@@ -39,7 +39,7 @@ A camada separa o que é **auto-gerado** do que é **do usuário**:
 | `.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 |
+| `.agents/skills/houndsman/SKILL.md` etc. | **auto** | `SKILL.md` do skill `/houndsman` (capabilities `hunt`/`train`/`fix`) por harness |
 
 Além disso, adiciona o script `"houndsman": "houndsman"` ao `package.json` — assim
 `bun run houndsman [...]` funciona na raiz do projeto. Os artefatos ficam em
@@ -64,6 +64,16 @@ bun run houndsman test           # suíte da lib (project-agnóstica)
 bun run houndsman --base main    # prepara briefs do diff atual
 ```
 
+## Capabilities do skill
+
+Depois do setup, invoque o skill `/houndsman` no seu harness:
+
+| Capability | Para quê |
+|---|---|
+| `/houndsman hunt` | Revisar a PR (default: `/houndsman`). |
+| `/houndsman train` | Adicionar/ajustar/remover regras dos watchdogs. |
+| `/houndsman fix` | Corrigir os findings marcados como `execute`. |
+
 ## Contrato do motor (`HoundsmanConfig`)
 
 Definido em `src/core/config.ts` (pacote) e espelhado em `.houndsman/core/types.ts` (gerado):

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`.