@payconductor/houndsman 0.1.1 → 0.1.4

package/src/core/verify.ts

@@ -0,0 +1,175 @@
+/**
+ * Verificação de findings (biblioteca) — "as violações foram resolvidas?".
+ *
+ * Checagem barata, **sem re-revisar a PR**:
+ *  - Tier 0 (local, grátis): reancora a âncora de conteúdo contra o working tree.
+ *  - Tier 1 (Jev, opcional): confirma/refuta os casos ambíguos (âncora sumida ou
+ *    inexistente) via LLM, sobre um diff focado do arquivo (`jev-verify.ts`).
+ *
+ * `verifyLocal` é puro (recebe o leitor de arquivos); o comando renderiza e, com
+ * `--apply`, persiste `resolved` → `execState: done`.
+ */
+
+import { reanchor } from "./finding-anchor";
+import {
+	applyFindingUpdate,
+	type FileReader,
+	type FindingState,
+	type FindingsFilter,
+	type FindingsStateFile,
+	filterFindings,
+} from "./findings-state";
+import type { Severity } from "./types";
+
+/** Resultado da verificação de um finding. */
+export type VerifyStatus = "resolved" | "persisting" | "uncertain" | "file-missing";
+
+/** Mecanismo que decidiu o status (reancoragem local ou LLM). */
+export type VerifyBasis = "anchor" | "jev";
+
+/** Valores canônicos de status (ordem de exibição). */
+export const VERIFY_STATUSES: readonly VerifyStatus[] = [
+	"resolved",
+	"persisting",
+	"uncertain",
+	"file-missing",
+];
+
+/** Um finding verificado. */
+export type VerifyEntry = {
+	id: string;
+	file: string;
+	rule: string;
+	severity: Severity;
+	message: string;
+	line: number | null;
+	status: VerifyStatus;
+	basis: VerifyBasis;
+	/** Confiança do Jev (0–1) quando `basis: "jev"`. */
+	confidence?: number;
+	detail?: string;
+	/** Ambíguo no tier local — candidato à confirmação do Jev. */
+	ambiguous: boolean;
+};
+
+/** Fila de verificação: presentes, excluindo `ignore` (descartados pelo usuário). */
+export function selectVerifiable(
+	state: FindingsStateFile,
+	filter: FindingsFilter = {},
+): FindingState[] {
+	return filterFindings(state, filter).filter(
+		(finding) => finding.decision !== "ignore",
+	);
+}
+
+/**
+ * Tier 0 — checagem local por conteúdo. Marca `ambiguous: true` quando a âncora
+ * sumiu (corrigida ou trecho reescrito) ou não existe; nesses casos o Jev pode
+ * confirmar. Âncora presente (`ok`/`moved`) ⇒ `persisting`, definitivo.
+ */
+export function verifyLocal(
+	findings: readonly FindingState[],
+	readFile: FileReader,
+): VerifyEntry[] {
+	return findings.map((finding) => {
+		const base = {
+			id: finding.id,
+			file: finding.file,
+			rule: finding.rule,
+			severity: finding.severity,
+			message: finding.message,
+			line: finding.line,
+		};
+		const content = readFile(finding.file);
+		if (content === null) {
+			return {
+				...base,
+				status: "file-missing" as const,
+				basis: "anchor" as const,
+				ambiguous: false,
+				detail: "arquivo ausente no working tree",
+			};
+		}
+		if (!finding.anchor) {
+			return {
+				...base,
+				status: "uncertain" as const,
+				basis: "anchor" as const,
+				ambiguous: true,
+				detail: "finding sem âncora de conteúdo",
+			};
+		}
+		const { status } = reanchor(content, finding.anchor, finding.line);
+		if (status === "stale") {
+			return {
+				...base,
+				status: "resolved" as const,
+				basis: "anchor" as const,
+				ambiguous: true,
+				detail: "âncora ausente (trecho corrigido?)",
+			};
+		}
+		return {
+			...base,
+			status: "persisting" as const,
+			basis: "anchor" as const,
+			ambiguous: false,
+			detail: status === "moved" ? "âncora deslocada" : undefined,
+		};
+	});
+}
+
+/**
+ * Tier 1 — aplica a confirmação do Jev aos casos ambíguos.
+ * `confidence[id] >= threshold` ⇒ a violação persiste; abaixo ⇒ resolvida.
+ * Ids sem resposta mantêm o provisório local (fail-open). Devolve o nº aplicado.
+ */
+export function applyJev(
+	entries: VerifyEntry[],
+	confidence: Map<string, number>,
+	threshold: number,
+): number {
+	let applied = 0;
+	for (const entry of entries) {
+		if (!entry.ambiguous) continue;
+		const value = confidence.get(entry.id);
+		if (value === undefined) continue;
+		entry.basis = "jev";
+		entry.confidence = value;
+		entry.status = value >= threshold ? "persisting" : "resolved";
+		applied++;
+	}
+	return applied;
+}
+
+export type VerifySummary = Record<VerifyStatus, number>;
+
+/** Contagem por status. */
+export function summarizeVerify(entries: readonly VerifyEntry[]): VerifySummary {
+	const summary = Object.fromEntries(
+		VERIFY_STATUSES.map((status) => [status, 0]),
+	) as VerifySummary;
+	for (const entry of entries) summary[entry.status]++;
+	return summary;
+}
+
+/**
+ * Persiste os `resolved` como `done` (acao `verify`). Devolve os ids alterados.
+ * Muta o estado em memória (o caller persiste).
+ */
+export function applyResolutions(
+	state: FindingsStateFile,
+	entries: readonly VerifyEntry[],
+	now: string = new Date().toISOString(),
+): string[] {
+	const changed: string[] = [];
+	for (const entry of entries) {
+		if (entry.status !== "resolved") continue;
+		const finding = state.findings[entry.id];
+		if (!finding || finding.execState === "done") continue;
+		applyFindingUpdate(finding, { execState: "done", by: "verify" }, now);
+		changed.push(finding.id);
+	}
+	if (changed.length > 0) state.updatedAt = now;
+	return changed;
+}

