@polymorphism-tech/morph-spec 8.46.0 → 8.47.0

package/framework/standards/ai-agents/modalities-speech-to-text.md

@@ -5,7 +5,7 @@
 > **Keywords:** speech to text, transcription, whisper, audio to text, voice transcription
 > **Read by Claude in:** implement (quando o projeto precisa transcrever áudio para texto)
 
-**Verified against:** OpenAI 2.13.0 + Microsoft.Extensions.AI 10.9.0 (ai-pin 2026-09-08). **Verificação documental**, sem cláusula `provado por` — o ai-kit não transcreve áudio. `AudioClient.TranscribeAudioAsync` e a ponte `AsISpeechToTextClient` foram **medidas por reflexão sobre as assemblies do pin** em 2026-09-08. Last-verified: 2026-09-08.
+**Verified against:** OpenAI 2.13.0 + Microsoft.Extensions.AI 10.9.0 (ai-pin 2026-09-08). **Verificação documental**, sem cláusula `provado por` — o ai-kit não transcreve áudio. `AudioClient.TranscribeAudioAsync` e a ponte `AsISpeechToTextClient` foram **medidas por reflexão sobre as assemblies do pin** em 2026-09-08. Em 2026-10-03 os blocos da API, do `TranscriptionService`, do agente downstream (dentro de um método-invólucro) e do registro DI compilaram com `TreatWarningsAsErrors` contra `OpenAI` 2.13.0 + `Microsoft.Agents.AI` 1.20.0 (o pin de 2026-09-08, que é a data que este campo carrega). Last-verified: 2026-09-08.
 
 ---
 
@@ -32,14 +32,20 @@ No OpenAI SDK (.NET 2.x), o caminho é `AudioClient.TranscribeAudio`:
 ```csharp
 using OpenAI.Audio;
 
-AudioClient client = new("whisper-1", apiKey);
-AudioTranscription transcription = await client.TranscribeAudioAsync(audioFilePath);
-string text = transcription.Text;
+public sealed class TranscribeOnce(AudioClient client)
+{
+    public async Task<string> RunAsync(string audioFilePath, CancellationToken ct)
+    {
+        await using var audio = File.OpenRead(audioFilePath);
+        AudioTranscription transcription = await client.TranscribeAudioAsync(audio, Path.GetFileName(audioFilePath), cancellationToken: ct);
+        return transcription.Text;
+    }
+}
 ```
 
-O projeto injeta `AudioClient` via DI. Para transcrição com timestamps (ex: sincronização de legenda), use `AudioTranscriptionOptions` com `ResponseFormat = AudioTranscriptionFormat.Verbose`.
+O `AudioClient` chega pelo construtor: ele é registrado **uma vez** no DI com modelo e chave vindos de configuração (ver *Registro DI* abaixo) e nunca é construído inline no chamador. Para transcrição com timestamps (ex: sincronização de legenda), use `AudioTranscriptionOptions` com `ResponseFormat = AudioTranscriptionFormat.Verbose`.
 
-> **Conferência de 2026-09-08.** As sobrecargas existentes na assembly `OpenAI` 2.13.0 são `TranscribeAudioAsync(string audioFilePath, AudioTranscriptionOptions)` e `TranscribeAudioAsync(Stream audio, string audioFilename, AudioTranscriptionOptions, CancellationToken)` — **a de `Stream` exige o nome do arquivo**, porque é dele que o serviço deduz o formato. Passar só o stream não compila.
+> **Conferência de 2026-09-08.** As sobrecargas existentes na assembly `OpenAI` 2.13.0 são `TranscribeAudioAsync(string audioFilePath, AudioTranscriptionOptions)` e `TranscribeAudioAsync(Stream audio, string audioFilename, AudioTranscriptionOptions, CancellationToken)` — **a de `Stream` exige o nome do arquivo**, porque é dele que o serviço deduz o formato. Passar só o stream não compila. **A de caminho não aceita `CancellationToken`** (recompilado em 2026-10-03: o exemplo anterior passava `cancellationToken:` a ela e não compilava, assim como `TimestampGranularities` escrito como coleção) — para honrar o cancelamento do request, abra o arquivo (`File.OpenRead`) e use a de `Stream`, como nos exemplos abaixo.
 >
 > **Caminho por abstração (opcional):** `Microsoft.Extensions.AI` 10.9.0 define `ISpeechToTextClient`, e `Microsoft.Extensions.AI.OpenAI` publica `audioClient.AsISpeechToTextClient()`. Vale quando o projeto quer trocar de provedor sem tocar no chamador; o `AudioClient` direto continua sendo o caminho mais curto.
 >
