@payconductor/houndsman 0.1.1 → 0.1.3

package/src/skill/{houndsman.md → hunt.md}

@@ -1,18 +1,18 @@
-# houndsman — {{projectName}} (v1)
+# houndsman — {{projectName}} · `hunt` (revisão de PR)
 
-> **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á.
+> **Documento canônico da capability `hunt`.** O entry point do skill é o `SKILL.md`
+> (`.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.
-O motor é o CLI **`houndsman`**; as regras do projeto ficam em `houndsman.config.ts` + `houndsman/`.
+Invocação: `/houndsman` (default) ou `/houndsman hunt`. 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).
+**Quando usar:** revisar PR antes de merge · code review de feature branch · validar
+mudanças antes de push.
 
 ## Quem executa o quê
 
-- **Você** só invoca o skill: `/houndsman`. Não precisa rodar nenhum script à mão.
+- **Você** só invoca o skill: `/houndsman [hunt]`. 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:
 
@@ -21,9 +21,10 @@ especialista por domínio que audita o diff (antigo "revisor"); **review/revisã
 | 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` |
+| 3. Finalizar | `houndsman --finalize` | skill | `review.md` + `state.json` + `run.json` |
 
 > 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`.
 
 **Arquitetura:**
 
@@ -42,12 +43,6 @@ especialista por domínio que audita o diff (antigo "revisor"); **review/revisã
 - 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)
@@ -114,6 +109,20 @@ as regras atômicas dos watchdogs. Respostas acima do limiar viram **candidatos*
 - **Opcional**: sem chave / erro / timeout → `available:false`; a revisão segue idêntica.
 - Desativar: `houndsman --no-jev`.
 
+### Review incremental (da 2ª revisão em diante)
+
+Cada `--finalize` grava o **commit revisado** (`reviewed.headSha` no `state.json`). No prepare
+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.
+
+- Sem mudanças desde a última revisão → **no-op** (nada a revisar; o estado é preservado).
+- 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).
+
+> Custo: o LLM só é gasto nos arquivos que mudaram desde a última revisão — não na PR inteira.
+
 ---
 
 ## Passo 2 — Revisar (skill despacha os subagentes)
@@ -151,46 +160,10 @@ Falha com mensagem clara se faltar algum `findings/<watchdog>.json`. Quando todo
 7. 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
 8. Grava `.houndsman/.runs/<branch-slug>/state.json` — a **triagem**: um `id` curto e um
-   `fingerprint` de conteúdo por finding (Passo 4), preservados entre execuções
+   `fingerprint` de conteúdo por finding, preservados entre execuções
 
-> Compatível com `classification.json` antigo: se faltar o churn, o orçamento não é aplicado.
-
----
-
-## Passo 4 — Triagem (opcional)
-
-Cada finding recebe um `id` curto e um `fingerprint` de **conteúdo** no `--finalize`,
-gravados em `.houndsman/.runs/<branch-slug>/state.json`. A triagem é feita pela UI ou
-pelo agente — sem editar o JSON à mão. Duas dimensões independentes:
-
-- **decision:** `pending` · `execute` · `ignore` (+ `comment` opcional).
-- **execState:** `pending` · `in_progress` · `done` · `stale`.
-
-### UI local
-
-```bash
-houndsman server --open
-```
-
-Abre a UI (Bun.serve + Preact): lista as runs, triar os findings por severidade, comentar,
-marcar como feito e ler os artefatos (`manifest.json`, `classification.json`, `review.md`).
-Bind em `127.0.0.1` (ferramenta local, sem auth).
-
-### Auto-fix pelo agente
-
-```bash
-houndsman findings list --decision execute --json   # pendentes marcados p/ corrigir
-# ... o agente aplica as correções ...
-houndsman findings sync                             # reancora por conteúdo
-houndsman findings done <id>                        # confirma os concluídos
-```
-
-> **A linha não é a identidade.** O auto-fix desloca linhas; o motor reancora cada finding
-> pelo **conteúdo** (trecho + contexto) e não perde itens que se movem. Se a âncora some
-> (o trecho foi corrigido), o finding vira `done` automaticamente quando a decisão era
-> `execute`, ou `stale` caso contrário.
-> Ocorrências byte-idênticas (mesmo trecho E mesmo contexto) compartilham o id — são
-> tratadas como um grupo (`×N`); limitação conhecida.
+Após finalizar, corrija os achados com a capability **`fix`** (`fix.md`): a UI ou os
+comandos `findings` levam do achado à correção.
 
 ---
 
@@ -243,9 +216,11 @@ git diff --name-status (base...head)
         ↓
 [2] N subagentes em paralelo   ──►  findings/<watchdog>.json
         ↓
-[3] houndsman --finalize       ──►  review.md + state.json
+[3] houndsman --finalize       ──►  review.md + state.json + run.json (review_done)
         ↓
-[4] triagem (UI ou agente)     ──►  state.json (decision/execState)
+[4] server (UI)                ──►  validar a revisão + marcar decision: execute
+        ↓
+[5] fix                        ──►  correções + state.json/run.json (fix_done)
 ```
 
 ---
@@ -254,25 +229,23 @@ git diff --name-status (base...head)
 
 ```
 /houndsman
-/houndsman feature/add-webhook-retry
+/houndsman hunt
+/houndsman hunt feature/add-webhook-retry
 ```
 
 Se a branch não for informada, detecta com `git branch --show-current`. Base do diff: `main`.
 
-**Comandos do CLI:**
+**Comandos do CLI usados no `hunt`:**
 
 | Comando | Função |
 |---|---|
 | `houndsman context` | Passo 0 — contexto da PR via `gh` |
-| `houndsman` | Passo 1 — preparar (briefs + manifesto) |
+| `houndsman` | Passo 1 — preparar (briefs + manifesto; incremental quando possível) |
 | `houndsman --finalize` | Passo 3 — gerar o relatório |
 | `houndsman watchdog <id>` | Contexto de um watchdog (`--json`, `--rules`) |
-| `houndsman findings <sub>` | Triagem dos findings (list/show/set/done/reset/sync/summary/path) |
-| `houndsman server` | UI local de triagem + leitura de artefatos (`--port`, `--host`, `--open`) |
-| `houndsman setup` | Cria a configuração inicial do projeto |
-| `houndsman update` | Sincroniza os arquivos auto-gerados (`.houndsman/core`) |
-| `houndsman doctor` | Valida a configuração, o ambiente e a credencial Jev |
-| `houndsman test` | Suíte de testes da lib |
+
+Flags do review: `--base` · `--head` · `--branch` · `--dir` · `--clean` · `--full` (força
+completo) · `--no-jev` · `--fail-on-blocking` (com `--finalize`).
 
 ---
 
@@ -294,11 +267,11 @@ Se a branch não for informada, detecta com `git branch --show-current`. Base do
 
 ## Manutenção das Regras
 
-> Alterar qualquer regra (adicionar, ajustar severidade, remover, corrigir escopo) → usar o
-> skill **`houndsman-update`** (`src/skill/houndsman-update.md`).
+> Alterar qualquer regra (adicionar, ajustar severidade, remover, corrigir escopo) → capability
+> **`train`** (`/houndsman train`, doc `train.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` + `houndsman test` + `ci:fix` + `ci:check`.
+> Após qualquer alteração, rodar `houndsman doctor` + `houndsman test` + `ci:fix` + `ci`.
 
 ---
 

package/src/skill/{houndsman-update.md → train.md}

@@ -1,14 +1,14 @@
-# Atualização de Lógicas do houndsman
+# houndsman — {{projectName}} · `train` (atualização de regras)
 
-> **Documento canônico do skill `/houndsman-update`.** Os `SKILL.md` de cada harness
-> (`.agents/skills/houndsman-update/` e `.claude/skills/houndsman-update/`) são apenas ponteiros para cá.
+> **Documento canônico da capability `train`.** O entry point do skill é o `SKILL.md`
+> (`.agents/skills/houndsman/SKILL.md` e `.claude/skills/houndsman/SKILL.md`).
 
 > **Propósito:** manter os watchdogs do skill `houndsman` alinhados ao que o
 > projeto **realmente aplica** — seja para adicionar/ajustar uma regra a pedido do
 > usuário, seja para uma auditoria geral após mudanças de padrão no código.
 
-Este skill é o **mantenedor** do `houndsman`. Ele não revisa PRs; ele atualiza as regras
-que o `houndsman` usa.
+Invocação: `/houndsman train`. Esta capability é a **mantenedora** do `houndsman`.
+Ela não revisa PRs (isso é `hunt`); ela atualiza as regras que o `houndsman` usa.
 
 ---
 
@@ -86,7 +86,7 @@ Toda regra (nova ou alterada) deve passar por **todos** os itens:
 - O projeto mudou de padrão (ex.: passou a usar uma lib, mudou autenticação, etc.).
 - **Auditoria completa** dos watchdogs após revisão geral do código.
 - **Regra confusa/ambígua** (humano ou IA não entende) — ver Modo C.
-- O usuário invoca `/houndsman-update`.
+- O usuário invoca `/houndsman train`.
 
 ---
 
@@ -108,7 +108,7 @@ Toda regra (nova ou alterada) deve passar por **todos** os itens:
 | `src/core/config-loader.ts` | Descoberta/carregamento de `houndsman.config.ts` |
 | `src/core/brief.ts` | Render do brief: `defaultRenderBrief` + `PROCEDURE` |
 | `src/core/registry-check.ts` | Validação anti-drift (config-driven) |
-| `src/skill/houndsman.md` | Orquestração + tabela de watchdogs |
+| `src/skill/hunt.md` | Orquestração da revisão (capability `hunt`) |
 | `src/tests/**` | Suíte da lib (project-agnóstica; usa `fixtures/fake-project.ts`) |
 | `src/cli/index.ts` | **CLI único** — `houndsman [context, setup, doctor, test, watchdog, --finalize]` |
 
@@ -169,7 +169,7 @@ verificáveis por leitura local. Candidatos não confirmados pelo watchdog **nã
    - Ajustar `scope` / `description` / `reviewFocus` / `exclude` / `contextFiles` se necessário.
    - Se a regra muda para outro domínio (paths), ajustar o `classify` do watchdog.
 5. **Watchdog novo?** criar `.houndsman/watchdogs/<id>.ts` e registrar em `.houndsman/watchdogs/index.ts` (o id é derivado das chaves).
-6. **Atualizar `src/skill/houndsman.md`/`README.md`** se escopo/regra visível mudou (no motor).
+6. **Atualizar `src/skill/hunt.md`/`README.md`** se escopo/regra visível mudou (no motor).
 7. **Atualizar a suíte da lib** se o comportamento do MOTOR mudou (a suíte é project-agnóstica).
 8. **Verificar** (seção abaixo).
 
@@ -228,16 +228,16 @@ todos os itens — em especial: **geral/reutilizável** (não regra de negócio
 bun run houndsman doctor     # config sem drift + ambiente + credencial Jev
 bun run houndsman test       # suíte da lib (project-agnóstica)
 bun run ci:fix               # formatação/imports/lint (no repo da lib)
-bun run ci:check             # tipagem (no repo da lib)
+bun run ci                   # tipagem (no repo da lib)
 ```
 
 Checklist final:
 
 - [ ] `bun run houndsman doctor` → sem problemas reportados.
 - [ ] `bun run houndsman test` → **0 fail**.
-- [ ] `ci:fix` + `ci:check` → exit 0 (warnings pré-existentes não contam).
+- [ ] `ci:fix` + `ci` → exit 0 (warnings pré-existentes não contam).
 - [ ] `WATCHDOG_DEFINITIONS[<id>].id` bate com a chave e `description` não vazio.
-- [ ] `src/skill/houndsman.md` continua consistente com os watchdogs do projeto.
+- [ ] `src/skill/hunt.md` continua consistente com os watchdogs do projeto.
 - [ ] Toda regra nova/alterada tem **evidência** registrada no PR/relatório
       (`file:line` se afirmativa; `0 ocorrências do anti-padrão` se negativa).
 - [ ] Nenhuma regra **negativa** foi removida por "0 ocorrências" (Regra de Ouro).

package/src/skill/verify.md

@@ -0,0 +1,70 @@
+# houndsman — {{projectName}} · `verify` (violações resolvidas?)
+
+> **Documento canônico da capability `verify`.** O entry point do skill é o `SKILL.md`
+> (`.agents/skills/houndsman/SKILL.md` e `.claude/skills/houndsman/SKILL.md`).
+
+Confere se os findings de uma revisão **já finalizada** foram resolvidos — **sem re-revisar a
+PR**. Invocação: `/houndsman verify`. Consome o `state.json` do `hunt`; não revisa nem altera
+regras.
+
+**Quando usar:**
+
+- Depois de corrigir achados (`fix`), para confirmar que as violações sumiram.
+- As violações foram resolvidas? · confere se ainda está lá · valida o fix.
+
+> **Pré-requisito:** existe `.houndsman/.runs/<branch-slug>/state.json` (gerado no `--finalize`).
+
+---
+
+## Como funciona (2 tiers)
+
+1. **Tier local (grátis, determinístico).** Para cada finding presente, reancora a âncora de
+   conteúdo contra o working tree (`core/finding-anchor.ts`):
+   - **âncora presente** (`ok`/`moved`) → **persiste** (a violação ainda está lá);
+   - **âncora sumida** (`stale`) → provável **resolvido** — mas o trecho pode ter sido reescrito;
+   - **arquivo ausente** → fora da verificação (deletado/movido).
+
+2. **Tier Jev (opcional, só nos ambíguos).** Com `TYPESAFE_API_KEY`, os casos `stale` / sem
+   âncora são confirmados pelo LLM sobre um **diff focado** do arquivo (`foundAtSha..HEAD`), uma
+   pergunta `noul` por finding. Falha-aberto: sem chave/erro → vale o resultado local.
+
+**Custo:** ~0 LLM quando o tier local decide; 1 chamada por arquivo ambíguo — nunca uma revisão
+completa.
+
+---
+
+## Procedimento
+
+```bash
+bun run houndsman findings verify            # relatório (não altera o estado)
+bun run houndsman findings verify --json     # saída estruturada
+bun run houndsman findings verify --apply    # marca os resolvidos como done (ping no run.json)
+```
+
+- Sem `--apply`: **só relatório** (grava `verify.md` na pasta da run). Nada muda no `state.json`.
+- Com `--apply`: os findings com status **`resolved`** viram `execState: done` (histórico
+  `by: "verify"`). `persisting` e `uncertain` **não** são tocados.
+
+Filtros (como no `findings list`): `--severity`, `--watchdog`, `--file`, `--decision`. `--all`
+inclui ausentes. `--no-jev` desliga o tier LLM. `--fail-on-persisting` sai com código 1 se algum
+`blocking` persistir (útil em CI).
+
+---
+
+## Status possíveis
+
+| Status | Significado | `--apply`? |
+|---|---|---|
+| `resolved` | Violação não encontrada (âncora sumida; confirmada pelo Jev quando há chave). | ✅ vira `done` |
+| `persisting` | Âncora ainda presente — a violação continua. | ❌ |
+| `uncertain` | Sem âncora e sem confirmação do Jev (ou Jev indisponível). | ❌ |
+| `file-missing` | Arquivo não está no working tree (deletado/movido). | ❌ |
+
+---
+
+## Anti-padrões
+
+- ❌ Reexecutar o `hunt` inteiro só para conferir se um fix funcionou — use o `verify`.
+- ❌ Esperar que o `verify` marque `done` sem `--apply` (sem a flag, nada muda no estado).
+- ❌ Tratar `persisting` como resolvido — a âncora ainda está no arquivo.
+- ❌ Esperar verificação 100% pelo LLM — o tier local resolve a maioria de graça.

package/src/tests/findings-commands.test.ts

@@ -1,8 +1,15 @@
 import { describe, expect, test } from "bun:test";
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import {
+	existsSync,
+	mkdirSync,
+	mkdtempSync,
+	readFileSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { runFindingsCommand } from "../core/commands/findings";
+import { runFindingsCommand, runVerifyCommand } from "../core/commands/findings";
 import { fakeHoundsmanConfig } from "./fixtures/fake-project";
 
 /** Run fake em disco: classification.json + findings/alpha.json. */
@@ -223,4 +230,247 @@ describe("findings command", () => {
 			run0.cleanup();
 		}
 	});
+
+	test("batch agrupa a fila e devolve o grupo atual + outros grupos", () => {
+		const dir = mkdtempSync(join(tmpdir(), "houndsman-batch-"));
+		const outDir = join(dir, "main");
+		mkdirSync(join(outDir, "findings"), { recursive: true });
+		writeFileSync(
+			join(outDir, "classification.json"),
+			JSON.stringify({ watchdogs: { alpha: ["src/a.ts"], beta: ["src/b.ts"] } }),
+		);
+		writeFileSync(
+			join(outDir, "findings", "alpha.json"),
+			JSON.stringify({
+				watchdogId: "alpha",
+				reviewedFiles: ["src/a.ts"],
+				skipped: [],
+				findings: [
+					{
+						rule: "R1",
+						severity: "blocking",
+						file: "src/a.ts",
+						line: 1,
+						message: "m1",
+						action: "a",
+					},
+					{
+						rule: "R2",
+						severity: "attention",
+						file: "src/a.ts",
+						line: 2,
+						message: "m2",
+						action: "a",
+					},
+					{
+						rule: "R3",
+						severity: "attention",
+						file: "src/a.ts",
+						line: 3,
+						message: "m3",
+						action: "a",
+					},
+					{
+						rule: "R4",
+						severity: "nit",
+						file: "src/a.ts",
+						line: 4,
+						message: "m4",
+						action: "a",
+					},
+				],
+			}),
+		);
+		writeFileSync(
+			join(outDir, "findings", "beta.json"),
+			JSON.stringify({
+				watchdogId: "beta",
+				reviewedFiles: ["src/b.ts"],
+				skipped: [],
+				findings: [
+					{
+						rule: "R5",
+						severity: "attention",
+						file: "src/b.ts",
+						line: 1,
+						message: "m5",
+						action: "a",
+					},
+					{
+						rule: "R6",
+						severity: "suggestion",
+						file: "src/b.ts",
+						line: 2,
+						message: "m6",
+						action: "a",
+					},
+				],
+			}),
+		);
+		try {
+			const list = JSON.parse(
+				run(["list", "--dir", dir, "--branch", "main", "--json"]).output,
+			);
+			for (const item of list) {
+				run([
+					"set",
+					item.id,
+					"--decision",
+					"execute",
+					"--dir",
+					dir,
+					"--branch",
+					"main",
+				]);
+			}
+
+			const result = run(["batch", "--dir", dir, "--branch", "main", "--json"]);
+			expect(result.exitCode).toBe(0);
+			const parsed = JSON.parse(result.output);
+			expect(parsed.dimension).toBe("file");
+			expect(parsed.totals.queue).toBe(6);
+			expect(parsed.totals.groups).toBe(2);
+			expect(parsed.current.key).toBe("file:src/a.ts");
+			expect(parsed.current.findings).toHaveLength(4);
+			expect(parsed.others).toEqual([
+				expect.objectContaining({ key: "file:src/b.ts", count: 2 }),
+			]);
+
+			const markdown = run(["batch", "--dir", dir, "--branch", "main"]);
+			expect(markdown.output).toContain("Grupo atual");
+			expect(markdown.output).toContain("Outros grupos");
+
+			const scoped = run([
+				"batch",
+				"--group",
+				"file:src/b.ts",
+				"--dir",
+				dir,
+				"--branch",
+				"main",
+				"--json",
+			]);
+			expect(JSON.parse(scoped.output).current.key).toBe("file:src/b.ts");
+		} finally {
+			rmSync(dir, { recursive: true, force: true });
+		}
+	});
+
+	test("mutações fazem ping no run.json (status)", () => {
+		const run0 = makeRun(ONE_FINDING);
+		try {
+			const id = JSON.parse(
+				run(["list", "--dir", run0.dir, "--branch", "main", "--json"]).output,
+			)[0].id;
+			const runJson = join(run0.dir, "main", "run.json");
+
+			run([
+				"set",
+				id,
+				"--decision",
+				"execute",
+				"--dir",
+				run0.dir,
+				"--branch",
+				"main",
+			]);
+			expect(JSON.parse(readFileSync(runJson, "utf8")).status).toBe("review_done");
+
+			run([
+				"set",
+				id,
+				"--exec",
+				"in_progress",
+				"--dir",
+				run0.dir,
+				"--branch",
+				"main",
+			]);
+			expect(JSON.parse(readFileSync(runJson, "utf8")).status).toBe("fixing");
+
+			run(["done", id, "--dir", run0.dir, "--branch", "main"]);
+			expect(JSON.parse(readFileSync(runJson, "utf8")).status).toBe("fix_done");
+		} finally {
+			run0.cleanup();
+		}
+	});
+});
+
+describe("findings verify", () => {
+	const FILE = "src/tests/fixtures/fake-project.ts";
+
+	/** Run fake apontando para um arquivo real (relativo ao cwd → âncora resolvível). */
+	function makeVerifyRun(): { dir: string; outDir: string; cleanup: () => void } {
+		const dir = mkdtempSync(join(tmpdir(), "houndsman-verify-"));
+		const outDir = join(dir, "main");
+		mkdirSync(join(outDir, "findings"), { recursive: true });
+		writeFileSync(
+			join(outDir, "classification.json"),
+			JSON.stringify({ watchdogs: { alpha: [FILE] } }),
+		);
+		writeFileSync(
+			join(outDir, "findings", "alpha.json"),
+			JSON.stringify({
+				watchdogId: "alpha",
+				reviewedFiles: [FILE],
+				skipped: [],
+				findings: [
+					{
+						rule: "regra",
+						severity: "attention",
+						file: FILE,
+						line: 1,
+						message: "msg",
+						action: "ação",
+					},
+				],
+			}),
+		);
+		return {
+			dir,
+			outDir,
+			cleanup: () => rmSync(dir, { recursive: true, force: true }),
+		};
+	}
+
+	test("reporta persisting e grava o verify.md (tier local)", async () => {
+		const run0 = makeVerifyRun();
+		try {
+			const result = await runVerifyCommand(fakeHoundsmanConfig, [
+				"verify",
+				"--dir",
+				run0.dir,
+				"--branch",
+				"main",
+				"--json",
+			]);
+			expect(result.exitCode).toBe(0);
+			const parsed = JSON.parse(result.output);
+			expect(parsed.summary.persisting).toBe(1);
+			expect(parsed.entries[0].basis).toBe("anchor");
+			expect(existsSync(join(run0.outDir, "verify.md"))).toBe(true);
+		} finally {
+			run0.cleanup();
+		}
+	});
+
+	test("sem --apply não altera o estado", async () => {
+		const run0 = makeVerifyRun();
+		try {
+			await runVerifyCommand(fakeHoundsmanConfig, [
+				"verify",
+				"--dir",
+				run0.dir,
+				"--branch",
+				"main",
+			]);
+			const state = JSON.parse(
+				readFileSync(join(run0.outDir, "state.json"), "utf8"),
+			) as { findings: Record<string, { execState: string }> };
+			const only = Object.values(state.findings)[0];
+			expect(only.execState).toBe("pending");
+		} finally {
+			run0.cleanup();
+		}
+	});
 });

package/src/tests/findings-state.test.ts

@@ -267,8 +267,59 @@ describe("FindingsStateStore", () => {
 
 	test("emptyState cria um estado vazio válido", () => {
 		const state = emptyState("feature/x");
-		expect(state.version).toBe(1);
+		expect(state.version).toBe(2);
 		expect(state.slug).toBe("feature-x");
 		expect(state.findings).toEqual({});
 	});
 });
+
+describe("rastreio de revisão (incremental)", () => {
+	test("carimba reviewed e foundAtSha nos findings do ciclo", () => {
+		const project = makeProject({ "src/f.ts": DUPLICATED });
+		try {
+			const state = buildStateFromFindings(
+				[merged({ file: "src/f.ts", rule: "r", line: 2 })],
+				{
+					branch: "main",
+					readFile: fileReader(project.cwd),
+					headSha: "abc1234",
+					reviewed: { headSha: "abc1234", at: "2026-01-01T00:00:00.000Z" },
+				},
+			);
+			expect(state.reviewed?.headSha).toBe("abc1234");
+			const only = Object.values(state.findings)[0];
+			expect(only.foundAtSha).toBe("abc1234");
+		} finally {
+			project.cleanup();
+		}
+	});
+
+	test("carry-over preserva o foundAtSha original", () => {
+		const project = makeProject({ "src/f.ts": DUPLICATED });
+		try {
+			const state = buildStateFromFindings(
+				[
+					// Novo/re-reportado: recebe o head atual.
+					merged({ file: "src/f.ts", rule: "r", line: 2 }),
+					// Carry-over: carrega o `foundAtSha` de quando foi observado.
+					{
+						...merged({ file: "src/f.ts", rule: "r2", line: 5 }),
+						foundAtSha: "old0001",
+					},
+				],
+				{
+					branch: "main",
+					readFile: fileReader(project.cwd),
+					headSha: "new0002",
+					reviewed: { headSha: "new0002", at: "2026-01-02T00:00:00.000Z" },
+				},
+			);
+			const byRule = (rule: string): string | undefined =>
+				Object.values(state.findings).find((f) => f.rule === rule)?.foundAtSha;
+			expect(byRule("r")).toBe("new0002");
+			expect(byRule("r2")).toBe("old0001");
+		} finally {
+			project.cleanup();
+		}
+	});
+});