@polymorphism-tech/morph-spec 8.38.0 → 8.40.0

package/framework/standards/ai-agents/modalities-image-gen.md

@@ -50,8 +50,7 @@ using Microsoft.Extensions.AI;
 using OpenAI.Images;
 
 #pragma warning disable MEAI001 // IImageGenerator e experimental: a superficie pode mudar entre menores
-// AsIImageGenerator() vem de Microsoft.Extensions.AI.OpenAI — um pacote A MAIS.
-// Sem ele, escreva o adaptador (e o kit escreve: ver a nota abaixo).
+// AsIImageGenerator() exige o pacote Microsoft.Extensions.AI.OpenAI, a mais (ver a nota abaixo).
 IImageGenerator generator = new ImageClient("gpt-image-2", apiKey).AsIImageGenerator();
 
 var response = await generator.GenerateAsync(
@@ -197,35 +196,33 @@ trocar a foto de referência **é** outro pedido, mesmo com o prompt idêntico.
 
 ## Exemplo C# completo
 
+O adaptador é de **provider**, não um serviço público que um handler possa chamar: quem produz bytes
+vive atrás do enfileiramento de `ai-agents/media-pipeline.md`, e no kit esse tipo é `internal` de
+propósito. Quatro escolhas do bloco abaixo foram impostas pelo compilador:
+
+- **Sem `using OpenAI.Images;`.** O gerador chega injetado e nenhum tipo do SDK da OpenAI aparece no
+  arquivo; deixar o `using` torna `ImageGenerationOptions` ambíguo (CS0104) entre
+  `Microsoft.Extensions.AI` e `OpenAI.Images`. Onde os dois convivem de verdade, como no adaptador do
+  kit, o tipo vai qualificado.
+- **O pragma abre acima da classe**, não dentro do método: o parâmetro do construtor primário também
+  nomeia `IImageGenerator`, e `MEAI001` é erro por padrão, não aviso. Pragma dentro do corpo deixa a
+  assinatura de fora e o arquivo não compila.
+- **O `IImageGenerator` chega injetado**, não construído aqui, e é isso que faz o exemplo compilar com
+  ou sem `Microsoft.Extensions.AI.OpenAI` no pin (ver a ressalva de §A API): com o pacote,
+  `imageClient.AsIImageGenerator()`; sem ele, um `IImageGenerator` escrito à mão sobre o `ImageClient`,
+  como em `templates/dotnet/ai-kit/src/Morph.AiKit/Media/Providers/OpenAIImageProvider.cs`.
+- **`ReadOnlyMemory<byte>` dos dois lados**, porque é o tipo real de `DataContent.Data`; declarar
+  `BinaryData` não converte (CS0029).
+
+`OriginalImages` é o gancho de edição: com referências, o produto real é preservado em vez de recriado.
+
 ```csharp
-// SEM `using OpenAI.Images;`. Ele nao e necessario aqui — o gerador chega injetado e nenhum
-// tipo do SDK da OpenAI aparece neste arquivo — e deixa-lo torna `ImageGenerationOptions`
-// AMBIGUO (CS0104) entre Microsoft.Extensions.AI e OpenAI.Images. Onde os dois convivem de
-// verdade, como no adaptador do kit, o tipo vai QUALIFICADO.
 using Microsoft.Extensions.AI;
 
-// O pragma abre ACIMA da classe, e nao dentro do metodo: o parametro do construtor primario
-// tambem nomeia IImageGenerator, e MEAI001 e ERRO por padrao — nao aviso. Pragma dentro do
-// corpo deixa a assinatura de fora e o arquivo nao compila.
 #pragma warning disable MEAI001 // IImageGenerator/ImageGenerationRequest sao experimentais: a superficie pode mudar entre menores.
 
-/// <summary>
-/// Adaptador de PROVIDER. Note o que ele NAO e: um servico publico que um handler
-/// possa chamar. Quem produz bytes vive atras do enfileiramento descrito em
-/// ai-agents/media-pipeline.md, e no kit esse tipo e `internal` de proposito.
-/// </summary>
-/// <remarks>
-/// O IImageGenerator chega INJETADO, e nao construido aqui. As duas formas de obte-lo
-/// sao legitimas e a escolha e do seu pin (ver a ressalva da secao "A API"):
-///   - com Microsoft.Extensions.AI.OpenAI no pin:  imageClient.AsIImageGenerator()
-///   - sem ele: um IImageGenerator escrito a mao sobre o ImageClient, como em
-///     templates/dotnet/ai-kit/src/Morph.AiKit/Media/Providers/OpenAIImageProvider.cs
-/// Injetar em vez de construir e o que faz ESTE exemplo compilar nos dois casos.
-/// </remarks>
 internal sealed class OpenAiImageAdapter(IImageGenerator generator)
 {
-    // ReadOnlyMemory<byte> dos dois lados porque e o tipo REAL de DataContent.Data.
-    // Declarar BinaryData aqui nao converte (CS0029) — e o compilador que decide isso.
     public async Task<ReadOnlyMemory<byte>> ProduceAsync(
         string prompt,
         IReadOnlyList<ReadOnlyMemory<byte>> references,
@@ -234,7 +231,6 @@ internal sealed class OpenAiImageAdapter(IImageGenerator generator)
         var request = new ImageGenerationRequest { Prompt = prompt };
         if (references.Count > 0)
         {
-            // OriginalImages e o gancho de EDICAO: preserva o produto real em vez de recria-lo.
             request.OriginalImages = [.. references.Select(r => new DataContent(r, "image/png"))];
         }
 

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

@@ -49,6 +49,8 @@ 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.
+
 ```csharp
 using OpenAI.Audio;
 using Microsoft.Extensions.Configuration;
@@ -64,19 +66,12 @@ public sealed class TranscriptionService
         _client = new AudioClient(model, apiKey);
     }
 
