@polymorphism-tech/morph-spec 8.37.0 → 8.38.0

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

@@ -5,7 +5,7 @@
 > **Keywords:** component, shadcn, reusable, shared, ui, three-tier
 > **Load When:** creating or editing React components
 
-**Verified against:** Next.js 15 + shadcn/ui CLI + TanStack Table 8. Last-verified: 2026-05-20.
+**Verified against:** Next.js 16 + shadcn 4 CLI (the code blocks typecheck under `tsc --strict`). Last-verified: 2026-09-24.
 
 ---
 
@@ -33,83 +33,62 @@ Tier 3: features/*/components/ ← feature-scoped (knows about users, billing, e
 
 ```bash
 # Add shadcn components via CLI — never write them manually
-npx shadcn@latest add button card dialog form input table
+npx shadcn@latest add button card dialog field input table
 ```
 
 If you need to change a shadcn component's behavior, wrap it — do not edit the source file.
 
 ## Tier 2 — Shared Composed Components
 
+Composes shadcn primitives and knows nothing about the domain.
+
 ```tsx
-// components/data-table.tsx — composes shadcn Table + TanStack Table
-'use client';
-
-import {
-  Table, TableBody, TableCell, TableHead, TableHeader, TableRow
-} from '@/components/ui/table';
-import {
-  type ColumnDef, flexRender, getCoreRowModel, useReactTable
-} from '@tanstack/react-table';
-
-interface DataTableProps<TData> {
-  columns: ColumnDef<TData>[];
-  data: TData[];
+// components/page-header.tsx
+import type { ReactNode } from 'react';
+import { cn } from '@/lib/utils';
+
+interface PageHeaderProps {
+  title: string;
+  description?: string;
+  actions?: ReactNode;
+  className?: string;
 }
 
-export function DataTable<TData>({ columns, data }: DataTableProps<TData>) {
-  const table = useReactTable({ data, columns, getCoreRowModel: getCoreRowModel() });
+export function PageHeader({ title, description, actions, className }: PageHeaderProps) {
   return (
-    <Table>
-      <TableHeader>
-        {table.getHeaderGroups().map((hg) => (
-          <TableRow key={hg.id}>
-            {hg.headers.map((h) => (
-              <TableHead key={h.id}>
-                {flexRender(h.column.columnDef.header, h.getContext())}
-              </TableHead>
-            ))}
-          </TableRow>
-        ))}
-      </TableHeader>
-      <TableBody>
-        {table.getRowModel().rows.map((row) => (
-          <TableRow key={row.id}>
-            {row.getVisibleCells().map((cell) => (
-              <TableCell key={cell.id}>
-                {flexRender(cell.column.columnDef.cell, cell.getContext())}
-              </TableCell>
-            ))}
-          </TableRow>
-        ))}
-      </TableBody>
-    </Table>
+    <div className={cn('flex items-start justify-between gap-4', className)}>
+      <div>
+        <h1 className="text-2xl font-semibold tracking-tight">{title}</h1>
+        {description && <p className="text-sm text-muted-foreground">{description}</p>}
+      </div>
+      {actions && <div className="flex gap-2">{actions}</div>}
+    </div>
   );
 }
 ```
 
+**The shared data table has one home: `admin-app/data-table.md`.** It is the Tier 2 component with the most rules — pagination, sorting and filtering on the server, the three states, selection — so it is specified there, once. Do not write a second `components/data-table.tsx` from this page.
+
 ## Tier 3 — Feature Components
 
 ```tsx
-// features/users/components/user-list.tsx
-'use client';
-
-import { DataTable } from '@/components/data-table';
-import { useUsers } from '@/features/users/hooks/use-users';
-import type { ColumnDef } from '@tanstack/react-table';
-import type { User } from '@/features/users/types/user.types';
-
-const columns: ColumnDef<User>[] = [
-  { accessorKey: 'name', header: 'Name' },
-  { accessorKey: 'email', header: 'Email' },
-];
-
-export function UserList() {
-  const { data: users = [], isLoading } = useUsers();
-  if (isLoading) return <div>Loading...</div>;
-  return <DataTable columns={columns} data={users} />;
+// features/users/components/users-page-header.tsx
+import { PageHeader } from '@/components/page-header';
+import { Button } from '@/components/ui/button';
+
+export function UsersPageHeader({ canInvite }: { canInvite: boolean }) {
+  return (
+    <PageHeader
+      title="Users"
+      description="People with access to this workspace."
+      actions={canInvite ? <Button>Invite user</Button> : null}
+    />
+  );
 }
 ```
 
+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

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

@@ -18,6 +18,7 @@ Server Components for initial page load. TanStack Query for client mutations and
 - 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`)
 
 ## TanStack Query Setup
 

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

@@ -2,20 +2,22 @@
 
 > **Scope:** frontend/nextjs/forms
 > **Layer:** 2 (on keyword)
-> **Keywords:** form, react-hook-form, zod, validation, input, submit, zodResolver
+> **Keywords:** form, react-hook-form, zod, validation, input, submit, zodResolver, Controller, Field, FieldError
 > **Load When:** implementing any form in Next.js
 
-**Verified against:** Next.js 15 + react-hook-form 7 + Zod 4 + @hookform/resolvers 3. Last-verified: 2026-05-20.
+**Verified against:** Next.js 16 + react-hook-form 7 + Zod 4 + @hookform/resolvers 5 + shadcn 4 `Field` (the code blocks typecheck under `tsc --strict`). Last-verified: 2026-09-24.
 
 ---
 
-react-hook-form + Zod + shadcn Form components. Schema defines both validation rules and TypeScript types.
+react-hook-form + Zod + shadcn `Field` components, wired through react-hook-form's `Controller`. The schema defines both the validation rules and the TypeScript types.
+
+**Admin app / CRUD screen?** This is the base pattern; `admin-app/forms.md` adds what a CRUD form needs on top of it — server validation errors on the field, where the form lives (dialog, sheet, page), validation timing and the unsaved-changes guard.
 
 ## Core Rules
 
-- ALWAYS define the Zod schema first — derive the TypeScript type from it with `z.infer<>`
+- ALWAYS define the Zod schema first — derive the TypeScript type from it with `z.infer<>` (or `z.input<>`/`z.output<>` when the schema coerces)
 - ALWAYS use `zodResolver` to connect schema to react-hook-form
-- ALWAYS use shadcn `<Form>`, `<FormField>`, `<FormItem>`, `<FormMessage>` for consistent UI
+- ALWAYS render fields with `Controller` + shadcn `<Field>`, `<FieldLabel>`, `<FieldError>` for consistent UI and accessible errors
 - NEVER use `useState` for form field values — react-hook-form handles this
 - ALWAYS use `useMutation` from TanStack Query for form submission
 
@@ -38,11 +40,9 @@ export type CreateUserInput = z.infer<typeof createUserSchema>;
 // features/users/components/create-user-form.tsx
 'use client';
 
-import { useForm } from 'react-hook-form';
+import { Controller, useForm } from 'react-hook-form';
 import { zodResolver } from '@hookform/resolvers/zod';
-import {
-  Form, FormControl, FormField, FormItem, FormLabel, FormMessage
-} from '@/components/ui/form';
+import { Field, FieldError, FieldGroup, FieldLabel } from '@/components/ui/field';
 import { Input } from '@/components/ui/input';
 import { Button } from '@/components/ui/button';
 import { useCreateUser } from '@/features/users/hooks/use-create-user';
@@ -64,28 +64,28 @@ export function CreateUserForm({ onSuccess }: { onSuccess?: () => void }) {
   }
 
   return (
-    <Form {...form}>
-      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
-        <FormField
-          control={form.control}
+    <form onSubmit={form.handleSubmit(onSubmit)}>
+      <FieldGroup>
+        <Controller
           name="name"
-          render={({ field }) => (
-            <FormItem>
-              <FormLabel>Name</FormLabel>
-              <FormControl><Input placeholder="John Doe" {...field} /></FormControl>
-              <FormMessage />
-            </FormItem>
+          control={form.control}
+          render={({ field, fieldState }) => (
+            <Field data-invalid={fieldState.invalid}>
+              <FieldLabel htmlFor={field.name}>Name</FieldLabel>
+              <Input {...field} id={field.name} aria-invalid={fieldState.invalid} placeholder="John Doe" />
+              {fieldState.invalid && <FieldError errors={[fieldState.error]} />}
+            </Field>
           )}
         />
-        <FormField
-          control={form.control}
+        <Controller
           name="email"
-          render={({ field }) => (
-            <FormItem>
-              <FormLabel>Email</FormLabel>
-              <FormControl><Input type="email" {...field} /></FormControl>
-              <FormMessage />
-            </FormItem>
+          control={form.control}
+          render={({ field, fieldState }) => (
+            <Field data-invalid={fieldState.invalid}>
+              <FieldLabel htmlFor={field.name}>Email</FieldLabel>
+              <Input {...field} id={field.name} type="email" aria-invalid={fieldState.invalid} />
+              {fieldState.invalid && <FieldError errors={[fieldState.error]} />}
+            </Field>
           )}
         />
         {form.formState.errors.root && (
@@ -94,8 +94,8 @@ export function CreateUserForm({ onSuccess }: { onSuccess?: () => void }) {
         <Button type="submit" disabled={isPending}>
           {isPending ? 'Creating...' : 'Create User'}
         </Button>
-      </form>
-    </Form>
+      </FieldGroup>
+    </form>
   );
 }
 ```
@@ -123,11 +123,12 @@ export const updateUserSchema = createUserSchema.partial();
 | Wrong | Right | Why |
 |-------|-------|-----|
 | `useState` for each field | `useForm` | Unnecessary re-renders on every keystroke |
-| Manual error display | `<FormMessage />` | Consistent UI, auto-connects to field errors |
+| Manual error display | `<FieldError errors={[fieldState.error]} />` | Consistent UI, wired to the field's own error |
 | `fetch` in submit handler | `useMutation` | Loading state, error handling, cache invalidation |
 | Type written manually | `z.infer<typeof schema>` | Single source of truth |
 | `z.string().email()` | `z.email()` | Zod 4 moved format checks to top-level functions |
 | `{ required_error: '...' }` | `{ error: '...' }` | Zod 4 unified error customization on one `error` param |
+| Legacy shadcn `<Form>`/`<FormField>`/`<FormMessage>` in a new screen | `Controller` + `<Field>`/`<FieldError>` | shadcn's forms docs are written around `Field`; a screen still on the legacy wrapper is migrated when it is next touched, never extended |
 
 ---
 

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

@@ -14,7 +14,8 @@ Server state (API data) lives in TanStack Query. UI state lives in React. No glo
 ## Core Rules
 
 - ALWAYS use TanStack Query for anything that comes from the .NET API
-- ALWAYS use `useState` for local UI state (modal open, selected tab, form step)
+- 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
 - 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

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

@@ -101,6 +101,24 @@ export function QueryClientWrapper({ children }: { children: React.ReactNode })
 }
 ```
 
+## Test Budget
+
+The plan (`morph-plan`) gives each task a budget: **one test per postcondition, plus one
+regression test per bug fixed**. Going above it takes a one-line justification in the task. The
+happy path + one error path per component above is that budget applied to a component.
+
+- **Table before copy.** Scenarios of the same behavior — edge cases included — are rows of one
+  `it.each`/`test.each`, never N `it()` blocks that differ by one value.
+- **No test that only pins text.** Finding an element by its text to assert what the user can do
+  is fine; a test whose only assertion is the presence or absence of a copy string (a dash, a
+  word, a tenant name) proves the file's version, not behavior. That rule belongs in a lint rule or
+  a publish-time validation, outside the suite count.
+- **Shared helpers by default.** Reuse the existing wrappers (`test/helpers.tsx`), MSW handlers and
+  factories. Before writing a new one, look for it (`morph-spec graph explain <Name>`; fallback
+  without a graph: `grep -rn`).
+- **TDD where it pays:** a bug gets its regression test first, and so does pure logic (formatters,
+  reducers, schema). Component and integration tests may come after the code.
+
 ## Common Mistakes
 
 | Wrong | Right | Why |

package/framework/templates/context/design-system.md

@@ -2,7 +2,7 @@
 
 > **Template** — copy to `.morph/context/design-system.md` and fill in sections marked `/* CUSTOMIZE */`.
 
-Living document. All agents read this before any UI work. All design decisions land here.
+Living document. All agents read this before any UI work. All design decisions land here — **rewritten in place, never stacked**: a decision that changes rewrites the section that described the old one (a value that still holds somewhere says where), so an agent reading only the body gets today's answer.
 
 ---
 
@@ -332,8 +332,8 @@ Choose patterns based on the project domain:
 
 ## Changelog
 
-> Living record — every agent that adds tokens or design decisions registers here.
-> Format: `- YYYY-MM-DD [agent-id] Description of addition/change`
+> When and why the body changed — never the new value itself: that lives in the section it rewrote.
+> Format: `- YYYY-MM-DD [agent-id] reason (section rewritten)`
 
 <!-- Entries below this line, newest first -->
 

package/framework/templates/docs/proposal.md

@@ -136,6 +136,17 @@ How will we know this feature is successful?
 
 ---
 
+## Conflitos com o acervo
+
+UCs (`.morph/specs/usecases/`), ADRs ativos (`.morph/specs/adrs/`) and `.morph/context/*.md` that
+this request contradicts. `Nenhum conflito encontrado.` when there is none — the section is always present.
+
+| Fonte | O que diz hoje | O que o pedido muda | Decisão |
+|-------|----------------|---------------------|---------|
+| {UC-133} | {Public Sans + Lora em toda a interface} | {admin passa a Geist} | {vale o novo no admin; a vitrine mantém o antigo — decisions.md ADR-001} |
+
+---
+
 ## Dependencies
 
 - [ ] {Dependency 1} - {status}

package/framework/templates/docs/spec.md

@@ -204,6 +204,21 @@ public interface I{{pascalCase FEATURE_NAME}}Service
 
 ---
 
+## UCs e ADRs que esta feature altera ou revoga
+
+> Read by `morph-spec finish`: in the archive commit, each row marks the project acervo — a UC turns
+> `status: superseded` + `superseded_by` (+ `scope` when partial); an ADR leaves `.morph/specs/adrs/`
+> (total) or keeps its file with the scope where it still holds (partial). Columns are positional.
+> `morph-spec usecase check {feature}` reports a bad row while this file can still change (it freezes at Gate 2).
+> Nothing revoked → replace the table with `Nenhum.`
+
+| Id | Mudança | Substituto | Escopo em que o antigo ainda vale |
+|----|---------|------------|-----------------------------------|
+| UC-{nn} | parcial | UC-{nn} | {where the old one still holds} |
+| {feature}/ADR-{nnn} | total | — | — |
+
+---
+
 ## Security
 
 | Action | Required Policy |

package/framework/templates/docs/ui-mockups.md

@@ -1,98 +1,115 @@
-# UI Mockups & Wireframes: {{titleCase FEATURE_NAME}}
-
-| Field | Value |
-|-------|-------|
-| **Feature** | {{FEATURE_NAME}} |
-| **Created** | {{DATE}} |
-
----
-
-## Screen Inventory
-
-| Screen ID | Name | Route | Priority |
-|-----------|------|-------|----------|
-| **S001** | {Screen Name} | /path | High |
-| **S002** | {Screen Name} | /path | Medium |
-
----
-
-## S001: {Primary Screen}
-
-### Desktop Layout
-
-```
-┌─────────────────────────────────────┐
-│  Header                    [User ▼] │
-├─────────────────────────────────────┤
-│                                     │
-│  [Title]                            │
-│                                     │
-│  ┌──────────────────────────────┐  │
-│  │ Main Content Area            │  │
-│  │                              │  │
-│  │  [Card 1]    [Card 2]        │  │
-│  │                              │  │
-│  │  ┌────────────────────────┐  │  │
-│  │  │ Data Table             │  │  │
-│  │  │ ...                    │  │  │
-│  │  └────────────────────────┘  │  │
-│  └──────────────────────────────┘  │
-│                                     │
-└─────────────────────────────────────┘
-```
-
-### Mobile Layout
-
-```
-┌──────────────────────┐
-│ ☰  Title    [User ▼]│
-├──────────────────────┤
-│                      │
-│ [Card 1]             │
-│                      │
-│ [Card 2]             │
-│                      │
-│ [View All Items]     │
-│                      │
-└──────────────────────┘
-```
-
----
-
-## States
-
-### Loading
-- Show skeleton placeholders
-- Spinner for primary content
-
-### Empty
-- Icon + message
-- Clear call-to-action button
-
-### Error
-- Warning icon
-- User-friendly message
-- Retry button
-
-### Success (After Action)
-- Toast notification
-- Auto-dismiss after 3s
-
----
-
-## Interactions
-
-- **Hover**: Subtle elevation increase
-- **Click**: Scale down (0.98)
-- **Transitions**: Fade-in 200ms
-
----
-
-## Accessibility
-- [ ] 44x44px minimum touch targets
-- [ ] Focus indicators visible
-- [ ] Proper heading hierarchy (H1 → H2 → H3)
-
----
-
-*Generated with MORPH Framework*
+# UI Mockups & Wireframes: {{titleCase FEATURE_NAME}}
+
+| Field | Value |
+|-------|-------|
+| **Feature** | {{FEATURE_NAME}} |
+| **Created** | {{DATE}} |
+
+---
+
+## Screen Inventory
+
+| Screen ID | Name | Route | Priority |
+|-----------|------|-------|----------|
+| **S001** | {Screen Name} | /path | High |
+| **S002** | {Screen Name} | /path | Medium |
+
+---
+
+## Tela: {Primary Screen}
+
+### Desktop Layout
+
+```
+┌─────────────────────────────────────┐
+│  Header                    [User ▼] │
+├─────────────────────────────────────┤
+│                                     │
+│  [Title]                            │
+│                                     │
+│  ┌──────────────────────────────┐  │
+│  │ Main Content Area            │  │
+│  │                              │  │
+│  │  [Card 1]    [Card 2]        │  │
+│  │                              │  │
+│  │  ┌────────────────────────┐  │  │
+│  │  │ Data Table             │  │  │
+│  │  │ ...                    │  │  │
+│  │  └────────────────────────┘  │  │
+│  └──────────────────────────────┘  │
+│                                     │
+└─────────────────────────────────────┘
+```
+
+### Mobile Layout
+
+```
+┌──────────────────────┐
+│ ☰  Title    [User ▼]│
+├──────────────────────┤
+│                      │
+│ [Card 1]             │
+│                      │
+│ [Card 2]             │
+│                      │
+│ [View All Items]     │
+│                      │
+└──────────────────────┘
+```
+
+### Checklist de tela
+
+Troque cada `…` pela decisão — "não se aplica" vale se escrito; `…`, vazio ou "a definir" reprovam o Gate uiux.
+
+| Item | Decisão |
+|---|---|
+| Superfície | … |
+| Volume esperado | … |
+| Paginação | … |
+| Ordenação | … |
+| Filtro | … |
+| Estado vazio | … |
+| Estado carregando | … |
+| Estado de erro | … |
+| Mobile | … |
+| Abas | … |
+
+---
+
+## States
+
+### Loading
+- Show skeleton placeholders
+- Spinner for primary content
+
+### Empty
+- Icon + message
+- Clear call-to-action button
+
+### Error
+- Warning icon
+- User-friendly message
+- Retry button
+
+### Success (After Action)
+- Toast notification
+- Auto-dismiss after 3s
+
+---
+
+## Interactions
+
+- **Hover**: Subtle elevation increase
+- **Click**: Scale down (0.98)
+- **Transitions**: Fade-in 200ms
+
+---
+
+## Accessibility
+- [ ] 44x44px minimum touch targets
+- [ ] Focus indicators visible
+- [ ] Proper heading hierarchy (H1 → H2 → H3)
+
+---
+
+*Generated with MORPH Framework*

package/framework/templates/dotnet/ai-kit/src/Morph.AiKit/Rag/DeltaPlan.cs

@@ -5,12 +5,18 @@ namespace Morph.AiKit.Rag;
 /// </summary>
 /// <remarks>
 /// <para>
-/// <b>O defeito que este tipo existe para matar</b> e concreto e esta em producao: a base de
-/// conhecimento do GHLBrain <b>apaga tudo e re-embeda tudo</b> a cada ingestao. O custo e
-/// pago em embedding de documento que nao mudou, e a janela entre o apagar e o gravar e uma
-/// janela em que a busca nao acha nada. Um plano em quatro baldes torna visivel o que a
-/// ingestao inteira escondia: quase sempre <see cref="Unchanged"/> e a lista grande e as
-/// outras tres sao curtas.
+/// <b>O defeito que este tipo existe para matar</b> e o apaga-e-regrava: a base de
+/// conhecimento do GHLBrain <b>apaga e re-embeda o documento inteiro</b> a cada ingestao,
+/// mudou ou nao. O custo e pago em embedding de trecho que nao mudou e em latencia (uma
+/// chamada de embedding por item no reindex em massa). Um plano em quatro baldes torna
+/// visivel o que a ingestao inteira escondia: quase sempre <see cref="Unchanged"/> e a lista
+/// grande e as outras tres sao curtas.
+/// </para>
+/// <para>
+/// Errata (2026-09-15, Morph.GHLBrain#96): a versao anterior deste comentario citava tambem
+/// uma janela entre o apagar e o gravar em que a busca nao acha nada. No GHLBrain o apagar e
+/// o gravar ja rodam numa transacao so, com o embedding antes dela, entao essa janela nao
+/// existe la. Ela existe em quem apaga fora da transacao que grava.
 /// </para>
 /// <para>
 /// <b>E um plano, nao uma execucao.</b> Nada aqui toca banco, vetor ou arquivo: quem aplica