@payconductor/houndsman 0.7.0 → 0.8.0

package/src/skill/SKILL.md

@@ -1,7 +1,7 @@
 ---
 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)'
+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. Quando o alvo é uma PR (#456, “PR 456” ou URL do GitHub), revisa em worktree isolado automaticamente. Capabilities: `hunt` (revisar a PR), `train` (atualizar regras), `fix` (corrigir achados), `verify` (violações resolvidas?).'
+argument-hint: 'Capability e alvo: hunt --pr 456 | hunt feature/x | train | fix | verify (default: hunt)'
 ---
 
 # houndsman — {{projectName}}
@@ -26,16 +26,50 @@ especialista por domínio · **finding** = um achado da revisão · **Jev** = pr
 ## 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
+/houndsman                          → hunt (default)
+/houndsman hunt                     → revisar a Pull Request
+/houndsman hunt, revise a pr 456    → hunt da PR 456 (worktree automático)
+/houndsman hunt feature/minha-branch → hunt da branch (clone atual)
+/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.
+Um argumento extra é o alvo da capability. Escolha a capability pelo que o usuário quer,
+leia o documento correspondente em `.houndsman/core/skill/<capability>.md` e siga-o.
+
+### Alvo da revisão (PR × branch)
+
+Interprete o alvo em linguagem natural **antes** de rodar o CLI:
+
+| O usuário disse | Alvo | Flags |
+|---|---|---|
+| `PR 456`, `#456`, `pull 456`, `456` (número sozinho), `https://github.com/org/repo/pull/456` | PR | `--pr 456` |
+| `feature/minha-branch`, `branch feature/x` | branch | `--branch feature/minha-branch` |
+| nada | branch atual | *(sem flag)* |
+
+> **PR citada ⇒ worktree obrigatório.** Nunca rode `houndsman` “puro” para revisar uma PR que o
+> usuário nomeou: o prepare precisa criar o worktree dedicado. Também **nunca** faça
+> `git checkout` da PR no clone principal — é isso que permite revisar várias PRs ao mesmo
+> tempo.
+
+Sequência para uma PR (ex.: 456):
+
+```bash
+houndsman context --pr 456
+houndsman --pr 456                 # cria/reusa o worktree e imprime o caminho
+# despache os briefs (cada um traz **Worktree:** <path>)
+houndsman --pr 456 --finalize
+```
+
+- O worktree vive em `<repo>/.houndsman/worktrees/<repo>/<branch>` (detached no commit da PR)
+  e é reutilizado nas próximas execuções da mesma branch. Ele fica **dentro do workspace**
+  (e o staging também) para o agente ler/executar sem prompts de permissão.
+- Use `--worktree <path>` para aproveitar um worktree já existente.
+- O prepare imprime `PR #456 — <head> → <base>`; use `<head>` em `status ping`,
+  `findings` e `verify` (`--branch <head>`). A review guarda o worktree, então esses
+  comandos leem a árvore correta.
+- PR de fork também funciona: o CLI busca `refs/pull/<n>/head`.
 
 > **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`.

package/src/skill/hunt.md

@@ -4,16 +4,32 @@
 > (`.agents/skills/houndsman/SKILL.md` e `.claude/skills/houndsman/SKILL.md`).
 
 Revisão de PR: classificação de arquivos → revisão paralela por domínio → consolidação.
-Invocação: `/houndsman` (default) ou `/houndsman hunt`. O motor é o CLI **`houndsman`**;
-as regras do projeto ficam em `houndsman.config.ts` + `.houndsman/`.
+Invocação: `/houndsman` (default), `/houndsman hunt` ou `/houndsman hunt pr 456`.
+O motor é o CLI **`houndsman`**; as regras do projeto ficam em `houndsman.config.ts` +
+`.houndsman/`.
+
+## Alvo da revisão
+
+Traduza o pedido do usuário para flags **antes** de começar:
+
+| Pedido | Alvo | Flag |
+|---|---|---|
+| “revise a PR 456”, “#456”, URL `.../pull/456` | PR | `--pr 456` |
+| “revise a branch feature/x” | branch | `--branch feature/x` |
+| “revise esta PR / o que mudou” | branch atual | *(sem flag)* |
+
+> **Se o alvo é uma PR, use worktree.** Rode `houndsman --pr 456` (não `houndsman`), nunca faça
+> checkout no clone principal e use o caminho impresso na saída como raiz dos subagentes.
+> Isso permite revisar outras PRs em paralelo, cada uma na sua árvore.
 
 **Quando usar:** revisar PR antes de merge · code review de feature branch · validar
 mudanças antes de push.
 
 > **Harness nativo (opcional):** além deste skill, o CLI tem `houndsman hunt` — o mesmo
 > fluxo executado pelo próprio houndsman, com tools read-only, investigação por evidência
-> e `VERIFY` obrigatório. Use `houndsman hunt --dry-run` para inspecionar sem IA. Detalhes
-> em `docs/HARNESS.md`.
+> e `VERIFY` obrigatório. Use `houndsman hunt --dry-run` para inspecionar sem IA. Para uma
+> PR específica, `houndsman hunt --pr 456` roda no worktree automaticamente. Detalhes em
+> `docs/HARNESS.md`.
 
 ## Quem executa o quê
 
@@ -56,7 +72,8 @@ O contexto vem da **descrição da PR** via GitHub CLI (`gh`), quando disponíve
 Um subagente executa o CLI e resume:
 
 ```
-Você é o subagente de contexto do houndsman. Execute `houndsman context`;
+Você é o subagente de contexto do houndsman. Execute `houndsman context --pr 456`
+(ou `houndsman context --worktree <path>` se o prepare já criou o worktree);
 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".
 ```
@@ -72,9 +89,16 @@ leia o `context-brief.md` indicado na saída; siga as instruções e grave
 ## Passo 1 — Preparar (skill executa)
 
 ```bash
-houndsman --base main
+houndsman --pr 456          # alvo = PR (cria/reusa o worktree)
+houndsman --base main       # alvo = branch atual (clone principal)
 ```
 
+Quando o alvo é uma PR, o prepare consulta a PR via `gh`, busca `refs/pull/<n>/head`, cria o
+worktree **detached** em `<repo>/.houndsman/worktrees/<repo>/<branch>` e imprime o caminho.
+Cada brief passa a trazer `**Worktree:** <path>` — essa é a raiz que os subagentes devem ler.
+Guarde também a linha `PR #456 — <head> → <base>`: `<head>` é a branch a usar em
+`status ping`, `findings` e `verify`.
+
 Grava os artefatos no **storage global** (SQLite em `<HOUNDSMAN_HOME>/houndsman.db`) e o
 staging dos subagentes em `<HOUNDSMAN_HOME>/work/<reviewId>/`:
 
@@ -157,6 +181,7 @@ calls) — evita estourar limites de taxa quando há muitos watchdogs. O prompt
 ```
 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).
 ```
 
 Cada subagente grava o `outputPath` indicado no brief (schema `.houndsman/core/skill/OUTPUT-FORMAT.md`).
