@seedgrid/ai-toolkit 0.3.3 → 0.3.4

package/README.md

@@ -23,7 +23,7 @@ Cada pasta de `.ai/` (`rules`, `agents`, `skills`, `templates`, `references`) te
 | Destino | Conteúdo |
 | --- | --- |
 | `.ai/agents/` | Papéis (`arquiteto`, `backend-java`, `backend-rust`, `frontend-react`, `qa`, `revisor`) e `index.md` gerado |
-| `.ai/rules/` | Coordenação, formato de entrega, personalização local e os **padrões SeedGrid obrigatórios** (`frontend-seedgrid`, `backend-java-seedgrid`) |
+| `.ai/rules/` | Coordenação, formato de entrega, personalização local e os **padrões SeedGrid obrigatórios** (`frontend-seedgrid`, `backend-seedgrid`, `backend-java-seedgrid`) |
 | `.ai/templates/` | Especificação de tarefa, decisão de arquitetura, relatório de validação |
 | `.ai/references/` | Modos shared/native e glossário |
 | `.ai/skills/index.md` | Índice gerado das skills (o que faz e quando usar) |
@@ -101,7 +101,7 @@ seedgrid-ai review back --tool codex             # só o back-end, usando o Code
 
 ### `seedgrid-ai review`
 
-Executa a skill `sg-review` na ferramenta de IA instalada, em modo não interativo e somente leitura (Claude Code: `claude -p` com ferramentas de leitura; Codex: `codex exec --sandbox read-only`). A skill confere o código contra as regras `FE-nn` e `BE-nn` (`.ai/rules/frontend-seedgrid.md` e `backend-java-seedgrid.md`) e o CLI mostra o relatório e devolve o código de saída.
+Executa a skill `sg-review` na ferramenta de IA instalada, em modo não interativo e somente leitura (Claude Code: `claude -p` com ferramentas de leitura; Codex: `codex exec --sandbox read-only`). A skill confere o código contra as regras `FE-nn` e `BE-nn` (`.ai/rules/frontend-seedgrid.md`, `backend-seedgrid.md` e `backend-java-seedgrid.md`) e o CLI mostra o relatório e devolve o código de saída.
 
 - **Escopo:** `front`, `back` ou nenhum (os dois). Por padrão revisa os arquivos alterados (diff); `--full` revisa o projeto inteiro.
 - **Ferramenta:** `--tool claude|codex`. Sem a opção, usa a primeira disponível nesta ordem: Claude Code, Codex. Considera só os targets instalados no projeto que tenham a skill e o executável no `PATH`. O CLI não detecta em qual ferramenta você está trabalhando.

package/dist/adapters/shared.js

@@ -103,6 +103,7 @@ function brainLines(bundle) {
 }
 const STANDARD_RULES = [
     ['rules/frontend-seedgrid.md', 'front-end'],
+    ['rules/backend-seedgrid.md', 'back-end, comum a todas as linguagens'],
     ['rules/backend-java-seedgrid.md', 'back-end Java'],
 ];
 /** Padrões SeedGrid obrigatórios (front e back), quando o conteúdo os inclui. */

package/docs/formato.md

