@polymorphism-tech/morph-spec 4.6.0 → 4.7.0

package/framework/rules/frontend-standards.md

@@ -1,8 +1,6 @@
 ---
 paths:
   - "**/*.razor"
-  - "**/*.tsx"
-  - "**/*.ts"
   - "**/*.css"
   - "**/*.scss"
 ---
@@ -10,5 +8,4 @@ paths:
 # Frontend Standards
 
 @.morph/framework/standards/frontend/blazor/design-checklist.md
-@.morph/framework/standards/frontend/nextjs/nextjs-patterns.md
 @.morph/framework/standards/frontend/design-system/naming.md

package/framework/rules/nextjs-standards.md

@@ -0,0 +1,17 @@
+---
+paths:
+  - "**/*.tsx"
+  - "**/*.ts"
+---
+
+# Next.js Standards
+
+@.morph/framework/standards/frontend/nextjs/naming-conventions.md
+@.morph/framework/standards/frontend/nextjs/project-structure.md
+@.morph/framework/standards/frontend/nextjs/app-router.md
+@.morph/framework/standards/frontend/nextjs/components.md
+@.morph/framework/standards/frontend/nextjs/data-fetching.md
+@.morph/framework/standards/frontend/nextjs/forms.md
+@.morph/framework/standards/frontend/nextjs/state-management.md
+@.morph/framework/standards/frontend/nextjs/testing.md
+@.morph/framework/standards/frontend/nextjs/nextjs-patterns.md

