@payconductor/houndsman 0.4.0 → 0.6.0

package/src/core/brief.ts

@@ -5,6 +5,7 @@
  * específico do domínio vive nas regras do watchdog (`rules`).
  */
 
+import type { AstDelta } from "./ast/types";
 import {
 	type Rule,
 	SEVERITY_EMOJI,
@@ -117,6 +118,141 @@ function deletedSection(args: WatchdogRenderArgs, def: WatchdogDefinition): stri
 	];
 }
 
+/** Escapa um valor para uso em code-span (evita quebrar o markdown). */
+function inlineCode(value: string): string {
+	return `\`${value.replace(/`/g, "'")}\``;
+}
+
+/** Trunca um texto longo (assinatura) para o brief. */
+function shorten(value: string, max = 120): string {
+	const normalized = value.replace(/\s+/g, " ").trim();
+	return normalized.length > max ? `${normalized.slice(0, max - 1)}…` : normalized;
+}
+
+/** Linhas de um delta estrutural (compactas e determinísticas). */
+function deltaLines(delta: AstDelta): string[] {
+	const lines: string[] = [];
+	for (const symbol of delta.addedSymbols.slice(0, 4)) {
+		lines.push(`+ ${inlineCode(symbol.name)} (${symbol.kind})`);
+	}
+	for (const symbol of delta.removedSymbols.slice(0, 4)) {
+		lines.push(`− ${inlineCode(symbol.name)} (${symbol.kind})`);
+	}
+	for (const symbol of delta.modifiedSymbols.slice(0, 4)) {
+		lines.push(`~ ${inlineCode(symbol.name)} (${symbol.kind})`);
+	}
+	for (const change of delta.changedSignatures.slice(0, 3)) {
+		lines.push(
+			`assinatura ${inlineCode(change.name)}: ${inlineCode(shorten(change.before) || "—")} → ${inlineCode(shorten(change.after) || "—")}`,
+		);
+	}
+	if (delta.addedImports.length > 0) {
+		lines.push(
+			`imports + ${delta.addedImports.slice(0, 4).map(inlineCode).join(", ")}`,
+		);
+	}
+	if (delta.removedImports.length > 0) {
+		lines.push(
+			`imports − ${delta.removedImports.slice(0, 4).map(inlineCode).join(", ")}`,
+		);
+	}
+	return lines;
+}
+
+/**
+ * Plano de revisão sugerido por IA — complementa (nunca substitui) as regras.
+ */
+function aiPlanSection(args: WatchdogRenderArgs): string[] {
+	const plan = args.aiPlan;
+	if (!plan) return [];
+	const focus = plan.focus ?? [];
+	const questions = plan.questions ?? [];
+	const risks = plan.risks ?? [];
+	const logic = plan.logic ?? [];
+	const domain = plan.domain ?? [];
+	if (
+		focus.length === 0 &&
+		questions.length === 0 &&
+		risks.length === 0 &&
+		logic.length === 0 &&
+		domain.length === 0
+	) {
+		return [];
+	}
+	const lines = [
+		"## Plano de revisão (IA) — sugestão",
+		"",
+		"> Sugestão automática para orientar a leitura. **Não** substitui as regras",
+		"> do watchdog nem dispensa confirmar cada violação no código.",
+		"",
+	];
+	if (focus.length > 0) {
+		lines.push("**Foco de leitura:**", "");
+		for (const item of focus.slice(0, 5)) lines.push(`- ${item}`);
+		lines.push("");
+	}
+	if (questions.length > 0) {
+		lines.push("**Perguntas de verificação:**", "");
+		for (const item of questions.slice(0, 3)) lines.push(`- ${item}`);
+		lines.push("");
+	}
+	if (risks.length > 0) {
+		lines.push("**Riscos prováveis:**", "");
+		for (const item of risks.slice(0, 3)) lines.push(`- ${item}`);
+		lines.push("");
+	}
+	if (logic.length > 0) {
+		lines.push("**Consistência lógica:**", "");
+		for (const item of logic.slice(0, 3)) lines.push(`- ${item}`);
+		lines.push("");
+	}
+	if (domain.length > 0) {
+		lines.push("**Domínio de negócio:**", "");
+		for (const item of domain.slice(0, 3)) lines.push(`- ${item}`);
+		lines.push("");
+	}
+	return lines;
+}
+
+/**
+ * Estrutura/delta dos arquivos do watchdog (AST). É um mapa para orientar a
+ * leitura — o watchdog confirma no código e não trata como achado.
+ */
+function astSection(args: WatchdogRenderArgs): string[] {
+	const entries = args.ast ?? [];
+	if (entries.length === 0) return [];
+	const lines: string[] = [
+		"## Estrutura (AST)",
+		"",
+		"> Delta estrutural dos arquivos do seu domínio. Use como mapa para",
+		"> priorizar a leitura; **não** é achado por si só.",
+		"",
+	];
+	let rendered = 0;
+	for (const entry of entries) {
+		const parts = deltaLines(entry.delta);
+		if (entry.importers && entry.importers.length > 0) {
+			parts.push(
+				`impacto: ${entry.importers.slice(0, 5).map(inlineCode).join(", ")}` +
+					(entry.importers.length > 5
+						? ` (+${entry.importers.length - 5})`
+						: ""),
+			);
+		}
+		if (parts.length === 0) continue;
+		lines.push(
+			`### ${inlineCode(entry.file)}`,
+			"",
+			...parts.map((part) => `- ${part}`),
+			"",
+		);
+		rendered++;
+		if (rendered >= 12) break;
+	}
+	if (rendered === 0) return [];
+	return lines;
+}
+
 /**
  * Render padrão do brief de um watchdog (ordem estável).
  * `def` é a definição do próprio watchdog (evita ciclo com o registry).
@@ -139,6 +275,8 @@ export function defaultRenderBrief(
 
 	if (args.context) lines.push(...renderBriefContext(args.context));
 
+	lines.push(...aiPlanSection(args));
+	lines.push(...astSection(args));
 	lines.push(...optionalList("Prioridade de leitura", def.reviewFocus));
 	lines.push(
 		"## Regras (por severidade)",

package/src/core/commands/findings.ts

@@ -10,7 +10,10 @@
  * com o UUID interno no banco.
  */
 