@@ -57,7 +57,7 @@ Arquivos e pastas que começam com ponto são ignorados.
 ```json
 {
   "schemaVersion": 2,
-  "contentVersion": "0.3.3",
+  "contentVersion": "0.3.4",
   "toolkitBase": "SeedGrid/Toolkit",
   "components": [
     { "id": "agents", "type": "agents", "files": ["agents/arquiteto.md"] },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seedgrid/ai-toolkit",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Instala agentes, skills, regras, templates e referências versionados em projetos locais para Claude Code e Codex.",
   "type": "module",
   "license": "MIT",

package/seedgridKB/SeedGrid/Toolkit/agents/backend-java.md

@@ -24,7 +24,7 @@ Implementar mudanças no backend Java com código coerente com o projeto, testes
 
 ## Responsabilidades
 
-- Seguir `.ai/rules/backend-java-seedgrid.md` (estrutura, injeção por construtor, `BaseEntity`/`publicId`, Flyway, testes).
+- Seguir `.ai/rules/backend-seedgrid.md` (comum: `publicId`, busca por prefixo, testes, guardiões, LGPD, auditoria) e `.ai/rules/backend-java-seedgrid.md` (estrutura, injeção por construtor, `BaseEntity`/Panache, Flyway, DTOs).
 - **Usar as extensions SeedGrid para acelerar**: antes de escrever autenticação, permissões, auditoria, notificação, billing, cache, storage ou criptografia, consulte o índice da KB (`.ai/brain/SeedGrid/Extensions/Indice.md`) e use a extension que já cobre a necessidade, configurada pelas propriedades documentadas. Só escreva código próprio quando nenhuma cobrir, e diga isso na entrega.
 - **LGPD**: dado pessoal (CPF, CNPJ de pessoa física, telefone, e-mail, endereço, data de nascimento) segue o `seedgrid-privacy`: `@EncryptedField` (com `searchField` quando precisar buscar) e mascaramento nas saídas de auditoria, log e API (`@PersonalData`/`@MaskRule`). Cadastro novo usa a skill `sg-crud-back`.
 - **Auditoria**: operações de criação, alteração e exclusão de entidades de negócio usam `@Audit` (extension `audit`).

package/seedgridKB/SeedGrid/Toolkit/agents/backend-rust.md

@@ -28,7 +28,7 @@ Implementar mudanças em backends Rust do ecossistema SeedGrid reaproveitando os
 - **LGPD**: dado pessoal (CPF, telefone, e-mail, endereço) segue o crate `seedgrid-rust-crate-privacy` (`#[derive(PersonalData)]`, criptografia de campo e hash de busca; mascaramento nas saídas de auditoria, log e API). Veja `.ai/brain/SeedGrid/Extensions/privacy/Rust.md`.
 - **Auditoria**: alterações em entidades de negócio passam pelo crate `audit`.
 - Os crates Rust são portes das extensions Java e o Java é a fonte da verdade: quando a nota Rust não cobrir um comportamento, consulte a nota Java e confirme no código antes de assumir equivalência. Não invente propriedades nem valores padrão.
-- As regras de API e de dados que não dependem da linguagem valem aqui: nunca expor o `id` interno (expor `publicId`), migrations versionadas, busca textual por prefixo (`term%`), exceptions/erros tipados e testes de integração com PostgreSQL real. Não há, no toolkit, um conjunto de regras `BE-nn` próprio para Rust; siga o padrão do projeto e informe divergências.
+- As regras de API e de dados que não dependem da linguagem valem aqui: nunca expor o `id` interno (expor `publicId`), migrations versionadas, busca textual por prefixo (`term%`), exceptions/erros tipados e testes de integração com PostgreSQL real. Siga `.ai/rules/backend-seedgrid.md` (regras `BE-nn` comuns a todas as linguagens, incluindo os testes-guardiões `...GuardianTest` do BE-42, que rodam no `cargo test`). Não há, no toolkit, regras próprias para Rust além dessas; siga o padrão do projeto e informe divergências.
 - Tratar erros com tipos próprios (sem `unwrap`/`expect` em caminho de requisição), validar entradas e não registrar dados sensíveis em log.
 - Escrever ou ajustar testes proporcionais à mudança; executar `cargo build`, `cargo test` e `cargo clippy` relevantes e relatar o resultado real.
 

package/seedgridKB/SeedGrid/Toolkit/agents/qa.md

@@ -27,7 +27,7 @@ Provar, com testes escritos e executados, que a mudança atende aos critérios d
 ## Responsabilidades
 
 - Mapear cada critério de aceite para pelo menos uma verificação concreta e automatizada quando possível.
-- **Criar os testes que faltam** nos padrões do projeto: unitários, de integração (no back SeedGrid, com Testcontainers e PostgreSQL; veja `.ai/rules/backend-java-seedgrid.md`) e de regressão. Vários asserts no mesmo teste ficam em `assertAll`.
+- **Criar os testes que faltam** nos padrões do projeto: unitários, de integração (no back SeedGrid, com Testcontainers e PostgreSQL; veja `.ai/rules/backend-seedgrid.md`) e de regressão. Vários asserts no mesmo teste ficam em `assertAll`. Teste-guardião (`...GuardianIT`/`...GuardianTest`, BE-42) nunca é alterado, enfraquecido nem desabilitado para fazer o build passar: se falhar, o defeito está no código de produção; em dúvida, pergunte ao dono.
 - Executar build, lint, testes afetados e a suíte relevante; exercitar o comportamento alterado quando possível.
 - Registrar comandos, resultados e evidências no formato do relatório de validação (`.ai/templates/relatorio-validacao.md`).
 - Diferenciar "passou", "falhou" e "não executado (motivo)". Teste instável é repetido uma vez e relatado, nunca ocultado.

