@payconductor/houndsman 0.1.0 → 0.1.3

package/README.md

@@ -12,7 +12,8 @@ relatório único.
 
 **Terminologia:** **houndsman** = orquestrador/treinador (CLI + motor) · **watchdog** = cada
 agente especialista por domínio que audita o diff · **review/revisão** = o processo ·
-**Jev** = pré-análise opcional.
+**Jev** = pré-análise opcional. O vocabulário completo (brief, findings, manifest, budget,
+overflow, churn, candidato…) está em [`docs/GLOSSARY.md`](docs/GLOSSARY.md).
 
 ---
 
@@ -25,8 +26,8 @@ diferente das PRs. O motor só coordena a caçada — as regras são problema se
 
 - **Bun** — runtime obrigatório.
 - **git** — o diff usa `git diff <base>...<head>`.
-- Opcionais, ambos **falha-aberto**: **`gh`** (contexto da PR) e **`TYPESAFE_API_KEY`**
-  (pré-análise Jev). Sem eles, a revisão roda igual.
+- Opcionais: **`gh`** (contexto da PR) e **`TYPESAFE_API_KEY`** (pré-análise Jev). A revisão
+  funciona normalmente sem eles; o `houndsman doctor` valida a credencial Jev quando presente.
 
 ### 2. Instale o CLI (global)
 