package/framework/skills/level-0-meta/code-review-nextjs/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: code-review-nextjs
+description: Next.js code review checklist covering naming conventions, component architecture (Server vs Client), data fetching patterns, form implementation, state management, TypeScript/Zod discipline, feature boundaries, and testing. Use after implementing Next.js code, before creating PRs, or when reviewing TSX/TS code for compliance with MORPH-SPEC Next.js standards.
+user-invocable: true
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# Next.js Code Review Checklist
+
+> Comprehensive checklist for Next.js code review: naming, component architecture, data fetching, forms, state, TypeScript, structure, and testing.
+> **Ref:** `framework/standards/frontend/nextjs/naming-conventions.md`
+> **Ref:** `framework/standards/frontend/nextjs/app-router.md`
+> **Ref:** `framework/standards/frontend/nextjs/components.md`
+> **Ref:** `framework/standards/frontend/nextjs/data-fetching.md`
+> **Ref:** `framework/standards/frontend/nextjs/forms.md`
+> **Ref:** `framework/standards/frontend/nextjs/state-management.md`
+> **Ref:** `framework/standards/frontend/nextjs/testing.md`
+> **Example:** `references/review-example-nextjs.md` — filled-in review showing expected finding format.
+> **Script:** `scripts/scan-nextjs.mjs` — automated scan for CRITICAL/HIGH violations before manual review.
+
+---
+
+## Step 1 — Run automated scan first
+
+```bash
+node scripts/scan-nextjs.mjs src/
+```
+
+Review and address CRITICAL findings before proceeding with the manual checklist below. Warnings can be addressed during review.
+
+---
+
+## Naming & Style (ref: naming-conventions.md)
+
+- [ ] `[CRITICAL]` File names use kebab-case (`user-card.tsx`, NOT `UserCard.tsx`)
+- [ ] `[HIGH]` Components exported as named exports (`export function UserCard`, NOT `export default function UserCard`)
+- [ ] `[HIGH]` Hook files named `use-{action}.ts` and export `use{Action}()`
+- [ ] `[HIGH]` Schema files named `{feature}.schemas.ts` with Zod exports
+- [ ] `[HIGH]` Type files named `{feature}.types.ts` with `z.infer<>` derived types
+- [ ] `[MEDIUM]` No abbreviations in public API names (`repository` not `repo`)
+- [ ] `[MEDIUM]` Feature folder uses kebab-case (`features/user-management/`, NOT `features/userManagement/`)
+
+---
+
+## Component Architecture (ref: app-router.md, components.md)
+
+### Server vs Client Discipline
+- [ ] `[CRITICAL]` `'use client'` only on components that use hooks or event handlers
+- [ ] `[CRITICAL]` No `useEffect(() => { fetch(...) }, [])` for data fetching — use Server Components or TanStack Query
+- [ ] `[HIGH]` Server Components used for initial page data (no `'use client'` on page files)
+- [ ] `[HIGH]` `loading.tsx`, `error.tsx` co-located with every `page.tsx`
+- [ ] `[HIGH]` No business logic in `app/` route files — import from `features/`
+
+### Three-Tier Hierarchy
+- [ ] `[CRITICAL]` No edits to `components/ui/` files — shadcn primitives are never modified
+- [ ] `[HIGH]` `components/` (Tier 2) has no imports from `features/` — no domain knowledge
+- [ ] `[HIGH]` Feature components (`features/*/components/`) do not import from other features
+- [ ] `[MEDIUM]` Feature cross-dependencies extracted to `components/` or `lib/`
+
+---
+
+## Data Fetching (ref: data-fetching.md)
+
+- [ ] `[CRITICAL]` No `useEffect` + `useState` pattern for API data — use `useQuery`
+- [ ] `[HIGH]` TanStack Query v5 syntax: `useQuery({ queryKey: [...], queryFn: async () => {} })`
+- [ ] `[HIGH]` Query key factory pattern used (`userKeys.lists()`, NOT hardcoded `['users']`)
+- [ ] `[HIGH]` `useMutation` used for POST/PUT/DELETE — not inline `fetch` in handlers
+- [ ] `[HIGH]` API responses validated with Zod before use
+- [ ] `[MEDIUM]` `onSuccess` in `useMutation` invalidates relevant query keys
+- [ ] `[MEDIUM]` `QueryClientProvider` wraps app in `app/layout.tsx`, not per-component
+
+---
+
+## Forms (ref: forms.md)
+
+- [ ] `[CRITICAL]` Zod schema defined BEFORE TypeScript type — type derived with `z.infer<>`
+- [ ] `[HIGH]` `useForm` uses `zodResolver(schema)` — NOT manual validation
+- [ ] `[HIGH]` shadcn `<Form>`, `<FormField>`, `<FormItem>`, `<FormLabel>`, `<FormControl>`, `<FormMessage>` used
+- [ ] `[HIGH]` Form submission uses `useMutation` — NOT direct `fetch` in `onSubmit`
+- [ ] `[MEDIUM]` `isPending` used for loading state — NOT `isLoading` (v5 renamed)
+- [ ] `[MEDIUM]` Root-level errors displayed: `form.formState.errors.root`
+- [ ] `[MEDIUM]` No `useState` for individual form fields — react-hook-form handles this
+
+---
+
+## State Management (ref: state-management.md)
+
+- [ ] `[HIGH]` No Zustand/Redux installed without documented justification
+- [ ] `[HIGH]` No React Context used for server state (API data) — use TanStack Query
+- [ ] `[MEDIUM]` Local UI state (open/closed, selected) in `useState` — not global store
+- [ ] `[MEDIUM]` Context only for truly global UI: theme, auth user, locale
+- [ ] `[LOW]` No prop drilling beyond 3 levels — consider Context or co-location
+
+---
+
+## TypeScript Discipline
+
+- [ ] `[CRITICAL]` No `any` type — use `unknown` and narrow, or fix the actual type
+- [ ] `[HIGH]` Types derived from Zod schemas (`type User = z.infer<typeof userSchema>`)
+- [ ] `[HIGH]` No duplicate type definitions — if the server returns it, define it once with Zod
+- [ ] `[MEDIUM]` API response types come from the shared schema, not manually written
+- [ ] `[MEDIUM]` `noUncheckedIndexedAccess` respected — array accesses use optional chaining
+- [ ] `[LOW]` No type assertions (`as User`) without validation
+
+---
+
+## Feature Structure (ref: project-structure.md)
+
+- [ ] `[HIGH]` Feature exposes public API via `features/{name}/index.ts` — no deep path imports
+- [ ] `[HIGH]` Consumers import from index: `from '@/features/users'` NOT `from '@/features/users/components/user-list'`
+- [ ] `[MEDIUM]` New features create: `components/`, `hooks/`, `types/` subdirectories
+- [ ] `[MEDIUM]` TanStack Query hooks in `features/{name}/hooks/` — NOT co-located with components
+- [ ] `[MEDIUM]` Zod schemas in `features/{name}/types/{name}.schemas.ts`
+- [ ] `[LOW]` Feature index only exports what external consumers actually need (no over-exposure)
+
+---
+
+## Testing (ref: testing.md)
+
+- [ ] `[HIGH]` Test files co-located with source (`user-card.test.tsx` next to `user-card.tsx`)
+- [ ] `[HIGH]` `@testing-library/user-event` used — NOT `fireEvent`
+- [ ] `[HIGH]` API calls mocked with MSW — NOT `jest.mock('fetch')` or `global.fetch = jest.fn()`
+- [ ] `[MEDIUM]` Hook tests use `QueryClientWrapper` helper with `retry: false`
+- [ ] `[MEDIUM]` Tests cover happy path + one error path per component
+- [ ] `[LOW]` No snapshot tests — use `expect(screen.getByText(...))`
+
+---
+
+## Quick Pre-Merge Checklist
+
+```
+[ ] node scripts/scan-nextjs.mjs src/ — 0 CRITICAL findings
+[ ] File names are kebab-case (UserCard.tsx → user-card.tsx)
+[ ] 'use client' only on interactive components (hooks or event handlers)
+[ ] No useEffect for data fetching — Server Component or useQuery
+[ ] Zod schema defined first, type derived with z.infer<>
+[ ] zodResolver connected to useForm, useMutation for submit
+[ ] Query key factory used (userKeys.lists() not ['users'])
+[ ] Feature public API via features/{name}/index.ts
+[ ] components/ui/ files untouched (shadcn CLI only)
+[ ] Tests: userEvent not fireEvent, MSW not mock fetch
+```
+
+---
+
+*Covers: naming-conventions.md + app-router.md + components.md + data-fetching.md + forms.md + state-management.md + testing.md + project-structure.md*
+*MORPH-SPEC by Polymorphism Tech*