package/seedgridKB/SeedGrid/Toolkit/rules/backend-java-seedgrid.md

@@ -1,13 +1,13 @@
 ---
-description: "Padrões obrigatórios do back-end Java SeedGrid: estrutura de pastas, injeção por construtor, exceptions tipadas, Flyway, JPA puro em libs, BaseEntity/publicId, RestControllerPath, DTOs, testes, uso das extensions SeedGrid, LGPD (privacy) e auditoria. Leia antes de criar ou alterar código Java."
+description: "Padrões obrigatórios do back-end Java SeedGrid (complementam backend-seedgrid.md): estrutura de pastas, injeção por construtor, exceptions tipadas, Flyway, Panache e BaseEntity, RestControllerPath, DTOs, assertAll, LGPD (privacy) e auditoria em Java. Leia antes de criar ou alterar código Java."
 ---
 # Padrões do back-end Java SeedGrid
 
-Regras **obrigatórias** para novos projetos e bibliotecas SeedGrid. Cada regra tem um id (`BE-nn`) para citar em revisões (`sg-review`). Para as extensions existentes (propriedades, enums, exemplos), consulte a KB: comece por `.ai/brain/SeedGrid/Extensions/Indice.md`.
+Regras **obrigatórias** para projetos Java que usam o SeedGrid. Cada regra tem um id (`BE-nn`) para citar em revisões (`sg-review`). Leia junto com `.ai/rules/backend-seedgrid.md`, que traz o que vale em qualquer linguagem (dados, API, testes, guardiões, LGPD, auditoria); os ids são os mesmos, e esta rule acrescenta o **como** em Java. Para as extensions existentes (propriedades, enums, exemplos), consulte a KB: comece por `.ai/brain/SeedGrid/Extensions/Indice.md`.
 
 ## Estrutura e nomes
 
-- **BE-01.** Quando aplicável, use as pastas `configs/`, `controllers/`, `dtos/`, `exceptions/`, `filters/`, `entities/`, `repositories/` (JPA puro), `services/`, `utils/` (com parcimônia) e `spis/`. Não crie pasta sem propósito claro.
+- **BE-01.** Quando aplicável, use as pastas `configs/`, `controllers/`, `dtos/`, `exceptions/`, `filters/`, `entities/`, `repositories/`, `services/`, `utils/` (com parcimônia) e `spis/`. Não crie pasta sem propósito claro.
 - **BE-02.** Toda pasta (pacote) no **plural**.
 - **BE-03.** Resources REST terminam em `Controller`, não `Resource` (`ClienteController`).
 - **BE-04.** Use sempre a biblioteca `seedgrid-commons` nos projetos.
