@polymorphism-tech/morph-spec 8.37.0 → 8.38.0

package/framework/standards/STANDARDS.json

@@ -1541,13 +1541,17 @@
         "fake clock",
         "integration test",
         "ProblemDetails",
-        "error body assertion"
+        "error body assertion",
+        "test budget",
+        "orçamento de teste",
+        "[Theory] table"
       ],
       "anchors": {
         "clock": "#rule-1--inject-timeprovider-fake-it-with-faketimeprovider-in-tests",
-        "errorbody": "#rule-2--error-path-tests-assert-the-response-body-not-just-the-status-code"
+        "errorbody": "#rule-2--error-path-tests-assert-the-response-body-not-just-the-status-code",
+        "test-budget": "#test-budget"
       },
-      "digest": "Inject TimeProvider (never DateTime.UtcNow / DateOnly.FromDateTime(DateTime.UtcNow) directly in a handler or validator) and fake it with FakeTimeProvider (Microsoft.Extensions.TimeProvider.Testing) in integration tests — deterministic, no midnight-UTC flake, boundary dates (today vs. yesterday) become facts about the fake clock instead of when the suite happens to run. xUnit + WebApplicationFactory error-path tests (400/404/409) must assert the ProblemDetails response BODY (title/detail/violated field or error code), never just the HTTP status code — a status-only assertion lets the wrong validation rule or the wrong error branch pass silently as long as the status matches.",
+      "digest": "Inject TimeProvider (never DateTime.UtcNow / DateOnly.FromDateTime(DateTime.UtcNow) directly in a handler or validator) and fake it with FakeTimeProvider (Microsoft.Extensions.TimeProvider.Testing) in integration tests — deterministic, no midnight-UTC flake, boundary dates (today vs. yesterday) become facts about the fake clock instead of when the suite happens to run. xUnit + WebApplicationFactory error-path tests (400/404/409) must assert the ProblemDetails response BODY (title/detail/violated field or error code), never just the HTTP status code — a status-only assertion lets the wrong validation rule or the wrong error branch pass silently as long as the status matches. Test budget per task: one test per postcondition plus one regression test per bug, more only with a one-line justification in the task; scenarios of the same behavior (edge cases included) are rows of one [Theory], never copied [Fact]s; no test whose only assertion is a copy, config or prose string (that is an analyzer or a publish-time validation, outside the suite count); shared fixtures before new helpers; TDD for bugs (regression first) and pure logic; a surviving mutant is killed by tightening an assertion or adding a row, not by a new test.",
       "verifiedAgainst": ".NET 10 + xUnit 2 + `Microsoft.Extensions.TimeProvider.Testing`.",
       "provedBy": []
     },
@@ -2136,8 +2140,8 @@
         "patterns": "#three-tier-hierarchy",
         "shadcn": "#tier-1--shadcnui-primitives"
       },
-      "digest": "Server Components for data fetching and static content. Client Components for interactivity. shadcn/ui components are copy-paste — customize in src/components/ui/. Never use index.tsx for named exports. One component per file. Avoid prop drilling — use composition or Context API.",
-      "verifiedAgainst": "Next.js 15 + shadcn/ui CLI + TanStack Table 8.",
+      "digest": "Three tiers: components/ui is shadcn CLI output (never edit, wrap instead); components/ composes primitives with no domain knowledge; features/*/components knows the domain. 'use client' only for hooks, events or browser APIs; never pass raw API data as props — type and validate it first. The shared data table is specified once, in admin-app/data-table.md.",
+      "verifiedAgainst": "Next.js 16 + shadcn 4 CLI (the code blocks typecheck under `tsc --strict`).",
       "provedBy": []
     },
     {
@@ -2185,15 +2189,15 @@
         "react-hook-form",
         "Zod",
         "form validation",
-        "Server Actions forms",
-        "useFormState"
+        "shadcn Field",
+        "Controller"
       ],
       "anchors": {
         "validation": "#schema-composition",
         "submission": "#complete-form-pattern"
       },