package/framework/skills/level-0-meta/code-review-nextjs/references/review-example-nextjs.md

@@ -0,0 +1,254 @@
+# Code Review Report — User Management Feature
+
+> Example of a well-structured Next.js code review output. Filled-in reference — not a template.
+
+**Scope:** `src/features/users/` + `src/app/(dashboard)/users/page.tsx`
+**Date:** 2026-02-23
+**Reviewer:** code-review-nextjs skill
+
+---
+
+## Automated Scan Results
+
+```bash
+$ node scripts/scan-nextjs.mjs src/features/users/
+
+CRITICAL (1)
+  features/users/components/UserList.tsx:1  — React hooks used (useState) without 'use client'
+
+HIGH/MEDIUM (2)
+  features/users/components/UserList.tsx  — PascalCase filename (should be user-list.tsx)
+  features/users/components/user-form.tsx — 'use client' directive present but no interactivity detected
+
+Summary: 8 files scanned | 3 issues (1 critical, 2 high/medium)
+```
+
+---
+
+## Findings by Severity
+
+| Severity | Count |
+|----------|-------|
+| CRITICAL | 2 |
+| HIGH | 3 |
+| MEDIUM | 2 |
+| LOW | 1 |
+
+---
+
+### [CRITICAL] Missing 'use client' on interactive component
+
+**File:** `src/features/users/components/UserList.tsx:1`
+
+**Current code:**
+```tsx
+import { useState } from 'react';
+
+export function UserList() {
+  const [selected, setSelected] = useState<string | null>(null);
+  return <div onClick={() => setSelected('test')}>...</div>;
+}
+```
+
+**Suggested fix:**
+```tsx
+'use client';
+
+import { useState } from 'react';
+// ... rest unchanged
+```
+
+**Why:** React hooks (`useState`) require `'use client'`. Without it, Next.js treats this as a Server Component and the `useState` call fails at runtime.
+
+---
+
+### [CRITICAL] useEffect for data fetching
+
+**File:** `src/features/users/components/user-list.tsx:8`
+
+**Current code:**
+```tsx
+'use client';
+import { useEffect, useState } from 'react';
+
+export function UserList() {
+  const [users, setUsers] = useState([]);
+  useEffect(() => {
+    fetch('/api/users').then(r => r.json()).then(setUsers);
+  }, []);
+  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
+}
+```
+
+**Suggested fix:**
+```tsx
+// Option A — Server Component (no 'use client' needed)
+// app/(dashboard)/users/page.tsx
+async function getUsers() {
+  const res = await fetch(`${process.env.API_URL}/api/users`, { next: { revalidate: 30 } });
+  return res.json();
+}
+export default async function UsersPage() {
+  const users = await getUsers();
+  return <UserList initialData={users} />;
+}
+
+// Option B — TanStack Query (when client interactivity needed)
+'use client';
+import { useUsers } from '@/features/users/hooks/use-users';
+export function UserList() {
+  const { data: users = [], isLoading } = useUsers();
+  if (isLoading) return <div>Loading...</div>;
+  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
+}
+```
+
+**Why:** `useEffect` + `useState` for fetching: (1) doubles renders, (2) no caching, (3) no SSR, (4) no error/loading states, (5) can't be cancelled. TanStack Query or Server Components solve all five.
+
+---
+
+### [HIGH] PascalCase file name
+
+**File:** `src/features/users/components/UserList.tsx`
+
+**Suggested fix:** Rename to `user-list.tsx`
+
+**Why:** Linux servers are case-sensitive. `UserList.tsx` and `user-list.tsx` are different files on the server but the same on macOS/Windows, causing import failures in production.
+
+---
+
+### [HIGH] Default export on non-page component
+
+**File:** `src/features/users/components/user-card.tsx:3`
+
+**Current code:**
+```tsx
+export default function UserCard({ user }: { user: User }) {
+```
+
+**Suggested fix:**
+```tsx
+export function UserCard({ user }: { user: User }) {
+```
+
+**Why:** Named exports are refactor-safe — IDEs track renames automatically. Default exports are anonymous in imports (`import X from './user-card'` allows `X` to be anything).
+
+---
+
+### [HIGH] Type defined manually instead of deriving from Zod schema
+
+**File:** `src/features/users/types/user.types.ts:1`
+
+**Current code:**
+```ts
+export type User = {
+  id: string;
+  name: string;
+  email: string;
+  role: 'admin' | 'user';
+};
+```
+
+**Suggested fix:**
+```ts
+// user.schemas.ts — single source of truth
+export const userSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+  role: z.enum(['admin', 'user']),
+});
+
+// user.types.ts — derived, never written manually
+export type User = z.infer<typeof userSchema>;
+```
+
+**Why:** Manually written types drift from API responses. `z.infer<>` ensures the TypeScript type is always in sync with the runtime validation.
+
+---
+
+### [MEDIUM] Deep path import instead of feature index
+
+**File:** `src/app/(dashboard)/users/page.tsx:2`
+
+**Current code:**
+```tsx
+import { UserList } from '@/features/users/components/user-list';
+```
+
+**Suggested fix:**
+```tsx
+import { UserList } from '@/features/users';
+```
+
+**Why:** Deep path imports expose internal structure. When `user-list.tsx` moves or is renamed, every consumer breaks. The feature index is the stable public API.
+
+---
+
+### [MEDIUM] Query key not using factory pattern
+
+**File:** `src/features/users/hooks/use-users.ts:8`
+
+**Current code:**
+```ts
+return useQuery({
+  queryKey: ['users'],
+```
+
+**Suggested fix:**
+```ts
+// query-keys.ts
+export const userKeys = {
+  all: ['users'] as const,
+  lists: () => [...userKeys.all, 'list'] as const,
+};
+
+// use-users.ts
+return useQuery({
+  queryKey: userKeys.lists(),
+```
+
+**Why:** Hardcoded `['users']` cannot be selectively invalidated. `queryClient.invalidateQueries({ queryKey: userKeys.lists() })` correctly invalidates only list queries, not detail queries with the same prefix.
+
+---
+
+### [LOW] Test uses fireEvent instead of userEvent
+
+**File:** `src/features/users/components/user-card.test.tsx:14`
+
+**Current code:**
+```tsx
+fireEvent.click(screen.getByRole('button', { name: /edit/i }));
+```
+
+**Suggested fix:**
+```tsx
+await userEvent.click(screen.getByRole('button', { name: /edit/i }));
+```
+
+**Why:** `fireEvent.click` dispatches a synthetic event. `userEvent.click` simulates the full browser interaction sequence (pointerdown, mousedown, focus, click, etc.) — closer to real user behaviour.
+
+---
+
+## Top Priorities
+
+1. `UserList.tsx:1` — CRITICAL missing `'use client'` (2 min fix)
+2. `user-list.tsx:8` — CRITICAL useEffect fetch → useQuery (15 min)
+3. `UserList.tsx` — HIGH rename to `user-list.tsx` (2 min)
+4. `user-card.tsx:3` — HIGH named export (2 min)
+5. `user.types.ts:1` — HIGH derive from Zod (10 min)
+
+---
+
+## Passed Checks ✅
+
+- `components/ui/` files untouched
+- `zodResolver` correctly wired in `user-form.tsx`
+- `isPending` used (v5 correct — not `isLoading`)
+- `loading.tsx` and `error.tsx` present in `app/(dashboard)/users/`
+- Feature has `index.ts` re-exporting public API
+- Test file co-located with component
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/skills/level-0-meta/tool-usage-guide/SKILL.md