@@ -49,33 +55,22 @@ O projeto injeta `AudioClient` via DI. Para transcrição com timestamps (ex: si
 
 ## Exemplo C# completo
 
-Três entradas: arquivo, bytes (ex: upload do usuário) — as duas devolvem texto simples — e a verbose, com timestamps por palavra e segmento, útil para legendas ou busca por trecho.
+Três entradas: arquivo, bytes (ex: upload do usuário) — as duas devolvem texto simples — e a verbose, com timestamps por palavra e segmento, útil para legendas ou busca por trecho. `TimestampGranularities` é um enum de flags (`AudioTimestampGranularities.Word | ...Segment`), não uma coleção.
 
 ```csharp
 using OpenAI.Audio;
-using Microsoft.Extensions.Configuration;
 
-public sealed class TranscriptionService
+public sealed class TranscriptionService(AudioClient client)
 {
-    private readonly AudioClient _client;
-
-    public TranscriptionService(IConfiguration config)
-    {
-        var model = config["Transcription:Model"] ?? "whisper-1";
-        var apiKey = config["OpenAI:ApiKey"]!;
-        _client = new AudioClient(model, apiKey);
-    }
-
     public async Task<string> TranscribeAsync(string audioFilePath, CancellationToken ct = default)
     {
-        AudioTranscription transcription = await _client.TranscribeAudioAsync(audioFilePath, cancellationToken: ct);
-        return transcription.Text;
+        await using var audio = File.OpenRead(audioFilePath);
+        return await TranscribeBytesAsync(audio, Path.GetFileName(audioFilePath), ct);
     }
 
     public async Task<string> TranscribeBytesAsync(
         Stream audioStream,
         string fileName,
-        string mediaType = "audio/mpeg",
         CancellationToken ct = default)
     {
         var options = new AudioTranscriptionOptions
@@ -83,7 +78,7 @@ public sealed class TranscriptionService
             ResponseFormat = AudioTranscriptionFormat.Simple
         };
 
-        AudioTranscription transcription = await _client.TranscribeAudioAsync(
+        AudioTranscription transcription = await client.TranscribeAudioAsync(
             audioStream, fileName, options, cancellationToken: ct);
         return transcription.Text;
     }
@@ -93,10 +88,11 @@ public sealed class TranscriptionService
         var options = new AudioTranscriptionOptions
         {
             ResponseFormat         = AudioTranscriptionFormat.Verbose,
-            TimestampGranularities = { AudioTimestampGranularity.Word, AudioTimestampGranularity.Segment }
+            TimestampGranularities = AudioTimestampGranularities.Word | AudioTimestampGranularities.Segment
         };
 
-        return await _client.TranscribeAudioAsync(audioFilePath, options, cancellationToken: ct);
+        await using var audio = File.OpenRead(audioFilePath);
+        return await client.TranscribeAudioAsync(audio, Path.GetFileName(audioFilePath), options, ct);
     }
 }
 ```
@@ -110,12 +106,26 @@ AgentResponse<MeetingActions> actions = await _statusAgent.RunAsync<MeetingActio
     $"Extraia ações, decisões e responsáveis desta transcrição:\n\n{transcript}");
 ```
 
-**Registro DI** (`Program.cs`):
+**Registro DI** (`Program.cs`) — o único lugar onde o `AudioClient` é construído:
 
 ```csharp