-      "digest": "react-hook-form with Zod resolver for client forms. Define Zod schema before component. Server Actions for mutations: 'use server' directive. Use useFormState/useActionState for Server Action feedback. Never submit to API routes — use Server Actions or React Query mutations. Display field-level errors from Zod.",
-      "verifiedAgainst": "Next.js 15 + react-hook-form 7 + Zod 4 + @hookform/resolvers 3.",
+      "digest": "react-hook-form + Zod + shadcn Field components wired through Controller. Define the Zod schema first and derive the type with z.infer (z.input/z.output when it coerces); zodResolver connects it; Field/FieldLabel/FieldError render each field and its error; never useState per field; submit through TanStack Query useMutation and put a failed submit on root. Edit forms reuse the create schema (.partial()). Zod 4: z.email(), a single `error` param. A legacy shadcn Form/FormField screen is migrated when touched, never extended. Admin CRUD forms add the deltas of admin-app/forms.md.",
+      "verifiedAgainst": "Next.js 16 + react-hook-form 7 + Zod 4 + @hookform/resolvers 5 + shadcn 4 `Field` (the code blocks typecheck under `tsc --strict`).",
       "provedBy": []
     },
     {
@@ -2357,13 +2361,17 @@
         "testing-library",
         "Playwright",
         "Next.js testing",
-        "component tests"
+        "component tests",
+        "test budget",
+        "orçamento de teste",
+        "it.each table"
       ],
       "anchors": {
         "unit": "#component-test-pattern",
-        "e2e": "#test-file-co-location"
+        "e2e": "#test-file-co-location",
+        "test-budget": "#test-budget"
       },
-      "digest": "Vitest for unit tests, React Testing Library for component tests. Mock next/navigation with vi.mock. Test Server Actions with direct function calls. Use MSW for API mocking in component tests. Playwright for E2E tests against running app. Never test implementation details — test user behavior and output.",
+      "digest": "Vitest for unit tests, React Testing Library for component tests. Mock next/navigation with vi.mock. Test Server Actions with direct function calls. Use MSW for API mocking in component tests. Playwright for E2E tests against running app. Never test implementation details — test user behavior and output. Test budget per task: one test per postcondition plus one regression test per bug, more only with a one-line justification in the task; scenarios of the same behavior are rows of one it.each, never copied it() blocks; no test whose only assertion is a copy string (lint or publish-time validation instead); shared wrappers, MSW handlers and factories before new helpers; TDD for bugs and pure logic, component tests may come after the code.",
       "verifiedAgainst": "Vitest 3 + React Testing Library 16 + MSW 2.",
       "provedBy": []
     },
@@ -2684,6 +2692,165 @@
       "digest": "MCP tools extend Claude with external data and actions. Tools are synchronous request-response with typed inputSchema. Resources provide read-only data access. Prompts are reusable templates. Register MCP servers in .claude/settings.json. Prefer @context7 for live library docs. Test tools with MCP Inspector before integrating.",
       "verifiedAgainst": "Claude Code MCP tooling — context7, Playwright; GitHub via `gh` CLI; Neon via `neonctl`.",
       "provedBy": []