@@ -127,7 +127,7 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 
 ### Phase 2 — Design (Technical Spec)
 
-**Goal:** Analyze schema, create spec.md, contracts.cs, decisions.md
+**Goal:** Analyze schema, create spec.md, contracts-level{N}.cs, decisions.md
 
 | Action | Tool | Why |
 |--------|------|-----|
@@ -141,7 +141,7 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 | Look up library for ADR | **Context7 MCP** `query_docs()` | Compare library capabilities |
 | Check existing code patterns | **GitHub MCP** `search_code()` | Find patterns in large repos |
 | **Fallback:** Search codebase | **Grep** patterns across project | When no GitHub MCP |
-| Render contracts template | **Bash** `npx morph-spec template render code/dotnet/contracts/contracts.cs ...` | CLI command |
+| Render contracts template (detected level) | **Bash** `npx morph-spec template render code/dotnet/contracts/contracts-level{N}.cs ...` where N = level detected | CLI command |
 | Render spec template | **Bash** `npx morph-spec template render docs/spec ...` | CLI command |
 | Render decisions template | **Bash** `npx morph-spec template render docs/decisions ...` | CLI command |
 | Create schema-analysis.md | **Write** to output directory | Document findings |
@@ -153,7 +153,7 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 - ❌ Guessing field names without checking schema (use MCP or Grep first!)
 - ❌ Task agent to read a single spec file (just use Read)
 - ❌ WebSearch for database schema (use Supabase MCP or code analysis)