-builder.Services.AddSingleton<TranscriptionService>();
+using OpenAI.Audio;
+
+public static class TranscriptionRegistration
+{
+    public static IServiceCollection AddTranscription(this IServiceCollection services, IConfiguration config)
+    {
+        services.AddSingleton(_ => new AudioClient(
+            config["Transcription:Model"] ?? "whisper-1",
+            config["OpenAI:ApiKey"] ?? throw new InvalidOperationException("OpenAI:ApiKey is not configured.")));
+        services.AddSingleton<TranscriptionService>();
+        return services;
+    }
+}
 ```
 
+A chave vem de user-secrets em desenvolvimento e de variável de ambiente no deploy (Coolify); o `throw` roda uma vez na resolução do singleton, como validação de configuração. `AudioClient` é thread-safe, então o singleton é seguro.
+
 ---
 
 ## Formatos e limites

package/framework/standards/ai-agents/prompt-sources.md

@@ -81,7 +81,7 @@ Column summary:
 
 | Column | Type | Notes |
 |--------|------|-------|
-| `id` | `uuid` | PK, `gen_random_uuid()` |
+| `id` | `uuid` | PK, **no column default** -- set by the app with `Guid.CreateVersion7()` on insert |
 | `agent_key` | `text NOT NULL` | Logical identifier, e.g. `"proposal-agent"` |
 | `version` | `int NOT NULL` | Monotonically increasing per `agent_key` |
 | `content` | `text NOT NULL` | The full system-prompt text |
@@ -238,9 +238,11 @@ UPDATE {{SCHEMA}}.agent_prompts
    SET is_active = false
  WHERE agent_key = 'proposal-agent' AND is_active = true;
 
--- 2. Insert the new version (version = previous max + 1)
-INSERT INTO {{SCHEMA}}.agent_prompts (agent_key, version, content, is_active)
+-- 2. Insert the new version (version = previous max + 1);
+--    :'new_id' is a Guid.CreateVersion7() generated by the app/tooling, never gen_random_uuid()
+INSERT INTO {{SCHEMA}}.agent_prompts (id, agent_key, version, content, is_active)
 VALUES (
+    :'new_id',
     'proposal-agent',
     (SELECT COALESCE(MAX(version), 0) + 1 FROM {{SCHEMA}}.agent_prompts WHERE agent_key = 'proposal-agent'),
     'Your new system prompt text here...',
@@ -248,7 +250,7 @@ VALUES (
 );
 ```
 
-This keeps a complete, auditable history. Rollback = deactivate the current row and reactivate any previous row.
+This keeps a complete, auditable history. Rollback = deactivate the current row and reactivate any previous row. When the publish runs from the app (a slice handler), the new row is `new AgentPrompt { Id = Guid.CreateVersion7(), ... }`, inside the same transaction as the deactivation (the unique partial index rejects a second active row if the deactivation is missing or runs after the insert).
 
 ---
 

package/framework/standards/ai-agents/providers/model-registry.md

@@ -1,7 +1,7 @@
 # Model Registry — Provider-agnostic agent configuration
 
 > **Scope:** stacks=["dotnet"]
-> **Layer:** 0 (always-load via persona maf-expert)
+> **Layer:** 0 (lista da persona `maf-expert`; resumo injetado pela rule `ai-agents-standards` em `**/Agents/**`, `**/agents/**`, `**/*Agent*.cs`; texto completo sob demanda via `morph-spec standards --find`)
 > **Keywords:** model registry, provider agnostic, model alias, IChatClient factory, multi-model, model selection, model config, api per alias, responses vs chat, reasoning effort
 > **Read by Claude in:** plan (cita este standard quando feature menciona >1 modelo ou multi-provider) + implement (copia o template ModelRegistry.cs e gera config no projeto)
 

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

@@ -5,7 +5,7 @@
 > **Keywords:** rag, vector search, pgvector, embeddings, custom rag, retrieval, semantic search, knowledge base, RAG tool, delta ingestion, incremental ingestion, lookup key
 > **Read by Claude in:** implement (when an agent needs to retrieve knowledge)
 
-**Verified against:** Microsoft.Agents.AI 1.20.0 + Microsoft.Extensions.AI 10.9.0 (ai-pin 2026-09-08); `provado por templates/dotnet/ai-kit/src/Morph.AiKit/Rag/DeltaIngest.cs` **restrito à seção "Ingestão delta por lookup-key"** — é a única parte deste standard que o ai-kit compila. Todo o resto (pgvector, SQL, HNSW, embeddings, multi-tenant) é **verificação documental**; a versão e o status de `Microsoft.Extensions.DataIngestion` foram apurados no nuget.org em 2026-09-08. Last-verified: 2026-09-08.
+**Verified against:** Microsoft.Agents.AI 1.20.0 + Microsoft.Extensions.AI 10.9.0 (ai-pin 2026-09-08); `provado por templates/dotnet/ai-kit/src/Morph.AiKit/Rag/DeltaIngest.cs` **restrito à seção "Ingestão delta por lookup-key"** — é a única parte deste standard que o ai-kit compila. Todo o resto (pgvector, SQL, HNSW, embeddings, multi-tenant) é **verificação documental**; a versão e o status de `Microsoft.Extensions.DataIngestion` foram apurados no nuget.org em 2026-09-08. Em 2026-10-03, contra o mesmo pin, compilaram com `TreatWarningsAsErrors` os blocos de registro do `IEmbeddingGenerator`, do `VectorSearchTool` (EF Core + Pgvector.EntityFrameworkCore 0.3.0) e do *Exemplo de uso* (a ponte `Microsoft.Extensions.AI.OpenAI` 10.9.0 resolveu `OpenAI` 2.12.0); a forma anterior `RunAsync(question, ct)` não compilava (CS1503). Last-verified: 2026-09-08.
 
 ---
 
