@polymorphism-tech/morph-spec 8.34.2 → 8.35.0

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

@@ -0,0 +1,236 @@
+# Testing AI — como se testa um agente sem rede, sem chave e sem variância
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 1 (on-keyword)
+> **Keywords:** testar agente, fake IChatClient, ScriptedChatClient, harness de turno, eval de agente, teste sem rede, golden de prompt, compatibilidade binaria
+> **Read by Claude in:** implement (ao escrever o teste de qualquer código que fala com um modelo)
+
+**Verified against:** Microsoft.Extensions.AI 10.9.0 + Microsoft.Agents.AI 1.20.0 (ai-pin 2026-09-08); provado por `templates/dotnet/ai-kit/tests/Morph.AiKit.Tests/Fakes/FakeChatClient.cs` e `.../src/Morph.AiKit/Providers/IProviderClientFactory.cs` — o fake roteirizado e a costura que dispensa rede são o que o kit compila e exercita. Harness de turno completo e evals com cache de resposta são **verificação documental** — o ai-kit não os traz. Last-verified: 2026-09-08.
+
+---
+
+## 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.**
+
+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
+disso.
+
+---
+
+## Fake de IChatClient
+
+**Roteirizado e burro.** Uma fila de respostas escritas à mão, servidas na ordem:
+
+- resposta de texto;
+- resposta com chamada de função (`FunctionCallContent`);
+- resposta de texto com uso preenchido (para exercitar a conta de custo).
+
+A fila guarda **respostas**, não exceções: no exemplar do kit, os três métodos de enfileiramento
+recebem `ChatResponse` (direto, por texto, ou por texto + uso), e o único `throw` do fake é o de
+**fila esgotada**. Para exercitar o caminho de falha do provider, injete um cliente que lança em vez
+de enfileirar uma exceção — são costuras diferentes, e confundi-las faz o teste de falha passar pelo
+motivo errado.
+
+E do outro lado, **captura**: as mensagens recebidas, as opções recebidas e a contagem de chamadas —
+uma entrada por chamada, na ordem. É o que permite assertar *o que foi ao provedor*, e não apenas
+*o que voltou*.
+
+**A regra que define o padrão: o fake não pode ser inteligente.** Ele não escolhe resposta por
+conteúdo, não simula um modelo, não "responde razoavelmente". E, esgotada a fila, **ele lança**, com
+a contagem exata de chamadas. Devolver uma resposta vazia em silêncio faria um teste passar por
+engano — que é a única coisa pior do que um teste falhando.
+
+O argumento mais forte a favor desta forma não é teórico: **duas implementações independentes, em
+dois produtos que não se conhecem, chegaram à mesma coisa** (um `FakeChatClient` e um
+`ScriptedChatClient`, com a mesma fila e a mesma captura). O ai-kit compila a terceira.
+
+### A costura, e por que `sealed` não é desculpa para abri-la
+
+O fake só serve se houver **um** ponto de injeção. No kit, esse ponto é uma interface de uma
+operação — dado um alias resolvido, devolva o `IChatClient`. O registry permanece `sealed` e continua
+sem saber construir cliente de provider nenhum.
+
+> **O que o kit traz, e o que ele não traz.** A única implementação dessa interface no kit é a de
+> **teste** (`FakeProviderClientFactory`) — medido. O adaptador de produção, aquele que faz o
+> `switch` por provider e constrói o cliente de verdade, é **seu**: o kit prova que a costura
+> funciona, não que o outro lado dela existe. É a mesma distinção de níveis do resto deste standard.
+
+Precedente de campo com a **variante**: quando o registry é `sealed` e não se quer uma interface
+pública, a costura foi um **construtor `internal`** recebendo uma função `alias -> IChatClient`,
+exposta ao projeto de teste. As duas formas resolvem o mesmo problema; ambas preservam `sealed`, que
+é a política da casa. **Costura de teste não é justificativa para tornar uma classe herdável.**
+
+---
+
+## Harness de turno
+
+**Rode o loop real por cima do fake.** O valor não está em testar o fake; está em fazer o cliente de
+invocação de funções **real** chamar as tools **reais**, com os clientes externos mockados.
+
+É assim que se prova, sem rede e sem chave de API:
+
+- que a tool escolhida foi a certa para aquele estado;
+- que os argumentos montados batem;
+- que o guard barrou o que devia barrar;
+- que o teto de tool calls encerrou o turno onde devia;
+- que o custo somou o que devia somar.
+
+Nenhuma dessas cinco coisas é observável testando o compositor isolado — todas dependem do loop.
+
+**Nota de ownership de recurso:** quem cria o cliente e quem o descarta precisa ser decidido uma vez.
+Se a fábrica guardasse e reaproveitasse clientes por fora, existiriam duas caches da mesma coisa — e
+duas caches da mesma coisa é como um cliente vazado sobrevive a um teste e polui o seguinte.
+
+---
+
+## Eval e unit
+
+**"Eval" aqui não significa "modelo real".**
+
+O padrão medido, e é o que dá mais retorno por hora escrita, é o **eval determinístico**: exercitar o
+caminho **completo e real** — processador de turno, compositor, runner com middleware, tools,
+persistência — com o comportamento do modelo **roteirizado**. Ganha-se cobertura de decisão sem
+variância, e o teste falha por um motivo legível em vez de "o modelo respondeu diferente hoje".
+
+Para o que **precisa** do modelo de verdade, o passo seguinte é uma biblioteca de avaliação com
+**cache de resposta**, em **categoria própria** de teste — nunca misturada à suíte determinística. E
+a regra que fecha: **gate duro só vale sobre propriedade determinística.** Reprovar um build porque
+uma nota subjetiva caiu de 8,1 para 7,9 é transformar ruído em bloqueio.
+
+**Zero chamada real ao provider dentro do `dotnet test`.** É uma propriedade **verificável
+mecanicamente**, e o jeito de verificá-la é uma varredura sobre `tests/` procurando chave de
+provider, leitura de variável de ambiente e cliente HTTP: ela precisa voltar **vazia**.
+
+> **Quem faz essa varredura hoje: ninguém, automaticamente.** Medido em 2026-09-08 sobre o ai-kit
+> (`grep -rniE "OPENAI_API_KEY|GetEnvironmentVariable|HttpClient|EnumerateFiles|Directory.Get"` em
+> `templates/dotnet/ai-kit/**`): **zero ocorrências** — o que prova que o kit **não chama** o
+> provider, e simultaneamente que **não existe teste que cobre essa ausência**. O kit descreve a
+> propriedade em prosa (`FakeChatClient.cs`), não a guarda. Adotar esta regra significa **escrever a
+> varredura no seu projeto**; herdá-la do kit é herdar uma intenção.
+
+A medição de campo que sustenta a regra é do **acervo**, não do kit: `grep -c OPENAI_API_KEY` em
+`tests/` = 0, sem nenhum teste marcado como pulado nem categoria de exclusão — ou seja, não há
+"teste real desligado", há ausência de teste real.
+
+**E o standard registra o preço disso**, porque ele é real: o harness com modelo de verdade daquele
+projeto (onze cenários) **nunca foi rodado por completo ao vivo**. O que fica fora do `dotnet test`
+tende a não rodar. Se um caminho precisa do modelo real, ele precisa de um dono e de um gatilho — ou
+vai apodrecer.
+
+---
+
+## Captura do que foi ao provedor
+
+O que se quer saber depois de um bug é: **o que exatamente foi enviado?**
+
+Os dois artefatos que existem no campo, e nenhum deles se chama "captura da chamada crua":
+
+1. **As opções recebidas pelo fake** — em teste, é a prova direta de que a lista de tools ofertadas
+   saiu da lista real, de que o modo de tool era o esperado, e de que o esforço de raciocínio foi o
+   do alias.
+2. **O hash do texto que foi ao provedor** — em produção.
+
+**A regra: prompt cru só em desenvolvimento e no harness, com opt-in explícito e sem dado pessoal;
+em produção, hash.** Um prompt cru persistido em produção é um vazamento esperando indexação.
+
+Duas asserções que o campo escreveu e que valem copiar: que a lista de tools ofertadas **saiu da
+lista real** (e não de uma constante paralela), e que **turno cancelado não grava** — porque um
+registro de algo que não aconteceu é pior que ausência de registro.
+
+A metade de produção deste assunto — como o hash vira span, e a invariante que o torna confiável —
+é de `ai-agents-observability-patterns`.
+
+---
+
+## Golden com parcimônia
+
+Golden test congela uma saída em arquivo e compara. É excelente onde o **contrato é a forma**, e é
+peso morto onde o conteúdo muda por motivo legítimo.
+
+**Onde compensa:** o render de uma persona a partir de blocos, o contrato de saída estruturada, o
+formato de um artefato publicado.
+
+**Onde não compensa, com contra-exemplo real:** goldens de dois blobs de prompt foram **removidos de
+propósito** de um projeto, com a justificativa medida — *"13,6 KB congelados para provar duas linhas
+de concatenação"*. Cada edição de prompt exigia regravar 13,6 KB, o diff era ilegível, e a revisão
+virava um "aceitar tudo". Um golden que ninguém lê no diff não é teste: é atrito.
+
+O critério: **golden prova forma, não conteúdo.** Se a asserção real é "estas duas linhas
+concatenam", escreva as duas linhas.
+
+### Teste de compatibilidade binária
+
+Técnica, não filosofia: comparar em runtime a versão do assembly do SDK carregado com a que a ponte
+referencia, e conferir a **assinatura** do membro que já quebrou uma vez. É barato, roda sem rede, e
+pega a classe de defeito que custou uma chamada paga sem resposta. Ponte com
+`ai-agents-llm-runtime-defaults`, seção de pin de SDK.
+
+### Prompt versionado é texto testável
+
+Quando o prompt vive fora do código, ele continua sendo texto — e texto se testa. Ler a fonte
+versionada e assertar:
+
+- **presença** de uma regra que precisa estar lá;
+- **vocabulário** das chaves que o consumidor espera;
+- **ausência** de uma instrução revogada — que é a asserção que ninguém escreve e a que mais pega
+  regressão.
+
+Precedente de campo: treze arquivos e cerca de 2.500 linhas fazendo exatamente isso. Ponte com
+`ai-agents-prompt-sources`, seção de reconciliação.
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Por quê é problema | Solução |
+|---|---|---|
+| Fake "inteligente" que escolhe resposta por conteúdo | Você passa a testar o fake | Fila roteirizada, servida na ordem |
+| Fake que devolve vazio quando a fila acaba | O teste passa por engano | Lance, com a contagem de chamadas |
+| Testar só o compositor, sem o loop real | Tool escolhida, guard e teto ficam sem cobertura | Harness com o cliente de invocação real |
+| Chamada real ao provider dentro do `dotnet test` | Custo, flake e dependência de rede na suíte | Zero; e verifique com varredura |
+| Harness com modelo real sem dono nem gatilho | Onze cenários que nunca rodaram por completo | Dono, gatilho e categoria própria |
+| Gate duro sobre nota subjetiva de eval | Ruído virando bloqueio de build | Gate só sobre propriedade determinística |
+| Prompt cru persistido em produção | Vazamento esperando indexação | Hash em produção; cru só em dev/harness com opt-in |
+| Gravar telemetria de turno cancelado | Registro de algo que não aconteceu | Não grave |
+| Golden de blob de prompt | 13,6 KB congelados para provar duas linhas | Asserte as duas linhas |
+| Abrir a classe (`sealed` removido) para poder testar | Costura de teste virando decisão de arquitetura | Interface de uma operação, ou construtor `internal` |
+| Fábrica que guarda e reaproveita clientes por fora | Duas caches da mesma coisa; cliente vazado entre testes | Ownership decidido num lugar |
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] Existe um fake de `IChatClient` roteirizado, com captura de mensagens, opções e contagem
+- [ ] O fake **lança** quando a fila acaba
+- [ ] Há ao menos um teste que roda o loop **real** de invocação de funções por cima do fake
+- [ ] Existe **no seu projeto** um teste que varre `tests/` por chave de provider, leitura de ambiente
+      e cliente HTTP, e ele volta vazio (o ai-kit **não** traz essa varredura — medido; herdá-la do
+      kit é herdar uma intenção)
+- [ ] Nenhum teste real de modelo está apenas "pulado" — ou tem dono e gatilho, ou não existe
+- [ ] Nenhum gate duro sobre nota subjetiva de eval
+- [ ] Existe asserção de que a lista de tools ofertadas saiu da lista real
+- [ ] Turno cancelado não grava telemetria
+- [ ] Nenhum golden de blob de prompt; goldens existentes provam **forma**
+- [ ] Existe teste de compatibilidade binária do par SDK × ponte
+- [ ] O prompt versionado tem teste de texto, incluindo **ausência** de instrução revogada
+- [ ] Nenhuma classe deixou de ser `sealed` por causa de teste
+
+---
+
+## References
+
+- `backend-dotnet-testing` — dono do testing .NET genérico (xUnit, `FakeTimeProvider`, isolamento).
+  Nada dele se repete aqui
+- `ai-agents-llm-runtime-defaults` — o pin de SDK que o teste de compatibilidade binária protege
+- `ai-agents-prompt-sources` — a fonte versionada que o teste de prompt como texto lê
+- `ai-agents-observability-patterns` — a metade de produção da captura (hash, span, invariante)
+- `ai-agents-conversational-agent-with-phases` — compositor, allow-list e teto: o que o harness exercita
+- `ai-agents-cost-and-budget` — a conta que o harness confere com uso roteirizado
+- `ai-agents-guardrails` — os guards que só o loop real prova
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/testing-ai.md v1.0 (2026-09-08)*