-- ❌ Manually writing contracts.cs from scratch (use template render)
+- ❌ Manually writing contracts-level{N}.cs from scratch (use template render)
 
 ---
 

package/framework/skills/level-1-workflows/phase-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: phase-design
-description: MORPH-SPEC Phase 2 (Design). Analyzes codebase/schema, then produces spec.md, contracts.cs, schema-analysis.md, and decisions.md for the feature. Use after setup phase to create a full technical specification with C# contracts based on the real database schema and architecture decision records.
+description: MORPH-SPEC Phase 2 (Design). Analyzes codebase/schema, then produces spec.md, contracts-level{N}.cs, schema-analysis.md, and decisions.md for the feature. Use after setup phase to create a full technical specification with C# contracts based on the real database schema and architecture decision records.
 argument-hint: "[feature-name]"
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
@@ -35,7 +35,7 @@ Expanda a proposta em especificação técnica completa, contracts, decisões ar
 | Ler arquivos de query/tipos (fallback) | **Read** cada arquivo encontrado | — |
 | Pesquisar biblioteca para ADR | **Context7 MCP** `query_docs()` | **WebSearch** + **WebFetch** |
 | Buscar padrões no código | **GitHub MCP** `search_code()` | **Grep** padrões no projeto |
-| Renderizar template contracts.cs | **Bash** `npx morph-spec template render code/dotnet/contracts/contracts.cs ...` | — |
+| Renderizar template contracts (nível detectado) | **Bash** `npx morph-spec template render code/dotnet/contracts/contracts-level{N}.cs ...` onde N = nível detectado no Passo 1.5 | — |
 | Renderizar template spec.md | **Bash** `npx morph-spec template render docs/spec ...` | — |
 | Renderizar template decisions.md | **Bash** `npx morph-spec template render docs/decisions ...` | — |
 | Criar schema-analysis.md | **Write** no diretório de outputs | — |