@@ -27,7 +27,7 @@ Hosted RAG (uploading PDFs to a service) hands control of chunking, embedding, a
 [Document ingestion]
         │
         ▼
- EmbeddingService                  (generates float vectors via IEmbeddingGenerator)
+ IEmbeddingGenerator (injected)    (batch GenerateAsync at ingestion, one vector per query)
         │
         ▼
   kb_embeddings table              (pgvector column, HNSW index, tenant_id partition)
@@ -41,9 +41,9 @@ Hosted RAG (uploading PDFs to a service) hands control of chunking, embedding, a
 
 Three pieces:
 
-1. **EmbeddingService** — wraps `IEmbeddingGenerator<string, Embedding<float>>` from `Microsoft.Extensions.AI`. Called during indexing (batch) and at query time (single text).
+1. **`IEmbeddingGenerator<string, Embedding<float>>`** (from `Microsoft.Extensions.AI`), injected directly where embeddings are needed: the ingestion handler (batch) and the tool (single text). No wrapper class.
 2. **`kb_embeddings` table** — stores chunk text + `vector(1536)` + `tenant_id` + `metadata jsonb`. HNSW index with `vector_cosine_ops`.
-3. **VectorSearchTool** — a typed MAF tool. A `[Description]`-decorated method the agent can call. Embeds the query, runs cosine-distance SQL, returns top-k chunks as concatenated text.
+3. **VectorSearchTool** — a typed MAF tool. A `[Description]`-decorated method the agent can call. Embeds the query, orders by cosine distance (EF Core LINQ), returns top-k chunks as concatenated text.
 
 ---
 
@@ -63,37 +63,35 @@ For implementation of each strategy, see `data-vector-search-rag-chunking`. Do n
 
 ---
 
-## EmbeddingService
+## Embeddings: `IEmbeddingGenerator` direto no slice
 
-Reference template: `templates/code/dotnet/ai-agents/EmbeddingService.cs.template`
+There is **no `EmbeddingService` wrapper**. The ingestion handler and the `VectorSearchTool` inject `IEmbeddingGenerator<string, Embedding<float>>` (from `Microsoft.Extensions.AI`) directly: a class whose `EmbedAsync`/`EmbedBatchAsync` only rename `GenerateVectorAsync`/`GenerateAsync` is the service layer the stack forbids, and it hides the batch call behind a per-text API.
 
-The service wraps `IEmbeddingGenerator<string, Embedding<float>>` (from `Microsoft.Extensions.AI`) and exposes two methods:
+- **Query time (one text):** `await embeddings.GenerateVectorAsync(query, cancellationToken: ct)` returns a `ReadOnlyMemory<float>`; wrap it in `Pgvector.Vector` for the column.
+- **Indexing (batch):** `await embeddings.GenerateAsync(texts, cancellationToken: ct)` returns `GeneratedEmbeddings<Embedding<float>>`, one provider call for the whole batch; each element's `.Vector` is a `ReadOnlyMemory<float>`.
 