@@ -51,15 +52,13 @@ Cria a camada `.houndsman/`, que é **autocontida** (não instala nada no seu pr
 | `.houndsman/exclusions.ts` | você | Arquivos que nunca entram na revisão |
 | `.houndsman/doc-mappings.ts` | você | path → documentação de contexto |
 | `.houndsman/core/**` | auto | Tipos + docs do skill (sincronizados por `houndsman update`) |
-| `.agents/` · `.claude/` | auto | Ponteiros de skill dos harnesses |
-| `package.json` | — | Adiciona o script `"houndsman"` |
 
-> **Não existe "modo completo".** O `setup` já cria a camada inicial com um watchdog de
-> exemplo — troque o exemplo pelas regras reais do seu projeto (ou use `/houndsman-update`).
+> O `setup` já cria a camada inicial com um watchdog de exemplo — troque o exemplo pelas
+> regras reais do seu projeto (ou use `/houndsman train`).
 
 ### 4. Escreva suas regras
 
-Edite `.houndsman/watchdogs/` — veja [Escrevendo boas regras](#escrevendo-boas-regras).
+Edite `.houndsman/watchdogs/` — veja [Escrevendo boas regras](docs/AVANCADO.md#escrevendo-boas-regras).
 
 ### 5. Valide
 
@@ -72,7 +71,7 @@ bun run houndsman doctor
 No seu harness (Claude Code / agents), invoque o skill:
 
 ```
-/houndsman
+/houndsman hunt
 ```
 
 O skill orquestra tudo e grava o relatório em `.houndsman/.runs/<branch-slug>/review.md`.
@@ -83,25 +82,68 @@ Não precisa rodar nenhum script à mão.
 ## O fluxo de trabalho
 
 ```
-/houndsman
+/houndsman hunt
    ├─ Passo 0  contexto da PR (gh, opcional)
-   ├─ Passo 1  classifica o diff → briefs por watchdog
+   ├─ Passo 1  classifica o diff → briefs por watchdog (incremental quando possível)
    ├─ Passo 2  N subagentes revisam em paralelo
-   └─ Passo 3  consolida em review.md
+   ├─ Passo 3  consolida em review.md + state.json
+   ├─ Passo 4  valida na UI (server) e marca os achados a executar
+   ├─ Passo 5  fix corrige o grupo atual → run.json (fix_done)
+   └─ Passo 6  verify confere o que resolveu, sem re-revisar
 ```
 
-- Revisão normal: só `/houndsman` (a branch é detectada; base default `main`).
-- Revisar outra branch: `/houndsman feature/minha-branch`.
+O skill tem **4 capabilities**, todas em `/houndsman`:
+
+- **`hunt`** — revisa a PR (default: `/houndsman` = `/houndsman hunt`).
+- **`train`** — mantém/atualiza as regras dos watchdogs.
+- **`fix`** — corrige os findings marcados (`/houndsman fix`).
+- **`verify`** — confere se as violações foram resolvidas (`/houndsman verify`), sem re-revisar.
+
+- Revisão normal: `/houndsman` ou `/houndsman hunt` (a branch é detectada; base default `main`).
+- Revisar outra branch: `/houndsman hunt feature/minha-branch`.
+- Validar e triar na UI: `houndsman server --open` — marque os achados a executar (`execute`).
 - Manual (sem skill): `houndsman context` → `houndsman --base main` → *(subagentes)* →
   `houndsman --finalize`.
 - CI: `houndsman --finalize --fail-on-blocking` (exit 1 se houver bloqueantes).
 
 ---
 
+## Triando os findings (opcional)
+
+Depois do `--finalize`, cada finding tem um `id` curto e um `fingerprint` de **conteúdo**
+no `.houndsman/.runs/<branch-slug>/state.json`. Você decide o que fazer com cada um — pela
+**UI local** ou pelo **agente** (auto-fix) — sem abrir o JSON à mão:
+
+```bash
+bun run houndsman server --open     # UI: triar, comentar, marcar feito, ler artefatos
+```
+
+- **decision:** `pending` · `execute` · `ignore` (+ comentário).
+- **execState:** `pending` · `in_progress` · `done` · `stale`.
+
+**Auto-fix pelo agente** — as linhas mudam depois do fix, e o motor reancora por conteúdo:
+
+```bash
+bun run houndsman findings batch --json     # grupo atual (agrupamento automático) + outros
+# ... o agente corrige apenas esse grupo ...
+bun run houndsman findings sync             # reancora por conteúdo
+bun run houndsman findings done <id>
+bun run houndsman findings verify           # confere o que resolveu (barato, sem re-revisar)
+```
+
+> A partir da 2ª revisão o `hunt` é **incremental**: revisa só os arquivos que mudaram desde
+> o último `--finalize` e **carrega** os findings dos arquivos inalterados. `--full` força
+> o review completo.
+
+> A identidade do finding é o **conteúdo** (fingerprint), não a linha: itens deslocados
+> pelo fix não se perdem. O estado é local e mora em `.runs/<slug>/state.json` (gitignored).
+
+---
+
 ## Mantendo a configuração
 
-- **Alterar regras** → use o skill **`/houndsman-update`**. Ele prova no código que o padrão
-  existe (evidência) antes de editar e roda as validações.
+- **Alterar regras** → use a capability **`train`** (`/houndsman train`). Ela prova no código
+  que o padrão existe (evidência) antes de editar e roda as validações.
 - **Atualizou a lib?** Sincronize os arquivos auto-gerados sem tocar nas suas regras:
 
   ```bash
@@ -116,80 +158,17 @@ Não precisa rodar nenhum script à mão.
 
 ---
 
-## Avançado
-
-### Comandos do dia a dia
-
-| Comando | Função |
-|---|---|
-| `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 context` | Passo 0 — contexto da PR via `gh` |
-| `houndsman --base main` | Passo 1 — prepara os briefs |
-| `houndsman --finalize` | Passo 3 — gera o relatório |
-| `houndsman watchdog <id>` | Contexto de um watchdog (`--rules`, `--json`) |
-
-Flags: `--base <branch>` (default `main`) · `--head <ref>` (default `HEAD`) ·
-`--branch <nome>` · `--dir <dir>` · `--config <path>` · `--clean` · `--no-jev` ·
-`--fail-on-blocking` (com `--finalize`).
-
-### Escrevendo boas regras
-
-O texto da regra é renderizado **literalmente** no brief do subagente — ambiguidade vira
-ruído na revisão. Toda regra começa com um **prefixo de polaridade**:
-
-- `Promover:` → algo que **DEVE** acontecer (o padrão precisa existir no código).
-- `Evitar:` → algo que **NÃO DEVE** acontecer. `Não` e `Nunca` no início são equivalentes.
-
-Boas práticas:
-
-1. **Só regra que o projeto aplica hoje** — prove com evidência (`arquivo:linha` para
-   afirmativas; `0 ocorrências via grep` do anti-padrão para negativas). Regra afirmativa sem
-   aplicação real gera falso positivo.
-2. **Geral e reutilizável** — descreva um padrão do domínio, não uma regra de negócio
-   amarrada a uma única classe/use-case (isso é papel de teste automatizado).
-3. **Condição inequívoca e critério concreto** — duas IAs chegam à mesma conclusão; use
-   limite/lista explícita ou símbolo real do código.
-4. **Sem jargão vago nem qualificador vazio** — nada de "o antigo", "isso", "apenas por
-   compatibilidade".
-5. **Declare o `classify`** do watchdog — regex de path (`filename`) ou de conteúdo
-   (`content`) para o motor achar os arquivos do domínio.
-6. **Prefira editar via `/houndsman-update`** — ele aplica a rubrica completa e roda as
-   verificações (`doctor`, `test`).
-
-> `houndsman doctor` emite um aviso (não bloqueante) para regra sem prefixo de polaridade.
-
-Exemplo:
-
-```ts
-{ severity: "blocking",  text: "Evitar: handler de webhook processa o payload antes de validar a assinatura do provider." }
-{ severity: "attention", text: "Promover: rotas validam a entrada com o schema do domínio." }
-```
-
-### Estrutura gerada por `setup`
-
-```
-houndsman.config.ts
-.houndsman/
-├── .gitignore            # AUTO
-├── core/                 # AUTO — sincronizado por `update`
-│   ├── types.ts
-│   └── skill/*.md
-├── watchdogs/            # você — 1 módulo .ts por watchdog
-│   └── index.ts
-├── exclusions.ts         # você
-└── doc-mappings.ts       # você
-```
-
-Os artefatos de cada review ficam em `.houndsman/.runs/<branch-slug>/` (auto-ignorados).
-
----
-
 ## Documentação
 
-- **`docs/CONTRIBUTING.md`** — arquitetura, fluxos internos, princípios e desenvolvimento da
+- `docs/AVANCADO.md` — como funciona por dentro (diagrama do fluxo e onde o Jev entra),
+  referência de comandos e boas práticas para escrever regras.
+- `docs/GLOSSARY.md` — glossário do vocabulário de domínio (brief, findings, manifest,
+  budget, overflow, churn, candidato, Jev…): o que cada termo significa **neste** projeto.
+- `docs/CONTRIBUTING.md` — arquitetura, fluxos internos, princípios e desenvolvimento da
   lib (para quem vai contribuir).
+
 - `src/skill/SETUP.md` — referência de configuração passo a passo.
-- `src/skill/houndsman.md` — orquestração do skill `/houndsman`.
-- `src/skill/houndsman-update.md` — manutenção das regras dos watchdogs.
+- `src/skill/SKILL.md` — entry point do skill `/houndsman` (capabilities).
+- `src/skill/hunt.md` — capability `hunt` (revisão de PR).
+- `src/skill/train.md` — capability `train` (manutenção das regras).
+- `src/skill/fix.md` — capability `fix` (correção dos findings).

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@payconductor/houndsman",
-	"version": "0.1.0",
+	"version": "0.1.3",
 	"description": "Orquestrador de revisão de Pull Requests: classifica o diff, despacha watchdogs especializados por domínio e consolida o relatório.",
 	"type": "module",
 	"license": "MIT",
@@ -54,7 +54,8 @@
 		"ci:format:fix": "biome format --fix"
 	},
 	"dependencies": {
-		"axios": "^1.12.2"
+		"axios": "^1.12.2",
+		"preact": "^11.0.1"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "2.2.4",

package/src/cli/index.ts

@@ -11,17 +11,20 @@
  *   (default)            Passo 1 — preparar (classificação + briefs + manifesto)
  *   --finalize           Passo 3 — consolidar os findings em review.md
  *   context              Passo 0 — coletar o contexto da PR via `gh`
+ *   findings <sub>       Triagem/correção dos findings (list/set/done/sync/batch/verify/...)
+ *   server               Sobe a UI local de triagem (Bun.serve)
  *   setup                Cria a configuração inicial do projeto (config + skills)
  *   update               Sincroniza os arquivos auto-gerados (.houndsman/core)
- *   doctor               Valida a configuração e o ambiente (anti-drift)
+ *   doctor               Valida a configuração, o ambiente e a credencial Jev (anti-drift)
  *   test                 Roda a suíte de testes da lib
  *   watchdog <id>        Contexto de um watchdog (`--rules`, `--json`)
  *
  * Flags: `--base <b>` · `--head <ref>` · `--branch <b>` · `--dir <d>` ·
- *   `--config <path>` · `--clean` · `--no-jev` · `--fail-on-blocking`.
+ *   `--config <path>` · `--clean` · `--full` · `--no-jev` · `--fail-on-blocking`.
  */
 
 import { runContextCommand } from "../core/commands/context";
+import { runFindingsCommand, runVerifyCommand } from "../core/commands/findings";
 import { parseReviewArgs } from "../core/commands/review";
 import { runSetupCommand } from "../core/commands/setup";
 import { runLibTests } from "../core/commands/test";
@@ -29,9 +32,11 @@ import { runUpdateCommand } from "../core/commands/update";
 import { renderWatchdogContext } from "../core/commands/watchdog";
 import { type HoundsmanConfig, resolveArtifactDir } from "../core/config";
 import { loadConfig } from "../core/config-loader";
+import { JevClient } from "../core/jev";
 import { finalize, prepare, resolveBranch } from "../core/orchestrator";
 import { relFromRoot } from "../core/paths";
 import { checkRegistry } from "../core/registry-check";
+import { startServer } from "../server";
 
 const HELP = `Uso: houndsman [comando] [flags]
 
@@ -39,9 +44,11 @@ Comandos:
   (nenhum)            Prepara a revisão (classification + briefs + manifesto)
   --finalize          Consolida os findings em review.md
   context             Coleta o contexto da PR via gh (Passo 0)
+  findings <sub>      Triagem/correção dos findings (list · show · set · done · reset · sync · summary · batch · verify · path)
+  server              Sobe a UI local de triagem (--port, --host, --open)
   setup               Cria a configuração inicial do projeto (config + skills)
   update              Sincroniza os arquivos auto-gerados (.houndsman/core)
-  doctor              Valida a configuração e o ambiente (anti-drift)
+  doctor              Valida a configuração, o ambiente e a credencial Jev
   test                Roda a suíte de testes da lib
   watchdog <id>       Contexto de um watchdog (--rules, --json)
 
@@ -52,8 +59,25 @@ Flags:
   --branch <nome>     Branch alvo (default: detecta do git)
   --dir <dir>         Diretório dos artefatos
   --clean             Descarta findings anteriores
+  --full              Força review completo (ignora o modo incremental)
   --no-jev            Desativa a pré-análise Jev
-  --fail-on-blocking  Exit 1 se houver bloqueantes (com --finalize)`;
+  --fail-on-blocking  Exit 1 se houver bloqueantes (com --finalize)
+
+Flags de findings:
+  --decision <d>      pending | execute | ignore
+  --exec <e>          pending | in_progress | done | stale
+  --comment <text>    Comentário/instrução adicional
+  --watchdog <id>     Filtra por watchdog (list)
+  --severity <s>      Filtra por severidade (list, batch)
+  --file <text>       Filtra por trecho do caminho (list)
+  --all               Inclui findings ausentes do último relatório
+  --json              Saída JSON
+  --limit <n>         Limita o nº de itens (list)
+  --group <key>       Grupo alvo no batch (default: o primeiro)
+  --offset <n>        Paginação dentro do grupo (batch)
+  --include-done      Inclui já concluídos no batch
+  --apply             (verify) Marca os resolvidos como done
+  --fail-on-persisting (verify) Exit 1 se algum blocking persistir`;
 
 function readFlag(args: string[], flag: string): string | undefined {
 	const index = args.indexOf(flag);
@@ -88,8 +112,8 @@ function runContext(config: HoundsmanConfig, args: string[]): void {
 	}
 }
 
-/** Valida a configuração do projeto e o ambiente (anti-drift). */
-function runDoctor(config: HoundsmanConfig): void {
+/** Valida a configuração do projeto e o ambiente. */
+async function runDoctor(config: HoundsmanConfig): Promise<void> {
 	console.log("→ Validando configuração do projeto...");
 	const { problems, warnings, jevQuestions } = checkRegistry(config);
 
@@ -110,9 +134,27 @@ function runDoctor(config: HoundsmanConfig): void {
 	console.log("\n→ Ambiente:");
 	console.log(`  ${Bun.which("git") ? "✅" : "❌"} git`);
 	console.log(`  ${Bun.which("gh") ? "✅" : "⚠️ "} gh (opcional — contexto da PR)`);
-	console.log(
-		`  ${process.env.TYPESAFE_API_KEY ? "✅" : "⚠️ "} TYPESAFE_API_KEY (opcional — pré-análise Jev)`,
-	);
+	await reportJevCredential();
+}
+
+/**
+ * Reporta o estado da credencial Jev: presença e validade (chamada mínima).
+ * Fail-open — nunca altera o exit code (`doctor` é diagnóstico).
+ */
+async function reportJevCredential(): Promise<void> {
+	const client = new JevClient();
+	if (!client.isConfigured()) {
+		console.log("  ⚠️  TYPESAFE_API_KEY (opcional — pré-análise Jev)");
+		return;
+	}
+	const check = await client.validateCredential();
+	if (check.ok) {
+		console.log(`  ✅ Jev: credencial válida (modelo ${check.model}).`);
+	} else if (check.kind === "invalid") {
+		console.log(`  ❌ Jev: credencial inválida — ${check.detail}`);
+	} else {
+		console.log(`  ⚠️  Jev: não foi possível validar — ${check.detail}`);
+	}
 }
 
 /** Contexto de um watchdog. */
@@ -137,6 +179,49 @@ function runWatchdog(config: HoundsmanConfig, args: string[]): void {
 	);
 }
 
+/**
+ * Subcomando `findings` — triagem/correção dos findings (list/show/set/done/reset/
+ * sync/summary/batch/verify/path). Deixa o agente interagir com o estado sem abrir
+ * o JSON. O `verify` é assíncrono (consulta opcional ao Jev) — roteado à parte.
+ */
+async function runFindings(config: HoundsmanConfig, args: string[]): Promise<void> {
+	const sub = args.find((arg) => !arg.startsWith("-"));
+	const result =
+		sub === "verify"
+			? await runVerifyCommand(config, args)
+			: runFindingsCommand(config, args);
+	if (result.exitCode !== 0) {
+		console.error(result.output);
+		process.exit(result.exitCode);
+	}
+	console.log(result.output);
+}
+
+/** Abre a URL no navegador padrão (best-effort, por plataforma). */
+function openBrowser(url: string): void {
+	try {
+		const command =
+			process.platform === "win32"
+				? ["cmd", "/c", "start", "", url]
+				: process.platform === "darwin"
+					? ["open", url]
+					: ["xdg-open", url];
+		Bun.spawn(command, { stdout: "ignore", stderr: "ignore" });
+	} catch {
+		// best-effort — se não abrir, o usuário copia a URL.
+	}
+}
+
+/** Subcomando `server` — sobe a UI local de triagem. */
+function runServer(config: HoundsmanConfig, args: string[]): void {
+	const port = Number(readFlag(args, "--port")) || 7331;
+	const host = readFlag(args, "--host") ?? "127.0.0.1";
+	const { url } = startServer({ config, port, host });
+	console.log(`[houndsman] servidor em ${url}`);
+	console.log("[houndsman] Ctrl+C para encerrar.");
+	if (args.includes("--open")) openBrowser(url);
+}
+
 /** Passo 1/3 — preparar ou finalizar. */
 async function runReview(config: HoundsmanConfig, args: string[]): Promise<void> {
 	const opts = parseReviewArgs(args, resolveArtifactDir(config));
@@ -187,11 +272,17 @@ export async function main(): Promise<void> {
 			return;
 		case "doctor":
 		case "check":
-			runDoctor(config);
+			await runDoctor(config);
 			return;
 		case "watchdog":
 			runWatchdog(config, rest);
 			return;
+		case "findings":
+			await runFindings(config, rest);
+			return;
+		case "server":
+			runServer(config, rest);
+			return;
 		case undefined:
 			await runReview(config, rest);
 			return;

package/src/core/assets.ts

@@ -11,10 +11,21 @@ import { join } from "node:path";
 /** Diretório de assets markdown embarcados no pacote. */
 export const SKILL_DIR = join(import.meta.dir, "..", "skill");
 
+/** Diretório de assets de mídia do pacote (root `assets/` — logo etc.). */
+export const MEDIA_DIR = join(import.meta.dir, "..", "..", "assets");
+
 /** Nome do arquivo de schema de output dos watchdogs. */
 export const OUTPUT_FORMAT_FILE = "OUTPUT-FORMAT.md";
 
+/** Nome do arquivo-base do skill (`SKILL.md`) — entry point escrito para cada harness. */
+export const SKILL_FILE = "SKILL.md";
+
 /** Caminho absoluto de um asset embarcado em `src/skill/`. */
 export function assetPath(fileName: string): string {
 	return join(SKILL_DIR, fileName);
 }
+
+/** Caminho absoluto de um asset de mídia em `assets/` (ex.: a logo). */
+export function mediaPath(fileName: string): string {
+	return join(MEDIA_DIR, fileName);
+}

package/src/core/brief.ts

@@ -1,8 +1,8 @@
 /**
  * Renderização do brief de um watchdog (biblioteca) — `defaultRenderBrief`.
  *
- * O procedimento (`PROCEDURE`) é compartilhado por todos os watchdogs; o que era
- * protocolo específico vive nas regras do watchdog (`rules`).
+ * O procedimento (`PROCEDURE`) é compartilhado por todos os watchdogs; o que é
+ * específico do domínio vive nas regras do watchdog (`rules`).
  */
 
 import {
@@ -17,7 +17,6 @@ import {
 
 /**
  * Procedimento de revisão — compartilhado por todos os watchdogs.
- * Substitui o antigo protocolo genérico de 5 passos + o ponteiro `PROTOCOL_GLOB`.
  */
 export const PROCEDURE: readonly string[] = [
 	"1. **FILTER** — descarte o que não for do seu domínio (ver *Prioridade de leitura* e *Não carregar*).",
@@ -78,14 +77,35 @@ function optionalList(title: string, items: readonly string[] | undefined): stri
 	return [`## ${title}`, "", ...items.map((item) => `- ${item}`), ""];
 }
 
-/** Lista de arquivos do domínio com status. */
+/** Lista de arquivos do domínio com status (e churn, quando disponível). */
 function fileItems(args: WatchdogRenderArgs): string[] {
 	return args.files.map((file) => {
 		const status = args.statuses[file]?.status ?? "modified";
-		return `- \`${file}\` (${status})`;
+		const churn = args.churn?.[file];
+		const delta = churn ? `, +${churn.additions}/−${churn.deletions}` : "";
+		return `- \`${file}\` (${status}${delta})`;
 	});
 }
 
+/**
+ * Arquivos do domínio fora do orçamento (triage de PRs grandes): o watchdog NÃO
+ * deve lê-los, mas precisa registrá-los em `skipped` — cobertura honesta.
+ */
+function overflowSection(args: WatchdogRenderArgs): string[] {
+	const overflow = args.overflow ?? [];
+	if (overflow.length === 0) return [];
+	return [
+		"## Fora do orçamento (NÃO revisar)",
+		"",
+		`> ${overflow.length} arquivo(s) do seu domínio ficaram fora do orçamento`,
+		"> (menor churn). Não os leia: registre-os em `skipped` com o motivo",
+		'> "budget" para que a cobertura do relatório fique honesta.',
+		"",
+		...overflow.map(codeItem),
+		"",
+	];
+}
+
 /** Seção de deletados (breaking change) — só p/ watchdogs com `breakingChange`. */
 function deletedSection(args: WatchdogRenderArgs, def: WatchdogDefinition): string[] {
 	if (!def.breakingChange || args.deleted.length === 0) return [];
@@ -141,6 +161,8 @@ export function defaultRenderBrief(
 		"",
 	);
 
+	lines.push(...overflowSection(args));
+
 	if (args.candidates && args.candidates.length > 0) {
 		lines.push(...renderBriefCandidates(args.candidates));
 	}