@polymorphism-tech/morph-spec 9.3.0 → 9.5.0

package/framework/standards/architecture/engineering-lens.md

@@ -0,0 +1,100 @@
+# Lente de engenharia — código para quem herda amanhã
+
+> **Scope:** universal
+> **Layer:** 0 (resumo injetado pelas rules `csharp-standards` (`**/*.cs`, `**/*.csproj`) e `nextjs-standards` (`**/*.ts`, `**/*.tsx`); texto completo sob demanda via `morph-spec standards --find`)
+> **Keywords:** clean code, código limpo, fragilidade, código morto, excesso, legibilidade, extensibilidade, flag booleana, efeito colateral, conventional commits
+> **Load When:** escrevendo, planejando ou revisando código em qualquer stack
+
+**Verified against:** C#, TypeScript e JavaScript (convenção de linguagem, sem pacote externo); Conventional Commits 1.0.0. Last-verified: 2026-10-18.
+
+---
+
+## Quem herda amanhã
+
+Escreva para quem abre o repo amanhã e precisa entregar uma feature na semana seguinte. A
+convenção que o projeto já usa vence o seu gosto. O mais simples que resolve vence o mais geral.
+Bug se corrige na causa raiz, nunca no sintoma.
+
+## Fragilidade
+
+Código que quebra fácil:
+
+- `catch` vazio, ou que só loga e segue como se nada tivesse acontecido.
+- Null ou ausência vindo de fronteira (HTTP, banco, arquivo, LLM) sem tratamento.
+- Dependência de ordem implícita: método que só funciona se outro rodou antes.
+- Parser estrito diante de dado real (campo opcional tratado como obrigatório, enum fechado para
+  valor externo).
+- Guard cego: a checagem e o dado saem do mesmo serializador, então ela nunca falha.
+- Teste que passa sem provar a regra (ver `backend-dotnet-testing` / `frontend-nextjs-testing`).
+
+## Código morto
+
+Símbolo, endpoint, flag, config ou tabela sem consumidor real sai. Feature começada e largada
+sai. Dois caminhos que fazem a mesma coisa viram um. Quando "X só é usado por Y", pergunte para
+quê Y existe: muitas vezes os dois saem. Código comentado sai, porque o git guarda o antigo.
+
+## Excesso
+
+- Abstração (interface, factory, base class, strategy) sem um segundo uso hoje.
+- Camada que só repassa a chamada.
+- Config ou parâmetro para um caso que ninguém pediu (o "e se um dia eu quiser voar com o carro":
+  construa as asas quando for voar).
+- Stdlib, plataforma ou dependência já instalada reinventada à mão.
+
+No plano, todo CRIAR de abstração diz no `why` o segundo uso ou a próxima adição que ela barateia.
+
+## Legibilidade
+
+- **Nomes:** descritivos, pronunciáveis, buscáveis, na linguagem do domínio. Distinção com
+  significado (`sourceAccount`/`targetAccount`, nunca `account1`/`account2`). Sem prefixo de tipo
+  nem caractere especial. Classe é substantivo, método é verbo, e um padrão aparece no nome
+  (`InvoiceFactory`). Um idioma por identificador.
+- **Funções:** pequenas, com um objetivo só. Poucos parâmetros (passou de 3, agrupe num tipo).
+  Sem efeito colateral fora do próprio objeto que o nome não anuncie.
+- **Sem flag booleana que bifurca o método** — são dois métodos:
+
+```ts
+// ruim
+sendInvoice(invoice, true);
+// bom
+sendInvoiceByEmail(invoice);
+sendInvoiceByWhatsApp(invoice);
+```
+
+- **Condicional positiva:** `if (order.isEmpty)` em vez de `if (!order.hasItems)`; o `!` some na leitura.
+- **Literal repetido vira constante** (detalhe em `architecture-code-comments`).
+- **Estrutura:** por feature/slice (`architecture-vertical-slice-vertical-slice`); variável declarada
+  perto do uso; funções de cima para baixo, a chamadora antes da chamada; funções afins juntas; sem
+  alinhamento horizontal; formatação pelo formatter do projeto.
+- **Comentários:** `architecture-code-comments` é a regra única.
+
+## Extensibilidade
+
+A próxima adição provável (uma skill nova, um campo novo de config refletido na tela, um provider
+novo) deve tocar poucos arquivos e nenhum `switch` espalhado. Se exige editar N lugares que precisam
+concordar, o atrito é o registro que falta, não a falta de uma camada genérica.
+
+## IA e código
+
+Regra que nunca pode ser quebrada fica em código, nunca vira prompt (`ai-agents-guardrails`). O
+inverso também vale: regex, heurística ou árvore de `if` que classifica linguagem natural é candidata
+a structured output, e a troca só entra medida por eval (`ai-agents-evals-with-cache`).
+
+## Git
+
+A branch é `morph/{f}`, criada pelo CLI. Commits seguem Conventional Commits:
+`<tipo>(<escopo>): <assunto>`, com o tipo em `feat`, `fix`, `refactor`, `test`, `chore`, `docs`,
+`perf`, `ci`, `build`, `style` ou `revert`. O hook `conventional-commit` recusa outra forma.
+
+## O que bloqueia no Gate 3
+
+Só o que o **diff introduziu**. O que já existia no arquivo vira nota.
+
+1. `catch` que engole a exceção.
+2. Flag booleana que bifurca o método.
+3. Efeito colateral escondido: o método muda estado alheio e o nome não diz.
+4. Símbolo, flag ou config sem consumidor, ou código comentado.
+5. Abstração ou camada sem segundo uso e sem `why` no plano.
+6. Literal mágico repetido em comparação.
+
+O resto (nome, tamanho, ordem, "eu faria diferente") é nota.