package/framework/standards/ai-agents/vector-data-extensions.md

@@ -5,7 +5,7 @@
 > **Keywords:** microsoft extensions vectordata, vectorstorecollection, vector store abstraction, data ingestion, ingestion pipeline, semantic kernel connectors exception, pgvector connector, vectorstorewriter
 > **Read by Claude in:** plan (when choosing a RAG storage backend) + implement (when deciding whether to adopt VectorData over custom pgvector)
 
-**Verified against:** Microsoft.Extensions.VectorData.Abstractions GA (`dotnet/extensions`, transferred from the Semantic Kernel repo) + Microsoft.Extensions.DataIngestion 10.0.1-preview.1.25571.5 + Microsoft.SemanticKernel.Connectors.PgVector 1.74.0-preview. Last-verified: 2026-07-06.
+**Verified against:** Microsoft.Extensions.VectorData.Abstractions **10.9.0** + CommunityToolkit.VectorData.PgVector **1.0.1** + Microsoft.Extensions.DataIngestion **10.9.0-preview.1.26411.16** — nenhum deles está no `framework/ai-pin.json` (que cobre os 5 pacotes de agente), portanto **todas as versões acima foram apuradas na API do nuget.org em 2026-09-08** e são citadas com essa data, não como pin. **Verificação documental**, sem cláusula `provado por`: o ai-kit **não referencia nem exercita** VectorData — o pacote não está no `Morph.AiKit.csproj`, cujos cinco `PackageReference` são exatamente os do pin (medido 2026-09-08). Aqui nem a régua fraca do restore existe. Last-verified: 2026-09-08.
 
 ---
 