+    },
+    {
+      "id": "frontend-admin-app-data-table",
+      "name": "data table",
+      "path": "frontend/admin-app/data-table.md",
+      "category": "frontend",
+      "subcategory": "admin-app",
+      "tags": [
+        "frontend",
+        "admin-app"
+      ],
+      "stacks": [
+        "nextjs"
+      ],
+      "aliases": [
+        "data table",
+        "admin list",
+        "server-side pagination",
+        "paginação",
+        "tabela de dados",
+        "ordenação no servidor",
+        "empty state",
+        "row selection",
+        "bulk actions",
+        "manualPagination"
+      ],
+      "anchors": {
+        "contract": "#the-list-contract-url-and-api",
+        "table": "#the-shared-datatable-tier-2",
+        "states": "#the-three-states",
+        "mobile": "#mobile"
+      },
+      "digest": "Every admin list is paged, sorted and filtered on the server, with page/pageSize/sort/dir/filters in the URL (searchParams parsed by a Zod schema with .catch defaults) and the API answering { items, totalCount } over an OrderBy plus a unique id tiebreaker. The Server Component page reads searchParams and wraps the results in a Suspense keyed by the query; one shared components/data-table.tsx on TanStack Table 9 sets manualPagination + rowCount, manualSorting and selection by a stable getRowId, and only writes the URL (router.replace with scroll:false, page reset on any filter/sort change). Three non-happy states always: loading skeleton, empty (no records vs no match for the filters), error as a value with retry via router.refresh(). Compact density, right-aligned tabular numbers, one inline row action plus a menu, a bulk bar over the selected page, a card list below md. Never 'first N + see all' instead of paging.",
+      "verifiedAgainst": "Next.js 16 App Router + @tanstack/react-table 9 + Zod 4 + shadcn 4 (the code blocks typecheck under `tsc --strict`).",
+      "provedBy": []
+    },
+    {
+      "id": "frontend-admin-app-feedback",
+      "name": "feedback",
+      "path": "frontend/admin-app/feedback.md",
+      "category": "frontend",
+      "subcategory": "admin-app",
+      "tags": [
+        "frontend",
+        "admin-app"
+      ],
+      "stacks": [
+        "nextjs"
+      ],
+      "aliases": [
+        "confirmation dialog",
+        "confirm dialog",
+        "delete confirmation",
+        "toast",
+        "sonner",
+        "toast messages",
+        "undo toast",
+        "diálogo de confirmação"
+      ],
+      "anchors": {
+        "when": "#when-to-confirm",
+        "dialog": "#the-confirmation-dialog-tier-2",
+        "catalog": "#the-toast-catalog"
+      },
+      "digest": "One ConfirmDialog (controlled shadcn AlertDialog, a plain Button that awaits the action, stays open showing the error on failure, optional type-to-confirm) used only for destructive-irreversible, bulk or discard-changes actions; a reversible action gets a 'Desfazer' toast instead. The title names the object and the confirm label repeats the verb. Every toast string comes from a catalog (lib/toast-messages.ts for generic outcomes + per-entity EntityMessages, because Portuguese agrees in gender and number); sonner toast.success/toast.error with an id per action, a longer duration for errors, errors mapped by status (403, 409, network), never the server's raw text, and field validation never in a toast.",
+      "verifiedAgainst": "shadcn 4 `AlertDialog` (Radix) + sonner 2 + TanStack Query 5 (the code blocks typecheck under `tsc --strict`).",
+      "provedBy": []
+    },
+    {
+      "id": "frontend-admin-app-forms",
+      "name": "forms",
+      "path": "frontend/admin-app/forms.md",
+      "category": "frontend",
+      "subcategory": "admin-app",
+      "tags": [
+        "frontend",
+        "admin-app"
+      ],
+      "stacks": [
+        "nextjs"
+      ],
+      "aliases": [
+        "admin form",
+        "crud form",
+        "server validation errors",
+        "ValidationProblemDetails",
+        "unsaved changes",
+        "formulário"
+      ],
+      "anchors": {
+        "server-errors": "#server-errors-on-the-field",
+        "placement": "#where-the-form-lives",
+        "dirty": "#unsaved-changes"
+      },
+      "digest": "Admin forms use the one pattern of nextjs/forms.md (Zod schema, zodResolver, react-hook-form Controller + shadcn Field/FieldError, useMutation) plus the CRUD deltas: map .NET ValidationProblemDetails errors onto their fields with setError (unmatched ones go to root.serverError), mode 'onTouched', submit disabled only while saving, form.reset(values) after a successful save, a guard for unsaved changes, the three useForm generics (z.input / unknown / z.output) when the schema coerces, and placement by size: dialog up to 4 fields, sheet or page up to 12, its own page beyond that, a wizard when steps depend on each other.",
+      "verifiedAgainst": "react-hook-form 7 + @hookform/resolvers 5 + Zod 4 + TanStack Query 5 + shadcn 4 `Field` (the code blocks typecheck under `tsc --strict`).",
+      "provedBy": []
+    },
+    {
+      "id": "frontend-admin-app-page-structure",
+      "name": "page structure",
+      "path": "frontend/admin-app/page-structure.md",
+      "category": "frontend",
+      "subcategory": "admin-app",
+      "tags": [
+        "frontend",
+        "admin-app"
+      ],
+      "stacks": [
+        "nextjs"
+      ],
+      "aliases": [
+        "tabs",
+        "abas",
+        "long page",
+        "página longa",
+        "wizard",
+        "multi-step form",
+        "stepper",
+        "detail page"
+      ],
+      "anchors": {
+        "decision": "#tabs-long-page-or-wizard",
+        "tabs": "#tabs-in-the-url",
+        "wizard": "#wizard-for-long-flows"
+      },
+      "digest": "Decide per screen and write it in the mockup checklist: tabs for 3+ independent sections, a long page with sticky section nav when sections are read together or share one save, a plain page for 2 short blocks, a wizard when later fields depend on earlier answers. The active tab lives in ?tab= and only its content is rendered and fetched on the server; switching tab drops the list params of the tab being left. Unbounded related lists get their own paged tab, never a capped preview. A wizard keeps one react-hook-form across steps, validates each step with trigger(stepFields), never loses data going back, and commits on a final review step.",
+      "verifiedAgainst": "Next.js 16 App Router + shadcn 4 `Tabs` (Radix) + react-hook-form 7 + Zod 4 (the code blocks typecheck under `tsc --strict`).",
+      "provedBy": []
+    },
+    {
+      "id": "architecture-code-comments",
+      "name": "code comments",
+      "path": "architecture/code-comments.md",
+      "category": "architecture",
+      "subcategory": null,
+      "tags": [
+        "architecture",
+        "comments"
+      ],
+      "stacks": [
+        "*"
+      ],
+      "aliases": [
+        "code comments",
+        "comentário de código",
+        "comment policy",
+        "política de comentário",
+        "comentário de processo",
+        "self-documenting code"
+      ],
+      "anchors": {
+        "comment-policy": "#o-que-merece-comentário",
+        "not-worth": "#o-que-não-merece",
+        "size": "#tamanho"
+      },
+      "digest": "Comment only the WHY the code cannot show: an invariant the type does not express, an order that matters, an external quirk (third-party API, library bug with its link), a public API contract. Never process history: task, UC, ADR, FR, Gate, evaluator, spec.md and mockup belong in the commit message and decisions.md. Do not restate the code (a good name replaces the comment), do not describe the world outside the file (it goes stale), and turn claims about behavior into test assertions. Ceiling ~3 lines; longer needs a reason. The verify validators node (code-budget) warns with the count of added comment lines that cite process.",
+      "verifiedAgainst": "C#, TypeScript e JavaScript (convenção de linguagem, sem pacote externo).",
+      "provedBy": []
     }
   ],
   "sharedAliases": {
@@ -2767,6 +2934,14 @@
     "seedance": [
       "ai-agents-media-video",
       "frontend-design-system-ai-video-generation"
+    ],
+    "test budget": [
+      "backend-dotnet-testing",
+      "frontend-nextjs-testing"
+    ],
+    "orçamento de teste": [
+      "backend-dotnet-testing",
+      "frontend-nextjs-testing"
     ]
   }
 }