package/framework/standards/architecture/vertical-slice/vertical-slice.md

@@ -380,20 +380,18 @@ app.MapApiEndpoints();
 | Errors class | `{Entity}Errors` | `BookErrors` (static, shared por feature) |
 | DTO record (GetAll) | `{Entity}Dto` | `BookDto` |
 | API tag constant | `ApiTags.{Entities}` | `ApiTags.Books` |
-| Entity class | `{Entity}` (`sealed`) | `Book` |
+| Entity class | `{Entity}` | `Book` |
 
 ---
 
 ## Padrões Obrigatórios
 
 1. **Handler records no mesmo arquivo**: `Request` e `Response` são declarados no mesmo arquivo `.cs` que o `Handler`.
-2. **`sealed` em tudo**: handlers, endpoints, validators, request/response records usam `sealed`.
-3. **`Guid.CreateVersion7()`** para gerar IDs (não `Guid.NewGuid()`).
-4. **`result.Match()`** nos endpoints — o sucesso recebe o valor no lambda (nunca ler `result.Value`) e a falha vira `error.ToHttpResult()` (status pelo `ErrorType`, nunca `Results.BadRequest` para todo erro).
-5. **IApiEndpoint `internal sealed`** — endpoints não são públicos.
-6. **`{Entity}Errors` compartilhado** por todas as operações da feature (1 arquivo por feature, não por slice).
-7. **`ApplicationDbContext` direto no slice**: CRUD por chave via `DbSet<T>`; queries específicas (joins, projeção, paginação) via LINQ no handler. Nunca uma Application Service layer entre handler e dados; nunca repository genérico (`IRepository<T>`/`IUnitOfWork`).
-8. **`SaveChangesAsync()`** explícito em operações de escrita (Create, Update, Delete).
+2. **`result.Match()`** nos endpoints — o sucesso recebe o valor no lambda (nunca ler `result.Value`) e a falha vira `error.ToHttpResult()` (status pelo `ErrorType`, nunca `Results.BadRequest` para todo erro).
+3. **IApiEndpoint `internal`** — endpoints não são públicos.
+4. **`{Entity}Errors` compartilhado** por todas as operações da feature (1 arquivo por feature, não por slice).
+5. **`ApplicationDbContext` direto no slice**: CRUD por chave via `DbSet<T>`; queries específicas (joins, projeção, paginação) via LINQ no handler. Nunca uma Application Service layer entre handler e dados; nunca repository genérico (`IRepository<T>`/`IUnitOfWork`).
+6. **`SaveChangesAsync()`** explícito em operações de escrita (Create, Update, Delete).
 9. **Sem validator em GetAll** — GetAllBooksHandler não tem validator (sem parâmetros para validar).
 
 ---
@@ -402,7 +400,7 @@ app.MapApiEndpoints();
 
 | Anti-pattern | Por quê não |
 |--------------|-------------|
-| `AggregateRoot` | VSA não usa DDD — entidade simples com `sealed class` |
+| `AggregateRoot` | VSA não usa DDD — entidade simples |
 | `DomainEvent` | VSA não tem Domain Events — reações são handlers separados |
 | `MediatR` / `IRequest` / `IRequestHandler` | Substituído por `IHandler<TRequest, TResponse>` próprio |
 | DTOs compartilhados entre features | Cada slice define seus próprios records |

package/framework/standards/backend/dotnet/analyzers.md