@@ -171,7 +196,8 @@ não são lidos: registre-os em `skipped`.
 ## Passo 3 — Finalizar (skill executa)
 
 ```bash
-houndsman --finalize
+houndsman --pr 456 --finalize     # alvo = PR (reusa o worktree gravado)
+houndsman --finalize              # alvo = branch atual
 ```
 
 Falha com mensagem clara se faltar algum `findings/<watchdog>.json` no staging. Quando todos existem:

package/src/tests/__snapshots__/baseline.test.ts.snap

@@ -200,8 +200,8 @@ exports[`baseline — camada gerada setup gera os mesmos arquivos e conteúdos 2
   ".agents/skills/houndsman/SKILL.md": 
 "---
 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)'
+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. Quando o alvo é uma PR (#456, “PR 456” ou URL do GitHub), revisa em worktree isolado automaticamente. Capabilities: \`hunt\` (revisar a PR), \`train\` (atualizar regras), \`fix\` (corrigir achados), \`verify\` (violações resolvidas?).'
+argument-hint: 'Capability e alvo: hunt --pr 456 | hunt feature/x | train | fix | verify (default: hunt)'
 ---
 
 # houndsman — acme
@@ -226,16 +226,50 @@ especialista por domínio · **finding** = um achado da revisão · **Jev** = pr
 ## 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
+/houndsman                          → hunt (default)
+/houndsman hunt                     → revisar a Pull Request
+/houndsman hunt, revise a pr 456    → hunt da PR 456 (worktree automático)
+/houndsman hunt feature/minha-branch → hunt da branch (clone atual)
+/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.
+Um argumento extra é o alvo da capability. Escolha a capability pelo que o usuário quer,
+leia o documento correspondente em \`.houndsman/core/skill/<capability>.md\` e siga-o.
+
+### Alvo da revisão (PR × branch)
+
+Interprete o alvo em linguagem natural **antes** de rodar o CLI:
+
+| O usuário disse | Alvo | Flags |
+|---|---|---|
+| \`PR 456\`, \`#456\`, \`pull 456\`, \`456\` (número sozinho), \`https://github.com/org/repo/pull/456\` | PR | \`--pr 456\` |
+| \`feature/minha-branch\`, \`branch feature/x\` | branch | \`--branch feature/minha-branch\` |
+| nada | branch atual | *(sem flag)* |
+
+> **PR citada ⇒ worktree obrigatório.** Nunca rode \`houndsman\` “puro” para revisar uma PR que o
+> usuário nomeou: o prepare precisa criar o worktree dedicado. Também **nunca** faça
+> \`git checkout\` da PR no clone principal — é isso que permite revisar várias PRs ao mesmo
+> tempo.
+
+Sequência para uma PR (ex.: 456):
+
+\`\`\`bash
+houndsman context --pr 456
+houndsman --pr 456                 # cria/reusa o worktree e imprime o caminho
+# despache os briefs (cada um traz **Worktree:** <path>)
+houndsman --pr 456 --finalize
+\`\`\`
+
+- O worktree vive em \`<repo>/.houndsman/worktrees/<repo>/<branch>\` (detached no commit da PR)
+  e é reutilizado nas próximas execuções da mesma branch. Ele fica **dentro do workspace**
+  (e o staging também) para o agente ler/executar sem prompts de permissão.
+- Use \`--worktree <path>\` para aproveitar um worktree já existente.
+- O prepare imprime \`PR #456 — <head> → <base>\`; use \`<head>\` em \`status ping\`,
+  \`findings\` e \`verify\` (\`--branch <head>\`). A review guarda o worktree, então esses
+  comandos leem a árvore correta.
+- PR de fork também funciona: o CLI busca \`refs/pull/<n>/head\`.
 
 > **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\`.
@@ -251,8 +285,8 @@ Escolha a capability pelo que o usuário quer, leia o documento correspondente e
   ".claude/skills/houndsman/SKILL.md": 
 "---
 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)'
+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. Quando o alvo é uma PR (#456, “PR 456” ou URL do GitHub), revisa em worktree isolado automaticamente. Capabilities: \`hunt\` (revisar a PR), \`train\` (atualizar regras), \`fix\` (corrigir achados), \`verify\` (violações resolvidas?).'
+argument-hint: 'Capability e alvo: hunt --pr 456 | hunt feature/x | train | fix | verify (default: hunt)'
 ---
 
 # houndsman — acme
@@ -277,16 +311,50 @@ especialista por domínio · **finding** = um achado da revisão · **Jev** = pr
 ## 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
+/houndsman                          → hunt (default)
+/houndsman hunt                     → revisar a Pull Request
+/houndsman hunt, revise a pr 456    → hunt da PR 456 (worktree automático)
+/houndsman hunt feature/minha-branch → hunt da branch (clone atual)
+/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. Escolha a capability pelo que o usuário quer,
+leia o documento correspondente em \`.houndsman/core/skill/<capability>.md\` e siga-o.
+
+### Alvo da revisão (PR × branch)
+
+Interprete o alvo em linguagem natural **antes** de rodar o CLI:
+
+| O usuário disse | Alvo | Flags |
+|---|---|---|
+| \`PR 456\`, \`#456\`, \`pull 456\`, \`456\` (número sozinho), \`https://github.com/org/repo/pull/456\` | PR | \`--pr 456\` |
+| \`feature/minha-branch\`, \`branch feature/x\` | branch | \`--branch feature/minha-branch\` |
+| nada | branch atual | *(sem flag)* |
+
+> **PR citada ⇒ worktree obrigatório.** Nunca rode \`houndsman\` “puro” para revisar uma PR que o
+> usuário nomeou: o prepare precisa criar o worktree dedicado. Também **nunca** faça
+> \`git checkout\` da PR no clone principal — é isso que permite revisar várias PRs ao mesmo
+> tempo.
+
+Sequência para uma PR (ex.: 456):
+
+\`\`\`bash
+houndsman context --pr 456
+houndsman --pr 456                 # cria/reusa o worktree e imprime o caminho
+# despache os briefs (cada um traz **Worktree:** <path>)
+houndsman --pr 456 --finalize
 \`\`\`
 
-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.
+- O worktree vive em \`<repo>/.houndsman/worktrees/<repo>/<branch>\` (detached no commit da PR)
+  e é reutilizado nas próximas execuções da mesma branch. Ele fica **dentro do workspace**
+  (e o staging também) para o agente ler/executar sem prompts de permissão.
+- Use \`--worktree <path>\` para aproveitar um worktree já existente.
+- O prepare imprime \`PR #456 — <head> → <base>\`; use \`<head>\` em \`status ping\`,
+  \`findings\` e \`verify\` (\`--branch <head>\`). A review guarda o worktree, então esses
+  comandos leem a árvore correta.
+- PR de fork também funciona: o CLI busca \`refs/pull/<n>/head\`.
 
 > **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\`.
@@ -300,10 +368,12 @@ Escolha a capability pelo que o usuário quer, leia o documento correspondente e
 "
 ,
   ".houndsman/.gitignore": 
-"# Diretórios gerados pelo houndsman — \`core/\` é regenerado por \`houndsman update\`
-# e \`.runs/\` guarda os artefatos de revisão.
+"# Diretórios gerados pelo houndsman — \`core/\` é regenerado por \`houndsman update\`.
+# \`work/\` e \`worktrees/\` são runtime de revisão (staging e worktrees).
 core/
 .runs/
+work/
+worktrees/
 "
 ,
   ".houndsman/core/types.ts": 
@@ -594,7 +664,7 @@ exports[`baseline — camada gerada setup gera os mesmos arquivos e conteúdos 3
   },
   {
     "file": ".houndsman/core/skill/README.md",
-    "sha256": "0c1514669d044033",
+    "sha256": "1738ef9c6d9ec919",
   },
   {
     "file": ".houndsman/core/skill/SETUP.md",
@@ -610,7 +680,7 @@ exports[`baseline — camada gerada setup gera os mesmos arquivos e conteúdos 3
   },
   {
     "file": ".houndsman/core/skill/hunt.md",
-    "sha256": "b55507d62d3c1fcd",
+    "sha256": "1cf68076325da4ab",
   },
   {
     "file": ".houndsman/core/skill/train.md",

package/src/tests/cli.test.ts

@@ -188,7 +188,8 @@ describe("cli smoke — imports dinâmicos", () => {
 	test("doctor valida a config (import lazy de registry-check)", () => {
 		const project = makeProject();
 		try {
-			const result = runCli(project.cwd, ["doctor"]);
+			// `--no-ping`: o teste cobre import lazy, não latência de rede.
+			const result = runCli(project.cwd, ["doctor", "--no-ping"]);
 			expect(result.code).toBe(0);
 			expect(result.stdout).toContain("Validando");
 		} finally {

package/src/tests/server.test.ts

@@ -111,6 +111,44 @@ describe("server API", () => {
 		}
 	});
 
+	test("DELETE /api/runs/:slug apaga review, findings, artefatos e staging", async () => {
+		const env = makeEnv();
+		try {
+			const handler = createRequestHandler(env.config, env);
+			const res = await handler(
+				new Request("http://localhost/api/runs/main", { method: "DELETE" }),
+			);
+			expect(res.status).toBe(200);
+			const body = (await res.json()) as { deleted: boolean };
+			expect(body.deleted).toBe(true);
+
+			expect(env.storage.getReview(env.reviewId)).toBeNull();
+			expect(env.storage.readFindings(env.reviewId)).toBeNull();
+			expect(env.storage.listArtifacts(env.reviewId)).toHaveLength(0);
+
+			const list = await get(handler, "/api/runs");
+			const after = (await list.json()) as { runs: unknown[] };
+			expect(after.runs).toHaveLength(0);
+		} finally {
+			env.cleanup();
+		}
+	});
+
+	test("DELETE /api/runs/:slug inexistente devolve 404", async () => {
+		const env = makeEnv();
+		try {
+			const handler = createRequestHandler(env.config, env);
+			const res = await handler(
+				new Request("http://localhost/api/runs/nao-existe", {
+					method: "DELETE",
+				}),
+			);
+			expect(res.status).toBe(404);
+		} finally {
+			env.cleanup();
+		}
+	});
+
 	test("GET findings reconstrói do artefato e PATCH atualiza o estado", async () => {
 		const env = makeEnv();
 		try {