package/src/core/watchdog-registry.ts

@@ -1,8 +1,7 @@
 /**
  * Acesso tipado aos watchdogs de um `HoundsmanConfig` (biblioteca).
  *
- * Substitui o antigo barrel `registry/`. O motor não conhece ids concretos —
- * tudo chega via `config`.
+ * O motor não conhece ids concretos — tudo chega via `config`.
  */
 
 import type { HoundsmanConfig } from "./config";

package/src/index.ts

@@ -8,7 +8,7 @@
 export { assetPath, OUTPUT_FORMAT_FILE } from "./core/assets";
 export { defaultRenderBrief, PROCEDURE, renderBrief } from "./core/brief";
 export type { FindingsCommandResult } from "./core/commands/findings";
-export { runFindingsCommand } from "./core/commands/findings";
+export { runFindingsCommand, runVerifyCommand } from "./core/commands/findings";
 export type {
 	HoundsmanBudgets,
 	HoundsmanConcurrency,

package/src/server/artifacts.ts

@@ -11,6 +11,7 @@ import { isAbsolute, join, relative, resolve } from "node:path";
 const RUN_MARKERS = [
 	"manifest.json",
 	"state.json",
+	"run.json",
 	"classification.json",
 	"review.md",
 ] as const;

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.
 
 ---
@@ -11,6 +11,10 @@ aplicadas em nenhuma parte do código) devem ser **removidas**, não apenas reba
 1. `.houndsman/watchdogs/<id>.ts` — `WATCHDOG_DEFINITIONS[<id>]` é a fonte única de verdade:
    `description`, `scope`, `rules` (severidade + texto), `classify`, `contextFiles`,
    `reviewFocus`, `exclude`.
+
+   > **Onde cada coisa vive:** a **regra** vive só em `rules`; `reviewFocus` = paths a priorizar;
+   > `contextFiles` = docs a consultar; `exclude` = paths a ignorar; `scope`/`description` = prosa.
+   > Texto de regra em `reviewFocus`/`contextFiles`/`exclude` é **duplicação** a corrigir.
 2. `src/core/brief.ts` (no motor) — `PROCEDURE` (passos de revisão compartilhados).
 3. Ground truth (padrões reais do projeto):
    - Documentos de convenção do projeto (ex.: `AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`).
@@ -41,6 +45,7 @@ classifique sem evidência (caminho de arquivo, linha, ou "0 ocorrências via gr
 | `OUTDATED` | Já foi aplicado, mas o código mudou | Remover ou reescrever |
 | `MISCALIBRATED` | Regra válida, mas severidade errada | Ajustar severidade |
 | `DEAD-PATH` | `scope`/`contextFiles`/`classify` apontam para caminho/arquivo inexistente | Corrigir ou remover |
+| `REDUNDANT` | Regra duplicada no mesmo watchdog ou repetida em `reviewFocus`/`contextFiles`/`exclude` | Remover a cópia (a regra fica só em `rules`) |
 
 ## Formato do relatório
 

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,15 +47,17 @@ 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) |
-| `houndsman test` | Roda a suíte de testes da lib |
+| `houndsman test` | **Manutenção da lib** — roda a suíte de testes do pacote (não é uso do consumidor) |
 
 ### 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
 
@@ -114,11 +138,13 @@ houndsman.config.ts           # HoundsmanConfig (dados; descoberto em runtime)
 > prove que o padrão existe no código (regra negativa: prove que o anti-padrão **não** existe).
 > Regras devem ser **gerais/reutilizáveis** no domínio e declarar a **polaridade** no texto
 > (`Promover:` = deve acontecer; `Evitar:`/`Não`/`Nunca` = não deve acontecer).
+> Cada regra vive **só** em `rules` — não a repita em `reviewFocus`/`contextFiles`/`scope`/
+> `description`/`exclude` (isso só duplicaria o brief).
 
 1. Novas regras/watchdogs → editar `.houndsman/watchdogs/<id>.ts` (regras + escopo +
    `classify`) ou `doc-mappings.ts`/`exclusions.ts`. Um watchdog novo exige só o módulo em
    `.houndsman/watchdogs/<id>.ts` + entrada em `.houndsman/watchdogs/index.ts`.
 2. Rodar `bun run houndsman doctor` — valida a config (definições, classificação, specs Jev).
 
-> Para qualquer alteração de regra (pontual ou auditoria completa), use o skill
-> **`houndsman-update`**: `.houndsman/core/skill/houndsman-update.md`.
+> 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
@@ -60,10 +60,19 @@ bun run houndsman update      # reescreve .houndsman/core/** e .houndsman/.gitig
 
 ```bash
 bun run houndsman doctor         # valida config + ambiente + credencial Jev
-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.