@@ -0,0 +1,59 @@
+# Analyzers .NET — o build cobra, a prosa não repete
+
+> **Scope:** dotnet
+> **Layer:** 0 (resumo injetado pela rule `csharp-standards` (`**/*.cs`, `**/*.csproj`); o `stack-scan` acusa o projeto sem estes arquivos)
+> **Keywords:** analyzer, roslyn, BannedApiAnalyzers, BannedSymbols, globalconfig, Guid.NewGuid, CreateVersion7, CancellationToken, CA2016, RS0030
+> **Load When:** projeto .NET sem `BannedSymbols.txt`, ou o build acusou RS0030/CA2016
+
+**Verified against:** .NET SDK 10.0.402, Microsoft.CodeAnalysis.BannedApiAnalyzers 5.6.0 (sonda: `Guid.NewGuid()` → erro RS0030, token não repassado → erro CA2016, código conforme → 0 erros). Last-verified: 2026-10-18.
+
+---
+
+Regra de código que tem motivo e nunca pode ser quebrada vira **erro de build**, não frase que o
+agente relê a cada sessão. Estes três arquivos na raiz da solution bastam; nenhum `.csproj` muda.
+
+## Arquivos
+
+`Directory.Build.props` (se já existe, some o `ItemGroup` ao dele):
+
+```xml
+<Project>
+  <ItemGroup>
+    <PackageReference Include="Microsoft.CodeAnalysis.BannedApiAnalyzers" Version="5.6.0" PrivateAssets="all" />
+    <AdditionalFiles Include="$(MSBuildThisFileDirectory)BannedSymbols.txt" />
+    <GlobalAnalyzerConfigFiles Include="$(MSBuildThisFileDirectory)morph.globalconfig" />
+  </ItemGroup>
+</Project>
+```
+
+Com Central Package Management (`Directory.Packages.props`), a versão vai lá e o
+`PackageReference` fica sem `Version`.
+
+`BannedSymbols.txt`:
+
+```text
+M:System.Guid.NewGuid;Use Guid.CreateVersion7(): ordenado, nao fragmenta o indice da PK
+```
+
+`morph.globalconfig`:
+
+```ini
+is_global = true
+dotnet_diagnostic.RS0030.severity = error
+dotnet_diagnostic.CA2016.severity = error
+```
+
+## O que cada regra compra
+
+| Diagnóstico | Bloqueia | Por quê |
+|---|---|---|
+| RS0030 | `Guid.NewGuid()` | UUID v4 é aleatório: PK nele fragmenta o índice B-tree do Postgres a cada insert; `Guid.CreateVersion7()` é ordenado no tempo |
+| CA2016 | método que recebe `CancellationToken` e não o repassa | requisição cancelada continua segurando conexão do banco e chamada ao LLM |
+
+API nova para banir entra como linha no `BannedSymbols.txt` (formato `M:`/`T:`/`P:` com a
+mensagem depois do `;`), com o porquê na mensagem. Nunca uma regra nova em prosa.
+
+## O que não é regra
+
+`sealed`, primary constructor, `var`, expression-bodied member e ordem de `using` são gosto: nem
+prosa nem analyzer. Siga o arquivo vizinho, e o formatter do projeto decide a forma.

package/framework/standards/backend/dotnet/vsa-handler-patterns.md

@@ -11,7 +11,7 @@
 
 ## Overview
 
-Each feature in VSA is a self-contained slice with 5 files in a feature folder. Handlers implement `IHandler<TRequest, TResponse>` (not MediatR). Dependencies use primary constructors. The data path is `Handler -> ApplicationDbContext` — no service layer, no generic repository in between.
+Each feature in VSA is a self-contained slice with 5 files in a feature folder. Handlers implement `IHandler<TRequest, TResponse>` (not MediatR). The data path is `Handler -> ApplicationDbContext` — no service layer, no generic repository in between.
 
 ---
 
