@polymorphism-tech/morph-spec 8.43.0 → 8.45.0

package/framework/standards/ai-agents/tool-adapters.md

@@ -0,0 +1,226 @@
+# Tool Adapters — a regra em `*Ops`, o texto do modelo no adaptador
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 2 (on-keyword)
+> **Keywords:** tool, AIFunctionFactory, adaptador de tool, tool fina, Ops, Desfecho, Render, regra de negócio em tool, descrição da tool, golden de tool, refactor neutro, migração de teste
+> **Read by Claude in:** implement (ao escrever ou migrar uma tool de agente que carrega regra de negócio)
+
+**Verified against:** Microsoft.Extensions.AI 10.9.0 + Microsoft.Agents.AI 1.20.0 (ai-pin 2026-09-08); os dois blocos C# abaixo foram extraídos com `scripts/extract-doc-csharp.mjs` e compilados contra o pin com `TreatWarningsAsErrors`, e os três testes do segundo bloco foram executados e passam. **A separação em si e a migração de teste são verificação documental:** vêm da feature `tools-finas` do MORPH_GHLBrain e o ai-kit não as traz. Last-verified: 2026-09-08.
+
+---
+
+## Fronteira com os outros standards
+
+`ai-agents-mcp-tools` cobre **consumir** tools de um MCP server. `ai-agents-testing-ai` cobre **testar** um agente sem rede. `backend-dotnet-testing` é dono de xUnit, relógio falso e orçamento de teste. **Nada disso se repete aqui.**
+
+Este standard cobre uma coisa só: a tool que o agente chama **e que carrega regra**. Onde mora a regra, onde mora a frase que o modelo lê, e como se testa cada uma sem que uma mascare a outra.
+
+## O problema
+
+Uma tool nasce como uma lambda dentro do `AIFunctionFactory.Create`. Enquanto é só "chame a API e devolva", serve. Quando ganha regra, a lambda passa a misturar três coisas que mudam por motivos diferentes:
+
+| O que é | Muda quando | Quem lê |
+|---|---|---|
+| a **regra** (validar, decidir, gravar) | o negócio muda | o código e o teste |
+| a **frase para o modelo** (descrição, recusa, instrução de correção) | o prompt é ajustado | o modelo |
+| o **efeito** (task, nota, mensagem entregue por código) | o processo muda | um humano |
+
+Misturadas, o único teste possível é por string: qualquer ajuste de redação quebra o teste da regra, e qualquer refactor da regra arrisca mudar, sem ninguém ver, o que o modelo lê.
+
+## O padrão
+
+```
+   o modelo chama                                          o modelo lê
+ ┌──────────────┐    pedido tipado    ┌───────────┐  desfecho  ┌────────────────┐
+ │  Adaptador   │ ──────────────────► │   *Ops    │ ─────────► │ Render(desfecho)│
+ │ (tool fina)  │                     │ (a regra) │  tipado    │ (frase p/ modelo)│
+ └──────────────┘ ◄───────────────────────────────────────────└────────────────┘
+```
+
+1. **`Ops`, não `Service`.** Regra determinística com dependências injetadas vira `sealed class XOps(...)`, com construtor primário e um `AddScoped` explícito. `*Service` colide com a proibição de camada de Service/Manager entre handler e dados; `*Ops` é outra coisa: a regra de uma tool, não um intermediário de persistência.
+2. **Desfecho tipado, e a fronteira é quem lê o texto.** Cada método de `Ops` devolve um `abstract record XDesfecho` com um `sealed record` por caso. A frase para o **modelo** (descrição, recusa, instrução de autocorreção, sucesso, a decisão de "tool indisponível") mora no adaptador, em `public static object Render(XDesfecho)`. O texto para **humano** entregue por código (corpo de task, nota, ack) mora na `Ops`, porque é efeito. É verificável por `grep`: a `Ops` não cita o nome da tool nem dá instrução ao modelo.
+3. **Adaptador fino.** `AIFunctionFactory.Create` com a lambda montando o pedido tipado, chamando a `Ops` e devolvendo `Render(desfecho)`. A régua é **zero regra no adaptador**, não um número de linhas: uma descrição dinâmica pode ser longa e tem de continuar byte a byte.
+4. **Testes em duas camadas.** O teste da `Ops` asserta desfecho, chamadas e ordem no fake, **nunca texto**. O teste de contrato asserta o `Render` com o literal exato e a `.Description`. Um golden de nome, descrição e schema, por tenant real, protege a superfície que o modelo lê.
+5. **Refactor neutro se prova antes de migrar teste.** Primeiro um commit de prova, com a suíte antiga intocada e verde (inclusive os evals offline); só depois a migração dos testes, com mutação rodando **só** contra os testes novos.
+
+## Exemplo C# completo
+
+A regra, o desfecho, o adaptador e o registro. O pedido é tipado, então a lambda não decide nada: monta, chama, renderiza.
+
+```csharp
+using System.ComponentModel;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.DependencyInjection;
+
+namespace Exemplo.Tools;
+
+public interface IAgendaExterna
+{
+    Task<int> CapacidadeAsync(string salaId, CancellationToken ct);
+    Task<string> GravarAsync(ReservaPedido pedido, CancellationToken ct);
+}
+
+public sealed record ReservaPedido(string SalaId, DateOnly Dia, int Pessoas);
+
+public abstract record ReservaDesfecho
+{
+    public sealed record Reservada(string ConfirmacaoId) : ReservaDesfecho;
+    public sealed record SalaCheia(int Capacidade) : ReservaDesfecho;
+    public sealed record DiaSemExpediente(DateOnly Dia) : ReservaDesfecho;
+}
+
+public sealed class ReservaOps(IAgendaExterna agenda)
+{
+    public async Task<ReservaDesfecho> ReservarAsync(ReservaPedido pedido, CancellationToken ct)
+    {
+        if (pedido.Dia.DayOfWeek is DayOfWeek.Saturday or DayOfWeek.Sunday)
+            return new ReservaDesfecho.DiaSemExpediente(pedido.Dia);
+
+        var capacidade = await agenda.CapacidadeAsync(pedido.SalaId, ct);
+        if (pedido.Pessoas > capacidade)
+            return new ReservaDesfecho.SalaCheia(capacidade);
+
+        return new ReservaDesfecho.Reservada(await agenda.GravarAsync(pedido, ct));
+    }
+}
+
+public static class ReservarSalaTool
+{
+    public const string Name = "reservar_sala";
+
+    public static AIFunction Create(ReservaOps ops) =>
+        AIFunctionFactory.Create(
+            async (
+                [Description("Identificador da sala, como listado por consultar_salas")] string salaId,
+                [Description("Dia da reserva, AAAA-MM-DD")] DateOnly dia,
+                [Description("Quantidade de pessoas")] int pessoas,
+                CancellationToken ct) =>
+                Render(await ops.ReservarAsync(new ReservaPedido(salaId, dia, pessoas), ct)),
+            Name,
+            "Reserva uma sala para um dia. Só chame depois de confirmar sala, dia e número de pessoas com o cliente.");
+
+    public static object Render(ReservaDesfecho desfecho) => desfecho switch
+    {
+        ReservaDesfecho.Reservada r => new { ok = true, confirmacao = r.ConfirmacaoId },
+        ReservaDesfecho.SalaCheia c => new { ok = false, erro = $"A sala comporta no máximo {c.Capacidade} pessoas. Ofereça outra sala ou reduza o grupo." },
+        ReservaDesfecho.DiaSemExpediente d => new { ok = false, erro = $"{d.Dia:yyyy-MM-dd} não tem expediente. Peça outro dia." },
+        _ => throw new ArgumentOutOfRangeException(nameof(desfecho)),
+    };
+}
+
+public static class ReservaToolsRegistration
+{
+    public static IServiceCollection AddReservaTools(this IServiceCollection services) =>
+        services.AddScoped<ReservaOps>();
+}
+```
+
+A checagem de fronteira é um `grep`, e tem de sair vazio: a `Ops` não conhece a tool nem fala com o modelo.
+
+```bash
+grep -rnE "reservar_sala|Ofereça|Peça|AIFunction" Features/Reservas/Ops/
+```
+
+## Os testes das duas camadas
+
+O teste da `Ops` compara **tipos e chamadas**; o de contrato compara **o texto que o modelo lê**. Trocar a redação de uma recusa quebra só o segundo.
+
+```csharp
+using System.Text.Encodings.Web;
+using System.Text.Json;
+using Exemplo.Tools;
+using Xunit;
+
+namespace Exemplo.Tools.Tests;
+
+internal sealed class AgendaFake(int capacidade) : IAgendaExterna
+{
+    public List<string> Chamadas { get; } = [];
+
+    public Task<int> CapacidadeAsync(string salaId, CancellationToken ct)
+    {
+        Chamadas.Add($"capacidade:{salaId}");
+        return Task.FromResult(capacidade);
+    }
+
+    public Task<string> GravarAsync(ReservaPedido pedido, CancellationToken ct)
+    {
+        Chamadas.Add($"gravar:{pedido.SalaId}");
+        return Task.FromResult("R-1");
+    }
+}
+
+public sealed class ReservaOpsTests
+{
+    [Fact]
+    public async Task Sala_cheia_nao_grava_e_devolve_a_capacidade()
+    {
+        var agenda = new AgendaFake(capacidade: 4);
+        var ops = new ReservaOps(agenda);
+
+        var desfecho = await ops.ReservarAsync(new ReservaPedido("s1", new DateOnly(2026, 10, 5), 6), CancellationToken.None);
+
+        Assert.Equal(new ReservaDesfecho.SalaCheia(4), desfecho);
+        Assert.Equal(["capacidade:s1"], agenda.Chamadas);
+    }
+}
+
+public sealed class ReservarSalaToolTests
+{
+    private static readonly JsonSerializerOptions Literal = new() { Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping };
+
+    [Fact]
+    public void Render_da_sala_cheia_diz_ao_modelo_o_que_fazer()
+    {
+        var json = JsonSerializer.Serialize(ReservarSalaTool.Render(new ReservaDesfecho.SalaCheia(4)), Literal);
+
+        Assert.Equal("{\"ok\":false,\"erro\":\"A sala comporta no máximo 4 pessoas. Ofereça outra sala ou reduza o grupo.\"}", json);
+    }
+
+    [Fact]
+    public void A_superficie_que_o_modelo_le_nao_mudou()
+    {
+        var tool = ReservarSalaTool.Create(new ReservaOps(new AgendaFake(capacidade: 10)));
+
+        Assert.Equal("reservar_sala", tool.Name);
+        Assert.StartsWith("Reserva uma sala para um dia.", tool.Description);
+        Assert.Contains("\"salaId\"", tool.JsonSchema.GetRawText());
+    }
+}
+```
+
+## Migrar uma tool que já tem a regra no adaptador
+
+A migração é um refactor que **não pode mudar o que o modelo lê**. Por isso ela tem ordem:
+
+1. **Commit de prova.** Extraia a `Ops` e o `Render` sem tocar nenhum teste. A suíte antiga tem de continuar verde, inclusive os evals offline. Esse commit é a âncora: prova que o refactor é neutro.
+2. **Migre os testes**, e só depois de o commit de prova estar verde.
+3. **Matriz de migração.** Liste cada asserção antiga e a asserção nova que a cobre. "Já está coberto pelo teste X" precisa de prova **asserção por asserção**: na migração que originou este standard, 11 de 22 alegações desse tipo tinham perdido alguma asserção do teste antigo.
+4. **Os testes que ficam na origem têm de ser idênticos à base.** A migração só apaga. Uma checagem byte a byte dos métodos restantes contra o commit de prova pegou (e provou corrigidos) `Edit`s que casaram no método errado.
+5. **Mutação só contra os testes novos.** Ela acha lacunas que a suíte antiga nunca protegeu: em duas das três `Ops` migradas apareceram regras sem teste algum (valor digitado pelo comercial sobrescrito pelo catálogo, campos reafirmados sumindo da falha do `PUT`, corpo de update reenviando valor igual).
+
+## Exemplos reais
+
+MORPH_GHLBrain, `src/Morph.GHLBrain/Features/Conversation/Operator/`:
+
+| Tool | Adaptador | `Ops` | Desfecho |
+|---|---|---|---|
+| `finalizar_handoff` | `Tools/FinalizarHandoffTool.cs` | `Ops/HandoffOps.cs` | `HandoffDesfecho` |
+| `atualizar_dossie` | `Tools/AtualizarDossieTool.cs` | `Ops/DossieOps.cs` | `DossieDesfecho` |
+| `set_lead_fields` | `Tools/SetLeadFieldsTool.cs` | `Ops/DossieOps.cs` | `CamposDesfecho` |
+| `route_lead` | `Tools/RouteLeadTool.cs` | `Ops/TriagemOps.cs` | `TriagemDesfecho` |
+
+As decisões estão em `.morph/features/tools-finas/2-plan/decisions.md` (ADR-1 e ADR-2) daquele repositório.
+
+## Regras
+
+- **ALWAYS** a regra de uma tool vai numa `sealed class XOps(...)` com construtor primário e `AddScoped` explícito
+- **NEVER** chame essa classe de `*Service` ou `*Manager`: o MORPH.md proíbe essa camada entre handler e dados, e `*Ops` é a forma da casa
+- **ALWAYS** cada método de `Ops` devolve um `abstract record XDesfecho`, com um `sealed record` por caso que a regra distingue
+- **NEVER** ponha na `Ops` uma frase para o modelo, o nome da tool ou uma instrução de autocorreção. Verifique por `grep`
+- **ALWAYS** o texto para humano entregue por código (task, nota, ack) fica na `Ops`: é efeito
+- **ALWAYS** o adaptador só monta o pedido tipado, chama a `Ops` e devolve `Render(desfecho)`. Zero regra ali; descrição dinâmica longa é permitida e segue byte a byte
+- **ALWAYS** o teste da `Ops` asserta desfecho, chamadas e ordem no fake, nunca texto
+- **ALWAYS** o teste de contrato asserta o `Render` com o literal exato e a `.Description`, e há um golden de nome, descrição e schema por tenant real
+- **NEVER** declare "já coberto" sem a asserção nova que cobre cada asserção antiga
+- **NEVER** migre o teste antes do commit de prova verde, nem deixe na origem um teste diferente da base

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

