@payconductor/houndsman 0.1.3 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@payconductor/houndsman",
-	"version": "0.1.3",
+	"version": "0.1.4",
 	"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/core/registry-check.ts

@@ -127,6 +127,57 @@ function checkRulePolarity(config: HoundsmanConfig, warnings: string[]): void {
 	}
 }
 
+/** Normaliza o texto da regra para detectar duplicatas (case/espaços). */
+function normalizeRuleText(text: string): string {
+	return text.trim().toLowerCase().replace(/\s+/g, " ");
+}
+
+/**
+ * Aviso para regra repetida (texto normalizado) no mesmo watchdog — a regra deve
+ * existir uma única vez em `rules` (§ Convenções de escrita, item 10).
+ */
+function checkRuleDuplication(config: HoundsmanConfig, warnings: string[]): void {
+	for (const id of config.watchdogIds) {
+		const def = config.watchdogs[id];
+		if (!def) continue;
+		const seen = new Set<string>();
+		def.rules.forEach((rule, index) => {
+			const key = normalizeRuleText(rule.text);
+			if (!key) return;
+			if (seen.has(key)) {
+				warnings.push(`Regra duplicada em ${id} (rule-${index}): ${rule.text}`);
+				return;
+			}
+			seen.add(key);
+		});
+	}
+}
+
+/** Campos de metadados que NÃO devem conter texto de regra. */
+const RULE_BEARING_FIELDS = ["reviewFocus", "contextFiles", "exclude"] as const;
+
+/**
+ * Aviso quando `reviewFocus`/`contextFiles`/`exclude` recebem texto de regra
+ * (prefixo de polaridade) — a regra vive só em `rules`; duplicá-la nesses campos
+ * deixa o brief do subagente redundante.
+ */
+function checkMetadataPrecision(config: HoundsmanConfig, warnings: string[]): void {
+	for (const id of config.watchdogIds) {
+		const def = config.watchdogs[id];
+		if (!def) continue;
+		for (const field of RULE_BEARING_FIELDS) {
+			const items = def[field];
+			if (!items) continue;
+			items.forEach((item, index) => {
+				if (!POLARITY_PREFIX.test(item.trim())) return;
+				warnings.push(
+					`Texto de regra em ${id}.${field}[${index}] — a regra vive só em 'rules': ${item}`,
+				);
+			});
+		}
+	}
+}
+
 /** Aviso para orçamento/concorrência inválidos — o motor cai no default. */
 function checkBudgets(config: HoundsmanConfig, warnings: string[]): void {
 	const maxFiles = config.budgets?.maxFilesPerBrief;
@@ -153,6 +204,8 @@ export function checkRegistry(config: HoundsmanConfig): {
 	checkClassification(config, problems);
 	checkRendering(config, problems);
 	checkRulePolarity(config, warnings);
+	checkRuleDuplication(config, warnings);
+	checkMetadataPrecision(config, warnings);
 	checkBudgets(config, warnings);
 	const jevQuestions = checkJevSpecs(config, problems);
 

package/src/skill/AUDIT-PROTOCOL.md

@@ -11,6 +11,10 @@ aplicadas em nenhuma parte do código) devem ser **removidas**, não apenas reba
 1. `.houndsman/watchdogs/<id>.ts` — `WATCHDOG_DEFINITIONS[<id>]` é a fonte única de verdade:
    `description`, `scope`, `rules` (severidade + texto), `classify`, `contextFiles`,
    `reviewFocus`, `exclude`.
+
+   > **Onde cada coisa vive:** a **regra** vive só em `rules`; `reviewFocus` = paths a priorizar;
+   > `contextFiles` = docs a consultar; `exclude` = paths a ignorar; `scope`/`description` = prosa.
+   > Texto de regra em `reviewFocus`/`contextFiles`/`exclude` é **duplicação** a corrigir.
 2. `src/core/brief.ts` (no motor) — `PROCEDURE` (passos de revisão compartilhados).
 3. Ground truth (padrões reais do projeto):
    - Documentos de convenção do projeto (ex.: `AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`).
@@ -41,6 +45,7 @@ classifique sem evidência (caminho de arquivo, linha, ou "0 ocorrências via gr
 | `OUTDATED` | Já foi aplicado, mas o código mudou | Remover ou reescrever |
 | `MISCALIBRATED` | Regra válida, mas severidade errada | Ajustar severidade |
 | `DEAD-PATH` | `scope`/`contextFiles`/`classify` apontam para caminho/arquivo inexistente | Corrigir ou remover |
+| `REDUNDANT` | Regra duplicada no mesmo watchdog ou repetida em `reviewFocus`/`contextFiles`/`exclude` | Remover a cópia (a regra fica só em `rules`) |
 
 ## Formato do relatório
 

package/src/skill/README.md

@@ -52,7 +52,7 @@ Um único skill (`/houndsman`), quatro capabilities (detalhadas em `hunt.md`, `t
 | `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 (anti-drift) |
-| `houndsman test` | Roda a suíte de testes da lib |
+| `houndsman test` | **Manutenção da lib** — roda a suíte de testes do pacote (não é uso do consumidor) |
 
 ### Flags
 
@@ -138,6 +138,8 @@ houndsman.config.ts           # HoundsmanConfig (dados; descoberto em runtime)
 > prove que o padrão existe no código (regra negativa: prove que o anti-padrão **não** existe).
 > Regras devem ser **gerais/reutilizáveis** no domínio e declarar a **polaridade** no texto
 > (`Promover:` = deve acontecer; `Evitar:`/`Não`/`Nunca` = não deve acontecer).
+> Cada regra vive **só** em `rules` — não a repita em `reviewFocus`/`contextFiles`/`scope`/
+> `description`/`exclude` (isso só duplicaria o brief).
 
 1. Novas regras/watchdogs → editar `.houndsman/watchdogs/<id>.ts` (regras + escopo +
    `classify`) ou `doc-mappings.ts`/`exclusions.ts`. Um watchdog novo exige só o módulo em

package/src/skill/SETUP.md

@@ -60,7 +60,6 @@ bun run houndsman update      # reescreve .houndsman/core/** e .houndsman/.gitig
 
 ```bash
 bun run houndsman doctor         # valida config + ambiente + credencial Jev
-bun run houndsman test           # suíte da lib (project-agnóstica)
 bun run houndsman --base main    # prepara briefs do diff atual
 ```
 

package/src/skill/hunt.md

@@ -271,7 +271,8 @@ completo) · `--no-jev` · `--fail-on-blocking` (com `--finalize`).
 > **`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`.
+> Após qualquer alteração, rodar `houndsman doctor`. (`houndsman test` e `ci:fix`/`ci` são
+> comandos da **lib**, não do projeto consumidor.)
 
 ---
 

package/src/skill/train.md

@@ -72,10 +72,29 @@ Toda regra (nova ou alterada) deve passar por **todos** os itens:
      direta da afirmação). Aí o prefixo lidera o sentido dominante e o outro entra como oração
      subordinada — nunca como segundo juízo coordenado.
 9. **Escopo coerente** — a regra pertence ao domínio do watchdog.
-10. **Sem duplicata** — nenhuma regra repetida literalmente no mesmo watchdog.
+10. **Sem duplicata** — nenhuma regra repetida (texto normalizado) no mesmo watchdog.
+11. **Lugar único** — a regra vive **apenas** em `rules`. Nunca repita o texto (nem o anti-padrão)
+    em `reviewFocus`, `contextFiles`, `scope`, `description` ou `exclude`.
 
 > O `houndsman doctor` emite um **aviso** (não bloqueante) para regra sem polaridade explícita
-> (`Promover:`, `Evitar:`, `Não` ou `Nunca`).
+> (`Promover:`, `Evitar:`, `Não` ou `Nunca`), para regra duplicada e para texto de regra que
+> vazou para `reviewFocus`/`contextFiles`/`exclude`.
+
+### Onde cada coisa vive (não duplique a regra)
+
+Cada informação tem o seu campo — não espelhe a regra em vários lugares:
+
+| O que você quer expressar | Campo | Observação |
+|---|---|---|
+| A **regra** (o que DEVE/NÃO DEVE acontecer) | `rules[]` | Único lugar da regra: `{ severity, text, jev? }`. |
+| **Quais arquivos** o watchdog cobre | `classify` | Regex de path (ou de conteúdo). |
+| **Que arquivos** olhar primeiro | `reviewFocus` | **Paths/áreas** do código — não texto de regra. |
+| **Que docs** consultar | `contextFiles` | Caminhos de **documentação** — não regra nem código. |
+| O que **nunca** carregar | `exclude` | Paths a ignorar. |
+| O **território** em prosa | `scope` / `description` | Contexto do domínio, não regra. |
+
+> A regra aparece **uma única vez** no arquivo — em `rules`. Repeti-la em
+> `reviewFocus`/`contextFiles`/`scope`/`description`/`exclude` só cria ruído no brief do subagente.
 
 ---
 
@@ -166,7 +185,9 @@ verificáveis por leitura local. Candidatos não confirmados pelo watchdog **nã
      `Evitar:`/`Não`/`Nunca` (NÃO DEVE), conforme as Convenções de escrita.
    - Regra que mistura afirmação e negação (dois sentidos) → dividir em **duas entradas** (*Unipolar*, item 8).
    - `jev` (opcional): `{ kind: "noul" }`, com `instructions` e/ou `criteria` — ver seção acima.
-   - Ajustar `scope` / `description` / `reviewFocus` / `exclude` / `contextFiles` se necessário.
+   - **A regra vai só em `rules`** — não a repita em `reviewFocus`/`contextFiles`/`scope`/
+     `description`/`exclude`. Só toque nesses campos se o **domínio/paths** mudou (ver
+     *Onde cada coisa vive*), nunca para reafirmar a regra.
    - 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/hunt.md`/`README.md`** se escopo/regra visível mudou (no motor).
@@ -226,16 +247,14 @@ todos os itens — em especial: **geral/reutilizável** (não regra de negócio
 
 ```bash
 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                   # tipagem (no repo da lib)
 ```
 
+> `bun run houndsman test`, `bun run ci:fix` e `bun run ci` são comandos para **manter a lib** do
+> houndsman (repo do pacote) — não para quem só usa o houndsman no projeto.
+
 Checklist final:
 
 - [ ] `bun run houndsman doctor` → sem problemas reportados.
-- [ ] `bun run houndsman test` → **0 fail**.
-- [ ] `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/hunt.md` continua consistente com os watchdogs do projeto.
 - [ ] Toda regra nova/alterada tem **evidência** registrada no PR/relatório
@@ -244,6 +263,8 @@ Checklist final:
 - [ ] Brief de amostra não contém regra removida (dry-run abaixo).
 - [ ] Toda regra passa nas convenções de escrita (geral/reutilizável, sem jargão abreviado,
       sem qualificador vago, com polaridade explícita e **unipolar**) — conferir via grep.
+- [ ] O texto de cada regra aparece **exatamente uma vez** no arquivo (só em `rules`) — nada em
+      `reviewFocus`/`contextFiles`/`scope`/`description`/`exclude`.
 
 ```bash
 # Dry-run: gerar briefs e conferir ausência de regras removidas

package/src/tests/review-scripts.test.ts

@@ -139,6 +139,42 @@ describe("registry-check", () => {
 		const { warnings } = checkRegistry(config as typeof fakeHoundsmanConfig);
 		expect(warnings).toEqual([]);
 	});
+
+	test("regra duplicada no mesmo watchdog gera aviso", () => {
+		const config = {
+			...fakeHoundsmanConfig,
+			watchdogs: {
+				...fakeHoundsmanConfig.watchdogs,
+				alpha: {
+					...alphaWatchdog,
+					rules: [
+						{ severity: "attention" as const, text: "Evitar console.log." },
+						{ severity: "blocking" as const, text: "Evitar   console.log." },
+					],
+				},
+			},
+		};
+		const { warnings } = checkRegistry(config as typeof fakeHoundsmanConfig);
+		expect(warnings.some((w) => w.includes("duplicada"))).toBe(true);
+	});
+
+	test("texto de regra em reviewFocus/contextFiles gera aviso", () => {
+		const config = {
+			...fakeHoundsmanConfig,
+			watchdogs: {
+				...fakeHoundsmanConfig.watchdogs,
+				alpha: {
+					...alphaWatchdog,
+					reviewFocus: ["Evitar: console.log."],
+					contextFiles: ["Promover: validar a entrada."],
+				},
+			},
+		};
+		const { warnings } = checkRegistry(config as typeof fakeHoundsmanConfig);
+		expect(
+			warnings.filter((w) => w.includes("a regra vive só em 'rules'")),
+		).toHaveLength(2);
+	});
 });
 
 // ---------------------------------------------------------------------------