@polymorphism-tech/morph-spec 8.33.0 → 8.35.0

package/framework/standards/ai-agents/evals-with-cache.md

@@ -0,0 +1,289 @@
+# Evals com cache — regressão de prompt e de modelo sem chave no CI
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 1 (on-keyword)
+> **Keywords:** eval, evals, response cache, cache de respostas, dataset de eval, regressão de prompt, troca de modelo, model swap, prompt regression, EvalFixture, OfflineChatClient, DiskBasedResponseCacheProvider, nó evals, --refresh-cache
+> **Read by Claude in:** implement (quando a feature muda prompt, troca modelo, ou o projeto vai declarar o nó `evals` no `verify`)
+
+**Verified against:** Microsoft.Extensions.AI.Evaluation 10.9.0 + `.Quality` + `.Reporting` (ai-pin 2026-09-08); provado por `templates/dotnet/ai-kit/src/Morph.AiKit/Evals/EvalFixture.cs`, que compila e roda no CI contra exatamente essas versões. A superfície de `DiskBasedReportingConfiguration`, `DiskBasedResponseCacheProvider`, `ReportingConfiguration` e dos avaliadores de `.Quality` foi **medida por reflexão sobre as assemblies `Microsoft.Extensions.AI.Evaluation*` 10.9.0** em 2026-09-08. Last-verified: 2026-09-08.
+
+---
+
+## Por que eval não é teste unitário
+
+Um teste unitário responde "esta função ainda faz o que fazia?". Um eval responde
+"este **produto** ainda responde o que respondia?" — e a diferença não é de grau.
+
+Trocar o prompt de sistema de um agente, ou trocar `gpt-4.1` por `gpt-5`, deixa **build
+verde e suíte unitária verde**. Nenhuma das duas coisas lê o comportamento do modelo; as
+duas leem o código em volta dele. O prompt e o modelo são a única parte do produto cujo
+comportamento não é coberto por nada do que já existe no gate.
+
+O precedente é de campo, e é caro: um repositório real manteve o script de eval **fora do
+CI** por decisão escrita (`ci.yml`, decisão registrada D-F5-2) porque *"variância de LLM
+real não pertence a pipeline determinístico"*. A decisão estava certa **para aquele
+desenho**. Um eval que chama o modelo a cada PR é lento, caro e flaky — e um eval flaky é
+um eval desligado, que verifica exatamente nada.
+
+Este standard descreve o desenho em que a decisão muda: **o eval lê de uma cache de
+respostas commitada**, e por isso é rápido, gratuito e determinístico.
+
+## O que se ganha, em uma frase
+
+Com a cache quente, a suíte de eval roda **sem credencial e sem rede**: a biblioteca
+embrulha o cliente interno num cliente de cache, e no *hit* o cliente interno nunca é
+invocado. Trocando o cliente interno por um que **recusa** (`OfflineChatClient`), o único
+caminho para a rede fica fechado — ou tudo resolve pela cache, ou a suíte fica vermelha
+nomeando o cenário que faltou.
+
+Isso é o que permite o nó de eval existir no CI de um repositório que **não tem uma única
+chave de LLM nos seus workflows**. Um mecanismo que exigisse uma chave seria adotado por
+ninguém.
+
+## Dataset por agente e por tenant
+
+```
+eval-datasets/
+├── triagem/acme/a-saudacao.json
+├── triagem/acme/b-escalonamento.json
+├── triagem/globex/a-saudacao.json
+└── orcamento/acme/a-resposta-estruturada.json
+```
+
+Os dois primeiros segmentos existem porque a pergunta útil quase nunca é "o produto
+regrediu?", e sim **"o agente X regrediu para o tenant Y?"**. Um dataset plano não responde
+isso sem convenção de nome, e convenção de nome é a forma mais frágil de estrutura.
+
+O caminho **é** a identidade do cenário: ele vira a chave do cenário na cache. Dois tenants
+têm cenários com o mesmo nome de propósito (`saudacao`, `handoff`), e uma chave que os
+confundisse devolveria a resposta de um tenant para o outro.
+
+> **Dado real de tenant é proibido no dataset.** A cache guarda **mensagens inteiras** e é
+> commitada: um segredo que entre no dataset entra no git, para sempre. O fixture só lê
+> cenário do diretório versionado — nunca de banco, nunca de variável de ambiente.
+
+## O que entra na chave de cache
+
+Medido no pacote 10.9.0, e o achado importa:
+
+| Entra na chave | Não entra |
+|---|---|
+| As mensagens e as `ChatOptions` | **O endpoint (`ProviderUri`)** |
+| `ProviderName` do `ChatClientMetadata` | |
+| `DefaultModelId` do `ChatClientMetadata` | |
+| A versão interna de formato de cache da biblioteca | |
+
+**A documentação afirma que o endpoint entra. Ele não entra.** A divergência entre o
+comentário XML da API e o comportamento medido é o que torna possível um cliente offline
+sem endpoint algum: ele não tem para onde ligar, e não precisa ter.
+
+A consequência prática: o cliente que **lê** a cache tem de replicar `ProviderName` e
+`DefaultModelId` do run que a **gravou**. Se divergirem, a chave computada na leitura é
+outra e **todo** cenário dá miss — uma cache quente indistinguível de uma cache vazia.
+
+## TTL explícito, sempre — e por quê
+
+`Defaults.DefaultTimeToLiveForCacheEntries` são **14 dias**, e a expiração é **destrutiva na
+leitura**: ao encontrar uma entrada vencida, o provedor **apaga o diretório da chave** antes
+de devolver `null`.
+
+Uma cache commitada com o default **se apaga sozinha ao ser lida**, duas semanas depois de
+gravada. O sintoma chega como CI verde por duas semanas e então miss em massa num dia em
+que ninguém mexeu em nada — com a árvore apagada no working tree, sujando o `git status`.
+
+Um TTL implícito aqui não é preguiça de configuração; é uma bomba-relógio. Declare-o, e
+declare-o **longo** (o kit recusa qualquer valor abaixo de um ano, com a razão na mensagem).
+
+## O carimbo, e o que ele responde de graça
+
+A função de hash que produz a chave **não promete ser estável entre versões da biblioteca**
+— a própria biblioteca carrega um número de versão de cache interno, justamente para
+invalidar tudo quando o formato muda. Ou seja: **subir o pin pode invalidar a árvore
+inteira**.
+
+Sem carimbo, isso chega como N misses inexplicáveis. Com carimbo, chega como uma frase:
+
+```
+eval-cache-stale-pin: Microsoft.Extensions.AI.Evaluation: gravada 10.9.0 vs pin 10.11.0
+```
+
+`.morph-eval-cache.json` fica na raiz da árvore e guarda o `pinnedAt` e as versões da
+família `Microsoft.Extensions.AI` sob as quais a árvore foi gravada. **Carimbo ausente tem
+motivo próprio**, distinto de carimbo divergente: as duas situações pedem ações diferentes
+— a primeira é "regrave", a segunda é "regrave **porque o pacote mudou**".
+
+## O que se commita, e o que não
+
+```
+<cachePath>/                          COMMITADO
+├── .morph-eval-cache.json            o carimbo
+└── cache/<cenário>/<iteração>/<chave-curta>/{entry.json, contents.data}
+
+<cachePath>/../eval-results/          NUNCA COMMITADO
+└── results/<execução>/<cenário>/<iteração>.json
+```
+
+Os resultados de execução carregam **latência medida por cronômetro, uso de tokens e o flag
+de cache hit**: são não-determinísticos por natureza, e commitá-los é diff garantido em toda
+rodada, sem sinal nenhum.
+
+Eles ficam fora da árvore commitada **por construção** — outra raiz de armazenamento — e
+não por um `.gitignore` dentro de um diretório commitado. Uma regra de ignore ali é uma
+regra que a próxima pessoa remove sem entender.
+
+### Por que a chave é CURTA, e por que isso não é detalhe
+
+O provedor de cache do kit (`ShortPathResponseCacheProvider`) nomeia o diretório da entrada
+com os **16 primeiros caracteres** do hash, e não com o hash inteiro. A chave completa é
+verificada dentro do `entry.json`: se dois cenários colidirem no prefixo, a leitura vira
+**miss** — nunca a resposta errada.
+
+O motivo é medido, e custou uma rodada inteira. Com o hash inteiro (96 caracteres em hex), o
+pior caminho relativo desta árvore dava **225**. Somado à raiz do repositório nesta máquina
+(73), o absoluto dava **298** — contra os 260 do `MAX_PATH` do Windows. O git **não recusou
+barulhento**: avisou `Filename too long` no stderr, commitou **1 de 9 arquivos**, e saiu com
+código 0.
+
+E o dano real não foi o arquivo faltando. Foi que o canário de CI — um `git diff --exit-code`
+sobre a árvore — passou a **reportar limpo**, não porque a árvore estivesse limpa, mas porque
+o git nunca enxergou aqueles arquivos. **Um guarda que não consegue observar o objeto reporta
+verde por construção.**
+
+Com a chave curta o pior caminho é **145**, e o teto que o cobra é 160 — a diferença é
+orçamento explícito, não sobra por acaso:
+
+| Parcela | Chars |
+|---|---|
+| `MAX_PATH` utilizável do Windows | 259 |
+| − `node_modules\@polymorphism-tech\morph-spec\` (estes arquivos viajam no tarball npm) | 43 |
+| − teto do caminho relativo | 160 |
+| = folga para a raiz do projeto de quem instala | **56** |
+
+Quem cobra os dois fatos — que cada arquivo é **endereçável pelo git** e que o pior caminho
+cabe no teto — é `test/framework/eval-cache-portability.test.js`, e ele recusa passar sobre
+um conjunto vazio: um canário que roda sobre zero arquivos é exatamente o canário cego que
+o defeito original tinha.
+
+### O payload é opaco: `-text` no `.gitattributes`
+
+A árvore de cache precisa de uma linha própria em `.gitattributes`:
+
+```
+<cachePath>/** -text
+```
+
+Sem ela, o `text=auto eol=lf` do repositório **normaliza** os `contents.data` — medido: avisos
+de CRLF→LF nos quatro payloads, e bytes que não sobreviveriam a um clone. `-text` (e não
+`binary`) porque ele preserva a fidelidade de byte **sem** perder o diff legível: quando o
+canário acusa, ele mostra o quê mudou, e não apenas que mudou.
+
+E o invariante que sustenta a commitabilidade é barato de cobrar: **um run offline não
+escreve um byte na árvore de cache.** Um canário que compara a árvore antes e depois (por
+conteúdo, não por data de modificação) morde no dia em que a biblioteca passar a tocar disco
+no caminho de hit — e não meses depois, quando alguém estranhar um diff que aparece sozinho.
+
+## Gate duro só em propriedade determinística
+
+| Papel | Quem | Reprova sozinho? |
+|---|---|---|
+| Asserção determinística | contém / não contém, chave de JSON, ferramenta escolhida, argumento de ferramenta, ausência de PII | **SIM** — é o gate |
+| Juízo de LLM | `RelevanceEvaluator`, `CompletenessEvaluator` | **NÃO** — número reportado |
+
+Um juízo de LLM que reprovasse sozinho reintroduziria exatamente o `FLAKY` que fez a decisão
+D-F5-2 manter o eval fora do CI. A métrica de juízo continua útil (dá tendência entre
+versões de prompt) sem precisar ser autoritativa — e, com a cache quente, ela é
+determinística também, porque a resposta do juiz está na cache.
+
+> **Dois dos quatro avaliadores de qualidade são `[Experimental("AIEVAL001")]` na 10.9.0**
+> (`TaskAdherenceEvaluator` e `ToolCallAccuracyEvaluator`). Sob `TreatWarningsAsErrors`,
+> usá-los exige suprimir um diagnóstico — uma decisão consciente, nunca um efeito colateral.
+> `.Safety` e `.NLP` ficam fora por outro motivo: ambos são preview, e `.Safety` exige
+> `TokenCredential` + Azure AI Foundry **na construção** — o oposto de "roda em CI sem
+> credencial".
+
+Um cenário **sem** asserção determinística não passa: ele não cobra nada. Deixá-lo verde é o
+mesmo defeito de um teste vazio, e aqui seria pior, porque o cenário apareceria na contagem
+como se tivesse verificado algo.
+
+## Quando o eval roda
+
+Declare-o como um nó a mais em `project.tests[]` — não como uma estrutura paralela:
+
+```json
+{
+  "project": {
+    "tests": [
+      { "id": "unit", "command": "dotnet test tests/App.Tests/App.Tests.csproj" },
+      {
+        "id": "evals",
+        "runner": "evals",
+        "command": "dotnet test tests/App.Tests/App.Tests.csproj --filter-trait Category=Eval",
+        "evals": { "cachePath": "tests/App.Tests/eval-cache", "envFile": ".env.evals" }
+      }
+    ],
+    "evals": { "watch": ["tenants/**", "product/**", "config/model-registry.json"] }
+  }
+}
+```
+
+| Quando | O que acontece |
+|---|---|
+| `verify {feature} {task}` (loop de task) | **pulado**, com motivo registrado — o relógio de uma task não paga uma suíte de eval |
+| `verify {feature}` (escopo de feature) | **roda**, offline, contra a cache commitada |
+| miss de cache sem credencial | **reprova** nomeando o cenário, o caminho, o comando de regravação e o arquivo de credencial |
+| `--refresh-cache` | regrava a árvore contra o provider real. **Nunca implícito**: é uma chamada paga |
+
+**Miss jamais vira `skip`.** A tentação é real ("não dá para avaliar, então não avalio") e
+recria o buraco que este harness já fechou duas vezes: gate verde sobre verificação que não
+aconteceu. E há razão positiva: em CI, com cache commitada, um miss significa **uma coisa
+só** — o prompt ou o modelo mudou e ninguém regravou. O miss é o veredito, não o obstáculo.
+
+## `evals.watch[]`: o que conta como "mudei o prompt"
+
+Os globs declaram, **para o projeto**, quais caminhos são prompt ou modelo. Eles são casados
+contra o que a feature mudou (diff contra a branch default **mais** arquivos novos ainda não
+rastreados) e alimentam a regra de Gate 3: tocou caminho declarado e não há eval verde
+carimbado no mesmo commit ⇒ o gate **pausa** e nomeia o caminho.
+
+Exclua `<cachePath>/**` e `<datasetPath>/**` dos globs. Sem isso, regravar a cache dispara a
+própria regra.
+
+O detector é por caminho, e as três formas conhecidas de escapar dele estão ditas em voz
+alta, porque um detector que se apresenta como completo e não é vale menos que nenhum:
+
+1. **eval trivialmente verde** — um cenário só, asserção vazia. É a mesma classe de contorno
+   de um teste vazio, e a resposta é a rubrica de prova, não uma segunda regra determinística
+   que também seria contornável;
+2. **prompt publicado direto no banco**, sem tocar arquivo;
+3. **modelo trocado por variável de ambiente** no provedor de deploy — invisível ao
+   repositório por construção.
+
+## Semeando a cache exemplar sem gastar dinheiro
+
+A cache commitada de um kit ou de um projeto novo é gravada rodando o fixture em modo
+`Refresh` contra um **fake roteirizado**, cujo `ChatClientMetadata` é configurado com o
+mesmo `providerName`/`defaultModelId` que o cliente offline vai replicar.
+
+Isto não é um atalho: o caminho de **escrita** exercitado é o da biblioteca, e a chave é
+computada pela mesma função que a leitura vai usar. A leitura offline lê exatamente o que
+aquela escrita produziu.
+
+**A lacuna residual, declarada:** isso não prova que uma cache gravada contra um provider
+real é legível offline. O que a mitiga é o fato medido acima — a chave depende de
+`ProviderName` e `DefaultModelId`, e não do endpoint, e ambos estão sob nosso controle.
+
+## Fronteira com `testing-ai`
+
+| Standard | Cobre |
+|---|---|
+| `testing-ai` | Fake roteirizado rodando o loop real do agente; prova ferramenta escolhida, argumentos e guard. **Sem rede, sem modelo** |
+| `evals-with-cache` (este) | Modelo **real** com cache em disco; dataset por tenant/agente; regressão de prompt e de modelo; o nó `evals` no `verify` |
+
+Em uma frase: `testing-ai` prova que **o código em volta do modelo** se comporta;
+`evals-with-cache` prova que **o modelo** ainda responde o que respondia.
+
+## Se precisar mapear o blast radius de um prompt
+
+`morph-spec graph explain <símbolo>` ajuda a achar quem lê um prompt ou um alias de modelo.
+**Sem grafo construído, caia para `grep -rn` e siga em frente** — a ausência do grafo nunca
+bloqueia este ciclo, e o fallback é a resposta correta, não um plano B envergonhado.

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

@@ -0,0 +1,222 @@
+# Guardrails — o que o código garante quando o prompt já falhou
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 1 (on-keyword)
+> **Keywords:** guardrail, guard de tool, regra proibida, validacao de pertinencia, fail-open guard, argumento nao confiavel, choke-point, veredito ternario
+> **Read by Claude in:** implement (ao escrever regra de negócio que o modelo poderia violar) e review (ao avaliar o que garante o comportamento)
+
+**Verified against:** 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. Last-verified: 2026-09-08.
+
+---
+
+## Regra proibida vira código
+
+**Instrução que já falhou ao vivo não se reforça escrevendo-a de novo em maiúsculas.**
+
+Quando uma regra tem consequência real — não falar de um assunto, não prometer um prazo, não citar
+um valor — ela sai do prompt e vira uma condição em C#. O prompt continua existindo para *orientar*;
+o código existe para *garantir*. São papéis diferentes, e confundi-los é como se descobre em
+produção que "o modelo geralmente obedece".
+
+Três formas medidas em campo, em ordem crescente de força:
+
+| Forma | Onde acontece | O que garante |
+|---|---|---|
+| **Gatilho literal avaliado antes do turno** | No compositor, sobre o texto de entrada | O assunto proibido nunca chega ao modelo com as tools que o executariam |
+| **Veredito calculado em .NET antes do turno e reescrito depois sobre a resposta** | Antes e depois da chamada | O número que o produto publica é o número que o backend calculou, não o que o modelo escreveu |
+| **Dado resolvido e pontuado em .NET, com o agente apenas copiando** | Fora do modelo | O modelo não tem oportunidade de errar a conta |
+
+**O motivo empírico está escrito no próprio código de campo**, e é a frase mais útil desta seção:
+*"o modelo obedece bem a 'uma entrada por elemento desta lista', mas erra feio quando precisa julgar
+sozinho quais blocos têm dado"* — com a medição ao lado: uma saída esperada de dez itens saía com
+dois.
+
+A leitura correta disso não é "o modelo é ruim". É: **o modelo é bom em transformação enumerada e
+ruim em julgamento de suficiência.** Dê-lhe a lista; faça o julgamento você.
+
+---
+
+## Onde fica o choke-point
+
+Três lugares legítimos, e cada um pega uma classe diferente de problema. Escolher o errado é o que
+faz um guard parecer instalado sem estar.
+
+**(a) Antes do turno, no compositor.** Pega o que não deve nem ser oferecido: a fase errada, a tool
+que este tenant não tem, o assunto proibido. É o mais barato — o modelo nem é chamado — e o único
+que evita gastar dinheiro com uma chamada que já nasceu errada.
+
+**(b) No middleware de invocação de função.** Pega o que o modelo pediu e não deveria ter pedido, e
+decide **o que volta ao modelo**. Duas exigências de forma:
+
+- **Vocabulário fechado de desfecho.** `ok` · `error` · `invalid_args` · `limit` · `unavailable`.
+  Fechado porque a alternativa — devolver a mensagem da exceção — dá ao modelo texto livre para
+  interpretar, e o modelo interpreta.
+- **Argumento obrigatório ausente é barrado sem executar a tool**, lendo `required` do próprio
+  schema JSON da função. Não se escreve a lista de obrigatórios num segundo lugar: ela já existe, e
+  a segunda cópia é a que diverge.
+
+**(c) Depois do run, como backstop.** É o único caminho em que o **código** invoca a implementação
+da tool diretamente, quando a resposta indica que algo obrigatório não foi feito. Serve como rede,
+nunca como mecanismo principal: um guard que só existe em (c) deixa o modelo decidir e depois
+conserta, pagando as duas coisas.
+
+O **mecanismo** de middleware — os três níveis, o registro no builder, a ordem — é de
+`ai-agents-middleware-patterns`. Este standard usa esse mecanismo e não o repete.
+
+---
+
+## Argumento de tool é input não confiável
+
+**Argumento vindo do modelo é entrada de usuário, com a agravante de ser gerada por algo que não
+tem intenção.**
+
+A regra: **identificadores e valores com efeito vêm da closure do turno, nunca do modelo.** A tool é
+construída já sabendo em qual conversa, em qual tenant e para qual registro ela opera; o modelo só
+fornece o que é genuinamente decisão dele.
+
+Os dois lados existem no acervo, e vale ver os dois:
+
+- **Padrão:** as tools de um produto são construídas sobre closures, com a regra escrita no código —
+  *"o modelo nunca fornece o identificador da conta, o identificador do contato nem valores
+  monetários"*.
+- **Padrão, no outro projeto:** o filtro de tenant da busca vetorial *"sempre vem do caller, nunca
+  do LLM"*.
+
+O caso que essa regra impede é direto: uma tool que aceita o identificador do registro como
+argumento é uma tool que, com o prompt certo na conversa errada, opera sobre o registro de outra
+pessoa. Não é um risco hipotético de segurança — é um bug de correção que aparece como suporte.
+
+Corolário: **valide o que sobra.** O que o modelo legitimamente decide (um texto, uma categoria, um
+valor dentro de uma faixa) ainda passa pelo schema e pelas regras de domínio, como qualquer entrada.
+
+---
+
+## Pertinência, não presença
+
+Esta é a seção difícil, e a que separa um guard de um `!= null`.
+
+O guard fraco pergunta: *o campo veio preenchido?*
+O guard forte pergunta: **o que veio se sustenta?**
+
+Três formas medidas, em ordem crescente de custo e de força:
+
+**(1) Rubrica determinística que soma 100.** As bandas espelham o que o prompt pediu, há uma
+whitelist explícita de "sem dados" (para que ausência legítima não seja punida como erro), e — o
+detalhe que faz a diferença — **os pontos que o backend já calculou são conferidos por igualdade**,
+não por plausibilidade. O validador **acumula todos os erros** em vez de parar no primeiro, e
+classifica o resultado em **incompleto × inválido**, que são coisas diferentes: o primeiro pede mais
+dado, o segundo pede rejeição. Referência de campo: o maior arquivo da camada de agentes daquele
+projeto, com 343 linhas, é justamente esse validador.
+
+**(2) Trava anti-alucinação por proveniência.** A afirmação do modelo só sobrevive se houver
+**rastro de origem**: um "encontrei" só permanece verdadeiro se o identificador correspondente
+estiver no sink de captura — isto é, se alguma tool de fato o raspou. Sem rastro, o resultado é
+**rebaixado** para "não encontrado", **preservando o texto de raciocínio original para auditoria**.
+Preservar é parte do padrão: apagar o raciocínio destrói a única pista de por que o modelo
+alucinou.
+
+**(3) Corte de confiança, com o caso real que o justifica.** O modelo casou um perfil apenas pelo
+nome e devolveu confiança 85, usando **a ausência de concorrentes como evidência a favor** — um
+raciocínio que soa razoável e é inválido. O remédio foi um mínimo de confiança **por rede**, não um
+mínimo global: a mesma pontuação significa coisas diferentes em fontes diferentes.
+
+O que as três têm em comum: **elas comparam com algo que não veio do modelo** — uma conta do
+backend, um rastro de execução, um limiar calibrado por fonte. Um guard que só olha para a resposta
+do modelo está pedindo ao modelo que se avalie.
+
+---
+
+## Quando o guard não consegue decidir
+
+A seção que o campo obriga, porque é o caso que mais acontece e o menos escrito.
+
+**O acervo responde fail-open, sempre.** Configuração ausente resolve para "pode"; configuração
+ilegível resolve para "pode"; os caminhos auxiliares (persona, sumarização, análise de memória, base
+de conhecimento, multimodal) devolvem vazio ou nulo em qualquer falha, e o turno segue.
+
+**Este standard ratifica o fail-open — com uma condição dura: o escape é registrado, nunca
+silencioso.**
+
+Ratifica porque a alternativa é pior no caso concreto: um guard que fecha quando não sabe derruba a
+conversa por causa de uma configuração ausente, e o custo de um falso bloqueio numa conversa ao vivo
+é maior que o de uma permissão a mais que alguém vai auditar.
+
+A condição é dura porque sem ela o fail-open é indistinguível de um bug.
+
+**Precedente que mostra a forma certa:** um guard **deliberadamente permeável** — rejeita a primeira
+tentativa, a segunda passa — **com o escape instrumentado**, num contador dedicado. A permeabilidade
+foi uma decisão de produto; a instrumentação é o que a torna revisável. *Guard permeável e medido é
+engenharia; guard permeável e mudo é bug.*
+
+**O anti-padrão, com número do campo:** **81 de 83 blocos `catch (Exception ex)` sem leitura do
+`ex`**, no mesmo projeto. Isso é fail-open sem instrumentação em escala — e está registrado como
+dívida pelo próprio time, o que significa que nem eles conseguem responder o que está sendo
+engolido.
+
+### Veredito ternário
+
+O resultado de um guard é `pass` / `reject` / `not_evaluated`, com **`reject` vencendo `pass` na
+mesma execução**.
+
+Um booleano perde exatamente a informação que o fail-open produz: *não deu para avaliar*. Com
+booleano, "não avaliado" vira "aprovado", e a métrica de aprovação passa a incluir tudo o que o
+guard não conseguiu olhar — que é a métrica errada com a aparência da certa.
+
+`not_evaluated` também é o que permite responder "quantas vezes este guard sequer rodou?", que é a
+primeira pergunta a fazer quando um guard "nunca reprova nada".
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Por quê é problema | Solução |
+|---|---|---|
+| Regra crítica reforçada em maiúsculas no prompt | O modelo geralmente obedece; "geralmente" não é garantia | Vira condição em código |
+| Pedir ao modelo que julgue quais blocos têm dado | Medido: dez itens esperados, dois entregues | Enumere você; peça transformação, não julgamento |
+| Guard só depois do run | Paga a chamada errada e depois conserta | Choke-point antes do turno, quando possível |
+| Devolver a mensagem da exceção ao modelo | Texto livre que o modelo interpreta | Vocabulário fechado de desfecho |
+| Lista de argumentos obrigatórios escrita num segundo lugar | A segunda cópia diverge do schema | Leia `required` do próprio schema da função |
+| Identificador ou valor vindo do modelo | Com o prompt certo, opera no registro de outra pessoa | Closure do turno |
+| Guard que checa presença (`!= null`) | Aprova qualquer coisa preenchida, inclusive alucinação | Compare com algo que não veio do modelo |
+| Validador que para no primeiro erro | Uma correção por rodada; o custo vira o número de rodadas | Acumule todos, e separe incompleto de inválido |
+| Rebaixar uma alucinação apagando o raciocínio | Destrói a única pista de por que aconteceu | Rebaixe preservando o raciocínio para auditoria |
+| Limiar de confiança global | A mesma pontuação significa coisas diferentes por fonte | Limiar por fonte |
+| Fail-open silencioso | Indistinguível de bug; 81 de 83 `catch` sem leitura | Fail-open **registrado** |
+| Veredito booleano | "Não avaliado" vira "aprovado", e a métrica mente | `pass` / `reject` / `not_evaluated` |
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] 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
+- [ ] O middleware de tool devolve **vocabulário fechado** de desfecho
+- [ ] Argumento obrigatório ausente é barrado **sem** executar a tool, lendo o schema da própria função
+- [ ] Nenhum identificador com efeito vem do modelo — todos vêm da closure do turno
+- [ ] Ao menos um guard compara a saída com algo que **não** veio do modelo
+- [ ] Validador acumula erros e distingue incompleto de inválido
+- [ ] Todo caminho fail-open **registra** o escape num contador ou span
+- [ ] O veredito é ternário, e `reject` vence `pass` na mesma execução
+- [ ] Existe forma de responder "quantas vezes este guard rodou, e quantas ele não conseguiu avaliar"
+
+---
+
+## References
+
+- `ai-agents-middleware-patterns` — **dono do mecanismo** de middleware de invocação de função
+  (os três níveis, o registro, a ordem). Este standard o usa e não o repete
+- `ai-agents-conversational-agent-with-phases` — o choke-point (a) na prática: compositor,
+  allow-list por fase e teto de tool calls
+- `ai-agents-agent-spec` — a spec do agente, onde as tools do turno são declaradas
+- `ai-agents-structured-output` — o schema cuja seção `required` o guard lê
+- `ai-agents-observability-patterns` — onde o escape registrado vira span e métrica
+- `ai-agents-production` — o panorama que hoje cita guardrails como um item de checklist
+
+> **Lacuna declarada.** O par compilável deste standard seria um guard de exemplo em
+> `templates/dotnet/ai-kit/src/Morph.AiKit/Middleware/`, com o teste que o vê barrar um argumento
+> obrigatório ausente **sem** executar a tool. **Ele ainda não existe** no ai-kit. Por isso o
+> cabeçalho declara verificação documental e não carimba `provado por`.
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/guardrails.md v1.0 (2026-09-08)*