@payconductor/houndsman 0.12.0 → 0.14.0

package/src/skill/hunt.md

@@ -8,6 +8,20 @@ Invocação: `/houndsman` (default), `/houndsman hunt` ou `/houndsman hunt pr 45
 O motor é o CLI **`houndsman`**; as regras do projeto ficam em `houndsman.config.ts` +
 `.houndsman/`.
 
+## Dois modos de execução
+
+| Modo | Quem usa | Requisitos | Quem despacha os briefs |
+|---|---|---|---|
+| **Skill `/houndsman hunt`** (padrão) | agente externo (Copilot/Claude/etc.) | nenhum | o próprio agente, via subagentes |
+| **CLI `houndsman hunt`** | operador/CI, sem agente | `houndsman hunt install` uma vez | o houndsman, via maki headless |
+
+Os dois modos produzem os mesmos artefatos, usam o mesmo staging e o mesmo ciclo
+`prepare → findings → finalize`. Nada muda no fluxo abaixo para quem usa a skill.
+
+> **Se você é o agente executando esta skill, NÃO rode `houndsman hunt`.** Ele instala/usa o
+> maki e despacha outro harness. Siga os passos 0–3 normalmente; o comando CLI é para quem
+> quer rodar tudo no terminal.
+
 ## Alvo da revisão
 
 Traduza o pedido do usuário para flags **antes** de começar:
@@ -33,10 +47,11 @@ mudanças antes de push.
 
 | 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` + triagem/status no storage |
+| 0. Contexto | `houndsman --pr` (via `gh`) | prepare | `context.json` + `context-brief.md` → `context-summary.json` (IA; sem IA, subagente) |
+| 1. Preparar | `houndsman` | skill | `classification.json` + `candidates.json` + `business-summary.json` + `briefs/` + `manifest.json` |
+| 1.5. Intenção | *(subagente)* | skill, só sem IA | `business-summary.json` enriquecido (`source: "reviewer"`) |
+| 2. Revisar | *(subagentes)* | skill (via `runSubagent`) | `findings/<watchdog>.json` (um por watchdog, incluindo `general`) |
+| 3. Finalizar | `houndsman --finalize` | skill | `review-resume.md` + triagem/status no storage |
 
 > 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`.
@@ -62,10 +77,14 @@ mudanças antes de push.
 
 ---
 
-## Passo 0 — Contexto da PR (subagente)
+## Passo 0 — Contexto da PR
 
 O contexto vem da **descrição da PR** via GitHub CLI (`gh`), quando disponível e logado.
-Um subagente executa o CLI e resume:
+
+**Com IA ligada** (`HOUNDSMAN_DEEP_SEEK_API_KEY`), o próprio `houndsman --pr 456` coleta o
+contexto e o resume (`AiContextSummarizer`) — **não despache subagente** para este passo.
+
+Sem IA, um subagente executa o CLI e resume:
 
 ```
 Você é o subagente de contexto do houndsman. Execute `houndsman context --pr 456`
@@ -104,6 +123,8 @@ staging dos subagentes em `<HOUNDSMAN_HOME>/work/<reviewId>/`:
 | `ast-summary.json` | Fatos estruturais + delta por arquivo (AST TS/JS) (storage) |
 | `ast-impact.json` | Importadores reversos e exports públicos alterados (storage) |
 | `candidates.json` | Indícios da pré-análise Jev (regra + arquivo + confiança) (storage) |
+| `business-summary.json` | Modelo de intenção (fluxos, invariantes, contratos, estados) (staging + storage) |
+| `business-brief.md` | Brief do passo de intenção (staging + storage) |
 | `briefs/<watchdog>.md` | Instruções prontas para cada subagente (staging + storage, para auditoria) |
 | `manifest.json` | Resumo: watchdogs, arquivos, deletados, status, contexto, Jev, orçamento (storage) |
 
@@ -115,6 +136,11 @@ staging dos subagentes em `<HOUNDSMAN_HOME>/work/<reviewId>/`:
 > símbolos adicionados/removidos/alterados, assinaturas e imports; o impacto reverso
 > (quem importa os arquivos alterados) aparece como mapa de leitura. É fail-open:
 > sem grammar/ABI, a revisão segue só com regex. Desative com `--no-ast`.