+import { AiClient } from "../ai/ai-client";
+import { AiVerifier } from "../ai/features/verifier";
 import { type HoundsmanConfig, resolveJevConcurrency } from "../config";
+import { ENV_NAMES } from "../env";
 import {
 	applyFindingUpdate,
 	FINDING_DECISIONS,
@@ -36,9 +39,11 @@ import {
 	type SubmitPreview,
 	type SubmitSelection,
 	submitFindings,
+	syncResolvedThreads,
 } from "../github-review";
 import { VERIFY_FILE } from "../paths";
 import { currentBranch } from "../pr-context";
+import { ProjectConfig } from "../project-config";
 import { BatchPresenter } from "../renderers/batch-presenter";
 import { FindingsPresenter } from "../renderers/findings-presenter";
 import { VerifyPresenter } from "../renderers/verify-presenter";
@@ -214,6 +219,25 @@ function pingStatus(ctx: CommandContext, state: FindingsStateFile): void {
 	pingFindingsStatus(ctx.storage, ctx.review.id, state);
 }
 
+/**
+ * Resolve no GitHub as threads dos findings recém-resolvidos localmente.
+ * Fail-open (`gh` ausente/sem PR ⇒ só a mensagem). Devolve a linha para o
+ * output ou `null` quando não há vínculo remoto pendente.
+ */
+function syncThreadsOutput(ctx: CommandContext, ids: readonly string[]): string | null {
+	if (ids.length === 0) return null;
+	const state = loadState(ctx);
+	const outcome = syncResolvedThreads({ state, ids });
+	if (outcome.checked === 0) return null;
+	if (outcome.updated.length > 0) ctx.storage.writeFindings(ctx.review.id, state);
+	if (!outcome.available) {
+		return `GitHub: threads não sincronizadas (${outcome.reason}).`;
+	}
+	const failures =
+		outcome.failed.length > 0 ? `, ${outcome.failed.length} falha(s)` : "";
+	return `GitHub: ${outcome.resolved.length} thread(s) resolvida(s), ${outcome.skipped.length} já resolvida(s)/pulada(s)${failures}.`;
+}
+
 /** Aplica uma atualização a um finding e persiste. */
 function updateOne(
 	ctx: CommandContext,
@@ -309,10 +333,17 @@ function execute(
 			}
 			const finding = updateOne(ctx, input, update);
 			pingStatus(ctx, loadState(ctx));
+			const threads =
+				update.execState === "done" ? syncThreadsOutput(ctx, [finding.id]) : null;
 			return {
 				output: parsed.bools.has("--json")
 					? JSON.stringify(finding, null, 2)
-					: `Atualizado: \`${finding.id}\` → ${finding.decision}/${finding.execState}.`,
+					: [
+							`Atualizado: \`${finding.id}\` → ${finding.decision}/${finding.execState}.`,
+							threads,
+						]
+							.filter(Boolean)
+							.join("\n"),
 				exitCode: 0,
 			};
 		}
@@ -320,8 +351,17 @@ function execute(
 			const ids = requireIds(parsed, "done");
 			const updated = updateMany(ctx, ids, { execState: "done" });
 			pingStatus(ctx, loadState(ctx));
+			const threads = syncThreadsOutput(
+				ctx,
+				updated.map((finding) => finding.id),
+			);
 			return {
-				output: `Marcados como done: ${updated.map((f) => f.id).join(", ")}.`,
+				output: [
+					`Marcados como done: ${updated.map((f) => f.id).join(", ")}.`,
+					threads,
+				]
+					.filter(Boolean)
+					.join("\n"),
 				exitCode: 0,
 			};
 		}
@@ -449,6 +489,20 @@ export async function runVerifyCommand(
 	}
 }
 
