@polymorphism-tech/morph-spec 9.4.0 → 9.5.0

package/framework/standards/frontend/nextjs/project-structure.md

@@ -14,10 +14,11 @@ Feature-based architecture with a shared core. Features are self-contained; shar
 ## Core Rules
 
 - ALWAYS use feature-based folders: `features/{feature-name}/`
-- ALWAYS keep `app/` for routing only — import from `features/`, not the other way
+- ALWAYS keep `app/` for routing only — the screen's logic lives in `features/`
 - NEVER import from one feature into another — extract to `components/` or `lib/` if shared
 - ALWAYS use `src/` directory (configured in `tsconfig.json` with `@/` alias)
 - NEVER put business logic in `components/` — it is presentation only
+- Deep imports into a feature from outside it, `components/` → `features/`, `features/` → `app/` and shared `hooks/` → the API client are lint errors (`frontend-nextjs-lint`)
 
 ## Canonical Folder Tree
 
@@ -82,7 +83,7 @@ export { useCreateUser } from './hooks/use-create-user';
 export type { User, CreateUserInput } from './types/user.types';
 ```
 
-Import from the index, not deep paths:
+Outside the feature, import from the index:
 ```ts
 // GOOD
 import { UserList, useUsers } from '@/features/users';

package/framework/standards/frontend/nextjs/state-management.md

@@ -16,7 +16,7 @@ Server state (API data) lives in TanStack Query. UI state lives in React. No glo
 - ALWAYS use TanStack Query for anything that comes from the .NET API
 - ALWAYS use `useState` for local UI state (modal open, form step)
 - ALWAYS keep a list's page, sort and filters, and a page's active tab, in the URL (`searchParams`) — never in `useState`: a refresh or a shared link must reopen the same view (`admin-app/data-table.md`, `admin-app/page-structure.md`)
-- NEVER install Zustand or Redux without first exhausting Server Components + TanStack Query
+- `zustand`, `redux` and `@reduxjs/toolkit` are lint errors (`frontend-nextjs-lint`); the only way past it is the exception below
 - NEVER use React Context for server state — Context does not cache or deduplicate
 - ALWAYS derive state from server data rather than syncing it to local state
 
@@ -30,9 +30,9 @@ Is this local UI state (open/closed, selected, current step)?
   YES → useState in the component that needs it
 
 Does multiple components need this UI state?
-  YES — is it parent-child?     → prop drilling (2-3 levels is fine)
+  YES — is it parent-child?     → props
   YES — is it truly global?     → React Context (theme, auth user, locale)
-  YES — complex with many actions? → Consider Zustand (last resort)
+  YES — complex with many actions? → global store (exception below)
 ```
 
 ## Server State (TanStack Query)
@@ -55,9 +55,10 @@ function UserList() {
 }
 ```
 
-## When Zustand Is Justified
+## When a Global Store Is Justified
 
-Only add Zustand if ALL of these are true:
+The lint blocks the import. Lift it only if ALL of these are true, with one
+`// eslint-disable-next-line no-restricted-imports -- <reason>` in the single store file:
 1. State is needed in 5+ unrelated components
 2. State has complex update logic (not just toggle/set)
 3. Context causes measurable re-render performance issues
@@ -67,10 +68,8 @@ Only add Zustand if ALL of these are true:
 
 | Wrong | Right | Why |
 |-------|-------|-----|
-| `useEffect` + `useState` for API data | TanStack Query | Stale data, no cache, double-render |
 | Global store for user list | `useUsers()` | TanStack Query handles sync/cache |
 | Context for everything | useState + prop drilling first | Context causes all consumers to re-render |
-| Zustand by default | Start with useState | YAGNI — most state is local |
 
 ---
 

package/framework/templates/README.md

@@ -8,8 +8,8 @@
 nextjs) rather than by stack. A template for a .NET slice serves every stack with a .NET
 backend, so a new stack reuses what exists instead of copying it.
 
-`REGISTRY.json` is the source of truth: it maps each template `id` to its `path`, category,
-technology and applicable stacks. Nothing resolves a template by hardcoded path — code goes
+`REGISTRY.json` is the source of truth: it maps each template `id` to its `kind`, `path` and
+`category` (the shape per kind is in its `kinds` block). Nothing resolves a template by hardcoded path — code goes
 through the registry, and this README never repeats a path the registry already owns.
 
 ---
@@ -109,8 +109,8 @@ updates** — only override when the packaged template genuinely does not fit.
 1. Create the file under the right technology directory:
    `framework/templates/code/{technology}/...` (Handlebars syntax, `.hbs` when the extension
    would otherwise confuse tooling).
-2. Register it in `REGISTRY.json` with a unique `id`, its `path`, `category`, `technology`
-   and applicable stacks.
+2. Register it in `REGISTRY.json` with a unique `id`, its `kind`, `path` and `category`, plus
+   the fields its kind requires (`kinds` block; `scripts/validate-framework.js` checks them).
 3. If a generator should emit it, add the `id` to the relevant list in
    `src/lib/generators/scaffold-generator.js`.