@payconductor/houndsman 0.13.0 → 0.16.0

package/src/skill/hunt.md

@@ -22,6 +22,66 @@ Os dois modos produzem os mesmos artefatos, usam o mesmo staging e o mesmo ciclo
 > maki e despacha outro harness. Siga os passos 0–3 normalmente; o comando CLI é para quem
 > quer rodar tudo no terminal.
 
+### Harness local (CLI) — profundidade por checklist
+
+`houndsman hunt` usa o mesmo `prepare`/`finalize`, mas cada watchdog roda headless. Para não
+trocar profundidade por velocidade:
+
+- o **`general` roda em três papéis separados** (sessões distintas): (1) **fluxo** — caça
+  achados sem devolver `checks`/`rules`; (2) **bookkeeping** — tarefa estreita, só vereditos
+  com `at` comprovado; (3) **adversarial** — sessão nova, com os achados já cobertos como
+  contexto, atacando as cinco classes (credencial/estado, capacidade, identificador,
+  idempotência, contrato). Antes, um único JSON de 60 KB misturava tudo e o revisor entregava
+  poucos achados com checklist “ok” sem lastro;
+- nos demais watchdogs, o prompt exige **uma verificação por fluxo/invariante** (`checks`:
+  `ok`/`gap`/`n/a` + `arquivo:linha`) e **uma por regra numerada** (`rules`);
+- **`n/a` não é cobertura**: só conta como verificado o `ok`/`gap` cujo `at` resolve para um
+  arquivo existente e uma linha dentro dele (e, quando o arquivo não está na raiz, não conta);
+- se a primeira resposta não cobrir o checklist, o harness **retoma a sessão** (`--resume`) e
+  pede só os vereditos pendentes; os achados das passadas são **unidos** (dedupe por
+  arquivo+linha+regra, maior severidade vence);
+- o prompt do `general` só pede o `businessSummary` quando o prepare **não** trouxe um modelo
+  da IA (gerar um resumo que seria rejeitado custava atenção do revisor);
+- o orçamento de exploração cresce com o tamanho do domínio (piso 6/10, teto 14/24 leituras);
+- a saída do maki concatena **todas** as mensagens do agente; o parser procura o último JSON
+  válido (bloco cercado ou objeto balanceado), não o primeiro `{`;
+- retry de saída inválida **retoma a mesma sessão** enviando só o schema — não refaz a
+  exploração inteira; e o system prompt do harness prioriza profundidade sobre economia de
+  tool calls;
+- `hunt-report.json` traz `rules`/`checks { expected, verified, missing, notApplicable, gaps }`,
+  `coverage` (`reviewed`/`skipped`/`undeclared`), o custo de cada passada extra (`checklist`,
+  `secondOpinion`) e a decisão sobre o modelo de intenção por watchdog. Desligue com
+  `--no-checklist`/`--no-second-opinion` (ou `hunt.checklist`/`hunt.secondOpinion: false`).
+
+### Golden set — medir em vez de contar
+
+Contagem de findings não mede profundidade: variantes diferentes amostram pontos diferentes do
+mesmo diff. O golden set **não gera** achados nem julga intenção — é uma lista de defeitos que
+você já confirmou no código (âncora), usada para dar nota a uma execução:
+
+- **recall** = quantos defeitos congelados a run encontrou;
+- **precisão** = quanto do que a run reportou cai num defeito congelado (o resto pode ser achado
+  legítimo ainda não triado — o relatório avisa);
+- **faltaram / fora do golden** = onde melhorar o brief/harness e o que ainda falta triar.
+
+```bash
+houndsman golden .houndsman/golden/<pr>.json              # todas as variantes da branch
+houndsman golden .houndsman/golden/<pr>.json --variant x  # uma variante
+```
+
+- formato: `{ "version": 1, "commit": "abc1234", "expected": [{ "id", "file", "line",
+  "tolerance", "match", "severity", "note" }] }`;
+- cada expectativa é uma **âncora** (arquivo + faixa de linha + trecho), nunca um fingerprint;
+  um finding comprova no máximo um defeito;
+- o `commit` é a referência do congelamento. Run que revisou **outro commit** é avaliada
+  normalmente, mas o relatório abre com **aviso** de commit divergente (não é erro): as linhas
+  podem ter se deslocado e a “falta” pode ser drift, não perda de profundidade — revalide o
+  golden antes de concluir;
+- `.houndsman/golden/` é massa local de avaliação (fica no `.gitignore` da camada), não
+  configuração do projeto;
+- saída gravada como `golden-<slug>.md|json` na run avaliada. Use para comparar
+  prompts/harness na **mesma** PR.
+
 ## Alvo da revisão
 
 Traduza o pedido do usuário para flags **antes** de começar:
@@ -47,10 +107,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`.
@@ -76,10 +137,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`
@@ -118,6 +183,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) |
 
@@ -129,6 +196,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`).
@@ -142,13 +214,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)
 
@@ -166,10 +247,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).
@@ -179,27 +260,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).
 
 ---
 
@@ -213,76 +368,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 · **Status:** ✅ Aprovado / ⚠️ Aprovado com Ressalvas / ❌ Mudanças Necessárias
 
-**Data:** YYYY-MM-DD
-**Watchdogs ativos:** [lista]
-**Achados:** N bloqueantes · N atenção · N sugestões · N nits
+## Resumo de negócio
+...
 
-## Contexto da PR
-**PR:** #123 Título — url
-**Branch:** `feature/x` → `main`
-**Objetivo:** ...
-**Resumo das alterações:**
-- ...
+## Pontos técnicos
+- **Contratos** — ...
 
-## Relatórios por domínio
-| Watchdog | Achados | Revisados | Relatório |
+## 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
         ↓

package/src/skill/train.md

@@ -147,6 +147,9 @@ Cada informação tem o seu campo — não espelhe a regra em vários lugares:
 
 > Severidade não é aspiração: se o projeto só aplica o padrão em 15/72 lugares, é `suggestion`.
 
+> A severidade é **derivada**, não escolhida na revisão: finding de regra usa a severidade
+> declarada aqui; emergente usa `impactClass`. O motor corrige divergências no `--finalize`.
+
 ---
 
 ## Pré-análise Jev (opcional)