package/framework/standards/ai-agents/rag-custom-pgvector.md

@@ -188,7 +188,10 @@ The agent decides autonomously when to call `VectorSearchTool.SearchAsync`. It r
 
 ## Ingestão delta por lookup-key
 
-**O defeito que esta seção existe para matar está em produção e foi medido.** `KbStore.IngestAsync` do GHLBrain faz `DELETE … WHERE location_id AND source` e re-insere/re-embeda **tudo** numa transação (`docs/specs/elevacao-9/brutos/scan-ghlbrain.md:412`): 288 itens re-embedados a cada republish do catálogo, e uma **janela** entre o apagar e o gravar em que a busca não acha nada.
+**O defeito que esta seção existe para matar é o apaga-e-regrava.** `KbStore.IngestAsync` do GHLBrain faz `DELETE … WHERE location_id AND source` e re-insere/re-embeda **tudo** do `source` a cada ingestão, mudou ou não (`docs/specs/elevacao-9/brutos/scan-ghlbrain.md:412`): 288 fichas re-embedadas, uma chamada de embedding por item, a cada reindex em massa do catálogo — e, com id posicional, inserir um trecho no topo de um documento torna "novos" todos os de baixo.
+
+> [!warning] Errata (2026-09-15, medida no código e no Neon de produção — Morph.GHLBrain#96)
+> A versão anterior deste parágrafo afirmava também uma **janela** entre o apagar e o gravar em que a busca não acha nada. **No GHLBrain ela não existe:** `ConvVectorSql.ExecuteAsync` roda o `DELETE` e os `INSERT`s numa transação só, e o embedding acontece **antes** de a transação abrir — em READ COMMITTED o leitor vê o conteúdo antigo até o commit. O custo medido também é pequeno (324 trechos, ~US$ 0,0005 por re-embed completo, 1 trecho por `source`): lá, o ganho real do delta é **latência** (o reindex em massa) e **prevenção** (documento de até ~70 trechos). A janela é real em quem apaga fora da transação que grava — é o caso que a regra 4 abaixo cobre.
 
 ### O contrato — uma função pura, sem I/O
 
@@ -220,7 +223,8 @@ public sealed record DeltaPlan<T>(
 1. **`Unchanged` não é re-embedado.** É a economia inteira. Num republish típico a lista grande é `Unchanged` e as outras três são curtas — e é exatamente isso que a ingestão anterior escondia.
 2. **`Removed` são as chaves presentes no acervo e ausentes do `incoming`.** Sem esse balde, conteúdo apagado na origem continua sendo devolvido pela busca.
 3. **O id continua determinístico** — `DeterministicUuid.V5(namespace, "{loc}:{source}:{idx}")` já é a prática — para que `Updated` seja **upsert**, não delete+insert. Delete+insert quebra referências e troca o id de um chunk que só mudou de texto.
-4. **Sem janela vazia: nunca apague tudo antes de gravar.** É literalmente o que faz a busca devolver vazio durante a reingestão. Aplique `Added`/`Updated` primeiro e só então `Removed`, dentro da mesma transação.
+   **Ressalva medida (Morph.GHLBrain#96, ADR-2 da `delta-ingestion`):** quando o item é um *trecho* de documento, a posição como lookup-key derrota a regra 1 — inserir um trecho no topo desloca os índices e marca todo trecho abaixo como `Updated`, re-embedando tudo. Ali a chave certa é o **hash do conteúdo** (`lookupKey` e `contentHash` recebem o mesmo delegado): `Updated` fica vazio por construção, editar um trecho vira `Added` + `Removed`, e trechos idênticos são deduplicados antes do `Plan` para a chave duplicada nunca disparar. A chave posicional continua certa quando o item tem identidade própria (uma ficha por produto, um documento inteiro).
+4. **Sem janela vazia: nunca apague antes de gravar fora da transação que grava.** Apagar e gravar em transações separadas (ou sem transação) é o que faz a busca devolver vazio durante a reingestão. Aplique `Added`/`Updated` primeiro e só então `Removed`, dentro da mesma transação — com a transação a janela já não existe, e a ordem mantém o código correto se um dia ela for partida.
 
 ### Chave duplicada no `incoming` é erro de entrada
 
@@ -308,4 +312,4 @@ ALTER TABLE kb_embeddings ENABLE ROW LEVEL SECURITY;
 
 ---
 
-*MORPH-SPEC by Polymorphism Tech — ai-agents/rag-custom-pgvector.md v2.0 (2026-09-08)*
+*MORPH-SPEC by Polymorphism Tech — ai-agents/rag-custom-pgvector.md v2.1 (2026-09-15 — errata da janela no GHLBrain; ressalva da chave por hash)*

package/framework/standards/ai-agents/testing-ai.md

@@ -12,7 +12,8 @@
 ## Fronteira com o testing genérico
 
 `backend-dotnet-testing` continua dono do que é de teste em .NET: xUnit, `FakeTimeProvider`,
-isolamento entre casos, nomes de teste, organização de fixtures. **Nada disso se repete aqui.**
+isolamento entre casos, nomes de teste, organização de fixtures e o orçamento de teste por task.
+**Nada disso se repete aqui.**
 
 Este standard cobre **só o que é de agente** — e o que é de agente cabe em uma frase: o único ponto
 em que o seu código toca um provider é um `IChatClient`. Todo o resto deste arquivo é consequência

package/framework/standards/architecture/code-comments.md

@@ -0,0 +1,64 @@
+# Comentários no código
+
+> **Scope:** universal
+> **Layer:** 0 (always load)
+> **Keywords:** comentário, comentario, comment, docstring, jsdoc, xml doc, história da task, código autoexplicativo
+> **Load When:** escrevendo ou revisando código em qualquer stack
+
+**Verified against:** C#, TypeScript e JavaScript (convenção de linguagem, sem pacote externo). Last-verified: 2026-09-24.
+
+---
+
+Comentário é relido a cada leitura do arquivo, por quem mantém e pelo agente que abre o arquivo na
+próxima task. Ele só se paga quando diz o que o código **não consegue** dizer.
+
+## O que merece comentário
+
+Só o **porquê que o código não mostra**:
+
+| Merece | Exemplo |
+|---|---|
+| Invariante que o tipo não expressa | "a chave é a identidade e o hash é a versão" |
+| Ordem que importa | "invalidar o cache ANTES de publicar: o consumidor relê na hora" |
+| Peculiaridade externa | API de terceiro que devolve 200 com erro no corpo; bug de biblioteca, com o link |
+| Contrato de API pública | `///` ou JSDoc no membro público: o que recebe, devolve e lança |
+
+## O que não merece
+
+- **História de processo.** Task, UC, ADR, FR, Gate, avaliador, `spec.md`, mockup, "confirmado ao
+  implementar a T11", "o Gate 3 pediu". Isso vai na mensagem de commit e no `decisions.md`, onde tem
+  data e autor e não envelhece dentro do arquivo.
+- **Repetição do código.** `// incrementa o contador` sobre `count++`. Nome bom substitui
+  comentário: extraia `isEligibleForRefund()` em vez de comentar a condição.
+- **Estado do mundo fora do arquivo.** "Public Sans é a fonte da interface" passa a mentir na
+  primeira troca de fonte, e nada avisa.
+- **Afirmação sobre comportamento.** "nunca retorna vazio", "ordenado por sobrenome": isso é
+  asserção de teste. A prosa não falha quando deixa de ser verdade; o teste falha.
+
+## Tamanho
+
+Teto de ~3 linhas. Acima disso o comentário justifica o volume (algoritmo não óbvio, armadilha de
+terceiro com a reprodução). Bloco longo narrando decisões é `decisions.md` com outro nome.
+
+## Exemplo
+
+```ts
+// Ruim: conta a task, repete o código e afirma comportamento que nenhum teste cobra.
+// T8 + T11: mutação obrigatória do relatório, item c. Confirmado ao implementar a T11.
+// Faz upsert do documento com chave e hash e nunca duplica.
+await upsert({ key: doc.sourceId, hash: sha256(doc.body) });
+
+// Bom: o porquê que o código não mostra.
+// A chave é a identidade e o hash é a versão: hash novo na mesma chave substitui.
+await upsert({ key: doc.sourceId, hash: sha256(doc.body) });
+```
+
+## Na revisão
+
+Comentário de processo é achado da rubrica `code-quality` no Gate 3. O nó `validators` do
+`morph-spec verify` mede, nas linhas que a feature adicionou, quantas linhas de comentário citam
+processo (validador `code-budget`) e avisa com o número.
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

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

@@ -113,6 +113,28 @@ respectively and the test suite stays green.
 
 ---
 
+## 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.
+
+- **Table before copy.** Scenarios of the same behavior — including its edge cases (null, empty,
+  boundary) — are rows of one `[Theory]` (`[InlineData]`/`[MemberData]`), never N `[Fact]` methods
+  that differ by one value.
+- **No test that only pins text.** An assertion that is only the presence or absence of a string in
+  UI copy, tenant config or prose proves the file's version, not behavior. Enforce it with an
+  analyzer, a lint rule or a validation at publish time, outside the suite count. The versioned
+  prompt case (at most one structural test) is `ai-agents-testing-ai`.
+- **Shared fixture by default.** Reuse the project's `WebApplicationFactory` fixture, fakes and
+  builders. Before writing a new helper, look for the existing one (`morph-spec graph explain
+  <Name>`; fallback without a graph: `grep -rn`).
+- **TDD where it pays:** a bug gets its regression test first (red, then the fix), and so does pure
+  logic. Integration and endpoint tests may come after the code.
+- **A surviving mutant** of the Gate 3 mutation proof is killed by tightening an existing assertion
+  or adding a table row, not by one new test per mutant.
+
+---
+
 ## Anti-Patterns
 
 | Do NOT | Do Instead |