@payconductor/houndsman 0.0.0-stage → 0.1.0

package/src/skill/houndsman.md

@@ -0,0 +1,239 @@
+# houndsman — {{projectName}} (v1)
+
+> **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á.
+
+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/`.
+
+**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).
+
+## Quem executa o quê
+
+- **Você** só invoca o skill: `/houndsman`. 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:
+
+| Passo | Comando | Quem roda | Resultado |
+|---|---|---|---|
+| 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` |
+
+> Por que comandos separados? Entre o passo 1 e o 3 acontece trabalho de LLM (os subagentes).
+
+**Arquitetura:**
+
+- N watchdogs especializados por domínio de negócio.
+- **Cada watchdog declara o que revisa** (`classify` em `.houndsman/watchdogs/<id>.ts`:
+  `{ type?: "filename" | "content", value }` — `value` é sempre regex; `filename`
+  (padrão) casa o caminho, `content` casa o conteúdo do arquivo). Não há arquivo de
+  classificação à parte nem fallback: arquivo fora dos padrões fica `unclassified`.
+- **Fonte única de verdade do projeto:** `houndsman.config.ts` (`HoundsmanConfig`) +
+  `.houndsman/` (`watchdogs/<id>.ts`: regras + escopo + foco + `classify`;
+  `exclusions.ts`: filtros; `doc-mappings.ts`: docs).
+- **O motor genérico** vive no pacote `@payconductor/houndsman` (`core/` + `cli/`). O markdown
+  do skill vive em `src/skill/`.
+- **As regras refletem os padrões APLICADOS hoje** — não validar práticas que o projeto
+  não adota. Regra sem aplicação real no código gera falso positivo.
+- 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)
+
+O contexto vem da **descrição da PR** via GitHub CLI (`gh`), quando disponível e logado.
+Um subagente executa o CLI e resume:
+
+```
+Você é o subagente de contexto do houndsman. Execute `houndsman context`;
+leia o `context-brief.md` indicado na saída; siga as instruções e grave
+`context-summary.json`. Retorne `objective`/`motivation`/`changeSummary` ou "indisponível".
+```
+
+- O CLI detecta `gh` (**ausente/sem login/sem PR** → grava `available:false` e sai com código 0).
+- O subagente resume em `context-summary.json`: `objective` (1 frase, ≤ 200 chars),
+  `motivation` (1 frase, ≤ 240 chars) e `changeSummary` (≤ 4 bullets, ≤ 160 chars cada),
+  em pt-BR e baseado **somente** no `context.json`. **Curto de propósito.**
+- Sem contexto → a revisão segue normalmente e a seção é omitida (registrado no `manifest.json`).
+
+---
+
+## Passo 1 — Preparar (skill executa)
+
+```bash
+houndsman --base main
+```
+
+Gera em `.houndsman/.runs/<branch-slug>/`:
+
+| Artefato | Conteúdo |
+|---|---|
+| `classification.json` | Watchdogs ativados por arquivo + status (A/M/D/R) |
+| `candidates.json` | Indícios da pré-análise Jev (regra + arquivo + confiança) |
+| `briefs/<watchdog>.md` | Instruções prontas para cada subagente |
+| `manifest.json` | Resumo: watchdogs, arquivos, deletados, status, contexto, Jev |
+
+**Excluídos automaticamente:** lock files, `dist/`, `build/`, `.env*`, imagens, source
+maps (padrões do projeto em `.houndsman/exclusions.ts`).
+**Deletados:** não entram como conteúdo; vão para o brief de watchdogs com
+`breakingChange` como candidatos a **breaking change**.
+
+### Pré-análise Jev (Passo 1.5, opcional)
+
+Se `TYPESAFE_API_KEY` estiver definida, cada arquivo é avaliado pelo modelo **Jev** contra
+as regras atômicas dos watchdogs. Respostas acima do limiar viram **candidatos** em
+`candidates.json` e entram no brief como *warm start* — o subagente **confirma ou refuta**.
+
+- **Não é achado**: candidatos não bloqueiam.
+- **Falha-aberto**: sem chave / erro / timeout → `available:false`; a revisão segue idêntica.
+- Desativar: `houndsman --no-jev`.
+
+---
+
+## Passo 2 — Revisar (skill despacha os subagentes)
+
+Um subagente por brief, todos no mesmo bloco de tool calls. O prompt é o próprio brief:
+
+```
+Leia e execute o brief: .houndsman/.runs/<branch-slug>/briefs/<watchdog-id>.md
+Você é o watchdog <watchdog-id> do {{projectName}}.
+```
+
+Cada subagente grava `findings/<watchdog-id>.json` (schema `.houndsman/core/skill/OUTPUT-FORMAT.md`).
+Sem achados → `"findings": []` (arquivo obrigatório).
+
+**NUNCA enviar:** `git diff` completo · histórico de commits · arquivos de outros domínios ·
+`AGENTS.md` completo (já está no contexto global).
+
+---
+
+## Passo 3 — Finalizar (skill executa)
+
+```bash
+houndsman --finalize
+```
+
+Falha com mensagem clara se faltar algum `findings/<watchdog>.json`. Quando todos existem:
+1. Valida o schema de cada JSON
+2. Deduplica achados por `(file, line, rule)` mesclando watchdogs sobrepostos
+3. Agrupa por severidade: ❌ blocking > ⚠️ attention > 💡 suggestion > 🔎 nit
+4. Grava `.houndsman/.runs/<branch-slug>/review.md` + tabela de cobertura
+5. Anexa os candidatos Jev não confirmados em `🔎 Candidatos não verificados` (não bloqueiam)
+
+---
+
+## Estrutura do Relatório
+
+```markdown
+# Review — [branch]
+
+**Data:** YYYY-MM-DD
+**Watchdogs ativos:** [lista]
+**Achados:** N bloqueantes · N atenção · N sugestões · N nits
+
+## Contexto da PR
+**PR:** #123 Título — url
+**Branch:** `feature/x` → `main`
+**Objetivo:** ...
+**Resumo das alterações:**
+- ...
+
+## ❌ blocking
+- **<regra>** — `arquivo:linha` · _<watchdogs>_
+  <mensagem>
+  **Ação:** <ação>
+
+## Cobertura
+| Watchdog | Arquivos revisados | Findings |
+|---|---|---|
+
+## Conclusão
+**Status:** ✅ Aprovado / ⚠️ Aprovado com Ressalvas / ❌ Mudanças Necessárias
+```
+
+---
+
+## Fluxo Completo
+
+```
+houndsman context (gh)         ──►  context.json ──► subagente ──► context-summary.json
+        ↓
+git diff --name-status (base...head)
+        ↓
+[1] houndsman                  ──►  classification.json + candidates.json + briefs/ + manifest.json
+        ↓
+[2] N subagentes em paralelo   ──►  findings/<watchdog>.json
+        ↓
+[3] houndsman --finalize       ──►  review.md
+```
+
+---
+
+## Invocação
+
+```
+/houndsman
+/houndsman feature/add-webhook-retry
+```
+
+Se a branch não for informada, detecta com `git branch --show-current`. Base do diff: `main`.
+
+**Comandos do CLI:**
+
+| Comando | Função |
+|---|---|
+| `houndsman context` | Passo 0 — contexto da PR via `gh` |
+| `houndsman` | Passo 1 — preparar (briefs + manifesto) |
+| `houndsman --finalize` | Passo 3 — gerar o relatório |
+| `houndsman watchdog <id>` | Contexto de um watchdog (`--json`, `--rules`) |
+| `houndsman setup` | Cria a configuração inicial do projeto |
+| `houndsman update` | Sincroniza os arquivos auto-gerados (`.houndsman/core`) |
+| `houndsman doctor` | Valida a configuração e o ambiente (anti-drift) |
+| `houndsman test` | Suíte de testes da lib |
+
+---
+
+## Anti-padrões
+
+- ❌ Enviar git diff completo para qualquer watchdog
+- ❌ Ativar watchdogs sem arquivos no seu domínio
+- ❌ Carregar documentação que o watchdog não precisa
+- ❌ Revisar arquivos gerados (lock files, builds, migrations)
+- ❌ Escrever markdown livre em vez do JSON de `OUTPUT-FORMAT.md`
+- ❌ Revisar arquivos `deleted` (não têm conteúdo) em vez de tratá-los como breaking change
+- ❌ Comentários genéricos ("código bom", "pode melhorar")
+- ❌ Sugestões de estilo triviais
+- ❌ Reescrever código completo — apenas apontar direção
+- ❌ Inventar objetivo/motivação da PR — o resumo vem **só** do `gh`; sem `gh`, omitir a seção
+
+---
+
+## Manutenção das Regras
+
+> Alterar qualquer regra (adicionar, ajustar severidade, remover, corrigir escopo) → usar o
+> skill **`houndsman-update`** (`src/skill/houndsman-update.md`).
+> Regra de ouro: só é regra o que o projeto **aplica hoje** — prove com evidência no código
+> (regra negativa com 0 ocorrências = seguida → **manter**).
+> Após qualquer alteração, rodar `houndsman doctor` (anti-drift) + `houndsman test` + `ci:fix` + `ci:check`.
+
+---
+
+## Performance Esperada
+
+| Tamanho do PR | Watchdogs | Tempo |
+|---|---|---|
+| Pequeno (500 linhas) | 2-4 | ~30-60s |
+| Médio (5k linhas) | 4-7 | ~1-2 min |
+| Grande (50k linhas) | 7-10 | ~3-5 min |
+| Enorme (300k linhas) | 10-15 | ~5-8 min |