-```csharp
-// Single text → embedding vector (used at query time)
-Task<ReadOnlyMemory<float>> EmbedAsync(string text, CancellationToken ct = default);
-
-// Batch of texts → list of vectors (used during document indexing)
-Task<IReadOnlyList<ReadOnlyMemory<float>>> EmbedBatchAsync(
-    IReadOnlyList<string> texts, CancellationToken ct = default);
-```
-
-Both call `GenerateAsync(IEnumerable<string>, ...)` on the injected `IEmbeddingGenerator` (verified via context7 / Microsoft Learn). `GenerateAsync` returns `GeneratedEmbeddings<Embedding<float>>`; each element's `.Vector` property is a `ReadOnlyMemory<float>`.
-
-**Wiring the `IEmbeddingGenerator`:** the project registers its chosen embedding provider in DI (e.g., via the OpenAI embedding client's `.AsIEmbeddingGenerator()` extension, or the equivalent for another provider). The `embeddings` alias in `model-registry.json` declares the model (`text-embedding-3-small`, dimensions 1536). The `EmbeddingService` is registered as a scoped or singleton service and injected wherever indexing or search happens.
+**Wiring the `IEmbeddingGenerator`:** the project registers its chosen embedding provider in DI (e.g., via the OpenAI embedding client's `.AsIEmbeddingGenerator()` extension, from `Microsoft.Extensions.AI.OpenAI` -- mind the NU1608 restore trap against `OpenAI` 2.13.0 described in `ai-agents/setup.md`). The `embeddings` alias in `model-registry.json` declares the model (`text-embedding-3-small`, dimensions 1536).
 
 ```csharp
 // Example DI registration (Program.cs, in the project — not in framework)
-builder.Services.AddSingleton<IEmbeddingGenerator<string, Embedding<float>>>(sp =>
+using Microsoft.Extensions.AI;
+using OpenAI;
+
+public static class EmbeddingRegistration
 {
-    var cfg = sp.GetRequiredService<IConfiguration>();
-    return new OpenAIClient(cfg["OpenAI:ApiKey"]!)
-        .GetEmbeddingClient("text-embedding-3-small")
-        .AsIEmbeddingGenerator();
-});
-builder.Services.AddScoped<EmbeddingService>();
+    public static IServiceCollection AddEmbeddings(this IServiceCollection services) =>
+        services.AddSingleton<IEmbeddingGenerator<string, Embedding<float>>>(sp =>
+        {
+            var cfg = sp.GetRequiredService<IConfiguration>();
+            return new OpenAIClient(cfg["OpenAI:ApiKey"]!)
+                .GetEmbeddingClient("text-embedding-3-small")
+                .AsIEmbeddingGenerator();
+        });
+}
 ```
 
+The legacy `templates/code/dotnet/ai-agents/EmbeddingService.cs.template` still generates the wrapper; do not copy it into new code.
+
 ---
 
 ## A tabela pgvector
@@ -102,7 +100,7 @@ Reference template: `templates/code/sql/ai-agents/pgvector-embeddings-migration.
 
 ```sql
 CREATE TABLE kb_embeddings (
-    id          uuid        PRIMARY KEY DEFAULT gen_random_uuid(),
+    id          uuid        PRIMARY KEY,  -- set by the app: deterministic V5 for delta-ingested chunks (rule 3 below), otherwise Guid.CreateVersion7(); never a gen_random_uuid() default
     tenant_id   uuid        NOT NULL,
     source      text        NOT NULL,   -- document identifier / URL
     chunk_index int         NOT NULL,   -- position within source document
@@ -135,23 +133,53 @@ Reference template: `templates/code/dotnet/ai-agents/VectorSearchTool.cs.templat
 A sealed class with a `[Description]`-decorated method the agent calls when it needs context from the knowledge base.
 
 ```csharp
-// Registration — in the agent setup code
-var tool = sp.GetRequiredService<VectorSearchTool>();
-var agent = _modelRegistry.GetChatClient("text-default")
-    .AsAIAgent(
-        instructions: systemPrompt,
-        tools: [AIFunctionFactory.Create(tool.SearchAsync)]);
+// Features/KnowledgeFeature/VectorSearchTool.cs
+using System.ComponentModel;
+using Microsoft.EntityFrameworkCore;
+using Microsoft.Extensions.AI;
+using Pgvector;
+using Pgvector.EntityFrameworkCore;
+
+public interface ITenantContext
+{
+    Guid TenantId { get; }
+}
+
+public sealed class VectorSearchTool(
+    ApplicationDbContext db,
+    IEmbeddingGenerator<string, Embedding<float>> embeddings,
+    ITenantContext tenant)
+{
+    [Description("Searches the knowledge base and returns the most relevant passages for the query.")]
+    public async Task<string> SearchAsync(
+        [Description("Natural-language search query")] string query,
+        CancellationToken ct = default)
+    {
+        var queryVector = new Vector(await embeddings.GenerateVectorAsync(query, cancellationToken: ct));
+
+        var chunks = await db.KbEmbeddings
+            .Where(e => e.TenantId == tenant.TenantId)
+            .OrderBy(e => e.Embedding.CosineDistance(queryVector))
+            .Take(5)
+            .Select(e => e.Content)
+            .ToListAsync(ct);
+
+        return string.Join("\n\n---\n\n", chunks);
+    }
+}
 ```
 
 The tool:
 1. Takes a natural-language `query` string (the only parameter the LLM sees).
-2. Calls `EmbeddingService.EmbedAsync(query)` to get a query vector.
-3. Runs a parameterized SQL `SELECT content FROM kb_embeddings WHERE tenant_id = @tenant ORDER BY embedding <=> @queryVec LIMIT 5`.
+2. Calls `GenerateVectorAsync(query)` on the injected generator to get the query vector.
+3. Filters by the tenant, orders by `CosineDistance` (translated to `ORDER BY embedding <=> @query`, which uses the HNSW index) and takes 5.
 4. Concatenates chunk contents and returns them as a single string — the agent uses this as grounding context.
 
+Registered on the agent with `tools: [AIFunctionFactory.Create(tool.SearchAsync)]` (see *Exemplo de uso*); `KbEmbedding` is mapped like the `Document` of `infrastructure-neon-pgvector` (`Vector` property, `HasColumnName` for the snake_case columns, `UseVector()`).
+
 The `tenant_id` filter is **never a tool parameter** (that would allow the LLM to cross tenant boundaries). It is injected via a constructor dependency — e.g., a scoped `ITenantContext` or a `Guid currentTenantId` resolved from the authenticated request. See §Multi-tenant below.
 
-Note on raw Npgsql vs EF Core: this template uses `NpgsqlDataSource` (raw SQL) for the cosine-distance query, since pgvector operators (`<=>`) are easier to express and verify in raw SQL. If the project already wires pgvector through EF Core (`UseVector()`, `HasMethod("hnsw")`), the equivalent `db.Database.SqlQuery<>` form per `infrastructure-neon-pgvector` is equally valid — choose whichever is already in use.
+Note on raw Npgsql vs EF Core: the EF Core LINQ form above is the default (`ApplicationDbContext` in the slice, no raw SQL). A raw `NpgsqlDataSource` query is acceptable only with a `decisions.md` justification (e.g. a project with no EF Core model for this table). The legacy `VectorSearchTool.cs.template` still uses raw SQL and `EmbeddingService`; prefer the block above.
 
 ---
 
@@ -176,7 +204,7 @@ public sealed class KnowledgeAgentHandler(
                 instructions: systemPrompt,
                 tools: [AIFunctionFactory.Create(searchTool.SearchAsync)]);
 
-        var response = await agent.RunAsync(question, ct);
+        var response = await agent.RunAsync(question, cancellationToken: ct);
         return response.Text;
     }
 }
@@ -283,9 +311,9 @@ ALTER TABLE kb_embeddings ENABLE ROW LEVEL SECURITY;
 
 ## Checklist (verifiable in review)
 
-- [ ] EmbeddingService (concrete class) registered in DI; it injects IEmbeddingGenerator<string, Embedding<float>> for the project's chosen embedding model.
+- [ ] `IEmbeddingGenerator<string, Embedding<float>>` registered in DI for the project's chosen embedding model and injected directly into the ingestion handler and `VectorSearchTool` — no `EmbeddingService` wrapper.
 - [ ] Embedding model declared in `model-registry.json` under the `embeddings` alias.
-- [ ] `kb_embeddings` table has `embedding vector(1536)` and HNSW index with `vector_cosine_ops`.
+- [ ] `kb_embeddings` table has `embedding vector(1536)` and HNSW index with `vector_cosine_ops`; `id` has no column default (app-assigned).
 - [ ] `tenant_id` column present and filtered in every query.
 - [ ] `VectorSearchTool.SearchAsync` takes only `query` + `ct` — no tenant param visible to the LLM.
 - [ ] `VectorSearchTool` registered on the agent via `AIFunctionFactory.Create(tool.SearchAsync)`.

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

@@ -1,7 +1,7 @@
 # Microsoft Agent Framework — Setup Guide (.NET 10)
 
 > **Scope:** stacks=["dotnet"]
-> **Layer:** 0 (always-load via persona maf-expert)
+> **Layer:** 0 (lista da persona `maf-expert`; resumo injetado pela rule `ai-agents-standards` em `**/Agents/**`, `**/agents/**`, `**/*Agent*.cs`; texto completo sob demanda via `morph-spec standards --find`)
 > **Keywords:** maf setup, microsoft agents ai, chatclient, ai agent, agent framework, agent dotnet, AsAIAgent, responses api, chat completions, store false
 > **Read by Claude in:** plan (pra citar pacote em tasks.json) + implement (pra escrever .csproj e Program.cs)
 

package/framework/standards/ai-agents/structured-output.md

@@ -1,7 +1,7 @@
 # Structured Output — Typed agent responses
 
 > **Scope:** stacks=["dotnet"]
-> **Layer:** 0 (always-load via persona maf-expert)
+> **Layer:** 0 (lista da persona `maf-expert`; resumo injetado pela rule `ai-agents-standards` em `**/Agents/**`, `**/agents/**`, `**/*Agent*.cs`; texto completo sob demanda via `morph-spec standards --find`)
 > **Keywords:** structured output, typed response, response format, schema validated output, record output, JSON schema agent, RunAsync generic
 > **Read by Claude in:** implement (sempre que um agente produz saída consumida por outro sistema)
 

package/framework/standards/ai-agents/sweet-spot.md

@@ -1,7 +1,7 @@
 # Sweet Spot — When to use what in MAF
 
 > **Scope:** stacks=["dotnet"]
-> **Layer:** 0 (always-load via persona maf-expert)
+> **Layer:** 0 (lista da persona `maf-expert`; resumo injetado pela rule `ai-agents-standards` em `**/Agents/**`, `**/agents/**`, `**/*Agent*.cs`; texto completo sob demanda via `morph-spec standards --find`)
 > **Keywords:** sweet spot, when to use agent, agent vs workflow, when not to use workflow, MAF decision, simple agent, tool budget, quantas tools
 > **Read by Claude in:** plan (decide arquitetura da feature antes de quebrar em tasks) + implement (validar que a arquitetura ainda é a mais simples possível)
 

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

@@ -1,7 +1,7 @@
 # Comentários no código
 
 > **Scope:** universal
-> **Layer:** 0 (always load)
+> **Layer:** 0 (resumo injetado pelas rules `csharp-standards` (`**/*.cs`, `**/*.csproj`) e `nextjs-standards` (`**/*.ts`, `**/*.tsx`); texto completo sob demanda via `morph-spec standards --find`)
 > **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
 
@@ -97,7 +97,7 @@ processo, banner/`#region`, bloco de mais de 3 linhas ou `///`/JSDoc em projeto
 publicado. Comentário que o arquivo já tinha nunca é acusado. Repetir o código em uma linha não é
 detectável por forma: fica com a revisão abaixo.
 
-Comentário que o código dispensava é achado da rubrica `code-quality` no Gate 3. O nó `validators`
+Comentário que o código dispensava é nota do avaliador no Gate 3 (`review-checklist.md`), não bloqueador. O nó `validators`
 do `morph-spec verify` mede, nas linhas que a feature adicionou (validador `code-budget`), quantas
 linhas de comentário citam processo e a densidade de comentário sobre o código adicionado, e avisa
 com os números e os arquivos mais comentados.

package/framework/standards/architecture/vertical-slice/vertical-slice.md

@@ -4,7 +4,7 @@
 > **Layer:** 2
 > **Keywords:** vertical-slice, vsa, minimal-api, ihandler, result-pattern, feature-slice, scrutor, fluentvalidation
 
-**Verified against:** .NET 10 + EF Core 10 + FluentValidation 12 + Scrutor 7. Last-verified: 2026-05-20.
+**Verified against:** .NET 10 (SDK 10.0.400-preview) + EF Core 10.0.12 + FluentValidation 12.1.1 + Scrutor 7. Os blocos da slice (Handler, Validator, Endpoint) compilam com `TreatWarningsAsErrors` sobre o `Result`/`Error`/`ErrorHttpMapping` de `result-pattern.md` nos namespaces da árvore acima (`{ProjectName}` substituído; o Handler com `global using` de Abstractions/Database/Entities, o Endpoint só com os próprios `using`); Abstractions, Pipelines e DI são verificação documental. Last-verified: 2026-10-03.
 
 ---
 
@@ -37,7 +37,8 @@ Sem MediatR, sem AggregateRoot, sem Domain Events, sem CQRS formal, sem reposito
 ├── Extensions/
 │   ├── HandlerRegistrationExtensions.cs  # AddHandlersFromAssembly() com Scrutor Decorate
 │   ├── MapEndpointExtensions.cs          # RegisterApiEndpointsFromAssembly() + MapApiEndpoints()
-│   └── ResultExtensions.cs              # result.Match(onSuccess, onFailure)
+│   ├── ResultExtensions.cs              # result.Match(onSuccess, onFailure)
+│   └── ErrorHttpMapping.cs              # error.ToHttpResult(): ErrorType → status + ProblemDetails
 ├── Features/
 │   └── {Entity}Feature/
 │       ├── {Entity}Errors.cs            # static class {Entity}Errors (factory methods)
@@ -215,9 +216,9 @@ public sealed class CreateBookHandler(
 using FluentValidation;
 namespace {ProjectName}.Features.BookFeature.CreateBook;
 
-public class CreateBookValidator : AbstractValidator<CreateBookRequest>
+public sealed class CreateBookValidator : AbstractValidator<CreateBookRequest>
 {
-    public CreateBookValidator()
+    public CreateBookValidator(TimeProvider timeProvider)
     {
         RuleFor(c => c.Title).NotEmpty().MaximumLength(200);
         RuleFor(c => c.Author).NotEmpty().MaximumLength(100);
@@ -225,7 +226,7 @@ public class CreateBookValidator : AbstractValidator<CreateBookRequest>
         RuleFor(c => c.Price).GreaterThan(0);
         RuleFor(c => c.PublishedYear)
             .GreaterThan(1000)
-            .LessThanOrEqualTo(DateTime.UtcNow.Year);
+            .LessThanOrEqualTo(_ => timeProvider.GetUtcNow().Year);
     }
 }
 ```
@@ -234,6 +235,9 @@ public class CreateBookValidator : AbstractValidator<CreateBookRequest>
 
 ```csharp
 // Features/BookFeature/CreateBook/CreateBookEndpoint.cs
+using {ProjectName}.Abstractions;
+using {ProjectName}.Constants;
+using {ProjectName}.Extensions;
 namespace {ProjectName}.Features.BookFeature.CreateBook;
 
 internal sealed class CreateBookEndpoint : IApiEndpoint
@@ -247,16 +251,18 @@ internal sealed class CreateBookEndpoint : IApiEndpoint
         {
             var result = await handler.HandleAsync(command, cancellationToken);
             return result.Match(
-                onSuccess: () => Results.Ok(result.Value),
-                onFailure: error => Results.BadRequest(error));
+                onSuccess: response => Results.Ok(response),
+                onFailure: error => error.ToHttpResult());
         })
         .WithTags(ApiTags.Books)
         .Produces<CreateBookResponse>(StatusCodes.Status200OK)
-        .Produces(StatusCodes.Status400BadRequest);
+        .ProducesProblem(StatusCodes.Status400BadRequest);
     }
 }
 ```
 
+O lado da falha passa por `error.ToHttpResult()` (`Extensions/ErrorHttpMapping.cs`, código em `backend/dotnet/result-pattern.md` → *Match() Pattern*): o `ErrorType` decide o status (`NotFound` → 404, `Conflict` → 409, `Validation` → 400 com `errors[]`) e a resposta é ProblemDetails. `Results.BadRequest(error)` para todo erro transforma entidade ausente e conflito em 400. O sucesso recebe o valor no lambda: o endpoint nunca lê `result.Value`. Declare um `.ProducesProblem(status)` para cada status de falha que a slice pode devolver.
+
 ### 4. Errors (por feature, não por operação)
 
 ```csharp
