@payconductor/houndsman 0.11.0 → 0.13.0

package/src/index.ts

@@ -7,7 +7,6 @@
 
 export type {
 	AiResult,
-	AiTool,
 	AiUsage,
 	ModelProvider,
 	ModelRequest,
@@ -26,7 +25,14 @@ export {
 } from "./core/ai";
 export { ArgParser } from "./core/arg-parser";
 export { assetPath, OUTPUT_FORMAT_FILE } from "./core/assets";
-export { computeDelta, emptyDelta, parseHunks } from "./core/ast/diff";
+export {
+	changedAnchorLines,
+	changedAnchors,
+	changedNewLines,
+	computeDelta,
+	emptyDelta,
+	parseHunks,
+} from "./core/ast/diff";
 export { buildImpact, resolveImport } from "./core/ast/impact";
 export { AstParser, languageForPath } from "./core/ast/parser";
 export { AstService } from "./core/ast/service";
@@ -44,6 +50,23 @@ export type {
 	AstSymbolKind,
 } from "./core/ast/types";
 export { defaultRenderBrief, PROCEDURE, renderBrief } from "./core/brief";
+export type {
+	BuildChangedScopeInput,
+	ChangedScope,
+	ChangedScopeSource,
+	ChangedSymbol,
+	FileChangedScope,
+	LineRange,
+	ScopeEntry,
+} from "./core/changed-scope";
+export {
+	buildChangedScope,
+	formatRanges,
+	formatSymbols,
+	isLineInScope,
+	mergeRanges,
+	summarizeScope,
+} from "./core/changed-scope";
 export type { FindingsCommandResult } from "./core/commands/findings";
 export { runFindingsCommand, runVerifyCommand } from "./core/commands/findings";
 export { ProjectScaffolder } from "./core/commands/scaffold";
@@ -57,13 +80,18 @@ export type {
 	HoundsmanConcurrency,
 	HoundsmanConfig,
 	HoundsmanConfigInput,
+	HoundsmanHunt,
 	HoundsmanStorage,
 } from "./core/config";
 export {
 	DEFAULT_ALWAYS_INCLUDE_DOCS,
 	DEFAULT_AST_MAX_FILE_BYTES,
 	DEFAULT_AST_MAX_IMPACT_FILES,
+	DEFAULT_HUNT_CONCURRENCY,
+	DEFAULT_HUNT_RETRIES,
+	DEFAULT_HUNT_TIMEOUT_MS,
 	DEFAULT_JEV_CONCURRENCY,
+	DEFAULT_MAKI_VERSION,
 	DEFAULT_MAX_FILES_PER_BRIEF,
 	defineHoundsmanConfig,
 	resolveJevConcurrency,
@@ -158,6 +186,50 @@ export {
 	syncState,
 } from "./core/findings-state";
 export type { GitResult, GitRunner } from "./core/git-runner";
+export type {
+	HuntEvent,
+	HuntReport,
+	HuntRunnerOptions,
+	HuntTotals,
+	HuntWatchdogResult,
+	InstallMakiOptions,
+	InstallMakiResult,
+	MakiBinary,
+	MakiBinarySource,
+	MakiInstallManifest,
+	MakiModel,
+	MakiProcessRunner,
+	MakiRunMetrics,
+	MakiRunRequest,
+	MakiRunResult,
+	MakiUsage,
+} from "./core/hunt";
+export {
+	extractJsonObject,
+	HuntRunner,
+	houndsmanKeyEnvFor,
+	installMaki,
+	MAKI_API_KEY_ENV,
+	MAKI_DISALLOWED_TOOLS,
+	makiArgs,
+	makiCurrentFile,
+	makiInstallDir,
+	makiSourceLabel,
+	makiToolsRoot,
+	mapPool,
+	metricsFrom,
+	parseMakiOutput,
+	probeMakiVersion,
+	readMakiInstall,
+	renderHuntPrompt,
+	renderRetrySuffix,
+	requireMakiBinary,
+	requireMakiModel,
+	resolveMakiBinary,
+	resolveMakiModel,
+	SpawnMakiRunner,
+	uninstallMaki,
+} from "./core/hunt";
 export {
 	CORE_DIR,
 	CORE_SKILL_DIR,
@@ -231,7 +303,6 @@ export type {
 	FileStatus,
 	FileStatusMap,
 	Rule,
-	RuleHints,
 	Severity,
 	WatchdogDefinition,
 	WatchdogMeta,

package/src/server/client/utils/constants.ts

@@ -97,7 +97,6 @@ const KIND_ORDER: ArtifactKind[] = [
 	"ai",
 	"ai-usage",
 	"ai-brief",
-	"harness-transcript",
 	"context",
 	"context-brief",
 	"context-summary",
@@ -119,10 +118,9 @@ const GROUP_BY_KIND: Record<ArtifactKind, { key: string; label: string; order: n
 		candidates: { key: "core", label: "Núcleo da revisão", order: 3 },
 		ast: { key: "core", label: "Núcleo da revisão", order: 3 },
 		"ast-impact": { key: "core", label: "Núcleo da revisão", order: 3 },
-		ai: { key: "ai", label: "IA e harness", order: 4 },
-		"ai-usage": { key: "ai", label: "IA e harness", order: 4 },
-		"ai-brief": { key: "ai", label: "IA e harness", order: 4 },
-		"harness-transcript": { key: "ai", label: "IA e harness", order: 4 },
+		ai: { key: "ai", label: "IA", order: 4 },
+		"ai-usage": { key: "ai", label: "IA", order: 4 },
+		"ai-brief": { key: "ai", label: "IA", order: 4 },
 		context: { key: "context", label: "Contexto da PR", order: 5 },
 		"context-brief": { key: "context", label: "Contexto da PR", order: 5 },
 		"context-summary": { key: "context", label: "Contexto da PR", order: 5 },
@@ -146,7 +144,6 @@ export const ARTIFACT_KIND_LABELS: Record<ArtifactKind, string> = {
 	ai: "ia",
 	"ai-usage": "uso ia",
 	"ai-brief": "plano ia",
-	"harness-transcript": "transcript",
 	context: "contexto",
 	"context-brief": "brief ctx",
 	"context-summary": "resumo ctx",

package/src/server/client/utils/types.ts

@@ -70,7 +70,6 @@ export type ArtifactKind =
 	| "ai"
 	| "ai-usage"
 	| "ai-brief"
-	| "harness-transcript"
 	| "other";
 
 /** Metadados de artefato retornados pela API (sem conteúdo). */

package/src/skill/OUTPUT-FORMAT.md

@@ -69,6 +69,11 @@ staging global da review:
 - Sem achados → `"findings": []` (arquivo **obrigatório**).
 - Um achado por regra violada; não agrupar regras diferentes.
 - `file:line` sempre que possível; `evidence` quando o achado não é óbvio.
+- **Escopo do diff:** a `line` deve cair dentro das faixas listadas em
+  *Escopo do diff (símbolos alterados)* no brief. Código fora delas é contexto — não é
+  achado desta revisão. Se a alteração quebra código não alterado, ancore o finding na
+  linha alterada que causou o problema.
+- Achado **sem linha** só quando for inerente à alteração (vira comentário de arquivo).
 - Não inventar achados — se não houver violação, o array fica vazio.
 
 ## Findings emergentes (opt-in)

package/src/skill/README.md

@@ -14,11 +14,22 @@ Um único skill (`/houndsman`), quatro capabilities (detalhadas em `hunt.md`, `t
 | `fix` | Correção dos findings marcados como `execute`. |
 | `verify` | Confere se as violações foram resolvidas, sem re-revisar a PR. |
 
+## Dois caminhos para o `hunt`
+
+| Caminho | Quem usa | Requisitos |
+|---|---|---|
+| Skill `/houndsman hunt` | agente externo (Copilot/Claude/etc.) | nenhum |
+| CLI `houndsman hunt` | operador/CI, sem agente | `houndsman hunt install` |
+
+Os dois usam o mesmo `prepare`/`finalize`, o mesmo staging e o mesmo schema de findings.
+O CLI só substitui o despacho manual dos subagentes por processos maki headless.
+
 ## Terminologia
 
 - **houndsman** — o orquestrador/treinador (CLI + motor).
 - **watchdog** — cada agente especialista por domínio que audita o diff.
-- **brief** — instruções prontas para um watchdog (o prompt do subagente).
+- **brief** — instruções prontas para um watchdog (o prompt do subagente), incluindo o
+  **escopo do diff** (faixas/símbolos alterados que podem virar finding).
 - **findings** — os achados que o subagente grava em JSON (único output consumido).
 - **candidato (Jev)** — indício automático; **não** é achado (o watchdog confirma ou refuta).
 - **churn** — linhas adicionadas/removidas por arquivo; usado para priorizar a leitura.
@@ -52,6 +63,8 @@ Um único skill (`/houndsman`), quatro capabilities (detalhadas em `hunt.md`, `t
 | `houndsman` | Passo 1 — preparar (gera os briefs) |
 | `houndsman --pr <n>` | Passo 1 em worktree dedicado (revisões paralelas) |
 | `houndsman --finalize` | Passo 3 — gerar o relatório (`--pr <n>` reusa o worktree) |
+| `houndsman hunt [--pr <n>]` | Harness local opcional (maki): prepare → watchdogs → finalize |
+| `houndsman hunt install` | Baixa o maki fixado para `<HOUNDSMAN_HOME>/tools/maki` |
 | `houndsman worktree <ação>` | `list`/`add`/`remove`/`prune`/`path` dos worktrees |
 | `houndsman watchdog <id>` | Contexto de um watchdog (`--json`, `--rules`) |
 | `houndsman findings <sub>` | Triagem/correção dos findings (`list`/`set`/`done`/`sync`/`batch`/`verify`/...) |

package/src/skill/SETUP.md

@@ -9,7 +9,7 @@ no seu projeto é **autocontida** — não exige nenhuma dependência local do p
 - **git** — o diff usa `git diff <base>...<head> --name-status`.
 - **gh** (Opcional) — Obtém contexto da PR e dispara comentários para o GitHub
 - **`HOUNDSMAN_TYPE_SAFE_API_KEY`** (opcional) — pré-análise Jev.
-- **`HOUNDSMAN_DEEP_SEEK_API_KEY`** (opcional) — IA própria do `hunt` nativo e das features de IA.
+- **`HOUNDSMAN_DEEP_SEEK_API_KEY`** (opcional) — features de IA (briefs, contexto, classificação, resumo técnico).
 - **`HOUNDSMAN_OPENAI_API_KEY`** / **`HOUNDSMAN_ANTHROPIC_API_KEY`** (opcional) — apenas se
   `ai.provider` for `openai`/`anthropic`.
 
@@ -76,6 +76,25 @@ Depois do setup, invoque o skill `/houndsman` no seu harness:
 | `/houndsman train` | Adicionar/ajustar/remover regras dos watchdogs. |
 | `/houndsman fix` | Corrigir os findings marcados como `execute`. |
 
+## Harness local (opcional) — `houndsman hunt`
+
+Quem não quer rodar a skill dentro de um agente externo pode executar a revisão 100% pelo
+CLI. O maki é instalado sob demanda, fora do projeto, e reaproveita a credencial já existente:
+
+```bash
+houndsman hunt install      # baixa o maki fixado (sha256) em <HOUNDSMAN_HOME>/tools/maki
+houndsman hunt doctor       # binário, modelo e credencial (opcional; não falha sem maki)
+houndsman hunt --pr 456     # prepare → maki (um processo por brief) → finalize
+```
+
+- A skill `/houndsman hunt` continua sendo o caminho canônico e não depende do maki.
+- `HOUNDSMAN_MAKI_PATH` aponta um binário já instalado; `HOUNDSMAN_MAKI_VERSION` troca a
+  versão baixada.
+- Config opcional em `houndsman.config.ts`: `hunt: { model?, concurrency?, timeoutMs?,
+  retries?, binaryPath?, enabled? }`.
+- Se algum watchdog falhar, o comando **não finaliza** (preserva o staging); use
+  `--allow-partial` para finalizar com findings vazios registrados em `skipped`.
+
 ## Contrato do motor (`HoundsmanConfig`)
 
 Definido em `src/core/config.ts` (pacote) e espelhado em `.houndsman/core/types.ts` (gerado):
@@ -91,6 +110,7 @@ Definido em `src/core/config.ts` (pacote) e espelhado em `.houndsman/core/types.
 | `budgets` | **Opcional** — teto de arquivos por brief (`maxFilesPerBrief`, default `40`); o excedente vira "fora do orçamento" (registrar em `skipped`). |
 | `concurrency` | **Opcional** — chamadas Jev simultâneas (`jev`, default `5`). |
 | `ast` | **Opcional** — AST determinístico para TS/JS (`enabled`, `maxFileBytes`, `maxImpactFiles`, `languages`, `aliases`). Default: ligado; falhas são fail-open. |
+| `hunt` | **Opcional** — harness local (`model`, `concurrency`, `timeoutMs`, `retries`, `binaryPath`, `enabled`). Só afeta `houndsman hunt`; a skill não depende. |
 
 > O motor **não contém** ids, paths ou regras do projeto — tudo chega por `HoundsmanConfig`,
 > carregado em runtime a partir de `houndsman.config.ts` (ou `--config <path>`).
@@ -103,7 +123,7 @@ houndsman/
 └── src/
     ├── index.ts              # API pública (defineWatchdog, defineHoundsmanConfig, tipos)
     ├── cli/index.ts          # CLI único — bin `houndsman`
-    ├── core/                 # bibliotecas genéricas (config, orchestrator, brief, jev/, …)
+    ├── core/                 # bibliotecas genéricas (config, orchestrator, brief, jev/, hunt/, …)
     ├── skill/*.md            # assets markdown (embarcados no pacote)
     └── tests/                # suíte da lib (project-agnóstica, "project fake")
 ```

package/src/skill/SKILL.md

@@ -38,6 +38,10 @@ especialista por domínio · **finding** = um achado da revisão · **Jev** = pr
 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.
 
+> **Harness local (opcional):** para rodar sem agente externo, o operador pode instalar o
+> maki (`houndsman hunt install`) e usar `houndsman hunt --pr 456`. Isso não muda esta
+> skill: se você é o agente, siga o fluxo normal e não rode `houndsman hunt`.
+
 ### Alvo da revisão (PR × branch)
 
 Interprete o alvo em linguagem natural **antes** de rodar o CLI:

package/src/skill/fix.md

@@ -132,7 +132,7 @@ Volte ao passo 1. A fila encolhe a cada volta; o `batch` traz o próximo grupo s
 
 ## Perguntas de decisão ao usuário
 
-Pergunte (ferramenta de perguntas do harness) **antes** de corrigir quando o achado for:
+Pergunte (ferramenta de perguntas do agente) **antes** de corrigir quando o achado for:
 
 - ambíguo ou com **múltiplas correções válidas**;
 - uma mudança de **produto/arquitetura** (não é "só código");

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:
@@ -25,12 +39,6 @@ Traduza o pedido do usuário para flags **antes** de começar:
 **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. Para uma
-> PR específica, `houndsman hunt --pr 456` roda no worktree automaticamente. Detalhes em
-> `docs/HARNESS.md`.
-
 ## Quem executa o quê
 
 - **Você** só invoca o skill: `/houndsman [hunt]`. Não precisa rodar nenhum script à mão.
@@ -62,6 +70,8 @@ mudanças antes de push.
 - **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.
+- O brief traz o **escopo do diff** (símbolos alterados e faixas revisáveis); achado fora
+  dessas faixas é código pré-existente, não escopo desta revisão.
 - Saída estruturada (JSON) por watchdog → consolidada e deduplicada automaticamente.
 
 ---
@@ -310,6 +320,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

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

@@ -11,7 +11,7 @@ exports[`baseline — brief defaultRenderBrief (contexto, churn, overflow, candi
 
 Watchdog baseline.
 
-## Escopo
+## Escopo do domínio
 
 src/alpha/**
 
@@ -63,10 +63,10 @@ src/alpha/**
 ## Procedimento
 
 1. **FILTER** — descarte o que não for do seu domínio (ver *Prioridade de leitura* e *Não carregar*).
-2. **READ HEAD** — leia os arquivos seletivamente (primeiras ~30 linhas). NUNCA o diff completo.
-3. **GREP** — use as regras críticas/anti-padrões como heurística para localizar violações.
-4. **DEEP-READ** — aprofunde apenas os arquivos com suspeita de violação.
-5. **CONCLUDE** — grave o JSON no caminho de output, com \`reviewedFiles\` preenchido. Sem achados → \`"findings": []\` (arquivo obrigatório). Não escreva markdown livre."
+2. **READ SCOPE** — carregue apenas as faixas alteradas em *Escopo do diff*; o restante do arquivo é só contexto.
+3. **GREP** — use as regras críticas/anti-padrões como heurística para localizar violações nas faixas alteradas.
+4. **DEEP-READ** — aprofunde apenas as faixas com suspeita de violação dentro do escopo.
+5. **CONCLUDE** — grave o JSON no caminho de output, com \`reviewedFiles\` preenchido e \`line\` dentro das faixas alteradas. Sem achados → \`"findings": []\` (arquivo obrigatório). Não escreva markdown livre."
 `;
 
 exports[`baseline — relatório renderReport consolidado 1`] = `
@@ -238,6 +238,10 @@ especialista por domínio · **finding** = um achado da revisão · **Jev** = pr
 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.
 
+> **Harness local (opcional):** para rodar sem agente externo, o operador pode instalar o
+> maki (\`houndsman hunt install\`) e usar \`houndsman hunt --pr 456\`. Isso não muda esta
+> skill: se você é o agente, siga o fluxo normal e não rode \`houndsman hunt\`.
+
 ### Alvo da revisão (PR × branch)
 
 Interprete o alvo em linguagem natural **antes** de rodar o CLI:
@@ -323,6 +327,10 @@ especialista por domínio · **finding** = um achado da revisão · **Jev** = pr
 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.
 
+> **Harness local (opcional):** para rodar sem agente externo, o operador pode instalar o
+> maki (\`houndsman hunt install\`) e usar \`houndsman hunt --pr 456\`. Isso não muda esta
+> skill: se você é o agente, siga o fluxo normal e não rode \`houndsman hunt\`.
+
 ### Alvo da revisão (PR × branch)
 
 Interprete o alvo em linguagem natural **antes** de rodar o CLI:
@@ -405,16 +413,6 @@ export type Rule = {
 	severity: Severity;
 	text: string;
 	jev?: JevRuleSpec;
-	hints?: RuleHints;
-};
-
-/** Sinais opcionais de uma regra (símbolos, imports, decorators, paths, checks). */
-export type RuleHints = {
-	symbols?: string[];
-	imports?: string[];
-	decorators?: string[];
-	paths?: string[];
-	checks?: string[];
 };
 
 /** Como o watchdog casa um arquivo alterado. \`value\` é sempre regex. */
@@ -509,20 +507,15 @@ export type HoundsmanAiFeatures = {
 /** Overrides de IA por watchdog. */
 export type HoundsmanAiWatchdog = {
 	model?: string;
-	maxSteps?: number;
-	maxOutputTokens?: number;
 };
 
-/** Configuração da camada de IA (briefs, contexto, classificação e hunt nativo). */
+/** Configuração da camada de IA (briefs, contexto, classificação, pré-análise, verify). */
 export type HoundsmanAi = {
 	enabled?: boolean;
 	provider?: AiProviderKind;
 	model?: string;
 	baseURL?: string;
 	concurrency?: number;
-	maxSteps?: number;
-	maxOutputTokens?: number;
-	temperature?: number;
 	providerOptions?: AiProviderOptions;
 	timeoutMs?: number;
 	maxCallsPerReview?: number;
@@ -531,6 +524,16 @@ export type HoundsmanAi = {
 	watchdogs?: Record<string, HoundsmanAiWatchdog>;
 };
 
+/** Harness local da capability \`hunt\` (\`houndsman hunt\`) — opcional. */
+export type HoundsmanHunt = {
+	enabled?: boolean;
+	model?: string;
+	concurrency?: number;
+	timeoutMs?: number;
+	retries?: number;
+	binaryPath?: string;
+};
+
 /** Contrato de configuração do motor. */
 export type HoundsmanConfig<TId extends string = string> = {
 	projectName: string;
@@ -544,6 +547,7 @@ export type HoundsmanConfig<TId extends string = string> = {
 	concurrency?: HoundsmanConcurrency;
 	ast?: HoundsmanAst;
 	ai?: HoundsmanAi;
+	hunt?: HoundsmanHunt;
 };
 
 /** Helper de autoria (identidade) — apenas tipagem. */
@@ -665,15 +669,15 @@ exports[`baseline — camada gerada setup gera os mesmos arquivos e conteúdos 3
   },
   {
     "file": ".houndsman/core/skill/OUTPUT-FORMAT.md",
-    "sha256": "94ea2b8def871784",
+    "sha256": "a78ed16d4d211889",
   },
   {
     "file": ".houndsman/core/skill/README.md",
-    "sha256": "1738ef9c6d9ec919",
+    "sha256": "2ecf43f34a624011",
   },
   {
     "file": ".houndsman/core/skill/SETUP.md",
-    "sha256": "b74af7e1979bf1b4",
+    "sha256": "5720c48ede6c84ea",
   },
   {
     "file": ".houndsman/core/skill/example-review.md",
@@ -681,11 +685,11 @@ exports[`baseline — camada gerada setup gera os mesmos arquivos e conteúdos 3
   },
   {
     "file": ".houndsman/core/skill/fix.md",
-    "sha256": "9f10b2d846dc7db5",
+    "sha256": "5782f4880af78d29",
   },
   {
     "file": ".houndsman/core/skill/hunt.md",
-    "sha256": "1cf68076325da4ab",
+    "sha256": "d31198580d894427",
   },
   {
     "file": ".houndsman/core/skill/train.md",
@@ -702,6 +706,7 @@ exports[`baseline — artefatos de prepare/finalize gera classification, brief,
 "Discovery: 1 watchdog(s) ativado(s), 3 arquivo(s), 1 deletado(s).
 Briefs: <cwd>/.home/work/<uuid>/briefs/
 Deletado (breaking change): src/alpha/old.ts
+Escopo: 2 arquivo(s), 0 símbolo(s) em 2 faixa(s) alterada(s).
 Jev: pulado (desativado (--no-jev)).
 AST: desabilitado ou sem grammar compatível.
 Sem contexto da PR (rode \`bun run houndsman context\` antes, se houver PR).
@@ -753,7 +758,29 @@ exports[`baseline — artefatos de prepare/finalize gera classification, brief,
   },
   "excludedCount": 0,
   "headSha": "<sha>",
-  "mode": "full"
+  "mode": "full",
+  "changedScope": {
+    "src/alpha/a.ts": {
+      "ranges": [
+        {
+          "start": 1,
+          "end": 2
+        }
+      ],
+      "symbols": [],
+      "source": "hunks"
+    },
+    "src/alpha/b.ts": {
+      "ranges": [
+        {
+          "start": 1,
+          "end": 1
+        }
+      ],
+      "symbols": [],
+      "source": "hunks"
+    }
+  }
 }
 "
 `;
@@ -827,10 +854,20 @@ exports[`baseline — artefatos de prepare/finalize gera classification, brief,
 
 Watchdog baseline.
 
-## Escopo
+## Escopo do domínio
 
 src/alpha/**
 
+## Escopo do diff (símbolos alterados)
+
+> **Regra de escopo:** um finding só é válido quando a \`line\` está nas faixas
+> abaixo. Código fora delas é contexto — use para entender o impacto, nunca
+> como achado. Se a mudança quebra código não alterado, ancore o finding na
+> linha alterada que causou o problema.
+
+- \`src/alpha/a.ts\` — linhas 1-2 _(faixas do diff)_
+- \`src/alpha/b.ts\` — linhas 1 _(faixas do diff)_
+
 ## Regras (por severidade)
 
 - ❌ **blocking** — Nunca usar \`any\`.
@@ -852,10 +889,10 @@ src/alpha/**
 ## Procedimento
 
 1. **FILTER** — descarte o que não for do seu domínio (ver *Prioridade de leitura* e *Não carregar*).
-2. **READ HEAD** — leia os arquivos seletivamente (primeiras ~30 linhas). NUNCA o diff completo.
-3. **GREP** — use as regras críticas/anti-padrões como heurística para localizar violações.
-4. **DEEP-READ** — aprofunde apenas os arquivos com suspeita de violação.
-5. **CONCLUDE** — grave o JSON no caminho de output, com \`reviewedFiles\` preenchido. Sem achados → \`"findings": []\` (arquivo obrigatório). Não escreva markdown livre.
+2. **READ SCOPE** — carregue apenas as faixas alteradas em *Escopo do diff*; o restante do arquivo é só contexto.
+3. **GREP** — use as regras críticas/anti-padrões como heurística para localizar violações nas faixas alteradas.
+4. **DEEP-READ** — aprofunde apenas as faixas com suspeita de violação dentro do escopo.
+5. **CONCLUDE** — grave o JSON no caminho de output, com \`reviewedFiles\` preenchido e \`line\` dentro das faixas alteradas. Sem achados → \`"findings": []\` (arquivo obrigatório). Não escreva markdown livre.
 "
 `;
 

package/src/tests/ai-core.test.ts

@@ -6,7 +6,11 @@ import { describe, expect, test } from "bun:test";
 import type { LanguageModel } from "ai";
 import { z } from "zod";
 import { AiClient, AiUsageBudget, AiUsageRecorder } from "../core/ai";
-import { buildGenerateTextArgs } from "../core/ai/ai-sdk-model-provider";
+import {
+	buildGenerateTextArgs,
+	formatSdkWarning,
+	formatSdkWarnings,
+} from "../core/ai/ai-sdk-model-provider";
 import { temperatureApplies } from "../core/ai/provider-capabilities";
 import { defineHoundsmanConfig } from "../core/config";
 import { DEFAULT_AI_MODEL } from "../core/defaults";
@@ -153,6 +157,39 @@ describe("temperature e providerOptions", () => {
 	});
 });
 
+describe("avisos do AI SDK", () => {
+	test("normaliza os avisos do provider em texto", () => {
+		expect(
+			formatSdkWarning({
+				type: "compatibility",
+				feature: "responseFormat JSON schema",
+				details: "JSON response schema is injected into the system message.",
+			}),
+		).toBe(
+			"compatibility: responseFormat JSON schema — JSON response schema is injected into the system message.",
+		);
+		expect(
+			formatSdkWarning({
+				type: "unsupported",
+				feature: "user message part type: image",
+			}),
+		).toBe("unsupported: user message part type: image");
+		expect(
+			formatSdkWarning({
+				type: "deprecated",
+				setting: "temperature",
+				message: "gone",
+			}),
+		).toBe("deprecated: temperature — gone");
+		expect(formatSdkWarning(null)).toBe("aviso");
+		expect(formatSdkWarnings(undefined)).toEqual([]);
+	});
+
+	test("logger default do SDK fica silencioso após carregar o adapter", () => {
+		expect(typeof globalThis.AI_SDK_LOG_WARNINGS).toBe("function");
+	});
+});
+
 describe("AiUsageBudget / AiUsageRecorder", () => {
 	test("acumula uso e bloqueia no teto", () => {
 		const budget = new AiUsageBudget({ maxCalls: 2 });