+>
+> **Trechos do diff:** cada brief recebe o patch `-U0` do seu domínio, com o teto
+> distribuído entre **todos** os arquivos (rateio igual + excedente por churn) — não há
+> arquivo "sem diff" só porque outro era maior. Trecho cortado vem com o marcador
+> `… [trecho truncado — abra o arquivo para o restante]`.
 
 **Excluídos automaticamente:** lock files, `dist/`, `build/`, `.env*`, imagens, source
 maps (padrões do projeto em `.houndsman/exclusions.ts`).
@@ -128,13 +154,22 @@ com **churn** (linhas adicionadas/removidas) por arquivo — o custo não cresce
 arquivos da PR. Cada brief recebe no máximo `budgets.maxFilesPerBrief` arquivos (default 40),
 **priorizados pelo maior churn**:
 
-- O excedente vai para a seção **Fora do orçamento (NÃO revisar)** do brief e o watchdog deve
-  registrá-lo em `skipped` — a tabela de **Cobertura** mostra o que ficou de fora (nunca some
-  silenciosamente).
+- No **`general`**, acima de **40 arquivos** ou **2.000 linhas alteradas** o prepare aplica o
+  **recorte por fluxo**: até 15 arquivos (os citados pelos fluxos do modelo de intenção + os de
+  maior churn), com diff de até 2k por arquivo. O restante vai para **Fora do recorte** e deve
+  ser registrado em `skipped` (`fora do fluxo`). A tabela de cobertura do resumo mostra
+  `Revisados`, `Fora do recorte` e `Faltam` (sem declaração).
+- O excedente do orçamento vai para a seção **Fora do recorte (NÃO revisar)** do brief e o
+  watchdog deve registrá-lo em `skipped` — a tabela de **Cobertura** mostra o que ficou de fora
+  (nunca some silenciosamente).
 - Isso mantém o contexto do subagente limitado mesmo num PR de 10k linhas com centenas de
   arquivos num único domínio.
 - Ajuste em `houndsman.config.ts`: `budgets: { maxFilesPerBrief: 60 }` e
   `concurrency: { jev: 8 }`. Valores não-positivos caem no default (o `doctor` avisa).
+- **Prioridade por caminho (opcional):** `priorities: [{ pattern, bonus?, maxRiskFromChurn? }]`.
+  O risco é `min(churn, maxRiskFromChurn) + bonus`: `bonus` promove caminho crítico (`db` +300,
+  `services` +200) e o teto satura o superchurn de caminho de baixa criticidade (`client` com
+  2.000 linhas reformatadas não passa de 120). A primeira regra que casar vence.
 
 ### Pré-análise Jev (Passo 1.5, opcional)
 
@@ -152,10 +187,10 @@ Cada `--finalize` grava o **commit revisado** (`reviewedSha` da review no storag
 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.
+`changedFiles`, `carried`) e o `review-resume.md` abre com um aviso.
 
 - Sem mudanças desde a última revisão → **no-op**: o prepare não gera briefs nem reescreve
-  artefatos (classification, manifest, review.md), e o `--finalize` também vira no-op — pare o
+  artefatos (classification, manifest, review-resume.md), e o `--finalize` também vira no-op — pare o
   fluxo aí (nenhum subagente é despachado).
 - 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).
@@ -165,27 +200,101 @@ arquivos alterados desde a última revisão — e **carrega** os findings dos ar
 
 ---
 