@@ -33,7 +33,23 @@ A single `VectorStoreCollection<TKey, TRecord>` shape works identically whether
 
 ## A pegadinha de nomenclatura (crítico — leia antes de tudo)
 
-The concrete vector-store **connectors** — the packages that actually implement `VectorStoreCollection` against a real backend — ship under `Microsoft.SemanticKernel.Connectors.*` package names (`Microsoft.SemanticKernel.Connectors.PgVector`, `.Qdrant`, `.SqlServer`, `.CosmosNoSQL`, `.InMemory`, etc.), even though `Microsoft.Extensions.VectorData.Abstractions` itself has been transferred out of the Semantic Kernel repo into `dotnet/extensions` and is fully independent of SK orchestration.
+> **Atualização de 2026-09-08 — a pegadinha mudou de forma.** Os conectores concretos **saíram** dos nomes `Microsoft.SemanticKernel.Connectors.*` e passaram a `CommunityToolkit.VectorData.*` (repositório `github.com/CommunityToolkit/AI`). Medido na API do nuget.org em 2026-09-08:
+>
+> | Pacote | Última versão | Publicada | Estável? |
+> |---|---|---|---|
+> | `Microsoft.SemanticKernel.Connectors.PgVector` | `1.74.0-preview` | 2026-03-20 | **Nunca teve versão estável**; parou aí |
+> | `CommunityToolkit.VectorData.PgVector` | **`1.0.1`** | **2026-08-31** | **Sim** |
+> | `CommunityToolkit.VectorData.InMemory` | `1.0.1` | 2026-08-31 | Sim |
+>
+> Os dois carregam o **mesmo título e a mesma descrição** ("Postgres (with pgvector extension) provider for Microsoft.Extensions.VectorData"), trocando apenas o autor — *"by Semantic Kernel"* → *"by the .NET Community Toolkit"*. É a mesma peça, com outro dono e outro nome.
+>
+> **Use `CommunityToolkit.VectorData.PgVector` 1.0.1.** O pacote com nome de Semantic Kernel é caminho morto: última versão em março de 2026, e preview.
+>
+> *Fronteira do que foi medido:* a substituição acima é medida (existência, versões, datas, título e descrição, apurados na API do nuget.org em 2026-09-08). Que a página do NuGet **exiba um aviso de rename** não foi confirmado nem pelo `.nuspec` da 1.74.0-preview nem pelos metadados de deprecação da registration API — a afirmação aqui é a substituição, não o aviso.
+
+A pegadinha original — abaixo — continua valendo para **projeto legado** que ainda referencia o nome antigo, e para quem tropeça no nome ao ler código existente.
+
+The concrete vector-store **connectors** — the packages that actually implement `VectorStoreCollection` against a real backend — **used to** ship under `Microsoft.SemanticKernel.Connectors.*` package names (`Microsoft.SemanticKernel.Connectors.PgVector`, `.Qdrant`, `.SqlServer`, `.CosmosNoSQL`, `.InMemory`, etc.), even though `Microsoft.Extensions.VectorData.Abstractions` itself has been transferred out of the Semantic Kernel repo into `dotnet/extensions` and is fully independent of SK orchestration.
 
 Microsoft's own docs are explicit about this:
 