@@ -171,7 +171,7 @@ This maps conceptually onto the existing custom pattern: `IngestionDocumentReade
 
 ---
 
-## Checklist (verifiable by morph-eval)
+## Checklist (verifiable in review)
 
 - [ ] 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.

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

@@ -183,7 +183,7 @@ Sempre use `await using` no `StreamingRun` / `Run` — é `IAsyncDisposable`.
 
 ---
 
-## Checklist (verifiable by morph-eval)
+## Checklist (verifiable in review)
 
 - [ ] Foi verificado que um `foreach` ou single agent não resolve o problema?
 - [ ] O critério de fan-in/out genuíno ou HITL está documentado em `decisions.md`?

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

@@ -27,6 +27,16 @@ The harness gives each worktree a **block of 10 ports** (`.morph/worktree.env`,
 
 Also exported: `COMPOSE_PROJECT_NAME=morph-{feature}` (isolates container, network and volume names), `MORPH_PORT_BASE`, `MORPH_PORT_RANGE`, `PLAYWRIGHT_BASE_URL=http://localhost:<+0>`.
 
+## Project-named port variables
+
+The harness exports only the four names above. A compose file that reads a port by another name (`"${PG_PORT:-5433}:5432"`) is **not** fed by the block: it publishes its own default, or whatever a `.env.e2e` copied from a sibling worktree carries, while `worktree.env` announces a different port. Hand-run specs then hit a closed port, or worse, seed one postgres and read another. Declare the name the project reads:
+
+```json
+{ "e2e": { "portEnvNames": { "postgres": "PG_PORT" } } }
+```
+
+Keys are `web`, `api`, `postgres` and `redis`. Each declared name carries the **same value** as the standard variable, everywhere the layout goes: `worktree.env`, the compose env of `verify`/`e2e up`/`morph-spec env`, and the `PreToolUse:Bash` hook. Being layout, it is ignored (and named on stderr) if the credentials file carries it. An entry the harness cannot honour — unknown port, invalid or reserved name, a name used twice — is dropped and named on stderr.
+
 ## Core Rules
 
 - NEVER set `container_name` — Compose already names containers `<project>-<service>-1`, and an explicit name is shared by every worktree
@@ -36,7 +46,7 @@ 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
+- NEVER put a variable from the port layout table above (nor `PLAYWRIGHT_BASE_URL`, nor a name declared in `e2e.portEnvNames`) 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
 

package/framework/templates/CLAUDE.md.core.template

@@ -18,5 +18,5 @@ morph-spec NLH — leia `.morph/framework/MORPH.md` ao iniciar cada sessão. Em
 
 ## Slash commands
 
-- `/morph-proposal {feature}` — entendimento de negócio + spec/mandate/tasks (Gates 1 e 2)
+- `/morph-proposal {feature}` — entendimento de negócio + use cases, spec e tasks (Gates 1 e 2)
 - `/morph-apply {feature}` — execução autônoma das tarefas + review (Gate 3)