+/** Trecho de ~20 linhas ao redor do finding (entrada da verificação por IA). */
+function snippetsAround(content: string | null, line: number | null): string {
+	if (!content) return "(arquivo indisponível)";
+	const lines = content.replace(/\r\n/g, "\n").split("\n");
+	const center = line && line > 0 ? line : 1;
+	const start = Math.max(1, center - 10);
+	const end = Math.min(lines.length, center + 10);
+	return lines
+		.slice(start - 1, end)
+		.map((text, index) => `${start + index}: ${text}`)
+		.join("\n")
+		.slice(0, 4_000);
+}
+
 async function executeVerify(
 	config: HoundsmanConfig,
 	storage: StorageProvider,
@@ -474,7 +528,7 @@ async function executeVerify(
 		if (parsed.bools.has("--no-jev")) {
 			jevReason = "desativado (--no-jev)";
 		} else if (!jevVerifier.isConfigured()) {
-			jevReason = "TYPESAFE_API_KEY não configurada";
+			jevReason = `${ENV_NAMES.typeSafeApiKey} não configurada`;
 		} else {
 			const byId = new Map(findings.map((finding) => [finding.id, finding]));
 			const outcome = await jevVerifier.verify(
@@ -495,6 +549,44 @@ async function executeVerify(
 		}
 	}
 
+	// Tier 2 — IA opcional para os ambíguos que o Jev não respondeu.
+	let aiChecked = 0;
+	let aiReason: string | undefined;
+	const stillAmbiguous = entries.filter(
+		(entry) => entry.ambiguous && entry.basis === "anchor",
+	);
+	if (stillAmbiguous.length > 0) {
+		const client = new AiClient({ project: new ProjectConfig(config) });
+		const aiVerifier = new AiVerifier(client);
+		if (parsed.bools.has("--no-ai")) {
+			aiReason = "desativado (--no-ai)";
+		} else if (!client.available) {
+			aiReason = "IA não configurada";
+		} else if (!aiVerifier.enabled) {
+			aiReason = "feature ai.features.verify desligada";
+		} else {
+			const readFile = fileReader(process.cwd());
+			const byId = new Map(findings.map((finding) => [finding.id, finding]));
+			const confidence = await aiVerifier.verify({
+				findings: stillAmbiguous.map((entry) => ({
+					id: entry.id,
+					rule: entry.rule,
+					file: entry.file,
+					line: entry.line,
+					message: byId.get(entry.id)?.message ?? entry.message,
+					snippets: snippetsAround(readFile(entry.file), entry.line),
+				})),
+			});
+			aiChecked = verifier.applyConfidence(
+				entries,
+				confidence,
+				JevCandidatesStore.THRESHOLD,
+				"ai",
+			);
+			aiReason = `${aiChecked} caso(s) confirmado(s) pela IA`;
+		}
+	}
+
 	const summary = verifier.summarize(entries);
 	const location = ctx.storage.location(ctx.review.id);
 	ctx.storage.writeArtifact(ctx.review.id, {
@@ -511,6 +603,9 @@ async function executeVerify(
 		pingStatus(ctx, current);
 	}
 
+	// Resolvidos localmente ⇒ resolve as conversas correspondentes no PR.
+	const threads = syncThreadsOutput(ctx, applied);
+
 	const output = parsed.bools.has("--json")
 		? JSON.stringify(
 				{
@@ -518,6 +613,8 @@ async function executeVerify(
 					summary,
 					jevChecked,
 					jevReason,
+					aiChecked,
+					aiReason,
 					applied,
 					entries,
 				},
@@ -534,6 +631,7 @@ async function executeVerify(
 				parsed.bools.has("--apply")
 					? `Aplicados (done): ${applied.length > 0 ? applied.join(", ") : "—"}.`
 					: "",
+				threads,
 			]
 				.filter(Boolean)
 				.join("\n");
@@ -603,6 +701,21 @@ function renderSubmitOutcome(outcome: SubmitOutcome, json: boolean): string {
 		"",
 		`Enviados: ${outcome.posted.length} · Falhas: ${outcome.failed.length} · Pulados: ${outcome.skipped.length}`,
 	];
+	const review = outcome.review;
+	if (review?.id !== undefined) {
+		const target = review.url ? ` — ${review.url}` : "";
+		if (review.created) {
+			const status = review.finalized
+				? `finalizada (${review.event})`
+				: "criada, mas não finalizada";
+			lines.push(`Revisão #${review.id} ${status}${target}`);
+		} else {
+			lines.push(
+				`Comentários adicionados à revisão pendente #${review.id}${target}`,
+			);
+		}
+	}
+	if (review?.error) lines.push(`Revisão: ❌ ${review.error}`);
 	if (outcome.general) {
 		lines.push(
 			`Comentário geral: ${outcome.general.url ?? outcome.general.commentId} (${outcome.general.ids.length})`,
@@ -615,8 +728,9 @@ function renderSubmitOutcome(outcome: SubmitOutcome, json: boolean): string {
 }
 
 /**
- * Subcomando `findings submit` — envia os findings selecionados como comentários
- * na PR (via `gh`). `--dry-run` mostra a prévia sem postar. Assíncrono (gh).
+ * Subcomando `findings submit` — envia os findings selecionados numa revisão da
+ * PR (via `gh`): reaproveita a revisão pendente ou cria/finaliza uma nova.
+ * `--dry-run` mostra a prévia sem postar. Assíncrono (gh).
  */
 export async function runSubmitCommand(
 	config: HoundsmanConfig,
@@ -664,6 +778,6 @@ async function executeSubmit(
 
 	return {
 		output: renderSubmitOutcome(outcome, json),
-		exitCode: outcome.failed.length > 0 ? 1 : 0,
+		exitCode: outcome.failed.length > 0 || Boolean(outcome.review?.error) ? 1 : 0,
 	};
 }

package/src/core/commands/review.ts

@@ -28,7 +28,9 @@ export function parseReviewArgs(args: string[]): ReviewOptions {
 	if (parser.has("--fail-on-blocking")) opts.failOnBlocking = true;
 	if (parser.has("--clean")) opts.clean = true;
 	if (parser.has("--no-jev")) opts.noJev = true;
+	if (parser.has("--no-ast")) opts.noAst = true;
 	if (parser.has("--full")) opts.full = true;
+	if (parser.has("--no-ai")) opts.noAi = true;
 
 	return opts;
 }

package/src/core/commands/scaffold.ts

@@ -8,14 +8,22 @@
  *   ├── .gitignore          AUTO — ignora core/ (gerado)
  *   ├── core/types.ts       AUTO — snapshot dos tipos + helpers
  *   ├── core/skill/*.md     AUTO — docs do skill (com {{projectName}} resolvido)
+ *   ├── core/grammars/*.wasm AUTO — runtime + grammars do AST
  *   ├── watchdogs/*.ts      USUÁRIO
  *   ├── doc-mappings.ts     USUÁRIO
  *   └── exclusions.ts       USUÁRIO
  */
 
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import {
+	copyFileSync,
+	existsSync,
+	mkdirSync,
+	readdirSync,
+	readFileSync,
+	writeFileSync,
+} from "node:fs";
 import { basename, join } from "node:path";
-import { SKILL_DIR, SKILL_FILE } from "../assets";
+import { GRAMMAR_FILES, grammarPath, SKILL_DIR, SKILL_FILE } from "../assets";
 import { CORE_DIR, CORE_SKILL_DIR, OUTPUT_FORMAT_PATH, PROJECT_DIR } from "../paths";
 
 export type Harness = "agents" | "claude";
@@ -123,11 +131,21 @@ 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. */
 export type ClassifyRule = {
-	type?: "filename" | "content";
+	type?: "filename" | "content" | "symbol" | "import" | "export" | "decorator";
 	value: string;
 };
 
@@ -144,6 +162,10 @@ export type WatchdogDefinition = WatchdogMeta & {
 	id: string;
 	description: string;
 	breakingChange?: boolean;
+	/** Só assume arquivos que nenhum outro watchdog casou. */
+	fallback?: boolean;
+	/** Permite findings emergentes (Lógica:/Domínio:) fora das regras. */
+	allowEmergentFindings?: boolean;
 	reviewFocus?: readonly string[];
 	exclude?: readonly string[];
 };
@@ -182,6 +204,54 @@ export type HoundsmanStorage = {
 	path?: string;
 };
 
+/** Linguagens suportadas pelo AST na primeira fase. */
+export type AstLanguage = "typescript" | "tsx" | "javascript";
+
+/** Configuração do AST determinístico (classificação estrutural, brief e impacto). */
+export type HoundsmanAst = {
+	enabled?: boolean;
+	maxFileBytes?: number;
+	maxImpactFiles?: number;
+	languages?: Record<string, AstLanguage>;
+	aliases?: Record<string, string>;
+};
+
+/** Providers suportados pela camada de IA. */
+export type AiProviderKind = "deepseek" | "openai" | "anthropic";
+
+/** Features de IA do fluxo normal (todas fail-open). */
+export type HoundsmanAiFeatures = {
+	context?: boolean;
+	brief?: boolean;
+	classification?: boolean;
+	preAnalysis?: boolean;
+	verify?: boolean;
+};
+
+/** 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). */
+export type HoundsmanAi = {
+	enabled?: boolean;
+	provider?: AiProviderKind;
+	model?: string;
+	baseURL?: string;
+	concurrency?: number;
+	maxSteps?: number;
+	maxOutputTokens?: number;
+	temperature?: number;
+	timeoutMs?: number;
+	maxCallsPerReview?: number;
+	maxTokensPerReview?: number;
+	features?: HoundsmanAiFeatures;
+	watchdogs?: Record<string, HoundsmanAiWatchdog>;
+};
+
 /** Contrato de configuração do motor. */
 export type HoundsmanConfig<TId extends string = string> = {
 	projectName: string;
@@ -193,6 +263,8 @@ export type HoundsmanConfig<TId extends string = string> = {
 	alwaysIncludeDocs?: readonly string[];
 	budgets?: HoundsmanBudgets;
 	concurrency?: HoundsmanConcurrency;
+	ast?: HoundsmanAst;
+	ai?: HoundsmanAi;
 };
 
 /** Helper de autoria (identidade) — apenas tipagem. */
@@ -212,7 +284,8 @@ const WATCHDOG_EXAMPLE = `import { defineWatchdog } from "../core/types";
 
 /**
  * Watchdog de exemplo — substitua pelas regras reais do projeto.
- * Um watchdog declara seus arquivos via \`classify\` (regex de path ou conteúdo).
+ * Um watchdog declara seus arquivos via \`classify\` (regex de path, conteúdo ou
+ * fatos AST: \`symbol\`/\`import\`/\`export\`/\`decorator\`).
  * O texto de cada regra começa com a polaridade: \`Promover:\` (DEVE acontecer)
  * ou \`Evitar:\`/\`Não\`/\`Nunca\` (NÃO DEVE acontecer).
  */
@@ -220,8 +293,8 @@ export const exampleWatchdog = defineWatchdog({
 	id: "example",
 	name: "Exemplo",
 	description: "Watchdog de exemplo — descreva o propósito em uma frase.",
-	scope: "Todo o repositório (ajuste o escopo)",
-	classify: [{ value: "^src/" }],
+	scope: "src/example/** (ajuste o escopo)",
+	classify: [{ value: "^src/example/" }],
 	rules: [
 		{
 			severity: "attention",
@@ -237,13 +310,65 @@ export const exampleWatchdog = defineWatchdog({
 });
 `;
 
-const WATCHDOGS_INDEX = `import { exampleWatchdog } from "./example";
+const DEFAULT_WATCHDOG = `import { defineWatchdog } from "../core/types";
+
+/**
+ * Watchdog de padrões gerais e lógica (fallback).
+ *
+ * Só assume arquivos que nenhum outro watchdog casou. Cobre consistência
+ * lógica, invariantes de domínio e defeitos genéricos que não pertencem a um
+ * domínio específico. Findings fora das regras abaixo podem ser reportados com
+ * os prefixos reservados "Lógica:" e "Domínio:" (opt-in abaixo).
+ */
+export const defaultWatchdog = defineWatchdog({
+	id: "default",
+	name: "Padrões gerais e lógica",
+	description:
+		"Cobre arquivos sem domínio específico: consistência lógica, domínio e defeitos genéricos.",
+	scope: "Arquivos não classificados por outros watchdogs",
+	fallback: true,
+	allowEmergentFindings: true,
+	rules: [
+		{
+			severity: "attention",
+			text: "Promover: nome, contrato e documentação do símbolo correspondem ao comportamento real.",
+			hints: { checks: ["symbol_context"] },
+		},
+		{
+			severity: "attention",
+			text: "Evitar: engolir erros/exceções sem propagar, logar ou tratar.",
+		},
+		{
+			severity: "attention",
+			text: "Promover: transições de estado e efeitos colaterais do domínio são explícitos, ordenados e idempotentes.",
+		},
+		{
+			severity: "suggestion",
+			text: "Evitar: lógica de negócio duplicada ou divergente entre camadas.",
+			hints: { checks: ["find_references"] },
+		},
+		{
+			severity: "suggestion",
+			text: "Promover: casos de borda do domínio (vazio, zero, negativo, timezone, arredondamento) são tratados.",
+		},
+		{
+			severity: "suggestion",
+			text: "Promover: a lógica do domínio respeita as invariantes e contratos documentados.",
+		},
+	],
+	contextFiles: ["AGENTS.md"],
+});
+`;
+
+const WATCHDOGS_INDEX = `import { defaultWatchdog } from "./default";
+import { exampleWatchdog } from "./example";
 
 /**
  * Definições dos watchdogs — as chaves definem o union \`WatchdogId\`.
  * Adicionar um watchdog = criar \`<id>.ts\` e registrá-lo aqui.
  */
 export const WATCHDOG_DEFINITIONS = {
+	default: defaultWatchdog,
 	example: exampleWatchdog,
 };
 
@@ -267,9 +392,10 @@ export function isExcluded(filePath: string): boolean {
 const DOC_MAPPINGS_TEMPLATE = `/**
  * Mapeamento de padrões nos paths → documentação relevante.
  * Consumido pelo motor via \`HoundsmanConfig.docMappings\`.
- */\`core/\` é regenerado por \`houndsman update\`.
-# Runs, findings e artefatos vivem no storage global (fora do projeto).
-core
+ *
+ * Exemplo: [/^src\\//, ["README.md"]]
+ */
+export const DOC_MAPPINGS: readonly (readonly [RegExp, readonly string[]])[] = [];
 `;
 
 const PROJECT_GITIGNORE = `# Diretórios gerados pelo houndsman — \`core/\` é regenerado por \`houndsman update\`
@@ -307,6 +433,14 @@ class WatchdogExampleTemplate implements ScaffoldTemplate {
 	}
 }
 
+class DefaultWatchdogTemplate implements ScaffoldTemplate {
+	readonly path = join(PROJECT_DIR, "watchdogs", "default.ts");
+
+	render(): string {
+		return DEFAULT_WATCHDOG;
+	}
+}
+
 class WatchdogsIndexTemplate implements ScaffoldTemplate {
 	readonly path = join(PROJECT_DIR, "watchdogs", "index.ts");
 
@@ -402,6 +536,7 @@ export class ProjectScaffolder {
 		const context = this.context();
 		const templates: ScaffoldTemplate[] = [
 			new ConfigTemplate(),
+			new DefaultWatchdogTemplate(),
 			new WatchdogExampleTemplate(),
 			new WatchdogsIndexTemplate(),
 			new ExclusionsTemplate(),
@@ -415,6 +550,7 @@ export class ProjectScaffolder {
 		const context = this.context();
 		this.writeGeneratedFile(new TypesTemplate(), context);
 		this.writeGeneratedFile(new GitignoreTemplate(), context);
+		this.syncGrammars();
 
 		// Docs do skill vão para `.houndsman/core/skill/`. O `SKILL.md` é o entry
 		// point dos harnesses, não um doc da camada.
@@ -428,6 +564,19 @@ export class ProjectScaffolder {
 		}
 	}
 
+	/**
+	 * Copia as grammars wasm para a camada. O consumidor não precisa rodar nada:
+	 * `setup` e `update` sincronizam os binários junto dos demais auto-gerados.
+	 */
+	private syncGrammars(): void {
+		const directory = join(this.ctx.cwd, CORE_DIR, "grammars");
+		mkdirSync(directory, { recursive: true });
+		for (const name of GRAMMAR_FILES) {
+			copyFileSync(grammarPath(name), join(directory, name));
+		}
+		this.ctx.generated.push(join(CORE_DIR, "grammars", "*.wasm"));
+	}
+
 	private context(): TemplateContext {
 		return { projectName: this.ctx.projectName };
 	}