@@ -342,6 +348,9 @@ builder.Services.AddSQLDatabaseConfiguration(builder.Configuration);
 // Endpoints (auto-discovery via reflection)
 builder.Services.RegisterApiEndpointsFromAssembly(Assembly.GetExecutingAssembly());
 
+// Relógio injetável (validators e handlers leem TimeProvider, nunca DateTime.UtcNow)
+builder.Services.AddSingleton(TimeProvider.System);
+
 // FluentValidation (auto-discovery)
 builder.Services.AddValidatorsFromAssembly(typeof(Program).Assembly);
 
@@ -380,7 +389,7 @@ app.MapApiEndpoints();
 1. **Handler records no mesmo arquivo**: `Request` e `Response` são declarados no mesmo arquivo `.cs` que o `Handler`.
 2. **`sealed` em tudo**: handlers, endpoints, validators, request/response records usam `sealed`.
 3. **`Guid.CreateVersion7()`** para gerar IDs (não `Guid.NewGuid()`).
-4. **`result.Match()`** nos endpoints — nunca acessar `result.Value` sem checar `IsSuccess`.
+4. **`result.Match()`** nos endpoints — o sucesso recebe o valor no lambda (nunca ler `result.Value`) e a falha vira `error.ToHttpResult()` (status pelo `ErrorType`, nunca `Results.BadRequest` para todo erro).
 5. **IApiEndpoint `internal sealed`** — endpoints não são públicos.
 6. **`{Entity}Errors` compartilhado** por todas as operações da feature (1 arquivo por feature, não por slice).
 7. **`ApplicationDbContext` direto no slice**: CRUD por chave via `DbSet<T>`; queries específicas (joins, projeção, paginação) via LINQ no handler. Nunca uma Application Service layer entre handler e dados; nunca repository genérico (`IRepository<T>`/`IUnitOfWork`).