@@ -47,7 +47,7 @@ Expanda a proposta em especificação técnica completa, contracts, decisões ar
 - ❌ Adivinhar nomes de campos sem verificar schema (use MCP ou Grep primeiro!)
 - ❌ Task agent para ler um único arquivo spec (use Read direto)
 - ❌ WebSearch para schema do banco (use Supabase MCP ou análise de código)
-- ❌ Escrever contracts.cs do zero (use template render)
+- ❌ Escrever contracts-level{N}.cs do zero (use template render)
 
 ---
 
@@ -71,12 +71,48 @@ Parse o JSON para obter `activeAgents`, então use standards context (já carreg
 
 **Use standards context ao gerar spec.md:**
 - Architecture standards → guiam Technical Architecture section
-- Coding standards → definem contracts.cs patterns
+- Coding standards → definem contracts-level{N}.cs patterns
 - Azure standards → determinam Infrastructure Requirements
 
+### Passo 1.5: Detectar Nível de Domínio (domain-architect)
+
+**⚠️ OBRIGATÓRIO:** Execute antes de gerar qualquer contrato.
+
+**Ref:** `framework/standards/architecture/ddd/complexity-levels.md`
+
+O `domain-architect` analisa a `proposal.md` e responde às seguintes perguntas:
+
+```
+1. A entidade principal tem estados com transições? (Draft → Confirmed → Shipped)
+2. Existem invariants de negócio? ("só cancela se estiver Ativo")
+3. Cálculos derivados existem? (Total, Saldo, Desconto)
+4. Outros módulos precisam reagir a mudanças? (Domain Events com consumidores)
+5. O usuário declarou explicitamente Bounded Context na proposta?
+
+→ Nenhuma acima: Nível 1 (CRUD)
+→ 1-4 verdadeiros: Nível 2 (Business Logic)
+→ 5 verdadeiro OU múltiplos domínios com modelos conflitantes: Nível 3 (BC)
+```
+
+**Documente no spec.md** (seção `## Domain Complexity`) antes de continuar para o Passo 3.
+
+**Template a usar no Passo 4 (contracts-level{N}.cs):**
+
+| Nível | Template |
+|-------|----------|
+| 1 | `code/dotnet/contracts/contracts-level1.cs` |
+| 2 | `code/dotnet/contracts/contracts-level2.cs` |
+| 3 | `code/dotnet/contracts/contracts-level3.cs` |
+
+**Para Nível 2+:** Preencha o `## Aggregate Blueprint` no spec.md antes de gerar contracts-level{N}.cs.
+
+**Para Nível 3:** Adicione `BOUNDED_CONTEXT` como variável ao renderizar o template.
+
+---
+
 ### Passo 2: Analisar Código Existente (CRÍTICO - FAZER ANTES DE CONTRACTS!)
 
-**⚠️ ATENÇÃO:** Este passo é OBRIGATÓRIO antes de gerar `contracts.cs`. Previne geração de DTOs com nomes de campos errados.
+**⚠️ ATENÇÃO:** Este passo é OBRIGATÓRIO antes de gerar `contracts-level{N}.cs`. Previne geração de DTOs com nomes de campos errados.
 
 **Delegate para skill dedicada:**
 
@@ -139,7 +175,7 @@ Se houver recursos Azure:
 
 **SEMPRE usar Bicep para infra!**
 
-### Passo 4: Gerar `contracts.cs` (BASEADO NO SCHEMA REAL!)
+### Passo 4: Gerar `contracts-level{N}.cs` (BASEADO NO SCHEMA REAL!)
 
 **⚠️ IMPORTANTE:** Use `schema-analysis.md` (do Passo 2) para gerar DTOs corretos!
 
@@ -148,7 +184,7 @@ Se houver recursos Azure:
 ```bash
 # Use o template de contracts com dados do schema-analysis.md:
 npx morph-spec template render \
-  code/dotnet/contracts/contracts.cs \
+  code/dotnet/contracts/contracts-level{N}.cs \
   .morph/features/$ARGUMENTS/1-design/contracts.cs \
   '{
     "FEATURE_NAME": "$ARGUMENTS",
@@ -164,7 +200,7 @@ npx morph-spec template render \
 
 ```bash
 # Leia o template base:
-Read: .morph/framework/templates/code/dotnet/contracts/contracts.cs.hbs
+Read: .morph/framework/templates/code/dotnet/contracts/contracts-level{N}.cs.hbs
 
 # Preencha manualmente usando dados de schema-analysis.md
 # Template contém placeholders para:
@@ -268,7 +304,7 @@ Apresente ao usuário 3 ações sugeridas:
 ## Critérios de Avanço
 
 - [x] `spec.md` completo com todos os requisitos
-- [x] `contracts.cs` com interfaces e DTOs
+- [x] `contracts-level{N}.cs` com interfaces e DTOs
 - [x] `decisions.md` com ADRs relevantes
 - [x] Custos estimados e documentados (se houver infra)
 - [x] State atualizado

package/framework/skills/level-1-workflows/phase-tasks/SKILL.md

@@ -73,6 +73,44 @@ npx morph-spec approval get $ARGUMENTS design
 
 ---
 
+### Passo 0: Ler Nível de Domínio
+
+**Ref:** `framework/standards/architecture/ddd/complexity-levels.md`
+
+Antes de quebrar tasks, leia a seção `## Domain Complexity` do spec.md:
+
+```bash
+grep -A15 "## Domain Complexity" ".morph/features/$ARGUMENTS/1-design/spec.md"
+```
+
+> Se a seção não existir no spec.md, assuma **Nível 1 (CRUD)** e documente nos pre-requisitos da task.
+
+Use o nível para **restringir** as categorias de tasks às listadas para o nível detectado:
+
+| Nível | Categorias de Tasks |
+|-------|---------------------|
+| **1 — CRUD** | `domain` (Entity simples) → `infrastructure` (Repository, EF Config) → `application` (Service CRUD) → `presentation` (API/Page) → `tests` |
+| **2 — Business Logic** | `domain` (AggregateRoot, ValueObjects, DomainEvents) → `infrastructure` (Repository, EF Config) → `application` (Commands, Queries, Handlers) → `presentation` (API/Page) → `tests` |
+| **3 — Bounded Context** | `domain-bc` (BC setup, Aggregates, Events) → `infrastructure` (BC repositories, EF) → `application` (Commands, Queries, Integration handlers) → `presentation` → `tests` |
+
+**Nível 1:** Nenhuma task adicional obrigatória — apenas o padrão CRUD nas categorias listadas.
+
+**Tasks adicionais obrigatórias por nível:**
+
+**Nível 2 apenas:**
+- `T{N}: Implementar AggregateRoot {EntityName} com factory method e invariants` (domain)
+- `T{N}: Implementar ValueObjects: {lista do Aggregate Blueprint}` (domain)
+- `T{N}: Implementar DomainEvents: {lista do Aggregate Blueprint}` (domain)
+- `T{N}: Implementar Command Handlers com MediatR` (application)
+- `T{N}: Implementar Query Handlers com read models` (application)
+
+**Nível 3 apenas (além do Nível 2):**
+- `T{N}: Configurar namespace/pasta do Bounded Context {BoundedContext}` (infrastructure)
+- `T{N}: Implementar Integration Events para comunicação cross-BC` (domain-bc)
+- `T{N}: Implementar handlers de Integration Events` (application)
+
+---
+
 ### Passo 1: Analisar Spec
 
 Leia `.morph/features/$ARGUMENTS/1-design/spec.md` e identifique: