@polymorphism-tech/morph-spec 8.43.0 → 8.45.0

package/framework/skills/core/morph-standards/SKILL.md

@@ -4,7 +4,7 @@ description: Localiza um standard específico via busca server-side (morph-spec
 version: core
 when-to-invoke: quando precisar consultar um standard específico durante a implementação
 user-invokable: true
-cliVersion: "8.43.0"
+cliVersion: "8.45.0"
 ---
 
 # morph-standards
@@ -16,7 +16,7 @@ para aplicar o standard na maioria dos casos.
 
 ## Quando invocar
 Quando durante a implementação surgir uma dúvida de padrão arquitetural, de contrato, de qualidade
-ou de teste — e o mandate.md não for suficiente para resolver.
+ou de teste — e o `spec.md` e os standards da task não bastarem para resolver.
 
 ## O que fazer
 

package/framework/skills/core/morph-uiux/SKILL.md

@@ -4,7 +4,7 @@ description: Conduz a fase opcional de UI/UX — design system, mockups, compone
 version: core
 when-to-invoke: ao tomar o ramo uiux (morph-spec advance --design), depois do Gate 1 e antes do morph-plan
 user-invokable: true
-cliVersion: "8.43.0"
+cliVersion: "8.45.0"
 ---
 
 # morph-uiux
@@ -89,8 +89,7 @@ Ao tomar o ramo opcional uiux: feature/bug cuja mudança cria ou altera superfí
 
    Cada relatório contém: (1) o que foi feito em 2-3 frases, (2) o artefato produzido,
    (3) decisões de design e por quê (token reusado vs. novo, padrão de acessibilidade
-   aplicado), (4) auto-score 0-10 com justificativa em uma linha. Relatório ausente, oco,
-   ou sem os 4 itens, é falha de protocolo.
+   aplicado), (4) o que ficou em aberto. Relatório ausente ou oco é falha de protocolo.
    ```
 
    Após o retorno: **leia primeiro** `1-design/reports/*-report.md` — valor de retorno autoritativo, a mensagem de texto é atalho best-effort quando chega inteira. `design-system.md` é o único output obrigatório (`phases.json → uiux.requiredOutputs`); sem ele em disco, `morph-spec advance` recusa avançar — confirme que existe antes de rodar `advance` no passo 6.

package/framework/standards/STANDARDS.json

@@ -33,7 +33,7 @@
         "visao": "#visão-com-structured-output",
         "historico": "#chat-com-histórico",
         "lastro": "#lastro-de-campo-por-arquétipo",
-        "checklist": "#checklist-verifiable-by-morph-eval"
+        "checklist": "#checklist-verifiable-in-review"
       },
       "digest": "The four shapes an agent can take, and the plan-phase question that picks one: conversational-with-phases, one-shot batch, vision + structured output, chat with history. Field ballast is UNEVEN and the standard says so: batch has 3 exemplars, conversational has 1, vision+structured has ZERO (it is a projected shape, not a distilled one), and conversational and chat-with-history are two AXES OF THE SAME AGENT (phases x history ownership), not alternatives. Pairs with ai-agents-sweet-spot, which decides agent-vs-workflow before this file decides which shape.",
       "verifiedAgainst": "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/Agents/AgentFactory.cs` e `.../Conversation/ConversationStore.cs` (arquétipos **one-shot em batch** e **chat com histórico** — o conversacional com fases NÃO tem lastro no kit, e `ai-agents-conversational-agent-with-phases` declara isso no próprio cabeçalho). O arquétipo visão + structured output é **verificação documental** — o ai-kit não exercita multimodalidade.",
@@ -112,7 +112,7 @@
         "catalogo": "#agentcatalog",
         "defaults": "#defaults-fora-do-código",
         "higiene": "#higiene-de-publicação",
-        "checklist": "#checklist-verifiable-by-morph-eval"
+        "checklist": "#checklist-verifiable-in-review"
       },
       "digest": "The agent as DATA: one immutable AgentSpec record per agent (Alias required, Instructions required, Api?, Tools, OutputSchema?, Options, Name?, Description?), a catalog that enumerates them, and defaults outside the code. The doctrine this standard freezes: a NULL property means \"do not send to the provider\", never \"send the framework default\" — and an empty list is NOT treated as null, it is sent as written. Precedence between the spec api and the alias api lives in ONE method on the record, never inside the factory. Blank Alias/Instructions are rejected at construction. A catalog entry with no runtime consumer is dead weight (measured: a seeded agent with a versioned prompt and zero C# callers).",
       "verifiedAgainst": "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/Agents/AgentSpec.cs`, `.../Agents/AgentSpecOptions.cs` e `.../Agents/AgentFactory.cs` — o record, o bag de opções e a materialização são exatamente o que o kit compila.",
@@ -228,7 +228,7 @@
         "requireany": "#exigir-tool-no-turno",
         "teto": "#teto-de-tool-calls-e-isenta",
         "auxiliar": "#agente-auxiliar-em-sequência",
-        "checklist": "#checklist-verifiable-by-morph-eval"
+        "checklist": "#checklist-verifiable-in-review"
       },
       "digest": "ONE agent, phase as turn data — the deep dive on the first archetype, and it DECLARES a single field source in its own body. A deterministic turn composer (pure static class, no I/O) yields the turn plan; the prompt is born decomposed into NAMED BLOCKS and the text sent IS the concatenation, derived without cache ON PURPOSE, \"so telemetry cannot lie\" — the invariant that makes a prompt hash worth anything. Allow-list prunes in two stages (phase, then tenant capability), a tool absent from the map is AVAILABLE, and pruning preserves order. Tool-call ceiling with an exempt tool, at agent level (not ChatOptions). ChatToolMode.RequireAny exists (measured by reflection) and is the default when every action is a tool — but it ships with an EXIT CRITERION, not a blind prescription: the field alternative (a second pass) has 7 tests and a \"recovered\" outcome, so migrate when the recovered rate stops paying for the second paid call. An auxiliary agent runs in sequence, never nested inside a tool call.",
       "verifiedAgainst": "Microsoft.Extensions.AI 10.9.0 + Microsoft.Agents.AI 1.20.0 (ai-pin 2026-09-08). `ChatToolMode.RequireAny` foi **medido por reflexão sobre `Microsoft.Extensions.AI.Abstractions` 10.9.0** em 2026-09-08. O restante é **verificação documental**, sem cláusula `provado por` — o ai-kit ainda não traz um compositor de turno, e o padrão é destilado de um único repositório de campo (ver a nota de fonte única abaixo).",
@@ -267,7 +267,7 @@
         "teto": "#teto-de-orçamento",
         "total": "#medir-o-total-não-o-piso",
         "fronteira": "#fronteira-com-observability-patterns",
-        "checklist": "#checklist-verifiable-by-morph-eval"
+        "checklist": "#checklist-verifiable-in-review"
       },
       "digest": "The only owner of COST as a subject. The SDK gives tokens and does not give money: UsageDetails (measured by reflection on Microsoft.Extensions.AI.Abstractions 10.9.0) exposes Input/Output/Total/Cached/Reasoning counts, the text-audio pairs, AdditionalCounts and Add() — and NO price property. So the tariff lives per alias in the registry, WITH a verification date, and an alias without a tariff must carry a written waiver. One middleware, above function-invocation in the pipeline (measured: above it, Usage already totals every tool round and one line is published per call). Three formula traps: reasoning tokens billed as output, CACHED input is a SUBSET of input (adding them double-counts), and hosted-operation flat fees never appear in UsageDetails. cost_usd is NEVER null: zero with an explicit state — Computed / Waived / UsageMissing. Budget UNIT is a parameter (lead, tenant, operation, day); the measured pain is one of PLACE — a ceiling living inside a tool does not govern the pipeline. Warn before blocking, and the block returns an actionable sentence to the model, never an exception. Two-way delegation with ai-agents-observability-patterns: span attributes stay there, tariff and ceiling live here.",
       "verifiedAgainst": "Microsoft.Extensions.AI 10.9.0 + Microsoft.Agents.AI 1.20.0 (ai-pin 2026-09-08); provado por `templates/dotnet/ai-kit/src/Morph.AiKit/Middleware/UsageCostMiddleware.cs`, `.../Middleware/UsageCostRecord.cs` e `.../Providers/ModelAlias.cs` — o middleware, o record de custo não-nulo e a conta de tarifa são o que o kit compila. A ausência de qualquer propriedade de preço em `UsageDetails` foi **medida por reflexão sobre `Microsoft.Extensions.AI.Abstractions` 10.9.0** em 2026-09-08. O teto de orçamento é **verificação documental** — o ai-kit não traz um middleware de orçamento.",
@@ -398,7 +398,7 @@
         "argumento": "#argumento-de-tool-é-input-não-confiável",
         "pertinencia": "#pertinência-não-presença",
         "failopen": "#quando-o-guard-não-consegue-decidir",
-        "checklist": "#checklist-verifiable-by-morph-eval"
+        "checklist": "#checklist-verifiable-in-review"
       },
       "digest": "What the CODE guarantees once the prompt has already failed. A rule with real consequence leaves the prompt and becomes a C# condition — the measured reason, written in field code: the model obeys \"one entry per element of this list\" but errs badly when it must judge on its own which blocks have data (10 expected, 2 delivered). Three legitimate choke-points (before the turn in the composer; in the function-invocation middleware, with a CLOSED outcome vocabulary ok/error/invalid_args/limit/unavailable and required arguments read from the function JSON schema; after the run as backstop). Tool arguments are UNTRUSTED input: ids and money come from the turn closure, never from the model. Relevance, not presence: compare against something that did NOT come from the model — a deterministic rubric checked BY EQUALITY against the backend numbers, a provenance lock that demotes an unsupported \"found\" while PRESERVING the reasoning for audit, and a per-source confidence floor. When the guard cannot decide the answer is FAIL-OPEN, ratified with one hard condition: the escape is RECORDED (the anti-pattern is 81 of 83 catch blocks that never read the exception). Verdict is ternary — pass / reject / not_evaluated — because a boolean turns \"could not evaluate\" into \"approved\".",
       "verifiedAgainst": "Microsoft.Extensions.AI 10.9.0 + Microsoft.Agents.AI 1.20.0 (ai-pin 2026-09-08). **Verificação documental**, sem cláusula `provado por` — o ai-kit não traz um guard de exemplo; o padrão é destilado de dois repositórios em produção, com o local de cada evidência citado na seção correspondente.",
@@ -436,7 +436,7 @@
         "strict": "#strict-json-schema-por-alias",
         "temperature": "#temperature-e-reasoning",
         "pin": "#pin-de-sdk-e-compatibilidade-binária",
-        "checklist": "#checklist-verifiable-by-morph-eval"
+        "checklist": "#checklist-verifiable-in-review"
       },
       "digest": "The runtime KNOBS of a model call, with the boundary against ai-agents-providers-model-registry (Layer 0, which owns the SCHEMA) written as the first section. Retry is INHERITED from the System.ClientModel pipeline — do not stack a loop on top (3 x 3 = 9 paid calls). Timeout is NOT inherited and must be created: ChatOptions has no timeout property (measured by reflection) and OpenAIClientOptions declares only Endpoint/OrganizationId/ProjectId/UserAgentApplicationId — the knob comes from the ClientPipelineOptions base. A CancellationToken is not a timeout. StrictJsonSchema DOES NOT EXIST: zero exported types containing \"Strict\" across the 14 pinned assemblies, and ChatResponseFormatJson has no strict field; the real mechanism is a key in ChatOptions.AdditionalProperties, so strict is per alias and NEVER a process-global flag. ReasoningEffort is a first-class enum (None/Low/Medium/High/ExtraHigh). Pin AI packages exactly — a floating 2.* range cost a MissingMethodException after the call was already paid for.",
       "verifiedAgainst": "Microsoft.Extensions.AI 10.9.0 + Microsoft.Agents.AI 1.20.0 + OpenAI 2.13.0 (ai-pin 2026-09-08); provado por `templates/dotnet/ai-kit/src/Morph.AiKit/Providers/ModelAlias.cs` e `.../Providers/ModelRegistry.cs` (alias, `api:`, e limite por alias com procedência obrigatória). A superfície do SDK citada aqui — `ChatOptions`, `ChatResponseFormatJson`, `ReasoningEffort`, `OpenAIClientOptions` — foi **medida por reflexão sobre as assemblies do pin** em 2026-09-08. O timeout é **provado por** `.../Agents/AgentSpecOptions.cs` e `.../Agents/AgentFactory.cs`, que o kit compila **por spec** (`TimeoutSeconds` vira um cliente de timeout no pipeline) — e **não** por alias: a allowlist de alias do registry não tem chave de timeout (medido). Os valores default do retry do `System.ClientModel` 1.15.0 são **verificação documental** — essa assembly está fora do conjunto que o probe carrega.",
@@ -866,7 +866,7 @@
         "rastreabilidade": "#rastreabilidade-do-que-foi-ao-provedor",
         "convencao": "#estabilidade-da-convenção-genai--a-ressalva-que-muda-como-ler-a-tabela-acima"
       },
-      "digest": "Canonical treatment of OpenTelemetry for MAF agents: setup, enrichment, investigation. Two DIFFERENT ActivitySources must be registered — Experimental.Microsoft.Agents.AI (span invoke_agent) and Experimental.Microsoft.Extensions.AI (spans chat and execute_tool, metrics gen_ai.client.operation.duration and gen_ai.client.token.usage). AgentOpenTelemetryConsts and agent.WithOpenTelemetry() do NOT exist in 1.20.0; the API is builder.UseOpenTelemetry(sourceName, configure) and the sensitive-data switch is EnableSensitiveData (same name on OpenTelemetryAgent and OpenTelemetryChatClient). Duplication rule, measured: instrumenting the two LEVELS is normal and does not duplicate; instrumenting the same level twice does. With a custom pipeline (UseProvidedChatClientAsIs) the MAF guard does not reach it and chat instrumentation becomes mandatory. Issue 3637 (no GenAI ActivityEvents) is a known open limitation. TRACEABILITY (added 2026-09-08): the question the instrumentation exists to answer is whether the turn can be RECONSTRUCTED — raw prompt only in dev/harness with opt-in, HASH in production, and the invariant that makes the hash worth anything is that the text sent is derived from named blocks WITHOUT cache (a cache between assembly and send lets telemetry and request diverge in silence). Two closing assertions: the offered tool list came from the real turn list, and a CANCELLED turn writes nothing. CONVENTION STABILITY: the GenAI semantic conventions LEFT the main OpenTelemetry repo — semconv v1.42.0 (2026-06-12) deprecated and moved all of gen_ai.*, v1.43.0 carries none, the content lives in open-telemetry/semantic-conventions-genai where NOTHING GenAI is Stable (all Development; only error.type/server.address/server.port are stable, and those are common attributes), while OpenTelemetryChatClient declares v1.37 — behind the split. Instrument anyway, but do not build an alert whose only identifier is a gen_ai.* name without a rename plan. Cost delegation is two-way: tariff, cost formula and budget ceiling live in ai-agents-cost-and-budget; span attributes stay here. The Gate 3 ruler for this property is evals/proof-rubrics/observabilidade-genai.md.",
+      "digest": "Canonical treatment of OpenTelemetry for MAF agents: setup, enrichment, investigation. Two DIFFERENT ActivitySources must be registered — Experimental.Microsoft.Agents.AI (span invoke_agent) and Experimental.Microsoft.Extensions.AI (spans chat and execute_tool, metrics gen_ai.client.operation.duration and gen_ai.client.token.usage). AgentOpenTelemetryConsts and agent.WithOpenTelemetry() do NOT exist in 1.20.0; the API is builder.UseOpenTelemetry(sourceName, configure) and the sensitive-data switch is EnableSensitiveData (same name on OpenTelemetryAgent and OpenTelemetryChatClient). Duplication rule, measured: instrumenting the two LEVELS is normal and does not duplicate; instrumenting the same level twice does. With a custom pipeline (UseProvidedChatClientAsIs) the MAF guard does not reach it and chat instrumentation becomes mandatory. Issue 3637 (no GenAI ActivityEvents) is a known open limitation. TRACEABILITY (added 2026-09-08): the question the instrumentation exists to answer is whether the turn can be RECONSTRUCTED — raw prompt only in dev/harness with opt-in, HASH in production, and the invariant that makes the hash worth anything is that the text sent is derived from named blocks WITHOUT cache (a cache between assembly and send lets telemetry and request diverge in silence). Two closing assertions: the offered tool list came from the real turn list, and a CANCELLED turn writes nothing. CONVENTION STABILITY: the GenAI semantic conventions LEFT the main OpenTelemetry repo — semconv v1.42.0 (2026-06-12) deprecated and moved all of gen_ai.*, v1.43.0 carries none, the content lives in open-telemetry/semantic-conventions-genai where NOTHING GenAI is Stable (all Development; only error.type/server.address/server.port are stable, and those are common attributes), while OpenTelemetryChatClient declares v1.37 — behind the split. Instrument anyway, but do not build an alert whose only identifier is a gen_ai.* name without a rename plan. Cost delegation is two-way: tariff, cost formula and budget ceiling live in ai-agents-cost-and-budget; span attributes stay here. The Gate 3 ruler for this property is evals/review-checklist.md.",
       "verifiedAgainst": "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/Observability/MorphOpenTelemetryExtensions.cs` — o guard de span duplicado, a regra de \"um nível, uma instrumentação\" e o default `EnableSensitiveData = false` são exatamente o que o kit compila, com os spans contados em `tests/Morph.AiKit.Tests/TelemetryTests.cs`. Nomes de símbolo, de span, de métrica e das duas `ActivitySource` foram **medidos por reflexão e por leitura dos literais das assemblies do pin** em 2026-09-08, e em 2026-09-09 **todos os treze nomes `gen_ai.*` desta página** foram remedidos, um a um, por **teste de exclusividade**: os quatro `SetTag` da seção *Enrichment* e os nove das seções de span, métrica e atributo de agente. **Os treze existem** — depois de uma correção: `gen_ai.response.finish_reason`, no **singular**, não existia, só aparecia como cabeça de `finish_reason`**s**, e sobreviveu a duas varreduras porque as duas usaram `includes` — e **`includes` de um prefixo não prova o literal autônomo**. Os treze estão tabelados, em **duas** tabelas com propósitos diferentes: a de *Enrichment* registra os **4** `SetTag` daquele bloco (mais os **cinco** nomes rejeitados: o `finish_reason` singular, `PromptTokens`, `CompletionTokens`, `prompt_tokens` e `completion_tokens`), e a de distribuição, na seção *Nomes de span, métricas e atributos — medidos*, registra os **13** por assembly. A conferência é reproduzível por `node scripts/api-probe/probe.mjs tags` sobre este arquivo. A **instabilidade da convenção** — o split do semconv **v1.42.0 (2026-06-12)**, que depreciou e moveu todo `gen_ai.*` para `open-telemetry/semantic-conventions-genai`, onde nada GenAI está `Stable`, contra a v1.37 que o `OpenTelemetryChatClient` declara implementar — é **verificação documental**, apurada em 2026-09-08.",
       "provedBy": [
         "templates/dotnet/ai-kit/src/Morph.AiKit/Observability/MorphOpenTelemetryExtensions.cs"
@@ -981,7 +981,7 @@
         "schema": "#schema-canonical",
         "providers": "#providers-first-class",
         "implementation": "#implementation-pattern",
-        "checklist": "#checklist-verifiable-by-morph-eval"
+        "checklist": "#checklist-verifiable-in-review"
       },
       "digest": "Single JSON file (model-registry.json v2) maps aliases to { provider, model, api, options, constraints }. Agents reference aliases, never model strings. EVERY alias declares `api`: `responses` (default when omitted) or `chat` (explicit opt-in); Ollama/OpenAI-compatible providers ignore the field but never travel the Responses path. `temperature` and `reasoningEffort` are mutually exclusive per alias, with the two origins labelled separately: the documented one (Chat Completions rejects tool calling with reasoning_effort != none from GPT-5.4) and the field-measured one (temperature on reasoning models — no primary source, so it is a per-alias constraint with mandatory provenance). .NET path: ChatOptions.Reasoning = new ReasoningOptions { Effort = ReasoningEffort.* } is CONFIRMED in M.E.AI 10.9.0; RawRepresentationFactory is the escape hatch for values the enum lacks. OPENAI001 still applies to the Responses types. No floating PackageReference ranges.",
       "verifiedAgainst": "Microsoft.Agents.AI 1.20.0 + Microsoft.Extensions.AI 10.9.0 + OpenAI 2.13.0 (ai-pin 2026-09-08); provado por `templates/dotnet/ai-kit/src/Morph.AiKit/Providers/ModelRegistry.cs` e `.../Providers/ModelAlias.cs` e `.../Agents/AgentApi.cs`. Nomes de tipo do `Microsoft.Extensions.AI` e do `OpenAI` medidos por reflexão sobre as assemblies do pin em 2026-09-08.",
@@ -1208,7 +1208,7 @@
         "eval": "#eval-e-unit",
         "captura": "#captura-do-que-foi-ao-provedor",
         "golden": "#golden-com-parcimônia",
-        "checklist": "#checklist-verifiable-by-morph-eval"
+        "checklist": "#checklist-verifiable-in-review"
       },
       "digest": "Only what is agent-specific — backend-dotnet-testing keeps xUnit, FakeTimeProvider and isolation. The single point where code touches a provider is an IChatClient, so everything follows from replacing it: a SCRIPTED and DUMB fake (a queue of hand-written responses, capture of messages/options/call count) that THROWS when the queue runs out — a silent empty response makes a test pass by accident. Two independent products converged on this shape; the kit compiles the third. Run the REAL function-invocation loop on top of the fake: tool choice, arguments, guard and ceiling are only observable through the loop. The seam keeps classes sealed (a one-operation interface, or an internal constructor taking alias -> IChatClient). ZERO real provider calls inside dotnet test, verified by a sweep of tests/ for API keys, environment reads and HTTP clients — and the standard records the price of leaving the real harness outside the suite: 11 scenarios that were never run end to end. Eval means DETERMINISTIC eval over the full real path with the model scripted; a hard gate only over deterministic properties. Raw prompt only in dev/harness with opt-in, hash in production. Golden proves FORM, not content (counter-example: 13.6 KB frozen to prove two lines of concatenation, deliberately deleted). A versioned prompt gets AT MOST ONE structural test (keys the consumer reads, absence of a revoked instruction); what the model answers is proven at runtime by evals-with-cache, never by Contains over the prompt source.",
       "verifiedAgainst": "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.",
@@ -2566,15 +2566,18 @@
         "POSTGRES_PORT",
         "COMPOSE_PROJECT_NAME",
         "port block",
+        "PG_PORT",
+        "portEnvNames",
         "local docker compose"
       ],
       "anchors": {
         "layout": "#port-layout-one-contract-everywhere",
+        "portNames": "#project-named-port-variables",
         "rules": "#core-rules",
         "enforcement": "#what-the-harness-enforces",
         "skeleton": "#minimal-compose-skeleton"
       },
-      "digest": "Every worktree runs its OWN compose stack (project morph-{feature}, own postgres, own volumes). Ports come from the worktree block: PORT +0, API_PORT +1 (ASPNETCORE_URLS on .NET), POSTGRES_PORT +2, REDIS_PORT +3 — publish via ${VAR:-default}:container, never a fixed host port, never container_name (not prefixed by the project → collides). Stable POSTGRES_DB, healthcheck on every service, DATABASE_URL with an in-network default, playwright.config reads PLAYWRIGHT_BASE_URL. A non-isolable compose fails the verify e2e node inside a worktree. finish tears down with volumes (--keep-volumes opts out). Cloud DB credentials go in e2e.auth.envFile, never in .morph/worktree.env.",
+      "digest": "Every worktree runs its OWN compose stack (project morph-{feature}, own postgres, own volumes). Ports come from the worktree block: PORT +0, API_PORT +1 (ASPNETCORE_URLS on .NET), POSTGRES_PORT +2, REDIS_PORT +3 — publish via ${VAR:-default}:container, never a fixed host port, never container_name (not prefixed by the project → collides). Stable POSTGRES_DB, healthcheck on every service, DATABASE_URL with an in-network default, playwright.config reads PLAYWRIGHT_BASE_URL. A non-isolable compose fails the verify e2e node inside a worktree. finish tears down with volumes (--keep-volumes opts out). Cloud DB credentials go in e2e.auth.envFile, never in .morph/worktree.env. A compose that reads a port by ANOTHER name (PG_PORT) is not fed by the block: declare it in config.json e2e.portEnvNames ({\"postgres\": \"PG_PORT\"}) and the harness exports it with the same value in worktree.env, the compose env and the hook.",
       "verifiedAgainst": "Docker Compose v2 + morph-spec 8.34 (dedicated stack per worktree).",
       "provedBy": []
     },
@@ -2851,6 +2854,47 @@
       "digest": "Default is NO comment: code explains itself through names, types and tests. Before commenting, rename, extract a function or named constant, encode the state in the type, or write a test; comment only what none of these can express: an invariant the type does not express, an order that matters, an external quirk (third-party API, library bug with its link), or the contract of a package published for consumers outside the repo. Never process history (task, UC, ADR, FR, Gate, evaluator, spec.md, mockup: commit message and decisions.md; in a test the link to the postcondition goes in the test NAME), never restate the code, no XML doc/JSDoc on application members that repeats the signature, no file headers, section banners, #region, commented-out code or loose TODOs, no claims about behavior (make them test assertions). One line is normal, ~3 is the ceiling; more than one comment line per ten code lines means the names are not doing the work. A heavily commented neighbour file is not a model. The comment-guard hook blocks an edit that ADDS process history, a banner/#region, a block over 3 lines or a doc-comment outside a published package; the verify validators node (code-budget) warns on added comments that cite process and on added comment density.",
       "verifiedAgainst": "C#, TypeScript e JavaScript (convenção de linguagem, sem pacote externo).",
       "provedBy": []
+    },
+    {
+      "id": "ai-agents-tool-adapters",
+      "name": "tool adapters",
+      "path": "ai-agents/tool-adapters.md",
+      "category": "ai-agents",
+      "subcategory": null,
+      "tags": [
+        "ai-agents",
+        "maf",
+        "tools",
+        "testing"
+      ],
+      "stacks": [
+        "dotnet"
+      ],
+      "aliases": [
+        "tool fina",
+        "adaptador de tool",
+        "Ops",
+        "Desfecho",
+        "Render",
+        "regra de negocio em tool",
+        "descricao da tool",
+        "golden de tool",
+        "refactor neutro",
+        "migracao de teste"
+      ],
+      "anchors": {
+        "fronteira": "#fronteira-com-os-outros-standards",
+        "problema": "#o-problema",
+        "padrao": "#o-padrão",
+        "exemplo": "#exemplo-c-completo",
+        "testes": "#os-testes-das-duas-camadas",
+        "migracao": "#migrar-uma-tool-que-já-tem-a-regra-no-adaptador",
+        "reais": "#exemplos-reais",
+        "regras": "#regras"
+      },
+      "digest": "A tool that carries business rule keeps apart three things that change for different reasons: the RULE (sealed class XOps(...), primary constructor, explicit AddScoped; never *Service, which MORPH.md bans as a layer between handler and data), the sentence the MODEL reads, and the EFFECT a human sees. Each Ops method returns a typed outcome (abstract record XDesfecho, one sealed record per case); the model-facing text (description, refusal, self-correction, success, the ToolUnavailable decision) lives in the adapter, in public static object Render(XDesfecho), while human text delivered by code (task body, note, ack) stays in Ops because it is an effect. Checkable by grep: Ops names no tool and instructs no model. The adapter (AIFunctionFactory.Create) only builds the typed request, calls Ops and returns Render: zero rule, not a line count, and a long dynamic description stays byte for byte. Two test layers: Ops tests assert outcome, calls and order on the fake, never text; contract tests assert Render's exact literal and .Description, with a golden of name, description and schema per real tenant. A neutral refactor is proven before any test moves: a proof commit with the old suite untouched and green (offline evals included), then the migration, with mutation run only against the new tests. \"Already covered\" needs proof assertion by assertion (11 of 22 such claims had lost one); the tests left at the origin must be identical to the base; mutation on the new tests found rules the old suite never protected. The C# blocks were compiled against the pin and the three xunit tests run.",
+      "verifiedAgainst": "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.",
+      "provedBy": []
     }
   ],
   "sharedAliases": {

package/framework/standards/ai-agents/agent-archetypes.md

@@ -132,7 +132,7 @@ não escolhe o histórico; escolher "chat com histórico" não escolhe as fases.
 
 ---
 
-## Checklist (verifiable by morph-eval)
+## Checklist (verifiable in review)
 
 - [ ] O arquétipo escolhido está **nomeado** no `decisions.md` da feature, com a pergunta de
       `## Como escolher` que o decidiu

package/framework/standards/ai-agents/agent-session.md

@@ -226,7 +226,7 @@ O histórico cresce a cada turno. Quando estoura o context window do modelo, as
 
 ---
 
-## Checklist (verifiable by morph-eval)
+## Checklist (verifiable in review)
 
 - [ ] A escolha da fonte de histórico foi feita pela tabela de critério — e está escrita em `decisions.md` quando não foi a conversa própria
 - [ ] O provider de histórico é registrado como **uma** instância compartilhada

package/framework/standards/ai-agents/agent-spec.md

@@ -165,7 +165,7 @@ avisando para não commitar não é um mecanismo — é uma esperança.
 
 ---
 
-## Checklist (verifiable by morph-eval)
+## Checklist (verifiable in review)
 
 - [ ] Existe exatamente **uma** `AgentSpec` por agente, e nenhum agente é construído inline
 - [ ] Nenhuma spec contém id de modelo — só `Alias`

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

@@ -192,7 +192,7 @@ if (batchDoc.TryGetProperty("error_file_id", out var errEl) && errEl.GetString()
 
 ---
 
-## Checklist (verifiable by morph-eval)
+## Checklist (verifiable in review)
 
 - [ ] Batch é usado somente para prompts independentes, sem usuário aguardando resposta
 - [ ] O poll de status roda em background job (Worker/Hangfire), não em request HTTP

package/framework/standards/ai-agents/context-providers.md

@@ -223,7 +223,7 @@ com `.UseAIContextProviders(...)` no `ChatClientBuilder` (`chatClient.AsBuilder(
 
 ---
 
-## Checklist (verifiable by morph-eval)
+## Checklist (verifiable in review)
 
 - [ ] O provider herda da classe base abstrata `AIContextProvider` (não implementa uma interface genérica)
 - [ ] `ProvideAIContextAsync` é read-only — sem writes a banco ou estado global

package/framework/standards/ai-agents/conversational-agent-with-phases.md

@@ -202,7 +202,7 @@ A composição legítima — quando ela é mesmo necessária — é assunto de
 
 ---
 
-## Checklist (verifiable by morph-eval)
+## Checklist (verifiable in review)
 
 - [ ] Existe **um** compositor de turno, puro e sem I/O, e nenhuma segunda montagem de prompt
 - [ ] O prompt é composto de blocos nomeados, e o texto enviado é derivado sem cache

package/framework/standards/ai-agents/cost-and-budget.md

@@ -225,7 +225,7 @@ mandado para lá. Nenhum dos dois duplica o outro.
 
 ---
 
-## Checklist (verifiable by morph-eval)
+## Checklist (verifiable in review)
 
 - [ ] A conta de custo existe em **um** lugar; nenhum agente a repete
 - [ ] A tarifa mora por alias no registry, e a **data** dela está registrada FORA do objeto `pricing` (comentário JSONC, campo próprio na allowlist, ou arquivo de procedência) — a allowlist do exemplar tem exatamente 3 chaves e recusa uma quarta

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

@@ -246,7 +246,7 @@ This framework deploys to VPS/Coolify by default and does not adopt Azure as a d
 
 ---
 
-## Checklist (verifiable by morph-eval)
+## Checklist (verifiable in review)
 
 - [ ] `ai-agents-workflows`' HITL or long-running criterion is documented in `decisions.md` before this standard is applied.
 - [ ] Every HITL wait point uses `RequestPort` + handles `RequestInfoEvent`.

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

@@ -186,7 +186,7 @@ primeira pergunta a fazer quando um guard "nunca reprova nada".
 
 ---
 
-## Checklist (verifiable by morph-eval)
+## Checklist (verifiable in review)
 
 - [ ] Toda regra com consequência real existe como condição em código, não apenas no prompt
 - [ ] O choke-point escolhido está nomeado no `decisions.md`, com o que ele pega

package/framework/standards/ai-agents/llm-runtime-defaults.md

@@ -197,7 +197,7 @@ explicando por quê.
 
 ---
 
-## Checklist (verifiable by morph-eval)
+## Checklist (verifiable in review)
 
 - [ ] Nenhum loop de retry escrito à mão em volta de uma chamada de LLM
 - [ ] Há timeout explícito (por spec de agente, como o exemplar do kit, ou por alias se a allowlist foi aberta), e ele **não** é o `CancellationToken` do turno

package/framework/standards/ai-agents/mcp-server.md

@@ -318,7 +318,7 @@ prefira o tipo de instância resolvido por DI a métodos estáticos com estado g
 
 ---
 
-## Checklist (verifiable by morph-eval)
+## Checklist (verifiable in review)
 
 - [ ] `ModelContextProtocol` e `Microsoft.Agents.AI` no `.csproj`; `ModelContextProtocol.AspNetCore` apenas se HTTP
 - [ ] Tools declaradas via `[McpServerToolType]` + `[McpServerTool]` (estáticas) ou `McpServerTool.Create(...)` (agente MAF / runtime)

package/framework/standards/ai-agents/mcp-tools.md

@@ -220,7 +220,7 @@ AIAgent agent = _modelRegistry.GetChatClient("text-default")
 
 ---
 
-## Checklist (verifiable by morph-eval)
+## Checklist (verifiable in review)
 
 - [ ] `ModelContextProtocol` presente no `.csproj` com versão exata (2.2.0 no pin) — sem faixa flutuante
 - [ ] `await using var mcpClient` — dispose correto do transporte

package/framework/standards/ai-agents/media-pipeline.md

@@ -303,7 +303,7 @@ mais caro que um modelo com o dobro da tarifa e 90 %.
 
 ---
 
-## Checklist (verifiable by morph-eval)
+## Checklist (verifiable in review)
 
 - [ ] Nenhum handler síncrono consegue nomear o tipo que produz bytes
 - [ ] Nenhum `await runner.RunAsync(...)` dentro de handler de turno — **o tipo não fecha esta

package/framework/standards/ai-agents/media-video.md

@@ -224,7 +224,7 @@ re-verificar diz qual página conferir. É falsificável em segundos, sem pesqui
 
 ---
 
-## Checklist (verifiable by morph-eval)
+## Checklist (verifiable in review)
 
 - [ ] Nenhum código novo aponta para um alias de §Deprecações
 - [ ] O id da operação/tarefa é **persistido antes** do primeiro polling

package/framework/standards/ai-agents/middleware-patterns.md

@@ -215,7 +215,7 @@ Precisa de middleware no agent?
 
 ---
 
-## Checklist (verifiable by morph-eval)
+## Checklist (verifiable in review)
 
 - [ ] Middleware registrado via `.AsBuilder().Use(...).Build()` — nunca depois de `Build()`
 - [ ] IChatClient middleware aplicado no `chatClient.AsBuilder()` antes de `.AsAIAgent()`

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

@@ -356,7 +356,7 @@ tem de cair **aqui**, no lugar que diz que ele morreu.
 
 ---
 
-## Checklist (verifiable by morph-eval)
+## Checklist (verifiable in review)
 
 - [ ] O alias escolhido **não** está na tabela de §Deprecações
 - [ ] A chamada passa por `IImageGenerator` (ou adaptador próprio), sem acoplar o handler ao SDK

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

@@ -145,7 +145,7 @@ builder.Services.AddSingleton<TranscriptionService>();
 
 ---
 
-## Checklist (verifiable by morph-eval)
+## Checklist (verifiable in review)
 
 - [ ] `AudioClient` injetado via DI — não instanciado inline
 - [ ] Áudio longo (>25MB) tratado com chunking antes de enviar ao provider

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

@@ -158,7 +158,7 @@ public class AudioController(TextToSpeechService tts) : ControllerBase
 
 ---
 
-## Checklist (verifiable by morph-eval)
+## Checklist (verifiable in review)
 
 - [ ] `AudioClient` injetado via DI — não instanciado inline
 - [ ] Cache implementado para textos invariantes (não gera o mesmo áudio duas vezes)

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

@@ -166,7 +166,7 @@ string desc3 = await agent.AnalyzeImageBytesAsync(data, "image/png",
 
 ---
 
-## Checklist (verifiable by morph-eval)
+## Checklist (verifiable in review)
 
 - [ ] Alias `"vision"` existe em `model-registry.json` e aponta para modelo com suporte a visão confirmado
 - [ ] `ChatMessage` usa `UriContent` para imagens por URL ou `DataContent` para bytes — nenhum encoding manual de base64 no código do agente

package/framework/standards/ai-agents/multi-agent-patterns.md

@@ -182,7 +182,7 @@ Tenho múltiplos agents — qual padrão usar?
 
 ---
 
-## Checklist (verifiable by morph-eval)
+## Checklist (verifiable in review)
 
 - [ ] Foi verificado em `decisions.md` que single agent não resolve?
 - [ ] O padrão escolhido é o mais simples que atende ao requisito? (Tool < Sequential imperativo < Workflow)

package/framework/standards/ai-agents/observability-patterns.md

@@ -298,7 +298,7 @@ auditável pela mesma via, são de `ai-agents-guardrails`.
 > requeridos — estão medidos na tabela **"Nomes de span, métricas e atributos — medidos"** acima, e
 > **não** são repetidos aqui: uma segunda lista dos mesmos nomes é a segunda verdade nascendo. A
 > régua de avaliação correspondente vive em
-> `.morph/framework/evals/proof-rubrics/observabilidade-genai.md`, e ela pergunta a **propriedade**
+> `.morph/framework/evals/review-checklist.md` ("Feature que chama LLM"), e ela pergunta a **propriedade**
 > desta seção (dá para reconstruir o turno?), não a tecnologia — porque uma régua binária "tem span?"
 > daria a mesma nota a quem tem só a mensagem da exceção e a quem tem hash por bloco de prompt com
 > teste de fidelidade.
@@ -327,7 +327,7 @@ Workflow para diagnosticar um incidente relatado ("o agente X respondeu errado/l
 
 ---
 
-## Checklist (verifiable by morph-eval)
+## Checklist (verifiable in review)
 
 - [ ] `AddSource` das **duas** fontes: `Experimental.Microsoft.Agents.AI` e `Experimental.Microsoft.Extensions.AI`
 - [ ] Nenhuma referência a `AgentOpenTelemetryConsts` ou `agent.WithOpenTelemetry()` (não existem no pin)
@@ -354,7 +354,7 @@ Workflow para diagnosticar um incidente relatado ("o agente X respondeu errado/l
 - `ai-agents-conversational-agent-with-phases` — o compositor de turno e a invariante "derivado sem cache" que torna o hash confiável
 - `ai-agents-testing-ai` — a metade de harness da rastreabilidade (captura do fake, prompt cru com opt-in)
 - `ai-agents-guardrails` — veredito ternário e escape registrado, auditáveis pela mesma telemetria
-- `.morph/framework/evals/proof-rubrics/observabilidade-genai.md` — a régua do Gate 3 para a propriedade desta seção
+- `.morph/framework/evals/review-checklist.md` — a régua do Gate 3 para a propriedade desta seção
 - `infrastructure-docker-coolify-deploy` — Serilog/JSON console log para o pipeline de agregação em produção
 - Reference implementation (compila e conta spans contra o pin): `templates/dotnet/ai-kit/src/Morph.AiKit/Observability/MorphOpenTelemetryExtensions.cs` + `tests/Morph.AiKit.Tests/TelemetryTests.cs`
 - [OpenTelemetry Semantic Conventions for GenAI](https://opentelemetry.io/docs/specs/semconv/gen-ai/)

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

@@ -211,7 +211,7 @@ Na **1.18** (2026-08-18) essa superfície foi renomeada. Nomes atuais, medidos p
 
 ---
 
-## Security Checklist (verifiable by morph-eval)
+## Security Checklist (verifiable in review)
 
 - [ ] API keys nunca em `appsettings.json` no repositório — bind de environment variables ou secret store
 - [ ] Variáveis de provider (`OpenAI__ApiKey`, `Google__ApiKey`, `Anthropic__ApiKey`) em env vars / Docker secrets
@@ -225,7 +225,7 @@ Na **1.18** (2026-08-18) essa superfície foi renomeada. Nomes atuais, medidos p
 
 ---
 
-## Production Checklist (verifiable by morph-eval)
+## Production Checklist (verifiable in review)
 
 - [ ] `Microsoft.Agents.AI` **1.20.0** (versão exata, do `ai-pin.json`) no `.csproj`; nenhum pacote SK de orquestração
 - [ ] Nenhum `PackageReference` de SDK de IA com faixa flutuante; pacote fora do pin com versão exata + data de apuração

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

@@ -344,7 +344,7 @@ rastreabilidade (hash em span, prompt cru só em harness) está em `ai-agents-ob
 
 ---
 
-## Checklist (verifiable by morph-eval)
+## Checklist (verifiable in review)
 
 - [ ] `agent_prompts` table exists with all required columns (`id`, `agent_key`, `version`, `content`, `is_active`, `created_at`)
 - [ ] Unique partial index `ix_agent_prompts_active` on `(agent_key) WHERE is_active` is present

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

@@ -265,7 +265,7 @@ When a task says "register the X agent" and the project has >1 model or >1 provi
 
 ---
 
-## Checklist (verifiable by morph-eval)
+## Checklist (verifiable in review)
 
 - [ ] Project has `config/model-registry.json` (or declared equivalent), `version` `2.0`.
 - [ ] Project has a `ModelRegistry` class registered as singleton in DI.

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

@@ -281,7 +281,7 @@ ALTER TABLE kb_embeddings ENABLE ROW LEVEL SECURITY;
 
 ---
 
-## Checklist (verifiable by morph-eval)
+## Checklist (verifiable in review)
 
 - [ ] EmbeddingService (concrete class) registered in DI; it injects IEmbeddingGenerator<string, Embedding<float>> for the project's chosen embedding model.
 - [ ] Embedding model declared in `model-registry.json` under the `embeddings` alias.

package/framework/standards/ai-agents/service-tier-flex.md

@@ -119,7 +119,7 @@ string responseText = result.Content[0].Text;
 
 ---
 
-## Checklist (verifiable by morph-eval)
+## Checklist (verifiable in review)
 
 - [ ] Tier flex usado somente em jobs assíncronos (Worker Service / Hangfire), nunca em handlers de request HTTP síncrono
 - [ ] `ServiceTier` usa o valor tipado (`ChatServiceTier.Flex` / `ResponseServiceTier.Flex`), nunca uma string

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

@@ -346,7 +346,7 @@ AIAgent instrumented = agent.AsBuilder()
 
 ---
 
-## 8. Checklist (verifiable by morph-eval)
+## 8. Checklist (verifiable in review)
 
 - [ ] `Microsoft.Agents.AI` package present in `.csproj`, com versão exata
 - [ ] No `Microsoft.SemanticKernel.*` orchestration references

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

@@ -254,7 +254,7 @@ public async Task<Result<ProposalDraft>> DraftValidatedAsync(string clientContex
 
 ---
 
-## Checklist (verifiable by morph-eval)
+## Checklist (verifiable in review)
 
 - [ ] Todo agente que alimenta outro sistema (front-end, banco, pipeline, outro agente) usa `RunAsync<T>` ou `ResponseFormat` — nenhum retorna `response.Text` para parsing downstream.
 - [ ] O tipo de saída é um `sealed record` ou `sealed class` decorado com `[Description("...")]`.

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

@@ -103,7 +103,7 @@ You may need to step outside the sweet spot when:
 
 ---
 
-## Checklist (verifiable by morph-eval)
+## Checklist (verifiable in review)
 
 - [ ] Was each agent designed as single-agent BEFORE reaching for multi-agent? (Check `decisions.md`.)
 - [ ] If a Workflow is used, is fan-in/out or HITL checkpointing genuinely present? Or could `foreach + LINQ` replace it?

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

@@ -201,7 +201,7 @@ mesmo padrão que este standard já contou como precedente ("treze arquivos, ~2.
 
 ---
 
-## Checklist (verifiable by morph-eval)
+## Checklist (verifiable in review)
 
 - [ ] Existe um fake de `IChatClient` roteirizado, com captura de mensagens, opções e contagem
 - [ ] O fake **lança** quando a fila acaba