-    /// <summary>
-    /// Transcreve áudio a partir de um arquivo e retorna texto simples.
-    /// O transcript retornado pode ser passado diretamente como input para um AIAgent downstream.
-    /// </summary>
     public async Task<string> TranscribeAsync(string audioFilePath, CancellationToken ct = default)
     {
         AudioTranscription transcription = await _client.TranscribeAudioAsync(audioFilePath, cancellationToken: ct);
         return transcription.Text;
     }
 
-    /// <summary>
-    /// Transcreve áudio a partir de bytes (ex: upload do usuário) e retorna texto simples.
-    /// </summary>
     public async Task<string> TranscribeBytesAsync(
         Stream audioStream,
         string fileName,
@@ -93,9 +88,6 @@ public sealed class TranscriptionService
         return transcription.Text;
     }
 
-    /// <summary>
-    /// Transcreve com timestamps por palavra e segmento (útil para legendas ou busca por trecho).
-    /// </summary>
     public async Task<AudioTranscription> TranscribeVerboseAsync(string audioFilePath, CancellationToken ct = default)
     {
         var options = new AudioTranscriptionOptions
@@ -109,21 +101,18 @@ public sealed class TranscriptionService
 }
 ```
 
-**Alimentando um agente downstream com o transcript:**
+**Alimentando um agente downstream com o transcript** — ele é texto puro, então basta passá-lo como input para qualquer `AIAgent`; aqui, um Status Agent que extrai as ações da reunião:
 
 ```csharp
-// O transcript é texto puro — basta passar como input para qualquer AIAgent
 string transcript = await _transcription.TranscribeAsync("meeting-2024-05-19.mp3");
 
-// Ex: Status Agent que extrai ações da reunião
 AgentResponse<MeetingActions> actions = await _statusAgent.RunAsync<MeetingActions>(
     $"Extraia ações, decisões e responsáveis desta transcrição:\n\n{transcript}");
 ```
 
-**Registro DI:**
+**Registro DI** (`Program.cs`):
 
 ```csharp
-// Program.cs
 builder.Services.AddSingleton<TranscriptionService>();
 ```
 

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

@@ -58,17 +58,11 @@ public sealed class TextToSpeechService
 
     public TextToSpeechService(IConfiguration config)
     {
-        // tts-1: mais rápido, menor qualidade. tts-1-hd: mais lento, maior qualidade.
         var model = config["TTS:Model"] ?? "tts-1";
         var apiKey = config["OpenAI:ApiKey"]!;
         _client = new AudioClient(model, apiKey);
     }
 
-    /// <summary>
-    /// Converte texto em áudio e retorna bytes MP3.
-    /// Cachear o resultado é altamente recomendado para textos repetitivos — gerar o mesmo texto
-    /// duas vezes é desperdício de custo e latência.
-    /// </summary>
     public async Task<BinaryData> SynthesizeAsync(
         string text,
         GeneratedSpeechVoice? voice = null,
@@ -91,14 +85,13 @@ public sealed class TextToSpeechService
 }
 ```
 
-**Registro DI:**
+**Registro DI** (`Program.cs`):
 
 ```csharp
-// Program.cs
 builder.Services.AddSingleton<TextToSpeechService>();
 ```
 
