@tavaressan/vetor 0.1.0

package/templates/skills/spec-validate/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: spec-validate
+description: Valida a qualidade de uma Spec (RF/RNF, Acceptance Criteria, Non-Goals, Edge Cases) contra o Quality Model do Vetor — score 0-100 ponderado por dimensão e Quality Gate (READY/NEEDS_REFINEMENT/INCOMPLETE) — e reporta Strengths/Gaps/Suggestions.
+license: MIT
+compatibility: Claude Code, OpenCode, Codex, Antigravity
+metadata:
+  author: vitortavares
+  version: "1.0.0"
+---
+
+Você é a skill de validação de qualidade de Specs do Vetor (Handoff #203). Sua missão é ler uma
+Spec já persistida em disco, computar seu score contra o Quality Model (5 dimensões ponderadas),
+classificá-la no Quality Gate e reportar o resultado em Strengths/Gaps/Suggestions — nunca decidir
+sozinho se a Spec "está boa o bastante": o Quality Gate é um mecanismo de decisão, quem age sobre o
+resultado (refinar, seguir para implementação) é sempre o usuário ou a skill chamadora.
+
+O Quality Model, o Quality Gate, a estrutura de saída (Score/Status/Strengths/Gaps/Suggestions —
+#220), os dimension checkers heurísticos (#221: Must sem Acceptance Criteria, termos vagos sem
+métrica mensurável, `⚠️ ABERTO` explícito vs. omissão silenciosa, Non-Goals ausente, Edge Cases
+contextuais), o feedback estruturado por gap (`location`/`problem`/`impact`/`suggestedAction`), o
+Quality Report em Markdown persistido separado da Spec e o refinamento iterativo com limite de 3
+ciclos (#222) já estão completos e operacionais. O formato de metadados de rastreabilidade por
+requisito (`id`/`priority`/`status`) e o Decision Log (#223) também estão preparados — ver
+`references/traceability.md` —, mas **sem** integração real com Coordinator/Guardian: essa
+integração é infraestrutura futura, não código funcional desta skill.
+
+---
+
+## Sintaxe
+
+```
+/vetor:spec-validate <path>
+```
+
+- `<path>`: caminho (relativo ao repositório) de uma Spec em markdown já persistida em disco (ex.:
+  `docs/specs/authentication.md`).
+
+Também invocável como etapa interna de `/vetor:spec` (uso futuro, quando #216-#219 estiverem
+mergeados e a skill `spec` passar a chamar esta validação antes de apresentar o rascunho final ao
+usuário) — nesse caso, a mesma CLI abaixo é chamada, só que a partir do fluxo de `/vetor:spec` em
+vez de invocação direta pelo usuário.
+
+---
+
+## Referências
+
+> Paths relativos abaixo resolvem a partir do diretório desta própria skill (informado ao carregar,
+> ex. "Base directory for this skill: ..."), não do `cwd` de execução. Em comandos `bash`/`deno run`,
+> prefixe o path absoluto desse diretório ao caminho relativo antes de executar — defina uma vez:
+> ```bash
+> SKILL_DIR="<path absoluto informado como 'Base directory for this skill' no carregamento>"
+> ```
+> e use `"$SKILL_DIR/../../scripts/..."` em todo comando abaixo, nunca o path relativo isolado.
+
+- `../../scripts/spec-validate.ts` — CLI que expõe o Quality Model e os dimension
+  checkers (`scripts/lib/spec-quality.ts`, `scripts/lib/spec-quality-checkers.ts`,
+  `scripts/lib/spec-parser.ts`). Uma `SKILL.md` é prosa interpretada por um agente — não pode
+  importar módulos TypeScript diretamente (mesmo padrão de `scripts/knowledge-doc.ts` para
+  `skills/spec/SKILL.md`).
+- `templates/spec.md` — esqueleto que os dimension checkers assumem ao fazer o parsing heurístico
+  (headings `## Nome da Seção`, requisitos `### RF-NN - <nome>` / `### RNF-NN - <nome>`).
+- `references/traceability.md` — formato de metadados de
+  requisito (`id`/`priority`/`status`), Decision Log (`DEC-NN`) e os pontos de extensão futuros
+  para Coordinator (RF→Task) e Guardian (Spec Drift) — #223, preparação sem integração real.
+
+---
+
+## Comportamento
+
+### 1 — Rodar o Quality Model
+
+```bash
+deno run -A "$SKILL_DIR/../../scripts/spec-validate.ts" <path> [--config <path-do-config>] [--history <path>]
+```
+
+- `<path>`: obrigatório — path para a Spec em markdown.
+- `--config`: opcional — path para `.claude/vetor/config.json` (default), de onde os thresholds do
+  Quality Gate são lidos (ver passo 3). Path inexistente/config sem a chave usam os thresholds
+  default.
+- `--history`: opcional — sobrescreve onde o histórico de validação é persistido (default:
+  derivado da raiz do repositório git + path da Spec, `<git-toplevel>/.claude/vetor/specs/
+  <slug>.validation.json` — não do cwd do processo, para que duas invocações a partir de
+  subdiretórios diferentes do mesmo checkout encontrem o mesmo histórico). `<slug>` é o path
+  relativo da Spec sem extensão, com `/` virando `-` (`validationPathFor`, spec-quality-
+  persistence.ts) — não só o basename, para que duas Specs de mesmo nome em pastas diferentes não
+  colidam no mesmo histórico (#269). Use `--history` só em cenário de teste/automação; em uso
+  normal, deixe o CLI derivar o path sozinho.
+
+O CLI lê a Spec, faz o parsing heurístico (`spec-parser.ts`), roda os 5 dimension checkers
+(`spec-quality-checkers.ts`) e agrega o resultado no Quality Model (`spec-quality.ts`), imprimindo
+o Quality Report em Markdown na saída padrão (`spec-quality-report.ts`). Se o path não existir ou
+não puder ser lido, o CLI termina com exit code 1 e uma mensagem de erro — repasse-a ao usuário sem
+tentar adivinhar o path correto por conta própria.
+
+### 2 — Quality Model
+
+Score final é `0-100`, soma ponderada de 5 dimensões (`DIMENSION_WEIGHTS` em `spec-quality.ts`,
+#203 §2):
+
+| Dimensão     | Peso |
+| ------------ | ---: |
+| Completeness |   30 |
+| Testability  |   25 |
+| Clarity      |   20 |
+| Scope        |   15 |
+| Edge Cases   |   10 |
+
+Cada dimensão é avaliada por um checker independente que devolve uma fração `0-1` de quanto foi
+satisfeita; o score da dimensão é `fraction × peso`, arredondado. A soma das 5 dimensões nunca
+ultrapassa 100.
+
+### 3 — Quality Gate
+
+Classificação operacional a partir do score (`gateFor` em `spec-quality.ts`, #203 §3):
+
+```text
+80-100 → READY
+60-79  → NEEDS_REFINEMENT
+0-59   → INCOMPLETE
+```
+
+Os thresholds são configuráveis via `.claude/vetor/config.json`:
+
+```json
+{
+  "specValidate": {
+    "thresholds": { "ready": 80, "needsRefinement": 60 }
+  }
+}
+```
+
+Um override parcial (ex.: só `ready`) preserva o default para o campo omitido — nunca assuma que a
+ausência de `specValidate` no config é um erro, é o caso comum (default aplicado silenciosamente).
+
+### 4 — Apresentar o resultado
+
+Reproduza o Quality Report emitido pelo CLI ao usuário — não resuma nem edite os números nem os
+gaps. Cada gap listado já vem estruturado (`location`/`problem`/`impact`/`suggestedAction`, #203
+§9) — nunca substitua esse detalhe por uma frase genérica tipo "a Spec precisa melhorar". O relato
+sempre inclui, no mínimo:
+
+```
+Score: <N>/100
+Status: <READY|NEEDS_REFINEMENT|INCOMPLETE>
+
+## Strengths
+...
+
+## Gaps
+- **<location>**: <problem>
+  - Impact: <impact>
+  - Suggested action: <suggestedAction>
+
+## Suggestions
+...
+```
+
+### 5 — Refinamento iterativo (limite de 3 ciclos)
+
+Quando `Status` for `NEEDS_REFINEMENT` ou `INCOMPLETE`, o ciclo `validate → gaps → refine →
+validate` (#203 §10) pode se repetir **no máximo 3 vezes** (`MAX_REFINEMENT_CYCLES` em
+`spec-quality-report.ts`) além da validação inicial:
+
+1. Rode o passo 1. Se `Status` for `READY`, pare — não há necessidade de refinar.
+2. Caso contrário, aplique **uma** correção objetiva a partir de um `Gap` do relatório (edite a
+   Spec você mesmo ou peça ao usuário, conforme o contexto de quem chamou esta skill).
+3. Rode o passo 1 de novo, **sempre com o mesmo `<path>`** (o CLI deriva o mesmo arquivo de
+   histórico automaticamente a partir do path da Spec — não passe `--history` em uso normal).
+4. O Quality Report da segunda chamada em diante inclui `## Refinement History` com a evolução do
+   score (ex.: `54 → 71 → 84`). Repita os passos 2-3 até `READY` ou até o CLI imprimir a mensagem de
+   limite de ciclos atingido.
+5. Se o CLI sinalizar que o limite foi atingido, **pare** — não invente uma 5ª validação. Informe ao
+   usuário que a Spec precisa de revisão manual; esta skill nunca decide sozinha refinar além do
+   limite.
+
+---
+
+## Restrições
+
+- Nunca decida sozinho que uma Spec `NEEDS_REFINEMENT`/`INCOMPLETE` pode seguir para implementação
+  mesmo assim — o Quality Gate é informativo para quem decide (usuário ou skill chamadora), não uma
+  trava automática nesta versão.
+- Nunca edite a Spec original a partir desta skill fora do ciclo de refinamento explícito do passo
+  5 — validação é somente leitura por padrão; qualquer edição fora desse ciclo é responsabilidade
+  de quem chamou (`/vetor:spec` ou o usuário diretamente).
+- Nunca invente um score, gate ou gap fora do que o CLI (`scripts/spec-validate.ts`) reportou.
+- Nunca substitua o `problem`/`impact`/`suggestedAction` de um gap por uma frase genérica — o
+  Handoff #203 §9 proíbe explicitamente saída tipo "Spec precisa ser melhorada" sem especificar
+  location/problem/impact/ação.
+- Nunca trate a ausência de `specValidate.thresholds` no config como erro — é o caso default,
+  silenciosamente resolvido para `{ ready: 80, needsRefinement: 60 }`.
+- Nunca ultrapasse `MAX_REFINEMENT_CYCLES` (3) ciclos de refinamento automático — ao atingir o
+  limite, pare e escale para revisão manual em vez de insistir em mais uma tentativa.
+- Nunca escreva o Quality Report dentro do arquivo da Spec — ele é sempre persistido separado
+  (`scripts/lib/spec-quality-persistence.ts`), nunca misturado ao conteúdo da Spec.

package/templates/skills/spec-validate/references/traceability.md

@@ -0,0 +1,169 @@
+# Rastreabilidade Spec → Task → Code → Test (#223, preparação)
+
+Este documento descreve o formato e os pontos de extensão preparados por #223 (Handoff #203
+§13-§18). **Nenhuma integração real está implementada aqui** — nem transformação de requirement em
+task pelo Coordinator, nem detecção de Spec Drift pelo Guardian. O que existe é o formato de dados
+e as garantias que essas integrações futuras vão poder assumir, implementadas em
+`scripts/lib/spec-traceability.ts`.
+
+```text
+Spec
+ │
+ ├── RF-01
+ ├── RF-02
+ └── RF-03
+       │
+       ▼
+     Task            (Coordinator — §2, não implementado)
+       │
+       ▼
+      Code
+       │
+       ▼
+      Test
+       │
+       ▼
+   Guardian           (§3, não implementado)
+```
+
+---
+
+## 1. Metadados por requisito
+
+Cada requisito (`RF-NN`/`RNF-NN`, ver `templates/spec.md` e `skills/spec/SKILL.md` §5.2) pode
+carregar metadados de rastreabilidade:
+
+```yaml
+id: RF-01
+priority: must
+status: planned
+```
+
+- `id`: o mesmo identificador estável já usado pelo motor de geração de `/vetor:spec` — nunca é
+  renumerado (ver `skills/spec/SKILL.md` §5.2).
+- `priority`: `must | should | could` (MoSCoW), mesma semântica de `**Priority:**` no template.
+- `status`: um de `planned | confirmed | implemented | verified` (`RequirementStatus` em
+  `scripts/lib/spec-traceability.ts`).
+
+**Garantia central:** o `id` nunca muda através de nenhuma transição de `status`. `RF-01` continua
+`RF-01` depois de implementado e verificado — só o campo `status` evolui.
+`transitionRequirementStatus(metadata, novoStatus)` (spec-traceability.ts) formaliza essa garantia:
+devolve um novo objeto com `status` atualizado e `id`/`priority` preservados, sem mutar o original.
+
+A ordem sugerida de estados (`REQUIREMENT_STATUSES`) é um fluxo recomendado, não uma máquina de
+estados imposta — `transitionRequirementStatus` não valida que a transição segue essa ordem (ex.:
+pular de `planned` direto para `verified`). Impor ou não essa ordem é decisão de quem consumir este
+módulo no futuro (Coordinator, Guardian), não deste módulo em si.
+
+Onde esses metadados vivem fisicamente (frontmatter YAML por requisito, um arquivo `.json` paralelo
+à Spec, ou embutido no Quality Report — ver `skills/shared/references/knowledge-provider-contract.md`
+para o precedente de persistência do Vetor) é uma decisão de implementação para quando a integração
+real (item 2 ou 3) for construída — esta issue não fixa esse formato de armazenamento, só a forma
+(`RequirementMetadata`) e a garantia de estabilidade do `id`.
+
+---
+
+## 2. Ponto de extensão: Coordinator (RF → Task)
+
+Fluxo futuro:
+
+```text
+RF-01
+  ↓
+Task: Implement user registration
+
+RF-02
+  ↓
+Task: Implement email verification
+```
+
+O `issue-coordinator` (`skills/issue-coordinator/SKILL.md`) já despacha issues do GitHub para
+workers isolados; a extensão futura é a **origem** dessas issues poder ser um requisito de Spec
+(`RF-NN`) em vez de uma issue criada manualmente. Para isso, cada task despachada precisaria
+referenciar o `id` do requisito que a originou — por exemplo, um campo `sourceRequirement: RF-01`
+na issue do GitHub ou no corpo da task.
+
+**Não implementado nesta issue** — geraria uma mudança grande no `issue-coordinator` (que hoje só
+conhece issues do GitHub, não requisitos de Spec) fora do escopo de #223. O que fica pronto é a
+garantia de que `RF-01` é um identificador estável o bastante para ser citado por uma task futura
+sem risco de a referência quebrar quando a Spec evoluir (ver item 1).
+
+---
+
+## 3. Ponto de extensão: Guardian (Spec Drift)
+
+Fluxo futuro:
+
+```text
+Spec
+ │
+ ▼
+Implementation
+ │
+ ▼
+Guardian
+ │
+ ├── RF-01 ✅
+ ├── RF-02 ✅
+ ├── RF-03 ⚠️
+ └── RF-04 ❌
+```
+
+O `guardian` (`skills/guardian/SKILL.md`) hoje audita gaps que o pre-commit não cobre (JSON
+inválido, migrations, worktrees órfãos, etc.). A extensão futura é ele também poder avaliar, por
+requisito:
+
+- **requirement sem implementação aparente** (`status: planned`/`confirmed` há muito tempo sem
+  commit relacionado);
+- **código sem requirement correspondente** (mudança de comportamento sem `RF-`/`RNF-` que a
+  explique);
+- **teste ausente** (`status: implemented` sem cobertura de teste correspondente);
+- **Spec Drift**: divergência relevante entre o comportamento especificado e o
+  implementado/documentado. Exemplo:
+
+  ```text
+  Spec:
+  RF-03 → mensagens devem utilizar processamento assíncrono.
+
+  Code:
+  implementação utiliza chamada síncrona.
+
+  Guardian:
+  ⚠️ POSSIBLE SPEC DRIFT
+  ```
+
+**Não implementado nesta issue** — exigiria análise semântica de código (comparar comportamento
+declarado vs. implementado), explicitamente fora do escopo de #223 (Handoff #203 §16-§17: "não
+implementar ainda análise semântica completa do código"). O que fica pronto é o formato de
+metadados (`status`) sobre o qual essa análise futura poderia se apoiar.
+
+---
+
+## 4. Decision Log
+
+Alterações importantes na Spec (decisões arquiteturais, mudanças de escopo) podem ser registradas
+num log minimalista, formato `DEC-NN` (mesma disciplina de IDs estáveis do item 1):
+
+```markdown
+### DEC-01
+
+Date: 2026-09-16
+
+Decision:
+...
+
+Reason:
+...
+
+Impact:
+...
+```
+
+`renderDecisionLogEntry`/`applyDecisionLogEntry` (`scripts/lib/spec-traceability.ts`) formalizam a
+renderização e a regra de que uma nova decisão sempre vai para o **final** do log, nunca substitui
+ou reordena entradas anteriores — mesmo espírito de nunca renumerar `RF-`/`RNF-` existentes.
+
+Quando uma decisão registrada aqui for arquitetural, o fluxo poderá **futuramente** gerar um ADR
+(`skills/architecture-review/`, se existir no projeto) — esta issue não implementa essa
+transformação automática (Handoff #203 §18: "não transformar esta issue em implementação completa
+de ADR").

package/templates/skills/stack-practices/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: stack-practices
+description: Detecta as libs/frameworks estruturais do projeto e grava regras de melhores práticas via Context7 (conhecimento externo, path-scoped, separado das rules factuais do /vetor).
+license: MIT
+compatibility: Claude Code
+metadata:
+  author: vitortavares
+  version: "1.0.0"
+---
+
+Você é a skill de melhores práticas de stack do Vetor. Sua missão é detectar as libs/frameworks
+estruturais do projeto-alvo, consultar o Context7 para cada uma e gravar regras de melhores
+práticas — rotuladas explicitamente como conhecimento externo, nunca misturadas às rules factuais
+que o `/vetor` já gera.
+
+---
+
+## Sintaxe
+
+```
+/vetor:stack-practices [--refresh]
+```
+
+- sem flag: só gera regras para libs que ainda não têm arquivo em
+  `.claude/rules/vetor/best-practices/`.
+- `--refresh`: força reconsulta ao Context7 e sobrescreve as regras já existentes — melhores
+  práticas envelhecem com o tempo, diferente das rules factuais de `/vetor` (que só mudam quando o
+  repo muda).
+
+---
+
+## Referências
+
+> Paths relativos abaixo resolvem a partir do diretório desta própria skill (informado ao carregar,
+> ex. "Base directory for this skill: ..."), não do `cwd` de execução. Em comandos `bash`/`deno run`,
+> prefixe o path absoluto desse diretório ao caminho relativo antes de executar — defina uma vez:
+> ```bash
+> SKILL_DIR="<path absoluto informado como 'Base directory for this skill' no carregamento>"
+> ```
+> e use `"$SKILL_DIR/../../scripts/..."` em todo comando abaixo, nunca o path relativo isolado.
+
+- `../shared/references/mcp-availability.md` — mecanismo de checagem de
+  disponibilidade do Context7 ("Documentação de ferramentas/libs (Context7)"). Esta skill é uma das
+  que tornam o Context7 **obrigatório quando disponível** — nunca usa conhecimento pré-treinado do
+  agente como fonte de melhor prática, com ou sem o MCP.
+
+---
+
+## Comportamento
+
+### 1 — Detectar libs/frameworks estruturais
+
+```bash
+deno run -A "$SKILL_DIR/../../scripts/lib/deps.ts" .
+```
+
+(ou, dentro de outra skill/script Deno, importe `detectStructuralDeps` de
+`scripts/lib/deps.ts`). O detector cruza `package.json`, `deno.json`/`deno.jsonc`,
+`pyproject.toml` e `Cargo.toml` e devolve só o punhado de dependências diretas *estruturais* —
+frameworks web, ORMs, a lib de UI principal — nunca toda dependência declarada nem dependências
+transitivas. Uma rule por utilitário/dependência transitiva infla o contexto sem ganho; o escopo
+é deliberadamente restrito ao mesmo allowlist do detector.
+
+Sem `--refresh`, filtre a lista às libs que ainda **não** têm arquivo em
+`.claude/rules/vetor/best-practices/<lib>.md`. Com `--refresh`, mantenha a lista inteira.
+
+Se a lista resultante estiver vazia (nenhuma lib estrutural detectada, ou todas já têm regra e não
+foi passado `--refresh`), reporte e pare — nada a fazer.
+
+### 2 — Checar disponibilidade do Context7
+
+Siga o mecanismo de `mcp-availability.md`: procure por qualquer ferramenta com prefixo
+`mcp__context7__` (direta ou diferida via `ToolSearch`).
+
+**Se não disponível:** não gere nenhuma regra para as libs afetadas. Reporte a limitação no
+resultado final ("Context7 indisponível — nenhuma regra de melhores práticas gerada para: <libs>")
+e pare. **Nunca** escreva melhor prática com base no conhecimento pré-treinado do agente como
+fallback — o risco de estar desatualizado para a versão exata em uso é exatamente o que esta skill
+existe para evitar.
+
+### 3 — Consultar o Context7 por lib
+
+Para cada lib da lista do passo 1:
+
+1. `mcp__context7__resolve-library-id` para achar o library ID a partir do nome (e, se disponível
+   na resposta, restrinja pela versão detectada no passo 1).
+2. `mcp__context7__query-docs` com uma pergunta específica e escopada, no estilo "práticas atuais
+   recomendadas e APIs deprecated para `<lib>` versão `<versão>`" — nunca uma pergunta genérica que
+   force o Context7 a devolver um resumo raso.
+
+Se a resolução ou a query falharem para uma lib específica (lib não indexada, erro transiente),
+**pule só aquela lib** — reporte a falha no resultado e continue com as demais. Uma lib com erro
+nunca bloqueia a geração das regras das outras.
+
+### 4 — Gravar a regra
+
+Para cada lib com resposta do Context7, escreva `.claude/rules/vetor/best-practices/<lib>.md`:
+
+```markdown
+---
+paths:
+  - "<globs relevantes à lib, ex. '**/*.tsx' para uma lib de UI React>"
+---
+
+> Gerado por `/vetor:stack-practices` a partir da documentação de <lib>@<versão> via Context7 em <data ISO>.
+> Conhecimento externo, não um fato observado neste repositório — pode ficar desatualizado.
+> Rode `/vetor:stack-practices --refresh` periodicamente. Editável — não sobrescrito sem `--refresh`.
+
+# Melhores práticas — <lib>@<versão>
+
+- <bullet curto e citável, só o que o Context7 retornou como prática atual documentada>
+- <...>
+```
+
+Regras:
+- Cabeçalho de proveniência (as 3 linhas `>`) é obrigatório e distinto do `ORIGIN` usado pelas
+  rules factuais de `scripts/lib/rules.ts` — nunca escreva regra de melhor prática no mesmo arquivo
+  `.claude/rules/vetor/<runtime>.md` gerado pelo `/vetor`, cuja regra de ouro é "só fato observado
+  localmente". `.claude/rules/vetor/best-practices/` é um diretório à parte.
+- `<data ISO>` é a data da consulta, não uma data fixa — usada depois pelo guardian para medir
+  staleness (passo 5).
+- Bullets refletem só o que a fonte (Context7) disse — nunca elaboração ou inferência do agente
+  além do que a resposta retornou.
+- Sem `--refresh`, nunca sobrescreva um arquivo já existente para a mesma lib.
+
+### 5 — Sinalizar staleness no guardian (referência cruzada)
+
+Esta skill não roda o guardian. A auditoria de staleness (regra de melhor prática com mais de 90
+dias desde a última consulta) já está documentada em `skills/guardian/SKILL.md` — nenhuma ação
+extra aqui, além de manter a data no cabeçalho (passo 4) precisa e atualizada a cada
+`--refresh`, já que é o dado que o guardian lê.
+
+### 6 — Reportar
+
+Ao final, resuma:
+- Libs detectadas no passo 1 e quais já tinham regra (puladas, sem `--refresh`).
+- Libs com regra gerada/atualizada nesta execução, com a versão consultada.
+- Libs puladas por falha de resolução/query no Context7 (passo 3).
+- Se o Context7 não estava disponível: a lista completa de libs sem regra por esse motivo (passo 2).
+
+---
+
+## Restrições
+
+- Nunca gera regra de melhor prática sem o Context7 disponível — sem exceção, sem fallback de
+  conhecimento pré-treinado.
+- Nunca escreve em `.claude/rules/vetor/<runtime>.md` (rules factuais do `/vetor`) — só em
+  `.claude/rules/vetor/best-practices/`.
+- Nunca gera regra para dependência transitiva ou utilitária fora do allowlist estrutural do
+  detector (`scripts/lib/deps.ts`).
+- Sem `--refresh`, nunca sobrescreve uma regra já existente.