@payconductor/houndsman 0.1.1 → 0.1.3

package/README.md

@@ -53,8 +53,8 @@ Cria a camada `.houndsman/`, que é **autocontida** (não instala nada no seu pr
 | `.houndsman/doc-mappings.ts` | você | path → documentação de contexto |
 | `.houndsman/core/**` | auto | Tipos + docs do skill (sincronizados por `houndsman update`) |
 
-> **Não existe "modo completo".** O `setup` já cria a camada inicial com um watchdog de
-> exemplo — troque o exemplo pelas regras reais do seu projeto (ou use `/houndsman-update`).
+> O `setup` já cria a camada inicial com um watchdog de exemplo — troque o exemplo pelas
+> regras reais do seu projeto (ou use `/houndsman train`).
 
 ### 4. Escreva suas regras
 
@@ -71,7 +71,7 @@ bun run houndsman doctor
 No seu harness (Claude Code / agents), invoque o skill:
 
 ```
-/houndsman
+/houndsman hunt
 ```
 
 O skill orquestra tudo e grava o relatório em `.houndsman/.runs/<branch-slug>/review.md`.
@@ -82,16 +82,26 @@ Não precisa rodar nenhum script à mão.
 ## O fluxo de trabalho
 
 ```
-/houndsman
+/houndsman hunt
    ├─ Passo 0  contexto da PR (gh, opcional)
-   ├─ Passo 1  classifica o diff → briefs por watchdog
+   ├─ Passo 1  classifica o diff → briefs por watchdog (incremental quando possível)
    ├─ Passo 2  N subagentes revisam em paralelo
    ├─ Passo 3  consolida em review.md + state.json
-   └─ Passo 4  triagem (UI local ou agente)
+   ├─ Passo 4  valida na UI (server) e marca os achados a executar
+   ├─ Passo 5  fix corrige o grupo atual → run.json (fix_done)
+   └─ Passo 6  verify confere o que resolveu, sem re-revisar
 ```
 
-- Revisão normal: só `/houndsman` (a branch é detectada; base default `main`).
-- Revisar outra branch: `/houndsman feature/minha-branch`.
+O skill tem **4 capabilities**, todas em `/houndsman`:
+
+- **`hunt`** — revisa a PR (default: `/houndsman` = `/houndsman hunt`).
+- **`train`** — mantém/atualiza as regras dos watchdogs.
+- **`fix`** — corrige os findings marcados (`/houndsman fix`).
+- **`verify`** — confere se as violações foram resolvidas (`/houndsman verify`), sem re-revisar.
+
+- Revisão normal: `/houndsman` ou `/houndsman hunt` (a branch é detectada; base default `main`).
+- Revisar outra branch: `/houndsman hunt feature/minha-branch`.
+- Validar e triar na UI: `houndsman server --open` — marque os achados a executar (`execute`).
 - Manual (sem skill): `houndsman context` → `houndsman --base main` → *(subagentes)* →
   `houndsman --finalize`.
 - CI: `houndsman --finalize --fail-on-blocking` (exit 1 se houver bloqueantes).
@@ -114,11 +124,17 @@ bun run houndsman server --open     # UI: triar, comentar, marcar feito, ler art
 **Auto-fix pelo agente** — as linhas mudam depois do fix, e o motor reancora por conteúdo:
 
 ```bash
-bun run houndsman findings list --decision execute --json
-bun run houndsman findings sync
+bun run houndsman findings batch --json     # grupo atual (agrupamento automático) + outros
+# ... o agente corrige apenas esse grupo ...
+bun run houndsman findings sync             # reancora por conteúdo
 bun run houndsman findings done <id>
+bun run houndsman findings verify           # confere o que resolveu (barato, sem re-revisar)
 ```
 
+> A partir da 2ª revisão o `hunt` é **incremental**: revisa só os arquivos que mudaram desde
+> o último `--finalize` e **carrega** os findings dos arquivos inalterados. `--full` força
+> o review completo.
+
 > A identidade do finding é o **conteúdo** (fingerprint), não a linha: itens deslocados
 > pelo fix não se perdem. O estado é local e mora em `.runs/<slug>/state.json` (gitignored).
 
@@ -126,8 +142,8 @@ bun run houndsman findings done <id>
 
 ## Mantendo a configuração
 
-- **Alterar regras** → use o skill **`/houndsman-update`**. Ele prova no código que o padrão
-  existe (evidência) antes de editar e roda as validações.
+- **Alterar regras** → use a capability **`train`** (`/houndsman train`). Ela prova no código
+  que o padrão existe (evidência) antes de editar e roda as validações.
 - **Atualizou a lib?** Sincronize os arquivos auto-gerados sem tocar nas suas regras:
 
   ```bash
@@ -152,5 +168,7 @@ bun run houndsman findings done <id>
   lib (para quem vai contribuir).
 
 - `src/skill/SETUP.md` — referência de configuração passo a passo.
-- `src/skill/houndsman.md` — orquestração do skill `/houndsman`.
-- `src/skill/houndsman-update.md` — manutenção das regras dos watchdogs.
+- `src/skill/SKILL.md` — entry point do skill `/houndsman` (capabilities).
+- `src/skill/hunt.md` — capability `hunt` (revisão de PR).
+- `src/skill/train.md` — capability `train` (manutenção das regras).
+- `src/skill/fix.md` — capability `fix` (correção dos findings).

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@payconductor/houndsman",
-	"version": "0.1.1",
+	"version": "0.1.3",
 	"description": "Orquestrador de revisão de Pull Requests: classifica o diff, despacha watchdogs especializados por domínio e consolida o relatório.",
 	"type": "module",
 	"license": "MIT",

package/src/cli/index.ts

@@ -11,7 +11,7 @@
  *   (default)            Passo 1 — preparar (classificação + briefs + manifesto)
  *   --finalize           Passo 3 — consolidar os findings em review.md
  *   context              Passo 0 — coletar o contexto da PR via `gh`
- *   findings <sub>       Triagem dos findings (list/set/done/sync/...)
+ *   findings <sub>       Triagem/correção dos findings (list/set/done/sync/batch/verify/...)
  *   server               Sobe a UI local de triagem (Bun.serve)
  *   setup                Cria a configuração inicial do projeto (config + skills)
  *   update               Sincroniza os arquivos auto-gerados (.houndsman/core)
@@ -20,11 +20,11 @@
  *   watchdog <id>        Contexto de um watchdog (`--rules`, `--json`)
  *
  * Flags: `--base <b>` · `--head <ref>` · `--branch <b>` · `--dir <d>` ·
- *   `--config <path>` · `--clean` · `--no-jev` · `--fail-on-blocking`.
+ *   `--config <path>` · `--clean` · `--full` · `--no-jev` · `--fail-on-blocking`.
  */
 
 import { runContextCommand } from "../core/commands/context";
-import { runFindingsCommand } from "../core/commands/findings";
+import { runFindingsCommand, runVerifyCommand } from "../core/commands/findings";
 import { parseReviewArgs } from "../core/commands/review";
 import { runSetupCommand } from "../core/commands/setup";
 import { runLibTests } from "../core/commands/test";
@@ -44,7 +44,7 @@ Comandos:
   (nenhum)            Prepara a revisão (classification + briefs + manifesto)
   --finalize          Consolida os findings em review.md
   context             Coleta o contexto da PR via gh (Passo 0)
-  findings <sub>      Triagem dos findings (list · show · set · done · reset · sync · summary · path)
+  findings <sub>      Triagem/correção dos findings (list · show · set · done · reset · sync · summary · batch · verify · path)
   server              Sobe a UI local de triagem (--port, --host, --open)
   setup               Cria a configuração inicial do projeto (config + skills)
   update              Sincroniza os arquivos auto-gerados (.houndsman/core)
@@ -59,6 +59,7 @@ Flags:
   --branch <nome>     Branch alvo (default: detecta do git)
   --dir <dir>         Diretório dos artefatos
   --clean             Descarta findings anteriores
+  --full              Força review completo (ignora o modo incremental)
   --no-jev            Desativa a pré-análise Jev
   --fail-on-blocking  Exit 1 se houver bloqueantes (com --finalize)
 
@@ -67,11 +68,16 @@ Flags de findings:
   --exec <e>          pending | in_progress | done | stale
   --comment <text>    Comentário/instrução adicional
   --watchdog <id>     Filtra por watchdog (list)
-  --severity <s>      Filtra por severidade (list)
+  --severity <s>      Filtra por severidade (list, batch)
   --file <text>       Filtra por trecho do caminho (list)
   --all               Inclui findings ausentes do último relatório
   --json              Saída JSON
-  --limit <n>         Limita o nº de itens (list)`;
+  --limit <n>         Limita o nº de itens (list)
+  --group <key>       Grupo alvo no batch (default: o primeiro)
+  --offset <n>        Paginação dentro do grupo (batch)
+  --include-done      Inclui já concluídos no batch
+  --apply             (verify) Marca os resolvidos como done
+  --fail-on-persisting (verify) Exit 1 se algum blocking persistir`;
 
 function readFlag(args: string[], flag: string): string | undefined {
 	const index = args.indexOf(flag);
@@ -174,11 +180,16 @@ function runWatchdog(config: HoundsmanConfig, args: string[]): void {
 }
 
 /**
- * Subcomando `findings` — triagem dos findings (list/show/set/done/reset/
- * sync/summary/path). Deixa o agente interagir com o estado sem abrir o JSON.
+ * Subcomando `findings` — triagem/correção dos findings (list/show/set/done/reset/
+ * sync/summary/batch/verify/path). Deixa o agente interagir com o estado sem abrir
+ * o JSON. O `verify` é assíncrono (consulta opcional ao Jev) — roteado à parte.
  */
-function runFindings(config: HoundsmanConfig, args: string[]): void {
-	const result = runFindingsCommand(config, args);
+async function runFindings(config: HoundsmanConfig, args: string[]): Promise<void> {
+	const sub = args.find((arg) => !arg.startsWith("-"));
+	const result =
+		sub === "verify"
+			? await runVerifyCommand(config, args)
+			: runFindingsCommand(config, args);
 	if (result.exitCode !== 0) {
 		console.error(result.output);
 		process.exit(result.exitCode);
@@ -267,7 +278,7 @@ export async function main(): Promise<void> {
 			runWatchdog(config, rest);
 			return;
 		case "findings":
-			runFindings(config, rest);
+			await runFindings(config, rest);
 			return;
 		case "server":
 			runServer(config, rest);

package/src/core/assets.ts

@@ -17,6 +17,9 @@ export const MEDIA_DIR = join(import.meta.dir, "..", "..", "assets");
 /** Nome do arquivo de schema de output dos watchdogs. */
 export const OUTPUT_FORMAT_FILE = "OUTPUT-FORMAT.md";
 
+/** Nome do arquivo-base do skill (`SKILL.md`) — entry point escrito para cada harness. */
+export const SKILL_FILE = "SKILL.md";
+
 /** Caminho absoluto de um asset embarcado em `src/skill/`. */
 export function assetPath(fileName: string): string {
 	return join(SKILL_DIR, fileName);

package/src/core/brief.ts

@@ -1,8 +1,8 @@
 /**
  * Renderização do brief de um watchdog (biblioteca) — `defaultRenderBrief`.
  *
- * O procedimento (`PROCEDURE`) é compartilhado por todos os watchdogs; o que era
- * protocolo específico vive nas regras do watchdog (`rules`).
+ * O procedimento (`PROCEDURE`) é compartilhado por todos os watchdogs; o que é
+ * específico do domínio vive nas regras do watchdog (`rules`).
  */
 
 import {
@@ -17,7 +17,6 @@ import {
 
 /**
  * Procedimento de revisão — compartilhado por todos os watchdogs.
- * Substitui o antigo protocolo genérico de 5 passos + o ponteiro `PROTOCOL_GLOB`.
  */
 export const PROCEDURE: readonly string[] = [
 	"1. **FILTER** — descarte o que não for do seu domínio (ver *Prioridade de leitura* e *Não carregar*).",

package/src/core/commands/findings.ts

@@ -3,13 +3,19 @@
  *
  * Lê/grava o `state.json` da run (`findings-state.ts`). Devolve o texto pronto
  * (markdown ou JSON) + exit code; o CLI decide o log/exit. O agente do usuário
- * usa `list`/`set`/`done` para interagir sem abrir o JSON à mão.
+ * usa `list`/`set`/`done` (e `batch` para lotes de correção) para interagir sem abrir o JSON à mão.
  *
  * Se o `state.json` não existir, é re-construído a partir de
  * `findings/*.json` + `classification.json` (não exige `--finalize`).
  */
 
-import { type HoundsmanConfig, resolveArtifactDir } from "../config";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+	type HoundsmanConfig,
+	resolveArtifactDir,
+	resolveJevConcurrency,
+} from "../config";
 import {
 	applyFindingUpdate,
 	buildStateFromRunDir,
@@ -29,9 +35,22 @@ import {
 	summarize,
 	syncState,
 } from "../findings-state";
-import { relFromRoot } from "../paths";
+import { buildFixBatch, type FixBatchResult } from "../fix-batch";
+import { JevCandidatesStore, JevClient, JevVerifier } from "../jev";
+import { relFromRoot, VERIFY_FILE } from "../paths";
 import { currentBranch } from "../pr-context";
+import { pingFindingsStatus } from "../run-status";
 import { SEVERITY_EMOJI, SEVERITY_ORDER, type Severity } from "../types";
+import {
+	applyJev,
+	applyResolutions,
+	selectVerifiable,
+	summarizeVerify,
+	type VerifyEntry,
+	type VerifyStatus,
+	type VerifySummary,
+	verifyLocal,
+} from "../verify";
 
 export type FindingsCommandResult = {
 	output: string;
@@ -49,6 +68,8 @@ const VALUE_FLAGS = new Set([
 	"--limit",
 	"--comment",
 	"--by",
+	"--offset",
+	"--group",
 ]);
 
 type ParsedArgs = {
@@ -161,6 +182,42 @@ function renderSummary(state: FindingsStateFile, summary: FindingsSummary): stri
 	].join("\n");
 }
 
+/** Mix de severidade compacto (ex.: `❌1 ⚠️2`). */
+function severityBreakdown(bySeverity: Record<Severity, number>): string {
+	return SEVERITY_ORDER.filter((severity) => bySeverity[severity] > 0)
+		.map((severity) => `${SEVERITY_EMOJI[severity]}${bySeverity[severity]}`)
+		.join(" ");
+}
+
+/** Render do lote de correção: grupo atual paginado + outros grupos. */
+function renderBatch(result: FixBatchResult): string {
+	const { dimension, current, others, totals } = result;
+	if (totals.queue === 0) return "Nenhum finding pendente de correção.";
+
+	const lines = [
+		`# Lote de correção — agrupado por ${dimension} (${totals.groups} grupo(s))`,
+		"",
+		`## Grupo atual — ${current.key} (${current.total} finding(s), mostrando ${current.returned})`,
+	];
+	for (const finding of current.findings) lines.push(...renderFindingLine(finding));
+	if (current.remaining > 0) {
+		lines.push("", `_… +${current.remaining} neste grupo (use \`--offset\`)._`);
+	}
+	if (others.length > 0) {
+		lines.push("", "## Outros grupos disponíveis");
+		for (const group of others) {
+			lines.push(
+				`- ${group.key} — ${group.count} (${severityBreakdown(group.bySeverity)})`,
+			);
+		}
+	}
+	lines.push(
+		"",
+		`fila: ${totals.queue} · retornados: ${totals.returned} · grupos: ${totals.groups}`,
+	);
+	return lines.join("\n");
+}
+
 // ---------------------------------------------------------------------------
 // Execução
 // ---------------------------------------------------------------------------
@@ -197,6 +254,13 @@ function filterFrom(parsed: ParsedArgs): FindingsFilter {
 	};
 }
 