@@ -108,11 +108,8 @@ public sealed class CreateBookHandler(
 
 ### Key Patterns
 
-- **`sealed class`** — handlers are never inherited
-- **`sealed record`** — DTOs are immutable value types
-- **Primary constructors** — `(ApplicationDbContext db)` replaces field + constructor boilerplate
-- **`Guid.CreateVersion7()`** — time-sortable, index-friendly UUID (not `Guid.NewGuid()`)
-- **`CancellationToken`** — passed through every async call
+- **`record`** — DTOs are immutable value types
+- **`Guid.CreateVersion7()` and a forwarded `CancellationToken`** — enforced by the build (`backend-dotnet-analyzers`), not by review
 - **`Result<T>` return** — never throw for expected failures
 
 ---
@@ -149,7 +146,7 @@ internal sealed class CreateBookEndpoint : IApiEndpoint
 
 ### Endpoint Conventions
 
-- **`internal sealed`** — endpoints are not public API
+- **`internal`** — endpoints are not public API
 - **`IApiEndpoint`** — single interface for auto-discovery
 - **Handler injected via DI** — resolved as `IHandler<TReq, TRes>` parameter
 - **`Match()` for responses** — the success lambda receives the value (never read `.Value` directly); the failure lambda is `error.ToHttpResult()` from `Extensions/ErrorHttpMapping.cs` (`backend/dotnet/result-pattern.md`), which maps `ErrorType` to the status — never `Results.BadRequest` for every error
@@ -299,13 +296,9 @@ builder.Services.AddExceptionHandler<CustomExceptionHandler>()
 | Use MediatR `IRequest`/`Send()` | Use `IHandler<TReq, TRes>` resolved directly from DI |
 | Create a service/manager layer | Handler uses `ApplicationDbContext` directly |
 | Add a generic repository (`IRepository<T>`/`IUnitOfWork`) | `DbSet<T>` is the repository; `DbContext` is the unit of work |
-| Use `Guid.NewGuid()` | Use `Guid.CreateVersion7()` for time-sortable IDs |
-| Make handler classes non-sealed | Always `sealed class` |
-| Use mutable DTOs (class with setters) | Always `sealed record` with positional parameters |
-| Omit `CancellationToken` from async methods | Pass `CancellationToken` through every async call |
+| Use mutable DTOs (class with setters) | Always `record` with positional parameters |
 | Put business logic in endpoints | Endpoints only map HTTP and call `Match()` |
 | Share handlers across features | Each feature has its own handler, even if similar |
-| Use constructor + field for DI | Use primary constructors: `class Handler(IDep dep)` |
 | Group by technical concern (Controllers/, Services/) | Group by feature: `Features/BookFeature/CreateBook/` |
 | Route data access through any indirection layer | Inject `DbContext` and write LINQ in the slice; dedicated store only with `plan.md` (`## Decisões`) justification |
 | Use raw SQL (`FromSqlRaw` / `ExecuteQuery(string)`) by default | Use LINQ; raw SQL only with a `plan.md` (`## Decisões`) justification |

package/framework/standards/frontend/admin-app/data-table.md

@@ -82,9 +82,7 @@ The page parses the query, renders the toolbar, and wraps the results in a `Susp
 // app/(admin)/products/page.tsx
 import { Suspense } from 'react';
 import { DataTableSkeleton } from '@/components/data-table-skeleton';
-import { ProductResults } from '@/features/products/components/product-results';
-import { ProductToolbar } from '@/features/products/components/product-toolbar';
-import { productListQuerySchema } from '@/features/products/types/product-list.schemas';
+import { ProductResults, ProductToolbar, productListQuerySchema } from '@/features/products';
 
 export default async function ProductsPage({
   searchParams,

package/framework/standards/frontend/admin-app/page-structure.md

@@ -35,10 +35,14 @@ The page reads `tab` from `searchParams` and renders only that tab's content on
 
 ```tsx
 // app/(admin)/products/[id]/page.tsx
-import { ProductTabs, PRODUCT_TABS, type ProductTab } from '@/features/products/components/product-tabs';
-import { ProductDetailsTab } from '@/features/products/components/product-details-tab';
-import { ProductVariantsTab } from '@/features/products/components/product-variants-tab';
-import { ProductHistoryTab } from '@/features/products/components/product-history-tab';
+import {
+  PRODUCT_TABS,
+  ProductDetailsTab,
+  ProductHistoryTab,
+  ProductTabs,
+  ProductVariantsTab,
+  type ProductTab,
+} from '@/features/products';
 
 export default async function ProductPage({
   params,

package/framework/standards/frontend/nextjs/app-router.md

@@ -16,9 +16,9 @@ Next.js App Router with TypeScript strict mode. Server Components by default, Cl
 - ALWAYS default to Server Components — add `'use client'` only when needed
 - ALWAYS keep `app/` directory for routing only — no business logic in page files
 - NEVER put data fetching in Client Components when a Server Component can do it
-- NEVER use `useEffect` to fetch data — use Server Components or TanStack Query
 - ALWAYS co-locate loading/error UI: `loading.tsx`, `error.tsx` next to `page.tsx`
 - ALWAYS use TypeScript — no `.js` or `.jsx` files in the project
+- Fetch inside `useEffect` and `'use client'` in the root `layout.tsx` are lint errors (`frontend-nextjs-lint`)
 
 ## Server vs Client Components
 
@@ -68,7 +68,7 @@ src/app/
 | `page.tsx` | Route segment UI | Server Component (default) |
 | `layout.tsx` | Shared UI wrapper | Server Component |
 | `loading.tsx` | Suspense fallback | Server Component |
-| `error.tsx` | Error boundary | **Must be Client Component** |
+| `error.tsx` | Error boundary | Client Component |
 | `not-found.tsx` | 404 page | Server Component |
 | `route.ts` | API route (avoid — use .NET API) | — |
 
@@ -80,7 +80,7 @@ the same-origin proxy prefix Client Components use. See `frontend/nextjs/data-fe
 
 ```tsx
 // app/(dashboard)/users/page.tsx
-import { UserList } from '@/features/users/components/user-list';
+import { UserList } from '@/features/users';
 import { BACKEND_API_PREFIX } from '@/lib/api/prefixes'; // server-direct prefix ONLY
 
 async function getUsers(): Promise<User[]> {
@@ -123,7 +123,6 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 | Wrong | Right | Why |
 |-------|-------|-----|
 | `'use client'` on every component | Only add when needed | Kills SSR benefits, bloats JS bundle |
-| `useEffect(() => { fetch(...) }, [])` | Server Component fetch or TanStack Query | Two renders, no caching, no SSR |
 | Business logic in `page.tsx` | Move to `features/` | pages are routes, not controllers |
 | `fetch` without error handling | Always check `res.ok` | Silent failures in production |
 

package/framework/standards/frontend/nextjs/components.md

@@ -14,10 +14,10 @@ Three-tier component hierarchy. `components/ui/` is shadcn primitives (never edi
 ## Core Rules
 
 - NEVER edit files in `components/ui/` — they are regenerated by shadcn CLI
-- NEVER import from `features/` inside `components/` — components know nothing about domain
 - ALWAYS compose shadcn primitives in `components/` instead of editing them
 - ALWAYS add `'use client'` only if the component uses hooks, events, or browser APIs
 - NEVER pass raw API data directly to a component — transform to props first
+- `components/` importing `features/` and the legacy `@/components/ui/form` are lint errors (`frontend-nextjs-lint`)
 
 ## Three-Tier Hierarchy
 
@@ -89,26 +89,13 @@ export function UsersPageHeader({ canInvite }: { canInvite: boolean }) {
 
 A feature **list** is a Tier 3 component too: the feature owns the columns and the URL ⇄ table mapping, the shared table owns the rendering — `admin-app/data-table.md` → "The Feature Table".
 
-## Component Props Conventions
-
-```tsx
-interface UserCardProps {
-  user: User;
-  onEdit?: (id: string) => void;
-  className?: string; // Always allow className for Tailwind override
-}
-
-export function UserCard({ user, onEdit, className }: UserCardProps) {}
-```
-
 ## Common Mistakes
 
 | Wrong | Right | Why |
 |-------|-------|-----|
 | Edit `components/ui/button.tsx` | Wrap in `components/action-button.tsx` | shadcn CLI overwrites it |
-| `import { useUsers } from '@/features/users'` in `components/` | Move to a feature component | Breaks tier isolation |
 | `'use client'` on all components | Only on interactive ones | Unnecessary client JS |
-| Pass raw fetch response as prop | Type and validate with Zod first | Runtime type safety |
+| Pass raw fetch response as prop | Map it to typed props in the feature | The component stops depending on the API shape |
 
 ---
 

package/framework/standards/frontend/nextjs/data-fetching.md

@@ -9,16 +9,16 @@
 
 ---
 
-Server Components for initial page load. TanStack Query for client mutations and interactive data. Never `useEffect` for fetching.
+Server Components for initial page load. TanStack Query for client mutations and interactive data.
 
 ## Core Rules
 
 - ALWAYS use Server Components for initial data that doesn't require interactivity
 - ALWAYS use TanStack Query (`useQuery`, `useMutation`) for client-side data needs
-- NEVER use `useEffect(() => { fetch(...) }, [])` — this is the old pattern
 - ALWAYS validate API responses with Zod before using them
 - ALWAYS use query key factories for consistent cache invalidation
 - NEVER fetch a whole collection to page, sort or filter it in the browser — a list is paged on the server, with the query in the URL (`admin-app/data-table.md`)
+- Fetch inside `useEffect` and a DB driver in Next are lint errors (`frontend-nextjs-lint`)
 
 ## TanStack Query Setup
 
@@ -134,7 +134,6 @@ export function UserListClient({ initialData }: { initialData: User[] }) {
 
 | Wrong | Right | Why |
 |-------|-------|-----|
-| `useEffect(() => { fetch(...) }, [])` | `useQuery(...)` | Two renders, no cache, no SSR |
 | No Zod on API response | `schema.parse(await res.json())` | Type safety at runtime |
 | Hardcoded query keys: `['users']` | Key factory: `userKeys.lists()` | Consistent invalidation |
 | `queryClient.invalidateQueries(['users'])` | `{ queryKey: userKeys.lists() }` | Object syntax required in v5 |

package/framework/standards/frontend/nextjs/lint.md

@@ -0,0 +1,141 @@
+# ESLint Next.js — o lint cobra, a prosa não repete
+
+> **Scope:** nextjs
+> **Layer:** 0 (resumo injetado pela rule `nextjs-standards` (`**/*.ts`, `**/*.tsx`); o `stack-scan` acusa o projeto sem este arquivo)
+> **Keywords:** eslint, lint, eslint.config.mjs, no-restricted-imports, no-restricted-paths, no-restricted-syntax, no-default-export, no-explicit-any, framer-motion, zustand
+> **Load When:** projeto Next.js sem `eslint.config.mjs` com `no-restricted-imports`, ou o lint acusou uma destas regras
+
+**Verified against:** eslint 9.39.5, eslint-config-next 16.4.2 (typescript-eslint 8.71.2, eslint-plugin-import 2.32.0), next 16.4.2, typescript 6.0.3 (sonda: um arquivo ruim por regra → erro da regra esperada, `no-console` → aviso, arquivos conformes e o scaffold `morph-spec scaffold nextjs` → 0 problemas). Last-verified: 2026-10-18.
+
+---
+
+Regra de código que tem motivo e que uma máquina enxerga vira **erro de lint**, não frase que o
+agente relê a cada sessão. Um arquivo na raiz do app Next basta, e só usa o que o
+`eslint-config-next` já instala (typescript-eslint e eslint-plugin-import): nenhum plugin novo.
+
+## Arquivos
+
+Dependências (`npm i -D eslint@9 eslint-config-next typescript`). ESLint 9 é a faixa que
+`eslint-plugin-import` e `eslint-plugin-react` declaram como peer; o typescript-eslint do
+`eslint-config-next` pede TypeScript `<6.1`.
+
+No Next 16 o `next build` não roda mais o lint. O nó de build do `morph-spec verify` roda o
+eslint (`--quiet`: só erro reprova) **só nos arquivos que a feature mudou**, na raiz do app, quando
+acha `eslint.config.*` e o pacote `eslint` instalado: dívida de lint antiga nunca deixa a feature
+vermelha. As zonas são relativas a essa raiz.
+
+`eslint.config.mjs`:
+
+```js
+import { defineConfig, globalIgnores } from 'eslint/config'
+import nextVitals from 'eslint-config-next/core-web-vitals'
+import nextTs from 'eslint-config-next/typescript'
+
+const BANNED = [
+  [['framer-motion'], 'Motion entra por motion/react: um único caminho de import.'],
+  [['zustand', 'redux', '@reduxjs/toolkit'], 'Estado de servidor é do TanStack Query; página e filtro vão na URL.'],
+  [['pg', '@neondatabase/serverless', '@prisma/client', 'drizzle-orm', 'postgres'], 'O Next nunca fala com o banco: o dado vem da API .NET.'],
+]
+
+const DEEP_FEATURE = {
+  group: ['@/features/*/*'],
+  message: 'Fora da feature, importe a API pública (@/features/x), nunca um caminho interno.',
+}
+
+const restrictedImports = (...extraPatterns) => ['error', {
+  paths: [
+    ...BANNED.flatMap(([names, message]) => names.map((name) => ({ name, message }))),
+    { name: '@/components/ui/form', message: 'Form legado do shadcn: Controller + Field (frontend-nextjs-forms).' },
+  ],
+  patterns: [
+    ...BANNED.map(([names, message]) => ({ group: names.map((n) => `${n}/*`), message })),
+    ...extraPatterns,
+  ],
+}]
+
+const FETCH_IN_EFFECT = {
+  selector:
+    "CallExpression[callee.name='useEffect'] CallExpression:matches([callee.name='fetch'], [callee.name='apiClient'], [callee.object.name='apiClient'])",
+  message: 'Dado do servidor vem de Server Component ou TanStack Query, nunca de fetch em useEffect.',
+}
+
+export default defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  globalIgnores(['.next/**', 'out/**', 'build/**', 'next-env.d.ts']),
+  {
+    rules: {
+      'no-restricted-imports': restrictedImports(DEEP_FEATURE),
+      'import/no-restricted-paths': ['error', {
+        zones: [
+          { target: './src/components', from: './src/features', message: 'components/ é apresentação: não conhece feature.' },
+          { target: './src/features', from: './src/app', message: 'app/ importa de features/, nunca o contrário.' },
+          { target: './src/hooks', from: ['./src/lib/api-client.ts', './src/lib/api'], message: 'Hook compartilhado não chama API: isso é hook de feature.' },
+        ],
+      }],
+      'no-restricted-syntax': ['error', FETCH_IN_EFFECT],
+      'import/no-default-export': 'error',
+      '@typescript-eslint/no-explicit-any': 'error',
+      'no-console': 'warn',
+    },
+  },
+  {
+    files: ['src/features/**'],
+    rules: { 'no-restricted-imports': restrictedImports() },
+  },
+  {
+    files: ['app/layout.tsx', 'src/app/layout.tsx'],
+    rules: {
+      'no-restricted-syntax': ['error', FETCH_IN_EFFECT, {
+        selector: "Program > ExpressionStatement[directive='use client']",
+        message: "O layout raiz é Server Component (metadata): o 'use client' vai no provider que ele renderiza.",
+      }],
+    },
+  },
+  {
+    files: [
+      '**/app/**/{page,layout,loading,error,global-error,not-found,forbidden,unauthorized,template,default,route}.{ts,tsx}',
+      '**/app/**/{sitemap,robots,manifest,icon,apple-icon,opengraph-image,twitter-image}.{ts,tsx}',
+      '**/*.config.{js,mjs,cjs,ts}',
+    ],
+    rules: { 'import/no-default-export': 'off' },
+  },
+])
+```
+
+Cada override de `no-restricted-imports` e `no-restricted-syntax` substitui a lista inteira da
+regra naquele arquivo, por isso o bloco do layout repete `FETCH_IN_EFFECT` e o de `features/`
+repete os pacotes banidos.
+
+## O que cada regra compra
+
+| Regra | Bloqueia | Por quê |
+|---|---|---|
+| `no-restricted-imports` `@/features/*/*` (fora de `src/features/`) | `app/`, `components/` e `lib/` lendo arquivo interno de uma feature | o `index.ts` é a API pública: refatorar dentro da feature não quebra quem está fora |
+| `no-restricted-imports` `framer-motion` | o segundo caminho de import do Motion | `motion/react` e `framer-motion` juntos duplicam o runtime no bundle e dividem o código em duas APIs |
+| `no-restricted-imports` `zustand`, `redux`, `@reduxjs/toolkit` | store global | cópia do estado do servidor fica velha sem o cache do TanStack Query; página e filtro na URL sobrevivem a refresh e link |
+| `no-restricted-imports` `pg`, `@neondatabase/serverless`, `@prisma/client`, `drizzle-orm`, `postgres` | driver de banco no Next | regra de negócio e acesso a dados moram no .NET (EF Core); um segundo caminho ao banco pula a autorização dele |
+| `no-restricted-imports` `@/components/ui/form` | o `Form` legado do shadcn | a documentação do shadcn é escrita em `Controller` + `Field`; a tela legada migra quando é tocada |
+| `import/no-restricted-paths` `src/components` ↛ `src/features` | componente compartilhado que conhece domínio | ele deixa de ser compartilhável e cria ciclo feature → components → feature |
+| `import/no-restricted-paths` `src/features` ↛ `src/app` | feature importando rota | a dependência é de mão única: a rota compõe a feature |
+| `import/no-restricted-paths` `src/hooks` ↛ cliente da API | hook compartilhado chamando o backend | chamada à API é de feature, com a key factory dela; hook compartilhado é só de UI |
+| `no-restricted-syntax` fetch/`apiClient` dentro de `useEffect` | busca de dado no efeito | sem cache, sem dedup, corrida entre requisições e cascata de render; Server Component ou TanStack Query resolvem |
+| `no-restricted-syntax` `'use client'` em `app/layout.tsx` | layout raiz no cliente | perde `metadata` e manda a árvore inteira para o bundle do cliente |
+| `import/no-default-export` (exceto arquivos de rota e `*.config.*`) | `export default` em componente e hook | nome único em todo import: busca e rename acham todos os usos; o Next exige `default` só nos arquivos de convenção |
+| `@typescript-eslint/no-explicit-any` | `any` | desliga o tipo no ponto onde o dado da API entra; o certo é schema Zod + `z.infer` |
+| `no-console` (aviso) | `console.log` esquecido | ruído no console do usuário e dado vazando; aviso, porque o diagnóstico local é legítimo |
+
+Restrição nova entra como linha neste arquivo, com o porquê na `message`. Nunca uma regra nova
+em prosa. Exceção pontual é `// eslint-disable-next-line <regra> -- <motivo>` na linha, nunca o
+desligamento da regra no projeto.
+
+## O que não é regra
+
+Nome de classe CSS (BEM, prefixo de página, namespace `--app-`, sufixo de estado), catálogo de
+classes `.animate-*`/`.stagger-*`, `className` opcional em toda prop, Zod em props, quantos
+momentos de motion uma página tem, o deslocamento de uma transição, o skeleton com
+`animate-pulse`, os defaults de `staleTime`/`retry` do `QueryClient` e quantos níveis de prop
+drilling são aceitáveis são gosto: nem prosa nem lint. Siga o arquivo vizinho, e o formatter do
+projeto decide a forma. Também saíram da prosa o `'use client'` no `error.tsx` (o `next build`
+recusa sem ele) e o prefixo `use` do hook (o `react-hooks/rules-of-hooks` que vem no
+`eslint-config-next` acusa hook chamado fora de função `useX`).

package/framework/standards/frontend/nextjs/motion-patterns.md

@@ -221,14 +221,11 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 
 - `mode="wait"` ensures the exit animation completes before the entering page renders.
 - The `key` prop must change on navigation — use `usePathname()` from `next/navigation`.
-- Keep page transitions subtle (`y: 8`, fast duration) — aggressive transitions hurt perceived performance.
 
 ---
 
 ## Section 6: Loading Patterns
 
-Prefer CSS `animate-pulse` for skeleton loaders over Motion — CSS animations run off the main thread and have lower performance overhead.
-
 ```tsx
 // components/skeleton.tsx
 import { cn } from '@/lib/utils';
@@ -315,11 +312,8 @@ This CSS fallback catches animations outside Motion (Tailwind `animate-*`, third
 | `duration: 0.8` for UI interactions | `duration: durations.fast` (0.15) for micro-interactions |
 | Hardcoded easing `[0.4, 0, 0.2, 1]` | `ease: easings.standard` (from design-tokens) |
 | No `useReducedMotion()` check | Always check or use CSS media query |
-| Animating everything on the page | Reserve motion for 3-5 meaningful moments per page |
 | Forgetting `animation-fill-mode: backwards` in stagger | Will cause a flash before the animation starts |
 | `AnimatePresence` without `key` changes | Exit animations will never fire |
-| Using `motion` for skeleton loaders | Use CSS `animate-pulse` — lower performance cost |
-| `npm install framer-motion` / `import ... from 'framer-motion'` | `npm install motion` / `import ... from 'motion/react'` — same code underneath, but one import path per codebase |
 | Need ScrollTrigger, SVG morph, or complex timelines | Use GSAP — see `frontend/gsap/gsap-core.md` |
 
 ---
@@ -333,7 +327,8 @@ npm install motion
 > The package is `motion` and components import from `motion/react`. `framer-motion`
 > is not deprecated: it is published with the same version and `motion` depends on
 > it. New code still depends on `motion` and imports from `motion/react`, so the
-> codebase has a single import path; do not add `framer-motion` alongside it.
+> codebase has a single import path; a `framer-motion` import is a lint error
+> (`frontend-nextjs-lint`).
 
 Verify the installed version supports the features used here (requires motion >= 11; current major on npm is 14):
 

package/framework/standards/frontend/nextjs/naming-conventions.md

@@ -15,9 +15,9 @@ Consistent naming prevents filesystem bugs (Linux case-sensitivity) and keeps th
 
 - ALWAYS use kebab-case for file names — never PascalCase or camelCase
 - ALWAYS use PascalCase for React component exports
-- ALWAYS use camelCase starting with `use` for hook exports
 - ALWAYS suffix schema files with `.schemas.ts` and type files with `.types.ts`
 - NEVER mix cases in the same category — no `UserCard.tsx` alongside `user-profile.tsx`
+- Named exports, the hook `use` prefix and `default` only in route files are lint errors (`frontend-nextjs-lint`), not rules to reread
 
 ## Complete Reference Table
 
@@ -63,7 +63,6 @@ export type UpdateUserInput = z.infer<typeof updateUserSchema>;
 |-------|-------|-----|
 | `UserCard.tsx` | `user-card.tsx` | Linux servers are case-sensitive |
 | `useUsers.ts` | `use-users.ts` | Inconsistent with Next.js file conventions |
-| `export default function UserCard` | `export function UserCard` | Named exports are more refactor-safe |
 | `type User = { id: string }` | `type User = z.infer<typeof userSchema>` | Single source of truth |
 
 ---

package/framework/standards/frontend/nextjs/nextjs-patterns.md

@@ -16,7 +16,8 @@ Stack: Next.js 15 + Neon PostgreSQL + .NET Backend
 - ALWAYS use App Router (not Pages Router)
 - Default to Server Components -- add `'use client'` only when needed
 - ALWAYS colocate loading.tsx and error.tsx with page.tsx
-- NEVER call the database directly from client -- use Route Handlers as BFF
+- Route Handlers are a BFF that delegates to the .NET API
+- A DB driver, `any`, fetch inside `useEffect` and `'use client'` in the root layout are lint errors (`frontend-nextjs-lint`)
 - ALWAYS validate inputs with Zod on both client and server
 - Use TypeScript strict mode (`"strict": true`)
 
@@ -58,7 +59,7 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 // loading.tsx
 export default function Loading() { return <div className="animate-pulse">Loading...</div>; }
 
-// error.tsx — MUST be 'use client'
+// error.tsx
 'use client';
 export default function Error({ error, reset }: { error: Error; reset: () => void }) {
   return <div><h2>Something went wrong</h2><button onClick={reset}>Try again</button></div>;
@@ -187,7 +188,7 @@ export function DocumentForm() {
 
 ## shadcn/ui
 
-Install: `npx shadcn@latest init` then `npx shadcn@latest add button input card dialog form`.
+Install: `npx shadcn@latest init` then `npx shadcn@latest add button input card dialog field`.
 Components are copied to `components/ui/` -- NOT an npm dependency, your code to customize.
 
 ## TypeScript Strict Patterns
@@ -195,7 +196,7 @@ Components are copied to `components/ui/` -- NOT an npm dependency, your code to
 | Pattern | Approach |
 |---------|----------|
 | API responses | Zod schema + `z.infer<typeof schema>` |
-| Props | Explicit interface, no `any` |
+| Props | Explicit interface |
 | Event handlers | `React.ChangeEvent<HTMLInputElement>` |
 | Null safety | `?.` over type assertions, `if (!data) return null` |
 
@@ -204,10 +205,7 @@ Components are copied to `components/ui/` -- NOT an npm dependency, your code to
 | Wrong | Right | Why |
 |-------|-------|-----|
 | `'use client'` on every component | Default to Server Components | Unnecessary JS bundle size |
-| Direct DB from client | Route Handler `/api/*` as BFF | Exposes queries, harder to secure |
-| `any` for API responses | Zod schema + infer | No runtime safety |
 | Missing loading.tsx | Colocate with page.tsx | Blank page during load |
-| `useEffect` for data fetching | React Query `useQuery` | No caching, race conditions |
 | Form validation on submit only | Zod resolver + react-hook-form | Delayed error feedback |
 | shadcn as npm package | `npx shadcn@latest add` | Copy-paste system, not a dependency |