@@ -36,43 +36,31 @@ public record ClienteDTORes(
         String categoriaPublicId, String categoriaDescricao
 ) {}
 ```
-- **BE-06.** Todo SPI criado é indexado com o `jandex-maven-plugin` (goal `jandex`).
 
 ## Injeção e exceptions
 
 - **BE-10.** Injeção **somente por construtor**, dependências `private final`. Nunca `@Inject` em atributo (só é permitido quando houver mais de um construtor).
-- **BE-11.** Exceptions **tipadas** que reflitam o objetivo; nunca lance `RuntimeException` direto. Em libs, o tratamento é por `ExceptionMapper`, filtro ou handler global; para a exception nova, crie uma `ApiExceptionExtension` que devolve `ProblemDetails`.
+- **BE-11.** Exceptions **tipadas** que reflitam o objetivo; nunca lance `RuntimeException` direto.
 
 ## Persistência
 
-- **BE-20.** Flyway, com migrations separadas por projeto: `src/main/resources/db/migration/<project-name>` e `src/test/resources/db/migration/<project-name>`. Em libs, combine o número `Vxxx__` previamente para não colidir com outras libs.
-- **BE-21.** **Proibido Panache em libs** (JPA puro). Em hosts, Panache é livre.
-- **BE-22.** Chave primária no PostgreSQL: `id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY`.
-- **BE-23.** Toda entidade JPA estende uma base de `br.com.seedgrid.commons.persistence` (traz `id`, `publicId`, datas e usuário de criação/alteração): `BaseEntity` (JPA puro, inclui `active`) em **libs**, e `BaseEntityPanache` (estende `PanacheEntityBase`, sem `active`) em **hosts** que usam Panache (BE-21). Os relacionamentos usam o `id`; o `publicId` é só para busca externa.
-- **BE-24.** Índice único para o `publicId`: `CREATE UNIQUE INDEX idx_<table>_public_id ON <table>(public_id);`.
-- **BE-25.** Proibido `UPDATE` em massa por JPQL ou SQL direto: quebra a auditoria (`@PreUpdate`) e ignora regras de negócio.
+- **BE-20.** Flyway, com migrations separadas por projeto: `src/main/resources/db/migration/<project-name>` e `src/test/resources/db/migration/<project-name>`.
+- **BE-21.** Em hosts, Panache é livre e recomendado para os repositórios.
+- **BE-23.** Toda entidade JPA estende uma base de `br.com.seedgrid.commons.persistence` (traz `id`, `publicId`, datas e usuário de criação/alteração): `BaseEntityPanache` (estende `PanacheEntityBase`, sem `active`) em hosts que usam Panache (BE-21), ou `BaseEntity` (JPA puro, inclui `active`) quando o projeto não usa Panache. Os relacionamentos usam o `id`; o `publicId` é só para busca externa.
 
 ## API REST
 
-- **BE-30.** **Nunca** exponha `id`; exponha sempre `publicId`.
 - **BE-31.** Os paths ficam centralizados em uma classe `RestControllerPath` no pacote `controllers` (`final`, construtor privado), usada na API **e** nos testes de integração. Padrão: constante do nome do parâmetro (`PUBLIC_ID_PARAM = "publicId"`), uma seção por recurso com a base (`USERS = "/users"`), os sub-paths (`USERS_BY_PUBLIC_ID = "/{" + PUBLIC_ID_PARAM + "}"`) e os caminhos completos com sufixo `_FULL` (`USERS_BY_PUBLIC_ID_FULL = USERS + USERS_BY_PUBLIC_ID`). O controller usa a base e os sub-paths; o teste usa os `_FULL`.
-- **BE-32.** Filtros de busca textual usam `LIKE` por prefixo (`term + "%"`), nunca `"%" + term + "%"`.
 
 ## Testes
 
-- **BE-40.** Todo projeto tem testes unitários e testes de integração com Testcontainers + PostgreSQL. Código sem teste não é considerado pronto.
 - **BE-41.** Teste com mais de um `assert` agrupa-os com `assertAll`.
 
-## Extensions SeedGrid, LGPD e auditoria
+## LGPD e auditoria em Java
 
-- **BE-60.** Use as extensions SeedGrid antes de escrever código próprio de autenticação/permissões (`security`), auditoria (`audit`), notificação, billing, cache, storage, rate limit etc. Consulte `.ai/brain/SeedGrid/Extensions/Indice.md` e configure pelas propriedades documentadas. Código próprio só quando nenhuma extension cobre, com a justificativa na entrega.
-- **BE-61.** Dado pessoal (CPF, telefone, e-mail, endereço, data de nascimento, nome quando identifica a pessoa) usa o `seedgrid-privacy`: campo `String` com `@Convert(converter = EncryptedFieldAttributeConverter.class)` e `@EncryptedField`, coluna `length = 512`; se a busca por igualdade for necessária, `@EncryptedField(searchField = "<campo>Hash", normalize = ...)` com a coluna irmã `<campo>_hash` (`length = 64`) e a consulta feita pelo hash (`EncryptedFieldSearch#hashForSearch`, com a **mesma** normalização da anotação). Entidade com campo cifrado leva `@EntityListeners(EncryptedFieldListener.class)`.
-- **BE-62.** A cifra de campo é opt-in: o host liga `seedgrid.privacy.encryption.enabled=true` e fornece `seedgrid.privacy.crypto.key` e `seedgrid.privacy.search.key` (Base64, 32 bytes) por segredo/variável de ambiente, nunca em arquivo versionado.
-- **BE-63.** Dado pessoal **não** vai em claro para auditoria, log, exportação ou resposta de erro: use `@PersonalData`/`@MaskRule` (e `remove = true` para senha e segredos).
-- **BE-64.** Criação, alteração e exclusão de entidades de negócio são auditadas com `@Audit` (`entityFqcn`, `operation`, `description`) no método de serviço, dentro de `@Transactional`.
-- **BE-65.** Endpoints protegidos com as anotações de segurança do Quarkus (`@Authenticated`, `@RolesAllowed`, `@PermissionsAllowed`) e permissões registradas conforme a extension `security`; a UI esconder um botão não substitui a checagem no back.
+- **BE-61.** Dado pessoal usa o `seedgrid-privacy`: campo `String` com `@Convert(converter = EncryptedFieldAttributeConverter.class)` e `@EncryptedField`, coluna `length = 512`; se a busca por igualdade for necessária, `@EncryptedField(searchField = "<campo>Hash", normalize = ...)` com a coluna irmã `<campo>_hash` (`length = 64`) e a consulta feita pelo hash (`EncryptedFieldSearch#hashForSearch`, com a **mesma** normalização da anotação). Entidade com campo cifrado leva `@EntityListeners(EncryptedFieldListener.class)`.
+- **BE-62.** O host liga `seedgrid.privacy.encryption.enabled=true` e fornece `seedgrid.privacy.crypto.key` e `seedgrid.privacy.search.key` (Base64, 32 bytes) por segredo/variável de ambiente, nunca em arquivo versionado.
+- **BE-63.** Use `@PersonalData`/`@MaskRule` para mascarar dado pessoal em auditoria, log, exportação e resposta de erro (e `remove = true` para senha e segredos).
+- **BE-64.** Criação, alteração e exclusão de entidades de negócio usam `@Audit` (`entityFqcn`, `operation`, `description`) no método de serviço, dentro de `@Transactional`.
+- **BE-65.** Endpoints protegidos com as anotações de segurança do Quarkus (`@Authenticated`, `@RolesAllowed`, `@PermissionsAllowed`) e permissões registradas conforme a extension `security`.
 - **BE-66.** Cadastros novos seguem a skill `sg-crud-back`.