+/** Faz ping no `run.json` (status derivado do estado atual) após uma mutação. */
+function pingStatus(config: HoundsmanConfig, parsed: ParsedArgs): void {
+	const { dir, branch } = resolveDir(config, parsed);
+	const state = FindingsStateStore.at(dir, branch).read();
+	if (state) pingFindingsStatus(runDir(dir, branch), state);
+}
+
 /** Aplica uma atualização a um finding e persiste. */
 function updateOne(
 	config: HoundsmanConfig,
@@ -294,6 +358,7 @@ function execute(config: HoundsmanConfig, parsed: ParsedArgs): FindingsCommandRe
 				);
 			}
 			const finding = updateOne(config, parsed, id, update);
+			pingStatus(config, parsed);
 			return {
 				output: parsed.bools.has("--json")
 					? JSON.stringify(finding, null, 2)
@@ -304,6 +369,7 @@ function execute(config: HoundsmanConfig, parsed: ParsedArgs): FindingsCommandRe
 		case "done": {
 			const ids = requireIds(parsed, "done");
 			const updated = updateMany(config, parsed, ids, { execState: "done" });
+			pingStatus(config, parsed);
 			return {
 				output: `Marcados como done: ${updated.map((f) => f.id).join(", ")}.`,
 				exitCode: 0,
@@ -316,6 +382,7 @@ function execute(config: HoundsmanConfig, parsed: ParsedArgs): FindingsCommandRe
 				execState: "pending",
 				comment: "",
 			});
+			pingStatus(config, parsed);
 			return {
 				output: `Triagem reiniciada: ${updated.map((f) => f.id).join(", ")}.`,
 				exitCode: 0,
@@ -327,6 +394,7 @@ function execute(config: HoundsmanConfig, parsed: ParsedArgs): FindingsCommandRe
 			const state = loadState(config, parsed);
 			const result = syncState(state, fileReader(process.cwd()));
 			store.write(state);
+			pingStatus(config, parsed);
 			const output = parsed.bools.has("--json")
 				? JSON.stringify(result, null, 2)
 				: [
@@ -357,9 +425,26 @@ function execute(config: HoundsmanConfig, parsed: ParsedArgs): FindingsCommandRe
 			const path = FindingsStateStore.at(dir, branch).filePath;
 			return { output: relFromRoot(path), exitCode: 0 };
 		}
+		case "batch": {
+			const state = loadState(config, parsed);
+			const severity = parsed.values["--severity"];
+			const offset = Number(parsed.values["--offset"]);
+			const result = buildFixBatch(state, {
+				severity: severity ? (severity as Severity) : undefined,
+				includeDone: parsed.bools.has("--include-done"),
+				offset: Number.isFinite(offset) ? offset : undefined,
+				group: parsed.values["--group"],
+			});
+			return {
+				output: parsed.bools.has("--json")
+					? JSON.stringify(result, null, 2)
+					: renderBatch(result),
+				exitCode: 0,
+			};
+		}
 		default:
 			return {
-				output: `Subcomando '${parsed.sub}' desconhecido. Use: list, show, set, done, reset, sync, summary, path.`,
+				output: `Subcomando '${parsed.sub}' desconhecido. Use: list, show, set, done, reset, sync, summary, batch, path.`,
 				exitCode: 1,
 			};
 	}
@@ -388,3 +473,146 @@ function requireIds(parsed: ParsedArgs, sub: string): string[] {
 	}
 	return parsed.positionals;
 }