package/src/tests/fixtures/fake-project.ts

@@ -0,0 +1,64 @@
+/**
+ * "Project fake" usado pela suíte de testes da lib.
+ *
+ * Os testes validam o MOTOR (`core/`), não as regras de um projeto real —
+ * por isso usam esta configuração fictícia em vez da config do projeto real.
+ */
+
+import { defineHoundsmanConfig, type HoundsmanConfig } from "../../core/config";
+import { defineWatchdog } from "../../core/types";
+
+/** Watchdog A — regra bloqueante com spec Jev + outras severidades. */
+export const alphaWatchdog = defineWatchdog({
+	id: "alpha",
+	name: "Alpha",
+	description: "Watchdog A do projeto fake.",
+	scope: "src/alpha/**",
+	classify: [{ value: "^src/alpha/" }],
+	rules: [
+		{ severity: "blocking", text: "Nunca usar `any`.", jev: { kind: "noul" } },
+		{ severity: "attention", text: "Validar entrada do usuário." },
+		{ severity: "suggestion", text: "Evitar console.log." },
+	],
+	contextFiles: ["README.md"],
+});
+
+/** Watchdog B — cobre testes e um padrão de nome de arquivo. */
+export const betaWatchdog = defineWatchdog({
+	id: "beta",
+	name: "Beta",
+	description: "Watchdog B do projeto fake.",
+	scope: "src/beta/**, arquivos de teste e o arquivo especial",
+	classify: [
+		{ value: "^src/beta/" },
+		{ value: "\\.test\\.ts$" },
+		{ value: "special\\.ts$" },
+	],
+	rules: [
+		{
+			severity: "blocking",
+			text: "Nunca commitar segredos.",
+			jev: { kind: "noul", instructions: "O estado contém segredo hardcoded?" },
+		},
+		{ severity: "attention", text: "Evitar código morto." },
+	],
+	contextFiles: ["README.md"],
+});
+
+export const FAKE_WATCHDOG_DEFINITIONS = {
+	alpha: alphaWatchdog,
+	beta: betaWatchdog,
+};
+
+export type FakeWatchdogId = keyof typeof FAKE_WATCHDOG_DEFINITIONS;
+
+/** Configuração completa do projeto fake. */
+export const fakeHoundsmanConfig: HoundsmanConfig<FakeWatchdogId> =
+	defineHoundsmanConfig<FakeWatchdogId>({
+		projectName: "Fake Project",
+		artifactDir: "tmp/fake-review",
+		watchdogs: FAKE_WATCHDOG_DEFINITIONS,
+		exclusions: [/^dist\//, /\.lock$/],
+		docMappings: [[/^src\//, ["README.md"]]],
+		alwaysIncludeDocs: ["README.md"],
+	});