@@ -45,28 +61,36 @@ Microsoft's own docs are explicit about this:
 
 ## Maturidade atual (verificado 2026-07-06)
 
-| Package | Status |
-|---------|--------|
-| `Microsoft.Extensions.VectorData.Abstractions` | **GA** |
-| `Microsoft.Extensions.AI` / `Microsoft.Extensions.AI.Abstractions` | **GA** |
-| `Microsoft.SemanticKernel.Connectors.PgVector` (Postgres/pgvector connector) | **Prerelease** (1.74.0-preview, requires `--prerelease`) |
-| `Microsoft.SemanticKernel.Connectors.InMemory` / other connectors | Verify current status via context7/NuGet before adding — connector GA timing lags the abstractions package |
-| `Microsoft.Extensions.DataIngestion` | **Preview** (10.0.1-preview.1.25571.5) |
+> Tabela **reapurada em 2026-09-08** na API do nuget.org. Cada linha traz a versão exata e a data — nenhum destes pacotes está no `framework/ai-pin.json`, então a data de apuração é o que dá validade ao número.
+
+| Package | Versão (apurada 2026-09-08) | Status |
+|---------|------------------------------|--------|
+| `Microsoft.Extensions.VectorData.Abstractions` | **10.9.0** (publicada 2026-08-11) | **GA** — é a camada de abstração |
+| `Microsoft.Extensions.AI` / `Microsoft.Extensions.AI.Abstractions` | **10.9.0** (no ai-pin) | **GA** |
+| `CommunityToolkit.VectorData.PgVector` (Postgres/pgvector connector) | **1.0.1** (publicada 2026-08-31) | **Estável** — é o conector recomendado hoje |
+| `CommunityToolkit.VectorData.InMemory` / demais conectores | **1.0.1** (2026-08-31) | Estável; confira cada um antes de adicionar |
+| `Microsoft.SemanticKernel.Connectors.PgVector` | `1.74.0-preview` (2026-03-20) | **Caminho morto** — nunca teve versão estável e não avança desde março/2026 |
+| `Microsoft.Extensions.DataIngestion` | **`10.9.0-preview.1.26411.16`** | **Preview** — sem versão estável |
 
-Preview packages are subject to breaking API changes before GA (see the May 2025 rename `PostgresVectorStoreRecordCollection` → `PostgresCollection` as precedent).
+> **Cuidado com o número que o conector declara.** `CommunityToolkit.VectorData.PgVector` 1.0.1 depende de `Microsoft.Extensions.VectorData.Abstractions` **10.8.2** — esse é o **piso da dependência**, não a versão corrente da abstração, que é 10.9.0. Citar 10.8.2 como "a versão do VectorData" é ler o `.nuspec` do conector como se fosse o do pacote.
+
+Preview packages are subject to breaking API changes before GA (see the rename `PostgresVectorStoreRecordCollection` → `PostgresCollection` as precedent).
 
 ---
 
 ## Decision matrix — custom pgvector vs VectorData
 
+**O critério, em uma frase:** a abstração se paga quando **a troca de store é plausível**; o SQL cru se paga quando **já funciona e é testado**. Nada aqui manda migrar o que está de pé.
+
 | Situation | Use |
 |-----------|-----|