+
+// ---------------------------------------------------------------------------
+// verify — as violações foram resolvidas? (sem re-revisar a PR)
+// ---------------------------------------------------------------------------
+
+/** Rótulo curto de cada status de verificação. */
+const VERIFY_LABEL: Record<VerifyStatus, string> = {
+	resolved: "✅ resolvido",
+	persisting: "❌ persiste",
+	uncertain: "⚠️ incerto",
+	"file-missing": "🗑️ arquivo ausente",
+};
+
+/** Render da verificação: contagem por status + uma linha por finding. */
+function renderVerify(
+	state: FindingsStateFile,
+	entries: VerifyEntry[],
+	summary: VerifySummary,
+	meta: { jevChecked: number; jevReason?: string },
+): string {
+	if (entries.length === 0) return "Nenhum finding para verificar.";
+	const lines = [
+		`# Verificação — ${state.branch} (${entries.length})`,
+		"",
+		`Resolvidos: ${summary.resolved} · Persistem: ${summary.persisting} · Incertos: ${summary.uncertain} · Arquivo ausente: ${summary["file-missing"]}`,
+	];
+	if (meta.jevChecked > 0) lines.push(`Confirmados por Jev: ${meta.jevChecked}.`);
+	else if (meta.jevReason) lines.push(`Jev: pulado (${meta.jevReason}).`);
+	lines.push("");
+	for (const entry of entries) {
+		const location = entry.line ? `${entry.file}:${entry.line}` : entry.file;
+		const via =
+			entry.basis === "jev" ? ` · Jev ${(entry.confidence ?? 0).toFixed(2)}` : "";
+		lines.push(
+			`- \`${entry.id}\` ${VERIFY_LABEL[entry.status]} — **${entry.severity}** \`${location}\` — ${entry.rule}${via}`,
+			`  ${entry.message}`,
+		);
+		if (entry.detail) lines.push(`  _${entry.detail}_`);
+	}
+	return lines.join("\n");
+}
+
+/**
+ * Subcomando `findings verify` — checa se as violações foram resolvidas, sem
+ * re-revisar a PR. Tier local (grátis) + confirmação Jev dos casos ambíguos
+ * (fail-open). `--apply` persiste os `resolved` como `done`.
+ */
+export async function runVerifyCommand(
+	config: HoundsmanConfig,
+	args: string[],
+): Promise<FindingsCommandResult> {
+	const parsed = parseArgs(args);
+	try {
+		return await executeVerify(config, parsed);
+	} catch (error) {
+		return {
+			output: error instanceof Error ? error.message : String(error),
+			exitCode: 1,
+		};
+	}
+}
+
+async function executeVerify(
+	config: HoundsmanConfig,
+	parsed: ParsedArgs,
+): Promise<FindingsCommandResult> {
+	const { dir, branch } = resolveDir(config, parsed);
+	const store = FindingsStateStore.at(dir, branch);
+	const state = loadState(config, parsed);
+
+	const findings = selectVerifiable(state, filterFrom(parsed));
+	const entries = verifyLocal(findings, fileReader(process.cwd()));
+
+	// Tier 1 — Jev só nos ambíguos (fail-open: sem chave/erro mantém o provisório).
+	let jevChecked = 0;
+	let jevReason: string | undefined;
+	const ambiguous = entries.filter((entry) => entry.ambiguous);
+	if (ambiguous.length > 0) {
+		const verifier = new JevVerifier(new JevClient());
+		if (parsed.bools.has("--no-jev")) {
+			jevReason = "desativado (--no-jev)";
+		} else if (!verifier.isConfigured()) {
+			jevReason = "TYPESAFE_API_KEY não configurada";
+		} else {
+			const byId = new Map(findings.map((finding) => [finding.id, finding]));
+			const outcome = await verifier.verify(
+				ambiguous.map((entry) => ({
+					id: entry.id,
+					file: entry.file,
+					rule: entry.rule,
+					foundAtSha: byId.get(entry.id)?.foundAtSha,
+				})),
+				{
+					headSha: state.reviewed?.headSha,
+					concurrency: resolveJevConcurrency(config),
+				},
+			);
+			applyJev(entries, outcome.confidence, JevCandidatesStore.THRESHOLD);
+			jevChecked = outcome.checked;
+			jevReason = outcome.reason;
+		}
+	}
+
+	const summary = summarizeVerify(entries);
+	const reportPath = join(runDir(dir, branch), VERIFY_FILE);
+	writeFileSync(
+		reportPath,
+		`${renderVerify(state, entries, summary, { jevChecked, jevReason })}\n`,
+	);
+
+	let applied: string[] = [];
+	if (parsed.bools.has("--apply")) {
+		store.update((current) => {
+			applied = applyResolutions(current, entries);
+		});
+		pingStatus(config, parsed);
+	}
+
+	const output = parsed.bools.has("--json")
+		? JSON.stringify(
+				{ branch, summary, jevChecked, jevReason, applied, entries },
+				null,
+				2,
+			)
+		: [
+				renderVerify(state, entries, summary, { jevChecked, jevReason }),
+				"",
+				`Relatório: ${relFromRoot(reportPath)}`,
+				parsed.bools.has("--apply")
+					? `Aplicados (done): ${applied.length > 0 ? applied.join(", ") : "—"}.`
+					: "",
+			]
+				.filter(Boolean)
+				.join("\n");
+
+	const failOnPersisting =
+		parsed.bools.has("--fail-on-persisting") &&
+		entries.some(
+			(entry) => entry.status === "persisting" && entry.severity === "blocking",
+		);
+
+	return { output, exitCode: failOnPersisting ? 1 : 0 };
+}