-
-## Ao terminar
-
-- **BE-50.** Revise se não sobrou nada (classes e arquivos que deveriam ser removidos) e liste os TODO que ficaram no projeto.

package/seedgridKB/SeedGrid/Toolkit/rules/backend-seedgrid.md

@@ -0,0 +1,45 @@
+---
+description: "Padrões obrigatórios de qualquer back-end SeedGrid, em qualquer linguagem: dados e API (publicId, busca por prefixo), erros tipados, testes (Testcontainers, testes-guardiões), uso das extensions/crates, LGPD e auditoria. Leia antes de criar ou alterar código de back-end."
+---
+# Padrões comuns do back-end SeedGrid
+
+Regras **obrigatórias** para quem usa o SeedGrid num back-end, seja qual for a linguagem. Cada regra tem um id (`BE-nn`) para citar em revisões (`sg-review`). Esta rule diz **o quê**; a rule da linguagem diz **como**: em Java, `backend-java-seedgrid.md`. Os ids são os mesmos nas duas: esta traz a regra, e a da linguagem acrescenta o que só vale nela.
+
+Para as extensions (propriedades, enums, exemplos), consulte a KB: comece por `.ai/brain/SeedGrid/Extensions/Indice.md`. A coluna "Rust" do índice indica o crate equivalente.
+
+## Dados
+
+- **BE-22.** Chave primária no PostgreSQL: `id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY`.
+- **BE-24.** Índice único para o `publicId`: `CREATE UNIQUE INDEX idx_<table>_public_id ON <table>(public_id);`.
+- **BE-25.** Proibido `UPDATE` em massa por JPQL ou SQL direto: quebra a auditoria e ignora regras de negócio.
+
+## API
+
+- **BE-30.** **Nunca** exponha `id`; exponha sempre `publicId`.
+- **BE-32.** Filtros de busca textual usam `LIKE` por prefixo (`term + "%"`), nunca `"%" + term + "%"`.
+
+## Erros
+
+- **BE-11.** Exceptions/erros **tipados** que reflitam o objetivo; nunca lance um erro genérico (`RuntimeException` em Java; em Rust, tipos de erro próprios e sem `unwrap`/`expect` em caminho de requisição). Detalhes por linguagem na rule da linguagem.
+
+## Testes
+
+- **BE-40.** Todo projeto tem testes unitários e testes de integração com Testcontainers + PostgreSQL. Código sem teste não é considerado pronto.
+- **BE-42.** **Testes-guardiões** protegem uma invariante crítica de negócio ou segurança cuja violação causa dano irrecuperável (exemplo: toda empresa/tenant mantém ao menos um usuário ativo com a role ADMIN; sem isso o cliente perde o acesso administrativo para sempre). Convenção:
+  - Nome da classe termina em `GuardianIT` (integração, Testcontainers + PostgreSQL) ou `GuardianTest` (unitário), por exemplo `LastAdminGuardianIT`. O sufixo `Guardian` sozinho **não roda**: o surefire/failsafe (Maven) só executa classes que casam o padrão `*Test`/`*IT`. Em outras linguagens, use o nome que o runner do projeto executa e mantenha o `Guardian` no nome.
+  - Comentário/Javadoc no topo da classe com: o que a invariante protege, por que existe, o dano se for quebrada e quais caminhos cobre, mais o aviso: "TESTE-GUARDIÃO: NÃO ALTERAR, ENFRAQUECER, DESABILITAR (@Disabled), REMOVER ASSERTS nem relaxar expectativas sem decisão EXPLÍCITA do dono do projeto."
+  - Cobre **todos** os caminhos que podem violar a invariante (endpoints, services, fluxos de host, desativação por conta etc.), não só o caminho feliz.
+  - Se um guardião falhar, o defeito está no código de produção, não no teste. Nunca ajuste o teste para passar; se parecer que o teste está errado, pare e pergunte ao dono. Alterar um guardião só com autorização explícita do dono, registrada na mensagem do commit.
+
+## Extensions/crates SeedGrid, LGPD e auditoria
+
+- **BE-60.** Use as extensions (Java) ou os crates (Rust) SeedGrid antes de escrever código próprio de autenticação/permissões (`security`), auditoria (`audit`), notificação, billing, cache, storage, rate limit etc. Consulte `.ai/brain/SeedGrid/Extensions/Indice.md` e configure pelas propriedades documentadas. Código próprio só quando nenhum cobre, com a justificativa na entrega.
+- **BE-61.** Dado pessoal (CPF, telefone, e-mail, endereço, data de nascimento, nome quando identifica a pessoa) usa o `privacy` do SeedGrid: cifrado em repouso e, se a busca por igualdade for necessária, consultado por hash. Anotações e colunas na rule da linguagem.
+- **BE-62.** A cifra de campo é opt-in: o projeto liga a cifra e fornece as chaves por segredo/variável de ambiente, nunca em arquivo versionado.
+- **BE-63.** Dado pessoal **não** vai em claro para auditoria, log, exportação ou resposta de erro: use o mascaramento do `privacy` (e remoção total para senha e segredos).
+- **BE-64.** Criação, alteração e exclusão de entidades de negócio são auditadas pela extension/crate `audit`.
+- **BE-65.** Endpoints protegidos pelo mecanismo de segurança da extension `security`; a UI esconder um botão não substitui a checagem no back.
+
+## Ao terminar
+
+- **BE-50.** Revise se não sobrou nada (classes e arquivos que deveriam ser removidos) e liste os TODO que ficaram no projeto.