-| Default production RAG on Neon/Postgres (this framework's default stack) | **`ai-agents-rag-custom-pgvector`** — GA-quality, zero preview dependencies, framework-owned raw SQL, already the checklisted default |
-| Project needs genuine portability across >1 vector backend (e.g., a client contract requires swapping Postgres for Qdrant or Azure AI Search later) | `Microsoft.Extensions.VectorData` with the relevant connector — document the choice in `decisions.md` |
-| Prototyping, tests, or demos where an in-memory GA-quality store is enough | `Microsoft.Extensions.VectorData` + an in-memory/SQLite connector |
-| Team explicitly accepts a preview dependency for the Postgres connector today | Allowed, but record the acceptance + a revisit-at-GA note in `decisions.md`; do not silently swap the default |
+| Default production RAG on Neon/Postgres (this framework's default stack), **already implemented and tested** | **`ai-agents-rag-custom-pgvector`** — framework-owned raw SQL, zero external connector, already the checklisted default. **Não se migra o que funciona** (item D4 da elevação-9) |
+| **Projeto novo** onde a escolha do store ainda não foi cravada, e trocá-lo depois deve custar pouco | `Microsoft.Extensions.VectorData.Abstractions` 10.9.0 + `CommunityToolkit.VectorData.PgVector` 1.0.1 — hoje **ambos estáveis**, o que remove o argumento "é preview" que existia em julho/2026 |
+| Project needs genuine portability across >1 vector backend (a client contract requires swapping Postgres for Qdrant or Azure AI Search later) | `Microsoft.Extensions.VectorData` + o conector correspondente — document the choice in `decisions.md` |
+| Prototyping, tests, or demos where an in-memory store is enough | `CommunityToolkit.VectorData.InMemory` 1.0.1 |
+| Ingestão em pipeline (reader → chunker → writer) hoje | Só com `Microsoft.Extensions.DataIngestion`, que **continua preview**: registre a aceitação e um lembrete de revisitar no GA |
 
-Do not migrate the existing `ai-agents-rag-custom-pgvector` implementation to the preview PgVector connector as a default — that would trade a working, GA-quality, framework-owned implementation for an unstable dependency, contradicting this framework's no-preview-by-default stance (see `ai-agents-setup` §1).
+Do not migrate the existing `ai-agents-rag-custom-pgvector` implementation to VectorData as a default — that would rewrite a working, tested, framework-owned implementation for no functional gain. **O que mudou desde a verificação anterior:** o argumento *"o conector é preview"* **caiu** (o `CommunityToolkit` é estável desde 2026-08-31); o argumento *"não se reescreve o que funciona"* **permanece**, e é ele que sustenta o default hoje.
 
 ---
 
@@ -138,9 +162,11 @@ This maps conceptually onto the existing custom pattern: `IngestionDocumentReade
 
 | Anti-pattern | Why it's wrong | Right way |
 |--------------|----------------|-----------|
-| Refusing to add `Microsoft.SemanticKernel.Connectors.PgVector` because of the "Forbidden: Microsoft.SemanticKernel.*" rule | The rule targets SK orchestration, not VectorData connectors — see the naming-trap section above | Read this standard's exception note before treating any `Microsoft.SemanticKernel.Connectors.*` package as forbidden |
-| Migrating the working custom pgvector implementation to VectorData "because it's official" | The Postgres connector is still prerelease — trades a stable implementation for an unstable one with no functional gain by default | Keep `ai-agents-rag-custom-pgvector` as the default; adopt VectorData only per the decision matrix |
-| Treating `Microsoft.Extensions.DataIngestion` as production-ready | It ships as `10.0.1-preview.1` — breaking changes are expected before GA | Track it for future adoption; do not wire it into a shipped feature today |
+| Refusing to add a VectorData connector because of the "Forbidden: Microsoft.SemanticKernel.*" rule | The rule targets SK orchestration, not VectorData connectors — see the naming-trap section above | Read this standard's exception note before treating any `Microsoft.SemanticKernel.Connectors.*` package as forbidden |
+| **Adding `Microsoft.SemanticKernel.Connectors.PgVector` in a new project** | Caminho morto: `1.74.0-preview` de 2026-03-20, sem versão estável | `CommunityToolkit.VectorData.PgVector` 1.0.1 |
+| **Citar `Microsoft.Extensions.VectorData.Abstractions` 10.8.2 como "a versão atual"** | 10.8.2 é o **piso da dependência** declarado pelo conector; a corrente é 10.9.0 | Ler a versão no pacote da abstração, não no `.nuspec` de quem depende dela |
+| Migrating the working custom pgvector implementation to VectorData "because it's official" | Reescreve uma implementação testada sem ganho funcional. Note que o motivo mudou: já **não** é mais "porque é preview" | Keep `ai-agents-rag-custom-pgvector` as the default; adopt VectorData per the decision matrix |
+| Treating `Microsoft.Extensions.DataIngestion` as production-ready | Continua preview em 2026-09-08 (`10.9.0-preview.1.26411.16`), sem versão estável | Track it for future adoption; do not wire it into a shipped feature today |
 | Importing `Microsoft.SemanticKernel` (the core orchestration package) to "just get the vector store types" | Pulls in the full SK orchestration surface this framework has deliberately moved away from | Import only `Microsoft.Extensions.VectorData.Abstractions` + the specific `*.Connectors.*` package needed |
 
 ---
@@ -150,7 +176,9 @@ This maps conceptually onto the existing custom pattern: `IngestionDocumentReade
 - [ ] If `Microsoft.SemanticKernel.Connectors.*` appears in a `.csproj`, it is used only for `VectorStoreCollection`/`VectorStore` types — no `Kernel`, `KernelFunction`, or `ChatHistory` usage anywhere in the project.
 - [ ] No plain `Microsoft.SemanticKernel` (core) package reference.
 - [ ] If VectorData was chosen over custom pgvector, the reason is recorded in `decisions.md` per the decision matrix.
-- [ ] If a preview package (`Microsoft.SemanticKernel.Connectors.*` or `Microsoft.Extensions.DataIngestion`) was adopted, `decisions.md` records the preview-acceptance and a revisit-at-GA note.
+- [ ] No new `Microsoft.SemanticKernel.Connectors.*` reference — new work uses `CommunityToolkit.VectorData.*`.
+- [ ] If a preview package (`Microsoft.Extensions.DataIngestion`, or any `*-preview` connector) was adopted, `decisions.md` records the preview-acceptance and a revisit-at-GA note.
+- [ ] Every VectorData/ingestion `PackageReference` carries an exact version — these packages are **not** in `framework/ai-pin.json`, so the project's own `decisions.md` (or a comment) states when the version was checked.
 - [ ] Embedding model/dimensions consistent between the `VectorStoreVector(N)` attribute and the chosen embedding model.
 
 ---
@@ -164,7 +192,9 @@ This maps conceptually onto the existing custom pattern: `IngestionDocumentReade
 - Data ingestion - .NET | Microsoft Learn: https://learn.microsoft.com/en-us/dotnet/ai/conceptual/data-ingestion
 - AI and Vector Data Extensions GA announcement: https://devblogs.microsoft.com/dotnet/ai-vector-data-dotnet-extensions-ga/
 - Introducing Data Ingestion Building Blocks (Preview): https://devblogs.microsoft.com/dotnet/introducing-data-ingestion-building-blocks-preview/
+- Vector stores overview: https://learn.microsoft.com/en-us/dotnet/ai/vector-stores/overview
+- `CommunityToolkit.VectorData.*` — repositório https://github.com/CommunityToolkit/AI (apurado 2026-09-08)
 
 ---
 
-*MORPH-SPEC by Polymorphism Tech — ai-agents/vector-data-extensions.md v1.0 (2026-07-06)*
+*MORPH-SPEC by Polymorphism Tech — ai-agents/vector-data-extensions.md v2.0 (2026-09-08)*

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

@@ -5,7 +5,7 @@
 > **Keywords:** workflow, orchestration, fan-in, fan-out, multi-agent workflow, sequential workflow
 > **Read by Claude in:** plan (only when a genuine fan-in/out or long-running need appears)
 
-**Verified against:** MAF 1.0 GA. Last-verified: 2026-05-19.
+**Verified against:** Microsoft.Agents.AI 1.20.0 (ai-pin 2026-09-08) + Microsoft.Agents.AI.Workflows 1.20.0, Microsoft.Agents.AI.Workflows.Declarative 1.20.0 e Microsoft.Agents.AI.Declarative `1.20.0-rc1` (**os três fora do pin**; versões apuradas no nuget.org em 2026-09-08). **Verificação documental**, sem cláusula `provado por` — o ai-kit não monta workflows. **A localização dos tipos de workflow foi medida por reflexão em 2026-09-08 e CORRIGE este standard**: eles não estão no pacote base. Last-verified: 2026-09-08.
 
 ---
 
@@ -43,19 +43,39 @@ Para o critério de HITL/long-running acima, a implementação (`RequestPort`, `
 
 ## Packages
 
-Workflow APIs (`AgentWorkflowBuilder`, `WorkflowBuilder`, `InProcessExecution`) estão no pacote GA principal:
+> **Correção de 2026-09-08, medida.** A versão anterior deste standard dizia que `AgentWorkflowBuilder`, `WorkflowBuilder` e `InProcessExecution` estavam no pacote base `Microsoft.Agents.AI`. **Não estão.** Varredura dos tipos exportados de `Microsoft.Agents.AI` 1.20.0: **zero** tipos de workflow. Todos os 132 tipos de workflow — `AgentWorkflowBuilder`, `WorkflowBuilder`, `InProcessExecution`, `HandoffWorkflowBuilder`, `GroupChatWorkflowBuilder`, `MagenticWorkflowBuilder`, `CheckpointManager` — vivem em **`Microsoft.Agents.AI.Workflows`**, um pacote **separado**. Seguir o texto antigo dá erro de compilação, não aviso.
 
 ```xml
-<PackageReference Include="Microsoft.Agents.AI" Version="1.0.*" />
+<!-- Base MAF — no ai-pin.json -->
+<PackageReference Include="Microsoft.Agents.AI" Version="1.20.0" />
+
+<!-- Workflows: PACOTE SEPARADO. Estável. Fora do pin; apurado no nuget.org em 2026-09-08. -->
+<PackageReference Include="Microsoft.Agents.AI.Workflows" Version="1.20.0" />
 ```
 
-Para DI helpers (`AddAIAgent`):
+Para DI helpers (`AddAIAgent`, `AddSequentialWorkflow`):
 
 ```xml
-<PackageReference Include="Microsoft.Agents.AI.Hosting" Version="1.0.*" />
+<!-- PRERELEASE: não há versão estável. Fora do pin; apurado em 2026-09-08. -->
+<PackageReference Include="Microsoft.Agents.AI.Hosting" Version="1.20.0-preview.260831.1" />
 ```
 
-> Sem pacotes "preview" separados. Sem `Microsoft.Extensions.AI 9.x`. As APIs de Workflow são parte do `Microsoft.Agents.AI` 1.0 GA.
+### Declarativo: workflow é estável, agente ainda não
+
+Os dois costumam ser citados juntos e têm maturidade **diferente**. Apurado no nuget.org em 2026-09-08:
+
+| Pacote | Última versão | Estável? |
+|---|---|---|
+| `Microsoft.Agents.AI.Workflows.Declarative` (workflows em YAML) | **1.20.0** | **Sim** — estáveis desde a 1.9 |
+| `Microsoft.Agents.AI.Declarative` (agentes declarativos) | `1.20.0-rc1` | **Não** — ainda exige `--prerelease` |
+
+Ou seja: descrever o **grafo** em YAML é caminho estável; descrever o **agente** em YAML ainda não.
+
+### Mudança de comportamento na 1.17
+
+A partir da **1.17**, um workflow **falha quando um agente participante retorna erro** — antes o erro podia ser absorvido e o grafo seguia com um resultado parcial. Consequência: um workflow que "sempre funcionou" pode passar a falhar depois do upgrade, e isso é o comportamento **correto**. Trate erro de agente explicitamente (branch de erro no grafo, ou tratamento dentro do executor) em vez de contar com a absorção antiga.
+
+> Sem `Microsoft.Extensions.AI 9.x`. Nenhuma faixa flutuante — SDK de cadência semanal com `1.0.*` é o defeito que `ai-agents-setup` §1 proíbe.
 
 ---
 
@@ -187,4 +207,4 @@ Sempre use `await using` no `StreamingRun` / `Run` — é `IAsyncDisposable`.
 
 ---
 
-*MORPH-SPEC by Polymorphism Tech — ai-agents/workflows.md v2.0 (2026-05-19)*
+*MORPH-SPEC by Polymorphism Tech — ai-agents/workflows.md v2.0 (2026-09-08)*

package/framework/standards/frontend/design-system/ai-image-generation.md

@@ -288,4 +288,16 @@ If none are good, regenerate at the same step with the prompt adjusted by the fe
 - [ ] Images headed for video framed without faces
 - [ ] Favicon and 1200x630 OG image produced
 
+## Boundary: Runtime Generation Is Another Standard
+
+This standard is **authoring time**: a designer, an MCP tool, and assets that end up committed in the
+repository. When the **product itself** generates images at runtime — a .NET backend calling a paid
+API per request, with cost, review and provenance — the standard is
+`ai-agents/modalities-image-gen.md`, and the surrounding job/review/labelling pipeline is
+`ai-agents/media-pipeline.md`.
+
+The two do not overlap: nothing here talks about paid calls per user, and nothing there repeats the
+brand prompt craft above. The rule that never crosses the boundary is the hard one from
+`ai-agents/media-pipeline.md`: **never generate media inside a conversation turn**.
+
 *MORPH-SPEC by Polymorphism Tech*

package/framework/standards/frontend/design-system/ai-video-generation.md

@@ -110,4 +110,17 @@ TECHNICAL: img2vid with image (start) + endImage (end). No audio. No watermark.
 - [ ] Draft at 480p/4s approved before any 1080p render
 - [ ] Frames re-extracted with a bumped cache-bust after the final render
 
+## Boundary: Runtime Generation Is Another Standard
+
+This standard is **authoring time**: a human driving the seedance MCP in a session, footage that ends
+up committed as a page asset. When the **product itself** generates video at runtime — a .NET worker
+creating a paid task, polling an operation, downloading bytes into its own blob store — the standard
+is `ai-agents/media-video.md` (Veo via `Google.GenAI`, the HTTP-only providers, cost per second, the
+2-day retention), and the surrounding job/review/labelling pipeline is
+`ai-agents/media-pipeline.md`.
+
+The face-moderation workaround in Section 3 above is the piece `ai-agents/media-video.md` cites
+rather than repeats. The rule that never crosses the boundary is the hard one from
+`ai-agents/media-pipeline.md`: **never generate media inside a conversation turn**.
+
 *MORPH-SPEC by Polymorphism Tech*

package/framework/standards/infrastructure/docker/local-compose-isolation.md

@@ -5,7 +5,7 @@
 > **Keywords:** docker compose, worktree, ports, container_name, POSTGRES_PORT, COMPOSE_PROJECT_NAME, local dev, e2e stack
 > **Load When:** a compose file, a dev-server port, or a worktree stack is being written or debugged
 
-**Verified against:** Docker Compose v2 + morph-spec 8.34 (dedicated stack per worktree). Last-verified: 2026-09-07.
+**Verified against:** Docker Compose v2 + morph-spec 8.34 (dedicated stack per worktree). Last-verified: 2026-09-08.
 
 ---
 
@@ -36,12 +36,14 @@ Also exported: `COMPOSE_PROJECT_NAME=morph-{feature}` (isolates container, netwo
 - ALWAYS give `DATABASE_URL` an in-network default so the stack comes up with no `.env`: `postgresql://postgres:postgres@postgres:5432/${POSTGRES_DB:-app}`
 - ALWAYS read the base URL from the environment in `playwright.config.ts`: `process.env.PLAYWRIGHT_BASE_URL ?? \`http://localhost:${process.env.PORT ?? 3000}\``
 - NEVER put a cloud connection string (Neon branch etc.) in `.morph/worktree.env` — it is regenerated; credentials go in the gitignored file named by `config.json → e2e.auth.envFile`
+- NEVER put a variable from the port layout table above (nor `PLAYWRIGHT_BASE_URL`) in that credentials file — the harness **ignores** it and says which key it ignored on stderr. Ports come from the allocated block; the file carries credentials. A `.env.e2e` copied from a sibling worktree carries THAT worktree's block, and before the filter existed it silently repointed this stack at the neighbour's postgres
 
 ## What the harness enforces
 
 - Inside a secondary worktree, a compose with a fixed host port or a `container_name` **fails the `verify` e2e node** (`compose-not-isolable`) — Gate 3 cannot pass on a stack that cannot run beside its siblings. At the primary root the same finding is a warning.
 - `morph-spec finish` tears the stack down **with volumes** (`--keep-volumes` opts out) and deletes the freshness stamp; `morph-spec worktree remove` tears it down without volumes (the feature is still open).
 - Two worktrees never share `POSTGRES_PORT`: the block is allocated first-free-index per feature and released only when the worktree is removed.
+- The credentials env file is read **after** the block but cannot outrank it. All four surfaces (`e2e up`, the `verify` e2e node, the teardown, `morph-spec env`) build their environment through the same `buildComposeEnv`, which drops the layout keys coming from that file and names them on **stderr** — stdout stays eval-safe for `eval "$(morph-spec env)"`. With no block allocated (outside a worktree) nothing is filtered: there the file is the only port source.
 
 ## Minimal compose skeleton
 

package/framework/templates/.idea/morph-templates.xml

@@ -0,0 +1,92 @@
+<templateSet group="MORPH Templates">
+  <template name="morph-pascal" value="{{pascalCase $FEATURE_NAME$}}" description="Convert to PascalCase (UserAuth)" toReformat="false" toShortenFQNames="true">
+    <variable name="FEATURE_NAME" expression="" defaultValue="&quot;FEATURE_NAME&quot;" alwaysStopAt="true" />
+    <context>
+      <option name="OTHER" value="true" />
+    </context>
+  </template>
+
+  <template name="morph-camel" value="{{camelCase $FEATURE_NAME$}}" description="Convert to camelCase (userAuth)" toReformat="false" toShortenFQNames="true">
+    <variable name="FEATURE_NAME" expression="" defaultValue="&quot;FEATURE_NAME&quot;" alwaysStopAt="true" />
+    <context>
+      <option name="OTHER" value="true" />
+    </context>
+  </template>
+
+  <template name="morph-snake" value="{{snakeCase $FEATURE_NAME$}}" description="Convert to snake_case (user_auth)" toReformat="false" toShortenFQNames="true">
+    <variable name="FEATURE_NAME" expression="" defaultValue="&quot;FEATURE_NAME&quot;" alwaysStopAt="true" />
+    <context>
+      <option name="OTHER" value="true" />
+    </context>
+  </template>
+
+  <template name="morph-title" value="{{titleCase $FEATURE_NAME$}}" description="Convert to Title Case (User Auth)" toReformat="false" toShortenFQNames="true">
+    <variable name="FEATURE_NAME" expression="" defaultValue="&quot;FEATURE_NAME&quot;" alwaysStopAt="true" />
+    <context>
+      <option name="OTHER" value="true" />
+    </context>
+  </template>
+
+  <template name="morph-kebab" value="{{kebabCase $FEATURE_NAME$}}" description="Convert to kebab-case (user-auth)" toReformat="false" toShortenFQNames="true">
+    <variable name="FEATURE_NAME" expression="" defaultValue="&quot;FEATURE_NAME&quot;" alwaysStopAt="true" />
+    <context>
+      <option name="OTHER" value="true" />
+    </context>
+  </template>
+
+  <template name="morph-if" value="{{#if $CONDITION$}}&#10;  $END$&#10;{{/if}}" description="Handlebars if block" toReformat="false" toShortenFQNames="true">
+    <variable name="CONDITION" expression="" defaultValue="&quot;condition&quot;" alwaysStopAt="true" />
+    <context>
+      <option name="OTHER" value="true" />
+    </context>
+  </template>
+
+  <template name="morph-if-else" value="{{#if $CONDITION$}}&#10;  $TRUE_BRANCH$&#10;{{else}}&#10;  $FALSE_BRANCH$&#10;{{/if}}" description="Handlebars if-else block" toReformat="false" toShortenFQNames="true">
+    <variable name="CONDITION" expression="" defaultValue="&quot;condition&quot;" alwaysStopAt="true" />
+    <variable name="TRUE_BRANCH" expression="" defaultValue="&quot;&quot;" alwaysStopAt="true" />
+    <variable name="FALSE_BRANCH" expression="" defaultValue="&quot;&quot;" alwaysStopAt="true" />
+    <context>
+      <option name="OTHER" value="true" />
+    </context>
+  </template>
+
+  <template name="morph-each" value="{{#each $ITEMS$}}&#10;  {{this.$PROPERTY$}}&#10;{{/each}}" description="Handlebars each loop" toReformat="false" toShortenFQNames="true">
+    <variable name="ITEMS" expression="" defaultValue="&quot;items&quot;" alwaysStopAt="true" />
+    <variable name="PROPERTY" expression="" defaultValue="&quot;name&quot;" alwaysStopAt="true" />
+    <context>
+      <option name="OTHER" value="true" />
+    </context>
+  </template>
+
+  <template name="morph-service" value="namespace {{NAMESPACE}}.Application.Features.{{pascalCase FEATURE_NAME}}.Services;&#10;&#10;public class {{pascalCase FEATURE_NAME}}Service(&#10;    I{{pascalCase FEATURE_NAME}}Repository repository,&#10;    ILogger&lt;{{pascalCase FEATURE_NAME}}Service&gt; logger) : I{{pascalCase FEATURE_NAME}}Service&#10;{&#10;    public async Task&lt;{{pascalCase FEATURE_NAME}}Dto?&gt; GetByIdAsync(int id, CancellationToken cancellationToken = default)&#10;    {&#10;        $END$&#10;    }&#10;}" description="MORPH .NET Service class template" toReformat="false" toShortenFQNames="true">
+    <context>
+      <option name="C_SHARP" value="true" />
+    </context>
+  </template>
+
+  <template name="morph-repository" value="public class {{pascalCase FEATURE_NAME}}Repository(AppDbContext context) : I{{pascalCase FEATURE_NAME}}Repository&#10;{&#10;    private readonly DbSet&lt;{{pascalCase FEATURE_NAME}}&gt; _dbSet = context.Set&lt;{{pascalCase FEATURE_NAME}}&gt;();&#10;&#10;    public async Task&lt;{{pascalCase FEATURE_NAME}}?&gt; GetByIdAsync(int id, CancellationToken cancellationToken = default)&#10;    {&#10;        $END$&#10;    }&#10;}" description="MORPH .NET Repository class template" toReformat="false" toShortenFQNames="true">
+    <context>
+      <option name="C_SHARP" value="true" />
+    </context>
+  </template>
+
+  <template name="morph-component" value="@page &quot;/{{kebabCase FEATURE_NAME}}&quot;&#10;@inject I{{pascalCase FEATURE_NAME}}Service {{pascalCase FEATURE_NAME}}Service&#10;@inject ILogger&lt;{{pascalCase FEATURE_NAME}}Page&gt; Logger&#10;&#10;&lt;PageTitle&gt;{{pascalCase FEATURE_NAME}}&lt;/PageTitle&gt;&#10;&#10;&lt;div class=&quot;container-fluid&quot;&gt;&#10;    $END$&#10;&lt;/div&gt;&#10;&#10;@code {&#10;&#10;}" description="MORPH Blazor component template" toReformat="false" toShortenFQNames="true">
+    <context>
+      <option name="HTML" value="true" />
+    </context>
+  </template>
+
+  <template name="morph-migration" value="public partial class Add{{pascalCase FEATURE_NAME}} : Migration&#10;{&#10;    protected override void Up(MigrationBuilder migrationBuilder)&#10;    {&#10;        migrationBuilder.CreateTable(&#10;            name: &quot;{{pascalCase FEATURE_NAME}}s&quot;,&#10;            columns: table =&gt; new&#10;            {&#10;                Id = table.Column&lt;int&gt;(type: &quot;int&quot;, nullable: false)&#10;                    .Annotation(&quot;SqlServer:Identity&quot;, &quot;1, 1&quot;),&#10;                $END$&#10;            },&#10;            constraints: table =&gt;&#10;            {&#10;                table.PrimaryKey(&quot;PK_{{pascalCase FEATURE_NAME}}s&quot;, x =&gt; x.Id);&#10;            });&#10;    }&#10;&#10;    protected override void Down(MigrationBuilder migrationBuilder)&#10;    {&#10;        migrationBuilder.DropTable(name: &quot;{{pascalCase FEATURE_NAME}}s&quot;);&#10;    }&#10;}" description="MORPH EF Core migration template" toReformat="false" toShortenFQNames="true">
+    <context>
+      <option name="C_SHARP" value="true" />
+    </context>
+  </template>
+
+  <template name="morph-ts-contract" value="export interface {{pascalCase FEATURE_NAME}} {&#10;  id: number;&#10;  $FIELD1$&#10;}&#10;&#10;export interface Create{{pascalCase FEATURE_NAME}}Request {&#10;  $FIELD2$&#10;}&#10;&#10;export interface Update{{pascalCase FEATURE_NAME}}Request {&#10;  $END$&#10;}" description="MORPH TypeScript contract template" toReformat="false" toShortenFQNames="true">
+    <variable name="FIELD1" expression="" defaultValue="&quot;&quot;" alwaysStopAt="true" />
+    <variable name="FIELD2" expression="" defaultValue="&quot;&quot;" alwaysStopAt="true" />
+    <context>
+      <option name="TypeScript" value="true" />
+    </context>
+  </template>
+</templateSet>