+## Passo 1.5 — Intenção da PR (subagente, condicional)
+
+O motor **sempre** grava `business-summary.json` (determinístico) e `business-brief.md`.
+Quando a IA está configurada (`HOUNDSMAN_DEEP_SEEK_API_KEY`), o prepare já gravou o modelo
+com `source: "ai"` e este passo é **pulado**.
+
+> **Quando pular (operacional):** se o prepare imprimir "Intenção da PR reconstruída pela IA"
+> ou `business-summary.json` tiver `source: "ai"`, não despache este subagente. Se a mensagem
+> for "Intenção da PR determinística", despache.
+
+Sem IA, despache **um** subagente antes dos watchdogs:
+
+```
+Leia e execute o brief de intenção: <staging>/business-brief.md
+Você é o passo de intenção do houndsman no {{projectName}}.
+Use como raiz de leitura o **Worktree:** indicado. Grave o JSON em
+`<staging>/business-summary.json` com `source: "reviewer"`.
+Não produza achados.
+```
+
+- O modelo descreve **o que a PR deve entregar** (fluxos, invariantes, contratos,
+estados) — não a estrutura do código.
+- Ele é lido por todos os briefs; o revisor `general` o reconstrói no primeiro passo da
+revisão e pode refiná-lo.
+- Falha do subagente mantém a versão determinística (fail-open).
+
+> **Obrigatório:** a revisão de lógica (`general`) nunca é opcional. Se o Passo 1.5 não
+> rodar, o `general` ainda reconstrói o modelo no próprio brief — a revisão degrada, mas
+> não perde o eixo de lógica/domínio.
+
+---
+
 ## Passo 2 — Revisar (skill despacha os subagentes)
 
-Um subagente por brief. Despache em **ondas** (ex.: até 8 subagentes por bloco de tool
-calls) — evita estourar limites de taxa quando há muitos watchdogs. O prompt é o próprio brief:
+Um subagente por brief. Despache **todos os briefs da onda no MESMO bloco de tool calls**
+(paralelo real) — não espere um terminar para despachar o próximo. Só divida em ondas
+menores se a plataforma recusar a concorrência.
+
+> **Custo:** cada subagente é um agente completo. Despacho serial transforma 8 briefs em
+> 8 × o tempo de um watchdog; o paralelo custa o do mais lento.
+
+> **`general` é obrigatório.** O motor injeta esse watchdog reservado em todos os ciclos
+> (com todos os arquivos alterados). Ele audita o fluxo inteiro e emite `Lógica:`/`Domínio:`.
+> Nunca remova o brief dele da onda. Despache-o primeiro (é o mais longo).
+
 
 > **Heartbeat:** antes de despachar cada onda, rode `houndsman status ping`. A UI usa esse
 > sinal (e não `updatedAt`) para saber que a execução está viva; sem ping por 10 min ela
 > mostra "Timeout na revisão".
 