package/seedgridKB/SeedGrid/Toolkit/skills/sg-crud-back/SKILL.md

@@ -7,15 +7,15 @@ metadata:
 
 # CRUD de back-end SeedGrid
 
-Monta um cadastro completo no padrão `.ai/rules/backend-java-seedgrid.md` (regras `BE-nn`), reaproveitando as extensions SeedGrid. Antes de começar, leia essa rule e, para cada extension usada, só a nota do grupo na KB (`.ai/brain/SeedGrid/Extensions/Indice.md` → `privacy`, `audit`, `commons`, `security`). Não invente propriedades nem anotações: confirme na KB ou no código.
+Monta um cadastro completo nos padrões `.ai/rules/backend-seedgrid.md` e `.ai/rules/backend-java-seedgrid.md` (regras `BE-nn`), reaproveitando as extensions SeedGrid. Antes de começar, leia essa rule e, para cada extension usada, só a nota do grupo na KB (`.ai/brain/SeedGrid/Extensions/Indice.md` → `privacy`, `audit`, `commons`, `security`). Não invente propriedades nem anotações: confirme na KB ou no código.
 
 ## Passos
 
 1. **Levantar.** Entidade, campos, quais são **dados pessoais** (CPF, telefone, e-mail, endereço, nascimento), quais precisam de **busca por igualdade**, permissões e se há relacionamentos. Leia um cadastro existente do projeto e copie as convenções dele. Dúvida de regra de negócio: pergunte.