package/src/core/commands/review.ts

@@ -14,6 +14,7 @@ const BOOLEAN_FLAGS = new Set([
 	"--fail-on-blocking",
 	"--clean",
 	"--no-jev",
+	"--full",
 ]);
 
 function applyValue(opts: ReviewOptions, flag: string, value: string | undefined): void {
@@ -29,6 +30,7 @@ function applyBoolean(opts: ReviewOptions, flag: string): void {
 	else if (flag === "--fail-on-blocking") opts.failOnBlocking = true;
 	else if (flag === "--clean") opts.clean = true;
 	else if (flag === "--no-jev") opts.noJev = true;
+	else if (flag === "--full") opts.full = true;
 }
 
 /** Converte argv (sem o subcomando) nas opções de prepare/finalize. */

package/src/core/commands/scaffold.ts

@@ -15,7 +15,7 @@
 
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, join } from "node:path";
-import { SKILL_DIR } from "../assets";
+import { SKILL_DIR, SKILL_FILE } from "../assets";
 import {
 	ARTIFACT_DIR,
 	CORE_DIR,
@@ -279,25 +279,6 @@ core/
 .runs/
 `;
 
-const SKILL_POINTER = (
-	name: string,
-	projectName: string,
-	canonical: string,
-	description: string,
-	argumentHint: string,
-): string => `---
-name: ${name}
-description: '${description}'
-argument-hint: '${argumentHint}'
----
-
-# ${name} — ${projectName}
-
-> **Ponteiro.** O conteúdo canônico está em \`${canonical}\`.
-
-Leia e siga \`${canonical}\`.
-`;
-
 // ---------------------------------------------------------------------------
 // Escrita
 // ---------------------------------------------------------------------------
@@ -345,15 +326,17 @@ export function writeUserLayer(ctx: ScaffoldContext): void {
 
 /**
  * Arquivos auto-gerados: tipos, docs do skill, `.gitignore` (ignora `core/` e
- * `.runs/`) e os ponteiros de skill dos harnesses. Sempre sobrescritos (é o
- * alvo do `update`).
+ * `.runs/`) e o `SKILL.md` de cada harness. Sempre sobrescritos (é o alvo do
+ * `update`).
  */
 export function syncGeneratedFiles(ctx: ScaffoldContext): void {
 	writeGeneratedFile(ctx, join(CORE_DIR, "types.ts"), TYPES_TEMPLATE);
 	writeGeneratedFile(ctx, join(PROJECT_DIR, ".gitignore"), PROJECT_GITIGNORE);
 
+	// Docs do skill vão para `.houndsman/core/skill/`. O `SKILL.md` é o entry point
+	// dos harnesses (escrito em `writeHarnessPointers`), não um doc da camada.
 	for (const name of readdirSync(SKILL_DIR)) {
-		if (!name.endsWith(".md")) continue;
+		if (!name.endsWith(".md") || name === SKILL_FILE) continue;
 		const raw = readFileSync(join(SKILL_DIR, name), "utf8");
 		writeGeneratedFile(
 			ctx,
@@ -365,29 +348,15 @@ export function syncGeneratedFiles(ctx: ScaffoldContext): void {
 	for (const harness of ctx.harnesses) writeHarnessPointers(ctx, harness);
 }
 
-/** Escreve os ponteiros de skill de um harness. */
+/**
+ * Escreve o `SKILL.md` do harness a partir do asset base (`src/skill/SKILL.md`),
+ * resolvendo `{{projectName}}`. O texto do skill vive no asset — não aqui.
+ */
 function writeHarnessPointers(ctx: ScaffoldContext, harness: Harness): void {
-	const pointerDir = `.${harness}/skills`;
-	writeGeneratedFile(
-		ctx,
-		join(pointerDir, "houndsman", "SKILL.md"),
-		SKILL_POINTER(
-			"houndsman",
-			ctx.projectName,
-			`${CORE_SKILL_DIR}/houndsman.md`,
-			"Revisa Pull Requests com watchdogs especializados por domínio. Orquestra `bun run houndsman context` → `bun run houndsman` → subagentes → `bun run houndsman --finalize`. Config em `houndsman.config.ts`; regras em `.houndsman/`; relatório em `.houndsman/.runs/<branch-slug>/review.md`.",
-			"Nome da branch (opcional, detecta automaticamente se omitido)",
-		),
-	);
+	const raw = readFileSync(join(SKILL_DIR, SKILL_FILE), "utf8");
 	writeGeneratedFile(
 		ctx,
-		join(pointerDir, "houndsman-update", "SKILL.md"),
-		SKILL_POINTER(
-			"houndsman-update",
-			ctx.projectName,
-			`${CORE_SKILL_DIR}/houndsman-update.md`,
-			"Atualiza as regras e protocolos do skill houndsman (watchdogs, exclusões, mapeamentos de docs).",
-			"Watchdog alvo (opcional)",
-		),
+		join(`.${harness}`, "skills", "houndsman", SKILL_FILE),
+		raw.replaceAll("{{projectName}}", ctx.projectName),
 	);
 }

package/src/core/diff-source.ts

@@ -2,9 +2,8 @@
  * Coleta do diff em um único passo (biblioteca).
  *
  * Roda `git diff base...head` **uma vez** (patch) e `--numstat` **uma vez**
- * (churn), fatiando o patch por arquivo em memória. Substitui os N spawns de
- * `git diff -- <arquivo>` (antes feitos por arquivo, no `jev-detector`): o custo
- * deixa de crescer com o número de arquivos da PR.
+ * (churn), fatiando o patch por arquivo em memória — o custo não cresce com o
+ * número de arquivos da PR.
  *
  * Usado por `orchestrator.prepare` (churn para a classificação + patch para o
  * Jev) e por `classifyRange` (fallback standalone).
@@ -24,7 +23,8 @@ export type CollectDiffOptions = {
 	maxPerFileChars?: number;
 };
 
-const DEFAULT_MAX_PER_FILE_CHARS = 8_000;
+/** Teto default de caracteres por arquivo no patch (compartilhado com o git-revision). */
+export const DEFAULT_MAX_PER_FILE_CHARS = 8_000;
 
 /** Executa `git` com `core.quotepath=false` (paths literais) e devolve o stdout. */
 function runGit(args: string[]): string {