+### Teste A/B (variantes)
+
+Para comparar duas formas de rodar a mesma PR (prompt, modelo, configuração, versão do
+houndsman), dê um **rótulo** a cada tentativa — cada variante é uma run própria
+(`(repo, branch, variante)`) e nada é apagado:
+
+```bash
+houndsman --pr 456 --variant baseline            # prepare da variante A
+# despache os briefs e grave findings/baseline
+houndsman --pr 456 --variant baseline --finalize
+
+houndsman --pr 456 --variant otimizado           # prepare da variante B
+# ...
+houndsman --pr 456 --variant otimizado --finalize
+
+houndsman compare --branch <head> --a baseline --b otimizado
+houndsman compare --list --branch <head>         # ver as runs e contagens
+```
+
+- `--variant <label>` vale para o comando default, `hunt`, `context`, `status`,
+  `findings` e `verify`; use o mesmo rótulo em todas as etapas.
+- Repetir a **mesma** variante: `--full` re-revisa o commit; para um teste realmente
+  limpo, use um rótulo novo.
+- `compare` grava `compare-<a>--<b>.md|.json` na run B (aparece nos artefatos da UI) e
+  mostra achados novos/sumidos, mudança de severidade, cobertura, tempo e tokens.
+- Sem rótulo, a run principal continua sendo a da branch (o `compare` assume A = principal
+  quando só `--b` é informado).
+
 ```
 Leia e execute o brief: <caminho absoluto impresso pelo prepare>/briefs/<watchdog-id>.md
 Você é o watchdog <watchdog-id> do {{projectName}}.
 Use como raiz de leitura o **Worktree:** indicado no brief (nunca o clone principal).
+O brief já traz os trechos alterados (`## Trechos alterados (diff)`): comece por eles.
+Respeite o **Orçamento de exploração** do brief (6 leituras/6 buscas; `general`: 10/10):
+se a prova não estiver no brief nem nesse orçamento, **não é achado**.
+Em `reviewedFiles`, liste apenas arquivos do seu domínio (subconjunto do brief).
 ```
 
 Cada subagente grava o `outputPath` indicado no brief (schema `.houndsman/core/skill/OUTPUT-FORMAT.md`).
-Sem achados → `"findings": []` (arquivo obrigatório). Arquivos na seção **Fora do orçamento**
-não são lidos: registre-os em `skipped`.
+Sem achados → `"findings": []` (arquivo obrigatório). Arquivos na seção **Fora do recorte**
+não são lidos: registre-os em `skipped` com o motivo (`budget` ou `fora do fluxo`).
 
 **NUNCA enviar:** `git diff` completo · histórico de commits · arquivos de outros domínios ·
-`AGENTS.md` completo (já está no contexto global).
+o `business-summary.json` inteiro (o brief já traz o recorte do domínio) · `AGENTS.md` completo
+(já está no contexto global).
 
 ---
 
@@ -199,76 +308,68 @@ houndsman --finalize              # alvo = branch atual
 Falha com mensagem clara se faltar algum `findings/<watchdog>.json` no staging. Quando todos existem:
 1. Valida o schema de cada JSON
 2. Deduplica achados por `(file, line, rule)` mesclando watchdogs sobrepostos
-3. 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
-4. Grava o `review.md` abrindo pelo **sumário**: contexto, relatórios por domínio, cobertura e
-   conclusão — antes dos achados
-5. Agrupa os achados por severidade (❌ blocking > ⚠️ attention > 💡 suggestion > 🔎 nit) e
-   **por arquivo** dentro de cada severidade (navegabilidade em PRs grandes)
-6. Anexa os candidatos Jev não confirmados em `🔎 Candidatos não verificados` ao final
-   (não bloqueiam)
-7. Persiste a **triagem** no storage — um `id` curto e um `fingerprint` de conteúdo por
-   finding, preservados entre execuções9. Marca como **`done`** os findings que sumiram do relatório (corrigidos manualmente entre
+3. Persiste a **triagem** no storage — um `id` curto e um `fingerprint` de conteúdo por
+   finding, preservados entre execuções
+4. Marca como **`done`** os findings que sumiram do relatório (corrigidos manualmente entre
    revisões) e **resolve as conversas correspondentes no GitHub** — só as ainda abertas, e
-   falha-aberto (sem `gh`/PR o relatório segue igual)
+   falha-aberto (sem `gh`/PR o resumo segue igual)
+5. Grava o **resumo final** (`review-resume.md`): negócio, pontos técnicos, **tabela de
+   cobertura por domínio** (achados · revisados/esperados · faltam), candidatos não
+   confirmados e **conclusão**. É o único relatório em markdown — os achados ficam na triagem
+   (`findings`, UI), sem serem duplicados em arquivo
+
+> **Resultado da revisão:** leia o `review-resume.md` (a saída do `--finalize` imprime o
+> caminho no storage). Ele é o contexto final para responder ao usuário sobre o resultado;
+> os achados individuais vêm de `findings list --json`.
+
 Após finalizar, corrija os achados com a capability **`fix`** (`fix.md`): a UI ou os
 comandos `findings` levam do achado à correção.
 
 ---
 
-## Estrutura do Relatório
+## Estrutura do Resumo Final
 
 ```markdown
-# Review — [branch]
+# Resumo da revisão — [branch]
 
-**Data:** YYYY-MM-DD
-**Watchdogs ativos:** [lista]
-**Achados:** N bloqueantes · N atenção · N sugestões · N nits
+**Data:** YYYY-MM-DD · **Status:** ✅ Aprovado / ⚠️ Aprovado com Ressalvas / ❌ Mudanças Necessárias
 
-## Contexto da PR
-**PR:** #123 Título — url
-**Branch:** `feature/x` → `main`
-**Objetivo:** ...
-**Resumo das alterações:**
-- ...
+## Resumo de negócio
+...
 