-2. **Entidade** (`entities/`): estenda a base do `seedgrid-commons` (BE-23). **Host com Panache:** `BaseEntityPanache` (`id`, `publicId`, datas, usuário de criação/alteração; sem `active`). **Lib** (JPA puro, sem Panache, BE-21): `BaseEntity` (as mesmas colunas mais `active`). Se o projeto já tem cadastros, siga a base que eles usam. Relacionamentos usam o `id`; o `publicId` é só para fora (BE-30).
+2. **Entidade** (`entities/`): estenda a base do `seedgrid-commons` (BE-23). **Com Panache** (recomendado em hosts, BE-21): `BaseEntityPanache` (`id`, `publicId`, datas, usuário de criação/alteração; sem `active`). **JPA puro:** `BaseEntity` (as mesmas colunas mais `active`). Se o projeto já tem cadastros, siga a base que eles usam. Relacionamentos usam o `id`; o `publicId` é só para fora (BE-30).
 3. **Campos pessoais** (BE-61): para cada um, `@Convert(converter = EncryptedFieldAttributeConverter.class)` + `@EncryptedField`, coluna `length = 512`. Com busca: `@EncryptedField(searchField = "cpfHash", normalize = SearchNormalization.CANONICAL)` (e-mail: `EMAIL`) e o campo irmão `cpfHash` (`length = 64`). Adicione `@EntityListeners(EncryptedFieldListener.class)` na entidade. Marque os mesmos campos com `@PersonalData` para o mascaramento na auditoria (BE-63).
 4. **Migration Flyway** (BE-20, BE-22, BE-24): tabela com `id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY`, as colunas da base escolhida (`public_id`, `created_at`, `updated_at` como `timestamptz`, `create_user_public_id`, `update_user_public_id`, e `active` só no `BaseEntity`; a lib não traz migrations), colunas cifradas com `VARCHAR(512)` e de hash com `VARCHAR(64)`, e `CREATE UNIQUE INDEX idx_<tabela>_public_id ON <tabela>(public_id)`. A pasta segue `db/migration/<projeto>`.
-5. **Repository** (`repositories/`, JPA puro em libs; Panache só em hosts, BE-21). Busca por campo cifrado usa o hash: `CryptoProvider.getSecureSearch().hashForSearch(valor, <mesma normalização>)`.
+5. **Repository** (`repositories/`; Panache é livre e recomendado em hosts, BE-21). Busca por campo cifrado usa o hash: `CryptoProvider.getSecureSearch().hashForSearch(valor, <mesma normalização>)`.
 6. **Service** (`services/`, injeção por construtor, BE-10): regras de negócio e exceptions tipadas (BE-11). Criar, alterar e excluir com `@Transactional` e `@Audit(entityFqcn = "...", operation = AuditOperationEnum.CREATE|UPDATE|DELETE, description = "...")` (BE-64). Para UPDATE/DELETE, o repository precisa expor `findByIdOptional` (é por ele que o `@Audit` captura o "antes").
 7. **DTOs** (`dtos/`, BE-05): `...DTOReq` só com o necessário e relacionamentos apenas pela chave estrangeira (`cidadePublicId`); `...DTORes` plano, com `publicId` e **sem** `id`, e `publicId`+descrição de cada relacionamento (`cidadePublicId`, `cidadeDescricao`, `paisPublicId`...). Nada de dado pessoal em claro em respostas de erro ou log.
 8. **Controller** (`controllers/`, BE-03, BE-31): primeiro acrescente a seção do recurso em `RestControllerPath` (base, `..._BY_PUBLIC_ID`, `..._FULL`; o controller usa base e sub-paths, o teste usa os `_FULL`); `GET` paginado (`page`, `size`, `sortField`, `sortOrder`, com `LIKE` por prefixo, BE-32), `GET` por `publicId`, `POST`, `PUT`, `DELETE`. Proteja com `@PermissionsAllowed("<ENTIDADE>_READ|CREATE|EDIT|DELETE")` (ou `@RolesAllowed`), conforme a extension `security` (BE-65), e registre as permissões como o projeto faz.