-**Servindo como download ou stream:**
+**Servindo como download ou stream** — verifique o cache antes de gerar (ver Anti-patterns):
 
 ```csharp
 public class AudioController(TextToSpeechService tts) : ControllerBase
@@ -106,14 +99,12 @@ public class AudioController(TextToSpeechService tts) : ControllerBase
     [HttpPost("synthesize")]
     public async Task<IActionResult> Synthesize([FromBody] SynthesizeRequest req)
     {
-        // Verificar cache antes de gerar (ver Anti-patterns)
         BinaryData audio = await tts.SynthesizeAsync(
             text:       req.Text,
             voice:      GeneratedSpeechVoice.Nova,
             format:     GeneratedSpeechFormat.Mp3,
             speedRatio: 1.1f);
 
-        // the storage layer may assign the final name; use a timestamp-based name here
         var fileName = $"tts-{DateTime.UtcNow:yyyyMMddHHmmss}.mp3";
         return File(audio.ToStream(), "audio/mpeg", fileName);
     }

package/framework/standards/ai-agents/modalities-vision.md

@@ -31,7 +31,6 @@ Vision em MAF usa `ChatMessage` multimodal — a mesma abstração `IChatClient`
 ```csharp
 using Microsoft.Extensions.AI;
 
-// Constrói um ChatMessage com texto + imagem
 ChatMessage message = new(ChatRole.User, [
     new TextContent("O que aparece nesta imagem?"),
     new UriContent(new Uri("https://example.com/foto.jpg"), "image/jpeg")
@@ -59,7 +58,7 @@ O `IChatClient` (e portanto `AIAgent`) aceita `IEnumerable<ChatMessage>` — voc
 
 ## Exemplo C# completo
 
-Agente de visão que recebe URL de imagem e retorna descrição. Para extração de dados tipados de um documento, combine com `RunAsync<T>` (ver comentário inline).
+Agente de visão que recebe URL de imagem e retorna descrição. Três entradas: URL pública, arquivo local via `DataContent.LoadFromAsync` (o padrão canônico MAF, preferido sempre que houver o caminho do arquivo) e bytes já em memória (ex: upload de usuário já lido). Para extração de dados tipados de um documento, combine com `RunAsync<T>` em vez de `RunAsync` — `AgentResponse<InvoiceData> r = await _agent.RunAsync<InvoiceData>(message);` e `return r.Result;` —, com o padrão completo em `ai-agents-structured-output`.
 
 ```csharp
 using Microsoft.Agents.AI;
@@ -84,7 +83,6 @@ public sealed class VisionAgent
         });
     }
 
-    /// <summary>Analisa uma imagem por URL pública e retorna descrição em texto.</summary>
     public async Task<string> AnalyzeImageUrlAsync(Uri imageUri, string question, CancellationToken ct = default)
     {
         ChatMessage message = new(ChatRole.User, [
@@ -96,14 +94,6 @@ public sealed class VisionAgent
         return response.Text;
     }
 
-    /// <summary>
-    /// Analisa imagem a partir de um arquivo local ou caminho de upload.
-    /// Usa DataContent.LoadFromAsync — padrão canônico MAF para carregar imagem de arquivo.
-    /// Para extrair dados tipados, use RunAsync&lt;T&gt; em vez de RunAsync:
-    ///   AgentResponse&lt;InvoiceData&gt; r = await _agent.RunAsync&lt;InvoiceData&gt;(message);
-    ///   return r.Result;
-    /// Veja ai-agents-structured-output para o padrão completo.
-    /// </summary>
     public async Task<string> AnalyzeImageFileAsync(string filePath, string question, CancellationToken ct = default)
     {
         DataContent imageContent = await DataContent.LoadFromAsync(filePath);
@@ -116,10 +106,6 @@ public sealed class VisionAgent
         return response.Text;
     }
 
-    /// <summary>
-    /// Analisa imagem a partir de bytes já em memória (ex: upload de usuário já lido).
-    /// Use AnalyzeImageFileAsync quando tiver o caminho do arquivo — é o padrão preferido.
-    /// </summary>
     public async Task<string> AnalyzeImageBytesAsync(BinaryData imageData, string mediaType, string question, CancellationToken ct = default)
     {
         ChatMessage message = new(ChatRole.User, [
@@ -138,17 +124,14 @@ public sealed class VisionAgent
 ```csharp
 var agent = new VisionAgent(modelRegistry);
 
-// Por URL pública
 string desc = await agent.AnalyzeImageUrlAsync(
     new Uri("https://cdn.example.com/invoice-2024.jpg"),
     "Extraia os campos: número da nota, valor total e data de emissão.");
 
-// Por arquivo local — padrão canônico com DataContent.LoadFromAsync
 string desc2 = await agent.AnalyzeImageFileAsync(
     "nota-fiscal.png",
     "Liste todos os itens e valores desta nota fiscal.");
 
-// Por bytes em memória (ex: upload já lido de IFormFile)
 BinaryData data = await BinaryData.FromStreamAsync(formFile.OpenReadStream());
 string desc3 = await agent.AnalyzeImageBytesAsync(data, "image/png",
     "Descreva o conteúdo da imagem enviada.");

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

@@ -113,10 +113,6 @@ Interface contract:
 ```csharp
 public interface IPromptRepository
 {
-    /// <summary>
-    /// Returns the content of the currently active prompt for the given agent key.
-    /// Throws <see cref="InvalidOperationException"/> if no active prompt exists.
-    /// </summary>
     Task<string> GetActivePromptAsync(string agentKey, CancellationToken ct = default);
 }
 ```

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

@@ -9,8 +9,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 padrão é nenhum comentário.** O código se explica pelos nomes, pelos tipos e pelos testes. Um
+comentário é relido a cada leitura do arquivo, por quem mantém e pelo agente que abre o arquivo na
+próxima task, e ninguém o atualiza quando o código muda. Ele só entra quando diz algo que o código
+**não consegue** dizer, e isso é raro: a maioria dos arquivos não tem nenhum.
+
+## Antes de escrever um comentário
+
+Tente, nesta ordem, e pare no primeiro que resolve:
+
+| Em vez de comentar... | Faça |
+|---|---|
+| o que uma variável ou função é | renomeie: `retryDelayMs`, `isEligibleForRefund()` |
+| o que um trecho faz | extraia uma função com esse nome |
+| um número ou string mágica | extraia uma constante nomeada |
+| um estado que não pode acontecer | expresse no tipo (enum, união, record, `required`) |
+| o que o código garante | escreva um teste que falha quando deixar de valer |
+
+Só sobrando algo que nenhum desses expressa, o comentário entra.
 
 ## O que merece comentário
 
@@ -21,15 +37,22 @@ Só o **porquê que o código não mostra**:
 | 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 |
+| Contrato de pacote publicado | `///` ou JSDoc só em API de pacote consumido **fora** deste repositório (NuGet, npm) |
 
 ## 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.
+- **Repetição do código.** `// incrementa o contador` sobre `count++`, `// valida o request` sobre
+  `validator.Validate(request)`. Nome bom substitui comentário.
+- **Doc-comment que repete a assinatura.** `/// <summary>Obtém o pedido.</summary>` sobre
+  `GetOrder()`, JSDoc com `@param id o id`. Membro de aplicação (handler, endpoint, componente,
+  serviço interno) não leva `///` nem JSDoc, mesmo sendo `public`.
+- **Estrutura e decoração.** Cabeçalho de arquivo, banner de seção (`// ---- Handlers ----`,
+  `#region`), comentário que só rotula o bloco seguinte.
+- **Código comentado e TODO solto.** O git guarda o código antigo; pendência vira issue, e o
+  comentário, se ficar, cita o número dela.
 - **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 é
@@ -37,27 +60,40 @@ Só o **porquê que o código não mostra**:
 
 ## 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.
+Uma linha é o normal; teto de ~3. 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. Em volume, código de aplicação fica perto de zero: mais de uma linha de comentário a
+cada dez de código é sinal de que os nomes não estão fazendo o trabalho.
 
 ## 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.
+// Ruim: rotula, conta a task, repete o código e afirma comportamento que nenhum teste cobra.
+/**
+ * Salva o documento.
+ * @param doc o documento
+ */
+// T8 + T11: mutação obrigatória do relatório, item c. Faz upsert e nunca duplica.
+async function save(doc: Doc) {
+  await upsert({ key: doc.sourceId, hash: sha256(doc.body) });
+}
+
+// Bom: sem comentário nenhum, porque o nome e a chamada já dizem tudo...
+async function save(doc: Doc) {
+  await upsert({ key: doc.sourceId, hash: sha256(doc.body) });
+}
+
+// ...e um comentário só quando há um porquê invisível.
 // 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.
+Comentário que o código dispensava é achado da rubrica `code-quality` no Gate 3. 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.
 
 ---