-## Relatórios por domínio
-| Watchdog | Achados | Revisados | Relatório |
+## Pontos técnicos
+- **Contratos** — ...
+
+## Cobertura por domínio
+| Domínio | Achados | Revisados | Faltam |
 |---|---|---|---|
 
-## Cobertura
-| Watchdog | Arquivos revisados | Findings |
-|---|---|---|
+## Candidatos não verificados (N)   ← se houver
+- `arquivo` · severity · regra
 
 ## Conclusão
-**Status:** ✅ Aprovado / ⚠️ Aprovado com Ressalvas / ❌ Mudanças Necessárias
-
-## ❌ blocking
-### `src/routes/order-route.ts`
-- **<regra>** — `src/routes/order-route.ts:5` · _<watchdogs>_
-  <mensagem>
-  **Ação:** <ação>
-
-## 🔎 Candidatos não verificados (Jev)   ← se houver, sempre ao final
+**Resumo:** N bloqueantes · N atenção · N sugestões · N nits.
 ```
 
-> O **sumário** (relatórios por domínio, cobertura e conclusão) vem **antes** dos achados;
-> os pontos específicos ficam no fim.
+> Tabelas e conclusão têm orçamento reservado: crescer o texto de negócio nunca as corta.
+> Achados individuais (com `id` de triagem) vivem na UI (`Findings`) e em `findings list --json`.
 
 ---
 
 ## Fluxo Completo
 
 ```
-houndsman context (gh)         ──►  context.json ──► subagente ──► context-summary.json
+houndsman --pr (gh)            ──►  context.json ──► prepare resume (IA) ──► context-summary.json
         ↓
 git diff --name-status (base...head)
         ↓
-[1] houndsman                  ──►  storage (classification/candidates/manifest) + briefs/ no staging
+[1] houndsman                  ──►  storage (classification/candidates/business/manifest) + briefs/ no staging
+        ↓
+[1.5] subagente de intenção    ──►  business-summary.json (só quando não veio da IA)
         ↓
-[2] N subagentes em paralelo   ──►  findings/<watchdog>.json no staging
+[2] N+1 subagentes em paralelo ──►  findings/<watchdog>.json (+ findings/general.json)
         ↓
-[3] houndsman --finalize       ──►  review.md + triagem no storage (review_done)
+[3] houndsman --finalize       ──►  review-resume.md + triagem no storage (review_done)
         ↓
 [4] server (UI)                ──►  validar a revisão + marcar decision: execute
         ↓
@@ -306,6 +407,28 @@ completo) · `--no-jev` · `--no-ast` · `--fail-on-blocking` (com `--finalize`)
 
 ---
 
+## Harness local (opcional, fora da skill)
+
+Para rodar a revisão inteira pelo terminal, sem agente externo, o mesmo `hunt` existe como
+comando. A instalação é única e fica fora do projeto:
+
+```bash
+houndsman hunt install            # baixa o maki fixado em <HOUNDSMAN_HOME>/tools/maki
+houndsman hunt doctor             # diagnóstico (não falha se o maki não existir)
+houndsman hunt --pr 456           # prepare → um processo maki por brief → finalize
+houndsman hunt --pr 456 --allow-partial  # finaliza mesmo se algum watchdog falhar
+```
+
+- Reaproveita a credencial já configurada (`HOUNDSMAN_DEEP_SEEK_API_KEY` → `DEEPSEEK_API_KEY`)
+  e o modelo de `ai.model` (default `deepseek/deepseek-v4-pro`).
+- O watchdog **não recebe escrita**: o maki devolve o JSON na resposta final e o houndsman
+  valida e grava `findings/<watchdog>.json`. `bash`, rede e edição ficam negados.
+- Sem maki instalado, nada muda para a skill: `setup`, `doctor` e `/houndsman hunt` seguem
+  funcionando.
+- O relatório do harness fica em `hunt-report.json` (sessões, custo e tokens por watchdog).
+
+---
+
 ## Anti-padrões
 
 - ❌ Enviar git diff completo para qualquer watchdog