package/seedgridKB/SeedGrid/Toolkit/skills/sg-review/SKILL.md

@@ -12,17 +12,17 @@ Confere o código contra as regras do toolkit e devolve uma lista objetiva de vi
 ## Escopo
 
 - `front`: revisa só o front-end (regras `FE-nn`, arquivo `.ai/rules/frontend-seedgrid.md`).
-- `back`: revisa só o back-end Java (regras `BE-nn`, arquivo `.ai/rules/backend-java-seedgrid.md`).
+- `back`: revisa só o back-end Java (regras `BE-nn`, arquivos `.ai/rules/backend-seedgrid.md` e `.ai/rules/backend-java-seedgrid.md`).
 - Sem argumento: revisa os dois. Se o projeto só tiver um lado (sem `pom.xml`/`*.java` ou sem `package.json`/`*.tsx`), diga isso e revise apenas o que existe.
 
 Alvo: por padrão, os arquivos alterados (`git diff --name-only <base>...HEAD` mais os não commitados). Se o usuário pedir "o projeto inteiro" ou não houver diff, varra `src/` (back) e `app/`, `components/` (front).
 
 ## Passos
 
-1. Leia **apenas** a rule do escopo (`.ai/rules/frontend-seedgrid.md` e/ou `.ai/rules/backend-java-seedgrid.md`). Para dúvida sobre um componente ou extension, abra pelo índice da KB (`.ai/brain/SeedGrid/SeedGrid-components/Indice.md`, `.ai/brain/SeedGrid/Extensions/Indice.md`) e só a nota do grupo; nunca varra `.ai/brain/` inteira.
+1. Leia **apenas** a rule do escopo (`.ai/rules/frontend-seedgrid.md` e/ou `.ai/rules/backend-seedgrid.md` com `.ai/rules/backend-java-seedgrid.md`). Para dúvida sobre um componente ou extension, abra pelo índice da KB (`.ai/brain/SeedGrid/SeedGrid-components/Indice.md`, `.ai/brain/SeedGrid/Extensions/Indice.md`) e só a nota do grupo; nunca varra `.ai/brain/` inteira.
 2. Faça primeiro as buscas mecânicas, sem abrir arquivo por arquivo. Exemplos:
    - Front: `<input`, `<button`, `<select`, `<textarea`, `<table` em `*.tsx`; `window.confirm`, `alert(`; `SgInputText` em campo cujo nome/label indique telefone, whatsapp, cpf, cnpj, e-mail, cep, senha, valor, data (FE-10 a FE-19).
-   - Back: `@Inject` em atributo; `throw new RuntimeException`; `Resource` no nome de classe; `UPDATE ` em JPQL/SQL de código; Panache em módulo de lib; endpoint que devolve `id` em vez de `publicId`; `"%" +` em `LIKE`; pacote no singular.
+   - Back: `@Inject` em atributo; `throw new RuntimeException`; `Resource` no nome de classe; `UPDATE ` em JPQL/SQL de código; endpoint que devolve `id` em vez de `publicId`; `"%" +` em `LIKE`; pacote no singular.
 3. Abra só os arquivos com suspeita e confirme no contexto. Descarte falsos positivos (por exemplo, `<input>` dentro do próprio pacote de componentes, ou comentário que justifica a exceção da FE-01).
 4. Para regras que exigem julgamento (FE-02, BE-05, BE-11, BE-40), reporte só o que você consegue sustentar com o trecho de código. Diga o que **não** conseguiu verificar.
 

package/seedgridKB/manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 2,
-  "contentVersion": "0.3.3",
+  "contentVersion": "0.3.4",
   "toolkitBase": "SeedGrid/Toolkit",
   "components": [
     {
@@ -24,6 +24,7 @@
         "rules/documentos.md",
         "rules/personalizacao-local.md",
         "rules/frontend-seedgrid.md",
+        "rules/backend-seedgrid.md",
         "rules/backend-java-seedgrid.md"
       ]
     },